XZBT/reviews/.completed-artifacts/02-application-code-triage.md

XZBT 0.1 Application Code Triage — Visual Subsystem Readiness & Impact of §§17–19 Review

Context: Following the triage of multi-model visual specification reviews in reviews/01-triage.md (covering §§17–19 rev 0.7, 30 repair packages V1–V30, and additional defects A1–A3), this document conducts a comprehensive audit and triage of the current application codebase (src/runtime/*, schema/xzbt-0.1.schema.json, tools/*, and test/*).

Status of Codebase:

• Working tree baseline: commit 527220e (branch main).
• Test suite: 102 tests passing, zero failures (npm test).
• Implementation progress: Phase 1 (runtime skeleton), Phase 2 (common grammar), and Phase 3 (audio engine through 3c-4) are implemented and verified.
• Visual status: Sections 17–19 represent the completed visual contract (slices 4a, 4b, 4c). No visual renderer or procedural runtime code currently exists in src/runtime/. Slice 4d is the scheduled entry point for visual implementation.

---

Executive Scorecard & Code Inventory

Subsystem / Module	Path	Current Implementation Status	Visual Contract & Triage Readiness	Key Touchpoints / Gaps
Top-Level Constants	src/runtime/constants.js	Implements Phase 3b/3c constants	Stale version string; top-level fields present	XZBT_RUNTIME_VERSION is '0.1.0-phase3b'. Contains 'visual' in RNG_DOMAINS and 'visuals', 'components' in ALLOWED_TOP_LEVEL_FIELDS.
JSON Schema	schema/xzbt-0.1.schema.json	Validates GC2 and Audio (Phase 3c)	Severe schema drift / Out of date	visuals definition is a Phase 0 stub (camera, systems, passes). Lacks scene, layers, fields, effects, and automation (V1). components.visual is unconstrained { "type": "object" }.
Validator	src/runtime/validator.js	Validates Meta, Grammar, Audio	Permits arbitrary visuals; blocks visual bindings	Completely lacks validateVisualSubsystem(). Rejects all 4 visual binding target families as ERR_UNSUPPORTED_TARGET (V2). Lacks ValueSpec<color> support (V5). Missing visual authoring limits and diagnostics (V7, V25).
Resolution Engine	src/runtime/resolution.js	Shared GC3 + Audio resolution pipeline	No visual target exposure	target(path) only recognizes parameters.*, state.*, and audio.buses.*.gain. Rejects all visual target families, blocking bindings, automation, overrides, and modulation for camera, layers, systems, and effects (V2).
Actions Executor	src/runtime/actions.js	Implements set and override	Missing lifecycle actions	Throws ERR_UNSUPPORTED_TARGET on spawn and remove actions needed by spawned visual systems (§19.2, V7, V23, A1).
Automation	src/runtime/audio-automation.js	Implements audio graph tracks	Audio-coupled; lacks loops	Implements curves/modes and numeric stages, but enforces audio point bounds (256 vs 2048) and lacks loop modes (repeat, ping-pong) required by §19.1 and V12.
Performance Shell	src/runtime/performance.js	60 Hz fixed-step scheduler	Clock/Signals ready; lacks canvas	signals.pointer.* and signals.viewport.* are tracked and updated. No Canvas element lifecycle or rendering loop attachment.
Type Utilities	src/runtime/types.js	Numeric/String/Color types	Minimal color support; no geometry	color type is checked only as non-empty string. Lacks color math (fog blending V18), angle conversions, or matrix transforms (V3).
Diagnostics	src/runtime/diagnostics.js	General diagnostics ring buffer	Missing visual codes	Visual diagnostic codes from §§17–19 are not declared or mapped (V24, V27).
Visual Runtime	src/runtime/visual-*.js	Nonexistent	Pending Slice 4d	No renderer (visual-engine.js), procedural system (visual-procedural.js), or visual lifecycle modules exist yet.

---

Detailed Impact Analysis of 01-triage.md Findings on Application Code

1. Tier 1 — Contract & Architecture Blockers (Affecting Pre-Renderer and Core Modules)

V1. visuals.automation forbidden by owning table

• Application Code Impact:
  • schema/xzbt-0.1.schema.json: Currently has passes instead of effects, and completely omits automation. The schema must add an optional automation array under visuals.
  • src/runtime/validator.js: When visual subsystem validation is implemented, ALLOWED_VISUAL_FIELDS must permit automation alongside scene, layers, systems, fields, camera, and effects.
  • Scope separation: Code must distinguish exhibit-scope automation (visuals.automation, clock zero at performance activation) from system-scope automation (visuals.systems.<id>.automation, clock zero at system instantiation/spawn).

V2. Acceptance trace 17.16.14 contradicts closed visual capability table

• Application Code Impact:
  • src/runtime/validator.js (validateBindings, line 233): Currently restricts binding targets to:

    /^(parameters|state)\.[a-z][a-z0-9_-]*$/.test(binding.target) || /^audio\.buses\.[a-z][a-z0-9_-]*\.gain$/.test(binding.target)
    

    Must be extended to recognize exactly the four visual target families from Format Specification Table 8.1:
    1. visuals.camera.<property> (x, y, zoom, rotation, focalLength)
    2. visuals.layers.<layer-id>.opacity
    3. visuals.systems.<system-id>.visible
    4. visuals.effects[<index>].<param> All other visual properties (such as per-object properties) must continue to emit ERR_UNSUPPORTED_TARGET.
  • src/runtime/resolution.js (target(path), lines 182–192): Currently returns null for any visual target. It must be updated to return specification records for camera, layer opacity, system visibility, and post-effect parameters, enabling bindings and overrides to resolve against them.

V3. Fit, camera, and perspective composition in named spaces

• Application Code Impact:
  • Planned src/runtime/visual-engine.js:
    • Must implement the unified scene-to-CSS fit matrix F (handling contain, cover, and stretch with offsets).
    • Camera translation must be evaluated in CSS display coordinates: q = F(cameraCenter), translation q - c.
    • Perspective scaling factor focalLength / (focalLength + zEffective) centered at display center c.
    • DPR (device pixel ratio) scaling applied once to the backing store transform.
  • src/runtime/types.js or a new math utility module:
    • Needs matrix multiplication / 2D affine transform helpers supporting non-uniform scale, translation, and rotation.

V4. Primitive geometry definitions & path generation

• Application Code Impact:
  • Planned src/runtime/visual-engine.js:
    • Explicit local extents and anchors for all 14 primitives (Visual Primitive Set 0.1).
    • Sweep calculation for arcs (direction, zero sweep, full turn >= 360).
    • Catmull–Rom spline evaluation and closed spline index wrapping.
    • Bezier spline explicit closing segment.
    • Point stroke rendering and open-path fill closure rules.

V5. Paint ValueSpecs contradict component example

• Application Code Impact:
  • src/runtime/validator.js (validateValueSpec, line 157):
    • Must recognize that fill and stroke accept ValueSpec<color> (e.g. { "ref": "inputs.tint" }), as well as paint objects and null.
    • Must validate that references inside components resolve to declared component inputs.
  • src/runtime/values.js (ValueResolver):
    • Must resolve color references and weighted choices of color literals without coercing to numbers.

V6. System controls vs item initialization resolution boundaries

• Application Code Impact:
  • Planned src/runtime/visual-procedural.js:
    • Emitter count and rate must resolve before allocating particle arrays.
    • ValueSpecs resolved at system instantiation boundary vs per-particle birth draws must draw from separate or strictly ordered PRNG streams.
    • Live automation channels must affect existing vs new particles according to the field ownership table.

V7. Live automation totals vs import authoring bounds

• Application Code Impact:
  • src/runtime/validator.js:
    • Check authored static limits (e.g. template track/point counts).
  • src/runtime/actions.js & visual lifecycle manager:
    • Runtime check: when executing a spawn action, check whether adding that instance's tracks/points would exceed the live budget (128 tracks, 2048 points).
    • If budget would be exceeded, execute atomic spawn refusal (do not partially allocate; raise WARN_VISUAL_CEILING).

V8. Coherent noise reproducible algorithm

• Application Code Impact:
  • src/runtime/rng.js or visual-procedural.js:
    • Current SeededRNG only provides nextFloat() and nextInt().
    • Must implement a fully deterministic, portable gradient noise algorithm (fixed hash lattice, permutation table, octaves normalization, and curl math) that produces bit-exact vectors across browsers.

V9. Sorting units for emitters, repeaters, and mixed-depth geometry

• Application Code Impact:
  • Planned src/runtime/visual-engine.js:
    • Procedural systems (particles, repeaters, emitters) must sort as atomic units using a documented representative depth (e.g. lowest live particle depth), with internal ordinal stability.

V10. Offscreen allocation and compositing

• Application Code Impact:
  • Planned src/runtime/visual-engine.js:
    • Maintain a pool of up to 16 offscreen canvas buffers.
    • Layer opacity and blend modes count against this pool.
    • Implement deterministic shedding (farthest objects first) when buffers are exhausted, emitting WARN_VISUAL_CEILING.
    • Separate instance release multiplier (initialized to 1) applied during release to avoid resetting authored opacity.

---

2. Tier 2 — Slice-Specific Implementation Requirements

V11. Repeater automation nonexistent step

• Application Code Impact:
  • src/runtime/validator.js and visual automation: Ensure step is rejected as an unsupported automation target on repeaters.

V12. Infinite loop legality on visual automation

• Application Code Impact:
  • Automation module (src/runtime/audio-automation.js or visual equivalent):
    • Implement repeat and ping-pong loop evaluation.
    • Reconcile loop legality across exhibit scope, persistent systems, and finite/indefinite spawned systems.

V13. Placement distributions & PRNG draw consumption

• Application Code Impact:
  • Planned src/runtime/visual-procedural.js:
    • Deterministic random sampling for all 9 placement distributions.
    • Fixed draw order (angle before radius; explicit draws for depth and jitter).
    • Grid distribution handling when item count does not match rows × columns.

V14. Behavior schemas & channel composition

• Application Code Impact:
  • Planned src/runtime/visual-procedural.js:
    • Implement all 17 behaviors writing to scalar channels (x, y, vx, vy, speed, angle, etc.).
    • Strict conflict detection: scalar channels cannot be simultaneously driven by conflicting behaviors.

V15. Morph geometry & target sampling

• Application Code Impact:
  • visual-engine.js / visual-procedural.js:
    • Restrict morph to point-list primitives with equal point counts. Reject unsupported geometry with ERR_UNSUPPORTED_TARGET.

V16. Distribution path references

• Application Code Impact:
  • validator.js: Distribution paths must use inline commands; reject sibling-path references that lack an object container.

V17. Viewport default fit & explicit-layer omission

• Application Code Impact:
  • validator.js: In viewport space, an absent fit is valid; only explicit non-stretch is rejected.
  • If layers map is present, system omission of layer must raise a named diagnostic rather than silently choosing a layer.

V18. Fog color math & conic fallback

• Application Code Impact:
  • visual-engine.js: Fog interpolation in sRGB/RGBA space; clamp conic gradient fallbacks when the focal point is external or degenerate.

V19. Post-effect radius conversion

• Application Code Impact:
  • visual-effects.js: Convert scene-unit blur/bloom radii to device pixels using display fit and DPR. Map filter names (saturation, hueRotate) to Canvas filter equivalents.

V20. Open camera clamp range minimum

• Application Code Impact:
  • src/runtime/resolution.js: Camera focalLength target must define a positive minimum clamp (e.g. min: 0.001 or min: 1) to prevent division by zero in perspective projection.

V21. Links style/fade defaults & capacity

• Application Code Impact:
  • visual-procedural.js: Distance links must enforce capacity <= 256, resolve missing maxDistance when fadeWithDistance is true, and implement nearest-neighbor tie-breaking.

V22. Component-input locations

• Application Code Impact:
  • validator.js: Enforce single canonical component-instance input location (emit.inputs vs system inputs).

V23. Ownership & release edge semantics

• Application Code Impact:
  • src/runtime/actions.js: Support spawn and remove. Handle cancelWithScenario, idempotent duplicate removals, and release factor transitions.

V24. Resource diagnostics cadence & identity

• Application Code Impact:
  • src/runtime/diagnostics.js: Implement throttling / deduplication for WARN_VISUAL_CEILING and approximation warnings (e.g. once per second or sustained 120-tick reporting).

V25. Centralized ceilings completeness

• Application Code Impact:
  • validator.js: Enforce static draw load ceilings: path commands (512), burst entries (16), grid dimensions (256), custom partials (64).

---

3. Additional Defects (A1–A3)

A1. Lifecycle fields collide with particle/emitter/repeater fields

• Application Code Impact:
  • In schema/xzbt-0.1.schema.json and src/runtime/validator.js: System-level lifetime (for spawned system duration) collides with item-level lifetime (for particle lifespan). The codebase must enforce the separated container/field naming (e.g. system lifecycle in a dedicated block or renamed property) before writing procedural validation.

A2. Missing extension fields

• Application Code Impact:
  • Add direction to procedural noise field definitions.
  • Clarify or reject trail on particle render objects.

A3. Backing-store limit (4096) & pinned parallax

• Application Code Impact:
  • visual-engine.js: When CSS display size × DPR exceeds 4096×4096, downsample the DPR multiplier rather than failing or exceeding the canvas maximum.
  • Parallax 0 pins against camera translation only; zoom and rotation still apply.

---

Action Plan & Implementation Sequencing for Application Code

The application code changes required by the visual specification and triage findings should be delivered in five coordinated stages aligned with the existing project milestones:

┌─────────────────────────────────────────────────────────────┐
│ Stage 0: Shared Pre-Renderer Alignment (Pre-4d)             │
│ • Reconcile schema/xzbt-0.1.schema.json (§§17-19, V1, A1)   │
│ • Update validator.js: expose 4 visual target families (V2)  │
│ • Update resolution.js: target() returns visual specs (V2)   │
│ • Update constants.js: version string to phase4             │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ Stage 1: Renderer Core (Slice 4d)                           │
│ • Canvas 2D backend, Scene fit & Camera transform (V3, A3)  │
│ • 14 Primitives path generator & appearance (V4, V5)        │
│ • 16-buffer offscreen pool & compositing (V10)              │
│ • Depth sorting & fog blending (V9, V18)                    │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ Stage 2: Procedural Systems (Slice 4e)                      │
│ • Component instantiation & inputs resolution (V5, V22, A1) │
│ • Particle Euler integrator & emission math (V6, V29)       │
│ • 9 Placement distributions & draw orders (V13)             │
│ • 17 Behaviors & scalar channels (V14)                      │
│ • Coherent noise algorithm (V8)                             │
│ • Distance links & trails (V21)                             │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ Stage 3: Automation, Lifecycle & Effects (Slice 4f)         │
│ • Shared automation with repeat/ping-pong loops (V1, V12)   │
│ • System lifecycle actions (spawn/remove) in actions.js(V23)│
│ • Atomic admission & live ceiling checks (V7, V24, V25)     │
│ • Post-processing filter chain & device conversion (V19)    │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ Stage 4: Verification & Acceptance (Slices 4g & 4h)         │
│ • PRD 130 challenge fixtures and Exhibit visuals            │
│ • Hardware benchmark and resource audit                     │
└─────────────────────────────────────────────────────────────┘

---

Immediate Next Steps & Safety Invariant

1. Safety Invariant: All existing 102 tests in npm test must continue to pass without regression. Audio and common grammar semantics remain locked.
2. Contract Synchronization: Before implementing the Canvas 2D renderer in Slice 4d, Stage 0 must synchronize the shared validator, JSON schema, and target resolver to prevent drift between Format Specification Rev 0.7 and the runtime foundation.
3. Evidence Record: Maintain this triage alongside reviews/01-triage.md and reviews/04-fix-log.md to track code closure as Phase 4 slices proceed.