@scriptc/compiler 0.2.5 → 0.2.7

package/dist/frontend/lowering/lowerer.js

@@ -1,4 +1,12 @@
+import { checkCycleBindingAccesses, refuseUncheckedCycleReads, } from "./cycle-initialization.js";
+import { identityPreservingWidening } from "./coercions/identity.js";
+import { checkedClassAssertion } from "./class-assertions.js";
+import { narrowStoredClassValue, narrowGenericClassValue } from "./class-unions.js";
+import { isOptionalProcessStreamProperty } from "./builtins/process.js";
+import { concreteCollectionNarrow } from "./collection-narrowing.js";
+import { lowerWorkerMetadata } from "./builtins/workers.js";
 import { dynUndefinedExpr, nodeThrowExpr, numLit, varRef } from "../../ir/build.js";
+import { iteratorSlotAdapter } from "./iterator-adapters.js";
 import { lowerBuiltinCall } from "./builtin-calls.js";
 import { CoercionState } from "./coercions/state.js";
 import { widthLiftPlan, unitOnlyElem, recordWidthPlan, describeRecordWidthBlocker, objToRecordPlan, recordToClassPlan, } from "./coercions/structural-plans.js";
@@ -8,6 +16,7 @@ import { unionRetagMappable, narrowedRetagHelper, strandedUnitTrap, strandedCoer
 import { jsvalLiftable, jsvalLiftExpr, unionToJsvalHelper, recordToJsvalHelper, arrayToJsvalHelper, arrayToJsvalArrayHelper, } from "./coercions/island.js";
 import { lowerUtilTypeValue, pathModuleValue, utilTypesModuleValue, } from "./lower-builtin-values.js";
 import { everyExprChild, everyStmtChild, transformStmtList } from "../../ir/traverse.js";
+import { RuntimeOptionalProvenance } from "./runtime-optional-provenance.js";
 import { RuntimeOptionalLocals } from "./runtime-optional-locals.js";
 import { sanitizeUnregisteredClassTypes } from "./sanitize-class-types.js";
 import { UnregisteredClassTypes } from "./unregistered-class-types.js";
@@ -15,6 +24,7 @@ import { bindingInContext, captureContextBinding, declareContextLocal, declareCo
 import { InternalCompilerError } from "../../errors.js";
 import { defaultAfterUndefined, lowerStaticallyUndefinedArgument } from "./optional-arguments.js";
 import { ClassDynamicDispatch, trackClassFieldCreation } from "./class-dynamic-dispatch.js";
+import { ClassProtocols } from "./class-protocols.js";
 import { DeferredModuleInitializers } from "./deferred-module-initializers.js";
 import { finalizeClassMethodValues } from "./class-method-values.js";
 export { newFnCtx } from "./function-context.js";
@@ -44,7 +54,7 @@ import { provenanceActive } from "../provenance-registry.js";
 import { ambientDtsPath, canonicalBuiltinModule, cjsExportAssignmentOf, cjsExportDiscardReason, fallbackDtsPath, isCjsExportTableLiteral, isCjsJsFile, isJsSourceFile, isNodeEsmFile, isNodeTypesPath, locOf, orderedImportsOf, overridesDtsPath, npmStaticDepSf7, requireSpecOf, resolveImport, workspacePackageOfPath, } from "../program.js";
 import { containsRecord, containsUnion, describeComponentBlocker, describeRecordMemberBlocker, formatIrType, ISLAND_AMBIENT_TYPES, isUnitOnlyTsType, jsOpenObjectType, mapType, ShapeRegistry, typeKey, UnionRegistry, withUndefinedArm as withUndefinedArmCanonical, } from "../type-mapper.js";
 import { boundaryIntoIslandMsg, boundaryOutOfIslandMsg, builtinConstLit, builtinModuleConstOf, builtinModulesArrayLit, builtinFenceHintOf, builtinModuleFnOf, stdlibMemberFence, isStdlibMember, isStdlibSymbol, isStdlibGlobal, stdlibGlobalNameOf, stdlibGlobalMember, nodeTypesOnlySymbol, } from "./surfaces.js";
-import { splitFiles, collectProgram, collectNpmImports, collectJsonImports, moduleArtifacts, collectGlobals, declSymbolOf, defaultExportSymbolOf, lowerFileInit, lowerDefaultExport, buildMain, appendDynamicImportModules, appendForkModules, } from "./lower-modules.js";
+import { splitFiles, collectProgram, collectNpmImports, collectJsonImports, moduleArtifacts, collectGlobals, declSymbolOf, defaultExportSymbolOf, lowerFileInit, lowerDefaultExport, buildMain, appendDynamicImportModules, appendForkModules, appendWorkerModules, } from "./lower-modules.js";
 import { prepareCjsModuleGraph } from "./lower-node-module.js";
 import { registerBuiltinErrorClasses, registerBuiltinEmitterClass, registerBuiltinStreamClasses, builtinErrorInfoOf, builtinEmitterInfoOf, builtinStreamInfoOf, analyzeClassDecoration, classIteratorDrainCall, classIteratorNextCall, classIteratorOf, classIteratorOpenCall, classIteratorRestDrainCall, classMemberNameOf, classValueRef, collectClassShape, exactClassOfReceiver, collectClassShapeInner, ctorAbiEquals, findMethodOn, findStaticOn, genericClassInstanceType, isSubclassOf, inHierarchy, overrideBelow, staticShadowBelow, upcastTo, lowerClassMembers, lowerClassCtor, lowerClassExpression, lowerClassExpressionInfo, lowerClassMethodMember, lowerClassValueProperty, lowerStaticMethod, throwingSetterFn, fieldInitStmts, lowerStaticFieldInits, lowerStaticFieldRead, lowerDerivedCtorBody, superCallStmt, lowerSuperMethodCall, superThisRef, lowerSuperAccessorRead, lowerSuperAccessorWrite, inheritsBuiltinErrorCtor, inheritsBuiltinEmitterCtor, errorConstructorArgs, lowerNew, accessorCall, } from "./lower-classes.js";
 import { mixinCallClassInfoOf, mixinIntersectionInstanceType, } from "./lower-mixins.js";
@@ -247,6 +257,7 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
     const extraModuleCycleDiags = [];
     const cycleKeys = new Set();
     const forkTargets = [];
+    const workerTargets = [];
     const onExtraCycle = (cycle, reason) => {
         const key = `${cycle}\0${reason}`;
         if (cycleKeys.has(key))
@@ -258,6 +269,7 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
         const before = moduleOrder.length;
         appendDynamicImportModules(program, moduleOrder, onExtraCycle);
         appendForkModules(program, moduleOrder, forkTargets, onExtraCycle);
+        appendWorkerModules(program, moduleOrder, workerTargets, onExtraCycle);
         if (moduleOrder.length === before)
             break;
         if (pass === 31)
@@ -274,6 +286,7 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
         ffiImports,
         libraryCallbacks,
         forkTargets,
+        workerTargets,
         externalTypes,
         externalTypeSpecifiersByFile,
     });
@@ -293,6 +306,7 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
             ffiImports,
             libraryCallbacks,
             forkTargets,
+            workerTargets,
             externalTypes,
             externalTypeSpecifiersByFile,
             ffiBindingSymbols: ffiValidation.symbolsByName,
@@ -322,6 +336,7 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
             ffiImports,
             libraryCallbacks,
             forkTargets,
+            workerTargets,
             ffiBindingSymbols: ffiValidation.symbolsByName,
             externalTypes,
             externalTypeSpecifiersByFile,
@@ -345,6 +360,7 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
         ffiImports,
         libraryCallbacks,
         forkTargets,
+        workerTargets,
         ffiBindingSymbols: ffiValidation.symbolsByName,
         externalTypes,
         externalTypeSpecifiersByFile,
@@ -927,6 +943,7 @@ export class Lowerer {
     /** Monomorphization worklist: instances queued by call sites, drained in
      * run() (processing an instance body can queue more). */
     instantiationQueue = [];
+    genericInstantiationPath = null;
     /** Historical emit rank of the retained declaration/init body currently
      * lowering, and the earliest such owner that demanded each generic
      * instance. Reachability can encounter a later caller first; the minimum
@@ -1234,6 +1251,17 @@ export class Lowerer {
         while (ts.isParenthesizedExpression(origin))
             origin = origin.expression;
         let optionalOrigin = ts.isElementAccessExpression(origin) || ts.isPropertyAccessExpression(origin);
+        if (ts.isCallExpression(origin)) {
+            const name = ts.isPropertyAccessExpression(origin.expression)
+                ? origin.expression.name
+                : origin.expression;
+            const symbol = ts.isIdentifier(name) ? this.resolveValueSymbol(name) : undefined;
+            const signature = symbol ? this.fnSigsBySymbol.get(symbol) : undefined;
+            optionalOrigin =
+                this.runtimeOptionalFunctionReturns.has(origin) ||
+                    (signature?.returnType.kind === "union" &&
+                        this.armTag(signature.returnType.unionId, UNDEFINED_T) >= 0);
+        }
         if (ts.isIdentifier(origin)) {
             const local = this.resolveLocal(origin);
             const root = local ? this.runtimeOptionalRootOf(local) : null;
@@ -1338,7 +1366,16 @@ export class Lowerer {
     runtimeOptionalWidening(actual, expected) {
         if (actual.kind !== "union" || this.armTag(actual.unionId, UNDEFINED_T) < 0)
             return null;
-        return typeEquals(this.stripUndefinedArm(actual), expected) ? actual : null;
+        const present = this.stripUndefinedArm(actual);
+        if (typeEquals(present, expected))
+            return actual;
+        // Only a bare expected arm gains runtime-optional storage. A slot that
+        // already admits undefined keeps its own checked representation.
+        if (expected.kind === "union" && this.armTag(expected.unionId, UNDEFINED_T) >= 0)
+            return null;
+        return identityPreservingWidening(this, present, expected)
+            ? this.runtimeOptionalType(expected)
+            : null;
     }
     runtimeOptionalType(t) {
         if (t.kind === "union")
@@ -1407,6 +1444,8 @@ export class Lowerer {
     /** True while re-lowering a base function's 2nd+ instance: the same source
      * statements were already counted for the first instance. */
     suppressStats = false;
+    /** Comparisons interned by operand representations and equality semantics. */
+    equalityHelpers = new Map();
     /** Synthetic array-HOF loop functions (map/filter/forEach desugar),
      * interned per method + element/callback-result type: key → fn name. */
     arrHofHelpers = new Map();
@@ -1498,6 +1537,10 @@ export class Lowerer {
      * node carrying the ?. token is marked handled so the receiver-typed
      * lowerings stop declining it (chainBlocked). */
     chainRecvByNode = new Map();
+    /** Lowered void calls whose checked type is `never` (they throw or exit).
+     * TypeScript lets such a call stand where any value is expected;
+     * coerceToExpected turns them into diverging sequences. */
+    neverValued = new Set();
     chainNarrowedType = new Map();
     chainHandled = new Set();
     /** for-of-over-matchAll bindings whose `.index` reads the companion-index
@@ -1513,6 +1556,7 @@ export class Lowerer {
      * (the ctx guard keeps hidden locals out of closures — a cross-function
      * walk falls back to the plain array walk and the fence). */
     matchAllDrainIndexes = new Map();
+    splitIdentifierUses = new Map();
     /** STORED numeric value iterators: `const it = numbers.values()` (and
      * the equivalent `[Symbol.iterator]()` spelling) over number[] or a
      * represented typed array has no first-class IR value, so its statically
@@ -1528,6 +1572,8 @@ export class Lowerer {
     /** Named method slots observed before class collection need a callable
      * ABI and shared prototype descriptors instead of call-site specialization. */
     prototypeMethodAccesses = new Map();
+    /** Field names whose complete source census stores only lexical arrows. */
+    receiverFreeCallbackFields = new Set();
     /** Inferred JS methods participating in an override chain keep a vtable
      * ABI instead of call-site specialization. Filled before class collection. */
     virtualJsMethods = new Set();
@@ -1601,6 +1647,9 @@ export class Lowerer {
     fileTag = new Map();
     /** Embedded fork roots and their private startup ids. */
     forkTargets;
+    workerTargets;
+    workerTargetIdByPath = new Map();
+    usesWorkers = false;
     forkTargetIdByPath = new Map();
     /** Namespace ModuleBlocks this program lowers, filled by splitFiles:
      * "flattened" — an instantiated namespace whose body joined the file's
@@ -1702,6 +1751,10 @@ export class Lowerer {
      * function called above the declaration statement reads that, never a
      * NULL slot. Filled by collectGlobals. */
     varGlobalEntryInits = new Map();
+    /** Import-cycle bindings with an initialization flag, by global id, and
+     * the top-level statements declaring them (cycle-initialization.ts). */
+    cycleInitFlags = new Map();
+    cycleInitDeclarations = new Map();
     get ctx() {
         const top = this.fnStack[this.fnStack.length - 1];
         if (!top)
@@ -1815,6 +1868,10 @@ export class Lowerer {
         this.startupCrash = mode.startupCrash ?? null;
         this.ffiImports = mode.ffiImports ?? [];
         this.libraryCallbacks = mode.libraryCallbacks ?? false;
+        this.workerTargets = mode.workerTargets ?? [];
+        this.workerTargets.forEach((sf, id) => {
+            this.workerTargetIdByPath.set(tsgoPath(resolve(sf.fileName)), id);
+        });
         this.forkTargets = mode.forkTargets ?? [];
         this.forkTargets.forEach((sf, id) => {
             this.forkTargetIdByPath.set(tsgoPath(resolve(sf.fileName)), id);
@@ -1881,6 +1938,7 @@ export class Lowerer {
                 return { kind: "object", className };
             },
             mixinIntersectionInstance: (widened) => mixinIntersectionInstanceType(this, widened),
+            classImplementedProtocol: (type) => this.classImplementedProtocol(type),
             isStdlibFile: this.isStdlibFile,
             isNpmFile: this.isNpmFile,
             isExternalTypeFile: (sf) => this.externalTypeSpecifiersByFile.has(tsgoPath(resolve(sf.fileName))),
@@ -1910,6 +1968,11 @@ export class Lowerer {
     registerBuiltinErrorClasses() {
         return registerBuiltinErrorClasses(this);
     }
+    classProtocols = null;
+    classImplementedProtocol(type) {
+        this.classProtocols ??= new ClassProtocols(this.checker, this.moduleOrder);
+        return this.classProtocols.usesCheckedIdentity(type);
+    }
     /** The nominal identity of a checker module-namespace type. Program
      * modules use their normalized absolute source name; supported builtins
      * use the lowering tables' canonical bare name. */
@@ -2840,9 +2903,13 @@ export class Lowerer {
      * but it is not a runtime proof; promoting only the affected slots keeps
      * the rest of the dense ABI unchanged. */
     analyzeRuntimeOptionalArrayReads(parts) {
+        const provenance = RuntimeOptionalProvenance.fromEnvironment();
+        // The site whose value the current promotion follows (debug only).
+        let provenanceSite;
         const optionalSymbols = new Set();
         const optionalReturns = new Set();
         const arithmeticReturns = new Map();
+        const primitiveBindings = new Map();
         const optionalParams = new Map();
         const optionalFields = new Map();
         const dynamicObjectEntryRows = new Set();
@@ -2853,7 +2920,7 @@ export class Lowerer {
         // facade's panic fence, then keep lookup free of lowering side effects:
         // resolveValueSymbol also flushes deferred diagnostics and applies
         // merged-namespace fences, whose authority remains ordinary lowering.
-        this.checker.prefetchSymbolRoots(sourceFiles);
+        this.checker.prefetchSymbolRoots(sourceFiles, true);
         const symbolOf = (node) => {
             const s = this.checker.getSymbolAtLocation(node);
             if (!s)
@@ -2869,6 +2936,17 @@ export class Lowerer {
                 (projection?.kind === "declared-function" ? projection.signature : null));
         };
         const functionDeclBySymbol = new Map();
+        const staticFieldsBySymbol = new Map();
+        for (const info of this.classes.values()) {
+            for (const field of info.staticFields) {
+                const declaration = field.initializer.parent;
+                if (!ts.isPropertyDeclaration(declaration))
+                    continue;
+                const symbol = symbolOf(declaration.name);
+                if (symbol)
+                    staticFieldsBySymbol.set(symbol, field);
+            }
+        }
         const signatureBySymbol = new Map();
         const methodFamilies = new Map();
         const familyBySymbol = new Map();
@@ -2965,11 +3043,12 @@ export class Lowerer {
             }
             return false;
         };
-        const isArrayRead = (node) => {
+        const isIndexedRead = (node) => {
             const e = peel(node);
             if (!ts.isElementAccessExpression(e))
                 return false;
-            return this.mapTypeOf(this.typeOf(e.expression))?.kind === "array";
+            const kind = this.mapTypeOf(this.typeOf(e.expression))?.kind;
+            return kind === "array" || kind === "string";
         };
         const isDynamicObjectEntryRead = (node) => {
             const read = peel(node);
@@ -3004,7 +3083,9 @@ export class Lowerer {
             if (explicitlyNonNull(node))
                 return false;
             const e = peel(node);
-            if (isArrayRead(e))
+            if (isIndexedRead(e))
+                return true;
+            if (ts.isPropertyAccessExpression(e) && isOptionalProcessStreamProperty(this, e))
                 return true;
             if (ts.isCallExpression(e) && this.runtimeOptionalReduceTypes.has(e))
                 return true;
@@ -3024,6 +3105,11 @@ export class Lowerer {
                 const symbol = symbolOf(e);
                 return symbol !== null && optionalSymbols.has(symbol);
             }
+            if (ts.isPropertyAccessExpression(e)) {
+                const symbol = symbolOf(e.name);
+                if (symbol && optionalSymbols.has(symbol))
+                    return true;
+            }
             if (ts.isCallExpression(e) && ts.isIdentifier(e.expression)) {
                 const symbol = callableSymbolOf(e.expression);
                 return symbol !== null && optionalReturns.has(symbol);
@@ -3051,11 +3137,31 @@ export class Lowerer {
             }
             return false;
         };
-        const optionalStringArithmeticType = (node) => {
+        const optionalPrimitiveResultType = (node) => {
             const e = peel(node);
-            if (!ts.isBinaryExpression(e) || e.operatorToken.kind !== ts.SyntaxKind.PlusToken)
+            if (ts.isIdentifier(e)) {
+                const symbol = symbolOf(e);
+                return symbol ? (primitiveBindings.get(symbol) ?? null) : null;
+            }
+            if (ts.isCallExpression(e)) {
+                const symbol = callableSymbolOf(e.expression);
+                return symbol ? (arithmeticReturns.get(symbol) ?? null) : null;
+            }
+            if (!ts.isBinaryExpression(e))
                 return null;
-            const stringArrayRead = (part) => {
+            if (e.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken && mayBeOptional(e.left)) {
+                const left = this.mapTypeOf(this.typeOf(e.left));
+                const right = this.mapTypeOf(this.typeOf(e.right));
+                const primitive = (t) => t?.kind === "f64" || t?.kind === "string" || t?.kind === "bool";
+                if (primitive(left) && primitive(right) && !typeEquals(left, right)) {
+                    const arms = [left, right].sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+                    return { kind: "union", unionId: this.unions.intern(arms) };
+                }
+                return null;
+            }
+            if (e.operatorToken.kind !== ts.SyntaxKind.PlusToken)
+                return null;
+            const stringRead = (part) => {
                 const p = peel(part);
                 if (!ts.isElementAccessExpression(p))
                     return false;
@@ -3063,16 +3169,15 @@ export class Lowerer {
                 if (t?.kind !== "string")
                     return false;
                 const recv = this.mapTypeOf(this.typeOf(p.expression));
-                return recv?.kind === "array" && recv.elem.kind === "string";
+                return recv?.kind === "string" || (recv?.kind === "array" && recv.elem.kind === "string");
             };
             const primitive = (part) => {
                 const t = this.mapTypeOf(this.typeOf(part));
                 return t?.kind === "f64" || t?.kind === "string";
             };
-            if (!stringArrayRead(e.left) && !stringArrayRead(e.right))
+            if (!stringRead(e.left) && !stringRead(e.right))
                 return null;
-            if (!(primitive(e.left) || stringArrayRead(e.left)) ||
-                !(primitive(e.right) || stringArrayRead(e.right)))
+            if (!primitive(e.left) || !primitive(e.right))
                 return null;
             return { kind: "union", unionId: this.unions.intern([F64, STRING]) };
         };
@@ -3105,6 +3210,7 @@ export class Lowerer {
                     const symbol = symbolOf(el.name);
                     if (symbol && !el.initializer && !optionalSymbols.has(symbol)) {
                         optionalSymbols.add(symbol);
+                        provenance?.note("pattern-binding", el.name, init);
                         // Indexed flow facts can survive a mutating method call in the
                         // checker. The array's element ABI describes every value a
                         // position may hold after that call, so bind from that type.
@@ -3248,6 +3354,7 @@ export class Lowerer {
                         const widened = this.runtimeOptionalType(current);
                         const previous = this.runtimeOptionalBindingTypes.get(symbol);
                         this.runtimeOptionalBindingTypes.set(symbol, widened);
+                        provenance?.note("callback-parameter", parameter.name, provenanceSite);
                         if (!previous || !typeEquals(previous, widened))
                             changed = true;
                         if (!optionalSymbols.has(symbol)) {
@@ -3259,6 +3366,7 @@ export class Lowerer {
                 const fnType = this.mapTypeOf(this.typeOf(fn));
                 if (fnType?.kind === "func" && bodyReturnsOptional(fn)) {
                     const widenedReturn = this.runtimeOptionalType(fnType.ret);
+                    provenance?.note("callback-return", fn, provenanceSite);
                     const previousReturn = this.runtimeOptionalFunctionReturnType(fn, fnType.ret);
                     this.runtimeOptionalFunctionReturns.set(fn, widenedReturn);
                     if (!typeEquals(previousReturn, widenedReturn))
@@ -3391,6 +3499,16 @@ export class Lowerer {
             const scan = (node) => {
                 if (ts.isVariableDeclaration(node)) {
                     if (node.initializer) {
+                        const result = optionalPrimitiveResultType(node.initializer);
+                        const symbol = ts.isIdentifier(node.name) ? symbolOf(node.name) : null;
+                        if (result?.kind === "union" && symbol) {
+                            const before = primitiveBindings.get(symbol);
+                            if (!before || !typeEquals(before, result)) {
+                                primitiveBindings.set(symbol, result);
+                                this.runtimeOptionalBindingTypes.set(symbol, result);
+                                changed = true;
+                            }
+                        }
                         if (ts.isIdentifier(node.name) && isDynamicObjectEntryRead(node.initializer)) {
                             const symbol = symbolOf(node.name);
                             if (symbol && !dynamicObjectEntryRows.has(symbol)) {
@@ -3402,6 +3520,7 @@ export class Lowerer {
                             const symbol = symbolOf(node.name);
                             if (symbol && !optionalSymbols.has(symbol)) {
                                 optionalSymbols.add(symbol);
+                                provenance?.note("binding", node.name, node.initializer);
                                 changed = true;
                             }
                         }
@@ -3422,6 +3541,8 @@ export class Lowerer {
                                 const aliasNew = !optionalReturns.has(symbol);
                                 if (aliasNew)
                                     optionalReturns.add(symbol);
+                                if (aliasNew)
+                                    provenance?.note("function-alias", node.name, node.initializer);
                                 if (aliasNew)
                                     changed = true;
                                 const valueType = this.mapTypeOf(this.typeOf(node.name));
@@ -3457,8 +3578,10 @@ export class Lowerer {
                                 const value = ts.isPropertyAssignment(prop)
                                     ? prop.initializer
                                     : prop.name;
-                                if (mayBeOptional(value) && noteField(node, name.text))
+                                if (mayBeOptional(value) && noteField(node, name.text)) {
+                                    provenance?.note("literal-field", name, value);
                                     changed = true;
+                                }
                             }
                         }
                     }
@@ -3473,14 +3596,24 @@ export class Lowerer {
                         const symbol = symbolOf(node.left);
                         if (symbol && !optionalSymbols.has(symbol)) {
                             optionalSymbols.add(symbol);
+                            provenance?.note("assigned-binding", node.left, node.right);
                             changed = true;
                         }
                     }
-                    else if (ts.isPropertyAccessExpression(node.left) &&
-                        ts.isIdentifier(node.left.expression)) {
-                        const symbol = symbolOf(node.left.expression);
-                        if (symbol && noteFieldSymbol(symbol, node.left.name.text))
+                    else if (ts.isPropertyAccessExpression(node.left)) {
+                        const field = symbolOf(node.left.name);
+                        if (field && staticFieldsBySymbol.has(field) && !optionalSymbols.has(field)) {
+                            optionalSymbols.add(field);
+                            provenance?.note("static-field", node.left, node.right);
                             changed = true;
+                        }
+                        else if (ts.isIdentifier(node.left.expression)) {
+                            const symbol = symbolOf(node.left.expression);
+                            if (symbol && noteFieldSymbol(symbol, node.left.name.text)) {
+                                provenance?.note("assigned-field", node.left, node.right);
+                                changed = true;
+                            }
+                        }
                     }
                 }
                 if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
@@ -3521,6 +3654,7 @@ export class Lowerer {
                             }
                         }
                         if (nativeArrayReceiver) {
+                            provenanceSite = node;
                             if (promoteHofCallback(callback, callbackIndices))
                                 changed = true;
                             const method = node.expression.name.text;
@@ -3571,6 +3705,7 @@ export class Lowerer {
                                     continue;
                                 shape.type = widened;
                                 const parameter = functionDeclBySymbol.get(target)?.parameters[i];
+                                provenance?.note("parameter", parameter, node, "(omitted or undefined argument)");
                                 if (parameter) {
                                     for (const bound of boundIdentifiersOf(parameter.name)) {
                                         const boundSymbol = symbolOf(bound);
@@ -3595,6 +3730,7 @@ export class Lowerer {
                         const callbackSlot = shape?.type;
                         if (callbackSlot?.kind === "func" && !ts.isSpreadElement(arg)) {
                             const optionalCallbackParams = callbackSlot.params.flatMap((type, index) => type.kind === "union" && this.armTag(type.unionId, UNDEFINED_T) >= 0 ? [index] : []);
+                            provenanceSite = node;
                             if (optionalCallbackParams.length > 0 &&
                                 promoteHofCallback(arg, optionalCallbackParams)) {
                                 changed = true;
@@ -3615,6 +3751,7 @@ export class Lowerer {
                                     continue;
                                 rest.type = widened;
                                 const parameter = functionDeclBySymbol.get(target)?.parameters[i];
+                                provenance?.note("rest-parameter", parameter, arg);
                                 if (parameter && ts.isIdentifier(parameter.name)) {
                                     const bound = symbolOf(parameter.name);
                                     if (bound)
@@ -3643,6 +3780,7 @@ export class Lowerer {
                             if (set.size !== before) {
                                 changed = true;
                                 const parameter = functionDeclBySymbol.get(target)?.parameters[i];
+                                provenance?.note("parameter", parameter, arg, target === symbol ? "" : "(override)");
                                 if (parameter) {
                                     for (const bound of boundIdentifiersOf(parameter.name)) {
                                         const boundSymbol = symbolOf(bound);
@@ -3666,9 +3804,10 @@ export class Lowerer {
             for (const expression of returnsOf(decl)) {
                 if (mayBeOptional(expression) && !optionalReturns.has(symbol)) {
                     optionalReturns.add(symbol);
+                    provenance?.note("return", decl.name ?? decl, expression);
                     changed = true;
                 }
-                const arithmetic = optionalStringArithmeticType(expression);
+                const arithmetic = optionalPrimitiveResultType(expression);
                 if (arithmetic && !arithmeticReturns.has(symbol)) {
                     arithmeticReturns.set(symbol, arithmetic);
                     changed = true;
@@ -3679,6 +3818,13 @@ export class Lowerer {
         let changed = true;
         while (changed) {
             changed = false;
+            for (const [symbol, field] of staticFieldsBySymbol) {
+                if (!optionalSymbols.has(symbol) && mayBeOptional(field.initializer)) {
+                    optionalSymbols.add(symbol);
+                    provenance?.note("static-field", field.initializer.parent, field.initializer);
+                    changed = true;
+                }
+            }
             for (const sf of sourceFiles)
                 if (scanFile(sf))
                     changed = true;
@@ -3710,11 +3856,27 @@ export class Lowerer {
                 for (const symbol of family) {
                     if (!optionalReturns.has(symbol)) {
                         optionalReturns.add(symbol);
+                        provenance?.note("return", functionDeclBySymbol.get(symbol), undefined, "(override family)");
                         changed = true;
                     }
                 }
             }
         }
+        const globalsById = new Map(this.globalsList.map((global) => [global.id, global]));
+        for (const [symbol, field] of staticFieldsBySymbol) {
+            if (!optionalSymbols.has(symbol))
+                continue;
+            const promoted = addUndefined(field.type);
+            // An explicit optional annotation already has the right layout, but
+            // an indexed assignment still invalidates the checker's presence fact.
+            field.type = promoted;
+            field.runtimeOptional = true;
+            const global = globalsById.get(field.globalId);
+            if (global) {
+                global.type = promoted;
+                this.runtimeOptionalGlobals.add(global);
+            }
+        }
         for (const [symbol, sig] of signatureBySymbol) {
             const params = optionalParams.get(symbol);
             if (params) {
@@ -3846,6 +4008,7 @@ export class Lowerer {
                 }
             });
         }
+        provenance?.flush();
     }
     run() {
         const parts = this.splitFiles();
@@ -3928,7 +4091,7 @@ export class Lowerer {
         // generic classes, generic methods calling generic functions) — the
         // index loops run to the joint fixpoint. Same-key recursion re-uses
         // its own entry; polymorphic recursion is cut off by
-        // MAX_GENERIC_INSTANCES.
+        // the recursive instantiation demand path.
         {
             let ec = 0;
             let gc = 0;
@@ -4089,6 +4252,7 @@ export class Lowerer {
         // the emitted program references, flushing deferred class diagnostics
         // that a reached type makes relevant.
         const artifacts = this.moduleArtifacts(functions);
+        refuseUncheckedCycleReads(this, artifacts.classes ?? []);
         // Types still naming a class that never REGISTERED after retention's
         // flush (JS graphs whose class fences deferred to runtime — the
         // sentence-walker's path params, printer tables whose func-typed
@@ -4103,7 +4267,7 @@ export class Lowerer {
         const module = this.diags.length > 0
             ? null
             : {
-                irVersion: 13,
+                irVersion: 15,
                 sourceFile: this.entry.fileName,
                 functions,
                 classes: artifacts.classes,
@@ -4112,10 +4276,13 @@ export class Lowerer {
                 globals: this.globalsList,
                 ...(this.npmEmbedded ? { embedded: this.npmEmbedded } : {}),
                 entry: ENTRY_NAME,
+                ...(this.usesWorkers ? { workers: true } : {}),
                 ...(this.ffiImports.length > 0 ? { ffiImports: [...this.ffiImports] } : {}),
             };
         if (module)
             sanitizeUnregisteredClassTypes(module, (name) => this.classes.has(name));
+        if (module)
+            checkCycleBindingAccesses(this, module);
         return {
             module,
             diagnostics: this.diags,
@@ -4712,6 +4879,7 @@ export class Lowerer {
         // globals pre-register before their initializers lower) — an exact
         // duplicate (code + span + message) adds noise, not information.
         if (this.diags.some((p) => p.code === d.code &&
+            p.loc.file === d.loc.file &&
             p.loc.start === d.loc.start &&
             p.loc.end === d.loc.end &&
             p.message === d.message)) {
@@ -4914,9 +5082,8 @@ export class Lowerer {
                 'new Intl.NumberFormat("en-US").format(x) and x.toLocaleString("en-US") with default options; ' +
                 "the rest is ICU locale data the binary does not carry";
             const typeHints = {
-                ArrayBuffer: "no free-standing ArrayBuffer value exists — typed arrays own their storage " +
-                    "(new Uint8Array(n) allocates; new Uint8Array(new ArrayBuffer(n)) erases the buffer into the view)",
-                SharedArrayBuffer: "no shared-memory threads exist in a compiled program — Uint8Array is the byte storage",
+                ArrayBuffer: "fixed ArrayBuffer storage and typed-array views are supported; resizable and detached storage are not modeled",
+                SharedArrayBuffer: "fixed SharedArrayBuffer storage is supported; growable shared storage is not modeled",
                 NumberFormat: intlHint,
                 DateTimeFormat: intlHint,
                 DurationFormat: intlHint,
@@ -5025,6 +5192,9 @@ export class Lowerer {
             if (arm !== undefined)
                 return arm;
         }
+        const collection = concreteCollectionNarrow(this, node, t);
+        if (collection)
+            return collection;
         // IMPLICIT-ANY instance bodies: an identifier reference to a BOUND
         // param answers the call site's concrete type wherever the checker
         // still says `any` (there is no `T` for mapType to substitute — the
@@ -5348,6 +5518,11 @@ export class Lowerer {
             this.pushDiag(recordShapeMismatchDiag(this.fmt(expected), this.fmt(actual), locOf(node), detail));
             throw new PoisonError();
         }
+        // Iterator-typed slots hold generators and built-in collection
+        // iterators; any other iterator object (a user class) stays fenced.
+        if (expected.kind === "generator" && actual.kind !== "generator") {
+            this.unsupported("SC1090", node, `'${this.fmt(actual)}' values in an iterator-typed slot (Iterator and IterableIterator slots hold generators and built-in collection iterators)`);
+        }
         // Everything else — a plain-kind mismatch like a string flowing into a
         // class-instance slot — is tsc-rejected in the lowering world and only
         // reaches here through preflight's project-world second chance (e.g. a
@@ -5403,6 +5578,21 @@ export class Lowerer {
         }
         return literalUnionArm(def, values, (id) => this.shapes.get(id), cached.owners);
     }
+    /** Widen only the result view; identical parameter ABIs preserve closure identity. */
+    coerceCovariantFunction(expr, expected) {
+        if (expr.type.kind === "func" &&
+            expected.kind === "func" &&
+            expr.type.rest === expected.rest &&
+            expr.type.restAbi === expected.restAbi &&
+            expr.type.argumentsAll === expected.argumentsAll &&
+            expr.type.params.length === expected.params.length &&
+            expr.type.params.every((type, i) => typeEquals(type, expected.params[i])) &&
+            expr.type.ret.kind === "object" &&
+            expected.ret.kind === "object" &&
+            this.isSubclassOf(expr.type.ret.className, expected.ret.className))
+            return { kind: "upcast", value: expr, type: expected, loc: expr.loc };
+        return null;
+    }
     /** Implicit union construction. Wherever a value flows into a typed slot
      * (initializer, assignment, call argument, return, field write, record
      * literal field, ternary arm) whose expected type is a union and the
@@ -5411,6 +5601,15 @@ export class Lowerer {
      * else (including a DIFFERENT union) is left for requireExactShape, which
      * rejects union mismatches with SC2003. */
     coerceToExpected(expr, expected) {
+        if (expr.type.kind === "void" && expected.kind !== "void" && this.neverValued.has(expr))
+            return this.divergentValue(expr, expected);
+        // Iterator-typed slots: native iterators and differently typed
+        // generators step through an adapter generator.
+        if (expected.kind === "generator" && !typeEquals(expr.type, expected)) {
+            const adapted = iteratorSlotAdapter(this, expr, expected);
+            if (adapted)
+                return adapted;
+        }
         // Island boundary, both directions. IN: any static value flowing into
         // an any-typed slot marshals implicitly (tsc allows the assignment;
         // the marshal is where its semantics live). OUT: an 'any' value
@@ -5670,6 +5869,9 @@ export class Lowerer {
                 return { kind: "call", callee: adapter, args: [expr], type: expected, loc: expr.loc };
             }
         }
+        const covariant = this.coerceCovariantFunction(expr, expected);
+        if (covariant)
+            return covariant;
         // The GENERAL function-value adapter (funcCoerceAdapter): a function
         // whose signature differs from the slot's only by coercible pieces —
         // fewer parameters (JS ignores extras: `load(function () {})` into an
@@ -5693,6 +5895,31 @@ export class Lowerer {
             this.isSubclassOf(expr.type.className, expected.className)) {
             return { kind: "upcast", value: expr, type: expected, loc: expr.loc };
         }
+        // Optional subclass storage still has the same object payload. Extract
+        // it with a checked tag test, then widen the class view without copying.
+        if (expected.kind === "object" && expr.type.kind === "union") {
+            const arms = this.unions.get(expr.type.unionId)?.arms;
+            const present = arms?.filter((arm) => !isUnitType(arm)) ?? [];
+            if (present.length === 1 &&
+                present[0].kind === "object" &&
+                present[0].className !== expected.className &&
+                this.isSubclassOf(present[0].className, expected.className)) {
+                // One class arm: the ordinary checked narrow reports a missing value
+                // exactly like same-class storage before the prefix view widens it.
+                return {
+                    kind: "upcast",
+                    value: this.coerceToExpected(expr, present[0]),
+                    type: expected,
+                    loc: expr.loc,
+                };
+            }
+            if (present.length > 1 &&
+                present.every((arm) => identityPreservingWidening(this, arm, expected))) {
+                const view = checkedClassAssertion(this, expr, expected, expr.loc);
+                if (view)
+                    return view;
+            }
+        }
         // CLASS-VALUE widening (classval:D into a classval:C slot): the same
         // pointer with only the static type changing — legal exactly when D
         // strictly descends from C AND the two completed constructor ABIs
@@ -6075,6 +6302,17 @@ export class Lowerer {
                 loc: expr.loc,
             }
             : this.coerceToExpected(expr, expected);
+        // Keep storage intact when ordinary widening already accepts it. Only
+        // a destination needing a more specific class layout uses the site's
+        // refinement and checked extraction.
+        if (!typeEquals(e.type, expected) &&
+            (expected.kind === "object" || expected.kind === "union")) {
+            const site = e.type.kind === "union" ? this.mapTypeOf(this.typeOf(node)) : null;
+            const narrowed = (site && narrowStoredClassValue(this, e, site)) ??
+                narrowGenericClassValue(this, e, expected);
+            if (narrowed)
+                e = this.coerceToExpected(narrowed, expected);
+        }
         // Existing JavaScript arrays retain mutations and identity across checked
         // slots. Fresh literals have no prior identity and use checked storage
         // directly, so later writes can change their inferred element type.
@@ -6663,6 +6901,42 @@ export class Lowerer {
     wrappedUndefined(type, loc) {
         return wrappedUndefined(this, type, loc);
     }
+    /** The value an OMITTED or deleted property leaves in a record field
+     * slot of `type`: the ABSENT state for undefined-armed unions (the slot
+     * reads as undefined but the property does not exist), the dyn
+     * undefined for 'unknown' slots, and null when the slot cannot be
+     * missing. Only legal as a direct field-slot write (IR fieldAbsent). */
+    absentFieldValue(type, loc) {
+        if (type.kind === "union" && this.armTag(type.unionId, UNDEFINED_T) >= 0) {
+            return { kind: "fieldAbsent", unionId: type.unionId, type, loc };
+        }
+        return this.wrappedUndefined(type, loc);
+    }
+    /** A field copy that keeps absence: `value` (the converted read of
+     * `field` from record `obj`, which must be repeatable) when the source
+     * property exists, else the target slot's ABSENT state. Fields that are
+     * always present, and targets that cannot be absent, copy `value`
+     * as-is. Only legal as a direct field-slot write. */
+    presenceKeepingCopy(obj, shapeId, field, value, loc) {
+        const present = this.recordFieldPresent(obj, shapeId, field, loc);
+        if (present.kind !== "recordHas")
+            return value;
+        const absent = this.absentFieldValue(value.type, loc);
+        if (absent?.kind !== "fieldAbsent")
+            return value;
+        return { kind: "ternary", cond: present, then: value, else_: absent, type: value.type, loc };
+    }
+    /** Own-property presence of declared field `field` on record `obj`
+     * (borrowed — callers pass a repeatable receiver): a runtime test for
+     * undefined-armed union fields, which can be absent, and `true` for
+     * every other declared field. */
+    recordFieldPresent(obj, shapeId, field, loc) {
+        const f = this.shapes.get(shapeId)?.fields.find((x) => x.name === field);
+        if (f && f.type.kind === "union" && this.armTag(f.type.unionId, UNDEFINED_T) >= 0) {
+            return { kind: "recordHas", obj, shapeId, field, type: BOOL, loc };
+        }
+        return { kind: "boolLit", value: true, type: BOOL, loc };
+    }
     /** The entry value of a binding JS initializes to `undefined` (an
      * initializer-less declaration, a hoisted `var` before its statement):
      * undefined-armed unions hold the interned undefined arm, and 'any'
@@ -6957,6 +7231,8 @@ export class Lowerer {
      * instance table. Filled by collectClassShapeInner's family mode;
      * consulted by mapType's genericClassInstance hook. */
     genericClassByDecl = new Map();
+    /** Forward generic references may demand a family before its declaration turn. */
+    collectingClassDeclarations = new Set();
     /** Instantiations in demand order — the member-lowering worklist run()'s
      * monomorphization fixpoint drains (an instantiation's methods can
      * demand further instances of either kind). */
@@ -7065,6 +7341,32 @@ export class Lowerer {
     declareLocal(nameNode, name, type, mutable) {
         return declareContextLocal(this.ctx, name, type, mutable, this.checker.getSymbolAtLocation(nameNode), bindingSource(nameNode));
     }
+    /** A never-returning call in a value position of type `expected`: the
+     * call runs for its effects (it throws or exits), and the expression ends
+     * in an unreachable trap instead of producing a value. The result reads an
+     * uninitialized hidden local that control never reaches. */
+    divergentValue(call, expected) {
+        const loc = call.loc;
+        const slot = this.declareHiddenLocal("%never", expected);
+        slot.mutable = true;
+        return {
+            kind: "seqExpr",
+            stmts: [
+                { kind: "exprStmt", expr: call, loc },
+                { kind: "varDecl", localId: slot.id, init: null, loc },
+                {
+                    kind: "runtimeFence",
+                    code: "SC9002",
+                    message: "unreachable: a 'never' call returned — please report this",
+                    loc,
+                },
+            ],
+            result: varRef(slot.id, expected, loc),
+            diverges: true,
+            type: expected,
+            loc,
+        };
+    }
     /** A function-scope local bound to NO ts.Symbol — the hidden ABI slot of a
      * defaulted parameter (the parameter's symbol binds to the separately-
      * declared body local; nothing in the source can name this one). */
@@ -8167,8 +8469,8 @@ export class Lowerer {
     lambdaSignature(node) {
         return lambdaSignature(this, node);
     }
-    lowerLambda(node) {
-        return lowerLambda(this, node);
+    lowerLambda(node, checkedReceiver = false) {
+        return lowerLambda(this, node, checkedReceiver);
     }
     lowerArrayMethodCall(call, access) {
         return lowerArrayMethodCall(this, call, access);
@@ -8537,6 +8839,11 @@ export class Lowerer {
         if (bi.module === "events" && bi.member === "defaultMaxListeners") {
             return { kind: "libCall", fn: "emitter.getDefaultMax", args: [], type: F64, loc };
         }
+        if (bi.module === "worker_threads") {
+            const value = lowerWorkerMetadata(bi.member, loc);
+            if (value)
+                return value;
+        }
         const c = builtinModuleConstOf(this, bi.module, bi.member);
         if (c !== undefined)
             return builtinConstLit(c, loc);