12 KiB
XZBT 0.1 Gap Closure Decisions
Record version: 0.1
Status: Incorporated into the planning baseline; implementation verification pending
Related resources: PRD, format specification, verification gates
Numbering preserves the seven gaps discussed during PRD preparation. Recording a decision closes a design question; it does not establish that a browser feature, performance target, or lifecycle guarantee has passed testing.
| Gap | Primary PRD placement | Supporting verification |
|---|---|---|
| 1 | 3.4, 109-111, 122, 132, Phase 0 | GC1 |
| 2 | Resource preface, 113, Phase 0, 145-146 | GC2 |
| 3 | 31-32, 54, 104 | GC3 |
| 4 | 14, 102, 117-118 | GC4 |
| 5 | 91, 94, 99-101 | GC5 |
| 6 | 58, 119-120, 133, 144 | GC6 |
| 7 | 108-110, 126-128, 134-135, 143-145 | GC7 |
1. Standalone HTML deployment model
Decision: Opening XZBT.html directly in a desktop Chromium browser is the primary 0.1 launch method. The distributed application needs no server, installation, or network connection. Development tooling may use a local server, but it cannot substitute for testing the delivered file directly.
Use IndexedDB for the exhibit cache and saved configuration. Always provide ordinary file-picker import. Directory import and remembered source handles are optional enhancements where available. A source handle is not the startup dependency: cached definitions are.
Verify file import, audio unlock, cache writes, browser restart, and cache restoration in the actual target environment. If the selected audio implementation needs AudioWorklet, verify loading engine-owned worklet code from the self-contained artifact. Exhibit-authored executable code remains prohibited.
Moving or renaming the HTML is a separate compatibility case. Do not promise that browser storage follows it. When storage is unavailable, retain session playback and explain that exhibits must be imported again on a later launch. This fallback does not waive the ordinary-mode persistence acceptance requirement.
Gate: GC1 in the verification checklist. A failure of direct-file persistence in the chosen supported environment reopens the deployment decision; do not silently replace the distribution promise with hosted-only operation.
Verified packaging refinement: The version 3 manual probe loads and connects the engine-owned worklet from an embedded data URL in direct-file Chrome 152; the earlier Blob URL approach failed in the same user's testing. Use the verified data-URL approach for this packaging path, with an explicit page script-source allowlist and network connections disabled. This does not permit exhibit-authored executable code or declare the remaining GC1 checks complete.
Basis: MDN file-origin behavior, Chrome File System Access API, and AudioWorklet requirements. These describe platform constraints, not evidence that the XZBT prototype has passed.
2. One authoritative format specification
Decision: Separate product requirements from exact authoring contracts. Maintain the companion Format Specification 0.1 and an internal structural JSON Schema, with additional semantic validation for references, graph legality, ownership, and limits.
For each exposed construct, specify JSON shape, required fields, defaults, units, ranges, ValueSpec support and evaluation timing, readable/writable targets, lifecycle, errors, and examples. Reject unknown fields in behavior-bearing objects. Define any allowed metadata extensions explicitly rather than permitting arbitrary executable-looking configuration.
Complete valid exhibits and invalid fixtures are required alongside each contract. Reconcile relevant details from the earlier discussion into the local specification. The current format document is a foundation and completeness register, not a claim that all grammar has been formalized.
Gate: GC2. Exact shared contracts precede their implementations; remaining subsystem contracts may be completed in dependency order. Publishing the schema and editor autocomplete remain optional post-MVP work. Maintaining an internal schema is required for 0.1.
3. Bindings, overrides, and automation
Decision: Resolve each target through base value, binding, automation, winning override, modulation, and safety clamp, using only stages supported by that target. Parameters and state have separate storage; state is not a universal layer above user configuration.
References ordinarily read resolved values. Configuration controls read and edit the user's stored parameter value and indicate an active override. Underlying bindings and automation continue evaluating while masked.
Override scope controls lifetime; explicit or inherited priority controls precedence. Equal priorities use activation order. Duration overrides do not automatically outrank scenario overrides. Release transitions approach the currently resolved underlying value, including changes made while masked. Additive modulation may remain after an override only on targets whose contracts permit it.
Reject competing ordinary bindings and unresolvable dependency cycles. The format specification must finish the target-capability and transition rules before the resolver is implemented.
Gate: GC3. Expected traces cover direct target overrides, parameter overrides flowing through bindings, overlapping priorities, user edits, and release behavior.
4. Clock and reproducibility
Decision: Use a logical simulation clock with an initial fixed update step of 1/60 second. Rendering is independent. Map logical audio scheduling to the audio clock with a bounded scheduling horizon; the exact horizon and late-work policy require prototype measurements and a written contract.
In 0.1, document visibility loss pauses the entire performance by default, including audio. Explicit application pause does the same. Resume from the previous logical position without replaying elapsed wall-clock time. Visibility return must not undo an explicit user pause. Background playback is a separately specified future capability.
Visuals may start before audio is unlocked, as permitted by the PRD. On unlock, begin audio at the current logical position without replaying expired sounds; the format contract must specify how continuous ambience and partially elapsed sounds initialize.
Derive isolated random streams from the exhibit seed for cadence, scenarios, visual systems, and sound instances. Manual SAMPLE playback has an independent stream. Record the actual numeric seed when the exhibit requests a random seed.
Reproducibility means identical procedural decisions for the same runtime version, seed, and logical input sequence. It does not promise identical pixels or audio samples across devices. Deterministic tests use recorded or synthetic audio-analysis signals where such signals affect decisions.
Gate: GC4. Render frequency, pause duration, and independent sound sampling must not perturb unrelated logical choices.
Basis: MDN Page Visibility API documents background frame/timer behavior. This decision supplies XZBT's product policy rather than relying on browser throttling as its scheduler.
5. Scenario ownership and failure
Decision: Propagate ownership through action execution and nested events. Indirectly created resources inherit the originating scenario unless a resource contract explicitly permits persistent ownership and the exhibit requests it.
A duration override created under a scenario expires at its deadline or when the owner terminates, whichever happens first. State mutations are persistent and are not rolled back after completion, cancellation, or failure. Failure cleanup removes temporary effects; scenarios are not transactions.
On termination, stop ordinary dispatch, cancel future work, run the applicable termination hook, and guarantee cleanup even when the hook fails. Bounded release fades may continue under a cleanup owner until final disposal. Hook execution order and permitted hook actions must be finalized in the format specification; no new failure-hook field is introduced by this record.
Condition triggers fire once after the qualifying condition has held for the declared interval, then require a false condition before rearming. A scenario definition has at most one pending deferred request, with an expiry and an eligibility recheck at dispatch. Exact queue ordering and default expiry must be specified before implementation.
Validate event/scenario trigger cycles where statically detectable. Enforce a per-update dispatch budget as a runtime backstop, with a visible diagnostic when exhausted. Cleanup must still run when ordinary dispatch is curtailed.
Gate: GC5. Repeated completion, cancellation, and injected failures return resource counts to the expected baseline after bounded releases finish.
6. Performance and audio acceptance
Decision: Record a real reference computer, OS, browser version, device-pixel ratio, audio sample rate, and a 1920 x 1080 test viewport. Fix a benchmark exhibit combining particles, links, trails, post-processing, and overlapping procedural audio.
Target 60 FPS. Use a provisional acceptance threshold of a 95th-percentile frame interval below 33.3 ms under the recorded benchmark workload. This is a reference-workload target, not a guarantee for every valid exhibit or device. Measure the workload before fixing final supported ceilings; do not silently reduce the workload between comparisons.
Expose resource counters for nodes, voices, visual instances, subscriptions, and scheduler records. Repeated lifecycle tests must return to expected baseline after releases and queued disposal finish. Retained memory must plateau after warm-up; record sampling method and investigate sustained growth rather than treating a transient allocation peak as a leak.
Require a two-hour development soak and an eight-hour release soak. Accelerated logical-time tests supplement, but do not replace, real-duration runs.
Specify master protection as a tested output stage with finite samples, a defined digital peak ceiling, controlled release, and no bypass. The exact ceiling, tolerances, and release settings must be recorded before audio acceptance. Test worst-case overlapping recipes and listen for clicks and distortion. A digital peak ceiling is not a guarantee of physical listening volume.
Gate: GC6. Early combined-load measurements inform architecture and limits; full benchmark acceptance and soak results are release gates.
7. Release scope and library updates
Decision: Preserve all PRD MVP completion criteria. Early integrated demonstrations are milestones, not a reduced definition of the finished MVP. Develop contrasting reference exhibits alongside supporting engine capabilities. Phase 9 completes and audits the suite.
Identical imports are no-ops. Changed content with an existing exhibit ID requires an explicit replacement choice. Invalid source refreshes preserve the last valid definition and compatible settings. Compatible numeric preferences are clamped to changed bounds with notice; incompatible preferences revert to declared defaults. Removed parameters are discarded and new ones receive defaults. Define exact compatibility and content-equality rules before persistence implementation.
Validate and prepare a replacement exhibit before stopping the working one. Preparation must not start audible or visible activity. If activation subsequently fails, dispose of the failed candidate and attempt to restart the previous exhibit with its saved configuration. A restarted exhibit is a fresh performance, not restoration of its prior scenario clock. Report failure if recovery also fails.
Develop separate source modules and build them into a reproducible, self-contained XZBT.html. No runtime module, asset, font, or CDN dependency may be required outside the delivered file. Single-file distribution does not require single-file development.
Gate: GC7. The implementation plan identifies integrated milestones, safe update paths, reference-exhibit coverage, and the single-file build check.