@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -0,0 +1,128 @@
+/**
+ * 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;
+};
+/**
+ * Which record words — and whether the kill flag — the result of a zero-absorbing opcode can reach.
+ *
+ * This is the bound on `fold_constants.fold_multiply_by_zero`, and it is deliberately blunt in the
+ * one direction that keeps it sound: every instruction in
+ * {@link PARTICLE_ZERO_ABSORBING_OPS} is treated as though its result had been substituted, because
+ * which of them had a compile-time zero operand is a fact about the optimizer's analysis and not
+ * about the program. The set comes from the pass rather than being restated here, so an opcode added
+ * to the rewrite is an opcode this follows. Everything the marked slots flow into is marked too, and a
+ * store carries the mark into the record word it writes.
+ *
+ * A `LOAD_ATTR` of a marked record word marks its destination back, so a value that went out through
+ * the record and came back in is still followed. Slots are cleared by a write whose sources are all
+ * unmarked — the value there is then the same in both programs — while record words are only ever
+ * added to, because a store cannot un-write what an earlier one already made unequal.
+ *
+ * Static, so it over-approximates the runs: a lane that never actually held a substituted zero is
+ * marked anyway. That is the right direction to be wrong in, and it is not blunt in practice — see
+ * the 94% in the module comment.
+ *
+ * @param {Uint32Array} words a packed instruction section
+ * @returns {{record: Uint8Array, killed: boolean}}
+ */
+export function particle_multiply_reach(words: Uint32Array): {
+    record: Uint8Array;
+    killed: boolean;
+};
+/**
+ * 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 {{record: Uint8Array, killed: boolean}|null} [comparison.reach] what the zero fold is
+ *   allowed to have changed, from {@link particle_multiply_reach}. A marked word is not compared at
+ *   all — there is no shape left to hold it to, which is the whole of the argument in the module
+ *   comment — and every other one is held to the bit.
+ * @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, reach }?: {
+    tolerance?: number;
+    reach?: {
+        record: Uint8Array;
+        killed: boolean;
+    } | null;
+}): 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}, plus
+ *   `reached_by_zero_fold` — the reach is a property of the two SECTIONS rather than of a run, so it
+ *   is worked out once here and handed down as `reach`
+ * @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_sections}, 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":"AA8GA;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,+CAHW,WAAW;YACA,UAAU;YAAU,OAAO;EAkEhD;AAqCD;;;;;;;;;;;;;;GAcG;AACH,qDAVW;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;IACkD,KAAK,GAA7D;QAAC,MAAM,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAC,GAAC,IAAI;IAIxC,MAAM,GAAC,IAAI,CAuCvB;AAED;;;;;;;;;;;;;;GAcG;AACH;IARkG,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;IAGJ,MAAM,GAAC,IAAI,CAqBvB;AAED;;;;;;;GAOG;AACH,qGAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAmBvB;AAtRD;;;;;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,376 @@
+import { PARTICLE_RECORD_WORD_COUNT, PARTICLE_VM_INSTRUCTION_WORDS, PARTICLE_VM_REGISTER_SLOTS } from "../ParticleConstants.js";
+import { VM_BUILTIN, VM_KIND, VM_MAX_WIDTH, VM_OP } from "../isa/ParticleVMISA.js";
+import { execute_particle_vm } from "../vm/ParticleVMReference.js";
+import { decode_particle_instructions, particle_read_slots } from "./particle_program_analysis.js";
+import { PARTICLE_ZERO_ABSORBING_OPS } from "./pass_fold_constants.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:
+ *
+ * - `reached_by_zero_fold`, for `fold_constants.fold_multiply_by_zero` (on by default).
+ * - `tolerance`, for `peephole.fuse_multiply_add` (off by default), which is a rounding difference
+ *   and so has no shape to name.
+ *
+ * The third relaxation, `fold_constants.fold_inexact`, needs nothing here, and that absence is the
+ * point of it: the fold evaluates each operation the way the reference executes it, so a program
+ * with the transcendentals folded is bit-identical HERE and differs only against a GPU. Which is
+ * why this harness cannot vouch for that one — `../vm/chunk_particle_vm.spec.js` is where the two
+ * executors meet, and its 1e-4 tolerance is exactly the slack the option spends.
+ *
+ * ## Why the zero fold is a reachability question and not a shape one
+ *
+ * This mode used to be called `absorbed_zero` and accepted two record shapes: a `-0` that had become
+ * a `+0`, and a `NaN` that had become a zero. Those are what folding `x * 0` to `+0` gives up AT THE
+ * MULTIPLY — and the record is not the multiply. The substitution lands in a register, and the next
+ * instruction to read that register is free to turn it into anything:
+ *
+ *     LOG r1, r0        ; r0 is zero, so r1 is -Inf
+ *     SCALE r3, r2, r1  ; r2 is -0. -0 * -Inf is NaN; folded, r3 is +0
+ *     CMP_GE r4, r3, r2 ; NaN >= -0 is false. +0 >= -0 is true. The record word is 0, then 1.
+ *
+ * A `0` that became a `1` is neither of the two shapes, and no per-word test on the record can name
+ * it — a division by the substituted zero turns the same `NaN` into an `Infinity` instead, and one
+ * more comparison launders that back into a finite number. Both of those came out of the fuzzer
+ * (`random_particle_program` seeds 148 and 2743), past the range the specs were sweeping.
+ *
+ * So what is bounded is not the VALUE but the REACH. {@link particle_multiply_reach} marks every
+ * record word a `MUL` or `SCALE` result can flow into, statically and without caring which multiply
+ * had a zero operand; the mode stops comparing those words and holds every other one to the bit.
+ * Over the fuzz corpus that leaves about 94% of the stored words still compared exactly, which is
+ * the part of the promise that survived — a pass that moved a value the fold never touched is still
+ * caught, and only the words genuinely downstream of a multiply are given up.
+ *
+ * ## 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 };
+}
+
+/**
+ * Which record words — and whether the kill flag — the result of a zero-absorbing opcode can reach.
+ *
+ * This is the bound on `fold_constants.fold_multiply_by_zero`, and it is deliberately blunt in the
+ * one direction that keeps it sound: every instruction in
+ * {@link PARTICLE_ZERO_ABSORBING_OPS} is treated as though its result had been substituted, because
+ * which of them had a compile-time zero operand is a fact about the optimizer's analysis and not
+ * about the program. The set comes from the pass rather than being restated here, so an opcode added
+ * to the rewrite is an opcode this follows. Everything the marked slots flow into is marked too, and a
+ * store carries the mark into the record word it writes.
+ *
+ * A `LOAD_ATTR` of a marked record word marks its destination back, so a value that went out through
+ * the record and came back in is still followed. Slots are cleared by a write whose sources are all
+ * unmarked — the value there is then the same in both programs — while record words are only ever
+ * added to, because a store cannot un-write what an earlier one already made unequal.
+ *
+ * Static, so it over-approximates the runs: a lane that never actually held a substituted zero is
+ * marked anyway. That is the right direction to be wrong in, and it is not blunt in practice — see
+ * the 94% in the module comment.
+ *
+ * @param {Uint32Array} words a packed instruction section
+ * @returns {{record: Uint8Array, killed: boolean}}
+ */
+export function particle_multiply_reach(words) {
+    const decoded = decode_particle_instructions(instruction_tuples(words));
+
+    /** One flag per register slot, with room for an operand run that ends on the last of them. */
+    const slot = new Uint8Array(PARTICLE_VM_REGISTER_SLOTS + VM_MAX_WIDTH);
+    const record = new Uint8Array(PARTICLE_RECORD_WORD_COUNT);
+
+    let killed = false;
+
+    for (const instruction of decoded) {
+        // Nothing past a `HALT` runs, so nothing past it can carry anything anywhere.
+        if (instruction.op === VM_OP.HALT) {
+            break;
+        }
+
+        let reached = false;
+
+        for (const read of instruction.reads) {
+            for (const s of particle_read_slots(read)) {
+                reached = reached || slot[s] === 1;
+            }
+        }
+
+        // The record operands are read straight out of the words: `LOAD_ATTR` keeps its offset and
+        // component count in s0 and s1, `STORE_ATTR` in s1 and s2 behind the value it stores.
+        if (instruction.op === VM_OP.LOAD_ATTR) {
+            const offset = instruction.words[1];
+            const components = instruction.words[2];
+
+            for (let lane = 0; lane < components; lane++) {
+                reached = reached || record[offset + lane] === 1;
+            }
+        }
+
+        if (instruction.op === VM_OP.STORE_ATTR) {
+            const offset = instruction.words[2];
+            const components = instruction.words[3];
+            const value = instruction.sources[0];
+            const stored = value.kind === VM_KIND.REG ? particle_read_slots(value, components) : [];
+
+            for (let lane = 0; lane < components; lane++) {
+                record[offset + lane] |= lane < stored.length ? slot[stored[lane]] : 0;
+            }
+
+            continue;
+        }
+
+        if (instruction.op === VM_OP.KILL) {
+            killed = killed || reached;
+            continue;
+        }
+
+        if (instruction.write === null) {
+            continue;
+        }
+
+        const substitutes = PARTICLE_ZERO_ABSORBING_OPS.has(instruction.op);
+
+        for (let lane = 0; lane < instruction.write.span; lane++) {
+            slot[instruction.write.base + lane] = substitutes || reached ? 1 : 0;
+        }
+    }
+
+    return { record, killed };
+}
+
+/**
+ * The reach of both sides at once. The two programs address different registers — packing moves
+ * them — so the sections are walked separately and only the record words are put together.
+ *
+ * @param {Uint32Array} before
+ * @param {Uint32Array} after
+ * @returns {{record: Uint8Array, killed: boolean}}
+ */
+function combined_multiply_reach(before, after) {
+    const a = particle_multiply_reach(before);
+    const b = particle_multiply_reach(after);
+
+    for (let i = 0; i < a.record.length; i++) {
+        a.record[i] |= b.record[i];
+    }
+
+    return { record: a.record, killed: a.killed || b.killed };
+}
+
+/**
+ * A packed section as the four-word tuples {@link decode_particle_instructions} reads.
+ *
+ * @param {Uint32Array} words
+ * @returns {Uint32Array[]} views, so nothing is copied
+ */
+function instruction_tuples(words) {
+    const out = [];
+
+    for (let base = 0; base < words.length; base += PARTICLE_VM_INSTRUCTION_WORDS) {
+        out.push(words.subarray(base, base + PARTICLE_VM_INSTRUCTION_WORDS));
+    }
+
+    return out;
+}
+
+/**
+ * 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 {{record: Uint8Array, killed: boolean}|null} [comparison.reach] what the zero fold is
+ *   allowed to have changed, from {@link particle_multiply_reach}. A marked word is not compared at
+ *   all — there is no shape left to hold it to, which is the whole of the argument in the module
+ *   comment — and every other one is held to the bit.
+ * @returns {string|null} what differs, or `null` when nothing does
+ */
+export function diff_particle_section_result(before, after, { tolerance = 0, reach = null } = {}) {
+    if (before.killed !== after.killed && !(reach !== null && reach.killed)) {
+        return `kill flag: ${before.killed} -> ${after.killed}`;
+    }
+
+    // Never relaxed. `RANDOM` has side effects, so no pass may add, drop or reorder a draw, and a
+    // substituted zero cannot reach the stream either — there is nothing in this ISA that makes a
+    // draw conditional on a value.
+    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;
+        }
+
+        if (reach !== null && reach.record[i] === 1) {
+            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}, plus
+ *   `reached_by_zero_fold` — the reach is a property of the two SECTIONS rather than of a run, so it
+ *   is worked out once here and handed down as `reach`
+ * @returns {string|null} a description of the first divergence, or `null`
+ */
+export function diff_particle_sections({ before, after, environments = PARTICLE_ENVIRONMENTS, comparison }) {
+    const { reached_by_zero_fold = false, ...rest } = comparison ?? {};
+    const resolved = reached_by_zero_fold
+        ? { ...rest, reach: combined_multiply_reach(before.words, after.words) }
+        : rest;
+
+    for (const environment of environments) {
+        const difference = diff_particle_section_result(
+            run_particle_section({ ...before, environment }),
+            run_particle_section({ ...after, environment }),
+            resolved
+        );
+
+        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_sections}, 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,43 @@
+/**
+ * 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: () => number, { body_length, halt, tagged, register_slots, }?: {
+    body_length?: number;
+    halt?: boolean;
+    tagged?: boolean;
+    register_slots?: number;
+}): ParticleProgram;
+/**
+ * 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: () => number, { groups }?: {
+    groups?: number;
+}): 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":"AAkDA;;;;;;;;;;;;;GAaG;AACH,oDAXuB,MAAM;IAED,WAAW,GAA5B,MAAM;IACY,IAAI,GAAtB,OAAO;IACW,MAAM,GAAxB,OAAO;IACU,cAAc,GAA/B,MAAM;oBAqHhB;AA8ED;;;;;;;;;;;;;;;;;;GAkBG;AACH,yDALuB,MAAM;IAED,MAAM,GAAvB,MAAM;oBAmEhB"}