docs(devlog): cover phase 3c master protection

2026-09-05 20:46:08 -07:00
parent 90fcbbe467
commit 6aab663981
1 changed files with 37 additions and 0 deletions
@@ -0,0 +1,37 @@
+_model: devlog-entry
+---
+schema_version: 1
+---
+title: Adding a fail-closed master protection path
+---
+date: 2026-09-05
+---
+author: Labyricorn
+---
+summary: Phase 3c's master-protection slice adds engine-owned worklet limiting, finite-sample guards, deterministic stress fixtures, and a direct-file measurement page, while reserving hardware measurement and listening acceptance for user evidence.
+---
+tags: Audio, Protection, Web Audio, Verification, Phase 3
+---
+source_commit: 90fcbbe467e804a7f15269cd4d9ba3eb521f2370
+---
+body:
+
+XZBT's audio engine now owns a final protection path. The [Phase 3c slice-4 commit](https://git.labyricorn.com/Labyricorn/XZBT/commit/90fcbbe467e804a7f15269cd4d9ba3eb521f2370) replaces the earlier placeholder master chain with an embedded AudioWorklet limiter, finite-sample safeguards, and the tools needed to collect the user-run evidence that automated tests cannot provide.
+
+## Protection belongs to the engine
+
+Every audible route passes through engine-owned release control, a per-voice finite-sample guard where applicable, declared buses, master volume, and final protection before the audio destination. An exhibit cannot author a route around those controls or target the master directly. If the browser cannot resume audio or load the protection worklet, unlock fails closed with a warning instead of connecting an unprotected fallback.
+
+The candidate processor is stereo-linked and uses lookahead limiting with a final hard sample clamp. It is configured for a −1 dBFS ceiling, 0.1 dB tolerance, 5 ms lookahead, 0.5 ms attack, and 250 ms gain recovery. These are implementation settings under test, not a claim that the output is already accepted on real hardware.
+
+Nonfinite samples receive special treatment. A fault in a voice guard mutes that render quantum, and the final master also detects nonfinite mixed input and mutes the affected block. The engine records affected blocks and emits one warning per guard or master lifetime, while still counting repeated faults. Disposal closes worklet ports and disconnects guards, buses, and master nodes with their owners.
+
+## Automated and user-run evidence
+
+The new automated suite runs the serialized production processor through overload, transient, silence, stereo, and nonfinite cases at several sample rates. The full repository suite passed 102 tests at the referenced commit. It also checks fail-closed initialization, concurrent unlock, disposal while loading, protection routing, capture-window boundaries, deterministic fixtures, and the self-contained acceptance build.
+
+Two authored fixtures provide a frozen overlap workload and twelve challenge recipes. A standalone direct-file page uses the production processor to warm up, capture final protected Float32 output for a defined interval, log workload activity, and export a JSON report. Its instructions ask the user to record the environment, verify the provisional digital ceiling, and document audible behavior for each challenge.
+
+## What remains unclaimed
+
+No production audio has been heard or measured as part of this milestone. The output meter is immediately before `AudioContext.destination`; it cannot represent browser or operating-system resampling, intersample peaks, or analog output. The required real-browser measurement, listening observations, PRD 129 challenge acceptance, and real GC4 synchronization checks therefore remain open. Phase 3 is implemented through this slice, but it is not accepted, and later phases have not begun.