@ultimat3/action 1.2.0 → 3.0.0

package/src/errors.ts

@@ -2,10 +2,22 @@
  * Every failure @ultimat3/action can produce, one subclass per stable code so
  * callers `instanceof` a specific failure instead of string-matching a message.
  */
-import { assertNever, registerErrorCodes, UltimateError } from '@ultimat3/core';
+import {
+  assertNever,
+  ERROR_DOCS_BASE,
+  errorDocsUrl,
+  hasErrorCode,
+  registerErrorCodes,
+  UltimateError,
+} from '@ultimat3/core';
 import type { SurfaceDenial } from '@ultimat3/policy';
+// Type-only: `idempotency.ts` imports the error classes below, and a runtime edge here would
+// close the cycle. `verbatimModuleSyntax` is what makes that guarantee mechanical.
+import type { IdempotencyFailure } from './idempotency';
 
-const docs = (code: string): string => `https://ultimate.dev/errors/${code}`;
+// Core's spelling, aliased — never a second one. A local template drifts from what
+// `x errors explain` prints the moment `ERROR_DOCS_BASE` moves.
+const docs = errorDocsUrl;
 
 /**
  * Titles for the framework-wide code table — every one of them owned by this package.
@@ -15,11 +27,20 @@ const docs = (code: string): string => `https://ultimate.dev/errors/${code}`;
  */
 const OWNED_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_INPUT_INVALID: 'input failed schema validation',
   X_OUTPUT_INVALID: 'a handler returned a value its output schema rejects',
   X_RPC_FAILED: 'an RPC call failed without a problem+json body',
@@ -119,12 +140,36 @@ export class ActionDuplicateError extends UltimateError {
   }
 }
 
+/**
+ * Two distinct action names, one derived route. `X_ACTION_DUPLICATE` guards the NAME; nothing
+ * guarded the path, so `archiveOrder` and `archiveOrders` both registered, both projected to
+ * `POST /api/orders/archive`, and whichever the router seated last silently shadowed the other —
+ * while the shadowed action's OpenAPI operation and MCP tool went on advertising it.
+ */
+export class ActionPathDuplicateError extends UltimateError {
+  constructor(input: { name: string; existing: string; path: string }) {
+    super({
+      code: 'X_ACTION_PATH_DUPLICATE',
+      cause: `actions "${input.name}" and "${input.existing}" both derive ${input.path}`,
+      fix: `rename one export so the two derive different paths — x actions list --json prints every derived route`,
+      docs: docs('X_ACTION_PATH_DUPLICATE'),
+    });
+  }
+}
+
+/**
+ * The action's NAME goes in the cause and the permission's SHAPE goes in the fix — the two are not
+ * interchangeable. `can()` takes `resource:verb` (`Permission` is `` `${string}:${string}` ``), so
+ * the `can('<the action name>')` this used to emit was a snippet that could not compile, and
+ * `assertPermission` would refuse it once the app declared its own set. Same split
+ * `@ultimat3/policy`'s own `policyMissing()` makes, and the same repair `X_QUERY_POLICY_MISSING` took.
+ */
 export class ActionPolicyMissingError extends UltimateError {
   constructor(name: string) {
     super({
       code: 'X_ACTION_POLICY_MISSING',
       cause: `action "${name}" was registered without a policy`,
-      fix: `add \`policy: can('${name}')\` to the action definition in the file that exports it`,
+      fix: `add \`policy: can('<resource>:<verb>')\` to the action() that exports "${name}" — a permission your definePermissions() call declares, never the action's own name — or \`allow('<resource>:<verb>')\` if the operation is genuinely public`,
       docs: docs('X_ACTION_POLICY_MISSING'),
     });
   }
@@ -176,6 +221,179 @@ export class IdempotencyConflictError extends UltimateError {
   }
 }
 
