@scriptc/compiler 0.2.6 → 0.2.8

package/dist/frontend/lowering/lowerer.js

@@ -1,14 +1,28 @@
+import { checkCycleBindingAccesses, refuseUncheckedCycleReads, } from "./cycle-initialization.js";
+import { identityPreservingWidening } from "./coercions/identity.js";
+import { scanDivergences } from "./divergences.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";
 import { widthCoerce, applyWidthLift, unionRecordWidthHelper, recordWidthHelper, tupleArrayWidthHelper, emptyArrayLiftHelper, arrayWidthHelper, objRecordWidthHelper, recordClassWidthHelper, classStaticsProjection, } from "./coercions/structural.js";
 import { funcReturnWidthAdapter, coercibleValue, cleanFuncAdaptable, funcCoerceAdapter, spawnResFnAdapterPlan, spawnResFnAdapter, } from "./coercions/function-adapters.js";
-import { unionRetagMappable, narrowedRetagHelper, strandedUnitTrap, strandedCoercionTrap, recordUnionWrapHelper, unionRetagHelper, narrowedArmHelper, deferredReadHelper, } from "./coercions/unions.js";
+import { unionRetagMappable, narrowedRetagHelper, strandedUnitTrap, strandedCoercionTrap, recordUnionWrapHelper, unionRetagHelper, narrowedArmHelper, checkedNarrowCall, checkedNarrowOperand, deferredReadHelper, } from "./coercions/unions.js";
 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 { presentAtUse, reassignedBindings } from "./runtime-optional-guards.js";
+import { ArrayElementStates } from "./runtime-optional-elements.js";
+import { indexReadInBounds } from "./runtime-optional-bounds.js";
+import { ArrayOwnership } from "./runtime-optional-ownership.js";
+import { StringIndexBounds } from "./string-index-bounds.js";
 import { RuntimeOptionalLocals } from "./runtime-optional-locals.js";
 import { sanitizeUnregisteredClassTypes } from "./sanitize-class-types.js";
 import { UnregisteredClassTypes } from "./unregistered-class-types.js";
