@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/compiler/source-map.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "vitest";
+import { decodeMappings, insertInto } from "./source-map.js";
+
+describe("insertInto", () => {
+    const source = `const a = Symbol("a");\nexport const b = Symbol("b"); const after = 2;\n`;
+    const insertions = [
+        { at: source.indexOf(`Symbol("a")`), text: "wrap(" },
+        { at: source.indexOf(`Symbol("a")`) + `Symbol("a")`.length, text: `, "a")` },
+        { at: source.indexOf(`Symbol("b")`), text: "wrap(" },
+        { at: source.indexOf(`Symbol("b")`) + `Symbol("b")`.length, text: `, "b")` },
+        { at: source.length, text: "\nfunction wrap(value) { return value; }\n" },
+    ];
+
+    test("makes the insertions in order of offset, those at one offset in the order given", () => {
+        const { code } = insertInto("ab", [{ at: 1, text: "2" }, { at: 0, text: "0" }, { at: 1, text: "3" }], "x.ts");
+        expect(code).toBe("0a23b");
+        expect(insertInto(source, insertions, "src/keys.ts").code).toBe(`const a = wrap(Symbol("a"), "a");\nexport const b = wrap(Symbol("b"), "b"); const after = 2;\n\nfunction wrap(value) { return value; }\n`);
+    });
+
+    test("maps the start of every word of the source to itself, with a segment of its own", () => {
+        const { code, map } = insertInto(source, insertions, "src/keys.ts");
+        expect({ sources: map.sources, sourcesContent: map.sourcesContent, version: map.version }).toEqual({ sources: ["src/keys.ts"], sourcesContent: [source], version: 3 });
+        const generated = code.split("\n");
+        const lines = decodeMappings(map.mappings);
+        const original = source.split("\n");
+        for (let line = 0; line < 2; line++) {
+            for (const match of (original[line] ?? "").matchAll(/[\w$]+/g)) {
+                const word = match[0];
+                const column = match.index;
+                // The same word, at the same occurrence along the generated line.
+                const occurrence = [...(original[line] ?? "").slice(0, column).matchAll(new RegExp(`\\b${word}\\b`, "g"))].length;
+                const at = [...(generated[line] ?? "").matchAll(new RegExp(`\\b${word}\\b`, "g"))][occurrence]?.index ?? -1;
+                const segment = lines[line]?.find(candidate => candidate.column === at);
+                expect([word, segment?.sourceLine, segment?.sourceColumn]).toEqual([word, line, column]);
+            }
+        }
+        // Inserted text starts no segment of its own.
+        expect(lines[0]?.some(segment => segment.column === generated[0]?.indexOf("wrap("))).toBe(false);
+    });
+});

package/src/implementation/compiler/source-map.ts

@@ -0,0 +1,134 @@
+import { locateIn, type Module } from './module-scope.js';
+
+const base64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/** One mapping: a generated column and the source line and column it came from, all counted from 0. */
+type Segment = { readonly column: number; readonly sourceLine: number; readonly sourceColumn: number };
+
+/** Decodes a source map's `mappings` into each generated line's segments that name a source position. */
+export const decodeMappings = (mappings: string): readonly (readonly Segment[])[] => {
+    const lines: Segment[][] = [];
+    let sourceLine = 0;
+    let sourceColumn = 0;
+    for (const line of mappings.split(";")) {
+        const segments: Segment[] = [];
+        let column = 0;
+        for (const text of line.split(",")) {
+            if (text === "") continue;
+            const values: number[] = [];
+            let value = 0;
+            let shift = 0;
+            for (const character of text) {
+                const digit = base64.indexOf(character);
+                value += (digit & 31) << shift;
+                if (digit & 32) shift += 5;
+                else {
+                    values.push(value & 1 ? -(value >>> 1) : value >>> 1);
+                    value = 0;
+                    shift = 0;
+                }
+            }
+            column += values[0] ?? 0;
+            if (values.length < 4) continue;
+            sourceLine += values[2] ?? 0;
+            sourceColumn += values[3] ?? 0;
+            segments.push({ column, sourceLine, sourceColumn });
+        }
+        lines.push(segments);
+    }
+    return lines;
+};
+
+/** Locates offsets in `code` at the source positions its map's `mappings` give: the nearest mapping at or before each. */
+export const locateThroughMap = (code: string, mappings: string): Module["locate"] => {
+    const generated = locateIn(code);
+    const lines = decodeMappings(mappings);
+    return offset => {
+        const { line, column } = generated(offset);
+        for (let index = line - 1; index >= 0; index--) {
+            const segments = lines[index] ?? [];
+            const found = [...segments].reverse().find(segment => index < line - 1 || segment.column <= column - 1);
+            if (found !== undefined) return { line: found.sourceLine + 1, column: found.sourceColumn + 1 + (index === line - 1 ? column - 1 - found.column : 0) };
+        }
+        return { line, column };
+    };
+};
+
+/** A source map of one source, version 3, as a bundler takes one from a transform. */
+export type SourceMap = { readonly version: 3; readonly sources: string[]; readonly sourcesContent: string[]; readonly names: string[]; readonly mappings: string };
+
+/** Text inserted before the character at offset `at`; insertions at one offset keep their order. */
+export type Insertion = { readonly at: number; readonly text: string };
+
+/** Appends `value` as a base64 VLQ, the sign in its lowest bit. */
+const encode = (value: number, into: string[]): void => {
+    let rest = value < 0 ? (-value << 1) | 1 : value << 1;
+    do {
+        let digit = rest & 31;
+        rest >>>= 5;
+        if (rest > 0) digit |= 32;
+        into.push(base64[digit] ?? "");
+    } while (rest > 0);
+};
+
+const word = /[\w$]/;
+
+/**
+ * `code` with `insertions` made, and its map back to `code` named `source`. Every character of `code` keeps its source
+ * position: a segment starts each line, each word or run of other characters, and what follows an insertion, so a
+ * position maps to its own column without interpolating. Inserted text maps to nothing of its own.
+ */
+export const insertInto = (code: string, insertions: readonly Insertion[], source: string): { readonly code: string; readonly map: SourceMap } => {
+    const ordered = insertions.map((insertion, order) => ({ insertion, order })).sort((a, b) => a.insertion.at - b.insertion.at || a.order - b.order);
+    const output: string[] = [];
+    const mappings: string[] = [];
+    let generatedColumn = 0;
+    let lineHasSegment = false;
+    let lastGeneratedColumn = 0;
+    let lastSourceLine = 0;
+    let lastSourceColumn = 0;
+    let sourceLine = 0;
+    let sourceColumn = 0;
+    let next = 0;
+    let inserted = true;
+    const newLine = (): void => {
+        mappings.push(";");
+        generatedColumn = 0;
+        lastGeneratedColumn = 0;
+        lineHasSegment = false;
+    };
+    const write = (text: string): void => {
+        output.push(text);
+        for (let k = 0; k < text.length; k++) {
+            if (text[k] === "\n") newLine();
+            else generatedColumn++;
+        }
+    };
+    for (let at = 0; at <= code.length; at++) {
+        while (next < ordered.length && ordered[next].insertion.at === at) {
+            write(ordered[next++].insertion.text);
+            inserted = true;
+        }
+        if (at === code.length) break;
+        const character = code[at] ?? "";
+        if (character !== "\n" && (inserted || sourceColumn === 0 || word.test(character) !== word.test(code[at - 1] ?? ""))) {
+            if (lineHasSegment) mappings.push(",");
+            encode(generatedColumn - lastGeneratedColumn, mappings);
+            encode(0, mappings);
+            encode(sourceLine - lastSourceLine, mappings);
+            encode(sourceColumn - lastSourceColumn, mappings);
+            lastGeneratedColumn = generatedColumn;
+            lastSourceLine = sourceLine;
+            lastSourceColumn = sourceColumn;
+            lineHasSegment = true;
+        }
+        inserted = false;
+        write(character);
+        if (character === "\n") {
+            sourceLine++;
+            sourceColumn = 0;
+        }
+        else sourceColumn++;
+    }
+    return { code: output.join(""), map: { version: 3, sources: [source], sourcesContent: [code], names: [], mappings: mappings.join("") } };
+};

package/src/implementation/compiler/spawns.ts

