open-wc/coordination/claims/M03-RND-STREAMING-PLANNER-001.md

# M03-RND-STREAMING-PLANNER-001 — Pure streaming target planner

<!-- OPENWC_CLAIM:M03-RND-STREAMING-PLANNER-001:sindo-main-codex:2026-07-17 -->

## Ownership

- Target: M03
- Program: RND
- Owner/Agent ID: sindo-main-codex
- Branch: `work/sindo-main-codex/m03-streaming-target-planner`
- Lease expires UTC: 2026-07-17
- Integrator: M03 milestone integrator

## Outcome

Extract runtime/editor ADT wanted/retained-set calculation and boundary prefetch
selection from `StreamingWorldLoader` into a scene-free, deterministic
`StreamingTargetPlanner` with typed focus input and asset-free contract tests.

## Non-goals

- Change load/retain radii, boundary thresholds, queue priority or LOD policy.
- Move queue mutation, async jobs, cache ownership or GPU finalization.
- Extract `RenderBudgetScheduler` or asset services in this package.
- Change cache formats, renderer profiles or target milestone status.

## Paths

- Exclusive: `src/render/streaming/streaming_target_planner.gd`,
  `src/render/streaming/streaming_target_policy.gd`,
  `src/render/streaming/streaming_target_plan.gd`,
  `src/tools/verify_streaming_target_planner.gd`,
  `docs/modules/streaming-target-planner.md`, this claim
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`,
  `src/tools/verify_coordinate_conversion_boundaries.gd`,
  `docs/modules/world-renderer.md`, `docs/modules/coordinate-mapping.md`,
  `docs/modules/README.md`, `RENDER.md`
- Generated/ignored: `.godot`, native DLL, generated cache resources and
  proprietary renderer corpus

## Contracts and data

- Input: immutable `GodotWorldPosition`, available-tile key set and immutable
  `StreamingTargetPolicy`
- Output: immutable `StreamingTargetPlan` with focus tile plus detached
  wanted/retained tile-key sets
- Tile-key representation remains the streamer's existing `<x>_<y>` internal key
- Schema/cache/coordinate versions: unchanged
- Consumers: `StreamingWorldLoader` runtime/editor refresh paths

## Dependencies

- Requires: M01 typed coordinates/focus and integrated facade package `a100ced`
- Blocks: budget scheduler extraction and planner performance regression gate
- External state: none; tests use synthetic tile catalogs

## Verification

- Commands: dedicated planner verifier, facade/focus/coordinate regressions,
  renderer manifest/dry-run and repository gates
- Fixtures: center, edge, corner, unavailable-tile, clamped-radius and editor cases
- Fidelity evidence: expected tile sets are captured from current formulas; full
  renderer dry-run retains all seven checkpoint plans
- Performance budget: planner work remains bounded by square radii and creates no
  Node, Resource, task, cache or RID

## Documentation deliverables

- Inline API docs for planner/policy/plan
- New module specification with input/output table and data-flow diagram
- Updated world-renderer data-flow/sequence/ownership/source map
- Updated module registry and renderer notes

## Simplicity and naming

- Important names: `StreamingTargetPlanner`, `StreamingTargetPolicy`,
  `StreamingTargetPlan`
- Simplest approach: one pure calculator plus two immutable value objects
- Rejected complexity: generic graph planner, priority framework, service
  container, job ownership or duplicate available-tile catalog
- Unavoidable complexity: boundary-prefetch cross product must preserve corner
  behavior and existing string tile keys
- Measured optimization evidence: no new optimization; exact extraction

## Status

- State: ready-for-review
- Done: extracted immutable policy/plan and pure planner, migrated runtime/editor
  target refresh, added behavior/dependency/performance coverage and module docs
- Next: integrated in master; next M03 package extracts the budget scheduler
- Blocked by:

<!-- OPENWC_HANDOFF:READY:M03-RND-STREAMING-PLANNER-001:ad8fc41 -->
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-STREAMING-PLANNER-001:643850c -->

## Handoff

- Commit: `e887c3b`; cold-start fix `ad8fc41`
- Integration: accepted in master merges `d0f74f8` and `643850c`
- Results: runtime/editor wanted and retained ADT sets plus boundary-prefetch
  centers are calculated by scene-free `StreamingTargetPlanner`; streamer keeps
  queue ordering, LOD/detail state, jobs, caches, nodes and RIDs.
- Verification: planner `cases=5 iterations=250 average_ms=1.765`; facade
  `delegation=3 runtime_scenes=2 tools=3`; focus `contract=1 runtime_scenes=2
  capture_tools=3`; coordinate boundary `files=109 consumers=6`; renderer
  manifest `checkpoints=7 coverage=7 caches=7`; shutdown ownership passed;
  documentation, coordination and diff gates passed.
- Fidelity: center/corner/catalog/clamp/editor fixtures preserve the extracted
  formulas; seven-checkpoint dry-run retained all plans. No radius, threshold,
  load priority, cache version, placement, material, animation or visibility
  rule changed. No build-12340 parity claim is added.
- External/local inputs: ignored native DLL and generated ADT resource scripts
  were copied from master for worktree smoke only. Proprietary ADT and character
  assets were unavailable, so the dry-run emitted expected degraded-data diagnostics.
- Remaining risks: exact p95/p99 impact still needs an asset-backed baseline;
  pathological custom radii are not benchmarked; tile-key strings remain the
  existing internal catalog representation; queue/LOD application remains monolithic.
- Documentation updated: new planner module spec with API/input/output/data-flow/
  sequence/ownership/recovery/performance/source-map sections; world renderer,
  coordinate mapping, module registry and renderer implementation notes updated.