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: active
• Done: contract and ownership boundary
• Next: implementation, verification and documentation
• Blocked by:

Handoff

• Commit:
• Results:
• Remaining risks:
• Documentation updated: