@codespar/cli 0.17.0 → 0.18.0

package/templates/checkout-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/checkout-agent/packages/agent-core/src/state-machine.ts

@@ -0,0 +1,157 @@
+/**
+ * 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, ExecutionBatch, ExecutionComposition, 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;
+  /** Present when this execution is one line of a batch: the set it was presented inside, and where in it. */
+  batch?: ExecutionBatch;
+  /** Present when this execution's amount is composed of lines (a cart): the lines' hash, not the lines. */
+  composition?: ExecutionComposition;
+  /**
+   * A batch line's attempt generation per item index, when it is not 0: how
+   * many of the line's derived attempt ids the rail answered as spent before
+   * the one this execution presented (`batchAttemptId`). Saved BEFORE the
+   * next id is presented, so a reconcile looks up the id that was sent.
+   */
+  attempt_generations?: Record<number, number>;
+  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>;
+}

package/templates/checkout-agent/packages/agent-core/src/stubs/charge-rail.ts

@@ -0,0 +1,195 @@
+/**
+ * STUB receivable rail. The deterministic stand-in for `POST /v1/charges`
+ * plus the sandbox payer, so the collections scenarios, the adversarial
+ * suite and the restart test run offline. Every issuance is persisted in
+ * state.db before the outcome is returned, so a process killed right after
+ * "the charge was issued" finds it again on `resume`.
+ *
+ * The fixture payer lives in the lookups: the first look after issuance
+ * finds the instrument registered (a cobranca com vencimento answers
+ * PROCESSING at create and PENDING once the clearing house has it), the
+ * second look finds what the payer did: paid (default), let it expire, or
+ * nothing yet. With a real key the scenario runner calls the sandbox pay
+ * route instead; this file never talks to the network.
+ */
+import { sha256Hex } from "../hash.js";
+import type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } from "../rail.js";
+import type { StateStore } from "../state/store.js";
+import type { Actor, ChargeInstrument } from "../types.js";
+
+export type StubPayerBehaviour = "pays" | "expires" | "never";
+
+export interface StubChargeRailOptions {
+  clock?: () => Date;
+  /** What the fixture payer does with a receivable, once it is payable. */
+  payer?: StubPayerBehaviour;
+  /** Debtor documents the issuer refuses (`failed` issuance), to script a partial failure. */
+  refusePayees?: string[];
+  /** Attempt ids whose create answers `uncertain` once (the issuer's answer was lost); the reservation still exists and a later look finds it. */
+  uncertainOnce?: string[];
+  /** Test hook: called after the issuance is persisted and before the outcome is returned. */
+  afterDispatch?: (attemptId: string) => void;
+}
+
+interface PayerState {
+  looks: number;
+  fate: StubPayerBehaviour;
+}
+
+const CURSOR = (attemptId: string) => `stub-charge-payer:${attemptId}`;
+
+export class StubChargeRail implements PaymentRail {
+  readonly name = "stub-charge" as const;
+  private readonly clock: () => Date;
+  private fate: StubPayerBehaviour;
+  private readonly uncertainPending: Set<string>;
+  /** How many NEW receivables pay() issued. */
+  issueCount = 0;
+
+  constructor(
+    private readonly store: StateStore,
+    private readonly options: StubChargeRailOptions = {},
+  ) {
+    this.clock = options.clock ?? (() => new Date());
+    this.fate = options.payer ?? "pays";
+    this.uncertainPending = new Set(options.uncertainOnce ?? []);
+  }
+
+  /** Changes what the fixture payer does with the receivables issued from now on. */
+  setPayer(behaviour: StubPayerBehaviour): void {
+    this.fate = behaviour;
+  }
+
+  /** Scripts the payer for ONE already-issued receivable (a scenario that pays or expires a specific parcel). */
+  decide(attemptId: string, behaviour: StubPayerBehaviour): void {
+    const state = this.payerState(attemptId);
+    this.savePayerState(attemptId, { looks: state?.looks ?? 0, fate: behaviour });
+  }
+
+  async pay(payment: RailPayment): Promise<RailOutcome> {
+    const existing = this.store.stubRailGet(payment.attempt_id);
+    if (existing) return existing.outcome as RailOutcome;
+
+    if (this.uncertainPending.has(payment.attempt_id)) {
+      this.uncertainPending.delete(payment.attempt_id);
+      // The issuer took the create and the answer was lost: the reservation exists, so a later lookup finds it.
+      this.persistIssued(payment, "PROCESSING", false);
+      return { status: "uncertain", code: "issuance_unconfirmed", message: "stub: the issuer's answer to the create was lost; the key is reserved" };
+    }
+
+    const at = this.clock().toISOString();
+    if (this.options.refusePayees?.includes(payment.payee)) {
+      const outcome: RailOutcome = { status: "failed", code: "issuer_refused", message: `stub: issuer refused a charge to ${payment.payee}` };
+      const { actor: _actor, ...request } = payment;
+      this.store.stubRailPut(payment.attempt_id, request, outcome, at);
+      this.options.afterDispatch?.(payment.attempt_id);
+      return outcome;
+    }
+    const outcome = this.persistIssued(payment, "PROCESSING", false);
+    this.options.afterDispatch?.(payment.attempt_id);
+    return outcome;
+  }
+
+  async lookup(attemptId: string, payment: RailPayment): Promise<RailLookup> {
+    const recorded = this.store.stubRailGet(attemptId);
+    if (!recorded) return undefined;
+    const outcome = recorded.outcome as RailOutcome;
+    if (outcome.status !== "accepted") return outcome;
+
+    const state = this.payerState(attemptId) ?? { looks: 0, fate: this.fate };
+    const looks = state.looks + 1;
+    this.savePayerState(attemptId, { ...state, looks });
+
+    // First look: the clearing house registered the instrument. It is payable from here.
+    if (looks === 1 || !outcome.instrument.payable) {
+      return this.update(attemptId, payment, "PENDING", true);
+    }
+    if (state.fate === "pays") {
+      const settled: RailOutcome = {
+        status: "settled",
+        transaction_id: outcome.transaction_id,
+        receipt_id: outcome.transaction_id,
+        money_moved: false,
+        sandbox: true,
+        raw: { stub: true, attempt_id: attemptId, simulated: true, settled_against: "sandbox_fixture", paid_at: this.clock().toISOString() },
+      };
+      this.replace(attemptId, payment, settled);
+      return settled;
+    }
+    if (state.fate === "expires") {
+      const failed: RailOutcome = { status: "failed", code: "charge_expired", message: `stub: the receivable ${outcome.transaction_id} reached its due date unpaid`, raw: { stub: true } };
+      this.replace(attemptId, payment, failed);
+      return failed;
+    }
+    return outcome;
+  }
+
+  async receipt(receiptId: string, actor: Actor): Promise<RailReceipt | undefined> {
+    // The paid charge IS the record: found by its receipt id once the payer acted here, or by its charge id when the settlement came by event.
+    const sealed = this.store.stubRailFindByReceipt(receiptId) ?? this.store.stubRailFindByTransaction(receiptId);
+    if (!sealed) return undefined;
+    const req = sealed.request as Omit<RailPayment, "actor">;
+    const out = sealed.outcome as Extract<RailOutcome, { status: "settled" | "accepted" }>;
+    const raw = out.raw as { paid_at?: string };
+    return {
+      receipt_id: receiptId,
+      kind: "charge",
+      state: "paid",
+      mandate: { id: req.mandate_id },
+      payment: { amount_minor: req.amount_minor, payee: req.payee, attempt_id: req.attempt_id, money_moved: false, sandbox: true, at: raw.paid_at ?? sealed.at },
+      chain: null,
+      receipt_sig: null,
+      receipt_sig_ed25519: null,
+      receipt_sig_kid: null,
+      actor,
+      raw: { stub: true, charge_id: out.transaction_id, simulated: true, settled_against: "sandbox_fixture" },
+    };
+  }
+
+  private instrument(payment: RailPayment, status: string, payable: boolean, chargeId: string): ChargeInstrument {
+    return {
+      payable,
+      status,
+      pix_copy_paste: payable ? `00020126580014br.gov.bcb.pix0136stub-${chargeId}5204000053039865802BR5909CODESPAR6009SAO PAULO62070503***6304STUB` : null,
+      boleto_bank_line: payable ? `${sha256Hex(chargeId).replace(/[a-f]/g, "").padEnd(47, "0").slice(0, 47)}` : null,
+      boleto_bar_code: payable ? `${sha256Hex(`bar:${chargeId}`).replace(/[a-f]/g, "").padEnd(44, "0").slice(0, 44)}` : null,
+      due_date: payment.due_date ?? null,
+    };
+  }
+
+  private persistIssued(payment: RailPayment, status: string, payable: boolean): Extract<RailOutcome, { status: "accepted" }> {
+    const chargeId = `chg_stub_${sha256Hex(payment.attempt_id).slice(0, 16)}`;
+    const outcome: Extract<RailOutcome, { status: "accepted" }> = {
+      status: "accepted",
+      transaction_id: chargeId,
+      instrument: this.instrument(payment, status, payable, chargeId),
+      sandbox: true,
+      raw: { stub: true, attempt_id: payment.attempt_id, issued_at: this.clock().toISOString() },
+    };
+    const { actor: _actor, ...request } = payment;
+    if (this.store.stubRailPut(payment.attempt_id, request, outcome, this.clock().toISOString())) this.issueCount += 1;
+    return outcome;
+  }
+
+  private update(attemptId: string, payment: RailPayment, status: string, payable: boolean): Extract<RailOutcome, { status: "accepted" }> {
+    const recorded = this.store.stubRailGet(attemptId)!;
+    const prior = recorded.outcome as Extract<RailOutcome, { status: "accepted" }>;
+    const outcome = { ...prior, instrument: this.instrument(payment, status, payable, prior.transaction_id) };
+    this.replace(attemptId, payment, outcome);
+    return outcome;
+  }
+
+  private replace(attemptId: string, payment: RailPayment, outcome: RailOutcome): void {
+    const { actor: _actor, ...request } = payment;
+    this.store.stubRailReplace(attemptId, request, outcome, this.clock().toISOString());
+  }
+
+  private payerState(attemptId: string): PayerState | undefined {
+    const raw = this.store.getCursor(CURSOR(attemptId));
+    return raw ? (JSON.parse(raw) as PayerState) : undefined;
+  }
+
+  private savePayerState(attemptId: string, state: PayerState): void {
+    this.store.setCursor(CURSOR(attemptId), JSON.stringify(state));
+  }
+}