@adobe/ecs 0.0.0-stage → 0.2.0

package/src/implementation/compiler/input-schemas.test.ts

@@ -0,0 +1,182 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, test } from 'vitest';
+import { inputInsertions, type InputHost } from './input-schemas.js';
+import { insertInto } from './source-map.js';
+import { hostOf } from './type-host.test-helper.js';
+import { moduleOf } from './type-schemas.js';
+
+/** The module as the pass leaves it, with the files whose types it read, or its failure; null when it inserts nothing. */
+const passInputSchemas = async (code: string, file: string, host: InputHost) => {
+    const result = await inputInsertions(moduleOf(file, code, host.parse(code, file)), host);
+    if (result === null || "failure" in result) return result;
+    return { ...insertInto(code, result.insertions, file), dependencies: result.dependencies };
+};
+
+const header = `import { System, type Entity, type Vec2, type F32, type I32 } from "@adobe/ecs";\n`;
+
+/** The schemas the pass gives each system of `body`, in order. */
+const schemasOf = async (body: string, files: { readonly [path: string]: string } = {}): Promise<unknown> => {
+    const code = header + body;
+    const result = await passInputSchemas(code, "/src/main.ts", hostOf(files));
+    if (result === null) return null;
+    if ("failure" in result) return { failure: result.failure.message };
+    return [...result.code.matchAll(/, (\{.*\})\);?$/gm)].map(match => JSON.parse(match[1] ?? "null"));
+};
+
+describe("passInputSchemas", () => {
+    test("gives a system the schema of its body's parameter after its context", async () => {
+        expect(await schemasOf(`System.create({}, (_context, input: { readonly count: number; label: string; on: boolean; none: null }) => {});`)).toEqual([
+            { type: "object", properties: { count: { type: "number" }, label: { type: "string" }, on: { type: "boolean" }, none: { type: "null" } } },
+        ]);
+    });
+    test("finds the input after the row when the declaration has components", async () => {
+        expect(await schemasOf(`System.create({ components: { with: [a] } }, (row, context, input: { dx: number }) => {});`)).toEqual([
+            { type: "object", properties: { dx: { type: "number" } } },
+        ]);
+        expect(await schemasOf(`System.create({ components: { with: [a] } }, (row, context) => {});`)).toBe(null);
+    });
+    test("takes a declaration not written in place's input from a third parameter, or a second with a type", async () => {
+        expect(await schemasOf([
+            `System.create(declaration, (row, context, input: { a: number }) => {});`,
+            `System.create(declaration, (context, input: { b: number }) => {});`,
+            `System.create(declaration, (row, context) => {});`,
+        ].join("\n"))).toEqual([{ type: "object", properties: { a: { type: "number" } } }, { type: "object", properties: { b: { type: "number" } } }]);
+    });
+    test("passes nothing for a body without input", async () => {
+        expect(await schemasOf(`System.create({ resources: {} }, ({ resources }) => {});\nSystem.create(context => {});`)).toBe(null);
+    });
+    test("reads optional fields, literals, unions, arrays, tuples, sets and maps", async () => {
+        expect(await schemasOf(`System.create({}, (_c, input: {
+            mode?: "add" | "remove";
+            level: 1 | -1;
+            tags: readonly string[];
+            ids: ReadonlyArray<Entity>;
+            pair: [number, number];
+            seen: ReadonlySet<string>;
+            names: ReadonlyMap<Entity, string>;
+            maybe: string | null;
+        }) => {});`)).toEqual([{
+            type: "object",
+            properties: {
+                mode: { anyOf: [{ const: "add" }, { const: "remove" }] },
+                level: { anyOf: [{ const: 1 }, { const: -1 }] },
+                tags: { type: "array", items: { type: "string" } },
+                ids: { type: "array", items: { type: "integer", format: "entity" } },
+                pair: { type: "array", items: { type: "number" }, minItems: 2, maxItems: 2 },
+                seen: { type: "set", items: { type: "string" } },
+                names: { type: "map", keys: { type: "integer", format: "entity" }, values: { type: "string" } },
+                maybe: { anyOf: [{ type: "string" }, { type: "null" }] },
+            },
+            required: ["level", "tags", "ids", "pair", "seen", "names", "maybe"],
+        }]);
+    });
+    test("gives the package's types their schemas", async () => {
+        expect(await schemasOf(`System.create({}, (_c, input: { entity: Entity; at: Vec2; cell: Vec2.I32; dt: F32; steps: I32 }) => {});`)).toEqual([{
+            type: "object",
+            properties: {
+                entity: { type: "integer", format: "entity" },
+                at: { type: "array", items: { type: "number", precision: 1 }, minItems: 2, maxItems: 2 },
+                cell: { type: "array", items: { type: "integer", minimum: -2147483648, maximum: 2147483647 }, minItems: 2, maxItems: 2 },
+                dt: { type: "number", precision: 1 },
+                steps: { type: "integer", minimum: -2147483648, maximum: 2147483647 },
+            },
+        }]);
+    });
+    test("follows a type named by Schema.Type to its schema, written as a literal type or `typeof` a constant", async () => {
+        const files = { "/src/units.ts": `import type { Schema } from "@adobe/ecs";\nexport type Level = Schema.Type<{ type: "integer"; minimum: 0; maximum: 9 }>;\nconst title = { type: "string", maxLength: 64 } as const;\nexport type Title = Schema.Type<typeof title>;` };
+        expect(await schemasOf([
+            `import type { Level, Title } from "./units.js";`,
+            `type Cell = readonly [Level, Level];`,
+            `System.create({}, (_c, input: { level: Level; title: Title; cell: Cell }) => {});`,
+        ].join("\n"), files)).toEqual([{
+            type: "object",
+            properties: {
+                level: { type: "integer", minimum: 0, maximum: 9 },
+                title: { type: "string", maxLength: 64 },
+                cell: { type: "array", items: { type: "integer", minimum: 0, maximum: 9 }, minItems: 2, maxItems: 2 },
+            },
+        }]);
+    });
+    test("reads the package's types through any namespace", async () => {
+        expect(await schemasOf(`import * as ecs from "@adobe/ecs";\nSystem.create({}, (_c, input: { at: ecs.Vec3; cell: ecs.Vec2.U32 }) => {});`)).toEqual([{
+            type: "object",
+            properties: {
+                at: { type: "array", items: { type: "number", precision: 1 }, minItems: 3, maxItems: 3 },
+                cell: { type: "array", items: { type: "integer", minimum: 0, maximum: 0xFFFFFFFF }, minItems: 2, maxItems: 2 },
+            },
+        }]);
+    });
+    test("takes any value for a class a module exports", async () => {
+        const files = { "/src/row.ts": `export class Row extends HTMLElement {}` };
+        expect(await schemasOf(`import { Row } from "./row.js";\nSystem.create({}, (_c, input: { row: Row }) => {});`, files)).toEqual([{ type: "object", properties: { row: { allOf: [] } } }]);
+    });
+    test("takes any value for a global class or unknown", async () => {
+        expect(await schemasOf(`System.create({}, (_c, input: { canvas: OffscreenCanvas; bitmap: ImageBitmap; element: HTMLCanvasElement; anything: unknown }) => {});`)).toEqual([
+            { type: "object", properties: { canvas: { allOf: [] }, bitmap: { allOf: [] }, element: { allOf: [] }, anything: { allOf: [] } } },
+        ]);
+    });
+    test("reads the values of an `as const` object, here or imported, as a union of their literals", async () => {
+        const files = { "/src/align.ts": `export const Align = { start: "start", end: "end", again: "start" } as const;\nexport type Align = (typeof Align)[keyof typeof Align];` };
+        expect(await schemasOf([
+            `import { Align } from "./align.js";`,
+            `const Level = { low: 1, high: -1, on: true } as const satisfies Record<string, number | boolean>;`,
+            `type Level = (typeof Level)[keyof typeof Level];`,
+            `System.create({}, (_c, input: { align: Align; level: Level; inline: (typeof Level)[keyof typeof Level] }) => {});`,
+        ].join("\n"), files)).toEqual([{
+            type: "object",
+            properties: {
+                align: { anyOf: [{ const: "start" }, { const: "end" }] },
+                level: { anyOf: [{ const: 1 }, { const: -1 }, { const: true }] },
+                inline: { anyOf: [{ const: 1 }, { const: -1 }, { const: true }] },
+            },
+        }]);
+    });
+    test("follows aliases and interfaces, here and in modules imported", async () => {
+        const files = {
+            "/src/types.ts": `export type Move = { readonly by: number };\nexport interface Named { readonly name: string }\nexport { type Tagged } from "./more.js";\nexport * from "./all.js";`,
+            "/src/more.ts": `export interface Tagged extends Base { readonly tag: string }\ninterface Base { readonly base: boolean }`,
+            "/src/all.ts": `export type Spread = { readonly spread: number };`,
+        };
+        expect(await schemasOf([
+            `import type { Move, Named, Tagged, Spread } from "./types.js";`,
+            `type Local = Move & Named;`,
+            `System.create({}, (_c, input: Local) => {});`,
+            `System.create({}, (_c, input: Tagged) => {});`,
+            `System.create({}, (_c, input: Spread) => {});`,
+        ].join("\n"), files)).toEqual([
+            { type: "object", properties: { by: { type: "number" }, name: { type: "string" } } },
+            { type: "object", properties: { base: { type: "boolean" }, tag: { type: "string" } } },
+            { type: "object", properties: { spread: { type: "number" } } },
+        ]);
+    });
+    test("names the module of a type it can't read", async () => {
+        const failed = await passInputSchemas(`${header}import type { Bad } from "./bad.js";\nSystem.create({}, (_c, input: Bad) => {});`, "/src/main.ts", hostOf({ "/src/bad.ts": `export type Bad = Pick<Big, "x">;` }));
+        expect(failed !== null && "failure" in failed ? failed.failure.frames.map(frame => [frame.file, frame.line]) : failed).toEqual([["/src/bad.ts", 1]]);
+        expect(failed !== null && "failure" in failed ? failed.dependencies : failed).toEqual(["/src/bad.ts"]);
+    });
+    test("fails, saying why, for what an input type can't be", async () => {
+        const failure = async (body: string) => {
+            const schemas = await schemasOf(body);
+            return typeof schemas === "object" && schemas !== null && "failure" in schemas ? schemas.failure : schemas;
+        };
+        expect(await failure(`System.create({}, (_c, input) => {});`)).toContain("has a type");
+        expect(await failure(`System.create({}, (_c, input: { a?: number | undefined }) => {});`)).toContain("optional");
+        expect(await failure(`System.create({}, (_c, input: Pick<Big, "x">) => {});`)).toContain("type arguments");
+        expect(await failure(`type Tree = { readonly child: Tree };\nSystem.create({}, (_c, input: Tree) => {});`)).toContain("refers to itself");
+        expect(await failure(`type Box<T> = { readonly value: T };\nSystem.create({}, (_c, input: Box) => {});`)).toContain("generic");
+        expect(await failure(`System.create({}, (_c, input: [number, string]) => {});`)).toContain("one type");
+        expect(await failure(`System.create({}, (_c, input: number) => {});`)).toContain("object of named fields");
+        expect(await failure(`const Loose = { a: "a" };\nSystem.create({}, (_c, input: { a: (typeof Loose)[keyof typeof Loose] }) => {});`)).toContain("as const");
+        expect(await failure(`const Nested = { a: { b: 1 } } as const;\nSystem.create({}, (_c, input: { a: (typeof Nested)[keyof typeof Nested] }) => {});`)).toContain("literals");
+        expect(await failure(`System.create({}, (_c, input: { a: Big["x"] }) => {});`)).toContain("keyof typeof");
+        expect(await failure(`System.create({}, (_c, ...rest: [{ a: number }]) => {});`)).toContain("rest parameter");
+    });
+    test("inserts each schema after the body, mapping the rest of the line back", async () => {
+        const result = await passInputSchemas(`${header}System.create({}, (_c, input: { a: number }) => {}); const after = 1;`, "/src/main.ts", hostOf({}));
+        expect(result !== null && "code" in result ? result.code.split("\n")[1] : result).toBe(`System.create({}, (_c, input: { a: number }) => {}, {"type":"object","properties":{"a":{"type":"number"}}}); const after = 1;`);
+        expect(result !== null && "map" in result ? result.map.mappings.length > 0 : result).toBe(true);
+    });
+    test("leaves calls of another System", async () => {
+        expect(await passInputSchemas(`import { System } from "elsewhere";\nSystem.create({}, (_c, input: { a: number }) => {});`, "/src/main.ts", hostOf({}))).toBe(null);
+    });
+});

