@scriptc/compiler 0.4.6 → 0.4.8

package/dist/frontend/lowering/lowerer.d.ts

@@ -1,23 +1,30 @@
 import type { DiagnosticCode } from "../../diagnostics/codes.js";
 import { type RecordOrigin } from "./decl-origin.js";
 import { type JournalScalar, type JournalTable, type UnitEvents } from "./unit-journal.js";
+import { type UnitStore } from "./unit-reuse.js";
 import { StructuralPositions } from "./structural-positions.js";
 import { type NodeIslandSet } from "../../node-islands/boundary.js";
-import type { IslandModuleBinding } from "./lower-node-island.js";
+import type { IslandBinding, IslandModuleBinding } from "./lower-node-island.js";
+import { LoweringFacts } from "./lowering-facts.js";
+import { type AdmittedOpinion } from "../tsc-codes.js";
 import type { ConstructorReturnPlan } from "./constructor-returns.js";
 import { type CycleInitFlag } from "./cycle-initialization.js";
 import { type JsonRequireModule } from "./json-require.js";
 import { type EarlyReference, type RequireInitFlag } from "./require-initialization.js";
 import { KeyOrderNotes } from "./key-order-witness.js";
+import { type StdioPatchSite } from "./builtins/process.js";
 import { type WasmModuleReport } from "../../wasm/discover.js";
 import type { FieldLift } from "./coercions/structural-plans.js";
 import { CoercionState } from "./coercions/state.js";
+import { RuntimeOptionalProvenance } from "./runtime-optional-provenance.js";
+import { type RuntimeOptionalNarrowing } from "./runtime-optional-report.js";
 import { NarrowingStability } from "./narrowing-stability.js";
 import { StringIndexBounds } from "./string-index-bounds.js";
 import { NanCodedReads } from "./nan-coded-reads.js";
 import { RuntimeOptionalLocals } from "./runtime-optional-locals.js";
 import { type ContractAnnotations } from "../contract-types.js";
 import type { WidthLift } from "./width-lift.js";
+import type { UnionClassRoute } from "./union-retag.js";
 import { type FnCtx } from "./function-context.js";
 import type { FrontendServices } from "../services.js";
 import type { FsPathPlan } from "./builtins/fs-paths.js";
@@ -25,6 +32,7 @@ import { type ProtocolDispatch } from "./class-protocol-dispatch.js";
 import { type DynamicFunction } from "../../ir/tiers.js";
 import { type TierMode, type TierReport } from "../tier-analysis.js";
 import { DeferredModuleInitializers } from "./deferred-module-initializers.js";
+import { type LinkedHelper, type StringFallback } from "./record-links.js";
 import { type ClassSymbolKey } from "./symbol-fields.js";
 import type { HttpClientFnBinding } from "./lower-server.js";
 export type { WidthLift } from "./width-lift.js";
@@ -34,9 +42,9 @@ import { type UnionLiteral } from "../union-discriminants.js";
 import type { ScrDiagnostic, TypeFailure, TypeFailureSlot } from "../../diagnostics/diagnostic.js";
 import { type DynamicSlotEntry } from "../../diagnostics/dynamic-slots.js";
 import { UNSUPPORTED } from "../../diagnostics/diagnostic.js";
-import type { IrClassDef, IrExpr, IrFfiImport, IrFunction, IrGlobal, IrLocal, IrModule, IrParam, IrRecordShape, IrStmt, IrType, IrUnionDef, SrcLoc } from "../../ir/ir.js";
+import type { IrClassDef, IrExpr, IrFfiImport, IrFunction, IrGlobal, IrLocal, IrModule, IrParam, IrRecordLink, IrRecordShape, IrStmt, IrType, IrUnionDef, SrcLoc } from "../../ir/ir.js";
 import { type StartupCrash, type CycleEdge } from "../program.js";
-import { ShapeRegistry, type TypeMapperCtx, UnionRegistry } from "../type-mapper.js";
+import { ShapeRegistry, type SymbolProvenance, type TypeMapperCtx, UnionRegistry } from "../type-mapper.js";
 import { type CompoundOp, type StdlibFnEntry, type BuiltinModuleFn } from "./surfaces.js";
 import { type BuiltinClassRef } from "./builtins/class-values.js";
 import { type FileParts } from "./lower-modules.js";
@@ -44,7 +52,7 @@ import { type SplitRequireBinding } from "./cjs-inline-require.js";
 import { type ClassInfo, type ClassIteratorInfo, type ClassIteratorOptions, type GenericClassInfo, findStaticOn } from "./lower-classes.js";
 import { type MixinFnShape } from "./lower-mixins.js";
 import { type ParamShape, type FnSig } from "./call-signatures.js";
-import { type GenericFnInfo, type GenericInstance } from "./generic-functions.js";
+import { type GenericFnInfo, type GenericInstance, type GenericAliasPresence } from "./generic-functions.js";
 import type { InstantiationPath } from "./instantiation-path.js";
 import { type ArrayHofInfo } from "./containers/array-pipelines.js";
 import { type RecordOvfCapturePlan } from "./containers/indexed-objects.js";
