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

M03-RND-TERRAIN-LOD-PLANNER-001 — Pure terrain chunk LOD planner

Ownership

• Target: M03
• Program: RND
• Owner/Agent ID: sindo-main-codex
• Branch: work/sindo-main-codex/m03-terrain-chunk-lod-planner
• Lease expires UTC: 2026-07-18
• Integrator: M03 milestone integrator

Outcome

Extract chunk-level terrain LOD desired-state calculation from the streamer into a scene-free TerrainChunkLodPlanner with immutable policy and typed focus input.

Non-goals

• Move chunk/tile queues, loaded state, Mesh/Node/RID creation or budget drains.
• Change radii, chunk size, threshold inclusivity, priority sorting or tile LOD policy.
• Normalize/reorder custom radii or reinterpret negative values.
• Move ADT parsing, quality cache/tasks, materials or ground query.
• Add dependencies, persistence, workers or mark terrain extraction complete.

Paths

• Exclusive: src/render/terrain/terrain_chunk_lod_policy.gd, src/render/terrain/terrain_chunk_lod_planner.gd, src/tools/verify_terrain_chunk_lod_planner.gd, docs/modules/terrain-chunk-lod-planner.md, this claim
• Shared/hotspots: src/scenes/streaming/streaming_world_loader.gd, docs/modules/world-renderer.md, docs/modules/README.md, RENDER.md, targets/03-renderer-facade.md
• Generated/ignored: .godot, native DLL, generated resources, caches and proprietary renderer corpus

Contracts and data

• Input: ADT chunk adapter records, immutable GodotWorldPosition, immutable enabled/radii/chunk-size policy
• Output: detached Dictionary mapping source chunk index to LOD 0, 1 or 2
• Formula: horizontal distance to origin + half chunk; inclusive squared thresholds
• Disabled policy and empty/sparse chunks return absent entries exactly as before
• Queue/cache/schema/coordinate versions: unchanged

Dependencies

• Requires: integrated terrain cache slice master ea08b8e
• Blocks: broader terrain service extraction and dependency/performance acceptance
• External state: none; tests use synthetic chunk adapter records

Verification

• Commands: dedicated center/boundary/outside/sparse/disabled/custom-radius and bounded timing verifier; loader source boundary; facade/cache/internal-access/ manifest/shutdown/scheduler/streaming planner and repository gates
• Fidelity evidence: extracted formulas and all seven baseline plans remain unchanged
• Performance budget: bounded linear scan over at most the ADT chunk record count; no Node, Resource, RID, task, cache entry or allocation framework

Documentation deliverables

• Inline API docs for policy/planner
• New module spec with inputs/outputs, data-flow, lifecycle, sequence, ownership, failure, performance and source map
• World renderer/module registry/RENDER.md updates

Simplicity and naming

• Important names: TerrainChunkLodPolicy, TerrainChunkLodPlanner
• Simplest solution: immutable scalar policy plus one pure linear planner
• Rejected complexity: generic spatial index, quadtree, callback strategy, normalized profile model or queue ownership
• Unavoidable complexity: raw chunk dictionaries remain at the ADT adapter boundary
• Measured optimization evidence: verifier records bounded High-like planning time

Status

• State: handoff
• Done: immutable policy, pure planner, both loader call sites, regressions and docs
• Next: milestone integrator merge and asset-backed performance acceptance later in M03
• Blocked by:

Handoff

• Commit: eb94cfc (refactor(M03): extract terrain chunk LOD planner)
• Results: dedicated contract PASS (cases=7, iterations=250, 12.726 ms); cache/facade/internal-access/manifest/shutdown/scheduler/streaming-focus/ streaming-planner/ground/terrain-query/coordinate regressions PASS; editor parse has no script errors; documentation and coordination gates PASS; checkpoint dry-run planned 7/7 entries with expected missing-private-corpus diagnostics
• Remaining risks: asset-backed p95/p99 and visual acceptance remain pending; terrain state, queue, quality-upgrade and finalization ownership remains in loader
• Documentation updated: terrain-chunk-lod-planner.md, module registry, world-renderer.md, RENDER.md, inline public API documentation and data-flow, lifecycle and sequence diagrams