open-wc/coordination/claims/M03-RND-WMO-RENDER-RESOURCE-CACHE-001.md

M03-RND-WMO-RENDER-RESOURCE-CACHE-001 — WMO render resource cache state

Ownership

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

Outcome

Extract lightweight-WMO render Resource cache, negative cache and asynchronous request bookkeeping from the loader while preserving loader-owned I/O and cache-format validation.

Non-goals

• Call ResourceLoader, construct cache paths or inspect files.
• Validate WMOStreamingResource script identity or format version.
• Own cached WMO scenes, live prototypes, placement/build jobs or Nodes/RIDs.
• Change fallback order, retry behavior, quality profiles or visual output.
• Claim asset-backed WMO fidelity, leak acceptance or traversal p95/p99.

Paths

• Exclusive: src/render/wmo/wmo_render_resource_cache_state.gd, src/tools/verify_wmo_render_resource_cache_state.gd, docs/modules/wmo-render-resource-cache-state.md, this claim
• Shared/hotspots: src/scenes/streaming/streaming_world_loader.gd, src/tools/verify_render_runtime_cache_shutdown.gd, docs/modules/wmo-render-build-queue.md, docs/modules/world-renderer.md, docs/modules/README.md, RENDER.md, targets/03-renderer-facade.md
• Generated/ignored: .godot, native DLL, generated ADT/WMO resources, caches and proprietary renderer corpus

Contracts and data

• State keys are loader-normalized relative WMO paths copied as String.
• Cached values are already validated Resource references.
• Pending values are cache paths for loader-owned ResourceLoader requests.
• Terminal request removal precedes validated-resource or missing-state adoption.
• Request/missing reset preserves accepted resources; full clear releases all.
• Cache/schema/coordinate/profile versions and validation rules remain unchanged.

Dependencies

• Requires: current master c954704, accepted WMO render build queue
• Blocks: further WMO cached-scene/load and materialization decomposition
• External state: none; verification uses synthetic Resources and paths

Verification

• Commands: dedicated lifecycle/request/cache/reset/diagnostics/source/timing verifier; WMO queue/planner/registry/resolver/material/shutdown plus adjacent renderer/streaming/coordinate/documentation/coordination gates
• Fixtures: synthetic Resource instances and normalized relative/cache paths
• Fidelity evidence: exact current cache/missing/request transitions preserved
• Performance budget: 100 cycles over 256 resource/request keys under 1 second

Documentation deliverables

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

Simplicity and naming

• Important names introduced: WmoRenderResourceCacheState
• Simplest considered solution: one RefCounted around three Dictionaries
• Rejected complexity/abstractions: generic cache, callbacks, signals, mutexes, ResourceLoader wrapper, persistence layer or shared WMO/M2 cache hierarchy
• Unavoidable complexity and justification: partial reset must retain validated Resources while discarding pending/negative state at map reset and shutdown
• Measured optimization evidence: bounded synthetic store/request/reset loop

Status

• State: ready for integration
• Done: state holder implemented; loader cache/request/reset/metrics adapters migrated; shutdown regression and required documentation updated
• Next: integrate and run post-merge smoke on master
• Blocked by:

Handoff

• Commit: d39f591
• Results: cache-state PASS (cases=10, iterations=100, elapsed_ms=58.727); direct no-.godot cache-state run PASS (45.361ms); WMO queue/planner/registry/resolver/material/shutdown plus 18 adjacent M2/terrain/facade/scheduler/streaming/coordinate regressions PASS; documentation and coordination gates PASS; checkpoint dry-run PASS 7/7.
• Remaining risks: accepted Resources remain strongly referenced until full shutdown release; cached-scene and ResourceLoader I/O seams remain in loader; no proprietary corrupt-cache fixture, asset-backed WMO traversal/leak run, p95/p99 or original-client paired evidence. Full loader cannot be used as a direct empty-class-cache smoke because pre-existing typed global coordinate/ focus dependencies require editor class registration; the extracted service itself passed cold and normal editor parse passed.
• Documentation updated: inline public API; new docs/modules/wmo-render-resource-cache-state.md; module registry, WMO queue, world renderer and RENDER.md; data-flow/state/sequence diagrams, ownership, threading, cache-version boundary, failure/recovery and source map included.