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

<!-- OPENWC_CLAIM:M03-RND-M2-ANIMATED-SCENE-FINALIZER-001:sindo-main-codex:2026-07-20 -->

## 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: claimed
- Done: candidate/material/player ownership boundary audited on current master
- Next: implement finalizer, migrate adapters, verify and document
- Blocked by:

## Handoff

- Commit:
- Results:
- Remaining risks:
- Documentation updated: