znippy-zoomies-build-thing/src/recipe.rs
//! **The recipe** — znippy-zoomies' `impl BuildThing`, the ONE declaration of
//! what this repository builds. `.nornir/build-variants.toml` is emitted from
//! [`ZnippyZoomiesBuildThing::variants`] (see [`crate::emit`]); nothing here
//! reads it.
//!
//! # What znippy-zoomies declares, honestly
//!
//! Five atoms, one per shipped executable, all `role = tool` and all
//! `linkage = not-applicable`: these are command-line decompressors and a
//! converter — programs you run, that exit. There is no server here, nothing to
//! be thin against, no port and no unit. `linkage` is said out loud rather than
//! omitted because `ServiceShape::default()` is `FatService`, so an omitted key
//! reads as a self-containment claim nobody made.
//!
//! | 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 rather than an omission: this repo's deliveries are the
//! pure-Rust decoders themselves, and every feature it declares is one of four
//! things that a delivery must not contain — a comparison arm against the
//! third-party implementations this repo exists to beat, a bench instrument, a
//! fixture downloader, or a matrix mode. All seven are excused BY NAME in
//! [`allow_unbuilt`].
//!
//! # Why `offers` is declared, and it is not decoration
//!
//! MEASURED 2026-08-22 (edda `feature_axis`'s own doc comment): 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. The
//! `offers` set below is the union of every `[features]` name the workspace
//! declares, `default` excluded, so the gate has a question with an answer:
//! seven offered, zero built, seven excused.
//!
//! # `vann-mmap`, and why it is not here
//!
//! It was declared and gated NOTHING — `src/vann/` has zero
//! `cfg(feature = "vann-mmap")` sites and never named `memmap2` — 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 ever written, the flag comes back
//! WITH it.
use std::collections::BTreeMap;
use nornir_build_thing::cargo_container::CargoToolchain;
use nornir_build_thing::contract::Coordinate;
use nornir_build_thing::plugin::{BuildThing, Manifest, Role, ABI_VERSION};
use nornir_build_thing::variant::{
AllowEntry, ArtifactKind, BuildVariant, BuildVariantSet, Profile, ServiceShape,
};
/// The crate a receipt names as its recipe.
pub const KRATE: &str = "znippy-zoomies-build-thing";
/// The content hash over this crate's sources, computed by `build.rs`.
pub const CONTENT_HASH: &str = env!("ZNIPPY_ZOOMIES_BUILD_THING_CONTENT_HASH");
/// The one delivery.
pub const SUITE: &str = "ORIGINAL";
/// znippy-zoomies' build thing.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct ZnippyZoomiesBuildThing;
impl ZnippyZoomiesBuildThing {
/// The coordinate a receipt names this recipe by: `krate:version:hash`.
#[must_use]
pub fn coordinate() -> Coordinate {
Coordinate {
krate: KRATE.to_string(),
version: env!("CARGO_PKG_VERSION").to_string(),
hash: Some(CONTENT_HASH.to_string()),
}
}
}
fn s(x: &str) -> String {
x.to_string()
}
/// One shipped executable: `package`'s `bin`, off its own floor.
fn tool(name: &str, package: &str, bin: &str, is_default: bool) -> BuildVariant {
BuildVariant {
name: s(name),
role: Some(Role::Tool),
is_default,
suites: vec![s(SUITE)],
member: Some(s("znippy-zoomies")),
package: Some(s(package)),
bin: Some(s(bin)),
kind: ArtifactKind::Exe,
shape: ServiceShape::NotApplicable,
no_default_features: true,
features: Vec::new(),
profile: Profile::Release,
..BuildVariant::default()
}
}
/// The five atoms, in declaration order.
pub fn variants() -> Vec<BuildVariant> {
vec![
tool("osm-katana", "osm-katana", "osm-katana", true),
tool("lbunzip2", "lbzip2", "lbunzip2", false),
tool("lgz", "lgz", "lgz", false),
tool("ljar", "ljar", "ljar", false),
tool("lzip", "lzip-parallel", "lzip", false),
]
}
/// Every `[features]` name the workspace declares, `default` excluded.
///
/// See the module doc: without this set the rot gate was VACUOUS — nine features,
/// none built, `Ok(())`.
fn offers() -> Vec<&'static str> {
vec![
"search-index",
"planet-fixture",
"dev",
"gen",
"zlib-ng",
"timing",
"testmatrix",
]
}
/// **All seven features, excused by name.** A delivery here is a pure-Rust
/// decoder; every feature is a comparison arm, a bench instrument, a fixture
/// downloader or a matrix mode, and none of those belongs in a shipped artifact.
pub fn allow_unbuilt() -> BTreeMap<String, String> {
[
("search-index", "osm-katana's inverted-name index (4 cfg sites): an opt-in extra output, not part of the converter every shipped atom runs. A variant would double the katana build for a path nobody installs."),
("planet-fixture", "pulls librqbit + tokio to torrent the OSM planet as a test fixture (3 cfg sites). A fixture downloader has no business inside a delivered artifact — that is the whole reason it is a feature."),
("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."),
("gen", "ljar + lzip-parallel: pulls `zip` and `miniz_oxide`, the third-party implementations this repo exists to beat, and gates the three bench-only bins. Shipping it would ship the rivals."),
("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."),
("timing", "lbzip2 + lgz: stderr stage timings (10 cfg sites). A decompressor that prints its own schedule is a dev instrument; the atoms ship quiet."),
("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."),
]
.into_iter()
.map(|(k, v)| (s(k), s(v)))
.collect()
}
/// **The five `[[bin]]` targets no atom builds**, each with a reason.
///
/// Not mentioned by the hand-written recipe at all (found 2026-08-30, lane AG).
/// Every one of them is an instrument: three are gated behind `gen` and exist to
/// measure this repo's decoders against the rivals, two are katana's own
/// benchmarks.
fn allow_unbuilt_bins() -> BTreeMap<String, AllowEntry> {
[
// 2026-10-16 build-thing sweep (loki): the gate counted these and no row or reason covered them.
("znippy-zoomies-build-thing", "this recipe crate's own emit door (`cargo run -p znippy-zoomies-build-thing -- emit` regenerates .nornir/build-variants.toml); the forge loads the crate as wasm, the bin is repository tooling, never shipped."),
("xtask", "the `cargo xtask` door onto this repo's build thing — repository tooling, never shipped."),
("bench_inflate_cmp", "ljar's A/B bench of this repo's inflate against the third-party one, behind `gen`. Shipping it would ship the rival implementation it measures."),
("bench_large", "ljar's large-archive bench, behind `gen`. Same reason: a bench harness is an instrument, not a delivery."),
("gen_large_zip", "ljar's fixture GENERATOR for the two benches above, behind `gen`. It writes test data; nothing installs it."),
("vtd_bench", "osm-katana's tag-decode micro-bench. An instrument run by hand and by the bench suite, never installed."),
("planet_bench", "osm-katana's whole-planet bench. Same reason as `vtd_bench`, and it additionally wants a planet on disk — a build point for it would be a button that fails on every box without one."),
]
.into_iter()
.map(|(k, v)| (s(k), AllowEntry::Reason(s(v))))
.collect()
}
/// **The pinned build image every cargo variant compiles in** — `[build.toolchain]`.
///
/// Until 2026-09-10 this recipe declared none, and the consequence was NOT that
/// znippy-zoomies built on the host. `dwarves buildthing` builds this very
/// crate's wasm32 module INSIDE this container
/// (`dwarves::build_thing::code::run_cargo`), so an absent table meant
/// `CargoToolchain::validate` refused — *"no `image_sha256` — a named tag is a
/// convenience, NOT a pin"* — the code road closed, and the forge fell back to
/// reading the emitted `.nornir/build-variants.toml` as if it were the source.
/// The code-is-source ruling was out of force here for want of one line; the
/// 2026-09-10 inventory render says `toml` for znippy-zoomies and six siblings.
///
/// It matters more here than most: this repo's whole claim is measured
/// throughput (gatling, the rotary engine, the parallel codecs), and a
/// benchmark compiled by whatever `nordisk-cargo-toolchain:latest` happened to
/// resolve to that week is a number nobody can reproduce. A pinned compiler is
/// the precondition for a comparable measurement, not paperwork.
///
/// The digest is the **MANIFEST** digest (64 lowercase hex, no `sha256:`), read
/// off the engine rather than typed from memory:
/// `cargo run -p nornir-build-thing --features image-build --example
/// image_digest -- nordisk-cargo-toolchain:live` — the bollard door added the
/// same day, because before it the only way to learn a digest was the
/// `podman image inspect` the no-shelling law forbids. The image recipe is
/// reproducible (edda `ac3852e`), so every box that mints it lands on this
/// digest. It moves only when the image RECIPE moves, in the same commit.
/// MOVED 2026-09-20 (loki). The value below was
/// `2cf9b012c9d2ffa42b447e5b0d127184e5a3f998dd2574d771477e9c8e366659` — a
/// second mint of this same recipe which exists on exactly one box, t14s, and
/// sat there UNTAGGED (`<none>:<none>`, 2026-07-13). On loki it does not exist
/// at all, so `CargoToolchain::validate` refused every container build of this
/// repo BY DIGEST — correctly, and that is the whole point of a pin: it told
/// the truth about an environment that was not there. The digest now names the
/// mint that is tagged `nordisk-cargo-toolchain:live` and `:live-uefi` on both
/// boxes, and which composed the live gunnar appliance ISO; `gunnar` and
/// `holger` have pinned it since 2026-09-15. Read back on loki through the
/// engine door, not from podman hearsay:
/// `cargo run -p nornir-build-thing --features image-build --example
/// image_digest -- nordisk-cargo-toolchain:live` ->
/// `3d5115baa07d03ca51eb3e44ebb86b4e64e679bd88f38e156ef9da12c35d2143`.
/// Same `rust_version` 1.97.1, and the target list below is a subset of what
/// that image carries (it adds `x86_64-unknown-uefi`), so the pin moves and
/// nothing else does.
fn toolchain() -> Option<CargoToolchain> {
Some(CargoToolchain {
image: s("nordisk-cargo-toolchain"),
// RE-PINNED 2026-10-01 (lane R, dwarf), `3d5115ba…` → `668468e7…`: edda 6b5f905 added
// clang + llvm to cargo-toolchain.Containerfile (same Debian snapshot, same
// SOURCE_DATE_EPOCH) and no longer mints `3d5115ba…`; this is the new manifest digest.
image_sha256: s("668468e775ad80f32d700cbc9709d41cac726f40d00649461a0932f30d1b2067"),
rust_version: s("1.97.1"),
// What the pinned image CARRIES std for (`rustup target list
// --installed` inside it), not what znippy-zoomies delivers. wasm32 is
// not optional here: it is the target this crate's own plugin module is
// built for, and a declaration that omitted it would refuse the code
// road by name before the container ever ran.
targets: vec![
s("x86_64-unknown-linux-gnu"),
s("x86_64-unknown-linux-musl"),
s("wasm32-unknown-unknown"),
],
timeout_secs: 3600,
mem_limit_mb: 8192,
cpus: 8,
network: false,
remap_paths: true,
// MEASURED 2026-09-10
// (`--example escaping_siblings /home/rickard/git/znippy-zoomies`), not
// guessed — and it is ONE name: this crate's own `nornir-build-thing`,
// twice. znippy-zoomies is the closest thing the constellation has to a
// leaf, and the list says so rather than hedging.
siblings: vec![s("edda")],
})
}
impl BuildThing for ZnippyZoomiesBuildThing {
fn manifest(&self) -> Manifest {
Manifest {
abi: ABI_VERSION,
repo: s("znippy-zoomies"),
source_crate: s(KRATE),
summary: "znippy-zoomies — the fast primitives leaf: the gatling fork-join \
engine, ragnar's static tree, and the pure-Rust parallel \
decompressors (bzip2 · gzip · JAR/ZIP · zip) plus the osm-katana \
OSM converter. Five programs you run, that exit."
.to_string(),
}
}
fn variants(&self) -> BuildVariantSet {
BuildVariantSet {
base_suite: Some(s(SUITE)),
offers: offers().into_iter().map(s).collect(),
allow_unbuilt: allow_unbuilt(),
allow_unbuilt_bins: allow_unbuilt_bins(),
variants: variants(),
toolchain: toolchain(),
..BuildVariantSet::default()
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use nornir_build_thing::feature_axis::FeatureAxis;
/// **The rot gate has a question with an answer.** MEASURED 2026-08-22: with
/// no `offers` space this repo had nine declared features, ZERO built by any
/// variant, and `gate()` said `Ok(())` — green because there was nothing to
/// ask. This asserts the space is non-empty AND that the gate passes, which
/// are two different facts.
#[test]
fn the_feature_axis_is_asked_a_real_question_and_it_is_clean() {
let set = ZnippyZoomiesBuildThing.variants();
assert!(
!set.offers.is_empty(),
"an unconstrained space makes `gate()` vacuous — the exact green this \
repo used to report"
);
let axis = FeatureAxis::of("znippy-zoomies", &set);
assert!(
!axis.unbuilt.is_empty(),
"every feature here is unbuilt on purpose; an empty `unbuilt` would mean \
the axis is not reading the declaration"
);
if let Err(rot) = axis.gate() {
panic!("the feature axis is rotting: {rot:#?}");
}
}
/// **A delivery here is a pure-Rust decoder**: every atom is built off its own
/// floor with no feature at all. A row that turned one on would ship a
/// comparison arm, a bench instrument, a fixture downloader or a matrix mode.
#[test]
fn every_atom_ships_the_bare_decoder() {
for v in ZnippyZoomiesBuildThing.variants().variants {
assert!(v.no_default_features, "'{}' inherits defaults", v.name);
assert!(
v.features.is_empty(),
"'{}' turns on {:?} — every feature this repo declares is an \
instrument, not a delivery",
v.name,
v.features
);
assert_eq!(v.shape, ServiceShape::NotApplicable, "'{}'", v.name);
assert_eq!(v.role, Some(Role::Tool), "'{}'", v.name);
assert_eq!(v.suites, vec![s(SUITE)], "'{}'", v.name);
}
}
/// **No two atoms write the same file.** Five packages, five bin names: unlike
/// znippy's two feature-shapes of one binary, these are five different
/// programs, and a collision here would be one artifact built twice.
#[test]
fn the_five_atoms_are_five_different_programs() {
let set = ZnippyZoomiesBuildThing.variants();
let mut bins: Vec<&str> = set.variants.iter().filter_map(|v| v.bin.as_deref()).collect();
let n = bins.len();
bins.sort_unstable();
bins.dedup();
assert_eq!(bins.len(), n, "two atoms write the same binary name");
assert_eq!(n, 5);
}
}