render: extract M2 animation resource finalizer

docs/modules/README.md

@@ -33,6 +33,7 @@
 | M2 animation playback controller | Implemented extraction | [`m2-animation-playback-controller.md`](m2-animation-playback-controller.md) |
 | M2 animated instance materializer | Implemented extraction | [`m2-animated-instance-materializer.md`](m2-animated-instance-materializer.md) |
 | M2 animation load pipeline state | Implemented extraction | [`m2-animation-load-pipeline-state.md`](m2-animation-load-pipeline-state.md) |
+| M2 animation resource finalizer | Implemented extraction | [`m2-animation-resource-finalizer.md`](m2-animation-resource-finalizer.md) |
 | M2 mesh load pipeline state | Implemented extraction | [`m2-mesh-load-pipeline-state.md`](m2-mesh-load-pipeline-state.md) |
 | M2 mesh resource cache state | Implemented extraction | [`m2-mesh-resource-cache-state.md`](m2-mesh-resource-cache-state.md) |
 | M2 mesh resource extractor | Implemented extraction | [`m2-mesh-resource-extractor.md`](m2-mesh-resource-extractor.md) |

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

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)

docs/modules/m2-animation-resource-finalizer.md

@@ -0,0 +1,249 @@
+# M2 Animation Resource Finalizer
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Status | Implemented extraction |
+| Target/work package | M03 / `M03-RND-M2-ANIMATION-RESOURCE-FINALIZER-001` |
+| Owners | Cached animated Resource polling, terminal load and prototype outcome |
+| Last verified | Worktree `work/sindo-main-codex/m03-m2-animation-resource-finalizer`, 2026-07-18 |
+| Profiles/capabilities | Existing optional cached-GLB animated M2 path |
+
+## Purpose
+
+Drain cached animated M2 ResourceLoader work without keeping terminal I/O and
+prototype outcome logic in `StreamingWorldLoader`. The service polls pending
+requests, prepares a detached scene candidate and completes material repair,
+validation, cache adoption or static-only fallback.
+
+## Non-goals
+
+- Select cached GLB paths, apply allow/deny policy or admit threaded requests.
+- Select/build native animated M2 prototypes.
+- Look up the static material prototype used for repair.
+- Own render permits, build jobs, playback, instances or SceneTree roots.
+- Change ResourceLoader ordering, cache formats, profiles or visible output.
+
+## Context and boundaries
+
+```mermaid
+flowchart LR
+    Observer[M2CachedAnimationResourceObserver] --> Pipeline[M2AnimationLoadPipelineState]
+    Loader[StreamingWorldLoader] --> Finalizer[M2AnimationResourceFinalizer]
+    Pipeline --> Finalizer
+    ResourceLoader --> Finalizer
+    Finalizer --> SceneFinalizer[M2AnimatedSceneFinalizer]
+    Finalizer --> Cache[M2PrototypeCacheState]
+    Loader --> Material[Material prototype lookup]
+    Material --> Finalizer
+```
+
+The two-phase API preserves the historical ordering: a loaded Resource must
+instantiate a candidate before the loader performs material-prototype lookup.
+
+## Public API
+
+| Symbol | Kind | Purpose | Failure behavior |
+|---|---|---|---|
+| `poll_terminal_requests(pipeline, cache)` | I/O command | Move LOADED/FAILED requests to completion FIFO | Invalid composition returns zero |
+| `prepare_next_candidate(pipeline, cache)` | I/O command/query | Pop one record, load Resource and instantiate candidate | Skip/failed/invalid outcome returns empty Dictionary |
+| `finalize_prepared_candidate(preparation, material_source, cache, debug)` | Command/query | Repair, validate, adopt/log or mark static-only | Invalid/finalization failure returns null |
+| `load_threaded_get_status(path)` | I/O adapter | Production status query with injectable test seam | Returns ResourceLoader status |
+| `load_threaded_get(path)` | I/O adapter | Production terminal Resource retrieval with injectable test seam | May return null |
+
+## Inputs and outputs
+
+| Direction | Data | Producer | Consumer | Ownership/lifetime |
+|---|---|---|---|---|
+| Input | Pending/finalize records | Animation pipeline | Finalizer | Pipeline-owned copied Dictionaries |
+| Input | ResourceLoader status/Resource | Godot ResourceLoader | Finalizer | Resource reference for one operation |
+| Input | Material source root | Loader lookup | Scene finalizer | Borrowed exact Node3D |
+| Input | Prototype/static-only state | Prototype cache | Finalizer | Borrowed service; loader session |
+| Output | Prepared candidate Dictionary | Finalizer | Loader/finalizer completion | Caller-owned, immediate operation |
+| Output | Canonical animated prototype | Prototype cache | Loader build path | Borrowed exact Node3D |
+| Output | Static-only outcome | Finalizer | Prototype cache | Copied path; loader session |
+| Output | Success diagnostic | Finalizer | Runtime log | Debug-gated one-line record |
+
+## Data flow
+
+```mermaid
+flowchart TD
+    Poll[Poll pending records in insertion order] --> Path{Resource path empty?}
+    Path -->|yes| Discard[Discard and mark static-only]
+    Path -->|no| Status{LOADED or FAILED?}
+    Status -->|no| Pending[Keep pending]
+    Status -->|yes| Complete[Append completion FIFO]
+    Complete --> Permit[Loader consumes one finalize permit]
+    Permit --> Pop[Pop oldest terminal record]
+    Pop --> Existing{Empty/cached/static-only?}
+    Existing -->|yes| Skip[Finish permit operation]
+    Existing -->|no| Loaded{Status LOADED?}
+    Loaded -->|no| Mark[Mark static-only]
+    Loaded -->|yes| Get[Get terminal Resource]
+    Get --> Instantiate[Instantiate detached candidate]
+    Instantiate --> Valid{Candidate exists?}
+    Valid -->|no| Mark
+    Valid -->|yes| Material[Loader resolves material source]
+    Material --> Repair[Repair and validate]
+    Repair --> Prototype{Prototype accepted?}
+    Prototype -->|no| Mark
+    Prototype -->|yes| Adopt[Adopt and optionally log]
+```
+
+## Lifecycle/state
+
+```mermaid
+stateDiagram-v2
+    [*] --> Polling
+    Polling --> Pending: nonterminal status
+    Polling --> TerminalQueued: LOADED or FAILED
+    Polling --> StaticOnly: empty Resource path
+    TerminalQueued --> Skipped: cached/static/invalid record
+    TerminalQueued --> StaticOnly: failed load or invalid candidate
+    TerminalQueued --> Prepared: detached candidate
+    Prepared --> Adopted: repair/finalize succeeds
+    Prepared --> StaticOnly: validation fails
+    Pending --> [*]
+    Skipped --> [*]
+    StaticOnly --> [*]
+    Adopted --> [*]
+```
+
+## Main sequence
+
+```mermaid
+sequenceDiagram
+    participant L as StreamingWorldLoader
+    participant F as AnimationResourceFinalizer
+    participant P as AnimationLoadPipelineState
+    participant R as ResourceLoader
+    participant S as AnimatedSceneFinalizer
+    participant C as PrototypeCacheState
+    L->>F: poll_terminal_requests(P, C)
+    F->>R: load_threaded_get_status(path)
+    F->>P: complete terminal request
+    L->>L: consume M2_ANIMATION_FINALIZE permit
+    L->>F: prepare_next_candidate(P, C)
+    F->>P: pop oldest finalize record
+    F->>R: load_threaded_get(path)
+    F->>S: instantiate_candidate(Resource)
+    alt candidate available
+        F-->>L: normalized/path/candidate
+        L->>L: resolve material prototype
+        L->>F: finalize_prepared_candidate(...)
+        F->>S: repair_materials + finalize_candidate
+        F->>C: adopt prototype or mark static-only
+    else rejected
+        F->>C: mark static-only
+    end
+```
+
+## Dependency diagram
+
+```mermaid
+flowchart TB
+    Finalizer[M2AnimationResourceFinalizer] --> ResourceLoader
+    Finalizer --> Pipeline[M2AnimationLoadPipelineState]
+    Finalizer --> SceneFinalizer[M2AnimatedSceneFinalizer]
+    Finalizer --> Cache[M2PrototypeCacheState]
+    Loader[StreamingWorldLoader] --> Finalizer
+    Loader --> Scheduler[RenderBudgetScheduler]
+    Loader --> MaterialLookup[Material prototype lookup]
+    Finalizer -. no dependency .-> Scheduler
+    Finalizer -. no dependency .-> BuildQueue[M2BuildQueue]
+    Finalizer -. no dependency .-> Playback[M2AnimationPlaybackController]
+```
+
+## Ownership, threading and resources
+
+- All methods run synchronously on the renderer main thread.
+- Pipeline owns pending and completion records; one loader permit pops one record.
+- The prepared Dictionary temporarily owns the detached candidate reference. The
+  loader must call completion synchronously after material lookup.
+- Existing scene finalizer frees rejected candidate roots. Prototype cache owns
+  accepted detached prototypes until final shutdown.
+- Service retains only scene-finalizer and optional test-adapter references. The
+  production ResourceLoader path creates no self-reference or retained Resource.
+- Loader retains scheduler permits, material lookup and all instance/SceneTree work.
+
+## Errors, cancellation and recovery
+
+| Failure/state | Behavior | Recovery |
+|---|---|---|
+| Missing service dependency | Return zero/empty/null | Correct renderer composition |
+| Empty Resource path | Discard pending request and mark static-only | Repair cache and start new session |
+| Nonterminal status | Keep request pending | Poll next tick |
+| FAILED terminal status | Pop one record and mark static-only | Repair cache and start new session |
+| Existing cached/static state | Pop and skip without terminal Resource get | None |
+| Null/unsupported Resource | Mark static-only | Repair imported cache |
+| Candidate validation failure | Scene finalizer frees candidate; mark static-only | Repair animation/cache |
+| Tile cancellation | No direct transition; shared cache work continues | Loader queue remains authoritative |
+| Shutdown | Loader drains ResourceLoader before pipeline/cache clear | New loader starts empty |
+
+## Configuration and capabilities
+
+The module adds no setting. Existing cached-animation allow/deny policy,
+`m2_animation_finalize_ops_per_tick`, debug flag and scheduler lane remain exact.
+
+## Persistence, cache and migration
+
+No persistence, schema or cache path changes are introduced. Existing `.glb`
+imports and `pivot_prefix_v1` eligibility remain owned by the cached observer.
+
+## Diagnostics and observability
+
+Successful debug-enabled adoption emits the unchanged `M2_ANIM_CACHE` record
+with normalized path, Resource cache path and AnimationPlayer count. Pipeline
+work metrics remain pending plus completion FIFO size.
+
+## Verification
+
+- Dedicated verifier covers pending/loaded/failed polling order, empty path,
+  completion FIFO, cached/static skips, terminal Resource get, candidate identity,
+  material repair arguments, adoption, rejection, source ownership and timing.
+- Pipeline, scene-finalizer, prototype-cache, cached-observer, shutdown, facade,
+  internal-access and baseline regressions protect adjacent behavior.
+- Fidelity evidence is exact lifecycle/I/O extraction only; no private asset,
+  original-client animation, visual, leak-pressure or p95/p99 claim is made.
+
+## Extension points
+
+Material-prototype lookup may later become a dedicated resource observer, which
+would allow the entire two-phase operation to compose outside the loader. Static
+Mesh Resource finalization remains separate to avoid premature generalization.
+
+## Capability status
+
+| Capability | Status | Evidence | Gap/next step |
+|---|---|---|---|
+| Animated request terminal polling | Implemented extraction | Status/order/source verifier | Asset-backed long traversal pending |
+| Animated candidate finalization/outcome | Implemented extraction | Identity/repair/adoption verifier | Private visual/leak/p95/p99 pending |
+| Material prototype lookup | Loader-owned | Existing renderer regressions | Dedicated observer optional |
+
+## Known gaps and risks
+
+- Terminal Resource get, instantiation and repair remain synchronous main-thread work.
+- Prepared candidate ownership relies on immediate completion by the loader adapter.
+- Private asset traversal, descriptor pressure, leak and p95/p99 evidence is absent.
+
+## Source map
+
+| Path | Responsibility |
+|---|---|
+| `src/render/m2/m2_animation_resource_finalizer.gd` | Poll/load/prepare/finalize/cache/log service |
+| `src/render/m2/m2_animation_load_pipeline_state.gd` | Pending and completion FIFO ownership |
+| `src/render/m2/m2_animated_scene_finalizer.gd` | Candidate instantiation/repair/validation/rejection cleanup |
+| `src/render/m2/m2_prototype_cache_state.gd` | Accepted prototype/static-only ownership |
+| `src/scenes/streaming/streaming_world_loader.gd` | Permits, material lookup and synchronous composition |
+| `src/tools/verify_m2_animation_resource_finalizer.gd` | Polling/finalization/boundary/timing regression |
+
+## Related decisions and references
+
+- [`m2-animation-load-pipeline-state.md`](m2-animation-load-pipeline-state.md)
+- [`m2-animated-scene-finalizer.md`](m2-animated-scene-finalizer.md)
+- [`m2-cached-animation-resource-observer.md`](m2-cached-animation-resource-observer.md)
+- [`m2-prototype-cache-state.md`](m2-prototype-cache-state.md)
+- [`world-renderer.md`](world-renderer.md)
+- [`../../RENDER.md`](../../RENDER.md)
+- [`../../targets/roadmap/02-rendering-and-graphics.md`](../../targets/roadmap/02-rendering-and-graphics.md)

docs/modules/m2-cached-animation-resource-observer.md

@@ -151,8 +151,9 @@ flowchart TB
 - Snapshot borrows the exact cached prototype; observer never frees it.
 - Resource existence/request and synchronous GLB JSON inspection run on the
   renderer main thread, matching the previous loader behavior.
-- The sibling native observer owns the native build attempt. Loader remains owner
-  of terminal polling/finalize, permits, materialization and SceneTree mutation.
+- The sibling native observer owns the native build attempt and the animation
+  resource finalizer owns terminal polling/finalize. Loader retains permits,
+  material lookup, materialization and SceneTree mutation.
 
 ## Errors, cancellation and recovery
 
@@ -197,9 +198,8 @@ queue and hitch metrics are unchanged.
 
 ## Extension points
 
-Native animation observation can become a sibling service without changing this
-cached-GLB contract. Terminal ResourceLoader polling/finalization may later move
-behind a dedicated adapter while retaining the pipeline state.
+Native and cached observation remain sibling services. Terminal ResourceLoader
+polling/finalization uses the dedicated finalizer while retaining pipeline state.
 
 ## Capability status
 
@@ -207,7 +207,7 @@ behind a dedicated adapter while retaining the pipeline state.
 |---|---|---|---|
 | Cached animation observation/request | Implemented extraction | Lifecycle/policy/GLB/source/timing verifier | Asset-backed traversal pending |
 | Native animation observation | Implemented sibling extraction | Native observer lifecycle/source verifier | Asset-backed traversal pending |
