render: extract M2 Mesh resource finalizer

docs/modules/README.md

@@ -37,6 +37,7 @@
 | 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) |
+| M2 mesh resource finalizer | Implemented extraction | [`m2-mesh-resource-finalizer.md`](m2-mesh-resource-finalizer.md) |
 | M2 runtime mesh finalizer | Implemented extraction | [`m2-runtime-mesh-finalizer.md`](m2-runtime-mesh-finalizer.md) |
 | M2 raw model repository | Implemented extraction | [`m2-raw-model-repository.md`](m2-raw-model-repository.md) |
 | M2 prototype cache state | Implemented extraction | [`m2-prototype-cache-state.md`](m2-prototype-cache-state.md) |

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

@@ -78,7 +78,7 @@ Side effects are limited to collection mutation and retaining String/integer val
 flowchart TD
     Start[Successful ResourceLoader request] --> Remember[remember request]
     Remember --> Snapshot[request records snapshot]
-    Snapshot --> Poll[Loader polls status]
+    Snapshot --> Poll[Mesh resource finalizer polls status]
     Poll --> Active{In progress?}
     Active -->|yes| Snapshot
     Active -->|no| Complete[complete request with terminal status]
@@ -86,7 +86,7 @@ flowchart TD
     FIFO --> Permit{Loader permit available?}
     Permit -->|no| FIFO
     Permit -->|yes| Pop[Pop oldest terminal record]
-    Pop --> Finalize[Loader gets Resource and delegates first-Mesh extraction]
+    Pop --> Finalize[Mesh resource finalizer gets Resource and extracts first Mesh]
     Finalize --> Prepare[M2RuntimeMeshFinalizer prepares Mesh]
     Prepare --> Adopt[Loader adopts Mesh or marks prototype outcome state]
 ```
@@ -113,6 +113,7 @@ again only if loader cache/missing rules permit it.
 ```mermaid
 sequenceDiagram
     participant Loader as StreamingWorldLoader
+    participant Finalizer as M2MeshResourceFinalizer
     participant Resource as ResourceLoader
     participant State as M2MeshLoadPipelineState
     participant Budget as RenderBudgetScheduler
@@ -120,14 +121,16 @@ sequenceDiagram
     Resource-->>Loader: OK or ERR_BUSY
     Loader->>State: remember_request(normalized, cache path)
     loop frames
-        Loader->>State: request_records_snapshot()
-        Loader->>Resource: load_threaded_get_status(path)
+        Loader->>Finalizer: poll_terminal_requests(state, prototype cache)
+        Finalizer->>State: request_records_snapshot()
+        Finalizer->>Resource: load_threaded_get_status(path)
     end
-    Loader->>State: complete_request(normalized, terminal status)
+    Finalizer->>State: complete_request(normalized, terminal status)
     Loader->>Budget: try_consume_permit(M2_MESH_FINALIZE)
-    Loader->>State: pop_finalize_record()
-    Loader->>Resource: load_threaded_get(path)
-    Loader->>Loader: extract/refresh/adopt Mesh or mark missing
+    Loader->>Finalizer: finalize_next_resource(state, caches, directory)
+    Finalizer->>State: pop_finalize_record()
+    Finalizer->>Resource: load_threaded_get(path)
+    Finalizer->>Finalizer: extract/refresh/adopt Mesh or mark missing
 ```
 
 ## Dependency diagram
@@ -135,7 +138,9 @@ sequenceDiagram
 ```mermaid
 flowchart TB
     Loader[StreamingWorldLoader] --> State[M2MeshLoadPipelineState]
-    Loader --> Resource[ResourceLoader]
+    Loader --> MeshFinalizer[M2MeshResourceFinalizer]
+    MeshFinalizer --> State
+    MeshFinalizer --> Resource[ResourceLoader]
     Loader --> Budget[RenderBudgetScheduler]
     Loader --> MeshCache[M2 Mesh resource and prototype outcome cache states]
     Loader --> Finalizer[M2RuntimeMeshFinalizer]
@@ -148,7 +153,9 @@ flowchart TB
 
 - Main thread serializes all state mutation and snapshots.
 - State owns only request/finalize Dictionaries containing Strings and status integers.
-- Loader owns ResourceLoader request lifetime and drains active paths before shutdown clear.
+- `M2MeshResourceFinalizer` owns terminal status polling, terminal Resource
+  retrieval, first-Mesh extraction, runtime preparation and cache/missing adoption.
+- Loader owns request admission, scheduler permits and shutdown drain ordering.
 - `M2MeshResourceCacheState` owns prepared static Mesh references and
   `M2RuntimeMeshFinalizer` owns refresh/rebuild/fallback. The loader owns shared
   adoption decisions, raw I/O and remaining engine resources; the prototype
@@ -161,9 +168,9 @@ flowchart TB
 |---|---|---|---|---|
 | Empty/duplicate request | State guard | Reject unchanged | Contract verifier | Correct caller/request later |
 | Request start failure | Loader return code | No state insert; mark missing | Existing loader behavior | Cache/source correction |
-| Non-terminal status | Loader poll | Keep pending | Existing queue metric | Poll next frame |
-| Terminal load failure | Status in popped record | Loader marks missing | Existing missing behavior | World/cache reload |
-| Empty defensive path | Loader before poll | Discard and mark missing | Source regression | Correct request producer |
+| Non-terminal status | Finalizer poll | Keep pending | Existing queue metric | Poll next frame |
+| Terminal load failure | Status in popped record | Finalizer marks missing | Existing missing behavior | World/cache reload |
+| Empty defensive path | Finalizer before poll | Discard and mark missing | Source regression | Correct request producer |
 | Shutdown | Loader drains pending Resource paths | Clear state | Shutdown verifier | New loader starts empty |
 
 ## Configuration and capabilities
