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

M03-RND-WMO-RENDER-BUILD-QUEUE-001 — WMO render build queue

Ownership

• Target: M03
• Program: RND
• Owner/Agent ID: sindo-main-codex
• Branch: work/sindo-main-codex/m03-wmo-render-build-queue
• Lease expires UTC: 2026-07-20
• Integrator: M03 milestone integrator

Outcome

Extract typed lightweight-WMO render build jobs and their FIFO key queue from the loader while leaving all engine-object destruction and materialization in the loader.

Non-goals

• Queue-free Nodes or free Resources/RIDs.
• Move material refresh, Node creation, editor ownership or budget permits.
• Change duplicate enqueue, stale-key cleanup, cancel or clear ordering.
• Change placement, cache loading/versioning, transforms, shadows or visibility.
• Claim asset-backed WMO fidelity, leak acceptance or traversal p95/p99.

Paths

• Exclusive: src/render/wmo/wmo_render_build_job.gd, src/render/wmo/wmo_render_build_queue.gd, src/tools/verify_wmo_render_build_queue.gd, docs/modules/wmo-render-build-queue.md, this claim
• Shared/hotspots: src/scenes/streaming/streaming_world_loader.gd, docs/modules/wmo-render-build-step-planner.md, docs/modules/world-renderer.md, docs/modules/README.md, RENDER.md, targets/03-renderer-facade.md
• Generated/ignored: .godot, native DLL, generated ADT/WMO resources, caches and proprietary renderer corpus

Contracts and data

• Typed job: placement key, strong Node3D/Resource references and two cursors
• FIFO queue preserves duplicate key append and first-occurrence erase behavior
• Stale front keys remain observable for loader-compatible pop-and-continue
• Cancel releases the keyed job reference and first queued key only
• Clear releases every job/key reference idempotently; never frees engine objects
• Loader retains validity checks, planner invocation, cursor adoption, materialization, permits, cancellation reactions and Node destruction
• Cache/schema/coordinate/profile versions: unchanged

Dependencies

• Requires: current master 1e740aa, accepted WMO build step planner
• Blocks: further WMO cache/load and materialization decomposition
• External state: none; verification uses synthetic Node3D/Resource instances

Verification

• Commands: dedicated invalid/FIFO/duplicate/stale/cursor/cancel/clear/ diagnostics/source/timing verifier; WMO planner/registry/resolver/material/ shutdown plus M2/terrain/facade/internal-access/manifest/scheduler/streaming/ coordinate/docs/coord gates
• Fidelity evidence: exact current queue/dictionary behavior preserved
• Performance budget: 100 cycles over 256 jobs under 1 second

Documentation deliverables

• Inline job/queue API documentation
• New module spec with inputs/outputs, data flow, state/sequence, ownership, threading, failure/recovery, performance/fidelity limits and source map
• Build-step planner, renderer module registry, world renderer and RENDER updates

Simplicity and naming

• Important names: WmoRenderBuildJob, WmoRenderBuildQueue
• Simplest solution: one typed record plus Dictionary/Array queue composition
• Rejected complexity: generic job scheduler, signals, callbacks, mutexes, Resources as job records or engine lifetime callbacks
• Unavoidable complexity: duplicate keys can intentionally leave stale entries
• Measured optimization evidence: bounded synthetic enqueue/cancel/clear loop

Status

• State: accepted
• Done: typed job/queue implemented; three clear sites, metrics, enqueue, drain and cancel migrated; engine destruction/materialization retained in loader
• Next: WMO cache/load state or liquid service extraction
• Blocked by:

Handoff

• Commit: e576ae2 (implementation e1bb105 plus cold-load fix)
• Results: queue PASS (cases=11, iterations=100, elapsed_ms=59.874); WMO planner/registry/resolver/material/shutdown and 18 adjacent M2/terrain/ facade/scheduler/streaming/coordinate regressions PASS; documentation and coordination gates PASS; checkpoint dry-run PASS 7/7.
• Cold-load recovery: post-merge smoke exposed an editor class-cache dependency; typed queue accessors removed the loader/global-class dependency and a fresh run without .godot passed (cases=11, elapsed_ms=57.835).
• Remaining risks: strong Node/Resource references require every loader cancel/ clear path; duplicate enqueue intentionally preserves stale FIFO keys; no proprietary WMO corpus, original-client paired capture, leak run or traversal p95/p99; dry-run reports expected missing ADT/DBC/character assets.
• Documentation updated: inline job/queue API; docs/modules/wmo-render-build-queue.md, build-step planner spec, module registry, world renderer and RENDER.md; data-flow/state/sequence diagrams, ownership, threading, failure/recovery and source map included.
• Integration: implementation merged as a878e7c; its first post-merge smoke exposed and rejected a cold global-class registration dependency. Fix merged as 60603e1; post-fix master queue (cases=11, iterations=100, elapsed_ms=56.454), planner, registry, resolver, shutdown, facade, documentation and coordination gates passed without parse diagnostics.