@ultimat3/action 1.0.0

package/src/http.ts

@@ -0,0 +1,149 @@
+/**
+ * Projections 1 and 2: an action becomes `POST /api/<resource>/<verb>` plus the
+ * OpenAPI operation describing it. Policy enforcement, input validation,
+ * idempotency and cache invalidation are wired here and are not optional —
+ * there is no way to mount an action without them.
+ */
+
+import { isUltimateError } from '@ultimat3/core';
+import type { Route, RouteMeta, UltimateRequest } from '@ultimat3/http';
+import { json, problem } from '@ultimat3/http';
+import type { ActionRateLimit, AnyAction } from './action';
+import { actionName, defOf, invoke } from './invoke';
+import {
+  derivePath,
+  inputSchemaName,
+  outputSchemaName,
+  PROBLEM_SCHEMA_NAME,
+  schemaRef,
+  toOperationId,
+  toToolName,
+} from './naming';
+import { policyCapability } from './policy-gate';
+import { tagKeys } from './tags';
+
+/** Matches `HttpConfig.buildIdHeader`; the pipeline reads it into `ctx.buildId`. */
+export const BUILD_ID_HEADER = 'x-ultimate-build';
+export const IDEMPOTENCY_HEADER = 'idempotency-key';
+export const REPLAYED_HEADER = 'x-ultimate-replayed';
+
+/**
+ * `publishPost` -> `POST /api/posts/publish`. Derivation: the first camelCase word
+ * is the verb, the rest is the resource with its last word pluralized and
+ * kebab-cased (`updateUserProfile` -> `/api/user-profiles/update`). See `naming.ts`.
+ */
+export function toRoute(target: AnyAction): Route {
+  const name = actionName(target);
+  const { path, resource } = derivePath(name);
+  const def = defOf(target);
+
+  const handler = async (req: UltimateRequest): Promise<Response> => {
+    try {
+      // The pipeline already parsed and size-capped the body; parsing it again here
+      // would be a second, differently-behaved parser for the same bytes.
+      const raw = await req.bodyRaw();
+      const key = def.idempotent === true ? req.header(IDEMPOTENCY_HEADER) : null;
+      let replayed = false;
+      const result = await invoke(target, raw, {
+        surface: 'http',
+        idempotencyKey: key,
+        onReplay: () => {
+          replayed = true;
+        },
+      });
+      const response = json(result);
+      if (key !== null) response.headers.set(REPLAYED_HEADER, replayed ? '1' : '0');
+      return response;
+    } catch (error) {
+      // Framework errors carry their own code, status and fix line; anything else is
+      // a bug and belongs to the server's error boundary, not to this route.
+      if (isUltimateError(error)) return problem(error);
+      throw error;
+    }
+  };
+
+  const meta: RouteMeta = {
+    name,
+    // `allow(...)` is the only way an action is public, and saying so explicitly is
+    // what keeps "forgot the policy" from ever looking like "meant to be public".
+    auth: def.policy.kind === 'allow' ? 'public' : 'required',
+    policy: policyCapability(def.policy),
+    // Named so the pipeline's authz stage stands down: `invoke` is this route's one
+    // evaluation, and it is the only one that has run `row` by the time it decides. A
+    // stage deciding first would decide from `row: null` — a denial for the row's own
+    // author, from an authz system that never saw the row.
+    enforcedBy: 'handler',
+    input: def.input,
+    cache: { mode: 'no-store', tags: tagKeys(def.cache?.invalidates ?? []) },
+    tags: [resource],
+    ...(def.rateLimit === undefined ? {} : { rateLimit: name }),
+    ...(def.mcp?.description === undefined ? {} : { description: def.mcp.description }),
+  };
+
+  return { method: 'POST', path, handler, meta };
+}
+
+export interface OpenApiOperation {
+  readonly operationId: string;
+  readonly tags: readonly string[];
+  readonly summary: string;
+  readonly parameters: readonly Record<string, unknown>[];
+  readonly requestBody: Record<string, unknown>;
+  readonly responses: Record<string, unknown>;
+  readonly 'x-ultimate': Record<string, unknown>;
+}
+
+/** The operation object for this action. `openapi.ts` assembles them into a document. */
+export function toOpenApiOperation(target: AnyAction): OpenApiOperation {
+  const name = actionName(target);
+  const def = defOf(target);
+  const path = derivePath(name);
+  const idempotent = def.idempotent === true;
+  return {
+    operationId: toOperationId(name),
+    tags: [path.resource],
+    summary: def.mcp?.description ?? name,
+    parameters: idempotent ? [IDEMPOTENCY_PARAMETER] : [],
+    requestBody: {
+      required: true,
+      content: { 'application/json': { schema: { $ref: schemaRef(inputSchemaName(name)) } } },
+    },
+    responses: {
+      '200': {
+        description: 'ok',
+        content: { 'application/json': { schema: { $ref: schemaRef(outputSchemaName(name)) } } },
+      },
+      '400': problemResponse('X_INPUT_INVALID'),
+      '403': problemResponse('policy denied'),
+      ...(idempotent ? { '409': problemResponse('X_IDEMPOTENCY_CONFLICT') } : {}),
+    },
+    'x-ultimate': {
+      capability: policyCapability(def.policy),
+      idempotent,
+      invalidates: tagKeys(def.cache?.invalidates ?? []),
+      mcpTool: def.mcp?.expose === false ? null : toToolName(name),
+      rateLimit: rateLimitMeta(def.rateLimit),
+    },
+  };
+}
+
+function rateLimitMeta(limit: ActionRateLimit | undefined): Record<string, number> | null {
+  return limit === undefined ? null : { limit: limit.limit, windowMs: limit.windowMs };
+}
+
+const IDEMPOTENCY_PARAMETER: Record<string, unknown> = {
+  name: 'Idempotency-Key',
+  in: 'header',
+  required: false,
+  schema: { type: 'string', maxLength: 255 },
+  description: 'Replays the first response for a repeated key.',
+};
+
+function problemResponse(description: string): Record<string, unknown> {
+  return {
+    description,
+    content: {
+      'application/problem+json': { schema: { $ref: schemaRef(PROBLEM_SCHEMA_NAME) } },
+    },
+  };
+}

package/src/idempotency.ts

@@ -0,0 +1,122 @@
+/**
+ * Idempotency for actions marked `idempotent`. A retried key replays the first
+ * response; a concurrent duplicate is refused rather than run twice, because a
+ * double charge is worse than a 409.
+ */
+import { uuid } from '@ultimat3/core';
+import { IdempotencyConflictError } from './errors';
+import { fingerprint } from './stable';
+
+export interface IdempotencyRecord {
+  readonly id: string;
+  readonly key: string;
+  /** Fingerprint of the parsed input — a reused key with a new payload is a bug. */
+  readonly requestHash: string;
+  readonly status: 'in-flight' | 'settled';
+  readonly value: unknown;
+  readonly createdAt: number;
+}
+
+export interface IdempotencyReservation {
+  readonly record: IdempotencyRecord;
+  /** True only for the caller that won the race and must therefore run the handler. */
+  readonly created: boolean;
+}
+
+export interface IdempotencyStore {
+  /** Atomically create-or-fetch the record for `key`. The atomicity is the point. */
+  reserve(key: string, requestHash: string): Promise<IdempotencyReservation>;
+  settle(key: string, value: unknown): Promise<void>;
+  /** Drop a reservation whose handler threw, so a retry can run. */
+  release(key: string): Promise<void>;
+  get(key: string): Promise<IdempotencyRecord | undefined>;
+}
+
+/**
+ * Default store: process memory. Correct for one web process and for tests;
+ * production swaps in a Postgres-backed store behind the same interface (a
+ * single `insert ... on conflict do nothing returning` gives the same atomicity).
+ */
+export class MemoryIdempotencyStore implements IdempotencyStore {
+  readonly #records = new Map<string, IdempotencyRecord>();
+
+  async reserve(key: string, requestHash: string): Promise<IdempotencyReservation> {
+    const existing = this.#records.get(key);
+    if (existing !== undefined) return { record: existing, created: false };
+    const record: IdempotencyRecord = {
+      id: uuid(),
+      key,
+      requestHash,
+      status: 'in-flight',
+      value: undefined,
+      createdAt: Date.now(),
+    };
+    this.#records.set(key, record);
+    return { record, created: true };
+  }
+
+  async settle(key: string, value: unknown): Promise<void> {
+    const existing = this.#records.get(key);
+    if (existing === undefined) return;
+    this.#records.set(key, { ...existing, status: 'settled', value });
+  }
+
+  async release(key: string): Promise<void> {
+    this.#records.delete(key);
+  }
+
+  async get(key: string): Promise<IdempotencyRecord | undefined> {
+    return this.#records.get(key);
+  }
+}
+
+let defaultStore: IdempotencyStore = new MemoryIdempotencyStore();
+
+export function setIdempotencyStore(store: IdempotencyStore): void {
+  defaultStore = store;
+}
+
+export function getIdempotencyStore(): IdempotencyStore {
+  return defaultStore;
+}
+
+/** Keys are namespaced per action: the same key under two actions is two keys. */
+export function idempotencyKeyFor(actionName: string, key: string): string {
+  return `${actionName}:${key}`;
+}
+
+export interface IdempotentOutcome<T> {
+  readonly value: T;
+  readonly replayed: boolean;
+}
+
+/**
+ * Replay-or-run. Four outcomes: fresh run, replay of a settled record,
+ * X_IDEMPOTENCY_CONFLICT for a payload mismatch, X_IDEMPOTENCY_CONFLICT for a
+ * duplicate that is still in flight.
+ */
+export async function withIdempotency<T>(
+  store: IdempotencyStore,
+  key: string,
+  input: unknown,
+  run: () => Promise<T>,
+): Promise<IdempotentOutcome<T>> {
+  const requestHash = fingerprint(input);
+  const { record, created } = await store.reserve(key, requestHash);
+  if (record.requestHash !== requestHash) {
+    throw new IdempotencyConflictError(key, 'payload-mismatch');
+  }
+  if (!created) {
+    if (record.status === 'in-flight') throw new IdempotencyConflictError(key, 'in-flight');
+    // The stored value is the previous return of this very handler.
+    return { value: record.value as T, replayed: true };
+  }
+  try {
+    const value = await run();
+    await store.settle(key, value);
+    return { value, replayed: false };
+  } catch (error) {
+    await store.release(key);
+    throw error;
+  }
+}

package/src/index.ts

@@ -0,0 +1,110 @@
+/**
+ * Public API of @ultimat3/action: the primitive plus its six projections.
+ *
+ * `handle` is deliberately absent. An action's declaration lives in `invoke.ts`'s
+ * private store, and `invoke` is the only thing that reads it — so no adapter can
+ * parse, authorize or run on its own. Two authz systems is how every Meteor-like
+ * framework died; there is exactly one here, structurally.
+ */
+
+/** 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';
+export type {
+  Action,
+  ActionCache,
+  ActionDef,
+  ActionDescriptor,
+  ActionFacade,
+  ActionHandlerArgs,
+  ActionMcp,
+  ActionRateLimit,
+  ActionRowArgs,
+  AnyAction,
+  InvokeOptions,
+  McpDescriptorMeta,
+} from './action';
+export { action, describeAction, isAction } from './action';
+export type {
+  ActionLike,
+  ActionMap,
+  CallOptions,
+  Client,
+  ClientMethod,
+  ClientOptions,
+  FetchLike,
+} from './client';
+export { rpc } from './client';
+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';
+export {
+  ActionDeniedError,
+  ActionDuplicateError,
+  ActionForeignError,
+  ActionPolicyMissingError,
+  ActionUnregisteredError,
+  ContractDriftError,
+  IdempotencyConflictError,
+  InputInvalidError,
+  OutputInvalidError,
+  RpcFailedError,
+} from './errors';
+export type { OpenApiOperation } from './http';
+export {
+  BUILD_ID_HEADER,
+  IDEMPOTENCY_HEADER,
+  REPLAYED_HEADER,
+  toOpenApiOperation,
+  toRoute,
+} from './http';
+export type {
+  IdempotencyRecord,
+  IdempotencyReservation,
+  IdempotencyStore,
+  IdempotentOutcome,
+} from './idempotency';
+export {
+  getIdempotencyStore,
+  idempotencyKeyFor,
+  MemoryIdempotencyStore,
+  setIdempotencyStore,
+  withIdempotency,
+} from './idempotency';
+/** The one execution path. `defOf` stays unexported — that is the enforcement. */
+export { actionName, invoke } from './invoke';
+export type { ActionJobHandle } from './job-handle';
+export { toJobHandle } from './job-handle';
+export type { JsonSchemaObject } from './json-schema';
+export { jsonSchemaOf, mcpSchemaOf } from './json-schema';
+export type { McpInvokeOptions, McpToolDescriptor } from './mcp-tool';
+export { isExposed, toMcpTool, toMcpTools } from './mcp-tool';
+export type {
+  Conflict,
+  CustomConflict,
+  LocalRow,
+  LocalTable,
+  LocalTableName,
+  LocalTables,
+  LocalTx,
+  Mutator,
+  MutatorDef,
+  MutatorDescriptor,
+} from './mutator';
+export { custom, isMutator, mutator, resolveConflict, strategyOf } from './mutator';
+export type { ActionPath } from './naming';
+export { derivePath, inputSchemaName, outputSchemaName, pluralize, toToolName } 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';
+export {
+  describeActions,
+  getAction,
+  listActions,
+  registerAction,
+  registerActions,
+  resetRegistry,
+} from './registry';

package/src/invoke.ts

@@ -0,0 +1,120 @@
+/**
+ * The one invocation core: parse input, evaluate policy, run the handler, parse
+ * 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.
+ */
+
+import { invalidateTags } from '@ultimat3/cache';
+import type { Ctx } from '@ultimat3/core';
+import {
+  anonymousActor,
+  createContext,
+  runWithContext,
+  tryUseContext,
+  useContext,
+  withChildContext,
+  withSpan,
+} from '@ultimat3/core';
+import type { AnyAction, AnyActionDef, InvokeOptions } from './action';
+import { ActionForeignError, ActionUnregisteredError } from './errors';
+import { getIdempotencyStore, idempotencyKeyFor, withIdempotency } from './idempotency';
+import { actorOf, guard } from './policy-gate';
+import { validateInput, validateOutput } from './validate';
+
+/**
+ * Private on purpose. `@ultimat3/action` exports no way to read this back, which
+ * is what makes "the only way to reach `handle` is `invoke`" structural rather
+ * than a rule someone has to remember.
+ */
+const DECLARATIONS = new WeakMap<object, AnyActionDef>();
+
+/** Called once per built action, by `action()` and by every rename it produces. */
+export function stashDef(target: object, def: AnyActionDef): void {
+  DECLARATIONS.set(target, def);
+}
+
+/** True only for objects this package built — `isAction` leans on it. */
+export function hasDef(target: object): boolean {
+  return DECLARATIONS.has(target);
+}
+
+/** Internal read of the declaration. Never re-exported from `src/index.ts`. */
+export function defOf(target: AnyAction): AnyActionDef {
+  const def = DECLARATIONS.get(target);
+  if (def === undefined) throw new ActionForeignError(target.name);
+  return def;
+}
+
+/** Projections need a stable name; an unregistered action has none yet. */
+export function actionName(target: AnyAction): string {
+  if (target.name.length === 0) throw new ActionUnregisteredError();
+  return target.name;
+}
+
+/**
+ * Run an action. Surfaces differ only in the `surface` they pass, which selects
+ * how a denial is rendered — never whether authz runs, never how input is parsed,
+ * never whether the handler's return value is checked against `output`.
+ */
+export function invoke(
+  target: AnyAction,
+  raw: unknown,
+  options: InvokeOptions = {},
+): Promise<unknown> {
+  if (options.actor === undefined) return core(target, raw, options.ctx ?? useContext(), options);
+
+  // Impersonation keeps the surrounding context whole — services, clock, locale,
+  // trace — and swaps only the actor. Policy models "nobody" as null; core models
+  // it as the anonymous actor.
+  const patch = { actor: options.actor ?? anonymousActor() };
+  const run = (): Promise<unknown> => core(target, raw, useContext(), options);
+  const base = options.ctx ?? tryUseContext();
+  return base === undefined
+    ? runWithContext(createContext(patch), run)
+    : runWithContext(base, () => withChildContext(patch, run));
+}
+
+async function core(
+  target: AnyAction,
+  raw: unknown,
+  ctx: Ctx,
+  options: InvokeOptions,
+): Promise<unknown> {
+  const def = defOf(target);
+  const name = actionName(target);
+  const input = await validateInput(def.input, raw, name);
+  // 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
+  // action with no loader hands the rule `null` — unchanged, and never a silent allow,
+  // because a rule that reads `row` has to decide what `null` means.
+  const row = def.row === undefined ? null : ((await def.row({ input, ctx })) ?? null);
+  guard(
+    def.policy,
+    { actor: actorOf(ctx), input, row, ctx, action: name },
+    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.
+  const run = async (): Promise<unknown> => {
+    const produced = await withSpan(`action.${name}`, () =>
+      Promise.resolve(def.handle({ input, ctx })),
+    );
+    return validateOutput(def.output, produced, name);
+  };
+
+  const key = def.idempotent === true ? (options.idempotencyKey ?? null) : null;
+  let value: unknown;
+  if (key === null) {
+    value = await run();
+  } else {
+    const store = options.store ?? getIdempotencyStore();
+    const outcome = await withIdempotency(store, idempotencyKeyFor(name, key), input, run);
+    if (outcome.replayed) options.onReplay?.();
+    value = outcome.value;
+  }
+  if (def.cache !== undefined) await invalidateTags(def.cache.invalidates);
+  return value;
+}

package/src/job-handle.ts

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+import type { Ctx } from '@ultimat3/core';
+import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import type { Action } from './action';
+import { actionName, invoke } from './invoke';
+import { fingerprint } from './stable';
+
+export interface ActionJobHandle<
+  TInput extends StandardSchemaV1 = StandardSchemaV1,
+  TOutput extends StandardSchemaV1 = StandardSchemaV1,
+> {
+  readonly kind: 'action-job';
+  /** Namespaced so an action-backed job never collides with a hand-written job. */
+  readonly name: string;
+  readonly input: TInput;
+  /** Required by the job type: derived from the payload, stable across retries. */
+  idempotencyKey(input: InferInput<TInput>): string;
+  invoke(input: InferInput<TInput>, ctx: Ctx): Promise<InferOutput<TOutput>>;
+}
+
+export function toJobHandle<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
+  target: Action<TInput, TOutput>,
+): ActionJobHandle<TInput, TOutput> {
+  const name = actionName(target);
+  return {
+    kind: 'action-job',
+    name: `action:${name}`,
+    input: target.input,
+    idempotencyKey: (input) => `action:${name}:${fingerprint(input)}`,
+    // Schema-erased at the seam; the output type is this action's by construction.
+    invoke: (input, ctx) =>
+      invoke(target, input, { surface: 'job', ctx }) as Promise<InferOutput<TOutput>>,
+  };
+}

