@scriptc/compiler 0.4.0 → 0.4.2

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

@@ -1,7 +1,10 @@
 import { staticNameBindings } from "./static-function-names.js";
+import { positionTag } from "./structural-positions.js";
+import { keyedHelperName } from "./stable-names.js";
 import * as ts from "../ts7/adapter.js";
 import { bodyReadsArguments } from "../arguments-usage.js";
-import { DYN, isUnitType, typeEquals, } from "../../ir/ir.js";
+import { BOOL, DYN, STRING, VOID, isUnitType, typeEquals, } from "../../ir/ir.js";
+import { helperLoc, nodeThrowExpr } from "../../ir/build.js";
 import { isJsSourceFile, locOf } from "../program.js";
 import { typeKey } from "../type-mapper.js";
 import { functionCanReturnUndefined } from "../function-completion.js";
@@ -12,7 +15,7 @@ import { nsPathPrefix } from "./lower-namespaces.js";
 import { declSymbolOf } from "./lower-modules.js";
 import { npmStaticPackageOfPath } from "../npm-static.js";
 import { rejectStaticThis } from "./static-this.js";
-import { jsBindingHasOpenWrites } from "./lower-stmts.js";
+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";
@@ -63,7 +66,7 @@ export function collectGenericSignature(lowerer, decl) {
     lowerer.genericFnsBySymbol.set(symbol, {
         decl,
         baseName: nameText,
-        qualifiedName: lowerer.qualify(ts.getSourceFileOfNode(decl), nsPathPrefix(decl) + nameText),
+        qualifiedName: lowerer.qualify(ts.getSourceFileOfNode(decl), nsPathPrefix(lowerer, decl) + nameText),
         typeParams,
         instances: new Map(),
     });
@@ -85,7 +88,14 @@ 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);
-    return { kind: "call", callee: instance.name, args, type: instance.returnType, loc };
+    const call = {
+        kind: "call",
+        callee: instance.name,
+        args,
+        type: instance.returnType,
+        loc,
+    };
+    return guardEarlyBindingCall(lowerer, info, expr, call);
 }
 /** The instance a CALL of a generic function-like names: resolved
  * signature → mapped param shapes/return → interned instance. Shared by
@@ -101,9 +111,13 @@ export function genericCallInstance(lowerer, expr, info) {
     // reconcile bridge, like the non-generic path).
     {
         const rdecl = rsig ? rsig.declaration : undefined;
-        if (rdecl &&
+        if (rsig &&
+            rdecl &&
             (ts.isFunctionDeclaration(rdecl) || ts.isMethodDeclaration(rdecl)) &&
             !rdecl.body) {
+            const overload = overloadCallInstance(lowerer, expr, info, rsig, rdecl);
+            if (overload)
+                return overload;
             lowerer.unsupported("SC1090", expr, `calls selecting an overload signature of a generic ${ts.isMethodDeclaration(rdecl) ? "method" : "function"} (only the implementation signature monomorphizes)`);
         }
     }
@@ -129,14 +143,7 @@ export function genericCallInstance(lowerer, expr, info) {
         fenceGenericSignatureResult(lowerer, expr, retTs);
         lowerer.badType(expr, retTs);
     }
-    // A body that can return an indexed read that misses returns undefined
-    // there, as in JavaScript, whatever the declared result says. An async
-    // body's promise is always present and settles with undefined there.
-    const returnType = lowerer.runtimeOptionalGenericReturns.has(info.decl)
-        ? mappedReturn.kind === "promise"
-            ? { kind: "promise", inner: lowerer.runtimeOptionalType(mappedReturn.inner) }
-            : lowerer.runtimeOptionalType(mappedReturn)
-        : mappedReturn;
+    const returnType = runtimeReturnType(lowerer, info, mappedReturn);
     // keyof-constrained type parameters (`K extends keyof T`): the bound
     // LITERAL is semantic — the instance body reads the named field — so
     // the bindings compute EAGERLY (the key needs them) and each literal
@@ -146,36 +153,120 @@ export function genericCallInstance(lowerer, expr, info) {
     // share one runtime-keyed instance per IR signature, exactly the
     // widened discipline.
     const named = staticNameBindings(lowerer, expr, info);
-    const keyofTps = keyofConstrainedTypeParams(info);
-    if (keyofTps.size > 0) {
+    if (keyofConstrainedTypeParams(info).size > 0) {
         const tsBindings = new Map();
         const bindings = lowerer.inferTypeParamBindings(expr, info, rsig, tsBindings);
-        const litKey = info.typeParams
-            .filter((tp) => keyofTps.has(tp))
-            .map((tp) => {
-            const bound = tsBindings.get(tp);
-            return bound?.isStringLiteralType()
-                ? JSON.stringify(bound.value)
-                : bound?.isNumberLiteralType()
-                    ? String(bound.value)
-                    : "*";
-        })
-            .join(",");
         return internGenericInstance(lowerer, expr, info, params, returnType, () => bindings, {
-            extraKey: `@${litKey}${named?.key ?? ""}`,
+            extraKey: `${keyofLiteralKey(info, tsBindings)}${named?.key ?? ""}`,
             tsBindings,
             ...(named ? { staticFnNames: named.names } : {}),
         });
     }
     return internGenericInstance(lowerer, expr, info, params, returnType, (tsBindings) => lowerer.inferTypeParamBindings(expr, info, rsig, tsBindings), named ? { extraKey: named.key, staticFnNames: named.names } : undefined);
 }
+/** A call that resolved to an OVERLOAD signature of a generic function
+ * or method with an implementation (`request<T>(p: WithHandler<T>):
+ * Promise<T>; request(p: Plain): Promise<Res>; request<T>(p: Params<T>)
+ * {...}`): the implementation monomorphizes under the bindings the
+ * overload's resolved signature proves for its type parameters (the
+ * structural unification every generic call uses, run against the
+ * overload; unbound parameters take their declared defaults). The
+ * instance's parameters and result are the IMPLEMENTATION's under those
+ * bindings — the body was checked against them — and the call's
+ * arguments and result coerce across, exactly as a non-generic overload
+ * call reconciles with its implementation (parameters the overload omits
+ * must be optional in the implementation). Null when the overload does
+ * not belong to this implementation or the arities do not line up. */
+function overloadCallInstance(lowerer, expr, info, rsig, rdecl) {
+    const impl = info.decl;
+    if (rdecl.parent !== impl.parent ||
+        rdecl.name === undefined ||
+        impl.name === undefined ||
+        rdecl.name.getText() !== impl.name.getText() ||
+        rdecl.parameters.nodes.length > impl.parameters.nodes.length ||
+        impl.parameters.nodes
+            .slice(rdecl.parameters.nodes.length)
+            .some((p) => p.questionToken === undefined && p.initializer === undefined) ||
+        rdecl.parameters.nodes.some((p) => p.dotDotDotToken !== undefined))
+        return null;
+    const declSig = lowerer.checker.getSignatureFromDeclaration(impl);
+    if (!declSig)
+        return null;
+    const tsBindings = new Map();
+    const bindings = new Map();
+    unifySignatureBindings(lowerer, info, rsig, bindings, tsBindings);
+    // Explicit type arguments name the OVERLOAD's type parameters, which
+    // need not match the implementation's in order: the resolved overload
+    // already carries them, so unification binds first, and an explicit
+    // argument binds only a still-unbound implementation parameter of the
+    // same name.
+    const overloadTps = rdecl.typeParameters?.nodes ?? [];
+    expr.typeArguments?.nodes.forEach((ta, i) => {
+        const name = overloadTps[i]?.name.text;
+        const tp = info.typeParams.find((p) => ts.symbolName(p) === name);
+        if (!tp || bindings.has(tp))
+            return;
+        const taT = lowerer.checker.getTypeFromTypeNode(ta);
+        const mapped = lowerer.mapTypeOf(taT);
+        if (mapped) {
+            bindings.set(tp, mapped);
+            tsBindings.set(tp, taT);
+        }
+    });
+    bindDefaultTypeParams(lowerer, info.typeParams, impl.typeParameters?.nodes, bindings, tsBindings);
+    // A type parameter the overload never mentions (a handler the overload
+    // omits) is `unknown`, the checker's own answer for an uninferred one.
+    for (const tp of info.typeParams) {
+        if (bindings.has(tp))
+            continue;
+        bindings.set(tp, DYN);
+        tsBindings.set(tp, lowerer.checker.getUnknownType());
+    }
+    const previous = lowerer.typeParamBindings;
+    const previousTs = lowerer.typeParamTsBindings;
+    lowerer.typeParamBindings = bindings;
+    lowerer.typeParamTsBindings = tsBindings;
+    let params;
+    let returnType;
+    try {
+        params = paramShapes(lowerer, impl.parameters.nodes, declSig, (_param, i) => expr.arguments.nodes[i] ?? expr);
+        returnType = lowerer.mapTypeOf(lowerer.checker.getReturnTypeOfSignature(declSig));
+    }
+    finally {
+        lowerer.typeParamBindings = previous;
+        lowerer.typeParamTsBindings = previousTs;
+    }
+    if (!returnType)
+        return null;
+    // keyof-constrained parameters key their instance on the bound literal,
+    // as on the implementation-signature path.
+    const runtimeReturn = runtimeReturnType(lowerer, info, returnType);
+    return internGenericInstance(lowerer, expr, info, params, runtimeReturn, () => bindings, {
+        ...(keyofConstrainedTypeParams(info).size > 0
+            ? { extraKey: keyofLiteralKey(info, tsBindings) }
+            : {}),
+        tsBindings,
+    });
+}
+/** An instance's result type: a body that can return an indexed read
+ * that misses returns undefined there, as in JavaScript, whatever the
+ * declared result says. An async body's promise is always present and
+ * settles with undefined there. */
+function runtimeReturnType(lowerer, info, mapped) {
+    if (!lowerer.runtimeOptionalGenericReturns.has(info.decl))
+        return mapped;
+    return mapped.kind === "promise"
+        ? { kind: "promise", inner: lowerer.runtimeOptionalType(mapped.inner) }
+        : lowerer.runtimeOptionalType(mapped);
+}
 /** A generic factory whose result is one of its own local classes
  * (`function base<T>(v: T) { return class { value: T = v }; }`). Each
  * instance has its own class, so the instance is keyed on its bindings and
  * the result maps inside it, where the local class takes the instance's
  * name and bindings. */
 function localClassResultInstance(lowerer, expr, info, rsig, params, retTs) {
-    if (!localClassOfResult(lowerer, info, retTs))
+    const resultClass = localClassOfResult(lowerer, info, retTs);
+    if (!resultClass)
         return null;
     const tsBindings = new Map();
     const bindings = lowerer.inferTypeParamBindings(expr, info, rsig, tsBindings);
@@ -192,12 +283,39 @@ function localClassResultInstance(lowerer, expr, info, rsig, params, retTs) {
     });
     if (inst.returnType !== pending)
         return inst;
-    const returnType = withInstanceScope(lowerer, info, inst, () => lowerer.mapTypeOf(retTs));
+    // A result typed by a declared constructor type rather than the class
+    // (`Struct<S>`) is the class value of the local class the body returns.
+    const declaredResult = info.decl.type
+        ? lowerer.checker.getTypeFromTypeNode(info.decl.type)
+        : undefined;
+    const viaConstructorType = retTs.getSymbol()?.valueDeclaration !== resultClass;
+    const returnType = withInstanceScope(lowerer, info, inst, () => {
+        if (!viaConstructorType)
+            return lowerer.mapTypeOf(retTs);
+        // The local class's own constructor type: a class expression's type is
+        // its constructor type, named or not (`return class { ... } as Struct<S>`).
+        const classSymbol = !ts.isClassExpression(resultClass) && resultClass.name
+            ? lowerer.checker.getSymbolAtLocation(resultClass.name)
+            : undefined;
+        const classType = ts.isClassExpression(resultClass)
+            ? lowerer.checker.getTypeAtLocation(resultClass)
+            : classSymbol
+                ? lowerer.checker.getTypeOfSymbol(classSymbol)
+                : undefined;
+        return classType ? lowerer.mapTypeOf(classType) : null;
+    });
     if (!returnType) {
         fenceGenericSignatureResult(lowerer, expr, retTs);
         lowerer.badType(expr, retTs);
     }
     inst.returnType = returnType;
+    if (viaConstructorType && returnType.kind === "classval") {
+        if (declaredResult)
+            inst.resultClass = { declared: declaredResult.id, value: returnType };
+        if (lowerer.typeParamBindings === null)
+            lowerer.localClassValueTypes.set(retTs.id, returnType);
+        return inst;
+    }
     // Values of the class outside the factory (`const b = new B()`, `b.read()`)
     // carry the instantiated checker type; record which class it names. A
     // call inside another generic instance can have a type that depends on
@@ -270,15 +388,103 @@ function insideGenericFunction(node) {
  * constructor or instance type of, or null. */
 function localClassOfResult(lowerer, info, type) {
     const symbol = type.getSymbol();
-    if (!symbol || !(symbol.flags & ts.SymbolFlags.Class))
+    const decl = symbol && symbol.flags & ts.SymbolFlags.Class ? symbol.valueDeclaration : undefined;
+    if (decl && (ts.isClassExpression(decl) || ts.isClassDeclaration(decl)))
+        return declaredInside(decl, info.decl) ? decl : null;
+    // A result typed by a constructor type (`Struct<S>`, `new () => S`) whose
+    // every return gives back the one local class, through parentheses and
+    // assertions (`return Base as Struct<S>`).
+    // A mixin (a class extending one of the function's parameters) keeps the
+    // mixin instantiation, which keys on the argument class.
+    if (lowerer.checker.getConstructSignatures(type).length === 0)
         return null;
-    const decl = symbol.valueDeclaration;
-    if (!decl || !(ts.isClassExpression(decl) || ts.isClassDeclaration(decl)))
+    const returned = returnedLocalClass(lowerer, info);
+    return returned && !extendsParameter(lowerer, returned, info) ? returned : null;
+}
+function extendsParameter(lowerer, decl, info) {
+    const params = new Set();
+    const fn = info.decl;
+    for (const param of fn.parameters?.nodes ?? []) {
+        const symbol = ts.isIdentifier(param.name)
+            ? lowerer.checker.getSymbolAtLocation(param.name)
+            : undefined;
+        if (symbol !== undefined)
+            params.add(symbol);
+    }
+    for (const clause of decl.heritageClauses?.nodes ?? [])
+        for (const base of clause.types.nodes) {
+            const symbol = ts.isIdentifier(base.expression)
+                ? lowerer.checker.getSymbolAtLocation(base.expression)
+                : undefined;
+            if (symbol !== undefined && params.has(symbol))
+                return true;
+        }
+    return false;
+}
+function declaredInside(node, owner) {
+    for (let parent = node.parent; parent && !ts.isSourceFile(parent); parent = parent.parent)
+        if (parent === owner)
+            return true;
+    return false;
+}
+/** The local class every return of `info`'s body gives back, or null when a
+ * return gives anything else (or nothing). Nested functions and classes keep
+ * their own returns. */
+function returnedLocalClass(lowerer, info) {
+    const fn = info.decl;
+    const body = fn.body;
+    if (!body)
         return null;
-    for (let parent = decl.parent; parent && !ts.isSourceFile(parent); parent = parent.parent)
-        if (parent === info.decl)
-            return decl;
-    return null;
+    const classOf = (node) => {
+        let expr = node;
+        while (ts.isParenthesizedExpression(expr) ||
+            ts.isAsExpression(expr) ||
+            ts.isSatisfiesExpression(expr) ||
+            ts.isNonNullExpression(expr))
+            expr = expr.expression;
+        if (ts.isClassExpression(expr))
+            return declaredInside(expr, info.decl) ? expr : null;
+        if (!ts.isIdentifier(expr))
+            return null;
+        const declaration = lowerer.checker.getSymbolAtLocation(expr)?.valueDeclaration;
+        if (!declaration || !declaredInside(declaration, info.decl))
+            return null;
+        if (ts.isClassDeclaration(declaration))
+            return declaration;
+        // A `const` bound to a class expression (`const C = class { ... }; return C`).
+        if (ts.isVariableDeclaration(declaration) &&
+            ts.getCombinedNodeFlags(declaration) & ts.NodeFlags.Const &&
+            declaration.initializer) {
+            let init = declaration.initializer;
+            while (ts.isParenthesizedExpression(init))
+                init = init.expression;
+            if (ts.isClassExpression(init))
+                return init;
+        }
+        return null;
+    };
+    if (!ts.isBlock(body))
+        return classOf(body);
+    let found = null;
+    let valid = true;
+    const visit = (node) => {
+        if (!valid ||
+            ts.isFunctionLike(node) ||
+            ts.isClassDeclaration(node) ||
+            ts.isClassExpression(node))
+            return;
+        if (ts.isReturnStatement(node)) {
+            const returned = node.expression ? classOf(node.expression) : null;
+            if (!returned || (found !== null && found !== returned))
+                valid = false;
+            else
+                found = returned;
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(body, visit);
+    return valid ? found : null;
 }
 /** Runs `fn` under an instance's type bindings and local-class names, as
  * its body lowers. */
@@ -287,15 +493,18 @@ function withInstanceScope(lowerer, info, inst, fn) {
     const prevTsBindings = lowerer.typeParamTsBindings;
     const previousPath = lowerer.genericInstantiationPath;
     const prevContext = lowerer.instantiationContext;
+    const prevResultClass = lowerer.instanceResultClass;
     lowerer.typeParamBindings = inst.bindings;
     lowerer.typeParamTsBindings = inst.tsBindings ?? null;
     lowerer.genericInstantiationPath = inst.path;
     lowerer.instantiationContext = `instantiating '${info.baseName}' with ${inst.typeArgsText}`;
+    lowerer.instanceResultClass = inst.resultClass ?? null;
     lowerer.localClassInstantiations.push({ owner: info.decl, name: inst.name });
     try {
         return fn();
     }
     finally {
+        lowerer.instanceResultClass = prevResultClass;
         lowerer.localClassInstantiations.pop();
         lowerer.typeParamBindings = prevBindings;
         lowerer.typeParamTsBindings = prevTsBindings;
@@ -339,7 +548,7 @@ function internGenericInstance(lowerer, blame, info, params, returnType, makeBin
         const typeArgsText = `<${rendered.length > 80 ? rendered.slice(0, 77) + "..." : rendered}>`;
         inst = {
             path,
-            name: `${info.qualifiedName}%${info.instances.size}`,
+            name: keyedHelperName(lowerer, `${info.qualifiedName}%`, key, ""),
             ordinal: info.instances.size,
             params,
             returnType,
@@ -374,6 +583,24 @@ function keyofConstrainedTypeParams(info) {
     info.keyofTps = out;
     return out;
 }
+/** The instance-key suffix of the literals bound to `info`'s
+ * keyof-constrained type parameters (`@"a"`; `*` for a non-literal
+ * binding): two literals can map to one IR signature while their bodies
+ * read different fields. */
+function keyofLiteralKey(info, tsBindings) {
+    const keyofTps = keyofConstrainedTypeParams(info);
+    const literals = info.typeParams
+        .filter((tp) => keyofTps.has(tp))
+        .map((tp) => {
+        const bound = tsBindings.get(tp);
+        return bound?.isStringLiteralType()
+            ? JSON.stringify(bound.value)
+            : bound?.isNumberLiteralType()
+                ? String(bound.value)
+                : "*";
+    });
+    return `@${literals.join(",")}`;
+}
 /** Type-parameter symbol → concrete IR type for one instantiation.
  * Explicit type arguments bind directly; the rest come from structurally
  * matching each DECLARED param/return type (which mentions the type
@@ -491,6 +718,31 @@ function unifySignatureBindings(lowerer, info, rsig, bindings, tsBindings) {
                 // too is safe only when no undeclared null arm remains.
                 unify(dParts[0], lowerer.checker.getNonNullableType(inst), depth + 1);
             }
+            else if (dParts.length > 1 && iParts.length === dParts.length) {
+                // `T | Promise<T>` against `Res | Promise<Res>`: each declared
+                // part that names a generic target (Promise, an interface, an
+                // alias) pairs with the one instantiated part of the same target;
+                // a single remaining bare type parameter takes the single
+                // remaining instantiated part.
+                const remaining = [...iParts];
+                const bare = [];
+                for (const d of dParts) {
+                    if (d.flags & ts.TypeFlags.TypeParameter) {
+                        bare.push(d);
+                        continue;
+                    }
+                    const target = d.getSymbol() ?? d.getAliasSymbol();
+                    if (target === undefined)
+                        return;
+                    const matches = remaining.filter((i) => (i.getSymbol() ?? i.getAliasSymbol()) === target);
+                    if (matches.length !== 1)
+                        return;
+                    remaining.splice(remaining.indexOf(matches[0]), 1);
+                    unify(d, matches[0], depth + 1);
+                }
+                if (bare.length === 1 && remaining.length === 1)
+                    unify(bare[0], remaining[0], depth + 1);
+            }
             return;
         }
         // Instantiations of the SAME generic ALIAS (Partial<T> vs
@@ -783,6 +1035,12 @@ export function lowerGenericFnValue(lowerer, ref, info) {
         lowerer.noteEdge(inst.name);
         return { 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
+    // it), which one shared compiled instance cannot give.
+    if (info.functionScoped) {
+        lowerer.unsupported("SC1090", ref, `generic arrow/function-expression bindings declared inside functions as values (each call of the enclosing function makes a new '${info.baseName}' function object, while its compiled instances are shared module functions — call '${info.baseName}' directly, or declare it at module scope)`);
+    }
     const fenceUnpinned = () => lowerer.unsupported("SC1090", ref, `generic functions as values without a pinned concrete signature (annotate the destination — e.g. 'const f: (x: number) => number = ${info.baseName}' — instantiate explicitly ('${info.baseName}<number>'), or call '${info.baseName}' directly)`);
     // The PINNING type: an instantiation expression's own checker type
     // (explicit type arguments applied), else the reference's contextual
@@ -815,6 +1073,78 @@ export function lowerGenericFnValue(lowerer, ref, info) {
     }
     if (!target)
         fenceUnpinned();
+    return guardEarlyBindingValue(lowerer, info, ref, pinnedGenericClosure(lowerer, ref, info, target, fenceUnpinned));
+}
+/** The value a generic binding declared inside a function stores when a
+ * nested function read it before the declaration lowered (`const read =
+ * () => id; const id: (x: number) => number = <T>(x: T): T => x`): such
+ * a read resolves to an ordinary TDZ local, so the declaration assigns it
+ * the instance its concrete declared signature pins. Each evaluation of
+ * the declaration makes a new function object, as in JavaScript: the
+ * value is a closure over a forwarder to the instance, not the instance's
+ * interned closure. */
+export function genericBindingStoredValue(lowerer, decl, info) {
+    const name = decl.name;
+    const fenceUnpinned = () => lowerer.unsupported("SC1090", name, `generic function bindings read before their declaration without a concrete declared signature (annotate '${info.baseName}' with one, or declare it before its uses)`);
+    const sigs = lowerer.checker.getCallSignatures(lowerer.typeOf(name));
+    if (sigs.length !== 1)
+        fenceUnpinned();
+    const pinned = pinnedGenericClosure(lowerer, name, info, sigs[0], fenceUnpinned);
+    const async = ts.getModifiers(info.decl)?.some((m) => m.kind === ts.SyntaxKind.AsyncKeyword);
+    if (pinned.kind !== "closure" || pinned.type.kind !== "func" || pinned.type.rest || async)
+        return lowerer.unsupported("SC1090", name, `async or rest-parameter generic function bindings read before their declaration (each evaluation of '${info.baseName}' makes a new function object)`);
+    return {
+        ...pinned,
+        fnName: genericValueForwarder(lowerer, info, pinned.fnName, pinned.type, pinned.loc),
+    };
+}
+/** A lifted function that calls the instance `instance` (of type `type`)
+ * with its own arguments. Lifted functions get a new closure object per
+ * evaluation; module functions, which instances are, get one interned
+ * closure. */
+function genericValueForwarder(lowerer, info, instance, type, at) {
+    info.valueForwarders ??= new Map();
+    const existing = info.valueForwarders.get(instance);
+    if (existing !== undefined)
+        return existing;
+    const name = `${instance}%value`;
+    const loc = helperLoc(at);
+    const params = type.params.map((paramType, i) => ({
+        localId: `%arg${i}.0`,
+        name: `%arg${i}`,
+        type: paramType,
+    }));
+    const call = {
+        kind: "call",
+        callee: instance,
+        args: params.map((p) => ({ kind: "varRef", localId: p.localId, type: p.type, loc })),
+        type: type.ret,
+        loc,
+    };
+    lowerer.liftedFns.push({
+        name,
+        params,
+        returnType: type.ret,
+        locals: params.map((p) => ({ id: p.localId, name: p.name, type: p.type, mutable: false })),
+        captures: [],
+        ...(ts.isFunctionExpression(info.decl) ? { ownsPrototype: true } : {}),
+        body: type.ret.kind === "void"
+            ? [
+                { kind: "exprStmt", expr: call, loc },
+                { kind: "return", value: null, loc },
+            ]
+            : [{ kind: "return", value: call, loc }],
+        loc,
+    });
+    lowerer.noteEdge(name);
+    info.valueForwarders.set(instance, name);
+    return name;
+}
+/** The closure of the instance of `info` that `target` pins, for a value
+ * read at `ref`. `fenceUnpinned` reports a signature that leaves a type
+ * parameter unbound. */
+function pinnedGenericClosure(lowerer, ref, info, target, fenceUnpinned) {
+    const loc = locOf(ref);
     const bindings = new Map();
     unifySignatureBindings(lowerer, info, target, bindings);
     const hofBinding = runtimeOptionalHofGenericBinding(lowerer, ref, info);
@@ -1611,7 +1941,7 @@ function internImplicitInstance(lowerer, blame, info, shapes, argTypes, patternK
     const declared = dynamicBroadPromise ? null : implicitDeclaredReturn(lowerer, info);
     inst = {
         path,
-        name: `${info.qualifiedName}%${info.instances.size}`,
+        name: keyedHelperName(lowerer, `${info.qualifiedName}%`, key, ""),
         ordinal: info.instances.size,
         params: shapes,
         // The promise callers rely on before the body settles it: the
@@ -1711,28 +2041,50 @@ export function implicitLocalFnNodeOf(lowerer, decl) {
             return null;
         if (!isConst && !bindingNeverReassigned(lowerer, sym, decl))
             return null;
-        // The capture scan: instances are module functions with no frame.
-        let captures = false;
-        const scan = (n) => {
-            if (captures)
-                return;
-            if (n.kind === ts.SyntaxKind.ThisKeyword || n.kind === ts.SyntaxKind.SuperKeyword) {
-                // 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.
-                captures = true;
-                return;
+        // Instances are module functions with no frame.
+        return capturesEnclosingFrame(lowerer, init, decl, init.body) ? null : init;
+    };
+    const node = probe();
+    if (node === null) {
+        lowerer.implicitLocalFns.set(decl, null);
+        return null;
+    }
+    return node;
+}
+/** True when `fn`, bound by `decl`, uses its enclosing function's frame
+ * somewhere in `scope`: `this`, `super`, `arguments` or `new.target`, or
+ * a value or type declared in an enclosing function (a local, a parameter,
+ * an enclosing generic's type parameter). Module-scope declarations and
+ * the binding itself are reachable from the module functions the
+ * instances compile to. */
+function capturesEnclosingFrame(lowerer, fn, decl, scope) {
+    const file = ts.getSourceFileOfNode(decl);
+    const self = lowerer.checker.getSymbolAtLocation(decl.name);
+    let captures = false;
+    const scan = (n) => {
+        if (captures)
+            return;
+        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.
+            captures = true;
+            return;
+        }
+        if (ts.isIdentifier(n)) {
+            const s = lowerer.checker.getSymbolAtLocation(n);
+            if (s === undefined) {
+                if (n.text === "arguments")
+                    captures = true;
             }
-            if (ts.isIdentifier(n)) {
-                const s = lowerer.checker.getSymbolAtLocation(n);
-                const d = s ? s.valueDeclaration : undefined;
-                if (d &&
-                    ts.getSourceFileOfNode(d) === ts.getSourceFileOfNode(decl) &&
-                    !(d.pos >= init.pos && d.end <= init.end)) {
-                    // Declared outside the initializer, in this file: a capture
-                    // exactly when some enclosing FUNCTION scope declares it —
-                    // module-scope declarations are reachable from any module
-                    // function.
+            else if (s !== self) {
+                for (const d of s.declarations) {
+                    if (ts.getSourceFileOfNode(d) !== file || (d.pos >= fn.pos && d.end <= fn.end))
+                        continue;
+                    // Declared outside the function, in this file: a capture
+                    // exactly when some enclosing FUNCTION scope declares it.
                     for (let p = d.parent; p !== undefined && !ts.isSourceFile(p); p = p.parent) {
                         if (ts.isFunctionLike(p)) {
                             captures = true;
@@ -1741,17 +2093,11 @@ export function implicitLocalFnNodeOf(lowerer, decl) {
                     }
                 }
             }
-            ts.forEachChild(n, scan);
-        };
-        scan(init.body);
-        return captures ? null : init;
+        }
+        ts.forEachChild(n, scan);
     };
-    const node = probe();
-    if (node === null) {
-        lowerer.implicitLocalFns.set(decl, null);
-        return null;
-    }
-    return node;
+    scan(scope);
+    return captures;
 }
 /** Registers (or returns) the GenericFnInfo of a qualifying implicit-any
  * function-value binding — implicitLocalFnNodeOf's companion, the
@@ -1776,7 +2122,7 @@ export function implicitLocalFnInfoOf(lowerer, decl, fnNode) {
     const info = {
         decl: fnNode,
         baseName: name,
-        qualifiedName: lowerer.qualify(ts.getSourceFileOfNode(decl), nsPathPrefix(stmt ?? decl, decl) + `${name}%l${ts.tokenStartOfNode(decl)}`),
+        qualifiedName: lowerer.qualify(ts.getSourceFileOfNode(decl), nsPathPrefix(lowerer, stmt ?? decl, decl) + `${name}%l${positionTag(lowerer, decl)}`),
         typeParams: [],
         instances: new Map(),
         implicitParams: implicit,
@@ -1848,7 +2194,7 @@ export function objLitGenericFnInfoOf(lowerer, blame, name, found) {
     const info = {
         decl: fnNode,
         baseName: name,
-        qualifiedName: lowerer.qualify(ts.getSourceFileOfNode(fnNode), `%ol${ts.tokenStartOfNode(fnNode)}.${name}`),
+        qualifiedName: lowerer.qualify(ts.getSourceFileOfNode(fnNode), `%ol${positionTag(lowerer, fnNode)}.${name}`),
         typeParams,
         instances: new Map(),
         objectLiteral: true,
@@ -1925,9 +2271,16 @@ 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.
+    let functionScoped = false;
     for (let n = decl.parent; n !== undefined && !ts.isSourceFile(n); n = n.parent) {
         if (ts.isFunctionLike(n)) {
-            lowerer.unsupported("SC1090", fnNode, `generic arrow/function-expression bindings declared inside functions (the compiled instantiations of '${name}' are module functions and cannot capture the enclosing frame — declare the binding at module scope)`);
+            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)`);
+            }
+            functionScoped = true;
+            break;
         }
     }
     const sym = lowerer.checker.getSymbolAtLocation(decl.name);
@@ -1956,15 +2309,30 @@ export function bindingGenericFnInfoOf(lowerer, decl, fnNode) {
     }
     checkGenericParameterNames(lowerer, fnNode.parameters.nodes, true);
     const stmt = decl.parent?.parent; // declarator → list → statement (nsPathPrefix wants the statement)
+    // A binding in a function or block can share its name with another; its
+    // instances take the declaration's position.
+    const topLevel = stmt?.parent !== undefined && (ts.isSourceFile(stmt.parent) || ts.isModuleBlock(stmt.parent));
     const info = {
         decl: fnNode,
         baseName: name,
-        qualifiedName: lowerer.qualify(ts.getSourceFileOfNode(decl), nsPathPrefix(stmt ?? decl, decl) + name),
+        qualifiedName: lowerer.qualify(ts.getSourceFileOfNode(decl), nsPathPrefix(lowerer, stmt ?? decl, decl) +
+            (topLevel ? name : `${name}%l${ts.tokenStartOfNode(decl)}`)),
         typeParams,
         instances: new Map(),
+        ...(functionScoped ? { functionScoped: true } : {}),
+        bindingDecl: decl,
     };
     lowerer.bindingGenericFns.set(fnNode, info);
     lowerer.genericFnsBySymbol.set(sym, info);
+    // Module-scope uses resolve to the instances from the start, so those
+    // that can run first need the flag. Inside a function the declaration
+    // registers before any later use lowers, and earlier uses read a TDZ
+    // box (genericBindingStoredValue).
+    if (!functionScoped) {
+        const presence = bindingPresenceOf(lowerer, info, decl, sym);
+        if (presence !== undefined)
+            info.presence = presence;
+    }
     if (ts.isFunctionExpression(fnNode) && fnNode.name !== undefined) {
         const inner = lowerer.checker.getSymbolAtLocation(fnNode.name);
         if (inner)
@@ -1972,6 +2340,225 @@ export function bindingGenericFnInfoOf(lowerer, decl, fnNode) {
     }
     return info;
 }
+/** Whether `use`, a reference to the binding `info` declares, can only
+ * run after the declaration has run: it follows the declaration in its
+ * statement list (closures count where they are created), sits inside the
+ * initializer itself, or is inside a function declaration whose every
+ * reference does. References from other modules run after this module's
+ * body, and export specifiers only export. A use the check cannot place
+ * answers false. */
+export function runsAfterDeclaration(lowerer, info, use) {
+    const decl = info.bindingDecl;
+    if (decl === undefined)
+        return true;
+    info.ordering ??= new Map();
+    return useRunsAfter(lowerer, decl, use, info.ordering, new Set());
+}
+function useRunsAfter(lowerer, decl, use, memo, inProgress) {
+    if (ts.getSourceFileOfNode(use) !== ts.getSourceFileOfNode(decl))
+        return true;
+    const init = decl.initializer;
+    if (init !== undefined && use.pos >= init.pos && use.end <= init.end)
+        return true;
+    const stmt = decl.parent?.parent;
+    const list = stmt?.parent;
+    if (stmt === undefined || list === undefined)
+        return false;
+    for (let n = use; n.parent !== undefined; n = n.parent) {
+        if (n.parent === list)
+            return n === stmt ? use.pos >= decl.end : n.pos >= stmt.end;
+        if (ts.isFunctionDeclaration(n))
+            return functionRunsAfter(lowerer, decl, n, memo, inProgress);
+    }
+    return false;
+}
+/** Whether every call of the function declaration `fn` runs after `decl`
+ * has run. A function in progress counts as running after: its calls of
+ * itself, directly or through other functions, add no earlier caller.
+ * Only answers that depend on no function in progress are memoized. */
+function functionRunsAfter(lowerer, decl, fn, memo, inProgress) {
+    const known = memo.get(fn);
+    if (known !== undefined)
+        return known;
+    if (inProgress.has(fn))
+        return true;
+    // `export default function () {}`: only importers call it, after this
+    // module's body has run.
+    if (fn.name === undefined)
+        return true;
+    inProgress.add(fn);
+    let result = true;
+    try {
+        const symbol = lowerer.checker.getSymbolAtLocation(fn.name);
+        if (symbol === undefined)
+            result = false;
+        else {
+            for (const ref of bindingReferences(lowerer, ts.getSourceFileOfNode(fn), symbol, fn.name)) {
+                if (ref.pos >= fn.pos && ref.end <= fn.end)
+                    continue;
+                if (!useRunsAfter(lowerer, decl, ref, memo, inProgress)) {
+                    result = false;
+                    break;
+                }
+            }
+        }
+    }
+    finally {
+        inProgress.delete(fn);
+    }
+    if (inProgress.size === 0)
+        memo.set(fn, result);
+    return result;
+}
+/** The value references of `symbol` in `file` other than `name` (its
+ * declaration name): identifiers spelled like it that resolve to it,
+ * outside type positions and export specifiers. */
+function bindingReferences(lowerer, file, symbol, name) {
+    let byName = lowerer.bindingIdentifiers.get(file);
+    if (byName === undefined) {
+        byName = new Map();
+        lowerer.bindingIdentifiers.set(file, byName);
+    }
+    let idents = byName.get(name.text);
+    if (idents === undefined) {
+        const found = [];
+        ts.walkPreorder(file, (node) => {
+            if (ts.isIdentifier(node) && node.text === name.text)
+                found.push(node);
+            return undefined;
+        });
+        lowerer.checker.prefetchSymbolNodesExact(found);
+        byName.set(name.text, found);
+        idents = found;
+    }
+    return idents.filter((ident) => {
+        if (ident === name)
+            return false;
+        const parent = ident.parent;
+        if (parent === undefined || ts.isExportSpecifier(parent) || ts.isExportAssignment(parent))
+            return false;
+        let resolved = lowerer.checker.getSymbolAtLocation(ident);
+        if (ts.isShorthandPropertyAssignment(parent) && parent.name === ident)
+            resolved = lowerer.checker.getShorthandAssignmentValueSymbol(parent) ?? resolved;
+        if (resolved !== symbol)
+            return false;
+        for (let p = parent; p !== undefined; p = p.parent) {
+            if (ts.isTypeNode(p) && p.kind !== ts.SyntaxKind.ExpressionWithTypeArguments)
+                return false;
+            if (ts.isStatement(p) || ts.isFunctionLike(p))
+                break;
+        }
+        return true;
+    });
+}
+/** The presence flag of a module-scope generic binding that code can use
+ * before its declaration runs (a hoisted function or an earlier closure
+ * called during module evaluation), or undefined when every use runs
+ * after it. The declaration statement sets the flag. */
+function bindingPresenceOf(lowerer, info, decl, symbol) {
+    const name = decl.name;
+    const early = bindingReferences(lowerer, ts.getSourceFileOfNode(decl), symbol, name).some((ref) => !runsAfterDeclaration(lowerer, info, ref));
+    if (!early)
+        return undefined;
+    const flagId = `%g.${info.qualifiedName}%initialized`;
+    lowerer.globalsList.push({ id: flagId, name: "%initialized", type: BOOL, mutable: true });
+    return { flagId, lexical: !isVarDeclared(decl) };
+}
+/** The statement that records a generic binding's declaration as run,
+ * for a binding with a presence flag. */
+export function genericBindingPresenceStore(info, decl) {
+    if (info.presence === undefined)
+        return null;
+    const loc = locOf(decl);
+    return {
+        kind: "assign",
+        localId: info.presence.flagId,
+        value: { kind: "boolLit", value: true, type: BOOL, loc },
+        loc,
+    };
+}
+/** A call of a generic binding where the binding may not be initialized
+ * yet. A `let`/`const` binding in its temporal dead zone throws Node's
+ * ReferenceError before the arguments run; an unassigned `var` is
+ * undefined, so the arguments run and the call throws "is not a
+ * function". Calls that run after the declaration stay direct. */
+function guardEarlyBindingCall(lowerer, info, expr, call) {
+    if (info.bindingDecl === undefined || runsAfterDeclaration(lowerer, info, expr))
+        return call;
+    const loc = call.loc;
+    const presence = requirePresence(lowerer, info, expr.expression);
+    const flag = { kind: "varRef", localId: presence.flagId, type: BOOL, loc };
+    if (presence.lexical)
+        return {
+            kind: "seqExpr",
+            stmts: [tdzCheck(flag, info.baseName, loc)],
+            result: call,
+            type: call.type,
+            loc,
+        };
+    // Arguments first, in order, then the check: Node evaluates them
+    // before it finds the callee is not callable.
+    const stmts = [];
+    const args = call.args.map((arg) => {
+        const id = `%earlyCallArg.${lowerer.ctx.locals.length}`;
+        lowerer.ctx.locals.push({ id, name: "%earlyCallArg", type: arg.type, mutable: false });
+        stmts.push({ kind: "varDecl", localId: id, init: arg, loc });
+        return { kind: "varRef", localId: id, type: arg.type, loc };
+    });
+    return {
+        kind: "seqExpr",
+        stmts,
+        result: {
+            kind: "ternary",
+            cond: flag,
+            then: { ...call, args },
+            else_: nodeThrowExpr(1, "", `${info.baseName} is not a function`, call.type, loc),
+            type: call.type,
+            loc,
+        },
+        type: call.type,
+        loc,
+    };
+}
+/** A generic binding read as a value where it may not be initialized
+ * yet: a `let`/`const` binding checks its temporal dead zone first. */
+function guardEarlyBindingValue(lowerer, info, ref, value) {
+    if (info.bindingDecl === undefined || runsAfterDeclaration(lowerer, info, ref))
+        return value;
+    const presence = requirePresence(lowerer, info, ref);
+    if (!presence.lexical)
+        lowerer.unsupported("SC1090", ref, `generic 'var' bindings read as values before their declaration runs (Node reads undefined there; declare '${info.baseName}' with const)`);
+    const loc = value.loc;
+    const flag = { kind: "varRef", localId: presence.flagId, type: BOOL, loc };
+    return {
+        kind: "seqExpr",
+        stmts: [tdzCheck(flag, info.baseName, loc)],
+        result: value,
+        type: value.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. */
+function requirePresence(lowerer, info, blame) {
+    if (info.presence !== undefined)
+        return info.presence;
+    return lowerer.unsupported("SC1090", blame, `generic arrow/function-expression bindings declared inside functions that code can call before their declaration runs (the binding '${info.baseName}' is a 'var' in a branch or block, or is called from a place that can run first — declare it with const before its uses)`);
+}
+function tdzCheck(flag, name, loc) {
+    return {
+        kind: "exprStmt",
+        expr: {
+            kind: "intrinsic",
+            name: "module.tdzCheck",
+            args: [flag, { kind: "strLit", value: name, type: STRING, loc }],
+            type: VOID,
+            loc,
+        },
+        loc,
+    };
+}
 /** `const h = id` — a binding ALIASING a generic function (a top-level
  * declaration, a registered generic binding, or another alias — resolved
  * left to right in declaration order). The alias registers the SAME info