@@ -44,7 +58,7 @@ import { anyOpRequiresDynamicDiag, blockedBindingUseDiag, checkerPanicDiag, comp
 import { arrayOf, BOOL, canAdaptDynFuncTo, canDynCheckTo, canConvertToDyn, canCrossIslandBoundary, canExitIslandToType, canMarshalTypedFuncIntoIsland, DYN, DYN_HANDLE_KINDS, F64, isDynTypedRefType, isJsonSafeType, isJsonStringifySafeType, isPrimitiveCollectionKey, isSupportedMapKey, isSupportedMapValue, isUndefinedArmedUnion, isUnitType, JSVAL, NULL_T, RUNTIME_ERROR_CLASSES, STRING, typeEquals, UNDEFINED_T, VOID, } from "../../ir/ir.js";
 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 { containsRecord, containsUnion, describeComponentBlocker, describeRecordMemberBlocker, formatIrType, ISLAND_AMBIENT_TYPES, isUnitOnlyTsType, isWorkerHandleType, 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, appendWorkerModules, } from "./lower-modules.js";
 import { prepareCjsModuleGraph } from "./lower-node-module.js";
@@ -189,6 +203,39 @@ export function stmtUsesIsland(stmts) {
         return !stmts.every((stmt) => everyStmtChild(stmt, expr, nested));
     return !everyStmtChild(stmts, expr, nested);
 }
+/** Statements a never-lowered body would have contributed to the coverage
+ * totals: every element of a statement list (blocks, case clauses), plus
+ * the single-statement bodies of control flow, nested functions included —
+ * the same accounting lowerStmts applies to bodies that do lower. */
+export function countBodyStatements(root) {
+    let n = 0;
+    const visit = (node) => {
+        if (ts.isBlock(node) || ts.isCaseClause(node) || ts.isDefaultClause(node)) {
+            n += node.statements.length;
+        }
+        else if ((ts.isIfStatement(node) ||
+            ts.isForStatement(node) ||
+            ts.isForInStatement(node) ||
+            ts.isForOfStatement(node) ||
+            ts.isWhileStatement(node) ||
+            ts.isDoStatement(node) ||
+            ts.isLabeledStatement(node)) &&
+            node.parent !== undefined) {
+            const bodies = ts.isIfStatement(node)
+                ? [node.thenStatement, node.elseStatement]
+                : ts.isLabeledStatement(node)
+                    ? [node.statement]
+                    : [node.statement];
+            for (const body of bodies) {
+                if (body !== undefined && !ts.isBlock(body) && !ts.isIfStatement(body))
+                    n++;
+            }
+        }
+    };
+    // Iterative: absurdly deep nesting must not overflow the stack here.
+    ts.walkPreorder(root, visit);
+    return n;
+}
 function directExternalTypeSpecifiersByFile(externalTypes) {
     const out = new Map();
     for (const [specifier, file] of externalTypes) {
@@ -341,6 +388,12 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
         resultLowerer = emit;
         timing("historical-order-relower");
     }
+    // Divergence warnings over the program's own modules: computed once,
+    // after lowering, from the same checker (never part of a failure).
+    const divergences = scanDivergences(resultLowerer, moduleOrder);
+    timing("divergence-scan", { found: divergences.length });
+    if (divergences.length > 0)
+        result = { ...result, divergences };
     if (options.coverage !== true)
         return result;
     const remainder = new Lowerer(program, entry, moduleOrder, dynamic, {
@@ -358,7 +411,17 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
         externalTypeSpecifiersByFile,
     });
     const rem = remainder.run();
-    return { ...result, unreached: { diagnostics: rem.diagnostics, stats: rem.stats } };
+    // Unreached JS statements whose fences deferred to runtime count as
+    // failed statements in the remainder's stats, so their diagnostics must
+    // travel with them: a failed statement is never left unexplained.
+    return {
+        ...result,
+        unreached: {
+            diagnostics: rem.diagnostics,
+            stats: rem.stats,
+            ...(rem.runtimeFences.length > 0 ? { runtimeFences: rem.runtimeFences } : {}),
+        },
+    };
 }
 /** The island-handle type a `import(...)` initializer gives a binding
  * whose DECLARED type has no static mapping (`Promise<typeof
@@ -874,6 +937,17 @@ export function jsFuncNameOf(node, lowerer) {
     }
     return null;
 }
+/** Answers `fallback` when a checker query panics inside the type checker. */
+function panicSafe(query, fallback) {
+    try {
+        return query();
+    }
+    catch (e) {
+        if (isCheckerPanic(e))
+            return fallback;
+        throw e;
+    }
+}
 export class Lowerer {
     program;
     entry;
@@ -902,6 +976,14 @@ export class Lowerer {
     /** Per-symbol result of the never-reassigned file scan
      * (bindingNeverReassigned — object-literal generic-method receivers). */
     neverReassignedCache = new Map();
+    stringIndexBoundsCache = null;
+    /** Proofs that a string element read names an existing code unit. The
+     * indexed-read analysis and expression lowering share one instance, so a
+     * read's representation and its callers' signatures always agree. */
+    get stringIndexBounds() {
+        this.stringIndexBoundsCache ??= new StringIndexBounds((node) => this.checker.getSymbolAtLocation(node) ?? null, (symbol) => this.checker.valueDeclarationOf(symbol), (node) => (this.typeOf(node).flags & ts.TypeFlags.StringLike) !== 0);
+        return this.stringIndexBoundsCache;
+    }
     /** Syntactic writes indexed once per JS scope. Symbol and RHS type
      * checks remain contextual to each binding probe. */
     jsBindingWritesByOwner = new Map();
@@ -1148,6 +1230,11 @@ export class Lowerer {
      * prepass. This includes explicit annotations: unchecked TS annotations do
      * not prove that an array property read produced a value. */
     runtimeOptionalBindingTypes = new Map();
+    /** Bindings that receive an unchecked indexed read (or a value derived
+     * from one) through an initializer or assignment. The checker narrows a
+     * declared optional binding to that read's bare type, so presence tests
+     * on these bindings consult the stored tag instead. */
+    runtimeOptionalAssignedSymbols = new Set();
     /** Concise callback/lambda returns promoted by the HOF callback prepass;
      * arrows have no declaration symbol to key in fnSigsBySymbol. */
     runtimeOptionalFunctionReturns = new Map();
@@ -1165,6 +1252,17 @@ export class Lowerer {
      * every name destructured from a present source optional. */
     runtimeOptionalPatternTypes = new Map();
     runtimeOptionalReduceTypes = new Map();
+    /** Non-null assertions whose value is forwarded into a slot promoted to
+     * hold undefined. `x!` has no runtime effect, so these keep the stored
+     * undefined state instead of trapping before any dereference. */
+    runtimeOptionalAssertions = new Set();
+    /** Array callback calls whose receiver the optional-read analysis proved
+     * never holds an explicit undefined (or a hole, for the find family):
+     * their callbacks take the element type itself. */
+    presentElementCalls = new Set();
+    /** for-of loops over arrays that can hold neither holes nor undefined:
+     * each pass reads the element payload directly. */
+    presentElementLoops = new Set();
     /** Capture entries and their origin share one mutable box. Normalize each
      * entry to the origin so writes and flow proofs stay synchronized. */
     runtimeOptionalRoots = new Map();
@@ -1239,6 +1337,9 @@ export class Lowerer {
      * optional-read analysis, so ordinary assertions keep their generic
      * checked-narrow behavior. */
     runtimeOptionalSourceValue(node, value) {
+        const slot = this.deferredFieldSlot(value);
+        if (slot)
+            return slot;
         let origin = node;
         while (ts.isParenthesizedExpression(origin))
             origin = origin.expression;
@@ -1273,12 +1374,9 @@ export class Lowerer {
             value.value.type.kind === "dyn")
             return value.value;
         let source = value;
-        if (value.kind === "call" &&
-            this.coercions.checkedNarrows.has(value.callee) &&
-            value.args.length === 1 &&
-            value.args[0]?.type.kind === "union") {
-            source = value.args[0];
-        }
+        const narrowed = checkedNarrowOperand(this, value);
+        if (narrowed?.type.kind === "union")
+            source = narrowed;
         return source.type.kind === "union" && this.armTag(source.type.unionId, UNDEFINED_T) >= 0
             ? source
             : null;
@@ -1358,7 +1456,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")
@@ -1382,6 +1489,41 @@ export class Lowerer {
     runtimeOptionalFunctionReturnType(node, fallback) {
         return this.runtimeOptionalFunctionReturns.get(node) ?? fallback;
     }
+    /** True when `actual` is `declared` with some record fields (directly,
+     * in nested records, or in an array's element records) widened to runtime-optional unions:
+     * fields filled from unchecked indexed reads the checker calls present.
+     * Inferred bindings and destructured parameters keep that layout instead
+     * of narrowing it away. */
+    isRuntimeOptionalRecordVariant(actual, declared) {
+        if (actual.kind === "array" && declared.kind === "array")
+            return this.isRuntimeOptionalRecordVariant(actual.elem, declared.elem);
+        if (actual.kind !== "record" || declared.kind !== "record")
+            return false;
+        if (actual.shapeId === declared.shapeId)
+            return false;
+        const a = this.shapes.get(actual.shapeId);
+        const d = this.shapes.get(declared.shapeId);
+        if (!a || !d || a.fields.length !== d.fields.length || !!a.tuple !== !!d.tuple)
+            return false;
+        if (a.indexValue || d.indexValue)
+            return false;
+        let widened = false;
+        for (const field of d.fields) {
+            const source = a.fields.find((f) => f.name === field.name);
+            if (!source)
+                return false;
+            if (typeEquals(source.type, field.type))
+                continue;
+            if (this.isRuntimeOptionalField(actual.shapeId, field.name) &&
+                (this.runtimeOptionalWidening(source.type, field.type) !== null ||
+                    this.isRuntimeOptionalRecordVariant(source.type, field.type))) {
+                widened = true;
+                continue;
+            }
+            return false;
+        }
+        return widened;
+    }
     /** Promote one field of a record storage shape to the value's runtime
      * type. Shapes are immutable by identity, so this interns a sibling shape
      * and records the field as runtime-optional for property-read narrowing. */
@@ -1427,6 +1569,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();
@@ -1518,6 +1662,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
@@ -1549,6 +1697,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();
@@ -1674,6 +1824,9 @@ export class Lowerer {
      * and therefore becomes the cycle's evaluation root. Dynamic imports
      * wait on this shared verdict rather than a build-time-selected member. */
     asyncCyclePromiseOf = new Map();
+    /** Modules whose evaluation an import() can request again after it threw,
+     * computed on first use (lower-modules.ts importRetryModules). */
+    importRetryModules = null;
     /** Record-shape interner: canonical (name-sorted) field list → shapeId.
      * Threaded into every mapType call; its `shapes` array becomes
      * IrModule.records. */
@@ -1726,6 +1879,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)
@@ -1766,6 +1923,13 @@ export class Lowerer {
      * coverage remainder as alreadyFlushed). */
     flushedSymbols = new Set();
     alreadyFlushed;
+    /** Deferred diagnostics a flush handed to a capture buffer (diagSink)
+     * instead of the build, keyed by the copy in that buffer. A buffer can
+     * be discarded (a declined probe, a collection that succeeded) or
+     * re-deferred under another declaration, so the declaration stays
+     * deferred until one of these copies reaches `diags` (pushDiag commits
+     * it); until then a later flush reports the diagnostics again. */
+    pendingFlushes = new Map();
     /** The build's target platform ("win32" | "darwin" | "linux" | ...):
      * selects the platform-keyed builtin surfaces (builtinModuleFnsOf /
      * builtinModuleConstOf in surfaces.ts). */
@@ -1944,6 +2108,12 @@ export class Lowerer {
         this.classProtocols ??= new ClassProtocols(this.checker, this.moduleOrder);
         return this.classProtocols.usesCheckedIdentity(type);
     }
+    /** Declared class fields may store a DYN value only when its static type
+     * names checked protocol identity or an owned runtime handle (a Worker
+     * or MessagePort); `unknown` and `any` fields stay refused. */
+    classFieldStoresDyn(type) {
+        return this.classImplementedProtocol(type) || isWorkerHandleType(type, this.typeCtx);
+    }
     /** 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. */
@@ -2874,9 +3044,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();
@@ -2903,6 +3077,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();
@@ -2999,11 +3184,76 @@ export class Lowerer {
             }
             return false;
         };
-        const isArrayRead = (node) => {
+        // `parent!` passed to a call or bound to a name forwards the value
+        // without reading it: a callee that never dereferences it observes
+        // undefined, as in JavaScript. Only a class value with one undefined
+        // arm qualifies; element reads keep the established bounds trap.
+        const forwardedAssertion = (node) => {
+            let e = node;
+            while (ts.isParenthesizedExpression(e))
+                e = e.expression;
+            if (!ts.isNonNullExpression(e))
+                return null;
+            let operand = e.expression;
+            while (ts.isParenthesizedExpression(operand))
+                operand = operand.expression;
+            if (ts.isElementAccessExpression(operand) || ts.isNonNullExpression(operand))
+                return null;
+            // A guard that already proves the binding present makes the
+            // assertion true at runtime: nothing is forwarded as undefined.
+            if (ts.isIdentifier(operand)) {
+                const symbol = symbolOf(operand);
+                if (symbol && provenPresent(operand, symbol))
+                    return null;
+            }
+            const stored = this.mapTypeOf(this.typeOf(e.expression));
+            const asserted = this.mapTypeOf(this.typeOf(e));
+            if (stored?.kind !== "union" || asserted?.kind !== "object")
+                return null;
+            const arms = this.unions.get(stored.unionId)?.arms;
+            if (arms?.length !== 2 ||
+                this.armTag(stored.unionId, UNDEFINED_T) < 0 ||
+                !arms.some((arm) => typeEquals(arm, asserted)))
+                return null;
+            return e;
+        };
+        // `decode(xs[i]!)`: a missing element is passed as undefined in
+        // JavaScript, and the callee may never read it.
+        const forwardedElementAssertion = (node) => {
+            let e = node;
+            while (ts.isParenthesizedExpression(e))
+                e = e.expression;
+            if (!ts.isNonNullExpression(e))
+                return null;
+            let read = e.expression;
+            while (ts.isParenthesizedExpression(read))
+                read = read.expression;
+            if (!ts.isElementAccessExpression(read))
+                return null;
+            if (this.mapTypeOf(this.typeOf(read.expression))?.kind !== "array")
+                return null;
+            // An in-bounds read of an array that never holds undefined or holes
+            // always produces a present element.
+            if (indexReadInBounds(read) && elementStates.elementsPresent(read.expression, "find"))
+                return null;
+            const element = this.mapTypeOf(this.typeOf(e));
+            if (!element ||
+                element.kind === "void" ||
+                element.kind === "dyn" ||
+                element.kind === "jsval" ||
+                element.kind === "generator")
+                return null;
+            return e;
+        };
+        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;
+            if (kind === "string")
+                return !this.stringIndexBounds.inBounds(e);
+            // Typed-array reads answer undefined for an invalid index too.
+            return kind === "array" || kind === "bytes";
         };
         const isDynamicObjectEntryRead = (node) => {
             const read = peel(node);
@@ -3031,6 +3281,37 @@ export class Lowerer {
             return this.withUndefinedArm(t);
         };
         const fieldName = (node) => node.name.text;
+        // The precision facts below ask about nodes ordinary lowering may never
+        // query. A checker panic on one of them answers null, and each caller
+        // falls back to its conservative fact.
+        const typeOrNull = (node) => panicSafe(() => this.typeOf(node), null);
+        const contextualOrNull = (node) => panicSafe(() => this.checker.getContextualType(node), null);
+        // Presence proofs only hold for a binding that keeps its one value for
+        // its whole lifetime.
+        const reassigned = reassignedBindings(sourceFiles, symbolOf, isJsSourceFile);
+        const presenceProofs = new Map();
+        const provenPresent = (use, symbol) => {
+            if (reassigned.has(symbol))
+                return false;
+            const cached = presenceProofs.get(use);
+            if (cached !== undefined)
+                return cached;
+            const proven = presentAtUse(use, {
+                sameBinding: (node) => node.text === use.text && symbolOf(node) === symbol,
+                isUndefined: (node) => node.text === "undefined" &&
+                    ((typeOrNull(node)?.flags ?? 0) & ts.TypeFlags.Undefined) !== 0,
+            });
+            presenceProofs.set(use, proven);
+            return proven;
+        };
+        // Bindings of a for-of loop over an array that can hold holes or
+        // undefined. Lowering keeps such a binding's runtime union, so storing
+        // it into another array can store undefined.
+        const iterationSymbols = new Set();
+        // The subset whose iterated array's own facts show a hole or undefined.
+        // Such a binding reads `T | undefined`, so a typed parameter, local or
+        // field it flows into widens like any other missing element read.
+        const holeyIterationSymbols = new Set();
         const mayBeOptional = (node) => {
             // `xs[i]!` is the explicit proven-present form. Its array read keeps
             // the established dense bounds trap and must not promote the enclosing
@@ -3038,7 +3319,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;
@@ -3056,7 +3339,14 @@ export class Lowerer {
                 return true;
             if (ts.isIdentifier(e)) {
                 const symbol = symbolOf(e);
-                return symbol !== null && optionalSymbols.has(symbol);
+                return (symbol !== null &&
+                    (optionalSymbols.has(symbol) || holeyIterationSymbols.has(symbol)) &&
+                    !provenPresent(e, 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);
@@ -3085,11 +3375,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;
+            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 stringArrayRead = (part) => {
+            const stringRead = (part) => {
                 const p = peel(part);
                 if (!ts.isElementAccessExpression(p))
                     return false;
@@ -3097,16 +3407,17 @@ export class Lowerer {
                 if (t?.kind !== "string")
                     return false;
                 const recv = this.mapTypeOf(this.typeOf(p.expression));
+                if (recv?.kind === "string")
+                    return !this.stringIndexBounds.inBounds(p);
                 return 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]) };
         };
@@ -3125,6 +3436,43 @@ export class Lowerer {
             optionalFields.set(symbol, set);
             return set.size !== before;
         };
+        // Runtime-optional record fields travel with the record value: a copy,
+        // a spread or a parameter receives the source's optional fields.
+        const fieldsOfValue = (node) => {
+            const e = peel(node);
+            if (!ts.isIdentifier(e))
+                return undefined;
+            const symbol = symbolOf(e);
+            return symbol === null ? undefined : optionalFields.get(symbol);
+        };
+        const noteFieldsFrom = (symbol, source) => {
+            const fields = fieldsOfValue(source);
+            if (fields === undefined)
+                return false;
+            let changed = false;
+            for (const field of fields)
+                if (noteFieldSymbol(symbol, field))
+                    changed = true;
+            return changed;
+        };
+        /** Optional fields an object literal takes from its spreads, minus
+         * the properties a later member writes explicitly. */
+        const spreadFieldsOf = (object) => {
+            const out = new Set();
+            for (const prop of object.properties) {
+                if (ts.isSpreadAssignment(prop)) {
+                    const fields = fieldsOfValue(prop.expression);
+                    if (fields !== undefined)
+                        for (const field of fields)
+                            out.add(field);
+                }
+                else if (prop.name !== undefined &&
+                    (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name))) {
+                    out.delete(prop.name.text);
+                }
+            }
+            return out;
+        };
         const scanPattern = (name, init) => {
             if (!ts.isArrayBindingPattern(name))
                 return false;
@@ -3139,6 +3487,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.
@@ -3282,6 +3631,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)) {
@@ -3293,6 +3643,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))
@@ -3388,6 +3739,70 @@ export class Lowerer {
             }
             return changed;
         };
+        // A reduce callback over present elements keeps the reduce helper's
+        // optional element ABI for its parameter storage, so the helper still
+        // splits each visit into a plain-element call. Its value is never
+        // absent, so nothing it flows into is widened.
+        const retypeInlineCallback = (callback, parameterIndices) => {
+            const fn = peel(callback);
+            if (!ts.isArrowFunction(fn) && !ts.isFunctionExpression(fn))
+                return false;
+            let changed = false;
+            for (const parameterIndex of parameterIndices) {
+                const parameter = fn.parameters[parameterIndex];
+                if (!parameter)
+                    continue;
+                const checkerType = this.typeOf(parameter.name);
+                if ((checkerType.flags & ts.TypeFlags.TypeParameter) !== 0)
+                    continue;
+                const current = this.mapTypeOf(checkerType);
+                if (!current)
+                    continue;
+                const widened = this.runtimeOptionalType(current);
+                if (!ts.isIdentifier(parameter.name)) {
+                    const previous = this.runtimeOptionalPatternTypes.get(parameter.name);
+                    this.runtimeOptionalPatternTypes.set(parameter.name, widened);
+                    if (!previous || !typeEquals(previous, widened))
+                        changed = true;
+                    continue;
+                }
+                const symbol = symbolOf(parameter.name);
+                if (!symbol)
+                    continue;
+                const previous = this.runtimeOptionalBindingTypes.get(symbol);
+                this.runtimeOptionalBindingTypes.set(symbol, widened);
+                if (!previous || !typeEquals(previous, widened))
+                    changed = true;
+            }
+            return changed;
+        };
+        // A present-element helper passes the stored element itself, so the
+        // callback must accept that exact value through a mechanical adapter.
+        // A parameter spelled as a structural supertype (`(r: { pos: number })`
+        // over a wider record) only converts through the optional element
+        // ABI's union retag; keep that site on the optional visit. Unannotated
+        // inline parameters take the element's contextual type, and generic
+        // parameters specialize later, so neither restricts the site.
+        const callbackTakesPresentElement = (callback, elem, index) => {
+            const fn = peel(callback);
+            let param;
+            if (ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)) {
+                const parameter = fn.parameters[index];
+                if (!parameter?.type || parameter.dotDotDotToken)
+                    return true;
+                const checkerType = this.typeOf(parameter.name);
+                if ((checkerType.flags & ts.TypeFlags.TypeParameter) !== 0)
+                    return true;
+                param = this.mapTypeOf(checkerType);
+            }
+            else {
+                const value = this.mapTypeOf(this.typeOf(fn));
+                if (value?.kind !== "func" || value.rest === true)
+                    return true;
+                param = value.params[index] ?? null;
+            }
+            return param === null || this.coercibleValue(elem, param);
+        };
         const callbackReturnsOptional = (callback, seen = new Set()) => {
             const node = peel(callback);
             if (ts.isArrowFunction(node) || ts.isFunctionExpression(node))
@@ -3405,6 +3820,253 @@ export class Lowerer {
                 !!decl.initializer &&
                 callbackReturnsOptional(decl.initializer, seen));
         };
+        // Element ABIs whose own type admits undefined (`(T | undefined)[]`,
+        // or a rest array widened for an absent argument).
+        const optionalElementKeys = new Set();
+        // Checker answers for the fixed point's repeated element-ABI queries.
+        // Only a binding's widened storage can change between passes.
+        const checkerTypes = new Map();
+        const arrayKeysOf = (node) => panicSafe(() => arrayKeysUnsafe(node), null);
+        const arrayKeysUnsafe = (node) => {
+            let checkerType = checkerTypes.get(node);
+            if (checkerType === undefined) {
+                checkerType = this.typeOf(node);
+                checkerTypes.set(node, checkerType);
+            }
+            const e = peel(node);
+            // A binding the prepass widened stores its widened array ABI.
+            const widened = ts.isIdentifier(e)
+                ? (() => {
+                    const symbol = symbolOf(e);
+                    return symbol ? this.runtimeOptionalBindingTypes.get(symbol) : undefined;
+                })()
+                : undefined;
+            let mapped = widened ?? this.mapTypeOf(checkerType);
+            if (mapped?.kind === "promise")
+                mapped = mapped.inner;
+            const anyElements = mapped?.kind === "array"
+                ? mapped.elem.kind === "dyn" || mapped.elem.kind === "jsval"
+                : mapped === null &&
+                    this.checker.isArrayType(checkerType) &&
+                    !this.checker.isTupleType(checkerType) &&
+                    ((this.checker.getTypeArguments(checkerType)[0]?.flags ?? 0) &
+                        (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !==
+                        0;
+            if (anyElements) {
+                // `new Array(n)` has an `any` element type; its storage takes the
+                // ABI of the slot it initializes.
+                const contextual = this.checker.getContextualType(node);
+                const target = contextual ? this.mapTypeOf(contextual) : null;
+                return target?.kind === "array" ? [typeKey(target.elem)] : [];
+            }
+            if (mapped === null) {
+                // An array whose element type is a type parameter: each
+                // instantiation picks its own element ABI.
+                return this.checker.isArrayType(checkerType) ? null : [];
+            }
+            const arms = mapped.kind === "union" ? (this.unions.get(mapped.unionId)?.arms ?? []) : [mapped];
+            const keys = [];
+            for (const arm of arms) {
+                if (arm.kind !== "array")
+                    continue;
+                const key = typeKey(arm.elem);
+                if (arm.elem.kind === "union"
+                    ? this.armTag(arm.elem.unionId, UNDEFINED_T) >= 0
+                    : isUnitType(arm.elem) || arm.elem.kind === "void")
+                    optionalElementKeys.add(key);
+                keys.push(key);
+            }
+            return keys;
+        };
+        const ownership = new ArrayOwnership(sourceFiles, {
+            symbolOf,
+            declarationOf: (symbol) => this.checker.valueDeclarationOf(symbol),
+            typeOf: typeOrNull,
+            instanceAssignableTo: (owner, target) => panicSafe(() => this.checker.isTypeAssignableTo(this.checker.getTypeAtLocation(owner), target), true),
+            isGlobal: (node, name) => this.isStdlibGlobal(node, name),
+            isArray: (node) => {
+                const type = typeOrNull(node);
+                return type !== null && this.checker.isArrayType(type);
+            },
+            fieldKeys: (declaration) => arrayKeysOf(declaration.name) ?? [],
+            dynamicViewKeys: () => (dynamicViews ??= collectDynamicViews()),
+        });
+        let dynamicViews = null;
+        // Element ABIs of the native arrays that an `any` or `unknown` value is
+        // converted to, including arrays nested in the converted value.
+        const collectDynamicViews = () => {
+            const keys = new Set();
+            const dynamicValue = (node) => {
+                // A binding's declared type says whether it holds dynamic data; a
+                // flow type such as `Array.isArray(x)`'s `any[]` only narrows it.
+                const e = peel(node);
+                const symbol = ts.isIdentifier(e) ? symbolOf(e) : null;
+                const declaration = symbol ? this.checker.valueDeclarationOf(symbol) : undefined;
+                const declared = declaration &&
+                    (ts.isVariableDeclaration(declaration) || ts.isParameter(declaration)) &&
+                    ts.isIdentifier(declaration.name)
+                    ? declaration.name
+                    : null;
+                const type = typeOrNull(declared ?? node);
+                if (type === null)
+                    return true;
+                if ((type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0)
+                    return true;
+                if (!this.checker.isArrayType(type) || this.checker.isTupleType(type))
+                    return false;
+                const element = this.checker.getTypeArguments(type)[0];
+                return (element !== undefined && (element.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0);
+            };
+            const collect = (type, depth) => {
+                if (!type || depth > 4)
+                    return;
+                if (type.kind === "array") {
+                    keys.add(typeKey(type.elem));
+                    collect(type.elem, depth + 1);
+                }
+                else if (type.kind === "union") {
+                    for (const arm of this.unions.get(type.unionId)?.arms ?? [])
+                        collect(arm, depth + 1);
+                }
+                else if (type.kind === "record") {
+                    for (const field of this.shapes.get(type.shapeId)?.fields ?? [])
+                        collect(field.type, depth + 1);
+                }
+                else if (type.kind === "promise")
+                    collect(type.inner, depth + 1);
+            };
+            const target = (type) => {
+                // An unanswerable target may be any array.
+                if (type === null)
+                    keys.add("*");
+                else if (type)
+                    collect(this.mapTypeOf(type), 0);
+            };
+            const visit = (node) => {
+                if ((ts.isAsExpression(node) || ts.isTypeAssertion(node)) && dynamicValue(node.expression))
+                    target(typeOrNull(node));
+                else if (ts.isVariableDeclaration(node) &&
+                    node.type &&
+                    node.initializer &&
+                    dynamicValue(node.initializer))
+                    target(typeOrNull(node.name));
+                else if (ts.isBinaryExpression(node) &&
+                    node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+                    dynamicValue(node.right))
+                    target(typeOrNull(node.left));
+                else if (ts.isReturnStatement(node) && node.expression && dynamicValue(node.expression))
+                    target(contextualOrNull(node.expression));
+                else if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+                    for (const arg of node.arguments ?? [])
+                        if (!ts.isSpreadElement(arg) && dynamicValue(arg))
+                            target(contextualOrNull(arg));
+                }
+                else if (ts.isPropertyAssignment(node) && dynamicValue(node.initializer))
+                    target(contextualOrNull(node.initializer));
+                else if (ts.isArrayLiteralExpression(node)) {
+                    for (const element of node.elements)
+                        if (!ts.isSpreadElement(element) &&
+                            !ts.isOmittedExpression(element) &&
+                            dynamicValue(element))
+                            target(contextualOrNull(element));
+                }
+                else if (ts.isArrowFunction(node) &&
+                    !ts.isBlock(node.body) &&
+                    dynamicValue(node.body))
+                    target(contextualOrNull(node.body));
+            };
+            for (const sf of sourceFiles)
+                ts.walkPreorder(sf, (node) => {
+                    // A checker panic hides this conversion's target: any array.
+                    if (!panicSafe(() => (visit(node), true), false))
+                        keys.add("*");
+                    return undefined;
+                });
+            return keys;
+        };
+        const elementStates = new ArrayElementStates({
+            elementAdmitsUndefined: (key) => optionalElementKeys.has(key),
+            ownerOf: (node) => ownership.ownerOf(node),
+            allocationOwner: (node) => ownership.allocationOwner(node),
+            arrayKeys: arrayKeysOf,
+            mayBeUndefined: (node) => {
+                if (explicitlyNonNull(node))
+                    return false;
+                if (mayBeOptional(node))
+                    return true;
+                // `undefined as unknown as T` keeps the undefined value.
+                for (let inner = node; ts.isParenthesizedExpression(inner) ||
+                    ts.isAsExpression(inner) ||
+                    ts.isTypeAssertion(inner) ||
+                    ts.isSatisfiesExpression(inner);) {
+                    inner = inner.expression;
+                    const type = typeOrNull(inner);
+                    if (type === null || (type.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) !== 0)
+                        return true;
+                }
+                const e = peel(node);
+                if (!ts.isIdentifier(e))
+                    return false;
+                const symbol = symbolOf(e);
+                return symbol !== null && iterationSymbols.has(symbol) && !provenPresent(e, symbol);
+            },
+            callbackReturnsUndefined: (node) => callbackReturnsOptional(node),
+            isGlobal: (node, name) => this.isStdlibGlobal(node, name),
+            isString: (node) => {
+                const type = typeOrNull(node);
+                return type !== null && this.mapTypeOf(type)?.kind === "string";
+            },
+            isArrayLikeObject: (node) => {
+                if (ts.isObjectLiteralExpression(peel(node)))
+                    return true;
+                const type = typeOrNull(node);
+                const mapped = type === null ? null : this.mapTypeOf(type);
+                return (mapped === null ||
+                    mapped.kind === "record" ||
+                    mapped.kind === "object" ||
+                    mapped.kind === "dyn" ||
+                    mapped.kind === "jsval" ||
+                    mapped.kind === "union");
+            },
+            restKeys: (call) => {
+                const callee = peel(call.expression);
+                if (!ts.isIdentifier(callee) && !ts.isPropertyAccessExpression(callee))
+                    return null;
+                const symbol = callableSymbolOf(callee);
+                const sig = symbol ? signatureBySymbol.get(symbol) : undefined;
+                if (!sig)
+                    return ts.isPropertyAccessExpression(callee) ? [] : null;
+                const rest = sig.params.find((shape) => shape.mode === "rest");
+                return rest?.type.kind === "array" ? [typeKey(rest.type.elem)] : [];
+            },
+            markIterationBinding: (node, known) => {
+                const symbol = symbolOf(node);
+                if (!symbol)
+                    return false;
+                let changed = false;
+                if (!iterationSymbols.has(symbol)) {
+                    iterationSymbols.add(symbol);
+                    changed = true;
+                }
+                if (known && !holeyIterationSymbols.has(symbol)) {
+                    holeyIterationSymbols.add(symbol);
+                    // `for (name of xs)` assigns an existing binding, whose own
+                    // storage must then hold the loop's undefined too.
+                    if (!ts.isVariableDeclaration(node.parent) && !ts.isBindingElement(node.parent))
+                        optionalSymbols.add(symbol);
+                    changed = true;
+                }
+                return changed;
+            },
+            note: provenance
+                ? (fact, key, site) => provenance.note(`element-${fact}`, site, site, key)
+                : null,
+        });
+        // Each pass revisits every array callback site; the last visit holds
+        // the decision at the fixed point.
+        const presentSites = new Map();
+        // The same for each for-of loop over an array.
+        const presentLoops = new Map();
         const scanSites = new Map();
         const sitesOf = (sf) => {
             const cached = scanSites.get(sf);
@@ -3414,7 +4076,14 @@ export class Lowerer {
             ts.walkPreorder(sf, (node) => {
                 if (ts.isVariableDeclaration(node) ||
                     ts.isBinaryExpression(node) ||
-                    ts.isCallExpression(node))
+                    ts.isCallExpression(node) ||
+                    ts.isNewExpression(node) ||
+                    ts.isArrayLiteralExpression(node) ||
+                    ts.isDeleteExpression(node) ||
+                    ts.isForOfStatement(node) ||
+                    ts.isArrayBindingPattern(node) ||
+                    ts.isPrefixUnaryExpression(node) ||
+                    ts.isPostfixUnaryExpression(node))
                     nodes.push(node);
             });
             scanSites.set(sf, nodes);
@@ -3423,8 +4092,22 @@ export class Lowerer {
         const scanFile = (sf) => {
             let changed = false;
             const scan = (node) => {
+                if (elementStates.scan(node))
+                    changed = true;
+                if (ts.isForOfStatement(node))
+                    presentLoops.set(node, !elementStates.loopMayYieldUndefined(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)) {
@@ -3436,6 +4119,17 @@ 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;
+                            }
+                        }
+                        else if (ts.isIdentifier(node.name)) {
+                            const assertion = forwardedAssertion(node.initializer);
+                            const symbol = assertion ? symbolOf(node.name) : null;
+                            if (assertion && symbol && !optionalSymbols.has(symbol)) {
+                                optionalSymbols.add(symbol);
+                                this.runtimeOptionalAssertions.add(assertion);
+                                provenance?.note("asserted-binding", node.name, node.initializer);
                                 changed = true;
                             }
                         }
@@ -3456,6 +4150,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));
@@ -3478,6 +4174,22 @@ export class Lowerer {
                         }
                         if (scanPattern(node.name, node.initializer))
                             changed = true;
+                        if (ts.isIdentifier(node.name)) {
+                            const symbol = symbolOf(node.name);
+                            const init = peel(node.initializer);
+                            if (symbol && noteFieldsFrom(symbol, init)) {
+                                provenance?.note("record-copy", node.name, node.initializer);
+                                changed = true;
+                            }
+                            if (symbol && ts.isObjectLiteralExpression(init)) {
+                                for (const field of spreadFieldsOf(init)) {
+                                    if (noteFieldSymbol(symbol, field)) {
+                                        provenance?.note("record-spread", node.name, node.initializer);
+                                        changed = true;
+                                    }
+                                }
+                            }
+                        }
                         if (ts.isIdentifier(node.name) &&
                             ts.isObjectLiteralExpression(peel(node.initializer))) {
                             const object = peel(node.initializer);
@@ -3491,12 +4203,44 @@ 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;
+                                }
                             }
                         }
                     }
                 }
+                if (ts.isBinaryExpression(node) &&
+                    node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+                    ts.isIdentifier(node.left)) {
+                    const symbol = symbolOf(node.left);
+                    if (symbol && noteFieldsFrom(symbol, node.right)) {
+                        provenance?.note("record-copy", node.left, node.right);
+                        changed = true;
+                    }
+                }
+                if (ts.isBinaryExpression(node) &&
+                    node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+                    ts.isIdentifier(node.left)) {
+                    const assertion = forwardedAssertion(node.right);
+                    const symbol = assertion ? symbolOf(node.left) : null;
+                    // Only a variable's storage is promoted (see the final pass).
+                    const declaration = symbol ? this.checker.valueDeclarationOf(symbol) : undefined;
+                    if (assertion &&
+                        symbol &&
+                        declaration &&
+                        ts.isVariableDeclaration(declaration) &&
+                        ts.isIdentifier(declaration.name) &&
+                        !this.runtimeOptionalAssertions.has(assertion)) {
+                        this.runtimeOptionalAssertions.add(assertion);
+                        if (!optionalSymbols.has(symbol)) {
+                            optionalSymbols.add(symbol);
+                            provenance?.note("asserted-binding", node.left, node.right);
+                        }
+                        changed = true;
+                    }
+                }
                 if (ts.isBinaryExpression(node) &&
                     (node.operatorToken.kind === ts.SyntaxKind.EqualsToken ||
                         node.operatorToken.kind === ts.SyntaxKind.QuestionQuestionEqualsToken ||
@@ -3507,14 +4251,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)) {
@@ -3555,11 +4309,26 @@ export class Lowerer {
                             }
                         }
                         if (nativeArrayReceiver) {
-                            if (promoteHofCallback(callback, callbackIndices))
-                                changed = true;
+                            provenanceSite = node;
                             const method = node.expression.name.text;
+                            // Callbacks skip holes (except the find family), so an array
+                            // that never holds undefined only passes present elements.
+                            const reduce = method === "reduce" || method === "reduceRight";
+                            const elementsPresent = receiver?.kind === "array" &&
+                                elementStates.elementsPresent(receiverNode, method) &&
+                                callbackTakesPresentElement(callback, receiver.elem, reduce ? 1 : 0);
+                            // A callback returning a runtime-absent value still needs its
+                            // widened return, whatever its elements.
+                            if (promoteHofCallback(callback, elementsPresent ? [] : callbackIndices))
+                                changed = true;
+                            // Element-typed callback helpers cover every method but
+                            // reduce, whose accumulator keeps the split visit.
+                            presentSites.set(node, elementsPresent && !reduce);
+                            if (elementsPresent && reduce && retypeInlineCallback(callback, callbackIndices))
+                                changed = true;
                             if ((method === "reduce" || method === "reduceRight") &&
-                                (node.arguments.length < 2 || callbackReturnsOptional(callback))) {
+                                ((!elementsPresent && node.arguments.length < 2) ||
+                                    callbackReturnsOptional(callback))) {
                                 if (promoteHofCallback(callback, [0, 1]))
                                     changed = true;
                                 const result = this.runtimeOptionalType(this.irTypeOf(node));
@@ -3578,8 +4347,34 @@ export class Lowerer {
                     if (!symbol)
                         return;
                     const sig = signatureBySymbol.get(symbol);
-                    if (!sig)
+                    if (!sig) {
+                        // A direct call of a function-valued const (`const show = (n:
+                        // number) => ...`): a possibly missing argument widens that
+                        // parameter, as for a callback the same value is passed as.
+                        if (!ts.isIdentifier(node.expression) || reassigned.has(symbol))
+                            return;
+                        const declaration = this.checker.valueDeclarationOf(symbol);
+                        const value = declaration && ts.isVariableDeclaration(declaration) && declaration.initializer
+                            ? peel(declaration.initializer)
+                            : null;
+                        if (!value || !(ts.isArrowFunction(value) || ts.isFunctionExpression(value)))
+                            return;
+                        // Optional, defaulted and rest parameters keep their own ABI.
+                        if (value.parameters.some((parameter) => parameter.questionToken !== undefined ||
+                            parameter.initializer !== undefined ||
+                            parameter.dotDotDotToken !== undefined))
+                            return;
+                        const indices = node.arguments.flatMap((arg, i) => !ts.isSpreadElement(arg) &&
+                            value.parameters[i] !== undefined &&
+                            !value.parameters[i].dotDotDotToken &&
+                            mayBeOptional(arg)
+                            ? [i]
+                            : []);
+                        provenanceSite = node;
+                        if (indices.length > 0 && promoteHofCallback(node.expression, indices))
+                            changed = true;
                         return;
+                    }
                     // JSDoc describes the usual value, not a runtime arity check.
                     // A short JavaScript call still passes undefined. Widen only the
                     // observed slots before bodies lower so both caller and callee
@@ -3605,6 +4400,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);
@@ -3629,13 +4425,63 @@ 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;
                             }
                         }
-                        if (ts.isSpreadElement(arg) || !mayBeOptional(arg) || !shape)
+                        if (!ts.isSpreadElement(arg) && shape && i !== restAt && fieldsOfValue(arg)) {
+                            const fields = fieldsOfValue(arg);
+                            for (const target of familyBySymbol.get(symbol) ?? [symbol]) {
+                                const parameterShape = signatureBySymbol.get(target)?.params[i];
+                                const parameter = functionDeclBySymbol.get(target)?.parameters[i];
+                                if (!parameterShape || parameterShape.type.kind !== "record")
+                                    continue;
+                                if (!parameter || !ts.isIdentifier(parameter.name))
+                                    continue;
+                                const bound = symbolOf(parameter.name);
+                                if (!bound)
+                                    continue;
+                                let promoted = parameterShape.type;
+                                for (const field of fields) {
+                                    const source = promoted.kind === "record"
+                                        ? this.shapes.get(promoted.shapeId)?.fields.find((f) => f.name === field)
+                                        : undefined;
+                                    if (source) {
+                                        promoted = this.runtimeOptionalRecordField(promoted, field, addUndefined(source.type));
+                                    }
+                                    if (noteFieldSymbol(bound, field))
+                                        changed = true;
+                                }
+                                if (!typeEquals(promoted, parameterShape.type)) {
+                                    parameterShape.type = promoted;
+                                    this.runtimeOptionalBindingTypes.set(bound, promoted);
+                                    provenance?.note("record-parameter", parameter, arg);
+                                    changed = true;
+                                }
+                            }
+                        }
+                        if (ts.isSpreadElement(arg) || !shape)
                             return;
+                        const assertion = forwardedAssertion(arg) ?? forwardedElementAssertion(arg);
+                        if (!assertion && !mayBeOptional(arg))
+                            return;
+                        if (assertion) {
+                            if (i === restAt)
+                                return;
+                            // An omittable slot's ABI already holds undefined (an
+                            // optional or defaulted parameter applies its own default).
+                            if (shape.mode === "omittable") {
+                                if (shape.type.kind === "union" &&
+                                    this.armTag(shape.type.unionId, UNDEFINED_T) >= 0)
+                                    this.runtimeOptionalAssertions.add(assertion);
+                                return;
+                            }
+                            if (shape.mode !== "required")
+                                return;
+                            this.runtimeOptionalAssertions.add(assertion);
+                        }
                         if (i === restAt) {
                             // A rest binding always receives an array. An unchecked
                             // argument can make its elements undefined, not the pack.
@@ -3649,6 +4495,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)
@@ -3677,6 +4524,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);
@@ -3700,9 +4548,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;
@@ -3713,6 +4562,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;
@@ -3744,11 +4600,33 @@ 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;
                     }
                 }
             }
         }
+        for (const [site, present] of presentSites)
+            if (present)
+                this.presentElementCalls.add(site);
+        for (const [loop, present] of presentLoops)
+            if (present)
+                this.presentElementLoops.add(loop);
+        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) {
@@ -3880,6 +4758,36 @@ export class Lowerer {
                 }
             });
         }
