@geastack/compiler 1.0.15

package/dist/semantics/normalize/flow/intrinsic-data-definition.d.ts

@@ -0,0 +1,35 @@
+import ts from 'typescript';
+export interface IntrinsicDataDefinitionPlan {
+    readonly owner: 'Object' | 'Reflect';
+    readonly member: 'defineProperty' | 'defineProperties';
+    readonly keys: readonly string[];
+    /** Every descriptor's `value` initializer, in definition order: what the definitions store on the target. */
+    readonly values: readonly ts.Expression[];
+    readonly returnsTarget: boolean;
+    /**
+     * The descriptor fields no descriptor literal spells, which
+     * ToPropertyDescriptor reads through `Object.prototype`: a `{ value }`
+     * descriptor turns into an accessor the moment someone defines
+     * `Object.prototype.get`. Empty exactly when every descriptor carries
+     * `__proto__: null`. Asked per key, not as the whole prototype: the three.js app's
+     * final census records single keys written through receivers it cannot
+     * attribute, which fails the whole-object question for every `Object
+     * .defineProperty( this, 'id', { value } )` in three while leaving
+     * `writable`, `enumerable`, `configurable`, `get` and `set` untouched.
+     */
+    readonly descriptorPrototypeKeys: readonly string[];
+    readonly call: ts.CallExpression;
+}
+/**
+ * Whether every mention of a binding is one this proof already accounts for --
+ * its own declaration name, or the argument being inspected.
+ */
+export type SoleUseOfBinding = (declaration: ts.VariableDeclaration, argument: ts.Expression) => boolean;
+/** The target argument of a data-only intrinsic definition is not published
+ * to user code by that operation. This plan still requires authenticated final
+ * static-member identity and, for ordinary descriptor literals, an intact
+ * Object prototype: ToPropertyDescriptor reads inherited get/set and flags.
+ * Callers must follow Object's returned target, and cannot ignore replacement
+ * of the member whose callable or containing-field identity they are proving.
+ */
+export declare const intrinsicDataDefinitionTargetOf: (checker: ts.TypeChecker, reference: ts.Expression, soleUseOfBinding?: SoleUseOfBinding) => IntrinsicDataDefinitionPlan | null;

package/dist/semantics/normalize/flow/intrinsic-data-definition.js

