@scriptc/compiler 0.0.22 → 0.0.24

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

@@ -13,12 +13,72 @@ import { probeNodeRequireRefusal } from "../npm.js";
 import { isNpmStaticPackage } from "../npm-static.js";
 import { invalidJsonModuleDiag, requiresDynamicImportDiag } from "../../diagnostics/diagnostic.js";
 import { builtinModuleFnOf, FS_READDIR_DOCUMENTED_OPTIONS, FS_WATCH_DOCUMENTED_OPTIONS, FS_WRITE_FILE_DOCUMENTED_OPTIONS, QS_PARSE_DOCUMENTED_OPTIONS, QS_STRINGIFY_DOCUMENTED_OPTIONS, READLINE_DOCUMENTED_OPTIONS, builtinConstLit, fenceOrDropOptionKey, isChildSurfaceMember, } from "./surfaces.js";
-import { conditionalSpreadOf, lowerDynObjectLiteral } from "./lower-exprs.js";
+import { conditionalSpreadOf, droppableStatic, lowerDynObjectLiteral } from "./lower-exprs.js";
 import { HTTP2_CONSTANTS } from "./http2-constants.js";
 import { CRYPTO_CIPHERS, CRYPTO_CONSTANTS, CRYPTO_CURVES, CRYPTO_HASHES } from "./crypto-tables.js";
 import { timerStyleCallback } from "./lower-calls.js";