+        for (const symbol of optionalSymbols)
+            this.runtimeOptionalAssignedSymbols.add(symbol);
+        // `decode(xs[i]!)` into a parameter whose final ABI already holds
+        // undefined: the assertion has no runtime effect, so a missing element
+        // reaches the callee as undefined instead of trapping at the read.
+        for (const sf of sourceFiles) {
+            for (const node of sitesOf(sf)) {
+                if (!ts.isCallExpression(node))
+                    continue;
+                if (!ts.isIdentifier(node.expression) && !ts.isPropertyAccessExpression(node.expression))
+                    continue;
+                const symbol = callableSymbolOf(node.expression);
+                const sig = symbol ? signatureBySymbol.get(symbol) : undefined;
+                if (!sig || node.arguments.some(ts.isSpreadElement))
+                    continue;
+                node.arguments.forEach((arg, i) => {
+                    let e = arg;
+                    while (ts.isParenthesizedExpression(e))
+                        e = e.expression;
+                    if (!ts.isNonNullExpression(e) || !isIndexedRead(e.expression))
+                        return;
+                    const shape = sig.params[i];
+                    if (shape?.mode !== "required" && shape?.mode !== "omittable")
+                        return;
+                    if (shape.type.kind === "union" && this.armTag(shape.type.unionId, UNDEFINED_T) >= 0)
+                        this.runtimeOptionalAssertions.add(e);
+                });
+            }
+        }
+        provenance?.flush();
     }
     run() {
         const parts = this.splitFiles();
@@ -3929,14 +4837,14 @@ export class Lowerer {
                 if (fn)
                     functions.push(fn);
                 else if (this.countsSkips())
-                    this.stats.functionsSkipped++;
+                    this.countSkippedBody(decl);
             }
             for (const decl of fp.classDecls) {
                 const info = this.classes.get(this.classNamer(decl));
                 if (info)
                     functions.push(...this.lowerClassMembers(info));
                 else if (this.countsSkips())
-                    this.stats.functionsSkipped++;
+                    this.countSkippedBody(decl);
             }
         }
         // Each file's top-level statements form its run-once init function.
@@ -4024,10 +4932,10 @@ export class Lowerer {
             // Deferred collection diagnostics nothing flushed — declarations no
             // reference ever made relevant. They belong to the unreached group
             // (collection order keeps them deterministic).
-            for (const [symbol, diags] of this.deferredDiags) {
+            for (const [symbol, diags] of [...this.deferredDiags]) {
                 if (this.alreadyFlushed.has(symbol))
                     continue;
-                for (const d of diags)
+                for (const d of [...diags])
                     this.pushDiag(d);
             }
             return {
@@ -4123,6 +5031,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
@@ -4137,7 +5046,7 @@ export class Lowerer {
         const module = this.diags.length > 0
             ? null
             : {
-                irVersion: 14,
+                irVersion: 15,
                 sourceFile: this.entry.fileName,
                 functions,
                 classes: artifacts.classes,
@@ -4147,10 +5056,13 @@ export class Lowerer {
                 ...(this.npmEmbedded ? { embedded: this.npmEmbedded } : {}),
                 entry: ENTRY_NAME,
                 ...(this.usesWorkers ? { workers: true } : {}),
+                ...(isNodeEsmFile(this.entry, this.program) ? {} : { commonJsEntry: 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,
@@ -4166,41 +5078,72 @@ export class Lowerer {
      * registered ClassInfo — the shape of a JS class whose collection fenced.
      * Used by run()'s global pruning; shapes/unions recurse with a seen-set
      * (interned ids can nest). */
-    typeNamesUnregisteredClass(t, seen = new Set()) {
+    typeNamesUnregisteredClass(t) {
+        return this.unregisteredClassOf(t, new Set()) !== null;
+    }
+    /** The first class name typeNamesUnregisteredClass finds in `t`. */
+    unregisteredClassOf(t, seen) {
+        const first = (types) => {
+            for (const type of types) {
+                const name = this.unregisteredClassOf(type, seen);
+                if (name !== null)
+                    return name;
+            }
+            return null;
+        };
         switch (t.kind) {
             case "object":
-                return !this.classes.has(t.className);
+                return this.classes.has(t.className) ? null : t.className;
             case "array":
             case "set":
-                return this.typeNamesUnregisteredClass(t.elem, seen);
+                return first([t.elem]);
             case "map":
-                return (this.typeNamesUnregisteredClass(t.key, seen) ||
-                    this.typeNamesUnregisteredClass(t.value, seen));
+                return first([t.key, t.value]);
             case "promise":
-                return this.typeNamesUnregisteredClass(t.inner, seen);
+                return first([t.inner]);
             case "func":
-                return (t.params.some((p) => this.typeNamesUnregisteredClass(p, seen)) ||
-                    this.typeNamesUnregisteredClass(t.ret, seen));
+                return first([...t.params, t.ret]);
             case "record": {
                 if (seen.has(t.shapeId))
-                    return false;
+                    return null;
                 seen.add(t.shapeId);
                 const shape = this.shapes.get(t.shapeId);
                 if (!shape)
-                    return false;
-                if (shape.indexValue && this.typeNamesUnregisteredClass(shape.indexValue, seen))
-                    return true;
-                return shape.fields.some((f) => this.typeNamesUnregisteredClass(f.type, seen));
+                    return null;
+                return first([
+                    ...(shape.indexValue ? [shape.indexValue] : []),
+                    ...shape.fields.map((f) => f.type),
+                ]);
             }
             case "union": {
                 if (seen.has(t.unionId))
-                    return false;
+                    return null;
                 seen.add(t.unionId);
                 const def = this.unions.get(t.unionId);
-                return !!def && def.arms.some((a) => this.typeNamesUnregisteredClass(a, seen));
+                return def ? first(def.arms) : null;
             }
             default:
-                return false;
+                return null;
+        }
+    }
+    /** A declaration whose signature blocked never lowers its body, so its
+     * statements would otherwise vanish from the coverage totals and the
+     * percentage would overstate how much of the program compiles. Count
+     * every statement the body holds as attempted and failed, in addition to
+     * the skipped-function tally. */
+    countSkippedBody(decl) {
+        this.stats.functionsSkipped++;
+        if (this.suppressStats)
+            return;
+        const n = countBodyStatements(decl);
+        if (n === 0)
+            return;
+        this.stats.statementsTotal += n;
+        this.stats.statementsFailed += n;
+        const file = decl.getSourceFile().fileName;
+        for (let i = 0; i < n; i++) {
+            this.bumpFileStat(file, "total");
+            this.bumpFileStat(file, "failed");
         }
     }
     /** Whether run() counts a signature-blocked declaration in
@@ -4736,13 +5679,18 @@ export class Lowerer {
         const d = this.instantiationContext
             ? { ...diag, message: `${diag.message} (${this.instantiationContext})` }
             : diag;
+        const pending = this.pendingFlushes.get(diag);
         // Deferred collection: the wrapper decides whether these ever report
         // (a reference flushes them; unreferenced declarations stay silent in
         // builds and report under coverage's unreached group).
         if (this.diagSink) {
+            if (pending && d !== diag)
+                this.pendingFlushes.set(d, pending);
             this.diagSink.push(d);
             return;
         }
+        if (pending)
+            this.commitFlush(pending.symbol, pending.source);
         // One site, one report: some declarations map a type twice (module
         // globals pre-register before their initializers lower) — an exact
         // duplicate (code + span + message) adds noise, not information.
@@ -5060,6 +6008,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
@@ -5383,6 +6334,29 @@ export class Lowerer {
             this.pushDiag(recordShapeMismatchDiag(this.fmt(expected), this.fmt(actual), locOf(node), detail));
             throw new PoisonError();
         }
+        // Instances of two unrelated classes: class identity is nominal here,
+        // so a structurally compatible instance never becomes the other class.
+        // An assertion (`x as Y`) names the mistake most directly.
+        if (actual.kind === "object" &&
+            expected.kind === "object" &&
+            this.classes.has(actual.className) &&
+            this.classes.has(expected.className) &&
+            this.classes.get(actual.className).decl !== this.classes.get(expected.className).decl &&
+            !this.isSubclassOf(actual.className, expected.className) &&
+            !this.isSubclassOf(expected.className, actual.className)) {
+            let site = node;
+            while (ts.isParenthesizedExpression(site))
+                site = site.expression;
+            const assertion = ts.isAsExpression(site) || ts.isTypeAssertion(site);
+            this.unsupported("SC1090", node, `${assertion ? "asserting" : "using"} a '${this.fmt(actual)}' instance as the unrelated class '${this.fmt(expected)}' (neither class extends the other, and class identity is nominal in compiled code)`, assertion
+                ? `narrow with \`instanceof ${this.fmt(expected)}\` where the value can really be one, or declare a shared base class and assert through it`
+                : `make one class extend the other, or construct a '${this.fmt(expected)}' from the value's fields`);
+        }
+        // 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
@@ -5438,6 +6412,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
@@ -5446,6 +6435,22 @@ export class Lowerer {
      * else (including a DIFFERENT union) is left for requireExactShape, which
      * rejects union mismatches with SC2003. */
     coerceToExpected(expr, expected) {
+        // A destination that holds undefined takes an unassigned deferred-init
+        // field's slot as is (Node passes the undefined along).
+        if (expected.kind === "union" && this.armTag(expected.unionId, UNDEFINED_T) >= 0) {
+            const slot = this.deferredFieldSlot(expr);
+            if (slot)
+                expr = slot;
+        }
+        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
@@ -5595,9 +6600,18 @@ export class Lowerer {
                 };
             }
             if (expr.kind === "unitLit" || this.dynConvertible(expr.type)) {
-                const shape = expr.type.kind === "record" ? this.shapes.get(expr.type.shapeId) : undefined;
-                const liveRef = expr.type.kind === "array" ||
-                    (!!shape && (shape.fields.length > 0 || shape.indexValue !== undefined));
+                // Records and arrays keep their identity as untyped values, including
+                // when they arrive through a union, so `unknown` views, weak
+                // collection keys and later typed reads all see the same object.
+                const liveReference = (type) => {
+                    if (type.kind === "array")
+                        return true;
+                    const shape = type.kind === "record" ? this.shapes.get(type.shapeId) : undefined;
+                    return !!shape && (shape.fields.length > 0 || shape.indexValue !== undefined);
+                };
+                const liveRef = liveReference(expr.type) ||
+                    (expr.type.kind === "union" &&
+                        (this.unions.get(expr.type.unionId)?.arms.some(liveReference) ?? false));
                 return {
                     kind: "dynFrom",
                     value: expr,
@@ -5705,6 +6719,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
@@ -5728,6 +6745,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
@@ -5763,7 +6805,7 @@ export class Lowerer {
                 this.armTag(expr.type.unionId, expected) >= 0) {
                 const helper = this.narrowedArmHelper(expr.type.unionId, expected, expr.loc);
                 if (helper) {
-                    return { kind: "call", callee: helper, args: [expr], type: expected, loc: expr.loc };
+                    return this.checkedNarrowCall(helper, expr, expected, expr.loc);
                 }
             }
             if (!typeEquals(expr.type, expected)) {
@@ -6014,6 +7056,9 @@ export class Lowerer {
     narrowedArmHelper(fromId, target, loc) {
         return narrowedArmHelper(this, fromId, target, loc);
     }
+    checkedNarrowCall(helper, value, type, loc) {
+        return checkedNarrowCall(this, helper, value, type, loc);
+    }
     deferredReadHelper(fromId, target, loc) {
         return deferredReadHelper(this, fromId, target, loc);
     }
@@ -6110,6 +7155,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.
@@ -6698,6 +7754,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'
@@ -6785,15 +7877,47 @@ export class Lowerer {
     flushDeferred(symbol) {
         if (this.collecting)
             return;
+        this.reportDeferred(symbol);
+    }
+    /** flushDeferred without the collection-pass guard: for declarations
+     * whose diagnostics must report eagerly (class statements with
+     * declaration-time code, extended bases — collectClassShapeDeferring). */
+    reportDeferred(symbol) {
         const diags = this.deferredDiags.get(symbol);
         if (!diags)
             return;
-        this.deferredDiags.delete(symbol);
-        if (this.alreadyFlushed.has(symbol))
-            return; // the emit pass reported these
-        this.flushedSymbols.add(symbol);
-        for (const d of diags)
+        if (this.alreadyFlushed.has(symbol)) {
+            this.deferredDiags.delete(symbol); // the emit pass reported these
+            return;
+        }
+        if (this.diagSink === null) {
+            this.deferredDiags.delete(symbol);
+            this.flushedSymbols.add(symbol);
+            for (const d of diags)
+                this.pushDiag(d);
+            return;
+        }
+        // A capture buffer is active (a probe, or another declaration's
+        // deferred collection): the copies ride that buffer, and the
+        // declaration stays deferred until one of them reaches the build.
+        for (const d of diags) {
+            this.pendingFlushes.set(d, { symbol, source: d });
             this.pushDiag(d);
+        }
+    }
+    /** A flushed copy of a deferred diagnostic reached `diags`: that
+     * diagnostic is reported, so it leaves the declaration's deferred list
+     * (the declaration counts as flushed for the coverage remainder). */
+    commitFlush(symbol, source) {
+        this.flushedSymbols.add(symbol);
+        const list = this.deferredDiags.get(symbol);
+        if (!list)
+            return;
+        const index = list.indexOf(source);
+        if (index >= 0)
+            list.splice(index, 1);
+        if (list.length === 0)
+            this.deferredDiags.delete(symbol);
     }
     flushDeferredClass(className) {
         const symbol = this.deferredClassByName.get(className);
@@ -7102,6 +8226,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). */
@@ -7846,13 +8996,7 @@ export class Lowerer {
         const helper = this.narrowedArmHelper(optional.unionId, optional.present, locOf(stmt.expression));
         if (!helper)
             return lowerForOf(this, stmt);
-        return this.withExpressionOverride(stmt.expression, {
-            kind: "call",
-            callee: helper,
-            args: [optional.value],
-            type: optional.present,
-            loc: locOf(stmt.expression),
-        }, () => lowerForOf(this, stmt));
+        return this.withExpressionOverride(stmt.expression, this.checkedNarrowCall(helper, optional.value, optional.present, locOf(stmt.expression)), () => lowerForOf(this, stmt));
     }
     lowerForStatement(stmt) {
         return lowerForStatement(this, stmt);
@@ -8097,21 +9241,21 @@ export class Lowerer {
             const helper = this.narrowedArmHelper(optionalRight.unionId, optionalRight.present, locOf(expr.right));
             if (!helper)
                 return lower();
-            right = {
-                kind: "call",
-                callee: helper,
-                args: [optionalRight.value],
-                type: optionalRight.present,
-                loc: locOf(expr.right),
-            };
+            right = this.checkedNarrowCall(helper, optionalRight.value, optionalRight.present, locOf(expr.right));
         }
         else {
             right = this.lowerExpr(expr.right);
         }
         if (right.type.kind !== "classval")
             return lower();
-        const stableRight = this.declareHiddenLocal("%instanceofRight", right.type);
-        const rightValue = varRef(stableRight.id, right.type, locOf(expr.right));
+        // A capture-free class reference is the immortal static class object:
+        // re-reading it is pure, so it needs no owned temporary (whose retain
+        // and release would be out-of-line calls on every test).
+        const constantRight = right.kind === "classRef" && right.captures === undefined;
+        const stableRight = constantRight
+            ? null
+            : this.declareHiddenLocal("%instanceofRight", right.type);
+        const rightValue = stableRight ? varRef(stableRight.id, right.type, locOf(expr.right)) : right;
         const body = this.withExpressionOverride(expr.left, {
             kind: "unionNarrow",
             unionId: left.type.unionId,
@@ -8124,7 +9268,16 @@ export class Lowerer {
             kind: "seqExpr",
             stmts: [
                 { kind: "varDecl", localId: stable.id, init: left, loc: locOf(expr.left) },
-                { kind: "varDecl", localId: stableRight.id, init: right, loc: locOf(expr.right) },
+                ...(stableRight
+                    ? [
+                        {
+                            kind: "varDecl",
+                            localId: stableRight.id,
+                            init: right,
+                            loc: locOf(expr.right),
+                        },
+                    ]
+                    : []),
             ],
             result: {
                 kind: "ternary",
@@ -8155,13 +9308,7 @@ export class Lowerer {
         const helper = this.narrowedArmHelper(optional.unionId, optional.present, locOf(node));
         if (!helper)
             return lower();
-        return this.withExpressionOverride(node, {
-            kind: "call",
-            callee: helper,
-            args: [optional.value],
-            type: optional.present,
-            loc: locOf(node),
-        }, lower);
+        return this.withExpressionOverride(node, this.checkedNarrowCall(helper, optional.value, optional.present, locOf(node)), lower);
     }
     withExpressionOverride(node, value, lower) {
         const previous = this.chainRecvByNode.get(node);
@@ -8270,6 +9417,37 @@ export class Lowerer {
     fieldGetExpr(target, loc, blame) {
         return fieldGetExpr(this, target, loc, blame);
     }
+    /** The undefined-armed slot read behind a checked deferred-init field
+     * read, or null. Consumers that observe undefined itself (equality,
+     * typeof, truthiness, nullish defaults) test the slot instead of the
+     * checked extraction, which throws for an unassigned field. */
+    deferredFieldSlot(value) {
+        // The inline form: `slot is undefined ? throw : narrow(slot)`.
+        if (value.kind === "ternary" &&
+            value.cond.kind === "unionIsTag" &&
+            value.else_.kind === "unionNarrow" &&
+            value.else_.value === value.cond.value &&
+            value.then.kind === "libCall" &&
+            value.then.fn === "error.nodeThrow") {
+            const read = value.cond.value;
+            return read.kind === "fieldGet" &&
+                read.type.kind === "union" &&
+                this.classes.get(read.className)?.deferredInitFields?.has(read.field) === true
+                ? read
+                : null;
+        }
+        if (value.kind !== "call" || value.args.length !== 1)
+            return null;
+        const read = value.args[0];
+        if (read.kind !== "fieldGet" || read.type.kind !== "union")
+            return null;
+        if (this.classes.get(read.className)?.deferredInitFields?.has(read.field) !== true)
+            return null;
+        return this.coercions.checkedNarrows.has(value.callee) ||
+            value.callee.startsWith("%deferred.read.")
+            ? read
+            : null;
+    }
     fieldSetStmt(target, value, loc, blame) {
         return fieldSetStmt(this, target, value, loc, blame);
     }
@@ -8953,8 +10131,8 @@ export class Lowerer {
         return lowerNumberStaticProperty(this, expr);
     }
     /* ── the island-backed ambient surface (ISLAND_SURFACE) ───────────── */
-    requireDynamicApi(feature, node) {
-        return requireDynamicApi(this, feature, node);
+    requireDynamicApi(feature, node, hint) {
+        return requireDynamicApi(this, feature, node, hint);
     }
     lowerMathProperty(expr) {
         return lowerMathProperty(this, expr);