@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/compiler/branches.ts

@@ -0,0 +1,45 @@
+import type { Node } from 'estree';
+import { set } from './booleans.js';
+import { dataValue, leavesOf, mapLeaves, sameShape, type Data } from './data.js';
+import { fail } from './failure.js';
+import { local, type Expression } from './ir.js';
+import type { Out } from './out.js';
+import type { Scope } from './scope.js';
+import { fresh } from './unit.js';
+import type { Value } from './value.js';
+
+const isTrivial = (expression: Expression): boolean =>
+    expression.kind === "local" || expression.kind === "number" || expression.kind === "boolean";
+
+/** Declares `let` locals for data's leaves, and returns them as data plus an assignment of other data to them. */
+export const temporaries = (data: Data, scope: Scope, out: Out): { readonly result: Data; readonly assign: (source: Data) => Out } => {
+    const locals = leavesOf(data).map(() => fresh(scope.unit, "t"));
+    let index = 0;
+    const result = mapLeaves(data, () => local(locals[index++]));
+    out.push({ kind: "declare", locals });
+    return { result, assign: source => leavesOf(source).map((leaf, leafIndex) => set(scope.unit, locals[leafIndex], leaf.expression, undefined)) };
+};
+
+/**
+ * The value of choosing between two branches on `test`: each leaf a conditional when neither branch emitted
+ * statements, else an `if` assigning temporaries.
+ */
+export const mergeBranches = (node: Node, test: Expression, consequent: Data, consequentOut: Out, alternate: Data, alternateOut: Out, scope: Scope, out: Out): Value => {
+    const unit = scope.unit;
+    if (!sameShape(consequent, alternate)) return fail(node, "both branches must have the same shape");
+    if (consequentOut.length === 0 && alternateOut.length === 0) {
+        let condition = test;
+        if (consequent.kind !== "leaf" && !isTrivial(test)) {
+            const name = fresh(unit, "test");
+            out.push(set(unit, name, test, "const"));
+            condition = local(name);
+        }
+        const alternateLeaves = leavesOf(alternate);
+        let index = 0;
+        return dataValue(mapLeaves(consequent, expression =>
+            ({ kind: "conditional", test: condition, consequent: expression, alternate: alternateLeaves[index++].expression })));
+    }
+    const { result, assign } = temporaries(consequent, scope, out);
+    out.push({ kind: "if", test, consequent: [...consequentOut, ...assign(consequent)], alternate: [...alternateOut, ...assign(alternate)] });
+    return dataValue(result);
+};

package/src/implementation/compiler/calls.ts

@@ -0,0 +1,384 @@
+import type { SimpleCallExpression, Expression as SourceExpression, Node, SpreadElement, Statement as SourceStatement } from 'estree';
+import { mergeBranches } from './branches.js';
+import { bind } from './bind.js';
+import { observe, set } from './booleans.js';
+import { access } from './access.js';
+import { dataValue, leavesOf, mapLeaves, materialize, toData } from './data.js';
+import { fail, within } from './failure.js';
+import { local, references, type Expression, type Statement } from './ir.js';
+import type { Program } from '../world/kernel.js';
+import { laneCount } from '../world/intrinsics.js';
+import type { Out } from './out.js';
+import { frameIn } from './module-value.js';
+import { scalar } from './scalar.js';
+import { childScope, findLocal, rootScope, type Scope } from './scope.js';
+import { fresh, keyIndex, spawnIndex } from './unit.js';
+import { scalarValue, type Value } from './value.js';
+
+const argument = (node: SourceExpression | SpreadElement): SourceExpression =>
+    node.type === "SpreadElement" ? fail(node, "spread arguments are not in the kernel subset") : node;
+
+const scalarArgument = (node: SourceExpression | SpreadElement, scope: Scope, out: Out): Expression => {
+    const expression = argument(node);
+    return scalar(scope.unit.expression(expression, scope, out), expression, scope);
+};
+
+/**
+ * A command's or spawn's value for the component `name` as data in a temporary, recording a tuple or struct, which only a
+ * component stored in linear memory takes.
+ */
+const commandValue = (name: string, node: Node, scope: Scope, out: Out): Expression => {
+    const data = toData(scope.unit.expression(node, scope, out), node, scope);
+    if (data.kind !== "leaf") scope.unit.structuredValues.add(name);
+    return temporary(scope, out, "value", observe(scope.unit, materialize(data)));
+};
+
+/** A value as a temporary, so command arguments are evaluated in source order before the command starts. */
+const temporary = (scope: Scope, out: Out, hint: string, value: Expression): Expression => {
+    if (value.kind === "local" || value.kind === "number" || value.kind === "boolean") return value;
+    const name = fresh(scope.unit, hint);
+    out.push(set(scope.unit, name, value, "const"));
+    return local(name);
+};
+
+/** The identifier a member chain `A.B.C` starts with, or the node itself. */
+const root = (node: Node): Node => node.type === "MemberExpression" ? root(node.object) : node;
+
+/**
+ * The keys a command's list of components names, as `Lists.names` reads them: an array literal's identifiers must not be
+ * the body's locals.
+ */
+const commandList = (node: Node, call: string, scope: Scope): readonly string[] => {
+    if (node.type === "ArrayExpression") for (const element of node.elements) if (element !== null && element.type !== "SpreadElement") commandName(element, scope);
+    const first = root(node);
+    if (first.type === "Identifier" && findLocal(scope, first.name) !== undefined) return fail(node, `${call}: ${first.name} is a local; commands name lists bound at module scope`);
+    const names = scope.unit.lists.names(node);
+    if ("error" in names) return fail(node, `${call}: ${names.error}`);
+    const twice = names.find((name, k) => names.indexOf(name) < k);
+    return twice === undefined ? names : fail(node, `${twice} is listed twice`);
+};
+
+/** A module-scope identifier naming a component in a command. */
+const commandName = (node: Node, scope: Scope): string =>
+    node.type === "Identifier" && findLocal(scope, node.name) === undefined && scope.module.bindings.has(node.name)
+        ? node.name
+        : fail(node, "commands name components by identifiers bound at module scope");
+
+const none = scalarValue({ kind: "nullish", value: "undefined" });
+const undefinedValue: Expression = { kind: "nullish", value: "undefined" };
+
+/**
+ * A list's values in its order, each given one evaluated into a temporary in source order, and every other component
+ * of the list `undefined`, which is its start.
+ */
+const listValues = (list: readonly string[], node: SourceExpression | SpreadElement | undefined, call: Node, scope: Scope, out: Out): readonly Expression[] => {
+    if (node?.type !== "ObjectExpression") return fail(node ?? call, "command values must be an object literal like { [position]: value }");
+    const given = new Map<string, Expression>();
+    for (const property of node.properties) {
+        if (property.type === "SpreadElement" || !property.computed) return fail(property, "command value keys must be computed component identifiers like [position]");
+        const name = commandName(property.key, scope);
+        if (!list.includes(name)) return fail(property.key, `${name} isn't one of the command's components`);
+        given.set(name, commandValue(name, property.value, scope, out));
+    }
+    return list.map(name => given.get(name) ?? undefinedValue);
+};
+
+/** A list's values as `(key index, value)` statements, as `listValues` gives them. */
+const commandValues = (list: readonly string[], node: SourceExpression | SpreadElement | undefined, call: Node, scope: Scope, out: Out): readonly Statement[] => {
+    const values = listValues(list, node, call, scope, out);
+    return list.map((name, k): Statement => ({ kind: "value", key: keyIndex(scope.unit, name), value: values[k] }));
+};
+
+/**
+ * A command's second argument as a list of components, or as one key's name: whatever its definition is (`Lists.component`).
+ * A body's local is one key, which `commandName` rejects.
+ */
+const componentOf = (node: Node, call: string, scope: Scope): readonly string[] | { readonly key: string } => {
+    if (node.type === "ArrayExpression") return commandList(node, call, scope);
+    const first = root(node);
+    if (first.type !== "Identifier" || findLocal(scope, first.name) !== undefined) return { key: commandName(node, scope) };
+    const named = scope.unit.lists.component(node);
+    switch (named.kind) {
+        case "list": return commandList(node, call, scope);
+        case "key": return { key: node.type === "Identifier" ? commandName(node, scope) : named.name };
+        case "error": return fail(node, `${call}: ${named.error}`);
+    }
+};
+
+/**
+ * `commands.spawn(components)(values)`: stages a spawn through the list's spawner, giving each of the components its
+ * value or its start, and reserving the entity.
+ */
+const spawn = (inner: SimpleCallExpression, node: SimpleCallExpression, scope: Scope, out: Out): Value => {
+    const [components, ...extra] = inner.arguments;
+    if (components === undefined || extra.length > 0 || node.arguments.length !== 1) return fail(node, "a spawn is commands.spawn(components)(values)");
+    const list = commandList(components, "commands.spawn", scope);
+    const values = listValues(list, node.arguments[0], node, scope, out);
+    const result = fresh(scope.unit, "spawned");
+    out.push({ kind: "spawn", local: result, list: spawnIndex(scope.unit, list), values });
+    return scalarValue(local(result));
+};
+
+const command = (name: string, node: SimpleCallExpression, scope: Scope, out: Out): Value => {
+    const [entity, second, third, ...rest] = node.arguments;
+    if (entity === undefined) return fail(node, `commands.${name} needs arguments`);
+    switch (name) {
+        case "spawn":
+            return fail(node, "a kernel calls the spawner where it gets it, as commands.spawn(components)(values)");
+        case "despawn":
+            out.push({ kind: "begin", command: 1, entity: temporary(scope, out, "entity", scalarArgument(entity, scope, out)) });
+            return none;
+        case "add": {
+            if (second === undefined || rest.length > 0) return fail(node, "an add is commands.add(entity, component, value) or commands.add(entity, components, values)");
+            const target = temporary(scope, out, "entity", scalarArgument(entity, scope, out));
+            const component = componentOf(argument(second), "commands.add", scope);
+            if (!("key" in component)) {
+                const values = commandValues(component, third, node, scope, out);
+                out.push({ kind: "begin", command: 2, entity: target }, ...values);
+                return none;
+            }
+            const key = keyIndex(scope.unit, component.key);
+            const value = third === undefined ? undefinedValue : commandValue(component.key, argument(third), scope, out);
+            out.push({ kind: "begin", command: 2, entity: target }, { kind: "value", key, value });
+            return none;
+        }
+        default: {
+            if (second === undefined || third !== undefined) return fail(node, "a remove is commands.remove(entity, component) or commands.remove(entity, components)");
+            const target = temporary(scope, out, "entity", scalarArgument(entity, scope, out));
+            const component = componentOf(argument(second), "commands.remove", scope);
+            const names = "key" in component ? [component.key] : component;
+            out.push({ kind: "begin", command: 3, entity: target }, ...names.map((key): Statement => ({ kind: "component", key: keyIndex(scope.unit, key) })));
+            return none;
+        }
+    }
+};
+
+/** Whether a statement returns somewhere outside nested functions and loops. */
+const containsReturn = (node: Node): boolean => {
+    switch (node.type) {
+        case "ReturnStatement": return true;
+        case "BlockStatement": return node.body.some(containsReturn);
+        case "IfStatement": return containsReturn(node.consequent) || (node.alternate !== null && node.alternate !== undefined && containsReturn(node.alternate));
+        default: return false;
+    }
+};
+
+const statementsOf = (node: SourceStatement): readonly SourceStatement[] => node.type === "BlockStatement" ? node.body : [node];
+
+/** Statements to run in order, each run in its scope: the statements of a block, then of the blocks after it. */
+type Segment = { readonly statements: readonly SourceStatement[]; readonly scope: Scope };
+
+/** A copy of a scope, so each branch of a split block declares its own locals. */
+const forkScope = (scope: Scope): Scope => ({ ...scope, locals: new Map(scope.locals) });
+
+/**
+ * A helper body's value. A return inside an `if` splits the block: each branch runs its own statements and then
+ * the rest of the block, and their returned values merge as a conditional would.
+ */
+const helperBlock = (name: string, segments: readonly Segment[], node: Node, out: Out): Value => {
+    const [segment, ...after] = segments;
+    if (segment === undefined) return fail(node, `${name} must end with return <value>`);
+    const { statements, scope } = segment;
+    const unit = scope.unit;
+    for (let index = 0; index < statements.length; index++) {
+        const statement = statements[index];
+        if (statement.type === "ReturnStatement") {
+            if (!statement.argument) return fail(statement, `${name} must return a value`);
+            return unit.expression(statement.argument, scope, out);
+        }
+        if (statement.type === "IfStatement" && containsReturn(statement)) {
+            const test = scalar(unit.expression(statement.test, scope, out), statement.test, scope);
+            const rest = (fork: Scope): Segment[] => [{ statements: statements.slice(index + 1), scope: fork }, ...after.map(next => ({ ...next, scope: forkScope(next.scope) }))];
+            const branch = (taken: SourceStatement | null | undefined, branchOut: Out): Value => {
+                const fork = forkScope(scope);
+                const own: Segment[] = taken === null || taken === undefined ? [] : [{ statements: statementsOf(taken), scope: childScope(fork) }];
+                return helperBlock(name, [...own, ...rest(fork)], statement, branchOut);
+            };
+            const consequentOut: Out = [];
+            const alternateOut: Out = [];
+            const consequent = toData(branch(statement.consequent, consequentOut), statement.consequent, scope);
+            const alternate = toData(branch(statement.alternate, alternateOut), statement, scope);
+            return mergeBranches(statement, test, consequent, consequentOut, alternate, alternateOut, scope, out);
+        }
+        unit.statement(statement, scope, out);
+    }
+    return helperBlock(name, after, node, out);
+};
+
+
+/** An argument's lanes as an intrinsic operand of `type`, or null if its shape doesn't match. */
+const operandLanes = (value: Value, type: Program.ValueType, node: SimpleCallExpression, scope: Scope): readonly Expression[] | null => {
+    const isLeaf = (item: Value): boolean => ["scalar", "dynamic", "found", "component", "snapshot"].includes(item.kind);
+    const count = laneCount(type);
+    if (count === 1) return isLeaf(value) ? [scalar(value, node, scope)] : null;
+    if (value.kind === "tuple") return value.items.length === count && value.items.every(isLeaf) ? value.items.map(item => scalar(item, node, scope)) : null;
+    if (value.kind === "component" || value.kind === "snapshot" || value.kind === "dynamic") {
+        return Array.from({ length: count }, (_, index) => scalar(access(value, { kind: "static", name: index }, node, scope, false), node, scope));
+    }
+    return null;
+};
+
+/**
+ * A GPU kernel's call to a function that matches a WGSL builtin, as an intrinsic region: its operands, and its inlined
+ * body, whose result lanes the region names. Each operand lane is read once by each backend where the call is: by the
+ * builtin, or by the body binding its parameters. Null where the call doesn't fit the declaration, so it is inlined
+ * as usual.
+ */
+const intrinsicCall = (helper: Extract<Value, { kind: "function" }>, intrinsic: Program.Intrinsic, values: readonly Value[], node: SimpleCallExpression, scope: Scope, out: Out, compile: (bind: (index: number) => Value, bodyOut: Out) => Value): Value | null => {
+    const unit = scope.unit;
+    if (intrinsic.parameters.length !== helper.params.length || values.length !== helper.params.length) return null;
+    const lanes = intrinsic.parameters.map((type, index) => operandLanes(values[index], type, node, scope));
+    if (lanes.some(item => item === null)) return null;
+    const operands = lanes.map(item => item ?? []);
+    const body: Out = [];
+    const result = toData(compile(index => {
+        const [first, ...rest] = operands[index] ?? [];
+        return first !== undefined && rest.length === 0 && laneCount(intrinsic.parameters[index] ?? "f32") === 1
+            ? scalarValue(first)
+            : { kind: "tuple", items: (operands[index] ?? []).map(scalarValue) };
+    }, body), node, scope);
+    const leaves = leavesOf(result);
+    const flat = laneCount(intrinsic.result) === 1 ? result.kind === "leaf" : result.kind === "tuple" && result.items.every(item => item.kind === "leaf");
+    if (!flat || leaves.length !== laneCount(intrinsic.result) || leaves.some(leaf => references(leaf.expression, item => item.kind === "column"))) {
+        out.push(...body);
+        return dataValue(result);
+    }
+    const id = unit.next();
+    out.push({ kind: "intrinsic", id, name: helper.name, intrinsic, operands, body });
+    let lane = 0;
+    return dataValue(mapLeaves(result, value => ({ kind: "lane", intrinsic: id, lane: lane++, value })));
+};
+
+/** Inlines a helper: arguments are bound to fresh parameter locals, and the body is compiled in the helper's own scope. */
+const inline = (helper: Extract<Value, { kind: "function" }>, node: SimpleCallExpression, scope: Scope, out: Out): Value => {
+    const unit = scope.unit;
+    if (unit.active.has(helper.identity)) return fail(node, `${helper.name} is recursive`);
+    if (node.arguments.length > helper.params.length) return fail(node, `${helper.name} takes ${helper.params.length} arguments`);
+    const values = node.arguments.map(item => unit.expression(argument(item), scope, out));
+    if (values.length < helper.params.length) return fail(node, `${helper.name} needs ${helper.params.length} arguments`);
+    unit.active.add(helper.identity);
+    const body = (argumentOf: (index: number) => Value, bodyOut: Out): Value => {
+        const compile = (): Value => {
+            const inner = rootScope(unit, true, helper.module);
+            helper.params.forEach((param, index) => bind(param, argumentOf(index), "parameter", inner, bodyOut));
+            return helper.body.type === "BlockStatement"
+                ? helperBlock(helper.name, [{ statements: helper.body.body, scope: inner }], helper.body, bodyOut)
+                : unit.expression(helper.body, inner, bodyOut);
+        };
+        return helper.module === unit.module ? compile() : within(node, frameIn(helper.module, helper.name), compile);
+    };
+    const argumentOf = (index: number): Value => values[index] ?? fail(node, `${helper.name} needs ${helper.params.length} arguments`);
+    const result = (unit.target === "gpu" && helper.intrinsic !== undefined ? intrinsicCall(helper, helper.intrinsic, values, node, scope, out, body) : null)
+        ?? body(argumentOf, out);
+    unit.active.delete(helper.identity);
+    return result;
+};
+
+/** The accumulator local of one leaf of a reduction, made at its first contribution. */
+const accumulator = (scope: Scope, reduced: number, path: readonly (number | string)[]): number => {
+    const unit = scope.unit;
+    const existing = unit.accumulators.find(entry => entry.reduced === reduced && JSON.stringify(entry.path) === JSON.stringify(path));
+    if (existing !== undefined) return existing.local;
+    const created = fresh(unit, "reduced");
+    unit.accumulators.push({ reduced, path, local: created });
+    return created;
+};
+
+/** `context[resource](value)`: folds each leaf of the value into its accumulator with the resource's operator. */
+const contribute = (reduced: number, node: SimpleCallExpression, scope: Scope, out: Out): Value => {
+    const { resource, operator } = scope.unit.signature.reduced[reduced] ?? fail(node, "unknown reduction");
+    if (node.arguments.length !== 1) return fail(node, `${resource} takes the one value it reduces`);
+    const value = toData(scope.unit.expression(argument(node.arguments[0]), scope, out), node, scope);
+    scope.unit.reducedShapes.add(`{ component: ${resource}, leaves: ${JSON.stringify(leavesOf(value).map(leaf => leaf.path))} }`);
+    for (const { path, expression } of leavesOf(value)) {
+        const target = accumulator(scope, reduced, path);
+        const folded: Expression = operator === "min" || operator === "max"
+            ? { kind: "math", name: operator, arguments: [local(target), expression] }
+            : { kind: "binary", operator, left: local(target), right: expression };
+        out.push(set(scope.unit, target, folded, undefined));
+    }
+    return none;
+};
+
+const comparisonOperators: ReadonlySet<string> = new Set(["==", "!=", "<", "<=", ">", ">="]);
+
+/** An object literal whose every key is a comparison's operator, so it's a comparison rather than a struct key part. */
+const comparisonOf = (node: SourceExpression): readonly (readonly [string, SourceExpression])[] | null => {
+    if (node.type !== "ObjectExpression" || node.properties.length === 0) return null;
+    const operators: [string, SourceExpression][] = [];
+    for (const property of node.properties) {
+        if (property.type !== "Property" || property.computed || property.kind !== "init" || property.method) return null;
+        const name = property.key.type === "Literal" && typeof property.key.value === "string" ? property.key.value : property.key.type === "Identifier" ? property.key.name : null;
+        if (name === null || !comparisonOperators.has(name) || property.value.type === "ObjectPattern" || property.value.type === "ArrayPattern"
+            || property.value.type === "AssignmentPattern" || property.value.type === "RestElement") return null;
+        operators.push([name, property.value]);
+    }
+    return operators;
+};
+
+/**
+ * A call of a lookup through an index: each argument a key part's value, given by its scalar leaves, and the last
+ * possibly a comparison literal. The call site gets its own list and first row, which the world binds to the index.
+ */
+const probe = (lookup: number, node: SimpleCallExpression, scope: Scope, out: Out): Value => {
+    const unit = scope.unit;
+    const values: Expression[] = [];
+    const leavesIn = (source: SourceExpression): string => {
+        const leaves = leavesOf(toData(unit.expression(source, scope, out), source, scope));
+        for (const leaf of leaves) values.push(temporary(scope, out, "key", observe(unit, leaf.expression)));
+        return JSON.stringify(leaves.map(leaf => leaf.path));
+    };
+    const parts = node.arguments.map((item, index) => {
+        const source = argument(item);
+        const comparison = comparisonOf(source);
+        if (comparison === null) return `{ kind: "value", paths: ${leavesIn(source)} }`;
+        if (index !== node.arguments.length - 1) return fail(source, "only a lookup's last key part may be a comparison");
+        return `{ kind: "comparison", operators: [${comparison.map(([operator, operand]) => `{ operator: ${JSON.stringify(operator)}, paths: ${leavesIn(operand)} }`).join(", ")}] }`;
+    });
+    const site = unit.probes.length;
+    unit.probes.push(`{ lookup: ${lookup}, arguments: [${parts.join(", ")}] }`);
+    const list = fresh(unit, "list");
+    const first = fresh(unit, "first");
+    unit.handles.add(list);
+    unit.handles.add(first);
+    out.push({ kind: "probe", list, first, lookup, probe: site, values });
+    return { kind: "indexed", lookup, list, first };
+};
+
+/** Compiles a call: a `Math` function, a command, a lookup, a reduction or a helper. */
+export const call = (node: SimpleCallExpression, scope: Scope, out: Out): Value => {
+    if (node.optional) return fail(node, "optional calls are not in the kernel subset");
+    if (node.callee.type === "Super") return fail(node, "super is not in the kernel subset");
+    if (node.callee.type === "CallExpression" && !node.callee.optional && node.callee.callee.type !== "Super") {
+        const maker = scope.unit.expression(node.callee.callee, scope, out);
+        if (maker.kind === "method" && maker.owner === "commands" && maker.name === "spawn") return spawn(node.callee, node, scope, out);
+    }
+    const callee = scope.unit.expression(node.callee, scope, out);
+    switch (callee.kind) {
+        case "method":
+            if (callee.owner === "commands") return command(callee.name, node, scope, out);
+            return scalarValue({ kind: "math", name: callee.name, arguments: node.arguments.map(item => scalarArgument(item, scope, out)) });
+        case "lookup": {
+            if (scope.unit.signature.lookups[callee.lookup]?.index === true) return probe(callee.lookup, node, scope, out);
+            if (node.arguments.length !== 1) return fail(node, "a lookup takes one entity");
+            const entity = scalarArgument(node.arguments[0], scope, out);
+            const found = fresh(scope.unit, "found");
+            out.push({ kind: "lookup", local: found, lookup: callee.lookup, entity });
+            return { kind: "found", lookup: callee.lookup, expression: local(found) };
+        }
+        case "listAt": {
+            if (node.arguments.length !== 1) return fail(node, "a list's at takes a row's position");
+            const index = scalarArgument(node.arguments[0], scope, out);
+            const row = fresh(scope.unit, "row");
+            scope.unit.handles.add(row);
+            out.push({ kind: "listRow", row, list: callee.list, lookup: callee.lookup, index });
+            return { kind: "indexRow", lookup: callee.lookup, row };
+        }
+        case "function":
+            return inline(callee, node, scope, out);
+        case "reducer":
+            return contribute(callee.reduced, node, scope, out);
+        default:
+            return fail(node.callee, "only Math functions, commands, lookups, reductions and helpers can be called");
+    }
+};

package/src/implementation/compiler/columns.ts

@@ -0,0 +1,46 @@
+import type { Path } from '../world/kernel.js';
+import type { Expression } from './ir.js';
+import type { Unit } from './unit.js';
+
+const column = (unit: Unit, identity: string, description: string): number => {
+    const existing = unit.columnIndex.get(identity);
+    if (existing !== undefined) return existing;
+    unit.columns.push(description);
+    unit.columnIndex.set(identity, unit.columns.length - 1);
+    return unit.columns.length - 1;
+};
+
+/** The column of a scalar leaf of a component. */
+export const fieldColumn = (unit: Unit, component: string, path: Path): number => {
+    const json = JSON.stringify(path);
+    return column(unit, `field ${component} ${json}`, `{ kind: "field", component: ${component}, path: ${json} }`);
+};
+
+export const fieldRead = (unit: Unit, component: string, path: Path): Expression => ({ kind: "column", column: fieldColumn(unit, component, path) });
+
+/** A component's changed column, immediately followed by its dense chunk column. */
+export const changedColumns = (unit: Unit, component: string): { readonly column: number; readonly chunks: number } => {
+    const changed = column(unit, `changed ${component}`, `{ kind: "changed", component: ${component} }`);
+    const chunks = column(unit, `chunks ${component}`, `{ kind: "chunks", component: ${component} }`);
+    unit.chunks.add(chunks);
+    return { column: changed, chunks };
+};
+
+/** A scalar leaf of a component of the row's parent, read through `up`. */
+export const upFieldRead = (unit: Unit, component: string, path: Path): Expression => {
+    const json = JSON.stringify(path);
+    const identity = `${component} ${json}`;
+    let column = unit.upColumnIndex.get(identity);
+    if (column === undefined) {
+        unit.upColumns.push(`{ kind: "field", component: ${component}, path: ${json} }`);
+        column = unit.upColumns.length - 1;
+        unit.upColumnIndex.set(identity, column);
+    }
+    return { kind: "upColumn", column };
+};
+
+/** A component leaf read, of the row or, through `up`, of its parent. */
+export const componentRead = (unit: Unit, value: { readonly component: string; readonly path: Path; readonly up?: true }, path: Path = []): Expression =>
+    value.up === true ? upFieldRead(unit, value.component, [...value.path, ...path]) : fieldRead(unit, value.component, [...value.path, ...path]);
+
+export const entityRead = (unit: Unit): Expression => ({ kind: "column", column: column(unit, "entity", `{ kind: "entity" }`) });

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

