@ultimat3/action 1.0.0

package/src/mutator.ts

@@ -0,0 +1,193 @@
+/**
+ * The `mutator` primitive: an action plus an optimistic local twin. It is built
+ * on `action()`, not beside it — a mutator IS an action, so it gets the route,
+ * the OpenAPI entry, the client method, the MCP tool, the job handle and the
+ * contract tests for free, and its authz is the same single evaluation.
+ */
+
+import type { Ctx } from '@ultimat3/core';
+import { assertNever } from '@ultimat3/core';
+import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import type { Action, ActionCache, ActionDef, ActionDescriptor, ActionMcp } from './action';
+import { action, isAction } from './action';
+import type { ActionPolicy } from './policy-gate';
+
+/** Minimum shape of a locally-stored row: an id the local twin can address. */
+export interface LocalRow {
+  readonly id: string;
+}
+
+/**
+ * Augmented by the app so `tx.posts` is typed:
+ *
+ * ```ts
+ * declare module '@ultimat3/action' {
+ *   interface LocalTables { posts: PostRow }
+ * }
+ * ```
+ */
+export interface LocalTables {
+  /** Reserved marker so augmentation, not this key, defines the table set. */
+  readonly '~ultimate': never;
+}
+
+export type LocalTableName = Exclude<keyof LocalTables, '~ultimate'>;
+
+export interface LocalTable<TRow extends LocalRow> {
+  insert(row: TRow): void;
+  update(id: string, patch: Partial<TRow> | ((row: TRow) => Partial<TRow>)): void;
+  delete(id: string): void;
+}
+
+/**
+ * The client-side write surface a mutator's `local()` gets. @ultimat3/realtime
+ * implements it over OPFS SQLite; tests implement it over a Map.
+ */
+export type LocalTx = {
+  readonly [K in LocalTableName]: LocalTable<Extract<LocalTables[K], LocalRow>>;
+} & {
+  /** Escape hatch for generated code that only knows the table name as a string. */
+  table<TRow extends LocalRow>(name: string): LocalTable<TRow>;
+};
+
+export interface CustomConflict<TOutput> {
+  readonly strategy: 'custom';
+  merge(local: TOutput, server: TOutput): TOutput;
+}
+
+export type Conflict<TOutput> = 'server-wins' | 'last-write-wins' | CustomConflict<TOutput>;
+
+export function custom<TOutput>(
+  merge: (local: TOutput, server: TOutput) => TOutput,
+): CustomConflict<TOutput> {
+  return { strategy: 'custom', merge };
+}
+
+export interface MutatorDef<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1> {
+  readonly input: TInput;
+  readonly output: TOutput;
+  readonly policy: ActionPolicy;
+  readonly cache?: ActionCache;
+  readonly mcp?: ActionMcp;
+  readonly idempotent?: boolean;
+  /** Optimistic twin: runs against the local store, synchronously, no I/O. */
+  local(tx: LocalTx, input: InferOutput<TInput>): void;
+  /** Authoritative write. Identical to an action `handle`, ctx-first for symmetry. */
+  server(
+    ctx: Ctx,
+    input: InferOutput<TInput>,
+  ): Promise<InferOutput<TOutput>> | InferOutput<TOutput>;
+  readonly conflict: Conflict<InferOutput<TOutput>>;
+}
+
+export type MutatorDescriptor = Omit<ActionDescriptor, 'kind'> & {
+  readonly kind: 'mutator';
+  readonly conflict: 'server-wins' | 'last-write-wins' | 'custom';
+};
+
+export interface Mutator<
+  TInput extends StandardSchemaV1 = StandardSchemaV1,
+  TOutput extends StandardSchemaV1 = StandardSchemaV1,
+> extends Action<TInput, TOutput> {
+  /**
+   * The brand, and the only thing `describeAction` has to go on: it reads this field to set
+   * `ActionDescriptor.mutator`, because a mutator's `describe()` still reports `kind: 'action'`.
+   * Renaming it here would silently turn every mutator back into a plain action downstream.
+   */
+  readonly isMutator: true;
+  readonly conflict: Conflict<InferOutput<TOutput>>;
+  /**
+   * Applied on the client before the server round trip, and replayed on every
+   * rebase — so it must stay a pure function of `(tx, input)`: no I/O, no clock,
+   * no randomness. Takes parsed input because nothing re-parses on this half.
+   */
+  local(tx: LocalTx, input: InferOutput<TInput>): void;
+  /**
+   * The authoritative half. Routes through the action's own callable, never the
+   * declared `server` — so input parsing, policy, the handler and output parsing
+   * run exactly once, in the one core, the same as every other surface. Takes raw
+   * input, like the callable and `.as()`, because this is where parsing happens.
+   */
+  server(ctx: Ctx, input: InferInput<TInput>): Promise<InferOutput<TOutput>>;
+  describeMutator(): MutatorDescriptor;
+  named(name: string): Mutator<TInput, TOutput>;
+}
+
+export function mutator<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
+  def: MutatorDef<TInput, TOutput>,
+): Mutator<TInput, TOutput> {
+  const actionDef: ActionDef<TInput, TOutput> = {
+    input: def.input,
+    output: def.output,
+    policy: def.policy,
+    ...(def.cache === undefined ? {} : { cache: def.cache }),
+    ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
+    ...(def.idempotent === undefined ? {} : { idempotent: def.idempotent }),
+    handle: ({ input, ctx }) => def.server(ctx, input),
+  };
+  return wrap(def, action(actionDef));
+}
+
+/**
+ * Structural, exactly like `isAction`: the brand alone is not enough, because a
+ * mutator's authoritative half runs through the action's declaration and a
+ * look-alike has none. Branding without `isAction` would have made this the one
+ * primitive whose façade a hand-rolled object could counterfeit.
+ */
+export function isMutator(value: unknown): value is Mutator {
+  return isAction(value) && (value as { isMutator?: unknown }).isMutator === true;
+}
+
+function wrap<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
+  def: MutatorDef<TInput, TOutput>,
+  base: Action<TInput, TOutput>,
+): Mutator<TInput, TOutput> {
+  // Captured before we overwrite it: wrapping in place would otherwise make
+  // `named` call itself forever instead of reaching the action's own rename.
+  const rename = base.named.bind(base);
+  const self: Mutator<TInput, TOutput> = Object.assign(base, {
+    isMutator: true as const,
+    conflict: def.conflict,
+    local: (tx: LocalTx, input: InferOutput<TInput>): void => {
+      def.local(tx, input);
+    },
+    // `base(...)` and not `def.server(...)`: the callable IS `invoke`, so the
+    // authoritative half cannot skip the input parse, the policy or the output
+    // parse. Calling the declaration here would be the second execution path.
+    server: (ctx: Ctx, input: InferInput<TInput>): Promise<InferOutput<TOutput>> =>
+      base(input, { ctx }),
+    describeMutator: (): MutatorDescriptor => ({
+      ...base.describe(),
+      kind: 'mutator' as const,
+      conflict: strategyOf(def.conflict),
+    }),
+    named: (name: string): Mutator<TInput, TOutput> => wrap(def, rename(name)),
+  });
+  return self;
+}
+
+export function strategyOf<TOutput>(
+  conflict: Conflict<TOutput>,
+): 'server-wins' | 'last-write-wins' | 'custom' {
+  return typeof conflict === 'string' ? conflict : conflict.strategy;
+}
+
+/**
+ * Rebase decision for @ultimat3/realtime: which value survives when the local
+ * twin and the server disagree.
+ */
+export function resolveConflict<TOutput>(
+  conflict: Conflict<TOutput>,
+  local: TOutput,
+  server: TOutput,
+): TOutput {
+  if (typeof conflict !== 'string') return conflict.merge(local, server);
+  switch (conflict) {
+    case 'server-wins':
+      return server;
+    case 'last-write-wins':
+      return local;
+    default:
+      return assertNever(conflict);
+  }
+}

