@coproduct_inc/verify 0.2.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to `@coproduct_inc/verify`.
 
+## 0.5.0
+
+- **`Workflow` — the DAG cage** (`./workflow`, re-exported from root). Compose a
+  multi-agent run into ONE signed `WorkflowReceipt`: register nodes (each a
+  `Cage`) with `after` edges, then `wf.attest(privateKey)`. `verifyWorkflowReceipt`
+  checks it offline — signature + per-node in-bounds recompute + the DAG (acyclic,
+  real edges) + a **cross-node information-flow policy** (`{ sources, sinks,
+  declassifiers }`). The keystone: every node can be locally in-bounds yet the
+  workflow refuses a run where a secret laundered source→…→sink across the DAG —
+  the failure that only exists at multi-agent scale, caught at the orchestration
+  layer. See `examples/workflow-leak.mjs`.
+
+## 0.4.0
+
+- **`Cage` — the 5-minute producer drop-in** (`./cage`, re-exported from root).
+  A runtime cage wraps an agent's tool calls (`cage.tool(name, fn, { guard,
+  subject })`): out-of-boundary calls are blocked, every call is recorded, and
+  `cage.attest(privateKey)` emits a signed in-bounds receipt the existing
+  `verifyReceipt` / CLI checks offline. Closes the loop — producers cage,
+  consumers verify, nobody trusts the seller. See `examples/cage-quickstart.mjs`.
+
+## 0.3.0
+
+### Added
+- **Offline Ed25519 license keys** (`./license` export + `nucleus-license` bin) —
+  entitlement with no user database and no callback: the vendor signs a tiny
+  claims payload; the Pro path verifies it against a pinned public key.
+  `keygen` / `issue` / `verify`; expiry enforced; tamper-evident.
+- **Converting demo** (`examples/converting-demo.sh`) — recordable 4-beat demo
+  (clean attests · OpenClaw impersonation refused · forged verdict caught two
+  ways · CI gate), runs against the published package or `LOCAL=1`.
+- **`WHY-VERIFY.md`** — positioning one-pager (the independent-recompute
+  differentiator + honest Microsoft-AGT contrast) and a static `site/` landing
+  page (zero-JS, zero-backend) wired for a Merchant-of-Record checkout.
+
 ## 0.2.0
 
 ### Added

package/README.md

@@ -1,5 +1,10 @@
 # @coproduct_inc/verify
 
+> **New here?** Read [WHY-VERIFY.md](./WHY-VERIFY.md) ("verify, don't trust" — the
+> one-pager + Microsoft-AGT contrast), or run the 90-second demo:
+> `bash examples/converting-demo.sh` (clean attests · OpenClaw bypass refused ·
+> forged verdict caught · CI gate).
+
 Offline, **zero-trust** verification for Nucleus. Two receipt families share one package:
 
 1. **Capability-boundary in-bounds attestation** (headline) — given an agent run's tool-call trace and a *declared* capability boundary, emit and offline-verify an Ed25519-signed, hash-chained receipt that the agent **stayed within bounds**. The boundary is keyed on a **cryptographic principal**, never a mutable display name — which is exactly what rules out OpenClaw-class trust-boundary bypass.
@@ -7,6 +12,70 @@ Offline, **zero-trust** verification for Nucleus. Two receipt families share one
 
 ---
 
+## Cage your agent — the 5-minute drop-in
+
+You ship an agent that takes actions for a customer. They won't take your word
+that it stayed in bounds. **Cage its tool calls; hand them a receipt they verify
+themselves.** Useful to you alone today (a tighter agent + an artifact your
+customer can check); more valuable as a network of recomputable receipts forms.
+
+```ts
+import { Cage, generateKeypair, verifyReceipt } from "@coproduct_inc/verify";
+
+const cage = new Cage({
+  principal: "spiffe://acme/support-agent",          // a stable id, not a name
+  allowedTools: ["search", "read_ticket", "refund"], // its capability boundary
+});
+
+// Wrap each tool. Out-of-boundary calls are blocked; a guard adds a runtime
+// check (never refund over $50). Works for sync and async tools.
+const search = cage.tool("search", realSearch);
+const refund = cage.tool("refund", realRefund, { guard: (cents) => cents <= 5000 });
+const wire   = cage.tool("wire_transfer", realWire);  // NOT granted
+
+await search("refund policy");        // recorded: allow
+try { await wire("0xbad"); } catch {} // BLOCKED + recorded — your customer sees the attempt
+
+// Emit a signed receipt and hand it over:
+const { privateKey } = generateKeypair();
+const receipt = cage.attest(privateKey);
+
+// THEY verify it — offline, no trust in you (or: npx @coproduct_inc/verify receipt.json):
+const report = verifyReceipt(receipt);  // report.ok === clean run, in bounds, signature valid
+```
+
+Run it end to end: `node examples/cage-quickstart.mjs`. The receipt attests the
+**tool boundary** (every call was to a permitted tool); for argument-level
+*proofs* ("amount < cap over all inputs") see the bytecode prover.
+
+### Multi-agent? Compose the DAG — and catch what node-checks can't
+
+A single agent you can eyeball; a DAG of agents you can't. The dangerous failure
+only exists at DAG scale: **every node is locally in-bounds, yet a secret
+launders from a source, through an innocent middle, to a public sink.** Per-node
+review all passes; only the whole-workflow check catches it.
+
+```ts
+import { Workflow, verifyWorkflowReceipt, generateKeypair } from "@coproduct_inc/verify";
+
+const wf = new Workflow("spiffe://acme/intake-pipeline");
+const reader = wf.node({ id: "reader",    boundary: ["read_secret", "emit"] });
+const enrich = wf.node({ id: "enricher",  boundary: ["transform", "emit"], after: ["reader"] });
+const pub    = wf.node({ id: "publisher", boundary: ["publish"],          after: ["enricher"] });
+// …run your agents through reader/enrich/pub's caged tools…
+
+const receipt = wf.attest(generateKeypair().privateKey);
+
+verifyWorkflowReceipt(receipt, { sources: ["read_secret"], sinks: ["publish"] });
+// → nodesOk: true (every node in-bounds) … but ok: false, flowOk: false:
+//   "information-flow leak: publisher→publish" — the secret reached the sink across the DAG.
+```
+
+It rides on whatever orchestrator you already use (LangGraph, Temporal, CrewAI…)
+— you cage the tools, not the framework. Run it: `node examples/workflow-leak.mjs`.
+
+---
+
 ## In-bounds attestation — the drop-in
 
 ```ts