-| Animated finalize/preparation | Loader/finalizer split | Pipeline/finalizer regressions | Polling adapter optional |
+| Animated finalize/preparation | Implemented finalizer extraction | Pipeline/finalizer regressions | Asset-backed traversal pending |
 
 ## Known gaps and risks
 
@@ -224,6 +224,7 @@ behind a dedicated adapter while retaining the pipeline state.
 | `src/render/m2/m2_cached_animation_resource_observer.gd` | Cached GLB policy, request and snapshot production |
 | `src/render/m2/m2_build_resource_snapshot.gd` | Typed per-step observation value |
 | `src/render/m2/m2_animation_load_pipeline_state.gd` | Pending request/finalize state |
+| `src/render/m2/m2_animation_resource_finalizer.gd` | Terminal polling/load/finalize outcomes |
 | `src/render/m2/m2_prototype_cache_state.gd` | Prototype and static-only outcomes |
 | `src/render/m2/m2_native_animation_resource_observer.gd` | Native-first candidate/read/build/cache observation |
 | `src/scenes/streaming/streaming_world_loader.gd` | Composition, fallback order, finalize and execution |

docs/modules/m2-prototype-cache-state.md

@@ -64,7 +64,7 @@ Mesh traversal and other application layers are forbidden.
 | Input | Normalized non-empty M2 path | Loader normalization | Cache state | Copied String key | Shutdown lifetime |
 | Input | Detached static Node3D | Cached scene/raw builder adapter | Cache state | Adopted on success | Until final shutdown |
 | Input | Detached animated Node3D | GLB/native animation adapter | Cache state | Adopted on success | Until final shutdown |
