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`. |

DOT is OTel-first. Traces, metrics, and logs come out of the kernelwithout you wiring anything — you wire the _exporter_. Without an OTel SDK, tracing and metrics safely use the API’s no-op implementations.

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 });

An effect runs after the commit, at least once, from a row in `journal_jobs`. A handler gets the event and a context: `(e, { jobId, signal, db, run })`.

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

`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. */

- Two runtime entry points (`node-postgres` pool by default, Bun-native SQL via the `bun` export condition, embedded PGlite via `./runtime-local`).

Key-value store abstraction with pluggable adapters for ARKI. Wraps [Keyv](https://keyv.org/) for general key-value access and [`rate-limiter-flexible`](https://github.com/animir/node-rate-limiter-flexible) for Redis-backed rate limiting. Provides automatic TLS handling (via `rediss://` URLs), Upstash support, and a graceful in-memory fallback when Redis is unreachable.

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.

Type-safe environment variables for ARKI. `defineEnv()` wraps [`@t3-oss/env-core`](https://env.t3.gg/). It validates on the first read and returns a typed object. Any [Standard Schema](https://standardschema.dev) works: Zod, Valibot, ArkType or a hand-written `~standard` object.

Typed HTTP for ARKI — route contracts as data, handlers validated by anyStandard Schema (zod, valibot, arktype, your own),request-scope derivers, SSE streaming, and deterministic OpenAPIgeneration. Ships a DOT adapter (`@arki/http/dot`) whose `http()` entrypoint unit

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'));

React component library for ARKI apps: Base UI primitives styled with Tailwind v4 semantic tokens. Forms, overlays, navigation, data display and charts. One import per component.

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

- **Safe types.** `Money<'EUR'>` cannot be added to `Money<'USD'>`. The compiler stops it, and the runtime throws `CurrencyMismatchError` too.

Payments for ARKI apps: a Stripe provider, plans, customers, subscriptions, payments, refunds, dunning and tax. It ships Drizzle table factories, repositories, services and [`@arki/journal`](https://www.npmjs.com/package/@arki/journal) commands. Routers stay in each consuming app, so the app owns its RPC context and its authorization policy.

Zero-dependency structured logging for every JavaScript runtime. Libraries log; apps configure. Message templates keep their values as fields, channels are set in one config, and records map onto the OpenTelemetry log data model. Importing it does nothing: no env read, no output, no listener.

Date and time math on [Temporal](https://tc39.es/proposal-temporal/) values with a small, explicit API. Calendar dates, instants, zoned date-times, durations, interval algebra, business days, formatting and relative text. Values are immutable, one arithmetic policy applies everywhere, and there is no hidden "now" and no hidden zone.