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](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 | Slices 3c-1–3 complete; 3c-4 implementation verified, user acceptance pending | [Contract](evidence/phase3/2026-09-05-phase3c-contract.md), [lifecycle/voices](evidence/phase3/2026-09-05-phase3c-lifecycle-voices.md), [automation](evidence/phase3/2026-09-05-phase3c-automation.md), and [protection evidence](evidence/phase3/2026-09-05-phase3c-protection.md). 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](evidence/phase4/2026-09-06-phase4a-contract.md). 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](../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`.

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](evidence/phase3/2026-09-05-phase3c-automation.md) 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](evidence/phase3/2026-09-05-phase3c-protection.md) records coverage and limits. A [standalone user-run page](../prototypes/phase3/XZBT-audio-acceptance.html) provides a frozen overlap workload, exact audio-frame capture, twelve challenge recipes and JSON export; see [run instructions](../prototypes/phase3/README.md).

**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](evidence/phase4/2026-09-06-phase4a-contract.md).