core/docs/zig/audio-compiler/implementation-slices.md

Zig Audio Compiler — Implementation Slices

Status: doctrine / implementation plan
Depends on: docs/zig/audio-compiler/README.md

This document breaks a future Zig audio compiler into small, reviewable slices.

Zig must not become the place where the audio ontology is invented. Python/spec/fixture work remains the reference first. Zig becomes valuable only after that reference is stable.

---

ZA-0 — Reference lock

Purpose: lock the Python audio compiler behavior before native port.

Required reference surfaces:

• canonical signal formation;
• frame grid;
• acoustic lexer;
• typed AudioIR;
• operator registry;
• projection hash;
• AudioCompilationUnit merge key;
• trace hygiene;
• teacher isolation.

Exit gate:

Python fixtures and expected hashes are green.
No Zig implementation starts by defining semantics.

---

ZA-1 — Canonicalizer and frame grid

Purpose: port deterministic buffer mechanics first.

Candidate files:

core-zig/src/audio/canonical.zig
core-zig/src/audio/frames.zig
core-zig/src/audio/checksum.zig

Required checks:

• same canonical hash as reference fixtures;
• same frame count;
• same padding behavior;
• same source/canonical hash semantics;
• no raw PCM exported beyond the compiler-local boundary.

---

ZA-2 — Acoustic lexer

Purpose: port measured fact extraction.

Candidate file:

core-zig/src/audio/lexer.zig

Required checks:

• same energy bins;
• same voiced/unvoiced classification;
• same pause/onset classification;
• same pitch candidate quantization where implemented;
• stable token stream hash.

The lexer measures facts. It must not infer semantic truth or call teacher models.

---

ZA-3 — AudioIR serialization

Purpose: produce canonical typed IR from tokens.

Candidate file:

core-zig/src/audio/ir.zig

Required checks:

• same event families as reference;
• same canonical event ordering;
• same serialized field order;
• same ir_sha256;
• content anchors remain evidence, not substrate.

---

ZA-4 — Operators and projection

Purpose: lower AudioIR to one (32,) float32 unit.

Candidate files:

core-zig/src/audio/operators.zig
core-zig/src/audio/project.zig

Required checks:

• same pack manifest interpretation;
• same operator lookup;
• same theta quantization;
• canonical event-order composition;
• same projection hash;
• versor_condition < 1e-6;
• negative test proves in-chunk event order matters.

The compiler must never parallelize the non-commutative in-chunk composition loop.

---

ZA-5 — AudioCompilationUnit C ABI

Purpose: expose compiled units to Python/CRDT without Python object semantics.

Candidate files:

core-zig/include/core_audio.h
core-zig/src/audio/ffi.zig
core_native/audio_zig.py

Required checks:

• unit exposes [32]f32;
• unit exposes canonical, IR, and projection hash legs;
• unit exposes pack/projection metadata needed for provenance;
• no raw PCM exported;
• Zig-owned unit has a matching free function;
• invalid input produces typed error.

---

ZA-6 — CRDT handoff

Purpose: write compiled units into thread-local arenas behind explicit selector.

Depends on:

• audio compiler parity;
• CRDT backend parity, or the current reference CRDT path.

Required checks:

• one compiled unit writes to one local arena;
• duplicate unit dedups by merge key;
• arena flush order does not change final Vault contribution;
• sequential vs concurrent proof passes;
• pending-delta count is observable.

---

ZA-7 — Streaming phase

Purpose: preserve continuity across chunk seams.

Deferred until offline/whole-buffer v1 is locked.

Streaming must add:

• explicit stream state object;
• deterministic carry-over buffers;
• stable chunk IDs;
• seam tests;
• clear reset behavior;
• no hidden global state.

Exit gate:

streamed chunks produce the same result as whole-buffer mode where equivalence is claimed.

---

Stop conditions

Stop or revert the Zig lane if:

• parity fails and requires semantic changes;
• teacher outputs begin changing substrate projection;
• trace hygiene is weakened;
• raw PCM leaks into Vault/TurnEvent records;
• closure thresholds are weakened;
• backend selection becomes automatic by library presence.