-| Input | Missing/static-only outcome | Loader/observer failure adapter | Cache state | Boolean set entry | Until final shutdown |
+| Input | Missing/static-only outcome | Resource observers/finalizers | Cache state | Boolean set entry | Until final shutdown |
 | Output | Canonical prototype Node3D | Cache state | Loader instance/material adapter | Borrowed exact reference | One lookup/use |
 | Output | Detached path-only snapshot | Cache state | Tests/diagnostics | Fresh caller-owned arrays | One query |
 
@@ -192,7 +192,8 @@ and native M2 formats are unchanged; no migration or rebake is introduced.
 
 - `diagnostic_snapshot` exposes four sorted path arrays without Node references.
 - Cached eligibility rejection logging belongs to the cached observer; native
-  animation success logging belongs to the native observer.
+  success logging belongs to the native observer and cached terminal success
+  logging belongs to the animation resource finalizer.
 - Existing renderer queue metrics remain unchanged because these tables never
   contributed work counts.
 - Normalized relative path remains the correlation key.
@@ -238,6 +239,7 @@ this state without moving ResourceLoader or builder ownership into cache state.
 |---|---|
 | `src/render/m2/m2_prototype_cache_state.gd` | Positive Node ownership, negative path state and shutdown release |
 | `src/render/m2/m2_native_animation_resource_observer.gd` | Animated raw/build and positive/static-only transitions |
