merge M03 M2 mesh resource extractor

RENDER.md

@@ -38,6 +38,7 @@ Paired run 2026-07-11 подтвердил крупный coordinate/placement g
 - `src/render/m2/m2_runtime_mesh_rebuild_classifier.gd` - memoized billboard/UV-rotation decision for stale cached M2 runtime mesh refresh.
 - `src/render/m2/m2_mesh_load_pipeline_state.gd` - static M2 threaded-load request records, terminal statuses and completion-order finalize FIFO without I/O or Mesh ownership.
 - `src/render/m2/m2_mesh_resource_cache_state.gd` - normalized-path prepared static M2 Mesh references with final-shutdown lifetime.
+- `src/render/m2/m2_mesh_resource_extractor.gd` - first-Mesh selection from direct/PackedScene/Node inputs with temporary instance cleanup.
 - `src/scenes/streaming/eastern_kingdoms_streaming.tscn` - текущая сцена для проверки Azeroth/Eastern Kingdoms.
 - `addons/mpq_extractor/loaders/adt_builder.gd` - сборка ADT terrain, control splat материалов и MH2O liquids.
 - `addons/mpq_extractor/loaders/m2_builder.gd` - сборка статического M2 mesh/material.
@@ -1087,6 +1088,18 @@ $exe = Join-Path $env:TEMP 'godot-4.6.1-openwc\Godot_v4.6.1-stable_win64.exe'
 - Cache formats, refresh metadata, profiles and visible output are unchanged.
   Synthetic cache timing is not asset-backed memory/leak or p95/p99 evidence.
 
+## 2026-07-17 M2 Mesh Resource Extractor
+
+- `M2MeshResourceExtractor` now selects the first Mesh from direct Mesh
+  Resources, temporary PackedScene instances and existing prototype/rebuild
+  Node subtrees using the prior depth-first child order.
+- PackedScene extraction still instantiates exactly once and synchronously frees
+  the temporary root before returning the borrowed Mesh reference.
+- `StreamingWorldLoader` still owns ResourceLoader I/O, raw M2 loading,
+  material refresh/rebuild, cache/missing adoption, permits and MultiMesh builds.
+- Cache formats, traversal rules, profiles and visible output are unchanged.
+  Synthetic traversal timing is not asset-backed leak or p95/p99 evidence.
+
 ## 2026-07-17 WMO Placement Resolver Extraction
 
 - `WmoPlacementResolver` now owns lowercase/slash cache-key normalization,

coordination/claims/M03-RND-M2-MESH-RESOURCE-EXTRACTOR-001.md

@@ -78,14 +78,23 @@ including temporary PackedScene instance cleanup, from `StreamingWorldLoader`.
 
 ## Status
 
-- State: claimed
+- State: ready
-- Done: three first-Mesh call sites and temporary PackedScene lifecycle identified
+- Done: extractor, three loader/test adapters, contract verifier and required documentation
-- Next: implement extractor, migrate loader adapters, verify and document
+- Next: integrator merge and post-merge smoke
 - Blocked by:
 
 ## Handoff
 
-- Commit:
+- Commit: `7b0e1ea`
-- Results:
+- Results: extractor passes direct/PackedScene/subtree/order/lifetime contracts
-- Remaining risks:
+  and 10,000 traversals in 39.243 ms; 36 headless renderer/coordinate
-- Documentation updated:
+  regressions pass; checkpoint dry-run passes 7/7; documentation and
+  coordination gates pass.
+- Remaining risks: synchronous PackedScene instantiation remains behind the
+  existing permit; no private M2 corrupt-scene/traversal/leak/p95/p99 or
+  original-client comparison; material preparation remains loader-owned.
+- Documentation updated: inline API; `m2-mesh-resource-extractor.md` with
+  data-flow, lifecycle, sequence and dependency diagrams; cache/pipeline specs,
+  module registry, `world-renderer.md` and `RENDER.md`.
+
+<!-- OPENWC_HANDOFF:READY:M03-RND-M2-MESH-RESOURCE-EXTRACTOR-001:7b0e1ea -->

docs/modules/README.md

@@ -24,6 +24,7 @@
 | M2 runtime mesh rebuild classifier | Implemented extraction | [`m2-runtime-mesh-rebuild-classifier.md`](m2-runtime-mesh-rebuild-classifier.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) |
 | WMO placement resolver | Implemented extraction | [`wmo-placement-resolver.md`](wmo-placement-resolver.md) |
 | WMO placement registry | Implemented extraction | [`wmo-placement-registry.md`](wmo-placement-registry.md) |
 | WMO render build step planner | Implemented extraction | [`wmo-render-build-step-planner.md`](wmo-render-build-step-planner.md) |

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

