@woosh/meep-engine 3.16.0 → 3.17.0

package/src/shade/renderer/particles/optimizer/pass_fold_constants.js

@@ -1,561 +1,678 @@
-import { pack_swizzle, VM_OP, vm_dest_width, vm_encode_word0 } from "../isa/ParticleVMISA.js";
-import { decode_particle_instructions, particle_instruction_is_well_formed } from "./particle_program_analysis.js";
-import { vm_source_lane } from "./particle_vm_semantics.js";
-
-/** @type {string} */
-export const PARTICLE_PASS_FOLD_CONSTANTS = "fold_constants";
-
-/**
- * Track what each register lane is known to hold, and rewrite the instructions that turn out not to
- * need computing.
- *
- * Two things come out of this. Instructions whose every output lane is a known number become a
- * `LOAD_CONST`, which usually makes everything feeding them dead. And instructions that are a known
- * *shape* rather than a known value collapse: a `SELECT` whose condition is a compile-time mask is
- * per-lane copying, and a multiply by one is a copy.
- *
- * The graph compiler emits both shapes constantly. It has no notion of a compile-time-known lane
- * mask, so `graph/particle_graph_distributions.js` assembling `(cos, sin, 0)` out of a `select` on
- * the literal `[0, 1, 0]` lowers to a broadcast, a second broadcast, a constant load and a `SELECT`
- * — four instructions for what is one `MOV`, and this pass is what notices.
- *
- * ## What is not folded, and why
- *
- * A lane is tracked only while its value is FINITE. `NaN` and `±Inf` are dropped from the analysis
- * rather than propagated, which removes at a stroke every rewrite that is right for ordinary numbers
- * and wrong at the edges — `min(NaN, x)` is the reference's `NaN` and the GPU's anything, and a
- * baked `NaN` constant is at the mercy of a driver that assumes there are none.
- *
- * Only operations both executors are obliged to round identically are evaluated here — see
- * `foldable` in {@link ./particle_vm_semantics.js}. Folding `sin` would quietly hand the GPU the
- * CPU's answer.
- *
- * Every identity here is exact — `x * 1`, `x / 1` and `x - (+0)` are `x` for every value a register
- * can hold — with one deliberate exception, below.
- *
- * ## Multiplying by zero: the one place this is not exact
- *
- * `x * 0` is `+0` for finite non-negative `x`, `-0` for finite negative `x`, and `NaN` for `±Inf`
- * and `NaN`. Folding it to `+0` is therefore a fast-math relaxation rather than a rewrite, and it is
- * on by default (`fold_multiply_by_zero`) because a particle effect essentially never needs the
- * distinction and the shape it unlocks is everywhere.
- *
- * That shape is the lane mask. `graph/particle_graph_distributions.js` clears the lanes a disk has
- * nothing to say about by multiplying through `[1, 1, 0]`, and the lowering has no way to know the
- * result of that lane is a constant. With the fold it becomes one, the tail of the instruction is
- * peeled off as a constant load, and the multiply, the mask's own load and the broadcast feeding it
- * all go dead behind it.
- *
- * What it costs, precisely: a `-0` in the record becomes a `+0` — which is what the deleted `RANDOM`
- * distribution modes wrote, so the disk goes back to the sign it had before the samplers moved into
- * the graph — and a lane that was `NaN` because something upstream overflowed becomes zero. Switch
- * it off (`{ passes: { fold_constants: { fold_multiply_by_zero: false } } }`) and every pass in the
- * optimizer is bit-exact again.
- *
- * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
- */
-export function pass_fold_constants(instructions, context) {
-    const decoded = decode_particle_instructions(instructions);
-    const slots = context.register_slots;
-
-    /** Whether a slot's value is known — and finite, which is the only kind that is tracked. */
-    const known = new Uint8Array(slots);
-    /** f32, so a tracked value is exactly the one the register would hold. */
-    const value = new Float32Array(slots);
-
-    const options = {
-        max_select_moves: 2,
-        fold_multiply_by_zero: true,
-        peel_constant_lanes: true,
-        ...context,
-    };
-
-    /** @type {number[][]} */
-    const out = [];
-
-    let changed = false;
-
-    for (const instruction of decoded) {
-        const lanes = evaluate_lanes(instruction, known, value, options);
-        const replacement = rewrite(instruction, lanes, known, value, options);
-
-        if (replacement === null) {
-            out.push(instruction.words);
-        } else {
-            out.push(...replacement);
-            changed = true;
-        }
-
-        publish(instruction, lanes, known, value);
-    }
-
-    return changed ? out : null;
-}
-
-/**
- * What each lane of the destination will hold, as far as it can be worked out here.
- *
- * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
- * @param {Uint8Array} known
- * @param {Float32Array} value
- * @param {object} options
- * @returns {Array<number|null>} one entry per destination lane; `null` where the value is not known
- */
-function evaluate_lanes(instruction, known, value, options) {
-    if (instruction.write === null) {
-        return [];
-    }
-
-    const count = vm_dest_width(instruction.op, instruction.width);
-    /** @type {Array<number|null>} */
-    const lanes = new Array(count).fill(null);
-
-    if (instruction.op === VM_OP.LOAD_CONST) {
-        for (let lane = 0; lane < count; lane++) {
-            lanes[lane] = finite(options.constants[instruction.words[2] + lane]);
-        }
-
-        return lanes;
-    }
-
-    if (instruction.op === VM_OP.LOAD_ATTR) {
-        // Lanes past the component count are the zero an over-wide load is defined to read. The
-        // ones inside it are whatever the record holds, which is not knowable here.
-        for (let lane = instruction.words[3]; lane < count; lane++) {
-            lanes[lane] = 0;
-        }
-
-        return lanes;
-    }
-
-    if (!instruction.semantics.foldable) {
-        return lanes;
-    }
-
-    for (let lane = 0; lane < count; lane++) {
-        /** @type {Array<number|undefined>} */
-        const inputs = [];
-        let complete = true;
-
-        for (const read of instruction.reads) {
-            const source_lane = vm_source_lane(
-                instruction.op,
-                lane,
-                instruction.meta.scalar_operands.includes(read.operand),
-                instruction.words[3]
-            );
-            const slot = read.base + source_lane;
-
-            if (slot >= known.length || !known[slot]) {
-                complete = false;
-                continue;
-            }
-
-            inputs[read.operand] = value[slot];
-        }
-
-        if (complete) {
-            lanes[lane] = finite(evaluate(instruction.op, inputs[0], inputs[1], inputs[2]));
-        } else if (options.fold_multiply_by_zero) {
-            lanes[lane] = absorbed_by_zero(instruction.op, inputs);
-        }
-    }
-
-    return lanes;
-}
-
-/**
- * Zero as an absorbing element: a known zero on either side of a multiply gives zero, whatever the
- * other operand turns out to be.
- *
- * This is the one thing here that is not true of every value a register can hold — `±Inf * 0` and
- * `NaN * 0` are `NaN`, and a negative operand gives `-0` — and it is what the module comment above
- * argues the trade for. A known `-0` absorbs as readily as a known `+0`: once the sign of the result
- * is being given up, it is being given up either way.
- *
- * @param {number} op
- * @param {Array<number|undefined>} inputs by operand slot, `undefined` where the value is unknown
- * @returns {number|null}
- */
-function absorbed_by_zero(op, inputs) {
-    if (op !== VM_OP.MUL && op !== VM_OP.SCALE) {
-        return null;
-    }
-
-    return inputs[0] === 0 || inputs[1] === 0 ? 0 : null;
-}
-
-/**
- * One lane of an operation, in the arithmetic the reference executes it in: `f32` operands, an
- * `f64` computation, and the result rounded back to `f32` — which for a single correctly-rounded
- * operation is the same number an `f32` machine produces.
- *
- * @param {number} op
- * @param {number} a
- * @param {number} b
- * @param {number} c
- * @returns {number}
- */
-function evaluate(op, a, b, c) {
-    switch (op) {
-        case VM_OP.MOV: return a;
-        case VM_OP.SWIZZLE: return a;
-        case VM_OP.ADD: return Math.fround(a + b);
-        case VM_OP.SUB: return Math.fround(a - b);
-        case VM_OP.MUL: return Math.fround(a * b);
-        case VM_OP.DIV: return Math.fround(a / b);
-        case VM_OP.SCALE: return Math.fround(a * b);
-        // `Math.min(-0, 0)` is `-0` and WGSL's `min`, spelled `select(e1, e2, e2 < e1)`, is `0` —
-        // the one place these two executors are allowed to disagree bit for bit. Refusing the fold
-        // wherever a zero is involved closes it without pretending the rest of `min` is unreliable.
-        case VM_OP.MIN: return a === 0 || b === 0 ? NaN : Math.min(a, b);
-        case VM_OP.MAX: return a === 0 || b === 0 ? NaN : Math.max(a, b);
-        case VM_OP.CLAMP: return a === 0 || b === 0 || c === 0 ? NaN : Math.min(Math.max(a, b), c);
-        case VM_OP.NEG: return -a;
-        case VM_OP.ABS: return Math.abs(a);
-        case VM_OP.FLOOR: return Math.floor(a);
-        case VM_OP.FRACT: return Math.fround(a - Math.floor(a));
-        case VM_OP.SQRT: return Math.fround(Math.sqrt(a));
-        case VM_OP.STEP: return b < a ? 0 : 1;
-        case VM_OP.CMP_LT: return a < b ? 1 : 0;
-        case VM_OP.CMP_LE: return a <= b ? 1 : 0;
-        case VM_OP.CMP_GT: return a > b ? 1 : 0;
-        case VM_OP.CMP_GE: return a >= b ? 1 : 0;
-        case VM_OP.CMP_EQ: return a === b ? 1 : 0;
-        case VM_OP.SELECT: return c > 0.5 ? b : a;
-        default: return NaN;
-    }
-}
-
-/**
- * Only finite values are tracked. Dropping `NaN` and `±Inf` here is what keeps every rewrite below
- * from having to restate its own edge cases.
- *
- * @param {number} x
- * @returns {number|null}
- */
-function finite(x) {
-    return Number.isFinite(x) ? Math.fround(x) : null;
-}
-
-/**
- * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
- * @param {Array<number|null>} lanes
- * @param {Uint8Array} known
- * @param {Float32Array} value
- */
-function publish(instruction, lanes, known, value) {
-    if (instruction.write === null) {
-        return;
-    }
-
-    for (let lane = 0; lane < lanes.length; lane++) {
-        const slot = instruction.write.base + lane;
-
-        if (slot >= known.length) {
-            continue;
-        }
-
-        known[slot] = lanes[lane] === null ? 0 : 1;
-        value[slot] = lanes[lane] ?? 0;
-    }
-}
-
-/**
- * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
- * @param {Array<number|null>} lanes
- * @param {Uint8Array} known
- * @param {Float32Array} value
- * @param {object} context
- * @param {number} max_select_moves
- * @returns {number[][]|null} what to emit instead, or `null` to keep the instruction
- */
-function rewrite(instruction, lanes, known, value, options) {
-    if (instruction.semantics.side_effects) {
-        return null;
-    }
-
-    const materialised = materialise(instruction, lanes, options);
-
-    if (materialised !== null) {
-        return materialised;
-    }
-
-    if (instruction.op === VM_OP.SELECT) {
-        const collapsed = collapse_select(instruction, known, value, options.max_select_moves);
-
-        if (collapsed !== null) {
-            return collapsed;
-        }
-    }
-
-    const identity = collapse_identity(instruction, known, value);
-
-    if (identity !== null) {
-        return identity;
-    }
-
-    return options.peel_constant_lanes ? peel_constant_tail(instruction, lanes, options) : null;
-}
-
-/**
- * Split an instruction whose trailing lanes turn out to be constants into the narrower instruction
- * that computes the rest, plus one load for the tail.
- *
- * One instruction becomes two, which only pays for itself through what it frees: the narrowed
- * instruction stops reading the upper lanes of its sources, and those are usually a broadcast, a
- * mask, and the arithmetic that built them. A distribution's mask lane is exactly this shape.
- *
- * Only for opcodes that compute their result from registers. `LOAD_ATTR`'s lanes past its component
- * count are already the zero it reads for free, and peeling those would be a load in place of
- * nothing at all.
- *
- * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
- * @param {Array<number|null>} lanes
- * @param {object} options
- * @returns {number[][]|null}
- */
-function peel_constant_tail(instruction, lanes, options) {
-    if (
-        options.intern_constant === null
-        || instruction.write === null
-        || instruction.reads.length === 0
-        || !instruction.semantics.narrowable
-        || instruction.write.span !== instruction.operation_width
-    ) {
-        return null;
-    }
-
-    // The longest run of known lanes at the top, leaving at least one below it for the instruction
-    // to still be worth issuing — one that is constant all the way down was materialised above.
-    let first = lanes.length;
-
-    while (first > 0 && lanes[first - 1] !== null) {
-        first--;
-    }
-
-    if (first === lanes.length || first < Math.max(1, instruction.meta.min_width)) {
-        return null;
-    }
-
-    const narrowed = instruction.words.slice();
-
-    narrowed[0] = vm_encode_word0(instruction.op, first);
-
-    const load = [
-        vm_encode_word0(VM_OP.LOAD_CONST, lanes.length - first),
-        instruction.write.base + first,
-        options.intern_constant(lanes.slice(first)),
-        0,
-        0,
-    ];
-
-    return particle_instruction_is_well_formed(narrowed) && particle_instruction_is_well_formed(load)
-        ? [narrowed, load]
-        : null;
-}
-
-/**
- * Replace an instruction whose every output lane is a known number with the load of that number.
- *
- * Neutral in instruction count on its own; the win is that it cuts the instruction loose from
- * everything that fed it, which is usually then dead.
- *
- * @returns {number[][]|null}
- */
-function materialise(instruction, lanes, options) {
-    if (
-        instruction.op === VM_OP.LOAD_CONST
-        || options.intern_constant === null
-        || lanes.length === 0
-        || lanes.some(lane => lane === null)
-    ) {
-        return null;
-    }
-
-    // A reduction writes one lane whatever it reads, so the load that replaces it is one lane wide.
-    const width = lanes.length;
-    const words = [
-        vm_encode_word0(VM_OP.LOAD_CONST, width),
-        instruction.write.base,
-        options.intern_constant(lanes),
-        0,
-        0,
-    ];
-
-    return particle_instruction_is_well_formed(words) ? [words] : null;
-}
-
-/**
- * A `SELECT` whose condition is known lane by lane is not a choice, it is copying — and most of
- * those copies are a register into itself.
- *
- * The replacement is capped at `max_select_moves` instructions: what pays for the split is the
- * constant load feeding the condition going dead, so a mask that alternates lane by lane and needs
- * a `MOV` for each run is not worth taking apart.
- *
- * The runs are safe to emit in sequence for the same reason the `SELECT` was legal: an operand
- * either names the destination's slots exactly — in which case its lanes are copies of themselves
- * and are dropped — or names none of them, so no `MOV` here can clobber a later one's source.
- *
- * @returns {number[][]|null}
- */
-function collapse_select(instruction, known, value, max_select_moves) {
-    const condition = instruction.reads[2];
-    const width = instruction.operation_width;
-    /** @type {number[]} the source operand's base, per lane */
-    const chosen = new Array(width);
-
-    for (let lane = 0; lane < width; lane++) {
-        const slot = condition.base + lane;
-
-        if (slot >= known.length || !known[slot]) {
-            return null;
-        }
-
-        chosen[lane] = value[slot] > 0.5 ? instruction.reads[1].base : instruction.reads[0].base;
-    }
-
-    /** @type {number[][]} */
-    const moves = [];
-
-    for (let lane = 0; lane < width;) {
-        let end = lane + 1;
-
-        while (end < width && chosen[end] === chosen[lane]) {
-            end++;
-        }
-
-        // A run taken from the destination itself is a copy of a register into itself.
-        if (chosen[lane] !== instruction.write.base) {
-            const words = [
-                vm_encode_word0(VM_OP.MOV, end - lane),
-                instruction.write.base + lane,
-                chosen[lane] + lane,
-                0,
-                0,
-            ];
-
-            if (!particle_instruction_is_well_formed(words)) {
-                return null;
-            }
-
-            moves.push(words);
-        }
-
-        lane = end;
-    }
-
-    return moves.length <= max_select_moves ? moves : null;
-}
-
-/**
- * The arithmetic identities that hold for every value a register can hold, not merely the ordinary
- * ones.
- *
- * `x * 1`, `x / 1` and `x - (+0)` are `x` bit for bit — including `-0`, `±Inf` and `NaN` — so they
- * are copies. `x + 0` is not: `-0 + 0` is `+0`. `x * 0` is not: it is `-0` for negative `x` and
- * `NaN` for a non-finite one. The line is drawn at what is exactly true, because the record a
- * program leaves is compared to the bit.
- *
- * `MAD` with a multiplier of one becomes an `ADD` for the same reason: `a * 1` is exact, so a
- * contracted `fma(a, 1, c)` and a plain `a + c` are the same number.
- *
- * @returns {number[][]|null}
- */
-function collapse_identity(instruction, known, value) {
-    const op = instruction.op;
-    const width = instruction.operation_width;
-    const is = (read, expected) => read !== undefined && all_lanes_are(read, width, expected, known, value);
-
-    /** Rebuild as a copy of one source. */
-    const copy_of = (read) => {
-        const words = [vm_encode_word0(VM_OP.MOV, width), instruction.write.base, read.base, 0, 0];
-
-        return particle_instruction_is_well_formed(words) ? [words] : null;
-    };
-
-    switch (op) {
-        case VM_OP.MUL:
-            if (is(instruction.reads[1], 1)) return copy_of(instruction.reads[0]);
-            if (is(instruction.reads[0], 1)) return copy_of(instruction.reads[1]);
-            return null;
-
-        case VM_OP.DIV:
-            return is(instruction.reads[1], 1) ? copy_of(instruction.reads[0]) : null;
-
-        case VM_OP.SCALE: {
-            // The scalar is one slot whatever the width, which `is_scalar_one` reads through the
-            // ISA's own scalar marking rather than assuming.
-            if (is_scalar_one(instruction, known, value)) {
-                return copy_of(instruction.reads[0]);
-            }
-
-            // The other way round: scaling a vector of ones is that scalar in every lane, which is a
-            // broadcast — and `SWIZZLE` is the opcode the VM has for one. Exact, and it is what the
-            // mask left behind by a peeled instruction turns into on its way out.
-            if (is(instruction.reads[0], 1)) {
-                const words = [
-                    vm_encode_word0(VM_OP.SWIZZLE, instruction.width),
-                    instruction.write.base,
-                    instruction.reads[1].base,
-                    pack_swizzle(0, 0, 0, 0),
-                    0,
-                ];
-
-                return particle_instruction_is_well_formed(words) ? [words] : null;
-            }
-
-            return null;
-        }
-
-        case VM_OP.SUB:
-            // Positive zero only, which is what `Object.is` in `all_lanes_are` gets us: `x - (-0)`
-            // is `x + 0`, and that turns a `-0` into a `+0`.
-            return is(instruction.reads[1], 0) ? copy_of(instruction.reads[0]) : null;
-
-        case VM_OP.MAD: {
-            const add = (a, b) => {
-                const words = [vm_encode_word0(VM_OP.ADD, width), instruction.write.base, a.base, b.base, 0];
-
-                return particle_instruction_is_well_formed(words) ? [words] : null;
-            };
-
-            if (is(instruction.reads[1], 1)) return add(instruction.reads[0], instruction.reads[2]);
-            if (is(instruction.reads[0], 1)) return add(instruction.reads[1], instruction.reads[2]);
-            return null;
-        }
-
-        default:
-            return null;
-    }
-}
-
-/**
- * @param {import("./particle_program_analysis.js").ParticleOperandRun} read
- * @param {number} width
- * @param {number} expected
- * @param {Uint8Array} known
- * @param {Float32Array} value
- * @returns {boolean}
- */
-function all_lanes_are(read, width, expected, known, value) {
-    for (let lane = 0; lane < width; lane++) {
-        const slot = read.base + lane;
-
-        // `Object.is`, so a `-0` never passes for the `+0` the identity actually needs.
-        if (slot >= known.length || !known[slot] || !Object.is(value[slot], expected)) {
-            return false;
-        }
-    }
-
-    return true;
-}
-
-/** @returns {boolean} whether `SCALE`'s scalar source is known to be exactly one */
-function is_scalar_one(instruction, known, value) {
-    const scalar = instruction.reads[1];
-    const slot = scalar.base;
-
-    return slot < known.length && known[slot] === 1 && Object.is(value[slot], 1);
-}
+import {
+    VM_KIND,
+    VM_OP,
+    swizzle_selector,
+    vm_dest_width,
+    vm_f32_value,
+    vm_pack_instruction,
+    vm_register,
+    vm_with_width,
+} from "../isa/ParticleVMISA.js";
+import {
+    decode_particle_instructions,
+    particle_instruction_is_well_formed,
+    particle_read_slots,
+} from "./particle_program_analysis.js";
+
+/** @type {string} */
+export const PARTICLE_PASS_FOLD_CONSTANTS = "fold_constants";
+
+/**
+ * The opcodes whose result a known zero operand decides on its own — the ones
+ * `fold_multiply_by_zero` rewrites, and therefore the ones whose results the equivalence harness's
+ * reach mode has to follow. Stated once so the two cannot drift.
+ * @type {Set<number>}
+ */
+export const PARTICLE_ZERO_ABSORBING_OPS = new Set([VM_OP.MUL]);
+
+/**
+ * Track what each register lane is known to hold, and rewrite the instructions that turn out not to
+ * need computing.
+ *
+ * Two things come out of this. Instructions whose every output lane is a known number become a
+ * `LOAD_CONST`, which usually makes everything feeding them dead. And instructions that are a known
+ * *shape* rather than a known value collapse: a `SELECT` whose condition is a compile-time mask is
+ * per-lane copying, and a multiply by one is a copy.
+ *
+ * The graph compiler emits both shapes constantly. It has no notion of a compile-time-known lane
+ * mask, so `graph/particle_graph_distributions.js` assembling `(cos, sin, 0)` out of a `select` on
+ * the literal `[0, 1, 0]` lowers to a broadcast, a second broadcast, a constant load and a `SELECT`
+ * — four instructions for what is one `MOV`, and this pass is what notices.
+ *
+ * ## What is not folded, and why
+ *
+ * A lane is tracked only while its value is FINITE. `NaN` and `±Inf` are dropped from the analysis
+ * rather than propagated, which removes at a stroke every rewrite that is right for ordinary numbers
+ * and wrong at the edges — `min(NaN, x)` is the reference's `NaN` and the GPU's anything, and a
+ * baked `NaN` constant is at the mercy of a driver that assumes there are none.
+ *
+ * Only operations both executors are obliged to round identically are evaluated here — see
+ * `foldable` in {@link ./particle_vm_semantics.js}. Folding `sin` would quietly hand the GPU the
+ * CPU's answer, so it happens only when a caller asks for it by name: see `fold_inexact` below.
+ *
+ * Every identity here is exact — `x * 1`, `x / 1` and `x - (+0)` are `x` for every value a register
+ * can hold — with one deliberate exception, below.
+ *
+ * ## Multiplying by zero: the one place this is not exact
+ *
+ * `x * 0` is `+0` for finite non-negative `x`, `-0` for finite negative `x`, and `NaN` for `±Inf`
+ * and `NaN`. Folding it to `+0` is therefore a fast-math relaxation rather than a rewrite, and it is
+ * on by default (`fold_multiply_by_zero`) because a particle effect essentially never needs the
+ * distinction and the shape it unlocks is everywhere.
+ *
+ * That shape is the lane mask. `graph/particle_graph_distributions.js` clears the lanes a disk has
+ * nothing to say about by multiplying through `[1, 1, 0]`, and the lowering has no way to know the
+ * result of that lane is a constant. With the fold it becomes one, the tail of the instruction is
+ * peeled off as a constant load, and the multiply, the mask's own load and the broadcast feeding it
+ * all go dead behind it.
+ *
+ * What it costs is not bounded by a shape — a substituted zero is read by whatever comes next, and
+ * a comparison or a division downstream can turn the difference into any number. The equivalence
+ * harness bounds its REACH instead: see `reached_by_zero_fold` in
+ * {@link ./particle_program_equivalence.js}. Switch the fold off
+ * (`{ fold_multiply_by_zero: false }`) and every pass in the
+ * optimizer is bit-exact again.
+ *
+ * ## `fold_inexact`: the transcendentals, off by default
+ *
+ * `{ fold_inexact: true }` also evaluates the operations whose two
+ * executors are allowed to round apart — `foldable_inexact` in
+ * {@link ./particle_vm_semantics.js}: the trigonometry and its inverses, `exp`, `log`, `pow`,
+ * `smoothstep`, `mix`, `mad` and `rsqrt`. That is HLSL's fast-math trade and it is worth naming
+ * rather than assuming: what is bought is a literal instead of a transcendental, and what is sold
+ * is the GPU's own last bits — `Math.sin` and a GPU's `sin` agree to about a part in 10^7, and
+ * with the fold on it is the CPU's answer that ships.
+ *
+ * It is off because that is not a trade the compiler gets to make on an author's behalf, and
+ * because there is nothing here to buy with it. The fold only fires where an argument is already a
+ * compile-time constant, and over all eighteen built-in groups — `curl4`, the simplex noises, the
+ * quaternion and sampling groups, 6,523 instructions optimized — turning it on changes not one
+ * instruction: every `sin` in the tree takes its argument from a `random`, an attribute or a
+ * builtin. On the fuzzer's programs, where the opcode mix is uniform and operands are often
+ * literals, it takes another 8.8% off what the default pipeline leaves (5,443 to 4,963 over 200
+ * programs). So the option is real and tested and worth having for a frontend that folds harder
+ * than this one — and on today's effects it is a switch with nothing behind it.
+ *
+ * What it does NOT do is turn a hardware `NaN` into a number. Only finite values are tracked, so
+ * `log` of zero, `asin` of two and `rsqrt` of a negative are all left alone by the same rule that
+ * leaves every other edge alone; the two operations whose reference spelling is defined where the
+ * hardware's is not — `pow` of a non-positive base and `smoothstep` with equal edges, both of which
+ * WGSL computes through a division or a `log2` that the reference does not — are refused in
+ * {@link evaluate} rather than relaxed. The relaxation is a rounding, and stays one.
+ *
+ * ## Operands
+ *
+ * A literal operand is a known value by construction, and a register operand's lanes are looked up
+ * through its swizzle — so a broadcast of a known register is known in every lane, and a `SELECT`
+ * between a register and a literal collapses to a `MOV` from whichever the mask picks, with the
+ * operand's kind and swizzle carried along.
+ *
+ * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
+ */
+export function pass_fold_constants(instructions, context) {
+    const decoded = decode_particle_instructions(instructions);
+    const slots = context.register_slots;
+
+    /** Whether a slot's value is known — and finite, which is the only kind that is tracked. */
+    const known = new Uint8Array(slots);
+    /** f32, so a tracked value is exactly the one the register would hold. */
+    const value = new Float32Array(slots);
+
+    const options = {
+        max_select_moves: 2,
+        fold_multiply_by_zero: true,
+        fold_inexact: false,
+        peel_constant_lanes: true,
+        ...context,
+    };
+
+    /** @type {number[][]} */
+    const out = [];
+
+    let changed = false;
+
+    for (const instruction of decoded) {
+        const lanes = evaluate_lanes(instruction, known, value, options);
+        const replacement = rewrite(instruction, lanes, known, value, options);
+
+        if (replacement === null) {
+            out.push(instruction.words);
+        } else {
+            out.push(...replacement);
+            changed = true;
+        }
+
+        publish(instruction, lanes, known, value);
+    }
+
+    return changed ? out : null;
+}
+
+/**
+ * What each lane of the destination will hold, as far as it can be worked out here.
+ *
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+ * @param {Uint8Array} known
+ * @param {Float32Array} value
+ * @param {object} options
+ * @returns {Array<number|null>} one entry per destination lane; `null` where the value is not known
+ */
+function evaluate_lanes(instruction, known, value, options) {
+    if (instruction.write === null) {
+        return [];
+    }
+
+    const count = vm_dest_width(instruction.op, instruction.width);
+    /** @type {Array<number|null>} */
+    const lanes = new Array(count).fill(null);
+
+    if (instruction.op === VM_OP.LOAD_CONST) {
+        for (let lane = 0; lane < count; lane++) {
+            lanes[lane] = finite(options.constants[instruction.words[1] + lane]);
+        }
+
+        return lanes;
+    }
+
+    if (instruction.op === VM_OP.LOAD_ATTR) {
+        // Lanes past the component count are the zero an over-wide load is defined to read. The
+        // ones inside it are whatever the record holds, which is not knowable here.
+        for (let lane = instruction.words[2]; lane < count; lane++) {
+            lanes[lane] = 0;
+        }
+
+        return lanes;
+    }
+
+    // Exact always; the ones the two executors may round apart only when the caller has asked for
+    // that trade by name.
+    const foldable = instruction.semantics.foldable
+        || (options.fold_inexact && instruction.semantics.foldable_inexact);
+
+    if (!foldable) {
+        return lanes;
+    }
+
+    for (let lane = 0; lane < count; lane++) {
+        /** @type {Array<number|undefined>} */
+        const inputs = [];
+        let complete = true;
+
+        for (const source of instruction.sources) {
+            const held = source_lane_value(source, lane, known, value);
+
+            if (held === null) {
+                complete = false;
+                continue;
+            }
+
+            inputs[source.operand] = held;
+        }
+
+        if (complete) {
+            lanes[lane] = finite(evaluate_particle_operation(instruction.op, inputs[0], inputs[1], inputs[2]));
+        } else if (options.fold_multiply_by_zero) {
+            lanes[lane] = absorbed_by_zero(instruction.op, inputs);
+        }
+    }
+
+    return lanes;
+}
+
+/**
+ * Zero as an absorbing element: a known zero on either side of a multiply gives zero, whatever the
+ * other operand turns out to be.
+ *
+ * This is the one thing here that is not true of every value a register can hold — `±Inf * 0` and
+ * `NaN * 0` are `NaN`, and a negative operand gives `-0` — and it is what the module comment above
+ * argues the trade for. A known `-0` absorbs as readily as a known `+0`: once the sign of the result
+ * is being given up, it is being given up either way.
+ *
+ * @param {number} op
+ * @param {Array<number|undefined>} inputs by operand slot, `undefined` where the value is unknown
+ * @returns {number|null}
+ */
+function absorbed_by_zero(op, inputs) {
+    if (!PARTICLE_ZERO_ABSORBING_OPS.has(op)) {
+        return null;
+    }
+
+    return inputs[0] === 0 || inputs[1] === 0 ? 0 : null;
+}
+
+/**
+ * One lane of an operation, in the arithmetic the reference executes it in: `f32` operands, an
+ * `f64` computation, and the result rounded back to `f32` — which for a single correctly-rounded
+ * operation is the same number an `f32` machine produces.
+ *
+ * @param {number} op
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @returns {number}
+ */
+export function evaluate_particle_operation(op, a, b, c) {
+    switch (op) {
+        case VM_OP.MOV: return a;
+        case VM_OP.ADD: return Math.fround(a + b);
+        case VM_OP.SUB: return Math.fround(a - b);
+        case VM_OP.MUL: return Math.fround(a * b);
+        case VM_OP.DIV: return Math.fround(a / b);
+        // `Math.min(-0, 0)` is `-0` and WGSL's `min`, spelled `select(e1, e2, e2 < e1)`, is `0` —
+        // the one place these two executors are allowed to disagree bit for bit. Refusing the fold
+        // wherever a zero is involved closes it without pretending the rest of `min` is unreliable.
+        case VM_OP.MIN: return a === 0 || b === 0 ? NaN : Math.min(a, b);
+        case VM_OP.MAX: return a === 0 || b === 0 ? NaN : Math.max(a, b);
+        case VM_OP.CLAMP: return a === 0 || b === 0 || c === 0 ? NaN : Math.min(Math.max(a, b), c);
+        case VM_OP.NEG: return -a;
+        case VM_OP.ABS: return Math.abs(a);
+        case VM_OP.FLOOR: return Math.floor(a);
+        case VM_OP.FRACT: return Math.fround(a - Math.floor(a));
+        case VM_OP.SQRT: return Math.fround(Math.sqrt(a));
+        case VM_OP.STEP: return b < a ? 0 : 1;
+        case VM_OP.CMP_LT: return a < b ? 1 : 0;
+        case VM_OP.CMP_LE: return a <= b ? 1 : 0;
+        case VM_OP.CMP_GT: return a > b ? 1 : 0;
+        case VM_OP.CMP_GE: return a >= b ? 1 : 0;
+        case VM_OP.CMP_EQ: return a === b ? 1 : 0;
+        case VM_OP.SELECT: return c > 0.5 ? b : a;
+
+        // --- reached only under `fold_inexact` ---
+        //
+        // Each of these is spelled exactly as `../vm/ParticleVMReference.js` spells it, so the fold
+        // and the reference agree to the bit and it is the GPU that is allowed to differ. That is
+        // the whole of what the option trades; anything an executor could disagree about by more
+        // than a rounding is refused below rather than folded.
+        case VM_OP.MAD: return Math.fround(a * b + c);
+        case VM_OP.MIX: return Math.fround(a + (b - a) * c);
+        case VM_OP.SIN: return Math.fround(Math.sin(a));
+        case VM_OP.COS: return Math.fround(Math.cos(a));
+        case VM_OP.TAN: return Math.fround(Math.tan(a));
+        case VM_OP.ASIN: return Math.fround(Math.asin(a));
+        case VM_OP.ACOS: return Math.fround(Math.acos(a));
+        case VM_OP.EXP: return Math.fround(Math.exp(a));
+        case VM_OP.LOG: return Math.fround(Math.log(a));
+        // `1 / sqrt(a)` for `a <= 0` is an infinity or a `NaN`, and `finite` drops both — the same
+        // rule that keeps `SQRT` next door out of trouble, so there is nothing to say here.
+        case VM_OP.RSQRT: return Math.fround(1 / Math.sqrt(a));
+        // WGSL's `pow` is `exp2(e2 * log2(e1))`, which is a `NaN` for every base at or below zero
+        // — including `pow(0, 0)`, where JS says 1. A fold that turned the hardware's `NaN` into a
+        // number would not be a rounding, so the non-positive bases are not folded at all.
+        case VM_OP.POW: return a > 0 ? Math.fround(Math.pow(a, b)) : NaN;
+        // Equal edges divide by zero on the GPU; the reference answers 0 or 1 instead. Same
+        // argument as `pow`: refuse the case rather than ship the reference's answer for it.
+        case VM_OP.SMOOTHSTEP: {
+            if (a === b) {
+                return NaN;
+            }
+
+            const t = Math.min(Math.max((c - a) / (b - a), 0), 1);
+
+            return Math.fround(t * t * (3 - 2 * t));
+        }
+        // `atan2(0, 0)` is 0 in JS and left to the implementation in WGSL. Every other pair is an
+        // angle both agree on to a rounding.
+        case VM_OP.ATAN2: return a === 0 && b === 0 ? NaN : Math.fround(Math.atan2(a, b));
+
+        default: return NaN;
+    }
+}
+
+/**
+ * Only finite values are tracked. Dropping `NaN` and `±Inf` here is what keeps every rewrite below
+ * from having to restate its own edge cases.
+ *
+ * @param {number} x
+ * @returns {number|null}
+ */
+function finite(x) {
+    return Number.isFinite(x) ? Math.fround(x) : null;
+}
+
+/**
+ * What one lane of a source is known to hold: a literal is its own value, a register operand is
+ * whatever the analysis has tracked into the slot its swizzle names for that lane. `null` where the
+ * value is not known — or not finite, since only finite values are ever tracked.
+ *
+ * @param {import("./particle_program_analysis.js").ParticleOperandRun} source
+ * @param {number} lane output lane
+ * @param {Uint8Array} known
+ * @param {Float32Array} value
+ * @returns {number|null}
+ */
+function source_lane_value(source, lane, known, value) {
+    if (source.kind === VM_KIND.IMM) {
+        return finite(vm_f32_value(source.word));
+    }
+
+    // A scalar source feeds every lane from its first; everything else reads straight across.
+    const slot = source.base + swizzle_selector(source.pattern, source.lanes === 1 ? 0 : lane);
+
+    return slot < known.length && known[slot] ? value[slot] : null;
+}
+
+/**
+ * A `MOV` of `width` lanes into `dst` from a source operand, from `first` lanes into it, keeping the
+ * source's kind: a copy of a register is that register read through the selectors those lanes use,
+ * a copy of a literal is that literal.
+ *
+ * @param {number} width
+ * @param {number} dst
+ * @param {import("./particle_program_analysis.js").ParticleOperandRun} source
+ * @param {number} [first]
+ * @returns {number[]}
+ */
+function move_from(width, dst, source, first = 0) {
+    if (source.kind === VM_KIND.IMM) {
+        return vm_pack_instruction(VM_OP.MOV, width, dst, [VM_KIND.IMM, VM_KIND.NONE, VM_KIND.NONE], [source.word, 0, 0]);
+    }
+
+    let pattern = 0;
+
+    for (let lane = 0; lane < 4; lane++) {
+        pattern |= swizzle_selector(source.pattern, first + lane) << (2 * lane);
+    }
+
+    return vm_pack_instruction(
+        VM_OP.MOV, width, dst,
+        [VM_KIND.REG, VM_KIND.NONE, VM_KIND.NONE],
+        [vm_register(source.base, pattern), 0, 0]
+    );
+}
+
+/**
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+ * @param {Array<number|null>} lanes
+ * @param {Uint8Array} known
+ * @param {Float32Array} value
+ */
+function publish(instruction, lanes, known, value) {
+    if (instruction.write === null) {
+        return;
+    }
+
+    for (let lane = 0; lane < lanes.length; lane++) {
+        const slot = instruction.write.base + lane;
+
+        if (slot >= known.length) {
+            continue;
+        }
+
+        known[slot] = lanes[lane] === null ? 0 : 1;
+        value[slot] = lanes[lane] ?? 0;
+    }
+}
+
+/**
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+ * @param {Array<number|null>} lanes
+ * @param {Uint8Array} known
+ * @param {Float32Array} value
+ * @param {object} options
+ * @returns {number[][]|null} what to emit instead, or `null` to keep the instruction
+ */
+function rewrite(instruction, lanes, known, value, options) {
+    if (instruction.semantics.side_effects) {
+        return null;
+    }
+
+    const materialised = materialise(instruction, lanes, options);
+
+    if (materialised !== null) {
+        return materialised;
+    }
+
+    if (instruction.op === VM_OP.SELECT) {
+        const collapsed = collapse_select(instruction, known, value, options.max_select_moves);
+
+        if (collapsed !== null) {
+            return collapsed;
+        }
+    }
+
+    const identity = collapse_identity(instruction, known, value);
+
+    if (identity !== null) {
+        return identity;
+    }
+
+    return options.peel_constant_lanes ? peel_constant_tail(instruction, lanes, options) : null;
+}
+
+/**
+ * Split an instruction whose trailing lanes turn out to be constants into the narrower instruction
+ * that computes the rest, plus one load for the tail.
+ *
+ * One instruction becomes two, which only pays for itself through what it frees: the narrowed
+ * instruction stops reading the upper lanes of its sources, and those are usually a broadcast, a
+ * mask, and the arithmetic that built them. A distribution's mask lane is exactly this shape.
+ *
+ * Only for opcodes that compute their result from registers. `LOAD_ATTR`'s lanes past its component
+ * count are already the zero it reads for free, and peeling those would be a load in place of
+ * nothing at all.
+ *
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+ * @param {Array<number|null>} lanes
+ * @param {object} options
+ * @returns {number[][]|null}
+ */
+function peel_constant_tail(instruction, lanes, options) {
+    if (
+        options.intern_constant === null
+        || instruction.write === null
+        || instruction.sources.length === 0
+        || !instruction.semantics.narrowable
+        || instruction.write.span !== instruction.operation_width
+    ) {
+        return null;
+    }
+
+    // The longest run of known lanes at the top, leaving at least one below it for the instruction
+    // to still be worth issuing — one that is constant all the way down was materialised above.
+    let first = lanes.length;
+
+    while (first > 0 && lanes[first - 1] !== null) {
+        first--;
+    }
+
+    if (first === lanes.length || first < Math.max(1, instruction.meta.min_width)) {
+        return null;
+    }
+
+    const narrowed = instruction.words.slice();
+
+    narrowed[0] = vm_with_width(narrowed[0], first);
+
+    const load = vm_pack_instruction(
+        VM_OP.LOAD_CONST, lanes.length - first, instruction.write.base + first,
+        [VM_KIND.NONE, VM_KIND.NONE, VM_KIND.NONE],
+        [options.intern_constant(lanes.slice(first)), 0, 0]
+    );
+
+    return particle_instruction_is_well_formed(narrowed) && particle_instruction_is_well_formed(load)
+        ? [narrowed, load]
+        : null;
+}
+
+/**
+ * Replace an instruction whose every output lane is a known number with the load of that number.
+ *
+ * Neutral in instruction count on its own; the win is that it cuts the instruction loose from
+ * everything that fed it, which is usually then dead.
+ *
+ * @returns {number[][]|null}
+ */
+function materialise(instruction, lanes, options) {
+    if (
+        instruction.op === VM_OP.LOAD_CONST
+        || options.intern_constant === null
+        || lanes.length === 0
+        || lanes.some(lane => lane === null)
+    ) {
+        return null;
+    }
+
+    // A reduction writes one lane whatever it reads, so the load that replaces it is one lane wide.
+    const words = vm_pack_instruction(
+        VM_OP.LOAD_CONST, lanes.length, instruction.write.base,
+        [VM_KIND.NONE, VM_KIND.NONE, VM_KIND.NONE],
+        [options.intern_constant(lanes), 0, 0]
+    );
+
+    return particle_instruction_is_well_formed(words) ? [words] : null;
+}
+
+/**
+ * A `SELECT` whose condition is known lane by lane is not a choice, it is copying — and most of
+ * those copies are a register into itself.
+ *
+ * The replacement is capped at `max_select_moves` instructions: what pays for the split is the
+ * constant load feeding the condition going dead, so a mask that alternates lane by lane and needs
+ * a `MOV` for each run is not worth taking apart.
+ *
+ * The `SELECT` read every source before it wrote; the `MOV`s run one after another. So a copy is
+ * refused where a later one would read a slot an earlier one has already written — the case the
+ * split cannot express — and a run taken from the destination itself is a copy of a register into
+ * itself and is left out.
+ *
+ * @returns {number[][]|null}
+ */
+function collapse_select(instruction, known, value, max_select_moves) {
+    const [when_false, when_true, condition] = instruction.sources;
+    const width = instruction.operation_width;
+    /** @type {import("./particle_program_analysis.js").ParticleOperandRun[]} the source picked, per lane */
+    const chosen = new Array(width);
+
+    for (let lane = 0; lane < width; lane++) {
+        const mask = source_lane_value(condition, lane, known, value);
+
+        if (mask === null) {
+            return null;
+        }
+
+        chosen[lane] = mask > 0.5 ? when_true : when_false;
+    }
+
+    /** @type {number[][]} */
+    const moves = [];
+    /** @type {Set<number>} slots the copies emitted so far have written */
+    const written = new Set();
+
+    for (let lane = 0; lane < width;) {
+        let end = lane + 1;
+
+        while (end < width && chosen[end] === chosen[lane]) {
+            end++;
+        }
+
+        const picked = chosen[lane];
+        const is_itself = picked.kind === VM_KIND.REG
+            && particle_read_slots(picked, width).slice(lane, end).every((slot, i) => slot === instruction.write.base + lane + i);
+
+        if (!is_itself) {
+            const words = move_from(end - lane, instruction.write.base + lane, picked, lane);
+
+            if (!particle_instruction_is_well_formed(words)) {
+                return null;
+            }
+
+            if (picked.kind === VM_KIND.REG
+                && particle_read_slots(picked, width).slice(lane, end).some(slot => written.has(slot))) {
+                return null;
+            }
+
+            moves.push(words);
+        }
+
+        for (let slot = lane; slot < end; slot++) {
+            written.add(instruction.write.base + slot);
+        }
+
+        lane = end;
+    }
+
+    return moves.length <= max_select_moves ? moves : null;
+}
+
+/**
+ * The arithmetic identities that hold for every value a register can hold, not merely the ordinary
+ * ones.
+ *
+ * `x * 1`, `x / 1` and `x - (+0)` are `x` bit for bit — including `-0`, `±Inf` and `NaN` — so they
+ * are copies. `x + 0` is not: `-0 + 0` is `+0`. `x * 0` is not: it is `-0` for negative `x` and
+ * `NaN` for a non-finite one. The line is drawn at what is exactly true, because the record a
+ * program leaves is compared to the bit.
+ *
+ * `MAD` with a multiplier of one becomes an `ADD` for the same reason: `a * 1` is exact, so a
+ * contracted `fma(a, 1, c)` and a plain `a + c` are the same number.
+ *
+ * @returns {number[][]|null}
+ */
+function collapse_identity(instruction, known, value) {
+    const op = instruction.op;
+    const width = instruction.operation_width;
+    const sources = instruction.sources;
+    const is = (source, expected) => source !== undefined && all_lanes_are(source, width, expected, known, value);
+
+    /** Rebuild as a copy of one source, whatever kind it is and however it is swizzled. */
+    const copy_of = (source) => {
+        const words = move_from(width, instruction.write.base, source);
+
+        return particle_instruction_is_well_formed(words) ? [words] : null;
+    };
+
+    switch (op) {
+        case VM_OP.MUL:
+            if (is(sources[1], 1)) return copy_of(sources[0]);
+            if (is(sources[0], 1)) return copy_of(sources[1]);
+            return null;
+
+        case VM_OP.DIV:
+            return is(sources[1], 1) ? copy_of(sources[0]) : null;
+
+        case VM_OP.SUB:
+            // Positive zero only, which is what `Object.is` in `all_lanes_are` gets us: `x - (-0)`
+            // is `x + 0`, and that turns a `-0` into a `+0`.
+            return is(sources[1], 0) ? copy_of(sources[0]) : null;
+
+        case VM_OP.MAD: {
+            const add = (a, b) => {
+                const words = vm_pack_instruction(
+                    VM_OP.ADD, width, instruction.write.base,
+                    [a.kind, b.kind, VM_KIND.NONE],
+                    [a.word, b.word, 0]
+                );
+
+                return particle_instruction_is_well_formed(words) ? [words] : null;
+            };
+
+            if (is(sources[1], 1)) return add(sources[0], sources[2]);
+            if (is(sources[0], 1)) return add(sources[1], sources[2]);
+            return null;
+        }
+
+        default:
+            return null;
+    }
+}
+
+/**
+ * @param {import("./particle_program_analysis.js").ParticleOperandRun} source
+ * @param {number} width
+ * @param {number} expected
+ * @param {Uint8Array} known
+ * @param {Float32Array} value
+ * @returns {boolean}
+ */
+function all_lanes_are(source, width, expected, known, value) {
+    for (let lane = 0; lane < width; lane++) {
+        const held = source_lane_value(source, lane, known, value);
+
+        // `Object.is`, so a `-0` never passes for the `+0` the identity actually needs.
+        if (held === null || !Object.is(held, expected)) {
+            return false;
+        }
+    }
+
+    return true;
+}