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, src/tools/verify_adt_water_load_pipeline_state.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: ready for integration
• Done: stateless finalizer implemented; both loader water paths migrated; synthetic scene/owner regression and required documentation added
• Next: integrate and run post-merge smoke on master
• Blocked by:

Handoff

• Commit: 235be3a
• Results: scene finalizer PASS (cases=8, iterations=100, elapsed_ms=0.042; initial 0.024ms); synthetic liquid produced one four-vertex/six-index surface with tile attachment and recursive owner; water pipeline (119.648ms), WMO/M2/terrain/facade/scheduler/streaming/coordinate, materials, shutdown, internal-access 36 and 32 headless contract regressions PASS; documentation and coordination gates PASS; checkpoint dry-run PASS 7/7.
• Remaining risks: main-thread mesh/material construction remains synchronous behind one existing permit; the Dictionary builder boundary remains untyped; proprietary MH2O/MCLQ traversal/leak/p95/p99/original-client evidence is absent. A verifier launched concurrently with the initial cold editor import observed the pre-existing global-class cache race; serialized editor parse and shutdown rerun passed, with only expected missing private asset diagnostics.
• Documentation updated: inline public API; new docs/modules/adt-water-scene-finalizer.md; water-pipeline spec, module registry, world renderer and RENDER.md; data-flow/state/sequence/dependency diagrams, ownership, main-thread effects, failure/recovery, migration and source map included.