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

<!-- OPENWC_CLAIM:M03-RND-TERRAIN-CACHE-SERVICE-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-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: