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

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

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:

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.