# M03-RND-M2-PROTOTYPE-CACHE-001 — M2 prototype cache state

<!-- OPENWC_CLAIM:M03-RND-M2-PROTOTYPE-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-prototype-cache`
- Lease expires UTC: 2026-07-20
- Integrator: M03 milestone integrator

## Outcome

Extract static/animated detached M2 prototype references plus missing-model and
static-animation negative outcomes from `StreamingWorldLoader` into one explicit
shutdown-lifetime cache-state service.

## Non-goals

- Choose `.tscn/.glb` paths, call ResourceLoader/native loaders or build Nodes.
- Own animation/Mesh request queues, Mesh resources, materials or MultiMeshes.
- Change candidate/allowlist/denylist rules, fallback order or visible behavior.
- Add persistence, eviction, async work, dependencies or cache-format changes.

## Paths

- Exclusive: `src/render/m2/m2_prototype_cache_state.gd`,
  `src/tools/verify_m2_prototype_cache_state.gd`,
  `docs/modules/m2-prototype-cache-state.md`, this claim
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`, runtime
  cache shutdown/M2 raw/finalizer/extractor/pipeline/material/animation verifiers
  and module specs, `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

- Normalized non-empty paths key static and animated detached `Node3D` prototypes.
- Missing-model and static-animation outcomes are independent path sets.
- Exact cached Node reference is returned; first adoption for an occupied path wins.
- Shutdown frees valid detached nodes synchronously, queues in-tree nodes for free,
  clears all four states and remains idempotent.
- Map refresh retains the state exactly as before; only final shutdown clears it.

## Dependencies

- Requires: accepted raw model repository package on master `ca77d32`
- Blocks: remaining M2 animation request/materialization extraction
- External state: none; verification uses synthetic Node3D instances

## Verification

- Commands: dedicated admission/identity/independence/duplicate/free/source/timing
  verifier; runtime shutdown/raw/finalizer/extractor/cache/pipeline/material/
  animation/M2 build/facade/internal-access/manifest, docs and coordination gates
- Fixtures: detached and in-tree synthetic Node3D prototypes
- Fidelity evidence: all existing lookup/store/negative/clear caller transitions
- Performance budget: 100 cycles over 256 path-state operations under 1 second

## Documentation deliverables

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

## Simplicity and naming

- Important name introduced: `M2PrototypeCacheState`
- Simplest solution: one main-thread RefCounted with two Node maps and two path sets
- Rejected complexity: generic Node cache, signals, callbacks, eviction policy,
  weak references, async cleanup or dependency injection
- Unavoidable complexity: detached Nodes require explicit free at final shutdown
- Measured optimization evidence: bounded synthetic cache-cycle loop

## Status

- State: accepted
- Done: cache state, loader/test adapters, lifecycle verifier and required documentation
- Next: continue M2 animation request/materialization extraction
- Blocked by:

## Handoff

- Commit: `cd664eb`
- Results: prototype state passes 16 admission/identity/negative/lifecycle/source
  cases and 100-by-256 cycles in 50.266 ms; 46 autonomous headless verifiers
  pass, while the proprietary ADT placement probe is unavailable without
  `data/extracted`; checkpoint dry-run passes 7/7; documentation and
  coordination gates pass; loader-private inventory decreases from 34 to 31.
- Remaining risks: strong prototypes remain unbounded until shutdown; successful
  asset traversal, descriptor pressure, leaks and p95/p99 require proprietary
  data; no original-client visual comparison is claimed.
- Documentation updated: inline API; `m2-prototype-cache-state.md` with data-flow,
  lifecycle, sequence and dependency diagrams; pipeline/Mesh-cache/extractor/raw
  repository/world-renderer specs, module registry and `RENDER.md`.

<!-- OPENWC_HANDOFF:READY:M03-RND-M2-PROTOTYPE-CACHE-001:cd664eb -->

## Integration

- Merge commit: `1de50f9`
- Post-merge results: prototype cache `cases=16 iterations=100
  elapsed_ms=37.978`; shutdown, raw repository, finalizer, extractor, Mesh cache,
  pipeline, materials, facade, internal-access `31`, manifest `7/7`,
  documentation and coordination gates passed.

<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-M2-PROTOTYPE-CACHE-001:1de50f9 -->