@@ -86,7 +86,8 @@ flowchart TD
     FIFO --> Permit{Loader permit available?}
     Permit -->|no| FIFO
     Permit -->|yes| Pop[Pop oldest terminal record]
-    Pop --> Finalize[Loader gets Resource and adopts Mesh/missing state]
+    Pop --> Finalize[Loader gets Resource and delegates first-Mesh extraction]
+    Finalize --> Adopt[Loader prepares and adopts Mesh/missing state]
 ```
 
 ## Lifecycle/state
@@ -204,7 +205,8 @@ 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 |
 | ResourceLoader I/O | Existing loader-owned | Shutdown/material regressions | I/O adapter extraction optional |
 | Mesh cache | Implemented extraction | Mesh resource cache state verifier | Asset-backed memory/leak run pending |
-| Mesh materialization | Existing loader-owned | Renderer/material tests | Separate finalizer extraction pending |
+| First-Mesh extraction | Implemented extraction | Resource/order/lifetime verifier | Asset-backed corrupt-scene fixture pending |
+| Mesh materialization | Existing loader-owned | Renderer/material tests | Separate preparation finalizer pending |
 
 ## Known gaps and risks
 
@@ -219,6 +221,7 @@ rebuild policy are unchanged; no migration or rebake is required.
 |---|---|
 | `src/render/m2/m2_mesh_load_pipeline_state.gd` | Pending records, terminal FIFO and metrics |
 | `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/scenes/streaming/streaming_world_loader.gd` | Cache path choice, I/O polling, permits and Mesh/missing adoption |
 | `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

@@ -33,7 +33,8 @@ flowchart LR
     Cache -->|cached Mesh or null| Loader
     Loader --> Pipeline[M2MeshLoadPipelineState]
     Pipeline --> IO[ResourceLoader]
-    IO --> Prepare[Loader extraction and runtime preparation]
+    IO --> Extract[M2MeshResourceExtractor]
+    Extract --> Prepare[Loader runtime preparation]
     Prepare --> Cache
     Loader --> Build[M2 MultiMesh materialization]
 ```
@@ -129,7 +130,8 @@ flowchart TB
 - Renderer main-thread adapters serialize every cache operation.
 - The cache owns normalized-path Strings and strong Mesh references.
 - Borrowed Mesh lookups do not transfer ownership or duplicate resources.
-- The loader owns missing/prototype/animated state and all Nodes/MultiMeshes.
+- `M2MeshResourceExtractor` owns first-Mesh selection and temporary PackedScene
+  instances. The loader owns missing/prototype/animated state and MultiMeshes.
 - The loader drains asynchronous work before the final cache clear.
 
 ## Errors, cancellation and recovery
@@ -181,7 +183,8 @@ the historical Mesh cache had no queue contribution or log site.
 |---|---|---|---|
 | 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 | ResourceLoader I/O remains loader-owned |
-| M2 Mesh extraction/preparation | Existing loader-owned | Material/classifier regressions | Separate finalizer extraction next |
+| M2 Mesh extraction | Implemented extraction | Resource/order/lifetime verifier | Asset-backed corrupt-scene fixture pending |
+| M2 Mesh preparation | Existing loader-owned | Material/classifier regressions | Separate finalizer extraction next |
 
 ## Known gaps and risks
 
@@ -196,6 +199,7 @@ the historical Mesh cache had no queue contribution or log site.
 | Path | Responsibility |
 |---|---|
 | `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/scenes/streaming/streaming_world_loader.gd` | Normalization, I/O, preparation, missing state and materialization |
 | `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

