diff --git a/coordination/claims/M03-RND-M2-PROTOTYPE-CACHE-001.md b/coordination/claims/M03-RND-M2-PROTOTYPE-CACHE-001.md new file mode 100644 index 0000000..8ac4ae2 --- /dev/null +++ b/coordination/claims/M03-RND-M2-PROTOTYPE-CACHE-001.md @@ -0,0 +1,91 @@ +# M03-RND-M2-PROTOTYPE-CACHE-001 — M2 prototype cache state + + + +## 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: claimed +- Done: four cache tables and all caller/lifecycle sites identified +- Next: implement state service, migrate adapters, verify and document +- Blocked by: + +## Handoff + +- Commit: +- Results: +- Remaining risks: +- Documentation updated: