XZBT/docs/XZBT_0-1_Implementation_Plan.md

XZBT 0.1 implementation plan

Planning baseline: Format Specification 0.1 Revision 0.3
Entry state: Phase 0 feasibility and shared contracts complete; production runtime not started
Rule: Finish each subsystem contract immediately before its implementation and preserve the Phase 0 shared semantics.

Sequenced milestones and verification stops

Milestone	PRD coverage	Deliverable and verification stop
Phase 1 — Runtime skeleton	8–14, 108–118, 121–127, 134–135	Modular shell, loader, diagnostics, seeded RNG, IndexedDB foundation, activation/deactivation, and deterministic standalone build. Stop only when two minimal exhibits import, cache, switch, restart, and restore directly from disk.
Phase 2 — Common grammar	15–33, 104, 136	Parameters/state/signals, ValueSpec, ConditionSpec, actions, bindings, and override stack. Re-run GC2/GC3 traces against production code; demonstrate preserved user edits through masking and release.
Phase 3 — Audio engine	34–60, 118–120, 129, 137	Complete audio subsystem contract, graph compiler/nodes/components/buses, lifecycle, automation, protection, unlock mapping, and voice limits. Run audio challenge and real GC4 synchronization checks. Begin reference Exhibits A/B audio. Delivered in three installments: 3a sources and control sources (PRD 36–42), 3b processing, routing, modulation, graph legality, authoring limits, components, sounds/recipes, and buses (PRD 43–53, 55, 56, 59, 60), 3c automation precedence, lifecycle, unlock behavior, voice ceilings, and master protection (PRD 54, 57, 58, 118–120).
Phase 4 — Visual engine	69–89, 119–120, 130, 138	Complete visual subsystem contract and generic renderer features. Run visual challenge. Begin reference Exhibits A–D visuals, then execute the early combined GC6 benchmark before fixing later optimization strategy.
Phase 5 — Events and cadence	61–68, 90–91, 139	Complete cadence/event shapes, selection/cooldown/overlap/anti-repetition, and event dispatch. Re-run dispatch budget and manual-stream isolation against production code. Integrate automatic behavior in Exhibits A–D.
Phase 6 — Scenario director	92–102, 131, 140	Complete trigger/timeline shapes; implement eligibility, branching, priority, concurrency, ownership, cleanup, and accelerated time. Re-run all GC5 traces with real resource counters. Build Exhibit E and temporary overrides in A/B. Run the two-hour development soak.
Phase 7 — Dynamic UI	103–107, 117–118, 123, 141	Complete UI contract; generated controls, soundboard, master volume, pause/resume, accessibility. Verify five distinct generated surfaces and SAMPLE isolation.
Phase 8 — Library/persistence hardening	108–116, 121–127, 132–133, 142	Directory/multi-file/drop import, refresh, update reconciliation, handles, transactions, recovery, and diagnostics. Execute every GC7 library failure and replacement test.
Phase 9 — Reference completion/audit	128–133, 143–145	Complete all five exhibits, all three challenge suites, direct/offline artifact audit, fixed benchmark, resource/leak cycles, and eight-hour release soak. Audit every MVP completion criterion before declaring 0.1 complete.

Every phase ends with tests and an evidence record. A failed gate stops dependent work; it does not silently weaken the requirement.

Phase 3c delivery slices

Phase 3c is delivered in four slices. Each slice ends green, committed, and pushable on its own, so an interrupted phase never leaves the runtime in a worse state than it started. Slice 2 in particular replaces working scaffolding, and must not be started unless it can be finished.

Slice	Content	Depends on	Blocked by
3c-1 — Contract	Format Specification section 16: automation tracks and precedence (PRD 54), lifecycle states and release (PRD 57), determinable one-shot endings, voice ceilings and eviction, master protection shape (PRD 58), unlock and pause behavior (PRD 117-118). Documentation only; no runtime change.	Sections 14-15	—
3c-2 — Lifecycle and voices	The seven-state machine, internal release gain, determinable-ending computation, voice ceilings with eviction, and full disposal. Replaces the fixed development timer currently used to release a one-shot.	3c-1	—
3c-3 — Automation	Automation tracks, the three modes, the four interpolation curves, and their placement between binding and override in the shared resolution pipeline. Touches the Phase 2 resolution path, so it carries the widest regression surface in Phase 3.	3c-1, 3c-2	—
3c-4 — Master protection	Replaces the placeholder master chain with the measured contract: peak ceiling, numerical tolerance, release behavior, and finite-sample handling, confirmed against real output.	3c-2	User-observed. Requires GC6 measurement and audible verification on real hardware; cannot be closed by automated tests.

Slices 3c-1 through 3c-3 can be implemented and verified without an audio device. Slice 3c-4 and the PRD 129 audio acceptance challenge cannot: they need measured output and listening observations from a real browser, which the recorded test boundary assigns to user-performed runs. Phase 3 is not accepted until 3c-4 and the audio challenge close, regardless of the state of the first three slices.

An installment is complete only when its own contract, implementation, tests, and evidence record are all in place. A contract installment is reviewed against its PRD sections and the shared contracts before its dependent installment begins; the Phase 3a review, which closed four blocking defects before Phase 3b started, is the worked example.

MVP completion-criteria map

