coordination: claim M2 build queue

2026-07-18 02:13:15 +04:00
parent 81e33a9bc4
commit 3ee9e77422
1 changed files with 88 additions and 0 deletions
@@ -0,0 +1,88 @@
+# 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: active
+- Done: contract and ownership boundary
+- Next: implementation, verification and documentation
+- Blocked by:
+
+## Handoff
+
+- Commit:
+- Results:
+- Remaining risks:
+- Documentation updated:
+