package/src/naming.ts

@@ -0,0 +1,99 @@
+/**
+ * The one naming rule: an action's export name derives its HTTP path and MCP
+ * tool name. Pure string math so the browser client can derive the same path
+ * without importing a byte of server code.
+ */
+
+/** Irregular plurals we actually hit in domain models. Extend deliberately, not eagerly. */
+const IRREGULAR: Readonly<Record<string, string>> = {
+  person: 'people',
+  child: 'children',
+  man: 'men',
+  woman: 'women',
+  datum: 'data',
+  index: 'indexes',
+  entry: 'entries',
+};
+
+export interface ActionPath {
+  /** First camelCase word, kebab-cased. `publishPost` -> `publish`. */
+  readonly verb: string;
+  /** Remaining words, last one pluralized, kebab-cased. `publishPost` -> `posts`. */
+  readonly resource: string;
+  /** `POST /api/<resource>/<verb>`. */
+  readonly path: string;
+}
+
+/** camelCase / PascalCase / SCREAMING_SNAKE -> lowercase words. */
+export function splitWords(name: string): string[] {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .split(/[\s_-]+/)
+    .filter((word) => word.length > 0)
+    .map((word) => word.toLowerCase());
+}
+
+/**
+ * Naive-on-purpose English pluralizer. A word that already ends in `s` is left
+ * alone, so `publishPosts` and `publishPost` agree on the `posts` resource.
+ */
+export function pluralize(word: string): string {
+  const irregular = IRREGULAR[word];
+  if (irregular !== undefined) return irregular;
+  if (word.endsWith('s')) return word;
+  if (/(x|z|ch|sh)$/.test(word)) return `${word}es`;
+  if (/[^aeiou]y$/.test(word)) return `${word.slice(0, -1)}ies`;
+  return `${word}s`;
+}
+
+/**
+ * `publishPost`        -> POST /api/posts/publish
+ * `updateUserProfile`  -> POST /api/user-profiles/update
+ * `likePost`           -> POST /api/posts/like
+ * `checkout`           -> POST /api/checkouts/invoke   (single-word fallback)
+ */
+export function derivePath(name: string): ActionPath {
+  const words = splitWords(name);
+  const head = words[0] ?? 'invoke';
+  if (words.length < 2) {
+    const resource = pluralize(head);
+    return { verb: 'invoke', resource, path: `/api/${resource}/invoke` };
+  }
+  const nouns = words.slice(1);
+  const last = nouns[nouns.length - 1] ?? head;
+  const resource = [...nouns.slice(0, -1), pluralize(last)].join('-');
+  return { verb: head, resource, path: `/api/${resource}/${head}` };
+}
+
+/** MCP tool names are `snake_case`: `publishPost` -> `publish_post`. */
+export function toToolName(name: string): string {
+  return splitWords(name).join('_');
+}
+
+/** OpenAPI `operationId` is the action name verbatim — it is already unique. */
+export function toOperationId(name: string): string {
+  return name;
+}
+
+const pascal = (name: string): string =>
+  splitWords(name)
+    .map((word) => `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`)
+    .join('');
+
+/** OpenAPI component name for an action's input schema. */
+export function inputSchemaName(name: string): string {
+  return `${pascal(name)}Input`;
+}
+
+/** OpenAPI component name for an action's output schema. */
+export function outputSchemaName(name: string): string {
+  return `${pascal(name)}Output`;
+}
+
+/** RFC 9457 body shared by every error response. */
+export const PROBLEM_SCHEMA_NAME = 'Problem';
+
+export function schemaRef(component: string): string {
+  return `#/components/schemas/${component}`;
+}

