verifyhash 0.1.0 → 0.1.1

package/docs/PUBLISH-VERIFY-VH.md

@@ -0,0 +1,45 @@
+# Publish `verify-vh` — the HUMAN checklist (one page)
+
+**Publishing stays human.** The build loop only builds and tests locally — it never runs
+`npm publish`, never deploys, never holds registry credentials (STRATEGY.md hard guardrails).
+This page is what the human follows when they decide to publish the standalone verifier package.
+
+**Why publish at all.** The front-door line in [docs/ADOPT.md](ADOPT.md) —
+`npx --yes verify-vh demo` — **404s until `verify-vh` is published to npm**. Everything else about
+that line is already true and machine-tested from the repo; publish is the single missing (human) step.
+
+**The gate that must be green first.** `test/verify-vh.pack.test.js` runs `npm pack` on `verifier/`
+(offline), extracts the tarball OUTSIDE the repo, proves the bare tree *cannot* fall back to the
+repo's modules, provisions ONLY the one declared dependency (`js-sha3`), and then proves `demo` and
+the real `--vendor` verify path work from the extracted tree alone — so a file missing from
+`verifier/package.json` `files` fails that suite, not the first stranger's `npx` run.
+
+## Checklist
+
+1. **Gate** (repo root): `npx hardhat test test/verify-vh.pack.test.js` → must be green.
+2. **Inspect the shipment** (from `verifier/`): `cd verifier && npm pack --dry-run` — expect
+   `verify-vh.js`, `lib/*.js`, `README.md`, `package.json`, and nothing else.
+3. **Log in as the human npm account**: `npm whoami` (then `npm login` if needed). The loop holds no
+   npm credentials and must never be given any.
+4. **Publish from `verifier/` — NOT the repo root** (the root package is `verifyhash`, a different
+   surface): `cd verifier && npm publish`. Re-publishing later requires a version bump in
+   `verifier/package.json` first (npm rejects a reused version).
+5. **Post-publish smoke**, from any directory OUTSIDE this repo (a clean machine is even better):
+
+   ```bash
+   npx --yes verify-vh demo
+   ```
+
+   Expect exit `0`; the transcript must ACCEPT the genuine packet naming signer
+   `0x70997970c51812dc3a010c7d01b50e0d17dc79c8` (the fixed TEST-ONLY hardhat #1 key — never a real
+   key), then REJECT the one-byte-tampered copy naming `model-card.md`.
+6. **Hands-on smoke** (optional): `npx --yes verify-vh demo ./vh-demo`, then run the verify / tamper /
+   restore commands it prints.
+7. **If the smoke fails**: `npm deprecate verify-vh@<version> "broken — do not use"`, fix, bump, and
+   re-run this checklist from step 1. Never leave a broken version as `latest`.
+
+## The honest boundary (say no more than this, anywhere the package is announced)
+
+The demo proves tamper-evidence + signer-pin, NOT a trusted timestamp, NOT a legal opinion.
+A verified packet means: the bytes you hold match what the named signer sealed — nothing about
+*when* it was sealed, and nothing about whether the content is true, licensed, or lawful.

package/examples/README.md

