@ultimat3/action 1.2.0 → 3.0.0

package/README.md

@@ -42,7 +42,7 @@ imports one package for the primitive and its schemas, never two.
 import { action, t } from '@ultimat3/action';
 
 export const publishPost = action({
-  input:  t.object({ postId: t.uuid, notify: t.boolean.default(true) }),
+  input:  t.object({ postId: t.uuid, orgId: t.uuid, notify: t.boolean.default(true) }),
   output: PostView,
   policy: can('post:publish', ({ input, actor }) => ownsPost(actor, input.postId)),
   cache:  { invalidates: [tag.post, tag.feed] },
@@ -50,7 +50,7 @@ export const publishPost = action({
   idempotent: true,
   async handle({ input, ctx }) {
     const post = await ctx.posts.publish(input.postId);
-    if (input.notify) await notifySubscribers.enqueue({ postId: post.id });
+    if (input.notify) await notifySubscribers.enqueue({ postId: post.id, orgId: input.orgId });
     return post;
   },
 });
@@ -75,21 +75,33 @@ export const api = defineApi({
 export type Api = typeof api;
 ```
 
+Six keys, all optional:
+
 | Key | Goes to | Why |
 |---|---|---|
 | `actions` | the action registry | the primitive |
 | `mutators` | the action registry | a mutator IS an action, on the same authz path |
 | `llm` | the action registry | `llm()` returns an action, not a ninth primitive |
 | `queries` | `@ultimat3/query`'s registry, via core's registrar table | `query` is on this tier, so importing it here would be a build error |
+| `jobs` | `@ultimat3/jobs`' registry, the same way | the export name becomes the durable queue key — a job row names the handle, not a counter |
+| `tasks` | `@ultimat3/jobs`' registry, the same way | handing a task over is what names its cron after its export |
+
+Jobs register **before** tasks: a task's descriptor lists the jobs it enqueues by name, so the
+other order would read the queue keys one boot step before they were assigned. `Api` carries all
+four maps back — `api.actions`, `api.queries`, `api.jobs`, `api.tasks` — keyed by the name
+registration stamped.
 
 Names come from **export names** — that is what makes the path, the tool name and the
 OpenAPI `operationId` derivable everywhere without a second declaration. Registration
 stamps the name onto the action the module exported, so the binding you imported is the
 one that projects; a projection attempted before boot is `X_ACTION_UNREGISTERED`. Two
-features exporting one name collide with `X_ACTION_DUPLICATE` rather than merging.
+features exporting one name collide with `X_ACTION_DUPLICATE` rather than merging, and two
+names deriving one route collide with `X_ACTION_PATH_DUPLICATE` — `pluralize` leaves a trailing
+`s` alone, so `archiveOrder` and `archiveOrders` are two exports and one `POST /api/orders/archive`.
 
-`registerActions` / `registerQueries` are what `defineApi` composes. An app calling them
-directly is a second path.
+`registerActions` is what `defineApi` composes for the three action-shaped keys; the other three
+go through core's `primitiveRegistrar(kind)`, because this package may not import `@ultimat3/query`
+or `@ultimat3/jobs` sideways. An app calling either directly is a second path.
 
 ## Call it — `rpc`
 
@@ -107,7 +119,7 @@ a page's module graph free of any edge to a feature's implementation.
 ## Path derivation
 
 First camelCase word is the verb; the rest is the resource, last word pluralized,
-kebab-cased. The **MCP tool name is not derived** — it is the export name verbatim, because
+kebab-cased. The **MCP tool name is not derived at all** — it is the export name verbatim, because
 that is what `defineAppMcp`'s `scopes:` and a `tools/call` have to spell.
 
 | Action | Route | MCP tool |
@@ -117,6 +129,18 @@ that is what `defineAppMcp`'s `scopes:` and a `tools/call` have to spell.
 | `likePost` | `POST /api/posts/like` | `likePost` |
 | `checkout` (single word) | `POST /api/checkouts/invoke` | `checkout` |
 
+**One name, four surfaces** — `.tool().name`, `openapi.json`'s `x-ultimate.mcpTool`,
+`describeAction().mcp.tool` (what `x actions describe --json`, `x actions list --json`, the
+`actions.describe` dev MCP tool and the `/_x` Routes panel show) and the catalog `@ultimat3/mcp`
+serves. It was two until 2026-08: a `toToolName()` here snake_cased the first three to
+`publish_post` while the server answered only `publishPost`, so an agent that read the published
+contract called a tool that does not exist. `toToolName` is **deleted**, not deprecated — a second
+derivation is a second name. `mcp-tool.test.ts`'s "one name per action, on every surface" is what
+keeps it that way.
+
+`x.manifest.json` is **not** one of the four: `ActionFact.mcp` is `{ expose, description? }`, so
+the manifest never carried a tool name and was never wrong about one.
+
 ## One invocation core
 
 `invoke()` is the only execution path: **parse input → evaluate policy → handle →
@@ -135,6 +159,11 @@ no `.def`. A second authz path cannot be written without deleting that store.
 | handle | whatever the handler throws |
 | parse output | `X_OUTPUT_INVALID` — and fields the schema never declared are dropped |
 
+`cache: { invalidates }` fans out **after** the handler commits, so it never fails it: a
+fan-out that refuses — an undeclared tag, `X_CACHE_TAG_UNKNOWN` — is one
+`action.invalidate.failed` log line and the entries expire by TTL. A replayed idempotent
+call busts nothing; the first call already did.
+
 Registering an action without `policy:` throws `X_ACTION_POLICY_MISSING`; there is
 no bypass flag. A look-alike that never came out of `action()` is `X_ACTION_FOREIGN`.
 
@@ -185,25 +214,257 @@ LocalTables { posts: PostRow } }`.
 name-sorted, and reads no clock, env or random source — same registry ⇒ same bytes ⇒
 `x verify` can diff the spec and fail on `X_CONTRACT_DRIFT`.
 
-`idempotent: true` + an `Idempotency-Key` header replays the first response
-(`x-ultimate-replayed: 1`); a duplicate still in flight, or a reused key with a new
-payload, is `X_IDEMPOTENCY_CONFLICT`. Store is swappable via `setIdempotencyStore()`.
+## `rateLimit:` is the enforced limit
+
+```ts
+rateLimit: { limit: 5, windowMs: 600_000 },   // 5 held, one back every two minutes
+```
+
+One declaration, three places it lands: the bucket the limiter runs on (named after the action,
+registered by `@ultimat3/http`'s `withRouteBuckets` when the route is mounted), the
+`ratelimit-limit` header the caller reads, and `x-ultimate.rateLimit` in the OpenAPI operation.
+`toBucket` is the only conversion — `capacity: limit`, `refillPerSecond: limit / (windowMs / 1000)`
+— so the published numbers and the enforced ones cannot differ. It lives in `@ultimat3/http`,
+beside `Bucket` and the limiter maths, and is re-exported here: `@ultimat3/query` needs the same
+conversion and is the same tier, so a copy in either package would be a second answer for the
+other. A pair the limiter cannot run on is `X_RATE_LIMIT_INVALID`, at projection. An action that declares nothing
+stays on the `default` bucket. An app that also configures `http.rateLimit.buckets.<actionName>`
+with **different** numbers is `X_RATE_LIMIT_BUCKET_CONFLICT` at boot: neither source wins, because
+the loser would go on being read as enforced.
+
+## `idempotent:` — and where its records live
+
+`idempotent: true` + an `Idempotency-Key` header replays the first **outcome**
+(`x-ultimate-replayed: 1`); a duplicate still in flight, or a reused key with a new payload, is
+`X_IDEMPOTENCY_CONFLICT`.
+
+**A record belongs to one caller.** The key is namespaced by action *and* by actor
+(`idempotencyKeyFor`), so two callers sending the same header value hold two records — the same
+value under one action used to be one shared record, which replayed one caller's response to
+another. A **blank** `Idempotency-Key:` is `X_IDEMPOTENCY_KEY_INVALID`, never read as "no key":
+`Headers.get()` answers `''` and not `null`, so a blank header was itself a shared key, and the
+quiet reading — run without idempotency — loses the retry protection exactly when a client's key
+interpolation broke. Omit the header to run un-keyed; the published `maxLength: 255` is enforced
+by the same refusal. An anonymous caller has no identity to narrow to, so anonymous callers of a
+public idempotent action still share a key space: a UUID key is what keeps them apart.
+
+**A failed first attempt is replayed too, not re-run.** `guard()` and the input parse both happen
+*before* the idempotency gate, so everything it 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.
+The reservation is settled as a FAILURE and the retry re-throws it under the first attempt's own
+code. Releasing it there is what made idempotency the cause of a double charge.
+
+**Where the records live is declared, and refused at registration.** The default store is process
+memory — bounded, swept on a 24h window, and `scope: 'process'`. An app on more than one replica
+must say so and bring a store that can keep it, or the retry that lands on another replica finds
+no record and runs the handler again:
+
+```ts
+// boot, before registerActions()
+import {
+  configureIdempotency,
+  postgresIdempotencyStore,
+  setIdempotencyStore,
+} from '@ultimat3/action';
+
+setIdempotencyStore(postgresIdempotencyStore({ executor: Bun.sql }));
+configureIdempotency({ scope: 'shared' });
+```
+
+`configureIdempotency({ scope: 'shared' })` over a per-process store — or over a store that
+declares no scope at all — is `X_IDEMPOTENCY_NOT_SHARED` at `registerAction`, before the socket
+opens. The table is `SQL_IDEMPOTENCY_TABLE`, applied the way `SQL_JOBS_TABLE` is: `x db up` in
+development, the release-phase `ROLE=migrate` in production. `postgresIdempotencyStore(...)
+.purgeExpired()` is the sweep — Postgres forgets nothing on its own, so run it from a `task`.
+
+**A plain mutating `route` can use the same gate.** `withIdempotency`, `IDEMPOTENCY_HEADER`,
+`idempotencyKeyFor` and `getIdempotencyStore` are all public, so a route that is not an action
+reserves and replays through the one implementation rather than growing a second:
+
+```ts
+const key = req.header(IDEMPOTENCY_HEADER);
+// No header is the caller declining idempotency; a BLANK one is not, and
+// `idempotencyKeyFor` refuses it below rather than filing a record everyone shares.
+if (key === null) return json(await refund(input));
+const outcome = await withIdempotency(
+  getIdempotencyStore(),
+  // Namespaced by action AND actor: otherwise two routes share one caller's key, and two
+  // callers share one record.
+  idempotencyKeyFor('refundCharge', key, req.ctx.actor),
+  input,
+  () => refund(input),
+);
+```
+
+A `query` has none and never will: a read has nothing to be idempotent about.
+
+## `deprecated:` — a compat window, not a version
+
+```ts
+deprecated: { since: '2026-08-01T00:00:00Z', sunset: '2026-12-31T23:59:59Z', replacedBy: 'searchOrders' },
+```
+
+Four things at once: `Deprecation: @1754006400` (RFC 9745) and `Sunset: Wed, 31 Dec 2026 …`
+(RFC 8594) on **every** response including the failures, `link: </api/orders/search>;
+rel="successor-version"`, `deprecated: true` plus `x-ultimate.deprecation` in the OpenAPI
+operation, and a `deprecated_calls_total{primitive,name}` counter — which is the only way to
+answer "is anyone still calling it?" before deleting it. A date that cannot be rendered is
+`X_ACTION_DEPRECATION_INVALID` at projection, not on the first request.
+
+**Versioning itself is deliberately absent, and will stay absent.** Running `v1` and `v2` of one
+action side by side is two deployments behind one ingress — axiom 7's answer, costing this package
+no router feature, no path prefix and no second registry. What ships is the window: a date, a
+successor, and a number.
+
+## Audit — the seam, not the row
+
+`audit: true` on any `action` or `mutator` sends **every attempt** — allowed, denied and failed
+— to the installed `AuditSink`. Opt-in per declaration, never a global switch: a login and a
+price change are not the same event, and the framework is not the thing that knows which of
+them your business has to keep.
+
+```ts
+import { setAuditSink } from '@ultimat3/action';
+
+setAuditSink({
+  async write(record) { await record.ctx.db.auditRows.insert(myRow(record)); },
+});
+```
+
+What the framework supplies is what it genuinely knows:
+
+| Field | |
+|---|---|
+| `at` | when the attempt began, from `ctx.now()` — an instant, never a rendering |
+| `action` / `mutator` | the registered name, and which primitive it was |
+| `surface` | `server` \| `http` \| `mcp` \| `job` — the same price change over MCP is not the same event |
+| `ctx` | the whole context: actor, `requestId`, `traceId`, locale, and the services a sink needs to write a row |
+| `input` | the **parsed** input, or `undefined` when the parse is what failed — never the raw payload |
+| `idempotencyKey` / `replayed` | the namespaced key, and whether this was a call rather than a write |
+| `outcome` | `allowed` \| `denied` \| `failed` |
+| `failure` | the `X_*` code and the thrown value, on every outcome but `allowed` |
+
+What it does **not** supply: an audit entity, a schema, a retention policy, a storage backend, a
+hash chain, a subject index, or an opinion on what "who" means under impersonation. Four apps
+model those four ways; shipping one would make three of them wrong.
+
+A denial is recorded because `invoke` wraps the whole path — `guard` throws **before** `handle`,
+so nothing you could write around your own handler would ever see one. That is the reason this
+lives in the framework and the row does not.
+
+**Failure is loud, both ways.** `audit: true` with no sink installed is `X_AUDIT_SINK_MISSING`,
+raised before the input parse — the one audit failure with no committed write behind it. A sink
+that refuses a **successful** record is `X_AUDIT_SINK_FAILED`: the deliberate opposite of the
+cache tier's `bestEffort`, because a dropped cache entry expires by TTL and the stack heals
+itself while nothing ever re-derives an audit row that was never written. It is post-commit all
+the same, and the error says so.
+
+**Its `fix:` branches, because only one of the two is ever true.** Retrying is safe exactly when
+*this invocation* went through the idempotency store — then the settled record replays and the
+audit row 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` but the caller sent no
+`Idempotency-Key`**: `invoke` reads `def.idempotent === true ? (options.idempotencyKey ?? null)
+: null`, so both collapse to the same `null`. In that case the error says *do not retry* and
+names the edit — telling a caller to re-run a committed mutator is worse than saying nothing.
+`meta.replayable` carries the same fact to `--json`.
+
+A sink that refuses a **denied or failed** record is logged as
+`audit.sink.failed` and the original error still reaches the caller: answering
+`X_AUDIT_SINK_FAILED` there would hide the `X_FORBIDDEN` from whoever has to act on it.
+
+Your house rule goes in a wrapper, not in a config option — the same shape as `tenantEntity()`:
+
+```ts
+// apps/web/shared/base/audited-mutator.ts — the app's convention, written once
+import { mutator, type MutatorDef } from '@ultimat3/action';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+
+/** Every write in this app is recorded and retryable — declared once, not at forty call sites. */
+export const auditedMutator = <I extends StandardSchemaV1, O extends StandardSchemaV1>(
+  def: MutatorDef<I, O>,
+) => mutator({ ...def, audit: true, idempotent: true });
+```
+
+Nothing downstream can tell the difference: `isMutator()` is structural and `registerActions`
+names the object in place, so every projection, the manifest and admin CRUD work on it exactly
+as on a hand-written one.
+
+The row it produces is the app's, and so is every question the framework refused to answer —
+which fields, whose tenant, chained or not, kept how long:
+
+```ts
+setAuditSink({
+  async write(record) {
+    const { ctx } = record;                             // the services a sink needs to write a row
+    const prev = await chainHead(ctx);                  // hash-chained: the app's choice
+    await ctx.db.auditRows.insert({
+      orgId: orgOf(ctx.actor),                          // tenancy: derived from the actor
+      subjectId: subjectOf(record.action, record.input),// queryable by subject: the app's index
+      actorId: impersonatorOf(ctx.actor) ?? ctx.actor.id,
+      at: record.at, outcome: record.outcome, code: record.failure?.code ?? null,
+      prevHash: prev, hash: await sha256(prev, record),
+    });
+  },
+});
+```
+
+## Contract tests
+
+`publishPost.contract()` returns three assertions. Run them; they throw `X_CONTRACT_DRIFT`.
+
+| Assertion | Holds when |
+|---|---|
+| input schema rejects garbage | the invocation fails `X_INPUT_INVALID` — that code, not any failure |
+| policy denies an anonymous actor | the invocation fails with an `ActionDeniedError` |
+| OpenAPI document contains its operation | the derived path is in `buildOpenApi()` |
+
+The denial assertion sends an input synthesized from `input:`'s own schema — required keys
+only, formats included — because a payload the schema rejects never reaches a policy. It
+asserts the denial, not `X_FORBIDDEN`: a denial carries the policy decision's own code, and
+`can()` answers a null actor with `X_UNAUTHENTICATED`.
+
+```ts
+publishPost.contract({
+  garbage: 42,                                 // what the input schema must reject
+  input: { postId, orgId },                    // when the synthesized one cannot fit
+  ctx: myCtx,                                  // default: an anonymous context
+})
+```
+
+Pass `input:` when the schema carries a constraint the IR cannot invert (a bare `pattern`) or
+when `row:` needs an id that resolves. Anything thrown *before* the policy decides is drift,
+never a pass — the assertion says which code got in the way and names `input:` as the fix.
 
 ## Errors
 
 | Code | When | Fix |
 |---|---|---|
 | `X_ACTION_DUPLICATE` | two actions registered under one name | rename one export |
+| `X_ACTION_PATH_DUPLICATE` | two actions derive one HTTP path (`archiveOrder` / `archiveOrders`) | rename one export |
 | `X_ACTION_POLICY_MISSING` | registration without `policy:` | add `policy: can('…')` |
+| `X_RATE_LIMIT_INVALID` | `rateLimit:` with a non-positive or non-finite half — `windowMs: 0` refills infinitely. Owned by `@ultimat3/http`, which owns the conversion | make both positive, or delete the block |
+| `X_ACTION_DEPRECATION_INVALID` | `deprecated:` with a `since`/`sunset` that is not a date | use an ISO-8601 instant |
 | `X_INPUT_INVALID` | input failed the Standard Schema | `x actions describe <name> --json` |
 | `X_IDEMPOTENCY_CONFLICT` | key reused with a new payload / still in flight | new key, or retry later |
+| `X_IDEMPOTENCY_KEY_INVALID` | `Idempotency-Key:` sent blank (`Headers.get()` answers `''`, not `null`) or past 255 characters | send one unique value per request, or omit the header |
+| `X_IDEMPOTENCY_NOT_SHARED` | `configureIdempotency({ scope: 'shared' })` over a per-process (or scope-less) store | install `postgresIdempotencyStore({ executor: Bun.sql })` at boot |
+| `X_IDEMPOTENCY_REPLAYED_FAILURE` | a retried key replays a first attempt that failed and carried no framework code of its own | read the first attempt, then send a fresh key |
 | `X_CONTRACT_DRIFT` | client/server build skew, missing spec entry | reload / `x verify --contract` |
-| `X_RPC_FAILED` | non-`problem+json` failure reached the client | check the gateway |
+| `X_RPC_FAILED` | non-`problem+json` failure, or a body naming no `X_` code | check the gateway |
 | `X_ACTION_UNREGISTERED` | projected before `registerActions()` ran | register at boot |
+| `X_AUDIT_SINK_MISSING` | `audit: true` and no sink installed — raised before the input parse | `setAuditSink(yourSink)` at boot |
+| `X_AUDIT_SINK_FAILED` | the sink refused the record for an attempt that **succeeded** | fix the sink — then retry the same `Idempotency-Key` if this call carried one, else reconcile by hand |
 
 Denials re-throw the policy layer's own codes (`X_FORBIDDEN`, `X_UNAUTHENTICATED`) —
 this package never invents an authz code.
 
+The client does the same with the server's: a `problem+json` failure comes back as a
+`RemoteActionError` keeping the code the server sent, marked `meta.origin: 'remote'` because
+the browser bundle may never have registered it, and linked only to a page that exists — the
+server's own `docs`/`type` when it sent an `http(s)` one, this build's registered link when it
+knows the code, otherwise the error index. A per-code URL is never synthesized for a code
+nothing here declares.
+
 ## Boundaries
 
 Tier 3. Imports `@ultimat3/core`, `schema`, `cache`, `policy`, `http`. Never imports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "1.2.0",
+  "version": "3.0.0",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,10 +31,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "1.2.0",
-    "@ultimat3/core": "1.2.0",
-    "@ultimat3/http": "1.2.0",
-    "@ultimat3/policy": "1.2.0",
-    "@ultimat3/schema": "1.2.0"
+    "@ultimat3/cache": "3.0.0",
+    "@ultimat3/core": "3.0.0",
+    "@ultimat3/http": "3.0.0",
+    "@ultimat3/policy": "3.0.0",
+    "@ultimat3/schema": "3.0.0"
   }
 }

package/src/action.ts

@@ -5,10 +5,13 @@
  */
 
 import type { CacheTag } from '@ultimat3/cache';
+import { tagKeys } from '@ultimat3/cache';
 import type { Actor, Ctx } from '@ultimat3/core';
+import { isMcpExposed } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { ClientMethod, ClientOptions } from './client';
 import type { ContractTest, ContractTestOptions } from './contract-test';
+import type { Deprecation } from './deprecation';
 import { facadeFor } from './facade';
 import type { OpenApiOperation } from './http';
 import type { IdempotencyStore } from './idempotency';
@@ -17,9 +20,13 @@ import type { ActionJobHandle } from './job-handle';
 import type { JsonSchemaObject } from './json-schema';
 import { jsonSchemaOf } from './json-schema';
 import type { McpToolDescriptor } from './mcp-tool';
-import { derivePath, toToolName } from './naming';
-import { type ActionPolicy, policyCapability, type Surface } from './policy-gate';
-import { tagKeys } from './tags';
+import { derivePath } from './naming';
+import {
+  type ActionPolicy,
+  policyCapability,
+  policyPermissions,
+  type Surface,
+} from './policy-gate';
 
 export interface ActionCache {
   /** Tags dropped from every cache tier after the handler settles. */
@@ -84,8 +91,32 @@ export interface ActionDef<
   readonly cache?: ActionCache;
   readonly mcp?: ActionMcp;
   readonly rateLimit?: ActionRateLimit;
+  /**
+   * On its way out. Declared here and projected everywhere at once: `Deprecation` and `Sunset`
+   * response headers (RFC 9745 / RFC 8594), a `rel="successor-version"` link when `replacedBy`
+   * names one, `deprecated: true` in the OpenAPI operation, and a
+   * `deprecated_calls_total{name}` counter — which is the only way to answer "is anyone
+   * still calling it?" before deleting it.
+   *
+   * **Versioning is deliberately NOT here.** Running `v1` and `v2` of one action side by side is
+   * two deployments behind one ingress, which is axiom 7's answer and costs this package no
+   * router feature; see the README. What ships is the compat WINDOW: a date, a successor, and a
+   * number.
+   */
+  readonly deprecated?: Deprecation;
   /** Marks the action safe to retry with an `Idempotency-Key`. */
   readonly idempotent?: boolean;
+  /**
+   * Record every attempt at this action through the installed `AuditSink` — allowed, denied and
+   * failed alike. Opt-in per declaration and never a global switch: a login and a price change
+   * are not the same event, and the framework is not the thing that knows which of them an app
+   * has to keep. `true` with no sink installed is `X_AUDIT_SINK_MISSING`, refused before the
+   * input parse.
+   *
+   * What the sink DOES with the record — which fields survive, how long, hash-chained or not,
+   * indexed by subject or not — is the app's, and this package ships none of it.
+   */
+  readonly audit?: boolean;
   /**
    * Loads the row a row-level `policy` decides about, once per invocation, after the
    * input parse and before the guard. This is the async half authz is not allowed to
@@ -136,13 +167,28 @@ export interface ActionDescriptor {
   readonly resource: string;
   readonly method: 'POST';
   readonly path: string;
+  /** The policy's DISPLAY label. A composite renders as `and(a:b, c:d)` — never a permission. */
   readonly capability: string;
+  /**
+   * Every permission the policy tree references, flattened. This is the field a compliance
+   * report matches a grant against: `capability` is a label, so `x policy list` reported every
+   * composite-guarded action's permissions as unenforced — real grants shown as dead.
+   */
+  readonly permissions: readonly string[];
   readonly input: JsonSchemaObject;
   readonly output: JsonSchemaObject;
   readonly invalidates: readonly string[];
   readonly idempotent: boolean;
+  /**
+   * Whether every attempt reaches the audit sink. Published here for the same reason
+   * `idempotent` is: "which of these writes leave a trail" is a question an agent asks of
+   * `x actions list --json`, and a fact nothing publishes is a fact nobody can check.
+   */
+  readonly audited: boolean;
   readonly mcp: McpDescriptorMeta;
   readonly rateLimit: ActionRateLimit | null;
+  /** Published so `x actions list --json` can answer "what is retiring, and when". */
+  readonly deprecated: Deprecation | null;
 }
 
 /**
@@ -157,7 +203,9 @@ export interface AnyActionDef {
   readonly cache?: ActionCache;
   readonly mcp?: ActionMcp;
   readonly rateLimit?: ActionRateLimit;
+  readonly deprecated?: Deprecation;
   readonly idempotent?: boolean;
+  readonly audit?: boolean;
   row?(args: { readonly input: unknown; readonly ctx: Ctx }): unknown;
   handle(args: { readonly input: unknown; readonly ctx: Ctx }): unknown;
 }
@@ -177,6 +225,18 @@ export interface AnyAction {
   as(actor: Actor | null, input: unknown, options?: InvokeOptions): Promise<unknown>;
   tool(): McpToolDescriptor;
   openapi(): OpenApiOperation;
+  /**
+   * The durable-work shape, erased. `listActions()` and `getAction(name)` hand back this view
+   * and nothing else, so leaving `job()` off it meant the registry could project an action to
+   * every surface except the queue — `getAction('publishPost')?.job()` was a type error against
+   * an object that has had the method since `facadeFor` bound it.
+   *
+   * It erases where `client()` cannot: `ActionJobHandle`'s members are method-syntax, so their
+   * parameters stay bivariant, and its output erases to `unknown`. `ClientMethod` is a function
+   * type — contravariant input — and `(input: unknown) => …` is a supertype of nothing.
+   * `type-pins.ts` holds both halves of that as build errors.
+   */
+  job(): ActionJobHandle;
   contract(options?: ContractTestOptions): readonly ContractTest[];
 }
 
@@ -195,8 +255,10 @@ export interface Action<
     options?: InvokeOptions,
   ): Promise<InferOutput<TOutput>>;
   /**
-   * Typed against this action's schemas, which is the whole point of both — so they
-   * live here and not on the schema-erased `AnyAction` view.
+   * Typed against this action's schemas, which is the whole point of it — and the reason
+   * `client()` lives here alone: its input sits in a contravariant position, so no erased
+   * spelling of it is assignable from a concrete one. `job()` is the narrowing of the erased
+   * view's, not a second declaration of it.
    */
   client(options: ClientOptions): ClientMethod<TInput, TOutput>;
   job(): ActionJobHandle<TInput, TOutput>;
@@ -281,15 +343,27 @@ export function describeAction(target: AnyAction): ActionDescriptor {
     method: 'POST',
     path: path.path,
     capability: policyCapability(def.policy),
+    // The flattened list, beside the label and never instead of it: one is read, one is matched.
+    permissions: policyPermissions(def.policy),
     input: jsonSchemaOf(def.input),
     output: jsonSchemaOf(def.output),
     invalidates: tagKeys(def.cache?.invalidates ?? []),
     idempotent: def.idempotent === true,
+    audited: def.audit === true,
     mcp: {
-      expose: mcp?.expose ?? true,
-      tool: toToolName(name),
+      // `isMcpExposed`, not `?? true`: this fact is what the manifest publishes and what the
+      // contract diff classifies, so it has to be the answer the tool projection actually gives.
+      // Fail-open here published every action as a tool no surface would ever serve, which made
+      // a first honest `expose: false` read as a withdrawn capability and demand a major bump.
+      expose: isMcpExposed(mcp),
+      // The export name verbatim, which is the only name `@ultimat3/mcp` will answer a
+      // `tools/call` for. A derived one made every descriptor reader — `x actions describe
+      // --json`, the `actions.describe` dev tool, the `/_x` panel — name a tool no surface
+      // serves. `x.manifest.json` is not among them: it copies `expose` and `description` only.
+      tool: name,
       description: mcp?.description ?? null,
     },
     rateLimit: def.rateLimit ?? null,
+    deprecated: def.deprecated ?? null,
   };
 }

package/src/audit-gate.ts

@@ -0,0 +1,92 @@
+/**
+ * The only file in this package that calls an `AuditSink`, and the one place the "a sink may not
+ * silently swallow" rule is spelled. Two failure policies, because an attempt that succeeded and
+ * an attempt that already failed do not want the same answer.
+ */
+
+import { isUltimateError, logger } from '@ultimat3/core';
+import type { AuditFailure, AuditOutcome, AuditRecord, AuditSink } from './audit';
+import { getAuditSink } from './audit';
+import { ActionDeniedError, AuditSinkFailedError, AuditSinkMissingError } from './errors';
+
+/**
+ * Resolved before the input parse, never after: an audited action that nothing can record must
+ * refuse while it has still made no change. This is the only audit failure with no committed
+ * write behind it, which is exactly why it is checked first.
+ */
+export function auditSinkFor(action: string): AuditSink {
+  const sink = getAuditSink();
+  if (sink === null) throw new AuditSinkMissingError(action);
+  return sink;
+}
+
+/**
+ * An authz refusal is `denied`; everything else that threw is `failed`, an unparsed input
+ * included.
+ *
+ * TOTAL, the same rule core's `isThrownError` states: `instanceof` runs a `Proxy`'s
+ * `getPrototypeOf` trap, and both callers ask this question inside a `catch` that is still
+ * holding the app's own error — `execute`'s span attribute and the one place the `failed` record
+ * is produced. A probe that threw there REPLACED the caller's throwable with its own `TypeError`,
+ * so an app catching by `instanceof` upstream stopped matching. A value that refuses to be
+ * examined is not evidence of a policy denial, so it fails closed to `failed`.
+ */
+export function auditOutcomeFor(error: unknown): AuditOutcome {
+  try {
+    return error instanceof ActionDeniedError ? 'denied' : 'failed';
+  } catch {
+    return 'failed';
+  }
+}
+
+export function auditFailureFor(error: unknown): AuditFailure {
+  return { code: isUltimateError(error) ? error.code : null, error };
+}
+
+/**
+ * The record for an attempt that SUCCEEDED. A sink that refuses fails the invocation — the
+ * deliberate opposite of `bustAfterCommit`, which absorbs its own failure because a stale cache
+ * entry expires by TTL and the stack heals itself. Nothing heals a missing audit row: the only
+ * process that held the facts has returned. So "if it isn't logged, it didn't happen" is enforced
+ * on the caller rather than on a log line nobody reads.
+ *
+ * It is post-commit all the same, and the error says so instead of pretending the write was
+ * rolled back. That is the honest half of the choice: what the caller gains is being TOLD.
+ *
+ * Whether a retry is SAFE is the record's own `idempotencyKey`, not the declaration's
+ * `idempotent`. The key is non-null exactly when this invocation went through the idempotency
+ * store, which is the one condition under which a retry replays instead of re-running a handler
+ * that has already committed — and it is null both for a non-idempotent action and for an
+ * idempotent one whose caller sent no header.
+ */
+export async function auditSettled(sink: AuditSink, record: AuditRecord): Promise<void> {
+  try {
+    await sink.write(record);
+  } catch (error) {
+    throw new AuditSinkFailedError(record.action, error, record.idempotencyKey !== null);
+  }
+}
+
+/**
+ * The record for an attempt that THREW. The sink's failure is reported and the original error is
+ * the one the caller gets — replacing a denial with `X_AUDIT_SINK_FAILED` would hide the
+ * `X_FORBIDDEN` from whoever has to act on it, and would answer a probing client differently
+ * depending on whether the audit backend happened to be up, which is an oracle.
+ *
+ * Never a silent swallow: the log line is the same shape every other subsystem writes, so
+ * `audit.sink.failed` is one alert rule over every action in the app.
+ */
+export async function auditThrew(sink: AuditSink, record: AuditRecord): Promise<void> {
+  try {
+    await sink.write(record);
+  } catch (error) {
+    // Core's logger, not `ctx.logger`: an HTTP `Ctx` is a cast request context that carries none,
+    // the same reason `cache-gate.ts` gives. Never the record — rendering an input the sink just
+    // choked on is the second throw this branch exists to prevent.
+    logger.error('audit.sink.failed', {
+      action: record.action,
+      outcome: record.outcome,
+      error,
+    });
+  }
+}