@ultimat3/action 23.0.0 → 25.0.0

package/src/idempotency.ts

@@ -9,8 +9,10 @@ import {
   IdempotencyConflictError,
   IdempotencyNotSharedError,
   IdempotencyReplayedFailureError,
+  IdempotentReplayRedactedError,
 } from './errors';
-import { MemoryIdempotencyStore } from './idempotency-memory';
+import { memoryIdempotencyStore } from './idempotency-memory';
+import { restingAnswer } from './idempotency-redact';
 
 /**
  * Where a store's records live. Declared by the driver, never inferred — the same rule
@@ -68,6 +70,12 @@ export interface IdempotencyRecord {
   readonly value: unknown;
   /** Present exactly when `status === 'failed'` — what the replay re-throws. */
   readonly failure?: IdempotencyFailure | undefined;
+  /**
+   * True when `value` had a field redacted at rest (`idempotency-redact.ts`). Its replay is
+   * `X_IDEMPOTENT_REPLAY_REDACTED`, decided by this flag — never by scanning the value for
+   * `[redacted]`, a string a legitimate answer may hold. Absent or false: replayed as stored.
+   */
+  readonly redacted?: boolean | undefined;
   /** Epoch milliseconds. The store's own dedupe window is measured from here. */
   readonly createdAt: number;
 }
