@ultimat3/action 30.9.0 → 31.1.0

package/CLAUDE.md

@@ -47,17 +47,20 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 | `declared-errors-contract.ts` | `.contract()`'s source scan |
 | `openapi-errors.ts` | core's builder bound to http's status and `problemTypeFor` |
 | `idempotency.ts` | the store SEAM: types, the installed-store slot, the scope declaration + `assertIdempotencyScope`, and `withIdempotency` — the replay-or-run gate |
+| `loader.ts` | `@ultimat3/action/loader`: `registerAction`/`registerActions` for `x`'s loader and framework fixtures. Never the barrel — `defineApi` is an app's one path (`loader.test.ts`) |
+| `adapter.ts` | `@ultimat3/action/adapter`: both stores' installers (each returns a release removing that install alone) + resets, port types, store errors, and `overrideHandler`. Never the barrel |
+| `handler-override.ts` | the slot `overrideHandler` writes: a test double where `handle` is, keyed by the stored declaration and read per call by `invoke` (`run`) and, for a stream, by the drain (`action-stream.ts`) — so policy, parse, meter, idempotency and output parse still run on every surface. `@ultimat3/testing`'s `stub()` is its one caller (`handler-override.test.ts`) |
 | `idempotency-key.ts` | the namespaced key — action + actor + the caller's key, as one JSON tuple — and the refusal of one that names no request |
 | `idempotency-memory.ts` | the process default: bounded, swept, `scope: 'process'` |
 | `idempotency-redact.ts` | `restingAnswer` — the copy of an answer a store may keep: core's `isRedactedKey` + `isSecret`, the SAME reference when nothing is redacted |
 | `idempotency-postgres.ts` | the SHARED store — one table, one `insert … on conflict` |
-| `policy-gate.ts` | **the only** runtime edge to `@ultimat3/policy` (`errors.ts` takes `SurfaceDenial` as a type, which erases) |
+| `policy-gate.ts` | **the only** runtime edge to `@ultimat3/policy` (`errors.ts` takes `PrimitiveDenial` and `SurfaceDenial` as types, which erases) |
 | `cache-gate.ts` | the post-COMMIT bust — **the only** file that calls `invalidateTags` |
 | `tx-scope.ts` | the open transaction — **the only** file that imports `@ultimat3/db` (`tx-scope.test.ts`): `openCommitScope` (the bust), `liveTransaction` (the settle), `completeTransaction`, and `inRolledBackScope`, the exercise's always-rolled-back scope and the memory transaction it opens always |
 | `rate-limit-gate.ts` | **the one place** a declared `rateLimit:` is spent (a `limit` resolved per call from `ctx`, through `toBucket`) |
 | `meter*.ts`, `errors-meter.ts` | `meter:` — declaration (`meter.ts`), UTC window, store seam + memory + Postgres (`x_meter`), and `meter-gate.ts`, **the one place** it is drawn |
 | `request-deadline.ts` | `requestDeadlineMs` — the app's `requestTimeoutMs`, resolved by http's own `defineHttpConfig` |
-| `audit.ts` | the audit seam's TYPES, re-exported from `@ultimat3/core` (shared with `query`); the slot (`setAuditSink`) is core's alone |
+| `audit.ts` | the audit seam's TYPES, re-exported from `@ultimat3/core` (shared with `query`); the slot (`installAuditSink`, `@ultimat3/core/adapter`) is core's alone |
 | `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 |
@@ -157,8 +160,8 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 - **Both clients inject `traceparent`** before the caller's headers; an incomplete span sends nothing.
 - `serializeOpenApi` output is byte-stable: sorted keys, sorted registry, no clock. `client.ts` stays
   free of server imports.
-- **`stable.ts` holds the DOCUMENT form only** (`stableStringify` → `openapi.json`, re-read by
-  `json-schema.ts`). The HASH form is core's `canonicalJson`/`fingerprint` (injective: tags
+- **`stable.ts` holds the DOCUMENT form only** (`stableStringify`, exported: `openapi.json`,
+  `json-schema.ts`, mcp's `tools.lock.json`, testing's cassettes — no other serializer). The HASH form is core's `canonicalJson`/`fingerprint` (injective: tags
   `NaN`/`±Infinity`/`-0`, `Date`, `Map`, `Set`); `stable.test.ts` pins byte-equality for ordinary
   payloads.
 - **`tagKeys` is `@ultimat3/cache`'s and `toBucket` is `@ultimat3/http`'s** (imported, never
@@ -184,21 +187,17 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 - **Flight control is `@ultimat3/core`'s, and NOT re-exported** — its values are imported from
   core (`X_HELPER_COPY` refuses a re-export); only the types `ClientFlight`/`ClientRetry`. Fix the
   pipeline in `packages/core/src/client-flight.ts`. No new code, curve, fence or retry loop here (`bun run flight-copies`).
-- **`isTransientFailure` INVERTS `retryDecision`'s unclassified default** (a caller's `AbortError`
-  is terminal). Must survive.
 - **`ClientFlight` is a TYPE inside `client.ts`, never a value.** Measured,
   `bun build --target=browser --minify`, one entry importing from `@ultimat3/action` — **the ONE
   table for these figures** (`packages/core/CLAUDE.md` points here):
 
-  | Entry | `As of 2026-11-06`, Bun 1.4.4, one entry over the working tree |
+  | Entry | `As of 2026-11-09`, Bun 1.4.4, one entry over the working tree |
   |---|---|
-  | `rpc` | 29,291 B: `.stream` (core's `clientStream`, through `dispatchStream`) +1,746 B over the 27,545 B before it; pinned paths (wave 5b) `fillWire` +758 B, `renderedActionPin` +619 B (each stubbed out) |
-  | `rpc` + core's `clientFlight` | 38,054 B |
+  | `rpc` | 24,473 B, pinned ≤ 25,000 (`client-bundle.test.ts`); 29,972 B while it read core's barrel |
+  | `rpc` + `clientFlight` from `@ultimat3/core/page` | 32,929 B (38,416 B from the barrel) |
 
-- **`sideEffects` is `["./src/error-titles.ts"]`**, never `false` (drops its bare imports): the
-  titles ride into every barrel chunk (`problemError` decodes by code), `errors.ts`'s classes do
-  not. An http refusal needs no http module: core's decoders take its title off the body and its
-  `retry-after` off the header (`rpc-refusal.test.ts`).
+- `isTransientFailure`'s inversion, the client graph's import rule, `sideEffects`: still rules, in
+  `docs/history/action-client-graph.md` (moved 2026-11-09).
 
 ## Invariants — idempotency
 
@@ -206,29 +205,15 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
   is SETTLED as a failure and a retry replays it; `release()` is only for a pre-handler failure. A
   `settle` that refuses leaves the record in flight. `idempotency-failure.test.ts`.
 - **A keyed run is owed its end**: `completeTransaction()`, then `runToCompletion(run)` under `idempotencyCeilingMs()` (`X_IDEMPOTENCY_RUN_CEILING`); `invoke` reads the handler's `ctx` inside it. `idempotency-orphan.test.ts`.
-- **A record belongs to ONE CALLER**: the key is
-  `JSON.stringify([action, actor.kind, actor.id, actor.orgId ?? null, key])` — a JSON tuple, never a
-  joined string. A blank header is `X_IDEMPOTENCY_KEY_INVALID` (4xx, before the handler), never "no
-  key". Anonymous callers still share one key space.
-- **The `idempotency-key` header also NAMES the write, on every action**: `http.ts` runs `invoke`
-  inside `withWriteOrigin(writeDigest(key))` so the page recognises its own `records` echo. A label,
-  never a gate.
 - **Both stores FENCE a settlement on the reservation `id` AND `in-flight`**:
   `settle(key, value, reservationId, redacted)` / `fail(key, failure, reservationId)` /
-  `release(key, reservationId)`. A fenced no-op is never thrown.
+  `release(key, reservationId)`. A fenced no-op is never thrown; an autocommit `settle`/`fail` logs `action.idempotency.settlement-fenced` on BOTH stores (`idempotency-memory-fenced.test.ts`).
 - **An answer rests REDACTED** (#591): `withIdempotency` passes the store `restingAnswer(value)`
   (core's `isRedactedKey` + `isSecret`) and `redacted` as `settle`'s REQUIRED 4th argument. A
   flagged replay is `X_IDEMPOTENT_REPLAY_REDACTED`, by the FLAG, never by scanning. Full rule: `docs/history/action.md`.
 - **A finished record skips the row half; a stale peek judges it in `beforeRun`** (`idempotency-row.test.ts`). **A `bigint` answer settles failed** (`X_IDEMPOTENCY_OUTPUT_UNSERIALIZABLE`).
-- **A stored status is NARROWED** (`isIdempotencyStatus`; unknown is
-  `X_IDEMPOTENCY_STATUS_UNKNOWN`), never cast.
-- **Where records live is DECLARED and refused at registration**: `IdempotencyStore.scope` vs
-  `configureIdempotency({ scope })`, compared by `assertIdempotencyScope` in `registerAction`
-  (`X_IDEMPOTENCY_NOT_SHARED`). Default `'process'`.
-- **The memory store is bounded; `in-flight` records are the last evicted.** Never an LRU.
-- **`postgresIdempotencyStore` is the shared store** over `@ultimat3/core`'s structural `PgExecutor`; the
-  reservation is ONE `insert … on conflict` statement. The CLI boot installs it.
-- **Inside a transaction the SETTLE commits with the write, on BOTH stores** (`liveTransaction()`). `idempotency-parity.test.ts`. Full rule: `docs/history/action.md`.
+- **Caller keying, the write-origin label, status narrowing, declared scope, eviction order, the shared store**: `docs/history/action.md#idempotency-invariants-moved-from-claudemd`.
+- **Inside a transaction the SETTLE commits with the write, on BOTH stores** (`liveTransaction()`). `idempotencyStoreConformance` (`@ultimat3/testing/conformance`). Full rule: `docs/history/action.md`.
 - **The deadline is `reclaimAfterMs: () => number`, REQUIRED on the Postgres store** and read per
   reservation (`requestDeadlineMs`, never a number here); `origin: () => object` is required too. Full rule: `docs/history/action.md`.
 
@@ -254,7 +239,7 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
   `locale`, `tz`, `buildId`, `role`, actor `id`/`kind`/`orgId`/`onBehalfOf`) and keeps
   `failure.code`, never the error.
 - **`x_audit` ships no purge**, deliberately. **`SQL_AUDIT_INSERT` is positional**, pinned by
-  `audit-parity.test.ts` with a distinct value per field. Only `*_TABLE` DDL is exported
+  `audit-postgres-columns.test.ts` (a distinct value per field) and `auditSinkConformance` live. Only `*_TABLE` DDL is exported
   (`X_SQL_EXPORT_UNREAD`).
 - **The two failure policies are opposites**: `X_AUDIT_SINK_MISSING` before the input parse; a sink refusing an ALLOWED record is `X_AUDIT_SINK_FAILED`; refusing a denied or failed one is logged. Full rule: `docs/history/action.md`.
 - **`auditSettled` sits outside the `catch`**, and **`auditOutcomeFor` is TOTAL** (fails closed to
@@ -263,7 +248,7 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 ## Commands
 
 ```
-bun test packages/action
+bun test ./packages/action/
 bun run typecheck
 ```
 

package/README.md

@@ -105,7 +105,8 @@ names deriving one route collide with `X_ACTION_PATH_DUPLICATE` — `pluralize`
 
 `registerActions` is what `defineApi` composes for the three action-shaped keys; the other three
 go through core's `primitiveRegistrar(kind)`, because this package may not import `@ultimat3/query`
-or `@ultimat3/jobs` sideways. An app calling either directly is a second path.
+or `@ultimat3/jobs` sideways. It is not on the `.` barrel: `defineApi` is the one path an app has,
+and `x`'s module loader imports `registerAction`/`registerActions` from `@ultimat3/action/loader`.
 
 ## Call it — `rpc`
 
@@ -470,7 +471,7 @@ call (`surface: 'server'` — a service, a seed, a test) is app code, not a call
 | Fact | Answer |
 |---|---|
 | whose bucket | the caller's: actor → org → connection address (`@ultimat3/http`'s `rateLimitSpends`). An anonymous caller with no address (MCP, a job) shares one bucket |
-| where it is counted | `@ultimat3/http`'s installed store (`installRateLimitStore()`) — the slot `@ultimat3/query` spends from too; the boot fills it with the SAME instance it gives `httpServer({ rateLimitStore })`, on every role. Default: one process' memory |
+| where it is counted | `@ultimat3/http`'s installed store — the slot `@ultimat3/query` spends from too; the boot fills it from `rateLimitStore` in `apps/<app>/runtime.ts` (else Postgres over its pool), on every role |
 | what HTTP answers | `RateLimit-*` from the bucket closest to refusing, and on a refusal `429` + `Retry-After` — the pipeline's own shape |
 | a retry | an admitted attempt spends one token; a refused one spends nothing. A job refused `X_RATE_LIMITED` is rescheduled for its `Retry-After` WITHOUT counting an attempt, so a backlog is delayed, never dead-lettered |
 | an idempotent replay | spends nothing: the stored answer is served, never a 429 |
@@ -480,15 +481,13 @@ call (`surface: 'server'` — a service, a seed, a test) is app code, not a call
 
 ```ts
 import type { PgExecutor } from '@ultimat3/core';
-import { installRateLimitStore, postgresRateLimitStore } from '@ultimat3/http';
+import { postgresRateLimitStore } from '@ultimat3/http';
 
-declare const executor: PgExecutor; // the pool this boot already opened
+declare const executor: PgExecutor; // the pool this process already opened
 
-// Boot, before the first call — the one store every surface and every replica counts in.
-// `x dev` and a container boot do this themselves, and `httpServer({ rateLimitStore })` adopts
-// the store it is handed; a process with no server (a worker of your own) installs it here.
-const rateLimitStore = postgresRateLimitStore({ executor });
-installRateLimitStore(rateLimitStore);
+// apps/<app>/runtime.ts — the one store every surface and every replica counts in. `x dev` and a
+// container boot install Postgres over their own pool without it; this line replaces that store.
+export const runtime = { rateLimitStore: postgresRateLimitStore({ executor }) };
 ```
 
 `toBucket` is the only conversion — `capacity: limit`, `refillPerSecond: limit / (windowMs / 1000)`
@@ -604,13 +603,8 @@ must say so and bring a store that can keep it, or the retry that lands on anoth
 no record and runs the handler again:
 
 ```ts
-// boot, before registerActions()
-import {
-  configureIdempotency,
-  postgresIdempotencyStore,
-  requestDeadlineMs,
-  setIdempotencyStore,
-} from '@ultimat3/action';
+// apps/<app>/runtime.ts — the boot installs the store before defineApi() registers
+import { configureIdempotency, postgresIdempotencyStore, requestDeadlineMs } from '@ultimat3/action';
 import { db } from '@ultimat3/db';
 
 const client = db();
@@ -618,17 +612,17 @@ 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
 // reservation.
-// The framework boot installs this store for you; reach for it by hand only from a host that
-// boots the framework itself, and wrap the client that host already opened.
-setIdempotencyStore(
-  postgresIdempotencyStore({
+// The framework boot installs this store for you; hand it one only to replace it, and wrap the
+// client this process already opened.
+export const runtime = {
+  idempotencyStore: postgresIdempotencyStore({
     executor: { query: (text, values) => client.query({ text, values }) },
     // The client transactions on THIS database open on: a settle rides one of those and no other.
     origin: () => client,
     // The app's `requestTimeoutMs` (`configureHttp`), read per reservation — never a number here.
     reclaimAfterMs: requestDeadlineMs,
   }),
-);
+};
 configureIdempotency({ scope: 'shared' });
 ```
 
@@ -675,7 +669,7 @@ status is `in-flight`** — one that ignores the second argument reopens the dou
 type-checking cannot catch it: a one-parameter function still satisfies the signature.
 
 **Inside a transaction the settlement commits with the write** (`As of 2026-10-02`, BOTH stores —
-`idempotency-parity.test.ts` runs one set of cases over memory and Postgres). An action invoked
+`idempotencyStoreConformance` on `@ultimat3/testing/conformance` runs one set of cases over memory and Postgres). An action invoked
 inside `withTransaction` settles with that transaction: on its own connection (Postgres), or at
 its `onCommit` (memory).
 
@@ -779,11 +773,15 @@ price change are not the same event, and the framework is not the thing that kno
 them your business has to keep.
 
 ```ts
-import { setAuditSink } from '@ultimat3/core';
+// apps/web/runtime.ts — the boot installs it before the app's modules import
+import type { RuntimeOverrides } from '@ultimat3/cli/serve';
+import type { AuditRecord } from '@ultimat3/core';
 
-setAuditSink({
-  async write(record) { await record.ctx.db.auditRows.insert(myRow(record)); },
-});
+declare function keep(record: AuditRecord): Promise<void>; // your table, log or queue
+
+export const runtime = {
+  auditSink: { write: (record) => keep(record) },
+} satisfies RuntimeOverrides;
 ```
 
 What the framework supplies is what it genuinely knows:
@@ -800,8 +798,9 @@ What the framework supplies is what it genuinely knows:
 | `failure` | the `X_*` code and the thrown value, on every outcome but `allowed` |
 
 **One contract, one sink, shared with reads.** `AuditRecord`, `AuditSink` and the installed slot
