@adobe/ecs 0.1.0 → 0.2.1

package/src/implementation/compiler/predicates.ts

@@ -0,0 +1,250 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Expression, FunctionDeclaration, MaybeNamedFunctionDeclaration, MemberExpression, Node, ObjectExpression } from 'estree';
+import { children, declaredIn, isFunction, patternNames } from './estree.js';
+import { fail, within } from './failure.js';
+import { resolveBinding, type Link } from './link.js';
+import type { Module, ModuleBinding } from './module-scope.js';
+import { frameIn } from './module-value.js';
+
+// What a `where` predicate may read: its value, the world's resources, literals, and module-scope constants and pure
+// functions. The world runs it as written whenever a resource it reads changed, so anything else that may change, a
+// module variable, a closure over a function's state or a global, would make its cached result wrong.
+
+/** Globals a predicate may read: pure functions and constants of the language, and namespaces of them. */
+const pureGlobals: ReadonlySet<string> = new Set(["Math", "Number", "Infinity", "NaN", "undefined", "isFinite", "isNaN"]);
+
+/** By namespace global, the members a predicate may read: each pure, or a constant; `Math.random` isn't. */
+const pureMembers: ReadonlyMap<string, ReadonlySet<string>> = new Map([
+    ["Math", new Set([
+        "abs", "acos", "acosh", "asin", "asinh", "atan", "atan2", "atanh", "cbrt", "ceil", "clz32", "cos", "cosh", "exp", "expm1", "floor", "fround",
+        "hypot", "imul", "log", "log10", "log1p", "log2", "max", "min", "pow", "round", "sign", "sin", "sinh", "sqrt", "tan", "tanh", "trunc",
+        "E", "LN10", "LN2", "LOG10E", "LOG2E", "PI", "SQRT1_2", "SQRT2",
+    ])],
+    ["Number", new Set([
+        "EPSILON", "MAX_SAFE_INTEGER", "MAX_VALUE", "MIN_SAFE_INTEGER", "MIN_VALUE", "NaN", "NEGATIVE_INFINITY", "POSITIVE_INFINITY",
+        "isFinite", "isInteger", "isNaN", "isSafeInteger", "parseFloat", "parseInt",
+    ])],
+]);
+
+/** Methods that change what they're called on, of arrays, typed arrays, maps, sets and data views, which a predicate may call only on what it made. */
+const mutatingMethods: ReadonlySet<string> = new Set(["push", "pop", "shift", "unshift", "splice", "sort", "reverse", "fill", "copyWithin", "set", "add", "delete", "clear"]);
+
+/** Whether a method may change what it's called on: a known one, or a data view's setter. */
+const mutates = (name: string | null): boolean => name === null || mutatingMethods.has(name) || /^set[A-Z]/.test(name);
+
+/** A function declaration with a name, which `export default` may leave out. */
+const isNamed = (node: FunctionDeclaration | MaybeNamedFunctionDeclaration): node is FunctionDeclaration => node.id !== null;
+
+/** Whether `node`, a child of `parent`, names a property 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;
+        default: return false;
+    }
+};
+
+/** The identifiers a function refers to that it doesn't declare, each at its first reference. */
+const freeNames = (fn: Node): ReadonlyMap<string, Node> => {
+    const declared = new Set<string>();
+    declaredIn(fn, name => declared.add(name));
+    if (fn.type === "ArrowFunctionExpression" || fn.type === "FunctionExpression" || fn.type === "FunctionDeclaration") {
+        for (const parameter of fn.params) for (const name of patternNames(parameter)) declared.add(name);
+    }
+    const free = new Map<string, Node>();
+    const visit = (node: Node, parent: Node | undefined): void => {
+        if (node.type === "ThisExpression") fail(node, "a where predicate reads its value and resources, never this");
+        if (node.type === "Identifier" && !isName(node, parent) && !declared.has(node.name) && !free.has(node.name)) free.set(node.name, node);
+        for (const child of children(node)) visit(child, node);
+    };
+    visit(fn, undefined);
+    return free;
+};
+
+/** A member's name, when it's written as one or as a string literal; null for one computed otherwise. */
+const memberName = (node: MemberExpression): string | null =>
+    !node.computed && node.property.type === "Identifier" ? node.property.name
+    : node.computed && node.property.type === "Literal" && typeof node.property.value === "string" ? node.property.value
+    : null;
+
+/** An expression as the build prints it in a failure: a name and its members, or "it" for anything else. */
+const textOf = (node: Node): string => {
+    if (node.type === "Identifier") return node.name;
+    if (node.type === "MemberExpression") {
+        const name = memberName(node);
+        const object = textOf(node.object);
+        if (name !== null && !node.computed) return `${object}.${name}`;
+        return `${object}[${node.property.type === "Identifier" ? node.property.name : name === null ? "…" : JSON.stringify(name)}]`;
+    }
+    return "it";
+};
+
+/** The innermost object of a chain of members: what a write or call through it reaches. */
+const rootOf = (node: Node): Node => node.type === "MemberExpression" ? rootOf(node.object) : node;
+
+/**
+ * Fails the build where a function writes through anything but what it made of its own, calls a method that changes
+ * what it's called on, a known one or one computed by name, on anything else, reads a member of `Math` or `Number` that isn't pure, or imports a module. What it makes of its
+ * own is a local holding an object or array it wrote out, never assigned anything else; every other value, its value,
+ * resources, parameters, globals and functions among them, may be shared. `global(name)` says whether a name it doesn't
+ * declare is a global, and `imported(name)` whether it's an import, whose members the reads check holds to the
+ * package's own namespaces and functions, which are fixed.
+ */
+const checkEffects = (fn: Node, global: (name: string) => boolean, imported: (name: string) => boolean): void => {
+    const declared = new Set<string>();
+    declaredIn(fn, name => declared.add(name));
+    // Names declared with an object or array it writes out, then never assigned.
+    const own = new Set<string>();
+    const shared = new Set<string>();
+    const scan = (node: Node): void => {
+        if (node.type === "VariableDeclarator") {
+            if (node.id.type === "Identifier" && (node.init?.type === "ObjectExpression" || node.init?.type === "ArrayExpression")) own.add(node.id.name);
+            else for (const name of patternNames(node.id)) shared.add(name);
+        }
+        if (node.type === "AssignmentExpression" && node.left.type === "Identifier") shared.add(node.left.name);
+        for (const child of children(node)) scan(child);
+    };
+    scan(fn);
+    if (fn.type === "ArrowFunctionExpression" || fn.type === "FunctionExpression" || fn.type === "FunctionDeclaration") {
+        for (const parameter of fn.params) for (const name of patternNames(parameter)) shared.add(name);
+    }
+    const isOwn = (node: Node): boolean => {
+        const root = rootOf(node);
+        return root.type === "Identifier" && own.has(root.name) && !shared.has(root.name) && declared.has(root.name);
+    };
+    const written = (target: Node): void => {
+        if (target.type === "MemberExpression") {
+            if (!isOwn(target)) fail(target, `a where predicate writes through ${textOf(rootOf(target))}, which it only reads`);
+            return;
+        }
+        if (target.type === "ObjectPattern" || target.type === "ArrayPattern" || target.type === "AssignmentPattern" || target.type === "RestElement") {
+            for (const child of children(target)) written(child);
+        }
+        if (target.type === "Property") written(target.value);
+    };
+    const visit = (node: Node): void => {
+        switch (node.type) {
+            case "ImportExpression": return fail(node, "a where predicate imports a module, which may run anything");
+            case "AssignmentExpression": written(node.left); break;
+            case "UpdateExpression": written(node.argument); break;
+            case "UnaryExpression": if (node.operator === "delete") written(node.argument); break;
+            case "ForInStatement": case "ForOfStatement": if (node.left.type !== "VariableDeclaration") written(node.left); break;
+            case "MemberExpression": {
+                const { object } = node;
+                if (object.type === "Identifier" && !declared.has(object.name) && global(object.name)) {
+                    const members = pureMembers.get(object.name);
+                    const name = memberName(node);
+                    if (members !== undefined && (name === null || !members.has(name))) fail(node, `a where predicate reads ${textOf(node)}, which isn't pure`);
+                }
+                break;
+            }
+            case "CallExpression": {
+                const { callee } = node;
+                if (callee.type === "MemberExpression" && !isOwn(callee)) {
+                    const root = rootOf(callee);
+                    const name = memberName(callee);
+                    // A namespace global's members are pure where they're read, above.
+                    const free = root === callee.object && root.type === "Identifier" && !declared.has(root.name);
+                    const namespace = free && ((global(root.name) && pureMembers.has(root.name)) || imported(root.name));
+                    if (!namespace && mutates(name)) fail(callee, `a where predicate calls ${textOf(callee)}, which may change what it reads`);
+                }
+                break;
+            }
+            default: break;
+        }
+        for (const child of children(node)) visit(child);
+    };
+    visit(fn);
+};
+
+/** Whether an expression is a literal: a number, string, boolean or `null`, possibly negated, or a template without expressions. */
+const isLiteral = (node: Expression): boolean =>
+    node.type === "Literal" ? node.value === null || ["number", "string", "boolean"].includes(typeof node.value)
+    : node.type === "UnaryExpression" ? (node.operator === "-" || node.operator === "+") && isLiteral(node.argument)
+    : node.type === "TemplateLiteral" && node.expressions.length === 0;
+
+/** Whether an expression is a `Symbol(...)` call: a key, which a predicate indexes resources by. */
+const isSymbolCall = (node: Expression): boolean => node.type === "CallExpression" && node.callee.type === "Identifier" && node.callee.name === "Symbol";
+
+/**
+ * Fails the build where a predicate reads anything but its value, resources, literals, and module-scope constants and
+ * pure functions: `outer`, the names declared by functions around it, are state that may change. Functions it calls
+ * are checked the same, in their own modules, through `link`; without one, only the package's own imports are read.
+ */
+export const checkPredicate = (fn: Node, module: Module, link: Link | null, outer: ReadonlySet<string>, packageSpecifier: (specifier: string) => boolean): void => {
+    const checked = new Set<Node>();
+    const check = (node: Node, at: Module, around: ReadonlySet<string>): void => {
+        if (checked.has(node)) return;
+        checked.add(node);
+        checkEffects(node, name => !around.has(name) && at.bindings.get(name) === undefined, name => {
+            const kind = at.bindings.get(name)?.kind;
+            return kind === "import" || kind === "importNamespace";
+        });
+        for (const [name, reference] of freeNames(node)) {
+            if (around.has(name)) fail(reference, `a where predicate reads ${name}, which a function around it declares and may change; read only its value, resources and module-scope constants`);
+            const binding = at.bindings.get(name);
+            if (binding === undefined) {
+                if (pureGlobals.has(name)) continue;
+                fail(reference, `a where predicate reads the global ${name}, which may change; read only its value, resources and module-scope constants`);
+            }
+            else definition(reference, name, binding, at);
+        }
+    };
+    const definition = (reference: Node, name: string, binding: ModuleBinding, at: Module): void => {
+        switch (binding.kind) {
+            case "const": {
+                const { init } = binding;
+                if (isLiteral(init) || isSymbolCall(init)) return;
+                if (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression") {
+                    if (init.async || init.generator) fail(reference, `a where predicate calls ${name}, which isn't a plain function`);
+                    return void within(reference, frameIn(at, name), () => check(init, at, new Set()));
+                }
+                return fail(reference, `a where predicate reads ${name}, which holds values that may change; read only its value, resources and module-scope constants`);
+            }
+            case "function": {
+                const { node } = binding;
+                if (!isNamed(node)) return fail(reference, `a where predicate calls ${name}, which the build can't read`);
+                return void within(reference, frameIn(at, name), () => check(node, at, new Set()));
+            }
+            case "import": case "importNamespace": {
+                if (link === null) {
+                    if (packageSpecifier(binding.specifier)) return;
+                    return fail(reference, `a where predicate reads ${name}, imported from a module this build doesn't read`);
+                }
+                const resolved = resolveBinding(link, at, name, binding);
+                if (resolved.kind === "namespace" || (resolved.kind === "binding" && link.packages.packagePathOf(resolved.module.file)?.startsWith("interface/") === true)) {
+                    // The package's own namespaces and functions are fixed.
+                    if (resolved.kind === "namespace" ? link.packages.packagePathOf(resolved.file)?.startsWith("interface/") === true : true) return;
+                    return fail(reference, `a where predicate reads the namespace ${name}, whose members the build doesn't check`);
+                }
+                if (resolved.kind === "error") return fail(reference, `a where predicate reads ${name}, which the build can't read: ${resolved.error}`);
+                return void within(reference, frameIn(resolved.module, resolved.name), () => definition(reference, resolved.name, resolved.binding, resolved.module));
+            }
+            case "other":
+                return fail(reference, `a where predicate reads ${name}, a module variable that may change; read only its value, resources and module-scope constants`);
+        }
+    };
+    check(fn, module, outer);
+};
+
+/** The predicates of a declaration's `components.where`: each value that's a function in place or a module function by name. */
+export const predicatesOf = (declaration: ObjectExpression, module: Module): readonly Node[] => {
+    const components = declaration.properties.find(property => property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === "components");
+    if (components?.type !== "Property" || components.value.type !== "ObjectExpression") return [];
+    const where = components.value.properties.find(property => property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === "where");
+    if (where?.type !== "Property" || where.value.type !== "ObjectExpression") return [];
+    const predicates: Node[] = [];
+    for (const property of where.value.properties) {
+        if (property.type !== "Property") continue;
+        const { value } = property;
+        if (isFunction(value)) predicates.push(value);
+        else if (value.type === "Identifier") {
+            const binding = module.bindings.get(value.name);
+            if (binding?.kind === "function" && isNamed(binding.node)) predicates.push(binding.node);
+            else if (binding?.kind === "const" && isFunction(binding.init)) predicates.push(binding.init);
+        }
+    }
+    return predicates;
+};

