@ultimat3/action 11.2.0 → 12.0.0

package/CLAUDE.md

@@ -34,7 +34,10 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 | `deprecation.ts` | `Deprecation` + the RFC 9745/8594 render + the `deprecated_calls_total` counter |
 | `policy-gate.ts` | **the only** runtime edge to `@ultimat3/policy` (`errors.ts` takes `SurfaceDenial` as a type, which erases) |
 | `cache-gate.ts` | the post-commit bust — **the only** file that calls `invalidateTags` |
-| `audit.ts` | the audit seam: `AuditRecord`, `AuditSink`, the memory sink, the installed-sink store |
+| `audit.ts` | the audit seam: `AuditRecord`, `AuditSink`, the installed-sink store |
+| `audit-memory.ts` | the process default: a bounded ring that DROPS, and counts what it dropped |
+| `audit-postgres.ts` | the DURABLE sink — one append-only `x_audit` table, one insert per record |
+| `audit-input.ts` | what may be written DOWN: an `input` redacted through core's table and made JSON-representable on every path |
 | `audit-gate.ts` | **the only** file that calls a sink, and where the two failure policies live |
 | `type-pins.ts` | compile-time assertions `tsc` checks — what the erased view projects, and why `client()` is not part of it |
 | `naming.ts`, `validate.ts`, `json-schema.ts`, `stable.ts` | pure helpers. `stable.ts` is the DOCUMENT serializer plus a re-export of core's `isJsonObject` — the hash form is `@ultimat3/core`'s `canonicalJson`/`fingerprint` |
@@ -339,10 +342,19 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   around its own handler could ever see one. What reaches the sink is what `invoke` already holds
   (`at` from `ctx.now()`, the name, the mutator brand, the surface, the whole `ctx`, the parsed
   input, the namespaced idempotency key, `replayed`, the outcome, the failure code). What does
-  **not** ship, ever: an audit entity, a schema, a retention policy, a storage backend, a hash
-  chain, a subject index, or an opinion on what "who" means under impersonation — four apps model
-  those four ways, so by axiom 8's own test they are business convention and shipping one makes
-  three of them wrong. `result` is absent for the same reason and one more: a handler's return is
+  **not** ship, ever: an audit entity, a retention policy, a hash chain, a subject index, or an
+  opinion on what "who" means under impersonation — four apps model those four ways, so by axiom
+  8's own test they are business convention and shipping one makes three of them wrong.
+  **"a storage backend" was on that list until 2026-08-24 and is off it**, because the list was
+  answering a different question than it appeared to. What four apps model four ways is the ROW —
+  which of their own facts it carries, how long they keep it, whether it chains. Where the record
+  the FRAMEWORK already defines is put is not one of those: `x_audit`'s columns are the fields of
+  `AuditRecord` and nothing else, which is the same relationship `idempotency-postgres.ts` has to
+  `IdempotencyRecord` and `@ultimat3/http`'s `postgresRateLimitStore` to its `Bucket`. Leaving it
+  off meant the only sink that shipped was a ring that drops, so the shortest edit clearing
+  `X_AUDIT_SINK_MISSING` was `setAuditSink(memoryAuditSink())` — compliant in dev, silently
+  amnesiac in production, which `docs/idea/20-large-app-readiness.md` scores as **Ship**. An app
+  that wants columns of its own still writes its own sink; the seam is one method. `result` is absent for the same reason and one more: a handler's return is
   reachable from the handler itself, so shipping it would be this package deciding a row carries
   an after-image, which is `@ultimat3/admin`'s `diff` convention arriving one tier down.
 - **The audit vocabulary is `@ultimat3/admin`'s, shared by name and not by import.** `AuditOutcome`
@@ -353,6 +365,47 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   Unifying them means lifting the vocabulary into `@ultimat3/core` — the only tier both reach —
   and rebuilding `admin/audit.ts` on this seam. Not done here: `admin` is a shipped public API
   and its `AuditEntry` is a different shape.
+- **The memory sink DROPS, and both halves of that sentence are enforced.** It was a plain array
+  with a `push` — the one memory implementation in the framework with no cap, beside five that
+  have one (`memoryRateLimitStore`, `MemoryIdempotencyStore`, `createLimiter`,
+  `createTotpReplayGuard`, `createMemoryEventBus`) — and a record pins a whole `Ctx`, so at 50
+  audited writes a second it is 4.3M immortal records a day and the pod OOMs holding the trail it
+  was retaining. It is now a ring at `DEFAULT_MAX_AUDIT_RECORDS`, evicting the OLDEST (the
+  direction `createMemoryEventBus` evicts in: refusing new writes would answer "nothing has
+  happened since" for a process that has been serving all day). `dropped` is what makes "it drops"
+  checkable in a running process instead of a sentence in a header — a non-zero count on a real
+  deployment is the sink saying it is the wrong one. A `maxRecords` of `0`, negative or `NaN`
+  falls back to the default: there is no spelling of "no bound", because that spelling was the bug.
+- **What a DURABLE sink may write down is decided in `audit-input.ts`, and it is two rules.**
+  A record's `input` is the PARSED input, which is exactly where a password, a bearer token or a
+  card number lives, so `postgresAuditSink` redacts it through `@ultimat3/core`'s `isRedactedKey`
+  — the SAME table `defineEnv({ secret: true })` extends, never a copy of the list, because a copy
+  is how a value that is `[redacted]` in a log line becomes plaintext in a table. `isSecret`
+  redacts by VALUE beside it, for a credential travelling under a harmless name. The second rule
+  is that the answer is always JSON-representable: a `bigint`, a `NaN`, a function and a cycle all
+  become a NAMED marker rather than a throw, because `auditSettled` turns a sink throw into a
+  failed invocation for a handler that has already committed — and because `JSON.stringify` over a
+  cycle takes ~4.6s in Bun 1.4 before it raises, so leaving the detection to the serializer stalls
+  the audited path either way. `toJSON` is never called: it is app code in the frame that owes the
+  caller a record.
+- **The `Ctx` is never walked, and never will be.** `createContext` spreads every installed
+  service ONTO the context object and an HTTP surface's value is a `RequestContext` carrying the
+  request's own `Authorization` and `Cookie`, so a projection that iterated it would write an
+  app's database clients and its caller's credentials into an audit table. `postgresAuditSink`
+  reads an allow-list of framework-owned fields (`requestId`, `traceId`, `locale`, `tz`,
+  `buildId`, `role`, and the actor's `id`/`kind`/`orgId`/`onBehalfOf`) and nothing else.
+  `failure.error` is not among them — the row keeps `failure.code`, because a throwable's stack is
+  worth reading and is not worth storing, and rendering one into a column is the trap
+  `renderThrowable` exists for.
+- **`x_audit` ships no purge, and it is the only framework table that does not.**
+  `x_idempotency` and `x_rate_limit` both ship one because a stale row there is meaningless; a
+  stale audit row IS the record, and "how long" is a legal answer that is seven years for one app
+  and thirty days for the next. Shipping a `delete` would be shipping one of those answers.
+- **`SQL_AUDIT_INSERT` is positional, so its parameter order is pinned by a test and not by a
+  type.** `audit-parity.test.ts` names every column once and compares both sinks' answer for every
+  string field with a DIFFERENT value per field — two columns holding the same word cannot catch a
+  slip, and a `locale` in the `tz` slot type-checks perfectly. Proven by mutation: the first draft
+  of that test did NOT catch a swapped `locale`/`tz` and was widened until it did.
 - **A sink may not silently swallow, and the two failure policies are deliberate opposites.**
   `X_AUDIT_SINK_MISSING` is raised *before* the input parse, so an audited action nothing can
   record refuses with no committed write behind it — there is deliberately no logger-backed

package/README.md

@@ -249,7 +249,10 @@ name-sorted, and reads no clock, env or random source — same registry ⇒ same
 ## `rateLimit:` is the enforced limit
 
 ```ts
-rateLimit: { limit: 5, windowMs: 600_000 },   // 5 held, one back every two minutes
+import type { ActionRateLimit } from '@ultimat3/action';
+
+// The `rateLimit:` key of an `action()`: 5 held, one back every two minutes.
+const rateLimit: ActionRateLimit = { limit: 5, windowMs: 600_000 };
 ```
 
 One declaration, three places it lands: the bucket the limiter runs on (named after the action,
@@ -298,6 +301,9 @@ import {
   postgresIdempotencyStore,
   setIdempotencyStore,
 } from '@ultimat3/action';
+import { db } from '@ultimat3/db';
+
+const client = db();
 
 // NOT `executor: Bun.sql` — `Bun.sql.query` is `undefined` `As of 2026-08` (it is a tagged
 // template whose positional form is `unsafe`), so that line compiles and throws on the first
@@ -348,7 +354,14 @@ A `query` has none and never will: a read has nothing to be idempotent about.
 ## `deprecated:` — a compat window, not a version
 
 ```ts
-deprecated: { since: '2026-08-01T00:00:00Z', sunset: '2026-12-31T23:59:59Z', replacedBy: 'searchOrders' },
+import type { Deprecation } from '@ultimat3/action';
+
+// The `deprecated:` key of an `action()`.
+const deprecated: Deprecation = {
+  since: '2026-08-01T00:00:00Z',
+  sunset: '2026-12-31T23:59:59Z',
+  replacedBy: 'searchOrders',
+};
 ```
 
 Four things at once: `Deprecation: @1754006400` (RFC 9745) and `Sunset: Wed, 31 Dec 2026 …`
@@ -391,9 +404,53 @@ What the framework supplies is what it genuinely knows:
 | `outcome` | `allowed` \| `denied` \| `failed` |
 | `failure` | the `X_*` code and the thrown value, on every outcome but `allowed` |
 
-What it does **not** supply: an audit entity, a schema, a retention policy, a storage backend, a
-hash chain, a subject index, or an opinion on what "who" means under impersonation. Four apps
-model those four ways; shipping one would make three of them wrong.
+What it does **not** supply: an audit entity, a retention policy, a hash chain, a subject index,
+or an opinion on what "who" means under impersonation. Four apps model those four ways; shipping
+one would make three of them wrong.
+
+### Two sinks ship, and only one of them keeps anything
+
+| Sink | Keeps | Use it for |
+|---|---|---|
+| `memoryAuditSink({ maxRecords })` | the newest `DEFAULT_MAX_AUDIT_RECORDS` (1,000) records, verbatim. **It DROPS** — `dropped` counts what it discarded | `x dev`, tests |
+| `postgresAuditSink({ executor })` | one append-only `x_audit` row per attempt. Drops nothing | anything that has to keep its trail |
+
+The memory sink is bounded because a record pins a whole `Ctx`: at 50 audited writes a second an
+unbounded array is 4.3M immortal records a day and the pod dies holding the trail it was
+retaining. The trap it names out loud is that the shortest edit clearing `X_AUDIT_SINK_MISSING`
+is `setAuditSink(memoryAuditSink())`, and nothing at that call site says the result is amnesiac.
+
+```ts
+// apps/web/server.ts — the app owns the connection, so the app installs the sink
+import { postgresAuditSink, setAuditSink } from '@ultimat3/action';
+import { db } from '@ultimat3/db';
+
+const client = db();
+setAuditSink(
+  postgresAuditSink({ executor: { query: (text, values) => client.query({ text, values }) } }),
+);
+```
+
+**The table is applied by the boot; the sink is not.** `startQueue` runs `SQL_AUDIT_TABLE` on
+every start — `x dev`, the container's `web`/`worker`, and the release-phase `ROLE=migrate` — the
+way `SQL_IDEMPOTENCY_TABLE` is applied, because a package holding no database dependency cannot
+apply its own schema. Installing a sink stays your one line, deliberately: there is no default, so
+`audit: true` with none installed keeps refusing with `X_AUDIT_SINK_MISSING` instead of recording
+into a ring. `executor` is a client that already speaks `(text, values)` — never `Bun.sql`, whose
+`.query` is `undefined`.
+
+`x_audit` carries the framework's own facts as columns — the action, the surface, the outcome,
+the actor, the correlation ids, the idempotency key — and the parsed `input` as `jsonb`, redacted
+through **core's own** `isRedactedKey` table, the one `defineEnv({ secret: true })` extends. So a
+value that renders `[redacted]` in a log line cannot be plaintext in the audit table, and a
+boxed `Secret` is redacted by value wherever its key sits. What never reaches a column: the `Ctx`
+itself (`createContext` spreads every installed service onto it, and an HTTP surface's is a
+`RequestContext` carrying the caller's `Authorization` and `Cookie`), and the thrown value behind
+a failure — the row keeps `failure.code`, never the throwable.
+
+The table has **no purge**, deliberately, and it is the one framework table that does not: a
+stale idempotency row is meaningless while a stale audit row *is* the record, and "how long" is a
+legal answer that differs per app. Pruning or partitioning `x_audit` is yours.
 
 A denial is recorded because `invoke` wraps the whole path — `guard` throws **before** `handle`,
 so nothing you could write around your own handler would ever see one. That is the reason this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "11.2.0",
+  "version": "12.0.0",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "license": "MIT",
   "type": "module",
@@ -34,10 +34,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "11.2.0",
-    "@ultimat3/core": "11.2.0",
-    "@ultimat3/http": "11.2.0",
-    "@ultimat3/policy": "11.2.0",
-    "@ultimat3/schema": "11.2.0"
+    "@ultimat3/cache": "12.0.0",
+    "@ultimat3/core": "12.0.0",
+    "@ultimat3/http": "12.0.0",
+    "@ultimat3/policy": "12.0.0",
+    "@ultimat3/schema": "12.0.0"
   }
 }

package/src/audit-input.ts

@@ -0,0 +1,78 @@
+/**
+ * One job: turn an `AuditRecord.input` into something a durable sink may write down — redacted
+ * through core's own table, and representable as JSON on every path. Both halves are safety, not
+ * formatting: a stored credential is a leak, and a sink that throws on the caller's input fails an
+ * invocation whose handler has already committed.
+ */
+
+import { isRedactedKey, isSecret, REDACTED } from '@ultimat3/core';
+
+/**
+ * What a value this cannot represent becomes. A NAME and never `null`: `JSON.stringify` writes
+ * `null` for `NaN` and `±Infinity` and drops a function entirely, so an auditor reading the row
+ * could not tell "the field was absent" from "the field held something unwritable".
+ */
+export const UNREPRESENTABLE = '[unrepresentable]';
+
+/**
+ * How deep the walk goes. The input is schema-parsed, so its shape is the app's declaration — but
+ * `t.record` and a recursive schema have no depth of their own, and an overflow HERE lands in the
+ * sink, after the handler committed. Anything past this is `UNREPRESENTABLE`, which is the honest
+ * answer: it was there and this row does not carry it.
+ */
+export const AUDIT_INPUT_MAX_DEPTH = 12;
+
+/**
+ * `undefined` in, `undefined` out — an input that never parsed is a row with no input, not a row
+ * whose input was null.
+ *
+ * A cycle is CUT rather than raised on, and that is a cost decision as much as a correctness one:
+ * `JSON.stringify` over a self-referential value takes ~4.6s in Bun 1.4 before it throws, so
+ * leaving the detection to the serializer stalls the audited path whether or not the throw is
+ * caught. The ancestor set is the path, not everything seen — a value appearing twice as siblings
+ * is repetition and is written twice, exactly as `JSON.stringify` writes it.
+ *
+ * **`toJSON` is never called.** It is app code inside the frame that owes the caller a record, and
+ * one that throws is the second failure `jsonResult` already names; a `Map`, a `Set` and a `URL`
+ * therefore walk as their own enumerable keys, which is what `JSON.stringify` makes of them too.
+ */
+export function auditableInput(value: unknown): unknown {
+  if (value === undefined) return undefined;
+  return walk(value, 0, new Set());
+}
+
+function walk(value: unknown, depth: number, ancestors: Set<object>): unknown {
+  if (value === null) return null;
+  const kind = typeof value;
+  if (kind === 'string' || kind === 'boolean') return value;
+  if (kind === 'number') return Number.isFinite(value) ? value : UNREPRESENTABLE;
+  // `bigint`, `function`, `symbol`, and `undefined` reached through an array hole.
+  if (kind !== 'object') return UNREPRESENTABLE;
+
+  const object = value as object;
+  if (isSecret(object)) return REDACTED;
+  if (object instanceof Date) {
+    return Number.isNaN(object.getTime()) ? UNREPRESENTABLE : object.toISOString();
+  }
+  if (depth >= AUDIT_INPUT_MAX_DEPTH || ancestors.has(object)) return UNREPRESENTABLE;
+
+  ancestors.add(object);
+  try {
+    if (Array.isArray(object)) {
+      return object.map((item) => walk(item, depth + 1, ancestors));
+    }
+    const out: Record<string, unknown> = {};
+    // `Object.entries`, so only OWN enumerable keys are read: a prototype member is not this
+    // record's data, and reading one would put `Object.prototype`'s members in every audit row.
+    for (const [key, item] of Object.entries(object)) {
+      // The key decides before the value does, so a credential under a redacted name is never
+      // walked at all — `isRedactedKey` is core's, the same table `defineEnv({ secret: true })`
+      // extends, so a value that is `[redacted]` in a log line cannot be plaintext in a table.
+      if (isRedactedKey(key)) out[key] = REDACTED;
+      else if (item !== undefined) out[key] = walk(item, depth + 1, ancestors);
+    }
+    return out;
+  } finally {
+    ancestors.delete(object);
+  }
+}

package/src/audit-memory.ts

@@ -0,0 +1,84 @@
+/**
+ * The audit seam's process-memory sink: a bounded ring that DROPS, for tests and `x dev`. Split
+ * from `audit.ts` on the seam `idempotency.ts` / `idempotency-memory.ts` already draw, so the file
+ * declaring what a record IS is not also the file deciding how many are kept.
+ */
+
+import type { AuditRecord, AuditSink } from './audit';
+
+/**
+ * Records held at once. A record pins a whole `Ctx` — the actor, the service bag, the parsed
+ * input — so its cost is the request's, not a row's: at 50 audited writes a second an unbounded
+ * array is 4.3M immortal records a day and the pod dies holding the trail it was retaining. This
+ * sink was the one memory implementation in the framework with no cap, beside five that have one
+ * (`memoryRateLimitStore`, `MemoryIdempotencyStore`, `createLimiter`, `createTotpReplayGuard`,
+ * `createMemoryEventBus`).
+ */
+export const DEFAULT_MAX_AUDIT_RECORDS = 1_000;
+
+export interface MemoryAuditSinkOptions {
+  /** Records held at once. Absent, zero, negative or NaN all read as the default — never "no cap". */
+  readonly maxRecords?: number | undefined;
+}
+
+/**
+ * The seam's memory implementation, for tests and `x dev`. **Not a system of record, and not
+ * merely because it is not durable: it DISCARDS.** Past `maxRecords` the oldest record is dropped
+ * on every write, so an audited action can run, succeed, be recorded, and leave nothing behind —
+ * which is exactly what an audit trail must never do. The trap this shape exists to make visible
+ * is that the shortest edit clearing `X_AUDIT_SINK_MISSING` is `setAuditSink(memoryAuditSink())`,
+ * and nothing about the call site says the result is amnesiac. A deployment that must keep its
+ * trail installs `postgresAuditSink({ executor })`, which drops nothing.
+ *
+ * `dropped` is what makes that statement checkable in a running process rather than a sentence
+ * here: a non-zero count on a real deployment is the sink saying it is the wrong one.
+ */
+export interface MemoryAuditSink extends AuditSink {
+  /** The retained window, oldest first. A copy — the log cannot be mutated through it. */
+  records(): readonly AuditRecord[];
+  /** Retained right now — the bound, observable. */
+  readonly size: number;
+  /** Records this sink has DISCARDED since the last `clear()`. Never a number to ignore. */
+  readonly dropped: number;
+  clear(): void;
+}
+
+/**
+ * The OLDEST goes, which is the same direction `createMemoryEventBus` evicts in and the opposite
+ * of refusing new writes: a sink that stopped recording at the cap would answer "nothing has
+ * happened since" for a process that has been serving all day, and the most recent attempts are
+ * the ones anyone reading `x dev` is looking at.
+ */
+export function memoryAuditSink(options: MemoryAuditSinkOptions = {}): MemoryAuditSink {
+  const declared = options.maxRecords;
+  const maxRecords =
+    typeof declared === 'number' && Number.isFinite(declared) && declared >= 1
+      ? Math.floor(declared)
+      : DEFAULT_MAX_AUDIT_RECORDS;
+  const log: AuditRecord[] = [];
+  let dropped = 0;
+
+  return {
+    write(record: AuditRecord): void {
+      log.push(record);
+      // `shift` in a loop, not a slice: the cap is only ever exceeded by one per write, so this
+      // runs at most once — and it releases the evicted record's `Ctx` rather than copying the
+      // array, which would hold both windows alive for the length of the copy.
+      while (log.length > maxRecords) {
+        log.shift();
+        dropped += 1;
+      }
+    },
+    records: (): readonly AuditRecord[] => [...log],
+    get size(): number {
+      return log.length;
+    },
+    get dropped(): number {
+      return dropped;
+    },
+    clear: (): void => {
+      log.length = 0;
+      dropped = 0;
+    },
+  };
+}

package/src/audit-postgres.ts

@@ -0,0 +1,175 @@
+/**
+ * The durable audit sink: one append-only Postgres table, one insert per record. Without it the
+ * shortest edit that clears `X_AUDIT_SINK_MISSING` is `setAuditSink(memoryAuditSink())`, which
+ * reads durable at the call site and is a ring that DROPS — compliant in dev, amnesiac in
+ * production. Statements are spelled out so an agent can run the exact one it saw in a log.
+ */
+
+import type { Actor } from '@ultimat3/core';
+import { uuid } from '@ultimat3/core';
+import type { AuditRecord, AuditSink } from './audit';
+import { auditableInput } from './audit-input';
+import type { PgExecutor } from './idempotency-postgres';
+
+/**
+ * Applied by the boot, never by an app migration — the rule `SQL_IDEMPOTENCY_TABLE` follows, and
+ * for the same reason: this package holds no database dependency and cannot apply its own schema.
+ * `create table if not exists` is a no-op against a database that already has it, so a new column
+ * is added by `alter table … add column if not exists` and never by editing the `create`.
+ *
+ * **Two indexes and no third.** "Who did what, when" is the only question an audit table is opened
+ * for, and an index is a write cost paid on the audited path. A SUBJECT index — which row the
+ * action was about — is deliberately absent: the framework does not know a record's subject, and
+ * guessing one is the audit ENTITY this seam refuses to ship.
+ *
+ * **`at` is the one nullable column that looks like it should not be.** It is `ctx.now()`, and a
+ * `Clock` is injectable, so an app can hand this seam an Invalid Date — whose `toISOString()`
+ * THROWS. A sink that raises fails an invocation whose handler has already committed, so an
+ * unrepresentable instant is written as "this process could not say when" and `recorded_at`, the
+ * database's own clock, still stamps the row. `not null` would have traded a lost row for a lost
+ * write.
+ *
+ * **No retention, no purge, and that is the difference from every other table this framework
+ * owns.** `x_idempotency` and `x_rate_limit` both ship a purge because a stale row there is
+ * meaningless; a stale audit row is the record. How long a trail is kept is a legal question with
+ * a different answer per app — seven years for one, thirty days for the next — so shipping a
+ * `delete` would be shipping one of those answers. The table grows until the app prunes or
+ * partitions it, and that is stated rather than solved.
+ */
+export const SQL_AUDIT_TABLE = `
+create table if not exists x_audit (
+  id                uuid        primary key,
+  at                timestamptz,
+  action            text        not null,
+  mutator           boolean     not null,
+  surface           text        not null,
+  outcome           text        not null,
+  replayed          boolean     not null,
+  idempotency_key   text,
+  failure_code      text,
+  actor_id          text        not null,
+  actor_kind        text        not null,
+  org_id            text,
+  on_behalf_of_id   text,
+  on_behalf_of_kind text,
+  request_id        text        not null,
+  trace_id          text        not null,
+  locale            text        not null,
+  tz                text        not null,
+  build_id          text        not null,
+  role              text        not null,
+  input             jsonb,
+  recorded_at       timestamptz not null default now()
+);
+
+create index if not exists x_audit_at_idx on x_audit (at desc);
+
+create index if not exists x_audit_actor_at_idx on x_audit (actor_id, at desc);
+`;
+
+/**
+ * `id` is generated per ROW and is not an idempotency key: two identical attempts are two events
+ * and an audit trail that collapsed them would be lying about how many times something was tried.
+ * There is deliberately no `on conflict` — an append-only table has nothing to reconcile.
+ *
+ * `recorded_at` defaults to `now()` and is not a parameter: `at` is the caller's clock
+ * (`ctx.now()`) and this is the database's, so the gap between them is the audit lag, and a
+ * process whose clock has drifted is visible instead of invisible.
+ */
+export const SQL_AUDIT_INSERT = `
+insert into x_audit (
+  id, at, action, mutator, surface, outcome, replayed, idempotency_key, failure_code,
+  actor_id, actor_kind, org_id, on_behalf_of_id, on_behalf_of_kind,
+  request_id, trace_id, locale, tz, build_id, role, input
+) values (
+  $1::uuid, $2::timestamptz, $3, $4, $5, $6, $7, $8, $9,
+  $10, $11, $12, $13, $14,
+  $15, $16, $17, $18, $19, $20, $21::jsonb
+)
+`;
+
+export interface PostgresAuditSinkOptions {
+  readonly executor: PgExecutor;
+}
+
+export interface PostgresAuditSink extends AuditSink {
+  write(record: AuditRecord): Promise<void>;
+}
+
+/**
+ * **Install it at boot, beside the store that declares the rest of this app's durability.** The
+ * app owes one line in `apps/web/server.ts`, over the client this process already opened:
+ *
+ * ```ts
+ * const client = db();
+ * setAuditSink(
+ *   postgresAuditSink({
+ *     executor: { query: (text, values) => client.query({ text, values }) },
+ *   }),
+ * );
+ * ```
+ *
+ * `Bun.sql` does not satisfy `PgExecutor` — `Bun.sql.query` is `undefined`; see that interface.
+ *
+ * What is written is an ALLOW-LIST of the facts the framework itself owns, never the `Ctx`. That
+ * is not tidiness: `createContext` spreads every installed service onto the context object, and on
+ * an HTTP surface the value is a `RequestContext` carrying the request's own `Authorization` and
+ * `Cookie` headers — so a projection that walked it would write an app's database clients and its
+ * caller's credentials into an audit table. An app that wants more columns writes its own
+ * `AuditSink`; the seam is one method, and that is the extension point.
+ */
+export function postgresAuditSink(options: PostgresAuditSinkOptions): PostgresAuditSink {
+  const exec = options.executor;
+  return {
+    async write(record: AuditRecord): Promise<void> {
+      const actor = record.ctx.actor;
+      const at = record.at instanceof Date && !Number.isNaN(record.at.getTime()) ? record.at : null;
+      const onBehalfOf = onBehalfOfOf(actor);
+      const input = auditableInput(record.input);
+      await exec.query(SQL_AUDIT_INSERT, [
+        uuid(),
+        at === null ? null : at.toISOString(),
+        record.action,
+        record.mutator,
+        record.surface,
+        record.outcome,
+        record.replayed,
+        record.idempotencyKey,
+        record.failure?.code ?? null,
+        actor.id,
+        actor.kind,
+        actor.orgId ?? null,
+        onBehalfOf?.actorId ?? null,
+        onBehalfOf?.actorKind ?? null,
+        record.ctx.requestId,
+        record.ctx.traceId,
+        record.ctx.locale,
+        record.ctx.tz,
+        record.ctx.buildId,
+        record.ctx.role,
+        // `undefined` in means a parse that never produced an input, which is a NULL column and
+        // not the four characters `JSON.stringify(undefined)` does not produce either.
+        input === undefined ? null : JSON.stringify(input),
+      ]);
+    },
+  };
+}
+
+/**
+ * Both halves of an impersonation, recorded and interpreted as NEITHER. `actor_id` is who the
+ * framework ran the attempt as and `on_behalf_of_*` is what `impersonate()` recorded; which of
+ * them an app calls "who did this" is the convention four apps model four ways, so the row carries
+ * the two facts and takes no position between them.
+ *
+ * Read through a guard rather than off the type: `Actor.onBehalfOf` is optional, and an actor
+ * minted by an app's own `resolveToken` is a plain object nothing in this package validated.
+ */
+function onBehalfOfOf(actor: Actor): { actorId: string; actorKind: string } | null {
+  const origin: unknown = actor.onBehalfOf;
+  if (typeof origin !== 'object' || origin === null) return null;
+  const record = origin as Record<string, unknown>;
+  const actorId = record['actorId'];
+  const actorKind = record['actorKind'];
+  if (typeof actorId !== 'string' || typeof actorKind !== 'string') return null;
+  return { actorId, actorKind };
+}

package/src/audit.ts

@@ -53,6 +53,12 @@ export interface AuditRecord {
    * a sink needs to write a row at all. Carried whole rather than projected into `actorId` +
    * `requestId` fields, because choosing WHICH context facts an audit row keeps is precisely the
    * convention four apps modelled four ways.
+   *
+   * **A sink that PERSISTS must project it, and `audit-postgres.ts` is where that is done.**
+   * `createContext` spreads every installed service onto this object and an HTTP surface's value
+   * is a `RequestContext` carrying the caller's `Authorization` and `Cookie`, so writing it down
+   * whole puts an app's database clients and its caller's credentials in a table. Whole here,
+   * allow-listed there — the seam hands over everything and each sink decides what it keeps.
    */
   readonly ctx: Ctx;
   /**
@@ -82,26 +88,6 @@ export interface AuditSink {
   write(record: AuditRecord): Promise<void> | void;
 }
 
-/** The seam's memory implementation, for tests and `x dev`. Not a system of record. */
-export interface MemoryAuditSink extends AuditSink {
-  /** In the order `invoke` produced them. A copy — the log cannot be mutated through it. */
-  records(): readonly AuditRecord[];
-  clear(): void;
-}
-
-export function memoryAuditSink(): MemoryAuditSink {
-  const log: AuditRecord[] = [];
-  return {
-    write(record: AuditRecord): void {
-      log.push(record);
-    },
-    records: (): readonly AuditRecord[] => [...log],
-    clear: (): void => {
-      log.length = 0;
-    },
-  };
-}
-
 /**
  * No default. A logger-backed default would satisfy `audit: true` with a line nobody stores,
  * which is the silent pass this seam exists to remove: an audited action with no sink installed

package/src/index.ts

@@ -67,9 +67,18 @@ export type {
   AuditOutcome,
   AuditRecord,
   AuditSink,
-  MemoryAuditSink,
 } from './audit';
-export { getAuditSink, memoryAuditSink, resetAuditSink, setAuditSink } from './audit';
+export { getAuditSink, resetAuditSink, setAuditSink } from './audit';
+export { AUDIT_INPUT_MAX_DEPTH, auditableInput, UNREPRESENTABLE } from './audit-input';
+export type { MemoryAuditSink, MemoryAuditSinkOptions } from './audit-memory';
+export { DEFAULT_MAX_AUDIT_RECORDS, memoryAuditSink } from './audit-memory';
+/**
+ * The DURABLE sink, and the only one an app that must keep its trail may install. The statements
+ * are exported beside it because the table is applied the way `SQL_IDEMPOTENCY_TABLE` is — by the
+ * boot, never by an app migration.
+ */
+export type { PostgresAuditSink, PostgresAuditSinkOptions } from './audit-postgres';
+export { postgresAuditSink, SQL_AUDIT_INSERT, SQL_AUDIT_TABLE } from './audit-postgres';
 export type {
   ActionLike,
   ActionMap,