@@ -0,0 +1,140 @@
+import ts from 'typescript';
+import { unwrapErasedExpression } from '../producers/erasure.js';
+const DESCRIPTOR_FIELDS = ['value', 'writable', 'get', 'set', 'enumerable', 'configurable'];
+const literalKey = (expression) => ts.isStringLiteralLike(expression) || ts.isNumericLiteral(expression) ? expression.text : null;
+const propertyKey = (name) => ts.isComputedPropertyName(name)
+    ? literalKey(unwrapErasedExpression(name.expression))
+    : ts.isIdentifier(name)
+        ? name.text
+        : literalKey(name);
+/** The target argument of a data-only intrinsic definition is not published
+ * to user code by that operation. This plan still requires authenticated final
+ * static-member identity and, for ordinary descriptor literals, an intact
+ * Object prototype: ToPropertyDescriptor reads inherited get/set and flags.
+ * Callers must follow Object's returned target, and cannot ignore replacement
+ * of the member whose callable or containing-field identity they are proving.
+ */
+export const intrinsicDataDefinitionTargetOf = (checker, reference, soleUseOfBinding) => {
+    const call = reference.parent;
+    if (!ts.isCallExpression(call) || call.arguments[0] !== reference || call.arguments.some(ts.isSpreadElement))
+        return null;
+    const callee = unwrapErasedExpression(call.expression);
+    if (!ts.isPropertyAccessExpression(callee) && !ts.isElementAccessExpression(callee))
+        return null;
+    const member = ts.isPropertyAccessExpression(callee) ? callee.name.text : literalKey(callee.argumentExpression);
+    if (member !== 'defineProperty' && member !== 'defineProperties')
+        return null;
+    const receiver = unwrapErasedExpression(callee.expression);
+    if (!ts.isIdentifier(receiver))
+        return null;
+    const symbol = checker.getSymbolAtLocation(receiver);
+    if (!symbol ||
+        (symbol.name !== 'Object' && symbol.name !== 'Reflect') ||
+        !symbol.declarations?.length ||
+        !symbol.declarations.every((declaration) => declaration.getSourceFile().hasNoDefaultLib))
+        return null;
+    const owner = symbol.name;
+    if (owner === 'Reflect' && member === 'defineProperties')
+        return null;
+    const method = checker.getPropertyOfType(checker.getTypeAtLocation(receiver), member);
+    if (!method?.declarations?.length || !method.declarations.every((declaration) => declaration.getSourceFile().hasNoDefaultLib))
+        return null;
+    const keys = new Set();
+    const values = [];
+    const descriptorPrototypeKeys = new Set();
+    /**
+     * The descriptor literal an argument names.
+     *
+     * `define-property-source-transform.ts` lowers `Object.defineProperties( o,
+     * { ... } )` into one `Object.defineProperty` per key, hoisting each
+     * descriptor into its own `const` first so that `defineProperties`' two
+     * phases -- evaluate every descriptor, THEN define -- are preserved. That
+     * hoist hands this proof an IDENTIFIER where the pre-transform call handed
+     * it a literal, and the plan was refused for it: three's `Object3D`
+     * constructor defines `position`, `rotation`, `quaternion`, `scale`,
+     * `modelViewMatrix` and `normalMatrix` that way, and the receiver `this`
+     * was reported escaping through its own lowering.
+     *
+     * Followed only to a `const` whose single declaration initializes it
+     * directly with the literal, and only when nothing else mentions the
+     * binding: an alias could otherwise write `d.get = fn` between the `const`
+     * and the call, which would turn a data definition into an accessor
+     * invocation ON the target and void the premise that the target is not
+     * published. Those are exactly the conditions the transform's own output
+     * satisfies by construction.
+     */
+    const descriptorLiteralOf = (expression) => {
+        const value = unwrapErasedExpression(expression);
+        if (ts.isObjectLiteralExpression(value))
+            return value;
+        if (!ts.isIdentifier(value) || soleUseOfBinding === undefined)
+            return null;
+        const declarations = checker.getSymbolAtLocation(value)?.declarations ?? [];
+        const declaration = declarations.length === 1 ? declarations[0] : undefined;
+        if (!declaration || !ts.isVariableDeclaration(declaration) || !declaration.initializer)
+            return null;
+        if ((ts.getCombinedNodeFlags(declaration) & ts.NodeFlags.Const) === 0)
+            return null;
+        if (!soleUseOfBinding(declaration, value))
+            return null;
+        const initializer = unwrapErasedExpression(declaration.initializer);
+        return ts.isObjectLiteralExpression(initializer) ? initializer : null;
+    };
+    const descriptor = (expression) => {
+        const value = descriptorLiteralOf(expression);
+        if (value === null)
+            return false;
+        let nullPrototype = false;
+        const spelled = new Set();
+        for (const property of value.properties) {
+            if (!ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property))
+                return false;
+            const key = propertyKey(property.name);
+            if (key !== null)
+                spelled.add(key);
+            if (key === '__proto__' &&
+                ts.isPropertyAssignment(property) &&
+                !ts.isComputedPropertyName(property.name) &&
+                unwrapErasedExpression(property.initializer).kind === ts.SyntaxKind.NullKeyword) {
+                nullPrototype = true;
+                continue;
+            }
+            if (key !== 'value' && key !== 'writable' && key !== 'enumerable' && key !== 'configurable')
+                return false;
+            if (key === 'value')
+                values.push(ts.isPropertyAssignment(property) ? property.initializer : property.name);
+        }
+        if (!nullPrototype)
+            for (const field of DESCRIPTOR_FIELDS)
+                if (!spelled.has(field))
+                    descriptorPrototypeKeys.add(field);
+        return true;
+    };
+    const entry = (key, value) => {
+        if (key === null || key === '__proto__' || key === 'constructor' || !descriptor(value))
+            return false;
+        keys.add(key);
+        return true;
+    };
+    if (member === 'defineProperty') {
+        if (call.arguments.length !== 3 || !entry(literalKey(unwrapErasedExpression(call.arguments[1])), call.arguments[2]))
+            return null;
+    }
+    else {
+        if (call.arguments.length !== 2)
+            return null;
+        const definitions = unwrapErasedExpression(call.arguments[1]);
+        if (!ts.isObjectLiteralExpression(definitions) ||
+            !definitions.properties.every((property) => ts.isPropertyAssignment(property) && entry(propertyKey(property.name), property.initializer)))
+            return null;
+    }
+    return {
+        owner,
+        member,
+        keys: [...keys],
+        values,
+        returnsTarget: owner === 'Object',
+        descriptorPrototypeKeys: [...descriptorPrototypeKeys],
+        call
+    };
+};

