XZBT/docs/XZBT_0-1_Verification_Gates.md

XZBT 0.1 Verification Gates

Status: Planning checklist; every check is pending
Related resources: PRD, decisions, format specification

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.