diff --git a/coordination/claims/M03-RND-TERRAIN-CHUNK-QUEUE-001.md b/coordination/claims/M03-RND-TERRAIN-CHUNK-QUEUE-001.md new file mode 100644 index 0000000..5839c2d --- /dev/null +++ b/coordination/claims/M03-RND-TERRAIN-CHUNK-QUEUE-001.md @@ -0,0 +1,90 @@ +# M03-RND-TERRAIN-CHUNK-QUEUE-001 — Pure terrain chunk geometry queue planner + + + +## 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: claimed +- Done: scope, ordering and ownership published +- Next: implement planner, migrate chunk queue calculation, tests and docs +- Blocked by: + +## Handoff + +- Commit: +- Results: +- Remaining risks: +- Documentation updated: