@codespar/cli 0.17.0 → 0.18.0

package/templates/checkout-agent/packages/agent-core/src/providers/types.ts

@@ -0,0 +1,39 @@
+/**
+ * Section 13: the contract of the harness file. Policy stays outside the
+ * provider: the state machine, the mandate, the guardrails and `tools.json`
+ * are the core's. Changing the model changes nothing about what can be paid.
+ */
+export interface ToolSpec {
+  name: string;
+  description: string;
+  input_schema: Record<string, unknown>;
+}
+
+export interface ToolCall {
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+
+export interface Reply {
+  text: string;
+}
+
+export type ConversationMessage =
+  | { role: "user"; content: string }
+  | { role: "assistant"; content: string; tool_calls?: ToolCall[] }
+  | { role: "tool"; tool_call_id: string; name: string; content: string; is_error?: boolean };
+
+export interface Turn {
+  system: string;
+  messages: ConversationMessage[];
+}
+
+export interface AgentRuntime {
+  readonly name: string;
+  step(input: Turn, tools: ToolSpec[]): Promise<ToolCall[] | Reply>;
+}
+
+export function isReply(out: ToolCall[] | Reply): out is Reply {
+  return !Array.isArray(out);
+}

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

@@ -0,0 +1,50 @@
+/**
+ * The offer a spend presents to the API (`SpendQuote`): seller, resource,
+ * price and payee. When a spend carries one, the API binds it into the
+ * receipt's chain between the mandate and the payment, so the sealed receipt
+ * names the payee; without one the chain carries no payee at all, and
+ * `GET /v1/consumers/receipts/{id}` answers `quote: null` (OPEN_QUESTIONS §18).
+ *
+ * The quote is built from the approval artifact's items, the list its
+ * `items_hash` covers, and from nothing the model says after approval. The
+ * API compares the quote to what settled in OBSERVE mode only: a divergence is
+ * recorded on the receipt and the money still moves. So the kit refuses a
+ * divergence itself, before the call.
+ */
+import type { ApprovalArtifact } from "./types.js";
+
+export interface SpendQuote {
+  seller: string;
+  resource: string;
+  price_minor: number;
+  payee: string;
+  /**
+   * When the offer was approved: the artifact's `approved_at`. Absent on a
+   * batch line, whose quote must be the same on every run of the list: the
+   * API compares the quote's digest on a repeat of an `attempt_id`, so an
+   * approval time in it would make the same line a different payment on
+   * every machine (OPEN_QUESTIONS §39c). The time is still in the artifact.
+   */
+  at?: string;
+}
+
+/**
+ * The quote for line `index` of what was approved, or undefined when the
+ * artifact has no such line. `stable` leaves the approval time out, for a
+ * batch line (see `SpendQuote.at`).
+ */
+export function quoteFromApproval(artifact: ApprovalArtifact, index: number, purpose: string, options: { stable?: boolean } = {}): SpendQuote | undefined {
+  const item = artifact.items[index];
+  if (!item) return undefined;
+  const quote = { seller: item.beneficiary, resource: item.description ?? purpose, price_minor: item.amount, payee: item.payee };
+  return options.stable ? quote : { ...quote, at: artifact.approved_at };
+}
+
+/** The quote a spend presents, or why it may not go out: none, or one that does not name exactly the amount and the payee it pays. */
+export function checkQuote(payment: { amount_minor: number; payee: string; quote?: SpendQuote | undefined }): { ok: true; quote: SpendQuote } | { ok: false; code: "quote_missing" | "quote_mismatch"; detail: string } {
+  const { quote } = payment;
+  if (!quote) return { ok: false, code: "quote_missing", detail: "a spend carries the quote of what was approved, or it does not go out" };
+  if (quote.price_minor !== payment.amount_minor) return { ok: false, code: "quote_mismatch", detail: `the approved price ${quote.price_minor} is not the amount ${payment.amount_minor} about to be spent` };
+  if (quote.payee !== payment.payee) return { ok: false, code: "quote_mismatch", detail: "the approved payee is not the payee about to be paid" };
+  return { ok: true, quote };
+}

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

@@ -0,0 +1,186 @@
+/**
+ * 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. Idempotence is OPT-IN on the API and the core always opts in:
+ * every payment carries an explicit `attempt_id`, and presenting the same
+ * attempt again answers from the rail's record of it instead of paying twice
+ * (ent#1671): the original outcome when it settled, "still running" while it
+ * is in flight, "unknown, reconcile" while it is pinned, and a refusal when
+ * the same id arrives with a different payment. A payment sent WITHOUT an id
+ * is a new payment every time; nothing here sends one.
+ */
+import type { ApiOperation, ApiRequestBody } from "@codespar/sdk";
+import type { SpendQuote } from "./quote.js";
+import type { Actor, ApprovalArtifact, ChargeInstrument } from "./types.js";
+
+/**
+ * The `approval` a spend presents (`SpendApproval` in the API's document,
+ * typed since @codespar/sdk 0.16.10): `sha256:<64 lowercase hex>`, as
+ * `itemsHash` and `batchHash` write it. Taken from the SDK so a change on
+ * the API's side fails `tsc` here.
+ */
+export type SpendApproval = NonNullable<ApiRequestBody<ApiOperation<"/v1/consumer-payments/execute", "post">>["approval"]>;
+
+/** What a receipt says it SEALED as the approval link: `batch_hash` is null when the spend sent none. */
+export interface SealedSpendApproval {
+  items_hash: string;
+  batch_hash: string | null;
+}
+
+/** The hashes of what was approved, for a spend of any line of this artifact: the ones the artifact's own HMAC covers. */
+export function spendApprovalOf(artifact: Pick<ApprovalArtifact, "items_hash" | "batch">): SpendApproval {
+  return { items_hash: artifact.items_hash, ...(artifact.batch ? { batch_hash: artifact.batch.batch_hash } : {}) };
+}
+
+const APPROVAL_HASH = /^(sha256:)?[0-9a-f]{64}$/;
+
+/**
+ * The approval a spend presents, or why it may not go out: none, or a hash
+ * the API would refuse (`invalid_approval_hash`: lowercase hex SHA-256, the
+ * `sha256:` prefix optional). The shape and never the content, like the API:
+ * WHICH list is the artifact's business, checked before `executing`.
+ */
+export function checkSpendApproval(payment: { approval?: SpendApproval | undefined }): { ok: true; approval: SpendApproval } | { ok: false; code: "approval_missing" | "approval_malformed"; detail: string } {
+  const { approval } = payment;
+  if (!approval) return { ok: false, code: "approval_missing", detail: "a spend carries the hashes of the approval artifact, or it does not go out" };
+  if (!APPROVAL_HASH.test(approval.items_hash)) return { ok: false, code: "approval_malformed", detail: "the approval's items_hash is not a lowercase hex SHA-256" };
+  if (approval.batch_hash !== undefined && !APPROVAL_HASH.test(approval.batch_hash)) return { ok: false, code: "approval_malformed", detail: "the approval's batch_hash is not a lowercase hex SHA-256" };
+  return { ok: true, approval };
+}
+
+export interface RailPayment {
+  attempt_id: string;
+  mandate_id: string;
+  amount_minor: number;
+  currency: string;
+  payee: string;
+  purpose: string;
+  agent_id: string;
+  /** The principal the agent acts for (the mandate's `consumer_id`). A receivable settles into THIS identity's account; `POST /v1/charges` needs it on the wire. */
+  consumer_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;
+  /** What was approved for this line, presented with a spend so the sealed receipt names the payee. A charge rail ignores it. */
+  quote?: SpendQuote;
+  /**
+   * The approval artifact's hashes, exactly as the artifact carries them: its
+   * `items_hash`, and for a batch line its `batch.batch_hash`. The API seals
+   * them into the receipt's chain as a link of their own (chain v4,
+   * ent#1670), so whoever holds the receipt read can show THIS payment was
+   * sealed against THAT list. It is the caller's claim, sealed: the API checks
+   * its shape and never its content. A charge rail ignores it.
+   */
+  approval?: SpendApproval;
+  /** 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;
+      /**
+       * The rail answered from its record of an attempt that had ALREADY
+       * settled (`idempotent_replay`, ent#1671): every other field is the
+       * original answer, and nothing moved, was held or was sealed by this
+       * call. Absent on the call that settled it.
+       */
+      replayed?: true;
+      raw: unknown;
+    }
+  | {
+      /** The rail answered and refused. Nothing moved. */
+      status: "failed";
+      code: string;
+      message: string;
+      /**
+       * The rail holds this `attempt_id` as an attempt that failed and moved
+       * no money, and will refuse it for good (`psp_attempt_conflict`). Set
+       * only on that answer: the id is spent, and a batch line pays under the
+       * next generation of its id (`batchAttemptId`).
+       */
+      spent?: true;
+      /**
+       * The rail holds this `attempt_id` for something else: a DIFFERENT
+       * payment (`attempt_id_conflict`, checked before whatever became of it)
+       * or another project of the organization (`attempt_id_unavailable`).
+       * Nothing was held or sent. Never `spent`: the id is not free and not
+       * burned, it is someone else's, and presenting it again answers the same.
+       */
+      held?: "conflict" | "unavailable";
+      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;
+  /** `sig_sha256` is SHA-256 of the mandate's own signature, which a v4 chain seals in place of it; never the signature itself, which is a bearer proof. */
+  mandate: { id: string; sig_sha256?: string };
+  /**
+   * The chain format the receipt was sealed under (4 once it carries the
+   * approval link), and the approval it sealed, as the API read them back:
+   * `null` when it sealed none. Absent when the rail cannot say — a charge,
+   * which seals nothing.
+   */
+  chain_version?: number;
+  approval?: SealedSpendApproval | null;
+  /** `payee` is the one the receipt SEALED — the quote's, on a payment — and null when it sealed none. Never copied from the execution. */
+  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;
+  /** The Ed25519 signature CodeSpar seals alongside the HMAC (base64url) and
+   *  the published key that made it. Null on a receipt sealed before the API
+   *  had the capability, on a record the API seals nothing for (a paid
+   *  charge), and on the stub rail, which is not CodeSpar and must not look
+   *  like it. Carried onto the bundle's copy so THAT copy is what a third
+   *  party checks: `npm run verify runs/<run-id>/receipts/<id>.json`. */
+  receipt_sig_ed25519: string | null;
+  receipt_sig_kid: 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. `transactionId` is the rail's own id for the attempt when the core recorded one (an accepted receivable): a rail
+   * whose read is keyed on its id and not on the caller's key looks it up by that.
+   */
+  lookup(attemptId: string, payment: RailPayment, transactionId?: string): Promise<RailLookup>;
+  receipt(receiptId: string, actor: Actor): Promise<RailReceipt | undefined>;
+}

package/templates/checkout-agent/packages/agent-core/src/receipt-chain.ts

@@ -0,0 +1,270 @@
+/**
+ * `receipt-chain`: the receipt's `chain` recomputed from its body, the way a
+ * party outside CodeSpar does it.
+ *
+ * The Ed25519 signature covers `codespar-receipt:v1:<id>:<chain>`, so on its
+ * own it proves CodeSpar sealed SOME body with that digest. Recomputing the
+ * digest from the receipt read is what binds THIS body — the payee, the
+ * amount, and since chain v4 the approval hashes — to the signature. CodeSpar
+ * publishes how, as data: `chain_recipe` on the unauthenticated
+ * `/.well-known/codespar-receipt-keys.json` (ent#1670). This module reads that
+ * recipe and applies it. It does not carry its own copy of the link shapes: a
+ * recipe it does not understand is an answer ("cannot recompute"), never a
+ * guess, because a verifier that silently skipped a clause would compute a
+ * different digest and blame the receipt.
+ *
+ *   chain = hex(SHA-256(UTF-8(JCS({ "v": chain_version, "links": [...] }))))
+ *
+ * JCS is RFC 8785, implemented below in full rather than imported: it is
+ * thirty lines, the enterprise's own canonicalizer is exactly the code a
+ * verifier must not depend on, and a dependency would be one more thing to
+ * audit for a third party who wants to reimplement this. Like
+ * `receipt-verification`, it imports `node:crypto` and nothing else.
+ */
+import { createHash } from "node:crypto";
+
+/* ── RFC 8785 ────────────────────────────────────────────────── */
+
+/** A high surrogate not followed by a low one, or a low one not preceded by a high one. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+
+/**
+ * The JSON Canonicalization Scheme (RFC 8785) of a JSON value.
+ *
+ * - Objects: members sorted by their names as arrays of UTF-16 code units,
+ *   which is what the default `Array.prototype.sort` compares (section 3.2.3).
+ * - Numbers: the ECMAScript `Number.prototype.toString` serialization, which
+ *   is what `JSON.stringify` emits for a finite number (section 3.2.2.3);
+ *   NaN and the infinities are not JSON and are refused.
+ * - Strings: `JSON.stringify`'s escaping, which is the RFC's (section
+ *   3.2.2.2) — except that JCS works on I-JSON, where a lone surrogate is not
+ *   a string at all, so one is refused instead of escaped.
+ * - No whitespace anywhere.
+ *
+ * `undefined`, functions and other non-JSON values are refused: canonicalizing
+ * something that is not JSON would hash a value nobody can reproduce.
+ */
+export function canonicalize(value: unknown): string {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "boolean":
+      return value ? "true" : "false";
+    case "number":
+      if (!Number.isFinite(value)) throw new TypeError(`RFC 8785: ${value} is not a JSON number`);
+      return JSON.stringify(value);
+    case "string":
+      if (LONE_SURROGATE.test(value)) throw new TypeError("RFC 8785: a string with a lone surrogate is not I-JSON");
+      return JSON.stringify(value);
+    case "object": {
+      if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+      const members = Object.keys(value as Record<string, unknown>).sort();
+      return `{${members
+        .map((name) => {
+          if (LONE_SURROGATE.test(name)) throw new TypeError("RFC 8785: a member name with a lone surrogate is not I-JSON");
+          return `${JSON.stringify(name)}:${canonicalize((value as Record<string, unknown>)[name])}`;
+        })
+        .join(",")}}`;
+    }
+    default:
+      throw new TypeError(`RFC 8785: a ${typeof value} is not a JSON value`);
+  }
+}
+
+/* ── The published recipe ────────────────────────────────────── */
+
+/** One link of the recipe, as `chain_recipe.links[]` publishes it. */
+export interface ChainRecipeLink {
+  link: string;
+  /** The member of the receipt read the link's fields are taken from. */
+  from: string;
+  /** When the link is part of the chain: a clause from a small published vocabulary. */
+  when: string;
+  fields?: string[];
+  fields_by_version?: Record<string, string[]>;
+}
+
+export interface ChainRecipe {
+  canonicalization: string;
+  digest: string;
+  version: { field: string; rule?: string };
+  /** The suffix that marks a field included only when the read has it and it is not null. */
+  optional_marker: string;
+  links: ChainRecipeLink[];
+}
+
+/** The canonicalization this module implements, spelled as the recipe spells it. */
+export const RECIPE_CANONICALIZATION = "RFC 8785 (JCS)";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+
+export type RecipeRead = { ok: true; recipe: ChainRecipe } | { ok: false; reason: "recipe_unpublished" | "recipe_unrecognized"; message: string };
+
+/**
+ * The `chain_recipe` of a key document, or why there is none this module can
+ * follow. A document without one comes from a deployment older than ent#1670:
+ * nothing is wrong with the receipt, there is just no published way to bind
+ * its body. A recipe whose canonicalization or digest is not the one
+ * implemented here is refused whole rather than followed halfway.
+ */
+export function readChainRecipe(keyDocument: unknown): RecipeRead {
+  // OUTSIDE THE SDK'S TYPES, and the one place it is read: the well-known
+  // document's schema does not declare `chain_recipe` yet (ent#1759), so no
+  // SDK type exists to read it through. It is validated field by field below
+  // instead. When ent#1759 lands and the SDK types it, this read moves onto
+  // that type and the validation stays: a verifier checks what it is served.
+  const raw = isRecord(keyDocument) ? keyDocument["chain_recipe"] : undefined;
+  if (raw === undefined || raw === null) {
+    return { ok: false, reason: "recipe_unpublished", message: "the key set publishes no `chain_recipe`, so the receipt's body cannot be bound to its chain (a deployment older than ent#1670)" };
+  }
+  const unrecognized = (why: string): RecipeRead => ({ ok: false, reason: "recipe_unrecognized", message: `the published \`chain_recipe\` ${why}, so this verifier does not follow it` });
+  if (!isRecord(raw)) return unrecognized("is not an object");
+  if (raw["canonicalization"] !== RECIPE_CANONICALIZATION) return unrecognized(`names the canonicalization ${JSON.stringify(raw["canonicalization"])}, not ${RECIPE_CANONICALIZATION}`);
+  const digest = raw["digest"];
+  if (typeof digest !== "string" || !/\bSHA-256\b/.test(digest) || !/\blowercase hex\b/.test(digest)) return unrecognized(`names the digest ${JSON.stringify(digest)}, not lowercase-hex SHA-256`);
+  const version = raw["version"];
+  if (!isRecord(version) || typeof version["field"] !== "string") return unrecognized("does not name the field that carries the chain version");
+  const marker = raw["optional_marker"];
+  if (typeof marker !== "string" || marker.length === 0) return unrecognized("does not name its optional-field marker");
+  const links = raw["links"];
+  if (!Array.isArray(links) || links.length === 0) return unrecognized("lists no links");
+  const parsed: ChainRecipeLink[] = [];
+  for (const entry of links) {
+    if (!isRecord(entry) || typeof entry["link"] !== "string" || typeof entry["from"] !== "string" || typeof entry["when"] !== "string") return unrecognized("carries a link without `link`, `from` and `when`");
+    const fields = entry["fields"];
+    const byVersion = entry["fields_by_version"];
+    if (fields !== undefined && !isStringArray(fields)) return unrecognized(`gives the link ${entry["link"]} fields that are not a list of names`);
+    if (byVersion !== undefined && !(isRecord(byVersion) && Object.values(byVersion).every(isStringArray))) return unrecognized(`gives the link ${entry["link"]} per-version fields that are not lists of names`);
+    if (fields === undefined && byVersion === undefined) return unrecognized(`gives the link ${entry["link"]} no fields`);
+    parsed.push({
+      link: entry["link"],
+      from: entry["from"],
+      when: entry["when"],
+      ...(fields !== undefined ? { fields } : {}),
+      ...(byVersion !== undefined ? { fields_by_version: byVersion as Record<string, string[]> } : {}),
+    });
+  }
+  return {
+    ok: true,
+    recipe: {
+      canonicalization: RECIPE_CANONICALIZATION,
+      digest,
+      version: { field: version["field"], ...(typeof version["rule"] === "string" ? { rule: version["rule"] } : {}) },
+      optional_marker: marker,
+      links: parsed,
+    },
+  };
+}
+
+/* ── Recomputing ─────────────────────────────────────────────── */
+
+export type ChainRecomputation =
+  | { ok: true; chain: string; version: number }
+  | {
+      ok: false;
+      /**
+       * `chain_version_missing`  the read does not say which version sealed it.
+       * `recipe_unrecognized`    a clause, or a version, the recipe does not
+       *                          define in a way this module can follow.
+       * `mandate_sig_required`   a v1–v3 chain seals the mandate's raw
+       *                          signature, which the read given here does
+       *                          not carry.
+       * `payee_masked`           the quote's payee is a masked copy; the chain
+       *                          sealed the key itself.
+       * `field_missing`          any other field the recipe needs is absent.
+       */
+      reason: "chain_version_missing" | "recipe_unrecognized" | "mandate_sig_required" | "payee_masked" | "field_missing";
+      message: string;
+      version: number | null;
+    };
+
+/** A payee the proof bundle masked (`es***@exemplo.com.br`). No Pix key contains `***`. */
+export function isMaskedPayee(payee: unknown): boolean {
+  return typeof payee === "string" && payee.includes("***");
+}
+
+/** Whether a link applies. `undefined` for a clause the recipe did not publish before this module was written. */
+function applies(when: string, from: string, read: Record<string, unknown>, version: number): boolean | undefined {
+  if (when === "always") return true;
+  if (when === `${from} is not null`) return read[from] !== null && read[from] !== undefined;
+  const byVersion = /^chain_version is (\d+)$/.exec(when);
+  if (byVersion) return version === Number(byVersion[1]);
+  return undefined;
+}
+
+/**
+ * Recompute `chain` from a receipt read (the JSON of
+ * `GET /v1/consumers/receipts/{id}`), following the recipe exactly: links in
+ * the published order, a link whose clause does not hold left out rather than
+ * nulled, values copied as read (`null` included), a field marked optional
+ * included only when present and not null. Timestamps are taken as read: the
+ * API seals them in the form it reads them back (RFC 3339 UTC, milliseconds).
+ *
+ * This is the pure recomputation, for any version. Whether a verifier SHOULD
+ * recompute a given version is policy, and lives in `verifyReceiptRead`.
+ */
+export function recomputeChain(read: Record<string, unknown>, recipe: ChainRecipe): ChainRecomputation {
+  const versionRaw = read[recipe.version.field];
+  if (typeof versionRaw !== "number" || !Number.isSafeInteger(versionRaw) || versionRaw < 1) {
+    return { ok: false, reason: "chain_version_missing", version: null, message: `the read carries no \`${recipe.version.field}\`, so which links were sealed cannot be known` };
+  }
+  const version = versionRaw;
+  const links: Record<string, unknown>[] = [];
+  for (const spec of recipe.links) {
+    const include = applies(spec.when, spec.from, read, version);
+    if (include === undefined) return { ok: false, reason: "recipe_unrecognized", version, message: `the recipe includes the link ${spec.link} "when ${spec.when}", a clause this verifier does not know` };
+    if (!include) continue;
+    const fields = spec.fields ?? spec.fields_by_version?.[String(version)];
+    if (!fields) return { ok: false, reason: "recipe_unrecognized", version, message: `the recipe gives the link ${spec.link} no fields for chain v${version}` };
+    const source = read[spec.from];
+    if (!isRecord(source)) return { ok: false, reason: "field_missing", version, message: `the read carries no \`${spec.from}\` object, which the ${spec.link} link of a v${version} chain is taken from` };
+    const link: Record<string, unknown> = {};
+    for (const field of fields) {
+      const optional = field.endsWith(recipe.optional_marker);
+      const name = optional ? field.slice(0, -recipe.optional_marker.length) : field;
+      const value = source[name];
+      if (optional) {
+        if (value !== undefined && value !== null) link[name] = value;
+        continue;
+      }
+      if (value === undefined) {
+        if (spec.from === "mandate" && name === "sig") {
+          return { ok: false, reason: "mandate_sig_required", version, message: `chain v${version} seals the mandate's own signature, and the read carries none: it is a bearer proof only the tenant holds` };
+        }
+        return { ok: false, reason: "field_missing", version, message: `the read carries no \`${spec.from}.${name}\`, which the ${spec.link} link of a v${version} chain seals` };
+      }
+      if (spec.from === "quote" && name === "payee" && isMaskedPayee(value)) {
+        return { ok: false, reason: "payee_masked", version, message: "the quote's payee is a masked copy; the chain sealed the key itself, so this body cannot be recomputed from it" };
+      }
+      link[name] = value;
+    }
+    links.push(link);
+  }
+  return { ok: true, version, chain: createHash("sha256").update(canonicalize({ v: version, links }), "utf8").digest("hex") };
+}
+
+/* ── The approval link (chain v4) ────────────────────────────── */
+
+export interface SealedApproval {
+  items_hash: string;
+  batch_hash: string | null;
+}
+
+/** The approval a read says was sealed, or `null` when it carries none (every chain before v4). */
+export function readSealedApproval(read: Record<string, unknown>): SealedApproval | null {
+  const approval = read["approval"];
+  if (!isRecord(approval) || typeof approval["items_hash"] !== "string") return null;
+  const batch = approval["batch_hash"];
+  return { items_hash: approval["items_hash"], batch_hash: typeof batch === "string" ? batch : null };
+}
+
+/** Two spellings of one SHA-256: the API seals the value as sent, and the `sha256:` prefix is optional on the wire. */
+export function sameApprovalHash(a: string | null | undefined, b: string | null | undefined): boolean {
+  const bare = (h: string | null | undefined) => (typeof h === "string" ? h.replace(/^sha256:/, "") : null);
+  return bare(a) === bare(b);
+}