package/src/implementation/compiler/print.ts

@@ -1,8 +1,10 @@
-import { chunkShift, type Path } from '../world/kernel.js';
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { blockShift, 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';
+import { presence } from './columns.js';
 
 /** A number as JS source that reads back as the same f64. */
 export const printNumber = (value: number): string =>
@@ -10,6 +12,9 @@ export const printNumber = (value: number): string =>
 
 const printPath = (path: Path): string => path.map(item => `[${JSON.stringify(item)}]`).join("");
 
+/** The presence of the optional component the key at `key` names. */
+const presenceOf = (unit: Unit, key: number): Expression => presence(unit, unit.keys[key] ?? "");
+
 export const localName = (unit: Unit, local: number): string => `${unit.names.get(local) ?? "t"}_${local}`;
 
 /** Prints an expression. `observed` converts boolean column reads. */
@@ -20,10 +25,16 @@ export const printExpression = (unit: Unit, expression: Expression, observed: bo
         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}])`;
+            // In the loop for archetypes without every optional component, theirs read undefined without a load.
+            if (unit.presentAs === false && unit.optionalColumns.has(column)) return "undefined";
+            // An optional component's column is empty in an archetype without it, where it reads undefined.
+            const read = observed
+                ? (unit.booleans.add(column), `(b${column} ? c${column}[x${column}] !== 0 : c${column}[x${column}])`)
+                : `c${column}[x${column}]`;
+            const key = unit.optionalColumns.get(column);
+            return key !== undefined && observed ? `(${print(presenceOf(unit, key))} ? ${read} : undefined)` : read;
         }
+        case "present": return unit.presentAs === null ? `q${expression.column}` : String(unit.presentAs);
         case "upColumn": {
             const column = expression.column;
             const read = `u${column}[p * us${column} + uo${column}]`;
@@ -33,6 +44,7 @@ export const printExpression = (unit: Unit, expression: Expression, observed: bo
         }
         case "resource": return `r${expression.index}${printPath(expression.path)}`;
         case "args": return `args${printPath(expression.path)}`;
+        case "shared": return `h${expression.index}${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)})`;
@@ -65,10 +77,18 @@ const printStatement = (unit: Unit, statement: Statement, labels: Labels): strin
             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 "store": {
+            const { column } = statement;
+            const store = `c${column}[x${column}] = ${value(statement.value)};`;
+            // Assigning an optional component an entity lacks fails its system, as a body run as written does.
+            const key = unit.optionalColumns.get(column);
+            if (key === undefined) return store;
+            const present = printExpression(unit, presenceOf(unit, key), false);
+            return present === "true" ? store : present === "false" ? `absent(${key});` : `if (${present}) ${store} else absent(${key});`;
+        }
         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;`;
