@ultimat3/action 1.2.0 → 3.0.0

package/src/index.ts

@@ -7,6 +7,12 @@
  * framework died; there is exactly one here, structurally.
  */
 
+/**
+ * `toBucket` is `@ultimat3/http`'s — http owns `Bucket` and the limiter maths, and `action` and
+ * `query` are the same tier, so a copy in either is a second answer for the other. Re-exported
+ * here, not re-implemented, so an action file still reaches it through one import.
+ */
+export { toBucket } from '@ultimat3/http';
 /** Re-exported so an `action` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
@@ -25,6 +31,19 @@ export type {
   McpDescriptorMeta,
 } from './action';
 export { action, describeAction, isAction } from './action';
+/**
+ * The audit seam. `AuditSink` is the whole extension point: the framework supplies the record
+ * and never the row. `audit-gate.ts` stays unexported — the sink has one caller, and that
+ * absence is what keeps it one.
+ */
+export type {
+  AuditFailure,
+  AuditOutcome,
+  AuditRecord,
+  AuditSink,
+  MemoryAuditSink,
+} from './audit';
+export { getAuditSink, memoryAuditSink, resetAuditSink, setAuditSink } from './audit';
 export type {
   ActionLike,
   ActionMap,
@@ -39,17 +58,33 @@ export type { ContractTest, ContractTestOptions } from './contract-test';
 export { anonymousCtx, contractTestsFor, policyTestStubFor } from './contract-test';
 export type { Api, ApiDef, ApiModule, ApiModules } from './define-api';
 export { defineApi } from './define-api';
-export type { IdempotencyConflictReason } from './errors';
+/**
+ * The compat window a retirement gets. Versioning itself is NOT here and never will be: two
+ * versions of one action side by side is two deployments behind one ingress (axiom 7), not a
+ * router feature. `renderDeprecation` is exported so a plain `route` can announce the same pair
+ * of headers the action projection does.
+ */
+export type { Deprecation, DeprecationField, DeprecationRender } from './deprecation';
+export { recordDeprecatedCall, renderDeprecation } from './deprecation';
+export type { IdempotencyConflictReason, IdempotencyKeyProblem, RemoteFailure } from './errors';
 export {
   ActionDeniedError,
+  ActionDeprecationInvalidError,
   ActionDuplicateError,
   ActionForeignError,
+  ActionPathDuplicateError,
   ActionPolicyMissingError,
   ActionUnregisteredError,
+  AuditSinkFailedError,
+  AuditSinkMissingError,
   ContractDriftError,
   IdempotencyConflictError,
+  IdempotencyKeyInvalidError,
+  IdempotencyNotSharedError,
+  IdempotencyReplayedFailureError,
   InputInvalidError,
   OutputInvalidError,
+  RemoteActionError,
   RpcFailedError,
 } from './errors';
 export type { OpenApiOperation } from './http';
@@ -60,19 +95,59 @@ export {
   toOpenApiOperation,
   toRoute,
 } from './http';
+/**
+ * The idempotency seam. `withIdempotency` and `IDEMPOTENCY_HEADER` are both public, so a plain
+ * mutating `route` can reserve-and-replay exactly as an action does — `idempotencyKeyFor` is the
+ * namespacing it must apply, or two routes sharing a caller's key would share one record, and so
+ * would two callers sending one key value.
+ */
 export type {
+  IdempotencyConfig,
+  IdempotencyFailure,
   IdempotencyRecord,
   IdempotencyReservation,
+  IdempotencyScope,
+  IdempotencyStatus,
   IdempotencyStore,
   IdempotentOutcome,
 } from './idempotency';
 export {
+  assertIdempotencyScope,
+  configureIdempotency,
+  DEFAULT_IDEMPOTENCY_CONFIG,
   getIdempotencyStore,
-  idempotencyKeyFor,
-  MemoryIdempotencyStore,
+  idempotencyConfig,
+  resetIdempotency,
   setIdempotencyStore,
   withIdempotency,
 } from './idempotency';
+export { idempotencyKeyFor, MAX_IDEMPOTENCY_KEY_LENGTH } from './idempotency-key';
+export type { MemoryIdempotencyStoreOptions } from './idempotency-memory';
+export {
+  DEFAULT_IDEMPOTENCY_WINDOW_MS,
+  DEFAULT_MAX_IDEMPOTENCY_KEYS,
+  MemoryIdempotencyStore,
+} from './idempotency-memory';
+/**
+ * The SHARED store, and the only one an app running more than one replica may install. The
+ * statements are exported beside it because the table is applied the way `SQL_JOBS_TABLE` is —
+ * by `x db up` in development and by the release-phase `ROLE=migrate` in production.
+ */
+export type {
+  PgExecutor,
+  PostgresIdempotencyStore,
+  PostgresIdempotencyStoreOptions,
+} from './idempotency-postgres';
+export {
+  postgresIdempotencyStore,
+  SQL_IDEMPOTENCY_FAIL,
+  SQL_IDEMPOTENCY_GET,
+  SQL_IDEMPOTENCY_PURGE,
+  SQL_IDEMPOTENCY_RELEASE,
+  SQL_IDEMPOTENCY_RESERVE,
+  SQL_IDEMPOTENCY_SETTLE,
+  SQL_IDEMPOTENCY_TABLE,
+} from './idempotency-postgres';
 /** The one execution path. `defOf` stays unexported — that is the enforcement. */
 export { actionName, invoke } from './invoke';
 export type { ActionJobHandle } from './job-handle';
@@ -95,11 +170,12 @@ export type {
 } from './mutator';
 export { custom, isMutator, mutator, resolveConflict, strategyOf } from './mutator';
 export type { ActionPath } from './naming';
-export { derivePath, inputSchemaName, outputSchemaName, pluralize, toToolName } from './naming';
+export { derivePath, inputSchemaName, outputSchemaName, pluralize } from './naming';
 export type { BuildOpenApiOptions, OpenApiDocument, OpenApiInfo } from './openapi';
 export { buildOpenApi, serializeOpenApi } from './openapi';
 export type { ActionPolicy, PolicySubject, Surface } from './policy-gate';
-export { actorOf, guard, policyCapability } from './policy-gate';
+/** `policyCapability` is the display label; `policyPermissions` is what a report MATCHES on. */
+export { actorOf, guard, policyCapability, policyPermissions } from './policy-gate';
 export {
   describeActions,
   getAction,

package/src/invoke.ts

@@ -3,13 +3,18 @@
  * output. The declaration lives in this module's private store, so `handle` is
  * unreachable from anywhere else — HTTP, MCP, jobs and `.as()` hand `invoke` a
  * payload, and none of them can become a second execution path.
+ *
+ * `audit: true` wraps that path, it never forks it: `execute` is the same body either way, and
+ * the audited branch only observes it. Wrapping rather than hooking is what lets a DENIED attempt
+ * be recorded at all — `guard` throws before `handle`, so nothing an app writes around its own
+ * handler could ever see one.
  */
 
-import { invalidateTags } from '@ultimat3/cache';
 import type { Ctx } from '@ultimat3/core';
 import {
   anonymousActor,
   createContext,
+  isUltimateError,
   runWithContext,
   tryUseContext,
   useContext,
@@ -17,8 +22,18 @@ import {
   withSpan,
 } from '@ultimat3/core';
 import type { AnyAction, AnyActionDef, InvokeOptions } from './action';
+import type { AuditRecord } from './audit';
+import {
+  auditFailureFor,
+  auditOutcomeFor,
+  auditSettled,
+  auditSinkFor,
+  auditThrew,
+} from './audit-gate';
+import { bustAfterCommit } from './cache-gate';
 import { ActionForeignError, ActionUnregisteredError } from './errors';
-import { getIdempotencyStore, idempotencyKeyFor, withIdempotency } from './idempotency';
+import { getIdempotencyStore, withIdempotency } from './idempotency';
+import { idempotencyKeyFor } from './idempotency-key';
 import { actorOf, guard } from './policy-gate';
 import { validateInput, validateOutput } from './validate';
 
@@ -62,7 +77,17 @@ export function invoke(
   raw: unknown,
   options: InvokeOptions = {},
 ): Promise<unknown> {
-  if (options.actor === undefined) return core(target, raw, options.ctx ?? useContext(), options);
+  if (options.actor === undefined) {
+    // INSTALLED, never only handed over. An explicit `ctx` used to be passed to `core` and to
+    // nothing else, so everything downstream that reads the ambient context — most importantly
+    // `@ultimat3/entity`'s tenant guard, which derives from `tryUseContext()` and not from the ctx
+    // it is given — saw either a different identity or none at all: policy decided about this
+    // actor while a row's tenancy was decided about nobody. When `ctx` is absent this is
+    // `runWithContext(useContext(), …)`, which is the context already installed — a no-op on every
+    // path that worked before.
+    const ctx = options.ctx ?? useContext();
+    return runWithContext(ctx, () => core(target, raw, ctx, options));
+  }
 
   // Impersonation keeps the surrounding context whole — services, clock, locale,
   // trace — and swaps only the actor. Policy models "nobody" as null; core models
@@ -75,6 +100,17 @@ export function invoke(
     : runWithContext(base, () => withChildContext(patch, run));
 }
 
+/**
+ * What `execute` learns on the way through, for the audit record. Mutable and module-private:
+ * the three facts a record needs that only exist partway down the one path, and reading them back
+ * out is what keeps the audit branch from becoming a second one.
+ */
+interface InvokeTrace {
+  input: unknown;
+  idempotencyKey: string | null;
+  replayed: boolean;
+}
+
 async function core(
   target: AnyAction,
   raw: unknown,
@@ -83,7 +119,105 @@ async function core(
 ): Promise<unknown> {
   const def = defOf(target);
   const name = actionName(target);
+  const trace: InvokeTrace = { input: undefined, idempotencyKey: null, replayed: false };
+  if (def.audit !== true) return execute(def, name, raw, ctx, options, trace);
+
+  // Resolved before the input parse: an audited action nothing can record must refuse while it
+  // has still made no change. Everything after this point has a committed write behind it.
+  const sink = auditSinkFor(name);
+  const draft = {
+    // When the attempt began, from the context's clock — never `new Date()`.
+    at: ctx.now(),
+    action: name,
+    // The brand `mutator()` stamps, read structurally — the same read `describeAction` makes,
+    // and for the same reason: importing `isMutator` would point this module at the one that
+    // imports it, for a check that needs the brand and not the predicate.
+    mutator: (target as { readonly isMutator?: unknown }).isMutator === true,
+    surface: options.surface ?? 'server',
+    ctx,
+  } as const;
+
+  let value: unknown;
+  try {
+    value = await execute(def, name, raw, ctx, options, trace);
+  } catch (error) {
+    // A failed mutation is the record an auditor wants most, so the throw is recorded before it
+    // is re-thrown — and `auditThrew` never replaces it, which is why this rethrow is
+    // unconditional rather than inside an `else`.
+    const record: AuditRecord = {
+      ...draft,
+      ...trace,
+      outcome: auditOutcomeFor(error),
+      failure: auditFailureFor(error),
+    };
+    await auditThrew(sink, record);
+    throw error;
+  }
+  // Outside the `catch` above on purpose: an `X_AUDIT_SINK_FAILED` from here describes the
+  // RECORD, not the attempt. Letting it fall into that branch wrote a second row claiming the
+  // action failed, for a handler that had committed.
+  await auditSettled(sink, { ...draft, ...trace, outcome: 'allowed', failure: null });
+  return value;
+}
+
+/**
+ * The span covers the WHOLE invocation, not just `handle`. Wrapping the handler alone reported
+ * 40ms for an action whose p99 was 2s, because `def.row()` — the loader a row-level policy needs
+ * — ran outside it, along with the input parse and `guard()`. The 1.96s was inside no span at
+ * all, so the only reading available was "framework overhead" and the only fix was hand
+ * instrumentation. One span, one extent, and the attributes that make it answerable.
+ *
+ * Attributes are chosen for bounded cardinality — surface, actor KIND, outcome, booleans — with
+ * one exception: the namespaced idempotency key, which is the single fact that joins a retry to
+ * the call it is retrying and is what a trace is for. It is never a metric label.
+ */
+async function execute(
+  def: AnyActionDef,
+  name: string,
+  raw: unknown,
+  ctx: Ctx,
+  options: InvokeOptions,
+  trace: InvokeTrace,
+): Promise<unknown> {
+  return withSpan(`action.${name}`, async (span) => {
+    span.setAttributes({
+      'ultimate.primitive': 'action',
+      'ultimate.action': name,
+      'ultimate.surface': options.surface ?? 'server',
+      'ultimate.actor.kind': ctx.actor.kind,
+      'ultimate.idempotent': def.idempotent === true,
+    });
+    try {
+      const value = await perform(def, name, raw, ctx, options, trace);
+      span.setAttributes({
+        'ultimate.outcome': 'allowed',
+        'ultimate.idempotency.replayed': trace.replayed,
+      });
+      if (trace.idempotencyKey !== null) {
+        span.setAttribute('ultimate.idempotency.key', trace.idempotencyKey);
+      }
+      return value;
+    } catch (error) {
+      // The same two words the audit record uses, from the same function: a denial and a failure
+      // are different questions, and a trace that called both "error" cannot separate them.
+      span.setAttribute('ultimate.outcome', auditOutcomeFor(error));
+      if (isUltimateError(error)) span.setAttribute('ultimate.error.code', error.code);
+      throw error;
+    }
+  });
+}
+
+/** The invocation itself, unwrapped: parse, load the row, guard, run, parse, bust. */
+async function perform(
+  def: AnyActionDef,
+  name: string,
+  raw: unknown,
+  ctx: Ctx,
+  options: InvokeOptions,
+  trace: InvokeTrace,
+): Promise<unknown> {
   const input = await validateInput(def.input, raw, name);
+  trace.input = input;
   // The one place a row-level rule gets its row. Once per invocation, never per row:
   // that asymmetry is what lets the predicate stay synchronous, so a live query can
   // re-evaluate the same policy per subscriber without a query per change event. An
@@ -96,25 +230,36 @@ async function core(
     options.surface ?? 'server',
   );
 
-  // Output parsing sits inside `run` so a replayed idempotent response is the
-  // parsed value too — one shape on the wire, first call and every retry.
+  // Output parsing sits inside `run` so a replayed idempotent response is the parsed value too —
+  // one shape on the wire, first call and every retry. No span of its own: `execute` above holds
+  // the one that covers this invocation, and a second here would only re-time its tail.
   const run = async (): Promise<unknown> => {
-    const produced = await withSpan(`action.${name}`, () =>
-      Promise.resolve(def.handle({ input, ctx })),
-    );
+    const produced = await Promise.resolve(def.handle({ input, ctx }));
     return validateOutput(def.output, produced, name);
   };
 
   const key = def.idempotent === true ? (options.idempotencyKey ?? null) : null;
   let value: unknown;
+  let wrote = true;
   if (key === null) {
     value = await run();
   } else {
     const store = options.store ?? getIdempotencyStore();
-    const outcome = await withIdempotency(store, idempotencyKeyFor(name, key), input, run);
+    // The namespaced key, not the caller's: the same key under two actions — or from two callers
+    // — is two keys, and an audit row keyed on the raw header would collide across both. The
+    // ACTOR comes from `ctx`, which `invoke` installed, so every surface scopes identically.
+    trace.idempotencyKey = idempotencyKeyFor(name, key, ctx.actor);
+    const outcome = await withIdempotency(store, trace.idempotencyKey, input, run);
     if (outcome.replayed) options.onReplay?.();
+    trace.replayed = outcome.replayed;
+    wrote = !outcome.replayed;
     value = outcome.value;
   }
-  if (def.cache !== undefined) await invalidateTags(def.cache.invalidates);
+  // Only for a run that actually happened, and only through the gate. A replay ran no handler
+  // and changed nothing the first call had not already busted — re-busting per retry re-purges
+  // the CDN and re-queues ISR for a write nobody made. And the bust is post-commit either way,
+  // so `bustAfterCommit` swallowing its own failure is what keeps a dead cache from turning a
+  // durable write into a failed action.
+  if (wrote && def.cache !== undefined) await bustAfterCommit(name, def.cache.invalidates);
   return value;
 }

package/src/job-handle.ts

@@ -1,7 +1,8 @@
 /**
- * Projection 5: an action as durable work. `@ultimat3/jobs` consumes this shape,
- * so enqueueing an existing action costs zero rewriting — and the queued run
- * goes through the same validation and policy evaluation as the HTTP call.
+ * 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. Nothing in the framework consumes it — an app bridges it into `job()`.
  */
 import type { Ctx } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
@@ -9,6 +10,24 @@ import type { Action } from './action';
 import { actionName, invoke } from './invoke';
 import { fingerprint } from './stable';
 
+/**
+ * **`@ultimat3/jobs` does not consume this, and cannot as written** (`As of 2026-08`; the header
+ * claimed it did). `isJobHandle` needs `kind === 'job'` AND membership of a module-private
+ * `WeakMap` only `job()` writes, so no externally-built object reaches the registry, the queue or
+ * the worker — and `kind: 'action-job'` is deliberately a different literal, not a near-miss.
+ *
+ * What it IS: the three fields plus the body a `JobDefinition` needs — `name`, `input`,
+ * `idempotencyKey`, and `invoke` as its `run`. An app bridges it in one call:
+ * `job({ name: h.name, input: h.input, idempotencyKey: h.idempotencyKey, tenant, retry,
+ * run: ({ input, ctx }) => h.invoke(input, ctx) })`, which yields a real handle `job()` seated.
+ *
+ * `tenant` and `retry` are what the bridge cannot fill: both are REQUIRED on `JobDefinition` with
+ * no default, on purpose — jobs states that every candidate default for `tenant` is a
+ * cross-tenant read waiting to happen. So "enqueueing an action costs zero rewriting" was never
+ * reachable; two facts an action does not declare have to come from somewhere. Whoever closes
+ * this writes the adapter in the app or at tier 4+: `action` and `jobs` are both tier 3, so
+ * neither may import the other.
+ */
 export interface ActionJobHandle<
   TInput extends StandardSchemaV1 = StandardSchemaV1,
   TOutput extends StandardSchemaV1 = StandardSchemaV1,

package/src/json-schema.ts

@@ -4,32 +4,50 @@
  */
 
 import type { StandardSchemaV1 } from '@ultimat3/schema';
-import { toJsonSchema, toMcpInputSchema } from '@ultimat3/schema';
+import { SchemaUnsupportedError, toJsonSchema, toMcpInputSchema } from '@ultimat3/schema';
 import { isJsonObject, stableStringify } from './stable';
 
 export type JsonSchemaObject = Record<string, unknown>;
 
 /**
- * Never throws: a schema that cannot be converted degrades to a permissive
- * object node, because a missing OpenAPI detail must not break a deploy.
+ * REFUSES rather than degrades. This used to swallow a conversion failure into
+ * `{ type: 'object', additionalProperties: true }` so that "a missing OpenAPI detail must not
+ * break a deploy" — which inverts axiom 3: the deploy succeeded and every caller was lied to.
+ * `toJsonSchema` throws exactly when the spec must not claim anything, and the same schema
+ * still fails `validateInput` on every payload, so the OpenAPI component and the MCP
+ * `inputSchema` were advertising "any object accepted" for an endpoint that accepts none.
+ * `registerAction` calls this at boot (`assertProjectable`), so a registered action can never
+ * reach a projection that throws.
  */
 export function jsonSchemaOf(schema: StandardSchemaV1): JsonSchemaObject {
-  return normalize(() => toJsonSchema(schema));
+  return normalizeJsonSchema(() => toJsonSchema(schema));
 }
 
 /** Draft-07, no `$schema` — the exact shape an MCP `tools/list` entry needs. */
 export function mcpSchemaOf(schema: StandardSchemaV1): JsonSchemaObject {
-  return normalize(() => toMcpInputSchema(schema));
+  return normalizeJsonSchema(() => toMcpInputSchema(schema));
 }
 
-function normalize(convert: () => unknown): JsonSchemaObject {
-  try {
-    const raw: unknown = convert();
-    if (isJsonObject(raw)) return raw;
-  } catch {
-    // fall through to the permissive node
-  }
-  return { type: 'object', additionalProperties: true };
+/**
+ * The narrowing both projections share, and the refusal it earns: a converter that answered with
+ * something that is not a JSON object is the same failure by a quieter route, so it gets the same
+ * shipped code rather than a permissive node. Exported for its own test and nothing else — it is
+ * absent from `src/index.ts`, exactly as `sortSchema` is.
+ *
+ * **The `fix:` names `introspect`, never a `toJsonSchema` member.** `SchemaProvider` declares no
+ * such member (`packages/schema/src/provider.ts`) and `toJsonSchema()` calls `introspect()`
+ * unconditionally, so the old line — "configure a provider whose toJsonSchema returns an object" —
+ * instructed a reader to implement an API that does not exist, which is axiom 4 inverted. It is
+ * the same false clause `@ultimat3/schema` deleted from its own docs; this was the user-visible
+ * half, one package over.
+ */
+export function normalizeJsonSchema(convert: () => unknown): JsonSchemaObject {
+  const raw: unknown = convert();
+  if (isJsonObject(raw)) return raw;
+  throw new SchemaUnsupportedError({
+    cause: `the schema converted to ${raw === null ? 'null' : typeof raw}, not a JSON Schema object`,
+    fix: 'declare the schema with `t` from @ultimat3/action, or add an introspect() returning a SchemaNode to the object passed to configureSchemaProvider()',
+  });
 }
 
 /** Key-sorted copy — deterministic ordering for the committed contract file. */

package/src/mcp-tool.ts

@@ -4,17 +4,25 @@
  * endpoint and cannot acquire a second authz path. One authz system, never two.
  */
 import type { Ctx } from '@ultimat3/core';
+import { isMcpExposed } from '@ultimat3/core';
 import type { AnyAction } from './action';
 import { actionName, defOf, invoke } from './invoke';
 import { type JsonSchemaObject, mcpSchemaOf, sortSchema } from './json-schema';
-import { toToolName } from './naming';
 import type { ActionPolicy } from './policy-gate';
 import { listActions } from './registry';
 
 export interface McpToolDescriptor {
+  /**
+   * The export name VERBATIM — `@ultimat3/mcp` serves that name and nothing else, so any
+   * transformation here would be a label no `tools/call` could spell. See `toMcpTool`.
+   */
   readonly name: string;
   /** The action's `mcp.description`, or its name when the author gave none. */
   readonly description: string;
+  /**
+   * The action this tool projects. Equal to `name` by construction since 2026-08 — kept because
+   * a reader asking "which action is behind this tool?" should not have to know that.
+   */
   readonly action: string;
   /**
    * The action's own policy object, not a copy — `tool().policy === action.policy`
@@ -31,11 +39,16 @@ export interface McpInvokeOptions {
   readonly idempotencyKey?: string | null;
 }
 
+/**
+ * The tool name is the export name VERBATIM — it was `snake_case`d until 2026-08, and
+ * `@ultimat3/mcp` has only ever served the verbatim one, so `.tool().name` was a label no
+ * `tools/call` accepted. One name per action, on every surface.
+ */
 export function toMcpTool(target: AnyAction): McpToolDescriptor {
   const name = actionName(target);
   const def = defOf(target);
   return {
-    name: toToolName(name),
+    name,
     description: def.mcp?.description ?? name,
     action: name,
     policy: def.policy,
@@ -56,10 +69,11 @@ export function toMcpTool(target: AnyAction): McpToolDescriptor {
  * It read `!== false` until 2026-08, which made writing an action silently hand every agent a
  * new write capability — and disagreed with `@ultimat3/mcp`'s `exposedPrimitives`, the projection
  * that actually builds a catalog. Two functions answering "is this a tool?" differently is the
- * ambiguity axiom 1 rejects, so the fail-closed one wins.
+ * ambiguity axiom 1 rejects, so the fail-closed one wins — and `isMcpExposed` from
+ * `@ultimat3/core` is now the single answer every reader in the framework asks.
  */
 export function isExposed(target: AnyAction): boolean {
-  return target.mcp?.expose === true;
+  return isMcpExposed(target.mcp);
 }
 
 /** Deterministic order — the tool list is part of the agent-visible contract. */

package/src/mutator.ts

@@ -70,6 +70,13 @@ export interface MutatorDef<TInput extends StandardSchemaV1, TOutput extends Sta
   readonly cache?: ActionCache;
   readonly mcp?: ActionMcp;
   readonly idempotent?: boolean;
+  /**
+   * Record every attempt through the installed `AuditSink`. Same key, same meaning as an
+   * action's — a mutator IS an action, so it inherits the seam rather than getting a second one.
+   * `.local()` is the one half nothing records: it never leaves the client, so there is no
+   * server-authoritative attempt to attest to.
+   */
+  readonly audit?: boolean;
   /** Optimistic twin: runs against the local store, synchronously, no I/O. */
   local(tx: LocalTx, input: InferOutput<TInput>): void;
   /** Authoritative write. Identical to an action `handle`, ctx-first for symmetry. */
@@ -123,6 +130,7 @@ export function mutator<TInput extends StandardSchemaV1, TOutput extends Standar
     ...(def.cache === undefined ? {} : { cache: def.cache }),
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
     ...(def.idempotent === undefined ? {} : { idempotent: def.idempotent }),
+    ...(def.audit === undefined ? {} : { audit: def.audit }),
     handle: ({ input, ctx }) => def.server(ctx, input),
   };
   return wrap(def, action(actionDef));

package/src/naming.ts

@@ -1,7 +1,8 @@
 /**
- * The one naming rule: an action's export name derives its HTTP path and MCP
- * tool name. Pure string math so the browser client can derive the same path
- * without importing a byte of server code.
+ * The one naming rule: an action's export name derives its HTTP path and its
+ * OpenAPI component names. Pure string math so the browser client can derive
+ * the same path without importing a byte of server code. The MCP tool name is
+ * derived by nothing — it is the export name verbatim.
  */
 
 /** Irregular plurals we actually hit in domain models. Extend deliberately, not eagerly. */
@@ -66,10 +67,9 @@ export function derivePath(name: string): ActionPath {
   return { verb: head, resource, path: `/api/${resource}/${head}` };
 }
 
-/** MCP tool names are `snake_case`: `publishPost` -> `publish_post`. */
-export function toToolName(name: string): string {
-  return splitWords(name).join('_');
-}
+// There is deliberately no `toToolName`. An MCP tool name is the export name verbatim — the one
+// `@ultimat3/mcp` serves and the one a `tools/call` spells — so a second derivation would be a
+// second name for one action, which is what shipped `publish_post` in two committed contracts.
 
 /** OpenAPI `operationId` is the action name verbatim — it is already unique. */
 export function toOperationId(name: string): string {

package/src/policy-gate.ts

@@ -7,7 +7,7 @@
 import type { Actor, Ctx } from '@ultimat3/core';
 import { assertNever, isAnonymous } from '@ultimat3/core';
 import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
-import { enforce } from '@ultimat3/policy';
+import { enforce, policyPermissions as flattenedPermissions } from '@ultimat3/policy';
 import { ActionDeniedError } from './errors';
 
 /**
@@ -75,7 +75,19 @@ export function actorOf(ctx: Ctx): Actor | null {
   return isAnonymous(ctx.actor) ? null : ctx.actor;
 }
 
-/** The capability an action requires, for manifests and OpenAPI metadata. */
+/** 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);
+}