@woosh/meep-engine 3.15.0 → 3.17.0

package/src/shade/renderer/particles/isa/validate_particle_program.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Validate a program's structural invariants (opcodes known, operand kinds consistent with the
+ * opcode, register runs in range, instruction budget, constant references in range). Throws on the
+ * first problem. Intended for tests and asset ingestion, not the hot path.
+ *
+ * @param {import("./ParticleProgram.js").ParticleProgram} program
+ */
+export function validate_particle_program(program: import("./ParticleProgram.js").ParticleProgram): void;
+//# sourceMappingURL=validate_particle_program.d.ts.map

package/src/shade/renderer/particles/isa/validate_particle_program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate_particle_program.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/validate_particle_program.js"],"names":[],"mappings":"AAkBA;;;;;;GAMG;AACH,mDAFW,OAAO,sBAAsB,EAAE,eAAe,QAWxD"}

package/src/shade/renderer/particles/isa/validate_particle_program.js

@@ -0,0 +1,128 @@
+import { assert } from "../../../../core/assert.js";
+import {
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_VM_INSTRUCTION_WORDS,
+    PARTICLE_VM_MAX_INSTRUCTIONS,
+} from "../ParticleConstants.js";
+import {
+    VM_ISA,
+    VM_MAX_WIDTH,
+    VM_OP,
+    VM_WIDTH,
+    vm_decode_op,
+    vm_decode_width,
+    vm_kinds_problem,
+    vm_operation_width,
+    vm_visit_register_runs,
+} from "./ParticleVMISA.js";
+
+/**
+ * Validate a program's structural invariants (opcodes known, operand kinds consistent with the
+ * opcode, register runs in range, instruction budget, constant references in range). Throws on the
+ * first problem. Intended for tests and asset ingestion, not the hot path.
+ *
+ * @param {import("./ParticleProgram.js").ParticleProgram} program
+ */
+export function validate_particle_program(program) {
+    const constant_word_count = program.constant_word_count;
+    const register_count = program.register_count;
+
+    validate_stream(program.init, "init", constant_word_count, register_count);
+    validate_stream(program.update, "update", constant_word_count, register_count);
+
+    assert.lessThanOrEqual(program.init_instruction_count, PARTICLE_VM_MAX_INSTRUCTIONS, "init exceeds instruction budget");
+    assert.lessThanOrEqual(program.update_instruction_count, PARTICLE_VM_MAX_INSTRUCTIONS, "update exceeds instruction budget");
+}
+
+/**
+ * There is no aliasing rule between an instruction's operands: the interpreter reads every source
+ * lane before it writes any destination lane, so a source may overlap the destination in any way
+ * and mean what it says.
+ *
+ * @param {Uint32Array} words
+ * @param {string} label
+ * @param {number} constant_word_count
+ * @param {number} register_count
+ */
+function validate_stream(words, label, constant_word_count, register_count) {
+    const instruction_count = words.length / PARTICLE_VM_INSTRUCTION_WORDS;
+
+    for (let i = 0; i < instruction_count; i++) {
+        const base = i * PARTICLE_VM_INSTRUCTION_WORDS;
+        const word0 = words[base];
+        const op = vm_decode_op(word0);
+        const width = vm_decode_width(word0);
+        const meta = VM_ISA.get(op);
+
+        if (meta === undefined) {
+            throw new Error(`${label}[${i}]: unknown opcode ${op}`);
+        }
+
+        if (meta.width !== VM_WIDTH.NONE) {
+            assert.greaterThanOrEqual(
+                width,
+                meta.min_width,
+                `${label}[${i}] (${meta.name}): width must be >= ${meta.min_width}`
+            );
+            assert.lessThanOrEqual(width, VM_MAX_WIDTH, `${label}[${i}] (${meta.name}): width must be <= ${VM_MAX_WIDTH}`);
+        }
+
+        const kinds_problem = vm_kinds_problem(words, base);
+
+        if (kinds_problem !== null) {
+            throw new Error(`${label}[${i}] (${meta.name}): ${kinds_problem}`);
+        }
+
+        // Every register operand names a RUN of slots, and a run that overshoots the file reads
+        // whatever the next value holds rather than failing — so the bound is on its end.
+        vm_visit_register_runs(words, base, (slot, span) => {
+            assert.lessThanOrEqual(
+                slot + span,
+                register_count,
+                `${label}[${i}] (${meta.name}): register range [${slot}, ${slot + span}) exceeds the `
+                + `${register_count}-slot register file`
+            );
+        });
+
+        const operation_width = vm_operation_width(op, width);
+
+        if (op === VM_OP.LOAD_CONST) {
+            // The load reads one word per lane, so the whole run has to be inside the pool.
+            const first = words[base + 1];
+
+            assert.lessThanOrEqual(
+                first + operation_width,
+                constant_word_count,
+                `${label}[${i}] (LOAD_CONST): words [${first}, ${first + operation_width}) exceed the `
+                + `${constant_word_count}-word constant pool`
+            );
+        }
+
+        // Attribute accesses must stay inside one record. An out-of-range offset is NOT caught by
+        // GPU robustness — record_base + offset lands inside the pool buffer, silently reading or
+        // corrupting the NEXT PARTICLE'S record.
+        if (op === VM_OP.LOAD_ATTR || op === VM_OP.STORE_ATTR) {
+            const first = op === VM_OP.LOAD_ATTR ? 1 : 2;
+            const offset = words[base + first];
+            const components = words[base + first + 1];
+
+            assert.greaterThanOrEqual(components, 1, `${label}[${i}] (${meta.name}): component count must be >= 1`);
+            assert.lessThanOrEqual(components, 4, `${label}[${i}] (${meta.name}): component count must be <= 4`);
+            assert.lessThanOrEqual(
+                offset + components,
+                PARTICLE_RECORD_WORD_COUNT,
+                `${label}[${i}] (${meta.name}): attribute access [${offset}, ${offset + components}) exceeds the ${PARTICLE_RECORD_WORD_COUNT}-word record`
+            );
+
+            // A store writes one record word per lane, so it cannot be asked for more words than
+            // the value holds — the extra ones would come out of the next value.
+            if (op === VM_OP.STORE_ATTR) {
+                assert.equal(
+                    width,
+                    components,
+                    `${label}[${i}] (STORE_ATTR): width ${width} must equal the component count ${components}`
+                );
+            }
+        }
+    }
+}

package/src/shade/renderer/particles/layout/ParticleLayout.d.ts

@@ -8,22 +8,44 @@
  * size, colour, …) via a separate render binding. Word 0 of every record is reserved for the owning
  * emitter index; user attributes are packed sequentially from
  * {@link PARTICLE_RECORD_USER_WORD_START}.
+ *
+ * ## The `type` tag
+ *
+ * An attribute may also say what its words are *for*: four of them tagged `color` are a colour
+ * rather than four numbers that happen to be four. It changes nothing here — the offset, the width
+ * and every instruction that touches the attribute are exactly what they were without it — and is
+ * read by the authoring layer, where {@link ../graph/ParticleValueType.js particle_semantic_type}
+ * turns the tag into a type that an editor can offer a swatch for and colour a wire by.
+ *
+ * A plain string rather than a type object, because the runtime schema has no business importing a
+ * frontend's vocabulary, and an effect saved with a tag this build has never heard of has to load
+ * as the plain vector it is instead of failing.
  */
 export class ParticleLayout {
     /**
-     * @param {Array<{name: string, components: number}>} attributes ordered attribute declarations
+     * @param {Array<{name: string, components: number, type?: string}>} attributes ordered
+     *   attribute declarations. `type` optionally says what the words are *for* — see the note on
+     *   {@link #attributes} — and never what shape they are, which is `components` and only that.
      */
     constructor(attributes: Array<{
         name: string;
         components: number;
+        type?: string;
     }>);
-    /** @type {Map<string, {name: string, offset: number, components: number}>} */
+    /**
+     * Attribute name -> where it sits in a particle record, how wide it is, and what it is for.
+     * @type {Map<string, {name: string, offset: number, components: number, type: string|undefined}>}
+     */
     attributes: Map<string, {
         name: string;
         offset: number;
         components: number;
+        type: string | undefined;
     }>;
-    /** @type {number} first free word after all attributes */
+    /**
+     * First free word after all attributes.
+     * @type {number}
+     */
     word_cursor: number;
     /**
      * @param {string} name
@@ -49,5 +71,28 @@ export class ParticleLayout {
      * @returns {number} component count of the attribute
      */
     componentsOf(name: string): number;
+    /**
+     * Structural equality: the same attributes, by name, at the same offsets, the same width, and
+     * tagged the same. Two layouts that compare equal describe one particle record — a program
+     * compiled against either reads and writes the same words.
+     *
+     * Declaration order is not compared separately because it cannot differ without an offset
+     * differing: attributes are packed sequentially in the order they were declared.
+     *
+     * @param {ParticleLayout} other
+     * @returns {boolean}
+     */
+    equals(other: ParticleLayout): boolean;
+    /**
+     * Hash over everything {@link ParticleLayout#equals} compares.
+     *
+     * Per-attribute hashes are summed rather than folded in iteration order. A `Map` iterates in
+     * insertion order and equal layouts are built in the same order, so a fold would agree — but a
+     * commutative combine says outright that the hash is of a set of attributes, and holds even if
+     * a layout is ever built by some other route.
+     *
+     * @returns {number} int32
+     */
+    hash(): number;
 }
 //# sourceMappingURL=ParticleLayout.d.ts.map

