docs/adr/
with status, date, context, decision, consequences. total:
Accepted, Proposed.
Canonical source:
docs/adr/index.json
(machine-readable) + docs/adr/README.md
(human index). One file per ADR, immutable once Accepted (superseded
rather than edited).At a glance
Total
decision records
Accepted
locked
Proposed
in review
By theme
Meta / Process (5)
Meta / Process (5)
How Nika runs itself as a project — version cadence, admission, ADRs-on-ADRs.
| ID | Title | Status |
|---|---|---|
| ADR-001 | Diamond orphan branch rewrite instead of iterative refactor | ✅ Accepted |
| ADR-002 | Real semver toward 1.0 — 0.91.0 release-candidate, 1.0 public API lock when gates are green | 🔄 amended (D-2026-06-20-N1) |
| ADR-003 | 12-gate crate admission protocol | ✅ Accepted |
| ADR-009 | ADR process and hook discipline | ✅ Accepted |
| ADR-011 | cargo xtask as canonical automation surface | ✅ Accepted |
Architecture / Layering (6)
Architecture / Layering (6)
The six-layer crate discipline + physical workspace layout.
| ID | Title | Status |
|---|---|---|
| ADR-004 | Context-window-sized crate architecture | ✅ Accepted |
| ADR-006 | Layered architecture with kernel ISP atomic traits + trait_variant | ✅ Accepted |
| ADR-022 | Foundation crate layout v0.81: 14 crates, publish = false | ✅ Accepted |
| ADR-023 | File modularity: 800 LOC warn / 1500 fail / 3000 fail-with-ADR | ✅ Accepted |
| ADR-026 | workspace.toml single source of truth + auto-generated crate.md | ✅ Accepted |
| ADR-027 | Strict L0 sublayer tiers + max 3 sibling deps | ✅ Accepted |
Forward-compat (4)
Forward-compat (4)
How Nika stays additive across decades without breaking changes.
| ID | Title | Status |
|---|---|---|
| ADR-007 | Forward-compat invariants with #[non_exhaustive], new(), pre-planted reservations | ✅ Accepted |
| ADR-014 | Sealed kernel traits with explicit adapter registration | ✅ Accepted |
| ADR-025 | Per-crate semver via release-plz (publishable crates only) | ✅ Accepted |
| ADR-028 | Forward-compat reservation policy: seams now, crates later | ✅ Accepted |
Error handling + diagnostics (2)
Error handling + diagnostics (2)
Runtime + concurrency (5)
Runtime + concurrency (5)
Cancellation, streaming, sync primitives, retry / timeout ownership.
| ID | Title | Status |
|---|---|---|
| ADR-012 | Typestate for nika-runtime workflow lifecycle | ✅ Accepted |
| ADR-016 | Cancellation model: future-drop primary + CancelCtx cooperative module | ✅ Accepted |
| ADR-017 | Streaming policy: bounded mpsc(32), ReceiverStream at kernel boundary | ✅ Accepted |
| ADR-018 | Runtime + sync primitives: single Tokio rt, parking_lot default | ✅ Accepted |
| ADR-019 | Retry + timeout ownership: stratified by layer | ✅ Accepted |
Testing (2)
Testing (2)
Catalog + YAML (2)
Catalog + YAML (2)
WASM + sandbox (1)
WASM + sandbox (1)
The v0.100 plugin boundary, pre-planted at v0.80.
| ID | Title | Status |
|---|---|---|
| ADR-020 | WASM plugin boundary + Sandbox: trait stubs now, dual timeout later | ✅ Accepted |
SOTA Rust patterns (1)
SOTA Rust patterns (1)
Cross-cutting idiom adoption.
| ID | Title | Status |
|---|---|---|
| ADR-024 | Adopt SOTA Rust patterns: bon Builder, Arc<str>, camino, sealed modules | ✅ Accepted |
L0 foundational additions (2)
L0 foundational additions (2)
Proposed — under review (5)
Proposed — under review (5)
Seed-level reservations ahead of their implementing crates.
| ID | Title | Status |
|---|---|---|
| ADR-029 | EmbeddingSpec value-type reservation (memory subsystem seed) | 🕒 Proposed |
| ADR-030 | MemoryFrameRef.trust reservation (Shield gate seed) | 🕒 Proposed |
| ADR-031 | RecallQuery.tenant reservation (multi-tenant keyspace seed) | 🕒 Proposed |
| ADR-032 | WasmPluginError::OutOfFuel + Trap + PluginCallContext reservation | 🕒 Proposed |
| ADR-035 | Telemetry seams: SpanGuard.parent_span_id + SpanRef (OTel-ready) | 🕒 Proposed |
How ADRs work
Propose
Any significant engineering decision starts as a Proposed ADR —
short markdown file in
docs/adr/adr-NNN-<slug>.md with
frontmatter: id, title, status: Proposed, date, tags,
related. Writer describes the context, options considered, and
recommended decision.Review
Proposed ADRs are discussed in PRs. Others get
related: /
supersedes: / requires: links. Status can flip to Accepted or
Rejected. The ADR index (docs/adr/index.json) is auto-regenerated.Accept
Once Accepted, the ADR is immutable. Any revision happens via a
new ADR that
supersedes: the old one. This keeps decision history
auditable — git log tells you when and why a given rule came in.Metadata fields
Every ADR carries rich metadata in both its frontmatter andindex.json:
| Field | Purpose |
|---|---|
id | ADR-001..ADR-035 — monotonic, gap-free |
title | One-line decision summary |
status | Proposed / Accepted / Rejected / Superseded |
date | ISO date of last status change |
tags | Free-form (e.g., architecture, runtime, forward-compat) |
affects_crates | List of crate names the decision constrains |
affects_layers | L0..L5 — which layers feel the effect |
supersedes | IDs this ADR replaces |
superseded_by | ID that replaces this ADR |
related | Sibling ADRs in the same design arc |
requires | Prerequisite ADRs (this one makes no sense without them) |
enables | Downstream ADRs this one unlocks |
Gate 12 integration
Admission Gate 12 fails when a crate’s commit changes a public API
surface without either (a) being purely additive under
#[non_exhaustive] rules, or (b) referencing an Accepted ADR that
authorizes the break. The ADR trail is how breaking changes earn the
right to exist.See also
Forward-compat invariants
The 8 patterns that keep most ADRs additive.
L0 decisions
Q1-Q13 — the foundation decisions that became ADRs 033, 034 + others.
12-gate admission
Gate 12 requires ADR alignment for breaking change.
ADR directory on GitHub
Browse the full ADR tree, index.json, and README.