render: extract M2 animation resource finalizer

docs/modules/m2-animation-load-pipeline-state.md

@@ -15,9 +15,9 @@
 Own cross-frame bookkeeping between a successful animated M2 ResourceLoader
 request, terminal polling and budgeted main-thread scene finalization. This is
 an exact state extraction; cached animation eligibility and request admission
-belong to `M2CachedAnimationResourceObserver`, while scene finalization and
-retained Node lifecycle belong to `M2AnimatedSceneFinalizer` and
-`M2PrototypeCacheState`.
+belong to `M2CachedAnimationResourceObserver`; terminal I/O/outcomes belong to
+`M2AnimationResourceFinalizer`, while validation and retained Node lifetime
+belong to `M2AnimatedSceneFinalizer` and `M2PrototypeCacheState`.
 
 ## Non-goals
 
@@ -32,11 +32,12 @@ retained Node lifecycle belong to `M2AnimatedSceneFinalizer` and
 flowchart LR
     Observer[M2CachedAnimationResourceObserver] --> IO[ResourceLoader request]
     Observer --> State[M2AnimationLoadPipelineState]
-    Loader[StreamingWorldLoader] --> IO
-    Loader --> State
-    State -->|detached pending records| Loader
-    Loader -->|opaque terminal status| State
-    State -->|completion FIFO| Loader
+    Finalizer[M2AnimationResourceFinalizer] --> IO
+    Finalizer --> State
+    State -->|detached pending records| Finalizer
+    Finalizer -->|opaque terminal status| State
+    State -->|completion FIFO| Finalizer
+    Loader[StreamingWorldLoader] --> Finalizer
     Loader --> Budget[M2_ANIMATION_FINALIZE permit]
     Loader --> Prototype[M2PrototypeCacheState]
 ```
@@ -65,9 +66,9 @@ renderer services are forbidden.
 | Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
 |---|---|---|---|---|---|
 | Input | Normalized M2 path and GLB Resource path | Loader request adapter | Pending map | Copied Strings | Until completion/discard/clear |
-| Input | Opaque terminal status | Loader polling adapter | Finalize FIFO | Integer value | Until pop/clear |
-| Output | Detached pending records | State | Loader poll/shutdown adapter | Caller-owned copies | One pass |
-| Output | Oldest completion record | State | Loader finalizer | Transferred Dictionary | One finalize attempt |
+| Input | Opaque terminal status | Resource finalizer | Finalize FIFO | Integer value | Until pop/clear |
+| Output | Detached pending records | State | Resource finalizer/shutdown adapter | Caller-owned copies | One pass |
+| Output | Oldest completion record | State | Resource finalizer | Transferred Dictionary | One finalize attempt |
 | Output | Detached diagnostics | State | Verifier/future metrics | Caller-owned copies | Snapshot lifetime |
 
 Side effects are limited to collection mutation and retaining String/integer values.
@@ -77,7 +78,7 @@ Side effects are limited to collection mutation and retaining String/integer val
 ```mermaid
 flowchart TD
     Start[Successful threaded request] --> Remember[Remember request]
-    Remember --> Poll[Loader polls detached snapshot]
+    Remember --> Poll[Resource finalizer polls detached snapshot]
     Poll --> Terminal{Loaded or failed?}
     Terminal -->|no| Poll
     Terminal -->|yes| Complete[Complete with opaque status]
@@ -85,7 +86,7 @@ flowchart TD
     FIFO --> Permit{Permit available?}
     Permit -->|no| FIFO
     Permit -->|yes| Pop[Pop oldest record]
-    Pop --> Finalize[Loader loads/instantiates or marks static]
+    Pop --> Finalize[Resource finalizer loads/instantiates or marks static]
 ```
 
 ## Lifecycle/state
@@ -105,19 +106,22 @@ stateDiagram-v2
 sequenceDiagram
     participant O as CachedAnimationObserver
     participant L as StreamingWorldLoader
+    participant F as AnimationResourceFinalizer
     participant R as ResourceLoader
     participant S as M2AnimationLoadPipelineState
     participant P as M2PrototypeCacheState
     O->>R: load_threaded_request(GLB)
     O->>S: remember_request(path, GLB)
     loop frames
-        L->>S: request_records_snapshot()
-        L->>R: load_threaded_get_status(GLB)
+        L->>F: poll terminal requests
+        F->>S: request_records_snapshot()
+        F->>R: load_threaded_get_status(GLB)
     end
-    L->>S: complete_request(path, status)
-    L->>S: pop_finalize_record() after permit
-    L->>R: load_threaded_get(GLB)
-    L->>P: adopt animated prototype or mark static
+    F->>S: complete_request(path, status)
+    L->>F: prepare after permit
+    F->>S: pop_finalize_record()
+    F->>R: load_threaded_get(GLB)
+    F->>P: adopt animated prototype or mark static
 ```
 
 ## Ownership, threading and resources
@@ -125,8 +129,8 @@ sequenceDiagram
 - Main thread serializes all mutation.
 - State owns only request/finalize Dictionaries with copied paths and statuses.
 - Loader drains pending ResourceLoader paths before orderly shutdown clear.
-- Loader owns PackedScene instantiation and material repair; prototype state owns
-  accepted detached Node references and static-only outcomes.
+- Resource finalizer owns terminal I/O/outcomes and composes scene validation;
+  prototype state owns accepted detached Nodes and static-only outcomes.
 
 ## Dependency diagram
 
@@ -134,8 +138,9 @@ sequenceDiagram
 flowchart TB
     Observer[M2CachedAnimationResourceObserver] --> State[M2AnimationLoadPipelineState]
     Observer --> Resource[ResourceLoader request]
-    Loader[StreamingWorldLoader] --> State[M2AnimationLoadPipelineState]
-    Loader --> Resource
+    Finalizer[M2AnimationResourceFinalizer] --> State[M2AnimationLoadPipelineState]
+    Finalizer --> Resource
+    Loader[StreamingWorldLoader] --> Finalizer
     Loader --> Budget[RenderBudgetScheduler]
     Loader --> Prototype[M2PrototypeCacheState]
     State -. no dependency .-> Resource
@@ -185,9 +190,8 @@ no rebake or migration is required.
 
 ## Extension points
 
-ResourceLoader polling may later move behind a separate adapter without
-changing this value-only state contract. Animated-scene finalization is now a
-sibling service.
+ResourceLoader polling/finalization now belongs to a sibling service without
+changing this value-only state contract.
 
 ## Capability status
 
@@ -195,7 +199,7 @@ sibling service.
 |---|---|---|---|
 | Animated request/finalize state | Implemented extraction | Synthetic contract/source/timing verifier | Asset-backed traversal/leak/p95/p99 pending |
 | Cached request admission and GLB selection | Implemented in observer | Policy/GLB/source verifier | Asset-backed traversal pending |
-| Terminal ResourceLoader polling | Existing loader-owned | Shutdown/finalizer regressions | I/O adapter extraction optional |
+| Terminal ResourceLoader polling | Implemented finalizer extraction | Status/order/source regressions | Asset-backed traversal pending |
 | Animated prototype outcomes | Implemented extraction | Prototype cache verifier | Asset-backed animation fidelity pending |
 
 ## Known gaps and risks
@@ -209,15 +213,17 @@ sibling service.
 | Path | Responsibility |
 |---|---|
 | `src/render/m2/m2_animation_load_pipeline_state.gd` | Pending records, completion FIFO and metrics |
+| `src/render/m2/m2_animation_resource_finalizer.gd` | Terminal polling, Resource load and prototype outcome |
 | `src/render/m2/m2_cached_animation_resource_observer.gd` | Eligibility, GLB selection and request admission |
 | `src/render/m2/m2_animated_scene_finalizer.gd` | Candidate instantiation, material repair and player validation |
 | `src/render/m2/m2_prototype_cache_state.gd` | Animated prototype/static-only outcomes |
-| `src/scenes/streaming/streaming_world_loader.gd` | Native eligibility/build, polling, permits and adoption |
+| `src/scenes/streaming/streaming_world_loader.gd` | Permit loop, material lookup and composition |
 | `src/tools/verify_m2_animation_load_pipeline_state.gd` | Lifecycle/boundary/timing regression |
 
 ## Related decisions and references
 
 - [`m2-animated-scene-finalizer.md`](m2-animated-scene-finalizer.md)
+- [`m2-animation-resource-finalizer.md`](m2-animation-resource-finalizer.md)
 - [`m2-prototype-cache-state.md`](m2-prototype-cache-state.md)
 - [`m2-mesh-load-pipeline-state.md`](m2-mesh-load-pipeline-state.md)
 - [`world-renderer.md`](world-renderer.md)