@agenticstechnologies/verify 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+Copyright 2026 Agentics, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# @agenticstechnologies/verify
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Offline checks for an Agentics evidence export. The tool recomputes receipt
+leaves and the `prev_hash` chain from the JSON file. It does not call
+Agentics, and it does not trust the `verification` summary inside the file.
+
+## Install
+
+> **Not yet published.** `@agenticstechnologies/verify` is not on npm, so this install fails with E404. Run it from a checkout of this repo, as shown below.
+
+```bash
+npm install @agenticstechnologies/verify
+```
+
+The package binary is `agentics-verify`.
+
+## Version bump policy
+
+Versions follow semver. A fix increments the patch number, a backwards-compatible addition increments the minor number, and a breaking change increments the major number. Update `version` in this package's `package.json` in the same commit as the change. Publishing uses the founder's npm token and does not run on merge.
+
+`scripts/verify-evidence.mjs` is a thin wrapper around the same leaf and chain
+code. From a checkout of this repo:
+
+```bash
+node scripts/verify-evidence.mjs bundle.json
+node packages/agentics-verify/bin/verify.mjs bundle.json
+```
+
+The package binary is `agentics-verify` (`./bin/verify.mjs`). Pass `-` to read
+JSON from stdin.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Leaf and chain match. Merkle, when present, folds. A devnet or testnet memo, when present, matches or the public RPC was skipped. |
+| 1 | A check failed, or the file is not JSON. The reason is on stderr. |
+| 2 | No bundle path was given. |
+
+A passing package run prints three lines:
+
+```text
+pass  checked 2 receipt(s)
+merkle  not-present  batch/merkle fields are not in this export
+solana  not-present  tx/cluster are not in this export
+```
+
+`not-present` means that block was skipped. It is not a failure. `warn` (RPC
+timeout or a cluster this tool does not query) is also not a failure.
+
+## What is checked
+
+**Leaf and chain.** Same algorithm as `lib/gateway/proof.ts` `leafHash` and
+the date-range export from `GET /api/proof/export`:
+
+```text
+sha256Hex(JSON.stringify(canonicalize(canonical minus {receipt_id, batch_id})))
+```
+
+`canonicalize` sorts object keys and drops null and undefined. Each receipt
+after the first must set `prev_hash` to the previous `receipt_hash`. The first
+`prev_hash` must be 64 hex characters. `verification.truncated: true` fails
+the file, including a single-receipt proof bundle.
+
+If a receipt sets `text_cleared_at`, the stored hash covers the cleared fields.
+Older leaves still check every other canonical field by trying the historical
+outcome labels in memory. The label is not printed. An older outcome that is
+not in that list, and every version 4 receipt, must carry `uncleared_digest`.
+Version 4 checks the leaf with `reason`, `target`, `outcome`, and
+`error_message` removed against that digest. An older unlisted outcome checks
+the leaf with `outcome` removed. Without the digest those leaves fail. The
+chain link is unchanged. A changed amount, agent, or `prev_hash` still fails.
+
+A proof bundle from `GET /api/proof/bundle` has one `receipt` plus
+`receipt_hash` instead of `receipts`. The leaf is recomputed the same way.
+`chain` is checked as hash links (oldest-first or the newest-first order
+`chainFor` returns). Ancestor bodies are not in that bundle, so only the
+included receipt is re-hashed.
+
+**Merkle.** When the export includes a proof, the fold is the sorted-pair
+Merkle in `netlify/edge-functions/lib/ledger.js` (`hashPair` hashes the two
+digests in sorted order, an odd node is duplicated, an empty list is null).
+That is the same fold `lib/gateway/proof.ts` uses for a batch. It is tree rule
+`v1`, and every batch anchored before v2 stays v1.
+
+**Tree rule v2 (1.0.0).** A claim with `tree_rule: "v2"` uses RFC 9162
+section 2.1 (RFC 6962) over the 32 bytes of each leaf:
+
+- leaf = SHA-256(0x00 || leaf)
+- node = SHA-256(0x01 || left || right), in position order
+- an odd last node is promoted unchanged
+- a one-leaf root is its leaf hash
+
+A v2 proof is the RFC audit path, so it also needs `index` (or `leaf_index`)
+and `leaf_count` (or `tree_size`). Without them the claim fails rather than
+guessing. With no `tree_rule`, the claim is v1. Any other value is refused,
+never folded as v1. `merkleRootV2`, `merkleProofV2`, `verifyProofV2`,
+`leafHashV2` and `treeRuleOf` are exported.
+
+Recognized fields, and no others:
+
+- `merkle.siblings` or `merkle.proof`, with `merkle.root` or `merkle.merkle_root`
+- `merkle.leaves` with a root (full leaf list, receipt-hash order)
+- the same fields on a receipt row's `merkle` object
+- `batches[].merkle_root` with `batches[].leaves` or `batches[].siblings`
+- `tree_rule` and `leaf_count` on any of the above (v2 only)
+
+The proof bundle published by `bundle()` uses `merkle.siblings` and
+`merkle.root`. If none of these fields are present, the line is
+`merkle  not-present`. A root with neither siblings nor a leaf list fails:
+the export claimed a root and this tool cannot recompute it.
+
+**Solana memo.** Only when the bundle has both a transaction id and a cluster
+(`anchor.txid` and `anchor.chain` or `anchor.cluster`, or top-level `tx` and
+`cluster`). Devnet (`solana-devnet`, `devnet`, Solscan `?cluster=devnet`) uses
+`https://api.devnet.solana.com`. Testnet uses `https://api.testnet.solana.com`.
+The public `getTransaction` response is read for a Memo program instruction
+(`MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr`) and compared to the recomputed
+Merkle root, or to `anchor.memo` when the export has no root. No private key
+is read and nothing is signed. Mainnet is not queried. If `anchor.memo` is
+present and a Merkle root was recomputed, the two must match before any
+network read; a missing transaction id still skips the public RPC. If the RPC
+does not answer within 8 seconds, the line is `solana  warn` and the process
+still exits 0 when every other check passed.
+
+## Agent record
+
+`GET /api/record/:handle/export` is a signed record (`typ` `agentics.record.v1`).
+Check it with the public keys from `https://agentics.you/.well-known/jwks.json`.
+The tool does not call Agentics.
+
+```bash
+node packages/agentics-verify/bin/verify.mjs record.json --jwks jwks.json
+```
+
+Exit 0 prints the handle, the label, and the counts. Exit 1 is `fail`, the
+reason code, and a sentence. A changed count, a changed score, or a flipped
+signature byte fails. A record does not expire by clock. A previous signing
+key still verifies old exports while it remains in the published key set.
+`New, no record yet` is a real label: the file had no settlement and no claim.
+
+## Tests
+
+```bash
+node --test packages/agentics-verify/test/verify.test.mjs
+```
+
+The fixture `test/fixtures/evidence-export.json` is an unmodified
+`agentics.evidence.v1` export. Tampering with `receipt_hash` or a leaf field
+exits 1.
+
+## License
+
+Apache-2.0 — © Agentics Technologies LLC.