package/src/openapi.ts

@@ -0,0 +1,85 @@
+/**
+ * Projection 2: the whole registry as one OpenAPI 3.1 document.
+ *
+ * DETERMINISM IS A HARD REQUIREMENT. `x verify` diffs this output against the
+ * committed spec to detect contract drift, so: keys are sorted at every depth
+ * (`stableStringify`), paths and components are built from the name-sorted
+ * registry, and nothing here reads the clock, the environment or a random source.
+ */
+
+import type { AnyAction } from './action';
+import { toOpenApiOperation } from './http';
+import { actionName } from './invoke';
+import { type JsonSchemaObject, jsonSchemaOf, sortSchema } from './json-schema';
+import { derivePath, inputSchemaName, outputSchemaName, PROBLEM_SCHEMA_NAME } from './naming';
+import { listActions } from './registry';
+import { stableStringify } from './stable';
+
+export interface OpenApiInfo {
+  readonly title: string;
+  readonly version: string;
+}
+
+export interface OpenApiDocument {
+  readonly openapi: '3.1.0';
+  readonly info: OpenApiInfo;
+  readonly paths: Record<string, unknown>;
+  readonly components: { readonly schemas: Record<string, JsonSchemaObject> };
+  readonly tags: readonly { readonly name: string }[];
+}
+
+export interface BuildOpenApiOptions {
+  readonly title?: string;
+  readonly version?: string;
+  /** Defaults to the whole registry. Pass a subset to spec one surface only. */
+  readonly actions?: readonly AnyAction[];
+}
+
+export function buildOpenApi(options: BuildOpenApiOptions = {}): OpenApiDocument {
+  const actions = [...(options.actions ?? listActions())].sort(compareByName);
+  const paths: Record<string, unknown> = {};
+  const schemas: Record<string, JsonSchemaObject> = { [PROBLEM_SCHEMA_NAME]: PROBLEM_SCHEMA };
+  const tags = new Set<string>();
+
+  for (const target of actions) {
+    const name = actionName(target);
+    const { path, resource } = derivePath(name);
+    paths[path] = { post: toOpenApiOperation(target) };
+    schemas[inputSchemaName(name)] = sortSchema(jsonSchemaOf(target.input));
+    schemas[outputSchemaName(name)] = sortSchema(jsonSchemaOf(target.output));
+    tags.add(resource);
+  }
+
+  return {
+    openapi: '3.1.0',
+    info: { title: options.title ?? 'Ultimate API', version: options.version ?? '0.0.0' },
+    paths,
+    components: { schemas },
+    tags: [...tags].sort().map((name) => ({ name })),
+  };
+}
+
+/** The bytes `x verify` compares. Sorted keys, trailing newline, 2-space indent. */
+export function serializeOpenApi(document: OpenApiDocument): string {
+  return `${stableStringify(document, 2)}\n`;
+}
+
+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). */
+const PROBLEM_SCHEMA: JsonSchemaObject = {
+  type: 'object',
+  required: ['type', 'title', 'status', 'code'],
+  properties: {
+    type: { type: 'string' },
+    title: { type: 'string' },
+    status: { type: 'integer' },
+    detail: { type: 'string' },
+    code: { type: 'string', pattern: '^X_[A-Z0-9_]+$' },
+    cause: { type: 'string' },
+    fix: { type: 'string' },
+    docs: { type: 'string', format: 'uri' },
+  },
+};

package/src/policy-gate.ts

@@ -0,0 +1,81 @@
+/**
+ * The single point of contact with @ultimat3/policy. Every surface (HTTP, MCP,
+ * job, direct server call) reaches authz through `guard()` — there is no second
+ * code path, which is what makes "one authz system" true rather than aspirational.
+ */
+
+import type { Actor, Ctx } from '@ultimat3/core';
+import { assertNever, isAnonymous } from '@ultimat3/core';
+import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
+import { enforce } from '@ultimat3/policy';
+import { ActionDeniedError } from './errors';
+
+/**
+ * Policies are opaque here: we evaluate them, we never introspect their rules.
+ * `TRow` is what a row-level rule decides about, defaulted so the bare
+ * `ActionPolicy` keeps meaning "decides on input, any row or none".
+ */
+export type ActionPolicy<TRow = unknown> = Policy<unknown, TRow>;
+
+/** Which projection is running. Selects the deny renderer, never the decision. */
+export type Surface = 'server' | 'http' | 'mcp' | 'job';
+
+export interface PolicySubject {
+  readonly actor: Actor | null;
+  readonly input: unknown;
+  /**
+   * The already-loaded row a row-level rule decides about; `null` when the action
+   * declared no loader. Optional here and required in `PolicyArgs` for the same
+   * reason `EvaluateArgs.row` is: a surface deciding on input alone should not have
+   * to write `row: null`, but the predicate it reaches must still see the field.
+   * `invoke` always passes it, so the gap closes before any rule runs.
+   */
+  readonly row?: unknown;
+  readonly ctx: Ctx;
+  readonly action: string;
+}
+
+/**
+ * Evaluate once, render the denial per surface. `enforce` runs the same policy
+ * object for every surface, so an actor denied over HTTP is denied over MCP with
+ * the same reason and the same code.
+ */
+export function guard(policy: ActionPolicy, subject: PolicySubject, surface: Surface): void {
+  const denial = enforce(policySurface(surface), policy, {
+    input: subject.input,
+    actor: subject.actor,
+    // `evaluate()` normalises a missing row to `null`, so an input-only rule and a
+    // row rule reach the predicate through one shape rather than two.
+    row: subject.row,
+    ctx: subject.ctx,
+  });
+  if (denial !== undefined) throw new ActionDeniedError(subject.action, denial);
+}
+
+/** A direct server call is the job surface: no request, no response to shape. */
+function policySurface(surface: Surface): PolicySurface {
+  switch (surface) {
+    case 'http':
+      return 'http';
+    case 'mcp':
+      return 'mcp';
+    case 'job':
+    case 'server':
+      return 'job';
+    default:
+      return assertNever(surface);
+  }
+}
+
+/**
+ * Core models "nobody" as an anonymous actor; policy models it as `null`, which is
+ * what turns a missing session into `X_UNAUTHENTICATED` instead of a bare denial.
+ */
+export function actorOf(ctx: Ctx): Actor | null {
+  return isAnonymous(ctx.actor) ? null : ctx.actor;
+}
+
+/** The capability an action requires, for manifests and OpenAPI metadata. */
+export function policyCapability(policy: ActionPolicy): string {
+  return policy.label;
+}

