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

feat(phase0): complete shared contracts and milestone plan

Browse Source
This commit is contained in:
Labyricorn
2026-09-05 12:08:36 -07:00
parent ee774d0307
commit 63895c4fe7
23 changed files with 1433 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/XZBT_0-1_Implementation_Plan.md
+73
View File
@@ -0,0 +1,73 @@
# 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. |
| 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.
## 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.