nordisk/dwarves

Release-Convergence Viz — Phase 2/3 plan (#28)

Status: design (READ-ONLY authored; no code touched). A build agent executes this directly.

The artifact chain already landed (Phase 1):

• dwarves release_doctor::graph_diff — the before→after GraphDiff + GraphDiffArtifact (crates/dwarves/src/release_doctor/graph_diff.rs, 953 LOC, green). This is the topology + node/edge delta source.
• facett-releaseview — the engine-agnostic ReleaseConvergence model (facett/facett-releaseview/src/model.rs) + the CPU pseudo-3D Planes3D hero and TriBadge2D fallback (.../src/lib.rs). Pure egui-painter, wasm-clean, green.
• facett-graph3d::CodeVault — the wgpu-capable 3D box vault (facett/facett-graph3d/src/codevault.rs) with a real orbit camera, depth-sorted projection, GPU bloom lane (gpu_scene, graph_gpu.rs), and per-node NodeState (Ok/Changed/Glitch).

Phase 2/3 delivers three things:

• (a) the DWARVES-SIDE one-way adapter graph_diff + 3 version sources → ReleaseConvergence (facett stays pure).
• (b) upgrade Planes3D from CPU pseudo-3D onto real CodeVault wgpu depth planes.
• (c) dwarves release watch — a CLI that streams the convergence live.

The three version sources (all already exist in dwarves — REUSE, do not twin)

derive_status(local, sparring, cratesio) (model.rs:131) is the pure kernel the model already ships — the adapter only has to feed it the three strings per crate.

(a) The dwarves-side adapter — release_doctor::convergence

New file: crates/dwarves/src/release_doctor/convergence.rs; register pub mod convergence; in mod.rs (after pub mod graph_diff; at mod.rs:295).

Dependency direction (one-way, facett stays pure): dwarves gains facett-releaseview as an OPTIONAL dep behind a new convergence feature — dwarves depends on facett, never the reverse. Mirror the existing facett-adapter feature (Cargo.toml, the facett-adapter = ["dep:facett-pipeline"] line) and brokkr/facett_adapter.rs:

# Cargo.toml [features]
convergence = ["dep:facett-releaseview"]      # engine → model, one-way (like facett-adapter)
# Cargo.toml [dependencies]
facett-releaseview = { path = "../../../facett/facett-releaseview", version = "0.1", optional = true }

Gate the whole module #![cfg(feature = "convergence")]. The adapter imports facett types (facett_releaseview::model::{ReleaseConvergence, CrateConvergence, DepEdge}) and produces a ReleaseConvergence — exactly the ForgePipelineAdapter::from_report shape in brokkr/facett_adapter.rs, but for the convergence model.

Core function (pure over already-gathered inputs — golden-testable, no I/O):

/// Build the engine-agnostic convergence model from the graph-diff topology + the
/// three resolved version maps. PURE (no probes here — the caller gathers the maps),
/// so it golden-tests on fixtures exactly like graph_diff::GraphDiff::between.
pub fn build_convergence(
    title: &str,
    after: &graph_diff::DepGraphSnapshot,          // the AFTER snapshot = the topology to show
    local:    &BTreeMap<String, String>,
    sparring: &BTreeMap<String, String>,
    cratesio: &BTreeMap<String, String>,
) -> ReleaseConvergence

Mapping rules, all grounded in the existing shapes:

1. Nodes — one CrateConvergence per after.nodes entry (graph_diff.rs:98, DepGraphSnapshot.nodes: Vec<GraphNode>). For each GraphNode { name, .. }:

   • local = local.get(name), sparring = sparring.get(name), cratesio = cratesio.get(name).
   • Missing-version discipline: a crate absent from a map (e.g. never published) → "0.0.0", matching from_repo_graphs's explicit-UNKNOWN rule (graph_diff.rs:160). Never silently a real version.
   • CrateConvergence::new(name, local, sparring, cratesio) (model.rs:174) auto-derives status via derive_status.

2. Edges — map each after.edges GraphEdge { from, to } (graph_diff.rs:73) to a DepEdge { from: idx, to: idx } (model.rs:222) by resolving the crate names to node indices (build a name → index map from the node vec first). Drop any edge whose endpoint isn't a node (defensive, mirrors build_dag's filter at lib.rs:679).

3. Title — the run id / workspace name.

Why after (not the diff) drives the topology: the convergence view shows the CURRENT constellation snapping to the published target; after = what we're releasing. The GraphDiff (before→after) is orthogonal — it's the semver-delta artifact, not the live 3-graph. If a build agent wants the diff's bump classification shown as a node badge, thread GraphDiff::bumped_nodes (graph_diff.rs:254) in as an optional per-node annotation, but that's additive polish, not required for convergence.

The gathering seam (does the I/O, calls build_convergence):

/// Probe the three sources for a checked-out constellation and assemble the model.
/// Best-effort probes (a miss → the crate reads Unpublished/0.0.0, never a hard block),
/// mirroring registry.rs's degrade-safe contract (registry.rs:51 doc).
pub fn gather_convergence(
    repo_root: &Path,
    graphs: &[model::RepoGraph],
    sparring: Option<&SparringRegistry>,   // Some when a Gate-B rehearsal is live; None ⇒ sparring==local
) -> Result<ReleaseConvergence>

• local: cargo::publishable_crate_versions(repo_root) → collect into BTreeMap (cargo.rs:1772).
• after snapshot: DepGraphSnapshot::from_repo_graphs(graphs, &local) (graph_diff.rs:149) — REUSES the produced-crate/edge granularity the publish plan already orders.
• cratesio: for each node, CratesIoBackend.published_max_version(name) (registry.rs:71); pace with the existing publish_pacing if probing many crates.
• sparring: when a SparringRegistry is running (rehearse feature), CustomBackend { base_url: sparring.probe_base_url() }.published_max_version(name) (rehearse.rs:95, registry.rs:109); when None, seed sparring = local (pre-rehearsal, the sparring plane just tracks local so derive_status reads BumpDrift/Converged, never a false LockDesync).

Robot/observable (LAW 6): add convergence_state_json(&ReleaseConvergence) -> serde_json::Value reusing the same tally shape the model already exposes via status_counts (model.rs:295) + converged_fraction (model.rs:318) + per-node chip_divergence (model.rs:204), so a headless test asserts the whole thing from one value.