package/src/registry.ts

@@ -0,0 +1,70 @@
+/**
+ * The action registry. Names come from export names — `registerActions(module)`
+ * is how a module namespace becomes named, collision-checked, projectable
+ * actions. Registration is also where a missing policy becomes a build error.
+ */
+
+import type { ActionDescriptor, AnyAction } from './action';
+import { isAction, nameAction } from './action';
+import { ActionDuplicateError, ActionPolicyMissingError } from './errors';
+
+const registry = new Map<string, AnyAction>();
+
+/**
+ * Register one action under an explicit name. The name lands on the action you
+ * passed, so the module's own export is projectable after boot and there is no
+ * "use the return value instead" rule to forget.
+ */
+export function registerAction<A extends AnyAction>(name: string, target: A): A {
+  const seated = registry.get(name);
+  if (seated !== undefined) {
+    // Re-registering the SAME object under the SAME name is one registration seen twice, not a
+    // collision: `defineApi` registers a feature module at boot and the framework's module scan
+    // reaches the same declaration file directly, so both arrive at the identical action. Only a
+    // DIFFERENT action under a taken name is the ambiguity `X_ACTION_DUPLICATE` exists to refuse.
+    if (seated !== (target as AnyAction)) throw new ActionDuplicateError(name);
+    return target;
+  }
+  if (target.policy === undefined || target.policy === null) {
+    throw new ActionPolicyMissingError(name);
+  }
+  const named = nameAction(target, name);
+  registry.set(name, named);
+  return named;
+}
+
+/**
+ * Register every action exported by a module namespace, keyed by export name.
+ * `registerActions(await import('./actions'))` at boot; the CLI does the same
+ * during `x verify` so the manifest and the server agree by construction.
+ */
+export function registerActions(module: Record<string, unknown>): readonly AnyAction[] {
+  const registered: AnyAction[] = [];
+  for (const name of Object.keys(module).sort()) {
+    const value = module[name];
+    if (isAction(value)) registered.push(registerAction(name, value));
+  }
+  return registered;
+}
+
+export function getAction(name: string): AnyAction | undefined {
+  return registry.get(name);
+}
+
+/** Sorted by name: iteration order is part of the deterministic contract output. */
+export function listActions(): readonly AnyAction[] {
+  return [...registry.entries()].sort(byName).map(([, value]) => value);
+}
+
+export function describeActions(): readonly ActionDescriptor[] {
+  return listActions().map((target) => target.describe());
+}
+
+/** Test-only. Production registers once at boot and never unregisters. */
+export function resetRegistry(): void {
+  registry.clear();
+}
+
+function byName(a: readonly [string, AnyAction], b: readonly [string, AnyAction]): number {
+  return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0;
+}

package/src/stable.ts

