@codespar/cli 0.17.0 → 0.18.0

package/templates/checkout-agent/packages/agent-core/src/api/mandate-status.ts

@@ -0,0 +1,74 @@
+/**
+ * Mandate status from the API: `GET /v1/mandates/{id}`, the one registered
+ * spelling of the consumer-allowance point read (the SDK's OpenAPI says the
+ * path has no alias; `/v1/consumers/mandates/{id}` answers 404 on staging,
+ * measured 2026-09-23). Consulted before `executing` (section 4.7), through
+ * the same `csk_test_` client every other call of the kit uses.
+ *
+ * Fail-closed: this source never throws and never assumes. A transport
+ * failure, a timeout, a 404, a 5xx, an unreadable body, a status outside
+ * `active | paused | revoked | expired` or an `org_paused` that is not a
+ * boolean is reported as `unknown`, and the engine executes nothing on
+ * `unknown`.
+ *
+ * The organization kill switch (ent#1648) answers on the same read:
+ * `org_paused` next to `status`, which stays the mandate's own. A missing
+ * `org_paused` is `unknown`, never "not paused": a deployment that cannot
+ * say whether the organization stopped every spend has not said it did not.
+ */
+import type { ApiOperation, ApiSuccess, ApiClient } from "@codespar/sdk";
+import { z } from "zod";
+import type { MandateStatusReport, MandateStatusSource } from "../revocation.js";
+import { describeApiError } from "./client.js";
+
+/** `GET /v1/mandates/{id}` as the SDK's generated OpenAPI types it. */
+type MandateRead = ApiSuccess<ApiOperation<"/v1/mandates/{id}", "get">>;
+
+/**
+ * The three fields the gate reads; the rest is passed through untouched.
+ * Bound to the SDK's type, so a field the API renames or retypes breaks the
+ * compile here instead of reading as absent at run time.
+ */
+const MandateReadSchema = z
+  .object({
+    status: z.enum(["active", "paused", "revoked", "expired"]),
+    expires_at: z.string(),
+    org_paused: z.boolean(),
+  })
+  .passthrough() satisfies z.ZodType<Pick<MandateRead, "status" | "expires_at" | "org_paused">>;
+
+export class ApiMandateStatusSource implements MandateStatusSource {
+  constructor(
+    private readonly api: ApiClient,
+    private readonly clock: () => Date = () => new Date(),
+  ) {}
+
+  async check(mandateId: string): Promise<MandateStatusReport> {
+    const base = { mandate_id: mandateId, org_paused: false, checked_at: this.clock().toISOString(), source: "api" as const };
+    let body: MandateRead;
+    try {
+      body = await this.api.get("/v1/mandates/{id}", { path: { id: mandateId } });
+    } catch (err) {
+      const failure = describeApiError(err);
+      const detail =
+        failure.status === 404
+          ? `the API has no mandate ${mandateId} for this key (${failure.code})`
+          : `GET /v1/mandates/${mandateId} did not answer (${failure.code}): ${failure.message}`;
+      return { ...base, status: "unknown", detail };
+    }
+    // The type says what the API promises; the parse checks that this answer kept the promise.
+    const parsed = MandateReadSchema.safeParse(body);
+    if (!parsed.success) {
+      const unread = parsed.error.issues.map((issue) => issue.path.join(".") || "body");
+      const status = body && typeof body === "object" && "status" in body ? String(body.status) : "missing";
+      const detail = unread.includes("org_paused")
+        ? `GET /v1/mandates/${mandateId} did not say whether the organization is paused (org_paused unreadable)`
+        : `GET /v1/mandates/${mandateId} answered a status this kit does not read (${status})`;
+      return { ...base, status: "unknown", detail };
+    }
+    if (parsed.data.org_paused) return { ...base, org_paused: true, status: parsed.data.status };
+    const expiresAt = new Date(parsed.data.expires_at).getTime();
+    const expired = Number.isFinite(expiresAt) && expiresAt <= this.clock().getTime();
+    return { ...base, status: expired && parsed.data.status === "active" ? "expired" : parsed.data.status };
+  }
+}

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

@@ -0,0 +1,153 @@
+/**
+ * The CodeSpar sandbox rail. With the signed envelope the consent returned
+ * (`mandate.canonical` + `mandate.signature`) it spends through
+ * `POST /v1/consumer-payments/execute`; without it, by mandate id through
+ * `POST /v1/consumers/mandates/{id}/spend`. Idempotence on both is OPT-IN
+ * and keyed on an explicit `attempt_id`, which every payment here carries: a
+ * spend without one is a fresh payment on every request (ent#1671, #1683).
+ * What a repeat of an attempt answers is in `lookup` below. The by-id route answered `bad_signature` on staging for a
+ * mandate carrying `periodic_cap` (OPEN_QUESTIONS §14), which is why the
+ * envelope is preferred when it exists. Receipts come back from
+ * `GET /v1/consumers/receipts/{id}`.
+ *
+ * The API has no `actor` field on the wire today (OPEN_QUESTIONS §2). The
+ * spend carries `agent_id`, which the mandate binds; the full actor is
+ * stamped on the local receipt copy and on every event of the bundle.
+ */
+import type { ApiClient } from "@codespar/sdk";
+import type { Mandate } from "../mandate.js";
+import { checkQuote } from "../quote.js";
+import { checkSpendApproval, type PaymentRail, type RailLookup, type RailOutcome, type RailPayment, type RailReceipt } from "../rail.js";
+import type { Actor } from "../types.js";
+import { describeApiError, isUncertain, type SpendErrorCode } from "./client.js";
+
+/** Another presentation of this attempt is claimed and has no recorded outcome yet: it may be moving money right now. */
+const ATTEMPT_IN_FLIGHT: SpendErrorCode = "psp_attempt_in_flight";
+/** This attempt failed, moved no money and was compensated; the API will never run this id again. */
+const ATTEMPT_SPENT: SpendErrorCode = "psp_attempt_conflict";
+/** This attempt id was already used for a DIFFERENT payment (checked before its state); nothing was held or sent. */
+const ATTEMPT_ID_CONFLICT: SpendErrorCode = "attempt_id_conflict";
+/** Another project of this organization holds this attempt id; opaque by design, nothing was held or sent. */
+const ATTEMPT_ID_UNAVAILABLE: SpendErrorCode = "attempt_id_unavailable";
+
+export class CodeSparRail implements PaymentRail {
+  readonly name = "codespar" as const;
+
+  constructor(
+    private readonly api: ApiClient,
+    private readonly envelope?: Pick<Mandate, "canonical" | "signature"> | undefined,
+  ) {}
+
+  async pay(payment: RailPayment): Promise<RailOutcome> {
+    // Without the quote the sealed receipt names no payee (OPEN_QUESTIONS §18), and the API pays a quote that disagrees. Neither goes out.
+    const quoted = checkQuote(payment);
+    if (!quoted.ok) return { status: "failed", code: quoted.code, message: `${quoted.detail}; nothing was sent` };
+    // Without it the receipt seals no link to what was approved (OPEN_QUESTIONS §3), and the API refuses a malformed one with 400 anyway.
+    const approval = checkSpendApproval(payment);
+    if (!approval.ok) return { status: "failed", code: approval.code, message: `${approval.detail}; nothing was sent` };
+    try {
+      const outcome =
+        this.envelope?.canonical && this.envelope.signature
+          ? await this.api.post("/v1/consumer-payments/execute", {
+              body: {
+                mandate: this.envelope.canonical,
+                signature: this.envelope.signature,
+                amount_minor: payment.amount_minor,
+                purpose: payment.purpose,
+                agent_id: payment.agent_id,
+                payee: payment.payee,
+                attempt_id: payment.attempt_id,
+                quote: quoted.quote,
+                approval: approval.approval,
+              },
+            })
+          : await this.api.post("/v1/consumers/mandates/{id}/spend", {
+              path: { id: payment.mandate_id },
+              body: { amount_minor: payment.amount_minor, payee: payment.payee, agent_id: payment.agent_id, attempt_id: payment.attempt_id, quote: quoted.quote, approval: approval.approval },
+            });
+      return {
+        status: "settled",
+        transaction_id: outcome.payment.transactionId,
+        receipt_id: outcome.receipt?.id ?? null,
+        money_moved: outcome.payment.moneyMoved,
+        sandbox: !outcome.payment.moneyMoved,
+        ...(outcome.idempotent_replay ? { replayed: true as const } : {}),
+        raw: outcome,
+      };
+    } catch (err) {
+      const failure = describeApiError(err);
+      // Not a refusal: the other presentation may already have reached the provider, so "nothing moved" would be a claim nobody can make.
+      if (failure.code === ATTEMPT_IN_FLIGHT) return { status: "uncertain", code: failure.code, message: failure.message };
+      if (isUncertain(failure)) return { status: "uncertain", code: failure.code, message: failure.message };
+      if (failure.code === ATTEMPT_SPENT) return { status: "failed", code: failure.code, message: failure.message, spent: true };
+      // Held, never spent: the id belongs to another payment or another project, so no generation may be derived past it.
+      if (failure.code === ATTEMPT_ID_CONFLICT) return { status: "failed", code: failure.code, message: failure.message, held: "conflict" };
+      if (failure.code === ATTEMPT_ID_UNAVAILABLE) return { status: "failed", code: failure.code, message: failure.message, held: "unavailable" };
+      return { status: "failed", code: failure.code, message: failure.message };
+    }
+  }
+
+  /**
+   * There is no read route for an attempt: the way to learn what became of
+   * one is to present the same `attempt_id`, with the same payment, again.
+   * Against the deployed API (ent#1671, #1683) that call never moves money
+   * for an attempt it already holds, and each answer maps to one reading:
+   *
+   * - settled: `200` with the ORIGINAL body verbatim (same `transactionId`,
+   *   same stored `receipt.id`, which the receipt route resolves) plus
+   *   `idempotent_replay: true`. Read as `settled`, exactly as the first
+   *   answer, and marked `replayed`.
+   * - `psp_attempt_in_flight` (409): claimed, no outcome yet, on every rail.
+   *   Read as `in_flight`; the next reconcile asks again with the SAME id.
+   * - `psp_attempt_uncertain` (409): pinned, dispatch outcome unknown. Read as
+   *   `uncertain`, which leaves the execution open for a person.
+   * - `psp_attempt_conflict` (409): failed, compensated, no money. Read as
+   *   `failed` and `spent`.
+   * - `attempt_id_conflict` / `attempt_id_unavailable` (409): the id is held for
+   *   a different payment, or by another project. Read as `failed` and `held`,
+   *   never `spent`: nothing was held or sent by this call. Neither can come from re-presenting the
+   *   payment this execution sent, whose tuple is the one the id was claimed
+   *   with, so seeing one here is a defect worth its readable failure.
+   * - an attempt the API never took: there is no record to answer from, so
+   *   this call IS the payment. Reconcile runs only after the outbox row
+   *   flipped to `sent`, so an attempt it looks up was presented once already.
+   */
+  async lookup(_attemptId: string, payment: RailPayment): Promise<RailLookup> {
+    const outcome = await this.pay(payment);
+    if (outcome.status === "uncertain" && outcome.code === ATTEMPT_IN_FLIGHT) return { status: "in_flight" };
+    return outcome;
+  }
+
+  async receipt(receiptId: string, actor: Actor): Promise<RailReceipt | undefined> {
+    try {
+      const r = await this.api.get("/v1/consumers/receipts/{id}", { path: { id: receiptId } });
+      return {
+        receipt_id: r.receipt_id,
+        state: r.state,
+        mandate: { id: r.mandate.id, sig_sha256: r.mandate.sig_sha256 },
+        chain_version: r.chain_version,
+        approval: r.approval ?? null,
+        payment: {
+          amount_minor: r.payment.amount_minor,
+          payee: r.quote?.payee ?? null,
+          attempt_id: r.payment.attempt_id,
+          money_moved: r.payment.money_moved,
+          sandbox: r.payment.sandbox === true,
+          at: r.payment.at,
+        },
+        chain: r.chain,
+        receipt_sig: r.receipt_sig,
+        // `||`, not `??`: a deployment older than ent#1633 omits both fields,
+        // and an empty string is no signature either. Both read as `unsigned`.
+        receipt_sig_ed25519: r.receipt_sig_ed25519 || null,
+        receipt_sig_kid: r.receipt_sig_kid || null,
+        actor,
+        raw: r,
+      };
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (failure.status === 404) return undefined;
+      throw err;
+    }
+  }
+}

