@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/compiler/print.ts

@@ -0,0 +1,104 @@
+import { chunkShift, type Path } from '../world/kernel.js';
+import type { Expression, Statement } from './ir.js';
+import { resolve, type Out } from './out.js';
+import { rowLabel } from './statement.js';
+import type { Unit } from './unit.js';
+
+/** A number as JS source that reads back as the same f64. */
+export const printNumber = (value: number): string =>
+    Number.isNaN(value) ? "NaN" : value === Infinity ? "Infinity" : Object.is(value, -0) ? "(-0)" : value < 0 ? `(${String(value)})` : String(value);
+
+const printPath = (path: Path): string => path.map(item => `[${JSON.stringify(item)}]`).join("");
+
+export const localName = (unit: Unit, local: number): string => `${unit.names.get(local) ?? "t"}_${local}`;
+
+/** Prints an expression. `observed` converts boolean column reads. */
+export const printExpression = (unit: Unit, expression: Expression, observed: boolean): string => {
+    const print = (item: Expression): string => printExpression(unit, item, observed);
+    switch (expression.kind) {
+        case "number": return printNumber(expression.value);
+        case "boolean": return String(expression.value);
+        case "column": {
+            const column = expression.column;
+            if (!observed) return `c${column}[x${column}]`;
+            unit.booleans.add(column);
+            return `(b${column} ? c${column}[x${column}] !== 0 : c${column}[x${column}])`;
+        }
+        case "upColumn": {
+            const column = expression.column;
+            const read = `u${column}[p * us${column} + uo${column}]`;
+            if (!observed) return read;
+            unit.upBooleans.add(column);
+            return `(ub${column} ? ${read} !== 0 : ${read})`;
+        }
+        case "resource": return `r${expression.index}${printPath(expression.path)}`;
+        case "args": return `args${printPath(expression.path)}`;
+        case "local": return localName(unit, expression.local);
+        case "unary": return `(${expression.operator}${print(expression.operand)})`;
+        case "binary": case "logical": return `(${print(expression.left)} ${expression.operator} ${print(expression.right)})`;
+        case "conditional": return `(${print(expression.test)} ? ${print(expression.consequent)} : ${print(expression.alternate)})`;
+        case "math": return `Math.${expression.name}(${expression.arguments.map(print).join(", ")})`;
+        case "observe": return printExpression(unit, expression.value, true);
+        case "lane": return print(expression.value);
+        // Lookups through indexes read through their reader, `l${lookup}`, and the handles each site holds.
+        case "listLength": return `l${expression.lookup}.length(${localName(unit, expression.list)})`;
+        case "listChanged": return `l${expression.lookup}.changed(${localName(unit, expression.list)})`;
+        case "rowLeaf": return `l${expression.lookup}.leaf(${localName(unit, expression.row)}, ${expression.leaf})`;
+        case "rowEntity": return `l${expression.lookup}.entity(${localName(unit, expression.row)})`;
+        case "rowFound": return `(${localName(unit, expression.row)}.f === 1 ? true : null)`;
+        case "nullish": return expression.value;
+        case "string": return JSON.stringify(expression.value);
+        case "element": return `${print(expression.object)}${expression.optional ? "?." : ""}[${print(expression.index)}]`;
+        case "array": return `[${expression.items.map(print).join(", ")}]`;
+        case "record": return `{ ${expression.fields.map(([name, item]) => `${JSON.stringify(name)}: ${print(item)}`).join(", ")} }`;
+    }
+};
+
+type Labels = ReadonlyMap<number, "block" | "loop">;
+
+const printStatement = (unit: Unit, statement: Statement, labels: Labels): string => {
+    const value = (item: Expression): string => printExpression(unit, item, false);
+    const branch = (label: number): string => `${labels.get(label) === "loop" ? "continue" : "break"} label_${label};`;
+    switch (statement.kind) {
+        case "set": {
+            const declare = statement.declare === undefined ? "" : `${statement.declare} `;
+            return `${declare}${localName(unit, statement.local)} = ${printExpression(unit, statement.value, unit.observed.has(statement.local))};`;
+        }
+        case "declare": return `let ${statement.locals.map(item => localName(unit, item)).join(", ")};`;
+        case "store": return `c${statement.column}[x${statement.column}] = ${value(statement.value)};`;
+        case "stamp": {
+            const row = `c${statement.column}[x${statement.column}] = tick;`;
+            return unit.stampedPerCall.has(statement.chunks) ? row : `${row}\nc${statement.chunks}[i >> ${chunkShift}] = tick;`;
+        }
+        case "if": {
+            const alternate = printStatements(unit, statement.alternate, labels);
+            return `if (${value(statement.test)}) {\n${printStatements(unit, statement.consequent, labels)}\n}${alternate === "" ? "" : ` else {\n${alternate}\n}`}`;
+        }
+        case "block":
+            return `label_${statement.label}: {\n${printStatements(unit, statement.body, new Map([...labels, [statement.label, "block"]]))}\n}`;
+        case "loop": {
+            // `for (;;)` repeats where a WASM loop falls off its end, so a trailing branch back is implicit, and otherwise the loop exits.
+            const body = resolve(statement.body);
+            const last = body[body.length - 1];
+            const repeats = last?.kind === "branch" && last.label === statement.label;
+            const inner = new Map([...labels, [statement.label, "loop" as const]]);
+            const printed = printStatements(unit, repeats ? body.slice(0, -1) : body, inner);
+            return `label_${statement.label}: for (;;) {\n${printed}${repeats ? "" : `\nbreak label_${statement.label};`}\n}`;
+        }
+        case "branch": return branch(statement.label);
+        case "branchIf": return `if (${value(statement.test)}) ${branch(statement.label)}`;
+        case "next": return `continue ${rowLabel};`;
+        case "intrinsic": return printStatements(unit, statement.body, labels);
+        case "lookup": return `const ${localName(unit, statement.local)} = l${statement.lookup}(${value(statement.entity)});`;
+        case "probe": return `l${statement.lookup}.probe(${[statement.probe, localName(unit, statement.list), localName(unit, statement.first), ...statement.values.map(value)].join(", ")});`;
+        case "listRow": return `l${statement.lookup}.row(${localName(unit, statement.row)}, ${localName(unit, statement.list)}, ${value(statement.index)});`;
+        case "spawn": return `const ${localName(unit, statement.local)} = spawn${statement.list}(${statement.values.map(value).join(", ")});`;
+        case "begin": return `commands.begin(${statement.command}, ${value(statement.entity)});`;
+        case "value": return `commands.value(${statement.key}, ${value(statement.value)});`;
+        case "component": return `commands.component(${statement.key});`;
+    }
+};
+
+/** Prints statements as JS. */
+export const printStatements = (unit: Unit, statements: Out | readonly Statement[], labels: Labels = new Map()): string =>
+    resolve([...statements]).map(statement => printStatement(unit, statement, labels)).join("\n");

package/src/implementation/compiler/program.ts

@@ -0,0 +1,232 @@
+import type { Path, Program } from '../world/kernel.js';
+import type { Expression, Statement } from './ir.js';
+import { resolve } from './out.js';
+
+const all = <T, R>(items: readonly T[], map: (item: T) => R | undefined): R[] | undefined => {
+    const result: R[] = [];
+    for (const item of items) {
+        const mapped = map(item);
+        if (mapped === undefined) return undefined;
+        result.push(mapped);
+    }
+    return result;
+};
+
+const unwrap = (node: Expression): Expression => node.kind === "observe" ? unwrap(node.value) : node;
+
+type Guards = ReadonlySet<number>;
+const union = (a: Guards, b: Guards): Guards => new Set([...a, ...b]);
+const none: Guards = new Set();
+/** The handle standing for `up`, which isn't looked up. */
+const upHandle = -1;
+
+/**
+ * Derives a `Program` from the lowered body, or null if it uses what WASM kernels don't support. Locals are renumbered
+ * densely, branch labels become depths counting enclosing blocks and loops, and each lookup call site gets a handle.
+ * A lookup result may only be null-tested or read by a static leaf access; a non-optional access must be under a
+ * guard proving the lookup found its entity, since JS would throw where WASM reads NaN. With `nameOf`, the program
+ * carries each local's name.
+ */
+export const toProgram = (statements: readonly Statement[], nameOf?: (local: number) => string, accumulators: readonly number[] = [], upLocal: number | null = null, listed = upLocal !== null): Program | null => {
+    const locals = new Map<number, number>();
+    const localIndex = (local: number): number => {
+        const existing = locals.get(local);
+        if (existing !== undefined) return existing;
+        locals.set(local, locals.size);
+        return locals.size - 1;
+    };
+    /** Handles by the local holding a lookup result. */
+    const handles = new Map<number, number>();
+    const handleOf = (node: Expression): number | undefined => {
+        const inner = unwrap(node);
+        // A row a lookup through an index gave tests as found, as a lookup's result does.
+        if (inner.kind === "rowFound") return handleFor(inner.row);
+        return inner.kind !== "local" ? undefined : inner.local === upLocal ? upHandle : handles.get(inner.local);
+    };
+    /** The handle of a local holding a lookup through an index's list or row, made at its first use. */
+    const handleFor = (local: number): number => {
+        const existing = handles.get(local);
+        if (existing !== undefined) return existing;
+        handles.set(local, handles.size);
+        return handles.size - 1;
+    };
+    /** Whether `handle` found its entity, or for `up`, whether the call's rows have a parent. */
+    const found = (handle: number): Program.Expression => handle === upHandle ? { kind: "upFound" } : { kind: "found", handle };
+    const isNull = (node: Expression): boolean => {
+        const inner = unwrap(node);
+        return inner.kind === "nullish" && inner.value === "null";
+    };
+    /** `handle` and whether the test means "found", for `other !== null` and its variants. */
+    const nullTest = (node: Expression): { readonly handle: number; readonly found: boolean } | undefined => {
+        if (node.kind !== "binary" || !["===", "!==", "==", "!="].includes(node.operator)) return undefined;
+        const handle = isNull(node.right) ? handleOf(node.left) : isNull(node.left) ? handleOf(node.right) : undefined;
+        return handle === undefined ? undefined : { handle, found: node.operator === "!==" || node.operator === "!=" };
+    };
+    /** Handles a test proves found when it is `truthy`. */
+    const proves = (node: Expression, truthy: boolean): Guards => {
+        const inner = unwrap(node);
+        const handle = handleOf(inner);
+        if (handle !== undefined) return truthy ? new Set([handle]) : none;
+        const test = nullTest(inner);
+        if (test !== undefined) return test.found === truthy ? new Set([test.handle]) : none;
+        if (inner.kind === "unary" && inner.operator === "!") return proves(inner.operand, !truthy);
+        if (inner.kind === "logical" && inner.operator === (truthy ? "&&" : "||")) return union(proves(inner.left, truthy), proves(inner.right, truthy));
+        return none;
+    };
+    /** A static leaf access into a lookup result, or undefined if `node` isn't one. */
+    const leaf = (node: Expression, guards: Guards): Program.Expression | null | undefined => {
+        const keys: Expression[] = [];
+        let first: Expression = node;
+        let optional = false;
+        while (first.kind === "element") {
+            keys.unshift(first.index);
+            optional = first.optional;
+            first = first.object;
+        }
+        const handle = handleOf(first);
+        if (handle === undefined) return undefined;
+        if (handle === upHandle) return null;
+        const [read, ...rest] = keys;
+        if (read?.kind !== "number" || (!optional && !guards.has(handle))) return null;
+        const path: (number | string)[] = [];
+        for (const key of rest) {
+            if (key.kind !== "number" && key.kind !== "string") return null;
+            path.push(key.value);
+        }
+        const leafPath: Path = path;
+        return { kind: "lookupLeaf", handle, read: read.value, path: leafPath };
+    };
+    /** `test` is set where only truthiness matters, so a lookup result may stand for `found`. */
+    const expression = (node: Expression, guards: Guards, test: boolean): Program.Expression | undefined => {
+        const handle = handleOf(node);
+        if (handle !== undefined) return test ? found(handle) : undefined;
+        const check = nullTest(node);
+        if (check !== undefined) {
+            const tested = found(check.handle);
+            return check.found ? tested : { kind: "unary", operator: "!", operand: tested };
+        }
+        switch (node.kind) {
+            case "number": case "boolean": case "column": case "resource": case "args":
+                return node;
+            // JS throws reading a parent that isn't there, so WASM reads one only where a test proves it is.
+            case "upColumn": return guards.has(upHandle) ? { kind: "upLeaf", column: node.column } : undefined;
+            case "local": return { kind: "local", local: localIndex(node.local) };
+            case "unary": {
+                const operand = expression(node.operand, guards, node.operator === "!");
+                return operand && { kind: "unary", operator: node.operator, operand };
+            }
+            case "binary": {
+                const left = expression(node.left, guards, false);
+                const right = expression(node.right, guards, false);
+                return left && right && { kind: "binary", operator: node.operator, left, right };
+            }
+            case "logical": {
+                if (node.operator === "??") return undefined;
+                const left = expression(node.left, guards, test);
+                const right = expression(node.right, node.operator === "&&" ? union(guards, proves(node.left, true)) : union(guards, proves(node.left, false)), test);
+                return left && right && { kind: "logical", operator: node.operator, left, right };
+            }
+            case "conditional": {
+                const condition = expression(node.test, guards, true);
+                const consequent = expression(node.consequent, union(guards, proves(node.test, true)), test);
+                const alternate = expression(node.alternate, union(guards, proves(node.test, false)), test);
+                return condition && consequent && alternate && { kind: "conditional", test: condition, consequent, alternate };
+            }
+            case "math": {
+                const items = all(node.arguments, item => expression(item, guards, false));
+                return items && { kind: "math", name: node.name, arguments: items };
+            }
+            case "observe": return expression(node.value, guards, test);
+            case "lane": {
+                const value = expression(node.value, guards, false);
+                return value && { kind: "lane", intrinsic: node.intrinsic, lane: node.lane, value };
+            }
+            case "element": return leaf(node, guards) ?? undefined;
+            // A row's leaves read NaN where there's no row, in JS kernels as in WASM, so they need no guard.
+            case "listLength": return { kind: "listLength", handle: handleFor(node.list) };
+            case "listChanged": return { kind: "listChanged", handle: handleFor(node.list) };
+            case "rowLeaf": return { kind: "rowLeaf", handle: handleFor(node.row), leaf: node.leaf };
+            case "rowEntity": return { kind: "rowEntity", handle: handleFor(node.row) };
+            default: return undefined;
+        }
+    };
+    let intrinsics = 0;
+    const exits = (body: readonly Statement[]): boolean => body[body.length - 1]?.kind === "next";
+    const block = (body: readonly Statement[], labels: readonly number[], outer: Guards): Program.Statement[] | undefined => {
+        let guards = outer;
+        const result: Program.Statement[] = [];
+        for (const item of body) {
+            const converted = statement(item, labels, guards);
+            if (converted === undefined) return undefined;
+            result.push(...converted);
+            // `if (other === null) return;` guards the rest of the block.
+            if (item.kind === "if") {
+                if (exits(resolve(item.consequent))) guards = union(guards, proves(item.test, false));
+                if (exits(resolve(item.alternate))) guards = union(guards, proves(item.test, true));
+            }
+        }
+        return result;
+    };
+    const depth = (label: number, labels: readonly number[]): number => labels.length - 1 - labels.lastIndexOf(label);
+    const statement = (node: Statement, labels: readonly number[], guards: Guards): Program.Statement[] | undefined => {
+        switch (node.kind) {
+            case "set": {
+                const value = expression(node.value, guards, false);
+                return value && [{ kind: "set", local: localIndex(node.local), value }];
+            }
+            case "declare":
+                for (const item of node.locals) localIndex(item);
+                return [];
+            case "store": {
+                const value = expression(node.value, guards, false);
+                return value && [{ kind: "store", column: node.column, value }];
+            }
+            case "stamp": case "next":
+                return [node];
+            case "if": {
+                const test = expression(node.test, guards, true);
+                const consequent = block(resolve(node.consequent), labels, union(guards, proves(node.test, true)));
+                const alternate = block(resolve(node.alternate), labels, union(guards, proves(node.test, false)));
+                return test && consequent && alternate && [{ kind: "if", test, consequent, alternate }];
+            }
+            case "block": case "loop": {
+                const body = block(resolve(node.body), [...labels, node.label], guards);
+                return body && [{ kind: node.kind, body }];
+            }
+            case "branch": return [{ kind: "branch", depth: depth(node.label, labels) }];
+            case "intrinsic": {
+                const operands = all(node.operands, lanes => all(lanes, lane => expression(lane, guards, false)));
+                const body = block(resolve(node.body), labels, guards);
+                intrinsics = Math.max(intrinsics, node.id + 1);
+                return operands && body && [{ kind: "intrinsic", id: node.id, name: node.name, intrinsic: node.intrinsic, operands, body }];
+            }
+            case "branchIf": {
+                const test = expression(node.test, guards, true);
+                return test && [{ kind: "branchIf", depth: depth(node.label, labels), test }];
+            }
+            case "probe": {
+                const values = all(node.values, item => expression(item, guards, false));
+                return values && [{ kind: "probe", list: handleFor(node.list), first: handleFor(node.first), probe: node.probe, values }];
+            }
+            case "listRow": {
+                const index = expression(node.index, guards, false);
+                return index && [{ kind: "listRow", row: handleFor(node.row), list: handleFor(node.list), index }];
+            }
+            case "lookup": {
+                const entity = expression(node.entity, guards, false);
+                const handle = handles.get(node.local) ?? handles.size;
+                handles.set(node.local, handle);
+                return entity && [{ kind: "find", handle, lookup: node.lookup, entity }];
+            }
+            default: return undefined;
+        }
+    };
+    const body = block(statements, [], none);
+    if (body === undefined) return null;
+    const counted = { ...intrinsics === 0 ? {} : { intrinsics }, ...accumulators.length === 0 ? {} : { reductions: accumulators.map(localIndex) } };
+    if (listed) Object.assign(counted, { up: true });
+    if (nameOf === undefined) return { locals: locals.size, handles: handles.size, ...counted, body };
+    const names: string[] = [];
+    for (const [original, dense] of locals) names[dense] = nameOf(original);
+    return { locals: locals.size, handles: handles.size, names, ...counted, body };
+};