@@ -91,6 +99,14 @@ export interface IdempotencyStore {
    * is one immortal entry per write, forever.
    */
   readonly windowMs?: number | undefined;
+  /**
+   * The store's declaration that it keeps `settle`'s `redacted` flag and hands it back as
+   * `IdempotencyRecord.redacted` (#591). REQUIRED, and a literal: a store written before answers
+   * were redacted at rest drops the flag and would replay `[redacted]` as the answer, and a
+   * required parameter alone cannot refuse it — TypeScript accepts an implementation with fewer
+   * parameters. Without this member, such a store is a build error (`type-pins.ts`).
+   */
+  readonly keepsRedaction: true;
   /** Atomically create-or-fetch the record for `key`. The atomicity is the point. */
   reserve(key: string, requestHash: string): Promise<IdempotencyReservation>;
   /**
@@ -104,8 +120,13 @@ export interface IdempotencyStore {
    * 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.
+   *
+   * `value` is already the RESTING copy — `withIdempotency` redacts before it calls, so no store
+   * ever receives a credential. `redacted` says it did, and a store MUST keep it and hand it back
+   * as `IdempotencyRecord.redacted`: one that drops it replays `[redacted]` as the answer. Required
+   * of every caller, so a store that wraps another cannot drop it on the way through.
    */
-  settle(key: string, value: unknown, reservationId: string): Promise<void>;
+  settle(key: string, value: unknown, reservationId: string, redacted: boolean): Promise<void>;
   /**
    * Settle a FAILURE, so the retry replays it instead of re-running a handler that may already
    * have committed. Fenced on the same reservation id as `settle`, for the same case — a
@@ -136,7 +157,7 @@ export interface IdempotencyConfig {
 export const DEFAULT_IDEMPOTENCY_CONFIG: IdempotencyConfig = Object.freeze({ scope: 'process' });
 
 let config: IdempotencyConfig = DEFAULT_IDEMPOTENCY_CONFIG;
-let defaultStore: IdempotencyStore = new MemoryIdempotencyStore();
+let defaultStore: IdempotencyStore = memoryIdempotencyStore();
 
 /** Declared at boot, before `registerActions()`. Nothing infers a replica count. */
 export function configureIdempotency(next: IdempotencyConfig): void {
@@ -158,7 +179,7 @@ export function getIdempotencyStore(): IdempotencyStore {
 /** Test-only. A process configures its idempotency once at boot and never reconfigures it. */
 export function resetIdempotency(): void {
   config = DEFAULT_IDEMPOTENCY_CONFIG;
-  defaultStore = new MemoryIdempotencyStore();
+  defaultStore = memoryIdempotencyStore();
 }
 
 /**
@@ -190,19 +211,30 @@ export interface IdempotentOutcome<T> {
  * X_IDEMPOTENCY_CONFLICT for a payload mismatch, X_IDEMPOTENCY_CONFLICT for a duplicate still in
  * flight.
  *
- * **Everything `run()` throws is treated as possibly-committed.** `guard()` and `validateInput`
+ * **Everything `run()` throws is treated as possibly-committed.** `guardAction()` and `validateInput`
  * both run before this gate is reached (`invoke.ts`), so by the time `run` is called the only
  * things left are the handler and `validateOutput` — and the second of those throws *after* the
  * first has committed. Releasing the reservation there is what turned a rounding change in an
  * output schema into a second charge: `X_OUTPUT_INVALID` dropped the record, and the client's
  * automatic retry re-ran a handler that had already taken the money. So the failure is SETTLED
- * and replayed, and `release` is reserved for a pre-handler failure — of which this gate has none.
+ * and replayed, and `release` is reserved for a pre-handler failure — `beforeRun` is the only one.
  */
+export interface WithIdempotencyOptions {
+  /**
+   * Called only for a reservation this call CREATED, before `run` — `invoke`'s rate-limit spend
+   * for a key its pre-parse peek took for a replay (a stale record reclaimed in between). A throw
+   * here is a PRE-handler failure, so the reservation is released, never settled: a refusal is not
+   * the key's outcome, and a retry once the bucket refills must still be able to run.
+   */
+  readonly beforeRun?: () => Promise<void>;
+}
+
 export async function withIdempotency<T>(
   store: IdempotencyStore,
   key: string,
   input: unknown,
   run: () => Promise<T>,
+  options: WithIdempotencyOptions = {},
 ): Promise<IdempotentOutcome<T>> {
   const requestHash = keyedFingerprint(input, IDEMPOTENCY_FINGERPRINT_PURPOSE);
   const { record, created } = await store.reserve(key, requestHash);
@@ -210,9 +242,20 @@ export async function withIdempotency<T>(
   if (!created) {
     if (record.status === 'in-flight') throw new IdempotencyConflictError(key, 'in-flight');
     if (record.status === 'failed') throw new IdempotencyReplayedFailureError(key, record.failure);
+    // The stored value lost a credential at rest: serving it would hand `[redacted]` back as the
+    // answer, so the replay is refused — and, like any replay, spends and runs nothing.
+    if (record.redacted === true) throw new IdempotentReplayRedactedError(key);
     // The stored value is the previous return of this very handler.
     return { value: record.value as T, replayed: true };
   }
+  if (options.beforeRun !== undefined) {
+    try {
+      await options.beforeRun();
+    } catch (error) {
+      await store.release(key);
+      throw error;
+    }
+  }
   let value: T;
   try {
     value = await run();
@@ -226,7 +269,15 @@ export async function withIdempotency<T>(
   //
   // `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);
+  //
+  // Inside a transaction the shared store settles on that transaction's connection, so "settled"
+  // and "the write is durable" are one COMMIT — and a settle that lost its reservation THROWS
+  // (`X_IDEMPOTENCY_RESERVATION_LOST`), which is the rollback of an attempt a retry replaced.
+  //
+  // The CALLER gets `value` whole; the store gets the resting copy, so an answer carrying a
+  // credential is never written down in plaintext for the window (#591).
+  const resting = restingAnswer(value);
+  await store.settle(key, resting.value, record.id, resting.redacted);
   return { value, replayed: false };
 }
 

package/src/index.ts

@@ -7,38 +7,18 @@
  * framework died; there is exactly one here, structurally.
  */
 
+// Imported bare, and the one module `sideEffects` lists: a browser that rebuilds a SERVER's refusal
+// (`problemError`, by code) constructs nothing from `errors.ts`, and still has to render the title
+// this package registered. `SIDE_EFFECTS_ANCHORS` carries the argument and `bun run side-effects`
+// enforces it.
+import './error-titles';
+
 /**
- * Flight control for the typed client, and OPT-IN by construction: `client.ts` names `ClientFlight`
- * as a TYPE only, so a caller that never mentions `createClientFlight` pays nothing for the fence,
- * the dedup map or the retry loop. Every mechanism underneath is `@ultimat3/core`'s — one fence,
- * one flight map, one gate, one backoff curve for the whole framework — and so is the pipeline
- * itself: it shipped as a byte-identical copy here and in `@ultimat3/query`, and
- * two tier-3 packages may not import each other, so the one copy lives at tier 0.
- *
- * Re-exported rather than re-declared, so every name is importable from this package exactly as
- * before. `isSuperseded` is core's too: reading a fenced answer is the point of installing a
- * flight, and it should not cost a second import.
- */
-export type {
-  ClientFlight,
-  ClientFlightOptions,
-  ClientRetry,
-  FlightKeyOptions,
-  FlightPlan,
-  WireAnswer,
-} from '@ultimat3/core';
-export {
-  createClientFlight,
-  DEFAULT_CLIENT_RETRY,
-  isSuperseded,
-  isTransientFailure,
-} from '@ultimat3/core';
-/**
- * `toBucket` is `@ultimat3/http`'s — http owns `Bucket` and the limiter maths, and `action` and
- * `query` are the same tier, so a copy in either is a second answer for the other. Re-exported
- * here, not re-implemented, so an action file still reaches it through one import.
+ * Types only: the barrel's own declarations name them. Flight control's VALUES are imported from
+ * `@ultimat3/core`, which holds the one pipeline for action and query alike; a value re-export
+ * here is `X_HELPER_COPY`.
  */
-export { toBucket } from '@ultimat3/http';
+export type { ClientFlight, ClientRetry, PgExecutor } from '@ultimat3/core';
 /** Re-exported so an `action` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
@@ -54,7 +34,6 @@ export type {
   ActionRowArgs,
   AnyAction,
   InvokeOptions,
-  McpAnnotationHints,
   McpDescriptorMeta,
 } from './action';
 export { action, describeAction, isAction } from './action';
@@ -73,25 +52,21 @@ export { apiDeclaration } from './api-declaration';
 /**
  * The audit seam. `AuditSink` is the whole extension point: the framework supplies the record
  * and never the row. `audit-gate.ts` stays unexported — the sink has one caller, and that
- * absence is what keeps it one.
+ * absence is what keeps it one. The record and the sink are `@ultimat3/core`'s, re-exported as
+ * TYPES only because this barrel's sinks name them; the slot (`setAuditSink`) is core's alone.
  */
-export type {
-  AuditFailure,
-  AuditOutcome,
-  AuditRecord,
-  AuditSink,
-} from './audit';
-export { getAuditSink, resetAuditSink, setAuditSink } from './audit';
+export type { AuditRecord, AuditSink } 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.
+ * The DURABLE sink, and the only one an app that must keep its trail may install. The table's DDL
+ * is exported beside it because the table is applied the way `SQL_IDEMPOTENCY_TABLE` is — by the
+ * boot, never by an app migration. The insert is not: it is the sink's own statement, and an
+ * export with no reader outside this package is `X_SQL_EXPORT_UNREAD` (`bun run sql-export-readers`).
  */
 export type { PostgresAuditSink, PostgresAuditSinkOptions } from './audit-postgres';
-export { postgresAuditSink, SQL_AUDIT_INSERT, SQL_AUDIT_TABLE } from './audit-postgres';
+export { postgresAuditSink, SQL_AUDIT_TABLE } from './audit-postgres';
 export type {
   ActionLike,
   ActionMap,
@@ -106,14 +81,6 @@ export type { ContractTest, ContractTestOptions } from './contract-test';
 export { anonymousCtx, contractTestsFor, policyTestStubFor } from './contract-test';
 export type { Api, ApiDef, ApiModule, ApiModules } from './define-api';
 export { defineApi } from './define-api';
-/**
- * The compat window a retirement gets. Versioning itself is NOT here and never will be: two
- * versions of one action side by side is two deployments behind one ingress (axiom 7), not a
- * router feature. `renderDeprecation` is exported so a plain `route` can announce the same pair
- * of headers the action projection does.
- */
-export type { Deprecation, DeprecationField, DeprecationRender } from './deprecation';
-export { recordDeprecatedCall, renderDeprecation } from './deprecation';
 export type { IdempotencyConflictReason, IdempotencyKeyProblem, RemoteFailure } from './errors';
 export {
   ActionDeniedError,
@@ -130,8 +97,11 @@ export {
   IdempotencyKeyInvalidError,
   IdempotencyNotSharedError,
   IdempotencyReplayedFailureError,
+  IdempotencyReservationLostError,
   IdempotencyStatusUnknownError,
+  IdempotentReplayRedactedError,
   InputInvalidError,
+  MutatorNotIdempotentError,
   OutputInvalidError,
   RemoteActionError,
   RpcFailedError,
@@ -143,8 +113,6 @@ export {
 } from './errors-http';
 export type { OpenApiOperation } from './http';
 export {
-  BUILD_ID_HEADER,
-  IDEMPOTENCY_HEADER,
   operationTagOf,
   REPLAYED_HEADER,
   toOpenApiOperation,
@@ -183,40 +151,27 @@ export {
   withIdempotency,
 } from './idempotency';
 export { idempotencyKeyFor, MAX_IDEMPOTENCY_KEY_LENGTH } from './idempotency-key';
-export type { MemoryIdempotencyStoreOptions } from './idempotency-memory';
+export type {
+  MemoryIdempotencyStore,
+  MemoryIdempotencyStoreOptions,
+} from './idempotency-memory';
 export {
   DEFAULT_IDEMPOTENCY_WINDOW_MS,
   DEFAULT_MAX_IDEMPOTENCY_KEYS,
-  MemoryIdempotencyStore,
+  memoryIdempotencyStore,
 } from './idempotency-memory';
-/**
- * The SHARED store, and the only one an app running more than one replica may install. The
- * statements are exported beside it because the table is applied the way `SQL_JOBS_TABLE` is —
- * by `x db up` in development and by the release-phase `ROLE=migrate` in production.
- */
 export type {
-  PgExecutor,
   PostgresIdempotencyStore,
   PostgresIdempotencyStoreOptions,
 } from './idempotency-postgres';
-export {
-  postgresIdempotencyStore,
-  SQL_IDEMPOTENCY_FAIL,
-  SQL_IDEMPOTENCY_GET,
-  SQL_IDEMPOTENCY_PURGE,
-  SQL_IDEMPOTENCY_RELEASE,
-  SQL_IDEMPOTENCY_RESERVE,
-  SQL_IDEMPOTENCY_SETTLE,
-  SQL_IDEMPOTENCY_TABLE,
-} from './idempotency-postgres';
+/** The table's DDL alone: the boot applies it. The store's own statements stay its own. */
+export { postgresIdempotencyStore, SQL_IDEMPOTENCY_TABLE } from './idempotency-postgres';
 /** The one execution path. `defOf` stays unexported — that is the enforcement. */
 export { actionName, invoke } from './invoke';
 export type { ActionJobHandle } from './job-handle';
 export { toJobHandle } from './job-handle';
 export type { JsonSchemaObject } from './json-schema';
-export { jsonSchemaOf, mcpSchemaOf } from './json-schema';
-export type { McpInvokeOptions, McpToolDescriptor } from './mcp-tool';
-export { isExposed, toMcpTool, toMcpTools } from './mcp-tool';
+export { jsonSchemaOf } from './json-schema';
 export type {
   LocalTable,
   LocalTableName,
@@ -228,7 +183,7 @@ export type {
 } from './mutator';
 export { custom, isMutator, mutator } from './mutator';
 export type { ActionPath } from './naming';
-export { derivePath, inputSchemaName, outputSchemaName, pluralize } from './naming';
+export { derivePath, inputSchemaName, outputSchemaName } from './naming';
 export type { BuildOpenApiOptions, OpenApiDocument, OpenApiInfo } from './openapi';
 export { buildOpenApi, serializeOpenApi } from './openapi';
 export {
@@ -244,19 +199,12 @@ export {
 export { explainActionPathMiss } from './path-style-miss';
 export type { ActionPolicy, PolicySubject, Surface } 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.
+ * The one authz gate, named after what it guards. The display label (`policyCapability`), what a
+ * report MATCHES on (`policyPermissions`) and what `toRoute` derives `meta.auth` from
+ * (`admitsAnonymous`) are `@ultimat3/policy`'s, and the anonymous → `null` mapping (`actorOf`) is
+ * `@ultimat3/core`'s — imported from there, so `query` reads the same walk through one import path.
  */
-export {
-  actorOf,
-  admitsAnonymous,
-  guard,
-  guardBeforeInput,
-  policyCapability,
-  policyPermissions,
-} from './policy-gate';
+export { guardAction, guardActionBeforeInput } from './policy-gate';
 export {
   actionHttpPath,
   configureActionPathStyle,
@@ -265,8 +213,9 @@ export {
   listActions,
   registerAction,
   registerActions,
-  resetRegistry,
+  resetActions,
 } from './registry';
+export { requestDeadlineMs } from './request-deadline';
 /**
  * A mutator FACTORY, never a ninth primitive: `transition()` returns a `mutator`, so a move through
  * a state machine inherits the route, the OpenAPI operation, the typed client, the MCP tool, the job

package/src/invoke.ts

@@ -1,19 +1,20 @@
 /**
- * The one invocation core: parse input, evaluate policy, run the handler, parse
- * output. The declaration lives in this module's private store, so `handle` is
+ * The one invocation core: ask who is calling, spend the rate limit, parse input, evaluate
+ * policy, run the handler, parse output. The declaration lives in this module's private store, so `handle` is
  * unreachable from anywhere else — HTTP, MCP, jobs and `.as()` hand `invoke` a
  * payload, and none of them can become a second execution path.
  *
  * `audit: true` wraps that path, it never forks it: `execute` is the same body either way, and
  * the audited branch only observes it. Wrapping rather than hooking is what lets a DENIED attempt
- * be recorded at all — `guard` throws before `handle`, so nothing an app writes around its own
+ * be recorded at all — `guardAction` throws before `handle`, so nothing an app writes around its own
  * handler could ever see one.
  */
 
 import type { Ctx } from '@ultimat3/core';
 import {
+  actorOf,
   anonymousActor,
-  createContext,
+  ctxOf,
   isUltimateError,
   runWithContext,
   tryUseContext,
@@ -34,7 +35,8 @@ import { bustAfterCommit } from './cache-gate';
 import { ActionForeignError, ActionUnregisteredError } from './errors';
 import { getIdempotencyStore, withIdempotency } from './idempotency';
 import { idempotencyKeyFor } from './idempotency-key';
-import { actorOf, guard, guardBeforeInput } from './policy-gate';
+import { guardAction, guardActionBeforeInput } from './policy-gate';
+import { spendActionLimit, withCallerAddress, withJobFrame } from './rate-limit-gate';
 import { parsedOrNothing, validateInput, validateOutput } from './validate';
 
 /**
@@ -77,6 +79,15 @@ export function invoke(
   raw: unknown,
   options: InvokeOptions = {},
 ): Promise<unknown> {
+  // The address a surface handed over becomes the one every nested call inherits — an agent's
+  // tool calls are keyed by the visitor who asked, not shared by every anonymous visitor.
+  // A job run opens a fresh frame instead: no visitor's address follows work into the worker.
+  return options.surface === 'job'
+    ? withJobFrame(() => invokeAs(target, raw, options))
+    : withCallerAddress(options.clientAddress, () => invokeAs(target, raw, options));
+}
+
+function invokeAs(target: AnyAction, raw: unknown, options: InvokeOptions): Promise<unknown> {
   if (options.actor === undefined) {
     // INSTALLED, never only handed over. An explicit `ctx` used to be passed to `core` and to
     // nothing else, so everything downstream that reads the ambient context — most importantly
@@ -96,7 +107,7 @@ export function invoke(
   const run = (): Promise<unknown> => core(target, raw, useContext(), options);
   const base = options.ctx ?? tryUseContext();
   return base === undefined
-    ? runWithContext(createContext(patch), run)
+    ? runWithContext(ctxOf(patch), run)
     : runWithContext(base, () => withChildContext(patch, run));
 }
 
@@ -128,7 +139,8 @@ async function core(
   const draft = {
     // When the attempt began, from the context's clock — never `new Date()`.
     at: ctx.now(),
-    action: name,
+    name,
+    primitive: 'action',
     // The brand `mutator()` stamps, read structurally — the same read `describeAction` makes,
     // and for the same reason: importing `isMutator` would point this module at the one that
     // imports it, for a check that needs the brand and not the predicate.
@@ -163,7 +175,7 @@ async function core(
 /**
  * The span covers the WHOLE invocation, not just `handle`. Wrapping the handler alone reported
  * 40ms for an action whose p99 was 2s, because `def.row()` — the loader a row-level policy needs
- * — ran outside it, along with the input parse and `guard()`. The 1.96s was inside no span at
+ * — ran outside it, along with the input parse and `guardAction()`. The 1.96s was inside no span at
  * all, so the only reading available was "framework overhead" and the only fix was hand
  * instrumentation. One span, one extent, and the attributes that make it answerable.
  *
@@ -219,15 +231,42 @@ async function perform(
   const surface = options.surface ?? 'server';
   // Who is asking is decided before what they sent is read: a caller the policy refuses whatever
   // the input is gets 403/401 here, not a 400 whose issues describe this action's input schema.
-  // Only the actor half runs — a predicate over `input` or `row` waits for `guard` below.
+  // Only the actor half runs — a predicate over `input` or `row` waits for `guardAction` below.
   try {
-    guardBeforeInput(def.policy, { actor: actorOf(ctx), ctx, action: name }, surface);
+    guardActionBeforeInput(def.policy, { actor: actorOf(ctx), ctx, action: name }, surface);
   } catch (denial) {
     // The audit record still names what was attempted — the denial is already decided, so parsing
     // now tells the CALLER nothing, and an unparseable payload is a record with no input.
     if (def.audit === true) trace.input = await parsedOrNothing(def.input, raw);
     throw denial;
   }
+  // The ONE place a declared `rateLimit:` is spent, so every surface draws on the same bucket.
+  // HERE — after the actor half (a refused caller learns that, not a 429), BEFORE the parse, the
+  // row load and `guardAction`: spent later, a flood of invalid input (400) or row-denied calls (403)
+  // was never refused, and every 429 had already paid for a row load.
+  const spend = (): Promise<void> =>
+    spendActionLimit(name, def.rateLimit, ctx, {
+      surface,
+      clientAddress: options.clientAddress,
+      onRateLimit: options.onRateLimit,
+    });
+  const key = def.idempotent === true ? (options.idempotencyKey ?? null) : null;
+  const store = key === null ? undefined : (options.store ?? getIdempotencyStore());
+  // The namespaced key, not the caller's: the same key under two actions — or from two callers
+  // — is two keys, and an audit row keyed on the raw header would collide across both. The
+  // ACTOR comes from `ctx`, which `invoke` installed, so every surface scopes identically.
+  if (key !== null) trace.idempotencyKey = idempotencyKeyFor(name, key, ctx.actor);
+  // A replay is its stored answer and spends nothing — a 429 in its place told a client its
+  // committed write had not happened. A key the store already holds is a replay (or a duplicate in
+  // flight, answered 409); only a key it does not hold spends here. The peek can be stale both
+  // ways, so `withIdempotency` meters a reservation it CREATED that this peek did not pay for.
+  const spentEarly =
+    trace.idempotencyKey === null ||
+    store === undefined ||
+    def.rateLimit === undefined ||
+    (await store.get(trace.idempotencyKey)) === undefined;
+  if (spentEarly) await spend();
+
   const input = await validateInput(def.input, raw, name);
   trace.input = input;
   // The one place a row-level rule gets its row. Once per invocation, never per row:
@@ -236,7 +275,7 @@ async function perform(
   // action with no loader hands the rule `null` — unchanged, and never a silent allow,
   // because a rule that reads `row` has to decide what `null` means.
   const row = def.row === undefined ? null : ((await def.row({ input, ctx })) ?? null);
-  guard(def.policy, { actor: actorOf(ctx), input, row, ctx, action: name }, surface);
+  guardAction(def.policy, { actor: actorOf(ctx), input, row, ctx, action: name }, surface);
 
   // Output parsing sits inside `run` so a replayed idempotent response is the parsed value too —
   // one shape on the wire, first call and every retry. No span of its own: `execute` above holds
@@ -246,18 +285,14 @@ async function perform(
     return validateOutput(def.output, produced, name);
   };
 
-  const key = def.idempotent === true ? (options.idempotencyKey ?? null) : null;
   let value: unknown;
   let wrote = true;
-  if (key === null) {
+  if (store === undefined || trace.idempotencyKey === null) {
     value = await run();
   } else {
-    const store = options.store ?? getIdempotencyStore();
-    // The namespaced key, not the caller's: the same key under two actions — or from two callers
-    // — is two keys, and an audit row keyed on the raw header would collide across both. The
-    // ACTOR comes from `ctx`, which `invoke` installed, so every surface scopes identically.
-    trace.idempotencyKey = idempotencyKeyFor(name, key, ctx.actor);
-    const outcome = await withIdempotency(store, trace.idempotencyKey, input, run);
+    const outcome = await withIdempotency(store, trace.idempotencyKey, input, run, {
+      ...(spentEarly ? {} : { beforeRun: spend }),
+    });
     if (outcome.replayed) options.onReplay?.();
     trace.replayed = outcome.replayed;
     wrote = !outcome.replayed;
@@ -268,8 +303,9 @@ async function perform(
   }
   // Only for a run that actually happened, and only through the gate. A replay ran no handler
   // and changed nothing the first call had not already busted — re-busting per retry re-purges
-  // the CDN and re-queues ISR for a write nobody made. And the bust is post-commit either way,
-  // so `bustAfterCommit` swallowing its own failure is what keeps a dead cache from turning a
+  // the CDN and re-queues ISR for a write nobody made. And the bust is post-COMMIT either way —
+  // invoked inside a transaction, it waits for the root commit and is dropped by a rollback — so
+  // `bustAfterCommit` swallowing its own failure is what keeps a dead cache from turning a
   // durable write into a failed action.
   if (wrote && def.cache !== undefined) await bustAfterCommit(name, def.cache.invalidates);
   return value;

package/src/job-handle.ts

@@ -1,9 +1,11 @@
 /**
  * Projection 5: an action as durable work — its input schema, a payload-derived
  * idempotency key, and an `invoke` that runs the action's one execution path under
- * `surface: 'job'`, so a queued run gets the same validation and policy evaluation
- * as the HTTP call. `@ultimat3/ai`'s `agentJob()` is the framework's one consumer — it takes any
- * `Action` and composes `job()` around this shape — and an app may write the same three lines.
+ * `surface: 'job'`, so a queued run takes the same validation and policy path as the HTTP call —
+ * under the worker's system authority: the enqueuer is `enqueuedBy`, attribution only, and never
+ * authorises the run. An action that acts for a user takes that user's id and re-authorises it.
+ * `@ultimat3/ai`'s `agentJob()` is the framework's one consumer — it takes any `Action` and
+ * composes `job()` around this shape — and an app may write the same three lines.
  */
 import type { Ctx } from '@ultimat3/core';
 import { fingerprint } from '@ultimat3/core';

package/src/json-schema.ts

@@ -1,11 +1,12 @@
 /**
- * Standard Schema -> JSON Schema, normalized to a plain record. OpenAPI, MCP
- * descriptors and the manifest all need the same object, produced the same way.
+ * Standard Schema -> JSON Schema, normalized to a plain record, for OpenAPI and the manifest. An
+ * MCP tool's schema is `@ultimat3/schema`'s `toWireSchema` — the one `tools/list` serves.
  */
 
+import { isJsonObject } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
-import { SchemaUnsupportedError, toJsonSchema, toMcpInputSchema } from '@ultimat3/schema';
-import { isJsonObject, stableStringify } from './stable';
+import { SchemaUnsupportedError, toJsonSchema } from '@ultimat3/schema';
+import { stableStringify } from './stable';
 
 export type JsonSchemaObject = Record<string, unknown>;
 
@@ -23,13 +24,8 @@ export function jsonSchemaOf(schema: StandardSchemaV1): JsonSchemaObject {
   return normalizeJsonSchema(() => toJsonSchema(schema));
 }
 
-/** Draft-07, no `$schema` — the exact shape an MCP `tools/list` entry needs. */
-export function mcpSchemaOf(schema: StandardSchemaV1): JsonSchemaObject {
-  return normalizeJsonSchema(() => toMcpInputSchema(schema));
-}
-
 /**
- * The narrowing both projections share, and the refusal it earns: a converter that answered with
+ * The narrowing `jsonSchemaOf` applies, and the refusal it earns: a converter that answered with
  * something that is not a JSON object is the same failure by a quieter route, so it gets the same
  * shipped code rather than a permissive node. Exported for its own test and nothing else — it is
  * absent from `src/index.ts`, exactly as `sortSchema` is.

package/src/mutator.ts

@@ -5,7 +5,7 @@
  * contract tests for free, and its authz is the same single evaluation.
  */
 
-import type { ConflictPolicy, Ctx, Row } from '@ultimat3/core';
+import type { ConflictPolicy, Ctx, Deprecation, Row } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type {
   Action,
@@ -17,7 +17,7 @@ import type {
   ActionRowArgs,
 } from './action';
 import { action, isAction } from './action';
-import type { Deprecation } from './deprecation';
+import { MutatorNotIdempotentError } from './errors';
 import type { ActionHttp } from './http-path';
 import { assertConflictClock } from './mutator-clock';
 import type { ActionPolicy } from './policy-gate';
@@ -97,7 +97,14 @@ export interface MutatorDef<
   readonly deprecated?: Deprecation;
   /** Same key, same meaning as an action's: `http: { path }` pins the URL. */
   readonly http?: ActionHttp;
-  readonly idempotent?: boolean;
+  /**
+   * REQUIRED, and only `true`. A mutator's write is replayed under one `Idempotency-Key` —
+   * `useMutation`'s retry, the offline queue's drain after a dropped response — and the server
+   * reads that key only for an idempotent action. Declared rather than defaulted because the
+   * replay is answered from the idempotency store, and which store that is (`configureIdempotency`)
+   * is the app's decision to see. Omitted: a compile error, and `X_MUTATOR_NOT_IDEMPOTENT`.
+   */
+  readonly idempotent: true;
   /**
    * The row a row-level `policy` decides about — an action's `row`, and dropped on the way into
    * the action until 2026-09-23, so such a policy received `row === null` and denied every call.
@@ -158,6 +165,9 @@ export function mutator<
   TOutput extends StandardSchemaV1,
   TRow = unknown,
 >(def: MutatorDef<TInput, TOutput, TRow>): Mutator<TInput, TOutput> {
+  // First, and for a caller the compiler never saw: a replay that runs the server half twice is
+  // silent, so the declaration is refused where it is written rather than on the second POST.
+  if (def.idempotent !== true) throw new MutatorNotIdempotentError();
   const row = def.row;
   const actionDef: ActionDef<TInput, TOutput, TRow> = {
     input: def.input,
@@ -169,7 +179,7 @@ export function mutator<
     ...(def.deprecated === undefined ? {} : { deprecated: def.deprecated }),
     ...(def.http === undefined ? {} : { http: def.http }),
     ...(row === undefined ? {} : { row: (args: ActionRowArgs<TInput>) => row.call(def, args) }),
-    ...(def.idempotent === undefined ? {} : { idempotent: def.idempotent }),
+    idempotent: true,
     ...(def.audit === undefined ? {} : { audit: def.audit }),
     handle: ({ input, ctx }) => def.server(ctx, input),
   };

package/src/naming.ts

@@ -11,10 +11,9 @@ import { resolveActionRoute } from './http-path';
 
 /**
  * The path rule is `@ultimat3/core`'s `client-paths.ts` — the typed client, the route and the
- * spec derive one URL from one function. Re-exported by name so `@ultimat3/action`'s public
- * `derivePath` / `pluralize` / `splitWords` / `ActionPath` keep resolving; never re-declared here.
+ * spec derive one URL from one function; `pluralize` and `splitWords` are imported from core by
+ * whoever needs them, never re-exported here (`X_HELPER_COPY`).
  */
-export { pluralize, splitWords } from '@ultimat3/core';
 
 export type ActionPath = ActionRoute;