+            return unit.stampedPerCall.has(statement.chunks) ? row : `${row}\nc${statement.blocks}[i >> ${blockShift}] = tick;\nc${statement.chunks}[i >> ${chunkShift}] = tick;`;
         }
         case "if": {
             const alternate = printStatements(unit, statement.alternate, labels);

package/src/implementation/compiler/program.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Path, Program } from '../world/kernel.js';
 import type { Expression, Statement } from './ir.js';
 import { resolve } from './out.js';
@@ -106,8 +107,10 @@ export const toProgram = (statements: readonly Statement[], nameOf?: (local: num
             return check.found ? tested : { kind: "unary", operator: "!", operand: tested };
         }
         switch (node.kind) {
-            case "number": case "boolean": case "column": case "resource": case "args":
+            case "number": case "boolean": case "column": case "resource": case "args": case "shared":
                 return node;
+            // WASM runs only archetypes with every optional component; the others run the JS kernel.
+            case "present": return { kind: "boolean", value: true };
             // 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) };

package/src/implementation/compiler/public.ts

@@ -0,0 +1,2 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export { plugin } from './plugin.js';

package/src/implementation/compiler/scalar.ts

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

package/src/implementation/compiler/scope.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Module } from './module-scope.js';
 import type { Unit } from './unit.js';
 import type { Value } from './value.js';

package/src/implementation/compiler/serialize.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { printNumber } from './print.js';
 
 /** Data as a JS literal; unlike JSON, it keeps NaN, infinities and -0. */

package/src/implementation/compiler/shared-kernels.test.ts

@@ -0,0 +1,57 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, test } from 'vitest';
+import { parseAst } from 'vite';
+import { transformKernels } from './transform.js';
+import { createLinker } from './link.js';
+import { nodeCopies, ownCopy } from './paths.js';
+import { estreeOf } from './estree.js';
+
+const parse = (code: string) => estreeOf(parseAst(code));
+
+const header = `import { System } from "ecs";
+const team = "team";
+const cell = "cell";
+const value = "value";
+const other = "other";
+`;
+
+/** Transforms `source` as the module "/test.js", whose `team` and `cell` are declared shared. */
+const transform = (source: string) => transformKernels(`${header}${source}`, "/test.js", parse, async specifier => specifier === "ecs" ? ownCopy : null, index => JSON.stringify(`kernel:${index}`), createLinker({
+    packages: nodeCopies,
+    shared: file => new Set(file === "/test.js" ? ["team", "cell"] : []),
+    resolve: async specifier => specifier === "ecs" ? ownCopy.index : { error: `${specifier} can't be resolved` },
+    load: async () => ({ error: "no files" }),
+}, parse));
+
+const failure = async (source: string): Promise<string> => {
+    const result = await transform(source);
+    return result !== null && "failure" in result ? result.failure.message : "compiled";
+};
+
+describe("kernels reading shared components", () => {
+    test("read each call's archetype's value as a parameter", async () => {
+        const result = await transform(`export const kernel = System.create({ kernel: true, components: { with: [cell, value] } }, row => { row[value] = row[cell][0] * 2 + row[cell][1]; });`);
+        if (result === null || "failure" in result) throw new Error(result === null ? "no kernel" : result.failure.message);
+        expect(result.code).toContain("shared: [cell],");
+        const [kernel = ""] = result.kernels;
+        expect(kernel).toContain("const h0 = shared[0];");
+        expect(kernel).toContain("h0[0]");
+        expect(kernel).toMatch(/\(columns, start, end, resources, lookups, keys, args, commands, tick, partials, partial, rows, parents, upColumns, found, shared\) =>/);
+        // WASM and WGSL take it as a scalar parameter per call.
+        expect(result.code).toContain(`{ "kind": "shared", "index": 0, "path": [0] }`);
+    });
+    test("never write one, read one optional, or read one through a lookup or up", async () => {
+        expect(await failure(`export const kernel = System.create({ kernel: true, components: { with: [team, value] } }, row => { row[team] = 1; });`))
+            .toContain("team is shared: its value is its archetype's, so a kernel reads it and never writes it");
+        expect(await failure(`export const kernel = System.create({ kernel: true, components: { with: [value], optional: [cell] } }, row => { row[value] = row[cell]?.[0] ?? 0; });`))
+            .toContain("cell is shared and optional, which kernels don't read yet");
+        expect(await failure(`export const kernel = System.create({ kernel: true, components: { with: [other, value] }, lookup: { at: { with: [team] } } }, (row, { lookup }) => { row[value] = lookup.at(row[other])?.[team] ?? 0; });`))
+            .toContain("team is shared, which a kernel reads only of its own rows");
+        expect(await failure(`export const kernel = System.create({ kernel: true, components: { with: [value] } }, (row, { commands }) => { commands.add(row.entity, team, 1); });`))
+            .toContain("team is shared: its value chooses an archetype, so only a system run as written on the world's thread spawns, adds or removes it");
+    });
+    test("tried, a body leaving the subset for one runs as written", async () => {
+        const result = await transform(`export const tried = System.create({ components: { with: [team, value] } }, row => { row[team] = 1; });\nexport const moving = System.create({ components: { with: [value] } }, (row, { commands }) => { commands.add(row.entity, team, 1); });`);
+        expect(result !== null && "failure" in result ? result.failure.message : result?.kernels ?? []).toEqual([]);
+    });
+});

