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

docs: establish XZBT 0.1 MVP planning baseline

Browse Source
This commit is contained in:
Labyricorn
2026-09-04 18:42:21 -07:00
parent 35866e0e74
commit 05fe2b4e02
7 changed files with 4582 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/XZBT_0-1_Verification_Gates.md
+123
View File
@@ -0,0 +1,123 @@
# XZBT 0.1 Verification Gates
**Status:** Planning checklist; every check is pending
**Related resources:** [PRD](../XZBT_0-1_MVP_Product_Requirements_Document.md), [decisions](XZBT_0-1_Gap_Closure_Decisions.md), [format specification](XZBT_0-1_Format_Specification.md)
No tests, browser prototypes, benchmark results, or soak results have been run as part of the gap-closure documentation. Mark a check complete only with linked evidence. A recorded design decision is not a passing test.
## Phase 0 and later gates
Drafting the implementation plan may proceed now. Before committing the deployment architecture, pass GC1. Before implementing shared runtime semantics, complete the shared portions of GC2 and GC3-GC5 contracts and their expected traces. Early GC6 measurements inform expensive subsystem design. Full conformance and real-duration soak results remain release requirements.
Subsystem-specific format details can be completed in dependency order as planned tasks. Do not require the finished engine or eight-hour soak before creating the plan.
| Gap | Decision | Evidence status | Gate placement |
| --- | --- | --- | --- |
| GC1 | Recorded | Not run | Phase 0, before deployment architecture commitment |
| GC2 | Recorded; format draft partial | Contracts and fixtures incomplete | Shared contracts in Phase 0; subsystem contracts before their implementation |
| GC3 | Recorded; transition details open | Traces and tests pending | Shared resolver contract before Phase 2; tests with implementation |
| GC4 | Recorded; audio mapping details open | Prototype and tests pending | Clock contract in Phase 0; synchronization tests in audio integration |
| GC5 | Recorded; hook/queue details open | Traces and tests pending | Ownership contract before actions/audio; full tests with scenarios |
| GC6 | Recorded; thresholds provisional | Reference setup and benchmark absent | Early combined-load prototype; development and release acceptance |
| GC7 | Recorded | Plan/build/library checks pending | Milestone planning, then library/build integration |
## 1. GC1: Direct-file feasibility
- [ ] Record OS, browser version/profile, launch path, and storage mode.
- [ ] Open the artifact directly from disk with network unavailable.
- [ ] Import two exhibits with the ordinary file picker and activate each.
- [ ] Save exhibit definitions, per-exhibit parameters, selection, and master volume to IndexedDB.
- [ ] Close the browser fully, reopen the same HTML, and restore the cached library and settings without selecting source files again.
- [ ] Verify user-initiated audio unlock and resumed playback.
- [ ] If needed by the audio design, load engine-owned AudioWorklet code from the single-file artifact. Otherwise document why this check is not applicable.
- [ ] Test renamed and moved HTML files; record observed storage behavior and the support boundary.
- [ ] Test unavailable/failed storage; session playback works and the UI explains lack of persistence.
- [ ] Test directory import/remembered handles where available and ordinary-picker fallback where unavailable or permission is denied.
**Evidence:** prototype artifact, reproducible steps, environment record, observed results. If ordinary-mode persistence fails, reopen decision 1 before dependent architecture commitment.
## 2. GC2: Format contract completeness
- [ ] Complete shared document, type, reference, ValueSpec, ConditionSpec, time, and ownership contracts.
- [ ] Fill the format-specification contract register in subsystem dependency order.
- [ ] Implement an internal structural schema plus separate semantic validation.
- [ ] Provide complete valid and invalid fixtures with expected diagnostics.
- [ ] Reject unsupported versions, unknown behavior fields, invalid reference types, recursive components, illegal graph cycles, and excessive resources.
- [ ] Produce two contrasting complete audiovisual exhibits early; expand toward all PRD challenge cases.
- [ ] Reconcile prior conversation proposals into the local documents; resolve conflicts explicitly.
**Evidence:** versioned specification/schema/fixtures and validation results. Naming a node or behavior does not close its contract.
## 3. GC3: Resolution semantics
- [ ] Record exact target capabilities, override defaults, smoothing, and interrupted transition rules.
- [ ] Define expected traces for a bound bus gain receiving a direct override.
- [ ] Define expected traces for a parameter override feeding a binding.
- [ ] Verify stored user edits during masking and release toward the updated lower value.
- [ ] Verify priority ties and competing duration/scenario overrides.
- [ ] Verify automation continues while masked and permitted modulation applies after an override.
- [ ] Verify numeric clamps and unsupported target/stage diagnostics.
- [ ] Reject conflicting bindings and dependency cycles without introducing undocumented delays.
**Evidence:** contract examples and deterministic resolver tests when implemented.
## 4. GC4: Time and reproducibility
- [ ] Define logical tick ordering, maximum work per turn, long-stall behavior, audio lookahead, and audio unlock alignment.
- [ ] Define PRNG algorithm, seed normalization, and stream derivation for the runtime version.
- [ ] Compare simulation traces at different render frequencies using the same logical inputs.
- [ ] Hide/restore the document and explicitly pause/resume; no missed wall-clock work is replayed.
- [ ] Verify visibility restoration does not undo an explicit pause.
- [ ] Verify audio suspends/resumes consistently and expired pre-unlock one-shots are not replayed.
- [ ] Verify manual SAMPLE does not perturb cadence/scenario random streams.
- [ ] Use deterministic signal fixtures for audio-reactive decision tests.
- [ ] Distinguish accelerated logical tests from real-time audio behavior and soak tests.
**Evidence:** clock/PRNG contract, logical traces, and browser/audio observations. No cross-device pixel or waveform equality claim is required.
## 5. GC5: Ownership and failure
- [ ] Define hook ordering, allowed hook actions, failure propagation, cleanup deadlines, deferred expiry/order, and dispatch-budget behavior.
- [ ] Start resources through nested events and confirm inherited scenario ownership.
- [ ] Verify duration overrides terminate with their owner and bounded releases eventually dispose.
- [ ] Verify persistent state mutations survive a later critical failure.
- [ ] Inject failures into startup, ordinary actions, and termination hooks; cleanup still completes.
- [ ] Verify condition triggers require a false condition before rearming.
- [ ] Verify at most one pending deferred request per definition, expiry, and eligibility recheck.
- [ ] Exercise event/scenario feedback and show bounded dispatch with diagnostics.
- [ ] Repeat completion/cancellation/failure cycles; counters return to baseline after releases finish.
**Evidence:** lifecycle traces, resource-count samples, and failure-injection results.
## 6. GC6: Performance and audio acceptance
- [ ] Record CPU/GPU/RAM, OS, browser version, 1920 x 1080 viewport, device-pixel ratio, sample rate, and relevant power settings.
- [ ] Fix benchmark exhibit/version/seed and counts for particles, links, trails, effect passes, audio nodes, and concurrent voices.
- [ ] Prototype combined visual/audio load early and record supported limits.
- [ ] Define warm-up duration, measurement window, frame interval sampling, and retained-memory sampling method before collecting acceptance data.
- [ ] Check the provisional p95 frame interval threshold of less than 33.3 ms and report progress toward the 60 FPS target.
- [ ] Record active resource baselines and verify expected return after repeated lifecycle operations.
- [ ] Specify and test digital output peak ceiling, numerical tolerance, finite samples, release behavior, and unavoidable master routing.
- [ ] Stress overlapping recipes and listen for clicks, clipping, and objectionable release artifacts.
- [ ] Run a two-hour development soak and an eight-hour release soak; record retained-memory trends, resource counts, frame intervals, audio glitches, and scheduler growth.
**Evidence:** fixed workload, environment, measurement method, results, and investigated anomalies. Any threshold revision must be recorded before rerunning acceptance; do not silently change the benchmark to produce a pass.
## 7. GC7: Scope, updates, and build
- [ ] Map all PRD completion criteria and challenge cases to milestones and evidence.
- [ ] Integrate two contrasting exhibits early; make Phase 9 the completion/audit phase for all five reference exhibits.
- [ ] Define import equality and parameter compatibility precisely.
- [ ] Verify identical imports are no-ops and changed same-ID content requires an explicit replacement choice.
- [ ] Verify invalid refreshes leave the last valid definition and configuration intact.
- [ ] Verify compatible parameter preservation, numeric bound changes with notice, removed/new parameters, and incompatible-type/enum resets.
- [ ] Validate and prepare a candidate without observable playback before stopping the working exhibit.
- [ ] Inject activation failure; dispose of the candidate and attempt a fresh restart of the previous exhibit with saved settings.
- [ ] Build separate source modules into one self-contained HTML artifact reproducibly.
- [ ] Test the delivered artifact directly and offline; no external runtime scripts, modules, assets, fonts, or CDN requests are required.
**Evidence:** implementation-plan coverage, library failure tests, build instructions, and artifact verification.
## Evidence record template
For each result, record gate/check ID, date, specification revision, implementation revision or artifact hash, environment, fixture/seed, procedure, expected result, actual result, pass/fail/not-applicable status, linked logs or measurements, and unresolved limitations. A not-applicable result requires a reason. Do not prefill results from intended behavior.