refactor(M03): extract M2 mesh resource cache state

Work-Package: M03-RND-M2-MESH-RESOURCE-CACHE-001
Agent: sindo-main-codex
Tests: 35 headless renderer/coordinate contracts pass; checkpoint dry-run 7/7; documentation and coordination gates pass
Fidelity: preserves exact Mesh references, replacement semantics and final-shutdown lifetime; no visual parity claim

src/render/m2/m2_mesh_resource_cache_state.gd

@@ -0,0 +1,50 @@
+class_name M2MeshResourceCacheState
+extends RefCounted
+
+## Owns normalized-path references to prepared static M2 Mesh resources.
+## The caller owns loading, preparation, missing-state and materialization.
+
+var _mesh_by_normalized_path: Dictionary = {}
+
+
+## Stores one prepared Mesh for a non-empty normalized M2 path. A later store
+## for the same path replaces the retained reference.
+func store_mesh(normalized_relative_path: String, mesh: Mesh) -> bool:
+	if normalized_relative_path.is_empty() or mesh == null:
+		return false
+	_mesh_by_normalized_path[normalized_relative_path] = mesh
+	return true
+
+
+## Returns whether one normalized path currently has a retained Mesh.
+func has_mesh(normalized_relative_path: String) -> bool:
+	return (
+		not normalized_relative_path.is_empty()
+		and _mesh_by_normalized_path.has(normalized_relative_path)
+	)
+
+
+## Returns the exact retained Mesh reference, or null for empty/unknown paths.
+func find_mesh(normalized_relative_path: String) -> Mesh:
+	if not has_mesh(normalized_relative_path):
+		return null
+	return _mesh_by_normalized_path[normalized_relative_path] as Mesh
+
+
+## Returns the number of retained static M2 Mesh resources.
+func mesh_count() -> int:
+	return _mesh_by_normalized_path.size()
+
+
+## Returns a detached insertion-order list of cached normalized paths.
+func normalized_paths_snapshot() -> Array[String]:
+	var normalized_paths: Array[String] = []
+	for normalized_path_variant in _mesh_by_normalized_path.keys():
+		normalized_paths.append(String(normalized_path_variant))
+	return normalized_paths
+
+
+## Releases all retained Mesh references. The loader calls this only after
+## asynchronous work has completed during final scene shutdown.
+func clear() -> void:
+	_mesh_by_normalized_path.clear()

src/render/m2/m2_mesh_resource_cache_state.gd.uid

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

src/scenes/streaming/streaming_world_loader.gd

@@ -66,6 +66,9 @@ const M2_RUNTIME_MESH_REBUILD_CLASSIFIER_SCRIPT := preload(
 const M2_MESH_LOAD_PIPELINE_STATE_SCRIPT := preload(
 	"res://src/render/m2/m2_mesh_load_pipeline_state.gd"
 )
+const M2_MESH_RESOURCE_CACHE_STATE_SCRIPT := preload(
+	"res://src/render/m2/m2_mesh_resource_cache_state.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")
@@ -256,7 +259,7 @@ var _m2_build_batch_planner := M2_BUILD_BATCH_PLANNER_SCRIPT.new()
 var _m2_runtime_mesh_rebuild_classifier := (
 	M2_RUNTIME_MESH_REBUILD_CLASSIFIER_SCRIPT.new()
 )
-var _m2_mesh_cache: Dictionary = {}
+var _m2_mesh_resource_cache_state := M2_MESH_RESOURCE_CACHE_STATE_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 = []
@@ -476,7 +479,7 @@ func _release_runtime_caches_for_shutdown() -> void:
 	_free_detached_node_cache(_m2_scene_cache)
 	_free_detached_node_cache(_m2_animated_scene_cache)
 	_free_detached_node_cache(_wmo_prototype_cache)
-	_m2_mesh_cache.clear()
+	_m2_mesh_resource_cache_state.clear()
 	_m2_static_animation_cache.clear()
 	_m2_missing_cache.clear()
 	_wmo_render_resource_cache_state.clear_all()
@@ -4263,7 +4266,10 @@ func _drain_m2_mesh_loads() -> void:
 			RENDER_BUDGET_SCHEDULER_SCRIPT.M2_MESH_FINALIZE):
 		var pending: Dictionary = _m2_mesh_load_pipeline_state.pop_finalize_record()
 		var normalized_rel := String(pending.get("normalized", ""))
-		if normalized_rel.is_empty() or _m2_mesh_cache.has(normalized_rel):
+		if (
+			normalized_rel.is_empty()
+			or _m2_mesh_resource_cache_state.has_mesh(normalized_rel)
+		):
 			continue
 		if int(pending.get("status", ResourceLoader.THREAD_LOAD_FAILED)) != ResourceLoader.THREAD_LOAD_LOADED:
 			_m2_missing_cache[normalized_rel] = true
@@ -4273,7 +4279,10 @@ func _drain_m2_mesh_loads() -> void:
 		var resource: Resource = ResourceLoader.load_threaded_get(path)
 		var mesh := _extract_first_mesh_from_m2_resource(resource)
 		if mesh != null:
-			_m2_mesh_cache[normalized_rel] = _prepare_m2_mesh_for_runtime(normalized_rel, mesh)
+			_m2_mesh_resource_cache_state.store_mesh(
+				normalized_rel,
+				_prepare_m2_mesh_for_runtime(normalized_rel, mesh)
+			)
 		else:
 			_m2_missing_cache[normalized_rel] = true
 
@@ -4608,8 +4617,8 @@ func _get_m2_mesh_or_request(rel_path: String) -> Mesh:
 	var normalized_rel := _normalize_m2_rel_path(rel_path)
 	if normalized_rel.is_empty():
 		return null
-	if _m2_mesh_cache.has(normalized_rel):
-		return _m2_mesh_cache[normalized_rel]
+	if _m2_mesh_resource_cache_state.has_mesh(normalized_rel):
+		return _m2_mesh_resource_cache_state.find_mesh(normalized_rel)
 	if _m2_missing_cache.has(normalized_rel):
 		return null
 	_request_m2_mesh_load(normalized_rel)
@@ -4716,15 +4725,15 @@ func _find_first_mesh_recursive(node: Node) -> Mesh:
 
 func _get_or_load_m2_mesh(rel_path: String) -> Mesh:
 	var normalized_rel := _normalize_m2_rel_path(rel_path)
-	if _m2_mesh_cache.has(normalized_rel):
-		return _m2_mesh_cache[normalized_rel]
+	if _m2_mesh_resource_cache_state.has_mesh(normalized_rel):
+		return _m2_mesh_resource_cache_state.find_mesh(normalized_rel)
 	var prototype: Node3D = _get_or_load_m2_prototype(rel_path)
 	if prototype == null:
 		return null
 	var mesh := _find_first_mesh_recursive(prototype)
 	if mesh != null and not normalized_rel.is_empty():
 		mesh = _prepare_m2_mesh_for_runtime(normalized_rel, mesh)
-		_m2_mesh_cache[normalized_rel] = mesh
+		_m2_mesh_resource_cache_state.store_mesh(normalized_rel, mesh)
 	return mesh
 
 

src/tools/verify_m2_mesh_load_pipeline_state.gd

@@ -110,7 +110,7 @@ func _verify_ownership_boundaries(failures: Array[String]) -> void:
 		"ResourceLoader.load_threaded_get_status(path)",
 		"ResourceLoader.load_threaded_get(path)",
 		"RENDER_BUDGET_SCHEDULER_SCRIPT.M2_MESH_FINALIZE",
-		"_m2_mesh_cache[normalized_rel]",
+		"_m2_mesh_resource_cache_state.store_mesh(",
 		"_m2_missing_cache[normalized_rel]",
 	]:
 		_expect_true(loader_source.contains(retained_loader_rule), "loader retains %s" % retained_loader_rule, failures)
@@ -121,6 +121,7 @@ func _verify_ownership_boundaries(failures: Array[String]) -> void:
 		"Node3D",
 		"RID(",
 		"_m2_mesh_cache",
