sindoring
5e2afbc400
Work-Package: M03-RND-M2-MESH-RESOURCE-CACHE-001 Agent: sindo-main-codex Tests: post-merge cache, pipeline, classifier, materials, shutdown, facade, internal-access, manifest, documentation and coordination gates pass Fidelity: preserves Mesh identity/replacement/final-shutdown lifetime; asset-backed visual parity remains unclaimed
4.3 KiB
4.3 KiB
M03-RND-M2-MESH-RESOURCE-CACHE-001 — M2 mesh resource cache state
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.mdwith data-flow, lifecycle, sequence and dependency diagrams; pipeline spec, module registry,world-renderer.mdandRENDER.md.
Integration
- Merge commit:
3094561 - Post-merge results: cache state
cases=9 iterations=100 elapsed_ms=38.686; pipeline, classifier, materials, shutdown, facade, internal-access34, manifest7/7, documentation and coordination gates passed.