open-wc/coordination/claims/M01-RND-STREAMING-FOCUS-001.md

M01-RND-STREAMING-FOCUS-001 — Explicit streaming focus contract

Ownership

• Target: M01
• Program: RND/FND
• Owner/Agent ID: sindo-main-codex
• Branch: work/sindo-main-codex/m01-streaming-focus
• Lease expires UTC: 2026-07-15
• Integrator: M01 milestone integrator

Outcome

Introduce a scene-free StreamingFocus value and make runtime/test streaming consume it through an explicit source or public setter instead of discovering the active Camera3D from a viewport.

Non-goals

• Extracting WorldRenderFacade or StreamingTargetPlanner from the monolithic loader.
• Adding direction, velocity, frustum or multi-focus planning.
• Decomposing the player controller before M02.
• Changing terrain, M2, WMO, liquid, cache or LOD formulas.

Paths

• Exclusive: src/domain/streaming/, src/tools/verify_streaming_focus.gd
• Shared/hotspots: src/scenes/streaming/streaming_world_loader.gd, src/scenes/streaming/eastern_kingdoms_streaming.tscn, src/scenes/streaming/kalimdor_streaming.tscn, renderer diagnostic tools, docs/modules/world-renderer.md, this claim
• Generated/ignored: local extracted assets, renderer caches and Godot import metadata

Contracts and data

• Public API: immutable StreamingFocus; loader set_streaming_focus and refresh_streaming_focus
• Source adapter: explicit streaming_focus_source_path may reference any Node3D
• Migration: runtime scenes use player focus; capture/probe tools explicitly use their dedicated camera as the source
• Compatibility: streaming radii/LOD/cache behavior and coordinate contract v2 unchanged

Dependencies

• Requires: coordinate contract version 2 and golden fixtures at 52e1b2b
• Blocks: M01 renderer/test focus exit criterion and later renderer facade extraction
• External state: no new dependency or proprietary input

Verification

• Commands: streaming focus contract/integration verifier, renderer baseline manifest/calibration, headless scene smoke, coordination/documentation gates
• Fixtures: Node3D player-style source and explicit capture-style setter
• Fidelity evidence: existing seven renderer checkpoints and build-12340 coordinate calibration must remain unchanged
• Performance budget: one scalar focus snapshot per configured streaming interval; no new per-tile or per-chunk work

Documentation deliverables

• Inline public API docs: focus value and loader public methods
• Module specification: inputs/outputs, ownership, lifecycle, failure/recovery and source map
• Data-flow diagram: player/editor/capture source to focus contract to loader
• State/sequence diagram: focus sampling and refresh threshold sequence

Simplicity and naming

• Important names introduced: StreamingFocus, streaming_focus_source_path, set_streaming_focus, refresh_streaming_focus
• Simplest considered solution: one immutable value plus one explicit scene adapter path
• Rejected complexity/abstractions: provider interface hierarchy, service locator, multi-focus registry and predictive motion fields
• Unavoidable complexity and justification: editor viewport remains a separate adapter because its camera is owned by EditorInterface
• Measured optimization evidence: not applicable

Status

• State: ready-for-review
• Done: contract, runtime/editor/capture migration, headless regression, module diagrams, renderer documentation and cold/warm GUI capture
• Next: integrator review and merge before typed identity work
• Blocked by:

Handoff

• Commit: 7815385
• Branch: work/sindo-main-codex/m01-streaming-focus
• Outcome: runtime streaming consumes immutable StreamingFocus; Eastern Kingdoms and Kalimdor scenes explicitly follow the player, while capture and terrain/occluder probes explicitly follow their dedicated camera
• Contract/API: new scene-free StreamingFocus(GodotWorldPosition) plus loader set_streaming_focus, refresh_streaming_focus and streaming_focus_source_path; camera_path remains only for optional overview positioning
• Verification: StreamingFocus PASS (1 contract, 2 runtime scenes, 3 capture tools); coordinate golden fixtures and CoordinateMapper PASS; M00 calibration PASS with maximum error 0.000015; manifest PASS (7 checkpoints); runtime-cache shutdown PASS; headless runtime scene exit 0; coordination, documentation, dependency and whitespace checks passed
• Renderer checkpoint: standard 8-second GUI capture completed 14 images (7 cold + 7 warm) and wrote schema-1 report.json; focus tiles changed through the public contract; no Node/resource/RID leak diagnostic appeared
• Fidelity: checkpoint camera positions, coordinate contract v2, streaming radii, LOD formulas, cache formats and quality profiles are unchanged; this is regression evidence, not a new 1:1 parity claim
• Rebuild: none; GUI verification used local ignored extracted assets/cache junctions. Missing worktree .godot/imported copies for several incidental M2 GLBs produced existing cache-load fallback diagnostics only
• Remaining risks: the monolithic loader still owns planning/jobs/presentation; direction, velocity, frustum and multiple foci remain M03 planner work. The known timing-dependent zero-reference ObjectDB shutdown warning occurred, without Node/resource/RID leak diagnostics
• Recommended merge order: after coordinate fixtures at 52e1b2b, before typed identity and renderer-facade extraction
• Documentation: world-renderer.md inputs/outputs, public API, lifecycle, data-flow and sequence diagrams, ownership, recovery, verification, capability matrix, risks and source map updated; RENDER.md updated