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

M03-RND-M2-BUILD-DISPATCH-PLANNER-001

Owner

• Agent ID: sindo-main-codex
• Target: M03 Renderer Facade and Safe Extraction
• Branch: work/sindo-main-codex/m03-m2-build-dispatch-planner
• Worktree: C:\Users\sindo\open-wc-worktrees\m03-m2-build-dispatch-planner

Outcome

Extract the pure M2 build-step dispatch decision from the loader while preserving animation-wait priority, static-resource retry, missing-model advancement and exact permit/cursor behavior.

Non-goals

• Move ResourceLoader I/O, path lookup, cache state or retry ownership.
• Create/free Nodes, Meshes, MultiMeshes or animated instances in the planner.
• Change batch sizing, queue ordering, transforms, visuals or cache versions.
• Add spatial-cell batching or new diagnostics/profile settings.

Paths

• Exclusive: src/render/m2/m2_build_dispatch_planner.gd, src/tools/verify_m2_build_dispatch_planner.gd, docs/modules/m2-build-dispatch-planner.md, this claim
• Shared/hotspots: src/scenes/streaming/streaming_world_loader.gd, M2 build/ queue/materializer/cache verifiers and specs, docs/modules/world-renderer.md, docs/modules/README.md, RENDER.md, targets/03-renderer-facade.md
• Generated/ignored: .godot, native DLL, generated resources/caches and proprietary corpus

Contracts and data

• Pending animation request wins before empty/animated/static decisions.
• Positive batch with animated prototype selects animated materialization.
• Positive static batch selects prepared Mesh, waits when unresolved, and advances without materialization only when the model is terminally missing.
• Zero/non-positive batch advances without materialization.
• Planner returns a fresh action plan and owns no state or engine reference.

Dependencies

• Requires: accepted typed M2 build queue on master c74b90a
• Blocks: extracting stateful M2 resource readiness/dispatch orchestration
• External state: cache lookups, requests and engine lifetime remain loader APIs

Verification

• Commands: dedicated action-priority/matrix/fresh-result/source/timing verifier; M2 queue/planner/materializer/cache/prototype/shutdown/facade/internal-access/ manifest regressions; documentation, coordination and checkpoint dry-run gates
• Fixtures: scalar availability and terminal-state combinations only
• Fidelity evidence: exact existing branch priority and retry/advance behavior
• Performance budget: 20,000 pure dispatch plans under one second

Documentation deliverables

• Inline API docs
• Module spec with inputs/outputs, ownership and source map
• Data-flow, lifecycle/state, sequence and dependency diagrams
• Adjacent M2 build/world-renderer/module-registry/RENDER updates

Simplicity and naming

• Important name: M2BuildDispatchPlanner
• Simplest solution: one stateless RefCounted with explicit action constants
• Rejected complexity: callbacks, signals, cache references and generic state machine
• Unavoidable complexity: animation-pending priority precedes every other action
• Measured optimization evidence: bounded synthetic decision loop

Status

• State: ready for integration
• Done: implementation, verification, documentation and worktree handoff
• Next: no-ff merge and post-merge acceptance on master
• Blocked by:

Handoff

• Commit: 17f5cc0faa376c8ac84a7ac72d5b8c0366866980
• Results: dispatch planner cases=10 iterations=20000 elapsed_ms=11.933; all autonomous headless regressions 53/53; internal access private_symbols=30; baseline manifest/dry-run 7/7; documentation module_specs=40; coordination passed with 30 historical expired warnings.
• Remaining risks: proprietary ADT visual/p95/p99 evidence is unavailable; resource observation/requests, action execution, permits and engine lifetime intentionally remain loader-owned.
• Documentation updated: new m2-build-dispatch-planner.md with API/I/O, data-flow, lifecycle, sequence, dependency and ownership diagrams; batch/queue/ world renderer specs, module registry, RENDER and M03 Evidence updated.