@scriptc/compiler 0.0.9 → 0.0.11

package/dist/frontend/lowering/lower-exprs.js

@@ -8,9 +8,9 @@ import * as ts from "../ts7/adapter.js";
 import { dirname } from "node:path";
 import { BOOL, CAUGHT, DYN, DYN_HANDLE_KINDS, F64, JSVAL, NULL_T, REF_TRUTHY_KINDS, REGEX, RUNTIME_ERROR_CLASSES, SEARCH_PARAMS_T, STRING, UNDEFINED_T, VOID, arrayOf, canAdaptDynFuncTo, canBoxFuncIntoDyn, canDynCheckTo, funcOf, isJsonSafeType, isUnitType, jsOpResultKind, shapeHasAccessorSlots, typeEquals, typeKey, unionFuncSetArmsOk } from "../../ir/nodes.js";
 import { cjsClassExprWholeExportOf, cjsExportAssignmentOf, cjsExportDiscardReason, isCjsExportTableLiteral, isCjsJsFile, isJsSourceFile, isModuleExportsAccess, isNodeEsmFile, locOf } from "../program.js";
-import { ARRAY_METHODS, builtinConstLit, builtinFenceHintOf, builtinModuleConstOf, builtinModuleFnOf, ISLAND_SURFACE, isChildSurfaceMember, MAP_METHODS, NARROW_FIRST, SET_METHODS, STR_METHODS, UNSUPPORTED_EXPR, sideEffectFreeOptionValue, stdlibGlobalNameOf } from "./surfaces.js";
+import { ARRAY_METHODS, builtinConstLit, builtinFenceHintOf, builtinModuleConstOf, builtinModulesArrayLit, builtinModuleFnOf, ISLAND_SURFACE, isChildSurfaceMember, MAP_METHODS, NARROW_FIRST, SET_METHODS, STR_METHODS, UNSUPPORTED_EXPR, sideEffectFreeOptionValue, stdlibGlobalNameOf } from "./surfaces.js";
 import { blockedBindingUseDiag, recordShapeMismatchDiag, requiresDynamicPackageDiag, unsupportedDiag } from "../../diagnostics/diagnostic.js";
-import { PoisonError, dynUndefinedExpr, jsFuncNameOf, neverTaintedJsType, own } from "./lowerer.js";
+import { PoisonError, dynUndefinedExpr, jsFuncNameOf, neverTaintedJsType, nodeThrowExpr, own } from "./lowerer.js";
 import { lowerIndexMergeHelper, lowerNpmStaticSafeIndexRead, strCharsCall } from "./lower-containers.js";
 import { npmStaticPackageOfPath } from "../npm-static.js";
 import { unsupportedModuleFeatureOf } from "../shared.js";
@@ -19,7 +19,7 @@ import { ambientNsRootOf, ambientUndefReadType, ambientUndefVarRootOf, ambientUn
 import { expandoMemberRead, expandoWritableTarget } from "./lower-expando.js";
 import { lowerSocketInstanceOf } from "./lower-server.js";
 import { findGenericMethodOn, lowerStaticFieldRead } from "./lower-classes.js";
-import { bindingNeverReassigned, implicitMonoFile, lowerTaggedTemplate, objLitGenericFnInfoOf, objLitGenericFnNodeOf, requireObjLitGenericReceiver } from "./lower-calls.js";
+import { bindingNeverReassigned, implicitMonoFile, lowerTaggedTemplate, nullishGenericBindingUnitOf, objLitGenericFnInfoOf, objLitGenericFnNodeOf, requireObjLitGenericReceiver } from "./lower-calls.js";
 import { mixinFnOfCallee } from "./lower-mixins.js";
 import { isConstAssertionTypeNode, isGenericCallableMemberType, underConstAssertion, unitOnlyUnion } from "../types.js";
 import { lowerYield } from "./lower-generators.js";
@@ -83,7 +83,22 @@ function lowerExprInner(L, expr) {
     if (chainRecv)
         return { ...chainRecv, loc };
     if (ts.isNumericLiteral(expr)) {
-        return { kind: "numLit", value: Number(expr.text.replace(/_/g, "")), type: F64, loc };
+        const value = Number(expr.text.replace(/_/g, ""));
+        // Ask 4's representability input: a DECIMAL INTEGER source spelling
+        // that does not survive the trip through f64 (parse, format back,
+        // compare) rides the literal so the library integer-boundary check
+        // can refuse on the author's source text. `expr.text` is the
+        // scanner's COOKED value (already the nearest double), so the
+        // source spelling comes from the file text; numeric separators are
+        // spelling sugar and strip first. Round-tripping literals (every
+        // integer within ±(2^53−1)) and non-integer spellings carry
+        // nothing, so the IR is unchanged for programs that held their
+        // numbers.
+        const spelled = expr.getText().replace(/_/g, "");
+        if (/^\d+$/.test(spelled) && String(Number(spelled)) !== spelled) {
+            return { kind: "numLit", value: Number(spelled), spelling: spelled, type: F64, loc };
+        }
+        return { kind: "numLit", value, type: F64, loc };
     }
     if (expr.kind === ts.SyntaxKind.TrueKeyword) {
         return { kind: "boolLit", value: true, type: BOOL, loc };
@@ -649,6 +664,11 @@ function lowerExprInner(L, expr) {
                 const c = builtinModuleConstOf(L, bi.module, bi.member);
                 if (c !== undefined)
                     return builtinConstLit(c, loc);
+                // module.builtinModules — the baked Node v24 list, a fresh
+                // string[] per read.
+                if (bi.module === "module" && bi.member === "builtinModules") {
+                    return builtinModulesArrayLit(loc);
+                }
                 // JavaScript sources: a builtin member taken as a bare VALUE is
                 // the same identity-token story as stdlib globals above (the
                 // harness adds worker_threads.Worker to its identity Set).
@@ -796,6 +816,18 @@ function lowerExprInner(L, expr) {
                     return nsUndefRead(L, expr.text, expr, t);
             }
         }
+        // A read of a TRAP binding — a declaration whose own initializer
+        // provably threw (module init unwound there), so this reference can
+        // never execute: any lowering is sound, and the trap keeps the
+        // shape honest. Typed by the use site when it maps, the F64 dummy
+        // otherwise (never observed — never even reached).
+        {
+            const sym = L.resolveValueSymbol(expr);
+            if (sym !== null && L.trapBindings.has(sym)) {
+                const t = ambientUndefReadType(L, expr) ?? contextualUndefReadType(L, expr) ?? F64;
+                return nsUndefRead(L, expr.text, expr, t);
+            }
+        }
         // A program CLASS NAME as a value: the classRef over the class's
         // immortal class object (member accesses and construction never
         // reach here — their hooks claim the property/new forms first).
@@ -1165,6 +1197,15 @@ function lowerExprInner(L, expr) {
             }
             return read;
         }
+        // `m.groups` on a match result whose regex is statically known:
+        // the compile-time record projection over the honest slice (or
+        // Node's undefined when the pattern has no named groups) — see
+        // lowerMatchGroupsRead.
+        {
+            const g = lowerMatchGroupsRead(L, expr);
+            if (g !== null)
+                return g;
+        }
         // `m.index` on a for-of-over-matchAll binding reads the companion-
         // index array at this iteration's cursor — always a number: every
         // drained row matched, so the lib's `.index` is never undefined
@@ -1406,12 +1447,25 @@ function lowerExprInner(L, expr) {
         // read (ARR answers length; everything else JS's own-property
         // answer). Mapped receivers keep the fence-first order: their
         // members' gaps are real surface gaps ([1,2].entries), not
-        // representation artifacts.
-        if (isJsSourceFile(expr.getSourceFile()) &&
+        // representation artifacts. `.length` on a receiver whose checker
+        // ARRAY type lowers to the checked-dynamic representation —
+        // `unknown[]`, the collapsed `(string | object)[]`, and the `any[]`
+        // an Array.isArray guard narrows a collapsed union to — is the DOM
+        // array's OWN length (a keyed read the ARR kind answers exactly),
+        // never an `Array.prototype` surface gap; both source languages.
+        // Prototype-method VALUE reads (`ps.map` unparenthesized) keep the
+        // fence-first order: a stored-member undefined would mis-answer
+        // them, and calls dispatch through the dyn method machinery
+        // instead.
+        if ((isJsSourceFile(expr.getSourceFile()) &&
             (L.mapTypeOf(L.typeOf(expr.expression)) === null ||
                 // A never-tainted receiver type maps (never rides as f64) but
                 // its VALUE lowered checked-dynamic — same DOM read.
-                neverTaintedJsType(L, expr.expression, L.typeOf(expr.expression)))) {
+                neverTaintedJsType(L, expr.expression, L.typeOf(expr.expression)))) ||
+            (expr.name.text === "length" &&
+                (L.checkerAnyArray(expr.expression) ||
+                    (L.checker.isArrayType(L.typeOf(expr.expression)) &&
+                        L.mapTypeOf(L.typeOf(expr.expression))?.kind === "dyn")))) {
             const recv = L.lowerExpr(expr.expression);
             if (recv.type.kind === "dyn") {
                 const key = { kind: "strLit", value: expr.name.text, type: STRING, loc: locOf(expr.name) };
@@ -1479,6 +1533,17 @@ function lowerExprInner(L, expr) {
                     return nsUndefRead(L, ambientRoot.text, expr, t);
             }
         }
+        // A member read through a NULLISH generic binding (`const i: I<A &
+        // B> = null as any; const _i: I<A> = i.something` — the receiver
+        // provably holds null/undefined forever): the read throws Node's
+        // exact TypeError at the access.
+        if (ts.isIdentifier(expr.expression) && expr.questionDotToken === undefined) {
+            const unit = nullishGenericBindingUnitOf(L, L.resolveValueSymbol(expr.expression));
+            if (unit !== null) {
+                const t = ambientUndefReadType(L, expr) ?? contextualUndefReadType(L, expr) ?? F64;
+                return nodeThrowExpr(1, "", `Cannot read properties of ${unit} (reading '${expr.name.text}')`, t, loc);
+            }
+        }
         // The lib fence's PROPERTY chokepoint: a stdlib-declared member that
         // no lowering above claimed ([1,2].entries, Math.SQRT2, Promise.all,
         // re.exec as a value, ...) reports SC2020 here.
@@ -1516,6 +1581,31 @@ function lowerExprInner(L, expr) {
             const opt = chainGuardedByQuestionDot(expr.expression);
             return L.maybeNarrow({ kind: "dynKeyGet", key, ...(opt ? { optional: true } : {}), value: recvLowered, type: DYN, loc }, expr);
         }
+        // The lowered receiver is a RECORD the checker spelled wider —
+        // `s.match(re).groups.key` in a JS file: the checker says
+        // `{ [key: string]: string } | undefined`, but the groups
+        // projection already answered the record arm (its null trap
+        // included). Declared fields read directly; an index-signature
+        // shape serves undeclared keys through the overflow read, exactly
+        // the dot-access rule on checker-spelled hybrids.
+        if (recvLowered.type.kind === "record") {
+            const recvShape = L.shapes.get(recvLowered.type.shapeId);
+            const field = recvShape?.fields.find((f) => f.name === expr.name.text);
+            if (field) {
+                return L.maybeNarrow({ kind: "recordGet", obj: recvLowered, shapeId: recvLowered.type.shapeId, field: field.name, type: field.type, loc }, expr);
+            }
+            if (recvShape?.indexValue !== undefined && !recvShape.tuple) {
+                return L.maybeNarrow({
+                    kind: "recordKeyGet",
+                    obj: recvLowered,
+                    shapeId: recvLowered.type.shapeId,
+                    key: { kind: "strLit", value: expr.name.text, type: STRING, loc: locOf(expr.name) },
+                    overflowOnly: true,
+                    type: recvShape.indexValue,
+                    loc,
+                }, expr);
+            }
+        }
         // An ABSTRACT property through an abstract-typed receiver: the
         // declaration is erased at runtime — Node defines no field for it,
         // each concrete subclass declares its OWN (at its own layout
@@ -2154,7 +2244,18 @@ function pureCondExpr(e) {
 export function lowerNullishCoalesce(L, expr, loc) {
     const left = L.lowerExpr(expr.left);
     if (left.type.kind === "dyn") {
-        L.unsupported("SC1100", expr, "nullish coalescing on 'unknown' values");
+        // `a ?? b` on a CHECKED-DYNAMIC left: the deciding test is the
+        // runtime kind (scr_dyn_is_nullish — UNDEF/NULL take the default;
+        // a wrapped island value routes to the engine's test, defensively:
+        // the wrap constructor scalar-normalizes engine null/undefined
+        // away). Both sides live in the DOM — the right converts through
+        // the usual boundary and evaluates lazily in its branch; a default
+        // with no dyn representation keeps the fence.
+        const right = L.coerceToExpected(L.lowerExpr(expr.right), DYN);
+        if (right.type.kind !== "dyn") {
+            L.unsupported("SC1100", expr, "nullish coalescing on 'unknown' values against defaults with no dynamic representation");
+        }
+        return { kind: "nullish", left, right, type: DYN, loc };
     }
     if (left.type.kind === "jsval") {
         // `a ?? b` on an ISLAND value: the engine's own nullish test — the
@@ -2947,8 +3048,8 @@ export function lowerIntrinsicProperty(L, expr) {
             // No ArrayBuffer VALUE exists — `.buffer` compiles only in the
             // one composed position that consumes it, the DataView
             // constructor's first argument (lowerDataViewNew peels it).
-            L.unsupported("SC1090", expr, "'.buffer' outside new DataView(x.buffer, ...) — scriptc typed arrays own their storage: " +
-                "no free-standing ArrayBuffer value exists, and slice()/subarray() copy");
+            L.unsupported("SC1090", expr, "'.buffer' outside new DataView(x.buffer, ...) / Buffer.from(x.buffer, ...) " +
+                "(no free-standing ArrayBuffer value exists; subarray() answers an aliasing view directly)");
         }
         if (name === "slice" || name === "subarray" || name === "set" || name === "toString") {
             L.unsupported("SC1090", expr, `typed-array methods as values (call '${name}' directly)`);
@@ -2988,6 +3089,24 @@ export function lowerIntrinsicProperty(L, expr) {
                 return read;
             return { kind: "jsExit", value: read, type: F64, loc: locOf(expr) };
         }
+        // A CHECKED-DYNAMIC value behind an array-typed checker spelling
+        // (`Object.keys(u).length` — the dyn walk answers a DOM array while
+        // tsc spells string[]): the runtime-world dispatch — a DOM keyed
+        // read validated into the declared number (a lying length throws
+        // the catchable TypeError, the dynCheck stance).
+        if (receiver.type.kind === "dyn") {
+            const read = {
+                kind: "dynKeyGet",
+                key: { kind: "strLit", value: "length", type: STRING, loc: locOf(expr) },
+                ...(expr.questionDotToken ? { optional: true } : {}),
+                value: receiver,
+                type: DYN,
+                loc: locOf(expr),
+            };
+            if (expr.questionDotToken)
+                return read;
+            return { kind: "dynCheck", value: read, type: F64, loc: locOf(expr) };
+        }
         return kind === "string"
             ? { kind: "strIntrinsic", method: "length", receiver, args: [], type: F64, loc: locOf(expr) }
             : { kind: "arrIntrinsic", method: "length", receiver, args: [], type: F64, loc: locOf(expr) };
@@ -3148,8 +3267,12 @@ export function lowerArrayLiteral(L, expr, expected) {
         // []) builds as a DOM ARRAY — one dyn value whose elements each
         // convert through the usual boundary (dynFrom's JSON-safe domain);
         // an element that cannot convert fences per element. length/index
-        // reads and dynamic consumers ride the keyed-DOM paths.
-        if (isJsSourceFile(expr.getSourceFile())) {
+        // reads and dynamic consumers ride the keyed-DOM paths. TS literals
+        // take the same build when the slot ITSELF is checked-dynamic — an
+        // `unknown[]` annotation or a collapsed `(string | object)[]` maps
+        // to DYN wholesale now (mapType's dyn-element array rule), so the
+        // literal IS the DOM array.
+        if (isJsSourceFile(expr.getSourceFile()) || mapped?.kind === "dyn") {
             const elems = expr.elements.map((el) => {
                 if (ts.isSpreadElement(el)) {
                     L.unsupported("SC1090", el, "spread elements in a dynamic (unknown[]) array literal");
@@ -5053,7 +5176,24 @@ export function lowerElementAccess(L, expr) {
         ? null
         : L.mapTypeOf(L.typeOf(expr.expression));
     if (receiverIr?.kind === "jsval") {
-        return islandElementRead(L, expr, L.lowerExpr(expr.expression));
+        // Dispatch follows the RUNTIME world (383(d)): a checker-'any'
+        // receiver whose value LOWERED checked-dynamic (`bag.list[0]` where
+        // bag.list is a routed keyed read off a wrapped island value) takes
+        // the DOM keyed read below — the routed JSVAL arm reads the real
+        // engine element; a jsval-lowered receiver keeps the island read.
+        const recv = L.lowerExpr(expr.expression);
+        if (recv.type.kind !== "dyn")
+            return islandElementRead(L, expr, recv);
+        const rawKey = L.lowerExpr(expr.argumentExpression);
+        const key = rawKey.type.kind === "string"
+            ? rawKey
+            : rawKey.type.kind === "f64"
+                ? { kind: "toString", operand: rawKey, type: STRING, loc: rawKey.loc }
+                : null;
+        if (key) {
+            const opt = chainGuardedByQuestionDot(expr.expression);
+            return L.maybeNarrow({ kind: "dynKeyGet", key, ...(opt ? { optional: true } : {}), value: recv, type: DYN, loc: locOf(expr) }, expr);
+        }
     }
     // Typed-array element read `b[i]` — like arrayGet with a scalar
     // result; any invalid index traps (the array discipline; JS would
@@ -5131,9 +5271,12 @@ export function lowerElementAccess(L, expr) {
         const obj = L.lowerExpr(expr.expression);
         if (obj.type.kind === "dyn") {
             const rawKey = L.lowerExpr(expr.argumentExpression);
+            // Number, bool, and DYN keys stringify (ToPropertyKey) — the
+            // dyn-keyed read `catchWarning[warning.name]` where the property
+            // chain itself lowered dyn.
             const key = rawKey.type.kind === "string"
                 ? rawKey
-                : rawKey.type.kind === "f64"
+                : rawKey.type.kind === "f64" || rawKey.type.kind === "bool" || rawKey.type.kind === "dyn"
                     ? { kind: "toString", operand: rawKey, type: STRING, loc: rawKey.loc }
                     : null;
             if (key) {
@@ -5499,11 +5642,58 @@ export function lowerElementWrite(L, expr) {
     const receiverIr = L.mapTypeOf(L.typeOf(target.expression));
     if (receiverIr?.kind === "jsval") {
         const obj = L.lowerExpr(target.expression);
+        // Dispatch follows the RUNTIME world (383(d)): a checker-'any'
+        // receiver whose value LOWERED checked-dynamic takes the DOM keyed
+        // write — the routed JSVAL arm lands it on the real engine object.
+        if (obj.type.kind === "dyn") {
+            const loc = locOf(expr);
+            const rawKey = L.lowerExpr(target.argumentExpression);
+            const key = rawKey.type.kind === "f64" || rawKey.type.kind === "bool" || rawKey.type.kind === "dyn"
+                ? { kind: "toString", operand: rawKey, type: STRING, loc: rawKey.loc }
+                : rawKey;
+            if (key.type.kind !== "string") {
+                L.unsupported("SC1090", target.argumentExpression, `'${L.fmt(key.type)}'-typed keys in keyed writes through 'unknown' values`);
+            }
+            const value = L.coerceToExpected(L.lowerExpr(expr.right), DYN);
+            if (value.type.kind !== "dyn") {
+                L.unsupported("SC1100", expr.right, `assigning '${L.fmt(value.type)}' values through 'unknown' receivers`);
+            }
+            return {
+                kind: "exprStmt",
+                expr: { kind: "libCall", fn: "dyn.keySet", args: [obj, key, value], type: VOID, loc },
+                loc,
+            };
+        }
         const key = L.jsvalIn(L.lowerExpr(target.argumentExpression), target.argumentExpression);
         const value = L.jsvalIn(L.lowerExpr(expr.right), expr.right);
         const loc = locOf(expr);
         return { kind: "exprStmt", expr: { kind: "jsOp", op: "setIdx", args: [obj, key, value], type: VOID, loc }, loc };
     }
+    // A checked-dynamic receiver TYPE (`unknown[]` and the collapsed
+    // `(string | object)[]` map to DYN wholesale now): the DOM keyed
+    // write — dyn.keySet. Number keys canonicalize through the JS-exact
+    // formatter; ARR receivers take canonical index keys as element
+    // set/extend (undefined-hole padding, JS's length growth exactly),
+    // OBJ receivers set the member, and the runtime throws Node's
+    // TypeErrors on every other kind. Values convert into the DOM;
+    // unconvertible ones fence per site (the dynFrom stance).
+    if (receiverIr?.kind === "dyn") {
+        const obj = L.lowerExpr(target.expression);
+        if (obj.type.kind === "dyn") {
+            const loc = locOf(expr);
+            let key = L.lowerExpr(target.argumentExpression);
+            if (key.type.kind === "f64")
+                key = L.ensureString(key, target.argumentExpression);
+            if (key.type.kind !== "string") {
+                L.unsupported("SC1090", target.argumentExpression, "indexing with non-string or non-number keys");
+            }
+            const value = L.coerceToExpected(L.lowerExpr(expr.right), DYN);
+            if (value.type.kind !== "dyn") {
+                L.unsupported("SC1101", expr.right, `storing '${L.fmt(value.type)}' values in a checked-dynamic array (the value cannot convert into the DOM)`);
+            }
+            return { kind: "exprStmt", expr: { kind: "libCall", fn: "dyn.keySet", args: [obj, key, value], type: VOID, loc }, loc };
+        }
+    }
     // Typed-array element write `b[i] = v` — bytesSet: the value is an f64
     // the runtime coerces JS-exactly; invalid indices trap (no appends —
     // typed arrays are fixed-length; JS would ignore the write).
@@ -5680,6 +5870,39 @@ export function lowerElementWrite(L, expr) {
             };
         }
     }
+    // Keyed write `d[k] = v` on a CHECKED-DYNAMIC receiver (a JS `any`
+    // dictionary — the Object.create(null) memo-table idiom writes
+    // `result[key] = value`): dyn.keySet, exactly the record-mapped dyn
+    // arm above — later writes win in insertion order, number keys
+    // canonicalize through the JS-exact formatter (ToPropertyKey's string
+    // side), index keys on DOM arrays set/extend elements, and non-object
+    // receivers throw Node's TypeErrors at runtime. An UNMAPPED checker
+    // type (static `any` — mapTypeOf answers null without --dynamic)
+    // probes the receiver's own lowered world: a dyn value takes the same
+    // write, anything else falls through to the fences.
+    if (receiverIr?.kind === "dyn" || receiverIr === null) {
+        const obj = receiverIr !== null ? L.lowerExpr(target.expression) : probeLower(L, target.expression);
+        if (obj !== null && obj.type.kind === "dyn") {
+            const loc = locOf(expr);
+            const litKey = recordKeyLiteralText(target.argumentExpression);
+            let key = litKey !== null
+                ? { kind: "strLit", value: litKey, type: STRING, loc: locOf(target.argumentExpression) }
+                : L.lowerExpr(target.argumentExpression);
+            if (key.type.kind === "f64")
+                key = L.ensureString(key, target.argumentExpression);
+            if (key.type.kind === "bool" || key.type.kind === "dyn") {
+                key = { kind: "toString", operand: key, type: STRING, loc: locOf(target.argumentExpression) };
+            }
+            if (key.type.kind !== "string") {
+                L.unsupported("SC1090", target.argumentExpression, "indexing checked-dynamic values with non-string or non-number keys");
+            }
+            const value = L.coerceToExpected(L.lowerExpr(expr.right), DYN);
+            if (value.type.kind !== "dyn") {
+                L.unsupported("SC1101", expr.right, `storing '${L.fmt(value.type)}' values in a checked-dynamic object (the value cannot convert into the DOM)`);
+            }
+            return { kind: "exprStmt", expr: { kind: "libCall", fn: "dyn.keySet", args: [obj, key, value], type: VOID, loc }, loc };
+        }
+    }
     if (receiverIr?.kind !== "array") {
         L.unsupported("SC1090", target, "assignment to non-array elements");
     }
@@ -8086,11 +8309,14 @@ function lowerRuntimeKeyIn(L, expr, loc) {
 }
 /** A regex literal `/ab+c/gi` → regexLit (interned per (pattern, flags)
    * by the backend). The TS parser has already syntax-checked the literal;
-   * what remains here are the slice fences: the flag alphabet (d and v are
-   * declared-valid TS flags outside this slice) and named capture groups
-   * (their results are unreachable without exec/match). The engine
-   * validates the pattern itself lazily at first use (SEMANTICS.md
-   * documents the divergence from Node's parse-time SyntaxError). */
+   * what remains here is the flag-alphabet fence (d and v are
+   * declared-valid TS flags outside this slice). Named capture groups
+   * `(?<name>...)` and `\k<name>` backreferences compile — libregexp
+   * executes them natively, replace templates resolve `$<name>` at
+   * runtime, and `.groups` reads desugar at their access sites
+   * (matchResultNamedGroupsOf). The engine validates the pattern itself
+   * lazily at first use (SEMANTICS.md documents the divergence from
+   * Node's parse-time SyntaxError). */
 export function lowerRegexLiteral(L, expr) {
     const text = expr.text;
     const lastSlash = text.lastIndexOf("/");
@@ -8105,12 +8331,414 @@ export function lowerRegexLiteral(L, expr) {
                     : `the regex '${f}' flag`);
         }
     }
-    // (?<name>...) — named groups; (?<= / (?<! are lookbehinds and fine.
-    if (/\(\?<(?![=!])/.test(pattern)) {
-        L.unsupported("SC1120", expr, "named capture groups in regex patterns");
-    }
     return { kind: "regexLit", pattern, flags, type: REGEX, loc: locOf(expr) };
 }
+/** The pattern's named capture groups, in source order: each `(?<name>`
+   * with its 1-based capture index (numbered and named groups share the
+   * numbering — the index IS the match slice's element position). Null
+   * when the scan can't answer confidently (an unterminated construct, a
+   * `\u`-escaped group name) — callers fence rather than guess. Duplicate
+   * names (ES2025 — valid across alternatives) appear once per
+   * declaration; consumers pick the participating occurrence. The scan
+   * only needs to track escapes, character classes, and `(` kinds; tsc
+   * has already syntax-checked the literal, so a malformed pattern here
+   * answers null and the engine's lazy compile reports it. */
+export function namedCaptureGroupsOfPattern(pattern) {
+    const groups = [];
+    let captureIndex = 0;
+    let inClass = false;
+    let i = 0;
+    while (i < pattern.length) {
+        const c = pattern[i];
+        if (c === "\\") {
+            i += 2;
+            continue;
+        }
+        if (inClass) {
+            if (c === "]")
+                inClass = false;
+            i++;
+            continue;
+        }
+        if (c === "[") {
+            inClass = true;
+            i++;
+            continue;
+        }
+        if (c !== "(") {
+            i++;
+            continue;
+        }
+        if (pattern[i + 1] !== "?") {
+            captureIndex++;
+            i++;
+            continue;
+        }
+        // (?<name> captures; (?<= and (?<! are lookbehinds; every other
+        // (?… form — (?:, (?=, (?!, modifier groups (?i: — is non-capturing.
+        if (pattern[i + 2] === "<" && pattern[i + 3] !== "=" && pattern[i + 3] !== "!") {
+            const gt = pattern.indexOf(">", i + 3);
+            if (gt < 0)
+                return null;
+            const name = pattern.slice(i + 3, gt);
+            if (name.includes("\\"))
+                return null; // \u-escaped names: bytecode spells them decoded
+            captureIndex++;
+            groups.push({ name, index: captureIndex });
+            i = gt + 1;
+            continue;
+        }
+        i += 2;
+    }
+    return groups;
+}
+/** The statically-known regex PATTERN behind an expression: a regex
+   * literal, a const local initialized with one (the crypto.js
+   * `const regexp = /(?<m>\d+)/` shape), or `new RegExp("...")` over a
+   * string literal (the cooked text IS the pattern). Null when the regex
+   * only exists at runtime — .groups consumers fence there. */
+export function staticRegexPatternOf(L, e) {
+    let expr = e;
+    for (;;) {
+        if (ts.isParenthesizedExpression(expr) || ts.isNonNullExpression(expr)) {
+            expr = expr.expression;
+            continue;
+        }
+        break;
+    }
+    if (ts.isRegularExpressionLiteral(expr)) {
+        const text = expr.text;
+        return text.slice(1, text.lastIndexOf("/"));
+    }
+    if (ts.isNewExpression(expr) &&
+        ts.isIdentifier(expr.expression) &&
+        expr.expression.text === "RegExp" &&
+        L.isStdlibGlobal(expr.expression, "RegExp") &&
+        expr.arguments !== undefined &&
+        expr.arguments.length >= 1 &&
+        (ts.isStringLiteral(expr.arguments[0]) || ts.isNoSubstitutionTemplateLiteral(expr.arguments[0]))) {
+        return expr.arguments[0].text;
+    }
+    if (ts.isIdentifier(expr)) {
+        const init = constInitializerOf(L, expr);
+        if (init !== null)
+            return staticRegexPatternOf(L, init);
+    }
+    return null;
+}
+/** The initializer behind a CONST identifier binding (a plain
+   * VariableDeclaration under a const list) — the one-hop provenance step
+   * the regex traces walk. Null for let/var (reassignable), params,
+   * destructured bindings, and unresolvable names. */
+function constInitializerOf(L, ident) {
+    const sym = L.resolveValueSymbol(ident);
+    const decl = sym ? L.checker.valueDeclarationOf(sym) : undefined;
+    if (decl === undefined || !ts.isVariableDeclaration(decl) || decl.initializer === undefined)
+        return null;
+    if (!ts.isVariableDeclarationList(decl.parent) || (decl.parent.flags & ts.NodeFlags.Const) === 0)
+        return null;
+    return decl.initializer;
+}
+/** The named-group table of the regex that PRODUCED a match-result
+   * expression — the `.groups` desugar's provenance question. Traces
+   * (through parens, `!`, and const bindings):
+   *   - `re.exec(s)` / `s.match(re)`   → re's static pattern
+   *   - a matchAll ROW: `rows[i]`, the for-of binding over a direct
+   *     `s.matchAll(re)` or a stored const drain → re's static pattern
+   * Answers null when the producing regex isn't statically known (the
+   * caller keeps its fence), or the groups list (possibly empty — a
+   * traced regex WITHOUT named groups is the Node-undefined case). */
+export function matchResultNamedGroupsOf(L, e) {
+    const reExpr = matchProducerRegexOf(L, e);
+    if (reExpr === null)
+        return null;
+    const pattern = staticRegexPatternOf(L, reExpr);
+    if (pattern === null)
+        return null;
+    return namedCaptureGroupsOfPattern(pattern);
+}
+/** The regex EXPRESSION whose match produced `e` (see
+   * matchResultNamedGroupsOf for the traced shapes). */
+function matchProducerRegexOf(L, e) {
+    let expr = e;
+    for (;;) {
+        if (ts.isParenthesizedExpression(expr) || ts.isNonNullExpression(expr)) {
+            expr = expr.expression;
+            continue;
+        }
+        break;
+    }
+    // The direct producers: re.exec(s) / s.match(re) — the receiver's
+    // mapped type pins the STDLIB operation (a regex for exec, a string
+    // or its nullable spelling for match — the claim lower-containers
+    // makes), so a user method that happens to be named `match` with a
+    // regex argument never traces.
+    if (ts.isCallExpression(expr) && ts.isPropertyAccessExpression(expr.expression)) {
+        const name = expr.expression.name.text;
+        const recvT = L.mapTypeOf(L.typeOf(expr.expression.expression));
+        if (name === "exec" && expr.arguments.length === 1 && recvT?.kind === "regex") {
+            return expr.expression.expression;
+        }
+        if (name === "match" && expr.arguments.length === 1 &&
+            (recvT?.kind === "string" || (recvT !== null && recvT !== undefined && nullableStringType(L, recvT))) &&
+            L.mapTypeOf(L.typeOf(expr.arguments[0]))?.kind === "regex") {
+            return expr.arguments[0];
+        }
+    }
+    // A matchAll ROW by element access: rows[i] with rows tracing to the
+    // drain call — or the direct s.matchAll(re)[i] spelling.
+    if (ts.isElementAccessExpression(expr)) {
+        return matchAllRegexOf(L, expr.expression);
+    }
+    if (ts.isIdentifier(expr)) {
+        // The for-of binding over a matchAll drain: `for (const m of
+        // s.matchAll(re))` (or over a stored const rows).
+        const sym = L.resolveValueSymbol(expr);
+        const decl = sym ? L.checker.valueDeclarationOf(sym) : undefined;
+        if (decl !== undefined && ts.isVariableDeclaration(decl) &&
+            ts.isVariableDeclarationList(decl.parent) && ts.isForOfStatement(decl.parent.parent)) {
+            return matchAllRegexOf(L, decl.parent.parent.expression);
+        }
+        // A stored const match result: `const m = re.exec(s)`.
+        const init = constInitializerOf(L, expr);
+        if (init !== null)
+            return matchProducerRegexOf(L, init);
+    }
+    return null;
+}
+/** The regex argument of a (possibly const-stored) `s.matchAll(re)`. */
+function matchAllRegexOf(L, e) {
+    let expr = e;
+    for (;;) {
+        if (ts.isParenthesizedExpression(expr) || ts.isNonNullExpression(expr)) {
+            expr = expr.expression;
+            continue;
+        }
+        break;
+    }
+    if (ts.isCallExpression(expr) && ts.isPropertyAccessExpression(expr.expression) &&
+        expr.expression.name.text === "matchAll" && expr.arguments.length === 1 &&
+        L.mapTypeOf(L.typeOf(expr.expression.expression))?.kind === "string" &&
+        L.mapTypeOf(L.typeOf(expr.arguments[0]))?.kind === "regex") {
+        return expr.arguments[0];
+    }
+    // The eager-spread spelling: `[...s.matchAll(re)]`.
+    if (ts.isArrayLiteralExpression(expr) && expr.elements.length === 1) {
+        const only = expr.elements[0];
+        if (ts.isSpreadElement(only))
+            return matchAllRegexOf(L, only.expression);
+    }
+    if (ts.isIdentifier(expr)) {
+        const init = constInitializerOf(L, expr);
+        if (init !== null)
+            return matchAllRegexOf(L, init);
+    }
+    return null;
+}
+/** `m.groups` on a match result whose producing regex is statically
+   * known: the honest slice already HOLDS every named group's value at
+   * its capture index, so the groups object is a compile-time record
+   * projection — `{ year: m[1], month: m[2] }` — built by one interned
+   * helper per (shape, index list, receiver type). Node's exact shape
+   * decisions:
+   *   - no named groups → `undefined` (the identifier-receiver shapes —
+   *     a call receiver would lose its own null trap, so those keep the
+   *     member fence);
+   *   - a nullable receiver (the JS `s.match(re).groups` idiom) throws
+   *     Node's exact TypeError on the unit arms;
+   *   - every declared name is a key (nonparticipating groups hold "" —
+   *     divergence 51's rule, exactly the slice elements they project);
+   *   - ES2025 duplicate names (distinct alternatives) project the first
+   *     participating occurrence: at most one participates, and a
+   *     participating-empty "" falls through to slots that are "" anyway;
+   *   - key order is group declaration order (declaredOrder), Node's own.
+   * The record has no prototype — Node's groups object is null-prototype,
+   * observable only through util.inspect's "[Object: null prototype]"
+   * prefix (the Object.groupBy stance, ledgered). Null when the receiver
+   * isn't a match slice or the regex isn't traceable — the caller's
+   * member fence (with the groups hint) names the gap. */
+export function lowerMatchGroupsRead(L, expr) {
+    if (expr.name.text !== "groups" || expr.questionDotToken !== undefined)
+        return null;
+    const loc = locOf(expr);
+    const strArr = arrayOf(STRING);
+    const recvT = L.mapTypeOf(L.typeOf(expr.expression));
+    if (!recvT || !isMatchSliceType(L, recvT) || !L.isStdlibMember(expr))
+        return null;
+    const groups = matchResultNamedGroupsOf(L, expr.expression);
+    if (groups === null)
+        return null;
+    if (groups.length === 0) {
+        // Node: a match result of a group-less regex answers undefined —
+        // the unit literal, exactly the `undefined` identifier's lowering.
+        // Identifier receivers only (evaluation-free): a CALL receiver's
+        // exec/match must still run and null-trap, which a folded unit
+        // cannot carry — those keep the fence.
+        let r = expr.expression;
+        while (ts.isParenthesizedExpression(r) || ts.isNonNullExpression(r))
+            r = r.expression;
+        if (ts.isIdentifier(r) && typeEquals(recvT, strArr)) {
+            return { kind: "unitLit", unit: "undefined", type: UNDEFINED_T, loc };
+        }
+        return null;
+    }
+    const recv = L.lowerExpr(expr.expression);
+    if (!isMatchSliceType(L, recv.type))
+        return null;
+    return lowerGroupsProjection(L, recv, groups, loc);
+}
+/** True when the IR type is a string-or-units union — the Dict<string>
+   * member spelling (`process.versions.openssl`), match's nullable
+   * receiver claim. */
+function nullableStringType(L, t) {
+    if (t.kind !== "union")
+        return false;
+    const arms = L.unions.get(t.unionId)?.arms ?? [];
+    return arms.some((a) => a.kind === "string") && arms.every((a) => a.kind === "string" || isUnitType(a));
+}
+/** True when the IR type is the honest match slice — `string[]`, or a
+   * union of it with unit arms only (`string[] | null`). The groups
+   * projection's receiver gate, shared with the destructure interception. */
+export function isMatchSliceType(L, t) {
+    if (typeEquals(t, arrayOf(STRING)))
+        return true;
+    return t.kind === "union" && matchSliceUnionArms(L, t.unionId) !== null;
+}
+/** The union-arm layout of a nullable match slice (`string[] | null`,
+   * matchAll's checker spellings with undefined arms included): the
+   * string[] arm's tag plus each unit arm's tag and spelling. Null when
+   * the union holds anything else. */
+function matchSliceUnionArms(L, unionId) {
+    const def = L.unions.get(unionId);
+    if (!def)
+        return null;
+    const strArr = arrayOf(STRING);
+    const arrTag = def.arms.findIndex((a) => typeEquals(a, strArr));
+    if (arrTag < 0)
+        return null;
+    const units = [];
+    for (let i = 0; i < def.arms.length; i++) {
+        if (i === arrTag)
+            continue;
+        const a = def.arms[i];
+        if (!isUnitType(a))
+            return null;
+        units.push({ tag: i, unit: a.kind === "nullT" ? "null" : "undefined" });
+    }
+    return { arrTag, units };
+}
+/** The groups-record projection call: the result is the CHECKER'S OWN
+   * shape — `{ [key: string]: string }`, the hybrid index-signature
+   * record with no declared fields — holding one OVERFLOW entry per
+   * group name in declaration order, so every downstream consumer
+   * (recordKeyGet reads, Object.keys, JSON, the `| undefined` union
+   * wrap) meets exactly the type tsc reported. One lifted helper per
+   * (index list, receiver representation) builds it; see
+   * lowerMatchGroupsRead for the semantics the body encodes. */
+export function lowerGroupsProjection(L, recv, groups, loc) {
+    // Name → its capture indices, in declaration order (duplicates keep
+    // every occurrence — the projection picks the participating one).
+    const order = [];
+    const indicesByName = new Map();
+    for (const g of groups) {
+        const got = indicesByName.get(g.name);
+        if (got) {
+            got.push(g.index);
+        }
+        else {
+            indicesByName.set(g.name, [g.index]);
+            order.push(g.name);
+        }
+    }
+    const shapeId = L.shapes.intern([], false, STRING);
+    const recordT = { kind: "record", shapeId };
+    const recvKey = recv.type.kind === "union" ? recv.type.unionId : "arr";
+    const key = `regexgroups:${shapeId}:${groups.map((g) => `${g.name}=${g.index}`).join(",")}:${recvKey}`;
+    let helper = L.widthHelpers.get(key);
+    if (!helper) {
+        helper = `%regex.groups.${L.widthHelpers.size}`;
+        L.widthHelpers.set(key, helper);
+        const body = [];
+        const locals = [{ id: "m.0", name: "m", type: recv.type, mutable: true }];
+        let mRef = { kind: "varRef", localId: "m.0", type: recv.type, loc };
+        if (recv.type.kind === "union") {
+            // Node's exact TypeError per unit arm, then the checked narrow.
+            const arms = matchSliceUnionArms(L, recv.type.unionId);
+            for (const u of arms.units) {
+                body.push({
+                    kind: "if",
+                    cond: { kind: "unionIsTag", unionId: recv.type.unionId, tag: u.tag, negated: false, value: mRef, type: BOOL, loc },
+                    then: [
+                        {
+                            kind: "throw",
+                            value: {
+                                kind: "libCall",
+                                fn: "error.new",
+                                args: [
+                                    { kind: "strLit", value: `Cannot read properties of ${u.unit} (reading 'groups')`, type: STRING, loc },
+                                ],
+                                type: { kind: "object", className: "%TypeError" },
+                                loc,
+                            },
+                            loc,
+                        },
+                    ],
+                    else_: null,
+                    loc,
+                });
+            }
+            const narrowed = { kind: "unionNarrow", unionId: recv.type.unionId, tag: arms.arrTag, value: mRef, type: arrayOf(STRING), loc };
+            locals.push({ id: "arr.0", name: "arr", type: arrayOf(STRING), mutable: false });
+            body.push({ kind: "varDecl", localId: "arr.0", init: narrowed, loc });
+            mRef = { kind: "varRef", localId: "arr.0", type: arrayOf(STRING), loc };
+        }
+        const num = (value) => ({ kind: "numLit", value, type: F64, loc });
+        const elem = (index) => ({ kind: "arrayGet", arr: mRef, index: num(index), type: STRING, loc });
+        const values = new Map();
+        order.forEach((name, i) => {
+            const idxs = indicesByName.get(name);
+            if (idxs.length === 1) {
+                values.set(name, elem(idxs[0]));
+                return;
+            }
+            // Duplicates: the first non-"" occurrence (at most one
+            // participates; all-"" answers "" like any nonparticipating slot).
+            const id = `g${i}.0`;
+            locals.push({ id, name: `g${i}`, type: STRING, mutable: true });
+            body.push({ kind: "varDecl", localId: id, init: elem(idxs[0]), loc });
+            const gRef = { kind: "varRef", localId: id, type: STRING, loc };
+            for (const idx of idxs.slice(1)) {
+                body.push({
+                    kind: "if",
+                    cond: { kind: "strEq", negated: false, left: gRef, right: { kind: "strLit", value: "", type: STRING, loc }, type: BOOL, loc },
+                    then: [{ kind: "assign", localId: id, value: elem(idx), loc }],
+                    else_: null,
+                    loc,
+                });
+            }
+            values.set(name, gRef);
+        });
+        body.push({
+            kind: "return",
+            value: {
+                kind: "recordLit",
+                fields: order.map((name) => ({ name, value: values.get(name), overflow: true })),
+                type: recordT,
+                loc,
+            },
+            loc,
+        });
+        L.liftedFns.push({
+            name: helper,
+            params: [{ localId: "m.0", name: "m", type: recv.type }],
+            returnType: recordT,
+            locals,
+            body,
+            loc,
+        });
+    }
+    return { kind: "call", callee: helper, args: [recv], type: recordT, loc };
+}
 /** Field read `obj.f` on class-instance and record receivers, through the
    * shared FieldTarget union (fieldGet / recordGet). Bound method references
    * on classes are rejected specifically; func-typed record fields are