@@ -207,7 +214,7 @@ rebuild policy are unchanged; no migration or rebake is required.
 |---|---|---|---|
 | Static M2 request/finalize state | Implemented extraction | Contract/source/timing verifier | Asset-backed long traversal pending |
 | Static request admission I/O | Implemented in observer | Observer/shutdown regressions | Asset-backed traversal pending |
-| Static request polling/finalize I/O | Existing loader-owned | Shutdown/material regressions | Finalize extraction optional |
+| Static request polling/finalize I/O | Implemented extraction | Finalizer contract/source/timing verifier | Asset-backed traversal pending |
 | Mesh cache | Implemented extraction | Mesh resource cache state verifier | Asset-backed memory/leak run pending |
 | First-Mesh extraction | Implemented extraction | Resource/order/lifetime verifier | Asset-backed corrupt-scene fixture pending |
 | Mesh preparation | Implemented extraction | Runtime finalizer transition/rebuild verifier | Asset-backed material comparison pending |
@@ -225,11 +232,12 @@ rebuild policy are unchanged; no migration or rebake is required.
 | Path | Responsibility |
 |---|---|
 | `src/render/m2/m2_mesh_load_pipeline_state.gd` | Pending records, terminal FIFO and metrics |
+| `src/render/m2/m2_mesh_resource_finalizer.gd` | Terminal polling, Resource extraction, preparation and adoption |
 | `src/render/m2/m2_mesh_resource_cache_state.gd` | Prepared static Mesh references and final clear |
 | `src/render/m2/m2_mesh_resource_extractor.gd` | First-Mesh selection and temporary PackedScene lifetime |
 | `src/render/m2/m2_runtime_mesh_finalizer.gd` | Refresh/rebuild/fallback preparation |
 | `src/render/m2/m2_prototype_cache_state.gd` | Missing-model outcome retention |
-| `src/scenes/streaming/streaming_world_loader.gd` | Cache path choice, I/O polling, permits and adoption decisions |
+| `src/scenes/streaming/streaming_world_loader.gd` | Cache path choice, request admission, permits and composition |
 | `src/render/m2/m2_runtime_mesh_rebuild_classifier.gd` | Downstream stale Mesh rebuild decision |
 | `src/tools/verify_m2_mesh_load_pipeline_state.gd` | Lifecycle/boundary/timing regression |
 

docs/modules/m2-mesh-resource-cache-state.md

@@ -103,9 +103,9 @@ sequenceDiagram
     participant Pipeline as M2MeshLoadPipelineState
     Loader->>Cache: find/has normalized path
     alt cache miss
-        Loader->>Pipeline: request/poll/finalize record
-        Loader->>Loader: ResourceLoader get; delegate extract + prepare
-        Loader->>Cache: store_mesh(path, prepared Mesh)
+        Loader->>Pipeline: request record
+        Loader->>Finalizer: poll/finalize one permitted record
+        Finalizer->>Cache: store_mesh(path, prepared Mesh)
     end
     Cache-->>Loader: exact retained Mesh
     Loader->>Loader: materialize static M2 batch
@@ -133,8 +133,9 @@ flowchart TB
 - Borrowed Mesh lookups do not transfer ownership or duplicate resources.
 - `M2MeshResourceExtractor` owns first-Mesh selection and temporary PackedScene
   instances. `M2PrototypeCacheState` owns missing/prototype/animated state; the
-  static materializer owns MultiMesh construction/attachment; the loader owns
-  resource adoption and build-job decisions.
+  static materializer owns MultiMesh construction/attachment;
+  `M2MeshResourceFinalizer` owns resource adoption, while the loader owns
+  build-job and scheduler-permit decisions.
 - The loader drains asynchronous work before the final cache clear.
 
 ## Errors, cancellation and recovery
@@ -186,7 +187,7 @@ the historical Mesh cache had no queue contribution or log site.
 | Capability | Status | Evidence | Gap/next step |
 |---|---|---|---|
 | Prepared static M2 Mesh cache | Implemented extraction | Contract/source/timing verifier | Asset-backed memory/leak run pending |
-| M2 Mesh request lifecycle | Implemented extraction | Pipeline state verifier | Finalize polling remains loader-owned |
+| M2 Mesh request lifecycle | Implemented extraction | Pipeline/finalizer verifiers | Asset-backed traversal pending |
 | M2 Mesh extraction | Implemented extraction | Resource/order/lifetime verifier | Asset-backed corrupt-scene fixture pending |
 | M2 Mesh preparation | Implemented extraction | Runtime finalizer transition/rebuild verifier | Asset-backed material comparison pending |
 
@@ -203,8 +204,9 @@ the historical Mesh cache had no queue contribution or log site.
 |---|---|
 | `src/render/m2/m2_mesh_resource_cache_state.gd` | Prepared Mesh references and final clear |
 | `src/render/m2/m2_mesh_resource_extractor.gd` | First-Mesh selection and temporary PackedScene lifetime |
+| `src/render/m2/m2_mesh_resource_finalizer.gd` | Prepared Mesh producer and cache adoption |
 | `src/render/m2/m2_prototype_cache_state.gd` | Prototype references and negative lookup outcomes |
-| `src/scenes/streaming/streaming_world_loader.gd` | Normalization, raw/resource I/O and materialization |
+| `src/scenes/streaming/streaming_world_loader.gd` | Normalization, request admission, permits and materialization |
 | `src/render/m2/m2_runtime_mesh_finalizer.gd` | Refresh/rebuild/fallback preparation |
 | `src/render/m2/m2_mesh_load_pipeline_state.gd` | Pending request and terminal finalize records |
 | `src/tools/verify_m2_mesh_resource_cache_state.gd` | Cache ownership/lifetime/boundary/timing regression |

docs/modules/m2-mesh-resource-extractor.md

@@ -92,27 +92,27 @@ No state or Resource reference is retained between calls.
 
 ```mermaid
 sequenceDiagram
-    participant Loader as StreamingWorldLoader
+    participant Finalizer as M2MeshResourceFinalizer
     participant Extractor as M2MeshResourceExtractor
     participant Scene as PackedScene
-    Loader->>Extractor: extract_first_mesh(loaded Resource)
+    Finalizer->>Extractor: extract_first_mesh(loaded Resource)
     alt direct Mesh
-        Extractor-->>Loader: same Mesh reference
+        Extractor-->>Finalizer: same Mesh reference
     else PackedScene
         Extractor->>Scene: instantiate()
         Scene-->>Extractor: temporary root
         Extractor->>Extractor: depth-first first-Mesh search
         Extractor->>Extractor: temporary_root.free()
-        Extractor-->>Loader: Mesh or null
+        Extractor-->>Finalizer: Mesh or null
     end
-    Loader->>Loader: prepare and cache Mesh or mark missing
+    Finalizer->>Finalizer: prepare and cache Mesh or mark missing
 ```
 
 ## Dependency diagram
 
 ```mermaid
 flowchart TB
-    Loader[StreamingWorldLoader] --> Extractor[M2MeshResourceExtractor]
+    Finalizer[M2MeshResourceFinalizer] --> Extractor[M2MeshResourceExtractor]
     Extractor --> Types[Resource / PackedScene / Node / Mesh]
     Loader --> Pipeline[M2MeshLoadPipelineState]
     Loader --> Cache[M2MeshResourceCacheState]
@@ -168,8 +168,8 @@ normalized M2 path. Its verifier measures traversal time and temporary Node coun
 
 ## Extension points
 
-- `M2RuntimeMeshFinalizer` consumes the Mesh returned here and the loader stores
-  its result in `M2MeshResourceCacheState`.
+- `M2MeshResourceFinalizer` passes the Mesh to `M2RuntimeMeshFinalizer` and
+  stores its result in `M2MeshResourceCacheState`.
 - Broader generic scene traversal is intentionally excluded until another real
   consumer requires the same exact contract.
 
@@ -194,8 +194,9 @@ normalized M2 path. Its verifier measures traversal time and temporary Node coun
 | Path | Responsibility |
 |---|---|
 | `src/render/m2/m2_mesh_resource_extractor.gd` | First-Mesh traversal and temporary PackedScene lifetime |
+| `src/render/m2/m2_mesh_resource_finalizer.gd` | Terminal Resource consumer and extraction caller |
 | `src/render/m2/m2_prototype_cache_state.gd` | Prototype and missing/static-only lookup state |
-| `src/scenes/streaming/streaming_world_loader.gd` | ResourceLoader/raw I/O, cache decisions and materialization |
+| `src/scenes/streaming/streaming_world_loader.gd` | Request admission, permits and materialization |
 | `src/render/m2/m2_runtime_mesh_finalizer.gd` | Refresh/rebuild/fallback preparation |
 | `src/render/m2/m2_mesh_resource_cache_state.gd` | Prepared Mesh retention |
 | `src/tools/verify_m2_mesh_resource_extractor.gd` | Resource/order/lifetime/boundary/timing regression |

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

@@ -0,0 +1,251 @@
+# M2 Mesh Resource Finalizer
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Status | Implemented extraction |
+| Target/work package | M03 / `M03-RND-M2-MESH-RESOURCE-FINALIZER-001` |
+| Owners | Static M2 terminal Resource I/O, Mesh preparation and cache outcome |
+| Last verified | Worktree `work/sindo-main-codex/m03-m2-mesh-resource-finalizer`, 2026-07-18 |
+| Profiles/capabilities | Existing cached/static MultiMesh M2 path |
+
+## Purpose
+
+Drain static M2 ResourceLoader work and publish a prepared Mesh or missing-model
+outcome without keeping terminal I/O and refresh logic in `StreamingWorldLoader`.
+The same preparation method serves threaded and synchronous Mesh consumers.
+
+## Non-goals
+
+- Select cache candidates or admit threaded ResourceLoader requests.
+- Own scheduler permits, prototype Nodes, MultiMeshes or SceneTree roots.
+- Change first-Mesh traversal, refresh version, rebuild rules or raw parser.
+- Merge static and animated terminal services through callbacks/frameworks.
+- Change cache formats, profiles or visible output.
+
+## Context and boundaries
+
+```mermaid
+flowchart LR
+    Observer[M2StaticBuildResourceObserver] --> Pipeline[M2MeshLoadPipelineState]
+    Loader[StreamingWorldLoader] --> Finalizer[M2MeshResourceFinalizer]
+    Pipeline --> Finalizer
+    ResourceLoader --> Finalizer
+    Finalizer --> Extractor[M2MeshResourceExtractor]
+    Finalizer --> Runtime[M2RuntimeMeshFinalizer]
+    Finalizer --> Raw[M2RawModelRepository]
+    Finalizer --> MeshCache[M2MeshResourceCacheState]
+    Finalizer --> Prototype[M2PrototypeCacheState]
+```
+
+## Public API
+
+| Symbol | Kind | Purpose | Failure behavior |
+|---|---|---|---|
+| `poll_terminal_requests(pipeline, prototype_cache)` | I/O command | Move LOADED/FAILED records into completion FIFO | Invalid composition returns zero |
+| `finalize_next_resource(pipeline, mesh_cache, prototype_cache, extracted_dir)` | I/O command | Pop one record and publish Mesh/missing outcome | Empty/invalid composition returns false |
+| `prepare_mesh_for_runtime(path, mesh, extracted_dir)` | I/O preparation | Preserve current Mesh or load raw data and refresh stale Mesh | Null 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 | Mesh pipeline | Finalizer | Pipeline-owned copied Dictionaries |
+| Input | Terminal Resource | ResourceLoader | Mesh extractor | Borrowed one operation |
+| Input | Extracted/cached Mesh | Mesh extractor/loader consumer | Runtime preparation | Borrowed Resource reference |
+| Input | Raw M2 Dictionary | Raw repository | Runtime finalizer | Call-local value |
+| Output | Prepared Mesh | Runtime finalizer | Mesh cache/loader consumer | Resource reference |
+| Output | Missing-model outcome | Finalizer | Prototype cache | Copied path; loader session |
+| Output | Processed-record flag | Finalizer | Loader permit loop/tests | Boolean value |
+
+## Data flow
+
+```mermaid
+flowchart TD
+    Poll[Poll pending records in insertion order] --> Path{Resource path empty?}
+    Path -->|yes| Discard[Discard and mark missing]
+    Path -->|no| Status{LOADED or FAILED?}
+    Status -->|no| Pending[Keep pending]
+    Status -->|yes| Complete[Append completion FIFO]
+    Complete --> Permit[Loader consumes M2_MESH_FINALIZE permit]
+    Permit --> Pop[Pop oldest terminal record]
+    Pop --> Cached{Empty path or Mesh cached?}
+    Cached -->|yes| Skip[Finish one permit operation]
+    Cached -->|no| Loaded{Status LOADED?}
+    Loaded -->|no| Missing[Mark model missing]
+    Loaded -->|yes| Get[Get terminal Resource]
+    Get --> Extract[Extract first Mesh]
+    Extract --> Found{Mesh found?}
+    Found -->|no| Missing
+    Found -->|yes| Current{Refresh version current?}
+    Current -->|yes| Store[Store exact Mesh]
+    Current -->|no| Raw[Read raw M2 data]
+    Raw --> Refresh[Finalize/rebuild/fallback Mesh]
+    Refresh --> Store
+```
+
+## Lifecycle/state
+
+```mermaid
+stateDiagram-v2
+    [*] --> Polling
+    Polling --> Pending: nonterminal status
+    Polling --> TerminalQueued: LOADED or FAILED
+    Polling --> Missing: empty Resource path
+    TerminalQueued --> Skipped: empty/cached record
+    TerminalQueued --> Missing: failed load or no Mesh
+    TerminalQueued --> Extracted: Mesh found
+    Extracted --> Current: refresh version current
+    Extracted --> Refreshing: stale Mesh
+    Refreshing --> Prepared: rebuild or fallback
+    Current --> Cached
+    Prepared --> Cached
+    Pending --> [*]
+    Skipped --> [*]
+    Missing --> [*]
+    Cached --> [*]
+```
+
+## Main sequence
+
+```mermaid
+sequenceDiagram
+    participant L as StreamingWorldLoader
+    participant F as M2MeshResourceFinalizer
+    participant P as M2MeshLoadPipelineState
+    participant R as ResourceLoader
+    participant E as M2MeshResourceExtractor
+    participant N as M2RuntimeMeshFinalizer
+    participant C as M2MeshResourceCacheState
+    L->>F: poll_terminal_requests(P, prototype cache)
+    F->>R: load_threaded_get_status(path)
+    F->>P: complete terminal request
+    L->>L: consume M2_MESH_FINALIZE permit
+    L->>F: finalize_next_resource(...)
+    F->>P: pop oldest record
+    F->>R: load_threaded_get(path)
+    F->>E: extract_first_mesh(Resource)
+    F->>N: requires_raw_data_for_refresh(Mesh)
+    opt stale Mesh
+        F->>F: read raw M2 data
+        F->>N: finalize_mesh(...)
+    end
+    F->>C: store prepared Mesh
+```
+
+## Dependency diagram
+
+```mermaid
+flowchart TB
+    Finalizer[M2MeshResourceFinalizer] --> ResourceLoader
+    Finalizer --> Pipeline[M2MeshLoadPipelineState]
+    Finalizer --> Extractor[M2MeshResourceExtractor]
+    Finalizer --> Runtime[M2RuntimeMeshFinalizer]
+    Finalizer --> Raw[M2RawModelRepository]
+    Finalizer --> MeshCache[M2MeshResourceCacheState]
+    Finalizer --> Prototype[M2PrototypeCacheState]
+    Loader[StreamingWorldLoader] --> Finalizer
+    Loader --> Scheduler[RenderBudgetScheduler]
+    Finalizer -. no dependency .-> Scheduler
+    Finalizer -. no dependency .-> MultiMesh
+    Finalizer -. no dependency .-> SceneTree
+```
+
+## Ownership, threading and resources
+
+- All operations run synchronously on the renderer main thread.
+- Pipeline owns pending/completion records; one permit pops one terminal record.
+- Extractor owns temporary PackedScene instance cleanup and returns a Mesh reference.
+- Runtime finalizer owns stale/current/rebuild/fallback rules; raw repository owns
+  only call-local native I/O.
+- Mesh cache retains prepared Mesh references until final shutdown; prototype
+  cache retains missing-model paths.
+- Service retains dependency references but no pending record, Resource, Mesh or
+  raw Dictionary between calls. Loader retains permits and materialization.
+
+## Errors, cancellation and recovery
+
+| Failure/state | Behavior | Recovery |
+|---|---|---|
+| Missing composition dependency | Return zero/false; preparation keeps Mesh where possible | Correct composition |
+| Empty Resource path | Discard request and mark missing | Repair cache and restart session |
+| Nonterminal status | Keep pending | Poll next tick |
+| FAILED status | Pop and mark missing | Repair cache and restart session |
+| Existing cached Mesh | Pop and skip terminal Resource get | None |
+| Null/unsupported/no-Mesh Resource | Mark missing | Repair imported cache |
+| Raw read/rebuild unavailable | Runtime finalizer marks/reuses original Mesh | Existing fallback |
+| Tile cancellation | Shared cache work continues | Loader queue remains authoritative |
+| Shutdown | Loader drains ResourceLoader before pipeline/cache clear | New loader starts empty |
+
+## Configuration and capabilities
+
+The service consumes the existing extracted directory. The scheduler retains
+`m2_mesh_finalize_ops_per_tick`; material refresh version remains `2`.
+
+## Persistence, cache and migration
+
+No cache path, schema or version changes are introduced. Existing `.tscn/.glb`
+Resources and in-memory refresh metadata remain compatible; no rebake is required.
+
+## Diagnostics and observability
+
+The service adds no log. Existing pending-plus-finalize metrics and refresh
+metadata remain unchanged. Normalized relative path remains the correlation key.
+
+## Verification
+
+- Dedicated verifier covers status insertion order, empty-path discard, FIFO,
+  failed/cached/null outcomes, terminal get, exact Mesh identity, stale-only raw
+  read, exact finalizer arguments, cache adoption, source ownership and timing.
+- Pipeline/cache/extractor/runtime-finalizer/raw-repository/prototype/shutdown,
+  facade, internal-access and baseline regressions protect adjacent behavior.
+- Fidelity evidence is exact lifecycle/I/O extraction only; no private asset,
+  original-client visual, leak-pressure or p95/p99 claim is made.
+
+## Extension points
+
+Further extraction can move static prototype/material-source construction without
+changing this terminal Resource contract. Animated finalization remains separate
+because its candidate-before-material ordering and Node ownership differ.
+
+## Capability status
+
+| Capability | Status | Evidence | Gap/next step |
+|---|---|---|---|
+| Static terminal polling/load | Implemented extraction | Status/FIFO/load/source verifier | Asset-backed traversal pending |
+| Mesh extraction/preparation/cache outcome | Implemented extraction | Identity/raw/finalizer/store verifier | Private leak/p95/p99 pending |
+| Static MultiMesh materialization | Separate implemented service | Materializer verifier | GPU/asset-backed evidence pending |
+
+## Known gaps and risks
+
+- Terminal Resource get, extraction and stale rebuild remain synchronous main-thread work.
+- Prepared Mesh cache remains unbounded until final shutdown.
+- Private asset traversal, descriptor pressure, leak and p95/p99 evidence is absent.
+
+## Source map
+
+| Path | Responsibility |
+|---|---|
+| `src/render/m2/m2_mesh_resource_finalizer.gd` | Poll/load/extract/prepare/cache/missing service |
+| `src/render/m2/m2_mesh_load_pipeline_state.gd` | Pending and completion FIFO ownership |
+| `src/render/m2/m2_mesh_resource_extractor.gd` | First-Mesh and temporary-instance ownership |
+| `src/render/m2/m2_runtime_mesh_finalizer.gd` | Refresh/rebuild/fallback rules |
+| `src/render/m2/m2_raw_model_repository.gd` | Optional native raw M2 boundary |
+| `src/render/m2/m2_mesh_resource_cache_state.gd` | Prepared Mesh ownership |
+| `src/render/m2/m2_prototype_cache_state.gd` | Missing-model outcome ownership |
+| `src/scenes/streaming/streaming_world_loader.gd` | Permit loop and materialization composition |
+| `src/tools/verify_m2_mesh_resource_finalizer.gd` | Polling/preparation/boundary/timing regression |
+
+## Related decisions and references
+
+- [`m2-mesh-load-pipeline-state.md`](m2-mesh-load-pipeline-state.md)
+- [`m2-mesh-resource-cache-state.md`](m2-mesh-resource-cache-state.md)
+- [`m2-mesh-resource-extractor.md`](m2-mesh-resource-extractor.md)
+- [`m2-runtime-mesh-finalizer.md`](m2-runtime-mesh-finalizer.md)
+- [`m2-raw-model-repository.md`](m2-raw-model-repository.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-prototype-cache-state.md

@@ -193,7 +193,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
   success logging belongs to the native observer and cached terminal success
-  logging belongs to the animation resource finalizer.
+  logging belongs to the animation resource finalizer. Static terminal missing
+  outcomes are produced by `M2MeshResourceFinalizer`.
 - Existing renderer queue metrics remain unchanged because these tables never
   contributed work counts.
 - Normalized relative path remains the correlation key.
@@ -240,6 +241,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/render/m2/m2_mesh_resource_finalizer.gd` | Static terminal missing 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/m2-raw-model-repository.md

