95 lines
4.1 KiB
Markdown
95 lines
4.1 KiB
Markdown
# 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: ready for integration
|
|
- Done: implementation, verification, documentation and worktree handoff
|
|
- Next: no-ff merge and post-merge acceptance on master
|
|
- 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.
|