package/templates/checkout-agent/packages/agent-core/src/api/sandbox-payer.ts

@@ -0,0 +1,43 @@
+/**
+ * The sandbox PAYER: `POST /v1/test/charges/{chargeId}/pay` (alias
+ * `POST /v1/charges/{chargeId}/sandbox/pay`), test environment only. It
+ * plays the debtor: the charge goes through the same settlement path a
+ * provider `charge-in` webhook takes, `commerce.charge.paid` fans out to the
+ * project's triggers, and every record it leaves carries `simulated: true`
+ * plus `settled_against: "sandbox_fixture"`. No money moves anywhere. A
+ * live-environment key is refused with `sandbox_pay_not_permitted` before
+ * anything is read. Since `@codespar/sdk@0.16.5` the route is in the SDK's
+ * OpenAPI document, so this is the client's own typed call (same base URL,
+ * key and project header as every other call); until 0.16.4 it was a plain
+ * `fetch`, see docs/OPEN_QUESTIONS.md section 31c. The key is checked for
+ * the `csk_test_` prefix before a client exists, like every other call.
+ */
+import { ApiClient, type ApiOperation, type ApiSuccess } from "@codespar/sdk";
+import type { ApiFailure } from "./client.js";
+import { createCodeSparClient, describeApiError } from "./client.js";
+
+/** What the payer route answers, as the SDK's generated OpenAPI types it. */
+export type SandboxPaidState = ApiSuccess<ApiOperation<"/v1/test/charges/{chargeId}/pay", "post">>;
+
+export type SandboxPayResult = { ok: true; state: SandboxPaidState } | { ok: false; failure: ApiFailure };
+
+/** Where the payer route lives when no client exists yet: the same three things `createCodeSparClient` takes. */
+export interface SandboxPayerTarget {
+  apiKey: string | undefined;
+  baseUrl?: string | undefined;
+  projectId?: string | undefined;
+  timeoutMs?: number;
+}
+
+export async function paySandboxCharge(target: ApiClient | SandboxPayerTarget, chargeRef: string, amountMinor?: number): Promise<SandboxPayResult> {
+  const api = target instanceof ApiClient ? target : createCodeSparClient(target);
+  try {
+    const state = await api.post("/v1/test/charges/{chargeId}/pay", {
+      path: { chargeId: chargeRef },
+      body: amountMinor !== undefined ? { amount_minor: amountMinor } : {},
+    });
+    return { ok: true, state };
+  } catch (err) {
+    return { ok: false, failure: describeApiError(err) };
+  }
+}

