@woosh/meep-engine 3.47.0 → 3.50.0

package/src/engine/physics/fluid/GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md

@@ -0,0 +1,1382 @@
+# GPU fluid with scrolling cascades — proposal, 2026-10-16
+
+Status: **revision (e), nothing built.** Written against the tree at `fb0e9497b`. Paths are relative
+to `packages/meep-engine/src/`.
+
+- **Revision (a)** proposed the simulation and six forks.
+- **Revision (b)** took Alex's answers and a reuse audit.
+- **Revision (c)** answered two adversarial passes.
+- **Revision (d)** took Alex's review of (c): one infinite fluid with `GlobalFluidEffector` as its far
+  field; an acceleration structure; water reading actual velocity; queries on the system; a solver
+  that departs from the CPU's algorithms on facts, with subgroups and LDS from the start.
+- **Revision (e)** answers a reference check and a design attack on (d) (§22). Its solver numbers are
+  **measured on a CPU model of the §8 solver**, reproduced by me.
+
+No fork is open.
+
+## 0. Summary
+
+**The model is one infinite fluid.**
+- **Inside the cascades** around a domain's anchor, velocity is what the simulation holds.
+- **Everywhere else** it is the **far field**: what the scene's `GlobalFluidEffector`s make of air
+  nothing else touches, `v_far(t)`, computed once per tick on the CPU.
+- **Toward the outer edge of the coarsest cascade**, reads blend toward it.
+
+There is one wind, read one way. God of War (2018) shipped one uniform volume, with no cascades and
+no projection. Coupled cascades are new for real time; the coupling comes from atmospheric nested
+grids (WRF).
+
+**The shape:**
+
+1. **`GlobalFluidEffector` defines the far field.**
+   - `v_far = u(t) + g(t)`: `u` relaxes toward the effector's `wind` at its `drag`, and `g` is
+     `ClothAmbientWind`'s gust, moved onto the effector with its meaning unchanged and *not*
+     low-passed.
+   - The body `force` stays a CPU-field term and is not part of the far field.
+   - **Every read of a cascade at any time `t` returns
+     `v_far(t) + (v − v_far(t_s))·e^(−(Λ(t) − Λ(t_s)))`**, with `t_s` that cascade's last step and
+     `Λ = ∫drag dt`. Uniform air therefore matches the far field at every instant, on every cascade,
+     through dropped ticks. Every step applies the atmosphere through the same identity, which is
+     exact by linearity (§6).
+   - `ClothAmbientWind`, `SceneVolumetrics.wind` and `WaterWaves`' per-body wind are removed.
+2. **A domain is a `GPUFluidComponent` on an entity with a `Transform64`.**
+   - Cascades of `cell_size · 2^i` at one power-of-two resolution, placed by a clipmap module shared
+     with the VSM and the CPU fluid.
+   - Toroidal per-component `r32float` face textures. **Ghosts are never persistent**: a step writes
+     its parent's read once into transient ghosts, which its passes and LDS halos read (§7).
+3. **The solver keeps the CPU's MAC discretisation and departs from its algorithms on measured
+   facts** (§8):
+   - **Pressure:** a geometric-multigrid V-cycle with an LDS block red-black smoother and the
+     finite-volume coarse boundary weight `2/(1+h/H)`.
+     - **Measured on 64×32×64:** 0.30 residual factor per V-cycle, against red-black SOR's 0.27 per
+       16 sweeps (32 passes). **Built at S1:** 10 passes a V-cycle, two a step, ~3× faster than SOR to
+       the same residual on the 4090; a whole step costs 115 µs there.
+     - **Also measured:** carrying the CPU's open-face rule onto every level stalls the V-cycle at
+       0.75, and a frozen-halo SOR with both colours in one dispatch diverges. Both traps are written
+       into the design.
+   - **Advection:** MacCormack with manual trilinear in f32. Vulkan core guarantees only 4 bits of
+     filter weight, and the limiter needs the corners anyway.
+   - **Stencils** on LDS tiles; subgroups for appends and reductions.
+4. **Effectors and obstacles are `GPUDatabase` rows linked to transform rows.**
+   - **Each frame** a GPU LBVH is built (or refit) over their world boxes, clipped to the cascades,
+     by the engine's TLAS builder: one for each resolution a stepping cascade needs, over the
+     effectors and the obstacles at least half its cell wide, which is the resolution cull (§10).
+   - **Each brick** of each stepping cascade queries its tree cooperatively in LDS. Survivors are
+     chosen deterministically by row index, obstacles first (§10).
+5. **Consumers read one field** through `chunk_wind_field_sample`: a generalised `GPUTileAtlas3D`, a
+   per-cascade read record, and `v_far`.
+   - Water samples it per body, low-passed to sea-state timescales.
+   - Volumetrics folds the far field into its noise phases on the host, per row, and samples the
+     departure from it where the noise is evaluated, as a flow map.
+   - Particles get one VM primitive (§11, §13).
+6. **CPU readers ask `GPUFluidSystem`:** `far_field(out)` synchronously and deterministically, and
+   `request(...)` for an async lattice through `GPUDatabaseReadback`. Cloth's default source is an
+   adapter over it (§12).
+
+## 1. What the tree has
+
+Facts, from the sources, the audits and the verification passes.
+
+**The CPU solver** (MAC grid; `quality.spec.js`, `REVIEW_02_PLAN.md`) measures:
+- wall penetration exactly 0;
+- `D∘G ≡ L`;
+- sealed-vortex KE 0.80 after 1 s;
+- warm post-divergence 2.96e-2 with red-black SOR against 2.8e-4 with MIC-PCG;
+- 2.74 ms at 32×8×32 and 10.4 ms at 32³ a step.
+
+How it is built:
+- **Pressure is a projection potential in grid units:** `u −= p_R − p_L` with no dt and h = 1
+  (`v3_mac_subtract_pressure_gradient.js`).
+- **Open faces read ghost pressure 0 with weight 1** in the diagonal (`v3_grid_solve_pressure.js`).
+- **Sweeps:** `max(8, ceil(0.25 · max_res))` at `sor_optimal_omega`.
+- **Fixed step:** 0.025 s.
+
+**Effectors.**
+- `GlobalFluidEffector` integrates `force + drag·(wind − v)` exactly. **With `force` and no `drag`
+  the velocity grows without bound** (its docstring); terminal velocity needs drag. `FluidSystem`
+  applies several globals one after another.
+- Impulse and Wake triplicate their face loops and inline `(1 − t)²` four times. Wake allocates a
+  closure per `apply`.
+- `syncFromTransform` copies translation only. Both fluid systems call the shared helper
+  `fluid_sync_effectors_from_transform`, one line each.
+- A manual `Wake.apply` writes `previous_position` under a declared `Read`.
+
+**Obstacles.**
+- `FluidObstacleSystem` voxelizes through `PosedShape3D.signed_distance_at_point`, exact for every
+  shape.
+- `FluidObstacle.hash()` covers only `inflation`; shape lives on `Collider` and motion on
+  `RigidBody`.
+- ω×r is not modelled.
+
+**Cloth** reads the CPU field. `AbstractClothWind.sample` must be pure in (time, point). Its clock
+was the cloth's own age (MEASUREMENTS §57); under G2 the gust takes the scene clock and the gate is
+restated (§12).
+
+**The four winds:**
+- `SceneVolumetrics.wind`: read only by `ParticipatingMediaSystem`.
+- `ClothAmbientWind`: `gust` is a scalar peak in m/s and an exact bound, since the amplitudes 4/7,
+  2/7 and 1/7 sum to one. Per axis it is three sinusoids at rates 1, 2.41 and 5.83 of `2π/period`,
+  with phase offsets φ, 2φ and 3φ, where φ is the axis's third of a turn. Period 4 s.
+- `WaterWaves` per-body speed and direction:
+  - the cull pass sets a CPU `windy` gate from them, which gates the spectrum pass and envelope
+    seeding;
+  - `wind.w` packs the shore reflection;
+  - fetch depends on the direction;
+  - the derive pass starts a 4 s turn when the direction moves more than ~0.26°, and a later change
+    waits for that turn to finish.
+- `GlobalFluidEffector.wind`.
+
+**Cascade-like code all rolls its own.**
+- The VSM is the only live toroidal clipmap.
+- One hysteretic snap is copied twice.
+- Toroidal wraps sit at ~10–13 sites.
+- `GPUClipMap3D` is broken and is retired under G1.
+
+**The engine already builds BVHs on the GPU.**
+- `graph_bvh_build_lbvh` is **19 dispatches**: Morton, four digits of histogram + CSDLDF prepare +
+  scan + scatter, emission, refit (`GPU_BVH_BUILD_PLAN.md`: "~0.15 ms … across all 19 dispatches",
+  measured outside a frame).
+- `GPUInstancesAccelerationStructure` drives it, and rebuilds only when its version moves:
+  - the host seeds ±inf with `encoder.writeBuffer`;
+  - the extraction pass (`shader_bvh_extract_instance_leaves`) writes leaf boxes and reduces their
+    union with subgroup min/max plus one atomic. Any bound on every centroid is valid.
+  - Leaves come from a CPU-compacted row list (`#refresh_rows`), because Karras breaks Morton ties by
+    leaf index.
+- The build is deterministic for an ordered set of finite leaves: the radix sort is stable.
+- The plan's motivations include that "the CPU cannot see GPU-authority transforms". The GPU tree
+  beat the CPU one on every axis at 20k instances, and was 1.9× worse in SAH at ~100.
+- Traversal is the stack loop in `chunk_sdf_query_distance` / `chunk_ray_query_*`
+  (`BVH_TRAVERSAL_STACK_SIZE` 32, no visit cap). No AABB-overlap query exists.
+
+**Subgroup-aggregated appends and reductions exist.**
+- `chunk_vsm_append_mover` does exclusive add, `subgroupAdd`, elect, one `atomicAdd`, broadcast, and
+  counts past capacity.
+- Min/max reductions: `shader_bvh_extract_instance_leaves`, `shader_meshlet_bounds_reduce`,
+  `shader_depth_reduce` and `shader_csm_caster_range`. The last records a measurement: a subgroup
+  reduction plus one atomic sufficed, and a workgroup step through shared memory measured the same.
+- f32 sums: `sh_exp_workgroup_sum` (one vec4, valid in invocation 0, callable once a kernel because
+  its counter is never reset), the SH projection and the multiscatter LUT.
+- **Three engine shaders state that local invocation indices need not map to subgroups in contiguous
+  blocks**, while three others assume they do.
+
+**ECS-driven GPU work.**
+- The `WaterSystem` / `GPUWaterSurface` shape.
+- `GPUDatabase` tables, with the particle database's cross-database `node` link.
+  `GPUParticleEmitterSystem.apply_particle_effect` **compares each field while assigning it**: no
+  change signal and no hash. A generic accessor measured 228 B of boxing a call.
+- `water_waves` mixes CPU-authored and GPU-derived fields ("the CPU writes what is authored … the GPU
+  writes what it derives").
+- Transforms rows hold `global` and `prev_global`. Node globals are current at `FrameStart`:
+  `scene.tick` is encoded before the extensions.
+- `TRANSFORM64_EVENT_PLACED` signals a teleport.
+- `GPUSceneVolumetrics` clears and refills the whole volume table on every version change, inverting
+  a matrix and allocating a `Float32Array(16)` per repack. A non-zero noise velocity bumps the
+  version every frame. *Resolved in S3 (§6, D14): a scroll moves `SceneVolumetrics.noise_version`
+  alone and writes each moved row's six phase words; the repack keeps its scratch.*
+
+**Constraints.**
+- A tiny compute pass costs 5–8 µs. *(S1 measured back-to-back small dispatches at 1–2 µs on the
+  4090; §14.)*
+- No read-write storage textures are in use.
+- `r32float` is core write-only storage and not filterable.
+- Default limits: 16 KiB of workgroup memory, 256 invocations, 4 storage textures a stage, a floor of
+  10 storage buffers.
+- `shader_water_cull` already binds 10 storage buffers.
+- Subgroups are optional in the floor and required in practice.
+- Barrier kernels cannot run whole under the emulator.
+- I-4: GPU readback never reaches gameplay.
+- `getAnyComponent` allocates per call.
+
+## 2. What the field ships
+
+Each source is tagged:
+- **VERIFIED**: the primary text was read.
+- **SECONDARY**: only an abstract, documentation or a write-up was read.
+- **MEASURED**: our own CPU model.
+
+**God of War (2018), Renard, GDC 2019 (VERIFIED).**
+- One 32×16×32 volume at ~1 m, shifted with the player.
+- Three-tier sampling: a static global vector, plus the volume, minus the object's own velocity.
+- No projection.
+- Motors: directional, omni, vortex, moving cone, cylinder.
+- CPU audio and cloth read the previous frame.
+- ~0.1 ms on PS4.
+
+**NVIDIA Flow (VERIFIED, source).** One cold-started geometric-multigrid V-cycle a step (one Jacobi
+smooth per level, four on the coarsest). The fallback is 40 Jacobi iterations.
+
+**Cohen, Tariq & Green, I3D 2010 (SECONDARY).** A full multigrid cycle plus two V-cycles bought ~5
+orders of magnitude. A warm start with flux prescribed on every face grew noise (the Neumann null
+space). Uncoupled grids, blended near their edges.
+
+**WRF (VERIFIED).** Nests specified from the parent; two-way face-mean feedback; Davies relaxation
+`F1 = (1/10Δt)·(6 − n)/4`, n = 2..5; a moving nest's leading edge filled from the parent.
+
+**Harris & Durran (SECONDARY).** Two-way nesting plus relaxation leaves negligible reflections.
+
+**Filter precision (VERIFIED, Vulkan).** `subTexelPrecisionBits` must be at least **4 in core**, 8
+under Roadmap 2022 / Vulkan 1.4 (docs.vulkan.org). D3D11 requires 8 (SECONDARY). WebGPU exposes
+neither.
+
+**Multigrid on this operator (MEASURED).**
+- **Setup:** a CPU model of §8 (`mg2.mjs`, `sor.mjs` in the session scratchpad; random RHS, zero
+  guess, asymptotic factors): 64×32×64 coarsened to 4×2×4, 8-child-mean restriction, trilinear
+  prolongation, red-black Gauss–Seidel with ν = 2 + 2.
+- **Residual factor per V-cycle:**
+
+  | | Global smoother | 8×8×4 frozen-halo block smoother |
+  |---|---|---|
+  | The CPU's open-face rule on every level | 0.661 | 0.750 |
+  | Finite-volume weight `2/(1+h/H)` | 0.103 | 0.296 |
+
+  The CPU rule puts the coarse Dirichlet point H/2 too far out, so the coarse correction overshoots
+  about 2×.
+- **Depth and coarse-solve budget don't matter here.** With the block smoother and the finite-volume
+  weight, stopping at 8×4×8 (4 levels) gives the same 0.296 as stopping at 4×2×4 (5 levels). That
+  holds with 32, 64 or 400 sweeps on the coarsest level. The fine-level block smoother sets the
+  factor.
+- **Red-black SOR at `sor_optimal_omega` (ω = 1.9065):** global, 0.267 after 16 sweeps and 2.2e-3
+  after 64. Run as a frozen-halo block with both colours per dispatch, it grows 2.2e2 after 16 and
+  9.9e12 after 64.
+- **The model-problem bound** `ρ = ω − 1 ≈ 0.9065` at that ω predicts 0.21 after 16 sweeps.
+
+**Others (SECONDARY):**
+- McAdams 2010 MGPCG: robust with irregular boundaries; needs a symmetric V-cycle.
+- Compact Poisson Filters (Jacobi-bounded); covector fluids (conditionally stable).
+- Lattice Boltzmann (dt tied to cell size).
+- VXGI, Insomniac and RTXGI clipmap scrolling.
+- The vgeo wavefront traversal precedent in this tree.
+
+## 3. Requirements
+
+- **Real time in a browser, on modest GPUs.** No async compute; pass count and bandwidth both count;
+  dispatches follow live counts.
+- **Every per-thread loop has a small fixed budget**, and the product of nested budgets is stated.
+- **Subgroups and LDS from the start.**
+  - Stencil passes are LDS tile passes.
+  - Appends and reductions are subgroup-aggregated.
+  - No subgroup layout is assumed: partials take a subgroup reduction plus one atomic, which is what
+    CSM measured as enough.
+  - Barrier kernels keep their per-cell maths in pure functions for the emulator (§15).
+- **One identity, two complete worlds.** Headless runs; gameplay never reads the GPU. CPU work is
+  O(changes + effectors + obstacles + queries).
+- **Keep the effector framework.** The kernel skips an inexpressible effector explicitly, and it is
+  asserted in dev.
+- **One fluid, read one way. No static/dynamic distinction.**
+  - Membership changes and drop counts are runtime facts, never authored categories.
+- **Reuse first, generalise rather than copy** (§4, §19).
+- **Binding budget:** the floor is 10 storage buffers. The water cull is already at 10, so the field
+  adds none there. Fluid passes stay ≤ 8 by choice, to leave headroom.
+
+## 4. The reuse map
+
+The verdicts used below:
+- **REUSE**: as is.
+- **GENERALISE**: grows a parameter or variant, and its clients move onto it.
+- **EXTRACT**: becomes shared, and its system migrates.
+- **COMPOSE**: built from existing pieces.
+- **NEW**: written generic, with a JS↔WGSL parity spec when it has both forms. Specs follow
+  `chunk_v3_apply_quat.spec.js`: top-level, no hooks.
+
+### 4.1 CPU side
+
+| Need | Engine machinery | Verdict |
+|---|---|---|
+| Hysteretic snap; window origins; exposed regions | `fluid_reanchor_field.js:70-73`, `VirtualShadowMap.js:223-227`; `VSMPageManager` | **EXTRACT** `quantize_hysteretic`, `ClipmapWindowSet`, `window_scroll_regions`; the VSM and the CPU fluid migrate |
+| Per-tick effector life and the far field | `fluid_sync_effectors_from_transform`, called by both fluid systems | **EXTRACT** `FluidEffectorsSystem`: once a tick it syncs transforms, calls a new `advance(dt)` on every effector (gust phases), folds the globals and integrates `v_far` and `Λ` (§6) |
+| Far-field relaxation | `GlobalFluidEffector`'s exact ODE | **REUSE** for `u(t)` |
+| Gust | `ClothAmbientWind` | **EXTRACT** into `GlobalFluidEffector`, meaning unchanged; `ClothAmbientWind` retired |
+| Shape parameters as a record | cloth `ClothColliderKind`, `ClothColliderRecord` `PARAM_0..3`, `cloth_collider_pack` | **EXTRACT** the shape half into core; cloth composes it. Extended: rigid `Transformed`, `Union` runs, hull planes (zero planes skipped, capped at 16). |
+| CPU obstacle SDF | `PosedShape3D.signed_distance_at_point` | **REUSE**: the CPU stays exact and is the oracle |
+| Segment distance, AABB tests | `line3_compute_segment_point_distance*`, `aabb3_intersects_aabb3`, `aabb3_expand_array` | **REUSE**; inline copies migrate |
+| Falloff, cone clamp, swirl, rigid velocity | inline / `v3_slerp` + `v3_angle_between` / none / inline at ≥ 10 physics sites | **NEW** `falloff_quadratic`; **COMPOSE** `v3_clamp_to_cone`; **NEW** `vortex_swirl`; **NEW** `rigid_velocity_at_point` (physics sites only under a flat allocation budget and bench) |
+| Change detection | `apply_particle_effect`: compare each field while assigning | **REUSE as pattern**: rows are written only when a record field differs. Pose is excluded, since it comes from the node row. Obstacles compare their encoded shape parameters, inflation, v and ω. |
+| Teleport | `TRANSFORM64_EVENT_PLACED` | **REUSE**: `GPUSceneRows` seeds `prev_global = global` on it |
+| CPU lattice sampling | `scs3d_sample_linear3_array` (planar) | **GENERALISE**: a strided variant |
+| Row holds, record writer, singleton | `RowChains`, `generate_record_writer`, `getAnyComponent` | **REUSE**; **GENERALISE** a non-allocating singleton accessor |
+
+### 4.2 WGSL
+
+| Need | Engine chunk | Verdict |
+|---|---|---|
+| Toroidal coordinate; finest containing cascade | `chunk_mod_v3i`; CSM blended-cascade shape | **REUSE** in `chunk_clipmap_storage_coord`; **NEW, concrete** `chunk_clipmap_select_finest` |
+| Flat ↔ 3-D index | `chunk_grid3d_to_index`, `chunk_index_to_grid3d`, `chunk_folded_workgroup_index` | **REUSE** |
+| 3-D tile + halo | none: 31 LDS shaders, mostly 1-D, none a 3-D tile | **NEW** `chunk_grid_tile_halo_f32` / `_vec4`: window-local indexing, toroidal wrap by conditional subtract, a caller-supplied out-of-window fetch, one barrier |
+| Trilinear corners; 3-D texel helpers | inside `chunk_sdf_texture_region_sample_linear_uv`; 2-D helpers | **EXTRACT** `chunk_texture3d_trilinear_corners`; **GENERALISE** 3-D siblings |
+| Primitive SDFs | box inside `chunk_aabb3_signed_distance_to_point`; plane `chunk_point_distance_above_plane` (`+w`); max of planes `chunk_frustum_sdf` | **EXTRACT** box; **REUSE** plane (`w = −offset`) and max of planes; **NEW** sphere, capsule, cylinder |
+| Segment distance; cone clamp; AABB overlap | `chunk_point_distance_to_line` (unguarded); `chunk_v3_angle_between`, `chunk_quat_from_unit_vectors`, `chunk_quat_rotate_v3`; none | **GENERALISE** (guard + spec); **COMPOSE**; **NEW** `chunk_aabb3_intersects_aabb3` |
+| BVH build | `graph_bvh_build_lbvh` (19 dispatches), refit via its returned Morton order | **GENERALISE**: a small-scene path. At ≤ 1,024 leaves (one sort tile), one 256-thread workgroup builds the whole tree in one dispatch, with Morton, a (key, index) bitonic sort in workgroup memory, emission and refit, reusing the builder's chunks. Above 1,024 the multi-pass path is unchanged. The TLAS gains the same path for small scenes. **Landed** on master `b523718db` (2026-10-16), with `chunk_sort_bitonic_comparator`, which the cooperative query also sorts with. |
+| Leaf extraction + centroid bound | `shader_bvh_extract_instance_leaves` (subgroup min/max + one atomic, host-seeded ±inf) | **REUSE as template** |
+| BVH query | traversal loops (ray, point, distance; no visit cap) | **NEW** `chunk_bvh_query_aabb_cooperative`: one workgroup per query box, a level-synchronous frontier in LDS (the vgeo wavefront precedent), so per-thread work is bounded by tree depth |
+| Append | `chunk_vsm_append_mover` | **GENERALISE** into a `COLLECTION_U32` append; the VSM migrates; the fluid's lists use it |
+| Reductions | `chunk_atomic_{min,max,add}_f32_storage`; the CSM measurement | **REUSE**: subgroup reduction + one atomic, no workgroup step, no layout assumption |
+| Node pose; indirect command | `scene_read_node`; `build_indirect_compute_dispatch_command` | **REUSE** |
+| MAC maths | CPU `v3_mac_*`, `v3_grid_limit8_at_indices`, `v3_mac_clip_trace` | **NEW** `chunk_v3_mac_*`: per-cell pure functions over a tile accessor (§15) |
+
+### 4.3 Host and GPU infrastructure
+
+| Need | Engine machinery | Verdict |
+|---|---|---|
+| Records | `GPUDatabase`; the particle precedent (own database, cross-database `node` link) | **REUSE**: `FLUID_DATABASE_SPEC` |
+| Readback | `GPUDatabaseReadback` (consecutive rows coalesce); `GPUEntityBoundsReadback` | **REUSE** + **GENERALISE** `request_run` (one handle and status per query, a smaller upload) |
+| Published atlas | `GPUTileAtlas3D` | **GENERALISE**: per-axis content + `chunk_tile_atlas_slot_origin` on `chunk_index_to_grid3d`; the noise tap and the SDF slot maths migrate |
+| Volume phase writes | `GPUSceneVolumetrics` (full repack on version) | **GENERALISE**: phase fields written per row with `set_fields`, so no repack and no per-repack allocation for a moving phase (§6) |
+| Textures, transients, passes, profiling | `GPUTextureContext`, 3-D `TextureResourceDescriptor`, `ComputeShader`, `setImmediate`, upload helpers, `push_scope`, `GPUProfileSession`, `graph_record_stat` | **REUSE** |
+| Producer lifecycle; pass shape | `GPUWaterSurface`; the volumetric TAA pass | **REUSE as pattern** |
+| 3-D debug view | `draw_texture_as_rgba` | **GENERALISE**: a 3-D slice mode; `shader_debug_clipmap` rewritten as the cascade overlay (G1) |
+
+## 5. Architecture
+
+```
+ECS (engine/physics/fluid/ecs/)                      Graphics (engine/graphics3/, shade/renderer/fluid/)
+──────────────────────────────────────────────       ──────────────────────────────────────────────────
+FluidEffectorsSystem (once a tick):                  GPUFluidSystem(graphics, scene)
+  syncFromTransform; advance(dt);                      CPU, headless-safe: far_field(out), request()/status
+  fold globals → v_far(t), Λ(t)  ─────────────────►     (from FluidEffectorsSystem; far field when no device)
+FluidSystem / WorkerFluidSystem (CPU fields)           GPU, FrameStart: rows → LBVH (build/refit, once a frame)
+  apply the folded atmosphere once per step            → per pending tick: brick queries → forcing → cascade
+GPUFluidComponent + Transform64 ─────────────────►       steps → publish → GPUSceneContext.wind
+FluidEffectorsComponent / FluidObstacle tuple ───►    GPU consumers: particles VM, water cull, query gather
+CPU consumers ask GPUFluidSystem: cloth adapter,       → chunk_wind_field_sample(p)
+  volumetrics, audio
+```
+
+**`FluidEffectorsSystem`** (extracted; its name matches `FluidEffectorsComponent`). Once per tick,
+before every fluid system (declared `Write` on `FluidEffectorsComponent`; the fluid systems declare
+`Read`):
+- `syncFromTransform` for entities with a `Transform64`;
+- `advance(dt)` for every effector;
+- the fold and the far-field integration (§6).
+
+It is the single owner of `v_far` and `Λ`, so no trail, phase or far field is advanced twice. The
+fluid systems drop their own sync line. The census runs before and after.
+
+**`GPUFluidComponent`.** Data only, adapter v0:
+- `resolution`: per axis, a power of two in [32, 256];
+- `cell_size`;
+- `cascade_count` (1..8);
+- `vorticity_confinement`;
+- `enabled`.
+
+There is no `velocity_damping`, because relaxing toward zero fights the far field.
+
+**`GPUFluidSystem`** (`engine/graphics3/`, registered wherever `WaterSystem` is):
+- **CPU half, headless-safe:** `far_field(out)` and `request(...)`.
+- **GPU half (`FrameStart`):**
+  - records pending ticks (`fixedStepTick` minus the last recorded, capped at 2; the excess is
+    counted);
+  - keeps the fluid database, the LBVH, the cascades and the published field;
+  - rebuilds on restart;
+  - holds rows with `RowChains`.
+- **`GPUSceneContext` always constructs a `GPUSceneWind`** (zero cascades, `v_far` = 0), so consumers
+  can bind it unconditionally with no fluid system present. `GPUFluidSystem` fills it.
+
+*S4, built (2026-10-16): `GPUFluidComponent` (adapter v0, 24 bytes) and `GPUFluidSystem`, registered beside
+`WaterSystem` in `EngineHarness`.*
+- **Ticks.** At `FrameStart`, the ticks `fixedStepTick` advanced since the last recording frame, at most two
+  (the latest), the rest counted (`dropped_tick_count`); each steps at `fixedUpdateStepSize` against the far
+  field at the end of the frame's last tick. Then `record_publish`, and the field's table is uploaded at once,
+  since the scene context uploads it before `FrameStart`.
+- **Node motion** is taken over `1/(frame_dt·fixedStepTimeScale)`, `frame_dt` the wall time the system's
+  `update` saw since the last `FrameStart`: the hierarchy pass copies `global` into `prev_global` once a
+  rendered frame.
+- **Rows** are kept in `update`, so a chain held this frame is in the scene's rows before the frame reads it.
+  Effector membership is by identity; an obstacle is packed again when its collider is handed another shape.
+- **No domain:** nothing is recorded or held on the device, and the wind field is `v_far` alone.
+- **One domain** (F2, R1): the enabled component on the lowest entity id. Any other is dormant and holds
+  nothing on the device until it takes over (§18).
+- `vorticity_confinement` reaches every step of every tick (S4d, §8): `record_tick`'s
+  `vorticity_confinement`, read from the component each frame, the cascades kept.
+
+## 6. The far field, and what reads the fluid
+
+**`GlobalFluidEffector`** keeps `force`, `wind` and `drag`, and gains:
+
+```js
+gust        = 0   // m/s, scalar peak — ClothAmbientWind's meaning: a bound, |g| ≤ gust per axis
+gust_period = 4   // s
+// state, advanced by advance(dt): phase_k ← frac(phase_k + dt·rate_k/period), rates 1, 2.41, 5.83
+```
+
+`g_axis(t) = gust · Σ_k a_k · sin(2π·phase_k + (k+1)·φ_axis)`, with amplitudes 4/7, 2/7 and 1/7 and
+φ the axis's third of a turn. That is `ClothAmbientWind` term for term. The phases are integrated, so
+editing the period never jumps.
+
+**The fold and the far-field state** (`FluidEffectorsSystem`, f64, once per tick):
+- **Fold:** `D = Σd`, `W = Σd·w / D` (the globals' steady winds), `g = Σ gusts`.
+- **Steady part:** `u ← W + (u − W)·e^(−D·dt)`, exact. It is seeded at `W` only on
+  `FluidEffectorsSystem`'s first fold, so a scene that starts with a global starts in steady state;
+  a global that arrives later relaxes `u` from where it is; `u` holds when `D = 0`.
+- **State:** `v_far = u + g`. `Λ += D·dt`.
+- **The gust is added, not filtered.** Filtering it through `drag` kept only 16% / 61% / 84% of the
+  authored gust at the drags in the tree's specs (0.35 / 2 / 5), shrinking cloth gusts 2–6×.
+- **`force` is not part of the far field.** A world-wide body force would be an unbounded downdraft
+  at `D = 0`, and a world downdraft read by water and cloth at `D > 0`. It stays a CPU-field term, as
+  today. The GPU path drops it, with a dev assert, and buoyancy is its successor with scalars (§20).
+- A scene that never had a global is still air; after the last global goes, the far field holds —
+  calm is authored as a global with wind 0 and a drag.
+- **The far field's state is warmed up, never saved** (Alex, 2026-10-16: "warm up instead of saving
+  the state … like particle simulation state - it's inherently transient"). `u`, `Λ` and the
+  cascades live on the systems; a load or a restart seeds `u` at the globals' `W` on its first fold
+  and the cascades at `v_far`, and a rollback re-simulates nothing of them. Only the effectors'
+  authored fields and gust phases are saved.
+
+**The atmosphere identity.**
+- At every step (both executors): `v ← v_far(t₁) + (v − v_far(t₀))·e^(−(Λ(t₁) − Λ(t₀)))` per face.
+- At every read of cascade *c*: `v_read = v_far(t) + (v_c − v_far(t_s,c))·e^(−(Λ(t) − Λ(t_s,c)))`.
+  `t_s,c` is the cascade's last step, recorded with `v_far(t_s,c)` and `Λ(t_s,c)`.
+- **Why it is exact:**
+  - Air that only the atmosphere acts on relaxes toward `v_far` at `D` while carrying `v_far`'s own
+    acceleration. Its deviation `e = v − v_far` obeys `de/dt = −D·e` for any `v_far(t)`, so the
+    update is exact whatever the gust does and however `D` varies (`Λ` integrates it).
+  - A cell equal to the far field reads as the far field at every instant, on every cascade, between
+    steps and across dropped ticks.
+- **What it replaces in revision (d):**
+  - the far-field ring, and its off-by-one;
+  - the published tile frozen against the live far field between a coarse cascade's steps;
+  - the parent reads that saw a stale uniform part.
+- **CPU consumers of the identity:**
+  - The GPU gets per cascade one uniform pair, `v_far(t_s,c)` and `k_c = e^(−(Λ(t) − Λ(t_s,c)))`,
+    computed on the CPU each frame: one FMA a read, and no large numbers on the device.
+  - **The CPU fluid applies the same folded atmosphere once per step** through the same identity, so
+    the executors agree exactly. Several globals no longer split order-dependently, and `force`
+    still adds `F·dt` inside CPU fields.
+
+**The read, everywhere:**
+- the finest cascade containing the point, through its identity;
+- in a cascade's edge band, blended with its parent's identity read, and in the coarsest cascade's
+  band, blended with `v_far`;
+- outside every cascade, `v_far`.
+
+**What reads it:**
+
+| Consumer | How |
+|---|---|
+| Particles | `SAMPLE_WIND` → `chunk_wind_field_sample` |
+| Water | **Built (S3).** The cull pass samples `wind_field_sample` 10 m above each body's origin (U10), binding the field's uniform, texture and sampler: its storage buffers stay the ten it had, at the floor. **One** per-body low-pass of the sample, `wind ← s + (wind − s)·e^(−dt/20 s)` over the frames that step, in a GPU-written wave-row field (`wind` + `wind_seeded`) and seeded from the first sample whether the frame steps or not, feeds fetch, the derivation and the turn, taken in the body's metric local xz. A derivation fires only when the low-passed wind leaves a deadband about what it was derived for (5% of speed, 3° of direction; `derived_for` is now speed, fetch and direction) or the fetch along that direction changes; a turn only when the direction leaves 3° of the one the waves turned to; a change during a turn waits for it, as before. Every body's wind is kept, hidden ones too, since their weights bound them. `windSpeed`/`windDirection` left `WaterWaves` (adapter v2, `WaterWavesSerializationUpgrader_1_2` drops them). The record's re-layout keeps the shore reflection, as `shore_reflection`. **The CPU `windy` gate** is "any enabled `GPUFluidComponent`, or `far_field` non-zero", without allocating (`getAnyComponentInstance`; the others are walked only when the lowest holder is disabled). **Measured** (RTX 4090): an impulse at the lake's U10 point, inside a domain's cascades, moved the lake's wind 0.75 m/s off a body outside them in 20 s; the culling dispatch 49 → 54–56 µs on four bodies; the frame unchanged within its run-to-run spread. A seed carries the gust of its instant (up to `gust` per axis), which the low-pass forgets over ~20 s. |
+| Volumetrics | **Built (S3), reworked on Alex's correction (§22).** **The far field is the host's:** `ParticipatingMediaSystem` folds `GPUFluidSystem.far_field` (the effectors' fold: synchronous, deterministic, nothing read back) × `noise_wind_factor` + `noise_velocity` into each noisy volume's phases; no `GPUFluidSystem` is still air. **The departure is the GPU's, wherever the noise is evaluated:** the froxel build samples `wind_field_sample` once a froxel at its jittered noise point, the tracer and the bakes at each density point (`participating_media_volume_density_at`), and `chunk_participating_media_noise` carries the noise by `d = (w(p) − v_far(t)) × noise_wind_factor` as a flow map: two phases half a period apart, `φ₀ = fract(s)`, `φ₁ = fract(s + ½)`, each moving the lookup by `−d·φₖ·P` (tile units), triangle-weighted so each resets at zero weight, the warp tap shared; `s = t/P` is a per-row word the host folds (`noise_flow_phase`, beside `noise_wind_factor` in the row's padding: still 240 B). Below a reach of `1/(2·255·35.3)` = 5.6e-5 tile units a period one tap, the uniform-air path (the tile's steepest gradient, read back, is 35.3 a tile unit, so the neglect is under half an `r8unorm` step); the reach ramps in to twice that, so the branch is continuous. **P = 2.5 s:** the pulse (rms of the crossfade term over the transport term, a function of `λ = |d|·P/noise_scale` alone: ~1 to λ ≈ 0.08, 0.47 at 0.32) and the stretch (`σ_max(I − φ·P·∇d) − 1`) medians cross at 2.48 s where |d| ≥ 1 m/s at the default 32 m scale (2.06 s at 16 m, 2.4–2.9 s over |d| ≥ 0.5 m/s), measured on the 4090 over a wake circling at 10 m/s beside a vortex. Every reader binds the field (uniform, texture, sampler; no storage buffer). **The phases go up per row with `set_fields`**: a scroll or the flow clock moves `SceneVolumetrics.noise_version` (`invalidate_noise()`) and not the version, and `GPUSceneVolumetrics` writes the seven phase words of each row whose f32 phases changed; anything else still repacks. The system compares while assigning and reads the transform's lanes; `set_fields` asserts with constant messages. `SceneVolumetrics.wind` is removed. **Measured:** the froxel build on the 4090 at 1280×720, the camera inside the fog, A/B against the old shader by frame blocks in one capture: uniform air 16.4 → 18.3 µs, with a domain, a wake and a vortex 15.4 → 19.4 µs; the uniform-air 1.9 µs is the flow map's code being there (without it 0.1–0.2 µs off the old; skipped by an exact compare, still 1.8). In calm air with a domain, the frame-to-frame change of the picture gathers around the vortex and the wake's path; without one the fog stands. *The S3 per-row write, in node with 64 noisy volumes: `GPUSceneVolumetrics.update` 41.5–46.5 µs and 72.3 KB a frame → 2.6–2.7 µs and nothing a volume.* |
+| Cloth | `ClothGPUFluidWind`, an adapter over the system (§12). `ClothAmbientWind` is retired. `ClothFluidWind` stays for CPU fields with `ambient = far_field`. |
+| Audio, presentation | `request` or `far_field` |
+| Gameplay | `far_field` only. It is deterministic given the effectors' serialized phases (§16); the fluid is presentation (I-4). |
+
+**Playground cost.** The water-surface playground's four per-body winds (cup 2, puddle 4, lake 6, ocean
+10 m/s) became one fluid: a `GlobalFluidEffector` far field (8 m/s by default, a gust slider) and a
+`GPUFluidComponent` on the stop's body. Sea states differ by fetch and by the field around each body: at
+8 m/s the ocean is a little lower than at its old 10, the others higher; all four stay recognisable
+(screenshot tour against the previous tree). On the 4090 at the ocean stop a frame that ticks spends 339–367 µs
+in fluid passes with a coarse step and 189–195 µs without (p10 of per-frame timestamps), the bonfire's tick less
+its forcing (§14). *S3 first read 1.09–1.13 ms a frame from 2.5 s captures in which every water pass also ran
+~3× its time (coherent optics 1.77–2.19 ms against 0.64–0.70): the GPU was slow then, not the fluid (§14).*
+
+## 7. The shared clipmap module, and the cascades on it
+
+**The module** (`core/geom/clipmap/`):
+- `quantize_hysteretic`;
+- `ClipmapWindowSet` (integer corners, placed flag, version, `place`, `contains`, `storage_cell`,
+  `decode`);
+- `window_scroll_regions` (disjoint k-D boxes);
+- WGSL: `chunk_clipmap_storage_coord`, `chunk_clipmap_contains`, `chunk_clipmap_select_finest`.
+
+**Migrations:**
+- the VSM's window bookkeeping and strip eviction (scroll specs re-pointed, masks unchanged);
+- the VSM depth snap and `fluid_reanchor_field` onto `quantize_hysteretic`;
+- the CPU fluid's patch edges stay: corner order is load-bearing, and they were judged not worth
+  unifying.
+
+**Cascades.**
+- `N = resolution` per axis, all active. Cell `h_c = cell_size · 2^c`.
+- Corners are multiples of 4: even for exact restriction, and in 4s for brick alignment of
+  cell-centred data.
+- **Re-placement:** when the anchor is more than 2.1 cells from the window centre, on the cascade's
+  own step tick, coarsest first.
+- **Nesting:** the child's corner is clamped into its parent's interior. *S2:* the interior is the
+  parent's window less the published read's edge band, 5 parent cells (`FLUID_CASCADE_NEST_MARGIN`),
+  so a read never needs a third tap; on the 4-cell corner lattice the margin kept is 6, so cascades
+  nest from 32 cells an axis. A parent placing on its own tick is held the same way by its unmoved
+  child. Measured cost (20,000 ticks of a random walk at 64×32×64): nothing held off its own placement
+  at 10 m/s; at 40 m/s with vertical motion, 0.4–0.8% of ticks, the anchor at most 7.1 of cascade 0's
+  cells from its centre on the 32-cell axis.
+- **Jumps:** a jump that would leave a child outside its parent re-places the whole stack.
+- **Exposed regions** refill from the parent's identity read, or from `v_far` with pressure 0.
+- **The far field is a parent with no window**, which reads `v_far` and pressure 0 (*S2*).
+
+**Storage.**
+- `u`, `v`, `w` are `r32float` 3-D textures of (N+1)×N×N, N×(N+1)×N and N×N×(N+1), each toroidal
+  with period N+1 along its own axis and N on the others. Every face of the window is stored, and a
+  scroll by Δ exposes and vacates Δ slots on every axis.
+- **Pressure:** `array<f32>` of N³, period N, **physical kinematic pressure (m²/s²)**, so
+  `u −= (dt_c/h_c)·(p_R − p_L)`.
+- **Units across cascades:** parent and child pressures share units, so Dirichlet halos and fill warm
+  starts need no rescaling. The CPU's projection potential (grid units, no dt) is the same field
+  scaled by `dt/h²`, and parity specs apply that scale.
+- **Ghosts are never persistent.** A step's first pass (`shader_fluid_cascade_ghosts`) evaluates
+  the parent's read once into the step's transients: its identity read at every face of a shell
+  `FLUID_CASCADE_GHOST_DEPTH` = 6 faces deep around each face lattice, and its pressure at the
+  centre of every cell one past the window. A tile at the window edge takes its halo from them
+  (pressure, Dirichlet; tangential velocity, through the identity), and an advection corner outside
+  the window reads one texel of them where the parent read takes eight. The depth holds every read
+  of a step whose far field crosses at most a cell (a carrier one face out, a trace of
+  `|v_far|·dt/h + 4` cells under the deviation clamp, its tap one more); a read past the shell takes
+  the parent itself, so the depth sets the cost, never the answer.
+- **Tiles are window-local**, 8×8×4: `N/8 × N/8 × N/4` tiles. Storage indices come from a
+  conditional subtract, because the face period N+1 is odd. The +boundary face plane, index N, is
+  owned by the last tile along its axis in every pass that writes faces (advect correct, gradient,
+  fill).
+
+**Scroll fill.** `window_scroll_regions` gives bricks, and one dispatch writes faces and pressure.
+*S2:* 4×4×4 bricks tile the boxes exactly; the dispatch is the live brick count, folded past 65,535.
+Fills, steps and seams read a parent as of the reading cascade's own record, so a newer parent's
+deviation is read back by `e^(+ΔΛ)`, its exponent held at 64.
+
+## 8. The solver step
+
+**Kept from the CPU, all measured in its gate and GPU-neutral:** the MAC discretisation (wall
+penetration exactly 0, `D∘G ≡ L`), MacCormack with Selle's limiter and solid-clipped traces,
+semi-Lagrangian scalars, open boundaries and warm starting.
+
+**Departs, on measurement:**
+
+**(1) Pressure: a geometric-multigrid V-cycle.**
+- **Cell-centred**, coarsening N → N/2 down to the first level that fits one workgroup at one cell
+  per thread: 64×32×64 → 8×4×8 = 256 cells, three coarsenings. Going on to 4×2×4 measured no better
+  (§2) and costs four more passes. Restriction is the 8-child mean, prolongation trilinear.
+- **Coarse operator:** each level's operator is the 7-point Laplacian over `H²` (physical units). An
+  open face has the **finite-volume weight `2/(1+h/H)`**, which keeps the Dirichlet point at the fine
+  ghost centre on every level.
+  - The CPU's weight-1 open-face rule on every level was measured to stall the V-cycle at 0.661
+    (global smoother) and 0.750 (block smoother, 4×2×4 coarsest); with the 8×4×8 coarsest at 8
+    sweeps, 0.554.
+  - A Galerkin coarse operator is the alternative, if obstacles demand it. *S1:* obstacles measured
+    0.43 a cycle, so they do not.
+- **Solids:** a coarse cell is solid iff all eight children are; a coarse face's weight is the open
+  fraction of its child faces.
+- **Smoother:** the CPU's red-black kernel, **with a colour mask**, on LDS tiles. One dispatch loads
+  an 8×8×4 tile plus a 1-cell halo (2.4 KB), runs ν colour-alternating sweeps against the frozen
+  halo, and writes the interior. ν = 2 + 2.
+  - **ω = 1 whenever both colours share a dispatch, asserted.** The CPU's ω = 1.9065 in that
+    configuration diverged (×9.9e12 in 64 sweeps).
+- **Coarsest level:** one 256-thread workgroup in LDS (1 KB), **8 sweeps**, one dispatch. *S1,
+  measured:* 32 sweeps were a third of a V-cycle on the 4090 (21.5 of 62 µs). On the CPU model, 8
+  sweeps (even 2) leave the factor unchanged to three digits on every window of three or more levels,
+  open and with obstacles. The two-level 16×8×16 window sets the count: 0.178 at 8 sweeps, 0.174 at
+  32, 0.345 at 4.
+- **Measured** (64×32×64, ν = 2 + 2; the CPU model `shade/renderer/fluid/pressure/__fixtures__/fluid_mg_model.js`,
+  matched on the 4090):
+  - 0.103 per V-cycle with a global smoother;
+  - **≈ 0.30 per V-cycle with the block smoother**: 0.296 by cycle 6, 0.298 at 16, 0.302 at 60, so the
+    asymptote sits just above 0.30. **0.43 with obstacles** (a sphere plus 5% scattered solids). The
+    weight-1 rule stalls at 0.554;
+  - **10 dispatches a V-cycle, 3L − 2**: 3 × (smooth, residual + restriction) down, the coarsest, 3
+    smooths up. Prolongation is pointwise, so it is folded into the next smoother's tile fetch, bit for
+    bit. A solve adds **L weight dispatches** (4 here), because the solid flags may change every step;
+  - red-black SOR (32 passes for 16 sweeps) reaches 0.267.
+- **Smoothers never run in place.** A tile writing its interior races a neighbour that is loading it as
+  halo, so every smoother writes another buffer: one N-cell scratch on the finest level, and two error
+  buffers per coarse level.
+- **Weights:** one u32 a cell, six faces of 5 bits, open area in sixteenths; a coarse face is the mean
+  of its four children, rounded up.
+- **The SOR arm** is the same kernel with the coarse correction off, **one colour per dispatch**, at
+  `sor_optimal_omega`: 2K passes. *S1, measured on the 4090 from a cold start at 64×32×64:* the
+  V-cycle reaches 0.1 of the start in 59 µs (1 cycle) against SOR's 173 µs (26 sweeps), and 0.01 in
+  110 µs (2 cycles) against 327 µs (49 sweeps); 162 µs (3 cycles) with obstacles. **V-cycles are the
+  default.**
+- **Two V-cycles a step** (`GPU_FLUID_CASCADE_V_CYCLES`). One fails the projection quality gate: max
+  |div| 1.62× the CPU's after one step and 4.96× after ten. The second costs 38 µs at 64×32×64 and
+  72 µs at 128×32×128.
+- **Escalation for obstacle-dense scenes:** MGPCG. It needs a symmetric V-cycle (restriction ∝
+  prolongationᵀ, post-smoothing in reversed colour order). Its two dot products are subgroup
+  reductions plus one atomic each. It is valid because every system is non-singular (§9).
+- **Warm start:** the previous step's pressure, safe under Dirichlet boundaries.
+
+**(2) Advection: manual trilinear, f32.**
+- Vulkan core guarantees 4 bits of filter weight (1/16 cell), enough to swamp MacCormack's
+  second-order correction. The limiter needs the 8 corners anyway.
+- So `chunk_texture3d_trilinear_corners` loads 8 corners per component per trace end from the
+  component's toroidal texture (from the parent outside the window), with exact f32 weights, and
+  feeds the limiter its min and max.
+- Velocity is `r32float` for that reason.
+- **Traces** are bisection-clipped against solids (`v3_mac_clip_trace`), with a fixed budget,
+  through the brick gate (§10).
+- **Advection reads textures**: traces are data-dependent, and the texture cache serves them. An
+  LDS-tiled *predict* pass with a 2-cell halo fits:
+  `13×12×8 + 12×13×8 + 12×12×9` f32 = 14.8 KiB of 16. The *correct* pass needs φⁿ and φ̂ (29.6 KiB)
+  and does not fit. That makes predict an S1 lever.
+- *S1, measured on the 4090:* manual trilinear costs 1.09× hardware's in predict at 64×32×64 and 1.19×
+  at 128×32×128 (11.3 against 10.2 µs, 33.8 against 27.7 µs). Advection is 22–30% of a step, so the
+  LDS predict pass was not built.
+
+**(3) LDS and subgroups.**
+- **Stencil passes** on 8×8×4 LDS tiles (`chunk_grid_tile_halo_*`): curl, the smoother (with the
+  prolongation folded into its fetch), residual + restriction, gradient + publish. *S1, measured:* the
+  divergence reads its faces straight from the textures, 2× faster than its tile on the 4090 (4.1 →
+  2.0 µs at 64×32×64, 9.2 → 5.1 µs at 128×32×128). Direct reads in the gradient measured level at
+  64×32×64 and 0.92× at 128×32×128, so the gradient keeps its tile.
+- **Gradient + publish share one pass.** The final velocity is in LDS for the collocated average,
+  and the pass writes four storage textures: u, v, w and the atlas tile.
+- **Subgroups:**
+  - appends through the generalised `COLLECTION_U32` append;
+  - reductions through a subgroup op plus one atomic;
+  - no `subgroupShuffle` stencils, and no layout assumptions.
+- **Hot loops** follow the measured local-memory rule: no runtime vector-component indexing, no
+  function-local tables, integer counters.
+
+**Order** (one projection a step; the end-of-step field is the next step's divergence-free carrier):
+
+| # | Pass | Grid |
+|---|---|---|
+| 0 | scroll fill (after a placement) | exposed bricks |
+| 1 | curl (confinement on) | tiles |
+| 2 | advect predict | full |
+| 3 | advect correct + limiter + atmosphere (identity, §6) + confinement + relaxation band (WRF rows 2..5 toward the parent's identity read) + **deviation clamp** `\|v − v_far\| ≤ 4·h_c/dt_c` (the teleport backstop, which never clamps the wind itself) | full |
+| 4 | divergence of `velocity_mid + forcing`, pinned faces at wall velocity | cells, direct reads |
+| 5 | the solve's weights (L passes), then two V-cycles (10 passes each); non-finite pressure and RHS zeroed on read, and the counter records them | tiles |
+| 6 | gradient + publish; records `t_s, v_far(t_s), Λ(t_s)` for this cascade | tiles |
+| 7 | restrict into the parent (before the parent steps) | parent ∩ child interior |
+
+*S4d, built and measured (2026-10-16): pass 1 and the confinement in pass 3.*
+- **Pass 1, curl** (`shader_fluid_mac_curl`), recorded only for a step whose `vorticity_confinement`
+  is above 0, after the ghosts and before predict. An LDS tile pass, 8×8×4 cells and two barriers: the
+  centre velocity of the tile and two cells around it (12×12×8, 3 × 4,608 B), then `|ω|` of the tile
+  and one cell around it (2,400 B), 16,224 of the 16,384 bytes a workgroup may have. It writes each
+  cell's `½·ε·dt·(N × ω)` into a transient of 3·N floats: the CPU kernel's three passes
+  (`chunk_v3_mac_vorticity_confinement`), its edge ring, solids and 1e-10 floor kept. The differences
+  are per cell on velocity in m/s, so the force is Fedkiw's `ε·h_c·(N × ω)·dt_c`, each cascade with
+  its own `h_c` and `dt_c`, as the CPU scales `ε·dt`.
+- **Pass 3** adds a face's two cells' halves (the CPU's scatter, gathered) after the atmosphere
+  identity and before the band and the clamp, on every face that is not pinned. Off, the step's
+  `confinement_dt` is 0, a uniform branch skips the term, and no curl is recorded.
+- **Against the CPU:** the CPU adds its force before advection and the GPU after, so one step at ε = 12
+  gives the GPU 1.05× the CPU's increment, cos 0.992. A sealed vortex at ε = 3 keeps 1.18 of its peak
+  vorticity on the GPU over 60 steps against 1.09 on the CPU (0.50 without, both); at ε = 12 with no
+  damping both grow, the GPU's more (1.77 against 1.22). Emulator parity at 16³ with solids and a
+  moving wall: every face is the CPU's increment to 16 ulps of the largest push and an ulp of the face.
+- *RTX 4090, ε = 4:* the curl 8.2 µs a step at 64×32×64 and the correct pass +1.0 µs; a tick of cascade
+  0 alone +8.2 µs (144.4 → 152.6), a tick with a coarse step +16.4 µs (291.8 → 308.2). Off, against the
+  step before confinement existed: 143.4 → 144.4 and 295.9 → 292.9 µs, nothing a tick shows.
+
+**Sub-cycling (Berger–Oliger, ruler).**
+- Cascade *c* ≥ 1 steps on ticks with `t mod 2^c = 2^(c−1)`, `dt_c = dt·2^c`.
+- Every tick steps cascade 0 plus at most one other, all at one Courant number.
+- The identity makes the time between steps consistent for uniform air.
+
+## 9. Coupling between cascades
+
+**The CPU's open boundary, given a parent.**
+- A nested cascade's edge halo takes the parent's pressure (Dirichlet, same units) and tangential
+  velocity, through the identity.
+- The coarsest cascade's parent is the far field: `v_far`, pressure 0.
+- Dirichlet keeps every system non-singular, so warm starting and MGPCG are safe. Sealed pockets stay
+  local Neumann cases, as on the CPU.
+
+**Relaxation band.** WRF rows 2..5, `F1 = (1/10Δt)·(6 − n)/4`. *S2:* `F1·Δt = (6 − n)/40` toward the
+parent's read at the step's start, carried to its end by the step's identity; a face's row counts
+faces along its axis and cells across.
+
+**Feedback.** Pass 7 overwrites the parent inside the child's interior with face means of four child
+faces. On a ratio-2 MAC lattice, a divergence-free child restricts to a divergence-free parent,
+exactly. The parent's projection removes the interface divergence.
+
+*S2:* the restricted parent cells are those whose children lie 6 or more child cells inside the
+child's window (`FLUID_CASCADE_FEEDBACK_MARGIN`): the band is not fed back. Pinned at 32³ with an
+integer curl field: all 1,000 restricted cells exactly divergence-free.
+
+**The fallback** without pass 7 and parent halos is uncoupled grids with the same data and sampler.
+It is the reversal if the S2 seam probes say so.
+
+## 10. Effectors and obstacles: rows, an LBVH, cooperative brick queries
+
+**`FLUID_DATABASE_SPEC`**, with a cross-database `node` link:
+
+| Table | Rows | Lifecycle |
+|---|---|---|
+| `fluid_effectors` | one per local effector (globals are folded on the CPU) | stable; written only when a record field differs, compared while assigning (the particle pattern); pose excluded |
+| `fluid_obstacles` | one per shape (a `Union` is a run) | stable; shape parameters, inflation, v and ω compared the same way, so a sleeping body writes nothing |
+| `fluid_obstacle_planes` | hull planes | a schema range, `add_run` |
+| `fluid_query`, `fluid_query_sample` | §12; *built at S5 as a database of their own, `FLUID_QUERY_DATABASE_SPEC`* | freed after delivery or drop |
+
+**Poses.** `node = row_of_entity(entity)` (`RowChains`), read by `scene_read_node`; node 0 (the world
+root) for transform-less effectors.
+
+**The acceleration structure, once per frame.**
+
+| # | Pass | Notes |
+|---|---|---|
+| L1 | extract | one thread per leaf, from a **CPU-compacted leaf → row list** (deterministic order, like the TLAS `#refresh_rows`); world AABB from the node pose and the record. **Every box is clipped to the union of the coarsest windows** (CPU-known), so planes, km-scale heightmap boxes and far rows stay finite; a leaf outside collapses to a point. Wake boxes are swept by `v·dt_max` of this frame's stepping cascades. Obstacles are dilated one cell on the + sides. Centroid bound by subgroup min/max + one atomic over a host-seeded buffer (the TLAS template). |
+| L2 | `graph_bvh_build_lbvh`. **≤ 1,024 leaves:** the small-scene path, one dispatch, **rebuilt every frame** (a fresh tree, no cadence). **More:** the multi-pass build (19 dispatches) on a frame whose leaf count changed or every 16th frame, otherwise **refit only** (`shader_bvh_refit` through the stored Morton order). | The engine scales, so both paths are first-class. Most scenes are expected to sit under the threshold, which is why it gets the fast path. The cadence above it is keyed on runtime facts (membership, age), with no static/dynamic category, and measured at S4. |
+
+**Per pending tick, for its stepping cascades:**
+
+| # | Pass | Notes |
+|---|---|---|
+| Q1 | cooperative brick query | **one workgroup per brick** of each stepping cascade, one dispatch. `chunk_bvh_query_aabb_cooperative`: a level-synchronous frontier in LDS, so per-thread work is bounded by tree depth. Brick box grown by the kernel floor (2·h_c). **Resolution cull:** obstacles narrower than `h_c/2` are not in this cascade's tree (S4d, below). Candidates gather into LDS (≤ 128); survivors are chosen **by row index**, which is stable under motion: ≤ 24 obstacles, then ≤ 16 effectors; overflow is counted. Non-empty bricks append (generalised append). |
+| Q2 | indirect command | 1 thread |
+| Q3 | forcing | one workgroup per touched brick. Per cell: **solid test** = any obstacle SDF at the centre ≤ inflation (≤ 24 obstacles × ≤ 16 hull planes = 384 plane tests worst case, one SDF for analytic shapes), recording the solid's obstacle. Pinned faces from neighbour flags, as on the CPU, with wall velocity from that obstacle. Effector deposits (≤ 16). Output: dense transient forcing + flags; readers gate on the touched bit. |
+
+**Effector kinds** (`write_gpu_record(record)` → `generate_record_writer`):
+
+| Kind | Class | Deposit over `dt_c` (shared core: segment, radius, `falloff_quadratic`) |
+|---|---|---|
+| `SPHERE_PUSH` | `ImpulseFluidEffector` + `spread` | `\|f\|·dt_c·w·v3_clamp_to_cone(r̂, f̂, spread)`: 0 is today, π is omni, `r = 0` → `f̂` |
+| `SWEPT_CAPSULE` | `WakeFluidEffector` | `v·strength·w` over `[p − v·dt_c, p]`; momentum per second `\|v\|²·strength·πR²` on every cascade (spec) |
+| `SWIRL` | `VortexFluidEffector` (`position`, `axis`, `length`, `radius`, `strength`) | `strength·dt_c·(27/4)·(â × r⊥)/R·(1 − d/R)²`: finite everywhere |
+
+- **Wake velocity:** `(global − prev_global)·offset / (frame_dt·fixedStepTimeScale)`.
+  `TRANSFORM64_EVENT_PLACED` makes teleports clean, and the deviation clamp is the backstop.
+- **Kernel floor:** `R_eff = max(R, 2·h_c)`, momentum-conserving, with a spec bounding sub-cell
+  pulsing.
+- **One record, two executors:** `fluid_record_apply` is the CPU applier, with parity on node-0
+  records.
+- **Obstacles on the GPU:** analytic shapes, rigid `Transformed`, `Union` runs, hulls as capped
+  planes; scaled shapes, meshes and heightmaps as their clipped oriented box until the SDF stage.
+  Wall velocity per face is `rigid_velocity_at_point(v, ω, node translation, x)`.
+- **The CPU obstacle path is untouched.**
+
+*S4, built and measured (2026-10-16): `GPUFluidForcing` (`shade/renderer/fluid/forcing/`).*
+- **The database** is the table above, less S5's query tables. The planes are runs through `add_run`
+  but not a schema range: a hull names its run in core's f32 shape parameters, and the 80-byte record
+  has no u32 pair to declare one over, so the caller frees the run with its records.
+- **The step's input.** The correct pass adds the forcing after its epilogue on every face that is not
+  pinned, so the divergence is of `velocity_mid + forcing` with no change to the divergence, the solve
+  or the gradient. The forcing is dense over the three face lattices and written only on forced bricks;
+  bit 1 of a cell's solid flags (`FLUID_FORCED_FLAG`) says its faces were written, so nothing is cleared
+  and every other pass keeps testing bit 0 alone. The flags are the cascade's own buffer; a word a
+  brick (`solid_bricks`) says which bricks the forcing last wrote, so a brick nothing meets any more is
+  listed once more and cleared.
+- **Pinned faces.** Q3 writes the wall's velocity (`rigid_velocity_at_point` of the solid cell's
+  obstacle, the + side's when both are) into the cascade's persistent faces at every face it pins,
+  before the step and after the restriction. Every pass already carries a pinned face's persistent
+  value through, so a face that just became pinned carries the wall, never the fluid value it held.
+- **Q3 is a dispatch per stepping cascade**, from its own command: it writes the cascade's three
+  persistent face textures, and two cascades' would be six of the four storage textures a stage may
+  bind. A coarse tick is Q1, Q2 and two Q3s. Bindings: extract 6 storage buffers, query 7, commands 3,
+  forcing 7 and 3 storage textures, the correct pass 2.
+- **On the RTX 4090** (every kernel compiled through Tint at the default limits): Q1–Q3 against the CPU
+  twins over two 32³ cascades, three frames with rows moved and removed: every cell's solid bit exact,
+  every forced face's forcing within 5.6e-10 of the summed peak, every pinned face exactly the wall's
+  velocity, every unforced cell fluid with no deposit. At 4,000 rows a refit and a rebuild at the same
+  pose list the same 2,494 bricks with the same survivors.
+- **A forest** of 3,000 spheres of 0.12–0.35 m on 48 × 4 × 48 m: survivors equal the lowest 24 rows
+  among the culled overlaps in every brick of every cascade, through a 0.05 m-a-frame drift (so a
+  changed list is a changed overlap, 275–317 of 1,024 fine bricks a frame). The cull leaves cascade 1
+  282 overflowing bricks against 352 without it, and cascades 2 and 3 no obstacle. But a coarse brick's
+  box meets so many of the small leaves that the query's frontier (256) overflows before the cull,
+  which runs at leaves: 692 nodes dropped a tick at cascade 2, ~5,500 at cascade 3, every leaf under
+  them small enough to be culled here.
+- **A mixed forest loses obstacles** (S4, 2026-10-16, RTX 4090): the same 3,000 small spheres with 60 of
+  1–4 m among them, their rows last, first or interleaved, survivors compared brick by brick with the CPU
+  reference (the lowest 24 rows among the culled overlaps). Cascades 0 and 1: exact. Cascade 2: 112 nodes
+  dropped a tick, 0–2 kept obstacles lost in at most one brick. **Cascade 3: 4,360–4,484 nodes dropped a
+  tick, and 134–148 of the 658 obstacles the reference keeps lost, in 23–24 of the 70 bricks that keep
+  any** — every one of them large; the brick then keeps higher rows in their place (14–20). A CPU model of
+  the query over a Karras LBVH of the same scene reproduces it (136 lost in 24 bricks, 4,470 nodes
+  dropped) and measures the remedies: a node-level cull, the leaf cull applied to internal boxes, still
+  loses 106; a frontier of 512 loses 35; 1,024 loses none; **a tree per coarse cascade over only the
+  obstacles it resolves loses none and drops nothing** at every cascade. Decided and built at S4d.
+
+*S4d, built and measured (2026-10-16): a tree per resolution.*
+- **The cull is the tree.** Each obstacle row keeps its extent, `fluid_obstacle_record_extent`:
+  `2·(max local half extent + inflation)`, ∞ for a plane. It is the record's own, so a turned box keeps
+  its longest edge; at the identity pose it is S4's widest world edge less the dilation. Cascade c
+  resolves the obstacles at least `h_c/2` wide and every effector; its bricks search a tree of exactly
+  those, obstacle rows ascending, then effector rows, and the query filters nothing. The sets are
+  nested, and a cascade resolving what the finer one does shares its tree.
+- **The CPU decides membership** because the build takes its leaf count from the host, and a tree of
+  the cascade's own leaves is what puts a coarse tree on the one-dispatch path. The extent is known when
+  a record is written, so membership costs O(delta).
+- **Only the trees the ticks need are built.** The first tick of a frame that steps a cascade of a level
+  records that level's tree, L1 and L2, right before its queries; a later tick of the frame reuses it.
+  Each tree keeps its own cadence (list version, count, age). A level resolving nothing binds an empty
+  tree.
+- **Bindings.** The query binds slot 0's and slot 1's trees (one buffer twice when shared): 8 storage
+  buffers, the per-stage limit. The forcing pass reads each slot's survivors through its own tree's leaf
+  rows.
+- **Measured.** The mixed forest on the RTX 4090 (S4's scene, rows last, first and interleaved, ticks
+  stepping cascades 1, 2 and 3): every survivor list of every brick equals the CPU reference at every
+  cascade, 0 nodes dropped, with trees of 3,026, 1,396, 100 and 100 leaves (cascades 2 and 3 share).
+  The CPU model and a tier-2/3 spec (`GPUFluidForcing.forest.spec.js`: the cooperative query in
+  lockstep over the CPU oracle's LBVH of each tree) lose nothing at any cascade; one tree culled at its
+  leaves loses 120 obstacles and 152 effectors at cascade 3 in the same spec.
+
+## 11. The published wind field
+
+**`GPUSceneWind`** (always on `GPUSceneContext`):
+- a `GPUTileAtlas3D` (per-axis content, `rgba16float`, border 1), one tile per cascade;
+- a uniform `WIND_CASCADE_STRUCT` table (≤ 16, finest first: slot, corner, cell size,
+  `v_far(t_s,c)`, `k_c`);
+- `v_far(t)`.
+
+**Pass 6** writes its own tile only: velocity collocated at cell centres, with the edge halo as the
+skirt. It never samples the atlas it writes.
+
+**`chunk_wind_field_sample(p)`:**
+- `chunk_clipmap_select_finest` picks the cascade and a band weight.
+- The read is the identity (`v_far(t) + (tap − v_far(t_s,c))·k_c`). Inside a band it takes two
+  identity reads (the cascade and its parent, or `v_far` for the coarsest); otherwise one; outside,
+  `v_far`.
+- **The blend is live at sample time.**
+- Bindings: one `texture_3d<f32>`, the clamp sampler, one uniform, no storage buffer.
+- **Hardware trilinear here is presentation-grade**, and 4-bit weights are acceptable for it.
+
+## 12. The CPU read API, and cloth
+
+**On `GPUFluidSystem`:**
+
+```js
+system.far_field(out)                                            // m/s, synchronous, deterministic
+const h = system.request(min_x, min_y, min_z, max_x, max_y, max_z, nx, ny, nz, target, target_offset);
+system.status[h]                                                 // GPUReadbackStatus, for one frame
+```
+
+**With a device:**
+- requests become `add_run` rows;
+- a gather evaluates `chunk_wind_field_sample` into them;
+- `request_run` reads them back, with `readback.encode` right after the gather in the fluid's own
+  pass;
+- delivery is in order, `max_in_flight` is 4 batches, drops come with a status, and latency is
+  typically 2–3 frames.
+
+**Headless:** answered from `far_field` at the next update.
+
+**Cloth: `ClothGPUFluidWind`, the default source.**
+- **`begin`** swaps in lattices delivered since the last tick.
+- **`varies`** answers whether a delivered lattice covers the box, and requests the padded box.
+- **`sample`** interpolates with the strided `scs3d_sample_linear3`, or answers `far_field`.
+- **G2:** the gust runs on the scene clock. The parity gate is restated: worker and inline agree for
+  cloths registered on the same tick, and under a time-invariant wind. The specs use those plus
+  injected lattices. Run-to-run repeatability under GPU wind is lost and accepted (F4).
+
+*S5, built and measured (2026-10-16).*
+- **The API.** `request(min_x, min_y, min_z, max_x, max_y, max_z, nx, ny, nz, target, target_offset)` → a
+  handle; `target` is a `Float32Array` and the lattice lands from `target_offset` as four floats a point,
+  `(x, y, z, 0)` m/s, x fastest, point `(i, j, k)` at `mix(min, max, (i, j, k) / (n − 1))` (an axis of one
+  point at `min`). `status[h]` is `Pending` until the apply point that answers it, then `Delivered` or
+  `Dropped` until the next, then `None`. **The apply point is the system's `update`**, once a frame.
+- **On the device** (`GPUFluidQueries`, `shade/renderer/fluid/query/`): the tables are a database of their
+  own, not `FLUID_DATABASE_SPEC`'s, because a request is answered with no domain (the field is then the far
+  field alone) and the forcing exists only while a domain does. At `FrameStart`, after the publish, a
+  frame's requests become a `fluid_query` row and a `fluid_query_sample` run each (`add_run_filled`) and one
+  pass: the upload, the gather (one invocation a sample; its request found by halving the frame's list; two
+  storage buffers), and `readback.encode` right after it. A frame's lattices share one pooled staging
+  array, so the readback delivers a frame as one run. A device restart or shutdown drops what is in flight.
+- **Latency, measured on the RTX 4090** (Chrome headless, ~240 frames a second, three ribbons and a probe
+  line asking every frame they could): from the frame a request is made in to the update that delivers it,
+  **median 2 frames, 95th percentile 3, worst 5** over 2,171 lattices, 8.5 ms median wall time, none
+  dropped or stalled; cloth reads a lattice at its next fixed step after that.
+- **The wake, through the read API:** a 32-point probe line across the ribbons' fronts deviated from the
+  far field by a median 2.77 m/s (worst 5.77) with a 6 m/s box wake crossing in front of them, against
+  0.026 (worst 0.51) with no wake.
+- **Cloth: `ClothGPUFluidWind`** (`engine/physics/cloth/wind/`): lattices over each cloth's box padded by
+  0.5 m, points every 0.5 m at most (16 along an axis at most), one request in flight per cloth. `begin`
+  lets go of a lattice no cloth read in the last tick and asks again over the box of one only a wake test
+  read, so a sleeping cloth notices a gust. A status is readable for one frame and `begin` runs once a
+  tick (four frames a tick at 240 Hz), so a lattice counts as delivered by its own data (a 0 the delivery
+  writes where a NaN was) and as dropped when its handle settled without that.
+- **Cloth reads it by default** (decided after S5's first report, F4): with nothing assigned,
+  `ClothWorld#wind` is a `ClothGPUFluidWind` while the scene has a domain, else a `ClothFluidWind` while
+  the far field is not exactly zero, else `null` — decided at every tick from those facts, so a scene
+  without wind gains no drag; an assigned source, `null` included, wins. Cloth finds the system by
+  `GPUFluidSystem.prototype.isGPUFluidSystem`, since importing it needs WebGPU's globals. The resolution
+  allocates 0.04–0.10 bytes a tick (sampling noise); the ribbons scene with no wind assigned came up on the
+  GPU wind on the 4090 with the same latency (median 2 frames, 95th percentile 3, worst 5).
+- **G2:** `ClothAmbientWind` is retired; `ClothFluidWind(effectors)` answers `FluidEffectorsSystem`'s far
+  field outside the CPU fields; `GlobalFluidEffector#apply` is removed and `FluidSimulator#step` refuses a
+  global. The restated gate measured (cloth `MEASUREMENTS.md` §69): the staggered spawn under a 3 m/s
+  gust differs at the second cloth's step 1, byte 0; registered on the same tick, none in 180 steps.
+- **Allocation per request at steady state:** headless 0.8 bytes; on the software device the read API's
+  own path ≤ 5 bytes, after two fixes in `GPUTypedTable` it exposed (`set_record`'s byte views, 278.8 →
+  0 bytes a row; `#find_run`'s interpolated assert message, 132 bytes a run → 0). Open, measured:
+  `GPUDatabase#update` walks each table's pages with entry destructuring and frees empty pages, ~59
+  bytes a request at 17 lattices of 64 points a frame.
+
+## 13. Integration
+
+**Water.** In this work (§6).
+
+**Particles: `SAMPLE_WIND`** (position → m/s).
+- A primitive: it reads a bound resource.
+- It touches the ISA, the interpreter (host function, far-field stub), the JS reference VM,
+  optimizer semantics, DAG lift/lower/pack, the node library, and every VM host: emit, simulate, the
+  wide variants, warm-up, the editor's `ParticleReferenceSimulation`, and the optimizer's equivalence
+  and fuzz harnesses.
+- No storage buffer.
+
+**Volumetrics.**
+- **Now:** the far field folded into the phases on the host, per-row phase writes, and the departure
+  from the far field sampled on the GPU wherever the noise is evaluated, carried as a flow map (§6).
+  Built in S3, reworked on Alex's correction (§22).
+- **Later:** fluid scalars (§20).
+
+**Audio.** A 1-point request.
+
+## 14. Budget
+
+**Memory at the defaults** (64×32×64, 4 cascades):
+
+| Resource | Size |
+|---|---|
+| velocity (persistent) | 6.4 MiB |
+| pressure (persistent) | 2 MiB |
+| atlas (persistent) | 4 MiB |
+| per-step transients | ~5 MiB, + 3.5 MiB the step's ghosts |
+| forcing + flags (two stepping cascades) | 5.2 MiB; *S4: 3.2 MiB of forcing and 0.66 MiB of survivors, the flags the cascades' own* |
+| LBVH | `(2n−1)·32 B` + sort transients for n leaves; *S4d:* one per resolution a stepping cascade needs, n its leaves |
+| confinement force (with confinement) | 3·N floats a step, transient: 1.5 MiB at 64×32×64 |
+| **peak** | **~28 MiB** |
+
+**Dispatches**, from the pass tables in §8 and §10. The cascade step is counted by S1
+(`GPUFluidCascade`, tier 3); the rest is an estimate until S2/S4 count it.
+
+| Unit | Item | Dispatches |
+|---|---|---|
+| **Cascade step** | the step's ghosts | 1 |
+| | advect predict, advect correct, divergence, gradient + publish | 4 |
+| | the solve's weights: level 0 from the solid flags, then each coarser level | 4 |
+| | two V-cycles to 8×4×8, each 3 levels × (smooth + residual/restrict), the coarsest, 3 levels × (prolongation folded into the smooth) | 2 × 10 |
+| | *baseline per step* | **29** (19 at one V-cycle) |
+| | scroll fill (only on a step that re-placed the cascade); curl (only with confinement) | +0..2 |
+| **Tick** | Q1 brick query, Q2 command, Q3 forcing | 3; *S4: 4 on a tick with a coarse step, a Q3 per cascade (§10)* |
+| | cascade 0 + one coarse cascade (7 ticks in 8 at four cascades; the 8th steps cascade 0 alone) | 2 × 29 |
+| | restriction of the child into the coarse cascade before it steps | 1 |
+| | *baseline per tick* | **62** (32 on the tick with no coarse step) |
+| **Frame** (any frame that records a tick) | L1 extract + L2: ≤ 1,024 leaves, the one-dispatch build every frame; more leaves, refit or rebuild (19). *S4d:* for each tree a tick of the frame needs, one when every level resolves the same obstacles | 2; or 2 / 20; each |
+| **Frame** (every frame) | fluid database uploads when rows changed (`GPUDatabase.update`'s upload shaders); the query gather + `GPUDatabaseReadback`'s gather (≥ 48 rows) when requests exist | ~2–4 |
+
+Per frame, then:
+- **No tick** (e.g. 2.6 of every 3.6 frames at 144 Hz against 40 Hz ticks): ~2–4.
+- **One tick, ≤ 1,024 leaves, or a refit above that:** 2 + 62 + 2–4 ≈ **66–68**, or ~72 with fills
+  and curl on both steps.
+- **One tick, rebuild above 1,024 leaves:** 20 + 62 + 2–4 ≈ **84–86**, or ~90.
+- **Two ticks** (the cap, under load, e.g. a third of frames at 30 fps): 2 + 2 × 62 + 2–4 ≈
+  **128–130**; ~148 on a rebuild frame.
+
+Two pressure solves are 48 of the 62 dispatches in a tick. The V-cycle is where the count lives.
+
+**Cost, measured at S1** (RTX 4090, D3D12, headless Chrome; the engine's recorded step replayed with
+timestamps, arms paired and interleaved, p10 of 100–200 samples):
+- **A cascade step:** 114.7 µs at 64×32×64 and 244.7 µs at 128×32×128 with two V-cycles (76.8 and
+  173.1 µs at one). At 64×32×64: V-cycles 77 µs, advection 25.6, weights 8.2, gradient 4.1,
+  divergence 2.0. The solve is 65–73% of a step. Obstacles change nothing.
+- **Small dispatches cost 1–2 µs back to back**, not the 5–8 µs a separate pass was estimated at.
+  Recording a step's 28 dispatches in one compute pass or in separate passes costs the same.
+- **One tick at the defaults** (cascade 0 plus one coarse cascade, both 64×32×64) is ~230 µs of
+  cascade steps plus forcing, and **a two-tick frame ~0.46 ms plus forcing**: at the 0.5 ms target on
+  the 4090. S2 and S4 measure a whole tick.
+- **A whole tick, measured at S2** (four cascades at 64×32×64, h₀ = 0.5 m; RTX 4090, the recorded tick
+  replayed with timestamps, its uniforms copied at capture, arms interleaved, p10 of 200): **214 µs**
+  on a tick that steps cascade 0 alone (28 dispatches), **432 µs** on one that steps cascade 1 too
+  (57), 349 µs with cascade 3. A lone S1-shaped cascade beside the far field reads 132 µs in the
+  same run. Against the revised 115 and ~230 µs above, a coupled step is ~1.6× S1's (per-dispatch
+  medians 221 against 138 µs): the parent seams' fetches (8 parent texels a beyond-window read, made
+  by the ~67% of a 64×32×64 window's tiles that lie on a window face) take predict from 14 to 42 µs
+  and correct from 24 to 59, and the solve's parent ghosts ~14 µs more. The band costs nothing a tick shows (213 against 213 µs),
+  3% of correct. Forcing (S4) is not in these.
+- **With the step's ghosts (§7, D3), measured at S2:** two stacks, one reading the parent per seam
+  tap and one from the ghosts, driven alike and their recorded ticks replayed paired and
+  interleaved (p10 of 200; after 32 ticks the four cascades' state bit for bit the same): **144.4 µs**
+  on a tick that steps cascade 0 alone (29 dispatches) against 246.8, **291.8 µs** with a coarse
+  step (59) against 489.5. Of cascade 0's step, predict 45 → 16 µs, correct 89 → 27, the smoother
+  63 → 53, residual + restriction 22 → 18 and the gradient 6 → 4, for the ghosts' 9. The per-tap
+  seams read 214 and 432 µs in the run above and 247 and 490 in this one: the level moves from run to
+  run, the paired difference does not.
+- **Levers, in order of where S1 measured the time:**
+  1. the solve. At 128×32×128 the finest up-leg smoother, with its folded prolongation, costs 19.5 µs
+     against 13.3 µs down: stage the coarse block in LDS (144 loads a tile instead of 4,800). Build the
+     coarse weights in one dispatch, or level 0's in the forcing pass (the weights are 7% of a step);
+  2. fusing divergence into the first smoother;
+  3. the LDS predict pass (advection is 22–30%);
+  4. a lower rebuild cadence above 1,024 leaves.
+- **The small-scene build, measured** (landed `b523718db`, RTX 4090, `GPU_BVH_BUILD_PLAN.md` §4.7):
+  one dispatch costs 7.3 µs at 16 leaves, 13.2 µs at 128 and 53.2 µs at 1,024, against ~73–84 µs for
+  the 19-dispatch build at those counts. Near the 1,024 threshold a rebuild is a single dispatch, but
+  it costs far more than a small dispatch's 1–2 µs.
+
+- **A whole tick with forcing, measured at S4** (the defaults, four cascades at 64×32×64, h₀ = 0.5 m;
+  RTX 4090, each tick recorded by the engine and replayed with timestamps, its uniforms, copies and
+  clears kept, arms interleaved, p10 of 200), against the same tick without forcing:
+
+  | Scene | Tick of cascade 0 alone | Tick with a coarse step |
+  |---|---|---|
+  | none (S2's tick) | 143.4 µs | 289.8 µs |
+  | 6 effectors and 6 obstacles about the anchor | 166.9 (+23.5) | 326.7 (+36.9) |
+  | the same and a ground plane, which forces every brick | 173.1 (+29.7) | 345.1 (+55.3) |
+  | 3,000 small spheres, 400 fine bricks past 24 obstacles | 201.7 (+58.3) | 379.9 (+90.1) |
+
+  By pass (medians, each in its own timed pass): Q1 13.8–15.4 µs over 2,048 bricks and 18–28 over 4,096,
+  40 and 59 in the forest; Q2 1 µs; Q3 8–16 µs for a cascade, 17–30 for two; the correct pass the
+  same with the forcing as without (26.6 and 53.2 µs). The frame's L1 and one-dispatch build at 13
+  leaves: 11.3 µs; at 3,000 (the 19-dispatch build): 86 µs.
+- **4,000 rows, rebuild against refit** (2,000 obstacles and 2,000 effectors over 200 × 40 × 200 m; costs
+  as the difference from a plain tick replayed before them, p10): L1 and the rebuild +87.7 µs, L1 and
+  the refit +17.0 µs; Q1 over both stepping cascades +70.3 µs. On the forest, Q1 over cascade 0 and 1
+  +54.3 µs, over 0 and 3 +50.2 µs.
+
+- **A scene from entities, measured at S4** (the bonfire playground, RTX 4090, every pass timestamped,
+  medians of 90 frames at 60 fps against 40 Hz ticks): a `GPUFluidComponent` at the defaults, a gusting
+  global, two impulses, a vortex, a wake on a moving entity and a moving box. The frame's passes sum to
+  1.60 ms on a frame with no tick and 2.00 ms on a frame with one; the fluid's share of a one-tick frame is
+  396 µs with a coarse step and 220 µs without (the frame's L1 and build 12 µs, Q1–Q3 20 µs, the publish
+  10 µs). No tick was dropped and the forcing dropped nothing. The published tile deviates from `v_far` by
+  up to 4.67 m/s beside the vortex, +0.48 m/s upward over the fire, and 0.001 m/s 17 m away.
+- **The water playground against the bonfire** (the ocean stop at the defaults, no effector or obstacle rows,
+  against the scene above; RTX 4090, every pass timestamped per frame, 240-frame captures at 60 fps by
+  `create_frame_loop`, runs alternated W B B W W B): pass for pass the two agree within 1 µs, but for the
+  bonfire's forcing (the brick query, the apply, the leaves and its one-dispatch tree: 45 µs with a coarse step,
+  34 alone) and its smoother (+7). A frame that ticks, p10 per capture: water 339–367 µs with a coarse step and
+  189–195 alone, the bonfire 391–419 and 221–234. S3's tree (`d2bd51b90`), alternated with this one, reads the
+  same (343–357 and 190–194); either tree drifts to 390–600 µs in a capture whose whole frame drifts with it.
+  The water frames tick at most once (a two-tick frame about once in 240), drop nothing, fill nothing at rest,
+  dispatch no forcing, and publish one or two cascades only on a frame that ticks. **A capture's mean of the
+  fluid's spans a frame is not its cost**: while other processes held the 4090 at 36–99%, single passes took
+  +270 µs steps, and that mean read 248–500 µs for water and 396–1,399 µs for the bonfire. S3's 1.09–1.13 ms
+  (§6) was that statistic, in captures where every water pass ran ~3× its time here. Judge the fluid by a
+  tick class's p10 or by per-pass medians.
+
+- **A tree per resolution, measured at S4d** (RTX 4090, whole frames, the trees and one tick, before
+  and after paired and interleaved, p10 of 200). 6 effectors and 6 obstacles build one tree as before,
+  every tick shape the same (181.2 → 181.2 µs alone, 545.8 → 545.5 with cascade 1, a 16-tick cycle
+  5,180.4 → 5,180.4); with S4b's protocol (the tick alone) 167.9 and 327.7 µs against S4b's 166.9 and
+  326.7 (no forcing: 144.4 and 291.8 against 143.4 and 289.8). The mixed forest: +12.3 µs with cascade
+  1 (its 1,396-leaf tree refit), +3.1 with cascade 2 and +9.3 with cascade 3 (a 100-leaf one-dispatch
+  build), +0 alone; a 16-tick cycle +2.9% (6,224.9 → 6,408.2 µs). 3,000 small spheres alone: +13.3 with
+  cascade 1, −11.3 and −6.1 with cascades 2 and 3 (their trees are empty), a cycle +2.1%.
+- **Vorticity confinement, measured at S4d** (§8): the curl 8.2 µs a step, the correct pass +1.0 µs; a
+  tick +8.2 µs alone and +16.4 with a coarse step. Off, nothing a tick shows.
+
+**Bandwidth** on a ~50 GB/s integrated GPU: ~1.5 ms a tick.
+
+## 15. Verification
+
+**Tier 1: WGSL validity.** ≤ 8 storage buffers (fluid passes), ≤ 4 storage textures, ≤ 16 KiB of
+workgroup memory, `enable subgroups;`.
+
+**Tier 2: the emulator, and CPU models.**
+- **Parity specs:**
+  - `sdf3_*`;
+  - `aabb3_intersects_aabb3`;
+  - segment distance;
+  - falloff;
+  - cone clamp (`r = 0`, antipodal);
+  - swirl (axis);
+  - rigid velocity;
+  - the clipmap coordinate;
+  - `fluid_record_apply` ↔ forcing (node-0);
+  - the atmosphere identity: a uniform cell matches `v_far` at dt_c = dt…8·dt with gusts on and `D`
+    changing mid-interval, and a dropped tick leaves no offset.
+- **Barrier kernels:** per-cell maths in `chunk_v3_mac_*` behind a two-function seam (`tile_read_*`
+  from LDS in production, from a buffer in specs — the particle VM's register-backing pattern).
+  Parity against `v3_mac_*` at 16³, with the pressure scale `dt/h²` applied.
+- **A CPU multigrid model as a spec** (the `mg2.mjs` shape):
+  - **≤ 0.30 per V-cycle at 64×32×64** with the block smoother and the finite-volume boundary;
+  - red the moment the CPU's open-face rule is put back (0.75);
+  - the both-colours / ω > 1 assert fires.
+- **The quality scenarios** at 16³ through the buffer-backed hosts (`.slow.spec.js`).
+- **Physics specs:**
+  - wake momentum equal across cascades;
+  - kernel-floor pulsing bounded;
+  - the far field keeps the authored gust exactly (no drag filtering);
+  - `force` with `D = 0` stays out of the GPU far field.
+- **LBVH inputs:** planes and heightmaps produce finite clipped leaves (no NaN centroid), and the
+  leaf order is the CPU list.
+
+**Tier 3: `SoftwareGPUDevice`.**
+- The ruler schedule.
+- Placement, nesting clamp, jump re-placement.
+- Fills.
+- L1/L2 build-versus-refit by membership and age.
+- Q1–Q3 sizes, and nothing with no rows.
+- Upload order.
+- `request_run`.
+- Teardown under a pending mapping.
+- Restart.
+- The default `GPUSceneWind` with no fluid system.
+
+**Migrations.** VSM, CPU fluid (sync extraction, folded atmosphere), cloth, volumetrics, water,
+physics and the singleton users stay green at each commit. The census runs before and after.
+
+**Tier 4: one-off device checks, short runs:**
+- the SOR and V-cycle arms;
+- manual against hardware trilinear;
+- the LDS predict pass;
+- in-pass dispatch cost;
+- seam probes;
+- a long warm start;
+- a fast camera;
+- a teleport;
+- an obstacle-dense scene (V-cycle against MGPCG);
+- 4,000 rows (rebuild against refit);
+- a forest on a coarse cascade (resolution cull, survivor stability under motion).
+
+## 16. Stages
+
+One-concern commits, each green alone.
+
+| Stage | Contents | Gate |
+|---|---|---|
+| **S0: shared foundations** | clipmap module + VSM and CPU-fluid migrations; `FluidEffectorsSystem` extraction; core shape record + cloth; SDF chunks; shared kernels; `chunk_aabb3_intersects_aabb3`; `chunk_bvh_query_aabb_cooperative`; the small-scene path in `graph_bvh_build_lbvh` (landed on master in its own session); `chunk_grid_tile_halo_*`; generalised append (the VSM migrates); `GPUTileAtlas3D` per-axis + slot origin; trilinear-corners extraction; 3-D texel helpers; `request_run`; strided `scs3d`; non-allocating singleton accessor; `GPUSceneRows` on `TRANSFORM64_EVENT_PLACED`; 3-D slice view; G1 retirement | parity specs; existing specs green; census |
+| **S1: solver core** | one cascade: MAC chunks, LDS hosts, V-cycle with the finite-volume boundary and colour-masked smoother, manual-trilinear MacCormack, far-field boundary, physical pressure | multigrid CPU-model spec; kernel parity; quality slow-spec; **device A/Bs**; dispatch cost; defaults confirmed or cut |
+| **S2: cascades** | toroidal face textures, window-local tiles, placement, fills, coupling, ruler, read records | seam probes, long run, teleport |
+| **S3: the far field and its readers** | `GlobalFluidEffector` gust + `advance` + effector serialization (`FluidEffectorsComponent` adapter, so phases persist); the fold, `v_far` and `Λ`; the folded CPU atmosphere; the read API; volumetrics with per-row phases; water (`WaterWaves` v2, GPU low-pass, `windy` gate); `ClothAmbientWind` retired | consumer specs; Breaking CHANGELOG lines |
+| **S4: ECS fluid** | `GPUFluidComponent` + adapter, `GPUFluidSystem`, fluid database with field-wise change detection, the LBVH (build/refit), cooperative queries, forcing, `fluid_record_apply`, Impulse `spread`, `VortexFluidEffector`, the `FluidObstacle` adapter | tier-3 specs; CPU quality gate re-run |
+| **S5: queries + cloth** | gather, `ClothGPUFluidWind`, restated parity gate | readback contract; cloth specs |
+| **S6: particles** | `SAMPLE_WIND`; the bonfire in a gust | VM meta-tests; device look |
+
+## 17. Decisions
+
+### Resolved by Alex
+
+- **F1. Two-way coupled cascades:** yes.
+- **F2. One scene wind.** As refined by R1: it is the fluid, with `GlobalFluidEffector` as its far
+  field.
+- **F3. The CPU fluid:** kept, deprecated later.
+- **F4. Cloth reads the GPU fluid.**
+- **F5. Obstacles are `FluidObstacle`s;** SDFs later.
+- **F6. More kinds:** Impulse gets `spread`, and a vortex effector is added.
+- **G1.** Retire `GPUClipMap3D`, its update shader, its wrap chunk and `GPURadianceField`; rewrite the
+  debug overlay.
+- **G2.** The gust runs on the scene clock, and cloth's parity gate is restated.
+- **R1.** One infinite fluid.
+- **R2.** An acceleration structure.
+- **R3.** Water reads actual velocity.
+- **R4.** Queries on the system; cloth left to my call.
+- **R5.** Depart from the CPU on facts; subgroups and LDS from the start.
+
+### Decided here
+
+Each line gives the decision, then *what would reverse it*.
+
+- **D1.** A domain follows its entity.
+- **D2.** Ratio 2, power-of-two resolution, corners in 4s.
+- **D3.** Toroidal per-component face textures (period N+1) and window-local tiles. The persistent
+  textures hold no ghost: a per-step transient ghost shell, written once a step from the parent
+  (velocity faces `FLUID_CASCADE_GHOST_DEPTH` = 6 deep, pressure one cell), holds the parent read the
+  step's passes and LDS halos take; past the shell they read the parent itself. *Confirmed by the S2
+  A/B: a tick 247 → 144 µs alone and 490 → 292 µs with a coarse step, bit for bit the same state
+  (§14). Reversal: a measured tick where the ghosts' pass costs more than the reads it saves.*
+- **D4.** The MAC discretisation and MacCormack are kept; the CPU kernels are the maths oracle, with
+  pressure scaled `dt/h²`.
+- **D5.** A V-cycle with the finite-volume coarse boundary and a colour-masked LDS block smoother at
+  ω = 1, two a step. *Confirmed by the S1 A/B: ~3× faster than SOR to the same residual on the
+  4090. Reversal: MGPCG for obstacle-dense scenes.*
+- **D6.** Manual trilinear in f32; `r32float` velocity. *S1: 1.09–1.19× hardware's cost in predict.*
+- **D7.** One projection a step. *Confirmed at S1: without its pre-advection projection the CPU reads
+  0.99–1.02 of its default on every quality scenario. Reversal: a quality scenario regressing beyond
+  tolerance.*
+- **D8.** Two-way nesting, Dirichlet halos in shared physical units, a WRF band, face-mean
+  restriction. *Reversal: seam probes, falling back to uncoupled grids.* *Confirmed by the S2 seam
+  probe* (a column vortex carried out of cascade 0 into cascade 1 and back, against one fine window
+  over cascade 1's region): after the round trip the vortex is 15.0% of its peak off the fine window
+  coupled, 16.0% with the band alone, 17.8% with feedback alone and 18.8% uncoupled; cascade 0's
+  interior 4.0% against 6.2%.
+- **D9.** Ruler sub-cycling with per-cascade read records instead of a ring.
+- **D10.** The atmosphere identity at every step and every read; `v_far = u + g` with an unfiltered
+  gust; `force` kept out of the far field.
+- **D11.** An LBVH once per frame. At ≤ 1,024 leaves it is the one-dispatch small-scene build, fresh
+  every frame. Above that it is rebuilt on membership change or every 16th frame, and refit otherwise,
+  queried cooperatively per brick, with survivors by row index and a resolution cull. *S4d:* the cull
+  is a tree per resolution, each with its own cadence.
+- **D12.** One record, two executors; field-wise change detection; a momentum-conserving floor at
+  2 cells.
+- **D13.** Water: one low-passed sample feeds fetch, derivation and turn; deadband triggers; the
+  `windy` gate from domains and `v_far`.
+- **D14.** Volumetrics phases written per row. *Built in S3 (§6): `SceneVolumetrics.noise_version`, seven
+  words a moved row (the two scrolls and the flow clock). The phases carry the far field only; the
+  departure from it is sampled on the GPU per evaluated point, never read back (§22).*
+- **D15.** Physics' inline ω×r copies migrate only under a flat budget.
+- **D16.** Projection stays on.
+
+## 18. Forks left
+
+The measured reversals are D5, D7, D8 and D11's cadence. S4 left two forks; the brick query's frontier
+on coarse cascades was decided (a tree per resolution) and built at S4d (§10). One is left, with a
+recommendation:
+
+- **Several `GPUFluidComponent`s.** *Built:* the lowest enabled entity is the domain, the others dormant.
+  The alternative, every domain stepping and one publishing, costs a whole stack's tick (~144–292 µs) for
+  nothing a consumer reads until S5's queries could ask a second domain; overlapping domains coupling to
+  each other is out of the proposal (§20).
+
+## 19. Duplication ledger
+
+**Removed by this work:**
+- The hysteretic snap (2 → 1); VSM window bookkeeping.
+- `GPUClipMap3D` and its wraps (G1).
+- Per-tick effector bookkeeping and several globals' order-dependent application →
+  `FluidEffectorsSystem` and one folded atmosphere.
+- Cloth's shape-parameter encoding → core.
+- The box SDF inside the AABB chunk; the trilinear corners inside the SDF chunk; two slot-maths
+  copies.
+- `chunk_vsm_append_mover` → the generalised append.
+- Impulse's and Wake's triplicated loops, four inline falloffs, Wake's closure and segment distance.
+- `ClothFluidWind`'s inline AABB tests.
+- `ClothAmbientWind`, `SceneVolumetrics.wind` and `WaterWaves`' wind.
+- `wind_main.js`'s hand copy.
+- `GPUSceneVolumetrics`' full repack and per-repack allocation for moving phases.
+- `getAnyComponent`'s per-call allocation.
+
+**Noted, separate work:**
+- The f32 workgroup-sum pattern repeated in the SH projection and the multiscatter LUT. A shared
+  chunk needs a reset and barrier, per-type variants and a layout-free slot claim.
+  `sh_exp_workgroup_sum` is callable once per kernel, and since `48926a7ec` its 64 partial slots
+  contradict its own one-slot-per-invocation comment.
+- The engine's split on subgroup contiguity (three shaders assume it, three warn against it).
+- `FluidObstacleSystem`'s triple traversal, duplicated clamp, `setVelocityAt` copy and stale
+  "mesh-ish shapes throw" note.
+- The undeclared write of a manual `Wake.apply` to `previous_position`.
+- The CPU fluid's patch-edge variants and `fluid_gather_visible_effectors`' O(fields × effectors).
+- Hand-rolled row holding in Water, the particle emitter system, `GPULightCollection` and
+  `prefab_place`.
+- Light and decal cluster tails; Brick4's index helpers.
+- ≥ 10 inline rigid-velocity sites.
+- `shape_to_type` throwing on `BoxShape3D`.
+- The CSM blended chunk as a `select_finest` client.
+- The existing BVH traversal loops have no visit budget.
+
+## 20. Not in this proposal, and open
+
+**Not in this proposal:**
+- Scalars, sources, buoyancy (the successor to `force`), temperature.
+- Interpolated presentation of sub-cycled cascades beyond the identity's uniform part.
+- Overlapping domains coupling to each other: the finest answers.
+- Mesh, heightmap and scaled-shape obstacles on the GPU from SDFs. That needs
+  `GPUGeometryManager.sdf`, a physics-shape source, and `shader_build_sdf`'s `NEGATIVE_WRAP_DISTANCE`
+  hack removed, because it reads thick meshes as hollow beyond ~5.6 voxels.
+
+**Open until measured:**
+- The V-cycle factor with obstacles, and Galerkin against the open-fraction operator.
+- In-pass dispatch cost.
+- The rebuild cadence above 1,024 leaves.
+- The staggering cost of sub-cycled coupling for non-uniform air.
+- Sealed pockets under a warm start.
+
+## 21. Sources
+
+- Renard, "Wind Simulation in God of War", GDC 2019 (speaker notes, quotes checked).
+- NVIDIA Flow, `NVIDIA-Omniverse/PhysX` `flow/source/nvflow/Pressure.cpp`.
+- Cohen, Tariq, Green, I3D 2010.
+- WRF v4 technical note; Harris & Durran.
+- Vulkan Required Limits (docs.vulkan.org); realtimerendering.com "Direct 3D Details Part V".
+- McAdams, Sifakis, Teran 2010; Trottenberg, Oosterlee, Schüller, *Multigrid*.
+- English et al. 2013.
+- Selle et al. 2008; Zehnder et al. 2018; Nabizadeh et al. 2022; Qu et al. 2019; Rabbani et al. 2022.
+- GPU Gems 1 ch. 38, GPU Gems 3 ch. 30; Stam 2003.
+- Panteleev 2014; Rockenbeck 2021; HOME-LBM 2023.
+- Karras 2012, as implemented in `gpu_primitive/bvh/`.
+- `mg2.mjs`, `sor.mjs` (CPU models of §8, session scratchpad, reproduced 2026-10-16).
+
+## 22. Review record
+
+**b → c.** Two adversarial passes. The blockers were the gust clock and NaN paths; about twenty
+majors followed. All were answered in (c); (d) superseded several answers.
+
+**c → d.** Alex's review: R1–R5, G1, G2.
+
+**d → e.** A reference check and a design attack.
+
+- **Blocker, measured and reproduced:**
+  - The CPU's open-face rule on every multigrid level stalls the V-cycle (0.66/0.75) → the
+    finite-volume coarse boundary (0.10/0.30).
+  - A frozen-halo SOR with both colours diverges → a colour mask, ω = 1 asserted for both colours,
+    and the SOR arm at one colour per dispatch.
+- **Majors:**
+  - Uniform air seamed between coarse steps; dropped ticks broke the ring → the read-time identity
+    with per-cascade records (§6).
+  - The gust was low-passed by drag (16–84% kept) → `v_far = u + g`.
+  - `force` at `D = 0` was unbounded and became a world downdraft → kept out of the far field.
+  - The speed clamp capped the wind at fine cells → it clamps the deviation.
+  - Parent pressure carried no unit scaling → physical pressure.
+  - Unbounded leaves (planes) put NaN into the LBVH → boxes clipped to the coarsest windows.
+  - Per-brick caps overflowed on coarse cascades, with flicker under Morton order and per-thread
+    visit budgets of 128 → cooperative queries, separate caps, row-index survivors, resolution cull.
+  - The LBVH is 19 dispatches and was rebuilt every tick → once per frame, refit unless membership
+    changed or every 16th frame, and the budget recounted (§14: at or over target until in-pass cost
+    is measured).
+  - Hash change detection was not the particle pattern and failed both row kinds → field-wise
+    compare.
+  - "Four inline workgroup sums" were four different computations, with an indexing rule the engine
+    itself warns against → subgroup op + one atomic, the ledger corrected.
+  - A subgroup append existed (`chunk_vsm_append_mover`) → generalised.
+  - Water's `windy` gate, shore reflection and fetch direction → §6.
+  - A live velocity would repack every volume every frame → per-row phase writes.
+- **Recount, at Alex's question.** "55–73 a frame" overstated a cascade step (~25 against 21
+  counted) and left out the fluid database uploads and the query gather (2–4 a frame). It also never
+  stated two-tick frames. Re-running the CPU model then showed that stopping the V-cycle at 8×4×8
+  matches 4×2×4 (0.296) at 32, 64 or 400 coarsest sweeps. The V-cycle is now 13 passes, a tick 38
+  dispatches, a one-tick frame 42–62, and a two-tick frame 80–100 (§14).
+- **The BVH, at Alex's question.**
+  - The rebuild's 19 dispatches are Morton (1), a 4-digit radix sort at 4 dispatches a digit
+    (histogram, scan prepare, indirect scan, scatter: 16), emission (1) and refit (1). All of them
+    are near-empty at fluid scale.
+  - Alex approved a small-scene path in `graph_bvh_build_lbvh`, and it was started as its own task.
+    He also corrected a question of mine: "this is an engine, there is no such thing as a 'typical',
+    the engine is build to scale … most cases will have very small number of elements, so having a
+    fast path for that is a big win."
+- **Minors:** window-local tiles for odd face periods; the LDS-advection sizes (predict only); MGPCG's
+  symmetry; the leaf order; the TLAS bound wording; the default `GPUSceneWind`; the water low-pass
+  seed; nested loop budgets stated; BVH-quote provenance; the sync helper being one line; LDS shaders
+  mostly 1-D; the binding-budget premise.
+- **S1, built and measured (2026-10-16).** The solver core exists as `GPUFluidCascade`
+  (`shade/renderer/fluid/`): `GPUFluidPressureSolve` (V-cycles or SOR) and `FluidMacPasses`
+  (predict, correct, divergence, gradient), every kernel a WGSL twin of its CPU model or kernel, and
+  all nine compiled through Tint on the 4090. Measurements moved four things here:
+  - the V-cycle is 10 passes, not 13 (prolongation folded into the smoother, bit for bit), plus 4
+    weight passes a solve that §14 had left out; a step is 28 dispatches at two V-cycles;
+  - the coarsest level sweeps 8 times, not 32 (a third of a V-cycle on the device, no change in the
+    factor on three or more levels);
+  - the divergence reads its faces directly (2× faster than its LDS tile);
+  - small dispatches cost 1–2 µs back to back, so the §14 cost model of 5–8 µs a pass was replaced by
+    the measured step (115 µs at 64×32×64, 245 µs at 128×32×128).
+  The quality slow-spec holds the GPU step to the CPU on every scenario (D7 confirmed), and the CPU far
+  field (S3's fold, gust and identity) was built alongside it.
+- **S2, built and measured (2026-10-16).** `GPUFluidCascadeStack` (`shade/renderer/fluid/`): placement
+  through `ClipmapWindowSet` (`FluidCascadePlacement`, with `clamp_corner`), the ruler
+  (`fluid_cascade_ruler`), fills, two-way feedback, parent seams and Dirichlet ghosts, the correct
+  pass's epilogue (identity, band, clamp) and per-cascade read records. Every kernel compiles through
+  Tint at the default limits; the most storage bindings are the smoother's and the residual's 7. A
+  uniform wind is exact everywhere, bit for bit, across three cascades through gusts, a changing drag,
+  dropped ticks and refills (the stack's recorded ticks run under the emulator). On the device: the
+  seam probe confirms D8 (above); 4,000 ticks at the defaults with a moving anchor stay finite with the
+  non-finite counter at 0, in calm air no deviation ever exceeding its seeded 1.72 m/s; a 1 km teleport
+  re-places and refills all four cascades to the far field exactly. A tick cost 214 µs alone and
+  432 µs with a coarse step (§14), the parent seams most of the excess; the step's ghosts (D3), one
+  dispatch that evaluates the parent's read once, take it to 144 µs alone and 292 µs with a coarse
+  step against 247 and 490 in the same paired run, the state bit for bit the same. The stack's
+  `record_publish` sets `GPUSceneWind` and publishes each cascade that changed, its skirt the
+  parent's read; uniform air reads back `v_far` exactly through `wind_field_sample`.
+- **S4, the ECS half, built and measured (2026-10-16).** `GPUFluidComponent` and `GPUFluidSystem` (§5): a
+  scene gets the GPU wind by adding a component. The CPU effectors moved onto `fluid_record_apply` (D12):
+  impulse and wake deposit through their records, so the CPU and GPU fluids deposit the same momentum; a
+  sub-cell push that carried 13–77× the continuum's momentum now carries 0.98–1.08 of it, a wake 0.22–0.32 of
+  its swept momentum now 1.00–1.07. From two cells up the push is within 1.43e-5 of its peak of the old one,
+  not bit for bit (the old apply rounded its grid-space centre to f32). The census found no system reordered
+  by the new system. The mixed forest's frontier loss and the several-domains rule are §18's forks.
+- **S4d, built and measured (2026-10-16).** Two gaps S4 measured. *The frontier* (§10): the resolution
+  cull became the tree's structure, a tree per resolution a stepping cascade needs, over the effectors
+  and the obstacles at least half its cell wide by the record's own extent, shared where the sets are
+  equal, built only by the ticks that need it, each with its own cadence. On the RTX 4090 the mixed
+  forest keeps every obstacle the reference keeps at every cascade, nothing dropped (S4: 134–148 of 658
+  lost at cascade 3); 6 + 6 rows cost the same as before, the mixed forest +2.9% over a 16-tick cycle.
+  *Vorticity confinement* (§8): pass 1 and its term in pass 3, the twin of the CPU kernel, `ε·dt_c` and
+  `h_c` per cascade, from `GPUFluidComponent.vorticity_confinement`; 8.2 µs a step on, nothing off.
+- **S5, built and measured (2026-10-16).** The read API (§12): `GPUFluidSystem#request` and `#status` over
+  `GPUFluidQueries`, headless answered from the far field; `ClothGPUFluidWind`; `ClothAmbientWind` and
+  `GlobalFluidEffector#apply` removed; cloth's parity gate restated. One departure from §10: the query tables
+  are a database of their own, since a request is answered with no domain and the forcing's database lives
+  only while one does. Measured on the 4090: a lattice lands a median 2 frames after it is asked for (95th
+  percentile 3), and a wake crossing in front of three ribbons reads 2.77 m/s off the far field through it.
+- **S3's volumetrics, corrected (2026-10-16).** S3 kept one `GPUFluidSystem.request()` per volume centre and
+  folded that one read-back wind into the volume's phases. Alex rejected it: "it breaks the GPU-driven design.
+  We already have all of the data on the GPU, and yet we bring CPU into the equation. We should just sample on
+  the GPU, and we might as well sample per-froxel instead of one tap at the origin. The volume is continuous,
+  so the result will be continuous too." The method he chose, *far phase + flow map*: the far field stays the
+  host's exact scroll (`far_field`, deterministic, no readback); per evaluated point the GPU samples the
+  published field and carries the noise by the departure as a flow map, two phases half a period apart on a
+  host-folded clock, because a froxel has no history to integrate a phase in and `t·w(p)` would jump by
+  `t·Δw`. Built as §6 says, with P and the threshold measured there. The per-volume requests and everything
+  that existed for them (handles, landing buffers, the status walk) are gone. Two defects surfaced on the way:
+  the host scroll carried the noise upwind (the lookup is `position/scale + offset` and the offset grew with
+  the velocity), and the accumulating path tracer's pass threw on every frame since the noise landed
+  (`this.#graphics` read inside a plain `execute`); both fixed and pinned. Measured and left open: the
+  uniform-air cost of the flow map's code (§6), and the flow map's reach: with the departures the fluid
+  produced here (median 0.33 m/s, at most 2.9 m/s, past 0.1 m/s) on the default 8 m features, the balance
+  point leaves the pulse and the stretch both near 0.9, so the departure reads mostly as an in-place
+  rebuild; a smaller `noise_scale` moves the balance toward motion.