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

feat(audio): implement phase 3c master protection

Browse Source
This commit is contained in:
Labyricorn
2026-09-05 20:45:47 -07:00
parent 249328e595
commit 90fcbbe467
21 changed files with 6732 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/IMPLEMENTATION_STATUS.md
+13 -5
View File
@@ -1,10 +1,10 @@
# XZBT implementation status
**Updated:** September 5, 2026
**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
**State:** Phase 3c slices 1–3 complete; slice 4 master protection implemented and automatically verified. Slice 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 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.
**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. 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), 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. |
| 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 | 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 |
@@ -63,7 +63,7 @@ At the Phase 3a/3b checkpoint, automation, lifecycle/voices, and measured protec
## 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 (pending). Each slice ends green and committable.
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.
@@ -81,4 +81,12 @@ Slice 3c-3 implements section 16.1 graph-local tracks, all three modes and four
`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.
**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.
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.** 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.
**Implementation status.** Phase 3c slices 1–3 and the slice-4 protection implementation pass automated checks. The runtime accepts graph-local `automation` and recipe `release`, implements lifecycle/voice management, resolves automation before override and modulation, and routes audio through an engine-owned finite-sample guard and final limiter. Slice 4's real-browser measurement and user-observed listening gates remain open. See the implementation status and slice evidence; the implemented limiter is not proof of the measured protection contract.
### 16.1 Automation tracks
docs/evidence/phase3/2026-09-05-phase3c-protection.md
+27
View File
@@ -0,0 +1,27 @@
# Phase 3c slice 4 — Master protection implementation
Date: September 5, 2026. Contract: PRD 58, 118–120, 129 and Format Specification 16.7, 16.11. **Implementation and automated verification complete; hardware measurement and listening acceptance pending.** This supersedes the slice-3 stop for the newly authorized slice-4 work.
## Runtime changes
The placeholder compressor is replaced by an embedded AudioWorklet. The only audible route is voice → internal release gain → voice finite-sample guard → declared bus (when present) → master volume → final protection → destination. The engine creates these nodes; the document cannot target them, and `audio.master` remains rejected.
The candidate settings are centralized in `AUDIO_PROTECTION`: −1 dBFS ceiling, 0.1 dB tolerance, 5 ms lookahead, 0.5 ms attack and 250 ms exponential gain-recovery time constant. A stereo-linked peak detector holds incoming peaks through the lookahead interval, smooths gain reduction/recovery, and a final hard sample clamp bounds attack overshoot and extreme overload. Stereo is explicitly two channels; quiet samples retain their values after the lookahead delay. Float32 rounding may put the mathematical ceiling a fraction above −1 dBFS, within the provisional tolerance. This algorithm and its numerical tests do not establish freedom from audible artifacts.
A nonfinite sample anywhere in a voice guard mutes that entire stereo render quantum. A separate finite fault lane reaches the final master and mutes its entire mixed block, including healthy voices. The master also scans its summed input, and flushes delayed history when it mutes a block. Voice warnings use the production sound instance key; each guard and the final master warn once for their lifetime. The capture counts all affected blocks, including repeat faults after the first warning.
Unlock resumes from the gesture, loads the embedded data-URL worklet, and exposes playable audio only after protected routing is ready. Concurrent unlocks share initialization. Unsupported/rejected worklet loading or resume fails silently with `WARN_AUDIO_UNAVAILABLE`; no unprotected fallback is connected. Disposal during loading cannot resurrect output. Processor failure disconnects output and rejects an active measurement. Guards, ports, master nodes and buses are disconnected/closed with their owners.
## Verification
`npm test`: **102 passed, 0 failed**, including 14 new slice-4 tests. The first sandboxed invocation could not spawn Node test workers (`EPERM`); the authorized escalated run passed. No browser or audio device was opened.
The tests execute the exact serialized production worklet processor in a VM, exercising finite output and peak bounds at 8, 44.1, 48, 96 and 192 kHz under DC, alternating full-scale floating-point overload, sine overlap, transients and silence. They verify quiet stereo preservation and delay, monotonic release recovery, complete block muting for NaN and both infinities, once-per-instance warnings, fault-lane propagation, affected-block counts, capture-window boundaries, routing, async initialization failures/races, capture completion/disposal/failure, and missing AudioContext behavior (16.11 traces 12 and 14).
Both new `.xzbt` fixtures validate and instantiate deterministically. The twelve challenge recipes cover the authored PRD 129 candidates. The overload fixture has finite transient ending bounds shorter than the 2-second burst cadence. Production and acceptance HTML builds are self-contained and deterministic; the acceptance build records the exact production and fixture hashes in its page and exported report.
## User-run evidence still required
[The standalone acceptance page](../../../prototypes/phase3/XZBT-audio-acceptance.html) and [run instructions](../../../prototypes/phase3/README.md) provide a frozen 16-continuous/64-one-shot workload, 30-second warmup, 120-second output capture, environment fields, actual burst/voice logs and JSON export. The meter measures the final worklet's Float32 samples before the destination. It cannot measure downstream browser/OS resampling or analog output. Counts apply to blocks intersecting the window; the sample peak covers exactly the requested frames.
No production-build audio has been heard or measured in this work. The −1 dBFS / 0.1 dB values and audible release behavior remain provisional. Format Specification 16.11 traces 15–17, reference-exhibit listening, full PRD 129, real GC4 synchronization and the Phase 1 direct-file restart observation remain open. Slice 4 and Phase 3 are not accepted until the required user-performed evidence is reviewed. Later phases have not started.