package/templates/checkout-agent/packages/agent-core/src/approval.ts

@@ -0,0 +1,135 @@
+/**
+ * Section 4.2: the approval artifact.
+ *
+ * STUB, on purpose: the artifact is signed with a LOCAL development key
+ * (`.codespar/approval.key`, generated on first use, never committed). The
+ * CodeSpar API does not sign approval lists; its HMAC is the mandate proof
+ * and the receipt seal. Until an API-side signature exists the artifact
+ * proves what was approved to whoever runs the agent, and to nobody else.
+ * See docs/OPEN_QUESTIONS.md.
+ */
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { canonicalJson, hexEqual, hmacSha256Hex, itemsHash } from "./hash.js";
+import type { Execution } from "./state-machine.js";
+import type { Actor, ApprovalArtifact, EscalationTrigger, ExecutionBatch, ExecutionComposition } from "./types.js";
+import { newId } from "./ids.js";
+
+export const APPROVAL_KEY_ID = "local-dev-stub";
+export const DEFAULT_APPROVAL_TTL_MS = 15 * 60 * 1000;
+
+export interface ApprovalSigner {
+  keyId: string;
+  sign(payload: string): string;
+  verify(payload: string, signature: string): boolean;
+}
+
+export function loadOrCreateLocalApprovalKey(stateDir: string): ApprovalSigner {
+  const path = join(stateDir, "approval.key");
+  let key: Buffer;
+  if (existsSync(path)) {
+    key = Buffer.from(readFileSync(path, "utf8").trim(), "hex");
+  } else {
+    mkdirSync(dirname(path), { recursive: true });
+    key = randomBytes(32);
+    writeFileSync(path, key.toString("hex") + "\n", { mode: 0o600 });
+    chmodSync(path, 0o600);
+  }
+  return hmacSigner(APPROVAL_KEY_ID, key);
+}
+
+export function hmacSigner(keyId: string, key: Buffer): ApprovalSigner {
+  return {
+    keyId,
+    sign: (payload) => hmacSha256Hex(key, payload),
+    verify: (payload, signature) => hexEqual(hmacSha256Hex(key, payload), signature),
+  };
+}
+
+function unsignedPayload(artifact: Omit<ApprovalArtifact, "signature">): string {
+  return canonicalJson(artifact);
+}
+
+export interface CreateApprovalInput {
+  execution: Execution;
+  approver: ApprovalArtifact["approver"];
+  actor: Actor;
+  now: Date;
+  ttlMs?: number;
+  escalation?: { trigger: EscalationTrigger; detail: string };
+}
+
+export function createApprovalArtifact(signer: ApprovalSigner, input: CreateApprovalInput): ApprovalArtifact {
+  const { execution } = input;
+  const approvedAt = input.now.toISOString();
+  const expiresAt = new Date(input.now.getTime() + (input.ttlMs ?? DEFAULT_APPROVAL_TTL_MS)).toISOString();
+  const unsigned: Omit<ApprovalArtifact, "signature"> = {
+    approval_id: newId("apr"),
+    execution_id: execution.id,
+    mode: execution.mode,
+    approver: input.approver,
+    approved_at: approvedAt,
+    expires_at: expiresAt,
+    mandate: execution.mandate,
+    items: execution.items,
+    items_hash: itemsHash(execution.items),
+    // The SET this line belongs to, when it belongs to one. Omitted — never
+    // null — on an execution that is not part of a batch, so the payload a
+    // bills-agent artifact signs is unchanged by this field existing.
+    ...(execution.batch ? { batch: execution.batch } : {}),
+    // What the single amount was composed of, when it was composed of lines. Same rule as `batch`: omitted, never null.
+    ...(execution.composition ? { composition: execution.composition } : {}),
+    ...(input.escalation ? { escalation: input.escalation } : {}),
+    actor: input.actor,
+  };
+  return {
+    ...unsigned,
+    signature: { alg: "HMAC-SHA256", key_id: signer.keyId, value: signer.sign(unsignedPayload(unsigned)) },
+  };
+}
+
+export type ApprovalCheck =
+  | { ok: true }
+  | { ok: false; problem: "signature_invalid" | "items_hash_mismatch" | "expired" | "wrong_execution" | "wrong_mandate" | "batch_mismatch" | "composition_mismatch" };
+
+/** Two batch bindings are the same binding, or one is absent and so is the other. */
+function sameBatch(a: ExecutionBatch | undefined, b: ExecutionBatch | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  return a.ref === b.ref && a.batch_hash === b.batch_hash && a.index === b.index && a.count === b.count;
+}
+
+/** Two compositions are the same binding, or one is absent and so is the other. */
+function sameComposition(a: ExecutionComposition | undefined, b: ExecutionComposition | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  return a.ref === b.ref && a.composition_hash === b.composition_hash && a.line_count === b.line_count;
+}
+
+/**
+ * The rule that makes the artifact proof: before `executing`, recompute the
+ * hash of what is about to be executed and compare it with the artifact.
+ */
+export function checkApprovalArtifact(
+  signer: ApprovalSigner,
+  artifact: ApprovalArtifact,
+  execution: Execution,
+  now: Date,
+): ApprovalCheck {
+  const { signature, ...unsigned } = artifact;
+  if (!signer.verify(unsignedPayload(unsigned), signature.value)) return { ok: false, problem: "signature_invalid" };
+  if (artifact.execution_id !== execution.id) return { ok: false, problem: "wrong_execution" };
+  if (artifact.mandate.id !== execution.mandate.id || artifact.mandate.version !== execution.mandate.version) {
+    return { ok: false, problem: "wrong_mandate" };
+  }
+  if (itemsHash(execution.items) !== artifact.items_hash) return { ok: false, problem: "items_hash_mismatch" };
+  // The line's own list is attested by the hash above; this is the list the
+  // line was one OF. An execution that gained, lost or moved its place in a
+  // batch after approval is not the one that was approved.
+  if (!sameBatch(artifact.batch, execution.batch)) return { ok: false, problem: "batch_mismatch" };
+  // The item's amount is attested above; this is what that amount was made of.
+  // A cart recomposed at a constant total leaves `items_hash` unchanged and
+  // this hash changed, and that is the only thing that sees it.
+  if (!sameComposition(artifact.composition, execution.composition)) return { ok: false, problem: "composition_mismatch" };
+  if (new Date(artifact.expires_at).getTime() <= now.getTime()) return { ok: false, problem: "expired" };
+  return { ok: true };
+}

package/templates/checkout-agent/packages/agent-core/src/bundle.ts

@@ -0,0 +1,191 @@
+/**
+ * Section 11: the proof bundle, one folder per run under `runs/<run-id>/`.
+ * It answers "why could the agent pay this". It holds no key and no secret;
+ * payee keys are masked the way a bank statement masks them.
+ */
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { canonicalJson } from "./hash.js";
+import type { Mandate } from "./mandate.js";
+import type { RailReceipt } from "./rail.js";
+import type { ApprovalArtifact } from "./types.js";
+
+export interface TranscriptLine {
+  at: string;
+  kind: "user" | "assistant_step" | "tool_call" | "tool_result" | "assistant" | "system";
+  [key: string]: unknown;
+}
+
+export class ProofBundle {
+  readonly dir: string;
+
+  constructor(
+    runsDir: string,
+    readonly runId: string,
+  ) {
+    this.dir = join(runsDir, runId);
+    mkdirSync(join(this.dir, "receipts"), { recursive: true });
+  }
+
+  static open(runsDir: string, runId: string): ProofBundle | undefined {
+    return existsSync(join(runsDir, runId)) ? new ProofBundle(runsDir, runId) : undefined;
+  }
+
+  transcript(line: TranscriptLine): void {
+    appendFileSync(join(this.dir, "transcript.jsonl"), JSON.stringify(line) + "\n");
+  }
+
+  readTranscript(): TranscriptLine[] {
+    const path = join(this.dir, "transcript.jsonl");
+    if (!existsSync(path)) return [];
+    return readFileSync(path, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => JSON.parse(l) as TranscriptLine);
+  }
+
+  event(event: Record<string, unknown>): void {
+    appendFileSync(join(this.dir, "events.jsonl"), JSON.stringify(event) + "\n");
+  }
+
+  /**
+   * The conversation, when the run had one: every message in and out of a
+   * channel, in order, with what the channel did with it. Separate from the
+   * transcript, which is the MODEL's side, because on a channel the two are
+   * not the same thing — a message the channel refused never reached the
+   * person, and the QR and the copy-and-paste were sent by the runner.
+   *
+   * It carries no contact in the clear: the channel masks it before it gets
+   * here, because the bundle travels.
+   */
+  channel(line: Record<string, unknown>): void {
+    appendFileSync(join(this.dir, "channel.jsonl"), JSON.stringify(line) + "\n");
+  }
+
+  readChannel(): Record<string, unknown>[] {
+    const path = join(this.dir, "channel.jsonl");
+    if (!existsSync(path)) return [];
+    return readFileSync(path, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => JSON.parse(l) as Record<string, unknown>);
+  }
+
+  readEvents(): Record<string, unknown>[] {
+    const path = join(this.dir, "events.jsonl");
+    if (!existsSync(path)) return [];
+    return readFileSync(path, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => JSON.parse(l) as Record<string, unknown>);
+  }
+
+  /** `approval.json` is the list of artifacts of this run, in approval order. */
+  approval(artifact: ApprovalArtifact): void {
+    const path = join(this.dir, "approval.json");
+    const current: ApprovalArtifact[] = existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as ApprovalArtifact[]) : [];
+    if (!current.some((a) => a.approval_id === artifact.approval_id)) current.push(artifact);
+    writeFileSync(path, JSON.stringify(current, null, 2) + "\n");
+  }
+
+  readApprovals(): ApprovalArtifact[] {
+    const path = join(this.dir, "approval.json");
+    return existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as ApprovalArtifact[]) : [];
+  }
+
+  mandateSnapshot(mandate: Mandate): void {
+    const { signature: _signature, canonical: _canonical, ...safe } = mandate;
+    writeFileSync(join(this.dir, "mandate.snapshot.json"), JSON.stringify({ ...safe, beneficiaries: safe.beneficiaries.map((b) => ({ ...b, payee: maskPayee(b.payee) })), merchant_allowlist: safe.merchant_allowlist.map(maskPayee) }, null, 2) + "\n");
+  }
+
+  /**
+   * Returns the path INSIDE the bundle (`receipts/<id>.json`): a bundle travels, and an absolute path names the machine that wrote it.
+   *
+   * `approval_id` names the artifact in `approval.json` whose hashes the spend carried, so `npm run verify` holds the receipt's sealed
+   * approval link against THAT artifact, found by identity and never by looking for one whose hash happens to match. The copy stays
+   * masked: binding its body to the chain needs the unmasked read, which `verify --from-api` takes from the API and writes nowhere.
+   */
+  receipt(receipt: RailReceipt, context: { approval_id?: string | undefined } = {}): string {
+    const relative = join("receipts", `${receipt.receipt_id}.json`);
+    const { raw: _raw, ...safe } = receipt;
+    const copy = { ...safe, payment: { ...safe.payment, payee: safe.payment.payee ? maskPayee(safe.payment.payee) : null }, ...(context.approval_id ? { approval_id: context.approval_id } : {}) };
+    writeFileSync(join(this.dir, relative), JSON.stringify(copy, null, 2) + "\n");
+    return relative;
+  }
+
+  /** The masked mandate as it stood when the run started. Absent on a bundle whose run never got that far. */
+  readMandateSnapshot(): Record<string, unknown> | undefined {
+    const path = join(this.dir, "mandate.snapshot.json");
+    return existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>) : undefined;
+  }
+
+  /** One receipt by its file name, as `listReceipts()` returns it. */
+  readReceipt(file: string): Record<string, unknown> | undefined {
+    const path = join(this.dir, "receipts", basename(file));
+    return existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>) : undefined;
+  }
+
+  /**
+   * Section 11: `verify.json` is the output of `codespar audit replay`, which
+   * is not a registered command of the CLI, so nothing here writes it and
+   * nothing here reimplements the hash-chain check. The reader exists so a
+   * bundle that gains one later is noticed rather than ignored.
+   */
+  hasVerify(): boolean {
+    return existsSync(join(this.dir, "verify.json"));
+  }
+
+  listReceipts(): string[] {
+    const dir = join(this.dir, "receipts");
+    if (!existsSync(dir)) return [];
+    return readdirSorted(dir);
+  }
+
+  meta(meta: Record<string, unknown>): void {
+    writeFileSync(join(this.dir, "run.json"), JSON.stringify(meta, null, 2) + "\n");
+  }
+
+  readMeta(): Record<string, unknown> | undefined {
+    const path = join(this.dir, "run.json");
+    return existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>) : undefined;
+  }
+}
+
+function readdirSorted(dir: string): string[] {
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".json"))
+    .sort();
+}
+
+/**
+ * Where the bundle's masked copy of a receipt says something the API's read of the same receipt does not. The copy is not what the
+ * signature covers, so a copy edited after the fact still verifies at the signature level; this is what catches it once the read is
+ * in hand. The payee is compared masked, the only form the copy holds. An empty list means the copy is a faithful mask of the read.
+ */
+export function copyDisagreesWithRead(copy: Record<string, unknown>, read: Record<string, unknown>): string[] {
+  const field = (o: unknown, k: string): unknown => (o && typeof o === "object" ? (o as Record<string, unknown>)[k] : undefined);
+  const readPayee = field(read["quote"], "payee");
+  const expected: Array<[string, unknown, unknown]> = [
+    ["receipt_id", copy["receipt_id"], read["receipt_id"]],
+    ["chain", copy["chain"], read["chain"]],
+    ["mandate.id", field(copy["mandate"], "id"), field(read["mandate"], "id")],
+    ["payment.amount_minor", field(copy["payment"], "amount_minor"), field(read["payment"], "amount_minor")],
+    ["payment.attempt_id", field(copy["payment"], "attempt_id"), field(read["payment"], "attempt_id")],
+    ["payment.money_moved", field(copy["payment"], "money_moved"), field(read["payment"], "money_moved")],
+    ["payment.at", field(copy["payment"], "at"), field(read["payment"], "at")],
+    ["payment.payee", field(copy["payment"], "payee"), typeof readPayee === "string" ? maskPayee(readPayee) : null],
+  ];
+  // Written onto the copy since the rail reads them through the SDK's types (0.16.10); a copy from before carries neither, and is not faulted for it.
+  if ("chain_version" in copy) expected.push(["chain_version", copy["chain_version"], read["chain_version"]]);
+  if ("approval" in copy) expected.push(["approval", canonicalJson(copy["approval"] ?? null), canonicalJson(read["approval"] ?? null)]);
+  return expected.filter(([, a, b]) => a !== b).map(([name]) => name);
+}
+
+/** `escola@exemplo.com.br` -> `es***@exemplo.com.br`; `+5511999998888` -> `+55***8888`; a UUID keeps its first and last 4. */
+export function maskPayee(payee: string): string {
+  if (payee === "*") return payee;
+  const at = payee.indexOf("@");
+  if (at > 0) return `${payee.slice(0, Math.min(2, at))}***${payee.slice(at)}`;
+  if (payee.length <= 8) return `${payee.slice(0, 2)}***`;
+  return `${payee.slice(0, 4)}***${payee.slice(-4)}`;
+}