.nornir/supporting-subsystems-guide.md · nordisk/nornir

Supporting subsystems (this run) — guide

Class: guide · audience: a techie driving the four supporting subsystems this run added. The what is in supporting-subsystems-design.md. Grouped: A funnel flow-sim · B job coverage · C robot-UI matrix · D warehouse/release/SCIP.

A — simulate a project's flow to completion

The funnel tab can time-step a whole project DAG wave-by-wave to Done, so you see how many waves it takes and which nodes stall.

In nornir viz (local mode), open the 🗂 Funnel tab and press ▶ Simulate flow. It replays the funnel from disk and advances every plan's DAG to completion, reporting:

waves — how many time-steps it took (= the longest dependency chain).
done / failed / remaining / total — the final tally. remaining > 0 means some nodes can never become ready (they depend on a failed node).

The result is at state_json["funnel"]["sim"], so a robot / operator reads it back. The button is disabled in remote mode ("Simulate is local-mode only").

Programmatically it's funnel_core::simulate_flow(&mut funnel, steps) (all-ready-nodes-to-Done), or simulate_flow_with(&mut funnel, steps, policy) to script a node as Failed and watch its dependents stall.

B — watch the new op families in the job ledger

Every long op this run added self-registers in the jobs ledger — you don't start these jobs, you read them:

nornir jobs --kind saga_capture     # each viz ⏹ Stop (drain → saga_events)
nornir jobs --kind ci_build         # each brokkr pipeline run (parent + a child per step)
nornir jobs --kind monitor_fetch    # each nornir monitor poll-tick fetch sweep
nornir jobs --kind security_scan    # the local SBOM/security scan
nornir jobs --kind docs_book        # docs book/render/export
nornir jobs --running               # anything still in flight, any kind
nornir jobs --json | jq '.[] | select(.status=="failed")'

A row that shows failed with "dropped without finish/fail" means the op panicked or ?-returned early — the ledger's Drop guard caught it, so there's never a zombie running row. This is the one place to answer "what ran, and did it finish?" across saga, brokkr, monitor, security and docs alike.

C — run the robot-UI matrix (every surface a scenario)

The headless robot suite drives the real viz and asserts every surface renders. Run the whole UI matrix:

cargo test --features "viz robot" --test viz_uiplane_walk     # walks every TAB_PANE_BLOCK surface
cargo test --features "viz robot" --test robot_full_nav       # ~25 tab headers
cargo test --features "viz robot" --test robot_funnel_journey # intake + demo + ▶ Simulate flow
cargo test --features "viz robot" --test viz_brokkr_robot     # the Brokkr tab, Run → green
cargo test --features "viz robot" --test robot_ops_journeys
cargo test --features "viz robot" --test robot_misc_tabs

Seven tabs — Metro, Helix, Bloodstream, WarehouseDeck, Build, Claude, Models — were reachable but had no declared surface, so the uiplane walk silently skipped them. They're now in TAB_PANE_BLOCK (src/viz/uiplane_plan.rs:49), so the walk runs a real row per tab: GREEN when the pane renders, RED when it doesn't. Adding a new tab means adding its (Tab, block) pair there so it can never become a silent hole.

D — the completed read + gate surfaces

D1 — read the write-only warehouse tables back.

# The airgap-op DAG (was write-only; now readable):
nornir airgap events

# The #[cfg(...)]-gated items for a repo (needs a symbol scan first):
nornir knowledge scan <repo>
nornir knowledge query <repo> feature-gates

# dep_graph now keeps unresolvable edges as labelled placeholder rows —
# an edge with no justifying `via` crate no longer vanishes from the snapshot.

D2 — the release gates. The no-regression gate now knows metric direction:

throughput-shaped (_mbs, higher-better) → a drop past the threshold is a regression;
latency-shaped (_ms, p99, latency, lower-better) → a rise past the threshold is the regression (metric_lower_is_better, src/release/gate.rs:227).

nornir doctor (release) additionally cross-checks the source dependency graph against the ELF/binary graph extracted from the linked binaries (graph_from_binary, src/release/doctor.rs:2151): a cycle present in the linked binary but absent from the source manifests is caught (Tarjan SCC partition compare).

D3 — resolved find-usages (SCIP).

# Ingest a rust-analyzer SCIP index (feature scip), SHA-keyed to HEAD:
nornir scip ingest <repo>
nornir scip ingest <repo> --in-process     # link ra_ap_* in-process (feature ra-ingest), no index.scip

# Precise, RESOLVED find-usages over the latest persisted SCIP map:
nornir scip query <repo> usages <symbol>
nornir scip query <repo> defs   <name-substring>
nornir scip query <repo> delta  <symbol>    # resolved-vs-syn precision comparison

With a resolved SCIP map present, nornir knowledge graph prefers it over the syn map (src/bin/nornir.rs:4888); without --features scip the syn map is used as before.

Where the same data shows up

nornir jobs — the one ledger across every op family (A's sim isn't a job; B/brokkr/saga/monitor/security/docs are).
the robot matrix rows are the CI twin of clicking every tab by hand.
nornir airgap events / nornir knowledge query … feature-gates / nornir scip query all read warehouse tables the write side already populated.