@woosh/meep-engine 3.16.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

@@ -71,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;;;;;;;;;;;;;;;;;;;;;;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;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,
@@ -120,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;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * Choose one node per class — the instruction-count half of the optimizer.
+ *
+ * Most classes hold one node and there is nothing to choose. The ones that hold two are where a
+ * rewrite's worth was not local: `a * b + c` as a `MAD` costs one instruction and as `MUL` then
+ * `ADD` costs two, but the `MAD` only SAVES one if nothing else reads the product. So the cost that
+ * matters is the DAG cost — every distinct node counted once, which is exactly the instruction count
+ * — and not the tree cost, which would count a shared subexpression once per reader and talk itself
+ * into duplicating work.
+ *
+ * ## Why this is a greedy and not an exact solver
+ *
+ * DAG-cost extraction is NP-hard in general (reduction from minimum set cover), and the literature's
+ * answer at this scale is an ILP. That would mean a solver, and there is no solver in this tree and
+ * no appetite for vendoring one. What is here instead is the standard two-step: a bottom-up
+ * relaxation to a consistent choice, then hill-climbing on the classes that actually have a choice,
+ * each flip scored by re-measuring the whole reachable set.
+ *
+ * ## The climb does nothing today, and that is worth saying
+ *
+ * With the one alternative there is — `MAD` beside `MUL` then `ADD` — the seed is already optimal,
+ * and it was measured to be: over the whole effect corpus, switching the climb off changes neither an
+ * instruction nor a slot. The reason is that a `MAD` is never WORSE than the pair. Choosing it costs
+ * one instruction and leaves the product to be counted only if something else still reads it, so its
+ * DAG cost is at most the pair's, and the bottom-up relaxation — which prefers it on tree cost, where
+ * it is strictly cheaper — lands on the answer without help.
+ *
+ * The climb stays because the seed's agreement is a property of THAT rule and not of the pipeline. A
+ * rule whose alternative is dearer where it is shared — a fused operation that costs more than one
+ * instruction, an operation with a wider destination — has a tree cost that says the wrong thing, and
+ * the climb is what corrects it. `./particle_vector_extract.spec.js` exercises exactly that, through the
+ * `node_cost` the caller may pass, so the machinery is held to its purpose rather than to the one
+ * rule that happens not to need it.
+ *
+ * The relaxation is also what keeps extraction honest about cycles. A class can only be given a cost
+ * through nodes whose children already have one, so a node that could only be reached through its own
+ * class never gets a finite cost and is never chosen, whatever the rules did.
+ */
+/**
+ * What a node costs. Everything is one instruction except a literal, which is usually an operand
+ * rather than an instruction — priced below one so that folding is preferred, and above zero so that
+ * a fold is not preferred over a value that was already going to be computed anyway.
+ *
+ * @param {import("./particle_vector_graph.js").ParticleVectorNode} node
+ * @returns {number}
+ */
+export function particle_vector_node_cost(node: import("./particle_vector_graph.js").ParticleVectorNode): number;
+/**
+ * @typedef {object} ParticleValueExtraction
+ * @property {Map<number, number>} choice per class, the node chosen for it
+ * @property {number[]} order the demanded classes, every class after the ones it reads
+ * @property {number} cost the DAG cost of that choice
+ */
+/**
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {number[]} roots classes the program has to compute
+ * @param {object} [options]
+ * @param {function(import("./particle_vector_graph.js").ParticleVectorNode): number} [options.node_cost]
+ * @param {number} [options.max_rounds] hill-climbing sweeps over the classes that have a choice
+ * @param {number} [options.max_evaluations] flips to score before settling for what is in hand; a
+ *   guard so a pathological program cannot make extraction the slow part of a build
+ * @returns {ParticleValueExtraction}
+ */
+export function extract_particle_values(graph: import("./particle_vector_graph.js").ParticleVectorGraph, roots: number[], { node_cost, max_rounds, max_evaluations, }?: {
+    node_cost?: (arg0: import("./particle_vector_graph.js").ParticleVectorNode) => number;
+    max_rounds?: number;
+    max_evaluations?: number;
+}): ParticleValueExtraction;
+export type ParticleValueExtraction = {
+    /**
+     * per class, the node chosen for it
+     */
+    choice: Map<number, number>;
+    /**
+     * the demanded classes, every class after the ones it reads
+     */
+    order: number[];
+    /**
+     * the DAG cost of that choice
+     */
+    cost: number;
+};
+//# sourceMappingURL=particle_vector_extract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"particle_vector_extract.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/optimizer/dag/particle_vector_extract.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;;;;;;GAOG;AACH,gDAHW,OAAO,4BAA4B,EAAE,kBAAkB,GACrD,MAAM,CAIlB;AAED;;;;;GAKG;AAEH;;;;;;;;;GASG;AACH,+CATW,OAAO,4BAA4B,EAAE,mBAAmB,SACxD,MAAM,EAAE;IAE4E,SAAS,UAApF,OAAO,4BAA4B,EAAE,kBAAkB,KAAG,MAAM;IACxD,UAAU,GAA3B,MAAM;IACW,eAAe,GAAhC,MAAM;IAEJ,uBAAuB,CA0DnC;;;;;YAvEa,IAAI,MAAM,EAAE,MAAM,CAAC;;;;WACnB,MAAM,EAAE;;;;UACR,MAAM"}