@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/compiler/assign.ts

@@ -0,0 +1,167 @@
+import type { AssignmentExpression, Expression as SourceExpression, Node, Pattern, UpdateExpression } from 'estree';
+import { access } from './access.js';
+import { failPattern } from './bind.js';
+import { set } from './booleans.js';
+import { changedColumns, fieldColumn, fieldRead } from './columns.js';
+import { leavesOf, toData, type Data } from './data.js';
+import { fail } from './failure.js';
+import { isBinary, local, number, references, type Expression } from './ir.js';
+import { propertyKey } from './key.js';
+import type { Out } from './out.js';
+import { requireReadable } from './scalar.js';
+import { findLocal, type Scope } from './scope.js';
+import { snapshotLeaf } from './snapshot.js';
+import { fresh } from './unit.js';
+import { describeValue, type Value } from './value.js';
+
+/** One scalar store. `component` is set for row writes, which stamp the changed column. */
+type Target = { readonly kind: "local"; readonly local: number } | { readonly kind: "column"; readonly column: number };
+type Store = { readonly target: Target; readonly value: Expression; readonly component: string | undefined };
+
+const localTarget = (node: Node, expression: Expression): Target =>
+    expression.kind === "local" ? { kind: "local", local: expression.local } : fail(node, "this can't be assigned in a kernel");
+
+const root = (node: Node): string | undefined =>
+    node.type === "Identifier" ? node.name : node.type === "MemberExpression" ? root(node.object) : undefined;
+
+const requireWritable = (node: Node, scope: Scope, component: string): void => {
+    if (!scope.unit.signature.write.has(component)) fail(node, `${component} is not in components write`);
+    scope.unit.used.write.add(component);
+};
+
+/** Resolves an assignment target to a value whose scalar leaves are assignable. */
+const targetValue = (node: SourceExpression | Pattern, scope: Scope, out: Out): Value => {
+    const value = scope.unit.expression(node, scope, out);
+    if (value.kind === "component") {
+        if (value.up === true) return fail(node, "up is read-only");
+        requireWritable(node, scope, value.component);
+        // Values are immutable: a write replaces the whole component value.
+        if (value.path.length > 0) return fail(node, "component values are immutable; write the whole value");
+        return value;
+    }
+    if (node.type !== "Identifier") return fail(node, "values are immutable; assign a whole new value to a let local");
+    const name = root(node);
+    const local = name === undefined ? undefined : findLocal(scope, name);
+    if (value.kind === "dynamic" && (local?.mutable !== true || node.type !== "Identifier")) return fail(node, "resources, args and lookup results are read-only in kernels");
+    if (local === undefined) return fail(node, "this can't be assigned in a kernel");
+    if (!local.mutable) return fail(node, `${name} is const`);
+    return value;
+};
+
+/** Pairs a target with assigned data, leaf by leaf. */
+const pair = (node: Node, target: Value, data: Data, scope: Scope): readonly Store[] => {
+    const unit = scope.unit;
+    switch (target.kind) {
+        case "component": {
+            const leaves = leavesOf(data);
+            if (target.path.length === 0 && data.kind !== "leaf") {
+                unit.shapes.add(`{ component: ${target.component}, leaves: ${JSON.stringify(leaves.map(leaf => leaf.path))} }`);
+            }
+            return leaves.map(leaf => ({
+                target: { kind: "column", column: fieldColumn(unit, target.component, [...target.path, ...leaf.path]) }, value: leaf.expression, component: target.component,
+            }));
+        }
+        case "snapshot":
+            return leavesOf(data).map(leaf => ({
+                target: { kind: "local", local: snapshotLeaf(unit, target.snapshot, [...target.path, ...leaf.path]) }, value: leaf.expression, component: undefined,
+            }));
+        case "scalar": case "dynamic":
+            return data.kind === "leaf" ? [{ target: localTarget(node, target.expression), value: data.expression, component: undefined }] : fail(node, "can't assign a tuple or struct to a scalar");
+        case "tuple":
+            return data.kind === "tuple" && data.items.length === target.items.length
+                ? target.items.flatMap((item, index) => pair(node, item, data.items[index], scope))
+                : fail(node, "the assigned value must have the same shape");
+        case "struct":
+            if (data.kind !== "struct") return fail(node, "the assigned value must have the same shape");
+            return target.fields.flatMap(([name, field]) => {
+                const source = data.fields.find(([sourceName]) => sourceName === name);
+                return source ? pair(node, field, source[1], scope) : fail(node, `the assigned value has no field ${name}`);
+            });
+        default:
+            return fail(node, `can't assign to ${describeValue(target)}`);
+    }
+};
+
+const collect = (pattern: Pattern, value: Value, scope: Scope, out: Out): readonly Store[] => {
+    switch (pattern.type) {
+        case "ArrayPattern":
+            return pattern.elements.flatMap((element, index) => element === null ? []
+                : element.type === "RestElement" ? fail(element, "rest elements are not in the kernel subset")
+                : collect(element, access(value, { kind: "static", name: index }, element, scope, false), scope, out));
+        case "ObjectPattern":
+            return pattern.properties.flatMap(property => property.type === "RestElement"
+                ? fail(property, "rest elements are not in the kernel subset")
+                : collect(property.value, access(value, propertyKey(property, scope, out), property, scope, false), scope, out));
+        case "Identifier": case "MemberExpression":
+            return pair(pattern, targetValue(pattern, scope, out), toData(value, pattern, scope), scope);
+        default:
+            return failPattern(pattern);
+    }
+};
+
+/** Whether `value` reads what `target` writes. */
+const reads = (value: Expression, target: Target): boolean => references(value, node => target.kind === "local"
+    ? node.kind === "local" && node.local === target.local
+    : node.kind === "column" && node.column === target.column);
+
+/**
+ * Emits stores as if every right-hand leaf were evaluated first, so `[a, b] = [b, a]` swaps: a leaf that reads an
+ * earlier store's target is copied to a temporary first. Each written component is stamped once.
+ */
+const emit = (stores: readonly Store[], scope: Scope, out: Out): void => {
+    const unit = scope.unit;
+    const values = stores.map((store, index) => {
+        if (!stores.slice(0, index).some(earlier => reads(store.value, earlier.target))) return store.value;
+        const temporary = fresh(unit, "t");
+        out.push(set(unit, temporary, store.value, "const"));
+        return local(temporary);
+    });
+    stores.forEach((store, index) => out.push(store.target.kind === "local"
+        ? set(unit, store.target.local, values[index], undefined)
+        : { kind: "store", column: store.target.column, value: values[index] }));
+    for (const component of new Set(stores.flatMap(store => store.component === undefined ? [] : [store.component]))) {
+        out.push({ kind: "stamp", ...changedColumns(unit, component) });
+    }
+};
+
+/** A scalar read-modify-write target. */
+const compoundStore = (node: SourceExpression | Pattern, operator: string, operand: Expression, scope: Scope, out: Out): Store => {
+    if (!isBinary(operator)) return fail(node, `${operator}= is not in the kernel subset`);
+    const target = targetValue(node, scope, out);
+    const unit = scope.unit;
+    const combine = (current: Expression): Expression => ({ kind: "binary", operator, left: current, right: operand });
+    switch (target.kind) {
+        case "component":
+            requireReadable(node, scope, target.component);
+            return {
+                target: { kind: "column", column: fieldColumn(unit, target.component, target.path) },
+                value: combine(fieldRead(unit, target.component, target.path)), component: target.component,
+            };
+        case "snapshot": {
+            const leaf = snapshotLeaf(unit, target.snapshot, target.path);
+            return { target: { kind: "local", local: leaf }, value: combine(local(leaf)), component: undefined };
+        }
+        case "scalar": case "dynamic":
+            return { target: localTarget(node, target.expression), value: combine(target.expression), component: undefined };
+        default:
+            return fail(node, `compound assignment needs a scalar, not ${describeValue(target)}`);
+    }
+};
+
+const logical = new Set(["&&=", "||=", "??="]);
+
+/** Compiles an assignment statement. */
+export const assign = (node: AssignmentExpression, scope: Scope, out: Out): void => {
+    if (node.operator === "=") {
+        const value = scope.unit.expression(node.right, scope, out);
+        return emit(collect(node.left, value, scope, out), scope, out);
+    }
+    if (logical.has(node.operator)) return fail(node, `${node.operator} is not in the kernel subset`);
+    const operand = toData(scope.unit.expression(node.right, scope, out), node.right, scope);
+    if (operand.kind !== "leaf") return fail(node.right, "compound assignment needs a scalar");
+    emit([compoundStore(node.left, node.operator.slice(0, -1), operand.expression, scope, out)], scope, out);
+};
+
+/** Compiles `x++`, `--x` and friends as statements. */
+export const update = (node: UpdateExpression, scope: Scope, out: Out): void =>
+    emit([compoundStore(node.argument, node.operator === "++" ? "+" : "-", number(1), scope, out)], scope, out);

package/src/implementation/compiler/bind.ts

@@ -0,0 +1,87 @@
+import type { Identifier, Node, Pattern } from 'estree';
+import { access } from './access.js';
+import { set } from './booleans.js';
+import { componentRead } from './columns.js';
+import { dataValue, mapLeaves, toData } from './data.js';
+import { fail } from './failure.js';
+import { local, type Expression } from './ir.js';
+import { propertyKey } from './key.js';
+import type { Out } from './out.js';
+import { requireReadable } from './scalar.js';
+import type { Scope } from './scope.js';
+import { createSnapshot, snapshotDeclaration, snapshotLeaf } from './snapshot.js';
+import { fresh } from './unit.js';
+import { describeValue, type Value } from './value.js';
+
+/** How a local is bound. Parameters are mutable data, but may also alias non-data values like `row`. */
+export type Binding = "const" | "let" | "parameter";
+
+const isLiteral = (expression: Expression): boolean =>
+    expression.kind === "number" || expression.kind === "boolean" || expression.kind === "nullish";
+
+/** The value a new local holds: data is copied into fresh locals, so later writes elsewhere don't change it. */
+const declared = (node: Identifier, value: Value, binding: Binding, scope: Scope, out: Out): Value => {
+    const keyword = binding === "const" ? "const" : "let";
+    const unit = scope.unit;
+    const copy = (expression: Expression): Expression => {
+        if (binding === "const" && isLiteral(expression)) return expression;
+        const target = fresh(unit, node.name);
+        out.push(set(unit, target, expression, keyword));
+        return local(target);
+    };
+    switch (value.kind) {
+        case "scalar":
+            return { kind: "scalar", expression: copy(value.expression) };
+        case "dynamic": {
+            // Resources and args don't change while a kernel runs, so a const can alias them.
+            const constant = value.expression.kind === "resource" || value.expression.kind === "args";
+            return binding === "const" && constant ? value : { kind: "dynamic", expression: copy(value.expression) };
+        }
+        case "tuple": case "struct":
+            return dataValue(mapLeaves(toData(value, node, scope), copy));
+        case "component": {
+            if (value.up !== true) requireReadable(node, scope, value.component);
+            const snapshot = createSnapshot(keyword, node.name, path => componentRead(unit, value, path));
+            out.push(snapshotDeclaration(snapshot));
+            return { kind: "snapshot", snapshot, path: [] };
+        }
+        case "snapshot": {
+            const source = value;
+            const snapshot = createSnapshot(keyword, node.name, path => local(snapshotLeaf(unit, source.snapshot, [...source.path, ...path])));
+            out.push(snapshotDeclaration(snapshot));
+            return { kind: "snapshot", snapshot, path: [] };
+        }
+        // A row's values are read where they're used: a const reads them lazily, a let holds a copy.
+        case "rowRead":
+            return binding === "let" ? dataValue(mapLeaves(toData(value, node, scope), copy)) : value;
+        default:
+            return binding === "let" ? fail(node, `a let can't hold ${describeValue(value)}; use const`) : value;
+    }
+};
+
+/** Binds a declaration or parameter pattern to a value. */
+export const bind = (pattern: Pattern, value: Value, binding: Binding, scope: Scope, out: Out): void => {
+    switch (pattern.type) {
+        case "Identifier":
+            scope.locals.set(pattern.name, { value: declared(pattern, value, binding, scope, out), mutable: binding !== "const" });
+            return;
+        case "ArrayPattern":
+            pattern.elements.forEach((element, index) => {
+                if (element === null) return;
+                if (element.type === "RestElement") return fail(element, "rest elements are not in the kernel subset");
+                bind(element, access(value, { kind: "static", name: index }, element, scope, false), binding, scope, out);
+            });
+            return;
+        case "ObjectPattern":
+            for (const property of pattern.properties) {
+                if (property.type === "RestElement") return fail(property, "rest elements are not in the kernel subset");
+                bind(property.value, access(value, propertyKey(property, scope, out), property, scope, false), binding, scope, out);
+            }
+            return;
+        default:
+            return failPattern(pattern);
+    }
+};
+
+export const failPattern = (pattern: Node): never =>
+    fail(pattern, pattern.type === "AssignmentPattern" ? "default values are not in the kernel subset" : `${pattern.type} is not in the kernel subset`);

package/src/implementation/compiler/body-access.ts

@@ -0,0 +1,332 @@
+import type { Node, ObjectExpression, Pattern } from 'estree';
+import { children, declaredIn, patternNames } from './estree.js';
+import type { Used } from './exact.js';
+import type { ModuleScope } from './module-scope.js';
+
+const unknown: Used = { query: null, resources: null, lookups: null };
+
+/** Whether `node`, a child of `parent`, names a property or label, or declares a binding, rather than referring to one. */
+const isName = (node: Node, parent: Node | undefined): boolean => {
+    switch (parent?.type) {
+        case "MemberExpression": return parent.property === node && !parent.computed;
+        case "Property": return parent.key === node && !parent.computed && !parent.shorthand;
+        case "MethodDefinition": case "PropertyDefinition": return parent.key === node && !parent.computed;
+        case "LabeledStatement": case "BreakStatement": case "ContinueStatement": return true;
+        case "VariableDeclarator": return parent.id === node;
+        default: return false;
+    }
+};
+
+/** How `member`, a `name[key]` expression, is used: read, written, or both; null when it's a destructuring target or deleted. */
+const useOf = (member: Node, parent: Node | undefined): { readonly read: boolean; readonly write: boolean } | null => {
+    switch (parent?.type) {
+        case "AssignmentExpression":
+            return parent.left !== member ? { read: true, write: false } : { read: parent.operator !== "=", write: true };
+        case "UpdateExpression": return { read: true, write: true };
+        case "UnaryExpression": return parent.operator === "delete" ? null : { read: true, write: false };
+        case "ArrayPattern": case "RestElement": case "AssignmentPattern": case "ForInStatement": case "ForOfStatement":
+            return null;
+        case "Property": return parent.value === member && parent.shorthand ? null : { read: true, write: false };
+        default: return { read: true, write: false };
+    }
+};
+
+/** Whether a lookup result `value`, a child of `parent`, is only tested: compared with null, or used as a condition. */
+const isTested = (value: Node, parent: Node | undefined): boolean => {
+    switch (parent?.type) {
+        case "BinaryExpression": {
+            const other = parent.left === value ? parent.right : parent.left;
+            return ["===", "!==", "==", "!="].includes(parent.operator) && other.type === "Literal" && other.value === null;
+        }
+        case "IfStatement": case "ConditionalExpression": case "WhileStatement": return parent.test === value;
+        case "UnaryExpression": return parent.operator === "!";
+        case "LogicalExpression": return parent.operator === "&&" && parent.left === value;
+        default: return false;
+    }
+};
+
+const isFunctionBody = (node: Node): node is Node & { readonly type: "ArrowFunctionExpression" | "FunctionExpression" } =>
+    node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression";
+
+const mentions = (node: Node, name: string): boolean =>
+    (node.type === "Identifier" && node.name === name) || children(node).some(child => mentions(child, name));
+
+/** The plain names of a declaration's lookups, or null when `lookup` isn't an object literal of them. */
+const lookupNames = (declaration: ObjectExpression): readonly string[] | null => {
+    const lookup = declaration.properties.find(property =>
+        property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === "lookup");
+    if (lookup === undefined) return [];
+    if (lookup.type !== "Property" || lookup.value.type !== "ObjectExpression") return null;
+    const names = lookup.value.properties.map(property =>
+        property.type === "Property" && !property.computed && property.key.type === "Identifier" ? property.key.name : null);
+    return names.every(name => name !== null) ? names.filter(name => name !== null) : null;
+};
+
+/** The names of a declaration's lookups through an index: those declared as an object literal with `index`. */
+const indexLookupNames = (declaration: ObjectExpression): ReadonlySet<string> => {
+    const lookup = declaration.properties.find(property =>
+        property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === "lookup");
+    if (lookup?.type !== "Property" || lookup.value.type !== "ObjectExpression") return new Set();
+    return new Set(lookup.value.properties.flatMap(property =>
+        property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.value.type === "ObjectExpression"
+            && property.value.properties.some(field => field.type === "Property" && !field.computed && field.key.type === "Identifier" && field.key.name === "index")
+            ? [property.key.name] : []));
+};
+
+type Group = "resources" | "lookup" | "reduce";
+
+const isGroup = (name: string): name is Group => name === "resources" || name === "lookup" || name === "reduce";
+
+/**
+ * What a main-thread body reads, writes and contributes to through its row and context, for the parts where every use
+ * shows in its source. `row` and `context` are the indexes of those parameters, or -1 for none. The row and the
+ * context's `resources`, `lookup` and `reduce` are indexed only by module-scope keys the body doesn't shadow, or
+ * destructured by them, and never passed on, aliased or spread. A lookup's results are followed where each is indexed
+ * by such keys or tested, directly or through a `const` declared once; a lookup through an index's lists where they're
+ * read for `length` and `changed`, and their rows from `at` as a lookup's results are.
+ */
+export const usedBy = (declaration: ObjectExpression, body: Node, module: ModuleScope, positions: { readonly row: number; readonly context: number }): Used => {
+    if (!isFunctionBody(body)) return unknown;
+    if (body.type === "FunctionExpression" && mentions(body.body, "arguments")) return unknown;
+    const counts = new Map<string, number>();
+    declaredIn(body.body, name => counts.set(name, (counts.get(name) ?? 0) + 1));
+    const parameters = new Set(body.params.flatMap(parameter => patternNames(parameter)));
+    const isKey = (name: string): boolean => module.has(name) && !counts.has(name) && !parameters.has(name);
+    const lookups = lookupNames(declaration);
+    const indexed = indexLookupNames(declaration);
+
+    const query = { read: new Set<string>(), write: new Set<string>() };
+    const resources = { read: new Set<string>(), write: new Set<string>(), reduce: new Set<string>() };
+    const lookupReads = new Map<string, Set<string> | null>((lookups ?? []).map(name => [name, new Set<string>()]));
+    let queryKnown = true;
+    let resourcesKnown = true;
+    let lookupsKnown = lookups !== null;
+    const unknownLookup = (lookup: string): void => { lookupReads.set(lookup, null); };
+    const unknownGroup = (group: Group): void => {
+        if (group === "lookup") lookupsKnown = false;
+        else resourcesKnown = false;
+    };
+
+    /** Names bound to a context group, to a lookup function, or to a lookup's result. */
+    const groups = new Map<string, Group>();
+    const callers = new Map<string, string>();
+    const results = new Map<string, string>();
+    /** Names bound to a row an index lookup's list gave, by lookup. */
+    const rows = new Map<string, string>();
+    /** The initializers `collect` followed: the context or a group, destructured or bound to a name. */
+    const followed = new Set<Node>();
+
+    /** Reads `pattern`'s computed module-scope keys; false when it does anything else. Named properties go to `named`. */
+    const destructure = (pattern: Pattern, named: (property: string, value: Pattern) => boolean, keyed: (key: string) => void): boolean => {
+        if (pattern.type !== "ObjectPattern") return false;
+        for (const property of pattern.properties) {
+            if (property.type === "RestElement" || property.key.type !== "Identifier") return false;
+            if (!property.computed) {
+                if (!named(property.key.name, property.value)) return false;
+            }
+            else if (isKey(property.key.name)) keyed(property.key.name);
+            else return false;
+        }
+        return true;
+    };
+    const rowNamed = (property: string): boolean => property === "entity";
+    const lookupNamed = (property: string, value: Pattern): boolean => {
+        if (lookups === null || !lookups.includes(property)) return false;
+        if (value.type === "Identifier" && counts.get(value.name) === (parameters.has(value.name) ? undefined : 1)) callers.set(value.name, property);
+        else unknownLookup(property);
+        return true;
+    };
+    /** Destructures a group: lookups by name, resources by key as reads, and reductions not at all. */
+    const destructureGroup = (group: Group, pattern: Pattern): void => {
+        if (group === "lookup") {
+            if (!destructure(pattern, lookupNamed, () => { lookupsKnown = false; })) lookupsKnown = false;
+        }
+        else if (group === "resources") {
+            if (!destructure(pattern, () => false, key => resources.read.add(key))) resourcesKnown = false;
+        }
+        else resourcesKnown = false;
+    };
+    /** Binds the context's groups from a destructuring of it; `declaredOnce` says whether a bound name is safe to follow. */
+    const contextNamed = (declaredOnce: (name: string) => boolean) => (property: string, value: Pattern): boolean => {
+        if (!isGroup(property)) return true;
+        if (value.type === "Identifier" && declaredOnce(value.name)) groups.set(value.name, property);
+        else if (value.type === "ObjectPattern") destructureGroup(property, value);
+        else unknownGroup(property);
+        return true;
+    };
+    const unknownContext = (): void => {
+        resourcesKnown = false;
+        lookupsKnown = false;
+    };
+
+    const row = positions.row < 0 ? undefined : body.params[positions.row];
+    const context = positions.context < 0 ? undefined : body.params[positions.context];
+    const rowName = row?.type === "Identifier" && !counts.has(row.name) ? row.name : null;
+    const contextName = context?.type === "Identifier" && !counts.has(context.name) ? context.name : null;
+    if (row !== undefined && rowName === null && !destructure(row, rowNamed, key => query.read.add(key))) queryKnown = false;
+    if (context !== undefined && contextName === null && !destructure(context, contextNamed(name => !counts.has(name)), () => unknownContext())) unknownContext();
+
+    /** A lookup's row `value`, a child of `ancestors[at]`: indexed by a key, read for `entity`, bound to a `const`, or tested. */
+    const rowOf = (lookup: string, value: Node, ancestors: readonly Node[], at: number): void => {
+        const parent = ancestors[at];
+        if (parent?.type === "MemberExpression" && parent.object === value) {
+            if (parent.computed && parent.property.type === "Identifier" && isKey(parent.property.name)) lookupReads.get(lookup)?.add(parent.property.name);
+            else if (!(indexed.has(lookup) && !parent.computed && parent.property.type === "Identifier" && parent.property.name === "entity")) unknownLookup(lookup);
+        }
+        else if (parent?.type === "VariableDeclarator" && parent.init === value && parent.id.type === "Identifier"
+            && (results.get(parent.id.name) === lookup || rows.get(parent.id.name) === lookup)) return;
+        else if (!isTested(value, parent)) unknownLookup(lookup);
+    };
+    /**
+     * A lookup's result `value`, a child of `ancestors[at]`: a row as `rowOf` takes it, or an index lookup's list, read
+     * for `length` and `changed`, its rows from `at` taken as rows.
+     */
+    const result = (lookup: string, value: Node, ancestors: readonly Node[], at: number): void => {
+        const parent = ancestors[at];
+        if (indexed.has(lookup) && parent?.type === "MemberExpression" && parent.object === value && !parent.computed && parent.property.type === "Identifier") {
+            const { name } = parent.property;
+            if (name === "length" || name === "changed") return;
+            const call = ancestors[at - 1];
+            if (name === "at" && call?.type === "CallExpression" && call.callee === parent) return rowOf(lookup, call, ancestors, at - 2);
+        }
+        rowOf(lookup, value, ancestors, at);
+    };
+    /** A reference to a lookup's function, `callee`, a child of `ancestors[at]`. */
+    const called = (lookup: string, callee: Node, ancestors: readonly Node[], at: number): void => {
+        const parent = ancestors[at];
+        if (parent?.type === "CallExpression" && parent.callee === callee) result(lookup, parent, ancestors, at - 1);
+        else unknownLookup(lookup);
+    };
+
+    /** The group `node` is: a name bound to one, or `context.group`. */
+    const groupAt = (node: Node): Group | undefined => {
+        if (node.type === "Identifier") return groups.get(node.name);
+        if (node.type === "MemberExpression" && !node.computed && node.object.type === "Identifier" && node.object.name === contextName
+            && node.property.type === "Identifier" && isGroup(node.property.name)) return node.property.name;
+        return undefined;
+    };
+    /** The lookup a call calls, when it's a lookup's function by name or through its group. */
+    const calledLookup = (call: Node): string | undefined => {
+        if (call.type !== "CallExpression") return undefined;
+        const { callee } = call;
+        if (callee.type === "Identifier") return callers.get(callee.name);
+        if (callee.type === "MemberExpression" && !callee.computed && groupAt(callee.object) === "lookup"
+            && callee.property.type === "Identifier" && lookups?.includes(callee.property.name)) return callee.property.name;
+        return undefined;
+    };
+    /** The index lookup whose list's `at` a call calls: on a name bound to the list, or on the lookup's call itself. */
+    const rowCall = (call: Node): string | undefined => {
+        if (call.type !== "CallExpression" || call.callee.type !== "MemberExpression" || call.callee.computed
+            || call.callee.property.type !== "Identifier" || call.callee.property.name !== "at") return undefined;
+        const list = call.callee.object;
+        const lookup = list.type === "Identifier" ? results.get(list.name) : calledLookup(list);
+        return lookup !== undefined && indexed.has(lookup) ? lookup : undefined;
+    };
+    /** Finds groups and lookups bound by `const` declarations declared once, and `const`s holding a lookup's result, before any reference is classified. */
+    const collect = (node: Node, kind: string | undefined): void => {
+        if (node.type === "VariableDeclarator" && kind === "const" && node.init) {
+            const once = (name: string): boolean => counts.get(name) === 1;
+            const group = groupAt(node.init);
+            if (node.id.type === "Identifier" && once(node.id.name)) {
+                const lookup = calledLookup(node.init);
+                if (lookup !== undefined) results.set(node.id.name, lookup);
+                const listed = rowCall(node.init);
+                if (listed !== undefined) rows.set(node.id.name, listed);
+                if (group !== undefined) {
+                    groups.set(node.id.name, group);
+                    followed.add(node.init);
+                }
+            }
+            else if (node.init.type === "Identifier" && node.init.name === contextName) {
+                if (destructure(node.id, contextNamed(once), () => unknownContext())) followed.add(node.init);
+            }
+            else if (group !== undefined) {
+                destructureGroup(group, node.id);
+                followed.add(node.init);
+            }
+        }
+        for (const child of children(node)) collect(child, node.type === "VariableDeclaration" ? node.kind : kind);
+    };
+    collect(body.body, undefined);
+
+    /** A use of group `group` at `node`, a child of `ancestors[at]`. */
+    const useGroup = (group: Group, node: Node, ancestors: readonly Node[], at: number): void => {
+        if (followed.has(node)) return;
+        const parent = ancestors[at];
+        const grandparent = ancestors[at - 1];
+        if (parent?.type !== "MemberExpression" || parent.object !== node) return unknownGroup(group);
+        const { property } = parent;
+        if (group === "lookup") {
+            if (!parent.computed && property.type === "Identifier" && lookups?.includes(property.name)) called(property.name, parent, ancestors, at - 1);
+            else lookupsKnown = false;
+            return;
+        }
+        if (!parent.computed || property.type !== "Identifier" || !isKey(property.name)) return unknownGroup(group);
+        if (group === "reduce") {
+            if (grandparent?.type === "CallExpression" && grandparent.callee === parent) resources.reduce.add(property.name);
+            else resourcesKnown = false;
+            return;
+        }
+        const use = useOf(parent, grandparent);
+        if (use === null) return unknownGroup(group);
+        if (use.read) resources.read.add(property.name);
+        if (use.write) resources.write.add(property.name);
+    };
+
+    /** Classifies a reference; `ancestors` ends with its parent. */
+    const reference = (node: Node & { readonly type: "Identifier" }, ancestors: readonly Node[]): void => {
+        const { name } = node;
+        const parent = ancestors.at(-1);
+        const grandparent = ancestors.at(-2);
+        if (name === rowName) {
+            if (parent?.type === "MemberExpression" && parent.object === node) {
+                const { property } = parent;
+                if (!parent.computed) {
+                    if (property.type !== "Identifier" || !rowNamed(property.name)) queryKnown = false;
+                    return;
+                }
+                const use = property.type === "Identifier" && isKey(property.name) ? useOf(parent, grandparent) : null;
+                if (use === null || property.type !== "Identifier") queryKnown = false;
+                else {
+                    if (use.read) query.read.add(property.name);
+                    if (use.write) query.write.add(property.name);
+                }
+            }
+            else if (!(parent?.type === "VariableDeclarator" && parent.init === node && destructure(parent.id, rowNamed, key => query.read.add(key)))) queryKnown = false;
+        }
+        else if (name === contextName) {
+            if (parent?.type === "MemberExpression" && parent.object === node && !parent.computed && parent.property.type === "Identifier") {
+                const property = parent.property.name;
+                if (isGroup(property)) useGroup(property, parent, ancestors, ancestors.length - 2);
+                return;
+            }
+            if (!followed.has(node)) unknownContext();
+        }
+        else {
+            const at = ancestors.length - 1;
+            const group = groups.get(name);
+            if (group !== undefined) return useGroup(group, node, ancestors, at);
+            const caller = callers.get(name);
+            if (caller !== undefined) return called(caller, node, ancestors, at);
+            const lookup = results.get(name);
+            if (lookup !== undefined) return result(lookup, node, ancestors, at);
+            const row = rows.get(name);
+            if (row !== undefined) rowOf(row, node, ancestors, at);
+        }
+    };
+
+    const ancestors: Node[] = [];
+    /** A declaration's target pattern only binds names, so only its initializer holds references. */
+    const visit = (node: Node): void => {
+        if (node.type === "Identifier" && !isName(node, ancestors.at(-1))) reference(node, ancestors);
+        ancestors.push(node);
+        for (const child of node.type === "VariableDeclarator" ? (node.init === null || node.init === undefined ? [] : [node.init]) : children(node)) visit(child);
+        ancestors.pop();
+    };
+    visit(body.body);
+    return {
+        query: queryKnown ? query : null,
+        resources: resourcesKnown ? resources : null,
+        lookups: lookupsKnown ? lookupReads : null,
+    };
+};