package/src/shade/renderer/particles/layout/ParticleLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleLayout.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/layout/ParticleLayout.js"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH;IACI;;OAEG;IACH,wBAFW,MAAM;QAAC,MAAM,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,EAsCnD;IAjCG,8EAA8E;IAC9E,YADW,IAAI,MAAM,EAAE;QAAC,MAAM,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAC/C;IAuB3B,0DAA0D;IAC1D,aADW,MAAM,CACQ;IAU7B;;;OAGG;IACH,UAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,UAHW,MAAM,GACJ;QAAC,MAAM,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAQ9D;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}
+{"version":3,"file":"ParticleLayout.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/layout/ParticleLayout.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAcI;;;;OAIG;IACH,wBAJW,MAAM;QAAC,MAAM,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,EAyClE;IAtDD;;;OAGG;IACH,YAFU,IAAI,MAAM,EAAE;QAAC,MAAM,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAC,SAAS,CAAA;KAAC,CAAC,CAE1E;IAEvB;;;OAGG;IACH,aAFU,MAAM,CAE8B;IA8C9C;;;OAGG;IACH,UAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,UAHW,MAAM,GACJ;QAAC,MAAM,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAQ9D;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;OAUG;IACH,cAHW,cAAc,GACZ,OAAO,CA8BnB;IAED;;;;;;;;;OASG;IACH,QAFa,MAAM,CAclB;CACJ"}

package/src/shade/renderer/particles/layout/ParticleLayout.js

@@ -1,4 +1,7 @@
 import { assert } from "../../../../core/assert.js";
+import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
+import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
+import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
 import {
     PARTICLE_RECORD_USER_WORD_START,
     PARTICLE_RECORD_WORD_COUNT,
@@ -14,17 +17,41 @@ import {
  * size, colour, …) via a separate render binding. Word 0 of every record is reserved for the owning
  * emitter index; user attributes are packed sequentially from
  * {@link PARTICLE_RECORD_USER_WORD_START}.
+ *
+ * ## The `type` tag
+ *
+ * An attribute may also say what its words are *for*: four of them tagged `color` are a colour
+ * rather than four numbers that happen to be four. It changes nothing here — the offset, the width
+ * and every instruction that touches the attribute are exactly what they were without it — and is
+ * read by the authoring layer, where {@link ../graph/ParticleValueType.js particle_semantic_type}
+ * turns the tag into a type that an editor can offer a swatch for and colour a wire by.
+ *
+ * A plain string rather than a type object, because the runtime schema has no business importing a
+ * frontend's vocabulary, and an effect saved with a tag this build has never heard of has to load
+ * as the plain vector it is instead of failing.
  */
 export class ParticleLayout {
+
+    /**
+     * Attribute name -> where it sits in a particle record, how wide it is, and what it is for.
+     * @type {Map<string, {name: string, offset: number, components: number, type: string|undefined}>}
+     */
+    attributes = new Map();
+
+    /**
+     * First free word after all attributes.
+     * @type {number}
+     */
+    word_cursor = PARTICLE_RECORD_USER_WORD_START;
+
     /**
-     * @param {Array<{name: string, components: number}>} attributes ordered attribute declarations
+     * @param {Array<{name: string, components: number, type?: string}>} attributes ordered
+     *   attribute declarations. `type` optionally says what the words are *for* — see the note on
+     *   {@link #attributes} — and never what shape they are, which is `components` and only that.
      */
     constructor(attributes) {
         assert.isArray(attributes, "attributes");
 
-        /** @type {Map<string, {name: string, offset: number, components: number}>} */
-        this.attributes = new Map();
-
         let cursor = PARTICLE_RECORD_USER_WORD_START;
 
         for (const attribute of attributes) {
@@ -33,6 +60,10 @@ export class ParticleLayout {
             assert.greaterThanOrEqual(attribute.components, 1, "attribute.components must be >= 1");
             assert.lessThanOrEqual(attribute.components, 4, "attribute.components must be <= 4");
 
+            if (attribute.type !== undefined) {
+                assert.isString(attribute.type, "attribute.type");
+            }
+
             if (this.attributes.has(attribute.name)) {
                 throw new Error(`Duplicate particle attribute '${attribute.name}'`);
             }
@@ -41,12 +72,12 @@ export class ParticleLayout {
                 name: attribute.name,
                 offset: cursor,
                 components: attribute.components,
+                type: attribute.type,
             });
 
             cursor += attribute.components;
         }
 
-        /** @type {number} first free word after all attributes */
         this.word_cursor = cursor;
 
         if (cursor > PARTICLE_RECORD_WORD_COUNT) {
@@ -92,4 +123,69 @@ export class ParticleLayout {
     componentsOf(name) {
         return this.get(name).components;
     }
+
+    /**
+     * Structural equality: the same attributes, by name, at the same offsets, the same width, and
+     * tagged the same. Two layouts that compare equal describe one particle record — a program
+     * compiled against either reads and writes the same words.
+     *
+     * Declaration order is not compared separately because it cannot differ without an offset
+     * differing: attributes are packed sequentially in the order they were declared.
+     *
+     * @param {ParticleLayout} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (this === other) {
+            return true;
+        }
+
+        const attributes = this.attributes;
+
+        if (attributes.size !== other.attributes.size) {
+            return false;
+        }
+
+        for (const [name, attribute] of attributes) {
+            const candidate = other.attributes.get(name);
+
+            if (candidate === undefined) {
+                return false;
+            }
+
+            if (
+                candidate.offset !== attribute.offset
+                || candidate.components !== attribute.components
+                || candidate.type !== attribute.type
+            ) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Hash over everything {@link ParticleLayout#equals} compares.
+     *
+     * Per-attribute hashes are summed rather than folded in iteration order. A `Map` iterates in
+     * insertion order and equal layouts are built in the same order, so a fold would agree — but a
+     * commutative combine says outright that the hash is of a set of attributes, and holds even if
+     * a layout is ever built by some other route.
+     *
+     * @returns {number} int32
+     */
+    hash() {
+        let hash = this.attributes.size;
+
+        for (const [name, attribute] of this.attributes) {
+            hash = (hash + hash_mix3(
+                computeStringHash(name),
+                hash_mix2(attribute.offset, attribute.components),
+                computeStringHash(attribute.type)
+            )) | 0;
+        }
+
+        return hash;
+    }
 }

package/src/shade/renderer/particles/optimizer/dag/optimize_particle_program_vector.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @typedef {object} ParticleVectorOptimizerResult
+ * @property {ParticleProgram} program
+ * @property {boolean} rewritten whether the returned program is the optimized one
+ * @property {number} instructions what the optimized program cost, before `keep_better` had its say
+ * @property {number} registers likewise
+ */
+/**
+ * @param {ParticleProgram} program
+ * @param {object} [options] see {@link optimize_particle_program_vector_result}
+ * @returns {ParticleProgram}
+ */
+export function optimize_particle_program_vector(program: ParticleProgram, options?: object): ParticleProgram;
+/**
+ * @param {ParticleProgram} program
+ * @param {object} [options]
+ * @param {number} [options.register_slots] size of the register file to optimize against
+ * @param {boolean} [options.fold_inexact] fold what the two executors may round apart
+ * @param {boolean} [options.fold_multiply_by_zero] a known zero absorbs a multiply
+ * @param {boolean} [options.compact_registers] finish with the first optimizer's register allocator
+ * @param {boolean} [options.keep_better] return what was given when the rewrite is bigger
+ * @param {number[]} [options.share_windows] see {@link PARTICLE_VECTOR_SHARE_WINDOWS}
+ * @returns {ParticleVectorOptimizerResult}
+ */
+export function optimize_particle_program_vector_result(program: ParticleProgram, { register_slots, fold_inexact, fold_multiply_by_zero, compact_registers, keep_better, share_windows, }?: {
+    register_slots?: number;
+    fold_inexact?: boolean;
+    fold_multiply_by_zero?: boolean;
+    compact_registers?: boolean;
+    keep_better?: boolean;
+    share_windows?: number[];
+}): ParticleVectorOptimizerResult;
+/**
+ * The optimizer, over a graph whose values are VECTORS.
+ *
+ * The second optimizer, beside `../optimize_particle_program.js`'s pass pipeline. `ParticleProgram`
+ * in and out, flat options, and it is what the editor and the runtime get.
+ *
+ * There was a third, over a graph whose values were single LANES, and it was retired once this one
+ * beat it everywhere: making a value one lane buys lane-exact rewriting and costs the vectorisation
+ * the frontend had already done, and the second turns out to be worth more than the first on this
+ * machine. The argument and the measurements survive in `./particle_vector_graph.js`, because they
+ * are the reason this file is shaped the way it is and not an accident of it.
+ *
+ * The stages are lift, rewrite, extract, lower. With a vector as the unit there is no
+ * re-vectorisation to do, so what would otherwise be eight hundred lines of superword grouping and
+ * lane-order search is a hundred that say "one value, one instruction".
+ */
+/**
+ * How much sharing to try, in order, until the program fits the register file.
+ *
+ * A rung says how far back a value may have been computed and still be reused rather than
+ * recomputed. Unbounded is the honest first try, and it is what `curl3` and `curl4` cannot afford:
+ * unbounded sharing puts them at 61 and 103 slots against a file of 48, where sharing nothing at all
+ * puts them at 32 and 39. Between those lies the trade, and where a given program sits in it is not
+ * something a constant can know.
+ *
+ * @type {number[]}
+ */
+export const PARTICLE_VECTOR_SHARE_WINDOWS: number[];
+export type ParticleVectorOptimizerResult = {
+    program: ParticleProgram;
+    /**
+     * whether the returned program is the optimized one
+     */
+    rewritten: boolean;
+    /**
+     * what the optimized program cost, before `keep_better` had its say
+     */
+    instructions: number;
+    /**
+     * likewise
+     */
+    registers: number;
+};
+import { ParticleProgram } from "../../isa/ParticleProgram.js";
+//# sourceMappingURL=optimize_particle_program_vector.d.ts.map

package/src/shade/renderer/particles/optimizer/dag/optimize_particle_program_vector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimize_particle_program_vector.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/optimizer/dag/optimize_particle_program_vector.js"],"names":[],"mappings":"AA4CA;;;;;;GAMG;AAEH;;;;GAIG;AACH,0DAJW,eAAe,YACf,MAAM,GACJ,eAAe,CAI3B;AAED;;;;;;;;;;GAUG;AACH,iEAVW,eAAe;IAEE,cAAc,GAA/B,MAAM;IACY,YAAY,GAA9B,OAAO;IACW,qBAAqB,GAAvC,OAAO;IACW,iBAAiB,GAAnC,OAAO;IACW,WAAW,GAA7B,OAAO;IACY,aAAa,GAAhC,MAAM,EAAE;IACN,6BAA6B,CAwCzC;AAhGD;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;GAUG;AACH,4CAFU,MAAM,EAAE,CAEqE;;aAIzE,eAAe;;;;eACf,OAAO;;;;kBACP,MAAM;;;;eACN,MAAM;;gCA9CY,8BAA8B"}

package/src/shade/renderer/particles/optimizer/dag/optimize_particle_program_vector.js

@@ -0,0 +1,219 @@
+import { assert } from "../../../../../core/assert.js";
+import { PARTICLE_VM_INSTRUCTION_WORDS, PARTICLE_VM_REGISTER_SLOTS } from "../../ParticleConstants.js";
+import { ParticleAssembler } from "../../isa/ParticleAssembler.js";
+import { ParticleProgram } from "../../isa/ParticleProgram.js";
+import { optimize_particle_section, stream_from_words } from "../optimize_particle_program.js";
+import { PARTICLE_PASS_ALLOCATE_REGISTERS } from "../pass_allocate_registers.js";
+import { PARTICLE_PASS_PACK_REGISTERS } from "../pass_pack_registers.js";
+import { extract_particle_values } from "./particle_vector_extract.js";
+import { lower_particle_values } from "./particle_vector_lower.js";
+import { ParticleVectorGraph, PV } from "./particle_vector_graph.js";
+import { lift_particle_vector_section } from "./particle_vector_lift.js";
+import { pack_particle_vectors } from "./particle_vector_pack.js";
+import { particle_vector_rules } from "./particle_vector_rules.js";
+
+/**
+ * The optimizer, over a graph whose values are VECTORS.
+ *
+ * The second optimizer, beside `../optimize_particle_program.js`'s pass pipeline. `ParticleProgram`
+ * in and out, flat options, and it is what the editor and the runtime get.
+ *
+ * There was a third, over a graph whose values were single LANES, and it was retired once this one
+ * beat it everywhere: making a value one lane buys lane-exact rewriting and costs the vectorisation
+ * the frontend had already done, and the second turns out to be worth more than the first on this
+ * machine. The argument and the measurements survive in `./particle_vector_graph.js`, because they
+ * are the reason this file is shaped the way it is and not an accident of it.
+ *
+ * The stages are lift, rewrite, extract, lower. With a vector as the unit there is no
+ * re-vectorisation to do, so what would otherwise be eight hundred lines of superword grouping and
+ * lane-order search is a hundred that say "one value, one instruction".
+ */
+
+/**
+ * How much sharing to try, in order, until the program fits the register file.
+ *
+ * A rung says how far back a value may have been computed and still be reused rather than
+ * recomputed. Unbounded is the honest first try, and it is what `curl3` and `curl4` cannot afford:
+ * unbounded sharing puts them at 61 and 103 slots against a file of 48, where sharing nothing at all
+ * puts them at 32 and 39. Between those lies the trade, and where a given program sits in it is not
+ * something a constant can know.
+ *
+ * @type {number[]}
+ */
+export const PARTICLE_VECTOR_SHARE_WINDOWS = Object.freeze([Infinity, 256, 64, 16, 4]);
+
+/**
+ * @typedef {object} ParticleVectorOptimizerResult
+ * @property {ParticleProgram} program
+ * @property {boolean} rewritten whether the returned program is the optimized one
+ * @property {number} instructions what the optimized program cost, before `keep_better` had its say
+ * @property {number} registers likewise
+ */
+
+/**
+ * @param {ParticleProgram} program
+ * @param {object} [options] see {@link optimize_particle_program_vector_result}
+ * @returns {ParticleProgram}
+ */
+export function optimize_particle_program_vector(program, options = {}) {
+    return optimize_particle_program_vector_result(program, options).program;
+}
+
+/**
+ * @param {ParticleProgram} program
+ * @param {object} [options]
+ * @param {number} [options.register_slots] size of the register file to optimize against
+ * @param {boolean} [options.fold_inexact] fold what the two executors may round apart
+ * @param {boolean} [options.fold_multiply_by_zero] a known zero absorbs a multiply
+ * @param {boolean} [options.compact_registers] finish with the first optimizer's register allocator
+ * @param {boolean} [options.keep_better] return what was given when the rewrite is bigger
+ * @param {number[]} [options.share_windows] see {@link PARTICLE_VECTOR_SHARE_WINDOWS}
+ * @returns {ParticleVectorOptimizerResult}
+ */
+export function optimize_particle_program_vector_result(program, {
+    register_slots = PARTICLE_VM_REGISTER_SLOTS,
+    fold_inexact = false,
+    fold_multiply_by_zero = true,
+    compact_registers = true,
+    keep_better = true,
+    share_windows = PARTICLE_VECTOR_SHARE_WINDOWS,
+} = {}) {
+    assert.ok(program instanceof ParticleProgram, "program must be a ParticleProgram");
+    assert.lessThanOrEqual(register_slots, PARTICLE_VM_REGISTER_SLOTS, "register_slots exceeds the VM register file");
+
+    const assembler = new ParticleAssembler();
+    const intern_constant = values => assembler.constant(...values);
+    const rules = particle_vector_rules({ fold_inexact, fold_multiply_by_zero });
+    const shared = { program, register_slots, intern_constant, rules, share_windows };
+
+    const init = rebuild_section(program.init, shared);
+    const update = rebuild_section(program.update, shared);
+
+    if (init === null || update === null) {
+        return unchanged(program);
+    }
+
+    const rebuilt = new ParticleProgram({
+        init: init.toWords(),
+        update: update.toWords(),
+        constants: new Float32Array(assembler.constants),
+        register_count: Math.max(init.register_count, update.register_count),
+    });
+
+    const finished = compact_registers ? compact(rebuilt, register_slots) : rebuilt;
+    const instructions = finished.init_instruction_count + finished.update_instruction_count;
+
+    if (keep_better && !is_better(finished, program)) {
+        return { ...unchanged(program), instructions, registers: finished.register_count };
+    }
+
+    return { program: finished, rewritten: true, instructions, registers: finished.register_count };
+}
+
+/** @param {ParticleProgram} program @returns {ParticleVectorOptimizerResult} */
+function unchanged(program) {
+    return {
+        program,
+        rewritten: false,
+        instructions: program.init_instruction_count + program.update_instruction_count,
+        registers: program.register_count,
+    };
+}
+
+/**
+ * @param {ParticleProgram} rebuilt
+ * @param {ParticleProgram} original
+ * @returns {boolean}
+ */
+function is_better(rebuilt, original) {
+    const after = rebuilt.init_instruction_count + rebuilt.update_instruction_count;
+    const before = original.init_instruction_count + original.update_instruction_count;
+
+    return after !== before ? after < before : rebuilt.register_count < original.register_count;
+}
+
+/**
+ * What a literal costs. Below an instruction, because most become an operand; above nothing, so that
+ * a fold is not preferred over a value that was going to be computed anyway.
+ *
+ * @param {import("./particle_vector_graph.js").ParticleVectorNode} node
+ * @returns {number}
+ */
+function node_cost(node) {
+    return node.op === PV.CONST ? 0.5 : 1;
+}
+
+/**
+ * @param {Uint32Array} words one section
+ * @param {object} params
+ * @returns {import("../../isa/InstructionStream.js").InstructionStream|null}
+ */
+function rebuild_section(words, { program, register_slots, intern_constant, rules, share_windows }) {
+    const tuples = to_tuples(words);
+
+    // Widest sharing first, and less of it only where the result will not fit. Reusing a value rather
+    // than recomputing it saves an instruction and costs however long it now has to be held, and
+    // whether that is a good trade is not a question about the pair — it is a question about whether
+    // the whole program still fits. So it is answered by trying.
+    for (const share_window of share_windows) {
+        const graph = new ParticleVectorGraph({ ...rules, share_window });
+        const section = lift_particle_vector_section(graph, tuples, {
+            constants: program.constants,
+            register_slots,
+        });
+
+        if (section === null) {
+            return null;
+        }
+
+        // Every draw is a root whether or not anything reads it: the state at the end counts them.
+        const roots = [
+            ...section.stores.map(store => store.place.value),
+            ...section.kills.map(kill => kill.value),
+            ...section.draws,
+        ];
+        const extraction = extract_particle_values(graph, roots, { node_cost });
+        const packing = pack_particle_vectors(graph, section, extraction);
+        const lowered = lower_particle_values(packing, { register_slots, intern_constant });
+
+        if (lowered !== null) {
+            return lowered.stream;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * @param {ParticleProgram} program
+ * @param {number} register_slots
+ * @returns {ParticleProgram}
+ */
+function compact(program, register_slots) {
+    const options = {
+        passes: [PARTICLE_PASS_ALLOCATE_REGISTERS, PARTICLE_PASS_PACK_REGISTERS],
+        register_slots,
+        constants: program.constants,
+    };
+
+    const init = optimize_particle_section(stream_from_words(program.init), options);
+    const update = optimize_particle_section(stream_from_words(program.update), options);
+
+    return new ParticleProgram({
+        init: init.toWords(),
+        update: update.toWords(),
+        constants: program.constants,
+        register_count: Math.max(init.register_count, update.register_count),
+    });
+}
+
+/** @param {Uint32Array} words @returns {number[][]} */
+function to_tuples(words) {
+    const tuples = [];
+
+    for (let base = 0; base < words.length; base += PARTICLE_VM_INSTRUCTION_WORDS) {
+        tuples.push(Array.from(words.subarray(base, base + PARTICLE_VM_INSTRUCTION_WORDS)));
+    }
+
+    return tuples;
+}