docs: raise the format specification to revision 0.9 and land the reconciliation

Revision 0.9 adds section 20, the cadence and event subsystems contract, and
carries two corrections the implementation forced. Section 6.1 now states that a
duration is the authored literal or a non-negative finite number already in
milliseconds, since a DurationSpec may be the resolved output of a ValueSpec or
a bounded TimeSpec, with the one documented exception of an automation track's
`at`, which 19.1 keeps literal-only so that point ordering stays decidable at
import. Section 20.11 documents the rejection of an undeclared input name in an
event action's `with` map as ERR_UNKNOWN_FIELD — the section's own convention
for that shape of error, replacing an invented code that appeared nowhere in the
registry.

The review record is committed with the code it describes: the two code triages
that found these defects, the reconciliation plan that sequenced the fixes, and
a follow-up debt record listing what was deliberately left open — the unchecked
JSON Schema artifact, degenerate path arcs, post-effect transient allocation,
the window-traffic fixture's per-copy wrap bounds, and the unstated
`ownership: "persistent"` value on a sound action. None of the five blocks phase
6; all five are written down rather than dropped.

Devlog entries are backfilled for the two milestones that had none: phase 3c
slice 2, the audio lifecycle and voice ceilings, and slice 4d, the renderer
core. The implementation status summary now reflects the reconciled state rather
than the in-flight one.

