render: extract cached M2 animation resource observer

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

@@ -14,9 +14,10 @@
 
 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; animation eligibility and loading remain in
-`StreamingWorldLoader`, while scene finalization and retained Node lifecycle
-belong to `M2AnimatedSceneFinalizer` and `M2PrototypeCacheState`.
+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`.
 
 ## Non-goals
 
@@ -29,8 +30,10 @@ belong to `M2AnimatedSceneFinalizer` and `M2PrototypeCacheState`.
 
 ```mermaid
 flowchart LR
-    Loader[StreamingWorldLoader] --> IO[ResourceLoader]
-    Loader --> State[M2AnimationLoadPipelineState]
+    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
@@ -100,12 +103,13 @@ stateDiagram-v2
 
 ```mermaid
 sequenceDiagram
+    participant O as CachedAnimationObserver
     participant L as StreamingWorldLoader
     participant R as ResourceLoader
     participant S as M2AnimationLoadPipelineState
     participant P as M2PrototypeCacheState
-    L->>R: load_threaded_request(GLB)
-    L->>S: remember_request(path, GLB)
+    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)
@@ -128,8 +132,10 @@ sequenceDiagram
 
 ```mermaid
 flowchart TB
+    Observer[M2CachedAnimationResourceObserver] --> State[M2AnimationLoadPipelineState]
+    Observer --> Resource[ResourceLoader request]
     Loader[StreamingWorldLoader] --> State[M2AnimationLoadPipelineState]
-    Loader --> Resource[ResourceLoader]
+    Loader --> Resource
     Loader --> Budget[RenderBudgetScheduler]
     Loader --> Prototype[M2PrototypeCacheState]
     State -. no dependency .-> Resource
@@ -142,7 +148,7 @@ flowchart TB
 | Failure | Detection | Behavior | Diagnostic | Recovery |
 |---|---|---|---|---|
 | Empty/duplicate request | State guard | Reject unchanged | Contract verifier | Correct caller or request later |
-| Request start/cache miss | Loader | No insertion; mark static | Existing loader path | Cache correction/reload |
+| Request start/cache miss | Cached observer | No insertion; mark static | Observer contract | Cache correction/reload |
 | Non-terminal status | Loader | Keep pending | Existing metric | Poll next frame |
 | Failed terminal load | Popped status | Loader marks static | Existing behavior | Future map/session reload |
 | Empty defensive path | Loader poll | Discard and mark static | Source contract | Correct producer |
@@ -154,7 +160,7 @@ flowchart TB
 |---|---|---|---|---|
 | `enable_m2_animated_instances` | `true` | Existing renderer profile | Yes | Enables caller request path |
 | `m2_animation_finalize_ops_per_tick` | `1` | Quality/custom | Yes | Bounds caller FIFO drain |
-| Animated allow/deny/primitive rules | Existing values | Existing renderer profile | Yes | Filter before state insertion |
+| Animated allow/deny/primitive rules | Existing values | Existing renderer profile | Yes | Observer filters before state insertion |
 
 ## Persistence, cache and migration
 
@@ -188,7 +194,8 @@ sibling service.
 | Capability | Status | Evidence | Gap/next step |
 |---|---|---|---|
 | Animated request/finalize state | Implemented extraction | Synthetic contract/source/timing verifier | Asset-backed traversal/leak/p95/p99 pending |
-| ResourceLoader and GLB selection | Existing loader-owned | Adjacent renderer tests | I/O adapter extraction optional |
+| 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 |
 | Animated prototype outcomes | Implemented extraction | Prototype cache verifier | Asset-backed animation fidelity pending |
 
 ## Known gaps and risks
@@ -202,9 +209,10 @@ sibling service.
 | Path | Responsibility |
 |---|---|
 | `src/render/m2/m2_animation_load_pipeline_state.gd` | Pending records, completion FIFO and metrics |
+| `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` | Eligibility, I/O, permits, instantiation and adoption |
+| `src/scenes/streaming/streaming_world_loader.gd` | Native eligibility/build, polling, permits and adoption |
 | `src/tools/verify_m2_animation_load_pipeline_state.gd` | Lifecycle/boundary/timing regression |
 
 ## Related decisions and references