@ultimat3/action 23.0.0 → 25.0.0

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/openapi.ts

@@ -76,7 +76,12 @@ function compareByName(a: AnyAction, b: AnyAction): number {
   return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
 }
 
-/** RFC 9457 + the Ultimate error contract (code / cause / fix / docs). */
+/**
+ * RFC 9457 + the Ultimate error contract, member for member what `@ultimat3/http`'s `toProblem`
+ * serves (`openapi-problem.test.ts` compares the two). `code` carries no `pattern`: `factsOf`
+ * serves whatever string an app's own throwable holds, and a published pattern the server breaks
+ * makes a generated client reject the very document it was written to read.
+ */
 const PROBLEM_SCHEMA: JsonSchemaObject = {
   type: 'object',
   required: ['type', 'title', 'status', 'code'],
@@ -85,9 +90,27 @@ const PROBLEM_SCHEMA: JsonSchemaObject = {
     title: { type: 'string' },
     status: { type: 'integer' },
     detail: { type: 'string' },
-    code: { type: 'string', pattern: '^X_[A-Z0-9_]+$' },
+    instance: { type: 'string' },
+    code: { type: 'string' },
     cause: { type: 'string' },
     fix: { type: 'string' },
     docs: { type: 'string', format: 'uri' },
+    requestId: { type: 'string' },
+    // Absent when the failure produced none — never `[]`, which would claim "validated clean".
+    issues: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['path', 'expected', 'received', 'message'],
+        properties: {
+          path: { type: 'string' },
+          expected: { type: 'string' },
+          received: { type: 'string' },
+          message: { type: 'string' },
+        },
+      },
+    },
+    // Only the keys the code declared through `registerProblemMeta`; its shape is per code.
+    meta: { type: 'object' },
   },
 };

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

@@ -5,7 +5,7 @@
  */
 
 import type { ActionPathStyle } from '@ultimat3/core';
-import { SchemaUnsupportedError } from '@ultimat3/schema';
+import { SchemaUnsupportedError, toWireSchema } from '@ultimat3/schema';
 import type { ActionDescriptor, AnyAction } from './action';
 import { isAction, nameAction } from './action';
 import { resetApiDeclaration } from './api-declaration';
@@ -19,7 +19,7 @@ import {
 } from './http-path';
 import { assertIdempotencyScope } from './idempotency';
 import { defOf } from './invoke';
-import { jsonSchemaOf, mcpSchemaOf } from './json-schema';
+import { jsonSchemaOf } from './json-schema';
 import type { ActionPath } from './naming';
 import { seatedActions } from './registry-store';
 
