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

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

<!-- OPENWC_CLAIM:M01-RND-STREAMING-FOCUS-001:sindo-main-codex:2026-07-15 -->
<!-- OPENWC_INTEGRATION:ACCEPTED:M01-RND-STREAMING-FOCUS-001:c8e99f2 -->

## 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