@scriptc/compiler 0.0.35 → 0.1.1

package/dist/frontend/lowering/lowerer.js

@@ -1,3 +1,4 @@
+import { InternalCompilerError } from "../../errors.js";
 /* AST + checker → IR.
  *
  * Invariants:
@@ -13,13 +14,14 @@
  *   ("x.0", "x.1" for shadowing); the IR is scope-flat.
  */
 import { resolve } from "node:path";
-import { isRelativeSpecifier, tsgoPath } from "../shared.js";
+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/nodes.js";
+import { arrayOf, BOOL, canAdaptDynFuncTo, canConvertToDyn, canCrossIslandBoundary, canExitIslandToType, canMarshalTypedFuncIntoIsland, DYN, F64, isJsonSafeType, isJsonStringifySafeType, isUndefinedArmedUnion, isUnitType, JSVAL, 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 "../types.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 { 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";
@@ -27,7 +29,7 @@ import { mixinCallClassInfoOf, mixinIntersectionInstanceType } from "./lower-mix
 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 { lowerStreamModuleCall } from "./lower-stream.js";
-import { lowerEmitOverrideSpec } from "./lower-emitter.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 { 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";
@@ -40,6 +42,7 @@ import { lowerStmts, noteBlockedBindings, isBlockedBinding, lowerScopedBlock, pr
 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 { lowerRecordFieldCall, lowerObjectMethodCall } from "./lower-calls.js";
 import { fenceCrossBlockNsRef, nsPathPrefix } from "./lower-namespaces.js";
+import { numLit, varRef } from "../../ir/build.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";
@@ -56,7 +59,7 @@ export function own(table, key) {
 /** Sentinel binding key for `this` (which has no ts.Symbol): a stable
  * object identity used in the same scope/capture maps as real symbols, so
  * arrows capturing `this` ride the ordinary capture machinery. */
-export const THIS_BINDING = { escapedName: "%this" };
+const THIS_BINDING = { escapedName: "%this" };
 export function newFnCtx(lifted, selfSymbol, selfType, returnType) {
     return {
         locals: [],
@@ -76,9 +79,9 @@ export function newFnCtx(lifted, selfSymbol, selfType, returnType) {
  * visit; descending would attribute a nested island statement to every
  * enclosing construct too). The top-level statement object itself is
  * always visited. */
-export const IR_STMT_KINDS = new Set([
+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
@@ -308,8 +311,8 @@ export function importCallHandleType(expr) {
  * Ambient (.d.ts) declarations never reach this: they have no compiled
  * implementation, so their calls lower through the island/builtin paths
  * whose validated exits keep the checker-trust trap. */
-export function uncheckedOverloadHandleCall(L, expr) {
-    if (!L.dynamic || !expr)
+export function uncheckedOverloadHandleCall(lowerer, expr) {
+    if (!lowerer.dynamic || !expr)
         return false;
     let e = expr;
     while (ts.isParenthesizedExpression(e))
@@ -319,25 +322,25 @@ export function uncheckedOverloadHandleCall(L, expr) {
     // overload of an any-returning implementation stores the handle.
     if (!ts.isCallExpression(e) && !ts.isTaggedTemplateExpression(e))
         return false;
-    const rsig = L.checker.getResolvedSignature(e);
-    const rdecl = rsig ? L.checker.signatureDeclaration(rsig) : undefined;
+    const rsig = lowerer.checker.getResolvedSignature(e);
+    const rdecl = rsig ? lowerer.checker.signatureDeclaration(rsig) : undefined;
     if (!rsig || !rdecl)
         return false;
     if (!(ts.isFunctionDeclaration(rdecl) || ts.isMethodDeclaration(rdecl)) || rdecl.body)
         return false;
     const name = rdecl.name;
-    const symbol = name ? L.checker.getSymbolAtLocation(name) : undefined;
+    const symbol = name ? lowerer.checker.getSymbolAtLocation(name) : undefined;
     if (!symbol)
         return false;
-    const impl = L.checker
+    const impl = lowerer.checker
         .declarationsOf(symbol)
         .find((d) => (ts.isFunctionDeclaration(d) || ts.isMethodDeclaration(d)) && d.body !== undefined);
     if (!impl)
         return false;
-    const implSig = L.checker.getSignatureFromDeclaration(impl);
+    const implSig = lowerer.checker.getSignatureFromDeclaration(impl);
     if (!implSig)
         return false;
-    return L.mapTypeOf(L.checker.getReturnTypeOfSignature(implSig))?.kind === "jsval";
+    return lowerer.mapTypeOf(lowerer.checker.getReturnTypeOfSignature(implSig))?.kind === "jsval";
 }
 /** The JavaScript declaration fallback for unmappable binding types (see
  * irTypeOf): `any` and every other inference residue is the checked-
@@ -356,7 +359,7 @@ export function uncheckedOverloadHandleCall(L, expr) {
  * checked-dynamic fallbacks apply, the pre-never-mapping behavior. Bare
  * `never` at the ROOT stays out (`for (const v of [])`'s loop var — the
  * dead read the f64 mapping is FOR). */
-export function neverTaintedJsType(L, node, t) {
+export function neverTaintedJsType(lowerer, node, t) {
     if (!isJsSourceFile(node.getSourceFile()))
         return false;
     const walk = (x, depth) => {
@@ -364,8 +367,8 @@ export function neverTaintedJsType(L, node, t) {
             return false;
         if (x.isUnionType())
             return ts.constituentTypes(x).some((a) => walk(a, depth - 1));
-        if (L.checker.isArrayType(x) || L.checker.isTupleType(x)) {
-            return L.checker
+        if (lowerer.checker.isArrayType(x) || lowerer.checker.isTupleType(x)) {
+            return lowerer.checker
                 .getTypeArguments(x)
                 .some((a) => (a.flags & ts.TypeFlags.Never) !== 0 || walk(a, depth - 1));
         }
@@ -414,10 +417,10 @@ export function nodeThrowExpr(kind, code, message, type, loc) {
  * (scr_throw_lowering_fence). The diagnostic joins the runtime-fence
  * ledger exactly like a deferred statement fence — nothing silently
  * drops off the coverage report. */
-export function ladderFenceExpr(L, surface, node, hint) {
+export function ladderFenceExpr(lowerer, surface, node, hint) {
     const loc = locOf(node);
     const d = noLoweringDiag(surface, loc, hint);
-    L.runtimeFences.push(d);
+    lowerer.runtimeFences.push(d);
     const sf = node.getSourceFile();
     const pos = ts.getLineAndCharacterOfPosition(sf, loc.start);
     return {
@@ -450,7 +453,7 @@ export function ladderFenceExpr(L, surface, node, hint) {
  * this fallback for `any` (mapType answers jsval first).
  *
  * Null for void (no value exists to represent). */
-export function dynFallbackType(L, node, t) {
+export function dynFallbackType(lowerer, node, t) {
     if (t.flags & ts.TypeFlags.Void)
         return null;
     if (!isJsSourceFile(node.getSourceFile())) {
@@ -459,13 +462,13 @@ export function dynFallbackType(L, node, t) {
         // TS single-call-signature function types: per-piece fallback, but
         // ONLY `any` pieces fall to dyn — any other unmappable piece keeps
         // the whole type's own fence.
-        return anyPiecedFuncType(L, node, t);
+        return anyPiecedFuncType(lowerer, node, t);
     }
-    if (L.checker.isArrayType(t)) {
-        const elem = L.checker.getTypeArguments(t)[0];
+    if (lowerer.checker.isArrayType(t)) {
+        const elem = lowerer.checker.getTypeArguments(t)[0];
         const elemTainted = elem !== undefined &&
-            ((elem.flags & ts.TypeFlags.Never) !== 0 || neverTaintedJsType(L, node, elem));
-        const mappedElem = elem !== undefined && !elemTainted ? L.mapTypeOf(elem) : null;
+            ((elem.flags & ts.TypeFlags.Never) !== 0 || neverTaintedJsType(lowerer, node, elem));
+        const mappedElem = elem !== undefined && !elemTainted ? lowerer.mapTypeOf(elem) : null;
         // A mappable element keeps the static array; an unmappable one makes
         // the WHOLE value dyn (the checked-dynamic tree has real arrays — length/index/push
         // read through the keyed-dyn paths; dyn-element STATIC arrays have no
@@ -482,14 +485,14 @@ export function dynFallbackType(L, 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(L, t);
+    const sig = pureSingleCallSignatureOf(lowerer, t);
     if (sig) {
         const params = sig.getParameters().map((p) => {
-            const pt = L.checker.getTypeOfSymbolAtLocation(p, node);
-            return L.mapTypeOf(pt) ?? DYN;
+            const pt = lowerer.checker.getTypeOfSymbolAtLocation(p, node);
+            return lowerer.mapTypeOf(pt) ?? DYN;
         });
-        const retT = L.checker.getReturnTypeOfSignature(sig);
-        const ret = retT.flags & ts.TypeFlags.Void ? VOID : L.mapTypeOf(retT) ?? DYN;
+        const retT = lowerer.checker.getReturnTypeOfSignature(sig);
+        const ret = retT.flags & ts.TypeFlags.Void ? VOID : lowerer.mapTypeOf(retT) ?? DYN;
         return { kind: "func", params, ret };
     }
     return DYN;
@@ -498,23 +501,23 @@ export function dynFallbackType(L, node, t) {
  * properties, no construct signatures, no type parameters, no rest params
  * (declared or synthesized from an `arguments` read). Null for every
  * other shape. The structural gate both dynFallbackType arms share. */
-function pureSingleCallSignatureOf(L, t) {
+function pureSingleCallSignatureOf(lowerer, t) {
     if (!(t.flags & ts.TypeFlags.Object))
         return null;
-    const sigs = L.checker.getCallSignatures(t);
+    const sigs = lowerer.checker.getCallSignatures(t);
     if (sigs.length === 1 &&
-        L.checker.getPropertiesOfType(t).length === 0 &&
-        L.checker.getConstructSignatures(t).length === 0 &&
+        lowerer.checker.getPropertiesOfType(t).length === 0 &&
+        lowerer.checker.getConstructSignatures(t).length === 0 &&
         sigs[0].getTypeParameters().length === 0 &&
         sigs[0].getParameters().every((p) => {
-            const pDecl = L.checker.valueDeclarationOf(p);
+            const pDecl = lowerer.checker.valueDeclarationOf(p);
             return !pDecl || !ts.isParameter(pDecl) || pDecl.dotDotDotToken === undefined;
         }) &&
         // A SYNTHESIZED rest param (tsc's `arguments` inference — no
         // valueDeclaration to carry the dotDotDot): param-count mismatch
         // against the signature's declaration; the whole value stays dyn.
         (() => {
-            const sigDecl = L.checker.signatureDeclaration(sigs[0]);
+            const sigDecl = lowerer.checker.signatureDeclaration(sigs[0]);
             const declParams = sigDecl !== undefined && ts.isFunctionLike(sigDecl) ? sigDecl.parameters : undefined;
             if (declParams !== undefined && declParams.length !== sigs[0].getParameters().length)
                 return false;
@@ -534,21 +537,21 @@ function pureSingleCallSignatureOf(L, t) {
  * irTypeOf fallback, so the binding type and the closure type agree).
  * A piece that fails to map for any other reason answers null — the
  * whole type keeps its own diagnostic. */
-function anyPiecedFuncType(L, node, t) {
-    const sig = pureSingleCallSignatureOf(L, t);
+function anyPiecedFuncType(lowerer, node, t) {
+    const sig = pureSingleCallSignatureOf(lowerer, t);
     if (!sig)
         return null;
     const params = [];
     for (const p of sig.getParameters()) {
-        const pt = L.checker.getTypeOfSymbolAtLocation(p, node);
-        const mapped = L.mapTypeOf(pt) ?? (pt.flags & ts.TypeFlags.Any ? DYN : null);
+        const pt = lowerer.checker.getTypeOfSymbolAtLocation(p, node);
+        const mapped = lowerer.mapTypeOf(pt) ?? (pt.flags & ts.TypeFlags.Any ? DYN : null);
         if (!mapped || mapped.kind === "void")
             return null;
         params.push(mapped);
     }
-    const retT = L.checker.getReturnTypeOfSignature(sig);
+    const retT = lowerer.checker.getReturnTypeOfSignature(sig);
     const ret = retT.flags & (ts.TypeFlags.Void | ts.TypeFlags.Never) ? VOID
-        : L.mapTypeOf(retT) ?? (retT.flags & ts.TypeFlags.Any ? DYN : null);
+        : lowerer.mapTypeOf(retT) ?? (retT.flags & ts.TypeFlags.Any ? DYN : null);
     if (!ret)
         return null;
     return { kind: "func", params, ret };
@@ -818,12 +821,233 @@ 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. Stabilize the 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 stable = this.declareHiddenLocal("%propertyRecv", source.type);
+        const stableRef = () => 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,
+            };
+        }
+        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) {
@@ -863,7 +1087,7 @@ export class Lowerer {
      * Reachability lowers inits before the declarations they discover, so
      * these rebuild after the worklist restores historical shape metadata. */
     shapeOrderHelperFinalizers = [];
-    /** Emit-override specializations (`%C.emit:<event>` — lower-emitter.ts's
+    /** Emit-override specializations (`%C.emit:<event>` — lower-event-emitter.ts's
      * emit-overrides block): interned names, the drive-loop queue, and the
      * currently-lowering specialization's context (the super-forward
      * interception reads it). */
@@ -917,6 +1141,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. */
@@ -1130,7 +1358,7 @@ export class Lowerer {
     get ctx() {
         const top = this.fnStack[this.fnStack.length - 1];
         if (!top)
-            throw new Error("lowerer bug: no active function context");
+            throw new InternalCompilerError("lowerer bug: no active function context");
         return top;
     }
     get scopes() {
@@ -1377,6 +1605,31 @@ export class Lowerer {
         this.flushDeferred(symbol);
         return symbol;
     }
+    /** Whether this exact direct call belongs to a manifest-validated native
+     * binding. Declaration classification uses this as a probe before normal
+     * expression lowering: resolving must not flush deferred diagnostics or
+     * trigger the merged-namespace fence just because it is asking ownership.
+     * Call lowering remains the authority for every ABI and call-shape
+     * diagnostic once this answers true. */
+    ownsFfiCall(expr) {
+        if (!ts.isIdentifier(expr.expression))
+            return false;
+        const binding = this.ffiImportsByName.get(expr.expression.text);
+        if (binding === undefined || this.ffiBindingSymbols === null)
+            return false;
+        const validSymbols = this.ffiBindingSymbols.get(binding.name);
+        if (validSymbols === undefined)
+            return false;
+        const wasCollecting = this.collecting;
+        this.collecting = true;
+        try {
+            const symbol = this.resolveValueSymbol(expr.expression);
+            return symbol !== null && validSymbols.has(symbol);
+        }
+        finally {
+            this.collecting = wasCollecting;
+        }
+    }
     /** The configured external host module owning an expression's runtime
      * value, or null. Alias chains are followed to their declaration file so
      * direct imports and local re-export facades classify identically. Type
@@ -1983,6 +2236,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
@@ -1996,6 +2963,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
@@ -2224,7 +3192,7 @@ export class Lowerer {
         const module = this.diags.length > 0
             ? null
             : {
-                irVersion: 6,
+                irVersion: 8,
                 sourceFile: this.entry.fileName,
                 functions,
                 classes: artifacts.classes,
@@ -2367,6 +3335,7 @@ 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.
@@ -2710,7 +3679,61 @@ export class Lowerer {
     moduleArtifacts(functions) {
         return moduleArtifacts(this, functions);
     }
-    /* ── diagnostics plumbing ─────────────────────────────────────────── */
+    deferToRuntimeFence(diagsBefore, node, target) {
+        if ((this.diagSink !== null && target.allowDiagSink !== true) ||
+            (this.diags.length <= diagsBefore && target.fallback === undefined)) {
+            return null;
+        }
+        const captured = this.diags.splice(diagsBefore);
+        if (captured.some((d) => d.code === "SC9001")) {
+            this.diags.push(...captured);
+            return null;
+        }
+        this.runtimeFences.push(...captured);
+        const first = captured[0];
+        const loc = locOf(node);
+        const code = first?.code ?? target.fallback.code;
+        const baseMessage = first?.message ?? target.fallback.message;
+        const messageLoc = first?.loc ?? loc;
+        const source = first
+            ? this.program.getSourceFile(messageLoc.file) ?? node.getSourceFile()
+            : node.getSourceFile();
+        const pos = ts.getLineAndCharacterOfPosition(source, messageLoc.start);
+        const fence = {
+            kind: "runtimeFence",
+            code,
+            message: target.bareMessage
+                ? baseMessage
+                : `${baseMessage} [${code} at ${messageLoc.file}:${pos.line + 1}]`,
+            loc,
+        };
+        if (target.kind === "statement")
+            return fence;
+        const params = target.params ?? [];
+        const name = typeof target.name === "function" ? target.name() : target.name;
+        const fn = {
+            name,
+            params,
+            returnType: target.returnType,
+            locals: params.map((p) => ({
+                id: p.localId,
+                name: p.name,
+                type: p.type,
+                mutable: target.paramsMutable ?? false,
+            })),
+            body: [fence],
+            loc,
+        };
+        if (target.async)
+            fn.async = true;
+        if (target.generator)
+            fn.generator = target.generator;
+        if (target.kind === "function")
+            return fn;
+        fn.captures = [];
+        this.liftedFns.push(fn);
+        return { kind: "closure", fnName: fn.name, captures: [], type: target.type, loc };
+    }
     /** All diagnostics land here; while a generic instance body is lowering,
      * the instantiation context is appended so the user knows which concrete
      * types made the (source-anchored) construct fail. */
@@ -3112,11 +4135,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
@@ -3316,7 +4342,7 @@ export class Lowerer {
     /** Unwraps a HYBRID (function-with-properties) record to its callable:
      * a record whose shape carries the reserved `%call` func field reads
      * that field; anything else returns unchanged. The consumer half of
-     * types.ts's chalk-shape mapping — call paths and func-slot coercions
+     * type-mapper.ts's chalk-shape mapping — call paths and func-slot coercions
      * share it. */
     hybridCallUnwrap(expr) {
         if (expr.type.kind !== "record")
@@ -3499,7 +4525,7 @@ export class Lowerer {
         }
         // A HYBRID (function-with-properties) record flowing into a plain
         // func slot extracts its reserved %call field — the chalk shape's
-        // "the value IS callable" half (types.ts's hybrid mapping).
+        // "the value IS callable" half (type-mapper.ts's hybrid mapping).
         if (expected.kind === "func" && expr.type.kind === "record") {
             const un = this.hybridCallUnwrap(expr);
             if (un !== expr && typeEquals(un.type, expected))
@@ -3954,102 +4980,102 @@ export class Lowerer {
                 return value;
             case "wrap": {
                 if (dst.kind !== "union")
-                    throw new Error("lowerer bug: wrap lift against a non-union");
+                    throw new InternalCompilerError("lowerer bug: wrap lift against a non-union");
                 return { kind: "unionWrap", unionId: dst.unionId, tag: lift.tag, value, type: dst, loc };
             }
             case "retag": {
                 if (dst.kind !== "union" || value.type.kind !== "union")
-                    throw new Error("lowerer bug: retag lift shape");
+                    throw new InternalCompilerError("lowerer bug: retag lift shape");
                 const retag = this.unionRetagHelper(value.type.unionId, dst.unionId, loc);
                 if (!retag)
-                    throw new Error("lowerer bug: planned retag lift failed to intern");
+                    throw new InternalCompilerError("lowerer bug: planned retag lift failed to intern");
                 return { kind: "call", callee: retag, args: [value], type: dst, loc };
             }
             case "liftWrap": {
                 if (dst.kind !== "union")
-                    throw new Error("lowerer bug: liftWrap lift against a non-union");
+                    throw new InternalCompilerError("lowerer bug: liftWrap lift against a non-union");
                 const inner = this.widthLiftPlan(value.type, lift.arm);
                 if (!inner)
-                    throw new Error("lowerer bug: planned liftWrap arm stopped lifting");
+                    throw new InternalCompilerError("lowerer bug: planned liftWrap arm stopped lifting");
                 const lifted = this.applyWidthLift(inner, value, lift.arm, loc);
                 return { kind: "unionWrap", unionId: dst.unionId, tag: lift.tag, value: lifted, type: dst, loc };
             }
             case "width": {
                 if (dst.kind !== "record" || value.type.kind !== "record")
-                    throw new Error("lowerer bug: width lift shape");
+                    throw new InternalCompilerError("lowerer bug: width lift shape");
                 const helper = this.recordWidthHelper(value.type.shapeId, dst.shapeId, loc);
                 if (!helper)
-                    throw new Error("lowerer bug: planned width lift failed to intern");
+                    throw new InternalCompilerError("lowerer bug: planned width lift failed to intern");
                 return { kind: "call", callee: helper, args: [value], type: dst, loc };
             }
             case "arr": {
                 if (dst.kind !== "array" || value.type.kind !== "array")
-                    throw new Error("lowerer bug: arr lift shape");
+                    throw new InternalCompilerError("lowerer bug: arr lift shape");
                 const helper = this.arrayWidthHelper(value.type, dst, loc);
                 if (!helper)
-                    throw new Error("lowerer bug: planned arr lift failed to intern");
+                    throw new InternalCompilerError("lowerer bug: planned arr lift failed to intern");
                 return { kind: "call", callee: helper, args: [value], type: dst, loc };
             }
             case "tupleArr": {
                 if (dst.kind !== "array" || value.type.kind !== "record")
-                    throw new Error("lowerer bug: tupleArr lift shape");
+                    throw new InternalCompilerError("lowerer bug: tupleArr lift shape");
                 const helper = this.tupleArrayWidthHelper(value.type.shapeId, dst, loc);
                 if (!helper)
-                    throw new Error("lowerer bug: planned tupleArr lift failed to intern");
+                    throw new InternalCompilerError("lowerer bug: planned tupleArr lift failed to intern");
                 return { kind: "call", callee: helper, args: [value], type: dst, loc };
             }
             case "emptyArr": {
                 if (dst.kind !== "array" || value.type.kind !== "array")
-                    throw new Error("lowerer bug: emptyArr lift shape");
+                    throw new InternalCompilerError("lowerer bug: emptyArr lift shape");
                 const helper = this.emptyArrayLiftHelper(value.type, dst, loc);
                 return { kind: "call", callee: helper, args: [value], type: dst, loc };
             }
             case "objWidth": {
                 if (dst.kind !== "record" || value.type.kind !== "object")
-                    throw new Error("lowerer bug: objWidth lift shape");
+                    throw new InternalCompilerError("lowerer bug: objWidth lift shape");
                 const helper = this.objRecordWidthHelper(value.type.className, dst.shapeId, loc);
                 if (!helper)
-                    throw new Error("lowerer bug: planned objWidth lift failed to intern");
+                    throw new InternalCompilerError("lowerer bug: planned objWidth lift failed to intern");
                 return { kind: "call", callee: helper, args: [value], type: dst, loc };
             }
             case "clsWidth": {
                 if (dst.kind !== "object" || value.type.kind !== "record")
-                    throw new Error("lowerer bug: clsWidth lift shape");
+                    throw new InternalCompilerError("lowerer bug: clsWidth lift shape");
                 const helper = this.recordClassWidthHelper(value.type.shapeId, dst.className, loc);
                 if (!helper)
-                    throw new Error("lowerer bug: planned clsWidth lift failed to intern");
+                    throw new InternalCompilerError("lowerer bug: planned clsWidth lift failed to intern");
                 return { kind: "call", callee: helper, args: [value], type: dst, loc };
             }
             case "narrow": {
                 if (value.type.kind !== "union")
-                    throw new Error("lowerer bug: narrow lift on a non-union");
+                    throw new InternalCompilerError("lowerer bug: narrow lift on a non-union");
                 const helper = this.narrowedArmHelper(value.type.unionId, dst, loc);
                 if (!helper)
-                    throw new Error("lowerer bug: planned narrow lift failed to intern");
+                    throw new InternalCompilerError("lowerer bug: planned narrow lift failed to intern");
                 return { kind: "call", callee: helper, args: [value], type: dst, loc };
             }
             case "dynIn": {
                 if (dst.kind !== "dyn")
-                    throw new Error("lowerer bug: dynIn lift against a non-dyn slot");
+                    throw new InternalCompilerError("lowerer bug: dynIn lift against a non-dyn slot");
                 return { kind: "dynFrom", value, type: DYN, loc };
             }
             case "upcast": {
                 if (dst.kind !== "object" || value.type.kind !== "object")
-                    throw new Error("lowerer bug: upcast lift shape");
+                    throw new InternalCompilerError("lowerer bug: upcast lift shape");
                 return this.upcastTo(value, dst.className);
             }
             case "funcAdapt": {
                 if (dst.kind !== "func" || value.type.kind !== "func")
-                    throw new Error("lowerer bug: funcAdapt lift shape");
+                    throw new InternalCompilerError("lowerer bug: funcAdapt lift shape");
                 const adapter = this.funcCoerceAdapter(value.type, dst, loc);
                 if (!adapter)
-                    throw new Error("lowerer bug: planned funcAdapt lift failed to intern");
+                    throw new InternalCompilerError("lowerer bug: planned funcAdapt lift failed to intern");
                 return { kind: "call", callee: adapter, args: [value], type: dst, loc };
             }
             default: {
                 const _exhaustive = lift;
                 void _exhaustive;
-                throw new Error("unreachable");
+                throw new InternalCompilerError("unreachable");
             }
         }
     }
@@ -4264,7 +5290,7 @@ export class Lowerer {
                             }
                             if ("absent" in lift) {
                                 if (f.type.kind !== "union")
-                                    throw new Error("lowerer bug: absent lift against a non-union field");
+                                    throw new InternalCompilerError("lowerer bug: absent lift against a non-union field");
                                 // The unset optional field: build the undefined arm.
                                 return {
                                     name: f.name,
@@ -4406,8 +5432,6 @@ export class Lowerer {
         this.widthHelpers.set(key, name);
         const arrT = { kind: "array", elem: fromElem };
         const outT = { kind: "array", elem: toElem };
-        const ref = (localId, type) => ({ kind: "varRef", localId, type, loc });
-        const num = (value) => ({ kind: "numLit", value, type: { kind: "f64" }, loc });
         const f64 = { kind: "f64" };
         this.liftedFns.push({
             name,
@@ -4424,17 +5448,17 @@ export class Lowerer {
                 {
                     kind: "varDecl",
                     localId: "n.0",
-                    init: { kind: "arrIntrinsic", method: "length", receiver: ref("a.0", arrT), args: [], type: f64, loc },
+                    init: { kind: "arrIntrinsic", method: "length", receiver: varRef("a.0", arrT, loc), args: [], type: f64, loc },
                     loc,
                 },
                 {
                     kind: "for",
-                    init: { kind: "varDecl", localId: "i.0", init: num(0), loc },
-                    cond: { kind: "bin", op: "<", left: ref("i.0", f64), right: ref("n.0", f64), type: BOOL, loc },
+                    init: { kind: "varDecl", localId: "i.0", init: numLit(0, loc), loc },
+                    cond: { kind: "bin", op: "<", left: varRef("i.0", f64, loc), right: varRef("n.0", f64, loc), type: BOOL, loc },
                     update: {
                         kind: "assign",
                         localId: "i.0",
-                        value: { kind: "bin", op: "+", left: ref("i.0", f64), right: num(1), type: f64, loc },
+                        value: { kind: "bin", op: "+", left: varRef("i.0", f64, loc), right: numLit(1, loc), type: f64, loc },
                         loc,
                     },
                     body: [
@@ -4443,9 +5467,9 @@ export class Lowerer {
                             expr: {
                                 kind: "arrIntrinsic",
                                 method: "push",
-                                receiver: ref("out.0", outT),
+                                receiver: varRef("out.0", outT, loc),
                                 args: [
-                                    this.applyWidthLift(elemLift, { kind: "arrayGet", arr: ref("a.0", arrT), index: ref("i.0", f64), type: fromElem, loc }, toElem, loc),
+                                    this.applyWidthLift(elemLift, { kind: "arrayGet", arr: varRef("a.0", arrT, loc), index: varRef("i.0", f64, loc), type: fromElem, loc }, toElem, loc),
                                 ],
                                 type: f64,
                                 loc,
@@ -4455,7 +5479,7 @@ export class Lowerer {
                     ],
                     loc,
                 },
-                { kind: "return", value: ref("out.0", outT), loc },
+                { kind: "return", value: varRef("out.0", outT, loc), loc },
             ],
             loc,
         });
@@ -4554,7 +5578,7 @@ export class Lowerer {
                             const lift = plan.get(f.name);
                             if ("absent" in lift) {
                                 if (f.type.kind !== "union")
-                                    throw new Error("lowerer bug: absent lift against a non-union field");
+                                    throw new InternalCompilerError("lowerer bug: absent lift against a non-union field");
                                 return {
                                     name: f.name,
                                     value: {
@@ -4683,7 +5707,7 @@ export class Lowerer {
             if ("absent" in entry) {
                 const u = this.wrappedUndefined(shape.type, loc);
                 if (!u)
-                    throw new Error("lowerer bug: planned absent ctor arg has no undefined arm");
+                    throw new InternalCompilerError("lowerer bug: planned absent ctor arg has no undefined arm");
                 return u;
             }
             const get = { kind: "recordGet", obj: r, shapeId: fromId, field: entry.field, type: entry.src, loc };
@@ -4986,7 +6010,7 @@ export class Lowerer {
                 const aRef = { kind: "varRef", localId: `a.${i}`, type: toT.params[i], loc };
                 const converted = this.coerceToExpected(aRef, pt);
                 if (!typeEquals(converted.type, pt))
-                    throw new Error("lowerer bug: probed fn-adapter param stopped coercing");
+                    throw new InternalCompilerError("lowerer bug: probed fn-adapter param stopped coercing");
                 return converted;
             });
             const call = {
@@ -5029,7 +6053,7 @@ export class Lowerer {
             else {
                 const result = this.coerceToExpected(call, toT.ret);
                 if (!typeEquals(result.type, toT.ret))
-                    throw new Error("lowerer bug: probed fn-adapter return stopped coercing");
+                    throw new InternalCompilerError("lowerer bug: probed fn-adapter return stopped coercing");
                 body = [{ kind: "return", value: result, loc }];
             }
         }
@@ -5519,10 +6543,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 = [];
@@ -5720,7 +6747,7 @@ export class Lowerer {
         if (e.type.kind === "dyn" || e.type.kind === "func") {
             return { kind: "jsMarshal", value: e, type: JSVAL, loc };
         }
-        throw new Error(`lowerer bug: jsvalLiftExpr of unliftable ${e.type.kind}`);
+        throw new InternalCompilerError(`lowerer bug: jsvalLiftExpr of unliftable ${e.type.kind}`);
     }
     /** Interned `%jsin.union.<n>(u)` — the runtime tag switch marshaling a
      * union value INTO the island: unit arms become the engine's own
@@ -5737,7 +6764,7 @@ export class Lowerer {
             return existing;
         const def = this.unions.get(unionId);
         if (!def)
-            throw new Error(`lowerer bug: jsval lift of unknown union ${unionId}`);
+            throw new InternalCompilerError(`lowerer bug: jsval lift of unknown union ${unionId}`);
         const name = `%jsin.union.${this.jsinHelpers.size}`;
         this.jsinHelpers.set(key, name);
         const fromT = { kind: "union", unionId };
@@ -5779,7 +6806,7 @@ export class Lowerer {
             return existing;
         const shape = this.shapes.get(shapeId);
         if (!shape)
-            throw new Error(`lowerer bug: jsval lift of unknown shape ${shapeId}`);
+            throw new InternalCompilerError(`lowerer bug: jsval lift of unknown shape ${shapeId}`);
         const name = `%jsin.rec.${this.jsinHelpers.size}`;
         this.jsinHelpers.set(key, name);
         const recT = { kind: "record", shapeId };
@@ -5812,9 +6839,7 @@ export class Lowerer {
         const iv = shape.indexValue;
         const f64 = { kind: "f64" };
         const ksT = arrayOf(STRING);
-        const ref = (localId, type) => ({ kind: "varRef", localId, type, loc });
-        const num = (value) => ({ kind: "numLit", value, type: f64, loc });
-        const kRef = ref("k.0", STRING);
+        const kRef = varRef("k.0", STRING, loc);
         this.liftedFns.push({
             name,
             params: [{ localId: "r.0", name: "r", type: recT }],
@@ -5831,25 +6856,25 @@ export class Lowerer {
                 { kind: "varDecl", localId: "ks.0", init: { kind: "recordOvfKeys", obj: r, shapeId, type: ksT, loc }, loc },
                 {
                     kind: "for",
-                    init: { kind: "varDecl", localId: "i.0", init: num(0), loc },
+                    init: { kind: "varDecl", localId: "i.0", init: numLit(0, loc), loc },
                     cond: {
                         kind: "bin",
                         op: "<",
-                        left: ref("i.0", f64),
-                        right: { kind: "arrIntrinsic", method: "length", receiver: ref("ks.0", ksT), args: [], type: f64, loc },
+                        left: varRef("i.0", f64, loc),
+                        right: { kind: "arrIntrinsic", method: "length", receiver: varRef("ks.0", ksT, loc), args: [], type: f64, loc },
                         type: BOOL,
                         loc,
                     },
-                    update: { kind: "assign", localId: "i.0", value: { kind: "bin", op: "+", left: ref("i.0", f64), right: num(1), type: f64, loc }, loc },
+                    update: { kind: "assign", localId: "i.0", value: { kind: "bin", op: "+", left: varRef("i.0", f64, loc), right: numLit(1, loc), type: f64, loc }, loc },
                     body: [
-                        { kind: "varDecl", localId: "k.0", init: { kind: "arrayGet", arr: ref("ks.0", ksT), index: ref("i.0", f64), type: STRING, loc }, loc },
+                        { kind: "varDecl", localId: "k.0", init: { kind: "arrayGet", arr: varRef("ks.0", ksT, loc), index: varRef("i.0", f64, loc), type: STRING, loc }, loc },
                         {
                             kind: "exprStmt",
                             expr: {
                                 kind: "jsOp",
                                 op: "setIdx",
                                 args: [
-                                    ref("out.0", JSVAL),
+                                    varRef("out.0", JSVAL, loc),
                                     { kind: "jsMarshal", value: kRef, type: JSVAL, loc },
                                     this.jsvalLiftExpr({ kind: "recordKeyGet", obj: r, shapeId, key: kRef, overflowOnly: true, type: iv, loc }, loc),
                                 ],
@@ -5861,7 +6886,7 @@ export class Lowerer {
                     ],
                     loc,
                 },
-                { kind: "return", value: ref("out.0", JSVAL), loc },
+                { kind: "return", value: varRef("out.0", JSVAL, loc), loc },
             ],
             loc,
         });
@@ -5880,8 +6905,6 @@ export class Lowerer {
         this.jsinHelpers.set(key, name);
         const arrT = { kind: "array", elem };
         const f64 = { kind: "f64" };
-        const ref = (localId, type) => ({ kind: "varRef", localId, type, loc });
-        const num = (value) => ({ kind: "numLit", value, type: f64, loc });
         this.liftedFns.push({
             name,
             params: [{ localId: "a.0", name: "a", type: arrT }],
@@ -5897,17 +6920,17 @@ export class Lowerer {
                 {
                     kind: "varDecl",
                     localId: "n.0",
-                    init: { kind: "arrIntrinsic", method: "length", receiver: ref("a.0", arrT), args: [], type: f64, loc },
+                    init: { kind: "arrIntrinsic", method: "length", receiver: varRef("a.0", arrT, loc), args: [], type: f64, loc },
                     loc,
                 },
                 {
                     kind: "for",
-                    init: { kind: "varDecl", localId: "i.0", init: num(0), loc },
-                    cond: { kind: "bin", op: "<", left: ref("i.0", f64), right: ref("n.0", f64), type: BOOL, loc },
+                    init: { kind: "varDecl", localId: "i.0", init: numLit(0, loc), loc },
+                    cond: { kind: "bin", op: "<", left: varRef("i.0", f64, loc), right: varRef("n.0", f64, loc), type: BOOL, loc },
                     update: {
                         kind: "assign",
                         localId: "i.0",
-                        value: { kind: "bin", op: "+", left: ref("i.0", f64), right: num(1), type: f64, loc },
+                        value: { kind: "bin", op: "+", left: varRef("i.0", f64, loc), right: numLit(1, loc), type: f64, loc },
                         loc,
                     },
                     body: [
@@ -5917,9 +6940,9 @@ export class Lowerer {
                                 kind: "jsOp",
                                 op: "setIdx",
                                 args: [
-                                    ref("out.0", JSVAL),
-                                    { kind: "jsMarshal", value: ref("i.0", f64), type: JSVAL, loc },
-                                    this.jsvalLiftExpr({ kind: "arrayGet", arr: ref("a.0", arrT), index: ref("i.0", f64), type: elem, loc }, loc),
+                                    varRef("out.0", JSVAL, loc),
+                                    { kind: "jsMarshal", value: varRef("i.0", f64, loc), type: JSVAL, loc },
+                                    this.jsvalLiftExpr({ kind: "arrayGet", arr: varRef("a.0", arrT, loc), index: varRef("i.0", f64, loc), type: elem, loc }, loc),
                                 ],
                                 type: { kind: "void" },
                                 loc,
@@ -5929,7 +6952,7 @@ export class Lowerer {
                     ],
                     loc,
                 },
-                { kind: "return", value: ref("out.0", JSVAL), loc },
+                { kind: "return", value: varRef("out.0", JSVAL, loc), loc },
             ],
             loc,
         });
@@ -5951,8 +6974,6 @@ export class Lowerer {
         const arrT = { kind: "array", elem: fromElem };
         const outT = { kind: "array", elem: JSVAL };
         const f64 = { kind: "f64" };
-        const ref = (localId, type) => ({ kind: "varRef", localId, type, loc });
-        const num = (value) => ({ kind: "numLit", value, type: f64, loc });
         this.liftedFns.push({
             name,
             params: [{ localId: "a.0", name: "a", type: arrT }],
@@ -5968,17 +6989,17 @@ export class Lowerer {
                 {
                     kind: "varDecl",
                     localId: "n.0",
-                    init: { kind: "arrIntrinsic", method: "length", receiver: ref("a.0", arrT), args: [], type: f64, loc },
+                    init: { kind: "arrIntrinsic", method: "length", receiver: varRef("a.0", arrT, loc), args: [], type: f64, loc },
                     loc,
                 },
                 {
                     kind: "for",
-                    init: { kind: "varDecl", localId: "i.0", init: num(0), loc },
-                    cond: { kind: "bin", op: "<", left: ref("i.0", f64), right: ref("n.0", f64), type: BOOL, loc },
+                    init: { kind: "varDecl", localId: "i.0", init: numLit(0, loc), loc },
+                    cond: { kind: "bin", op: "<", left: varRef("i.0", f64, loc), right: varRef("n.0", f64, loc), type: BOOL, loc },
                     update: {
                         kind: "assign",
                         localId: "i.0",
-                        value: { kind: "bin", op: "+", left: ref("i.0", f64), right: num(1), type: f64, loc },
+                        value: { kind: "bin", op: "+", left: varRef("i.0", f64, loc), right: numLit(1, loc), type: f64, loc },
                         loc,
                     },
                     body: [
@@ -5987,9 +7008,9 @@ export class Lowerer {
                             expr: {
                                 kind: "arrIntrinsic",
                                 method: "push",
-                                receiver: ref("out.0", outT),
+                                receiver: varRef("out.0", outT, loc),
                                 args: [
-                                    this.jsvalLiftExpr({ kind: "arrayGet", arr: ref("a.0", arrT), index: ref("i.0", f64), type: fromElem, loc }, loc),
+                                    this.jsvalLiftExpr({ kind: "arrayGet", arr: varRef("a.0", arrT, loc), index: varRef("i.0", f64, loc), type: fromElem, loc }, loc),
                                 ],
                                 type: f64,
                                 loc,
@@ -5999,7 +7020,7 @@ export class Lowerer {
                     ],
                     loc,
                 },
-                { kind: "return", value: ref("out.0", outT), loc },
+                { kind: "return", value: varRef("out.0", outT, loc), loc },
             ],
             loc,
         });
@@ -6998,6 +8019,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 };
     }
@@ -7466,7 +8495,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);
@@ -7513,7 +8548,7 @@ export class Lowerer {
      * node_modules but NOT the standard library (typescript's own lib files
      * live under node_modules too), or inside a registered workspace-linked
      * package (a node_modules symlink whose realpath'd files carry no
-     * node_modules segment — shared.ts). The provenance half of the npm
+     * node_modules segment — workspace-registry.ts). The provenance half of the npm
      * typing rule (package types are island handles) and of the per-package
      * requires-dynamic attribution. */
     isNpmFile = (sf) => sf.isDeclarationFile &&
@@ -7553,7 +8588,38 @@ export class Lowerer {
         return rejectThisInObjectMethod(this, node);
     }
     lowerElementAccess(expr) {
-        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);
@@ -7620,7 +8686,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
@@ -7760,7 +8903,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
@@ -8249,6 +9393,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) {