core/docs/zig/STATUS.md

Zig Native Substrate — Status & Handoff

Last updated: 2026-05-31 Maintainer note: update this page whenever a gate advances or a slice ships.

This is the single portable "where we are / what's next" page for the Zig native-substrate work. The doctrine and the definition of each step live in the sibling docs; this page records execution state, the immediate next action, and environment gotchas so any operator — or a fresh terminal, or another agent — can resume cold.

Cold-start read order: this page → README.md (decision package) → adoption-gates.md (G0–G8) → the per-component slice docs.

---

TL;DR

• CORE is not converting to Zig. Zig is a Ring-1 native-substrate candidate, adopted component-by-component through gates G0–G8. Python stays the semantic source of truth; Rust stays the incumbent algebra backend.
• Ratified: ADR-0196 (doctrine). Locked: the Delta-CRDT reference contract (ADR-0180 → Accepted, gate G1).
• No Zig code is authorized. The next Zig step (ZC-1) requires a new ADR clearing gate G2.
• This is opportunistic Ring-1 work. Ring-2 GSM8K comprehension remains the live priority — do not let substrate work displace it.

---

What shipped

PR	Scope	State
#509	ADR-0196 doctrine ratification (docs/zig/** + README section)	open
#511	ADR-0180 → Accepted; Delta-CRDT G1 contract lock (slice ZC-0); this STATUS page	open

Merge #509 first (narrative coherence + so the sibling links in this page resolve on main). The two PRs are otherwise independent (no file conflict).

---

Gate status per component

Gate ladder: G0 doctrine → G1 reference-locked → G2 prototype-selector → G3 parity → G4 determinism → G5 mechanical-advantage → G6 ops → G7 supported → G8 default-by-ADR.

Delta-CRDT substrate (ADR-0180) — highest priority

Slice	What	Gate	Status
ZC-0	Contract pinning: Python reference + golden fixtures + Rust↔Python byte parity	G1	✅ done (#511)
ZC-1	Inert Zig skeleton core-zig/ (builds + local tests, no runtime wiring)	G2	⬜ needs a new ADR to clear G2 first
ZC-2	C ABI self-test (create/free/push/snapshot/join/merge/hash, no Python)	—	⬜
ZC-3	Python binding behind CORE_CRDT_BACKEND=zig (no auto-selection)	—	⬜
ZC-4	Parity fixtures: Zig == reference (reuses the corpus locked in ZC-0)	G3	⬜
ZC-5	Benchmark + memory profile (must win a named mechanical criterion)	G5	⬜
ZC-6	Runtime integration proposal	G6→G7	⬜ new ADR
—	Default backend	G8	⬜ separate ADR

Step detail: crdt-substrate/implementation-slices.md.

Other components (each starts fresh at its own G0/G1)

Component	Doc	Current gate	Blocker / note
Audio compiler (ADR-0181)	audio-compiler/	G0/G1 (blocked)	Python audio spec not locked — ADR-0183 lexeme fork is a stub. Lock it (audio's own "ZC-0") before any Zig.
Runtime FFI contract	runtime-ffi/	G0	Doctrine says land the C-ABI/versioning/ownership contract before serious Zig in any component.
Batch-recall challenge (vault_recall_batch)	algebra-kernels/	G0	Optional Rust/Zig contest; only after parity tests. vault_recall_batch is Python-canonical today (algebra/backend.py).
Edge-native ingestion runner	core-native-system/	G0	Future; after the above contracts stabilize.

---

Immediate next action

Nothing is authorized to start — this is the deliberate stopping point.

When the CRDT Zig lane is greenlit, the first step is an ADR to clear gate G2 (cite ADR-0196's gate ladder and ADR-0180's locked contract), then ZC-1 (inert core-zig/ skeleton). The ZC-4 parity fixtures already exist:

• Python golden corpus: tests/fixtures/crdt/merge_fixtures.json
• Rust expected hex: core-rs/tests/fixtures/crdt_parity_expected.rs
• Single source of truth (regenerator): tests/fixtures/crdt/_generate.py

A Zig prototype is graded against canonical_bytes / delta_hash from the locked reference (below).

---

The locked reference contract (gate G1)

• Python canonical reference: vault/crdt.py — ArenaEntry, Delta, LocalArena, merge_kernel, canonical_bytes, delta_hash. Pure content law (content-addressed by IEEE-754 bits then provenance; no normalization, no versor closure, no global Vault writes).

• Rust incumbent parity: Delta::canonical_bytes in core-rs/src/vault.rs, pinned byte-identical by core-rs/tests/test_crdt_hash_parity.rs.

• Canonical byte layout (the cross-language contract; delta_hash = its SHA-256):

  u64   entry_count
  per entry (content order):
    32 x f32   versor components (IEEE-754, little-endian, 4 bytes each)
    u64        provenance_length
    bytes      provenance
  

• Obligation → test map: ADR-0180 §5.2.

---

Environment gotchas (these cost time on 2026-05-31)

1. Build core-rs with an explicit PyO3 compatibility policy. PyO3 0.21 supports max 3.12, while fresh uv worktree venvs may resolve to 3.13 and the Homebrew system Python may be newer. The core rust build / core rust test commands set PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 automatically. For direct cargo invocations, either use Python 3.12 explicitly:

   PYO3_PYTHON=/opt/homebrew/bin/python3.12 cargo test --test test_crdt_hash_parity --test test_arena -q
   

   or set the same forward-compatibility variable:

   PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 cargo test --test test_crdt_hash_parity --test test_arena -q
   

2. public_demo lane SHA miss is environmental, not a regression. scripts/verify_lane_shas.py reports lanes: 7/8 with ✗ public_demo → DemoContractError: showcase exceeded ADR-0099 runtime budget (~46–48s > 30000 ms). This is a wall-clock overrun in core/demos/showcase.py, reproduced identically on clean main. For substrate-only PRs (no lane-affecting serving code), confirm the 7 content lanes match and the only miss is public_demo's timeout. Do not re-pin or chase it.

---

How to verify current state

# Python contract (default backend)
uv run python -m pytest tests/test_crdt_semilattice_contract.py \
  tests/test_crdt_content_ordering.py \
  tests/test_crdt_no_global_write_from_arena.py -q          # expect 21 passed

# Rust ↔ Python byte parity (needs Py3.12)
cd core-rs && PYO3_PYTHON=/opt/homebrew/bin/python3.12 \
  cargo test --test test_crdt_hash_parity --test test_arena -q   # expect 16 passed

# Regenerate the golden fixtures (Python is the single source of truth)
uv run python tests/fixtures/crdt/_generate.py

---

Authoritative docs

• Doctrine & ratification: ADR-0196 (docs/adr/), README.md
• Gates: adoption-gates.md
• CRDT slices: crdt-substrate/ + implementation-slices.md
• Component contract status / what locked G1: ADR-0180 §5