@scriptc/compiler 0.3.1 → 0.3.3

package/dist/frontend/lowering/lowerer.js

@@ -1,11 +1,16 @@
+import { lifetimeRegionType, lowerLifetimeRegionCall, lowerLifetimeRegionNew, } from "./lifetime-regions.js";
+import { isExperimentalDeclarationFile } from "../experimental-import.js";
 import { checkCycleBindingAccesses, refuseUncheckedCycleReads, } from "./cycle-initialization.js";
 import { identityPreservingWidening } from "./coercions/identity.js";
 import { scanDivergences } from "./divergences.js";
 import { checkedClassAssertion } from "./class-assertions.js";
 import { narrowStoredClassValue, narrowGenericClassValue } from "./class-unions.js";
 import { isOptionalProcessStreamProperty } from "./builtins/process.js";
+import { isSettledIteratorValueRead } from "./lower-generators.js";
 import { concreteCollectionNarrow } from "./collection-narrowing.js";
 import { lowerWorkerMetadata } from "./builtins/workers.js";
+import { fenceStaticBlobMember, lowerBlobNew, lowerStaticBlobCall } from "./builtins/blob.js";
+import { lowerKeyObjectCall } from "./builtins/key-object.js";
 import { dynUndefinedExpr, nodeThrowExpr, numLit, varRef } from "../../ir/build.js";
 import { iteratorSlotAdapter } from "./iterator-adapters.js";
 import { lowerBuiltinCall } from "./builtin-calls.js";
@@ -16,12 +21,14 @@ import { funcReturnWidthAdapter, coercibleValue, cleanFuncAdaptable, funcCoerceA
 import { unionRetagMappable, narrowedRetagHelper, strandedUnitTrap, strandedCoercionTrap, recordUnionWrapHelper, unionRetagHelper, narrowedArmHelper, checkedNarrowCall, checkedNarrowOperand, deferredReadHelper, } from "./coercions/unions.js";
 import { lowerUtilTypeValue, pathModuleValue, utilTypesModuleValue, } from "./lower-builtin-values.js";
 import { devirtualizeVirtualCalls } from "./devirtualize.js";
+import { foldRegexSpanReads } from "./regex-span-reads.js";
 import { RuntimeOptionalProvenance } from "./runtime-optional-provenance.js";
 import { presentAtUse, reassignedBindings } from "./runtime-optional-guards.js";
 import { NarrowingStability } from "./narrowing-stability.js";
 import { ArrayElementStates } from "./runtime-optional-elements.js";
 import { indexReadInBounds } from "./runtime-optional-bounds.js";
 import { ArrayOwnership } from "./runtime-optional-ownership.js";
+import { RecordFlowClasses } from "./runtime-optional-records.js";
 import { StringIndexBounds } from "./string-index-bounds.js";
 import { NanCodedReads } from "./nan-coded-reads.js";
 import { RuntimeOptionalLocals } from "./runtime-optional-locals.js";
@@ -31,8 +38,11 @@ import { UnregisteredClassTypes } from "./unregistered-class-types.js";
 import { bindingInContext, captureContextBinding, declareContextLocal, declareContextThis, } from "./function-context.js";
 import { InternalCompilerError } from "../../errors.js";
 import { defaultAfterUndefined, lowerStaticallyUndefinedArgument } from "./optional-arguments.js";
+import {} from "./class-protocol-dispatch.js";
 import { ClassDynamicDispatch, trackClassFieldCreation } from "./class-dynamic-dispatch.js";
 import { ClassProtocols } from "./class-protocols.js";
+import { earlyReadVarSymbols } from "./var-hoisting.js";
+import { recordTextCodecClass } from "../../ir/ir.js";
 import { DeferredModuleInitializers } from "./deferred-module-initializers.js";
 import { finalizeClassMethodValues } from "./class-method-values.js";
 export { newFnCtx } from "./function-context.js";
@@ -60,10 +70,11 @@ import { unsupportedAnyOperationDiag, blockedBindingUseDiag, checkerPanicDiag, c
 import { arrayOf, BOOL, canAdaptDynFuncTo, canDynCheckTo, canConvertToDyn, DYN, DYN_HANDLE_KINDS, F64, isDynTypedRefType, isJsonSafeType, isJsonStringifySafeType, isPrimitiveCollectionKey, isSupportedMapKey, isSupportedMapValue, isUndefinedArmedUnion, isUnitType, NULL_T, RUNTIME_ERROR_CLASSES, STRING, typeEquals, UNDEFINED_T, VOID, } from "../../ir/ir.js";
 import { provenanceActive } from "../provenance-registry.js";
 import { ambientDtsPath, canonicalBuiltinModule, cjsExportAssignmentOf, cjsExportDiscardReason, fallbackDtsPath, isCjsExportTableLiteral, isCjsJsFile, isJsSourceFile, isNodeEsmFile, isNodeTypesPath, locOf, orderedImportsOf, overridesDtsPath, npmStaticDepSf7, requireSpecOf, resolveImport, workspacePackageOfPath, } from "../program.js";
-import { containsRecord, containsUnion, describeComponentBlocker, describeRecordMemberBlocker, formatIrType, FETCH_AMBIENT_TYPES, isUnitOnlyTsType, isWorkerHandleType, jsOpenObjectType, mapType, ShapeRegistry, typeKey, UnionRegistry, withUndefinedArm as withUndefinedArmCanonical, } from "../type-mapper.js";
+import { containsRecord, containsUnion, describeComponentBlocker, describeRecordMemberBlocker, formatIrType, FETCH_AMBIENT_TYPES, isOsConstantsSymbol, isUnitOnlyTsType, isWorkerHandleType, jsOpenObjectType, mapType, ShapeRegistry, typeKey, UnionRegistry, withUndefinedArm as withUndefinedArmCanonical, } from "../type-mapper.js";
 import { builtinConstLit, builtinModuleConstOf, builtinModulesArrayLit, builtinFenceHintOf, builtinModuleFnOf, stdlibMemberFence, isStdlibMember, isStdlibSymbol, isStdlibGlobal, stdlibGlobalNameOf, stdlibGlobalMember, nodeTypesOnlySymbol, } from "./surfaces.js";
 import { splitFiles, collectProgram, collectNpmImports, collectJsonImports, moduleArtifacts, collectGlobals, declSymbolOf, defaultExportSymbolOf, lowerFileInit, lowerDefaultExport, buildMain, appendDynamicImportModules, appendForkModules, appendWorkerModules, } from "./lower-modules.js";
 import { prepareCjsModuleGraph } from "./lower-node-module.js";
+import { registerBuiltinEventTargetClasses } from "./lower-event-target.js";
 import { registerBuiltinErrorClasses, registerBuiltinEmitterClass, registerBuiltinStreamClasses, builtinErrorInfoOf, builtinEmitterInfoOf, builtinStreamInfoOf, analyzeClassDecoration, classIteratorDrainCall, classIteratorNextCall, classIteratorOf, classIteratorOpenCall, classIteratorRestDrainCall, classMemberNameOf, classValueRef, collectClassShape, exactClassOfReceiver, collectClassShapeInner, ctorAbiEquals, findMethodOn, findStaticOn, genericClassInstanceType, isSubclassOf, inHierarchy, overrideBelow, staticShadowBelow, upcastTo, lowerClassMembers, lowerClassCtor, lowerClassExpression, lowerClassExpressionInfo, lowerClassMethodMember, lowerClassValueProperty, lowerStaticMethod, throwingSetterFn, fieldInitStmts, lowerStaticFieldInits, lowerStaticFieldRead, lowerDerivedCtorBody, superCallStmt, lowerSuperMethodCall, superThisRef, lowerSuperAccessorRead, lowerSuperAccessorWrite, inheritsBuiltinErrorCtor, inheritsBuiltinEmitterCtor, errorConstructorArgs, lowerNew, accessorCall, } from "./lower-classes.js";
 import { mixinCallClassInfoOf, mixinIntersectionInstanceType, } from "./lower-mixins.js";
 import { tryLowerExpression } from "./expressions/try-lower-expression.js";
@@ -104,14 +115,14 @@ import { lowerReadlineMethodCall } from "./builtins/readline.js";
 import { lowerDiagnosticsChannelMethodCall, lowerDiagnosticsChannelProperty, lowerAsyncLocalStorageMethodCall, lowerTracingChannelMethodCall, lowerTracingChannelProperty, } from "./builtins/async-context.js";
 import { lowerErrorCodeProperty } from "./builtins/errors.js";
 import { lowerProcessProperty, lowerProcessMethodCall, lowerProcessOptionalMethodCall, lowerProcessStreamProperty, } from "./builtins/process.js";
-import { isConsoleLog, consoleCallMember } from "./builtins/console.js";
+import { consoleCallMember, consoleMethodMember, isConsoleLog, } from "./builtins/console.js";
 import { lowerConsoleNew } from "./lower-console.js";
 import { lowerNumberStaticCall, lowerNumberStaticProperty } from "./builtins/numbers.js";
 import { lowerDateCall } from "./builtins/dates.js";
 import { lowerFsConstantsProperty, lowerBuiltinConstantsProperty, builtinConstantBindingOf, builtinConstantsDestructureDecl, } from "./builtins/constants.js";
 import { lowerStringStaticCall, lowerStringLastIndexOfCall } from "./builtins/strings.js";
 import { lowerPromiseStaticCall } from "./builtins/promises.js";
-import { fenceFetchObjectAssignment, fenceFetchObjectBinding, fenceStaticAbortControllerMemberRead, fenceStaticHeadersIteration, fenceStaticHeadersMember, fenceStaticReadableStreamMember, fenceStaticResponseMember, fenceUnsupportedFetchConstructorMember, refuseUnsupportedApi, stdlibGlobalFnOf, lowerAbortControllerNew, lowerDynamicImportCall, lowerFetchCall, lowerFetchElementMethodCall, lowerResponseNew, lowerFetchWebNew, lowerStaticFetchCompanionCall, lowerStaticAbortControllerCall, lowerStaticAbortSignalListenerCall, lowerStaticReadableStreamCancelCall, lowerStaticReadableStreamControllerCall, lowerStaticReadableStreamNew, lowerStaticReadableStreamReaderCall, lowerStaticResponseCall, lowerStdlibMethodCall, lowerMathProperty, npmPackageOf, npmMemberFence, npmPackageOfSymbol, } from "./lower-stdlib.js";
+import { fenceFetchObjectAssignment, fenceFetchObjectBinding, fenceStaticAbortControllerMemberRead, fenceStaticHeadersIteration, fenceStaticHeadersMember, fenceStaticReadableStreamMember, fenceStaticResponseMember, fenceUnsupportedFetchConstructorMember, refuseUnsupportedApi, stdlibGlobalFnOf, lowerAbortControllerNew, lowerEventTargetNew, lowerLiveWebValue, lowerDynamicImportCall, lowerFetchCall, lowerFetchElementMethodCall, lowerResponseNew, lowerFetchWebNew, lowerStaticFetchCompanionCall, lowerStaticAbortControllerCall, lowerStaticAbortSignalListenerCall, lowerStaticReadableStreamCancelCall, lowerStaticReadableStreamControllerCall, lowerStaticReadableStreamNew, lowerStaticReadableStreamReaderCall, lowerStaticResponseCall, lowerStdlibMethodCall, lowerMathProperty, npmPackageOf, npmMemberFence, npmPackageOfSymbol, } from "./lower-stdlib.js";
 import { lowerHttpHeadersElement, lowerNetModuleCall, lowerServerMethodCall, lowerServerProperty, lowerTlsRootCertificates, } from "./lower-server.js";
 import { lowerDgramDnsModuleCall, lowerDgramMethodCall } from "./lower-dgram.js";
 import { lowerNodeTestModuleCall, lowerTestDirectCall, lowerTestMethodCall, lowerTestCtxProperty, } from "./lower-test.js";
@@ -495,8 +506,8 @@ export function neverTaintedJsType(lowerer, node, t) {
  * per-statement runtime fence would have thrown (message + "[code at
  * file:line]"), rendered eagerly so the runtime can throw it verbatim
  * (scr_throw_lowering_fence). The diagnostic joins the runtime-fence
- * ledger exactly like a deferred statement fence — nothing silently
- * drops off the coverage report. */
+ * ledger exactly like a deferred statement fence, so every fence appears
+ * on the coverage report. */
 export function ladderFenceExpr(lowerer, surface, node, hint) {
     const loc = locOf(node);
     const d = noLoweringDiag(surface, loc, hint);
@@ -1101,6 +1112,9 @@ export class Lowerer {
     requestInitPropMutatedSyms = null;
     emitterEventTable = null;
     emitterComputedPatterns = [];
+    /** The EventTarget engine's handleEvent reader was lifted
+     * (lower-event-target.ts noteEventListeners). */
+    handleEventReader = false;
     /** Locals widened beyond the checker's type because an inferred indexed
      * read can be absent at runtime. Bare reads preserve that union until a
      * surrounding JavaScript guard/default consumes it. */
@@ -1116,6 +1130,9 @@ 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();
+    /** `var` bindings code can read before their first store
+     * (var-hoisting.ts): their storage holds undefined until then. */
+    earlyReadVars = 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. */
@@ -1129,6 +1146,9 @@ export class Lowerer {
      * prepass. This includes explicit annotations: unchecked TS annotations do
      * not prove that an array property read produced a value. */
     runtimeOptionalBindingTypes = new Map();
+    /** Set when a match result lowers to execGroups/matchGroups, the inputs
+     * of regex span folding. */
+    regexGroupResults = false;
     /** Bindings that receive an unchecked indexed read (or a value derived
      * from one) through an initializer or assignment. The checker narrows a
      * declared optional binding to that read's bare type, so presence tests
@@ -1147,6 +1167,10 @@ export class Lowerer {
     /** 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();
+    /** Record bindings whose flow class reaches storage outside the class:
+     * they keep the declared layout, so an initializer from unchecked reads
+     * converts once instead of the binding adopting the widened variant. */
+    runtimeOptionalRecordsKeptDeclared = new Set();
     /** Callback pattern parameters carry an optional source without making
      * every name destructured from a present source optional. */
     runtimeOptionalPatternTypes = new Map();
@@ -1162,6 +1186,9 @@ export class Lowerer {
     /** for-of loops over arrays that can hold neither holes nor undefined:
      * each pass reads the element payload directly. */
     presentElementLoops = new Set();
+    /** The fs/promises glob() call lowerForOf is lowering as a for await
+     * head; other glob() calls have no lowering. */
+    fspGlobHead = null;
     /** 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();
@@ -1439,6 +1466,10 @@ export class Lowerer {
             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);
+        // The widened shape keeps the fields this one already widened.
+        for (const f of shape.fields)
+            if (this.isRuntimeOptionalField(type.shapeId, f.name))
+                this.runtimeOptionalFields.add(this.runtimeOptionalFieldKey(shapeId, f.name));
         this.runtimeOptionalFields.add(this.runtimeOptionalFieldKey(shapeId, field));
         return { kind: "record", shapeId };
     }
@@ -1522,8 +1553,9 @@ export class Lowerer {
      * runtime closure pointer: a coercion adapter allocates a different
      * closure at the registration and release sites, so lowerFfiCall must
      * refuse these forms at compile time (SC5003). Any new closure-minting
-     * adapter helper MUST add its name here, or the identity guard silently
-     * reopens and the mismatch surfaces as a runtime release trap instead. */
+     * adapter helper MUST add its name here, or the identity guard reopens
+     * without a diagnostic and the mismatch surfaces as a runtime release
+     * trap instead. */
     freshClosureAdapters = new Set();
     /** Symbols bound by `const process = globalThis.process` (and the other
      * stdlib-global snapshot spellings): pure alias plumbing — receiver
@@ -1599,6 +1631,11 @@ export class Lowerer {
     /** Named method slots observed before class collection need a callable
      * ABI and shared prototype descriptors instead of call-site specialization. */
     prototypeMethodAccesses = new Map();
+    /** Typed calls through class-backed protocols, by signature; class
+     * dynamic dispatch adds their native arms (class-protocol-dispatch.ts). */
+    protocolDispatches = new Map();
+    /** Bindings no other function assigns (class-protocol-dispatch.ts). */
+    protocolOwnedBindings = new Map();
     /** Field names whose complete source census stores only lexical arrows. */
     receiverFreeCallbackFields = new Set();
     /** Inferred JS methods participating in an override chain keep a vtable
@@ -1655,6 +1692,12 @@ export class Lowerer {
     workerTargets;
     workerTargetIdByPath = new Map();
     usesWorkers = false;
+    /** The program constructs a LifetimeRegion (lifetime-regions.ts). */
+    usesLifetimeRegions = false;
+    /** Per-directory answers of experimental-import.ts's declaration-file test. */
+    experimentalFiles = new Map();
+    /** Interned LifetimeRegion.run helpers, by callback type key. */
+    regionRunHelpers = new Map();
     forkTargetIdByPath = new Map();
     /** Namespace ModuleBlocks this program lowers, filled by splitFiles:
      * "flattened" — an instantiated namespace whose body joined the file's
@@ -1761,6 +1804,9 @@ export class Lowerer {
     /** Import-cycle bindings with an initialization flag, by global id, and
      * the top-level statements declaring them (cycle-initialization.ts). */
     cycleInitFlags = new Map();
+    /** Initialization flags of classes reachable before their statement ran,
+     * by class name (cycle-initialization.ts). */
+    classInitFlags = new Map();
     cycleInitDeclarations = new Map();
     get ctx() {
         const top = this.fnStack[this.fnStack.length - 1];
@@ -1784,6 +1830,9 @@ export class Lowerer {
     /** Set while a subclass constructor's super() call notes its base
      * constructor edge: that edge does not instantiate the base exactly. */
     superConstructorEdge = false;
+    /** Set when the async generator `return` being lowered awaited its
+     * promise operand (returnedPromiseAwait). */
+    returnAwaitedPromise = false;
     virtualEdges = new Map();
     classCanBeConstructed(info) {
         return (this.constructedClasses === null ||
@@ -1963,6 +2012,9 @@ export class Lowerer {
             // fileTag is filled just below; the hook is only ever CALLED during
             // lowering, long after the constructor completes.
             isProgramFile: (sf) => this.fileTag.has(sf),
+            lifetimeRegionClass: (decl) => isExperimentalDeclarationFile(decl.getSourceFile(), this.experimentalFiles)
+                ? lifetimeRegionType(this)
+                : null,
             moduleNamespaceId: (type) => this.moduleNamespaceIdOfType(type),
         };
         // Modules reachable only through literal import() joined
@@ -1977,6 +2029,7 @@ export class Lowerer {
         this.registerBuiltinErrorClasses();
         registerBuiltinEmitterClass(this);
         registerBuiltinStreamClasses(this);
+        registerBuiltinEventTargetClasses(this);
     }
     registerBuiltinErrorClasses() {
         return registerBuiltinErrorClasses(this);
@@ -3009,8 +3062,70 @@ export class Lowerer {
                     familyBySymbol.set(symbol, family);
                 }
             }
+            // Static methods never share a dispatch slot: each is its own family.
+            if (info.staticMethods) {
+                for (const sig of info.staticMethods.values()) {
+                    const name = sig.member.name;
+                    if (!(ts.isIdentifier(name) || ts.isStringLiteral(name)))
+                        continue;
+                    const symbol = symbolOf(name);
+                    if (symbol && !signatureBySymbol.has(symbol))
+                        signatureBySymbol.set(symbol, { params: sig.params, returnType: sig.ret, method: sig });
+                }
+            }
         }
         const mappedOrNull = (node) => panicSafe(() => this.mapTypeOf(this.typeOf(node)), null);
+        const admitsUndefined = (type) => typeEquals(addUndefined(type), type);
+        const plainRecordShape = (type) => {
+            if (type?.kind !== "record")
+                return null;
+            const shape = this.shapes.get(type.shapeId);
+            return shape && !shape.tuple && !shape.indexValue && shape.fields.length > 0
+                ? type.shapeId
+                : null;
+        };
+        // Parameters and results read the signatures collected above; bindings
+        // ask the checker, so the scan builds no layout of its own.
+        const parameterType = (node) => {
+            const parameter = node.parent;
+            if (!parameter || !ts.isParameter(parameter))
+                return null;
+            const fn = parameter.parent;
+            const symbol = (ts.isFunctionDeclaration(fn) || ts.isMethodDeclaration(fn)) && fn.name
+                ? symbolOf(fn.name)
+                : null;
+            const index = fn.parameters.indexOf(parameter);
+            return (symbol && signatureBySymbol.get(symbol)?.params[index]?.type) ?? null;
+        };
+        const returnTypeOf = (fn) => {
+            const symbol = fn.name ? symbolOf(fn.name) : null;
+            return (symbol && signatureBySymbol.get(symbol)?.returnType) ?? null;
+        };
+        const recordFlows = new RecordFlowClasses(sourceFiles, {
+            symbolOf,
+            declarationOf: (symbol) => this.checker.valueDeclarationOf(symbol),
+            mayBeRecord: (node) => {
+                if (node.parent && ts.isParameter(node.parent))
+                    return plainRecordShape(parameterType(node)) !== null;
+                const t = panicSafe(() => this.typeOf(node), null);
+                return (t !== null &&
+                    (t.flags & ts.TypeFlags.Object) !== 0 &&
+                    !this.checker.isArrayType(t) &&
+                    this.checker.getCallSignatures(t).length === 0 &&
+                    this.checker.getConstructSignatures(t).length === 0);
+            },
+            prefetchTypes: (nodes) => this.checker.prefetchCollectionTypes(nodes),
+            mayReturnRecord: (fn) => plainRecordShape(returnTypeOf(fn)) !== null,
+            familyOf: (method) => familyBySymbol.get(method),
+            recordShape: (node) => plainRecordShape(node.parent && ts.isParameter(node.parent) ? parameterType(node) : mappedOrNull(node)),
+            returnShape: (fn) => plainRecordShape(returnTypeOf(fn)),
+            isGlobal: (node, name) => this.isStdlibGlobal(node, name),
+        });
+        /** Optional fields of the records a visible function returns. */
+        const returnFields = new Map();
+        /** Record parameters that receive a value with optional fields, by the
+         * parameter's own symbol. */
+        const recordParameterSlots = new Map();
         const nanCoded = new NanCodedReads({
             symbolOf,
             declarationOf: (symbol) => this.checker.valueDeclarationOf(symbol),
@@ -3228,6 +3343,10 @@ export class Lowerer {
                 return true;
             if (ts.isPropertyAccessExpression(e) && isOptionalProcessStreamProperty(this, e))
                 return true;
+            if (ts.isPropertyAccessExpression(e) && isSettledIteratorValueRead(this, e))
+                return true;
+            if (ts.isPropertyAccessExpression(e) && isOsConstantsSymbol(symbolOf(e.expression), this))
+                return true;
             if (ts.isCallExpression(e) && this.runtimeOptionalReduceTypes.has(e))
                 return true;
             if (ts.isCallExpression(e) &&
@@ -3285,10 +3404,8 @@ export class Lowerer {
                 if (op === ts.SyntaxKind.AmpersandAmpersandToken)
                     return mayBeOptional(e.left) || mayBeOptional(e.right);
             }
-            if (ts.isPropertyAccessExpression(e) && ts.isIdentifier(e.expression)) {
-                const symbol = symbolOf(e.expression);
-                const fields = symbol === null ? undefined : optionalFields.get(symbol);
-                return fields?.has(fieldName(e)) ?? false;
+            if (ts.isPropertyAccessExpression(e)) {
+                return fieldsOfValue(e.expression)?.has(fieldName(e)) ?? false;
             }
             return false;
         };
@@ -3397,10 +3514,40 @@ export class Lowerer {
         // a spread or a parameter receives the source's optional fields.
         const fieldsOfValue = (node) => {
             const e = peel(node);
-            if (!ts.isIdentifier(e))
-                return undefined;
-            const symbol = symbolOf(e);
-            return symbol === null ? undefined : optionalFields.get(symbol);
+            if (ts.isIdentifier(e)) {
+                const symbol = symbolOf(e);
+                // A binding whose class reaches other storage keeps the declared
+                // layout, so its fields read as present.
+                return symbol === null || recordFlows.opened(symbol)
+                    ? undefined
+                    : optionalFields.get(symbol);
+            }
+            // A fresh literal carries the fields its values can leave undefined.
+            if (ts.isObjectLiteralExpression(e)) {
+                const out = spreadFieldsOf(e);
+                for (const prop of e.properties) {
+                    if (!ts.isPropertyAssignment(prop) && !ts.isShorthandPropertyAssignment(prop))
+                        continue;
+                    const name = prop.name;
+                    if (!(ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)))
+                        continue;
+                    const value = ts.isPropertyAssignment(prop) ? prop.initializer : name;
+                    if (mayBeOptional(value))
+                        out.add(name.text);
+                }
+                return out.size > 0 ? out : undefined;
+            }
+            if (ts.isCallExpression(e) &&
+                (ts.isIdentifier(e.expression) || ts.isPropertyAccessExpression(e.expression))) {
+                const symbol = symbolOf(ts.isIdentifier(e.expression) ? e.expression : e.expression.name);
+                return symbol === null ? undefined : returnFields.get(symbol);
+            }
+            if (ts.isConditionalExpression(e)) {
+                const a = fieldsOfValue(e.whenTrue);
+                const b = fieldsOfValue(e.whenFalse);
+                return a && b ? new Set([...a, ...b]) : (a ?? b);
+            }
+            return undefined;
         };
         const noteFieldsFrom = (symbol, source) => {
             const fields = fieldsOfValue(source);
@@ -3520,6 +3667,19 @@ export class Lowerer {
                     found = true;
             return found;
         };
+        /** A return of a var that code can read before its first store. */
+        const returnsEarlyVar = (fn) => {
+            const early = (e) => {
+                const read = peel(e);
+                if (!ts.isIdentifier(read))
+                    return false;
+                const symbol = symbolOf(read);
+                return symbol !== null && this.earlyReadVars.has(symbol);
+            };
+            if (fn.body && !ts.isBlock(fn.body))
+                return early(fn.body);
+            return returnsOf(fn).some(early);
+        };
         const jsLambdas = [];
         // TypeScript lambdas keep the checker's inferred return type, which
         // spells a missing read as its bare element type and `read ?? "text"`
@@ -4415,23 +4575,21 @@ export class Lowerer {
                                 const bound = symbolOf(parameter.name);
                                 if (!bound)
                                     continue;
-                                let promoted = parameterShape.type;
+                                const declared = this.shapes.get(parameterShape.type.shapeId);
+                                // The parameter's layout settles with its flow class once
+                                // the fixed point ends. A literal or call argument only adds
+                                // fields the declaration calls present.
+                                const fresh = !ts.isIdentifier(peel(arg));
                                 for (const field of fields) {
-                                    const source = promoted.kind === "record"
-                                        ? this.shapes.get(promoted.shapeId)?.fields.find((f) => f.name === field)
-                                        : undefined;
-                                    if (source) {
-                                        promoted = this.runtimeOptionalRecordField(promoted, field, addUndefined(source.type));
-                                    }
-                                    if (noteFieldSymbol(bound, field))
+                                    const slot = declared?.fields.find((f) => f.name === field);
+                                    if (!slot || (fresh && admitsUndefined(slot.type)))
+                                        continue;
+                                    if (noteFieldSymbol(bound, field)) {
+                                        provenance?.note("record-parameter", parameter, arg);
                                         changed = true;
+                                    }
                                 }
-                                if (!typeEquals(promoted, parameterShape.type)) {
-                                    parameterShape.type = promoted;
-                                    this.runtimeOptionalBindingTypes.set(bound, promoted);
-                                    provenance?.note("record-parameter", parameter, arg);
-                                    changed = true;
-                                }
+                                recordParameterSlots.set(bound, { target, index: i });
                             }
                         }
                         if (ts.isSpreadElement(arg) || !shape)
@@ -4515,7 +4673,27 @@ export class Lowerer {
         };
         const scanReturns = (symbol, decl) => {
             let changed = false;
+            const recordReturn = recordFlows.returnClass(symbol) !== null;
+            const returned = signatureBySymbol.get(symbol)?.returnType;
+            const returnedShape = returned?.kind === "record" ? this.shapes.get(returned.shapeId) : null;
             for (const expression of returnsOf(decl)) {
+                const fields = recordReturn ? fieldsOfValue(expression) : undefined;
+                if (fields) {
+                    for (const field of fields) {
+                        // A result field that already admits undefined keeps the
+                        // checker's narrowing.
+                        const slot = returnedShape?.fields.find((f) => f.name === field);
+                        if (slot && admitsUndefined(slot.type))
+                            continue;
+                        const set = returnFields.get(symbol) ?? new Set();
+                        if (set.has(field))
+                            continue;
+                        set.add(field);
+                        returnFields.set(symbol, set);
+                        provenance?.note("record-return", decl.name ?? decl, expression);
+                        changed = true;
+                    }
+                }
                 if (mayBeOptional(expression) && !optionalReturns.has(symbol)) {
                     optionalReturns.add(symbol);
                     provenance?.note("return", decl.name ?? decl, expression);
@@ -4529,6 +4707,19 @@ export class Lowerer {
             }
             return changed;
         };
+        // A `var` that code can read before its first store holds undefined
+        // there, whatever its declared type.
+        for (const symbol of earlyReadVarSymbols(this, sourceFiles)) {
+            // Text codec bindings keep their own presence-checked storage.
+            const declaration = this.checker.valueDeclarationOf(symbol);
+            const mapped = declaration && ts.isVariableDeclaration(declaration)
+                ? mappedOrNull(declaration.name)
+                : null;
+            if (mapped?.kind === "record" && recordTextCodecClass(this.shapes.get(mapped.shapeId)))
+                continue;
+            optionalSymbols.add(symbol);
+            this.earlyReadVars.add(symbol);
+        }
         let changed = true;
         while (changed) {
             changed = false;
@@ -4546,8 +4737,10 @@ export class Lowerer {
                 if (scanReturns(symbol, decl))
                     changed = true;
             for (const fn of tsLambdas) {
-                // An annotated return is the author's contract, as for parameters.
-                if (fn.type)
+                // An annotated return is the author's contract, as for parameters,
+                // except that a var read before its first store is undefined
+                // whatever the annotation says.
+                if (fn.type && !returnsEarlyVar(fn))
                     continue;
                 const mapped = this.mapTypeOf(this.typeOf(fn));
                 if (mapped?.kind !== "func")
@@ -4679,6 +4872,72 @@ export class Lowerer {
                 this.runtimeOptionalGlobals.add(global);
             }
         }
+        // Record layouts settle per flow class: a closed class widens every
+        // member to the union of its members' optional fields, and a class that
+        // reaches other storage keeps the declared layout for every member.
+        const classFields = new Map();
+        const addClassFields = (id, fields) => {
+            if (id === null)
+                return;
+            const set = classFields.get(id) ?? new Set();
+            for (const field of fields)
+                set.add(field);
+            classFields.set(id, set);
+        };
+        for (const [symbol, fields] of optionalFields)
+            addClassFields(recordFlows.bindingClass(symbol), fields);
+        for (const [symbol, fields] of returnFields)
+            addClassFields(recordFlows.returnClass(symbol), fields);
+        const settledFields = (id, own) => id === null
+            ? own
+            : classFields.has(id) && recordFlows.closed(id)
+                ? classFields.get(id)
+                : undefined;
+        const widenRecordFields = (type, fields) => {
+            let promoted = type;
+            for (const field of fields) {
+                const source = promoted.kind === "record"
+                    ? this.shapes.get(promoted.shapeId)?.fields.find((f) => f.name === field)
+                    : undefined;
+                if (source)
+                    promoted = this.runtimeOptionalRecordField(promoted, field, addUndefined(source.type));
+            }
+            return promoted;
+        };
+        for (const [symbol, id] of recordFlows.bindings())
+            if (classFields.has(id) && !recordFlows.closed(id))
+                this.runtimeOptionalRecordsKeptDeclared.add(symbol);
+        // Every tracked parameter settles with its class, including one that
+        // only receives plain records. An untracked one (a function used as a
+        // value, a method another member name or view can reach) widens to the
+        // fields its own arguments carry.
+        for (const { symbol, fn, index } of recordFlows.parameters())
+            recordParameterSlots.set(symbol, { target: fn, index });
+        for (const [bound, { target, index }] of recordParameterSlots) {
+            const shape = signatureBySymbol.get(target)?.params[index];
+            if (!shape || shape.type.kind !== "record")
+                continue;
+            const fields = settledFields(recordFlows.bindingClass(bound), optionalFields.get(bound));
+            if (!fields)
+                continue;
+            const promoted = widenRecordFields(shape.type, fields);
+            if (typeEquals(promoted, shape.type))
+                continue;
+            shape.type = promoted;
+            this.runtimeOptionalBindingTypes.set(bound, promoted);
+        }
+        for (const [symbol, sig] of signatureBySymbol) {
+            const id = recordFlows.returnClass(symbol);
+            const fields = id === null ? undefined : settledFields(id, undefined);
+            if (fields && sig.returnType.kind === "record") {
+                const next = widenRecordFields(sig.returnType, fields);
+                sig.returnType = next;
+                if (sig.top)
+                    sig.top.returnType = next;
+                if (sig.method)
+                    sig.method.ret = next;
+            }
+        }
         for (const [symbol, sig] of signatureBySymbol) {
             const params = optionalParams.get(symbol);
             if (params) {
@@ -4762,7 +5021,7 @@ export class Lowerer {
                             global.type = promoted;
                     }
                 }
-                const fields = optionalFields.get(symbol);
+                const fields = settledFields(recordFlows.bindingClass(symbol), optionalFields.get(symbol));
                 if (!dynamicObjectEntryRows.has(symbol) && !optionalSymbols.has(symbol) && !fields)
                     return;
                 const current = this.mapTypeOf(this.typeOf(node.name));
@@ -4781,16 +5040,8 @@ export class Lowerer {
                         };
                     }
                 }
-                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 (fields && promoted.kind === "record")
+                    promoted = widenRecordFields(promoted, fields);
                 if (!typeEquals(promoted, current)) {
                     this.runtimeOptionalBindingTypes.set(symbol, promoted);
                     const global = ts.isIdentifier(node.name)
@@ -5107,6 +5358,7 @@ export class Lowerer {
                 globals: this.globalsList,
                 entry: ENTRY_NAME,
                 ...(this.usesWorkers ? { workers: true } : {}),
+                ...(this.usesLifetimeRegions ? { lifetimeRegions: true } : {}),
                 ...(isNodeEsmFile(this.entry, this.program) ? {} : { commonJsEntry: true }),
                 ...(this.ffiImports.length > 0 ? { ffiImports: [...this.ffiImports] } : {}),
             };
@@ -5291,6 +5543,8 @@ export class Lowerer {
         for (const info of this.classes.values()) {
             if (info.builtinError)
                 continue; // runtime-provided; nothing lowers
+            if (info.lifetimeRegion)
+                continue; // synthesized with the class
             // Generic-class INSTANTIATIONS (and mixin instantiations) are
             // demand-driven, not units: their members lower unconditionally in
             // the instance drain below — the generic-fn instance rule.
@@ -5606,6 +5860,9 @@ export class Lowerer {
             ...this.liftedFns,
             ...this.implicitFns,
         ];
+        if (this.regexGroupResults)
+            for (const fn of functions)
+                foldRegexSpanReads(this, fn);
         // The worklist can leave a virtual site with a single implementation.
         // Devirtualize after construction/override reachability has settled.
         devirtualizeVirtualCalls(this, functions, {
@@ -5727,7 +5984,7 @@ export class Lowerer {
             : diag;
         const pending = this.pendingFlushes.get(diag);
         // Deferred collection: the wrapper decides whether these ever report
-        // (a reference flushes them; unreferenced declarations stay silent in
+        // (a reference flushes them; unreferenced declarations report nothing in
         // builds and report under coverage's unreached group).
         if (this.diagSink) {
             if (pending && d !== diag)
@@ -5941,7 +6198,7 @@ export class Lowerer {
         return stdlibMemberFence(this, access);
     }
     fenceStaticResponseMember(access, use) {
-        return fenceStaticResponseMember(this, access, use);
+        return fenceStaticResponseMember(this, access, use) ?? fenceStaticBlobMember(this, access, use);
     }
     fenceUnsupportedFetchConstructorMember(access) {
         return fenceUnsupportedFetchConstructorMember(this, access);
@@ -6698,6 +6955,21 @@ export class Lowerer {
                     return this.checkedNarrowCall(helper, expr, expected, expr.loc);
                 }
             }
+            // A record arm beside unit arms flowing into another layout of that
+            // record (`R | undefined` into the runtime-optional variant of R): the
+            // same checked extraction of the record arm, then the record's width
+            // lift into the destination layout.
+            if (expr.type.kind === "union" && expected.kind === "record") {
+                const arms = this.unions.get(expr.type.unionId)?.arms ?? [];
+                const records = arms.filter((arm) => !isUnitType(arm));
+                const arm = records.length === 1 && records[0].kind === "record" ? records[0] : null;
+                const lift = arm ? this.widthLiftPlan(arm, expected) : null;
+                const helper = arm && lift ? this.narrowedArmHelper(expr.type.unionId, arm, expr.loc) : null;
+                if (arm && lift && helper) {
+                    const narrowed = this.checkedNarrowCall(helper, expr, arm, expr.loc);
+                    return this.applyWidthLift(lift, narrowed, expected, expr.loc);
+                }
+            }
             if (!typeEquals(expr.type, expected)) {
                 const w = this.widthCoerce(expr, expected);
                 if (w)
@@ -7296,6 +7568,8 @@ export class Lowerer {
                     builtinOption("RequestInit") ||
                     builtinOption("ErrorOptions") ||
                     builtinOption("SpawnOptions") ||
+                    builtinOption("UrlObject") ||
+                    builtinOption("URLFormatOptions") ||
                     !this.mapTypeOf(this.typeOf(x))) {
                     return lowerDynObjectLiteral(this, x);
                 }
@@ -7496,8 +7770,10 @@ export class Lowerer {
     returnedPromiseAwait(e) {
         if (e.type.kind !== "promise")
             throw new InternalCompilerError("returned-promise await of a non-promise");
-        if (!this.adoptsReturnedPromise())
+        if (!this.adoptsReturnedPromise()) {
+            this.returnAwaitedPromise = true;
             return { kind: "awaitExpr", value: e, type: e.type.inner, loc: e.loc };
+        }
         return { kind: "awaitExpr", value: e, type: e.type.inner, adopt: true, loc: e.loc };
     }
     /** `return <expr>` lowered as a STATEMENT against the declared return.
@@ -7507,6 +7783,26 @@ export class Lowerer {
      * caller never sees a value, so the return goes out bare. Async
      * void-inner returns still resolve a returned promise first. */
     lowerReturnStmt(node, loc) {
+        if (!(this.ctx.isAsync === true && this.ctx.generator))
+            return this.lowerReturnOf(node, loc);
+        // An async generator's `return x` awaits x; for a promise that await
+        // is the returned-promise await, and the return needs no other turn.
+        const saved = this.returnAwaitedPromise;
+        this.returnAwaitedPromise = false;
+        const s = this.lowerReturnOf(node, loc);
+        const awaited = this.returnAwaitedPromise;
+        this.returnAwaitedPromise = saved;
+        if (!awaited)
+            return s;
+        if (s.kind === "return")
+            return { ...s, awaited: true };
+        if (s.kind === "block" && s.body.at(-1)?.kind === "return") {
+            const last = s.body.at(-1);
+            return { ...s, body: [...s.body.slice(0, -1), { ...last, awaited: true }] };
+        }
+        return s;
+    }
+    lowerReturnOf(node, loc) {
         const expected = this.ctx.returnType;
         if (expected.kind === "void") {
             let e = this.lowerExpr(node);
@@ -8597,7 +8893,7 @@ export class Lowerer {
      * lowered — set by lowerLabeled around lowering the labeled construct,
      * consumed exactly once by the construct's own lowering (takeLabels).
      * A lowering that never consumes them signals lowerLabeled to fence:
-     * silently dropping a label would compile `break lbl` wrong. */
+     * dropping a label without a diagnostic would compile `break lbl` wrong. */
     pendingLabels = null;
     takeLabels() {
         const labels = this.pendingLabels;
@@ -8804,6 +9100,9 @@ export class Lowerer {
     lowerElementWrite(expr) {
         return lowerElementWrite(this, expr);
     }
+    lowerLiveWebValue(node) {
+        return lowerLiveWebValue(this, node);
+    }
     ensureString(e, node) {
         return ensureString(this, e, node);
     }
@@ -8945,7 +9244,8 @@ export class Lowerer {
         // dispatch. The general identifier-call paths have no lowering for a
         // promise-returning ambient global, and `import` is a keyword callee no
         // identifier path matches.
-        return (lowerFfiCall(this, expr) ??
+        return (lowerLifetimeRegionCall(this, expr) ??
+            lowerFfiCall(this, expr) ??
             lowerFetchCall(this, expr) ??
             lowerStaticFetchCompanionCall(this, expr) ??
             lowerStaticAbortControllerCall(this, expr) ??
@@ -8954,6 +9254,8 @@ export class Lowerer {
             lowerStaticReadableStreamControllerCall(this, expr) ??
             lowerStaticReadableStreamReaderCall(this, expr) ??
             lowerStaticResponseCall(this, expr) ??
+            lowerStaticBlobCall(this, expr) ??
+            lowerKeyObjectCall(this, expr) ??
             lowerFetchElementMethodCall(this, expr) ??
             lowerDynamicImportCall(this, expr) ??
             lowerCall(this, expr));
@@ -9080,9 +9382,12 @@ export class Lowerer {
         return inheritsBuiltinEmitterCtor(this, info);
     }
     lowerNew(expr) {
-        const builtin = lowerAbortControllerNew(this, expr) ??
+        const builtin = lowerLifetimeRegionNew(this, expr) ??
+            lowerAbortControllerNew(this, expr) ??
+            lowerEventTargetNew(this, expr) ??
             lowerFetchWebNew(this, expr) ??
             lowerResponseNew(this, expr) ??
+            lowerBlobNew(this, expr) ??
             lowerStaticReadableStreamNew(this, expr) ??
             lowerConsoleNew(this, expr);
         return (builtin ?? this.withRuntimeOptionalClassValue(expr.expression, () => lowerNew(this, expr)));
@@ -9135,6 +9440,9 @@ export class Lowerer {
     consoleCallMember(call) {
         return consoleCallMember(this, call);
     }
+    consoleMethodMember(call) {
+        return consoleMethodMember(this, call);
+    }
     /* ── standard library (process + node:fs) ─────────────────────────── */
     builtinImportOf(ident) {
         return builtinImportOf(this, ident);
@@ -9361,6 +9669,10 @@ export class Lowerer {
         if (bi.module === "http" && bi.member === "STATUS_CODES") {
             return { kind: "libCall", fn: "http.statusCodes", args: [], type: DYN, loc };
         }
+        // os.constants: the runtime's null-prototype constants object.
+        if (bi.module === "os" && bi.member === "constants") {
+            return { kind: "libCall", fn: "os.constants", args: [], type: DYN, loc };
+        }
         // tls.rootCertificates through the namespace: the same runtime-valued
         // constant the named-import read lowers to.
         {