@@ -0,0 +1,114 @@
+import type { Expression, Node, Property, SpreadElement } from 'estree';
+import { children, declaredIn } from './estree.js';
+import { fail } from './failure.js';
+import type { ModuleScope } from './module-scope.js';
+
+type Range = { readonly start: number; readonly end: number };
+
+/**
+ * A `commands.spawn(components)({ ... })` or `commands.add(entity, components, { ... })` call with literal keys: key
+ * expressions as module-scope source, and source ranges of the entity, for an add, of the components and of the values
+ * in order.
+ */
+export type SpawnSite = Range & {
+    readonly kind: "spawn" | "add";
+    readonly entity: Range | null;
+    readonly components: Range;
+    readonly keys: readonly string[];
+    readonly values: readonly Range[];
+};
+
+/** A plain, string or number key, which is never a component's, since component keys are symbols. */
+const plainKey = (property: Property | SpreadElement): boolean =>
+    property.type === "Property" && property.kind === "init" && !property.method && (!property.computed || property.key.type === "Literal");
+
+/** A key as a module-scope expression, or null when the property isn't a module constant's computed key. */
+const keyOf = (property: Property | SpreadElement, module: ModuleScope, declared: ReadonlySet<string>): string | null => {
+    if (property.type !== "Property" || property.kind !== "init" || property.method || !property.computed) return null;
+    const { key } = property;
+    if (key.type !== "Identifier") return null;
+    return module.has(key.name) && !declared.has(key.name) ? key.name : null;
+};
+
+/** Whether an add's components are a list as written: an array literal, or a module constant of one or of `Archetype.create`. */
+const listed = (components: Expression, module: ModuleScope, declared: ReadonlySet<string>): boolean => {
+    if (components.type === "ArrayExpression") return true;
+    if (components.type !== "Identifier" || declared.has(components.name)) return false;
+    const binding = module.get(components.name);
+    if (binding?.kind !== "const") return false;
+    const { init } = binding;
+    return init.type === "ArrayExpression" || (init.type === "CallExpression" && init.callee.type === "MemberExpression" && !init.callee.computed
+        && init.callee.property.type === "Identifier" && init.callee.property.name === "create" && init.arguments[0]?.type === "ArrayExpression");
+};
+
+const plainKeyFailure = "a command's keys are its components' symbols, as [key]; a plain or string key is never a component's";
+
+/** Where a body reaches its commands: a name bound to them, or a context parameter's `commands`. */
+const commandsOf = (parameter: Node | undefined): { readonly name: string; readonly viaContext: boolean } | null => {
+    if (parameter?.type === "Identifier") return { name: parameter.name, viaContext: true };
+    if (parameter?.type !== "ObjectPattern") return null;
+    for (const property of parameter.properties) {
+        if (property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === "commands") {
+            return property.value.type === "Identifier" ? { name: property.value.name, viaContext: false } : null;
+        }
+    }
+    return null;
+};
+
+/**
+ * The spawn and add sites in a main-thread system body whose values can pass positionally: `spawn(components)(values)`
+ * and `add(entity, components, values)` on the commands of the body's own context parameter, at index `context`, with
+ * an object literal of computed keys, each a module-scope constant. A body that redeclares the context or its commands anywhere is left alone, and so is a
+ * key it shadows.
+ */
+export const spawnSites = (body: Node, module: ModuleScope, context: number): { readonly commands: string; readonly sites: readonly SpawnSite[] } | null => {
+    if (body.type !== "ArrowFunctionExpression" && body.type !== "FunctionExpression") return null;
+    const reached = commandsOf(body.params[context]);
+    if (reached === null) return null;
+    const declared = new Set<string>();
+    declaredIn(body.body, name => declared.add(name));
+    if (declared.has(reached.name)) return null;
+    const isCommands = (node: Node): boolean => reached.viaContext
+        ? node.type === "MemberExpression" && !node.computed && !node.optional && node.object.type === "Identifier" && node.object.name === reached.name
+            && node.property.type === "Identifier" && node.property.name === "commands"
+        : node.type === "Identifier" && node.name === reached.name;
+    const sites: SpawnSite[] = [];
+    /** The method a call makes on the commands, and its arguments, or null. */
+    const method = (node: Node): { readonly name: string; readonly arguments: readonly (Expression | SpreadElement)[] } | null =>
+        node.type === "CallExpression" && node.callee.type === "MemberExpression" && !node.callee.computed && !node.optional
+            && isCommands(node.callee.object) && node.callee.property.type === "Identifier"
+            ? { name: node.callee.property.name, arguments: node.arguments }
+            : null;
+    const visit = (node: Node): void => {
+        if (node.type === "CallExpression" && !node.optional) {
+            const spawned = method(node.callee);
+            const called = method(node);
+            const spawn = spawned?.name === "spawn" && spawned.arguments.length === 1 && node.arguments.length === 1 ? spawned.arguments[0] : null;
+            const add = called?.name === "add" && called.arguments.length === 3 ? called.arguments : null;
+            const components = spawn ?? add?.[1] ?? null;
+            const values = spawn !== null ? node.arguments[0] : add?.[2];
+            const entity = add?.[0] ?? null;
+            if (components !== null && components.type !== "SpreadElement" && entity?.type !== "SpreadElement" && values?.type === "ObjectExpression") {
+                // A spawn's values, or a list add's, are keyed by components; one component's object value has keys of its own.
+                const plain = values.properties.find(plainKey);
+                if (plain !== undefined && (spawn !== null || listed(components, module, declared))) return fail(plain.type === "Property" ? plain.key : plain, plainKeyFailure);
+                const keys = plain === undefined ? values.properties.map(property => keyOf(property, module, declared)) : [null];
+                if (keys.every((key): key is string => key !== null)) {
+                    sites.push({
+                        kind: spawn !== null ? "spawn" : "add",
+                        start: node.start,
+                        end: node.end,
+                        entity: entity === null ? null : { start: entity.start, end: entity.end },
+                        components: { start: components.start, end: components.end },
+                        keys,
+                        values: values.properties.flatMap(property => property.type === "Property" ? [{ start: property.value.start, end: property.value.end }] : []),
+                    });
+                    return;
+                }
+            }
+        }
+        for (const child of children(node)) visit(child);
+    };
+    visit(body.body);
+    return { commands: reached.viaContext ? `${reached.name}.commands` : reached.name, sites };
+};

