@adobe/ecs 0.0.0-stage → 0.2.0

package/src/implementation/compiler/link.ts

@@ -0,0 +1,231 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Program } from 'estree';
+import { createModule, locateIn, type Module, type ModuleBinding } from './module-scope.js';
+import type { PackageCopies } from './package-copies.js';
+
+/**
+ * Why a specifier names no file the linker can read. `unreadable` marks one the build leaves unread, such as a package
+ * external to it, rather than one that fails to resolve.
+ */
+export type Unresolved = { readonly error: string; readonly unreadable?: boolean };
+
+/** How the linker reaches other modules. Errors are reasons, reported only if a kernel uses what failed. */
+export type LinkHost = {
+    /** The file an import specifier names from `importer`. */
+    readonly resolve: (specifier: string, importer: string) => Promise<string | Unresolved>;
+    /** A file's code as JavaScript, and how offsets in it map to source lines when it was compiled from another language. */
+    readonly load: (file: string) => Promise<{ readonly code: string; readonly locate?: Module["locate"] } | { readonly error: string }>;
+    /** The operator each resource a file declares with a `reduce` trait reduces with, by its key's binding. */
+    readonly reductions?: (file: string) => ReadonlyMap<string, string>;
+    /** The components a file declares `shared`, by their keys' bindings. */
+    readonly shared?: (file: string) => ReadonlySet<string>;
+    /** The copies of the package the files are in. */
+    readonly packages: PackageCopies;
+};
+
+/**
+ * Modules as the compiler sees them. Both answer from what the linker has loaded, and when it hasn't loaded something
+ * yet they throw a `Pending`, which `transformKernels` awaits before compiling the kernel again.
+ */
+export type Link = {
+    readonly module: (file: string) => Module | { readonly error: string };
+    readonly resolve: (specifier: string, importer: string) => string | Unresolved;
+    /** The operator the resource `binding` of `file` declares in its `reduce` trait, if the build can read one. */
+    readonly reductionOf?: (file: string, binding: string) => string | undefined;
+    /** Whether the component `binding` of `file` declares `shared: true`, so kernels read its value per call. */
+    readonly sharedOf?: (file: string, binding: string) => boolean;
+    /** The copies of the package the modules are in. */
+    readonly packages: PackageCopies;
+};
+
+/** A cache of modules and resolutions shared across transforms. */
+export type Linker = Link & {
+    /** Adds the module being transformed, so imports back into it resolve to the same module. */
+    readonly add: (module: Module) => void;
+    /** Drops a changed file, and with `resolutions` every resolution, for files that were created or deleted. */
+    readonly forget: (file: string, resolutions: boolean) => void;
+};
+
+type Pending = { readonly pending: Promise<void> };
+
+const reason = (error: unknown): string => error instanceof Error ? error.message : String(error);
+
+const pending = (promise: Promise<void>): never => {
+    const signal: Pending = { pending: promise };
+    throw signal;
+};
+
+export const isPending = (error: unknown): error is Pending =>
+    typeof error === "object" && error !== null && "pending" in error && error.pending instanceof Promise;
+
+type Loaded = Module | { readonly error: string };
+type Resolution = string | Unresolved;
+
+export const createLinker = (host: LinkHost, parse: (code: string) => Program): Linker => {
+    const modules = new Map<string, Loaded>();
+    const loading = new Map<string, Promise<void>>();
+    const resolutions = new Map<string, Resolution>();
+    const resolving = new Map<string, Promise<void>>();
+    /** Bumped when a file changes, or every resolution is dropped, so loads and resolutions in flight are discarded. */
+    const versions = new Map<string, number>();
+    let resolutionVersion = 0;
+    /** Starts resolving `specifier` and loading its file, unless either is known or in flight. */
+    const prefetch = (specifier: string, importer: string): Promise<void> => {
+        const key = `${importer}\0${specifier}`;
+        const resolved = resolutions.get(key);
+        if (resolved !== undefined) return typeof resolved === "string" ? startLoad(resolved) : Promise.resolve();
+        let promise = resolving.get(key);
+        if (promise === undefined) {
+            const version = resolutionVersion;
+            promise = host.resolve(specifier, importer)
+                .catch((error: unknown) => ({ error: `${specifier} can't be resolved from ${importer}: ${reason(error)}` }))
+                .then(result => {
+                    if (version !== resolutionVersion) return;
+                    resolutions.set(key, result);
+                    if (typeof result === "string") void startLoad(result);
+                })
+                .finally(() => resolving.delete(key));
+            resolving.set(key, promise);
+        }
+        return promise;
+    };
+    const startLoad = (file: string): Promise<void> => {
+        if (modules.has(file)) return Promise.resolve();
+        let promise = loading.get(file);
+        if (promise === undefined) {
+            promise = load(file).finally(() => loading.delete(file));
+            loading.set(file, promise);
+        }
+        return promise;
+    };
+    /**
+     * Loads a module, then starts on the modules it re-exports: compiling stops at each module it doesn't have yet,
+     * and a namespace's members are usually found through re-exports.
+     */
+    const load = async (file: string): Promise<void> => {
+        const version = versions.get(file) ?? 0;
+        const loaded = await host.load(file).catch((error: unknown) => ({ error: `${file} can't be read: ${reason(error)}` }));
+        if (version !== (versions.get(file) ?? 0)) return;
+        if ("error" in loaded) {
+            modules.set(file, loaded);
+            return;
+        }
+        let module: Module;
+        try {
+            module = createModule(file, parse(loaded.code), loaded.locate ?? locateIn(loaded.code));
+        } catch (error) {
+            modules.set(file, { error: `${file} can't be parsed: ${reason(error)}` });
+            return;
+        }
+        modules.set(file, module);
+        for (const exported of module.exports.values()) if (exported.kind !== "local") void prefetch(exported.specifier, file);
+        for (const star of module.stars) void prefetch(star, file);
+    };
+    const reductions = new Map<string, ReadonlyMap<string, string>>();
+    const shared = new Map<string, ReadonlySet<string>>();
+    return {
+        module: file => modules.get(file) ?? pending(startLoad(file)),
+        reductionOf: (file, binding) => {
+            let declared = reductions.get(file);
+            if (declared === undefined && host.reductions !== undefined) reductions.set(file, declared = host.reductions(file));
+            return declared?.get(binding);
+        },
+        sharedOf: (file, binding) => {
+            let declared = shared.get(file);
+            if (declared === undefined && host.shared !== undefined) shared.set(file, declared = host.shared(file));
+            return declared?.has(binding) === true;
+        },
+        resolve: (specifier, importer) => resolutions.get(`${importer}\0${specifier}`) ?? pending(prefetch(specifier, importer)),
+        packages: host.packages,
+        add: module => { modules.set(module.file, module); },
+        forget: (file, all) => {
+            modules.delete(file);
+            reductions.delete(file);
+            shared.delete(file);
+            loading.delete(file);
+            versions.set(file, (versions.get(file) ?? 0) + 1);
+            if (all) {
+                resolutions.clear();
+                resolving.clear();
+                resolutionVersion++;
+            }
+        },
+    };
+};
+
+/** A name as the linker resolves it: a definition in its module, a module namespace, or why it isn't one. */
+export type Resolved =
+    | { readonly kind: "binding"; readonly module: Module; readonly name: string; readonly binding: Exclude<ModuleBinding, { kind: "import" | "importNamespace" }> }
+    | { readonly kind: "namespace"; readonly file: string }
+    /**
+     * `cause` tells a name a module doesn't export, one several `export *` provide, and one in a module the build leaves
+     * unread, from failing to tell.
+     */
+    | { readonly kind: "error"; readonly error: string; readonly cause?: "missing" | "ambiguous" | "unreadable" };
+
+/** A resolution that names no file, as a `Resolved`. */
+const unresolved = ({ error, unreadable }: Unresolved): Resolved => unreadable === true ? { kind: "error", error, cause: "unreadable" } : { kind: "error", error };
+
+const sameResolution = (a: Resolved, b: Resolved): boolean =>
+    a.kind === "binding" && b.kind === "binding" ? a.module === b.module && a.name === b.name
+        : a.kind === "namespace" && b.kind === "namespace" && a.file === b.file;
+
+/** Follows a binding of `module` through imports to its definition. */
+export const resolveBinding = (link: Link, module: Module, name: string, binding: ModuleBinding, seen: Set<string> = new Set()): Resolved => {
+    switch (binding.kind) {
+        case "import": case "importNamespace": {
+            const file = link.resolve(binding.specifier, module.file);
+            if (typeof file !== "string") return unresolved(file);
+            return binding.kind === "importNamespace" ? { kind: "namespace", file } : resolveExport(link, file, binding.imported, seen);
+        }
+        default:
+            return { kind: "binding", module, name, binding };
+    }
+};
+
+/** What `file` exports as `name`, following re-exports and `export *`. */
+export const resolveExport = (link: Link, file: string, name: string, seen: Set<string> = new Set()): Resolved => {
+    const module = link.module(file);
+    if ("error" in module) return { kind: "error", error: module.error };
+    const missing: Resolved = { kind: "error", error: `${name} isn't exported by ${file}`, cause: "missing" };
+    const key = `${file}\0${name}`;
+    if (seen.has(key)) return missing;
+    seen.add(key);
+    const exported = module.exports.get(name);
+    if (exported !== undefined) {
+        switch (exported.kind) {
+            case "local": {
+                const binding = module.bindings.get(exported.local);
+                return binding === undefined ? missing : resolveBinding(link, module, exported.local, binding, seen);
+            }
+            case "reexport": case "namespace": {
+                const target = link.resolve(exported.specifier, file);
+                if (typeof target !== "string") return unresolved(target);
+                return exported.kind === "namespace" ? { kind: "namespace", file: target } : resolveExport(link, target, exported.imported, seen);
+            }
+        }
+    }
+    if (name === "default") return missing;
+    // Every star is searched, to find ambiguity; what isn't loaded yet is waited for together. A star that is
+    // ambiguous itself makes the name ambiguous, and one that fails is the reason when no other star exports it.
+    const found: Resolved[] = [];
+    const failures: Resolved[] = [];
+    const waiting: Promise<void>[] = [];
+    for (const star of module.stars) {
+        try {
+            const target = link.resolve(star, file);
+            const result: Resolved = typeof target === "string" ? resolveExport(link, target, name, new Set(seen)) : unresolved(target);
+            if (result.kind !== "error") {
+                if (!found.some(item => sameResolution(item, result))) found.push(result);
+            }
+            else if (result.cause === "ambiguous") return result;
+            else if (result.cause !== "missing") failures.push(result);
+        } catch (error) {
+            if (!isPending(error)) throw error;
+            waiting.push(error.pending);
+        }
+    }
+    if (waiting.length > 0) pending(Promise.all(waiting).then(() => undefined));
+    if (found.length > 1) return { kind: "error", error: `${name} is exported by more than one export * of ${file}`, cause: "ambiguous" };
+    return found[0] ?? failures[0] ?? missing;
+};

package/src/implementation/compiler/lists.ts

@@ -0,0 +1,230 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { ArrayExpression, Expression, Node } from 'estree';
+import { children } from './estree.js';
+import { resolveBinding, resolveExport, type Link, type Resolved } from './link.js';
+import type { Module, ModuleBinding } from './module-scope.js';
+
+/** The keys a list names, each as an expression of the kernel's module; or why the node isn't a list the compiler can read. */
+export type ListNames = readonly string[] | { readonly error: string };
+
+/** How a kernel's module reads its lists of keys, wherever they are declared. */
+export type Lists = {
+    /**
+     * The keys a list names: an array literal of the kernel's module-scope identifiers, or a constant, of the kernel's
+     * module or imported through any re-exports and namespaces, holding an array literal.
+     * A key of another module's list is named by the kernel's binding of the same definition, or else by the list
+     * itself, as `List[k]`.
+     */
+    readonly names: (node: Node) => ListNames;
+    /**
+     * What a command's component argument names: a list, or one key by the expression the kernel's module names it with.
+     * A name is one key when its definition is a call of the global `Symbol`, identified or not, or a literal, which
+     * registration rejects for not being a symbol. A name defined in a module the build can't read, such as a package
+     * external to it, is taken as a key, and registration rejects a list there. Anything else fails with the reason.
+     */
+    readonly component: (node: Node) => Named;
+    /** Whether the component the kernel's module names `name` is declared `shared`, read through the build from the module declaring it. */
+    readonly shared: (name: string) => boolean;
+    /**
+     * The operator the resource the kernel's module names `name` reduces with, its declaration's `reduce` trait, read
+     * through the build from the module declaring it, undefined where the build can't read one, and that module's file;
+     * null for a name the module doesn't bind.
+     */
+    readonly reduction: (name: string) => { readonly operator: string | undefined; readonly file: string } | null;
+};
+
+/** What a command's component argument names, or why the compiler can't tell. */
+export type Named = { readonly kind: "list" } | { readonly kind: "key"; readonly name: string } | { readonly kind: "error"; readonly error: string };
+
+/** A list's array literal, the module it's written in, and how the kernel's module refers to it. */
+type Found = { readonly literal: ArrayExpression; readonly module: Module; readonly reference: string };
+
+/** What a name is defined as: a list, a key by its definition's identity (null where the build can't read it), or why it's neither. */
+type Followed = Found | { readonly key: string | null } | { readonly error: string };
+
+/** Whether a name may be one key as well as a list, which words the reasons it's neither. */
+type Wanted = "list" | "either";
+
+/** A call of the global `Symbol` in `module`. */
+const isSymbolCall = (node: Expression, module: Module): boolean =>
+    node.type === "CallExpression" && node.callee.type === "Identifier" && node.callee.name === "Symbol" && !module.bindings.has("Symbol");
+
+/** A key's definition: `Symbol(...)`, as the plugin identifies it, `identify$(Symbol(...), id)`, or a literal. */
+const isKey = (node: Expression, module: Module): boolean => {
+    if (node.type === "Literal") return !("regex" in node);
+    if (isSymbolCall(node, module)) return true;
+    if (node.type !== "CallExpression" || node.callee.type !== "Identifier" || !/^identify\$\d*$/.test(node.callee.name)) return false;
+    const [symbol] = node.arguments;
+    return module.bindings.get(node.callee.name)?.kind === "function" && symbol !== undefined && symbol.type !== "SpreadElement" && isSymbolCall(symbol, module);
+};
+
+/** A list's literal as the plugin gives it an index, `archetype$([...])` with its appended function: the literal, else null. */
+const indexedList = (node: Expression, module: Module): ArrayExpression | null => {
+    if (node.type !== "CallExpression" || node.arguments.length !== 1 || node.callee.type !== "Identifier" || !/^archetype\$\d*$/.test(node.callee.name)) return null;
+    const [list] = node.arguments;
+    return module.bindings.get(node.callee.name)?.kind === "function" && list.type === "ArrayExpression" ? list : null;
+};
+
+const fileOf = (module: Module, kernel: Module): string => module === kernel ? "this module" : module.file;
+
+/** Follows a binding to the array literal or key its constant holds, through imports and constants naming another. */
+const follow = (name: string, binding: ModuleBinding, module: Module, kernel: Module, link: Link | null, reference: string, wanted: Wanted, seen: Set<string>): Followed => {
+    const identity = `${module.file}\0${name}`;
+    if (seen.has(identity)) return { error: `${reference} refers to itself` };
+    seen.add(identity);
+    const unread = wanted === "list" ? "the compiler can't read its components" : "the compiler can't tell whether it's a key or a list";
+    switch (binding.kind) {
+        case "const": {
+            const { init } = binding;
+            if (init.type === "ArrayExpression") return { literal: init, module, reference };
+            const indexed = indexedList(init, module);
+            if (indexed !== null) return { literal: indexed, module, reference };
+            if (init.type === "Identifier") {
+                const aliased = module.bindings.get(init.name);
+                if (aliased !== undefined) return follow(init.name, aliased, module, kernel, link, reference, wanted, seen);
+            }
+            if (isKey(init, module)) return { key: identity };
+            const declare = wanted === "list" ? "declare it as an array literal, `as const`" : "declare a key as Symbol(...), or a list as an array literal, `as const`";
+            return { error: `${reference} is computed when ${fileOf(module, kernel)} runs, so ${unread}; ${declare}` };
+        }
+        case "import": case "importNamespace":
+            // Without a linker nothing imported can be read, so a name that may be one key is taken as one.
+            if (link === null) return wanted === "list" ? { error: `${reference} is imported, and this build doesn't link imports` } : { key: null };
+            return followResolved(resolveBinding(link, module, name, binding), kernel, link, reference, wanted, seen);
+        case "function": case "other":
+            return { error: `${reference} isn't a module-scope const, so ${unread}` };
+    }
+};
+
+const followResolved = (resolved: Resolved, kernel: Module, link: Link | null, reference: string, wanted: Wanted, seen: Set<string>): Followed => {
+    switch (resolved.kind) {
+        case "error": return wanted === "either" && resolved.cause === "unreadable" ? { key: null } : { error: resolved.error };
+        case "namespace": return { error: `${reference} is a module namespace, not ${wanted === "list" ? "a list of components" : "a key or a list of components"}` };
+        case "binding": return follow(resolved.name, resolved.binding, resolved.module, kernel, link, reference, wanted, seen);
+    }
+};
+
+/** The names of a member chain of identifiers, `A.B.C`, outermost first; null for any other node. */
+const chain = (node: Node): readonly string[] | null => {
+    if (node.type === "Identifier") return [node.name];
+    if (node.type !== "MemberExpression" || node.computed || node.property.type !== "Identifier") return null;
+    const object = chain(node.object);
+    return object === null ? null : [...object, node.property.name];
+};
+
+/** What a node names: an array literal, or the definition an identifier or a namespace member chain names. */
+const find = (node: Node, kernel: Module, link: Link | null, wanted: Wanted): Followed => {
+    if (node.type === "ArrayExpression") return { literal: node, module: kernel, reference: "" };
+    const names = chain(node);
+    if (names === null) return { error: "commands and kernel declarations name a list as an array literal, or a constant holding one" };
+    const [first, ...members] = names;
+    const reference = names.join(".");
+    const binding = kernel.bindings.get(first);
+    if (binding === undefined) return { error: `${first} isn't bound at module scope` };
+    if (members.length === 0) return follow(first, binding, kernel, kernel, link, reference, wanted, new Set());
+    const what = wanted === "list" ? "a list" : "a key or a list";
+    if (binding.kind !== "importNamespace") return { error: `${first} isn't a module namespace, so ${reference} isn't ${what} the compiler can read` };
+    if (link === null) return wanted === "list" ? { error: `${reference} is imported, and this build doesn't link imports` } : { key: null };
+    let resolved = resolveBinding(link, kernel, first, binding);
+    for (const member of members) {
+        if (resolved.kind === "error") return followResolved(resolved, kernel, link, reference, wanted, new Set());
+        if (resolved.kind !== "namespace") return { error: `${reference} isn't ${what} the compiler can read` };
+        resolved = resolveExport(link, resolved.file, member);
+    }
+    return followResolved(resolved, kernel, link, reference, wanted, new Set());
+};
+
+/** The identity of what a binding of `module` defines: its module and name, through imports; null where it can't be followed. */
+const definition = (module: Module, name: string, binding: ModuleBinding, link: Link | null): string | null => {
+    if (binding.kind !== "import" && binding.kind !== "importNamespace") return `${module.file}\0${name}`;
+    if (link === null) return null;
+    const resolved = resolveBinding(link, module, name, binding);
+    return resolved.kind === "binding" ? `${resolved.module.file}\0${resolved.name}` : null;
+};
+
+/**
+ * Lists as `kernel` reads them. `nodes` are the kernel's declaration and body: the kernel's names for keys of other
+ * modules' lists are found among the module-scope identifiers they use, so only those are followed.
+ */
+export const createLists = (kernel: Module, link: Link | null, nodes: readonly Node[]): Lists => {
+    /** Each key definition's name in the kernel's module, filled from the kernel's identifiers when a list of another module is first read. */
+    let named: Map<string, string> | null = null;
+    const nameOf = (identity: string, fallback: string): string => {
+        if (named === null) {
+            const found = new Map<string, string>();
+            const followed = new Set<string>();
+            const visit = (node: Node): void => {
+                if (node.type === "Identifier" && !followed.has(node.name)) {
+                    followed.add(node.name);
+                    const binding = kernel.bindings.get(node.name);
+                    const defined = binding === undefined ? null : definition(kernel, node.name, binding, link);
+                    if (defined !== null && !found.has(defined)) found.set(defined, node.name);
+                }
+                for (const child of children(node)) visit(child);
+            };
+            for (const node of nodes) visit(node);
+            named = found;
+        }
+        const name = named.get(identity);
+        if (name !== undefined) return name;
+        named.set(identity, fallback);
+        return fallback;
+    };
+    const names = (node: Node): ListNames => {
+        const found = find(node, kernel, link, "list");
+        if ("key" in found) {
+            const reference = chain(node)?.join(".") ?? "";
+            return { error: `${reference} is a key, not a list of components; list it as [${reference}]` };
+        }
+        if (!("literal" in found)) return found;
+        const { literal, module, reference } = found;
+        const result: string[] = [];
+        for (let k = 0; k < literal.elements.length; k++) {
+            const element = literal.elements[k];
+            // The kernel's own list may spread another it can read: `with: [...Unit, tagged]`.
+            if (element?.type === "SpreadElement" && module === kernel) {
+                const spread = names(element.argument);
+                if ("error" in spread) return spread;
+                result.push(...spread);
+                continue;
+            }
+            const binding = element?.type === "Identifier" ? module.bindings.get(element.name) : undefined;
+            if (element?.type !== "Identifier" || binding === undefined) {
+                return { error: module === kernel ? "lists name keys by identifiers bound at module scope" : `${reference} names a key by something other than an identifier bound at the scope of ${module.file}` };
+            }
+            if (module === kernel) {
+                result.push(element.name);
+                continue;
+            }
+            const fallback = `${reference}[${k}]`;
+            const identity = definition(module, element.name, binding, link);
+            result.push(identity === null ? fallback : nameOf(identity, fallback));
+        }
+        return result;
+    };
+    const component = (node: Node): Named => {
+        const found = find(node, kernel, link, "either");
+        if ("literal" in found) return { kind: "list" };
+        if ("error" in found) return { kind: "error", error: found.error };
+        const reference = chain(node)?.join(".") ?? "";
+        // A key named by an identifier is that identifier; one named through a namespace is the kernel's own binding of
+        // its definition where it has one.
+        return { kind: "key", name: node.type === "Identifier" || found.key === null ? reference : nameOf(found.key, reference) };
+    };
+    const reduction = (name: string): { readonly operator: string | undefined; readonly file: string } | null => {
+        const binding = kernel.bindings.get(name);
+        const identity = binding === undefined ? null : definition(kernel, name, binding, link);
+        if (identity === null) return null;
+        const [file = "", defined = ""] = identity.split("\0");
+        return { operator: link?.reductionOf?.(file, defined), file };
+    };
+    /** Whether a key the kernel names is a shared component, as its declaration's module says. */
+    const shared = (name: string): boolean => {
+        const binding = kernel.bindings.get(name);
+        const identity = binding === undefined ? null : definition(kernel, name, binding, link);
+        if (identity === null) return false;
+        const [file = "", defined = ""] = identity.split("\0");
+        return link?.sharedOf?.(file, defined) === true;
+    };
+    return { names, component, reduction, shared };
+};