package/src/implementation/compiler/scalar.ts

@@ -0,0 +1,46 @@
+import type { Node } from 'estree';
+import { componentRead, fieldRead } from './columns.js';
+import { fail } from './failure.js';
+import type { Scope } from './scope.js';
+import { local, type Expression } from './ir.js';
+import { snapshotLeaf } from './snapshot.js';
+import { describeValue, type Value } from './value.js';
+
+/** The `rowLeaves` index of a leaf bodies read of a lookup's rows, listed once. */
+const rowLeafIndex = (unit: Scope["unit"], lookup: number, read: number, path: readonly (number | string)[]): number => {
+    const text = JSON.stringify([lookup, read, path]);
+    const index = unit.rowLeaves.indexOf(text);
+    if (index >= 0) return index;
+    unit.rowLeaves.push(text);
+    return unit.rowLeaves.length - 1;
+};
+
+/** A component in `write` is readable too. */
+export const requireReadable = (node: Node, scope: Scope, component: string): void => {
+    const { signature } = scope.unit;
+    if (!signature.read.has(component) && !signature.write.has(component)) fail(node, `${component} is not in components read or write`);
+    scope.unit.used.read.add(component);
+};
+
+/** A value used as a number or boolean. A component of unknown shape is read as a scalar. */
+export const scalar = (value: Value, node: Node, scope: Scope): Expression => {
+    switch (value.kind) {
+        case "scalar": case "dynamic": case "found":
+            return value.expression;
+        case "component":
+            if (value.up === true) return componentRead(scope.unit, value);
+            requireReadable(node, scope, value.component);
+            return fieldRead(scope.unit, value.component, value.path);
+        case "snapshot":
+            return local(snapshotLeaf(scope.unit, value.snapshot, value.path));
+        // A row tests as found, so a unique index's result compares with null as a lookup's does.
+        case "indexed":
+            return { kind: "rowFound", row: value.first, lookup: value.lookup };
+        case "indexRow":
+            return { kind: "rowFound", row: value.row, lookup: value.lookup };
+        case "rowRead":
+            return { kind: "rowLeaf", row: value.row, lookup: value.lookup, leaf: rowLeafIndex(scope.unit, value.lookup, value.read, value.path) };
+        default:
+            return fail(node, `expected a number or boolean, not ${describeValue(value)}`);
+    }
+};

package/src/implementation/compiler/scope.ts

@@ -0,0 +1,27 @@
+import type { Module } from './module-scope.js';
+import type { Unit } from './unit.js';
+import type { Value } from './value.js';
+
+export type Local = { readonly value: Value; readonly mutable: boolean };
+
+/** The labels `break` and `continue` branch to. */
+export type Loop = { readonly exit: number; readonly next: number };
+
+/** A lexical scope. A helper's scope has no parent, so it sees only its parameters and its module's scope, `module`. */
+export type Scope = {
+    readonly unit: Unit;
+    readonly module: Module;
+    readonly locals: Map<string, Local>;
+    readonly parent: Scope | undefined;
+    readonly loop: Loop | undefined;
+    readonly helper: boolean;
+};
+
+export const rootScope = (unit: Unit, helper: boolean, module: Module = unit.module): Scope =>
+    ({ unit, module, locals: new Map(), parent: undefined, loop: undefined, helper });
+
+export const childScope = (scope: Scope, loop: Loop | undefined = scope.loop): Scope =>
+    ({ unit: scope.unit, module: scope.module, locals: new Map(), parent: scope, loop, helper: scope.helper });
+
+export const findLocal = (scope: Scope | undefined, name: string): Local | undefined =>
+    scope === undefined ? undefined : scope.locals.get(name) ?? findLocal(scope.parent, name);

package/src/implementation/compiler/serialize.ts

@@ -0,0 +1,10 @@
+import { printNumber } from './print.js';
+
+/** Data as a JS literal; unlike JSON, it keeps NaN, infinities and -0. */
+export const serialize = (value: unknown): string => {
+    if (typeof value === "number") return printNumber(value);
+    if (typeof value === "string" || typeof value === "boolean" || value === null) return JSON.stringify(value);
+    if (Array.isArray(value)) return `[${value.map(serialize).join(", ")}]`;
+    if (typeof value === "object") return `{ ${Object.entries(value).map(([key, item]) => `${JSON.stringify(key)}: ${serialize(item)}`).join(", ")} }`;
+    return "undefined";
+};

package/src/implementation/compiler/signature.ts

@@ -0,0 +1,170 @@
+import type { Expression, ObjectExpression, Property, SpreadElement, Pattern } from 'estree';
+import type { Reduction } from '../../interface/resource/reduction.js';
+import { isReduction, reductionOperators } from '../../interface/registry/reduction.js';
+import { fail } from './failure.js';
+import type { Lists } from './lists.js';
+import type { ModuleScope } from './module-scope.js';
+
+/**
+ * A lookup by entity, or through an index (`index`), whose calls take a key and give a list of rows. A lookup by
+ * entity that `watches` declares `changed`: its result has `changed` after what it reads.
+ */
+export type Lookup = { readonly name: string; readonly read: readonly string[]; readonly index: boolean; readonly watches: boolean };
+
+/** The reference rows run down, and what the context's `up` reads of the entity it names. */
+export type Up = { readonly through: string; readonly read: readonly string[] };
+
+/** A resource the kernel reduces into, by its module-scope binding name. */
+export type Reduced = { readonly resource: string; readonly operator: Reduction };
+
+/**
+ * The parts of a kernel declaration the compiler needs. Component and resource keys are expressions of the kernel's
+ * module: its module-scope bindings, or, for a key only another module's list names, that list indexed (`lists.ts`).
+ */
+export type Signature = {
+    readonly read: ReadonlySet<string>;
+    readonly write: ReadonlySet<string>;
+    readonly resources: readonly string[];
+    readonly reduced: readonly Reduced[];
+    readonly lookups: readonly Lookup[];
+    readonly up: Up | null;
+    /** Whether its rows run in an index's order, as a list, as `up`'s do. */
+    readonly ordered: boolean;
+    readonly input: boolean;
+    /** Whether it filters on `added` or `changed` components, or on changed resources. */
+    readonly filtered: boolean;
+};
+
+const entry = <T>(name: string, value: T): readonly [string, T] => [name, value];
+
+const propertyName = (property: Property): string => {
+    if (!property.computed && property.key.type === "Identifier") return property.key.name;
+    if (property.key.type === "Literal" && typeof property.key.value === "string") return property.key.value;
+    return fail(property.key, "kernel declaration keys must be plain names");
+};
+
+const properties = (node: Expression | Pattern, what: string): readonly (readonly [string, Property])[] => {
+    if (node.type !== "ObjectExpression") return fail(node, `${what} must be an object literal in a kernel declaration`);
+    return node.properties.map((property: Property | SpreadElement) => property.type === "SpreadElement"
+        ? fail(property, `${what} can't use spread in a kernel declaration`)
+        : entry(propertyName(property), property));
+};
+
+/** Keys a kernel declaration lists, as `Lists.names` reads them; `what` names the list in a failure. */
+const identifiers = (node: Expression | Pattern, what: string, lists: Lists): readonly string[] => {
+    const names = lists.names(node);
+    return "error" in names ? fail(node, `${what}: ${names.error}`) : names;
+};
+
+const keyLists = (node: Expression | Pattern, what: string, allowed: readonly string[], lists: Lists): ReadonlyMap<string, readonly string[]> =>
+    new Map(properties(node, what).map(([name, property]) => allowed.includes(name)
+        ? entry(name, identifiers(property.value, `${what}.${name}`, lists))
+        : fail(property, `${what}.${name} is not allowed in a kernel declaration`)));
+
+/** `reduce: { [resource]: "operator", ... }`, with resources bound at module scope. */
+const reductions = (node: Expression | Pattern, module: ModuleScope): readonly Reduced[] => {
+    if (node.type !== "ObjectExpression") return fail(node, "reduce must be an object literal in a kernel declaration");
+    return node.properties.map((property): Reduced => {
+        if (property.type === "SpreadElement" || !property.computed || property.key.type !== "Identifier" || !module.has(property.key.name)) {
+            return fail(property, "reduce names each resource as a computed key bound at module scope, as in { [total]: \"+\" }");
+        }
+        const { value } = property;
+        const operator = value.type === "Literal" ? value.value : undefined;
+        if (!isReduction(operator)) return fail(value, `a resource is reduced with one of ${reductionOperators.map(item => JSON.stringify(item)).join(", ")}`);
+        return { resource: property.key.name, operator };
+    }).map((entry, index, all) => all.findIndex(other => other.resource === entry.resource) === index ? entry : fail(node, `${entry.resource} is reduced twice`));
+};
+
+/** What kind of kernel a `System.create` declaration compiles to, or null when it isn't a kernel. */
+export const kernelOf = (declaration: ObjectExpression): "cpu" | "gpu" | null => {
+    for (const property of declaration.properties) {
+        if (property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === "kernel") {
+            const { value } = property;
+            if (value.type === "Literal" && (value.value === "cpu" || value.value === "gpu")) return value.value;
+            return fail(value, `kernel must be the literal "cpu" or "gpu"`);
+        }
+    }
+    return null;
+};
+
+/** Reads and validates a kernel declaration; `lists` reads its lists of keys. */
+export const signature = (declaration: ObjectExpression, module: ModuleScope, lists: Lists): Signature => {
+    let components: ReadonlyMap<string, readonly string[]> | undefined;
+    let resources: readonly string[] = [];
+    let reduced: readonly Reduced[] = [];
+    let changedResources: readonly string[] = [];
+    let input = false;
+    let up: Up | null = null;
+    let ordered = false;
+    const lookups: Lookup[] = [];
+    for (const [name, property] of properties(declaration, "a kernel declaration")) {
+        switch (name) {
+            case "components":
+                components = keyLists(property.value, "components", ["read", "write", "has", "not", "added", "changed"], lists);
+                break;
+            case "resources":
+                for (const [list, value] of properties(property.value, "resources")) {
+                    // A condition in `is` is readable too; one in `not` is only checked before the kernel runs.
+                    if (list === "read" || list === "is") resources = [...resources, ...identifiers(value.value, `resources.${list}`, lists)];
+                    else if (list === "changed") changedResources = identifiers(value.value, "resources.changed", lists);
+                    else if (list === "not") continue;
+                    else fail(value, `resources.${list} is not allowed in a kernel declaration`);
+                }
+                break;
+            case "reduce":
+                reduced = reductions(property.value, module);
+                break;
+            case "lookup":
+                for (const [lookup, value] of properties(property.value, "lookup")) {
+                    // The index is a value the world resolves; only that a lookup goes through one changes how it compiles.
+                    const fields = properties(value.value, `lookup.${lookup}`);
+                    const index = fields.some(([field]) => field === "index");
+                    const listed = fields.filter(([field]) => field !== "index");
+                    const read = listed.flatMap(([field, item]) => {
+                        if (index ? field !== "read" && field !== "changed" : field !== "read" && field !== "has" && field !== "not" && field !== "changed") return fail(item, `lookup.${lookup}.${field} is not allowed in a kernel declaration`);
+                        // An index lookup's `changed: true` filters the system's runs, which the world does before calling it.
+                        if (index && field === "changed" && item.value.type === "Literal" && item.value.value === true) return [];
+                        const names = identifiers(item.value, `lookup.${lookup}.${field}`, lists);
+                        return field === "read" ? names : [];
+                    });
+                    lookups.push({ name: lookup, read, index, watches: !index && listed.some(([field]) => field === "changed") });
+                }
+                break;
+            case "up": {
+                let through: string | undefined;
+                let read: readonly string[] = [];
+                for (const [field, value] of properties(property.value, "up")) {
+                    if (field === "through") {
+                        const node = value.value;
+                        through = node.type === "Identifier" && module.has(node.name) ? node.name : fail(node, "up.through is an identifier bound at module scope");
+                    }
+                    else if (field === "read") read = identifiers(value.value, "up.read", lists);
+                    else fail(value, `up.${field} is not allowed in a kernel declaration`);
+                }
+                up = { through: through ?? fail(property, "up needs through"), read };
+                break;
+            }
+            case "input":
+                input = true;
+                break;
+            // The index is a value the world resolves; only that rows run as a list changes how it compiles.
+            case "order":
+                ordered = true;
+                break;
+            case "name": case "kernel": case "before": case "after": case "during":
+                break;
+            default:
+                fail(property, `${name} is not allowed in a kernel declaration`);
+        }
+    }
+    if (components === undefined) return fail(declaration, "a kernel needs components");
+    for (const { resource } of reduced) {
+        if (resources.includes(resource) || changedResources.includes(resource)) fail(declaration, `${resource} is reduced, so it can't also be read or filtered on`);
+    }
+    const write = components.get("write") ?? [];
+    const both = (components.get("read") ?? []).find(key => write.includes(key));
+    if (both !== undefined) fail(declaration, `${both} is in both components read and write; write already makes it readable`);
+    const rowFiltered = (components.get("added")?.length ?? 0) + (components.get("changed")?.length ?? 0) > 0;
+    if (up !== null && ordered) fail(declaration, "a kernel can't use both up and order, which both decide the order of its rows");
+    return { read: new Set(components.get("read")), write: new Set(write), resources, reduced, lookups, up, ordered, input, filtered: changedResources.length > 0 || rowFiltered };
+};

package/src/implementation/compiler/snapshot.ts

@@ -0,0 +1,34 @@
+import type { Path } from '../world/kernel.js';
+import { record } from './booleans.js';
+import type { Expression, Statement } from './ir.js';
+import { fresh, type Unit } from './unit.js';
+
+/**
+ * A local bound to a component value of unknown shape. Each leaf the body uses becomes its own local,
+ * set where the snapshot was bound, so later writes to the component don't change it.
+ */
+export type Snapshot = {
+    readonly keyword: "const" | "let";
+    readonly hint: string;
+    readonly read: (path: Path) => Expression;
+    readonly leaves: Map<string, { readonly local: number; readonly value: Expression }>;
+};
+
+export const createSnapshot = (keyword: "const" | "let", hint: string, read: (path: Path) => Expression): Snapshot =>
+    ({ keyword, hint, read, leaves: new Map() });
+
+/** The local holding one leaf of `snapshot`. */
+export const snapshotLeaf = (unit: Unit, snapshot: Snapshot, path: Path): number => {
+    const identity = JSON.stringify(path);
+    const existing = snapshot.leaves.get(identity);
+    if (existing !== undefined) return existing.local;
+    const local = fresh(unit, snapshot.hint);
+    const value = snapshot.read(path);
+    record(unit, local, value);
+    snapshot.leaves.set(identity, { local, value });
+    return local;
+};
+
+/** The leaves the body used, resolved after the body is compiled. */
+export const snapshotDeclaration = (snapshot: Snapshot) => (): readonly Statement[] =>
+    [...snapshot.leaves.values()].map(leaf => ({ kind: "set", local: leaf.local, value: leaf.value, declare: snapshot.keyword }));