@codespar/cli 0.13.0 → 0.14.0

package/templates/bills-agent/packages/agent-core/src/rail.ts

@@ -0,0 +1,87 @@
+/**
+ * The payment rail the core dispatches to once an execution is `executing`.
+ * Two implementations: the CodeSpar sandbox through the API (needs a
+ * `csk_test_` key) and a local stub persisted in state.db for CI and
+ * scenarios. Both are idempotent on `attempt_id`: presenting the same
+ * attempt again answers the earlier outcome instead of paying twice.
+ */
+import type { Actor, ChargeInstrument } from "./types.js";
+
+export interface RailPayment {
+  attempt_id: string;
+  mandate_id: string;
+  amount_minor: number;
+  currency: string;
+  payee: string;
+  purpose: string;
+  agent_id: string;
+  description?: string;
+  /** Display name of the counterparty (a receivable's debtor). The rail that issues a charge needs it; a payout rail ignores it. */
+  beneficiary?: string;
+  /** Due date of a receivable, `YYYY-MM-DD`. */
+  due_date?: string;
+  /** Section 4.5: carried on every call. The API has no wire field for it yet; see OPEN_QUESTIONS. */
+  actor: Actor;
+}
+
+export type RailOutcome =
+  | {
+      /**
+       * The rail took the attempt and the outcome comes later: a receivable
+       * was issued and its payer has not acted yet. The execution stays
+       * `executing`; `lookup()` or a `commerce.charge.*` event closes it.
+       */
+      status: "accepted";
+      transaction_id: string;
+      instrument: ChargeInstrument;
+      sandbox: boolean;
+      raw: unknown;
+    }
+  | {
+      status: "settled";
+      transaction_id: string;
+      receipt_id: string | null;
+      money_moved: boolean;
+      sandbox: boolean;
+      raw: unknown;
+    }
+  | {
+      /** The rail answered and refused. Nothing moved. */
+      status: "failed";
+      code: string;
+      message: string;
+      raw?: unknown;
+    }
+  | {
+      /** The outcome is unknown (timeout, 5xx, `psp_dispatch_uncertain`). Never retried blind: reconciled. */
+      status: "uncertain";
+      code: string;
+      message: string;
+      raw?: unknown;
+    };
+
+export interface RailReceipt {
+  receipt_id: string;
+  /** `payment` (the API's sealed receipt) or `charge` (the paid receivable as the API reports it; no seal exists for it today). */
+  kind?: "payment" | "charge";
+  state: string;
+  mandate: { id: string };
+  payment: { amount_minor: number; payee: string | null; attempt_id: string; money_moved: boolean; sandbox: boolean; at: string };
+  /** Null when the API seals nothing for this kind of record. */
+  chain: string | null;
+  receipt_sig: string | null;
+  /** Section 4.5: the kit stamps the actor onto the local copy of every receipt. */
+  actor: Actor;
+  raw: unknown;
+}
+
+/** What a reconcile learns: a recorded outcome, "still running", or nothing. Never a new payment. */
+export type RailLookup = RailOutcome | { status: "in_flight" } | undefined;
+
+export interface PaymentRail {
+  readonly name: "stub" | "codespar" | "stub-charge" | "codespar-charge";
+  pay(payment: RailPayment): Promise<RailOutcome>;
+  /** Answers the outcome of an attempt already presented, `in_flight` while the rail is still on it, or `undefined` when the rail never saw it. */
+  lookup(attemptId: string, payment: RailPayment): Promise<RailLookup>;
+  receipt(receiptId: string, actor: Actor): Promise<RailReceipt | undefined>;
+}

package/templates/bills-agent/packages/agent-core/src/revocation.ts