+export type IdempotencyKeyProblem = 'empty' | 'too-long';
+
+/**
+ * The header arrived and cannot name one request. Refused, never read as absent: `Headers.get()`
+ * answers `''` for `Idempotency-Key:` rather than `null`, so a blank value became a live key that
+ * every caller sending a blank header shared — and reading it as "no key" is the quieter failure,
+ * because a client whose key interpolation produced nothing would lose the protection silently
+ * and double-charge on its own retry. `@ultimat3/jobs` refuses an empty key at the enqueue for the
+ * same reason; it uses `assert` because the empty key there is the app's own declaration, while
+ * this one is a caller's header and therefore a 4xx.
+ *
+ * The length bound is the one the OpenAPI operation has always published (`maxLength: 255`).
+ * A contract that disagrees with the runtime is worse than no contract.
+ */
+export class IdempotencyKeyInvalidError extends UltimateError {
+  constructor(action: string, problem: IdempotencyKeyProblem, length: number) {
+    super({
+      code: 'X_IDEMPOTENCY_KEY_INVALID',
+      cause:
+        problem === 'empty'
+          ? `action "${action}" was called with an empty Idempotency-Key, which every caller sending a blank header would share`
+          : `action "${action}" was called with an Idempotency-Key of ${length} characters, past the 255 its OpenAPI operation publishes`,
+      fix: 'set the Idempotency-Key header to a fresh crypto.randomUUID() on the client, one per request — or omit the header entirely to run this call without idempotency',
+      docs: docs('X_IDEMPOTENCY_KEY_INVALID'),
+      meta: { action, problem, length },
+    });
+  }
+}
+
+/**
+ * The deployment declared `scope: 'shared'` and the installed store cannot keep it. Refused at
+ * registration, before a socket opens, because the failure it replaces is silent and expensive:
+ * a per-process store under `replicas: 3` means the retry that lands on another replica finds no
+ * record, re-runs the handler, and charges the card again — with nothing anywhere saying it did.
+ * An UNDECLARED scope is refused the same way: what cannot be shown to be shared is not assumed
+ * to be, the rule `assertRouteBuckets` already applies to a limiter that publishes no table.
+ */
+export class IdempotencyNotSharedError extends UltimateError {
+  constructor(storeScope: string | undefined) {
+    super({
+      code: 'X_IDEMPOTENCY_NOT_SHARED',
+      cause:
+        storeScope === undefined
+          ? "configureIdempotency({ scope: 'shared' }) is declared and the installed idempotency store declares no scope"
+          : `configureIdempotency({ scope: 'shared' }) is declared and the installed idempotency store is ${storeScope}`,
+      // NOT `executor: Bun.sql` — `Bun.sql.query` is `undefined` (it is a tagged template whose
+      // positional form is `unsafe`), so that line compiled and would have thrown on the first
+      // reservation. The framework's own boot already installs this store; a host booting the
+      // framework itself wraps the client it opened.
+      fix: "the framework boot installs a shared store — reach this only from a host that boots it itself: setIdempotencyStore(postgresIdempotencyStore({ executor: { query: (text, values) => client.query({ text, values }) } })) from '@ultimat3/action', or drop the declaration to configureIdempotency({ scope: 'process' })",
+      docs: docs('X_IDEMPOTENCY_NOT_SHARED'),
+      meta: { storeScope: storeScope ?? null },
+    });
+  }
+}
+
+/**
+ * The replay of a first attempt that FAILED. It is a replay and not a re-run on purpose: `guard()`
+ * and the input parse both run before the idempotency gate, so everything the gate can see throw
+ * is post-authorization and possibly post-commit — a handler that took the money and then failed
+ * its own `output:` schema is the case this exists for. Releasing the reservation there let the
+ * client's automatic retry charge a second time, which made idempotency the cause of the double
+ * charge it exists to prevent.
+ *
+ * The first attempt's code is re-used verbatim, the way `RemoteActionError` re-uses the server's:
+ * the caller is owed the failure it would have got, not a new one. `X_IDEMPOTENCY_REPLAYED_FAILURE`
+ * is the code only when the original throw carried none of its own.
+ */
+export class IdempotencyReplayedFailureError extends UltimateError {
+  /** The recorded first attempt, so a caller reads the original code without parsing a message. */
+  readonly failure: IdempotencyFailure;
+
+  constructor(key: string, failure: IdempotencyFailure | undefined) {
+    const recorded: IdempotencyFailure = failure ?? {
+      code: 'X_IDEMPOTENCY_REPLAYED_FAILURE',
+      cause: 'the first attempt under this key failed and the store kept no detail of it',
+      fix: 'read the first attempt in the logs, then send a fresh Idempotency-Key once the cause is fixed',
+    };
+    super({
+      code: recorded.code,
+      cause: `${recorded.cause} — replayed from the first attempt under Idempotency-Key "${key}", which may have committed before it failed`,
+      fix: recorded.fix,
+      ...(recorded.docs === undefined ? {} : { docs: recorded.docs }),
+      // `replayed` is what tells an operator this is not a second execution: nothing ran here.
+      meta: { origin: 'idempotent-replay', key, replayed: true, code: recorded.code },
+    });
+    this.failure = recorded;
+  }
+}
+
+/**
+ * A `deprecated:` block whose dates cannot become the headers it promises. Refused where the
+ * declaration is converted, so the route and the OpenAPI operation refuse the same value — the
+ * same shape as `@ultimat3/http`'s `X_RATE_LIMIT_INVALID`, and for the same reason: a `Sunset` that
+ * renders `Invalid Date` is a contract statement no client can act on.
+ */
+export class ActionDeprecationInvalidError extends UltimateError {
+  constructor(action: string, field: string, value: string) {
+    super({
+      code: 'X_ACTION_DEPRECATION_INVALID',
+      cause: `action "${action}" declares deprecated.${field} as "${value}", which is not a date`,
+      fix: `edit \`deprecated: { ${field}: … }\` on ${action} to an ISO-8601 instant — e.g. '2026-12-31T23:59:59Z'`,
+      docs: docs('X_ACTION_DEPRECATION_INVALID'),
+      meta: { action, field, value },
+    });
+  }
+}
+
+/** What the wire said, once `client.ts` has decided the body really is a problem document. */
+export interface RemoteFailure {
+  /** The action that was called — `meta` carries it, so a report names the call, not just a code. */
+  readonly action: string;
+  readonly status: number;
+  /** The server's code, kept verbatim: matching on it is why problem+json carries one. */
+  readonly code: string;
+  readonly cause: string;
+  readonly fix: string;
+  /**
+   * The links the server offered, most specific first. Never synthesized from the code, and
+   * never trusted for being present — the first one that is an absolute HTTP(S) URL wins, so
+   * a `javascript:` in the preferred slot cannot suppress a usable link behind it.
+   */
+  readonly docs?: readonly (string | undefined)[] | undefined;
+}
+
+/** A link, not a string the server happened to put in a field the overlay renders as an href. */
+const ABSOLUTE_HTTP_URL = /^https?:\/\//;
+
+/**
+ * The docs link, or the honest absence of one. `UltimateError` resolves an unregistered code to
+ * `https://ultimate.dev/errors/<code>`, and a code the SERVER owns — `X_SIGNUP_CLOSED`, declared
+ * by the app through `registerErrorStatus` — is exactly the kind this bundle never registered:
+ * that URL is a 404 dressed as documentation, printed under `docs:` as if the framework wrote the
+ * page. So: the server's own link when it sent a resolvable one, this build's registered link
+ * when it knows the code, and otherwise the index — a page that exists.
+ *
+ * `sent` is ordered, not singular: a server that fills `docs` with a `javascript:` URI still
+ * sent RFC-9457's `type`, and taking the first *resolvable* candidate means the unusable one
+ * costs nothing. Testing only the preferred slot would have dropped a valid link on the floor.
+ */
+function remoteDocs(code: string, sent: readonly (string | undefined)[] = []): string | undefined {
+  const link = sent.find((value) => value !== undefined && ABSOLUTE_HTTP_URL.test(value));
+  if (link !== undefined) return link;
+  // `undefined` lets the constructor resolve the REGISTERED descriptor, whose docs a package
+  // may have declared as something other than the default URL.
+  return hasErrorCode(code) ? undefined : ERROR_DOCS_BASE;
+}
+
+/**
+ * A failure the SERVER raised, rebuilt from `application/problem+json` in the browser. The code
+ * is the server's — this package invents none, the same rule `ActionDeniedError` follows for a
+ * policy decision — but a code the server owns is one this bundle may never have registered, so
+ * the error says where it came from rather than passing as locally declared: `name` marks it in
+ * a stack trace and `meta.origin` marks it in `--json`, the dev overlay and the error reporter.
+ * `RpcFailedError` stays the answer when no framework code came back at all.
+ */
+export class RemoteActionError extends UltimateError {
+  override readonly name = 'RemoteActionError';
+  /** The status that carried it — typed, so a caller never digs it back out of `meta`. */
+  readonly status: number;
+
+  constructor(failure: RemoteFailure) {
+    super({
+      code: failure.code,
+      cause: failure.cause,
+      fix: failure.fix,
+      docs: remoteDocs(failure.code, failure.docs),
+      meta: { origin: 'remote', action: failure.action, status: failure.status },
+    });
+    this.status = failure.status;
+  }
+}
+
 /** The client got a non-`problem+json` failure — a proxy, not our server, answered. */
 export class RpcFailedError extends UltimateError {
   constructor(name: string, status: number) {
@@ -188,6 +406,61 @@ export class RpcFailedError extends UltimateError {
   }
 }
 
+/**
+ * `audit: true` with no sink installed. Raised before the input parse, so an action nobody can
+ * record has made no write to be inconsistent about — the one audit failure that costs nothing.
+ * There is deliberately no logger-backed default sink to fall back on: a line nobody stores
+ * satisfies the declaration while recording nothing, which is the silent pass this code exists
+ * to turn into a stop.
+ */
+export class AuditSinkMissingError extends UltimateError {
+  constructor(action: string) {
+    super({
+      code: 'X_AUDIT_SINK_MISSING',
+      cause: `action "${action}" declares \`audit: true\` and no audit sink is installed`,
+      fix: "call setAuditSink(yourSink) from '@ultimat3/action' at boot, before registerActions()",
+      docs: docs('X_AUDIT_SINK_MISSING'),
+    });
+  }
+}
+
+/**
+ * The sink refused a record for an attempt that SUCCEEDED. The opposite call to the cache tier's
+ * `bestEffort`, and for the opposite reason: a dropped cache entry expires by TTL and the stack
+ * self-heals, while nothing ever re-derives an audit row that was never written. So the caller is
+ * told rather than left believing the operation was recorded.
+ *
+ * The cause says what the fix cannot undo: the handler already committed.
+ *
+ * **The fix branches, because only one of the two is true.** "Retry with the same
+ * Idempotency-Key" is safe exactly when this invocation went through the idempotency store —
+ * the settled record is then replayed and the record is re-attempted without re-running the
+ * handler. It did not when the action is not `idempotent`, and it did not when the action IS
+ * `idempotent` and the caller sent no key: `invoke` reads
+ * `def.idempotent === true ? (options.idempotencyKey ?? null) : null`, so both collapse to the
+ * same `null`. Telling either one to retry instructs a caller to apply a committed write twice
+ * — the worst possible advice for a mutator, and an axiom-4 violation dressed as a fix line.
+ * `replayable` is therefore the invocation's own fact (`record.idempotencyKey !== null`), never
+ * the declaration's: requiring `idempotent: true` at declaration would not have made the
+ * original message true, since a caller may still omit the header.
+ */
+export class AuditSinkFailedError extends UltimateError {
+  constructor(action: string, sourceError: unknown, replayable: boolean) {
+    super({
+      code: 'X_AUDIT_SINK_FAILED',
+      cause: `"${action}" ran and its audit sink refused the record, so the change is unrecorded — the handler had already committed`,
+      fix: replayable
+        ? `fix the sink installed by setAuditSink, then retry with the same Idempotency-Key — the replay re-records without re-running the handler`
+        : `fix the sink installed by setAuditSink, then reconcile this one change by hand — do NOT retry: ${action} ran with no Idempotency-Key, so a second call runs the committed handler again. Add \`idempotent: true\` and send the header to make retries safe`,
+      docs: docs('X_AUDIT_SINK_FAILED'),
+      // Read by `--json` and the error reporter: whether a retry is safe is the one decision an
+      // operator makes here, so it is a field and not only a sentence.
+      meta: { action, replayable },
+      sourceError,
+    });
+  }
+}
+
 export class ContractDriftError extends UltimateError {
   constructor(cause: string, fix: string) {
     super({ code: 'X_CONTRACT_DRIFT', cause, fix, docs: docs('X_CONTRACT_DRIFT') });

package/src/http.ts

@@ -5,10 +5,17 @@
  * there is no way to mount an action without them.
  */
 
-import { isUltimateError } from '@ultimat3/core';
+import { tagKeys } from '@ultimat3/cache';
+import { isMcpExposed, isUltimateError } from '@ultimat3/core';
 import type { Route, RouteMeta, UltimateRequest } from '@ultimat3/http';
-import { json, problem } from '@ultimat3/http';
+// `toBucket` is `@ultimat3/http`'s, not this package's: http owns `Bucket` and the limiter maths,
+// and `@ultimat3/query` needs the identical conversion while being the same tier as this one — so
+// a copy here would be a second answer to "what does this limit mean" for the read half.
+import { json, problem, redirect, takeRedirect, toBucket } from '@ultimat3/http';
 import type { ActionRateLimit, AnyAction } from './action';
+import type { Deprecation } from './deprecation';
+import { applyHeaders, recordDeprecatedCall, renderDeprecation } from './deprecation';
+import { ActionDeprecationInvalidError } from './errors';
 import { actionName, defOf, invoke } from './invoke';
 import {
   derivePath,
@@ -17,12 +24,11 @@ import {
   PROBLEM_SCHEMA_NAME,
   schemaRef,
   toOperationId,
-  toToolName,
 } from './naming';
 import { policyCapability } from './policy-gate';
-import { tagKeys } from './tags';
 
-/** Matches `HttpConfig.buildIdHeader`; the pipeline reads it into `ctx.buildId`. */
+/** Matches `HttpConfig.buildIdHeader`; the pipeline reads it into `ctx.clientBuildId` — the
+ * CLIENT's claim, never `ctx.buildId`, which is the build this process serves. */
 export const BUILD_ID_HEADER = 'x-ultimate-build';
 export const IDEMPOTENCY_HEADER = 'idempotency-key';
 export const REPLAYED_HEADER = 'x-ultimate-replayed';
@@ -36,8 +42,12 @@ export function toRoute(target: AnyAction): Route {
   const name = actionName(target);
   const { path, resource } = derivePath(name);
   const def = defOf(target);
+  // Rendered ONCE, at projection: a date that cannot become a header is a mount-time refusal,
+  // not a surprise on the first request — the same rule `toBucket` follows for a rate limit.
+  const sunsetting = deprecationHeadersFor(name, def.deprecated);
 
   const handler = async (req: UltimateRequest): Promise<Response> => {
+    if (sunsetting !== undefined) recordDeprecatedCall('action', name);
     try {
       // The pipeline already parsed and size-capped the body; parsing it again here
       // would be a second, differently-behaved parser for the same bytes.
@@ -51,14 +61,26 @@ export function toRoute(target: AnyAction): Route {
           replayed = true;
         },
       });
-      const response = json(result);
+      // The one thing an action's return value cannot say. `setRedirect()` inside the handler
+      // is how a `<form method="post">` gets an answer a browser follows — a `Location` on the
+      // 200 this used to always return is a header browsers ignore, so a JS-less form left the
+      // reader staring at `{"ok":true}`. Only this projection honours it: a redirect is an HTTP
+      // fact, and the MCP tool and the job handle share none of it.
+      const to = takeRedirect(req.ctx);
+      const response = to === undefined ? json(result) : redirect(to.location, to.status);
       if (key !== null) response.headers.set(REPLAYED_HEADER, replayed ? '1' : '0');
+      // On the failure path too, below: a client polling a deprecated endpoint that is currently
+      // 403ing still has to learn the endpoint is going away. Announcing it only on 200 hides the
+      // sunset from exactly the callers most likely to be stale.
+      if (sunsetting !== undefined) applyHeaders(response, sunsetting);
       return response;
     } catch (error) {
       // Framework errors carry their own code, status and fix line; anything else is
       // a bug and belongs to the server's error boundary, not to this route.
-      if (isUltimateError(error)) return problem(error);
-      throw error;
+      if (!isUltimateError(error)) throw error;
+      const response = problem(error);
+      if (sunsetting !== undefined) applyHeaders(response, sunsetting);
+      return response;
     }
   };
 
@@ -76,7 +98,12 @@ export function toRoute(target: AnyAction): Route {
     input: def.input,
     cache: { mode: 'no-store', tags: tagKeys(def.cache?.invalidates ?? []) },
     tags: [resource],
-    ...(def.rateLimit === undefined ? {} : { rateLimit: name }),
+    // Name AND numbers. The name alone selected a bucket the limiter's table never held, so
+    // `bucketFor` fell through to `default` — 120 burst for an action that declared 5. The
+    // numbers ride along and `withRouteBuckets` registers them at construction.
+    ...(def.rateLimit === undefined
+      ? {}
+      : { rateLimit: name, rateLimitBucket: toBucket(name, def.rateLimit) }),
     ...(def.mcp?.description === undefined ? {} : { description: def.mcp.description }),
   };
 
@@ -87,6 +114,9 @@ export interface OpenApiOperation {
   readonly operationId: string;
   readonly tags: readonly string[];
   readonly summary: string;
+  /** OpenAPI's own flag. Absent — not `false` — when nothing is deprecated, so the spec bytes
+   * of an app that deprecates nothing are unchanged and `x verify`'s contract diff stays quiet. */
+  readonly deprecated?: boolean;
   readonly parameters: readonly Record<string, unknown>[];
   readonly requestBody: Record<string, unknown>;
   readonly responses: Record<string, unknown>;
@@ -99,10 +129,12 @@ export function toOpenApiOperation(target: AnyAction): OpenApiOperation {
   const def = defOf(target);
   const path = derivePath(name);
   const idempotent = def.idempotent === true;
+  const deprecation = deprecationMetaFor(name, def.deprecated);
   return {
     operationId: toOperationId(name),
     tags: [path.resource],
     summary: def.mcp?.description ?? name,
+    ...(deprecation === undefined ? {} : { deprecated: true }),
     parameters: idempotent ? [IDEMPOTENCY_PARAMETER] : [],
     requestBody: {
       required: true,
@@ -121,14 +153,59 @@ export function toOpenApiOperation(target: AnyAction): OpenApiOperation {
       capability: policyCapability(def.policy),
       idempotent,
       invalidates: tagKeys(def.cache?.invalidates ?? []),
-      mcpTool: def.mcp?.expose === false ? null : toToolName(name),
-      rateLimit: rateLimitMeta(def.rateLimit),
+      // The tool name an agent would call, or `null` when there is no tool. `!== false` here
+      // advertised one for every action, so an agent reading the spec asked for a tool the MCP
+      // catalog never listed — `isMcpExposed` is the same answer `toMcpTool` gives. The NAME was
+      // the second half of the same defect: `toToolName` published `publish_post` while
+      // `@ultimat3/mcp` served `publishPost`, so a spec-reading agent called a tool that does not
+      // exist. Verbatim, and never derived — this is a published contract, not a label.
+      mcpTool: isMcpExposed(def.mcp) ? name : null,
+      rateLimit: rateLimitMeta(name, def.rateLimit),
+      // The dates as data, beside the boolean flag OpenAPI defines: `deprecated: true` says an
+      // operation is going away and nothing else, so a client that wants to plan the migration
+      // has to read the sunset out of prose. Absent, not null, for the same byte-stability
+      // reason `deprecated` is.
+      ...(deprecation === undefined ? {} : { deprecation }),
     },
   };
 }
 
-function rateLimitMeta(limit: ActionRateLimit | undefined): Record<string, number> | null {
-  return limit === undefined ? null : { limit: limit.limit, windowMs: limit.windowMs };
+/**
+ * The headers this action's `deprecated:` block renders to, or nothing. The successor's URL comes
+ * from `derivePath` — the same derivation the route and the client use, never a second one.
+ */
+function deprecationHeadersFor(
+  name: string,
+  deprecated: Deprecation | undefined,
+): Readonly<Record<string, string>> | undefined {
+  if (deprecated === undefined) return undefined;
+  const successor =
+    deprecated.replacedBy === undefined ? undefined : derivePath(deprecated.replacedBy).path;
+  const rendered = renderDeprecation(deprecated, successor);
+  if (!rendered.ok) throw new ActionDeprecationInvalidError(name, rendered.field, rendered.value);
+  return rendered.headers;
+}
+
+/** The same declaration as spec data. Validated through the same render, so the two agree. */
+function deprecationMetaFor(
+  name: string,
+  deprecated: Deprecation | undefined,
+): Readonly<Record<string, string>> | undefined {
+  if (deprecated === undefined) return undefined;
+  const rendered = renderDeprecation(deprecated, undefined);
+  if (!rendered.ok) throw new ActionDeprecationInvalidError(name, rendered.field, rendered.value);
+  return rendered.meta;
+}
+
+function rateLimitMeta(
+  name: string,
+  limit: ActionRateLimit | undefined,
+): Record<string, number> | null {
+  if (limit === undefined) return null;
+  // Validated through the same call the route makes, so the spec cannot publish a pair the
+  // limiter would have refused to run on.
+  toBucket(name, limit);
+  return { limit: limit.limit, windowMs: limit.windowMs };
 }
 
 const IDEMPOTENCY_PARAMETER: Record<string, unknown> = {

package/src/idempotency-key.ts

@@ -0,0 +1,47 @@
+/**
+ * What an idempotency record is filed under: the action, the CALLER, and the caller's key —
+ * one JSON tuple, so no part of it can spell another. A key scoped to the action name alone was a
+ * key space every caller shared, and a blank header is refused rather than read as no key at all.
+ */
+import type { Actor } from '@ultimat3/core';
+import { IdempotencyKeyInvalidError } from './errors';
+
+/**
+ * The bound the OpenAPI operation has always published for the `Idempotency-Key` parameter. It is
+ * enforced here so the spec and the runtime say the same thing — and because the key is
+ * caller-chosen, which makes its length the caller's choice of how much store to occupy.
+ */
+export const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+
+/**
+ * Keys are namespaced per action AND per caller: the same key under two actions is two keys, and
+ * the same key from two callers is two keys.
+ *
+ * The caller half is the fix for a real replay across identities — alice POSTs `charge` with a
+ * key, bob POSTs `charge` with the same key and was handed alice's stored response; with a
+ * differing payload bob got `X_IDEMPOTENCY_CONFLICT` instead, so any key he guessed was a key he
+ * could deny her.
+ *
+ * **The encoding is a JSON tuple and never a joined string**, the reasoning `@ultimat3/query`'s
+ * `readAuthority` states: an actor id is app data, so a caller who can choose one can spell
+ * whatever separator the key uses. Under `${action}:${id}:${key}`, id `alice:x` with key `y` and
+ * id `alice` with key `x:y` are one record. Fixed arity plus JSON escaping means no value can
+ * move a boundary.
+ *
+ * The limit it does NOT close: an anonymous actor has no identity to narrow to, so every
+ * anonymous caller of a public idempotent action still shares one key space. Nothing at this tier
+ * can tell two of them apart, and narrowing to something that is not identity (an IP, a session
+ * cookie) would break the retry it exists to serve.
+ */
+export function idempotencyKeyFor(actionName: string, key: string, actor: Actor): string {
+  if (key.trim().length === 0) {
+    throw new IdempotencyKeyInvalidError(actionName, 'empty', key.length);
+  }
+  if (key.length > MAX_IDEMPOTENCY_KEY_LENGTH) {
+    throw new IdempotencyKeyInvalidError(actionName, 'too-long', key.length);
+  }
+  // The same three fields every other caller-scoped key in the framework is built from
+  // (`readAuthority`, `scopeKey`): kind, id, org. Two of them alone is one identity too few —
+  // a `service` and a `user` may hold the same id, and one actor's org is what a tenant sees.
+  return JSON.stringify([actionName, actor.kind, actor.id, actor.orgId ?? null, key]);
+}