package/dist/semantics/normalize/flow/invocation-facts.d.ts

@@ -0,0 +1,98 @@
+import ts from 'typescript';
+import type { FlowInvocationOperands, ReceiverReference, ValueFlowIndex } from './model.js';
+import type { IntrinsicProtocolRequirement } from '../deferred-intrinsic-protocols.js';
+import { type CallableCompletionSummary } from './callable-completions.js';
+import { type SourceInvocationFrameLayout } from './source-invocation-frame-layout.js';
+declare const invocationFactIdentity: unique symbol;
+export interface InvocationValueUses {
+    readonly value: ts.Expression;
+    readonly parameter: ts.ParameterDeclaration | null;
+    /** Only actual arguments inhabit the arguments object. */
+    readonly argumentPosition: number | null;
+    readonly restElementPosition: number | null;
+    /** Defaults conservatively continue only along the undefined-argument branch. */
+    readonly activation: 'always' | 'argument-undefined';
+    readonly uses: readonly ts.Expression[];
+    /** Uses of an actual argument after it is packed into an identifier rest array. */
+    readonly elementUses: readonly ts.Expression[];
+}
+export interface SourceInvocationFrame {
+    readonly layout: SourceInvocationFrameLayout;
+    readonly body: ts.SignatureDeclaration;
+    readonly parameters: readonly ts.ParameterDeclaration[];
+    readonly receiverUses: readonly ReceiverReference[];
+    /** Known body outcomes survive an unresolved exact-result projection. */
+    readonly completionSummary: CallableCompletionSummary;
+    /** Complete continuation into this body, or a named unsupported frame. */
+    readonly forwarding: {
+        readonly kind: 'values';
+        readonly entries: readonly InvocationValueUses[];
+    } | {
+        readonly kind: 'unresolved';
+        readonly reason: 'spread-arguments' | 'destructured-parameter' | 'arguments-object';
+    };
+    /** Source normal completions in this call's receiver frame. */
+    readonly completions: {
+        readonly kind: 'values';
+        readonly values: readonly ts.Expression[];
+    } | {
+        readonly kind: 'unresolved';
+        readonly reason: 'optional-call' | 'deferred-or-unnamed-completion' | 'implicit-receiver';
+    };
+}
+/** The admitted target set and operand mapping belong to the same proof. */
+export interface SourceInvocationFact {
+    readonly [invocationFactIdentity]: true;
+    readonly call: ts.CallExpression;
+    readonly operands: FlowInvocationOperands;
+    readonly frames: readonly SourceInvocationFrame[];
+    readonly requirements: readonly IntrinsicProtocolRequirement[];
+}
+/** Only the invocation authority may publish an admitted frame family. */
+export declare const sourceInvocationFact: (call: ts.CallExpression, operands: FlowInvocationOperands, frames: readonly SourceInvocationFrame[], requirements: readonly IntrinsicProtocolRequirement[]) => SourceInvocationFact;
+/**
+ * Constructed only by the invocation authority after target admission. Keeping
+ * the frame builder separate from admission lets recursive target proofs follow
+ * a known body's continuations without pretending the whole invocation closed.
+ */
+export declare const sourceInvocationFrame: (flow: ValueFlowIndex, call: ts.CallExpression, body: ts.SignatureDeclaration, argumentsUsesAt: (body: ts.SignatureDeclaration) => readonly ts.Identifier[] | undefined) => SourceInvocationFrame | null;
+/** Complete uses of an actual operand across every admitted target. */
+export declare const invocationValueUsesOf: (fact: SourceInvocationFact, value: ts.Expression) => readonly ts.Expression[] | null;
+export interface InvocationValueContinuation {
+    readonly expression: ts.Expression;
+    readonly projection: 'value' | 'array-element';
+}
+/** Complete actual-argument continuations, retaining the rest-array element hop. */
+export declare const invocationValueContinuationsOf: (fact: SourceInvocationFact, value: ts.Expression) => readonly InvocationValueContinuation[] | null;
+export declare const invocationCompletionValuesOf: (fact: SourceInvocationFact) => readonly ts.Expression[] | null;
+/**
+ * The parameter cell one actual argument binds to in this body's frame, or
+ * `null` when the frame resolves it to no single such cell.
+ *
+ * Which parameter an argument binds to is this contract's fact. A consumer that
+ * asks it of `call.arguments` and `runtimeParametersOf` instead gets a
+ * position, and a position is not the fact: it does not know that a spread
+ * makes every later slot unknown, that a destructured parameter names no cell
+ * at all, or that a body reading its own `arguments` object reaches the
+ * argument through a cell no parameter names. The frame states all three as
+ * named unresolved reasons, so a projection of it cannot forget one.
+ *
+ * A rest slot resolves to a parameter whose value is a FRESH ARRAY holding the
+ * argument, which is a different cell from the argument; `elementUses` is how
+ * the frame says so, and this projection refuses rather than hand back a
+ * parameter that does not hold the value asked about.
+ */
+/**
+ * The argument this call binds to `parameter`, or null when the frame does not
+ * state exactly one.
+ *
+ * The mirror of `frameForwardedParameterOf`, and it lives beside it for the
+ * reason §3 item 1 gives: which argument binds which parameter is the call
+ * frame contract's fact, and a consumer that recomputes it from
+ * `call.arguments` writes a second spelling that will disagree. A rest element,
+ * a destructured element use, or anything but a single stated entry is not one
+ * argument and answers null rather than guessing which.
+ */
+export declare const frameForwardedArgumentOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, call: ts.CallExpression, body: ts.SignatureDeclaration, parameter: ts.ParameterDeclaration) => ts.Expression | null;
+export declare const frameForwardedParameterOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, call: ts.CallExpression, body: ts.SignatureDeclaration, value: ts.Expression) => ts.ParameterDeclaration | null;
+export {};

package/dist/semantics/normalize/flow/invocation-facts.js

@@ -0,0 +1,257 @@
+import ts from 'typescript';
+import { callableCompletionSummaryOf, callableCompletionValuesOf } from './callable-completions.js';
+import { isTypePositionReference } from './targets.js';
+import { sourceInvocationFrameLayoutOf } from './source-invocation-frame-layout.js';
+import { unwrapErasedExpression } from '../producers/erasure.js';
+import { argumentsObjectUsesAt } from '../arguments-objects.js';
+const invocationFactIdentity = Symbol('source-invocation-fact');
+/** Only the invocation authority may publish an admitted frame family. */
+export const sourceInvocationFact = (call, operands, frames, requirements) => ({ [invocationFactIdentity]: true, call, operands, frames, requirements });
+/** The frame access is written, deleted, or appears in a destructuring target. */
+const frameWrite = (access) => {
+    let target = access;
+    let context = target.parent;
+    while (ts.isParenthesizedExpression(context) && context.expression === target) {
+        target = context;
+        context = context.parent;
+    }
+    if (ts.isBinaryExpression(context) &&
+        context.left === target &&
+        context.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+        context.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
+        return true;
+    if ((ts.isPrefixUnaryExpression(context) || ts.isPostfixUnaryExpression(context)) &&
+        (context.operator === ts.SyntaxKind.PlusPlusToken || context.operator === ts.SyntaxKind.MinusMinusToken))
+        return true;
+    return (ts.isDeleteExpression(context) ||
+        ts.isArrayLiteralExpression(context) ||
+        ts.isPropertyAssignment(context) ||
+        ts.isShorthandPropertyAssignment(context) ||
+        ts.isSpreadElement(context));
+};
+/**
+ * Every read of a callable's own arguments object that can yield an argument.
+ * A null result means the object is used in a way whose carried values cannot
+ * be represented by a finite invocation frame.
+ */
+const argumentsElementReadsOf = (body, argumentsUsesAt) => {
+    const reads = [];
+    for (const identifier of argumentsUsesAt(body) ?? []) {
+        const access = identifier.parent;
+        if (ts.isPropertyAccessExpression(access) && access.expression === identifier && access.name.text === 'length' && !frameWrite(access))
+            continue;
+        if (ts.isElementAccessExpression(access) && access.expression === identifier && !frameWrite(access)) {
+            reads.push(access);
+            continue;
+        }
+        return null;
+    }
+    return reads;
+};
+/**
+ * Constructed only by the invocation authority after target admission. Keeping
+ * the frame builder separate from admission lets recursive target proofs follow
+ * a known body's continuations without pretending the whole invocation closed.
+ */
+export const sourceInvocationFrame = (flow, call, body, argumentsUsesAt) => {
+    const layout = sourceInvocationFrameLayoutOf(flow, call, body);
+    const completionSummary = callableCompletionSummaryOf(flow, body);
+    if (layout === null || completionSummary === null)
+        return null;
+    const { parameters, receiverUses, operands } = layout;
+    const entries = [];
+    const parameterUses = (parameter) => flow.referencesToDeclaration(parameter).filter((reference) => reference !== parameter.name && !isTypePositionReference(reference));
+    const frameReads = argumentsElementReadsOf(body, argumentsUsesAt);
+    const restPosition = parameters.findIndex((parameter) => parameter.dotDotDotToken !== undefined);
+    const restParameter = restPosition < 0 ? undefined : parameters[restPosition];
+    const restUses = restParameter && ts.isIdentifier(restParameter.name) ? parameterUses(restParameter) : [];
+    for (let position = 0; position < operands.args.length; position++) {
+        const value = operands.args[position];
+        const parameter = restPosition >= 0 && position >= restPosition ? restParameter : parameters[position];
+        const uses = new Set(frameReads ?? []);
+        const elementUses = new Set();
+        if (restPosition >= 0 && position >= restPosition) {
+            for (const use of restUses)
+                elementUses.add(use);
+        }
+        else if (parameter && ts.isIdentifier(parameter.name)) {
+            for (const use of parameterUses(parameter))
+                uses.add(use);
+        }
+        entries.push({
+            value,
+            parameter: parameter ?? null,
+            argumentPosition: position,
+            restElementPosition: restPosition >= 0 && position >= restPosition ? position - restPosition : null,
+            activation: 'always',
+            uses: [...uses],
+            elementUses: [...elementUses]
+        });
+    }
+    if (layout.arguments.kind === 'positional')
+        for (const slot of layout.arguments.slots)
+            if (slot.kind === 'single' && slot.defaultValue && slot.defaultActivation !== 'never' && ts.isIdentifier(slot.parameter.name))
+                entries.push({
+                    value: slot.defaultValue,
+                    parameter: slot.parameter,
+                    argumentPosition: null,
+                    restElementPosition: null,
+                    activation: 'argument-undefined',
+                    uses: parameterUses(slot.parameter),
+                    elementUses: []
+                });
+    if (layout.receiver.kind === 'expression')
+        entries.push({
+            value: layout.receiver.expression,
+            parameter: null,
+            argumentPosition: null,
+            restElementPosition: null,
+            activation: 'always',
+            uses: receiverUses,
+            elementUses: []
+        });
+    // An arrow still evaluates its explicit/member receiver operand, but never
+    // binds it to this. Retain the discarded operand's empty continuation.
+    if (layout.receiver.kind === 'lexical' && layout.receiver.source === 'arrow' && operands.receiver)
+        entries.push({
+            value: operands.receiver,
+            parameter: null,
+            argumentPosition: null,
+            restElementPosition: null,
+            activation: 'always',
+            uses: [],
+            elementUses: []
+        });
+    const forwarding = layout.arguments.kind === 'spread'
+        ? { kind: 'unresolved', reason: 'spread-arguments' }
+        : parameters.some((parameter) => !ts.isIdentifier(parameter.name))
+            ? { kind: 'unresolved', reason: 'destructured-parameter' }
+            : frameReads === null
+                ? { kind: 'unresolved', reason: 'arguments-object' }
+                : { kind: 'values', entries };
+    const values = ts.isMethodDeclaration(body) || ts.isFunctionDeclaration(body) || ts.isFunctionExpression(body) || ts.isArrowFunction(body)
+        ? callableCompletionValuesOf(flow, body)
+        : null;
+    let completions = { kind: 'unresolved', reason: 'deferred-or-unnamed-completion' };
+    if (ts.isCallChain(call))
+        completions = { kind: 'unresolved', reason: 'optional-call' };
+    else if (values !== null) {
+        const returned = [];
+        let complete = true;
+        for (const value of values) {
+            if (unwrapErasedExpression(value).kind === ts.SyntaxKind.ThisKeyword && !ts.isArrowFunction(body)) {
+                if (layout.receiver.kind !== 'expression' || layout.receiver.conversion !== 'identity') {
+                    complete = false;
+                    break;
+                }
+                returned.push(layout.receiver.expression);
+            }
+            else
+                returned.push(value);
+        }
+        completions = complete ? { kind: 'values', values: returned } : { kind: 'unresolved', reason: 'implicit-receiver' };
+    }
+    return { layout, body, parameters, receiverUses, completionSummary, forwarding, completions };
+};
+/** Complete uses of an actual operand across every admitted target. */
+export const invocationValueUsesOf = (fact, value) => {
+    const uses = new Set();
+    for (const frame of fact.frames) {
+        if (frame.forwarding.kind !== 'values')
+            return null;
+        const entries = frame.forwarding.entries.filter((entry) => entry.value === value);
+        if (entries.length === 0)
+            return null;
+        for (const entry of entries) {
+            if (entry.elementUses.length > 0)
+                return null;
+            for (const use of entry.uses)
+                uses.add(use);
+        }
+    }
+    return [...uses];
+};
+/** Complete actual-argument continuations, retaining the rest-array element hop. */
+export const invocationValueContinuationsOf = (fact, value) => {
+    const valueUses = new Set();
+    const elementUses = new Set();
+    for (const frame of fact.frames) {
+        if (frame.forwarding.kind !== 'values')
+            return null;
+        const entries = frame.forwarding.entries.filter((entry) => entry.value === value);
+        if (entries.length === 0)
+            return null;
+        for (const entry of entries) {
+            for (const expression of entry.uses)
+                valueUses.add(expression);
+            for (const expression of entry.elementUses)
+                elementUses.add(expression);
+        }
+    }
+    return [
+        ...[...valueUses].map((expression) => ({ expression, projection: 'value' })),
+        ...[...elementUses].map((expression) => ({ expression, projection: 'array-element' }))
+    ];
+};
+export const invocationCompletionValuesOf = (fact) => {
+    const values = new Set();
+    for (const frame of fact.frames) {
+        if (frame.completions.kind !== 'values')
+            return null;
+        for (const value of frame.completions.values)
+            values.add(value);
+    }
+    return [...values];
+};
+/**
+ * The parameter cell one actual argument binds to in this body's frame, or
+ * `null` when the frame resolves it to no single such cell.
+ *
+ * Which parameter an argument binds to is this contract's fact. A consumer that
+ * asks it of `call.arguments` and `runtimeParametersOf` instead gets a
+ * position, and a position is not the fact: it does not know that a spread
+ * makes every later slot unknown, that a destructured parameter names no cell
+ * at all, or that a body reading its own `arguments` object reaches the
+ * argument through a cell no parameter names. The frame states all three as
+ * named unresolved reasons, so a projection of it cannot forget one.
+ *
+ * A rest slot resolves to a parameter whose value is a FRESH ARRAY holding the
+ * argument, which is a different cell from the argument; `elementUses` is how
+ * the frame says so, and this projection refuses rather than hand back a
+ * parameter that does not hold the value asked about.
+ */
+/**
+ * The argument this call binds to `parameter`, or null when the frame does not
+ * state exactly one.
+ *
+ * The mirror of `frameForwardedParameterOf`, and it lives beside it for the
+ * reason §3 item 1 gives: which argument binds which parameter is the call
+ * frame contract's fact, and a consumer that recomputes it from
+ * `call.arguments` writes a second spelling that will disagree. A rest element,
+ * a destructured element use, or anything but a single stated entry is not one
+ * argument and answers null rather than guessing which.
+ */
+export const frameForwardedArgumentOf = (checker, flow, call, body, parameter) => {
+    const frame = sourceInvocationFrame(flow, call, body, (owner) => argumentsObjectUsesAt(checker, owner));
+    if (!frame || frame.forwarding.kind !== 'values')
+        return null;
+    const entries = frame.forwarding.entries.filter((entry) => entry.parameter === parameter);
+    if (entries.length !== 1)
+        return null;
+    const entry = entries[0];
+    if (entry.restElementPosition !== null || entry.elementUses.length > 0)
+        return null;
+    return entry.value;
+};
+export const frameForwardedParameterOf = (checker, flow, call, body, value) => {
+    const frame = sourceInvocationFrame(flow, call, body, (owner) => argumentsObjectUsesAt(checker, owner));
+    if (!frame || frame.forwarding.kind !== 'values')
+        return null;
+    const entries = frame.forwarding.entries.filter((entry) => entry.value === value);
+    if (entries.length !== 1)
+        return null;
+    const entry = entries[0];
+    if (entry.parameter === null || entry.restElementPosition !== null || entry.elementUses.length > 0)
+        return null;
+    return entry.parameter;
+};

package/dist/semantics/normalize/flow/member-call-forwarding.d.ts

@@ -0,0 +1,122 @@
+import ts from 'typescript';
+import { type SourceClass, type ValueFlowIndex } from './model.js';
+import type { SharedProvenanceAnswer } from './origin-authority.js';
+export interface ExactClassAllocationOrigins {
+    readonly classes: ReadonlySet<SourceClass>;
+    /** Alternatives reaching this value, projected when the value is a frame's `this`. */
+    readonly constructions: ReadonlyMap<ts.NewExpression, readonly SourceClass[]>;
+}
+export interface SourceConstructionFact {
+    readonly call: ts.NewExpression;
+    readonly alternatives: readonly SourceClass[];
+}
+export declare const namedDeclarationAt: (checker: ts.TypeChecker, expression: ts.Expression) => ts.Declaration | null;
+/** Keyed by the index alone: this walk reads the index and the AST, nothing a
+ * solve can revise, so an answer taken once is the answer. It is asked per
+ * heritage clause of every class the receiver walks, which is why it is worth
+ * holding onto -- following a constructor through a parameter made each answer
+ * cost a frame layout per caller. */
+/**
+ * The owned class family `this.constructor` allocates from when `callee` is
+ * that spelling inside an instance member of a class-spelled source class,
+ * or null: the class and every source subclass in the program
+ * (`sourceClassFamilyOf`). The `constructor` slot must still be
+ * `Object.prototype.constructor` on every member.
+ */
+export declare const thisConstructorFamilyOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, callee: ts.Expression) => readonly SourceClass[] | null;
+export declare const sourceConstructorSelectionsOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, expression: ts.Expression) => readonly SourceClass[] | null;
+export declare const sourceConstructorReturnValuesOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, owner: SourceClass) => readonly ts.Expression[] | null;
+export type ParameterValuesAt = (parameter: ts.ParameterDeclaration) => readonly ts.Expression[] | null;
+/** Constructor/prototype references must be closed even for a subclass with no
+ * visible allocation: handing its constructor elsewhere can create instances
+ * with inherited method slots that the local construction list does not name. */
+export declare const classConstructorKeepsInstanceOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, instance: ts.InterfaceType) => boolean;
+/** The complete source constructor proof shared by receiver observations. */
+export declare const ordinarySourceClassInstanceTestOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, expression: ts.BinaryExpression) => boolean;
+/** Actual allocations reaching a held reference through the shared write and
+ * factory-return inventory. A checker class type alone cannot establish this:
+ * it also admits subclasses and constructors returning alternate objects. */
+/**
+ * The family a `this` denotes, injected rather than imported.
+ *
+ * `this` in a class member denotes an instance of that member's class OR any
+ * subclass of it, and enumerating that -- with the proof that no unknown
+ * subclass exists -- is `ownedClassReceiverInventoryOf`'s job. This module
+ * cannot import it: `owned-class-receivers.ts` and `source-class-data.ts`
+ * both import FROM here, so the dependency only runs one way. It arrives as a
+ * callback for the same reason `parameterValuesAt` does.
+ */
+export type ThisFamilyAt = (expression: ts.Expression) => ExactClassAllocationOrigins | null;
+/** Complete contents of a source data slot, including its mutation and alias
+ * proof. Allocation discovery must not mistake visible writes for all writes. */
+export type BindingValuesAt = (declaration: ts.VariableDeclaration) => readonly ts.Expression[] | null;
+export type FieldValuesAt = (expression: ts.PropertyAccessExpression | ts.ElementAccessExpression) => readonly ts.Expression[] | null;
+/** Complete values produced by a closed source invocation. */
+export type CallCompletionValuesAt = (call: ts.CallExpression) => readonly ts.Expression[] | null;
+/** Every edge of the origin graph is answered by the same enclosing authority.
+ * @semanticCategory generic-primitive
+ */
+export interface ClassAllocationAuthority {
+    readonly parameterValuesOf: ParameterValuesAt;
+    readonly thisFamilyOf: ThisFamilyAt;
+    readonly fieldValuesOf: FieldValuesAt;
+    readonly bindingValuesOf: BindingValuesAt;
+    readonly callCompletionValuesOf: CallCompletionValuesAt;
+    /** The complete values an expression holds, or null: the joint value graph's
+     * answer. Asked for a destructured binding's reference, which it follows
+     * through the record literals `nested` came out of, and for a
+     * `new this.constructor()` construction, where a non-null answer is the
+     * graph's proof that `this` there holds only the named family's constructions. */
+    readonly graphValuesOf?: (expression: ts.Expression) => readonly ts.Expression[] | null;
+    /** Publish a cache entry only after the enclosing recursive assumptions settle. */
+    readonly whenSettled: (publish: () => void) => void;
+    /**
+     * Share one answer across every proof holding the same coinductive parks --
+     * see `OriginAuthority.sharedAnswerOf`, which is the same function.
+     *
+     * The caches below are keyed on the authority OBJECT, and every proof mints
+     * a fresh one, so they answer a proof's own repeats and nothing else. That
+     * is the difference between a walk that runs once per question and one that
+     * runs once per (proof, question): a live three.js profile counted 11,363,007
+     * seeded-origin solvers built from zero, and charged the resulting Tarjan
+     * walk 35% of self time, with this walk the largest named caller.
+     *
+     * Optional because the answer only depends on the asking proof through its
+     * parks and its key functions, which is a property of the authorities this
+     * compiler builds rather than of the interface; a caller that cannot promise
+     * it (the tests) simply omits it and keeps the per-authority behaviour.
+     */
+    readonly sharedAnswerOf?: <T>(identity: string, compute: () => T | null, shareable?: (value: T | null) => boolean) => SharedProvenanceAnswer<T>;
+}
+export declare const exactSourceConstructionOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, call: ts.NewExpression) => SourceConstructionFact | null;
+export declare const exactClassAllocationOriginsOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, expression: ts.Expression, authority: ClassAllocationAuthority) => ExactClassAllocationOrigins | null;
+/**
+ * The value a constructor-function member's own `this.<key> = <value>`
+ * declares, or null when the declaration is not that shape or does not sit
+ * inside a source constructor function.
+ *
+ * Three's pre-class renderer factories declare every member this way:
+ * `function WebGLTextures( _gl, ... ) { function setTexture2D( texture, slot
+ * ) { ... } this.setTexture2D = setTexture2D }`. TypeScript files such an
+ * assignment's `this.<key>` as the property's OWN declaration -- there is no
+ * `MethodDeclaration` to find -- so the former class-only forwarding resolver refused
+ * every call through the whole factory family before this recognized the
+ * shape at all. Requiring the enclosing function to be `isConstructorFunction`
+ * keeps an ordinary assignment to some unrelated object's property
+ * (`obj.setSize = ...` where `obj` is not `this` of a source constructor) out
+ * of this arm entirely -- that shape is a class-family question this proof
+ * does not otherwise ask, and is not what "this member's own declaration" is
+ * supposed to mean.
+ */
+export declare const constructorFunctionMemberAssignment: (declaration: ts.Declaration) => {
+    readonly value: ts.Expression;
+} | null;
+export interface ClosedConstructorForwardingTarget {
+    readonly body: ts.ConstructorDeclaration;
+    readonly parameters: readonly ts.ParameterDeclaration[];
+}
+/** An ordinary argument entering a source class constructor reaches its
+ * explicit formal slots. Default derived constructors forward the same slots
+ * to their base. Unknown constructor identities, replacement returns and
+ * arguments/rest aliases remain outside this closed forwarding proof. */
+export declare const closedConstructorForwardingTargetsOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, call: ts.CallExpression | ts.NewExpression, argumentsUsesAt: (declaration: ts.SignatureDeclaration) => readonly ts.Identifier[] | undefined) => readonly ClosedConstructorForwardingTarget[] | null;