@@ -179,6 +187,18 @@ export interface LowerResult {
     dynamicFunctions?: DynamicFunction[];
     /** LowerOptions.tierReport: the report-only tier assignment. */
     tiers?: TierReport;
+    /** The program replaces a process output stream's write method, with the
+     * site: the executable planner refuses the combination with Node islands
+     * (SC8006), whose process objects would not see the patch. Present only
+     * when the build has islands. */
+    stdioPatches?: StdioPatchSite[];
+    /** LIBRARY mode (LowerOptions.libRoots): each root name resolved through
+     * the entry module's export table to the unit that supplies it — the
+     * entry's own unit for a direct export, the module-tagged unit of the
+     * declaration for a re-exported one. Absent when the build passes no lib
+     * roots; a root name that resolves to no unit is absent from the map
+     * (the export-map resolution reports it as SC4002). */
+    libExportUnits?: ReadonlyMap<string, string>;
 }
 export interface LowerOptions {
     /** Packages that run in Node islands (scope-B NI-4): their imports lower
@@ -186,6 +206,9 @@ export interface LowerOptions {
     nodeIslands?: NodeIslandSet | null;
     /** Parser/checker services owned by the load; required for npm graph analysis. */
     frontendServices?: FrontendServices | undefined;
+    /** Where reachable emit stores its units' records and finds an earlier
+     * build's (unit-reuse.ts). */
+    unitStore?: UnitStore | null;
     /** The project's tsconfig sets `checkJs` (see isCheckedJsSourceFile). */
     projectCheckJs?: boolean;
     /** Coverage: additionally lower the unreached remainder (bodies nothing
@@ -207,17 +230,23 @@ export interface LowerOptions {
      * resolution walk and named-import link checks): the program
      * compiles to that startup crash. */
     startupCrash?: StartupCrash | null;
+    /** LoadResult.admittedOpinions: every JavaScript checker diagnostic
+     * preflight admitted under an opinion row (tsc-codes.ts, JS_OPINIONS). A
+     * view's lowering path is gated on one of these records. */
+    admittedOpinions?: readonly AdmittedOpinion[] | undefined;
     /** LoadResult.inlineRequireCycleCalls. */
     inlineRequireCycleCalls?: ReadonlySet<ts.Node> | undefined;
     /** LoadResult.moduleEdges. */
     moduleEdges?: ReadonlyMap<ts.SourceFile, readonly CycleEdge[]> | undefined;
     /** LoadResult.dynamicImportRejections. */
     dynamicImportRejections?: ReadonlyMap<ts.SourceFile, StartupCrash> | undefined;
-    /** LIBRARY mode's reachability roots: the profile-mapped exports of the
-     * entry module. Executable builds root at the entry's top level alone
+    /** LIBRARY mode's reachability roots: the profile-mapped export names of
+     * the entry module. Executable builds root at the entry's top level alone
      * (an unreferenced export dead-strips); a library's exports are called from
-     * OUTSIDE the graph, so discovery seeds them alongside the init
-     * bodies. Names are the entry file's unqualified declaration names. */
+     * OUTSIDE the graph, so discovery seeds them alongside the init bodies.
+     * Each name resolves through the entry module's export table (see
+     * libExportUnit), so a re-exported function seeds the unit of the module
+     * that declares it. */
     libRoots?: readonly string[];
     /** Outbound native FFI declarations from a validated format-1 manifest.
      * Calls of their exact ambient TypeScript bindings lower to direct C ABI
@@ -324,6 +353,9 @@ export interface LowererMode {
      * pass saw an untyped value flow into a stream slot
      * (requiresDynNodeStreams). */
     dynNodeStreams?: boolean;
+    /** LoadResult.admittedOpinions: the JS opinion sites preflight admitted
+     * (opinionAt). */
+    admittedOpinions?: readonly AdmittedOpinion[] | undefined;
     /** LoadResult.inlineRequireCycleCalls. */
     inlineRequireCycleCalls?: ReadonlySet<ts.Node> | undefined;
     /** LoadResult.dynamicImportRejections. */
@@ -337,6 +369,11 @@ export interface LowererMode {
      * always-reachable init bodies and module building, and report deferred
      * collection diagnostics nothing flushed. */
     remainder?: boolean;
+    /** Coverage (--explain-dynamic): keep the runtime-optional storage
+     * decisions and the reads the checker narrows below the widened
+     * storage, for the report (runtime-optional-report.ts). Report-only:
+     * lowering does not change. */
+    runtimeOptionalReport?: boolean;
     /** Node's startup refusal (preflight's resolution walk / named-import
      * link checks): %main opens with exactly this throw, before any
      * module init — Node refuses the whole graph before anything evaluates,
@@ -348,6 +385,11 @@ export interface LowererMode {
     /** LowerOptions.tierMode, shared by every pass. */
     tierMode?: TierMode;
     workerTargets?: readonly ts.SourceFile[];
+    /** The program facts every pass of ONE island round shares
+     * (lowering-facts.ts): the same program and moduleOrder, so a pass that
+     * omits it simply gets a private copy. lowerToIrWithIslands builds one and
+     * hands it to every Lowerer of the round. */
+    facts?: LoweringFacts;
 }
 export declare function lowerToIr(program: ts.Program, entry: ts.SourceFile, moduleOrder: ts.SourceFile[], options?: LowerOptions): LowerResult;
 /** The native namespace type produced by a literal static import() of a
@@ -394,6 +436,10 @@ export declare function dynFallbackType(lowerer: Lowerer, node: ts.Node, t: ts.T
  * const aliases (`const get = process.cwd`), when the module table names its
  * value differently from its member (BuiltinModuleFn.valueName); else null. */
 export declare function builtinValueNameOf(node: ts.Node, lowerer: Lowerer): string | null;
+/** The name V8 gives a function value read from this expression: its own
+ * definition, through parenthesized, rebindable and const bindings and
+ * property reads (`process.cwd`), or the binding an anonymous definition
+ * initializes. Null when the source does not determine it. */
 export declare function jsFuncNameOf(node: ts.Node, lowerer?: Lowerer): string | null;
 /** A loop over an untyped iterable (lowerForOfDyn). `kind` is a local the
  * loop sets once it has opened the iterator: 0 for the dynamic protocol,
@@ -423,6 +469,9 @@ export declare class Lowerer {
         exports: boolean;
         moduleExports: boolean;
     }>;
+    /** JavaScript checker diagnostics preflight admitted under an opinion row
+     * (LoadResult.admittedOpinions): the sites opinionAt answers for. */
+    readonly admittedOpinions: readonly AdmittedOpinion[];
     /** Inline require() calls whose module edge closes a require cycle
      * (LoadResult.inlineRequireCycleCalls). */
     readonly inlineRequireCycleCalls: ReadonlySet<ts.Node>;