package/src/implementation/compiler/stamps.ts

@@ -0,0 +1,24 @@
+import type { Statement } from './ir.js';
+import { resolve } from './out.js';
+
+const exits = (statement: Statement): boolean => {
+    switch (statement.kind) {
+        case "next": return true;
+        case "if": return resolve(statement.consequent).some(exits) || resolve(statement.alternate).some(exits);
+        case "block": case "loop": return resolve(statement.body).some(exits);
+        default: return false;
+    }
+};
+
+/**
+ * Chunk columns stamped on every row: by a top-level stamp that no earlier `next` can skip. Every row in
+ * `[start, end)` runs the body, so these chunks can be stamped once per call instead of per row.
+ */
+export const unconditionalChunks = (rows: readonly Statement[]): ReadonlySet<number> => {
+    const chunks = new Set<number>();
+    for (const statement of rows) {
+        if (exits(statement)) break;
+        if (statement.kind === "stamp") chunks.add(statement.chunks);
+    }
+    return chunks;
+};

package/src/implementation/compiler/statement.ts

@@ -0,0 +1,102 @@
+import type { DoWhileStatement, Expression, ForStatement, Node, WhileStatement } from 'estree';
+import { assign, update } from './assign.js';
+import { bind } from './bind.js';
+import { fail } from './failure.js';
+import { not } from './ir.js';
+import type { Out } from './out.js';
+import { scalar } from './scalar.js';
+import { childScope, type Scope } from './scope.js';
+import { label } from './unit.js';
+
+/** The label of the JS row loop; `next` continues it. */
+export const rowLabel = "rows";
+
+const expressionStatement = (node: Expression, scope: Scope, out: Out): void => {
+    switch (node.type) {
+        case "AssignmentExpression": return assign(node, scope, out);
+        case "UpdateExpression": return update(node, scope, out);
+        case "SequenceExpression": return node.expressions.forEach(item => expressionStatement(item, scope, out));
+        default: scope.unit.expression(node, scope, out);
+    }
+};
+
+/** Exits the loop's block when `node` is false. */
+const test = (node: Expression, exit: number, scope: Scope, out: Out): void => {
+    out.push({ kind: "branchIf", label: exit, test: not(scalar(scope.unit.expression(node, scope, out), node, scope)) });
+};
+
+/**
+ * Every loop compiles to `block exit { loop repeat { test; block next { body } update; branch repeat } }`, so a test
+ * that emits statements is re-evaluated each iteration, `break` exits `exit`, and `continue` exits `next` and still
+ * runs the update.
+ */
+const loop = (node: ForStatement | WhileStatement | DoWhileStatement, scope: Scope, out: Out): void => {
+    const outer = childScope(scope);
+    if (node.type === "ForStatement" && node.init) {
+        if (node.init.type === "VariableDeclaration") statement(node.init, outer, out);
+        else expressionStatement(node.init, outer, out);
+    }
+    const unit = scope.unit;
+    const exit = label(unit);
+    const repeat = label(unit);
+    const next = label(unit);
+    const head: Out = [];
+    const tail: Out = [];
+    if (node.type !== "DoWhileStatement" && node.test) test(node.test, exit, outer, head);
+    const body: Out = [];
+    statement(node.body, childScope(outer, { exit, next }), body);
+    if (node.type === "ForStatement" && node.update) expressionStatement(node.update, outer, tail);
+    if (node.type === "DoWhileStatement") test(node.test, exit, outer, tail);
+    out.push({
+        kind: "block", label: exit, body: [{
+            kind: "loop", label: repeat,
+            body: [...head, { kind: "block", label: next, body }, ...tail, { kind: "branch", label: repeat }],
+        }],
+    });
+};
+
+/** Compiles a statement of the kernel subset. */
+export const statement = (node: Node, scope: Scope, out: Out): void => {
+    switch (node.type) {
+        case "VariableDeclaration":
+            if (node.kind !== "const" && node.kind !== "let") return fail(node, `use const or let, not ${node.kind}`);
+            for (const declarator of node.declarations) {
+                if (!declarator.init) return fail(declarator, "locals need an initializer");
+                const value = scope.unit.expression(declarator.init, scope, out);
+                bind(declarator.id, value, node.kind, scope, out);
+            }
+            return;
+        case "ExpressionStatement":
+            return expressionStatement(node.expression, scope, out);
+        case "BlockStatement": {
+            const inner = childScope(scope);
+            for (const item of node.body) statement(item, inner, out);
+            return;
+        }
+        case "IfStatement": {
+            const condition = scalar(scope.unit.expression(node.test, scope, out), node.test, scope);
+            const consequent: Out = [];
+            const alternate: Out = [];
+            statement(node.consequent, childScope(scope), consequent);
+            if (node.alternate) statement(node.alternate, childScope(scope), alternate);
+            out.push({ kind: "if", test: condition, consequent, alternate });
+            return;
+        }
+        case "ForStatement": case "WhileStatement": case "DoWhileStatement":
+            return loop(node, scope, out);
+        case "BreakStatement": case "ContinueStatement":
+            if (node.label) return fail(node, "labels are not in the kernel subset");
+            if (scope.loop === undefined) return fail(node, `${node.type === "BreakStatement" ? "break" : "continue"} outside a loop`);
+            out.push({ kind: "branch", label: node.type === "BreakStatement" ? scope.loop.exit : scope.loop.next });
+            return;
+        case "ReturnStatement":
+            if (scope.helper) return fail(node, "a helper can only return at its end");
+            if (node.argument) return fail(node, "a kernel returns nothing; return ends the current row");
+            out.push({ kind: "next" });
+            return;
+        case "EmptyStatement":
+            return;
+        default:
+            return fail(node, `${node.type} is not in the kernel subset`);
+    }
+};

