# Móðguðr — guide (f0, the whole)
> **Class:** `guide` · audience: a techie driving modgunn end to end. The *what* is in
> [`design.md`](design.md); the *why* in [`reasoning.md`](reasoning.md). This file is the
> workflow that spans functions; per-function how-tos are each `{fn}-guide.md`.
## f0 — a full session
modgunn ships as a **library** (both engines) plus one **binary** (`modgunn`, the secure-side
warehouse driver, `required-features = ["warehouse", "scan"]`). A whole session is three moves:
```sh
# 1 · build the plane you need
# The BINARY has exactly ONE build door — the declaration in
# `.nornir/build-variants.toml`, resolved by the one build verb. Do NOT hand-write a
# `cargo build --features …` for it: a second recipe is a second declaration, and the
# two drift.
cargo xtask build --suite ORIGINAL # the `modgunn` binary (client · fat), as declared
dwarves buildthing modgunn --suite ORIGINAL # the same resolver, from outside the repo
# The raw feature axis below is for CONSUMERS LINKING THE LIBRARY (holger's gate,
# static-holger, nornir) — it names no binary.
cargo build # Engine A — the lean artifact verdict (default = scan)
cargo build --features scip # + Engine B — the heavy world-delta
# 2 · import an offline advisory generation (secure side)
modgunn warehouse import --warehouse <root> --rev 2026-07-04-a \
--osv <dir> [--nvd <dir>] [--malicious <dir>] [--epss epss.csv] [--kev kev.json]
# 3 · scan the whole fleet against it
modgunn warehouse scan --warehouse <root> [--since <snapshot_id>] [--vex <dir>] [--sql]
modgunn warehouse stats --warehouse <root> [--ecosystem cargo]
```
`import` reads every `*.json` under each `--<feed>` dir, merges + dedups by alias, enriches
with EPSS/KEV, and appends the corpus as a new `db_rev` generation (`main.rs:cmd_import`).
`scan` joins the whole `sbom_components` table × the latest advisories and prints every
vulnerable dependency; `--since <snapshot_id>` does the **incremental CDC delta** — only the
components added since that snapshot, printing the next watermark to poll (`main.rs:cmd_scan`).
To embed the gate in another Rust app, depend on modgunn with no extra features and call
Engine A directly — see [`verdict-guide.md`](verdict-guide.md). To run the world-delta, see
[`worlddelta-guide.md`](worlddelta-guide.md).
## Per-function how-tos
| function | do this | guide |
|---|---|---|
| **verdict** | build a `Policy` + `AdvisoryDb`, call `OsvScanner::scan(&artifact)` | [`verdict-guide.md`](verdict-guide.md) |
| **feeds** | parse a feed dir → `merge_by_alias` → `enrich` → `Advisory`s | [`feeds-guide.md`](feeds-guide.md) |
| **warehouse** | `Warehouse::open` → `append_advisories` / `scan_fleet` / `table_delta` | [`warehouse-guide.md`](warehouse-guide.md) |
| **worlddelta** | build two `WorldSnapshot`s → `scip::diff` → read `BehaviorDelta` | [`worlddelta-guide.md`](worlddelta-guide.md) |
| **provenance** | `ProvenanceRequirement::evaluate(att)` → findings | [`provenance-guide.md`](provenance-guide.md) |
| **sbom** | build a `SbomInput` → `to_cyclonedx` → serialize | [`sbom-guide.md`](sbom-guide.md) |
| **rollup** | `rollup_fleet_findings(&findings)` → `FleetRollup` | [`rollup-guide.md`](rollup-guide.md) |
## Which feature do I need?
- **holger's gate / static-holger** — nothing: `default = ["scan"]` links Engine A only, no
toml/arrow/iceberg tree.
- **nornir's security plane** — `features = ["warehouse", "rustsec"]` (skade is already a
nornir path-dep, so no new tree).
- **the world-delta site** — `["scip", "warehouse"]`; add `warehouse-sql` for the DataFusion
fleet-join pushdown at S3/S4 scale.
- **CI / `nornir test`** — add `testmatrix` so each functional surface ships a
`functional_status` row (a compiled-out no-op otherwise).