# 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: 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.

<!-- OPENWC_HANDOFF:READY:M03-RND-ADT-WATER-LOAD-PIPELINE-001:b7c036f -->