@@ -0,0 +1,30 @@
+/**
+ * Section 4.7: the core asks a status source before `executing`. The
+ * approval artifact alone is not enough, because it may predate a
+ * revocation. The interface is the contract. Two implementations ship:
+ * `api/mandate-status.ts` reads `GET /v1/mandates/{id}` and is what a run
+ * with a test key gets; `stubs/mandate-status.ts` answers from the local
+ * state.db and is what a run without a key (the CI, the scenarios, `rerun`)
+ * gets, so revocation can be driven with no network.
+ *
+ * `unknown` is a status too: the source could not say. The engine treats it
+ * as "do not execute" (`mandate_status_unavailable`), never as `active`.
+ */
+export type MandateStatus = "active" | "paused" | "revoked" | "expired";
+
+export interface MandateStatusReport {
+  mandate_id: string;
+  status: MandateStatus | "unknown";
+  /** True when the organization pressed the kill switch (`org pauseAll`). The API has no such read yet; only the stub can say it. */
+  org_paused: boolean;
+  checked_at: string;
+  /** Which source answered, so the bundle says whether the check was real. */
+  source: "stub" | "api";
+  /** Why the status is `unknown`, for the trail. Never carries a response body. */
+  detail?: string;
+}
+
+export interface MandateStatusSource {
+  /** Must not throw for a read that failed: answer `unknown` and say why. A source that throws is still fail-closed at the gate. */
+  check(mandateId: string): Promise<MandateStatusReport>;
+}

package/templates/bills-agent/packages/agent-core/src/secrets.ts

@@ -0,0 +1,30 @@
+/**
+ * Sandbox by construction: a key outside the `csk_test_` pattern fails
+ * before any network call. Nothing in this repository ever holds a live key.
+ */
+export const TEST_KEY_PREFIX = "csk_test_";
+
+export class NotATestKeyError extends Error {
+  constructor() {
+    super(
+      `CODESPAR_API_KEY must be a test key (prefix "${TEST_KEY_PREFIX}"). ` +
+        "This kit runs in the sandbox only; a live key is refused before any call is made.",
+    );
+    this.name = "NotATestKeyError";
+  }
+}
+
+export function isTestKey(key: string | undefined): key is string {
+  return typeof key === "string" && key.startsWith(TEST_KEY_PREFIX) && key.length > TEST_KEY_PREFIX.length;
+}
+
+export function assertTestKey(key: string | undefined): string {
+  if (!isTestKey(key)) throw new NotATestKeyError();
+  return key;
+}
+
+/** For logs and bundles: the prefix and the last four characters, nothing else. */
+export function redactKey(key: string): string {
+  if (key.length <= 12) return "csk_****";
+  return `${key.slice(0, 9)}…${key.slice(-4)}`;
+}

package/templates/bills-agent/packages/agent-core/src/state/store.ts

@@ -0,0 +1,307 @@
+/**
+ * Section 10: local state in `.codespar/state.db` (SQLite, via `node:sqlite`,
+ * so there is no native build step). Executions and their states, the
+ * append-only event log, the event cursor, the outbox with its
+ * `idempotency_key`, the approval artifacts, and two stub tables the
+ * sandbox stubs persist into so a killed process finds them again.
+ */
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import type { Execution, ExecutionState } from "../state-machine.js";
+import type { ApprovalArtifact } from "../types.js";
+
+export interface EventRow {
+  seq: number;
+  run_id: string;
+  execution_id: string | null;
+  type: string;
+  payload: unknown;
+  at: string;
+}
+
+export type OutboxStatus = "pending" | "sent" | "done" | "failed";
+
+export interface OutboxRow {
+  idempotency_key: string;
+  execution_id: string;
+  kind: string;
+  payload: unknown;
+  status: OutboxStatus;
+  response: unknown;
+  created_at: string;
+  updated_at: string;
+}
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS executions (
+  id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL,
+  state TEXT NOT NULL,
+  mandate_id TEXT NOT NULL,
+  json TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS executions_run ON executions(run_id);
+CREATE INDEX IF NOT EXISTS executions_state ON executions(state);
+
+CREATE TABLE IF NOT EXISTS events (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  run_id TEXT NOT NULL,
+  execution_id TEXT,
+  event_id TEXT UNIQUE,
+  type TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS cursors (
+  name TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS outbox (
+  idempotency_key TEXT PRIMARY KEY,
+  execution_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  status TEXT NOT NULL,
+  response TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS approvals (
+  approval_id TEXT PRIMARY KEY,
+  execution_id TEXT NOT NULL,
+  json TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS stub_rail_attempts (
+  attempt_id TEXT PRIMARY KEY,
+  request TEXT NOT NULL,
+  outcome TEXT NOT NULL,
+  at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS stub_mandate_status (
+  mandate_id TEXT PRIMARY KEY,
+  status TEXT NOT NULL,
+  reason TEXT,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS stub_org (
+  org_id TEXT PRIMARY KEY,
+  paused INTEGER NOT NULL DEFAULT 0,
+  updated_at TEXT NOT NULL
+);
+`;
+
+export class StateStore {
+  private readonly db: DatabaseSync;
+
+  constructor(readonly path: string) {
+    if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+    this.db = new DatabaseSync(path);
+    this.db.exec("PRAGMA journal_mode = WAL; PRAGMA synchronous = FULL; PRAGMA foreign_keys = ON;");
+    this.db.exec(SCHEMA);
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  transaction<T>(fn: () => T): T {
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const out = fn();
+      this.db.exec("COMMIT");
+      return out;
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      throw err;
+    }
+  }
+
+  // executions
+
+  saveExecution(execution: Execution): void {
+    this.db
+      .prepare(
+        `INSERT INTO executions (id, run_id, state, mandate_id, json, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET state = excluded.state, json = excluded.json, updated_at = excluded.updated_at`,
+      )
+      .run(execution.id, execution.run_id, execution.state, execution.mandate.id, JSON.stringify(execution), execution.created_at, execution.updated_at);
+  }
+
+  getExecution(id: string): Execution | undefined {
+    const row = this.db.prepare("SELECT json FROM executions WHERE id = ?").get(id) as { json: string } | undefined;
+    return row ? (JSON.parse(row.json) as Execution) : undefined;
+  }
+
+  listExecutions(filter: { run_id?: string; state?: ExecutionState | ExecutionState[]; mandate_id?: string } = {}): Execution[] {
+    const where: string[] = [];
+    const args: string[] = [];
+    if (filter.run_id) {
+      where.push("run_id = ?");
+      args.push(filter.run_id);
+    }
+    if (filter.mandate_id) {
+      where.push("mandate_id = ?");
+      args.push(filter.mandate_id);
+    }
+    if (filter.state) {
+      const states = Array.isArray(filter.state) ? filter.state : [filter.state];
+      where.push(`state IN (${states.map(() => "?").join(",")})`);
+      args.push(...states);
+    }
+    const sql = `SELECT json FROM executions ${where.length ? "WHERE " + where.join(" AND ") : ""} ORDER BY created_at, id`;
+    return (this.db.prepare(sql).all(...args) as { json: string }[]).map((r) => JSON.parse(r.json) as Execution);
+  }
+
+  // events
+
+  appendEvent(event: { run_id: string; execution_id?: string | null; event_id?: string; type: string; payload: unknown; at: string }): EventRow | undefined {
+    if (event.event_id) {
+      const dup = this.db.prepare("SELECT seq FROM events WHERE event_id = ?").get(event.event_id);
+      if (dup) return undefined;
+    }
+    const result = this.db
+      .prepare("INSERT INTO events (run_id, execution_id, event_id, type, payload, at) VALUES (?, ?, ?, ?, ?, ?)")
+      .run(event.run_id, event.execution_id ?? null, event.event_id ?? null, event.type, JSON.stringify(event.payload ?? null), event.at);
+    return { seq: Number(result.lastInsertRowid), run_id: event.run_id, execution_id: event.execution_id ?? null, type: event.type, payload: event.payload, at: event.at };
+  }
+
+  listEvents(filter: { run_id?: string; execution_id?: string; after_seq?: number } = {}): EventRow[] {
+    const where: string[] = [];
+    const args: (string | number)[] = [];
+    if (filter.run_id) {
+      where.push("run_id = ?");
+      args.push(filter.run_id);
+    }
+    if (filter.execution_id) {
+      where.push("execution_id = ?");
+      args.push(filter.execution_id);
+    }
+    if (filter.after_seq !== undefined) {
+      where.push("seq > ?");
+      args.push(filter.after_seq);
+    }
+    const sql = `SELECT seq, run_id, execution_id, type, payload, at FROM events ${where.length ? "WHERE " + where.join(" AND ") : ""} ORDER BY seq`;
+    return (this.db.prepare(sql).all(...args) as Array<Omit<EventRow, "payload"> & { payload: string }>).map((r) => ({ ...r, payload: JSON.parse(r.payload) }));
+  }
+
+  getCursor(name: string): string | undefined {
+    const row = this.db.prepare("SELECT value FROM cursors WHERE name = ?").get(name) as { value: string } | undefined;
+    return row?.value;
+  }
+
+  setCursor(name: string, value: string): void {
+    this.db.prepare("INSERT INTO cursors (name, value) VALUES (?, ?) ON CONFLICT(name) DO UPDATE SET value = excluded.value").run(name, value);
+  }
+
+  // outbox
+
+  putOutbox(row: Omit<OutboxRow, "updated_at">): void {
+    this.db
+      .prepare(
+        `INSERT INTO outbox (idempotency_key, execution_id, kind, payload, status, response, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(idempotency_key) DO NOTHING`,
+      )
+      .run(row.idempotency_key, row.execution_id, row.kind, JSON.stringify(row.payload), row.status, row.response === undefined ? null : JSON.stringify(row.response), row.created_at, row.created_at);
+  }
+
+  updateOutbox(idempotencyKey: string, status: OutboxStatus, response: unknown, at: string): void {
+    this.db.prepare("UPDATE outbox SET status = ?, response = ?, updated_at = ? WHERE idempotency_key = ?").run(status, response === undefined ? null : JSON.stringify(response), at, idempotencyKey);
+  }
+
+  getOutbox(idempotencyKey: string): OutboxRow | undefined {
+    const row = this.db.prepare("SELECT * FROM outbox WHERE idempotency_key = ?").get(idempotencyKey) as (Omit<OutboxRow, "payload" | "response"> & { payload: string; response: string | null }) | undefined;
+    return row ? { ...row, payload: JSON.parse(row.payload), response: row.response ? JSON.parse(row.response) : undefined } : undefined;
+  }
+
+  listOutbox(filter: { execution_id?: string; status?: OutboxStatus[] } = {}): OutboxRow[] {
+    const where: string[] = [];
+    const args: string[] = [];
+    if (filter.execution_id) {
+      where.push("execution_id = ?");
+      args.push(filter.execution_id);
+    }
+    if (filter.status) {
+      where.push(`status IN (${filter.status.map(() => "?").join(",")})`);
+      args.push(...filter.status);
+    }
+    const sql = `SELECT * FROM outbox ${where.length ? "WHERE " + where.join(" AND ") : ""} ORDER BY created_at, idempotency_key`;
+    return (this.db.prepare(sql).all(...args) as Array<Omit<OutboxRow, "payload" | "response"> & { payload: string; response: string | null }>).map((r) => ({
+      ...r,
+      payload: JSON.parse(r.payload),
+      response: r.response ? JSON.parse(r.response) : undefined,
+    }));
+  }
+
+  // approvals
+
+  saveApproval(artifact: ApprovalArtifact): void {
+    this.db.prepare("INSERT OR REPLACE INTO approvals (approval_id, execution_id, json, created_at) VALUES (?, ?, ?, ?)").run(artifact.approval_id, artifact.execution_id, JSON.stringify(artifact), artifact.approved_at);
+  }
+
+  getApproval(approvalId: string): ApprovalArtifact | undefined {
+    const row = this.db.prepare("SELECT json FROM approvals WHERE approval_id = ?").get(approvalId) as { json: string } | undefined;
+    return row ? (JSON.parse(row.json) as ApprovalArtifact) : undefined;
+  }
+
+  // stub rail (sandbox stand-in, persisted so a restart still sees the attempt)
+
+  stubRailGet(attemptId: string): { request: unknown; outcome: unknown; at: string } | undefined {
+    const row = this.db.prepare("SELECT request, outcome, at FROM stub_rail_attempts WHERE attempt_id = ?").get(attemptId) as { request: string; outcome: string; at: string } | undefined;
+    return row ? { request: JSON.parse(row.request), outcome: JSON.parse(row.outcome), at: row.at } : undefined;
+  }
+
+  stubRailFindByReceipt(receiptId: string): { request: unknown; outcome: unknown; at: string } | undefined {
+    const row = this.db.prepare("SELECT request, outcome, at FROM stub_rail_attempts WHERE json_extract(outcome, '$.receipt_id') = ?").get(receiptId) as { request: string; outcome: string; at: string } | undefined;
+    return row ? { request: JSON.parse(row.request), outcome: JSON.parse(row.outcome), at: row.at } : undefined;
+  }
+
+  stubRailFindByTransaction(transactionId: string): { request: unknown; outcome: unknown; at: string } | undefined {
+    const row = this.db.prepare("SELECT request, outcome, at FROM stub_rail_attempts WHERE json_extract(outcome, '$.transaction_id') = ?").get(transactionId) as { request: string; outcome: string; at: string } | undefined;
+    return row ? { request: JSON.parse(row.request), outcome: JSON.parse(row.outcome), at: row.at } : undefined;
+  }
+
+  stubRailPut(attemptId: string, request: unknown, outcome: unknown, at: string): boolean {
+    const result = this.db.prepare("INSERT OR IGNORE INTO stub_rail_attempts (attempt_id, request, outcome, at) VALUES (?, ?, ?, ?)").run(attemptId, JSON.stringify(request), JSON.stringify(outcome), at);
+    return result.changes === 1;
+  }
+
+  /** The stub receivable rail: an issued charge changes state as its payer acts, under the same attempt id. */
+  stubRailReplace(attemptId: string, request: unknown, outcome: unknown, at: string): void {
+    this.db
+      .prepare("INSERT INTO stub_rail_attempts (attempt_id, request, outcome, at) VALUES (?, ?, ?, ?) ON CONFLICT(attempt_id) DO UPDATE SET outcome = excluded.outcome, at = excluded.at")
+      .run(attemptId, JSON.stringify(request), JSON.stringify(outcome), at);
+  }
+
+  // stub mandate status / org pause (the local stand-in of stubs/mandate-status.ts, for runs without a key)
+
+  stubMandateStatus(mandateId: string): { status: string; reason: string | null } | undefined {
+    return this.db.prepare("SELECT status, reason FROM stub_mandate_status WHERE mandate_id = ?").get(mandateId) as { status: string; reason: string | null } | undefined;
+  }
+
+  stubSetMandateStatus(mandateId: string, status: string, reason: string | null, at: string): void {
+    this.db
+      .prepare("INSERT INTO stub_mandate_status (mandate_id, status, reason, updated_at) VALUES (?, ?, ?, ?) ON CONFLICT(mandate_id) DO UPDATE SET status = excluded.status, reason = excluded.reason, updated_at = excluded.updated_at")
+      .run(mandateId, status, reason, at);
+  }
+
+  stubOrgPaused(orgId: string): boolean {
+    const row = this.db.prepare("SELECT paused FROM stub_org WHERE org_id = ?").get(orgId) as { paused: number } | undefined;
+    return row?.paused === 1;
+  }
+
+  stubSetOrgPaused(orgId: string, paused: boolean, at: string): void {
+    this.db.prepare("INSERT INTO stub_org (org_id, paused, updated_at) VALUES (?, ?, ?) ON CONFLICT(org_id) DO UPDATE SET paused = excluded.paused, updated_at = excluded.updated_at").run(orgId, paused ? 1 : 0, at);
+  }
+}

package/templates/bills-agent/packages/agent-core/src/state-machine.ts

@@ -0,0 +1,146 @@
+/**
+ * Section 4.1: the execution as a closed state machine.
+ *
+ * The transition table is a type. `transition()` only accepts a target that
+ * the table lists for the current state, so a transition outside the table
+ * does not compile; the runtime check below refuses the same pair when the
+ * types were bypassed (a cast, a row read back from SQLite).
+ */
+import type { Actor, ApprovalMode, EscalationTrigger, ExecutionItem, ExecutionReason, ItemOutcome, MandateRef } from "./types.js";
+
+export type ExecutionState =
+  | "drafted"
+  | "awaiting_approval"
+  | "approved"
+  | "executing"
+  | "settled"
+  | "failed"
+  | "denied"
+  | "expired";
+
+/**
+ * The table of section 4.1, plus the two exits section 4.7 adds (revocation
+ * from `drafted` / `approved`) and the return section 4.2 adds (`approved`
+ * back to `awaiting_approval` when the list changed after approval).
+ */
+export type TransitionTable = {
+  drafted: "awaiting_approval" | "approved" | "denied" | "expired";
+  awaiting_approval: "approved" | "denied" | "expired";
+  approved: "executing" | "awaiting_approval" | "denied" | "expired";
+  executing: "settled" | "failed";
+  settled: never;
+  failed: never;
+  denied: never;
+  expired: never;
+};
+
+export type NextState<S extends ExecutionState> = TransitionTable[S];
+
+export const TRANSITIONS: { readonly [S in ExecutionState]: readonly TransitionTable[S][] } = {
+  drafted: ["awaiting_approval", "approved", "denied", "expired"],
+  awaiting_approval: ["approved", "denied", "expired"],
+  approved: ["executing", "awaiting_approval", "denied", "expired"],
+  executing: ["settled", "failed"],
+  settled: [],
+  failed: [],
+  denied: [],
+  expired: [],
+};
+
+export const TERMINAL_STATES: readonly ExecutionState[] = ["settled", "failed", "denied", "expired"];
+
+export function isTerminal(state: ExecutionState): boolean {
+  return TERMINAL_STATES.includes(state);
+}
+
+export interface TransitionRecord {
+  from: ExecutionState;
+  to: ExecutionState;
+  at: string;
+  reason?: ExecutionReason;
+  detail?: string;
+  actor: Actor;
+}
+
+export interface Execution<S extends ExecutionState = ExecutionState> {
+  id: string;
+  run_id: string;
+  state: S;
+  mode: ApprovalMode;
+  /** Who created the execution: always the agent acting for someone. */
+  actor: Actor;
+  items: ExecutionItem[];
+  /** Computed by the core, never by the model. */
+  total: number;
+  currency: string;
+  /** What the model claimed the total was, when it claimed one. Recorded, never used. */
+  model_claimed_total?: number;
+  items_hash: string;
+  mandate: MandateRef;
+  /** Written once, before the rail is called. Retrying reuses it. */
+  idempotency_key: string;
+  approval_id?: string;
+  escalation?: { trigger: EscalationTrigger; detail: string };
+  /** Reasons the core will refuse to approve, even if a human says yes. */
+  blocking_reasons: ExecutionReason[];
+  reason?: ExecutionReason;
+  detail?: string;
+  outcomes: ItemOutcome[];
+  history: TransitionRecord[];
+  created_at: string;
+  updated_at: string;
+}
+
+export class IllegalTransitionError extends Error {
+  constructor(
+    readonly executionId: string,
+    readonly from: ExecutionState,
+    readonly to: ExecutionState,
+  ) {
+    super(`illegal transition ${from} -> ${to} on ${executionId}`);
+    this.name = "IllegalTransitionError";
+  }
+}
+
+export function canTransition(from: ExecutionState, to: ExecutionState): boolean {
+  return (TRANSITIONS[from] as readonly ExecutionState[]).includes(to);
+}
+
+export interface TransitionInput {
+  at: string;
+  actor: Actor;
+  reason?: ExecutionReason;
+  detail?: string;
+}
+
+/**
+ * Move an execution to a state the table allows. Returns a new object with
+ * the transition appended to `history`; the caller persists it.
+ */
+export function transition<S extends ExecutionState, T extends NextState<S>>(
+  execution: Execution<S>,
+  to: T,
+  input: TransitionInput,
+): Execution<T> {
+  if (!canTransition(execution.state, to)) {
+    throw new IllegalTransitionError(execution.id, execution.state, to);
+  }
+  const record: TransitionRecord = {
+    from: execution.state,
+    to,
+    at: input.at,
+    actor: input.actor,
+    ...(input.reason ? { reason: input.reason } : {}),
+    ...(input.detail ? { detail: input.detail } : {}),
+  };
+  // `reason`/`detail` describe the LATEST transition; a step without one clears what the previous step left.
+  const { reason: _reason, detail: _detail, ...rest } = execution;
+  return {
+    ...rest,
+    state: to,
+    ...(input.reason ? { reason: input.reason } : {}),
+    ...(input.detail ? { detail: input.detail } : {}),
+    history: [...execution.history, record],
+    updated_at: input.at,
+  } as Execution<T>;
+}