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

4 KiB

Raw Blame History

Zig Adoption Gates

Status: doctrine
Applies to: all future Zig work in CORE

Zig may enter CORE only through evidence. This page defines the proof ladder for any Zig component.

Gate ladder

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

No component skips a gate because it is small, native, or easy to write.

G0 — Doctrine

Before implementation, document:

exact component boundary;
current source of truth;
why Zig is being considered;
why Python or Rust may be insufficient for this boundary;
non-goals;
fallback path;
proof obligations.

The document must name the governing ADRs/specs. Current anchors include ADR-0013, ADR-0019, ADR-0020, ADR-0054, ADR-0180, and ADR-0181.

G1 — Reference contract locked

A Zig implementation must trail a locked reference contract.

Valid references:

tested Python behavior;
tested Rust behavior;
an ADR/spec/eval plan with executable acceptance gates;
fixture corpus plus expected hashes.

Invalid references:

performance hope;
preference for a language;
untested native behavior;
implementation-first semantics.

G2 — Explicit prototype selector

A Zig prototype must be unreachable unless deliberately selected.

Acceptable selectors:

CORE_NATIVE_BACKEND=zig
CORE_CRDT_BACKEND=zig
CORE_AUDIO_COMPILER_BACKEND=zig
core doctor --zig

A local Zig library being present must not automatically alter runtime behavior.

G3 — Parity

Parity means the Zig component preserves the reference contract.

Component	Required parity
CRDT merge	same canonical order, same dedup result, same merge hash for all input permutations
Audio compiler	same AudioIR hash, projection hash, merge key, and declared `(32,)` output contract
Algebra kernel	bit-identical result, or ADR-approved numeric tolerance
Batch recall	identical top-k indices, scores, and tie-break behavior
FFI boundary	same typed errors at Python surface

The parity gate must fail loudly if ordering, hashing, closure, or recall semantics drift.

G4 — Determinism

A Zig component must prove repeatability across:

repeated calls;
reordered inputs when order-invariance is claimed;
concurrent calls when thread-safety is claimed;
cold and warm startup;
supported target platforms.

CRDT minimum:

join(a, b) == join(b, a)
join(join(a, b), c) == join(a, join(b, c))
join(a, a) == a
hash(merge(permutation(deltas))) == hash(merge(deltas))

Audio minimum:

same canonical bytes
+ same compiler version
+ same pack manifest
+ same operator registry
= same AudioIR
= same projection hash
= same CRDT merge key

G5 — Mechanical advantage

Zig must prove at least one real advantage:

clearer C ABI;
simpler edge-native deployment;
lower memory footprint;
lower latency on representative workloads;
explicit allocation/lifecycle control;
reduced binding overhead;
safer ownership at a native boundary.

Performance data without parity does not count.

G6 — Operational proof

A supported Zig backend needs:

build command;
diagnostic command;
backend selector;
ABI version check;
memory free contract;
error contract;
fallback behavior;
CI or local verification command.

G7/G8 — Supported and default

Supported backend status requires parity, determinism, operational proof, and documented advantage.

Default backend status requires a separate ADR. Default-by-availability is not allowed.

Review checklist

Every Zig PR must answer:

What behavior is being ported or introduced?
Where is the reference contract?
How is Zig selected?
What is the fallback?
Who owns each buffer?
How are allocations released?
What errors are surfaced?
What proves deterministic replay?
What benchmark or deployment evidence justifies the component?
What test fails if semantics drift?

4 KiB Raw Blame History