+		"_m2_mesh_resource_cache_state",
 		"_m2_missing_cache",
 	]:
 		_expect_false(

src/tools/verify_m2_mesh_resource_cache_state.gd

@@ -0,0 +1,158 @@
+extends SceneTree
+
+## Synthetic ownership/lifetime/boundary/timing regression for the prepared
+## static M2 Mesh resource cache.
+
+const CACHE_SCRIPT := preload("res://src/render/m2/m2_mesh_resource_cache_state.gd")
+const CACHE_PATH := "res://src/render/m2/m2_mesh_resource_cache_state.gd"
+const LOADER_PATH := "res://src/scenes/streaming/streaming_world_loader.gd"
+
+
+func _initialize() -> void:
+	var failures: Array[String] = []
+	_verify_validation_store_lookup_and_replace(failures)
+	_verify_clear_and_diagnostics(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_CACHE_STATE: %s" % failure)
+		quit(1)
+		return
+	print(
+		"M2_MESH_RESOURCE_CACHE_STATE PASS cases=9 iterations=100 elapsed_ms=%.3f"
+		% elapsed_milliseconds
+	)
+	quit(0)
+
+
+func _verify_validation_store_lookup_and_replace(failures: Array[String]) -> void:
+	var cache: RefCounted = CACHE_SCRIPT.new()
+	var first_mesh := ArrayMesh.new()
+	var replacement_mesh := ArrayMesh.new()
+	_expect_false(cache.call("store_mesh", "", first_mesh), "empty path rejected", failures)
+	_expect_false(cache.call("store_mesh", "world/a.m2", null), "null Mesh rejected", failures)
+	_expect_true(cache.call("store_mesh", "world/a.m2", first_mesh), "first Mesh stored", failures)
+	_expect_true(cache.call("has_mesh", "world/a.m2"), "stored Mesh observable", failures)
+	_expect_same(cache.call("find_mesh", "world/a.m2"), first_mesh, "exact Mesh retained", failures)
+	_expect_true(
+		cache.call("store_mesh", "world/a.m2", replacement_mesh),
+		"same-path Mesh replaced",
+		failures
+	)
+	_expect_same(
+		cache.call("find_mesh", "world/a.m2"),
+		replacement_mesh,
+		"replacement Mesh retained",
+		failures
+	)
+	_expect_equal(int(cache.call("mesh_count")), 1, "replacement keeps one entry", failures)
+	_expect_same(cache.call("find_mesh", "world/missing.m2"), null, "unknown path returns null", failures)
+
+
+func _verify_clear_and_diagnostics(failures: Array[String]) -> void:
+	var cache: RefCounted = CACHE_SCRIPT.new()
+	cache.call("store_mesh", "world/a.m2", ArrayMesh.new())
+	cache.call("store_mesh", "world/b.m2", ArrayMesh.new())
+	var normalized_paths: Array[String] = cache.call("normalized_paths_snapshot")
+	_expect_equal(normalized_paths.size(), 2, "diagnostic path count", failures)
+	_expect_string_equal(normalized_paths[0], "world/a.m2", "diagnostic insertion order first", failures)
+	_expect_string_equal(normalized_paths[1], "world/b.m2", "diagnostic insertion order second", failures)
+	normalized_paths.clear()
+	_expect_equal(int(cache.call("mesh_count")), 2, "diagnostics detached", failures)
+	cache.call("clear")
+	cache.call("clear")
+	_expect_equal(int(cache.call("mesh_count")), 0, "clear releases all entries", failures)
+
+
+func _verify_ownership_boundaries(failures: Array[String]) -> void:
+	var cache_source := FileAccess.get_file_as_string(CACHE_PATH)
+	var loader_source := FileAccess.get_file_as_string(LOADER_PATH)
+	_expect_true(
+		loader_source.contains("M2_MESH_RESOURCE_CACHE_STATE_SCRIPT.new()"),
+		"loader composes Mesh cache state",
+		failures
+	)
+	_expect_false(loader_source.contains("var _m2_mesh_cache:"), "legacy Mesh cache removed", failures)
+	_expect_equal(
+		loader_source.count("_m2_mesh_resource_cache_state.store_mesh("),
+		2,
+		"two existing stores delegate",
+		failures
+	)
+	_expect_equal(
+		loader_source.count("_m2_mesh_resource_cache_state.find_mesh("),
+		2,
+		"two existing lookups delegate",
+		failures
+	)
+	_expect_equal(
+		loader_source.count("_m2_mesh_resource_cache_state.clear()"),
+		1,
+		"final shutdown clear delegates",
+		failures
+	)
+	for retained_loader_rule in [
+		"ResourceLoader.load_threaded_get(path)",
+		"_extract_first_mesh_from_m2_resource(resource)",
+		"_prepare_m2_mesh_for_runtime(normalized_rel, mesh)",
+		"_m2_missing_cache[normalized_rel]",
+		"_m2_scene_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.",
+		"PackedScene",
+		"Node3D",
+		"M2Builder",
+		"_m2_missing_cache",
+		"_m2_scene_cache",
+	]:
+		_expect_false(
+			cache_source.contains(forbidden_dependency),
+			"cache omits %s ownership" % forbidden_dependency,
+			failures
+		)
+
+
+func _verify_bounded_timing(failures: Array[String]) -> float:
+	var cache: RefCounted = CACHE_SCRIPT.new()
+	var meshes: Array[Mesh] = []
+	for _path_index in range(256):
+		meshes.append(ArrayMesh.new())
+	var started_microseconds := Time.get_ticks_usec()
+	for _iteration in range(100):
+		for path_index in range(256):
+			cache.call("store_mesh", "world/model_%d.m2" % path_index, meshes[path_index])
+		for path_index in range(256):
+			cache.call("find_mesh", "world/model_%d.m2" % path_index)
+		cache.call("clear")
+	var elapsed_milliseconds := float(Time.get_ticks_usec() - started_microseconds) / 1000.0
+	_expect_true(elapsed_milliseconds < 1000.0, "100 by 256 store/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_string_equal(actual: String, expected: String, label: String, failures: Array[String]) -> void:
+	if actual != expected:
+		failures.append("%s expected=%s actual=%s" % [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_cache_state.gd.uid

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

src/tools/verify_render_runtime_cache_shutdown.gd

@@ -35,7 +35,8 @@ func _verify_runtime_cache_ownership() -> void:
 	loader.set("_m2_scene_cache", {"static": static_m2_prototype})
 	loader.set("_m2_animated_scene_cache", {"animated": animated_m2_prototype})
 	loader.set("_wmo_prototype_cache", {"wmo": wmo_prototype})
-	loader.set("_m2_mesh_cache", {"mesh": ArrayMesh.new()})
+	var m2_mesh_resource_cache_state: RefCounted = loader.get("_m2_mesh_resource_cache_state")
+	m2_mesh_resource_cache_state.call("store_mesh", "mesh", ArrayMesh.new())
 	loader.set("_m2_static_animation_cache", {"static": true})
 	loader.set("_m2_missing_cache", {"missing": true})
 	var wmo_render_cache_state: RefCounted = loader.get("_wmo_render_resource_cache_state")
@@ -59,7 +60,6 @@ func _verify_runtime_cache_ownership() -> void:
 		"_m2_scene_cache",
 		"_m2_animated_scene_cache",
 		"_wmo_prototype_cache",
-		"_m2_mesh_cache",
 		"_m2_static_animation_cache",
 		"_m2_missing_cache",
 		"_wmo_missing_cache",
@@ -67,6 +67,10 @@ func _verify_runtime_cache_ownership() -> void:
 	]:
 		var cache: Dictionary = loader.get(cache_name)
 		_expect(cache.is_empty(), "%s should be empty after shutdown" % cache_name)
+	_expect(
+		int(m2_mesh_resource_cache_state.call("mesh_count")) == 0,
+		"M2 Mesh Resources should be empty after shutdown"
+	)
 	var wmo_render_snapshot: Dictionary = wmo_render_cache_state.call("diagnostic_snapshot")
 	_expect(
 		(wmo_render_snapshot["resource_paths"] as Array).is_empty(),