package/src/implementation/compiler/subset.md

@@ -0,0 +1,82 @@
+# Kernel subset
+
+What a kernel body (`kernel: "cpu"` or `"gpu"`) may contain. The build rejects anything else with a message at the
+offending code. It is plain TypeScript; types are stripped before compiling.
+
+```
+body        = "(" [row ["," context ["," commands]]] ")" "=>" (block | expression) | "function" "(" ... ")" block
+row         = identifier | pattern            // parameters may be destructured
+statement   = declaration | (assignment | update | call) {"," (assignment | update | call)} | if | loop | break | continue
+            | return | block | ";"
+declaration = ("const" | "let") pattern "=" expression { "," pattern "=" expression }
+pattern     = identifier | "[" pattern { "," pattern } "]" | "{" field [":" pattern] { "," ... } "}"
+assignment  = target ("=" | "+=" | "-=" | "*=" | "/=" | "%=" | "**=" | "&=" | "|=" | "^=" | "<<=" | ">>=" | ">>>=") expression
+target      = let-local | pattern of let-locals | "row[" component "]"
+update      = ("++" | "--") target | target ("++" | "--")
+if          = "if (" expression ")" statement ["else" statement]
+loop        = "for (" [declaration | assignment] ";" [expression] ";" [assignment | update] ")" statement
+            | "while (" expression ")" statement | "do" statement "while (" expression ")"
+return      = "return"                        // ends the current row
+expression  = literal | identifier | tuple | struct | unary | binary | logical | conditional | member | call
+literal     = number | boolean | "null" | "undefined" | "NaN" | "Infinity"
+tuple       = "[" expression { "," expression } "]"
+struct      = "{" name ":" expression { "," name ":" expression } "}"
+unary       = ("-" | "+" | "!" | "~") expression
+binary      = expression ("+" | "-" | "*" | "/" | "%" | "**" | "<" | ">" | "<=" | ">=" | "==" | "!=" | "===" | "!=="
+              | "&" | "|" | "^" | "<<" | ">>" | ">>>") expression
+logical     = expression ("&&" | "||" | "??") expression
+conditional = expression "?" expression ":" expression
+member      = expression "[" index "]" | expression "." name | expression "?." name
+call        = Math-function | helper | lookup | command | reducer
+```
+
+## Values
+
+- **Numbers and booleans** are scalars. **Tuples and structs** of them are values with a fixed shape: they are
+  immutable, compiled to one local per leaf, and never allocate. A `let` takes a whole new value; its elements can't be
+  assigned.
+- **The body is `(row, context)`,** and either may be destructured, as in `(row, { resources, lookup, reduce })`.
+- **`row[component]`** reads a component in `components.read` or `components.write`, and writes one in
+  `components.write`, always whole. `row.entity` is the row's entity.
+- **`context.resources[resource]`** reads a resource in `resources.read`, and `context.input` the system's input.
+  Kernels don't write resources; they reduce into them.
+- **Declarations list exactly what the body uses.** Every component in `components.read`, `components.write` and a
+  lookup's `read` must be read or written as listed, every resource in `resources.read` read, and every one in
+  `reduce` contributed to; a component only required belongs in `has`.
+- **Indexes** are literals, field names, or constants and locals whose value is a number or string literal. Tuples and
+  structs are indexed only statically; resources and the input may be indexed at runtime.
+- **Shapes are known at build time.** A local holding a component value takes its shape from the leaves the body uses
+  or assigns. A tuple or struct component value written or contributed whole with none of its leaves used, as in `row[a] = row[b]`,
+  fails at registration: destructure it or index its fields.
+
+## Calls
+
+- **`Math`:** `abs sign floor ceil round trunc min max sqrt cbrt hypot exp expm1 log log1p log2 log10 pow sin cos tan
+  asin acos atan atan2 sinh cosh tanh asinh acosh atanh fround imul clz32`, and its constants.
+- **Helpers:** functions and constants of any module the build resolves to a file, the kernel's own included, the
+  package's math types among them. Each call is inlined in its own module's scope. A helper's body is in the same
+  subset; it may `return` early inside `if`, and must end with `return <value>`. No recursion, no closures, no default
+  or rest parameters, no spread.
+- **Lookups:** `context.lookup.name(entity)` returns the other entity's values in that lookup's `read`, or `null`.
+- **Reductions:** `context.reduce[resource](value)` contributes a value to a resource in `reduce`; see `design.md`.
+- **Commands:** `context.commands.spawn(components)({ [component]: value, ... })`, `despawn(entity)`,
+  `add(entity, component, value)` or `add(entity, components, { ... })`, and `remove(entity, component)` or
+  `remove(entity, components)`, with component keys bound at module scope. A list of components is an array literal of
+  them, or a constant holding one or `Archetype.create` of one, in the kernel's module or imported, also through
+  re-exports and namespaces, its keys read in the scope of the module that declares it; a component it lists that a
+  command gives no value starts at its start. A list the build can't read, such as one computed when its module runs,
+  fails the build at the command. `add` and `remove` take a name as one key when its definition is `Symbol(...)`, as a
+  list when it's a list, and otherwise fail the build with the reason; a name from a package external to the build,
+  which the build can't read, is one key, and registration rejects a list there. The spawner is called where it's made.
+
+## GPU kernels
+
+Also no lookups, change filters, commands, reductions or loops, and only 4-byte scalar values: f32,
+i32, u32, and booleans in a `"storage"` layout. Results follow WGSL where it leaves JS results indeterminate (NaN and
+infinities).
+
+## Not in the subset
+
+`var`, classes, closures and function expressions, `this`, `new`, `delete`, `typeof`, `in`, `instanceof`, strings
+other than as keys, template literals, regular expressions, `try`, `throw`, `switch`, labels, generators, `async`,
+spread, holes, optional calls, and module state other than constants.

