# M03-RND-M2-MESH-RESOURCE-CACHE-001 — M2 mesh resource cache state

<!-- OPENWC_CLAIM:M03-RND-M2-MESH-RESOURCE-CACHE-001:sindo-main-codex:2026-07-20 -->

## Ownership

- Target: M03
- Program: RND
- Owner/Agent ID: sindo-main-codex
- Branch: `work/sindo-main-codex/m03-m2-mesh-resource-cache`
- Lease expires UTC: 2026-07-20
- Integrator: M03 milestone integrator

## Outcome

Extract the normalized-path to static M2 Mesh resource cache from
`StreamingWorldLoader`, preserving lookup, replacement, shutdown lifetime and
all existing cache consumers.

## Non-goals

- Own the shared M2 missing-path cache or animated/prototype node caches.
- Call ResourceLoader, extract Meshes from Resources or select cache paths.
- Prepare, rebuild or materialize M2 Meshes.
- Change cache formats, material refresh, animation or visible behavior.

## Paths

- Exclusive: `src/render/m2/m2_mesh_resource_cache_state.gd`,
  `src/tools/verify_m2_mesh_resource_cache_state.gd`,
  `docs/modules/m2-mesh-resource-cache-state.md`, this claim
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`,
  `src/tools/verify_m2_mesh_load_pipeline_state.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 M2 resources, caches and
  proprietary renderer corpus

## Contracts and data

- Non-empty normalized M2 paths map to at most one Mesh resource reference.
- Store replaces the previous reference for the same path.
- Lookup returns the exact retained Mesh reference; unknown/empty paths return null.
- Clear releases all cache references only at the existing final-shutdown site.
- Shared missing/prototype/animated caches remain loader-owned and unchanged.

## Dependencies

- Requires: accepted mesh load pipeline package on master `ef782d1`
- Blocks: isolated M2 Mesh resource finalizer extraction
- External state: none; verification uses synthetic Mesh resources

## Verification

- Commands: dedicated validation/store/replace/lookup/clear/source/timing
  verifier; mesh pipeline/classifier/material/shutdown/M2 build/facade/internal-
  access/manifest, documentation and coordination gates
- Fixtures: synthetic ArrayMesh resources and normalized paths
- Fidelity evidence: exact cache call-site and shutdown lifetime preservation
- Performance budget: 100 cycles over 256 store/lookup entries under 1 second

## Documentation deliverables

- Inline public API docs
- Module specification with inputs/outputs, ownership and source map
- Data-flow, lifecycle/state and dependency diagrams
- World-renderer, module registry and RENDER status updates

## Simplicity and naming

- Important name introduced: `M2MeshResourceCacheState`
- Simplest solution: one RefCounted with one typed-purpose Dictionary
- Rejected complexity: generic resource cache, missing-state merger, eviction,
  signals, callbacks or materialization ownership
- Unavoidable complexity: none beyond retaining engine Resource references
- Measured optimization evidence: bounded synthetic store/lookup loop

## Status

- State: accepted
- Done: cache state, loader/test adapters, contract verifier and required documentation
- Next: isolated M2 Mesh resource finalizer extraction
- Blocked by:

## Handoff

- Commit: `e990a65`
- Results: dedicated cache verifier passes 100-by-256 store/lookups in
  38.974 ms; 35 headless renderer/coordinate regressions pass; checkpoint
  dry-run passes 7/7; documentation and coordination gates pass.
- Remaining risks: no private M2 traversal, Mesh memory/leak/descriptor-pressure
  run or original-client visual comparison; extraction/preparation, shared
  missing state and materialization remain loader-owned by design.
- Documentation updated: inline API; `m2-mesh-resource-cache-state.md` with
  data-flow, lifecycle, sequence and dependency diagrams; pipeline spec, module
  registry, `world-renderer.md` and `RENDER.md`.

<!-- OPENWC_HANDOFF:READY:M03-RND-M2-MESH-RESOURCE-CACHE-001:e990a65 -->

## Integration

- Merge commit: `3094561`
- Post-merge results: cache state `cases=9 iterations=100
  elapsed_ms=38.686`; pipeline, classifier, materials, shutdown, facade,
  internal-access `34`, manifest `7/7`, documentation and coordination gates passed.

<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-M2-MESH-RESOURCE-CACHE-001:3094561 -->