@ultimat3/action 7.0.0 → 8.0.0

package/CLAUDE.md

@@ -61,6 +61,21 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   author, and never reach the evaluation that had the row. `meta.policy` stays set — dropping
   it would read as "this action is unguarded" in `x routes` and the manifest. `http.test.ts`
   drives a row-level action over the real pipeline and counts the evaluations: exactly one.
+- **`meta.auth` is derived from a WALK of the policy tree**, never from the root combinator.
+  `def.policy.kind === 'allow'` answered `'required'` for `or(allow(), can('x:y'))`, so the
+  pipeline's `auth` stage 401'd an anonymous caller the policy itself ALLOWS — while the MCP tool
+  and the job handle let that caller through the same object. One policy, a different answer per
+  surface, which is the thing `enforcedBy: 'handler'` exists to prevent. `'public'` here is not
+  "unguarded": `invoke` still evaluates the policy for every call.
+  **`admitsAnonymous` is `@ultimat3/policy`'s** (`policy.ts`, beside `policyPermissions`) and
+  reaches this package through `policy-gate.ts` like every other authz question — never a copy
+  here. It cannot be one: `@ultimat3/query` needs the identical answer and is the same tier, so a
+  copy in either is a second answer for the other, and the walk is a property of the combinators
+  `policy.ts` declares. It is EXACT rather than heuristic — with `actor === null`, `can()`
+  short-circuits before its predicate and `allow()`/`deny()` ignore their arguments, so the tree
+  alone decides. `packages/policy/src/policy.test.ts` asserts it against
+  `policy.run({ actor: null })` itself, case for case; `http.test.ts` proves this projection reads
+  the answer, over the real pipeline.
 - **`stable.ts` holds the DOCUMENT form and NOTHING else, `As of 2026-08`.** `stableStringify` is
   published as `openapi.json` by `serializeOpenApi` and re-read with `JSON.parse` by
   `json-schema.ts`, so a non-finite number has to be `null` and a `Date` has to be its ISO string —
@@ -140,16 +155,25 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   What this does NOT close: an anonymous actor is one identity, so anonymous callers of a public
   idempotent action still share a key space — nothing at this tier can tell two apart, and keying
   on an IP or a cookie would break the retry the header exists to serve.
-- **Both stores FENCE a settlement on `in-flight`**, as `@ultimat3/jobs`' `SQL_ACK` fences on
-  `state = 'running'`. A reservation whose window lapsed is reclaimed by the next caller
-  (`on conflict … do update`), so a straggler from the first one used to overwrite a record it no
-  longer owned and the next replay answered a retry with a value produced for a different request.
-  Postgres fences in SQL and returns `key`, so the no-op is observable and logged; memory checks
-  the status it holds. It is logged and never thrown — a settlement is post-commit, so raising
-  there would turn a durable write into the caller's error. The fence is on the STATUS only: the
-  reservation's own `id` would close the last case (a straggler landing while the replacement is
-  still in flight) and cannot be checked, because `IdempotencyStore.settle(key, value)` is public
-  API and does not carry it.
+- **Both stores FENCE a settlement on the reservation `id` AND on `in-flight`**, as
+  `@ultimat3/jobs`' `SQL_ACK` fences on `id = $1 and state = 'running'`. A reservation whose window
+  lapsed is reclaimed by the next caller (`on conflict … do update`), so a straggler from the first
+  one used to overwrite a record it no longer owned and the next replay answered a retry with a
+  value produced for a different request. Postgres fences in SQL and returns `key`, so the no-op is
+  observable and logged; memory checks the id and status it holds. It is logged and never thrown —
+  a settlement is post-commit, so raising there would turn a durable write into the caller's error.
+  **The status alone was not enough**, which is why `settle(key, value, reservationId)` and
+  `fail(key, failure, reservationId)` carry the id: a reclaimed record is `in-flight` AGAIN, so a
+  straggler satisfied a status-only fence exactly and overwrote a LIVE reservation — and the
+  replacement's own settle was then fenced out. Public API, changed in the 8.0.0 major; callers
+  pass `reservation.record.id`, which `withIdempotency` already holds.
+- **A stored status is NARROWED, never cast.** `isIdempotencyStatus` decides, and an unknown word
+  is `X_IDEMPOTENCY_STATUS_UNKNOWN` at `toRecord`. `row.status as IdempotencyStatus` let one
+  through and `withIdempotency` has no branch for it: the record fell past `in-flight` and
+  `failed` and answered `{ value: null, replayed: true }` — "this already ran, here is its result"
+  — for a row nobody could read. The record was written by whatever build was deployed when the
+  first attempt ran, which on a rolling deploy is not this one. Same rule, same column shape, as
+  `@ultimat3/jobs`' `statusIn`.
 - **Where the idempotency records live is DECLARED, and refused at registration.**
   `IdempotencyStore.scope` says what a driver provides; `configureIdempotency({ scope })` says what
   the deployment requires; `assertIdempotencyScope` compares them inside `registerAction` — the

package/README.md

@@ -267,7 +267,16 @@ import {
   setIdempotencyStore,
 } from '@ultimat3/action';
 
-setIdempotencyStore(postgresIdempotencyStore({ executor: Bun.sql }));
+// 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({
+    executor: { query: (text, values) => client.query({ text, values }) },
+  }),
+);
 configureIdempotency({ scope: 'shared' });
 ```
 
@@ -296,6 +305,12 @@ const outcome = await withIdempotency(
 );
 ```
 
+`settle` and `fail` take the reservation's own id — `outcome`'s reservation, never the key alone.
+Both stores fence on it AND on `in-flight` `As of 2026-08`, the way `@ultimat3/jobs`' `SQL_ACK` fences on
+`id = $1 and state = 'running'`: a reservation whose window lapsed is reclaimed by the next caller,
+so a straggler from the first attempt satisfied a status-only fence exactly and overwrote a live
+reservation.
+
 A `query` has none and never will: a read has nothing to be idempotent about.
 
 ## `deprecated:` — a compat window, not a version
@@ -447,8 +462,9 @@ never a pass — the assertion says which code got in the way and names `input:`
 | `X_INPUT_INVALID` | input failed the Standard Schema | `x actions describe <name> --json` |
 | `X_IDEMPOTENCY_CONFLICT` | key reused with a new payload / still in flight | new key, or retry later |
 | `X_IDEMPOTENCY_KEY_INVALID` | `Idempotency-Key:` sent blank (`Headers.get()` answers `''`, not `null`) or past 255 characters | send one unique value per request, or omit the header |
-| `X_IDEMPOTENCY_NOT_SHARED` | `configureIdempotency({ scope: 'shared' })` over a per-process (or scope-less) store | install `postgresIdempotencyStore({ executor: Bun.sql })` at boot |
+| `X_IDEMPOTENCY_NOT_SHARED` | `configureIdempotency({ scope: 'shared' })` over a per-process (or scope-less) store | install `postgresIdempotencyStore({ executor })` at boot |
 | `X_IDEMPOTENCY_REPLAYED_FAILURE` | a retried key replays a first attempt that failed and carried no framework code of its own | read the first attempt, then send a fresh key |
+| `X_IDEMPOTENCY_STATUS_UNKNOWN` | `x_idempotency.status` holds a word this build has no branch for — written by a newer deploy | finish the rollout onto the build that writes it, then reconcile those requests — never DELETE the rows, which frees the key to run an already-committed action a second time |
 | `X_CONTRACT_DRIFT` | client/server build skew, missing spec entry | reload / `x verify --contract` |
 | `X_RPC_FAILED` | non-`problem+json` failure, or a body naming no `X_` code | check the gateway |
 | `X_ACTION_UNREGISTERED` | projected before `registerActions()` ran | register at boot |

package/package.json

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

package/src/errors-idempotency.ts

@@ -0,0 +1,147 @@
+/**
+ * The five idempotency failures, split out of `errors.ts` at its line ceiling. One subclass per
+ * stable code, exactly as there — the codes and their titles stay in `errors.ts`'s one
+ * `registerErrorCodes` call, because a second registration is how two modules end up deciding a
+ * title by load order.
+ */
+import { errorDocsUrl, renderCauseValue, UltimateError } from '@ultimat3/core';
+// Type-only: `idempotency.ts` imports the classes below, and a runtime edge here would close the
+// cycle. `verbatimModuleSyntax` is what makes that guarantee mechanical.
+import type { IdempotencyFailure } from './idempotency';
+
+// Core's spelling, aliased — never a second one, and the same alias `errors.ts` takes.
+const docs = errorDocsUrl;
+
+export type IdempotencyConflictReason = 'payload-mismatch' | 'in-flight';
+
+export class IdempotencyConflictError extends UltimateError {
+  constructor(key: string, reason: IdempotencyConflictReason) {
+    super({
+      code: 'X_IDEMPOTENCY_CONFLICT',
+      cause:
+        reason === 'payload-mismatch'
+          ? `idempotency key "${key}" was already used with a different payload`
+          : `idempotency key "${key}" is still in flight from an earlier request`,
+      // A paste-able call, the spelling `IdempotencyKeyInvalidError` already uses: both failures
+      // are the CLIENT's to act on, and one header built two ways is two ways to get it wrong.
+      fix:
+        reason === 'payload-mismatch'
+          ? 'set the Idempotency-Key header to a fresh crypto.randomUUID() — one key per payload, since this one already names a different request'
+          : 'resend this request with the same Idempotency-Key once the first one settles — a fresh crypto.randomUUID() here would run the mutation twice',
+      docs: docs('X_IDEMPOTENCY_CONFLICT'),
+    });
+  }
+}
+
+export type IdempotencyKeyProblem = 'empty' | 'too-long';
+
+/**
+ * The header arrived and cannot name one request. Refused, never read as absent: `Headers.get()`
+ * answers `''` for `Idempotency-Key:` rather than `null`, so a blank value became a live key that
+ * every caller sending a blank header shared — and reading it as "no key" is the quieter failure,
+ * because a client whose key interpolation produced nothing would lose the protection silently
+ * and double-charge on its own retry. `@ultimat3/jobs` refuses an empty key at the enqueue for the
+ * same reason; it uses `assert` because the empty key there is the app's own declaration, while
+ * this one is a caller's header and therefore a 4xx.
+ *
+ * The length bound is the one the OpenAPI operation has always published (`maxLength: 255`).
+ * A contract that disagrees with the runtime is worse than no contract.
+ */
+export class IdempotencyKeyInvalidError extends UltimateError {
+  constructor(action: string, problem: IdempotencyKeyProblem, length: number) {
+    super({
+      code: 'X_IDEMPOTENCY_KEY_INVALID',
+      cause:
+        problem === 'empty'
+          ? `action "${action}" was called with an empty Idempotency-Key, which every caller sending a blank header would share`
+          : `action "${action}" was called with an Idempotency-Key of ${length} characters, past the 255 its OpenAPI operation publishes`,
+      fix: 'set the Idempotency-Key header to a fresh crypto.randomUUID() on the client, one per request — or omit the header entirely to run this call without idempotency',
+      docs: docs('X_IDEMPOTENCY_KEY_INVALID'),
+      meta: { action, problem, length },
+    });
+  }
+}
+
+/**
+ * The deployment declared `scope: 'shared'` and the installed store cannot keep it. Refused at
+ * registration, before a socket opens, because the failure it replaces is silent and expensive:
+ * a per-process store under `replicas: 3` means the retry that lands on another replica finds no
+ * record, re-runs the handler, and charges the card again — with nothing anywhere saying it did.
+ * An UNDECLARED scope is refused the same way: what cannot be shown to be shared is not assumed
+ * to be, the rule `assertRouteBuckets` already applies to a limiter that publishes no table.
+ */
+export class IdempotencyNotSharedError extends UltimateError {
+  constructor(storeScope: string | undefined) {
+    super({
+      code: 'X_IDEMPOTENCY_NOT_SHARED',
+      cause:
+        storeScope === undefined
+          ? "configureIdempotency({ scope: 'shared' }) is declared and the installed idempotency store declares no scope"
+          : `configureIdempotency({ scope: 'shared' }) is declared and the installed idempotency store is ${storeScope}`,
+      // NOT `executor: Bun.sql` — `Bun.sql.query` is `undefined` (it is a tagged template whose
+      // positional form is `unsafe`), so that line compiled and would have thrown on the first
+      // reservation. The framework's own boot already installs this store; a host booting the
+      // framework itself wraps the client it opened.
+      fix: "the framework boot installs a shared store — reach this only from a host that boots it itself: setIdempotencyStore(postgresIdempotencyStore({ executor: { query: (text, values) => client.query({ text, values }) } })) from '@ultimat3/action', or drop the declaration to configureIdempotency({ scope: 'process' })",
+      docs: docs('X_IDEMPOTENCY_NOT_SHARED'),
+      meta: { storeScope: storeScope ?? null },
+    });
+  }
+}
+
+/**
+ * The replay of a first attempt that FAILED. It is a replay and not a re-run on purpose: `guard()`
+ * and the input parse both run before the idempotency gate, so everything the gate can see throw
+ * is post-authorization and possibly post-commit — a handler that took the money and then failed
+ * its own `output:` schema is the case this exists for. Releasing the reservation there let the
+ * client's automatic retry charge a second time, which made idempotency the cause of the double
+ * charge it exists to prevent.
+ *
+ * The first attempt's code is re-used verbatim, the way `RemoteActionError` re-uses the server's:
+ * the caller is owed the failure it would have got, not a new one. `X_IDEMPOTENCY_REPLAYED_FAILURE`
+ * is the code only when the original throw carried none of its own.
+ */
+export class IdempotencyReplayedFailureError extends UltimateError {
+  /** The recorded first attempt, so a caller reads the original code without parsing a message. */
+  readonly failure: IdempotencyFailure;
+
+  constructor(key: string, failure: IdempotencyFailure | undefined) {
+    const recorded: IdempotencyFailure = failure ?? {
+      code: 'X_IDEMPOTENCY_REPLAYED_FAILURE',
+      cause: 'the first attempt under this key failed and the store kept no detail of it',
+      fix: 'read the first attempt in the logs, then send a fresh Idempotency-Key once the cause is fixed',
+    };
+    super({
+      code: recorded.code,
+      cause: `${recorded.cause} — replayed from the first attempt under Idempotency-Key "${key}", which may have committed before it failed`,
+      fix: recorded.fix,
+      ...(recorded.docs === undefined ? {} : { docs: recorded.docs }),
+      // `replayed` is what tells an operator this is not a second execution: nothing ran here.
+      meta: { origin: 'idempotent-replay', key, replayed: true, code: recorded.code },
+    });
+    this.failure = recorded;
+  }
+}
+
+/**
+ * The stored record holds a status word this build has no branch for. Refused, never cast: with
+ * `row.status as IdempotencyStatus`, an unknown word fell through every branch of
+ * `withIdempotency` and answered `{ value: null, replayed: true }` — "this already ran, here is
+ * its result" — for a record nobody could read, which is the silent wrong answer idempotency
+ * exists to prevent. The mirror of `@ultimat3/jobs`' `X_JOB_ROW_STATUS_UNKNOWN`, for the same
+ * column shape and the same cause: the record was written by whatever build was deployed when the
+ * first attempt ran, which on a rolling deploy is not this one.
+ */
+export class IdempotencyStatusUnknownError extends UltimateError {
+  constructor(input: { key: string; value: unknown; known: readonly string[] }) {
+    super({
+      code: 'X_IDEMPOTENCY_STATUS_UNKNOWN',
+      cause:
+        `x_idempotency.status holds ${renderCauseValue(input.value)} for key "${input.key}", ` +
+        `which this build does not know — it reads ${input.known.join(', ')}`,
+      fix: `psql "$DATABASE_URL" -c "select key, status from x_idempotency where status not in ('in-flight', 'settled', 'failed')" # then drain the older processes: a status this build cannot read was written by a newer deploy`,
+      docs: docs('X_IDEMPOTENCY_STATUS_UNKNOWN'),
+      meta: { key: input.key, value: renderCauseValue(input.value), known: [...input.known] },
+    });
+  }
+}

package/src/errors.ts

@@ -1,6 +1,8 @@
 /**
  * Every failure @ultimat3/action can produce, one subclass per stable code so
  * callers `instanceof` a specific failure instead of string-matching a message.
+ * The idempotency five live in `errors-idempotency.ts` — this file reached the line ceiling —
+ * and are re-exported here, so `./errors` stays the one import path for all of them.
  */
 import {
   assertNever,
@@ -11,9 +13,17 @@ import {
   UltimateError,
 } from '@ultimat3/core';
 import type { SurfaceDenial } from '@ultimat3/policy';
-// Type-only: `idempotency.ts` imports the error classes below, and a runtime edge here would
-// close the cycle. `verbatimModuleSyntax` is what makes that guarantee mechanical.
-import type { IdempotencyFailure } from './idempotency';
+
+// Re-exported, not re-declared: the five idempotency failures moved to their own file when this
+// one reached the line ceiling, and every importer still reads them from `./errors`.
+export type { IdempotencyConflictReason, IdempotencyKeyProblem } from './errors-idempotency';
+export {
+  IdempotencyConflictError,
+  IdempotencyKeyInvalidError,
+  IdempotencyNotSharedError,
+  IdempotencyReplayedFailureError,
+  IdempotencyStatusUnknownError,
+} from './errors-idempotency';
 
 // Core's spelling, aliased — never a second one. A local template drifts from what
 // `x errors explain` prints the moment `ERROR_DOCS_BASE` moves.
@@ -41,6 +51,7 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
     'idempotency is declared fleet-wide and the installed store is per-process',
   X_IDEMPOTENCY_REPLAYED_FAILURE:
     'a retried Idempotency-Key replays a first attempt that failed after it may have committed',
+  X_IDEMPOTENCY_STATUS_UNKNOWN: 'an idempotency record holds a status this build cannot read',
   X_INPUT_INVALID: 'input failed schema validation',
   X_OUTPUT_INVALID: 'a handler returned a value its output schema rejects',
   X_RPC_FAILED: 'an RPC call failed without a problem+json body',
@@ -202,115 +213,6 @@ export class OutputInvalidError extends UltimateError {
   }
 }
 
-export type IdempotencyConflictReason = 'payload-mismatch' | 'in-flight';
-
-export class IdempotencyConflictError extends UltimateError {
-  constructor(key: string, reason: IdempotencyConflictReason) {
-    super({
-      code: 'X_IDEMPOTENCY_CONFLICT',
-      cause:
-        reason === 'payload-mismatch'
-          ? `idempotency key "${key}" was already used with a different payload`
-          : `idempotency key "${key}" is still in flight from an earlier request`,
-      fix:
-        reason === 'payload-mismatch'
-          ? 'send a fresh Idempotency-Key header for a different payload'
-          : 'retry the same Idempotency-Key after the first request settles',
-      docs: docs('X_IDEMPOTENCY_CONFLICT'),
-    });
-  }
-}
-
-export type IdempotencyKeyProblem = 'empty' | 'too-long';
-
-/**
- * The header arrived and cannot name one request. Refused, never read as absent: `Headers.get()`
- * answers `''` for `Idempotency-Key:` rather than `null`, so a blank value became a live key that
- * every caller sending a blank header shared — and reading it as "no key" is the quieter failure,
- * because a client whose key interpolation produced nothing would lose the protection silently
- * and double-charge on its own retry. `@ultimat3/jobs` refuses an empty key at the enqueue for the
- * same reason; it uses `assert` because the empty key there is the app's own declaration, while
- * this one is a caller's header and therefore a 4xx.
- *
- * The length bound is the one the OpenAPI operation has always published (`maxLength: 255`).
- * A contract that disagrees with the runtime is worse than no contract.
- */
-export class IdempotencyKeyInvalidError extends UltimateError {
-  constructor(action: string, problem: IdempotencyKeyProblem, length: number) {
-    super({
-      code: 'X_IDEMPOTENCY_KEY_INVALID',
-      cause:
-        problem === 'empty'
-          ? `action "${action}" was called with an empty Idempotency-Key, which every caller sending a blank header would share`
-          : `action "${action}" was called with an Idempotency-Key of ${length} characters, past the 255 its OpenAPI operation publishes`,
-      fix: 'set the Idempotency-Key header to a fresh crypto.randomUUID() on the client, one per request — or omit the header entirely to run this call without idempotency',
-      docs: docs('X_IDEMPOTENCY_KEY_INVALID'),
-      meta: { action, problem, length },
-    });
-  }
-}
-
-/**
- * The deployment declared `scope: 'shared'` and the installed store cannot keep it. Refused at
- * registration, before a socket opens, because the failure it replaces is silent and expensive:
- * a per-process store under `replicas: 3` means the retry that lands on another replica finds no
- * record, re-runs the handler, and charges the card again — with nothing anywhere saying it did.
- * An UNDECLARED scope is refused the same way: what cannot be shown to be shared is not assumed
- * to be, the rule `assertRouteBuckets` already applies to a limiter that publishes no table.
- */
-export class IdempotencyNotSharedError extends UltimateError {
-  constructor(storeScope: string | undefined) {
-    super({
-      code: 'X_IDEMPOTENCY_NOT_SHARED',
-      cause:
-        storeScope === undefined
-          ? "configureIdempotency({ scope: 'shared' }) is declared and the installed idempotency store declares no scope"
-          : `configureIdempotency({ scope: 'shared' }) is declared and the installed idempotency store is ${storeScope}`,
-      // NOT `executor: Bun.sql` — `Bun.sql.query` is `undefined` (it is a tagged template whose
-      // positional form is `unsafe`), so that line compiled and would have thrown on the first
-      // reservation. The framework's own boot already installs this store; a host booting the
-      // framework itself wraps the client it opened.
-      fix: "the framework boot installs a shared store — reach this only from a host that boots it itself: setIdempotencyStore(postgresIdempotencyStore({ executor: { query: (text, values) => client.query({ text, values }) } })) from '@ultimat3/action', or drop the declaration to configureIdempotency({ scope: 'process' })",
-      docs: docs('X_IDEMPOTENCY_NOT_SHARED'),
-      meta: { storeScope: storeScope ?? null },
-    });
-  }
-}
-
-/**
- * The replay of a first attempt that FAILED. It is a replay and not a re-run on purpose: `guard()`
- * and the input parse both run before the idempotency gate, so everything the gate can see throw
- * is post-authorization and possibly post-commit — a handler that took the money and then failed
- * its own `output:` schema is the case this exists for. Releasing the reservation there let the
- * client's automatic retry charge a second time, which made idempotency the cause of the double
- * charge it exists to prevent.
- *
- * The first attempt's code is re-used verbatim, the way `RemoteActionError` re-uses the server's:
- * the caller is owed the failure it would have got, not a new one. `X_IDEMPOTENCY_REPLAYED_FAILURE`
- * is the code only when the original throw carried none of its own.
- */
-export class IdempotencyReplayedFailureError extends UltimateError {
-  /** The recorded first attempt, so a caller reads the original code without parsing a message. */
-  readonly failure: IdempotencyFailure;
-
-  constructor(key: string, failure: IdempotencyFailure | undefined) {
-    const recorded: IdempotencyFailure = failure ?? {
-      code: 'X_IDEMPOTENCY_REPLAYED_FAILURE',
-      cause: 'the first attempt under this key failed and the store kept no detail of it',
-      fix: 'read the first attempt in the logs, then send a fresh Idempotency-Key once the cause is fixed',
-    };
-    super({
-      code: recorded.code,
-      cause: `${recorded.cause} — replayed from the first attempt under Idempotency-Key "${key}", which may have committed before it failed`,
-      fix: recorded.fix,
-      ...(recorded.docs === undefined ? {} : { docs: recorded.docs }),
-      // `replayed` is what tells an operator this is not a second execution: nothing ran here.
-      meta: { origin: 'idempotent-replay', key, replayed: true, code: recorded.code },
-    });
-    this.failure = recorded;
-  }
-}
-
 /**
  * A `deprecated:` block whose dates cannot become the headers it promises. Refused where the
  * declaration is converted, so the route and the OpenAPI operation refuse the same value — the

package/src/http.ts

@@ -25,7 +25,7 @@ import {
   schemaRef,
   toOperationId,
 } from './naming';
-import { policyCapability } from './policy-gate';
+import { admitsAnonymous, policyCapability } from './policy-gate';
 
 /** Matches `HttpConfig.buildIdHeader`; the pipeline reads it into `ctx.clientBuildId` — the
  * CLIENT's claim, never `ctx.buildId`, which is the build this process serves. */
