open-wc/coordination/claims/M03-RND-M2-BUILD-RESOURCE-SNAPSHOT-001.md

M03-RND-M2-BUILD-RESOURCE-SNAPSHOT-001

Owner

• Agent ID: sindo-main-codex
• Target: M03 Renderer Facade and Safe Extraction
• Branch: work/sindo-main-codex/m03-m2-build-resource-snapshot
• Worktree: C:\Users\sindo\open-wc-worktrees\m03-m2-build-resource-snapshot

Outcome

Replace loose per-step M2 animated/static resource variables with a typed observation snapshot consumed by the dispatch planner and materializer adapter.

Non-goals

• Move ResourceLoader I/O, cache lookup/request execution or retry ownership.
• Own or free prototype Nodes or Mesh Resources.
• Change dispatch priority, batch sizing, queue ordering, permits or visuals.
• Change M2 cache paths, formats, allowlists or native animation selection.

Paths

• Exclusive: src/render/m2/m2_build_resource_snapshot.gd, src/tools/verify_m2_build_resource_snapshot.gd, docs/modules/m2-build-resource-snapshot.md, this claim
• Shared/hotspots: src/render/m2/m2_build_dispatch_planner.gd, its verifier/spec, src/scenes/streaming/streaming_world_loader.gd, M2 queue/materializer/cache specs and tests, docs/modules/world-renderer.md, docs/modules/README.md, RENDER.md, targets/03-renderer-facade.md
• Generated/ignored: .godot, native DLL, generated resources/caches and proprietary corpus

Contracts and data

• Snapshot retains normalized path, optional animated prototype, animation request state, optional static Mesh and terminal missing-model state.
• Static observation is adopted only after animation is not pending, the batch is positive and no animated prototype exists.
• Accessors borrow exact engine references without transferring/freeing ownership.
• Diagnostics expose only path and scalar availability flags.

Dependencies

• Requires: accepted M2 dispatch planner on master b113db0
• Blocks: extracting M2 resource observation/request service ownership
• External state: prototype/cache/pipeline/resource lifetime remains loader-owned

Verification

• Commands: dedicated identity/adoption/diagnostic/lifetime/source/timing verifier; dispatch/queue/batch/materializer/cache/pipeline/shutdown/facade/internal-access/ manifest regressions; documentation, coordination and checkpoint dry-run gates
• Fixtures: synthetic Node3D prototype and ArrayMesh resources
• Fidelity evidence: exact resource presence/pending/missing values and branch order
• Performance budget: 20,000 snapshot construct/adopt/read cycles under one second

Documentation deliverables

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

Simplicity and naming

• Important name: M2BuildResourceSnapshot
• Simplest solution: one small RefCounted value holder with explicit accessors
• Rejected complexity: generic resource union, signals, callbacks and cache ownership
• Unavoidable complexity: two-phase animation then optional static observation
• Measured optimization evidence: bounded synthetic lifecycle loop

Status

• State: ready for integration
• Done: implementation, verification, documentation and worktree handoff
• Next: no-ff merge and post-merge acceptance on master
• Blocked by:

Handoff

• Commit: ec1b90f1e44037572e3e5052e6dedc016c29859a
• Results: resource snapshot cases=12 iterations=20000 elapsed_ms=42.995; dispatch planner remained green; all autonomous headless regressions 54/54; internal access private_symbols=30; baseline manifest/dry-run 7/7; documentation module_specs=41; coordination passed with 30 historical warnings.
• Remaining risks: proprietary ADT visual/p95/p99 evidence is unavailable; resource lookup/request execution, action execution, permits and engine lifetime intentionally remain loader-owned.
• Documentation updated: new m2-build-resource-snapshot.md with API/I/O, data-flow, lifecycle, sequence, dependency and ownership diagrams; dispatch/ queue/world renderer specs, module registry, RENDER and M03 Evidence updated.