open-wc/coordination/claims/M03-RND-M2-BUILD-BATCH-PLANNER-001.md

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

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: accepted
• Done: planner, loader adapter, regressions and documentation verified
• Next: M2 queue/resource state extraction and spatial-cell evidence
• Blocked by:

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.
• Integration: accepted in master merge 3f84717; post-merge planner (cases=8, iterations=20000, elapsed_ms=14.532), grouper, transform resolver, registry, internal-access, facade, manifest, documentation and coordination gates passed.