116 lines
5.2 KiB
Markdown
116 lines
5.2 KiB
Markdown
# M03-RND-ADT-WATER-LOAD-PIPELINE-001 — ADT water load pipeline state
|
|
|
|
<!-- OPENWC_CLAIM:M03-RND-ADT-WATER-LOAD-PIPELINE-001:sindo-main-codex:2026-07-20 -->
|
|
|
|
## Ownership
|
|
|
|
- Target: M03
|
|
- Program: RND
|
|
- Owner/Agent ID: sindo-main-codex
|
|
- Branch: `work/sindo-main-codex/m03-adt-water-load-pipeline`
|
|
- Lease expires UTC: 2026-07-20
|
|
- Integrator: M03 milestone integrator
|
|
|
|
## Outcome
|
|
|
|
Extract ADT water pending-request FIFO/deduplication, active worker task IDs and
|
|
worker-safe result mailbox from the loader while preserving loader-owned parse,
|
|
budget, stale-result and scene finalization behavior.
|
|
|
|
## Non-goals
|
|
|
|
- Instantiate `ADTLoader`, start/wait WorkerThreadPool tasks or parse ADT bytes.
|
|
- Consume `WATER_FINALIZE` permits or choose concurrency/profile limits.
|
|
- Build/attach/free water Nodes, materials, Meshes or RIDs.
|
|
- Change tile/path stale checks, empty-data behavior or `water_loaded` timing.
|
|
- Change MH2O/MCLQ parsing or claim liquid fidelity/performance parity.
|
|
|
|
## Paths
|
|
|
|
- Exclusive: `src/render/liquid/adt_water_load_pipeline_state.gd`,
|
|
`src/tools/verify_adt_water_load_pipeline_state.gd`,
|
|
`docs/modules/adt-water-load-pipeline-state.md`, this claim
|
|
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`,
|
|
`src/tools/verify_render_runtime_cache_shutdown.gd`,
|
|
`docs/modules/world-renderer.md`, `docs/modules/README.md`, `RENDER.md`,
|
|
`targets/03-renderer-facade.md`
|
|
- Generated/ignored: `.godot`, native DLL, generated ADT resources, caches and
|
|
proprietary renderer corpus
|
|
|
|
## Contracts and data
|
|
|
|
- Pending requests preserve FIFO and tile-key deduplication.
|
|
- Tile release removes all matching pending entries but does not cancel active work.
|
|
- Active task IDs are loader-created opaque integers keyed by tile.
|
|
- Worker publication and main-thread result pop/clear are mutex protected.
|
|
- Result order and Dictionary payload identity remain unchanged.
|
|
- Clear releases bookkeeping only; loader waits tasks at orderly shutdown.
|
|
- Water parsing, coordinate, material, profile and visual rules are unchanged.
|
|
|
|
## Dependencies
|
|
|
|
- Requires: current master `4387c66`; accepted scheduler and renderer lifecycle
|
|
- Blocks: further liquid parse/finalization decomposition
|
|
- External state: none; verification uses synthetic task IDs and payloads
|
|
|
|
## Verification
|
|
|
|
- Commands: dedicated FIFO/dedupe/task/result/cancel/clear/thread/source/timing
|
|
verifier; shutdown, water/material and adjacent renderer/streaming/coordinate/
|
|
documentation/coordination gates
|
|
- Fixtures: synthetic tile/path requests, task IDs and water dictionaries
|
|
- Fidelity evidence: exact current queue/task/result transitions preserved
|
|
- Performance budget: 100 cycles over 256 requests/results under 1 second
|
|
|
|
## Documentation deliverables
|
|
|
|
- Inline public API docs
|
|
- Module specification with inputs/outputs, ownership and source map
|
|
- Data-flow, lifecycle/state, worker sequence and dependency diagrams
|
|
- World-renderer, module registry and RENDER status updates
|
|
|
|
## Simplicity and naming
|
|
|
|
- Important names introduced: `AdtWaterLoadPipelineState`
|
|
- Simplest considered solution: one RefCounted with FIFO/dedupe/task maps and one mutex mailbox
|
|
- Rejected complexity/abstractions: generic async scheduler, signals, callbacks,
|
|
WorkerThreadPool wrapper, parser/material ownership or multi-lane framework
|
|
- Unavoidable complexity and justification: result mailbox crosses worker/main threads
|
|
- Measured optimization evidence: bounded synthetic lifecycle loop
|
|
|
|
## Status
|
|
|
|
- State: accepted
|
|
- Done: pipeline state implemented; loader enqueue/start/publish/drain/release/
|
|
reset/shutdown/metrics adapters migrated; required documentation added
|
|
- Next: continue liquid parse/finalization extraction or another remaining M03
|
|
service boundary
|
|
- Blocked by:
|
|
|
|
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-ADT-WATER-LOAD-PIPELINE-001:f470775 -->
|
|
|
|
## Handoff
|
|
|
|
- Commit: `b7c036f`
|
|
- Results: water pipeline PASS (`cases=12`, `iterations=100`,
|
|
`elapsed_ms=86.170`; initial direct cold run `94.576ms`); real Thread result
|
|
publication, FIFO/dedupe/task/cancel/clear/source contracts PASS; WMO caches/
|
|
queue/planner/registry/resolver, materials, shutdown and 18 adjacent M2/terrain/
|
|
facade/scheduler/streaming/coordinate regressions PASS; documentation and
|
|
coordination gates PASS; checkpoint dry-run PASS `7/7`.
|
|
- Remaining risks: clear does not interrupt active WorkerThreadPool work and a
|
|
post-reset publication remains stale until drained/cleared, matching prior
|
|
behavior; payload Dictionaries require no mutation after publication; parser,
|
|
main-thread water materialization and asset-backed MH2O/MCLQ traversal/leak/
|
|
p95/p99/original-client evidence remain pending.
|
|
- Documentation updated: inline public API; new
|
|
`docs/modules/adt-water-load-pipeline-state.md`; module registry, world renderer
|
|
and `RENDER.md`; data-flow/state/sequence/dependency diagrams, ownership,
|
|
threading, failure/recovery, profiles, performance limit and source map included.
|
|
- Integration: merged as `f470775`; post-merge water pipeline (`cases=12`,
|
|
`iterations=100`, `elapsed_ms=86.935`), shutdown, renderer materials, facade,
|
|
internal-access (`private_symbols=36`), `7/7` manifest, documentation and
|
|
coordination gates passed.
|
|
|
|
<!-- OPENWC_HANDOFF:READY:M03-RND-ADT-WATER-LOAD-PIPELINE-001:b7c036f -->
|