@@ -433,6 +482,11 @@ export declare class Lowerer {
      * exact binding discipline as globals/functions. */
     readonly staticCallables: Map<ts.Symbol, StaticCallableProjection>;
     readonly genericFnsBySymbol: Map<ts.Symbol, GenericFnInfo>;
+    /** Temporal-dead-zone flags of module-scope generic ALIASES (`const h =
+     * id`) that code can read before the declaration runs: the alias has no
+     * binding storage of its own, so a read that can come first checks a
+     * flag instead (bindingGenericFnAliasInfoOf). */
+    readonly genericAliasPresence: Map<ts.Symbol, GenericAliasPresence>;
     /** Typed declarations' instances for arguments that keep their own
      * record or array layout (structural-instances.ts). */
     readonly structuralFnInfos: Map<ts.Symbol, GenericFnInfo>;
@@ -549,6 +603,42 @@ export declare class Lowerer {
      * type parameters are bound to `unknown`, so lambdaSignature admits
      * them. */
     readonly erasingLambdas: Set<import("../ts7/ast-node.js").AstNode>;
+    /** Identity comparisons of a generic declaration met while lowering
+     * (directly against the declaration, or through a dynamic value): exact
+     * only while the program holds that declaration as one function object
+     * (checkGenericIdentityPins). */
+    readonly genericIdentityPins: {
+        info: GenericFnInfo;
+        node: ts.Node;
+    }[];
+    /** Identity comparisons whose operands are dynamic values, recorded while
+     * lowering and resolved by checkGenericIdentityPins only when some
+     * generic declaration is held at more than one signature. */
+    readonly dynIdentityComparisons: {
+        node: ts.Node;
+        left: ts.Node;
+        right: ts.Node;
+    }[];
+    /** The value instance each pinned binding holds (`const f: Fn = ident`),
+     * keyed by the binding's declaration: two pins of one generic
+     * declaration at different signatures are separate compiled closures, so
+     * checkGenericIdentityPins refuses to compare them. */
+    readonly pinnedValueInstances: Map<import("../ts7/ast-node.js").AstNode, {
+        info: GenericFnInfo;
+        instance: string;
+    }>;
+    /** Function-vs-function identity comparisons recorded while lowering,
+     * with the closure name each operand lowered to when it is a closure
+     * (an inline instantiation expression names its instance directly). */
+    readonly pinnedIdentityComparisons: {
+        node: ts.Node;
+        left: ts.Node;
+        right: ts.Node;
+        leftInstance: string | undefined;
+        rightInstance: string | undefined;
+    }[];
+    /** The identity comparison check reports once, after all lowering. */
+    genericIdentityCheckDone: boolean;
     /** Function expressions lowered against a fixed target signature with a
      * tuple-typed `arguments` (typed-arguments.ts). */
     readonly typedArgumentsLambdas: Set<import("../ts7/ast-node.js").AstNode>;
@@ -654,9 +744,18 @@ export declare class Lowerer {
     streamPropMutatedSyms: Set<ts.Symbol> | null;
     /** Whether some source reads process.exitCode (processReadsExitCode). */
     readsExitCode: boolean | null;
+    /** Whether some source replaces a process output stream's write method
+     * (programPatchesStdio in builtins/process.ts). */
+    patchesStdio: boolean | null;
+    /** The write-replacement site programPatchesStdio found: the executable
+     * planner refuses it beside Node islands (SC8006). */
+    readonly stdioPatchSites: StdioPatchSite[];
     requestInitPropMutatedSyms: Set<ts.Symbol> | null;
     emitterEventTable: Map<string, EventSig> | null;
     emitterComputedPatterns: ComputedEventPattern[];
+    /** Some site registers a listener under an unrestricted computed name
+     * (lower-event-emitter.ts emitterEvents). */
+    emitterAnyNameListener: boolean;
     /** The EventTarget engine's handleEvent reader was lifted
      * (lower-event-target.ts noteEventListeners). */
     handleEventReader: boolean;
@@ -713,6 +812,19 @@ export declare class Lowerer {
      * prepass. This includes explicit annotations: unchecked TS annotations do
      * not prove that an array property read produced a value. */
     readonly runtimeOptionalBindingTypes: Map<ts.Symbol, IrType>;
+    /** The indexed-read analysis's storage decisions: kept for the coverage
+     * report when --explain-dynamic asks, and written to stderr under
+     * SCRIPTC_DEBUG_RUNTIME_OPTIONAL=1. */
+    readonly runtimeOptionalProvenance: RuntimeOptionalProvenance | null;
+    /** Coverage (--explain-dynamic): the widened slots whose storage holds
+     * an absence the checker's type does not admit, with the reads that
+     * narrow them below it (runtime-optional-report.ts). Empty unless the
+     * report was asked for. */
+    runtimeOptionalNarrowings: readonly RuntimeOptionalNarrowing[];
+    /** JavaScript bindings assigned values outside their declared type
+     * (analyzeJsWidenedBindings): checked-dynamic storage, and reads keep the
+     * stored value instead of narrowing it to the checker's type. */
+    readonly jsWidenedBindings: Set<ts.Symbol>;
     /** A pipeline() function stage's `source` parameter: the IR type of what
      * the pipeline passes it (the previous stage as an async iterable), set
      * while the stage lowers. Parameter typing and `for await` heads read
@@ -890,6 +1002,12 @@ export declare class Lowerer {
     /** The collection types that uses prove for untyped JavaScript bindings,
      * by every identifier naming one (js-collection-types.ts). */
     inferredCollectionTypes: Map<ts.Node, ts.Type> | undefined;
+    /** Partial record assertions (`partial-assertions.ts`): per target shape,
+     * the required fields some asserted literal leaves unwritten. */
+    partialAssertions: Map<string, {
+        missing: ReadonlySet<string>;
+        text: string;
+    }> | undefined;
     /** overload-choice's answers per call, binding and function. */
     readonly dynamicOverloadAnswers: Map<import("../ts7/ast-node.js").AstNode, boolean>;
     /** Error parameters of an error-first callback with a known value in
@@ -934,6 +1052,11 @@ export declare class Lowerer {
      * Reachability lowers inits before the declarations they discover, so
      * these rebuild after the worklist restores historical shape metadata. */
     readonly shapeOrderHelperFinalizers: (() => void)[];
+    /** Whether any lowered function converts a checked-dynamic value into a
+     * closed record, the only conversion that can leave a record holding
+     * undeclared source keys (record-sources.ts). Settled once lowering ends,
+     * before the shape helpers finalize their bodies. */
+    recordSourcesPossible: boolean;
     /** Construction witnesses that choose each shape's enumeration order
      * once lowering settles (key-order-witness.ts). */
     readonly keyOrder: KeyOrderNotes;
@@ -1055,6 +1178,9 @@ export declare class Lowerer {
      * interned here so references under one source-world ABI are the SAME
      * zero-capture closure (see primitiveCtorClosure). */
     readonly primitiveCtorFns: Map<string, string>;
+    /** Whether a compiled source creates primitive wrapper objects
+     * (programCreatesWrappers), computed on first use. */
+    createsWrappers: boolean | undefined;
     /** Builtin-module FUNCTIONS admitted as values by their surface-table
      * entries. The resolved runtime function plus ABI is the identity key,
      * so named imports, namespace reads, CommonJS bindings, and alias chains
@@ -1062,9 +1188,20 @@ export declare class Lowerer {
     readonly builtinCallableValueFns: Map<string, string>;
     /** Each builtin function-value adapter's Node name, for boxed values. */
     readonly builtinCallableValueNames: Map<string, string>;
+    /** Adapters whose name holds on the main thread only
+     * (BuiltinModuleFn.valueNameMainThreadOnly): a Worker boxes them
+     * unnamed, as Node's unwrapped function is. */
+    readonly builtinCallableValueMainThreadNames: Set<string>;
     /** Builtin function values whose `length` differs from their adapter's
      * parameter count (BuiltinModuleFn.valueLength), by adapter name. */
     readonly builtinCallableValueLengths: Map<string, number>;
+    /** Typed builtin adapters with a checked twin (checkedBuiltinValue): the
+     * builtin, its display name and the location the twin is lowered at. */
+    readonly builtinCheckedValues: Map<string, {
+        fn: BuiltinModuleFn;
+        display: string;
+        loc: SrcLoc;
+    }>;
     /** Optional-chain lowering state. While a chain body lowers, the guarded
      * receiver NODE reads as a chainRecv (typed by the narrowed arm) instead
      * of re-lowering, its checker type reads non-nullish (typeOf), and the
@@ -1077,6 +1214,9 @@ export declare class Lowerer {
     readonly neverValued: Set<IrExpr>;
     readonly chainNarrowedType: Map<import("../ts7/ast-node.js").AstNode, ts.Type>;
     readonly chainHandled: Set<import("../ts7/ast-node.js").AstNode>;
+    /** One arm's narrowed value for a spread source while a distributed
+     * union spread lowers that arm (lowerDistributedUnionSpread). */
+    readonly spreadArmOverrides: Map<import("../ts7/ast-node.js").AstNode, IrExpr>;
     /** for-of-over-matchAll bindings whose `.index` reads the companion-index
      * array: binding SYMBOL → the hidden number[] of match start indices plus
      * the hidden cursor holding THIS iteration's position (registered while
@@ -1181,6 +1321,12 @@ export declare class Lowerer {
     readonly globalsByDeclNode: Map<import("../ts7/ast-node.js").AstNode, IrGlobal>;
     readonly globalsList: IrGlobal[];
     readonly npmInitActions: Map<ts.SourceFile, Map<ts.StatementBase, IrStmt[]>>;
+    /** Per-file %init statements of static island imports and re-exports,
+     * by the import or export statement that loads the island module: the
+     * importer's %init header runs them in that statement's place among its
+     * dependencies' %init calls, so the island module evaluates in source
+     * order with the native dependencies around it. */
+    readonly islandImportActions: Map<ts.SourceFile, Map<ts.StatementBase, IrStmt[]>>;
     /** Per-file %init PRELUDE statements for JSON imports: bakeable DATA
      * assignments with no observable evaluation order of their own —
      * prepended by lowerFileInit so the bindings are live before any
@@ -1299,6 +1445,9 @@ export declare class Lowerer {
     }[];
     /** Island handle bindings by symbol (lower-node-island.ts). */
     readonly islandHandleBindings: Map<ts.Symbol, boolean>;
+    /** Names a native module re-exports from an island package, by the
+     * symbol an alias chain reaches (lower-node-island.ts). */
+    readonly islandReexports: Map<ts.Symbol, IslandBinding>;
     /** `instanceof` expressions the island lowering already handles. */
     readonly islandInstanceofHandled: Set<import("../ts7/ast-node.js").AstNode>;
     /** NI-6: the modules shared with Node islands (lower-shared-modules.ts),
@@ -1327,6 +1476,35 @@ export declare class Lowerer {
     }>;
     /** Classes used as ThreadSlots keys: their hierarchies carry a slot word. */
     readonly threadSlotKeys: Set<string>;
+    /** The narrowing conversions that link copies to their sources, by
+     * `${from}:${to}` (record-links.ts). */
+    readonly recordLinks: Map<string, IrRecordLink>;
+    /** Where each of recordLinks' pairs was first converted, by compose
+     * helper name. */
+    readonly recordLinkLocs: Map<string, SrcLoc>;
+    /** The conversion each %rec.string and %rec.primitive helper's calls
+     * replace, by helper name (record-links.ts recordStringCall). */
+    readonly recordStringFallbacks: Map<string, StringFallback>;
+    /** The conversion helpers that build copies of recordLinks' pairs. */
+    readonly recordLinkSites: {
+        link: IrRecordLink;
+        projection: IrFunction;
+    }[];
+    /** Object.prototype methods other than toString called by name on
+     * record types (finalizeRecordLinks checks them against link sources). */
+    readonly recordMethodCalls: {
+        shapeId: string;
+        method: string;
+        loc: SrcLoc;
+    }[];
+    /** Completions of "custom" linked helpers (record-links.ts), which
+     * finalizeRecordLinks runs once the links are known. */
+    readonly linkedHelperFinalizers: (() => void)[];
+    /** Helpers over record types that finalizeRecordLinks completes. */
+    readonly linkedHelpers: LinkedHelper[];
+    /** The JavaScript names of object literals' methods, by lifted function
+     * (function-names.ts). */
+    readonly objectMethodNames: Map<string, string>;
     readonly forkTargetIdByPath: Map<string, number>;
     /** Namespace ModuleBlocks this program lowers, filled by splitFiles:
      * "flattened" — an instantiated namespace whose body joined the file's
@@ -1390,12 +1568,42 @@ export declare class Lowerer {
     readonly unions: UnionRegistry;
     /** Context-free successful type mappings. See TypeMapperCtx.typeMemo. */
     readonly typeMemo: Map<number, IrType>;
-    readonly ambient: string;
-    readonly overridesAmbient: string;
+    /** Successful mappings that read no generic-instantiation scope state
+     * (TypeMapperCtx.typeMemoShared): the same answer in every binding scope
+     * and at the top level. A generic instance's unscoped types land here, so
+     * the next instance — and the top level — answers them without mapping
+     * again. */
+    readonly sharedTypeMemo: Map<number, IrType>;
+    /** Successful mappings per generic binding context (TypeMapperCtx.typeMemoFor):
+     * by the installed typeParamBindings map, then the typeParamTsBindings map
+     * (NO_BINDINGS stands for null). Binding maps are filled before they are
+     * installed and never change while installed, so their identity is the
+     * context. The lowerer owns the memos: they live as long as it does. */
+    private readonly scopedTypeMemos;
+    /** The program facts this Lowerer shares with the other passes of its
+     * island round (lowering-facts.ts). Every field that is a fact lives
+     * there, so a pass that re-derives it cannot disagree with its siblings.
+     * A Lowerer built without LowererMode.facts gets a private copy (tests,
+     * one-off lowerings). */
+    readonly facts: LoweringFacts;
+    /** SCRIPTC_LOWERING_FACTS_VERIFY: the shared provenance memo's hit check,
+     * public so contexts built from this Lowerer (webassembly.ts's hand-made
+     * ctx, property-access.ts passing the Lowerer itself) verify too. */
+    readonly verifySymbolProvenance: ((sym: ts.Symbol, answer: SymbolProvenance) => void) | undefined;
     /** The one mapType context: registries + hooks, assembled in the
      * constructor (typeParamResolver reads the CURRENT instantiation bindings
      * through `this`, so the same ctx serves generic bodies too). */
     readonly typeCtx: TypeMapperCtx;
+    /** The context lastContextMemo answered for. Every mapType call asks for the
+     * current binding context, and a lowering pass stays in one context for
+     * thousands of calls, so the pair of identity checks below is the whole
+     * cost on that path: the two-level lookup only runs when the context
+     * actually changes. */
+    private lastMemoOuter;
+    private lastMemoInner;
+    private lastMemo;
+    /** The memo for the current binding context (scopedTypeMemos). */
+    currentTypeMemo(): Map<number, IrType>;
     readonly stats: LowerStats;
     /** Reachability edge sink: every resolution of
      * a reference to a lowerable body reports its name here — recorded even
@@ -1412,6 +1620,11 @@ export declare class Lowerer {
     /** Whether the program freezes, seals or prevents extensions of untyped
      * values other than fresh literals (noteUntypedIntegrity). */
     untypedIntegrity: boolean;
+    /** A JavaScript source constructs an ArrayBuffer with a maxByteLength,
+     * or reads a member that resizes, grows or detaches a buffer
+     * (buffers.ts, t262-dc §2.4). Sets IrModule.bytesHeadersMutable and arms
+     * the scr_js_buffers views registry in %main. */
+    buffersMutable: boolean;
     readonly liftedFns: IrFunction[];
     /** `for … of` and `for await` loops over untyped iterables, by their
      * generator-kind local (generator-dynamic-dispatch.ts steps the program's
@@ -1430,6 +1643,9 @@ export declare class Lowerer {
     /** web-streams-dyn.ts's answer: whether a JavaScript source names a web
      * stream class; undefined until asked. */
     namesWebStreamClass: boolean | undefined;
+    /** web-streams-dyn.ts's answer: whether a TypeScript source uses a web
+     * stream operation the native streams lack; undefined until asked. */
+    typedWebStreams: boolean | undefined;
     /** The first lifted function of each name (liftedFnNamed), for the
      * liftedFns indexed so far. liftedFns only grows. */
     private readonly liftedFnsByName;
@@ -1491,6 +1707,10 @@ export declare class Lowerer {
      * function called above the declaration statement reads that, never a
      * NULL slot. Filled by collectGlobals. */
     readonly varGlobalEntryInits: Map<ts.SourceFile, IrGlobal[]>;
+    /** Initializer-less JavaScript lets holding a runtime handle or undefined
+     * that a closure captures (inferredEvolvingLetType). Reads inside a nested
+     * function lower as the checked-dynamic value. */
+    readonly closureDynLets: Set<ts.Symbol>;
     /** Import-cycle bindings with an initialization flag, by global id, and
      * the top-level statements declaring them (cycle-initialization.ts). */
     readonly cycleInitFlags: Map<string, CycleInitFlag>;
@@ -1590,6 +1810,8 @@ export declare class Lowerer {
      * refuse and fence exactly as before. Stage S6 demotes the units of
      * committed refusals in "auto" and keeps them refusals in "static-only". */
     readonly tierMode: TierMode;
+    /** LowererMode.runtimeOptionalReport. */
+    readonly runtimeOptionalReport: boolean;
     readonly generalNodeStreams: boolean;
     readonly dynNodeStreams: boolean;
     /** Functions finishModule placed in the dynamic tier (ir/tiers.ts). */
@@ -1750,7 +1972,6 @@ export declare class Lowerer {
      * (decl-origin.ts), by IrModule.declOrigins index. */
     readonly declOrigins: string[];
     private readonly declOriginIds;
-    private readonly packageFileMemo;
     private readonly slotOriginMemo;
     /** The value whose slot coercion is being lowered, while that value is
      * in a package file: union extractions built for it carry the slot's
@@ -1771,22 +1992,34 @@ export declare class Lowerer {
     /** The origin of the package-declared slot a value flows into. */
     slotOriginOf(node: ts.Node): string | null;
     private inPackageFileOf;
-    private declBoundaryMemo;
     get declBoundary(): boolean;
     /** Tracked classes' bag initializers over a typed `this`
      * (class-dynamic-dispatch.ts recordBagInitializers). */
     readonly classBagInitializers: Map<string, IrExpr>;
     constructor(program: ts.Program, entry: ts.SourceFile, moduleOrder: ts.SourceFile[], mode?: LowererMode);
+    /** Whether preflight admitted the checker diagnostic `code` at `node`: a
+     * site in `admittedOpinions` (tsc-codes.ts, JS_OPINIONS) whose span the
+     * node contains. A `widen`/`throw`/`island` row's lowering path is reached
+     * only through this query, so a program that admitted no such site keeps
+     * the IR it has today. */
+    opinionAt(node: ts.Node, code: number): boolean;
+    /** opinionAt's index: admitted sites by file and code (one index per
+     * admitted-opinions list, shared by the round). */
+    private admittedOpinionSites;
     /** A JavaScript file TypeScript type-checks (`// @ts-check`, or the
      * project's `checkJs`). Its JSDoc types are enforced like TypeScript
      * annotations, so its classes use them as a TypeScript file would. */
     checkedJsFile(sf: ts.SourceFile): boolean;
     registerBuiltinErrorClasses(): void;
-    private classProtocols;
     classImplementedProtocol(type: ts.Type): boolean;
     /** A record view a Map or Set answers: it keeps protocol identity but
      * calls the collection's own methods, never a stored member. */
     classCollectionView(type: ts.Type): boolean;
+    /** The round's shared class protocol index (lowering-facts.ts): a pure
+     * analysis of (checker, moduleOrder). With SCRIPTC_LOWERING_FACTS_VERIFY
+     * this Lowerer builds its own index and every answer is compared. */
+    private verifyProtocol;
+    private ownClassProtocols;
     /** Declared class fields may store a DYN value only when its static type
      * is `unknown` or `object` (also with `null` or `undefined`, or an array
      * of those), names checked protocol identity, is an owned runtime
@@ -1796,8 +2029,18 @@ export declare class Lowerer {
      * WeakMap/WeakSet (native weak collections live in checked-dynamic
      * storage, as locals of those types do); `any` fields stay refused. */
     classFieldStoresDyn(type: ts.Type): boolean;
-    /** A stdlib WeakMap or WeakSet, alone or with `null`/`undefined`. */
+    /** A stdlib WeakMap or WeakSet, alone or in a union with `null`/`undefined`
+     * (including the `WeakMap | WeakSet` pair). */
     private weakCollectionType;
+    /** The stdlib collections a type denotes — `WeakMap`, `WeakSet`, or the
+     * two in a union — alone or with `null`/`undefined`, which `nullable`
+     * reports; null for everything else. The predicate behind
+     * weak-collection lowering and the JavaScript value read of one of
+     * their methods, whose receiver may hold either collection. */
+    weakCollectionNamesOf(type: ts.Type): {
+        names: ("WeakMap" | "WeakSet")[];
+        nullable: boolean;
+    } | null;
     /** A type `handle` accepts, alone or with `null`/`undefined`. */
     private stdlibHandleType;
     /** `unknown`, `object`, an array of those, or a union of those with
@@ -1858,6 +2101,10 @@ export declare class Lowerer {
      * program-unique through the file qualifier, and collision-free with
      * user identifiers ('%'). */
     readonly classNamer: (decl: ts.ClassLikeDeclaration) => string;
+    /** True for a class declaration lexically inside a function: only such a
+     * class can take an instantiated owner's name (classNamer), and only there
+     * can localClassInstance's instantiation-stack check answer. */
+    private classInsideFunction;
     /** Follows import aliases to the original declaration's symbol. Every
      * value reference resolves through here, so it doubles as the flush
      * point for deferred collection diagnostics: resolving a reference to a
@@ -2022,11 +2269,29 @@ export declare class Lowerer {
      * undefined arm before any body reads it; the declaration lowers its
      * initializer as the matching absence probe. */
     analyzeGuardedRecordReadGlobals(parts: FileParts[]): void;
+    /** A JavaScript `let`/`var` binding assigned a value its declared type
+     * does not admit (`let t = parseInt(s); if (isNaN(t)) t = undefined`):
+     * TypeScript types the binding from its initializer and reports the
+     * assignment (TS2322), which JavaScript files relax, so the binding takes
+     * checked-dynamic storage and holds whatever the program stores. JSDoc
+     * type annotations keep their declared storage.
+     *
+     * A set accessor's unannotated parameter joins them: a JavaScript setter's
+     * parameter is whatever the caller passes, and `paramShape` gives the slot
+     * checked-dynamic storage. The checker types it from the twin getter's
+     * return when one exists (`set value(next) { this.stored = next; }` beside
+     * `get value() { return this.stored; }` types `next` as the getter's type),
+     * and otherwise reports TS7032; reading the parameter at the inferred type
+     * would check the caller's value back into it and throw where Node stores
+     * it as is. A JSDoc `@param` type keeps its declared storage, exactly like
+     * a variable's `@type`. */
+    analyzeJsWidenedBindings(parts: FileParts[]): void;
     analyzeRuntimeOptionalArrayReads(parts: FileParts[]): void;
     run(): LowerResult;
     /** Final retention, pruning, and module assembly shared by ordinary emit
-     * and the retained reachability worklist. */
-    finishModule(functions: IrFunction[]): LowerResult;
+     * and the retained reachability worklist. `library` is true for a native
+     * library's emit, whose runtime has no builtin-statics unit. */
+    finishModule(functions: IrFunction[], library?: boolean): LowerResult;
     /** True when `t` (recursively) names a class instance type with no
      * registered ClassInfo — the shape of a JS class whose collection fenced.
      * Used by run()'s global pruning; shapes/unions recurse with a seen-set
@@ -2054,6 +2319,19 @@ export declare class Lowerer {
      * remainder do; an externally-gated emit pass leaves the counting to the
      * remainder (the declaration was never reached). */
     countsSkips(): boolean;
+    /** LIBRARY mode: the unit the root name `name` seeds, resolved through
+     * the entry module's export table. A direct `export function f` and every
+     * facade that names it (`export { f }`, `export { f as g }`,
+     * `export { f } from "./m"`, `export * from "./m"`) reach the same
+     * declaration, and the unit is whatever the declaration's own module
+     * qualified it as — the entry's bare name or another module's `%mN.` tag.
+     * Memoized: the four emit passes and the result's export map read one
+     * answer. Null when the name is not an export of a compiled function
+     * (SC4002/SC4004/SC4007 report it). */
+    libExportUnit(name: string): string | null;
+    /** One answer per root name: a pass builds its own Lowerer, and the
+     * signatures this reads are collected before any body is lowered. */
+    private readonly libExportUnits;
     /** Reachable emit: computes the set of body names the program's entry
      * reaches and retains each body IR as it lowers. Seeds are the per-file
      * init bodies (top-level statements always run); edges fire from
@@ -2067,10 +2345,15 @@ export declare class Lowerer {
      * demand-driven) and lifted lambdas lower inline with their enclosing
      * body; both fire edges through the same hooks and are not units
      * themselves. */
-    emitReachable(extraRoots?: readonly string[]): {
+    emitReachable(extraRoots?: readonly string[], unitStore?: UnitStore | null): {
         reachable: Set<string>;
         result: LowerResult;
     };
+    /** What the steps before the worklist settled for a top-level
+     * declaration, as text without source positions (unit-reuse.ts): a
+     * function's signature, a class's layout and the signatures of its
+     * methods and statics, and the globals of a variable statement. */
+    private declarationFacts;
     /** The lowerer's side of a recorded wave (unit-journal.ts).
      * `lowerUnitBody` lowers a unit as reachable emit does. */
     private waveHost;
@@ -2214,6 +2497,10 @@ export declare class Lowerer {
      * `sym`, when given, picks the wording: surface declared only by the
      * adopted @types/node is blamed at @types/node. */
     noLowering(surface: string, node: ts.Node, hint?: string, sym?: ts.Symbol | null, reason?: string): never;
+    /** A read of a Node 24 global the native runtime does not implement
+     * (host-globals.ts): refusing is the honest answer, and the reason id
+     * lets a Node island run the module instead. */
+    hostGlobalFence(name: string, node: ts.Node): never;
     /** The declaration-side refusal of a stdlib-global snapshot read as a
      * VALUE (stdlibGlobalAliasDecl): report once, at the declaration's name,
      * naming the type the program asked the compiler to hold when it has a
@@ -2328,6 +2615,9 @@ export declare class Lowerer {
         messageListeners: number;
     };
     irTypeOf(node: ts.Node): IrType;
+    /** Whether `type`, or an array element type inside it, is a union with
+     * both a function arm and an array arm. */
+    private mixesFunctionsWithArrays;
     /** Exact-shape enforcement (SC2002). Records are monomorphic structs, so
      * everywhere a value flows into a typed slot (call arg, initializer,
      * assignment, field, return) the shapes must MATCH — or width-coerce:
@@ -2442,7 +2732,7 @@ export declare class Lowerer {
     recordUnionRouteHelper(source: IrType & {
         kind: "record";
     }, toId: string, loc: SrcLoc): string | null;
-    unionRetagHelper(fromId: string, toId: string, loc: SrcLoc, trappable?: ReadonlySet<number>): string | null;
+    unionRetagHelper(fromId: string, toId: string, loc: SrcLoc, trappable?: ReadonlySet<number>, classRoutes?: ReadonlyMap<number, readonly UnionClassRoute[]>): string | null;
     narrowedArmHelper(fromId: string, target: IrType, loc: SrcLoc, message?: string): string | null;
     checkedNarrowCall(helper: string, value: IrExpr, type: IrType, loc: SrcLoc): IrExpr;
     deferredReadHelper(fromId: string, target: IrType, loc: SrcLoc): string | null;
@@ -2529,6 +2819,24 @@ export declare class Lowerer {
      * undefined, which the void slot drops. Units are pure literals, so
      * nothing evaluates; unit-typed non-literals keep the fences. */
     lowerReturnValue(node: ts.Expression): IrExpr | null;
+    /** A fresh object literal returned into a RECORD result whose ordinary
+     * construction cannot reach that result: not a thenable, so it is built
+     * at the result type like a synchronous return. An unannotated method
+     * inside a contextually typed literal is checked against the CONTEXTUAL
+     * signature's result while its own return type stays the literal's
+     * inferred (narrower) record — `ToolDefinition<Schema, Details>` methods
+     * returning `{ content, details }`. Building at the contextual type
+     * would then coerce that wider record into the declared result and
+     * refuse; the result slot is the layout. A literal that declares `then`
+     * is awaited instead, and a literal whose contextual build does convert
+     * keeps the ordinary lowering, so no convertible value changes. */
+    private returnsFreshRecord;
+    /** A parenthesized fresh object literal that does not declare `then`. */
+    private isFreshRecordLiteral;
+    /** One arm of a returned conditional: a fresh object literal whose
+     * ordinary construction cannot reach the declared result (see
+     * returnsFreshRecord). */
+    private freshRecordLiteralInto;
     /** An array literal or a `new Map(...)`, `new Set(...)` or `new
      * Array(...)` of the builtins: a fresh collection, never a thenable, so
      * an async return takes the declared result type as its construction
@@ -2538,6 +2846,12 @@ export declare class Lowerer {
     /** A fresh JS object literal returned into a checked-native (dyn) result,
      * which lowers straight into that storage. */
     private returnsLiteralIntoDyn;
+    /** Whether `node`'s TS type is a `Promise<never>` (the throw-only async
+     * function's declared result): the promise can never settle, so the value
+     * it would resolve to is unreachable. The IR keeps `Promise<never>` as a
+     * promise with a void payload, exactly like `Promise<void>`, so the TS
+     * payload type is what separates the two. */
+    private promisePayloadIsNever;
     /** The value of `return <e>` (already lowered untyped) in an async or
      * void context: a promise flattens through the returned-promise await,
      * everything else converts into the declared result. */
@@ -2842,7 +3156,7 @@ export declare class Lowerer {
      * call runs for its effects (it throws or exits), and the expression ends
      * in an unreachable trap instead of producing a value. The result reads an
      * uninitialized hidden local that control never reaches. */
-    divergentValue(call: IrExpr, expected: IrType): IrExpr;
+    divergentValue(call: IrExpr, expected: IrType, message?: string): IrExpr;
     /** A function-scope local bound to NO ts.Symbol — the hidden ABI slot of a
      * defaulted parameter (the parameter's symbol binds to the separately-
      * declared body local; nothing in the source can name this one). */
@@ -2953,6 +3267,27 @@ export declare class Lowerer {
      * declare hits the SC2020-family fence). The file half of every
      * supported-surface provenance check. */
     readonly isStdlibFile: (sf: ts.SourceFile) => boolean;
+    /** provenanceOf's answers (type-mapper.ts's SymbolProvenance), keyed by
+     * symbol. A symbol's declarations are fixed for one loaded program, and
+     * the mapper asks on every object type it maps, so the round shares one
+     * map (lowering-facts.ts). */
+    get symbolProvenance(): Map<ts.Symbol, SymbolProvenance>;
+    /** SCRIPTC_LOWERING_FACTS_VERIFY: the shared provenance memo answered, so
+     * recompute it and fail on a disagreement (lowering-facts.ts). */
+    private verifySymbolProvenanceAnswer;
+    /** Whether the file holds declarations of an explicitly mapped external
+     * type surface (coverage's --external-types) or of the declaration-typed
+     * boundary's generated types. Both are fixed for the program, and the
+     * mapper asks per type (lowering-facts.ts keeps the answer). */
+    readonly isExternalTypeFile: (sf: ts.SourceFile) => boolean;
+    /** tsgoPath(resolve(sf.fileName)): the path spelling the module tables
+     * key by. A source file's path cannot change while the program lowers. */
+    readonly pathOf: (sf: ts.SourceFile) => string;
+    /** Whether values of `type` are island handles (boundary.ts's
+     * isForeignType; the answers and their invalidation live in
+     * lowering-facts.ts). The type mapper asks this on every mapType call,
+     * memo hits included. */
+    private foreignType;
     nodeTypesOnlySymbol(sym: ts.Symbol | null | undefined): boolean;
     readonly isNpmFile: (sf: ts.SourceFile) => boolean;
     npmPackageOf(type: ts.Type): string | null;
@@ -3103,12 +3438,19 @@ export declare class Lowerer {
         member: string;
     }, loc: SrcLoc): IrExpr | null;
     lowerNativeCallableValue(fn: BuiltinModuleFn, display: string, loc: SrcLoc): IrExpr | null;
+    /** A builtin function value about to become untyped: its checked twin
+     * when the builtin names its parameters (checkedNativeCallableValue), so
+     * untyped callers meet Node's argument validation. Typed slots keep the
+     * typed adapter. */
+    checkedBuiltinValue(expr: IrExpr): IrExpr;
     /** The name and length a builtin function's adapter boxes under: the ones
-     * Node's function carries (`[Function: randomUUID]`). Empty for any other
-     * value. */
+     * Node's function carries (`[Function: randomUUID]`), with the main-thread
+     * qualifier of a name a Worker does not carry (`process.cwd`). Empty for
+     * any other value. */
     builtinFunctionIdentity(expr: IrExpr): {
         fnName?: string;
         fnLength?: number;
+        fnNameMainThreadOnly?: true;
     };
     isBuiltinCallableValue(expr: IrExpr): boolean;
     lowerBuiltinModuleCall(expr: ts.CallExpression, bi: {