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

docs(audio): specify the phase 3c contract

Browse Source 
Phase 3c is delivered in four slices so an interrupted phase never leaves
the runtime worse than it started: contract, lifecycle and voices,
automation, and measured master protection. Slice 2 replaces working
scaffolding, and slice 4 cannot close without user-observed measurement.
Record that split in the implementation plan.

This commit is slice 1, the contract. Format Specification section 16
adds automation tracks with three modes and four interpolation curves,
their placement in the shared resolution pipeline, the seven-state
lifecycle with its permitted transitions, the engine-owned internal
release gain, a per-node table for computing determinable one-shot
endings, voice ceilings with an eviction order that always releases
rather than hard-stops, the master protection contract, and unlock and
pause behavior for audio.

Automation reuses the modulation registry rather than introducing a
second answer to which properties vary over time, and a track is
declared inside the graph that owns its target, so section 14.4 stands:
automation does not widen the external surface of a node property. Close
the container gap the new fields opened by adding `automation` to the
graph object in 14.3 and `release` to the recipe object in 15.16.

Master protection is specified in shape and provisional in value.
Finite-sample handling is normative because a NaN in the output buffer
is unacceptable at any ceiling; the peak ceiling, numerical tolerance,
and release behavior await GC6 measurement.

No runtime change. There is no lifecycle state machine, no voice ceiling
is enforced, and `automation` and `release` are still rejected as
unknown fields. No sound has been heard from any build.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011FWPdCqKaaDnP9NC3JAwh6
This commit is contained in:
Labyricorn
2026-09-05 23:20:01 +00:00
co-authored by Claude Opus 5
parent cc36878a0f
commit 42e4b32fd6
5 changed files with 313 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+4 -4
View File
@@ -9,10 +9,10 @@ XZBT is a self-contained browser runtime for declarative procedural audiovisual
| Resource | Purpose | Status |
| --- | --- | --- |
| [MVP Product Requirements Document](XZBT_0-1_MVP_Product_Requirements_Document.md) | Product scope, user behavior, delivery requirements, and release acceptance | Document revision 0.3; format version remains 0.1 |
| [Format Specification 0.1](docs/XZBT_0-1_Format_Specification.md) | Runtime semantics, contract inventory, and required authoring examples | Document revision 0.4; Phase 0 shared contracts and the Phase 3a/3b audio authoring contract complete, remaining subsystem contracts in dependency order |
| [Format Specification 0.1](docs/XZBT_0-1_Format_Specification.md) | Runtime semantics, contract inventory, and required authoring examples | Document revision 0.4; Phase 0 shared contracts and the complete Phase 3a-3c audio subsystem contract, remaining subsystem contracts in dependency order |
| [Gap Closure Decisions](docs/XZBT_0-1_Gap_Closure_Decisions.md) | Decisions and rationale for the seven pre-implementation gaps | Record revision 0.3; GC1–GC5 Phase 0 evidence complete |
| [Verification Gates](docs/XZBT_0-1_Verification_Gates.md) | Evidence required before architecture commitment, subsystem work, and release | Phase 0 complete; later subsystem, GC6, and GC7 checks scheduled |
| [Implementation status](docs/IMPLEMENTATION_STATUS.md) | Current phase, stop reason, saved work, and resume prerequisites | Phase 3a/3b audio contract and implementation complete; Phase 1 direct-file and Phase 3 audible observations pending |
| [Implementation status](docs/IMPLEMENTATION_STATUS.md) | Current phase, stop reason, saved work, and resume prerequisites | Audio contract complete through Phase 3c; Phase 3c implementation, Phase 1 direct-file, and Phase 3 audible observations pending |
| [Implementation plan](docs/XZBT_0-1_Implementation_Plan.md) | Sequenced phases, completion/challenge mapping, and GC6/GC7 verification schedule | Phase 1–9 plan recorded |
The PRD is authoritative for product requirements. The format specification is authoritative for runtime semantics where a contract is explicitly defined. The decision record explains those choices; the verification gates define how to check them. These documents must be updated together when a decision changes. An unresolved conflict is a specification defect, not permission for an implementation to choose silently.
@@ -21,7 +21,7 @@ The earlier ChatGPT discussion, **Discuss Application Vision** (conversation `6a
## Planning entry point
Phase 0 is complete, and the production runtime is implemented through Phase 3b. Continue with Phase 3c (audio automation precedence, lifecycle, and master protection) from the implementation plan while preserving the verified launch model, shared semantic contracts, and production GC2/GC3 behavior. Two observations remain open in completed work: the Phase 1 direct-file two-fixture restart, and the Phase 3 audible acceptance — no sound has been heard from any build. Workload measurements and release soak tests remain later explicit gates.
Phase 0 is complete, the production runtime is implemented through Phase 3b, and the audio subsystem contract is written through Phase 3c. Continue with Phase 3c implementation slice 2 (lifecycle and voices) from the implementation plan while preserving the verified launch model, shared semantic contracts, and production GC2/GC3 behavior. Two observations remain open in completed work: the Phase 1 direct-file two-fixture restart, and the Phase 3 audible acceptance — no sound has been heard from any build. Workload measurements and release soak tests remain later explicit gates.
The full PRD completion criteria remain the 0.1 release target. Early integrated demonstrations are milestones, not completed MVPs. Reference exhibits develop alongside the engine; Phase 9 completes and audits the suite.
@@ -67,7 +67,7 @@ Run every suite with `npm test`.
The active performance supports typed parameters and state, read-only runtime signals, ValueSpec and ConditionSpec evaluation, ordered `set` and `override` actions, same-tick bindings with deterministic smoothing, numeric transitions, and priority-based temporary overrides. The audio subsystem validates and expands declared graphs without touching an `AudioContext`, instantiates them deterministically from the seeded stream, and realizes them through Web Audio; the application exposes gesture unlock, master volume, per-bus gain, and per-sound triggering. `exhibits/minimal-audio.xzbt` exercises components, modulation, buses, and both recipe modes.
No sound has yet been heard from a build: the audio acceptance challenge, peak and finite-sample capture, and listening observations are open Phase 3 gates, and audio automation precedence, the lifecycle state machine, unlock behavior, voice ceilings, and master protection are Phase 3c contracts. Visuals, cadence, events, scenarios, and the final schema-driven UI remain assigned to later phases.
The Phase 3c contract (section 16) specifies automation, the lifecycle state machine, determinable one-shot endings, voice ceilings, master protection, and unlock behavior, but the runtime does not implement it yet: `automation` and `release` are still rejected as unknown fields. No sound has yet been heard from a build, and the audio acceptance challenge, peak and finite-sample capture, and listening observations remain open Phase 3 gates. Visuals, cadence, events, scenarios, and the final schema-driven UI remain assigned to later phases.
## Local development server