@ultimat3/action 24.0.0 → 25.1.0

package/src/action.ts

@@ -1,17 +1,19 @@
 /**
  * The `action` primitive: one server-authoritative mutation, declared once.
- * Every projection in this package (route, OpenAPI, client, MCP tool, job
- * handle, contract tests) reads this declaration — none of them re-declare it.
+ * Every projection in this package (route, OpenAPI, client, job handle, contract
+ * tests) reads this declaration — none of them re-declare it. The MCP tool is
+ * `@ultimat3/mcp`'s projection (`toolFrom`), one tier up, of the same declaration.
  */
 
 import type { CacheTag } from '@ultimat3/cache';
 import { tagKeys } from '@ultimat3/cache';
-import type { Actor, Ctx } from '@ultimat3/core';
+import type { Actor, Ctx, Deprecation, McpExposureDeclaration } from '@ultimat3/core';
 import { isMcpExposed } from '@ultimat3/core';
+import type { RateLimitDecision } from '@ultimat3/http';
+import { policyCapability, policyPermissions } from '@ultimat3/policy';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { ClientMethod, ClientOptions } from './client';
 import type { ContractTest, ContractTestOptions } from './contract-test';
-import type { Deprecation } from './deprecation';
 import { facadeFor } from './facade';
 import type { OpenApiOperation } from './http';
 import type { ActionHttp } from './http-path';
@@ -21,76 +23,18 @@ import { actionName, defOf, hasDef, invoke, stashDef } from './invoke';
 import type { ActionJobHandle } from './job-handle';
 import type { JsonSchemaObject } from './json-schema';
 import { jsonSchemaOf } from './json-schema';
-import type { McpToolDescriptor } from './mcp-tool';
-import {
-  type ActionPolicy,
-  policyCapability,
-  policyPermissions,
-  type Surface,
-} from './policy-gate';
+import type { ActionPolicy, Surface } from './policy-gate';
 
 export interface ActionCache {
   /** Tags dropped from every cache tier after the handler settles. */
   readonly invalidates: readonly CacheTag[];
 }
 
-export interface ActionMcp {
-  /** Opt-in: only a literal `true` makes the action a tool. Silence exposes nothing. */
-  readonly expose: boolean;
-  /**
-   * Contract text, NOT UI text — deliberately outside `t()`. It becomes the OpenAPI
-   * operation `summary` (`toOpenApiOperation`), and `buildOpenApi`'s bytes are what
-   * `x verify` diffs for contract drift. Resolving it through the ambient, request-scoped
-   * translator would make `openapi.json` depend on whichever locale happened to be active
-   * when it was generated, which is exactly the determinism that file's header forbids.
-   * Localised agent-facing text needs a separate, locale-resolved projection; there is no
-   * second field for it here until that exists, because two ways to describe one tool is
-   * the drift axiom 1 rejects.
-   */
-  readonly description?: string;
-  /**
-   * Roles that may SEE the projected tool. A CATALOG audience, never an authz rule — the
-   * `policy` above still decides every call, and this list decides nothing about one. Omitted
-   * means every caller may enumerate it.
-   *
-   * Fail-closed where it lands (`@ultimat3/mcp`): a caller whose role is not named — including
-   * one carrying no role at all — gets the answer an ABSENT tool gets, never `Forbidden`.
-   * Forbidden would confirm the tool exists, which turns the catalog into something an agent
-   * can enumerate by probing names.
-   *
-   * A plain role list, never a predicate: a declared fact has to stay static and serialisable.
-   * A surface deriving visibility from something richer (`@ultimat3/admin` derives it from the
-   * actor's admin permissions) hands `@ultimat3/mcp` a predicate instead.
-   */
-  readonly visibleTo?: readonly string[];
-  /**
-   * The tool's display name in an MCP client's UI (`title`, MCP 2025-06-18). Contract text, like
-   * `description`. Omitted: none is published and the client shows the tool name.
-   */
-  readonly title?: string;
-  /**
-   * MCP tool annotations, overriding what `@ultimat3/mcp` derives key by key. An action derives
-   * `readOnlyHint: false`, `destructiveHint: true` and `idempotentHint` from `idempotent`. Hints for
-   * a client's confirmation UI — the policy decides every call whatever they say.
-   *
-   * ```ts
-   * mcp: { expose: true, annotations: { destructiveHint: false, openWorldHint: true } },
-   * ```
-   */
-  readonly annotations?: McpAnnotationHints;
-}
-
 /**
- * MCP's four tool hints, as the spec spells them. Declared here (tier 3) and in `@ultimat3/query`
- * because `@ultimat3/mcp` (tier 4) is the reader and cannot be imported; its `McpToolAnnotations`
- * is the same shape.
+ * An action's `mcp` block: core's ONE `McpExposureDeclaration`, minus the list whitelist an action
+ * has no list to compose over. Derived, never restated — `type-pins.ts` holds it to core's.
  */
-export interface McpAnnotationHints {
-  readonly readOnlyHint?: boolean;
-  readonly destructiveHint?: boolean;
-  readonly idempotentHint?: boolean;
-  readonly openWorldHint?: boolean;
-}
+export type ActionMcp = Omit<McpExposureDeclaration, 'listParams'>;
 
 export interface ActionRateLimit {
   readonly limit: number;
@@ -180,6 +124,19 @@ export interface InvokeOptions {
   readonly idempotencyKey?: string | null;
   readonly store?: IdempotencyStore;
   readonly onReplay?: () => void;
+  /**
+   * The caller's connection address, which is the only rate-limit subject an anonymous caller has
+   * (`actor > org > address`). The HTTP projection passes the request's; a surface with none
+   * leaves it out, and every anonymous caller there shares one bucket — refused together rather
+   * than unlimited.
+   */
+  readonly clientAddress?: string | null;
+  /**
+   * Hands over the `rateLimit:` decision before a refusal is thrown — how the HTTP projection
+   * answers with `RateLimit-*` and `Retry-After`. Called only for a declared limit on a surface
+   * that spends one.
+   */
+  readonly onRateLimit?: (decision: RateLimitDecision) => void;
 }
 
 export interface McpDescriptorMeta {
@@ -258,7 +215,6 @@ export interface AnyAction {
   named(name: string): AnyAction;
   /** Run as this actor. Same `invoke` core, only the context's actor changes. */
   as(actor: Actor | null, input: unknown, options?: InvokeOptions): Promise<unknown>;
-  tool(): McpToolDescriptor;
   openapi(): OpenApiOperation;
   /**
    * The durable-work shape, erased. `listActions()` and `getAction(name)` hand back this view
@@ -302,7 +258,7 @@ export interface Action<
 /** The fluent half of an action: lifted declaration plus one method per projection. */
 export type ActionFacade<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1> = Pick<
   Action<TInput, TOutput>,
-  'input' | 'output' | 'policy' | 'mcp' | 'as' | 'tool' | 'openapi' | 'client' | 'job' | 'contract'
+  'input' | 'output' | 'policy' | 'mcp' | 'as' | 'openapi' | 'client' | 'job' | 'contract'
 >;
 
 export function action<
@@ -327,7 +283,7 @@ export function isAction(value: unknown): value is AnyAction {
 /**
  * Stamp the export name onto the action the app declared, rather than handing back a
  * differently-named copy of it. `import { publishPost } from './actions'` is then the
- * action that projects — `publishPost.tool()` after boot, with nothing to remember.
+ * action that projects — `publishPost.openapi()` after boot, with nothing to remember.
  * Naming twice is the one case that still needs a twin: one object, one name, forever.
  */
 export function nameAction<A extends AnyAction>(target: A, name: string): A {

package/src/api-declaration.ts

@@ -117,7 +117,7 @@ export function apiDeclaration(): ApiDeclaration {
   return declared;
 }
 
-/** Test seam, called by `resetRegistry`. */
+/** Test seam, called by `resetActions`. */
 export function resetApiDeclaration(): void {
   declared = {};
 }

package/src/audit-gate.ts

@@ -4,9 +4,8 @@
  * an attempt that already failed do not want the same answer.
  */
 
-import { isUltimateError, logger } from '@ultimat3/core';
+import { getAuditSink, isUltimateError, logger } from '@ultimat3/core';
 import type { AuditFailure, AuditOutcome, AuditRecord, AuditSink } from './audit';
-import { getAuditSink } from './audit';
 import { ActionDeniedError, AuditSinkFailedError, AuditSinkMissingError } from './errors';
 
 /**
@@ -63,7 +62,7 @@ export async function auditSettled(sink: AuditSink, record: AuditRecord): Promis
   try {
     await sink.write(record);
   } catch (error) {
-    throw new AuditSinkFailedError(record.action, error, record.idempotencyKey !== null);
+    throw new AuditSinkFailedError(record.name, error, record.idempotencyKey !== null);
   }
 }
 
@@ -84,7 +83,7 @@ export async function auditThrew(sink: AuditSink, record: AuditRecord): Promise<
     // the same reason `cache-gate.ts` gives. Never the record — rendering an input the sink just
     // choked on is the second throw this branch exists to prevent.
     logger.error('audit.sink.failed', {
-      action: record.action,
+      action: record.name,
       outcome: record.outcome,
       error,
     });

package/src/audit-memory.ts

@@ -11,8 +11,8 @@ import type { AuditRecord, AuditSink } from './audit';
  * input — so its cost is the request's, not a row's: at 50 audited writes a second an unbounded
  * array is 4.3M immortal records a day and the pod dies holding the trail it was retaining. This
  * sink was the one memory implementation in the framework with no cap, beside five that have one
- * (`memoryRateLimitStore`, `MemoryIdempotencyStore`, `createLimiter`, `createTotpReplayGuard`,
- * `createMemoryEventBus`).
+ * (`memoryRateLimitStore`, `memoryIdempotencyStore`, `concurrencyLimiter`, `memoryTotpReplayGuard`,
+ * `memoryEventBus`).
  */
 export const DEFAULT_MAX_AUDIT_RECORDS = 1_000;
 
@@ -46,7 +46,7 @@ export interface MemoryAuditSink extends AuditSink {
 }
 
 /**
- * The OLDEST goes, which is the same direction `createMemoryEventBus` evicts in and the opposite
+ * The OLDEST goes, which is the same direction `memoryEventBus` evicts in and the opposite
  * of refusing new writes: a sink that stopped recording at the cap would answer "nothing has
  * happened since" for a process that has been serving all day, and the most recent attempts are
  * the ones anyone reading `x dev` is looking at.

package/src/audit-postgres.ts

@@ -6,7 +6,7 @@
  */
 
 import type { Actor, PgExecutor } from '@ultimat3/core';
-import { uuid } from '@ultimat3/core';
+import { uuidV7 } from '@ultimat3/core';
 import type { AuditRecord, AuditSink } from './audit';
 import { auditableInput } from './audit-input';
 
@@ -34,6 +34,10 @@ import { auditableInput } from './audit-input';
  * a different answer per app — seven years for one, thirty days for the next — so shipping a
  * `delete` would be shipping one of those answers. The table grows until the app prunes or
  * partitions it, and that is stated rather than solved.
+ *
+ * **`primitive` arrived by `alter`, with a default of `'action'`.** The sink is shared with
+ * `query({ audit: true })` since plan 101 sweep 10b, so a row has to say whether a read or a write
+ * acted; every row written before that was an action's, which is exactly what the default says.
  */
 export const SQL_AUDIT_TABLE = `
 create table if not exists x_audit (
@@ -61,6 +65,8 @@ create table if not exists x_audit (
   recorded_at       timestamptz not null default now()
 );
 
+alter table x_audit add column if not exists primitive text not null default 'action';
+
 create index if not exists x_audit_at_idx on x_audit (at desc);
 
 create index if not exists x_audit_actor_at_idx on x_audit (actor_id, at desc);
@@ -79,11 +85,11 @@ export const SQL_AUDIT_INSERT = `
 insert into x_audit (
   id, at, action, mutator, surface, outcome, replayed, idempotency_key, failure_code,
   actor_id, actor_kind, org_id, on_behalf_of_id, on_behalf_of_kind,
-  request_id, trace_id, locale, tz, build_id, role, input
+  request_id, trace_id, locale, tz, build_id, role, input, primitive
 ) values (
   $1::uuid, $2::timestamptz, $3, $4, $5, $6, $7, $8, $9,
   $10, $11, $12, $13, $14,
-  $15, $16, $17, $18, $19, $20, $21::jsonb
+  $15, $16, $17, $18, $19, $20, $21::jsonb, $22
 )
 `;
 
@@ -111,7 +117,7 @@ export interface PostgresAuditSink extends AuditSink {
  * `Bun.sql` does not satisfy `PgExecutor` — `Bun.sql.query` is `undefined`; see that interface.
  *
  * What is written is an ALLOW-LIST of the facts the framework itself owns, never the `Ctx`. That
- * is not tidiness: `createContext` spreads every installed service onto the context object, and on
+ * is not tidiness: `ctxOf` spreads every installed service onto the context object, and on
  * an HTTP surface the value is a `RequestContext` carrying the request's own `Authorization` and
  * `Cookie` headers — so a projection that walked it would write an app's database clients and its
  * caller's credentials into an audit table. An app that wants more columns writes its own
@@ -126,9 +132,11 @@ export function postgresAuditSink(options: PostgresAuditSinkOptions): PostgresAu
       const onBehalfOf = onBehalfOfOf(actor);
       const input = auditableInput(record.input);
       await exec.query(SQL_AUDIT_INSERT, [
-        uuid(),
+        uuidV7(),
         at === null ? null : at.toISOString(),
-        record.action,
+        // `name`, into the column the seam named before reads were audited: renaming it is a data
+        // migration for every installed table, and the value it holds is the same.
+        record.name,
         record.mutator,
         record.surface,
         record.outcome,
@@ -149,6 +157,7 @@ export function postgresAuditSink(options: PostgresAuditSinkOptions): PostgresAu
         // `undefined` in means a parse that never produced an input, which is a NULL column and
         // not the four characters `JSON.stringify(undefined)` does not produce either.
         input === undefined ? null : JSON.stringify(input),
+        record.primitive,
       ]);
     },
   };

package/src/audit.ts

@@ -1,109 +1,10 @@
 /**
- * The audit seam: THAT an action or mutator can be recorded at all. One `AuditSink`, installed
- * once, handed every fact `invoke` genuinely knows about an attempt — who acted, which primitive,
- * when, on which surface, with which idempotency key, and whether it was allowed, denied or
- * failed. What the ROW says — its fields, its retention, its hash chain, its subject index, what
- * "who" means under impersonation — is the app's, and this file declares none of it.
+ * The audit seam, as this package exposes it: THAT an action or mutator can be recorded at all.
+ * The contract — the record, the sink, the one installed-sink slot — moved to `@ultimat3/core`'s
+ * `audit.ts` so `@ultimat3/query` (a sibling this package cannot import) writes the same record
+ * into the same sink. The TYPES are re-exported for this package's own modules; the slot's VALUES
+ * (`getAuditSink`, `setAuditSink`, `resetAuditSink`) are imported from `@ultimat3/core` and never
+ * re-exported — a second import path for one value is `X_HELPER_COPY` (`bun run flight-copies`).
  */
 
-import type { Ctx } from '@ultimat3/core';
-import type { Surface } from './policy-gate';
-
-/**
- * The three things that can happen to an attempt. Deliberately the same three words
- * `@ultimat3/admin`'s `AuditEntry` uses — that package is tier 5 and this one is tier 3, so the
- * vocabulary is shared by name and not by import. `denied` is an authz refusal, `failed` is
- * everything else that threw, including an input that never parsed.
- */
-export type AuditOutcome = 'allowed' | 'denied' | 'failed';
-
-/** Why a non-`allowed` attempt ended. The framework classifies; it never renders. */
-export interface AuditFailure {
-  /** The `X_*` code when an `UltimateError` ended it; `null` for anything else that threw. */
-  readonly code: string | null;
-  /** The thrown value, verbatim — its stack is the thing worth reading. */
-  readonly error: unknown;
-}
-
-/**
- * One attempt, as the framework observed it. Every field here is something `invoke` already
- * holds; nothing on it is a guess about the business.
- *
- * `result` is deliberately absent. A handler's return value is reachable from the handler
- * itself, on the one outcome that has one — so shipping it would be the framework deciding the
- * row carries an after-image, which is the first field of an audit ENTITY. `input` is present
- * for the opposite reason: on a `denied` record the handler never ran, so nothing in app code
- * can recover what was attempted, and that is the record an auditor actually wants.
- */
-export interface AuditRecord {
-  /**
-   * When the attempt began, from `ctx.now()` — never `new Date()`. An instant, not a rendering:
-   * serialising it (ISO, epoch, a Postgres `timestamptz`) is the app's decision, and it is the
-   * app that knows the zone anything is displayed in.
-   */
-  readonly at: Date;
-  /** The registered export name. A mutator carries the name of its action half. */
-  readonly action: string;
-  /** True when `mutator()` built it. Which primitive acted is a framework fact. */
-  readonly mutator: boolean;
-  /** Which projection ran it: a price change over `http` and one over `mcp` are not the same event. */
-  readonly surface: Surface;
-  /**
-   * The context the attempt ran in — actor, `requestId`, `traceId`, locale, and the service bag
-   * a sink needs to write a row at all. Carried whole rather than projected into `actorId` +
-   * `requestId` fields, because choosing WHICH context facts an audit row keeps is precisely the
-   * convention four apps modelled four ways.
-   *
-   * **A sink that PERSISTS must project it, and `audit-postgres.ts` is where that is done.**
-   * `createContext` spreads every installed service onto this object and an HTTP surface's value
-   * is a `RequestContext` carrying the caller's `Authorization` and `Cookie`, so writing it down
-   * whole puts an app's database clients and its caller's credentials in a table. Whole here,
-   * allow-listed there — the seam hands over everything and each sink decides what it keeps.
-   */
-  readonly ctx: Ctx;
-  /**
-   * The PARSED input, or `undefined` when the parse is what failed. Never the raw payload:
-   * an unvalidated body is attacker-shaped, and handing one to a sink that writes it to a table
-   * is how an audit trail becomes an injection surface.
-   */
-  readonly input: unknown;
-  /** The namespaced key an `idempotent` action was retried under, or `null`. */
-  readonly idempotencyKey: string | null;
-  /** True when the response was replayed from an earlier settled record — a call, not a write. */
-  readonly replayed: boolean;
-  readonly outcome: AuditOutcome;
-  /** Present exactly when `outcome !== 'allowed'`. */
-  readonly failure: AuditFailure | null;
-}
-
-/**
- * Where a record goes. The app's implementation: a table, an append-only hash chain, an OTel
- * log, a queue. `@ultimat3/admin`'s `AuditSink` is the same noun one tier up, over its own
- * fixed entry type; this one carries no `AdminActor` and no `permission`, because an action
- * outside `/admin` has neither.
- *
- * A sink that throws is never swallowed — see `audit-gate.ts` for which failure wins.
- */
-export interface AuditSink {
-  write(record: AuditRecord): Promise<void> | void;
-}
-
-/**
- * No default. A logger-backed default would satisfy `audit: true` with a line nobody stores,
- * which is the silent pass this seam exists to remove: an audited action with no sink installed
- * is `X_AUDIT_SINK_MISSING`, refused before the handler runs.
- */
-let installed: AuditSink | null = null;
-
-export function setAuditSink(sink: AuditSink): void {
-  installed = sink;
-}
-
-export function getAuditSink(): AuditSink | null {
-  return installed;
-}
-
-/** Test seam: back to "nothing installed", which restoring a literal cannot express. */
-export function resetAuditSink(): void {
-  installed = null;
-}
+export type { AuditFailure, AuditOutcome, AuditRecord, AuditSink } from '@ultimat3/core';

package/src/client.ts

@@ -4,7 +4,7 @@
  * compile error in a Solid component — not a 404 at runtime.
  *
  * `ClientFlight` is a TYPE here and never a value: the fence, the retry loop and the deadline are
- * `@ultimat3/core`'s `client-flight.ts`, so a caller that never calls `createClientFlight` does
+ * `@ultimat3/core`'s `client-flight.ts`, so a caller that never calls `clientFlight` does
  * not pay a byte for any of them — an `import type` is erased and the value import would not be.
  * Dedup is deliberately unreachable from this file — a mutation may never join another mutation,
  * and the way that is guaranteed is that `keyFor` is never called here.
@@ -24,15 +24,16 @@ import type {
 } from '@ultimat3/core';
 import {
   actionPath,
+  BUILD_ID_HEADER,
   clientTransport,
   FRAMEWORK_CODE,
   isJsonObject,
   problemOf,
+  remoteTitleOf,
 } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { Action } from './action';
 import { ContractDriftError, RemoteActionError } from './errors';
-import { BUILD_ID_HEADER } from './wire-headers';
 import { issuesFromWire } from './wire-issues';
 
 /**
@@ -79,7 +80,7 @@ export interface ClientOptions {
   readonly buildId?: string;
   readonly headers?: Readonly<Record<string, string>>;
   /**
-   * Opt-in flight control — `createClientFlight({ … })`. Absent, a call is one dispatch and
+   * Opt-in flight control — `clientFlight({ … })`. Absent, a call is one dispatch and
    * nothing else, which is what every caller written before this option existed already gets.
    */
   readonly flight?: ClientFlight;
@@ -132,8 +133,11 @@ export function clientMethodFor<TInput extends StandardSchemaV1, TOutput extends
   const url = `${options.baseUrl.replace(/\/+$/, '')}${path}`;
   const onResponse = (response: Response): void =>
     assertSameBuild(options.buildId, response.headers.get(BUILD_ID_HEADER), name);
-  const decodeError = (status: number, text: string): UltimateError | undefined =>
-    toUltimateError(text, status, name);
+  const decodeError = (
+    status: number,
+    text: string,
+    retryAfterSeconds?: number,
+  ): UltimateError | undefined => toUltimateError(text, status, name, retryAfterSeconds);
   // Erased at the wire seam; the response type is this action's by construction.
   return (input, callOptions = {}) =>
     clientTransport({
@@ -197,7 +201,12 @@ function assertSameBuild(
  * code a query gets for the same failure. `X_RPC_FAILED` was this branch until 21.0.0; the code
  * stays registered (shipped codes never change) and nothing in the framework throws it now.
  */
-function toUltimateError(text: string, status: number, name: string): UltimateError | undefined {
+function toUltimateError(
+  text: string,
+  status: number,
+  name: string,
+  retryAfterSeconds: number | undefined,
+): UltimateError | undefined {
   // `problemOf` is total — a gateway's HTML, an empty body and a truncated stream all answer `{}`,
   // which carries no `code` and therefore falls through to the transport's decode.
   const body = problemOf(text);
@@ -207,6 +216,9 @@ function toUltimateError(text: string, status: number, name: string): UltimateEr
     action: name,
     status,
     code,
+    // Core's reader, so an island titles an http refusal it never loaded the table for.
+    title: remoteTitleOf(body['title']),
+    retryAfterSeconds,
     // Parsed, never taken: `body` is whatever answered the request. A list this build cannot read
     // is dropped rather than repaired, and `cause` below still carries every rejection in it.
     issues: issuesFromWire(body['issues']),

package/src/contract-test.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Ctx } from '@ultimat3/core';
-import { createContext, isUltimateError, logger } from '@ultimat3/core';
+import { ctxOf, isJsonObject, isUltimateError, logger, renderFixShellArg } from '@ultimat3/core';
 import type { AnyAction } from './action';
 import { ActionDeniedError, ContractDriftError } from './errors';
 import { toOpenApiOperation } from './http';
@@ -14,7 +14,6 @@ import { actionName, invoke } from './invoke';
 import { buildOpenApi } from './openapi';
 import { listActions } from './registry';
 import { describeSampleGap, sampleGaps, sampleInput } from './sample-input';
-import { isJsonObject } from './stable';
 import { validateInput } from './validate';
 
 export interface ContractTest {
@@ -37,7 +36,7 @@ export interface ContractTestOptions {
 
 /** A context whose actor is core's anonymous actor — what a signed-out caller has. */
 export function anonymousCtx(): Ctx {
-  return createContext({});
+  return ctxOf({});
 }
 
 export function contractTestsFor(
@@ -95,13 +94,26 @@ function assertDocumented(target: AnyAction, name: string): void {
   const published = buildOpenApi({ actions }).paths[path];
   const owner = operationIdAt(published);
   if (owner === toOpenApiOperation(target).operationId) return;
-  throw new ContractDriftError(
+  throw documentedDrift(path, owner, name);
+}
+
+/**
+ * The refusal when the published document does not name this action at its route. `name` is
+ * whatever `.named()` was handed — nothing validates its alphabet — so it is screened where it
+ * enters the `x actions describe` command (security audit of plan 101 sweep 1c).
+ */
+export function documentedDrift(
+  path: string,
+  owner: string | undefined,
+  name: string,
+): ContractDriftError {
+  return new ContractDriftError(
     owner === undefined
       ? `OpenAPI document has no entry for ${path}`
       : `OpenAPI document serves ${path} as ${owner}, so ${name} is not in the published contract`,
     owner === undefined
       ? 'x verify --json   # the contract suite is a step of it'
-      : `x actions describe ${name} --json   # then rename it, or pin its own route with http: { path } in the ${name} definition`,
+      : `x actions describe ${renderFixShellArg(name, '<action>')} --json   # then rename it, or pin its own route with http: { path } in the ${name} definition`,
   );
 }
 
@@ -176,7 +188,7 @@ async function expectDenied(
     if (error instanceof ActionDeniedError) return;
     // `invoke` runs the policy's actor half → parse input → row → policy → handle → parse
     // output, and every stage lands here identically. Only `X_INPUT_INVALID` is attributable: it
-    // is what `validateInput` raises before `guard()` is reached (for a policy whose actor half
+    // is what `validateInput` raises before `guardAction()` is reached (for a policy whose actor half
     // could not decide), and `input:` is the knob that answers it. Any other
     // code — `X_TENANCY_UNSCOPED` from a `row:` loader, `X_DB_CONFLICT` from a handler,
     // `X_OUTPUT_INVALID` from the parse after it — keeps its own code and its own fix rather

package/src/error-titles.ts

@@ -0,0 +1,51 @@
+// @ultimat3/action's error TITLES, registered at import — the one module `sideEffects` names, so
+// `errors.ts` (the classes) is unlisted and a chunk carries it only where it constructs a class:
+// Bun >= 1.4.1 honours the array and keeps a listed module wherever the barrel reaches it.
+// `index.ts` imports this bare, because `problemError` rebuilds a server's refusal by code and reads
+// its title from the registry; `errors.ts` and its two siblings import it bare as well.
+
+import { registerErrorCodes } from '@ultimat3/core';
+
+/**
+ * Titles for the framework-wide code table — every one of them owned by this package.
+ * `X_INPUT_INVALID` and `X_RPC_FAILED` are action's: an action is where an input schema is
+ * enforced and where the typed client speaks, and `@ultimat3/query` only throws them.
+ * Authz codes are absent on purpose — `ActionDeniedError` re-uses the policy decision's code.
+ */
+export const ACTION_ERROR_TITLES: Readonly<Record<string, string>> = {
+  X_ACTION_DUPLICATE: 'two actions are registered under one name',
+  X_AUDIT_SINK_FAILED: 'an audited action ran and the audit sink refused its record',
+  X_AUDIT_SINK_MISSING: 'an action declares audit: true and no audit sink is installed',
+  X_ACTION_DEPRECATION_INVALID: 'an action declares a deprecation whose dates cannot be rendered',
+  X_ACTION_PATH_DUPLICATE: 'two actions derive one HTTP path',
+  X_ACTION_FOREIGN: 'a value that is not an action was projected as one',
+  X_ACTION_POLICY_MISSING: 'an action was registered without a policy',
+  X_ACTION_UNREGISTERED: 'an action was projected before it was registered',
+  X_CONTRACT_DRIFT: 'client and server disagree about the contract',
+  X_IDEMPOTENCY_CONFLICT: 'idempotency key reused with a different payload or still in flight',
+  X_IDEMPOTENCY_KEY_INVALID: 'an Idempotency-Key was sent that cannot identify one request',
+  X_IDEMPOTENCY_NOT_SHARED:
+    '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_MUTATOR_CLOCK_MISSING:
+    "a mutator declares conflict: 'last-write-wins' and its entity has no number clock column",
+  X_OUTPUT_INVALID: 'a handler returned a value its output schema rejects',
+  X_RPC_FAILED: 'an RPC call failed without a problem+json body',
+  X_ACTION_HTTP_PATH_INVALID: "an action's pinned http.path is not a static lowercase path",
+  X_ACTION_PATH_STYLE_INVALID: "defineApi's http.pathStyle is not a known style",
+  X_OPENAPI_CONFIG_INVALID: "defineApi's openapi block cannot produce a valid document",
+  X_ACTION_PATH_DERIVED_EARLY: 'a path was derived before pathStyle changed',
+  X_MUTATOR_NOT_IDEMPOTENT: 'a mutator is declared without idempotent: true',
+  X_IDEMPOTENCY_RESERVATION_LOST:
+    "an idempotent action's reservation was taken over before its transaction could settle it",
+  X_IDEMPOTENT_REPLAY_REDACTED: 'an idempotent replay would return a field redacted at rest',
+};
+
+// One unconditional call: a presence guard would turn "another package claims one of these codes"
+// from an X_ERROR_CODE_DUPLICATE at import into whichever module loaded first deciding the title.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(ACTION_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);

package/src/errors-http.ts

@@ -1,10 +1,12 @@
 /**
  * The refusals of the HTTP declaration an app makes about its actions: a pinned `http.path`, the
  * app's `pathStyle`, and the `openapi` block. Split from `errors.ts` at its ceiling; the codes and
- * titles stay registered there, one registry.
+ * titles are registered in `error-titles.ts`, one registry, imported bare so constructing one of
+ * these registers its title first.
  */
 
 import { renderCauseValue, UltimateError } from '@ultimat3/core';
+import './error-titles';
 
 export class ActionHttpPathInvalidError extends UltimateError {
   constructor(input: { name: string; path: unknown; reason: string }) {

package/src/errors-idempotency.ts

@@ -1,10 +1,11 @@
 /**
  * The 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
+ * stable code, exactly as there — the codes and their titles stay in `error-titles.ts`'s one
  * `registerErrorCodes` call, because a second registration is how two modules end up deciding a
- * title by load order.
+ * title by load order. Imported bare, so constructing one of these registers its title first.
  */
 import { renderCauseValue, UltimateError } from '@ultimat3/core';
+import './error-titles';
 // 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';
@@ -84,7 +85,7 @@ export class IdempotencyNotSharedError extends UltimateError {
 }
 
 /**
- * The replay of a first attempt that FAILED. It is a replay and not a re-run on purpose: `guard()`
+ * The replay of a first attempt that FAILED. It is a replay and not a re-run on purpose: `guardAction()`
  * 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
@@ -172,3 +173,20 @@ export class IdempotencyReservationLostError extends UltimateError {
     });
   }
 }
+
+/**
+ * A replay of a settled answer that had a field redacted at rest. Refused, never served: the
+ * stored copy holds `[redacted]` where the first caller got a credential, and handing that back
+ * as "the answer" is a silent wrong value. The first attempt RAN — a fresh key runs it again, so
+ * the fix names reading its effect as the way to recover the result.
+ */
+export class IdempotentReplayRedactedError extends UltimateError {
+  constructor(key: string) {
+    super({
+      code: 'X_IDEMPOTENT_REPLAY_REDACTED',
+      cause: `the answer stored for idempotency key "${key}" had a secret-named field redacted when it settled, so it cannot be replayed faithfully`,
+      fix: "x actions describe '<action>' --json   # the call already ran and showed its secret once — read its effect with a query; a new Idempotency-Key runs it again (a second credential)",
+      meta: { key, replayed: true },
+    });
+  }
+}