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
109 lines
4.3 KiB
Markdown
109 lines
4.3 KiB
Markdown
# 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 -->
|