@scriptc/compiler 0.4.8 → 0.4.9

package/dist/frontend/type-mapper.js

@@ -4,7 +4,7 @@ import { contentDigest } from "./lowering/unit-journal.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, 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 { 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, sortArms, 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";
@@ -299,7 +299,11 @@ export class ShapeRegistry {
     keyOf(fields, tuple, indexValue) {
         return ((tuple ? "tuple!" : "") +
             (indexValue ? `idx<${typeKey(indexValue)}>!` : "") +
-            JSON.stringify(fields.map((f) => [f.name, typeKey(f.type)])));
+            // An absentable optional dyn field carries a third element in the
+            // key; every other entry keeps the historical two-element spelling,
+            // so a shape without one hashes exactly as before (zero-cost
+            // identity for programs that use no optional `unknown`/`any`).
+            JSON.stringify(fields.map((f) => f.optional === true ? [f.name, typeKey(f.type), 1] : [f.name, typeKey(f.type)])));
     }
     /** Runs one lowering unit under its historical emit-order rank. Shape
      * ids remain demand-assigned; only first-seen declaration-order metadata
@@ -1336,6 +1340,15 @@ function genChannels(yieldTs, retTs, nextTs, ctx) {
  * fallback for it. */
 const MAP_TYPE_MAX_DEPTH = 64;
 let mapTypeDepth = 0;
+/** The overload sets whose signatures the equal-modulo-union-order arm is
+ * mapping, outermost first. Mapping a signature maps its parameter and return
+ * types, which can name the set again — `interface R { (x: number): R; (x:
+ * string): R }` declared in a package, which isOverloadedCallableMemberType
+ * does not claim. Each level would map every signature again, so a recursive
+ * set expands exponentially until MAP_TYPE_MAX_DEPTH cuts every branch off. A
+ * set already being expanded is refused instead (null, as every other
+ * unmappable type), and the slot reports the overload diagnostic. */
+const overloadExpansion = [];
 /** Bumped whenever mapType resolves a type through CONTEXT-SENSITIVE or
  * collection-sensitive hooks (a generic body's type parameter, a mixin
  * instantiation, a generic class instance) — mappings that can make the same
@@ -2347,7 +2360,7 @@ function mapTypeInner(type, ctx) {
             }
             if (hasNum && hasStr) {
                 const arms = [F64, STRING];
-                arms.sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+                sortArms(arms);
                 return { kind: "union", unionId: unions.intern(arms) };
             }
             return hasStr ? STRING : F64;
@@ -2982,7 +2995,9 @@ function mapTypeInner(type, ctx) {
     // in a declaration file, which recordProvenanceOk rightly refuses for
     // lib type worlds. Map it manually with the executor's own scriptc
     // field shapes (plain-value resolve — () => void for Promise<void> —
-    // and the Error-pinned reject), so both the destructured and the
+    // and the reject the promise's own reason representation picks: Error
+    // for a typed payload, the checked-dynamic value for a promise whose
+    // settled value is unknown), so both the destructured and the
     // record-holding binding forms compile. User-declared literals with
     // these member names keep the ordinary record path (their declarations
     // are not in declaration files).
@@ -3005,7 +3020,7 @@ function mapTypeInner(type, ctx) {
                             name: "reject",
                             type: {
                                 kind: "func",
-                                params: [{ kind: "object", className: "%Error" }],
+                                params: [inner.kind === "dyn" ? DYN : { kind: "object", className: "%Error" }],
                                 ret: VOID,
                             },
                         },
@@ -3302,7 +3317,8 @@ function mapTypeInner(type, ctx) {
         isStdlibInterface("SharedArrayBuffer") ||
         isStdlibInterface("PropertyDescriptor") ||
         isStdlibInterface("ProcessVersions") ||
-        isStdlibInterface("ProcessRelease"))
+        isStdlibInterface("ProcessRelease") ||
+        isStdlibInterface("ProcessReport"))
         return DYN;
     if (Object.values(BYTES_ELEMENT_NAME).some((name) => isStdlibInterface(`${name}Constructor`)))
         return DYN;
@@ -3965,7 +3981,7 @@ function mapTypeInner(type, ctx) {
         const optStr = withUndefinedArm(STRING, ctx.unions);
         const optNum = withUndefinedArm(F64, ctx.unions);
         const optBool = withUndefinedArm(BOOL, ctx.unions);
-        const stdioArms = [arrayOf(STRING), STRING, UNDEFINED_T].sort((a, b) => typeKey(a) < typeKey(b) ? -1 : 1);
+        const stdioArms = sortArms([arrayOf(STRING), STRING, UNDEFINED_T]);
         const stdio = { kind: "union", unionId: ctx.unions.intern(stdioArms) };
         if (!optStr || !optNum || !optBool)
             return null;
@@ -3998,19 +4014,25 @@ function mapTypeInner(type, ctx) {
         const optBool = withUndefinedArm(BOOL, ctx.unions);
         const stdioArms = [arrayOf(STRING), STRING, UNDEFINED_T].sort((a, b) => typeKey(a) < typeKey(b) ? -1 : 1);
         const stdio = { kind: "union", unionId: ctx.unions.intern(stdioArms) };
-        if (!optStr || !optNum || !optBool)
+        // `env?: NodeJS.ProcessEnv` — the same record the inline literal builds
+        // its [k,v,...] pairs from. A runtime record can carry a replacement
+        // environment, so the member maps rather than staying literal-only.
+        const envProp = ctx.checker.getPropertyOfType(type, "env");
+        const env = envProp ? mapType(ctx.checker.getTypeOfSymbol(envProp), ctx) : null;
+        if (!optStr || !optNum || !optBool || !env || env.kind !== "union")
             return null;
         return {
             kind: "record",
             shapeId: ctx.shapes.intern([
                 { name: "cwd", type: optStr },
                 { name: "encoding", type: STRING },
+                { name: "env", type: env },
                 { name: "input", type: optStr },
                 { name: "shell", type: optBool },
                 { name: "stdio", type: stdio },
                 { name: "timeout", type: optNum },
                 { name: "windowsHide", type: optBool },
-            ], false, undefined, ["encoding", "cwd", "input", "timeout", "shell", "stdio", "windowsHide"]),
+            ], false, undefined, ["encoding", "cwd", "env", "input", "timeout", "shell", "stdio", "windowsHide"]),
         };
     }
     if (isStdlibInterface("AddressInfo")) {
@@ -4212,7 +4234,7 @@ function mapTypeInner(type, ctx) {
             if (!t || t.kind !== "string")
                 return null;
         }
-        const shellArms = [NULL_T, STRING].sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+        const shellArms = sortArms([NULL_T, STRING]);
         const shell = { kind: "union", unionId: ctx.unions.intern(shellArms) };
         return {
             kind: "record",
@@ -4463,7 +4485,7 @@ function mapTypeInner(type, ctx) {
     if (isStdlibInterface("NetworkInterfaceInfoIPv4") ||
         isStdlibInterface("NetworkInterfaceInfoIPv6")) {
         const v6 = ts.symbolName(psym) === "NetworkInterfaceInfoIPv6";
-        const cidrArms = [NULL_T, STRING].sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+        const cidrArms = sortArms([NULL_T, STRING]);
         const cidr = { kind: "union", unionId: ctx.unions.intern(cidrArms) };
         const scopeid = v6 ? F64 : withUndefinedArm(F64, ctx.unions);
         if (!scopeid)
@@ -4544,9 +4566,18 @@ function mapTypeInner(type, ctx) {
     // the plain-func mapping below (historic behavior: the properties drop
     // from the type).
     if (widened.isIntersectionType() && checker.getConstructSignatures(widened).length === 0) {
-        const hybrid = mapHybridCallableIntersection(widened, ctx);
-        if (hybrid)
-            return hybrid;
+        // node:test's `Mock<F>` (`F & { mock: MockFunctionContext<F> }`) keeps
+        // its hybrid `%call` record: the `mock` member is the runner's live
+        // call log, which the mock lowering builds and mutates, not data the
+        // closure's own-property table could carry yet.
+        if (isMockHybridIntersection(widened, ctx)) {
+            const hybrid = mapHybridCallableRecord(widened, ctx);
+            if (hybrid)
+                return hybrid;
+        }
+        const callable = mapCallableIntersection(widened, ctx);
+        if (callable)
+            return callable;
         // Recursive and Symbol-keyed callable objects need their complete live
         // property table; dropping those members into a plain closure loses data.
         if (checker.getCallSignatures(widened).length > 0 &&
@@ -4600,6 +4631,30 @@ function mapTypeInner(type, ctx) {
         if (erased !== undefined)
             return erased;
     }
+    // An overload set whose signatures are the SAME once union members are
+    // read as a set is one signature: `typeof fetch` merges lib.dom's
+    // `(input: URL | RequestInfo, ...)` with undici's `(input: string |
+    // Request | URL, ...)`, which spell the same members in a different
+    // order. Union interning keeps arm order, so the two mapped signatures
+    // differ by unionId alone; a set whose signatures genuinely differ (a
+    // rest parameter elsewhere, another result type) keeps its fence.
+    // Erasable sets (isOverloadedCallableMemberType) already have their one
+    // compiled signature and keep it: this arm is for the sets no erasure
+    // reaches, such as a merged library declaration.
+    // The signatures are mapped LAZILY, and only while the set is not already
+    // being mapped higher up the stack: mapping a signature maps its parameter
+    // and return types, so a recursive result type (`interface R { (x: number):
+    // R; (x: string): R }` in a package declaration) re-enters the set and
+    // would otherwise map every signature again at every level — exponential
+    // until MAP_TYPE_MAX_DEPTH cuts each branch, stalling the build instead of
+    // reporting the refusal (see overloadSetBeingExpanded).
+    if (callSigs.length > 1 &&
+        !isOverloadedCallableMemberType(widened, checker) &&
+        !overloadSetBeingExpanded(widened)) {
+        const agreed = mapAgreeingOverloadSignature(callSigs, widened, ctx);
+        if (agreed !== null)
+            return agreed;
+    }
     if (callSigs.length === 1)
         return mapCallSignature(callSigs[0], ctx);
     // Records: object types whose members are all data properties (shorthand
@@ -5008,7 +5063,7 @@ function mapTypeInner(type, ctx) {
                 !maybePromiseUnionOk(parts, mergedArms, ctx)) {
                 return null;
             }
-            mergedArms.sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+            sortArms(mergedArms);
             const discriminant = unionDiscriminant(recordParts, mergedArms, ctx) ??
                 (substitutedUnions.length === 1
                     ? remapUnionDiscriminant(substitutedUnions[0], mergedArms)
@@ -5107,6 +5162,89 @@ function isStdlibStreamWriteOverloads(sigs, ctx) {
             ctx.isStdlibFile(ts.getSourceFileOfNode(decl)));
     });
 }
+/** An overloaded set's identity for the expansion guard. A generic set
+ * re-enters under a FRESH type object at each level (`interface R<T> { (x:
+ * T): R<T[]> }`), so the declaration a type instantiation names stands in for
+ * the type; an anonymous type literal is interned by the checker, so the type
+ * itself is its own identity. */
+function overloadSetKey(type) {
+    return type.getAliasSymbol() ?? type.getSymbol() ?? type;
+}
+/** True when `type` is already being expanded, or a chain of sets is
+ * expanding that led back to it: mapping the set again can only repeat the
+ * mapping that is already in progress, so the set has no single compiled
+ * signature (see overloadExpansion). */
+function overloadSetBeingExpanded(type) {
+    return overloadExpansion.includes(overloadSetKey(type));
+}
+/** The one signature `sigs` agree on, or null when they disagree or any of
+ * them does not map. Signatures are mapped lazily — a set whose first two
+ * signatures disagree costs two mappings — and the set stays on the expansion
+ * stack throughout, so a signature naming the set again refuses it. */
+function mapAgreeingOverloadSignature(sigs, set, ctx) {
+    overloadExpansion.push(overloadSetKey(set));
+    try {
+        const first = mapCallSignature(sigs[0], ctx);
+        if (first === null)
+            return null;
+        for (let i = 1; i < sigs.length; i++) {
+            const next = mapCallSignature(sigs[i], ctx);
+            if (next === null || !sameTypeUpToUnionOrder(first, next, ctx, 0))
+                return null;
+        }
+        return first;
+    }
+    finally {
+        overloadExpansion.pop();
+    }
+}
+/** Two mapped types that agree once every union's arms are read as a SET.
+ * `URL | RequestInfo` and `string | Request | URL` name the same members
+ * but intern as different unions (arm order is part of a union's identity),
+ * so the overload dedupe below cannot use typeKey or typeEquals. Records and
+ * handles compare by identity; the composite forms recurse. */
+function sameTypeUpToUnionOrder(a, b, ctx, depth) {
+    if (typeKey(a) === typeKey(b))
+        return true;
+    if (depth > 16)
+        return false;
+    if (a.kind === "union" && b.kind === "union") {
+        const armsA = ctx.unions.get(a.unionId)?.arms ?? [];
+        const armsB = ctx.unions.get(b.unionId)?.arms ?? [];
+        if (armsA.length !== armsB.length)
+            return false;
+        const rest = [...armsB];
+        for (const arm of armsA) {
+            const at = rest.findIndex((candidate) => sameTypeUpToUnionOrder(arm, candidate, ctx, depth + 1));
+            if (at < 0)
+                return false;
+            rest.splice(at, 1);
+        }
+        return true;
+    }
+    switch (a.kind) {
+        case "array":
+            return b.kind === "array" && sameTypeUpToUnionOrder(a.elem, b.elem, ctx, depth + 1);
+        case "promise":
+            return b.kind === "promise" && sameTypeUpToUnionOrder(a.inner, b.inner, ctx, depth + 1);
+        case "map":
+            return (b.kind === "map" &&
+                sameTypeUpToUnionOrder(a.key, b.key, ctx, depth + 1) &&
+                sameTypeUpToUnionOrder(a.value, b.value, ctx, depth + 1));
+        case "set":
+            return b.kind === "set" && sameTypeUpToUnionOrder(a.elem, b.elem, ctx, depth + 1);
+        case "func":
+            return (b.kind === "func" &&
+                a.params.length === b.params.length &&
+                (a.rest ?? false) === (b.rest ?? false) &&
+                (a.restAbi ?? null) === (b.restAbi ?? null) &&
+                (a.argumentsAll ?? false) === (b.argumentsAll ?? false) &&
+                a.params.every((p, i) => sameTypeUpToUnionOrder(p, b.params[i], ctx, depth + 1)) &&
+                sameTypeUpToUnionOrder(a.ret, b.ret, ctx, depth + 1));
+        default:
+            return false;
+    }
+}
 function mapCallSignature(sig, ctx) {
     const { checker } = ctx;
     if (sig.getTypeParameters().length && ctx.erasingSignature !== sig)
@@ -5158,27 +5296,36 @@ function mapCallSignature(sig, ctx) {
         let pt = mapType(checker.getTypeOfSymbol(p), 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, method and call
+        // already is (dynFallbackType). This holds in every declaration world
+        // the program or a package writes — program source and `.d.ts`
+        // declaration files alike, since a published declaration is the same
+        // contract as the implementation source. The standard library keeps
+        // its existing paths: its ambient signatures are the language's own
+        // surface, so admitting them would change the static shape of every
+        // typed program that calls one (`PropertyDescriptor.get`'s `this: any`,
+        // `map`'s `thisArg?: any`), which the zero-cost gate forbids. 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.
+        // Promise<R>`), ambient class methods, 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 &&
             ts.isParameter(decl) &&
             decl.parent !== undefined &&
+            !(ts.getSourceFileOfNode(decl).isDeclarationFile &&
+                ctx.isStdlibFile(ts.getSourceFileOfNode(decl))) &&
             (ts.isFunctionDeclaration(decl.parent) ||
                 ts.isFunctionTypeNode(decl.parent) ||
                 ts.isMethodSignatureDeclaration(decl.parent) ||
                 ts.isCallSignatureDeclaration(decl.parent) ||
+                (ts.isMethodDeclaration(decl.parent) && ts.getSourceFileOfNode(decl).isDeclarationFile) ||
                 ((ts.isArrowFunction(decl.parent) || ts.isFunctionExpression(decl.parent)) &&
                     decl.initializer !== undefined &&
                     decl.type === undefined &&
                     !isJsSourceFile(ts.getSourceFileOfNode(decl)))) &&
-            !ts.getSourceFileOfNode(decl).isDeclarationFile &&
             (checker.getTypeOfSymbol(p).flags & ts.TypeFlags.Any) !== 0)
             pt = DYN;
         if (decl &&
@@ -6047,7 +6194,7 @@ function mapGenericIndexedAccess(type, ctx) {
     }
     if (arms.length === 1)
         return arms[0];
-    arms.sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+    sortArms(arms);
     return { kind: "union", unionId: ctx.unions.intern(arms) };
 }
 /** A distributive conditional (`T extends "a" ? A : T extends "b" ? B :
@@ -6162,7 +6309,7 @@ function mapDistributedConditional(type, ctx) {
         return arms[0];
     if (!unionContainerArmsOk(arms))
         return null;
-    arms.sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+    sortArms(arms);
     return { kind: "union", unionId: ctx.unions.intern(arms) };
 }
 /** `keyof T extends never ? A : B` over a bound record T (the lib's
@@ -6241,13 +6388,18 @@ function mapBoundMappedType(widened, ctx) {
         const optional = modifier === ts.SyntaxKind.MinusToken
             ? false
             : modifier !== undefined || (property.flags & ts.SymbolFlags.Optional) !== 0;
+        let absentable = false;
         if (optional) {
-            const armed = withUndefinedArm(type, unions);
-            if (!armed)
-                return null;
-            type = armed;
+            if (type.kind === "dyn")
+                absentable = true;
+            else {
+                const armed = withUndefinedArm(type, unions);
+                if (!armed)
+                    return null;
+                type = armed;
+            }
         }
-        fields.push({ name, type });
+        fields.push({ name, type, ...(absentable ? { optional: true } : {}) });
         order.push(name);
     }
     fields.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
@@ -6588,6 +6740,12 @@ function mapGenericUtilityAlias(widened, ctx) {
         return null;
     const fields = [];
     for (const f of shape.fields) {
+        // Partial makes every property optional: a checked-dynamic slot becomes
+        // absentable, every other one gains the undefined arm.
+        if (f.type.kind === "dyn") {
+            fields.push({ name: f.name, type: f.type, optional: true });
+            continue;
+        }
         const armed = withUndefinedArm(f.type, unions);
         if (!armed)
             return null;
@@ -6615,7 +6773,7 @@ function mapGenericUtilityAlias(widened, ctx) {
  * that could inhabit the extra arm. */
 export function unitOnlyUnion(unions) {
     const arms = [NULL_T, UNDEFINED_T];
-    arms.sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+    sortArms(arms);
     return { kind: "union", unionId: unions.intern(arms) };
 }
 /** `Iterable<T>`: a union whose arms are the sources that keep their own
@@ -6649,7 +6807,7 @@ export function iterableUnionType(elem, shapes, unions) {
             isSupportedMapValue(v.type))
             arms.push({ kind: "map", key: k.type, value: v.type });
     }
-    arms.sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+    sortArms(arms);
     return { kind: "union", unionId: unions.intern(arms) };
 }
 /** The IteratorResult record of a generator's value channels: `{ done:
@@ -6699,7 +6857,7 @@ export function genResultRecord(yieldT, retT, shapes, unions) {
             valueT = unitOnlyUnion(unions);
         }
         else {
-            arms.sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+            sortArms(arms);
             valueT = { kind: "union", unionId: unions.intern(arms) };
         }
     }
@@ -6775,6 +6933,13 @@ export const X509_FIELDS = [
 export function withUndefinedArm(t, unions) {
     return withUnitArm(t, "undefinedT", unions);
 }
+/** A record property declared `?:` whose mapped type is the checked-dynamic
+ * slot. Only such a field's shape carries an ABSENT state of its own (the
+ * absent marker); every other optional property maps to an undefined-armed
+ * union, whose absence is the union's ABSENT state. */
+function optionalCheckedDyn(p, type) {
+    return type.kind === "dyn" && (p.flags & ts.SymbolFlags.Optional) !== 0;
+}
 /** Preserve a nullish runtime value that JavaScript inference omitted. */
 export function withUnitArm(t, kind, unions) {
     const unit = { kind };
@@ -6788,7 +6953,7 @@ export function withUnitArm(t, kind, unions) {
         // Date and Promise arms beside other data arms have no union home.
         if (!unionContainerArmsOk(arms))
             return null;
-        arms.sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+        sortArms(arms);
         return { kind: "union", unionId: unions.transform(def, arms) };
     }
     if (t.kind === "void" ||
@@ -6799,7 +6964,7 @@ export function withUnitArm(t, kind, unions) {
         return null;
     }
     const arms = [t, unit];
-    arms.sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+    sortArms(arms);
     return { kind: "union", unionId: unions.intern(arms) };
 }
 /** The chalk-shape recognizer behind mapType's hybrid branch: an
@@ -6878,7 +7043,68 @@ function mapClassExpandoIntersection(widened, ctx) {
     }
     return DYN;
 }
-function mapHybridCallableIntersection(widened, ctx) {
+/** `F & { data }` maps to the CALLABLE part's func type: the members live in
+ * the closure's own-property table (lowering/callable-properties.ts), so the
+ * value IS the function — identity, aliasing, `typeof`, enumeration and
+ * inspect all answer as Node's function object does. The parts that cannot
+ * share that one representation (a recursive or `this`-typed member, a
+ * symbol-keyed member, an accessor, a class or index-signature part) return
+ * null, and the caller keeps the DYN mapping. */
+function mapCallableIntersection(widened, ctx) {
+    const { checker } = ctx;
+    if (!widened.isIntersectionType())
+        return null;
+    if (checker.getCallSignatures(widened).length !== 1)
+        return null;
+    let funcPart = null;
+    for (const part of ts.constituentTypes(widened)) {
+        if (checker.getCallSignatures(part).length > 0) {
+            if (funcPart)
+                return null; // exactly one callable part
+            funcPart = part;
+            continue;
+        }
+        const partSym = part.getSymbol();
+        if ((part.flags & ts.TypeFlags.Object) === 0 ||
+            checker.getConstructSignatures(part).length > 0 ||
+            (partSym !== undefined && (partSym.flags & ts.SymbolFlags.Class) !== 0) ||
+            checker.getIndexInfosOfType(part).length > 0) {
+            return null;
+        }
+    }
+    if (!funcPart)
+        return null;
+    const properties = checker.getPropertiesOfType(widened);
+    if (properties.length === 0)
+        return null; // no properties — it is just F
+    for (const p of properties) {
+        if (p.flags & (ts.SymbolFlags.GetAccessor | ts.SymbolFlags.SetAccessor))
+            return null;
+        // A symbol-keyed member has no string key in the table.
+        if (ts.symbolName(p).startsWith("__@"))
+            return null;
+    }
+    const fn = mapType(funcPart, ctx);
+    return fn?.kind === "func" ? fn : null;
+}
+/** Whether `widened` is node:test's `Mock<F>` — an intersection carrying a
+ * `mock: MockFunctionContext<F>` member declared in the ambient `test`
+ * module (the same provenance check MockFunctionContext's own mapping
+ * uses). */
+function isMockHybridIntersection(widened, ctx) {
+    if (!widened.isIntersectionType())
+        return false;
+    const mock = ctx.checker.getPropertyOfType(widened, "mock");
+    if (mock === undefined)
+        return false;
+    const sym = ctx.checker.getTypeOfSymbol(mock).getSymbol();
+    return (sym !== undefined &&
+        ts.symbolName(sym) === "MockFunctionContext" &&
+        sym.declarations.some((d) => ts.isInterfaceDeclaration(d) &&
+            ctx.isStdlibFile(ts.getSourceFileOfNode(d)) &&
+            isDeclaredInAmbientModule(d, "test")));
+}
+function mapHybridCallableRecord(widened, ctx) {
     const { checker, shapes } = ctx;
     if (!widened.isIntersectionType())
         return null;
@@ -6913,7 +7139,11 @@ function mapHybridCallableIntersection(widened, ctx) {
         const pt = mapType(checker.getTypeOfSymbol(p), ctx);
         if (!pt || pt.kind === "void")
             return null;
-        fields.push({ name: ts.symbolName(p), type: pt });
+        fields.push({
+            name: ts.symbolName(p),
+            type: pt,
+            ...(optionalCheckedDyn(p, pt) ? { optional: true } : {}),
+        });
         declaredOrder.push(ts.symbolName(p));
     }
     if (fields.length === 1)
@@ -6921,8 +7151,12 @@ function mapHybridCallableIntersection(widened, ctx) {
     fields.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     return { kind: "record", shapeId: shapes.intern(fields, false, undefined, declaredOrder) };
 }
-/** The record every part of a union of function-with-properties
- * intersections maps to, or null when a part does not map to the same one. */
+/** The representation every part of a union of function-with-properties
+ * intersections maps to, or null when a part does not map to the same one.
+ * Each part maps exactly as it does alone — an ordinary callable
+ * intersection to the callable's func type (its members ARE the closure's
+ * own properties), node:test's `Mock<F>` to its hybrid `%call` record — so a
+ * union never reintroduces the record a value no longer has. */
 function mapUniformHybridUnion(widened, ctx) {
     const parts = ts.constituentTypes(widened);
     if (!parts.every((p) => p.isIntersectionType()))
@@ -6931,7 +7165,9 @@ function mapUniformHybridUnion(widened, ctx) {
     for (const part of parts) {
         if (ctx.checker.getConstructSignatures(part).length > 0)
             return null;
-        const mapped = mapHybridCallableIntersection(part, ctx);
+        const mapped = isMockHybridIntersection(part, ctx)
+            ? mapHybridCallableRecord(part, ctx)
+            : mapCallableIntersection(part, ctx);
         if (!mapped || (first && typeKey(mapped) !== typeKey(first)))
             return null;
         first ??= mapped;
@@ -7021,9 +7257,10 @@ function mapErrorMetadataIntersection(type, ctx) {
 /** A conventional primitive brand has one runtime-carrying primitive part
  * and one or more phantom object parts whose fields are literal marker
  * values. The marker can use a string or unique-symbol key, can be imported
- * from a declaration file, and can be expressed through a generic alias;
- * none of those facts changes the runtime value. Empty `{}` refinements are
- * the marker-free form of the same primitive narrowing.
+ * from a declaration file, can be expressed through a generic alias, and can
+ * nest tables of further markers; none of those facts changes the runtime
+ * value. Empty `{}` refinements are the marker-free form of the same
+ * primitive narrowing.
  *
  * Arbitrary primitive/object intersections do not erase here. A companion
  * with a class identity, call/construct/index signature, accessor, or a
@@ -7059,7 +7296,7 @@ function mapBrandedPrimitiveIntersection(widened, ctx) {
         }
         return null;
     };
-    const markerValue = (value) => {
+    const markerValue = (value, seen = new Set()) => {
         if (value.flags &
             (ts.TypeFlags.StringLiteral |
                 ts.TypeFlags.NumberLiteral |
@@ -7074,15 +7311,42 @@ function mapBrandedPrimitiveIntersection(widened, ctx) {
             return true;
         }
         if (value.isUnionType())
-            return ts.constituentTypes(value).every(markerValue);
+            return ts.constituentTypes(value).every((part) => markerValue(part, seen));
         if (value.flags & ts.TypeFlags.TypeParameter) {
             const bound = resolveTypeParamTs?.(value) ?? null;
             if (bound) {
                 contextResolutions++;
-                return markerValue(bound);
+                return markerValue(bound, seen);
             }
         }
-        return false;
+        // A NESTED marker table (`{ readonly ["~effect/Brand"]: { readonly
+        // ProviderDriverKind: "ProviderDriverKind" } }`): an object whose own
+        // members are all markers describes no runtime data, so the nesting
+        // does not make the marker observable. Class identity, call, construct
+        // or index signatures, accessors, and non-literal value fields stay
+        // outside the rule, because those can describe runtime behavior.
+        if ((value.flags & ts.TypeFlags.Object) === 0)
+            return false;
+        if (seen.has(value))
+            return false;
+        seen.add(value);
+        // `seen` holds the types on the current path only: two sibling fields
+        // that name the same marker type both erase, while a table that refers
+        // to itself stays outside the rule.
+        let marker = false;
+        const sym = value.getSymbol();
+        if (sym === undefined || (sym.flags & ts.SymbolFlags.Class) === 0) {
+            marker =
+                checker.getCallSignatures(value).length === 0 &&
+                    checker.getConstructSignatures(value).length === 0 &&
+                    checker.getIndexInfosOfType(value).length === 0 &&
+                    checker
+                        .getPropertiesOfType(value)
+                        .every((prop) => (prop.flags & (ts.SymbolFlags.GetAccessor | ts.SymbolFlags.SetAccessor)) === 0 &&
+                        markerValue(checker.getTypeOfSymbol(prop), seen));
+        }
+        seen.delete(value);
+        return marker;
     };
     let primitive = null;
     let markerParts = 0;
@@ -7301,7 +7565,14 @@ export function packageTypeIsData(type, ctx) {
         if (!data)
             return false;
     }
-    return declared;
+    if (declared)
+        return true;
+    // A union spelled through a package type alias whose members all come
+    // from elsewhere (`type RawData = Buffer | ArrayBuffer | Buffer[]`):
+    // no member carries the package's provenance, but the alias declaration
+    // is the package's data shape, so the type is still data the program
+    // builds and never a value the package's implementation produces.
+    return packageDataPart(type, ctx) === true;
 }
 /** The record path's provenance fence. Declared shapes (object literals,
  * interfaces, type literals) must come from user code or an explicitly
@@ -7517,7 +7788,7 @@ function joinOverloadTypes(types, ctx) {
         }
     }
     if (scalar && [...arms.values()].some((arm) => !isUnitType(arm))) {
-        const sorted = [...arms.values()].sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+        const sorted = sortArms([...arms.values()]);
         return { kind: "union", unionId: ctx.unions.intern(sorted) };
     }
     if (types.every((t) => t.kind === "dyn" ||
@@ -7578,8 +7849,12 @@ export function erasedOverloadMemberType(t, ctx) {
 /** Why an overloaded member's set has no erased type
  * (erasedOverloadMemberType): the first overload, and within it the first
  * parameter or result, that does not map; otherwise the join itself. A
- * message tail after "its member 'name'". */
-function describeOverloadSetBlocker(t, ctx) {
+ * message tail after "its member 'name'". `depth` and `seen` continue the
+ * enclosing description's walk: an overload whose parameter or result
+ * names the record being described (`interface Chain { attach(next:
+ * Chain): Chain }`) must answer from that walk, not restart it, or each
+ * overload tail would describe the same set again without end. */
+function describeOverloadSetBlocker(t, ctx, depth, seen) {
     const { checker } = ctx;
     for (const sig of checker.getCallSignatures(t)) {
         const own = new Set(sig.getTypeParameters());
@@ -7602,10 +7877,10 @@ function describeOverloadSetBlocker(t, ctx) {
         for (const param of sig.getParameters()) {
             const paramTs = checker.getTypeOfSymbol(param);
             if (!mapType(paramTs, sigCtx))
-                return `is an overload set, and its ${which} has parameter '${ts.symbolName(param)}' of type '${checker.typeToString(paramTs)}', which does not compile`;
+                return `is an overload set, and its ${which} has parameter '${ts.symbolName(param)}' of type '${checker.typeToString(paramTs)}', which does not compile${slotReason(paramTs, ctx, depth + 1, seen)}`;
         }
         const retTs = checker.getReturnTypeOfSignature(sig);
-        return `is an overload set, and its ${which} returns '${checker.typeToString(retTs)}', which does not compile`;
+        return `is an overload set, and its ${which} returns '${checker.typeToString(retTs)}', which does not compile${slotReason(retTs, ctx, depth + 1, seen)}`;
     }
     return "is an overload set whose signatures do not join into one stored function (a void result beside a value result, or positions whose differing types do not cross the checked-dynamic boundary)";
 }
@@ -7875,7 +8150,7 @@ function dictSpreadLiteralShape(widened, parts, ctx) {
             return null;
     if (![...arms.values()].some((arm) => !isUnitType(arm)))
         return null;
-    const sorted = [...arms.values()].sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+    const sorted = sortArms([...arms.values()]);
     const slot = sorted.length === 1 ? sorted[0] : { kind: "union", unionId: unions.intern(sorted) };
     return shapes.intern([], false, slot, []);
 }
@@ -8137,7 +8412,7 @@ function mapRecordTypeInner(widened, ctx) {
             slotDef.arms.some((a) => a.kind === "array" && a.elem.kind === "string") &&
             slotDef.arms.every(armOk)) {
             const armsRaw = [F64, STRING, arrayOf(STRING), UNDEFINED_T];
-            armsRaw.sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1));
+            sortArms(armsRaw);
             const canonical = { kind: "union", unionId: ctx.unions.intern(armsRaw) };
             const fits = (t) => {
                 if (!t)
@@ -8370,7 +8645,11 @@ function mapRecordTypeInner(widened, ctx) {
             if (accessorSlotProp(ts.symbolName(p)) !== null)
                 return null;
             // an options record with `signal?: AbortSignal` must not turn its
-            fields.push({ name: ts.symbolName(p), type: pt });
+            fields.push({
+                name: ts.symbolName(p),
+                type: pt,
+                ...(optionalCheckedDyn(p, pt) ? { optional: true } : {}),
+            });
         }
         // getPropertiesOfType yields DECLARATION order (interface/alias/literal
         // source order) — captured before the canonical sort so Object.keys/
@@ -8582,7 +8861,7 @@ function mergePromiseArms(arms, ctx) {
             : payload.every((arm) => armHasUnionHome(arm))
                 ? {
                     kind: "union",
-                    unionId: ctx.unions.intern([...payload].sort((a, b) => (typeKey(a) < typeKey(b) ? -1 : 1))),
+                    unionId: ctx.unions.intern(sortArms([...payload])),
                 }
                 : null;
     const merged = inner === null ? null : { kind: "promise", inner };
@@ -8618,14 +8897,37 @@ function armHasUnionHome(arm) {
             return true;
     }
 }
+/** The deeper story of why an ABI slot (a container argument, union arm,
+ * array/tuple element, function parameter or return type) does not compile,
+ * as a tail for its "... does not compile" sentence: the record member or
+ * nested component actually at fault. Empty when the slot's own type is the
+ * blocker, which keeps the flat message. Naming the member matters for the
+ * shapes a real program passes around — a 33-member `ExtensionAPI` is not a
+ * useful answer. `depth` bounds the recursion over self-referential shapes
+ * (`type F = (f: F) => void`); `innerBlockedMember`'s own `seen` set cannot
+ * see across the describeComponentBlocker call. */
+function slotReason(t, ctx, depth, seen = new Set()) {
+    // A self-referential shape (`type F = () => F`) reaches the same type
+    // again at every step: saying the same sentence twice adds nothing.
+    if (depth >= 3 || seen.has(t))
+        return "";
+    seen.add(t);
+    const why = describeRecordMemberBlocker(t, ctx, depth, seen) ??
+        describeComponentBlocker(t, ctx, depth + 1, seen);
+    return why === null ? "" : `: ${why}`;
+}
 /** When an unmapped type is a SUPPORTED container/composite whose failure
  * lives in a component, answer a message tail naming the component (the
  * SC2009 story); null when the shape itself is the blocker (the caller
  * falls through to the other fences). Stdlib container heads (Map, Set,
  * Promise, generators) ALWAYS answer — their shapes have lowerings, so a
  * later "no lowering" claim about them would be false. */
-export function describeComponentBlocker(widened, ctx) {
+export function describeComponentBlocker(widened, ctx, depth = 0, inherited) {
     const { checker } = ctx;
+    // The type under description is already spoken for: a component that
+    // leads back to it (`type F = () => F`) has nothing to add.
+    const seen = inherited ?? new Set();
+    seen.add(widened);
     const text = (t) => checker.typeToString(t);
     // Stdlib container references (provenance, not the name — a user's own
     // `interface Map` is a record shape and keeps the record stories).
@@ -8643,7 +8945,7 @@ export function describeComponentBlocker(widened, ctx) {
             const role = spec.role(i);
             const mapped = mapType(arg, ctx);
             if (!mapped) {
-                return `the ${container} shape is supported, but its ${role} type '${text(arg)}' does not compile`;
+                return `the ${container} shape is supported, but its ${role} type '${text(arg)}' does not compile${slotReason(arg, ctx, depth, seen)}`;
             }
             if ((container === "Map" || container === "ReadonlyMap") &&
                 i === 0 &&
@@ -8673,7 +8975,7 @@ export function describeComponentBlocker(widened, ctx) {
             return null;
         const elem = mapType(elemTs, ctx);
         if (!elem) {
-            return `the array shape is supported, but its element type '${text(elemTs)}' does not compile`;
+            return `the array shape is supported, but its element type '${text(elemTs)}' does not compile${slotReason(elemTs, ctx, depth, seen)}`;
         }
         return `the array shape is supported, but '${text(elemTs)}' elements have no array representation yet`;
     }
@@ -8686,7 +8988,7 @@ export function describeComponentBlocker(widened, ctx) {
             if (et?.kind === "void" && isUnitOnlyTsType(arg, ctx.resolveTypeParam))
                 continue;
             if (!et || et.kind === "void") {
-                return `the tuple shape is supported, but its element type '${text(arg)}' does not compile`;
+                return `the tuple shape is supported, but its element type '${text(arg)}' does not compile${slotReason(arg, ctx, depth, seen)}`;
             }
         }
         return null;
@@ -8716,7 +9018,7 @@ export function describeComponentBlocker(widened, ctx) {
         }
         for (const { p: part, mapped } of mappedArms) {
             if (!mapped) {
-                return `the union shape is supported, but its arm '${text(part)}' does not compile`;
+                return `the union shape is supported, but its arm '${text(part)}' does not compile${slotReason(part, ctx, depth, seen)}`;
             }
             if (!armHasUnionHome(mapped)) {
                 return `the union shape is supported, but '${text(part)}' arms have no home in a compiled union yet (no runtime narrowing test exists against sibling arms)`;
@@ -8758,12 +9060,12 @@ export function describeComponentBlocker(widened, ctx) {
         for (const p of sig.getParameters()) {
             const pTs = checker.getTypeOfSymbol(p);
             if (!mapType(pTs, ctx)) {
-                return `the function shape is supported, but its parameter '${ts.symbolName(p)}' has type '${text(pTs)}', which does not compile`;
+                return `the function shape is supported, but its parameter '${ts.symbolName(p)}' has type '${text(pTs)}', which does not compile${slotReason(pTs, ctx, depth, seen)}`;
             }
         }
         const retTs = checker.getReturnTypeOfSignature(sig);
         if ((retTs.flags & ts.TypeFlags.Never) === 0 && !mapType(retTs, ctx)) {
-            return `the function shape is supported, but its return type '${text(retTs)}' does not compile`;
+            return `the function shape is supported, but its return type '${text(retTs)}' does not compile${slotReason(retTs, ctx, depth, seen)}`;
         }
         return null;
     }
@@ -8774,8 +9076,10 @@ export function describeComponentBlocker(widened, ctx) {
  * signature routing, so what reaches it is a plain data shape; a null
  * answer (no member pinpointed — provenance fences, accessor rules, shape
  * knots) keeps the residual SC2001 story. */
-export function describeRecordMemberBlocker(widened, ctx) {
+export function describeRecordMemberBlocker(widened, ctx, depth = 0, inherited) {
     const { checker } = ctx;
+    const seen = inherited ?? new Set();
+    seen.add(widened);
     if ((widened.flags & ts.TypeFlags.Object) === 0)
         return null;
     if (checker.getCallSignatures(widened).length > 0)
@@ -8811,7 +9115,7 @@ export function describeRecordMemberBlocker(widened, ctx) {
         if (isOverloadedCallableMemberType(fieldTs, checker)) {
             if (erasedOverloadMemberType(fieldTs, ctx) !== undefined)
                 continue;
-            return `the record shape is supported, but its member '${ts.symbolName(p)}' ${describeOverloadSetBlocker(fieldTs, ctx)}`;
+            return `the record shape is supported, but its member '${ts.symbolName(p)}' ${describeOverloadSetBlocker(fieldTs, ctx, depth, seen)}`;
         }
         if (memberMaps(fieldTs, ctx, p))
             continue;
@@ -8820,7 +9124,7 @@ export function describeRecordMemberBlocker(widened, ctx) {
         // its outermost member.
         const inner = innerBlockedMember(fieldTs, ctx, new Set());
         if (inner !== null && inner.path !== "") {
-            return `the record shape is supported, but its member '${ts.symbolName(p)}${inner.path}' has type '${checker.typeToString(inner.type)}', which does not compile`;
+            return `the record shape is supported, but its member '${ts.symbolName(p)}${inner.path}' has type '${checker.typeToString(inner.type)}', which does not compile${slotReason(inner.type, ctx, depth + 1, seen)}`;
         }
         return `the record shape is supported, but its member '${ts.symbolName(p)}' has type '${checker.typeToString(fieldTs)}', which does not compile`;
     }
@@ -8859,8 +9163,8 @@ function memberMaps(fieldTs, ctx, member) {
 }
 /** The member path inside the unmapped type `t` that its failure comes
  * from, and that member's type: `.name` steps into record members, `[]`
- * into array elements, `()` into a function's return; union arms and
- * promise payloads are transparent. The empty path means `t` itself is
+ * into array elements, `(param)` into a function parameter, `()` into a
+ * function's return; union arms and promise payloads are transparent. The empty path means `t` itself is
  * the blocker; null means `t` maps (or is `any`). */
 function innerBlockedMember(t, ctx, seen) {
     const { checker } = ctx;
@@ -8902,8 +9206,14 @@ function innerBlockedMember(t, ctx, seen) {
         const sig = calls[0];
         if (sig.getTypeParameters().length > 0)
             return here;
-        if (sig.getParameters().some((p) => mapType(checker.getTypeOfSymbol(p), ctx) === null))
-            return here;
+        // A parameter carries the failure as often as the result does (an
+        // event handler's `ctx`, a factory's `theme`): name that parameter's
+        // slot instead of stopping at the function.
+        for (const param of sig.getParameters()) {
+            const paramTs = checker.getTypeOfSymbol(param);
+            if (mapType(paramTs, ctx) === null)
+                return step(`(${ts.symbolName(param)})`, paramTs);
+        }
         return step("()", checker.getReturnTypeOfSignature(sig));
     }
     if (calls.length > 0 ||