package/bin/verify.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// Offline check of an Agentics evidence export.
+//
+//   node packages/agentics-verify/bin/verify.mjs bundle.json
+//   node packages/agentics-verify/bin/verify.mjs -     # JSON on stdin
+//
+// Exit 0 when the leaf and prev_hash checks pass, any included Merkle proof
+// folds, and a devnet/testnet memo (if present) matches or the RPC is skipped.
+// Exit 1 when a check fails. Exit 2 when no path is given.
+
+import { verifyBundle } from "../src/bundle.mjs";
+import { isRecordBundle, verifyRecord } from "../src/record.mjs";
+
+function statusLine(label, part) {
+  return `${label}  ${part.status}${part.reason ? "  " + part.reason : ""}`;
+}
+
+const args = process.argv.slice(2);
+let jwksPath = null;
+const positional = [];
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--jwks") {
+    jwksPath = args[i + 1] ?? "";
+    i += 1;
+    continue;
+  }
+  positional.push(args[i]);
+}
+const arg = positional[0];
+if (!arg) {
+  console.error("usage: node packages/agentics-verify/bin/verify.mjs <bundle.json | -> [--jwks jwks.json]");
+  process.exit(2);
+}
+
+const fs = await import("node:fs");
+let text;
+try {
+  text = arg === "-" ? fs.readFileSync(0, "utf8") : fs.readFileSync(arg, "utf8");
+} catch (e) {
+  console.error("cannot read bundle:", e instanceof Error ? e.message : String(e));
+  process.exit(1);
+}
+
+let bundle;
+try {
+  bundle = JSON.parse(text);
+} catch (e) {
+  console.error("invalid JSON:", e instanceof Error ? e.message : String(e));
+  process.exit(1);
+}
+
+if (isRecordBundle(bundle)) {
+  if (!jwksPath) {
+    console.error("fail  jwks required  pass --jwks with the keys from /.well-known/jwks.json");
+    process.exit(1);
+  }
+  let jwksText;
+  try {
+    jwksText = fs.readFileSync(jwksPath, "utf8");
+  } catch (e) {
+    console.error("cannot read jwks:", e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+  let jwks;
+  try {
+    jwks = JSON.parse(jwksText);
+  } catch (e) {
+    console.error("invalid jwks JSON:", e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+  const checked = await verifyRecord(bundle, jwks);
+  if (!checked.ok) {
+    console.error(`fail  ${checked.reason}${checked.message ? "  " + checked.message : ""}`);
+    process.exit(1);
+  }
+  const record = checked.record ?? {};
+  console.log(`pass  record ${checked.handle}`);
+  console.log(`label  ${record.label}`);
+  console.log(`paid on time  ${record.paid_on_time}`);
+  console.log(`claims filed  ${record.claims_filed}`);
+  console.log(`claims paid  ${record.claims_paid}`);
+  console.log(`sellers  ${record.distinct_sellers}`);
+  console.log(`age  ${record.age_days == null ? "none" : record.age_days + " days"}`);
+  process.exit(0);
+}
+
+const result = await verifyBundle(bundle);
+const merkleLine = statusLine("merkle", result.merkle);
+const solanaLine = statusLine("solana", result.solana);
+
+if (result.ok) {
+  console.log(`pass  checked ${result.checked} receipt(s)`);
+  console.log(merkleLine);
+  if (result.solana.status === "warn") console.error(solanaLine);
+  else console.log(solanaLine);
+  process.exit(0);
+}
+
+console.error(`fail  checked ${result.checked}`);
+for (const f of result.failures) {
+  console.error(`- ${f.reason}  hash=${f.receipt_hash} prev=${f.prev_hash}`);
+}
+console.error(merkleLine);
+console.error(solanaLine);
+process.exit(1);

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@agenticstechnologies/verify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Offline verifier for Agentics evidence export bundles. Recomputes receipt leaves and the prev_hash chain, and folds a Merkle proof when the export includes one.",
+  "license": "Apache-2.0",
+  "author": "Agentics Technologies LLC",
+  "homepage": "https://agentics.you",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agenticstechnologies/agentics.you",
+    "directory": "packages/agentics-verify"
+  },
+  "type": "module",
+  "bin": {
+    "agentics-verify": "./bin/verify.mjs"
+  },
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs"
+    },
+    "./cleared": {
+      "types": "./src/cleared.d.ts",
+      "import": "./src/cleared.mjs"
+    }
+  },
+  "scripts": {
+    "test": "node --test test/verify.test.mjs"
+  },
+  "engines": { "node": ">=18" },
+  "files": ["bin", "src", "README.md", "LICENSE"],
+  "publishConfig": { "access": "public" },
+  "keywords": ["agentics", "evidence", "receipts", "merkle", "verify"]
+}

