docs(visual): specify the phase 4a scene, primitive, and appearance contract

Open the Visual subsystem contract at Format Specification revision 0.5 with
section 17, covering PRD 69-76: the renderer-neutral pipeline, canonical units
on a single degrees convention, the visuals container, layers, the scene model
with three coordinate spaces and three fit modes, 2.5D depth with a fixed sign,
stable sorting, parallax, perspective factor and per-object fog, the fourteen
primitives of Visual Primitive Set 0.1, common visual properties, a normative
transform composition order, appearance with the eight-mode safe blend set and
gradient paint, paths and splines with independently addressable points, text
restricted to the three generic font families, and the once-at-instantiation
resolution boundary for visual ValueSpec fields.

Visual objects are keyed rather than listed and carry no id field, matching the
audio node-identity rule that a Phase 3a blocking defect established. No visual
property becomes externally addressable in this slice; a binding, set, or
override naming one remains ERR_UNSUPPORTED_TARGET, and section 8.1 is
unchanged until section 19.1 adds its rows.

Add five diagnostic codes to the section 7 table, record the eight-slice Phase 4
delivery plan, mark the section 11 Visuals register row in progress, and refresh
the implementation status, which had not been updated since the 3c-1 contract.

Documentation only; no runtime, schema, fixture, or test file is touched.
npm test passes 102 tests with zero failures.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01GwmTQU6zLwh3qbBvq5zf5B

docs/IMPLEMENTATION_STATUS.md

@@ -1,10 +1,10 @@
 # XZBT implementation status
 
-**Updated:** September 5, 2026
-**State:** Phase 3c slices 1–3 complete; slice 4 master protection implemented and automatically verified. Slice 4 hardware measurement/listening acceptance, the Phase 3 audible gates, and the Phase 1 direct-file import/restart observation remain pending
+**Updated:** September 6, 2026
+**State:** Phase 3 audio engine implemented through slice 3c-4 and automatically verified; Phase 4 has begun with slice 4a, the first 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
 **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. Visual, 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 open at Phase 4a; 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 | Not started | Earlier phases and visual contracts |
+| 4 — Visual engine | Contract slice 4a complete; 4b–4h pending | [Slice-4a contract evidence](evidence/phase4/2026-09-06-phase4a-contract.md). Format Specification section 17 covers PRD 69–76; sections 18 and 19 (slices 4b, 4c) precede any renderer implementation. 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 |
@@ -90,3 +90,25 @@ The placeholder compressor is replaced by an embedded AudioWorklet with stereo-l
 `npm test` passes **102 tests**, including 14 slice-4 tests. Production and acceptance builds are deterministic and self-contained. The [protection evidence](evidence/phase3/2026-09-05-phase3c-protection.md) records coverage and limits. A [standalone user-run page](../prototypes/phase3/XZBT-audio-acceptance.html) provides a frozen overlap workload, exact audio-frame capture, twelve challenge recipes and JSON export; see [run instructions](../prototypes/phase3/README.md).
 
 **Acceptance checkpoint:** Implementation is ready for user testing. The candidate −1 dBFS ceiling, 0.1 dB tolerance and audible release behavior remain provisional. No production audio has been heard or measured; traces 15–17, PRD 129, reference-exhibit listening and real GC4 synchronization remain open. Phase 3 is not accepted, and later phases have not started.
+
+## Phase 4a visual contract (slice 1 of eight)
+
+Format Specification revision 0.5 adds section 17, the first of three Visual subsystem contract
+sections. It fixes the visual pipeline and its renderer-neutral scope, canonical units with a single
+degrees convention, the `visuals` container, layers, the scene model and the `normalized`/`viewport`/
+`virtual` coordinate spaces with `contain`/`cover`/`stretch` fit, 2.5D depth (sign, sorting, parallax,
+perspective factor, and per-object depth fog), the fourteen primitives of Visual Primitive Set 0.1,
+common visual properties, the normative transform composition order, appearance with the eight-mode safe
+blend set and gradient paint, paths and splines with independently addressable points, text restricted to
+the three generic font families, and the once-at-instantiation resolution boundary for visual ValueSpec
+fields. Five diagnostic codes were added to the section 7 table.
+
+Phase 4 is delivered in eight slices, recorded in the implementation plan: three contract slices
+(sections 17, 18, 19), three implementation slices (renderer core, procedural systems, automation and
+effects), a challenge-and-exhibit slice, and the user-observed early combined GC6 benchmark. Each slice
+ends green and committable.
+
+Section 17 is contract only. No visual runtime code exists, the JSON Schema has no visual definitions,
+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).