@scriptc/compiler 0.0.36 → 0.1.2

package/dist/frontend/lowering/lowerer.js

@@ -15,22 +15,24 @@ import { InternalCompilerError } from "../../errors.js";
  */
 import { resolve } from "node:path";
 import { tsgoPath } from "../dts-paths.js";
-import { isRelativeSpecifier } from "../workspace-registry.js";
 import * as ts from "../ts7/adapter.js";
 import { anyOpRequiresDynamicDiag, blockedBindingUseDiag, checkerPanicDiag, componentTypeDiag, isCheckerPanic, genericSignatureTypeDiag, indexSignatureTypeDiag, intersectionTypeDiag, noLoweringDiag, overloadedSignatureTypeDiag, recordShapeMismatchDiag, requiresDynamicApiDiag, requiresDynamicPackageDiag, requiresDynamicTypeDiag, unionMismatchDiag, unsupportedDiag, unsupportedTypeDiag, } from "../../diagnostics/diagnostic.js";
-import { arrayOf, BOOL, canAdaptDynFuncTo, canConvertToDyn, canCrossIslandBoundary, canExitIslandToType, canMarshalTypedFuncIntoIsland, DYN, F64, isJsonSafeType, isUndefinedArmedUnion, isUnitType, JSVAL, RUNTIME_ERROR_CLASSES, STRING, typeEquals, UNDEFINED_T, VOID } from "../../ir/ir.js";
+import { arrayOf, BOOL, canAdaptDynFuncTo, canConvertToDyn, canCrossIslandBoundary, canExitIslandToType, canMarshalTypedFuncIntoIsland, DYN, DYN_HANDLE_KINDS, F64, isDynTypedRefType, isJsonSafeType, isJsonStringifySafeType, 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, isJsSourceFile, isNodeEsmFile, isNodeTypesPath, locOf, orderedImportsOf, overridesDtsPath, npmStaticDepSf7, requireSpecOf, resolveImport, workspacePackageOfPath, } from "../program.js";
 import { containsRecord, containsUnion, describeComponentBlocker, describeRecordMemberBlocker, formatIrType, ISLAND_AMBIENT_TYPES, isUnitOnlyTsType, mapType, ShapeRegistry, typeKey, UnionRegistry, withUndefinedArm as withUndefinedArmCanonical, } from "../type-mapper.js";
 import { boundaryIntoIslandMsg, boundaryOutOfIslandMsg, builtinConstLit, builtinModuleConstOf, builtinModulesArrayLit, builtinFenceHintOf, builtinModuleFnOf, stdlibMemberFence, isStdlibMember, isStdlibSymbol, isStdlibGlobal, stdlibGlobalMember, nodeTypesOnlySymbol } from "./surfaces.js";
 import { splitFiles, collectProgram, collectNpmImports, collectJsonImports, moduleArtifacts, collectGlobals, declSymbolOf, defaultExportSymbolOf, lowerFileInit, lowerDefaultExport, buildMain, appendDynamicImportModules } from "./lower-modules.js";
+import { prepareCjsModuleGraph } from "./lower-node-module.js";
 import { registerBuiltinErrorClasses, registerBuiltinEmitterClass, registerBuiltinStreamClasses, builtinErrorInfoOf, builtinEmitterInfoOf, builtinStreamInfoOf, analyzeClassDecoration, classIteratorDrainCall, classIteratorNextCall, classIteratorOf, classIteratorOpenCall, classIteratorRestDrainCall, classMemberNameOf, classValueRef, collectClassShape, exactClassOfReceiver, collectClassShapeInner, ctorAbiEquals, findMethodOn, findStaticOn, findGenericMethodOn, findGenericStaticOn, genericClassInstanceType, isSubclassOf, inHierarchy, overrideBelow, staticShadowBelow, upcastTo, lowerClassMembers, lowerClassCtor, lowerClassExpression, lowerClassExpressionInfo, lowerClassMethodMember, lowerClassValueProperty, lowerStaticMethod, throwingSetterFn, fieldInitStmts, lowerStaticFieldInits, lowerStaticFieldRead, lowerDerivedCtorBody, superCallStmt, lowerSuperMethodCall, superThisRef, lowerSuperAccessorRead, lowerSuperAccessorWrite, inheritsBuiltinErrorCtor, inheritsBuiltinEmitterCtor, errorMessageArg, lowerNew, accessorCall } from "./lower-classes.js";
 import { mixinCallClassInfoOf, mixinIntersectionInstanceType } from "./lower-mixins.js";
 import { bindingNeverReassigned, bodyReadsArguments, implicitMonoFile, isThisParameter, paramShape, paramShapes, checkDefaultParamBodyType, completeArgs, wrappedUndefined, undefinedArgFor, requireExactArityValue, bodyReturnType, declaredReturnType, collectSignature, collectSignatureInner, collectGenericSignature, genericFnOf, lowerGenericCall, lowerGenericFnValue, inferTypeParamBindings, lowerGenericInstance, lowerCall, lowerFfiCall, lowerTimersMemberCall, lowerPromiseMethodCall, lowerFilterNarrowCall, isTopLevelFnSymbol, lowerNestedFunctionDecl, lambdaSignature, lowerLambda, lowerFunction, validateFfiImports } from "./lower-calls.js";
-import { lowerArrayMethodCall, lowerBufferStaticCall, lowerBytesMethodCall, lowerBytesNew, lowerMapMethodCall, lowerMapForEachCall, buildMapForEachFn, lowerRecordOvfCaptureHelper, lowerEnvToPairsHelper, lowerSetMethodCall, lowerSetForEachCall, buildSetForEachFn, lowerRegexMethodCall, lowerStringMethodCall } from "./lower-containers.js";
+import { lowerArrayMethodCall, lowerMapMethodCall, lowerMapForEachCall, buildMapForEachFn, lowerRecordOvfCaptureHelper, lowerEnvToPairsHelper, lowerSetMethodCall, lowerSetForEachCall, buildSetForEachFn } from "./lower-containers.js";
+import { lowerBufferStaticCall, lowerBytesMethodCall, lowerBytesNew } from "./containers/bytes.js";
+import { lowerRegexMethodCall, lowerStringMethodCall } from "./containers/string-and-regexp.js";
 import { lowerStreamModuleCall } from "./lower-stream.js";
 import { lowerEmitOverrideSpec } from "./lower-event-emitter.js";
-import { builtinImportOf, createRequireBindingDecl, createRequireNamespaceDecl, createRequireSpecOf, stripTypeCasts, lowerBuiltinModuleCall, lowerFsToUnixTimestampCall, lowerFsLadderCall, lowerChildArgsArg, lowerSpawnSyncCall, lowerSpawnCall, lowerExecSyncCall, recordToEnvPairs, lowerJsonMethodCall, fencedBuiltinImportOf, lowerCryptoComposedCall, lowerUrlMethodCall, lowerSearchParamsMethodCall, lowerStatsMethodCall, lowerChildMethodCall, lowerAtomicsCall, lowerBuiltinExtraProperty, promisifiedExecFileDecl, lowerExecFileAsyncCall, execFileAsyncHelper, lowerStringDecoderMethodCall, strdecHelper, lowerReadlineMethodCall, lowerDcChannelMethodCall, lowerDcChannelProperty, lowerAlsMethodCall, lowerDcTracingChannelMethodCall, lowerDcTracingChannelProperty, lowerJsonProperty, lowerErrorCodeProperty, lowerProcessProperty, isProcessEnv, envValueType, lowerProcessEnvGet, lowerProcessMethodCall, lowerProcessOptionalMethodCall, lowerTimeoutMethodCall, envSnapshotHelper, isConsoleLog, consoleCallMember, lowerNumberStaticCall, lowerNumberStaticProperty, lowerDateCall, lowerTextCodecCall, lowerCryptoModuleCall, lowerFsConstantsProperty, lowerBuiltinConstantsProperty, builtinConstantBindingOf, builtinConstantsDestructureDecl, lowerProcessStreamProperty, lowerStringStaticCall, lowerStringLastIndexOfCall, lowerPromiseStaticCall, textCodecBindingClassOf } from "./lower-builtins.js";
+import { builtinImportOf, createRequireBindingDecl, createRequireNamespaceDecl, createRequireSpecOf, stripTypeCasts, lowerBuiltinModuleCall, lowerTimersPromisesSetInterval, lowerFsToUnixTimestampCall, lowerFsLadderCall, lowerChildArgsArg, lowerSpawnSyncCall, lowerSpawnCall, lowerExecSyncCall, recordToEnvPairs, lowerJsonMethodCall, fencedBuiltinImportOf, lowerCryptoComposedCall, lowerUrlMethodCall, lowerSearchParamsMethodCall, lowerStatsMethodCall, lowerChildMethodCall, lowerAtomicsCall, lowerBuiltinExtraProperty, promisifiedExecFileDecl, lowerExecFileAsyncCall, execFileAsyncHelper, lowerStringDecoderMethodCall, strdecHelper, lowerReadlineMethodCall, lowerDcChannelMethodCall, lowerDcChannelProperty, lowerAlsMethodCall, lowerDcTracingChannelMethodCall, lowerDcTracingChannelProperty, lowerJsonProperty, lowerErrorCodeProperty, lowerProcessProperty, isProcessEnv, envValueType, lowerProcessEnvGet, lowerProcessMethodCall, lowerProcessOptionalMethodCall, lowerTimeoutMethodCall, envSnapshotHelper, isConsoleLog, consoleCallMember, lowerNumberStaticCall, lowerNumberStaticProperty, lowerDateCall, lowerTextCodecCall, lowerCryptoModuleCall, lowerFsConstantsProperty, lowerBuiltinConstantsProperty, builtinConstantBindingOf, builtinConstantsDestructureDecl, lowerProcessStreamProperty, lowerStringStaticCall, lowerStringLastIndexOfCall, lowerPromiseStaticCall, textCodecBindingClassOf } from "./lower-builtins.js";
 import { fenceFetchObjectAssignment, fenceFetchObjectBinding, fenceStaticAbortControllerMemberRead, fenceStaticHeadersIteration, fenceStaticHeadersMember, fenceStaticReadableStreamMember, fenceStaticResponseMember, fenceUnsupportedFetchConstructorMember, isIslandExpr, islandFuncValueFence, islandRegexpOf, jsvalIn, requireDynamicApi, islandGlobalFnOf, lowerAbortControllerNew, lowerDynamicHeadersIteratorCall, lowerDynamicHeadersSpread, lowerDynamicImportCall, lowerFetchCall, lowerFetchElementMethodCall, lowerResponseNew, lowerStaticFetchCompanionCall, lowerStaticAbortControllerCall, lowerStaticAbortSignalListenerCall, lowerStaticReadableStreamCancelCall, lowerStaticReadableStreamControllerCall, lowerStaticReadableStreamNew, lowerStaticReadableStreamReaderCall, lowerStaticResponseCall, lowerIslandMethodCall, lowerMathProperty, npmPackageOf, npmMemberFence, npmPackageOfSymbol } from "./lower-island.js";
 import { lowerHttpHeadersElement, lowerNetModuleCall, lowerServerMethodCall, lowerServerProperty, lowerTlsRootCertificates } from "./lower-server.js";
 import { lowerDgramDnsModuleCall, lowerDgramMethodCall } from "./lower-dgram.js";
@@ -38,11 +40,14 @@ import { lowerNodeTestModuleCall, lowerTestDirectCall, lowerTestMethodCall, lowe
 import { lowerAssertModuleCall, lowerAssertDirectCall } from "./lower-assert.js";
 import { lowerUtilModuleCall } from "./lower-inspect.js";
 import { lowerComptime, comptimeBakeable, rejectComptimeCaptures, comptimeValueToIr } from "./lower-comptime.js";
-import { lowerStmts, noteBlockedBindings, isBlockedBinding, lowerScopedBlock, predeclareForwardCapture, predeclareForwardFnDecl, predeclareForwardVar, rejectJumpCrossingFinally, lowerStmt, lowerVarStatement, lowerDestructuringDecl, lowerDestructuringAssignParts, lowerBindingPattern, lowerJsvalBindingPattern, checkBindingElement, bindPatternTarget, isParseArgsDynCheckerType, lowerVarDeclList, lowerVarDecl, lowerSwitch, lowerTry, lowerExprStatement, lowerForOf, lowerForStatement } from "./lower-stmts.js";
-import { lowerDynObjectLiteral, lowerExpr, maybeNarrow, lowerUnitComparison, lowerNullishCoalesce, lowerOptionalChain, finishOptionalChain, lowerCondition, ensureBool, requireTruthyUnion, eqComparableUnion, lowerIntrinsicProperty, lowerArrayLiteral, lowerObjectLiteral, lowerShorthandValue, rejectThisInObjectMethod, lowerElementAccess, lowerElementWrite, lowerRecordKeyRead, ensureString, lowerTemplate, lowerAsExpression, lowerPrefixUnary, lowerBinary, lowerCaughtTypeofTest, caughtRead, caughtLocalOf, caughtToString, lowerInstanceOf, lowerRegexLiteral, lowerFieldRead, lowerUnionProperty, fieldTarget, fieldGetExpr, fieldSetStmt, lowerFieldCompound, uniqueSymbolKeyOf, foldedStringKeyOf } from "./lower-exprs.js";
+import { lowerStmts, noteBlockedBindings, isBlockedBinding, lowerScopedBlock, predeclareForwardCapture, predeclareForwardFnDecl, predeclareForwardVar, lowerStmt, lowerVarStatement, lowerDestructuringDecl, lowerDestructuringAssignParts, lowerBindingPattern, lowerJsvalBindingPattern, checkBindingElement, bindPatternTarget, isParseArgsDynCheckerType, lowerVarDeclList, lowerVarDecl, lowerSwitch, lowerTry, lowerExprStatement, lowerForOf, lowerForStatement } from "./lower-stmts.js";
+import { lowerExpr, maybeNarrow, lowerUnitComparison, lowerNullishCoalesce, lowerCondition, ensureBool, requireTruthyUnion, eqComparableUnion, lowerIntrinsicProperty, lowerArrayLiteral, lowerElementAccess, lowerElementWrite, lowerRecordKeyRead, ensureString, lowerTemplate, lowerAsExpression, lowerPrefixUnary, lowerBinary, lowerCaughtTypeofTest, caughtRead, caughtLocalOf, caughtToString, lowerInstanceOf, lowerRegexLiteral, lowerFieldRead, lowerUnionProperty, fieldTarget, fieldGetExpr, fieldSetStmt, lowerFieldCompound, uniqueSymbolKeyOf } from "./lower-exprs.js";
+import { finishOptionalChain, lowerOptionalChain } from "./expressions/optional-chains.js";
+import { foldedStringKeyOf, lowerDynObjectLiteral, lowerObjectLiteral, lowerShorthandValue, rejectThisInObjectMethod } from "./expressions/object-literals.js";
 import { lowerRecordFieldCall, lowerObjectMethodCall } from "./lower-calls.js";
 import { fenceCrossBlockNsRef, nsPathPrefix } from "./lower-namespaces.js";
 import { numLit, varRef } from "../../ir/build.js";
+import { isSafeToRepeat } from "./expressions/evaluation-safety.js";
 /** Entry function name. '%' cannot appear in a TS identifier, so a user
  * function can never collide with it (mangling is injective per prefix). */
 export const ENTRY_NAME = "%main";
@@ -81,7 +86,7 @@ export function newFnCtx(lifted, selfSymbol, selfType, returnType) {
  * always visited. */
 const IR_STMT_KINDS = new Set([
     "varDecl", "assign", "exprStmt", "if", "while", "doWhile", "switch",
-    "arraySet", "forOf", "return", "fieldSet", "recordSet", "break",
+    "arraySet", "arraySetLength", "arraySetUndefined", "arrayDelete", "forOf", "return", "fieldSet", "recordSet", "break",
     "continue", "block", "tryCatch", "throw", "rethrow", "runtimeFence",
 ]);
 /** True when a lowered statement's OWN expressions contain island
@@ -464,6 +469,41 @@ export function dynFallbackType(lowerer, node, t) {
         // the whole type's own fence.
         return anyPiecedFuncType(lowerer, node, t);
     }
+    // JS inference commonly spells a callback field initialized to null as
+    // `((value: any) => any) | null`. Preserve the callable arm and its
+    // checked-dynamic pieces instead of collapsing the whole slot to dyn.
+    // Besides keeping direct calls static, this leaves closure captures
+    // visible to the native cycle collector (a dyn-boxed closure edge is
+    // intentionally opaque to it).
+    if (t.isUnionType()) {
+        const arms = [];
+        let functions = 0;
+        for (const part of ts.constituentTypes(t)) {
+            if (part.flags & ts.TypeFlags.Null) {
+                arms.push(NULL_T);
+                continue;
+            }
+            if (part.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) {
+                arms.push(UNDEFINED_T);
+                continue;
+            }
+            const mapped = lowerer.mapTypeOf(part) ?? jsFallbackFunctionType(lowerer, node, part);
+            if (mapped?.kind !== "func") {
+                functions = -1;
+                break;
+            }
+            functions++;
+            arms.push(mapped);
+        }
+        if (functions === 1 && arms.length > 1) {
+            const canonical = [...new Map(arms.map((arm) => [typeKey(arm), arm])).entries()]
+                .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+                .map(([, arm]) => arm);
+            return canonical.length === 1
+                ? canonical[0]
+                : { kind: "union", unionId: lowerer.unions.intern(canonical) };
+        }
+    }
     if (lowerer.checker.isArrayType(t)) {
         const elem = lowerer.checker.getTypeArguments(t)[0];
         const elemTainted = elem !== undefined &&
@@ -485,18 +525,23 @@ export function dynFallbackType(lowerer, node, t) {
     // construct signatures, overloads, and function-with-properties shapes
     // stay out (the whole value falls to dyn below, where every reached
     // use meets its own fence or boxes as-is).
-    const sig = pureSingleCallSignatureOf(lowerer, t);
-    if (sig) {
-        const params = sig.getParameters().map((p) => {
-            const pt = lowerer.checker.getTypeOfSymbolAtLocation(p, node);
-            return lowerer.mapTypeOf(pt) ?? DYN;
-        });
-        const retT = lowerer.checker.getReturnTypeOfSignature(sig);
-        const ret = retT.flags & ts.TypeFlags.Void ? VOID : lowerer.mapTypeOf(retT) ?? DYN;
-        return { kind: "func", params, ret };
-    }
+    const fallbackFunction = jsFallbackFunctionType(lowerer, node, t);
+    if (fallbackFunction !== null)
+        return fallbackFunction;
     return DYN;
 }
+function jsFallbackFunctionType(lowerer, node, t) {
+    const sig = pureSingleCallSignatureOf(lowerer, t);
+    if (!sig)
+        return null;
+    const params = sig.getParameters().map((p) => {
+        const pt = lowerer.checker.getTypeOfSymbolAtLocation(p, node);
+        return lowerer.mapTypeOf(pt) ?? DYN;
+    });
+    const retT = lowerer.checker.getReturnTypeOfSignature(sig);
+    const ret = retT.flags & ts.TypeFlags.Void ? VOID : lowerer.mapTypeOf(retT) ?? DYN;
+    return { kind: "func", params, ret };
+}
 /** The one call signature of a PURE function type — single signature, no
  * properties, no construct signatures, no type parameters, no rest params
  * (declared or synthesized from an `arguments` read). Null for every
@@ -821,12 +866,237 @@ export class Lowerer {
     /** All storage slots widened for runtime absence, including slots whose
      * current control-flow branch has temporarily narrowed the value. */
     runtimeOptionalStorageLocals = new Set();
+    /** Globals whose checker-bare type was widened because an indexed read can
+     * carry undefined at runtime. Identifier reads keep the union tag so
+     * typeof and later boundaries observe the real value. */
+    runtimeOptionalGlobals = new Set();
+    /** Bindings whose unchecked string arithmetic can produce either a number
+     * (NaN for an absent read) or a string. Preserve that result union at bare
+     * reads instead of applying the checker-bare string narrowing adapter. */
+    runtimeOptionalArithmeticLocals = new Set();
+    runtimeOptionalArithmeticGlobals = new Set();
+    /** Binding symbols whose IR storage type was widened by the indexed-read
+     * prepass. This includes explicit annotations: unchecked TS annotations do
+     * not prove that an array property read produced a value. */
+    runtimeOptionalBindingTypes = new Map();
+    /** Concise callback/lambda returns promoted by the HOF callback prepass;
+     * arrows have no declaration symbol to key in fnSigsBySymbol. */
+    runtimeOptionalFunctionReturns = new WeakMap();
+    /** Arithmetic over an unchecked string read can answer either NaN or a
+     * string. Bindings and returns use this marker to retain that result union
+     * through checker-bare string annotations. */
+    runtimeOptionalArithmeticTypes = new WeakMap();
+    /** Record fields promoted to an undefined-armed union by an indexed-read
+     * value. The key is the concrete emitted shape and field name. */
+    runtimeOptionalFields = new Set();
+    /** Callback pattern parameters carry an optional source without making
+     * every name destructured from a present source optional. */
+    runtimeOptionalPatternTypes = new WeakMap();
+    runtimeOptionalReduceTypes = new WeakMap();
     /** 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();
     runtimeOptionalRootOf(local) {
         return this.runtimeOptionalRoots.get(local) ?? local;
     }
+    runtimeOptionalBindingType(node, fallback) {
+        const patternType = this.runtimeOptionalPatternTypes.get(node);
+        if (patternType)
+            return patternType;
+        const symbol = ts.isIdentifier(node) ? this.resolveValueSymbol(node) : this.checker.getSymbolAtLocation(node);
+        if (!symbol)
+            return fallback ?? null;
+        const known = this.runtimeOptionalBindingTypes.get(symbol);
+        if (known)
+            return known;
+        // A module-scope function alias is collected as a global before the
+        // optional-read fixed point settles. Derive its promoted function ABI
+        // directly from the aliased declaration as a final read-side hook, so
+        // the initializer cannot fall back to a narrowing adapter.
+        if (ts.isIdentifier(node) && fallback?.kind === "func") {
+            const decl = this.checker.valueDeclarationOf(symbol);
+            if (decl && ts.isVariableDeclaration(decl) && decl.initializer) {
+                let init = decl.initializer;
+                while (ts.isParenthesizedExpression(init))
+                    init = init.expression;
+                if (ts.isIdentifier(init)) {
+                    const source = this.resolveValueSymbol(init);
+                    const sig = source ? this.fnSigsBySymbol.get(source) : undefined;
+                    if (sig) {
+                        return {
+                            ...fallback,
+                            params: sig.params.filter((p) => p.mode !== "dynRest").map((p) => p.type),
+                            ret: sig.returnType,
+                        };
+                    }
+                }
+            }
+        }
+        return fallback ?? null;
+    }
+    runtimeOptionalIdentifierValue(node) {
+        if (!ts.isIdentifier(node) || this.chainRecvByNode.has(node))
+            return null;
+        const local = this.resolveLocal(node);
+        const symbol = this.resolveValueSymbol(node);
+        const storage = local ?? (symbol ? this.globalsBySymbol.get(symbol) : undefined);
+        if (!storage || storage.type.kind !== "union" || this.armTag(storage.type.unionId, UNDEFINED_T) < 0)
+            return null;
+        const present = this.stripUndefinedArm(storage.type);
+        if (isUnitType(present))
+            return null;
+        return { value: varRef(storage.id, storage.type, locOf(node)), present, unionId: storage.type.unionId };
+    }
+    /** Recover the original optional union when a checked single-arm helper
+     * was installed before a strict property consumer could name its member.
+     * Recovery is limited to array element reads and storage roots marked by
+     * the optional-read analysis, so ordinary assertions keep their generic
+     * checked-narrow behavior. */
+    runtimeOptionalSourceValue(node, value) {
+        let origin = node;
+        while (ts.isParenthesizedExpression(origin))
+            origin = origin.expression;
+        let optionalOrigin = ts.isElementAccessExpression(origin);
+        if (ts.isIdentifier(origin)) {
+            const local = this.resolveLocal(origin);
+            const root = local ? this.runtimeOptionalRootOf(local) : null;
+            const global = this.globalOf(origin);
+            optionalOrigin =
+                (!!root && this.runtimeOptionalStorageLocals.has(root)) ||
+                    (!!global && (this.isRuntimeOptionalGlobal(global) ||
+                        (global.type.kind === "union" && this.armTag(global.type.unionId, UNDEFINED_T) >= 0)));
+        }
+        if (!optionalOrigin)
+            return null;
+        let source = value;
+        if (value.kind === "call" &&
+            this.checkedNarrowHelpers.has(value.callee) &&
+            value.args.length === 1 &&
+            value.args[0]?.type.kind === "union") {
+            source = value.args[0];
+        }
+        return source.type.kind === "union" && this.armTag(source.type.unionId, UNDEFINED_T) >= 0
+            ? source
+            : null;
+    }
+    /** A strict property or method receiver over an array-derived optional
+     * value. Reuse a plain read directly or stabilize an effectful receiver
+     * once, throw Node's member-read TypeError for a unit arm, and extract the
+     * expected present arm otherwise. */
+    runtimeOptionalPropertyReceiver(node, value, expected, member) {
+        const source = this.runtimeOptionalSourceValue(node, value);
+        if (source?.type.kind !== "union")
+            return null;
+        const def = this.unions.get(source.type.unionId);
+        const valueTag = this.armTag(source.type.unionId, expected);
+        if (!def ||
+            valueTag < 0 ||
+            !def.arms.every((arm) => typeEquals(arm, expected) || isUnitType(arm)))
+            return null;
+        const loc = locOf(node);
+        const repeatSource = isSafeToRepeat(source);
+        const stable = repeatSource ? null : this.declareHiddenLocal("%propertyRecv", source.type);
+        const stableRef = () => repeatSource ? source : varRef(stable.id, source.type, loc);
+        let result = {
+            kind: "unionNarrow",
+            unionId: source.type.unionId,
+            tag: valueTag,
+            value: stableRef(),
+            type: expected,
+            loc,
+        };
+        for (let i = def.arms.length - 1; i >= 0; i--) {
+            const arm = def.arms[i];
+            if (!arm || !isUnitType(arm))
+                continue;
+            const unit = arm.kind === "nullT" ? "null" : "undefined";
+            result = {
+                kind: "ternary",
+                cond: {
+                    kind: "unionIsTag",
+                    unionId: source.type.unionId,
+                    tag: i,
+                    negated: false,
+                    value: stableRef(),
+                    type: BOOL,
+                    loc,
+                },
+                then: nodeThrowExpr(1, "", `Cannot read properties of ${unit} (reading '${member}')`, expected, loc),
+                else_: result,
+                type: expected,
+                loc,
+            };
+        }
+        if (stable === null)
+            return result;
+        return {
+            kind: "seqExpr",
+            stmts: [{ kind: "varDecl", localId: stable.id, init: source, loc }],
+            result,
+            type: expected,
+            loc,
+        };
+    }
+    runtimeOptionalFieldKey(shapeId, field) {
+        return `${shapeId}:${field}`;
+    }
+    isRuntimeOptionalField(shapeId, field) {
+        return this.runtimeOptionalFields.has(this.runtimeOptionalFieldKey(shapeId, field));
+    }
+    isRuntimeOptionalGlobal(global) {
+        return this.runtimeOptionalGlobals.has(global);
+    }
+    isRuntimeOptionalArithmeticGlobal(global) {
+        return this.runtimeOptionalArithmeticGlobals.has(global);
+    }
+    /** The union produced when an unchecked array read reaches a typed slot
+     * whose checker type is the corresponding bare arm. */
+    runtimeOptionalWidening(actual, expected) {
+        if (actual.kind !== "union" || this.armTag(actual.unionId, UNDEFINED_T) < 0)
+            return null;
+        return typeEquals(this.stripUndefinedArm(actual), expected) ? actual : null;
+    }
+    runtimeOptionalType(t) {
+        if (t.kind === "union")
+            return this.armTag(t.unionId, UNDEFINED_T) >= 0 ? t : this.withUndefinedArmOf(t) ?? t;
+        if (t.kind === "void" || t.kind === "dyn" || t.kind === "jsval" || t.kind === "generator")
+            return t;
+        return this.withUndefinedArm(t);
+    }
+    promoteRuntimeOptionalParameter(node, type) {
+        const widened = this.runtimeOptionalType(type);
+        const symbol = this.checker.getSymbolAtLocation(node);
+        if (symbol)
+            this.runtimeOptionalBindingTypes.set(symbol, widened);
+        return widened;
+    }
+    promoteRuntimeOptionalFunctionReturn(node, type) {
+        const widened = this.runtimeOptionalType(type);
+        this.runtimeOptionalFunctionReturns.set(node, widened);
+        return widened;
+    }
+    runtimeOptionalFunctionReturnType(node, fallback) {
+        return this.runtimeOptionalFunctionReturns.get(node) ?? fallback;
+    }
+    /** 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. */
+    runtimeOptionalRecordField(type, field, fieldType) {
+        if (type.kind !== "record")
+            return type;
+        const shape = this.shapes.get(type.shapeId);
+        if (!shape)
+            return type;
+        const existing = shape.fields.find((f) => f.name === field);
+        if (!existing || typeEquals(existing.type, fieldType)) {
+            if (existing)
+                this.runtimeOptionalFields.add(this.runtimeOptionalFieldKey(type.shapeId, field));
+            return type;
+        }
+        const shapeId = this.shapes.intern(shape.fields.map((f) => ({ name: f.name, type: f.name === field ? fieldType : f.type })), shape.tuple === true, shape.indexValue, shape.declaredOrder);
+        this.runtimeOptionalFields.add(this.runtimeOptionalFieldKey(shapeId, field));
+        return { kind: "record", shapeId };
+    }
     /** Runs `fn` with the given aliased-typeof narrows applied (and restored
      * after) — the branch-scoping primitive. */
     narrowingAliases(narrows, fn) {
@@ -920,6 +1190,10 @@ export class Lowerer {
      * declaration: member reads call the getter (lower-exprs). */
     cjsAccessorFns = new Map();
     narrowHelpers = new Map();
+    /** Exact members of narrowHelpers produced by narrowedArmHelper. This
+     * lets property consumers recognize an earlier checked extraction by
+     * provenance instead of relying on its generated-name prefix. */
+    checkedNarrowHelpers = new Set();
     /** Interned `%iter.drain.<n>` helpers (classIteratorDrainCall): one per
      * receiver class — the eager drain of a class iterable's protocol into
      * a fresh element array, behind array/call spreads. */
@@ -1040,6 +1314,12 @@ export class Lowerer {
      * any body lowers: import headers and inline require statements call
      * dependency inits by these names. */
     initNameOf = new Map();
+    /** CommonJS module objects are scalar handles into the runtime registry.
+     * IDs are assigned in deterministic module order before any body lowers;
+     * the feature gate stays false for programs that never inspect the graph. */
+    cjsModuleIdOf = new Map();
+    cjsModuleFiles = [];
+    cjsModuleGraphEnabled = false;
     /** File → the id of its run-once guard global (a bool module global,
      * false at program start). Every non-entry module gets one: its %init
      * may be called from several importers/requirers, and the guard is what
@@ -1324,9 +1604,8 @@ export class Lowerer {
                     const spec = requireSpecOf(recvDecl.initializer);
                     const dep = spec === null
                         ? null
-                        : isRelativeSpecifier(spec)
-                            ? resolveImport(this.program, recvDecl.getSourceFile(), spec)
-                            : npmStaticDepSf7(this.program, recvDecl.getSourceFile(), spec);
+                        : resolveImport(this.program, recvDecl.getSourceFile(), spec) ??
+                            npmStaticDepSf7(this.program, recvDecl.getSourceFile(), spec);
                     if (dep)
                         symbol = this.cjsModuleExportSymbol(dep, ident.text);
                 }
@@ -1462,15 +1741,15 @@ export class Lowerer {
         return this.externalTypeSpecifierOfSymbol(this.checker.getSymbolAtLocation(value));
     }
     /** The source file a checker-resolved module-specifier node names. The
-     * checker path covers package.json aliases as well as relative imports;
-     * resolveImport is the fallback for the latter. */
+     * checker path is preferred; resolveImport is the canonical fallback for
+     * every project-module spelling. */
     moduleSourceFileOf(from, spec) {
         const moduleSymbol = this.checker.getSymbolAtLocation(spec);
         for (const decl of moduleSymbol ? this.checker.declarationsOf(moduleSymbol) : []) {
             if (ts.isSourceFile(decl))
                 return decl;
         }
-        return isRelativeSpecifier(spec.text) ? resolveImport(this.program, from, spec.text) : null;
+        return resolveImport(this.program, from, spec.text);
     }
     /** Follow one project-module export through the checker's resolved export
      * table, then recover its exact external route where alias declarations
@@ -1712,22 +1991,19 @@ export class Lowerer {
             return null;
         }
         const spec = importDecl.moduleSpecifier.text;
-        // Bare specifiers resolve only for opted-in --npm-static packages —
-        // their CJS entries take the same default-binding interop as a
-        // relative require; every other bare import answers null and keeps
-        // its own machinery.
-        const dep = isRelativeSpecifier(spec)
-            ? resolveImport(this.program, importDecl.getSourceFile(), spec)
-            : npmStaticDepSf7(this.program, importDecl.getSourceFile(), spec);
+        // Project aliases/self-references resolve through the same entry point as
+        // relative imports; an opted-in --npm-static package is the fallback.
+        const dep = resolveImport(this.program, importDecl.getSourceFile(), spec) ??
+            npmStaticDepSf7(this.program, importDecl.getSourceFile(), spec);
         if (!dep || !isJsSourceFile(dep) || isNodeEsmFile(dep))
             return null;
         return dep;
     }
     /** True when `expr` is an identifier bound by a top-level
-     * `const x = require("./local")` of a RELATIVE module — the CommonJS
-     * namespace binding — or of a bare specifier naming an opted-in
-     * --npm-static package (its CJS entry is a program module, so the
-     * binding is the same namespace over the same export table), or by a
+     * `const x = require("./local")` of a project module — relative,
+     * tsconfig-aliased, or package.json-mediated — or of a bare specifier
+     * naming an opted-in --npm-static package (its CJS entry is a program
+     * module, so the binding is the same namespace over the same export table), or by a
      * DEFAULT import of a CommonJS JS module (`import d from "./lib.cjs"`:
      * Node binds d to module.exports, the same value require answers).
      * Member accesses on it resolve through the export table (property
@@ -1752,7 +2028,7 @@ export class Lowerer {
             const spec = requireSpecOf(decl.initializer);
             if (spec === null)
                 return false;
-            if (!isRelativeSpecifier(spec) &&
+            if (resolveImport(this.program, decl.getSourceFile(), spec) === null &&
                 npmStaticDepSf7(this.program, decl.getSourceFile(), spec) === null) {
                 return false;
             }
@@ -1972,16 +2248,15 @@ export class Lowerer {
      * their external dependencies by name). Null for everything else
      * (builtins load nothing; the rest kept its preflight fence). */
     requireInitStmt(spec, node) {
-        // Relative requires resolve within the program; a BARE require can be
-        // a program-module edge too when it names an opted-in --npm-static
-        // package (one package requiring another — the resolution answered
-        // its shipped JS, the file is in the module order, and the reads
-        // alias its globals). Without the guarded %init call at this position
+        // Project requires resolve within the program; another bare require can
+        // be a program-module edge when it names an opted-in --npm-static package
+        // (one package requiring another — the resolution answered its shipped
+        // JS, the file is in the module order, and the reads alias its globals).
+        // Without the guarded %init call at this position
         // those globals stay uninitialized: the dep's module body would never
         // run.
-        const dep = isRelativeSpecifier(spec)
-            ? resolveImport(this.program, node.getSourceFile(), spec)
-            : npmStaticDepSf7(this.program, node.getSourceFile(), spec);
+        const dep = resolveImport(this.program, node.getSourceFile(), spec) ??
+            npmStaticDepSf7(this.program, node.getSourceFile(), spec);
         if (!dep || dep.fileName.endsWith(".json"))
             return null;
         if (this.asyncInitFiles.has(dep)) {
@@ -1991,11 +2266,33 @@ export class Lowerer {
         if (initName === undefined)
             return null;
         const loc = locOf(node);
-        return {
+        const init = {
             kind: "exprStmt",
             expr: { kind: "call", callee: initName, args: [], type: VOID, loc },
             loc,
         };
+        const parentModule = this.cjsModuleIdOf.get(node.getSourceFile());
+        const childModule = this.cjsModuleIdOf.get(dep);
+        if (parentModule === undefined || childModule === undefined)
+            return init;
+        return {
+            kind: "block",
+            body: [
+                {
+                    kind: "exprStmt",
+                    expr: {
+                        kind: "libCall",
+                        fn: "module.link",
+                        args: [numLit(parentModule, loc), numLit(childModule, loc)],
+                        type: VOID,
+                        loc,
+                    },
+                    loc,
+                },
+                init,
+            ],
+            loc,
+        };
     }
     /** True when this body should lower: everything with no reachable set,
      * the marked bodies in an externally-gated pass, and exactly the
@@ -2011,6 +2308,720 @@ export class Lowerer {
     collectJsonImports(parts) {
         return collectJsonImports(this, parts);
     }
+    /** Discover the unchecked-array values that cross static ABI/storage
+     * boundaries before any function body or module initializer is emitted.
+     * TypeScript's default indexed-access type is a useful source annotation,
+     * but it is not a runtime proof; promoting only the affected slots keeps
+     * the rest of the dense ABI unchanged. */
+    analyzeRuntimeOptionalArrayReads(parts) {
+        const optionalSymbols = new Set();
+        const optionalReturns = new Set();
+        const arithmeticReturns = new Map();
+        const optionalParams = new Map();
+        const optionalFields = new Map();
+        const dynamicObjectEntryRows = new Set();
+        const sourceFiles = parts.map((p) => p.sf);
+        const fnDecls = parts.flatMap((p) => p.fnDecls);
+        // This fixed-point scan intentionally sees deferred bodies before
+        // reachability is known. Batch their binding queries through the
+        // facade's panic fence, then keep lookup free of lowering side effects:
+        // resolveValueSymbol also flushes deferred diagnostics and applies
+        // merged-namespace fences, whose authority remains ordinary lowering.
+        this.checker.prefetchSymbolRoots(sourceFiles);
+        const symbolOf = (node) => {
+            const s = this.checker.getSymbolAtLocation(node);
+            if (!s)
+                return null;
+            return s.flags & ts.SymbolFlags.Alias ? this.checker.getAliasedSymbol(s) : s;
+        };
+        const functionDeclBySymbol = new Map();
+        const signatureBySymbol = new Map();
+        for (const [symbol, sig] of this.fnSigsBySymbol)
+            signatureBySymbol.set(symbol, { params: sig.params, returnType: sig.returnType, top: sig });
+        for (const decl of fnDecls) {
+            const symbol = declSymbolOf(this, decl);
+            if (symbol)
+                functionDeclBySymbol.set(symbol, decl);
+        }
+        for (const sf of sourceFiles) {
+            ts.walkPreorder(sf, (node) => {
+                if ((ts.isMethodDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node)) &&
+                    node.body && node.name && (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name))) {
+                    const symbol = symbolOf(node.name);
+                    if (symbol)
+                        functionDeclBySymbol.set(symbol, node);
+                }
+            });
+        }
+        for (const info of this.classes.values()) {
+            for (const { mName, member } of this.classMethodMembers(info)) {
+                if (!member.name || !(ts.isIdentifier(member.name) || ts.isStringLiteral(member.name)))
+                    continue;
+                const symbol = symbolOf(member.name);
+                const sig = info.methods.get(mName);
+                if (symbol && sig)
+                    signatureBySymbol.set(symbol, { params: sig.params, returnType: sig.ret, method: sig });
+            }
+        }
+        const peel = (node) => {
+            let e = node;
+            while (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isTypeAssertion(e) || ts.isNonNullExpression(e)) {
+                e = e.expression;
+            }
+            return e;
+        };
+        const explicitlyNonNull = (node) => {
+            let e = node;
+            while (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isTypeAssertion(e) || ts.isNonNullExpression(e)) {
+                if (ts.isNonNullExpression(e))
+                    return true;
+                e = e.expression;
+            }
+            return false;
+        };
+        const isArrayRead = (node) => {
+            const e = peel(node);
+            if (!ts.isElementAccessExpression(e))
+                return false;
+            return this.mapTypeOf(this.typeOf(e.expression))?.kind === "array";
+        };
+        const isDynamicObjectEntryRead = (node) => {
+            const read = peel(node);
+            if (!ts.isElementAccessExpression(read) || !ts.isIdentifier(read.expression))
+                return false;
+            const source = symbolOf(read.expression);
+            const declaration = source ? this.checker.valueDeclarationOf(source) : undefined;
+            if (!declaration || !ts.isVariableDeclaration(declaration) || !declaration.initializer)
+                return false;
+            const init = peel(declaration.initializer);
+            if (!ts.isCallExpression(init) || !ts.isPropertyAccessExpression(init.expression))
+                return false;
+            if (init.expression.name.text !== "entries" || !this.isStdlibGlobal(init.expression.expression, "Object"))
+                return false;
+            const object = init.arguments[0];
+            const objectType = object ? this.mapTypeOf(this.typeOf(object)) : null;
+            return objectType?.kind === "dyn" || objectType?.kind === "jsval";
+        };
+        const addUndefined = (t) => {
+            if (t.kind === "union")
+                return this.armTag(t.unionId, UNDEFINED_T) >= 0 ? t : this.withUndefinedArmOf(t) ?? t;
+            if (t.kind === "void" || t.kind === "dyn" || t.kind === "jsval" || t.kind === "generator")
+                return t;
+            return this.withUndefinedArm(t);
+        };
+        const fieldName = (node) => node.name.text;
+        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
+            // function/global ABI to `T | undefined`.
+            if (explicitlyNonNull(node))
+                return false;
+            const e = peel(node);
+            if (isArrayRead(e))
+                return true;
+            if (ts.isCallExpression(e) && this.runtimeOptionalReduceTypes.has(e))
+                return true;
+            if (ts.isCallExpression(e) &&
+                ts.isPropertyAccessExpression(e.expression) &&
+                (e.expression.name.text === "pop" || e.expression.name.text === "shift") &&
+                this.mapTypeOf(this.typeOf(e))?.kind === "union" &&
+                this.armTag(this.mapTypeOf(this.typeOf(e)).unionId, UNDEFINED_T) >= 0)
+                return true;
+            if (ts.isIdentifier(e))
+                return optionalSymbols.has(symbolOf(e) ?? {});
+            if (ts.isCallExpression(e) && ts.isIdentifier(e.expression)) {
+                return optionalReturns.has(symbolOf(e.expression) ?? {});
+            }
+            if (ts.isCallExpression(e) && ts.isPropertyAccessExpression(e.expression)) {
+                return optionalReturns.has(symbolOf(e.expression.name) ?? {});
+            }
+            if (ts.isConditionalExpression(e)) {
+                return mayBeOptional(e.whenTrue) || mayBeOptional(e.whenFalse);
+            }
+            if (ts.isBinaryExpression(e)) {
+                const op = e.operatorToken.kind;
+                if (op === ts.SyntaxKind.AmpersandAmpersandToken ||
+                    op === ts.SyntaxKind.BarBarToken ||
+                    op === ts.SyntaxKind.QuestionQuestionToken)
+                    return mayBeOptional(e.left) || mayBeOptional(e.right);
+            }
+            if (ts.isPropertyAccessExpression(e) && ts.isIdentifier(e.expression)) {
+                const fields = optionalFields.get(symbolOf(e.expression) ?? {});
+                return fields?.has(fieldName(e)) ?? false;
+            }
+            return false;
+        };
+        const optionalStringArithmeticType = (node) => {
+            const e = peel(node);
+            if (!ts.isBinaryExpression(e) || e.operatorToken.kind !== ts.SyntaxKind.PlusToken)
+                return null;
+            const stringArrayRead = (part) => {
+                const t = this.mapTypeOf(this.typeOf(part));
+                const p = peel(part);
+                if (t?.kind !== "string" || !ts.isElementAccessExpression(p))
+                    return false;
+                const recv = this.mapTypeOf(this.typeOf(p.expression));
+                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))
+                return null;
+            if (!(primitive(e.left) || stringArrayRead(e.left)) || !(primitive(e.right) || stringArrayRead(e.right)))
+                return null;
+            return { kind: "union", unionId: this.unions.intern([F64, STRING]) };
+        };
+        const noteField = (decl, name) => {
+            if (!ts.isIdentifier(decl.name))
+                return false;
+            const symbol = symbolOf(decl.name);
+            if (!symbol)
+                return false;
+            return noteFieldSymbol(symbol, name);
+        };
+        const noteFieldSymbol = (symbol, name) => {
+            const set = optionalFields.get(symbol) ?? new Set();
+            const before = set.size;
+            set.add(name);
+            optionalFields.set(symbol, set);
+            return set.size !== before;
+        };
+        const scanPattern = (name, init) => {
+            if (!ts.isArrayBindingPattern(name))
+                return false;
+            const sourceType = this.mapTypeOf(this.typeOf(init));
+            if (sourceType?.kind !== "array")
+                return false;
+            let changed = false;
+            name.elements.forEach((el) => {
+                if (ts.isOmittedExpression(el) || el.name === undefined || el.dotDotDotToken)
+                    return;
+                if (ts.isIdentifier(el.name)) {
+                    const symbol = symbolOf(el.name);
+                    if (symbol && !el.initializer && !optionalSymbols.has(symbol)) {
+                        optionalSymbols.add(symbol);
+                        // 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.
+                        const mapped = sourceType.elem;
+                        if (mapped && mapped.kind !== "void" && mapped.kind !== "dyn" && mapped.kind !== "jsval") {
+                            const widened = mapped.kind === "union" ? this.withUndefinedArmOf(mapped) : this.withUndefinedArm(mapped);
+                            if (widened) {
+                                this.runtimeOptionalBindingTypes.set(symbol, widened);
+                                const global = this.globalsBySymbol.get(symbol);
+                                if (global) {
+                                    global.type = widened;
+                                    this.runtimeOptionalGlobals.add(global);
+                                }
+                            }
+                        }
+                        changed = true;
+                    }
+                }
+            });
+            return changed;
+        };
+        const hofCallbackIndices = (name, hasInitialValue) => {
+            if (name === "reduce" || name === "reduceRight")
+                return hasInitialValue ? [1] : [0, 1];
+            if (name === "map" || name === "filter" || name === "forEach" ||
+                name === "find" || name === "findIndex" || name === "findLast" ||
+                name === "findLastIndex" || name === "some" || name === "every" ||
+                name === "flatMap")
+                return [0];
+            return null;
+        };
+        const bodyReturnsOptional = (fn) => {
+            if (!fn.body)
+                return false;
+            if (!ts.isBlock(fn.body))
+                return mayBeOptional(fn.body);
+            let found = false;
+            ts.walkPreorder(fn.body, (node) => {
+                if (node !== fn.body && (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node)))
+                    return "skip";
+                if (ts.isReturnStatement(node) && node.expression && mayBeOptional(node.expression))
+                    found = true;
+                return undefined;
+            });
+            return found;
+        };
+        const promoteHofCallback = (callback, parameterIndices, seen = new Set()) => {
+            let changed = false;
+            const checkerTypeContainsTypeParameter = (type) => {
+                if ((type.flags & ts.TypeFlags.TypeParameter) !== 0)
+                    return true;
+                return type.isUnionType() && ts.constituentTypes(type).some(checkerTypeContainsTypeParameter);
+            };
+            const promoteNode = (fn) => {
+                for (const parameterIndex of parameterIndices) {
+                    const parameter = fn.parameters[parameterIndex];
+                    if (!parameter)
+                        continue;
+                    const symbol = ts.isIdentifier(parameter.name) ? symbolOf(parameter.name) : null;
+                    const checkerType = this.typeOf(parameter.name);
+                    const mapped = this.mapTypeOf(checkerType);
+                    // Generic callbacks are monomorphized by their call-site binder.
+                    // During this prepass the type parameter has no static ABI yet;
+                    // asking irTypeOf to invent one poisons otherwise valid generic
+                    // value/HOF programs. Leave that parameter at its generic
+                    // signature and let the normal instantiation path specialize it.
+                    const current = mapped ??
+                        (checkerTypeContainsTypeParameter(checkerType) ? null : this.irTypeOf(parameter.name));
+                    if (!current)
+                        continue;
+                    if (!ts.isIdentifier(parameter.name)) {
+                        const widened = this.runtimeOptionalType(current);
+                        const previous = this.runtimeOptionalPatternTypes.get(parameter.name);
+                        this.runtimeOptionalPatternTypes.set(parameter.name, widened);
+                        if (!previous || !typeEquals(previous, widened))
+                            changed = true;
+                    }
+                    if (symbol) {
+                        const widened = this.runtimeOptionalType(current);
+                        const previous = this.runtimeOptionalBindingTypes.get(symbol);
+                        this.runtimeOptionalBindingTypes.set(symbol, widened);
+                        if (!previous || !typeEquals(previous, widened))
+                            changed = true;
+                        if (!optionalSymbols.has(symbol)) {
+                            optionalSymbols.add(symbol);
+                            changed = true;
+                        }
+                    }
+                }
+                const fnType = this.mapTypeOf(this.typeOf(fn));
+                if (fnType?.kind === "func" && bodyReturnsOptional(fn)) {
+                    const widenedReturn = this.runtimeOptionalType(fnType.ret);
+                    const previousReturn = this.runtimeOptionalFunctionReturnType(fn, fnType.ret);
+                    this.runtimeOptionalFunctionReturns.set(fn, widenedReturn);
+                    if (!typeEquals(previousReturn, widenedReturn))
+                        changed = true;
+                }
+            };
+            if (ts.isArrowFunction(callback) || ts.isFunctionExpression(callback) || ts.isFunctionDeclaration(callback) || ts.isMethodDeclaration(callback)) {
+                promoteNode(callback);
+                return changed;
+            }
+            const callbackName = ts.isIdentifier(callback)
+                ? callback
+                : ts.isPropertyAccessExpression(callback)
+                    ? callback.name
+                    : null;
+            if (!callbackName)
+                return false;
+            const symbol = symbolOf(callbackName);
+            if (!symbol || seen.has(symbol))
+                return false;
+            // Generic function values are pinned and monomorphized by the normal
+            // contextual-value path when the HOF lowers its callback. Promoting
+            // their type-parameter body here either asks for an impossible
+            // monomorphic ABI or poisons valid generic value programs.
+            if (this.genericFnsBySymbol.has(symbol))
+                return false;
+            seen.add(symbol);
+            const declaration = this.checker.valueDeclarationOf(symbol);
+            if (declaration && ts.isVariableDeclaration(declaration) && declaration.initializer) {
+                if (promoteHofCallback(peel(declaration.initializer), parameterIndices, seen))
+                    changed = true;
+            }
+            const sig = signatureBySymbol.get(symbol);
+            if (sig) {
+                for (const parameterIndex of parameterIndices) {
+                    if (!sig.params[parameterIndex])
+                        continue;
+                    const before = sig.params[parameterIndex].type;
+                    sig.params[parameterIndex].type = this.runtimeOptionalType(before);
+                    if (!typeEquals(before, sig.params[parameterIndex].type))
+                        changed = true;
+                }
+            }
+            const fn = functionDeclBySymbol.get(symbol);
+            if (fn)
+                promoteNode(fn);
+            const valueType = this.runtimeOptionalBindingTypes.get(symbol) ?? this.mapTypeOf(this.typeOf(callback));
+            if (valueType?.kind === "func") {
+                const params = valueType.params.slice();
+                for (const parameterIndex of parameterIndices) {
+                    if (params[parameterIndex])
+                        params[parameterIndex] = this.runtimeOptionalType(params[parameterIndex]);
+                }
+                const promoted = { ...valueType, params };
+                const previous = this.runtimeOptionalBindingTypes.get(symbol);
+                this.runtimeOptionalBindingTypes.set(symbol, promoted);
+                if (!previous || !typeEquals(previous, promoted))
+                    changed = true;
+                const global = this.globalsBySymbol.get(symbol);
+                if (global)
+                    global.type = promoted;
+                // A callback-typed parameter used by a native array HOF changes
+                // the containing function's own call ABI. Record that edge in the
+                // already-collected signature as well as on the body binding, so a
+                // caller can promote the concrete callback value it supplies on a
+                // later fixed-point pass (`wrapper(xs, predicate)` ->
+                // `xs.some(predicate)`).
+                if (declaration && ts.isParameter(declaration)) {
+                    const owner = declaration.parent;
+                    let ownerSymbol = null;
+                    if (ts.isFunctionDeclaration(owner))
+                        ownerSymbol = declSymbolOf(this, owner) ?? null;
+                    else if ((ts.isMethodDeclaration(owner) || ts.isGetAccessorDeclaration(owner) || ts.isSetAccessorDeclaration(owner)) &&
+                        owner.name)
+                        ownerSymbol = symbolOf(owner.name);
+                    const ownerSig = ownerSymbol ? signatureBySymbol.get(ownerSymbol) : undefined;
+                    const ownerIndex = ts.isFunctionLike(owner) ? owner.parameters.indexOf(declaration) : -1;
+                    const slot = ownerIndex >= 0 ? ownerSig?.params[ownerIndex] : undefined;
+                    if (slot && !typeEquals(slot.type, promoted)) {
+                        slot.type = promoted;
+                        changed = true;
+                    }
+                }
+            }
+            return changed;
+        };
+        const callbackReturnsOptional = (callback, seen = new Set()) => {
+            const node = peel(callback);
+            if (ts.isArrowFunction(node) || ts.isFunctionExpression(node))
+                return bodyReturnsOptional(node);
+            const symbol = symbolOf(ts.isPropertyAccessExpression(node) ? node.name : node);
+            if (!symbol || seen.has(symbol))
+                return false;
+            seen.add(symbol);
+            const fn = functionDeclBySymbol.get(symbol);
+            if (fn)
+                return bodyReturnsOptional(fn);
+            const decl = this.checker.valueDeclarationOf(symbol);
+            return !!decl && ts.isVariableDeclaration(decl) && !!decl.initializer && callbackReturnsOptional(decl.initializer, seen);
+        };
+        const scanFile = (sf) => {
+            let changed = false;
+            ts.walkPreorder(sf, (node) => {
+                if (ts.isVariableDeclaration(node)) {
+                    if (node.initializer) {
+                        if (ts.isIdentifier(node.name) && isDynamicObjectEntryRead(node.initializer)) {
+                            const symbol = symbolOf(node.name);
+                            if (symbol && !dynamicObjectEntryRows.has(symbol)) {
+                                dynamicObjectEntryRows.add(symbol);
+                                changed = true;
+                            }
+                        }
+                        else if (ts.isIdentifier(node.name) && mayBeOptional(node.initializer)) {
+                            const symbol = symbolOf(node.name);
+                            if (symbol && !optionalSymbols.has(symbol)) {
+                                optionalSymbols.add(symbol);
+                                changed = true;
+                            }
+                        }
+                        if (ts.isIdentifier(node.name)) {
+                            const valueSymbol = ts.isIdentifier(peel(node.initializer))
+                                ? symbolOf(peel(node.initializer))
+                                : ts.isPropertyAccessExpression(peel(node.initializer))
+                                    ? symbolOf(peel(node.initializer).name)
+                                    : null;
+                            const symbol = symbolOf(node.name);
+                            const sourceSig = valueSymbol ? signatureBySymbol.get(valueSymbol) : undefined;
+                            const sourceOptional = !!sourceSig &&
+                                (optionalReturns.has(valueSymbol) ||
+                                    (sourceSig.returnType.kind === "union" && this.armTag(sourceSig.returnType.unionId, UNDEFINED_T) >= 0) ||
+                                    sourceSig.params.some((p) => p.type.kind === "union" && this.armTag(p.type.unionId, UNDEFINED_T) >= 0));
+                            if (symbol && valueSymbol && sourceOptional) {
+                                const aliasNew = !optionalReturns.has(symbol);
+                                if (aliasNew)
+                                    optionalReturns.add(symbol);
+                                if (aliasNew)
+                                    changed = true;
+                                const valueType = this.mapTypeOf(this.typeOf(node.name));
+                                if (valueType?.kind === "func" && sourceSig) {
+                                    const promotedFn = {
+                                        ...valueType,
+                                        params: sourceSig.params.map((p) => p.type),
+                                        ret: sourceSig.returnType,
+                                    };
+                                    const previous = this.runtimeOptionalBindingTypes.get(symbol);
+                                    if (!previous || !typeEquals(previous, promotedFn)) {
+                                        this.runtimeOptionalBindingTypes.set(symbol, promotedFn);
+                                        const global = this.globalsBySymbol.get(symbol);
+                                        if (global)
+                                            global.type = promotedFn;
+                                        changed = true;
+                                    }
+                                }
+                            }
+                        }
+                        if (scanPattern(node.name, node.initializer))
+                            changed = true;
+                        if (ts.isIdentifier(node.name) && ts.isObjectLiteralExpression(peel(node.initializer))) {
+                            const object = peel(node.initializer);
+                            for (const prop of object.properties) {
+                                if (!ts.isPropertyAssignment(prop) && !ts.isShorthandPropertyAssignment(prop))
+                                    continue;
+                                const name = prop.name;
+                                if (!name || !(ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)))
+                                    continue;
+                                const value = ts.isPropertyAssignment(prop) ? prop.initializer : prop.name;
+                                if (mayBeOptional(value) && noteField(node, name.text))
+                                    changed = true;
+                            }
+                        }
+                    }
+                }
+                if (ts.isBinaryExpression(node) &&
+                    (node.operatorToken.kind === ts.SyntaxKind.EqualsToken ||
+                        node.operatorToken.kind === ts.SyntaxKind.QuestionQuestionEqualsToken ||
+                        node.operatorToken.kind === ts.SyntaxKind.BarBarEqualsToken ||
+                        node.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandEqualsToken) &&
+                    mayBeOptional(node.right)) {
+                    if (ts.isIdentifier(node.left)) {
+                        const symbol = symbolOf(node.left);
+                        if (symbol && !optionalSymbols.has(symbol)) {
+                            optionalSymbols.add(symbol);
+                            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))
+                            changed = true;
+                    }
+                }
+                if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+                    const callbackIndices = hofCallbackIndices(node.expression.name.text, node.arguments.length >= 2);
+                    const receiverNode = node.expression.expression;
+                    const receiver = this.mapTypeOf(this.typeOf(receiverNode));
+                    const callback = callbackIndices === null ? undefined : node.arguments[0];
+                    const tuple = receiver?.kind === "record" && this.shapes.get(receiver.shapeId)?.tuple === true;
+                    // A JS/evolving-any array may have acquired a precise FLOW type
+                    // at this call while its actual binding remains a checked-dynamic
+                    // array. Its callback consumes DYN values through runtime method
+                    // dispatch, so widening that callback to the native array value
+                    // ABI makes it impossible to box back into DYN. Judge a simple
+                    // binding by its declaration type, the same storage fact local
+                    // declaration lowering uses.
+                    let nativeArrayReceiver = receiver?.kind === "array" || tuple;
+                    if (nativeArrayReceiver && ts.isIdentifier(receiverNode)) {
+                        const receiverSymbol = symbolOf(receiverNode);
+                        const declaration = receiverSymbol ? this.checker.valueDeclarationOf(receiverSymbol) : undefined;
+                        if (declaration && ts.isVariableDeclaration(declaration)) {
+                            const declared = this.mapTypeOf(this.typeOf(declaration.name));
+                            if (declared?.kind !== "array" && !(declared?.kind === "record" && this.shapes.get(declared.shapeId)?.tuple === true)) {
+                                nativeArrayReceiver = false;
+                            }
+                        }
+                    }
+                    if (nativeArrayReceiver && callback && !ts.isSpreadElement(callback)) {
+                        if (promoteHofCallback(callback, callbackIndices))
+                            changed = true;
+                        const method = node.expression.name.text;
+                        if ((method === "reduce" || method === "reduceRight") &&
+                            (node.arguments.length < 2 || callbackReturnsOptional(callback))) {
+                            if (promoteHofCallback(callback, [0, 1]))
+                                changed = true;
+                            const result = this.runtimeOptionalType(this.irTypeOf(node));
+                            const previous = this.runtimeOptionalReduceTypes.get(node);
+                            if (!previous || !typeEquals(previous, result)) {
+                                this.runtimeOptionalReduceTypes.set(node, result);
+                                changed = true;
+                            }
+                        }
+                    }
+                }
+                if (ts.isCallExpression(node) &&
+                    (ts.isIdentifier(node.expression) || ts.isPropertyAccessExpression(node.expression))) {
+                    const calleeNode = ts.isIdentifier(node.expression) ? node.expression : node.expression.name;
+                    const symbol = symbolOf(calleeNode);
+                    if (!symbol)
+                        return;
+                    const sig = signatureBySymbol.get(symbol);
+                    if (!sig) {
+                        const decl = this.checker.valueDeclarationOf(symbol);
+                        if (decl && ts.isVariableDeclaration(decl) && decl.initializer && ts.isIdentifier(decl.initializer)) {
+                            const source = symbolOf(decl.initializer);
+                            const sourceSig = source ? signatureBySymbol.get(source) : undefined;
+                            if (sourceSig) {
+                                node.arguments.forEach((arg, i) => {
+                                    if (ts.isSpreadElement(arg) || !mayBeOptional(arg) || !sourceSig.params[i])
+                                        return;
+                                    const before = sourceSig.params[i].type;
+                                    sourceSig.params[i].type = this.runtimeOptionalType(before);
+                                    if (!typeEquals(before, sourceSig.params[i].type)) {
+                                        changed = true;
+                                        const sourceFn = functionDeclBySymbol.get(source);
+                                        const parameter = sourceFn?.parameters[i];
+                                        if (parameter) {
+                                            for (const bound of boundIdentifiersOf(parameter.name)) {
+                                                const boundSymbol = symbolOf(bound);
+                                                if (boundSymbol && !optionalSymbols.has(boundSymbol)) {
+                                                    optionalSymbols.add(boundSymbol);
+                                                    changed = true;
+                                                }
+                                            }
+                                        }
+                                    }
+                                });
+                            }
+                        }
+                        return;
+                    }
+                    node.arguments.forEach((arg, i) => {
+                        const callbackSlot = sig.params[i]?.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] : []);
+                            if (optionalCallbackParams.length > 0 && promoteHofCallback(arg, optionalCallbackParams)) {
+                                changed = true;
+                            }
+                        }
+                        if (ts.isSpreadElement(arg) || !mayBeOptional(arg) || !sig.params[i])
+                            return;
+                        const set = optionalParams.get(symbol) ?? new Set();
+                        const before = set.size;
+                        set.add(i);
+                        optionalParams.set(symbol, set);
+                        if (set.size !== before) {
+                            changed = true;
+                            const callee = functionDeclBySymbol.get(symbol);
+                            const parameter = callee?.parameters[i];
+                            if (parameter) {
+                                for (const bound of boundIdentifiersOf(parameter.name)) {
+                                    const boundSymbol = symbolOf(bound);
+                                    if (boundSymbol && !optionalSymbols.has(boundSymbol)) {
+                                        optionalSymbols.add(boundSymbol);
+                                        changed = true;
+                                    }
+                                }
+                            }
+                        }
+                    });
+                }
+            });
+            return changed;
+        };
+        const scanReturns = (symbol, decl) => {
+            if (!decl.body)
+                return false;
+            let changed = false;
+            if (!ts.isBlock(decl.body) && mayBeOptional(decl.body) && !optionalReturns.has(symbol)) {
+                optionalReturns.add(symbol);
+                changed = true;
+            }
+            if (!ts.isBlock(decl.body)) {
+                const arithmetic = optionalStringArithmeticType(decl.body);
+                if (arithmetic && !arithmeticReturns.has(symbol)) {
+                    arithmeticReturns.set(symbol, arithmetic);
+                    changed = true;
+                }
+            }
+            ts.walkPreorder(decl.body, (node) => {
+                if (node !== decl.body && (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node)))
+                    return "skip";
+                if (ts.isReturnStatement(node) && node.expression && mayBeOptional(node.expression) && !optionalReturns.has(symbol)) {
+                    optionalReturns.add(symbol);
+                    changed = true;
+                }
+                if (ts.isReturnStatement(node) && node.expression) {
+                    const arithmetic = optionalStringArithmeticType(node.expression);
+                    if (arithmetic && !arithmeticReturns.has(symbol)) {
+                        arithmeticReturns.set(symbol, arithmetic);
+                        changed = true;
+                    }
+                }
+                return undefined;
+            });
+            return changed;
+        };
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const sf of sourceFiles)
+                if (scanFile(sf))
+                    changed = true;
+            for (const [symbol, decl] of functionDeclBySymbol)
+                if (scanReturns(symbol, decl))
+                    changed = true;
+        }
+        for (const [symbol, sig] of signatureBySymbol) {
+            const params = optionalParams.get(symbol);
+            if (params) {
+                for (const i of params) {
+                    const shape = sig.params[i];
+                    if (shape)
+                        shape.type = addUndefined(shape.type);
+                }
+            }
+            if (optionalReturns.has(symbol)) {
+                const next = sig.returnType.kind === "promise"
+                    ? { kind: "promise", inner: addUndefined(sig.returnType.inner) }
+                    : addUndefined(sig.returnType);
+                sig.returnType = next;
+                if (sig.top)
+                    sig.top.returnType = next;
+                if (sig.method)
+                    sig.method.ret = next;
+            }
+            const arithmetic = arithmeticReturns.get(symbol);
+            if (arithmetic && sig.returnType.kind !== "promise") {
+                sig.returnType = arithmetic;
+                if (sig.top)
+                    sig.top.returnType = arithmetic;
+                if (sig.method)
+                    sig.method.ret = arithmetic;
+                const decl = functionDeclBySymbol.get(symbol);
+                if (decl)
+                    this.runtimeOptionalFunctionReturns.set(decl, arithmetic);
+            }
+        }
+        for (const sf of sourceFiles) {
+            ts.walkPreorder(sf, (node) => {
+                if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name))
+                    return;
+                const symbol = symbolOf(node.name);
+                if (!symbol)
+                    return;
+                const fields = optionalFields.get(symbol);
+                if (!dynamicObjectEntryRows.has(symbol) && !optionalSymbols.has(symbol) && !fields)
+                    return;
+                const current = this.mapTypeOf(this.typeOf(node.name));
+                if (!current)
+                    return;
+                let promoted = dynamicObjectEntryRows.has(symbol) ? DYN : current;
+                if (!dynamicObjectEntryRows.has(symbol) && optionalSymbols.has(symbol))
+                    promoted = addUndefined(promoted);
+                if (promoted.kind === "func" && node.initializer && ts.isIdentifier(node.initializer)) {
+                    const sourceSig = this.fnSigOf(node.initializer);
+                    if (sourceSig) {
+                        promoted = {
+                            ...promoted,
+                            params: sourceSig.params.filter((p) => p.mode !== "dynRest").map((p) => p.type),
+                            ret: sourceSig.returnType,
+                        };
+                    }
+                }
+                if (fields && promoted.kind === "record") {
+                    for (const field of fields) {
+                        const source = promoted.kind === "record"
+                            ? this.shapes.get(promoted.shapeId)?.fields.find((f) => f.name === field)
+                            : undefined;
+                        if (!source)
+                            continue;
+                        promoted = this.runtimeOptionalRecordField(promoted, field, addUndefined(source.type));
+                    }
+                }
+                if (!typeEquals(promoted, current)) {
+                    this.runtimeOptionalBindingTypes.set(symbol, promoted);
+                    const global = ts.isIdentifier(node.name) ? this.globalOf(node.name) : this.globalsBySymbol.get(symbol);
+                    if (global) {
+                        global.type = promoted;
+                        this.runtimeOptionalGlobals.add(global);
+                    }
+                }
+                else if (promoted.kind === "union" && this.armTag(promoted.unionId, UNDEFINED_T) >= 0) {
+                    const global = ts.isIdentifier(node.name) ? this.globalOf(node.name) : this.globalsBySymbol.get(symbol);
+                    if (global)
+                        this.runtimeOptionalGlobals.add(global);
+                }
+            });
+        }
+    }
     run() {
         const parts = this.splitFiles();
         // The coverage remainder deliberately visits every body that reachable
@@ -2024,6 +3035,7 @@ export class Lowerer {
                 this.checker.prefetchSourceFile(fp.sf);
         }
         this.collectProgram(parts);
+        this.analyzeRuntimeOptionalArrayReads(parts);
         // Decorated classes analyze AFTER the whole collection pass: a
         // decorator's return type may name a subclass declared below the
         // class, and reference lowering needs each class's rebindability
@@ -2031,6 +3043,7 @@ export class Lowerer {
         for (const info of this.classes.values())
             analyzeClassDecoration(this, info);
         this.prepareModuleInits(parts);
+        prepareCjsModuleGraph(this, parts);
         const functions = [];
         for (const fp of parts) {
             for (const decl of fp.fnDecls) {
@@ -2252,7 +3265,7 @@ export class Lowerer {
         const module = this.diags.length > 0
             ? null
             : {
-                irVersion: 6,
+                irVersion: 8,
                 sourceFile: this.entry.fileName,
                 functions,
                 classes: artifacts.classes,
@@ -2395,12 +3408,14 @@ export class Lowerer {
         // will reuse the same answers later.
         this.prefetchClassCollection(parts.flatMap((fp) => fp.classDecls));
         this.collectProgram(parts);
+        this.analyzeRuntimeOptionalArrayReads(parts);
         // Decorated classes analyze post-collection here too: the %init seeds
         // lower the decoration calls, whose edges (decorator bodies, construct
         // thunks) reachable emit must see.
         for (const info of this.classes.values())
             analyzeClassDecoration(this, info);
         this.prepareModuleInits(parts);
+        prepareCjsModuleGraph(this, parts);
         // Every lowerable body, by emitted-function name. The names double as
         // retained-function keys and are deterministic by construction
         // (qualified declaration names).
@@ -3194,11 +4209,14 @@ export class Lowerer {
         const def = this.unions.get(unionId);
         return def ? def.arms.flatMap((arm, tag) => (this.isArrayValueType(arm) ? [tag] : [])) : [];
     }
-    /** isJsonSafeType with this Lowerer's registries — the shared fence for
-     * what JSON.stringify accepts and what a checked cast can validate. */
+    /** Checked JSON conversion excludes undefined array slots because JSON
+     * text cannot preserve that distinction. */
     jsonSafe(t) {
         return isJsonSafeType(t, (id) => this.shapes.get(id), (id) => this.unions.get(id));
     }
+    jsonStringifySafe(t) {
+        return isJsonStringifySafeType(t, (id) => this.shapes.get(id), (id) => this.unions.get(id));
+    }
     /** True when a type is a BARE undefined-armed union — the one JSON-unsafe
      * shape whose rejections deserve their own wording: Node's stringify of
      * bare undefined is not a string at all and JSON text never matches the
@@ -3563,10 +4581,18 @@ export class Lowerer {
             const undefArmedOk = expected.kind === "union" &&
                 (this.unions
                     .get(expected.unionId)
-                    ?.arms.every((a) => a.kind === "undefinedT" || this.jsonSafe(a)) ??
+                    ?.arms.every((a) => a.kind === "undefinedT" ||
+                    this.jsonSafe(a) ||
+                    isDynTypedRefType(a) ||
+                    DYN_HANDLE_KINDS.has(a.kind)) ??
                     false);
             const bytesOk = expected.kind === "bytes" && expected.elem === "u8";
             const errorOk = expected.kind === "object" && expected.className === "%Error";
+            // Program and runtime class instances can return only from a
+            // compiler-owned typed-reference capsule. A parsed/plain dyn object
+            // fails the runtime check; an exact capsule unwraps the original
+            // instance and preserves identity.
+            const classOk = isDynTypedRefType(expected);
             // ADAPTABLE function targets (the checked-dynamic function
             // boundary's OUT direction — `const wrapped: F = mustCall(fn)`):
             // check callable-kind, then unwrap an identical boxed signature
@@ -3574,7 +4600,8 @@ export class Lowerer {
             // arguments/results per F.
             const funcOk = expected.kind === "func" &&
                 canAdaptDynFuncTo(expected, (id) => this.shapes.get(id), (id) => this.unions.get(id));
-            if (this.jsonSafe(expected) || undefArmedOk || bytesOk || errorOk || funcOk) {
+            const handleOk = DYN_HANDLE_KINDS.has(expected.kind);
+            if (this.jsonSafe(expected) || undefArmedOk || bytesOk || errorOk || classOk || funcOk || handleOk) {
                 return { kind: "dynCheck", value: expr, type: expected, loc: expr.loc };
             }
             return expr;
@@ -5599,10 +6626,13 @@ export class Lowerer {
             return null;
         const key = `${fromId}:${tag}`;
         const existing = this.narrowHelpers.get(key);
-        if (existing)
+        if (existing) {
+            this.checkedNarrowHelpers.add(existing);
             return existing;
+        }
         const name = `%union.narrow.${this.narrowHelpers.size}`;
         this.narrowHelpers.set(key, name);
+        this.checkedNarrowHelpers.add(name);
         const fromT = { kind: "union", unionId: fromId };
         const u = { kind: "varRef", localId: "u.0", type: fromT, loc };
         const body = [];
@@ -7072,6 +8102,14 @@ export class Lowerer {
             }
             const local = this.declareLocal(decl.name, name, shape.type, true);
             params.push({ localId: local.id, name, type: local.type });
+            if (shape.mode === "required" &&
+                shape.type.kind === "union" &&
+                this.armTag(shape.type.unionId, UNDEFINED_T) >= 0 &&
+                typeEquals(this.stripUndefinedArm(shape.type), this.mapTypeOf(this.typeOf(decl.name)) ?? VOID)) {
+                const root = this.runtimeOptionalRootOf(local);
+                this.runtimeOptionalLocals.add(root);
+                this.runtimeOptionalStorageLocals.add(root);
+            }
         });
         return { params, prologue };
     }
@@ -7313,11 +8351,8 @@ export class Lowerer {
     lowerScopedBlock(stmt) {
         return lowerScopedBlock(this, stmt);
     }
-    /** Lowers inside a control-construct marker (loop/switch/labeled block/
-     * try-with-finally/finally block) so the jump fences below know what a
-     * break/continue/return crosses. `labels` carries the construct's JS
-     * label names when the source statement was labeled — labeled jumps
-     * resolve against them. */
+    /** Lowers inside a jump-target marker. `labels` carries the construct's
+     * source label names so labeled jumps resolve against them. */
     inCtl(kind, fn, labels) {
         this.ctx.ctl.push(labels !== undefined && labels.length > 0 ? { kind, labels } : { kind });
         try {
@@ -7338,9 +8373,6 @@ export class Lowerer {
         this.pendingLabels = null;
         return labels ?? undefined;
     }
-    rejectJumpCrossingFinally(kw, stmt, label) {
-        return rejectJumpCrossingFinally(this, kw, stmt, label);
-    }
     lowerStmt(stmt) {
         return lowerStmt(this, stmt);
     }
@@ -7540,7 +8572,13 @@ export class Lowerer {
         return lowerExprStatement(this, expr);
     }
     lowerForOf(stmt) {
-        return lowerForOf(this, stmt);
+        const optional = this.runtimeOptionalIdentifierValue(stmt.expression);
+        if (optional?.present.kind !== "string")
+            return lowerForOf(this, stmt);
+        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));
     }
     lowerForStatement(stmt) {
         return lowerForStatement(this, stmt);
@@ -7627,7 +8665,44 @@ export class Lowerer {
         return rejectThisInObjectMethod(this, node);
     }
     lowerElementAccess(expr) {
-        return lowerElementAccess(this, expr);
+        if (ts.isPropertyAccessExpression(expr.expression) &&
+            ts.isIdentifier(expr.expression.expression) &&
+            expr.expression.expression.text === "require" &&
+            expr.expression.name.text === "cache") {
+            return lowerElementAccess(this, expr);
+        }
+        const receiver = this.runtimeOptionalIdentifierValue(expr.expression);
+        const receiverValue = receiver && (receiver.present.kind === "array" || receiver.present.kind === "record")
+            ? (() => {
+                const helper = this.narrowedArmHelper(receiver.unionId, receiver.present, locOf(expr.expression));
+                return helper ? { kind: "call", callee: helper, args: [receiver.value], type: receiver.present, loc: locOf(expr.expression) } : null;
+            })()
+            : null;
+        if (receiverValue && receiver?.present.kind === "record" && ts.isNumericLiteral(expr.argumentExpression)) {
+            const shape = this.shapes.get(receiver.present.shapeId);
+            const index = expr.argumentExpression.text;
+            const field = shape?.tuple ? shape.fields.find((candidate) => candidate.name === String(Number(index))) : undefined;
+            if (field) {
+                const read = {
+                    kind: "recordGet",
+                    obj: receiverValue,
+                    shapeId: receiver.present.shapeId,
+                    field: field.name,
+                    type: field.type,
+                    loc: locOf(expr),
+                };
+                if (expr.parent && ts.isTypeOfExpression(expr.parent) &&
+                    (field.type.kind === "f64" || field.type.kind === "bool" || field.type.kind === "string")) {
+                    return { kind: "dynFrom", value: read, type: DYN, loc: locOf(expr) };
+                }
+                return read;
+            }
+        }
+        const key = this.runtimeOptionalIdentifierValue(expr.argumentExpression);
+        const keyValue = key?.present.kind === "string" ? this.ensureString(key.value, expr.argumentExpression) : null;
+        const lower = () => lowerElementAccess(this, expr);
+        const withKey = () => keyValue ? this.withExpressionOverride(expr.argumentExpression, keyValue, lower) : lower();
+        return receiverValue ? this.withExpressionOverride(expr.expression, receiverValue, withKey) : withKey();
     }
     lowerRecordKeyRead(expr, shapeId, shape, includeUndefined = false) {
         return lowerRecordKeyRead(this, expr, shapeId, shape, includeUndefined);
@@ -7694,7 +8769,84 @@ export class Lowerer {
         return caughtToString(this, node);
     }
     lowerInstanceOf(expr, loc) {
-        return lowerInstanceOf(this, expr, loc);
+        const lower = () => this.withRuntimeOptionalClassValue(expr.right, () => lowerInstanceOf(this, expr, loc));
+        if (!ts.isIdentifier(expr.right) || this.mapTypeOf(this.typeOf(expr.right))?.kind !== "classval") {
+            return lower();
+        }
+        const optionalLeft = this.runtimeOptionalIdentifierValue(expr.left);
+        const left = optionalLeft?.value ?? (ts.isElementAccessExpression(expr.left) ? this.lowerExpr(expr.left) : null);
+        if (!left)
+            return lower();
+        if (left.type.kind !== "union" || this.armTag(left.type.unionId, UNDEFINED_T) < 0)
+            return lower();
+        const present = this.stripUndefinedArm(left.type);
+        if (present.kind !== "object")
+            return lower();
+        const undefinedTag = this.armTag(left.type.unionId, UNDEFINED_T);
+        const valueTag = this.armTag(left.type.unionId, present);
+        if (undefinedTag < 0 || valueTag < 0)
+            return lower();
+        const stable = this.declareHiddenLocal("%instanceofLeft", left.type);
+        const value = varRef(stable.id, left.type, locOf(expr.left));
+        const optionalRight = this.runtimeOptionalIdentifierValue(expr.right);
+        let right;
+        if (optionalRight?.present.kind === "classval") {
+            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) };
+        }
+        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));
+        const body = this.withExpressionOverride(expr.left, {
+            kind: "unionNarrow", unionId: left.type.unionId, tag: valueTag, value, type: present, loc: locOf(expr.left),
+        }, () => this.withExpressionOverride(expr.right, rightValue, () => lowerInstanceOf(this, expr, loc)));
+        return {
+            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) },
+            ],
+            result: {
+                kind: "ternary",
+                cond: { kind: "unionIsTag", unionId: left.type.unionId, tag: undefinedTag, negated: false, value, type: BOOL, loc },
+                then: { kind: "boolLit", value: false, type: BOOL, loc },
+                else_: body,
+                type: BOOL,
+                loc,
+            },
+            type: BOOL,
+            loc,
+        };
+    }
+    withRuntimeOptionalClassValue(node, lower) {
+        if (this.mapTypeOf(this.typeOf(node))?.kind !== "classval")
+            return lower();
+        const optional = this.runtimeOptionalIdentifierValue(node);
+        if (optional?.present.kind !== "classval")
+            return lower();
+        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);
+    }
+    withExpressionOverride(node, value, lower) {
+        const previous = this.chainRecvByNode.get(node);
+        this.chainRecvByNode.set(node, value);
+        try {
+            return lower();
+        }
+        finally {
+            if (previous)
+                this.chainRecvByNode.set(node, previous);
+            else
+                this.chainRecvByNode.delete(node);
+        }
     }
     lowerCall(expr) {
         // Ambient fetch (native in static builds, island-backed under
@@ -7834,7 +8986,8 @@ export class Lowerer {
             const arg = this.lowerExpr(expr.arguments[0]);
             return { kind: "jsOp", op: "construct", args: [ctor, arg], type: JSVAL, loc };
         }
-        return lowerAbortControllerNew(this, expr) ?? lowerResponseNew(this, expr) ?? lowerStaticReadableStreamNew(this, expr) ?? lowerNew(this, expr);
+        const builtin = lowerAbortControllerNew(this, expr) ?? lowerResponseNew(this, expr) ?? lowerStaticReadableStreamNew(this, expr);
+        return builtin ?? this.withRuntimeOptionalClassValue(expr.expression, () => lowerNew(this, expr));
     }
     lowerFieldRead(expr) {
         // `C.x` static reads first (the receiver is a CLASS, not an instance
@@ -8132,6 +9285,9 @@ export class Lowerer {
     lowerBuiltinModuleCall(expr, bi, fn, loc) {
         return lowerBuiltinModuleCall(this, expr, bi, fn, loc);
     }
+    lowerTimersPromisesSetInterval(expr, bi, loc) {
+        return lowerTimersPromisesSetInterval(this, expr, bi, loc);
+    }
     lowerFsToUnixTimestampCall(expr, bi, loc) {
         return lowerFsToUnixTimestampCall(this, expr, bi, loc);
     }
@@ -8323,6 +9479,13 @@ export class Lowerer {
         return lowerStringLastIndexOfCall(this, call, access);
     }
     lowerFilterNarrowCall(call, access) {
+        // Native array filters use the state-aware HOF helper: its callback
+        // receives present undefined values and skips holes before a narrowed
+        // survivor is extracted. The older narrowing helper reads the payload
+        // directly and therefore cannot represent that three-state contract.
+        if (this.mapTypeOf(this.typeOf(access.expression))?.kind === "array" && this.isStdlibMember(access)) {
+            return null;
+        }
         return lowerFilterNarrowCall(this, call, access);
     }
     lowerPromiseMethodCall(call, access) {