nordisk/nornir

Guide

Class: guide · audience: a techie driving nornir over a real workspace. This is the f0 file — the end-to-end workflow that spans every function. Each function then has its own deep guide (*-guide.md); this one is the through-line and the map into them. The what (architecture) is in design.md; the why is in reasoning.md.

f0 — one session, start to finish (the whole)

nornir is one workspace-orchestrator: a handful of peer verb-functions over a single warehouse substrate, reached through a few surfaces (CLI, viz, serve, key). A full session touches several functions in order — each writes its facts into the same SHA-keyed warehouse, so the next function reads what the last one recorded:

1. Appoint the workspace. Tell nornir which crates are one set:

nornir workspace register <name> --descriptor nornir-workspace.toml

The registry (redb) becomes the source of truth for monitored-ness; a fetch clones each member and republishes its knowledge + dep-graph into that workspace's warehouse. → deep dive: workspace-guide.md.

1. Know the code. The republish hook scans every member (syn, fanned across cores), filling the warehouse — the dep-graph, knowledge/SCIP, arch, index and vector tables that every later step queries. → warehouse-guide.md, and query it with SQL: nornir warehouse query "SELECT …" → sql-guide.md.
2. Gate it. Run the multi-aspect matrix — build · unit · doctest · clippy · fmt · audit — plus bench (which gates like a test) and coverage:

nornir test <name>

→ test-guide.md.

1. Build variants + provenance. nornir build … produces the declared build goals and an attestation. → build-guide.md.
2. Release. Advise → rehearse → promote to crates.io, gated, over the component dependency DAG:

nornir release advise <name>
nornir release rehearse <name>
nornir release promote <name>

→ release-guide.md (and the doctor: release-doctor-guide.md).

1. Publish the docs. Regenerate README + the three books from .nornir/:

nornir docs render <name>
nornir docs book <name>

→ docbook-guide.md.

Every long-running step above (fetch, republish, bench, render, release) self-registers a row in the jobs ledger, so the viz shows live progress — jobs-guide.md. To carry all of this into a network-isolated box, seal it: airgap-guide.md.

The function map (where each guide lives)

Surfaces (how you reach any of the above)

• CLI — nornir <function> <verb> (src/bin/nornir.rs); the primary surface, used in every example in the per-function guides.
• viz — the egui app (nornir viz / the urðr-threads UI): watch jobs, tests, releases and the warehouse live.
• serve — nornir-server (gRPC) + nornir-mcp (MCP thin client): the same functions, driven by a remote or airgapped agent by query.
• key — identity for signing/publishing.

Operator knobs — memory of the served process

The server caches decoded hot tables for Mímir; the cache is charged in bytes and logs every cap-hit. If the served process grows fat, or you want it leaner on a small box, set (units 4g / 512m / bytes):

• NORNIR_WORKING_SET_MAX_BYTES (default 4g) — whole decoded-table cache; LRU evicts, each eviction logged.
• NORNIR_PREVIEW_MAX_BYTES (default 1g) — one table's preview decode; a cut table is logged by name.
• NORNIR_ARROW_MAX_BYTES (default 2g) — one table's Arrow decode; same loud cut.

Read the journal for working-set lines: ⏱ working-set warm … resident = X (budget Y; …) after every populate, CUT at / evicted / NOT retained at every cap. See design.md → Memory bounds of the served process.

The three deployment modes (fat local · server-monitored · thin client) frame where a session runs; the workflow above is identical in each. See design.md for the architecture and reasoning.md for why the shape is this way.