XZBT/docs/evidence/phase6/2026-09-06-scenario-director.md

Phase 6: Scenario Director Acceptance Evidence

Date: September 6, 2026
Status: Implementation and automated acceptance complete; real-duration two-hour development soak and hardware/listening gates pending
Specification References: PRD 92–102 (Scenario Model 0.1), 131 (Scenario Acceptance Challenge), 140 (Development Phase 6: Scenario Director); Format Specification Revision 0.10, Section 21 ("Scenario Model 0.1")

---

1. Executive Summary

Phase 6 completes the Scenario Director and Scenario Model 0.1 of XZBT, delivering:

1. Contract & Schema: Complete Section 21 normative contract in the Format Specification and authoritative JSON Schema definitions in schema/xzbt-0.1.schema.json for ScenarioDefinition, ScenarioTrigger, TimelineEntry, ConcurrencySpec, EligibilitySpec, and ScenarioControlAction.
2. Static & Semantic Validation: Implemented in src/runtime/scenario-validation.js, integrated with src/runtime/validator.js and standalone CLI tools/validate-exhibit.mjs. Enforces authoring bounds (at most 64 definitions, 1024 entries per definition, 1024 repeat occurrences), identifier patterns, non-negative literal durations, trigger parameters, cycle detection on anchor dependencies (after), termination hook action restrictions (set and non-persistent one-shot sound only; ERR_UNSUPPORTED_TARGET), and scenario control actions (start, stop, enable, disable).
3. Runtime Scenario Director Subsystem: Implemented in src/runtime/scenario.js and integrated with src/runtime/performance.js, src/runtime/actions.js, src/runtime/audio-engine.js, src/runtime/resolution.js, and src/runtime/app.js:
   • Seven Trigger Types: manual, once, interval, random-interval, probability, condition (with startup hold disarming, hold interruption, and false-tick rearming per GC5), and event.
   • Admission & Concurrency: Symmetric exclusivity (scope: 'global' | 'group'), replacement policy (replace requiring strictly higher priority), deferred queues (policy: 'defer') with single-request deduplication and 5-minute logical timeout, and capacity limits (at most 16 active instances, at most 1 active instance per definition).
   • Timeline Scheduling: Absolute (at) and relative (after + delay) timestamps, anchor dependency resolution, deterministic tie-breaking, lazy finite repeats (repeat.count up to 1024, repeat.every), and weighted branching (choose) with conditional filtering and per-instance PRNG stream isolation (scenario / <id>:<ordinal>).
   • Ownership & Bounded Cleanup: scenario, persistent, and performance ownership. Resource tracking across real voice pools, visual instances, and parameter/bus duration overrides. On termination, future timeline entries are removed, termination hooks run, active resources transfer to bounded cleanup owners (capped at 5000ms), and visual instances honor originating scenario relations.
   • Logical Clock Synchronization & Pre-unlock Intents: Shared logical time, pause/resume reasons (user, visibility), and retention of up to 16 pre-unlock continuous sound intents started by scenarios.
   • Accelerated Development Time: advanceTicks() executing production fixed ticks without wall-clock delay or native audio overhead.
4. Content Integration: Authored exhibits:
   • exhibits/exhibit-e.xzbt: Exhibit E — Long Passage, a forty-minute procedural scenario with approach, repeated signals, branching disturbance, and recovery.
   • exhibits/scenario-challenge.xzbt: Scenario Challenge fixture covering 5-second, 3-minute, condition hold, event trigger, exclusive group, and deferred queue cases.
   • exhibits/exhibit-a.xzbt & exhibits/exhibit-b.xzbt: Augmented with temporary scenario overrides (withTemporaryScenario()).
   • prototypes/phase6/workload-v1.xzbt: Frozen workload for development soak testing (seed 4206).
5. Acceptance & Soak Tooling: prototypes/phase6/XZBT-scenario-acceptance.html, prototypes/phase6/acceptance.js, and prototypes/phase6/README.md providing standalone, zero-dependency browser testing with live controls, 40-minute accelerated advancement, and two-hour real-time soak data collection with exact Web Audio frame capture.
6. Verification: All 15 acceptance traces of Section 21.6 verified in test/phase6-scenarios.test.mjs (traces 1–14 automated; trace 15 tooling and workload delivered). The full repository test suite passes 252 checks with 0 failures. Independent builds of XZBT.html and XZBT-scenario-acceptance.html produce deterministic, byte-identical SHA-256 digests.

---

2. Test Execution and Acceptance Traces

The 15 acceptance traces defined in Section 21.6 of the Format Specification:

Trace	Title	Verification Target	Status
Trace 1	Duration Endpoints	Five-second and multi-minute duration endpoints; boundary beats at the exact endpoint execute before completion; empty undurated scenarios complete in their start tick.	PASS
Trace 2	Relative Timing & Repeats	Absolute/relative ties maintain definition and entry document order; forward relative references (after) resolve correctly; repeat intervals stay lazy without expanding upfront.	PASS
Trace 3	Weighted Branching	Weighted choices exclude false condition and zero-weight branches; preserves per-instance PRNG streams; manual SAMPLE evaluations do not alter decisions.	PASS
Trace 4	Trigger Types	Verifies once, interval, probability, random-interval, manual, and event triggers fire at expected timestamps.	PASS
Trace 5	Condition Trigger (GC5)	Startup-true condition disarming (must observe a false tick first), hold timer cancellation on interruption, and false-tick rearming.	PASS
Trace 6	Deferred Queue (GC5)	Deduplication preserves original expiry timestamp and input scope; rechecks eligibility and cooldown on admission; 5-minute timeout expiry.	PASS
Trace 7	Exclusivity & Concurrency	Symmetric global/group exclusivity; parallel starts; higher-priority replacement cancels victim; active capacity defers atomically.	PASS
Trace 8	Nested Event Ownership (GC5)	Resources created through nested events inherit the scenario owner; exercises real voice pools, visual instances, and duration overrides.	PASS
Trace 9	Lifecycle Cleanup (GC5)	Completion, cancellation, critical startup failure, and action failure preserve prior set mutations, run cancel hooks, and continue past hook failure.	PASS
Trace 10	Duration Override Release (GC5)	Scenario termination bounds duration override release to 5s max; masked user edits remain stored and restore on release.	PASS
Trace 11	Termination Hook Budget (GC5)	Ordinary dispatch budget exhaustion (1024 units) cannot be softened and preserves the independent 256-action termination hook budget.	PASS
Trace 12	Repeated Cycle Baseline (GC5)	24 repeated completion, cancellation, and failure cycles return all production counters and native allocations to exact baseline.	PASS
Trace 13	Accelerated Exhibit E	Forty logical minutes run through production fixed ticks; two runs with equal seeds produce byte-identical decision traces.	PASS
Trace 14	Pause/Resume & Disposal	User and visibility pause reasons preserve logical time; disposal clears active ownership and removes all subscriptions.	PASS
Trace 15	Two-Hour Development Soak	Frozen combined workload (workload-v1.xzbt, seed 4206) in standalone acceptance runner. Physical run requires real hardware and listening.	Tooling Ready (User Gate)

Test Suite Execution Output

> node test/phase6-scenarios.test.mjs

✔ 21.6.1 duration boundary beats run before completion, empty finite timelines complete (55.9253ms)
✔ 21.6.2 absolute/forward-relative ties keep document order and repeats stay lazy (1.6336ms)
✔ 21.6.3 weighted choices exclude false/zero branches and preserve per-instance randomness (2.4319ms)
✔ 21.6.4 once, interval, probability, random interval, event and manual opportunities (1.6158ms)
✔ GC5 condition startup disarming, interrupted hold and false-tick rearming (1.1711ms)
✔ GC5 deferred deduplication preserves expiry and rechecks eligibility and cooldown (0.4421ms)
✔ 21.6.7 group/global exclusivity is symmetric; replacement is strict and deferred order stable (0.6647ms)
✔ 21.6.7 active capacity defers atomically and admits after cancellation (0.8045ms)
✔ GC5 nested ownership uses real voice pools, visual instances and duration overrides with bounded cleanup (19.3919ms)
✔ GC5 critical startup/ordinary failures preserve set, run cancel hook, continue past hook failures (0.6007ms)
✔ GC5 dispatch exhaustion cannot be softened and reserves termination hook budget (7.7733ms)
✔ GC5 repeated completion/cancellation/failure cycles return production counters and native allocations to baseline (140.7785ms)
✔ 21.6.14 pause reasons and direct disposal clear active ownership before resource teardown (0.7258ms)
✔ continuous pre-unlock intentions disappear with their owner and never replay one-shots (0.3824ms)
✔ scenario control stop blocks remaining ordinary actions for the terminated owner (0.2923ms)
✔ scenario contract rejects malformed shapes, dangling anchors, feedback and unsupported hooks in both validators (3.2885ms)
✔ 21.6.13 Exhibit E completes forty logical minutes through production fixed ticks reproducibly (8429.4419ms)
✔ signals.scenario.active is visible to onStart and termination hooks in the same tick (0.3851ms)
✔ a persistent sound and a detached persistent visual survive their originating scenario (6.5028ms)
✔ production audio releases obey paused logical time and dispose after the bounded release (5.2905ms)
✔ scenario acceptance build is reproducible and embeds only valid declarative fixtures (20.2825ms)
ℹ tests 21
ℹ suites 0
ℹ pass 21
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 8706.5378

