@woosh/meep-engine 3.16.0 → 3.17.1

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

@@ -1,213 +1,376 @@
-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;
-}
+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;
+}