package/src/implementation/compiler/input-schemas.ts

@@ -0,0 +1,107 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Failure } from './failure.js';
+import type { Insertion } from './source-map.js';
+import { createConverter, isThrown, type Module, type Node, type Statement, type TypeHost, type TypeNode } from './type-schemas.js';
+
+/** Whether an import specifier, resolved from `importer`, is a module of the package exporting `System`. */
+export type IsSystem = (specifier: string, importer: string) => Promise<boolean>;
+
+export type InputHost = TypeHost & { readonly isSystem: IsSystem };
+
+/** What a pass inserts into a module, and the files whose types it read; or why it failed. */
+export type PassResult =
+    | { readonly insertions: readonly Insertion[]; readonly dependencies: readonly string[] }
+    | { readonly failure: Failure; readonly dependencies: readonly string[] };
+
+type Expression = Extract<Statement, { readonly type: "ExpressionStatement" }>["expression"];
+type Call = Extract<Expression, { readonly type: "CallExpression" }>;
+type FunctionNode = Extract<Expression, { readonly type: "ArrowFunctionExpression" | "FunctionExpression" }>;
+
+/** Every node under `node`, in source order. */
+const each = (node: unknown, visit: (node: Node) => void): void => {
+    if (Array.isArray(node)) {
+        for (const item of node) each(item, visit);
+        return;
+    }
+    if (typeof node !== "object" || node === null || typeof Reflect.get(node, "type") !== "string") return;
+    if (isNode(node)) visit(node);
+    for (const key of Object.keys(node)) if (key !== "parent") each(Reflect.get(node, key), visit);
+};
+
+const isNode = (value: object): value is Node => typeof Reflect.get(value, "start") === "number" && typeof Reflect.get(value, "end") === "number";
+
+// Each call's arguments are its own expressions.
+const isCall = (node: Node): node is Call => node.type === "CallExpression";
+
+const unwrapped = (node: Call["arguments"][number]): Call["arguments"][number] =>
+    node.type === "ParenthesizedExpression" ? unwrapped(node.expression) : node;
+
+const isFunction = (node: Call["arguments"][number]): node is FunctionNode => node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression";
+
+/** Whether a declaration written in place declares `components`; null when it isn't written in place. */
+const declaresComponents = (declaration: Call["arguments"][number]): boolean | null => {
+    if (declaration.type !== "ObjectExpression") return null;
+    return declaration.properties.some(property => property.type === "Property" && !property.computed
+        && ((property.key.type === "Identifier" && property.key.name === "components") || (property.key.type === "Literal" && property.key.value === "components")));
+};
+
+/**
+ * Passes each `System.create(declaration, body)` the schema of its body's input, the type of its parameter after its
+ * context, as a third argument: `create` takes the schema from there. The type is read from its syntax, through aliases
+ * and interfaces of the module and those it imports, so it needs no type checker. Returns null when no system here
+ * takes input.
+ */
+export const inputInsertions = async (module: Module, host: InputHost): Promise<PassResult | null> => {
+    const { code, file, program } = module;
+    if (!code.includes("System") || !code.includes(".create(")) return null;
+    const converter = createConverter(host, file);
+    const { fail } = converter;
+    const systems = new Set<string>();
+    for (const [local, entry] of module.imports) {
+        if (entry.imported === "System" && await host.isSystem(entry.source, file)) systems.add(local);
+    }
+    if (systems.size === 0) return null;
+    const calls: Call[] = [];
+    each(program.body, node => {
+        if (!isCall(node)) return;
+        const { callee } = node;
+        if (callee.type === "MemberExpression" && !callee.computed && callee.object.type === "Identifier" && systems.has(callee.object.name)
+            && callee.property.type === "Identifier" && callee.property.name === "create" && node.arguments.length === 2) calls.push(node);
+    });
+    const insertions: Insertion[] = [];
+    try {
+        for (const call of calls) {
+            const [declaration, second] = call.arguments;
+            if (declaration === undefined || second === undefined) continue;
+            const body = unwrapped(second);
+            if (!isFunction(body)) continue;
+            const components = declaresComponents(declaration);
+            // For a declaration not written in place, a third parameter is the input, as is a second one with a type: a
+            // context is rarely given one.
+            const before = components === null ? (body.params.length > 2 || annotationOf(body.params[1]) === null ? 2 : 1) : components ? 2 : 1;
+            const parameter = body.params[before];
+            if (parameter === undefined) continue;
+            if (parameter.type === "RestElement") fail(module, parameter, "a body's input is one parameter, not a rest parameter");
+            if (parameter.type === "AssignmentPattern") fail(module, parameter, "a body's input has no default");
+            const annotation = annotationOf(parameter);
+            if (annotation === null) return fail(module, parameter, "a body's input parameter has a type, which its schema is made from");
+            converter.site.at = parameter.start;
+            const schema = await converter.convert(annotation, module, new Set(), "input");
+            if (!("type" in schema) || schema.type !== "object") fail(module, parameter, "a body's input is an object of named fields");
+            insertions.push({ at: second.end, text: `, ${JSON.stringify(schema)}` });
+        }
+    } catch (error) {
+        if (isThrown(error)) return { failure: error.typeFailure, dependencies: [...converter.read] };
+        throw error;
+    }
+    if (insertions.length === 0) return null;
+    return { insertions, dependencies: [...converter.read] };
+};
+
+type Parameter = FunctionNode["params"][number];
+
+const annotationOf = (parameter: Parameter | undefined): TypeNode | null => {
+    if (parameter === undefined || parameter.type === "TSParameterProperty") return null;
+    const annotation = parameter.type === "RestElement" ? parameter.typeAnnotation : parameter.typeAnnotation;
+    return annotation === null || annotation === undefined ? null : annotation.typeAnnotation;
+};

