XZBT/docs/IMPLEMENTATION_STATUS.md

XZBT implementation status

Updated: September 6, 2026 State: Phase 3 audio engine implemented through slice 3c-4 and automatically verified; Phase 4 has begun with slice 4a, the first of three visual contract sections. Slice 3c-4 hardware measurement/listening acceptance, 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, Phase 2 common grammar, and audio engine through Phase 3c slice 4's implementation pass automated checks. Phase 1's direct-file two-fixture restart observation, Phase 3's audible acceptance (no sound has been heard from a production build), and real-browser measured master protection remain open. The visual subsystem contract is open at Phase 4a; visual implementation, 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	Slices 3c-1–3 complete; 3c-4 implementation verified, user acceptance pending	Contract, lifecycle/voices, automation, and protection evidence. Slice 4 requires real-browser measurement and user listening; PRD 129 and real GC4 audio acceptance remain open.
4 — Visual engine	Contract slice 4a complete; 4b–4h pending	Slice-4a contract evidence. Format Specification section 17 covers PRD 69–76; sections 18 and 19 (slices 4b, 4c) precede any renderer implementation. Slice 4h and the PRD 130 visual challenge are user-observed.
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.

At the Phase 3a/3b checkpoint, automation, lifecycle/voices, and measured protection were still future work. The subsequent slice records below supersede that implementation status. PRD 129, real GC4 synchronization, peak/finite-sample capture, and listening observations 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 (done), automation (done), and measured master protection (implementation done; user acceptance pending). Each slice ends green and committable.

Section 16 was contract only at slice 1.

Phase 3c lifecycle and voices (slice 2)

Slice 3c-2 implements the seven-state lifecycle state machine (CREATED, SCHEDULED, ACTIVE, RELEASING, FINISHED, DISPOSED, FAILED) per section 16.3, the engine-owned internal release gain per 16.4, authorable release durations (0ms to 10s) on recipes, determinable one-shot ending bounds calculation per 16.5 (and ERR_INDETERMINATE_ONESHOT validation for unbounded sources), voice ceilings (64 one-shot, 16 continuous) with 4-step eviction order (FINISHED -> RELEASING -> ACTIVE -> refuse) and WARN_VOICE_LIMIT per 16.6, full disposal, and removal of the fixed 4-second dev timer from src/runtime/app.js.

npm test runs 67 tests with zero failures. Two clean builds produce byte-identical artifacts with digest d7d16a89f9b1a9e21262232382d7ae53a0a84abafce191a873327e66dc4103a6.

At the slice-2 checkpoint, slices 3 and 4 remained. No sound had been heard from a production build.

Phase 3c automation (slice 3)

Slice 3c-3 implements section 16.1 graph-local tracks, all three modes and four curves, strict literal time ordering, numeric ValueSpec validation, component expansion/encapsulation, conflict detection, and the 64-track / 256-total-point expanded limits. Procedural values are sampled once in depth-first document order. Native audio-clock scheduling holds curve endpoints, sums modulation before the safety clamp, and propagates exposed component controls. Section 16.2 is integrated into the shared Phase 2 resolver and the application's live bus gains; masked automation advances and override release follows its current value.

npm test passes 88 tests, including 21 new slice-3 tests. The self-contained build is deterministic; the artifact digest is 6aa1b659e1f06ca3175ac62a4544cc3342e8731f6d6f186c68fcd667cf683d97. See the slice-3 evidence for exact coverage, scheduling precision, and the test boundary.

Historical checkpoint: Slice 3 ended with the master chain unchanged. The user subsequently authorized slice 4, recorded below.

Phase 3c master protection (slice 4)

The placeholder compressor is replaced by an embedded AudioWorklet with stereo-linked lookahead limiting, a final sample clamp, and per-instance finite-sample guards. Every bus and master-volume gain precedes final protection. Nonfinite input mutes the complete mixed block and raises one warning per instance; measurement records repeat affected blocks. Initialization fails closed when protection is unavailable, and disposal owns all worklet nodes and ports.

npm test passes 102 tests, including 14 slice-4 tests. Production and acceptance builds are deterministic and self-contained. The protection evidence records coverage and limits. A standalone user-run page provides a frozen overlap workload, exact audio-frame capture, twelve challenge recipes and JSON export; see run instructions.

Acceptance checkpoint: Implementation is ready for user testing. The candidate −1 dBFS ceiling, 0.1 dB tolerance and audible release behavior remain provisional. No production audio has been heard or measured; traces 15–17, PRD 129, reference-exhibit listening and real GC4 synchronization remain open. Phase 3 is not accepted, and later phases have not started.

Phase 4a visual contract (slice 1 of eight)

Format Specification revision 0.5 adds section 17, the first of three Visual subsystem contract sections. It fixes the visual pipeline and its renderer-neutral scope, canonical units with a single degrees convention, the visuals container, layers, the scene model and the normalized/viewport/ virtual coordinate spaces with contain/cover/stretch fit, 2.5D depth (sign, sorting, parallax, perspective factor, and per-object depth fog), the fourteen primitives of Visual Primitive Set 0.1, common visual properties, the normative transform composition order, appearance with the eight-mode safe blend set and gradient paint, paths and splines with independently addressable points, text restricted to the three generic font families, and the once-at-instantiation resolution boundary for visual ValueSpec fields. Five diagnostic codes were added to the section 7 table.

Phase 4 is delivered in eight slices, recorded in the implementation plan: three contract slices (sections 17, 18, 19), three implementation slices (renderer core, procedural systems, automation and effects), a challenge-and-exhibit slice, and the user-observed early combined GC6 benchmark. Each slice ends green and committable.

Section 17 is contract only. No visual runtime code exists, the JSON Schema has no visual definitions, and nothing has been drawn from any build. The deliberate deferral of live numeric text readouts, and the open question of whether sections 17-19 pass a multi-model review before slice 4d begins, are recorded in the slice-4a evidence.