nika binary (or @supernovae-st/nika for apps). This page
explains why that binary can check a file before it runs. Workflow authors
never pick a layer: this is how the engine is built, not how you use it.
Internally the engine is a Rust workspace of crates
at v: admitted past the twelve
admission gates, and
still pre-admission, several of which ship in the
binary (the Session, the terminal workspace, nika serve). Each crate has one
job. Together they parse .nika, check it, route to providers, execute verbs
and record the run.
Layers, bottom up
Arrows read “built on”. L4 interface crates consume the L3 runtime, which orchestrates the L2 verbs, which call L1 effects and L1.5 provider wires through L0.5 kernel traits, which use L0 types. An upward import fails CI. Thenika binary is built from the nika-cli crate at L4; a separate L5
composition root is not built.
Each layer answers one question
Why layers matter
Mechanical sorting · no debate
Mechanical sorting · no debate
New crate? Answer the mechanical sort test
in under ten seconds. No meetings, no “where should this live”.
Swappable effects · test hermetically
Swappable effects · test hermetically
Every I/O crate implements a kernel trait with a mock twin. Unit tests use
nika-kernel-mock (MockClock, MockFs, MockProvider): no network, no
disk, no wall-clock flakiness.The runtime boundary · permits and the sandbox
The runtime boundary · permits and the sandbox
What a workflow may touch is declared in its
permits: block and enforced
at run time, with exec: children confined by the OS sandbox (Seatbelt on
macOS, bubblewrap on Linux). Crates were also meant to declare capability
axes in a registry; no CI check enforces that vocabulary in 0.124.3. See
Security.The build model
A crate is admitted when it passes twelve gates: specification first, tests red before code, zero clippy warnings, mutation testing, property tests where they matter, benchmarks on hot paths, clean docs, a canary workflow, a review, and one atomic commit. Pre-admission crates can live in the workspace, and ship, while they work towards those gates;Cargo.toml lists them.
In the 0.124 line, work stays focused on maintenance, security and the
media capabilities workflows need. No new crate admissions are planned.
The crate constellation → · Admission →
See also
Layers
The layer registry and the mechanical sort test.
Forward-compat invariants
The patterns that keep the public API stable.
L0 decisions
The early foundation decisions and what became of them.
Admission
The twelve gates with their rationale.