docs/architecture/forward-compat-invariants.md.The patterns
FCI-001: Kernel traits upfront, implementations deferred
FCI-001: Kernel traits upfront, implementations deferred
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.FCI-002: #[non_exhaustive] on every public struct, enum, error variant
FCI-002: #[non_exhaustive] on every public struct, enum, error variant
#[non_exhaustive] so adding a field or variant
is always additive. new() constructors provide ergonomic construction
without exposing struct literal syntax.#[non_exhaustive] struct ships a new() constructor.FCI-003: One mark per on-disk artifact
FCI-003: One mark per on-disk artifact
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.$schema line, a trace’s
trace_format, a package manifest’s version.FCI-004: Extension namespaces (nika.* core + x-* community)
FCI-004: Extension namespaces (nika.* core + x-* community)
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.FCI-005: Reserved error code ranges
FCI-005: Reserved error code ranges
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.FCI-006: Sealed traits for core, open traits for extension
FCI-006: Sealed traits for core, open traits for extension
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.FCI-007: Feature flags with stable defaults
FCI-007: Feature flags with stable defaults
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.FCI-008: Public API discipline via CI
FCI-008: Public API discipline via CI
cargo public-api: detects API surface changes per crate.cargo semver-checks: verifies SemVer compatibility.cargo deny: enforces license + advisories + layer bans.
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
cargo public-api +
cargo semver-checks catch violations before merge.- All public types carry
#[non_exhaustive]. - All public structs with
#[non_exhaustive]ship anew()constructor. - All
asynctrait methods usetrait_variant::makefor dynamic dispatch. - All core traits seal via private supertrait.
- All error types expose a
NIKA-XXXcode viaNikaError::code(). - Every on-disk artifact other than a workflow carries its own version marker (a workflow’s identity is
nika: <name>, ADR-113). - All DTO fields reserve forward-compat extension slots (see FCI-010).
- All feature flags default to a stable subset: new caps ship OFF.
- All public API changes emit a
cargo public-apidiff in the PR. - All breaking changes require ADR Accepted before merge.