feat: forge rank (centrality × team history), temporal ledger queries + Merkle root, impact() tightening

[CodeWithJuber]

What & why

A full-repo review (architecture + algorithm audit, cross-checked against currently-trending open-source agent tooling) found that forgekit's atlas graph and append-only ledger were each sitting on unused mathematical capability. Three commits, smallest-risk first:

1. perf(atlas): impact() dequeues in O(1) — the label-correcting blast-radius search (the hottest path in the repo: consensus ≤10×, imagine ≤8×, gate ≤10× calls per invocation) drained its frontier with queue.shift() (O(n) per dequeue) and a linear starts.includes scan in the inner loop. Now an index pointer + a Set. Processing order is unchanged, so outputs are bit-identical — verified across all targets on this repo's own 9,205-node atlas; a synthetic 20,000-dependent frontier drops 2,463 ms → 102 ms. A new test pins the max-product diamond semantics. Also memoizes lesson trigger-glob compilation (ran per lesson × file on every PreToolUse hook).

2. feat(rank): forge rank — load-bearing code, measured — answers the question every agent asks before touching a repo: what here is dangerous to change?

   • Weighted PageRank centrality over the atlas graph, reusing the same EDGE_WEIGHT priors the blast-radius search trusts (now exported).
   • Circular-import clusters via iterative Tarjan SCC over a new scope.directedImportGraph() (real import statements — measured first that atlas call-edges are too noisy: one coincidental unique-name match glued ~100 unrelated files into a mega-component).
   • Chokepoint files via iterative Hopcroft–Tarjan articulation points.
   • The original join: each file's past-incident history from the evidence ledger (val()-weighted lesson claims whose trigger globs match it, plus deja session summaries that list it) multiplies into hazard = centrality × (1 + history) — central code that has already bitten the team outranks equally central code that hasn't. Fail-open: no ledger → purely structural.
   • Exposed as the rank_code MCP tool (20 MCP tools — count reconciled in all six doc claims). Deterministic end to end: sorted-order power iteration, no Math.random.

3. feat(ledger): temporal queries + Merkle state root — the store is append-only and every record carries its day, so past beliefs are recomputable — now they're queryable:

   • forge ledger at <date> — beliefs as of any past day, with val scored by that day's evidence and clock. stateAt is a lattice morphism (commutes with the CRDT merge — property-tested beside the semilattice suite).
   • forge ledger diff <since> [<until>] — appeared / retired / strengthened / weakened between two days.
   • forge ledger root — a permutation-invariant Merkle root over the verified state, with per-shard hashes that localize divergence; wired into ledger sync --dir as an already-in-sync fast path (the ref transport's tree-SHA equality already was this check).

Not done on purpose (over-engineering guard): no heap rewrite of impact() (label correction already converges; pointer fix gets the asymptotic win with identical output), no rank→substrate/route auto-integration (documented seam), no LSH for clusters() (no production caller yet), no new env vars or config knobs.

Note on reports/benchmarks.md: deliberately not regenerated — the committed table carries maintainer-hardware measurements that README bold claims reconcile against; regenerating on an ephemeral CI container would overwrite them with unrepresentative numbers. The impact() speedup receipt above was measured A/B on this container instead.

Checklist

• npm test passes (1,088 pass / 0 fail locally, Node 20)
• npm run check passes (Biome lint + format)
• New public functions have a test (test/rank.test.js ×8, ledger temporal/root ×5, syncDir fast path, MCP rank_code ×2, impact diamond pin)
• Conventional commit message (feat:/fix:/docs: …)
• CHANGELOG.md updated under ## [Unreleased]
• No new runtime dependency (dev deps ok)
• Substrate/docs updated if this changes forge substrate, forge impact, router/gate, or MCP substrate tools (README, docs/GUIDE.md, ARCHITECTURE.md, mintlify pages, MCP tool count ×6)

Risk & rollback

• Risk level: low — commit 1 is output-identical (pinned by test); commits 2–3 are additive surfaces (new command/subcommands/MCP tool); the only behavior change to an existing path is the syncDir fast path, which short-circuits only on exact state-root equality and is covered by a divergence-then-reconverge test.
• Rollback plan: revert the three commits (each is self-contained and reverts cleanly in reverse order); no migrations, no storage-format changes, no new persisted files.

Extra checks (tick if applicable)

• npm run typecheck passes
• Input validated at boundaries; errors handled (no swallowing) — parseDay rejects malformed dates with usage + exit 1; rankReport fails open (built:false) without an atlas; corrupt ledger → structural-only ranking
• Authorization/ownership checked (if it touches access) — n/a
• Logs contain no secrets/PII
• If AI-assisted: I understand it, verified the package APIs, and it has tests

🤖 Generated with Claude Code

https://claude.ai/code/session_01LXmzxfRVDRVPU6LG8W39Rz

---

Generated by Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
forgekit-docs	🟢 Ready	View Preview	Aug 7, 2026, 7:11 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.