> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nika.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How the nika binary is built: Rust crates in strict layers, from pure types to the command line, with downward-only dependencies enforced in CI.

You install one `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 90 crates
at v0.124.4: 75 admitted past the twelve
[admission gates](https://docs.nika.sh/architecture/admission.md), and
{STATUS.wipCrates.length} 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.

> [!TIP]
>
> **Looking for the authoritative contract?** The [Architecture tab](https://docs.nika.sh/architecture/layers.md)
> holds it: [layers](https://docs.nika.sh/architecture/layers.md) ·
> [forward-compatibility invariants](https://docs.nika.sh/architecture/forward-compat-invariants.md) ·
> [L0 decisions](https://docs.nika.sh/architecture/l0-decisions.md) · [admission](https://docs.nika.sh/architecture/admission.md).
> This page orients; those pages are the record.

## Layers, bottom up

```mermaid theme={"system"}
%%{init: {'theme':'dark','themeVariables':{'background':'transparent','mainBkg':'transparent'}}}%%
flowchart BT
  L0["L0 · pure types · parser · checker · zero I/O"]:::z
  L05["L0.5 · kernel traits (async OK)"]:::a
  L1["L1 · effects (fs · http · process · sandbox · clock)"]:::b
  L15["L1.5 · provider wires · builtins · local inference"]:::b
  L2["L2 · the four verbs · registry client"]:::c
  L3["L3 · runtime · execution"]:::d
  L4["L4 · interfaces · cli · serve · mcp · lsp · dap · session"]:::e

  L0 --> L05 --> L1 --> L15 --> L2 --> L3 --> L4

  classDef z fill:#1e3a8a,color:#fff,stroke:#3b82f6
  classDef a fill:#0e3a5c,color:#fff,stroke:#22d3ee
  classDef b fill:#065f46,color:#fff,stroke:#10b981
  classDef c fill:#92400e,color:#fff,stroke:#f59e0b
  classDef d fill:#9a3412,color:#fff,stroke:#f97316
  classDef e fill:#991b1b,color:#fff,stroke:#ef4444
```

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.**
The `nika` binary is built from the `nika-cli` crate at L4; a separate L5
composition root is not built.

## Each layer answers one question

| Layer | Question | Examples at v0.124.4 |
| - | - | - |
| **L0** | What shapes does the engine use, and what does a file mean? | `nika-types`, `nika-error`, `nika-event`, `nika-schema`, `nika-check`, `nika-cel`, `nika-catalog` |
| **L0.5** | What contract does a provider, filesystem, clock or tool executor implement? | `nika-kernel` (a facade over `nika-kernel-core`, `-ai`, `-runtime`, `-plugin`), `nika-kernel-mock` |
| **L1** | How do I read a file, call a host, run a process safely? | `nika-fs`, `nika-http`, `nika-exec-runner`, `nika-sandbox-seatbelt`, `nika-sandbox-landlock`, `nika-clock` |
| **L1.5** | How do I speak to a model provider, run a builtin, infer locally? | `nika-providers`, `nika-providers-access`, `nika-builtin`, `nika-extract`, `nika-infer-local` |
| **L2** | How do I execute a Nika verb end-to-end? | `nika-verb-infer`, `nika-verb-exec`, `nika-verb-invoke`, `nika-verb-agent` |
| **L3** | How do I orchestrate a whole workflow safely? | `nika-runtime`, `nika-runtime-laws`, `nika-execution` |
| **L4** | How does a person, tool or editor talk to Nika? | `nika-cli` (the binary), `nika-serve`, `nika-mcp`, `nika-lsp`, `nika-dap`, `nika-trace`, `nika-session` |

## Why layers matter

> [accordion] Mechanical sorting · no debate
>
> New crate? Answer the [mechanical sort test](https://docs.nika.sh/architecture/layers.md#mechanical-sort-test)
> in under ten seconds. No meetings, no "where should this live".

> [accordion] Trustable L0 · no hidden I/O
>
> L0 has **zero I/O, zero async, zero runtime dependencies**. The parser and
> the checker that `nika check` runs live there: the command line reads the
> file, and the judgment itself calls no model and performs no effect.
> Property tests against L0 types run in milliseconds.

> [accordion] 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.

> [accordion] 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](https://docs.nika.sh/concepts/security.md).

## The build model

A crate is admitted when it passes [twelve gates](https://docs.nika.sh/architecture/admission.md):
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 →](https://docs.nika.sh/reference/constellation.md) · [Admission →](https://docs.nika.sh/architecture/admission.md)

## See also

> [card] [Layers](https://docs.nika.sh/architecture/layers.md)
>
> The layer registry and the mechanical sort test.

> [card] [Forward-compat invariants](https://docs.nika.sh/architecture/forward-compat-invariants.md)
>
> The patterns that keep the public API stable.

> [card] [L0 decisions](https://docs.nika.sh/architecture/l0-decisions.md)
>
> The early foundation decisions and what became of them.

> [card] [Admission](https://docs.nika.sh/architecture/admission.md)
>
> The twelve gates with their rationale.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.