# znippy-zoomies' build thing — what the recipe declares, and why
**The code is the source (lane AG, 2026-08-30).** `znippy-zoomies-build-thing/`
is this repo's `impl BuildThing`; `.nornir/build-variants.toml` is **emitted**
from it and read back as authority by nothing:
```
cargo run -p znippy-zoomies-build-thing -- emit # regenerate the file
cargo run -p znippy-zoomies-build-thing -- toml # the emission, on stdout
cargo run -p znippy-zoomies-build-thing -- --list # the roster and its cargo argv
```
`tests/toml_parity.rs` fails for **any** reason the file and the code differ.
## What it declares
Five atoms, one per shipped executable, all `role = tool` and all
`linkage = not-applicable` — these are programs you run, that exit.
| atom | package · bin | what it is |
|---|---|---|
| `osm-katana` ⭐ | `osm-katana` · `osm-katana` | OSM → GeoParquet/PBF converter |
| `lbunzip2` | `lbzip2` · `lbunzip2` | the parallel bzip2 decompressor |
| `lgz` | `lgz` · `lgz` | the parallel gzip decompressor |
| `ljar` | `ljar` · `ljar` | the parallel JAR/ZIP reader |
| `lzip` | `lzip-parallel` · `lzip` | the parallel zip reader |
Every row is `no_default_features` with an **empty** feature list, and that is the
honest shape: this repo's deliveries are the pure-Rust decoders themselves.
`every_atom_ships_the_bare_decoder` holds it.
## What the emission changed
**The rot gate stops being vacuous.** MEASURED 2026-08-22 (and quoted in edda's
own `feature_axis` doc): with no `offers` space, this repo had **nine declared
features, zero built by any declared variant, and `gate()` returned `Ok(())`** —
green because there was nothing to ask, which is exactly the shape of a check that
can never report red. `offers` is now the union of every `[features]` name the
workspace declares, so the gate has a question with an answer: seven offered,
zero built, seven excused.
`the_feature_axis_is_asked_a_real_question_and_it_is_clean` asserts the space is
non-empty AND that `unbuilt` is non-empty AND that the gate passes — three
different facts, because the first two are what stop the third from being green
about nothing.
Every feature here is one of four things a delivery must not contain — a
COMPARISON arm against the third-party implementations this repo exists to beat
(`zlib-ng`, `gen`), a bench instrument (`timing`), a fixture downloader
(`planet-fixture`, `dev`), or a matrix mode (`testmatrix`) — plus
`search-index`, an opt-in extra output of the converter. The reasons carried over
verbatim from the hand-written file; they were already right.
**Five `[[bin]]` targets nobody builds are now written down.** The hand-written
recipe did not mention them at all: `bench_inflate_cmp`, `bench_large` and
`gen_large_zip` (ljar, behind `gen`) and `vtd_bench` and `planet_bench`
(osm-katana). All five are instruments; `planet_bench` additionally wants a planet
on disk, so a build point for it would be a button that fails on every box without
one.
## `vann-mmap`, and why it is not here
It was declared and gated NOTHING — zero `cfg(feature = "vann-mmap")` sites, no
`memmap2` anywhere — so it was DELETED rather than allowlisted, because an excuse
would have made it permanent. A flag that compiles nothing either way is worse
than no flag: a reader takes it for a capability and a coverage gate takes it for
ground somebody is watching. If the mmap path is written, the flag comes back with
it.
---
## Appendix — the reasoning that used to sit between the rows
**An archive, kept verbatim, in file order. 2026-08-30, lane AG.**
Until this day `.nornir/build-variants.toml` was hand-written, and the reasoning
above and between its rows was the most valuable thing in it. The file is
**emitted** now (`code → toml`, one-directional), and an emission carries data,
not argument — a comment typed into it is deleted by the next `emit` without
anybody noticing. So the prose is kept here rather than lost.
**New reasoning goes beside the code that acts on it** — a doc comment in
`crates/<repo>-build-thing/src/recipe.rs` — or in the section above. Never back
into the toml. This appendix is an archive of what was already written, not a
place to add to.
### after `(the file preamble)`
```text
znippy-zoomies — the suite build matrix, as data. NEW on 2026-08-03.
Read by `nornir_build_thing::suite_cli`, which is the WHOLE body of
`cargo xtask build --suite ORIGINAL [--atom <name>]` (xtask/src/main.rs) and the
same door `dwarves buildthing znippy-zoomies --suite ORIGINAL` comes through.
═══════════════════════════════════════════════════════════════════════════════
THIS FILE DID NOT EXIST
═══════════════════════════════════════════════════════════════════════════════
Measured 2026-08-03: znippy-zoomies had **no `.nornir/build-variants.toml` at all**
and **no xtask**. Five real CLI binaries shipped out of this workspace with no
declared build point anywhere — they were built by hand cargo, and `dwarves
buildthing znippy-zoomies` had nothing to ask for. Under the rule that **carrying a
`suites` tag is what makes an atom a Build Thing**, every one of them was outside
the system.
═══════════════════════════════════════════════════════════════════════════════
WHY THE FIVE-SHAPE LADDER DOES NOT APPLY
═══════════════════════════════════════════════════════════════════════════════
korp, dwarves, nornir and modgunn were reshaped onto the five shapes of
`workspace_nordisk/.nornir/build-matrix-2026-08-02.md`:
<x>-server ⭐ · <x> · <x>-cli · <x>-ui · <x>-solo
That ladder is an axis about ONE question — *where does the server live*. This
repo has no server and never will: it is a bag of decompressors and one OSM
converter. You run `lbunzip2 foo.bz2`, it exits. There is nothing to be thin
against, nothing to embed, no port, no unit, no deploy.
So every atom here is `role = "tool"` and `linkage = "not-applicable"`.
`linkage` is stated OUT LOUD rather than omitted, and that is not cosmetic:
`ServiceShape::default()` is `FatService`, so an omitted key reads as a positive
claim of self-containment that nobody made and nobody checked, and a reader cannot
tell it from a field somebody forgot. `not-applicable` says *this axis has no
answer here* in a way that IS tellable apart, and `validate_shape` holds it to
`embeds` and `reaches` both being empty.
═══════════════════════════════════════════════════════════════════════════════
THE MATRIX — five atoms, one delivery
═══════════════════════════════════════════════════════════════════════════════
SUITE ATOM ROLE LINKAGE PACKAGE BIN
ORIGINAL osm-katana ⭐ tool not-applicable osm-katana osm-katana
ORIGINAL lbunzip2 tool not-applicable lbzip2 lbunzip2
ORIGINAL lgz tool not-applicable lgz lgz
ORIGINAL ljar tool not-applicable ljar ljar
ORIGINAL lzip tool not-applicable lzip-parallel lzip
Note two names where atom ≠ package: `lbunzip2` ships from package `lbzip2`, and
`lzip` from package `lzip-parallel`. The ATOM is named for the artifact a user
runs, not for the crate — which is why `bin` is spelled out on every row and why
`xtask/tests/build_variants.rs` walks the real `[[bin]]` targets out of the
manifests instead of assuming the package name.
── WHAT IS NOT HERE, AND WHY ─────────────────────────────────────────────────
✗ `gatling` (package `rotaryengine`) · `linflate` · `znippy-zip-core` ·
`zstd-sys-rs` · the root `znippy-zoomies` crate itself — LIBRARIES. They are
linked by whoever consumes them (skade and znippy both depend on this repo),
with that consumer's own feature selection. A Build Thing is a declared BUILD
POINT, and `cargo build -p rotaryengine` is not something anybody ships. They
stay in `Cargo.toml`, where they belong; nothing was deleted.
✗ The FIVE BENCH-HELPER BINARIES — `planet_bench` and `vtd_bench` (osm-katana),
`bench_inflate_cmp`, `bench_large` and `gen_large_zip` (ljar). These ARE real
`[[bin]]` targets and they are DELIBERATELY unbuilt, not forgotten:
* `vtd_bench` / `planet_bench` — timing harnesses for the VTD-style index and
the planet pass. They print measurements; nobody installs them.
* `bench_inflate_cmp` / `bench_large` / `gen_large_zip` — all three carry
`required-features = ["gen"]`, and `gen = ["dep:zip", "dep:miniz_oxide"]`
pulls the third-party rivals this repo exists to beat. Shipping them would
put `zip` and `miniz_oxide` in a delivered artifact.
They are named as a POSITIVE CLAIM in `xtask/tests/build_variants.rs`
(`BENCH_HELPERS`), which asserts that every `[[bin]]` in the workspace is either
a matrix atom or one of these five. So a new binary added tomorrow cannot quietly
join the "probably a bench helper" pile — it trips the guard until somebody
decides which it is. An undeclared bin and a deliberately-unbuilt bin look
identical on disk; this is what tells them apart.
The `required-features` half matters for a second reason. `cargo build
--all-targets` SILENTLY SKIPS a target whose required features are off and still
exits 0 — so "the workspace builds" says nothing about whether those three
compile, and it would say nothing about a matrix atom either if one ever grew a
`required-features`. The guard therefore reads `required-features` out of the
manifests and asserts no DECLARED atom carries one its feature set does not
satisfy, with those three ljar bins as the live proof the check can see them.
```
### after `[build]`
```text
The delivery every atom is tagged into. znippy-zoomies ships ONE.
```
### after `base_suite = "ORIGINAL"`
```text
`offers` is deliberately ABSENT rather than empty-but-present.
It is a repo-wide allowlist that `validate` checks enabled features against, and
this matrix has no feature column at all: all five atoms are the lean default
build of their package. A repo-wide list would also be the wrong shape here —
these are five INDEPENDENT crates with disjoint feature tables (`search-index`,
`planet-fixture`/`dev` on osm-katana; `timing` on lbzip2/lgz;
`zlib-ng`, `gen` on ljar/lzip-parallel), so one flat list could not say which
feature belongs to which package.
The check that actually holds the line is in `xtask/tests/build_variants.rs`: it
asserts every atom's `features` is EMPTY and that every named package's Cargo
`default` list is empty too, so `no_default_features = true` below is a statement
of fact rather than a change of build. A feature appearing on an atom tomorrow
trips that assertion instead of slipping past an unconstrained `offers`.
```
### after `base_suite = "ORIGINAL"`
```text
═══════════════════════════════════════════════════════════════════════════════
THE FEATURE AXIS — every declared feature is built, or excused IN WORDS
═══════════════════════════════════════════════════════════════════════════════
The five rows above are all `features = []`, which is a deliberate shipping
decision and stays. What it MEANT until 2026-08-22 is that **not one feature this
repo declares was compiled by any declared build point** — and that nothing could
say so, because the gate that asks the question, `FeatureAxis::gate`, is a verdict
on the `[build] offers` space, and this repo (rightly) has none. Both of its inputs
are empty by construction here, so it returned `Ok(())` over a repo building zero
of nine. A check that cannot report red is not a check.
`FeatureAxis::manifest_gate` (nornir-build-thing, the SAME shared module — LAW 5,
not a second implementation next to it) asks the half that still has an answer:
every feature in this repo's `Cargo.toml` files is either enabled by a variant or
has a line below saying in words why nothing compiles it. Same allowlist, same
stale-excuse rule, and it refuses to pass an empty scan. Wired in
`xtask/tests/build_variants.rs`, which compiles nothing and is therefore always on.
Two features did NOT get a line here and were DELETED instead — root `vann-mmap`
and osm-katana `pmtiles`. Both gated zero `cfg` sites and pulled no dependency:
they compiled nothing whether on or off. An excuse for a flag like that is worse
than the flag, because it puts it under a watched heading for ever. See the notes
in the two `Cargo.toml`s.
```
### after `[build.allow_unbuilt]`
```text
— the two that are real capabilities of the SHIPPED binaries, off by choice ——————
```
### after `dev = "the one-word alias for `planet-fixture` above; same reason, and it exists so a human types `--features dev`, not so a build point does."`
```text
— the two that would put a THIRD-PARTY RIVAL in the artifact ————————————————————
```
### after `"zlib-ng" = "ljar + lzip-parallel: swaps the pure-Rust inflate for `flate2`/zlib-ng (11 cfg sites) — a COMPARISON arm. The shipped decoder is this repo's own; a build point for it would ship the thing under test."`
```text
— the two that are instrumentation, not product —————————————————————————————————
```
### after `testmatrix = "every crate: turns the `functional_status(...)` self-reports into nornir test-matrix rows (26 cfg sites). It is on for a MATRIX run, which is a different question from what a delivery contains — the same reason it is unbuilt in korp and dwarves."`
```text
── ⭐ osm-katana — the OSM (XML/PBF) → GeoParquet/PBF converter ──────────────
The ⭐ default: the only atom here anybody runs on purpose rather than reaches for
when handed a compressed file. `check_defaults` requires exactly one `default =
true` per (suite, role), so this is the answer to "which one if nobody said".
```
### after `linkage = "not-applicable"`
```text
Stated, not inherited. osm-katana declares no `default` list, so this changes
nothing today — and that is the point: a `default` added tomorrow cannot join the
shipped binary unannounced.
```
### after `profile = "release"`
```text
── lbunzip2 — parallel bzip2 decompressor (package `lbzip2`) ─────────────────
```
### after `profile = "release"`
```text
── lgz — parallel gzip decompressor ─────────────────────────────────────────
```
### after `profile = "release"`
```text
── ljar — parallel JAR decompressor ─────────────────────────────────────────
`features = []` is load-bearing here, not boilerplate: ljar's `gen` feature pulls
`zip` + `miniz_oxide` (the third-party rivals) and gates three bench-only bins.
The shipped `ljar` must carry none of it.
```
### after `profile = "release"`
```text
── lzip — parallel ZIP decompressor (package `lzip-parallel`) ────────────────
```