docs(devlog): cover phase 3c automation

2026-09-05 20:43:35 -07:00
parent 04d4e49e9f
commit 249328e595
1 changed files with 37 additions and 0 deletions
@@ -0,0 +1,37 @@
+_model: devlog-entry
+---
+schema_version: 1
+---
+title: Automating the audio graph without weakening its boundaries
+---
+date: 2026-09-05
+---
+author: Labyricorn
+---
+summary: Phase 3c's automation slice adds deterministic graph-local tracks, component-safe expansion, and shared bus-gain resolution to XZBT's audio engine, while leaving measured master protection and listening acceptance explicitly open.
+---
+tags: Audio, Automation, Determinism, Web Audio, Phase 3
+---
+source_commit: 04d4e49e9f5b2f239303fa6b1de76edd2dbc15f4
+---
+body:
+
+Phase 3c now has its automation layer. The [slice-3 implementation commit](https://git.labyricorn.com/Labyricorn/XZBT/commit/04d4e49e9f5b2f239303fa6b1de76edd2dbc15f4) adds time-varying control to declared audio graphs without turning authoring data into an escape hatch around the engine's validation, ownership, or seeded-reproducibility rules.
+
+## A track is part of the graph, not a script
+
+Authoring can attach automation tracks to graph properties in inline recipes, shared recipes, and reusable components. Tracks support `absolute`, `offset`, and `scale` modes; `step`, `linear`, `exponential`, and `smooth` curves; and defined endpoint holds. Track times are strictly increasing duration literals, while values are numeric ValueSpecs. The engine samples those values once from the owning sound's seeded stream in documented depth-first order, rather than allowing a random value to drift while a track is playing.
+
+Automation expands through components while preserving their boundary. Exposed component inputs can participate, but component internals do not become targets for external bindings or overrides. Duplicate expanded targets are rejected, and the implementation enforces the authored limits of 64 tracks and 256 total points after expansion. That makes a component instance useful without making its private graph an accidental public API.
+
+## One resolution path for live controls
+
+The slice also connects audio control to the shared numeric-resolution model. For a control that supports each stage, the order is base value, binding, automation, override, modulation, then safety clamp. Bus gains use this path in the live application, including the case where an override releases toward the automation value that continued changing underneath it. Modulation remains additive before the final clamp.
+
+At Web Audio realization time, the engine schedules the supported curves against the audio clock, holds the first and final values as specified, and uses a linear fallback with one warning when an exponential segment cannot be represented. It also carries the same rules through delay timing, resonator ratios, component controls, disposal, and partial-failure cleanup.
+
+## Evidence and remaining boundary
+
+The implementation adds 21 automation tests; `npm test` passed 88 tests with no failures at the referenced revision. The deterministic self-contained build had SHA-256 digest `6aa1b659e1f06ca3175ac62a4544cc3342e8731f6d6f186c68fcd667cf683d97`. The accompanying evidence covers interpolation and holds, conflicts, limits, seeded sampling, component encapsulation, masked automation, cleanup, and injected scheduling failure.
+
+This remains automated evidence, not an audio-quality claim. The master-protection chain was deliberately unchanged at this checkpoint. Measured protection, peak and finite-sample capture, real clock-synchronization checks, and user listening for the Phase 3 acceptance challenge remain open; no production build audio is claimed to have been heard here.