+| `src/render/m2/m2_animation_resource_finalizer.gd` | Cached terminal positive/static-only transitions |
 | `src/scenes/streaming/streaming_world_loader.gd` | Normalization, observer order, remaining I/O/fallback adapters |
 | `src/tools/verify_m2_prototype_cache_state.gd` | Admission/identity/lifecycle/source/timing regression |
 | `src/tools/verify_render_runtime_cache_shutdown.gd` | Integrated final-shutdown release regression |

docs/modules/world-renderer.md

@@ -148,6 +148,7 @@ from externally reading/writing loader-private queue, task, cache and tile-state
 | `M2StaticBatchMaterializer.materialize_batch` | Internal M2 scene-materialization service | Builds and attaches one prepared-Mesh MultiMesh transform slice | Renderer main thread; stateless after each call | Invalid/empty input returns null; bounds are caller precondition |
 | `M2RuntimeMeshRebuildClassifier` | Internal memoized M2 service | Detects billboard/UV-rotation metadata requiring stale cached-mesh rebuild | Renderer main thread; cached until reset | Invalid variants/indices skipped; first path decision wins |
 | `M2AnimationLoadPipelineState` | Internal M2 async-state service | Owns animated scene pending request records and terminal finalize FIFO | Renderer main thread; map/session | Empty/duplicate/unknown transitions rejected |
+| `M2AnimationResourceFinalizer` | Internal M2 terminal-I/O service | Polls cached animation requests, loads/finalizes scenes and publishes prototype outcome | Renderer main thread; stateless across calls | Invalid/failed candidates mark static-only |
 | `M2AnimatedSceneFinalizer` | Internal M2 scene-finalization service | Instantiates candidates, repairs materials and requires AnimationPlayer descendants | Renderer main thread; stateless after each call | Invalid/rejected detached roots are freed |
 | `M2AnimationPlaybackController` | Internal M2 playback service | Applies stable phase, default imported animation and native animator startup | Renderer main thread; stateless after each call | Missing inventories/names no-op through historical fallbacks |
 | `M2AnimatedInstanceMaterializer` | Internal M2 scene-materialization service | Duplicates ordered animated instances, applies render settings, starts playback and attaches a non-empty batch | Renderer main thread; stateless after each call | Invalid/empty input or all failed duplicates returns empty |
@@ -432,7 +433,8 @@ sequenceDiagram
   terminal statuses and completion-order finalize FIFO. The cached animation
   observer owns allow/deny/path/GLB selection, request admission and initial
   snapshot production. The native observer owns synchronous native build; the