package/src/implementation/compiler/booleans.ts

@@ -0,0 +1,38 @@
+import type { Expression, Statement } from './ir.js';
+import { references } from './ir.js';
+import type { Unit } from './unit.js';
+
+/**
+ * Column reads print as plain `c{k}[i]`, since a 0/1 number behaves like a boolean in most positions. Where a
+ * boolean's identity is observable (`===`, `!==`, command values) reads convert, along with every local whose
+ * value flows there.
+ */
+const observeLocals = (unit: Unit, expression: Expression): void => {
+    references(expression, node => {
+        if (node.kind === "local" && !unit.observed.has(node.local)) {
+            unit.observed.add(node.local);
+            for (const source of unit.assignments.get(node.local) ?? []) observeLocals(unit, source);
+        }
+        return false;
+    });
+};
+
+/** Marks a value for an observable position. */
+export const observe = (unit: Unit, value: Expression): Expression => {
+    observeLocals(unit, value);
+    return { kind: "observe", value };
+};
+
+/** Records an assignment, so observing the local later also observes its sources. */
+export const record = (unit: Unit, local: number, value: Expression): void => {
+    const assigned = unit.assignments.get(local) ?? [];
+    assigned.push(value);
+    unit.assignments.set(local, assigned);
+    if (unit.observed.has(local)) observeLocals(unit, value);
+};
+
+/** `local = value`, recorded. */
+export const set = (unit: Unit, local: number, value: Expression, declare: "const" | "let" | undefined): Statement => {
+    record(unit, local, value);
+    return { kind: "set", local, value, declare };
+};