Skip to main content
Nika is a single Rust binary — nika at L5 — composed of crates across six layers. Each crate has one job. Together they parse .nika.yaml, resolve templates, route to providers, execute verbs, and emit a structured event stream.
Looking for the authoritative contract? The Architecture tab holds the curated specs: Layer registry · Forward-compat invariants · L0 decisions · 12-gate admission. This page orients the concept; those pages are the contract.

​
One binary, six layers

Arrows read “built on”. The nika binary at L5 composes L4 interface crates, which consume L3 runtime + policy, which orchestrate L2 verbs, which call L1 effects through L0.5 kernel traits, which use L0 foundation types. Upward imports are a CI hard failure.

​
Each layer answers one question

LayerQuestionExamples
L0What shapes does the engine use to talk about itself?WorkflowId, NikaError, ModelCapabilities, Timestamp
L0.5What contract does a provider / fs / clock / tool executor implement?Provider, Fs, Clock, ToolExecutor, MemoryStore
L1How do I actually call OpenAI / read a file / run a process?nika-provider-openai, nika-fs, nika-process, nika-http
L2How do I execute a Nika verb end-to-end?nika-verb-exec, nika-verb-infer, nika-verb-agent
L3How do I orchestrate a full workflow safely?nika-runtime, nika-shield, nika-sandbox (future minors)
L4How does a human / tool / IDE talk to Nika?nika-cli, nika-serve, nika-mcp, nika-lsp
L5What’s the single entrypoint that wires it all?nika binary (<500 LOC)

​
Why layers matter

New crate? Answer the mechanical sort test in under 10 seconds. No meetings, no “where should this live”, no spiral into abstraction-first design.
L0 has zero I/O, zero async, zero runtime deps. Your build script can safely use nika_types::* without pulling in tokio. Property tests against L0 types run in milliseconds.
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. Invariant #27.
Every L1 crate declares its capability axes in docs/architecture/security-axes.toml (e.g., net-egress for HTTP, rw-fs for filesystem). Silent axis escalation fails CI. 12 axes total.

​
What ships at v

crates admitted past 12 gates:

nika-types

L0 · Foundation value types

nika-error

L0 · NIKA-XXX error infra

nika-catalog

L0 · providers · rules

nika-kernel

L0.5 · 40 ISP traits

nika-kernel-mock

L0.5 · Pure-memory mocks

nika-catalog-verify

L4 · Catalog validation tool
nika-schema (parser · analyzer · static check) is admitted and live — it is what nika check runs. Live constellation → · 12-gate admission →

​
The build model

Every crate earns its seat through twelve gates. No exceptions, no late fixes. One crate = one atomic commit.
1

SPEC → TDD → IMPL

Spec at docs/crate-specs/<crate>.md first. Tests red before implementation. Minimal code to green.
2

CLIPPY 0 → MUTATION ≥ 90%

Zero clippy warnings. cargo mutants -p <crate> kills ≥ 90% of generated mutants.
3

PROPERTY → BENCHMARKS → DOCS

Property tests via proptest where it matters (parsers, taint, crypto). Criterion benchmarks on hot paths. cargo doc clean.
4

CANARY → PARITY → REVIEW → COMMIT

End-to-end .nika.yaml canary. Golden diff vs legacy (Phase 5+). 3-agent swarm review. One atomic commit with a gate checklist in the body.
Full 12-gate spec →

​
See also

Layers

Authoritative layer registry with mechanical sort test.

Forward-compat invariants

The 8 patterns that keep the public API stable across years.

L0 decisions

Q1-Q13 — why no proc macros in L0, why sibling sinks not god-trait.

Admission

The 12 gates with rationale per gate.