refactor(M03): extract ADT water scene finalizer

2026-07-17 09:48:56 +04:00
parent 4f8fc3b3b8
commit 235be3a36c
12 changed files with 538 additions and 31 deletions
@@ -16,6 +16,7 @@
 | Terrain chunk LOD planner | Implemented extraction | [`terrain-chunk-lod-planner.md`](terrain-chunk-lod-planner.md) |
 | Terrain chunk geometry queue planner | Implemented extraction | [`terrain-chunk-geometry-queue-planner.md`](terrain-chunk-geometry-queue-planner.md) |
 | ADT water load pipeline state | Implemented extraction | [`adt-water-load-pipeline-state.md`](adt-water-load-pipeline-state.md) |
+| ADT water scene finalizer | Implemented extraction | [`adt-water-scene-finalizer.md`](adt-water-scene-finalizer.md) |
 | M2 unique placement registry | Implemented extraction | [`m2-unique-placement-registry.md`](m2-unique-placement-registry.md) |
 | M2 placement transform resolver | Implemented | [`m2-placement-transform-resolver.md`](m2-placement-transform-resolver.md) |
 | M2 placement grouper | Implemented extraction | [`m2-placement-grouper.md`](m2-placement-grouper.md) |
@@ -38,8 +38,9 @@ flowchart LR
    State --> Result[Parsed ADT result]
    Result --> Loader
    Loader --> Budget[WATER_FINALIZE permit]
-    Loader --> Builder[ADTBuilder water scene]
-    Builder --> Scene[Main-thread tile Node attach]
+    Loader --> Finalizer[AdtWaterSceneFinalizer]
+    Finalizer --> Builder[ADTBuilder water scene]
+    Finalizer --> Scene[Main-thread tile Node attach]
 ```

 Allowed dependencies are RefCounted, Dictionary/Array/String and one Godot
@@ -127,7 +128,7 @@ sequenceDiagram
    participant State as AdtWaterLoadPipelineState
    participant Worker as WorkerThreadPool task
    participant Budget as RenderBudgetScheduler
-    participant Builder as ADTBuilder
+    participant Finalizer as AdtWaterSceneFinalizer
    Loader->>State: enqueue_request(tile key, ADT path)
    Loader->>State: take_next_request()
    Loader->>Worker: add_task(parse binding)
@@ -140,8 +141,8 @@ sequenceDiagram
    Loader->>Worker: wait_for_task_completion(task ID)
    Loader->>State: complete_active_task(key)
    Loader->>Loader: reject stale tile/path/root
-    Loader->>Builder: build_tile_water_scene(data, origin)
-    Loader->>Loader: attach Node and mark water_loaded
+    Loader->>Finalizer: attach_water_scene(data, origin, tile root, editor owner)
+    Loader->>Loader: mark water_loaded
 ```

 ## Dependency diagram
@@ -151,10 +152,11 @@ flowchart TB
    Loader[StreamingWorldLoader] --> State[AdtWaterLoadPipelineState]
    Loader --> Scheduler[RenderBudgetScheduler]
    Loader --> Worker[WorkerThreadPool / ADTLoader]
-    Loader --> Builder[ADTBuilder / SceneTree]
+    Loader --> Finalizer[AdtWaterSceneFinalizer]
+    Finalizer --> Builder[ADTBuilder / SceneTree]
    Worker -->|publish only| State
    State -. no dependency .-> Scheduler
