XZBT/docs/XZBT_0-1_Gap_Closure_Decisions.md

XZBT 0.1 Gap Closure Decisions

Record version: 0.3
Status: Phase 0 GC1–GC5 decisions and shared contract evidence complete; GC6/GC7 implementation evidence remains scheduled
Related resources: PRD, format specification, verification gates

Phase 6 implementation checkpoint (September 6, 2026): Format Specification section 21 completes the previously deferred scenario trigger/timeline shapes while preserving GC5 hook ordering, ownership, deferred expiry and bounded cleanup. One active instance per definition, symmetric exclusivity, cooldown from termination, dependency-resolved first timestamps and one lazy record per repeated entry make admission and finite execution explicit. Scenario streams are isolated per definition/instance. Production GC5 and accelerated Exhibit E evidence is recorded here. The real two-hour development soak and earlier hardware/listening gates remain pending.

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 (Passed)
2	Resource preface, 113, Phase 0, 145-146	GC2 (Shared contracts verified)
3	31-32, 54, 104	GC3 (Shared contract passed)
4	14, 102, 117-118	GC4 (Shared contract passed)
5	91, 94, 99-101	GC5 (Shared contract passed)
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. All 10 direct-file feasibility checks are verified with linked empirical evidence; GC1 is passed.

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. Shared contracts, structural schema, semantic validator, and 12-case test suite are verified; see GC2 evidence. Subsystem-specific contracts will be completed in dependency order before implementing each subsystem. 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 now fixes the shared target-capability registry, canonical source/target binding fields, zero-duration default smoothing, the exact one-pole smoothing equation, override priority defaults and runtime IDs, easing equations, and interrupted attack/release behavior. Draft from/to/transform spellings were reconciled to the PRD and are rejected rather than retained as aliases.

Gate: GC3. Passed by deterministic traces covering direct target overrides, parameter overrides flowing through bindings, overlapping priorities, user edits, release behavior, smoothing, clamps, conflicts, cycles, and unsupported targets.

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 the bounded horizon and late-work policy fixed by the format 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 earlier one-shots. Continuous ambience aligns at its current logical phase with a short engine-owned ramp; partially elapsed one-shots are skipped.

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. The 0.1 contract uses FNV-1a-32 domain derivation, SplitMix32 state expansion, and xoshiro128**, with stable known-vector tests.

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.

The fixed-step driver accepts at most 250 ms from one wall-time observation and runs at most eight logical ticks per browser turn. Audio scheduling uses a 100 ms horizon. Pre-unlock one-shots are skipped if their start is already past; still-owned continuous audio aligns to current logical state with a 20 ms engine ramp.

Gate: GC4. Shared clock/PRNG contract passed by deterministic render-frequency, stall, pause-reason, audio-unlock decision, known-vector, stream-isolation, and signal-fixture tests. Real Web Audio synchronization remains an audio-integration gate rather than a Phase 0 contract-oracle claim.

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. Natural completion uses onComplete; cancellation and critical failure use onCancel, with the original terminal result preserved. Termination hooks permit only set and nonpersistent one-shot sound actions. Bounded release fades continue under a cleanup owner for at most five logical seconds before forced disposal. No new failure-hook field is introduced.

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. Default expiry is five logical minutes; ordering is priority descending, creation tick ascending, then document order.

Validate event/scenario trigger cycles where statically detectable. Enforce a budget of 1024 ordinary dispatch units per logical tick as a runtime backstop, with a visible diagnostic when exhausted. Cleanup remains budget-exempt, with a separate 256-action termination-hook limit.

Gate: GC5. Passed by ownership, bounded-release, persistent-state, startup/action/hook failure, trigger-rearm, deferred-ordering, feedback-budget, and repeated lifecycle traces. Runtime subsystem implementations must repeat these traces with real resource counters.

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.