# WMO Render Build Step Planner

## Metadata

| Field | Value |
|---|---|
| Status | Implemented |
| Target/work package | M03 / `M03-RND-WMO-RENDER-BUILD-PLANNER-001` |
| Owners | Pure mesh-first WMO render-group cursor decision |
| Last verified | Worktree `work/sindo-main-codex/m03-wmo-render-build-planner`, 2026-07-17 |
| Profiles/capabilities | Lightweight WMO render-cache path; profile-independent |

## Purpose

Select exactly one next lightweight WMO render build operation from mesh and
MultiMesh counts/cursors. The planner makes the ordering and cursor transition
testable without loading a WMO, creating a Node or consuming a frame budget.

## Non-goals

- Own render Resources, Nodes, materials, jobs, queues or permits.
- Read WMO arrays, create group instances or adopt cursors in a job.
- Change group ordering, names, transforms, shadows or visibility.
- Load, validate, version or persist a WMO cache.
- Implement portals, rooms, doodad semantics or WMO visual parity.

## Context and boundaries

```mermaid
flowchart LR
    Cache[WMOStreamingResource arrays] --> Loader[StreamingWorldLoader]
    Job[Loader mesh/MultiMesh cursors] --> Loader
    Loader --> Planner[WmoRenderBuildStepPlanner]
    Planner --> Step[Operation + selected index + next cursors]
    Step --> Loader
    Loader --> Material[Material refresh]
    Loader --> Node[MeshInstance3D or MultiMeshInstance3D]
    Loader --> Budget[RenderBudgetScheduler permit]
```

The planner depends only on `RefCounted`, integers, `StringName` and a fresh
Dictionary result. Node, Resource, Mesh, MultiMesh, RID, SceneTree, files,
threads, locks, caches, gameplay, network and editor UI are forbidden.

## Public API

| Symbol | Kind | Purpose | Thread/lifetime | Errors |
|---|---|---|---|---|
| `OPERATION_MESH` | Constant | Identifies one mesh-group operation | Immutable | None |
| `OPERATION_MULTIMESH` | Constant | Identifies one doodad MultiMesh-group operation | Immutable | None |
| `OPERATION_COMPLETE` | Constant | Identifies exhausted mesh and MultiMesh ranges | Immutable | None |
| `plan_step(mesh_count, mesh_index, multimesh_count, multimesh_index)` | Pure query | Select one operation, selected index and next cursors | Any thread; caller-owned result | No clamp/error branch; raw integer comparisons are preserved |

## Inputs and outputs

| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
|---|---|---|---|---|---|
| Input | Mesh array count and current mesh cursor | Loader resource/job adapter | Planner | Integer values | One call |
| Input | MultiMesh array count and current MultiMesh cursor | Loader resource/job adapter | Planner | Integer values | One call |
| Output | `mesh`, `multimesh` or `complete` operation | Planner | Loader materializer/cancellation branch | Immutable `StringName` | One call |
| Output | Selected index | Planner | Loader Resource array access | Integer value | One operation |
| Output | Next mesh and MultiMesh cursors | Planner | Loader job adoption | Fresh Dictionary values | Until adopted/discarded |

The planner retains no input or output. Scene-tree mutation, material refresh,
job writes, permit consumption and cancellation are loader side effects.

## Data flow

```mermaid
flowchart TD
    Input[Counts and cursors] --> MeshRemaining{mesh index < mesh count?}
    MeshRemaining -->|yes| MeshStep[mesh at mesh index; increment mesh cursor]
    MeshRemaining -->|no| MultiRemaining{MultiMesh index < MultiMesh count?}
    MultiRemaining -->|yes| MultiStep[MultiMesh at its index; increment MultiMesh cursor]
    MultiRemaining -->|no| Complete[complete; keep both cursors]
```

## Lifecycle/state

The planner is stateless. State belongs to the loader job. Repeated loader calls
advance through `mesh` steps, then `multimesh` steps, then `complete`. Planner
construction, cancellation, map reset and shutdown require no cleanup.

## Main sequence

```mermaid
sequenceDiagram
    participant Loader as StreamingWorldLoader
    participant Planner as WmoRenderBuildStepPlanner
    participant Scene as SceneTree
    participant Budget as RenderBudgetScheduler
    Loader->>Planner: plan_step(counts, cursors)
    Planner-->>Loader: operation, selected index, next cursors
    alt mesh or MultiMesh
        Loader->>Loader: refresh material and create group Node
        Loader->>Scene: attach Node and editor owner
        Loader->>Loader: adopt returned cursor
        Loader->>Budget: consume one WMO group permit
    else complete
        Loader->>Loader: cancel/remove job and queue key
    end
```

## Ownership, threading and resources

- The planner owns only call-local scalar comparisons and the returned value map.
- `WmoRenderBuildQueue` owns typed jobs, FIFO keys and strong Node3D/Resource
  references. The loader owns mesh-array interpretation and engine lifetime.
- The loader creates and owns every MeshInstance3D/MultiMeshInstance3D and
  performs material refresh and editor-owner assignment on the main thread.
- `RenderBudgetScheduler` owns permits; the planner neither reads nor consumes one.
- Pure calls are thread-safe because the planner has no mutable state.

## Errors, cancellation and recovery

| Failure/state | Detection | Behavior | Diagnostic | Recovery |
|---|---|---|---|---|
| Empty arrays | Both `0 < 0` comparisons false | Return `complete` | Contract verifier | Loader removes job |
| Cursor at/beyond count | Raw integer comparison | Skip that range | Contract verifier | Continue next range or complete |
| Negative cursor/count | Raw historical comparison | No clamp; select exactly as prior loader condition | Edge fixture | Caller should maintain valid job cursors |
| Missing/invalid Resource | Loader validation before planning | Loader cancels job | Existing shutdown/runtime diagnostics | Reload/requeue placement |
| Root freed | Loader validity check before planning | Loader cancels job | Runtime-cache shutdown verifier | Placement may rebuild later |
| Placement final release | Loader/registry lifecycle | Loader cancels queued build | Registry regression | Later placement starts at cursor zero |

## Configuration and capabilities

The planner has no setting or profile branch. `wmo_render_group_ops_per_tick`,
quality presets, shadow/visibility settings and cache limits remain loader-owned.

## Persistence, cache and migration

No data is persisted. WMO render resource format/version, cache path and job
Dictionary fields are unchanged. No migration or cache rebuild is required.

## Diagnostics and observability

The planner emits no logs. Its verifier reports operation/cursor/source contracts
and bounded timing. Queue lengths, active WMO count and hitch sections remain in
existing loader/facade diagnostics.

## Verification

- `verify_wmo_render_build_step_planner.gd`: mesh-first order, cursor increments,
  completion, empty and raw negative integer behavior, fresh results, loader
  delegation, dependency boundary and 20,000-plan timing.
- WMO registry/resolver/material/shutdown plus renderer regressions verify the
  unchanged ownership and surrounding runtime path.
- Fidelity evidence is exact extraction of existing mesh-before-MultiMesh and
  one-index-per-permit behavior. No asset-backed build-12340 visual claim is made.

## Extension points

- `WmoRenderBuildQueue` now owns typed pending state; cache/load requests and
  materialization remain separate extraction seams.
- Materialization can later receive typed commands without changing this planner.

## Capability status

| Capability | Status | Evidence | Gap/next step |
|---|---|---|---|
| WMO render build step planning | Implemented | Pure contract/source/timing verifier | Asset-backed traversal p95/p99 pending |
| WMO build job/queue ownership | Implemented | Typed lifecycle/source/timing verifier | Asset-backed traversal/leak evidence pending |
| WMO visual/portal/material fidelity | Partial | Renderer baseline/material checks | Original-client paired evidence pending |

## Known gaps and risks

- Loader build jobs remain untyped Dictionaries.
- Resource array shape/length consistency remains a cache-builder invariant.
- No proprietary WMO corpus, traversal profile or paired client capture is part
  of this extraction.

## Source map

| Path | Responsibility |
|---|---|
| `src/render/wmo/wmo_render_build_step_planner.gd` | Pure operation and cursor selection |
| `src/render/wmo/wmo_render_build_job.gd` | Typed engine references and cursors |
| `src/render/wmo/wmo_render_build_queue.gd` | Pending jobs, FIFO keys and cancellation state |
| `src/scenes/streaming/streaming_world_loader.gd` | Resource validation, materialization, permits and engine lifetime |
| `src/tools/verify_wmo_render_build_step_planner.gd` | Contract, boundary and timing regression |

## Related decisions and references

- [`wmo-placement-registry.md`](wmo-placement-registry.md)
- [`wmo-render-build-queue.md`](wmo-render-build-queue.md)
- [`wmo-placement-resolver.md`](wmo-placement-resolver.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)