@@ -0,0 +1,207 @@
+# M2 Mesh Resource Extractor
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Status | Implemented extraction |
+| Target/work package | M03 / `M03-RND-M2-MESH-RESOURCE-EXTRACTOR-001` |
+| Owners | First-Mesh selection and temporary PackedScene instance lifetime |
+| Last verified | Worktree `work/sindo-main-codex/m03-m2-mesh-resource-extractor`, 2026-07-17 |
+| Profiles/capabilities | Static M2 threaded cache and synchronous raw/prototype fallback paths |
+
+## Purpose
+
+Select the first M2 Mesh from a direct Resource, PackedScene or existing Node
+subtree while keeping traversal and temporary-node lifetime outside
+`StreamingWorldLoader`.
+
+## Non-goals
+
+- Request/load Resources or choose cache paths.
+- Load raw M2 data, refresh materials or rebuild Meshes.
+- Own Mesh/prototype/missing caches or pending/finalize queues.
+- Create MultiMeshes, attach Nodes or consume render permits.
+- Change first-Mesh selection order or visible output.
+
+## Context and boundaries
+
+```mermaid
+flowchart LR
+    Pipeline[M2 load pipeline] --> Loader[StreamingWorldLoader]
+    Loader --> Resource[Loaded Mesh or PackedScene Resource]
+    Resource --> Extractor[M2MeshResourceExtractor]
+    Extractor -->|first Mesh or null| Loader
+    Loader --> Prepare[Material refresh/rebuild]
+    Prepare --> Cache[M2MeshResourceCacheState]
+    Prototype[Existing M2 Node subtree] --> Extractor
+```
+
+The extractor may inspect `Resource`, `PackedScene`, `Node`, `MeshInstance3D`
+and `Mesh` engine types. It has no ResourceLoader, filesystem, worker, cache,
+scheduler, builder, gameplay, network or editor dependency.
+
+## Public API
+
+| Symbol | Kind | Purpose | Thread/lifetime | Errors |
+|---|---|---|---|---|
+| `extract_first_mesh(resource)` | Query with temporary ownership | Return direct Mesh or first Mesh from one PackedScene instance | Renderer main thread; temporary root freed before return | Null/unsupported/empty returns null |
+| `find_first_mesh_in_subtree(root)` | Query | Return first Mesh in historical depth-first preorder | Renderer main thread; caller-owned subtree unchanged | Null/no Mesh returns null |
+
+## Inputs and outputs
+
+| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
+|---|---|---|---|---|---|
+| Input | Direct Mesh Resource | Loader threaded finalizer | Extractor | Borrowed Resource | One call |
+| Input | PackedScene Resource | Loader threaded finalizer | Extractor | Borrowed scene; extractor owns temporary instance | Temporary root until return |
+| Input | Existing prototype/rebuild Node subtree | Loader builder/fallback | Extractor | Borrowed Node tree | One traversal |
+| Output | First Mesh reference | Extractor | Loader preparation/cache adapter | Borrowed exact reference | Cache may retain later |
+
+The only side effect is synchronous creation and immediate `free()` of a
+temporary PackedScene instance.
+
+## Data flow
+
+```mermaid
+flowchart TD
+    Input[Resource or Node subtree] --> Direct{Direct Mesh?}
+    Direct -->|yes| Return[Return exact Mesh]
+    Direct -->|no| Packed{PackedScene?}
+    Packed -->|yes| Instantiate[Instantiate temporary root]
+    Packed -->|no| Traverse[Traverse caller-owned subtree]
+    Instantiate --> TraverseTemp[Depth-first preorder traversal]
+    TraverseTemp --> Free[Free temporary root]
+    Free --> ReturnOrNull[Return first Mesh or null]
+    Traverse --> ReturnOrNull
+```
+
+## Lifecycle/state
+
+```mermaid
+stateDiagram-v2
+    [*] --> Stateless
+    Stateless --> TemporaryInstance: extract PackedScene
+    TemporaryInstance --> Traversing: instantiate succeeded
+    Traversing --> Stateless: free temporary root before return
+    Stateless --> Stateless: direct Mesh/subtree/invalid input
+```
+
+No state or Resource reference is retained between calls.
+
+## Main sequence
+
+```mermaid
+sequenceDiagram
+    participant Loader as StreamingWorldLoader
+    participant Extractor as M2MeshResourceExtractor
+    participant Scene as PackedScene
+    Loader->>Extractor: extract_first_mesh(loaded Resource)
+    alt direct Mesh
+        Extractor-->>Loader: 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
+    end
+    Loader->>Loader: prepare and cache Mesh or mark missing
+```
+
+## Dependency diagram
+
+```mermaid
+flowchart TB
+    Loader[StreamingWorldLoader] --> Extractor[M2MeshResourceExtractor]
+    Extractor --> Types[Resource / PackedScene / Node / Mesh]
+    Loader --> Pipeline[M2MeshLoadPipelineState]
+    Loader --> Cache[M2MeshResourceCacheState]
+    Loader --> Classifier[M2RuntimeMeshRebuildClassifier]
+    Extractor -. no dependency .-> Pipeline
+    Extractor -. no dependency .-> Cache
+    Extractor -. no dependency .-> Classifier
+```
+
+## Ownership, threading and resources
+
+- The renderer main thread performs all traversal and PackedScene instantiation.
+- Direct and subtree Mesh references are borrowed without duplication.
+- A PackedScene temporary root is extractor-owned and synchronously freed.
+- Existing prototype/rebuild subtrees remain caller-owned and are never mutated.
+- Cache retention and Mesh material preparation remain loader/service concerns.
+
+## Errors, cancellation and recovery
+
+| Failure/state | Detection | Behavior | Diagnostic | Recovery |
+|---|---|---|---|---|
+| Null/unsupported Resource | Type guard | Return null | Contract verifier | Loader marks missing/falls back |
+| PackedScene instantiate failure | Null root | Return null | Existing loader behavior | Rebuild cache/source |
+| No Mesh in subtree | Traversal exhaustion | Return null | Contract verifier | Loader marks missing/falls back |
+| Null MeshInstance Mesh | Null traversal result | Parent continues with later siblings | Order verifier | Normal sibling search |
+| Shutdown/cancel | No retained state | No action | Ownership docs | Caller owns surrounding job |
+
+## Configuration and capabilities
+
+The module adds no settings or profile branches. Cache format order, material
+refresh version, render permits and batching remain unchanged outside it.
+
+## Persistence, cache and migration
+
+The extractor is stateless and serializes nothing. Existing `.tscn`/`.glb`
+formats, cache versions and rebuild metadata are unchanged; no migration or
+rebake is required.
+
+## Diagnostics and observability
+
+The module emits no logs and retains no counters. Loader correlation remains the
+normalized M2 path. Its verifier measures traversal time and temporary Node count.
+
+## Verification
+
+- `verify_m2_mesh_resource_extractor.gd`: direct/invalid Resources, depth-first
+  child order, null-Mesh sibling continuation, subtree ownership, PackedScene
+  exact Mesh identity, temporary Node release, source boundaries and 10,000
+  bounded traversals.
+- M2 pipeline/cache/classifier/material/shutdown/build regressions cover adjacent
+  behavior. No asset-backed visual parity claim is made.
+
+## Extension points
+
+- Material refresh/rebuild can become a separate finalizer consuming the Mesh
+  returned here and storing its result in `M2MeshResourceCacheState`.
+- Broader generic scene traversal is intentionally excluded until another real
+  consumer requires the same exact contract.
+
+## Capability status
+
+| Capability | Status | Evidence | Gap/next step |
+|---|---|---|---|
+| Direct/PackedScene first-Mesh extraction | Implemented extraction | Resource/order/lifetime verifier | Asset-backed corrupt-scene fixture pending |
+| Prototype/rebuild subtree selection | Implemented extraction | Synthetic preorder verifier | Asset-backed M2 traversal pending |
+| Material refresh/rebuild finalization | Existing loader-owned | Classifier/material regressions | Separate finalizer extraction next |
+
+## Known gaps and risks
+
+- PackedScene instantiation remains synchronous main-thread work behind the
+  existing finalize permit.
+- The first Mesh rule intentionally ignores additional MeshInstances.
+- No proprietary M2 corpus, corrupt cache, leak/descriptor-pressure, p95/p99 or
+  paired original-client capture is included.
+
+## Source map
+
+| Path | Responsibility |
+|---|---|
+| `src/render/m2/m2_mesh_resource_extractor.gd` | First-Mesh traversal and temporary PackedScene lifetime |
+| `src/scenes/streaming/streaming_world_loader.gd` | ResourceLoader, preparation, caching, missing state and materialization |
+| `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 |
+
+## Related decisions and references
+
+- [`m2-mesh-resource-cache-state.md`](m2-mesh-resource-cache-state.md)
+- [`m2-mesh-load-pipeline-state.md`](m2-mesh-load-pipeline-state.md)
+- [`m2-runtime-mesh-rebuild-classifier.md`](m2-runtime-mesh-rebuild-classifier.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/world-renderer.md

@@ -7,7 +7,7 @@
 | Status | Partial |
 | Target/work package | M00 baseline; `M01-RND-STREAMING-FOCUS-001`; `M01-QAR-SERVER-SPAWN-RENDERER-001`; M03 facade/planner/scheduler/internal-access/ground/environment/entity packages; M03 terrain packages; M03 M2 packages; M03 WMO placement package |
 | Owners | Renderer workstream / milestone integrator |
-| Last verified | Worktree `work/sindo-main-codex/m03-m2-mesh-resource-cache`, 2026-07-17 |
+| Last verified | Worktree `work/sindo-main-codex/m03-m2-mesh-resource-extractor`, 2026-07-17 |
 | Profiles/capabilities | `Performance`, `Balanced`, `High`, `Custom`; Blizzlike fidelity incomplete |
 
 ## Purpose
@@ -135,6 +135,7 @@ from externally reading/writing loader-private queue, task, cache and tile-state
 | `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 |
 | `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 |
 | `WmoPlacementResolver.normalize_relative_path/resolve_unique_key/resolve_world_transform` | Internal pure WMO service | Resolves cache key, registry identity and world transform | Main/any thread; stateless | Missing UID uses tile/index fallback; transform fields use historical defaults |
 | `WmoPlacementRegistry.add_reference/release_reference/contains/active_count/diagnostic_snapshot/clear` | Internal WMO service | Owns placement-key to tile/global reference sets | Renderer main thread; map session | Empty/unknown/non-owner input is rejected without mutation |
 | `WmoRenderBuildStepPlanner.plan_step` | Internal pure WMO service | Selects one mesh-first lightweight render-group operation and next cursors | Main/any thread; stateless | Raw integer comparisons are preserved without clamping |
@@ -375,8 +376,11 @@ sequenceDiagram
   terminal statuses and completion-order finalize FIFO. The loader retains cache
   path selection, ResourceLoader calls, permits, shared missing state and adoption.
 - `M2MeshResourceCacheState` owns prepared static Mesh references and releases
-  them at the existing final-shutdown site. The loader retains extraction,
+  them at the existing final-shutdown site. The loader retains material
-  material refresh/rebuild, missing/prototype state and materialization.
+  refresh/rebuild, missing/prototype state and materialization.
+- `M2MeshResourceExtractor` owns depth-first first-Mesh selection and temporary
+  PackedScene instance destruction. The loader retains ResourceLoader I/O,
+  runtime preparation, cache/missing adoption and materialization.
 - Rendered-ground query results and diagnostic snapshots are caller-owned values;
   the facade never returns Mesh, Node, tile-state or queue references.
 - Loaded-mesh ground sampling is renderer diagnostics, not authoritative gameplay
@@ -580,6 +584,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
 | `src/render/m2/m2_runtime_mesh_rebuild_classifier.gd` | Billboard/UV-rotation stale cached-mesh rebuild decision and memoization |
 | `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/streaming/streaming_target_planner.gd` | Scene-free wanted/retained ADT target calculation |
 | `src/render/streaming/streaming_target_policy.gd` | Immutable renderer radius/prefetch policy |
 | `src/render/streaming/streaming_target_plan.gd` | Immutable planner result with read-only tile-key sets |
@@ -597,6 +602,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_mesh_load_pipeline_state.gd` | Static M2 request/terminal/FIFO/boundary/timing regression |
 | `src/tools/verify_m2_mesh_resource_cache_state.gd` | Static M2 Mesh cache ownership/lifetime/boundary/timing regression |
