@scriptc/compiler 0.4.5 → 0.4.6

package/dist/frontend/type-mapper.js

@@ -3,7 +3,7 @@ import { keyedHelperName } from "./lowering/stable-names.js";
 import { mockCallRecordType, mockContextType } from "./mock-shapes.js";
 import * as ts from "./ts7/adapter.js";
 import { bodyReadsArguments } from "./arguments-usage.js";
-import { BYTES_ELEMENT_NAME, arrayOf, isDynTypedRefType, BOOL, bytesOf, canConvertToDyn, canDynCheckTo, CHILD_T, CRYPTOHASH_T, CRYPTOHMAC_T, DATE_T, DYN, F64, funcOf, isSupportedArrayElem, isSupportedIndexValue, isSupportedMapKey, isSupportedMapValue, isSupportedSetElem, iterableArmsElem, isUnitType, mapOf, NULL_T, PROCSTREAM_T, RUNTIME_EMITTER_CLASS, RUNTIME_ERROR_CLASSES, RUNTIME_STREAM_CLASSES, ZLIB_STREAM_MODES, setOf, STRING, SYMBOL_T, typeEquals, typeKey, maybePromiseUnionArmsOk, unionContainerArmsOk, UNDEFINED_T, VOID, } from "../ir/ir.js";
+import { BYTES_ELEMENT_NAME, arrayOf, isDynTypedRefType, BOOL, bytesOf, canBoxFuncIntoDyn, canConvertToDyn, canDynCheckTo, CHILD_T, CRYPTOHASH_T, CRYPTOHMAC_T, DATE_T, DYN, FOREIGN, F64, funcOf, isSupportedArrayElem, isSupportedIndexValue, isSupportedMapKey, isSupportedMapValue, isSupportedSetElem, iterableArmsElem, isUnitType, mapOf, NULL_T, PROCSTREAM_T, RUNTIME_EMITTER_CLASS, RUNTIME_ERROR_CLASSES, RUNTIME_STREAM_CLASSES, ZLIB_STREAM_MODES, setOf, STRING, SYMBOL_T, typeEquals, typeKey, maybePromiseUnionArmsOk, unionContainerArmsOk, UNDEFINED_T, VOID, } from "../ir/ir.js";
 import { BIGINT_T, KEY_ORDER_FIELD } from "../ir/ir.js";
 import { literalValues } from "./literal-values.js";
 import { remapUnionDiscriminant } from "./union-discriminants.js";