231 tests pass. tools/verify-spec-contract.py reports 46 declared diagnostic
codes with every used code resolving and its two long-standing unresolved
cross-references unchanged.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01ShxxFqFmCUDQnQvFNm4TKy
This commit is contained in:
2026-09-06 21:54:09 +00:00
co-authored by Claude Opus 5
parent 3db1df058f
commit c4332363a9
30 changed files with 7892 additions and 137 deletions
+20 -4
View File
@@ -1,10 +1,10 @@
# XZBT implementation status
**Updated:** September 6, 2026
**State:** Phase 3 audio engine implemented through slice 3c-4 and automatically verified; the Phase 4 visual subsystem contract is complete across slices 4a, 4b, and 4c, and no visual runtime code exists yet. Slice 3c-4 hardware measurement/listening acceptance, the Phase 3 audible gates, and the Phase 1 direct-file import/restart observation remain pending
**State:** Phase 3 audio engine implemented through slice 3c-4 and automatically verified; Phase 4 visual implementation is complete through 4g, with automated verification and a standalone visual challenge page; Phase 5 Events and Cadence implemented and verified across all 14 traces and reference exhibits AD. The Phase 4d4g and Phase 5 review triages ([reviews/02-triage.md](../reviews/02-triage.md), [reviews/03-phase5-triage.md](../reviews/03-phase5-triage.md)) have been worked through: every Tier-1 finding is fixed and covered by a test on the production code path, and the residual items are tracked in [reviews/04-followup-debt.md](../reviews/04-followup-debt.md). Slices 3c-4/4h hardware measurement/listening acceptance and Phase 1 direct-file import/restart observation remain pending; Phase 6 (scenario director) is unblocked
**Planning baseline:** `05fe2b4e021ba86e4a290d05b63c7cae0e386128`
**Exact demarcation:** GC1 direct-file feasibility (10/10 checks), GC2 shared format contracts, GC3 resolution semantics, GC4 clock/PRNG semantics, and GC5 ownership/failure semantics are complete at the Phase 0 contract-oracle level. The Phase 1 production runtime skeleton, Phase 2 common grammar, and audio engine through Phase 3c slice 4's implementation pass automated checks. Phase 1's direct-file two-fixture restart observation, Phase 3's audible acceptance (no sound has been heard from a production build), and real-browser measured master protection remain open. The visual subsystem contract is complete at Phase 4a-4c and its aggregate ceilings are provisional pending the slice 4h GC6 measurement; visual implementation, cadence/event, scenario, final generated-UI, performance, and soak work remains assigned to later phases.
**Exact demarcation:** GC1 direct-file feasibility (10/10 checks), GC2 shared format contracts, GC3 resolution semantics, GC4 clock/PRNG semantics, and GC5 ownership/failure semantics are complete at the Phase 0 contract-oracle level. The Phase 1 production runtime skeleton, Phase 2 common grammar, audio engine through Phase 3c slice 4's implementation, visual engine through 4g, and Phase 5 Events and Cadence pass automated checks. Phase 1's direct-file two-fixture restart observation, Phase 3's audible acceptance (no sound has been heard from a production build), and real-browser measured master protection remain open. The visual subsystem contract is complete at Phase 4a-4c and its aggregate ceilings are provisional pending the slice 4h GC6 measurement; visual implementation through 4g is present; scenario director, final generated-UI, measured performance, and soak work remain assigned to later phases.
The user requested sequential implementation with a stop on problems. The [manual version 3 evidence](evidence/phase0/2026-09-04-user-run-v3.md) verifies embedded data-URL worklet loading in direct-file Chrome. The subsequent [user-performed restart test](evidence/phase0/2026-09-04-user-restart.md) restored Blue Study activity 0.37 and master volume 0.19 immediately on reopening. Native tone output and AudioContext suspend/resume are also observed. Ordinary file import, selection of both exhibits, regular Chrome mode, and [directory cancellation/denial fallback](evidence/phase0/2026-09-05-user-directory-fallback.md) have been confirmed.
@@ -14,8 +14,8 @@ The user requested sequential implementation with a stop on problems. The [manua
| 1 — Runtime skeleton | Implemented; acceptance pending | [Automated evidence](evidence/phase1/2026-09-05-runtime-skeleton.md) passes production-module, lifecycle, PRNG-vector, cache/restore, fixture-validation, and deterministic-build tests. Direct-file two-fixture import/restart remains a user-observed gate. |
| 2 — Common grammar | Complete | [Automated evidence](evidence/phase2/2026-09-05-common-grammar.md) covers production GC2 conformance, typed values, signals, actions, same-tick bindings, transitions, override precedence/release, and parameter restoration. |
| 3 — Audio engine | Slices 3c-13 complete; 3c-4 implementation verified, user acceptance pending | [Contract](evidence/phase3/2026-09-05-phase3c-contract.md), [lifecycle/voices](evidence/phase3/2026-09-05-phase3c-lifecycle-voices.md), [automation](evidence/phase3/2026-09-05-phase3c-automation.md), and [protection evidence](evidence/phase3/2026-09-05-phase3c-protection.md). Slice 4 requires real-browser measurement and user listening; PRD 129 and real GC4 audio acceptance remain open. |
| 4 — Visual engine | Contract slices 4a, 4b, and 4c complete; 4d4h pending | [Slice-4a](evidence/phase4/2026-09-06-phase4a-contract.md), [slice-4b](evidence/phase4/2026-09-06-phase4b-contract.md), and [slice-4c contract evidence](evidence/phase4/2026-09-06-phase4c-contract.md). Format Specification section 17 covers PRD 6976, section 18 covers PRD 7784, and section 19 covers PRD 8589 and 119120. Slice 4d is the first slice that writes renderer code. Slice 4h and the PRD 130 visual challenge are user-observed. |
| 5 — Events and cadence | Not started | Earlier phases and event/cadence contracts |
| 4 — Visual engine | Implemented through 4g; user acceptance pending | [4e procedural evidence](evidence/phase4/2026-09-06-phase4e-procedural.md), [4f execution evidence](evidence/phase4/2026-09-06-phase4f-execution.md), [4g fixtures](evidence/phase4/2026-09-06-phase4g-challenges.md). Fourteen challenge fixtures and first visuals for AD execute without subject-specific renderer code. Slice 4h and PRD 130 display judgment remain open. |
| 5 — Events and cadence | Complete | [Automated evidence](evidence/phase5/2026-09-06-phase5-events-cadence.md) covers contract Section 20, schema/validation with static cycle detection, 1024-action budget, 16-level nesting, priority cadence clocks, minGap, recency relaxation, ambient voices, and manual SAMPLE PRNG isolation. |
| 6 — Scenario director | Not started | Earlier phases and scenario contracts |
| 7 — Dynamic UI | Not started | Earlier phases and UI contracts |
| 8 — Library and persistence hardening | Not started | Earlier phases and library contracts |
@@ -141,3 +141,19 @@ The visual contract now contains no unresolved forward reference, and `npm test`
with zero failures — all three slices are documentation-only. `src/runtime` has no renderer module, the
JSON Schema has no visual definitions, and nothing has been drawn from any build. Whether sections 17-19
pass a multi-model review before slice 4d begins remains the one open decision, and 4d is the next slice.
## Phase 4e4g implementation
Final verification: **223 checks pass**, including **109 Phase 4 tests**. Both standalone builds are deterministic; see the [4f evidence](evidence/phase4/2026-09-06-phase4f-execution.md) for exact test execution and artifact hashes.
The procedural runtime advances graphic, component, emitter and repeater object behaviors on logical ticks, including point motion and morph geometry. System-local automation updates the render inputs; exhibit automation uses the shared resolution pipeline for public visual targets. Spawned instances have bounded ownership, release, disposal and atomic refusal. Seven post-effects execute on frame pixels; aggregate ceilings remain provisional pending measurement.
All fourteen PRD 130 challenge fixtures and first visual compositions for Exhibits AD are authored data. The standalone [visual review page](../prototypes/phase4/XZBT-visual-acceptance.html) supplies reproducible test signals and observation export. Automated checks establish execution and deterministic decisions, not visual quality, live audio acceptance, full reference-exhibit completion, or the 4h benchmark. Earlier contract-only checkpoints below remain historical evidence.
## Phase 5 events and cadence
Final verification: **229 checks pass**, including **14 Phase 5 tests**. Both standalone builds are deterministic; the production artifact hash is `f3f634d7d33b2f8a57cae541fc31b4dcedce88b2ee2648093f92a2cfc168d718`. See the [Phase 5 evidence](evidence/phase5/2026-09-06-phase5-events-cadence.md) for detailed trace coverage and implementation details.
Format Specification revision 0.9 adds Section 20, completing the Cadence and Event subsystems contract with 14 acceptance traces. The JSON Schema and semantic validator enforce DAG event cycle detection (`ERR_CYCLIC_DEPENDENCY`), cadence clock range ordering (`ERR_INVALID_RANGE_ORDER`), and sound cadence metadata. The Action Model enforces the 1024-unit/tick dispatch budget (`ERR_DISPATCH_BUDGET`), 16-level event nesting depth limit, event parameter scoping and strict type validation (`ERR_TYPE_MISMATCH`, `ERR_UNKNOWN_FIELD`), and sound usage gating (`ERR_UNSUPPORTED_TARGET`). The CadenceSubsystem schedules four class clocks (`routine`, `intermittent`, `occasional`, `rare`), enforces the 1.5s minimum gap with class priority ordering, applies anti-repetition recency multipliers (`[0.0, 0.25, 0.50, 0.75]`) with pool relaxation on deadlock, maintains continuous ambient voices, and runs on an isolated PRNG stream (`cadence` domain). Exhibits AD include complete audio buses, sound recipes, cadence clocks, and lifecycle events.