@codespar/cli 0.14.1 → 0.16.0

package/templates/supplier-payments-agent/packages/agent-core/src/api/client.ts

@@ -0,0 +1,53 @@
+/**
+ * The one place the kit talks to the CodeSpar API. The key is checked for
+ * the `csk_test_` prefix before the client is built, so no live key ever
+ * reaches the network from this repository.
+ */
+import { ApiClient, CodesparApiError, TimeoutError } from "@codespar/sdk";
+import { assertTestKey } from "../secrets.js";
+
+export const DEFAULT_BASE_URL = "https://api.codespar.dev";
+
+export interface CodeSparClientOptions {
+  apiKey: string | undefined;
+  baseUrl?: string | undefined;
+  projectId?: string | undefined;
+  timeoutMs?: number;
+}
+
+export function createCodeSparClient(options: CodeSparClientOptions): ApiClient {
+  const apiKey = assertTestKey(options.apiKey);
+  return new ApiClient({
+    baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+    apiKey,
+    ...(options.projectId ? { projectId: options.projectId } : {}),
+    timeout: options.timeoutMs ?? 30_000,
+  });
+}
+
+export interface ApiFailure {
+  status: number;
+  code: string;
+  message: string;
+  body?: unknown;
+}
+
+/** Normalise the SDK's two error classes into one readable shape without leaking the body into logs. */
+export function describeApiError(err: unknown): ApiFailure {
+  if (err instanceof TimeoutError) return { status: 0, code: "timeout", message: `request timed out after ${err.timeoutMs}ms` };
+  if (err instanceof CodesparApiError) {
+    const body = err.body as { error?: { code?: string; message?: string } } | undefined;
+    return {
+      status: err.status,
+      code: err.code ?? body?.error?.code ?? (err.status === 0 ? "network" : `http_${err.status}`),
+      message: body?.error?.message ?? err.message,
+      body: err.body,
+    };
+  }
+  return { status: 0, code: "unknown", message: err instanceof Error ? err.message : String(err) };
+}
+
+/** 5xx, timeouts and `psp_dispatch_uncertain` mean "the money may have moved". */
+export function isUncertain(failure: ApiFailure): boolean {
+  return failure.status === 0 || failure.status >= 500 || failure.code === "psp_dispatch_uncertain" || failure.code === "psp_attempt_uncertain";
+}

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

@@ -0,0 +1,58 @@
+/**
+ * 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 or a status outside
+ * `active | paused | revoked | expired` is reported as `unknown`, and the
+ * engine executes nothing on `unknown`.
+ *
+ * The organization kill switch (`org pauseAll`) has no API surface, so
+ * `org_paused` is `false` here: the API cannot say it, and this source does
+ * not invent it.
+ */
+import type { ApiClient } from "@codespar/sdk";
+import { z } from "zod";
+import type { MandateStatusReport, MandateStatusSource } from "../revocation.js";
+import { describeApiError } from "./client.js";
+
+/** The two fields of the 14-field projection the gate reads; the rest is passed through untouched. */
+const MandateReadSchema = z
+  .object({
+    status: z.enum(["active", "paused", "revoked", "expired"]),
+    expires_at: z.string(),
+  })
+  .passthrough();
+
+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: unknown;
+    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 };
+    }
+    const parsed = MandateReadSchema.safeParse(body);
+    if (!parsed.success) {
+      const status = body && typeof body === "object" && "status" in body ? String((body as { status: unknown }).status) : "missing";
+      return { ...base, status: "unknown", detail: `GET /v1/mandates/${mandateId} answered a status this kit does not read (${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/supplier-payments-agent/packages/agent-core/src/api/rail.ts

@@ -0,0 +1,117 @@
+/**
+ * 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`. Both are idempotent on
+ * `attempt_id`. 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 type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } from "../rail.js";
+import type { Actor } from "../types.js";
+import { describeApiError, isUncertain } from "./client.js";
+
+/** The asymmetric seal as the API serves it, or nulls when this deployment
+ *  does not serve one. Never throws on a shape it does not recognise: a
+ *  receipt is evidence of a payment that already happened, and refusing to
+ *  record it over an unexpected field would trade the record for the proof. */
+function readEd25519Seal(body: unknown): { receipt_sig_ed25519: string | null; receipt_sig_kid: string | null } {
+  const r = body as { receipt_sig_ed25519?: unknown; receipt_sig_kid?: unknown };
+  const str = (v: unknown): string | null => (typeof v === "string" && v.length > 0 ? v : null);
+  return { receipt_sig_ed25519: str(r.receipt_sig_ed25519), receipt_sig_kid: str(r.receipt_sig_kid) };
+}
+
+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> {
+    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,
+              },
+            })
+          : 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 },
+            });
+      return {
+        status: "settled",
+        transaction_id: outcome.payment.transactionId,
+        receipt_id: outcome.receipt?.id ?? null,
+        money_moved: outcome.payment.moneyMoved,
+        sandbox: !outcome.payment.moneyMoved,
+        raw: outcome,
+      };
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (isUncertain(failure)) return { status: "uncertain", code: failure.code, message: failure.message };
+      return { status: "failed", code: failure.code, message: failure.message };
+    }
+  }
+
+  /**
+   * There is no read route for an attempt. The documented way is to present
+   * the same `attempt_id` again: the lifecycle is idempotent on it and
+   * answers the state it reached. `psp_attempt_in_flight` means the first
+   * presentation is still running.
+   */
+  async lookup(_attemptId: string, payment: RailPayment): Promise<RailLookup> {
+    const outcome = await this.pay(payment);
+    if (outcome.status === "failed" && outcome.code === "psp_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 },
+        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,
+        // ent#1633 landed after `@codespar/sdk@0.16.6` was generated, so the
+        // typed response does not carry these two yet. Read off the body
+        // defensively rather than pinning a new SDK for two nullable strings:
+        // a deployment that predates the change answers null, which is the
+        // same answer the columns hold and reads as `unsigned`.
+        ...readEd25519Seal(r),
+        actor,
+        raw: r,
+      };
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (failure.status === 404) return undefined;
+      throw err;
+    }
+  }
+}

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

@@ -0,0 +1,58 @@
+/**
+ * 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 } from "@codespar/sdk";
+import type { ApiFailure } from "./client.js";
+import { createCodeSparClient, describeApiError } from "./client.js";
+
+export interface SandboxPaidState {
+  charge_id: string;
+  status: "paid";
+  local_status: string;
+  currency: string;
+  quoted_minor: number;
+  paid_minor: number;
+  payment: "full" | "partial" | "over";
+  paid_via: string;
+  wallet_id: string;
+  ledger_entry_id: string | null;
+  event: { id: string; type: string } | null;
+  simulated: boolean;
+  settled_against: string | null;
+  money_moved: false;
+  idempotent_replay: boolean;
+}
+
+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/supplier-payments-agent/packages/agent-core/src/approval.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 } 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 } : {}),
+    ...(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" };
+
+/** 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;
+}
+
+/**
+ * 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" };
+  if (new Date(artifact.expires_at).getTime() <= now.getTime()) return { ok: false, problem: "expired" };
+  return { ok: true };
+}

package/templates/supplier-payments-agent/packages/agent-core/src/bundle.ts

@@ -0,0 +1,159 @@
+/**
+ * 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 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. */
+  receipt(receipt: RailReceipt): string {
+    const relative = join("receipts", `${receipt.receipt_id}.json`);
+    const { raw: _raw, ...safe } = receipt;
+    writeFileSync(join(this.dir, relative), JSON.stringify({ ...safe, payment: { ...safe.payment, payee: safe.payment.payee ? maskPayee(safe.payment.payee) : null } }, 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();
+}
+
+/** `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)}`;
+}