open-wc/coordination/claims/M03-RND-ADT-WATER-SCENE-FINALIZER-001.md

M03-RND-ADT-WATER-SCENE-FINALIZER-001 — ADT water scene finalizer

Ownership

• Target: M03
• Program: RND
• Owner/Agent ID: sindo-main-codex
• Branch: work/sindo-main-codex/m03-adt-water-scene-finalizer
• Lease expires UTC: 2026-07-20
• Integrator: M03 milestone integrator

Outcome

Extract main-thread ADT water subtree construction, tile-root attachment and optional recursive editor ownership from StreamingWorldLoader while retaining the existing ADTBuilder geometry/material implementation.

Non-goals

• Parse or reinterpret MH2O/MCLQ data.
• Own pending requests, WorkerThreadPool tasks or parsed-result delivery.
• Consume WATER_FINALIZE permits or validate tile/path/result staleness.
• Mark tile state water_loaded or choose whether water is enabled.
• Change liquid geometry, materials, coordinates, cache formats or profiles.

Paths

• Exclusive: src/render/liquid/adt_water_scene_finalizer.gd, src/tools/verify_adt_water_scene_finalizer.gd, docs/modules/adt-water-scene-finalizer.md, this claim
• Shared/hotspots: src/scenes/streaming/streaming_world_loader.gd, docs/modules/adt-water-load-pipeline-state.md, 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

• Empty water data or invalid tile root produces no Node and no scene mutation.
• Existing ADTBuilder.build_tile_water_scene remains the only geometry/material source.
• A non-empty built Water root is attached exactly once to the supplied tile root.
• Optional editor ownership is assigned recursively only when explicitly enabled and an edited scene root is available.
• The returned Node is borrowed and remains owned by the tile SceneTree subtree.

Dependencies

• Requires: accepted water pipeline package on current master e1b2886
• Blocks: further liquid finalization/material responsibility extraction
• External state: none; verification uses synthetic liquid dictionaries

Verification

• Commands: dedicated empty/invalid/build/attach/editor-owner/source/timing verifier; water pipeline, materials, shutdown, facade, internal-access, manifest, documentation and coordination gates
• Fixtures: synthetic one-cell liquid mask/heights and temporary Node roots
• Fidelity evidence: exact existing ADTBuilder output and two attachment paths preserved
• Performance budget: 100 empty finalization attempts under 1 second

Documentation deliverables

• Inline public API docs
• Module specification with inputs/outputs, ownership and source map
• Data-flow, lifecycle/state, main-thread sequence and dependency diagrams
• Water-pipeline, world-renderer, module registry and RENDER status updates

Simplicity and naming

• Important names introduced: AdtWaterSceneFinalizer
• Simplest considered solution: one RefCounted with one explicit attach operation
• Rejected complexity/abstractions: generic scene finalizer, signals, callbacks, builder interface, queue ownership or alternate liquid renderer
• Unavoidable complexity and justification: editor-persisted generated subtrees require recursive owner assignment after SceneTree attachment
• Measured optimization evidence: bounded synthetic no-water loop

Status

• State: claimed
• Done: both loader-owned water materialization call sites and policy boundaries identified
• Next: implement finalizer, migrate adapters, verify and document
• Blocked by:

Handoff

• Commit:
• Results:
• Remaining risks:
• Documentation updated: