@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -0,0 +1,337 @@
+import { PARTICLE_RECORD_WORD_COUNT, PARTICLE_VM_FAST_REGISTER_SLOTS } from "../ParticleConstants.js";
+import { ParticleAssembler } from "../isa/ParticleAssembler.js";
+import {
+    VM_BUILTIN,
+    VM_ISA,
+    VM_MAX_WIDTH,
+    VM_OP,
+    VM_OPERAND,
+    pack_swizzle,
+    vm_immediate,
+    vm_register,
+} from "../isa/ParticleVMISA.js";
+
+/**
+ * Random but well-formed particle programs, for holding the optimizer to
+ * {@link ./particle_program_equivalence.js}'s bit-identity property on programs nobody wrote.
+ *
+ * The generator carves the register file into value runs of random width and draws every operand of
+ * an instruction from one width class, so a source is a whole value: the same shape the node
+ * compiler produces, and the one the passes have opinions about. `../vm/chunk_particle_vm.spec.js`
+ * fuzzes the two executors against each other the same way; the difference here is that nothing is
+ * excluded for being numerically awkward. Division by zero, `sqrt` of a negative and `log` of zero
+ * are all fair game, because both sides of this comparison are the same executor and an optimizer
+ * that turns `NaN` into a number is exactly what wants catching.
+ *
+ * The mix is deliberately biased towards what the optimizer has opinions about: constants that are
+ * 0 and 1, `SELECT`s whose condition is one of them, copies, broadcasts, and results that nothing
+ * ever stores.
+ *
+ * With `tagged`, a source is sometimes a literal rather than a register — the operand kinds of
+ * {@link ../isa/ParticleVMISA.js} — so every pass meets literals in every slot of every opcode, in
+ * programs that also carry the shapes it rewrites. Register sources are sometimes read through a
+ * swizzle in either mode, since a swizzle is part of what a register operand is.
+ */
+
+/** Every opcode a generated program may contain, `HALT` aside — that one is placed by hand. */
+const FUZZ_OPS = [
+    VM_OP.MOV, VM_OP.ADD, VM_OP.SUB, VM_OP.MUL, VM_OP.DIV, VM_OP.MAD, VM_OP.MIN, VM_OP.MAX,
+    VM_OP.MIX, VM_OP.CLAMP, VM_OP.NEG, VM_OP.ABS, VM_OP.FLOOR, VM_OP.FRACT,
+    VM_OP.SQRT, VM_OP.SIN, VM_OP.COS, VM_OP.EXP, VM_OP.LOG, VM_OP.POW, VM_OP.STEP,
+    VM_OP.SMOOTHSTEP, VM_OP.RSQRT, VM_OP.TAN, VM_OP.ASIN, VM_OP.ACOS, VM_OP.ATAN2,
+    VM_OP.DOT, VM_OP.CROSS, VM_OP.LENGTH, VM_OP.NORMALIZE, VM_OP.DISTANCE,
+    VM_OP.CMP_LT, VM_OP.CMP_LE, VM_OP.CMP_GT, VM_OP.CMP_GE, VM_OP.CMP_EQ,
+    VM_OP.SELECT, VM_OP.RANDOM, VM_OP.CURVE, VM_OP.LOAD_CONST, VM_OP.LOAD_ATTR, VM_OP.LOAD_BUILTIN,
+    VM_OP.NOP,
+];
+
+/** Values the folding pass has rules about, mixed in with arbitrary ones. */
+const NOTABLE_CONSTANTS = [0, 1, -1, 0.5, 2, -0];
+
+/**
+ * A random program, in the UPDATE section.
+ *
+ * @param {function(): number} rand
+ * @param {object} [options]
+ * @param {number} [options.body_length] instructions in the body, before the closing stores
+ * @param {boolean} [options.halt] place a `HALT` part-way through, so unreachable code exists
+ * @param {boolean} [options.tagged] whether sources may be literals
+ * @param {number} [options.register_slots] slots to carve into values — the FAST interpreter's file
+ *   by default, not the ISA's 256. What is being fuzzed is the optimizer over programs of the shape
+ *   a real effect has, and carving every addressable slot would make every generated program a
+ *   register-pressure outlier instead.
+ * @returns {ParticleProgram}
+ */
+export function random_particle_program(rand, {
+    body_length = 24,
+    halt = false,
+    tagged = false,
+    register_slots = PARTICLE_VM_FAST_REGISTER_SLOTS,
+} = {}) {
+    const assembler = new ParticleAssembler();
+    const stream = assembler.update;
+
+    /** @type {Array<{base: number, width: number}>} the file, carved into runs */
+    const values = [];
+
+    for (let base = 0; base < register_slots;) {
+        const width = 1 + Math.floor(rand() * 4);
+
+        if (base + width > register_slots) {
+            break;
+        }
+
+        values.push({ base, width });
+        base += width;
+    }
+
+    /** @type {Map<number, Array<{base: number, width: number}>>} */
+    const by_width = new Map();
+
+    for (const value of values) {
+        if (!by_width.has(value.width)) {
+            by_width.set(value.width, []);
+        }
+
+        by_width.get(value.width).push(value);
+    }
+
+    const widths = Array.from(by_width.keys());
+    const pick = (list) => list[Math.floor(rand() * list.length)];
+    const constant = () => (rand() < 0.45
+        ? NOTABLE_CONSTANTS[Math.floor(rand() * NOTABLE_CONSTANTS.length)]
+        : Math.round((rand() * 8 - 4) * 64) / 64);
+
+    /**
+     * A source in a register slot: a value of the width class, sometimes read through a swizzle
+     * over its own lanes, or — when tagging — a literal.
+     *
+     * @param {Array<{base: number, width: number}>} group
+     * @returns {number|{kind: number, word: number}}
+     */
+    const source = (group) => {
+        if (tagged && rand() < 0.2) {
+            return vm_immediate(constant());
+        }
+
+        const value = pick(group);
+
+        if (rand() < 0.15) {
+            const lane = () => Math.floor(rand() * value.width);
+
+            return vm_register(value.base, pack_swizzle(lane(), lane(), lane(), lane()));
+        }
+
+        return value.base;
+    };
+
+    // Seed the file, so a read is a read of something rather than of the zeroed file.
+    for (const value of values) {
+        stream.loadConst(
+            value.base,
+            assembler.constant(constant(), constant(), constant(), constant()),
+            value.width
+        );
+    }
+
+    const pool = { values, by_width, widths, pick, constant, source };
+
+    for (let i = 0; i < body_length; i++) {
+        emit_random_instruction(stream, assembler, rand, pool);
+    }
+
+    // Store what the file holds, so the fuzzed results are actually observed rather than dropped by
+    // the very dead-code pass under test.
+    let cursor = 1;
+
+    for (const value of values) {
+        if (cursor + value.width > PARTICLE_RECORD_WORD_COUNT) {
+            break;
+        }
+
+        stream.storeAttr(value.base, cursor, value.width);
+        cursor += value.width;
+    }
+
+    if (rand() < 0.35) {
+        stream.kill(pick(values).base);
+    }
+
+    // A tail behind a `HALT`: more instructions, more draws and another store, none of which run.
+    // Anything the optimizer keeps here it has kept for nothing; anything it lets influence the
+    // program above is a bug the equivalence check will name.
+    if (halt) {
+        stream.halt();
+
+        for (let i = 0; i < 4; i++) {
+            emit_random_instruction(stream, assembler, rand, pool);
+        }
+
+        const unreachable = pick(values);
+
+        stream.storeAttr(unreachable.base, 1, unreachable.width);
+    }
+
+    return assembler.build();
+}
+
+/**
+ * One instruction, with operands drawn from a single width class so every source is a whole value.
+ *
+ * @param {import("../isa/InstructionStream.js").InstructionStream} stream
+ * @param {ParticleAssembler} assembler
+ * @param {function(): number} rand
+ * @param {object} pool
+ */
+function emit_random_instruction(stream, assembler, rand, pool) {
+    const { by_width, widths, pick, constant, source } = pool;
+    const op = FUZZ_OPS[Math.floor(rand() * FUZZ_OPS.length)];
+    const meta = VM_ISA.get(op);
+    const candidates = widths.filter(w => w >= meta.min_width);
+
+    if (candidates.length === 0) {
+        return;
+    }
+
+    const width = pick(candidates);
+    const group = by_width.get(width);
+    const dst = pick(group).base;
+
+    switch (op) {
+        case VM_OP.NOP:
+            stream.emit(VM_OP.NOP);
+            return;
+
+        case VM_OP.RANDOM:
+            stream.random(dst, width);
+            return;
+
+        case VM_OP.LOAD_CONST:
+            stream.loadConst(dst, assembler.constant(constant(), constant(), constant(), constant()), width);
+            return;
+
+        case VM_OP.LOAD_BUILTIN:
+            stream.loadBuiltin(dst, Math.floor(rand() * Object.keys(VM_BUILTIN).length), width);
+            return;
+
+        case VM_OP.LOAD_ATTR: {
+            const components = 1 + Math.floor(rand() * 4);
+            const offset = 1 + Math.floor(rand() * (PARTICLE_RECORD_WORD_COUNT - components - 1));
+
+            stream.loadAttr(dst, offset, components, width);
+            return;
+        }
+
+        case VM_OP.CURVE: {
+            const handle = Math.floor(rand() * 4);
+
+            stream.curve(dst, handle, source(group), width);
+            return;
+        }
+
+        default: {
+            // A `SELECT` whose condition is a constant is the shape the folding pass exists for, and
+            // random registers hold one about never — so it is worth steering into deliberately.
+            if (op === VM_OP.SELECT && rand() < 0.4) {
+                const condition = pick(group).base;
+
+                stream.loadConst(
+                    condition,
+                    assembler.constant(...Array.from({ length: 4 }, () => (rand() < 0.5 ? 0 : 1))),
+                    width
+                );
+                stream.emit(op, dst, source(group), source(group), condition, width);
+                return;
+            }
+
+            const operand = (slot) => (meta.operands[slot] === VM_OPERAND.REG ? source(group) : 0);
+
+            stream.emit(op, dst, operand(0), operand(1), operand(2), width);
+        }
+    }
+}
+
+/**
+ * A program built out of the shape the copy rewrites exist for: a run of lanes taken out of one
+ * value and put into another a lane at a time, spelled as plain copies or as lane-picking swizzles.
+ *
+ * {@link random_particle_program} cannot reach it. Its operands come from one width class, so two of
+ * its copies never land on ADJACENT runs, which is the whole of what a merge is about. So the shape
+ * the node library produces from every `decompose` and every `vec2..4` has to be generated on
+ * purpose, with the things that must STOP a merge mixed in at the same time: a write to a slot the
+ * rest of the run still reads, a read of one it is about to fill, a draw, a `HALT`.
+ *
+ * Operands are drawn freely: the destination may land on top of the source, which the executors
+ * define — every source is read before the destination is written — and the rewrites have to
+ * respect.
+ *
+ * @param {function(): number} rand
+ * @param {object} [options]
+ * @param {number} [options.groups] how many take-apart-and-rebuild runs to write
+ * @returns {ParticleProgram}
+ */
+export function random_particle_copy_program(rand, { groups = 5 } = {}) {
+    const assembler = new ParticleAssembler();
+    const stream = assembler.update;
+    const pick = (n) => Math.floor(rand() * n);
+
+    /** Enough of the file for the runs to be placed at random inside it, and no more. */
+    const slots = 20;
+
+    // Seed the file, so a copy copies something.
+    for (let base = 0; base < slots; base += VM_MAX_WIDTH) {
+        stream.loadConst(
+            base,
+            assembler.constant(...Array.from({ length: VM_MAX_WIDTH }, () => Math.round((rand() * 8 - 4) * 64) / 64)),
+            VM_MAX_WIDTH
+        );
+    }
+
+    for (let group = 0; group < groups; group++) {
+        const source = pick(slots - VM_MAX_WIDTH);
+        const destination = pick(slots - VM_MAX_WIDTH);
+        const as_swizzle = rand() < 0.5;
+        const lanes = Array.from({ length: 2 + pick(3) }, (_, lane) => lane);
+
+        // Out of order sometimes, and sometimes with a lane missing: a merge must not care about the
+        // first and must not happen for the second.
+        if (rand() < 0.25) {
+            lanes.reverse();
+        }
+
+        if (rand() < 0.2) {
+            lanes.splice(pick(lanes.length), 1);
+        }
+
+        for (const lane of lanes) {
+            if (as_swizzle) {
+                stream.mov(destination + lane, vm_register(source, pack_swizzle(lane, lane, lane, lane)), 1);
+            } else {
+                stream.mov(destination + lane, source + lane, 1);
+            }
+
+            const roll = rand();
+
+            if (roll < 0.12) {
+                stream.loadConst(source + pick(VM_MAX_WIDTH), assembler.constant(rand()), 1);
+            } else if (roll < 0.24) {
+                stream.storeAttr(destination + pick(VM_MAX_WIDTH), 1 + pick(8), 1);
+            } else if (roll < 0.32) {
+                stream.emit(VM_OP.ADD, pick(slots), pick(slots), pick(slots), 0, 1);
+            } else if (roll < 0.36) {
+                stream.random(pick(slots), 1);
+            }
+        }
+
+        if (rand() < 0.08) {
+            stream.halt();
+        }
+    }
+
+    // Store the file, so what the copies moved is observed rather than dropped as dead.
+    for (let base = 0; base + VM_MAX_WIDTH <= slots && base + VM_MAX_WIDTH < PARTICLE_RECORD_WORD_COUNT; base += VM_MAX_WIDTH) {
+        stream.storeAttr(base, base + 1, VM_MAX_WIDTH);
+    }
+
+    return assembler.build();
+}

package/src/shade/renderer/particles/optimizer/particle_vm_semantics.d.ts

@@ -0,0 +1,107 @@
+/**
+ * What may be assumed about an opcode. An unknown one is assumed to do everything, so a new opcode
+ * is inert to the optimizer until somebody adds it to the table above.
+ *
+ * @param {number} op
+ * @returns {ParticleOpSemantics}
+ */
+export function vm_semantics_of(op: number): ParticleOpSemantics;
+/**
+ * What the optimizer is allowed to assume about each opcode.
+ *
+ * {@link ../isa/ParticleVMISA.js} says what an instruction *does*; this says what may be done *to*
+ * it — whether it can be deleted when its result is unread, narrowed when its high lanes are dead,
+ * evaluated at compile time, or recognised as a recomputation of something already in a register.
+ * Those are four different questions and an opcode can answer them differently: `LOAD_ATTR` is
+ * removable but not shareable across a store, `RANDOM` is neither, and `CURVE` is both.
+ *
+ * Every opcode has to appear in {@link VM_SEMANTICS} — the spec asserts it — because the safe
+ * default for a new one is "assume nothing", and a table that silently omitted it would instead have
+ * the optimizer assume everything.
+ *
+ * Which lane of a source feeds which lane of the result is not a property of the opcode any more:
+ * every register operand carries a swizzle, and `vm_operand_slot` in the ISA answers it per operand.
+ * What is left here is per-opcode: whether lane `i` of the result depends on lane `i` of the
+ * sources alone (`lanewise`), and whether every lane of the result is the same value (`broadcasts`).
+ */
+/**
+ * @typedef {object} ParticleOpSemantics
+ * @property {boolean} side_effects execution changes something other than the destination register:
+ *   the RNG stream, the record, the kill flag, or where the section stops. Never removable, never
+ *   duplicated, never widened or narrowed.
+ * @property {boolean} lanewise output lane `i` is a function of lane `i` of every non-scalar source
+ *   (and of the whole of a scalar one). The reductions and `CROSS` are not.
+ * @property {boolean} narrowable dropping trailing output lanes leaves the remaining ones unchanged.
+ *   Weaker than `lanewise` — `CROSS` writes a fourth lane nothing else depends on — and not implied
+ *   by it for `RANDOM`, whose lanes are independent but whose count is the draw count.
+ * @property {boolean} shareable two executions with equal operand values produce equal results, so a
+ *   second one can read the first one's register instead. False for anything reading the record or
+ *   the RNG.
+ * @property {boolean} broadcasts every lane of the destination holds the same value, by construction
+ *   rather than by what the operands happen to be. Lane `i` is then a copy of lane 0 and may be read
+ *   as one.
+ * @property {boolean} foldable the JS reference and the WGSL interpreter are both obliged to produce
+ *   the *same bits* for this operation, so evaluating it here and baking a constant changes nothing
+ *   on either. Correctly-rounded IEEE arithmetic qualifies; a transcendental does not — JS
+ *   `Math.sin` and a GPU's `sin` agree to about a part in 10^7, which is what the parity spec's
+ *   tolerance is for, and folding would quietly pick the CPU's answer for the GPU.
+ * @property {boolean} foldable_inexact the operation has a value at compile time and it is the right
+ *   one, but only to within the rounding the two executors are allowed to differ by. Folding it is
+ *   the fast-math trade every shading compiler offers: a constant instead of a transcendental, at
+ *   the price of the GPU's own last bits. Never true alongside `foldable` — an operation is exact
+ *   or it is not — and read only by `pass_fold_constants.fold_inexact`, which is off by default.
+ *   Only lanewise operations may carry it: the fold evaluates lane `i` from lane `i` of the sources
+ *   and has no model for a reduction.
+ */
+/** @type {Map<number, ParticleOpSemantics>} */
+export const VM_SEMANTICS: Map<number, ParticleOpSemantics>;
+export type ParticleOpSemantics = {
+    /**
+     * execution changes something other than the destination register:
+     * the RNG stream, the record, the kill flag, or where the section stops. Never removable, never
+     * duplicated, never widened or narrowed.
+     */
+    side_effects: boolean;
+    /**
+     * output lane `i` is a function of lane `i` of every non-scalar source
+     * (and of the whole of a scalar one). The reductions and `CROSS` are not.
+     */
+    lanewise: boolean;
+    /**
+     * dropping trailing output lanes leaves the remaining ones unchanged.
+     * Weaker than `lanewise` — `CROSS` writes a fourth lane nothing else depends on — and not implied
+     * by it for `RANDOM`, whose lanes are independent but whose count is the draw count.
+     */
+    narrowable: boolean;
+    /**
+     * two executions with equal operand values produce equal results, so a
+     * second one can read the first one's register instead. False for anything reading the record or
+     * the RNG.
+     */
+    shareable: boolean;
+    /**
+     * every lane of the destination holds the same value, by construction
+     * rather than by what the operands happen to be. Lane `i` is then a copy of lane 0 and may be read
+     * as one.
+     */
+    broadcasts: boolean;
+    /**
+     * the JS reference and the WGSL interpreter are both obliged to produce
+     * the *same bits* for this operation, so evaluating it here and baking a constant changes nothing
+     * on either. Correctly-rounded IEEE arithmetic qualifies; a transcendental does not — JS
+     * `Math.sin` and a GPU's `sin` agree to about a part in 10^7, which is what the parity spec's
+     * tolerance is for, and folding would quietly pick the CPU's answer for the GPU.
+     */
+    foldable: boolean;
+    /**
+     * the operation has a value at compile time and it is the right
+     * one, but only to within the rounding the two executors are allowed to differ by. Folding it is
+     * the fast-math trade every shading compiler offers: a constant instead of a transcendental, at
+     * the price of the GPU's own last bits. Never true alongside `foldable` — an operation is exact
+     * or it is not — and read only by `pass_fold_constants.fold_inexact`, which is off by default.
+     * Only lanewise operations may carry it: the fold evaluates lane `i` from lane `i` of the sources
+     * and has no model for a reduction.
+     */
+    foldable_inexact: boolean;
+};
+//# sourceMappingURL=particle_vm_semantics.d.ts.map

