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

2026-09-05 20:22:22 -07:00
parent 9ae2c76075
commit 04d4e49e9f
18 changed files with 2224 additions and 590 deletions
@@ -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.