@@ -111,7 +111,8 @@ function assertProjectable(name: string, target: AnyAction): void {
   for (const field of ['input', 'output'] as const) {
     try {
       jsonSchemaOf(target[field]);
-      mcpSchemaOf(target[field]);
+      // 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
       // unknown shape, and this package's own two facts — which action, which field — are the
@@ -153,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/request-deadline.ts

@@ -0,0 +1,25 @@
+/**
+ * The app's request deadline — how long an idempotency record bound to a transaction may stay in
+ * flight before a retry takes the key. Read from `@ultimat3/http`'s own declaration and resolved
+ * by its own `defineHttpConfig`, so the default and its screen are never restated here.
+ */
+import { configuredHttp, defineHttpConfig } from '@ultimat3/http';
+
+let resolved: { readonly declared: number | undefined; readonly ms: number } | undefined;
+
+/**
+ * `configureHttp({ requestTimeoutMs })`, else http's default; `0` is "no deadline". Read on every
+ * call because the app declares it at module scope AFTER the boot has built its stores — resolved
+ * once per declared value, since `defineHttpConfig` screens a whole config to answer one field.
+ */
+export function requestDeadlineMs(): number {
+  const declared = configuredHttp()?.requestTimeoutMs;
+  if (resolved === undefined || resolved.declared !== declared) {
+    const config = defineHttpConfig({
+      ...(declared === undefined ? {} : { requestTimeoutMs: declared }),
+      rateLimit: { enabled: false, scope: 'process' },
+    });
+    resolved = { declared, ms: config.requestTimeoutMs };
+  }
+  return resolved.ms;
+}

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

@@ -17,15 +17,14 @@ import type {
   StandardSchemaV1,
   StringSchema,
 } from '@ultimat3/schema';
-import { t } from '@ultimat3/schema';
+import { nodeOf, t } from '@ultimat3/schema';
 import { type Mutator, mutator } from './mutator';
 import type { ActionPolicy } from './policy-gate';
 
 /**
  * The one method this factory calls, declared structurally: `@ultimat3/entity`'s `Table.transition`
- * satisfies it as written. Structural and not an import because `@ultimat3/action` holds no
- * dependency edge on `@ultimat3/entity` — the tier table permits one (2 is below 3), the manifest
- * and the lockfile do not — the same trade `@ultimat3/db`'s `entity-shape.ts` makes one tier down.
+ * satisfies it as written. Structural because it is all this file needs of a table — one method —
+ * and a fake that implements it is the whole test seam; the package does import entity elsewhere.
  *
  * `id` is a plain `string` rather than entity's `IdOf<Row>`: that alias "collapses to `string` for
  * every unbranded entity" by its own account, and a branded one still satisfies this because a
@@ -69,16 +68,22 @@ export interface TransitionDef<
    * tool's `inputSchema` carries it, the typed client refuses a typo at COMPILE time, and a
    * misspelled state is `X_INPUT_INVALID` before the request reaches a database.
    *
-   * It is the one thing restated from the column's own declaration, and the reason is a boundary:
-   * reading the machine off the entity needs `@ultimat3/entity` as a real dependency of this
-   * package. Listing a SUBSET refuses a legal move at the input schema — loud, and the fix is the
-   * enum in the refusal.
+   * It is the one thing restated from the column's own declaration: `table` is resolved per request
+   * (`(ctx) => …`), and the input schema is needed at declaration, before any table exists to read
+   * a machine off. Listing a SUBSET refuses a legal move at the input schema — loud, and the fix is
+   * the enum in the refusal.
    */
   readonly states: readonly [S, ...S[]];
   /** The local store's name for this entity — what the optimistic twin patches. */
   readonly localTable: string;
   /** The projection the caller gets back. Unknown keys are dropped by the parse, so a `$view` works. */
   readonly output: TOutput;
+  /**
+   * The key's schema, for an `output` that does not carry the key as `id`. Omitted — the usual
+   * case — it is read off `output.id` (`keySchemaOf`), which for an entity `$view` IS the key
+   * column's own shape.
+   */
+  readonly id?: StringSchema;
   readonly policy: ActionPolicy;
   /**
    * OFF unless the app says otherwise, and deliberately not `?? true`.
@@ -115,9 +120,12 @@ export function transition<
   // can reach these two callbacks.
   const valuesOf = (raw: unknown): TransitionValues<S> => raw as TransitionValues<S>;
   return mutator({
-    input: t.object({ id: t.uuid, from: state, to: state }),
+    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,
     ...(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.
@@ -142,3 +150,21 @@ export function transition<
     },
   });
 }
+
+/**
+ * The `id` a move takes, from the key the OUTPUT declares — never a fixed `t.uuid`, which made
+ * every call on an entity keyed by `text()` or `bigint()` `X_INPUT_INVALID` while the mechanism
+ * underneath addresses any single-column key. An entity `$view` builds its `id` node from the key
+ * column, so the bounds copied here are that column's: a uuid stays a uuid (and a malformed one is
+ * still refused before a database reads it), a `bigint()` keeps its digits pattern, a `text()` its
+ * length. Never empty: an empty string names no row. An output with no string `id` keeps the
+ * framework's default key type, `uuid().primaryKey()`.
+ */
+function keySchemaOf(output: StandardSchemaV1): StringSchema {
+  const key = nodeOf(output)?.properties?.['id'];
+  if (key === undefined || key.kind !== 'string' || key.format === 'uuid') return t.uuid;
+  let schema = t.string.min(Math.max(1, key.minLength ?? 1));
+  if (key.maxLength !== undefined) schema = schema.max(key.maxLength);
+  if (key.pattern !== undefined) schema = schema.pattern(new RegExp(key.pattern, key.patternFlags));
+  return schema;
+}

package/src/tx-scope.ts

@@ -0,0 +1,57 @@
+/**
+ * The open database transaction, as this package needs it — **the only** file here that imports
+ * `@ultimat3/db` (`tx-scope.test.ts` holds that). When is a write durable (`openCommitScope`, the
+ * cache bust), and is a transaction really OPEN, on which client (`liveTransaction`, idempotency).
+ */
+
+// Type-only: `idempotency-postgres.ts` imports this module, and a runtime edge would be a cycle.
+import type { PgExecutor } from '@ultimat3/core';
+import { currentTx, liveTxConnection } from '@ultimat3/db';
+
+/** The half of a transaction a deferred effect needs. `@ultimat3/db`'s `DbTx` satisfies it. */
+export interface CommitScope {
+  /** Fired once the ROOT transaction has committed; dropped on rollback or a lost COMMIT. */
+  onCommit(effect: () => void): void;
+}
+
+/**
+ * The transaction this call runs inside, or `undefined`. `currentTx()` on purpose, FINISHED scopes
+ * included: a promise chain the body forgot to await still finds the handle after the scope
+ * closed, and `onCommit` on it runs the effect at once after a COMMIT and drops it after a
+ * ROLLBACK — the answer `@ultimat3/entity`'s row observer gets from the same call, so a late bust
+ * and a late change report never disagree about one write.
+ */
+export function openCommitScope(): CommitScope | undefined {
+  return currentTx();
+}
+
+/** A transaction that is still OPEN: statements sent now are inside it. */
+export interface LiveTransaction extends CommitScope {
+  /** The client it was opened on — which DATABASE this is, compared by identity. */
+  readonly origin: object;
+  /** Fired when the scope rolls back; never after a commit. */
+  onRollback(undo: () => void): void;
+  /** `(text, values)` on the transaction's OWN connection. */
+  readonly executor: PgExecutor;
+}
+
+/**
+ * The open transaction, or `undefined` — outside one, and ALSO for a finished scope's handle. A
+ * 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
+ * wrote the `$1..$n` text itself and hands over already-bound values.
+ */
+export function liveTransaction(): LiveTransaction | undefined {
+  const tx = currentTx();
+  if (tx === undefined || liveTxConnection() === undefined) return undefined;
+  return {
+    origin: tx.origin,
+    onCommit: (effect) => tx.onCommit(effect),
+    onRollback: (undo) => tx.onRollback(undo),
+    executor: {
+      query: <R>(text: string, values: readonly unknown[]) => tx.query<R>({ text, values }),
+    },
+  };
+}

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,84 @@ 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>
+>;
+
+/** …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;