# M03-RND-TERRAIN-CHUNK-QUEUE-001 — Pure terrain chunk geometry queue planner

<!-- OPENWC_CLAIM:M03-RND-TERRAIN-CHUNK-QUEUE-001:sindo-main-codex:2026-07-19 -->

## Ownership

- Target: M03
- Program: RND
- Owner/Agent ID: sindo-main-codex
- Branch: `work/sindo-main-codex/m03-terrain-chunk-queue`
- Lease expires UTC: 2026-07-19
- Integrator: M03 milestone integrator

## Outcome

Extract chunk-geometry create/remove desired-operation calculation from the
streamer into a scene-free `TerrainChunkGeometryQueuePlanner`.

## Non-goals

- Move queue storage/drains, render budgets, tile-LOD queues or async tasks.
- Move chunk Mesh/Node/RID creation/removal or terrain state ownership.
- Change removal-first execution, nearest-first create order or LOD selection.
- Change coordinate conversions, radii, cache formats or quality profiles.
- Add dependencies or mark the broad terrain service checklist complete.

## Paths

- Exclusive: `src/render/terrain/terrain_chunk_geometry_queue_planner.gd`,
  `src/tools/verify_terrain_chunk_geometry_queue_planner.gd`,
  `docs/modules/terrain-chunk-geometry-queue-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 ADT resources, caches and
  proprietary renderer corpus

## Contracts and data

- Input: loader-owned tile-state read model plus immutable `GodotWorldPosition`
- Output: fresh create/remove request arrays; planner retains no queue state
- Removal: current chunks absent from desired state, or all current chunks while
  tile LOD is desired
- Creation: missing or LOD-mismatched chunks, sorted by origin XZ distance
- Queue/cache/schema/coordinate versions: unchanged

## Dependencies

- Requires: integrated terrain LOD planner master `b568768`
- Blocks: broader terrain service extraction and dependency/performance acceptance
- External state: none; tests use synthetic tile/chunk dictionaries

## Verification

- Commands: dedicated removal/create/mismatch/tile-fallback/sparse/order and
  bounded timing verifier; loader source boundary; facade/cache/LOD/internal-access/
  manifest/shutdown/scheduler/streaming planner and repository gates
- Fidelity evidence: extracted branch/order/distance rules and loader drain order
- Performance budget: bounded linear planning plus existing create sort; no engine
  resource, task, cache or persistent allocation framework

## Documentation deliverables

- Inline planner API documentation
- 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 name: `TerrainChunkGeometryQueuePlanner`
- Simplest solution: one stateless planner returning two fresh arrays
- Rejected complexity: generic operation graph, queue class, callback strategy,
  spatial index or ownership transfer
- Unavoidable complexity: raw dictionaries remain at the loader/ADT adapter boundary
- Measured optimization evidence: bounded synthetic multi-tile verifier

## Status

- State: accepted
- Done: pure planner, loader queue adoption, semantic/timing regressions and docs
- Next: asset-backed performance acceptance and further terrain-service extraction later in M03
- Blocked by:

<!-- OPENWC_HANDOFF:READY:M03-RND-TERRAIN-CHUNK-QUEUE-001:f800e11 -->
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-TERRAIN-CHUNK-QUEUE-001:24aef13 -->

## Handoff

- Commit: `f800e11` (`refactor(M03): extract terrain chunk queue planner`)
- Results: dedicated contract PASS (`cases=8`, `iterations=100`, `235.096 ms`);
  LOD/cache/facade/internal-access/manifest/shutdown/scheduler/streaming/focus/
  ground/terrain-query/coordinate regressions PASS; internal inventory remains
  `42`; editor parse has no script errors; documentation/coordination/diff gates
  PASS; checkpoint dry-run planned `7/7` entries with expected missing-private-
  corpus diagnostics
- Remaining risks: planner adds a second linear tile-state pass; asset-backed
  p95/p99 and visual acceptance remain pending; queue drains, terrain state and
  Mesh/Node/RID finalization remain loader-owned
- Documentation updated: `terrain-chunk-geometry-queue-planner.md`, module
  registry, `world-renderer.md`, `RENDER.md`, inline API documentation and
  data-flow/lifecycle/sequence diagrams
- Integration: accepted in master merge `24aef13`; post-merge planner,
  internal-access, facade and manifest gates passed