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

<!-- OPENWC_CLAIM:M03-RND-TERRAIN-LOD-PLANNER-001:sindo-main-codex:2026-07-18 -->

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