@ultimat3/action 24.0.0 → 25.1.0

package/src/job-handle.ts

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

package/src/json-schema.ts

@@ -3,9 +3,10 @@
  * MCP tool's schema is `@ultimat3/schema`'s `toWireSchema` — the one `tools/list` serves.
  */
 
+import { isJsonObject } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { SchemaUnsupportedError, toJsonSchema } from '@ultimat3/schema';
-import { isJsonObject, stableStringify } from './stable';
+import { stableStringify } from './stable';
 
 export type JsonSchemaObject = Record<string, unknown>;
 

package/src/mutator.ts

@@ -5,7 +5,7 @@
  * contract tests for free, and its authz is the same single evaluation.
  */
 
-import type { ConflictPolicy, Ctx, Row } from '@ultimat3/core';
+import type { ConflictPolicy, Ctx, Deprecation, Row } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type {
   Action,
@@ -17,7 +17,6 @@ import type {
   ActionRowArgs,
 } from './action';
 import { action, isAction } from './action';
-import type { Deprecation } from './deprecation';
 import { MutatorNotIdempotentError } from './errors';
 import type { ActionHttp } from './http-path';
 import { assertConflictClock } from './mutator-clock';

package/src/naming.ts

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

package/src/openapi-complete.ts

@@ -79,10 +79,25 @@ interface Refusals {
   readonly unauthorizedHeaders?: Record<string, unknown>;
 }
 
+/**
+ * An ACTION's limit is spent inside `invoke`, so its route carries no bucket to read; the operation
+ * itself publishes the declaration (`x-ultimate.rateLimit`, `null` when none). A query's route
+ * still does, hence both reads above.
+ */
+function declaresRateLimit(operation: Operation): boolean {
+  const extensions = operation['x-ultimate'];
+  if (typeof extensions !== 'object' || extensions === null) return false;
+  const declared = (extensions as Record<string, unknown>)['rateLimit'];
+  return declared !== undefined && declared !== null;
+}
+
 /** One operation, with its route's refusals and security added. Never mutates `operation`. */
 function completeOperation(operation: Operation, route: Route | undefined, refusals: Refusals) {
   const authenticated = route?.meta.auth === 'required';
-  const limited = refusals.everyOpLimited || route?.meta.rateLimitBucket !== undefined;
+  const limited =
+    refusals.everyOpLimited ||
+    route?.meta.rateLimitBucket !== undefined ||
+    declaresRateLimit(operation);
   if (!authenticated && !limited) return operation;
   const responses = { ...(operation['responses'] as Record<string, unknown>) };
   if (limited) {

package/src/policy-gate.ts

@@ -1,18 +1,13 @@
 /**
  * The single point of contact with @ultimat3/policy. Every surface (HTTP, MCP,
- * job, direct server call) reaches authz through `guard()` — there is no second
+ * job, direct server call) reaches authz through `guardAction()` — there is no second
  * code path, which is what makes "one authz system" true rather than aspirational.
  */
 
 import type { Actor, Ctx } from '@ultimat3/core';
-import { assertNever, isAnonymous } from '@ultimat3/core';
+import { assertNever } from '@ultimat3/core';
 import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
-import {
-  enforce,
-  enforceBeforeInput,
-  policyPermissions as flattenedPermissions,
-  admitsAnonymous as policyAdmitsAnonymous,
-} from '@ultimat3/policy';
+import { enforce, enforceBeforeInput } from '@ultimat3/policy';
 import { ActionDeniedError } from './errors';
 
 /**
@@ -45,7 +40,7 @@ export interface PolicySubject {
  * object for every surface, so an actor denied over HTTP is denied over MCP with
  * the same reason and the same code.
  */
-export function guard(policy: ActionPolicy, subject: PolicySubject, surface: Surface): void {
+export function guardAction(policy: ActionPolicy, subject: PolicySubject, surface: Surface): void {
   const denial = enforce(policySurface(surface), policy, {
     input: subject.input,
     actor: subject.actor,
@@ -58,13 +53,13 @@ export function guard(policy: ActionPolicy, subject: PolicySubject, surface: Sur
 }
 
 /**
- * The actor-only half of `guard`, run BEFORE the input is parsed: a caller the policy refuses
+ * The actor-only half of `guardAction`, run BEFORE the input is parsed: a caller the policy refuses
  * whatever they send gets the 403 (or 401) here, and never the 400 whose issue list describes
  * the input schema of an operation they may not call. Undecided — a predicate that reads the input
- * or the row — passes, and `guard` decides after the parse exactly as before. Same denial class,
- * same code, same surface rendering as `guard`'s.
+ * or the row — passes, and `guardAction` decides after the parse exactly as before. Same denial
+ * class, same code, same surface rendering as `guardAction`'s.
  */
-export function guardBeforeInput(
+export function guardActionBeforeInput(
   policy: ActionPolicy,
   subject: Omit<PolicySubject, 'input' | 'row'>,
   surface: Surface,
@@ -90,41 +85,3 @@ function policySurface(surface: Surface): PolicySurface {
       return assertNever(surface);
   }
 }
-
-/**
- * Core models "nobody" as an anonymous actor; policy models it as `null`, which is
- * what turns a missing session into `X_UNAUTHENTICATED` instead of a bare denial.
- */
-export function actorOf(ctx: Ctx): Actor | null {
-  return isAnonymous(ctx.actor) ? null : ctx.actor;
-}
-
-/** The capability an action requires, for manifests and OpenAPI metadata. A DISPLAY label. */
-export function policyCapability(policy: ActionPolicy): string {
-  return policy.label;
-}
-
-/**
- * Every permission the policy tree references, flattened and deduped — and the only field a
- * compliance report may match a grant against. `label` renders a composite as
- * `and(post:publish, org:administer)`, which is a sentence and never equals a permission string,
- * so matching on it reported every action guarded by a composite as enforcing nothing: `x policy
- * list` showed real grants as dead. The two are kept side by side rather than one replacing the
- * other — the label is what a human reads, this is what a machine compares.
- */
-export function policyPermissions(policy: ActionPolicy): readonly string[] {
-  return flattenedPermissions(policy);
-}
-
-/**
- * Whether a policy admits an ANONYMOUS caller — `@ultimat3/policy`'s answer, re-exported here so
- * `http.ts` reads it through this file like every other authz question. `toRoute` derives
- * `meta.auth` from it, never from `policy.kind === 'allow'`: that read looked at the ROOT
- * combinator only, so `or(allow(), can('x:y'))` was 401'd by the pipeline before `invoke` ran
- * while the MCP tool and the job handle allowed it. `true` is not "unguarded" — `invoke` still
- * evaluates the policy for every call. Declared once in `policy.ts`, exactly as
- * `policyPermissions` is: the answer is a property of the combinators it walks.
- */
-export function admitsAnonymous(policy: ActionPolicy): boolean {
-  return policyAdmitsAnonymous(policy);
-}

package/src/rate-limit-gate.ts

@@ -0,0 +1,114 @@
+/**
+ * Where a declared `rateLimit:` is spent: once, inside `invoke`, so HTTP, MCP, the in-app agent
+ * tool and `.job()` draw on ONE bucket. The store is `@ultimat3/http`'s installed one — the slot
+ * `@ultimat3/query` spends from too, filled at boot with the instance `httpServer` is handed.
+ */
+
+import type { Ctx } from '@ultimat3/core';
+import { asyncContext, isAnonymous } from '@ultimat3/core';
+import type { RateLimitDecision } from '@ultimat3/http';
+// The bucket maths, the subject precedence and the refusal are all `@ultimat3/http`'s (tier 2):
+// a copy here would be a second answer to "what does this limit mean" and "whose bucket is it".
+import { installedRateLimitStore, rateLimited, rateLimitSpends, toBucket } from '@ultimat3/http';
+import type { ActionRateLimit } from './action';
+import type { Surface } from './policy-gate';
+
+/**
+ * Who a call chain started from: the address of the request, or the fact that it is a job run.
+ * An `agent()` is an action whose handler calls its tools through `invoke` with no address of its
+ * own, so without this every anonymous visitor's tool calls shared one `ip:unknown` bucket and one
+ * visitor could exhaust it for all. Opened by `invoke`; read by every nested call that has none.
+ */
+interface CallerFrame {
+  readonly address: string | null;
+  /** Inside a job run: nested calls are the job's, never a visitor's. */
+  readonly job: boolean;
+}
+
+const callerFrame = asyncContext<CallerFrame>('the caller frame');
+
+/** Run `fn` with `address` as the inherited caller address; an absent one changes nothing. */
+export function withCallerAddress<T>(address: string | null | undefined, fn: () => T): T {
+  return typeof address === 'string' && address !== ''
+    ? callerFrame.run({ address, job: false }, fn)
+    : fn();
+}
+
+/**
+ * Run `fn` as a job: no inherited address, and every nested call unattributed unless it has an
+ * actor or an org of its own. A FRESH frame, not a read of the current one — a worker loop re-armed
+ * by `setTimeout` inside a request carries that request's frame, and a tenantless job charged to
+ * whichever visitor happened to start the loop is the leak this closes.
+ */
+export function withJobFrame<T>(fn: () => T): T {
+  return callerFrame.run({ address: null, job: true }, fn);
+}
+
+/**
+ * The subject of a job run nobody attributed — no actor, no tenant. Its own population: sharing
+ * `ip:unknown` let a flood of unaddressed anonymous requests park every tenantless job, and the
+ * reverse. Still ONE bucket for all such runs, deliberately: unlimited is the abuse this exists for.
+ */
+const UNATTRIBUTED_JOB = 'job:unattributed';
+
+/**
+ * Namespaced, never the bare action name: the HTTP pipeline still spends its `default` bucket
+ * under `<route name>|<subject>`, and one key taken against two bucket shapes in one store would
+ * corrupt both counters.
+ */
+const ACTION_SCOPE = 'action';
+
+export interface RateLimitSpendOptions {
+  readonly surface: Surface;
+  /** The connection address — the only subject an anonymous caller has. */
+  readonly clientAddress?: string | null | undefined;
+  /** The decision, before a refusal is thrown: how HTTP puts `RateLimit-*` on the answer. */
+  readonly onRateLimit?: ((decision: RateLimitDecision) => void) | undefined;
+}
+
+/**
+ * Spend one token of `limit` for this caller, or throw `X_RATE_LIMITED` — the code, the cause and
+ * the `Retry-After` seconds every limit in the framework answers with.
+ *
+ * `surface: 'server'` spends nothing: that is app code calling its own action in-process (a
+ * service composing two, a seed, a test), not a caller arriving from outside. A refused attempt
+ * spends nothing either — the token bucket only decrements on an admission — so a job retried
+ * into a refusal is not charged for it.
+ */
+export async function spendActionLimit(
+  name: string,
+  limit: ActionRateLimit | undefined,
+  ctx: Ctx,
+  options: RateLimitSpendOptions,
+): Promise<void> {
+  if (limit === undefined || options.surface === 'server') return;
+  const frame = callerFrame.get();
+  // A job run, or any call nested inside one (an `agent()` run as a job calling its tools as
+  // `'mcp'`): never a visitor's address, and the unattributed bucket rather than `ip:unknown`.
+  const inJob = options.surface === 'job' || frame?.job === true;
+  const spends = rateLimitSpends(
+    {
+      actorId: isAnonymous(ctx.actor) ? null : ctx.actor.id,
+      // Read off an anonymous actor too: a job run IS the worker's anonymous identity carrying the
+      // job's org (`jobRunActor`), and that org is who the run is — charging every tenant's runs
+      // to one `ip:unknown` key let one tenant's backlog refuse everyone's.
+      orgId: ctx.actor.orgId ?? null,
+      ip: options.clientAddress ?? (inJob ? null : (frame?.address ?? null)),
+      routeName: `${ACTION_SCOPE}:${name}`,
+      ...(inJob ? { unattributed: UNATTRIBUTED_JOB } : {}),
+    },
+    // The tenant allowance is the HTTP pipeline's (it spends it for every route, a handler-limited
+    // one included); counting it here too would charge an HTTP call against the tenant twice.
+    { route: name, tenant: null },
+  );
+  for (const spend of spends) {
+    const decision = await installedRateLimitStore().take(
+      spend.key,
+      toBucket(name, limit),
+      1,
+      ctx.now().getTime(),
+    );
+    options.onRateLimit?.(decision);
+    if (!decision.allowed) throw rateLimited(spend.key, decision.retryAfterSeconds);
+  }
+}

package/src/record-wire.ts

@@ -6,7 +6,7 @@
 
 import { encodeRecordEnvelope, RECORDS_HEADER } from '@ultimat3/core';
 import { hasEntityRows, rowsOf } from '@ultimat3/entity';
-import { json } from '@ultimat3/http';
+import { jsonResponse } from '@ultimat3/http';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 
 /** The header value that says "this body is an envelope". Presence alone is not enough. */
@@ -26,7 +26,7 @@ export function carriesRecords(output: StandardSchemaV1): boolean {
 
 /** The 200 for an action that carries records: the envelope, and the header that names it. */
 export function recordResponse(output: StandardSchemaV1, result: unknown): Response {
-  const response = json(encodeRecordEnvelope(result, rowsOf(output, result)));
+  const response = jsonResponse(encodeRecordEnvelope(result, rowsOf(output, result)));
   response.headers.set(RECORDS_HEADER, ENVELOPED);
   return response;
 }

package/src/registry.ts

@@ -111,7 +111,7 @@ function assertProjectable(name: string, target: AnyAction): void {
   for (const field of ['input', 'output'] as const) {
     try {
       jsonSchemaOf(target[field]);
-      // The schema `.tool()` and `tools/list` publish — the one an MCP client reads.
+      // The schema `tools/list` publishes — the one an MCP client reads.
       toWireSchema(target[field]);
     } catch {
       // The thrown value is deliberately not rendered into the cause: it is the provider's, of
@@ -154,7 +154,7 @@ export function describeActions(): readonly ActionDescriptor[] {
 }
 
 /** Test-only. Production registers once at boot and never unregisters. */
-export function resetRegistry(): void {
+export function resetActions(): void {
   registry.clear();
   paths.clear();
   resetActionPathStyle();

package/src/sample-input.ts

@@ -99,6 +99,25 @@ function sampleObject(node: SchemaNode): Record<string, unknown> {
   return sample;
 }
 
+/**
+ * The most items a sample will hold. A contract sample is a handful of values; `minItems` past
+ * this is an input the framework does not invent — `2 ** 32` made `Array.from` throw, and anything
+ * below it allocated that many samples first. Such an array is a GAP (`sampleGaps`), reported as
+ * `X_CONTRACT_DRIFT` with the instruction to pass the input, never silently under-sampled.
+ */
+export const SAMPLE_ITEMS_MAX = 1000;
+
+/**
+ * The `minItems` an array sample owes, or `undefined` when none can be built: past the ceiling,
+ * or not a count at all. The builtin `t.array` refuses a bad bound at declaration
+ * (`X_SCHEMA_BOUNDS_INVALID`), but this IR may come from a swapped provider.
+ */
+function owedItems(node: SchemaNode): number | undefined {
+  const min = node.minItems;
+  if (min === undefined) return 0;
+  return Number.isSafeInteger(min) && min >= 0 && min <= SAMPLE_ITEMS_MAX ? min : undefined;
+}
+
 function sampleFor(node: SchemaNode): unknown {
   // A nullable field accepts `null`, and `null` is the smallest thing it accepts.
   if (node.nullable === true) return null;
@@ -115,8 +134,13 @@ function sampleFor(node: SchemaNode): unknown {
       return node.values?.[0] ?? SAMPLE_STRING;
     case 'literal':
       return node.literal ?? null;
+    // The fewest items the array accepts: `[]` under a `minItems` is a sample its own schema
+    // refuses. Items repeat the one item sample; a uniqueness rule would be a refinement.
     case 'array':
-      return [];
+      // An unbuildable count samples `[]`, which the schema refuses — `sampleGaps` names why.
+      return Array.from({ length: owedItems(node) ?? 0 }, () =>
+        node.items === undefined ? null : sampleFor(node.items),
+      );
     case 'union': {
       const first = node.anyOf?.[0];
       return first === undefined ? null : sampleFor(first);
@@ -174,24 +198,29 @@ function gapsIn(node: SchemaNode, path: string): string[] {
     }
     return out;
   }
-  if (satisfiesPattern(node, sampleFor(node))) return [];
+  const unbuildable = node.kind === 'array' && owedItems(node) === undefined;
+  if (!unbuildable && satisfiesPattern(node, sampleFor(node))) return [];
   return [path === '' ? ROOT_PATH : path];
 }
 
 /** `orderRef` -> `orderRef (must match ^ORD-\d{4}$)`, for a cause a reader can act on. */
 export function describeSampleGap(schema: StandardSchemaV1, path: string): string {
-  const pattern = patternAt(tryIntrospect(schema), path);
+  const node = nodeAt(tryIntrospect(schema), path);
+  if (node?.kind === 'array' && node.minItems !== undefined && owedItems(node) === undefined) {
+    return `${path} (needs at least ${node.minItems} items)`;
+  }
+  const pattern = node?.pattern;
   return pattern === undefined ? path : `${path} (must match ${pattern})`;
 }
 
-function patternAt(node: SchemaNode | undefined, path: string): string | undefined {
+function nodeAt(node: SchemaNode | undefined, path: string): SchemaNode | undefined {
   if (node === undefined) return undefined;
-  if (path === '' || path === ROOT_PATH) return node.pattern;
+  if (path === '' || path === ROOT_PATH) return node;
   const [head, ...rest] = path.split('.');
   // `path` is the caller's — `describeSampleGap` is exported — so the same own-property read the
   // format table takes: `properties['constructor']` is otherwise the `Object` function.
   const properties = node.properties ?? {};
   const child =
     head === undefined || !Object.hasOwn(properties, head) ? undefined : properties[head];
-  return child === undefined ? undefined : patternAt(child, rest.join('.'));
+  return child === undefined ? undefined : nodeAt(child, rest.join('.'));
 }

package/src/stable.ts

@@ -9,13 +9,6 @@
  * published. Ordinary payloads are byte-identical between the two; `stable.test.ts` pins that.
  */
 
-/**
- * `@ultimat3/core`'s, re-exported so `./stable` stays this package's one import path for the JSON
- * helpers. It was declared here AND identically in `@ultimat3/query`'s own `stable.ts`, which is
- * the duplication `client-wire.ts` moving to tier 0 made unnecessary.
- */
-export { isJsonObject } from '@ultimat3/core';
-
 export type JsonObject = Record<string, unknown>;
 
 /** JSON with object keys sorted at every depth. No timestamps, no insertion-order leaks. */

package/src/transition.ts

@@ -18,6 +18,7 @@ import type {
   StringSchema,
 } from '@ultimat3/schema';
 import { nodeOf, t } from '@ultimat3/schema';
+import type { ActionRowArgs } from './action';
 import { type Mutator, mutator } from './mutator';
 import type { ActionPolicy } from './policy-gate';
 
@@ -57,6 +58,7 @@ export interface TransitionDef<
   Row extends InferOutput<TOutput> & object,
   K extends keyof Row & string,
   S extends Row[K] & string,
+  TRow = unknown,
 > {
   /** The request's table — `(ctx) => posts(ctx)`, so the move is tenant-scoped like every write. */
   readonly table: (ctx: Ctx) => TransitionTarget<Row, S>;
@@ -84,7 +86,21 @@ export interface TransitionDef<
    * column's own shape.
    */
   readonly id?: StringSchema;
-  readonly policy: ActionPolicy;
+  readonly policy: ActionPolicy<TRow>;
+  /**
+   * The row a row-level `policy` decides about — an action's own `row` loader, handed through
+   * unchanged: loaded once, after the input parse, before the guard and before the statement. The
+   * factory reads no row itself; which columns a rule needs (an `authorId` the `output` view may not
+   * carry) is the app's. Omitted, the rule sees `row: null` — and must fail closed on it.
+   *
+   * CHECK-THEN-ACT, as every row-policy action's: the read is unlocked and outside any transaction,
+   * and the compare-and-set predicate is `id` + `from` only. A concurrent write to a column the
+   * rule read (an `authorId` reassigned between the read and the move) is not seen, so the move
+   * lands on the decision about the older row. Where that matters, do not use `transition()`: an
+   * `action` whose handler runs `withTransaction`, reads the row `for update`, decides, and calls
+   * `Table.transition` in that transaction closes the window.
+   */
+  row?(args: ActionRowArgs<TransitionInput<S>>): TRow | null | Promise<TRow | null>;
   /**
    * OFF unless the app says otherwise, and deliberately not `?? true`.
    *
@@ -110,7 +126,8 @@ export function transition<
   Row extends InferOutput<TOutput> & object,
   K extends keyof Row & string,
   const S extends Row[K] & string,
->(def: TransitionDef<TOutput, Row, K, S>): Mutator<TransitionInput<S>, TOutput> {
+  TRow = unknown,
+>(def: TransitionDef<TOutput, Row, K, S, TRow>): Mutator<TransitionInput<S>, TOutput> {
   const state = t.enum(def.states);
   // ONE cast, and it is a compiler limitation rather than an unknown value: `t.object`'s output is
   // a mapped type over its shape, and a mapped type does not reduce while a type parameter is still
@@ -119,13 +136,16 @@ export function transition<
   // reason. What arrives here has already been parsed by the schema two lines up, and nothing else
   // can reach these two callbacks.
   const valuesOf = (raw: unknown): TransitionValues<S> => raw as TransitionValues<S>;
-  return mutator({
+  const row = def.row;
+  return mutator<TransitionInput<S>, TOutput, TRow>({
     input: t.object({ id: def.id ?? keySchemaOf(def.output), from: state, to: state }),
     output: def.output,
     policy: def.policy,
     // A compare-and-set move replayed under its key answers the first outcome, never a second
     // `X_STATE_CONFLICT` for a move that already happened.
     idempotent: true,
+    // `.call(def, …)`, as `mutator()` hands its own on: a loader written as a method keeps `this`.
+    ...(row === undefined ? {} : { row: (args) => row.call(def, args) }),
     ...(def.audit === undefined ? {} : { audit: def.audit }),
     // Never overridable: the server is the half that REFUSED the move, and a local twin that won
     // the rebase would leave the client showing a state the database rejected.

package/src/tx-scope.ts

@@ -40,7 +40,7 @@ export interface LiveTransaction extends CommitScope {
  * settlement bound to a transaction that already ended is bound to nothing: it would run as its
  * own commit while the record claimed otherwise, and that record is the one a retry may reclaim.
  *
- * The fragment is assembled by hand, exactly as `@ultimat3/cli`'s `pgExecutorFor` does: the caller
+ * The fragment is assembled by hand, exactly as `@ultimat3/db`'s `dbExecutor` does: the caller
  * wrote the `$1..$n` text itself and hands over already-bound values.
  */
 export function liveTransaction(): LiveTransaction | undefined {

package/src/type-pins.ts

@@ -3,18 +3,32 @@
 // type-level claim written in one can never fail. This module emits nothing and exports nothing
 // anybody imports — a regression here is a build error, the only enforcement that counts.
 
-import type { Row } from '@ultimat3/core';
+import type { AuditRecord, McpExposureDeclaration, Row } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
-import type { Action, AnyAction } from './action';
+import type { Action, ActionDef, AnyAction, AnyActionDef } from './action';
 import type { ClientMethod } from './client';
+import type {
+  IdempotencyRecord,
+  IdempotencyReservation,
+  IdempotencyScope,
+  IdempotencyStore,
+} from './idempotency';
 import type { ActionJobHandle } from './job-handle';
-import type { LocalTable } from './mutator';
+import type { LocalTable, MutatorDef } from './mutator';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
 type Assert<T extends true> = T;
 
 type Equals<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
 
+/**
+ * IDENTICAL, not merely mutually assignable: an object type without an optional key is assignable
+ * to one with it and back, so `Equals` cannot see an optional field added on one side only — and
+ * every field of the `mcp` block is optional but `expose`.
+ */
+type Identical<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
 type PublishInput = StandardSchemaV1<{ readonly postId: string }>;
 type PublishOutput = StandardSchemaV1<{ readonly published: boolean }>;
 type PublishPost = Action<PublishInput, PublishOutput>;
@@ -59,3 +73,89 @@ export type _LocalTableIsTheStoreTxShape = Assert<
 export type _LocalInsertTakesTheKey = Assert<
   Equals<Parameters<LocalTable['insert']>, [key: string, row: Row]>
 >;
+
+/**
+ * #591: a store written before answers were redacted at rest drops `settle`'s `redacted` flag and
+ * would replay `[redacted]` as the answer. A required 4th PARAMETER cannot refuse it — TypeScript
+ * accepts an implementation with fewer parameters — so the store DECLARES it keeps the flag
+ * (`keepsRedaction: true`), and a pre-25 store without the declaration is a build error here.
+ */
+interface PreRedactionStore {
+  readonly scope?: IdempotencyScope | undefined;
+  reserve(key: string, requestHash: string): Promise<IdempotencyReservation>;
+  settle(key: string, value: unknown, reservationId: string): Promise<void>;
+  release(key: string): Promise<void>;
+  get(key: string): Promise<IdempotencyRecord | undefined>;
+}
+
+export type _APreRedactionStoreIsNotAStore = Assert<
+  Equals<PreRedactionStore extends IdempotencyStore ? true : false, false>
+>;
+
+/** A release names the reservation it drops — the fence `settle` and `fail` already carry. */
+export type _ReleaseNamesTheReservation = Assert<
+  Equals<Parameters<IdempotencyStore['release']>['length'], 2>
+>;
+
+/** …and `settle`'s flag is required of every CALLER, so a wrapping store cannot drop it either. */
+export type _SettleRequiresTheRedactedFlag = Assert<
+  Equals<Parameters<IdempotencyStore['settle']>['length'], 4>
+>;
+
+/**
+ * 25.0.0 (plan 101, M9): `name` and `primitive` are REQUIRED on an audit record and the `action`
+ * alias is gone. Pinned as keys rather than with a literal record, because a literal would need a
+ * `Ctx` this module has no business building: a field that turned optional again, or an alias
+ * that came back, flips one of these to `false`.
+ */
+type RequiredKeys<T> = { [K in keyof T]-?: object extends Pick<T, K> ? never : K }[keyof T];
+
+export type _AuditRecordRequiresNameAndPrimitive = Assert<
+  Equals<Extract<RequiredKeys<AuditRecord>, 'name' | 'primitive'>, 'name' | 'primitive'>
+>;
+
+export type _AuditRecordHasNoActionAlias = Assert<
+  Equals<Extract<keyof AuditRecord, 'action'>, never>
+>;
+
+/**
+ * 25.0.0 (plan 101, M5): the deprecation TYPES are `@ultimat3/core`'s alone, as the helpers are.
+ * A runtime test cannot see a type re-export, so each is an expected error: a re-export coming
+ * back makes the directive unused, which `tsc` refuses.
+ */
+// @ts-expect-error — `Deprecation` is imported from `@ultimat3/core`, never from this barrel.
+export type _NoDeprecationReexport = import('./index').Deprecation;
+// @ts-expect-error — `DeprecationField` is imported from `@ultimat3/core`.
+export type _NoDeprecationFieldReexport = import('./index').DeprecationField;
+// @ts-expect-error — `DeprecationRender` is imported from `@ultimat3/core`.
+export type _NoDeprecationRenderReexport = import('./index').DeprecationRender;
+
+/**
+ * O-tool, 25.0.0: an action projects no MCP tool of its own — `@ultimat3/mcp`'s `toolFrom`
+ * is the one projection, and a tier-3 `.tool()` could only ever be a second one. A `tool` member
+ * coming back on either view flips these to `false`.
+ */
+export type _AnActionHasNoToolTwin = Assert<Equals<Extract<keyof AnyAction, 'tool'>, never>>;
+export type _ATypedActionHasNoToolTwin = Assert<Equals<Extract<keyof PublishPost, 'tool'>, never>>;
+
+/**
+ * 25.0.0: an action's `mcp` block is core's ONE `McpExposureDeclaration`, minus the list
+ * whitelist an action has nothing to compose over — on the declaration, the erased declaration,
+ * the erased action and a mutator alike. `ActionMcp` restated the block field by field (and
+ * `McpAnnotationHints` its hints); a field drifting on either side flips these to `false`.
+ */
+type ActionBlock = Omit<McpExposureDeclaration, 'listParams'>;
+export type _ActionDeclaresCoresBlock = Assert<
+  Identical<NonNullable<ActionDef<PublishInput, PublishOutput>['mcp']>, ActionBlock>
+>;
+export type _ErasedActionDefDeclaresCoresBlock = Assert<
+  Identical<NonNullable<AnyActionDef['mcp']>, ActionBlock>
+>;
+export type _AnyActionCarriesCoresBlock = Assert<
+  Identical<NonNullable<AnyAction['mcp']>, ActionBlock>
+>;
+export type _MutatorDeclaresCoresBlock = Assert<
+  Identical<NonNullable<MutatorDef<PublishInput, PublishOutput>['mcp']>, ActionBlock>
+>;
+// @ts-expect-error — `McpAnnotationHints` is `@ultimat3/core`'s, never this barrel's.
+export type _NoAnnotationHintsTwin = import('./index').McpAnnotationHints;