@woosh/meep-engine 3.14.6 → 3.16.0

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

@@ -0,0 +1,95 @@
+/**
+ * Run one section and return everything a program can be observed to have done.
+ *
+ * @param {object} params
+ * @param {Uint32Array} params.words
+ * @param {Float32Array|number[]} params.constants
+ * @param {number} params.register_count
+ * @param {object} params.environment one of {@link PARTICLE_ENVIRONMENTS}
+ * @returns {{ record: Uint32Array, killed: boolean, rng_state: number }}
+ */
+export function run_particle_section({ words, constants, register_count, environment }: {
+    words: Uint32Array;
+    constants: Float32Array | number[];
+    register_count: number;
+    environment: object;
+}): {
+    record: Uint32Array;
+    killed: boolean;
+    rng_state: number;
+};
+/**
+ * Compare two runs. Record words are compared as raw bits first — which is the strict answer,
+ * including the sign of a zero — and only a pair that differs is re-read as floats, so a `NaN` on
+ * both sides counts as agreement whatever payload it carries.
+ *
+ * @param {{record: Uint32Array, killed: boolean, rng_state: number}} before
+ * @param {{record: Uint32Array, killed: boolean, rng_state: number}} after
+ * @param {object} [comparison]
+ * @param {number} [comparison.tolerance] relative slack on record words; zero means the bits match
+ * @param {boolean} [comparison.absorbed_zero] accept the two things `x * 0 -> +0` gives up: a `-0`
+ *   that became a `+0`, and a `NaN` that became a zero. Nothing else — a number that moved is still
+ *   a failure, and a zero that became a `NaN` is a failure in the direction that cannot happen.
+ * @returns {string|null} what differs, or `null` when nothing does
+ */
+export function diff_particle_section_result(before: {
+    record: Uint32Array;
+    killed: boolean;
+    rng_state: number;
+}, after: {
+    record: Uint32Array;
+    killed: boolean;
+    rng_state: number;
+}, { tolerance, absorbed_zero }?: {
+    tolerance?: number;
+    absorbed_zero?: boolean;
+}): string | null;
+/**
+ * Compare an optimized section against the original across every environment.
+ *
+ * The two may have different register counts and different constant pools — the optimizer shrinks
+ * one and may extend the other — so both are passed per side rather than assumed shared.
+ *
+ * @param {object} params
+ * @param {{words: Uint32Array, constants: Float32Array|number[], register_count: number}} params.before
+ * @param {{words: Uint32Array, constants: Float32Array|number[], register_count: number}} params.after
+ * @param {Array<object>} [params.environments]
+ * @param {object} [params.comparison] see {@link diff_particle_section_result}
+ * @returns {string|null} a description of the first divergence, or `null`
+ */
+export function diff_particle_sections({ before, after, environments, comparison }: {
+    before: {
+        words: Uint32Array;
+        constants: Float32Array | number[];
+        register_count: number;
+    };
+    after: {
+        words: Uint32Array;
+        constants: Float32Array | number[];
+        register_count: number;
+    };
+    environments?: Array<object>;
+    comparison?: object;
+}): string | null;
+/**
+ * Compare every section of two compiled programs.
+ *
+ * @param {ParticleProgram} before
+ * @param {ParticleProgram} after
+ * @param {object} [comparison] see {@link diff_particle_section_result}, plus `environments`
+ * @returns {string|null}
+ */
+export function diff_particle_programs(before: ParticleProgram, after: ParticleProgram, comparison?: object): string | null;
+/**
+ * The contexts a program is compared in. Seeds differ so a pass that dropped or added a draw shows
+ * up as a diverging RNG state rather than only as a diverging record.
+ *
+ * @type {Array<{name: string, builtins: number[][], rng_state: number, record: () => Uint32Array}>}
+ */
+export const PARTICLE_ENVIRONMENTS: Array<{
+    name: string;
+    builtins: number[][];
+    rng_state: number;
+    record: () => Uint32Array;
+}>;
+//# sourceMappingURL=particle_program_equivalence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"particle_program_equivalence.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/particle_program_equivalence.js"],"names":[],"mappings":"AAiFA;;;;;;;;;GASG;AACH;IAN+B,KAAK,EAAzB,WAAW;IACmB,SAAS,EAAvC,YAAY,GAAC,MAAM,EAAE;IACN,cAAc,EAA7B,MAAM;IACS,WAAW,EAA1B,MAAM;;YACM,WAAW;YAAU,OAAO;eAAa,MAAM;EAgBrE;AAED;;;;;;;;;;;;;GAaG;AACH,qDATW;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,SACzD;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC;IAErC,SAAS,GAA7B,MAAM;IACe,aAAa,GAAlC,OAAO;IAGL,MAAM,GAAC,IAAI,CAqCvB;AAED;;;;;;;;;;;;GAYG;AACH;IANkG,MAAM,EAA7F;QAAC,KAAK,EAAE,WAAW,CAAC;QAAC,SAAS,EAAE,YAAY,GAAC,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAC;IACS,KAAK,EAA5F;QAAC,KAAK,EAAE,WAAW,CAAC;QAAC,SAAS,EAAE,YAAY,GAAC,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAC;IACvD,YAAY,GAAnC,MAAM,MAAM,CAAC;IACG,UAAU,GAA1B,MAAM;IACJ,MAAM,GAAC,IAAI,CAgBvB;AAED;;;;;;;GAOG;AACH,qGAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAmBvB;AAhJD;;;;;GAKG;AACH,oCAFU,MAAM;IAAC,MAAM,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,WAAW,CAAA;CAAC,CAAC,CAOjG"}

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

@@ -0,0 +1,213 @@
+import { PARTICLE_RECORD_WORD_COUNT } from "../ParticleConstants.js";
+import { VM_BUILTIN } from "../isa/ParticleVMISA.js";
+import { execute_particle_vm } from "../vm/ParticleVMReference.js";
+
+/**
+ * The property every optimizer pass is held to: an optimized program leaves the same record, the
+ * same kill flag and the same RNG state as the one it was built from — to the bit.
+ *
+ * This is a differential harness rather than a set of expected outputs because the interesting
+ * failures are not "the optimizer produced something odd", they are "the optimizer produced
+ * something plausible that computes a slightly different number". Running both programs on
+ * {@link execute_particle_vm} and comparing the whole observable state catches those without anyone
+ * having to predict them.
+ *
+ * ## Bit-identical, and the two relaxations that are named rather than tolerated
+ *
+ * Float rewrites that look obviously fine mostly are not, so the default here is that the bits
+ * match. Two rewrites deliberately do not, and each has a comparison mode that accepts EXACTLY what
+ * it gives up and nothing else — a blanket tolerance would accept those and also whatever else went
+ * wrong:
+ *
+ * - `absorbed_zero`, for `fold_constants.fold_multiply_by_zero` (on by default). Folding `x * 0` to
+ *   `+0` gives up the sign of that zero, and turns a `NaN` from an upstream overflow into a zero.
+ *   Those two shapes are accepted; a value that merely moved is not.
+ * - `tolerance`, for `peephole.fuse_multiply_add` (off by default), which is a rounding difference
+ *   and so has no shape to name.
+ *
+ * ## Environments
+ *
+ * A program reads more than its constants — record words, builtins, the RNG, curve samples — and a
+ * pass that mishandled any of those could still agree on a single run. {@link PARTICLE_ENVIRONMENTS}
+ * varies all of them, including a record pre-filled with values a `LOAD_ATTR` can pick up.
+ */
+
+/** Distinct, non-round values, so a builtin read from the wrong id or lane lands on a wrong number. */
+const BUILTINS_A = [];
+BUILTINS_A[VM_BUILTIN.DELTA_TIME] = [0.0125, 0, 0, 0];
+BUILTINS_A[VM_BUILTIN.EMITTER_AGE] = [3.5, 0, 0, 0];
+BUILTINS_A[VM_BUILTIN.EMITTER_POSITION] = [1.25, -2.5, 7, 1];
+BUILTINS_A[VM_BUILTIN.EMITTER_DIRECTION] = [0.6, -0.5, -0.8, 0];
+BUILTINS_A[VM_BUILTIN.EMITTER_UP] = [-0.25, 1, 0.375, 0];
+BUILTINS_A[VM_BUILTIN.PARTICLE_INDEX] = [11, 0, 0, 0];
+BUILTINS_A[VM_BUILTIN.SPAWN_FRACTION] = [0.75, 0, 0, 0];
+BUILTINS_A[VM_BUILTIN.TIME] = [12.5, 0, 0, 0];
+
+/** A second set, negated and shuffled, so nothing passes by holding a builtin's value constant. */
+const BUILTINS_B = BUILTINS_A.map(v => v.map(x => -x + 0.5));
+
+/**
+ * A record with something in every user word — a program that loads an attribute the harness left
+ * at zero is a program whose loads are all interchangeable.
+ *
+ * @returns {Uint32Array}
+ */
+function seeded_record() {
+    const record = new Uint32Array(PARTICLE_RECORD_WORD_COUNT);
+    const floats = new Float32Array(record.buffer);
+
+    for (let i = 1; i < PARTICLE_RECORD_WORD_COUNT; i++) {
+        floats[i] = (i % 7) - 3.25 + i / 32;
+    }
+
+    return record;
+}
+
+/** @param {number} handle @param {number} t @returns {number} */
+const sample_curve = (handle, t) => Math.sin(handle + t * 3) * 0.5 + handle * 0.125;
+
+/**
+ * The contexts a program is compared in. Seeds differ so a pass that dropped or added a draw shows
+ * up as a diverging RNG state rather than only as a diverging record.
+ *
+ * @type {Array<{name: string, builtins: number[][], rng_state: number, record: () => Uint32Array}>}
+ */
+export const PARTICLE_ENVIRONMENTS = [
+    { name: "zeroed record, seed 1", builtins: BUILTINS_A, rng_state: 1, record: () => new Uint32Array(PARTICLE_RECORD_WORD_COUNT) },
+    { name: "seeded record, seed 1", builtins: BUILTINS_A, rng_state: 1, record: seeded_record },
+    { name: "seeded record, seed 0x9e3779b9", builtins: BUILTINS_B, rng_state: 0x9e3779b9, record: seeded_record },
+    { name: "seeded record, seed 12345", builtins: BUILTINS_B, rng_state: 12345, record: seeded_record },
+];
+
+/**
+ * Run one section and return everything a program can be observed to have done.
+ *
+ * @param {object} params
+ * @param {Uint32Array} params.words
+ * @param {Float32Array|number[]} params.constants
+ * @param {number} params.register_count
+ * @param {object} params.environment one of {@link PARTICLE_ENVIRONMENTS}
+ * @returns {{ record: Uint32Array, killed: boolean, rng_state: number }}
+ */
+export function run_particle_section({ words, constants, register_count, environment }) {
+    const record = environment.record();
+
+    const result = execute_particle_vm({
+        words,
+        constants: constants instanceof Float32Array ? constants : new Float32Array(constants),
+        register_count,
+        record,
+        builtins: environment.builtins,
+        rng_state: environment.rng_state,
+        sampleCurve: sample_curve,
+    });
+
+    return { record, killed: result.killed, rng_state: result.rng_state };
+}
+
+/**
+ * Compare two runs. Record words are compared as raw bits first — which is the strict answer,
+ * including the sign of a zero — and only a pair that differs is re-read as floats, so a `NaN` on
+ * both sides counts as agreement whatever payload it carries.
+ *
+ * @param {{record: Uint32Array, killed: boolean, rng_state: number}} before
+ * @param {{record: Uint32Array, killed: boolean, rng_state: number}} after
+ * @param {object} [comparison]
+ * @param {number} [comparison.tolerance] relative slack on record words; zero means the bits match
+ * @param {boolean} [comparison.absorbed_zero] accept the two things `x * 0 -> +0` gives up: a `-0`
+ *   that became a `+0`, and a `NaN` that became a zero. Nothing else — a number that moved is still
+ *   a failure, and a zero that became a `NaN` is a failure in the direction that cannot happen.
+ * @returns {string|null} what differs, or `null` when nothing does
+ */
+export function diff_particle_section_result(before, after, { tolerance = 0, absorbed_zero = false } = {}) {
+    if (before.killed !== after.killed) {
+        return `kill flag: ${before.killed} -> ${after.killed}`;
+    }
+
+    if (before.rng_state !== after.rng_state) {
+        return `RNG state: ${before.rng_state} -> ${after.rng_state}`;
+    }
+
+    const a = new Float32Array(before.record.buffer);
+    const b = new Float32Array(after.record.buffer);
+
+    for (let i = 0; i < before.record.length; i++) {
+        if (before.record[i] === after.record[i]) {
+            continue;
+        }
+
+        if (Number.isNaN(a[i]) && Number.isNaN(b[i])) {
+            continue;
+        }
+
+        // `===` rather than `Object.is`, so the two zeros compare equal and nothing else does.
+        if (absorbed_zero && (a[i] === b[i] || (Number.isNaN(a[i]) && b[i] === 0))) {
+            continue;
+        }
+
+        if (tolerance > 0 && Math.abs(a[i] - b[i]) <= tolerance * Math.max(1, Math.abs(a[i]), Math.abs(b[i]))) {
+            continue;
+        }
+
+        return `record word ${i}: ${a[i]} (0x${before.record[i].toString(16)})`
+            + ` -> ${b[i]} (0x${after.record[i].toString(16)})`;
+    }
+
+    return null;
+}
+
+/**
+ * Compare an optimized section against the original across every environment.
+ *
+ * The two may have different register counts and different constant pools — the optimizer shrinks
+ * one and may extend the other — so both are passed per side rather than assumed shared.
+ *
+ * @param {object} params
+ * @param {{words: Uint32Array, constants: Float32Array|number[], register_count: number}} params.before
+ * @param {{words: Uint32Array, constants: Float32Array|number[], register_count: number}} params.after
+ * @param {Array<object>} [params.environments]
+ * @param {object} [params.comparison] see {@link diff_particle_section_result}
+ * @returns {string|null} a description of the first divergence, or `null`
+ */
+export function diff_particle_sections({ before, after, environments = PARTICLE_ENVIRONMENTS, comparison }) {
+    for (const environment of environments) {
+        const difference = diff_particle_section_result(
+            run_particle_section({ ...before, environment }),
+            run_particle_section({ ...after, environment }),
+            comparison
+        );
+
+        if (difference !== null) {
+            return `${environment.name}: ${difference}`;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Compare every section of two compiled programs.
+ *
+ * @param {ParticleProgram} before
+ * @param {ParticleProgram} after
+ * @param {object} [comparison] see {@link diff_particle_section_result}, plus `environments`
+ * @returns {string|null}
+ */
+export function diff_particle_programs(before, after, comparison = {}) {
+    const { environments = PARTICLE_ENVIRONMENTS, ...rest } = comparison;
+
+    for (const section of ["init", "update"]) {
+        const difference = diff_particle_sections({
+            before: { words: before[section], constants: before.constants, register_count: before.register_count },
+            after: { words: after[section], constants: after.constants, register_count: after.register_count },
+            environments,
+            comparison: rest,
+        });
+
+        if (difference !== null) {
+            return `${section}: ${difference}`;
+        }
+    }
+
+    return null;
+}

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

@@ -0,0 +1,16 @@
+/** @param {number} seed @returns {function(): number} */
+export function mulberry32(seed: number): () => number;
+/**
+ * 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
+ * @returns {ParticleProgram}
+ */
+export function random_particle_program(rand: () => number, { body_length, halt }?: {
+    body_length?: number;
+    halt?: boolean;
+}): ParticleProgram;
+//# sourceMappingURL=particle_program_fuzz.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"particle_program_fuzz.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/particle_program_fuzz.js"],"names":[],"mappings":"AAoCA,yDAAyD;AACzD,iCADY,MAAM,SAA6B,MAAM,CAWpD;AAED;;;;;;;;GAQG;AACH,oDANuB,MAAM;IAED,WAAW,GAA5B,MAAM;IACY,IAAI,GAAtB,OAAO;oBAoFjB"}

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

@@ -0,0 +1,223 @@
+import { PARTICLE_RECORD_WORD_COUNT, PARTICLE_VM_REGISTER_SLOTS } from "../ParticleConstants.js";
+import { ParticleAssembler } from "../isa/ParticleAssembler.js";
+import { VM_BUILTIN, VM_ISA, VM_OP, VM_OPERAND, pack_swizzle } 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, which is what makes the results legal: the ISA lets two
+ * operands of an instruction name the same run or disjoint ones, never a partial overlap, and runs
+ * of equal width either coincide or do not touch. `../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.
+ */
+
+/** 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.SCALE, 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.DOT, VM_OP.CROSS, VM_OP.LENGTH, VM_OP.NORMALIZE, VM_OP.DISTANCE,
+    VM_OP.SWIZZLE, 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];
+
+/** @param {number} seed @returns {function(): number} */
+export function mulberry32(seed) {
+    let a = seed >>> 0;
+
+    return function () {
+        a |= 0;
+        a = (a + 0x6D2B79F5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+
+/**
+ * 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
+ * @returns {ParticleProgram}
+ */
+export function random_particle_program(rand, { body_length = 24, halt = false } = {}) {
+    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 < PARTICLE_VM_REGISTER_SLOTS;) {
+        const width = 1 + Math.floor(rand() * 4);
+
+        if (base + width > PARTICLE_VM_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);
+
+    // 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
+        );
+    }
+
+    for (let i = 0; i < body_length; i++) {
+        emit_random_instruction(stream, assembler, rand, { values, by_width, widths, pick, constant });
+    }
+
+    // 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, { values, by_width, widths, pick, constant });
+        }
+
+        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 the operand runs coincide or
+ * stay disjoint.
+ *
+ * @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 } = 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 destination = pick(group);
+    const dst = destination.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:
+            stream.curve(dst, Math.floor(rand() * 4), pick(group).base, width);
+            return;
+
+        case VM_OP.SWIZZLE: {
+            const source = pick(group);
+            const lane = () => Math.floor(rand() * source.width);
+
+            stream.emit(op, dst, source.base, pack_swizzle(lane(), lane(), lane(), lane()), 0, 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, pick(group).base, pick(group).base, condition, width);
+                return;
+            }
+
+            const operand = (slot) => (meta.operands[slot] === VM_OPERAND.REG ? pick(group).base : 0);
+
+            stream.emit(op, dst, operand(0), operand(1), operand(2), width);
+        }
+    }
+}

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

@@ -0,0 +1,121 @@
+/**
+ * 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;
+/**
+ * Which lane of a source operand feeds a given output lane.
+ *
+ * A scalar operand feeds every output lane from lane 0, a `SWIZZLE` reads the lane its pattern
+ * names, and everything lanewise reads straight across.
+ *
+ * @param {number} op
+ * @param {number} lane output lane
+ * @param {boolean} is_scalar whether the ISA marks this source slot scalar
+ * @param {number} pattern packed swizzle pattern, read only for `SWIZZLE`
+ * @returns {number} lane of the source operand read into `lane`
+ */
+export function vm_source_lane(op: number, lane: number, is_scalar: boolean, pattern: number): number;
+/**
+ * Rewrite a swizzle pattern so its lanes past `width` name nothing new.
+ *
+ * A pattern's four selectors are read whatever the instruction's width, so a narrowed broadcast
+ * still reaches as far as its widest selector — {@link swizzle_span} counts all four. Pointing the
+ * unused ones at lane 0's selector shrinks the source run to what the live lanes actually read,
+ * which is what frees the slots above it.
+ *
+ * @param {number} pattern
+ * @param {number} width lanes the instruction still writes
+ * @returns {number} a pattern equivalent at that width
+ */
+export function vm_trim_swizzle(pattern: number, width: number): number;
+/**
+ * How far into its source a swizzle reaches once trimmed to `width`.
+ *
+ * @param {number} pattern
+ * @param {number} width
+ * @returns {number}
+ */
+export function vm_trimmed_swizzle_span(pattern: number, width: number): number;
+/**
+ * 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.
+ */
+/**
+ * @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; `SWIZZLE` is lane-mapped
+ *   rather than lanewise and is handled by {@link vm_source_lane}.
+ * @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.
+ */
+/** @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; `SWIZZLE` is lane-mapped
+     * rather than lanewise and is handled by {@link vm_source_lane }.
+     */
+    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;
+};
+//# 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":"AAgIA;;;;;;GAMG;AACH,oCAHW,MAAM,GACJ,mBAAmB,CAW/B;AAED;;;;;;;;;;;GAWG;AACH,mCANW,MAAM,QACN,MAAM,aACN,OAAO,WACP,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;;;;;;GAWG;AACH,yCAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAclB;AAED;;;;;;GAMG;AACH,iDAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;AA3MD;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,+CAA+C;AAC/C,2BADW,IAAI,MAAM,EAAE,mBAAmB,CAAC,CACL;;;;;;;kBAvBxB,OAAO;;;;;;cAGP,OAAO;;;;;;gBAGP,OAAO;;;;;;eAGP,OAAO;;;;;;gBAGP,OAAO;;;;;;;;cAGP,OAAO"}