package/src/implementation/compiler/ir.ts

@@ -0,0 +1,106 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { BinaryOperator } from 'estree';
+import type { Path, Program } from '../world/kernel.js';
+import type { Out } from './out.js';
+
+export type Binary = Exclude<BinaryOperator, "in" | "instanceof">;
+export type Unary = "-" | "+" | "!" | "~";
+
+const unaryOperators: ReadonlySet<string> = new Set(["-", "+", "!", "~"]);
+const binaryOperators: ReadonlySet<string> = new Set([
+    "+", "-", "*", "/", "%", "**", "<", ">", "<=", ">=", "==", "!=", "===", "!==", "&", "|", "^", "<<", ">>", ">>>",
+]);
+
+export const isUnary = (operator: string): operator is Unary => unaryOperators.has(operator);
+export const isBinary = (operator: string): operator is Binary => binaryOperators.has(operator);
+
+/**
+ * The lowered kernel body: the `Program` subset plus JS-only nodes (lookups, commands, nullish values, runtime
+ * indexing, JS values). JS is printed from it; a `Program` is derived from it when it has no JS-only nodes.
+ * Locals and labels are unit-unique numbers.
+ */
+export type Expression =
+    | { readonly kind: "number"; readonly value: number }
+    | { readonly kind: "boolean"; readonly value: boolean }
+    | { readonly kind: "column"; readonly column: number }
+    /** Whether this call's archetype has an optional component, by its presence column: the same for every row. */
+    | { readonly kind: "present"; readonly column: number }
+    /** A column of the row's parent, at the parent's row: `Unit.upColumns`. */
+    | { readonly kind: "upColumn"; readonly column: number }
+    | { readonly kind: "resource"; readonly index: number; readonly path: Path }
+    | { readonly kind: "args"; readonly path: Path }
+    /** A leaf of the call's archetype's value of shared component `index`, in `Signature.shared` order: a parameter of the call. */
+    | { readonly kind: "shared"; readonly index: number; readonly path: Path }
+    | { readonly kind: "local"; readonly local: number }
+    | { readonly kind: "unary"; readonly operator: Unary; readonly operand: Expression }
+    | { readonly kind: "binary"; readonly operator: Binary; readonly left: Expression; readonly right: Expression }
+    | { readonly kind: "logical"; readonly operator: "&&" | "||" | "??"; readonly left: Expression; readonly right: Expression }
+    | { readonly kind: "conditional"; readonly test: Expression; readonly consequent: Expression; readonly alternate: Expression }
+    | { readonly kind: "math"; readonly name: string; readonly arguments: readonly Expression[] }
+    /** Reads inside convert boolean columns to booleans: a position where `true` and `1` differ. */
+    | { readonly kind: "observe"; readonly value: Expression }
+    | { readonly kind: "lane"; readonly intrinsic: number; readonly lane: number; readonly value: Expression }
+    /** A lookup through an index's list, in the local `list` holds, and its rows, in the locals `row` holds: as in `Program`. */
+    | { readonly kind: "listLength"; readonly list: number; readonly lookup: number }
+    | { readonly kind: "listChanged"; readonly list: number; readonly lookup: number }
+    | { readonly kind: "rowLeaf"; readonly row: number; readonly lookup: number; readonly leaf: number }
+    | { readonly kind: "rowEntity"; readonly row: number; readonly lookup: number }
+    /** Whether the row in `row` was found: `true` or `null` in JS, so it tests as a lookup's result does. */
+    | { readonly kind: "rowFound"; readonly row: number; readonly lookup: number }
+    // JS only:
+    | { readonly kind: "nullish"; readonly value: "null" | "undefined" }
+    | { readonly kind: "string"; readonly value: string }
+    | { readonly kind: "element"; readonly object: Expression; readonly index: Expression; readonly optional: boolean }
+    | { readonly kind: "array"; readonly items: readonly Expression[] }
+    | { readonly kind: "record"; readonly fields: readonly (readonly [string, Expression])[] };
+
+export type Statement =
+    | { readonly kind: "set"; readonly local: number; readonly value: Expression; readonly declare: "const" | "let" | undefined }
+    /** Declares `let` locals that every path assigns before reading. */
+    | { readonly kind: "declare"; readonly locals: readonly number[] }
+    | { readonly kind: "store"; readonly column: number; readonly value: Expression }
+    /** Stamps a changed column at the row, and its chunk and block columns at the row's chunk and block. */
+    | { readonly kind: "stamp"; readonly column: number; readonly chunks: number; readonly blocks: number }
+    | { readonly kind: "if"; readonly test: Expression; readonly consequent: Out; readonly alternate: Out }
+    | { readonly kind: "block"; readonly label: number; readonly body: Out }
+    | { readonly kind: "loop"; readonly label: number; readonly body: Out }
+    | { readonly kind: "branch"; readonly label: number }
+    | { readonly kind: "branchIf"; readonly label: number; readonly test: Expression }
+    | { readonly kind: "next" }
+    /** An intrinsic region, as in `Program`; only GPU kernels have them. */
+    | { readonly kind: "intrinsic"; readonly id: number; readonly name: string; readonly intrinsic: Program.Intrinsic; readonly operands: readonly (readonly Expression[])[]; readonly body: Out }
+    /** A lookup through an index, as in `Program`, by `probe`, into the locals `list` and `first` hold. */
+    | { readonly kind: "probe"; readonly list: number; readonly first: number; readonly lookup: number; readonly probe: number; readonly values: readonly Expression[] }
+    | { readonly kind: "listRow"; readonly row: number; readonly list: number; readonly lookup: number; readonly index: Expression }
+    // JS only:
+    | { readonly kind: "lookup"; readonly local: number; readonly lookup: number; readonly entity: Expression }
+    /**
+     * `KernelCommands`: `spawn` stages a spawn through spawner `list`, an index into `Unit.spawns`, with one value per
+     * component of the list, into `local`; `begin` starts a despawn (1), add (2) or remove (3).
+     */
+    | { readonly kind: "spawn"; readonly local: number; readonly list: number; readonly values: readonly Expression[] }
+    | { readonly kind: "begin"; readonly command: 1 | 2 | 3; readonly entity: Expression }
+    /** A component (index into `keys`) and its value for the current spawn or add. */
+    | { readonly kind: "value"; readonly key: number; readonly value: Expression }
+    /** A component (index into `keys`) for the current remove. */
+    | { readonly kind: "component"; readonly key: number };
+
+export const number = (value: number): Expression => ({ kind: "number", value });
+export const local = (index: number): Expression => ({ kind: "local", local: index });
+export const not = (operand: Expression): Expression => ({ kind: "unary", operator: "!", operand });
+
+/** Whether `expression` reads anything `matches`. */
+export const references = (expression: Expression, matches: (node: Expression) => boolean): boolean => {
+    if (matches(expression)) return true;
+    switch (expression.kind) {
+        case "unary": return references(expression.operand, matches);
+        case "binary": case "logical": return references(expression.left, matches) || references(expression.right, matches);
+        case "conditional": return [expression.test, expression.consequent, expression.alternate].some(item => references(item, matches));
+        case "math": return expression.arguments.some(item => references(item, matches));
+        case "observe": case "lane": return references(expression.value, matches);
+        case "element": return references(expression.object, matches) || references(expression.index, matches);
+        case "array": return expression.items.some(item => references(item, matches));
+        case "record": return expression.fields.some(([, item]) => references(item, matches));
+        default: return false;
+    }
+};

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

