{"row":{"id":"ADR-135","title":"The public executable is born nika: one bin target with the public name, no packaging rename, no second executable","file":"adr-135-the-public-executable-is-born-nika.md","status":"accepted","date":"2026-09-04","cites":2,"supersedes":[],"superseded_by":[],"layers":["L4","L5"],"tags":["architecture","build","release","one-door"],"room":true},"pin":{"release_tag":"v0.118.7","commit":"f3a31a6ee00766e4b010379c535bca994631d637"}}

[{"k":"h","depth":1,"text":"ADR-135 · The public executable is born `nika`","id":"adr-135--the-public-executable-is-born-nika"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"An external consumer integrating the engine (a benchmark harness, 2026-09-04)\nran the command the product's name suggests, "},{"k":"code","text":"cargo build --release --locked --bin nika"},{"k":"text","text":", and cargo refused: the workspace had no bin target named "},{"k":"code","text":"nika"},{"k":"text","text":".\nThe executable's identity was split across six surfaces that disagreed with\nthe seventh. Clap said "},{"k":"code","text":"nika"},{"k":"text","text":" ("},{"k":"code","text":"crates/nika-cli/src/main.rs"},{"k":"text","text":" ·\n"},{"k":"code","text":"#[command(name = \"nika\", bin_name = \"nika\")]"},{"k":"text","text":"), the release tarball, the\nHomebrew formula ("},{"k":"code","text":"bin.install \"nika\""},{"k":"text","text":"), the Dockerfile, the flake's\n"},{"k":"code","text":"mainProgram"},{"k":"text","text":" and every page of the docs said "},{"k":"code","text":"nika"},{"k":"text","text":", while the Cargo bin\ntarget said "},{"k":"code","text":"nika-cli"},{"k":"text","text":", so "},{"k":"code","text":"release.yml"},{"k":"text","text":" renamed the artifact at packaging\n("},{"k":"code","text":"cp target/<triple>/release/nika-cli stage/nika"},{"k":"text","text":"), "},{"k":"code","text":"flake.nix"},{"k":"text","text":" renamed it\nagain ("},{"k":"code","text":"mv \u0024out/bin/nika-cli \u0024out/bin/nika"},{"k":"text","text":"), four scripts probed\n"},{"k":"code","text":"target/*/nika-cli"},{"k":"text","text":", and forty integration tests read\n"},{"k":"code","text":"CARGO_BIN_EXE_nika-cli"},{"k":"text","text":"."}]},{"k":"p","inline":[{"k":"text","text":"The split was deliberate once: a 2026-06 comment on the bin target reserved\nthe name "},{"k":"code","text":"nika"},{"k":"text","text":" for a future L5 composition root (« this dev-named bin is the\nseed it will compose »). Three months later the seed IS the product's\nexecutable, shipped under the public name in every channel, and the\nreservation only produced a rename in every packaging path and a wrong first\ncommand for every newcomer. One Door's law applies to the build as much as to\nthe run: many doors (cargo, the tarball, the tap, the flake, the image, the\nprompt), one name, one artifact, one path to reality."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"text","text":"The bin target of the "},{"k":"code","text":"nika-cli"},{"k":"text","text":" package is named "},{"k":"code","text":"nika"},{"k":"text","text":", and the package\nruns it by default:"}]},{"k":"code","lang":"toml","text":"[package]\nname        = \"nika-cli\"     # the layer name (L4) stays\ndefault-run = \"nika\"\n\n[[bin]]\nname = \"nika\"\npath = \"src/main.rs\""},{"k":"p","inline":[{"k":"text","text":"Consequences written into the tree, in the same change:"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"cargo build --release --locked --bin nika"},{"k":"text","text":" yields "},{"k":"code","text":"target/release/nika"},{"k":"text","text":";\n"},{"k":"code","text":"release.yml"},{"k":"text","text":" builds "},{"k":"code","text":"--bin nika"},{"k":"text","text":", signs "},{"k":"code","text":"target/<triple>/release/nika"},{"k":"text","text":" and\nstages that file under the same name (a copy into the staging dir, never a\nrename); "},{"k":"code","text":"flake.nix"},{"k":"text","text":" has no "},{"k":"code","text":"postInstall"},{"k":"text","text":" rename; the Homebrew formula, the\nDockerfile and cargo-binstall ("},{"k":"code","text":"bin-dir = \"nika\""},{"k":"text","text":") were already speaking the\npublic name and are unchanged."}],[{"k":"text","text":"Every integration test reads "},{"k":"code","text":"env!(\"CARGO_BIN_EXE_nika\")"},{"k":"text","text":"; the scripts that\nprobe a built binary ("},{"k":"code","text":"check-funnel.sh"},{"k":"text","text":", "},{"k":"code","text":"check-taught-commands.sh"},{"k":"text","text":",\n"},{"k":"code","text":"structured-live-battery.sh"},{"k":"text","text":", the kit's "},{"k":"code","text":"check-on-edit.sh"},{"k":"text","text":") probe\n"},{"k":"code","text":"target/{debug,release}/nika"},{"k":"text","text":"."}],[{"k":"text","text":"No second executable. A "},{"k":"code","text":"nika-cli"},{"k":"text","text":" alias binary is explicitly rejected: one\ndoor means one executable, and no external consumer ever depended on the\nCargo target name (the only consumer that typed it was our own release\nmachinery, which is what this ADR deletes)."}],[{"k":"text","text":"The identity is gated twice, from both sides of the build. Cargo's own\nreading is "},{"k":"code","text":"crates/nika-cli/tests/public_binary_identity.rs"},{"k":"text","text":": it cannot\ncompile unless the target is named "},{"k":"code","text":"nika"},{"k":"text","text":", and it asks "},{"k":"code","text":"cargo metadata"},{"k":"text","text":" for\nexactly one bin target named "},{"k":"code","text":"nika"},{"k":"text","text":" in the workspace, owned by "},{"k":"code","text":"nika-cli"},{"k":"text","text":",\nwith "},{"k":"code","text":"default_run = \"nika\""},{"k":"text","text":". The packaging reading is the ratchet\n"},{"k":"code","text":"scripts/ci/check-public-binary.sh"},{"k":"text","text":" (the CI matrix and the pre-push gate):\nthe manifests including cargo's auto-discovered bins, "},{"k":"code","text":"default-run"},{"k":"text","text":", the\nrelease build line, the staging copy, and zero surviving "},{"k":"code","text":"nika-cli"},{"k":"text","text":" build,\npackage, install or test paths. The ratchet proves itself before it judges\n("},{"k":"code","text":"test-public-binary.sh"},{"k":"text","text":" · one clean tree, seven mutants, one unjudgeable\nroot)."}],[{"k":"text","text":"The L5 reservation is retired. The layer registry keeps L5 as the future\ncomposition root that will OWN the "},{"k":"code","text":"nika"},{"k":"text","text":" bin target by moving "},{"k":"code","text":"[[bin]]"},{"k":"text","text":"\n(same name, same path to reality); ownership may move, the identity does\nnot. A stable public identity outranks a Cargo target name held for an\narchitecture that has not shipped."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"A newcomer or a harness types the command the product's name implies and\ngets "},{"k":"code","text":"target/release/nika"},{"k":"text","text":"; the docs, the tarball and the build agree."}],[{"k":"text","text":"Two rename sites (release.yml · flake.nix) and four path probes are gone;\nthe artifact is the build output, byte for byte."}],[{"k":"text","text":"A drift back is caught before merge on two independent legs (tests · ratchet)."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Forty test files change one identifier; a fork that still reads\n"},{"k":"code","text":"CARGO_BIN_EXE_nika-cli"},{"k":"text","text":" fails to compile until it follows (one sed)."}],[{"k":"code","text":"cargo build -p nika-cli"},{"k":"text","text":" prints "},{"k":"code","text":"Compiling nika-cli"},{"k":"text","text":" and emits "},{"k":"code","text":"nika"},{"k":"text","text":"; the\npackage name and the executable name differ on purpose (the layer name vs\nthe public name), which the manifest comment says in one line."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika-catalog-verify"},{"k":"text","text":" keeps its own bin target (an internal tool, its own\nname); the gate counts "},{"k":"code","text":"nika"},{"k":"text","text":" alone."}],[{"k":"text","text":"Historical documents ("},{"k":"code","text":"CHANGELOG.md"},{"k":"text","text":", "},{"k":"code","text":"docs/plans/*"},{"k":"text","text":") keep their\n"},{"k":"code","text":"nika-cli"},{"k":"text","text":" build paths as the record of what was true then."}]]},{"k":"h","depth":2,"text":"Evidence / Affected code","id":"evidence--affected-code"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"crates/nika-cli/Cargo.toml"},{"k":"text","text":" — "},{"k":"code","text":"default-run"},{"k":"text","text":" + the "},{"k":"code","text":"[[bin]] name = \"nika\""}],[{"k":"code","text":"crates/nika-cli/tests/public_binary_identity.rs"},{"k":"text","text":" — cargo's own reading"}],[{"k":"code","text":"scripts/ci/check-public-binary.sh"},{"k":"text","text":" · "},{"k":"code","text":"scripts/ci/test-public-binary.sh"},{"k":"text","text":" —\nthe packaging reading and its mutants ("},{"k":"code","text":".github/workflows/diamond-ci.yml"},{"k":"text","text":"\nratchet matrix · "},{"k":"code","text":"scripts/hooks/run-ci-ratchets.sh"},{"k":"text","text":")"}],[{"k":"code","text":".github/workflows/release.yml"},{"k":"text","text":" — "},{"k":"code","text":"--bin nika"},{"k":"text","text":" · the signed path · the\nstaging copy"}],[{"k":"code","text":"flake.nix"},{"k":"text","text":" — the rename removed"}],[{"k":"code","text":"scripts/ci/check-funnel.sh"},{"k":"text","text":" · "},{"k":"code","text":"scripts/hygiene/check-taught-commands.sh"},{"k":"text","text":" ·\n"},{"k":"code","text":"scripts/test/structured-live-battery.sh"},{"k":"text","text":" ·\n"},{"k":"code","text":".agents/plugins/nika/scripts/check-on-edit.sh"},{"k":"text","text":" — the probes"}],[{"k":"code","text":"docs/architecture/crate-layer-registry.md"},{"k":"text","text":" · "},{"k":"code","text":"DIAMOND.md"},{"k":"text","text":" · "},{"k":"code","text":"ROADMAP.md"},{"k":"text","text":" ·\n"},{"k":"code","text":"CONTRIBUTING.md"},{"k":"text","text":" — L5 re-stated as ownership, never identity"}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Keep `nika-cli` and rename at packaging (the status quo)."},{"k":"text","text":" Rejected: a\nsplit identity that only the release machinery could resolve; the first\ncommand a stranger types fails."}],[{"k":"strong","text":"Ship both `nika` and `nika-cli` executables."},{"k":"text","text":" Rejected: one door, one\nexecutable; no consumer needs the alias, and two names on PATH invite the\nwrong one into a script."}],[{"k":"strong","text":"Rename the package to `nika`."},{"k":"text","text":" Rejected: the package name is the layer\nname ("},{"k":"code","text":"nika-cli"},{"k":"text","text":", L4, ADR-110's unit with "},{"k":"code","text":"nika-cli-host"},{"k":"text","text":" and "},{"k":"code","text":"nika-trace"},{"k":"text","text":");\nmoving it churns every path dependency and every baseline for no public\ngain, and a future L5 crate may still want "},{"k":"code","text":"nika"},{"k":"text","text":" as a package name."}]]}]

ADR-135

The public executable is born nika: one bin target with the public name, no packaging rename, no second executable

accepted · 2026-09-04 · L4 L5 · cites 2

ADR-135 · The public executable is born `nika` #

Context #

An external consumer integrating the engine (a benchmark harness, 2026-09-04) ran the command the product's name suggests, cargo build --release --locked --bin nika, and cargo refused: the workspace had no bin target named nika. The executable's identity was split across six surfaces that disagreed with the seventh. Clap said nika (crates/nika-cli/src/main.rs · #[command(name = "nika", bin_name = "nika")]), the release tarball, the Homebrew formula (bin.install "nika"), the Dockerfile, the flake's mainProgram and every page of the docs said nika, while the Cargo bin target said nika-cli, so release.yml renamed the artifact at packaging (cp target/<triple>/release/nika-cli stage/nika), flake.nix renamed it again (mv $out/bin/nika-cli $out/bin/nika), four scripts probed target/*/nika-cli, and forty integration tests read CARGO_BIN_EXE_nika-cli.

The split was deliberate once: a 2026-06 comment on the bin target reserved the name nika for a future L5 composition root (« this dev-named bin is the seed it will compose »). Three months later the seed IS the product's executable, shipped under the public name in every channel, and the reservation only produced a rename in every packaging path and a wrong first command for every newcomer. One Door's law applies to the build as much as to the run: many doors (cargo, the tarball, the tap, the flake, the image, the prompt), one name, one artifact, one path to reality.

Decision #

The bin target of the nika-cli package is named nika, and the package runs it by default:

toml

1[package]2name        = "nika-cli"     # the layer name (L4) stays3default-run = "nika"45[[bin]]6name = "nika"7path = "src/main.rs"

Consequences written into the tree, in the same change:

cargo build --release --locked --bin nika yields target/release/nika; release.yml builds --bin nika, signs target/<triple>/release/nika and stages that file under the same name (a copy into the staging dir, never a rename); flake.nix has no postInstall rename; the Homebrew formula, the Dockerfile and cargo-binstall (bin-dir = "nika") were already speaking the public name and are unchanged.
Every integration test reads env!("CARGO_BIN_EXE_nika"); the scripts that probe a built binary (check-funnel.sh, check-taught-commands.sh, structured-live-battery.sh, the kit's check-on-edit.sh) probe target/{debug,release}/nika.
No second executable. A nika-cli alias binary is explicitly rejected: one door means one executable, and no external consumer ever depended on the Cargo target name (the only consumer that typed it was our own release machinery, which is what this ADR deletes).
The identity is gated twice, from both sides of the build. Cargo's own reading is crates/nika-cli/tests/public_binary_identity.rs: it cannot compile unless the target is named nika, and it asks cargo metadata for exactly one bin target named nika in the workspace, owned by nika-cli, with default_run = "nika". The packaging reading is the ratchet scripts/ci/check-public-binary.sh (the CI matrix and the pre-push gate): the manifests including cargo's auto-discovered bins, default-run, the release build line, the staging copy, and zero surviving nika-cli build, package, install or test paths. The ratchet proves itself before it judges (test-public-binary.sh · one clean tree, seven mutants, one unjudgeable root).
The L5 reservation is retired. The layer registry keeps L5 as the future composition root that will OWN the nika bin target by moving [[bin]] (same name, same path to reality); ownership may move, the identity does not. A stable public identity outranks a Cargo target name held for an architecture that has not shipped.

Consequences #

Positive #

A newcomer or a harness types the command the product's name implies and gets target/release/nika; the docs, the tarball and the build agree.
Two rename sites (release.yml · flake.nix) and four path probes are gone; the artifact is the build output, byte for byte.
A drift back is caught before merge on two independent legs (tests · ratchet).

Negative #

Forty test files change one identifier; a fork that still reads CARGO_BIN_EXE_nika-cli fails to compile until it follows (one sed).
cargo build -p nika-cli prints Compiling nika-cli and emits nika; the package name and the executable name differ on purpose (the layer name vs the public name), which the manifest comment says in one line.

Neutral #

nika-catalog-verify keeps its own bin target (an internal tool, its own name); the gate counts nika alone.
Historical documents (CHANGELOG.md, docs/plans/*) keep their nika-cli build paths as the record of what was true then.

Evidence / Affected code #

crates/nika-cli/Cargo.toml — default-run + the [[bin]] name = "nika"
crates/nika-cli/tests/public_binary_identity.rs — cargo's own reading
scripts/ci/check-public-binary.sh · scripts/ci/test-public-binary.sh — the packaging reading and its mutants (.github/workflows/diamond-ci.yml ratchet matrix · scripts/hooks/run-ci-ratchets.sh)
.github/workflows/release.yml — --bin nika · the signed path · the staging copy
flake.nix — the rename removed
scripts/ci/check-funnel.sh · scripts/hygiene/check-taught-commands.sh · scripts/test/structured-live-battery.sh · .agents/plugins/nika/scripts/check-on-edit.sh — the probes
docs/architecture/crate-layer-registry.md · DIAMOND.md · ROADMAP.md · CONTRIBUTING.md — L5 re-stated as ownership, never identity

Alternatives considered #

Keep `nika-cli` and rename at packaging (the status quo). Rejected: a split identity that only the release machinery could resolve; the first command a stranger types fails.
Ship both `nika` and `nika-cli` executables. Rejected: one door, one executable; no consumer needs the alias, and two names on PATH invite the wrong one into a script.
Rename the package to `nika`. Rejected: the package name is the layer name (nika-cli, L4, ADR-110's unit with nika-cli-host and nika-trace); moving it churns every path dependency and every baseline for no public gain, and a future L5 crate may still want nika as a package name.

read at v0.118.7 · the decision record ships with the engine

Every decision, with its status This one in the repo