@geastack/compiler 1.0.15

package/dist/semantics/normalize/flow/native-collection-protocol.js

@@ -0,0 +1,252 @@
+import ts from 'typescript';
+import { outermostErasureOf, unwrapErasedExpression } from '../producers/erasure.js';
+import { deferredIntrinsicProtocolLedgerOf } from '../deferred-intrinsic-protocols.js';
+import { isModuleExportedDeclaration, isTypePositionReference, resolveFlowSymbolAlias } from './targets.js';
+/** One protocol is shared by every instance. A local map alone cannot prove
+ * its methods immutable: a sibling may expose that same prototype. */
+const buildNativeCollectionProtocolPlan = (checker, flow, publication, family, constructions, arrayAnchor) => {
+    const deferred = deferredIntrinsicProtocolLedgerOf(flow) !== null;
+    const original = unwrapErasedExpression;
+    const roots = new Set(arrayAnchor ? flow.arrayLiterals : []);
+    const exported = (declaration) => isModuleExportedDeclaration(checker, declaration, checker.getSymbolAtLocation(declaration.name) ?? null);
+    // Exposing the original constructor also exposes its prototype. A property
+    // assignment through it or an opaque consumer invalidates native get/set.
+    const constructorSymbols = new Set([...constructions].map((construction) => resolveFlowSymbolAlias(checker, checker.getSymbolAtLocation(original(construction.expression)))));
+    if (arrayAnchor)
+        constructorSymbols.add(resolveFlowSymbolAlias(checker, checker.resolveName('Array', arrayAnchor, ts.SymbolFlags.Value, false)));
+    for (const constructor of constructorSymbols) {
+        if (!constructor?.valueDeclaration?.getSourceFile().isDeclarationFile)
+            return null;
+        for (const reference of flow.referencesToSymbol(constructor)) {
+            const positioned = outermostErasureOf(reference);
+            const parent = positioned.parent;
+            if (isTypePositionReference(reference))
+                continue;
+            if ((ts.isNewExpression(parent) || (arrayAnchor && ts.isCallExpression(parent))) && parent.expression === positioned) {
+                roots.add(parent);
+                continue;
+            }
+            if (arrayAnchor && ts.isPropertyAccessExpression(parent) && parent.expression === positioned) {
+                const member = checker.getSymbolAtLocation(parent.name);
+                const declared = checker.getPropertyOfType(checker.getTypeOfSymbolAtLocation(constructor, arrayAnchor), parent.name.text);
+                const called = outermostErasureOf(parent).parent;
+                if (member &&
+                    declared &&
+                    member.declarations?.some((declaration) => declared.declarations?.includes(declaration)) &&
+                    ts.isCallExpression(called) &&
+                    outermostErasureOf(parent) === called.expression &&
+                    ['isArray', 'from', 'of'].includes(parent.name.text)) {
+                    if (parent.name.text !== 'isArray')
+                        roots.add(called);
+                    continue;
+                }
+            }
+            if (!deferred)
+                return null;
+        }
+    }
+    if (arrayAnchor) {
+        for (const site of flow.calls) {
+            const type = checker.getTypeAtLocation(site.call);
+            if (checker.isArrayType(type) || checker.isTupleType(type))
+                roots.add(site.call);
+        }
+    }
+    const global = checker.resolveName('globalThis', publication, ts.SymbolFlags.Value | ts.SymbolFlags.Namespace, false);
+    const globalSeen = new Set();
+    const globalUse = (reference) => {
+        if (globalSeen.has(reference))
+            return true;
+        globalSeen.add(reference);
+        const parent = reference.parent;
+        if (ts.isParenthesizedExpression(parent) || ts.isAsExpression(parent) || ts.isTypeAssertionExpression(parent))
+            return globalUse(parent);
+        if (ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {
+            if (exported(parent))
+                return false;
+            if (parent.name === reference)
+                return true;
+            return parent.initializer === reference && flow.referencesToDeclaration(parent).every(globalUse);
+        }
+        if (ts.isPropertyAccessExpression(parent) && parent.expression === reference) {
+            if (parent.name.text === family || parent.name.text === 'globalThis')
+                return false;
+            const type = checker.getTypeAtLocation(parent);
+            const primitive = (item) => item.isUnion()
+                ? item.types.every(primitive)
+                : (item.flags &
+                    (ts.TypeFlags.StringLike |
+                        ts.TypeFlags.NumberLike |
+                        ts.TypeFlags.BooleanLike |
+                        ts.TypeFlags.Null |
+                        ts.TypeFlags.Undefined)) !==
+                    0;
+            return primitive(type);
+        }
+        return ts.isTypeOfExpression(parent);
+    };
+    if (!deferred && global && !flow.referencesToSymbol(global).every(globalUse))
+        return null;
+    const anchor = arrayAnchor ?? constructions.values().next().value;
+    if (!anchor)
+        return null;
+    const nativeType = checker.getTypeAtLocation(anchor);
+    const members = new Set(checker.getPropertiesOfType(nativeType).flatMap((symbol) => symbol.declarations ?? []));
+    const terminalUse = (reference) => {
+        const positioned = outermostErasureOf(reference);
+        const parent = positioned.parent;
+        if (family === 'Array') {
+            if ((ts.isForOfStatement(parent) && parent.expression === positioned) ||
+                (ts.isSpreadElement(parent) && parent.expression === positioned))
+                return true;
+            if (ts.isElementAccessExpression(parent) && parent.expression === positioned) {
+                const key = checker.getTypeAtLocation(parent.argumentExpression);
+                if ((key.flags & ts.TypeFlags.NumberLike) === 0)
+                    return false;
+                const use = outermostErasureOf(parent).parent;
+                if (ts.isDeleteExpression(use) || (ts.isBinaryExpression(use) && use.left === outermostErasureOf(parent)))
+                    return true;
+                const value = checker.getTypeAtLocation(parent);
+                // Object-valued elements may contain this array itself; the shared
+                // value graph needs to follow those aliases before admitting a read.
+                return ((value.flags &
+                    (ts.TypeFlags.StringLike |
+                        ts.TypeFlags.NumberLike |
+                        ts.TypeFlags.BooleanLike |
+                        ts.TypeFlags.BigIntLike |
+                        ts.TypeFlags.ESSymbolLike |
+                        ts.TypeFlags.Null |
+                        ts.TypeFlags.Undefined)) !==
+                    0);
+            }
+        }
+        if (family === 'Map' &&
+            ((ts.isForOfStatement(parent) && parent.expression === positioned) ||
+                (ts.isSpreadElement(parent) && parent.expression === positioned)))
+            return true;
+        if (!ts.isPropertyAccessExpression(parent) || parent.expression !== positioned)
+            return null;
+        const symbol = checker.getSymbolAtLocation(parent.name);
+        if (!symbol?.declarations?.length || !symbol.declarations.every((declaration) => members.has(declaration)))
+            return false;
+        const key = parent.name.text;
+        if (key === 'size' || (family === 'Array' && key === 'length')) {
+            const positionedAccess = outermostErasureOf(parent);
+            const use = positionedAccess.parent;
+            return ((family === 'Map' || family === 'Array') &&
+                !ts.isDeleteExpression(use) &&
+                !ts.isPrefixUnaryExpression(use) &&
+                !ts.isPostfixUnaryExpression(use) &&
+                !(ts.isBinaryExpression(use) &&
+                    use.left === positionedAccess &&
+                    use.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+                    use.operatorToken.kind <= ts.SyntaxKind.LastAssignment));
+        }
+        const callPosition = outermostErasureOf(parent);
+        const call = callPosition.parent;
+        if (!ts.isCallExpression(call) || call.expression !== callPosition || call.arguments.some(ts.isSpreadElement))
+            return false;
+        if (family === 'Array') {
+            if ([
+                'slice',
+                'concat',
+                'splice',
+                'push',
+                'pop',
+                'shift',
+                'unshift',
+                'indexOf',
+                'lastIndexOf',
+                'includes',
+                'join',
+                'toString',
+                'at',
+                'keys',
+                'values',
+                'entries'
+            ].includes(key))
+                return true;
+            if (['reverse', 'sort', 'fill', 'copyWithin'].includes(key))
+                return ts.isExpressionStatement(call.parent);
+            // Callback-bearing methods pass the receiver as an ordinary callback
+            // argument. Without its complete callback frame this is an exposure.
+            return false;
+        }
+        // `set` returns its receiver; the shared engine must follow that result.
+        if (key === 'set')
+            return ts.isExpressionStatement(call.parent) ? true : null;
+        if (key === 'get' || key === 'has' || key === 'delete')
+            return true;
+        if (family === 'Map' && (key === 'clear' || key === 'keys' || key === 'values' || key === 'entries'))
+            return true;
+        // forEach's third argument, method extraction and reflection can hand out
+        // the map itself. They need explicit continuations, never an inert answer.
+        return false;
+    };
+    return { intrinsic: family, location: publication, deferred, prototypeKeys: prototypeKeysOf(family), roots: [...roots], terminalUse };
+};
+const arrayMethods = [
+    'slice',
+    'concat',
+    'splice',
+    'push',
+    'pop',
+    'shift',
+    'unshift',
+    'indexOf',
+    'lastIndexOf',
+    'includes',
+    'join',
+    'toString',
+    'at',
+    'keys',
+    'values',
+    'entries',
+    'reverse',
+    'sort',
+    'fill',
+    'copyWithin'
+];
+const mapMethods = ['get', 'set', 'has', 'delete', 'clear', 'keys', 'values', 'entries', 'size'];
+/**
+ * The prototype keys a plan's admitted uses read. `next` is the iterator
+ * prototype's method (a write to it can only come through a receiver the
+ * census cannot name, which it records against every surface), `@@`-names
+ * are symbol keys, and `constructor` is read by species creation
+ * (`slice`/`concat`/`splice`).
+ */
+const prototypeKeysOf = (family) => family === 'Array'
+    ? { names: [...arrayMethods, 'constructor', 'next', '@@iterator', '@@species', '@@isConcatSpreadable'], arrayIndices: true }
+    : { names: [...mapMethods, 'next', '@@iterator'] };
+const plans = new WeakMap();
+export const nativeCollectionProtocolPlanOf = (checker, flow, publication, family, constructions) => {
+    const anchor = constructions.values().next().value;
+    if (!anchor)
+        return null;
+    const constructor = resolveFlowSymbolAlias(checker, checker.getSymbolAtLocation(unwrapErasedExpression(anchor.expression)));
+    if (!constructor)
+        return null;
+    let cache = plans.get(flow);
+    if (!cache)
+        plans.set(flow, (cache = new Map()));
+    if (cache.has(constructor))
+        return cache.get(constructor);
+    const plan = buildNativeCollectionProtocolPlan(checker, flow, publication, family, constructions);
+    cache.set(constructor, plan);
+    return plan;
+};
+const arrayPlans = new WeakMap();
+export const nativeArrayProtocolPlanOf = (checker, flow, array) => {
+    // The plan is one per program -- every array shares the intrinsic
+    // protocol -- but whether THIS expression is an array is a question about
+    // it, and answering from the cache first let any expression through once
+    // one array had been asked about.
+    const type = checker.getTypeAtLocation(array);
+    if (!checker.isArrayType(type) && !checker.isTupleType(type))
+        return null;
+    if (arrayPlans.has(flow))
+        return arrayPlans.get(flow);
+    const plan = buildNativeCollectionProtocolPlan(checker, flow, array, 'Array', new Set(), array);
+    arrayPlans.set(flow, plan);
+    return plan;
+};

package/dist/semantics/normalize/flow/node-path-token.d.ts

@@ -0,0 +1,3 @@
+import ts from 'typescript';
+export declare const nodePathToken: (node: ts.Node) => string;
+export declare const nodeSetToken: (nodes: readonly ts.Node[]) => string;

package/dist/semantics/normalize/flow/node-path-token.js

@@ -0,0 +1,53 @@
+/**
+ * A short, stable id for a node -- the spelling of "which syntax is this" that
+ * content-keyed proof identities are built from.
+ *
+ * It is interned rather than spelled out for two measured reasons, both from
+ * live three.js profiles. Spelling it as `<file>#<pos>` called
+ * `getSourceFile()`, which walks parent pointers up to the file, on EVERY ask;
+ * that walk (`getSourceFileOfNode`) reached 17.6% of self time. And the
+ * resulting key carried a full absolute path per root, so every memo lookup
+ * hashed a string hundreds of characters long -- `sharedAnswerOf` itself then
+ * reached 17.6% of self time, almost all of it in key construction and Map
+ * hashing rather than in the answers.
+ *
+ * A counter is enough: the memo keys only need the id to be unique per node
+ * and stable for the life of the compile, which the WeakMap guarantees. The
+ * ids are never parsed, printed to a user, or compared for order -- callers
+ * sort them only to make a multi-root key canonical.
+ */
+const nodePathTokens = new WeakMap();
+let nextNodePathToken = 0;
+export const nodePathToken = (node) => {
+    let token = nodePathTokens.get(node);
+    if (token === undefined)
+        nodePathTokens.set(node, (token = `n${(nextNodePathToken++).toString(36)}`));
+    return token;
+};
+/**
+ * The canonical token list for a set of nodes, memoized on the array itself.
+ *
+ * A proof identity spells this on EVERY ask, and 99% of asks are memo HITS --
+ * so the map, the sort and the join were pure allocation on the fast path,
+ * feeding the garbage collector that a live three.js profile put at 20.3% of
+ * self time, the largest single cost once the walk and the long keys were
+ * gone. The array object memoizes that work whenever a caller holds onto its
+ * array, which the tokens it holds cannot invalidate.
+ *
+ * The array memo is not enough on its own, because a caller is free to mint a
+ * fresh array per ask and several do. A ONE-root set needs no array work in
+ * the first place, and that is not a rare shape: every question the three.js app asks
+ * millions of times names a single root, so the canonical spelling of the set
+ * is just that root's own token. Taking it before the WeakMap skips the
+ * lookup, both intermediate arrays and the join on the path that dominates.
+ */
+const nodeSetTokens = new WeakMap();
+export const nodeSetToken = (nodes) => {
+    const sole = nodes.length === 1 ? nodes[0] : undefined;
+    if (sole !== undefined)
+        return nodePathToken(sole);
+    let token = nodeSetTokens.get(nodes);
+    if (token === undefined)
+        nodeSetTokens.set(nodes, (token = nodes.map(nodePathToken).sort().join(',')));
+    return token;
+};

package/dist/semantics/normalize/flow/object-binding-continuation.d.ts

@@ -0,0 +1,11 @@
+import ts from 'typescript';
+import type { ValueFlowIndex } from './model.js';
+export interface ObjectBindingRead {
+    readonly key: string;
+    readonly binding: ts.BindingElement;
+}
+/** Named object-binding reads already enumerated by the shared flow index.
+ * This states the selected fields, not whether a receiver field is data or
+ * whether the resulting binding escapes; consumers retain those proofs.
+ */
+export declare const objectBindingReadsOf: (flow: ValueFlowIndex, source: ts.Expression) => readonly ObjectBindingRead[] | null;

package/dist/semantics/normalize/flow/object-binding-continuation.js

@@ -0,0 +1,42 @@
+import ts from 'typescript';
+const reads = new WeakMap();
+/** Named object-binding reads already enumerated by the shared flow index.
+ * This states the selected fields, not whether a receiver field is data or
+ * whether the resulting binding escapes; consumers retain those proofs.
+ */
+export const objectBindingReadsOf = (flow, source) => {
+    const parent = source.parent;
+    if (!ts.isVariableDeclaration(parent) || parent.initializer !== source || !ts.isObjectBindingPattern(parent.name))
+        return null;
+    let inventory = reads.get(flow);
+    if (!inventory) {
+        const collected = new Map();
+        for (const write of flow.allWrites) {
+            if (write.edge !== 'destructuring' ||
+                write.slot !== 'member' ||
+                !write.naming ||
+                write.member === null ||
+                !ts.isBindingElement(write.site))
+                continue;
+            let entries = collected.get(write.naming);
+            if (!entries)
+                collected.set(write.naming, (entries = new Map()));
+            entries.set(write.site, write.member);
+        }
+        inventory = collected;
+        reads.set(flow, inventory);
+    }
+    const selected = inventory.get(source);
+    const result = [];
+    for (const binding of parent.name.elements) {
+        if (binding.dotDotDotToken || binding.initializer || !ts.isIdentifier(binding.name))
+            return null;
+        const key = selected?.get(binding);
+        if (key === undefined)
+            return null;
+        if (!flow.writesToDeclaration(binding).some((write) => write.edge === 'destructuring' && write.slot === 'whole' && write.site === binding))
+            return null;
+        result.push({ key, binding });
+    }
+    return result;
+};

package/dist/semantics/normalize/flow/origin-authority.d.ts

@@ -0,0 +1,56 @@
+import ts from 'typescript';
+import type { NativeCollectionProtocolPlan } from './native-collection-protocol.js';
+import type { ClosedCallableAuthority } from './callable-array-origins.js';
+import type { SourceInvocationFact } from './invocation-facts.js';
+import type { IntrinsicProtocolRequirement } from '../deferred-intrinsic-protocols.js';
+/** A provenance answer computed under the deferred-protocol ledger's capture. */
+export interface SharedProvenanceAnswer<T> {
+    readonly value: T | null;
+    readonly requirements: readonly IntrinsicProtocolRequirement[];
+}
+/** @semanticCategory generic-primitive */
+export interface SourceRecordOriginAuthority {
+    /** Complete inbound frame, including defaults and writes; partial callers are not evidence. */
+    readonly parameterValuesOf: (parameter: ts.ParameterDeclaration) => readonly ts.Expression[] | null;
+    readonly checker: ts.TypeChecker;
+    readonly protocolClosed: (plan: NativeCollectionProtocolPlan) => boolean;
+    /** Index keys the checker cannot type as numbers; see `arrayStoredValuesOf`. */
+    readonly numericKey: (key: ts.Expression) => boolean;
+    /** Whole-program proof for record slots the local alias walk cannot follow. */
+    readonly recordSlotClosed: (receiver: ts.Expression, key: string, roots: readonly ts.ObjectLiteralExpression[]) => boolean;
+    /** The complete values a slot read yields, from the joint value graph, or
+     * null where it refuses: `renderer.state` filled by `_this.state = state`
+     * in a constructor, which no record-literal plan can see through. */
+    readonly slotValuesOf?: (access: ts.PropertyAccessExpression | ts.ElementAccessExpression) => readonly ts.Expression[] | null;
+    /** The complete values any expression holds, from the joint value graph, or null where it refuses. */
+    readonly graphValuesOf?: (expression: ts.Expression) => readonly ts.Expression[] | null;
+}
+/** @semanticCategory generic-primitive */
+export interface OriginAuthority extends SourceRecordOriginAuthority, ClosedCallableAuthority {
+    readonly receiverValuesOf: NonNullable<ClosedCallableAuthority['receiverValuesOf']>;
+    readonly closedCallerSitesOf: NonNullable<ClosedCallableAuthority['closedCallerSitesOf']>;
+    readonly arrayElementTargetsOf: NonNullable<ClosedCallableAuthority['arrayElementTargetsOf']>;
+    readonly explicitInvocationIsIntact: NonNullable<ClosedCallableAuthority['explicitInvocationIsIntact']>;
+    readonly invocationFactOf: (call: ts.CallExpression) => SourceInvocationFact | null;
+    readonly bindingValuesOf: (declaration: ts.VariableDeclaration) => readonly ts.Expression[] | null;
+    /** Direct integrity check when available; otherwise obligations enter the deferred ledger. */
+    readonly intrinsicIntact?: (intrinsic: 'Object' | 'Array', member: string | undefined, location: ts.Node) => boolean;
+    /** Publish a positive memo only after its enclosing coinductive proof settles. */
+    readonly whenSettled: (publish: () => void) => void;
+    /**
+     * Compute a provenance answer once for every proof that holds the same
+     * coinductive parks. A record plan or an array inventory depends on the
+     * authority only through its parks (the members, families, record and
+     * value proofs assumed open up the stack) and its two key functions, not on
+     * which proof happened to ask -- yet the caller-identity caches above are
+     * keyed on the authority OBJECT, which every proof mints afresh, so the three.js app
+     * rebuilt the same origin solvers 115 million times. The authority records
+     * which parks the computation leaned on and replays the answer wherever
+     * those same parks are in force; `shareable` withholds an answer -- refusal
+     * or not -- that the caller knows was computed from an incomplete view (a
+     * re-entered inventory), which is the one thing the trail cannot see.
+     */
+    readonly sharedAnswerOf?: <T>(identity: string, compute: () => T | null, shareable?: (value: T | null) => boolean) => SharedProvenanceAnswer<T>;
+}
+/** Structural cache identity is the complete caller authority object itself. */
+export declare const originAuthorityIdentity: (authority: OriginAuthority) => object;

package/dist/semantics/normalize/flow/origin-authority.js

@@ -0,0 +1,2 @@
+/** Structural cache identity is the complete caller authority object itself. */
+export const originAuthorityIdentity = (authority) => authority;

package/dist/semantics/normalize/flow/owned-class-receivers.d.ts

@@ -0,0 +1,35 @@
+import ts from 'typescript';
+import { type ReceiverReference, type SourceClass, type ValueFlowIndex } from './model.js';
+import { type SourceConstructionFact } from './member-call-forwarding.js';
+export interface OwnedClassConstruction extends SourceConstructionFact {
+    /** The authenticated constructor alternatives that belong to this inventory's exact receiver family. */
+    readonly familyProjection: readonly SourceClass[];
+}
+export interface OwnedClassReceiverInventory {
+    readonly classes: ReadonlySet<SourceClass>;
+    readonly initializers: readonly {
+        readonly owner: SourceClass;
+        /**
+         * The declaration whose body or initializer runs with the receiver.
+         *
+         * A constructor function IS its own constructor -- there is no separate
+         * `ConstructorDeclaration` to name, and its field initializers are the
+         * `this.<key> = ...` statements in that same body -- so the function
+         * declaration stands for both, once.
+         */
+        readonly member: ts.ConstructorDeclaration | ts.PropertyDeclaration | ts.FunctionDeclaration | ts.FunctionExpression;
+        readonly references: readonly ReceiverReference[];
+    }[];
+    /** Source construction alternatives are retained with their exact-family projection. */
+    readonly constructionFacts: readonly OwnedClassConstruction[];
+}
+/**
+ * Every source class in the program whose ancestry reaches one of `roots`,
+ * the roots included, each with its declared type; null when a root is not a
+ * class the checker types. This is the whole "family" the receiver inventory
+ * below walks, and the family `new this.constructor()` allocates from
+ * (`thisConstructorFamilyOf`): heritage alone, read from the checker, so it
+ * can be asked while that inventory is itself being built.
+ */
+export declare const sourceClassFamilyOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, roots: ReadonlySet<SourceClass>) => ReadonlyMap<SourceClass, ts.InterfaceType> | null;
+export declare const ownedClassReceiverInventoryOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, roots: ReadonlySet<SourceClass>) => OwnedClassReceiverInventory | null;

package/dist/semantics/normalize/flow/owned-class-receivers.js

@@ -0,0 +1,191 @@
+import ts from 'typescript';
+import { heritageClassOrInterfaceOf, isClassSpelledSourceClass, isConstructorFunction } from './model.js';
+import { classConstructorKeepsInstanceOf, exactSourceConstructionOf, sourceConstructorSelectionsOf } from './member-call-forwarding.js';
+const declaredTypeOf = (checker, declaration) => {
+    const symbol = declaration.name ? checker.getSymbolAtLocation(declaration.name) : checker.getTypeAtLocation(declaration).getSymbol();
+    const type = symbol && checker.getDeclaredTypeOfSymbol(symbol);
+    return type?.isClassOrInterface() ? type : null;
+};
+const classDeclarationOf = (type) => {
+    const declaration = type.getSymbol()?.valueDeclaration;
+    return declaration && (ts.isClassDeclaration(declaration) || ts.isClassExpression(declaration) || isConstructorFunction(declaration))
+        ? declaration
+        : null;
+};
+const ancestryOf = (checker, type, seen = new Set()) => {
+    if (seen.has(type))
+        return [];
+    seen.add(type);
+    const own = classDeclarationOf(type);
+    return [
+        ...(own ? [own] : []),
+        ...checker.getBaseTypes(type).flatMap((base) => {
+            const declared = heritageClassOrInterfaceOf(base);
+            return declared === null ? [] : ancestryOf(checker, declared, seen);
+        })
+    ];
+};
+/**
+ * Every source class in the program whose ancestry reaches one of `roots`,
+ * the roots included, each with its declared type; null when a root is not a
+ * class the checker types. This is the whole "family" the receiver inventory
+ * below walks, and the family `new this.constructor()` allocates from
+ * (`thisConstructorFamilyOf`): heritage alone, read from the checker, so it
+ * can be asked while that inventory is itself being built.
+ */
+export const sourceClassFamilyOf = (checker, flow, roots) => {
+    const family = new Map();
+    for (const declaration of flow.classDeclarations) {
+        const type = declaredTypeOf(checker, declaration);
+        if (type && ancestryOf(checker, type).some((ancestor) => roots.has(ancestor)))
+            family.set(declaration, type);
+    }
+    return [...roots].some((root) => !family.has(root)) ? null : family;
+};
+/** Constructor/field receiver uses exist even when no code names a method on
+ * the constructed object. Enumerate them and every construction that can
+ * select a class in the source family before a caller tries to prove that a
+ * sibling field cannot publish its owner. A mixed source choice retains all
+ * alternatives beside the family projection; this is an inventory, not an
+ * escape proof, so callers must still explain every receiver mention and
+ * construction result.
+ */
+const collectOwnedClassReceiverInventory = (checker, flow, roots) => {
+    if (roots.size === 0)
+        return null;
+    const watched = process.env.GEA_OWNED_CLASS_DEBUG;
+    const named = (declaration) => declaration.name?.text ?? '(anonymous)';
+    const watching = watched !== undefined && [...roots].some((root) => named(root) === watched);
+    const refuse = (reason, detail) => {
+        if (watching)
+            console.error(`[OWNED-CLASS] ${[...roots].map(named).join(',')} ${reason}${detail ? ` ${detail}` : ''}`);
+        return null;
+    };
+    const declarationOf = classDeclarationOf;
+    const ancestry = (type) => ancestryOf(checker, type);
+    const family = sourceClassFamilyOf(checker, flow, roots);
+    if (!family)
+        return refuse('root-outside-family');
+    const owners = new Set();
+    for (const type of family.values()) {
+        // In particular this rejects a subclass handed to unknown code even if
+        // the program never spells `new Subclass`: that code can construct one.
+        if (!classConstructorKeepsInstanceOf(checker, flow, type))
+            return refuse('constructor-does-not-keep-instance', named(declarationOf(type)));
+        for (const owner of ancestry(type))
+            owners.add(owner);
+    }
+    const constructionFacts = [];
+    for (const { call } of flow.calls) {
+        if (!ts.isNewExpression(call))
+            continue;
+        const selections = sourceConstructorSelectionsOf(checker, flow, call.expression);
+        if (selections) {
+            const familyProjection = selections.filter((owner) => family.has(owner));
+            if (familyProjection.length === 0)
+                continue;
+            const construction = exactSourceConstructionOf(checker, flow, call);
+            if (!construction ||
+                construction.alternatives.length !== selections.length ||
+                selections.some((owner) => !construction.alternatives.includes(owner)))
+                return refuse('unverified-construction', call.getText().slice(0, 60));
+            // The helper admits only complete source selections whose constructors
+            // preserve their instance identity. A mixed conditional keeps sibling
+            // alternatives attached; classes and familyProjection remain scoped to
+            // this exact nominal family.
+            constructionFacts.push({ ...construction, familyProjection });
+        }
+        else {
+            const type = checker.getTypeAtLocation(call);
+            const alternatives = type.isUnion() ? type.types : [type];
+            if (!alternatives.some((value) => value.isClassOrInterface() && family.has(declarationOf(value))))
+                continue;
+            // An opaque constructor promising this family cannot be silently
+            // omitted from its allocation inventory.
+            return refuse('opaque-construction', call.getText().slice(0, 60));
+        }
+    }
+    // Zero constructions is a COMPLETE inventory, not an unknown one. Every
+    // possibly family-producing construction is either recorded with a nonempty
+    // exact projection or an opaque family promise has refused above, and
+    // `classConstructorKeepsInstanceOf` accounts for every mention of every
+    // class binding in the family. Reaching here empty means the program creates
+    // no instance of this family at all, so there is no receiver for a caller to
+    // explain. Refusing it instead made three's `SpotLight` (never constructed
+    // by the renderer under measurement) the terminal of 32 escapes, among them
+    // `WebGLState`'s whole colour/depth/stencil buffer family.
+    const initializers = [];
+    for (const owner of owners) {
+        if (!isClassSpelledSourceClass(owner)) {
+            initializers.push({ owner, member: owner, references: flow.receiverReferencesToDeclaration(owner) });
+            continue;
+        }
+        for (const member of owner.members) {
+            if (!ts.isConstructorDeclaration(member) && !ts.isPropertyDeclaration(member))
+                continue;
+            if ((ts.getCombinedModifierFlags(member) & ts.ModifierFlags.Static) !== 0)
+                continue;
+            initializers.push({ owner, member, references: flow.receiverReferencesToDeclaration(member) });
+        }
+    }
+    return { classes: new Set(family.keys()), initializers, constructionFacts };
+};
+const inventories = new WeakMap();
+/**
+ * A multi-class family (a union receiver, or several exact allocation
+ * origins) asks the identical question every time the SAME set of roots is
+ * handed back -- measured on the three.js app at 23.3 s of self time in
+ * `collectOwnedClassReceiverInventory` alone, because the singleton fast path
+ * below only ever covered `roots.size === 1` and every larger family fell
+ * through to the uncached walk on every call, including every one of a
+ * class's several members asking about the same family in the same round.
+ *
+ * Keyed by a canonical, ORDER-INDEPENDENT spelling of the root set rather than
+ * the `Set` object identity, because `familyRootsOf` mints a fresh `Set` per
+ * call even when its contents are the same roots as the last call. Ordinals
+ * are minted once per `SourceClass` node (stable for the process, harmless to
+ * share across flows) purely so two sets with the same members always sort to
+ * the same key regardless of which order they were built in.
+ */
+const classOrdinals = new WeakMap();
+let nextClassOrdinal = 0;
+const ordinalOf = (node) => {
+    let id = classOrdinals.get(node);
+    if (id === undefined) {
+        id = nextClassOrdinal++;
+        classOrdinals.set(node, id);
+    }
+    return id;
+};
+const rootsKey = (roots) => [...roots]
+    .map(ordinalOf)
+    .sort((a, b) => a - b)
+    .join(',');
+const multiRootInventories = new WeakMap();
+export const ownedClassReceiverInventoryOf = (checker, flow, roots) => {
+    // Every method of one class asks for the same source inventory. Cache the
+    // inventory, never the caller's escape decision; a rebuilt flow index starts
+    // a new inference round and cannot reuse facts from the previous one.
+    if (roots.size === 0)
+        return collectOwnedClassReceiverInventory(checker, flow, roots);
+    if (roots.size === 1) {
+        const root = roots.values().next().value;
+        let entries = inventories.get(flow);
+        if (!entries)
+            inventories.set(flow, (entries = new Map()));
+        if (entries.has(root))
+            return entries.get(root);
+        const inventory = collectOwnedClassReceiverInventory(checker, flow, roots);
+        entries.set(root, inventory);
+        return inventory;
+    }
+    let held = multiRootInventories.get(flow);
+    if (!held)
+        multiRootInventories.set(flow, (held = new Map()));
+    const key = rootsKey(roots);
+    if (held.has(key))
+        return held.get(key);
+    const inventory = collectOwnedClassReceiverInventory(checker, flow, roots);
+    held.set(key, inventory);
+    return inventory;
+};