+| `src/tools/verify_m2_mesh_resource_extractor.gd` | M2 direct/PackedScene/subtree order/lifetime/boundary/timing regression |
 | `src/tools/verify_streaming_target_planner.gd` | Planner behavior, dependency and bounded timing regression |
 | `src/tools/verify_render_budget_scheduler.gd` | Scheduler bounds, shared-lane priority, cancellation and timing regression |
 | `src/tools/verify_renderer_internal_access.gd` | Gameplay/EditorPlugin/registered renderer-tool boundary gate derived from private streamer fields |

src/render/m2/m2_mesh_resource_extractor.gd

@@ -0,0 +1,34 @@
+class_name M2MeshResourceExtractor
+extends RefCounted
+
+## Selects the first Mesh from loaded M2 Resources or existing Node subtrees.
+## The caller owns ResourceLoader I/O, cache adoption and material preparation.
+
+
+## Returns the direct Mesh Resource or the first Mesh in a temporary PackedScene
+## instance. The temporary instance is freed before this method returns.
+func extract_first_mesh(resource: Resource) -> Mesh:
+	if resource is Mesh:
+		return resource as Mesh
+	if not (resource is PackedScene):
+		return null
+	var temporary_root := (resource as PackedScene).instantiate()
+	if temporary_root == null:
+		return null
+	var mesh := find_first_mesh_in_subtree(temporary_root)
+	temporary_root.free()
+	return mesh
+
+
+## Returns the first MeshInstance3D Mesh in depth-first preorder. The subtree
+## and Mesh ownership remain unchanged.
+func find_first_mesh_in_subtree(root: Node) -> Mesh:
+	if root == null:
+		return null
+	if root is MeshInstance3D:
+		return (root as MeshInstance3D).mesh
+	for child in root.get_children():
+		var mesh := find_first_mesh_in_subtree(child)
+		if mesh != null:
+			return mesh
+	return null

src/render/m2/m2_mesh_resource_extractor.gd.uid

@@ -0,0 +1 @@
+uid://dea4gekrxshjf

src/scenes/streaming/streaming_world_loader.gd

@@ -69,6 +69,9 @@ const M2_MESH_LOAD_PIPELINE_STATE_SCRIPT := preload(
 const M2_MESH_RESOURCE_CACHE_STATE_SCRIPT := preload(
 	"res://src/render/m2/m2_mesh_resource_cache_state.gd"
 )
+const M2_MESH_RESOURCE_EXTRACTOR_SCRIPT := preload(
+	"res://src/render/m2/m2_mesh_resource_extractor.gd"
+)
 const STREAMING_TARGET_PLANNER_SCRIPT := preload("res://src/render/streaming/streaming_target_planner.gd")
 const STREAMING_TARGET_POLICY_SCRIPT := preload("res://src/render/streaming/streaming_target_policy.gd")
 const RENDER_BUDGET_SCHEDULER_SCRIPT := preload("res://src/render/streaming/render_budget_scheduler.gd")
@@ -260,6 +263,7 @@ var _m2_runtime_mesh_rebuild_classifier := (
 	M2_RUNTIME_MESH_REBUILD_CLASSIFIER_SCRIPT.new()
 )
 var _m2_mesh_resource_cache_state := M2_MESH_RESOURCE_CACHE_STATE_SCRIPT.new()
+var _m2_mesh_resource_extractor := M2_MESH_RESOURCE_EXTRACTOR_SCRIPT.new()
 var _m2_mesh_load_pipeline_state := M2_MESH_LOAD_PIPELINE_STATE_SCRIPT.new()
 var _m2_animation_load_requests: Dictionary = {}
 var _m2_animation_finalize_queue: Array = []
@@ -4277,7 +4281,7 @@ func _drain_m2_mesh_loads() -> void:
 
 		var path := String(pending.get("path", ""))
 		var resource: Resource = ResourceLoader.load_threaded_get(path)
-		var mesh := _extract_first_mesh_from_m2_resource(resource)
+		var mesh := _m2_mesh_resource_extractor.extract_first_mesh(resource)
 		if mesh != null:
 			_m2_mesh_resource_cache_state.store_mesh(
 				normalized_rel,
@@ -4695,34 +4699,11 @@ func _rebuild_m2_mesh_from_data(data: Dictionary) -> Mesh:
 	var prototype: Node3D = M2_BUILDER_SCRIPT.build(data, extracted_dir)
 	if prototype == null:
 		return null
-	var rebuilt := _find_first_mesh_recursive(prototype)
+	var rebuilt := _m2_mesh_resource_extractor.find_first_mesh_in_subtree(prototype)
 	prototype.free()
 	return rebuilt
 
 
-func _extract_first_mesh_from_m2_resource(resource: Resource) -> Mesh:
-	if resource is Mesh:
-		return resource as Mesh
-	if resource is PackedScene:
-		var node := (resource as PackedScene).instantiate()
-		if node == null:
-			return null
-		var mesh := _find_first_mesh_recursive(node)
-		node.free()
-		return mesh
-	return null
-
-
-func _find_first_mesh_recursive(node: Node) -> Mesh:
-	if node is MeshInstance3D:
-		return (node as MeshInstance3D).mesh
-	for child in node.get_children():
-		var mesh := _find_first_mesh_recursive(child)
-		if mesh != null:
-			return mesh
-	return null
-
-
 func _get_or_load_m2_mesh(rel_path: String) -> Mesh:
 	var normalized_rel := _normalize_m2_rel_path(rel_path)
 	if _m2_mesh_resource_cache_state.has_mesh(normalized_rel):
@@ -4730,7 +4711,7 @@ func _get_or_load_m2_mesh(rel_path: String) -> Mesh:
 	var prototype: Node3D = _get_or_load_m2_prototype(rel_path)
 	if prototype == null:
 		return null
-	var mesh := _find_first_mesh_recursive(prototype)
+	var mesh := _m2_mesh_resource_extractor.find_first_mesh_in_subtree(prototype)
 	if mesh != null and not normalized_rel.is_empty():
 		mesh = _prepare_m2_mesh_for_runtime(normalized_rel, mesh)
 		_m2_mesh_resource_cache_state.store_mesh(normalized_rel, mesh)

src/tools/verify_m2_mesh_resource_cache_state.gd

@@ -94,7 +94,7 @@ func _verify_ownership_boundaries(failures: Array[String]) -> void:
 	)
 	for retained_loader_rule in [
 		"ResourceLoader.load_threaded_get(path)",
-		"_extract_first_mesh_from_m2_resource(resource)",
+		"_m2_mesh_resource_extractor.extract_first_mesh(resource)",
 		"_prepare_m2_mesh_for_runtime(normalized_rel, mesh)",
 		"_m2_missing_cache[normalized_rel]",
 		"_m2_scene_cache[normalized_rel]",

src/tools/verify_m2_mesh_resource_extractor.gd

@@ -0,0 +1,185 @@
+extends SceneTree
+
+## Synthetic direct-Resource/PackedScene/subtree/order/lifetime/boundary/timing
+## regression for first-Mesh extraction.
+
+const EXTRACTOR_SCRIPT := preload("res://src/render/m2/m2_mesh_resource_extractor.gd")
+const EXTRACTOR_PATH := "res://src/render/m2/m2_mesh_resource_extractor.gd"
+const LOADER_PATH := "res://src/scenes/streaming/streaming_world_loader.gd"
+
+
+func _initialize() -> void:
+	var failures: Array[String] = []
+	_verify_direct_and_invalid_resources(failures)
+	_verify_depth_first_subtree_order(failures)
+	_verify_packed_scene_mesh_and_temporary_lifetime(failures)
+	_verify_ownership_boundaries(failures)
+	var elapsed_milliseconds := _verify_bounded_timing(failures)
+	if not failures.is_empty():
+		for failure in failures:
+			push_error("M2_MESH_RESOURCE_EXTRACTOR: %s" % failure)
+		quit(1)
+		return
+	print(
+		"M2_MESH_RESOURCE_EXTRACTOR PASS cases=10 iterations=10000 elapsed_ms=%.3f"
+		% elapsed_milliseconds
+	)
+	quit(0)
+
+
+func _verify_direct_and_invalid_resources(failures: Array[String]) -> void:
+	var extractor: RefCounted = EXTRACTOR_SCRIPT.new()
+	var direct_mesh := ArrayMesh.new()
+	_expect_same(
+		extractor.call("extract_first_mesh", direct_mesh),
+		direct_mesh,
+		"direct Mesh reference retained",
+		failures
+	)
+	_expect_same(extractor.call("extract_first_mesh", Resource.new()), null, "unsupported Resource returns null", failures)
+	_expect_same(extractor.call("extract_first_mesh", null), null, "null Resource returns null", failures)
+	_expect_same(extractor.call("find_first_mesh_in_subtree", null), null, "null subtree returns null", failures)
+
+
+func _verify_depth_first_subtree_order(failures: Array[String]) -> void:
+	var extractor: RefCounted = EXTRACTOR_SCRIPT.new()
+	var root := Node3D.new()
+	var first_branch := Node3D.new()
+	var second_branch := Node3D.new()
+	var first_mesh_instance := MeshInstance3D.new()
+	var second_mesh_instance := MeshInstance3D.new()
+	var first_mesh := ArrayMesh.new()
+	var second_mesh := ArrayMesh.new()
+	first_mesh_instance.mesh = first_mesh
+	second_mesh_instance.mesh = second_mesh
+	root.add_child(first_branch)
+	root.add_child(second_branch)
+	first_branch.add_child(first_mesh_instance)
+	second_branch.add_child(second_mesh_instance)
+	_expect_same(
+		extractor.call("find_first_mesh_in_subtree", root),
+		first_mesh,
+		"depth-first child order retained",
+		failures
+	)
+	_expect_same(first_mesh_instance.get_parent(), first_branch, "subtree ownership unchanged", failures)
+	first_mesh_instance.mesh = null
+	_expect_same(
+		extractor.call("find_first_mesh_in_subtree", root),
+		second_mesh,
+		"null MeshInstance Mesh skipped by parent traversal",
+		failures
+	)
+	root.free()
+
+
+func _verify_packed_scene_mesh_and_temporary_lifetime(failures: Array[String]) -> void:
+	var extractor: RefCounted = EXTRACTOR_SCRIPT.new()
+	var source_root := Node3D.new()
+	var mesh_instance := MeshInstance3D.new()
+	var packed_mesh := ArrayMesh.new()
+	mesh_instance.mesh = packed_mesh
+	source_root.add_child(mesh_instance)
+	mesh_instance.owner = source_root
+	var packed_scene := PackedScene.new()
+	_expect_equal(packed_scene.pack(source_root), OK, "synthetic PackedScene packs", failures)
+	source_root.free()
+	var node_count_before := int(Performance.get_monitor(Performance.OBJECT_NODE_COUNT))
+	var extracted_mesh: Mesh = extractor.call("extract_first_mesh", packed_scene)
+	var node_count_after := int(Performance.get_monitor(Performance.OBJECT_NODE_COUNT))
+	_expect_same(extracted_mesh, packed_mesh, "PackedScene first Mesh retained", failures)
+	_expect_equal(node_count_after, node_count_before, "temporary PackedScene root freed", failures)
+
+
+func _verify_ownership_boundaries(failures: Array[String]) -> void:
+	var extractor_source := FileAccess.get_file_as_string(EXTRACTOR_PATH)
+	var loader_source := FileAccess.get_file_as_string(LOADER_PATH)
+	_expect_true(
+		loader_source.contains("M2_MESH_RESOURCE_EXTRACTOR_SCRIPT.new()"),
+		"loader composes Mesh resource extractor",
+		failures
+	)
+	_expect_false(
+		loader_source.contains("func _extract_first_mesh_from_m2_resource("),
+		"legacy Resource extractor removed",
+		failures
+	)
+	_expect_false(
+		loader_source.contains("func _find_first_mesh_recursive("),
+		"legacy subtree extractor removed",
+		failures
+	)
+	_expect_equal(
+		loader_source.count("_m2_mesh_resource_extractor.extract_first_mesh("),
+		1,
+		"threaded Resource finalization delegates",
+		failures
+	)
+	_expect_equal(
+		loader_source.count("_m2_mesh_resource_extractor.find_first_mesh_in_subtree("),
+		2,
+		"rebuild and synchronous fallback delegate",
+		failures
+	)
+	for retained_loader_rule in [
+		"ResourceLoader.load_threaded_get(path)",
+		"_prepare_m2_mesh_for_runtime(normalized_rel, mesh)",
+		"_m2_mesh_resource_cache_state.store_mesh(",
+		"M2_BUILDER_SCRIPT.build(data, extracted_dir)",
+		"_m2_missing_cache[normalized_rel]",
+	]:
+		_expect_true(loader_source.contains(retained_loader_rule), "loader retains %s" % retained_loader_rule, failures)
+	for forbidden_dependency in [
+		"ResourceLoader.",
+		"FileAccess.",
+		"WorkerThreadPool.",
+		"M2Builder",
+		"_m2_mesh_resource_cache_state",
+		"_m2_missing_cache",
+		"MultiMesh",
+	]:
+		_expect_false(
+			extractor_source.contains(forbidden_dependency),
+			"extractor omits %s ownership" % forbidden_dependency,
+			failures
+		)
+	_expect_true(extractor_source.contains("temporary_root.free()"), "temporary root free remains explicit", failures)
+
+
+func _verify_bounded_timing(failures: Array[String]) -> float:
+	var extractor: RefCounted = EXTRACTOR_SCRIPT.new()
+	var root := Node3D.new()
+	var branch := root
+	for _depth_index in range(8):
+		var child_branch := Node3D.new()
+		branch.add_child(child_branch)
+		branch = child_branch
+	var mesh_instance := MeshInstance3D.new()
+	mesh_instance.mesh = ArrayMesh.new()
+	branch.add_child(mesh_instance)
+	var started_microseconds := Time.get_ticks_usec()
+	for _iteration in range(10000):
+		extractor.call("find_first_mesh_in_subtree", root)
+	var elapsed_milliseconds := float(Time.get_ticks_usec() - started_microseconds) / 1000.0
+	root.free()
+	_expect_true(elapsed_milliseconds < 1000.0, "10000 subtree lookups under 1 second", failures)
+	return elapsed_milliseconds
+
+
+func _expect_true(condition: bool, label: String, failures: Array[String]) -> void:
+	if not condition:
+		failures.append(label)
+
+
+func _expect_false(condition: bool, label: String, failures: Array[String]) -> void:
+	_expect_true(not condition, label, failures)
+
+
+func _expect_equal(actual: int, expected: int, label: String, failures: Array[String]) -> void:
+	if actual != expected:
+		failures.append("%s expected=%d actual=%d" % [label, expected, actual])
+
+
+func _expect_same(actual: Variant, expected: Variant, label: String, failures: Array[String]) -> void:
+	if not is_same(actual, expected):
+		failures.append(label)

src/tools/verify_m2_mesh_resource_extractor.gd.uid

@@ -0,0 +1 @@
+uid://bgvidp5u31sud