@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -0,0 +1,764 @@
+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;
+            }
+        }
+    }
+}