package/src/implementation/compiler/lookups.ts

@@ -0,0 +1,121 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Expression, Node, ObjectExpression, Pattern, SpreadElement } from 'estree';
+import { children, declaredIn } from './estree.js';
+
+type Range = { readonly start: number; readonly end: number };
+
+/** How a call passes a key part: as in `world/index-lookups.ts`'s `Shape`, `0` whole, `n` a tuple of `n` scalars, or a comparison's operators. */
+type Form = number | readonly (readonly [string, number])[];
+
+/**
+ * A call of an index lookup in a main-thread body: its callee's source, its key's shape, and the source ranges of the
+ * values it passes, literals flattened.
+ */
+export type LookupSite = Range & { readonly callee: Range; readonly shape: readonly Form[]; readonly values: readonly Range[] };
+
+/** Arguments a site passes at most (`world/prepared-lookup.ts`). */
+const maximumArguments = 16;
+
+const operators: ReadonlySet<string> = new Set(["==", "!=", "<", ">", "<=", ">="]);
+
+/** A property's plain name: an identifier or a string literal, not computed. */
+const nameOf = (key: Node, computed: boolean): string | null =>
+    !computed && key.type === "Identifier" ? key.name : key.type === "Literal" && typeof key.value === "string" ? key.value : null;
+
+/** The names of a declaration's lookups that go through an index: those declared as an object literal with `index`. */
+const indexLookupsOf = (declaration: ObjectExpression): ReadonlySet<string> => {
+    const names = new Set<string>();
+    for (const property of declaration.properties) {
+        if (property.type !== "Property" || nameOf(property.key, property.computed) !== "lookup" || property.value.type !== "ObjectExpression") continue;
+        for (const lookup of property.value.properties) {
+            if (lookup.type !== "Property" || lookup.value.type !== "ObjectExpression") continue;
+            const name = nameOf(lookup.key, lookup.computed);
+            const indexed = lookup.value.properties.some(field => field.type === "Property" && nameOf(field.key, field.computed) === "index");
+            if (name !== null && indexed) names.add(name);
+        }
+    }
+    return names;
+};
+
+/** How a body reaches its lookups: the context's name, a name bound to `lookup`, and names bound to lookups themselves. */
+type Reach = { readonly context: string | null; readonly lookup: string | null; readonly direct: ReadonlyMap<string, string> };
+
+const reachOf = (parameter: Pattern | undefined, names: ReadonlySet<string>): Reach | null => {
+    if (parameter?.type === "Identifier") return { context: parameter.name, lookup: null, direct: new Map() };
+    if (parameter?.type !== "ObjectPattern") return null;
+    for (const property of parameter.properties) {
+        if (property.type !== "Property" || nameOf(property.key, property.computed) !== "lookup") continue;
+        if (property.value.type === "Identifier") return { context: null, lookup: property.value.name, direct: new Map() };
+        if (property.value.type !== "ObjectPattern") return null;
+        const direct = new Map<string, string>();
+        for (const inner of property.value.properties) {
+            if (inner.type !== "Property" || inner.value.type !== "Identifier") continue;
+            const name = nameOf(inner.key, inner.computed);
+            if (name !== null && names.has(name)) direct.set(inner.value.name, name);
+        }
+        return { context: null, lookup: null, direct };
+    }
+    return null;
+};
+
+/** The form and values of one argument: a tuple or comparison literal flattened, anything else whole. */
+const formOf = (argument: Expression): { readonly form: Form; readonly values: readonly Range[] } => {
+    if (argument.type === "ArrayExpression" && argument.elements.length > 0 && argument.elements.every(element => element !== null && element.type !== "SpreadElement")) {
+        return { form: argument.elements.length, values: argument.elements.flatMap(element => element === null ? [] : [{ start: element.start, end: element.end }]) };
+    }
+    if (argument.type === "ObjectExpression" && argument.properties.length > 0) {
+        const entries: [string, number][] = [];
+        const values: Range[] = [];
+        for (const property of argument.properties) {
+            if (property.type !== "Property" || property.kind !== "init" || property.method || property.computed) return { form: 0, values: [argument] };
+            const operator = nameOf(property.key, false);
+            if (operator === null || !operators.has(operator) || property.value.type === "AssignmentPattern" || property.value.type === "ObjectPattern"
+                || property.value.type === "ArrayPattern" || property.value.type === "RestElement") return { form: 0, values: [argument] };
+            const operand = formOf(property.value);
+            entries.push([operator, typeof operand.form === "number" ? operand.form : 0]);
+            values.push(...typeof operand.form === "number" ? operand.values : [property.value]);
+        }
+        return { form: entries, values };
+    }
+    return { form: 0, values: [argument] };
+};
+
+/**
+ * The index lookup calls in a main-thread body, whose context is its parameter at `context`: `context.lookup.name(key)`,
+ * `lookup.name(key)` and `name(key)` as the parameter's pattern binds them, for lookups the declaration declares with
+ * `index` in an object literal. A body that redeclares the names it reaches them by is left alone, and so is a call
+ * with a spread argument or more than `maximumArguments` values, or one inside another's arguments.
+ */
+export const lookupSites = (body: Node, declaration: ObjectExpression, context: number): readonly LookupSite[] => {
+    if (body.type !== "ArrowFunctionExpression" && body.type !== "FunctionExpression") return [];
+    const names = indexLookupsOf(declaration);
+    if (names.size === 0) return [];
+    const reach = reachOf(body.params[context], names);
+    if (reach === null) return [];
+    const declared = new Set<string>();
+    declaredIn(body.body, name => declared.add(name));
+    if ((reach.context !== null && declared.has(reach.context)) || (reach.lookup !== null && declared.has(reach.lookup))) return [];
+    /** Whether a callee is one of the declaration's index lookups, as the body reaches it. */
+    const isLookup = (callee: Node): boolean => {
+        if (callee.type === "Identifier") return reach.direct.has(callee.name) && !declared.has(callee.name);
+        if (callee.type !== "MemberExpression" || callee.computed || callee.optional || callee.property.type !== "Identifier" || !names.has(callee.property.name)) return false;
+        const { object } = callee;
+        if (object.type === "Identifier") return reach.lookup !== null && object.name === reach.lookup;
+        return reach.context !== null && object.type === "MemberExpression" && !object.computed && !object.optional && object.object.type === "Identifier"
+            && object.object.name === reach.context && object.property.type === "Identifier" && object.property.name === "lookup";
+    };
+    const sites: LookupSite[] = [];
+    const visit = (node: Node): void => {
+        if (node.type === "CallExpression" && !node.optional && isLookup(node.callee) && node.arguments.every((argument): argument is Expression => argument.type !== "SpreadElement")) {
+            const forms = node.arguments.map((argument: Expression | SpreadElement) => argument.type === "SpreadElement" ? { form: 0, values: [] } : formOf(argument));
+            const values = forms.flatMap(form => form.values);
+            if (values.length <= maximumArguments) {
+                sites.push({ start: node.start, end: node.end, callee: { start: node.callee.start, end: node.callee.end }, shape: forms.map(form => form.form), values });
+                return;
+            }
+        }
+        for (const child of children(node)) visit(child);
+    };
+    visit(body.body);
+    return sites;
+};

package/src/implementation/compiler/math.ts

@@ -0,0 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/** The `Math` functions allowed in kernels: pure and deterministic. */
+export const mathFunctions: ReadonlySet<string> = new Set([
+    "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",
+]);
+
+export const mathConstants: ReadonlySet<string> = new Set(["PI", "E", "LN2", "LN10", "LOG2E", "LOG10E", "SQRT2", "SQRT1_2"]);