diff --git a/coordination/claims/M03-RND-ADT-WATER-SCENE-FINALIZER-001.md b/coordination/claims/M03-RND-ADT-WATER-SCENE-FINALIZER-001.md new file mode 100644 index 0000000..75a2158 --- /dev/null +++ b/coordination/claims/M03-RND-ADT-WATER-SCENE-FINALIZER-001.md @@ -0,0 +1,93 @@ +# 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: