render: extract static M2 batch materializer

docs/modules/README.md

@@ -21,6 +21,7 @@
 | M2 placement transform resolver | Implemented | [`m2-placement-transform-resolver.md`](m2-placement-transform-resolver.md) |
 | M2 placement grouper | Implemented extraction | [`m2-placement-grouper.md`](m2-placement-grouper.md) |
 | M2 build batch planner | Implemented extraction | [`m2-build-batch-planner.md`](m2-build-batch-planner.md) |
+| M2 static batch materializer | Implemented extraction | [`m2-static-batch-materializer.md`](m2-static-batch-materializer.md) |
 | M2 runtime mesh rebuild classifier | Implemented extraction | [`m2-runtime-mesh-rebuild-classifier.md`](m2-runtime-mesh-rebuild-classifier.md) |
 | M2 animated scene finalizer | Implemented extraction | [`m2-animated-scene-finalizer.md`](m2-animated-scene-finalizer.md) |
 | M2 animation playback controller | Implemented extraction | [`m2-animation-playback-controller.md`](m2-animation-playback-controller.md) |

docs/modules/m2-build-batch-planner.md

@@ -174,7 +174,8 @@ queue depth, build activity and hitch observability.
 | Path | Responsibility |
 |---|---|
 | `src/render/m2/m2_build_batch_planner.gd` | Pure limit/count/cursor planning |
-| `src/scenes/streaming/streaming_world_loader.gd` | Build job, queue, resources, instance materialization and budgets |
+| `src/scenes/streaming/streaming_world_loader.gd` | Build job, queue, resource readiness, materializer adapters and budgets |
+| `src/render/m2/m2_static_batch_materializer.gd` | Planned static-slice MultiMesh construction and attachment |
 | `src/render/m2/m2_animation_playback_controller.gd` | Animated-instance phase/selection/native/imported playback |
 | `src/render/m2/m2_animated_instance_materializer.gd` | Planned animated-slice duplication, playback startup and attachment |
 | `src/render/m2/m2_placement_grouper.gd` | Produces grouped transform arrays |
@@ -184,6 +185,7 @@ queue depth, build activity and hitch observability.
 
 - [`m2-placement-grouper.md`](m2-placement-grouper.md)
 - [`m2-placement-transform-resolver.md`](m2-placement-transform-resolver.md)
+- [`m2-static-batch-materializer.md`](m2-static-batch-materializer.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-mesh-resource-cache-state.md

@@ -36,7 +36,7 @@ flowchart LR
     IO --> Extract[M2MeshResourceExtractor]
     Extract --> Prepare[M2RuntimeMeshFinalizer]
     Prepare --> Cache
-    Loader --> Build[M2 MultiMesh materialization]
+    Loader --> Build[M2StaticBatchMaterializer]
 ```
 
 The cache may retain `Mesh` resources and copied normalized-path Strings. It has
@@ -118,7 +118,8 @@ flowchart TB
     Loader[StreamingWorldLoader] --> Cache[M2MeshResourceCacheState]
     Loader --> Pipeline[M2MeshLoadPipelineState]
     Loader --> Finalizer[M2RuntimeMeshFinalizer]
-    Loader --> Builder[M2Builder and MultiMesh]
+    Loader --> Builder[M2Builder]
+    Loader --> Materializer[M2StaticBatchMaterializer]
     Cache --> Mesh[Godot Mesh Resource]
     Cache -. no dependency .-> Pipeline
     Cache -. no dependency .-> Classifier
@@ -132,7 +133,8 @@ 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
-  loader owns MultiMeshes and adoption decisions.
+  static materializer owns MultiMesh construction/attachment; the loader owns
+  resource adoption and build-job decisions.
 - The loader drains asynchronous work before the final cache clear.
 
 ## Errors, cancellation and recovery

docs/modules/m2-static-batch-materializer.md

@@ -0,0 +1,224 @@
+# M2 Static Batch Materializer
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Status | Implemented |
+| Target/work package | M03 / `M03-RND-M2-STATIC-BATCH-MATERIALIZER-001` |
+| Owners | Static M2 MultiMesh construction, render settings and attachment |
+| Last verified | Worktree `work/sindo-main-codex/m03-m2-static-batch-materializer`, 2026-07-18 |
+| Profiles/capabilities | Existing static M2 placement path |
+
+## Purpose
+
+Build and attach one static M2 `MultiMeshInstance3D` from an already prepared
+Mesh and an ordered transform slice. The service preserves the existing
+transform format, Mesh identity, batch name, visibility and shadow behavior.
+
+## Non-goals
+
+- Group placements, size batches or advance build-job cursors.
+- Load, refresh, build or cache Mesh resources.
+- Consume render permits, rotate queues or decide retries/cancellation.
+- Assign Editor owners or release tile roots.
+- Materialize animated instances or introduce spatial-cell batching.
+
+## Context and boundaries
+
+```mermaid
+flowchart LR
+    Groups[Ordered transform group] --> Loader[StreamingWorldLoader build adapter]
+    MeshCache[Prepared Mesh cache] --> Loader
+    Planner[M2BuildBatchPlanner] --> Slice[Start and count]
+    Slice --> Loader
+    Loader --> Materializer[M2StaticBatchMaterializer]
+    Materializer --> Batch[Attached MultiMeshInstance3D]
+    Loader --> EditorOwner[Editor owner adapter]
+```
+
+Allowed dependencies are Godot `Mesh`, `MultiMesh`, `MultiMeshInstance3D`,
+`GeometryInstance3D` and main-thread SceneTree APIs. Files, ResourceLoader,
+workers, RenderingServer calls, caches, build jobs, scheduler policy, gameplay,
+network and Editor ownership are forbidden.
+
+## Public API
+
+| Symbol | Kind | Purpose | Thread/lifetime | Errors |
+|---|---|---|---|---|
+| `materialize_batch(parent, path, mesh, transforms, start, count, serial, visibility_end, visibility_margin, cast_shadows)` | Command/query | Create, configure and attach one static MultiMesh batch | Main thread; borrowed inputs, parent owns result | Invalid/empty input returns null; transform bounds are a caller precondition |
+
+## Inputs and outputs
+
+| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
+|---|---|---|---|---|---|
+| Input | M2 parent root | Loader build job | Batch attachment | Borrowed Node3D | Tile/job lifetime |
+| Input | Relative model path and serial | Loader build adapter | Batch node name | Copied values | One call |
+| Input | Prepared static Mesh | M2 Mesh resource cache/finalizer | MultiMesh | Borrowed Resource; exact reference retained by MultiMesh | Cache and batch lifetimes |
+| Input | Ordered transforms, start and count | Placement group and batch plan | MultiMesh transform buffer | Borrowed Array/scalars | One call |
+| Input | Visibility end/margin and shadow flag | Renderer configuration | MultiMeshInstance3D properties | Copied scalars | One call |
+| Output | Attached `MultiMeshInstance3D` | Materializer | Parent SceneTree and loader Editor-owner adapter | Parent-owned node/resource | Tile lifetime |
+
+Side effects are MultiMesh allocation, transform-buffer mutation,
+MultiMeshInstance3D allocation/configuration and SceneTree attachment. The
+service retains no direct reference after return.
+
+## Data flow
+
+```mermaid
+flowchart TD
+    Validate[Validate parent, Mesh, transforms and count] --> MultiMesh[Allocate TRANSFORM_3D MultiMesh]
+    MultiMesh --> MeshIdentity[Assign exact prepared Mesh]
+    MeshIdentity --> Count[Set instance count]
+    Count --> Upload[Upload transforms start plus ordered batch offset]
+    Upload --> Node[Create named MultiMeshInstance3D]
+    Node --> Render[Apply shadow and optional visibility end/margin]
+    Render --> Attach[Attach once to supplied parent]
+    Attach --> Return[Return attached node]
+    Validate -->|invalid| Null[Return null without attachment]
+```
+
+## Lifecycle/state
+
+```mermaid
+stateDiagram-v2
+    [*] --> Validating
+    Validating --> Rejected: invalid or empty input
+    Validating --> Building: valid slice
+    Building --> Configured: transforms and render properties set
+    Configured --> Attached: parent add_child
+    Rejected --> [*]
+    Attached --> [*]: parent/tile owner releases subtree
+```
+
+The `RefCounted` service is stateless; states describe a single call.
+
+## Main sequence
+
+```mermaid
+sequenceDiagram
+    participant L as StreamingWorldLoader
+    participant P as M2BuildBatchPlanner
+    participant M as M2StaticBatchMaterializer
+    participant R as M2 parent root
+    L->>P: plan_batch(transform count, offset, static limits)
+    P-->>L: start/count and cursor transition
+    L->>L: resolve prepared Mesh or rotate pending job
+    L->>M: materialize_batch(parent, Mesh, transform slice, render settings)
+    M->>M: allocate MultiMesh and upload ordered transforms
+    M->>R: add_child(MultiMeshInstance3D)
+    M-->>L: attached node
+    L->>L: assign optional Editor owner
+```
+
+## Dependency diagram
+
+```mermaid
+flowchart TB
+    Loader[StreamingWorldLoader] --> Materializer[M2StaticBatchMaterializer]
+    Planner[M2BuildBatchPlanner] --> Loader
+    MeshState[M2MeshResourceCacheState] --> Loader
+    Materializer --> Engine[Mesh / MultiMesh / MultiMeshInstance3D]
+    Loader --> EditorOwner[Editor ownership]
+    Loader --> Scheduler[RenderBudgetScheduler]
+    Materializer -. no dependency .-> ResourceIO[ResourceLoader / files]
+    Materializer -. no dependency .-> BuildState[Build jobs / queues / caches]
+```
+
+## Ownership, threading and resources
+
+- The caller borrows a prepared Mesh and transform Array for the synchronous call.
+- The new MultiMesh retains the exact Mesh Resource reference.
+- The new MultiMeshInstance3D retains the MultiMesh and transfers to the parent.
+- Parent/tile teardown owns node and Resource release through the SceneTree.
+- Loader assigns an Editor owner after successful attachment when configured.
+- All Resource and SceneTree mutation is main-thread-only.
+- No RID is acquired or released directly by this service.
+
+## Errors, cancellation and recovery
+
+| Failure | Detection | Behavior | Diagnostic | Recovery |
+|---|---|---|---|---|
+| Null parent or Mesh | Entry guard | Return null without allocation/attachment | Synthetic contract fixture | Correct build composition/cache state |
+| Empty transforms or non-positive count | Entry guard | Return null | Synthetic contract fixture | Planner supplies non-empty slice |
+| Invalid transform bounds | Caller precondition | Historical indexed access behavior remains | Build planner/source regression | Repair job cursor/group state |
+| Mesh pending | Outside service | Loader rotates job without calling service | Existing build/cache diagnostics | Async completion retries job |
+| Tile cancelled | Outside service | Loader cancels before materialization or releases parent later | Shutdown regression | Eligible tile may requeue |
+
+The service does not swallow invalid bounds or silently clamp/reorder transforms,
+because doing so would change the accepted build-planner contract.
+
+## Configuration and capabilities
+
+| Setting/capability | Default | Profile | Runtime mutable | Effect |
+|---|---|---|---|---|
+| Transform format | `MultiMesh.TRANSFORM_3D` | All | No | Preserves full 3D M2 placements |
+| Static batch count | Loader `m2_multimesh_batch_size` through planner | Quality preset | Yes, between plans | Controls per-batch transform count |
+| Visibility end/margin | Loader M2 range / chunk size | Quality preset | Yes, between calls | Applied only when end is positive |
+| Shadow mode | Loader `m2_cast_shadows` | Quality preset | Yes, between calls | Selects ON/OFF casting setting |
+
+## Persistence, cache and migration
+
+No state is serialized and no cache/schema version changes. The service consumes
+the accepted prepared Mesh cache contract; no rebake or migration is required.
+
+## Diagnostics and observability
+
+- The service emits no logs, metrics or debug views.
+- Existing loader queue/hitch metrics continue to account for `m2build` work.
+- Path/serial remain visible through the unchanged batch node name.
+- Editor ownership remains observable through the existing loader adapter.
+
+## Verification
+
+- `verify_m2_static_batch_materializer.gd` covers invalid inputs, node naming,
+  exact Mesh identity, transform format/count, ordered slice source contract,
+  visibility, shadows, single attachment, ownership boundaries and timing.
+- Build planner, Mesh cache/extractor/finalizer, prototype, animated materializer,
+  shutdown, materials, facade and internal-access regressions protect neighbors.
+- The headless dummy renderer does not round-trip per-instance transforms through
+  `MultiMesh.get_instance_transform`; exact ordered upload is protected by the
+  source contract and render checkpoints remain the observable regression gate.
+- Fidelity evidence is exact extraction only; no new build-12340 parity claim.
+- Performance budget: 10,000 transform API writes under one second in headless.
+
+## Extension points
+
+Measured spatial-cell batching may later provide smaller transform slices while
+reusing this materializer. A generic static/animated base class, async mutation
+and callback framework are intentionally excluded.
+
+## Capability status
+
+| Capability | Status | Evidence | Gap/next step |
+|---|---|---|---|
+| Static M2 MultiMesh materialization | Implemented extraction | Synthetic node/resource/render/source/timing verifier | Asset-backed traversal pending |
+| Transform ordering | Implemented extraction | Exact source contract and existing checkpoints | Headless per-instance getter unavailable |
+| Editor persistence | Existing loader-owned | Source boundary and editor helper | Editor integration fixture remains separate |
+| Spatial-cell batching | Planned | Renderer roadmap | Culling/performance design and evidence pending |
+
+## Known gaps and risks
+
+- Materialization remains synchronous main-thread work under the existing permit.
+- MultiMesh transform upload timing in a headless dummy renderer does not measure GPU cost.
+- No private asset traversal, visual comparison, descriptor-pressure, leak or p95/p99 run exists.
+- Current model-path batching is not culling-driven spatial-cell batching.
+
+## Source map
+
+| Path | Responsibility |
+|---|---|
+| `src/render/m2/m2_static_batch_materializer.gd` | Static MultiMesh allocation, transform upload, render setup and attachment |
+| `src/render/m2/m2_build_batch_planner.gd` | Static/animated batch count and cursor planning |
+| `src/render/m2/m2_mesh_resource_cache_state.gd` | Prepared static Mesh reference ownership |
+| `src/scenes/streaming/streaming_world_loader.gd` | Resource readiness, job/budget adapter and Editor ownership |
+| `src/tools/verify_m2_static_batch_materializer.gd` | Node/resource/render/source/timing regression |
+
+## Related decisions and references
+
+- [`m2-build-batch-planner.md`](m2-build-batch-planner.md)
+- [`m2-mesh-resource-cache-state.md`](m2-mesh-resource-cache-state.md)
+- [`m2-animated-instance-materializer.md`](m2-animated-instance-materializer.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

@@ -54,6 +54,8 @@ flowchart LR
     M2Transform --> Loader
     Loader --> M2Batch[M2BuildBatchPlanner]
     M2Batch --> Loader
+    Loader --> M2Static[M2StaticBatchMaterializer]
+    M2Static --> Scene
     Loader --> WmoPlacement[WmoPlacementResolver]
     WmoPlacement --> Loader
     Loader --> WmoRegistry[WmoPlacementRegistry]
@@ -132,6 +134,7 @@ from externally reading/writing loader-private queue, task, cache and tile-state
 | `M2PlacementTransformResolver.resolve_basis/resolve_origin_offset` | Internal pure M2 service | Resolves regular and calibrated model-specific ADT placement transforms | Worker/main thread; stateless | Unknown paths use regular basis and zero offset |
 | `M2PlacementGrouper.group_placements` | Internal pure M2 service | Validates and groups ordered tile-local placement transforms by normalized path | Worker/main thread; stateless | Invalid variants/name IDs/empty paths are skipped |
 | `M2BuildBatchPlanner.plan_batch` | Internal pure M2 service | Selects static/animated batch count and next group cursor | Main/any thread; stateless | Non-positive selected limit clamps to one; empty range completes |
+| `M2StaticBatchMaterializer.materialize_batch` | Internal M2 scene-materialization service | Builds and attaches one prepared-Mesh MultiMesh transform slice | Renderer main thread; stateless after each call | Invalid/empty input returns null; bounds are caller precondition |
 | `M2RuntimeMeshRebuildClassifier` | Internal memoized M2 service | Detects billboard/UV-rotation metadata requiring stale cached-mesh rebuild | Renderer main thread; cached until reset | Invalid variants/indices skipped; first path decision wins |
 | `M2AnimationLoadPipelineState` | Internal M2 async-state service | Owns animated scene pending request records and terminal finalize FIFO | Renderer main thread; map/session | Empty/duplicate/unknown transitions rejected |
 | `M2AnimatedSceneFinalizer` | Internal M2 scene-finalization service | Instantiates candidates, repairs materials and requires AnimationPlayer descendants | Renderer main thread; stateless after each call | Invalid/rejected detached roots are freed |
@@ -179,6 +182,7 @@ loader configuration remains transitional composition data, not a caller API.
 | Internal transform | Rotation/path/scale | Loader or grouper / `M2PlacementTransformResolver` | Group/placeholder/instance transforms | Value-only Basis/Vector3 | One placement |
 | Internal grouping | Tile origin, M2 names and placements | Loader / `M2PlacementGrouper` | Loader worker result/build job | Fresh Dictionary/Transform3D arrays | One grouping task |
 | Internal batch plan | Transform count/offset, path kind and limits | Loader / `M2BuildBatchPlanner` | Loader materialization/cursor adapter | Fresh scalar Dictionary | One build operation |
+| Internal static M2 materialization | Parent, prepared Mesh, ordered transform slice and render settings | Loader / `M2StaticBatchMaterializer` | Attached MultiMeshInstance3D | Parent owns node/MultiMesh; exact Mesh reference retained | One main-thread build batch |
 | Internal WMO placement | Path, MODF placement, tile/index | Loader / `WmoPlacementResolver` | WMO caches, registry and three instance adapters | Value-only String/Transform3D | Lookup/placement lifetime |
 | Internal WMO ownership | Resolved placement key and tile/global reference key | Loader / `WmoPlacementRegistry` | Loader create/retain/final-free decisions | Registry-owned String sets; detached diagnostics | Map session or final release |
 | Internal WMO build step | Mesh/MultiMesh counts and job cursors | Loader / `WmoRenderBuildStepPlanner` | Loader materialization/cursor adapter | Fresh scalar Dictionary | One group operation |
@@ -239,7 +243,8 @@ flowchart TD
     M2Registry --> M2Grouper[M2PlacementGrouper]
     M2Transform[M2PlacementTransformResolver] --> M2Grouper
     M2Grouper --> M2Batch[M2BuildBatchPlanner]
-    M2Batch --> M2
+    M2Batch --> M2Static[M2StaticBatchMaterializer]
+    M2Static --> M2
     R --> WmoPlacement[WmoPlacementResolver]
     WmoPlacement --> WmoRegistry[WmoPlacementRegistry]
     WmoRegistry --> WmoBuildQueue[WmoRenderBuildQueue]
@@ -364,8 +369,10 @@ sequenceDiagram
   transforms and every build/render side effect remain loader-owned.
 - `M2PlacementGrouper` is stateless and owns only call-local grouped transforms.
   The loader retains tasks, mutex/result queues, stale checks and build state.
-- `M2BuildBatchPlanner` is stateless and owns only call-local scalar plans. The
-  loader retains queue/resource transitions, cursor adoption and materialization.
+- `M2BuildBatchPlanner` is stateless and owns only call-local scalar plans.
+  `M2StaticBatchMaterializer` owns static MultiMesh construction/attachment;
+  the loader retains queue/resource transitions, cursor adoption, animated/static
+  dispatch, budgets and Editor ownership.
 - `WmoPlacementResolver` is stateless and owns only call-local cache-key,
   identity and transform values. `WmoPlacementRegistry` owns only placement-key
   reference sets. `WmoRenderBuildStepPlanner` owns only a call-local operation
@@ -542,6 +549,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
 |---|---|---|---|
 | ADT streaming/terrain | Partial | M00 checkpoints and current scenes | Fidelity/performance gaps remain |
 | Static M2 placement | Partial | MultiMesh/dedupe probes | Full materials/animation/effects |
+| M2 static batch materializer | Implemented extraction | Synthetic node/Mesh/render/source/timing contract | Asset-backed traversal/visual/GPU p95/p99 pending |
 | M2 unique placement registry | Implemented extraction | Scene-free ownership/lifecycle/timing contract and historical `uid:11785` smoke | Group/build/tasks/finalization and asset-backed p95/p99 remain pending |
 | M2 placement transform resolver | Implemented extraction | Scene-free formula/source/timing contract across three consumers | Asset-backed visual recheck and general placement parity pending |
 | M2 placement grouper | Implemented extraction | Scene-free validation/order/transform/source/timing contract | Worker/build state, spatial cells and asset-backed p95/p99 remain pending |
@@ -615,6 +623,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
 | `src/render/m2/m2_animated_scene_finalizer.gd` | Animated scene candidate ownership, material repair and player validation |
 | `src/render/m2/m2_animation_playback_controller.gd` | Per-instance phase, selection, native copy/start and imported playback |
 | `src/render/m2/m2_animated_instance_materializer.gd` | Animated duplicate/render/playback startup and non-empty batch attachment |
+| `src/render/m2/m2_static_batch_materializer.gd` | Static MultiMesh construction, render setup and attachment |
 | `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 |
@@ -640,6 +649,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
 | `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 |
+| `src/tools/verify_m2_static_batch_materializer.gd` | Static M2 node/Mesh/render/attachment/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 |