verifyhash 0.1.0

package/docs/ADOPT.md

@@ -0,0 +1,183 @@
+# Adopt verifyhash in one line
+
+You do **not** need an account, a license, a sales call, or our `ethers`/`hardhat` toolchain to start.
+Pick the row that matches where you are, copy the one line, and run it. The **free** rows below are
+**offline** and need at most **Node.js >= 18** — no account, no key, no network.
+
+| You want to… | Copy this one line | Price |
+|---|---|---|
+| **No Node/terminal at all? Verify in your browser** (the 60-second challenge built in) | open [`verifier/dist/verify-vh-standalone.html`](../verifier/dist/verify-vh-standalone.html) | free |
+| **See it work in 5 seconds** (no clone, no flags, no key) | `npx --yes verify-vh demo` | free |
+| **Gate your CI on tampered/forged seals** (GitHub Actions) | `uses: <owner>/<repo>/verifier/action@<ref>` | free |
+| **Issue signed, customer-verifiable seals of your own** (the paid producer surface) | `vh evidence seal <dir> --sign --license <f> --vendor 0xYOU` | **paid** |
+
+The on-ramp is **deliberately one direction**: the free rows convince you the verdict is real, then the
+paid row is the **only** part that turns into revenue — and the line below it (price, key, the sale) is a
+**human** step, never the loop's. Each path is detailed below.
+
+---
+
+## 0. The no-terminal path — one offline page in your browser
+
+The browser row needs **no Node, no terminal, no install, no account**: save the ONE committed file
+[`verifier/dist/verify-vh-standalone.html`](../verifier/dist/verify-vh-standalone.html) and double-click
+it. The page opens with the **60-second challenge built in** — click **"Load the sample packet &
+verify"** (**ACCEPT**), change one character of the editable sample file on the page and re-verify
+(**REJECT**, naming the file you changed) — then drag a REAL sealed packet + its files in for the same
+verdict the CLI prints. It contains **no network API at all**, so your bytes never leave your machine —
+check the browser **devtools Network tab**: it stays empty. Honest scope, same as every row here:
+tamper-evidence (+ signer-pin for a signed seal), NOT a trusted "sealed at T"; for CI/production gating
+use the node standalone (`verify-vh-standalone.js`) — that is row two and §2 below. The guided walkthrough
+is [`challenge/README.md`](../challenge/README.md).
+
+---
+
+## 1. The 5-second proof — `npx --yes verify-vh demo`
+
+Run, with nothing checked out at all:
+
+```bash
+npx --yes verify-vh demo
+```
+
+It downloads the **standalone, offline** `verify-vh` verifier (one runtime dependency, `js-sha3` — **no**
+ethers, **no** hardhat, **no** network), ships a tiny **genuinely-signed** evidence packet baked into the
+file, plays it through the **exact same verify path** every real check uses, and prints the honest verdict:
+a genuine packet is **ACCEPTED and its signer named**, then a one-byte change is **REJECTED**. No flags, no
+`--vendor` to paste, no key knowledge. It writes only a throwaway temp dir it deletes, opens **no network**,
+and exits `0`.
+
+> The `verify-vh` package's `bin` is `verify-vh`, and `demo` is a real subcommand of
+> [`verifier/verify-vh.js`](../verifier/verify-vh.js) — a test runs the literal command above so this line
+> can never drift from the tool.
+
+Want a copy you can tamper with by hand? Add a directory and the demo writes the same signed packet there,
+then prints the exact verify / tamper / restore commands:
+
+```bash
+npx --yes verify-vh demo ./vh-demo
+```
+
+When it clicks, point the tool at a **real** packet you were handed:
+
+```bash
+npx --yes verify-vh <packet> --vendor 0xPRODUCER_ADDRESS   # exit 0 = ACCEPT; 3 = REJECT
+```
+
+Prefer no `npx`? The same verifier is a single self-contained file you can save and run with bare `node` —
+see [`verifier/README.md`](../verifier/README.md).
+
+---
+
+## 2. Gate your CI in one line — `uses: <owner>/<repo>/verifier/action@<ref>`
+
+Drop this workflow at `.github/workflows/verify-vh.yml` in the repo that **receives** sealed verifyhash
+artifacts. Every push / pull request then fails the build the instant any artifact is tampered, forged, or
+signed by the wrong key — blocking the merge:
+
+```yaml
+# .github/workflows/verify-vh.yml
+name: verify-vh merge gate
+on: [push, pull_request]
+jobs:
+  verify-vh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: <owner>/<repo>/verifier/action@<ref>
+        with:
+          vendor: "0xYOUR_PRODUCER_SIGNER_ADDRESS"   # the key that must have signed (omit to check tamper only)
+          manifest: "release.manifest"               # OR set `artifacts:` instead
+```
+
+Replace `<owner>/<repo>` with this repository's slug and `<ref>` with a tag or commit SHA you trust (pin a
+SHA for supply-chain safety). The composite action installs **only** the standalone verifier (`js-sha3`) and
+resolves its bundled `verifier/` tree via `${{ github.action_path }}` at run time — so you do **not** vendor
+`verifier/` into your repo. The action lives at [`verifier/action/`](../verifier/action/action.yml); its full
+input table and exit-code contract are in [`verifier/action/README.md`](../verifier/action/README.md).
+
+> ⚠️ **Pin `vendor:` for any SIGNED release.** A signed artifact gated **without** `vendor:` is accepted as
+> long as its signature recovers to the signer the packet **self-asserts** — so an attacker who re-signs a
+> tampered release with **their own key** passes the gate. Leave `vendor:` empty **only** for genuinely
+> unsigned evidence seals (where there is no signer to pin).
+
+---
+
+## 3. Turn "it works" into revenue — the free→paid bridge
+
+The two lines above cost nothing and stay free forever. They exist to get a prospect to one thought:
+*"the verdict is real, and I want to hand my OWN signed seals to MY customers."* That is the line that
+becomes a paying relationship — and it is the **only** part of this funnel that does.
+
+**What is free vs. paid (no surprises).** The free surface is everything a *recipient* needs: `verify-vh`,
+the CI gate, and the producer CLI's baseline verbs — an **unsigned** evidence seal of up to **25 files**
+and offline verify. The **paid** surface is what a *producer who sells trust* needs: a **`--sign`** wrap
+(a signed attestation your customers pin to YOUR published key) and sealing **more than 25 files**. Those
+two are gated by a signed, offline-verifiable entitlement and refuse — never silently downgrade — without
+one.
+
+**The whole loop, end to end.** A customer pays you out-of-band. Your billing webhook (after it
+authenticates the provider's own signature) runs ONE command to mint that customer a license against a
+plan in the catalog:
+
+```bash
+# You, the producer, mint a per-sale entitlement with a key YOU provisioned outside this loop:
+vh evidence license fulfill --plan evidence-pro-annual --customer "Acme Co" \
+    --key-env EVIDENCE_VENDOR_KEY --out ./acme.vhevidence-license.json
+```
+
+`evidence-pro-annual` is a **real** plan in the bundled DRAFT catalog (`cli/core/fixtures/evidence-plans/baseline.json`);
+`fulfill` copies that plan's entitlements **verbatim** and signs them — the loop **sets no price** and
+**holds no key**. The customer then unlocks the paid surface OFFLINE, pinning your **published** address —
+no per-sale terminal step for you:
+
+```bash
+# Your paying customer runs the PAID producer surface, gated by the license you minted:
+vh evidence seal <dir> --sign --license <f> --vendor 0xYOU
+```
+
+> The **needs-human** line, on purpose: the **price** on each plan, the **vendor signing key**, and the
+> actual **sale/subscription agreement** are all human steps (the loop builds and tests the mechanism but
+> sets no price, holds no key, and takes no payment). Revenue comes from **delivering this software value
+> to a paying customer** — never from issuing a token, a coin, or any tradeable/appreciating asset; an
+> entitlement is an **access description for delivered value**, not a security. Full schema, the closed
+> entitlement table, and the worked webhook→fulfill→deliver flow are in [`docs/EVIDENCE.md`](EVIDENCE.md).
+
+---
+
+## What a green result actually proves (the honest boundary)
+
+Whether you run `npx --yes verify-vh demo` or the CI gate, the seal proves **tamper-evidence + signer-pin**,
+NOT a trusted "sealed at T" and NOT a legal opinion — it attests *this key vouched for exactly these bytes*,
+re-derived from the bytes you hold, offline, with no producer stack. The trusted-timestamp claim ("sealed at
+time T") is a separate, human-gated step (see
+[`docs/INDEPENDENT-VERIFICATION.md`](INDEPENDENT-VERIFICATION.md)).
+
+---
+
+## Where to go next
+
+- [`verifier/README.md`](../verifier/README.md) — the full independent-verifier guide (zero-install bundle,
+  reproduce-from-source, the conformance corpus).
+- [`docs/INDEPENDENT-VERIFICATION.md`](INDEPENDENT-VERIFICATION.md) — the counterparty-facing spec: exactly
+  what a seal proves and what it does not.
+- [`verifier/action/README.md`](../verifier/action/README.md) — the GitHub Action's inputs, exit codes, and
+  the no-drift source-of-truth guarantee.
+- [`docs/EVIDENCE.md`](EVIDENCE.md) — the **paid** producer surface: the signed evidence packet schema, the
+  free-vs-paid line, the closed entitlement table, and the worked **webhook → `license fulfill` → deliver**
+  flow that turns an adopter into a paying customer.
+- [`docs/AGENTTRACE.md`](AGENTTRACE.md) — sealing **AI-agent session logs** (`vh agent`, `*.vhagent.json`):
+  tamper-evident, selectively-redactable session records the same free `verify-vh` paths on this page
+  verify. Adoption is a ~20-line mapping over the transcript you already have — the committed example is
+  [`examples/agent-session/`](../examples/agent-session/) (map → seal → redact → verify → prove). A session
+  can also be BOUND to a git commit (`vh agent commit-claim` / `verify-commit`, free + key-less;
+  containment, not causation — the auditor re-derives the oid + tracked-set root from their OWN clone):
+  see *Binding a session to a git commit* in [`AGENTTRACE.md`](AGENTTRACE.md) and the scripted flow
+  [`examples/agent-session/commit-bound-session.js`](../examples/agent-session/commit-bound-session.js).
+- [`docs/TRUSTLEDGER.md`](TRUSTLEDGER.md) › *Zero-install: the offline app* — the TrustLedger pilot path with
+  **zero** install: email ONE file ([`trustledger/dist/trustledger-standalone.html`](../trustledger/dist/trustledger-standalone.html)),
+  the partner double-clicks it, drags their real exports in, and the page makes **no network request** (free tier only).
+
+
+---
+<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/ADOPTION.json

@@ -0,0 +1,11 @@
+{
+  "_doc": "The loop's EXTERNAL adoption signal (audit 2026-07-03: 'the loop cannot fail its own test because its test has no market term'). Updated by the human (or future analytics). The Strategist/panel MUST read this and weigh it: novelty with zero adoption scores LOW; no new vertical/epic while every number here is zero.",
+  "updatedAt": "2026-07-03T04:35:00Z",
+  "distinctExternalUsers7d": 0,
+  "npmPublished": false,
+  "npmDownloads7d": null,
+  "pilotsActive": 0,
+  "buyerConversations": 0,
+  "revenueUsdTotal": 0,
+  "notes": "Live surfaces: verifyhash.com (site + zero-install verifier), Polygon-mainnet registry 0x77d8eF881D5aeEda64788968D13f9146fE1A609B. Nothing measured yet."
+}

package/docs/AGENTTRACE.md

@@ -0,0 +1,247 @@
+# AgentTrace — tamper-evident, selectively-redactable agent-session evidence (`vh agent`)
+
+AgentTrace turns an **ordered log of AI-agent session events** — prompts, completions, tool calls,
+tool results, notes — into **one** tamper-evident, selectively-redactable, independently-verifiable
+packet: `*.vhagent.json`. It is the agent-evidence vertical on the same provenance core as every other
+verifyhash product, for the buyer who has to *keep* and *show* agent records (compliance/record-keeping,
+incident forensics, audit, disputes) and cannot rely on operator-editable observability traces.
+
+This page is the buyer-facing spec: exactly what a packet **proves**, what it does **not** prove, what
+is **free vs. paid**, **where a counterparty independently verifies** it, and a committed, test-gated
+**worked example** showing that adoption is a ~20-line mapping over the log you already have.
+
+---
+
+## What a `*.vhagent.json` packet PROVES
+
+The packet carries an RFC-6962-style ordered Merkle `head` `{ size, root }` over **redaction-safe**
+per-event leaves (each event's payload participates only via its keccak-256 hash commitment). From
+that, `vh agent verify` — and the independent verifier, which shares no code with the producer stack —
+re-derive everything from the bytes you hold. A green verdict proves, offline:
+
+1. **The log is unaltered since it was sealed.** Every event leaf and the root re-derive from the
+   events in the packet; editing, reordering, inserting, or dropping any event is a REJECT that names
+   the first offending event `seq`.
+2. **Any disclosed event is verbatim as recorded.** A full event's payload hash commitment is
+   recomputed from the payload bytes — a one-byte payload edit is a REJECT naming the seq. A
+   single-event disclosure (`vh agent prove` → `verify-proof`) binds the event to its exact position
+   under the head, so a quoted transcript line can be checked without the rest of the session.
+3. **Append-only growth between a checkpoint and the final head.** `vh agent checkpoint` commits the
+   session so far; `vh agent verify-growth` proves a later packet extends that checkpoint append-only —
+   a rewritten, reordered, dropped, or inserted past is a REJECT. That is the anti-retroactive-edit
+   property: the operator cannot quietly rewrite history between checkpoints.
+4. **Redaction can only withhold — it can never silently alter.** `vh agent redact` withholds chosen
+   payloads behind their hash commitments; leaves and root are UNCHANGED, so the redacted copy still
+   verifies (and one head signature stays valid across every redacted copy). A **forged** commitment on
+   a redacted event is a REJECT naming the seq. What you cannot see is *declared* withheld — never
+   silently substituted.
+
+## What it does NOT prove (read this before relying on a packet)
+
+- **It does NOT prove the log faithfully records what the agent ACTUALLY did — garbage-in is out of
+  scope.** The head proves the LOG is intact and append-only since seal. If the software that wrote the
+  log lied, omitted events, or was compromised *before sealing*, the packet faithfully preserves that
+  lie. Sealing early (checkpoint as the session runs) narrows this window; it never closes it.
+- **Event `ts` fields are self-asserted metadata.** They are recorded and bound verbatim, never
+  verified against any clock. Order is proven by tree position (`seq`), not by `ts`.
+- **NOT a trusted timestamp.** There is no "this session existed at time T" claim without the
+  human-owned **P-3** trust-root ([`STRATEGY.md`](../STRATEGY.md) › Proposals — needs-human: a
+  provisioned signing key, an RFC-3161 TSA, or an on-chain anchor). A signed head proves *who vouched*
+  for the session head, not *when*.
+- **NOT a legal opinion**, and not a claim the agent behaved well, safely, or compliantly.
+
+**The same wording rides in-band.** Per the family's trust-note discipline, every packet, checkpoint,
+and proof artifact carries this boundary as its `note` field — and `vh agent verify` refuses a packet
+whose note has drifted — so the caveat travels with the evidence instead of living only in a doc. The
+standing in-band note, verbatim:
+
+> 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.
+
+---
+
+## The command surface
+
+```
+vh agent seal <session.jsonl> [--out <p>] [--sign (--key-env <VAR>|--key-file <p>) --license <f> --vendor <0xaddr>] [--json]
+vh agent verify <packet> [--vendor <0xaddr>] [--json]          # exit 0 ACCEPTED / 3 named REJECT (+ offending seq)
+vh agent redact <packet> --seq <list> [--out <p>] [--json]     # withhold payloads; head UNCHANGED, still verifies
+vh agent prove <packet> --seq <n> [--out <p>] [--json]         # disclose ONE event + its inclusion proof
+vh agent verify-proof <proof> [--root <hex>] [--json]          # check a disclosure offline against a head you trust
+vh agent checkpoint <session.jsonl> [--out <p>] [--json]       # commit the head so far (mid-session)
+vh agent verify-growth <earlier-head-or-packet> <later-packet> [--json]  # append-only extension or REJECT
+vh agent commit-claim --repo <dir> [--ref <ref=HEAD>] --seq <n> [--ts <iso>] [--actor <s>] [--out <p>] [--json]
+                                                               # bind the session to a git commit (FREE, key-less)
+vh agent verify-commit <packet> --repo <dir> [--ref <ref>] [--vendor <0xaddr>] [--json]
+                                                               # auditor re-derives oid + root from THEIR OWN clone
+```
+
+The input is JSONL (or a JSON array) of canonical events — a **closed** five-type schema:
+`{ seq, ts, actor, type: prompt|completion|tool_call|tool_result|note, payload | payloadHash, redacted?, meta? }`
+with `seq` contiguous from 0 (the tree position). Exit codes are the family contract: 0 ok/ACCEPTED,
+3 named REJECT or gate-fail, 2 usage, 1 IO/invalid artifact. Artifacts are written only to an explicit
+`--out` path, never implicitly to the working directory.
+
+## Free vs. paid (no surprises)
+
+- **FREE — the whole read/verify surface, forever:** unsigned `seal`, `verify`, `redact`, `prove`,
+  `verify-proof`, `checkpoint`, and `verify-growth`, plus every independent-verifier path below. Any
+  third party can check a packet without paying anyone; redaction and single-event disclosure are free
+  because withholding must never cost the *counterparty* anything to check.
+- **PAID — `--sign`:** wrapping the packet's head in a detached EIP-191 attestation ("this key vouches
+  for THIS session head"), so a recipient can pin YOUR published address with `--vendor`. Because
+  leaves are redaction-safe, ONE signature stays valid for every redacted copy. `--sign` is gated
+  OFFLINE behind a valid `--license <f> --vendor <0xaddr>` carrying the DRAFT **`agent_signed`**
+  capability — the SAME fail-closed license mechanism as `vh evidence seal --sign` (`vh-evidence-license`
+  kind; a missing/invalid/under-entitled license is a named refusal, never a silent downgrade).
+
+The `agent_signed` capability is DRAFT and priceless in the bundled catalog: the vendor key, the price,
+and the sale remain the standing human-owned go-live steps of the evidence vertical (P-7/P-8 in
+[`STRATEGY.md`](../STRATEGY.md), one flip in [`GO-LIVE.md`](GO-LIVE.md)) — this vertical adds **no new
+human gate**, and revenue is a license for delivered software value, never a token or tradeable asset.
+
+## Where the buyer independently verifies (no producer stack)
+
+A counterparty handed a `*.vhagent.json` never has to trust the producer's tooling — the packet is
+self-contained (no sibling files), and the independent [`verifier/`](../verifier/) tree re-implements
+verification against its own keccak with **zero** imports from the producer stack:
+
+```bash
+node verifier/verify-vh.js session.vhagent.json                      # unsigned packet — free, offline
+node verifier/verify-vh.js session.vhagent.json --vendor 0xPRODUCER  # signed packet, signer PINNED
+```
+
+- **Zero-install CLI:** the single self-contained file
+  [`verifier/dist/verify-vh-standalone.js`](../verifier/dist/verify-vh-standalone.js) (Node core only)
+  gives the same verdict with no clone and no `npm install`.
+- **No terminal at all:** the offline browser page
+  [`verifier/dist/verify-vh-standalone.html`](../verifier/dist/verify-vh-standalone.html) has a
+  built-in agent-session demo (a sample packet with one payload already redacted — verify it, tamper
+  one byte on the page, watch the REJECT name the seq) and accepts a dropped real packet; it contains
+  no network API at all, so the transcript never leaves the machine.
+
+Exit 0 = ACCEPTED, 3 = REJECTED naming the reason (and the offending event seq when event-local); a
+`--vendor` pin on an unsigned packet is a clean REJECT, so a stripped signature never passes a pinned
+verify. Details: [`verifier/README.md`](../verifier/README.md) §2c.
+
+---
+
+## Binding a session to a git commit (`commit-claim` / `verify-commit`)
+
+The first question the AI-code-governance / IP-provenance / audit buyer asks of an agent-session
+record is: *which code change does this session correspond to — and can I check the record wasn't
+doctored?* The commit-binding verbs answer it with machinery the family already ships. A
+**commit-claim** is an ORDINARY `note` event whose payload is a canonical claim string naming exactly
+ONE git **commit oid** plus that commit's **tracked-set root** — the same clone-reproducible Merkle
+root `vh hash <repo> --git` computes over the files git tracks. Appended to the session log *before*
+`vh agent seal`, the claim becomes one more redaction-safe leaf under the same head: no new packet
+kind, no new crypto, no new dependency.
+
+```bash
+# producer (FREE, key-less): derive oid + tracked-set root from YOUR repo, emit ONE JSONL claim event
+vh agent commit-claim --repo . --seq <next-seq> >> session.jsonl    # then: vh agent seal session.jsonl …
+
+# auditor (FREE, key-less): re-derive BOTH facts from THEIR OWN clone and check the sealed claim
+vh agent verify-commit session.vhagent.json --repo /their/clone     # exit 0 ACCEPTED / 3 named REJECT
+```
+
+### What a commit-bound packet PROVES
+
+- **The sealed, unaltered log contains a claim to exactly commit oid X with tracked-set root R at
+  position k.** The claim is an ordinary event leaf under the same head: editing, moving, or dropping
+  it — or doctoring any event around it — is the same named REJECT as any other tamper, and `k` (the
+  claim's `seq`) is bound by tree position, not by self-asserted metadata.
+- **Anyone with a clean checkout of X re-derives R via the shipped `vh hash <repo> --git` machinery.**
+  `vh agent verify-commit` FIRST re-runs the full packet verification (a tampered or forged packet —
+  including a failed `--vendor` pin — never reaches the claim check), THEN re-resolves the oid and
+  RECOMPUTES the tracked-set root from the auditor's OWN clone; it never trusts the packet's stored
+  facts. A REJECT names the failed check: `packet-invalid` / `no-disclosed-claim` / `oid-mismatch` /
+  `root-mismatch`. Because `hashGit` reads work-tree bytes, a dirty checkout of the right commit is an
+  HONEST `root-mismatch` (the named fix: check out the claimed commit in a CLEAN tree), never a false
+  ACCEPT.
+- **Redaction of any other payload leaves the claim checkable.** Leaves are redaction-safe, so the
+  producer can withhold every prompt/completion/tool payload and hand over a packet that still proves
+  the commit binding; redacting the CLAIM itself is, by definition, `no-disclosed-claim` — a withheld
+  claim is committed-to but not disclosable.
+
+### What it does NOT prove
+
+- **Containment, NOT causation — it does NOT prove the session's events produced the commit.** The
+  packet proves the sealed log CONTAINS the claim at position k; whether the recorded session actually
+  authored commit X is a real-world fact no hash can witness.
+- **Not faithful recording.** The boundary above is unchanged: garbage-in is out of scope — if the
+  software that wrote the log lied before sealing, the packet faithfully preserves the lie, claim
+  included.
+- **The claim's `ts` is self-asserted**, like every event `ts`: recorded verbatim, never verified
+  against any clock.
+- **NOT a trusted timestamp.** "This session (or claim) existed at time T" still rides the human-owned
+  **P-3** trust-root ([`STRATEGY.md`](../STRATEGY.md) › Proposals — needs-human); a signed head proves
+  *who vouched* for the head, not *when*.
+
+**The same wording rides in-band**: every `commit-claim` emission and every `verify-commit` verdict
+carries this boundary as its `note`. Verbatim:
+
+> A commit-claim is an ORDINARY session event binding a claim to EXACTLY one git commit oid and its tracked-set root (the `vh hash --git` work-tree root over the files git tracks at that commit). Sealed into a packet it proves CONTAINMENT, NOT CAUSATION: the unaltered log CONTAINS this claim — it does NOT prove the session's events PRODUCED that commit. The auditor re-derives BOTH facts from THEIR OWN clone via `vh agent verify-commit` (free, read-only, key-less); because hashGit reads WORK-TREE bytes, a dirty checkout is an HONEST root mismatch, never a false ACCEPT. `scope` is an UNVERIFIED hint; `ts` is SELF-ASSERTED metadata like every event ts. Every caveat of the agent-session packet applies (see `vh agent verify`).
+
+### Free vs. paid, and where each leg verifies
+
+`commit-claim` and `verify-commit` are **FREE**, read-only, and key-less end-to-end — the whole
+commit-binding surface joins the free verify tier above. **`--sign` is unchanged behind the existing
+gate** (the DRAFT `agent_signed` capability, same fail-closed license mechanism as above): commit
+binding adds no new paid surface and no new human gate.
+
+**The standalone-page boundary, honestly:** the zero-install page verifies the PACKET — seal, leaves,
+head, signature, and the disclosed claim bytes; re-deriving the COMMIT facts requires git + a clone,
+i.e. the CLI (`vh agent verify-commit`) is the auditor tool for that leg. A counterparty without git
+can still check the packet is unaltered and read the claim; only the re-derivation leg needs a
+checkout.
+
+The scripted worked flow — map → `commit-claim` → seal → redact-all-but-claim → `verify-commit` — is
+committed at
+[`examples/agent-session/commit-bound-session.js`](../examples/agent-session/commit-bound-session.js)
+and driven end-to-end (plus the tamper/dirty-checkout negatives) by
+[`test/cli.agent.commit.docs.test.js`](../test/cli.agent.commit.docs.test.js), so it cannot rot.
+
+---
+
+## Adoption is a ~20-line mapping, not a platform migration (the worked example)
+
+Your agent framework already writes a session log. The only integration you own is mapping its shape
+into the canonical five-type event schema — and the committed, test-gated example
+[`examples/agent-session/`](../examples/agent-session/) shows exactly that on a **realistic
+third-party transcript**:
+
+- [`examples/agent-session/transcript.openai.jsonl`](../examples/agent-session/transcript.openai.jsonl)
+  — an OpenAI-chat-completions-style `messages[]` + tool-calls JSONL export (system/user/assistant
+  roles, assistant `tool_calls`, `role:"tool"` results carrying PII worth redacting).
+- [`examples/agent-session/map-transcript.js`](../examples/agent-session/map-transcript.js) — the
+  dependency-free mapper; the whole mapping sits between its `MAPPING BEGIN`/`MAPPING END` markers,
+  about twenty lines, with the size pinned by test.
+
+The end-to-end flow (each command from the example's README, driven verbatim by
+[`test/cli.agent.docs.test.js`](../test/cli.agent.docs.test.js) so it cannot rot):
+
+```bash
+node examples/agent-session/map-transcript.js --out $W/events.jsonl        # 1. MAP    (your 20 lines)
+node cli/vh.js agent seal $W/events.jsonl --out $W/session.vhagent.json    # 2. SEAL   (free)
+node cli/vh.js agent redact $W/session.vhagent.json --seq 3 \
+    --out $W/session.redacted.vhagent.json                                 # 3. REDACT the PII tool result
+node cli/vh.js agent verify $W/session.redacted.vhagent.json              # 4. VERIFY — ACCEPTED, seq 3 withheld
+node cli/vh.js agent prove $W/session.redacted.vhagent.json --seq 8 \
+    --out $W/event-8.proof.json                                            # 5. PROVE the final completion…
+node cli/vh.js agent verify-proof $W/event-8.proof.json                    #    …and check it offline
+```
+
+The redacted copy verifies with the **identical head** as the full one; the withheld PII stays
+checkable ("something was here, committed to, and withheld") without being disclosed.
+
+---
+
+## How it relates to the rest of the family
+
+Same core, different artifact: the leaf/root/proof math is the shipped RFC-6962 ordered-log core
+([`cli/journal-log.js`](../cli/journal-log.js), the transparency-log engine in
+[`INTEGRITY-JOURNAL.md`](INTEGRITY-JOURNAL.md)); the packet/trust-note/license disciplines are the
+evidence family's ([`EVIDENCE.md`](EVIDENCE.md)); signing reuses the shared attestation envelope; and a
+`vh.agent-session-packet` is kind-disjoint from every other artifact, so nothing cross-verifies as
+something it is not. Boundary language across the family lives in
+[`TRUST-BOUNDARIES.md`](TRUST-BOUNDARIES.md).

package/docs/ANCHORING.md

@@ -0,0 +1,167 @@
+# Anchoring sealed artifacts on-chain — `vh anchor-artifact` / `vh verify-anchored`
+
+Every verifyhash product ends in a **sealed artifact** whose integrity folds up into ONE 32-byte
+digest. Anchoring writes that digest into the **ContributionRegistry** — the project's immutable,
+permissionless, append-only contract — so an on-chain record binds the artifact at a block whose
+timestamp **bounds its existence**. This is Option **(C)** of the STRATEGY.md **P-3** trust-root
+menu: no timestamp authority, no signing-key custody — the chain itself is the witness.
+
+The bridge is deliberately thin: the pure core (`cli/core/anchor-binding.js`) knows how to extract
+the one canonical digest from each sealed artifact kind — re-validating it through the artifact's
+**own shipped validator first** — and how to verify, **offline**, that an anchored receipt binds
+exactly the artifact bytes in hand. The CLI (`cli/anchor-artifact.js`) adds the chain legs.
+
+## The closed kind table (what can be anchored)
+
+| artifact | kind string | anchored digest |
+|---|---|---|
+| Evidence packet (`vh evidence seal`) | `vh.evidence-seal` | the seal's Merkle `root` |
+| Agent-session packet (`vh agent seal`) | `vh.agent-session-packet` | the **verified** head root |
+| Journal tree head (`vh journal tree-head`) | `vh.journal-tree-head` | the head `root` (size bound into the derivation rule) |
+| TrustLedger sealfile | `trustledger.reconcile-seal` | the seal's `root` |
+| Dataset attestation (`vh dataset attest`) | `verifyhash.dataset-attestation` | `0x` + sha256 of the canonical bytes — the **same** digest `vh dataset timestamp-request` emits |
+| Parcel attestation (`vh parcel attest`) | `verifyhash.parcel-attestation` | `0x` + sha256 of the canonical bytes — the **same** digest `vh parcel timestamp-request` emits |
+
+The table is **closed**: an unknown or invalid artifact is a **named reject**, never a guess. One
+artifact, one digest — the attestation legs reuse the exact digest your RFC-3161 TSA flow already
+stamps, so Options (B) and (C) anchor the **same** identity.
+
+## The command surface
+
+```
+vh anchor-artifact <sealed-file> --contract <addr> --rpc <url> (--key-env <VAR> | --key-file <p>)
+                   [--author-bound] [--uri <s>] [--out <receipt>] [--json] [--i-understand-mainnet]
+vh verify-anchored <receipt> <sealed-file> [--rpc <url> --contract <addr>] [--json]
+```
+
+`anchor-artifact` extracts the digest, submits it as the registry `contentHash`, waits for the tx,
+reads the record **back from the chain** (contributor / authorBound / blockNumber / block
+timestamp), and emits the canonical, sorted-key **`vh-anchored-receipt@1`** container — digest +
+derivation rule + chain facts + the trust note below, verbatim. The signing key comes **only** from
+`--key-env <VAR>` / `--key-file <p>` (read, used, discarded — never generated, persisted, or
+logged), and a chainId outside the known local/testnet set refuses without `--i-understand-mainnet`.
+Exit contract: `0` anchored / `3` named reject (an invalid artifact, or the registry's own revert
+such as `AlreadyAnchored`) / `2` usage / `1` IO-network-key.
+
+`verify-anchored` is **OFFLINE by default** — no key, no network (but it runs through the producer
+`cli/` stack, which loads `ethers`; "OFFLINE" here means **no key and no network**, NOT "no producer
+stack" — the standalone `verifier/` tree does not yet verify anchored receipts, see **Independent
+verification** below): it validates the receipt strictly and **recomputes** the artifact's digest
+through the same closed table; any deviation is a specific named reject (`digest-mismatch` /
+`kind-mismatch` / `how-mismatch` / `bad-receipt` / the artifact's own named reject). With **both** `--rpc` and `--contract` it additionally authenticates the registry
+(the standing identity probe — no record is believed until the contract self-identifies) and
+re-checks every chain fact the receipt claims. Exit `0` ACCEPTED / `3` REJECTED / `2` / `1` — the
+shared CI-gateable verify contract.
+
+## What an anchored receipt PROVES
+
+- **The binding.** An on-chain registry record binds **this exact artifact digest**: `verify-anchored`
+  re-derives the digest from the artifact bytes you hold (through the artifact's own validator) and
+  matches it against the receipt and — with `--rpc` — against the chain record itself.
+- **Existence by block time.** The record's block timestamp **BOUNDS existence**: the digest existed
+  by that block — as trustworthy as the chain + YOUR pinned contract address.
+- **Attribution, exactly as strong as D-1.** With `--author-bound` the record reads back `authorBound:true` — front-run-resistant, first-claimant attribution per D-1 (commit-reveal: the commitment binds digest + committer + a secret salt, so a mempool copier cannot redirect the claim to themselves). The default one-shot `anchor()` records only the **first broadcaster** (`authorBound:false`).
+
+## What it does NOT prove (the honest boundary)
+
+Every receipt carries this note **in-band, verbatim** (an edited note is a named `bad-receipt`):
+
+> This anchored receipt binds the artifact digest above to an on-chain registry record. A receipt from a LOCAL dev chain proves MECHANISM only and is worth NOTHING publicly until a human deploys the registry (STRATEGY.md P-2). On a public chain it proves ONLY that an on-chain record binds this exact digest at a block whose timestamp BOUNDS existence — as trustworthy as the chain + YOUR pinned contract address — NOT the artifact's truth, NOT faithful recording, NOT attribution beyond the anchoring key. The `chain` facts in this receipt are the anchorer's claim until re-checked against the chain (`vh verify-anchored --rpc`).
+
+Spelled out:
+
+- **A LOCAL dev-chain receipt proves MECHANISM only.** The committed fixtures below and every test
+  in this repo anchor on an ephemeral local chain (chainId `31337`) — that demonstrates the pipeline
+  works end to end, and **nothing more**. Until a human deploys the registry to a public chain
+  (STRATEGY.md **P-2**), no receipt from this repo is worth anything publicly.
+- **NOT the artifact's truth or faithful recording.** Anchoring binds bytes, not reality: a sealed
+  evidence packet's files, an agent log's events, a dataset's provenance hints are exactly as true
+  as they were before anchoring (see each product's own trust note — garbage in is out of scope).
+- **NOT attribution beyond the anchoring key.** Even `authorBound:true` proves only that the
+  **key-holder** was the front-run-resistant first claimant — it does not identify a person or
+  organization; pin the key out of band (see `docs/KEY-LIFECYCLE.md`).
+- **NOT legal advice** and NOT a compliance verdict.
+- **Options (A) and (B) of P-3 remain INDEPENDENT trust-roots a buyer may also require.** A
+  publisher signature (A: `vh dataset/parcel sign`) proves *who vouched*; an RFC-3161 TSA token (B:
+  `timestamp-request`/`timestamp-wrap`/`verify-timestamp`) is a third party's *existed-by-genTime*
+  attestation. An on-chain anchor (C) complements them; it does not replace them.
+
+## Independent verification — the one axis this does NOT yet cover
+
+The verifyhash family's headline is that a counterparty can verify a sealed artifact **OFFLINE,
+without installing the producer's stack**: the standalone `verifier/` bundle
+([`../verifier/dist/verify-vh-standalone.js`](../verifier/dist/verify-vh-standalone.js)) is a single,
+dependency-free file — **no `ethers`, no `npm install`** — that re-derives an evidence packet's or
+agent packet's digest by itself. That promise **DOES** cover the **sealed artifact underneath** an
+anchored receipt: hand a counterparty the `*.vhevidence.json` (or any closed-table artifact) and they
+verify it standalone, exactly as before, with no producer code.
+
+It does **NOT yet extend to the anchored receipt itself.** `vh verify-anchored` — including its
+OFFLINE binding leg — runs **only through the producer `cli/` stack, which loads `ethers` at module
+load** (`cli/anchor-artifact.js` → `cli/core/attestation.js`); and `vh-anchored-receipt@1` is **NOT a
+recognized kind** in the standalone `verifier/verify-vh.js` tree, which scopes itself to sealed
+artifacts and explicitly puts on-chain anchoring out of scope. So the family's zero-install
+"verify without the producer's stack" promise **does not YET reach the anchored-receipt binding
+leg**: a counterparty who wants to check the receipt's binding today must run the producer cli
+(`node cli/vh.js verify-anchored`).
+
+This is a **packaging gap, not a proof gap.** (1) The binding check is pure hashing — the standalone
+verifier already re-derives evidence-seal and agent-packet digests with no `ethers` — so
+`vh-anchored-receipt@1` can be added to the standalone tree to actually close it (tracked as
+**T-70.4**). (2) The `--rpc` chain re-check needs the chain anyway, so the offline binding leg's
+standalone value is limited until then. Until T-70.4 lands: verify the **sealed artifact** standalone
+(zero-install, independent), and verify the **anchor** via the producer cli.
+
+## The free line
+
+Both verbs are FREE — no paid gate, no license, no entitlement: the only cost is the chain's own gas, and the gas is YOUR OWN (paid from a key you provision and hold; `vh verify-anchored` needs no key at all).
+
+## The worked local flow (seal → anchor → verify offline → verify against the chain)
+
+The whole flow runs on a **local** hardhat node — remember the boundary: this proves **mechanism
+only**.
+
+```bash
+# 0. a LOCAL dev chain + a local registry (terminal 1, then terminal 2):
+npx hardhat node --hostname 127.0.0.1 --port 8545
+npx hardhat run scripts/deploy.js --network localhost      # prints the registry address
+export VH_DEV_KEY=0x...                                    # a LOCAL pre-funded dev key — never a real key
+
+# 1. seal — any closed-table artifact works; here, an evidence packet:
+node cli/vh.js evidence seal ./report --out report.vhevidence.json
+
+# 2. anchor — write the digest on-chain, emit the anchored receipt:
+node cli/vh.js anchor-artifact report.vhevidence.json --contract <addr> --rpc http://127.0.0.1:8545 \
+  --key-env VH_DEV_KEY --author-bound --out report.anchored.json
+
+# 3. verify OFFLINE — no key, no network; the receipt binds EXACTLY this artifact:
+node cli/vh.js verify-anchored report.anchored.json report.vhevidence.json
+
+# 4. verify against the CHAIN — authenticate the registry, re-check every chain fact:
+node cli/vh.js verify-anchored report.anchored.json report.vhevidence.json \
+  --rpc http://127.0.0.1:8545 --contract <addr>
+```
+
+**Zero-setup offline leg.** The repo commits a real sample pair under
+[`examples/anchoring/`](../examples/anchoring/) — a sealed evidence packet and the
+`vh-anchored-receipt@1` a local run produced (chainId `31337`, `authorBound:true`). Step 3 runs
+against them with no chain at all:
+
+```bash
+node cli/vh.js verify-anchored examples/anchoring/anchored-receipt.local.json examples/anchoring/sample-seal.vhevidence.json
+```
+
+It prints `ACCEPTED (offline binding check)` and exits `0`; flip one byte of either file and it is a
+named reject, exit `3`. (`test/anchoring.docs.test.js` runs exactly this leg.)
+
+## Going public — the standing human gate (P-2)
+
+Everything above is built, tested, and free to run — against a **local** chain. The single missing
+step for receipts that are worth something publicly is the standing **P-2** deploy, which is a
+**human** action the loop never takes: provision a THROWAWAY faucet-funded testnet key, deploy to
+**Polygon Amoy first** (`scripts/deploy.js`), verify the source on the explorer, and publish the
+address so consumers can **pin** it. From that moment the exact commands above work unchanged —
+point `--rpc` at Amoy and `--contract` at YOUR pinned address — and every sealed artifact in the
+family gains "digest existed by public-chain block time T", with `--author-bound` front-run
+resistance, for the price of gas. The loop itself still NEVER deploys, holds funds, or anchors
+publicly (see STRATEGY.md P-2/P-3).