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: ready-for-review
• Done: scene-free cache ownership/LRU extraction, loader adapter migration, contract regression and module documentation
• Next: M03 integrator reviews and merges 97480e0
• Blocked by:

Handoff

• Commit: 97480e0
• Results: TerrainQualityMeshCache now owns retained full-quality Mesh references, source admission and oldest-to-newest LRU. The loader retains only restore-to-state, store-after-upgrade and clear lifecycle adapters.
• Verification: cache contract_cases=15 loader_calls=3; facade/entity/ground/ terrain regressions; internal access private_symbols=42 gameplay=7 editor_sources=9 renderer_tools=1; manifest 7/7; shutdown; scheduler 20000 iterations; planner 250 iterations; focus; editor parse; dry-run; coordination, documentation and diff gates passed.
• Fidelity: baked_full revisit retention, three excluded splat sources, LRU touch/trim, profile capacities and all call sites remain unchanged. All seven checkpoint plans remain valid. No visible or build-12340 parity claim is added.
• External/local inputs: ignored native DLL and generated ADT scripts supported parse/dry-run only; missing proprietary ADT/DBC/character data produced expected diagnostics.
• Remaining risks: entry count does not measure Mesh bytes; ordered-array touch remains linear; asset-backed revisit flash, memory and p95/p99 evidence remain pending; terrain build/tasks/state/finalization are still monolithic.
• Documentation updated: new terrain cache API/input-output/data-flow/lifecycle/ sequence/ownership/failure/configuration/migration/diagnostic/source-map spec; world renderer, registry and RENDER.md updated.
• Integration: accepted in master merge 630a0c1; post-merge cache, facade, internal-access, manifest, shutdown, scheduler and planner gates passed.