@@ -27,11 +27,13 @@ static or animated Dictionary consumed by existing builders and classifiers.
 
 ```mermaid
 flowchart LR
-    Loader[StreamingWorldLoader] --> Repository[M2RawModelRepository]
+    MeshFinalizer[M2MeshResourceFinalizer] --> Repository[M2RawModelRepository]
+    Loader[StreamingWorldLoader] --> Repository
     Observer[M2NativeAnimationResourceObserver] --> Repository
     Repository --> File[Extracted M2 file]
     Repository --> Native[ClassDB M2Loader]
     Native --> Raw[Raw Dictionary]
+    Raw --> MeshFinalizer
     Raw --> Loader
     Raw --> Observer
     Loader --> Builder[Existing M2 builders/finalizer]
@@ -55,7 +57,7 @@ renderer policy and other application layers are forbidden.
 | Input | Extracted directory String | Loader configuration | Repository path resolution | Copied value | One call |
 | Input | Already-normalized relative M2 path String | Loader normalization | Repository | Copied value | One call |
 | Input | Extracted `.m2` bytes | Local legal extraction | Native M2Loader | File-owned | Native call |
-| Output | Static raw M2 Dictionary | Native `load_m2` | Loader/finalizer/M2Builder | Fresh native result | One caller operation |
+| Output | Static raw M2 Dictionary | Native `load_m2` | Mesh resource finalizer/M2Builder | Fresh native result | One caller operation |
 | Output | Animated raw M2 Dictionary | Native `load_m2_animated` | Native animation observer/builder | Fresh native result | One caller operation |
 | Output | Empty Dictionary | Repository guards | Loader fallback and prototype outcome adapter | Fresh value | One failed call |
 
@@ -136,8 +138,9 @@ flowchart TB
 ## Ownership, threading and resources
 
 - The repository owns only call-local path, native instance and result values.
-- The loader owns path normalization and fallback selection; the native observer
-  owns the animated raw-read/build decision;
+- The loader owns path normalization and fallback selection; the Mesh resource
+  finalizer owns static refresh reads, while the native observer owns the
+  animated raw-read/build decision;
   `M2PrototypeCacheState` owns prototype/negative adoption.
 - Native `M2Loader` owns parsing behavior and returns a new Dictionary value.
 - Calls are synchronous on the caller's thread; current renderer callers use the
@@ -215,6 +218,7 @@ measured work packages rather than expansion of this repository.
 | Path | Responsibility |
 |---|---|
 | `src/render/m2/m2_raw_model_repository.gd` | Stateless native class/file/method boundary |
+| `src/render/m2/m2_mesh_resource_finalizer.gd` | Static refresh repository consumer |
 | `src/render/m2/m2_native_animation_resource_observer.gd` | Animated raw-data consumer and builder adapter |
 | `src/render/m2/m2_prototype_cache_state.gd` | Prototype and negative-result retention |
 | `src/scenes/streaming/streaming_world_loader.gd` | Path normalization, fallback decisions and result consumers |

docs/modules/m2-runtime-mesh-finalizer.md

@@ -27,9 +27,8 @@ UV-rotation cases and returning the historical original-Mesh fallback.
 
 ```mermaid
 flowchart LR
-    Extractor[M2MeshResourceExtractor] --> Loader[StreamingWorldLoader]
-    Loader -->|is raw data required?| Finalizer[M2RuntimeMeshFinalizer]
-    Loader --> Raw[M2RawModelRepository]
+    ResourceFinalizer[M2MeshResourceFinalizer] -->|is raw data required?| Finalizer[M2RuntimeMeshFinalizer]
+    ResourceFinalizer --> Raw[M2RawModelRepository]
     Raw --> Finalizer
     Finalizer --> Classifier[M2RuntimeMeshRebuildClassifier]
     Finalizer --> Builder[M2Builder]
@@ -54,8 +53,8 @@ Nodes outside temporary rebuild roots and other application layers are forbidden
 
 | Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
 |---|---|---|---|---|---|
-| Input | Extracted Mesh and normalized M2 path | Loader/extractor adapter | Finalizer | Borrowed Mesh reference/String copy | One call |
-| Input | Already-loaded raw M2 Dictionary | `M2RawModelRepository` through loader adapter | Classifier/M2Builder | Caller-owned value container | One call |
+| Input | Extracted Mesh and normalized M2 path | Mesh resource finalizer | Finalizer | Borrowed Mesh reference/String copy | One call |
+| Input | Already-loaded raw M2 Dictionary | `M2RawModelRepository` through resource finalizer | Classifier/M2Builder | Caller-owned value container | One call |
 | Input | Extracted directory path | Loader configuration | M2Builder texture resolution | Copied String | One rebuild |
 | Output | Original or rebuilt current Mesh | Finalizer | Cache/prototype adapter | Borrowed/new Resource reference | Cache may retain |
 
@@ -101,24 +100,24 @@ map/reset clear site calls `clear()`.
 
 ```mermaid
 sequenceDiagram
-    participant Loader as StreamingWorldLoader
+    participant ResourceFinalizer as M2MeshResourceFinalizer
     participant Finalizer as M2RuntimeMeshFinalizer
     participant Raw as M2Loader boundary
     participant Classifier as RebuildClassifier
     participant Builder as M2Builder
-    Loader->>Finalizer: requires_raw_data_for_refresh(mesh)
+    ResourceFinalizer->>Finalizer: requires_raw_data_for_refresh(mesh)
     alt current Mesh
-        Finalizer-->>Loader: false; reuse Mesh
+        Finalizer-->>ResourceFinalizer: false; reuse Mesh
     else stale Mesh
-        Finalizer-->>Loader: true
-        Loader->>Raw: load static raw Dictionary
-        Loader->>Finalizer: finalize_mesh(path, mesh, raw, extracted dir)
+        Finalizer-->>ResourceFinalizer: true
+        ResourceFinalizer->>Raw: load static raw Dictionary
+        ResourceFinalizer->>Finalizer: finalize_mesh(path, mesh, raw, extracted dir)
         Finalizer->>Classifier: needs_runtime_mesh_rebuild(path, raw)
         opt rebuild required
             Finalizer->>Builder: build(raw, extracted dir)
             Finalizer->>Finalizer: extract first Mesh; free prototype
         end
-        Finalizer-->>Loader: rebuilt or marked fallback Mesh
+        Finalizer-->>ResourceFinalizer: rebuilt or marked fallback Mesh
     end
 ```
 
@@ -126,12 +125,12 @@ sequenceDiagram
 
 ```mermaid
 flowchart TB
-    Loader[StreamingWorldLoader] --> Finalizer[M2RuntimeMeshFinalizer]
+    ResourceFinalizer[M2MeshResourceFinalizer] --> Finalizer[M2RuntimeMeshFinalizer]
     Finalizer --> Classifier[M2RuntimeMeshRebuildClassifier]
     Finalizer --> Extractor[M2MeshResourceExtractor]
     Finalizer --> Builder[M2Builder]
-    Loader --> Raw[M2RawModelRepository]
-    Loader --> Cache[M2MeshResourceCacheState]
+    ResourceFinalizer --> Raw[M2RawModelRepository]
+    ResourceFinalizer --> Cache[M2MeshResourceCacheState]
     Finalizer -. no dependency .-> Raw
     Finalizer -. no dependency .-> Cache
 ```
@@ -139,7 +138,8 @@ flowchart TB
 ## Ownership, threading and resources
 
 - Renderer main thread executes metadata changes and M2Builder work.
-- `M2RawModelRepository` owns raw M2 file/native calls; loader supplies its value result.
+- `M2RawModelRepository` owns raw M2 file/native calls; the Mesh resource
+  finalizer supplies its value result.
 - Finalizer owns classifier memoization and temporary rebuild prototype lifetime.
 - M2Builder owns construction rules; extractor selects the first rebuilt Mesh.
 - Cache/prototype adapters decide where the returned Mesh reference is retained.
@@ -208,7 +208,8 @@ logs/queue metrics are unchanged. Normalized M2 path remains the correlation key
 |---|---|
 | `src/render/m2/m2_runtime_mesh_finalizer.gd` | Refresh version, classification, rebuild and fallback |
 | `src/render/m2/m2_raw_model_repository.gd` | Raw-file/native I/O and Dictionary result |
-| `src/scenes/streaming/streaming_world_loader.gd` | Repository call and returned-Mesh adoption |
+| `src/render/m2/m2_mesh_resource_finalizer.gd` | Repository call and returned-Mesh adoption |
+| `src/scenes/streaming/streaming_world_loader.gd` | Service composition, permits and materialization |
 | `src/render/m2/m2_runtime_mesh_rebuild_classifier.gd` | Memoized billboard/UV-rotation predicate |
 | `src/render/m2/m2_mesh_resource_extractor.gd` | First rebuilt-Mesh selection |
 | `src/tools/verify_m2_runtime_mesh_finalizer.gd` | Transition/rebuild/boundary/timing regression |

docs/modules/m2-static-build-resource-observer.md

@@ -134,7 +134,8 @@ flowchart TB
 - Cache/pipeline services retain their existing state and resource ownership.
 - Snapshot borrows the exact cached Mesh; observer never frees it.
 - Resource existence/request and GLB inspection run on renderer main thread.
-- Finalization and Mesh preparation remain in the loader drain path.
+- `M2MeshResourceFinalizer` performs terminal polling, Resource extraction,
+  Mesh preparation and cache/missing adoption from the loader permit loop.
 
 ## Errors, cancellation and recovery
 
@@ -181,7 +182,7 @@ a generic resource framework.
 | Capability | Status | Evidence | Gap |
 |---|---|---|---|
 | Static build lookup/request production | Implemented extraction | Lifecycle/path/source/timing verifier | Asset-backed traversal pending |
-| Static finalize/preparation | Existing loader-owned | Pipeline/finalizer regressions | Later extraction |
+| Static finalize/preparation | Implemented extraction | Mesh resource finalizer verifier | Asset-backed traversal pending |
 | Animated observation | Existing loader-owned | Animation regressions | Separate producer pending |
 
 ## Known gaps and risks
@@ -197,7 +198,8 @@ a generic resource framework.
 |---|---|
 | `src/render/m2/m2_static_build_resource_observer.gd` | Static cache/request/missing observation |
 | `src/render/m2/m2_build_resource_snapshot.gd` | Typed observation result |
-| `src/scenes/streaming/streaming_world_loader.gd` | Composition, finalize drain and action execution |
+| `src/render/m2/m2_mesh_resource_finalizer.gd` | Terminal polling, preparation and adoption |
+| `src/scenes/streaming/streaming_world_loader.gd` | Composition, permits and action execution |
 | `src/tools/verify_m2_static_build_resource_observer.gd` | Lifecycle/path/boundary/timing regression |
 
 ## Related decisions and references

docs/modules/world-renderer.md

@@ -155,6 +155,7 @@ from externally reading/writing loader-private queue, task, cache and tile-state
 | `M2MeshLoadPipelineState` | Internal M2 async-state service | Owns static Mesh pending request records and terminal finalize FIFO | Renderer main thread; map/session | Empty/duplicate/unknown transitions rejected |
 | `M2MeshResourceCacheState` | Internal M2 Resource cache | Owns prepared static Mesh references by normalized path | Renderer main thread; final shutdown | Empty path/null Mesh rejected; same path replaces |
 | `M2MeshResourceExtractor` | Internal M2 scene/resource service | Selects first Mesh from direct Resource, PackedScene or Node subtree | Renderer main thread; stateless except temporary instance | Invalid/no Mesh returns null; temporary PackedScene root freed |
+| `M2MeshResourceFinalizer` | Internal M2 terminal-I/O service | Polls static requests, extracts/prepares terminal Meshes and publishes cache/missing outcomes | Renderer main thread; stateless across calls | Invalid/failed Resources mark missing; one call pops at most one terminal record |
 | `M2RuntimeMeshFinalizer` | Internal M2 preparation service | Owns refresh version, rebuild classification, M2Builder rebuild and fallback | Renderer main thread; decisions cached until reset | Null returns null; missing/failed rebuild marks and reuses original Mesh |
 | `M2RawModelRepository` | Internal M2 native repository | Reads static/animated raw Dictionaries through exact M2Loader methods | Synchronous; stateless | Invalid/unavailable/non-Dictionary result returns empty Dictionary |
 | `M2PrototypeCacheState` | Internal M2 prototype cache | Owns detached static/animated Nodes and missing/static-only outcomes | Renderer main thread; final shutdown | Invalid admission rejected; first valid prototype wins |
@@ -427,8 +428,9 @@ sequenceDiagram
 - `M2MeshLoadPipelineState` owns static M2 pending Resource paths, opaque
   terminal statuses and completion-order finalize FIFO. The static observer owns
   cache path selection, request admission and initial snapshot adoption. The
-  loader retains ResourceLoader polling/finalize, permits and terminal adoption;
-  prototype cache state owns shared missing outcomes.
+  Mesh resource finalizer owns ResourceLoader polling/finalize and terminal
+  adoption; loader retains permits and composition, while prototype cache state
+  owns shared missing outcomes.
 - `M2AnimationLoadPipelineState` owns animated M2 pending Resource paths, opaque
   terminal statuses and completion-order finalize FIFO. The cached animation
   observer owns allow/deny/path/GLB selection, request admission and initial
@@ -440,11 +442,11 @@ sequenceDiagram
   belong to the sibling cache service and loader respectively.
 - `M2MeshResourceExtractor` owns depth-first first-Mesh selection and temporary
   PackedScene instance destruction. The static observer admits ResourceLoader
-  requests and initial cache/missing adoption; the loader retains polling,
-  terminal adoption and materialization.
+  requests and initial cache/missing adoption; the Mesh resource finalizer owns
+  terminal extraction/adoption, while the loader retains materialization.
 - `M2RuntimeMeshFinalizer` owns refresh version `2`, classifier lifetime,
-  M2Builder rebuild and original-Mesh fallback. The loader loads raw data only
-  after the finalizer reports that a cached Mesh is stale.
+  M2Builder rebuild and original-Mesh fallback. `M2MeshResourceFinalizer` loads
+  raw data only after the runtime finalizer reports that a cached Mesh is stale.
 - `M2RawModelRepository` owns FileAccess/ClassDB availability and the exact
   `load_m2`/`load_m2_animated` calls. The loader retains normalization, fallback
   order and every result consumer; `M2PrototypeCacheState` retains outcomes.
@@ -596,10 +598,11 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
 | M2 build batch planner | Implemented extraction | Scene-free limit/count/cursor/source/timing contract | Spatial cells and asset-backed p95/p99 remain pending |
 | 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 static build resource observer | Implemented extraction | Cache/pending/path/request/source/timing contract | Asset-backed traversal 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 mesh resource finalizer | Implemented extraction | Status/FIFO/load/extract/prepare/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 |
@@ -681,6 +684,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
 | `src/render/m2/m2_mesh_load_pipeline_state.gd` | Static M2 pending Resource paths, terminal statuses and finalize FIFO |
 | `src/render/m2/m2_mesh_resource_cache_state.gd` | Prepared static M2 Mesh references and final-shutdown release |
 | `src/render/m2/m2_mesh_resource_extractor.gd` | First-Mesh selection and temporary PackedScene instance lifetime |
+| `src/render/m2/m2_mesh_resource_finalizer.gd` | Static terminal polling, Mesh preparation and cache/missing adoption |
 | `src/render/m2/m2_runtime_mesh_finalizer.gd` | Runtime refresh version, rebuild classification/build and fallback |
 | `src/render/m2/m2_raw_model_repository.gd` | Stateless static/animated native M2 file boundary |
 | `src/render/m2/m2_native_animation_resource_observer.gd` | Native candidate/read/build/cache observation |
@@ -702,6 +706,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
 | `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_mesh_resource_finalizer.gd` | Static M2 polling/extraction/preparation/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 |