nika binary. Internally, at v, it is a
workspace of crates (
admitted, pre-admission) organized in layers:
L0, L0.5, L1, L1.5, L2, L3 and L4. Every workspace-local dependency points
downward, and a CI script (check-layering.sh) fails the build on any upward
import. Workflow authors do not pick a layer: this page is the engine’s crate
contract.
docs/architecture/crate-layer-registry.md
and the [workspace.metadata.diamond] table of the engine’s Cargo.toml.
This page curates the layer model for readers; the engine repository holds
the manifest next to the enforcement script.Mechanical sort test
Every new crate answers these questions in order. First hit wins.Does it expose a transport or UI surface (CLI, HTTP, MCP, LSP, DAP, terminal)?
nika binary itself is built from nika-cli
here.Does it orchestrate a whole workflow or enforce runtime law?
Does it implement a verb, or a client a verb calls?
Is it a provider wire, a builtin tool, extraction or local inference?
Is it a primitive with I/O (fs, net, process, sandbox, clock)?
None of the above?
The layers
Arrows read “depends on”. Upward arrows are forbidden:check-layering.sh fails on any workspace-local dependency that points up.
Layer table
Crate counts per layer at v: L0 · L0.5 · L1 · L1.5 · L2 · L3 · L4 .nika in nika-cli (ADR-135). The TypeScript SDK is not a crate: it
is the npm package @supernovae-st/nika, in its own repository.
Enforcement
check-layering.sh(scripts/ci/andscripts/hygiene/, fails on violation) reads layer membership from[workspace.metadata.diamond.layers]and verifies every workspace-local dependency is at an equal or lower layer.check-no-async-in-l0.sh(scripts/hygiene/) refusesasync fnandasync {in L0 source trees.check-crate-gates.sh(scripts/ci/) runs the admission gates for a crate.
Capability axes: a vocabulary, not enforced in 0.123.0
Capability axes: a vocabulary, not enforced in 0.123.0
reads-env, reads-fs, rw-fs, exec-shell, net-egress,
net-ingress, spawns-thread, mutates-global, panics-allowed,
reads-secrets, time-mutation, allocator-sensitive,
thread-local-state). No registry file declares them and no CI check
enforces them at v0.123.0. The runtime boundary a workflow meets is its
permits: block and the OS sandbox (Security).Forward compatibility
The layer model leaves room for additive crates without renumbering. In the 0.124 line, work stays focused on maintenance, security and the media capabilities workflows need, and none is planned.Anti-patterns
- Kitchen-sink crate: “I’ll just add this utility to
nika-error” leads to a bag of tricks every crate transitively pulls in. One caller = stays in the caller. - Facade mega-crate: “Re-export everything for convenience” collapses the layer contract and slows every build.
- Upward re-exports: an L1 crate re-exporting an L2 API turns it into an L2 consumer and breaks mechanical sorting.
asyncin L0: forces a runtime choice on every consumer and makes the crate unusable in build scripts.anyhow::Errorin library code: binaries only. Libraries use the typed error hierarchy.Box<dyn Error>in public API: hygiene vector 19 bans it. Use the typed error hierarchy.- Runtime imports in L0:
tokio::spawninnika-erroris a layer violation even if it compiles.
See also
- Forward-compat invariants: the patterns that protect the public API
- L0 foundation decisions: the early decisions and what became of them
- Admission: how a crate earns its seat
- Constellation: the map of admitted and pre-admission crates