@@ -0,0 +1,34 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/// <reference types="node" />
+import { createHash } from 'node:crypto';
+
+const servePrefix = "/@ecs-kernel/";
+const buildPrefix = "\0ecs-kernel:";
+
+/** `hash` is set for serve urls: the version of the kernel the description was compiled against. */
+export type KernelId = { readonly parent: string; readonly index: number; readonly hash: string | undefined };
+
+const encode = (parent: string, index: number): string => `${Buffer.from(parent).toString("base64url")}/${index}.js`;
+
+/** A short hash of a kernel's identity (its description and module source). */
+export const kernelHash = (identity: string): string => createHash("sha256").update(identity).digest("base64url").slice(0, 10);
+
+/**
+ * The root-absolute url of a kernel module on the dev server, which a page and its module workers import from it. The
+ * hash makes an edited kernel a new module, and lets `load` reject a stale url.
+ */
+export const serveUrl = (parent: string, index: number, hash: string): string => `${servePrefix}${encode(parent, index)}?h=${hash}`;
+
+/** The virtual id of a kernel module emitted as a chunk in a build. */
+export const buildId = (parent: string, index: number): string => `${buildPrefix}${encode(parent, index)}`;
+
+/** Parses a serve url or build id. */
+export const parseKernelId = (id: string): KernelId | undefined => {
+    const prefix = id.startsWith(servePrefix) ? servePrefix : id.startsWith(buildPrefix) ? buildPrefix : undefined;
+    if (prefix === undefined) return undefined;
+    const [path = "", query = ""] = id.slice(prefix.length).split("?");
+    const match = /^([\w-]+)\/(\d+)\.js$/.exec(path);
+    if (match === null) return undefined;
+    const hash = new URLSearchParams(query).get("h") ?? undefined;
+    return { parent: Buffer.from(match[1] ?? "", "base64url").toString(), index: Number(match[2]), hash };
+};

package/src/implementation/compiler/key.ts

@@ -0,0 +1,33 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { AssignmentProperty, MemberExpression, Node, Property } from 'estree';
+import { fail } from './failure.js';
+import type { Out } from './out.js';
+import { findLocal, type Scope } from './scope.js';
+import type { Value } from './value.js';
+
+/**
+ * An index into a value: a static name or element, a binding of the kernel's own module (a component, resource or
+ * command key), or a runtime value. Other values that are number or string literals, such as constants of other
+ * modules and locals, fold to static indices.
+ */
+export type Key =
+    | { readonly kind: "static"; readonly name: number | string }
+    | { readonly kind: "binding"; readonly name: string }
+    | { readonly kind: "value"; readonly value: Value };
+
+const keyOf = (node: Node, computed: boolean, scope: Scope, out: Out): Key => {
+    if (!computed && node.type === "Identifier") return { kind: "static", name: node.name };
+    if (node.type === "Literal" && (typeof node.value === "number" || typeof node.value === "string")) return { kind: "static", name: node.value };
+    if (node.type === "Identifier" && findLocal(scope, node.name) === undefined && scope.module === scope.unit.module && scope.module.bindings.has(node.name)) {
+        return { kind: "binding", name: node.name };
+    }
+    if (node.type === "PrivateIdentifier") return fail(node, "private names are not in the kernel subset");
+    const value = scope.unit.expression(node, scope, out);
+    const expression = value.kind === "scalar" ? value.expression : undefined;
+    if (expression?.kind === "number" || expression?.kind === "string") return { kind: "static", name: expression.value };
+    return { kind: "value", value };
+};
+
+export const memberKey = (node: MemberExpression, scope: Scope, out: Out): Key => keyOf(node.property, node.computed, scope, out);
+
+export const propertyKey = (property: Property | AssignmentProperty, scope: Scope, out: Out): Key => keyOf(property.key, property.computed, scope, out);

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

