nordisk/nornir

nornir architecture wiring — the code-derived map

EPIC ARCH (nordisk plan). The complete, code-derived picture of how every nornir mechanism is wired: ONE core lib with many faces, the sibling crates + ecosystem peers, and — the heart of the ask — which warehouse table each of the 24 viz panes reads/writes and the exact flow path (fat = direct IcebergWarehouse open; thin = which Viz.* / Warehouse.* / … gRPC verb → server → table). Derived by reading src/viz/*, src/bin/nornir-server.rs, src/viz/model.rs, proto/nornir.proto, and cross-checked against warehouse-schema.md (the gold table↔write/read map).

This is the human-authored data model behind EPIC ARCH / AUT7. The long-term plan (ARCH2/ARCH3) is to auto-generate this from call_edges + the new fn→table access fact + the UI-Facet ∩ registry() enumeration, rendered skade-style. Until then, this doc is the source of truth and the spec the generator must reproduce.

0. Where this lived before (gap analysis)

What already existed in .nornir/:

• EPIC J flow SVGs (circuit-board house style, all embedded in docs): release_events_flow.svg (J3), warehouse_layers.svg (J3), deployment_modes.svg + test_matrix_pipeline.svg + viz_thin_rpc.svg (J3b), nordisk-constellation.svg (J5).
• Mode docs: mode-matrix.md, viz-modes.md, design.md.
• The warehouse table map: warehouse-schema.md — every table's write-site and read-site, exhaustively.

The GAP this doc closes: there was no single per-pane → table(+RPC+flow) map for all 24 viz panes, and no one all-component wiring board that draws the constellation, the thin/fat/server flow, and the pane↔table flow together. viz_thin_rpc.svg showed the mechanism (mode resolve → a token-bearing verb → Arrow batch → table) for one generic pane; warehouse-schema.md listed read-sites in prose. Neither answered "open the Test tab — what does it read, by what path?" for every pane at once. That table + the new architecture_wiring.svg are the new artifacts.

No drift was found between the existing SVGs and code; this doc synchronizes text + picture by embedding the relevant existing SVGs alongside the new per-pane board, so every claim here has a matching figure.

1. Component constellation — one core, many faces

nornir is one core library (nornir, src/lib.rs) with several faces, each a thin binary or surface over the same core:

Sibling crates (in this repo's crates/) and ecosystem peers:

1a. holger in the picture

Holger (/run/media/rickard/T9/git/holger, codeberg.org/nordisk/holger) is a secure, airgap-first artifact server. Its shape rhymes with nornir's:

• One trait, many backends. RepositoryBackendTrait (traits/src/lib.rs) is the single seam — every ecosystem (Maven/Python/Rust/npm/NuGet/Go/Gem/Deb/RPM/ Helm/Docker/Conda/Composer + native znippy-package) is a plugin boxed as Arc<dyn RepositoryBackendTrait>. The engine dispatches through the vtable via an O(1) FastRoutes table and never matches the concrete type. (Compare: nornir's one core, many faces.)
• Config is a graph. A RON holger.ron of ExposedEndpoint ← Repository → StorageEndpoint nodes, resolved by wire_holger() (server/lib/src/lib.rs).
• Dual transport behind one HolgerObject facade: LocalHolger (in-process) vs RemoteHolger (gRPC/tonic) — the same fat/thin split nornir's viz has.
• Storage = immutable znippy archives (blake3 content-addressed, one per repo version, random-access ZnippyReader::extract_file — no full decompress), carriable across the airgap. This is the same znippy nornir depends on.

How they relate: nornir monitors holger as a workspace repo (it appears in nordisk-constellation.svg as a monitored repo) — so holger gets a dep graph, release lineage, knowledge map, test matrix, etc. like every other nordisk repo. And holger is nornir's release target: where nornir release publishes crates / where skidbladnir (Skíðblaðnir, EPIC AIRGAP; sibling repo ../Skidbladnir) ships a bundle's artifacts to be served on the secure side.

The constellation figure (deps + orchestrator role over the monitored repos holger · skade · znippy · knut · facett · korp · njord):

Figure 1 — the constellation (EPIC J5). nornir orchestrates; holger/skade/znippy/facett are peers.

2. Per-UI-pane → warehouse-table flow (the heart)

The viz has 24 tabs (pub const ALL: [Tab; 24] in src/viz/app.rs — the authoritative header order: Nornir, Timeline, DepGraph, CallGraph, Architecture, Metro, Helix, Bloodstream, Funnel, TimeTravel, LiveRun, Release, Knowledge, Warehouse, WarehouseDeck, Mcp, Search, Gates, Bench, Test, Leaderboard, Security, Holger, Manual). The 16 numbered rows below are the original data-bearing panes; rows 17–21 are five chrome/overview panes (Nornir, Architecture, Metro, Holger, Manual). Three newer tabs — Helix, Bloodstream, and WarehouseDeck — are also in Tab::ALL (24 total) but are not yet broken out as rows here. Each pane is built local(...) (fat) or remote(endpoint, token, workspace) (thin) at construction (UrdrThreadsApp::new matching on Source::Local vs Source::Remote). Its load()/refresh()/hydrate() then either opens the warehouse direct or calls a gRPC verb. Every pane exposes what it renders in state_json()[key] (LAW #6).

Authoritative map — derived from each pane's loader in src/viz/* and the matching Viz.* impl in src/bin/nornir-server.rs (impl VizSvcTrait for VizSvc at line 2817) + proto/nornir.proto (the Viz service from line 809).

2a. The contract the Viz.* RPCs honor

The five dedicated Viz.* data RPCs are thin mirrors of the fat query fns — same data, JSON-serialized — because the server holds the redb lock so a thin viz can't open the warehouse (src/bin/nornir-server.rs):

• Viz.Timeline → build_timeline(&wh, ws, root) → release_lineage + dep_graph_edges.
• Viz.ReleaseEvents → query_release_events(&wh, EventSelector::All) → release_events.
• Viz.TestResults → query_test_results(&wh, TestSelector::All) → test_results.
• Viz.BakeoffResults → query_agent_model_runs(&wh, BakeoffSelector::All) → agent_model_runs.
• Viz.BenchTelemetry → query_bench_telemetry(None) + query_bench_runs → bench_telemetry + bench_runs.
• Viz.Knowledge → server runs knowledge::scan_all over each member clone (the thin client has no checkout).

The write-back RPCs (so a fat CLI run lands in the locked server warehouse) live on the Telemetry service: SubmitReleaseEvents → release_events, SubmitTestResults → test_results, SubmitBakeoff → agent_model_runs, SubmitMcpCalls → mcp_requests. These honor the LAW "persist to warehouse, stream not /tmp".

2b. The pane↔table wiring board (NEW SVG)

Figure 2 — the 23-pane wiring board (this doc's primary new artifact; the SVG still renders the 16 data-bearing panes — regenerate to add the seven overview/chrome panes). Pane → gRPC verb → table → warehouse ground rail. THE pane↔table map.

2c. Known coverage gaps (from the code)

• Search, Gates have no fat path — they are server-only; in local mode the pane shows a hint. (Search needs the warm Tantivy index + embedder the server holds; Gates runs gate logic against bench_history.jsonl.)
• CallGraph, Mcp use the generic Warehouse.Scan in thin mode (not a dedicated Viz.* verb) — they read symbol_facts/call_edges and mcp_requests by scanning.
• DepGraph / TimeTravel have no dedicated DepGraph RPC — the dep snapshots ride inside the Viz.Timeline JSON response.
• The MD-MATRIX test (tests/viz_md_matrix.rs) tracks the thin-present cells; the dedicated Viz.* verbs (ReleaseEvents/TestResults/BakeoffResults/ BenchTelemetry) closed the earlier Release/Test/Leaderboard/Bench gaps.

3. Thin / fat / server data flow (the mode example)

The pane↔table map above is parameterized by mode. The three modes (mode-matrix.md):

• Fat (embedded): the human's CLI/viz opens the warehouse in-process and owns the redb lock. Every "Fat path" cell in §2 is a direct call.
• Server-monitored: the nornir server clones member git URLs and runs the same verbs under its write lock; it is "thin against itself, fed by pull."
• Thin client: the viz holds no lock; every "Thin path" cell is a token-bearing gRPC verb to the server, which owns the lock.

Figure 3 — fat / server-monitored / thin (EPIC J3b). The example the ask kept as one section.

The mode-resolution → token-bearing verb → Arrow batch → table mechanism for a single thin pane (the generic shape every "Thin path" row in §2 follows):

Figure 4 — the thin-RPC mechanism (EPIC J3b), one pane generalized.

4. The warehouse layers + the two flagship flows

The ground rail of every row in §2 is the IcebergWarehouse — Apache Iceberg (iceberg-rust) over a single-file skade-katalog redb catalog, append-only, so each append mints a snapshot (free time-travel). Its read-acceleration layers:

Figure 5 — warehouse layers (EPIC J3).

The two write-flows that feed the busiest panes:

Figure 6 — release_events DAG flow → 🚀 Release + 📡 LiveRun (EPIC J3).

Figure 7 — test-matrix pipeline → 🧪 Test (EPIC J3b).

Full per-table schema, write-sites and read-sites: warehouse-schema.md.

5. This is the data model behind EPIC ARCH / AUT7

The §2 table is the human-authored version of the graph EPIC ARCH/AUT7 will auto-generate:

• Nodes: UI-component (pane) · gRPC verb · core fn · warehouse table.
• Edges: pane → verb (from Facet ∩ registry() + the tab enum × {thin,fat}), verb → core fn (from call_edges), core fn → table (the new fn→table access fact, ARCH2).
• Render: the AUT7 owner-fn quotient of call_edges, drawn skade-style (Typst→SVG, never mermaid), regenerated by nornir docs (ARCH3), surfaced as nornir arch [svg | trace <entrypoint>] + an MCP tool reusing knowledge_call_path (ARCH5).
• Storage: per-workspace_*/ asset (travels with source) and/or a warehouse architecture_wiring table historized by git sha (ARCH4).

