# ADT Water Scene Finalizer

## Metadata

| Field | Value |
|---|---|
| Status | Implemented extraction |
| Target/work package | M03 / `M03-RND-ADT-WATER-SCENE-FINALIZER-001` |
| Owners | Main-thread ADT water subtree build, attach and optional editor ownership |
| Last verified | Worktree `work/sindo-main-codex/m03-adt-water-scene-finalizer`, 2026-07-17 |
| Profiles/capabilities | Existing ADT MH2O/MCLQ scene output; profile-independent adapter |

## Purpose

Provide one liquid-specific main-thread boundary for converting parsed ADT
water data through the existing `ADTBuilder`, attaching the resulting `Water`
subtree to a caller-owned tile root and assigning optional persisted Editor
ownership. The service is stateless and retains no Node or Resource.

## Non-goals

- Parse or validate MH2O/MCLQ binary structures.
- Replace ADTBuilder geometry, material or coordinate calculations.
- Own water request/task/result state, permits or concurrency.
- Validate tile/path/root freshness beyond receiving a valid root.
- Mark `water_loaded`, enable water or remove water subtrees.

## Context and boundaries

```mermaid
flowchart LR
    Parse[Parsed ADT Dictionary] --> Loader[StreamingWorldLoader]
    Loader -->|validated data, origin, tile root| Finalizer[AdtWaterSceneFinalizer]
    Finalizer --> Builder[ADTBuilder]
    Builder --> Water[Water Node3D or null]
    Water --> Finalizer
    Finalizer -->|main-thread add_child| Tile[Caller-owned tile root]
    Loader -->|after return| Loaded[water_loaded timing]
```

Allowed dependencies are `ADTBuilder` and Godot Node/mesh types needed to adopt
its output. WorkerThreadPool, scheduler, tile-state dictionaries, facade,
gameplay, network and editor plugin packages are forbidden.

## Public API

| Symbol | Kind | Purpose | Thread/lifetime | Errors |
|---|---|---|---|---|
| `attach_water_scene(water_data, tile_origin_godot_units, tile_root, editor_owner)` | Command/query | Build and attach one existing-format water subtree | Renderer main thread; returned Node is borrowed for tile lifetime | Empty data, invalid root or dry build returns null without attachment |

`editor_owner` is optional. When supplied it must be an ancestor suitable for
Godot `Node.owner`; ownership is recursively assigned to the generated subtree.

## Inputs and outputs

| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
|---|---|---|---|---|---|
| Input | Parsed ADT water-containing Dictionary | ADTLoader/raw tile path | Finalizer/ADTBuilder | Caller retains Dictionary; not mutated | One main-thread call |
| Input | Tile origin in Godot world units | Loader tile state/ADTBuilder | Finalizer | Value copy | One call |
| Input | Valid tile root | StreamingWorldLoader | Finalizer | Caller/SceneTree-owned | Must outlive call and attached subtree |
| Input | Optional edited scene root | Loader Editor policy | Finalizer | SceneTree-owned borrowed Node | One call |
| Output | Attached `Water` Node3D or null | Finalizer | Loader/SceneTree | Tile root owns attached Node | Tile subtree lifetime |

Side effects are limited to ADTBuilder mesh/material creation, `add_child` and
optional recursive `Node.owner` assignment. No cache, filesystem, task or tile
state is mutated.

## Data flow

```mermaid
flowchart TD
    Input[water data + Godot origin + tile root] --> Guard{Data and root valid?}
    Guard -->|no| None[Return null; unchanged]
    Guard -->|yes| Build[ADTBuilder.build_tile_water_scene]
    Build --> Dry{Water root exists?}
    Dry -->|no| None
    Dry -->|yes| Attach[tile root add_child]
    Attach --> Owner{Editor owner supplied?}
    Owner -->|yes| Assign[Assign owner recursively]
    Owner -->|no| Return[Return borrowed root]
    Assign --> Return
```

## Lifecycle/state

The service has no retained lifecycle. Each call moves one temporary builder
result through the following call-local states.

```mermaid
stateDiagram-v2
    [*] --> Validating
    Validating --> Rejected: empty data or invalid root
    Validating --> Building: valid input
    Building --> Dry: no geometry
    Building --> Attached: Water root built
    Attached --> EditorOwned: owner supplied
    Attached --> Complete: no owner
    EditorOwned --> Complete
    Rejected --> [*]
    Dry --> [*]
    Complete --> [*]
```

## Main sequence

```mermaid
sequenceDiagram
    participant Loader as StreamingWorldLoader main thread
    participant Finalizer as AdtWaterSceneFinalizer
    participant Builder as ADTBuilder
    participant Tile as Tile root
    Loader->>Finalizer: attach_water_scene(data, origin, tile, editor owner)
    Finalizer->>Builder: build_tile_water_scene(data, origin)
    Builder-->>Finalizer: Water root or null
    alt Water root exists
        Finalizer->>Tile: add_child(Water)
        opt editor owner supplied
            Finalizer->>Finalizer: assign owner recursively
        end
        Finalizer-->>Loader: borrowed Water root
    else dry/invalid
        Finalizer-->>Loader: null
    end
    Loader->>Loader: preserve existing water_loaded timing
```

## Dependency diagram

```mermaid
flowchart TB
    Loader[StreamingWorldLoader] --> Finalizer[AdtWaterSceneFinalizer]
    Finalizer --> Builder[ADTBuilder]
    Builder --> Material[WowLiquidMaterial]
    Finalizer --> Scene[Godot SceneTree]
    Pipeline[AdtWaterLoadPipelineState] --> Loader
    Scheduler[RenderBudgetScheduler] --> Loader
    Finalizer -. no dependency .-> Pipeline
    Finalizer -. no dependency .-> Scheduler
```

## Ownership, threading and resources

- The method is main-thread only because it creates Mesh/Material/Node objects
  and mutates the SceneTree.
- `ADTBuilder` owns temporary construction. It frees an empty `Water` root and
  returns null for dry/invalid liquid geometry.
- After `add_child`, the caller's tile subtree owns the returned Water root and
  all MeshInstance children; the finalizer retains no references.
- Optional editor ownership affects serialization ownership only and does not
  replace SceneTree lifetime ownership.
- Parsed Dictionaries are borrowed and not mutated.

## Errors, cancellation and recovery

| Failure | Detection | Behavior | Diagnostic | Recovery |
|---|---|---|---|---|
| Empty parsed data | Input guard | Return null, no builder call | Contract verifier | Loader preserves existing loaded timing |
| Missing/freed tile root | Input guard | Return null, no scene mutation | Contract verifier | Stale-result validation normally rejects earlier |
| Dry or malformed liquid arrays | ADTBuilder returns null | No attachment | Builder/shutdown regression | Reload after corrected source |
| Tile/path stale | Loader before call | Finalizer is not invoked | Existing loader behavior | Current tile may enqueue again |
| Shutdown/cancellation | Loader drains/cancels before call | No retained finalizer work | Shutdown verifier | New loader starts stateless |

## Configuration and capabilities

| Setting/capability | Default | Profile | Runtime mutable | Effect |
|---|---|---|---|---|
| `enable_water` | Loader setting | Quality/custom | Yes | Gates both caller paths; not owned here |
| `water_finalize_ops_per_tick` | `1` | Quality/custom | Yes | Budgets async calls before finalizer |
| `editor_persist_generated_nodes` | `false` | Editor only | Yes | Supplies or omits editor owner |

## Persistence, cache and migration

The service writes no files and changes no cache/resource schema. Existing ADT,
terrain cache and liquid material versions remain valid; no rebuild or migration
is required. Persisted Editor ownership follows the loader's existing opt-in.

## Diagnostics and observability

- Logs: none; existing loader/builder diagnostics remain authoritative.
- Metrics: no independent counters; existing water queue/finalize metrics remain.
- Debug views: generated `Water/Liquid_<id>` names remain unchanged.
- Correlation IDs: tile/path correlation stays in loader pipeline state.

## Verification

- `verify_adt_water_scene_finalizer.gd`: empty/invalid/dry guards, one-cell
  geometry, attachment, recursive owner, loader delegation and bounded timing.
- `verify_adt_water_load_pipeline_state.gd`: adjacent async ownership and loaded timing.
- Renderer material and shutdown verifiers cover material construction and dry-root cleanup.
- Fidelity evidence is the unchanged ADTBuilder implementation and unchanged two
  loader call positions; no new original-client liquid parity claim is made.
- Performance budget: 100 empty calls under one second.

## Extension points

- A future liquid renderer may replace the internal builder only after paired
  MH2O/MCLQ fixtures establish equivalent geometry/material behavior.
- Removal/eviction remains ordinary tile subtree ownership and needs no parallel API.

## Capability status

| Capability | Status | Evidence | Gap/next step |
|---|---|---|---|
| ADT water scene finalization seam | Implemented extraction | Synthetic geometry/attach/owner/source verifier | Asset-backed traversal and hitch metrics pending |
| ADT liquid geometry/materials | Existing implementation | ADTBuilder/material/checkpoint evidence | MH2O/MCLQ and original-client parity incomplete |
| Async water scheduling | Existing extracted state | Water pipeline verifier | Active worker interruption remains loader-owned |

## Known gaps and risks

- The service intentionally wraps the existing Dictionary-based ADTBuilder boundary.
- It does not verify that `editor_owner` is an ancestor; the loader supplies the
  edited scene root under the existing policy.
- Mesh/material creation remains synchronous main-thread work behind the existing permit.
- No proprietary liquid corpus, long traversal leak run, p95/p99 or paired capture is included.

## Source map

| Path | Responsibility |
|---|---|
| `src/render/liquid/adt_water_scene_finalizer.gd` | Main-thread build, attach and optional recursive editor ownership |
| `addons/mpq_extractor/loaders/adt_builder.gd` | Existing ADT liquid geometry/material creation and dry-root cleanup |
| `src/render/liquid/adt_water_load_pipeline_state.gd` | Pending/task/result state before finalization |
| `src/scenes/streaming/streaming_world_loader.gd` | Permits, stale checks, tile state and finalizer calls |
| `src/tools/verify_adt_water_scene_finalizer.gd` | Synthetic scene/ownership/boundary/timing regression |

## Related decisions and references

- [`adt-water-load-pipeline-state.md`](adt-water-load-pipeline-state.md)
- [`world-renderer.md`](world-renderer.md)
- [`render-budget-scheduler.md`](render-budget-scheduler.md)
- [`../../RENDER.md`](../../RENDER.md)
- [`../../targets/roadmap/02-rendering-and-graphics.md`](../../targets/roadmap/02-rendering-and-graphics.md)