package/src/json-schema.ts

@@ -0,0 +1,39 @@
+/**
+ * Standard Schema -> JSON Schema, normalized to a plain record. OpenAPI, MCP
+ * descriptors and the manifest all need the same object, produced the same way.
+ */
+
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { 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.
+ */
+export function jsonSchemaOf(schema: StandardSchemaV1): JsonSchemaObject {
+  return normalize(() => 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));
+}
+
+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 };
+}
+
+/** Key-sorted copy — deterministic ordering for the committed contract file. */
+export function sortSchema(schema: JsonSchemaObject): JsonSchemaObject {
+  const parsed: unknown = JSON.parse(stableStringify(schema));
+  return isJsonObject(parsed) ? parsed : {};
+}

package/src/mcp-tool.ts

@@ -0,0 +1,73 @@
+/**
+ * Projection 4: an action as an MCP tool. Its `invoke` is the package's `invoke`
+ * — the same core the HTTP route calls — so the tool cannot drift from the
+ * endpoint and cannot acquire a second authz path. One authz system, never two.
+ */
+import type { Ctx } 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 {
+  readonly name: string;
+  /** The action's `mcp.description`, or its name when the author gave none. */
+  readonly description: string;
+  readonly action: string;
+  /**
+   * The action's own policy object, not a copy — `tool().policy === action.policy`
+   * is what makes "an MCP call cannot reach a different authz path" checkable.
+   */
+  readonly policy: ActionPolicy;
+  readonly inputSchema: JsonSchemaObject;
+  readonly outputSchema: JsonSchemaObject;
+  invoke(input: unknown, options?: McpInvokeOptions): Promise<unknown>;
+}
+
+export interface McpInvokeOptions {
+  readonly ctx?: Ctx;
+  readonly idempotencyKey?: string | null;
+}
+
+export function toMcpTool(target: AnyAction): McpToolDescriptor {
+  const name = actionName(target);
+  const def = defOf(target);
+  return {
+    name: toToolName(name),
+    description: def.mcp?.description ?? name,
+    action: name,
+    policy: def.policy,
+    inputSchema: sortSchema(mcpSchemaOf(def.input)),
+    outputSchema: sortSchema(mcpSchemaOf(def.output)),
+    invoke: (input, options = {}) =>
+      invoke(target, input, {
+        surface: 'mcp',
+        ...(options.ctx === undefined ? {} : { ctx: options.ctx }),
+        idempotencyKey: options.idempotencyKey ?? null,
+      }),
+  };
+}
+
+/**
+ * Opt-in, exactly like a query's: only a literal `mcp: { expose: true }` exposes an action.
+ *
+ * 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.
+ */
+export function isExposed(target: AnyAction): boolean {
+  return target.mcp?.expose === true;
+}
+
+/** Deterministic order — the tool list is part of the agent-visible contract. */
+export function toMcpTools(
+  actions: readonly AnyAction[] = listActions(),
+): readonly McpToolDescriptor[] {
+  return actions
+    .filter(isExposed)
+    .map(toMcpTool)
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}