@@ -0,0 +1,68 @@
+/**
+ * Deterministic JSON: key-sorted serialization plus a cheap content hash.
+ * Both the OpenAPI document and idempotency fingerprints depend on byte-stable
+ * output, so this is the only serializer either path is allowed to use.
+ */
+
+export type JsonObject = Record<string, unknown>;
+
+export function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** JSON with object keys sorted at every depth. No timestamps, no insertion-order leaks. */
+export function stableStringify(value: unknown, indent = 0): string {
+  return write(value, indent, 0);
+}
+
+function write(value: unknown, indent: number, depth: number): string {
+  if (value === null) return 'null';
+  switch (typeof value) {
+    case 'string':
+      return JSON.stringify(value);
+    case 'number':
+      return Number.isFinite(value) ? String(value) : 'null';
+    case 'boolean':
+      return String(value);
+    case 'bigint':
+      return JSON.stringify(`${value}n`);
+    case 'undefined':
+    case 'function':
+    case 'symbol':
+      return 'null';
+    default:
+      break;
+  }
+  const pad = indent > 0 ? '\n'.padEnd(1 + indent * (depth + 1), ' ') : '';
+  const close = indent > 0 ? '\n'.padEnd(1 + indent * depth, ' ') : '';
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    const items = value.map((item) => write(item, indent, depth + 1));
+    return `[${pad}${items.join(`,${pad || ''}`)}${close}]`;
+  }
+  const record = value as JsonObject;
+  const keys = Object.keys(record)
+    .filter((key) => record[key] !== undefined)
+    .sort();
+  if (keys.length === 0) return '{}';
+  const gap = indent > 0 ? ' ' : '';
+  const entries = keys.map(
+    (key) => `${JSON.stringify(key)}:${gap}${write(record[key], indent, depth + 1)}`,
+  );
+  return `{${pad}${entries.join(`,${pad || ''}`)}${close}}`;
+}
+
+/** FNV-1a/32 as hex. Fingerprinting only — never a security boundary. */
+export function fnv1a(input: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, '0');
+}
+
+/** Stable fingerprint of any JSON-ish value. */
+export function fingerprint(value: unknown): string {
+  return fnv1a(stableStringify(value));
+}

package/src/tags.ts

@@ -0,0 +1,17 @@
+/**
+ * Cache tags stay opaque to actions — we hand them back to @ultimat3/cache
+ * untouched. The only thing this package needs is the wire string per tag, for
+ * manifests, OpenAPI metadata and the invalidation graph in `/_x`.
+ */
+
+import type { CacheTag } from '@ultimat3/cache';
+import { serializeTag } from '@ultimat3/cache';
+
+export function tagKey(value: CacheTag): string {
+  return serializeTag(value);
+}
+
+/** Sorted + de-duplicated: descriptor output must not depend on declaration order. */
+export function tagKeys(tags: readonly CacheTag[]): readonly string[] {
+  return [...new Set(tags.map(tagKey))].sort();
+}

package/src/validate.ts

@@ -0,0 +1,38 @@
+/**
+ * Schema validation for every surface. One code path covers HTTP, MCP, jobs and
+ * direct server calls, so all four reject the same payload with the same code
+ * and the same issue text — on the way in and on the way out.
+ */
+
+import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import { formatIssues, validateAsync } from '@ultimat3/schema';
+import { InputInvalidError, OutputInvalidError } from './errors';
+
+export async function validateInput<S extends StandardSchemaV1>(
+  schema: S,
+  raw: unknown,
+  actionName: string,
+): Promise<InferOutput<S>> {
+  const result = await validateAsync(schema, raw);
+  if (result.issues !== undefined) {
+    throw new InputInvalidError(actionName, formatIssues(result.issues).join('; '));
+  }
+  return result.value;
+}
+
+/**
+ * The handler's return value is data too. Parsing it is what makes the OpenAPI
+ * response schema, the typed client and the MCP `outputSchema` true rather than
+ * documentation — a handler that drifts from `output` fails on its own call.
+ */
+export async function validateOutput<S extends StandardSchemaV1>(
+  schema: S,
+  produced: unknown,
+  actionName: string,
+): Promise<InferOutput<S>> {
+  const result = await validateAsync(schema, produced);
+  if (result.issues !== undefined) {
+    throw new OutputInvalidError(actionName, formatIssues(result.issues).join('; '));
+  }
+  return result.value;
+}