Full repository regression (npm test): 252 tests pass, 0 fail.

---

3. Content and Exhibit Validation

All exhibits and challenge fixtures validate with 0 errors via tools/validate-exhibit.mjs:

> node tools/validate-exhibit.mjs exhibits/exhibit-e.xzbt exhibits/scenario-challenge.xzbt exhibits/exhibit-a.xzbt exhibits/exhibit-b.xzbt exhibits/exhibit-c.xzbt exhibits/exhibit-d.xzbt prototypes/phase6/workload-v1.xzbt

[PASS] exhibits/exhibit-e.xzbt (0 errors)
[PASS] exhibits/scenario-challenge.xzbt (0 errors)
[PASS] exhibits/exhibit-a.xzbt (0 errors)
[PASS] exhibits/exhibit-b.xzbt (0 errors)
[PASS] exhibits/exhibit-c.xzbt (0 errors)
[PASS] exhibits/exhibit-d.xzbt (0 errors)
[PASS] prototypes/phase6/workload-v1.xzbt (0 errors)

• Exhibit E (exhibits/exhibit-e.xzbt): Forty-minute journey with 12 repeated signal beats, branching disturbance/drift overrides, continuous drone sound, visual spawned rotating rings, cadence interaction, and clean recovery.
• Scenario Challenge (exhibits/scenario-challenge.xzbt): Six scenarios demonstrating 5-second, 3-minute, condition hold, event trigger, exclusive group, and deferred queue policies.
• Exhibits A & B (exhibits/exhibit-a.xzbt, exhibits/exhibit-b.xzbt): Augmented with temporary disturbance scenario override driving activity, cadence intensity, and continuous resonance sound.
• Soak Workload (prototypes/phase6/workload-v1.xzbt): Combines forty-minute journey with 5-second resource cycles every 20 seconds under seed 4206.

---

4. Deterministic Build Digest

Rebuilding runtime and acceptance artifacts via tools/build-xzbt.mjs and tools/build-scenario-acceptance.mjs:

Artifact	File Size	SHA-256 Digest	Determinism
XZBT.html	544,151 bytes	8c34cf53cd9252fe5de7376a0af00d906c28f5a656ce89071311cc791fb1a1ef	Byte-identical across clean builds
prototypes/phase6/XZBT-scenario-acceptance.html	534,145 bytes	9ffe5712b0848f0507c41db44638624b97729ae7feb7bc37923fae400938e94e	Byte-identical across clean builds
prototypes/phase4/XZBT-visual-acceptance.html	542,481 bytes	6700c26b71b64de4ed719aead76ffa07c330109d3a707428d09c6d4042956d9a	Byte-identical across clean builds

---

5. Verification Boundaries and Open Gates

1. Automated Acceptance: Closed. All 14 programmatic acceptance traces, validation rules, budget constraints, baseline recoveries, and the accelerated 40-minute Exhibit E pass automated verification.
2. Two-Hour Development Soak (GC6): Open. The standalone runner prototypes/phase6/XZBT-scenario-acceptance.html and frozen workload workload-v1.xzbt are delivered and verified. In accordance with the project testing boundary, running the 7200-second continuous soak and recording audio listening observations/frame histograms requires a physical reference system (1920 × 1080) and user observation.
3. Earlier User-Observed Gates: Direct-file restart (Phase 1), audible listening/protection acceptance (Phase 3), and Phase 4h hardware benchmark remain open at their scheduled gates.