-    State -. no dependency .-> Builder
+    State -. no dependency .-> Finalizer
 ```

 ## Ownership, threading and resources
@@ -163,7 +165,8 @@ flowchart TB
 - Worker threads may call only `publish_result`; result observe/pop/clear also lock.
 - Parsed water Dictionary identity is retained until main-thread pop.
 - Loader owns WorkerThreadPool task lifetime and must wait before orderly shutdown clear.
- Loader owns tile states, ADTBuilder, water Nodes and every render resource.
+- Loader owns tile states and the tile subtree; `AdtWaterSceneFinalizer` performs
+  the main-thread ADTBuilder call and attachment without retaining Nodes.
 - `clear` cannot cancel a worker; post-reset publication becomes a stale result
  and is discarded because no active task/tile ownership remains.

@@ -211,8 +214,8 @@ versions are unchanged; no migration or rebuild is required.
 ## Extension points

 - ADT parse execution can later move behind a parser/job adapter without changing state.
- Water scene materialization can be extracted separately because it owns Nodes
-  and main-thread effects rather than async bookkeeping.
+- Water scene materialization is now delegated to `AdtWaterSceneFinalizer`,
+  independently of this async bookkeeping service.

 ## Capability status

@@ -220,7 +223,7 @@ versions are unchanged; no migration or rebuild is required.
 |---|---|---|---|
 | ADT water load pipeline state | Implemented extraction | FIFO/task/thread/source/timing verifier | Asset-backed traversal/leak evidence pending |
 | ADT liquid parsing | Existing/loader-owned adapter | Native ADTLoader and dry-run paths | MH2O/MCLQ fidelity fixtures pending |
-| Water scene finalization | Existing/loader-owned | Scheduler/material/shutdown regressions | Separate materialization extraction possible |
+| Water scene finalization | Implemented extraction | Dedicated synthetic scene/ownership verifier | Asset-backed traversal/hitch evidence pending |

 ## Known gaps and risks

@@ -235,13 +238,15 @@ versions are unchanged; no migration or rebuild is required.
 | Path | Responsibility |
 |---|---|
 | `src/render/liquid/adt_water_load_pipeline_state.gd` | Request/task/result bookkeeping and result mutex |
-| `src/scenes/streaming/streaming_world_loader.gd` | Parse task execution, permits, stale checks and Node finalization |
+| `src/render/liquid/adt_water_scene_finalizer.gd` | Main-thread ADTBuilder call, attach and optional editor ownership |
+| `src/scenes/streaming/streaming_world_loader.gd` | Parse task execution, permits, stale checks and tile loaded timing |
 | `addons/mpq_extractor/loaders/adt_builder.gd` | ADT liquid geometry/material construction |
 | `src/tools/verify_adt_water_load_pipeline_state.gd` | Lifecycle/thread/boundary/timing regression |

 ## Related decisions and references

 - [`world-renderer.md`](world-renderer.md)
+- [`adt-water-scene-finalizer.md`](adt-water-scene-finalizer.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)
@@ -0,0 +1,232 @@
+# 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)
@@ -7,7 +7,7 @@
 | Status | Partial |
 | Target/work package | M00 baseline; `M01-RND-STREAMING-FOCUS-001`; `M01-QAR-SERVER-SPAWN-RENDERER-001`; M03 facade/planner/scheduler/internal-access/ground/environment/entity packages; M03 terrain packages; M03 M2 packages; M03 WMO placement package |
 | Owners | Renderer workstream / milestone integrator |
-| Last verified | Worktree `work/sindo-main-codex/m03-adt-water-load-pipeline`, 2026-07-17 |
+| Last verified | Worktree `work/sindo-main-codex/m03-adt-water-scene-finalizer`, 2026-07-17 |
 | Profiles/capabilities | `Performance`, `Balanced`, `High`, `Custom`; Blizzlike fidelity incomplete |

 ## Purpose
@@ -139,6 +139,7 @@ from externally reading/writing loader-private queue, task, cache and tile-state
 | `WmoRenderResourceCacheState` | Internal WMO cache-state service | Owns validated Resources, negative entries and pending cache paths | Renderer main thread; map/cache session | Invalid/occupied request and unknown completion are rejected |
 | `WmoSceneResourceCacheState` | Internal WMO cache-state service | Owns validated PackedScenes, negative entries and pending `.tscn` paths | Renderer main thread; map/cache session | Direct missing and terminal request transitions remain distinct |
 | `AdtWaterLoadPipelineState` | Internal liquid async-state service | Owns ADT water FIFO/dedupe, active task IDs and mutex result mailbox | Main-thread state; worker result publication | Invalid/duplicate requests rejected; clear does not interrupt workers |
+| `AdtWaterSceneFinalizer.attach_water_scene` | Internal liquid main-thread service | Builds and attaches one existing-format ADT Water subtree | Main thread; stateless, returned Node tile-owned | Empty/invalid/dry input returns null without attachment |

 Публичным contract не считаются `StreamingWorldLoader` methods/properties,
 внутренние dictionaries, queues, job records и generated node names. Scene-owned
@@ -361,7 +362,9 @@ sequenceDiagram
 - `AdtWaterLoadPipelineState` owns pending request order/deduplication, opaque
  active task IDs and the worker-safe parsed-result mailbox. The loader retains
  WorkerThreadPool start/wait, ADTLoader parsing, concurrency/finalize permits,
-  stale tile/path/root checks and ADTBuilder/Node finalization.
+  stale tile/path/root checks and `water_loaded` timing. `AdtWaterSceneFinalizer`
+  performs the existing ADTBuilder call, tile attach and optional recursive
+  Editor ownership on the main thread without retaining the generated subtree.
 - Rendered-ground query results and diagnostic snapshots are caller-owned values;
  the facade never returns Mesh, Node, tile-state or queue references.
 - Loaded-mesh ground sampling is renderer diagnostics, not authoritative gameplay
@@ -561,6 +564,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
 | `src/render/terrain/rendered_ground_sample.gd` | Immutable renderer-owned available/unavailable ground query result |
 | `src/render/terrain/terrain_quality_mesh_cache.gd` | Full-quality terrain revisit Mesh retention and LRU ownership |
 | `src/render/liquid/adt_water_load_pipeline_state.gd` | ADT water request/task/result bookkeeping and worker-safe mailbox |
+| `src/render/liquid/adt_water_scene_finalizer.gd` | Main-thread ADT water build, tile attachment and optional editor ownership |
 | `src/render/streaming/streaming_target_planner.gd` | Scene-free wanted/retained ADT target calculation |
 | `src/render/streaming/streaming_target_policy.gd` | Immutable renderer radius/prefetch policy |
 | `src/render/streaming/streaming_target_plan.gd` | Immutable planner result with read-only tile-key sets |
@@ -574,6 +578,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
 | `src/tools/verify_rendered_ground_sample.gd` | Cold-start renderer ground result invariant regression |
 | `src/tools/verify_terrain_quality_mesh_cache.gd` | Terrain cache admission, LRU, ownership and loader-boundary regression |
 | `src/tools/verify_adt_water_load_pipeline_state.gd` | ADT water FIFO/task/thread/boundary/timing regression |
+| `src/tools/verify_adt_water_scene_finalizer.gd` | Synthetic ADT water scene/ownership/boundary/timing regression |
 | `src/tools/verify_streaming_target_planner.gd` | Planner behavior, dependency and bounded timing regression |
 | `src/tools/verify_render_budget_scheduler.gd` | Scheduler bounds, shared-lane priority, cancellation and timing regression |
 | `src/tools/verify_renderer_internal_access.gd` | Gameplay/EditorPlugin/registered renderer-tool boundary gate derived from private streamer fields |