nordisk/znippy-zoomies

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.

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)

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]

The delivery every atom is tagged into. znippy-zoomies ships ONE.

after base_suite = "ORIGINAL"

`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"

═══════════════════════════════════════════════════════════════════════════════
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]

— the two that are real capabilities of the SHIPPED binaries, off by choice ——————

after dev = "the one-word alias for planet-fixtureabove; same reason, and it exists so a human types--features dev, not so a build point does."

— 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."

— 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."

── ⭐ 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"

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"

── lbunzip2 — parallel bzip2 decompressor (package `lbzip2`) ─────────────────

after profile = "release"

── lgz — parallel gzip decompressor ─────────────────────────────────────────

after profile = "release"

── 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"

── lzip — parallel ZIP decompressor (package `lzip-parallel`) ────────────────