@@ -244,8 +244,31 @@ export class ShapeRegistry {
      * writer after all priority candidates have closed. */
     derivedDeclaredOrderFinalizers = [];
     currentDeclaredOrderPriority = [0, 0];
+    /** The declared-order candidates and the attached names the registry
+     * holds, counted as they are added (journalSizes). */
+    candidateCount = 0;
+    extendedCount = 0;
     /** All interned shapes in first-seen order. */
     shapes = [];
+    /** The sizes of the registry's tables, which only grow while shapes are
+     * interned (unit-journal.ts). */
+    journalSizes() {
+        return [
+            this.revision,
+            this.shapes.length,
+            this.byKey.size,
+            this.byId.size,
+            this.keyedNameKeys.size,
+            this.declaredOrderPriority.size,
+            this.declaredOrderCandidates.size,
+            this.candidateCount,
+            this.derivedDeclaredOrderFinalizers.length,
+            this.recIds.size,
+            this.pendingRec.size,
+            this.extendedNames.size,
+            this.extendedCount,
+        ];
+    }
     /** ts.Types currently being mapped — a BACK-REFERENCE to one of these is
      * the recursive knot (`interface TreeNode { children: TreeNode[] }`):
      * mapType answers a NAMED RECURSIVE SHAPE (recursiveRef) whose fields
@@ -291,6 +314,7 @@ export class ShapeRegistry {
     adoptDeclaredOrder(shape, declaredOrder) {
         if (declaredOrder === undefined)
             return;
+        this.candidateCount++;
         const candidates = this.declaredOrderCandidates.get(shape.id);
         const candidate = { order: declaredOrder, priority: this.currentDeclaredOrderPriority };
         if (candidates)
@@ -424,6 +448,7 @@ export class ShapeRegistry {
             this.byId.set(id, shape);
             this.shapes.push(shape);
             if (declaredOrder !== undefined) {
+                this.candidateCount++;
                 this.declaredOrderCandidates.set(id, [
                     { order: declaredOrder, priority: this.currentDeclaredOrderPriority },
                 ]);
@@ -482,6 +507,7 @@ export class ShapeRegistry {
         if (fresh.length === 0)
             return;
         shape.fields = [...shape.fields, ...fresh].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+        this.extendedCount += fresh.length;
         this.extendedNames.set(shapeId, [
             ...(this.extendedNames.get(shapeId) ?? []),
             ...fresh.map((f) => f.name),
@@ -551,6 +577,99 @@ export class UnionRegistry {
     armTags = new Map();
     /** All interned unions in first-seen order. */
     unions = [];
+    /** The sizes of the tables recursive unions change, which no unit
+     * record carries (unit-journal.ts). */
+    journalSizes() {
+        return [this.revision, this.recIds.size, this.pendingRec.size];
+    }
+    /** The interned unions as a table unit records carry (unit-journal.ts).
+     * An entry is a union's definition; applying it interns the union under
+     * the key its arms give. A unit that adds a recursive union changes
+     * journalSizes, so the unions past a unit's start are interned ones. */
+    journalTable() {
+        return {
+            name: "unions",
+            size: () => this.unions.length,
+            entries: (from) => {
+                const out = [];
+                for (const def of this.unions.slice(from)) {
+                    // JSON writes a number that is not finite as null.
+                    const text = JSON.stringify(def);
+                    if (/[:,[]null\b/.test(text))
+                        return null;
+                    out.push(text);
+                }
+                return out;
+            },
+            apply: (entries) => {
+                for (const entry of entries) {
+                    const def = JSON.parse(entry);
+                    const key = unionKey(def.arms, def.discriminant);
+                    if (this.byKey.has(key))
+                        continue;
+                    if (keyedHelperName(this, "u", key, "") !== def.id)
+                        throw new InternalCompilerError(`union record ${def.id} does not match its arms`);
+                    this.byKey.set(key, def.id);
+                    this.byId.set(def.id, def);
+                    this.unions.push(def);
+                }
+            },
+            truncate: (from) => {
+                while (this.unions.length > from) {
+                    const def = this.unions.pop();
+                    this.byKey.delete(unionKey(def.arms, def.discriminant));
+                    this.byId.delete(def.id);
+                    this.keyedNameKeys.delete(def.id);
+                }
+            },
+            contents: () => {
+                // A recursive placeholder still pending fills in place when its
+                // outer frame completes, which changes journalSizes.
+                const texts = [];
+                const indexes = new Map();
+                const differs = (index) => {
+                    const text = texts[index] ?? null;
+                    return (text !== null &&
+                        index < this.unions.length &&
+                        JSON.stringify(this.unions[index]) !== text);
+                };
+                const held = {
+                    extend: () => {
+                        for (let index = texts.length; index < this.unions.length; index++) {
+                            const def = this.unions[index];
+                            texts.push(this.pendingRec.has(def.id) ? null : JSON.stringify(def));
+                            indexes.set(def.id, index);
+                        }
+                    },
+                    changed: () => {
+                        for (let index = 0; index < texts.length; index++)
+                            if (differs(index))
+                                return this.unions[index].id;
+                        return null;
+                    },
+                    changedAmong: (keys) => {
+                        for (const key of keys) {
+                            const index = indexes.get(key);
+                            if (index !== undefined && differs(index))
+                                return key;
+                        }
+                        return null;
+                    },
+                    refresh: (keys) => {
+                        for (const key of keys) {
+                            const index = indexes.get(key);
+                            if (index !== undefined &&
+                                index < this.unions.length &&
+                                (texts[index] ?? null) !== null)
+                                texts[index] = JSON.stringify(this.unions[index]);
+                        }
+                    },
+                };
+                held.extend();
+                return held;
+            },
+        };
+    }
     /** ts.Types currently being mapped — a back-reference to one is the
      * recursive knot passing through a union (`type Tree = Leaf | Branch`
      * whose Branch arm carries `Tree[]`, the optional field `a?: A` of a
@@ -590,6 +709,11 @@ export class UnionRegistry {
         const id = this.recIds.get(t);
         return id !== undefined && this.pendingRec.has(id);
     }
+    /** True when `unionId` is a recursive placeholder whose arms are not
+     * known yet (its outer frame is still mapping, or failed). */
+    isPendingPlaceholder(unionId) {
+        return this.pendingRec.has(unionId);
+    }
     /** Completes a recursive placeholder with its canonical arm list and
      * registers the structural key (first writer wins, like shapes). */
     finalizeRecursive(t, arms, discriminant) {
@@ -612,7 +736,7 @@ export class UnionRegistry {
     }
     /** Interns canonical arms and discriminator cases, returning their unionId. */
     intern(arms, discriminant) {
-        const key = JSON.stringify([arms.map(typeKey), discriminant]);
+        const key = unionKey(arms, discriminant);
         let id = this.byKey.get(key);
         if (id === undefined) {
             id = keyedHelperName(this, "u", key, "");
@@ -654,6 +778,10 @@ export class UnionRegistry {
         return tags.get(typeKey(arm))?.find((tag) => typeEquals(def.arms[tag], arm)) ?? -1;
     }
 }
+/** The key UnionRegistry interns a union's arms and discriminant under. */
+function unionKey(arms, discriminant) {
+    return JSON.stringify([arms.map(typeKey), discriminant]);
+}
 /** Human-readable rendering of an IrType for diagnostics (records expand to
  * their canonical field list, unions to their arms; `checker.typeToString`
  * can't — it never sees IR types). Bound the traversal as well as its output:
@@ -837,6 +965,8 @@ export function formatIrType(t, shapes, unions, seen = new Set()) {
                 return append("bigint");
             case "stats":
                 return append("Stats");
+            case "bigintStats":
+                return append("BigIntStats");
             case "fileHandle":
                 return append("FileHandle");
             case "dir":
@@ -1164,6 +1294,23 @@ export function isLegacyUrlSymbol(symbol, ctx) {
  * (errno, dlopen, priority) and SignalConstants, and the fallback's twins:
  * the runtime's checked-dynamic constants object, whose members vary by
  * platform. */
+/** True for node:path's platform-specific namespaces ("path/posix",
+ * "path/win32"). Their values are the path module object, so they map to
+ * the checked-dynamic module value (see pathModuleValue in
+ * lowering/lower-builtin-values.ts), not to a module declaration. */
+export function isPathPlatformNamespaceId(moduleId) {
+    return moduleId === "builtin:path/posix" || moduleId === "builtin:path/win32";
+}
+/** @types/node's `PlatformPath` interface (module "path"): the declared type
+ * of `path.posix`/`path.win32`. Its values are the path module object. */
+function isPlatformPathType(type, ctx) {
+    const sym = type.getSymbol();
+    if (sym === undefined || ts.symbolName(sym) !== "PlatformPath")
+        return false;
+    return sym.declarations.some((decl) => ts.isInterfaceDeclaration(decl) &&
+        ctx.isStdlibFile(ts.getSourceFileOfNode(decl)) &&
+        isDeclaredInAmbientModule(decl, "path"));
+}
 export function isOsConstantsType(type, ctx) {
     return (isOsConstantsSymbol(type.getAliasSymbol(), ctx, true) ||
         isOsConstantsSymbol(type.getSymbol(), ctx, true));
@@ -1431,7 +1578,46 @@ export function isFetchHandleType(type, ctx) {
     }
     return handle;
 }
+/** The array type a class declared `extends Array` maps to (its base type,
+ * `T[]`), or null for every other class. */
+function arrayClassBaseType(classDecl, instance, ctx) {
+    const heritage = classDecl.heritageClauses?.nodes.find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword)?.types?.nodes[0];
+    if (heritage === undefined || !ts.isIdentifier(heritage.expression))
+        return null;
+    if (heritage.expression.text !== "Array")
+        return null;
+    // The polymorphic `this` type of the class names the class's own type.
+    const symbol = instance.getSymbol();
+    const declared = (instance.flags & ts.TypeFlags.TypeParameter) !== 0 && symbol !== undefined
+        ? ctx.checker.getDeclaredTypeOfSymbol(symbol)
+        : instance;
+    if ((declared.flags & ts.TypeFlags.Object) === 0)
+        return null;
+    const target = declared.isTypeReference() ? (declared.getTarget() ?? declared) : declared;
+    const bases = ctx.checker.getBaseTypes(target);
+    const base = bases[0];
+    if (base === undefined || !ctx.checker.isArrayType(base))
+        return null;
+    const mapped = mapType(base, ctx);
+    if (mapped?.kind === "array")
+        return mapped;
+    // `extends Array` in JavaScript reads `any[]`: dyn elements (the class's
+    // arrayClassBase).
+    return isJsSourceFile(ts.getSourceFileOfNode(classDecl)) ? { kind: "array", elem: DYN } : null;
+}
 export function mapType(type, ctx) {
+    const shadow = ctx.canonShadow;
+    if (shadow === undefined || mapTypeDepth !== 0)
+        return mapTypeEntry(type, ctx);
+    // Shadow mode observes every successful top-level mapping, including the
+    // intrinsic primitives, local class values and memo hits that return
+    // before the mapping proper.
+    const mapped = mapTypeEntry(type, ctx);
+    if (mapped !== null)
+        shadow(type, mapped, ctx);
+    return mapped;
+}
+function mapTypeEntry(type, ctx) {
     if (mapTypeDepth >= MAP_TYPE_MAX_DEPTH)
         return null;
     // These intrinsic domains cannot depend on generic bindings, declaration
@@ -1446,6 +1632,8 @@ export function mapType(type, ctx) {
         if (flags & (ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral))
             return BOOL;
     }
+    if (ctx.foreignType !== undefined && ctx.foreignType(type))
+        return FOREIGN;
     const localValue = ctx.localClassValue?.(type);
     if (localValue) {
         contextResolutions++;
@@ -1456,8 +1644,8 @@ export function mapType(type, ctx) {
     const memoizable = typeId !== undefined && (ctx.canMemoizeType?.() ?? true);
     // An empty literal's type maps to the empty record as an unreduced union's
     // arm (emptyLiteralArm) and to the checked-dynamic value elsewhere: the two
-    // answers keep separate memo entries.
-    const memoKey = memoizable ? `${ctx.emptyLiteralArm ? 1 : 0}:${typeId}` : null;
+    // answers keep separate memo entries. Type ids are non-negative integers.
+    const memoKey = memoizable ? typeId * 2 + (ctx.emptyLiteralArm ? 1 : 0) : null;
     if (memoKey !== null) {
         const memo = ctx.typeMemo?.get(memoKey);
         if (memo !== undefined)
@@ -1478,10 +1666,39 @@ export function mapType(type, ctx) {
                 throw e;
             mapped = null;
         }
+        // A generic alias the body spells over its own type parameters (`x as
+        // Catalog<G, P>`) stays symbolic in the checker; when that form does not
+        // map, the instance's concrete instantiation of the same alias does.
+        if (mapped === null && ctx.resolveBoundAliasTs) {
+            const concrete = ctx.resolveBoundAliasTs(type);
+            if (concrete !== null && concrete !== type) {
+                mapped = mapType(concrete, ctx);
+                if (mapped !== null)
+                    contextResolutions++;
+            }
+        }
+        // Localized failure: a type that failed at a committed slot maps to its
+        // lenient form. It counts as a context resolution so neither it nor a
+        // type containing it is memoized: the strict form may map elsewhere.
+        if (mapped === null && ctx.degradedType) {
+            const lenient = ctx.degradedType(type);
+            if (lenient !== null) {
+                mapped = lenient;
+                contextResolutions++;
+            }
+        }
+        // Push-down (stage L3): in a lenient mapping, the smallest failing
+        // component is the checked dynamic.
+        if (mapped === null && ctx.lenient === true && !topLevel) {
+            mapped = DYN;
+            contextResolutions++;
+            ctx.onLenientPiece?.(type);
+        }
         if (mapped !== null &&
             memoKey !== null &&
             topLevel &&
             contextResolutions === sensitivityAtEntry &&
+            ctx.erasingSignature === undefined &&
             (ctx.canMemoizeType?.() ?? true)) {
             ctx.typeMemo?.set(memoKey, mapped);
         }
@@ -1543,8 +1760,16 @@ function mapTypeInner(type, ctx) {
     }
     {
         const moduleId = ctx.moduleNamespaceId?.(type) ?? null;
-        if (moduleId !== null)
+        // node:path's platform namespaces (`path.posix`, `path.win32`) are
+        // ordinary objects at run time: the same module object the whole
+        // namespace lowers to (pathModuleValue). Typing them as a module
+        // namespace declaration made every value read a static type with no
+        // value lowering; the checked-dynamic module value is the honest
+        // type, and a union with a plain record arm collapses onto it.
+        if (moduleId !== null && !isPathPlatformNamespaceId(moduleId))
             return { kind: "moduleNs", moduleId };
+        if (moduleId !== null)
+            return DYN;
     }
     // A TypeScript object literal that spreads a checked-dynamic value
     // (`{ ...requestOptions, path, timeout }`): its keys are the source's
@@ -1590,6 +1815,11 @@ function mapTypeInner(type, ctx) {
             isDeclaredInAmbientModule(decl, "child_process"))) {
         return { kind: "object", className: "%Error" };
     }
+    // @types/node declares the platform-path namespace value as the
+    // `PlatformPath` interface of module "path"; its values ARE the path
+    // module object (the checked-dynamic module value).
+    if (isPlatformPathType(type, ctx))
+        return DYN;
     if (isOsConstantsType(type, ctx) || isLegacyUrlType(type, ctx))
         return DYN;
     // The WebAssembly API's values have the checked-dynamic representation, so
@@ -1627,7 +1857,8 @@ function mapTypeInner(type, ctx) {
         !checker.getCallSignatures(type).some((sig) => sig === ctx.erasingSignature) &&
         !ERASURE_KEPT_CONTAINERS.has(ts.symbolNameOf(type.getSymbol()) ?? "") &&
         mentionsErasedTypeParam(type, ctx, 0)) {
-        contextResolutions++;
+        if (!ctx.erasedMember || ctx.erasedMember.outerConsulted)
+            contextResolutions++;
         return DYN;
     }
     // Readonly<C> over a program class (Object.freeze's result type) is the
@@ -1638,7 +1869,8 @@ function mapTypeInner(type, ctx) {
     if (resolveTypeParam && type.flags & ts.TypeFlags.TypeParameter) {
         const bound = resolveTypeParam(type);
         if (bound) {
-            contextResolutions++;
+            if (!ctx.erasedMember?.own.has(type))
+                contextResolutions++;
             return bound;
         }
     }
@@ -1693,6 +1925,11 @@ function mapTypeInner(type, ctx) {
                     return viaConditional;
                 }
             }
+            const viaDistribution = mapDistributedConditional(type, ctx);
+            if (viaDistribution !== null) {
+                contextResolutions++;
+                return viaDistribution;
+            }
         }
     }
     const widened = checker.getBaseTypeOfLiteralType(type);
@@ -2196,6 +2433,13 @@ function mapTypeInner(type, ctx) {
                 return viaMixin;
             }
         }
+        // A class declared `extends Array` (frontend/lowering/builtins/
+        // array-classes.ts): its instances are arrays of the base's elements.
+        {
+            const arrayBase = arrayClassBaseType(classDecl, widened, ctx);
+            if (arrayBase !== null)
+                return arrayBase;
+        }
         if (classExprNeedsContext(classDecl)) {
             const local = ctx.localClassInstance?.(classDecl, widened);
             if (local)
@@ -2555,6 +2799,21 @@ function mapTypeInner(type, ctx) {
     // stdio and env values. Keep it checked-dynamic for native normalization.
     if (isStdlibInterface("SpawnOptions"))
         return DYN;
+    // util.inspect as a value (a custom inspect method's third parameter is
+    // `typeof inspect`): the runtime's inspect function, called through the
+    // checked-dynamic boundary.
+    if (psym !== undefined &&
+        ts.symbolName(psym) === "inspect" &&
+        psym.declarations.some((d) => ts.isFunctionDeclaration(d) &&
+            ctx.isStdlibFile(ts.getSourceFileOfNode(d)) &&
+            isDeclaredInAmbientModule(d, "util")))
+        return DYN;
+    // util.inspect's options bag, which inspect and formatWithOptions read
+    // at run time (its sorted option can be a comparator function), and the
+    // options custom inspect functions receive.
+    if ((isStdlibInterface("InspectOptions") || isStdlibInterface("InspectOptionsStylized")) &&
+        psym.declarations.some((d) => ts.isInterfaceDeclaration(d) && isDeclaredInAmbientModule(d, "util")))
+        return DYN;
     // dns.LookupAllOptions (`all: true`, the overload whose callback takes
     // an address list): a lookup option bag dns.lookup reads at run time.
     // It rides checked-dynamic storage, so the lookup function type that
@@ -2608,14 +2867,25 @@ function mapTypeInner(type, ctx) {
             return null;
         return genResultRecord(elem, VOID, ctx.shapes, ctx.unions);
     }
-    // node:net's SocketAddress and BlockList: native handles (scr_net.c)
-    // whose getters and methods dispatch through the handle.
+    // node:net's SocketAddress and BlockList (scr_net.c) and node:util's
+    // MIMEType and MIMEParams (scr_mime.c): native handles whose getters and
+    // methods dispatch through the handle.
     if (((psym !== undefined && ts.symbolName(psym) === "SocketAddress") ||
-        (psym !== undefined && ts.symbolName(psym) === "BlockList")) &&
+        (psym !== undefined && ts.symbolName(psym) === "BlockList") ||
+        (psym !== undefined && ts.symbolName(psym) === "MIMEType") ||
+        (psym !== undefined && ts.symbolName(psym) === "MIMEParams")) &&
         psym.declarations.some((d) => (ts.isClassDeclaration(d) || ts.isInterfaceDeclaration(d)) &&
             ctx.isStdlibFile(ts.getSourceFileOfNode(d)))) {
         return DYN;
     }
+    // The functions node:util's debounce and throttle return
+    // (scr_util_timing.c): native functions with their own members and
+    // getters.
+    if (psym !== undefined &&
+        (ts.symbolName(psym) === "DebouncedFunction" || ts.symbolName(psym) === "ThrottledFunction") &&
+        psym.declarations.some((d) => ts.isInterfaceDeclaration(d) && ctx.isStdlibFile(ts.getSourceFileOfNode(d)))) {
+        return DYN;
+    }
     // WebCrypto: the crypto global and its subtle object are dynamic
     // objects, CryptoKey values are native handles (scr_webcrypto.c), and
     // the algorithm dictionaries the methods take and keys report are plain
@@ -2874,6 +3144,16 @@ function mapTypeInner(type, ctx) {
             ctx.isStdlibFile(ts.getSourceFileOfNode(d)))) {
         return { kind: "stats" };
     }
+    // fs.BigIntStats: the SAME snapshot handle under Node's bigint member
+    // table (`statSync(p, { bigint: true })`). Declared by @types/node as
+    // `class BigIntStats` in "fs"; the fallback declarations keep the class
+    // shape too. Provenance-checked like Stats.
+    if (psym !== undefined &&
+        ts.symbolName(psym) === "BigIntStats" &&
+        psym.declarations.some((d) => (ts.isInterfaceDeclaration(d) || ts.isClassDeclaration(d)) &&
+            ctx.isStdlibFile(ts.getSourceFileOfNode(d)))) {
+        return { kind: "bigintStats" };
+    }
     // Capacity snapshots and options keep their live object representation
     // across numeric/BigInt overloads, runtime options, and callbacks.
     if (((psym !== undefined && ts.symbolName(psym) === "StatsFs") ||
@@ -4198,6 +4478,8 @@ function mapTypeInner(type, ctx) {
                 parts.some((part) => (part.flags & nullish) === 0 &&
                     !checker.isNeverType(part) &&
                     !isEmptyObjectLiteralType(part, ctx));
+            let neverConditionalPart = false;
+            let undefinedPart;
             for (const part of parts) {
                 if (hasArrayPart && emptyTuple(part))
                     continue;
@@ -4205,6 +4487,12 @@ function mapTypeInner(type, ctx) {
                 // distributed union. They have no inhabitants and no runtime tag.
                 if (checker.isNeverType(part))
                     continue;
+                // A conditional over a bound parameter whose every member selects
+                // `never` contributes no arm either.
+                if (distributedConditionalParts(part, ctx)?.length === 0) {
+                    neverConditionalPart = true;
+                    continue;
+                }
                 // A `void` PART is inhabited only by undefined (`Promise<void> |
                 // void` return types, `string | void`): it becomes the undefinedT
                 // unit arm, exactly like an undefined part — the value either
@@ -4212,6 +4500,7 @@ function mapTypeInner(type, ctx) {
                 // void stays VOID (the return-position mapping above).
                 if (part.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) {
                     byKey.set(typeKey(UNDEFINED_T), UNDEFINED_T);
+                    undefinedPart ??= part;
                     continue;
                 }
                 if (part.flags & ts.TypeFlags.Null) {
@@ -4258,6 +4547,11 @@ function mapTypeInner(type, ctx) {
             const arms = [...byKey.values()];
             if (arms.length === 0)
                 return F64; // same unreachable placeholder as standalone never
+            // `Cond<T> | undefined` whose conditional selects never for the
+            // instance's binding is the plain `undefined` the concrete
+            // instantiation's optional member has.
+            if (neverConditionalPart && arms.length === 1 && undefinedPart !== undefined)
+                return mapType(undefinedPart, ctx);
             // A single surviving UNIT arm cannot stand alone (degenerate — the
             // checker collapsed everything else away); anything else single is
             // just that type. A single arm UNDER A MINTED PLACEHOLDER cannot
@@ -4296,19 +4590,42 @@ function mapTypeInner(type, ctx) {
                 !unions.recursivePending(widened)) {
                 return DYN;
             }
-            if (arms.some((a) => a.kind === "void" ||
+            // SEVERAL PROMISE ARMS are ONE: `Promise<A> | Promise<B>` is
+            // `Promise<A | B>`. A promise arm's tag IS the `instanceof Promise`
+            // test, so JavaScript cannot tell the arms apart at run time (both
+            // answer true, both `await` to a value of their payload), and the
+            // merged payload union is exactly what `await` produces either way.
+            // The merge happens here, in the union the checker gave us, so every
+            // use site (a declaration slot, an argument, an `await`, `.then`)
+            // sees the same one-promise-arm layout; the conversion of a
+            // `Promise<A>` value into it is the checked promise-payload widening
+            // (promisePayloadWidens / promiseWiden). A payload that cannot ride
+            // that union (a promise of a promise, a regex or generator payload)
+            // keeps the whole union fenced.
+            const mergedArms = mergePromiseArms(arms, ctx);
+            if (mergedArms === null)
+                return null;
+            // Promise arms were the whole union (`Promise<void> | Promise<undefined>`
+            // merges to the plain `Promise<void>`): a one-armed union has no
+            // representation and needs none — the merge left the arm alone.
+            if (mergedArms.length === 1) {
+                if (unions.recursivePending(widened))
+                    return null;
+                return mergedArms[0];
+            }
+            if (mergedArms.some((a) => a.kind === "void" ||
                 a.kind === "union" ||
                 a.kind === "dyn" ||
                 // A generator arm only comes from an Iterable<T> (an optional
                 // one keeps its unit arms beside the iterable union's).
-                (a.kind === "generator" && iterableArmsElem(arms) === null)) ||
-                !maybePromiseUnionOk(parts, arms, ctx)) {
+                (a.kind === "generator" && iterableArmsElem(mergedArms) === null)) ||
+                !maybePromiseUnionOk(parts, mergedArms, ctx)) {
                 return null;
             }
-            arms.sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
-            const discriminant = unionDiscriminant(recordParts, arms, ctx) ??
+            mergedArms.sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+            const discriminant = unionDiscriminant(recordParts, mergedArms, ctx) ??
                 (substitutedUnions.length === 1
-                    ? remapUnionDiscriminant(substitutedUnions[0], arms)
+                    ? remapUnionDiscriminant(substitutedUnions[0], mergedArms)
                     : undefined);
             if (unions.recursivePending(widened)) {
                 // The knot closed through this union. A frame that resolved
@@ -4318,9 +4635,12 @@ function mapTypeInner(type, ctx) {
                 // recursive generic-open unions stay fenced.
                 if (contextResolutions !== sensitivityAtEntry)
                     return null;
-                return { kind: "union", unionId: unions.finalizeRecursive(widened, arms, discriminant) };
+                return {
+                    kind: "union",
+                    unionId: unions.finalizeRecursive(widened, mergedArms, discriminant),
+                };
             }
-            return { kind: "union", unionId: unions.intern(arms, discriminant) };
+            return { kind: "union", unionId: unions.intern(mergedArms, discriminant) };
         }
         finally {
             unions.inProgress.delete(widened);
@@ -4401,10 +4721,12 @@ function mapCallSignature(sig, ctx) {
         // A parameter a TypeScript program types `any` takes whatever the
         // caller passes: the checked-dynamic slot, as an `any`-typed binding
         // already is (dynFallbackType). Declaration files keep their paths.
-        // Only function declarations, spelled function types and lambda
-        // parameters whose default is the only source of their type (`(n =
-        // lookup() ?? 5) => ...` with an `any` lookup): other lambdas and
-        // methods in object literals keep their existing checked-dynamic story.
+        // Only function declarations, spelled function types, method and call
+        // signatures of interfaces and type literals (`execute(params: any):
+        // Promise<R>`), and lambda parameters whose default is the only source
+        // of their type (`(n = lookup() ?? 5) => ...` with an `any` lookup):
+        // other lambdas and methods in object literals keep their existing
+        // checked-dynamic story.
         if (!pt &&
             !rest &&
             decl !== undefined &&
@@ -4412,6 +4734,8 @@ function mapCallSignature(sig, ctx) {
             decl.parent !== undefined &&
             (ts.isFunctionDeclaration(decl.parent) ||
                 ts.isFunctionTypeNode(decl.parent) ||
+                ts.isMethodSignatureDeclaration(decl.parent) ||
+                ts.isCallSignatureDeclaration(decl.parent) ||
                 ((ts.isArrowFunction(decl.parent) || ts.isFunctionExpression(decl.parent)) &&
                     decl.initializer !== undefined &&
                     decl.type === undefined &&
@@ -4474,8 +4798,18 @@ function mapCallSignature(sig, ctx) {
             pt = jsOpenObjectType(decl, pt, ctx.shapes, ctx.unions);
         // Belt and braces for non-strict type worlds: an optional param's
         // ABI slot is always the undefined-armed union (strictNullChecks
-        // already spells it that way; arm it here if the world didn't).
-        if (optional && pt && pt.kind !== "void" && pt.kind !== "dyn") {
+        // already spells it that way; arm it here if the world didn't). A
+        // back-reference to a union still being mapped (`options?: { then?:
+        // (ctx: Sub) => void }` where Sub extends the interface declaring the
+        // method) is a recursive placeholder with no arms yet; when the checker
+        // spelled the parameter `X | undefined`, the placeholder receives that
+        // undefined arm when its frame finishes.
+        const pendingOptional = pt?.kind === "union" &&
+            ctx.unions.isPendingPlaceholder(pt.unionId) &&
+            ts
+                .constituentTypes(checker.getTypeOfSymbol(p))
+                .some((part) => (part.flags & ts.TypeFlags.Undefined) !== 0);
+        if (optional && pt && pt.kind !== "void" && pt.kind !== "dyn" && !pendingOptional) {
             const armed = withUndefinedArm(pt, ctx.unions);
             if (!armed)
                 return null;
@@ -5278,6 +5612,121 @@ function mapGenericIndexedAccess(type, ctx) {
     arms.sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
     return { kind: "union", unionId: ctx.unions.intern(arms) };
 }
+/** A distributive conditional (`T extends "a" ? A : T extends "b" ? B :
+ * never`, its check type a naked type parameter) over a parameter the
+ * instance binds: evaluated once per member of the binding (`"a" | "b"`,
+ * or the open `"a" | (string & {})` spelling), as the checker distributes
+ * it. Answers the non-never results (empty when every member selects
+ * never, so an optional member of that type holds only undefined, as in
+ * the concrete instantiation), or null when the conditional is another
+ * shape or a member does not evaluate. */
+function distributedConditionalParts(type, ctx) {
+    const { checker, resolveTypeParamTs } = ctx;
+    if (!resolveTypeParamTs || !type.isConditionalType())
+        return null;
+    const checkType = type.getCheckType();
+    if (!checkType || !(checkType.flags & ts.TypeFlags.TypeParameter))
+        return null;
+    const symbol = checkType.getSymbol();
+    const bound = resolveTypeParamTs(checkType);
+    if (!symbol || !bound)
+        return null;
+    // The answer depends on the instance's binding: a mapping that consults
+    // it, even one that drops an all-never part, is not context-free.
+    contextResolutions++;
+    const parts = [];
+    for (const member of bound.isUnionType() ? ts.constituentTypes(bound) : [bound]) {
+        // `string & {}` (the open-union spelling) extends exactly what `string`
+        // extends: the empty object adds nothing to a primitive.
+        const emptyObject = (part) => (part.flags & ts.TypeFlags.Object) !== 0 &&
+            checker.getPropertiesOfType(part).length === 0 &&
+            checker.getIndexInfosOfType(part).length === 0 &&
+            checker.getCallSignatures(part).length === 0 &&
+            checker.getConstructSignatures(part).length === 0;
+        const primitive = member.isIntersectionType()
+            ? ts.constituentTypes(member).filter((part) => !emptyObject(part))
+            : [member];
+        if (primitive.length !== 1)
+            return null;
+        const evaluated = evalMappedTemplate(type, new Map(), new Map([[symbol, primitive[0]]]), ctx);
+        if (!evaluated)
+            return null;
+        if (checker.isNeverType(evaluated))
+            continue;
+        if (!parts.includes(evaluated))
+            parts.push(evaluated);
+    }
+    return parts;
+}
+/** A unit-only type once its conditionals over bound parameters are
+ * distributed: `Cond<T> | undefined` where every member of T's binding
+ * selects never (the optional member's type in a generic body). */
+function neverConditionalUnitOnly(t, ctx) {
+    const UNIT = ts.TypeFlags.Undefined | ts.TypeFlags.Void | ts.TypeFlags.Null;
+    if (!t.isUnionType())
+        return false;
+    let conditional = false;
+    for (const part of ts.constituentTypes(t)) {
+        if ((part.flags & UNIT) !== 0)
+            continue;
+        if (distributedConditionalParts(part, ctx)?.length !== 0)
+            return false;
+        conditional = true;
+    }
+    return conditional;
+}
+/** mapType of a distributed conditional (distributedConditionalParts): the
+ * union of its members' results, as the concrete conditional's union maps
+ * them. An `unknown` or `any` result absorbs the rest (the checker's union
+ * is that type), as does a result that maps to the checked-dynamic value
+ * (`{}`, `object`, `Object`: the checker's union of one with a concrete
+ * result is the top type), and `undefined` and `null` results are the unit
+ * arms. Null when it does not distribute, when a result does not map, when
+ * every member selects never (the enclosing union drops such a part), or
+ * when only units remain. */
+function mapDistributedConditional(type, ctx) {
+    const parts = distributedConditionalParts(type, ctx);
+    if (!parts || parts.length === 0)
+        return null;
+    const top = parts.find((part) => (part.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0);
+    if (top !== undefined)
+        return mapType(top, ctx);
+    const arms = [];
+    for (const part of parts) {
+        if (part.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) {
+            if (!arms.some((a) => typeEquals(a, UNDEFINED_T)))
+                arms.push(UNDEFINED_T);
+            continue;
+        }
+        if (part.flags & ts.TypeFlags.Null) {
+            if (!arms.some((a) => typeEquals(a, NULL_T)))
+                arms.push(NULL_T);
+            continue;
+        }
+        const mapped = mapType(part, ctx);
+        if (!mapped)
+            return null;
+        // A top-type result (`{}`, `object`, `Object`): the checker's union with
+        // a concrete result is the top type itself, so the member is
+        // checked-dynamic. A `dyn` arm would be invalid union IR (SC9001).
+        if (mapped.kind === "dyn")
+            return DYN;
+        const members = mapped.kind === "union" ? (ctx.unions.get(mapped.unionId)?.arms ?? null) : [mapped];
+        if (!members)
+            return null;
+        for (const arm of members)
+            if (!arms.some((a) => typeEquals(a, arm)))
+                arms.push(arm);
+    }
+    if (arms.every(isUnitType))
+        return null;
+    if (arms.length === 1)
+        return arms[0];
+    if (!unionContainerArmsOk(arms))
+        return null;
+    arms.sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+    return { kind: "union", unionId: ctx.unions.intern(arms) };
+}
 /** `keyof T extends never ? A : B` over a bound record T (the lib's
  * Object.entries element spelling): decided by whether the binding has any
  * key. */
@@ -6297,7 +6746,9 @@ function isTypeOnlyNamespace(d) {
         isTypeOnlyNamespace(statement));
 }
 function packageTypeFile(sf, ctx) {
-    return (sf.isDeclarationFile && /[\\/]node_modules[\\/]/.test(sf.fileName) && !ctx.isStdlibFile(sf));
+    return (sf.isDeclarationFile &&
+        (/[\\/]node_modules[\\/]/.test(sf.fileName) || ctx.isExperimentalFile?.(sf) === true) &&
+        !ctx.isStdlibFile(sf));
 }
 /** The record path's provenance fence. Declared shapes (object literals,
  * interfaces, type literals) must come from user code or an explicitly
@@ -6411,10 +6862,23 @@ export function erasedGenericMemberType(t, ctx) {
     const sig = sigs[0];
     const own = new Set(sig.getTypeParameters());
     const outer = ctx.resolveTypeParam;
+    // Resolving only the member's own parameters does not make the erasure
+    // context-sensitive, so a recursive record holding a generic method
+    // (`interface Sub extends Base { send<T>(m: Msg<T>): void }` reached
+    // from Base) still closes its knot. Consulting an enclosing binding does.
+    const erasedMember = { own, outerConsulted: false };
     const erased = mapType(t, {
         ...ctx,
         erasingSignature: sig,
-        resolveTypeParam: (param) => (own.has(param) ? DYN : (outer?.(param) ?? null)),
+        erasedMember,
+        resolveTypeParam: (param) => {
+            if (own.has(param))
+                return DYN;
+            if (outer === undefined)
+                return null;
+            erasedMember.outerConsulted = true;
+            return outer(param);
+        },
     });
     return erased?.kind === "func" ? erased : undefined;
 }
@@ -7306,7 +7770,8 @@ function mapRecordTypeInner(widened, ctx) {
             // absent-field idiom — and `{ p: undefined }` spellings): the
             // unit-only union. The runtime value is the interned unit, JSON
             // omits the undefined arm exactly like an omitted optional.
-            if (pt?.kind === "void" && isUnitOnlyTsType(fieldTs, ctx.resolveTypeParam))
+            if (pt?.kind === "void" &&
+                (isUnitOnlyTsType(fieldTs, ctx.resolveTypeParam) || neverConditionalUnitOnly(fieldTs, ctx)))
                 pt = unitOnlyUnion(ctx.unions);
             if (pt !== null && isUnitOnlyIr(pt, ctx) && jsObjectLiteralProperty(p))
                 pt = DYN;
@@ -7402,6 +7867,12 @@ function dynSubsumableUnionArm(arm, ctx) {
         // `string | URL | Request`, fetch's own input type under @types/node.
         case "url":
             return true;
+        // A function the checked-dynamic tree can box (each parameter checks
+        // in, the result converts out) is held by reference there, and
+        // `typeof x === "function"` narrows it back out: `Progress | AbortSignal`
+        // beside fetch's handles.
+        case "func":
+            return canBoxFuncIntoDyn(arm, (id) => ctx.shapes.get(id), (id) => ctx.unions.get(id));
         case "record":
         case "array":
         // `T | Promise<T>` with T bound to `unknown`: the checked-dynamic value
@@ -7451,6 +7922,84 @@ function maybePromiseUnionOk(parts, arms, ctx) {
         return false;
     return maybePromiseThenableArm(parts, ctx) === null;
 }
+/** Merge the promise arms of one union into a single `Promise<A | B>`
+ * (mapTypeInner's union rule): JavaScript-wise the arms are
+ * indistinguishable — `instanceof Promise` answers true for both, and
+ * `await` settles to the payload union — so the merged arm is the same
+ * value in the same slot. Payloads join like union arms: a `void` payload
+ * becomes the undefined unit, a payload that is already a union flattens,
+ * and a checked-dynamic payload (`Promise<unknown>`) absorbs the arms the
+ * checked-dynamic representation holds faithfully (dynSubsumableUnionArm).
+ * Null keeps the whole union fenced: a promise-of-a-promise payload, a
+ * payload with no union home (regex, generator), or a dyn payload beside an
+ * arm whose semantics would degrade. */
+function mergePromiseArms(arms, ctx) {
+    let promiseArms = 0;
+    for (const arm of arms)
+        if (arm.kind === "promise")
+            promiseArms++;
+    if (promiseArms < 2)
+        return arms;
+    const payloads = [];
+    let dynamic = false;
+    for (const arm of arms) {
+        if (arm.kind !== "promise")
+            continue;
+        const inner = arm.inner;
+        if (inner.kind === "void") {
+            payloads.push(UNDEFINED_T);
+            continue;
+        }
+        if (inner.kind === "dyn") {
+            dynamic = true;
+            continue;
+        }
+        if (inner.kind === "union") {
+            const substituted = ctx.unions.get(inner.unionId);
+            if (!substituted?.arms.length)
+                return null;
+            payloads.push(...substituted.arms);
+            continue;
+        }
+        payloads.push(inner);
+    }
+    if (dynamic) {
+        if (!payloads.every((arm) => dynSubsumableUnionArm(arm, ctx)))
+            return null;
+        payloads.length = 0;
+        payloads.push(DYN);
+    }
+    const byKey = new Map();
+    for (const arm of payloads) {
+        // A promise payload has no arm home beside the others: `await` of the
+        // merged promise would adopt it as a thenable, which no union tag does.
+        if (arm.kind === "promise")
+            return null;
+        byKey.set(typeKey(arm), arm);
+    }
+    const payload = [...byKey.values()];
+    if (payload.length === 0)
+        return null;
+    // Every arm is the undefined unit: the promise never settles a value,
+    // exactly `Promise<void>`.
+    if (payload.every((arm) => arm.kind === "undefinedT"))
+        payload.length = 0;
+    // One payload arm is that arm itself (a regex or a promise payload has a
+    // promise slot but no union arm); a JOINT payload is a union, so its arms
+    // need union homes.
+    const inner = payload.length === 0
+        ? VOID
+        : payload.length === 1
+            ? payload[0]
+            : payload.every((arm) => armHasUnionHome(arm))
+                ? {
+                    kind: "union",
+                    unionId: ctx.unions.intern([...payload].sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1))),
+                }
+                : null;
+    const merged = inner === null ? null : { kind: "promise", inner };
+    return merged === null ? null : [...arms.filter((arm) => arm.kind !== "promise"), merged];
+}
 /** The first non-promise constituent of a promise-armed union whose type
  * has a `then` member (a thenable data arm), or null. */
 function maybePromiseThenableArm(parts, ctx) {
@@ -7587,7 +8136,7 @@ export function describeComponentBlocker(widened, ctx) {
         }
         const promiseArms = mappedArms.filter(({ mapped }) => mapped?.kind === "promise");
         if (promiseArms.length > 1) {
-            return `the union shape is supported, but it has several promise arms ('${text(promiseArms[0].p)}' and '${text(promiseArms[1].p)}'), and a compiled union holds at most one (the union tag is the 'instanceof Promise' test)`;
+            return `the union shape is supported, but its promise arms ('${text(promiseArms[0].p)}' and '${text(promiseArms[1].p)}') do not merge into one promise (their payloads have no common union layout)`;
         }
         if (promiseArms.length === 1 && dataArms.length > 1) {
             const callable = mappedArms.find(({ mapped }) => mapped?.kind === "func");