@geastack/compiler 1.0.15

package/dist/semantics/normalize/producers/tuple-spread.js

@@ -0,0 +1,279 @@
+import ts from 'typescript';
+import { semanticResultId } from '../../../identity/ids.js';
+import { normalCompletion, pureEffects } from '../../model/operands.js';
+import { declaredClosedTupleRestElementsOf } from '../parameter-slot.js';
+import { resolveExpressionOperand } from './boundary.js';
+import { mintOperationId, mintResult, operand } from './mint.js';
+import { resultEdge } from './shared.js';
+/**
+ * The per-position types of a tuple whose arity is closed, or `null` for
+ * anything else.
+ *
+ * `optional`/`rest`/`variadic` elements are each a reason the arity is NOT
+ * settled -- `[number, ...string[]]` has no compile-time length, and
+ * `[number, string?]` has two possible ones -- so a tuple carrying any of them
+ * is not admitted here and falls through to whatever its caller's general path
+ * is. This is the same closed-arity requirement `lowerTupleLiteral`'s own
+ * `layout.length !== operands.length` check enforces one layer down, asked
+ * before the operands are built rather than after.
+ */
+export const closedTupleElementTypesOf = (context, type) => {
+    const shape = context.table.get(type).shape;
+    if (shape.kind !== 'tuple')
+        return null;
+    if (shape.elements.some((element) => element.optional || element.rest || element.variadic))
+        return null;
+    return shape.elements.map((element) => element.type);
+};
+/**
+ * An OPEN-ENDED tuple a spread can still settle positionally: `k` required
+ * positions followed by exactly one `rest` element and nothing after it --
+ * `[DiagnosticMessage, ...DiagnosticArguments]`. The fixed positions expand
+ * to `[[Get]]`s like a closed tuple's (`mintPositionalSpreadReads`), and the
+ * tail is a range copy from `fixed.length` into the callee's rest array,
+ * which is exactly what the language's own iteration would hand it. An
+ * optional position before the rest, or a variadic position, has no such
+ * split and stays `null`.
+ */
+export const openTupleSpreadShapeOf = (context, type) => {
+    const shape = context.table.get(type).shape;
+    if (shape.kind !== 'tuple')
+        return null;
+    const rest = shape.elements.findIndex((element) => element.rest);
+    if (rest < 0 || rest !== shape.elements.length - 1)
+        return null;
+    const fixed = shape.elements.slice(0, rest);
+    if (fixed.some((element) => element.optional || element.rest || element.variadic))
+        return null;
+    const tail = shape.elements[rest];
+    if (!tail || tail.variadic)
+        return null;
+    return { fixed: fixed.map((element) => element.type), tail: tail.type };
+};
+/** Whether `...expression`'s own source is a closed tuple, asked without minting anything. */
+export const isClosedTupleSpread = (context, expression) => closedTupleElementTypesOf(context, context.types.typeAt(expression)) !== null;
+/**
+ * The arity a REST PARAMETER spread expands to when the parameter's own
+ * declared type is a CLOSED tuple, or `null` for anything else.
+ *
+ * `/** @param {[number, number, number, number, number]} args *\/ function
+ * texStorage2D( ...args ) { gl.texStorage2D( ...args ) }` -- three's
+ * `WebGLState.js` as the native-webgl-angle plugin rewrites its
+ * `...arguments` forwarders. The parameter's CELL is typed by
+ * `structural.ts`'s `rest-parameter-array-element` form from call-site
+ * evidence, an array of the joined argument types, so `isClosedTupleSpread`
+ * above never sees a tuple and the spread fell through to the range-copy
+ * refusal ("can only be range-copied into a rest parameter") against a host
+ * function with five named formals. The cell's type is right -- the rest slot
+ * materializes an array -- but the DECLARATION states its length: every
+ * position required, no optional, rest or variadic element, and the checker
+ * refuses any call site that passes a different count. That is exactly the
+ * fact a closed tuple LOCAL supplies, asked of the declaration instead of the
+ * cell; the reads it admits are ordinary constant-index `[[Get]]`s off the
+ * array the cell holds (`declaredTupleRestSpreadReads`).
+ *
+ * Only an ARRAY-shaped cell qualifies: a parameter this compiler settled to
+ * anything else has a different carrier, and a constant-index read against it
+ * would be a claim this producer cannot check.
+ */
+const declaredTupleRestElementsOf = (context, expression) => {
+    if (!ts.isIdentifier(expression))
+        return null;
+    const symbol = context.checker.getSymbolAtLocation(expression);
+    const declaration = symbol ? context.identities.declarationOfSymbol(symbol) : null;
+    if (!declaration || !ts.isParameter(declaration))
+        return null;
+    const elements = declaredClosedTupleRestElementsOf(context.checker, declaration);
+    if (elements === null)
+        return null;
+    return context.table.get(context.types.typeAt(expression)).shape.kind === 'array' ? elements : null;
+};
+export const declaredTupleRestArityOf = (context, expression) => declaredTupleRestElementsOf(context, expression)?.length ?? null;
+/**
+ * The positional reads a declared-tuple rest parameter spread expands to
+ * (`declaredTupleRestArityOf`), each typed as the DECLARED tuple's own
+ * position -- not as the array cell's element. The cell holds the join of
+ * every position (`[string, number, number]` is an array of `string | number`),
+ * and a read typed by that join handed `describe( name, x, y )` a
+ * `string | number` for `x`, which made `x * y` a dynamic multiplication with
+ * no C++ spelling. The declaration is what fixes the value at each position,
+ * and a closed tuple LOCAL's reads are typed the same way off the same
+ * tagged-union carrier.
+ */
+export const declaredTupleRestSpreadReads = (context, candidate, expression) => {
+    const elements = declaredTupleRestElementsOf(context, expression);
+    if (elements === null)
+        return null;
+    const receiver = spreadReceiverOf(context, expression);
+    if (!receiver)
+        return null;
+    return mintPositionalSpreadReads(context, candidate, receiver, elements.map((element) => context.types.typeOf(element)));
+};
+/**
+ * The receiver both expansions below read positions off: `resolveExpressionOperand`'s
+ * own VALUE identity (which family published this expression's result --
+ * correctly resolved past an `as`/`satisfies`/`<T>` wrapper, since none of
+ * those own a runtime operation of their own), paired with the TYPE asked
+ * directly at `expression`, exactly as `isClosedTupleSpread`/
+ * `admitsMaxArityTupleSpread` (`spread-arguments.ts`) already ask it -- not
+ * `resolveExpressionOperand`'s own bundled `.type`, which asks past the same
+ * wrapper for the type too and disagrees with both admission gates the
+ * moment one is present. `args as Parameters<NewResponse>` (hono's
+ * `Context.newResponse`) is the concrete case: the CAST states a real closed
+ * shape the underlying `args` binding does not have on its own (an ordinary,
+ * open-arity array, once the rest-parameter census has done its job) -- an
+ * admission gate that reads the cast agrees to expand it, and an expansion
+ * that then reads past the cast right back to the array finds no tuple
+ * there and refuses, silently, for an admission that already said yes.
+ * `local-bindings.ts`'s `knownOrResolve` draws this identical line for a
+ * cast ("the checker's own answer there is taken as-is and never read
+ * past"); this is that same rule, asked with the SAME node the two
+ * admission gates already use, so the three can only ever agree.
+ */
+export const spreadReceiverOf = (context, expression) => {
+    const resolved = resolveExpressionOperand(context, expression);
+    return resolved ? { source: resolved.source, type: context.types.typeAt(expression) } : null;
+};
+/**
+ * The `[[Get]]`s a tuple's positions expand to, shared by every admission
+ * shape below -- each differs only in WHICH element types it is sound to ask
+ * for, never in how a position, once admitted, is read.
+ *
+ * The receiver is cited ONCE and read N times, which is what the language
+ * does: `f(...sideEffect())` evaluates `sideEffect()` a single time and then
+ * indexes the result. Citing the expression per position instead would name
+ * the same published result N times, which is harmless, but building the
+ * operand once makes that single evaluation explicit rather than incidental.
+ */
+export const mintPositionalSpreadReads = (context, candidate, receiver, elements, firstIndex = 0) => {
+    // A tuple position's key is a String, the same way every other static key in
+    // this compiler is: `properties.ts`'s `keyOf` interns exactly this type for
+    // `o[0]`, on the grounds that ToPropertyKey turns a numeric index into a
+    // String and two spellings of one key must not look like two keys.
+    const keyType = context.table.intern({ kind: 'primitive', primitive: 'string' });
+    const operations = [];
+    const edges = [];
+    const positions = [];
+    for (const [offset, elementType] of elements.entries()) {
+        const index = firstIndex + offset;
+        const id = mintOperationId(context.ordinals, candidate.id, 'property');
+        operations.push({
+            id,
+            family: 'property',
+            internalMethod: 'get',
+            strict: true,
+            keyIsComputed: false,
+            // A read consults whatever descriptor is installed; it states none.
+            descriptor: null,
+            caller: candidate.caller,
+            operands: [
+                operand('receiver', 0, receiver.source, receiver.type),
+                operand('key', 0, { kind: 'constant', text: String(index), literal: 'string' }, keyType)
+            ],
+            results: [mintResult(id, 'value', elementType)],
+            // A tuple type excludes `null`/`undefined` by construction, so the read
+            // cannot be the nullish-receiver TypeError an ordinary `[[Get]]` guards
+            // against, and a tuple position is native storage rather than an
+            // accessor, so nothing user-written runs here either.
+            completion: normalCompletion,
+            effects: { ...pureEffects, readsMutableState: true },
+            evaluationOrdinal: candidate.evaluationOrdinal
+        });
+        const edge = resultEdge(receiver.source, id, 'receiver', 0);
+        if (edge)
+            edges.push(edge);
+        positions.push({ source: { kind: 'result', result: semanticResultId(id, 'value') }, type: elementType });
+    }
+    return { operations, edges, positions };
+};
+/**
+ * The positional reads `...expression` expands to, or `null` when the source
+ * is not a closed tuple or when no operation publishes its value.
+ */
+export const tupleSpreadReads = (context, candidate, expression) => {
+    const receiver = spreadReceiverOf(context, expression);
+    if (!receiver)
+        return null;
+    const elements = closedTupleElementTypesOf(context, receiver.type);
+    if (!elements)
+        return null;
+    return mintPositionalSpreadReads(context, candidate, receiver, elements);
+};
+/**
+ * The per-position types of a tuple whose only "unsettled" elements are a
+ * trailing OPTIONAL run, or `null` for anything else -- including a `rest`/
+ * `variadic` element, which still has no settled arity at all.
+ *
+ * `closedTupleElementTypesOf` above is right to refuse an optional-tailed
+ * tuple for its own callers: a spread's DESTINATION cares about the source's
+ * true runtime LENGTH (`[...t]` with `t.length === 1` must allocate a
+ * one-element array, not `[t[0], undefined]`), and expanding to the tuple's
+ * full declared arity would silently manufacture a longer collection than the
+ * source ever had. `maxArityTupleSpreadReads` is the one context where a
+ * fixed-at-declared-arity expansion is still exact rather than approximate --
+ * see it for why.
+ *
+ * The type widening happens HERE, at the element, rather than being layered
+ * onto every read: `t[i]` for an absent optional position `i` already reads
+ * `undefined` by ordinary out-of-bounds `[[Get]]`, so the element's own type
+ * has to say so, exactly the way `parameter-slot.ts`'s `parameterSlotTypeOf`
+ * widens an optional PARAMETER's slot with `undefined` for the same reason.
+ * The union is flattened rather than nested -- a member that is already a
+ * union has its own members spliced in -- because only a flat union derives
+ * to this compiler's three-armed optional carrier (`parameter-slot.ts`'s own
+ * comment states why a nested one would not).
+ */
+export const maxArityTupleElementTypesOf = (context, type) => {
+    const shape = context.table.get(type).shape;
+    if (shape.kind !== 'tuple')
+        return null;
+    if (shape.elements.some((element) => element.rest || element.variadic))
+        return null;
+    return shape.elements.map((element) => (element.optional ? widenedWithUndefined(context, element.type) : element.type));
+};
+const widenedWithUndefined = (context, type) => {
+    const undefinedType = context.table.intern({ kind: 'primitive', primitive: 'undefined' });
+    if (type === undefinedType)
+        return type;
+    const shape = context.table.get(type).shape;
+    if (shape.kind === 'union') {
+        return shape.members.includes(undefinedType)
+            ? type
+            : context.table.intern({ kind: 'union', members: [...shape.members, undefinedType] });
+    }
+    return context.table.intern({ kind: 'union', members: [type, undefinedType] });
+};
+/**
+ * `...expression`'s positional reads, over an OPTIONAL-tailed tuple, for the
+ * one context where that is still sound: a CALL ARGUMENT, where an omitted
+ * argument and an explicitly `undefined` one read identically at the callee.
+ *
+ * Ordinary JS parameter binding makes that true unconditionally: an omitted
+ * argument binds `undefined` (ECMA-262 `FunctionDeclarationInstantiation` /
+ * `IteratorBindingInitialization` over a shorter argument list), and a
+ * defaulted parameter's initializer triggers on `undefined` however it
+ * arrived -- there is no third state a NAMED, non-rest parameter can
+ * observe. So `f(...t)` with `t: [A, B?]` reads IDENTICALLY at the callee
+ * whether `t`'s true runtime length is 1 or 2, PROVIDED:
+ *
+ *  - the callee has no REST formal anywhere the tuple's positions could
+ *    land -- a rest parameter's own `.length` DOES observe the caller's true
+ *    argument count, which this fixed-at-declared-arity expansion cannot
+ *    track;
+ *  - nothing else follows this spread in the argument list -- a written
+ *    argument after it would land at a position that shifts with the
+ *    tuple's TRUE length, which only the real spread ever knows.
+ *
+ * Both conditions are the CALLER's to check (`spread-arguments.ts`'s
+ * `restFrom` and its own last-argument scan) -- this function only expands
+ * the positions, exactly as `tupleSpreadReads` does for a closed tuple.
+ */
+export const maxArityTupleSpreadReads = (context, candidate, expression) => {
+    const receiver = spreadReceiverOf(context, expression);
+    if (!receiver)
+        return null;
+    const elements = maxArityTupleElementTypesOf(context, receiver.type);
+    if (!elements)
+        return null;
+    return mintPositionalSpreadReads(context, candidate, receiver, elements);
+};

package/dist/semantics/normalize/property-key-domain.d.ts

@@ -0,0 +1,36 @@
+import ts from 'typescript';
+import type { ValueFlowIndex } from './flow/model.js';
+/** An over-approximation of ToPropertyKey's string results; unknown never excludes a name. */
+export type PropertyKeyDomain = {
+    readonly kind: 'unknown';
+} | {
+    readonly kind: 'literal';
+    readonly value: string;
+} | {
+    readonly kind: 'number';
+} | {
+    readonly kind: 'union';
+    readonly members: readonly PropertyKeyDomain[];
+} | {
+    readonly kind: 'concat';
+    readonly left: PropertyKeyDomain;
+    readonly right: PropertyKeyDomain;
+};
+export declare const createPropertyKeyDomains: (checker: ts.TypeChecker, flow: ValueFlowIndex, reachable: (node: ts.Node) => boolean, parameterTypeAt?: (parameter: ts.Expression) => ts.Type) => {
+    readonly of: (expression: ts.Expression) => PropertyKeyDomain;
+    readonly mayName: (domain: PropertyKeyDomain, name: string) => boolean;
+};
+/**
+ * Whether ANY canonical numeric string lies in `domain` -- `mayName` asked of
+ * every such name at once. Each starts with `-`, a digit, `I` (Infinity) or `N`
+ * (NaN) and ends with a digit, `y` or `N`, and every spelled piece between
+ * must be a substring of such a name; an unknown domain may name anything.
+ *
+ * The interior rule is what three's `WebGLUniformsGroups.js` needs: its cache
+ * is keyed `index + '_' + indexArray`, two numbers around an underscore. The
+ * edges are unspelled, so the edge rule alone kept this write as a possible
+ * numeric key on the WebGL context, refused the context's numeric-absence
+ * proof, and left `WebGLUtils.convert`'s `gl[ p ]` fallback -- and every
+ * `glFormat`/`glType` downstream of it -- dynamic.
+ */
+export declare const domainMayNameNumeric: (domain: PropertyKeyDomain) => boolean;