-are `@ultimat3/core`'s, and so is the one way to install it: `setAuditSink` from `@ultimat3/core`
-(this package re-exports the two types, never the slot — `As of 25.0.0`) installs the sink `query({ audit: true })` writes to as well (`@ultimat3/query`'s README). A sink
+are `@ultimat3/core`'s, and so is the one way to install it: the `auditSink` field of
+`apps/web/runtime.ts`, which the boot installs through core's `installAuditSink`
+(`@ultimat3/core/adapter`, 31.0; this package re-exports the two types, never the slot) — the sink `query({ audit: true })` writes to as well (`@ultimat3/query`'s README). A sink
 tells the two apart by `record.primitive`.
 
 What it does **not** supply: an audit entity, a retention policy, a hash chain, a subject index,
@@ -818,18 +817,17 @@ one would make three of them wrong.
 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.
+is `auditSink: memoryAuditSink()`, and nothing at that line says the result is amnesiac.
 
 ```ts
-// apps/web/server.ts — the app owns the connection, so the app installs the sink
+// apps/web/runtime.ts — the boot installs the sink, over the pool it opened
 import { postgresAuditSink } from '@ultimat3/action';
-import { setAuditSink } from '@ultimat3/core';
-import { db } from '@ultimat3/db';
+import type { RuntimeOverrides } from '@ultimat3/cli/serve';
+import { dbExecutor } from '@ultimat3/db';
 
-const client = db();
-setAuditSink(
-  postgresAuditSink({ executor: { query: (text, values) => client.query({ text, values }) } }),
-);
+export const runtime = {
+  auditSink: postgresAuditSink({ executor: dbExecutor() }),
+} satisfies RuntimeOverrides;
 ```
 
 **The table is applied by the boot; the sink is not.** `startQueue` runs `SQL_AUDIT_TABLE` on
@@ -898,7 +896,8 @@ The row it produces is the app's, and so is every question the framework refused
 which fields, whose tenant, chained or not, kept how long:
 
 ```ts
-setAuditSink({
+// apps/web/runtime.ts — every name below but `runtime` is the app's own
+export const runtime = { auditSink: {
   async write(record) {
     const { ctx } = record;                             // the services a sink needs to write a row
     const prev = await chainHead(ctx);                  // hash-chained: the app's choice
@@ -910,7 +909,7 @@ setAuditSink({
       prevHash: prev, hash: await sha256(prev, record),
     });
   },
-});
+} } satisfies RuntimeOverrides; // apps/web/runtime.ts
 ```
 
 ## The audit trail, for a subject export or erase
@@ -956,6 +955,24 @@ Pass `input:` when the schema carries a constraint the IR cannot invert (a bare
 when `row:` needs an id that resolves. Anything thrown *before* the policy decides is drift,
 never a pass — the assertion says which code got in the way and names `input:` as the fix.
 
+## `@ultimat3/action/loader` — where an export is named
+
+`registerAction(name, action)` / `registerActions(module)`: what `defineApi` and `x`'s module scan
+call to stamp an export's name onto it, and what a framework fixture calls to name one action.
+Never on the `.` barrel — an app hands its modules to `defineApi` (`loader.test.ts` pins both).
+
+## `@ultimat3/action/adapter` — the stores' installers and the handler override
+
+The boot's installers live here, never on the `.` barrel: `installIdempotencyStore(store)` and
+`installMeterStore(store)` each return a release that removes that install alone, in any order, beside
+`resetIdempotency()` / `resetMeterStore()`, the port types and the errors a store throws. An app
+swaps a store with `idempotencyStore:` / `meterStore:` in `apps/<app>/runtime.ts`.
+
+`overrideHandler(action, handle | undefined)` puts a test double where `handle` is, on every
+surface — a direct call, `.as()`, HTTP, MCP, `.job()`, `.stream()` (the drain reads it per call).
+The policy, the rate limit, the input parse, the meter, idempotency and the output parse still run
+around it; `undefined` restores the declared handler. `@ultimat3/testing`'s `stub()` drives it.
+
 ## Errors
 
 | Code | When | Fix |
@@ -980,8 +997,8 @@ never a pass — the assertion says which code got in the way and names `input:`
 | `X_CONTRACT_EXERCISE_UNREACHED` | no generated run reached the handler | `.contract({ exercise: { actor } })` with a permitted actor, or bind a row with `exercise.input` |
 | `X_CONTRACT_EXERCISE_UNDECLARED` | `.contract()` on a guarded action with no `exercise`, or a blank `off` | `.contract({ exercise: { actor } })` or `{ exercise: { off: '<reason>' } }` |
 | `X_RPC_FAILED` | registered, thrown by nothing since 21.0.0 — a non-`problem+json` failure is core's `X_CLIENT_TRANSPORT_FAILED` now, as for a query | match `X_CLIENT_TRANSPORT_FAILED` instead |
-| `X_ACTION_UNREGISTERED` | projected before `registerActions()` ran | register at boot |
-| `X_AUDIT_SINK_MISSING` | `audit: true` and no sink installed — raised before the input parse | `setAuditSink(yourSink)` at boot |
+| `X_ACTION_UNREGISTERED` | projected before `defineApi()` named it | hand its module to `defineApi` at boot |
+| `X_AUDIT_SINK_MISSING` | `audit: true` and no sink installed — raised before the input parse | `auditSink: postgresAuditSink({ executor })` in `apps/web/runtime.ts` |
 | `X_AUDIT_SINK_FAILED` | the sink refused the record for an attempt that **succeeded** | fix the sink — then retry the same `Idempotency-Key` if this call carried one, else reconcile by hand |
 
 Denials re-throw the policy layer's own codes (`X_FORBIDDEN`, `X_UNAUTHENTICATED`) —
@@ -1009,21 +1026,12 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | Class | Code | Declared in |
 |---|---|---|
 | `ActionDeniedError` | the policy denial's own code (`X_FORBIDDEN`, `X_UNAUTHENTICATED`, …), kept on `.denial` | `src/errors.ts` |
-| `ActionDeprecationInvalidError` | `X_ACTION_DEPRECATION_INVALID` | `src/errors.ts` |
-| `ActionDuplicateError` | `X_ACTION_DUPLICATE` | `src/errors.ts` |
-| `ActionForeignError` | `X_ACTION_FOREIGN` | `src/errors.ts` |
-| `ActionPathDuplicateError` | `X_ACTION_PATH_DUPLICATE` | `src/errors.ts` |
-| `ActionPolicyMissingError` | `X_ACTION_POLICY_MISSING` | `src/errors.ts` |
-| `ActionUnregisteredError` | `X_ACTION_UNREGISTERED` | `src/errors.ts` |
 | `AuditSinkFailedError` | `X_AUDIT_SINK_FAILED` | `src/errors.ts` |
-| `AuditSinkMissingError` | `X_AUDIT_SINK_MISSING` | `src/errors.ts` |
 | `ContractDriftError` | `X_CONTRACT_DRIFT` | `src/errors.ts` |
 | `IdempotencyConflictError` | `X_IDEMPOTENCY_CONFLICT` | `src/errors-idempotency.ts` |
 | `IdempotencyKeyInvalidError` | `X_IDEMPOTENCY_KEY_INVALID` | `src/errors-idempotency.ts` |
-| `IdempotencyNotSharedError` | `X_IDEMPOTENCY_NOT_SHARED` | `src/errors-idempotency.ts` |
 | `IdempotencyReplayedFailureError` | `X_IDEMPOTENCY_REPLAYED_FAILURE` | `src/errors-idempotency.ts` |
 | `IdempotencyReservationLostError` | `X_IDEMPOTENCY_RESERVATION_LOST` | `src/errors-idempotency.ts` |
-| `IdempotencyStatusUnknownError` | `X_IDEMPOTENCY_STATUS_UNKNOWN` | `src/errors-idempotency.ts` |
 | `InputInvalidError` | `X_INPUT_INVALID` | `src/errors.ts` |
 | `MutatorNotIdempotentError` | `X_MUTATOR_NOT_IDEMPOTENT` | `src/errors-idempotency.ts` |
 | `OutputInvalidError` | `X_OUTPUT_INVALID` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "30.9.0",
+  "version": "31.1.0",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "keywords": [
     "ultimate",
@@ -28,7 +28,9 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./adapter": "./src/adapter.ts",
+    "./loader": "./src/loader.ts"
   },
   "files": [
     "src",
@@ -46,12 +48,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "30.9.0",
-    "@ultimat3/core": "30.9.0",
-    "@ultimat3/db": "30.9.0",
-    "@ultimat3/entity": "30.9.0",
-    "@ultimat3/http": "30.9.0",
-    "@ultimat3/policy": "30.9.0",
-    "@ultimat3/schema": "30.9.0"
+    "@ultimat3/cache": "31.1.0",
+    "@ultimat3/core": "31.1.0",
+    "@ultimat3/db": "31.1.0",
+    "@ultimat3/entity": "31.1.0",
+    "@ultimat3/http": "31.1.0",
+    "@ultimat3/policy": "31.1.0",
+    "@ultimat3/schema": "31.1.0"
   }
 }

package/src/action-stream.ts

@@ -9,6 +9,7 @@ import { asyncContext } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { formatIssues, validateAsync } from '@ultimat3/schema';
 import { ActionStreamInvalidError } from './errors-stream';
+import { handlerOverrideOf } from './handler-override';
 
 /** Where a draining handler hands its chunks: `http-stream.ts` opens one per streamed request. */
 export interface ChunkSink {
@@ -39,6 +40,18 @@ export function withChunkSink<T>(sink: ChunkSink, fn: () => T): T {
   return sinks.run({ sink, claimed: false }, fn);
 }
 
+/**
+ * Each draining copy → the declaration it wraps. Built once per `.named()` twin, so an override is
+ * keyed by the declaration (`declarationOf`), never the copy, and reaches every twin at once.
+ */
+const DRAINED = new WeakMap<object, object>();
+
+/** Whether `def`'s `handle` is the drain: the drain, not `invoke`, resolves its override. */
+export const drainsItsHandler = (def: object): boolean => DRAINED.has(def);
+
+/** The declaration an override is keyed by: the wrapped one for a draining copy, else `def`. */
+export const declarationOf = (def: object): object => DRAINED.get(def) ?? def;
+
 interface StreamingDef {
   readonly stream?: StandardSchemaV1;
   handle(args: { readonly input: unknown; readonly ctx: Ctx }): unknown;
@@ -53,9 +66,12 @@ export function streamingDef<D extends StreamingDef>(def: D, name: () => string)
   if (stream === undefined) return def;
   const wrapped: D = {
     ...def,
+    // The override is resolved per call, never captured here: a test double installed after the
+    // declaration (`overrideHandler`) is drained exactly as the declared generator would be.
     handle: (args: { readonly input: unknown; readonly ctx: Ctx }) =>
-      drain(wrapped, stream, name(), def.handle(args)),
+      drain(wrapped, stream, name(), (handlerOverrideOf(def) ?? def.handle.bind(def))(args)),
   };
+  DRAINED.set(wrapped, def);
   return wrapped;
 }
 

package/src/adapter.ts

@@ -0,0 +1,22 @@
+// `@ultimat3/action/adapter` — what an idempotency or meter store is built and installed from: the
+// port interfaces, the errors a store throws, and the boot's installers with their resets. Never
+// the `.` barrel: an app swaps a store in `apps/<app>/runtime.ts` (`idempotencyStore:`,
+// `meterStore:`), so the only callers here are the cli boot, `@ultimat3/testing` and a store author.
+
+export {
+  IdempotencyReservationLostError,
+  IdempotencyStatusUnknownError,
+} from './errors';
+export type { HandlerOverride } from './handler-override';
+export type {
+  IdempotencyFailure,
+  IdempotencyRecord,
+  IdempotencyReservation,
+  IdempotencyScope,
+  IdempotencyStatus,
+  IdempotencyStore,
+} from './idempotency';
+export { installIdempotencyStore, resetIdempotency } from './idempotency';
+export { overrideHandler } from './invoke';
+export type { MeterDraw, MeterDrawResult, MeterKey, MeterStore } from './meter-store';
+export { installMeterStore, resetMeterStore } from './meter-store';

package/src/audit-gate.ts

@@ -4,7 +4,13 @@
  * an attempt that already failed do not want the same answer.
  */
 
-import { getAuditSink, isUltimateError, logger } from '@ultimat3/core';
+import {
+  AUDIT_SINK_FAILED_EVENT,
+  auditFailureOf,
+  auditOutcomeOf,
+  getAuditSink,
+  logger,
+} from '@ultimat3/core';
 import type { AuditFailure, AuditOutcome, AuditRecord, AuditSink } from './audit';
 import { ActionDeniedError, AuditSinkFailedError, AuditSinkMissingError } from './errors';
 
@@ -31,15 +37,11 @@ export function auditSinkFor(action: string): AuditSink {
  * examined is not evidence of a policy denial, so it fails closed to `failed`.
  */
 export function auditOutcomeFor(error: unknown): AuditOutcome {
-  try {
-    return error instanceof ActionDeniedError ? 'denied' : 'failed';
-  } catch {
-    return 'failed';
-  }
+  return auditOutcomeOf(error, (thrown) => thrown instanceof ActionDeniedError);
 }
 
 export function auditFailureFor(error: unknown): AuditFailure {
-  return { code: isUltimateError(error) ? error.code : null, error };
+  return auditFailureOf(error);
 }
 
 /**
@@ -82,7 +84,7 @@ export async function auditThrew(sink: AuditSink, record: AuditRecord): Promise<
     // Core's logger, not `ctx.logger`: an HTTP `Ctx` is a cast request context that carries none,
     // the same reason `cache-gate.ts` gives. Never the record — rendering an input the sink just
     // choked on is the second throw this branch exists to prevent.
-    logger.error('audit.sink.failed', {
+    logger.error(AUDIT_SINK_FAILED_EVENT, {
       action: record.name,
       outcome: record.outcome,
       error,

package/src/audit-memory.ts

@@ -26,8 +26,8 @@ export interface MemoryAuditSinkOptions {
  * 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
+ * is that the shortest edit clearing `X_AUDIT_SINK_MISSING` is `auditSink: memoryAuditSink()`,
+ * and nothing about that line 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

package/src/audit-postgres.ts

@@ -1,7 +1,7 @@
 /**
  * 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
+ * shortest edit that clears `X_AUDIT_SINK_MISSING` is `auditSink: memoryAuditSink()`, which
+ * reads durable at the line 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.
  */
 
@@ -102,16 +102,13 @@ export interface PostgresAuditSink extends AuditSink {
 }
 
 /**
- * **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:
+ * **Name it in `apps/web/runtime.ts`, beside the rest of this app's durability**, over the pool the
+ * boot opened — the boot installs it (`installAuditSink`) before the app's modules import:
  *
  * ```ts
- * const client = db();
- * setAuditSink(
- *   postgresAuditSink({
- *     executor: { query: (text, values) => client.query({ text, values }) },
- *   }),
- * );
+ * export const runtime = {
+ *   auditSink: postgresAuditSink({ executor: dbExecutor() }),
+ * } satisfies RuntimeOverrides;
  * ```
  *
  * `Bun.sql` does not satisfy `PgExecutor` — `Bun.sql.query` is `undefined`; see that interface.

package/src/audit.ts

@@ -3,8 +3,8 @@
  * The contract — the record, the sink, the one installed-sink slot — moved to `@ultimat3/core`'s
  * `audit.ts` so `@ultimat3/query` (a sibling this package cannot import) writes the same record
  * into the same sink. The TYPES are re-exported for this package's own modules; the slot's VALUES
- * (`getAuditSink`, `setAuditSink`, `resetAuditSink`) are imported from `@ultimat3/core` and never
- * re-exported — a second import path for one value is `X_HELPER_COPY` (`bun run flight-copies`).
+ * (`getAuditSink`; the boot's `installAuditSink` is `@ultimat3/core/adapter`'s) are imported from
+ * core and never re-exported — a second import path for one value is `X_HELPER_COPY` (`bun run flight-copies`).
  */
 
 export type { AuditFailure, AuditOutcome, AuditRecord, AuditSink } from '@ultimat3/core';

package/src/client.ts

@@ -21,7 +21,7 @@ import type {
   ClientRetry,
   FetchLike,
   UltimateError,
-} from '@ultimat3/core';
+} from '@ultimat3/core/page';
 import {
   actionPath,
   BUILD_ID_HEADER,
@@ -33,7 +33,7 @@ import {
   problemOf,
   remoteTitleOf,
   renderedActionPin,
-} from '@ultimat3/core';
+} from '@ultimat3/core/page';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { Action, StreamAction } from './action';
 import { ContractDriftError, RemoteActionError } from './errors';
@@ -101,7 +101,7 @@ export type StreamClientMethod<
 };
 
 /** Core's one declaration, re-exported by name so `import type { FetchLike }` keeps resolving. */
-export type { FetchLike } from '@ultimat3/core';
+export type { FetchLike } from '@ultimat3/core/page';
 
 export interface ClientOptions {
   readonly baseUrl: string;
@@ -311,6 +311,7 @@ function toUltimateError(
     // Parsed, never taken: `body` is whatever answered the request. A list this build cannot read
     // is dropped rather than repaired, and `cause` below still carries every rejection in it.
     issues: issuesFromWire(body['issues']),
+    issuesTruncated: body['issuesTruncated'] === true ? true : undefined,
     meta: metaFromWire(body['meta']),
     requestId: body['requestId'],
     cause: stringOr(body['cause'] ?? body['detail'], `${name} failed with ${status}`),
@@ -325,8 +326,8 @@ function toUltimateError(
 
 /**
  * The document's `meta` member, or nothing. Parsed JSON is JSON-safe by construction, so the only
- * work is shape: an object, copied own key by own key onto a fresh record. `issues` is skipped
- * because it has its own reader and its own bound one line up, and `__proto__` because
+ * work is shape: an object, copied own key by own key onto a fresh record. `issues` and its flag
+ * `issuesTruncated` are skipped because they have their own reader up top, and `__proto__` because
  * `JSON.parse` mints it as a real own key — copied by assignment it would replace the prototype
  * of the error's `meta`, which the reporter and the overlay walk. EMPTY is `undefined`: an
  * `{}` under `meta` would say the server declared keys and sent none.
@@ -336,7 +337,7 @@ function metaFromWire(value: unknown): Readonly<Record<string, unknown>> | undef
   const out: Record<string, unknown> = {};
   let carried = 0;
   for (const [key, member] of Object.entries(value)) {
-    if (key === 'issues' || key === '__proto__') continue;
+    if (key === 'issues' || key === 'issuesTruncated' || key === '__proto__') continue;
     Object.defineProperty(out, key, {
       value: member,
       writable: true,

package/src/error-titles.ts

@@ -4,7 +4,7 @@
 // `index.ts` imports this bare, because `problemError` rebuilds a server's refusal by code and reads
 // its title from the registry; `errors.ts` and its two siblings import it bare as well.
 
-import { registerErrorCodes, registerErrorRetry } from '@ultimat3/core';
+import { registerErrorCodes, registerErrorRetry } from '@ultimat3/core/page';
 
 /**
  * Titles for the framework-wide code table — every one of them owned by this package.

package/src/errors-http.ts

@@ -5,7 +5,7 @@
  * these registers its title first.
  */
 
-import { renderCauseValue, UltimateError } from '@ultimat3/core';
+import { renderCauseValue, UltimateError } from '@ultimat3/core/page';
 import './error-titles';
 
 export class ActionHttpPathInvalidError extends UltimateError {