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

M03-RND-M2-BUILD-QUEUE-001

Owner

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

Outcome

Replace loader-owned raw M2 build-job Dictionary/FIFO fields with typed job and queue state while preserving cursor, rotation, stale-key and lifetime behavior.

Non-goals

• Move tile eligibility, resource readiness/retry or scheduler policy.
• Create/free Nodes, Meshes, MultiMeshes or animated instances inside queue state.
• Change grouping, batch planning, materialization, transform order or visuals.
• Change M2 cache versions, diagnostics text or Editor persistence.

Paths

• Exclusive: src/render/m2/m2_build_job.gd, src/render/m2/m2_build_queue.gd, src/tools/verify_m2_build_queue.gd, docs/modules/m2-build-queue.md, this claim
• Shared/hotspots: src/scenes/streaming/streaming_world_loader.gd, M2 build/ materializer/cache/shutdown/facade/internal-access 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

• A job retains tile key, root, exact groups Dictionary, insertion-order groups.keys() snapshot, group index, transform offset and batch serial.
• FIFO keeps duplicate/stale keys; front rotation moves exactly one key to tail.
• Job erase does not erase FIFO entries, preserving external-cancel stale cleanup.
• Progress adopts group index, transform offset and serial atomically.
• Queue release never frees engine objects; loader retains finish/cancel cleanup.

Dependencies

• Requires: accepted static materializer package on master 81e33a9
• Blocks: extracting remaining M2 build/resource orchestration
• External state: Node validity and SceneTree destruction remain loader APIs

Verification

• Commands: dedicated invalid/FIFO/duplicate/stale/rotation/cursor/lifetime/ diagnostics/source/timing verifier; M2 planner/materializer/cache/prototype/ shutdown/facade/internal-access/manifest regressions; docs/coordination/dry-run gates
• Fixtures: synthetic Node3D roots and ordered transform-group Dictionaries
• Fidelity evidence: exact existing keyed state, FIFO and cursor transitions
• Performance budget: 100 cycles of 256 enqueue/rotate/erase operations 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 build/world-renderer/module-registry/RENDER updates

Simplicity and naming

• Important names: M2BuildJob, M2BuildQueue
• Simplest solution: two small RefCounted types mirroring accepted WMO queue pattern
• Rejected complexity: signals, generic queue base, callbacks and engine destruction
• Unavoidable complexity: keyed jobs and FIFO keys intentionally permit stale entries
• Measured optimization evidence: bounded synthetic lifecycle loop

Status

• State: integration accepted
• Done: implementation, verification, documentation and worktree handoff
• Next: extract the next unclaimed M2 resource-dispatch seam
• Blocked by:

Handoff

• Commit: 4a8338f2f0503c2ba31c495e00a696d359518c06
• Results: cold editor parse exit=0; M2 build queue cases=13 iterations=100 elapsed_ms=66.247; all autonomous headless regressions 52/52; internal access private_symbols=30; baseline manifest/dry-run 7/7; documentation module_specs=39; coordination passed with 30 historical expired warnings.
• Remaining risks: proprietary ADT visual/p95/p99 evidence is unavailable; resource readiness/dispatch, permits, materializer choice and root destruction intentionally remain loader-owned.
• Documentation updated: new m2-build-queue.md with API/I/O, data-flow, lifecycle, sequence, dependency and ownership diagrams; world renderer, batch planner, module registry, RENDER and M03 Evidence updated.
• Integration: master merge 1dc013e5c2597d5e6f26f44807f5f0a943bf1517; post-merge queue cases=13 iterations=100 elapsed_ms=65.998, ten adjacent M2/lifetime/facade/internal-access/manifest checks, documentation and coordination all passed; checkpoint dry-run retained 7/7 plans.