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.

Phase 4 delivery slices

Phase 4 is the largest milestone in this plan: twenty-one PRD sections (69-89) plus the shared ceilings of PRD 119-120, a fourteen-item acceptance challenge (PRD 130), and the first visuals for four reference exhibits. It is delivered in eight slices under the same rule as Phase 3c — each slice ends green, committed, and pushable on its own — and under the project rule that a subsystem contract is finished immediately before the implementation that depends on it.

Slice	Content	Depends on	Blocked by
4a — Contract I	Complete at Revision 0.5. Format Specification section 17: pipeline and canonical units, the visuals container, layers, scene model and coordinate/fit modes (PRD 70), 2.5D depth (PRD 71), the fourteen geometry primitives (PRD 72), common visual properties (PRD 73), the transform model (PRD 74), appearance and the safe blend set (PRD 75), and paths and splines (PRD 76). Documentation only; no runtime change.	Sections 1-13	—
4b — Contract II	Format Specification section 18: visual components (PRD 77), particle systems (PRD 78), placement distributions (PRD 79), emitters (PRD 80), repeaters (PRD 81), the behavior vocabulary (PRD 82), procedural fields (PRD 83), and trails, ribbons, and links (PRD 84). Documentation only. Complete at Revision 0.6.	4a	—
4c — Contract III	Complete at Revision 0.7. Format Specification section 19: visual automation and loop modes (PRD 85), visual lifecycle and ownership (PRD 86), camera and projection (PRD 87), post-processing (PRD 88), visual safety limits (PRD 89), the centralized runtime ceilings of PRD 120, and the four system-level visual rows added to the section 8.1 target-capability table. Documentation only.	4a, 4b	—
4d — Renderer core	Canvas 2D backend, the scene/coordinate/fit resolution, layers, the transform stack, the fourteen primitives, appearance and paint, paths and splines, and depth sorting. Widest new-code surface in the phase.	4a	—
4e — Procedural systems	Visual components, particles, distributions, emitters, repeaters, behaviors, fields, trails/ribbons, and distance links.	4b, 4d	—
4f — Automation, lifecycle, and effects	Visual automation into the shared section 8 resolution path, spawned-system lifecycle and ownership, camera projection, post-effect passes, and enforcement of the centralized ceilings. Touches the Phase 2 and Phase 3c resolution path, so it carries the widest regression surface in Phase 4.	4c, 4e	—
4g — Challenge fixtures and exhibit visuals	The fourteen PRD 130 challenge fixtures, proven to need no subject-specific renderer code, and the first visuals for Exhibits A-D.	4d, 4e, 4f	—
4h — Early combined GC6 benchmark	Freeze the benchmark ID, version, seed, and counts; run the 30-second warm-up and 120-second measurement window; record frame intervals, runtime counters, and memory samples; derive the workload ceilings that fix later optimization strategy.	4g	User-observed. Requires a real reference computer and browser at 1920 x 1080; cannot be closed by automated tests.

Slices 4a through 4g are implementable and verifiable without a display measurement. Slice 4h and the PRD 130 visual acceptance challenge are not: the challenge's judgement is visual, and the benchmark is a hardware measurement, which the recorded test boundary assigns to user-performed runs. Phase 4 is not accepted until 4h and the visual challenge close, regardless of the state of the first seven slices.

The three contract slices are complete. They landed before any implementation slice because the section 17-19 contract fixes decisions that 4d through 4f would otherwise have to relitigate: the resolution boundary for visual ValueSpec fields, the transform composition order, depth semantics, and which visual properties are externally addressable at all — which section 19.1 settles at exactly four system-level target families and nothing per-object. Whether the finished contract also passes a multi-model review before 4d begins — the pass that found thirteen defects in sections 14-16, nine of which any single reviewer would have missed — is the one open decision, and it is now due rather than pending, because 4d is the next slice.

Phase 3 remains unaccepted while its user-observed gates (traces 15-17 of section 16.11 and the Phase 1 direct-file restart observation) are open. Those gates are pending measurement, not failed, and no Phase 4 slice depends on them; Phase 4 nonetheless carries that debt forward and cannot close it.

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.