ADR index

Every significant engineering decision in Nika Diamond lives as an ADR, a short markdown file in 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)

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)

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)

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)

How NikaError is shaped + how failures surface to users.

ID	Title	Status
ADR-005	Trait-based error hierarchy with `NikaErrorCode` + `Box<dyn>`	✅ Accepted
ADR-010	`miette` as the L4 diagnostic presentation layer	✅ Accepted

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)

How the engine verifies itself beyond unit tests.

ID	Title	Status
ADR-013	Loom-based concurrency verification for L0.5 + L3	✅ Accepted
ADR-015	`expect-test` for inline snapshot assertions on rendered output	✅ Accepted

Catalog + YAML (2)

The data-driven provider catalog and the workflow envelope convention.

ID	Title	Status
ADR-008	TOML-driven catalog with build-time codegen + perfect-hash lookup	✅ Accepted
ADR-021	YAML envelope: `apiVersion + kind + metadata + spec`	✅ Accepted

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)

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)

Late-added Accepted ADRs covering foundational types + kernel expansion.

ID	Title	Status
ADR-033	L0 foundational types: Cost, UUIDv7, TrustLevel, TokenUsage evolution	✅ Accepted
ADR-034	L0.5 kernel traits expansion: 6 new traits scoped to v0.81+	✅ Accepted

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: a 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.

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.

Supersede

Rare, but when a decision proves wrong, a new Accepted ADR supersedes it. The superseded ADR stays in the tree with status: superseded and superseded_by:. It has happened once so far: ADR-021 (the K8s-style apiVersion envelope) was superseded by ADR-082, which locked the single nika: v1 version marker. One ADR is also Rejected outright (ADR-089) and kept in the tree as the record of a road not taken.

Metadata fields

Every ADR carries rich metadata in both its frontmatter and index.json:

Field	Purpose
`id`	`ADR-NNN` · assigned in ascending order, never reused. Not gap-free: ranges are reserved in blocks, so the tree currently runs `ADR-001`..`ADR-106` with 043-077 and 101-104 unallocated
`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.

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.

Foundations

Decisions

At a glance

Total

Accepted

Proposed

By theme

How ADRs work

Metadata fields

Gate 12 integration

See also

Forward-compat invariants

L0 decisions

12-gate admission

ADR directory on GitHub

​At a glance

Total

Accepted

Proposed

​By theme

​How ADRs work

​Metadata fields

​Gate 12 integration

​See also

Forward-compat invariants

L0 decisions

12-gate admission

ADR directory on GitHub

At a glance

By theme

How ADRs work

Metadata fields

Gate 12 integration

See also