Completion criterion group	Primary milestone	Final evidence
Self-contained XZBT.html, direct/offline operation, no external runtime dependencies	Phase 1 build foundation; Phase 9 audit	Reproducible digest comparison, network capture, direct-file launch record
External import, cache/reopen, parameter persistence, malformed-input safety	Phase 1 foundation; Phase 8 hardening	Import/restart matrix, invalid/failed-refresh and transaction tests
Generated UI and per-exhibit surfaces	Phase 7	UI fixture snapshots, keyboard/accessibility checks, five-exhibit surface comparison
ValueSpec, ConditionSpec, Action Model, Binding Model, overrides	Phase 2	GC2/GC3 conformance suite against production modules
Audio Graph 0.1 and audio challenge	Phase 3; Phase 9 audit	Node/graph/lifecycle tests, challenge traces, audible observations, peak/finite-sample capture
Visual System 0.1 and visual challenge	Phase 4; Phase 9 audit	Primitive/behavior/effect fixtures, screenshots, benchmark frame samples
Event and Cadence 0.1; SAMPLE isolation	Phase 5 and Phase 7	Long logical cadence trace, collision/anti-repeat checks, PRNG stream comparison
Scenario Model and scenario challenge	Phase 6; Phase 9 audit	Accelerated scenario traces, ownership/failure counters, completion/cancel/failure repetitions
Clean exhibit switching and recovery	Phase 8	Resource baselines, candidate activation fault injection, previous-exhibit restart record
Seeded reproducibility	Phase 1 PRNG; Phases 2–6 consumers	Known vectors and equal decision traces across render rates/runs
Five generic reference exhibits with no exhibit-specific JavaScript	Developed in Phases 3–7; audited Phase 9	Source audit and capability/requirement matrix for Exhibits A–E
Long-running stability, fixed benchmark, two/eight-hour soaks	Phase 6 development soak; Phase 9 release soak	GC6 environment/workload records, retained-memory/resource/frame/audio logs
Direct-file feasibility and structural/semantic contract evidence	Phase 0 complete	GC1 manual evidence and GC2–GC5 contract evidence

Reference-exhibit and challenge map

Exhibit	Required challenge coverage	First integrated milestone	Completion
A — Procedural Machine Environment	Multiple buses; oscillator/noise/impulse/resonator; continuous ambience; all cadence classes; geometry, gauges, paths, particles; temporary disturbance	Phase 4 after audio + visual cores	Phase 9 audio, visual, cadence, scenario, and soak audit
B — Deep Abstract Field	Layered synthesis, evolving modulation, abstract depth, particles/links/trails/glow, audio-reactive bindings, scenario override	Phase 4	Phase 9 audio/visual challenge and benchmark fixture candidate
C — Natural Environment	Nonliteral procedural ambience, organic fields/distributions, slow cadence, restrained effects	Phase 4	Phase 9 breadth and performance audit
D — Instrument/Data Display	UI-driven parameters, state/signals, gauges/paths/text-like generic display primitives, accessibility	Phase 4 visuals; Phase 7 UI	Phase 9 dynamic-UI and visual challenge audit
E — Long Scenario	Relative/random timing, repeats, branching, persistent state, cadence interaction, continuous audio, visual spawn, recovery/cleanup	Phase 6	Phase 9 scenario challenge and lifecycle soak audit

The audio acceptance challenge (PRD 129) is primarily Phases 3 and 9; visual challenge (130), Phases 4 and 9; scenario challenge (131), Phases 6 and 9; persistence acceptance (132), Phase 8; reliability tests (133), Phases 6, 8, and 9.

GC6 measurement schedule and fixed method

GC6 is staged rather than treated as a Phase 0 pass:

1. Phase 1 environment record: CPU, GPU/driver, RAM, OS/browser, viewport 1920 × 1080, device-pixel ratio, sample rate, power mode, and artifact revision.
2. End of Phase 4 early combined benchmark: Freeze benchmark ID/version/seed and counts for particles, links, trails, passes, audio nodes, and voices. Use 30 seconds warm-up followed by a 120-second measurement window. Sample every rendered frame interval, runtime counters once per logical second, and browser-reported memory where available every 10 seconds.
3. Phase 6 development soak: Run the frozen workload for two real hours; record p50/p95/p99 frame interval, dropped/long frames, output peak/nonfinite sample count, audio glitches, scheduler size, resource counters, and retained-memory trend.
4. Phase 9 release soak: Repeat for eight real hours with the release artifact and the same environment/workload. Any benchmark change creates a new version and requires a documented rationale plus fresh results.

The provisional interactive threshold is p95 frame interval below 33.3ms, with progress toward 60 FPS reported separately. Audio acceptance requires finite output, an exact peak ceiling/tolerance fixed in the Phase 3 audio contract, unavoidable master routing, bounded releases, and listening observations for clicks/clipping. Accelerated tests never substitute for real-duration audio or soak evidence.

GC7 library/build verification schedule

Revision 0.3 defines byte-level import identity, explicit same-ID replacement, parameter compatibility, inert candidate preparation, activation recovery, and reproducible build boundaries. Execute them as follows:

• Phase 1: clean-build digest equality and direct/offline two-fixture import/restart.
• Phase 7: the first two integrated exhibits generate distinct controls without runtime-specific UI.
• Phase 8: identical no-op, changed-ID confirmation, invalid refresh preservation, every parameter reconciliation case, inert preparation, activation failure, candidate disposal, and previous-exhibit restart.
• Phase 9: all five exhibits, source-code audit, final direct/offline build, challenge coverage, and completion-criteria audit.

Remembered directory handles remain optional. If implemented, they receive permission-loss and ordinary-picker fallback tests; failure cannot remove the ordinary import path.