package/src/implementation/compiler/signature.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 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';
@@ -9,7 +10,7 @@ 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 };
+export type Lookup = { readonly name: string; readonly read: readonly string[]; readonly index: boolean; readonly watches: boolean; readonly optional: 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[] };
@@ -24,13 +25,18 @@ export type Reduced = { readonly resource: string; readonly operator: Reduction
 export type Signature = {
     readonly read: ReadonlySet<string>;
     readonly write: ReadonlySet<string>;
+    /** What it requires of its rows, its `with`. */
+    readonly has: ReadonlySet<string>;
+    /** Components its rows may lack, its `optional`: an archetype without one gives the kernel an empty column. */
+    readonly optional: ReadonlySet<string>;
+    /** Components it reads that are shared, in the order it lists them: each call takes its archetype's values of them as parameters. */
+    readonly shared: readonly 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;
 };
@@ -61,30 +67,61 @@ const keyLists = (node: Expression | Pattern, what: string, allowed: readonly st
         ? 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]: \"+\" }");
+/** `resources: { reduce: [resource, ...] }`, each folded with its declaration's `reduce` trait. */
+const reductions = (node: Expression | Pattern, lists: Lists): readonly Reduced[] => {
+    const names = identifiers(node, "resources.reduce", lists);
+    return names.map((resource): Reduced => {
+        const found = lists.reduction(resource);
+        const operator = found?.operator;
+        if (!isReduction(operator)) {
+            const missing = found !== null && /\.m?js$/.test(found.file)
+                ? `which its module's JavaScript doesn't register: declare it in TypeScript, and build a library declaring it with Compiler.plugin({ library: true })`
+                : "which it can't find: declare the resource with reduce in the module that makes its key";
+            return fail(node, `${resource} is reduced, so the build reads its operator from its declaration's reduce trait, ${operator === undefined ? missing : `"${operator}", which isn't one of ${reductionOperators.map(item => JSON.stringify(item)).join(", ")}`}`);
         }
-        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 };
+        return { resource, 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 => {
+/** How a `System.create` declaration's body compiles: to `target`, and whether its `kernel` requires it or it's tried. */
+export type KernelRequest = { readonly target: "cpu" | "gpu"; readonly required: boolean };
+
+/** Whether a declaration has property `name`, written out. */
+const declares = (declaration: ObjectExpression, name: string): boolean => declaration.properties.some(property =>
+    property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === name);
+
+/** A declaration's `components.optional` property, or null without one. */
+const hasOptional = (declaration: ObjectExpression): Property | null => {
+    for (const property of declaration.properties) {
+        if (property.type !== "Property" || property.computed || property.key.type !== "Identifier" || property.key.name !== "components") continue;
+        if (property.value.type !== "ObjectExpression") return null;
+        for (const field of property.value.properties) {
+            if (field.type === "Property" && !field.computed && field.key.type === "Identifier" && field.key.name === "optional") return field;
+        }
+    }
+    return null;
+};
+
+/**
+ * How a `System.create` declaration compiles to a kernel, or null when it doesn't: `kernel: true` or `"gpu"` requires
+ * it, `false` rules it out, and without it a system with components is tried, unless it observes, runs on one entity
+ * or spreads what the build can't read.
+ */
+export const kernelOf = (declaration: ObjectExpression): KernelRequest | null => {
+    const optional = hasOptional(declaration);
     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"`);
+            if (value.type === "Literal" && value.value === "gpu" && optional !== null) return fail(optional, "a GPU kernel can't have optional components: WGSL has no undefined to read where an archetype lacks one, and a GPU kernel can't fail its system for one row; list them in with, or use kernel: true to run it on the CPU");
+            if (value.type === "Literal" && value.value === true) return { target: "cpu", required: true };
+            if (value.type === "Literal" && value.value === "gpu") return { target: "gpu", required: true };
+            if (value.type === "Literal" && value.value === false) return null;
+            return fail(value, `kernel must be the literal true, false or "gpu"`);
         }
     }
-    return null;
+    if (declaration.properties.some(property => property.type === "SpreadElement")) return null;
+    if (!declares(declaration, "components") || declares(declaration, "observer") || declares(declaration, "target")) return null;
+    return { target: "cpu", required: false };
 };
 
 /** Reads and validates a kernel declaration; `lists` reads its lists of keys. */
@@ -93,27 +130,25 @@ export const signature = (declaration: ObjectExpression, module: ModuleScope, li
     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);
+                components = keyLists(property.value, "components", ["read", "write", "with", "optional", "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 === "reduce") reduced = reductions(value.value, lists);
                     else if (list === "not") continue;
+                    else if (list === "write") fail(value, "a kernel can't write resources: write them from a system that runs as written, or reduce into them");
                     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.
@@ -121,13 +156,13 @@ export const signature = (declaration: ObjectExpression, module: ModuleScope, li
                     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`);
+                        if (index ? field !== "read" && field !== "changed" : field !== "read" && field !== "with" && field !== "optional" && 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") });
+                    lookups.push({ name: lookup, read, index, watches: !index && listed.some(([field]) => field === "changed"), optional: listed.some(([field]) => field === "optional") });
                 }
                 break;
             case "up": {
@@ -144,20 +179,17 @@ export const signature = (declaration: ObjectExpression, module: ModuleScope, li
                 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":
+            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");
+    if (components === undefined) return fail(declaration, "a system without components runs once, so there's nothing to compile");
     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`);
     }
@@ -165,6 +197,14 @@ export const signature = (declaration: ObjectExpression, module: ModuleScope, li
     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;
+    // A shared component's value is its archetype's: a call reads it once, as a parameter, and never writes it.
+    const writtenShared = write.find(lists.shared);
+    if (writtenShared !== undefined) fail(declaration, `${writtenShared} is shared: its value is its archetype's, so a kernel reads it and never writes it; give it another with commands.add`);
+    const shared = (components.get("read") ?? []).filter(lists.shared);
+    const optionalShared = shared.find(key => components?.get("optional")?.includes(key) === true);
+    if (optionalShared !== undefined) fail(declaration, `${optionalShared} is shared and optional, which kernels don't read yet; list it in with, or run the system as written`);
+    const looked = [...lookups.flatMap(lookup => lookup.read), ...up?.read ?? []].find(lists.shared);
+    if (looked !== undefined) fail(declaration, `${looked} is shared, which a kernel reads only of its own rows, not through a lookup or up; run the system as written`);
     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 };
+    return { read: new Set(components.get("read")), write: new Set(write), has: new Set(components.get("with")), optional: new Set(components.get("optional")), shared, resources, reduced, lookups, up, ordered, filtered: changedResources.length > 0 || rowFiltered };
 };