Tests (in convergence.rs, #[cfg(test)]):

• builds_model_from_diff_and_three_version_maps — fixture: the graph_diff.rs:658 before()/after() chain, three hand-built version maps (one converged crate, one NeedsRelease = cratesio behind local, one LockDesync = sparring≠cratesio, one BumpDrift = sparring≠local). Assert status_counts() buckets exactly. RED if the name→index edge mapping or the missing-version→0.0.0 rule breaks.
• missing_cratesio_version_reads_unpublished_not_a_real_version — a crate absent from the cratesio map → cratesio_ver == "0.0.0" and status NeedsRelease.
• edges_survive_the_name_to_index_remap — the app→lib→base edges land as the right DepEdge indices.
• Gate behind #[cfg(feature = "testmatrix")] nornir_testmatrix::functional_status("release-convergence", …) exactly like graph_diff.rs:770.

(b) Upgrade Planes3D onto real CodeVault wgpu depth planes

Philosophy stays intact (facett-releaseview/src/lib.rs:8 "GPU-hero + CPU-honest"): the CPU Planes3D painter (lib.rs:344) is the always-works fallback and does not get deleted. We ADD a GPU hero backed by CodeVault, and make it the default ViewMode when the graph3d feature is on. This is precisely the follow-up the crate doc already promises (lib.rs:19-20).

b.1 — deps + feature (facett-releaseview/Cargo.toml):

[features]
graph3d = ["dep:facett-graph3d"]          # opt-in GPU hero; CPU planes stay default-clean
[dependencies]
facett-graph3d = { path = "../facett-graph3d", version = "0.1", optional = true }

Keep graph3d OFF by default so the published/wasm build stays CPU-only and light (matches how facett-graph3d's own wgpu is off by default, facett-graph3d/Cargo.toml default = []). A host that wants the GPU hero turns on facett-releaseview/graph3d + facett-graph3d/wgpu.

b.2 — map ReleaseConvergence → a 3-plane CodeGraph (new facett-releaseview/src/vault.rs, #![cfg(feature = "graph3d")]):

The clean reuse move — express the three planes as depth-staggered copies of the DAG in ONE CodeGraph, then hand it to CodeVault, whose orbit camera + depth-sorted projection + GPU bloom give the real depth the CPU parallelogram fakes:

/// Lower the convergence model to a CodeGraph whose nodes are placed on three depth
/// planes (LOCAL front, SPARRING mid, CRATES_IO back). A CONVERGED crate contributes
/// ONE box at the merged position; a DIVERGED crate contributes a box on each plane it
/// differs on, joined by a convergence "beam" edge. Divergence maps to CodeVault's
/// NodeState so the existing red-flicker / amber-glow IS the fix signal.
pub fn convergence_to_codegraph(conv: &ReleaseConvergence, separation: f32) -> (CodeGraph, Vec<[f32;3]>)

• Colour per plane box: reuse the existing role_color (lib.rs:92) — local=blue, sparring=amber, cratesio=green — fed into CodeNode::color (codevault.rs:114).
• State per box: map ConvergeStatus::severity() (model.rs:82) → NodeState (codevault.rs:55): severity 2 (NeedsRelease/LockDesync) → Glitch (red flicker = the release/lock blocker throbbing — reuses the whole flicker/box_look lane codevault.rs:325,344); severity 1 (BumpDrift) → Changed (steady amber); converged/publishing → Ok.
• Explicit plane placement: Node3.pos is a PUBLIC field and the doc calls it "the shared-placement seam nornir's funnel3d uses" (facett-graph3d/src/lib.rs:117,265). After CodeVault::new(graph, Layout3D::Force), overwrite graph.nodes[i].pos per plane: reuse the Force/toposort X,Y from the layout, set Z = plane_depth × separation (local Z=-sep, sparring Z=0, cratesio Z=+sep), so separation = 1 − converged_fraction (model.rs:318) drives the planes together exactly like the CPU separation() (lib.rs:300) — same math, real depth buffer. Expose a tiny CodeVault::set_positions(&[[f32;3]]) OR a Graph3D-level placement setter if one isn't public yet (check facett-graph3d/src/lib.rs around layout() at :527; the positions are already pub, so a thin with_positions builder is the minimal add).
• Edges: intra-plane dep edges (from the model's DepEdge, model.rs:222) on each plane the crate is present, PLUS the cross-plane convergence beams for a diverged crate (connect its local/sparring/cratesio copies). CodeVault already renders glitchy edges red-flickering (codevault.rs:473), so a beam into a glitch box reads as the corrupted convergence line — the CPU render's beam (lib.rs:417) upgraded to 3D + bloom.

b.3 — the hero render path. Add ViewMode::Vault3D (third variant, lib.rs:53). In paint (lib.rs:327) route Vault3D to a CodeVault::view call:

• Hold an Option<CodeVault> on ReleaseView (rebuilt when the model or separation changes, like dag is rebuilt at lib.rs:170). Because CodeVault reuses Graph3D's injected clock (codevault.rs:300), thread ReleaseState.clock_s (lib.rs:110) into CodeVault::with_clock so the whole view stays deterministic/headless-snapshottable.
• CodeVault::view returns CodeVaultMsgs (orbit/select) — translate CamMsg::SelectNode(i) back to Msg::SelectCrate by looking up which crate the box i belongs to (keep an i → krate map alongside the codegraph). Orbit/spin msgs pass straight through to the embedded camera.
• The GPU bloom lane is CodeVault::gpu_scene(w, h, phase) (codevault.rs:562, #[cfg(feature="wgpu")]) → feed to graph_gpu::GraphGpu (graph_gpu.rs:152). The egui_wgpu paint-callback wiring is the same one facett-graph3d already uses for the cloud (facett-graph3d/src/lib.rs:284 with_gpu); reuse it, don't hand-roll a pipeline.

b.4 — keep CPU planes green. ViewMode::Planes3D (lib.rs:344) and TriBadge2D (lib.rs:467) are untouched and remain the default when graph3d is off. The toolbar (lib.rs:578) gains the Vault3D toggle only under #[cfg(feature = "graph3d")].

Tests:

• convergence_to_codegraph_places_three_planes_and_maps_severity (in vault.rs) — a diverged model yields 3 boxes for the diverged crate with distinct Z, Glitch state for the severity-2 crate; assert via CodeGraph::glitch_count (codevault.rs:154) and the returned position Z spread. Converged crate → 1 box, Ok.
• separation_collapses_planes_as_convergence_completes — separation=0 (fully converged) ⇒ all three Z coincide (RED-when-broken: the planes must actually snap together).
• Reuse CodeVault's existing headless render proof pattern (codevault.rs:921 headless_render) to assert the vault draws + state_json["glitch_count"] matches the diverged count.
• These run under --features graph3d; the existing CPU render tests (facett-releaseview/tests/render.rs) stay feature-free and green.

(c) dwarves release watch — stream the convergence

The stream already exists. The release cascade writes an append-only NDJSON event log release-run-<run_id>.events.ndjson via progress::ProgressWriter (progress.rs:134,141), one progress::ReleaseEvent per line (progress.rs:42). watch tails that file and maps engine events → facett model::ReleaseEvent (model.rs:255) → ReleaseConvergence::apply (model.rs:330), which flips one crate at a time and drives the animation.

c.1 — CLI subcommand (main.rs, in enum Cmd after Release at main.rs:113):

/// Watch a release cascade converge live: tail the run's progress events and render
/// the three-graph convergence (LOCAL · SPARRING · CRATES_IO snapping together).
/// Text by default; `--json` streams the convergence state_json per update.
Release... /* add: */
Watch {
    #[arg(default_value = ".")] path: PathBuf,
    /// The run to follow (else the newest release-run-*.events.ndjson under the log dir).
    #[arg(long)] run_id: Option<String>,
    /// Emit convergence state_json per update instead of the text readout.
    #[arg(long)] json: bool,
    /// Poll interval ms for the tail.
    #[arg(long, default_value = "500")] interval_ms: u64,
},

Wire it in fn main's match (main.rs:324) → watch_cmd(path, run_id, json, interval_ms). Gate behind #[cfg(feature = "convergence")] (it needs the adapter + model).

c.2 — watch_cmd:

1. Build the initial ReleaseConvergence via convergence::gather_convergence(repo_root, graphs, sparring=None) (before any publish → sparring tracks local, cratesio = current published).

2. Resolve the events file: --run-id → release-run-<id>.events.ndjson, else newest by mtime in the log dir (same dir ProgressWriter::open writes, progress.rs:141).

3. Tail loop (poll every interval_ms, seek past consumed bytes): parse each new line as progress::ReleaseEvent; map:

   • PhaseStart { repo, phase: "publish" } → for each crate in that repo, model::ReleaseEvent::PublishStart { krate } (flips to Publishing, pulses).
   • PhaseEnd { repo, phase: "publish", ok: true } → model::ReleaseEvent::Published { krate, version: local_ver } (crate lands on the published target → re-derives to Converged).
   • RepoEnd/RunEnd → final re-probe of crates.io for the just-published repo (authoritative) and a last render. Apply each with conv.apply(ev) (model.rs:330); on true (a node changed) re-render.

4. Render per update:

   • --json: print convergence_state_json(&conv) (the LAW-6 blob from (a)).
   • default text: a compact readout REUSING the model's own tallies — converged_fraction (model.rs:318) as a percent bar + status_counts (model.rs:295) as ✓N ⚑N ⌥N ~N ⟳N, mirroring the view's legend line (lib.rs:543). One line per changed crate: krate L{local} S{sparring} C{cratesio} {status.label()}.

5. Exit 0 when conv.is_converged() (model.rs:311) after RunEnd; non-zero if the run ended with a non-converged/blocked crate.

No new event schema — this is a pure consumer of the existing progress NDJSON, mapped through the model's existing realtime seam. (If a build agent later wants the WAREHOUSE-backed stream instead of the file tail, the release_events::ReleaseEventRow + read_release_events/EventSelector path release_events.rs:283,295 is the drop-in richer source over the Viz.ReleaseEvents RPC; the file tail is the fat/serverless default.)

Tests (crates/dwarves/tests/, e.g. convergence_watch.rs):

• watch_maps_publish_events_to_convergence — feed a synthetic NDJSON (PhaseStart publish → PhaseEnd publish ok) through the mapper against a fixture model; assert the crate walks Publishing → Converged and is_converged() flips true at RunEnd. RED if the phase→event mapping or the tail-parse breaks.
• CLI smoke in cli_smoke.rs — dwarves release watch --json on a fixture events file prints valid convergence JSON and exits 0.

Sequencing for the build agent

1. (a) adapter first — pure build_convergence + tests (no facett GPU needed; only the model types). Land green under --features convergence.
2. (c) watch CLI — depends only on (a) + the existing progress stream. Land green.
3. (b) GPU planes — the heaviest; depends on facett-graph3d wgpu. Land the convergence_to_codegraph mapping + CPU-headless vault tests first (no GPU), then the egui_wgpu paint-callback wiring behind graph3d+wgpu. CPU Planes3D stays the default the whole time.

Laws honored

• REUSE (L5): three version probes reuse cargo::publishable_crate_versions + registry::{CratesIoBackend,CustomBackend}; the GPU hero reuses CodeVault/Graph3D/graph_gpu verbatim (only placement + state-mapping is new); watch reuses the progress NDJSON + ReleaseConvergence::apply. No twins.
• One-way / facett-pure: dwarves→facett dep only; the adapter feeds the neutral model IN. facett-releaseview never learns dwarves (model.rs:1-6).
• Testable + emitters + robot (L6): every new seam has a state_json + a red-when-broken test + a functional_status matrix row.
• No new content-id / no rayon / no Python: nothing here spawns a CPU pool (the projection fan-out is already gatling inside facett-graph3d, facett-graph3d/src/lib.rs project_all); no shell, no Python.