@ultimat3/action 22.15.0 → 24.0.0

package/src/mutator.ts

@@ -18,6 +18,7 @@ import type {
 } from './action';
 import { action, isAction } from './action';
 import type { Deprecation } from './deprecation';
+import { MutatorNotIdempotentError } from './errors';
 import type { ActionHttp } from './http-path';
 import { assertConflictClock } from './mutator-clock';
 import type { ActionPolicy } from './policy-gate';
@@ -97,7 +98,14 @@ export interface MutatorDef<
   readonly deprecated?: Deprecation;
   /** Same key, same meaning as an action's: `http: { path }` pins the URL. */
   readonly http?: ActionHttp;
-  readonly idempotent?: boolean;
+  /**
+   * REQUIRED, and only `true`. A mutator's write is replayed under one `Idempotency-Key` —
+   * `useMutation`'s retry, the offline queue's drain after a dropped response — and the server
+   * reads that key only for an idempotent action. Declared rather than defaulted because the
+   * replay is answered from the idempotency store, and which store that is (`configureIdempotency`)
+   * is the app's decision to see. Omitted: a compile error, and `X_MUTATOR_NOT_IDEMPOTENT`.
+   */
+  readonly idempotent: true;
   /**
    * The row a row-level `policy` decides about — an action's `row`, and dropped on the way into
    * the action until 2026-09-23, so such a policy received `row === null` and denied every call.
@@ -158,6 +166,9 @@ export function mutator<
   TOutput extends StandardSchemaV1,
   TRow = unknown,
 >(def: MutatorDef<TInput, TOutput, TRow>): Mutator<TInput, TOutput> {
+  // First, and for a caller the compiler never saw: a replay that runs the server half twice is
+  // silent, so the declaration is refused where it is written rather than on the second POST.
+  if (def.idempotent !== true) throw new MutatorNotIdempotentError();
   const row = def.row;
   const actionDef: ActionDef<TInput, TOutput, TRow> = {
     input: def.input,
@@ -169,7 +180,7 @@ export function mutator<
     ...(def.deprecated === undefined ? {} : { deprecated: def.deprecated }),
     ...(def.http === undefined ? {} : { http: def.http }),
     ...(row === undefined ? {} : { row: (args: ActionRowArgs<TInput>) => row.call(def, args) }),
-    ...(def.idempotent === undefined ? {} : { idempotent: def.idempotent }),
+    idempotent: true,
     ...(def.audit === undefined ? {} : { audit: def.audit }),
     handle: ({ input, ctx }) => def.server(ctx, input),
   };

package/src/openapi.ts

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

package/src/path-style-miss.ts

@@ -0,0 +1,56 @@
+/**
+ * What the server says to a caller that derived an action's URL under the WRONG path style: a
+ * script or another service passing `rpc({ pathStyle })` by hand, where matching build ids prove
+ * nothing. Handed to `@ultimat3/http` as `hooks.explainMiss`, so it runs only when the router
+ * matched nothing — and answers `X_CONTRACT_DRIFT` naming the style served, in place of a
+ * `X_ROUTE_NOT_FOUND` that sends the caller looking for a route that exists.
+ */
+
+import type { ActionPathStyle } from '@ultimat3/core';
+import { ACTION_PATH_PREFIX, ACTION_PATH_STYLES, actionRoute } from '@ultimat3/core';
+import { ContractDriftError } from './errors';
+import { actionPathStyle, servedActionRoute } from './http-path';
+import { defOf } from './invoke';
+import { seatedActions } from './registry-store';
+
+/**
+ * The action `pathname` names under a style this app does not serve, or `undefined`. A pinned
+ * action is skipped: its URL is the pin under every style, so no style explains missing it.
+ *
+ * A walk of the registry per miss, and deliberately not an index: the registry and the style both
+ * move (`x dev` re-evaluates modules), and only a POST under `/api/` that matched no route pays —
+ * one string derivation per action, no I/O.
+ */
+function driftedAction(
+  pathname: string,
+): { readonly name: string; readonly under: ActionPathStyle } | undefined {
+  const served = actionPathStyle();
+  for (const under of ACTION_PATH_STYLES) {
+    if (under === served) continue;
+    // why no index: a memo keyed by path would outlive a re-registration and name a stale action.
+    for (const [name, seated] of seatedActions) {
+      if (defOf(seated).http?.path !== undefined) continue;
+      if (actionRoute(name, under).path === pathname) return { name, under };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * `hooks.explainMiss` for the action surface. Every value in the message is the framework's own:
+ * the name is a registered export name and both paths are derived from it — the caller's bytes
+ * reach the message only by being equal to one of them.
+ */
+export function explainActionPathMiss(
+  method: string,
+  pathname: string,
+): ContractDriftError | undefined {
+  if (method !== 'POST' || !pathname.startsWith(`${ACTION_PATH_PREFIX}/`)) return undefined;
+  const drifted = driftedAction(pathname);
+  if (drifted === undefined) return undefined;
+  const served = actionPathStyle();
+  return new ContractDriftError(
+    `POST ${pathname} is ${drifted.name} under pathStyle '${drifted.under}'; this server serves pathStyle '${served}', where it is POST ${servedActionRoute(drifted.name).path}`,
+    `rpc<Api['actions']>({ baseUrl, pathStyle: '${served}' })   # in a browser, pass no pathStyle: the page states it`,
+  );
+}

package/src/registry.ts

@@ -5,7 +5,7 @@
  */
 
 import type { ActionPathStyle } from '@ultimat3/core';
-import { SchemaUnsupportedError } from '@ultimat3/schema';
+import { SchemaUnsupportedError, toWireSchema } from '@ultimat3/schema';
 import type { ActionDescriptor, AnyAction } from './action';
 import { isAction, nameAction } from './action';
 import { resetApiDeclaration } from './api-declaration';
@@ -19,7 +19,7 @@ import {
 } from './http-path';
 import { assertIdempotencyScope } from './idempotency';
 import { defOf } from './invoke';
-import { jsonSchemaOf, mcpSchemaOf } from './json-schema';
+import { jsonSchemaOf } from './json-schema';
 import type { ActionPath } from './naming';
 import { seatedActions } from './registry-store';
 
@@ -111,7 +111,8 @@ function assertProjectable(name: string, target: AnyAction): void {
   for (const field of ['input', 'output'] as const) {
     try {
       jsonSchemaOf(target[field]);
-      mcpSchemaOf(target[field]);
+      // The schema `.tool()` and `tools/list` publish — the one an MCP client reads.
+      toWireSchema(target[field]);
     } catch {
       // The thrown value is deliberately not rendered into the cause: it is the provider's, of
       // unknown shape, and this package's own two facts — which action, which field — are the

package/src/request-deadline.ts

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

package/src/transition.ts

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

package/src/tx-scope.ts

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