# 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](evidence/phase0/2026-09-04-user-run-v3.md) verifies embedded data-URL worklet loading in direct-file Chrome. The subsequent [user-performed restart test](evidence/phase0/2026-09-04-user-restart.md) 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](evidence/phase0/2026-09-05-user-directory-fallback.md) 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](evidence/phase1/2026-09-05-runtime-skeleton.md) 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](evidence/phase2/2026-09-05-common-grammar.md) 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](evidence/phase3/2026-09-05-audio-authoring-contract.md) 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](evidence/phase3/2026-09-05-phase3c-contract.md) 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](../prototypes/phase0/XZBT-phase0-probe.html) 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](../prototypes/phase0/README.md).
- 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](../schema/xzbt-0.1.schema.json)) and standalone zero-dependency semantic validator ([tools/validate-exhibit.mjs](../tools/validate-exhibit.mjs)).
- Automated GC2 conformance test matrix ([test/gc2-runner.test.mjs](../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](XZBT_0-1_Implementation_Plan.md) 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](evidence/phase0/2026-09-04-user-storage-failure.md) 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](evidence/phase0/2026-09-04-user-offline-audio.md). The [user confirmed regular Chrome mode and ordinary import/activation](evidence/phase0/2026-09-04-user-import-environment.md). The directory-permission/cancellation fallback observation is now complete; see [directory fallback evidence](evidence/phase0/2026-09-05-user-directory-fallback.md). 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.