XZBT/docs/IMPLEMENTATION_STATUS.md

XZBT implementation status

Updated: September 5, 2026 State: The audio subsystem contract is complete through Phase 3c; Phase 3c implementation (slices 2-4), the Phase 3 audible gates, and the Phase 1 direct-file import/restart observation remain pending Planning baseline: 05fe2b4e021ba86e4a290d05b63c7cae0e386128

Exact demarcation: GC1 direct-file feasibility (10/10 checks), GC2 shared format contracts, GC3 resolution semantics, GC4 clock/PRNG semantics, and GC5 ownership/failure semantics are complete at the Phase 0 contract-oracle level. The Phase 1 production runtime skeleton, the Phase 2 common grammar, and the Phase 3a/3b audio authoring contract and its implementation pass automated checks. Three gates remain open in the completed work: Phase 1's direct-file two-fixture restart observation, Phase 3's audible observation (no sound has been heard from any build), and the Phase 3c audio contracts on which real playback acceptance depends. Visual, cadence/event, scenario, final generated-UI, performance, and soak work remains assigned to later phases.

The user requested sequential implementation with a stop on problems. The manual version 3 evidence verifies embedded data-URL worklet loading in direct-file Chrome. The subsequent user-performed restart test restored Blue Study activity 0.37 and master volume 0.19 immediately on reopening. Native tone output and AudioContext suspend/resume are also observed. Ordinary file import, selection of both exhibits, regular Chrome mode, and directory cancellation/denial fallback have been confirmed.

Phase	Status	Evidence or next prerequisite
0 — Contracts and feasibility	Complete	GC1 passed; GC2–GC5 shared contracts and traces passed; GC6/GC7 later gates scheduled and mapped
1 — Runtime skeleton	Implemented; acceptance pending	Automated evidence passes production-module, lifecycle, PRNG-vector, cache/restore, fixture-validation, and deterministic-build tests. Direct-file two-fixture import/restart remains a user-observed gate.
2 — Common grammar	Complete	Automated evidence covers production GC2 conformance, typed values, signals, actions, same-tick bindings, transitions, override precedence/release, and parameter restoration.
3 — Audio engine	Phases 3a/3b complete; 3c contract complete, 3c implementation not started	Automated evidence covers Format Specification sections 14-15, all sixteen node types, routing and modulation, twelve legality rules, authoring limits, components, sounds/recipes, and buses. The Phase 3c contract adds section 16: automation tracks and precedence, the seven-state lifecycle and release, determinable one-shot endings, voice ceilings and eviction, master protection, and unlock and pause behavior. Phase 3c implementation slices 2-4 and the PRD 129 audio acceptance challenge remain.
4 — Visual engine	Not started	Earlier phases and visual contracts
5 — Events and cadence	Not started	Earlier phases and event/cadence contracts
6 — Scenario director	Not started	Earlier phases and scenario contracts
7 — Dynamic UI	Not started	Earlier phases and UI contracts
8 — Library and persistence hardening	Not started	Earlier phases and library contracts
9 — Reference suite completion/audit	Not started	Earlier phases, challenge coverage, benchmark and soak evidence

Work saved

• A self-contained Phase 0 probe for import, isolated probe caching, settings restoration, user-initiated audio, embedded engine worklet loading, suspend/resume, and injected storage failure.
• Two minimal import fixtures and manual test instructions.
• Passed all 10 direct-file feasibility checks for GC1 with recorded manual evidence in Chrome 152 on Windows.
• Authoritative JSON Schema (schema/xzbt-0.1.schema.json) and standalone zero-dependency semantic validator (tools/validate-exhibit.mjs).
• Automated GC2 conformance test matrix (test/gc2-runner.test.mjs) verifying 12 valid and fault-injected fixtures with zero errors.
• Format Specification Revision 0.3 with exact shared GC3 resolution/binding/transition, GC4 clock/PRNG/audio-alignment, GC5 ownership/failure/dispatch, and GC7 import/update/build contracts.
• Executable Phase 0 contract models and tests for GC3–GC5; the combined Phase 0 run passes 27 tests with zero failures.
• A sequenced implementation plan mapping every MVP completion group, reference challenge, GC6 measurement stage, and GC7 library/build verification stop.
• Preserved user evidence runs for versions 1, 2, 3, offline, file relocation, and directory fallback.

Phase 1 entry condition

The injected-storage-failure run and audio follow-up confirm in-memory activity changes, successful directory import, and heard native playback despite 16 expected failed saves. The user subsequently confirmed the visible session-only warning. The injected-storage-failure check passed; this does not establish real browser permission-denial behavior.

Worklet loading and the user-performed restart/settings test have passed and need not be repeated without a relevant code change. The offline restoration, tone, and worklet check also passed with explicit user confirmation of browser-scoped Offline mode; see offline evidence. The user confirmed regular Chrome mode and ordinary import/activation. The directory-permission/cancellation fallback observation is now complete; see directory fallback evidence. GC1 is fully satisfied.

The browser rejection explicitly forbids agent workarounds through alternate browser surfaces, raw commands, or indirect execution. No workaround was attempted. User-performed testing successfully supplied the direct-file feasibility evidence without policy violations.

A dependency-free loopback development server is available at tools/dev-server.mjs. It serves the workspace at http://localhost:5173/ for later automated development testing only and listens on both IPv4 and IPv6 loopback. It may support source-level UI or regression work after Phase 0, but direct-file operation remains the primary distribution architecture.

Phase 0 remains complete and the Phase 1 implementation now reuses the GC4 PRNG known vectors in the production SeededRNG. The mandatory direct-file Phase 1 observation, combined-load measurements, production subsystem conformance, two-hour development soak, and eight-hour release soak remain outstanding at their mapped gates.

Phase 1 implementation

The modular runtime sources now live in src/runtime and build deterministically with node tools/build-xzbt.mjs into the self-contained root XZBT.html. The artifact has no external runtime dependencies or requests. Two minimal, subject-neutral fixtures live in exhibits; one uses fixed seed 42 and one requests cryptographic entropy. Phase 2 extends both with small common-grammar examples.

Automated Phase 1 checks cover JSON/version/metadata failure, the frozen GC4 state/output vectors, byte-identical import behavior, in-memory restore, prepare-before-teardown activation recovery, and byte-identical standalone builds. The existing GC2–GC5 suites still pass when run in-process. Phase 1 is not marked accepted until the built artifact imports both fixtures directly from disk, restores them after a full browser restart, and records the Phase 1 GC6 environment details required by the implementation plan.

Phase 3a and 3b audio subsystem

Format Specification revision 0.4 adds section 14 (pipeline, canonical units, audio graph objects, node-field resolution scope, frequency-ceiling staging, audio reproducibility scope, and the six source and control-source node contracts) and section 15 (nine processing and routing nodes, the component instance node, routing, modulation semantics with an explicit modulatable-property registry, twelve graph legality rules, authoring limits, components, sound definitions and recipes, and buses). A Phase 3a review closed four blocking defects in the draft before Phase 3b began: the node-identity contradiction, the missing graph container shape, the conflated audioMaxFrequency validation stages, and the undocumented sample-hold PRNG child key. Those four, and nine further gaps, are recorded in the Phase 3 evidence file.

Implementation lives in src/runtime/audio-contract.js (declarative tables), src/runtime/audio-graph.js (pure validation, component expansion, legality), and src/runtime/audio-engine.js (deterministic instantiation, Web Audio realization, and the AudioSubsystem runtime owner). Validation never opens an AudioContext, which the test suite asserts directly. tools/validate-exhibit.mjs now delegates its audio checks to the shared module instead of carrying a second implementation. exhibits/minimal-audio.xzbt exercises components, modulation, buses, a shared recipe, and both recipe modes.

npm test runs 62 tests with zero failures. Two clean builds produce byte-identical artifacts with digest 64d9932ed863dbae66f309504b88e19370ad2c9017e92c32bd61ea1ea39a3f17.

Phase 3 is not accepted. Audio automation precedence, the lifecycle state machine, unlock behavior, voice ceilings, and the measured master-protection contract are Phase 3c; no sound has been heard from any build, so the PRD 129 audio acceptance challenge, real GC4 synchronization checks, peak and finite-sample capture, and listening observations all remain open.

Phase 3c contract (slice 1)

Format Specification section 16 completes the audio subsystem contract. Phase 3c is delivered in four slices, recorded in the implementation plan: the contract (done), lifecycle and voices, automation, and measured master protection. Each slice ends green and committable, because slice 2 replaces the working one-shot timer scaffolding and must not be left half-applied.

Section 16 is contract only. The runtime does not implement it: there is no lifecycle state machine, no voice ceiling, and automation and release are still rejected as unknown fields. Slice 3c-4 and the PRD 129 audio acceptance challenge are user-observed and cannot be closed by automated tests. No sound has been heard from any build.