nordisk/dwarves

Release doctor — semantic blast-radius (the pre-link check)

release = build, and this is the link step: it proves the constellation's cross-crate API references resolve before a version bump ships. Where the crate-level blast answers "who depends on the changed crate", semantic blast answers "which exact call sites touch the changed crate's API" — what actually breaks. PLAN EPIC 7. Lives in src/release/semantic_blast.rs.

Design

A linker resolves each object's undefined symbols against the exports of the others and refuses to emit if any is unresolved/incompatible. The release doctor does the same over crates, using the warehouse SCIP call-graph:

1. Target crate C (dirty / to-be-bumped) + the set of its changed/removed symbols (its exported API delta).
2. RepoGraph.blast_radius on the reverse graph Gᵀ gives the dependent repos — the only places a call site to C can live.
3. Read the SCIP call-graph from the warehouse (call_edges + symbol_facts Iceberg tables, produced by deep_scan) via knowledge::query::load_preferred_merged (source-tagged resolved/scip, with a syn-call_edges fallback when the scip feature is off).
4. KnowledgeView::callers_of(symbol) — the memoized inverted index over call_edges — resolves each changed symbol to its exact call sites in the dependents (matches both facett::render and bare render; intra-C self-calls excluded).
5. Rank by API-surface delta: most-called symbol first, Removed before Changed. Symbols no dependent calls become unused_changes (a provably safe delta) — the report distinguishes "might break" from "actually breaks".

Output: SemanticBlast { target_repo, target_crates, impacts: [SymbolImpact { symbol, change, call_sites: [CallSite{crate, caller, callee, kind, file, line}] }], unused_changes, total_call_sites, affected_crates }. Turns "facett → 7 repos might break" into "these 12 call sites in 3 crates call the 2 symbols that changed."

Guide

The plain nornir release doctor runs without a warehouse and leaves the semantic section empty (only crate-level blast). To get exact call sites, use the warehouse-aware entry point doctor::run_with_semantic_blast(repos, policy, wh, changed_by_repo) — it fills DoctorReport.semantic_blast and format_report renders a "Semantic blast radius (exact call sites touching the changed API)" section after the crate-level blast. Feed it the changed-symbol set per dirty repo (from the API diff); it needs a populated warehouse (nornir populate / deep_scan).

Idiot guide

• "Will bumping this crate break anything?" → semantic blast lists the exact files+lines that call the API you changed. Empty list = safe. Non-empty = those are your link errors; fix or coordinate them before releasing.
• "It says unused_changes." → you changed/removed those symbols but nobody calls them — safe to ship.
• Needs the warehouse — run nornir populate first, or you only get the coarse "who depends on it" list.