open-wc/coordination/claims/M03-RND-ADT-WATER-LOAD-PIPELINE-001.md

M03-RND-ADT-WATER-LOAD-PIPELINE-001 — ADT water load pipeline state

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: ready for integration
• Done: pipeline state implemented; loader enqueue/start/publish/drain/release/ reset/shutdown/metrics adapters migrated; required documentation added
• Next: integrate and run post-merge smoke on master
• Blocked by:

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.