package/dist/semantics/normalize/property-key-domain.js

@@ -0,0 +1,150 @@
+import ts from 'typescript';
+import { unwrapErasedExpression } from './producers/erasure.js';
+import { isCanonicalNumericKey } from './host-mutation-keys.js';
+const unknown = { kind: 'unknown' };
+const numeric = { kind: 'number' };
+const literal = (value) => ({ kind: 'literal', value });
+const concat = (left, right) => ({ kind: 'concat', left, right });
+const isStringDomain = (domain) => domain.kind === 'literal' || domain.kind === 'concat' || (domain.kind === 'union' && domain.members.every(isStringDomain));
+export const createPropertyKeyDomains = (checker, flow, reachable, parameterTypeAt = (parameter) => checker.getTypeAtLocation(parameter)) => {
+    const domains = new Map();
+    const typeDomain = (type) => {
+        if (type.isUnion())
+            return { kind: 'union', members: type.types.map(typeDomain) };
+        if (type.isStringLiteral())
+            return literal(type.value);
+        if ((type.flags & ts.TypeFlags.NumberLike) !== 0 && (type.flags & ~ts.TypeFlags.NumberLike) === 0)
+            return numeric;
+        return unknown;
+    };
+    const domainOf = (expression) => {
+        const current = unwrapErasedExpression(expression);
+        const known = domains.get(current);
+        if (known)
+            return known;
+        // Cyclic aliases provide no restriction. This placeholder also bounds
+        // recursive initializers without mistaking an empty cycle for evidence.
+        domains.set(current, unknown);
+        let result = unknown;
+        if (ts.isStringLiteralLike(current))
+            result = literal(current.text);
+        else if (ts.isNumericLiteral(current))
+            result = numeric;
+        else if (ts.isTemplateExpression(current)) {
+            result = literal(current.head.text);
+            for (const span of current.templateSpans)
+                result = concat(concat(result, domainOf(span.expression)), literal(span.literal.text));
+        }
+        else if (ts.isConditionalExpression(current)) {
+            result = { kind: 'union', members: [domainOf(current.whenTrue), domainOf(current.whenFalse)] };
+        }
+        else if (ts.isBinaryExpression(current) && current.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+            const left = domainOf(current.left);
+            const right = domainOf(current.right);
+            // A string assertion does not change numeric addition into concatenation.
+            if (isStringDomain(left) || isStringDomain(right))
+                result = concat(left, right);
+            else if (left.kind === 'number' && right.kind === 'number')
+                result = numeric;
+        }
+        else {
+            const declaration = ts.isIdentifier(current) ? flow.targetOf(current)?.declaration : null;
+            if (declaration && ts.isVariableDeclaration(declaration)) {
+                const writes = flow.writesToDeclaration(declaration).filter((write) => reachable(write.site) && write.slot === 'whole');
+                result =
+                    writes.length > 0
+                        ? { kind: 'union', members: writes.map((write) => (write.value === null ? unknown : domainOf(write.value))) }
+                        : unknown;
+            }
+            else if (ts.isIdentifier(current) && declaration && ts.isParameter(declaration)) {
+                result = typeDomain(parameterTypeAt(current));
+            }
+        }
+        domains.set(current, result);
+        return result;
+    };
+    const matches = new Map();
+    const mayName = (domain, name) => {
+        let names = matches.get(domain);
+        if (!names) {
+            names = new Map();
+            matches.set(domain, names);
+        }
+        const known = names.get(name);
+        if (known !== undefined)
+            return known;
+        let result;
+        switch (domain.kind) {
+            case 'unknown':
+                result = true;
+                break;
+            case 'literal':
+                result = domain.value === name;
+                break;
+            case 'number':
+                result = String(Number(name)) === name;
+                break;
+            case 'union':
+                result = domain.members.some((member) => mayName(member, name));
+                break;
+            case 'concat': {
+                result = false;
+                for (let split = 0; split <= name.length; split++) {
+                    if (mayName(domain.left, name.slice(0, split)) && mayName(domain.right, name.slice(split))) {
+                        result = true;
+                        break;
+                    }
+                }
+                break;
+            }
+        }
+        names.set(name, result);
+        return result;
+    };
+    return { of: domainOf, mayName };
+};
+const domainEdgeLiteral = (domain, side) => domain.kind === 'literal' ? domain.value : domain.kind === 'concat' ? domainEdgeLiteral(domain[side], side) : null;
+/**
+ * Every character a canonical numeric string can contain: the decimal and
+ * exponent forms (`-1.5e+21`), `Infinity`, `-Infinity` and `NaN`. A spelled
+ * fragment holding any other character cannot be a substring of one, wherever
+ * it sits in the concatenation.
+ */
+const CANONICAL_NUMERIC_ALPHABET = /^[-+.\deINafinty]*$/;
+const domainLiteralPieces = (domain) => domain.kind === 'literal'
+    ? [domain.value]
+    : domain.kind === 'concat'
+        ? [...domainLiteralPieces(domain.left), ...domainLiteralPieces(domain.right)]
+        : [];
+/**
+ * Whether ANY canonical numeric string lies in `domain` -- `mayName` asked of
+ * every such name at once. Each starts with `-`, a digit, `I` (Infinity) or `N`
+ * (NaN) and ends with a digit, `y` or `N`, and every spelled piece between
+ * must be a substring of such a name; an unknown domain may name anything.
+ *
+ * The interior rule is what three's `WebGLUniformsGroups.js` needs: its cache
+ * is keyed `index + '_' + indexArray`, two numbers around an underscore. The
+ * edges are unspelled, so the edge rule alone kept this write as a possible
+ * numeric key on the WebGL context, refused the context's numeric-absence
+ * proof, and left `WebGLUtils.convert`'s `gl[ p ]` fallback -- and every
+ * `glFormat`/`glType` downstream of it -- dynamic.
+ */
+export const domainMayNameNumeric = (domain) => {
+    switch (domain.kind) {
+        case 'literal':
+            return isCanonicalNumericKey(domain.value);
+        case 'union':
+            return domain.members.some(domainMayNameNumeric);
+        case 'concat': {
+            const lead = domainEdgeLiteral(domain, 'left');
+            const trail = domainEdgeLiteral(domain, 'right');
+            if (lead && !/^[-\dIN]/.test(lead))
+                return false;
+            if (trail && !/[\dyN]$/.test(trail))
+                return false;
+            return domainLiteralPieces(domain).every((piece) => CANONICAL_NUMERIC_ALPHABET.test(piece));
+        }
+        default:
+            return true;
+    }
+};

package/dist/semantics/normalize/reachability.d.ts

@@ -0,0 +1,189 @@
+import ts from 'typescript';
+/**
+ * What a program reaches from the files it was asked to compile.
+ *
+ * A project's file set is not its module graph. `include` names every file a
+ * *typechecker* should see; what an application does is what its entry points
+ * import, and nothing else runs. Compiling the first as though it were the
+ * second is how an app that imports `Display` and `mount` acquires the
+ * obligations of a camera it never opens: `runtime/host.ts` is one file, so
+ * the whole of it -- `Camera`'s four `Promise.resolve` calls, `imageHost`'s
+ * `GeaEmbeddedImage` boundary -- arrives alongside the two bindings the app
+ * actually asked for.
+ *
+ * This is the one place that difference is decided. Every census downstream
+ * walks the statements this hands it rather than the file it hands them for,
+ * so there is one answer to "is this code in the program" instead of four that
+ * can drift apart.
+ *
+ * Nothing here changes what anything *means*. The checker still sees the whole
+ * project, so every type resolves exactly as it did and every layout is still
+ * expanded from the checker's own answer -- a declaration this drops is
+ * dropped from the *census*, not from the type system. That is what makes the
+ * pruning safe to state at one seam: the stages after normalize cannot tell
+ * that it happened, because the program they are handed simply does not
+ * contain the code, and obligations, certification, lowering and emission all
+ * read that one graph.
+ *
+ * ## What it refuses to prune
+ *
+ * The rule is not "unreferenced code is dead". A module's top level *runs* on
+ * import, so a statement that performs an action -- a call, an assignment, an
+ * `if`, an `export default` expression, a bare expression statement -- stays
+ * whether or not anything reads what it produced. Exactly three declaration
+ * forms are ever dropped, each because its own evaluation is provably not an
+ * action:
+ *
+ * - A **function declaration**. Its evaluation is `InstantiateFunctionObject`:
+ *   a closure is created and bound. Nothing observable happens, and the body
+ *   does not run.
+ * - A **class declaration** with no decorators, no `extends` clause, no static
+ *   block, no static field initializer and no computed member name.
+ *   `ClassDefinitionEvaluation` for such a class evaluates nothing at all, and
+ *   this compiler lowers class evaluation to *no runtime step at all*
+ *   (`ir/lower.ts`, `case 'class-lifecycle'`): the struct and the construct
+ *   function it emits already are the layout the definition events record. A
+ *   static block or a static initializer is the opposite -- each is a real
+ *   region with a body -- so a class carrying one is kept; so is a class with
+ *   a heritage clause, whose one definition-time step (the heritage read) is
+ *   the event the projection takes the struct's base from (see
+ *   `classDefinitionIsInert`).
+ * - A **variable statement** whose every declarator binds a plain name and has
+ *   either no initializer or an initializer drawn from `initializerIsInert`'s
+ *   whitelist: literals, function/arrow/class expressions, and object/array
+ *   literals built from those. Anything that could call something -- a call, a
+ *   `new`, a property read (which can be a getter), a template substitution
+ *   (which can be a `toString`), a spread, an assignment, even a bare
+ *   identifier read (which can be a temporal-dead-zone throw) -- is outside the
+ *   whitelist, and the statement is kept.
+ *
+ * Everything else is kept unconditionally: imports, exports, `export default`,
+ * expression statements, control flow, enums, namespaces, and every type-only
+ * declaration. Type declarations cost nothing to keep -- `familyOf`
+ * (`census.ts`) assigns no family to an interface or a type alias, so they
+ * contribute no candidates either way -- and keeping them removes the whole
+ * question of whether a record layout was pruned out from under a live value.
+ *
+ * ## The second granularity: a class member
+ *
+ * A live class is live whole as a DEFINITION -- its layout, its fields, its
+ * constructor -- but a method body runs only when a dispatch names it, and a
+ * dispatch has to name it. `C.m` resolves to one declaration, so a static
+ * member is opened by symbol. An instance member cannot be: a structurally
+ * typed parameter, a base-class reference and an interface-typed call all land
+ * on a member the receiver's static type does not identify, and an override is
+ * reached through the base's name. So an instance member is opened by KEY --
+ * any spelling of its name in live code, on any receiver, opens every member
+ * that answers that name on every class.
+ *
+ * This is the same cut `ir/shake.ts` makes over the lowered IR, and its own
+ * header states the fact that makes the key comparison sound for this backend:
+ * a class method or accessor is addressable only through a key spelled at
+ * compile time, because `emit-properties.ts` refuses a dynamic key by name and
+ * the two dynamic paths that do exist address record fields and a box's
+ * expando, neither of which can answer a method key. What that pass could not
+ * do from the IR is stop a refusal inside a dead body from denying the whole
+ * program its certificate -- obligations are censused before lowering, so a
+ * method nothing calls still had to be representable. That is the reason this
+ * half of the cut lives here.
+ *
+ * A member reached through no spelling at all -- the gea plugin lowers
+ * `instance.render(root, depth)` into a call to the class's own `template`
+ * (`plugins/gea/render-bridge.ts`) -- is not something this walk can see, so
+ * the host states its own such names instead: see `hostReachedMemberKeys`.
+ *
+ * ## Fail-closed everywhere it cannot see
+ *
+ * - No entry file resolves: nothing is pruned at all (`wholeProgram`).
+ * - A reference resolves into a file this walk has not reached: that file is
+ *   *promoted* to reachable rather than the reference dropped. A missed import
+ *   edge, a global script file that nothing imports, a `declare global`
+ *   augmentation -- each resurrects its file the moment anything names
+ *   something in it.
+ * - A reference is followed for **every** identifier in live code, in type
+ *   position as well as value position, and through property names too. A
+ *   property name resolves to the member of the type it was read off, so a
+ *   structural read of a class member keeps that class. Over-marking costs
+ *   dead code left in; under-marking is the only direction that could be
+ *   wrong, so the walk is deliberately blunt.
+ * - Only an import or a re-export is *not* traversed for references, because
+ *   neither uses what it names: `export { mount } from './primitives'`
+ *   re-exports a binding without reading it, and traversing one would make
+ *   every barrel file mark its whole surface live -- which is precisely the
+ *   state being removed. An importer that really does use the name resolves
+ *   the alias chain to the same declaration and marks it here.
+ */
+export interface ProgramReachability {
+    /** The top-level statements of `file` this program reaches, in source order. */
+    readonly statementsOf: (file: ts.SourceFile) => readonly ts.Statement[];
+    /**
+     * Whether this node is an unused class member, or a constructor/initializer
+     * whose class is retained only for its instance layout.
+     *
+     * The second granularity this module answers at, and the only one below a
+     * statement. A class is opened whole because its DEFINITION is what a live
+     * reference reaches -- but a method's body is not part of that definition: it
+     * runs when a dispatch names it. So a method is exactly as prunable as a
+     * top-level function declaration, and for the same reason.
+     *
+     * A static is named by symbol (`C.m` resolves to one declaration) and an
+     * instance member by key (a dispatch's receiver does not say which class's
+     * member it lands on). See this module's header.
+     */
+    readonly memberIsPruned: (node: ts.Node) => boolean;
+    readonly classIsLayoutOnly: (node: ts.ClassDeclaration) => boolean;
+}
+/**
+ * Every statement of every file: the answer when nothing may be pruned.
+ *
+ * This is the fail-closed value, and it is what a compilation whose entry
+ * points could not be resolved gets. It is deliberately not the default of any
+ * parameter -- a census that silently walked the whole program because someone
+ * forgot to thread the reachability through would be the second authority this
+ * module exists to prevent.
+ */
+export declare const wholeProgram: ProgramReachability;
+/**
+ * `ts.forEachChild(file, visit)` restricted to what the program reaches.
+ *
+ * Every census in the parameter-binding family walks a file this way, and a
+ * walk that still visited a pruned statement counted references in code the
+ * program never runs: test262's propertyHelper ends with the inert, unreached
+ * `var verifyPrimordialProperty = verifyProperty`, and that one alias made
+ * the parameter census refuse `verifyProperty` as "escaping" -- so its `obj`
+ * never learned it is only ever called with `Math`, and every helper under it
+ * went dynamic. A declaration file has no statements the program evaluates,
+ * the same exclusion the walks made for themselves before.
+ */
+export declare const forEachReachableStatement: (reachable: ProgramReachability, file: ts.SourceFile, visit: (node: ts.Node) => void) => void;
+/**
+ * Whether `node` is code the program runs: inside a top-level statement this
+ * program reaches, and under no member it pruned -- the boundary
+ * `forEachReachableStatement` draws for a walk, asked of one node a walk did
+ * not produce. A module the checker loaded but the program never evaluates
+ * (three's `ColorSpaceNode.js`, pulled in beside the node materials) answers
+ * false everywhere.
+ */
+export declare const nodeIsReachable: (reachable: ProgramReachability, node: ts.Node) => boolean;
+export interface ReachabilityInput {
+    readonly checker: ts.TypeChecker;
+    /** The files this compiler is responsible for -- `CompiledProgram.sourceFiles`. */
+    readonly files: readonly ts.SourceFile[];
+    /** The files the caller named. Empty means the entry points are unknown, and nothing is pruned. */
+    readonly entries: readonly ts.SourceFile[];
+    /**
+     * Member names a HOST reaches without the program spelling them.
+     *
+     * The gea plugin lowers `instance.render(root, depth)` into a call to the
+     * class's own `template` member (`plugins/gea/render-bridge.ts`), which no
+     * TypeScript source names -- so nothing in this walk could ever see it
+     * spelled, and the member-key rule below would drop the one body the bridge
+     * calls. A plugin states its own such names (`PluginCapabilities`'
+     * `reachedMemberKeys`) rather than this file knowing any of them: which
+     * members a host reaches is the host's fact, and a name hard-coded here
+     * would be gea behaviour living in the generic compiler.
+     */
+    readonly hostReachedMemberKeys?: ReadonlySet<string>;
+}
+export declare const moduleEvaluationOrder: (input: ReachabilityInput) => readonly ts.SourceFile[];
+export declare const censusReachability: (input: ReachabilityInput) => ProgramReachability;