open-wc/coordination/claims/M03-RND-TERRAIN-CACHE-SERVICE-001.md

M03-RND-TERRAIN-CACHE-SERVICE-001 — Terrain quality mesh cache service

Ownership

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

Outcome

Extract the full-quality terrain revisit Mesh cache, its LRU ownership and source-admission rules from StreamingWorldLoader into a small scene-free TerrainQualityMeshCache, preserving all call sites and observable behavior.

Non-goals

• Move ADT parsing, tile state, quality-upgrade tasks/results or SceneTree/RID finalization.
• Change cache capacity defaults, quality profiles, source priority or cache formats.
• Cache control-splat/splat meshes that the current loader deliberately rejects.
• Extract chunk LOD, terrain material building, ground query or other asset services.
• Add dependencies, persistence, background work or mark the terrain service complete.

Paths

• Exclusive: src/render/terrain/terrain_quality_mesh_cache.gd, src/tools/verify_terrain_quality_mesh_cache.gd, docs/modules/terrain-quality-mesh-cache.md, this claim
• Shared/hotspots: src/scenes/streaming/streaming_world_loader.gd, src/tools/verify_render_runtime_cache_shutdown.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

• Public service API: store, restore, clear, detached diagnostic_snapshot
• Entry: tile key, retained Mesh reference and source string
• Admission: non-empty key, non-null Mesh, source other than control_splat_cache, splat_cache or splat
• LRU: successful restore touches newest; store touches then trims oldest to max(0, capacity); invalid restored records are removed
• Persistence/cache format: none; session-memory ownership only

Dependencies

• Requires: integrated facade contracts master 61bad09
• Blocks: later terrain service extraction and cache/finalization acceptance audit
• External state: none; tests use synthetic ArrayMesh references

Verification

• Commands: dedicated cache contract/LRU/ownership regression; streamer source boundary; shutdown/facade/internal-access/manifest/planner/scheduler and repository gates
• Fixtures: admission/rejection, replacement, LRU touch/eviction, zero/negative capacity, invalid record cleanup, clear and detached diagnostics
• Fidelity evidence: same sources/capacity/call sites; all seven baseline plans unchanged
• Performance budget: dictionary lookup plus bounded single-entry LRU operations; no Node, task, file, cache serialization or RID creation

Documentation deliverables

• Inline public API docs: store/restore/clear/diagnostics and ownership
• Module specification: new terrain quality mesh cache specification
• Data-flow diagram: upgrade result through cache to revisit state
• Sequence/state/dependency diagrams: store/restore/evict/reset and failure paths
• Source map/status updates: module registry, world renderer and RENDER.md

Simplicity and naming

• Important names introduced: TerrainQualityMeshCache
• Simplest considered solution: one RefCounted with dictionary plus ordered tile-key array
• Rejected complexity/abstractions: generic cache framework, weak references, callbacks, Resource cache integration, background eviction or persistence
• Unavoidable complexity and justification: Mesh references must survive unloaded tile state while LRU keeps revisit memory bounded
• Measured optimization evidence: exact ownership extraction, no optimization claim

Status

• State: claimed
• Done: ownership, behavior and non-goals published
• Next: implement service, migrate loader wrappers, tests and docs
• Blocked by:

Handoff

• Commit:
• Results:
• Remaining risks:
• Documentation updated: