verifyhash 0.1.0

package/docs/IDENTITY.md

@@ -0,0 +1,123 @@
+# Producer identity card (`vh identity`)
+
+A **signed, offline-verifiable "who is this vendor, and what exactly do they attest?"** card. A producer
+SIGNS — with the **same key** that signs their evidence packets / signed licenses / dataset attestations —
+a small, self-describing container that binds their **`vendorAddress`** to a bounded `claims[]` set (what
+they attest) and an honest `nonClaims[]` set (what they explicitly do **NOT**). A recipient — or a **cold
+prospect** who has never met you — recovers the signer from the card, confirms it **equals the card's own
+`vendorAddress`** (the key controls the address it claims), and OPTIONALLY pins it to an address they
+learned out of band. All of it is **OFFLINE, key-free, network-free, I/O-free**.
+
+It is the **recipient's / cold prospect's pin-point**: every other artifact this family mints (an evidence
+seal, a signed license, a dataset attestation) pins its producer by a vendor **address** the recipient must
+learn out of band — an email, a slide, a README line. The identity card is the **one** artifact whose
+whole job is to answer, verifiably, "**does this 0x-address really belong to THIS vendor, and what exactly
+do they attest — and, just as load-bearing, what do they explicitly NOT?**" before the recipient trusts a
+single packet.
+
+**Trust boundary (the output leads with this, verbatim — the standing `IDENTITY_CARD_TRUST_NOTE`):**
+
+```
+This is a verifyhash producer IDENTITY CARD: the holder of `vendorAddress`'s key SIGNED it, binding that address to the `claims` it attests and the `nonClaims` it explicitly does NOT. verify RE-DERIVES the signer from these exact bytes and REQUIRES it to equal `vendorAddress` — it never trusts the file's own claims. It proves IDENTITY + the claim SET ONLY: it does NOT prove any specific sealed/signed packet is true (each packet carries its own proof), it is NOT a trusted TIMESTAMP ("published since T" rides the human-owned signing/timestamp trust-root, STRATEGY.md P-3), and it is NOT a legal opinion.
+```
+
+> A card proves **IDENTITY + the claim SET**, **NOT packet truth** (each sealed/signed packet carries its
+> own proof — `vh evidence verify` / `verify-signed`), **NOT a trusted timestamp** (P-3), and **NOT a legal
+> opinion**. See [`docs/TRUST-BOUNDARIES.md`](TRUST-BOUNDARIES.md).
+
+## Commands
+
+```
+vh identity publish --address <0xaddr> --product-line <line> --claim <text> [--claim ...] --non-claim <text> [--non-claim ...] [--published-at <ISO>] (--key-env <VAR> | --key-file <path>) [--out <p>] [--json]
+vh identity verify <card> [--signer <0xaddr>] [--json]
+```
+
+### `vh identity publish` — mint the card
+
+`publish` MINTS a signed `*.vhidentity.json` card binding `--address` to the `--claim` set it attests + the
+`--non-claim` set it explicitly does NOT. It signs with a **HUMAN-provisioned key** (EXACTLY ONE of
+`--key-env` / `--key-file`, **read-used-discarded** via the shared `loadSigningWallet` — the loop **NEVER**
+generates, persists, or logs a key, and the key never appears in any output).
+
+- **The load-bearing mint invariant — the key controls the address it claims.** `publish` mints **ONLY**
+  when the provisioned key's address **EQUALS** `--address`. A key that does **NOT** control `--address`
+  **hard-errors (exit 2) BEFORE writing anything** — so a card can never assert an identity the key cannot
+  back, and a published card **always** round-trips to ACCEPTED by construction.
+- **Filesystem hygiene.** Default **prints the card + writes NOTHING**; `--out <p>` writes ONLY to the
+  caller-chosen path — **never silently to cwd**.
+- `--product-line` is one of the closed set `["dataledger", "evidence", "trustledger"]` (an out-of-set line
+  is a usage error); `claims` and `nonClaims` are each a **non-empty** list (a card that attests nothing, or
+  that drops the honest boundary, is refused).
+- The output **LEADS with the trust line**; `--json` carries the PUBLIC card summary (vendorAddress, signer,
+  productLine, claims, nonClaims, publishedAt) + the artifact — and **never the key**.
+- **Exit:** **0** ok / **2** usage (missing/invalid field, key-source error, key does not control
+  `--address`) / **1** IO (`--out` write).
+
+### `vh identity verify` — check + pin the card
+
+`verify <card>` is the **OFFLINE / key-free / network-free** read path. It RECOVERS the signer from the
+embedded canonical card bytes + signature and:
+
+1. confirms the signature backs the container's claimed `signer` (**ALWAYS**);
+2. confirms the recovered signer **IS** the card's own `vendorAddress` — the load-bearing "the key controls
+   the address it claims" check (**ALWAYS**);
+3. OPTIONALLY pins the recovered signer to an expected **`--signer <0xaddr>`** you learned out of band.
+
+The verdict is **ACCEPTED** only when **every requested check passes**; a **forged / tampered / wrong-vendor
+card, or a wrong `--signer`, is a clean REJECTED — NEVER a silent pass**. It **LEADS with the trust line**,
+prints the `claims` + `nonClaims` + per-check **PASS / FAIL / [skip]**, and writes **NOTHING**.
+
+- **Exit:** **0** ACCEPTED / **3** REJECTED / **2** usage / **1** IO — the same read contract as
+  `vh evidence verify-signed` / `vh dataset verify-attest`.
+
+## Pin once, trust across handoffs
+
+The card exists so a recipient does the **address-to-vendor** trust step **ONCE**, then reuses that pin
+across **every later handoff** — without re-establishing trust out of band each time.
+
+1. **Pin once.** The vendor publishes their card once (`vh identity publish … --out vendor.vhidentity.json`)
+   and the recipient confirms it once: `vh identity verify vendor.vhidentity.json --signer <addr-you-were-given>`.
+   That single ACCEPTED verdict is the recipient's durable answer to "this 0x-address really is this vendor,
+   and here is exactly what they attest / do NOT." The `--signer` pin binds the card to the address the
+   recipient learned out of band (the email/slide/contract) — so the out-of-band step happens **once**.
+2. **Trust across handoffs.** Every subsequent evidence packet, signed license, or dataset attestation the
+   vendor hands over is signed by the **same** key. The recipient verifies each artifact's signer
+   (`vh evidence verify-signed <p> --signer <addr>`, etc.) against the **same pinned address** — no new
+   out-of-band step, no re-pinning. The card's `vendorAddress` IS the address every later `--signer` pin
+   reuses, so one verified card amortizes the trust cost across an unbounded stream of handoffs.
+
+This is why the card is the **cold prospect's first stop**: it converts a single out-of-band "is this
+address really them?" into a verifiable, reusable pin — closing the gap between "interesting claim" and "I
+trust this vendor enough to run a pilot."
+
+## What the card does and does NOT prove
+
+- **It DOES prove IDENTITY + the claim SET.** The key that controls `vendorAddress` signed a bounded,
+  self-describing list of what the vendor attests (`claims`) and what they explicitly do **NOT** (`nonClaims`).
+  verify re-derives the signer from the exact bytes and requires it to equal `vendorAddress` — it never
+  trusts the file's own claims.
+- **It does NOT prove any specific packet's contents are true.** Each sealed/signed packet carries its OWN
+  proof — re-derive it (`vh evidence verify`) and check the signer (`vh evidence verify-signed`). The card
+  vouches for **who** the vendor is and **what** they claim to attest, not for the truth of any one packet.
+- **It is NOT a trusted timestamp.** A `publishedAt` is the vendor's self-asserted instant; "published
+  since T" rides the human-owned signing/timestamp trust-root (`needs-human`, **P-3** in
+  [`STRATEGY.md`](../STRATEGY.md)), exactly like every other dated artifact in this family.
+- **It is NOT a legal opinion.** The card makes no compliance/legal claim; it is tamper-evidence + a signed
+  identity binding, nothing more.
+
+## Where it fits
+
+The card is **one more product on the shared signed-attestation envelope** — no new crypto, no new
+dependency, no new scheme. It defines its own KIND (`vh-identity-card` / `vh-identity-card-signed`) + a
+closed field set, then hands the canonical payload to [`cli/core/attestation.js`](../cli/core/attestation.js),
+which does all the crypto: it embeds the EXACT canonical payload bytes, attaches the detached **EIP-191**
+signature, and later re-derives the signer — byte-for-byte the same shared paths the evidence seal and the
+signed license use. The publish/verify core lives in [`cli/identity.js`](../cli/identity.js).
+
+Provisioning the real vendor key, setting the price, and landing the first design partner remain **human
+steps** — the producer publishes their card with the same key they provision for signed evidence/licenses
+(STRATEGY.md › **P-7 step 1** / **P-6 step 1**).
+
+
+---
+<sub>© 2026 verifyhash.com · Licensed under Apache-2.0 (SPDX-License-Identifier: Apache-2.0) — see the [LICENSE](https://verifyhash.com/LICENSE) and [NOTICE](https://verifyhash.com/NOTICE) served with this file.</sub>

package/docs/INDEPENDENT-VERIFICATION.md

@@ -0,0 +1,377 @@
+# Independent verification — the buyer/counterparty deliverable
+
+> **Audience: a NON-customer.** You were handed a sealed verifyhash artifact by a counterparty (a
+> "producer") and you need to decide whether to believe it — without trusting the producer's software,
+> their servers, or us. This document is the contract that makes that possible. The runnable tool and a
+> quickstart live in [`../verifier/README.md`](../verifier/README.md); this is the deeper specification.
+
+The whole point of a provenance seal is that **the party relying on it is not the party who made it.**
+A proof you can only check with the producer's own toolchain is not a proof — it is a request to trust
+them. `verify-vh` exists so the relying party can recompute everything themselves, offline, for free.
+
+---
+
+## 0. Get it in 10 seconds (zero-install — start here)
+
+You do not need to clone this repo, run `npm install`, create an account, or install our toolchain to
+check a seal. Verification is **one self-contained file**,
+[`../verifier/dist/verify-vh-standalone.js`](../verifier/dist/verify-vh-standalone.js), that depends on
+**nothing but Node core**. The fastest honest path:
+
+```bash
+# 1. Save ONE file — verifier/dist/verify-vh-standalone.js — next to the packet you were handed.
+#    (Copy it from the repo, or your counterparty sends it to you. No clone, no install.)
+
+# 2. (Optional, recommended) Check its PUBLISHED checksum so you know the file itself wasn't swapped.
+#    The producer publishes the SHA-256 out-of-band; we ship it next to the file as
+#    verify-vh-standalone.js.sha256 (standard `sha256sum` line format):
+sha256sum -c verify-vh-standalone.js.sha256        # -> "verify-vh-standalone.js: OK"
+#    (macOS: `shasum -a 256 -c verify-vh-standalone.js.sha256`. Or eyeball it:
+#     `sha256sum verify-vh-standalone.js` and compare to the published hex.)
+
+# 2b. (Even better — needs NO second file.) The bundle is SELF-DESCRIBING: it carries its own
+#     build-provenance and can check its own bytes. From the ONE file alone:
+node verify-vh-standalone.js --self-attest          # -> "[MATCH] ... this file is intact"; exit 1 if edited
+node verify-vh-standalone.js --provenance           # -> the ordered source modules + sha256 it was built from
+#     `--provenance` lists the exact `verifier/lib/*` files (each pinned by its own sha256) the bundle inlines;
+#     those same hashes are in verifier/dist/BUILD-PROVENANCE.json, which
+#     `node verifier/build-standalone.js --check` reproduces end-to-end from source.
+
+# 3. Run it on the packet — no clone, no `npm install`, no node_modules, no account:
+node verify-vh-standalone.js <packet>.vhevidence.json --vendor 0xPRODUCER_ADDRESS
+#    exit 0 = verifies; exit 3 = REJECTED (and it names the file that changed / the wrong signer).
+```
+
+That single file is **byte-for-byte the same verifier** documented below — it is built deterministically
+from the `verifier/` sources (the keccak provider is swapped for a vendored pure-JS one, cross-checked
+against `js-sha3` and `ethers`), and a stale bundle FAILS CI
+([`../test/verifier.standalone.test.js`](../test/verifier.standalone.test.js)). The split-source,
+`npm install`-the-`verifier/`-tree path in [`../verifier/README.md`](../verifier/README.md) and §4 below
+remains for auditors who want to read each lib file on its own; both paths compute the **identical**
+verdict and exit code.
+
+**The easier path does not change what is proven.** Whether you run the one-file bundle or the split tree,
+the seal proves **tamper-evidence + signer-pin**, NOT a trusted "sealed at T" (that still requires
+**P-3** — see §3). The convenience is in the *install*, never in the *claim*.
+
+> **New here? Start with the guided 60-second challenge.** If you were handed a seal cold and want the
+> *fastest* "prove it to me" path — verify a real pre-sealed sample packet, then tamper one byte and watch
+> it get rejected and the changed file named — run [`../challenge/`](../challenge/) (one command, zero
+> install, zero account). It is the cold-prospect entry point to everything specified below, on the
+> **FREE, UNSIGNED** path (so there is no signer to pin in the sample), and it points free-verify →
+> free-produce → **paid-produce**. See [`../challenge/README.md`](../challenge/README.md).
+
+> **No Node on the machine? Run that challenge in your browser.** The same engine also ships as ONE
+> committed, fully offline HTML page —
+> [`../verifier/dist/verify-vh-standalone.html`](../verifier/dist/verify-vh-standalone.html): open it,
+> click the built-in sample packet (**ACCEPT**), change one character of the sample file on the page and
+> re-verify (**REJECT**, naming the file), then drag a real packet + its files in for the same verdict +
+> per-file localization specified below. The file contains **no network API at all** — check the browser
+> **devtools Network tab**: it stays empty, so your bytes never leave your machine. The boundary is the
+> one in §3, unchanged; for CI/production gating use the node standalone (`verify-vh-standalone.js`).
+
+> **On the checksum's trust model — read this so step 2 isn't oversold.** `sha256sum -c` proves the file
+> you saved is bit-for-bit the file whose hash was published; it does **not**, by itself, prove *who*
+> published that hash. The hash is a **transport-integrity** check (did the bundle arrive intact / un-swapped?),
+> pinned to a value you obtain **out-of-band** from the producer — exactly like the `--vendor` signer
+> address. The real root of trust is still the cross-checked, dependency-grepped, network-poisoned audit of
+> the source in §5: the checksum only saves you from re-reading 80 KB every time once you have audited it once.
+
+---
+
+## 0a. Produce your own seal in 10 seconds, then verify it (the free round-trip)
+
+§0 shows the **verify** half. There is a matching FREE **produce** half, so you can drive the *entire*
+loop yourself before you ever talk to us — **seal your own files, hand them off, verify** — with **no
+clone, no `npm install`, no account, no key** on either side. The producer half is also **one
+self-contained file**, [`../verifier/dist/seal-vh-standalone.js`](../verifier/dist/seal-vh-standalone.js),
+depending on **nothing but Node core** (the same vendored keccak the verifier uses):
+
+```bash
+# 1. Save ONE file — verifier/dist/seal-vh-standalone.js (optionally check its published
+#    seal-vh-standalone.js.sha256 the same way as the verifier in §0).
+
+# 2. Seal up to 25 of YOUR OWN files into one tamper-evident packet — no install, no key, no account:
+node seal-vh-standalone.js <your-folder> -o packet.vhevidence.json      # exit 0 = sealed
+
+# 3. Hand packet.vhevidence.json + your folder to a counterparty; they run the FREE verifier from §0:
+node verify-vh-standalone.js packet.vhevidence.json --dir <your-folder> # exit 0 = verifies; 3 = REJECTED
+```
+
+That is the whole self-service adoption loop, free on both ends: one file to **seal**, one file to
+**verify**, and the `.vhevidence.json` is all that changes hands. The standalone sealer is built
+deterministically from the `verifier/` sources and a stale bundle FAILS CI
+([`../test/freeseal.standalone.test.js`](../test/freeseal.standalone.test.js)); its seal bytes are
+byte-for-byte identical to the producer's own `cli/evidence.js` seal over the same folder, so a free seal
+is the **same** artifact the paid tool wraps — not a toy.
+
+**The honest boundary is identical to §0, and the free seal is narrower still.** A standalone seal proves
+**tamper-evidence + offline-recompute** — these are exactly those files, independently re-derivable by
+anyone — and **NOT** a trusted "sealed at T" without **P-3** (see §3). On top of that the FREE seal is
+**UNSIGNED** (no signer to pin; there is no `--sign`/`--license`/`--key` flag here at all) and **capped at
+25 files** (a folder of more than 25 hard-errors and writes nothing). **SIGNING** (an EIP-191 signer-pin
+you can then check with `--vendor`) and **UNLIMITED** sealing are the PAID upgrade —
+`vh evidence seal --sign` / the `evidence_unlimited` entitlement (`--license`) through the full producer
+CLI. The free round-trip is the funnel; the paid upgrade adds *who signed it* and *no file cap*.
+
+---
+
+## 1. The deliverable, precisely
+
+`verify-vh` is a **standalone, read-only, OFFLINE** verifier that, given an artifact plus the files it
+references and the producer's signer address:
+
+1. **re-derives** the keccak-256 Merkle root from the bytes you hold,
+2. **compares** it to the root embedded (and signed) in the artifact,
+3. **recovers** the secp256k1 signer of the signature, and
+4. **pins** that signer to an address you supply out-of-band.
+
+It emits a deterministic verdict and a CI-gateable exit code. It is **free** — verification is never a
+paid tier (the producer pays to seal; anyone may verify forever). It ships with near-zero dependencies
+(`js-sha3` + a tiny vendored secp256k1 routine), so a third party can `npm install` it alone and audit
+the entire thing in an afternoon.
+
+---
+
+## 2. The exact bytes that are verified
+
+### 2.1 Content hash (per file)
+```
+contentHash(file) = keccak256( raw file bytes )
+```
+No normalization, no encoding, no line-ending fixups — the literal bytes on disk. A single changed byte
+produces a different hash, and the verifier reports that file as `CHANGED` with both the sealed and the
+on-disk hash so the diff is attributable.
+
+### 2.2 Merkle root (per artifact)
+Each referenced file contributes a leaf binding its `relPath` to its `contentHash`. Reconciliation
+seals additionally fold in a synthetic **header leaf** computed from the seal's own `verdict` + input
+role bindings, so editing the verdict (which lives in the seal, not in any file) still changes the
+recomputed root. All leaves are folded into one keccak-256 **root**. The exact leaf encoding and
+pairing order are in [`../verifier/lib/merkle.js`](../verifier/lib/merkle.js) — short and
+dependency-free by design, so you can re-implement it.
+
+### 2.3 Signature (EIP-191 `personal_sign` / keccak)
+A signed artifact carries a 65-byte `r(32) || s(32) || v(1)` secp256k1 signature whose **message is the
+canonical UTF-8 bytes of the artifact's unsigned payload** — re-derived by the verifier in
+[`../verifier/lib/canonical.js`](../verifier/lib/canonical.js), **not** read back from a self-asserting
+field. The digest is the standard EIP-191 personal-sign pre-image:
+
+```
+digest = keccak256( "\x19Ethereum Signed Message:\n" + decimal(byteLength(message)) + message )
+```
+
+The signer address is recovered via standard secp256k1 public-key recovery (SEC 1 §4.1.6) and rendered
+as `"0x" + lastBytes20( keccak256( X32 || Y32 ) )`, lowercased. With `--vendor 0xADDR` the recovered
+address must equal it (20 raw bytes; checksum casing ignored) or the verdict is `wrong_issuer`. This is
+a second, independent implementation of the family's recovery, continuously cross-checked against the
+production `ethers` path so the two cannot silently diverge
+([`../test/verifier.crypto.test.js`](../test/verifier.crypto.test.js)).
+
+---
+
+## 3. The trust boundary
+
+`verify-vh` makes exactly three claims, all derivable from the bytes in your hands, and explicitly
+disclaims everything else.
+
+### What it DOES prove
+- **Tamper-evidence.** The referenced files are byte-for-byte the ones sealed; any change is localized
+  and attributable (which file, sealed-hash vs on-disk-hash).
+- **Offline recompute.** The root is re-derivable by you alone — no trusted server, no "it matched on
+  our end." No network access occurs (proven mechanically; see §5).
+- **Signer-pin.** *Which key* vouched, pinned to an address you obtained out-of-band, so a different
+  key cannot impersonate the producer.
+- **Revocation-aware (opt-in).** With `--revocations <file-or-dir> [--as-of <ISO>]` `verify-vh`
+  consults the producer's signed key revocations and **downgrades** an otherwise-ACCEPTED artifact to
+  **REVOKED** (exit 3) when the signing key was revoked **at or before** the as-of instant (default:
+  now). A revocation dated *after* the as-of leaves the verdict ACCEPTED with an informational
+  later-revoked note; a forged / tampered / third-party revocation is **ignored** with a warning (a
+  revocation only ever *removes* trust, never adds it — a key revokes itself, so a third party cannot
+  grief you into rejecting a good artifact). This reaches the **same** downgrade the producer-stack
+  `vh ... verify-signed --revocations <f> --as-of <T>` reaches on the identical inputs — fully OFFLINE,
+  no producer stack, no network, no key (see [`KEY-LIFECYCLE.md`](KEY-LIFECYCLE.md)). A directory is
+  read as a flat pool of revocation files; a single file may be one revocation or a JSON array.
+
+### What it does NOT prove
+- **NOT a trusted "sealed at time T."** A signature attests *this key vouched for these bytes* — not
+  *when*. Any `timestamp`/`sealedAt`/`reportDate` field inside an artifact is **producer-asserted** and
+  rides the human-owned signing/timestamp trust-root (proposal **P-3** in
+  [`../STRATEGY.md`](../STRATEGY.md)). For an *independent* time anchor the family ships a separate,
+  also-offline **RFC-3161** timestamp path (`vh dataset/parcel verify-timestamp`, P-3 Option B) — that
+  is a different deliverable, and `verify-vh` does not assert it.
+- **NOT a legal/accounting opinion.** A green verdict means the bytes and the signer check out — not
+  that the producer's underlying conclusion (a reconciliation result, a dataset's lawful provenance) is
+  correct. That judgement stays with the producer and their reviewers.
+
+> **One sentence:** `verify-vh` tells you the bytes are unchanged and which key signed them — **not
+> when, and not whether the producer's conclusion is true.**
+
+---
+
+## 4. Worked example: `producer seals → hands over packet → counterparty runs verify-vh`
+
+A real end-to-end run (test-only ephemeral keys — never a real key or real funds; the same path the
+acceptance suite [`../test/verifier.cli.test.js`](../test/verifier.cli.test.js) exercises against the
+REAL producer code).
+
+**(a) Producer side.** With their paid evidence tool, the producer seals a directory and publishes
+their signer address (`0xb463…3221`) somewhere the counterparty trusts (contract, site, email sig):
+
+```
+data/
+  model-card.md
+  weights.bin
+  packet.vhevidence.json     # the signed seal, handed to the counterparty alongside the files
+```
+
+**(b) Hand-over.** The counterparty receives the three files. No producer software, account, or license
+is involved.
+
+**(c) Counterparty verifies** (one runtime dependency, no network):
+
+```bash
+cd verifier && npm install
+node verify-vh.js ../data/packet.vhevidence.json \
+     --vendor 0xb463f30cf53d1e0365130363ae9b9867998c3221
+```
+
+Accepted output (exit `0`):
+
+```
+kind:            vh.evidence-seal-signed
+embedded kind:   vh.evidence-seal
+signed:          yes
+recovered signer: 0xb463f30cf53d1e0365130363ae9b9867998c3221
+claimed signer:  0xb463f30cf53d1e0365130363ae9b9867998c3221
+pinned --vendor: 0xb463f30cf53d1e0365130363ae9b9867998c3221
+signer matches vendor: yes
+sealed root:     0x51004f29ea5b0081be2943d377b2c1572b0543af4bfea724642fa73db3589dd5
+recomputed root: 0x51004f29ea5b0081be2943d377b2c1572b0543af4bfea724642fa73db3589dd5
+root matches:    yes
+files: 2 matched, 0 changed, 0 missing, 0 rejected, 0 unexpected
+
+OK — the artifact verifies.
+```
+
+`--json` returns a stable verdict object — e.g.
+`{"verdict":"OK","reason":"OK","accepted":true,"rootMatches":true,"signerMatchesVendor":true,"counts":{"matched":2,"changed":0,"missing":0,"escaped":0,"unexpected":0}}`
+— so a counterparty's CI can gate on `accepted`.
+
+**(d) The rejections you should be able to reproduce** (each a clean exit `3`, never a crash):
+
+| you change | verdict | exit |
+|------------|---------|------|
+| any sealed byte (`echo x >> model-card.md`) | `CHANGED` (names the file, sealed vs on-disk hash) | 3 |
+| a sealed file is absent | `MISSING` | 3 |
+| pass a `--vendor` that is not the signer | `wrong_issuer` | 3 |
+| corrupt the embedded signature | `bad_signature` | 3 |
+
+---
+
+## 4a. Batch / manifest mode — gate a whole release in one invocation
+
+A release is rarely one artifact. To make `verify-vh` a wired-in CI **merge gate** rather than a one-off
+demo, a single invocation can verify **every** artifact a release produces and return **one** exit code.
+
+**Two ways to name the set:**
+
+```bash
+# (i) repeated positionals — each inherits the one top-level --vendor/--dir:
+verify-vh a.vhevidence.json b.vhseal --vendor 0xADDR --dir ./out
+
+# (ii) a manifest file — each entry carries its OWN optional --vendor/--dir:
+verify-vh --manifest release.manifest [--vendor 0xADDR] [--dir <d>] [--json]
+```
+
+**Manifest format.** A manifest is EITHER a **newline list** OR a **JSON array**:
+
+- *Newline form* — one entry per line; blank lines and lines beginning with `#` are skipped. A line is an
+  artifact path followed by optional `--vendor <0xaddr>` / `--dir <d>` tokens:
+  ```text
+  # 2026-Q2 release
+  datasets/march.vhevidence.json --vendor 0xb463…3221 --dir datasets/march
+  recon/q2.vhseal                --vendor 0xb463…3221
+  proofs/claim-7.vhproof.json
+  ```
+- *JSON form* — an array of strings and/or `{ "artifact": "...", "vendor"?: "0x...", "dir"?: "..." }`
+  objects.
+
+Artifact paths resolve relative to the **manifest file's own directory** (a release ships its manifest
+alongside its artifacts). A per-entry `--dir` likewise resolves against the manifest directory and
+localizes where THAT artifact's sibling files are read. A **top-level** `--vendor`/`--dir` is a
+**default** every entry inherits unless the entry overrides it. The manifest is parsed in-process; it
+introduces **no new crypto and no network** — it is a list, and nothing more.
+
+**Aggregate exit contract** (the existing `0/3/2/1` codes, now over the whole set):
+
+| exit | when |
+|------|------|
+| `0` (OK)       | **and only if** EVERY artifact verifies (each `accepted`) |
+| `3` (REJECTED) | ANY artifact is rejected — the report names WHICH artifact failed and why (per-entry `reason`) |
+| `2` (USAGE)    | a bad flag, a malformed per-entry `--vendor`, an empty manifest, or `--manifest` passed together with a positional artifact |
+| `1` (IO)       | the manifest itself, or any listed artifact, is unreadable / not the expected shape |
+
+Usage and IO faults are evaluated per entry and **short-circuit** the whole run with the matching code:
+a release gate must never report `ok` while one of its artifacts could not even be read or parsed.
+
+**Stable `--json` aggregate.** With `--json`, batch mode emits one object:
+
+```json
+{ "ok": false, "total": 3, "passed": 2, "failed": 1, "results": [ /* …per-artifact… */ ] }
+```
+
+Each element of `results[]` is **byte-identical in shape** to the single-artifact `--json` verdict object
+(§4) — the SAME core (`verifyArtifact`) verifies every entry, so the per-artifact body cannot drift from
+the single path. Gate your CI on `ok` (or the exit code). Every entry preserves the same per-entry
+path-escape / no-network guarantees (§3, §5) as a lone verify. The **single-artifact** invocation
+(`verify-vh <artifact>`) is a strict subset and is unchanged: a lone positional emits the single-artifact
+object, not an aggregate.
+
+---
+
+## 4b. A copy-paste CI merge gate — wire it into the partner's pipeline
+
+Batch mode answers the most common B2B adoption question — *"how do I make my pipeline AUTOMATICALLY
+reject a tampered/forged artifact on every merge?"* — only once it is actually **wired into CI**. Two
+shipped snippets do that with a single paste, and both install **only** the standalone verifier
+(`js-sha3`, never the producer's ethers/hardhat stack):
+
+- **[`../verifier/ci/verify-vh.generic.sh`](../verifier/ci/verify-vh.generic.sh)** — a portable `set -e`
+  shell gate for GitLab CI / CircleCI / Jenkins / a Makefile / a git hook. Configured purely by env vars
+  (`VH_VENDOR`, plus `VH_MANIFEST` *or* `VH_ARTIFACTS`, optional `VH_DIR`), it runs `verify-vh` over the
+  release and passes the `0/3/2/1` exit code straight through, so any non-zero verdict **fails the job**.
+- **[`../verifier/ci/verify-vh.github-actions.yml`](../verifier/ci/verify-vh.github-actions.yml)** — a
+  GitHub Actions workflow dropped at `.github/workflows/verify-vh.yml` that gates every push / pull
+  request.
+
+These are shipped **examples the loop never executes**. To prevent doc-rot, their exact gate command is
+mechanically extracted and run by [`../test/verifier.ci-snippet.test.js`](../test/verifier.ci-snippet.test.js):
+the shipped command MUST exit `0` on a good release and `3` on a tampered one. A snippet a partner copies
+is therefore known-good, not aspirational — the gate that converts a one-off pilot into a wired-in
+renewal.
+
+---
+
+## 5. Why you can trust the verifier itself (proven, not promised)
+
+Independence is enforced by [`../test/verifier.isolation.test.js`](../test/verifier.isolation.test.js),
+which is part of the standard `npx hardhat test` suite:
+
+- **No producer stack / no back-edge.** It statically greps **every** `require(` across the whole
+  `verifier/` tree and asserts none resolves to `ethers`, `hardhat`, `@nomicfoundation/*`, or anything
+  under `cli/` or `trustledger/`. The only runtime dependency is `js-sha3`.
+- **No network.** It runs a real verify and asserts the process opens **no socket or network handle**,
+  and that the source never `require`s `http`/`https`/`net`/`dns`/`tls`. The tool cannot phone home —
+  it has nothing to phone home with.
+- **Read-only.** Holds no key, writes nothing, leaves the working tree untouched
+  ([`../test/verifier.cli.test.js`](../test/verifier.cli.test.js)).
+- **No silent crypto drift.** The vendored secp256k1 recovery is cross-checked against the production
+  `ethers` recovery ([`../test/verifier.crypto.test.js`](../test/verifier.crypto.test.js)).
+
+This is what lets a counterparty audit the verifier in an afternoon and then rely on its verdict
+without relying on us.
+
+
+---
+<sub>© 2026 verifyhash.com · Licensed under Apache-2.0 (SPDX-License-Identifier: Apache-2.0) — see the [LICENSE](https://verifyhash.com/LICENSE) and [NOTICE](https://verifyhash.com/NOTICE) served with this file.</sub>