# 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: 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:

<!-- OPENWC_HANDOFF:READY:M03-RND-TERRAIN-CACHE-SERVICE-001:97480e0 -->

## 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.