@ultimat3/action 24.0.0 → 25.0.0

package/src/idempotency-redact.ts

@@ -0,0 +1,140 @@
+/**
+ * One job: the copy of an idempotent answer that may be kept AT REST — every value under a key
+ * core's `isRedactedKey` names, every `Secret` box, and everything the walk cannot vouch for
+ * replaced by `[redacted]`. The rule is core's table, the one `audit-input.ts` and the logger ask.
+ */
+import { isRedactedKey, isSecret, REDACTED } from '@ultimat3/core';
+
+/**
+ * How deep the walk inspects. Past it the subtree is REDACTED, never kept: what was not looked at
+ * cannot be shown to hold no credential, and the record of it outlives the request by a day. An
+ * output schema deep enough to reach this is a recursive one, and its replay is refused rather
+ * than served with a credential in it.
+ */
+export const IDEMPOTENCY_REDACT_MAX_DEPTH = 32;
+
+export interface RestingAnswer {
+  /** What the store may write down. The ORIGINAL reference when nothing was redacted. */
+  readonly value: unknown;
+  /** True when anything was replaced — the record's flag, so a replay never scans for a string. */
+  readonly redacted: boolean;
+}
+
+interface WalkState {
+  redacted: boolean;
+}
+
+/**
+ * The answer as it may rest. Plain data — objects whose prototype is `Object.prototype` or
+ * `null`, arrays, `Date`, primitives — with no redacted key comes back as the SAME reference, so
+ * the common case stores and replays exactly what it did before.
+ *
+ * **Fail closed on everything else.** The Postgres store writes `JSON.stringify(value)`, which
+ * runs app code this walk never saw: a `toJSON` (on a class, a plain object, an array, even a
+ * function) may return `{ apiKey }`, and a getter read a second time may return something else.
+ * So a value with a callable `toJSON`, a `Map`, a `Set`, a class instance or a `Date` subclass is
+ * `[redacted]` and the record flagged — its replay is refused, which is the honest answer for an
+ * answer this walk could not judge. An own getter is read ONCE and the subtree copied, so the
+ * serializer reads the value that was judged, not a fresh one. `toJSON` is never called. A CYCLE
+ * is cut the same way — its back-reference becomes `[redacted]` — so both stores keep one
+ * serializable copy; a value repeated as siblings is not a cycle and is kept.
+ */
+export function restingAnswer(value: unknown): RestingAnswer {
+  const state: WalkState = { redacted: false };
+  const out = walk(value, 0, new Set(), state);
+  return { value: out, redacted: state.redacted };
+}
+
+function redact(state: WalkState): string {
+  state.redacted = true;
+  return REDACTED;
+}
+
+/** `JSON.stringify` asks for `toJSON` on any object — a function included. */
+function hasToJson(value: object): boolean {
+  return typeof (value as { toJSON?: unknown }).toJSON === 'function';
+}
+
+/** A `Date` whose `toJSON` is the built-in one: its own prototype, no own override. */
+function isPlainDate(value: object): boolean {
+  return Object.getPrototypeOf(value) === Date.prototype && !Object.hasOwn(value, 'toJSON');
+}
+
+function isPlainObject(value: object): boolean {
+  const proto: unknown = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function walk(value: unknown, depth: number, ancestors: Set<object>, state: WalkState): unknown {
+  if (typeof value === 'function') return hasToJson(value) ? redact(state) : value;
+  if (typeof value !== 'object' || value === null) return value;
+  if (isSecret(value)) return redact(state);
+  if (isPlainDate(value)) return value;
+  // A back-reference fails closed: kept, `JSON.stringify` throws in the Postgres store after the
+  // handler committed, while the memory store would accept it — two answers for one record.
+  if (ancestors.has(value)) return redact(state);
+  const array = Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype;
+  if (hasToJson(value) || !(array || isPlainObject(value))) return redact(state);
+  if (depth >= IDEMPOTENCY_REDACT_MAX_DEPTH) return redact(state);
+  ancestors.add(value);
+  try {
+    return array
+      ? walkArray(value as readonly unknown[], depth, ancestors, state)
+      : walkObject(value, depth, ancestors, state);
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+/**
+ * One read of an own property: a data property's value, or its getter called exactly once.
+ * `copy` says the subtree must be copied for the read to be the one the serializer sees.
+ */
+function readOnce(target: object, key: string | number): { value: unknown; copy: boolean } {
+  const descriptor = Object.getOwnPropertyDescriptor(target, key);
+  if (descriptor === undefined) return { value: undefined, copy: false };
+  if (descriptor.get !== undefined) return { value: descriptor.get.call(target), copy: true };
+  return { value: descriptor.value, copy: false };
+}
+
+function walkArray(
+  value: readonly unknown[],
+  depth: number,
+  ancestors: Set<object>,
+  state: WalkState,
+): unknown {
+  let copy: unknown[] | undefined;
+  // Indexed, not `forEach`: a hole is visited (as `undefined`) and kept in its place.
+  for (let index = 0; index < value.length; index += 1) {
+    const read = readOnce(value, index);
+    const next = walk(read.value, depth + 1, ancestors, state);
+    if (read.copy || next !== read.value) copy ??= value.slice(0, index);
+    copy?.push(next);
+  }
+  return copy ?? value;
+}
+
+function walkObject(
+  value: object,
+  depth: number,
+  ancestors: Set<object>,
+  state: WalkState,
+): unknown {
+  let changed = false;
+  const out: Record<string, unknown> = {};
+  // OWN enumerable string keys: what `JSON.stringify` writes and what the Postgres store keeps.
+  for (const key of Object.keys(value)) {
+    const read = readOnce(value, key);
+    const item = read.value;
+    // The key decides before the value is walked, so a credential under a redacted name is never
+    // read further. `null` and `undefined` under one are KEPT: they hold no credential, and
+    // redacting them would refuse the replay of a `{ resetToken: null }` that never carried one.
+    const next =
+      item !== undefined && item !== null && isRedactedKey(key)
+        ? redact(state)
+        : walk(item, depth + 1, ancestors, state);
+    if (read.copy || next !== item) changed = true;
+    out[key] = next;
+  }
+  return changed ? out : value;
+}

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();
@@ -230,7 +273,11 @@ export async function withIdempotency<T>(
   // 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.
-  await store.settle(key, value, record.id);
+  //
+  // 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,44 +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.
- */
-/**
- * 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 {
-  ClientFlight,
-  ClientFlightOptions,
-  ClientRetry,
-  FlightKeyOptions,
-  FlightPlan,
-  PgExecutor,
-  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';
@@ -60,7 +34,6 @@ export type {
   ActionRowArgs,
   AnyAction,
   InvokeOptions,
-  McpAnnotationHints,
   McpDescriptorMeta,
 } from './action';
 export { action, describeAction, isAction } from './action';
@@ -79,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,
@@ -112,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,
@@ -138,6 +99,7 @@ export {
   IdempotencyReplayedFailureError,
   IdempotencyReservationLostError,
   IdempotencyStatusUnknownError,
+  IdempotentReplayRedactedError,
   InputInvalidError,
   MutatorNotIdempotentError,
   OutputInvalidError,
@@ -151,8 +113,6 @@ export {
 } from './errors-http';
 export type { OpenApiOperation } from './http';
 export {
-  BUILD_ID_HEADER,
-  IDEMPOTENCY_HEADER,
   operationTagOf,
   REPLAYED_HEADER,
   toOpenApiOperation,
@@ -191,34 +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';
 export type {
   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 } from './json-schema';
-export type { McpInvokeOptions, McpToolDescriptor } from './mcp-tool';
-export { isExposed, toMcpTool, toMcpTools } from './mcp-tool';
 export type {
   LocalTable,
   LocalTableName,
@@ -230,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 {
@@ -246,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,
@@ -267,7 +213,7 @@ export {
   listActions,
   registerAction,
   registerActions,
-  resetRegistry,
+  resetActions,
 } from './registry';
 export { requestDeadlineMs } from './request-deadline';
 /**

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;

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