package/src/bundle.mjs

@@ -0,0 +1,364 @@
+// Full offline check of an evidence export or a proof bundle.
+// Leaf and prev_hash: verifyEvidenceExport (GET /api/proof/export).
+// A single-receipt proof bundle (GET /api/proof/bundle) has `receipt` instead
+// of `receipts`; its chain array is hash links only.
+// Merkle and Solana run only when the bundle carries those fields.
+
+import { clearedLeafMatches, leafHash, verifyEvidenceExport } from "./evidence.mjs";
+import { merkleRoot, merkleRootV2, treeRuleOf, TREE_RULE_V2, verifyProof, verifyProofV2 } from "./merkle.mjs";
+import { checkSolanaMemo, classifyCluster } from "./solana.mjs";
+
+const HEX64 = /^[0-9a-f]{64}$/;
+
+function failure(reason, hashOk = false, chainOk = false) {
+  return {
+    receipt_hash: "",
+    prev_hash: "",
+    hash_ok: hashOk,
+    chain_ok: chainOk,
+    reason,
+  };
+}
+
+function hex64(v) {
+  if (typeof v !== "string") return null;
+  const s = v.trim().toLowerCase();
+  return HEX64.test(s) ? s : null;
+}
+
+function text(v) {
+  if (v == null) return null;
+  const s = String(v).trim();
+  return s.length ? s : null;
+}
+
+function linksOldestFirst(chain) {
+  for (let i = 0; i < chain.length; i++) {
+    const prev = String((chain[i] ?? {}).prev_hash ?? "");
+    if (i === 0) {
+      if (!HEX64.test(prev)) return false;
+    } else if (prev !== String((chain[i - 1] ?? {}).receipt_hash ?? "")) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function linksNewestFirst(chain) {
+  for (let i = 0; i < chain.length; i++) {
+    const prev = String((chain[i] ?? {}).prev_hash ?? "");
+    if (!HEX64.test(prev)) return false;
+    if (i < chain.length - 1 && prev !== String((chain[i + 1] ?? {}).receipt_hash ?? "")) {
+      return false;
+    }
+  }
+  return true;
+}
+
+async function verifySingleReceipt(bundle) {
+  const canonical = bundle.receipt ?? {};
+  const claimed = String(bundle.receipt_hash ?? "");
+  const prev = String(canonical.prev_hash ?? "");
+  let recomputed = "";
+  let hashOk = false;
+  try {
+    recomputed = await leafHash(canonical);
+    hashOk = recomputed === claimed || await clearedLeafMatches(canonical, claimed, leafHash, {
+      text_cleared_at: bundle.text_cleared_at,
+      hash_version: bundle.hash_version ?? canonical.hash_version,
+      uncleared_digest: bundle.uncleared_digest,
+      status: bundle.status,
+    });
+  } catch {
+    hashOk = false;
+  }
+  let chainOk = true;
+  let reason = null;
+  if (!hashOk) reason = `leaf recomputed ${recomputed} != ${claimed}`;
+  if (Array.isArray(bundle.chain) && bundle.chain.length > 0) {
+    const forward = linksOldestFirst(bundle.chain);
+    const backward = linksNewestFirst(bundle.chain);
+    if (!forward && !backward) {
+      chainOk = false;
+      reason = reason ?? "prev_hash does not match the previous receipt_hash";
+    } else {
+      const mine = bundle.chain.find((row) => String((row ?? {}).receipt_hash ?? "") === claimed);
+      if (!mine) {
+        chainOk = false;
+        reason = reason ?? "receipt_hash is not in the chain";
+      } else if (String(mine.prev_hash ?? "") !== prev) {
+        chainOk = false;
+        reason = reason ?? "prev_hash does not match the previous receipt_hash";
+      }
+    }
+  } else if (!HEX64.test(prev)) {
+    chainOk = false;
+    reason = reason ?? "prev_hash is not 64 hex characters";
+  }
+  const failures = [];
+  if (!hashOk || !chainOk) {
+    failures.push({
+      receipt_hash: claimed,
+      prev_hash: prev,
+      hash_ok: hashOk,
+      chain_ok: chainOk,
+      reason: reason ?? "failed",
+    });
+  }
+  return { checked: 1, failures };
+}
+
+function hexList(v) {
+  if (!Array.isArray(v)) return null;
+  return v.map((item) => (typeof item === "string" ? item.trim().toLowerCase() : ""));
+}
+
+function claimFrom(merkle, leaf) {
+  if (!merkle || typeof merkle !== "object") return null;
+  const root = hex64(merkle.root) || hex64(merkle.merkle_root);
+  const siblings = Array.isArray(merkle.siblings)
+    ? hexList(merkle.siblings)
+    : (Array.isArray(merkle.proof) ? hexList(merkle.proof) : null);
+  const leaves = Array.isArray(merkle.leaves) ? hexList(merkle.leaves) : null;
+  const index = Number.isInteger(merkle.index)
+    ? merkle.index
+    : (Number.isInteger(merkle.leaf_index) ? merkle.leaf_index : null);
+  if (!root && !siblings && !leaves) return null;
+  const size = Number.isInteger(merkle.leaf_count) ? merkle.leaf_count : (Number.isInteger(merkle.tree_size) ? merkle.tree_size : null);
+  return {
+    root,
+    siblings,
+    leaves,
+    index,
+    size,
+    // anchor_batches.tree_rule (L3-16). Absent is v1, the rule every batch before v2 was anchored under.
+    rule: merkle.tree_rule ?? null,
+    leaf: hex64(merkle.leaf) || leaf || null,
+  };
+}
+
+function merkleClaims(bundle) {
+  const claims = [];
+  const topLeaf = hex64(bundle.receipt_hash);
+  const top = claimFrom(bundle.merkle, topLeaf);
+  if (top) claims.push(top);
+  if (Array.isArray(bundle.receipts)) {
+    for (const row of bundle.receipts) {
+      if (!row || typeof row !== "object" || row.merkle == null) continue;
+      const rowClaim = claimFrom(row.merkle, hex64(row.receipt_hash));
+      if (rowClaim) claims.push(rowClaim);
+    }
+  }
+  // ledger_batches / anchor batch rows, if an export included them.
+  // Same field names as proof.ts: merkle_root, plus siblings or leaves.
+  if (Array.isArray(bundle.batches)) {
+    for (const batch of bundle.batches) {
+      if (!batch || typeof batch !== "object") continue;
+      const rowClaim = claimFrom({
+        root: batch.root,
+        merkle_root: batch.merkle_root,
+        siblings: batch.siblings,
+        proof: batch.proof,
+        leaves: batch.leaves,
+        index: batch.index,
+        leaf_index: batch.leaf_index,
+        leaf_count: batch.leaf_count,
+        tree_rule: batch.tree_rule,
+      }, topLeaf);
+      if (rowClaim) claims.push(rowClaim);
+    }
+  }
+  return claims;
+}
+
+async function checkClaim(claim) {
+  const reasons = [];
+  let confirmed = null;
+  const rule = treeRuleOf(claim.rule);
+  if (rule === null) {
+    reasons.push(`unknown merkle tree rule ${String(claim.rule).slice(0, 40)}`);
+    return { reasons, root: null };
+  }
+  const v2 = rule === TREE_RULE_V2;
+  if (!claim.root) {
+    reasons.push("merkle root is missing");
+    return { reasons, root: null };
+  }
+  if (!claim.leaves && !claim.siblings) {
+    reasons.push("merkle root is present but the export has no leaves or siblings to recompute");
+    return { reasons, root: null };
+  }
+  if (claim.leaves) {
+    if (claim.leaves.some((h) => !HEX64.test(h))) {
+      reasons.push("merkle leaf is not 64 hex characters");
+    } else {
+      const recomputed = v2 ? await merkleRootV2(claim.leaves) : await merkleRoot(claim.leaves);
+      if (recomputed !== claim.root) {
+        reasons.push(`merkle root recomputed ${recomputed} != ${claim.root}`);
+      } else {
+        confirmed = recomputed;
+      }
+      if (claim.index != null) {
+        if (claim.index < 0 || claim.index >= claim.leaves.length) {
+          reasons.push("merkle index is outside the leaf list");
+        } else if (claim.leaf && claim.leaves[claim.index] !== claim.leaf) {
+          reasons.push("merkle index does not point at the receipt hash");
+        }
+      }
+    }
+  }
+  if (claim.siblings) {
+    if (!claim.leaf) {
+      reasons.push("merkle proof is present but no leaf hash");
+    } else if (claim.siblings.some((h) => !HEX64.test(h))) {
+      reasons.push("merkle sibling is not 64 hex characters");
+    } else {
+      const size = claim.size ?? claim.leaves?.length ?? null;
+      if (v2 && (claim.index == null || size == null)) {
+        reasons.push("a v2 merkle proof needs the leaf index and leaf_count");
+      } else {
+        const folded = v2
+          ? await verifyProofV2(claim.leaf, claim.index, size, claim.siblings, claim.root)
+          : await verifyProof(claim.leaf, claim.siblings, claim.root);
+        if (!folded) reasons.push(`merkle proof does not fold to ${claim.root}`);
+        else if (!confirmed) confirmed = claim.root;
+      }
+    }
+  }
+  return { reasons, root: reasons.length === 0 ? confirmed : null };
+}
+
+async function verifyMerkle(bundle) {
+  const claims = merkleClaims(bundle);
+  if (claims.length === 0) {
+    return {
+      status: "not-present",
+      reason: "batch/merkle fields are not in this export",
+      roots: [],
+    };
+  }
+  const reasons = [];
+  const roots = [];
+  for (const claim of claims) {
+    const checked = await checkClaim(claim);
+    reasons.push(...checked.reasons);
+    if (checked.root) roots.push(checked.root);
+  }
+  if (reasons.length) {
+    return { status: "fail", reason: reasons[0], roots: [] };
+  }
+  return { status: "pass", reason: null, roots };
+}
+
+function anchorFrom(bundle) {
+  const a = bundle.anchor && typeof bundle.anchor === "object" ? bundle.anchor : null;
+  const src = a ?? {};
+  const tx = text(src.txid) || text(src.tx) || text(src.tx_hash) || text(bundle.tx) || text(bundle.txid) || text(bundle.anchor_txid);
+  const clusterHint = text(src.cluster) || text(src.chain) || text(bundle.cluster) || text(bundle.anchor_chain);
+  const explorer = text(src.explorer_url);
+  const memo = text(src.memo) || text(bundle.memo);
+  if (!a && !tx && !clusterHint) return null;
+  return { tx, clusterHint, explorer, memo };
+}
+
+async function verifySolana(bundle, merkle, opts) {
+  const anchor = anchorFrom(bundle);
+  // Local consistency: memo must equal a recomputed root even when there is
+  // no transaction to fetch, and even when the memo is not 64 hex characters.
+  // This does not call the network.
+  const memoText = anchor && anchor.memo ? String(anchor.memo).trim().toLowerCase() : "";
+  const memoHex = anchor ? hex64(anchor.memo) : null;
+  const roots = merkle.roots || [];
+  if (memoText && roots.length && !roots.includes(memoText)) {
+    return { status: "fail", reason: "anchor memo does not equal the recomputed merkle root" };
+  }
+  if (!anchor || (!anchor.tx && !anchor.clusterHint && !anchor.explorer)) {
+    return { status: "not-present", reason: "tx/cluster are not in this export" };
+  }
+  if (!anchor.tx || !(anchor.clusterHint || anchor.explorer)) {
+    return { status: "not-present", reason: "tx and cluster are both required" };
+  }
+  const cluster = classifyCluster(anchor.clusterHint, anchor.explorer);
+  if (cluster === "mainnet") {
+    return {
+      status: "warn",
+      reason: "solana memo not checked: cluster is mainnet; public devnet and testnet only",
+    };
+  }
+  if (cluster !== "devnet" && cluster !== "testnet") {
+    return {
+      status: "warn",
+      reason: "solana memo not checked: cluster is not devnet or testnet",
+    };
+  }
+  const expected = (memoHex && roots.includes(memoHex) ? memoHex : roots[0]) || memoHex;
+  if (!expected) {
+    return {
+      status: "not-present",
+      reason: "no merkle root or memo to compare",
+    };
+  }
+  const checked = await checkSolanaMemo({
+    txid: anchor.tx,
+    cluster,
+    expected,
+    timeoutMs: opts.timeoutMs,
+    fetchImpl: opts.fetchImpl,
+  });
+  if (checked.ok) return { status: "pass", reason: null };
+  if (checked.warn) return { status: "warn", reason: checked.reason };
+  return { status: "fail", reason: checked.reason };
+}
+
+/**
+ * @param {unknown} bundle
+ * @param {{ timeoutMs?: number, fetchImpl?: typeof fetch }} [opts]
+ */
+export async function verifyBundle(bundle, opts = {}) {
+  if (!bundle || typeof bundle !== "object" || Array.isArray(bundle)) {
+    return {
+      ok: false,
+      checked: 0,
+      failures: [failure("bundle is not an object")],
+      merkle: { status: "not-present", reason: "batch/merkle fields are not in this export" },
+      solana: { status: "not-present", reason: "tx/cluster are not in this export" },
+    };
+  }
+
+  let checked = 0;
+  /** @type {ReturnType<typeof failure>[]} */
+  let failures = [];
+  if (Array.isArray(bundle.receipts)) {
+    const leaf = await verifyEvidenceExport(bundle);
+    checked = leaf.checked;
+    failures = leaf.failures.slice();
+  } else if (bundle.receipt && typeof bundle.receipt === "object") {
+    const one = await verifySingleReceipt(bundle);
+    checked = one.checked;
+    failures = one.failures.slice();
+  } else {
+    failures = [failure("bundle.receipts is missing")];
+  }
+
+  // A receipts export already records this inside verifyEvidenceExport.
+  // A single-receipt proof bundle (GET /api/proof/bundle, the sample receipt)
+  // did not, so a truncated file could still pass leaf and Merkle.
+  if (bundle.verification && bundle.verification.truncated === true) {
+    const already = failures.some((row) => String(row.reason).includes("truncated"));
+    if (!already) failures.push(failure("export was truncated; refuse to call it complete"));
+  }
+
+  const merkle = await verifyMerkle(bundle);
+  if (merkle.status === "fail") failures.push(failure(merkle.reason));
+
+  const solana = await verifySolana(bundle, merkle, opts);
+  if (solana.status === "fail") failures.push(failure(solana.reason));
+
+  return {
+    ok: failures.length === 0,
+    checked,
+    failures,
+    merkle: { status: merkle.status, reason: merkle.reason },
+    solana: { status: solana.status, reason: solana.reason },
+  };
+}

package/src/cleared.d.ts

@@ -0,0 +1,11 @@
+export function clearedLeafMatches(
+  canonical: Record<string, unknown>,
+  storedHash: string,
+  leafHash: (canonical: Record<string, unknown>) => Promise<string>,
+  meta?: {
+    text_cleared_at?: unknown;
+    hash_version?: unknown;
+    uncleared_digest?: unknown;
+    status?: unknown;
+  },
+): Promise<boolean>;