@@ -86,9 +86,13 @@ export function toRoute(target: AnyAction): Route {
 
   const meta: RouteMeta = {
     name,
-    // `allow(...)` is the only way an action is public, and saying so explicitly is
-    // what keeps "forgot the policy" from ever looking like "meant to be public".
-    auth: def.policy.kind === 'allow' ? 'public' : 'required',
+    // Derived from a WALK of the policy tree, never from the root combinator alone. A saying that
+    // "`allow(...)` is the only way an action is public" is true of the leaf and was false of the
+    // read: `policy.kind === 'allow'` answered `required` for `or(allow(), can('x:y'))`, so the
+    // pipeline 401'd an anonymous caller the policy itself allows — while the MCP tool and the job
+    // handle let the same caller through the same object. `public` here is not "unguarded":
+    // `enforcedBy: 'handler'` below means `invoke` still evaluates the policy for every call.
+    auth: admitsAnonymous(def.policy) ? 'public' : 'required',
     policy: policyCapability(def.policy),
     // Named so the pipeline's authz stage stands down: `invoke` is this route's one
     // evaluation, and it is the only one that has run `row` by the time it decides. A

package/src/idempotency-memory.ts

@@ -81,28 +81,38 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
   }
 
   /**
-   * Both settlements are FENCED on `in-flight`, as `SQL_IDEMPOTENCY_SETTLE` is and as
-   * `@ultimat3/jobs`' `SQL_ACK` is: a record past the window is reclaimed by the next caller, so a
-   * straggler from the reservation before it would otherwise overwrite a record it no longer owns
-   * and the next replay would answer one request with another's value. Both stores fence, or the
-   * guarantee is whichever store the deployment happens to install.
+   * Both settlements are FENCED on the reservation's own `id` AND on `in-flight`, as
+   * `SQL_IDEMPOTENCY_SETTLE` is and as `@ultimat3/jobs`' `SQL_ACK` is. A record past the window is
+   * reclaimed by the next caller, so a straggler from the reservation before it would otherwise
+   * overwrite a record it no longer owns and the next replay would answer one request with
+   * another's value. The status alone does not catch it — the reclaimed record is `in-flight`
+   * again — which is why the id is half the fence. Both stores fence, or the guarantee is
+   * whichever store the deployment happens to install.
    */
-  settle(key: string, value: unknown): Promise<void> {
-    const existing = this.#records.get(key);
-    if (existing?.status === 'in-flight') {
+  settle(key: string, value: unknown, reservationId: string): Promise<void> {
+    const existing = this.#owned(key, reservationId);
+    if (existing !== undefined) {
       this.#records.set(key, { ...existing, status: 'settled', value });
     }
     return Promise.resolve();
   }
 
-  fail(key: string, failure: IdempotencyFailure): Promise<void> {
-    const existing = this.#records.get(key);
-    if (existing?.status === 'in-flight') {
+  fail(key: string, failure: IdempotencyFailure, reservationId: string): Promise<void> {
+    const existing = this.#owned(key, reservationId);
+    if (existing !== undefined) {
       this.#records.set(key, { ...existing, status: 'failed', value: undefined, failure });
     }
     return Promise.resolve();
   }
 
+  /** The record this reservation may still write, or nothing — the fence, in one place. */
+  #owned(key: string, reservationId: string): IdempotencyRecord | undefined {
+    const existing = this.#records.get(key);
+    if (existing === undefined) return undefined;
+    if (existing.status !== 'in-flight' || existing.id !== reservationId) return undefined;
+    return existing;
+  }
+
   release(key: string): Promise<void> {
     this.#records.delete(key);
     return Promise.resolve();

package/src/idempotency-postgres.ts

@@ -5,14 +5,15 @@
  * Statements are spelled out so an agent can run the exact one it saw in a log.
  */
 import { logger, uuid } from '@ultimat3/core';
+import { IdempotencyStatusUnknownError } from './errors';
 import type {
   IdempotencyFailure,
   IdempotencyRecord,
   IdempotencyReservation,
   IdempotencyScope,
-  IdempotencyStatus,
   IdempotencyStore,
 } from './idempotency';
+import { IDEMPOTENCY_STATUSES, isIdempotencyStatus } from './idempotency';
 import { DEFAULT_IDEMPOTENCY_WINDOW_MS } from './idempotency-memory';
 
 /**
@@ -82,22 +83,26 @@ select key, id, request_hash, status, value, failure,
 `;
 
 /**
- * `and status = 'in-flight'` is a FENCE, not a filter — the one `@ultimat3/jobs`' `SQL_ACK` carries
- * as `and state = 'running'`, for the same failure. A reservation whose window lapsed is reclaimed
- * by the next caller (`do update` above), so a straggler from the first one arriving afterwards
- * overwrote a record it no longer owned: the next replay under that key answered a retry with a
- * value produced for a different request. `returning key` is what makes the refusal observable —
- * an update matching no row is indistinguishable from one that matched, otherwise.
+ * `and id = $3 and status = 'in-flight'` is a FENCE, not a filter — the one `@ultimat3/jobs`'
+ * `SQL_ACK` carries as `where id = $1 and state = 'running'`, for the same failure. A reservation
+ * whose window lapsed is reclaimed by the next caller (`do update` above), so a straggler from the
+ * first one arriving afterwards overwrote a record it no longer owned: the next replay under that
+ * key answered a retry with a value produced for a different request.
+ *
+ * BOTH halves, because either alone leaves a case open. The status alone misses the reclaimed
+ * record — it is `in-flight` again, belonging to someone else — and the id alone would let a
+ * straggler overwrite a record its own attempt had already settled. `returning key` is what makes
+ * the refusal observable: an update matching no row is indistinguishable from one that matched.
  */
 export const SQL_IDEMPOTENCY_SETTLE = `
 update x_idempotency set status = 'settled', value = $2::jsonb, failure = null
- where key = $1 and status = 'in-flight'
+ where key = $1 and id = $3::uuid and status = 'in-flight'
 returning key
 `;
 
 export const SQL_IDEMPOTENCY_FAIL = `
 update x_idempotency set status = 'failed', value = null, failure = $2::jsonb
- where key = $1 and status = 'in-flight'
+ where key = $1 and id = $3::uuid and status = 'in-flight'
 returning key
 `;
 
@@ -121,6 +126,12 @@ interface IdempotencyRow {
 export interface PostgresIdempotencyStoreOptions {
   readonly executor: PgExecutor;
   readonly windowMs?: number | undefined;
+  /**
+   * Injectable, exactly as `MemoryIdempotencyStoreOptions.now` is. The two stores are one seam and
+   * a caller must be able to drive either from the same clock; a hardcoded `Date.now()` here made
+   * the one record this store stamps itself untestable and unfreezable.
+   */
+  readonly now?: (() => number) | undefined;
 }
 
 export interface PostgresIdempotencyStore extends IdempotencyStore {
@@ -164,6 +175,7 @@ export function postgresIdempotencyStore(
   const windowMs = Math.max(1, Math.floor(options.windowMs ?? DEFAULT_IDEMPOTENCY_WINDOW_MS));
   const windowSecs = windowMs / 1000;
   const exec = options.executor;
+  const now = options.now ?? ((): number => Date.now());
 
   const fetch = async (key: string): Promise<IdempotencyRecord | undefined> => {
     const rows = await exec.query<IdempotencyRow>(SQL_IDEMPOTENCY_GET, [key, windowSecs]);
@@ -200,20 +212,28 @@ export function postgresIdempotencyStore(
           requestHash,
           status: 'in-flight',
           value: undefined,
-          createdAt: Date.now(),
+          createdAt: now(),
         },
         created: false,
       };
     },
 
-    async settle(key, value): Promise<void> {
-      const rows = await exec.query(SQL_IDEMPOTENCY_SETTLE, [key, JSON.stringify(value ?? null)]);
-      fenced(rows, key, 'settle');
+    async settle(key, value, reservationId): Promise<void> {
+      const rows = await exec.query(SQL_IDEMPOTENCY_SETTLE, [
+        key,
+        JSON.stringify(value ?? null),
+        reservationId,
+      ]);
+      fenced(rows, key, reservationId, 'settle');
     },
 
-    async fail(key, failure: IdempotencyFailure): Promise<void> {
-      const rows = await exec.query(SQL_IDEMPOTENCY_FAIL, [key, JSON.stringify(failure)]);
-      fenced(rows, key, 'fail');
+    async fail(key, failure: IdempotencyFailure, reservationId): Promise<void> {
+      const rows = await exec.query(SQL_IDEMPOTENCY_FAIL, [
+        key,
+        JSON.stringify(failure),
+        reservationId,
+      ]);
+      fenced(rows, key, reservationId, 'fail');
     },
 
     async release(key): Promise<void> {
@@ -238,18 +258,36 @@ export function postgresIdempotencyStore(
  * store that refuses. An operator still has to see it: a fenced settle means this attempt's record
  * belongs to another reservation, and the value this attempt produced is stored nowhere.
  */
-function fenced(rows: readonly unknown[], key: string, statement: 'settle' | 'fail'): void {
+function fenced(
+  rows: readonly unknown[],
+  key: string,
+  reservationId: string,
+  statement: 'settle' | 'fail',
+): void {
   if (rows.length > 0) return;
-  logger.warn('action.idempotency.settlement-fenced', { key, statement });
+  logger.warn('action.idempotency.settlement-fenced', { key, reservationId, statement });
 }
 
+/**
+ * The narrowing, never a cast. `row.status as IdempotencyStatus` let an unknown word through, and
+ * `withIdempotency` has no branch for one: it fell past `in-flight` and `failed` and answered
+ * `{ value: null, replayed: true }` — "this already ran, here is its result" — for a record nobody
+ * could read. The rule `@ultimat3/jobs`' `statusIn` already writes out for the same column.
+ */
 function toRecord(row: IdempotencyRow): IdempotencyRecord {
   const failure = toFailure(row.failure);
+  if (!isIdempotencyStatus(row.status)) {
+    throw new IdempotencyStatusUnknownError({
+      key: row.key,
+      value: row.status,
+      known: IDEMPOTENCY_STATUSES,
+    });
+  }
   return {
     id: row.id,
     key: row.key,
     requestHash: row.request_hash,
-    status: row.status as IdempotencyStatus,
+    status: row.status,
     value: row.value,
     ...(failure === undefined ? {} : { failure }),
     createdAt: Number(row.created_at),

package/src/idempotency.ts

@@ -32,7 +32,27 @@ export interface IdempotencyFailure {
   readonly docs?: string | undefined;
 }
 
-export type IdempotencyStatus = 'in-flight' | 'settled' | 'failed';
+/**
+ * The closed list, in the order a record moves through it — and the ONE declaration. The type is
+ * derived from it below rather than restated beside it, so a fourth status cannot be added to one
+ * and missed by the other, which is exactly how `isIdempotencyStatus` would start refusing a word
+ * this build writes itself.
+ */
+export const IDEMPOTENCY_STATUSES = Object.freeze(['in-flight', 'settled', 'failed'] as const);
+
+export type IdempotencyStatus = (typeof IDEMPOTENCY_STATUSES)[number];
+
+/**
+ * The one narrowing for the status column, and never a cast. A record crosses a process boundary —
+ * the row under this key was written by whatever build was deployed when the first attempt ran,
+ * which on a rolling deploy is not this one — so `row.status as IdempotencyStatus` made an unknown
+ * word answer `{ value: null, replayed: true }` in `withIdempotency`: the caller was told "this
+ * already ran, here is its result" for a row nobody could read. The rule `@ultimat3/jobs`'
+ * `statusIn` already writes out for the same column in the same situation.
+ */
+export function isIdempotencyStatus(value: string): value is IdempotencyStatus {
+  return (IDEMPOTENCY_STATUSES as readonly string[]).includes(value);
+}
 
 export interface IdempotencyRecord {
   readonly id: string;
@@ -68,14 +88,29 @@ export interface IdempotencyStore {
   readonly windowMs?: number | undefined;
   /** Atomically create-or-fetch the record for `key`. The atomicity is the point. */
   reserve(key: string, requestHash: string): Promise<IdempotencyReservation>;
-  settle(key: string, value: unknown): Promise<void>;
+  /**
+   * Settle the record `reservationId` owns — `IdempotencyReservation.record.id`, never the key
+   * alone. Fenced on the id AND the status, the way `@ultimat3/jobs`' `SQL_ACK` fences on
+   * `id = $1 and state = 'running'`.
+   *
+   * The status alone was not enough, and the gap it left is silent: a reservation whose window
+   * lapsed is reclaimed by the next caller, so the record under that key is `in-flight` AGAIN and
+   * belongs to someone else. A straggler from the first attempt satisfied the status fence
+   * exactly, overwrote a live reservation, and the replacement's own settle was then fenced out —
+   * so the retry replayed a value produced for a different request. A settlement that matches no
+   * record is logged, never thrown: it lands after the handler has committed.
+   */
+  settle(key: string, value: unknown, reservationId: string): Promise<void>;
   /**
    * Settle a FAILURE, so the retry replays it instead of re-running a handler that may already
-   * have committed. Optional so an existing store still type-checks — and when it is absent the
-   * gate leaves the reservation standing rather than releasing it, because refusing the retry is
-   * the safe answer and re-running it is the double charge.
+   * have committed. Fenced on the same reservation id as `settle`, for the same case — a
+   * straggler's failure marking a live reservation `failed` is the worse half of it.
+   *
+   * Optional so an existing store still type-checks — and when it is absent the gate leaves the
+   * reservation standing rather than releasing it, because refusing the retry is the safe answer
+   * and re-running it is the double charge.
    */
-  fail?(key: string, failure: IdempotencyFailure): Promise<void>;
+  fail?(key: string, failure: IdempotencyFailure, reservationId: string): Promise<void>;
   /** Drop a reservation, so a retry can run. Only ever correct BEFORE the handler starts. */
   release(key: string): Promise<void>;
   get(key: string): Promise<IdempotencyRecord | undefined>;
@@ -176,13 +211,16 @@ export async function withIdempotency<T>(
   try {
     value = await run();
   } catch (error) {
-    await settleFailure(store, key, error);
+    await settleFailure(store, key, record.id, error);
     throw error;
   }
   // Outside the `try` on purpose: a `settle` that refuses is itself post-commit, and the record
   // stays in flight rather than being released — a retry then gets a 409 it can act on instead of
   // re-running a handler that has already committed.
-  await store.settle(key, value);
+  //
+  // `record.id` is THIS reservation's, so a straggler from an attempt whose window has since
+  // lapsed cannot land on the replacement that reclaimed the key.
+  await store.settle(key, value, record.id);
   return { value, replayed: false };
 }
 
@@ -191,7 +229,12 @@ export async function withIdempotency<T>(
  * here would otherwise surface as the caller's error, hiding the `X_OUTPUT_INVALID` or the
  * handler's own throw that is the thing worth reading — the same rule `auditThrew` follows.
  */
-async function settleFailure(store: IdempotencyStore, key: string, error: unknown): Promise<void> {
+async function settleFailure(
+  store: IdempotencyStore,
+  key: string,
+  reservationId: string,
+  error: unknown,
+): Promise<void> {
   if (store.fail === undefined) {
     // Deliberately NOT `release`. A store with no failure slot cannot say "this already ran", and
     // the retry-safe reading of that is "refuse the retry", not "run it again".
@@ -199,7 +242,7 @@ async function settleFailure(store: IdempotencyStore, key: string, error: unknow
     return;
   }
   try {
-    await store.fail(key, failureOf(error));
+    await store.fail(key, failureOf(error), reservationId);
   } catch (sinkError) {
     // Never the error's own text: rendering an `unknown` into a message is the second throw this
     // branch exists to prevent. The logger takes it as a field and shapes it itself.

package/src/index.ts

@@ -82,6 +82,7 @@ export {
   IdempotencyKeyInvalidError,
   IdempotencyNotSharedError,
   IdempotencyReplayedFailureError,
+  IdempotencyStatusUnknownError,
   InputInvalidError,
   OutputInvalidError,
   RemoteActionError,
@@ -116,7 +117,9 @@ export {
   configureIdempotency,
   DEFAULT_IDEMPOTENCY_CONFIG,
   getIdempotencyStore,
+  IDEMPOTENCY_STATUSES,
   idempotencyConfig,
+  isIdempotencyStatus,
   resetIdempotency,
   setIdempotencyStore,
   withIdempotency,
@@ -174,8 +177,19 @@ export { derivePath, inputSchemaName, outputSchemaName, pluralize } from './nami
 export type { BuildOpenApiOptions, OpenApiDocument, OpenApiInfo } from './openapi';
 export { buildOpenApi, serializeOpenApi } from './openapi';
 export type { ActionPolicy, PolicySubject, Surface } from './policy-gate';
-/** `policyCapability` is the display label; `policyPermissions` is what a report MATCHES on. */
-export { actorOf, guard, policyCapability, policyPermissions } from './policy-gate';
+/**
+ * `policyCapability` is the display label; `policyPermissions` is what a report MATCHES on.
+ * `admitsAnonymous` is `@ultimat3/policy`'s, re-exported here beside them: it is what `toRoute`
+ * derives `meta.auth` from, so a plain `route` sets that field from the same walk rather than
+ * re-reading the root combinator.
+ */
+export {
+  actorOf,
+  admitsAnonymous,
+  guard,
+  policyCapability,
+  policyPermissions,
+} from './policy-gate';
 export {
   describeActions,
   getAction,

package/src/policy-gate.ts

@@ -7,7 +7,11 @@
 import type { Actor, Ctx } from '@ultimat3/core';
 import { assertNever, isAnonymous } from '@ultimat3/core';
 import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
-import { enforce, policyPermissions as flattenedPermissions } from '@ultimat3/policy';
+import {
+  enforce,
+  policyPermissions as flattenedPermissions,
+  admitsAnonymous as policyAdmitsAnonymous,
+} from '@ultimat3/policy';
 import { ActionDeniedError } from './errors';
 
 /**
@@ -91,3 +95,16 @@ export function policyCapability(policy: ActionPolicy): string {
 export function policyPermissions(policy: ActionPolicy): readonly string[] {
   return flattenedPermissions(policy);
 }
+
+/**
+ * Whether a policy admits an ANONYMOUS caller — `@ultimat3/policy`'s answer, re-exported here so
+ * `http.ts` reads it through this file like every other authz question. `toRoute` derives
+ * `meta.auth` from it, never from `policy.kind === 'allow'`: that read looked at the ROOT
+ * combinator only, so `or(allow(), can('x:y'))` was 401'd by the pipeline before `invoke` ran
+ * while the MCP tool and the job handle allowed it. `true` is not "unguarded" — `invoke` still
+ * evaluates the policy for every call. Declared once in `policy.ts`, exactly as
+ * `policyPermissions` is: the answer is a property of the combinators it walks.
+ */
+export function admitsAnonymous(policy: ActionPolicy): boolean {
+  return policyAdmitsAnonymous(policy);
+}

package/src/sample-input.ts

@@ -75,13 +75,25 @@ function sampleNumber(node: SchemaNode): number {
   return node.integer === true ? Math.floor(node.maximum) : node.maximum;
 }
 
+/**
+ * `Object.create(null)`, the shape `@ultimat3/schema`'s own object check already builds: on a `{}`
+ * literal `sample['__proto__'] = value` reaches `Object.prototype`'s SETTER, so a required field
+ * named `__proto__` never became an own key and REPLACED the sample's prototype instead. The
+ * payload then failed the very schema it was derived from, and the contract test reported the
+ * action as drifted. A field can carry that name through any computed key
+ * (`t.object({ [name]: t.string })`) or a provider whose IR was parsed from JSON.
+ *
+ * The read is guarded for the same reason `patternAt` guards its own: `requiredKeys` happens to
+ * answer own keys only (`Object.entries`), so this is the invariant stated locally rather than
+ * borrowed from a function two packages away.
+ */
 function sampleObject(node: SchemaNode): Record<string, unknown> {
   const properties = node.properties ?? {};
-  const sample: Record<string, unknown> = {};
+  const sample: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
   // Required-only is what "minimal" means: an optional key and a defaulted one are both
   // absences the schema already accepts, so adding them would only widen what can go wrong.
   for (const key of requiredKeys(node)) {
-    const child = properties[key];
+    const child = Object.hasOwn(properties, key) ? properties[key] : undefined;
     if (child !== undefined) sample[key] = sampleFor(child);
   }
   return sample;
@@ -157,7 +169,7 @@ function gapsIn(node: SchemaNode, path: string): string[] {
     const properties = node.properties ?? {};
     const out: string[] = [];
     for (const key of requiredKeys(node)) {
-      const child = properties[key];
+      const child = Object.hasOwn(properties, key) ? properties[key] : undefined;
       if (child !== undefined) out.push(...gapsIn(child, path === '' ? key : `${path}.${key}`));
     }
     return out;