# M03-RND-M2-BUILD-BATCH-PLANNER-001 — M2 build batch planner

<!-- OPENWC_CLAIM:M03-RND-M2-BUILD-BATCH-PLANNER-001:sindo-main-codex:2026-07-20 -->

## Ownership

- Target: M03
- Program: RND
- Owner/Agent ID: sindo-main-codex
- Branch: `work/sindo-main-codex/m03-m2-build-batch-planner`
- Lease expires UTC: 2026-07-20
- Integrator: M03 milestone integrator

## Outcome

Extract pure static/animated M2 build batch sizing and cursor progression from
the loader build-job loop into a scene-free planner.

## Non-goals

- Move build-job/queue ownership, tile eligibility or cancellation.
- Move animation/mesh requests, cache lookup, queue rotation or retry behavior.
- Create Nodes, MultiMesh, Mesh, materials or RIDs.
- Change render-budget permit consumption or per-profile batch limits.
- Introduce spatial-cell batching or claim asset-backed performance parity.

## Paths

- Exclusive: `src/render/m2/m2_build_batch_planner.gd`,
  `src/tools/verify_m2_build_batch_planner.gd`,
  `docs/modules/m2-build-batch-planner.md`, this claim
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`,
  `docs/modules/m2-placement-grouper.md`, `docs/modules/world-renderer.md`,
  `docs/modules/README.md`, `RENDER.md`, `targets/03-renderer-facade.md`
- Generated/ignored: `.godot`, native DLL, generated ADT resources, caches and
  proprietary renderer corpus

## Contracts and data

- Input: transform count, current offset, animated/static path selector and raw
  animated/static batch limits
- Output: fresh plan Dictionary with effective batch size, batch count, next
  offset and group-complete flag
- Selected batch limit clamps to at least one
- Batch count clamps to remaining non-negative transforms
- Group completes when no batch can be consumed or offset plus batch reaches end
- Queue/cache/schema/coordinate/profile values: unchanged

## Dependencies

- Requires: current master `9d74d99`; grouped transform arrays from
  `M2PlacementGrouper`
- Blocks: broader M2 build-job state extraction
- External state: none; tests use scalar synthetic counts/limits

## Verification

- Commands: dedicated static/animated/limit/remaining/complete/empty/offset and
  bounded timing verifier; loader source boundary; grouper/transform/registry plus
  facade/internal-access/manifest/shutdown/documentation/coordination gates
- Fidelity evidence: exact batch/count/cursor formulas moved unchanged
- Performance budget: constant-time scalar/container calculation; no Node,
  Resource, RID, task, queue, mutex, cache or file access

## Documentation deliverables

- Inline planner API documentation
- New module spec with inputs/outputs, data-flow, lifecycle, ownership, failure,
  performance, fidelity limitations and source map
- Grouper, renderer/module registry and `RENDER.md` updates

## Simplicity and naming

- Important name: `M2BuildBatchPlanner`
- Simplest solution: one stateless `plan_batch` query with a small detached result
- Rejected complexity: job classes, state machine framework, callbacks, signals,
  Resources, strategies or scheduler integration
- Unavoidable complexity: loader retains raw build-job Dictionaries
- Measured optimization evidence: bounded synthetic planning loop

## Status

- State: handoff
- Done: planner, loader adapter, regressions and documentation verified
- Next: M03 integrator acceptance and merge to master
- Blocked by:

<!-- OPENWC_HANDOFF:READY:M03-RND-M2-BUILD-BATCH-PLANNER-001:be6db7f -->

## Handoff

- Commit: `be6db7f` (`refactor(M03): extract M2 build batch planner`)
- Results: dedicated planner PASS (`cases=8`, `iterations=20000`,
  `elapsed_ms=13.464`); grouper, transform resolver, M2 registry/dedupe, terrain
  cache/LOD/queue, facade, internal-access, manifest, shutdown, scheduler,
  streaming planner/focus, terrain-query and coordinate-boundary suites PASS;
  editor import parsed with only expected missing private corpus diagnostics;
  documentation PASS (`module_specs=18`, `required_files=7`); coordination PASS
  with 23 pre-existing expired M00/M01 warnings; checkpoint dry-run planned `7/7`.
- Remaining risks: no private asset-backed p95/p99 or visual comparison; result
  and loader job remain Dictionaries; resource/queue transitions and spatial-cell
  batching are still loader-owned; negative offset behavior remains permissive.
- Documentation updated: inline public API; new
  `docs/modules/m2-build-batch-planner.md`; placement grouper module spec,
  renderer module registry, `docs/modules/world-renderer.md` and `RENDER.md`.