# M03-RND-M2-BUILD-QUEUE-001

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

## 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.