package/src/shade/renderer/particles/optimizer/particle_vm_semantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_vm_semantics.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/particle_vm_semantics.js"],"names":[],"mappings":"AAoJA;;;;;;GAMG;AACH,oCAHW,MAAM,GACJ,mBAAmB,CAY/B;AAnKD;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,+CAA+C;AAC/C,2BADW,IAAI,MAAM,EAAE,mBAAmB,CAAC,CACL;;;;;;;kBA7BxB,OAAO;;;;;cAGP,OAAO;;;;;;gBAEP,OAAO;;;;;;eAGP,OAAO;;;;;;gBAGP,OAAO;;;;;;;;cAGP,OAAO;;;;;;;;;;sBAKP,OAAO"}

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

@@ -0,0 +1,166 @@
+import { VM_OP } from "../isa/ParticleVMISA.js";
+
+/**
+ * What the optimizer is allowed to assume about each opcode.
+ *
+ * {@link ../isa/ParticleVMISA.js} says what an instruction *does*; this says what may be done *to*
+ * it — whether it can be deleted when its result is unread, narrowed when its high lanes are dead,
+ * evaluated at compile time, or recognised as a recomputation of something already in a register.
+ * Those are four different questions and an opcode can answer them differently: `LOAD_ATTR` is
+ * removable but not shareable across a store, `RANDOM` is neither, and `CURVE` is both.
+ *
+ * Every opcode has to appear in {@link VM_SEMANTICS} — the spec asserts it — because the safe
+ * default for a new one is "assume nothing", and a table that silently omitted it would instead have
+ * the optimizer assume everything.
+ *
+ * Which lane of a source feeds which lane of the result is not a property of the opcode any more:
+ * every register operand carries a swizzle, and `vm_operand_slot` in the ISA answers it per operand.
+ * What is left here is per-opcode: whether lane `i` of the result depends on lane `i` of the
+ * sources alone (`lanewise`), and whether every lane of the result is the same value (`broadcasts`).
+ */
+
+/**
+ * @typedef {object} ParticleOpSemantics
+ * @property {boolean} side_effects execution changes something other than the destination register:
+ *   the RNG stream, the record, the kill flag, or where the section stops. Never removable, never
+ *   duplicated, never widened or narrowed.
+ * @property {boolean} lanewise output lane `i` is a function of lane `i` of every non-scalar source
+ *   (and of the whole of a scalar one). The reductions and `CROSS` are not.
+ * @property {boolean} narrowable dropping trailing output lanes leaves the remaining ones unchanged.
+ *   Weaker than `lanewise` — `CROSS` writes a fourth lane nothing else depends on — and not implied
+ *   by it for `RANDOM`, whose lanes are independent but whose count is the draw count.
+ * @property {boolean} shareable two executions with equal operand values produce equal results, so a
+ *   second one can read the first one's register instead. False for anything reading the record or
+ *   the RNG.
+ * @property {boolean} broadcasts every lane of the destination holds the same value, by construction
+ *   rather than by what the operands happen to be. Lane `i` is then a copy of lane 0 and may be read
+ *   as one.
+ * @property {boolean} foldable the JS reference and the WGSL interpreter are both obliged to produce
+ *   the *same bits* for this operation, so evaluating it here and baking a constant changes nothing
+ *   on either. Correctly-rounded IEEE arithmetic qualifies; a transcendental does not — JS
+ *   `Math.sin` and a GPU's `sin` agree to about a part in 10^7, which is what the parity spec's
+ *   tolerance is for, and folding would quietly pick the CPU's answer for the GPU.
+ * @property {boolean} foldable_inexact the operation has a value at compile time and it is the right
+ *   one, but only to within the rounding the two executors are allowed to differ by. Folding it is
+ *   the fast-math trade every shading compiler offers: a constant instead of a transcendental, at
+ *   the price of the GPU's own last bits. Never true alongside `foldable` — an operation is exact
+ *   or it is not — and read only by `pass_fold_constants.fold_inexact`, which is off by default.
+ *   Only lanewise operations may carry it: the fold evaluates lane `i` from lane `i` of the sources
+ *   and has no model for a reduction.
+ */
+
+/** @type {Map<number, ParticleOpSemantics>} */
+export const VM_SEMANTICS = new Map();
+
+/**
+ * @param {number} op
+ * @param {Partial<ParticleOpSemantics>} flags
+ */
+function semantics(op, flags) {
+    VM_SEMANTICS.set(op, {
+        side_effects: false,
+        lanewise: false,
+        narrowable: false,
+        shareable: false,
+        broadcasts: false,
+        foldable: false,
+        foldable_inexact: false,
+        ...flags,
+    });
+}
+
+/** Pure element-wise arithmetic whose two executors are bit-for-bit obliged to agree. */
+const EXACT = { lanewise: true, narrowable: true, shareable: true, foldable: true };
+
+/**
+ * The same, except that the two executors may round apart: correct to narrow and to share, and
+ * foldable only under the named relaxation — see `foldable_inexact` above.
+ */
+const INEXACT = { lanewise: true, narrowable: true, shareable: true, foldable_inexact: true };
+
+semantics(VM_OP.HALT, { side_effects: true });
+semantics(VM_OP.NOP, {});
+semantics(VM_OP.MOV, EXACT);
+semantics(VM_OP.LOAD_CONST, EXACT);
+// Reads the record, so it is removable when dead but may not be shared across a store that could
+// touch the same words — which is why it is not `shareable` and the CSE pass never sees it.
+semantics(VM_OP.LOAD_ATTR, { lanewise: true, narrowable: true });
+semantics(VM_OP.STORE_ATTR, { side_effects: true });
+semantics(VM_OP.LOAD_BUILTIN, { lanewise: true, narrowable: true, shareable: true });
+semantics(VM_OP.KILL, { side_effects: true });
+
+semantics(VM_OP.ADD, EXACT);
+semantics(VM_OP.SUB, EXACT);
+semantics(VM_OP.MUL, EXACT);
+semantics(VM_OP.DIV, EXACT);
+// `a * b + c` is one rounding on hardware that contracts it into an FMA and two in the reference.
+semantics(VM_OP.MAD, INEXACT);
+semantics(VM_OP.MIN, EXACT);
+semantics(VM_OP.MAX, EXACT);
+// The reference spells it `a + (b - a) * t`; WGSL's `mix` is free to round it differently.
+semantics(VM_OP.MIX, INEXACT);
+semantics(VM_OP.CLAMP, EXACT);
+
+semantics(VM_OP.NEG, EXACT);
+semantics(VM_OP.ABS, EXACT);
+semantics(VM_OP.FLOOR, EXACT);
+semantics(VM_OP.FRACT, EXACT);
+semantics(VM_OP.SQRT, EXACT);
+semantics(VM_OP.SIN, INEXACT);
+semantics(VM_OP.COS, INEXACT);
+semantics(VM_OP.EXP, INEXACT);
+semantics(VM_OP.LOG, INEXACT);
+semantics(VM_OP.POW, INEXACT);
+semantics(VM_OP.STEP, EXACT);
+semantics(VM_OP.SMOOTHSTEP, INEXACT);
+// `inverseSqrt` is a hardware estimate with ULPs of slack to it, and the reference divides one by
+// a square root — a different computation rather than a different rounding of the same one. So it
+// folds where a transcendental folds: under `fold_inexact`, and not before.
+semantics(VM_OP.RSQRT, INEXACT);
+semantics(VM_OP.TAN, INEXACT);
+semantics(VM_OP.ASIN, INEXACT);
+semantics(VM_OP.ACOS, INEXACT);
+semantics(VM_OP.ATAN2, INEXACT);
+
+// The reductions read every lane to write one, so there are no trailing lanes to drop.
+semantics(VM_OP.DOT, { shareable: true });
+// Three lanes of cross product plus, optionally, the zero `w`. Dropping that `w` is the one
+// narrowing available, and `min_width` already floors it at three.
+semantics(VM_OP.CROSS, { narrowable: true, shareable: true });
+semantics(VM_OP.LENGTH, { shareable: true });
+semantics(VM_OP.NORMALIZE, { shareable: true });
+semantics(VM_OP.DISTANCE, { shareable: true });
+
+semantics(VM_OP.CMP_LT, EXACT);
+semantics(VM_OP.CMP_LE, EXACT);
+semantics(VM_OP.CMP_GT, EXACT);
+semantics(VM_OP.CMP_GE, EXACT);
+semantics(VM_OP.CMP_EQ, EXACT);
+semantics(VM_OP.SELECT, EXACT);
+
+// Ordered and side-effecting: it advances the shared RNG, and its width IS the number of draws it
+// takes. Removing, duplicating, reordering or narrowing one moves every value drawn after it.
+semantics(VM_OP.RANDOM, { side_effects: true });
+// An external WGSL symbol, but a pure function of (handle, t) — so a dead one goes and a repeated
+// one is shared. Every lane of the result is the same sample, which is what makes it narrowable —
+// and what makes it a broadcast, so a consumer reading it wide is a consumer that wants `.xxxx`.
+semantics(VM_OP.CURVE, { lanewise: true, narrowable: true, shareable: true, broadcasts: true });
+
+/**
+ * What may be assumed about an opcode. An unknown one is assumed to do everything, so a new opcode
+ * is inert to the optimizer until somebody adds it to the table above.
+ *
+ * @param {number} op
+ * @returns {ParticleOpSemantics}
+ */
+export function vm_semantics_of(op) {
+    return VM_SEMANTICS.get(op) ?? {
+        side_effects: true,
+        lanewise: false,
+        narrowable: false,
+        shareable: false,
+        broadcasts: false,
+        foldable: false,
+        foldable_inexact: false,
+    };
+}