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

feat(audio): complete phase 3c slice 3 automation

Browse Source
This commit is contained in:
Labyricorn
2026-09-05 20:22:22 -07:00
parent 9ae2c76075
commit 04d4e49e9f
18 changed files with 2224 additions and 590 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/IMPLEMENTATION_STATUS.md
+14 -6
View File
@@ -1,10 +1,10 @@
# XZBT implementation status
**Updated:** September 5, 2026
**State:** The audio subsystem contract is complete through Phase 3c; Phase 3c slices 1 and 2 implemented; automation (slice 3) and master protection (slice 4), the Phase 3 audible gates, and the Phase 1 direct-file import/restart observation remain pending
**State:** Phase 3c slices 1–3 complete; stopped at the user-requested slice-3 checkpoint. Master protection (slice 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/3c-2 audio engine 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.
**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 3 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 measured master protection remain open. 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 | Slices 3c-1 (contract) and 3c-2 (lifecycle/voices) complete; slices 3c-3 and 3c-4 pending | [Automated evidence](evidence/phase3/2026-09-05-audio-authoring-contract.md) covers sections 14-15; [contract evidence](evidence/phase3/2026-09-05-phase3c-contract.md) adds section 16. [Slice 3c-2 evidence](evidence/phase3/2026-09-05-phase3c-lifecycle-voices.md) implements the seven-state lifecycle, engine-owned release gain, determinable one-shot endings, voice ceilings (64/16), 4-step eviction, and disposal. Slices 3c-3 (automation) and 3c-4 (master protection measurement) and the PRD 129 audio acceptance challenge remain. |
| 3 — Audio engine | Slices 3c-1 (contract), 3c-2 (lifecycle/voices), and 3c-3 (automation) complete; stopped before slice 4 | [Audio authoring evidence](evidence/phase3/2026-09-05-audio-authoring-contract.md), [contract evidence](evidence/phase3/2026-09-05-phase3c-contract.md), [lifecycle/voice evidence](evidence/phase3/2026-09-05-phase3c-lifecycle-voices.md), and [automation evidence](evidence/phase3/2026-09-05-phase3c-automation.md). Slice 4 requires measured master protection and user listening; PRD 129 and real GC4 audio acceptance remain open. |
| 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 |
@@ -59,11 +59,11 @@ Implementation lives in `src/runtime/audio-contract.js` (declarative tables), `s
`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.
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, 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.
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 (pending). Each slice ends green and committable.
Section 16 was contract only at slice 1.
@@ -73,4 +73,12 @@ Slice 3c-2 implements the seven-state lifecycle state machine (`CREATED`, `SCHED
`npm test` runs 67 tests with zero failures. Two clean builds produce byte-identical artifacts with digest `d7d16a89f9b1a9e21262232382d7ae53a0a84abafce191a873327e66dc4103a6`.
Phase 3 is not accepted. Slices 3c-3 (automation) and 3c-4 (measured master protection) remain. No sound has been heard from any build.
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.
**Stop:** Slice 3 is complete; wait for the user before starting slice 4. The master chain is unchanged. Measured protection, audible acceptance, and real GC4 synchronization are not claimed by the automated tests.
docs/XZBT_0-1_Format_Specification.md
+1 -1
View File
@@ -1260,7 +1260,7 @@ This section closes the audio subsystem. It covers automation tracks and their p
Sections 14 and 15 define what an exhibit may *declare*. This section defines what the runtime *does* with it over time. Where an earlier section deferred a rule to "Phase 3c", this section is the referent.
**Implementation status.** This section is the Phase 3c *contract*; the runtime does not yet implement it. Until slices 3c-2 and 3c-3 land, a document declaring `automation` or `release` is rejected with `ERR_UNKNOWN_FIELD` by the current validator, sound instances have no lifecycle state machine, and no voice ceiling is enforced. The implementation plan records the slice order.
**Implementation status.** Phase 3c slices 1–3 are implemented: the runtime accepts graph-local `automation` and recipe `release`, implements lifecycle/voice management, and resolves automation before override and modulation. Slice 4 (measured master protection) and the user-observed audio acceptance gates remain open. See the implementation status and slice evidence; the current master chain is still a placeholder, not proof of the protection contract.
### 16.1 Automation tracks
docs/evidence/phase3/2026-09-05-phase3c-automation.md
+38
View File
@@ -0,0 +1,38 @@
# Phase 3c slice 3 — Automation
Date: September 5, 2026. Contract: PRD 54 and Format Specification revision 0.4, sections 8.1, 14.4, 15.13–15.17, and 16.1–16.2. Scope: implementation-plan slice 3c-3 only. The requested stop is preserved; slice 4 has not started.
## Delivered
- Graph-local tracks on inline/shared recipes and reusable components. Both validators share structural/semantic checks; JSON Schema exposes the same authoring fields.
- Defaults, three modes, four curves, first/last holds, and one exponential fallback warning per sampled track. Times are duration literals in strictly increasing order; values are numeric ValueSpecs sampled once from the owning sound stream.
- Depth-first, property-document sampling, including nested components, route depths, and automation after the owning graph's nodes/routes. Internal expressions retain only exposed `inputs.*` references; random choices and external references stay sampled.
- Expanded-target conflicts and limits of 64 tracks / 256 total points. Component internals remain encapsulated. Automation does not enable external node bindings or overrides.
- Audio-clock scheduling, exposed component controls, modulation summation before property safety clamps, millisecond-to-second delay conversion, and resonator-ratio control. Automated delay tails conservatively use their maximum resolved time for disposal bounds.
- Shared numeric resolution: base → binding → automation → override → modulation → clamp. Bus gains use this path in the actual application, with current-value override release and preserved masked base edits. Zero-smoothing bindings react to same-tick edits. Bus automation/modulation registration is an internal runtime surface; no unspecified bus document fields were invented.
- Disposal cancels scheduled controls, stops/disconnects sources, clears control caches, releases the voice plan, and removes bus subscriptions. Injected scheduling failures clean partial graphs without violating the terminal `FAILED` lifecycle state. Successful exhibit switching detaches the preceding audio owner.
- The minimal audio exhibit demonstrates all modes and curves; the standalone artifact includes the new modules with no external runtime dependency.
## Verification
`npm test`: **88 passed, 0 failed** (67 existing regression tests plus 21 new tests in `test/phase3-automation.test.mjs`). Node's test workers require the existing sandbox escalation on this machine; no audio device was opened. `npm run test:phase3c3` runs the new suite directly. `npm run test:phase3` includes both audio test files.
| Required section 16.11 trace | Automated evidence |
| --- | --- |
| 1–2: modes, curves, slopes, holds | Every mode/curve combination at start, midpoint, and end; quarter points and endpoint slopes for smooth; delayed first point and long-time final hold |
| 3: conflict versus modulation sum | Duplicate expanded targets rejected; distinct component instances remain distinct; duplicate modulation routes sum |
| 4: exponential fallback | Zero, sign crossing, and negative endpoints; one warning per track despite repeated evaluations; native linear-ramp fallback |
| 5: target capabilities | Every registry property, unknown nodes, unsupported fields, component encapsulation, external binding/override restrictions, and absence of stages for parameters/state |
| 6: limits | 64 expanded component tracks / 256 points accepted; 65 tracks and 257 points rejected |
| 8: masked automation | Production bus resolver and connected bus AudioParam follow a live binding, masked track, mid-release destination, additive modulation, and final clamp |
| 11: resource cleanup | Voice disposal, duplicate disposal, cleared scheduled events, disconnected native-control graph, released plan/subscription, and injected scheduling failure |
Additional traces cover seeded sampling order/repeatability, component expressions with frozen procedural choices, bus ValueSpec sampling, same-tick upstream parameter overrides, delay units/tails, device frequency ceilings, and resonator ratios. Existing lifecycle/voice and Phase 0–2 tests continue to pass.
The connected Web Audio stand-in records scheduled events and evaluates the constructed scalar control graph; it does not merely test a separate analytic formula. Step/linear/exponential tracks schedule native AudioParam events. Smooth tracks schedule linear progress and evaluate `3t² - 2t³` with native a-rate gain/summing nodes, including segment resets and zero endpoint slopes; allocation is independent of segment duration. General nonlinear component-expression shapers (reciprocal and rounding) use sampled lookup curves; this is not a claim of bit-identical rendered samples. The final property clamp uses three collinear WaveShaper points with saturation, after summation.
`npm run build` and the reproducible-build regression produce byte-identical, self-contained HTML. Checked-in `XZBT.html`: **204,205 bytes**, SHA-256 **`6aa1b659e1f06ca3175ac62a4544cc3342e8731f6d6f186c68fcd667cf683d97`**. `git diff --check` passes.
## Acceptance boundary and stop
This is automated slice-3 evidence, not a browser listening or hardware measurement record. No production-build audio has been heard. The placeholder master chain is unchanged; measured peak ceiling, tolerance/release, finite-sample protection, PRD 129 listening, and real GC4 synchronization remain open. Phase 1's direct-file two-fixture restart observation also remains open. Do not start slice 4 or later phases until the user resumes work.