When the generator lands, regenerating this doc's §2 table + Figure 2 from the warehouse must reproduce exactly what is hand-derived here — this doc is the acceptance fixture.

6. The generator has landed (ARCH1–5 / AUT7) — how to use it

The auto-generator now exists in code (src/arch/mod.rs + src/arch/warehouse.rs), so §5 is no longer forward-looking. The mapping from plan item to code:

CLI usage (fat, in-process):

nornir arch generate <repo>        # scan → coarsen → render → historize (git-sha keyed)
nornir arch svg <repo> [--out f]   # print/write the wiring SVG without historizing extra rows
nornir arch trace <repo> <entry>   # focused sub-board reachable from an entrypoint (the flow trace)
nornir arch history <repo>         # list historized snapshots, newest first

MCP parity (LLM agents, reads the latest historized snapshot from the warehouse): arch_svg{repo} → the board SVG · arch_graph{repo} → the graph JSON · arch_trace{repo,entrypoint} → the reachable sub-board SVG (the visual twin of knowledge_call_path).

Naming note (deviation from the plan prose, by design): the plan sketched the trace surface as nornir flow <entrypoint> + a flow_trace MCP tool and a Typst render under nornir docs. The shipped surface folds the trace into the arch verb (nornir arch trace) and the arch_trace MCP tool — one cohesive arch namespace — and renders a direct-emit skade SVG (no Typst layout engine, so it works in every feature set). The skade-style / no-mermaid / owner-fn-quotient / fn→table / warehouse-historized intent is met verbatim; only the verb/tool names and the (Typst→)SVG mechanism differ.