@@ -0,0 +1,185 @@
+# verifyhash — runnable examples
+
+Two committed, self-checking, fully-offline examples. Zero setup, one command each.
+
+## `sdk-verify.js` — embed the SDK exactly as an external developer would
+
+```bash
+node examples/sdk-verify.js
+```
+
+This is the **consumer** example: it imports the package **only** through its single public entrypoint,
+`require("verifyhash")` (plus `ethers`, verifyhash's **own** declared dependency, used only to mint an
+**ephemeral throwaway** signing key that stands in for a real, out-of-band vendor key) — **no** deep
+`cli/core/...` reach-in, no network, no third-party non-core dependency, no real key. It runs **two acts**:
+the free-tier tamper-evidence path, and the paid, revenue-relevant **signed + vendor-pinned verify gate**.
+
+**Act 1 — UNSIGNED tamper-evidence (free tier):**
+
+1. **`buildSeal`** — seal an in-memory `{ relPath, bytes }` file set (no directory, no disk).
+2. **`verifySeal`** (untouched bytes) → **ACCEPTED** — the root is re-derived from the bytes you hold.
+3. **`verifySeal`** (one byte flipped) → **REJECTED** — and it prints the per-file **diff** the verdict is
+   built from (which `relPath` changed, expected vs. actual hash).
+4. **`serializeSeal` / `readSeal`** — the canonical, byte-deterministic packet a counterparty can re-read.
+
+**Act 2 — SIGNED + vendor-PINNED verify gate (the paid embed).** This is the integration a downstream
+service pays for: **verify in-process that a packet was signed by _our_ published vendor address**, with
+**no** shell-out to the `vh` binary (STRATEGY.md **P-9** / EPIC-58 — "verified by verifyhash, signed &
+pinned, inside _your_ product").
+
+5. **`signSealWith`** — a publisher signs the seal (ephemeral key here; a real out-of-band key in prod).
+6. **`verifySignedSeal`** pinned to **our** vendor address → **ACCEPTED**.
+7. **`verifySignedSeal`** pinned to a **different** vendor → **REJECTED** — the signature is *genuine*; only
+   the **pin** fails. "Signed by someone, but not by us" must reject; that is the security property a paying
+   integrator's gate enforces (it is **not** tamper-evidence — the bytes are fine).
+8. **`verifySignedSeal`** on a one-byte-tampered signature → **REJECTED** (recovered signer ≠ claimed).
+
+It leads with the standing **trust note** (a seal proves *tamper-evidence*; a valid **signature** proves
+*who vouched* — the pinned address's key-holder — for those bytes; **neither** proves a trusted timestamp
+and **neither** is a legal opinion — timestamping rides the human-owned trust-root, `needs-human`, P-3 in
+[`STRATEGY.md`](../STRATEGY.md)), prints a clear **PASS** summary naming both acts, and exits 0. The only
+key it ever uses is an **ephemeral, in-memory throwaway** (never persisted, funded, or logged). It is
+test-gated by [`test/sdk.example.test.js`](../test/sdk.example.test.js) on every `npx hardhat test` — a grep
+there asserts the example uses **only** the public surface (`require("verifyhash")` + `ethers`, no deep
+`cli/*` import), so the "public API stands alone" claim can never silently rot.
+
+## `verify-service-client.js` — call the `vh serve-verify` HTTP endpoint as a drop-in dependency
+
+```bash
+node examples/verify-service-client.js
+```
+
+The **verify-service client** example: it boots the `vh serve-verify` HTTP endpoint (the *"CI plugin that
+imports rather than shells out"*), then treats it as a drop-in dependency. It **builds** a seal with
+`require("verifyhash")`, **POSTs** a clean seal to the booted service (HTTP **200 ACCEPTED** → prints
+`ACCEPT`), then **POSTs** the same seal with **one byte flipped** (HTTP **422 REJECTED** → prints `REJECT`),
+tears the service down, and exits 0. It imports **only** `require("verifyhash")`, the `vh` **command**
+(spawned from the package's own `bin.vh`), and Node built-ins (`http`, `child_process`, `path`) — **no**
+deep `cli/*` reach-in and **no** third-party dependency. See
+[`docs/VERIFY-SERVICE.md`](../docs/VERIFY-SERVICE.md) for the request/response schema, the status mapping,
+and the trust boundary. It is test-gated by
+[`test/verify-service.example.test.js`](../test/verify-service.example.test.js) on every `npx hardhat test`,
+so it can never silently rot.
+
+## `journal-ci.js` — continuous-integrity CI step (the `vh journal` integrity journal)
+
+```bash
+node examples/journal-ci.js
+```
+
+The **continuous-integrity** example: it treats the `vh journal` **append-only, hash-chained integrity
+journal** as a drop-in CI step. It **builds** a seal with `require("verifyhash")`, writes the sealed bytes +
+packet to a throwaway workdir, then shells out to `vh journal append` **twice** (recording two hash-chained
+verdicts, strictly additively), runs `vh journal verify` (reporting an **unbroken chain**, exit 0), and exits
+0. It imports **only** `require("verifyhash")`, the `vh` **command** (spawned from the package's own `bin.vh`),
+and Node built-ins (`fs`, `os`, `path`, `child_process`) — **no** deep `cli/*` reach-in (not even the pure
+journal core) and **no** third-party dependency. The `ts` on each entry is **self-asserted**, **not** a
+trusted timestamp — the journal never claims *"unaltered since date T"* on its own (STRATEGY.md **P-3**). See
+[`docs/INTEGRITY-JOURNAL.md`](../docs/INTEGRITY-JOURNAL.md) for the schema, the chain guarantee, the 0/3
+contract, and the honesty boundary. It is test-gated by
+[`test/journal.example.test.js`](../test/journal.example.test.js) on every `npx hardhat test`, so it can
+never silently rot.
+
+## `sdk-verify-signed.js` — the SIGNED + vendor-PINNED verify gate, in-process
+
+```bash
+node examples/sdk-verify-signed.js
+```
+
+This is the **buyer's** signed-verify example: it plays a downstream service that **receives** a signed,
+vendor-address-pinned deliverable (a model, a dataset, a build artifact) and clears the **two gates that
+gate a real purchase** — **(a)** *"was this signed by our published vendor address?"* and **(b)** *"are the
+exact files I received **on disk** the ones that vendor signed?"* — **in-process**, with **no** shell-out to
+the `vh` binary. It is the SIGNED twin of `vh evidence verify-signed` (including its `--signer` pin and
+`--dir` binding), byte-identical because it **is** the same code (`index.js` is a thin identity re-export;
+see [`../docs/SDK.md`](../docs/SDK.md)). This is the paid, revenue-relevant embed (STRATEGY.md **P-9** /
+EPIC-58 — "verified by verifyhash, signed & pinned, inside _your_ product").
+
+The verify example imports **only** `require("verifyhash")` and **relative** example files — nothing else,
+**no** `child_process`, **no** built-in (`fs`/`os`/`path`), **no** network, **no** deep `cli/*` reach-in.
+Because a buyer **never signs** and does not do its own disk plumbing, both the publisher-side key handling
+(minting an **ephemeral throwaway** key that stands in for the publisher's real out-of-band key) **and** the
+"receive the deliverable to a throwaway temp dir / corrupt one received file / clean up" plumbing are
+quarantined in [`lib/ephemeral-publisher.js`](./lib/ephemeral-publisher.js) — the only place `ethers`
+(verifyhash's own dependency) and Node built-ins are touched. It runs one **ACCEPT** then **four** REJECT/
+ACCEPT steps that **escalate in value**:
+
+1. **`verifySignedSeal`** pinned to **our** vendor address → **ACCEPTED**.
+2. **`verifySignedSeal`** pinned to a **different** vendor → **REJECTED** — a **wrong-signer** reject: the
+   signature is *genuine* and the bytes are fine; it just recovers to a signer we do **not** pin. "Signed by
+   someone, but not by us" must reject; that is the security property a paying integrator's gate enforces.
+3. **`verifySignedSeal`** on a one-byte-**tampered** signature → **REJECTED** — the recovered signer no
+   longer matches the claimed one, so it rejects even under the correct vendor pin.
+4. **`verifySignedSealAttestation`** — the **strict, on-disk BINDING gate** a paying integrator actually
+   buys — pinned to **our** vendor address **and bound to the actual files received on disk**:
+   - **[4a]** the **untouched** received deliverable → **ACCEPTED** — both gates pass: our vendor signed it
+     **and** the bytes on disk are byte-identical to what was signed (`manifestBindsAttestation=true`).
+   - **[4b]** the received deliverable with **one file corrupted on disk** → **REJECTED** — the vendor
+     signature over the **original** bytes is **still genuine** and the pin **still** matches; only the
+     on-disk bytes drifted, so `manifestBindsAttestation=false`. This is the **real fraud** the buyer cares
+     about — a **genuine our-vendor signature attached to a substituted download** — and it is the case the
+     signature-only path (1–3) **cannot** catch. The on-disk binding does.
+
+It leads with the standing **trust note** (a valid **signature** proves *who vouched* — the pinned address's
+key-holder — for those exact sealed bytes; it does **not** prove a trusted timestamp and is **not** a legal
+opinion — timestamping rides the human-owned trust-root, `needs-human`, P-3 in
+[`../STRATEGY.md`](../STRATEGY.md)), prints a clear **PASS** summary, and exits 0. The received deliverable
+is written to a **throwaway OS temp dir** (never the repo tree) and cleaned up in a `finally`. Verification
+is **offline and key-free**: it recovers a **public** address from the signature, holds no private key, and
+contacts nothing. It is test-gated by [`test/sdk.example.signed.test.js`](../test/sdk.example.signed.test.js)
+on every `npx hardhat test` — a grep there asserts the example imports **only** `require("verifyhash")` +
+relative files, with **no** deep `cli/*` import, **no** `child_process`, **no** built-in, and **no** network,
+and a snapshot check asserts it leaves no temp dir in the repo — so the "in-process public verify stands
+alone" claim can never silently rot.
+
+## `run.js` — the end-to-end DataLedger + ProofParcel buyer pipeline
+
+One command, zero setup, fully offline:
+
+```bash
+node examples/run.js
+```
+
+This drives the **real** DataLedger + ProofParcel buyer pipeline against the tiny committed sample data
+in this directory, using the **same module entrypoints the `vh` CLI dispatches to** (`cli/dataset.js`,
+`cli/parcel.js`) — it is not a brittle shell pipeline of string parsing. It prints a clear **PASS/FAIL**
+summary with the produced artifact paths.
+
+## What it runs
+
+- **DataLedger:** `dataset build` → `check --policy` (a PASS against a lenient policy **and** a FAIL
+  against a strict one) → `verify` (a MATCH against the untouched sample **and** a MISMATCH after a
+  one-byte tamper) → `report` (one filed evidence document) → `attest` (the canonical UNSIGNED bytes).
+- **ProofParcel:** `parcel build` → `verify` (MATCH **and** a tamper MISMATCH) → `attest`.
+
+The sample contains **deliberate** problems so the gates have something real to catch:
+
+- `vendored/gpl-snippet.txt` carries a `GPL-3.0` license hint → flagged by `denyLicenses`.
+- `data/unlabeled.txt` carries no license hint → flagged by `requireLicense`.
+
+## Where it writes
+
+The committed sample under `examples/` is **read-only** to the script. Everything it produces (manifests,
+the report, the unsigned attestation bytes, and the working copies it deliberately tampers) goes to a
+fresh **OS temp dir**. Override the location with `VH_EXAMPLE_OUT=/some/path`; keep the artifacts for
+inspection with `VH_EXAMPLE_KEEP=1`. **Nothing is ever scattered into the repo working tree.**
+
+## Trust posture (read this — the script will not let you forget it)
+
+The example proves **tamper-evidence** (any edit, rename, add, or remove flips the Merkle root) and emits
+the canonical **UNSIGNED** attestation bytes a trust-root would sign. It does **not**, and cannot, prove
+*"unaltered since date T"*: that standing claim rides the **human-owned** signing / timestamp / anchor
+trust-root (`needs-human`, P-3 in [`STRATEGY.md`](../STRATEGY.md)). The script **references but never
+executes** those `sign` / `timestamp` / anchor steps, and says exactly where the human handoff is. See
+[`docs/TRUST-BOUNDARIES.md`](../docs/TRUST-BOUNDARIES.md), [`docs/DATALEDGER.md`](../docs/DATALEDGER.md),
+and [`docs/PROOFPARCEL.md`](../docs/PROOFPARCEL.md).
+
+## It cannot rot
+
+`test/cli.examples.test.js` runs this example end-to-end against the committed sample on every
+`npx hardhat test`, asserting the pipeline completes, the policy violation is flagged, the tamper is
+caught, and the run leaves the working tree clean.
+
+
+---
+<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/examples/policy.lenient.json

@@ -0,0 +1,5 @@
+{
+  "kind": "verifyhash.dataset-policy",
+  "schemaVersion": 1,
+  "denyLicenses": ["AGPL-3.0"]
+}

package/examples/policy.strict.json

@@ -0,0 +1,6 @@
+{
+  "kind": "verifyhash.dataset-policy",
+  "schemaVersion": 1,
+  "denyLicenses": ["GPL-3.0", "AGPL-3.0"],
+  "requireLicense": true
+}

package/examples/run.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+"use strict";
+
+// =================================================================================================
+// verifyhash — runnable, self-checking, OFFLINE end-to-end EXAMPLE (T-21.2)
+//
+// WHAT THIS IS
+//   A single script a buyer/evaluator (and CI) can run with ZERO setup — no key, no TSA, no RPC, no
+//   network — to watch the real DataLedger + ProofParcel buyer pipeline work against the committed
+//   sample data in examples/. It reuses the EXACT module entrypoints the `vh` CLI dispatches to
+//   (cli/dataset.js, cli/parcel.js) — it is NOT a brittle shell pipeline of string parsing.
+//
+//   DataLedger : dataset build -> check --policy (PASS + FAIL) -> verify (MATCH + TAMPER) -> report -> attest
+//   ProofParcel: parcel  build -> verify (MATCH + TAMPER) -> attest
+//
+// FILESYSTEM HYGIENE (load-bearing)
+//   The committed sample data under examples/ is READ-ONLY here. Everything this script produces —
+//   manifests, the report, the unsigned attestation bytes, and the working copies it deliberately
+//   tampers — is written to a fresh OS temp workspace (or VH_EXAMPLE_OUT if you set it). NOTHING is
+//   ever scattered into the repo working tree. Set VH_EXAMPLE_KEEP=1 to keep the temp dir for inspection.
+//
+// TRUST POSTURE (read this; the script will not let you forget it)
+//   This example demonstrates TAMPER-EVIDENCE (any edit/rename/add/remove flips the Merkle root) and
+//   emits the canonical UNSIGNED attestation bytes a human trust-root would sign. It does NOT, and
+//   cannot, prove "unaltered since date T": that standing claim rides the HUMAN-OWNED signing/timestamp/
+//   anchor trust-root (needs-human, P-3 in STRATEGY.md). This script references — but never executes —
+//   those `sign` / `timestamp` / anchor steps, and says exactly where the human handoff is.
+// =================================================================================================
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const dataset = require("../cli/dataset");
+const parcel = require("../cli/parcel");
+
+const EX_DIR = __dirname;
+const SAMPLE_DATASET = path.join(EX_DIR, "sample-dataset");
+const SAMPLE_DATASET_HINTS = path.join(EX_DIR, "sample-dataset.hints.json");
+const POLICY_LENIENT = path.join(EX_DIR, "policy.lenient.json");
+const POLICY_STRICT = path.join(EX_DIR, "policy.strict.json");
+const SAMPLE_PARCEL = path.join(EX_DIR, "sample-parcel");
+
+// ---- tiny output + check helpers -----------------------------------------------------------------
+
+const out = (s) => process.stdout.write(s + "\n");
+const hr = () => out("-".repeat(88));
+
+const checks = []; // { ok, label } — the script's verdict is the AND of every one of these.
+function check(label, ok, detail) {
+  checks.push({ ok: !!ok, label });
+  out(`  [${ok ? "PASS" : "FAIL"}] ${label}${detail ? "  — " + detail : ""}`);
+}
+
+// Recursively copy a directory tree (the sample is tiny). Used so the TAMPER step mutates a working
+// COPY in the temp workspace, never the committed sample under examples/.
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+// A stdout sink that swallows the command's own human output — the example prints its OWN narration so
+// the PASS/FAIL summary stays readable. (The commands still run for real; we just don't echo their block.)
+const quiet = () => {};
+
+// =================================================================================================
+
+function main() {
+  // LEAD with the standing trust note so the example can never overclaim.
+  hr();
+  out("verifyhash — OFFLINE end-to-end example (DataLedger + ProofParcel)");
+  hr();
+  out("TRUST NOTE (DataLedger): " + dataset.TRUST_NOTE);
+  out("TRUST NOTE (ProofParcel): " + parcel.TRUST_NOTE);
+  out("");
+  out("This example proves TAMPER-EVIDENCE and emits the canonical UNSIGNED attestation bytes.");
+  out('It does NOT prove "unaltered since date T" — that rides the HUMAN-OWNED signing/timestamp/');
+  out("anchor trust-root (needs-human, P-3). Those steps are referenced below but NEVER executed.");
+  hr();
+
+  // Fresh, isolated output workspace. Default: an OS temp dir; override via VH_EXAMPLE_OUT.
+  const work =
+    process.env.VH_EXAMPLE_OUT && process.env.VH_EXAMPLE_OUT.trim()
+      ? path.resolve(process.env.VH_EXAMPLE_OUT.trim())
+      : fs.mkdtempSync(path.join(os.tmpdir(), "vh-example-"));
+  fs.mkdirSync(work, { recursive: true });
+  out(`output workspace (gitignored / OS temp — never the repo): ${work}`);
+  out("");
+
+  const artifacts = {};
+
+  // ===============================================================================================
+  // PART 1 — DataLedger: the AI training-data provenance pipeline.
+  // ===============================================================================================
+  out("== DataLedger ==");
+
+  const dsManifest = path.join(work, "dataset.manifest.json");
+  const hints = JSON.parse(fs.readFileSync(SAMPLE_DATASET_HINTS, "utf8"));
+
+  // build — tamper-evident manifest (Merkle root + per-file leaves) with the UNTRUSTED hints attached.
+  const dsBuild = dataset.runDatasetBuild({
+    dir: SAMPLE_DATASET,
+    out: dsManifest,
+    hints,
+    stdout: quiet,
+  });
+  artifacts.datasetManifest = dsManifest;
+  check(
+    "dataset build produced a manifest with a Merkle root over every file",
+    /^0x[0-9a-fA-F]{64}$/.test(dsBuild.root) && dsBuild.fileCount === 5,
+    `root=${dsBuild.root.slice(0, 14)}… files=${dsBuild.fileCount}`
+  );
+
+  // check --policy (LENIENT) — the org-policy gate should PASS (CI exit 0).
+  const lenient = dataset.runDatasetCheck({
+    manifest: dsManifest,
+    policy: POLICY_LENIENT,
+    stdout: quiet,
+  });
+  check(
+    "dataset check --policy (lenient) PASSes  → CLI exit 0",
+    lenient.verdict === "PASS",
+    `verdict=${lenient.verdict}`
+  );
+
+  // check --policy (STRICT) — the DELIBERATE violations in the sample (a GPL-3.0 file + a file with no
+  // license hint under requireLicense) must be FLAGGED (CI exit 3). This is the core "the gate works" proof.
+  const strict = dataset.runDatasetCheck({
+    manifest: dsManifest,
+    policy: POLICY_STRICT,
+    stdout: quiet,
+  });
+  const flaggedGpl = strict.violations.some(
+    (v) => v.rule === "denyLicenses" && v.value === "GPL-3.0"
+  );
+  const flaggedMissing = strict.violations.some((v) => v.rule === "requireLicense");
+  check(
+    "dataset check --policy (strict) FLAGS the deliberate violations → CLI exit 3",
+    strict.verdict === "FAIL" && flaggedGpl && flaggedMissing,
+    `verdict=${strict.verdict} violations=${strict.violations.length} (GPL-3.0 + missing-license)`
+  );
+
+  // verify (MATCH) — re-derive the root from the UNTOUCHED committed sample; must MATCH (CI exit 0).
+  const dsVerifyOk = dataset.runDatasetVerify({
+    dir: SAMPLE_DATASET,
+    manifest: dsManifest,
+    stdout: quiet,
+  });
+  check(
+    "dataset verify against the untouched sample → MATCH (CLI exit 0)",
+    dsVerifyOk.status === "MATCH",
+    `status=${dsVerifyOk.status}`
+  );
+
+  // verify (TAMPER) — copy the sample, mutate ONE file, and confirm verify catches it as MISMATCH and
+  // localizes the CHANGED file. The mutation happens on the temp COPY, never the committed sample.
+  const dsTamperDir = path.join(work, "tampered-dataset");
+  copyDir(SAMPLE_DATASET, dsTamperDir);
+  const tamperedFile = path.join(dsTamperDir, "corpus", "mit-notes.txt");
+  fs.appendFileSync(tamperedFile, "\nTAMPER: one extra byte changes the file's bytes.\n");
+  const dsVerifyTamper = dataset.runDatasetVerify({
+    dir: dsTamperDir,
+    manifest: dsManifest,
+    stdout: quiet,
+  });
+  const caughtChanged = dsVerifyTamper.diff.changed.some(
+    (c) => c.path === "corpus/mit-notes.txt"
+  );
+  check(
+    "dataset verify catches a one-byte TAMPER → MISMATCH, localized to the CHANGED file (CLI exit 3)",
+    dsVerifyTamper.status === "MISMATCH" && caughtChanged,
+    `status=${dsVerifyTamper.status} changed=[${dsVerifyTamper.diff.changed
+      .map((c) => c.path)
+      .join(", ")}]`
+  );
+
+  // report — ONE filed evidence document (identity + license roll-up + embedded verify + policy verdict).
+  // Run with BOTH gates against the strict policy: the report is the combined CI gate and reports FAIL.
+  const dsReport = path.join(work, "dataset.evidence.md");
+  const reportRes = dataset.runDatasetReport({
+    manifest: dsManifest,
+    verifyDir: SAMPLE_DATASET,
+    policy: POLICY_STRICT,
+    out: dsReport,
+    stdout: quiet,
+  });
+  artifacts.datasetReport = dsReport;
+  check(
+    "dataset report wrote ONE evidence document (verify=MATCH embedded, policy=FAIL embedded)",
+    fs.existsSync(dsReport) &&
+      reportRes.verifyStatus === "MATCH" &&
+      reportRes.policyVerdict === "FAIL",
+    `verify=${reportRes.verifyStatus} policy=${reportRes.policyVerdict}`
+  );
+
+  // attest — emit the canonical UNSIGNED attestation bytes the human trust-root would sign.
+  const dsAttest = path.join(work, "dataset.attestation.json");
+  const attestRes = dataset.runDatasetAttest({
+    manifest: dsManifest,
+    out: dsAttest,
+    stdout: quiet,
+  });
+  artifacts.datasetAttestation = dsAttest;
+  check(
+    "dataset attest emitted canonical UNSIGNED bytes (signed:false) for the human trust-root to sign",
+    fs.existsSync(dsAttest) &&
+      attestRes.envelope.signed === false &&
+      typeof attestRes.canonical === "string" &&
+      attestRes.canonical.length > 0,
+    `signed=${attestRes.envelope.signed}`
+  );
+
+  out("");
+
+  // ===============================================================================================
+  // PART 2 — ProofParcel: the B2B data-delivery receipt pipeline.
+  // ===============================================================================================
+  out("== ProofParcel ==");
+
+  const pManifest = path.join(work, "parcel.manifest.json");
+
+  // build — tamper-evident delivery receipt (root + per-file leaves + UNTRUSTED parcel metadata).
+  const pBuild = parcel.runParcelBuild({
+    dir: SAMPLE_PARCEL,
+    out: pManifest,
+    parcel: {
+      parcelId: "EX-0001",
+      sender: "acme-data-co",
+      recipient: "globex-ml",
+    },
+    stdout: quiet,
+  });
+  artifacts.parcelManifest = pManifest;
+  check(
+    "parcel build produced a delivery receipt with a Merkle root over every delivered file",
+    /^0x[0-9a-fA-F]{64}$/.test(pBuild.root) && pBuild.fileCount === 3,
+    `root=${pBuild.root.slice(0, 14)}… files=${pBuild.fileCount}`
+  );
+
+  // verify (MATCH) — the recipient re-derives the root from the delivered bytes; must MATCH (CI exit 0).
+  const pVerifyOk = parcel.runParcelVerify({
+    dir: SAMPLE_PARCEL,
+    manifest: pManifest,
+    stdout: quiet,
+  });
+  check(
+    "parcel verify against the delivered files → MATCH (CLI exit 0)",
+    pVerifyOk.status === "MATCH",
+    `status=${pVerifyOk.status}`
+  );
+
+  // verify (TAMPER) — mutate ONE delivered file on a temp copy; verify must catch it as MISMATCH.
+  const pTamperDir = path.join(work, "tampered-parcel");
+  copyDir(SAMPLE_PARCEL, pTamperDir);
+  fs.appendFileSync(path.join(pTamperDir, "data", "records.csv"), "4,delta,400\n");
+  const pVerifyTamper = parcel.runParcelVerify({
+    dir: pTamperDir,
+    manifest: pManifest,
+    stdout: quiet,
+  });
+  const pCaughtChanged = pVerifyTamper.diff.changed.some((c) => c.path === "data/records.csv");
+  check(
+    "parcel verify catches a TAMPER → MISMATCH, localized to the CHANGED file (CLI exit 3)",
+    pVerifyTamper.status === "MISMATCH" && pCaughtChanged,
+    `status=${pVerifyTamper.status} changed=[${pVerifyTamper.diff.changed
+      .map((c) => c.path)
+      .join(", ")}]`
+  );
+
+  // attest — emit the canonical UNSIGNED parcel-attestation bytes the human trust-root would sign.
+  const pAttest = path.join(work, "parcel.attestation.json");
+  const pAttestRes = parcel.runParcelAttest({
+    manifest: pManifest,
+    out: pAttest,
+    stdout: quiet,
+  });
+  artifacts.parcelAttestation = pAttest;
+  check(
+    "parcel attest emitted canonical UNSIGNED bytes (signed:false) for the human trust-root to sign",
+    fs.existsSync(pAttest) &&
+      pAttestRes.envelope.signed === false &&
+      typeof pAttestRes.canonical === "string" &&
+      pAttestRes.canonical.length > 0,
+    `signed=${pAttestRes.envelope.signed}`
+  );
+
+  // ===============================================================================================
+  // Summary + the human-gated trust-root handoff (referenced, NOT executed).
+  // ===============================================================================================
+  out("");
+  hr();
+  out("Produced artifacts (all under the temp workspace — none in the repo):");
+  for (const [k, v] of Object.entries(artifacts)) out(`  ${k}: ${v}`);
+  out("");
+  out("NEXT — the HUMAN-OWNED trust-root steps (NOT run here; they need a key / a TSA / an RPC):");
+  out(
+    "  vh dataset sign " +
+      dsAttest +
+      " --key-file <YOUR-KEY>        # sign the UNSIGNED bytes with a key YOU provisioned"
+  );
+  out(
+    "  vh dataset timestamp-request " +
+      dsManifest +
+      "                  # then stamp the digest at an RFC-3161 TSA"
+  );
+  out(
+    "  vh parcel  sign " +
+      pAttest +
+      " --key-file <YOUR-KEY>         # same handoff for the parcel attestation"
+  );
+  out(
+    "  (on-chain anchor is a deploy + real funds — also needs-human, P-2 in STRATEGY.md)"
+  );
+  out(
+    '  These convert "the bytes are these" into "signed/stamped by a trusted party at time T". The'
+  );
+  out("  example deliberately stops at the unsigned bytes — that boundary is the product's honesty line.");
+  hr();
+
+  const failed = checks.filter((c) => !c.ok);
+  if (failed.length === 0) {
+    out(`RESULT: PASS — all ${checks.length} pipeline checks passed.`);
+  } else {
+    out(`RESULT: FAIL — ${failed.length} of ${checks.length} checks failed:`);
+    for (const c of failed) out(`  - ${c.label}`);
+  }
+
+  return {
+    code: failed.length === 0 ? 0 : 1,
+    work,
+    artifacts,
+    checks: checks.slice(),
+    // A temp workspace is OURS to delete on success; a caller-chosen VH_EXAMPLE_OUT is theirs to keep.
+    ownsWorkspace: !(process.env.VH_EXAMPLE_OUT && process.env.VH_EXAMPLE_OUT.trim()),
+  };
+}
+
+// Run, then clean up the temp workspace (unless the caller asked to keep it or chose their own --out).
+if (require.main === module) {
+  let result;
+  try {
+    result = main();
+  } catch (e) {
+    process.stderr.write("example crashed: " + (e && e.stack ? e.stack : e) + "\n");
+    process.exit(1);
+    return;
+  }
+  const keep = process.env.VH_EXAMPLE_KEEP === "1";
+  if (result.work && result.ownsWorkspace && !keep) {
+    try {
+      fs.rmSync(result.work, { recursive: true, force: true });
+    } catch {
+      /* best-effort cleanup; never fail the example over it */
+    }
+  } else if (result.work) {
+    out(`(kept workspace: ${result.work})`);
+  }
+  process.exit(result.code);
+}
+
+module.exports = { main };

package/examples/sample-dataset/README.txt

@@ -0,0 +1,10 @@
+Sample training dataset for the verifyhash / DataLedger end-to-end example.
+
+This directory stands in for a real AI training dataset. It is intentionally tiny
+(a handful of small text files, no secrets, no large blobs) so the example runs in
+well under a second and the whole pipeline is auditable by eye.
+
+The per-file source/license hints live in ../sample-dataset.hints.json. Those hints
+are UNTRUSTED, self-asserted metadata: they are NOT bound into the Merkle root and
+prove nothing on their own. The example's policy check is a gate on those CLAIMS,
+not a verification that any license is genuinely correct.

package/examples/sample-dataset/corpus/cc-by-poem.txt

@@ -0,0 +1,8 @@
+A short CC-BY-4.0 poem in the sample corpus.
+
+  Hash the bytes, fold the tree,
+  one root proves identity;
+  change one byte and you will see
+  the whole root shift — tamper-free.
+
+Its license hint ("CC-BY-4.0") is a self-asserted CLAIM, not a verified fact.

package/examples/sample-dataset/corpus/mit-notes.txt

@@ -0,0 +1,4 @@
+An MIT-licensed text file in the sample corpus.
+
+The MIT license is permissive; an org policy that forbids copyleft would allow this
+file. Its license hint ("MIT") is recorded in sample-dataset.hints.json as a CLAIM.

package/examples/sample-dataset/data/unlabeled.txt

@@ -0,0 +1,5 @@
+A data file with NO license hint at all.
+
+This file exists ON PURPOSE so the example's strict policy (which sets
+requireLicense: true) has a second, different violation to flag: a file that asserts
+no license is reported as "(no license hint)".

package/examples/sample-dataset/vendored/gpl-snippet.txt

@@ -0,0 +1,5 @@
+A vendored snippet whose license hint is GPL-3.0.
+
+This file exists ON PURPOSE so the example's strict policy (which denies copyleft
+licenses) has a real violation to flag. A proprietary-product org policy that lists
+GPL-3.0 in denyLicenses will FAIL the dataset on this file.

package/examples/sample-dataset.hints.json

@@ -0,0 +1,7 @@
+{
+  "README.txt": { "source": "verifyhash-examples", "license": "MIT" },
+  "corpus/mit-notes.txt": { "source": "verifyhash-examples", "license": "MIT" },
+  "corpus/cc-by-poem.txt": { "source": "verifyhash-examples", "license": "CC-BY-4.0" },
+  "vendored/gpl-snippet.txt": { "source": "third-party-vendor", "license": "GPL-3.0" },
+  "data/unlabeled.txt": { "source": "verifyhash-examples" }
+}