nordisk/heimdall

Kernel tooling v2: the design as built

This is the current design of the nordisk kernel tooling, as the code on main has it on 2026-11-04. It supersedes ../KERNEL-TOOLING-MAP.md, the read-through of 2026-11-03 that found the gaps. That document is kept as history. Every claim here names the file that does it. Paths are repo-relative, and the repo is named first: edda, tunnr, heimdall, dwarves, nornir or holger. Planned items are listed only in the short "Next" section at the end.

1. What it is for

The tooling builds the smallest kernel a row can boot. A row is one appliance medium. The kernel must still carry everything the row's programs need, and every CONFIG_X=n must be backed by evidence. The evidence comes from four places:

Build Thing joins these files to the kernel tree. It then decides what the row's kernel must keep, and what a veto may drop.

2. The three homes

The tooling lives in three homes, and the homes share nothing but files. Each file has a schema and a validator. No home links another home's code. Build Thing is MIT and never links Heimdall, which is AGPL. Mímir's walk is the owner's engine, and no lane writes a second one.

The files all have one definition, in the MIT crate nordisk-kernel-evidence (edda crates/nordisk-kernel-evidence; see section 8).

3. Every schema'd file

4. Data flow

 Mímir (nornir)                         Heimdall tooling                        Heimdall runtime
 ────────────────                       ─────────────────                       ────────────────
 consume (driver dumps every crate,     measure.toml                            heimdall kernel needs --json
  registry crates from a crates.io       │ measure syscalls <row>                 │
  mirror: MIMIR_CRATE_MIRROR)            │  (edda measure.rs runs heimdall)       ▼
   │                                     ▼                                      .nornir/kernel-runtime-needs/
   ▼                                    .nornir/profiles/<row>/                   <name>/heimdall.json
 lake ──► mimir-room possible ──►         measure.json, <prog>/*.probe.json         │
                       graph.json ──────► <prog>/graph.json                         │ kernel requires-from-needs
                                          │            │                            ▼
                                          │            └► dwarves-tune-graph      [[build.installer.requires]]
                                          │               --graph --profile         (generated rows)
                                          ▼               (cross-check)              │
 Build Thing (edda)                     syscall_join (measured ⊆ possible)          │
 ───────────────────                      │ kernel needs <row> --save               │
 [[build.kernel]] + preset + profile      ▼                                         │
 + requires (consumers, vetoes =n) ──►  kernel-needs.json ──► dwarves tune show     │
   merged fragment ◄──────────────────────────────────────────────────────────────┘
   │ container build (draupnir), pin, ledger key
   ▼
 .kernel-out/<name>/bzImage ──► installer medium ──► kernel-suite.sh (KVM, gcov probe)
                                                        │ kernel coverage <row> --run <suite>
                                                        ▼
                                      .nornir/kernel-coverage/<row>/<sha12>.json
                                                        │ kernel candidates / kernel veto CONFIG_X
                                                        ▼
                                      receipt (nornir.kernel-veto/1) + veto list line
                                                        │ veto::check_list (every verb, the build)
                                                        ▼
                                      =n requires in the next merged fragment

 every file above ──► kernel_facts::gather ──► nornir.kernel-facts/1 ──► MCP kernel_facts, docs/ai-context.md

5. The verbs

6. The veto and receipt rule

A veto is one row-level CONFIG_X=n, applied by one run of kernel veto <row> CONFIG_X (edda kernel_trim/veto.rs run_veto). The run goes in this order:

1. The symbol must be a candidate the static what-if calls clean. A drop that takes away a measured call's option is refused by name (syscall_join::vetoes_for). So is a drop that takes away a possible call's option (possible_vetoes_for).
2. The coverage on the row's current fragment must say the symbol is never executed. It must also not be protected: protect.list, and the probe's own symbols (PROBE_ALTERED).
3. The vetoed kernel is composed, and the inverse check must hold.
4. The row's suite runs again on the vetoed kernel. A green rerun appends the list line and writes an applied receipt. A red rerun writes a refused receipt and leaves the list unchanged.

The build trusts the list only through its receipts. veto::check_list runs before every kernel verb except vetoes and requires-from-needs. tunnr's preflight and kernel-probe run it too, through check_row_vetoes. Each line must name an applied receipt for its row and symbol. That receipt's before and after fragments must be this row's merged fragment without the line and with it. Otherwise the line is refused by name: [veto-no-receipt], [veto-not-applied], [veto-receipt-mismatch] or [veto-stale]. A --repo veto lands in the other repo's .nornir/kernel-vetoes/<row>/vetoes.list (RowDirVetoStore). Both the list and its receipts are committed.

7. Possible versus measured

The rules are in edda syscall_join.rs needs. They are shown by dwarves tune show and dwarves-tune-graph:

• Measured ⊆ possible. A measured call outside the possible set is listed as outside_possible. That is a graph gap to review, because the probe is the truth.
• Possible but not measured is a call no test drove. Its options are listed with the class possible, unexercised, and the path to it is given.
• A veto may not drop an option a possible call needs (possible_vetoes_for). That holds even when no run made the call.
• A generated seccomp profile holds only what was measured. The graph never widens a filter (dwarves-tune-graph's rule).

Mímir widens rather than drops. An unresolved edge (dyn dispatch, a call through a value, a fn pointer) is widened to every target the room holds, and it is listed in unresolved_sites. So the max stays a max (nornir docs/v2/mimir/README.md §10.2). The dependency crates come from their exact sources. With MIMIR_CRATE_MIRROR=sparse+<holger>/…, the dumper's cargo takes them from Holger's crates.io mirror through its normal sparse registry door (nornir crates/mimir-ingest/src/crate_mirror.rs).

8. The evidence crate

edda crates/nordisk-kernel-evidence, licence MIT, depends only on serde, serde_json, anyhow and nornir-hash. It lives in edda because edda, tunnr and dwarves already depend on edda by path. That avoids a new repo and a new release line. Heimdall takes it from crates.io, since it is MIT and may be used under the AGPL.

These users have no copy of their own:

• edda nornir-build-thing re-exports the crate's types under its old paths (syscall_join, kernel_trim::{coverage,veto}, kernel_requires::from_needs, kernel::KERNEL_LEDGER_KEY_SCHEMA).
• dwarves dwarves-tune-graph re-exports Graph, ModuleInfo, Reach and Site.
• tunnr tunnr-build-thing reads the probe word, receipts and runtime needs through it.
• heimdall heimdall-container re-exports RuntimeNeeds under its own names. This is on branch ktool/evidence-crate, which waits for the crate on crates.io and for Heimdall 0.3.2.

The round-trip tests use real files:

• edda crates/nordisk-kernel-evidence/tests/real_files.rs covers holger's kernel-needs, tunnr's coverage and receipt, heimdall's runtime needs, and a cut of holger's graph.json.
• tunnr tests/evidence_files_round_trip.rs covers every committed coverage report, receipt and runtime needs file.

9. AI visibility

edda crates/nornir-build-thing/src/kernel_facts.rs gather(repo_root) reads every file in section 3 through its own reader. The result is one nornir.kernel-facts/1 document with a validator: kernel rows, and per row the saved needs, each program's measured and possible syscalls, coverage totals, the veto list with BACKED/UNBACKED per receipt, every receipt, and the protect list; plus Heimdall's runtime needs. A broken file fails with its path. Nothing in the document is typed by hand.

It reaches AI in two ways:

• nornir MCP kernel_facts <repo> (src/mcp_stdio.rs) returns the JSON document. It is covered by the MCP matrix harness.
• nornir docs ai-context <repo> writes docs/ai-context.md, which carries a "Kernel evidence" section. nornir injects kernel_facts::ai_section into nornir-docgen's Ctx::with_kernel_facts, so the docgen leaf links no build engine.

The public site's llms.txt lists each repository's README and file tree, and the committed docs/ai-context.md is in that tree.

Example: tunnr, cargo run -p nornir-build-thing --example kernel_facts -- <tunnr>, cut:

## Kernel evidence

### Kernel rows

| kernel | version | arch | profile | preset | toolchain | solver | lto |
|---|---|---|---|---|---|---|---|
| tunnr-kernel-k8s | 6.12.104 | x86_64 | k8s-hardened | slim | gcc | - | false |
…
### Row `rusternetes-node` (kernel tunnr/tunnr-kernel-k8s)

Needs: no saved `kernel-needs.json` (`kernel needs rusternetes-node --save`).
- program node-pid1 (x86_64 musl): measured 17: arch_prctl brk close exit_group fcntl getdents64 …
  possible: no graph.json
- coverage `.nornir/kernel-coverage/rusternetes-node/58a245df9d77.json`: tunnr-kernel-k8s 6.12.104 suite bridge GREEN on 2026-11-03T14:29:51Z: 993 symbols, 311 executed, 54 never executed, 628 unmeasured; 10 checks not run; fragment 58a245df9d77
- veto CONFIG_MOUSE_PS2_BYD BACKED (from build-variants.toml, receipt 2026-11-03T144637Z-CONFIG_MOUSE_PS2_BYD.json): never executed under suite bridge (65536 B bzImage)
- receipt 2026-11-03T144637Z-CONFIG_MOUSE_PS2_BYD.json: CONFIG_MOUSE_PS2_BYD applied on suite bridge, bzImage -65536 B, fragment after 333150ec4493, 10 checks not run
- protect.list: 47 pattern(s) never offered as veto candidates

### Runtime needs `.nornir/kernel-runtime-needs/tunnr-kernel-sandbox/heimdall.json` (heimdall 0.3.1, mode strict)

- CONFIG_SECCOMP=y (strict seccomp_filter: Heimdall strict: every job runs under a seccomp filter …)
- CONFIG_LSM∋landlock (strict landlock: Heimdall strict: Landlock must be in the LSM boot order by name …)
…

10. Node profiles and Landlock (tunnr)

Measured profiles. The rusternetes-node and rusternetes-node-aya rows pack measured seccomp profiles for every program that a probe can run under: Rusternetes, the youki shim's wait phase, the CSI node plugin and tunnr-cni. Each one is a VM leg of its row ([program.vm] how + approved in tunnr .nornir/profiles/<row>/measure.toml, read by edda measure.rs). measure syscalls <row> --check holds each leg's KVM evidence to the approved file the row packs. scripts/kernel-suite.sh <row> <suite> heimdall <out> composes the DEV probe medium (--opt heimdall-probe=on). It cuts the evidence after the suite (scripts/heimdall-evidence.py) and prints STAGE heimdall-<program> PASS|FAIL against the packed profile.

The floor stays. korp-start loads the hand-written profile (rusternetes-node/approved-x86_64.oci.json, the 361-call floor) onto the node's PID 1 and execs it. No probe can measure either of them. Each must be PID 1, and the kernel allows one seccomp listener per process tree. The floor is also the ceiling of the whole tree, pods included: privileged and Unconfined pods start below it through the shim door. tunnr crates/tunnr-build-thing/tests/measured_profiles.rs holds the floor above every measured profile of its tree.

Landlock. Rusternetes takes no Landlock domain (payloads/rusternetes-node/src/landlock.rs RUSTERNETES). The kubelet opens every pod's /proc/<pid>/ns and kills pods through libcontainer. A Landlock domain may not reach a process outside it (the ptrace rule), and the pods start outside Rusternetes. The pods take the domain instead. PID 1 starts the shim keeper (tunnr-shim-keeper, src/door.rs) under landlock::pods_rules. These rules scope signals and abstract unix sockets, and they handle neither TCP nor the filesystem. The keeper starts every shim, so all pods share ONE domain. A pod can no longer signal or ptrace PID 1, Rusternetes, the CSI plugin or the signer, nor reach their abstract sockets. Containers of the same pod still can reach each other. Every suite holds both serial logs to the filter and Landlock self-tests and to no SIGSYS kill (STAGE filter-selftest, landlock-selftest, no-sigsys). The aya suite also runs the NetworkPolicy cases (STAGE netpol).

Next (planned, not built)

• Holger's rust-remote download base from the index's config.json dl (holger branch fix/rust-remote-dl, to be merged by Holger's lane). With it, the Mímir step 3 proof runs against Holger's /cache.
• Heimdall on the evidence crate (branch ktool/evidence-crate), after nordisk-kernel-evidence 0.1.0 is on crates.io and Heimdall 0.3.2 is out.
• A graph.json beside each measured program of tunnr's rows (the mimir-sys bench step 5 on rusternetes-node and tunnr-cni). Holger's scan worker keeps its graph gzipped under .nornir/kernel-usage/, so syscall_join does not read it yet.
• One .probe.json reader in the evidence crate. Heimdall, edda and dwarves each still parse the probe by field name.