What's inside

import type {  AnyUnit,  EmptyPhases,  EmptyShape,  MergePhases,  RuntimeUnit,  ServiceRecord,  UnitCloseFailure,  UnitOpenFailure,  UnitPhaseFailures,  UnitPhases,  UnitRole,  UnitSourceGuard,  UnitWiring,} from './unit-contract.js';type NeedsError<TAvail extends ServiceRecord, TNeeds extends ServiceRecord> = {  readonly 'DOT: this unit needs services that nothing before it provides. Mount their providers earlier (.infra → .features → .entrypoints)': {    readonly missing: MissingKeys<TAvail, TNeeds>;    readonly mismatched: MismatchedKeys<TAvail, TNeeds>;  };};

type CollisionError<TAvail, TProvides> = {  readonly 'DOT: this unit provides a key that an earlier unit already provides. Give one of them a new key with rename()': keyof TAvail &    keyof TProvides;};

  .needs({    db: database.provides.db, // typed from the provider    cache: cache.provides.kv.lazy, // a Lazy<T>, even if the provider is eager  })

import { defineFeature, entrypointOnly } from '@arki/dot/feature';import { database } from '../../infra/db';import { cache } from '../../infra/kv';import { emailClient } from '../../infra/mail/client';  .needs({    db: entrypointOnly(database.provides.db),    kv: entrypointOnly(cache.provides.kv),    // The app's outbound email client; a test fakes the plugin.    mailer: emailClient.provides.emailClient,  })

 * Stable error codes for every failure the kernel throws, `ARKI_DOT_E001`.. * Codes are never renumbered and never reused (E009 and E010 are retired). * E001-E021 and E033 are lifecycle failures; E022-E031 are feature-composition * failures (see `FEATURE_ERROR_CODES`); E032 is non-JSON manifest data. */export const DotLifecycleErrorCode = {

at `configure()`:- `ARKI_DOT_E020` — a provider is mounted after its consumer. The fix

- Previously booted units dispose in reverse declaration order.- App transitions to `failed`; no failed provider publishes a service.- The original refusal is returned when cleanup succeeds; unknown throws become

| `dot explain` | Imports the app file and runs `configure`. Never boots.                                    || `dot doctor`  | Boots the app (`boot` hooks run, migrations apply), then disposes it. Never calls `start`. |

import { tanstackStart } from '@arki/tanstack-start/dot';import { gateway } from './entrypoints/gateway';import { authn } from './infra/auth';  .entrypoints(    hostClock,    tanstackStart({      needs: { rpc: gateway.provides.rpc, auth: authn.provides.auth, scheduler },      session: ({ auth }, request) => auth.principal(request.headers),      rpc: ({ rpc }, request) => rpc.client(request.headers),

        for (const event of recorded) {          for (const projection of projections) {            if (projection.types.has(event.type) && projection.entities.some(e => e.kind === entity.kind)) {              await projection.run(sp, event);            }

import { CommandConflict, CommandNotFound, initJournal, need } from '@arki/journal';    write(order, input.orderId, row => {      if (!row) return CommandNotFound({ detail: 'Order not found' });      if (row.status !== 'placed') return CommandConflict({ detail: `Order is already ${row.status}` });      return [OrderPaid({ amount: input.amount })]; // [] means: write nothing    }),);

  .create(OrderPlaced, e => ({ customerId: e.data.customerId, total: e.data.total, status: 'placed' }))  .on(OrderPaid, () => ({ status: 'paid' })) // a patch: only the columns that change  .on(OrderCancelled, () => null); // null deletes the row; the events stay

import { idempotent } from '@arki/http/idempotency';import { responseCache } from '@arki/journal/http';idempotent({ cache: responseCache(db, tables), scope, routes: ['POST /orders'], ttl: 86_400_000 });

import { and, eq, sql } from 'drizzle-orm';          sql`select pg_notify(${deps.wakeChannel}, ${JSON.stringify({ from: Math.min(...seqs), to: Math.max(...seqs) })})`,

A workflow is a list of steps that runs to the end even when the process dies. Each step runs as a job in `journal_jobs`. When a step finishes, its result is saved (a checkpoint) and the next step is scheduled, in one transaction. A run can wait for a signal from outside, or sleep, for hours or days. When it cannot finish, it undoes the steps it did, newest first (compensation). The run is a journal entity (`workflow.run`), so every move is an event in `journal_events`.

        startOn: {          entity: refund,          event: refundsJournal.events.RefundApproved,          id: e => refundRunId(e.entityId),          input: e => ({ refundId: e.entityId }),        },

      .waitFor('settled', {        signal: 'stripe.refund.settled',        schema: settledSchema,        timeout: '3d',        // No signal in 3 days: `record` asks Stripe        onTimeout: 'continue',

`journal.forget(db, entity, id)` rewrites every stored event of that entity that has an erased form to it, sets `erased_at` on those rows, and then repairs the row from the rewritten log, so the row and its history agree. All in one transaction. An erased form the schema rejects is `BAD_DEFINITION` and nothing changes. A history replay cannot rebuild, such as a legacy row that was never adopted, is `NO_HISTORY` and nothing changes: adopt it first. Running it twice is safe; the first erased time is kept. It returns `{ erased, row }`.

 * The entrypoint, for `.entrypoints()`: one worker between `start` and `stop`, for the * journal that `journal(...)` published. Each effect and tap of a feature gets the * services of that feature. A process that serves no worker still writes: its jobs * wait for a process that does. With `jobs`, the worker also runs queue rows * (`@arki/queue/outbox`) through the runner the source builds at boot. */

Commit `.env.<environment>` files with their secrets encrypted. The format is dotenvx 2.x, so the `dotenvx` CLI reads the same files. Each file holds a public key, so anyone can add a value. Only a holder of the private key can read one. The private key lives in `DOTENV_PRIVATE_KEY_<ENV>` (for `.env.production`: `DOTENV_PRIVATE_KEY_PRODUCTION`) or in the gitignored `.env.keys` file.

import { buildEngine, route, routes } from '@arki/http';const engine = buildEngine([routes().bind(getOrder, ({ params }) => ({ id: params.id, total: 12 }))]);const response = await engine.fetch(new Request('http://localhost/orders/ord_1'));

- **Exact.** Amounts are whole numbers of units: `19.99 EUR` is `1999` units at 2 decimals. Nothing rounds unless you pass a rounding mode.

import { z } from 'zod';import { defineFailure, isFailure } from '@arki/failure';const EmailTaken = defineFailure('user.email_taken', {  status: 409,  data: z.object({ email: z.string() }),  message: 'email {email} is taken',});

`signUp` returns `{ email } | Failure<'user.email_taken', { email: string }>`. Nobody wrote that type. The compiler infers it, and `result.email` is a type error until `isFailure` has run.

- **Caught when ignored.** The `must-use` lint rule reports a call whose failure is thrown away. `no-blind-accept` reports `accept(r)` of a failure not checked by kind.

Typed command-line programs from one `defineCommand({...})`. The input schema drives the flags, their coercion and their help. A run writes a JSON envelope when stdout is a pipe and text on a terminal. Exit codes are stable. Help and `--version` never run a command, and import at most one lazy level of the tree.