verifyhash 0.1.0 → 0.1.1

package/verifier/dist/verify-vh-standalone.js

@@ -0,0 +1,4121 @@
+#!/usr/bin/env node
+"use strict";
+
+// verify-vh-standalone.js — the SINGLE-FILE, ZERO-DEPENDENCY, OFFLINE verifyhash verifier.
+//
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 verifyhash.com — https://verifyhash.com
+//
+// GENERATED by verifier/build-standalone.js from the in-tree verifier — DO NOT EDIT BY HAND.
+// Re-generate with: node verifier/build-standalone.js   (the build is deterministic; see that file.)
+//
+// HOW TO USE IT (no clone, no `npm install`, no node_modules, no package.json):
+//   1. Save THIS one file somewhere next to the sealed artifact you were handed.
+//   2. Run:  node verify-vh-standalone.js <artifact> [--vendor <0xaddr>] [--dir <d>] [--json]
+//   Exit codes: 0 ok / 3 rejected / 2 usage / 1 IO.   It is READ-ONLY and opens NO network.
+//
+// SELF-DESCRIBING (needs NO second file): this bundle carries its OWN build-provenance.
+//   node verify-vh-standalone.js --self-attest   # confirm THIS file's bytes are intact (0 ok / 1 modified)
+//   node verify-vh-standalone.js --provenance    # print the ordered source modules + sha256 it was built from
+//
+// It RE-DERIVES the keccak Merkle root from the bytes YOU hold and recovers the signer with a
+// pure-JS secp256k1 routine — it never trusts the artifact's own stored hashes, and it requires
+// NOTHING outside Node core. This is the in-tree verifier inlined verbatim, with keccak256 swapped
+// for a byte-identical pure-JS implementation (cross-checked against js-sha3 AND ethers).
+
+// ---- minimal CommonJS module shim (so the inlined modules keep their require() structure) --------
+var __modules = Object.create(null);
+var __cache = Object.create(null);
+function __require(id) {
+  if (id in __cache) return __cache[id].exports;
+  var factory = __modules[id];
+  if (!factory) throw new Error('standalone bundle: unknown module: ' + id);
+  var module = { exports: {} };
+  __cache[id] = module;
+  factory(module, module.exports, __require);
+  return module.exports;
+}
+
+// ===== module: keccak256-vendored  (from verifier/lib/keccak256-vendored.js) =====
+__modules["keccak256-vendored"] = function (module, exports, __require) {
+"use strict";
+
+// verifier/lib/keccak256-vendored.js — a PURE-JS, ZERO-DEPENDENCY keccak256 (T-35.1).
+//
+// WHY THIS FILE EXISTS
+//   The whole point of the free verifier is "save ONE file, run it with `node`, no `npm install`, audit it
+//   in one sitting." The in-tree verifier core takes keccak256 from `js-sha3` (verifier/lib/keccak.js) — an
+//   audited, dependency-free package that is already a project dependency — which is correct for the
+//   IN-TREE path. But `js-sha3` is still a RUNTIME dependency: a third party handed a single sealed packet
+//   would have to `npm install` it. This module is the LAST piece needed to inline the verifier into one
+//   self-contained file: a from-scratch keccak256 that `require`s NOTHING (no `js-sha3`, no Node core, no
+//   relative module). It is ADDITIVE — keccak.js and verifier/package.json's `dependencies: ["js-sha3"]`
+//   are deliberately left UNCHANGED so the existing tree + isolation test stay green.
+//
+// CORRECTNESS, NOT NOVELTY
+//   keccak256 is the FIXED, standardized Keccak[c=512] sponge over the Keccak-f[1600] permutation with the
+//   ORIGINAL Keccak padding (a single 0x01 domain byte, NOT SHA3's 0x06) and a 256-bit squeeze — exactly
+//   what Ethereum/ethers and `js-sha3.keccak256` compute. This is a textbook implementation of FIPS-202's
+//   Keccak-f (theta, rho, pi, chi, iota) done with 32-bit lane halves (lo/hi) so it runs on plain JS numbers
+//   with no BigInt and no 64-bit-int dependency. test/verifier.keccak-vendored.test.js proves byte-identical
+//   output vs BOTH `js-sha3` AND the production `ethers` keccak path across the empty input, the known
+//   vectors, and ≥500 random buffers — a single mismatch FAILS. So this is independent CODE but never an
+//   independent ALGORITHM: it cannot silently diverge from the standard.
+//
+// REQUIRES NOTHING: a grep of this source finds no CommonJS require call and no bare-name import.
+// (Intentional — this property is asserted by test/verifier.keccak-vendored.test.js.)
+
+// ---- Keccak-f[1600] round constants, split into 32-bit (hi, lo) halves --------------------------------
+// The 24 RC[i] are the canonical Keccak iota constants; here each 64-bit constant is pre-split so we never
+// need a 64-bit integer type. RC_HI[i] is bits 63..32, RC_LO[i] is bits 31..0.
+const RC_HI = [
+  0x00000000, 0x00000000, 0x80000000, 0x80000000, 0x00000000, 0x00000000, 0x80000000, 0x80000000,
+  0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x80000000, 0x80000000, 0x80000000,
+  0x80000000, 0x80000000, 0x00000000, 0x80000000, 0x80000000, 0x80000000, 0x00000000, 0x80000000,
+];
+const RC_LO = [
+  0x00000001, 0x00008082, 0x0000808a, 0x80008000, 0x0000808b, 0x80000001, 0x80008081, 0x00008009,
+  0x0000008a, 0x00000088, 0x80008009, 0x8000000a, 0x8000808b, 0x0000008b, 0x00008089, 0x00008003,
+  0x00008002, 0x00000080, 0x0000800a, 0x8000000a, 0x80008081, 0x00008080, 0x80000001, 0x80008008,
+];
+
+// Rotation offsets r[x,y] for the rho step, indexed by lane number (x + 5*y). Lane 0 is never rotated.
+const RHO = [
+  0, 1, 62, 28, 27, 36, 44, 6, 55, 20, 3, 10, 43, 25, 39, 41, 45, 15, 21, 8, 18, 2, 61, 56, 14,
+];
+// pi permutation: destination lane for each source lane. pi maps (x,y) -> (y, 2x+3y), so source lane
+// (x + 5y) is written to lane (y + 5*((2x+3y) mod 5)); PI[src] = dst.
+const PI = [
+  0, 10, 20, 5, 15, 16, 1, 11, 21, 6, 7, 17, 2, 12, 22, 23, 8, 18, 3, 13, 14, 24, 9, 19, 4,
+];
+
+// The state is 25 lanes; we hold each lane as two 32-bit halves in parallel arrays sLo/sHi (index = lane).
+
+// Keccak-f[1600] permutation, in place, on (sLo, sHi). 24 rounds of theta, rho+pi, chi, iota.
+function keccakF(sLo, sHi) {
+  const bcLo = new Array(5);
+  const bcHi = new Array(5);
+  const tLo = new Array(25);
+  const tHi = new Array(25);
+
+  for (let round = 0; round < 24; round++) {
+    // --- theta ---
+    for (let x = 0; x < 5; x++) {
+      bcLo[x] = sLo[x] ^ sLo[x + 5] ^ sLo[x + 10] ^ sLo[x + 15] ^ sLo[x + 20];
+      bcHi[x] = sHi[x] ^ sHi[x + 5] ^ sHi[x + 10] ^ sHi[x + 15] ^ sHi[x + 20];
+    }
+    for (let x = 0; x < 5; x++) {
+      // d = bc[x-1] XOR rotl1(bc[x+1])
+      const x1 = (x + 1) % 5;
+      const x4 = (x + 4) % 5;
+      const rotLo = ((bcLo[x1] << 1) | (bcHi[x1] >>> 31)) >>> 0;
+      const rotHi = ((bcHi[x1] << 1) | (bcLo[x1] >>> 31)) >>> 0;
+      const dLo = (bcLo[x4] ^ rotLo) >>> 0;
+      const dHi = (bcHi[x4] ^ rotHi) >>> 0;
+      for (let y = 0; y < 25; y += 5) {
+        sLo[x + y] = (sLo[x + y] ^ dLo) >>> 0;
+        sHi[x + y] = (sHi[x + y] ^ dHi) >>> 0;
+      }
+    }
+
+    // --- rho + pi --- (write permuted, rotated lanes into t)
+    for (let i = 0; i < 25; i++) {
+      const r = RHO[i];
+      const dest = PI[i];
+      let outLo, outHi;
+      if (r === 0) {
+        outLo = sLo[i];
+        outHi = sHi[i];
+      } else if (r < 32) {
+        outLo = ((sLo[i] << r) | (sHi[i] >>> (32 - r))) >>> 0;
+        outHi = ((sHi[i] << r) | (sLo[i] >>> (32 - r))) >>> 0;
+      } else if (r === 32) {
+        outLo = sHi[i];
+        outHi = sLo[i];
+      } else {
+        const rr = r - 32;
+        outLo = ((sHi[i] << rr) | (sLo[i] >>> (32 - rr))) >>> 0;
+        outHi = ((sLo[i] << rr) | (sHi[i] >>> (32 - rr))) >>> 0;
+      }
+      tLo[dest] = outLo;
+      tHi[dest] = outHi;
+    }
+
+    // --- chi --- a[x] = t[x] XOR ((NOT t[x+1]) AND t[x+2]), per row
+    for (let y = 0; y < 25; y += 5) {
+      for (let x = 0; x < 5; x++) {
+        const x1 = y + ((x + 1) % 5);
+        const x2 = y + ((x + 2) % 5);
+        sLo[y + x] = (tLo[y + x] ^ (~tLo[x1] & tLo[x2])) >>> 0;
+        sHi[y + x] = (tHi[y + x] ^ (~tHi[x1] & tHi[x2])) >>> 0;
+      }
+    }
+
+    // --- iota ---
+    sLo[0] = (sLo[0] ^ RC_LO[round]) >>> 0;
+    sHi[0] = (sHi[0] ^ RC_HI[round]) >>> 0;
+  }
+}
+
+// keccak256 over `bytes` (a Uint8Array/Buffer or array of byte values), returning a 32-byte Uint8Array.
+// Rate r = 1088 bits = 136 bytes (c = 512), original Keccak padding (0x01 .. 0x80), 256-bit output.
+function keccak256Bytes(bytes) {
+  const RATE = 136; // bytes absorbed per permutation
+  const sLo = new Array(25).fill(0);
+  const sHi = new Array(25).fill(0);
+
+  // Build the padded message: append a single 0x01 domain/pad start byte, zero-fill, set the high bit
+  // (0x80) of the final rate block. (If the 0x01 lands on the last byte of a block, it merges to 0x81.)
+  const inLen = bytes.length;
+  const padLen = RATE - (inLen % RATE); // 1..RATE, guarantees room for the 0x01 and 0x80 markers
+  const total = inLen + padLen;
+  const msg = new Uint8Array(total);
+  for (let i = 0; i < inLen; i++) msg[i] = bytes[i] & 0xff;
+  msg[inLen] = 0x01; // start of the original-Keccak pad (NOT SHA3's 0x06)
+  msg[total - 1] = (msg[total - 1] | 0x80) & 0xff; // final-block high bit
+
+  // Absorb: XOR each RATE-byte block into the state (little-endian lanes) and permute.
+  for (let off = 0; off < total; off += RATE) {
+    for (let i = 0; i < RATE; i += 8) {
+      const lane = i >> 3; // lane index within the rate region (0..16), block-relative
+      const b = off + i;
+      const lo =
+        ((msg[b] | (msg[b + 1] << 8) | (msg[b + 2] << 16) | (msg[b + 3] << 24)) >>> 0);
+      const hi =
+        ((msg[b + 4] | (msg[b + 5] << 8) | (msg[b + 6] << 16) | (msg[b + 7] << 24)) >>> 0);
+      sLo[lane] = (sLo[lane] ^ lo) >>> 0;
+      sHi[lane] = (sHi[lane] ^ hi) >>> 0;
+    }
+    keccakF(sLo, sHi);
+  }
+
+  // Squeeze 256 bits = 32 bytes = the first 4 lanes (little-endian), no further permutation needed.
+  const out = new Uint8Array(32);
+  for (let lane = 0; lane < 4; lane++) {
+    const lo = sLo[lane];
+    const hi = sHi[lane];
+    const base = lane * 8;
+    out[base] = lo & 0xff;
+    out[base + 1] = (lo >>> 8) & 0xff;
+    out[base + 2] = (lo >>> 16) & 0xff;
+    out[base + 3] = (lo >>> 24) & 0xff;
+    out[base + 4] = hi & 0xff;
+    out[base + 5] = (hi >>> 8) & 0xff;
+    out[base + 6] = (hi >>> 16) & 0xff;
+    out[base + 7] = (hi >>> 24) & 0xff;
+  }
+  return out;
+}
+
+// Lowercase hex (no 0x prefix) of a byte array — used by the hex-string entry point.
+function toHex(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i] & 0xff;
+    s += (b < 16 ? "0" : "") + b.toString(16);
+  }
+  return s;
+}
+
+/**
+ * keccak256 over a byte buffer.
+ * @param {Uint8Array|Buffer|number[]} bytes input bytes
+ * @returns {Uint8Array} the 32-byte digest
+ */
+function keccak256(bytes) {
+  if (
+    !(bytes instanceof Uint8Array) &&
+    !Array.isArray(bytes) &&
+    !(typeof Buffer !== "undefined" && Buffer.isBuffer && Buffer.isBuffer(bytes))
+  ) {
+    throw new TypeError("keccak256 requires a Uint8Array/Buffer/byte-array of input bytes");
+  }
+  return keccak256Bytes(bytes);
+}
+
+/**
+ * keccak256 over a byte buffer, returned as a lowercase hex string WITHOUT a 0x prefix
+ * (matching `js-sha3`'s keccak256().hex() output, for drop-in cross-checking).
+ * @param {Uint8Array|Buffer|number[]} bytes input bytes
+ * @returns {string} 64-char lowercase hex
+ */
+function keccak256Hex(bytes) {
+  return toHex(keccak256(bytes));
+}
+
+module.exports = { keccak256, keccak256Hex };
+
+};
+
+// ===== module: keccak  (from verifier/lib/keccak.js) =====
+__modules["keccak"] = function (module, exports, __require) {
+"use strict";
+// Inlined keccak provider for the standalone bundle: the SAME `keccak256(bytes) -> Buffer` surface as
+// verifier/lib/keccak.js, but backed by the PURE-JS, zero-dependency vendored implementation
+// (verifier/lib/keccak256-vendored.js) instead of js-sha3 — so the bundle requires nothing external.
+var vendored = __require("keccak256-vendored");
+function keccak256(bytes) {
+  if (!(bytes instanceof Uint8Array) && !Buffer.isBuffer(bytes)) {
+    throw new TypeError("keccak256 requires a Buffer/Uint8Array of input bytes");
+  }
+  // The vendored routine returns a Uint8Array; wrap it as a Buffer so downstream `.slice(...).toString
+  // ("hex")` and `Buffer.concat([...])` callers behave exactly as they do with the js-sha3-backed shim.
+  return Buffer.from(vendored.keccak256(bytes));
+}
+module.exports = { keccak256 };
+};
+
+// ===== module: merkle  (from verifier/lib/merkle.js) =====
+__modules["merkle"] = function (module, exports, __require) {
+"use strict";
+
+// verifier/lib/merkle.js — INDEPENDENT re-derivation of the family's path-bound, domain-separated
+// Merkle convention, using ONLY ./keccak (js-sha3). NO ethers, NO hardhat, NO require back into cli/.
+//
+// WHY THIS EXISTS
+//   To verify an evidence seal / reconciliation seal / proof bundle OFFLINE without the producer stack,
+//   the independent verifier must RE-DERIVE the same per-file leaves and the same Merkle root the
+//   producer (cli/hash.js) computes. cli/hash.js uses `ethers` (keccak256/concat/toUtf8Bytes), which the
+//   verifier explicitly refuses to depend on. So this file reproduces the EXACT byte composition of
+//   pathLeaf / leafHash / nodeHash / buildTree from first principles — and test/verifier.cli.test.js
+//   cross-checks the result is byte-identical to the producer's. The two can never silently diverge.
+//
+// THE CONVENTION (must match cli/hash.js VERBATIM)
+//   * content digest      c          = keccak256(file bytes)
+//   * DIR_LEAF_DOMAIN      = keccak256("verifyhash/dir-leaf/v1")  (a fixed 32-byte prefix)
+//   * path-bound leaf      pathLeaf   = keccak256(DIR_LEAF_DOMAIN ++ utf8(relPath) ++ 0x00 ++ c)
+//   * tagged leaf          leafHash   = keccak256(0x00 ++ leaf)
+//   * interior node        nodeHash   = keccak256(0x01 ++ min(a,b) ++ max(a,b))   (sorted 32-byte pair)
+//   * tree                 sorted-leaf, "duplicate the lone odd node" pairing (OpenZeppelin style)
+//   relPath is normalized with no leading "./", exactly as the producer's toPosixRel does. CRUCIALLY
+//   this must be BYTE-FOR-BYTE the producer's normalization (cli/hash.js#toPosixRel) — see toPosixRel
+//   below — or the verifier would re-derive a DIFFERENT root than the producer sealed for some input
+//   class and would either falsely reject a genuine artifact or falsely accept the wrong one.
+
+const { keccak256 } = __require("keccak");
+
+// Domain tags, byte-identical to ContributionRegistry / cli/hash.js LEAF_TAG / NODE_TAG.
+const LEAF_TAG = Buffer.from([0x00]);
+const NODE_TAG = Buffer.from([0x01]);
+const PATH_SEP = Buffer.from([0x00]);
+
+// The fixed, versioned domain prefix for path-bound directory leaves: keccak256 of the ASCII tag.
+const DIR_LEAF_DOMAIN_STR = "verifyhash/dir-leaf/v1";
+const DIR_LEAF_DOMAIN = keccak256(Buffer.from(DIR_LEAF_DOMAIN_STR, "utf8")); // 32-byte Buffer
+
+const HEX32_RE = /^0x[0-9a-fA-F]{64}$/;
+
+// 0x-hex string (no 0x, lowercase) <-> 32-byte Buffer.
+function hexToBuf32(hex) {
+  if (typeof hex !== "string" || !HEX32_RE.test(hex)) {
+    throw new Error(`expected a 0x-prefixed 32-byte hex string, got: ${String(hex)}`);
+  }
+  return Buffer.from(hex.slice(2), "hex");
+}
+function bufToHex(buf) {
+  return "0x" + Buffer.from(buf).toString("hex");
+}
+
+/** keccak256 of raw bytes, returned as a 0x-prefixed 32-byte hex string (matches cli/hash.js hashBytes). */
+function hashBytes(bytes) {
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  return bufToHex(keccak256(buf));
+}
+
+/**
+ * Normalize a relPath EXACTLY as the producer (cli/hash.js#toPosixRel) does, so the verifier
+ * re-derives the IDENTICAL root the producer sealed. The producer is `split(path.sep).join("/")`
+ * then `.replace(/^\.\//, "")`. The artifacts the verifier reads carry relPaths the producer wrote,
+ * and those are produced on POSIX hosts (cli/evidence.js#loadDirEntries does the same `path.sep`
+ * split) — where `path.sep === "/"`, so the split/join is a no-op and a literal backslash byte is a
+ * CONTENT byte that survives into the hash. We therefore must NOT collapse backslashes: a previous
+ * version unconditionally mapped "\\"->"/", which made the verifier hash `a/b.txt` while the producer
+ * hashed `a\b.txt` — a silent root divergence that could falsely REJECT a genuine backslash-named
+ * directory or falsely ACCEPT one where `a/b.txt` and `a\b.txt` collide. All we strip is the leading
+ * "./", which the producer also strips on every host. (Windows-authored relPaths, if ever needed,
+ * must be converted to "/" on BOTH the producer and verifier sides identically — not only here.)
+ */
+function toPosixRel(relPath) {
+  return String(relPath).replace(/^\.\//, "");
+}
+
+/**
+ * pathLeaf(relPath, contentDigest) = keccak256(DIR_LEAF_DOMAIN ++ utf8(relPath) ++ 0x00 ++ c).
+ * @param {string} relPath
+ * @param {string} contentDigest 0x bytes32
+ * @returns {string} 0x bytes32
+ */
+function pathLeaf(relPath, contentDigest) {
+  const relBytes = Buffer.from(toPosixRel(relPath), "utf8");
+  const c = hexToBuf32(contentDigest);
+  return bufToHex(keccak256(Buffer.concat([DIR_LEAF_DOMAIN, relBytes, PATH_SEP, c])));
+}
+
+/** leafHash(c) = keccak256(LEAF_TAG ++ c). */
+function leafHash(c) {
+  return bufToHex(keccak256(Buffer.concat([LEAF_TAG, hexToBuf32(c)])));
+}
+
+/** nodeHash(a,b) = keccak256(NODE_TAG ++ min(a,b) ++ max(a,b)) comparing as 32-byte big-endian values. */
+function nodeHash(a, b) {
+  const A = hexToBuf32(a);
+  const B = hexToBuf32(b);
+  const [lo, hi] = Buffer.compare(A, B) <= 0 ? [A, B] : [B, A];
+  return bufToHex(keccak256(Buffer.concat([NODE_TAG, lo, hi])));
+}
+
+/**
+ * Build the sorted-leaf, domain-separated Merkle root from an array of per-file PATH-BOUND leaves
+ * (the same values pathLeaf produces). Leaves are sorted ascending by their 32-byte value, tagged via
+ * leafHash, then folded with nodeHash, pairing a lone odd node with itself — byte-identical to
+ * cli/hash.js buildTree's root.
+ * @param {string[]} leaves array of 0x bytes32 path-bound leaves
+ * @returns {string} the 0x bytes32 root
+ */
+function rootFromLeaves(leaves) {
+  if (!Array.isArray(leaves) || leaves.length === 0) {
+    throw new Error("cannot build a Merkle tree from zero leaves");
+  }
+  const sorted = leaves
+    .slice()
+    .sort((a, b) => Buffer.compare(hexToBuf32(a), hexToBuf32(b)));
+  let layer = sorted.map((c) => leafHash(c));
+  while (layer.length > 1) {
+    const next = [];
+    for (let i = 0; i < layer.length; i += 2) {
+      const right = i + 1 < layer.length ? layer[i + 1] : layer[i];
+      next.push(nodeHash(layer[i], right));
+    }
+    layer = next;
+  }
+  return layer[0];
+}
+
+/**
+ * Re-derive the top-level root from a flat list of { relPath, contentHash } — the SAME computation the
+ * seal cores use: pathLeaf each, then rootFromLeaves. PURE.
+ * @param {{relPath:string, contentHash:string}[]} flat
+ * @returns {string} 0x bytes32 root
+ */
+function rootFromFlat(flat) {
+  return rootFromLeaves(flat.map((e) => pathLeaf(e.relPath, e.contentHash)));
+}
+
+module.exports = {
+  HEX32_RE,
+  DIR_LEAF_DOMAIN_STR,
+  hashBytes,
+  toPosixRel,
+  pathLeaf,
+  leafHash,
+  nodeHash,
+  rootFromLeaves,
+  rootFromFlat,
+};
+
+};
+
+// ===== module: canonical  (from verifier/lib/canonical.js) =====
+__modules["canonical"] = function (module, exports, __require) {
+"use strict";
+
+// verifier/lib/canonical.js — INDEPENDENT canonical UNSIGNED serialization.
+//
+// WHY THIS EXISTS
+//   For the independent `verifier/` to sign/hash over BYTE-IDENTICAL input to the production path, it must
+//   reproduce the family's canonical UNSIGNED serialization itself — WITHOUT importing the producer code in
+//   `cli/`. If the verifier imported `cli/dataset.js`'s `serializeAttestation`, a cross-check would be
+//   circular (it would be comparing a function to itself). So this file re-derives the SAME byte string,
+//   from first principles, and the cross-check test asserts it equals what the producer emits.
+//
+// THE CANONICAL CONVENTION (must match cli/core/attestation.js + cli/dataset.js#serializeAttestation)
+//   * A FIXED key order — NOT JSON.stringify's insertion order by accident, but an EXPLICIT ordered key
+//     list per object shape. We emit keys in that exact order.
+//   * NO insignificant whitespace (separators ",", ":").
+//   * A SINGLE trailing newline ("\n") terminating the document.
+//   The result is byte-deterministic: the same logical value always serializes to the same bytes.
+
+/**
+ * Serialize a value to canonical JSON with an EXPLICIT key order, no insignificant whitespace, and NO
+ * trailing newline (the newline is the document-level convention added by the envelope serializers below).
+ *
+ * Key order: when `keyOrder[<path-or-shape>]` is provided we use it; otherwise keys are emitted in the
+ * object's own insertion order (matching the producer's explicit object literals, which V8 preserves).
+ * Because the producers always build their canonical objects via explicit ordered literals, reproducing
+ * that same ordered literal here yields byte-identical output WITHOUT a generic key-sorting pass.
+ *
+ * This is a minimal, dependency-free JSON emitter that matches JSON.stringify's escaping for the value
+ * shapes this family uses (strings, integers, booleans, null, nested objects/arrays).
+ *
+ * @param {*} value
+ * @returns {string} canonical JSON (no trailing newline)
+ */
+function canonicalJson(value) {
+  // JSON.stringify with no spacing already emits ","/":" separators and standard string escaping with no
+  // insignificant whitespace. The ONLY thing it does not do for us is reorder keys — but the family's
+  // canonical objects are built as explicit ordered literals, so insertion order IS the canonical order.
+  // We therefore use JSON.stringify directly on a value whose keys are already in canonical order. This is
+  // intentionally the SAME primitive the producer uses, but driven from an INDEPENDENTLY constructed,
+  // explicitly-ordered object here (so the bytes are reproduced, not imported).
+  return JSON.stringify(value);
+}
+
+/**
+ * Reproduce the canonical UNSIGNED dataset-attestation bytes, byte-for-byte identical to
+ * `cli/dataset.js#serializeAttestation` — WITHOUT importing it.
+ *
+ * Canonical top-level key order (from the producer's explicit object literal):
+ *   kind, schemaVersion, note, root, fileCount, manifestDigest, signed, signature
+ * then a single trailing newline.
+ *
+ * @param {object} env a validated UNSIGNED attestation envelope
+ * @returns {string} the canonical serialization (newline-terminated)
+ */
+function serializeUnsignedDatasetAttestation(env) {
+  if (env == null || typeof env !== "object" || Array.isArray(env)) {
+    throw new Error("serializeUnsignedDatasetAttestation requires an attestation envelope object");
+  }
+  // Build the canonical object via an EXPLICIT ordered literal — independently of the producer.
+  const canonical = {
+    kind: env.kind,
+    schemaVersion: env.schemaVersion,
+    note: env.note,
+    root: env.root,
+    fileCount: env.fileCount,
+    manifestDigest: env.manifestDigest,
+    signed: env.signed,
+    signature: env.signature,
+  };
+  return canonicalJson(canonical) + "\n";
+}
+
+/**
+ * Generic canonical envelope serializer for the family's signed-attestation containers, reproducing
+ * `cli/core/attestation.js#serializeSignedAttestation` byte-for-byte WITHOUT importing it.
+ *
+ * Canonical key order: kind, schemaVersion, note, attestation, signature{scheme,signer,signature}
+ * then a single trailing newline.
+ *
+ * @param {object} container a signed-attestation container
+ * @returns {string} the canonical serialization (newline-terminated)
+ */
+function serializeSignedContainer(container) {
+  if (container == null || typeof container !== "object" || Array.isArray(container)) {
+    throw new Error("serializeSignedContainer requires a signed-attestation container object");
+  }
+  const sig = container.signature || {};
+  const canonical = {
+    kind: container.kind,
+    schemaVersion: container.schemaVersion,
+    note: container.note,
+    attestation: container.attestation,
+    signature: {
+      scheme: sig.scheme,
+      signer: sig.signer,
+      signature: sig.signature,
+    },
+  };
+  return canonicalJson(canonical) + "\n";
+}
+
+// The reserved relPath of the synthetic HEADER leaf a reconciliation seal binds its verdict + input
+// role partition into, byte-identical to trustledger/seal.js#SEAL_HEADER_RELPATH. A real file may not
+// occupy it; the verifier folds the header content in under this relPath when re-deriving the root.
+const TRUST_SEAL_HEADER_RELPATH = "__trustledger.seal-header__v1";
+
+/**
+ * Reproduce the canonical "content" bytes of a reconciliation seal's verdict/role HEADER entry, byte-for-
+ * byte identical to trustledger/seal.js#_headerBytes — WITHOUT importing it. The header binds the recorded
+ * verdict (pass/reportDate/period) + each input's logical role→relPath into the SAME committed Merkle
+ * root as the files, so a verdict/role edit changes the header content -> its leaf -> the root.
+ *
+ * Canonical layout (FIXED key order, no insignificant whitespace, roles sorted by role):
+ *   { v: 1, verdict: { pass, reportDate, period }, roles: [{ role, relPath }, ...] }
+ *
+ * @param {object} verdict { pass, reportDate, period }
+ * @param {{role:string, relPath:string}[]} inputs the seal's input role bindings
+ * @returns {Buffer} the canonical UTF-8 header content
+ */
+function trustSealHeaderBytes(verdict, inputs) {
+  const canonical = {
+    v: 1,
+    verdict: {
+      pass: verdict.pass,
+      reportDate: verdict.reportDate,
+      period: verdict.period == null ? null : String(verdict.period),
+    },
+    roles: inputs
+      .map((i) => ({ role: i.role, relPath: i.relPath }))
+      .sort((a, b) => (a.role < b.role ? -1 : a.role > b.role ? 1 : 0)),
+  };
+  return Buffer.from(JSON.stringify(canonical), "utf8");
+}
+
+module.exports = {
+  canonicalJson,
+  serializeUnsignedDatasetAttestation,
+  serializeSignedContainer,
+  TRUST_SEAL_HEADER_RELPATH,
+  trustSealHeaderBytes,
+};
+
+};
+
+// ===== module: secp256k1-recover  (from verifier/lib/secp256k1-recover.js) =====
+__modules["secp256k1-recover"] = function (module, exports, __require) {
+"use strict";
+
+// verifier/lib/secp256k1-recover.js — INDEPENDENT EIP-191 personal_sign signer recovery.
+//
+// WHY THIS EXISTS
+//   `verifier/` is a near-zero-dependency, SECOND implementation of the family's signature recovery, kept
+//   deliberately separate from the production ethers path so the two can be CROSS-CHECKED and can never
+//   silently drift (the anti-divergence guard in test/verifier.crypto.test.js). This file recovers the
+//   secp256k1 signer ADDRESS from an `eip191-personal-sign` 65-byte (r||s||v) signature over a message,
+//   using ONLY:
+//     * `js-sha3` (via ./keccak) for keccak256, and
+//     * a single, tiny, vendored elliptic-curve routine (below) for the secp256k1 public-key RECOVERY.
+//   It does NOT require `ethers`, `hardhat`, `cli/`, or `trustledger/`.
+//
+// THE secp256k1 ROUTINE (vendored, audited, standard)
+//   Public-key recovery from an ECDSA signature is textbook curve math over the secp256k1 group
+//   (SEC 1, §4.1.6 / §2.3). We implement exactly that with Node BigInt: affine point add/double on
+//   y^2 = x^3 + 7 (mod p), a constant-time-agnostic double-and-add scalar multiply, and a Tonelli-Shanks
+//   style square root (p ≡ 3 mod 4, so √a = a^((p+1)/4)). No randomness, no secrets — recovery is a PUBLIC
+//   computation over the signature + message hash, so timing/side-channels are irrelevant here. The curve
+//   constants are the canonical secp256k1 domain parameters.
+
+const { keccak256 } = __require("keccak");
+
+// ---- secp256k1 domain parameters (canonical) -------------------------------------------------------
+const P = 0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2fn; // field prime
+const N = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n; // group order
+const A = 0n; // curve a
+const B = 7n; // curve b
+const GX = 0x79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798n;
+const GY = 0x483ada7726a3c4655da4fbfc0e1108a8fd17b448a68554199c47d08ffb10d4b8n;
+
+// ---- modular arithmetic helpers --------------------------------------------------------------------
+function mod(a, m) {
+  const r = a % m;
+  return r >= 0n ? r : r + m;
+}
+
+// Modular inverse via the extended Euclidean algorithm (m is prime here, so a is invertible unless 0).
+function invmod(a, m) {
+  a = mod(a, m);
+  if (a === 0n) throw new Error("secp256k1: inverse of zero");
+  let [old_r, r] = [a, m];
+  let [old_s, s] = [1n, 0n];
+  while (r !== 0n) {
+    const q = old_r / r;
+    [old_r, r] = [r, old_r - q * r];
+    [old_s, s] = [s, old_s - q * s];
+  }
+  return mod(old_s, m);
+}
+
+// Modular exponentiation (square-and-multiply).
+function powmod(base, exp, m) {
+  base = mod(base, m);
+  let result = 1n;
+  while (exp > 0n) {
+    if (exp & 1n) result = mod(result * base, m);
+    base = mod(base * base, m);
+    exp >>= 1n;
+  }
+  return result;
+}
+
+// Square root mod p. secp256k1's p ≡ 3 (mod 4), so √a = a^((p+1)/4) mod p (when a is a QR).
+function sqrtmod(a) {
+  const r = powmod(a, (P + 1n) / 4n, P);
+  if (mod(r * r, P) !== mod(a, P)) throw new Error("secp256k1: no square root (x not on curve)");
+  return r;
+}
+
+// ---- elliptic-curve point arithmetic (affine; null = point at infinity) ---------------------------
+const INF = null;
+
+function isInf(Pt) {
+  return Pt === INF;
+}
+
+function pointAdd(p1, p2) {
+  if (isInf(p1)) return p2;
+  if (isInf(p2)) return p1;
+  const [x1, y1] = p1;
+  const [x2, y2] = p2;
+  if (x1 === x2 && mod(y1 + y2, P) === 0n) return INF; // p1 = -p2
+  let m;
+  if (x1 === x2 && y1 === y2) {
+    // doubling: m = (3x^2 + a) / (2y)
+    m = mod((3n * x1 * x1 + A) * invmod(2n * y1, P), P);
+  } else {
+    m = mod((y2 - y1) * invmod(x2 - x1, P), P);
+  }
+  const x3 = mod(m * m - x1 - x2, P);
+  const y3 = mod(m * (x1 - x3) - y1, P);
+  return [x3, y3];
+}
+
+function scalarMul(k, point) {
+  k = mod(k, N);
+  let result = INF;
+  let addend = point;
+  while (k > 0n) {
+    if (k & 1n) result = pointAdd(result, addend);
+    addend = pointAdd(addend, addend);
+    k >>= 1n;
+  }
+  return result;
+}
+
+const G = [GX, GY];
+
+// Decompress the curve point with x-coordinate `x` and the given y-parity (0 = even, 1 = odd).
+function liftX(x, yParity) {
+  const alpha = mod(x * x * x + A * x + B, P); // y^2
+  let y = sqrtmod(alpha);
+  if ((y & 1n) !== BigInt(yParity)) y = mod(P - y, P);
+  return [x, y];
+}
+
+// ---- big-endian buffer <-> BigInt ------------------------------------------------------------------
+function bufToBig(buf) {
+  let n = 0n;
+  for (const b of buf) n = (n << 8n) | BigInt(b);
+  return n;
+}
+
+function bigTo32(n) {
+  const out = Buffer.alloc(32);
+  for (let i = 31; i >= 0; i--) {
+    out[i] = Number(n & 0xffn);
+    n >>= 8n;
+  }
+  return out;
+}
+
+/**
+ * Recover the secp256k1 PUBLIC KEY from an ECDSA signature + 32-byte message hash (SEC 1, §4.1.6).
+ * @param {Buffer} msgHash 32-byte hash that was signed
+ * @param {bigint} r       signature r
+ * @param {bigint} s       signature s
+ * @param {number} recId   recovery id 0..3 (derived from v)
+ * @returns {{x: bigint, y: bigint}} the recovered public-key point
+ */
+function recoverPublicKey(msgHash, r, s, recId) {
+  if (r <= 0n || r >= N) throw new Error("secp256k1: r out of range");
+  if (s <= 0n || s >= N) throw new Error("secp256k1: s out of range");
+  if (recId < 0 || recId > 3) throw new Error("secp256k1: invalid recovery id");
+
+  // x = r + (recId >> 1) * N  (the high bit of recId says whether r overflowed the field by one order)
+  const x = r + (recId >> 1 ? N : 0n);
+  if (x >= P) throw new Error("secp256k1: recovered x not in field");
+
+  // R = point with x-coordinate x and y-parity = (recId & 1).
+  const R = liftX(x, recId & 1);
+
+  // Q = r^-1 (s*R - e*G), where e = msgHash mod N.
+  const e = mod(bufToBig(msgHash), N);
+  const rInv = invmod(r, N);
+  const sR = scalarMul(s, R);
+  const eG = scalarMul(e, G);
+  const negEG = isInf(eG) ? INF : [eG[0], mod(P - eG[1], P)];
+  const Q = scalarMul(rInv, pointAdd(sR, negEG));
+  if (isInf(Q)) throw new Error("secp256k1: recovered point at infinity");
+  return { x: Q[0], y: Q[1] };
+}
+
+/**
+ * Derive the lowercase 0x Ethereum address from a recovered public-key point.
+ * address = "0x" + last 20 bytes of keccak256( X(32) || Y(32) ).
+ */
+function pubKeyToAddress(pub) {
+  const raw = Buffer.concat([bigTo32(pub.x), bigTo32(pub.y)]); // 64-byte uncompressed (no 0x04 prefix)
+  const hash = keccak256(raw);
+  return "0x" + hash.slice(12).toString("hex");
+}
+
+/**
+ * Build the EIP-191 personal_sign pre-image for a message and return its keccak256 digest.
+ *
+ * EIP-191 personal_sign: keccak256( "\x19Ethereum Signed Message:\n" + <decimal byte length> + <message> ),
+ * where <message> is the EXACT canonical UTF-8 bytes (here, the canonical attestation string including its
+ * single trailing newline). This reproduces, byte-for-byte, what `cli/core/attestation.js` documents and
+ * what ethers' personal_sign hashes.
+ *
+ * @param {Buffer|Uint8Array|string} message UTF-8 message (string is encoded as UTF-8)
+ * @returns {Buffer} the 32-byte EIP-191 digest
+ */
+function eip191Hash(message) {
+  const msgBytes = Buffer.isBuffer(message)
+    ? message
+    : message instanceof Uint8Array
+    ? Buffer.from(message)
+    : Buffer.from(String(message), "utf8");
+  const prefix = Buffer.from("\x19Ethereum Signed Message:\n" + msgBytes.length, "utf8");
+  return keccak256(Buffer.concat([prefix, msgBytes]));
+}
+
+/**
+ * Recover the lowercase 0x signer ADDRESS from an `eip191-personal-sign` 65-byte (r||s||v) signature over
+ * `message`. INDEPENDENT of ethers/hardhat — only ./keccak (js-sha3) + the vendored secp256k1 above.
+ *
+ * @param {Buffer|Uint8Array|string} message    the EXACT canonical UTF-8 bytes that were signed
+ * @param {string|Buffer|Uint8Array} signature  65-byte r(32)||s(32)||v(1), as 0x-hex or raw bytes
+ * @returns {string} the recovered signer address, 0x-prefixed lowercase
+ */
+function recoverPersonalSignAddress(message, signature) {
+  const sig = normalizeSig(signature);
+  const r = bufToBig(sig.subarray(0, 32));
+  const s = bufToBig(sig.subarray(32, 64));
+  let v = sig[64];
+  // Accept v in {0,1} or {27,28} (and EIP-155-ish higher v reduced to parity). recId is v's low bit.
+  if (v >= 27) v -= 27;
+  if (v !== 0 && v !== 1) {
+    // Fall back to parity for any non-canonical encoding; reject only the wildly invalid.
+    v = v & 1;
+  }
+  const digest = eip191Hash(message);
+  const pub = recoverPublicKey(digest, r, s, v);
+  return pubKeyToAddress(pub);
+}
+
+function normalizeSig(signature) {
+  let buf;
+  if (Buffer.isBuffer(signature)) {
+    buf = signature;
+  } else if (signature instanceof Uint8Array) {
+    buf = Buffer.from(signature);
+  } else if (typeof signature === "string") {
+    const hex = signature.startsWith("0x") || signature.startsWith("0X") ? signature.slice(2) : signature;
+    if (!/^[0-9a-fA-F]*$/.test(hex) || hex.length % 2 !== 0) {
+      throw new Error("secp256k1: signature must be 0x-hex (even length)");
+    }
+    buf = Buffer.from(hex, "hex");
+  } else {
+    throw new TypeError("secp256k1: signature must be a 0x-hex string or byte buffer");
+  }
+  if (buf.length !== 65) {
+    throw new Error(`secp256k1: eip191-personal-sign signature must be 65 bytes (r||s||v), got ${buf.length}`);
+  }
+  return buf;
+}
+
+module.exports = {
+  recoverPersonalSignAddress,
+  eip191Hash,
+  recoverPublicKey,
+  pubKeyToAddress,
+  // exported for tests/audit:
+  _internal: { mod, invmod, powmod, sqrtmod, pointAdd, scalarMul, liftX, G, N, P },
+};
+
+};
+
+// ===== module: revocation-core  (from verifier/lib/revocation-core.js) =====
+__modules["revocation-core"] = function (module, exports, __require) {
+"use strict";
+
+// verifier/lib/revocation-core.js — the PURE (I/O-FREE, fs-FREE, path-FREE, clock-FREE) half of the
+// stack-free recipient-side KEY-REVOCATION reader + as-of decision (EPIC-51 / T-51.4, split out by T-66.1).
+//
+// WHY THIS FILE IS SEPARATE
+//   T-66.1 gives the independent verifier an IN-MEMORY file-source seam (`verifyArtifactFromBytes`) whose
+//   whole code path must be portable off Node (a browser page, a vm sandbox): NO `fs`, NO `path`, NO `os`,
+//   NO `process` may be reachable from it — statically, at module scope (the same discipline
+//   trustledger/lib/policy-bundled-loader.js established for the TrustLedger browser core). The revocation
+//   DECISION (validate + recover + classify + as-of fold) was always pure, but it lived in the same module
+//   as the FILE/DIR reader, which requires `fs` + `path` at module scope. This file is the decision, alone:
+//   every function here is a pure function of its arguments; requiring this module touches NOTHING impure.
+//   verifier/lib/revocation.js re-exports everything from here VERBATIM (the same function objects) and adds
+//   the two — and only two — fs-backed conveniences (`readRevocationsFromPath`, `loadAndApply`), so every
+//   existing caller keeps its exact surface and byte-identical behavior.
+//
+// EVERYTHING BELOW IS MOVED VERBATIM from verifier/lib/revocation.js (no semantic edit) — see that file's
+// header for the full design rationale (the load-bearing self-control invariant, subject scoping, and the
+// gate-for-gate parity with the producer stack's cli/core/trust-asof.js + cli/core/revocation.js).
+
+const { recoverPersonalSignAddress } = __require("secp256k1-recover");
+
+// ---------------------------------------------------------------------------
+// On-disk discriminators + grammars — byte-identical to cli/core/revocation.js so a producer-minted
+// revocation reads here verbatim.
+// ---------------------------------------------------------------------------
+
+const SIGNED_REVOCATION_KIND = "vh-key-revocation-signed";
+const REVOCATION_KIND = "vh-key-revocation";
+
+// The SCHEMA versions this build understands — byte-identical to cli/core/revocation.js's
+// SUPPORTED_*_SCHEMA_VERSIONS. The producer REJECTS (IGNORES) a revocation whose container OR embedded
+// payload carries an unsupported schemaVersion, so the verifier must too (parity).
+const REVOCATION_SCHEMA_VERSION = 1;
+const SUPPORTED_REVOCATION_SCHEMA_VERSIONS = Object.freeze([1]);
+const SUPPORTED_SIGNED_REVOCATION_SCHEMA_VERSIONS = Object.freeze([1]);
+
+// The CLOSED reason set (the producer's REVOCATION_REASON_SET, sorted). An out-of-set reason marks the
+// embedded revocation structurally malformed — the entry is IGNORED (never silently honored).
+const REVOCATION_REASON_SET = Object.freeze(["compromised", "retired", "rotated", "superseded"]);
+
+// The CLOSED field set of an UNSIGNED revocation payload — byte-identical to cli/core/revocation.js's
+// REVOCATION_FIELDS. The producer HARD-rejects any extraneous/unknown key (validateRevocation), IGNORING
+// the revocation; the verifier must enforce the SAME closed set so a smuggled extra field can never make
+// the two stacks disagree (a self-signed-but-non-canonical revocation the producer ignores must be ignored
+// here too). `supersededBy` is OPTIONAL but a member of the set.
+const REVOCATION_FIELDS = Object.freeze([
+  "kind",
+  "schemaVersion",
+  "note",
+  "vendorAddress",
+  "reason",
+  "revokedAt",
+  "supersededBy",
+]);
+
+// The standing in-band trust NOTES — copied VERBATIM from cli/core/revocation.js so the verifier pins the
+// EXACT same `note` text the producer requires. The producer's validateRevocation requires the embedded
+// payload's `note` to equal REVOCATION_TRUST_NOTE, and validateSignedAttestation requires the container's
+// `note` to equal SIGNED_REVOCATION_TRUST_NOTE; a revocation with a wrong/absent note is IGNORED by the
+// producer, so the verifier must ignore it too (parity). These strings are LOAD-BEARING for parity, not
+// for security (the signature binds the bytes regardless) — they must never drift from the producer's.
+const REVOCATION_TRUST_NOTE =
+  "This is a verifyhash producer KEY REVOCATION: the holder of `vendorAddress`'s key SIGNED it, declaring " +
+  "that address REVOKED as of `revokedAt` for `reason` (optionally superseded by `supersededBy`). verify " +
+  "RE-DERIVES the signer from these exact bytes and REQUIRES it to equal `vendorAddress` — a key revokes " +
+  "ITSELF; a third party cannot revoke a key it does not control. It proves the KEY-HOLDER's SIGNED CLAIM " +
+  'ONLY: `revokedAt` is the holder\'s self-asserted instant, NOT a trusted TIMESTAMP (it rides the human-' +
+  "owned timestamp trust-root, STRATEGY.md P-3), and this is NOT a legal opinion.";
+
+const SIGNED_REVOCATION_TRUST_NOTE =
+  "This is a SIGNED verifyhash key-revocation container: it WRAPS (never edits) the EXACT canonical " +
+  "revocation bytes in `attestation` and attaches a detached EIP-191 signature. verifyRevocation " +
+  "RE-DERIVES the signer from those bytes and pins it to the embedded `vendorAddress` — it never trusts " +
+  "the file's own claims. Every caveat of the embedded revocation applies. " +
+  REVOCATION_TRUST_NOTE;
+
+// A claimed 0x-address INSIDE the payload: 0x + 40 LOWERCASE hex (byte-determinism — mixed-case rejected).
+const PAYLOAD_ADDRESS_RE = /^0x[0-9a-f]{40}$/;
+// A recovered/expected address (the verifier lowercases everything it compares).
+const ADDRESS_RE = /^0x[0-9a-f]{40}$/;
+// A 65-byte (r||s||v) signature as 0x-hex — LOWERCASE-only, byte-for-byte the producer's EIP191_SIG_RE
+// (cli/core/attestation.js). The producer REJECTS mixed/upper-case hex for byte-determinism and IGNORES a
+// revocation carrying it; accepting mixed case here would let a third party re-encode a holder's genuine
+// revocation into one the producer drops but the verifier honors — a parity split with NO key required. So
+// the verifier pins the SAME lowercase grammar.
+const SIGNATURE_RE = /^0x[0-9a-f]{130}$/;
+// A strict, CANONICAL ISO-8601 UTC instant — the SAME grammar revokedAt / asOf are pinned to.
+const ISO_INSTANT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/;
+
+// The recovered-signer sentinel the producer core returns for an unrecoverable signature.
+const UNRECOVERABLE = "(unrecoverable)";
+
+// A dedicated error type for the HARD input errors of THIS helper (a malformed asOf, a non-JSON/wrong-type
+// revocations input, an unreadable path). An individual BOGUS revocation is NEVER thrown — it is collected as
+// an ignored warning so one bad entry can never abort the evaluation of the good ones.
+class RevocationReadError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RevocationReadError";
+  }
+}
+
+function isPlainObject(v) {
+  return v != null && typeof v === "object" && !Array.isArray(v);
+}
+
+// ---------------------------------------------------------------------------
+// Canonical-instant parsing (asOf + revokedAt share this).
+// ---------------------------------------------------------------------------
+
+function parseCanonicalInstant(value, label) {
+  if (typeof value !== "string" || !ISO_INSTANT_RE.test(value)) {
+    throw new RevocationReadError(
+      `${label} must be an ISO-8601 UTC instant ("YYYY-MM-DDTHH:MM:SS(.mmm)Z"), got: ${String(value)}`
+    );
+  }
+  const ms = Date.parse(value);
+  if (Number.isNaN(ms) || new Date(ms).toISOString() !== value) {
+    throw new RevocationReadError(
+      `${label} must be a canonical ISO-8601 UTC instant (no rolled-over/impossible fields), got: ${String(value)}`
+    );
+  }
+  return ms;
+}
+
+/**
+ * Resolve the effective `--as-of` instant. PURE. When the recipient supplied one, validate + use it; when
+ * they did not, default to the recipient's CURRENT decision time (`nowISO`, injectable for tests). A
+ * malformed explicit `--as-of` is a HARD RevocationReadError (never silently coerced to now). Mirrors
+ * cli/core/trust-asof.js resolveAsOf.
+ * @param {string|undefined|null} asOf
+ * @param {string} nowISO the recipient's current instant (ISO-8601 UTC)
+ * @returns {{ asOf: string, defaulted: boolean }}
+ */
+function resolveAsOf(asOf, nowISO) {
+  if (asOf !== undefined && asOf !== null && asOf !== "") {
+    parseCanonicalInstant(asOf, "--as-of"); // validate shape; throws on malformed
+    return { asOf, defaulted: false };
+  }
+  if (typeof nowISO !== "string") {
+    throw new RevocationReadError("resolveAsOf requires a nowISO instant when --as-of is not given");
+  }
+  parseCanonicalInstant(nowISO, "nowISO"); // the injected/default now must itself be canonical
+  return { asOf: nowISO, defaulted: true };
+}
+
+/**
+ * Serialize a validated UNSIGNED revocation payload to its CANONICAL, byte-deterministic bytes — a FIXED key
+ * order, NO insignificant whitespace, a single trailing newline. This is a LINE-FOR-LINE port of
+ * cli/core/revocation.js serializeRevocation: the FIXED field order (kind, schemaVersion, note,
+ * vendorAddress, reason, revokedAt) with `supersededBy` appended LAST and ONLY when present. It lets the
+ * verifier perform the producer's canonical-bytes BINDING check (`attestation === serializeRevocation(...)`)
+ * with NO ethers — the producer's whole point that two logically-identical revocations serialize identically.
+ * @param {object} payload an already-structurally-validated revocation payload
+ * @returns {string} the canonical serialization (newline-terminated)
+ */
+function serializeRevocation(payload) {
+  const canonical = {
+    kind: payload.kind,
+    schemaVersion: payload.schemaVersion,
+    note: payload.note,
+    vendorAddress: payload.vendorAddress,
+    reason: payload.reason,
+    revokedAt: payload.revokedAt,
+  };
+  if (Object.prototype.hasOwnProperty.call(payload, "supersededBy") && payload.supersededBy !== undefined) {
+    canonical.supersededBy = payload.supersededBy;
+  }
+  return JSON.stringify(canonical) + "\n";
+}
+
+// ---------------------------------------------------------------------------
+// Structural validation of a parsed SIGNED revocation container + its embedded payload. A structurally
+// invalid container is REJECTED by THROWING (the caller catches + IGNORES it with a warning) — never
+// half-accepted.
+//
+// PARITY-CRITICAL: this MIRRORS the producer's cli/core/attestation.js validateSignedAttestation +
+// cli/core/revocation.js validateRevocation so the two stacks IGNORE the EXACT same malformed-but-self-signed
+// revocations. The producer's verdict-gating structural checks the verifier MUST replicate (or the offline
+// path reaches REVOKED where the producer reaches OK on identical inputs) are:
+//   - the CONTAINER carries the right kind, a SUPPORTED schemaVersion, and the standing SIGNED note;
+//   - the signature block has a known scheme, a 65-byte LOWERCASE-hex signature, and a lowercase signer;
+//   - the EMBEDDED payload re-validates as a sound UNSIGNED revocation: a CLOSED field set (no extra/unknown
+//     key), the right kind, a SUPPORTED schemaVersion, the standing UNSIGNED note, a lowercase vendorAddress,
+//     a closed-set reason, a canonical revokedAt, an optional lowercase supersededBy; AND
+//   - the WRAP-DON'T-EDIT binding: the embedded `attestation` STRING is byte-for-byte the canonical
+//     re-serialization of the embedded payload (so a non-canonical / reordered / whitespace variant is
+//     IGNORED, exactly as the producer ignores it).
+// The signature recovery (verifyRevocation) is what makes a revocation SAFE against forgers; these structural
+// checks are what make the verifier's VERDICT EQUAL the producer's on every malformed input it sees.
+// ---------------------------------------------------------------------------
+
+function validateSignedRevocation(obj) {
+  if (!isPlainObject(obj)) {
+    throw new RevocationReadError("revocation container must be a JSON object");
+  }
+  if (obj.kind !== SIGNED_REVOCATION_KIND) {
+    throw new RevocationReadError(
+      `not a signed key-revocation (kind ${JSON.stringify(obj.kind)}; expected ${JSON.stringify(SIGNED_REVOCATION_KIND)})`
+    );
+  }
+  // The CONTAINER schemaVersion must be supported (the producer's validateSignedAttestation rejects an
+  // unsupported one before any recovery — so the verifier must too).
+  if (!SUPPORTED_SIGNED_REVOCATION_SCHEMA_VERSIONS.includes(obj.schemaVersion)) {
+    throw new RevocationReadError(
+      `unsupported signed revocation schemaVersion: ${JSON.stringify(obj.schemaVersion)} ` +
+        `(this build understands ${JSON.stringify(SUPPORTED_SIGNED_REVOCATION_SCHEMA_VERSIONS)})`
+    );
+  }
+  // The CONTAINER note must be the standing SIGNED note (the producer pins it; a drifted note is IGNORED).
+  if (obj.note !== SIGNED_REVOCATION_TRUST_NOTE) {
+    throw new RevocationReadError("signed revocation `note` must be the standing SIGNED_REVOCATION_TRUST_NOTE");
+  }
+  if (typeof obj.attestation !== "string") {
+    throw new RevocationReadError("signed revocation must embed the canonical UNSIGNED bytes as a string `attestation`");
+  }
+  const sig = obj.signature;
+  if (!isPlainObject(sig)) {
+    throw new RevocationReadError("signed revocation is missing a { scheme, signer, signature } signature block");
+  }
+  if (sig.scheme !== "eip191-personal-sign") {
+    throw new RevocationReadError(
+      `unsupported signature scheme: ${JSON.stringify(sig.scheme)} (this verifier understands eip191-personal-sign)`
+    );
+  }
+  // LOWERCASE-only signer + signature, byte-for-byte the producer's ADDRESS_RE / EIP191_SIG_RE — a
+  // mixed/upper-case re-encoding is IGNORED by the producer, so it must be ignored here too.
+  if (typeof sig.signer !== "string" || !PAYLOAD_ADDRESS_RE.test(sig.signer)) {
+    throw new RevocationReadError(
+      "signed revocation signer must be a 0x-prefixed 20-byte LOWERCASE-hex address (mixed/upper case rejected for byte-determinism)"
+    );
+  }
+  if (typeof sig.signature !== "string" || !SIGNATURE_RE.test(sig.signature)) {
+    throw new RevocationReadError(
+      "signed revocation signature must be a 65-byte (r||s||v) 0x-prefixed LOWERCASE-hex string (mixed/upper case rejected for byte-determinism)"
+    );
+  }
+
+  // Parse + strictly validate the embedded revocation payload (the producer's validateRevocation, mirrored).
+  let rev;
+  try {
+    rev = JSON.parse(obj.attestation);
+  } catch (e) {
+    throw new RevocationReadError(`embedded revocation is not valid JSON: ${e.message}`);
+  }
+  if (!isPlainObject(rev)) {
+    throw new RevocationReadError("embedded revocation payload must be a JSON object");
+  }
+  // CLOSED FIELD SET: an unknown/extraneous key is a HARD reject (the producer IGNORES such a revocation).
+  for (const key of Object.keys(rev)) {
+    if (!REVOCATION_FIELDS.includes(key)) {
+      throw new RevocationReadError(
+        `revocation has an unknown field: ${JSON.stringify(key)} (the closed field set is ${JSON.stringify(REVOCATION_FIELDS)})`
+      );
+    }
+  }
+  if (rev.kind !== REVOCATION_KIND) {
+    throw new RevocationReadError(
+      `embedded payload is not a key revocation (kind ${JSON.stringify(rev.kind)}; expected ${JSON.stringify(REVOCATION_KIND)})`
+    );
+  }
+  if (!SUPPORTED_REVOCATION_SCHEMA_VERSIONS.includes(rev.schemaVersion)) {
+    throw new RevocationReadError(
+      `unsupported revocation schemaVersion: ${JSON.stringify(rev.schemaVersion)} ` +
+        `(this build understands ${JSON.stringify(SUPPORTED_REVOCATION_SCHEMA_VERSIONS)})`
+    );
+  }
+  if (rev.note !== REVOCATION_TRUST_NOTE) {
+    throw new RevocationReadError("revocation `note` must be the standing REVOCATION_TRUST_NOTE (caveat must not drift)");
+  }
+  if (typeof rev.vendorAddress !== "string" || !PAYLOAD_ADDRESS_RE.test(rev.vendorAddress)) {
+    throw new RevocationReadError(
+      `revocation vendorAddress must be a 0x-prefixed 20-byte LOWERCASE-hex address, got: ${String(rev.vendorAddress)}`
+    );
+  }
+  if (typeof rev.reason !== "string" || !REVOCATION_REASON_SET.includes(rev.reason)) {
+    throw new RevocationReadError(
+      `revocation reason must be one of ${JSON.stringify(REVOCATION_REASON_SET)}, got: ${JSON.stringify(rev.reason)}`
+    );
+  }
+  parseCanonicalInstant(rev.revokedAt, "revocation revokedAt"); // throws on a non-canonical instant
+  if (
+    Object.prototype.hasOwnProperty.call(rev, "supersededBy") &&
+    rev.supersededBy !== undefined &&
+    (typeof rev.supersededBy !== "string" || !PAYLOAD_ADDRESS_RE.test(rev.supersededBy))
+  ) {
+    throw new RevocationReadError(
+      `revocation supersededBy, when present, must be a 0x-prefixed 20-byte LOWERCASE-hex address, got: ${String(rev.supersededBy)}`
+    );
+  }
+  // WRAP-DON'T-EDIT BINDING (the producer's `obj.attestation !== cfg.serializeUnsigned(embedded)` gate). The
+  // embedded STRING must be byte-for-byte the canonical re-serialization of the embedded payload — so a
+  // reordered-keys / extra-whitespace / otherwise non-canonical (but genuinely self-signed) variant is
+  // IGNORED here exactly as the producer ignores it. THIS is the check that closes the headline parity gap.
+  if (obj.attestation !== serializeRevocation(rev)) {
+    throw new RevocationReadError(
+      "embedded revocation is not in canonical form (the signed-over bytes must be byte-for-byte the canonical serialization)"
+    );
+  }
+  return { container: obj, revocation: rev };
+}
+
+/**
+ * Verify (purely, OFFLINE) a parsed SIGNED revocation container — the STACK-FREE mirror of the producer's
+ * verifyRevocation. It recovers the signer from the embedded canonical bytes + signature and:
+ *   (1) confirms it equals the container's CLAIMED `signer` (signatureMatchesSigner — ALWAYS run);
+ *   (2) confirms it equals the revocation's OWN embedded `vendorAddress` (vendorAddressMatchesSigner — the
+ *       load-bearing SELF-CONTROL check: a key revokes ITSELF).
+ * The verdict is ACCEPTED only when BOTH pass; a forged/tampered/third-party revocation is a clean REJECTED.
+ * A structurally invalid container THROWS (RevocationReadError) before any recovery, so an ordinary REJECTED
+ * verdict only ever describes a STRUCTURALLY SOUND revocation whose signature simply doesn't back its claims.
+ *
+ * @param {object} container a parsed signed-revocation container object
+ * @returns {{ accepted, recoveredSigner, claimedSigner, vendorAddress, reason, revokedAt, supersededBy, failedChecks }}
+ */
+function verifyRevocation(container) {
+  const { revocation } = validateSignedRevocation(container);
+  const claimedSigner = container.signature.signer.toLowerCase();
+  const vendorAddress = revocation.vendorAddress;
+
+  // Recover the signer from the EXACT embedded bytes. A tampered/corrupt signature can be UNRECOVERABLE (no
+  // valid curve point) — that throws; we map it to the "(unrecoverable)" sentinel, never a crash, mirroring
+  // the producer core's catch.
+  let recoveredSigner;
+  try {
+    recoveredSigner = recoverPersonalSignAddress(container.attestation, container.signature.signature);
+  } catch (_) {
+    recoveredSigner = UNRECOVERABLE;
+  }
+
+  const signatureMatchesSigner = recoveredSigner === claimedSigner;
+  const vendorAddressMatchesSigner = recoveredSigner === vendorAddress;
+
+  const failedChecks = [];
+  if (!signatureMatchesSigner) failedChecks.push("signatureMatchesSigner");
+  if (!vendorAddressMatchesSigner) failedChecks.push("vendorAddressMatchesSigner");
+
+  return {
+    accepted: failedChecks.length === 0,
+    recoveredSigner,
+    claimedSigner,
+    vendorAddress,
+    reason: revocation.reason,
+    revokedAt: revocation.revokedAt,
+    supersededBy: Object.prototype.hasOwnProperty.call(revocation, "supersededBy")
+      ? revocation.supersededBy
+      : null,
+    failedChecks,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Normalize the `revocations` input into a flat array of entries to evaluate. PURE. Accepts an ARRAY of
+// already-parsed containers (or JSON strings), a single container object, or a JSON STRING of either (a
+// bundle file is a JSON ARRAY of containers, or a single container object). A per-entry parse failure becomes
+// a `_parseError` marker (IGNORED with a warning); a WHOLE-input parse failure HARD-errors. Mirrors
+// cli/core/trust-asof.js normalizeRevocationsInput.
+// ---------------------------------------------------------------------------
+
+function normalizeRevocationsInput(revocations) {
+  if (typeof revocations === "string") {
+    let parsed;
+    try {
+      parsed = JSON.parse(revocations);
+    } catch (e) {
+      throw new RevocationReadError(`revocations input is not valid JSON: ${e.message}`);
+    }
+    return normalizeRevocationsInput(parsed);
+  }
+  if (Array.isArray(revocations)) {
+    return revocations.map((el) => {
+      if (typeof el === "string") {
+        try {
+          return JSON.parse(el);
+        } catch (e) {
+          return { _parseError: `entry is not valid JSON: ${e.message}`, _raw: el };
+        }
+      }
+      return el;
+    });
+  }
+  if (isPlainObject(revocations)) {
+    return [revocations];
+  }
+  throw new RevocationReadError(
+    "revocations input must be a signed-revocation container, an array of them, or JSON text of either"
+  );
+}
+
+// Classify ONE already-parsed revocation entry against the subject + as-of pivot. PURE. Mirrors
+// cli/core/trust-asof.js classifyRevocation exactly (the same `applies`/`later`/`irrelevant`/`ignored`
+// outcomes + the inclusive `revokedAt <= asOf` boundary).
+function classifyRevocation(entry, subject, asOfMs) {
+  if (entry && entry._parseError) {
+    return { kind: "ignored", warning: `ignored an unparseable revocation entry (${entry._parseError})` };
+  }
+  let v;
+  try {
+    v = verifyRevocation(entry);
+  } catch (e) {
+    return { kind: "ignored", warning: `ignored a malformed/foreign revocation (${e.message})` };
+  }
+  if (!v.accepted) {
+    return {
+      kind: "ignored",
+      warning:
+        `ignored a revocation that does not verify (failed: ${v.failedChecks.join(", ")}; ` +
+        `vendorAddress ${v.vendorAddress}) — a forged/tampered/third-party revocation never downgrades trust`,
+    };
+  }
+  if (v.vendorAddress !== subject) {
+    return { kind: "irrelevant", vendorAddress: v.vendorAddress };
+  }
+  const revokedAtMs = Date.parse(v.revokedAt);
+  const detail = {
+    vendorAddress: v.vendorAddress,
+    reason: v.reason,
+    revokedAt: v.revokedAt,
+    supersededBy: v.supersededBy,
+  };
+  // Inclusive on the revoked side: a revocation effective EXACTLY at the as-of instant counts as revoked.
+  if (revokedAtMs <= asOfMs) {
+    return { kind: "applies", ...detail };
+  }
+  return { kind: "later", ...detail };
+}
+
+/**
+ * THE RECIPIENT-SIDE TRUST-DECISION-AS-OF. PURE / OFFLINE / KEY-FREE / I/O-FREE / CLOCK-FREE. Identical
+ * semantics to cli/core/trust-asof.js evaluateTrustAsOf (so verify-vh's downgrade matches the producer's
+ * byte-for-byte). Returns a stable decision block.
+ * @param {object} params { subject, asOf, revocations }
+ * @returns {{ status, revoked, subject, asOf, governing, laterRevoked, counts, ignored }}
+ */
+function evaluateTrustAsOf(params) {
+  if (!isPlainObject(params)) {
+    throw new RevocationReadError("evaluateTrustAsOf requires { subject, asOf, revocations }");
+  }
+  const { subject, asOf, revocations } = params;
+  if (typeof subject !== "string" || subject.length === 0) {
+    throw new RevocationReadError("evaluateTrustAsOf requires a string `subject` (the artifact's recovered signer)");
+  }
+  const asOfMs = parseCanonicalInstant(asOf, "--as-of");
+  const entries = normalizeRevocationsInput(revocations);
+
+  // A non-address subject (the "(unrecoverable)" sentinel) cannot be matched by any revocation — still
+  // evaluate every entry (so forged ones are reported as ignored), but no SOUND revocation can apply.
+  const subjectIsAddress = ADDRESS_RE.test(subject);
+
+  const applicable = [];
+  const later = [];
+  let irrelevant = 0;
+  const ignored = [];
+
+  for (const entry of entries) {
+    const c = classifyRevocation(entry, subject, asOfMs);
+    if (c.kind === "ignored") ignored.push(c.warning);
+    else if (c.kind === "irrelevant") irrelevant += 1;
+    else if (c.kind === "later") later.push(c);
+    else if (c.kind === "applies") applicable.push(c);
+  }
+
+  // The GOVERNING revocation is the EARLIEST applicable one (smallest revokedAt), tie-broken deterministically
+  // on vendorAddress then reason — the instant from which the key was no longer trustworthy.
+  const sortByEffective = (a, b) =>
+    Date.parse(a.revokedAt) - Date.parse(b.revokedAt) ||
+    (a.vendorAddress < b.vendorAddress ? -1 : a.vendorAddress > b.vendorAddress ? 1 : 0) ||
+    (a.reason < b.reason ? -1 : a.reason > b.reason ? 1 : 0);
+
+  const govern = (arr) => {
+    if (arr.length === 0) return null;
+    const [g] = arr.slice().sort(sortByEffective);
+    return { vendorAddress: g.vendorAddress, reason: g.reason, revokedAt: g.revokedAt, supersededBy: g.supersededBy };
+  };
+
+  const governing = govern(applicable);
+  const laterRevoked = governing ? null : govern(later);
+
+  let status;
+  if (governing) status = "REVOKED";
+  else if (!subjectIsAddress) status = "UNEVALUABLE";
+  else status = "OK";
+
+  return {
+    status,
+    revoked: status === "REVOKED",
+    subject,
+    asOf,
+    governing,
+    laterRevoked,
+    counts: {
+      total: entries.length,
+      applicable: applicable.length,
+      later: later.length,
+      irrelevant,
+      ignored: ignored.length,
+    },
+    ignored,
+  };
+}
+
+/**
+ * Fold a TRUST-DECISION-AS-OF onto an existing verify-vh result, OFFLINE. PURE. Mirrors cli/core/trust-asof.js
+ * applyToVerifyResult: it NEVER upgrades a verdict — an already-REJECTED artifact stays rejected; the
+ * trust-as-of only ever ADDS a REVOKED downgrade on top of an otherwise-ACCEPTED artifact. Returns a NEW
+ * result object (the original is not mutated): the original fields PLUS `trustAsOf`, with accepted/verdict/
+ * reason updated when REVOKED.
+ *
+ * The `subject` is the artifact's RECOVERED signer. When the signature did not even recover (the
+ * "(unrecoverable)" sentinel / a null), no revocation can bind — the decision is UNEVALUABLE and never
+ * changes the (already-rejected) verdict.
+ *
+ * @param {object} params { result, revocations, asOf }
+ * @returns {object} a new result with `trustAsOf` attached
+ */
+function applyToVerifyResult(params) {
+  if (!isPlainObject(params) || !isPlainObject(params.result)) {
+    throw new RevocationReadError("applyToVerifyResult requires { result, revocations, asOf }");
+  }
+  const { result, revocations, asOf } = params;
+  // The subject is the recovered signer. verify-vh leaves recoveredSigner null for an UNSIGNED artifact and
+  // sets the "(unrecoverable)" sentinel for a broken signature — both are non-addresses, so neither binds.
+  const subject =
+    typeof result.recoveredSigner === "string" && result.recoveredSigner.length > 0
+      ? result.recoveredSigner
+      : UNRECOVERABLE;
+
+  const decision = evaluateTrustAsOf({ subject, asOf, revocations });
+  const out = { ...result, trustAsOf: decision };
+
+  if (decision.revoked) {
+    // The ONLY downgrading path: an otherwise-ACCEPTED artifact whose signer was revoked-before-as-of becomes
+    // REVOKED (exit 3). We flip accepted=false + set a distinct REVOKED verdict + a named reason so the
+    // existing `accepted ? 0 : 3` exit mapping yields exit 3, byte-for-byte with the producer.
+    out.accepted = false;
+    out.verdict = "REVOKED";
+    out.reason = "key_revoked_as_of";
+  }
+  return out;
+}
+
+/**
+ * Render the human-readable TRUST-DECISION-AS-OF lines verify-vh appends to its report. PURE. Returns an
+ * array of lines. Mirrors cli/core/trust-asof.js renderTrustAsOf's content so the two stacks read the same.
+ * @param {object} decision the object evaluateTrustAsOf returns
+ * @param {{ defaulted?: boolean, indent?: string }} [ctx]
+ * @returns {string[]} lines
+ */
+function renderTrustAsOf(decision, ctx = {}) {
+  const I = ctx.indent || "";
+  const L = [];
+  const asOfNote = ctx.defaulted ? " (defaulted to now; pass --as-of <ISO> to pin the decision instant)" : "";
+  L.push(`${I}revocation check (as of ${decision.asOf})${asOfNote}:`);
+  if (decision.status === "REVOKED") {
+    const g = decision.governing;
+    L.push(
+      `${I}  [REVOKED] the signing key (${g.vendorAddress}) was REVOKED as of ${g.revokedAt} ` +
+        `(reason: ${g.reason})${g.supersededBy ? `, superseded by ${g.supersededBy}` : ""} — at or before ` +
+        `the as-of instant. This artifact is NOT trustworthy as of ${decision.asOf}.`
+    );
+  } else if (decision.status === "UNEVALUABLE") {
+    L.push(`${I}  [skip] the signature did not recover to a key — no subject to evaluate revocations against.`);
+  } else {
+    L.push(`${I}  [OK] no applicable revocation: the signing key was not revoked as of ${decision.asOf}.`);
+    if (decision.laterRevoked) {
+      const lr = decision.laterRevoked;
+      L.push(
+        `${I}  [note] this key (${lr.vendorAddress}) IS revoked as of ${lr.revokedAt} ` +
+          `(reason: ${lr.reason})${lr.supersededBy ? `, superseded by ${lr.supersededBy}` : ""} — AFTER your ` +
+          `as-of instant, so it does NOT downgrade THIS decision (informational).`
+      );
+    }
+  }
+  for (const w of decision.ignored) {
+    L.push(`${I}  [warning] ${w}`);
+  }
+  return L;
+}
+
+module.exports = {
+  RevocationReadError,
+  SIGNED_REVOCATION_KIND,
+  REVOCATION_KIND,
+  REVOCATION_SCHEMA_VERSION,
+  SUPPORTED_REVOCATION_SCHEMA_VERSIONS,
+  SUPPORTED_SIGNED_REVOCATION_SCHEMA_VERSIONS,
+  REVOCATION_REASON_SET,
+  REVOCATION_FIELDS,
+  REVOCATION_TRUST_NOTE,
+  SIGNED_REVOCATION_TRUST_NOTE,
+  ISO_INSTANT_RE,
+  UNRECOVERABLE,
+  isPlainObject,
+  parseCanonicalInstant,
+  resolveAsOf,
+  serializeRevocation,
+  validateSignedRevocation,
+  verifyRevocation,
+  normalizeRevocationsInput,
+  classifyRevocation,
+  evaluateTrustAsOf,
+  applyToVerifyResult,
+  renderTrustAsOf,
+};
+
+};
+
+// ===== module: revocation  (from verifier/lib/revocation.js) =====
+__modules["revocation"] = function (module, exports, __require) {
+"use strict";
+
+// verifier/lib/revocation.js — the STACK-FREE recipient-side KEY-REVOCATION reader + as-of decision for the
+// INDEPENDENT verifier (EPIC-51 / T-51.4).
+//
+// WHY THIS EXISTS
+//   The producer stack already lets a recipient downgrade an otherwise-ACCEPTED signed artifact to REVOKED
+//   when the signing key was revoked-before-the-as-of-instant (`vh ... verify-signed --revocations <f>
+//   --as-of <T>`, cli/core/trust-asof.js + cli/core/revocation.js). The OFFLINE, no-producer-stack verifier
+//   (`verify-vh`) did NOT — so a counterparty who only holds the single-file verifier reached a DIFFERENT
+//   verdict than the producer on the SAME inputs (a clean ACCEPTED where the producer returned REVOKED).
+//   This module closes that gap WITHOUT pulling in ethers/hardhat or back-edging into cli/: it RE-IMPLEMENTS
+//   the revocation soundness check (EIP-191 signer recovery + the load-bearing SELF-CONTROL invariant) and
+//   the as-of trust decision using ONLY the verifier's own pure-JS crypto (./secp256k1-recover, ./keccak).
+//
+// MODULE LAYOUT (T-66.1 split — surface + behavior UNCHANGED)
+//   Every PURE piece of this module — the discriminators/grammars/trust notes, the structural validation, the
+//   signer recovery, the as-of classification/decision, the verify-result fold, the renderer — lives in
+//   ./revocation-core.js (which requires NO fs/path/os, so the verifier's IN-MEMORY bytes path can reach it
+//   without ANY impure builtin on its require graph). This file re-exports ALL of it VERBATIM (the very same
+//   function objects) and adds the two — and only two — fs-backed conveniences: `readRevocationsFromPath`
+//   (the --revocations <file-or-dir> reader) and `loadAndApply` (the one-call CLI integration). Every
+//   existing caller keeps its exact import surface; on identical inputs every function is byte-identical.
+//
+// THE LOAD-BEARING SAFETY INVARIANT — A REVOCATION CAN ONLY EVER REMOVE TRUST, NEVER ADD IT.
+//   Every revocation statement is verified the SAME way the producer core does: it must (1) recover to its
+//   own claimed `signer` AND (2) recover to its own embedded `vendorAddress` (a key revokes ITSELF). A
+//   revocation that fails EITHER check — forged, tampered, third-party, structurally malformed, or simply
+//   not parseable — is IGNORED with a WARNING and can NEVER downgrade the verdict. So a planted "revocation"
+//   for a victim's key cannot grief a recipient into rejecting a perfectly good artifact.
+//
+// SUBJECT-SCOPING — A REVOCATION ONLY BITES THE KEY IT NAMES.
+//   The `subject` is the artifact's RECOVERED signer (the address verify-vh derived from the bytes). A
+//   revocation only affects the verdict when its `vendorAddress` EQUALS that subject; a revocation for some
+//   OTHER key is `irrelevant`, never a downgrade.
+//
+// PURE + I/O-FREE on the decision; the FILE/DIR READ is the only I/O (readRevocationsFromPath), kept here so
+//   verify-vh stays a thin wiring layer. No network, no key, no clock (the `asOf` instant is caller-supplied).
+//
+// PARITY WITH THE PRODUCER STACK
+//   The decision semantics (applies / later / irrelevant / ignored; the inclusive `revokedAt <= asOf`
+//   boundary; the EARLIEST-applicable governing record; the later-revoked informational note) mirror
+//   cli/core/trust-asof.js, and the STRUCTURAL validation (validateSignedRevocation in ./revocation-core.js)
+//   mirrors the producer's cli/core/attestation.js validateSignedAttestation + cli/core/revocation.js
+//   validateRevocation gate-for-gate: the closed embedded field set, the supported schemaVersion (container
+//   AND payload), the standing trust NOTES, the lowercase-only signature/address grammar, and the
+//   WRAP-DON'T-EDIT canonical re-serialization binding. A revocation the producer IGNORES (a non-canonical /
+//   extra-field / wrong-note / unsupported-schemaVersion / mixed-case-hex but genuinely self-signed one) is
+//   therefore IGNORED here too — so on identical inputs verify-vh's verdict + exit code match
+//   `vh ... verify-signed --revocations` byte-for-byte, for the SOUND inputs AND the malformed ones.
+//   test/verifier.revocation.test.js pins that parity against the REAL producer core, including the
+//   malformed-but-self-signed (NEGATIVE-parity) classes.
+
+const fs = require("fs");
+const path = require("path");
+
+const core = __require("revocation-core");
+
+const { RevocationReadError, isPlainObject, resolveAsOf, normalizeRevocationsInput, applyToVerifyResult } = core;
+
+// ---------------------------------------------------------------------------
+// FILE-OR-DIR reader. The ONLY I/O in this module. A counterparty may hand the verifier a SINGLE revocation
+// file (one container, or a JSON array of them) OR a DIRECTORY of revocation files — a vendor commonly
+// publishes one file per revoked key. Reading a directory aggregates every entry into ONE array of parsed
+// containers, so the as-of decision sees them all under one --revocations flag.
+//
+// DIRECTORY MODE: read every *.json / *.vhrevocation.json file in the dir (NON-recursive — a flat folder of
+// revocations), parse each, and flatten (a file that is itself a JSON array contributes all its entries). A
+// file that is not valid JSON, or whose JSON is not an object/array, becomes a `_parseError` marker so it is
+// IGNORED with a warning downstream — a single junk file in the folder never aborts the decision.
+//
+// FILE MODE: read the one file's text and hand it to normalizeRevocationsInput (so a single file may be one
+// container OR a JSON array). A non-JSON single file HARD-errors (the recipient pointed --revocations at
+// bytes that aren't a revocations input at all) — same contract as the producer's single-file read.
+// ---------------------------------------------------------------------------
+
+// File extensions a directory scan treats as candidate revocation files.
+const REVOCATION_FILE_RE = /\.(json|vhrevocation\.json)$/i;
+
+/**
+ * Read the --revocations <file-or-dir> path into a normalized array of parsed entries (each a container
+ * object or a `_parseError` marker). The caller passes the already-resolved array straight to
+ * evaluateTrustAsOf/applyToVerifyResult.
+ *
+ * @param {string} p the --revocations path (a file or a directory)
+ * @param {{ readFile?: Function, statSync?: Function, readdirSync?: Function }} [io] injectable fs for tests
+ * @returns {Array<object>} a flat array of parsed entries (containers or `_parseError` markers)
+ * @throws {RevocationReadError} on an unreadable path or a non-JSON SINGLE file
+ */
+function readRevocationsFromPath(p, io = {}) {
+  const readFile = io.readFile || ((f) => fs.readFileSync(f, "utf8"));
+  const statSync = io.statSync || ((f) => fs.statSync(f));
+  const readdirSync = io.readdirSync || ((d) => fs.readdirSync(d));
+
+  let st;
+  try {
+    st = statSync(p);
+  } catch (e) {
+    throw new RevocationReadError(`cannot read --revocations ${p}: ${e.message}`);
+  }
+
+  if (st.isDirectory()) {
+    let names;
+    try {
+      names = readdirSync(p);
+    } catch (e) {
+      throw new RevocationReadError(`cannot read --revocations directory ${p}: ${e.message}`);
+    }
+    // Deterministic order (sorted) so the governing tie-break + ignored-warning order are stable.
+    const files = names
+      .filter((n) => REVOCATION_FILE_RE.test(n))
+      .sort()
+      .map((n) => path.join(p, n));
+    const entries = [];
+    for (const f of files) {
+      let text;
+      try {
+        text = readFile(f);
+      } catch (e) {
+        entries.push({ _parseError: `cannot read ${path.basename(f)}: ${e.message}`, _raw: f });
+        continue;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch (e) {
+        entries.push({ _parseError: `${path.basename(f)} is not valid JSON: ${e.message}`, _raw: f });
+        continue;
+      }
+      // A file may itself be a single container OR a JSON array of them — flatten either into the pool.
+      if (Array.isArray(parsed)) {
+        for (const el of parsed) entries.push(el);
+      } else if (isPlainObject(parsed)) {
+        entries.push(parsed);
+      } else {
+        entries.push({ _parseError: `${path.basename(f)} is not a revocation object/array`, _raw: f });
+      }
+    }
+    return entries;
+  }
+
+  // Single file: read its text and normalize (a non-JSON single file HARD-errors via normalizeRevocationsInput).
+  let text;
+  try {
+    text = readFile(p);
+  } catch (e) {
+    throw new RevocationReadError(`cannot read --revocations ${p}: ${e.message}`);
+  }
+  return normalizeRevocationsInput(text);
+}
+
+/**
+ * The ONE shared integration verify-vh calls: read the --revocations file-or-dir, resolve the --as-of
+ * (defaulting to nowISO), evaluate the decision, and fold it onto the verify result. Runs ONLY when
+ * `revocationsPath` is truthy; with no path it returns the result UNCHANGED + a null decision (the
+ * regression-safety contract — with no --revocations the verifier is byte-identical to today).
+ *
+ * @param {object} params { result, revocationsPath, asOf, nowISO, io? }
+ * @returns {{ result, decision, defaulted }}
+ */
+function loadAndApply(params) {
+  if (!isPlainObject(params) || !isPlainObject(params.result)) {
+    throw new RevocationReadError("loadAndApply requires { result, revocationsPath, asOf, nowISO }");
+  }
+  const { result, revocationsPath, asOf, nowISO, io } = params;
+  if (!revocationsPath) {
+    return { result, decision: null, defaulted: false };
+  }
+  const { asOf: effectiveAsOf, defaulted } = resolveAsOf(asOf, nowISO);
+  const entries = readRevocationsFromPath(revocationsPath, io || {});
+  const out = applyToVerifyResult({ result, revocations: entries, asOf: effectiveAsOf });
+  return { result: out, decision: out.trustAsOf, defaulted };
+}
+
+module.exports = {
+  RevocationReadError: core.RevocationReadError,
+  SIGNED_REVOCATION_KIND: core.SIGNED_REVOCATION_KIND,
+  REVOCATION_KIND: core.REVOCATION_KIND,
+  REVOCATION_SCHEMA_VERSION: core.REVOCATION_SCHEMA_VERSION,
+  SUPPORTED_REVOCATION_SCHEMA_VERSIONS: core.SUPPORTED_REVOCATION_SCHEMA_VERSIONS,
+  SUPPORTED_SIGNED_REVOCATION_SCHEMA_VERSIONS: core.SUPPORTED_SIGNED_REVOCATION_SCHEMA_VERSIONS,
+  REVOCATION_REASON_SET: core.REVOCATION_REASON_SET,
+  REVOCATION_FIELDS: core.REVOCATION_FIELDS,
+  REVOCATION_TRUST_NOTE: core.REVOCATION_TRUST_NOTE,
+  SIGNED_REVOCATION_TRUST_NOTE: core.SIGNED_REVOCATION_TRUST_NOTE,
+  ISO_INSTANT_RE: core.ISO_INSTANT_RE,
+  UNRECOVERABLE: core.UNRECOVERABLE,
+  parseCanonicalInstant: core.parseCanonicalInstant,
+  resolveAsOf: core.resolveAsOf,
+  serializeRevocation: core.serializeRevocation,
+  validateSignedRevocation: core.validateSignedRevocation,
+  verifyRevocation: core.verifyRevocation,
+  normalizeRevocationsInput: core.normalizeRevocationsInput,
+  classifyRevocation: core.classifyRevocation,
+  evaluateTrustAsOf: core.evaluateTrustAsOf,
+  applyToVerifyResult: core.applyToVerifyResult,
+  renderTrustAsOf: core.renderTrustAsOf,
+  readRevocationsFromPath,
+  loadAndApply,
+};
+
+};
+
+// ===== module: verify-vh  (from verifier/verify-vh.js) =====
+__modules["verify-vh"] = function (module, exports, __require) {
+"use strict";
+
+// verifier/verify-vh.js — the STANDALONE, read-only, OFFLINE verifier (T-31.2).
+//
+// WHY THIS EXISTS
+//   The whole verifyhash family sells one promise: "you do NOT have to trust the producer — verify it
+//   OFFLINE, independently." `verify-vh` is the artifact that makes that promise real for the party who
+//   matters most for a sale: the COUNTERPARTY (an auditor, opposing counsel, a buyer's security team, a
+//   design partner). They drop one `*.vhevidence.json` / `*.vhseal` / dataset attestation / proof bundle
+//   in front of this command and get a deterministic verdict — WITHOUT installing the producer's heavy
+//   ethers/hardhat stack. This tree depends on ONLY `js-sha3` (+ a tiny vendored secp256k1 routine), so a
+//   third party can `npm install` it alone and audit it in an afternoon.
+//
+// WHAT IT DOES
+//   * AUTO-DETECTS the artifact `kind` (evidence seal, reconciliation/trust seal, dataset attestation,
+//     proof bundle — bare or signed).
+//   * RE-DERIVES the keccak Merkle root from the bytes REFERENCED by the artifact (resolving sibling
+//     files relative to the artifact's own directory, with a `--dir <d>` override), NEVER trusting the
+//     artifact's own stored hashes.
+//   * RECOVERS the signer of a signed artifact via the independent EIP-191 secp256k1 recovery (T-31.1),
+//     PINS it to a caller-supplied `--vendor <0xaddr>` (or REPORTS the recovered signer when no pin is
+//     given).
+//   * Prints a deterministic verdict: OK / which file CHANGED / MISSING / UNEXPECTED / `bad_signature`
+//     / `wrong_issuer`.
+//
+// POSTURE — READ-ONLY. It holds NO key, opens nothing for write, and NEVER writes the cwd (or anywhere).
+//   It reads ONLY the artifact and the sibling files it references. Same exit-code contract as
+//   `vh verify-seal` / `vh evidence verify`: 0 ok / 3 rejected / 2 usage / 1 IO.
+//
+// FILE-SOURCE SEAM (T-66.1). The verify cores are written against ONE tiny abstraction — a `readEntry`
+//   function `(relPath) -> { status: "ok", bytes } | { status: "missing" } | { status: "escaped" }` — so
+//   the SAME engine verifies from the DISK (the CLI path below, byte-identical to before) or from an
+//   IN-MEMORY `{ relPath: Uint8Array }` map (`verifyArtifactFromBytes`, the seam a browser page / vm
+//   sandbox drives with ZERO fs/os/path/process on its code path). The whole pure engine sits between the
+//   BEGIN/END markers below; test/verifier.browser-core.test.js proves (statically AND dynamically) that
+//   no impure builtin use is reachable from the bytes entry, and that disk/bytes verdicts are DEEP-EQUAL.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const merkle = __require("merkle");
+const canonical = __require("canonical");
+const { recoverPersonalSignAddress } = __require("secp256k1-recover");
+const revocation = __require("revocation");
+
+// ============================ BEGIN VERIFY-VH PURE ENGINE (T-66.1) ============================
+// EVERYTHING between this marker and the matching END marker is the PURE verify engine: it performs NO
+// I/O of its own and never touches fs / os / path / process / child_process — every byte it verifies
+// arrives through the injected `readEntry` seam (or as an argument). Its only outside references are the
+// four module bindings above, all of which resolve to PURE modules for the functions used here:
+// `merkle`, `canonical`, `recoverPersonalSignAddress`, and the PURE decision half of `revocation`
+// (./lib/revocation-core.js re-exports — never the fs-backed readRevocationsFromPath/loadAndApply).
+// test/verifier.browser-core.test.js enforces all of this mechanically; the markers also make the block
+// mechanically extractable (vm / browser bundling, EPIC-66).
+
+// CI-gateable exit contract, mirroring the producer family (vh verify-seal / vh evidence verify):
+//   0 ok / 3 rejected / 2 usage / 1 IO. Stable; a future CI/indexer keys on these.
+const EXIT = Object.freeze({ OK: 0, IO: 1, USAGE: 2, REJECTED: 3 });
+
+// A usage error the CLI maps to exit 2 (vs an IO error -> 1, vs a clean REJECTED verdict -> 3).
+class UsageError extends Error {}
+class IOError extends Error {}
+
+// The on-disk `kind` discriminators of every artifact family this verifier understands. Bare and signed
+// variants are listed so auto-detect routes correctly. Disjoint, versioned strings — a foreign/random
+// JSON file falls through to a clear "unrecognized artifact" usage error rather than a misread.
+const KINDS = Object.freeze({
+  EVIDENCE_SEAL: "vh.evidence-seal",
+  EVIDENCE_SEAL_SIGNED: "vh.evidence-seal-signed",
+  TRUST_SEAL: "trustledger.reconcile-seal",
+  TRUST_SEAL_SIGNED: "trustledger.reconcile-seal-signed",
+  DATASET_ATTESTATION: "verifyhash.dataset-attestation",
+  DATASET_ATTESTATION_SIGNED: "verifyhash.dataset-attestation-signed",
+  DATASET_ATTESTATION_TIMESTAMPED: "verifyhash.dataset-attestation-timestamped",
+  PROOF: "verifyhash.merkle-proof",
+  AGENT_PACKET: "vh.agent-session-packet",
+});
+
+const TRUST_NOTE =
+  "verify-vh is an INDEPENDENT, read-only, OFFLINE verifier. It RE-DERIVES the keccak root from the " +
+  "bytes you hold and recovers the signer with no producer stack. It proves TAMPER-EVIDENCE + WHO " +
+  "vouched — NOT a trusted timestamp and NOT a legal opinion.";
+
+// ---------------------------------------------------------------------------
+// Address normalization + recovery helpers. The verifier compares addresses as LOWERCASE 0x-hex (the
+// canonical byte-deterministic form the producer records); a caller may paste an EIP-55-checksummed
+// --vendor and we lowercase it (a checksum mismatch is not our concern — we compare 20 raw bytes).
+// ---------------------------------------------------------------------------
+
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+
+function normalizeAddress(addr, label) {
+  if (typeof addr !== "string" || !ADDRESS_RE.test(addr)) {
+    throw new UsageError(`${label} must be a 0x-prefixed 20-byte hex address, got: ${String(addr)}`);
+  }
+  return addr.toLowerCase();
+}
+
+// Recover the EIP-191 signer over the embedded canonical bytes. A tampered/corrupt signature can be
+// UNRECOVERABLE (no valid curve point) — that throws, which the caller turns into a `bad_signature`
+// REJECTED verdict, never a crash. Returns lowercase 0x-hex, or null if recovery failed.
+function tryRecover(message, signature) {
+  try {
+    return recoverPersonalSignAddress(message, signature);
+  } catch (_) {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Signed-container decoding. A signed artifact carries the embedded UNSIGNED payload as the EXACT
+// canonical bytes (a STRING) in `attestation`, plus a { scheme, signer, signature } block. The signed
+// MESSAGE is that embedded string verbatim, so signer recovery runs over `container.attestation`.
+// ---------------------------------------------------------------------------
+
+function decodeSigned(container) {
+  const sig = container && container.signature;
+  if (sig == null || typeof sig !== "object" || Array.isArray(sig)) {
+    throw new IOError("signed artifact is missing a { scheme, signer, signature } signature block");
+  }
+  if (sig.scheme !== "eip191-personal-sign") {
+    throw new IOError(
+      `unsupported signature scheme: ${JSON.stringify(sig.scheme)} ` +
+        "(this verifier understands eip191-personal-sign)"
+    );
+  }
+  if (typeof container.attestation !== "string") {
+    throw new IOError("signed artifact must embed the canonical UNSIGNED bytes as a string `attestation`");
+  }
+  if (typeof sig.signature !== "string" || !/^0x[0-9a-fA-F]{130}$/.test(sig.signature)) {
+    throw new IOError("signed artifact signature must be a 65-byte (r||s||v) 0x-hex string");
+  }
+  if (typeof sig.signer !== "string" || !ADDRESS_RE.test(sig.signer)) {
+    throw new IOError("signed artifact signer must be a 0x-prefixed 20-byte hex address");
+  }
+  let embedded;
+  try {
+    embedded = JSON.parse(container.attestation);
+  } catch (e) {
+    throw new IOError(`embedded attestation is not valid JSON: ${e.message}`);
+  }
+  return { embedded, message: container.attestation, claimedSigner: sig.signer.toLowerCase(), signature: sig.signature };
+}
+
+// ---------------------------------------------------------------------------
+// Per-file re-derivation, shared by every seal kind AND by both file sources. Given the sealed
+// { relPath, contentHash } entries and a `readEntry` source, fetch each referenced file's bytes through
+// the source, recompute its contentHash, and localize the outcome to MATCH / CHANGED / MISSING /
+// ESCAPED; a file present under a sealed relPath that is NOT in the seal cannot occur here (we only read
+// sealed relPaths) — UNEXPECTED is reported only for seals where the producer enumerates a directory
+// (evidence seal verify re-walks the dir). For artifact verification we follow the producer's read
+// model: read exactly the relPaths the artifact names from the source.
+//
+// SECURITY — CONFINEMENT LIVES IN THE SOURCE. `relPath` values come straight from the attacker-controlled
+// artifact JSON (the threat model is attacker-controls-the-input, victim-runs-on-their-own-machine: a
+// malicious producer hands a counterparty a "verify me" artifact, hoping its relPaths probe the
+// counterparty's filesystem). Each source therefore CONFINES every read BEFORE touching its backing
+// store and answers `{ status: "escaped" }` for a hostile relPath (absolute, a `..` traversal component,
+// or — for the disk source — a resolved/realpath escape of baseDir). An escaped entry is recorded ONLY by
+// relPath (the attacker's string) — we NEVER hash it and NEVER emit an actualContentHash for it, so the
+// verdict can never become a content-confirmation / hash-disclosure oracle over a file outside the
+// source. A `path_escape` entry is a hard REJECTED verdict.
+// ---------------------------------------------------------------------------
+
+function classifyFilesWith(sealedEntries, readEntry) {
+  const changed = [];
+  const missing = [];
+  const matched = [];
+  const escaped = []; // { relPath } only — NEVER a hash; a confinement reject, read nothing
+  const flat = []; // { relPath, contentHash } actually-present, for the root re-derivation
+
+  for (const e of sealedEntries) {
+    const relPath = e.relPath;
+    const r = readEntry(relPath);
+    if (r.status === "escaped") {
+      escaped.push({ relPath: String(relPath) });
+      continue;
+    }
+    if (r.status === "missing") {
+      missing.push({ relPath });
+      continue;
+    }
+    const actual = merkle.hashBytes(r.bytes);
+    flat.push({ relPath, contentHash: actual });
+    if (actual.toLowerCase() === String(e.contentHash).toLowerCase()) {
+      matched.push({ relPath, contentHash: actual });
+    } else {
+      changed.push({ relPath, expectedContentHash: e.contentHash, actualContentHash: actual });
+    }
+  }
+  return { matched, changed, missing, escaped, flat };
+}
+
+// ---------------------------------------------------------------------------
+// Verify an EVIDENCE seal (bare or the embedded seal of a signed container). The seal lists `files`
+// [{ relPath, contentHash, leaf }] + `root`. We re-derive the root from the bytes the source holds and
+// localize any tamper. NO header (evidence seals bind only the file set). UNEXPECTED files (present
+// under a sealed-sibling tree but not named) are NOT scanned here — the artifact names exactly what it
+// commits to; the producer's `vh evidence verify` re-walks the dir, but the standalone verifier verifies
+// what the artifact REFERENCES (read-only, no directory walk). NOTE an "extra" file is still caught
+// structurally: the sealed root commits to the FULL file set, so a seal doctored to omit an entry can
+// never keep its root (root_mismatch), and a signed seal edited that way breaks its signature.
+// ---------------------------------------------------------------------------
+
+function verifyEvidenceSealWith(seal, readEntry) {
+  if (!Array.isArray(seal.files) || seal.files.length === 0) {
+    throw new IOError("evidence seal `files` must be a non-empty array");
+  }
+  if (typeof seal.root !== "string" || !merkle.HEX32_RE.test(seal.root)) {
+    throw new IOError("evidence seal `root` must be a 0x-prefixed 32-byte hex string");
+  }
+  const { matched, changed, missing, escaped, flat } = classifyFilesWith(seal.files, readEntry);
+
+  // The AUTHORITATIVE root is re-derived from the bytes actually held — never the seal's stored root.
+  // A partial/changed set yields a different root; rootMatches goes false.
+  let recomputedRoot = null;
+  if (flat.length > 0) {
+    try {
+      recomputedRoot = merkle.rootFromFlat(flat);
+    } catch (_) {
+      recomputedRoot = null;
+    }
+  }
+  const rootMatches =
+    missing.length === 0 &&
+    changed.length === 0 &&
+    escaped.length === 0 &&
+    recomputedRoot != null &&
+    recomputedRoot.toLowerCase() === seal.root.toLowerCase();
+
+  return {
+    matched,
+    changed,
+    missing,
+    escaped,
+    unexpected: [],
+    sealedRoot: seal.root,
+    recomputedRoot,
+    rootMatches,
+    filesOk: changed.length === 0 && missing.length === 0 && escaped.length === 0 && rootMatches,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Verify a TRUST (reconciliation) seal (bare or embedded). The seal lists `inputs` (role+relPath+
+// contentHash+leaf) and `outputs` (relPath+contentHash+leaf), plus a `verdict` + `root`. The root commits
+// to all inputs + outputs PLUS a synthetic verdict/role HEADER leaf. We re-derive the root from the held
+// bytes AND the header content recomputed from the seal's OWN verdict + input role bindings — so a
+// verdict/role edit (which lives in the seal, not a file) still changes the recomputed root. Inputs are
+// sealed by basename and resolve through the source (the portable handoff ships sources next to the seal).
+// ---------------------------------------------------------------------------
+
+function verifyTrustSealWith(seal, readEntry) {
+  if (!Array.isArray(seal.inputs) || seal.inputs.length === 0) {
+    throw new IOError("trust seal `inputs` must be a non-empty array");
+  }
+  if (!Array.isArray(seal.outputs) || seal.outputs.length === 0) {
+    throw new IOError("trust seal `outputs` must be a non-empty array");
+  }
+  if (typeof seal.root !== "string" || !merkle.HEX32_RE.test(seal.root)) {
+    throw new IOError("trust seal `root` must be a 0x-prefixed 32-byte hex string");
+  }
+  if (seal.verdict == null || typeof seal.verdict !== "object") {
+    throw new IOError("trust seal is missing its `verdict` block");
+  }
+
+  const sealedEntries = [
+    ...seal.inputs.map((e) => ({ relPath: e.relPath, contentHash: e.contentHash, role: e.role })),
+    ...seal.outputs.map((e) => ({ relPath: e.relPath, contentHash: e.contentHash, role: null })),
+  ];
+  const { matched, changed, missing, escaped, flat } = classifyFilesWith(sealedEntries, readEntry);
+
+  // Re-derive the root: the held file leaves PLUS the verdict/role HEADER leaf (content recomputed
+  // from the seal's own verdict + input role bindings). The header is folded in as one more (relPath,
+  // content) pair under the reserved header relPath — exactly the producer's binding.
+  let recomputedRoot = null;
+  // Only attempt the root re-derivation when no file is MISSING or ESCAPED (a partial set can never
+  // re-derive the sealed root anyway, and the header binds the FULL committed structure).
+  if (missing.length === 0 && escaped.length === 0 && flat.length === seal.inputs.length + seal.outputs.length) {
+    try {
+      const headerBytes = canonical.trustSealHeaderBytes(
+        seal.verdict,
+        seal.inputs.map((e) => ({ role: e.role, relPath: e.relPath }))
+      );
+      const committed = [
+        ...flat,
+        { relPath: canonical.TRUST_SEAL_HEADER_RELPATH, contentHash: merkle.hashBytes(headerBytes) },
+      ];
+      recomputedRoot = merkle.rootFromFlat(committed);
+    } catch (_) {
+      recomputedRoot = null;
+    }
+  }
+  const rootMatches =
+    escaped.length === 0 &&
+    recomputedRoot != null &&
+    recomputedRoot.toLowerCase() === seal.root.toLowerCase();
+
+  return {
+    matched,
+    changed,
+    missing,
+    escaped,
+    unexpected: [],
+    sealedRoot: seal.root,
+    recomputedRoot,
+    rootMatches,
+    filesOk: changed.length === 0 && missing.length === 0 && escaped.length === 0 && rootMatches,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Verify a DATASET attestation (bare/signed/timestamped). A dataset attestation commits to the dataset
+// IDENTITY (root, fileCount, manifestDigest) — it does NOT carry the per-file list, so there are no
+// sibling bytes to re-derive a Merkle root from without the original manifest. The independent verifier
+// therefore confirms the embedded identity is well-formed + (for signed) recovers/pins the signer; the
+// `root` is the dataset's, carried as-is. (`vh dataset verify <dir> --manifest` is the path that
+// re-derives a root from a live tree; the attestation alone has no tree to re-walk.)
+// ---------------------------------------------------------------------------
+
+function verifyDatasetAttestation(att) {
+  for (const f of ["root", "manifestDigest"]) {
+    if (typeof att[f] !== "string" || !merkle.HEX32_RE.test(att[f])) {
+      throw new IOError(`dataset attestation ${f} must be a 0x-prefixed 32-byte hex string`);
+    }
+  }
+  if (!Number.isInteger(att.fileCount) || att.fileCount < 1) {
+    throw new IOError("dataset attestation fileCount must be a positive integer");
+  }
+  return {
+    matched: [],
+    changed: [],
+    missing: [],
+    escaped: [],
+    unexpected: [],
+    sealedRoot: att.root,
+    recomputedRoot: null,
+    rootMatches: null, // no sibling bytes to re-derive a root from (identity-only artifact)
+    filesOk: true, // structural identity is sound; the binding is via the signature for signed variants
+    identityOnly: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Verify a PROOF bundle. A proof artifact carries { root, leaf, contentHash, relPath, proof[] }. We
+// RE-DERIVE the leaf from relPath + contentHash, then fold leafHash(leaf) up through the proof siblings
+// with nodeHash and confirm it reproduces `root` — byte-identically to the on-chain verifyLeaf, but
+// fully OFFLINE. (The on-chain "is this root anchored" check is out of scope for the offline verifier.)
+// ---------------------------------------------------------------------------
+
+function verifyProofBundle(art) {
+  for (const f of ["root", "leaf", "contentHash"]) {
+    if (typeof art[f] !== "string" || !merkle.HEX32_RE.test(art[f])) {
+      throw new IOError(`proof artifact ${f} must be a 0x-prefixed 32-byte hex string`);
+    }
+  }
+  if (typeof art.relPath !== "string" || art.relPath.length === 0) {
+    throw new IOError("proof artifact relPath must be a non-empty string");
+  }
+  if (!Array.isArray(art.proof)) {
+    throw new IOError("proof artifact `proof` must be an array of 0x 32-byte hex siblings");
+  }
+  const derivedLeaf = merkle.pathLeaf(art.relPath, art.contentHash);
+  const leafMatches = derivedLeaf.toLowerCase() === art.leaf.toLowerCase();
+  let computed = merkle.leafHash(art.leaf);
+  for (const sib of art.proof) {
+    computed = merkle.nodeHash(computed, sib);
+  }
+  const foldsToRoot = computed.toLowerCase() === art.root.toLowerCase();
+  return {
+    matched: leafMatches && foldsToRoot ? [{ relPath: art.relPath, contentHash: art.contentHash }] : [],
+    changed:
+      leafMatches && foldsToRoot ? [] : [{ relPath: art.relPath, expectedContentHash: art.root, actualContentHash: computed }],
+    missing: [],
+    escaped: [],
+    unexpected: [],
+    sealedRoot: art.root,
+    recomputedRoot: computed,
+    rootMatches: leafMatches && foldsToRoot,
+    filesOk: leafMatches && foldsToRoot,
+    proof: { derivedLeaf, leafMatches, foldsToRoot },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Verify an AGENT-SESSION packet (T-68.3 — the AgentTrace funnel leg, FREE surface only).
+//
+// A `*.vhagent.json` packet is SELF-CONTAINED: it carries its ordered event list (full and/or
+// REDACTED), a per-event leaf expectation list, and an RFC-6962-style ordered Merkle head
+// { size, root } — there are NO sibling files to read, so `readEntry` is never consulted. This block
+// RE-DERIVES every event leaf and the root from the events the packet holds, exactly as the producer's
+// `vh agent verify` does, but from an INDEPENDENT implementation surface: everything below is written
+// against the verifier's OWN dependency-free keccak (merkle.hashBytes) — it imports NOTHING from cli/.
+//
+// THE CONVENTION (must match cli/core/agent-session.js + cli/journal-log.js VERBATIM):
+//   * payloadHash  = keccak256(utf8(payload))                                (the payload COMMITMENT)
+//   * event leaf   = keccak256(utf8(JSON.stringify([
+//                      LEAF_DOMAIN, seq, ts, actor, type, payloadHash, canonicalMetaJson|null ])))
+//     — the payload participates ONLY via its commitment, so a FULL event and its REDACTED twin
+//     (payload dropped, commitment carried, `redacted: true`) derive the IDENTICAL leaf: redaction
+//     changes neither the leaves nor the root (it can WITHHOLD, never silently ALTER).
+//   * the ordered tree (RFC 6962, position-bound, NO sorting — the OPPOSITE of the evidence tree):
+//       leaf node = keccak256(0x00 || leaf)      interior = keccak256(0x01 || left || right)
+//       MTH(D[0:n]) = interior(MTH(D[0:k]), MTH(D[k:n])), k = largest power of two < n
+//       empty log root = keccak256(utf8("vh.journal-log/v1:empty-root"))
+//   * a SIGNED packet carries `headAttestation`: a detached EIP-191 personal-sign over the EXACT
+//     canonical head-payload bytes (the embedded `attestation` string). The signature wraps the HEAD,
+//     so ONE signature stays valid for every redacted copy of the same sealed session.
+//
+// VERDICTS: event-level tamper (a payload that no longer matches its carried commitment — including a
+// REDACTED event whose commitment was forged — or a leaf that no longer matches its expectation) is a
+// REJECT NAMING THE SEQ; a tampered head is `root_mismatch`; a forged signature is `bad_signature`; a
+// sound signature by the wrong signer under a --vendor pin is `wrong_issuer`; a --vendor pin on an
+// UNSIGNED packet is `unsigned_cannot_pin_vendor` (a stripped signature never passes a pinned verify).
+// The recompute is AUTHORITATIVE: the packet is an untrusted container and its stored hashes are only
+// EXPECTATIONS checked against.
+// ---------------------------------------------------------------------------
+
+// The producer's in-band trust note, REQUIRED verbatim (the packetseal discipline: the caveat may not
+// drift; a packet whose note was edited is structurally invalid, exactly as `vh agent verify` treats it).
+const AGENT_TRUST_NOTE =
+  "This agent-session packet is TAMPER-EVIDENT + OFFLINE-RECOMPUTABLE, NOT a trusted timestamp and " +
+  "NOT a claim the agent behaved well. Its ordered Merkle `head` {size, root} (RFC-6962-style, " +
+  "position-bound) commits to every event: verify RE-DERIVES each event leaf — recomputing the " +
+  "payload hash commitment for a FULL event, checking the carried commitment for a REDACTED one — " +
+  "and the root from the events you hold, and a REJECT names the first offending event seq. " +
+  "Redaction WITHHOLDS a payload behind its hash commitment without changing any leaf or the root: " +
+  "it can hide, never silently alter. Event `ts` fields are SELF-ASSERTED metadata (recorded, never " +
+  'verified against any clock); "sealed at time T" rides the human-owned signing/timestamp ' +
+  "trust-root (STRATEGY.md P-3). Garbage-in is out of scope: the head proves the LOG is intact and " +
+  "append-only, not that the log faithfully records what the agent actually did. The packet is an " +
+  "UNTRUSTED transport container: verify never trusts the packet's own stored hashes.";
+
+const AGENT_SIGNED_HEAD_TRUST_NOTE =
+  "This is a SIGNED agent-session HEAD attestation: it WRAPS (never edits) the EXACT canonical head " +
+  "bytes in `attestation` and attaches a detached EIP-191 signature. It asserts the holder of the " +
+  "`signer` key vouched for THIS session head {size, root} at signing time. Because event leaves " +
+  "are redaction-safe, the SAME signature stays valid for every redacted copy of the sealed session " +
+  "(redaction changes neither leaves nor root). It does NOT prove a timestamp (no \"sealed since " +
+  "T\" — still the human trust-root P-3) and is NOT a legal opinion. Every caveat of the packet " +
+  "applies. " +
+  AGENT_TRUST_NOTE;
+
+const AGENT_HEAD_KIND = "vh.agent-head";
+const AGENT_SIGNED_HEAD_KIND = "vh.agent-head-signed";
+const AGENT_PACKET_SCHEMA_VERSIONS = Object.freeze([1]);
+const AGENT_EVENT_TYPES = Object.freeze(["prompt", "completion", "tool_call", "tool_result", "note"]);
+const AGENT_EVENT_FIELDS = Object.freeze([
+  "seq",
+  "ts",
+  "actor",
+  "type",
+  "payload",
+  "payloadHash",
+  "redacted",
+  "meta",
+]);
+const AGENT_LEAF_DOMAIN = "vh.agent-session/v1:event-leaf";
+const AGENT_EMPTY_ROOT_DOMAIN = "vh.journal-log/v1:empty-root";
+const AGENT_META_MAX_DEPTH = 32;
+const AGENT_META_MAX_NODES = 100000;
+
+// Canonical-case wire shapes (the producer emits lowercase-only hex; mixed case is a foreign artifact).
+const AGENT_HEX32_LC_RE = /^0x[0-9a-f]{64}$/;
+const AGENT_ADDRESS_LC_RE = /^0x[0-9a-f]{40}$/;
+const AGENT_SIG_LC_RE = /^0x[0-9a-f]{130}$/;
+
+// STRICT UTF-8 encoder that MIRRORS the producer's ethers `toUtf8Bytes` byte-for-byte (verified over
+// the whole 0x0000..0xFFFF code-unit space + surrogate edge cases). ethers' default error mode THROWS
+// only on a lone HIGH surrogate (an unfinished pair, no code point) — so this returns null there — but
+// it ENCODES a lone LOW surrogate as its literal 3-byte sequence (U+DC00 -> ed b0 80), NOT an error;
+// so a lone low surrogate falls straight through to the c<0x10000 branch below (matching the producer,
+// whose commitment over such a payload is well-defined). Pure JS; no TextEncoder (which would silently
+// substitute U+FFFD and DIVERGE from the producer). null => the event's commitment is undefined here
+// exactly as it is for the producer, so both sides reject in lockstep (fail-closed, never a mismatch).
+function agentUtf8Bytes(str) {
+  const out = [];
+  for (let i = 0; i < str.length; i++) {
+    let c = str.charCodeAt(i);
+    if (c >= 0xd800 && c <= 0xdbff) {
+      const lo = i + 1 < str.length ? str.charCodeAt(i + 1) : -1;
+      if (lo < 0xdc00 || lo > 0xdfff) return null; // lone HIGH surrogate (ethers THROWS; no code point)
+      c = (c - 0xd800) * 0x400 + (lo - 0xdc00) + 0x10000;
+      i++;
+    }
+    // A lone LOW surrogate (0xdc00..0xdfff) is NOT special-cased: ethers encodes it as its 3-byte form
+    // via the c<0x10000 branch, so we do too — deleting the old lone-low `return null` that FALSELY
+    // rejected genuine packets carrying truncated-UTF-16 / arbitrary-tool-result bytes.
+    if (c < 0x80) out.push(c);
+    else if (c < 0x800) out.push(0xc0 | (c >> 6), 0x80 | (c & 63));
+    else if (c < 0x10000) out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
+    else out.push(0xf0 | (c >> 18), 0x80 | ((c >> 12) & 63), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
+  }
+  return new Uint8Array(out);
+}
+
+// 0x-hex -> bytes, and a tiny concat — the only byte plumbing the ordered tree needs.
+function agentHexToBytes(hex) {
+  const s = hex.slice(2);
+  const out = new Uint8Array(s.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(s.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+function agentConcatBytes(list) {
+  let total = 0;
+  for (const b of list) total += b.length;
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const b of list) {
+    out.set(b, off);
+    off += b.length;
+  }
+  return out;
+}
+
+// RFC-6962 domain-separated hashing over the verifier's OWN keccak (merkle.hashBytes — the same
+// independent primitive every other artifact family here is re-derived with). Children fold in TREE
+// ORDER (never sorted): position IS meaning in an ordered session log.
+function agentLeafNodeHash(leafHex) {
+  return merkle.hashBytes(agentConcatBytes([Uint8Array.of(0x00), agentHexToBytes(leafHex)]));
+}
+function agentInteriorHash(leftHex, rightHex) {
+  return merkle.hashBytes(
+    agentConcatBytes([Uint8Array.of(0x01), agentHexToBytes(leftHex), agentHexToBytes(rightHex)])
+  );
+}
+
+// MTH (RFC 6962 §2.1) over the ORDERED leaf values; the empty log has a domain-separated constant root.
+function agentTreeRoot(leaves) {
+  if (leaves.length === 0) return merkle.hashBytes(agentUtf8Bytes(AGENT_EMPTY_ROOT_DOMAIN));
+  function mth(lo, hi) {
+    const n = hi - lo;
+    if (n === 1) return agentLeafNodeHash(leaves[lo]);
+    let k = 1;
+    while (k * 2 < n) k *= 2;
+    return agentInteriorHash(mth(lo, lo + k), mth(lo + k, hi));
+  }
+  return mth(0, leaves.length);
+}
+
+// A "plain" JSON-shaped object (prototype Object.prototype or null) — the same strictness the producer
+// applies, so what is hashed is exactly what could be written to disk and read back.
+function agentIsPlainObject(v) {
+  if (v === null || typeof v !== "object" || Array.isArray(v)) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+
+// Canonical JSON for `meta`: keys SORTED, only JSON-representable values, depth capped, and a TOTAL
+// work budget so a shared-reference DAG can never hang the verifier. Returns the canonical text or
+// null (reject) — byte-identical to the producer's canonicalization for every accepted value.
+function agentCanonicalJson(value, depth, budget) {
+  if (depth > AGENT_META_MAX_DEPTH) return null;
+  if (++budget.n > AGENT_META_MAX_NODES) return null;
+  if (value === null) return "null";
+  const t = typeof value;
+  if (t === "boolean") return value ? "true" : "false";
+  if (t === "number") return Number.isFinite(value) ? JSON.stringify(value) : null;
+  if (t === "string") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    const parts = [];
+    for (const item of value) {
+      const p = agentCanonicalJson(item, depth + 1, budget);
+      if (p === null) return null;
+      parts.push(p);
+    }
+    return "[" + parts.join(",") + "]";
+  }
+  if (agentIsPlainObject(value)) {
+    const keys = Object.keys(value).sort();
+    const parts = [];
+    for (const k of keys) {
+      const p = agentCanonicalJson(value[k], depth + 1, budget);
+      if (p === null) return null;
+      parts.push(JSON.stringify(k) + ":" + p);
+    }
+    return "{" + parts.join(",") + "}";
+  }
+  return null;
+}
+
+// The payload COMMITMENT: keccak256 over the payload's UTF-8 bytes. null on a non-string or a string
+// with no UTF-8 encoding (a lone HIGH surrogate — where ethers throws) — TOTAL, mirrors the producer
+// exactly (a lone LOW surrogate IS encodable, so it commits rather than rejecting).
+function agentPayloadHash(payload) {
+  if (typeof payload !== "string") return null;
+  const bytes = agentUtf8Bytes(payload);
+  return bytes === null ? null : merkle.hashBytes(bytes);
+}
+
+// STRICT validation of one canonical event — an INDEPENDENT re-implementation of the producer's rules
+// (closed field set; exactly the FULL or REDACTED shape; a carried commitment on a full event must
+// equal the recomputed one). Never throws; every failure is a named { ok:false, reason, field? } (the
+// commitment-mismatch reject also carries carried/recomputed so the caller can localize the change).
+function agentValidateEvent(event) {
+  try {
+    if (!agentIsPlainObject(event)) return { ok: false, reason: "EVENT_NOT_OBJECT" };
+    for (const k of Object.keys(event)) {
+      if (!AGENT_EVENT_FIELDS.includes(k)) return { ok: false, reason: "EVENT_UNKNOWN_FIELD", field: k };
+    }
+    if (!Number.isSafeInteger(event.seq) || event.seq < 0) {
+      return { ok: false, reason: "EVENT_BAD_SEQ", field: "seq" };
+    }
+    if (typeof event.ts !== "string") return { ok: false, reason: "EVENT_BAD_TS", field: "ts" };
+    if (typeof event.actor !== "string" || event.actor.length === 0) {
+      return { ok: false, reason: "EVENT_BAD_ACTOR", field: "actor" };
+    }
+    if (!AGENT_EVENT_TYPES.includes(event.type)) return { ok: false, reason: "EVENT_BAD_TYPE", field: "type" };
+    const hasPayload = "payload" in event;
+    const hasHash = "payloadHash" in event;
+    if (hasPayload && typeof event.payload !== "string") {
+      return { ok: false, reason: "EVENT_BAD_PAYLOAD", field: "payload" };
+    }
+    if (hasHash && !(typeof event.payloadHash === "string" && merkle.HEX32_RE.test(event.payloadHash))) {
+      return { ok: false, reason: "EVENT_BAD_PAYLOAD_HASH", field: "payloadHash" };
+    }
+    if ("redacted" in event && typeof event.redacted !== "boolean") {
+      return { ok: false, reason: "EVENT_BAD_REDACTED_FLAG", field: "redacted" };
+    }
+    if (!hasPayload && !hasHash) return { ok: false, reason: "EVENT_MISSING_PAYLOAD", field: "payload" };
+    if (event.redacted === true && hasPayload) {
+      return { ok: false, reason: "EVENT_REDACTED_WITH_PAYLOAD", field: "redacted" };
+    }
+    if (event.redacted === true && !hasHash) {
+      return { ok: false, reason: "EVENT_BAD_PAYLOAD_HASH", field: "payloadHash" };
+    }
+    if (!hasPayload && event.redacted !== true) {
+      return { ok: false, reason: "EVENT_UNFLAGGED_REDACTION", field: "redacted" };
+    }
+    let commitment;
+    if (hasPayload) {
+      commitment = agentPayloadHash(event.payload);
+      if (commitment === null) return { ok: false, reason: "EVENT_BAD_PAYLOAD", field: "payload" };
+      if (hasHash && commitment !== event.payloadHash.toLowerCase()) {
+        return {
+          ok: false,
+          reason: "EVENT_PAYLOAD_HASH_MISMATCH",
+          field: "payloadHash",
+          carried: event.payloadHash.toLowerCase(),
+          recomputed: commitment,
+        };
+      }
+    } else {
+      commitment = event.payloadHash.toLowerCase();
+    }
+    let metaJson = null;
+    if ("meta" in event) {
+      metaJson = agentCanonicalJson(event.meta, 0, { n: 0 });
+      if (metaJson === null) return { ok: false, reason: "EVENT_BAD_META", field: "meta" };
+    }
+    return { ok: true, redacted: !hasPayload, payloadHash: commitment, metaJson };
+  } catch (_) {
+    return { ok: false, reason: "HOSTILE_INPUT" };
+  }
+}
+
+// The redaction-safe LEAF VALUE of one validated event: the fixed-position JSON array preimage with
+// the payload represented ONLY by its commitment (so a full event and its redacted twin derive the
+// identical leaf). Returns null only for an encoding fault (kept total).
+function agentEventLeaf(event, validated) {
+  const encoded = JSON.stringify([
+    AGENT_LEAF_DOMAIN,
+    event.seq,
+    event.ts,
+    event.actor,
+    event.type,
+    validated.payloadHash,
+    validated.metaJson,
+  ]);
+  const bytes = agentUtf8Bytes(encoded);
+  return bytes === null ? null : merkle.hashBytes(bytes);
+}
+
+// The shared { size, root } head shape. Throws IOError (a malformed/foreign artifact, exit 1 — the same
+// class `vh agent verify` gives a structurally invalid packet).
+function validateAgentHeadShape(head, label) {
+  if (head == null || typeof head !== "object" || Array.isArray(head)) {
+    throw new IOError(`${label} \`head\` must be a { size, root } object`);
+  }
+  for (const k of Object.keys(head)) {
+    if (k !== "size" && k !== "root") {
+      throw new IOError(`${label} head has unknown field: ${JSON.stringify(k)}`);
+    }
+  }
+  if (!Number.isSafeInteger(head.size) || head.size < 0) {
+    throw new IOError(`${label} head.size must be a non-negative integer, got: ${String(head.size)}`);
+  }
+  if (typeof head.root !== "string" || !AGENT_HEX32_LC_RE.test(head.root)) {
+    throw new IOError(
+      `${label} head.root must be a LOWERCASE 0x-bytes32 hex string, got: ${String(head.root)}`
+    );
+  }
+}
+
+// STRICT structural validation of the OPTIONAL signed-head container: the exact canonical embedded
+// bytes, a known scheme, lowercase signer/signature, and an embedded head payload in canonical form.
+// Returns { embeddedHead } for the binding check. Throws IOError on any structural defect.
+function validateAgentSignedHead(container) {
+  const label = "agent-session packet headAttestation";
+  if (container == null || typeof container !== "object" || Array.isArray(container)) {
+    throw new IOError(`${label} must be a JSON object`);
+  }
+  const KNOWN = ["kind", "schemaVersion", "note", "attestation", "signature"];
+  for (const k of Object.keys(container)) {
+    if (!KNOWN.includes(k)) throw new IOError(`${label} has unknown field: ${JSON.stringify(k)}`);
+  }
+  if (container.kind !== AGENT_SIGNED_HEAD_KIND) {
+    throw new IOError(
+      `${label} kind must be ${JSON.stringify(AGENT_SIGNED_HEAD_KIND)}, got: ${JSON.stringify(container.kind)}`
+    );
+  }
+  if (container.schemaVersion !== 1) {
+    throw new IOError(`${label} has unsupported schemaVersion: ${JSON.stringify(container.schemaVersion)}`);
+  }
+  if (container.note !== AGENT_SIGNED_HEAD_TRUST_NOTE) {
+    throw new IOError(`${label} note must be the standing signed-head trust note (caveat must not drift)`);
+  }
+  if (typeof container.attestation !== "string") {
+    throw new IOError(`${label} must embed the canonical UNSIGNED head bytes as a string \`attestation\``);
+  }
+  let embedded;
+  try {
+    embedded = JSON.parse(container.attestation);
+  } catch (e) {
+    throw new IOError(`${label} embedded attestation is not valid JSON: ${e.message}`);
+  }
+  if (
+    embedded == null ||
+    typeof embedded !== "object" ||
+    Array.isArray(embedded) ||
+    embedded.kind !== AGENT_HEAD_KIND ||
+    embedded.schemaVersion !== 1 ||
+    embedded.note !== AGENT_TRUST_NOTE
+  ) {
+    throw new IOError(`${label} embedded payload is not a canonical ${JSON.stringify(AGENT_HEAD_KIND)} payload`);
+  }
+  validateAgentHeadShape(embedded.head, `${label} embedded payload`);
+  // The embedded string must be the EXACT canonical serialization (the byte-unambiguous signed message);
+  // an insignificant-whitespace/reordered variant is a foreign artifact.
+  const canonicalText =
+    JSON.stringify({
+      kind: embedded.kind,
+      schemaVersion: embedded.schemaVersion,
+      note: embedded.note,
+      head: { size: embedded.head.size, root: embedded.head.root },
+    }) + "\n";
+  if (container.attestation !== canonicalText) {
+    throw new IOError(`${label} embedded attestation is not in canonical form (the signed-over bytes are ambiguous)`);
+  }
+  const sig = container.signature;
+  if (sig == null || typeof sig !== "object" || Array.isArray(sig)) {
+    throw new IOError(`${label} signature must be a { scheme, signer, signature } object`);
+  }
+  if (sig.scheme !== "eip191-personal-sign") {
+    throw new IOError(
+      `${label} has unsupported signature scheme: ${JSON.stringify(sig.scheme)} (this verifier understands eip191-personal-sign)`
+    );
+  }
+  if (typeof sig.signer !== "string" || !AGENT_ADDRESS_LC_RE.test(sig.signer)) {
+    throw new IOError(`${label} signer must be a LOWERCASE 0x-prefixed 20-byte hex address`);
+  }
+  if (typeof sig.signature !== "string" || !AGENT_SIG_LC_RE.test(sig.signature)) {
+    throw new IOError(`${label} signature must be a 65-byte (r||s||v) LOWERCASE 0x-hex string`);
+  }
+  return { embeddedHead: { size: embedded.head.size, root: embedded.head.root } };
+}
+
+// STRICT structural validation of a parsed packet (SHAPE only — the per-event/leaf/root RECOMPUTE is
+// verifyAgentSeal's job, so event-level tamper stays a NAMED verdict naming the seq, never a throw).
+// Mirrors the producer's validatePacketShape defect-for-defect. Throws IOError.
+function validateAgentPacketStructure(obj) {
+  const label = "agent-session packet";
+  const KNOWN = ["kind", "schemaVersion", "note", "head", "counts", "events", "leaves", "headAttestation"];
+  for (const k of Object.keys(obj)) {
+    if (!KNOWN.includes(k)) throw new IOError(`${label} has unknown field: ${JSON.stringify(k)}`);
+  }
+  if (!AGENT_PACKET_SCHEMA_VERSIONS.includes(obj.schemaVersion)) {
+    throw new IOError(
+      `unsupported ${label} schemaVersion: ${JSON.stringify(obj.schemaVersion)} ` +
+        `(this verifier understands ${JSON.stringify(AGENT_PACKET_SCHEMA_VERSIONS)})`
+    );
+  }
+  if (obj.note !== AGENT_TRUST_NOTE) {
+    throw new IOError(`${label} \`note\` must be the standing trust note (caveat must not drift)`);
+  }
+  validateAgentHeadShape(obj.head, label);
+  if (obj.counts == null || typeof obj.counts !== "object" || Array.isArray(obj.counts)) {
+    throw new IOError(`${label} \`counts\` must be a { events, full, redacted } object`);
+  }
+  for (const k of Object.keys(obj.counts)) {
+    if (!["events", "full", "redacted"].includes(k)) {
+      throw new IOError(`${label} counts has unknown field: ${JSON.stringify(k)}`);
+    }
+  }
+  for (const k of ["events", "full", "redacted"]) {
+    if (!Number.isSafeInteger(obj.counts[k]) || obj.counts[k] < 0) {
+      throw new IOError(`${label} counts.${k} must be a non-negative integer, got: ${String(obj.counts[k])}`);
+    }
+  }
+  if (!Array.isArray(obj.events)) throw new IOError(`${label} \`events\` must be an array`);
+  if (!Array.isArray(obj.leaves) || obj.leaves.length !== obj.events.length) {
+    throw new IOError(`${label} \`leaves\` must be an array with EXACTLY one leaf expectation per event`);
+  }
+  obj.leaves.forEach((l, i) => {
+    if (typeof l !== "string" || !AGENT_HEX32_LC_RE.test(l)) {
+      throw new IOError(`${label} leaves[${i}] must be a LOWERCASE 0x-bytes32 hex string, got: ${String(l)}`);
+    }
+  });
+  if (obj.head.size !== obj.events.length) {
+    throw new IOError(
+      `${label} head.size (${obj.head.size}) does not match the events length (${obj.events.length})`
+    );
+  }
+  if (obj.counts.events !== obj.events.length || obj.counts.full + obj.counts.redacted !== obj.counts.events) {
+    throw new IOError(
+      `${label} \`counts\` is internally inconsistent (events must equal the events length; full + redacted must equal events)`
+    );
+  }
+  let signedHead = null;
+  if (obj.headAttestation !== undefined) signedHead = validateAgentSignedHead(obj.headAttestation);
+  return { packet: obj, signedHead };
+}
+
+// The AUTHORITATIVE per-event/leaf/root/counts RECOMPUTE over a shape-validated packet. Returns the
+// engine's standard fileResult shape (matched/changed/... + roots) PLUS an `agent` sub-verdict block
+// and a `reasonKind` in the verifier's reason vocabulary. Event faults are localized to the FIRST
+// offending seq, exactly as the producer's verify names it. Never throws.
+function verifyAgentSeal(packet) {
+  const matched = [];
+  const changed = [];
+  const withheld = [];
+  const agent = {
+    head: { size: packet.head.size, root: packet.head.root },
+    recomputedHead: null,
+    counts: null,
+    withheld: null,
+    seq: null,
+    reason: null,
+  };
+  const base = {
+    matched,
+    changed,
+    missing: [],
+    escaped: [],
+    unexpected: [],
+    sealedRoot: packet.head.root,
+    recomputedRoot: null,
+    rootMatches: null,
+    filesOk: false,
+    reasonKind: null,
+    agent,
+  };
+  const events = packet.events;
+  const leaves = [];
+  for (let i = 0; i < events.length; i++) {
+    const v = agentValidateEvent(events[i]);
+    if (!v.ok) {
+      agent.seq = i;
+      agent.reason = v.reason;
+      if (v.field !== undefined) agent.field = v.field;
+      if (v.reason === "EVENT_PAYLOAD_HASH_MISMATCH") {
+        // The payload no longer matches its carried commitment: a CONTENT change localized to its seq
+        // (this is also how a REDACTED event's FORGED commitment surfaces once its leaf is checked).
+        changed.push({ relPath: `events[${i}]`, expectedContentHash: v.carried, actualContentHash: v.recomputed });
+        base.reasonKind = "CHANGED";
+      } else {
+        base.reasonKind = "event_invalid";
+      }
+      return base;
+    }
+    if (events[i].seq !== i) {
+      agent.seq = i;
+      agent.reason = "SESSION_SEQ_NOT_CONTIGUOUS";
+      base.reasonKind = "event_invalid";
+      return base;
+    }
+    const leaf = agentEventLeaf(events[i], v);
+    if (leaf === null || leaf !== packet.leaves[i]) {
+      // A bound-field edit (ts/actor/type/meta) or a forged redacted commitment: the re-derived leaf no
+      // longer matches the packet's own expectation — named by seq, recompute authoritative.
+      agent.seq = i;
+      agent.reason = "EVENT_LEAF_MISMATCH";
+      changed.push({ relPath: `events[${i}]`, expectedContentHash: packet.leaves[i], actualContentHash: leaf });
+      base.reasonKind = "CHANGED";
+      return base;
+    }
+    leaves.push(leaf);
+    matched.push({ relPath: `events[${i}]`, contentHash: leaf });
+    if (v.redacted) withheld.push(i);
+  }
+  const recomputedRoot = agentTreeRoot(leaves);
+  base.recomputedRoot = recomputedRoot;
+  agent.recomputedHead = { size: leaves.length, root: recomputedRoot };
+  base.rootMatches = leaves.length === packet.head.size && recomputedRoot === packet.head.root;
+  if (!base.rootMatches) {
+    agent.reason = "HEAD_MISMATCH";
+    base.reasonKind = "root_mismatch";
+    return base;
+  }
+  const full = events.length - withheld.length;
+  agent.counts = { events: events.length, full, redacted: withheld.length };
+  agent.withheld = withheld;
+  if (packet.counts.full !== full || packet.counts.redacted !== withheld.length) {
+    agent.reason = "COUNTS_MISMATCH";
+    base.reasonKind = "counts_mismatch";
+    return base;
+  }
+  base.filesOk = true;
+  return base;
+}
+
+// The artifact-level orchestrator for KINDS.AGENT_PACKET — both entrypoints (disk + bytes) route here
+// through verifyParsedArtifact, so the two paths' verdicts are one code path (deep-equal by
+// construction). Precedence mirrors the producer's `vh agent verify`: event/leaf/head/counts faults
+// (naming the seq) dominate; then head binding, signature genuineness, and the vendor pin.
+function verifyAgentPacketArtifact({ artifact, obj, pinned }) {
+  const { signedHead } = validateAgentPacketStructure(obj); // throws IOError on a malformed/foreign packet
+  const fileResult = verifyAgentSeal(obj);
+  const agent = fileResult.agent;
+
+  const signed = obj.headAttestation !== undefined;
+  let recoveredSigner = null;
+  let claimedSigner = null;
+  let signatureOk = null;
+  let signerMatchesVendor = null;
+  let headBound = null;
+  if (signed) {
+    claimedSigner = obj.headAttestation.signature.signer; // lowercase, structurally enforced
+    recoveredSigner = tryRecover(obj.headAttestation.attestation, obj.headAttestation.signature.signature);
+    signatureOk = recoveredSigner != null && recoveredSigner === claimedSigner;
+    if (agent.recomputedHead != null) {
+      // The signature must vouch for THIS session's RECOMPUTED head — a signature pasted from a
+      // different session recovers fine but binds a different { size, root }.
+      headBound =
+        signedHead.embeddedHead.size === agent.recomputedHead.size &&
+        signedHead.embeddedHead.root === agent.recomputedHead.root;
+    }
+    if (signatureOk && pinned != null) signerMatchesVendor = recoveredSigner === pinned;
+  }
+
+  let accepted = true;
+  let reason = "OK";
+  if (!fileResult.filesOk) {
+    accepted = false;
+    reason = fileResult.reasonKind;
+  } else if (signed && headBound === false) {
+    accepted = false;
+    reason = "head_not_bound";
+    agent.reason = "HEAD_NOT_BOUND";
+  } else if (signed && !signatureOk) {
+    accepted = false;
+    reason = "bad_signature";
+    agent.reason = "SIGNATURE_FORGED";
+  } else if (signed && pinned != null && signerMatchesVendor !== true) {
+    accepted = false;
+    reason = "wrong_issuer";
+    agent.reason = "WRONG_VENDOR";
+  } else if (!signed && pinned != null) {
+    // Fail-closed pin: a stripped signature can never pass a pinned verify.
+    accepted = false;
+    reason = "unsigned_cannot_pin_vendor";
+    agent.reason = "NOT_SIGNED";
+  }
+
+  const result = {
+    artifact,
+    kind: KINDS.AGENT_PACKET,
+    payloadKind: KINDS.AGENT_PACKET,
+    signed,
+    verdict: accepted ? "OK" : "REJECTED",
+    reason,
+    accepted,
+    recoveredSigner,
+    claimedSigner,
+    pinnedVendor: pinned,
+    signatureOk,
+    signerMatchesVendor,
+    sealedRoot: fileResult.sealedRoot,
+    recomputedRoot: fileResult.recomputedRoot,
+    rootMatches: fileResult.rootMatches,
+    counts: {
+      matched: fileResult.matched.length,
+      changed: fileResult.changed.length,
+      missing: 0,
+      escaped: 0,
+      unexpected: 0,
+    },
+    matched: fileResult.matched,
+    changed: fileResult.changed,
+    missing: [],
+    escaped: [],
+    unexpected: [],
+    agent,
+    note: TRUST_NOTE,
+  };
+  return { result, code: accepted ? EXIT.OK : EXIT.REJECTED };
+}
+
+// ---------------------------------------------------------------------------
+// The core verify orchestration over an ALREADY-PARSED artifact object + an injected file source. This
+// is the ONE engine BOTH entrypoints drive — `verifyArtifact` (disk: the CLI contract, byte-identical to
+// before this seam existed) and `verifyArtifactFromBytes` (in-memory map). It auto-detects the artifact
+// kind, decodes a signed container (recovering + pinning the signer), re-derives the root from
+// referenced bytes, and assembles a deterministic verdict. PURE: every read goes through `readEntry`.
+// Returns { result, code } — code is the EXIT-contract integer.
+// ---------------------------------------------------------------------------
+
+function verifyParsedArtifact({ artifact, obj, vendor, readEntry }) {
+  const kind = obj.kind;
+  const pinned = vendor != null ? normalizeAddress(vendor, "--vendor") : null;
+
+  // AGENT-SESSION packet (T-68.3): SELF-CONTAINED — no sibling bytes, its own leaf/root convention and
+  // its own in-packet signed head. Routed to the dedicated orchestrator above (`readEntry` unused).
+  if (kind === KINDS.AGENT_PACKET) {
+    return verifyAgentPacketArtifact({ artifact, obj, pinned });
+  }
+
+  // Detect signed vs bare and the underlying payload kind. A signed container wraps the embedded payload.
+  let signed = false;
+  let recoveredSigner = null;
+  let claimedSigner = null;
+  let signatureOk = null; // null = no signature on this artifact
+  let payload = obj; // the (possibly embedded) thing whose root we re-derive
+  let payloadKind = kind;
+
+  if (
+    kind === KINDS.EVIDENCE_SEAL_SIGNED ||
+    kind === KINDS.TRUST_SEAL_SIGNED ||
+    kind === KINDS.DATASET_ATTESTATION_SIGNED ||
+    kind === KINDS.DATASET_ATTESTATION_TIMESTAMPED
+  ) {
+    signed = true;
+    const dec = decodeSigned(obj);
+    payload = dec.embedded;
+    payloadKind = dec.embedded.kind;
+    claimedSigner = dec.claimedSigner;
+    recoveredSigner = tryRecover(dec.message, dec.signature);
+    // signatureOk: the signature recovers AND matches the CLAIMED signer recorded in the container.
+    signatureOk = recoveredSigner != null && recoveredSigner === claimedSigner;
+  } else if (!Object.values(KINDS).includes(kind)) {
+    throw new UsageError(
+      `unrecognized artifact kind: ${JSON.stringify(kind)} ` +
+        "(verify-vh understands evidence seals, reconciliation seals, dataset attestations, and proof bundles)"
+    );
+  }
+
+  // Re-derive the root from the referenced bytes per the (underlying) kind.
+  let fileResult;
+  if (payloadKind === KINDS.EVIDENCE_SEAL) {
+    fileResult = verifyEvidenceSealWith(payload, readEntry);
+  } else if (payloadKind === KINDS.TRUST_SEAL) {
+    fileResult = verifyTrustSealWith(payload, readEntry);
+  } else if (payloadKind === KINDS.DATASET_ATTESTATION) {
+    fileResult = verifyDatasetAttestation(payload);
+  } else if (payloadKind === KINDS.PROOF) {
+    fileResult = verifyProofBundle(payload);
+  } else {
+    throw new UsageError(
+      `unrecognized embedded artifact kind: ${JSON.stringify(payloadKind)}`
+    );
+  }
+
+  // --- Decide the verdict + the deterministic reason. ---
+  // Precedence: a structural file tamper (CHANGED/MISSING/root mismatch) is a clean REJECTED. For a
+  // SIGNED artifact, a broken signature is `bad_signature`; a recovered signer that does not equal the
+  // pinned --vendor is `wrong_issuer`. Both are clean REJECTED verdicts (exit 3), never a crash.
+  let reason = "OK";
+  let accepted = true;
+
+  const escaped = fileResult.escaped || [];
+  if (!fileResult.filesOk) {
+    accepted = false;
+    // path_escape DOMINATES: an artifact that tries to read outside its source is malicious by
+    // construction (the threat model is a hostile producer probing the counterparty's filesystem), so it
+    // is reported FIRST — never as a benign CHANGED/MISSING, and never with a leaked out-of-tree content
+    // hash.
+    if (escaped.length > 0) reason = "path_escape";
+    else if (fileResult.changed.length > 0) reason = "CHANGED";
+    else if (fileResult.missing.length > 0) reason = "MISSING";
+    else if (fileResult.unexpected.length > 0) reason = "UNEXPECTED";
+    else reason = "root_mismatch";
+  }
+
+  // Signature checks (only for signed artifacts). A bad signature dominates the "issuer" check (you
+  // cannot trust an issuer you cannot recover).
+  let signerMatchesVendor = null;
+  if (signed) {
+    if (!signatureOk) {
+      accepted = false;
+      // bad_signature is the dominant reason ONLY if files were otherwise OK; if a file also changed we
+      // still surface bad_signature because the signature is the trust root of a signed artifact.
+      reason = "bad_signature";
+    } else if (pinned != null) {
+      signerMatchesVendor = recoveredSigner === pinned;
+      if (!signerMatchesVendor) {
+        accepted = false;
+        // wrong_issuer only when the signature itself is sound but the signer is not the pinned vendor.
+        if (fileResult.filesOk) reason = "wrong_issuer";
+        else if (reason === "OK") reason = "wrong_issuer";
+      }
+    }
+  } else if (pinned != null) {
+    // A --vendor pin on an UNSIGNED artifact cannot be satisfied (there is no signer to recover); this is
+    // a clean REJECTED wrong_issuer-style verdict so a CI gate expecting a signed-by-vendor artifact fails.
+    accepted = false;
+    reason = "unsigned_cannot_pin_vendor";
+  }
+
+  const verdict = accepted ? "OK" : "REJECTED";
+  const code = accepted ? EXIT.OK : EXIT.REJECTED;
+
+  const result = {
+    artifact,
+    kind,
+    payloadKind,
+    signed,
+    verdict,
+    reason,
+    accepted,
+    recoveredSigner,
+    claimedSigner,
+    pinnedVendor: pinned,
+    signatureOk,
+    signerMatchesVendor,
+    sealedRoot: fileResult.sealedRoot,
+    recomputedRoot: fileResult.recomputedRoot,
+    rootMatches: fileResult.rootMatches,
+    counts: {
+      matched: fileResult.matched.length,
+      changed: fileResult.changed.length,
+      missing: fileResult.missing.length,
+      escaped: escaped.length,
+      unexpected: fileResult.unexpected.length,
+    },
+    matched: fileResult.matched,
+    changed: fileResult.changed,
+    missing: fileResult.missing,
+    escaped,
+    unexpected: fileResult.unexpected,
+    note: TRUST_NOTE,
+  };
+  if (fileResult.identityOnly) result.identityOnly = true;
+  if (fileResult.proof) result.proof = fileResult.proof;
+
+  return { result, code };
+}
+
+// ---------------------------------------------------------------------------
+// The PURE revocation fold for the bytes path. Semantically identical to revocation.loadAndApply (the
+// disk integration) once the entries are in hand: resolve the as-of instant (defaulting to nowISO),
+// normalize the caller-supplied revocations input (a JSON string, a container object, or an array of
+// either), fold the decision onto the result, and recompute the exit code. Uses ONLY the pure decision
+// functions (./lib/revocation-core.js via the revocation re-exports) — never the fs-backed reader.
+// ---------------------------------------------------------------------------
+
+function applyRevocationsDecision(result, revocationsInput, asOf, nowISO) {
+  const resolved = revocation.resolveAsOf(asOf, nowISO);
+  const entries = revocation.normalizeRevocationsInput(revocationsInput);
+  const downgraded = revocation.applyToVerifyResult({ result, revocations: entries, asOf: resolved.asOf });
+  downgraded.trustAsOfDefaulted = resolved.defaulted;
+  return { result: downgraded, code: downgraded.accepted ? EXIT.OK : EXIT.REJECTED };
+}
+
+// ---------------------------------------------------------------------------
+// THE IN-MEMORY FILE SOURCE + BYTES ENTRYPOINT (T-66.1).
+//
+// `verifyArtifactFromBytes({ artifactText, files, vendor, revocationsText, asOf, nowISO, artifactName })`
+// drives the EXACT engine above over caller-supplied bytes:
+//   * `artifactText` — the artifact JSON as a STRING (what a browser read out of a dropped file);
+//   * `files`        — a plain `{ relPath: Uint8Array|Buffer }` map of the packet's referenced bytes;
+//   * `vendor`       — optional 0x-address pin (same semantics as `--vendor`);
+//   * `revocationsText` — optional revocations input (JSON text / container / array; same semantics as
+//     the CONTENT of a `--revocations` file), with optional `asOf` (canonical ISO instant) + `nowISO`;
+//   * `artifactName` — optional label used verbatim as `result.artifact` (defaults below).
+//
+// CONTRACT — NEVER THROWS. Hostile input (non-JSON artifact text, an oversized / absolute / `..` map
+// key, a non-bytes map value, a malformed vendor or asOf) is NAMED-rejected: the return value is
+//   { ok, code, result, error }
+// where a computed verdict carries `result` (the SAME structured shape `verifyArtifact` returns — the
+// two are DEEP-EQUAL on identical inputs) + `error: null`, and an input problem carries `result: null` +
+// `error: { name: "UsageError"|"IOError", code, message }` with the exact defect named. The verdict
+// classes (missing / extra / content-mismatch / wrong-vendor / tampered-signature / path_escape /
+// revoked) derive from the MAP exactly as the disk path derives them from the directory.
+// ---------------------------------------------------------------------------
+
+// The largest relPath key the in-memory map accepts. Sealed relPaths are short; a multi-kilobyte "key"
+// is hostile input (an attempted resource-exhaustion / log-flooding vector), rejected by NAME up front.
+const MAX_RELPATH_CHARS = 4096;
+
+// PURE string-level confinement for an in-memory relPath — the map-source mirror of the disk source's
+// string checks (absolute anywhere, or any `..` traversal component, is hostile). Windows-style drive
+// and UNC prefixes are treated as absolute here too: an in-memory map NEVER has a legitimate absolute
+// key, whatever platform authored the artifact.
+function isTraversalOrAbsoluteRelPath(relPath) {
+  if (typeof relPath !== "string" || relPath.length === 0) return true;
+  if (relPath.charAt(0) === "/" || relPath.charAt(0) === "\\") return true;
+  if (/^[A-Za-z]:[\\/]/.test(relPath)) return true;
+  if (relPath.split(/[\\/]/).includes("..")) return true;
+  return false;
+}
+
+// Validate the caller's `{ relPath: bytes }` map SHAPE up front so a hostile map is NAMED-rejected
+// before any verification work (and before any key is dereferenced). Throws UsageError; the entrypoint
+// converts that into the structured `{ error }` return — never an uncaught throw.
+function validateFilesMap(files) {
+  if (files == null || typeof files !== "object" || Array.isArray(files)) {
+    throw new UsageError(
+      "verifyArtifactFromBytes requires `files` as a plain { relPath: Uint8Array|Buffer } object map"
+    );
+  }
+  for (const key of Object.keys(files)) {
+    if (key.length === 0) {
+      throw new UsageError("files map contains an empty relPath key");
+    }
+    if (key.length > MAX_RELPATH_CHARS) {
+      throw new UsageError(
+        `files map key exceeds ${MAX_RELPATH_CHARS} characters (oversized relPath, starts: ` +
+          `${JSON.stringify(key.slice(0, 64))})`
+      );
+    }
+    if (isTraversalOrAbsoluteRelPath(key)) {
+      throw new UsageError(
+        `files map key is not a confined relative path: ${JSON.stringify(key.slice(0, 256))}`
+      );
+    }
+    const v = files[key];
+    if (!(v instanceof Uint8Array)) {
+      throw new UsageError(
+        `files map value for ${JSON.stringify(key.slice(0, 256))} must be a Uint8Array/Buffer of the file's bytes`
+      );
+    }
+  }
+}
+
+// The in-memory `readEntry` source over an (already-validated) map: a hostile relPath from the ARTIFACT
+// is `escaped` (the same string-level rules as the disk source — so absolute/`..` seal entries produce
+// the identical path_escape verdict), an absent key is `missing`, and a present key answers its bytes.
+// Lookups use an own-property check so `__proto__`/`constructor` style keys can never smuggle
+// prototype-chain values in as file bytes.
+function makeMapReadEntry(files) {
+  return function readEntry(relPath) {
+    if (isTraversalOrAbsoluteRelPath(relPath)) return { status: "escaped" };
+    if (!Object.prototype.hasOwnProperty.call(files, relPath)) return { status: "missing" };
+    return { status: "ok", bytes: files[relPath] };
+  };
+}
+
+function verifyArtifactFromBytes(params) {
+  try {
+    if (params == null || typeof params !== "object" || Array.isArray(params)) {
+      throw new UsageError(
+        "verifyArtifactFromBytes requires a params object: " +
+          "{ artifactText, files, vendor?, revocationsText?, asOf?, nowISO?, artifactName? }"
+      );
+    }
+    const { artifactText, files, vendor, revocationsText, asOf, nowISO, artifactName } = params;
+    if (typeof artifactText !== "string") {
+      throw new UsageError("verifyArtifactFromBytes requires `artifactText` (the artifact JSON as a string)");
+    }
+    validateFilesMap(files);
+
+    // Mirror the CLI's flag-shape gate (parseArgs): asOf only means something alongside revocations, and
+    // must be a canonical ISO-8601 UTC instant — a malformed one is a NAMED usage rejection up front,
+    // never a mid-verify throw.
+    if (asOf !== undefined && asOf !== null && (revocationsText === undefined || revocationsText === null)) {
+      throw new UsageError(
+        "asOf requires revocationsText (it pins the instant the revocation decision is made AS OF)"
+      );
+    }
+    if (asOf !== undefined && asOf !== null) {
+      const ms = Date.parse(asOf);
+      if (
+        typeof asOf !== "string" ||
+        !revocation.ISO_INSTANT_RE.test(asOf) ||
+        Number.isNaN(ms) ||
+        new Date(ms).toISOString() !== asOf
+      ) {
+        throw new UsageError(
+          `invalid asOf: ${String(asOf)} (expected a canonical ISO-8601 UTC instant, e.g. 2026-06-01T00:00:00.000Z)`
+        );
+      }
+    }
+
+    const label = artifactName != null ? String(artifactName) : "(in-memory artifact)";
+    let obj;
+    try {
+      obj = JSON.parse(artifactText);
+    } catch (e) {
+      throw new IOError(`artifact ${label} is not valid JSON: ${e.message}`);
+    }
+    if (obj == null || typeof obj !== "object" || Array.isArray(obj)) {
+      throw new IOError(`artifact ${label} must be a JSON object`);
+    }
+
+    const { result, code } = verifyParsedArtifact({
+      artifact: label,
+      obj,
+      vendor,
+      readEntry: makeMapReadEntry(files),
+    });
+
+    // OPTIONAL recipient-side TRUST-DECISION-AS-OF, from caller-supplied revocations INPUT (never a
+    // filesystem read). Same downgrade math as the disk path's revocation.loadAndApply, so the two
+    // paths' results stay deep-equal on identical inputs.
+    if (revocationsText !== undefined && revocationsText !== null) {
+      let applied;
+      try {
+        applied = applyRevocationsDecision(result, revocationsText, asOf, nowISO || new Date().toISOString());
+      } catch (e) {
+        // A non-JSON / wrong-shape revocations input is the bytes-path analogue of an unreadable
+        // --revocations file: a NAMED IO-class rejection, never a silently-skipped downgrade.
+        throw new IOError(`cannot evaluate revocations: ${e.message}`);
+      }
+      return { ok: applied.result.accepted, code: applied.code, result: applied.result, error: null };
+    }
+
+    return { ok: result.accepted, code, result, error: null };
+  } catch (e) {
+    const isUsage = e instanceof UsageError;
+    const code = isUsage ? EXIT.USAGE : EXIT.IO;
+    return {
+      ok: false,
+      code,
+      result: null,
+      error: {
+        name: isUsage ? "UsageError" : "IOError",
+        code,
+        message: String(e && e.message ? e.message : e),
+      },
+    };
+  }
+}
+
+// ============================= END VERIFY-VH PURE ENGINE (T-66.1) =============================
+
+// ---------------------------------------------------------------------------
+// Argument parsing.
+//   SINGLE-ARTIFACT (the original, byte-for-byte unchanged contract):
+//     verify-vh <artifact> [--vendor <0xaddr>] [--dir <d>] [--json]
+//   BATCH/MANIFEST (T-33.1 — one invocation gates EVERY release artifact, one CI exit code):
+//     verify-vh <artifact> <artifact> ... [--vendor <0xaddr>] [--dir <d>] [--json]
+//     verify-vh --manifest <file> [--vendor <0xaddr>] [--dir <d>] [--json]
+// Batch mode is a pure SUPERSET: it engages ONLY when more than one positional <artifact> is given OR
+// `--manifest <file>` is supplied. A lone positional with no --manifest takes the identical single path,
+// so existing callers/tests never shift. A top-level `--vendor`/`--dir` is a DEFAULT each entry inherits
+// unless the entry (a manifest line) overrides it with its own per-entry `--vendor`/`--dir`.
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const opts = {
+    artifact: undefined,
+    vendor: undefined,
+    dir: undefined,
+    json: false,
+    help: false,
+    manifest: undefined,
+    revocations: undefined,
+    asOf: undefined,
+    _pos: [],
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const need = (flag) => {
+      const v = argv[++i];
+      if (v === undefined) throw new UsageError(`${flag} requires a value`);
+      return v;
+    };
+    switch (a) {
+      case "--vendor":
+        opts.vendor = need("--vendor");
+        break;
+      case "--dir":
+        opts.dir = need("--dir");
+        break;
+      case "--manifest":
+        opts.manifest = need("--manifest");
+        break;
+      case "--revocations":
+        opts.revocations = need("--revocations");
+        break;
+      case "--as-of":
+        opts.asOf = need("--as-of");
+        break;
+      case "--json":
+        opts.json = true;
+        break;
+      case "-h":
+      case "--help":
+      case "help":
+        opts.help = true;
+        break;
+      default:
+        if (a && a.startsWith("--")) throw new UsageError(`unknown flag: ${a}`);
+        opts._pos.push(a);
+    }
+  }
+  // batch === any path that aggregates MULTIPLE per-artifact verdicts under ONE exit code:
+  // either a --manifest file, or more than one repeated positional <artifact>.
+  opts.batch = opts.manifest !== undefined || opts._pos.length > 1;
+  if (opts.manifest !== undefined && opts._pos.length > 0) {
+    throw new UsageError(
+      `--manifest <file> lists the artifacts; do not also pass positional <artifact> args (got: ${opts._pos[0]})`
+    );
+  }
+  // Validate the OPTIONAL recipient-side trust-decision flags (--revocations / --as-of, T-51.4) SHAPE up
+  // front so a malformed --as-of (or --as-of without --revocations) is a usage error (2), never a runtime
+  // throw mid-verify. Mirrors `vh evidence verify-signed`'s validateAsOfFlags so the two stacks reject the
+  // same inputs the same way.
+  if (opts.asOf !== undefined && !opts.revocations) {
+    throw new UsageError(
+      "--as-of requires --revocations (it pins the instant the revocation decision is made AS OF)"
+    );
+  }
+  if (opts.asOf !== undefined) {
+    const ms = Date.parse(opts.asOf);
+    if (
+      typeof opts.asOf !== "string" ||
+      !revocation.ISO_INSTANT_RE.test(opts.asOf) ||
+      Number.isNaN(ms) ||
+      new Date(ms).toISOString() !== opts.asOf
+    ) {
+      throw new UsageError(
+        `invalid --as-of: ${opts.asOf} (expected a canonical ISO-8601 UTC instant, e.g. 2026-06-01T00:00:00.000Z)`
+      );
+    }
+  }
+  // Preserve the SINGLE-artifact contract verbatim: exactly one positional and no --manifest.
+  opts.artifact = opts._pos[0];
+  return opts;
+}
+
+// ---------------------------------------------------------------------------
+// Manifest parsing. A manifest is a newline list OR a JSON array of artifact entries; each entry names an
+// artifact path and may carry a per-entry `--vendor`/`--dir` that overrides the top-level defaults.
+//
+//   NEWLINE form — one entry per line, shell-style tokens. Blank lines and `#` comments are skipped:
+//       releases/a.vhevidence.json
+//       releases/b.vhseal --vendor 0xabc... --dir ./out
+//   JSON form — an array of strings and/or objects:
+//       ["a.vhevidence.json", {"artifact":"b.vhseal","vendor":"0xabc...","dir":"./out"}]
+//
+// Paths in the manifest resolve relative to the MANIFEST FILE's own directory (a release ships its
+// manifest next to its artifacts), unless the path is given a per-entry `--dir` for its SIBLINGS — note
+// `dir` localizes where an artifact's SIBLING files are read, exactly as the single-artifact `--dir` does;
+// the artifact path itself resolves against the manifest dir. The manifest is parsed in-process; NO new
+// crypto and NO network — it is a list, nothing more.
+// ---------------------------------------------------------------------------
+
+// Minimal whitespace tokenizer for a newline-form manifest line. No quoting support is needed (artifact
+// paths and 0x addresses contain no spaces); a token is any run of non-whitespace.
+function tokenizeManifestLine(line) {
+  return line.split(/\s+/).filter((t) => t.length > 0);
+}
+
+function parseManifestLine(line, lineNo) {
+  const toks = tokenizeManifestLine(line);
+  const entry = { artifact: undefined, vendor: undefined, dir: undefined };
+  for (let i = 0; i < toks.length; i++) {
+    const t = toks[i];
+    const need = (flag) => {
+      const v = toks[++i];
+      if (v === undefined) throw new UsageError(`manifest line ${lineNo}: ${flag} requires a value`);
+      return v;
+    };
+    if (t === "--vendor") entry.vendor = need("--vendor");
+    else if (t === "--dir") entry.dir = need("--dir");
+    else if (t.startsWith("--")) throw new UsageError(`manifest line ${lineNo}: unknown flag: ${t}`);
+    else if (entry.artifact === undefined) entry.artifact = t;
+    else throw new UsageError(`manifest line ${lineNo}: unexpected extra token: ${t}`);
+  }
+  if (entry.artifact === undefined) {
+    throw new UsageError(`manifest line ${lineNo}: no artifact path`);
+  }
+  return entry;
+}
+
+function parseManifest(text, manifestPath) {
+  const trimmed = text.replace(/^/, "").trim();
+  const entries = [];
+  if (trimmed.startsWith("[")) {
+    // JSON array form.
+    let arr;
+    try {
+      arr = JSON.parse(trimmed);
+    } catch (e) {
+      throw new IOError(`manifest ${manifestPath} is not valid JSON: ${e.message}`);
+    }
+    if (!Array.isArray(arr)) throw new IOError(`manifest ${manifestPath} JSON must be an array of entries`);
+    arr.forEach((raw, idx) => {
+      if (typeof raw === "string") {
+        entries.push({ artifact: raw, vendor: undefined, dir: undefined });
+      } else if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        if (typeof raw.artifact !== "string" || raw.artifact.length === 0) {
+          throw new IOError(`manifest ${manifestPath} entry ${idx}: "artifact" must be a non-empty string`);
+        }
+        entries.push({
+          artifact: raw.artifact,
+          vendor: raw.vendor != null ? String(raw.vendor) : undefined,
+          dir: raw.dir != null ? String(raw.dir) : undefined,
+        });
+      } else {
+        throw new IOError(`manifest ${manifestPath} entry ${idx} must be a string or { artifact, vendor?, dir? }`);
+      }
+    });
+  } else {
+    // Newline form: one entry per non-blank, non-comment line.
+    const lines = trimmed.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const bare = line.trim();
+      if (bare.length === 0 || bare.startsWith("#")) continue;
+      entries.push(parseManifestLine(line, i + 1));
+    }
+  }
+  if (entries.length === 0) {
+    throw new UsageError(`manifest ${manifestPath} lists no artifacts`);
+  }
+  return entries;
+}
+
+// ---------------------------------------------------------------------------
+// THE DISK FILE SOURCE — the CLI's `readEntry` implementation, carrying the FULL path-confinement
+// discipline the disk path always had (byte-identical classification):
+//   (1) string-level confinement, BEFORE any filesystem access: an ABSOLUTE relPath, or any relPath with
+//       a `..` path COMPONENT, is REJECTED unread;
+//   (2) resolved-path confinement: a resolved path that ESCAPES baseDir (string-wise, against the
+//       realpath of baseDir) is REJECTED;
+//   (3) post-open symlink confinement: after opening a present file we realpath it and re-assert
+//       containment, defeating a sibling that is a SYMLINK pointing out of baseDir (fs.readFileSync
+//       follows symlinks regardless of the string check) — the just-read bytes are DROPPED, never hashed.
+// ---------------------------------------------------------------------------
+
+// True when a resolved absolute path escapes the (already realpath'd) base directory. A path equal to the
+// base or under it does not escape; anything that path.relative()'s to "" / ".." / an absolute drive is out.
+function escapesBase(baseReal, abs) {
+  const rel = path.relative(baseReal, abs);
+  return rel === ".." || rel.startsWith(".." + path.sep) || path.isAbsolute(rel);
+}
+
+function makeDiskReadEntry(baseDir) {
+  // Anchor confinement on the REALPATH of baseDir so a symlinked baseDir itself (e.g. /tmp -> /private/tmp
+  // on macOS) does not spuriously trip the containment check on otherwise-legitimate siblings.
+  let baseReal;
+  try {
+    baseReal = fs.realpathSync(baseDir);
+  } catch (_) {
+    baseReal = path.resolve(baseDir);
+  }
+
+  return function readEntry(relPath) {
+    // (1) String-level confinement, BEFORE any filesystem access.
+    if (
+      typeof relPath !== "string" ||
+      relPath.length === 0 ||
+      path.isAbsolute(relPath) ||
+      relPath.split(/[\\/]/).includes("..")
+    ) {
+      return { status: "escaped" };
+    }
+
+    // (2) Resolved-path confinement: the resolved absolute path must stay under baseReal.
+    const abs = path.resolve(baseDir, relPath);
+    if (escapesBase(baseReal, abs)) {
+      return { status: "escaped" };
+    }
+
+    let bytes;
+    try {
+      bytes = fs.readFileSync(abs);
+    } catch (_) {
+      return { status: "missing" };
+    }
+
+    // (3) Post-open symlink confinement.
+    let real;
+    try {
+      real = fs.realpathSync(abs);
+    } catch (_) {
+      real = abs;
+    }
+    if (escapesBase(baseReal, real)) {
+      return { status: "escaped" };
+    }
+
+    return { status: "ok", bytes };
+  };
+}
+
+// The original disk-shaped helpers, kept with their exact signatures + behavior (thin wrappers over the
+// engine with a disk source). `relResolver` was always accepted-and-unused on classifyFiles; retained so
+// the signature does not shift.
+function classifyFiles(sealedEntries, baseDir, relResolver) { // eslint-disable-line no-unused-vars
+  return classifyFilesWith(sealedEntries, makeDiskReadEntry(baseDir));
+}
+
+function verifyEvidenceSeal(seal, baseDir) {
+  return verifyEvidenceSealWith(seal, makeDiskReadEntry(baseDir));
+}
+
+function verifyTrustSeal(seal, baseDir) {
+  return verifyTrustSealWith(seal, makeDiskReadEntry(baseDir));
+}
+
+// ---------------------------------------------------------------------------
+// The DISK verify entrypoint — the original CLI contract, byte-identical: reads + JSON-parses the
+// artifact, then drives the SAME pure engine with the disk file source. Returns { result, code }.
+// ---------------------------------------------------------------------------
+
+function verifyArtifact(opts) {
+  if (!opts.artifact) throw new UsageError("verify-vh requires an <artifact>");
+
+  const artifactPath = path.resolve(opts.artifact);
+  let text;
+  try {
+    text = fs.readFileSync(artifactPath, "utf8");
+  } catch (e) {
+    throw new IOError(`cannot read artifact ${opts.artifact}: ${e.message}`);
+  }
+  let obj;
+  try {
+    obj = JSON.parse(text);
+  } catch (e) {
+    throw new IOError(`artifact ${opts.artifact} is not valid JSON: ${e.message}`);
+  }
+  if (obj == null || typeof obj !== "object" || Array.isArray(obj)) {
+    throw new IOError(`artifact ${opts.artifact} must be a JSON object`);
+  }
+
+  // The base directory siblings resolve against: --dir override else the artifact's own directory.
+  const baseDir = opts.dir != null ? path.resolve(opts.dir) : path.dirname(artifactPath);
+
+  const { result, code } = verifyParsedArtifact({
+    artifact: opts.artifact,
+    obj,
+    vendor: opts.vendor,
+    readEntry: makeDiskReadEntry(baseDir),
+  });
+
+  // OPTIONAL recipient-side TRUST-DECISION-AS-OF (EPIC-51 / T-51.4). Runs ONLY under --revocations — with no
+  // flag the result + code are byte-identical to the pre-T-51.4 baseline (regression-pinned). A signer
+  // revoked-before-as-of downgrades an otherwise-ACCEPTED artifact to REVOKED (exit 3); a later-dated
+  // revocation is informational; a forged/tampered/third-party one is ignored with a warning. OFFLINE /
+  // key-free on the read side; the revocations file/dir is the ONLY new I/O. This reaches the SAME downgrade
+  // `vh ... verify-signed --revocations` does, byte-for-byte on identical inputs.
+  if (opts.revocations) {
+    let applied;
+    try {
+      applied = revocation.loadAndApply({
+        result,
+        revocationsPath: opts.revocations,
+        asOf: opts.asOf,
+        nowISO: opts.nowISO || new Date().toISOString(),
+      });
+    } catch (e) {
+      // A malformed --as-of is caught at parse time; here the only failures are an unreadable path or a
+      // non-JSON single revocations file — a genuine IO error (exit 1), surfaced (never a stack), never a
+      // silently-skipped downgrade.
+      throw new IOError(`cannot evaluate --revocations ${opts.revocations}: ${e.message}`);
+    }
+    // A REVOKED decision flips an otherwise-ACCEPTED verdict to REVOKED (exit 3); an already-REJECTED verdict
+    // is left rejected (the trust-as-of never upgrades). The trustAsOf block + defaulted flag ride along for
+    // the renderer.
+    const downgraded = applied.result;
+    downgraded.trustAsOfDefaulted = applied.defaulted;
+    const newCode = downgraded.accepted ? EXIT.OK : EXIT.REJECTED;
+    return { result: downgraded, code: newCode };
+  }
+
+  return { result, code };
+}
+
+// ---------------------------------------------------------------------------
+// BATCH / MANIFEST orchestration (T-33.1). One invocation gates EVERY artifact a release produces and
+// returns ONE CI exit code. Each entry is verified READ-ONLY through the SAME `verifyArtifact` core (NO
+// new crypto, NO new artifact kind, path-escape/no-network guarantees preserved per entry); the per-entry
+// `--json` body is the IDENTICAL single-artifact shape, so there is no divergence to drift.
+//
+// AGGREGATE EXIT CONTRACT:
+//   * exit 0 (OK)        — and only if — EVERY artifact verifies (each accepted).
+//   * exit 3 (REJECTED)  — if ANY artifact is rejected (CHANGED/MISSING/bad_signature/wrong_issuer/…);
+//                          the report names WHICH artifact failed and why.
+//   * exit 2 (USAGE)     — a malformed flag / per-entry --vendor (raised before any verify runs).
+//   * exit 1 (IO)        — an artifact (or the manifest itself) is unreadable / not the expected shape.
+// Usage/IO are evaluated PER ENTRY and SHORT-CIRCUIT the whole run with the matching code, exactly as the
+// single-artifact path does — a release gate must not "pass" while one of its artifacts could not even be
+// read or parsed. The IO/USAGE code wins over a REJECTED tally (you cannot certify a batch you could not
+// fully evaluate).
+// ---------------------------------------------------------------------------
+
+function buildBatchEntries(opts) {
+  // Returns [{ artifact, vendor, dir }] with top-level --vendor/--dir applied as DEFAULTS each entry may
+  // override. Artifact paths from a manifest resolve against the manifest file's own directory.
+  if (opts.manifest !== undefined) {
+    const manifestPath = path.resolve(opts.manifest);
+    let text;
+    try {
+      text = fs.readFileSync(manifestPath, "utf8");
+    } catch (e) {
+      throw new IOError(`cannot read manifest ${opts.manifest}: ${e.message}`);
+    }
+    const manifestDir = path.dirname(manifestPath);
+    return parseManifest(text, opts.manifest).map((e) => ({
+      // The artifact path resolves relative to the manifest's directory (a release ships them together).
+      artifact: path.resolve(manifestDir, e.artifact),
+      // Per-entry --vendor/--dir override the top-level defaults; a --dir resolves against the manifest dir.
+      vendor: e.vendor != null ? e.vendor : opts.vendor,
+      dir: e.dir != null ? path.resolve(manifestDir, e.dir) : opts.dir,
+    }));
+  }
+  // Repeated positional <artifact> args: each inherits the (single) top-level --vendor/--dir.
+  return opts._pos.map((a) => ({ artifact: a, vendor: opts.vendor, dir: opts.dir }));
+}
+
+function verifyBatch(opts) {
+  const entries = buildBatchEntries(opts);
+  const results = [];
+  for (const e of entries) {
+    // Verify each entry through the SAME core. A USAGE/IO problem with any single entry short-circuits the
+    // whole batch with that code (the gate cannot certify a release it could not fully evaluate). The
+    // top-level --revocations/--as-of (T-51.4) apply to EVERY entry as a default, so one revocations
+    // file/dir gates a whole release's signed artifacts under one as-of instant.
+    const { result } = verifyArtifact({
+      artifact: e.artifact,
+      vendor: e.vendor,
+      dir: e.dir,
+      revocations: opts.revocations,
+      asOf: opts.asOf,
+      nowISO: opts.nowISO,
+    });
+    results.push(result);
+  }
+  const total = results.length;
+  const passed = results.filter((r) => r.accepted).length;
+  const failed = total - passed;
+  const ok = failed === 0;
+  const aggregate = { ok, total, passed, failed, results };
+  return { aggregate, code: ok ? EXIT.OK : EXIT.REJECTED };
+}
+
+// ---------------------------------------------------------------------------
+// Human + JSON rendering.
+// ---------------------------------------------------------------------------
+
+function renderHuman(r) {
+  const L = [];
+  L.push(TRUST_NOTE);
+  L.push("");
+  L.push(`# verify-vh — ${r.artifact}`);
+  L.push(`kind:            ${r.kind}`);
+  if (r.payloadKind !== r.kind) L.push(`embedded kind:   ${r.payloadKind}`);
+  L.push(`signed:          ${r.signed ? "yes" : "no"}`);
+  if (r.signed) {
+    L.push(`recovered signer:${r.recoveredSigner ? " " + r.recoveredSigner : " (unrecoverable)"}`);
+    L.push(`claimed signer:  ${r.claimedSigner}`);
+    if (r.pinnedVendor != null) {
+      L.push(`pinned --vendor: ${r.pinnedVendor}`);
+      L.push(`signer matches vendor: ${r.signerMatchesVendor ? "yes" : "NO"}`);
+    } else {
+      L.push("(no --vendor pin: the recovered signer above is reported, not pinned)");
+    }
+  } else if (r.recoveredSigner == null && r.pinnedVendor != null) {
+    L.push("note: --vendor was supplied but this artifact is UNSIGNED (no signer to pin)");
+  }
+  if (r.sealedRoot != null) L.push(`sealed root:     ${r.sealedRoot}`);
+  if (r.recomputedRoot != null) L.push(`recomputed root: ${r.recomputedRoot}`);
+  if (r.rootMatches != null) L.push(`root matches:    ${r.rootMatches ? "yes" : "NO"}`);
+  if (r.identityOnly) {
+    L.push("(identity-only artifact: it commits to a dataset root/digest, not a re-walkable file set)");
+  }
+  L.push(
+    `files: ${r.counts.matched} matched, ${r.counts.changed} changed, ` +
+      `${r.counts.missing} missing, ${r.counts.escaped || 0} rejected, ${r.counts.unexpected} unexpected`
+  );
+  // AGENT-SESSION packet block (T-68.3) — present ONLY for r.agent results, so every other kind's
+  // output stays byte-identical.
+  if (r.agent) {
+    L.push(`declared head:   { size: ${r.agent.head.size}, root: ${r.agent.head.root} }`);
+    if (r.agent.counts) {
+      L.push(
+        `events:          ${r.agent.counts.events} (${r.agent.counts.full} full, ${r.agent.counts.redacted} redacted)`
+      );
+      L.push(
+        `withheld seqs:   ${r.agent.withheld.length === 0 ? "(none — every payload disclosed)" : r.agent.withheld.join(", ")}`
+      );
+    }
+  }
+  // OPTIONAL recipient-side TRUST-DECISION-AS-OF block (T-51.4) — printed ONLY when --revocations was
+  // supplied (r.trustAsOf is attached then). With no flag this block is absent, so the output is byte-
+  // identical to the pre-T-51.4 baseline. The block reads the SAME way the producer's verify-signed does.
+  if (r.trustAsOf) {
+    L.push("");
+    for (const line of revocation.renderTrustAsOf(r.trustAsOf, { defaulted: r.trustAsOfDefaulted })) {
+      L.push(line);
+    }
+  }
+  L.push("");
+  if (r.accepted) {
+    L.push("OK — the artifact verifies.");
+  } else if (r.reason === "key_revoked_as_of") {
+    // The signature + bytes checked out, but the signing key was revoked AT OR BEFORE the as-of instant — a
+    // distinct REVOKED verdict (exit 3), matching the producer's verify-signed downgrade.
+    const g = r.trustAsOf && r.trustAsOf.governing;
+    L.push("REVOKED (key_revoked_as_of):");
+    if (g) {
+      L.push(
+        `  key_revoked_as_of: the signing key (${g.vendorAddress}) was REVOKED as of ${g.revokedAt} ` +
+          `(reason: ${g.reason})${g.supersededBy ? `, superseded by ${g.supersededBy}` : ""} — at or before ` +
+          `the as-of instant. The bytes + signature check out, but the key was no longer trustworthy then.`
+      );
+    }
+  } else {
+    L.push(`REJECTED (${r.reason}):`);
+    for (const c of r.changed) {
+      L.push(`  CHANGED    ${c.relPath}: sealed ${c.expectedContentHash} != on-disk ${c.actualContentHash}`);
+    }
+    for (const m of r.missing) {
+      L.push(`  MISSING    ${m.relPath}: referenced but not found on disk`);
+    }
+    for (const x of r.escaped || []) {
+      // SECURITY: print the attacker's relPath string ONLY — never a content hash of the out-of-tree target.
+      L.push(`  REJECTED   ${x.relPath}: path escapes the artifact directory (refused to read; no hash computed)`);
+    }
+    for (const u of r.unexpected) {
+      L.push(`  UNEXPECTED ${u.relPath}: on disk but not referenced`);
+    }
+    if (r.reason === "bad_signature") {
+      L.push("  bad_signature: the signature does not recover to the claimed signer (tampered or forged).");
+    }
+    if (r.reason === "wrong_issuer") {
+      L.push(
+        `  wrong_issuer: recovered ${r.recoveredSigner} but you pinned --vendor ${r.pinnedVendor}.`
+      );
+    }
+    if (r.reason === "unsigned_cannot_pin_vendor") {
+      L.push("  --vendor was pinned but the artifact carries no signature to recover a signer from.");
+    }
+    if (r.reason === "root_mismatch") {
+      L.push("  root_mismatch: the recomputed root does not equal the sealed root.");
+    }
+    if (r.reason === "path_escape") {
+      L.push(
+        "  path_escape: the artifact references a file OUTSIDE its own directory (absolute path, `..` " +
+          "traversal, or an out-of-tree symlink). A genuine artifact never does this; refused to read it."
+      );
+    }
+    // AGENT-SESSION packet reject details (T-68.3): name the first offending event seq + the named fault.
+    if (r.agent) {
+      if (r.agent.seq !== null && r.agent.seq !== undefined) {
+        L.push(`  first offending event seq: ${r.agent.seq}${r.agent.reason ? ` (${r.agent.reason})` : ""}`);
+      }
+      if (r.reason === "event_invalid") {
+        L.push(
+          `  event_invalid: an event failed strict canonical validation` +
+            `${r.agent.field ? ` (field: ${r.agent.field})` : ""} — the packet cannot be trusted.`
+        );
+      }
+      if (r.reason === "counts_mismatch") {
+        L.push("  counts_mismatch: the packet's declared full/redacted counts do not match a recount.");
+      }
+      if (r.reason === "head_not_bound") {
+        L.push(
+          "  head_not_bound: the headAttestation signs a DIFFERENT { size, root } than this packet's " +
+            "events derive — the signature belongs to another session."
+        );
+      }
+    }
+  }
+  L.push("");
+  return L.join("\n");
+}
+
+// Human rendering of a batch aggregate: a per-artifact PASS/FAIL line (FAIL names the reason), then the
+// one-line roll-up + the final verdict. The trust note is printed ONCE at the top.
+function renderBatchHuman(agg) {
+  const L = [];
+  L.push(TRUST_NOTE);
+  L.push("");
+  L.push(`# verify-vh — BATCH (${agg.total} artifact${agg.total === 1 ? "" : "s"})`);
+  for (const r of agg.results) {
+    if (r.accepted) {
+      L.push(`  PASS  ${r.artifact}`);
+    } else {
+      L.push(`  FAIL  ${r.artifact}  (${r.reason})`);
+      // Localize the first failing detail so a CI log names exactly what moved, per artifact.
+      for (const c of r.changed) {
+        L.push(`          CHANGED   ${c.relPath}: sealed ${c.expectedContentHash} != on-disk ${c.actualContentHash}`);
+      }
+      for (const m of r.missing) {
+        L.push(`          MISSING   ${m.relPath}`);
+      }
+      for (const x of r.escaped || []) {
+        L.push(`          REJECTED  ${x.relPath}: path escapes the artifact directory (no hash computed)`);
+      }
+    }
+  }
+  L.push("");
+  L.push(`total: ${agg.total}, passed: ${agg.passed}, failed: ${agg.failed}`);
+  L.push(agg.ok ? "OK — every artifact verifies." : `REJECTED — ${agg.failed} artifact(s) failed.`);
+  L.push("");
+  return L.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// `demo` — the ZERO-CONFIG, zero-flag, zero-key-knowledge quickstart (T-55.2).
+//
+// WHY THIS EXISTS
+//   A cold prospect should be able to go from NOTHING to a VERIFIED packet in one command — `verify-vh demo`
+//   (or `npx … demo`) — with NO flags, NO `--vendor` to paste, and NO key knowledge. The whole sales promise
+//   ("don't trust us — verify it yourself, offline") is unfalsifiable until they have RUN the tool once and
+//   watched it ACCEPT a genuine packet, name the signer, then REJECT a one-byte-tampered copy. `demo` IS that
+//   first run: it ships a tiny, self-contained, GENUINELY-SIGNED evidence packet baked into this file, plays
+//   it through the EXACT same `verifyArtifact` core every real verify uses, and prints the honest verdict.
+//
+// HOW IT STAYS HONEST (no special-case verify path)
+//   The fixture below is a REAL `vh.evidence-seal-signed` container: a keccak Merkle seal over two referenced
+//   files, signed with a FIXED, well-known TEST-ONLY key (NEVER a real key, NEVER real funds — its address is
+//   the standard hardhat account #1, published precisely so no one mistakes it for a production signer). The
+//   signature was produced once with the family's real EIP-191 personal-sign path; the demo RECOVERS it with
+//   the SAME vendored secp256k1 recovery a real verify uses, so the signer address printed is genuinely
+//   recovered from the bytes — not echoed. `demo` materializes the packet + its two files into a throwaway
+//   temp dir, runs the real `verifyArtifact` twice (genuine -> ACCEPT pinned to the recovered signer; a
+//   one-byte-tampered copy -> REJECT/CHANGED), then deletes the temp dir. It writes NOTHING under cwd.
+// ---------------------------------------------------------------------------
+
+// The fixed TEST-ONLY signer (hardhat account #1). Published so it can NEVER be confused with a real key.
+const DEMO_SIGNER = "0x70997970c51812dc3a010c7d01b50e0d17dc79c8";
+
+// The two referenced files the demo seal commits to, by relPath -> exact UTF-8 content.
+const DEMO_FILES = Object.freeze({
+  "model-card.md": "# Demo model card\nThis file is sealed by the verify-vh demo.\n",
+  "weights.txt": "0.10 0.20 0.30\n",
+});
+
+// The GENUINELY-SIGNED evidence container. `attestation` is the EXACT bytes the signature is over (the same
+// plain serialization the producer's evidence path emits for the embedded seal); the signature is a real
+// 65-byte EIP-191 personal-sign over those bytes by DEMO_SIGNER. Re-derived from DEMO_FILES (a build-time
+// check would re-seal the same bytes), so the root binds the real file content above.
+const DEMO_CONTAINER = Object.freeze({
+  kind: "vh.evidence-seal-signed",
+  attestation:
+    '{"kind":"vh.evidence-seal","files":[{"relPath":"model-card.md","contentHash":"0x1aeca0ad922f53e9c30186234c5d1a62ffda62a828988bdd266fa93240675db0","leaf":"0xbbb3052a7359188aed3f114e15b721cf5d707a8bdf09109d1d51ec5765b3c58c"},{"relPath":"weights.txt","contentHash":"0x7716d380e062d1daf7ca58897b55f6b58900ed4fd1eda79445956c5c3d336cdf","leaf":"0x34ce488c6fb49a32d356a2553196dc817a439c13a03ce9a2a2ff2710fcf9eea2"}],"root":"0x621a5eb924a9887f88d4b05ccdf19834cdae2f4ed2399921acc7b8a45d48da9b"}',
+  signature: {
+    scheme: "eip191-personal-sign",
+    signer: DEMO_SIGNER,
+    signature:
+      "0x1aabba1530df192e87498bbf1a26f63a7e30d84d72c14bf5d08b2d872df9810b672efcf26f30ec6a38a00ffc158be53633daeff9e99f344b6c1a2e99522d61a01b",
+  },
+});
+
+// The packet filename the demo materializes (shared by the throwaway-temp round-trip and the `demo <dir>`
+// keepable scaffold) so the "NEXT" command the demo prints names the file it actually wrote.
+const DEMO_PACKET_NAME = "demo-packet.vhevidence.json";
+
+// ---------------------------------------------------------------------------
+// The DEMO AGENT-SESSION packet (T-68.3): a small, GENUINE `vh.agent-session-packet` produced by the
+// REAL `vh agent seal` + `vh agent redact` path (never re-authored by hand) — a 4-event session
+// (prompt -> tool_call -> tool_result -> completion) whose tool_call payload (seq 1) is REDACTED
+// behind its hash commitment, so the fixture demonstrates the load-bearing property: a redacted
+// packet STILL VERIFIES (identical leaves + root). UNSIGNED — the whole agent verify surface is the
+// FREE funnel leg. The standalone HTML page inlines these constants verbatim (next to DEMO_FILES /
+// DEMO_CONTAINER above) for its built-in agent demo: click -> ACCEPT; tamper ONE byte of a payload in
+// the page -> REJECT naming event seq DEMO_AGENT_TAMPER_SEQ. The TAMPER_FROM/TO pair is a one-byte
+// substring edit that occurs EXACTLY once in the packet text (pinned by test/verifier.agent.test.js).
+// ---------------------------------------------------------------------------
+const DEMO_AGENT_PACKET_NAME = "demo-session.vhagent.json";
+const DEMO_AGENT_PACKET_TEXT = "{\"kind\":\"vh.agent-session-packet\",\"schemaVersion\":1,\"note\":\"This agent-session packet is TAMPER-EVIDENT + OFFLINE-RECOMPUTABLE, NOT a trusted timestamp and NOT a claim the agent behaved well. Its ordered Merkle `head` {size, root} (RFC-6962-style, position-bound) commits to every event: verify RE-DERIVES each event leaf — recomputing the payload hash commitment for a FULL event, checking the carried commitment for a REDACTED one — and the root from the events you hold, and a REJECT names the first offending event seq. Redaction WITHHOLDS a payload behind its hash commitment without changing any leaf or the root: it can hide, never silently alter. Event `ts` fields are SELF-ASSERTED metadata (recorded, never verified against any clock); \\\"sealed at time T\\\" rides the human-owned signing/timestamp trust-root (STRATEGY.md P-3). Garbage-in is out of scope: the head proves the LOG is intact and append-only, not that the log faithfully records what the agent actually did. The packet is an UNTRUSTED transport container: verify never trusts the packet's own stored hashes.\",\"head\":{\"size\":4,\"root\":\"0xd455ad3f8050f1d863d65003532055326629bf92574cf8919b022222abdf66d1\"},\"counts\":{\"events\":4,\"full\":3,\"redacted\":1},\"events\":[{\"seq\":0,\"ts\":\"2026-07-01T09:00:00.000Z\",\"actor\":\"user\",\"type\":\"prompt\",\"payload\":\"Summarize the vendor contract and flag any auto-renewal clause.\",\"payloadHash\":\"0x1e2d99e683d2623c77a82721f633f27206cd8051be8c848509f63bb570bd5be4\"},{\"seq\":1,\"ts\":\"2026-07-01T09:00:01.000Z\",\"actor\":\"agent:assistant\",\"type\":\"tool_call\",\"payloadHash\":\"0x32133a5998ab97eaef8850a7a47cec6e1056b964a050e6e5561f97ec22b24498\",\"redacted\":true,\"meta\":{\"tool\":\"contract_search\"}},{\"seq\":2,\"ts\":\"2026-07-01T09:00:02.000Z\",\"actor\":\"tool:contract_search\",\"type\":\"tool_result\",\"payload\":\"Section 12.3: renews automatically for successive 12-month terms unless cancelled 60 days prior.\",\"payloadHash\":\"0x57bed64393fb6ed461a5b00143cc239cf705e4a1ea5d0ee84a8f5f7ecc85bdc1\"},{\"seq\":3,\"ts\":\"2026-07-01T09:00:03.000Z\",\"actor\":\"agent:assistant\",\"type\":\"completion\",\"payload\":\"Flagged: Section 12.3 auto-renews for successive 12-month terms and requires 60 days cancellation notice.\",\"payloadHash\":\"0x43649f64cb62093be040484c6858b80f0973e6aa2bd9bc4df75c0c725dcd5bb4\"}],\"leaves\":[\"0x5a3354160c02d09a5b653227ebd35d8f0a1ade1284e402049b91c4f8acd873e3\",\"0x57ac83bf53104a1d952cf9d00e904f15e31d4cc17bc6ff0aedacd1b6ca40904a\",\"0xb3ee61a8dc496b92e05db48b990edee212bda46ca29e5480efb056a5c2cf817f\",\"0x1000b07e45f6151bcf49be6266358cec551a690654f22dc5dae279e7d6bfb7d1\"]}\n";
+const DEMO_AGENT_TAMPER_SEQ = 0;
+const DEMO_AGENT_TAMPER_FROM = "\"payload\":\"Summarize the vendor contract";
+const DEMO_AGENT_TAMPER_TO = "\"payload\":\"SUMMARIZE the vendor contract";
+
+// Materialize the demo packet + its referenced files into `dir`. Returns the packet path.
+function writeDemoFixture(dir) {
+  for (const [rel, content] of Object.entries(DEMO_FILES)) {
+    fs.writeFileSync(path.join(dir, rel), content);
+  }
+  const packetPath = path.join(dir, DEMO_PACKET_NAME);
+  fs.writeFileSync(packetPath, JSON.stringify(DEMO_CONTAINER, null, 2));
+  return packetPath;
+}
+
+// Run the zero-config demo: seal -> ACCEPT (pinned to the recovered signer) -> tamper -> REJECT. Uses the
+// REAL verifyArtifact core for BOTH runs (no bespoke verify path), so the verdicts are exactly what a real
+// counterparty would see. Returns the EXIT-contract code (0 only when the whole demo behaved as designed).
+function runDemo(write, writeErr) {
+  // A throwaway temp dir so the demo needs no input and writes NOTHING under cwd. Cleaned in finally.
+  let tmp;
+  try {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), "verify-vh-demo-"));
+  } catch (e) {
+    writeErr(`error: demo could not create a temp working dir: ${e.message}\n`);
+    return EXIT.IO;
+  }
+  try {
+    const packetPath = writeDemoFixture(tmp);
+
+    const L = [];
+    L.push(TRUST_NOTE);
+    L.push("");
+    L.push("# verify-vh demo — a self-contained, GENUINELY-SIGNED packet, verified OFFLINE with zero config.");
+    L.push("# (No flags, no key to paste: the demo ships a real signed seal + its files and checks them for you.)");
+    L.push(`# Working dir (throwaway, deleted on exit): ${tmp}`);
+    L.push("");
+
+    // (1) GENUINE packet: recover the signer first, then PIN it (so the demo proves both recovery AND the
+    //     vendor-pin path) — exactly what a real counterparty does once they learn the producer's address.
+    const recovered = tryRecover(DEMO_CONTAINER.attestation, DEMO_CONTAINER.signature.signature);
+    if (recovered !== DEMO_SIGNER) {
+      writeErr(
+        `error: demo fixture is corrupt — embedded signature recovered ${String(recovered)} != ${DEMO_SIGNER}\n`
+      );
+      return EXIT.IO;
+    }
+    L.push("STEP 1 — verify the genuine packet (signer recovered from the bytes, then pinned):");
+    const good = verifyArtifact({ artifact: packetPath, vendor: recovered, dir: tmp });
+    if (!good.result.accepted || good.code !== EXIT.OK) {
+      // Should never happen for the shipped fixture; treat as an internal fault, not a silent pass.
+      writeErr(`error: demo genuine packet did NOT verify (reason: ${good.result.reason})\n`);
+      write(renderHuman(good.result));
+      return EXIT.IO;
+    }
+    L.push(`  ACCEPT — the artifact verifies. signer: ${good.result.recoveredSigner}`);
+    L.push(`  sealed root:     ${good.result.sealedRoot}`);
+    L.push(`  recomputed root: ${good.result.recomputedRoot}  (re-derived from the bytes on disk)`);
+    L.push(`  files: ${good.result.counts.matched} matched, 0 changed, 0 missing.`);
+    L.push("");
+
+    // (2) TAMPER one byte of a referenced file, re-verify the SAME packet -> a clean REJECT naming the file.
+    const victim = path.join(tmp, "model-card.md");
+    fs.writeFileSync(victim, DEMO_FILES["model-card.md"] + "X"); // one extra byte
+    L.push("STEP 2 — tamper ONE byte of a referenced file, then re-verify the SAME packet:");
+    const bad = verifyArtifact({ artifact: packetPath, vendor: recovered, dir: tmp });
+    if (bad.result.accepted || bad.code !== EXIT.REJECTED) {
+      writeErr(`error: demo tampered packet was NOT rejected (reason: ${bad.result.reason})\n`);
+      return EXIT.IO;
+    }
+    L.push(`  REJECT (${bad.result.reason}) — the tampered copy is caught:`);
+    for (const c of bad.result.changed) {
+      L.push(`    CHANGED  ${c.relPath}: sealed ${c.expectedContentHash} != on-disk ${c.actualContentHash}`);
+    }
+    L.push("");
+
+    L.push("That is the whole promise: a genuine packet is ACCEPTED and its signer named, while a one-byte");
+    L.push("change is REJECTED — re-derived from the bytes you hold, offline, with no producer stack.");
+    L.push("");
+    // The bare demo is a closed loop in a temp dir — gone the instant it exits. Hand the user the ONE command
+    // that turns "I watched a demo" into "I have a real packet on disk I can poke at": `demo <dir>` writes the
+    // same genuine packet somewhere they KEEP, with copy-paste verify/tamper/restore commands. That is the
+    // working on-ramp from the canned proof to verifying their OWN bytes (where the paid `--sign` pull begins).
+    // NOTE: we name the command literally (NOT process.argv[1]) so the bare-demo output is byte-identical
+    // whether run in-process, as `node verify-vh.js`, or from the standalone bundle — the demo's own
+    // determinism is a tested invariant (the standalone must byte-match the in-tree demo).
+    L.push("TRY IT YOURSELF: keep a copy you can tamper with by hand —");
+    L.push("  node verify-vh.js demo ./vh-demo     # writes the same signed packet + files into ./vh-demo,");
+    L.push("                                       # then prints the exact verify / tamper / restore commands.");
+    L.push("");
+    L.push("NEXT: run it on a REAL packet you were handed:");
+    L.push("  node verify-vh.js <packet> --vendor 0xPRODUCER_ADDRESS   (exit 0 = verifies; 3 = REJECTED)");
+    L.push("");
+    write(L.join("\n"));
+    return EXIT.OK;
+  } catch (e) {
+    writeErr(`error: demo failed unexpectedly: ${e.message}\n`);
+    return EXIT.IO;
+  } finally {
+    try {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    } catch (_) {
+      /* best-effort cleanup; the OS reaps temp dirs anyway */
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// `demo <dir>` — the KEEPABLE scaffold (T-55.2 rework). The bare `demo` proves the round-trip in a throwaway
+// temp dir and is GONE the instant it exits — a closed loop the prospect can WATCH but cannot TOUCH. That is
+// the funnel dead-end the review panel flagged: the demo's own "NEXT: run it on a REAL packet" is unactionable
+// because a brand-new user HAS no packet yet. `demo <dir>` closes that gap: it MATERIALIZES the same genuine
+// signed packet + its two referenced files into a directory the user names and KEEPS, then prints the exact,
+// copy-pasteable REAL commands to (a) verify it with the real (non-canned) verify path, (b) tamper one byte
+// and watch the real REJECT, and (c) restore and re-ACCEPT. The prospect's FIRST hands-on artifact is now one
+// they hold on disk and can poke at with the production code path — the working on-ramp from "watched a demo"
+// to "verified my own bytes", which is where the free→paid pull (sign YOUR OWN files: `vh evidence seal
+// --sign` / the `evidence_unlimited` upgrade) actually begins.
+//
+// It is a PURE SUPERSET of the flagless quickstart: it engages ONLY when a single <dir> token follows `demo`
+// (`verify-vh demo` with no token stays the byte-identical throwaway round-trip above). It WRITES — by design,
+// into the dir the user explicitly named — so it is never reached by the bare flagless path the "writes
+// nothing under cwd" contract pins. The packet it writes is byte-identical to the round-trip's, signed by the
+// same fixed TEST-ONLY key (hardhat #1 — never a real key / real funds).
+// ---------------------------------------------------------------------------
+
+function runDemoEmit(targetDir, write, writeErr) {
+  // Confirm the shipped fixture is internally sound BEFORE writing anything (recover the signer from the
+  // embedded bytes, exactly as a real verify does) — a corrupt fixture is an internal fault, not a scaffold.
+  const recovered = tryRecover(DEMO_CONTAINER.attestation, DEMO_CONTAINER.signature.signature);
+  if (recovered !== DEMO_SIGNER) {
+    writeErr(
+      `error: demo fixture is corrupt — embedded signature recovered ${String(recovered)} != ${DEMO_SIGNER}\n`
+    );
+    return EXIT.IO;
+  }
+
+  const dir = path.resolve(targetDir);
+  // mkdir -p the target. We create the user-named dir if absent; an existing dir is fine (we only add files).
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (e) {
+    writeErr(`error: demo could not create ${targetDir}: ${e.message}\n`);
+    return EXIT.IO;
+  }
+
+  let packetPath;
+  try {
+    packetPath = writeDemoFixture(dir);
+  } catch (e) {
+    writeErr(`error: demo could not write the scaffold into ${targetDir}: ${e.message}\n`);
+    return EXIT.IO;
+  }
+
+  // Verify the just-written packet through the REAL core (no canned path), so the scaffold is proven good on
+  // disk before we tell the user to trust it — and so the ACCEPT line the user will reproduce is the truth.
+  const good = verifyArtifact({ artifact: packetPath, vendor: recovered, dir });
+  if (!good.result.accepted || good.code !== EXIT.OK) {
+    writeErr(`error: demo scaffold did NOT verify after writing (reason: ${good.result.reason})\n`);
+    return EXIT.IO;
+  }
+
+  // The command name as the user invoked us (verify-vh.js in-tree, verify-vh-standalone.js as the bundle), so
+  // the copy-paste commands below name the EXACT file they ran — not a guessed path.
+  // Name the command the user actually ran (verify-vh.js in-tree, verify-vh-standalone.js as the bundle) so the
+  // copy-paste lines below name the EXACT file they invoked. If argv[1] is not one of our scripts (e.g. running
+  // in-process under a test harness), fall back to the canonical name rather than printing the harness binary.
+  const argv1 = path.basename(process.argv[1] || "");
+  const self = /verify-vh/.test(argv1) ? argv1 : "verify-vh.js";
+  // Print a path that is copy-pasteable from the user's CURRENT shell: the relative path when the target sits
+  // at/under cwd (the common `demo ./vh-demo` case -> a tidy `vh-demo/...`), else the absolute path (a `../../`
+  // chain to a far-off dir is unreadable and brittle — the absolute path always resolves).
+  const rel = (p) => {
+    const r = path.relative(process.cwd(), p);
+    return r && !r.startsWith("..") && !path.isAbsolute(r) ? r : p;
+  };
+  const pkt = rel(packetPath);
+  const card = rel(path.join(dir, "model-card.md"));
+
+  const L = [];
+  L.push(TRUST_NOTE);
+  L.push("");
+  L.push(`# verify-vh demo — wrote a real, KEEPABLE signed packet you can verify yourself, hands-on.`);
+  L.push(`# Signed by a fixed TEST-ONLY key (hardhat #1 — never a real key / real funds).`);
+  L.push("");
+  L.push(`Wrote into ${dir}:`);
+  L.push(`  ${DEMO_PACKET_NAME}   (a genuinely-signed evidence packet)`);
+  for (const r of Object.keys(DEMO_FILES)) L.push(`  ${r}`);
+  L.push(`  signer (recovered from the bytes): ${recovered}`);
+  L.push("");
+  L.push("It already VERIFIES — run it yourself (the real verify path, no canned demo):");
+  L.push(`  node ${self} ${pkt} --vendor ${recovered}`);
+  L.push("  # exit 0 = ACCEPT (root re-derived from YOUR bytes on disk; signer pinned).");
+  L.push("");
+  L.push("Now PROVE tamper-evidence with your own hands — change one byte, then re-verify:");
+  L.push(`  printf 'X' >> ${card}`);
+  L.push(`  node ${self} ${pkt} --vendor ${recovered}   # exit 3 = REJECT (CHANGED ${path.basename(card)})`);
+  L.push("");
+  L.push("Restore it and watch it ACCEPT again (the change was the ONLY reason it rejected):");
+  L.push(`  node ${self} ${pkt} --vendor ${recovered}   # after restoring the byte`);
+  L.push("");
+  L.push("NEXT — verify a packet someone handed YOU (same command, their address):");
+  L.push(`  node ${self} <their-packet> --vendor 0xTHEIR_ADDRESS`);
+  L.push("");
+  L.push("Want to SIGN your OWN files so a counterparty can pin YOU? That is the paid producer side:");
+  L.push("  vh evidence seal <your-folder> --sign        (an EIP-191 signer-pin; the `evidence_unlimited`");
+  L.push("                                                upgrade lifts the free 25-file cap) — see verifier/README.md §0a.");
+  L.push("");
+  write(L.join("\n"));
+  return EXIT.OK;
+}
+
+function usage() {
+  return [
+    "verify-vh — standalone, read-only, OFFLINE verifier for verifyhash artifacts",
+    "",
+    "Usage:",
+    "  verify-vh demo                                                                                   (zero-config quickstart)",
+    "  verify-vh demo <dir>                                                                              (write a keepable signed packet you can verify yourself)",
+    "  verify-vh <artifact> [--vendor <0xaddr>] [--dir <d>] [--revocations <file-or-dir> [--as-of <ISO>]] [--json]",
+    "  verify-vh <artifact> <artifact> ... [--vendor <0xaddr>] [--dir <d>] [--revocations <file-or-dir>] [--json]   (batch)",
+    "  verify-vh --manifest <file> [--vendor <0xaddr>] [--dir <d>] [--revocations <file-or-dir>] [--json]           (batch)",
+    "",
+    "DEMO: `verify-vh demo` runs a self-contained, genuinely-signed packet through the real verify path —",
+    "NO flags, NO key, NO install state: it ACCEPTs the packet (naming the signer), then REJECTs a one-byte-",
+    "tampered copy. The single command that takes a brand-new user from nothing to a verified packet.",
+    "`verify-vh demo <dir>` goes one step further: it WRITES that same genuine signed packet + its files into",
+    "<dir> (which you keep) and prints copy-paste commands so you verify, tamper, and re-verify it by hand.",
+    "",
+    "Auto-detects the artifact kind (evidence seal, reconciliation seal, dataset attestation, proof",
+    "bundle — bare or signed — or an agent-session packet *.vhagent.json), RE-DERIVES the keccak root",
+    "from the referenced bytes (siblings resolve next to the artifact, or under --dir <d>), recovers",
+    "the signer of a signed artifact, and PINS it to --vendor <0xaddr> (or reports the recovered signer",
+    "when no pin is given). An agent-session packet is SELF-CONTAINED: every event leaf + the ordered",
+    "RFC-6962-style head are re-derived from the events in the packet (REDACTED payloads are checked by",
+    "their hash commitments), and a REJECT names the first offending event seq.",
+    "",
+    "REVOCATIONS: --revocations <file-or-dir> [--as-of <ISO>] downgrades an otherwise-ACCEPTED signed",
+    "artifact to REVOKED (exit 3) when its signing key was REVOKED at or before --as-of (default now). The",
+    "file may be one signed revocation or a JSON array; a directory is read as a flat pool of revocation",
+    "files. A revocation dated AFTER --as-of stays ACCEPTED with a later-revoked note; a forged/tampered/",
+    "third-party revocation is IGNORED with a warning. This reaches the SAME downgrade the producer's",
+    "`vh ... verify-signed --revocations` does, OFFLINE — no producer stack, no network, no key.",
+    "",
+    "BATCH/MANIFEST: pass several <artifact> args, or --manifest <file> (a newline list or JSON array of",
+    "artifact paths, each line/object may carry its own --vendor/--dir). ALL must pass for exit 0; if ANY",
+    "is rejected, exit is 3 and the report names which artifact failed and why. --json emits a stable",
+    "aggregate { ok, total, passed, failed, results:[...] } whose entries are the single-artifact shape.",
+    "Top-level --vendor/--dir are inherited as defaults a manifest entry may override; --revocations/--as-of",
+    "apply to every entry.",
+    "",
+    "READ-ONLY: holds no key, writes nothing. Exit: 0 ok / 3 rejected|revoked / 2 usage / 1 IO.",
+    "",
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// run(argv, io) — the testable entrypoint. Returns the EXIT-contract integer. Injectable stdout/stderr.
+// ---------------------------------------------------------------------------
+
+function run(argv, io = {}) {
+  const write = io.write || ((s) => process.stdout.write(s));
+  const writeErr = io.writeErr || ((s) => process.stderr.write(s));
+
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (e) {
+    writeErr(`error: ${e.message}\n`);
+    return EXIT.USAGE;
+  }
+  if (opts.help) {
+    write(usage());
+    return EXIT.OK;
+  }
+  // DEMO: the zero-config quickstart (T-55.2). `verify-vh demo` — a SINGLE bare positional `demo`, with NO
+  // other args at all (no flags, no second positional, no manifest) — runs the self-contained signed packet
+  // through the real verify path. We require the LONE argument to be exactly `demo` so the quickstart contract
+  // is unambiguous: `demo` with any extra token falls through to the normal path (where it is a clean error),
+  // never a silently-flag-ignoring run. It is a pure SUPERSET of the existing contract: `demo` was never a
+  // valid artifact path before (there is no file named `demo`, so a lone `demo` was a clean IO error), so
+  // intercepting it here shifts no existing caller.
+  if (argv.length === 1 && opts.artifact === "demo") {
+    return runDemo(write, writeErr);
+  }
+  // DEMO SCAFFOLD: `verify-vh demo <dir>` — a pure SUPERSET (T-55.2 rework). When `demo` is followed by exactly
+  // ONE more bare token (a target directory) and NO flags, write the same genuine signed packet + its files
+  // into that dir the user KEEPS, and print copy-paste verify/tamper/restore commands. This is the actionable
+  // on-ramp the bare demo (a throwaway temp dir, gone on exit) cannot give. We require EXACTLY two bare
+  // positionals and no flags so the contract stays unambiguous; `demo <dir> --anything` falls through to the
+  // normal path (where a file literally named `demo` is a clean IO error, byte-identically to before).
+  if (
+    argv.length === 2 &&
+    argv[0] === "demo" &&
+    opts._pos.length === 2 &&
+    opts._pos[0] === "demo" &&
+    !opts.json &&
+    opts.manifest === undefined &&
+    opts.vendor === undefined &&
+    opts.dir === undefined
+  ) {
+    return runDemoEmit(opts._pos[1], write, writeErr);
+  }
+  // No artifact AND no manifest → the same usage error as before (the batch additions are a pure superset).
+  if (opts.artifact === undefined && opts.manifest === undefined) {
+    writeErr("error: verify-vh requires an <artifact>\n\n");
+    writeErr(usage());
+    return EXIT.USAGE;
+  }
+
+  // The recipient's current decision instant (the default --as-of). Injectable via io.nowISO so a test can
+  // pin the clock; otherwise the wall clock. Threaded onto opts for the (optional) revocation evaluation.
+  opts.nowISO = io.nowISO || new Date().toISOString();
+
+  // BATCH path: a --manifest file or more than one positional <artifact>. Aggregates per-artifact verdicts
+  // under one CI exit code. The single-artifact path below is byte-for-byte the original behavior.
+  if (opts.batch) {
+    let out;
+    try {
+      out = verifyBatch(opts);
+    } catch (e) {
+      if (e instanceof UsageError) {
+        writeErr(`error: ${e.message}\n`);
+        return EXIT.USAGE;
+      }
+      if (e instanceof IOError) {
+        writeErr(`error: ${e.message}\n`);
+        return EXIT.IO;
+      }
+      writeErr(`error: ${e.message}\n`);
+      return EXIT.IO;
+    }
+    if (opts.json) {
+      write(JSON.stringify(out.aggregate, null, 2) + "\n");
+    } else {
+      write(renderBatchHuman(out.aggregate));
+    }
+    return out.code;
+  }
+
+  let out;
+  try {
+    out = verifyArtifact(opts);
+  } catch (e) {
+    if (e instanceof UsageError) {
+      writeErr(`error: ${e.message}\n`);
+      return EXIT.USAGE;
+    }
+    if (e instanceof IOError) {
+      writeErr(`error: ${e.message}\n`);
+      return EXIT.IO;
+    }
+    // Any other error is an unexpected internal fault — surface it as an IO error (never a stack to a
+    // counterparty), exit 1.
+    writeErr(`error: ${e.message}\n`);
+    return EXIT.IO;
+  }
+
+  if (opts.json) {
+    write(JSON.stringify(out.result, null, 2) + "\n");
+  } else {
+    write(renderHuman(out.result));
+  }
+  return out.code;
+}
+
+// CLI shim: only run when invoked directly (so the module is importable in tests without side effects).
+if (require.main === module) {
+  process.exit(run(process.argv.slice(2)));
+}
+
+module.exports = {
+  EXIT,
+  KINDS,
+  TRUST_NOTE,
+  UsageError,
+  IOError,
+  parseArgs,
+  parseManifest,
+  verifyArtifact,
+  verifyArtifactFromBytes,
+  verifyBatch,
+  buildBatchEntries,
+  renderBatchHuman,
+  verifyEvidenceSeal,
+  verifyTrustSeal,
+  verifyDatasetAttestation,
+  verifyProofBundle,
+  verifyAgentSeal,
+  AGENT_TRUST_NOTE,
+  renderHuman,
+  revocation,
+  usage,
+  run,
+  runDemo,
+  runDemoEmit,
+  DEMO_SIGNER,
+  DEMO_FILES,
+  DEMO_CONTAINER,
+  DEMO_PACKET_NAME,
+  DEMO_AGENT_PACKET_NAME,
+  DEMO_AGENT_PACKET_TEXT,
+  DEMO_AGENT_TAMPER_SEQ,
+  DEMO_AGENT_TAMPER_FROM,
+  DEMO_AGENT_TAMPER_TO,
+  MAX_RELPATH_CHARS,
+};
+
+};
+
+// ---- embedded build-provenance (this file's own): see `--provenance` / `--self-attest` below. ----
+var __SELF_SHA256_SENTINEL = "0000000000000000000000000000000000000000000000000000000000000000";
+var __PROVENANCE = {
+  "schema": "verifyhash/build-provenance@1",
+  "target": "verify",
+  "note": "This bundle's OWN provenance, embedded so the single file is self-describing. Run `node verify-vh-standalone.js --self-attest` to recompute selfSha256 from these very bytes, or `--provenance` to print the ordered source modules + hashes it was built from. Cross-check against verifier/dist/BUILD-PROVENANCE.json (the same data) with: node verifier/build-standalone.js --check",
+  "selfSha256": "97d8a906c8f9d584ff2c5ff88691e4bad334180f8894afa1d3c7a6b4aff2d8e8",
+  "modules": [
+    {
+      "id": "keccak256-vendored",
+      "synthetic": false,
+      "sourceFile": "verifier/lib/keccak256-vendored.js",
+      "sourceSha256": "4f5f2dda618a5889ab5b3f8498dc64ddeacdd22b57349d97824f60960ee334a1",
+      "inlinedSha256": "4f5f2dda618a5889ab5b3f8498dc64ddeacdd22b57349d97824f60960ee334a1",
+      "entry": false
+    },
+    {
+      "id": "keccak",
+      "synthetic": true,
+      "sourceFile": null,
+      "sourceSha256": null,
+      "inlinedSha256": "7ead489c805c4e62e8338dbcfde77a85ca52076e2a3639e2ba57ce3b2415828e",
+      "note": "swapped body (keccak provider shim) — defined in build-standalone.js, not a source file"
+    },
+    {
+      "id": "merkle",
+      "synthetic": false,
+      "sourceFile": "verifier/lib/merkle.js",
+      "sourceSha256": "1bea7bab4b479962225279f4590c5524fad5295c7c70cf01d4978dbf9f37f34b",
+      "inlinedSha256": "e65be5614998f9a00ca9b58a6c79b05abe7f70ed2e0dad61ece07a41ee5da876",
+      "entry": false
+    },
+    {
+      "id": "canonical",
+      "synthetic": false,
+      "sourceFile": "verifier/lib/canonical.js",
+      "sourceSha256": "edc190dcabd2b34b33c54240fc951141de13d2c7d2759184cacb160dfdf3e764",
+      "inlinedSha256": "edc190dcabd2b34b33c54240fc951141de13d2c7d2759184cacb160dfdf3e764",
+      "entry": false
+    },
+    {
+      "id": "secp256k1-recover",
+      "synthetic": false,
+      "sourceFile": "verifier/lib/secp256k1-recover.js",
+      "sourceSha256": "34bb39eed0afc5f55241419ba827404bf767fa5dde1363dba5ad9c419cf91dab",
+      "inlinedSha256": "c8bab43d54b01dd7e55aeae6bc6d27986b868cbc7ebc1b1279dc70f032dbc122",
+      "entry": false
+    },
+    {
+      "id": "revocation-core",
+      "synthetic": false,
+      "sourceFile": "verifier/lib/revocation-core.js",
+      "sourceSha256": "99377291d5455b7a01a3eca313cd1289f6df8ce76a37bcb0aacc68ebe70601b1",
+      "inlinedSha256": "6a426132b56560771fc187caaeee308cd4aaaf87b211aff87dff04cbc622bd2e",
+      "entry": false
+    },
+    {
+      "id": "revocation",
+      "synthetic": false,
+      "sourceFile": "verifier/lib/revocation.js",
+      "sourceSha256": "538b09ca210e47b51319b89fc681229ee16873425f2635855dc0d6f0dc57374f",
+      "inlinedSha256": "ba7ae1d7600289d7584e998f02fffb82eaa03dfb55e2e2373bda374144ce9d44",
+      "entry": false
+    },
+    {
+      "id": "verify-vh",
+      "synthetic": false,
+      "sourceFile": "verifier/verify-vh.js",
+      "sourceSha256": "0e948e5973cd0faf3acda4fb14640feed13fde6190e345b2aea083addeb4b662",
+      "inlinedSha256": "ad89a1d71240c725255633f27f7f3298c8c9718b33eea7c640cae8d62eea8054",
+      "entry": true
+    }
+  ]
+};
+function __maybeProvenance(argv) {
+  var wantProv = argv.indexOf('--provenance') !== -1;
+  var wantAttest = argv.indexOf('--self-attest') !== -1;
+  if (!wantProv && !wantAttest) return null;
+  if (wantProv) { process.stdout.write(JSON.stringify(__PROVENANCE, null, 2) + '\n'); }
+  if (wantAttest) {
+    var fs = require('fs');
+    var crypto = require('crypto');
+    var selfText;
+    try { selfText = fs.readFileSync(__filename, 'utf8'); }
+    catch (e) { process.stderr.write('self-attest: cannot read this file: ' + e.message + '\n'); return 1; }
+    // Re-blank our own selfSha256 line back to the sentinel, then hash — reproducing the build's pass-1 hash.
+    var blanked = selfText.replace(
+      '"selfSha256": "' + __PROVENANCE.selfSha256 + '"',
+      '"selfSha256": "' + __SELF_SHA256_SENTINEL + '"'
+    );
+    var got = crypto.createHash('sha256').update(Buffer.from(blanked, 'utf8')).digest('hex');
+    if (got === __PROVENANCE.selfSha256) {
+      process.stdout.write('[MATCH] self-attest: this file is intact (selfSha256 ' + got + ').\n');
+      return 0;
+    }
+    process.stderr.write('[MISMATCH] self-attest: this file has been MODIFIED ' +
+      '(embedded selfSha256 ' + __PROVENANCE.selfSha256 + ' != recomputed ' + got + ').\n');
+    return 1;
+  }
+  return 0;
+}
+
+// ---- boot: run the inlined verifier CLI with this process's argv. ----
+var __entry = __require("verify-vh");
+if (require.main === module) {
+  var __code = __maybeProvenance(process.argv.slice(2));
+  if (__code !== null) process.exit(__code);
+  process.exit(__entry.run(process.argv.slice(2)));
+}
+module.exports = __entry;