feat: Proof-Carrying Memory ledger core (substrate-v2 P1)

[CodeWithJuber]

What & why

Phase P1 of the merged substrate-v2 plan (#24): the Proof-Carrying Memory (PCM) ledger — the keystone store every later phase (team sync, reuse cache, context assembly, dashboard) builds on. Spec: docs/plans/substrate-v2/01-pcm-protocol.md, ADR-0006.

• src/ledger.js (pure core, no fs): canonical JSON with sorted keys/NFC → content-addressed claim ids (provenance and evidence excluded, so teammates who independently learn the same thing mint the same claim); an oracle taxonomy where only independent signals (tests, CI, human accept/revert) may move confidence; val = time-decayed Beta posterior that decays toward uncertainty (0.5), never toward false; the paper's Eq. 3 retrieval score; dependency-free MinHash similarity + union-find consolidation clustering; and a join-semilattice merge — property-tested for commutativity, associativity, and idempotence, so teammate ledgers converge under any merge order with zero conflicts.
• src/ledger_store.js: the git-native .forge/ledger/ layout — one immutable canonical-JSON file per claim (id-sharded), append-only hash-deduped evidence logs (union-merge-safe; .gitattributes added), tombstones, attic, generated LEDGER.md, and a CI-friendly normal-form verify. Corrupt or tampered files (address mismatch) are quarantined on read, never trusted.
• src/ledger_bridge.js (the P1 migration seam): cortex shadow-writes every lesson event — create mints a claim with zero evidence (creation is not confirmation), recurrence appends a cortex.episode confirm, a human reversal appends a human.revert contradiction; forge remember / forge recall add shadow facts; forge ledger import back-fills legacy lessons (aggregate counts → dated outcomes) and facts, idempotently.
• CLI: forge ledger stats | verify | show <id> | import (all --json-capable).
• Secret-refusal moved down: SECRET_RE now lives in the ledger core so no claim kind can persist a credential; recall.js re-exports it for compatibility.

Legacy stores stay the read path in P1 (every existing test/hook/guard unchanged — the P1 acceptance gate from the plan); the read-path flip lands with P2's merge tooling.

Checklist

• npm test passes (253/253 — 31 new ledger tests incl. property tests: id stability, decay monotonicity, semilattice laws)
• npm run check passes (Biome lint + format)
• New public functions have a test
• Conventional commit message (feat:)
• CHANGELOG.md updated under ## [Unreleased]
• No new runtime dependency (dependencies still empty — pure stdlib)
• Substrate/docs updated — implements docs/plans/substrate-v2/01-pcm-protocol.md §7 (module plan)

Risk & rollback

• Risk level: low-medium — new modules are additive; the only behavior touched in existing paths is best-effort shadow-writes (wrapped in try/catch, never block the hook path) and the SECRET_RE relocation (regex byte-identical, re-exported)
• Rollback plan: revert the commit; .forge/ledger/ directories are inert data safe to delete

Extra checks (tick if applicable)

• npm run typecheck passes
• Input validated at boundaries; errors handled (mint/outcome/put return {ok:false, reason}; corrupt files skipped with debug logging, never fatal)
• Logs contain no secrets/PII (secret-refusal enforced at mint, at store, and re-scanned by forge ledger verify)
• If AI-assisted: I understand it, verified the package APIs, and it has tests

---

An adversarial multi-angle review pass (8 finder angles + verification) is running; surviving findings land as a follow-up commit on this PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Fc2MvWJbQ1cyNQ76ymv4hs

---

Generated by Claude Code