Labyricorn/XZBT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(visual): close the visual contract with the phase 4c automation, lifecycle, camera, effects, and ceiling rules

Browse Source 
Format Specification revision 0.7 adds section 19, the third and final
visual contract section, covering PRD 85-89 and 119-120.

Visual automation reuses the audio track shape of 16.1 and adds only
`loop`. It is declared in two scopes: `visuals.automation`, measured from
activation, and `visuals.systems.<id>.automation`, measured from that
system's instantiation boundary, so a track on a spawned system behaves
identically however late the spawn happens.

Section 8.1 gains exactly four visual rows, all system-level: camera
fields, layer opacity, system visibility, and post-effect parameters. No
per-object geometry, transform, or style property becomes externally
addressable in 0.1, so the statements in 17.14 and trace 19 of 18.10
survive unchanged. This is the decision 17.14 and 18.6 both deferred.

Systems are persistent or spawned by an explicit `lifecycle` enum. A
spawned system is a template, instantiated only by a spawn action, with a
five-state machine plus FAILED, a `0ms` default release, and a spawn
ceiling that refuses rather than evicts.

The camera matrix is normative, including that parallax multiplies the
camera translation only. `projection` is authored once and is neither
automatable nor bindable.

Seven post-effects, applied in normative array order with a stated
approximation boundary. `grain` is explicitly exempt from reproducibility
and consumes no procedural stream.

Section 19.5 is the centralized ceiling table PRD 120 requires. It
separates authoring bounds, which reject an exhibit at import, from
runtime ceilings, which shed work by a documented deterministic rule and
keep the exhibit running, and it restates every ceiling first fixed in
sections 10 and 14 through 18. Its aggregate values are provisional
pending the slice 4h GC6 measurement.

Two diagnostic codes added: ERR_INVALID_EFFECT_TYPE and
WARN_VISUAL_CEILING. ERR_AUTOMATION_CONFLICT widens to cover a visual
scope and the behavior collision rather than minting a second code.

Documentation only: no runtime, schema, fixture, or test file was
touched. The visual contract now contains no unresolved forward
reference, and npm test still passes 102 tests with zero failures.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01AzX3848PwqYwzdUCWvjegL
This commit is contained in:
Labyricorn
2026-09-06 04:29:40 +00:00
co-authored by Claude Opus 5
parent 2deec016d6
commit d3cd688a3c
4 changed files with 583 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/IMPLEMENTATION_STATUS.md
+32 -3
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; Phase 4 has begun with slices 4a and 4b, the first two of three visual contract sections. 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; 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
**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 open at Phase 4a-4b; 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, 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.
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,7 +14,7 @@ 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-1–3 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 and 4b complete; 4c–4h pending | [Slice-4a contract evidence](evidence/phase4/2026-09-06-phase4a-contract.md) and [slice-4b contract evidence](evidence/phase4/2026-09-06-phase4b-contract.md). Format Specification section 17 covers PRD 69–76 and section 18 covers PRD 77–84; section 19 (slice 4c) precedes any renderer implementation. Slice 4h and the PRD 130 visual challenge are user-observed. |
| 4 — Visual engine | Contract slices 4a, 4b, and 4c complete; 4d–4h 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 69–76, section 18 covers PRD 77–84, and section 19 covers PRD 85–89 and 119–120. 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 |
| 6 — Scenario director | Not started | Earlier phases and scenario contracts |
| 7 — Dynamic UI | Not started | Earlier phases and UI contracts |
@@ -112,3 +112,32 @@ Section 17 is contract only. No visual runtime code exists, the JSON Schema has
and nothing has been drawn from any build. The deliberate deferral of live numeric text readouts, and
the open question of whether sections 17-19 pass a multi-model review before slice 4d begins, are
recorded in the [slice-4a evidence](evidence/phase4/2026-09-06-phase4a-contract.md).
## Phase 4b and 4c visual contract (slices 2 and 3 of eight)
Format Specification revision 0.6 adds section 18: visual components and their construct-scoped `inputs`,
particle systems with a normative semi-implicit Euler integrator and `dt`-correct drag, nine placement
distributions with a normative sample order, emitters whose fractional accumulator makes cumulative
emission exactly `floor(rate x t)`, repeaters and the copy-scoped `repeat.*` namespace, a seventeen-behavior
vocabulary and the internal channel set behaviors may write, six procedural fields with a fully specified
coherent-noise function, and trails, ribbons, and links. Seven diagnostic codes were added.
Revision 0.7 adds section 19 and closes the contract: visual automation in two declaration scopes with
`repeat` and `ping-pong` loop modes, the persistent and spawned system lifecycle with its own six-state
machine and refuse-rather-than-evict spawn ceiling, the normative camera matrix and both projection modes,
a seven-effect post-processing chain with a stated approximation boundary, and the centralized runtime
ceilings for the whole engine. Two diagnostic codes were added, and the section 8.1 target-capability table
gained exactly four visual rows — camera fields, layer opacity, system visibility, and post-effect
parameters. No per-object visual property is externally addressable in 0.1.
Section 19.5 is now the single centralized ceiling table PRD 120 requires: it restates every ceiling first
fixed in sections 10 and 14 through 18 alongside the aggregate visual ceilings, and separates authoring
bounds, which reject an exhibit at import, from runtime ceilings, which shed work by a documented
deterministic rule and keep the exhibit running. Every aggregate value there is provisional in the same
sense the master-protection values of 16.7 are: the shape is normative, the numbers are confirmed or
replaced by the slice 4h GC6 measurement.
The visual contract now contains no unresolved forward reference, and `npm test` still passes 102 tests
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.