@ultimat3/action 29.3.2 → 30.0.0

package/src/openapi.ts

@@ -7,10 +7,11 @@
  * registry, and nothing here reads the clock, the environment or a random source.
  */
 
+import { ERROR_RETRY_KINDS, templateParams, toOpenApiPath } from '@ultimat3/core';
 import type { AnyAction } from './action';
 import { operationTagOf, toOpenApiOperation } from './http';
-import { servedActionRoute } from './http-path';
-import { actionName } from './invoke';
+import { methodOfHttp, servedActionRoute } from './http-path';
+import { actionName, defOf } from './invoke';
 import { type JsonSchemaObject, jsonSchemaOf, sortSchema } from './json-schema';
 import { inputSchemaName, outputSchemaName, PROBLEM_SCHEMA_NAME } from './naming';
 import { listActions } from './registry';
@@ -52,8 +53,16 @@ export function buildOpenApi(options: BuildOpenApiOptions = {}): OpenApiDocument
   for (const target of actions) {
     const name = actionName(target);
     const { path } = servedActionRoute(name);
-    paths[path] = { post: toOpenApiOperation(target) };
-    schemas[inputSchemaName(name)] = sortSchema(jsonSchemaOf(target.input));
+    const documented = toOpenApiPath(path);
+    // Merged, never replaced: REST's two verbs on one URL are two operations of one path item.
+    const item = Object.hasOwn(paths, documented) ? (paths[documented] as object) : {};
+    const verb = methodOfHttp(defOf(target).http).toLowerCase();
+    paths[documented] = { ...item, [verb]: toOpenApiOperation(target) };
+    // The component IS the request body, so a `:param`'s key leaves it: the URL carries it.
+    schemas[inputSchemaName(name)] = withoutKeys(
+      sortSchema(jsonSchemaOf(target.input)),
+      templateParams(path),
+    );
     schemas[outputSchemaName(name)] = sortSchema(jsonSchemaOf(target.output));
     tags.add(operationTagOf(target));
   }
@@ -72,6 +81,27 @@ export function serializeOpenApi(document: OpenApiDocument): string {
   return `${stableStringify(document, 2)}\n`;
 }
 
+/** `schema` minus `keys` from `properties` and `required`; the same object when `keys` is empty. */
+function withoutKeys(schema: JsonSchemaObject, keys: readonly string[]): JsonSchemaObject {
+  if (keys.length === 0) return schema;
+  const properties = schema['properties'];
+  const required = schema['required'];
+  const kept =
+    typeof properties === 'object' && properties !== null
+      ? Object.fromEntries(Object.entries(properties).filter(([key]) => !keys.includes(key)))
+      : properties;
+  const { required: _dropped, ...rest } = schema;
+  const still = Array.isArray(required)
+    ? required.filter((key: unknown) => typeof key !== 'string' || !keys.includes(key))
+    : [];
+  return {
+    ...rest,
+    ...(kept === undefined ? {} : { properties: kept }),
+    // Omitted when nothing is left, as `jsonSchemaOf` omits it for an all-optional object.
+    ...(still.length === 0 ? {} : { required: still }),
+  };
+}
+
 function compareByName(a: AnyAction, b: AnyAction): number {
   return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
 }
@@ -95,6 +125,8 @@ const PROBLEM_SCHEMA: JsonSchemaObject = {
     cause: { type: 'string' },
     fix: { type: 'string' },
     docs: { type: 'string', format: 'uri' },
+    // The class a client maps to an exception. On every document, hidden 5xx included.
+    retry: { type: 'string', enum: [...ERROR_RETRY_KINDS] },
     requestId: { type: 'string' },
     // Absent when the failure produced none — never `[]`, which would claim "validated clean".
     issues: {
@@ -107,6 +139,9 @@ const PROBLEM_SCHEMA: JsonSchemaObject = {
           expected: { type: 'string' },
           received: { type: 'string' },
           message: { type: 'string' },
+          // `SCHEMA_RULES` is the vocabulary; typed `string` because it grows (add, never rename).
+          rule: { type: 'string' },
+          params: { type: 'object' },
         },
       },
     },

package/src/rate-limit-gate.ts

@@ -49,7 +49,12 @@ export function withJobFrame<T>(fn: () => T): T {
  * `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';
+export const UNATTRIBUTED_JOB = 'job:unattributed';
+
+/** Whether this call runs inside a job run, nested or not — the one answer both gates key on. */
+export function inJobFrame(): boolean {
+  return callerFrame.get()?.job === true;
+}
 
 /**
  * Namespaced, never the bare action name: the HTTP pipeline still spends its `default` bucket
@@ -85,7 +90,7 @@ export async function spendActionLimit(
   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 inJob = options.surface === 'job' || inJobFrame();
   const spends = rateLimitSpends(
     {
       actorId: isAnonymous(ctx.actor) ? null : ctx.actor.id,
@@ -101,10 +106,16 @@ export async function spendActionLimit(
     // one included); counting it here too would charge an HTTP call against the tenant twice.
     { route: name, tenant: null },
   );
+  // Resolved once per call, BEFORE any bucket is touched, and through `toBucket`'s own screen: a
+  // resolver answering `NaN`, `0` or `Infinity` is `X_RATE_LIMIT_INVALID`, never allow-all.
+  const bucket = toBucket(name, {
+    limit: await resolvedRateLimit(limit, ctx),
+    windowMs: limit.windowMs,
+  });
   for (const spend of spends) {
     const decision = await installedRateLimitStore().take(
       spend.key,
-      toBucket(name, limit),
+      bucket,
       1,
       ctx.now().getTime(),
     );
@@ -112,3 +123,32 @@ export async function spendActionLimit(
     if (!decision.allowed) throw rateLimited(spend.key, decision.retryAfterSeconds);
   }
 }
+
+/**
+ * The number a call is held to: the declared one, or what the resolver answers from `ctx` — the
+ * tenant's plan, read by the app. A non-number becomes `NaN`, so `toBucket` refuses it by name.
+ */
+async function resolvedRateLimit(limit: ActionRateLimit, ctx: Ctx): Promise<number> {
+  const resolved: unknown =
+    typeof limit.limit === 'function' ? await limit.limit({ ctx }) : limit.limit;
+  return typeof resolved === 'number' ? resolved : Number.NaN;
+}
+
+/**
+ * At mount, never on the first request: a fixed pair is checked whole; a per-call limit has only
+ * its window to check until a caller resolves it, so the window is checked against one request.
+ */
+export function assertActionRateLimit(name: string, limit: ActionRateLimit): void {
+  toBucket(name, {
+    limit: typeof limit.limit === 'function' ? 1 : limit.limit,
+    windowMs: limit.windowMs,
+  });
+}
+
+/** The declaration as data: the fixed pair, or `null` for a limit resolved per call. */
+export function fixedRateLimit(
+  limit: ActionRateLimit | undefined,
+): { readonly limit: number; readonly windowMs: number } | null {
+  if (limit === undefined || typeof limit.limit === 'function') return null;
+  return { limit: limit.limit, windowMs: limit.windowMs };
+}

package/src/registry.ts

@@ -5,13 +5,15 @@
  */
 
 import type { ActionPathStyle } from '@ultimat3/core';
-import { SchemaUnsupportedError, toWireSchema } from '@ultimat3/schema';
+import { assertNoSensitiveOutput, SchemaUnsupportedError, toWireSchema } from '@ultimat3/schema';
 import type { ActionDescriptor, AnyAction } from './action';
 import { isAction, nameAction } from './action';
 import { resetApiDeclaration } from './api-declaration';
 import { ActionDuplicateError, ActionPathDuplicateError, ActionPolicyMissingError } from './errors';
 import {
-  assertPinnedPath,
+  assertPinnedHttp,
+  filledRoute,
+  methodOfHttp,
   resetActionPathStyle,
   resolveActionRoute,
   routeFor,
@@ -22,11 +24,14 @@ import { defOf } from './invoke';
 import { jsonSchemaOf } from './json-schema';
 import type { ActionPath } from './naming';
 import { seatedActions } from './registry-store';
+import { clearToolGates } from './tool-gate';
 
 const registry = seatedActions;
 
 /**
- * Derived route -> the action name that owns it. A second index because the name is not the
+ * `METHOD path` -> the action name that owns it. Keyed on the method too, so REST's two verbs on
+ * one URL (`PUT /orders/:id`, `DELETE /orders/:id`) are two routes, as the router seats them. A
+ * second index because the name is not the
  * path: `pluralize` leaves a trailing `s` alone by design, so `archiveOrder` and `archiveOrders`
  * are two names and one route. Nothing downstream can refuse that — the router seats whichever
  * came last and the shadowed action stays in the OpenAPI document and the MCP tool list.
@@ -57,28 +62,43 @@ export function registerAction<A extends AnyAction>(name: string, target: A): A
     throw new ActionPolicyMissingError(name);
   }
   assertProjectable(name, target);
-  const pin = defOf(target).http?.path;
-  if (pin !== undefined) assertPinnedPath(name, pin);
-  const { path } = routeFor(name, pin);
-  const owner = paths.get(path);
+  // An output is sent back, which `.sensitive()` (`writeOnly`) forbids: refused at boot, once.
+  const output = defOf(target).output;
+  if (output !== undefined) assertNoSensitiveOutput(`action "${name}" output`, output);
+  const http = defOf(target).http;
+  if (http !== undefined) assertPinnedHttp(name, http, defOf(target).input);
+  const slot = slotOf(name, target);
+  const owner = paths.get(slot);
   if (owner !== undefined && owner !== name) {
-    throw new ActionPathDuplicateError({ name, existing: owner, path });
+    throw new ActionPathDuplicateError({ name, existing: owner, path: slot });
   }
   const named = nameAction(target, name);
   registry.set(name, named);
-  paths.set(path, name);
+  paths.set(slot, name);
   return named;
 }
 
+/**
+ * The route table's key, and so the duplicate index's: the path alone for `POST` (every unpinned
+ * action's verb, and the spelling `X_ACTION_PATH_DUPLICATE` has always named), `METHOD path` else.
+ */
+const slotOf = (name: string, target: AnyAction): string => {
+  const http = defOf(target).http;
+  const { path } = routeFor(name, http?.path);
+  const method = methodOfHttp(http);
+  return method === 'POST' ? path : `${method} ${path}`;
+};
+
 /**
  * Where `target` is served — its pin, else the app's style over its name. A NAME is resolved
  * through the registry, so a pin declared on the action is honoured for a caller that only has the
- * name (a deprecation's `replacedBy`, a page minting an island's endpoint).
+ * name (a deprecation's `replacedBy`, a page minting an island's endpoint). A `:param` pin needs
+ * `params` (`actionHttpPath('refundOrder', { id })`), each value encoded as one segment.
  */
-export function actionHttpPath(target: AnyAction | string): ActionPath {
+export function actionHttpPath(target: AnyAction | string, params?: unknown): ActionPath {
   // By NAME is how a page mints a form target, so it answers through the recorded path.
-  if (typeof target === 'string') return resolveActionRoute(target);
-  return routeFor(target.name, defOf(target).http?.path);
+  if (typeof target === 'string') return resolveActionRoute(target, params);
+  return filledRoute(target.name, routeFor(target.name, defOf(target).http?.path), params);
 }
 
 /**
@@ -90,12 +110,12 @@ export function configureActionPathStyle(style: ActionPathStyle): void {
   setActionPathStyle(style);
   paths.clear();
   for (const [name, target] of [...registry.entries()].sort(byName)) {
-    const { path } = routeFor(name, defOf(target).http?.path);
-    const owner = paths.get(path);
+    const slot = slotOf(name, target);
+    const owner = paths.get(slot);
     if (owner !== undefined && owner !== name) {
-      throw new ActionPathDuplicateError({ name, existing: owner, path });
+      throw new ActionPathDuplicateError({ name, existing: owner, path: slot });
     }
-    paths.set(path, name);
+    paths.set(slot, name);
   }
 }
 
@@ -103,7 +123,7 @@ export function configureActionPathStyle(style: ActionPathStyle): void {
  * Both schemas must reach JSON Schema, and this is where that is decided — boot, beside the policy
  * check, never the first `tools/list`. `jsonSchemaOf` used to swallow the refusal into
  * `additionalProperties: true`, so an action whose `input:` the provider cannot describe registered
- * cleanly and then published "any object accepted" on three surfaces while `validateInput` rejected
+ * cleanly and then published "any object accepted" on three surfaces while `parseActionInput` rejected
  * every payload. The shipped `X_SCHEMA_UNSUPPORTED` is re-raised rather than re-coded — the failure
  * is the provider's, and only the cause needs to say which action and which field.
  */
@@ -159,6 +179,7 @@ export function resetActions(): void {
   paths.clear();
   resetActionPathStyle();
   resetApiDeclaration();
+  clearToolGates();
 }
 
 function byName(a: readonly [string, AnyAction], b: readonly [string, AnyAction]): number {

package/src/tool-gate.ts

@@ -0,0 +1,97 @@
+/**
+ * The gates a named tool passes on its way to `invoke`, keyed by name because a tool is named across
+ * both surfaces. Tier 3, the lowest `@ultimat3/mcp` (which registers one) and `@ultimat3/ai` (whose
+ * adapter reads one) can both reach, since those two may not import each other.
+ */
+
+import type { Actor } from '@ultimat3/core';
+import {
+  actorOf,
+  ctxOf,
+  hasContext,
+  runWithContext,
+  useContext,
+  withChildContext,
+} from '@ultimat3/core';
+import type { WireJsonSchema } from '@ultimat3/schema';
+import type { AnyAction } from './action';
+import { guardActionBeforeInput } from './policy-gate';
+
+/** One tool call, as a gate reads it: raw arguments, and the schema that tool publishes for them. */
+export interface ToolGateCall {
+  readonly tool: string;
+  readonly args: unknown;
+  readonly inputSchema: WireJsonSchema | undefined;
+  readonly actor: Actor;
+}
+
+/** Answers by running `run`, or by throwing the refusal the caller reads instead. */
+export type ToolGate = (call: ToolGateCall, run: () => Promise<unknown>) => Promise<unknown>;
+
+const gates = new Map<string, ToolGate>();
+
+/**
+ * First registered keeps the name; a later one for it is a no-op, never an error. Two
+ * `mcpConfirmations` on one tool are legal, since each MCP server holds its own, and a duplicate
+ * check by identity would trip on the fresh closure a re-evaluated module hands in.
+ */
+export function registerToolGate(names: readonly string[], gate: ToolGate): void {
+  for (const name of names) if (!gates.has(name)) gates.set(name, gate);
+}
+
+/** Read at CALL time: the module declaring a gate may evaluate after the agent listing the tool. */
+export function toolGateFor(name: string): ToolGate | undefined {
+  return gates.get(name);
+}
+
+/** Sorted, so what two processes registered compares as data (`X_ROLE_LOAD_INCOMPLETE`). */
+export function gatedToolNames(): readonly string[] {
+  return [...gates.keys()].sort();
+}
+
+const noted = new Set<string>();
+
+/**
+ * Tools no registry holds: a hand-written MCP tool, an agent's in-process one. Noted by what declares
+ * them, so the `manifest` step can tell a gate on one of those from a gate on a typo, which holds
+ * nothing and lets the real tool run (`X_MCP_CONFIRMATION_TOOL_UNKNOWN`).
+ */
+export function noteToolNames(names: readonly string[]): void {
+  for (const name of names) noted.add(name);
+}
+
+export function knownToolNames(): readonly string[] {
+  return [...noted].sort();
+}
+
+/**
+ * `resetActions`' half of a reload, and only that. `resetActions` is on the barrel because 48 files
+ * outside this package reach it there and no test-only entry exists, so it does empty these tables:
+ * a test resetting after each case must re-declare any module-level gate, or later cases run ungated.
+ */
+export function clearToolGates(): void {
+  gates.clear();
+  noted.clear();
+}
+
+/**
+ * Run `fn` with `actor` as the ambient identity, whether or not a request is in flight.
+ * `withChildContext` alone calls `useContext()`, which throws `X_NO_CONTEXT` with nothing in flight:
+ * over `x mcp serve` (stdio) every tool call answered that instead of running. With a request, the
+ * child keeps the policy subject and what the handler reads off `ctx.actor` one identity.
+ */
+export function asCallerContext<T>(actor: Actor, fn: () => T): T {
+  return hasContext() ? withChildContext({ actor }, fn) : runWithContext(ctxOf({ actor }), fn);
+}
+
+/**
+ * The opening gate of `invoke`, asked earlier: throws for a caller the action's policy refuses before
+ * reading the input. Both tool surfaces ask it, so such a caller opens no row for a person to look at.
+ */
+export function admitActionCaller(target: AnyAction, name: string): (actor: Actor) => void {
+  return (actor) =>
+    asCallerContext(actor, () => {
+      const ctx = useContext();
+      guardActionBeforeInput(target.policy, { actor: actorOf(ctx), ctx, action: name }, 'mcp');
+    });
+}

package/src/tx-scope.ts

@@ -2,11 +2,23 @@
  * 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).
+ * And a scope whose writes are never kept (`inRolledBackScope`, the contract step's exercise).
  */
 
 // 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';
+import { storeMode } from '@ultimat3/core';
+import {
+  completeTransaction,
+  currentTx,
+  dbClientInstalled,
+  liveTxConnection,
+  withTransaction,
+} from '@ultimat3/db';
+import { memoryJournal, memoryTransactor } from '@ultimat3/entity';
+
+/** The mark a keyed run puts on the open root: its COMMIT carries the settle, abort or no abort. */
+export const carrySettleOnCommit = (): void => completeTransaction();
 
 /** The half of a transaction a deferred effect needs. `@ultimat3/db`'s `DbTx` satisfies it. */
 export interface CommitScope {
@@ -19,10 +31,15 @@ export interface CommitScope {
  * 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.
+ * and a late change report never disagree about one write. With no SQL transaction, the open
+ * MEMORY transaction answers the same way (the row observer asks it too).
  */
 export function openCommitScope(): CommitScope | undefined {
-  return currentTx();
+  const sql = currentTx();
+  if (sql !== undefined) return sql;
+  const memory = memoryJournal();
+  const onCommit = memory?.onCommit?.bind(memory);
+  return onCommit === undefined ? undefined : { onCommit };
 }
 
 /** A transaction that is still OPEN: statements sent now are inside it. */
@@ -55,3 +72,54 @@ export function liveTransaction(): LiveTransaction | undefined {
     },
   };
 }
+
+/**
+ * Thrown inside the scope only to end it, and caught right outside: the one way a `withTransaction`
+ * body asks for ROLLBACK. Never an `UltimateError`, because nothing but `inRolledBackScope` ever
+ * sees it — a code would be a failure mode no caller can meet.
+ */
+const ROLLBACK: unique symbol = Symbol('ultimate.action.rollback');
+
+/** What `run` settled to inside the scope, carried past the rollback that ends it. */
+export type Settled<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: unknown };
+
+/** Whether a SQL transaction can hold the writes: one is open, or a client is installed. */
+const sqlScopeAvailable = (): boolean => liveTxConnection() !== undefined || dbClientInstalled();
+
+/**
+ * Whether `inRolledBackScope` undoes the writes: a SQL transaction can hold them, or the store is
+ * memory (`storeMode`, `test`), whose writes the memory transaction it always opens holds.
+ */
+export const rollbackAvailable = (): boolean =>
+  sqlScopeAvailable() || storeMode(Bun.env) === 'memory';
+
+/**
+ * `run` inside a transaction that ALWAYS rolls back — a memory transaction, always, so a memory
+ * store write is undone however the handler wrote it; and in it a SAVEPOINT when a SQL transaction
+ * is already open (a test's own scope), a root BEGIN when a test installed a client. The outbox
+ * stage and the post-commit bust ride the SQL transaction, so they drop with it. A write made
+ * outside both (a second client, `outsideTransaction`) is not undone.
+ */
+export async function inRolledBackScope<T>(run: () => Promise<T>): Promise<Settled<T>> {
+  let settled: Settled<T> | undefined;
+  const settleThenRollBack = async (): Promise<never> => {
+    try {
+      settled = { ok: true, value: await run() };
+    } catch (error) {
+      settled = { ok: false, error };
+    }
+    throw ROLLBACK;
+  };
+  try {
+    // One ROLLBACK ends both: thrown out of the SQL scope, it carries on through the memory one.
+    await memoryTransactor().run(() =>
+      sqlScopeAvailable() ? withTransaction(settleThenRollBack) : settleThenRollBack(),
+    );
+  } catch (error) {
+    if (error !== ROLLBACK) throw error;
+  }
+  // `settleThenRollBack` assigns before it throws, so a scope that ended on ROLLBACK assigned it.
+  return settled ?? { ok: false, error: ROLLBACK };
+}

package/src/validate.ts

@@ -18,7 +18,7 @@ import { InputInvalidError, OutputInvalidError } from './errors';
  * handed to an HTTP surface that returns it to the caller. Four members travel, and
  * `describeValue` is what keeps a value out of the fifth.
  */
-export async function validateInput<S extends StandardSchemaV1>(
+export async function parseActionInput<S extends StandardSchemaV1>(
   schema: S,
   raw: unknown,
   actionName: string,

package/src/wire-issues.ts

@@ -7,6 +7,7 @@
 
 import { stringField } from '@ultimat3/core';
 import type { ValidationIssue } from '@ultimat3/schema';
+import { issueRuleFacts } from '@ultimat3/schema';
 
 /**
  * A list this long is not a form's worth of rejections; it is a body meant to be expensive. The
@@ -35,12 +36,14 @@ export function issuesFromWire(value: unknown): readonly ValidationIssue[] | und
     if (path === undefined || message === undefined || message.length === 0) return undefined;
     // Built member by member, never spread: a foreign issue object may carry the rejected VALUE
     // (some libraries put it in `received`), and a whole-object copy would forward it to whoever
-    // renders the list. Four members travel; everything else stops here.
+    // renders the list. Four members travel, plus the `rule` a translator keys on and its scalar
+    // `params` (schema's one reader); everything else stops here.
     issues.push({
       path,
       expected: stringField(entry, 'expected') ?? '',
       received: stringField(entry, 'received') ?? '',
       message,
+      ...issueRuleFacts(entry),
     });
   }
   return issues;