@@ -0,0 +1,73 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, test } from 'vitest';
+import { parseAst } from 'vite';
+import { createLinker, isPending, resolveExport, type Link, type LinkHost } from './link.js';
+import { estreeOf } from './estree.js';
+import { nodeCopies } from './paths.js';
+
+const parse = (code: string) => estreeOf(parseAst(code));
+
+/** Resolves `./name.js` to `/name.js`, and loads from `files`, which tests may change. */
+const host = (files: Map<string, string>, gate: Promise<void> = Promise.resolve()): LinkHost => ({
+    packages: nodeCopies,
+    resolve: async specifier => `/${specifier.replace(/^\.\//, "")}`,
+    load: async file => {
+        const code = files.get(file);
+        await gate;
+        return code === undefined ? { error: `${file} can't be read` } : { code };
+    },
+});
+
+/** Resolves an export, loading what it needs. */
+const resolved = async (link: Link, file: string, name: string) => {
+    for (;;) {
+        try {
+            return resolveExport(link, file, name);
+        } catch (error) {
+            if (!isPending(error)) throw error;
+            await error.pending;
+        }
+    }
+};
+
+describe("linker", () => {
+    test("reports why an export * target failed when nothing else exports the name", async () => {
+        const files = new Map([["/barrel.js", "export * from './missing.js';"]]);
+        expect(await resolved(createLinker(host(files), parse), "/barrel.js", "f")).toEqual({ kind: "error", error: "/missing.js can't be read" });
+    });
+
+    test("an ambiguous export * deeper down is ambiguous", async () => {
+        const files = new Map([
+            ["/top.js", "export * from './both.js';\nexport * from './c.js';"],
+            ["/c.js", "export const f = 3;"],
+            ["/both.js", "export * from './a.js';\nexport * from './b.js';"],
+            ["/a.js", "export const f = 1;"],
+            ["/b.js", "export const f = 2;"],
+        ]);
+        expect(await resolved(createLinker(host(files), parse), "/top.js", "f")).toMatchObject({ kind: "error", error: "f is exported by more than one export * of /both.js" });
+    });
+
+    test("a default class export is a class, not a missing export", async () => {
+        const files = new Map([["/shape.js", "export default class Shape {}"]]);
+        const result = await resolved(createLinker(host(files), parse), "/shape.js", "default");
+        expect(result.kind === "binding" ? result.binding.kind : result.kind).toBe("other");
+    });
+
+    test("a file changed while loading is loaded again", async () => {
+        const files = new Map([["/value.js", "export const v = 1;"]]);
+        let open = (): void => {};
+        const gate = new Promise<void>(resolve => { open = resolve; });
+        const linker = createLinker(host(files, gate), parse);
+        let first: unknown;
+        try {
+            linker.module("/value.js");
+        } catch (error) {
+            first = error;
+        }
+        files.set("/value.js", "export const w = 2;");
+        linker.forget("/value.js", false);
+        open();
+        if (isPending(first)) await first.pending;
+        expect(await resolved(linker, "/value.js", "w")).toMatchObject({ kind: "binding", name: "w" });
+    });
+});