package/WHY-VERIFY.md

@@ -0,0 +1,81 @@
+# Verify, don't trust.
+
+**`@coproduct_inc/verify`** turns an agent run into **verifiable evidence** that it
+stayed inside a declared capability boundary — evidence a third party can check
+**offline, without trusting the agent or the platform that produced it.**
+
+```sh
+npx @coproduct_inc/verify nucleus-verify run-receipt.json
+#  exit 0 → in bounds   ·   exit 1 → refused
+```
+
+## The problem everyone now has
+
+97% of security leaders expect a material AI-agent incident in the next 12 months;
+6% of budgets address it. The dominant failure mode has a name: the **lethal
+trifecta** — an agent with private data + untrusted content + an exfiltration sink
+gets turned into a *confused deputy*, exercising its authority for an attacker
+(OpenClaw, CVE-2026-25253; Invariant Labs' GitHub-MCP exploit). Regulators are
+arriving too: the EU AI Act's high-risk regime (Aug 2, 2026) demands **productized
+evidence tied to real runs and operator identity** — not a dashboard, an artifact.
+
+The runtime's job is to make that trifecta safe by *non-interference*. This
+package's job is to **prove it happened**: an offline-verifiable receipt that the
+agent stayed inside its declared boundary — i.e. was *not* a confused deputy.
+
+## The one thing that's different: we recompute the verdict
+
+Most "agent receipts" — including Microsoft's Agent Governance Toolkit — are a
+**signed record of what the platform's own engine decided.** You trust the engine.
+
+`@coproduct_inc/verify` is a **second, independent check.** Given the declared
+boundary and the observed trace, it **re-derives** the in-bounds verdict and
+confirms it matches the receipt — then checks an Ed25519 signature and a SHA-256
+hash-chain. A **forged or mistaken** verdict is caught two ways: the recompute
+disagrees, *and* the signature (taken over the honest verdict) breaks.
+
+> A platform vendor is structurally incentivized to be *trusted*. A neutral
+> verifier is incentivized to be *checkable*. That's the wedge.
+
+| | Microsoft Agent Governance Toolkit | `@coproduct_inc/verify` |
+|---|---|---|
+| Capability manifest / policy | ✅ (denies outside the manifest) | relies on yours (any runtime) |
+| Signed, hash-chained receipts | ✅ Ed25519 decision receipts | ✅ Ed25519 + SHA-256 chain |
+| **Independent verdict recompute** | ❌ (trust the engine's decision) | ✅ **soundness floor — catches a forged claim** |
+| Keyed on cryptographic principal, not display name | partial | ✅ rules out OpenClaw by construction |
+| Verdict logic backed by machine-checked theorems | ❌ | ✅ (IFC noninterference, leanchecker-rechecked) |
+| Footprint | a governance framework | one `npx` / one GitHub Action, **zero runtime deps** |
+| Position | the platform | the **neutral verifier above any platform** (incl. AGT) |
+
+We don't compete with the guardrail. We're the evidence layer **above** it — and
+we verify *their* agents too.
+
+## See it (90 seconds)
+
+```sh
+npx @coproduct_inc/verify --help          # or: bash examples/converting-demo.sh
+```
+
+1. **Clean run → attests** (exit 0). Auditor-grade evidence the agent stayed in bounds.
+2. **OpenClaw bypass** — a call wearing an allowlisted *display name* but a different
+   cryptographic principal → **refused** (exit 1). The CVE class, ruled out by construction.
+3. **Forge the verdict** (claim `inBounds:true`) → **caught** by the independent recompute
+   *and* the broken signature. This is the difference between a signed log and verifiable evidence.
+4. **CI gate** — drop the Action in a PR; an out-of-bounds run **fails the build.** A merge gate, not a dashboard.
+
+## Who it's for
+
+- **AppSec** — a 30-second drop-in CI/PR gate, no platform migration, works above your existing guardrails.
+- **GRC / SOC 2 / EU AI Act** — the receipt **is** the exportable audit artifact: offline-verifiable, tied to real runs and operator identity.
+
+## Honest scope
+
+It attests that the **observed trace** stayed within the **declared boundary** —
+integrity-axis, model-level evidence. It is **not** a proof of arbitrary agent
+behavior, and it does not vouch that the trace is a *complete* record of what the
+agent did (completeness of capture is the runtime's job). It's the verifiable
+evidence layer above probabilistic guardrails, not a replacement for them.
+
+---
+
+Sources for the market claims: [VentureBeat / Arkose 2026 agent-security survey](https://venturebeat.com/security/most-enterprises-cant-stop-stage-three-ai-agent-threats-venturebeat-survey-finds), [EU AI Act Art. 16 / Aug 2026](https://artificialintelligenceact.eu/article/16/), [Microsoft Agent Governance Toolkit](https://opensource.microsoft.com/blog/2026/04/02/introducing-the-agent-governance-toolkit-open-source-runtime-security-for-ai-agents/), [PipeLab — mediator receipts / independent attestation](https://pipelab.org/blog/independent-attestation-mediator-receipts/).

package/dist/attestation.browser.d.ts

@@ -0,0 +1 @@
+export { verifyReceipt, verifyReceiptJson, recomputeVerdict, canonicalize, rootHash, makeBoundary, permissionFingerprint, } from "./attestation.js";

package/dist/attestation.browser.js

@@ -0,0 +1,3 @@
+// Browser-only entry: the SAME in-bounds attestation verifier, with node:crypto
+// aliased to a @noble shim at bundle time. Verify-only (no signReceipt).
+export { verifyReceipt, verifyReceiptJson, recomputeVerdict, canonicalize, rootHash, makeBoundary, permissionFingerprint, } from "./attestation.js";

package/dist/cage.d.ts

@@ -0,0 +1,54 @@
+import type { KeyObject } from "node:crypto";
+import type { Receipt } from "./attestation.js";
+import { type ToolProxyExport } from "./toolproxy.js";
+/** Thrown when a caged tool call violates policy (and is blocked). */
+export declare class CageDenied extends Error {
+    readonly tool: string;
+    constructor(tool: string, message: string);
+}
+export interface CageOptions {
+    /** Cryptographic principal the receipt is keyed on — a stable id (SPIFFE id,
+     *  key fingerprint, anything), NOT a mutable display name. */
+    principal: string;
+    /** The tools this agent is permitted to call — its capability boundary. A call
+     *  to anything else is denied and recorded. */
+    allowedTools: string[];
+}
+export interface ToolOptions<A extends unknown[]> {
+    /** A per-call predicate to deny an in-boundary tool on specific arguments
+     *  (e.g. only allow `pay` below a cap). Returning false → blocked at runtime +
+     *  recorded as a deny. NOTE: the receipt attests the TOOL boundary (tool ∈
+     *  allowedTools); a guard is finer RUNTIME hardening — a guard-denied call to
+     *  an allowed tool is still "in bounds" in the receipt (the tool was permitted).
+     *  Argument-level *proof* (e.g. "amount < cap over all inputs") is the
+     *  bytecode prover's job, not this receipt's. */
+    guard?: (...args: A) => boolean;
+    /** Bind the call to its target (a URL, path, counterparty…) — recorded as a
+     *  digest in the receipt, so the receipt is specific to what was acted on. */
+    subject?: (...args: A) => string;
+}
+/**
+ * A runtime cage for an agent's tool calls. Wrap each tool with {@link Cage.tool};
+ * every call is policy-checked and recorded, and a denied call is BLOCKED. At the
+ * end {@link Cage.attest} signs an in-bounds receipt verifiable offline by this
+ * same package.
+ */
+export declare class Cage {
+    private readonly opts;
+    private readonly records;
+    constructor(opts: CageOptions);
+    /** Wrap a tool function so each call is caged + recorded. Works for sync and
+     *  async tools (a denied call throws `CageDenied` before the tool runs). */
+    tool<A extends unknown[], R>(name: string, fn: (...args: A) => R, options?: ToolOptions<A>): (...args: A) => R;
+    /** Record a call you invoke yourself (when wrapping the fn isn't convenient). */
+    record(name: string, allowed: boolean, subject?: string): void;
+    /** How many calls have been caged so far. */
+    get callCount(): number;
+    /** The raw verdict log — the tool-proxy export the verifier consumes. */
+    toExport(): ToolProxyExport;
+    /** Sign an in-bounds attestation receipt. Verify it anywhere with
+     *  `verifyReceipt` / the `@coproduct_inc/verify` CLI — no trust in you required. */
+    attest(privateKey: KeyObject, opts?: {
+        signedAt?: string;
+    }): Receipt;
+}

package/dist/cage.js

@@ -0,0 +1,66 @@
+import { attestToolProxyRun } from "./toolproxy.js";
+/** Thrown when a caged tool call violates policy (and is blocked). */
+export class CageDenied extends Error {
+    tool;
+    constructor(tool, message) {
+        super(message);
+        this.tool = tool;
+        this.name = "CageDenied";
+    }
+}
+/**
+ * A runtime cage for an agent's tool calls. Wrap each tool with {@link Cage.tool};
+ * every call is policy-checked and recorded, and a denied call is BLOCKED. At the
+ * end {@link Cage.attest} signs an in-bounds receipt verifiable offline by this
+ * same package.
+ */
+export class Cage {
+    opts;
+    records = [];
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Wrap a tool function so each call is caged + recorded. Works for sync and
+     *  async tools (a denied call throws `CageDenied` before the tool runs). */
+    tool(name, fn, options) {
+        return (...args) => {
+            const inBoundary = this.opts.allowedTools.includes(name);
+            const guardOk = !options?.guard || options.guard(...args);
+            const ok = inBoundary && guardOk;
+            const rec = { operation: name, verdict: ok ? "allow" : "deny", actor: this.opts.principal };
+            const subject = options?.subject?.(...args);
+            if (subject)
+                rec.subject = subject;
+            this.records.push(rec);
+            if (!ok) {
+                throw new CageDenied(name, inBoundary
+                    ? `tool "${name}" denied by its guard on these arguments`
+                    : `tool "${name}" is outside the agent's capability boundary {${this.opts.allowedTools.join(", ")}}`);
+            }
+            return fn(...args);
+        };
+    }
+    /** Record a call you invoke yourself (when wrapping the fn isn't convenient). */
+    record(name, allowed, subject) {
+        const rec = { operation: name, verdict: allowed ? "allow" : "deny", actor: this.opts.principal };
+        if (subject)
+            rec.subject = subject;
+        this.records.push(rec);
+    }
+    /** How many calls have been caged so far. */
+    get callCount() {
+        return this.records.length;
+    }
+    /** The raw verdict log — the tool-proxy export the verifier consumes. */
+    toExport() {
+        return {
+            boundary: { principal: this.opts.principal, allowedTools: this.opts.allowedTools },
+            records: [...this.records],
+        };
+    }
+    /** Sign an in-bounds attestation receipt. Verify it anywhere with
+     *  `verifyReceipt` / the `@coproduct_inc/verify` CLI — no trust in you required. */
+    attest(privateKey, opts) {
+        return attestToolProxyRun(this.toExport(), privateKey, opts).receipt;
+    }
+}

package/dist/claim-cli.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * `nucleus-verify-claim` — the **proof gate**. Adjudicate one or more
+ * recompute-verified claims and use the exit code as a CI/merge gate.
+ *
+ *   0  → every claim verified (or no claim files found, unless --require)
+ *   1  → at least one claim failed verification
+ *   2  → usage / I/O error
+ *
+ * Usage:
+ *   nucleus-verify-claim <claim.json...> [--summary <file>] [--json]
+ *                        [--require] [--quiet]
+ *
+ * Each `<claim.json>` holds a `Claim` (or an array of them). Evidence may be
+ * inlined (`evidence.receipt`) or referenced by path (`evidence.receiptPath`,
+ * resolved relative to the claim file) so a repo commits a small claim that
+ * points at a checked-in receipt.
+ *
+ * Designed as a drop-in GitHub Action step: writes a Markdown table to
+ * `--summary` (point it at `$GITHUB_STEP_SUMMARY`) and a one-line-per-claim
+ * log, then fails the job if any claim did not recompute.
+ */
+export {};

package/dist/claim-cli.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * `nucleus-verify-claim` — the **proof gate**. Adjudicate one or more
+ * recompute-verified claims and use the exit code as a CI/merge gate.
+ *
+ *   0  → every claim verified (or no claim files found, unless --require)
+ *   1  → at least one claim failed verification
+ *   2  → usage / I/O error
+ *
+ * Usage:
+ *   nucleus-verify-claim <claim.json...> [--summary <file>] [--json]
+ *                        [--require] [--quiet]
+ *
+ * Each `<claim.json>` holds a `Claim` (or an array of them). Evidence may be
+ * inlined (`evidence.receipt`) or referenced by path (`evidence.receiptPath`,
+ * resolved relative to the claim file) so a repo commits a small claim that
+ * points at a checked-in receipt.
+ *
+ * Designed as a drop-in GitHub Action step: writes a Markdown table to
+ * `--summary` (point it at `$GITHUB_STEP_SUMMARY`) and a one-line-per-claim
+ * log, then fails the job if any claim did not recompute.
+ */
+import { readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { verifyClaim } from "./claim.js";
+const HELP = `nucleus-verify-claim — recompute-verified proof gate
+
+USAGE:
+  nucleus-verify-claim <claim.json...> [options]
+
+OPTIONS:
+  --summary <file>   append a Markdown result table to <file>
+                     (use "$GITHUB_STEP_SUMMARY" inside a GitHub Action)
+  --json             print the full verdicts as JSON to stdout
+  --require          fail (exit 1) if NO claim files were supplied/matched
+  --quiet            suppress per-claim log lines (exit code + summary only)
+  -h, --help         show this help
+
+EXIT CODES:
+  0  all claims verified        1  a claim failed / none found with --require        2  usage / I/O error`;
+function parseArgs(argv) {
+    const args = { paths: [], json: false, require: false, quiet: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        switch (a) {
+            case "-h":
+            case "--help":
+                args.help = true;
+                break;
+            case "--json":
+                args.json = true;
+                break;
+            case "--require":
+                args.require = true;
+                break;
+            case "--quiet":
+                args.quiet = true;
+                break;
+            case "--summary":
+                args.summary = argv[++i];
+                break;
+            default:
+                if (a.startsWith("--"))
+                    throw new Error(`unknown option ${a}`);
+                args.paths.push(a);
+        }
+    }
+    return args;
+}
+/** Load the claims from one file, resolving any `receiptPath` against it. */
+function loadClaims(path) {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    const entries = Array.isArray(raw) ? raw : [raw];
+    return entries.map((entry) => {
+        const ev = entry.evidence ?? {};
+        if (ev.receiptPath && ev.receipt === undefined) {
+            const receiptText = readFileSync(resolve(dirname(path), ev.receiptPath), "utf8");
+            // Keep object receipts as objects (in_bounds) and string receipts as
+            // strings (clearing wire form) — try to parse, fall back to raw text.
+            let receipt;
+            try {
+                receipt = JSON.parse(receiptText);
+            }
+            catch {
+                receipt = receiptText;
+            }
+            return { ...entry, evidence: { ...ev, receipt } };
+        }
+        return entry;
+    });
+}
+function statusCell(v) {
+    return v.verified ? "✓ verified" : `✗ ${v.reason ?? "failed"}`;
+}
+function writeSummary(file, verdicts) {
+    const failed = verdicts.filter((v) => !v.verified).length;
+    const lines = [
+        "## Proof gate — recompute-verified claims",
+        "",
+        "| claim | kind | verdict |",
+        "| --- | --- | --- |",
+        ...verdicts.map((v) => `| ${escapePipes(v.statement)} | \`${v.kind}\` | ${escapePipes(statusCell(v))} |`),
+        "",
+        failed === 0
+            ? `**✓ all ${verdicts.length} claim${verdicts.length === 1 ? "" : "s"} recompute-verified.**`
+            : `**✗ ${failed} of ${verdicts.length} claim${verdicts.length === 1 ? "" : "s"} failed.**`,
+        "",
+    ];
+    // `$GITHUB_STEP_SUMMARY` is appended to across steps; honor that.
+    const body = lines.join("\n");
+    try {
+        appendFileSync(file, body + "\n");
+    }
+    catch {
+        writeFileSync(file, body + "\n");
+    }
+}
+function escapePipes(s) {
+    return s.replace(/\|/g, "\\|");
+}
+async function main() {
+    let args;
+    try {
+        args = parseArgs(process.argv.slice(2));
+    }
+    catch (e) {
+        process.stderr.write(`error: ${e.message}\n\n${HELP}\n`);
+        return 2;
+    }
+    if (args.help) {
+        process.stdout.write(HELP + "\n");
+        return 0;
+    }
+    if (args.paths.length === 0) {
+        if (args.require) {
+            process.stderr.write("error: no claim files supplied (--require)\n");
+            return 1;
+        }
+        process.stdout.write("proof gate: no claims to verify.\n");
+        return 0;
+    }
+    let claims;
+    try {
+        claims = args.paths.flatMap(loadClaims);
+    }
+    catch (e) {
+        process.stderr.write(`error: cannot read claims: ${e.message}\n`);
+        return 2;
+    }
+    const verdicts = [];
+    for (const claim of claims) {
+        verdicts.push(await verifyClaim(claim));
+    }
+    if (args.json) {
+        process.stdout.write(JSON.stringify(verdicts, null, 2) + "\n");
+    }
+    else if (!args.quiet) {
+        for (const v of verdicts) {
+            const mark = v.verified ? "✓" : "✗";
+            const stream = v.verified ? process.stdout : process.stderr;
+            stream.write(`${mark} [${v.kind}] ${v.statement} — ${statusCell(v)}\n`);
+            if (!v.verified) {
+                for (const step of v.trace.filter((s) => !s.ok)) {
+                    stream.write(`    ↳ ${step.check}${step.detail ? `: ${step.detail}` : ""}\n`);
+                }
+            }
+        }
+    }
+    if (args.summary) {
+        try {
+            writeSummary(args.summary, verdicts);
+        }
+        catch (e) {
+            process.stderr.write(`warning: could not write summary: ${e.message}\n`);
+        }
+    }
+    const failed = verdicts.filter((v) => !v.verified).length;
+    if (!args.quiet) {
+        process.stdout.write(failed === 0
+            ? `proof gate: ✓ ${verdicts.length} verified.\n`
+            : `proof gate: ✗ ${failed} of ${verdicts.length} failed.\n`);
+    }
+    return failed === 0 ? 0 : 1;
+}
+main().then((code) => process.exit(code));

package/dist/claim.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `claim.ts` — a **recompute-verified claim** façade.
+ *
+ * One uniform call — `verifyClaim(claim) → ClaimVerdict` — over the package's
+ * existing recompute engines, so any surface (a comment-box widget, a CI
+ * check, an MCP tool) can render a single ✓/✗ plus a human-readable recompute
+ * trace next to a claim, without knowing which engine adjudicated it.
+ *
+ * ## The honest boundary
+ *
+ * This verifies **only** claims that reduce to a *deterministic recomputation
+ * over committed evidence* — never arbitrary prose. A claim is adjudicable iff
+ * its value is the output of a pure function the caller can re-run from the
+ * cited inputs:
+ *
+ *   - `clearing`  — re-run an auction's clearing from its SIGNED bid set and
+ *                   check the receipt's price/winner (WASM kernel; the exact
+ *                   `verify` / `recomputeClearing` path).
+ *   - `in_bounds` — re-run an agent run's capability verdict from its tool
+ *                   trace + declared boundary (pure-node attestation engine).
+ *   - `signature` — authenticity only: Ed25519 + BLAKE3 root hash, no
+ *                   value recompute.
+ *
+ * Anything NOT reducible to a recompute (e.g. "10k users downloaded this")
+ * returns `verified: false` with an explicit `unsupported`/`reason` — it is
+ * never silently passed. `eval_score` and `dataset_aggregate` are the planned
+ * next kinds (see docs/RECOMPUTE-VERIFIED-CLAIMS.md); until wired they report
+ * unsupported rather than faking a check.
+ *
+ * ## Proof-carrying numbers
+ *
+ * When a claim carries an `asserted` value (the number a human wrote in prose,
+ * e.g. "cleared at 400000 µ$"), it is cross-checked against the recomputed
+ * value. A receipt that is authentic but whose prose number was altered fails
+ * (`verified: false`, `asserted.matched: false`) — the receipt can't lie, and
+ * neither can the sentence quoting it.
+ */
+/** The closed set of recomputable claim kinds. */
+export type ClaimKind = "clearing" | "in_bounds" | "signature";
+/** Evidence a claim is recomputed against. Shape depends on `kind`. */
+export interface ClaimEvidence {
+    /**
+     * For `clearing` / `signature`: the auction receipt as a JSON **string**
+     * (the hub's wire form). For `in_bounds`: the attestation receipt **object**
+     * (as produced by `signReceipt` / returned from a tool-proxy run).
+     */
+    receipt: string | Record<string, unknown>;
+    /** Pinned issuer JWKS JSON string. Required for `signature`; for `clearing`
+     *  it upgrades the check from recompute-only to recompute + signature. */
+    jwks?: string;
+    /** `in_bounds`: pin the expected cryptographic principal / public key. */
+    expectPrincipal?: string;
+    expectPublicKey?: string;
+}
+/** An author-asserted value to cross-check against the recompute. */
+export interface ClaimAssertion {
+    /** `clearing`: integer micro-USD price. `in_bounds`: boolean. */
+    value: number | boolean | string;
+}
+export interface Claim {
+    /** Human-readable statement rendered next to the ✓/✗. */
+    statement: string;
+    kind: ClaimKind;
+    evidence: ClaimEvidence;
+    /** Optional prose value to cross-check (proof-carrying numbers). */
+    asserted?: ClaimAssertion;
+}
+export interface ClaimTraceStep {
+    check: string;
+    ok: boolean;
+    detail?: string;
+}
+export interface ClaimVerdict {
+    /** The single boolean to gate the ✓/✗ on. */
+    verified: boolean;
+    kind: ClaimKind;
+    statement: string;
+    /** What the recompute produced (kind-specific), or null on a hard error. */
+    recomputed: {
+        label: string;
+        value: unknown;
+    } | null;
+    /** The author's asserted value + whether it matched the recompute. */
+    asserted: {
+        value: unknown;
+        matched: boolean;
+    } | null;
+    /** Ordered, human-readable trace of the checks that ran. */
+    trace: ClaimTraceStep[];
+    /** First failing reason, or null when verified. */
+    reason: string | null;
+}
+/**
+ * Adjudicate a claim by recomputation. Never throws — a malformed receipt,
+ * an unknown kind, or an engine error surface as `verified: false` with a
+ * `reason`, so the widget can always render a definite ✓/✗.
+ */
+export declare function verifyClaim(claim: Claim): Promise<ClaimVerdict>;