@adobe/ecs 0.1.0 → 0.2.1

package/src/implementation/compiler/compile-kernel.ts

@@ -1,31 +1,53 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Node, ObjectExpression } from 'estree';
 import { bind } from './bind.js';
-import { requireExact } from './exact.js';
 import { expression } from './expression.js';
 import { fail } from './failure.js';
 import type { Link } from './link.js';
+import type { PackageCopies } from './package-copies.js';
 import { createLists } from './lists.js';
 import type { Module } from './module-scope.js';
 import { resolve, type Out } from './out.js';
+import type { Statement } from './ir.js';
 import { localName, printStatements } from './print.js';
 import { toProgram } from './program.js';
 import { serialize } from './serialize.js';
 import { unconditionalChunks } from './stamps.js';
-import { chunkShift, type Program } from '../world/kernel.js';
+import { blockShift, chunkShift, type Program } from '../world/kernel.js';
 import { rootScope } from './scope.js';
-import { signature } from './signature.js';
+import { signature, type Signature } from './signature.js';
+import type { Reduction } from '../../interface/resource/reduction.js';
 import { rowLabel, statement } from './statement.js';
 import { createUnit } from './unit.js';
 import type { Value } from './value.js';
 
-const parameterValues: readonly Value[] = [{ kind: "row" }, { kind: "context" }];
+/** A kernel body takes its row, its context and its input, the run's arguments. */
+const parameterValues: readonly Value[] = [{ kind: "row" }, { kind: "context" }, { kind: "dynamic", expression: { kind: "args", path: [] } }];
 
 /**
  * One compiled kernel: `description(url)` is the source of its `KernelDescription`, with keys as the declaration's
  * identifiers and `program` lowered from the same statements as the JS; `create` is the source of
  * `KernelModule.create`, which references no module bindings and uses `keys[k]` only as opaque property keys.
  */
-export type CompiledKernel = { readonly description: (url: string) => string; readonly create: string };
+export type CompiledKernel = { readonly description: (url: string) => string; readonly create: string; readonly explain: () => KernelExplanation };
+
+/**
+ * What describing a kernel needs of its compiling (`describe.ts`), made only when asked: its statements, its program
+ * with its locals named, or why it has none, and its columns and lookups by their keys' bindings.
+ */
+export type KernelExplanation = {
+    readonly statements: readonly Statement[];
+    readonly program: Program | null;
+    /** Why it has no program, when it has none for a reason other than its statements. */
+    readonly unprogrammed: string | null;
+    /** Each column by its identity: `entity`, `field <key> <path>`, or `changed`, `chunks`, `blocks` or `present` and its key. */
+    readonly columns: readonly string[];
+    readonly upColumns: readonly string[];
+    readonly signature: Signature;
+    readonly storagePrecision: boolean;
+    /** Each accumulator's operator, in its description's `reductions` order. */
+    readonly operators: readonly Reduction[];
+};
 
 /**
  * Statements a GPU kernel can't contain: WGSL has no labeled multi-level branches, and loops aren't supported yet.
@@ -40,14 +62,14 @@ const loops = (statements: readonly Program.Statement[]): boolean => statements.
 });
 
 /** `target` "gpu" also checks, before anything runs, what only a GPU kernel can't do; schemas are checked at registration. */
-export const compileKernel = (declaration: ObjectExpression, body: Node, module: Module, target: "cpu" | "gpu" = "cpu", link: Link | null = null): CompiledKernel => {
+export const compileKernel = (declaration: ObjectExpression, body: Node, module: Module, target: "cpu" | "gpu" = "cpu", link: Link | null = null, tried = false, packages: PackageCopies | null = link?.packages ?? null): CompiledKernel => {
     if (body.type !== "ArrowFunctionExpression" && body.type !== "FunctionExpression") {
         return fail(body, "a kernel body must be an inline function");
     }
     if (body.async || body.generator) return fail(body, "a kernel body can't be async or a generator");
-    if (body.params.length > 2) return fail(body, "a kernel body takes row and context");
+    if (body.params.length > 3) return fail(body, "a kernel body takes its row, context and input");
     const lists = createLists(module, link, [declaration, body]);
-    const unit = createUnit(signature(declaration, module.bindings, lists), module, lists, expression, statement, link, target);
+    const unit = createUnit(signature(declaration, module.bindings, lists), module, lists, expression, statement, link, target, tried, packages);
     const scope = rootScope(unit, false);
     const prelude: Out = [];
     const rows: Out = [];
@@ -58,14 +80,26 @@ export const compileKernel = (declaration: ObjectExpression, body: Node, module:
         statement({ type: "ExpressionStatement", expression: body.body, start: body.body.start, end: body.body.end }, scope, rows);
     }
     const statements = [...resolve(prelude), ...resolve(rows)];
-    for (const chunks of unconditionalChunks(resolve(rows))) unit.stampedPerCall.add(chunks);
+    for (const [chunks, perCall] of unconditionalChunks(resolve(rows))) unit.stampedPerCall.set(chunks, perCall);
     const kernel = printStatements(unit, resolve(rows));
+    // Which optional components a call's archetype has is the same for every row, so a kernel with them runs loops
+    // specialized for all present and all absent, and the general one only for archetypes with some of them.
+    const specialized = unit.presences.size === 0 ? null : ([true, false] as const).map(present => {
+        unit.presentAs = present;
+        const body = printStatements(unit, resolve(rows));
+        unit.presentAs = null;
+        return body;
+    });
     const preludeCode = printStatements(unit, resolve(prelude));
     const accumulators = unit.accumulators.map(entry => entry.local);
     const { signature: { resources, lookups, up, ordered, filtered, reduced }, columns, booleans, keys } = unit;
     /** Whether it runs a list of rows, which needn't be consecutive: `up`'s depth order, or an index's. */
     const listed = up !== null || ordered;
-    const program = toProgram(statements, target === "gpu" ? local => localName(unit, local) : undefined, accumulators, unit.up, listed);
+    // WASM doesn't read components an archetype may lack yet, so such a kernel runs as JS.
+    // WASM reads a lookup's rows only where every component it reads is there.
+    const optionalListed = unit.optionalColumns.size + unit.presences.size > 0 && listed;
+    const optionalLookups = unit.signature.lookups.some(lookup => lookup.optional);
+    const program = optionalListed || optionalLookups ? null : toProgram(statements, target === "gpu" ? local => localName(unit, local) : undefined, accumulators, unit.up, listed);
     if (target === "gpu") {
         if (lookups.length > 0) fail(declaration, "a GPU kernel can't use lookups yet");
         if (filtered) fail(declaration, "a GPU kernel can't use change filters yet");
@@ -73,12 +107,15 @@ export const compileKernel = (declaration: ObjectExpression, body: Node, module:
         if (program === null) fail(body, "a GPU kernel can't issue commands or use values that aren't numbers or booleans");
         else if (loops(program.body)) fail(body, "a GPU kernel can't use loops or labeled blocks yet");
     }
-    const contributed = new Set(unit.accumulators.flatMap(entry => reduced[entry.reduced]?.resource ?? []));
-    requireExact(declaration, { query: unit.used, resources: { read: unit.used.resources, write: new Set(), reduce: contributed }, lookups: unit.used.lookups, up: unit.used.up }, module.bindings, lists);
-    const strided = columns.flatMap((_, index) => unit.chunks.has(index) ? [] : [index]);
+    // Chunk, block and presence columns aren't read at a row's element.
+    const strided = columns.flatMap((column, index) => unit.chunks.has(index) || unit.blocks.has(index) || column.startsWith("{ kind: \"present\"") ? [] : [index]);
     const locals = [
         ...columns.map((_, index) => `const c${index} = columns[${index}];`),
+        // Whether this call's archetype has each optional component, whose column is empty where it doesn't.
+        ...[...unit.presences.values()].map(index => `const q${index} = c${index}.length !== 0;`),
         ...resources.map((_, index) => `const r${index} = resources[${index}];`),
+        // Each call's archetype's values of the shared components it reads.
+        ...unit.signature.shared.map((_, index) => `const h${index} = shared[${index}];`),
         ...lookups.map((_, index) => `const l${index} = lookups[${index}];`),
         ...unit.spawns.map((_, index) => `const spawn${index} = commands.spawners[${index}];`),
         // A call's rows share one parent archetype, whose columns `up` reads at each row's parent row `p`.
@@ -87,12 +124,34 @@ export const compileKernel = (declaration: ObjectExpression, body: Node, module:
             ...unit.upColumns.map((_, index) => `const u${index} = upColumns[${index}];`),
         ],
     ];
+    const presences = [...unit.presences.values()];
+    /** The row loop around a body. */
+    const loop = (body: string): string => [
+        listed
+            ? `${rowLabel}: for (let n = start; n < end; n++) { const i = rows[n], p = parents[n]; ${[...strided.map(index => `const x${index} = i * s${index} + o${index};`), ...[...unit.stampedPerCall].map(([chunks, { blocks, when }]) => `${when === null ? "" : `if (q${when}) `}{ c${blocks}[i >> ${blockShift}] = tick; c${chunks}[i >> ${chunkShift}] = tick; }`)].join(" ")}`
+            : `${rowLabel}: for (let ${["i = start", ...strided.map(index => `x${index} = start * s${index} + o${index}`)].join(", ")}; i < end; ${["i++", ...strided.map(index => `x${index} += s${index}`)].join(", ")}) {`,
+        body,
+        "}",
+    ].join("\n");
+    const explain = (): KernelExplanation => ({
+        statements,
+        program: program === null ? null : target === "gpu" ? program : toProgram(statements, local => localName(unit, local), accumulators, unit.up, listed),
+        unprogrammed: optionalListed ? "WASM doesn't read optional components of rows run as a list, in `up`'s or an index's order, yet"
+            : optionalLookups ? "WASM doesn't read a lookup's optional components yet" : null,
+        columns: [...unit.columnIndex.keys()],
+        upColumns: [...unit.upColumnIndex.keys()],
+        signature: unit.signature,
+        storagePrecision: !unit.tried,
+        operators: unit.accumulators.map(entry => unit.signature.reduced[entry.reduced]?.operator ?? fail(declaration, "unknown reduction")),
+    });
     return {
+        explain,
         description: url => [
             "{",
             `columns: [${columns.join(", ")}],`,
             `shapes: [${[...unit.shapes].join(", ")}],`,
             `resources: [${resources.join(", ")}],`,
+            ...unit.signature.shared.length === 0 ? [] : [`shared: [${unit.signature.shared.join(", ")}],`],
             `lookups: [${lookups.map(lookup => JSON.stringify(lookup.name)).join(", ")}],`,
             ...unit.probes.length === 0 ? [] : [`probes: [${unit.probes.join(", ")}],`, `rowLeaves: [${unit.rowLeaves.join(", ")}],`],
             ...up === null ? [] : ["up: true,", `upColumns: [${unit.upColumns.join(", ")}],`],
@@ -103,6 +162,7 @@ export const compileKernel = (declaration: ObjectExpression, body: Node, module:
             `url: ${url},`,
             `program: ${serialize(program)},`,
             `reducedShapes: [${[...unit.reducedShapes].join(", ")}],`,
+            ...unit.tried ? [] : ["storagePrecision: true,"],
             `reductions: [${unit.accumulators.map(entry => {
                 const { resource, operator } = reduced[entry.reduced] ?? fail(declaration, "unknown reduction");
                 return `{ resource: ${resource}, operator: ${JSON.stringify(operator)}, path: ${JSON.stringify(entry.path)} }`;
@@ -112,25 +172,30 @@ export const compileKernel = (declaration: ObjectExpression, body: Node, module:
         // Per-registration constants live in the closure. Each column's element index `i * s + o` is strength-reduced to
         // an induction variable in the loop update, which `continue rows` still runs.
         create: [
-            "(booleans, strides, offsets, upBooleans, upStrides, upOffsets) => {",
+            "(booleans, strides, offsets, upBooleans, upStrides, upOffsets, labels) => {",
             ...[...booleans].map(index => `const b${index} = booleans[${index}];`),
+            ...unit.optionalColumns.size + unit.presences.size === 0 ? [] : [
+                "const absent = k => { throw new Error(`An entity lacks \"${labels[k]}\", optional in its system: add it with commands.add rather than assigning it.`); };",
+            ],
             ...[...unit.upBooleans].map(index => `const ub${index} = upBooleans[${index}];`),
             ...unit.upColumns.map((_, index) => `const us${index} = upStrides[${index}], uo${index} = upOffsets[${index}];`),
             ...strided.map(index => `const s${index} = strides[${index}], o${index} = offsets[${index}];`),
             // Each lookup through an index's site holds its list and rows in handles its reader fills, made once.
             ...[...unit.handles].map(handle => `const ${localName(unit, handle)} = { a: 0, b: 0, c: 0, d: 0, e: 0, f: 0, g: 0, h: 0 };`),
-            "return (columns, start, end, resources, lookups, keys, args, commands, tick, partials, partial, rows, parents, upColumns, found) => {",
+            "return (columns, start, end, resources, lookups, keys, args, commands, tick, partials, partial, rows, parents, upColumns, found, shared) => {",
             ...locals,
             preludeCode,
             ...accumulators.map((local, k) => `let ${localName(unit, local)} = partials[partial + ${k}];`),
-            // A kernel that runs a list of rows, which needn't be consecutive, stamps each row's own chunk.
-            ...listed ? [] : [...unit.stampedPerCall].map(chunks =>
-                `if (start < end) for (let k = start >> ${chunkShift}, last = (end - 1) >> ${chunkShift}; k <= last; k++) c${chunks}[k] = tick;`),
-            listed
-                ? `${rowLabel}: for (let n = start; n < end; n++) { const i = rows[n], p = parents[n]; ${[...strided.map(index => `const x${index} = i * s${index} + o${index};`), ...[...unit.stampedPerCall].map(chunks => `c${chunks}[i >> ${chunkShift}] = tick;`)].join(" ")}`
-                : `${rowLabel}: for (let ${["i = start", ...strided.map(index => `x${index} = start * s${index} + o${index}`)].join(", ")}; i < end; ${["i++", ...strided.map(index => `x${index} += s${index}`)].join(", ")}) {`,
-            kernel,
-            "}",
+            // A kernel that runs a list of rows, which needn't be consecutive, stamps each row's own block and chunk.
+            ...listed ? [] : [...unit.stampedPerCall].flatMap(([chunks, { blocks, when }]) => [
+                `if (${when === null ? "" : `q${when} && `}start < end) for (let k = start >> ${blockShift}, last = (end - 1) >> ${blockShift}; k <= last; k++) c${blocks}[k] = tick;`,
+                `if (${when === null ? "" : `q${when} && `}start < end) for (let k = start >> ${chunkShift}, last = (end - 1) >> ${chunkShift}; k <= last; k++) c${chunks}[k] = tick;`,
+            ]),
+            ...specialized === null ? [loop(kernel)] : [
+                `if (${presences.map(index => `q${index}`).join(" && ")}) {`, loop(specialized[0]),
+                `} else if (${presences.map(index => `!q${index}`).join(" && ")}) {`, loop(specialized[1]),
+                "} else {", loop(kernel), "}",
+            ],
             ...accumulators.map((local, k) => `partials[partial + ${k}] = ${localName(unit, local)};`),
             "};",
             "}",

package/src/implementation/compiler/compiler.ts

@@ -0,0 +1,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export type Compiler = never;
+
+/**
+ * The build's compiler: `Compiler.plugin()` in an application's Vite config, `Compiler.plugin({ library: true })` in a
+ * library's.
+ */
+export * as Compiler from './public.js';

package/src/implementation/compiler/data.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Node } from 'estree';
 import type { Path } from '../world/kernel.js';
 import { fail } from './failure.js';

package/src/implementation/compiler/describe.test-helper.ts

@@ -0,0 +1,97 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity, type F32, System, Vec2, Vec3 } from '../../index.js';
+
+/** Systems of each kind the descriptions tell apart (`describe.test.ts`), compiled by the plugin and described from this source. */
+
+export const position = Symbol("describeTest/position");
+export const velocity = Symbol("describeTest/velocity");
+export const spot = Symbol("describeTest/spot");
+export const drift = Symbol("describeTest/drift");
+export const label = Symbol("describeTest/label");
+export const bonus = Symbol("describeTest/bonus");
+export const score = Symbol("describeTest/score");
+export const flag = Symbol("describeTest/flag");
+export const target = Symbol("describeTest/target");
+export const aim = Symbol("describeTest/aim");
+export const delta = Symbol("describeTest/delta");
+export const total = Symbol("describeTest/total");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [position]: { type: Vec3 };
+        [velocity]: { type: Vec3 };
+        [spot]: { type: Vec2 };
+        [drift]: { type: Vec2 };
+        [label]: { type: string };
+        [bonus]: { type: F32 };
+        [score]: { type: number };
+        [flag]: { type: boolean };
+        [target]: { type: Entity };
+        [aim]: { type: number };
+    }
+    export interface Resources {
+        [delta]: { type: F32; default: 0.5 };
+        [total]: { type: number; reduce: "+" };
+    }
+}
+
+export const automatic = System.create({ components: { with: [velocity, position] } }, (row, { resources }) => {
+    row[position] = Vec3.add(row[position], Vec3.scale(row[velocity], resources[delta]));
+});
+
+export const asserted = System.create({ kernel: true, components: { with: [velocity, position] } }, row => {
+    row[position] = Vec3.add(row[position], row[velocity]);
+});
+
+export const shaded = System.create({ kernel: "gpu", components: { with: [drift, spot] } }, row => {
+    row[spot] = Vec2.add(row[spot], row[drift]);
+});
+
+export const spawn = System.create(({ commands }) => {
+    commands.spawn([position, velocity])({ [position]: [0, 0, 0], [velocity]: [1, 0, 0] });
+});
+
+export const observe = System.create({ observer: true, components: { with: [position] } }, row => {
+    console.log(row[position]);
+});
+
+export const named = System.create({ components: { with: [label, score] } }, row => {
+    row[score] = row[label].length;
+});
+
+export const optional = System.create({ components: { with: [score], optional: [bonus] } }, row => {
+    row[score] = row[score] + (row[bonus] ?? 1);
+});
+
+export const unflagged = System.create({ kernel: false, components: { with: [velocity] } }, row => {
+    row[velocity] = Vec3.scale(row[velocity], 0.5);
+});
+
+export const draw = System.render({ shader: { accessors: { dotPosition: spot } } }, ({ tables }) => {
+    console.log(tables.length);
+});
+
+export const filtered = System.create({ components: { with: [score], changed: [score] } }, row => {
+    row[score] = Math.max(row[score], 0) % 7;
+});
+
+export const looked = System.create({ components: { with: [target, aim] }, lookup: { other: { with: [score, flag], changed: [score] } } }, (row, { lookup }) => {
+    const found = lookup.other(row[target]);
+    row[aim] = found === null ? 0 : found[flag] ? found[score] : -found[score];
+});
+
+export const summed = System.create({ components: { with: [score] } }, (row, { reduce }) => {
+    reduce[total](row[score]);
+});
+
+export const inputs = System.create({ components: { with: [score] } }, (row, _context, input: { readonly by: number; readonly negate: boolean }) => {
+    row[score] = input.negate ? -row[score] * input.by : row[score] * input.by;
+});
+
+export const hypotenuse = System.create({ components: { with: [score] } }, row => {
+    row[score] = Math.hypot(row[score], 1, 2);
+});
+
+export const nested = (): unknown => System.create({ components: { with: [score] } }, row => {
+    row[score] = 1;
+});

package/src/implementation/compiler/describe.test.ts

@@ -0,0 +1,168 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/// <reference types="node" />
+import { readdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import createWabt from 'wabt';
+import { beforeAll, describe, expect, it } from 'vitest';
+import { definitionOf } from '../../interface/registry/index.js';
+import type { System } from '../../interface/system/system.js';
+import { kernelOf } from '../world/attach-kernel.js';
+import { bindKernel } from '../world/kernels.js';
+import { createState, idOf } from '../world/state.js';
+import type { Backend } from './describe.js';
+import * as fixture from './describe.test-helper.js';
+import { createMemoryCompiler, type MemoryCompiler, type SystemDescription } from './memory-compiler.js';
+import { wasmHost } from './oxc.test-helper.js';
+
+const root = fileURLToPath(new URL("../../..", import.meta.url)).replace(/\/$/, "");
+const filesIn = (folder: string, extension: string): readonly string[] =>
+    readdirSync(`${root}/${folder}`, { recursive: true, encoding: "utf8" }).filter(file => file.endsWith(extension)).map(file => `${root}/${folder}/${file}`);
+const files = new Map([`${root}/package.json`, ...filesIn("src", ".ts"), ...filesIn("dist", ".js")].map(file => [file, readFileSync(file, "utf8")]));
+const helper = `${root}/src/implementation/compiler/describe.test-helper.ts`;
+const source = files.get(helper) ?? "";
+
+let compiler: MemoryCompiler;
+let systems: ReadonlyMap<string | null, SystemDescription>;
+beforeAll(async () => {
+    const { parse, strip } = await wasmHost();
+    compiler = createMemoryCompiler({ files, packageRoot: root, parse, strip });
+    const compiled = await compiler.compile(helper, source, index => JSON.stringify(`kernel:${index}`), { describe: true });
+    if ("failure" in compiled) throw new Error(compiled.failure);
+    systems = new Map((compiled.systems ?? []).map(system => [system.binding, system]));
+}, 60000);
+
+const described = (binding: string | null): SystemDescription => {
+    const system = systems.get(binding);
+    if (system === undefined) throw new Error(`no system ${binding}`);
+    return system;
+};
+const codeOf = (backend: Backend): string => "code" in backend ? backend.code : `no code: ${backend.reason}`;
+const reasonOf = (backend: Backend): string => "reason" in backend ? backend.reason : "compiled";
+
+const features = { simd: true, threads: true, sat_float_to_int: true };
+/** A module's text as wabt prints it from its bytes, which no names or grouping of locals change. */
+const canonical = async (bytes: Uint8Array): Promise<string> => {
+    const wabt = await createWabt();
+    const module = wabt.readWasm(bytes, { ...features, readDebugNames: false });
+    try {
+        return module.toText({ foldExprs: false });
+    } finally {
+        module.destroy();
+    }
+};
+const assembled = async (wat: string): Promise<Uint8Array> => {
+    const wabt = await createWabt();
+    const module = wabt.parseWat("described.wat", wat, features);
+    try {
+        const { buffer } = module.toBinary({ write_debug_names: false });
+        // Node validates shared memory, which wabt's validator doesn't take.
+        if (!WebAssembly.validate(buffer)) throw new Error("the WAT assembles to a module that isn't valid");
+        return buffer;
+    } finally {
+        module.destroy();
+    }
+};
+
+/** A system's kernel bound as a world binds it, with `score`'s changes observed, as `filtered` observes them. */
+const bound = (system: System<unknown>) => {
+    const leaf = definitionOf(system);
+    const description = kernelOf(system);
+    if (leaf === undefined || leaf.kind === "composite" || description === undefined) throw new Error("not a compiled leaf");
+    const state = createState(true);
+    state.observed.add(idOf(state, fixture.score));
+    return bindKernel(state, leaf, description);
+};
+
+describe("a module's systems described", () => {
+    it("locates each system's call and names its binding", () => {
+        const system = described("automatic");
+        expect(source.slice(system.start, system.end)).toMatch(/^System\.create\(\{ components: \{ with: \[velocity, position\] \} \}[\s\S]*\}\)$/);
+        expect(source.split("\n")[system.line - 1]?.slice(system.column - 1)).toMatch(/^System\.create\(/);
+        expect([...systems.keys()]).toEqual(["automatic", "asserted", "shaded", "spawn", "observe", "named", "optional", "unflagged", "draw", "filtered", "looked", "summed", "inputs", "hypotenuse", null]);
+    });
+
+    it("gives an automatic kernel's JS, its WASM at the body's precision, and the shader it would be as a GPU kernel", () => {
+        const system = described("automatic");
+        expect(system).toMatchObject({ kind: "row", kernel: null, js: { kind: "compiled" }, wasm: { kind: "compiled" }, wgsl: { kind: "eligible", reason: expect.stringContaining("With `kernel: \"gpu\"`") } });
+        expect(codeOf(system.js)).toContain("export const create = (booleans");
+        expect(codeOf(system.js)).toContain("\n\t\trows: for (");
+        expect(codeOf(system.wasm)).toContain("(func $run (type 0) (param $start i32) (param $end i32) (param $tick f64) (param $lastRun f64) (param $c0 i32)");
+        expect(codeOf(system.wasm)).toContain("(local $x1_7 f64)");
+        expect(codeOf(system.wasm)).toContain("f64.promote_f32");
+        expect(codeOf(system.wgsl)).toContain("@compute @workgroup_size(64)");
+        expect(system.runs).toMatch(/^WASM on the kernel pool's workers, (a row at a time|two f64 lanes at a time, bit-exact with the body as written); the JS kernel/);
+    });
+
+    it("gives a kernel: true kernel's WASM in f32 lanes at storage precision", () => {
+        const system = described("asserted");
+        expect(system).toMatchObject({ kernel: true, wasm: { kind: "compiled" }, runs: expect.stringContaining("four f32 lanes at a time, rounding each step to storage precision") });
+        expect(codeOf(system.wasm)).toContain("f32x4.add");
+    });
+
+    it("gives a GPU kernel's shader, and the kernel it runs as on the CPU without a GPU", () => {
+        const system = described("shaded");
+        expect(system).toMatchObject({ kernel: "gpu", js: { kind: "compiled" }, wasm: { kind: "compiled" }, wgsl: { kind: "compiled" } });
+        expect(system.runs).toMatch(/^A compute shader, in a world with a GPU device; in one without, WASM on the kernel pool's workers/);
+        expect(codeOf(system.wgsl)).toContain("fn kernelRow(row: u32)");
+    });
+
+    it("says why systems that run as written have no code: per-run systems, observers, render systems, kernel: false and one declared in a function", () => {
+        expect(described("spawn")).toMatchObject({ kind: "per-run", runs: `Its body as written, on the "world" thread` });
+        for (const backend of ["js", "wasm", "wgsl"] as const) expect(reasonOf(described("spawn")[backend])).toBe("per-run systems run as written; only row systems compile");
+        expect(described("observe")).toMatchObject({ kind: "observer", js: { kind: "none", reason: expect.stringMatching(/^an observer runs as written/) } });
+        expect(described("draw")).toMatchObject({ kind: "render", runs: expect.stringContaining("while the world has a GPU device"), wgsl: { kind: "none", reason: expect.stringMatching(/^a render system runs as written/) } });
+        const unflagged = described("unflagged");
+        expect(unflagged).toMatchObject({ kernel: false, js: { kind: "none", reason: "as written, because `kernel: false`" }, wasm: { kind: "none", reason: "as written, because `kernel: false`" }, wgsl: { kind: "eligible" } });
+        expect(described(null)).toMatchObject({ kind: "row", js: { kind: "none", reason: "it's declared inside a function, and kernels are declared at module scope" } });
+    });
+
+    it("says why a body reading a string runs as written, as registering its kernel finds", () => {
+        const system = described("named");
+        expect(reasonOf(system.js)).toBe("its body isn't a kernel: it reads label, a string, which kernels don't read yet");
+        expect(reasonOf(system.wgsl)).toBe("GPU kernels need `kernel: \"gpu\"`, and this body can't be one: it reads label, a string, which kernels don't read yet");
+        expect(system.runs).toBe(`Its body as written, on the "world" thread`);
+    });
+
+    it("says why a body reading an optional component has no WASM, and can't be a GPU kernel", () => {
+        const system = described("optional");
+        expect(system).toMatchObject({ js: { kind: "compiled" }, runs: "The JS kernel, on the kernel pool's workers" });
+        expect(reasonOf(system.wasm)).toBe("it uses ??, which WASM and the GPU have no null for");
+        expect(reasonOf(system.wgsl)).toMatch(/^GPU kernels need `kernel: "gpu"`, and this body can't be one: a GPU kernel can't have optional components/);
+    });
+
+    it("says why kernels with change filters, lookups and reductions can't be GPU kernels, from the GPU compile's own failures", () => {
+        expect(reasonOf(described("filtered").wgsl)).toMatch(/a GPU kernel can't use change filters yet$/);
+        expect(reasonOf(described("looked").wgsl)).toMatch(/a GPU kernel can't use lookups yet$/);
+        expect(reasonOf(described("summed").wgsl)).toMatch(/a GPU kernel can't use reductions yet$/);
+        expect(reasonOf(described("inputs").wgsl)).toMatch(/it reads an f64 value, such as an entity or a precision-2 number$/);
+    });
+
+    it("says why the WASM generator can't run a body its JS kernel runs", () => {
+        expect(described("hypotenuse")).toMatchObject({ js: { kind: "compiled" }, runs: "The JS kernel, on the kernel pool's workers" });
+        expect(reasonOf(described("hypotenuse").wasm)).toBe("it calls Math.hypot with more than two arguments, and WASM imports it taking two");
+    });
+
+    it("gives, for every kernel, the WASM and shader a world generates when it binds the kernel", async () => {
+        const kernels = { automatic: fixture.automatic, asserted: fixture.asserted, shaded: fixture.shaded, optional: fixture.optional, filtered: fixture.filtered, looked: fixture.looked, summed: fixture.summed, inputs: fixture.inputs, hypotenuse: fixture.hypotenuse };
+        for (const [binding, system] of Object.entries(kernels)) {
+            const kernel = bound(system);
+            const { wasm } = described(binding);
+            if (kernel.wasm === null) {
+                expect(wasm.kind, binding).toBe("none");
+                continue;
+            }
+            expect(await canonical(await assembled(codeOf(wasm))), binding).toBe(await canonical(kernel.wasm.bytes));
+        }
+        const shader = bound(fixture.shaded).gpu();
+        expect(codeOf(described("shaded").wgsl)).toBe(typeof shader === "string" ? shader : shader.code);
+    });
+
+    it("isn't given unless asked for, and costs the plugin's path nothing", async () => {
+        const compiled = await compiler.compile(helper, source, index => JSON.stringify(`kernel:${index}`));
+        expect(compiled).not.toHaveProperty("systems");
+        const again = await compiler.compile(helper, source, index => JSON.stringify(`kernel:${index}`), { describe: true });
+        if ("failure" in compiled || "failure" in again) throw new Error("a failure");
+        expect(again.code).toBe(compiled.code);
+        expect(again.kernels).toEqual(compiled.kernels);
+    });
+});