@scriptc/compiler 0.4.6 → 0.4.8

package/dist/frontend/lowering/generic-functions.js

@@ -1,5 +1,5 @@
 import { shapeOverlayAnnotated } from "../shape-inference/index.js";
-import { documentedParameter } from "./call-signatures.js";
+import { documentedParameter, generatorParamsBindAtCall } from "./call-signatures.js";
 import { staticNameBindings } from "./static-function-names.js";
 import { positionTag } from "./structural-positions.js";
 import { keyedHelperName } from "./stable-names.js";
@@ -8,6 +8,7 @@ import { heritageElementTarget, isHeritageTypeReference } from "../heritage-elem
 import { bodyReadsArguments } from "../arguments-usage.js";
 import { BOOL, DYN, STRING, VOID, isUnitType, typeEquals, } from "../../ir/ir.js";
 import { helperLoc, nodeThrowExpr } from "../../ir/build.js";
+import { unsupportedDiag } from "../../diagnostics/diagnostic.js";
 import { isJsSourceFile, locOf } from "../program.js";
 import { typeKey } from "../type-mapper.js";
 import { functionCanReturnUndefined } from "../function-completion.js";
@@ -22,6 +23,7 @@ import { isVarDeclared, jsBindingHasOpenWrites } from "./lower-stmts.js";
 import { paramShapes, generatorMeta, funcTypeFromParamShapes, } from "./call-signatures.js";
 import { fenceGenericSignatureResult, blockBodyOf, resolveInferredReturn, appendImplicitUndefinedReturn, hasExplicitJsDocReturn, promiseCarriesDyn, } from "./function-returns.js";
 import { bindingNeverReassigned, stripValueWrappers } from "./binding-analysis.js";
+import { declareContextLocal } from "./function-context.js";
 import { extendInstantiationPath, MAX_INSTANTIATION_RECURSION, } from "./instantiation-path.js";
 /** Defaults bind during inference; collection only resolves symbols in
  * declaration order and preserves each declaration form's diagnostic. */
@@ -91,6 +93,45 @@ export function lowerGenericCall(lowerer, expr, info) {
         ? implicitCallInstance(lowerer, expr, info)
         : genericCallInstance(lowerer, expr, info);
     const args = lowerer.completeArgs(expr.arguments.nodes, instance.params, loc, expr);
+    if (info.captureMode === "env") {
+        // The environment form: a closure over this call site's boxes of the
+        // captured bindings (resolveKey threads them through any closures in
+        // between and boxes the origin), called at once. Arguments evaluate
+        // after the callee, as in JavaScript; building the closure only reads
+        // the boxes.
+        if (instance.params.some((p) => p.mode === "rest" || p.mode === "dynRest" || p.mode === "arguments")) {
+            lowerer.unsupported("SC1090", expr, `generic arrow/function-expression bindings with rest parameters that write the frames of their enclosing functions ('${info.baseName}')`);
+        }
+        const sources = info.captures.map((capture) => {
+            const local = lowerer.resolveKey(capture.symbol, expr);
+            if (local === null || !typeEquals(local.type, capture.type)) {
+                lowerer.unsupported("SC1090", expr, `generic arrow/function-expression bindings sharing '${capture.name}' with their enclosing function when its storage differs from its declared type ('${info.baseName}')`);
+            }
+            // An origin read from its own frame is not boxed by resolveKey; the
+            // closure needs the box (captureContextBinding's origin rule).
+            local.boxed = true;
+            return local.id;
+        });
+        const call = {
+            kind: "callValue",
+            callee: {
+                kind: "closure",
+                fnName: instance.name,
+                captures: sources,
+                type: funcTypeFromParamShapes(instance.params, instance.returnType),
+                loc,
+            },
+            args,
+            type: instance.returnType,
+            loc,
+        };
+        return guardEarlyCall(lowerer, info, expr, call);
+    }
+    // The enclosing-frame values follow the declared arguments, the order
+    // the instance takes them in (lowerGenericInstance).
+    for (const capture of info.captures ?? []) {
+        args.push(lowerer.lowerExprExpecting(capture.nameNode, capture.type));
+    }
     const call = {
         kind: "call",
         callee: instance.name,
@@ -98,7 +139,7 @@ export function lowerGenericCall(lowerer, expr, info) {
         type: instance.returnType,
         loc,
     };
-    return guardEarlyBindingCall(lowerer, info, expr, call);
+    return guardEarlyCall(lowerer, info, expr, call);
 }
 /** The instance a CALL of a generic function-like names: resolved
  * signature → mapped param shapes/return → interned instance. Shared by
@@ -903,7 +944,10 @@ export function lowerGenericInstance(lowerer, info, inst) {
     let bodyReturn = isGenerator
         ? lowerer.genBodyReturnType(inst.returnType)
         : lowerer.bodyReturnType(isAsync, inst.returnType);
-    const fnCtx = newFnCtx(false, null, null, bodyReturn);
+    // The environment form lowers as a LIFTED function: its captures arrive
+    // in the closure environment, never as parameters.
+    const envForm = info.captureMode === "env";
+    const fnCtx = newFnCtx(envForm, null, null, bodyReturn);
     fnCtx.isAsync = isAsync;
     // Instances lower on demand, on top of whichever caller reached them.
     fnCtx.thisBoundary = true;
@@ -943,11 +987,43 @@ export function lowerGenericInstance(lowerer, info, inst) {
             const thisLocal = lowerer.declareThis(thisType);
             params.push({ localId: thisLocal.id, name: "this", type: thisType });
         }
+        // Environment form: one boxed capture entry per captured binding, in
+        // FrameCapture order (the call sites' closure caps[] order), keyed by
+        // the binding's symbol so the body (parameter defaults included)
+        // reads and writes the shared box. Pre-registering them also keeps
+        // resolution from walking past this instance's frame.
+        if (envForm) {
+            for (const capture of info.captures) {
+                const entry = declareContextLocal(fnCtx, capture.name, capture.type, capture.reassigned, undefined, undefined);
+                entry.boxed = true;
+                fnCtx.captureBySymbol.set(capture.symbol, entry);
+                fnCtx.captures.push({ localId: entry.id, name: entry.name, type: entry.type });
+            }
+        }
+        // The enclosing-frame values travel as TRAILING parameters, after the
+        // declared ones: a call lowers its arguments first (JavaScript's
+        // order), then reads the captures. Binding each local to the captured
+        // symbol is what lets the body resolve the reference; the locals are
+        // bound before the declared parameters so that a default initializer
+        // reading a capture resolves it too.
+        const captureParams = [];
+        for (const capture of envForm ? [] : (info.captures ?? [])) {
+            const local = lowerer.declareLocal(capture.nameNode, capture.name, capture.type, false);
+            captureParams.push({ localId: local.id, name: capture.name, type: capture.type });
+        }
         // Default-param initializers lower per instance, with the bindings
         // threaded — a default mentioning T resolves like any body expression.
         const declared = lowerer.declareParams(decl.parameters.nodes, inst.params);
-        params.push(...declared.params);
-        const body = [...receiverInit, ...declared.prologue];
+        params.push(...declared.params, ...captureParams);
+        // See lowerFunction: a generator binds its parameters at the CALL
+        // exactly when that is observable. The receiver materialization
+        // (`staticReceiver`) is call machinery, not parameter binding.
+        const bindsAtCall = isGenerator && declared.prologue.length > 0 && generatorParamsBindAtCall(decl);
+        const body = [
+            ...receiverInit,
+            ...declared.prologue,
+            ...(bindsAtCall ? [{ kind: "genBindBarrier", loc: locOf(decl) }] : []),
+        ];
         const bodyBlock = blockBodyOf(decl);
         if (bodyBlock) {
             body.push(...lowerer.lowerStmts(bodyBlock.statements.nodes));
@@ -1002,13 +1078,14 @@ export function lowerGenericInstance(lowerer, info, inst) {
             params,
             returnType: bodyReturn,
             locals: lowerer.ctx.locals,
+            ...(envForm ? { captures: fnCtx.captures } : {}),
             body,
             loc: locOf(decl),
         };
         if (isAsync)
             fn.async = true;
         if (fnCtx.generator)
-            fn.generator = fnCtx.generator;
+            fn.generator = bindsAtCall ? { ...fnCtx.generator, bindAtCall: true } : fnCtx.generator;
         return fn;
     }
     finally {
@@ -1026,6 +1103,37 @@ export function lowerGenericInstance(lowerer, info, inst) {
             lowerer.erasingDepth--;
     }
 }
+/** Records that `instance` is one of `info`'s value instances (see
+ * `valueInstances`). Written as its own statements rather than
+ * `(x ??= new Set()).add(...)`: the self-hosted frontend fences a Set method
+ * call on a non-Set receiver, and this compiler compiles its own source. */
+function noteValueInstance(info, instance) {
+    let instances = info.valueInstances;
+    if (instances === undefined) {
+        instances = new Set();
+        info.valueInstances = instances;
+    }
+    instances.add(instance);
+}
+/** Records the instance a pinned binding holds (`const f: Fn = ident`,
+ * `const i = identity<number>`) under its declaration, so an identity
+ * comparison between two bindings compares the closures they name
+ * (checkGenericIdentityPins). */
+function notePinnedBinding(lowerer, ref, info, instance) {
+    let node = ref;
+    if (node.parent !== undefined &&
+        ts.isPropertyAccessExpression(node.parent) &&
+        node.parent.name === node)
+        node = node.parent;
+    while (node.parent !== undefined && ts.isParenthesizedExpression(node.parent))
+        node = node.parent;
+    const parent = node.parent;
+    if (parent === undefined || !ts.isVariableDeclaration(parent) || parent.initializer !== node)
+        return;
+    if (!ts.isIdentifier(parent.name))
+        return;
+    lowerer.pinnedValueInstances.set(parent, { info, instance });
+}
 /** A generic function taken as a VALUE, monomorphized by flow. A function
  * value needs ONE concrete signature; tsc pins one at exactly two
  * reference shapes — an instantiation EXPRESSION (`identity<number>`,
@@ -1046,10 +1154,18 @@ export function lowerGenericFnValue(lowerer, ref, info) {
     // closure per function, so `f === f` holds like any declaration).
     if (info.implicitParams) {
         const inst = implicitDefaultInstance(lowerer, ref, info);
+        noteValueInstance(info, inst.name);
+        notePinnedBinding(lowerer, ref, info, inst.name);
         const funcType = funcTypeFromParamShapes(inst.params, inst.returnType);
         lowerer.requireExactArityValue(ref, ref, inst.params, funcType);
         lowerer.noteEdge(inst.name);
-        return { kind: "closure", fnName: inst.name, captures: [], type: funcType, loc };
+        return aliasTdzGuard(lowerer, ref, {
+            kind: "closure",
+            fnName: inst.name,
+            captures: [],
+            type: funcType,
+            loc,
+        });
     }
     // Each call of the enclosing function makes a new function object for a
     // binding declared inside it (`make() !== make()` when make returns
@@ -1087,9 +1203,110 @@ export function lowerGenericFnValue(lowerer, ref, info) {
                 target = callable[0][0];
         }
     }
-    if (!target)
-        fenceUnpinned();
-    return guardEarlyBindingValue(lowerer, info, ref, pinnedGenericClosure(lowerer, ref, info, target, fenceUnpinned));
+    if (!target) {
+        target = identityComparisonPin(lowerer, ref);
+        if (target)
+            lowerer.genericIdentityPins.push({ info, node: ref });
+    }
+    // No concrete pin, or a pin that keeps its own type parameters (the slot
+    // type is the generic signature itself, as a record field of a generic
+    // method or a generic result flows): the value is the ERASED instance —
+    // the one function JavaScript runs for every type argument — and each
+    // instantiating call converts its arguments in and its result out
+    // (lower-calls.ts, genericValueCall). `f === f` still holds: the erased
+    // instance is one interned closure per declaration.
+    if (!target || target.getTypeParameters().length > 0) {
+        return aliasTdzGuard(lowerer, ref, guardEarlyBindingValue(lowerer, info, ref, erasedGenericFnValue(lowerer, ref, info)));
+    }
+    return aliasTdzGuard(lowerer, ref, guardEarlyBindingValue(lowerer, info, ref, pinnedGenericClosure(lowerer, ref, info, target, fenceUnpinned)));
+}
+/** A read of a generic ALIAS binding (`const h = id`) that can run before
+ * the alias's declaration: the alias has no binding storage, so JavaScript
+ * reaches its temporal dead zone through the flag the declaration sets —
+ * the read throws before it hands out the function. Reads that can only
+ * run after the declaration stay direct. A `var` alias reads `undefined`
+ * there, which is no function value to hand out, so that read is
+ * refused. */
+function aliasTdzGuard(lowerer, ref, value) {
+    const presence = earlyAliasPresence(lowerer, ref);
+    if (presence === undefined)
+        return value;
+    if (!presence.lexical)
+        lowerer.unsupported("SC1090", ref, `generic 'var' aliases read as values before their declaration runs (Node reads undefined there; declare '${presence.name}' with const)`);
+    const loc = value.loc;
+    const flag = { kind: "varRef", localId: presence.flagId, type: BOOL, loc };
+    return {
+        kind: "seqExpr",
+        stmts: [tdzCheck(flag, presence.name, loc)],
+        result: value,
+        type: value.type,
+        loc,
+    };
+}
+/** The flag of a generic ALIAS binding that `node`, a reference to it,
+ * can reach before its declaration runs — undefined when the node names no
+ * alias, or names one whose declaration has already run. */
+function earlyAliasPresence(lowerer, node) {
+    const ident = ts.isIdentifier(node)
+        ? node
+        : ts.isExpressionWithTypeArguments(node) && ts.isIdentifier(node.expression)
+            ? node.expression
+            : undefined;
+    if (ident === undefined)
+        return undefined;
+    const symbol = lowerer.resolveValueSymbol(ident);
+    const presence = symbol === null ? undefined : lowerer.genericAliasPresence.get(symbol);
+    if (presence === undefined)
+        return undefined;
+    if (useRunsAfter(lowerer, presence.decl, ident, presence.ordering, new Set()))
+        return undefined;
+    return presence;
+}
+/** The value of a generic declaration read where no concrete instantiation
+ * pins it: the declaration's erased instance's closure — the ONE function
+ * JavaScript has, whose parameters and result are `unknown`, so arguments
+ * entering it box (records, arrays, maps and sets as live capsules;
+ * identity preserved) and results leaving it are checked against the
+ * instantiated signature at the call. */
+function erasedGenericFnValue(lowerer, ref, info) {
+    const loc = locOf(ref);
+    const inst = erasedGenericInstance(lowerer, ref, info);
+    const funcType = funcTypeFromParamShapes(inst.params, inst.returnType);
+    lowerer.requireExactArityValue(ref, ref, inst.params, funcType);
+    lowerer.noteEdge(inst.name);
+    return { kind: "closure", fnName: inst.name, captures: [], type: funcType, loc };
+}
+/** The pinning signature of a generic declaration compared by identity
+ * (`held === ident`, `held !== ident`, and the loose forms): the other
+ * operand's one concrete call signature. A held value of that type that is
+ * this declaration is its instance at that signature, whose interned
+ * closure is the one this reference names, so the comparison answers as
+ * in JavaScript, provided the program holds the declaration at that one
+ * signature only (checkGenericIdentityPins). Null when the other operand
+ * has no single concrete call signature (another generic value, a union of
+ * callables, a non-function). */
+function identityComparisonPin(lowerer, ref) {
+    let operand = ref;
+    if (ref.parent !== undefined &&
+        ts.isPropertyAccessExpression(ref.parent) &&
+        ref.parent.name === ref)
+        operand = ref.parent;
+    while (operand.parent !== undefined && ts.isParenthesizedExpression(operand.parent))
+        operand = operand.parent;
+    const bin = operand.parent;
+    if (bin === undefined || !ts.isBinaryExpression(bin))
+        return null;
+    const op = bin.operatorToken.kind;
+    if (op !== ts.SyntaxKind.EqualsEqualsEqualsToken &&
+        op !== ts.SyntaxKind.ExclamationEqualsEqualsToken &&
+        op !== ts.SyntaxKind.EqualsEqualsToken &&
+        op !== ts.SyntaxKind.ExclamationEqualsToken)
+        return null;
+    const other = bin.left === operand ? bin.right : bin.left;
+    const sigs = lowerer.checker.getCallSignatures(lowerer.typeOf(other));
+    if (sigs.length !== 1 || sigs[0].getTypeParameters()?.length)
+        return null;
+    return sigs[0];
 }
 /** The value a generic binding declared inside a function stores when a
  * nested function read it before the declaration lowered (`const read =
@@ -1173,6 +1390,8 @@ function pinnedGenericClosure(lowerer, ref, info, target, fenceUnpinned) {
     if (info.typeParams.some((tp) => !bindings.get(tp)))
         fenceUnpinned();
     const inst = genericValueInstance(lowerer, ref, info, bindings);
+    noteValueInstance(info, inst.name);
+    notePinnedBinding(lowerer, ref, info, inst.name);
     // The value's type is the completed ABI signature. Typed rest keeps its
     // packed-array slot; dynRest stays hidden behind the rest marker.
     const funcType = funcTypeFromParamShapes(inst.params, inst.returnType);
@@ -1213,12 +1432,288 @@ export function erasedGenericInstance(lowerer, blame, info) {
     try {
         const instance = genericValueInstance(lowerer, blame, info, new Map(info.typeParams.map((tp) => [tp, DYN])));
         instance.erased = true;
+        noteValueInstance(info, instance.name);
         return instance;
     }
     finally {
         lowerer.erasingDepth--;
     }
 }
+/** After every body lowered: an identity comparison of a generic
+ * declaration is exact only when the program holds the declaration as one
+ * function object. Otherwise a held value may be another instance's
+ * closure, where JavaScript has one function, so the comparison is
+ * refused instead of answering false. */
+export function checkGenericIdentityPins(lowerer) {
+    if (lowerer.genericIdentityCheckDone)
+        return;
+    lowerer.genericIdentityCheckDone = true;
+    const seen = new Map();
+    const report = (info, node, dynamic) => {
+        let infos = seen.get(node);
+        if (infos === undefined)
+            seen.set(node, (infos = new Set()));
+        if (infos.has(info))
+            return;
+        infos.add(info);
+        const held = info.valueInstances?.size ?? 0;
+        if (held <= 1)
+            return;
+        const through = dynamic ? " through a dynamic value" : "";
+        lowerer.pushDiag(unsupportedDiag("SC1090", locOf(node), `comparing the generic function '${info.baseName}' by identity${through} while the program holds it at ${held} different signatures (each is a separate compiled function object; JavaScript has one) — compare against a value pinned once, or hold '${info.baseName}' at a single signature`));
+    };
+    for (const { info, node } of lowerer.genericIdentityPins)
+        report(info, node, false);
+    // Dynamic comparisons resolve their provenance only when some declaration
+    // is held at more than one signature: the symbol lookups are the
+    // expensive part, and every other program answers them all at one
+    // instance. Recorded at lowering, resolved here so the pins' instance
+    // sets are complete.
+    let ambiguous = false;
+    for (const info of lowerer.genericFnsBySymbol.values()) {
+        if ((info.valueInstances?.size ?? 0) > 1) {
+            ambiguous = true;
+            break;
+        }
+    }
+    if (!ambiguous)
+        return;
+    for (const { node, left, right } of lowerer.dynIdentityComparisons) {
+        for (const operand of [left, right]) {
+            const info = genericDeclarationBehindValue(lowerer, operand);
+            if (info)
+                report(info, node, true);
+        }
+    }
+    // A typed function-vs-function comparison (`g === h`) whose two operands
+    // are pins of ONE declaration at different signatures: the closures the
+    // operands name are different function objects, so the pointer compare
+    // answers false while JavaScript has one function — a silent divergence.
+    for (const { node, left, right, leftInstance, rightInstance, } of lowerer.pinnedIdentityComparisons) {
+        const leftPin = pinnedInstanceBehind(lowerer, left, leftInstance);
+        if (leftPin === null)
+            continue;
+        const rightPin = pinnedInstanceBehind(lowerer, right, rightInstance);
+        if (rightPin === null || rightPin.info !== leftPin.info)
+            continue;
+        if (rightPin.instance === leftPin.instance)
+            continue;
+        let infos = seen.get(node);
+        if (infos === undefined)
+            seen.set(node, (infos = new Set()));
+        if (infos.has(leftPin.info))
+            continue;
+        infos.add(leftPin.info);
+        lowerer.pushDiag(unsupportedDiag("SC1090", locOf(node), `comparing two values of the generic function '${leftPin.info.baseName}' pinned at different signatures by identity (each pinned signature is a separate compiled function object; JavaScript has one) — hold '${leftPin.info.baseName}' at a single signature, or compare values pinned to the same signature`));
+    }
+}
+/** The value instance an identity operand names: the closure name it
+ * lowered to when it is an inline pin (`identity<number>`), else the
+ * binding it reads, resolved through casts and aliasing bindings. Null for
+ * a value with no recorded pin (a call result, a parameter, a binding the
+ * program rewrites). */
+function pinnedInstanceBehind(lowerer, node, directInstance) {
+    let current = node;
+    const seen = new Set();
+    while (current !== undefined && !seen.has(current)) {
+        seen.add(current);
+        if (ts.isParenthesizedExpression(current) ||
+            ts.isAsExpression(current) ||
+            ts.isSatisfiesExpression(current) ||
+            ts.isNonNullExpression(current) ||
+            ts.isExpressionWithTypeArguments(current)) {
+            current = current.expression;
+            continue;
+        }
+        if (!ts.isIdentifier(current) && !ts.isPropertyAccessExpression(current))
+            return null;
+        const symbol = lowerer.checker.getSymbolAtLocation(ts.isPropertyAccessExpression(current) ? current.name : current);
+        if (symbol === undefined)
+            return null;
+        const info = lowerer.genericFnsBySymbol.get(symbol);
+        if (info !== undefined) {
+            // The bare declaration itself: a pin only where the comparison
+            // names it directly (the direct rule covers that shape).
+            return directInstance === undefined ? null : { info, instance: directInstance };
+        }
+        const decl = symbol.valueDeclaration ?? symbol.declarations?.[0];
+        if (decl === undefined)
+            return null;
+        // A binding the program later rewrites may hold another function at
+        // the comparison: resolve it, and alias it through its initializer,
+        // only where it is never written.
+        if (!holdsItsInitializer(lowerer, decl))
+            return null;
+        const recorded = lowerer.pinnedValueInstances.get(decl);
+        if (recorded !== undefined)
+            return recorded;
+        current = decl
+            .initializer;
+    }
+    return null;
+}
+/** Whether `decl` is a variable or property that keeps the value it starts
+ * with: a variable with an identifier name that nothing writes, or a
+ * readonly property its class never assigns (a constructor can). A
+ * parameter's default is not its value: a call can pass any function for
+ * it. */
+function holdsItsInitializer(lowerer, decl) {
+    if (ts.isPropertyDeclaration(decl))
+        return ((ts.getCombinedModifierFlags(decl) & ts.ModifierFlags.Readonly) !== 0 &&
+            !classWritesField(decl));
+    if (!ts.isVariableDeclaration(decl) || !ts.isIdentifier(decl.name))
+        return false;
+    const binding = lowerer.checker.getSymbolAtLocation(decl.name);
+    return binding !== undefined && bindingNeverReassigned(lowerer, binding, decl);
+}
+/** Whether the class that declares `field` assigns a property of its name
+ * anywhere in its body: a readonly field can still be assigned in a
+ * constructor or a static block. Any receiver counts, which only
+ * over-approximates. */
+function classWritesField(field) {
+    const name = field.name;
+    if (!ts.isIdentifier(name) && !ts.isStringLiteral(name))
+        return true;
+    const text = name.text;
+    const targets = (target) => {
+        let e = target;
+        while (ts.isParenthesizedExpression(e))
+            e = e.expression;
+        if (ts.isPropertyAccessExpression(e))
+            return e.name.text === text;
+        if (ts.isElementAccessExpression(e))
+            return !ts.isStringLiteralLike(e.argumentExpression) || e.argumentExpression.text === text;
+        return false;
+    };
+    let written = false;
+    const visit = (node) => {
+        if (written)
+            return;
+        if (ts.isBinaryExpression(node) &&
+            node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+            node.operatorToken.kind <= ts.SyntaxKind.LastAssignment &&
+            targets(node.left))
+            written = true;
+        else if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+            (node.operator === ts.SyntaxKind.PlusPlusToken ||
+                node.operator === ts.SyntaxKind.MinusMinusToken) &&
+            targets(node.operand))
+            written = true;
+        else
+            ts.forEachChild(node, visit);
+    };
+    if (field.parent !== undefined)
+        visit(field.parent);
+    return written;
+}
+/** The generic declaration whose value instance an expression names, when
+ * the expression is a binding initialized (directly, or through casts,
+ * aliasing bindings and property initializers) from that declaration. Used
+ * where a comparison reads the value through `unknown`/`any`, so the
+ * declaration is not syntactically at the compared site. */
+export function genericDeclarationBehindValue(lowerer, node, 
+// A comparison answers for the VALUE the binding holds at that point, so
+// only a binding the program cannot reassign may stand for the
+// declaration its initializer reads.
+requireConst = false) {
+    let current = node;
+    const seen = new Set();
+    while (current !== undefined && !seen.has(current)) {
+        seen.add(current);
+        if (ts.isParenthesizedExpression(current) ||
+            ts.isAsExpression(current) ||
+            ts.isSatisfiesExpression(current) ||
+            ts.isNonNullExpression(current)) {
+            current = current.expression;
+            continue;
+        }
+        // An instantiation expression (`identity<number>`) names the
+        // declaration its type arguments apply to.
+        if (ts.isExpressionWithTypeArguments(current)) {
+            current = current.expression;
+            continue;
+        }
+        if (!ts.isIdentifier(current) && !ts.isPropertyAccessExpression(current))
+            return null;
+        const symbol = lowerer.checker.getSymbolAtLocation(ts.isPropertyAccessExpression(current) ? current.name : current);
+        if (symbol === undefined)
+            return null;
+        const info = lowerer.genericFnsBySymbol.get(symbol);
+        if (info !== undefined)
+            return info;
+        const decl = symbol.valueDeclaration ?? symbol.declarations?.[0];
+        if (decl === undefined)
+            return null;
+        if (!ts.isVariableDeclaration(decl) && !ts.isPropertyDeclaration(decl) && !ts.isParameter(decl))
+            return null;
+        if (requireConst &&
+            (!ts.isVariableDeclaration(decl) ||
+                !ts.isVariableDeclarationList(decl.parent) ||
+                (decl.parent.flags & ts.NodeFlags.Const) === 0))
+            return null;
+        current = decl.initializer;
+    }
+    return null;
+}
+/** An identity comparison at the dynamic boundary (`unknown`/`any`
+ * operands): when either operand reads a generic declaration's value
+ * instance, the comparison is exact only while the program holds that
+ * declaration at one signature (checkGenericIdentityPins). */
+export function noteDynamicIdentityComparison(lowerer, node, left, right) {
+    // A function compared with a string, number, boolean, bigint or symbol
+    // is unequal whichever instance it is, as in JavaScript.
+    if (isPrimitiveTyped(lowerer, left) || isPrimitiveTyped(lowerer, right))
+        return;
+    // The only work done while lowering. No instance count can gate this:
+    // a value reference's instance is interned when its binding settles,
+    // which can be later than the comparison that reads it, so the notes
+    // are resolved at the end of lowering, when every instance is known.
+    if (mightNameBinding(left) || mightNameBinding(right))
+        lowerer.dynIdentityComparisons.push({ node, left, right });
+}
+/** An identity comparison of two function-typed values (`g === h`), where
+ * either side may name a value instance of a generic declaration: two pins
+ * of one declaration at different signatures are separate compiled
+ * closures, so the pointer compare would answer false where JavaScript
+ * answers true (one function object). Resolved by
+ * checkGenericIdentityPins, where every instance is known. */
+export function notePinnedIdentityComparison(lowerer, node, left, right, leftInstance, rightInstance) {
+    if (mightNameBinding(left) || mightNameBinding(right))
+        lowerer.pinnedIdentityComparisons.push({ node, left, right, leftInstance, rightInstance });
+}
+const PRIMITIVE_TYPE_FLAGS = ts.TypeFlags.StringLike |
+    ts.TypeFlags.NumberLike |
+    ts.TypeFlags.BooleanLike |
+    ts.TypeFlags.BigIntLike |
+    ts.TypeFlags.ESSymbolLike;
+/** Whether the checker types `node` as a string, number, boolean, bigint or
+ * symbol (a union with any other member is not). */
+function isPrimitiveTyped(lowerer, node) {
+    return (lowerer.typeOf(node).flags & PRIMITIVE_TYPE_FLAGS) !== 0;
+}
+/** Whether an expression could name a binding at all — an identifier or a
+ * property access, through parentheses and casts. A literal, a call, an
+ * operator expression: nothing to resolve. */
+function mightNameBinding(node) {
+    let current = node;
+    for (let hops = 0; hops < 16 && current !== undefined; hops++) {
+        if (ts.isIdentifier(current) || ts.isPropertyAccessExpression(current))
+            return true;
+        if (ts.isExpressionWithTypeArguments(current)) {
+            current = current.expression;
+            continue;
+        }
+        if (ts.isParenthesizedExpression(current) ||
+            ts.isAsExpression(current) ||
+            ts.isNonNullExpression(current) ||
+            ts.isSatisfiesExpression(current)) {
+            current = current.expression;
+            continue;
+        }
+        return false;
+    }
+    return false;
+}
 /** The instance a pinned VALUE reference names: the declaration's modes
  * over the DECLARED types mapped under the bindings (mapType's resolver
  * substitutes — the instance-body trick), which is the same result the
@@ -2173,6 +2668,200 @@ function capturesEnclosingFrame(lowerer, fn, decl, scope) {
     scan(scope);
     return captures;
 }
+/** Whether a captured value's type can change between two instantiations of
+ * the enclosing generic scopes: true when a type parameter reaches the type
+ * (directly, through a union, or as a type argument), and true for the shapes
+ * whose contents the walk cannot name — a mapped type, an inferred object
+ * literal, a signature — so those keep the fence they had. */
+function typeVariesWithEnclosingTypeParameters(lowerer, type) {
+    const seen = new Set();
+    const walk = (part, depth) => {
+        if ((part.flags & ts.TypeFlags.TypeParameter) !== 0)
+            return true;
+        if (depth > 8)
+            return true;
+        if (seen.has(part))
+            return false;
+        seen.add(part);
+        if (part.isUnionType())
+            return ts.constituentTypes(part).some((p) => walk(p, depth + 1));
+        if ((part.flags & ts.TypeFlags.Intersection) !== 0)
+            return ts.constituentTypes(part).some((p) => walk(p, depth + 1));
+        if (part.getAliasTypeArguments().some((p) => walk(p, depth + 1)))
+            return true;
+        // An indexed access, a conditional, a substitution or an index type is
+        // resolved from a source type this walk would have to reduce.
+        if ((part.flags &
+            (ts.TypeFlags.Index |
+                ts.TypeFlags.IndexedAccess |
+                ts.TypeFlags.Conditional |
+                ts.TypeFlags.Substitution)) !==
+            0)
+            return true;
+        if ((part.flags & ts.TypeFlags.Object) === 0)
+            return false;
+        const flags = part.objectFlags;
+        // A reference names its type arguments — a class instance, an interface,
+        // an array, a tuple.
+        if ((flags & ts.ObjectFlags.Reference) !== 0)
+            return lowerer.checker
+                .getTypeArguments(part)
+                .some((p) => walk(p, depth + 1));
+        // A mapped type reduces to its source's keys and type arguments.
+        if ((flags & ts.ObjectFlags.Mapped) !== 0)
+            return true;
+        // An index signature names its value type directly, and its key is never
+        // a type parameter: `{ [key: string]: T }` varies exactly as `T` does,
+        // whether the type is an object literal's or a named one's.
+        for (const info of lowerer.checker.getIndexInfosOfType(part)) {
+            if (walk(info.type, depth + 1))
+                return true;
+        }
+        // A nominal instance whose type arguments the reference test above did
+        // not see carries none to miss.
+        if ((flags & ts.ObjectFlags.ClassOrInterface) !== 0)
+            return false;
+        // An inferred object literal or a type alias's object type names its
+        // members instead of type arguments: read them, with a bounded width so
+        // a wide type cannot make this walk expensive.
+        let budget = 0;
+        for (const prop of lowerer.checker.getPropertiesOfType(part)) {
+            if (++budget > 64)
+                return true;
+            if (walk(lowerer.checker.getTypeOfSymbol(prop), depth + 1))
+                return true;
+        }
+        for (const sig of [
+            ...lowerer.checker.getCallSignatures(part),
+            ...lowerer.checker.getConstructSignatures(part),
+        ]) {
+            for (const param of sig.getParameters()) {
+                if (walk(lowerer.checker.getTypeOfSymbol(param), depth + 1))
+                    return true;
+            }
+            if (walk(lowerer.checker.getReturnTypeOfSignature(sig), depth + 1))
+                return true;
+        }
+        return false;
+    };
+    return walk(type, 0);
+}
+/** The enclosing-frame VALUES `fn`, bound by `decl`, reads — in first-use
+ * order, the order the instances take them as trailing parameters. The
+ * shape is the one the instance body resolves: a binding declared by an
+ * enclosing function (a local, a parameter, a local function or class).
+ *
+ * Module-scope declarations and the binding itself are reachable from the
+ * module functions the instances compile to, so they are not captures; nor
+ * are type-only declarations, whose mapping is static. `this`, `super`,
+ * `arguments`, `new.target`, and an enclosing generic's type parameter
+ * have no value a parameter can stand in for and stay fenced. A
+ * reassigned binding is shared through the environment form instead of
+ * copied. */
+function enclosingFrameCaptures(lowerer, fn, decl, scope, name) {
+    const file = ts.getSourceFileOfNode(decl);
+    const self = lowerer.checker.getSymbolAtLocation(decl.name);
+    const frameFence = () => lowerer.unsupported("SC1090", fn, `generic arrow/function-expression bindings that use the frames of their enclosing functions (the compiled instantiations of '${name}' are module functions and cannot capture its locals, parameters, type parameters or 'this' — pass them as arguments, or declare the binding at module scope)`);
+    const captures = [];
+    const seen = new Set();
+    const scan = (n) => {
+        if (n.kind === ts.SyntaxKind.ThisKeyword ||
+            n.kind === ts.SyntaxKind.SuperKeyword ||
+            ts.isMetaProperty(n)) {
+            // Arrow bodies see the ENCLOSING this; function expressions
+            // rebind their own — but a bare `this` there is untyped JS
+            // dynamism either way. Reject both, cheaply and soundly.
+            frameFence();
+        }
+        if (ts.isIdentifier(n)) {
+            const s = lowerer.checker.getSymbolAtLocation(n);
+            if (s === undefined) {
+                if (n.text === "arguments")
+                    frameFence();
+            }
+            else if (s !== self && !seen.has(s)) {
+                for (const d of s.declarations) {
+                    if (ts.getSourceFileOfNode(d) !== file || (d.pos >= fn.pos && d.end <= fn.end))
+                        continue;
+                    let enclosing = false;
+                    for (let p = d.parent; p !== undefined && !ts.isSourceFile(p); p = p.parent) {
+                        if (ts.isFunctionLike(p)) {
+                            enclosing = true;
+                            break;
+                        }
+                    }
+                    if (!enclosing)
+                        continue;
+                    // A type parameter (of the enclosing function or class) keys
+                    // the enclosing instantiation; the instance would need that
+                    // frame's type arguments, which this binding cannot carry.
+                    if ((s.flags & ts.SymbolFlags.TypeParameter) !== 0)
+                        frameFence();
+                    // Type-only declarations cost no runtime slot.
+                    if ((s.flags & ts.SymbolFlags.Value) === 0)
+                        break;
+                    // A trailing-parameter COPY is exact only while the original
+                    // never changes; a binding written anywhere in the file puts the
+                    // whole binding in the environment form (GenericFnInfo.captureMode).
+                    const reassigned = !bindingNeverReassigned(lowerer, s, d);
+                    // ...and exact only once the original is INITIALIZED. A capture
+                    // declared after the binding could be read from a call that runs
+                    // before its initializer — a temporal dead zone JavaScript would
+                    // throw on. Declared before, the copy is always the initialized
+                    // value: reaching the binding's own declaration ran it.
+                    if (d.pos > decl.pos)
+                        frameFence();
+                    // The declaration's own identifier (a binding element's for a
+                    // destructured name): lowering it resolves the SYMBOL, so the
+                    // instance body reads the parameter we declare for it.
+                    const declaredName = d.name;
+                    const nameNode = declaredName !== undefined && ts.isIdentifier(declaredName) ? declaredName : d;
+                    const type = lowerer.irTypeOf(nameNode);
+                    captures.push({
+                        symbol: s,
+                        nameNode,
+                        name: ts.isIdentifier(nameNode) ? nameNode.text : ts.symbolName(s),
+                        type,
+                        reassigned,
+                    });
+                    seen.add(s);
+                    break;
+                }
+            }
+        }
+        ts.forEachChild(n, scan);
+    };
+    scan(scope);
+    // A capture's type is fixed when the info is registered, once per
+    // binding, while an enclosing generic function or class re-lowers its
+    // frame per instantiation: the second instantiation's value would have a
+    // different type than the parameter the shared instance declares. The
+    // fence is about that TYPE, not about genericity: a capture whose type
+    // reads none of the enclosing type parameters is the same type in every
+    // instantiation, and the instance reads it exactly (the getSlot shape:
+    // a generic arrow closing over a Map and a counter inside a generic
+    // provider function).
+    if (captures.length > 0) {
+        let genericEnclosing = false;
+        for (let p = fn.parent; p && !ts.isSourceFile(p); p = p.parent) {
+            if (!ts.isFunctionLike(p) && !ts.isClassLikeDeclaration(p))
+                continue;
+            const typeParameters = p
+                .typeParameters;
+            if (typeParameters !== undefined && typeParameters.nodes.length > 0) {
+                genericEnclosing = true;
+                break;
+            }
+        }
+        if (genericEnclosing) {
+            for (const capture of captures) {
+                if (typeVariesWithEnclosingTypeParameters(lowerer, lowerer.typeOf(capture.nameNode)))
+                    frameFence();
+            }
+        }
+    }
+    return captures;
+}
 /** Registers (or returns) the GenericFnInfo of a qualifying implicit-any
  * function-value binding — implicitLocalFnNodeOf's companion, the
  * bindingGenericFnInfoOf shape: the info enters genericFnsBySymbol under
@@ -2345,14 +3034,19 @@ export function bindingGenericFnInfoOf(lowerer, decl, fnNode) {
     const name = decl.name.text;
     if (fnNode.asteriskToken)
         lowerer.unsupported("SC1071", fnNode);
-    // Inside a function, the compiled instances are module functions, so
-    // the initializer may not use the enclosing frame.
+    // Inside a function, the compiled instances are module functions: the
+    // values the initializer reads from the enclosing frame travel as
+    // trailing parameters (FrameCapture), or through a closure environment
+    // when one of them is reassigned (captureMode). `this`, `arguments` and
+    // an enclosing generic's type parameters have no value to pass and stay
+    // fenced.
     let functionScoped = false;
+    let captures;
     for (let n = decl.parent; n !== undefined && !ts.isSourceFile(n); n = n.parent) {
         if (ts.isFunctionLike(n)) {
-            if (capturesEnclosingFrame(lowerer, fnNode, decl, fnNode)) {
-                lowerer.unsupported("SC1090", fnNode, `generic arrow/function-expression bindings that use the frames of their enclosing functions (the compiled instantiations of '${name}' are module functions and cannot capture its locals, parameters, type parameters or 'this' — pass them as arguments, or declare the binding at module scope)`);
-            }
+            const found = enclosingFrameCaptures(lowerer, fnNode, decl, fnNode, name);
+            if (found.length > 0)
+                captures = found;
             functionScoped = true;
             break;
         }
@@ -2394,6 +3088,8 @@ export function bindingGenericFnInfoOf(lowerer, decl, fnNode) {
         typeParams,
         instances: new Map(),
         ...(functionScoped ? { functionScoped: true } : {}),
+        ...(captures ? { captures } : {}),
+        ...(captures?.some((capture) => capture.reassigned) ? { captureMode: "env" } : {}),
         bindingDecl: decl,
     };
     lowerer.bindingGenericFns.set(fnNode, info);
@@ -2572,8 +3268,13 @@ function guardEarlyBindingCall(lowerer, info, expr, call) {
             type: call.type,
             loc,
         };
-    // Arguments first, in order, then the check: Node evaluates them
-    // before it finds the callee is not callable.
+    return earlyUnassignedCall(lowerer, call, flag, info.baseName, loc);
+}
+/** A call whose callee is an unassigned `var` binding — or a `var` alias
+ * — before its initializer runs: arguments first, in order, then the
+ * check. Node evaluates them before it finds the callee is not
+ * callable. */
+function earlyUnassignedCall(lowerer, call, flag, name, loc) {
     const stmts = [];
     const args = call.args.map((arg) => {
         const id = `%earlyCallArg.${lowerer.ctx.locals.length}`;
@@ -2588,7 +3289,7 @@ function guardEarlyBindingCall(lowerer, info, expr, call) {
             kind: "ternary",
             cond: flag,
             then: { ...call, args },
-            else_: nodeThrowExpr(1, "", `${info.baseName} is not a function`, call.type, loc),
+            else_: nodeThrowExpr(1, "", `${name} is not a function`, call.type, loc),
             type: call.type,
             loc,
         },
@@ -2614,6 +3315,29 @@ function guardEarlyBindingValue(lowerer, info, ref, value) {
         loc,
     };
 }
+/** A call of a generic binding or ALIAS that can run before the
+ * declaration. Through an ALIAS (`h(3)`), JavaScript reads the alias first:
+ * a `let`/`const` alias is in its temporal dead zone, so the call throws
+ * before the arguments evaluate, while a `var` alias is `undefined`, so the
+ * arguments run and the call throws "is not a function" — the alias names
+ * no binding the callee could have read, so no check of the aliased
+ * binding's own flag applies. Other calls check the binding's flag. */
+function guardEarlyCall(lowerer, info, expr, call) {
+    const presence = earlyAliasPresence(lowerer, expr.expression);
+    if (presence === undefined)
+        return guardEarlyBindingCall(lowerer, info, expr, call);
+    const loc = call.loc;
+    const flag = { kind: "varRef", localId: presence.flagId, type: BOOL, loc };
+    if (!presence.lexical)
+        return earlyUnassignedCall(lowerer, call, flag, presence.name, loc);
+    return {
+        kind: "seqExpr",
+        stmts: [tdzCheck(flag, presence.name, loc)],
+        result: guardEarlyBindingCall(lowerer, info, expr, call),
+        type: call.type,
+        loc,
+    };
+}
 /** The presence flag a use that can run before the declaration checks.
  * Only module-scope bindings have one: a binding inside a function would
  * need a per-call flag that its closures share. */
@@ -2671,8 +3395,56 @@ export function bindingGenericFnAliasInfoOf(lowerer, decl) {
     const name = decl.name.text;
     requireStableGenericBinding(lowerer, decl, sym, name);
     lowerer.genericFnsBySymbol.set(sym, target);
+    noteAliasPresence(lowerer, decl, sym, name);
     return target;
 }
+/** Records the temporal-dead-zone flag of a module-scope alias whose reads
+ * can run before its declaration — a hoisted function called during module
+ * evaluation reads the binding while JavaScript still has it in its dead
+ * zone, and the alias has no storage of its own to throw from. The
+ * declaration statement sets the flag (genericAliasPresenceStore) and the
+ * early reads check it. Aliases declared inside functions keep the
+ * existing fences: a per-call flag would need a closure shared with every
+ * reader. */
+function noteAliasPresence(lowerer, decl, symbol, name) {
+    const stmt = decl.parent?.parent;
+    const list = stmt?.parent;
+    if (stmt === undefined || list === undefined)
+        return;
+    if (!ts.isSourceFile(list) && !ts.isModuleBlock(list))
+        return;
+    const nameNode = decl.name;
+    const ordering = new Map();
+    const early = bindingReferences(lowerer, ts.getSourceFileOfNode(decl), symbol, nameNode).some((ref) => !useRunsAfter(lowerer, decl, ref, ordering, new Set()));
+    if (!early)
+        return;
+    const flagId = `%g.${lowerer.qualify(ts.getSourceFileOfNode(decl), nsPathPrefix(lowerer, stmt, decl) + name)}%initialized`;
+    lowerer.globalsList.push({ id: flagId, name: "%initialized", type: BOOL, mutable: true });
+    lowerer.genericAliasPresence.set(symbol, {
+        flagId,
+        name,
+        decl,
+        lexical: !isVarDeclared(decl),
+        ordering,
+    });
+}
+/** The statement that records a generic alias's declaration as run, for
+ * an alias with a presence flag. */
+export function genericAliasPresenceStore(lowerer, decl) {
+    if (!ts.isIdentifier(decl.name))
+        return null;
+    const symbol = lowerer.checker.getSymbolAtLocation(decl.name);
+    const presence = symbol === undefined ? undefined : lowerer.genericAliasPresence.get(symbol);
+    if (presence === undefined)
+        return null;
+    const loc = locOf(decl);
+    return {
+        kind: "assign",
+        localId: presence.flagId,
+        value: { kind: "boolLit", value: true, type: BOOL, loc },
+        loc,
+    };
+}
 /** Static resolution stands in for the receiver's runtime value, so an
  * object-literal generic-method receiver must provably HOLD the defining
  * literal: a direct read of a binding whose initializer IS that literal