# 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: 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`.

<!-- OPENWC_HANDOFF:READY:M03-RND-M2-ANIMATED-SCENE-FINALIZER-001:1b450dc -->

## 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.

<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-M2-ANIMATED-SCENE-FINALIZER-001:e7a7c67 -->
