@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -1,647 +1,764 @@
-import { CSRGraph } from "../../../../core/graph/csr/CSRGraph.js";
-import { PARTICLE_VM_REGISTER_SLOTS } from "../ParticleConstants.js";
-import {
-    VM_DEST,
-    VM_ISA,
-    VM_OP,
-    VM_OPERAND,
-    vm_decode_op,
-    vm_decode_width,
-    vm_dest_width,
-    vm_operation_width,
-    vm_visit_register_operands,
-} from "../isa/ParticleVMISA.js";
-import { vm_semantics_of, vm_trim_swizzle, vm_trimmed_swizzle_span } from "./particle_vm_semantics.js";
-
-/**
- * The analysis every optimizer pass reads: instructions decoded into the operand runs they touch,
- * the def-use graph over those runs, and per-lane liveness.
- *
- * Everything here is derived, never authoritative — the instruction words are. A pass rewrites
- * words and the next one re-derives, which is why there is no incremental update path and no
- * mutation of an analysis in place: the programs are at most
- * {@link ../ParticleConstants.js PARTICLE_VM_MAX_INSTRUCTIONS} instructions over
- * {@link PARTICLE_VM_REGISTER_SLOTS} slots, and re-deriving all of it is cheaper than keeping it
- * honest.
- *
- * ## Lanes, not registers
- *
- * A register is one `f32` slot and an operand of width `w` is a RUN of `w` of them, so nothing here
- * is per-register: a value's producer is per (instruction, lane), and so is its liveness. The rules
- * for how far an operand reaches are irregular — reductions write one lane, `SCALE` and `CURVE`
- * have a scalar source, a `SWIZZLE` reads as far as its pattern names, `STORE_ATTR` and `KILL` keep
- * a *source* in the destination slot — and they are not restated here:
- * {@link vm_visit_register_operands} is the one place that knows them.
- */
-
-/**
- * @typedef {object} ParticleOperandRun
- * @property {number} operand which operand this is: `-1` for the source that `STORE_ATTR` and
- *   `KILL` keep in the destination slot, otherwise the source slot `0..2`.
- * @property {number} base first register slot
- * @property {number} span consecutive slots the operand reaches
- */
-
-/**
- * @typedef {object} ParticleDecodedInstruction
- * @property {number} index position in the stream
- * @property {number[]} words the five instruction words
- * @property {number} op
- * @property {number} width the encoded width field
- * @property {number} operation_width lanes the operation spans, after the ISA's fixed-width rules
- * @property {object} meta the {@link VM_ISA} entry
- * @property {import("./particle_vm_semantics.js").ParticleOpSemantics} semantics
- * @property {ParticleOperandRun|null} write destination run, or null when the opcode writes nothing
- * @property {ParticleOperandRun[]} reads every register run the instruction reads
- */
-
-/**
- * Decode one instruction into the runs of register slots it reads and writes.
- *
- * @param {ArrayLike<number>} words the five words of a single instruction
- * @param {number} [index]
- * @returns {ParticleDecodedInstruction}
- */
-export function decode_particle_instruction(words, index = 0) {
-    const word0 = words[0];
-    const op = vm_decode_op(word0);
-    const width = vm_decode_width(word0);
-    const meta = VM_ISA.get(op);
-
-    if (meta === undefined) {
-        throw new Error(`particle optimizer: unknown opcode ${op} at instruction ${index}`);
-    }
-
-    // The visitor yields the destination slot first (when the opcode uses one) and then the REG
-    // source slots in order, which is what lets the runs be matched back up to operand positions
-    // without restating how far any of them reaches.
-    /** @type {Array<{base: number, span: number}>} */
-    const visited = [];
-
-    vm_visit_register_operands(words, 0, (base, span) => visited.push({ base, span }));
-
-    /** @type {number[]} source slots that carry a register, in the order the visitor yields them */
-    const register_slots = [];
-
-    for (let slot = 0; slot < 3; slot++) {
-        if (meta.operands[slot] === VM_OPERAND.REG) {
-            register_slots.push(slot);
-        }
-    }
-
-    let cursor = 0;
-    let write = null;
-    /** @type {ParticleOperandRun[]} */
-    const reads = [];
-
-    if (meta.dst) {
-        const run = visited[cursor++];
-
-        if (meta.dest === VM_DEST.NONE) {
-            // STORE_ATTR and KILL: the destination slot holds a source, and the run is what it reads.
-            reads.push({ operand: -1, base: run.base, span: run.span });
-        } else {
-            write = { operand: -1, base: run.base, span: run.span };
-        }
-    }
-
-    for (const slot of register_slots) {
-        const run = visited[cursor++];
-
-        reads.push({ operand: slot, base: run.base, span: run.span });
-    }
-
-    return {
-        index,
-        words: [words[0], words[1], words[2], words[3], words[4]],
-        op,
-        width,
-        operation_width: vm_operation_width(op, width),
-        meta,
-        semantics: vm_semantics_of(op),
-        write,
-        reads,
-    };
-}
-
-/**
- * @param {ArrayLike<ArrayLike<number>>} instructions five-word tuples
- * @returns {ParticleDecodedInstruction[]}
- */
-export function decode_particle_instructions(instructions) {
-    const out = new Array(instructions.length);
-
-    for (let i = 0; i < instructions.length; i++) {
-        out[i] = decode_particle_instruction(instructions[i], i);
-    }
-
-    return out;
-}
-
-/**
- * Whether an instruction's operands satisfy the rule {@link ../isa/ParticleProgram.js} enforces:
- * two runs of one instruction name the same slots or disjoint ones, never a partial overlap.
- *
- * Every executor reads slot `c` of a source to write slot `c` of the destination, so an exact alias
- * is fine and a shifted one would read slots the same instruction has already written. A pass that
- * moves a base or changes a width can turn a legal pair into an illegal one, so each of them checks
- * its candidate here before keeping it — cheaper than discovering it in `validate()` downstream, and
- * it keeps the rule stated once.
- *
- * @param {ArrayLike<number>} words the five words of a single instruction
- * @returns {boolean}
- */
-export function particle_instruction_is_well_formed(words) {
-    const decoded = decode_particle_instruction(words);
-    /** @type {ParticleOperandRun[]} */
-    const runs = decoded.write === null ? decoded.reads : [decoded.write, ...decoded.reads];
-
-    for (const run of runs) {
-        if (run.base < 0 || run.base + run.span > PARTICLE_VM_REGISTER_SLOTS) {
-            return false;
-        }
-    }
-
-    for (let a = 0; a < runs.length; a++) {
-        for (let b = a + 1; b < runs.length; b++) {
-            const x = runs[a];
-            const y = runs[b];
-
-            if (x.base < y.base + y.span && y.base < x.base + x.span && x.base !== y.base) {
-                return false;
-            }
-        }
-    }
-
-    return true;
-}
-
-/**
- * Def-use over the instruction stream: an edge `i -> j` says instruction `j` reads a slot
- * instruction `i` last wrote.
- *
- * Straight-line code with no control flow, so "last wrote" is exact rather than a may-reach
- * approximation: one forward scan of a slot-indexed table finds every producer. The result is a
- * {@link CSRGraph} because that is what the rest of the engine walks — `edge_addresses` /
- * `adjacency` directly, without a per-vertex closure — and because dead-code elimination is then a
- * reachability question over it rather than a bespoke container.
- *
- * A read of a slot nothing has written yet has no producer and contributes no edge: the register
- * file starts zeroed on both executors, so such a read is a constant, not a dependency.
- *
- * @param {ParticleDecodedInstruction[]} decoded
- * @param {number} [register_slots]
- * @returns {CSRGraph} vertices are instructions; vertex `i`'s adjacency lists its consumers
- */
-export function build_particle_def_use_graph(decoded, register_slots = PARTICLE_VM_REGISTER_SLOTS) {
-    const count = decoded.length;
-    const degree = new Uint32Array(count + 1);
-    /** @type {number[][]} consumer lists, gathered before the CSR is sized */
-    const edges = [];
-
-    const producer = new Int32Array(register_slots).fill(-1);
-
-    for (let i = 0; i < count; i++) {
-        const instruction = decoded[i];
-        /** @type {Set<number>} one edge per producing instruction, however many lanes it feeds */
-        const sources = new Set();
-
-        for (const read of instruction.reads) {
-            for (let lane = 0; lane < read.span; lane++) {
-                const slot = read.base + lane;
-                const from = slot < register_slots ? producer[slot] : -1;
-
-                if (from >= 0) {
-                    sources.add(from);
-                }
-            }
-        }
-
-        for (const from of sources) {
-            edges.push([from, i]);
-            degree[from]++;
-        }
-
-        if (instruction.write !== null) {
-            for (let lane = 0; lane < instruction.write.span; lane++) {
-                const slot = instruction.write.base + lane;
-
-                if (slot < register_slots) {
-                    producer[slot] = i;
-                }
-            }
-        }
-    }
-
-    const graph = new CSRGraph(count, edges.length);
-    const addresses = graph.edge_addresses;
-
-    for (let i = 0; i < count; i++) {
-        addresses[i + 1] = addresses[i] + degree[i];
-    }
-
-    const cursor = addresses.slice(0, count);
-
-    for (const [from, to] of edges) {
-        graph.adjacency[cursor[from]++] = to;
-    }
-
-    graph.edge_weights.fill(1);
-
-    return graph;
-}
-
-/**
- * @typedef {object} ParticleLaneAnalysis
- * @property {Uint8Array} keep per instruction: whether it has to survive — it runs, and either it
- *   has an effect beyond its destination or something reads a lane it writes
- * @property {Int32Array} width per instruction: the width field it could carry, once the lanes
- *   nothing reads are dropped. Equal to the encoded one wherever narrowing is not allowed.
- * @property {Int32Array} pattern per instruction: the swizzle pattern at that width; the encoded
- *   one for every other opcode.
- * @property {Uint8Array} live_lanes per instruction: bitmask of destination lanes read later
- * @property {number} halt_index index of the first `HALT`, or `-1`
- */
-
-/**
- * Backward per-lane liveness: which lanes of each instruction's destination anything downstream
- * actually reads, and therefore how narrow the instruction could be and whether it is needed at all.
- *
- * Registers do not outlive a section — both executors start a particle with a zeroed file — so the
- * walk starts with nothing live and everything a program means has already been written to the
- * record, the kill flag or the RNG by the time it ends.
- *
- * Narrowing is decided inside the same backward pass rather than after it, because an instruction's
- * reads follow its width: narrowing a broadcast to two lanes shortens the run it reads, which is
- * what makes the value above it dead. Deciding both at once reaches that fixed point in one sweep.
- *
- * @param {ParticleDecodedInstruction[]} decoded
- * @param {number} [register_slots]
- * @returns {ParticleLaneAnalysis}
- */
-export function analyze_particle_lanes(decoded, register_slots = PARTICLE_VM_REGISTER_SLOTS) {
-    const count = decoded.length;
-    const keep = new Uint8Array(count);
-    const width = new Int32Array(count);
-    const pattern = new Int32Array(count);
-    const live_lanes = new Uint8Array(count);
-
-    let halt_index = -1;
-
-    for (let i = 0; i < count; i++) {
-        width[i] = decoded[i].width;
-        pattern[i] = decoded[i].words[3];
-
-        if (halt_index < 0 && decoded[i].op === VM_OP.HALT) {
-            halt_index = i;
-        }
-    }
-
-    // A HALT returns, so nothing past the first one runs — and nothing past it can make a value live.
-    const last = halt_index >= 0 ? halt_index : count - 1;
-    const live = new Uint8Array(register_slots);
-
-    for (let i = last; i >= 0; i--) {
-        const instruction = decoded[i];
-        const semantics = instruction.semantics;
-
-        let mask = 0;
-        let highest_live = -1;
-
-        if (instruction.write !== null) {
-            for (let lane = 0; lane < instruction.write.span; lane++) {
-                if (live[instruction.write.base + lane]) {
-                    mask |= 1 << lane;
-                    highest_live = lane;
-                }
-            }
-        }
-
-        live_lanes[i] = mask;
-
-        if (!semantics.side_effects && highest_live < 0) {
-            continue;
-        }
-
-        keep[i] = 1;
-
-        // Only the lanes below the highest live one have to be computed. Lanes are a contiguous run
-        // from zero, so a live lane 2 holds the width at 3 however dead lanes 0 and 1 are.
-        if (
-            semantics.narrowable
-            && highest_live >= 0
-            && instruction.write !== null
-            && instruction.write.span === instruction.operation_width
-        ) {
-            width[i] = Math.max(highest_live + 1, instruction.meta.min_width);
-        }
-
-        const operation_width = vm_operation_width(instruction.op, width[i]);
-
-        if (instruction.op === VM_OP.SWIZZLE) {
-            pattern[i] = vm_trim_swizzle(instruction.words[3], operation_width);
-        }
-
-        if (instruction.write !== null) {
-            const span = vm_dest_width(instruction.op, width[i]);
-
-            for (let lane = 0; lane < span; lane++) {
-                live[instruction.write.base + lane] = 0;
-            }
-        }
-
-        for (const read of instruction.reads) {
-            const span = read_span_at(instruction, read, operation_width, pattern[i]);
-
-            for (let lane = 0; lane < span; lane++) {
-                live[read.base + lane] = 1;
-            }
-        }
-    }
-
-    return { keep, width, pattern, live_lanes, halt_index };
-}
-
-/**
- * How far a read reaches once the instruction is narrowed to `operation_width`.
- *
- * @param {ParticleDecodedInstruction} instruction
- * @param {ParticleOperandRun} read
- * @param {number} operation_width
- * @param {number} pattern the (possibly trimmed) swizzle pattern
- * @returns {number}
- */
-export function read_span_at(instruction, read, operation_width, pattern) {
-    if (instruction.op === VM_OP.SWIZZLE && read.operand === 0) {
-        return vm_trimmed_swizzle_span(pattern, operation_width);
-    }
-
-    if (read.operand >= 0 && instruction.meta.scalar_operands.includes(read.operand)) {
-        return 1;
-    }
-
-    return operation_width;
-}
-
-/**
- * @param {number} base_a
- * @param {number} span_a
- * @param {number} base_b
- * @param {number} span_b
- * @returns {boolean} whether the two runs share a slot
- */
-export function particle_runs_overlap(base_a, span_a, base_b, span_b) {
-    return base_a < base_b + span_b && base_b < base_a + span_a;
-}
-
-/**
- * Whether anything in `[from, to)` reads or writes any slot of a run.
- *
- * What a pass moving an instruction has to ask: a value that nothing in the gap looks at or
- * disturbs can be produced anywhere in that gap.
- *
- * @param {ParticleDecodedInstruction[]} decoded
- * @param {number} from inclusive
- * @param {number} to exclusive
- * @param {number} base
- * @param {number} span
- * @returns {boolean}
- */
-export function particle_run_is_touched_between(decoded, from, to, base, span) {
-    for (let i = from; i < to; i++) {
-        const instruction = decoded[i];
-
-        if (instruction.write !== null
-            && particle_runs_overlap(instruction.write.base, instruction.write.span, base, span)) {
-            return true;
-        }
-
-        for (const read of instruction.reads) {
-            if (particle_runs_overlap(read.base, read.span, base, span)) {
-                return true;
-            }
-        }
-    }
-
-    return false;
-}
-
-/**
- * Whether every slot of a run is overwritten — or the section ends — before anything reads it again.
- *
- * A run that is dead from `index` onwards belongs to nobody, so the instruction that filled it may
- * be retargeted, folded into its consumer, or dropped.
- *
- * @param {ParticleDecodedInstruction[]} decoded
- * @param {number} index the instruction after which to look
- * @param {number} base
- * @param {number} span
- * @returns {boolean}
- */
-export function particle_run_is_dead_after(decoded, index, base, span) {
-    const pending = new Set();
-
-    for (let lane = 0; lane < span; lane++) {
-        pending.add(base + lane);
-    }
-
-    for (let i = index + 1; i < decoded.length && pending.size > 0; i++) {
-        const instruction = decoded[i];
-
-        // Nothing past a HALT runs, so nothing past it can want the value.
-        if (instruction.op === VM_OP.HALT) {
-            return true;
-        }
-
-        for (const read of instruction.reads) {
-            for (let lane = 0; lane < read.span; lane++) {
-                if (pending.has(read.base + lane)) {
-                    return false;
-                }
-            }
-        }
-
-        if (instruction.write !== null) {
-            for (let lane = 0; lane < instruction.write.span; lane++) {
-                pending.delete(instruction.write.base + lane);
-            }
-        }
-    }
-
-    return true;
-}
-
-/**
- * Which value each register slot holds, as a number, and where that value was first computed.
- *
- * Two passes ask questions that turn out to be the same question underneath. "Is this register still
- * the copy it was?" and "has this expression already been evaluated?" both reduce to comparing value
- * numbers, and both need a copy to carry its source's number across rather than minting a new one —
- * otherwise a value moved between registers stops being recognisable as itself.
- *
- * Numbers are minted per write and inherited by `MOV` and `SWIZZLE`, the only two opcodes that move
- * a value without changing it. Because a number is never reused, a slot overwritten since simply
- * fails to match, and there is no invalidation step to get wrong.
- */
-export class ParticleValueNumbering {
-    /**
-     * @param {number} [slots]
-     */
-    constructor(slots = PARTICLE_VM_REGISTER_SLOTS) {
-        /** @type {number} */
-        this.slots = slots;
-        /** @type {Int32Array} the value in each slot */
-        this.value_id = new Int32Array(slots);
-        /** @type {Int32Array} the slot each value was first computed in */
-        this.home = new Int32Array(slots);
-        /** @type {number} */
-        this.next_id = slots;
-
-        // The file starts zeroed on both executors, but every slot is given a DISTINCT number: they
-        // hold equal values, not the same value, and nothing is gained by conflating them.
-        for (let slot = 0; slot < slots; slot++) {
-            this.value_id[slot] = slot;
-            this.home[slot] = slot;
-        }
-    }
-
-    /**
-     * @param {number} base
-     * @param {number} span
-     * @returns {number[]|null} the numbers in that run, or `null` if it leaves the file
-     */
-    ids_of(base, span) {
-        if (base < 0 || base + span > this.slots) {
-            return null;
-        }
-
-        const ids = new Array(span);
-
-        for (let lane = 0; lane < span; lane++) {
-            ids[lane] = this.value_id[base + lane];
-        }
-
-        return ids;
-    }
-
-    /**
-     * @param {number} base
-     * @param {number[]} ids
-     * @returns {boolean} whether that run still holds exactly those values
-     */
-    holds(base, ids) {
-        if (base < 0 || base + ids.length > this.slots) {
-            return false;
-        }
-
-        for (let lane = 0; lane < ids.length; lane++) {
-            if (this.value_id[base + lane] !== ids[lane]) {
-                return false;
-            }
-        }
-
-        return true;
-    }
-
-    /**
-     * Where the values in a run were originally computed, when that is itself a run and still holds
-     * them.
-     *
-     * Two lanes of a broadcast were both computed in the same slot, which is not a run — so a
-     * broadcast as a whole has no origin to be read past, however each of its lanes does.
-     *
-     * @param {number} base
-     * @param {number} span
-     * @returns {number} the origin's base, or `-1`
-     */
-    origin_of(base, span) {
-        if (base < 0 || base + span > this.slots) {
-            return -1;
-        }
-
-        const origin = this.home[base];
-
-        if (origin + span > this.slots) {
-            return -1;
-        }
-
-        for (let lane = 0; lane < span; lane++) {
-            if (this.home[base + lane] !== origin + lane || this.value_id[origin + lane] !== this.value_id[base + lane]) {
-                return -1;
-            }
-        }
-
-        return origin;
-    }
-
-    /**
-     * Record what an instruction leaves in its destination.
-     *
-     * Takes the words as they will be EMITTED rather than as they were read, because a pass may have
-     * moved a source or rewritten the opcode by the time it gets here — the state has to describe
-     * the program that will run.
-     *
-     * @param {ArrayLike<number>} words the five words of a single instruction
-     */
-    publish(words) {
-        const instruction = decode_particle_instruction(words);
-
-        if (instruction.write === null) {
-            return;
-        }
-
-        const base = instruction.write.base;
-        const span = instruction.write.span;
-        const source = words[2];
-
-        /** Gathered before anything is written: the ISA lets a destination alias a source exactly. */
-        const lanes = new Array(span);
-
-        if (instruction.semantics.broadcasts) {
-            // One value in every lane, so lane `i` is a copy of lane 0 and traces back to it — which
-            // is what lets a consumer read the scalar instead of the widened form.
-            const id = this.next_id++;
-
-            lanes.fill({ id, home: base });
-        } else {
-            for (let lane = 0; lane < span; lane++) {
-                const from = carried_lane(instruction.op, words, lane, source);
-
-                lanes[lane] = from >= 0 && from < this.slots
-                    ? { id: this.value_id[from], home: this.home[from] }
-                    : { id: this.next_id++, home: base + lane };
-            }
-        }
-
-        for (let lane = 0; lane < span; lane++) {
-            const slot = base + lane;
-
-            if (slot < this.slots) {
-                this.value_id[slot] = lanes[lane].id;
-                this.home[slot] = lanes[lane].home;
-            }
-        }
-    }
-}
-
-/**
- * The slot an output lane's value is carried across from, for the two opcodes that move a value
- * without changing it. `-1` for everything else, which mints a new value.
- *
- * @param {number} op
- * @param {ArrayLike<number>} words
- * @param {number} lane
- * @param {number} source
- * @returns {number}
- */
-function carried_lane(op, words, lane, source) {
-    if (op === VM_OP.MOV) {
-        return source + lane;
-    }
-
-    if (op === VM_OP.SWIZZLE) {
-        return source + ((words[3] >> (2 * lane)) & 3);
-    }
-
-    return -1;
-}
+import { CSRGraph } from "../../../../core/graph/csr/CSRGraph.js";
+import { PARTICLE_VM_REGISTER_SLOTS } from "../ParticleConstants.js";
+import {
+    VM_ISA,
+    VM_KIND,
+    VM_MAX_WIDTH,
+    VM_OP,
+    VM_SWIZZLE_IDENTITY,
+    swizzle_selector,
+    vm_decode_dst,
+    vm_decode_kinds,
+    vm_decode_op,
+    vm_decode_width,
+    vm_dest_width,
+    vm_kinds_problem,
+    vm_operand_base,
+    vm_operand_pattern,
+    vm_operand_slot,
+    vm_operation_width,
+    vm_register,
+    vm_visit_operands,
+} from "../isa/ParticleVMISA.js";
+import { vm_semantics_of } from "./particle_vm_semantics.js";
+
+/**
+ * The analysis every optimizer pass reads: instructions decoded into the operands they resolve and
+ * the run they write, the def-use graph over those, and per-lane liveness.
+ *
+ * Everything here is derived, never authoritative — the instruction words are. A pass rewrites
+ * words and the next one re-derives, which is why there is no incremental update path and no
+ * mutation of an analysis in place: the programs are at most
+ * {@link ../ParticleConstants.js PARTICLE_VM_MAX_INSTRUCTIONS} instructions over
+ * {@link PARTICLE_VM_REGISTER_SLOTS} slots, and re-deriving all of it is cheaper than keeping it
+ * honest.
+ *
+ * ## Lanes, not registers
+ *
+ * A register is one `f32` slot and a value of width `w` is a run of `w` of them, so nothing here is
+ * per-register: a value's producer is per (instruction, lane), and so is its liveness. Which slots a
+ * source reads is the operand's own business — its base and its swizzle, read at as many lanes as the
+ * opcode takes of it — and {@link particle_read_slots} is the one place that turns an operand into
+ * slots. The ISA's {@link vm_visit_operands} is the one place that says how many lanes that is.
+ *
+ * ## Kinds
+ *
+ * A source is a register run or a literal, by the kind bits its instruction carries. Only the first
+ * is a run of the file, so `reads` holds only those — every question about liveness, aliasing and
+ * dependency is a question about the file, and a literal whose bits happen to look like a slot index
+ * must never answer it. The passes that care what a source *is* rather than where it lives — folding,
+ * sharing, the copy rewrites — read `sources`, which lists every operand with its kind.
+ */
+
+/**
+ * @typedef {object} ParticleOperandRun
+ * @property {number} operand which source slot this is, `0..2`; `-1` for the destination
+ * @property {number} kind a `VM_KIND`; `REG` for every entry of `reads` and for the write
+ * @property {number} word the operand word as encoded
+ * @property {number} base first register slot, or `-1` for a literal
+ * @property {number} pattern the swizzle the operand reads through, as `pack_swizzle` packs one; the
+ *   identity for a write
+ * @property {number} lanes how many lanes the instruction reads of it — the operation's width, or one
+ *   for a slot the ISA marks scalar; for the write, how many it writes
+ * @property {number} span consecutive slots the operand reaches from its base
+ */
+
+/**
+ * @typedef {object} ParticleDecodedInstruction
+ * @property {number} index position in the stream
+ * @property {number[]} words the four instruction words
+ * @property {number} op
+ * @property {number} width the encoded width field
+ * @property {number} dst the encoded destination register
+ * @property {number} kinds the three source kinds as one field, as word 0 carries them
+ * @property {number} operation_width lanes the operation spans, after the ISA's fixed-width rules
+ * @property {object} meta the {@link VM_ISA} entry
+ * @property {import("./particle_vm_semantics.js").ParticleOpSemantics} semantics
+ * @property {ParticleOperandRun|null} write destination run, or null when the opcode writes nothing
+ * @property {ParticleOperandRun[]} reads every register operand the instruction reads — the `REG` sources
+ * @property {ParticleOperandRun[]} sources every source operand, whatever its kind, in slot order
+ */
+
+/**
+ * Decode one instruction into the operands it resolves and the run it writes.
+ *
+ * @param {ArrayLike<number>} words the four words of a single instruction
+ * @param {number} [index]
+ * @returns {ParticleDecodedInstruction}
+ */
+export function decode_particle_instruction(words, index = 0) {
+    const word0 = words[0];
+    const op = vm_decode_op(word0);
+    const width = vm_decode_width(word0);
+    const meta = VM_ISA.get(op);
+
+    if (meta === undefined) {
+        throw new Error(`particle optimizer: unknown opcode ${op} at instruction ${index}`);
+    }
+
+    const dst = vm_decode_dst(word0);
+    const dest = vm_dest_width(op, width);
+
+    /** @type {ParticleOperandRun|null} */
+    const write = dest === 0
+        ? null
+        : { operand: -1, kind: VM_KIND.REG, word: dst, base: dst, pattern: VM_SWIZZLE_IDENTITY, lanes: dest, span: dest };
+
+    /** @type {ParticleOperandRun[]} */
+    const sources = [];
+
+    vm_visit_operands(words, 0, ({ slot, kind, word, lanes, span }) => {
+        sources.push({
+            operand: slot,
+            kind,
+            word,
+            base: kind === VM_KIND.REG ? vm_operand_base(word) : -1,
+            pattern: kind === VM_KIND.REG ? vm_operand_pattern(word) : VM_SWIZZLE_IDENTITY,
+            lanes,
+            span,
+        });
+    });
+
+    return {
+        index,
+        words: [words[0], words[1], words[2], words[3]],
+        op,
+        width,
+        dst,
+        kinds: vm_decode_kinds(word0),
+        operation_width: vm_operation_width(op, width),
+        meta,
+        semantics: vm_semantics_of(op),
+        write,
+        reads: sources.filter(source => source.kind === VM_KIND.REG),
+        sources,
+    };
+}
+
+/**
+ * @param {ArrayLike<ArrayLike<number>>} instructions four-word tuples
+ * @returns {ParticleDecodedInstruction[]}
+ */
+export function decode_particle_instructions(instructions) {
+    const out = new Array(instructions.length);
+
+    for (let i = 0; i < instructions.length; i++) {
+        out[i] = decode_particle_instruction(instructions[i], i);
+    }
+
+    return out;
+}
+
+/**
+ * The slots a register operand reads, one per lane read — in lane order, and a slot appears once per
+ * lane that reads it, so a broadcast lists the same slot several times.
+ *
+ * @param {ParticleOperandRun} read a `REG` run
+ * @param {number} [lanes] how many lanes to read; the operand's own count when left out
+ * @returns {number[]}
+ */
+export function particle_read_slots(read, lanes = read.lanes) {
+    const slots = new Array(lanes);
+
+    for (let lane = 0; lane < lanes; lane++) {
+        slots[lane] = read.base + swizzle_selector(read.pattern, lane);
+    }
+
+    return slots;
+}
+
+/**
+ * Whether an instruction fits the register file: its kinds agree with its opcode, and every run it
+ * touches ends inside the file.
+ *
+ * There is no aliasing rule to check. Every executor resolves every source before it writes the
+ * destination, so a source may overlap the destination in any way and mean what it held before the
+ * instruction — which is also what lets a pass move a base or fold a swizzle without asking how the
+ * result sits against the other operands.
+ *
+ * @param {ArrayLike<number>} words the four words of a single instruction
+ * @returns {boolean}
+ */
+export function particle_instruction_is_well_formed(words) {
+    if (vm_kinds_problem(words, 0) !== null) {
+        return false;
+    }
+
+    const decoded = decode_particle_instruction(words);
+    const runs = decoded.write === null ? decoded.reads : [decoded.write, ...decoded.reads];
+
+    for (const run of runs) {
+        if (run.base < 0 || run.base + run.span > PARTICLE_VM_REGISTER_SLOTS) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Def-use over the instruction stream: an edge `i -> j` says instruction `j` reads a slot
+ * instruction `i` last wrote.
+ *
+ * Straight-line code with no control flow, so "last wrote" is exact rather than a may-reach
+ * approximation: one forward scan of a slot-indexed table finds every producer. The result is a
+ * {@link CSRGraph} because that is what the rest of the engine walks — `edge_addresses` /
+ * `adjacency` directly, without a per-vertex closure — and because dead-code elimination is then a
+ * reachability question over it rather than a bespoke container.
+ *
+ * A read of a slot nothing has written yet has no producer and contributes no edge: the register
+ * file starts zeroed on both executors, so such a read is a constant, not a dependency.
+ *
+ * @param {ParticleDecodedInstruction[]} decoded
+ * @param {number} [register_slots]
+ * @returns {CSRGraph} vertices are instructions; vertex `i`'s adjacency lists its consumers
+ */
+export function build_particle_def_use_graph(decoded, register_slots = PARTICLE_VM_REGISTER_SLOTS) {
+    const count = decoded.length;
+    const degree = new Uint32Array(count + 1);
+    /** @type {number[][]} consumer lists, gathered before the CSR is sized */
+    const edges = [];
+
+    const producer = new Int32Array(register_slots).fill(-1);
+
+    for (let i = 0; i < count; i++) {
+        const instruction = decoded[i];
+        /** @type {Set<number>} one edge per producing instruction, however many lanes it feeds */
+        const sources = new Set();
+
+        for (const read of instruction.reads) {
+            for (const slot of particle_read_slots(read)) {
+                const from = slot < register_slots ? producer[slot] : -1;
+
+                if (from >= 0) {
+                    sources.add(from);
+                }
+            }
+        }
+
+        for (const from of sources) {
+            edges.push([from, i]);
+            degree[from]++;
+        }
+
+        if (instruction.write !== null) {
+            for (let lane = 0; lane < instruction.write.span; lane++) {
+                const slot = instruction.write.base + lane;
+
+                if (slot < register_slots) {
+                    producer[slot] = i;
+                }
+            }
+        }
+    }
+
+    const graph = new CSRGraph(count, edges.length);
+    const addresses = graph.edge_addresses;
+
+    for (let i = 0; i < count; i++) {
+        addresses[i + 1] = addresses[i] + degree[i];
+    }
+
+    const cursor = addresses.slice(0, count);
+
+    for (const [from, to] of edges) {
+        graph.adjacency[cursor[from]++] = to;
+    }
+
+    graph.edge_weights.fill(1);
+
+    return graph;
+}
+
+/**
+ * @typedef {object} ParticleLaneAnalysis
+ * @property {Uint8Array} keep per instruction: whether it has to survive — it runs, and either it
+ *   has an effect beyond its destination or something reads a lane it writes
+ * @property {Int32Array} width per instruction: the width field it could carry, once the lanes
+ *   nothing reads are dropped. Equal to the encoded one wherever narrowing is not allowed.
+ * @property {Uint8Array} live_lanes per instruction: bitmask of destination lanes read later
+ * @property {number} halt_index index of the first `HALT`, or `-1`
+ */
+
+/**
+ * Backward per-lane liveness: which lanes of each instruction's destination anything downstream
+ * actually reads, and therefore how narrow the instruction could be and whether it is needed at all.
+ *
+ * Registers do not outlive a section — both executors start a particle with a zeroed file — so the
+ * walk starts with nothing live and everything a program means has already been written to the
+ * record, the kill flag or the RNG by the time it ends.
+ *
+ * Narrowing is decided inside the same backward pass rather than after it, because an instruction's
+ * reads follow its width: a narrowed copy reads fewer lanes of its source, which is what makes the
+ * value above it dead. Deciding both at once reaches that fixed point in one sweep.
+ *
+ * @param {ParticleDecodedInstruction[]} decoded
+ * @param {number} [register_slots]
+ * @returns {ParticleLaneAnalysis}
+ */
+export function analyze_particle_lanes(decoded, register_slots = PARTICLE_VM_REGISTER_SLOTS) {
+    const count = decoded.length;
+    const keep = new Uint8Array(count);
+    const width = new Int32Array(count);
+    const live_lanes = new Uint8Array(count);
+
+    let halt_index = -1;
+
+    for (let i = 0; i < count; i++) {
+        width[i] = decoded[i].width;
+
+        if (halt_index < 0 && decoded[i].op === VM_OP.HALT) {
+            halt_index = i;
+        }
+    }
+
+    // A HALT returns, so nothing past the first one runs — and nothing past it can make a value live.
+    const last = halt_index >= 0 ? halt_index : count - 1;
+    const live = new Uint8Array(register_slots);
+
+    for (let i = last; i >= 0; i--) {
+        const instruction = decoded[i];
+        const semantics = instruction.semantics;
+
+        let mask = 0;
+        let highest_live = -1;
+
+        if (instruction.write !== null) {
+            for (let lane = 0; lane < instruction.write.span; lane++) {
+                if (live[instruction.write.base + lane]) {
+                    mask |= 1 << lane;
+                    highest_live = lane;
+                }
+            }
+        }
+
+        live_lanes[i] = mask;
+
+        if (!semantics.side_effects && highest_live < 0) {
+            continue;
+        }
+
+        keep[i] = 1;
+
+        // Only the lanes below the highest live one have to be computed. Lanes are a contiguous run
+        // from zero, so a live lane 2 holds the width at 3 however dead lanes 0 and 1 are.
+        if (
+            semantics.narrowable
+            && highest_live >= 0
+            && instruction.write !== null
+            && instruction.write.span === instruction.operation_width
+        ) {
+            width[i] = Math.max(highest_live + 1, instruction.meta.min_width);
+        }
+
+        const operation_width = vm_operation_width(instruction.op, width[i]);
+
+        if (instruction.write !== null) {
+            const span = vm_dest_width(instruction.op, width[i]);
+
+            for (let lane = 0; lane < span; lane++) {
+                live[instruction.write.base + lane] = 0;
+            }
+        }
+
+        for (const read of instruction.reads) {
+            for (const slot of particle_read_slots(read, particle_lanes_read_at(instruction, read, operation_width))) {
+                if (slot < register_slots) {
+                    live[slot] = 1;
+                }
+            }
+        }
+    }
+
+    return { keep, width, live_lanes, halt_index };
+}
+
+/**
+ * The most slots alive at once anywhere in the section — what a perfect allocator would need, and
+ * the one measure of an instruction order the scheduling pass is for.
+ *
+ * A slot is alive between a write and a later read of it; a read at the instruction that overwrites
+ * the slot counts for the value above, since every executor reads its sources before it writes.
+ * `HALT` is not special here: what follows one is dead code, and counting it can only overstate.
+ *
+ * @param {ParticleDecodedInstruction[]} decoded
+ * @param {number} [register_slots]
+ * @returns {number}
+ */
+export function particle_peak_live_slots(decoded, register_slots = PARTICLE_VM_REGISTER_SLOTS) {
+    const live = new Uint8Array(register_slots);
+
+    let alive = 0;
+    let peak = 0;
+
+    for (let i = decoded.length - 1; i >= 0; i--) {
+        const instruction = decoded[i];
+
+        if (instruction.write !== null) {
+            for (let lane = 0; lane < instruction.write.span; lane++) {
+                const slot = instruction.write.base + lane;
+
+                if (slot < register_slots && live[slot]) {
+                    live[slot] = 0;
+                    alive--;
+                }
+            }
+        }
+
+        for (const read of instruction.reads) {
+            for (const slot of particle_read_slots(read)) {
+                if (slot >= 0 && slot < register_slots && !live[slot]) {
+                    live[slot] = 1;
+                    alive++;
+                }
+            }
+        }
+
+        peak = Math.max(peak, alive);
+    }
+
+    return peak;
+}
+
+/**
+ * How many lanes of a source an instruction reads once it is narrowed to `operation_width`: one for a
+ * slot the ISA marks scalar, the width for everything else.
+ *
+ * @param {ParticleDecodedInstruction} instruction
+ * @param {ParticleOperandRun} read
+ * @param {number} operation_width
+ * @returns {number}
+ */
+function particle_lanes_read_at(instruction, read, operation_width) {
+    return instruction.meta.scalar_operands.includes(read.operand) ? 1 : operation_width;
+}
+
+/**
+ * @param {number} base_a
+ * @param {number} span_a
+ * @param {number} base_b
+ * @param {number} span_b
+ * @returns {boolean} whether the two runs share a slot
+ */
+export function particle_runs_overlap(base_a, span_a, base_b, span_b) {
+    return base_a < base_b + span_b && base_b < base_a + span_a;
+}
+
+/**
+ * Whether anything in `[from, to)` reads or writes any slot of a run.
+ *
+ * What a pass moving an instruction has to ask: a value that nothing in the gap looks at or
+ * disturbs can be produced anywhere in that gap. A read is taken at its whole span, which is at
+ * least what it touches.
+ *
+ * @param {ParticleDecodedInstruction[]} decoded
+ * @param {number} from inclusive
+ * @param {number} to exclusive
+ * @param {number} base
+ * @param {number} span
+ * @returns {boolean}
+ */
+export function particle_run_is_touched_between(decoded, from, to, base, span) {
+    for (let i = from; i < to; i++) {
+        const instruction = decoded[i];
+
+        if (instruction.write !== null
+            && particle_runs_overlap(instruction.write.base, instruction.write.span, base, span)) {
+            return true;
+        }
+
+        for (const read of instruction.reads) {
+            if (particle_runs_overlap(read.base, read.span, base, span)) {
+                return true;
+            }
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Whether anything in `[from, to)` writes any slot of a run — the weaker question, for a pass that
+ * needs a value to still be where it was but does not mind who has looked at it in between.
+ *
+ * @param {ParticleDecodedInstruction[]} decoded
+ * @param {number} from inclusive
+ * @param {number} to exclusive
+ * @param {number} base
+ * @param {number} span
+ * @returns {boolean}
+ */
+export function particle_run_is_written_between(decoded, from, to, base, span) {
+    for (let i = from; i < to; i++) {
+        const instruction = decoded[i];
+
+        if (instruction.write !== null
+            && particle_runs_overlap(instruction.write.base, instruction.write.span, base, span)) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Whether every slot of a run is overwritten — or the section ends — before anything reads it again.
+ *
+ * A run that is dead from `index` onwards belongs to nobody, so the instruction that filled it may
+ * be retargeted, folded into its consumer, or dropped.
+ *
+ * @param {ParticleDecodedInstruction[]} decoded
+ * @param {number} index the instruction after which to look
+ * @param {number} base
+ * @param {number} span
+ * @returns {boolean}
+ */
+export function particle_run_is_dead_after(decoded, index, base, span) {
+    const pending = new Set();
+
+    for (let lane = 0; lane < span; lane++) {
+        pending.add(base + lane);
+    }
+
+    for (let i = index + 1; i < decoded.length && pending.size > 0; i++) {
+        const instruction = decoded[i];
+
+        // Nothing past a HALT runs, so nothing past it can want the value.
+        if (instruction.op === VM_OP.HALT) {
+            return true;
+        }
+
+        for (const read of instruction.reads) {
+            for (const slot of particle_read_slots(read)) {
+                if (pending.has(slot)) {
+                    return false;
+                }
+            }
+        }
+
+        if (instruction.write !== null) {
+            for (let lane = 0; lane < instruction.write.span; lane++) {
+                pending.delete(instruction.write.base + lane);
+            }
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Which value each register slot holds, as a number, and where that value was first computed.
+ *
+ * Two passes ask questions that turn out to be the same question underneath. "Is this register still
+ * the copy it was?" and "has this expression already been evaluated?" both reduce to comparing value
+ * numbers, and both need a copy to carry its source's number across rather than minting a new one —
+ * otherwise a value moved between registers stops being recognisable as itself.
+ *
+ * Numbers are minted per write and inherited by `MOV`, the one opcode that moves a value without
+ * changing it — through whatever swizzle its source carries, so a broadcast's lanes all hold one
+ * number and a permutation's hold the source's in the permuted order. Because a number is never
+ * reused, a slot overwritten since simply fails to match, and there is no invalidation step to get
+ * wrong.
+ */
+export class ParticleValueNumbering {
+    /**
+     * @param {number} [slots]
+     */
+    constructor(slots = PARTICLE_VM_REGISTER_SLOTS) {
+        /** @type {number} */
+        this.slots = slots;
+        /** @type {Int32Array} the value in each slot */
+        this.value_id = new Int32Array(slots);
+        /** @type {Int32Array} the slot each value was first computed in */
+        this.home = new Int32Array(slots);
+        /** @type {Int32Array} which publish computed the value in each slot; `-1` for the reset's zero */
+        this.producer = new Int32Array(slots).fill(-1);
+        /** @type {number} */
+        this.next_id = slots;
+        /** @type {number} publishes so far, which is what names a producer */
+        this.published = 0;
+
+        // The file starts zeroed on both executors, but every slot is given a DISTINCT number: they
+        // hold equal values, not the same value, and nothing is gained by conflating them.
+        for (let slot = 0; slot < slots; slot++) {
+            this.value_id[slot] = slot;
+            this.home[slot] = slot;
+        }
+    }
+
+    /**
+     * @param {number} base
+     * @param {number} span
+     * @returns {number[]|null} the numbers in that run, or `null` if it leaves the file
+     */
+    ids_of(base, span) {
+        if (base < 0 || base + span > this.slots) {
+            return null;
+        }
+
+        const ids = new Array(span);
+
+        for (let lane = 0; lane < span; lane++) {
+            ids[lane] = this.value_id[base + lane];
+        }
+
+        return ids;
+    }
+
+    /**
+     * The numbers a register operand reads, one per lane, through its swizzle.
+     *
+     * @param {ParticleOperandRun} read a `REG` run
+     * @returns {number[]|null} `null` if a lane reaches outside the file
+     */
+    ids_read(read) {
+        const slots = particle_read_slots(read);
+
+        if (slots.some(slot => slot < 0 || slot >= this.slots)) {
+            return null;
+        }
+
+        return slots.map(slot => this.value_id[slot]);
+    }
+
+    /**
+     * @param {number} base
+     * @param {number[]} ids
+     * @returns {boolean} whether that run still holds exactly those values
+     */
+    holds(base, ids) {
+        if (base < 0 || base + ids.length > this.slots) {
+            return false;
+        }
+
+        for (let lane = 0; lane < ids.length; lane++) {
+            if (this.value_id[base + lane] !== ids[lane]) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * The register operand that reads the same values from where they were first computed.
+     *
+     * Lane by lane, the value a read sees has a home slot; if every home still holds its value and
+     * the homes fit in the four slots a swizzle can reach from one base, the read can be redirected
+     * there. That is how a copy is read through, a broadcast folds into the consumer's swizzle, and a
+     * value moved between registers stays recognisable as itself.
+     *
+     * Every lane has to come from ONE instruction. Two producers' results side by side could be named
+     * by one swizzled operand too, but folding them there would leave both producers where they are;
+     * forwarding one of them into the copy's slot deletes the copy outright, and that is the rewrite
+     * the copy-propagation pass wants to have the chance to make.
+     *
+     * @param {ParticleOperandRun} read a `REG` run
+     * @returns {number} a register operand word, or `-1` when the values are not all at home, come from
+     *   more than one producer, or their homes do not fit one operand
+     */
+    origin_of_read(read) {
+        const slots = particle_read_slots(read);
+        const homes = new Array(slots.length);
+
+        let low = Infinity;
+        let high = -Infinity;
+        let producer = null;
+
+        for (let lane = 0; lane < slots.length; lane++) {
+            const slot = slots[lane];
+
+            if (slot < 0 || slot >= this.slots) {
+                return -1;
+            }
+
+            const home = this.home[slot];
+
+            if (this.value_id[home] !== this.value_id[slot]) {
+                return -1;
+            }
+
+            if (producer !== null && this.producer[slot] !== producer) {
+                return -1;
+            }
+
+            producer = this.producer[slot];
+            homes[lane] = home;
+            low = Math.min(low, home);
+            high = Math.max(high, home);
+        }
+
+        if (high - low >= VM_MAX_WIDTH) {
+            return -1;
+        }
+
+        let pattern = 0;
+
+        for (let lane = 0; lane < VM_MAX_WIDTH; lane++) {
+            // Lanes past the read are the identity: they are not read, and the canonical spelling
+            // wants them so.
+            const selector = lane < homes.length ? homes[lane] - low : lane;
+
+            pattern |= (selector & 3) << (2 * lane);
+        }
+
+        return vm_register(low, pattern);
+    }
+
+    /**
+     * Record what an instruction leaves in its destination.
+     *
+     * Takes the words as they will be EMITTED rather than as they were read, because a pass may have
+     * moved a source or rewritten the opcode by the time it gets here — the state has to describe
+     * the program that will run.
+     *
+     * @param {ArrayLike<number>} words the four words of a single instruction
+     */
+    publish(words) {
+        const instruction = decode_particle_instruction(words);
+
+        if (instruction.write === null) {
+            return;
+        }
+
+        const base = instruction.write.base;
+        const span = instruction.write.span;
+        const publish = this.published++;
+
+        /** Gathered before anything is written: a source may alias the destination. */
+        const lanes = new Array(span);
+
+        if (instruction.semantics.broadcasts) {
+            // One value in every lane, so lane `i` is a copy of lane 0 and traces back to it — which
+            // is what lets a consumer read the scalar instead of the widened form.
+            const id = this.next_id++;
+
+            lanes.fill({ id, home: base, producer: publish });
+        } else {
+            // A copy carries values only from a REGISTER source. A literal is a value the file never
+            // held, so a MOV from one mints — and its word is not the slot it would otherwise be
+            // read as.
+            const source = instruction.op === VM_OP.MOV && instruction.sources[0].kind === VM_KIND.REG
+                ? instruction.sources[0]
+                : null;
+
+            for (let lane = 0; lane < span; lane++) {
+                const from = source === null ? -1 : vm_operand_slot(source.word, lane);
+
+                lanes[lane] = from >= 0 && from < this.slots
+                    ? { id: this.value_id[from], home: this.home[from], producer: this.producer[from] }
+                    : { id: this.next_id++, home: base + lane, producer: publish };
+            }
+        }
+
+        for (let lane = 0; lane < span; lane++) {
+            const slot = base + lane;
+
+            if (slot < this.slots) {
+                this.value_id[slot] = lanes[lane].id;
+                this.home[slot] = lanes[lane].home;
+                this.producer[slot] = lanes[lane].producer;
+            }
+        }
+    }
+}