Skip to main content
Nika follows real semver. 0.124 is the current release line. Work stays focused on maintenance, security and the media capabilities workflows need; native video is planned for 0.125. These invariants are what keeps a later change, whoever makes it, from breaking the public API: any feature must fit without breaking changes to the public API.
Status: locked at v0.80, with later amendments noted inline. Every crate admitted to the workspace must comply before passing gate 12. Patterns distilled from Rust, Tokio, Deno, Cargo, Serde, Axum/Tower and Bevy.Canonical source: docs/architecture/forward-compat-invariants.md.

The patterns

Define the kernel traits for a subsystem before its implementations exist, so an implementation can plug in without changing the kernel. At v0.123.0, memory is three small traits, MemoryRemember, MemoryRecall and MemoryForget, with a blanket MemoryStore over them (crates/nika-kernel-ai/src/memory.rs); nika-store provides a signed implementation, still pre-admission.Reserved traits: MemoryStore, EmbeddingProvider, ToolExecutor, WasmPluginHost, MetricsExporter, TracerProvider, AuditSink, BillingSink, Sandbox. Several have no production implementation at v0.123.0 (see Events).Impact: a memory, metrics or audit implementation plugs into its traits without changing the kernel.
Every public type carries #[non_exhaustive] so adding a field or variant is always additive. new() constructors provide ergonomic construction without exposing struct literal syntax.
Invariant #19: every #[non_exhaustive] struct ships a new() constructor.
A workflow opens with one header line · nika: <name> (the language name as key, the workflow’s own identifier as value · the nine-key envelope of 0.109 · supersedes the nika: v1 + workflow: { id } form and the older K8s apiVersion: / schema: nika/workflow@X forms). The document type is the tasks: key: present = a workflow · absent = the project file nika.yaml, whose nika: key is the project’s name (nika: my-project); its schema version is on the editor’s $schema line, and nika: v1 is refused in both documents. Parsers refuse the previous envelope with a clear error and nika check --fix migrates it.
illustration · the envelope mark
A grammar change ships with its migration and a refusal that names the move (spec 00-overview, the stability contract). Non-workflow artifacts carry their own marker: the project file’s $schema line, a trace’s trace_format, a package manifest’s version.
Public schemas reserve two namespaces: nika.* for core additions (authoritative, versioned) and x-* for community overlays (no stability guarantee, no collision with core). Scope note · in the workflow language both are RESERVED, not current: unknown top-level fields are rejected at v0.1, and the tool namespace set is closed at nika: / mcp: (engine-specific tools route through mcp:). The live x-* surface today is the pck registry.
illustration · RESERVED future extension fields (rejected today)
Two error surfaces, one rule each. The WORKFLOW-VISIBLE surface is the spec’s NIKA-<NAMESPACE>-<NNN> taxonomy ( registered codes across namespaces · reference/error-codes). Namespaces own 001-099 ranges, codes are never repurposed. The ENGINE-INTERNAL registry (nika_error::codes · NIKA-1000+ blocks per L1 effect crate) is diagnostics machinery: reserved per crate, never reassigned, and never leaked into workflow-visible errors.
Core kernel traits (e.g., Provider, EventSink, Sandbox) are sealed via a private supertrait: only Nika-owned crates can implement them. The design kept extension traits open for community crates; at v0.123.0 the memory traits (MemoryRemember, MemoryRecall, MemoryForget) are sealed too, and the provider sub-traits (ProviderInfer, ProviderStream, ProviderMeta) stay open while their combination, Provider, is sealed.
Enforced by ADR-014.
New capability = new feature flag, OFF by default. After 1-2 minor cycles of stability, flips to default-ON. Never remove a default feature (breaking change): deprecate and redirect.
Three tools on every CI run:
  • cargo public-api: detects API surface changes per crate.
  • cargo semver-checks: verifies SemVer compatibility.
  • cargo deny: enforces license + advisories + layer bans.
Gate 12 fails on any unintentional public API drift. A public-api.txt snapshot is checked in for each crate, and the public-api.yml and semver-checks.yml CI workflows compare against it.

The five early decisions (v0.80)

The rules

Every crate admission answers “yes” to each. cargo public-api + cargo semver-checks catch violations before merge.
  1. All public types carry #[non_exhaustive].
  2. All public structs with #[non_exhaustive] ship a new() constructor.
  3. All async trait methods use trait_variant::make for dynamic dispatch.
  4. All core traits seal via private supertrait.
  5. All error types expose a NIKA-XXX code via NikaError::code().
  6. Every on-disk artifact other than a workflow carries its own version marker (a workflow’s identity is nika: <name>, ADR-113).
  7. All DTO fields reserve forward-compat extension slots (see FCI-010).
  8. All feature flags default to a stable subset: new caps ship OFF.
  9. All public API changes emit a cargo public-api diff in the PR.
  10. All breaking changes require ADR Accepted before merge.

See also

Layer registry

The layers and the mechanical sort test.

L0 foundation decisions

The early foundation decisions and what became of them.

12-gate admission

How a crate earns a seat at the workspace: SPEC through ATOMIC commit.

ADR index

Every decision record at v0.123.0.