-  loader retains ResourceLoader polling/finalize, permits and terminal adoption.
+  animation resource finalizer owns cached terminal polling/load/finalize and
+  adoption. Loader retains permits and material-prototype lookup.
 - `M2MeshResourceCacheState` owns prepared static Mesh references and releases
   them at the existing final-shutdown site. Prototype state and materialization
   belong to the sibling cache service and loader respectively.
@@ -595,8 +597,9 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
 | M2 build dispatch planner | Implemented extraction | Scene-free priority/action/transition/source/timing contract | Resource observation/orchestration and asset-backed traversal remain pending |
 | M2 build resource snapshot | Implemented extraction | Typed identity/adoption/lifetime/source/timing contract | Resource observation service and asset-backed traversal remain pending |
 | M2 static build resource observer | Implemented extraction | Cache/pending/path/request/source/timing contract | Asset-backed traversal and finalize extraction pending |
-| M2 cached animation resource observer | Implemented extraction | Cache/pending/policy/GLB/request/source/timing contract | Asset-backed traversal and terminal polling extraction pending |
+| M2 cached animation resource observer | Implemented extraction | Cache/pending/policy/GLB/request/source/timing contract | Asset-backed traversal pending |
 | M2 native animation resource observer | Implemented extraction | Candidate/cache/raw/build/adoption/source/timing contract | Asset-backed traversal/leak/p95/p99 pending |
+| M2 animation resource finalizer | Implemented extraction | Status/FIFO/load/candidate/repair/adoption/source/timing contract | Asset-backed traversal/leak/p95/p99 pending |
 | M2 build queue | Implemented extraction | Typed lifecycle/FIFO/progress/lifetime/source/timing contract | Resource dispatch and asset-backed traversal remain pending |
 | M2 animation load pipeline state | Implemented extraction | Synthetic lifecycle/FIFO/source/timing contract | Asset-backed traversal/leak/animation-fidelity/p95/p99 pending |
 | M2 animated scene finalizer | Implemented extraction | Synthetic type/lifetime/material/player/source/timing contract | Asset-backed GLB traversal/material/animation comparison pending |
@@ -664,6 +667,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
 | `src/render/liquid/adt_water_scene_finalizer.gd` | Main-thread ADT water build, tile attachment and optional editor ownership |
 | `src/render/m2/m2_runtime_mesh_rebuild_classifier.gd` | Billboard/UV-rotation stale cached-mesh rebuild decision and memoization |
 | `src/render/m2/m2_animation_load_pipeline_state.gd` | Animated M2 pending Resource paths, terminal statuses and finalize FIFO |
+| `src/render/m2/m2_animation_resource_finalizer.gd` | Cached animation terminal polling/load/finalize outcomes |
 | `src/render/m2/m2_animated_scene_finalizer.gd` | Animated scene candidate ownership, material repair and player validation |
 | `src/render/m2/m2_animation_playback_controller.gd` | Per-instance phase, selection, native copy/start and imported playback |
 | `src/render/m2/m2_animated_instance_materializer.gd` | Animated duplicate/render/playback startup and non-empty batch attachment |
@@ -697,6 +701,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
 | `src/tools/verify_adt_water_scene_finalizer.gd` | Synthetic ADT water scene/ownership/boundary/timing regression |
 | `src/tools/verify_m2_runtime_mesh_rebuild_classifier.gd` | M2 rebuild predicate/cache/boundary/timing regression |
 | `src/tools/verify_m2_animation_load_pipeline_state.gd` | Animated M2 request/terminal/FIFO/boundary/timing regression |
+| `src/tools/verify_m2_animation_resource_finalizer.gd` | Animated M2 polling/load/finalize/adoption/boundary/timing regression |
 | `src/tools/verify_m2_animated_scene_finalizer.gd` | Animated M2 candidate/material/player/lifetime/boundary/timing regression |
 | `src/tools/verify_m2_animation_playback_controller.gd` | Animated M2 phase/selection/playback/native/boundary/timing regression |
 | `src/tools/verify_m2_animated_instance_materializer.gd` | Animated M2 order/render/playback/attachment/boundary/timing regression |