open-wc/coordination/claims/M03-RND-M2-ANIMATED-SCENE-FINALIZER-001.md

M03-RND-M2-ANIMATED-SCENE-FINALIZER-001

Owner

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

Outcome

Extract animated M2 PackedScene candidate instantiation, material override repair and AnimationPlayer validation from StreamingWorldLoader into an explicit main-thread finalizer.

Non-goals

• Call ResourceLoader or interpret threaded-load statuses.
• Choose animation eligibility, cache paths, material prototypes or permits.
• Adopt/cache prototype Nodes or change static/native animation paths.
• Change visible materials, animation selection, cache formats or profiles.

Paths

• Exclusive: src/render/m2/m2_animated_scene_finalizer.gd, src/tools/verify_m2_animated_scene_finalizer.gd, docs/modules/m2-animated-scene-finalizer.md, this claim
• Shared/hotspots: src/scenes/streaming/streaming_world_loader.gd, M2 animation pipeline/prototype/material/build/shutdown/facade/internal-access/ manifest 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

• Only a PackedScene whose instantiated root is Node3D becomes a candidate; unsupported or invalid roots return null and any created invalid root is freed.
• Material repair preserves depth-first MeshInstance3D order, source-index clamping, per-surface override priority and first-material fallback.
• Finalization accepts a candidate only when at least one descendant AnimationPlayer exists; rejected detached candidates are freed synchronously.
• Accepted result transfers the exact Node3D and player count to the loader.
• Loader retains ResourceLoader, material-prototype acquisition, permit, prototype adoption/static fallback and diagnostic-log decisions.

Dependencies

• Requires: accepted animation load pipeline package on master c20bc62
• Blocks: further animated M2 build/materialization decomposition
• External state: imported GLB/PackedScene shape remains engine-owned input

Verification

• Commands: dedicated invalid/ownership/traversal/material/finalization/source/ timing verifier; animation pipeline/prototype/shutdown/material/M2 build/facade/ internal-access/manifest and adjacent M2 regressions; docs/coordination/dry-run gates
• Fixtures: synthetic PackedScenes, nested AnimationPlayers and ArrayMesh materials
• Fidelity evidence: exact material mapping and accepted/rejected Node transitions
• Performance budget: 10,000 depth-first candidate queries 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 animation/prototype/world-renderer/module-registry/RENDER updates

Simplicity and naming

• Important name introduced: M2AnimatedSceneFinalizer
• Simplest solution: one stateless main-thread RefCounted over engine scene types
• Rejected complexity: callbacks, generic scene pipeline, signals or cache ownership
• Unavoidable complexity: material repair occurs between candidate creation and acceptance
• Measured optimization evidence: bounded synthetic subtree traversal

Status

• State: accepted
• Done: finalizer, loader adapters, lifecycle/material verifier and required documentation
• Next: continue animated M2 playback/instance materialization extraction
• Blocked by:

Handoff

• Commit: 1b450dc
• Results: animated scene finalizer passes 13 invalid/type/lifetime/traversal/ material/transfer/source cases and 10,000 depth-eight queries in 40.126 ms; all 48 autonomous headless verifiers pass, while the proprietary ADT placement probe is unavailable without data/extracted; checkpoint dry-run passes 7/7; documentation and coordination gates pass; loader-private inventory remains 30.
• Remaining risks: proprietary GLB traversal, material/animation comparison, descriptor pressure, leaks and p95/p99 remain unavailable; no paired original- client visual comparison is claimed. Positional material mapping is unchanged.
• Documentation updated: inline API; m2-animated-scene-finalizer.md with data-flow, lifecycle, sequence and dependency diagrams; animation pipeline, prototype/world-renderer specs, module registry and RENDER.md.

Integration

• Merge commit: e7a7c67
• Post-merge results: finalizer cases=13 iterations=10000 elapsed_ms=40.314; animation pipeline, prototype state, shutdown, materials, facade, internal-access 30, manifest 7/7, documentation and coordination passed.