@ultimat3/action 23.0.0 → 25.0.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;
 
@@ -34,6 +34,8 @@ export interface MemoryAuditSinkOptions {
  * here: a non-zero count on a real deployment is the sink saying it is the wrong one.
  */
 export interface MemoryAuditSink extends AuditSink {
+  /** Synchronous here: the window is an array, so nothing is left for a caller to await. */
+  write(record: AuditRecord): void;
   /** The retained window, oldest first. A copy — the log cannot be mutated through it. */
   records(): readonly AuditRecord[];
   /** Retained right now — the bound, observable. */
@@ -44,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

@@ -5,11 +5,10 @@
  * production. Statements are spelled out so an agent can run the exact one it saw in a log.
  */
 
-import type { Actor } from '@ultimat3/core';
-import { uuid } from '@ultimat3/core';
+import type { Actor, PgExecutor } from '@ultimat3/core';
+import { uuidV7 } from '@ultimat3/core';
 import type { AuditRecord, AuditSink } from './audit';
 import { auditableInput } from './audit-input';
-import type { PgExecutor } from './idempotency-postgres';
 
 /**
  * Applied by the boot, never by an app migration — the rule `SQL_IDEMPOTENCY_TABLE` follows, and
@@ -35,6 +34,10 @@ import type { PgExecutor } from './idempotency-postgres';
  * 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 (
@@ -62,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);
@@ -80,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
 )
 `;
 
@@ -112,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
@@ -127,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,
@@ -150,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/cache-gate.ts

@@ -1,22 +1,41 @@
 /**
  * The post-commit cache bust — the only file in this package that calls `invalidateTags`.
- * The handler has already committed by the time it runs, so a fan-out that refuses degrades to
- * one logged failure instead of a failed action: the stale entries expire by TTL, and the caller
- * keeps the write it already made.
+ * Post-COMMIT, not post-handler: inside a transaction it waits for the root commit. A fan-out that
+ * refuses degrades to one logged failure instead of a failed action — the stale entries expire by
+ * TTL, and the caller keeps the write it already made.
  */
 
 import type { CacheTag, InvalidationReport } from '@ultimat3/cache';
 import { invalidateTags } from '@ultimat3/cache';
 import { logger } from '@ultimat3/core';
+import { type CommitScope, openCommitScope } from './tx-scope';
 
 /**
- * Fan `tags` out and never throw. `undefined` back means the fan-out itself refused and nothing
- * was cleared — an undeclared tag (`X_CACHE_TAG_UNKNOWN`) is the one an app hits. One dead tier
- * is not that case: `invalidateTags` absorbs those into `report.errors` and still reports.
+ * Fan `tags` out and never throw. `undefined` back means nothing was cleared BY THIS CALL: the
+ * fan-out refused — an undeclared tag (`X_CACHE_TAG_UNKNOWN`) is the one an app hits — or it was
+ * deferred. One dead tier is not that case: `invalidateTags` absorbs those into `report.errors`.
+ *
+ * Inside a transaction (`scope`, the ambient one unless a caller passes its own) the handler's rows
+ * are not durable when it returns. Busting there let a concurrent read refill the cache with the
+ * pre-commit rows, which then stayed for the TTL — and a rollback busted for a write nobody made.
+ * So the bust is handed to the ROOT commit, as `@ultimat3/entity`'s row observer hands its report:
+ * `onCommit` never fires for a transaction that rolled back or whose COMMIT was lost.
  */
 export async function bustAfterCommit(
   action: string,
   tags: readonly CacheTag[],
+  scope: CommitScope | undefined = openCommitScope(),
+): Promise<InvalidationReport | undefined> {
+  if (scope === undefined) return bust(action, tags);
+  // Not awaited, and it cannot be: a commit effect is synchronous and runs after the transaction
+  // is durable. `bust` never rejects, so there is no rejection for the missing await to lose.
+  scope.onCommit(() => void bust(action, tags));
+  return undefined;
+}
+
+async function bust(
+  action: string,
+  tags: readonly CacheTag[],
 ): Promise<InvalidationReport | undefined> {
   try {
     return await invalidateTags(tags);

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,12 +5,14 @@
  */
 
 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';
+import { servedActionRoute } from './http-path';
 import { actionName, invoke } from './invoke';
-import { derivePath } from './naming';
 import { buildOpenApi } from './openapi';
+import { listActions } from './registry';
 import { describeSampleGap, sampleGaps, sampleInput } from './sample-input';
 import { validateInput } from './validate';
 
@@ -34,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(
@@ -74,20 +76,54 @@ export function contractTestsFor(
     },
     {
       name: `${name}: OpenAPI document contains its operation`,
-      run: async () => {
-        const document = buildOpenApi({ actions: [target] });
-        const path = derivePath(name).path;
-        if (document.paths[path] === undefined) {
-          throw new ContractDriftError(
-            `OpenAPI document has no entry for ${path}`,
-            'x verify --json   # the contract suite is a step of it',
-          );
-        }
-      },
+      run: async () => assertDocumented(target, name),
     },
   ];
 }
 
+/**
+ * Against the document the APP publishes — the whole registry, plus this action when a test drives
+ * a `.named()` twin nothing seated — never one built from this action alone: that one holds its
+ * own path by construction, so the assertion could not fail. What can go wrong is in the rest of
+ * the registry: a second action deriving the same route, whose operation is the one published.
+ */
+function assertDocumented(target: AnyAction, name: string): void {
+  const seated = listActions();
+  const actions = seated.some((other) => other.name === name) ? seated : [...seated, target];
+  const { path } = servedActionRoute(name);
+  const published = buildOpenApi({ actions }).paths[path];
+  const owner = operationIdAt(published);
+  if (owner === toOpenApiOperation(target).operationId) return;
+  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 ${renderFixShellArg(name, '<action>')} --json   # then rename it, or pin its own route with http: { path } in the ${name} definition`,
+  );
+}
+
+/** `paths[path].post.operationId`, read off a value typed `unknown` — narrowed, never cast. */
+function operationIdAt(entry: unknown): string | undefined {
+  if (!isJsonObject(entry) || !isJsonObject(entry['post'])) return undefined;
+  const id = entry['post']['operationId'];
+  return typeof id === 'string' ? id : undefined;
+}
+
 /**
  * A `pattern` cannot be inverted, so the framework cannot build a payload for
  * `t.string.pattern(...)` — but the pattern IS in the IR, so it knows that BEFORE it invokes.
@@ -152,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