@woosh/meep-engine 3.68.0 → 3.70.0

package/src/shade/renderer/fluid/mac/FluidMacPasses.js

@@ -1,427 +1,453 @@
-import { assert } from "../../../../core/assert.js";
-import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
-import { GRID_TILE_SIZE } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
-import { fluid_cascade_window_place, fluid_cascade_window_value } from "../fluid_cascade_window.js";
-import { FLUID_CASCADE_DEVIATION_CELLS } from "../coupling/chunk_fluid_cascade_epilogue.js";
-import { FLUID_MAC_STEP_STRUCT } from "./FLUID_MAC_STEP_STRUCT.js";
-import { shader_fluid_mac_advect_correct } from "./shader_fluid_mac_advect_correct.js";
-import { shader_fluid_mac_advect_predict } from "./shader_fluid_mac_advect_predict.js";
-import { shader_fluid_mac_curl } from "./shader_fluid_mac_curl.js";
-import { shader_fluid_mac_divergence } from "./shader_fluid_mac_divergence.js";
-import { shader_fluid_mac_gradient } from "./shader_fluid_mac_gradient.js";
-import { shader_fluid_cascade_ghosts } from "../coupling/shader_fluid_cascade_ghosts.js";
-import { FLUID_CASCADE_GHOST_DEPTH } from "../coupling/FLUID_CASCADE_GHOSTS.js";
-
-/**
- * @typedef {import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
- * @typedef {import("./FluidMacVelocitySet.js").FluidMacVelocitySet} FluidMacVelocitySet
- * @typedef {{u: GPUTextureView, v: GPUTextureView, w: GPUTextureView}} FluidMacVelocityViews a MAC
- *   velocity field's three component views: a {@link FluidMacVelocitySet}'s, or a frame graph's
- *   transient textures'
- * @typedef {{uniform: GPUBuffer, u: GPUTextureView, v: GPUTextureView, w: GPUTextureView, pressure: GPUBuffer}} FluidCascadeParentBindings
- *   what a step reads of its parent beyond its window: `uniform`, the parent as
- *   {@link FLUID_CASCADE_PARENT_STRUCT}; `u`, `v`, `w`, its persistent faces; `pressure`, its pressure.
- *   A far-field parent binds stand-ins it never reads.
- * @typedef {{u: GPUTextureView, v: GPUTextureView, w: GPUTextureView, pressure: GPUBuffer}} FluidCascadeGhostBindings
- *   a step's ghosts (`shader_fluid_cascade_ghosts`): `u`, `v`, `w`, the velocity shells, transient
- *   `r32float` textures of each face lattice grown by `FLUID_CASCADE_GHOST_DEPTH` on every side;
- *   `pressure`, the pressure ghosts over the window grown by one cell.
- */
-
-/**
- * Records the MAC passes of one cascade's step (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8): the
- * advection (predict, then correct), the right-hand side of the pressure solve, and the gradient
- * subtraction that writes the step's end velocity. The pressure solve between the last two is not
- * here.
- *
- * One instance a cascade. {@link place} puts its window, {@link set_step} sets a step's h, dt and far
- * field, and each `record_*` records into the encoder a frame-graph pass hands its callback. Each
- * record serialises the step's parameters into a transient uniform of its own (pooled by the
- * encoder), so a step recorded later in the frame cannot change what an earlier one reads.
- *
- * The step's order and what moves between the passes, A the cascade's persistent velocity:
- *
- *     record_ghosts(encoder, parent, G)                                parent → G (the step's ghosts)
- *     record_curl(encoder, A, solid, C)                                A → C, the confinement force (with confinement)
- *     record_advect(encoder, A, F, B, solid, forcing, C, parent, G)    A → F (predict), A + F + C + forcing → B (correct)
- *     record_divergence(encoder, B, solid, rhs, words)                 B → rhs = div/dt, solid → level 0 words
- *     (the pressure solve: rhs → pressure, its ghosts G)
- *     record_gradient(encoder, B, pressure, solid, A, G)               B + pressure → A
- *
- * so A is the only velocity a cascade keeps between steps, and F and B are transients. Beyond the
- * window, the advection reads the step's ghosts of the parent's faces and the gradient those of its
- * pressure ({@link FluidCascadeGhostBindings}), each written once a step from the parent
- * ({@link FluidCascadeParentBindings}).
- *
- * Every pass dispatches `(nx / 8, ny / 8, nz / 4)` workgroups, the ghosts `ceil((n + 1 + 2·depth) / 4)`
- * on each axis, a texel of the largest shell an invocation. Nothing here allocates once placed:
- * the parameters, bindings and dispatch arguments are retained and rewritten in place.
- */
-export class FluidMacPasses {
-    /**
-     * Offer the compute pipelines the MAC step passes dispatch — see {@link PipelineEnquiry}.
-     *
-     * @param {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} enquiry
-     */
-    static enquirePipelines(enquiry) {
-        enquiry.compute.push(
-            shader_fluid_mac_advect_correct.pipeline,
-            shader_fluid_mac_advect_predict.pipeline,
-            shader_fluid_mac_curl.pipeline,
-            shader_fluid_mac_divergence.pipeline,
-            shader_fluid_mac_gradient.pipeline,
-            shader_fluid_cascade_ghosts.pipeline,
-        );
-    }
-
-    /** The value of {@link FLUID_MAC_STEP_STRUCT}, rewritten in place. */
-    #step = {
-        cells: fluid_cascade_window_value(),
-        faces_u: fluid_cascade_window_value(),
-        faces_v: fluid_cascade_window_value(),
-        faces_w: fluid_cascade_window_value(),
-        far_velocity: new Float32Array(3),
-        dt_over_h: 0,
-        far_velocity_end: new Float32Array(3),
-        rhs_scale: 0,
-        keep: 1,
-        deviation_limit: 0,
-        band: 0,
-        confinement_dt: 0,
-    };
-
-    #placed = false;
-    #stepped = false;
-
-    /** Stand-in words buffer when {@link record_divergence} is called without an explicit words buffer. */
-    #stand_in_device = null;
-    #stand_in_words = null;
-
-    #curl = {
-        encoder: null,
-        bindings: { step: null, source_u: null, source_v: null, source_w: null, solid: null, confinement: null },
-        group_count_x: 1, group_count_y: 1, group_count_z: 1,
-    };
-
-    #predict = {
-        encoder: null,
-        bindings: {
-            step: null, source_u: null, source_v: null, source_w: null,
-            ghost_u: null, ghost_v: null, ghost_w: null,
-            solid: null, forward_u: null, forward_v: null, forward_w: null,
-        },
-        group_count_x: 1, group_count_y: 1, group_count_z: 1,
-    };
-
-    #correct = {
-        encoder: null,
-        bindings: {
-            step: null, parent: null, source_u: null, source_v: null, source_w: null, forward_u: null, forward_v: null, forward_w: null,
-            parent_u: null, parent_v: null, parent_w: null, ghost_u: null, ghost_v: null, ghost_w: null,
-            solid: null, forcing: null, confinement: null, out_u: null, out_v: null, out_w: null,
-        },
-        group_count_x: 1, group_count_y: 1, group_count_z: 1,
-    };
-
-    #divergence = {
-        encoder: null,
-        bindings: { step: null, velocity_u: null, velocity_v: null, velocity_w: null, solid: null, rhs: null, words: null },
-        group_count_x: 1, group_count_y: 1, group_count_z: 1,
-    };
-
-    #ghosts = {
-        encoder: null,
-        bindings: {
-            step: null, parent: null, parent_u: null, parent_v: null, parent_w: null, parent_pressure: null,
-            ghost_u: null, ghost_v: null, ghost_w: null, ghost_pressure: null,
-        },
-        group_count_x: 1, group_count_y: 1, group_count_z: 1,
-    };
-
-    #gradient = {
-        encoder: null,
-        bindings: {
-            step: null, velocity_u: null, velocity_v: null, velocity_w: null, pressure: null, ghost_pressure: null,
-            solid: null, out_u: null, out_v: null, out_w: null,
-        },
-        group_count_x: 1, group_count_y: 1, group_count_z: 1,
-    };
-
-    /**
-     * Where the cascade's window is.
-     *
-     * @param {ArrayLike<number>} resolution cells on each axis, each a power of two, at least 8, 8, 4
-     * @param {ArrayLike<number>} corner the world cell at window-local (0, 0, 0)
-     */
-    place(resolution, corner) {
-        for (let i = 0; i < 3; i++) {
-            assert.isNonNegativeInteger(resolution[i], 'resolution');
-            assert.ok(isPowerOfTwo(resolution[i]), 'resolution is a power of two on each axis');
-            assert.greaterThanOrEqual(resolution[i], GRID_TILE_SIZE[i], 'resolution holds a whole tile on each axis');
-            assert.isInteger(corner[i], 'corner');
-        }
-
-        const step = this.#step;
-
-        fluid_cascade_window_place(step.cells, corner, resolution, -1);
-        fluid_cascade_window_place(step.faces_u, corner, resolution, 0);
-        fluid_cascade_window_place(step.faces_v, corner, resolution, 1);
-        fluid_cascade_window_place(step.faces_w, corner, resolution, 2);
-
-        const x = resolution[0] / GRID_TILE_SIZE[0];
-        const y = resolution[1] / GRID_TILE_SIZE[1];
-        const z = resolution[2] / GRID_TILE_SIZE[2];
-
-        for (const pass of [this.#curl, this.#predict, this.#correct, this.#divergence, this.#gradient]) {
-            pass.group_count_x = x;
-            pass.group_count_y = y;
-            pass.group_count_z = z;
-        }
-
-        // the ghosts: a texel of the largest shell an invocation
-        const ghosts = this.#ghosts;
-        ghosts.group_count_x = Math.ceil((resolution[0] + 1 + 2 * FLUID_CASCADE_GHOST_DEPTH) / 4);
-        ghosts.group_count_y = Math.ceil((resolution[1] + 1 + 2 * FLUID_CASCADE_GHOST_DEPTH) / 4);
-        ghosts.group_count_z = Math.ceil((resolution[2] + 1 + 2 * FLUID_CASCADE_GHOST_DEPTH) / 4);
-
-        this.#placed = true;
-    }
-
-    /**
-     * The step about to be recorded, from `t₀` to `t₁` (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §6, §8).
-     *
-     * @param {number} h cell size, m
-     * @param {number} dt time step, s
-     * @param {ArrayLike<number>} far_velocity `v_far(t₀)`, m/s: what the velocity the step starts from
-     *   is a deviation from
-     * @param {ArrayLike<number>} far_velocity_end `v_far(t₁)`, m/s
-     * @param {number} keep `e^(−(Λ(t₁) − Λ(t₀)))`, in [0, 1]
-     * @param {boolean} band whether the faces of rows 2..5 relax toward the parent
-     * @param {number} confinement the vorticity confinement's strength ε, per second, ≥ 0: 0 for none,
-     *   and then {@link record_curl} is not recorded for the step
-     */
-    set_step(h, dt, far_velocity, far_velocity_end, keep, band, confinement) {
-        assert.isFinite(h, 'h'); assert.greaterThan(h, 0, 'h');
-        assert.isFinite(dt, 'dt'); assert.greaterThan(dt, 0, 'dt');
-        assert.isFinite(keep, 'keep');
-        assert.greaterThanOrEqual(keep, 0, 'keep');
-        assert.lessThanOrEqual(keep, 1, 'keep');
-        assert.isBoolean(band, 'band');
-        assert.isFinite(confinement, 'confinement');
-        assert.greaterThanOrEqual(confinement, 0, 'confinement');
-
-        const step = this.#step;
-
-        step.dt_over_h = dt / h;
-        step.rhs_scale = 1 / (h * dt);
-        step.keep = keep;
-        step.deviation_limit = FLUID_CASCADE_DEVIATION_CELLS * h / dt;
-        step.band = band ? 1 : 0;
-        step.confinement_dt = confinement * dt;
-
-        for (let i = 0; i < 3; i++) {
-            assert.isFinite(far_velocity[i], 'far_velocity');
-            assert.isFinite(far_velocity_end[i], 'far_velocity_end');
-
-            step.far_velocity[i] = far_velocity[i];
-            step.far_velocity_end[i] = far_velocity_end[i];
-        }
-
-        this.#stepped = true;
-    }
-
-    /**
-     * @param {ShadeGPUCommandContext} encoder
-     * @returns {GPUBuffer}
-     */
-    #uniform(encoder) {
-        assert.ok(this.#placed, 'placed before recording');
-        assert.ok(this.#stepped, 'a step set before recording');
-
-        return encoder.allocateTransientValueBuffer(FLUID_MAC_STEP_STRUCT, this.#step, GPUBufferUsage.UNIFORM);
-    }
-
-    /**
-     * The step's vorticity confinement, pass 1 (`shader_fluid_mac_curl`): the curl of the persistent
-     * velocity and the force it makes in every cell, for the correct pass. Recorded only for a step whose
-     * confinement is not 0, before {@link record_advect}.
-     *
-     * @param {ShadeGPUCommandContext} encoder
-     * @param {FluidMacVelocityViews} source the persistent velocity, toroidal; read
-     * @param {GPUBuffer} solid the window-local solid flags, `array<u32>`, bit 0
-     * @param {GPUBuffer} confinement written, `array<f32>` of 3·N cells, window-local
-     */
-    record_curl(encoder, source, solid, confinement) {
-        assert.greaterThan(this.#step.confinement_dt, 0, 'a step with confinement');
-
-        const pass = this.#curl;
-        const b = pass.bindings;
-        b.step = this.#uniform(encoder);
-        b.source_u = source.u; b.source_v = source.v; b.source_w = source.w;
-        b.solid = solid;
-        b.confinement = confinement;
-        pass.encoder = encoder;
-
-        shader_fluid_mac_curl.dispatch(pass);
-
-        pass.encoder = null;
-        b.confinement = null;
-    }
-
-    /**
-     * MacCormack advection of the persistent velocity by itself: predict into `forward`, then correct
-     * into `out`, which adds the step's confinement and the tick's forcing.
-     *
-     * @param {ShadeGPUCommandContext} encoder
-     * @param {FluidMacVelocityViews} source the persistent velocity, toroidal; read
-     * @param {FluidMacVelocityViews} forward a transient, window-local; written, then read
-     * @param {FluidMacVelocityViews} out a transient, window-local; written
-     * @param {GPUBuffer} solid the window-local solid flags, `array<u32>`: bit 0 solid, bit 1
-     *   (`FLUID_FORCED_FLAG`) forcing written for the cell's faces
-     * @param {GPUBuffer} forcing the tick's forcing, `array<f32>` over the three face lattices
-     *   (`shader_fluid_mac_advect_correct`); read only where `solid` says it was written
-     * @param {GPUBuffer} confinement what {@link record_curl} wrote for the step; read only when the
-     *   step's confinement is not 0
-     * @param {FluidCascadeParentBindings} parent what the relaxation band reads on rows 2..5
-     * @param {FluidCascadeGhostBindings} ghosts the step's ghosts, written by {@link record_ghosts}
-     */
-    record_advect(encoder, source, forward, out, solid, forcing, confinement, parent, ghosts) {
-        assert.notEqual(source, forward, 'source and forward are different sets');
-        assert.notEqual(source, out, 'source and out are different sets');
-        assert.notEqual(forward, out, 'forward and out are different sets');
-
-        const step = this.#uniform(encoder);
-
-        const predict = this.#predict;
-        const p = predict.bindings;
-        p.step = step;
-        p.source_u = source.u; p.source_v = source.v; p.source_w = source.w;
-        p.ghost_u = ghosts.u; p.ghost_v = ghosts.v; p.ghost_w = ghosts.w;
-        p.solid = solid;
-        p.forward_u = forward.u; p.forward_v = forward.v; p.forward_w = forward.w;
-        predict.encoder = encoder;
-
-        shader_fluid_mac_advect_predict.dispatch(predict);
-
-        const correct = this.#correct;
-        const c = correct.bindings;
-        c.step = step;
-        c.parent = parent.uniform;
-        c.source_u = source.u; c.source_v = source.v; c.source_w = source.w;
-        c.forward_u = forward.u; c.forward_v = forward.v; c.forward_w = forward.w;
-        c.parent_u = parent.u; c.parent_v = parent.v; c.parent_w = parent.w;
-        c.ghost_u = ghosts.u; c.ghost_v = ghosts.v; c.ghost_w = ghosts.w;
-        c.solid = solid;
-        c.forcing = forcing;
-        c.confinement = confinement;
-        c.out_u = out.u; c.out_v = out.v; c.out_w = out.w;
-        correct.encoder = encoder;
-
-        shader_fluid_mac_advect_correct.dispatch(correct);
-
-        predict.encoder = null;
-        correct.encoder = null;
-        c.forcing = null;
-        c.confinement = null;
-    }
-
-    /**
-     * The step's ghosts (`shader_fluid_cascade_ghosts`): the parent's identity read at every face of the
-     * velocity shells and its pressure at every cell one past the window, once, for the step's passes.
-     *
-     * @param {ShadeGPUCommandContext} encoder
-     * @param {FluidCascadeParentBindings} parent
-     * @param {FluidCascadeGhostBindings} ghosts written
-     */
-    record_ghosts(encoder, parent, ghosts) {
-        const pass = this.#ghosts;
-        const b = pass.bindings;
-        b.step = this.#uniform(encoder);
-        b.parent = parent.uniform;
-        b.parent_u = parent.u; b.parent_v = parent.v; b.parent_w = parent.w;
-        b.parent_pressure = parent.pressure;
-        b.ghost_u = ghosts.u; b.ghost_v = ghosts.v; b.ghost_w = ghosts.w;
-        b.ghost_pressure = ghosts.pressure;
-        pass.encoder = encoder;
-
-        shader_fluid_cascade_ghosts.dispatch(pass);
-
-        pass.encoder = null;
-    }
-
-    /**
-     * @param {GPUDevice} device
-     * @param {number} size
-     * @returns {GPUBuffer}
-     */
-    #ensure_stand_in_words(device, size) {
-        if (this.#stand_in_device === device && this.#stand_in_words !== null && this.#stand_in_words.size === size) {
-            return this.#stand_in_words;
-        }
-
-        this.#stand_in_words?.destroy();
-        this.#stand_in_device = device;
-        this.#stand_in_words = device.createBuffer({
-            label: 'Fluid / MAC / stand-in words',
-            size,
-            usage: GPUBufferUsage.STORAGE,
-        });
-
-        return this.#stand_in_words;
-    }
-
-    /**
-     * The right-hand side and finest-level weight words of the pressure solve, `div/dt` at every cell,
-     * 0 in solid cells.
-     *
-     * @param {ShadeGPUCommandContext} encoder
-     * @param {FluidMacVelocityViews} velocity the advected velocity, window-local; read
-     * @param {GPUBuffer} solid the window-local solid flags, `array<u32>`, bit 0
-     * @param {GPUBuffer} rhs written, `array<f32>` of N cells, window-local, x fastest
-     * @param {GPUBuffer} [words] written, `array<u32>` of N cells, the finest level's weight words
-     */
-    record_divergence(encoder, velocity, solid, rhs, words = null) {
-        const pass = this.#divergence;
-        const b = pass.bindings;
-        b.step = this.#uniform(encoder);
-        b.velocity_u = velocity.u; b.velocity_v = velocity.v; b.velocity_w = velocity.w;
-        b.solid = solid;
-        b.rhs = rhs;
-        b.words = words ?? this.#ensure_stand_in_words(encoder.device, rhs.size);
-        pass.encoder = encoder;
-
-        shader_fluid_mac_divergence.dispatch(pass);
-
-        pass.encoder = null;
-        b.words = null;
-    }
-
-    /**
-     * The pressure gradient taken from the advected velocity, into the persistent velocity.
-     *
-     * @param {ShadeGPUCommandContext} encoder
-     * @param {FluidMacVelocityViews} velocity the advected velocity, window-local; read
-     * @param {GPUBuffer} pressure kinematic pressure, m²/s², `array<f32>` of N cells, toroidal; read
-     * @param {GPUBuffer} solid the window-local solid flags, `array<u32>`, bit 0
-     * @param {FluidMacVelocityViews} out the persistent velocity, toroidal; written
-     * @param {FluidCascadeGhostBindings} ghosts the step's ghosts: `pressure` is the pressure beyond the window
-     */
-    record_gradient(encoder, velocity, pressure, solid, out, ghosts) {
-        assert.notEqual(velocity, out, 'velocity and out are different sets');
-        assert.notEqual(pressure, ghosts.pressure, 'the ghosts are not the cascade\'s pressure');
-
-        const pass = this.#gradient;
-        const b = pass.bindings;
-        b.step = this.#uniform(encoder);
-        b.velocity_u = velocity.u; b.velocity_v = velocity.v; b.velocity_w = velocity.w;
-        b.pressure = pressure;
-        b.ghost_pressure = ghosts.pressure;
-        b.solid = solid;
-        b.out_u = out.u; b.out_v = out.v; b.out_w = out.w;
-        pass.encoder = encoder;
-
-        shader_fluid_mac_gradient.dispatch(pass);
-
-        pass.encoder = null;
-    }
-}
+import { assert } from "../../../../core/assert.js";
+import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
+import { GRID_TILE_SIZE } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
+import { fluid_cascade_window_place, fluid_cascade_window_value } from "../fluid_cascade_window.js";
+import { FLUID_CASCADE_DEVIATION_CELLS } from "../coupling/chunk_fluid_cascade_epilogue.js";
+import { FLUID_MAC_STEP_STRUCT } from "./FLUID_MAC_STEP_STRUCT.js";
+import { shader_fluid_mac_advect_correct } from "./shader_fluid_mac_advect_correct.js";
+import { shader_fluid_mac_advect_predict } from "./shader_fluid_mac_advect_predict.js";
+import { shader_fluid_mac_curl } from "./shader_fluid_mac_curl.js";
+import { shader_fluid_mac_divergence } from "./shader_fluid_mac_divergence.js";
+import { shader_fluid_mac_gradient } from "./shader_fluid_mac_gradient.js";
+import { shader_fluid_cascade_ghosts } from "../coupling/shader_fluid_cascade_ghosts.js";
+import { FLUID_CASCADE_GHOST_DEPTH } from "../coupling/FLUID_CASCADE_GHOSTS.js";
+import { fluid_far_field_value } from "../FLUID_FAR_FIELD_STRUCT.js";
+
+/**
+ * @typedef {import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
+ * @typedef {import("./FluidMacVelocitySet.js").FluidMacVelocitySet} FluidMacVelocitySet
+ * @typedef {{u: GPUTextureView, v: GPUTextureView, w: GPUTextureView}} FluidMacVelocityViews a MAC
+ *   velocity field's three component views: a {@link FluidMacVelocitySet}'s, or a frame graph's
+ *   transient textures'
+ * @typedef {{uniform: GPUBuffer, u: GPUTextureView, v: GPUTextureView, w: GPUTextureView, pressure: GPUBuffer, turbulence: GPUTextureView}} FluidCascadeParentBindings
+ *   what a step reads of its parent beyond its window: `uniform`, the parent as
+ *   {@link FLUID_CASCADE_PARENT_STRUCT}; `u`, `v`, `w`, its persistent faces; `pressure`, its pressure;
+ *   `turbulence`, the far field's turbulence tile, which the step's far field reads too. A far-field
+ *   parent binds stand-ins it never reads.
+ * @typedef {{u: GPUTextureView, v: GPUTextureView, w: GPUTextureView, pressure: GPUBuffer}} FluidCascadeGhostBindings
+ *   a step's ghosts (`shader_fluid_cascade_ghosts`): `u`, `v`, `w`, the velocity shells, transient
+ *   `r32float` textures of each face lattice grown by `FLUID_CASCADE_GHOST_DEPTH` on every side;
+ *   `pressure`, the pressure ghosts over the window grown by one cell.
+ */
+
+/**
+ * Copy a far field value ({@link FLUID_FAR_FIELD_STRUCT}) into another, checking it is finite.
+ *
+ * @param {{mean: Float32Array, sigma: number, origin: Float32Array, scale: Float32Array}} out
+ * @param {{mean: ArrayLike<number>, sigma: number, origin: ArrayLike<number>, scale: ArrayLike<number>}} from
+ */
+function copy_far_field(out, from) {
+    assert.isFinite(from.sigma, 'sigma');
+
+    for (let i = 0; i < 3; i++) {
+        assert.isFinite(from.mean[i], 'far mean');
+        assert.isFinite(from.origin[i], 'far origin');
+        assert.isFinite(from.scale[i], 'far scale');
+
+        out.mean[i] = from.mean[i];
+        out.origin[i] = from.origin[i];
+        out.scale[i] = from.scale[i];
+    }
+
+    out.sigma = from.sigma;
+    out.lod = from.lod ?? 0;
+}
+
+/**
+ * Records the MAC passes of one cascade's step (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8): the
+ * advection (predict, then correct), the right-hand side of the pressure solve, and the gradient
+ * subtraction that writes the step's end velocity. The pressure solve between the last two is not
+ * here.
+ *
+ * One instance a cascade. {@link place} puts its window, {@link set_step} sets a step's h, dt and far
+ * field, and each `record_*` records into the encoder a frame-graph pass hands its callback. Each
+ * record serialises the step's parameters into a transient uniform of its own (pooled by the
+ * encoder), so a step recorded later in the frame cannot change what an earlier one reads.
+ *
+ * The step's order and what moves between the passes, A the cascade's persistent velocity:
+ *
+ *     record_ghosts(encoder, parent, G)                                parent → G (the step's ghosts)
+ *     record_curl(encoder, A, solid, C)                                A → C, the confinement force (with confinement)
+ *     record_advect(encoder, A, F, B, solid, forcing, C, parent, G)    A → F (predict), A + F + C + forcing → B (correct)
+ *     record_divergence(encoder, B, solid, rhs, words)                 B → rhs = div/dt, solid → level 0 words
+ *     (the pressure solve: rhs → pressure, its ghosts G)
+ *     record_gradient(encoder, B, pressure, solid, A, G)               B + pressure → A
+ *
+ * so A is the only velocity a cascade keeps between steps, and F and B are transients. Beyond the
+ * window, the advection reads the step's ghosts of the parent's faces and the gradient those of its
+ * pressure ({@link FluidCascadeGhostBindings}), each written once a step from the parent
+ * ({@link FluidCascadeParentBindings}).
+ *
+ * Every pass dispatches `(nx / 8, ny / 8, nz / 4)` workgroups, the ghosts `ceil((n + 1 + 2·depth) / 4)`
+ * on each axis, a texel of the largest shell an invocation. Nothing here allocates once placed:
+ * the parameters, bindings and dispatch arguments are retained and rewritten in place.
+ */
+export class FluidMacPasses {
+    /**
+     * Offer the compute pipelines the MAC step passes dispatch — see {@link PipelineEnquiry}.
+     *
+     * @param {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry) {
+        enquiry.compute.push(
+            shader_fluid_mac_advect_correct.pipeline,
+            shader_fluid_mac_advect_predict.pipeline,
+            shader_fluid_mac_curl.pipeline,
+            shader_fluid_mac_divergence.pipeline,
+            shader_fluid_mac_gradient.pipeline,
+            shader_fluid_cascade_ghosts.pipeline,
+        );
+    }
+
+    /** The value of {@link FLUID_MAC_STEP_STRUCT}, rewritten in place. */
+    #step = {
+        cells: fluid_cascade_window_value(),
+        faces_u: fluid_cascade_window_value(),
+        faces_v: fluid_cascade_window_value(),
+        faces_w: fluid_cascade_window_value(),
+        far: fluid_far_field_value(),
+        far_end: fluid_far_field_value(),
+        dt_over_h: 0,
+        rhs_scale: 0,
+        keep: 1,
+        deviation_limit: 0,
+        band: 0,
+        confinement_dt: 0,
+    };
+
+    #placed = false;
+    #stepped = false;
+
+    /** Stand-in words buffer when {@link record_divergence} is called without an explicit words buffer. */
+    #stand_in_device = null;
+    #stand_in_words = null;
+
+    #curl = {
+        encoder: null,
+        bindings: { step: null, source_u: null, source_v: null, source_w: null, solid: null, confinement: null },
+        group_count_x: 1, group_count_y: 1, group_count_z: 1,
+    };
+
+    #predict = {
+        encoder: null,
+        bindings: {
+            step: null, source_u: null, source_v: null, source_w: null,
+            ghost_u: null, ghost_v: null, ghost_w: null,
+            solid: null, forward_u: null, forward_v: null, forward_w: null,
+        },
+        group_count_x: 1, group_count_y: 1, group_count_z: 1,
+    };
+
+    #correct = {
+        encoder: null,
+        bindings: {
+            step: null, parent: null, source_u: null, source_v: null, source_w: null, forward_u: null, forward_v: null, forward_w: null,
+            parent_u: null, parent_v: null, parent_w: null, ghost_u: null, ghost_v: null, ghost_w: null,
+            solid: null, forcing: null, confinement: null, out_u: null, out_v: null, out_w: null, fluid_turbulence: null,
+        },
+        group_count_x: 1, group_count_y: 1, group_count_z: 1,
+    };
+
+    #divergence = {
+        encoder: null,
+        bindings: { step: null, velocity_u: null, velocity_v: null, velocity_w: null, solid: null, rhs: null, words: null },
+        group_count_x: 1, group_count_y: 1, group_count_z: 1,
+    };
+
+    #ghosts = {
+        encoder: null,
+        bindings: {
+            step: null, parent: null, parent_u: null, parent_v: null, parent_w: null, parent_pressure: null,
+            ghost_u: null, ghost_v: null, ghost_w: null, ghost_pressure: null, fluid_turbulence: null,
+        },
+        group_count_x: 1, group_count_y: 1, group_count_z: 1,
+    };
+
+    #gradient = {
+        encoder: null,
+        bindings: {
+            step: null, velocity_u: null, velocity_v: null, velocity_w: null, pressure: null, ghost_pressure: null,
+            solid: null, out_u: null, out_v: null, out_w: null,
+        },
+        group_count_x: 1, group_count_y: 1, group_count_z: 1,
+    };
+
+    /**
+     * Where the cascade's window is.
+     *
+     * @param {ArrayLike<number>} resolution cells on each axis, each a power of two, at least 8, 8, 4
+     * @param {ArrayLike<number>} corner the world cell at window-local (0, 0, 0)
+     */
+    place(resolution, corner) {
+        for (let i = 0; i < 3; i++) {
+            assert.isNonNegativeInteger(resolution[i], 'resolution');
+            assert.ok(isPowerOfTwo(resolution[i]), 'resolution is a power of two on each axis');
+            assert.greaterThanOrEqual(resolution[i], GRID_TILE_SIZE[i], 'resolution holds a whole tile on each axis');
+            assert.isInteger(corner[i], 'corner');
+        }
+
+        const step = this.#step;
+
+        fluid_cascade_window_place(step.cells, corner, resolution, -1);
+        fluid_cascade_window_place(step.faces_u, corner, resolution, 0);
+        fluid_cascade_window_place(step.faces_v, corner, resolution, 1);
+        fluid_cascade_window_place(step.faces_w, corner, resolution, 2);
+
+        const x = resolution[0] / GRID_TILE_SIZE[0];
+        const y = resolution[1] / GRID_TILE_SIZE[1];
+        const z = resolution[2] / GRID_TILE_SIZE[2];
+
+        for (const pass of [this.#curl, this.#predict, this.#correct, this.#divergence, this.#gradient]) {
+            pass.group_count_x = x;
+            pass.group_count_y = y;
+            pass.group_count_z = z;
+        }
+
+        // the ghosts: a texel of the largest shell an invocation
+        const ghosts = this.#ghosts;
+        ghosts.group_count_x = Math.ceil((resolution[0] + 1 + 2 * FLUID_CASCADE_GHOST_DEPTH) / 4);
+        ghosts.group_count_y = Math.ceil((resolution[1] + 1 + 2 * FLUID_CASCADE_GHOST_DEPTH) / 4);
+        ghosts.group_count_z = Math.ceil((resolution[2] + 1 + 2 * FLUID_CASCADE_GHOST_DEPTH) / 4);
+
+        this.#placed = true;
+    }
+
+    /**
+     * The step about to be recorded, from `t₀` to `t₁` (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §6, §8).
+     *
+     * @param {number} h cell size, m
+     * @param {number} dt time step, s
+     * @param {{mean: ArrayLike<number>, sigma: number, origin: ArrayLike<number>, scale: ArrayLike<number>}} far
+     *   `v_far(t₀)` as {@link FLUID_MAC_STEP_STRUCT} `far` holds it, over the window's cells: what the
+     *   velocity the step starts from is a deviation from
+     * @param {{mean: ArrayLike<number>, sigma: number, origin: ArrayLike<number>, scale: ArrayLike<number>}} far_end
+     *   `v_far(t₁)`, likewise
+     * @param {number} keep `e^(−(Λ(t₁) − Λ(t₀)))`, in [0, 1]
+     * @param {boolean} band whether the faces of rows 2..5 relax toward the parent
+     * @param {number} confinement the vorticity confinement's strength ε, per second, ≥ 0: 0 for none,
+     *   and then {@link record_curl} is not recorded for the step
+     */
+    set_step(h, dt, far, far_end, keep, band, confinement) {
+        assert.isFinite(h, 'h'); assert.greaterThan(h, 0, 'h');
+        assert.isFinite(dt, 'dt'); assert.greaterThan(dt, 0, 'dt');
+        assert.isFinite(keep, 'keep');
+        assert.greaterThanOrEqual(keep, 0, 'keep');
+        assert.lessThanOrEqual(keep, 1, 'keep');
+        assert.isBoolean(band, 'band');
+        assert.isFinite(confinement, 'confinement');
+        assert.greaterThanOrEqual(confinement, 0, 'confinement');
+
+        const step = this.#step;
+
+        step.dt_over_h = dt / h;
+        step.rhs_scale = 1 / (h * dt);
+        step.keep = keep;
+        step.deviation_limit = FLUID_CASCADE_DEVIATION_CELLS * h / dt;
+        step.band = band ? 1 : 0;
+        step.confinement_dt = confinement * dt;
+
+        copy_far_field(step.far, far);
+        copy_far_field(step.far_end, far_end);
+
+        this.#stepped = true;
+    }
+
+    /**
+     * @param {ShadeGPUCommandContext} encoder
+     * @returns {GPUBuffer}
+     */
+    #uniform(encoder) {
+        assert.ok(this.#placed, 'placed before recording');
+        assert.ok(this.#stepped, 'a step set before recording');
+
+        return encoder.allocateTransientValueBuffer(FLUID_MAC_STEP_STRUCT, this.#step, GPUBufferUsage.UNIFORM);
+    }
+
+    /**
+     * The step's vorticity confinement, pass 1 (`shader_fluid_mac_curl`): the curl of the persistent
+     * velocity and the force it makes in every cell, for the correct pass. Recorded only for a step whose
+     * confinement is not 0, before {@link record_advect}.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {FluidMacVelocityViews} source the persistent velocity, toroidal; read
+     * @param {GPUBuffer} solid the window-local solid flags, `array<u32>`, bit 0
+     * @param {GPUBuffer} confinement written, `array<f32>` of 3·N cells, window-local
+     */
+    record_curl(encoder, source, solid, confinement) {
+        assert.greaterThan(this.#step.confinement_dt, 0, 'a step with confinement');
+
+        const pass = this.#curl;
+        const b = pass.bindings;
+        b.step = this.#uniform(encoder);
+        b.source_u = source.u; b.source_v = source.v; b.source_w = source.w;
+        b.solid = solid;
+        b.confinement = confinement;
+        pass.encoder = encoder;
+
+        shader_fluid_mac_curl.dispatch(pass);
+
+        pass.encoder = null;
+        b.confinement = null;
+    }
+
+    /**
+     * MacCormack advection of the persistent velocity by itself: predict into `forward`, then correct
+     * into `out`, which adds the step's confinement and the tick's forcing.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {FluidMacVelocityViews} source the persistent velocity, toroidal; read
+     * @param {FluidMacVelocityViews} forward a transient, window-local; written, then read
+     * @param {FluidMacVelocityViews} out a transient, window-local; written
+     * @param {GPUBuffer} solid the window-local solid flags, `array<u32>`: bit 0 solid, bit 1
+     *   (`FLUID_FORCED_FLAG`) forcing written for the cell's faces
+     * @param {GPUBuffer} forcing the tick's forcing, `array<f32>` over the three face lattices
+     *   (`shader_fluid_mac_advect_correct`); read only where `solid` says it was written
+     * @param {GPUBuffer} confinement what {@link record_curl} wrote for the step; read only when the
+     *   step's confinement is not 0
+     * @param {FluidCascadeParentBindings} parent what the relaxation band reads on rows 2..5
+     * @param {FluidCascadeGhostBindings} ghosts the step's ghosts, written by {@link record_ghosts}
+     */
+    record_advect(encoder, source, forward, out, solid, forcing, confinement, parent, ghosts) {
+        assert.notEqual(source, forward, 'source and forward are different sets');
+        assert.notEqual(source, out, 'source and out are different sets');
+        assert.notEqual(forward, out, 'forward and out are different sets');
+
+        const step = this.#uniform(encoder);
+
+        const predict = this.#predict;
+        const p = predict.bindings;
+        p.step = step;
+        p.source_u = source.u; p.source_v = source.v; p.source_w = source.w;
+        p.ghost_u = ghosts.u; p.ghost_v = ghosts.v; p.ghost_w = ghosts.w;
+        p.solid = solid;
+        p.forward_u = forward.u; p.forward_v = forward.v; p.forward_w = forward.w;
+        predict.encoder = encoder;
+
+        shader_fluid_mac_advect_predict.dispatch(predict);
+
+        const correct = this.#correct;
+        const c = correct.bindings;
+        c.step = step;
+        c.parent = parent.uniform;
+        c.source_u = source.u; c.source_v = source.v; c.source_w = source.w;
+        c.forward_u = forward.u; c.forward_v = forward.v; c.forward_w = forward.w;
+        c.parent_u = parent.u; c.parent_v = parent.v; c.parent_w = parent.w;
+        c.ghost_u = ghosts.u; c.ghost_v = ghosts.v; c.ghost_w = ghosts.w;
+        c.solid = solid;
+        c.forcing = forcing;
+        c.confinement = confinement;
+        c.out_u = out.u; c.out_v = out.v; c.out_w = out.w;
+        c.fluid_turbulence = parent.turbulence;
+        correct.encoder = encoder;
+
+        shader_fluid_mac_advect_correct.dispatch(correct);
+
+        predict.encoder = null;
+        correct.encoder = null;
+        c.forcing = null;
+        c.confinement = null;
+        c.fluid_turbulence = null;
+    }
+
+    /**
+     * The step's ghosts (`shader_fluid_cascade_ghosts`): the parent's identity read at every face of the
+     * velocity shells and its pressure at every cell one past the window, once, for the step's passes.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {FluidCascadeParentBindings} parent
+     * @param {FluidCascadeGhostBindings} ghosts written
+     */
+    record_ghosts(encoder, parent, ghosts) {
+        const pass = this.#ghosts;
+        const b = pass.bindings;
+        b.step = this.#uniform(encoder);
+        b.parent = parent.uniform;
+        b.parent_u = parent.u; b.parent_v = parent.v; b.parent_w = parent.w;
+        b.parent_pressure = parent.pressure;
+        b.ghost_u = ghosts.u; b.ghost_v = ghosts.v; b.ghost_w = ghosts.w;
+        b.ghost_pressure = ghosts.pressure;
+        b.fluid_turbulence = parent.turbulence;
+        pass.encoder = encoder;
+
+        shader_fluid_cascade_ghosts.dispatch(pass);
+
+        pass.encoder = null;
+        b.fluid_turbulence = null;
+    }
+
+    /**
+     * @param {GPUDevice} device
+     * @param {number} size
+     * @returns {GPUBuffer}
+     */
+    #ensure_stand_in_words(device, size) {
+        if (this.#stand_in_device === device && this.#stand_in_words !== null && this.#stand_in_words.size === size) {
+            return this.#stand_in_words;
+        }
+
+        this.#stand_in_words?.destroy();
+        this.#stand_in_device = device;
+        this.#stand_in_words = device.createBuffer({
+            label: 'Fluid / MAC / stand-in words',
+            size,
+            usage: GPUBufferUsage.STORAGE,
+        });
+
+        return this.#stand_in_words;
+    }
+
+    /**
+     * The right-hand side and finest-level weight words of the pressure solve, `div/dt` at every cell,
+     * 0 in solid cells.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {FluidMacVelocityViews} velocity the advected velocity, window-local; read
+     * @param {GPUBuffer} solid the window-local solid flags, `array<u32>`, bit 0
+     * @param {GPUBuffer} rhs written, `array<f32>` of N cells, window-local, x fastest
+     * @param {GPUBuffer} [words] written, `array<u32>` of N cells, the finest level's weight words
+     */
+    record_divergence(encoder, velocity, solid, rhs, words = null) {
+        const pass = this.#divergence;
+        const b = pass.bindings;
+        b.step = this.#uniform(encoder);
+        b.velocity_u = velocity.u; b.velocity_v = velocity.v; b.velocity_w = velocity.w;
+        b.solid = solid;
+        b.rhs = rhs;
+        b.words = words ?? this.#ensure_stand_in_words(encoder.device, rhs.size);
+        pass.encoder = encoder;
+
+        shader_fluid_mac_divergence.dispatch(pass);
+
+        pass.encoder = null;
+        b.words = null;
+    }
+
+    /**
+     * The pressure gradient taken from the advected velocity, into the persistent velocity.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {FluidMacVelocityViews} velocity the advected velocity, window-local; read
+     * @param {GPUBuffer} pressure kinematic pressure, m²/s², `array<f32>` of N cells, toroidal; read
+     * @param {GPUBuffer} solid the window-local solid flags, `array<u32>`, bit 0
+     * @param {FluidMacVelocityViews} out the persistent velocity, toroidal; written
+     * @param {FluidCascadeGhostBindings} ghosts the step's ghosts: `pressure` is the pressure beyond the window
+     */
+    record_gradient(encoder, velocity, pressure, solid, out, ghosts) {
+        assert.notEqual(velocity, out, 'velocity and out are different sets');
+        assert.notEqual(pressure, ghosts.pressure, 'the ghosts are not the cascade\'s pressure');
+
+        const pass = this.#gradient;
+        const b = pass.bindings;
+        b.step = this.#uniform(encoder);
+        b.velocity_u = velocity.u; b.velocity_v = velocity.v; b.velocity_w = velocity.w;
+        b.pressure = pressure;
+        b.ghost_pressure = ghosts.pressure;
+        b.solid = solid;
+        b.out_u = out.u; b.out_v = out.v; b.out_w = out.w;
+        pass.encoder = encoder;
+
+        shader_fluid_mac_gradient.dispatch(pass);
+
+        pass.encoder = null;
+    }
+}