@@ -0,0 +1,139 @@
+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 { createLists } from './lists.js';
+import type { Module } from './module-scope.js';
+import { resolve, type Out } from './out.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 { rootScope } from './scope.js';
+import { signature } from './signature.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" }];
+
+/**
+ * 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 };
+
+/**
+ * Statements a GPU kernel can't contain: WGSL has no labeled multi-level branches, and loops aren't supported yet.
+ * Intrinsic regions emit their builtin, not their body.
+ */
+const loops = (statements: readonly Program.Statement[]): boolean => statements.some(statement => {
+    switch (statement.kind) {
+        case "block": case "loop": case "branch": case "branchIf": case "find": return true;
+        case "if": return loops(statement.consequent) || loops(statement.alternate);
+        default: return false;
+    }
+});
+
+/** `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 => {
+    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");
+    const lists = createLists(module, link, [declaration, body]);
+    const unit = createUnit(signature(declaration, module.bindings, lists), module, lists, expression, statement, link, target);
+    const scope = rootScope(unit, false);
+    const prelude: Out = [];
+    const rows: Out = [];
+    body.params.forEach((param, index) => bind(param, parameterValues[index] ?? { kind: "row" }, "const", scope, index === 0 ? rows : prelude));
+    if (body.body.type === "BlockStatement") {
+        for (const item of body.body.body) statement(item, scope, rows);
+    } else {
+        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);
+    const kernel = printStatements(unit, resolve(rows));
+    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);
+    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");
+        if (reduced.length > 0) fail(declaration, "a GPU kernel can't use reductions yet");
+        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]);
+    const locals = [
+        ...columns.map((_, index) => `const c${index} = columns[${index}];`),
+        ...resources.map((_, index) => `const r${index} = resources[${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`.
+        ...unit.up === null ? [] : [
+            `const ${localName(unit, unit.up)} = found ? true : null;`,
+            ...unit.upColumns.map((_, index) => `const u${index} = upColumns[${index}];`),
+        ],
+    ];
+    return {
+        description: url => [
+            "{",
+            `columns: [${columns.join(", ")}],`,
+            `shapes: [${[...unit.shapes].join(", ")}],`,
+            `resources: [${resources.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(", ")}],`],
+            ...ordered ? ["ordered: true,"] : [],
+            `keys: [${keys.join(", ")}],`,
+            `spawns: ${JSON.stringify(unit.spawns)},`,
+            `structuredValues: ${JSON.stringify([...unit.structuredValues].map(name => unit.keys.indexOf(name)).sort((a, b) => a - b))},`,
+            `url: ${url},`,
+            `program: ${serialize(program)},`,
+            `reducedShapes: [${[...unit.reducedShapes].join(", ")}],`,
+            `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)} }`;
+            }).join(", ")}],`,
+            "}",
+        ].join("\n"),
+        // 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].map(index => `const b${index} = booleans[${index}];`),
+            ...[...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) => {",
+            ...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,
+            "}",
+            ...accumulators.map((local, k) => `partials[partial + ${k}] = ${localName(unit, local)};`),
+            "};",
+            "}",
+        ].filter(line => line !== "").join("\n"),
+    };
+};