render: extract M2 animation resource finalizer

docs/modules/m2-animated-scene-finalizer.md

@@ -27,9 +27,9 @@ and accept only candidates containing AnimationPlayer descendants.
 
 ```mermaid
 flowchart LR
-    Loader[StreamingWorldLoader] -->|loaded Resource and material source| Finalizer[M2AnimatedSceneFinalizer]
-    Finalizer -->|accepted Node3D and player count| Loader
-    Loader --> Cache[M2PrototypeCacheState]
+    ResourceFinalizer[M2AnimationResourceFinalizer] -->|loaded Resource and material source| Finalizer[M2AnimatedSceneFinalizer]
+    Finalizer -->|accepted Node3D and player count| ResourceFinalizer
+    ResourceFinalizer --> Cache[M2PrototypeCacheState]
 ```
 
 Allowed dependencies are Godot scene/resource/material types. ResourceLoader,
@@ -50,10 +50,10 @@ other application layers are forbidden.
 
 | Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
 |---|---|---|---|---|---|
-| Input | Loaded Resource | Loader I/O adapter | Candidate instantiator | Borrowed Resource | One finalize permit |
+| Input | Loaded Resource | Animation resource finalizer | Candidate instantiator | Borrowed Resource | One finalize permit |
 | Input | Static material prototype Node3D | Loader cache/build adapter | Material repair | Borrowed Node | One repair call |
 | Input | Detached animated candidate | Instantiator | Repair/final validation | Finalizer then caller/release | One attempt |
-| Output | Accepted prototype and player count | Finalizer | Loader adoption/log adapter | Exact Node transferred | Shutdown cache lifetime |
+| Output | Accepted prototype and player count | Finalizer | Resource-finalizer adoption/log adapter | Exact Node transferred | Shutdown cache lifetime |
 | Output | Depth-first engine-node arrays | Traversal | Loader preparation/playback | Borrowed references | One call |
 
 Side effects are PackedScene instantiation, surface override assignment and
@@ -91,20 +91,19 @@ stateDiagram-v2
 
 ```mermaid
 sequenceDiagram
-    participant L as StreamingWorldLoader
+    participant R as M2AnimationResourceFinalizer
     participant F as M2AnimatedSceneFinalizer
     participant C as M2PrototypeCacheState
-    L->>F: instantiate_candidate(Resource)
-    F-->>L: detached Node3D or null
-    L->>L: get static material prototype
-    L->>F: repair_materials(candidate, source)
-    L->>F: finalize_candidate(candidate)
+    R->>F: instantiate_candidate(Resource)
+    F-->>R: detached Node3D or null
+    R->>F: repair_materials(candidate, source)
+    R->>F: finalize_candidate(candidate)
     alt accepted
-        F-->>L: exact Node3D and player count
-        L->>C: adopt animated prototype
+        F-->>R: exact Node3D and player count
+        R->>C: adopt animated prototype
     else rejected
-        F-->>L: empty; candidate freed
-        L->>C: mark animation static
+        F-->>R: empty; candidate freed
+        R->>C: mark animation static
     end
 ```
 
@@ -112,11 +111,11 @@ sequenceDiagram
 
 ```mermaid
 flowchart TB
-    Loader[StreamingWorldLoader] --> Finalizer[M2AnimatedSceneFinalizer]
+    ResourceFinalizer[M2AnimationResourceFinalizer] --> Finalizer[M2AnimatedSceneFinalizer]
     Finalizer --> Engine[PackedScene / Node3D / Mesh / Material / AnimationPlayer]
-    Loader --> Resource[ResourceLoader]
+    ResourceFinalizer --> Resource[ResourceLoader]
     Loader --> Budget[RenderBudgetScheduler]
-    Loader --> Prototype[M2PrototypeCacheState]
+    ResourceFinalizer --> Prototype[M2PrototypeCacheState]
     Finalizer -. no dependency .-> Resource
     Finalizer -. no dependency .-> Budget
     Finalizer -. no dependency .-> Prototype
@@ -126,7 +125,7 @@ flowchart TB
 
 - Every method runs synchronously on the renderer main thread.
 - A valid candidate is detached and finalizer-owned until acceptance.
-- Acceptance transfers the exact Node3D to the loader/prototype cache path.
+- Acceptance transfers the exact Node3D to the resource-finalizer/cache path.
 - Rejection frees the candidate synchronously, including wrong-type roots.
 - Traversal results borrow Nodes; source materials remain Resource-owned.
 
@@ -134,11 +133,11 @@ flowchart TB
 
 | Failure | Detection | Behavior | Diagnostic | Recovery |
 |---|---|---|---|---|
-| Null/unsupported Resource | Type guard | Return null | Dedicated verifier | Loader marks static |
+| Null/unsupported Resource | Type guard | Return null | Dedicated verifier | Resource finalizer marks static |
 | Wrong root type | Instantiated type guard | Free and return null | Node-count regression | Rebuild cache |
 | No material source/meshes | Null/empty traversal | Leave materials unchanged | Material fixture | Imported materials remain |
 | Missing source surface | Material lookup | First source material fallback | Mapping fixture | Repair static source |
-| No AnimationPlayer | Descendant inventory | Free and return empty | Lifetime regression | Loader marks static |
+| No AnimationPlayer | Descendant inventory | Free and return empty | Lifetime regression | Resource finalizer marks static |
 | Shutdown/cancellation | Not owned | No retained state | N/A | Loader drains first |
 
 ## Configuration and capabilities
@@ -199,7 +198,8 @@ by `M2AnimatedInstanceMaterializer`.
 | `src/render/m2/m2_animated_instance_materializer.gd` | Per-duplicate player inventory consumer and batch owner |
 | `src/render/m2/m2_animation_load_pipeline_state.gd` | Pending/terminal records before finalization |
 | `src/render/m2/m2_prototype_cache_state.gd` | Accepted prototype/static-only outcomes |
-| `src/scenes/streaming/streaming_world_loader.gd` | I/O, permits, material source, adoption and logs |
+| `src/render/m2/m2_animation_resource_finalizer.gd` | I/O, candidate composition, adoption and logs |
+| `src/scenes/streaming/streaming_world_loader.gd` | Permits and material-source lookup |
 | `src/tools/verify_m2_animated_scene_finalizer.gd` | Scene/material/lifetime/boundary/timing regression |
 
 ## Related decisions and references