@scriptc/compiler 0.0.8 → 0.0.10

package/dist/frontend/lowering/lowerer.js

@@ -26,7 +26,7 @@ import { mixinCallClassInfoOf, mixinIntersectionInstanceType } from "./lower-mix
 import { bindingNeverReassigned, bodyReadsArguments, isThisParameter, paramShape, paramShapes, checkDefaultParamBodyType, completeArgs, wrappedUndefined, undefinedArgFor, requireExactArityValue, bodyReturnType, declaredReturnType, collectSignature, collectSignatureInner, collectGenericSignature, genericFnOf, lowerGenericCall, lowerGenericFnValue, inferTypeParamBindings, lowerGenericInstance, lowerCall, lowerTimersMemberCall, lowerPromiseMethodCall, lowerFilterNarrowCall, isTopLevelFnSymbol, lowerNestedFunctionDecl, lambdaSignature, lowerLambda, lowerFunction } from "./lower-calls.js";
 import { lowerArrayMethodCall, lowerBufferStaticCall, lowerBytesMethodCall, lowerBytesNew, lowerMapMethodCall, lowerMapForEachCall, buildMapForEachFn, lowerRecordOvfCaptureHelper, lowerEnvToPairsHelper, lowerSetMethodCall, lowerSetForEachCall, buildSetForEachFn, lowerRegexMethodCall, lowerStringMethodCall } from "./lower-containers.js";
 import { lowerStreamModuleCall } from "./lower-stream.js";
-import { builtinImportOf, lowerBuiltinModuleCall, lowerChildArgsArg, lowerSpawnSyncCall, lowerSpawnCall, lowerExecSyncCall, recordToEnvPairs, lowerJsonMethodCall, fencedBuiltinImportOf, lowerCryptoComposedCall, lowerUrlMethodCall, lowerSearchParamsMethodCall, lowerStatsMethodCall, lowerChildMethodCall, lowerAtomicsCall, lowerBuiltinExtraProperty, promisifiedExecFileDecl, lowerExecFileAsyncCall, execFileAsyncHelper, lowerStringDecoderMethodCall, strdecHelper, lowerReadlineMethodCall, lowerDcChannelMethodCall, lowerDcChannelProperty, lowerAlsMethodCall, lowerDcTracingChannelMethodCall, lowerDcTracingChannelProperty, lowerJsonProperty, lowerErrorCodeProperty, lowerProcessProperty, isProcessEnv, envValueType, lowerProcessEnvGet, lowerProcessMethodCall, lowerProcessOptionalMethodCall, lowerTimeoutMethodCall, envSnapshotHelper, isConsoleLog, consoleCallMember, lowerNumberStaticCall, lowerNumberStaticProperty, lowerDateCall, lowerTextCodecCall, lowerFsConstantsProperty, lowerHttp2ConstantsProperty, http2ConstantBindingOf, http2ConstantsDestructureDecl, lowerProcessStreamProperty, lowerStringStaticCall, lowerStringLastIndexOfCall, lowerPromiseStaticCall } from "./lower-builtins.js";
+import { builtinImportOf, lowerBuiltinModuleCall, lowerFsToUnixTimestampCall, lowerFsLadderCall, lowerChildArgsArg, lowerSpawnSyncCall, lowerSpawnCall, lowerExecSyncCall, recordToEnvPairs, lowerJsonMethodCall, fencedBuiltinImportOf, lowerCryptoComposedCall, lowerUrlMethodCall, lowerSearchParamsMethodCall, lowerStatsMethodCall, lowerChildMethodCall, lowerAtomicsCall, lowerBuiltinExtraProperty, promisifiedExecFileDecl, lowerExecFileAsyncCall, execFileAsyncHelper, lowerStringDecoderMethodCall, strdecHelper, lowerReadlineMethodCall, lowerDcChannelMethodCall, lowerDcChannelProperty, lowerAlsMethodCall, lowerDcTracingChannelMethodCall, lowerDcTracingChannelProperty, lowerJsonProperty, lowerErrorCodeProperty, lowerProcessProperty, isProcessEnv, envValueType, lowerProcessEnvGet, lowerProcessMethodCall, lowerProcessOptionalMethodCall, lowerTimeoutMethodCall, envSnapshotHelper, isConsoleLog, consoleCallMember, lowerNumberStaticCall, lowerNumberStaticProperty, lowerDateCall, lowerTextCodecCall, lowerFsConstantsProperty, lowerHttp2ConstantsProperty, http2ConstantBindingOf, http2ConstantsDestructureDecl, lowerProcessStreamProperty, lowerStringStaticCall, lowerStringLastIndexOfCall, lowerPromiseStaticCall } from "./lower-builtins.js";
 import { isIslandExpr, islandFuncValueFence, islandRegexpOf, jsvalIn, requireDynamicApi, islandGlobalFnOf, lowerDynamicImportCall, lowerFetchCall, lowerIslandMethodCall, lowerMathProperty, npmPackageOf, npmMemberFence, npmPackageOfSymbol } from "./lower-island.js";
 import { lowerHttpHeadersElement, lowerNetModuleCall, lowerServerMethodCall, lowerServerProperty } from "./lower-server.js";
 import { lowerDgramDnsModuleCall, lowerDgramMethodCall } from "./lower-dgram.js";
@@ -280,6 +280,45 @@ export function dynUndefinedExpr(loc) {
         loc,
     };
 }
+/** An always-throwing Node-parity error expression (the error.nodeThrow
+ * libCall — the lowered form of arms Node rejects unconditionally:
+ * ERR_INVALID_THIS receivers, ERR_MISSING_ARGS arity ladders, the
+ * symbol-to-string TypeError). kind 0 Error / 1 TypeError / 2 RangeError;
+ * an empty code means no code slot. `type` is the replaced expression's
+ * own (never materialized — the global.undefRead pattern). */
+export function nodeThrowExpr(kind, code, message, type, loc) {
+    return {
+        kind: "libCall",
+        fn: "error.nodeThrow",
+        args: [
+            { kind: "numLit", value: kind, type: F64, loc },
+            { kind: "strLit", value: code, type: STRING, loc },
+            { kind: "strLit", value: message, type: STRING, loc },
+        ],
+        type,
+        loc,
+    };
+}
+/** The post-validation fence STRING a validation-ladder Chk libCall
+ * throws after its Node-order checks pass: the same SC2020 text the
+ * per-statement runtime fence would have thrown (message + "[code at
+ * file:line]"), rendered eagerly so the runtime can throw it verbatim
+ * (scr_throw_lowering_fence). The diagnostic joins the runtime-fence
+ * ledger exactly like a deferred statement fence — nothing silently
+ * drops off the coverage report. */
+export function ladderFenceExpr(L, surface, node, hint) {
+    const loc = locOf(node);
+    const d = noLoweringDiag(surface, loc, hint);
+    L.runtimeFences.push(d);
+    const sf = node.getSourceFile();
+    const pos = ts.getLineAndCharacterOfPosition(sf, loc.start);
+    return {
+        kind: "strLit",
+        value: `${d.message} [${d.code} at ${loc.file}:${pos.line + 1}]`,
+        type: STRING,
+        loc,
+    };
+}
 /** The checked-dynamic declaration fallback for unmappable binding types
  * (see irTypeOf), two gates over one story:
  *
@@ -458,6 +497,29 @@ export class Lowerer {
     /** Per-symbol result of the never-reassigned file scan
      * (bindingNeverReassigned — object-literal generic-method receivers). */
     neverReassignedCache = new Map();
+    /** TRAP bindings: declarations whose initializer provably throws before
+     * producing a value (its chain roots at an ambient-undefined name —
+     * ambientUndefVarRootOf). Module init unwinds at the declaration, so no
+     * reference to the binding can ever execute; the statement lowers to the
+     * root's throw, no storage exists, and references lower to the same
+     * trap shape (never reached — sound whatever the type). */
+    trapBindings = new Set();
+    /** NULLISH bindings of unmappable (generic-signature) types: `const i:
+     * I<A & B> = null as any` — the binding provably holds null/undefined
+     * forever (every write's RHS is nullish too), so no storage exists and
+     * each READ knows the value. Member reads and method calls through one
+     * lower to Node's exact TypeError ("Cannot read properties of null
+     * (reading 'fn')"); nullish-to-nullish flows lower to nothing. The map
+     * answers which unit the binding holds (the TypeError names it). Null
+     * entries cache probed non-qualifiers. */
+    nullishBindings = new Map();
+    /** DEAD bindings of unmappable types: never READ anywhere in the
+     * program, declared with no initializer or a value-only one (a function
+     * literal), every write's RHS side-effect-free. Node materializes the
+     * value and drops it — zero observable effect — so the declaration and
+     * its writes lower to nothing, and no type fence fires for a value the
+     * program never consumes. */
+    deadBindings = new Set();
     /** IMPLICIT-ANY function-value bindings (npm-static JS — `const knownBy
      * = (cmd) => ...`), by their VariableDeclaration: the registered info,
      * or null for probed non-qualifiers (implicitLocalFnNodeOf). */
@@ -902,7 +964,11 @@ export class Lowerer {
                 const recvDecl = recvDecls.find(ts.isImportClause) ?? recvDecls[0];
                 if (recvDecl && ts.isVariableDeclaration(recvDecl) && recvDecl.initializer) {
                     const spec = requireSpecOf(recvDecl.initializer);
-                    const dep = spec !== null ? resolveImport(this.program, recvDecl.getSourceFile(), spec) : null;
+                    const dep = spec === null
+                        ? null
+                        : isRelativeSpecifier(spec)
+                            ? resolveImport(this.program, recvDecl.getSourceFile(), spec)
+                            : npmStaticDepSf7(this.program, recvDecl.getSourceFile(), spec);
                     if (dep)
                         symbol = this.cjsModuleExportSymbol(dep, ident.text);
                 }
@@ -1099,12 +1165,14 @@ export class Lowerer {
     }
     /** True when `expr` is an identifier bound by a top-level
      * `const x = require("./local")` of a RELATIVE module — the CommonJS
-     * namespace binding — or by a DEFAULT import of a CommonJS JS module
-     * (`import d from "./lib.cjs"`: Node binds d to module.exports, the
-     * same value require answers). Member accesses on it resolve through
-     * the export table (property symbols → resolveValueSymbol); the bare
-     * value keeps the namespace-object fence, like ESM namespace imports
-     * of builtins. */
+     * namespace binding — or of a bare specifier naming an opted-in
+     * --npm-static package (its CJS entry is a program module, so the
+     * binding is the same namespace over the same export table), or by a
+     * DEFAULT import of a CommonJS JS module (`import d from "./lib.cjs"`:
+     * Node binds d to module.exports, the same value require answers).
+     * Member accesses on it resolve through the export table (property
+     * symbols → resolveValueSymbol); the bare value keeps the
+     * namespace-object fence, like ESM namespace imports of builtins. */
     cjsLocalModuleBindingOf(expr) {
         if (!ts.isIdentifier(expr))
             return false;
@@ -1122,8 +1190,12 @@ export class Lowerer {
                 return false;
             }
             const spec = requireSpecOf(decl.initializer);
-            if (spec === null || !isRelativeSpecifier(spec))
+            if (spec === null)
+                return false;
+            if (!isRelativeSpecifier(spec) &&
+                npmStaticDepSf7(this.program, decl.getSourceFile(), spec) === null) {
                 return false;
+            }
         }
         // SINGLE-VALUE exporters (`module.exports = Countdown` / `= double` /
         // `= 42`): the requirer's binding IS the exported value, not a
@@ -1222,13 +1294,22 @@ export class Lowerer {
     /** The lowering of a CommonJS `require("./local")` occurrence: a call of
      * the required module's run-once %init at exactly this statement's
      * position — Node's inline evaluation, with the guard supplying the
-     * cache-hit behavior for every require after the first. Null when the
-     * specifier is not a relative program module (builtins load nothing;
-     * anything else kept its preflight fence). */
+     * cache-hit behavior for every require after the first. Bare specifiers
+     * naming an opted-in --npm-static package resolve to that package's
+     * program entry (the same edge preflight admitted — bundle dists require
+     * their external dependencies by name). Null for everything else
+     * (builtins load nothing; the rest kept its preflight fence). */
     requireInitStmt(spec, node) {
-        if (!isRelativeSpecifier(spec))
-            return null;
-        const dep = resolveImport(this.program, node.getSourceFile(), spec);
+        // Relative requires resolve within the program; a BARE require can be
+        // a program-module edge too when it names an opted-in --npm-static
+        // package (one package requiring another — the resolution answered
+        // its shipped JS, the file is in the module order, and the reads
+        // alias its globals). Without the guarded %init call at this position
+        // those globals stay uninitialized: the dep's module body would never
+        // run.
+        const dep = isRelativeSpecifier(spec)
+            ? resolveImport(this.program, node.getSourceFile(), spec)
+            : npmStaticDepSf7(this.program, node.getSourceFile(), spec);
         if (!dep || dep.fileName.endsWith(".json"))
             return null;
         const initName = this.initNameOf.get(dep);
@@ -1830,8 +1911,8 @@ export class Lowerer {
             throw new PoisonError();
         }
         // Would-be records with INDEX SIGNATURES (`Record<string, T>`,
-        // `{ [k: string]: T }`) get a message that points at Map<K, V> — the
-        // container that holds unbounded keys — instead of the generic
+        // `{ [k: string]: T }`) get the index-signature fence (SC2006) naming
+        // the supported key/value domain instead of the generic
         // supported-types recitation.
         if (widened.flags & (ts.TypeFlags.Object | ts.TypeFlags.Intersection) &&
             this.checker.getCallSignatures(widened).length === 0 &&
@@ -1950,9 +2031,27 @@ export class Lowerer {
             }
         }
         // STANDARD-LIBRARY nominal types with no lowering at all: the SC2020
-        // story, naming the type.
+        // story, naming the type — and for the families with a WHY, the same
+        // pointed reason the identifier/constructor chokepoints teach.
         if (stdlibNominal) {
-            this.pushDiag(noLoweringDiag(this.checker.typeToString(type), locOf(node)));
+            const intlHint = "Intl formatter values have no representation — the COMPOSED en-US forms lower: " +
+                'new Intl.NumberFormat("en-US").format(x) and x.toLocaleString("en-US") with default options; ' +
+                "the rest is ICU locale data the binary does not carry";
+            const typeHints = {
+                ArrayBuffer: "no free-standing ArrayBuffer value exists — typed arrays own their storage " +
+                    "(new Uint8Array(n) allocates; new Uint8Array(new ArrayBuffer(n)) erases the buffer into the view)",
+                SharedArrayBuffer: "no shared-memory threads exist in a compiled program — Uint8Array is the byte storage",
+                NumberFormat: intlHint,
+                DateTimeFormat: intlHint,
+                DurationFormat: intlHint,
+                PluralRules: intlHint,
+                Collator: intlHint,
+                ListFormat: intlHint,
+                RelativeTimeFormat: intlHint,
+                Segmenter: intlHint,
+                DisplayNames: intlHint,
+            };
+            this.pushDiag(noLoweringDiag(this.checker.typeToString(type), locOf(node), typeHints[stdlibOwnSym?.name ?? ""]));
             throw new PoisonError();
         }
         // USER record shapes blocked by ONE member (SC2009's record arm):
@@ -2147,8 +2246,10 @@ export class Lowerer {
     }
     /** Exact-shape enforcement (SC2002). Records are monomorphic structs, so
      * everywhere a value flows into a typed slot (call arg, initializer,
-     * assignment, field, return) the shapes must MATCH — TS's structural width
-     * subtyping (`{a, b}` where `{a}` is expected) has no runtime coercion.
+     * assignment, field, return) the shapes must MATCH — or width-coerce:
+     * coerceToExpected already ran widthCoerce (the copy-reshape family),
+     * so what reaches here is the RESIDUE its rules decline, and the
+     * diagnostic names the first blocking rule (describeRecordWidthBlocker).
      * Non-record mismatches are not reachable through tsc-clean programs; the
      * validator ICEs on them as the usual backstop. */
     requireExactShape(node, actual, expected) {
@@ -2207,7 +2308,13 @@ export class Lowerer {
             throw new PoisonError();
         }
         if (containsRecord(actual) || containsRecord(expected)) {
-            this.pushDiag(recordShapeMismatchDiag(this.fmt(expected), this.fmt(actual), locOf(node)));
+            // A record→record pair gets the pointed story: WHICH width rule
+            // declined (a field that doesn't lift, a required field with no
+            // source, an index signature that could hold the completed key).
+            const detail = actual.kind === "record" && expected.kind === "record"
+                ? (this.describeRecordWidthBlocker(actual.shapeId, expected.shapeId) ?? undefined)
+                : undefined;
+            this.pushDiag(recordShapeMismatchDiag(this.fmt(expected), this.fmt(actual), locOf(node), detail));
             throw new PoisonError();
         }
         // Everything else — a plain-kind mismatch like a string flowing into a
@@ -2297,6 +2404,21 @@ export class Lowerer {
             return expr;
         }
         if (expr.type.kind === "jsval" && expected.kind !== "jsval") {
+            // The jsval→DOM crossing (the world unification's engine-handle
+            // kind): an 'any'-typed engine value flowing into an 'unknown'/
+            // 'object'/JS-residue slot wraps BY REFERENCE as the DOM's island
+            // kind — engine scalars normalize to native DOM kinds at wrap time,
+            // typeof/truthiness/String()/=== route to the engine, un-armed DOM
+            // walks fence loudly, and the value unwraps back identity-preserved
+            // (scr_jsval_from_dyn). Monotone under evolution/widening: a value
+            // wraps once at its first dyn edge and stays valid through every
+            // subsequent dyn slot; narrowing never changes representation.
+            // This wrap RETIRES the silent-wrong-answer fence-closure box for
+            // jsval members of DOM object literals (lowerDynObjectLiteral's
+            // coercion lands here first).
+            if (expected.kind === "dyn") {
+                return { kind: "dynFromJsval", value: expr, type: DYN, loc: expr.loc };
+            }
             // The exit set: everything round-trippable, plus bare undefined-armed
             // unions of JSON-safe data arms (the engine's undefined takes the
             // undefined arm before the JSON detour) — canExitIslandToType.
@@ -2705,10 +2827,23 @@ export class Lowerer {
      *               recursively — NESTED width)
      *   arr       — array into array whose element pair lifts (per-element
      *               copy loop, arrayWidthHelper)
+     *   dynIn     — a typed value into an 'unknown' (dyn) slot — the same
+     *               static→DOM deep copy coerceToExpected applies top-level
+     *   upcast    — a derived class instance into a base-typed slot (the
+     *               prefix-layout pointer reinterpret, no copy)
+     *   funcAdapt — a function into a slot whose signature differs only by
+     *               CLEAN mechanical conversions (cleanFuncAdaptable); the
+     *               stranded (trap-only) dispositions stay out of the plan
      * Null when the pair isn't in the relation — callers keep their fences. */
     widthLiftPlan(src, dst) {
         if (typeEquals(src, dst))
             return { how: "copy" };
+        // An 'unknown' (dyn) DESTINATION slot: the static→DOM conversion —
+        // dynFrom, a DEEP COPY (`{ v: 5 }` into `{ v: unknown }`, `number[]`
+        // into `unknown[]` — tsc's top type over the width family's copies).
+        if (dst.kind === "dyn" && src.kind !== "dyn" && this.dynConvertible(src)) {
+            return { how: "dynIn" };
+        }
         if (dst.kind === "union") {
             if (src.kind === "union") {
                 return this.unionRetagMappable(src.unionId, dst.unionId) ? { how: "retag" } : null;
@@ -2747,6 +2882,23 @@ export class Lowerer {
         if (src.kind === "union" && !isUnitType(dst) && dst.kind !== "void" && this.armTag(src.unionId, dst) >= 0) {
             return { how: "narrow" };
         }
+        // A DERIVED instance into a BASE-typed slot (`{ p: Q }` copying into
+        // `{ p: P }`): the same implicit upcast coerceToExpected performs at
+        // top level — prefix layout, a pointer reinterpret, no copy.
+        if (dst.kind === "object" &&
+            src.kind === "object" &&
+            this.isSubclassOf(src.className, dst.className)) {
+            return { how: "upcast" };
+        }
+        // A FUNCTION into a slot whose signature differs only by CLEAN
+        // mechanical conversions (fewer params — JS ignores extras — and
+        // coercibleValue pieces): the general function-value adapter, plan-
+        // gated to the clean subset. The stranded (trap-only) dispositions
+        // funcCoerceAdapter also builds stay TOP-LEVEL only: a width plan
+        // never promises a bridge that can only throw.
+        if (dst.kind === "func" && src.kind === "func" && this.cleanFuncAdaptable(src, dst)) {
+            return { how: "funcAdapt" };
+        }
         if (dst.kind === "record" && src.kind === "record") {
             return this.recordWidthPlan(src.shapeId, dst.shapeId) !== null ? { how: "width" } : null;
         }
@@ -2874,6 +3026,24 @@ export class Lowerer {
                     throw new Error("lowerer bug: planned narrow lift failed to intern");
                 return { kind: "call", callee: helper, args: [value], type: dst, loc };
             }
+            case "dynIn": {
+                if (dst.kind !== "dyn")
+                    throw new Error("lowerer bug: dynIn lift against a non-dyn slot");
+                return { kind: "dynFrom", value, type: DYN, loc };
+            }
+            case "upcast": {
+                if (dst.kind !== "object" || value.type.kind !== "object")
+                    throw new Error("lowerer bug: upcast lift shape");
+                return this.upcastTo(value, dst.className);
+            }
+            case "funcAdapt": {
+                if (dst.kind !== "func" || value.type.kind !== "func")
+                    throw new Error("lowerer bug: funcAdapt lift shape");
+                const adapter = this.funcCoerceAdapter(value.type, dst, loc);
+                if (!adapter)
+                    throw new Error("lowerer bug: planned funcAdapt lift failed to intern");
+                return { kind: "call", callee: adapter, args: [value], type: dst, loc };
+            }
             default: {
                 const _exhaustive = lift;
                 void _exhaustive;
@@ -2891,9 +3061,11 @@ export class Lowerer {
      * optional-flavored field completes to its undefined arm (the
      * literal-completion rule). TUPLES width-coerce too, arity-exact (TS
      * permits no other tuple width): per-position lifts, never completion.
-     * Index-signature shapes keep the exactness fences here (the overflow
-     * CAPTURE helper owns their reshapes). Null when the shapes don't
-     * relate that way. */
+     * Index-signature SOURCES narrow here like any wider record — declared
+     * fields copy, the overflow drops with the width (missing target
+     * fields decline: the overflow could hold them). Index-signature
+     * TARGETS keep the overflow CAPTURE helper (widthCoerce's other arm).
+     * Null when the shapes don't relate that way. */
     /** The pure planning half of recordWidthHelper — every target field's
      * lift, or null when the pair isn't width-coercible. Callers that must
      * validate a WHOLE plan before interning anything (the retag helper's
@@ -2901,7 +3073,13 @@ export class Lowerer {
     recordWidthPlan(fromId, toId) {
         const from = this.shapes.get(fromId);
         const to = this.shapes.get(toId);
-        if (!from || !to || from.indexValue || to.indexValue)
+        // INDEX-SIGNATURE sources narrow like any wider record — the target
+        // fields copy off the declared struct slots and the overflow drops
+        // with the rest of the width (divergence 36's stance; the absent-
+        // completion rule below is the one extra fence). Index-signature
+        // TARGETS keep the overflow CAPTURE helper (widthCoerce's other arm):
+        // a fresh hybrid needs keyed writes, not a field-list literal.
+        if (!from || !to || to.indexValue)
             return null;
         // Tuple↔record pairs never relate; tuple↔tuple only arity-exact.
         if (!!from.tuple !== !!to.tuple)
@@ -2926,8 +3104,12 @@ export class Lowerer {
                     // the absent-property read: the options-record call shape
                     // against `{ plugins: unknown, ... }`). Never for tuples: a
                     // completed position would change .length and JSON where Node
-                    // keeps the source arity.
-                    if (from.tuple)
+                    // keeps the source arity. Never for INDEX-SIGNATURE sources:
+                    // the overflow may hold this very key at runtime (tsc lets the
+                    // signature satisfy optional target members), so completing to
+                    // undefined would drop a value Node keeps — the pair stays
+                    // fenced.
+                    if (from.tuple || from.indexValue)
                         return null;
                     if (tf.type.kind === "dyn") {
                         plan.set(tf.name, { absentDyn: true });
@@ -2953,6 +3135,92 @@ export class Lowerer {
             this.widthPlanning.delete(key);
         }
     }
+    /** Post-hoc classifier for SC2002's record→record residue: WHY the
+     * width family (recordWidthPlan and the overflow capture — widthCoerce's
+     * two record arms) declined this pair — the FIRST blocking rule, named.
+     * Pure description on the failure path (the site already carries the
+     * rejection): mirrors the planners' gates, never changes what coerces,
+     * and answers null when no pointed story applies (the generic message
+     * stands). */
+    describeRecordWidthBlocker(fromId, toId) {
+        const from = this.shapes.get(fromId);
+        const to = this.shapes.get(toId);
+        if (!from || !to)
+            return null;
+        if (to.indexValue) {
+            // The overflow CAPTURE's gates (lowerRecordOvfCaptureHelper).
+            if (from.tuple || to.tuple)
+                return "a tuple cannot reshape into an index-signature record";
+            const tIv = to.indexValue;
+            const slotOk = (t) => typeEquals(t, tIv) ||
+                (tIv.kind === "dyn" && (t.kind === "dyn" || this.dynConvertible(t))) ||
+                this.widthLiftPlan(t, tIv) !== null;
+            const consumed = new Set();
+            for (const tf of to.fields) {
+                const sf = from.fields.find((f) => f.name === tf.name);
+                if (sf) {
+                    if (this.widthLiftPlan(sf.type, tf.type) !== null) {
+                        consumed.add(tf.name);
+                        continue;
+                    }
+                    return `field '${tf.name}': '${this.fmt(sf.type)}' does not lift into '${this.fmt(tf.type)}'`;
+                }
+                if (tf.type.kind !== "union" || this.armTag(tf.type.unionId, UNDEFINED_T) < 0) {
+                    return `the expected field '${tf.name}' is required and the source has no field to copy into it`;
+                }
+                if (tIv.kind === "dyn" ? !this.dynConvertible(tf.type) : !typeEquals(tf.type, tIv)) {
+                    return `the expected field '${tf.name}' ('${this.fmt(tf.type)}') cannot take a runtime key collision from the '${this.fmt(tIv)}' signature slot`;
+                }
+            }
+            for (const ff of from.fields) {
+                if (consumed.has(ff.name))
+                    continue;
+                if (!slotOk(ff.type)) {
+                    return `the source field '${ff.name}' ('${this.fmt(ff.type)}') cannot enter the expected '[key: string]: ${this.fmt(tIv)}' slot`;
+                }
+            }
+            if (from.indexValue && !slotOk(from.indexValue)) {
+                return `the source's '[key: string]: ${this.fmt(from.indexValue)}' slot cannot enter the expected '[key: string]: ${this.fmt(tIv)}' slot`;
+            }
+            // The dispatch-writes gate: runtime-keyed writes can collide with a
+            // declared field whose type is not the slot's.
+            const dispatchWrites = from.indexValue !== undefined ||
+                from.fields.some((ff) => !consumed.has(ff.name) && to.fields.some((f) => f.name === ff.name));
+            if (dispatchWrites) {
+                const bad = to.fields.find((f) => tIv.kind === "dyn" ? !this.dynConvertible(f.type) : !typeEquals(f.type, tIv));
+                if (bad) {
+                    return `runtime-keyed writes can collide with the expected field '${bad.name}' ('${this.fmt(bad.type)}'), which cannot take a '${this.fmt(tIv)}' slot value`;
+                }
+            }
+            return null;
+        }
+        // The field-copy plan's gates (recordWidthPlan).
+        if (!!from.tuple !== !!to.tuple)
+            return null;
+        if (from.tuple && from.fields.length !== to.fields.length) {
+            return `tuple arities differ (${from.fields.length} vs ${to.fields.length}; TS permits no tuple width)`;
+        }
+        for (const tf of to.fields) {
+            const ff = from.fields.find((f) => f.name === tf.name);
+            if (!ff) {
+                if (from.tuple)
+                    return null;
+                if (from.indexValue) {
+                    return `'${tf.name}' is not a declared field of the source, and the source's index signature could hold it at runtime (a completed undefined would drop that value)`;
+                }
+                if (tf.type.kind === "dyn")
+                    continue;
+                if (tf.type.kind !== "union" || this.armTag(tf.type.unionId, UNDEFINED_T) < 0) {
+                    return `the expected field '${tf.name}' is missing on the source and is not optional`;
+                }
+                continue;
+            }
+            if (this.widthLiftPlan(ff.type, tf.type) === null) {
+                return `field '${tf.name}': '${this.fmt(ff.type)}' does not lift into '${this.fmt(tf.type)}'`;
+            }
+        }
+        return null;
+    }
     recordWidthHelper(fromId, toId, loc) {
         const from = this.shapes.get(fromId);
         const to = this.shapes.get(toId);
@@ -3611,6 +3879,28 @@ export class Lowerer {
         }
         return false;
     }
+    /** True when a `src` function value enters a `dst` slot through
+     * funcCoerceAdapter with NO stranded (trap-only) piece: no rest packs,
+     * no surplus source params, every slot parameter converts into the
+     * wrapped function's own type, and the result converts back (a void
+     * slot drops it; a void result answers the exact JS undefined for
+     * dyn/jsval slots). The width family's func gate — widthLiftPlan
+     * bridges only signatures whose every call succeeds by construction. */
+    cleanFuncAdaptable(src, dst) {
+        if (src.rest === true || dst.rest === true)
+            return false;
+        if (src.params.length > dst.params.length)
+            return false;
+        for (let i = 0; i < src.params.length; i++) {
+            if (!this.coercibleValue(dst.params[i], src.params[i]))
+                return false;
+        }
+        if (dst.ret.kind === "void")
+            return src.ret.kind !== "jsval";
+        if (this.coercibleValue(src.ret, dst.ret))
+            return true;
+        return src.ret.kind === "void" && (dst.ret.kind === "dyn" || dst.ret.kind === "jsval");
+    }
     /** Interned `%fn.adapt.<n>(f)` — the GENERAL function-value adapter: a
      * `fromT` function value flowing into a `toT` slot whose pieces differ
      * only by coercibleValue conversions. The slot's callers pass toT's
@@ -4929,6 +5219,11 @@ export class Lowerer {
         if (value.kind === "unitLit") {
             return { kind: "dynFrom", value, type: DYN, loc: value.loc };
         }
+        // An ISLAND ('any') value: the by-reference jsval→DOM wrap — the same
+        // edge coerceToExpected converts (dyn slots accept engine values).
+        if (value.type.kind === "jsval") {
+            return { kind: "dynFromJsval", value, type: DYN, loc: value.loc };
+        }
         if (!this.dynConvertible(value.type)) {
             this.unsupported("SC1100", node, `storing '${this.fmt(value.type)}' values under an 'unknown'-valued index signature (only numbers, strings, booleans, and JSON-safe records/arrays/unions convert)`);
         }
@@ -5884,7 +6179,7 @@ export class Lowerer {
     lowerDestructuringAssignParts(target, rhs, loc) {
         return lowerDestructuringAssignParts(this, target, rhs, loc);
     }
-    lowerBindingPattern(pattern, srcRef, srcType, isLet, out) {
+    lowerBindingPattern(pattern, srcRef, srcType, isLet, out, dynSpell) {
         // An ISLAND source (`const { readFileSync } = await import("fs")` —
         // a namespace handle, or any 'any'-typed object): each bound name is
         // an engine property read, mirroring the island property-read rule —
@@ -5948,7 +6243,7 @@ export class Lowerer {
             }
             return;
         }
-        return lowerBindingPattern(this, pattern, srcRef, srcType, isLet, out);
+        return lowerBindingPattern(this, pattern, srcRef, srcType, isLet, out, dynSpell);
     }
     checkBindingElement(el, allowDefault = false) {
         return checkBindingElement(this, el, allowDefault);
@@ -6029,6 +6324,16 @@ export class Lowerer {
                     const local = this.declareLocal(decl.name, decl.name.text, JSVAL, isLet);
                     return { kind: "varDecl", localId: local.id, init, loc: locOf(decl) };
                 }
+                // The CHECKED-DYNAMIC twin of the handle rescue (the runtime-world
+                // local rule): an unmappable declared type over a dyn initializer
+                // (`const first = plugins[0]` — the checker spells 'string |
+                // object' while the read is a DOM keyed read) keeps the binding
+                // dyn; typed use sites ride validated extractions and the routed
+                // engine ops, exactly the JSON.parse-binding story.
+                if (mapped === null && init.type.kind === "dyn") {
+                    const local = this.declareLocal(decl.name, decl.name.text, DYN, isLet);
+                    return { kind: "varDecl", localId: local.id, init, loc: locOf(decl) };
+                }
                 if (mapped === null)
                     this.badType(decl.name, this.typeOf(decl.name));
                 // A mappable declared type with a non-island initializer: the
@@ -6402,6 +6707,27 @@ export class Lowerer {
                 const spec = requireSpecOf(decl.initializer);
                 return spec !== null ? canonicalBuiltinModule(spec) : null;
             }
+            // A DESTRUCTURED sub-namespace binding — `const { promises } =
+            // fs` / `= require('fs')`: the member is itself a supported module
+            // ("fs/promises"), so the binding carries that module's namespace
+            // surface. canonicalBuiltinModule gates the composition (an
+            // ordinary destructured FUNCTION binding composes to an unknown
+            // name and answers null — builtinImportOf owns those).
+            if (ts.isBindingElement(decl) && ts.isObjectBindingPattern(decl.parent) &&
+                ts.isVariableDeclaration(decl.parent.parent) && decl.parent.parent.initializer !== undefined &&
+                decl.propertyName === undefined && decl.initializer === undefined) {
+                const name = decl.name;
+                if (name === undefined || !ts.isIdentifier(name))
+                    return null;
+                const init = decl.parent.parent.initializer;
+                const spec = requireSpecOf(init);
+                const outer = spec !== null
+                    ? canonicalBuiltinModule(spec)
+                    : ts.isIdentifier(init) ? this.builtinNamespaceModuleOf(init) : null;
+                if (outer !== null)
+                    return canonicalBuiltinModule(`${outer}/${name.text}`);
+                return null;
+            }
         }
         // The INLINE CommonJS spelling: `require("cluster").isPrimary` — the
         // call expression IS the module namespace (Node evaluates the member
@@ -6509,6 +6835,17 @@ export class Lowerer {
         const streamServed = lowerStreamModuleCall(this, call, bi, locOf(access));
         if (streamServed)
             return streamServed;
+        // fs._toUnixTimestamp — off the param tables (an underscore-stable
+        // internal), served by its own spoke before the table fence.
+        const fsTs = this.lowerFsToUnixTimestampCall(call, bi, locOf(access));
+        if (fsTs)
+            return fsTs;
+        // The fs validation-ladder spoke (checked-dynamic lane): misuse of
+        // implemented-namespace members throws Node's typed errors instead
+        // of meeting the table fence.
+        const fsLadder = this.lowerFsLadderCall(call, bi, locOf(access));
+        if (fsLadder)
+            return fsLadder;
         const builtinFn = builtinModuleFnOf(this, bi.module, bi.member);
         if (!builtinFn) {
             this.noLowering(`${bi.module}.${bi.member}`, call, builtinFenceHintOf(bi.module, bi.member), this.checker.getSymbolAtLocation(access.name));
@@ -6539,6 +6876,11 @@ export class Lowerer {
         const bi = this.builtinMemberOf(expr);
         if (!bi)
             return null;
+        // events.defaultMaxListeners READS the process-wide default (its
+        // write twin routes through emitter.setDefaultMaxChk).
+        if (bi.module === "events" && bi.member === "defaultMaxListeners") {
+            return { kind: "libCall", fn: "emitter.getDefaultMax", args: [], type: F64, loc };
+        }
         const c = builtinModuleConstOf(this, bi.module, bi.member);
         if (c !== undefined)
             return builtinConstLit(c, loc);
@@ -6554,6 +6896,12 @@ export class Lowerer {
     lowerBuiltinModuleCall(expr, bi, fn, loc) {
         return lowerBuiltinModuleCall(this, expr, bi, fn, loc);
     }
+    lowerFsToUnixTimestampCall(expr, bi, loc) {
+        return lowerFsToUnixTimestampCall(this, expr, bi, loc);
+    }
+    lowerFsLadderCall(expr, bi, loc) {
+        return lowerFsLadderCall(this, expr, bi, loc);
+    }
     lowerChildArgsArg(node, loc) {
         return lowerChildArgsArg(this, node, loc);
     }