core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
core/docs/decisions/ADR-0196-native-substrate-language-doctrine.md
Shay 9ead270fda docs: ratify Zig native-substrate doctrine (ADR-0196) 
Bring the docs/zig/** decision package and README 'Native Substrate
Direction' section into main, and record ADR-0196 (Accepted) as the
binding ratification.

The doctrine is explicitly NOT a wholesale Zig rewrite. It establishes a
ring architecture (Python = semantic source of truth; Rust = incumbent
algebra backend; Zig = Ring 1 native-substrate candidate only) and the
G0-G8 adoption gate ladder. Zig may enter only by clearing gates against
a locked reference contract; default-by-availability is forbidden.

ADR-0196 forward-references ADR-0180 as the first G1 instantiation (the
CRDT contract lock / ZC-0 slice). No Zig code is authorized.
2026-05-31 15:13:19 -07:00

5.1 KiB
Raw Blame History

ADR-0196 — Native Substrate Language Doctrine (Python / Rust / Zig)

Status: Accepted. Date: 2026-05-31.

Decision

CORE is not moving toward a wholesale Zig rewrite. This ADR ratifies the component-by-component native-substrate doctrine recorded in docs/zig/ as binding architectural direction.

The governing conclusion:

  • Python remains the semantic source of truth — cognition runtime, teaching/review workflows, pack ratification, eval harnesses, Workbench/operator tooling, and all fast-changing cognition semantics.
  • Rust (core-rs) remains the incumbent native algebra backend — Cl(4,1) geometric product, versor apply/closure, CGA inner product, exact recall, and diffusion — already parity-gated and opt-in via CORE_BACKEND=rust (algebra/backend.py).
  • Zig is a candidate material for the Ring 1 native substrate layer only: Delta-CRDT arenas/deltas/merge kernels, deterministic modality compilers (e.g. audio_core_v1), stable C ABI surfaces, edge-native ingestion, and selected exact-recall challenge kernels — and only after parity and benchmark proof.

The architectural question is therefore not "should CORE be rewritten in Zig?" (the answer is no) but "which substrate components require Zig's explicit allocation, C ABI clarity, edge-native build story, and deterministic buffer ownership strongly enough to justify a new native lane?"

Ring architecture

Ring Layer Material
Ring 3 Operator / Workbench / Review Python + TypeScript
Ring 2 Semantic cognition runtime Python — source of truth
Ring 1 Native substrate services Rust incumbent + Zig candidate
Ring 0 Hardware / memory substrate CPU, UMA, future MLX/Metal

Zig belongs in Ring 1 where its properties matter. It does not belong in Ring 2 merely because the project is getting large.

Adoption gates (binding)

No Zig component is promoted without passing the G0–G8 ladder defined in docs/zig/adoption-gates.md:

G0 doctrine
G1 reference contract locked
G2 prototype behind explicit selector
G3 parity proof
G4 determinism proof
G5 mechanical advantage proof
G6 operational proof
G7 supported backend
G8 default backend, only by later ADR

Default-by-availability is forbidden: a present Zig library must never change runtime behavior. Backend selection is always explicit and trace-visible.

Decision rules (binding)

  1. Python semantics lock first. A Zig implementation must trail a locked reference contract; it may accelerate or package behavior, never reinterpret it.
  2. No approximate substrate. No ANN/HNSW, cosine fallback, opaque embeddings, hot-path repair, or arrival-order-dependent merge.
  3. Explicit ownership or no adoption. Every component names input/output buffers, allocator ownership, failure ownership, lifecycle, determinism contract, and fallback.
  4. No hidden background work. Native workers exist only as explicitly mounted components with observable state.
  5. Component migration, not language migration. Language count is not the enemy; boundary ambiguity is.

Non-goals

This ADR does not authorize any Zig implementation. It does not authorize porting chat.runtime, teaching/review, pack ratification, the eval framework, the Workbench API, identity/safety/ethics policy, or the natural-language realizer to any native language. Those are semantic/governance layers where Python remains the right material.

Consequences

  • The doctrine package under docs/zig/** is now binding. Future Zig PRs must cite the gate they are clearing and the reference contract they trail.
  • The first gate instantiation is the Delta-CRDT substrate's G1 reference-contract lock, handled under ADR-0180 (whose gate obligations this ADR governs). That lock corresponds to the ZC-0 slice in docs/zig/crdt-substrate/implementation-slices.md.
  • ZC-1 and beyond (any Zig code) remain unauthorized until ADR-0180's reference contract is Accepted and a separate ADR clears gate G2.

Alternatives considered

  • Wholesale Zig rewrite — rejected. It would make CORE's semantic and governance layers harder, not truer; it contradicts the decoding, not generating thesis and the explicit "not an infrastructure playground" stance.
  • Status quo (Rust-only, no doctrine) — rejected. Leaving the native-substrate boundary undefined risks ad-hoc Zig adoption later, when the system is harder to re-materialize around the correct substrate.

References