-import { registerHttpClientFnBinding } from "./lower-server.js";
-import { BOOL, BYTES_U8, CHILD_T, CHILDSTREAM_T, DYN, F64, FSWATCHER_T, PROCSTREAM_T, JSVAL, NULL_T, SEARCH_PARAMS_T, SPAWNRES_T, STRING, UNDEFINED_T, VOID, arrayOf, canBoxFuncIntoDyn, canConvertToDyn, funcOf, isUnitType, typeEquals, typeKey } from "../../ir/nodes.js";
+import { registerHttpClientFnBinding, voidizedCallback } from "./lower-server.js";
+import { BOOL, BYTES_U8, CHILD_T, CHILDSTREAM_T, DYN, F64, FILEHANDLE_T, FSWATCHER_T, PROCSTREAM_T, JSVAL, NULL_T, SEARCH_PARAMS_T, SPAWNRES_T, STRING, UNDEFINED_T, VOID, arrayOf, canBoxFuncIntoDyn, canConvertToDyn, funcOf, isUnitType, typeEquals, typeKey } from "../../ir/nodes.js";
+/** Lower an optional builtin argument whose checker type is statically
+ * undefined/void. The returned expression exists only to preserve effects;
+ * callers replace its value with the API default. */
+function lowerStaticallyUndefinedBuiltinArg(L, node) {
+    const peel = (value) => {
+        let expr = value;
+        while (ts.isParenthesizedExpression(expr) ||
+            ts.isAsExpression(expr) ||
+            ts.isTypeAssertion(expr) ||
+            ts.isSatisfiesExpression(expr)) {
+            expr = expr.expression;
+        }
+        return expr;
+    };
+    let expr = node;
+    while (ts.isParenthesizedExpression(expr))
+        expr = expr.expression;
+    if ((L.typeOf(expr).flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) === 0)
+        return null;
+    expr = peel(expr);
+    let sawVoid = false;
+    while (ts.isVoidExpression(expr)) {
+        sawVoid = true;
+        expr = peel(expr.expression);
+    }
+    return L.lowerExpr(sawVoid ? expr : node);
+}
+function defaultAfterUndefined(value, dflt) {
+    if (droppableStatic(value))
+        return dflt;
+    return {
+        kind: "seqExpr",
+        stmts: [{ kind: "exprStmt", expr: value, loc: value.loc }],
+        result: dflt,
+        type: dflt.type,
+        loc: value.loc,
+    };
+}
+/** Complete an optional builtin argument. Statically undefined spellings
+ * preserve their effects and select the default; a runtime unit-armed union
+ * uses nullish selection when every non-unit arm is the expected type. */
+function lowerBuiltinOptionalDefault(L, node, expected, dflt, nullIsDefault = false) {
+    const undefinedArg = lowerStaticallyUndefinedBuiltinArg(L, node);
+    if (undefinedArg)
+        return defaultAfterUndefined(undefinedArg, dflt);
+    if (nullIsDefault && (L.typeOf(node).flags & ts.TypeFlags.Null) !== 0) {
+        return defaultAfterUndefined(L.lowerExpr(node), dflt);
+    }
+    const value = L.lowerExpr(node);
+    if (value.type.kind === "union") {
+        const def = L.unions.get(value.type.unionId);
+        const allowed = def?.arms.every((arm) => typeEquals(arm, expected) ||
+            arm.kind === "undefinedT" ||
+            (nullIsDefault && arm.kind === "nullT"));
+        if (allowed && def.arms.some((arm) => isUnitType(arm))) {
+            return { kind: "nullish", left: value, right: dflt, type: expected, loc: value.loc };
+        }
+    }
+    return L.coerceInto(node, value, expected);
+}
 /** Resolves an identifier to a supported builtin-module IMPORT BINDING:
    * a named import (through its alias, so `import { join as j }` matches)
    * whose declaration is an ImportSpecifier under a supported builtin
@@ -785,6 +845,191 @@ export function lowerBuiltinModuleCall(L, expr, bi, fn, loc) {
     if (bi.module === "fs" && bi.member === "watch") {
         return lowerFsWatchCall(L, expr, loc);
     }
+    // fs/promises.open(path[, flags[, mode]]) — string flags and numeric
+    // creation mode, with Node's "r"/0o666 defaults. The runtime wraps
+    // the descriptor in a shared FileHandle and settles/rejects exactly
+    // like the existing fs/promises operations.
+    if (bi.module === "fs/promises" && bi.member === "open") {
+        if (expr.arguments.length < 1 || expr.arguments.length > 3 || expr.arguments.some(ts.isSpreadElement)) {
+            L.noLowering(`fs.promises.open with ${expr.arguments.length} arguments`, expr, "use open(path[, stringFlags[, numericMode]])");
+        }
+        const path = L.lowerExprExpecting(expr.arguments[0], STRING);
+        const defaultFlags = { kind: "strLit", value: "r", type: STRING, loc };
+        const defaultMode = { kind: "numLit", value: 0o666, type: F64, loc };
+        const flags = expr.arguments[1]
+            ? lowerBuiltinOptionalDefault(L, expr.arguments[1], STRING, defaultFlags)
+            : defaultFlags;
+        const mode = expr.arguments[2]
+            ? lowerBuiltinOptionalDefault(L, expr.arguments[2], F64, defaultMode)
+            : defaultMode;
+        return {
+            kind: "libCall",
+            fn: "fsp.open",
+            args: [path, flags, mode],
+            type: { kind: "promise", inner: FILEHANDLE_T },
+            loc,
+        };
+    }
+    // fs.rename(oldPath, newPath, callback): the callback is a
+    // program-shaped closure (zero parameters are valid; the ordinary
+    // form receives NodeJS.ErrnoException | null). Keep it typed here so
+    // the backends can emit the same union-building adapter used by
+    // dns.lookup instead of losing the Error arm through a dyn boundary.
+    if (bi.module === "fs" && bi.member === "rename") {
+        if (expr.arguments.length !== 3 || expr.arguments.some(ts.isSpreadElement)) {
+            L.noLowering(`rename with ${expr.arguments.length} argument${expr.arguments.length === 1 ? "" : "s"}`, expr, "the supported form is rename(oldPath, newPath, callback)");
+        }
+        const oldPath = L.lowerExprExpecting(expr.arguments[0], STRING);
+        const newPath = L.lowerExprExpecting(expr.arguments[1], STRING);
+        let callback = L.lowerExpr(expr.arguments[2]);
+        // JS/checkJs callback values may arrive as checked-dynamic callables.
+        // Adapt them to the one error-first slot; the runtime passes a dyn
+        // Error on failure and null on success through the emitted thunk.
+        if (callback.type.kind === "dyn") {
+            callback = {
+                kind: "dynCheck",
+                value: callback,
+                type: funcOf([DYN], VOID),
+                loc: locOf(expr.arguments[2]),
+            };
+        }
+        let callbackOk = callback.type.kind === "func" && callback.type.params.length <= 1;
+        if (callbackOk && callback.type.kind === "func" && callback.type.params.length === 1) {
+            const param = callback.type.params[0];
+            if (param.kind === "dyn") {
+                callbackOk = true;
+            }
+            else if (param.kind === "union") {
+                const def = L.unions.get(param.unionId);
+                callbackOk = !!def &&
+                    def.arms.some((a) => a.kind === "nullT") &&
+                    def.arms.some((a) => a.kind === "object" && a.className === "%Error") &&
+                    def.arms.every((a) => a.kind === "nullT" || a.kind === "undefinedT" ||
+                        (a.kind === "object" && a.className === "%Error"));
+            }
+            else {
+                callbackOk = false;
+            }
+        }
+        if (!callbackOk) {
+            L.unsupported("SC1090", expr.arguments[2], "fs.rename callbacks must accept at most one Error | null parameter");
+        }
+        // TypeScript deliberately permits a value-returning function where a
+        // void callback is expected; Node ignores that value. Normalize the
+        // closure to the runtime's void callback ABI after validating its
+        // error-first parameter shape.
+        callback = voidizedCallback(L, callback, locOf(expr.arguments[2]));
+        return { kind: "libCall", fn: "fs.renameCb", args: [oldPath, newPath, callback], type: VOID, loc };
+    }
+    // fs.readSync(fd, buffer, offset, length[, position]) — normalize the
+    // current-offset forms to Node/libuv's -1 sentinel so the IR and native
+    // ABI stay fixed-width. A real numeric position is a positioned read
+    // and therefore must not advance the descriptor. Literal null is the
+    // documented current-offset spelling; richer nullable expressions must
+    // narrow first so no effectful evaluation is silently discarded.
+    if (bi.module === "fs" && bi.member === "readSync") {
+        const supported = "use readSync(fd, buffer, offset, length[, position]) with a numeric position or literal null; options objects and bigint positions have no lowering";
+        if ((expr.arguments.length !== 4 && expr.arguments.length !== 5) ||
+            expr.arguments.some(ts.isSpreadElement)) {
+            L.noLowering(`readSync with ${expr.arguments.length} argument${expr.arguments.length === 1 ? "" : "s"}`, expr, supported);
+        }
+        const args = [
+            L.lowerExprExpecting(expr.arguments[0], F64),
+            L.lowerExprExpecting(expr.arguments[1], BYTES_U8),
+            L.lowerExprExpecting(expr.arguments[2], F64),
+            L.lowerExprExpecting(expr.arguments[3], F64),
+        ];
+        const positionNode = expr.arguments[4];
+        let positionValueNode = positionNode;
+        while (positionValueNode && ts.isParenthesizedExpression(positionValueNode)) {
+            positionValueNode = positionValueNode.expression;
+        }
+        if (positionNode === undefined || positionValueNode.kind === ts.SyntaxKind.NullKeyword) {
+            args.push({ kind: "numLit", value: -1, type: F64, loc });
+        }
+        else {
+            const positionType = L.mapTypeOf(L.typeOf(positionNode));
+            if (positionType?.kind !== "f64") {
+                L.noLowering(`readSync with a '${positionType ? L.fmt(positionType) : L.checker.typeToString(L.typeOf(positionNode))}' position`, positionNode, supported);
+            }
+            args.push(L.lowerExprExpecting(positionNode, F64));
+        }
+        return { kind: "libCall", fn: "fs.readSync", args, type: F64, loc };
+    }
+    // fs.writeSync has two static families. Buffer writes use the classic
+    // (fd, buffer, offset, length[, position]) shape; string writes accept
+    // (fd, string[, position[, "utf8"]]). The runtime uses -1 for the
+    // current-offset forms. Node treats a negative, fractional, non-finite,
+    // or over-MAX_SAFE numeric write position like null rather than throwing;
+    // preserve the value here so the runtime can make that dispatch.
+    if (bi.module === "fs" && bi.member === "writeSync") {
+        const supported = 'use writeSync(fd, buffer, offset, length[, position]) or writeSync(fd, string[, position[, "utf8"]]); options objects, bigint positions, and other encodings have no lowering';
+        if (expr.arguments.some(ts.isSpreadElement) || expr.arguments.length < 2) {
+            L.noLowering(`writeSync with ${expr.arguments.length} argument${expr.arguments.length === 1 ? "" : "s"}`, expr, supported);
+        }
+        const dataNode = expr.arguments[1];
+        const dataType = L.mapTypeOf(L.typeOf(dataNode));
+        const fd = L.lowerExprExpecting(expr.arguments[0], F64);
+        const position = (node) => {
+            let valueNode = node;
+            while (valueNode && ts.isParenthesizedExpression(valueNode))
+                valueNode = valueNode.expression;
+            if (node === undefined || valueNode.kind === ts.SyntaxKind.NullKeyword) {
+                return { kind: "numLit", value: -1, type: F64, loc };
+            }
+            const t = L.mapTypeOf(L.typeOf(node));
+            if (t?.kind !== "f64") {
+                L.noLowering(`writeSync with a '${t ? L.fmt(t) : L.checker.typeToString(L.typeOf(node))}' position`, node, supported);
+            }
+            return L.lowerExprExpecting(node, F64);
+        };
+        if (dataType?.kind === "bytes") {
+            if (dataType.elem !== "u8") {
+                L.noLowering(`writeSync of '${L.fmt(dataType)}' data`, dataNode, "byte writes take Uint8Array/Buffer data");
+            }
+            if (expr.arguments.length !== 4 && expr.arguments.length !== 5) {
+                L.noLowering(`writeSync of Buffer data with ${expr.arguments.length} arguments`, expr, supported);
+            }
+            return {
+                kind: "libCall",
+                fn: "fs.writeSync",
+                args: [
+                    fd,
+                    L.lowerExprExpecting(dataNode, BYTES_U8),
+                    L.lowerExprExpecting(expr.arguments[2], F64),
+                    L.lowerExprExpecting(expr.arguments[3], F64),
+                    position(expr.arguments[4]),
+                ],
+                type: F64,
+                loc,
+            };
+        }
+        if (dataType?.kind === "string") {
+            if (expr.arguments.length > 4) {
+                L.noLowering(`writeSync of string data with ${expr.arguments.length} arguments`, expr, supported);
+            }
+            const encNode = expr.arguments[3];
+            let enc = { kind: "strLit", value: "utf8", type: STRING, loc };
+            if (encNode !== undefined) {
+                const encType = L.typeOf(encNode);
+                if (!encType.isStringLiteralType() || (encType.value !== "utf8" && encType.value !== "utf-8")) {
+                    L.noLowering("writeSync with a non-utf8 encoding", encNode, supported);
+                }
+                // Even though utf8 is the runtime's only encoding, the argument
+                // remains an ordinary JS argument: evaluate it in source order so
+                // a call/getter whose type is the accepted literal cannot vanish.
+                enc = L.lowerExprExpecting(encNode, STRING);
+            }
+            return {
+                kind: "libCall",
+                fn: "fs.writeStrSync",
+                args: [fd, L.lowerExprExpecting(dataNode, STRING), position(expr.arguments[2]), enc],
+                type: F64,
+                loc,
+            };
+        }
+        L.noLowering(`writeSync of '${dataType ? L.fmt(dataType) : L.checker.typeToString(L.typeOf(dataNode))}' data`, dataNode, supported);
+    }
     if (bi.module === "child_process" &&
         (bi.member === "execFileSync" || bi.member === "execSync")) {
         return L.lowerExecSyncCall(expr, bi.member === "execSync", loc);
@@ -1151,14 +1396,54 @@ export function lowerBuiltinModuleCall(L, expr, bi, fn, loc) {
             return { kind: "libCall", fn: "fs.writeFileSyncBytes", args: [path, data], type: VOID, loc };
         }
     }
-    // writeFileSync(p, data, options): the lowered options are a literal
+    // writeFileSync(p, data, options) / fs.promises.writeFile(p, data,
+    // options): the lowered options are a literal
     // `{ mode?: <number>, encoding?: "utf8" }` — the mode is open(2)'s
     // O_CREAT argument (creation only; an existing file keeps its
     // permissions, exactly Node), and the encoding may only spell the
-    // utf8 the runtime writes anyway. String data only — the Buffer form
-    // never carries options in the supported corpus.
-    if (bi.module === "fs" && bi.member === "writeFileSync" && expr.arguments.length === 3) {
+    // utf8 the runtime writes anyway. String data only — Buffer options
+    // remain outside the static surface.
+    const syncWriteOptions = bi.module === "fs" && bi.member === "writeFileSync";
+    const promiseWriteOptions = bi.module === "fs/promises" && bi.member === "writeFile";
+    if ((syncWriteOptions || promiseWriteOptions) && expr.arguments.length === 3) {
         const optsNode = expr.arguments[2];
+        const operation = promiseWriteOptions ? "fs.promises.writeFile" : "writeFileSync";
+        const plainFn = promiseWriteOptions ? "fsp.writeFile" : "fs.writeFileSync";
+        const modeFn = promiseWriteOptions ? "fsp.writeFileMode" : "fs.writeFileModeSync";
+        const resultType = promiseWriteOptions ? { kind: "promise", inner: VOID } : VOID;
+        // The runtime needs only `mode`, but every source option value is an
+        // ordinary JS expression. Stage path/data and then evaluate the option
+        // values in object-literal order before issuing the write; otherwise a
+        // call/getter statically typed as the accepted utf8 literal can vanish.
+        const finishWrite = (optionValues) => {
+            const path = L.lowerExprExpecting(expr.arguments[0], STRING);
+            const data = L.lowerExprExpecting(expr.arguments[1], STRING);
+            const pathLocal = L.declareHiddenLocal("%writePath", STRING);
+            const dataLocal = L.declareHiddenLocal("%writeData", STRING);
+            const ref = (local) => ({ kind: "varRef", localId: local.id, type: local.type, loc });
+            const stmts = [
+                { kind: "varDecl", localId: pathLocal.id, init: path, loc: path.loc },
+                { kind: "varDecl", localId: dataLocal.id, init: data, loc: data.loc },
+            ];
+            let mode = null;
+            for (const option of optionValues) {
+                if (option.kind === "effect") {
+                    stmts.push({ kind: "exprStmt", expr: option.value, loc: option.value.loc });
+                    continue;
+                }
+                const modeLocal = L.declareHiddenLocal("%writeMode", F64);
+                stmts.push({ kind: "varDecl", localId: modeLocal.id, init: option.value, loc: option.value.loc });
+                mode = ref(modeLocal);
+            }
+            const result = {
+                kind: "libCall",
+                fn: mode ? modeFn : plainFn,
+                args: mode ? [ref(pathLocal), ref(dataLocal), mode] : [ref(pathLocal), ref(dataLocal)],
+                type: resultType,
+                loc,
+            };
+            return { kind: "seqExpr", stmts, result, type: resultType, loc };
+        };
         // The bare-encoding spelling — writeFileSync(p, data, "utf-8") — is
         // the options record's encoding key alone: utf8 is what the runtime
         // writes anyway, so string data takes the plain write. Any OTHER
@@ -1167,12 +1452,10 @@ export function lowerBuiltinModuleCall(L, expr, bi, fn, loc) {
             const t = L.typeOf(optsNode);
             if (t.isStringLiteralType() && (t.value === "utf8" || t.value === "utf-8") &&
                 L.mapTypeOf(L.typeOf(expr.arguments[1]))?.kind === "string") {
-                const path = L.lowerExprExpecting(expr.arguments[0], STRING);
-                const data = L.lowerExprExpecting(expr.arguments[1], STRING);
-                return { kind: "libCall", fn: "fs.writeFileSync", args: [path, data], type: VOID, loc };
+                return finishWrite([{ kind: "effect", value: L.lowerExprExpecting(optsNode, STRING) }]);
             }
         }
-        let modeNode = null;
+        const optionValues = [];
         let ok = ts.isObjectLiteralExpression(optsNode);
         if (ok) {
             for (const p of optsNode.properties) {
@@ -1182,7 +1465,7 @@ export function lowerBuiltinModuleCall(L, expr, bi, fn, loc) {
                     break;
                 }
                 if (m.name === "mode") {
-                    modeNode = m.value;
+                    optionValues.push({ kind: "mode", value: L.lowerExprExpecting(m.value, F64) });
                 }
                 else if (m.name === "encoding") {
                     const t = L.typeOf(m.value);
@@ -1190,30 +1473,24 @@ export function lowerBuiltinModuleCall(L, expr, bi, fn, loc) {
                         ok = false;
                         break;
                     }
+                    optionValues.push({ kind: "effect", value: L.lowerExprExpecting(m.value, STRING) });
                 }
                 else if (m.name === "flag") {
                     // Documented, behavior-changing (open(2)'s disposition — 'a'
                     // IS appendFileSync), no lowering: fence by name.
-                    L.noLowering("writeFileSync with the flag option", p, "the write truncates-or-creates (Node's default 'w') — appendFileSync is the lowered append; other flags have no lowering");
+                    L.noLowering(`${operation} with the flag option`, p, "the write truncates-or-creates (Node's default 'w'); other flags have no lowering");
                 }
                 else {
                     // The options-record stance: documented keys with no lowering
                     // fence by name; undocumented keys drop like Node.
-                    fenceOrDropOptionKey(L, p, m.name, "writeFileSync", FS_WRITE_FILE_DOCUMENTED_OPTIONS, 'the supported options are { mode: <number>, encoding: "utf8" }');
+                    fenceOrDropOptionKey(L, p, m.name, operation, FS_WRITE_FILE_DOCUMENTED_OPTIONS, 'the supported options are { mode: <number>, encoding: "utf8" }');
                 }
             }
         }
         if (!ok || L.mapTypeOf(L.typeOf(expr.arguments[1]))?.kind !== "string") {
-            L.noLowering("fs.writeFileSync with 3 arguments", optsNode, 'the supported options are { mode: <number>, encoding: "utf8" } over string data');
-        }
-        const path = L.lowerExprExpecting(expr.arguments[0], STRING);
-        const data = L.lowerExprExpecting(expr.arguments[1], STRING);
-        if (modeNode === null) {
-            // encoding-only options change nothing: the plain write.
-            return { kind: "libCall", fn: "fs.writeFileSync", args: [path, data], type: VOID, loc };
+            L.noLowering(`${operation} with 3 arguments`, optsNode, 'the supported options are { mode: <number>, encoding: "utf8" } over string data');
         }
-        const mode = L.lowerExprExpecting(modeNode, F64);
-        return { kind: "libCall", fn: "fs.writeFileModeSync", args: [path, data, mode], type: VOID, loc };
+        return finishWrite(optionValues);
     }
     // zlib takes Buffers; a string argument (the lib admits it) gets the
     // wrap-it-first hint instead of a generic type mismatch.
@@ -3672,6 +3949,211 @@ function buildSpForEachFn(name, arity, fnRet, loc) {
         loc,
     };
 }
+/** Calls on an fs/promises FileHandle. The promise-returning methods run
+ * through the same synchronous descriptor primitives as fs.readSync /
+ * writeSync, then settle so failures reject at await. read/write retain
+ * the caller's buffer in the Node-shaped result record. */
+export function lowerFileHandleMethodCall(L, call, access) {
+    if (call.questionDotToken || access.questionDotToken)
+        return null;
+    if (L.mapTypeOf(L.typeOf(access.expression))?.kind !== "fileHandle")
+        return null;
+    if (!L.isStdlibMember(access))
+        return null;
+    const name = access.name.text;
+    const loc = locOf(call);
+    const receiver = () => L.lowerExprExpecting(access.expression, FILEHANDLE_T);
+    const promise = (inner) => ({ kind: "promise", inner });
+    const bool = (value) => ({ kind: "boolLit", value, type: BOOL, loc });
+    const num = (node, dflt) => {
+        const defaultValue = { kind: "numLit", value: dflt, type: F64, loc };
+        if (!node)
+            return { value: defaultValue, defaulted: bool(true) };
+        const undefinedArg = lowerStaticallyUndefinedBuiltinArg(L, node);
+        if (undefinedArg) {
+            return { value: defaultAfterUndefined(undefinedArg, defaultValue), defaulted: bool(true) };
+        }
+        if ((L.typeOf(node).flags & ts.TypeFlags.Null) !== 0) {
+            return { value: defaultAfterUndefined(L.lowerExpr(node), defaultValue), defaulted: bool(true) };
+        }
+        const value = L.lowerExpr(node);
+        if (value.type.kind === "union") {
+            const def = L.unions.get(value.type.unionId);
+            const units = def?.arms.filter(isUnitType) ?? [];
+            if (units.length > 0 &&
+                def?.arms.every((arm) => typeEquals(arm, F64) || isUnitType(arm))) {
+                // The normalized number and the separate "length was omitted"
+                // bit must observe one evaluation of a runtime optional union.
+                // Bind it in the numeric argument; the later bool argument reads
+                // the same hidden local (libCall arguments evaluate left-to-right).
+                const saved = L.declareHiddenLocal("%fhOptNum", value.type);
+                const savedRef = () => ({
+                    kind: "varRef", localId: saved.id, type: value.type, loc: value.loc,
+                });
+                let defaulted = {
+                    kind: "unionIsTag", unionId: value.type.unionId,
+                    tag: L.armTag(value.type.unionId, units[0]), negated: false,
+                    value: savedRef(), type: BOOL, loc: value.loc,
+                };
+                for (const unit of units.slice(1)) {
+                    defaulted = {
+                        kind: "logical", op: "||", left: defaulted,
+                        right: {
+                            kind: "unionIsTag", unionId: value.type.unionId,
+                            tag: L.armTag(value.type.unionId, unit), negated: false,
+                            value: savedRef(), type: BOOL, loc: value.loc,
+                        },
+                        type: BOOL,
+                        loc: value.loc,
+                    };
+                }
+                return {
+                    value: {
+                        kind: "seqExpr",
+                        stmts: [{ kind: "varDecl", localId: saved.id, init: value, loc: value.loc }],
+                        result: {
+                            kind: "nullish", left: savedRef(), right: defaultValue,
+                            type: F64, loc: value.loc,
+                        },
+                        type: F64,
+                        loc: value.loc,
+                    },
+                    defaulted,
+                };
+            }
+        }
+        return { value: L.coerceInto(node, value, F64), defaulted: bool(false) };
+    };
+    const utf8 = (node) => {
+        const dflt = { kind: "strLit", value: "utf8", type: STRING, loc };
+        if (!node)
+            return dflt;
+        const nodeType = L.typeOf(node);
+        const parts = nodeType.isUnionType() ? nodeType.getTypes() : [nodeType];
+        const supported = parts.every((t) => (t.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void | ts.TypeFlags.Null)) !== 0 ||
+            (t.isStringLiteralType() && (t.value === "utf8" || t.value === "utf-8")));
+        if (!supported) {
+            L.noLowering(`FileHandle.${name} with a non-utf8 encoding`, node, "only utf8 data is supported");
+        }
+        return lowerBuiltinOptionalDefault(L, node, STRING, dflt, true);
+    };
+    if (name === "close" || name === "stat") {
+        if (call.arguments.length !== 0)
+            L.noLowering(`FileHandle.${name} with arguments`, call);
+        return {
+            kind: "libCall",
+            fn: name === "close" ? "fileHandle.close" : "fileHandle.stat",
+            args: [receiver()],
+            type: promise(name === "close" ? VOID : { kind: "stats" }),
+            loc,
+        };
+    }
+    if (name === "readFile") {
+        if (call.arguments.length > 1) {
+            L.noLowering(`FileHandle.readFile with ${call.arguments.length} arguments`, call);
+        }
+        const type = L.mapTypeOf(L.typeOf(call));
+        if (type?.kind !== "promise")
+            L.badType(call, L.typeOf(call));
+        const encoding = utf8(call.arguments[0]);
+        if (typeEquals(type.inner, BYTES_U8)) {
+            return {
+                kind: "libCall", fn: "fileHandle.readFileBytes", args: [receiver(), encoding],
+                type, loc,
+            };
+        }
+        if (!typeEquals(type.inner, STRING))
+            L.badType(call, L.typeOf(call));
+        return {
+            kind: "libCall", fn: "fileHandle.readFile", args: [receiver(), encoding],
+            type, loc,
+        };
+    }
+    if (name === "writeFile" || name === "appendFile") {
+        if (call.arguments.length < 1 || call.arguments.length > 2) {
+            L.noLowering(`FileHandle.${name} with ${call.arguments.length} arguments`, call);
+        }
+        const dataNode = call.arguments[0];
+        const dataT = L.mapTypeOf(L.typeOf(dataNode));
+        // Evaluate a supplied utf8 encoding even for Buffer data, matching
+        // Node's argument order; it does not affect the bytes.
+        const encoding = utf8(call.arguments[1]);
+        if (dataT?.kind === "string") {
+            return {
+                kind: "libCall", fn: "fileHandle.writeFile",
+                args: [receiver(), L.lowerExprExpecting(dataNode, STRING), encoding],
+                type: promise(VOID), loc,
+            };
+        }
+        if (dataT?.kind === "bytes" && dataT.elem === "u8") {
+            return {
+                kind: "libCall", fn: "fileHandle.writeFileBytes",
+                args: [receiver(), L.lowerExprExpecting(dataNode, BYTES_U8), encoding],
+                type: promise(VOID), loc,
+            };
+        }
+        L.noLowering(`FileHandle.${name} of '${dataT ? L.fmt(dataT) : L.checker.typeToString(L.typeOf(dataNode))}' data`, dataNode, "string and Uint8Array data are supported");
+    }
+    if (name === "read") {
+        if (call.arguments.length < 1 || call.arguments.length > 4) {
+            L.noLowering(`FileHandle.read with ${call.arguments.length} arguments`, call, "use read(buffer[, offset[, length[, position]]])");
+        }
+        const buffer = L.lowerExprExpecting(call.arguments[0], BYTES_U8);
+        const type = L.mapTypeOf(L.typeOf(call));
+        if (type?.kind !== "promise" || type.inner.kind !== "record") {
+            L.badType(call, L.typeOf(call));
+        }
+        const offset = num(call.arguments[1], 0);
+        const length = num(call.arguments[2], -1);
+        const position = num(call.arguments[3], -1);
+        return {
+            kind: "libCall", fn: "fileHandle.read",
+            args: [
+                receiver(), buffer, offset.value, length.value,
+                position.value, length.defaulted,
+            ],
+            type, loc,
+        };
+    }
+    if (name === "write") {
+        if (call.arguments.length < 1 || call.arguments.length > 4) {
+            L.noLowering(`FileHandle.write with ${call.arguments.length} arguments`, call);
+        }
+        const dataNode = call.arguments[0];
+        const dataT = L.mapTypeOf(L.typeOf(dataNode));
+        const type = L.mapTypeOf(L.typeOf(call));
+        if (type?.kind !== "promise" || type.inner.kind !== "record") {
+            L.badType(call, L.typeOf(call));
+        }
+        if (dataT?.kind === "bytes" && dataT.elem === "u8") {
+            const offset = num(call.arguments[1], 0);
+            const length = num(call.arguments[2], -1);
+            const position = num(call.arguments[3], -1);
+            return {
+                kind: "libCall", fn: "fileHandle.writeBytes",
+                args: [
+                    receiver(), L.lowerExprExpecting(dataNode, BYTES_U8),
+                    offset.value, length.value, position.value,
+                    length.defaulted,
+                ],
+                type, loc,
+            };
+        }
+        if (dataT?.kind === "string") {
+            if (call.arguments.length > 3) {
+                L.noLowering(`FileHandle.write(string) with ${call.arguments.length} arguments`, call, 'use write(string[, position[, "utf8"]])');
+            }
+            const position = num(call.arguments[1], -1);
+            return {
+                kind: "libCall", fn: "fileHandle.writeStr",
+                args: [receiver(), L.lowerExprExpecting(dataNode, STRING), position.value, utf8(call.arguments[2])],
+                type, loc,
+            };
+        }
+        L.noLowering(`FileHandle.write of '${dataT ? L.fmt(dataT) : L.checker.typeToString(L.typeOf(dataNode))}' data`, dataNode, "string and Uint8Array data are supported");
+    }
+    L.noLowering(`FileHandle.${name}`, call, "fd, close(), read(), write(), readFile(), writeFile(), appendFile(), and stat() are the supported FileHandle members", L.checker.getSymbolAtLocation(access.name));
+}
 /** Method calls on Stats-typed receivers: isFile()/isDirectory()/
    * isSymbolicLink() are pure reads on the stat snapshot (a followed
    * statSync snapshot never answers true to isSymbolicLink — take
@@ -3694,7 +4176,7 @@ export function lowerStatsMethodCall(L, call, access) {
                 : "stats.isSymbolicLink";
         return { kind: "libCall", fn, args: [receiver], type: BOOL, loc: locOf(call) };
     }
-    L.noLowering(`Stats.${name}`, call, "isFile(), isDirectory(), isSymbolicLink(), size, and mtimeMs are the supported Stats members", L.checker.getSymbolAtLocation(access.name));
+    L.noLowering(`Stats.${name}`, call, "isFile(), isDirectory(), isSymbolicLink(), size, blocks, nlink, atimeMs, and mtimeMs are the supported Stats members", L.checker.getSymbolAtLocation(access.name));
 }
 /** `Atomics.wait(int32Array, idx, expected, timeoutMs)` — the
    * synchronous-sleep idiom (RouteStore's
@@ -3733,12 +4215,11 @@ export function lowerAtomicsCall(L, call, access) {
 }
 /** The property-read extensions this spoke owns, tried BEFORE the
    * lower-exprs intrinsic-property fallback (the lowerer's wrapper chains
-   * them): Stats.mtimeMs (milliseconds with the nanosecond fraction,
-   * Node's arithmetic) and SpawnSyncReturns.signal (the termination
-   * signal's name as the call site's `Signals | null` union — null for a
-   * normal exit or spawn failure; a timeout kill reports its killSignal,
-   * Node's shape). Null for everything else, so the ordinary chain (and
-   * its fences) keeps going. */
+   * them): the widened numeric Stats snapshot and SpawnSyncReturns.signal
+   * (the termination signal's name as the call site's `Signals | null` union
+   * — null for a normal exit or spawn failure; a timeout kill reports its
+   * killSignal, Node's shape). Null for everything else, so the ordinary
+   * chain (and its fences) keeps going. */
 export function lowerBuiltinExtraProperty(L, expr) {
     if (expr.questionDotToken && !L.chainHandled.has(expr))
         return null;
@@ -3752,12 +4233,23 @@ export function lowerBuiltinExtraProperty(L, expr) {
         return { kind: "recordGet", obj: receiver, shapeId: receiver.type.shapeId, field: "%enc", type: STRING, loc: locOf(expr) };
     }
     const kind = L.mapTypeOf(L.typeOf(expr.expression))?.kind;
-    if (kind !== "stats" && kind !== "spawnRes" && kind !== "child")
+    if (kind !== "stats" && kind !== "fileHandle" && kind !== "spawnRes" && kind !== "child")
         return null;
     if (kind === "child" ? !isChildSurfaceMember(L, expr) : !L.isStdlibMember(expr))
         return null;
     const name = expr.name.text;
     const loc = locOf(expr);
+    if (kind === "fileHandle") {
+        if (name === "fd") {
+            const receiver = L.lowerExprExpecting(expr.expression, FILEHANDLE_T);
+            return { kind: "libCall", fn: "fileHandle.fd", args: [receiver], type: F64, loc };
+        }
+        const methods = new Set(["close", "read", "write", "readFile", "writeFile", "appendFile", "stat"]);
+        if (methods.has(name)) {
+            L.unsupported("SC1090", expr, `FileHandle methods as values (call '${name}' directly)`);
+        }
+        L.noLowering(`FileHandle.${name}`, expr, "fd, close(), read(), write(), readFile(), writeFile(), appendFile(), and stat() are the supported FileHandle members", L.checker.getSymbolAtLocation(expr.name));
+    }
     // child.stdout / child.stderr — the piped-output streams: the
     // checker's `Readable | null` (null exactly when the slot was not
     // piped), constructed type-directedly in the backend over the
@@ -3779,9 +4271,11 @@ export function lowerBuiltinExtraProperty(L, expr) {
     }
     if (kind === "child")
         return null; // pid/exitCode/killed live in lowerIntrinsicProperty
-    if (kind === "stats" && name === "mtimeMs") {
+    if (kind === "stats" &&
+        (name === "blocks" || name === "nlink" || name === "atimeMs" || name === "mtimeMs")) {
         const receiver = L.lowerExpr(expr.expression);
-        return { kind: "libCall", fn: "stats.mtimeMs", args: [receiver], type: F64, loc };
+        const fn = `stats.${name}`;
+        return { kind: "libCall", fn, args: [receiver], type: F64, loc };
     }
     if (kind === "spawnRes" && name === "signal") {
         const receiver = L.lowerExpr(expr.expression);
@@ -4756,12 +5250,13 @@ export function lowerProcessEnvGet(L, expr) {
 export function lowerProcessMethodCall(L, call, access) {
     if (call.questionDotToken)
         return null;
-    // process.stdout.write(s) / process.stderr.write(s): the raw byte
-    // write — no newline, no formatting. stdout shares console.log's
+    // process.stdout.write(s[, encoding][, callback]) and stderr's twin:
+    // raw bytes, no newline or formatting. stdout shares console.log's
     // promptly-submitted stream, preserving source order. Node's boolean
     // is a backpressure signal; this synchronous write is constantly true.
-    // @types/node's wider forms (Buffer data, encoding, callback) typecheck
-    // and fence here.
+    // String encodings are compile-time-known BufferEncoding spellings;
+    // byte chunks evaluate but ignore the encoding like Node. Completion
+    // callbacks ride the next-tick queue and receive the success `null`.
     // process.stdin.destroy(): a deliberate no-op — no stream machinery
     // exists to tear down, and no other stdin surface observes the
     // destroyed state (SEMANTICS.md documents it).
@@ -4845,10 +5340,64 @@ export function lowerProcessMethodCall(L, call, access) {
         const stream = L.stdlibGlobalMember(access.expression, "process");
         if (stream === "stdout" || stream === "stderr") {
             const loc = locOf(call);
-            if (call.arguments.length !== 1) {
-                L.noLowering(`process.${stream}.write with ${call.arguments.length} arguments`, call, "the supported form is write(data) with one string — encodings and callbacks have no lowering");
+            const args = call.arguments;
+            if (args.length < 1 || args.length > 3 || args.some(ts.isSpreadElement)) {
+                L.noLowering(`process.${stream}.write with ${args.length} arguments`, call, "the supported forms are write(data[, encoding][, callback]) with a static BufferEncoding and completion callback");
             }
-            let data = L.lowerExpr(call.arguments[0]);
+            const secondNode = args[1];
+            const thirdNode = args[2];
+            const secondUndefined = secondNode
+                ? lowerStaticallyUndefinedBuiltinArg(L, secondNode)
+                : null;
+            const thirdUndefined = thirdNode
+                ? lowerStaticallyUndefinedBuiltinArg(L, thirdNode)
+                : null;
+            const secondT = secondNode && !secondUndefined ? L.mapTypeOf(L.typeOf(secondNode)) : undefined;
+            const callbackNode = args.length === 3 && !thirdUndefined
+                ? thirdNode
+                : args.length === 2 && secondT?.kind === "func"
+                    ? secondNode
+                    : undefined;
+            const encodingNode = (args.length === 3 || (args.length === 2 && callbackNode === undefined)) && !secondUndefined
+                ? secondNode
+                : undefined;
+            // Node's BufferEncoding aliases normalize before bytes are made.
+            // Preserve an effectful literal-typed expression even when its
+            // spelling folds (for example a function returning `"binary"`).
+            const encoding = (() => {
+                const defaultEncoding = { kind: "strLit", value: "utf8", type: STRING, loc };
+                if (secondUndefined) {
+                    return defaultAfterUndefined(secondUndefined, defaultEncoding);
+                }
+                if (!encodingNode) {
+                    return defaultEncoding;
+                }
+                const aliases = {
+                    utf8: "utf8", "utf-8": "utf8", hex: "hex", base64: "base64",
+                    base64url: "base64url", latin1: "latin1", binary: "latin1", ascii: "ascii",
+                    utf16le: "utf16le", "utf-16le": "utf16le", ucs2: "utf16le", "ucs-2": "utf16le",
+                };
+                const t = L.typeOf(encodingNode);
+                const raw = t.isStringLiteralType() ? t.value : undefined;
+                const canonical = raw !== undefined ? own(aliases, raw) : undefined;
+                if (canonical === undefined) {
+                    L.noLowering(`process.${stream}.write with this encoding`, encodingNode, 'use a literal "utf8", "hex", "base64", "base64url", "latin1", "binary", "ascii", "utf16le", or "ucs2" encoding');
+                }
+                const evaluated = L.lowerExprExpecting(encodingNode, STRING);
+                if (canonical === raw)
+                    return evaluated;
+                const normalized = { kind: "strLit", value: canonical, type: STRING, loc: locOf(encodingNode) };
+                return droppableStatic(evaluated)
+                    ? normalized
+                    : {
+                        kind: "seqExpr",
+                        stmts: [{ kind: "exprStmt", expr: evaluated, loc: evaluated.loc }],
+                        result: normalized,
+                        type: STRING,
+                        loc: evaluated.loc,
+                    };
+            })();
+            let data = L.lowerExpr(args[0]);
             // A checked-dynamic argument in a JS file takes the validated
             // string exit (the trust-but-verify boundary: commander's
             // `writeOut: (str) => process.stdout.write(str)` — str untyped):
@@ -4857,20 +5406,81 @@ export function lowerProcessMethodCall(L, call, access) {
             if (data.type.kind === "dyn" && isJsSourceFile(call.getSourceFile())) {
                 data = { kind: "dynCheck", value: data, type: STRING, loc };
             }
-            // The Buffer overload writes raw bytes through the same promptly
-            // submitted streams.
-            if (data.type.kind === "bytes" && data.type.elem === "u8") {
+            const isBytes = data.type.kind === "bytes" && data.type.elem === "u8";
+            if (!isBytes && data.type.kind !== "string") {
+                L.noLowering(`process.${stream}.write of non-string data`, args[0], "strings and Buffer/Uint8Array values write; narrow unions first");
+            }
+            let callback;
+            if (callbackNode) {
+                callback = L.lowerExpr(callbackNode);
+                if (callback.type.kind === "dyn" && isJsSourceFile(call.getSourceFile())) {
+                    callback = {
+                        kind: "dynCheck",
+                        value: callback,
+                        type: funcOf([DYN], VOID),
+                        loc: locOf(callbackNode),
+                    };
+                }
+                let callbackOk = callback.type.kind === "func" && callback.type.params.length <= 1;
+                if (callbackOk && callback.type.kind === "func" && callback.type.params.length === 1) {
+                    const param = callback.type.params[0];
+                    if (param.kind !== "dyn") {
+                        const def = param.kind === "union" ? L.unions.get(param.unionId) : undefined;
+                        callbackOk = !!def &&
+                            def.arms.some((a) => a.kind === "nullT") &&
+                            def.arms.some((a) => a.kind === "object" && a.className === "%Error") &&
+                            def.arms.every((a) => a.kind === "nullT" || a.kind === "undefinedT" ||
+                                (a.kind === "object" && a.className === "%Error"));
+                    }
+                }
+                if (!callbackOk) {
+                    L.unsupported("SC1090", callbackNode, "process output completion callbacks must accept at most one Error | null parameter");
+                }
+                callback = voidizedCallback(L, callback, locOf(callbackNode));
+            }
+            // Encoding- or callback-bearing writes use one fixed byte ABI. For
+            // strings, Buffer.from's encoder runs after data/encoding evaluation
+            // and before the callback expression; only its pure allocation moves
+            // earlier than Node's internal write conversion.
+            if (callback || args.length > 1 || isBytes) {
+                const bytes = isBytes
+                    ? data
+                    : { kind: "libCall", fn: "buffer.fromStr", args: [data, encoding], type: BYTES_U8, loc };
+                const defaultRuntimeEncoding = { kind: "strLit", value: "utf8", type: STRING, loc };
+                let runtimeEncoding = isBytes ? encoding : defaultRuntimeEncoding;
+                // An explicitly-undefined third argument is still evaluated after
+                // data and encoding, even though it schedules no callback. Strings
+                // already evaluate encoding while producing `bytes`; byte chunks
+                // fold both ignored argument effects into this final ABI slot.
+                if (thirdUndefined && !droppableStatic(thirdUndefined)) {
+                    const effects = isBytes
+                        ? [encoding, thirdUndefined].filter((effect) => !droppableStatic(effect))
+                        : [thirdUndefined];
+                    runtimeEncoding = {
+                        kind: "seqExpr",
+                        stmts: effects.map((effect) => ({ kind: "exprStmt", expr: effect, loc: effect.loc })),
+                        result: defaultRuntimeEncoding,
+                        type: STRING,
+                        loc: thirdUndefined.loc,
+                    };
+                }
+                if (callback) {
+                    return {
+                        kind: "libCall",
+                        fn: stream === "stdout" ? "process.stdoutWriteBytesCb" : "process.stderrWriteBytesCb",
+                        args: [bytes, runtimeEncoding, callback],
+                        type: BOOL,
+                        loc,
+                    };
+                }
                 return {
                     kind: "libCall",
                     fn: stream === "stdout" ? "process.stdoutWriteBytes" : "process.stderrWriteBytes",
-                    args: [data],
+                    args: [bytes, runtimeEncoding],
                     type: BOOL,
                     loc,
                 };
             }
-            if (data.type.kind !== "string") {
-                L.noLowering(`process.${stream}.write of non-string data`, call.arguments[0], "strings and Buffer/Uint8Array values write; narrow unions first");
-            }
             return {
                 kind: "libCall",
                 fn: stream === "stdout" ? "process.stdoutWrite" : "process.stderrWrite",
@@ -5326,13 +5936,29 @@ export function lowerNumberStaticCall(L, call, access) {
     }
     return null; // other Number statics land on the member fence
 }
-/** The Date slice: `Date.now()` and the COMPOSED
-   * `new Date(ms?).toISOString()` — the Date object between the two calls
-   * never exists (the crypto randomBytes(n).toString(enc) precedent). An
-   * omitted constructor argument completes with date.now; a one-argument
-   * form takes the milliseconds. String parsing, Y/M/D fields (local-time
-   * semantics), and Date VALUES stay fenced — lowerNew carries the hint.
-   * Null when this is neither form. */
+const DATE_GETTER_FNS = {
+    getFullYear: "date.getFullYear",
+    getUTCFullYear: "date.getUTCFullYear",
+    getMonth: "date.getMonth",
+    getUTCMonth: "date.getUTCMonth",
+    getDate: "date.getDate",
+    getUTCDate: "date.getUTCDate",
+    getDay: "date.getDay",
+    getUTCDay: "date.getUTCDay",
+    getHours: "date.getHours",
+    getUTCHours: "date.getUTCHours",
+    getMinutes: "date.getMinutes",
+    getUTCMinutes: "date.getUTCMinutes",
+    getSeconds: "date.getSeconds",
+    getUTCSeconds: "date.getUTCSeconds",
+    getMilliseconds: "date.getMilliseconds",
+    getUTCMilliseconds: "date.getUTCMilliseconds",
+    getTimezoneOffset: "date.getTimezoneOffset",
+};
+const DATE_METHOD_HINT = "getTime(), valueOf(), toISOString(), the local/UTC calendar getters, and getTimezoneOffset() are supported; Date setters and locale/string formatters have no lowering";
+/** The Date slice: statics plus read-only Date values backed by one
+   * TimeClip'd millisecond scalar. Construction lives in lowerNew;
+   * identity and mutating methods remain fenced. */
 export function lowerDateCall(L, call, access) {
     if (call.questionDotToken || access.questionDotToken)
         return null;
@@ -5363,60 +5989,107 @@ export function lowerDateCall(L, call, access) {
         }
         return { kind: "libCall", fn: "date.utc", args, type: F64, loc };
     }
-    if (access.name.text !== "toISOString" && access.name.text !== "getTime")
+    if (L.mapTypeOf(L.typeOf(access.expression))?.kind !== "date")
         return null;
-    const recv = access.expression;
-    if (!ts.isNewExpression(recv) || !ts.isIdentifier(recv.expression))
-        return null;
-    const sym = L.resolveValueSymbol(recv.expression);
-    if (!sym || sym.name !== "Date" || !L.isStdlibSymbol(sym))
-        return null;
-    if (access.name.text === "getTime") {
-        // The composed `new Date(x).getTime()` read — the Date value
-        // between the two never materializes (the toISOString precedent).
-        // new Date().getTime() IS Date.now(); the STRING form parses the
-        // bounded date-string grammar (the X509 validity shape portless's
-        // cert-expiry check reads, plus ECMA's own date-time format) and
-        // answers NaN elsewhere — a documented divergence from V8's wider
-        // parser. The ms form is pointless composition; the fence points at
-        // the value.
-        if (call.arguments.length !== 0) {
-            L.noLowering("getTime with arguments", call);
-        }
-        const ctorArgs = recv.arguments ?? [];
-        if (ctorArgs.length === 0) {
-            return { kind: "libCall", fn: "date.now", args: [], type: F64, loc };
-        }
-        if (ctorArgs.length !== 1) {
-            L.noLowering("new Date with year/month/day arguments", recv, "the field constructor is local-time; only new Date() and new Date(dateString) compose with .getTime()");
-        }
-        const arg = L.lowerExpr(ctorArgs[0]);
-        if (arg.type.kind !== "string") {
-            L.noLowering(`new Date of '${L.fmt(arg.type)}' values composed with .getTime()`, ctorArgs[0], arg.type.kind === "f64"
-                ? "new Date(ms).getTime() is the ms value — use it directly (or Date.now())"
-                : "the composed form parses date STRINGS — narrow unions first");
-        }
-        return { kind: "libCall", fn: "date.parseGetTime", args: [arg], type: F64, loc };
-    }
+    if (!L.isStdlibMember(access))
+        return null;
+    const name = access.name.text;
     if (call.arguments.length !== 0) {
-        L.noLowering("toISOString with arguments", call);
+        L.noLowering(`Date.prototype.${name} with arguments`, call, DATE_METHOD_HINT);
     }
-    const ctorArgs = recv.arguments ?? [];
-    let ms;
-    if (ctorArgs.length === 0) {
-        ms = { kind: "libCall", fn: "date.now", args: [], type: F64, loc };
+    const receiver = L.lowerExpr(access.expression);
+    if (receiver.type.kind !== "date")
+        L.badType(access.expression, L.typeOf(access.expression));
+    if (name === "getTime" || name === "valueOf") {
+        return {
+            kind: "libCall",
+            fn: name === "getTime" ? "date.getTime" : "date.valueOf",
+            args: [receiver],
+            type: F64,
+            loc,
+        };
     }
-    else if (ctorArgs.length === 1) {
-        const arg = L.lowerExpr(ctorArgs[0]);
-        if (arg.type.kind !== "f64") {
-            L.noLowering(`new Date of '${L.fmt(arg.type)}' values`, ctorArgs[0], "only the milliseconds form composes — new Date(ms).toISOString(); date-string parsing has no lowering");
-        }
-        ms = arg;
+    if (name === "toISOString") {
+        return { kind: "libCall", fn: "date.toISOStringValue", args: [receiver], type: STRING, loc };
     }
-    else {
-        L.noLowering("new Date with year/month/day arguments", recv, "the field constructor is local-time; only new Date() and new Date(ms) compose with .toISOString()");
+    const fn = DATE_GETTER_FNS[name];
+    if (fn !== undefined) {
+        return { kind: "libCall", fn, args: [receiver], type: F64, loc };
     }
-    return { kind: "libCall", fn: "date.toISOString", args: [ms], type: STRING, loc };
+    L.noLowering(`Date.prototype.${name}`, call, DATE_METHOD_HINT, L.checker.getSymbolAtLocation(access.name));
+}
+/* WHATWG label registry → native decoder id. The first 27 ids stay in the
+ * same order as scripts/gen-text-decoder-tables.mjs; the remaining ids match
+ * scr_bytes.c's compact enum. ISO-8859-8-I shares ISO-8859-8's byte table,
+ * and GBK/gb18030 share one decoder (their decoders are identical). */
+const TEXT_DECODER_SINGLE_BYTE_NAMES = [
+    "ibm866", "iso-8859-2", "iso-8859-3", "iso-8859-4", "iso-8859-5",
+    "iso-8859-6", "iso-8859-7", "iso-8859-8", "iso-8859-10", "iso-8859-13",
+    "iso-8859-14", "iso-8859-15", "iso-8859-16", "koi8-r", "koi8-u",
+    "macintosh", "windows-874", "windows-1250", "windows-1251", "windows-1252",
+    "windows-1253", "windows-1254", "windows-1255", "windows-1256", "windows-1257",
+    "windows-1258", "x-mac-cyrillic",
+];
+const TEXT_DECODER_UTF8_LABELS = new Set([
+    "unicode-1-1-utf-8", "unicode11utf8", "unicode20utf8", "utf-8", "utf8", "x-unicode20utf8",
+]);
+const TEXT_DECODER_LEGACY_LABELS = (() => {
+    const labels = Object.create(null);
+    const add = (encoding, names) => {
+        for (const name of names)
+            labels[name] = encoding;
+    };
+    const single = (name, aliases) => {
+        add(TEXT_DECODER_SINGLE_BYTE_NAMES.indexOf(name), aliases);
+    };
+    single("ibm866", ["866", "cp866", "csibm866", "ibm866"]);
+    single("iso-8859-2", ["csisolatin2", "iso-8859-2", "iso-ir-101", "iso8859-2", "iso88592", "iso_8859-2", "iso_8859-2:1987", "l2", "latin2"]);
+    single("iso-8859-3", ["csisolatin3", "iso-8859-3", "iso-ir-109", "iso8859-3", "iso88593", "iso_8859-3", "iso_8859-3:1988", "l3", "latin3"]);
+    single("iso-8859-4", ["csisolatin4", "iso-8859-4", "iso-ir-110", "iso8859-4", "iso88594", "iso_8859-4", "iso_8859-4:1988", "l4", "latin4"]);
+    single("iso-8859-5", ["csisolatincyrillic", "cyrillic", "iso-8859-5", "iso-ir-144", "iso8859-5", "iso88595", "iso_8859-5", "iso_8859-5:1988"]);
+    single("iso-8859-6", ["arabic", "asmo-708", "csiso88596e", "csiso88596i", "csisolatinarabic", "ecma-114", "iso-8859-6", "iso-8859-6-e", "iso-8859-6-i", "iso-ir-127", "iso8859-6", "iso88596", "iso_8859-6", "iso_8859-6:1987"]);
+    single("iso-8859-7", ["csisolatingreek", "ecma-118", "elot_928", "greek", "greek8", "iso-8859-7", "iso-ir-126", "iso8859-7", "iso88597", "iso_8859-7", "iso_8859-7:1987", "sun_eu_greek"]);
+    single("iso-8859-8", ["csiso88598e", "csiso88598i", "csisolatinhebrew", "hebrew", "iso-8859-8", "iso-8859-8-e", "iso-8859-8-i", "iso-ir-138", "iso8859-8", "iso88598", "iso_8859-8", "iso_8859-8:1988", "logical", "visual"]);
+    single("iso-8859-10", ["csisolatin6", "iso-8859-10", "iso-ir-157", "iso8859-10", "iso885910", "l6", "latin6"]);
+    single("iso-8859-13", ["iso-8859-13", "iso8859-13", "iso885913"]);
+    single("iso-8859-14", ["iso-8859-14", "iso8859-14", "iso885914"]);
+    single("iso-8859-15", ["csisolatin9", "iso-8859-15", "iso8859-15", "iso885915", "iso_8859-15", "l9"]);
+    single("iso-8859-16", ["iso-8859-16"]);
+    single("koi8-r", ["cskoi8r", "koi", "koi8", "koi8-r", "koi8_r"]);
+    single("koi8-u", ["koi8-ru", "koi8-u"]);
+    single("macintosh", ["csmacintosh", "mac", "macintosh", "x-mac-roman"]);
+    single("windows-874", ["dos-874", "iso-8859-11", "iso8859-11", "iso885911", "tis-620", "windows-874"]);
+    single("windows-1250", ["cp1250", "windows-1250", "x-cp1250"]);
+    single("windows-1251", ["cp1251", "windows-1251", "x-cp1251"]);
+    single("windows-1252", ["ansi_x3.4-1968", "ascii", "cp1252", "cp819", "csisolatin1", "ibm819", "iso-8859-1", "iso-ir-100", "iso8859-1", "iso88591", "iso_8859-1", "iso_8859-1:1987", "l1", "latin1", "us-ascii", "windows-1252", "x-cp1252"]);
+    single("windows-1253", ["cp1253", "windows-1253", "x-cp1253"]);
+    single("windows-1254", ["cp1254", "csisolatin5", "iso-8859-9", "iso-ir-148", "iso8859-9", "iso88599", "iso_8859-9", "iso_8859-9:1989", "l5", "latin5", "windows-1254", "x-cp1254"]);
+    single("windows-1255", ["cp1255", "windows-1255", "x-cp1255"]);
+    single("windows-1256", ["cp1256", "windows-1256", "x-cp1256"]);
+    single("windows-1257", ["cp1257", "windows-1257", "x-cp1257"]);
+    single("windows-1258", ["cp1258", "windows-1258", "x-cp1258"]);
+    single("x-mac-cyrillic", ["x-mac-cyrillic", "x-mac-ukrainian"]);
+    add(27, ["x-user-defined"]);
+    add(28, ["csunicode", "iso-10646-ucs-2", "ucs-2", "unicode", "unicodefeff", "utf-16", "utf-16le"]);
+    add(29, ["unicodefffe", "utf-16be"]);
+    add(30, ["chinese", "csgb2312", "csiso58gb231280", "gb18030", "gb2312", "gb_2312", "gb_2312-80", "gbk", "iso-ir-58", "x-gbk"]);
+    add(31, ["big5", "big5-hkscs", "cn-big5", "csbig5", "x-x-big5"]);
+    add(32, ["cseucpkdfmtjapanese", "euc-jp", "x-euc-jp"]);
+    add(33, ["csiso2022jp", "iso-2022-jp"]);
+    add(34, ["csshiftjis", "ms932", "ms_kanji", "shift-jis", "shift_jis", "sjis", "windows-31j", "x-sjis"]);
+    add(35, ["cseuckr", "csksc56011987", "euc-kr", "iso-ir-149", "korean", "ks_c_5601-1987", "ks_c_5601-1989", "ksc5601", "ksc_5601", "windows-949"]);
+    return labels;
+})();
+/** TextDecoder's get-an-encoding normalization: trim ASCII whitespace and
+ * fold ASCII case only (Unicode case folding must not manufacture a label). */
+function staticTextDecoderEncoding(label) {
+    const normalized = label
+        .replace(/^[\u0009\u000a\u000c\u000d\u0020]+|[\u0009\u000a\u000c\u000d\u0020]+$/g, "")
+        .replace(/[A-Z]/g, (char) => char.toLowerCase());
+    if (TEXT_DECODER_UTF8_LABELS.has(normalized))
+        return { kind: "utf8" };
+    const id = own(TEXT_DECODER_LEGACY_LABELS, normalized);
+    return id === undefined ? null : { kind: "legacy", id };
 }
 /** A direct construction of THE stdlib TextEncoder/TextDecoder, through
    * type-only wrappers. Name alone is never enough: a user class with the
@@ -5440,8 +6113,9 @@ function directTextCodecCtorOf(L, expr) {
 /** True when construction itself is effect-free and inside the already
    * lowered codec slice, so a const binding can be erased and calls can
    * resolve back to the initializer. TextDecoder's explicit label must be
-   * an actual literal here: accepting an arbitrary expression merely typed
-   * as "utf-8" would move or repeat its effects when the binding is erased. */
+   * an actual recognized literal here: accepting an arbitrary expression
+   * merely typed as a label would move or repeat its effects when the
+   * binding is erased. */
 function erasableTextCodecCtor(info) {
     const args = info.ctor.arguments ?? [];
     if (info.cls === "TextEncoder")
@@ -5451,9 +6125,9 @@ function erasableTextCodecCtor(info) {
     if (args.length !== 1)
         return false;
     const label = stripTypeCasts(args[0]);
-    return ts.isStringLiteralLike(label) && (label.text === "utf-8" || label.text === "utf8");
+    return ts.isStringLiteralLike(label) && staticTextDecoderEncoding(label.text) !== null;
 }
-/** `const encoder = new TextEncoder()` / the default TextDecoder twin:
+/** `const encoder = new TextEncoder()` / a statically-labelled TextDecoder twin:
    * compile-time alias plumbing with no runtime object. Calls through the
    * stable binding are recognized by textCodecReceiverOf below; any other
    * reached value use keeps the ordinary SC2020 representation fence. Both
@@ -5548,8 +6222,9 @@ function textCodecReceiverOf(L, expr) {
    * the idiomatic store-then-call equivalents. The codec object never
    * exists (the crypto/Date precedent); bare construction and value uses
    * are fenced with the composed hint. decode is the runtime's WHATWG
-   * utf-8 decode with the leading BOM stripped; a zero-argument decode()
-   * is "" like the spec's. encode IS Buffer.from(s, "utf8") — ScrStr
+   * decode for every recognized static label (with BOM handling for the
+   * Unicode encodings); a zero-argument decode() is "" like the spec's.
+   * encode IS Buffer.from(s, "utf8") — ScrStr
    * storage is well-formed UTF-8, so the bytes are identical (lone
    * surrogates became U+FFFD at string construction, exactly what the
    * spec's encoder emits). Null when this is neither supported form. */
@@ -5569,17 +6244,33 @@ export function lowerTextCodecCall(L, call, access) {
     const loc = locOf(call);
     const ctorArgs = recv.arguments ?? [];
     if (cls === "TextDecoder") {
-        // The constructor may spell the default label; anything else (other
-        // labels, { fatal }/{ ignoreBOM } options) changes behavior the
-        // runtime doesn't implement.
+        // The label must be statically known. A literal-typed effectful inline
+        // expression is accepted, but its evaluation is sequenced before the
+        // decode below; stored decoder aliases admit only actual literals.
         const labelT = ctorArgs.length >= 1 ? L.typeOf(ctorArgs[0]) : null;
-        const utf8Label = labelT !== null && labelT.isStringLiteralType() && (labelT.value === "utf-8" || labelT.value === "utf8");
-        if (ctorArgs.length > 1 || (ctorArgs.length === 1 && !utf8Label)) {
-            L.noLowering("new TextDecoder beyond the default utf-8", recv, "utf-8 with default options is the supported decoder: new TextDecoder().decode(bytes)");
-        }
+        const encoding = ctorArgs.length === 0
+            ? { kind: "utf8" }
+            : labelT !== null && labelT.isStringLiteralType()
+                ? staticTextDecoderEncoding(labelT.value)
+                : null;
+        if (ctorArgs.length > 1 || encoding === null) {
+            L.noLowering("new TextDecoder with runtime-valued options or an unknown label", recv, "a recognized literal WHATWG label with default options compiles");
+        }
+        const labelEffect = ctorArgs.length === 1
+            ? L.lowerExprExpecting(ctorArgs[0], STRING)
+            : null;
+        const afterLabel = (result) => labelEffect === null || labelEffect.kind === "strLit"
+            ? result
+            : {
+                kind: "seqExpr",
+                stmts: [{ kind: "exprStmt", expr: labelEffect, loc: labelEffect.loc }],
+                result,
+                type: result.type,
+                loc,
+            };
         if (call.arguments.length === 0) {
             // decode() with no input is "" per spec — nothing to evaluate.
-            return { kind: "strLit", value: "", type: STRING, loc };
+            return afterLabel({ kind: "strLit", value: "", type: STRING, loc });
         }
         if (call.arguments.length !== 1) {
             L.noLowering("decode with a stream option", call, "streaming decode has no lowering — decode whole buffers");
@@ -5589,7 +6280,16 @@ export function lowerTextCodecCall(L, call, access) {
         if (!(arg.type.kind === "bytes" && arg.type.elem === "u8")) {
             L.noLowering(`TextDecoder.decode of '${L.fmt(arg.type)}' values`, argNode, "Uint8Array/Buffer input decodes (ArrayBuffer values have no representation)");
         }
-        return { kind: "libCall", fn: "text.decode", args: [arg], type: STRING, loc };
+        const decoded = encoding.kind === "utf8"
+            ? { kind: "libCall", fn: "text.decode", args: [arg], type: STRING, loc }
+            : {
+                kind: "libCall",
+                fn: "text.decodeLegacy",
+                args: [arg, { kind: "numLit", value: encoding.id, type: F64, loc }],
+                type: STRING,
+                loc,
+            };
+        return afterLabel(decoded);
     }
     if (ctorArgs.length > 0) {
         L.noLowering("new TextEncoder with arguments", recv);