feat: the graph explorer (ADR-0020, stacked on #112)

[HenryCFnord]

Stacked on #112 (base is that PR's branch — retarget to main after #112 merges). Draft until the base lands.

The owner's design decisions, taken this session: report graph as export product plus site staging, d3-force vendored as the layout engine, documents by default with the code layer switchable.

What this is

arqix report graph [--out <path>] renders the trace core graph (ADR-0006, identity per ADR-0007) into one self-contained interactive HTML page: embedded graph data (enriched with each document's title and declared lifecycle status), embedded vendored engine, zero external references — works from the filesystem, the published site, and offline. publish site stages the page for the default language (site-src/graph.html), never committed (ADR-0020 rejects the snapshot treadmill for data that ages with every commit).

The interaction shell is project code in the page: canvas rendering, pan/zoom, node drag with layout pinning, type facets with counts and colour swatches, lifecycle facets, search, hover tooltip, click-to-highlight neighbourhood, and the code-artefact layer off by default.

Vendoring, dogfooded

The engine is the concatenation of four pinned minified UMD builds (d3-dispatch@3.0.1, d3-quadtree@3.0.1, d3-timer@3.0.1, d3-force@3.0.0, ISC) with a provenance header — recorded as source record SRC-0005 with its sha256, so the existing SRC-006 digest check now guards the vendored bytes on every lint frontmatter. Updating the engine is a deliberate re-vendoring with a new digest.

Commit order (spec-first)

1. docs: ADR-0020 + chapter-9 row.
2. spec: US-08-01-42 (a genuinely new goal — explore the corpus) + REQ-08-01-42-01/-02/-03.
3. red: three tests. Verbatim evidence:

report_graph_embeds_the_corpus_graph ... FAILED        (unrecognized subcommand 'graph')
report_graph_writes_a_self_contained_page ... FAILED   (unrecognized subcommand 'graph')
publish_site_stages_the_graph_explorer ... FAILED      (missing site-src/graph.html)

4. feat (green): trace::graph_json (the scan model, shared), reporter::graph_page/graph, the ReportCommand::Graph surface, publish staging, both assets, SRC-0005.
5. docs: roadmap (candidate → landed) + program status, including the triage note that FR-E1 is not a dependency — the explorer reads the ADR-0006 core graph; the uniform findings JSON concerns the lint/verify surface and stays an independent, parallel slice.

Validation

• All three tests green; full just ci green before every commit (unpiped log, exit 0).
• Driven live in headless Chromium against this corpus: 545 nodes, 2029 edges, facets populated, zero console errors. To see it yourself: cargo run -- report graph --out graph.html && open graph.html.
• Injection safety: embedded JSON has </ escaped to <\/, so no title can close the script element early.

Review notes

• The </-escape and the enrichment-never-invents-nodes rule are the two subtle spots (src/reporter.rs::graph_page).
• The shell is ~300 lines of vanilla JS in src/assets/graph-explorer.html; the vendored bundle is byte-frozen by SRC-0005.
• Growth path per ADR-0020: claims/freshness layers become new toggles over the same embedded model.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Gie4jfrHKCxQktD2UsvH4Q