package/src/implementation/compiler/terminal.ts

@@ -0,0 +1,49 @@
+import type { Node, Pattern } from 'estree';
+import { children, declaredIn } from './estree.js';
+
+/** Whether `node`, a child of `parent`, names a property or label, or declares a binding, rather than referring to one. */
+const isName = (node: Node, parent: Node | undefined): boolean => {
+    switch (parent?.type) {
+        case "MemberExpression": return parent.property === node && !parent.computed;
+        case "Property": return parent.key === node && !parent.computed && !parent.shorthand;
+        case "MethodDefinition": case "PropertyDefinition": return parent.key === node && !parent.computed;
+        case "LabeledStatement": case "BreakStatement": case "ContinueStatement": return true;
+        case "VariableDeclarator": return parent.id === node;
+        default: return false;
+    }
+};
+
+/** Whether a destructuring of the context binds plain names other than `commands`, with no rest. */
+const destructuresOthers = (pattern: Pattern): boolean =>
+    pattern.type === "ObjectPattern" && pattern.properties.every(property =>
+        property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name !== "commands");
+
+/** Whether a name is used anywhere in `node` as a reference: `arguments` or `eval` could reach the context. */
+const refers = (node: Node, name: string, parent?: Node): boolean =>
+    (node.type === "Identifier" && node.name === name && !isName(node, parent)) || children(node).some(child => refers(child, name, node));
+
+/**
+ * Whether a main-thread system's body provably never reaches its context's `commands`, so the system is terminal
+ * where its declaration allows: its context, the parameter at `context`, is absent, destructured by plain names other
+ * than `commands` with no rest, or a name the body doesn't redeclare and uses only as `name.property` for other
+ * properties; and the body never refers to `arguments` or `eval`. A body it can't follow may reach them.
+ */
+export const neverReachesCommands = (body: Node, context: number): boolean => {
+    if (body.type !== "ArrowFunctionExpression" && body.type !== "FunctionExpression") return false;
+    if (refers(body.body, "eval") || (body.type === "FunctionExpression" && refers(body.body, "arguments"))) return false;
+    const parameter = body.params[context];
+    if (parameter === undefined) return body.params.every(each => each.type !== "RestElement");
+    if (parameter.type !== "Identifier") return destructuresOthers(parameter);
+    const { name } = parameter;
+    let redeclared = false;
+    declaredIn(body.body, declared => { if (declared === name) redeclared = true; });
+    if (redeclared) return false;
+    const reaches = (node: Node, parent: Node | undefined): boolean => {
+        if (node.type === "Identifier" && node.name === name && !isName(node, parent)) {
+            return !(parent?.type === "MemberExpression" && parent.object === node && !parent.computed
+                && parent.property.type === "Identifier" && parent.property.name !== "commands");
+        }
+        return children(node).some(child => reaches(child, node));
+    };
+    return !reaches(body.body, body);
+};