Labyricorn/XZBT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(audio): complete phase 3a/3b audio subsystem contract and runtime

Browse Source 
Review Phase 3a before building on it, then implement Phase 3b.

The Phase 3a draft had four blocking defects: nodes were described as a
keyed map while every documented example carried an inline `id` field,
so under the strict unknown-field policy each minimal example would have
failed its own acceptance trace; no section said where a node lives; the
`audioMaxFrequency` ceiling was declared a semantic-stage error while
depending on a live AudioContext sample rate; and the sample-hold PRNG
child key that section 9.3 requires was undocumented. Close all four,
plus nine further gaps in noise seeding, spectral definitions, impulse
decay math, Nyquist handling, missing-field codes, LFO phase origin, the
units table, node-type staging, and a duplicated diagnostics table.

Add Format Specification section 15 for Phase 3b: nine processing and
routing node contracts, the component instance node, audio routing and
modulation with an explicit modulatable-property registry, twelve graph
legality rules, authoring limits, components with a component-scoped
`inputs.*` namespace, sound definitions and recipes, and buses.

Implement the subsystem in three modules. audio-contract.js holds the
declarative node, limit, and modulation tables every consumer reads.
audio-graph.js validates, expands components, and checks legality
without ever opening an AudioContext. audio-engine.js resolves node
fields once from the seeded stream, clamps frequencies to the live
device ceiling, realizes the graph through Web Audio, and owns the
runtime AudioSubsystem. Extend the schema, delegate the standalone
validator's audio checks to the shared module rather than carrying a
second implementation, and add a generic audio fixture.

Phase 3 is not accepted. Automation precedence, the lifecycle state
machine, unlock behavior, voice ceilings, and master protection are
Phase 3c. No sound has been heard from any build, so the audio
acceptance challenge, peak and finite-sample capture, and listening
observations remain open.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011FWPdCqKaaDnP9NC3JAwh6
This commit is contained in:
Labyricorn
2026-09-05 22:03:18 +00:00
co-authored by Claude Opus 5
parent 12140055f7
commit f07fc777f3
20 changed files with 5736 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/IMPLEMENTATION_STATUS.md
+13 -3
View File
@@ -1,10 +1,10 @@
# XZBT implementation status
**Updated:** September 5, 2026
**State:** Phase 2 common grammar complete; Phase 1 direct-file import/restart observation remains pending
**State:** Phase 3a/3b audio authoring contract and implementation complete; Phase 3c audio contracts, 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 and Phase 2 common grammar are implemented and pass automated checks, but Phase 1's direct-file two-fixture restart observation remains open. Real audio, visual, cadence/event, scenario, final generated-UI, performance, and soak work remains assigned to later phases.
**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.
@@ -13,7 +13,7 @@ The user requested sequential implementation with a stop on problems. The [manua
| 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 | Not started | Earlier phases and audio contracts |
| 3 — Audio engine | Phases 3a/3b complete; 3c 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. Phase 3c (automation precedence PRD 54, lifecycle PRD 57, safety limits and master protection PRD 58) 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 |
@@ -50,3 +50,13 @@ Phase 0 remains complete and the Phase 1 implementation now reuses the GC4 PRNG
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.