@scriptc/compiler 0.0.11 → 0.0.13

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

@@ -12,7 +12,7 @@ import * as ts from "../ts7/adapter.js";
 import { ladderFenceExpr, nodeThrowExpr } from "./lowerer.js";
 import { isJsSourceFile, locOf } from "../program.js";
 import { arrayOf, BOOL, BYTES_U8, canBoxFuncIntoDyn, canConvertToDyn, DYN, DYN_HANDLE_KINDS, F64, funcOf, HTTP2SESSION_T, HTTP2STREAM_T, HTTPCLIENTREQ_T, HTTPREQ_T, HTTPRES_T, NETSERVER_T, NETSOCKET_T, NULL_T, SECURECTX_T, STRING, UNDEFINED_T, typeKey, VOID } from "../../ir/nodes.js";
-import { builtinFenceHintOf, builtinModuleFnOf, fenceOrDropOptionKey, HTTP_CLIENT_DOCUMENTED_OPTIONS, HTTP_SERVER_DOCUMENTED_OPTIONS, HTTP2_SECURE_SERVER_DOCUMENTED_OPTIONS, HTTPS_CLIENT_DOCUMENTED_OPTIONS, sideEffectFreeOptionValue, TLS_SERVER_DOCUMENTED_OPTIONS, } from "./surfaces.js";
+import { AGENT_DOCUMENTED_OPTIONS, builtinFenceHintOf, builtinModuleFnOf, fenceOrDropOptionKey, HTTP_CLIENT_DOCUMENTED_OPTIONS, HTTP_SERVER_DOCUMENTED_OPTIONS, HTTP2_SECURE_SERVER_DOCUMENTED_OPTIONS, HTTPS_CLIENT_DOCUMENTED_OPTIONS, sideEffectFreeOptionValue, TLS_SERVER_DOCUMENTED_OPTIONS, } from "./surfaces.js";
 import { conditionalSpreadOf } from "./lower-exprs.js";
 /** The lowered value members of the net module — the surfaces.ts table's
  * spoke-side twin (the call SHAPES are all special-cased here, so the
@@ -152,7 +152,7 @@ function lowerCallbackArg(L, node, what, maxParams, paramOk, paramHint, dynTuple
         // hoisted `function onConn(socket)` — dyn params), or an
         // arguments-reading rest function: box it and adapt through the
         // dynCheck function boundary like the dyn flavor above — the event
-        // payloads box into the DOM (handles by reference) and the body's
+        // payloads box into the checked-dynamic tree (handles by reference) and the body's
         // member uses dispatch at runtime.
         const boxed = { kind: "dynFrom", value: cb, type: DYN, loc: locOf(node) };
         const toT = funcOf([...dynTuple], VOID);
@@ -291,7 +291,7 @@ function h2HeadersCallbackAdapter(L, node, what, handleKind, withStatus, loc) {
     // value or an arguments-reading rest function of dyn params): wrap it
     // in a dynCheck to the CANONICAL event signature, then build the header
     // record and invoke through that typed boundary (handles box by
-    // reference, the record boxes to a DOM object — the net server-callbacks
+    // reference, the record boxes to a dyn object — the net server-callbacks
     // precedent). The synthesized record IS the shape the adapter builds.
     const handleT = handleKind === "http2Stream" ? HTTP2STREAM_T : null;
     const isDynCb = cb.type.kind === "dyn" ||
@@ -1244,6 +1244,40 @@ function lowerNetSocketMethodCall(L, call, access) {
         const ms = L.lowerExprExpecting(args[0], F64);
         return { kind: "libCall", fn: "net.sockSetTimeout", args: [receiver, ms], type: VOID, loc };
     }
+    if (name === "pause" || name === "resume") {
+        // Flow control (the struct's flag comments in scr_net.c): pause holds
+        // reads off — kernel/TCP backpressure is the buffer; resume flows
+        // (and discards sans listeners, so 'end' is reachable). Both answer
+        // the socket, Node's chaining.
+        if (args.length !== 0) {
+            L.noLowering(`${name} with ${args.length} arguments`, call, `the form is ${name}()`);
+        }
+        const receiver = handleReceiver(L, access.expression, NETSOCKET_T);
+        const fn = name === "pause" ? "net.sockPause" : "net.sockResume";
+        return { kind: "libCall", fn, args: [receiver], type: NETSOCKET_T, loc };
+    }
+    if (name === "setNoDelay") {
+        // TCP_NODELAY on the live fd; missing/undefined means true (Node).
+        // Answers the socket, Node's chaining.
+        if (args.length > 1) {
+            L.noLowering(`setNoDelay with ${args.length} arguments`, call, "the form is setNoDelay(noDelay?)");
+        }
+        const receiver = handleReceiver(L, access.expression, NETSOCKET_T);
+        const enable = args.length === 1
+            ? L.lowerExprExpecting(args[0], BOOL)
+            : boolLit(true, loc);
+        return { kind: "libCall", fn: "net.sockSetNoDelay", args: [receiver, enable], type: NETSOCKET_T, loc };
+    }
+    if (name === "destroySoon") {
+        // end() now, destroy once the FIN actually flushed — Node's
+        // 'finish'-then-destroy.
+        requireStatementPosition(L, call, "socket.destroySoon()");
+        if (args.length !== 0) {
+            L.noLowering(`destroySoon with ${args.length} arguments`, call, "the form is destroySoon()");
+        }
+        const receiver = handleReceiver(L, access.expression, NETSOCKET_T);
+        return { kind: "libCall", fn: "net.sockDestroySoon", args: [receiver], type: VOID, loc };
+    }
     if (name === "read") {
         // socket.read(n?) — the demux peek. Answers the interned
         // `Buffer | null` union: exactly n buffered bytes, or null (Node's
@@ -1311,6 +1345,12 @@ function lowerNetSocketMethodCall(L, call, access) {
                             : "net.sockOnConnect";
             return { kind: "libCall", fn, args: [receiver, cb, once], type: VOID, loc };
         }
+        if (event === "finish") {
+            // Fires once when the FIN goes out — once either way (the event
+            // happens at most once per socket).
+            const { cb } = lowerCallbackArg(L, args[1], "finish listeners", 0, () => false, "use ()", []);
+            return { kind: "libCall", fn: "net.sockOnFinish", args: [receiver, cb], type: VOID, loc };
+        }
         if (event === "secureConnect") {
             // The TLS client's post-handshake event: on a TLS socket the
             // 'connect' list already fires at establishment (scr_net.c's
@@ -1501,7 +1541,7 @@ function lowerH2SessionMethodCall(L, call, access) {
         return { kind: "libCall", fn: "http2.sessionDestroy", args: [receiver()], type: VOID, loc };
     }
     if (name === "settings") {
-        // session.settings(obj[, cb]): the settings record crosses as a DOM
+        // session.settings(obj[, cb]): the settings record crosses as a dyn
         // value (the checked-dynamic boundary — object literals box); the
         // callback fires on the peer's ACK ((err, settings, duration) in the
         // dyn flavor, zero-arg in the typed one).
@@ -1515,7 +1555,7 @@ function lowerH2SessionMethodCall(L, call, access) {
             const cbV = L.lowerExpr(args[1]);
             if (cbV.type.kind === "dyn") {
                 // The dyn callback keeps Node's exact (err, settings, duration)
-                // shape — the runtime fires it through the DOM.
+                // shape — the runtime fires it through the checked-dynamic tree.
                 return { kind: "libCall", fn: "http2.sessionSettingsDynCb", args: [receiver(), settingsArg, cbV], type: VOID, loc };
             }
             const { cb } = lowerCallbackArg(L, args[1], "settings callbacks", 0, () => false, "use () — or a dynamic (mustCall-wrapped) callback for the (err, settings, duration) shape", []);
@@ -1529,7 +1569,7 @@ function lowerH2SessionMethodCall(L, call, access) {
         const evT = L.typeOf(args[0]);
         const event = evT.isStringLiteralType() ? evT.value : null;
         if (event === "localSettings" || event === "remoteSettings") {
-            // The settings payload crosses as a DOM value: dyn (mustCall)
+            // The settings payload crosses as a dyn value: dyn (mustCall)
             // listeners fire with the settings record; zero-arg typed
             // listeners register plainly.
             const local = boolLit(event === "localSettings", loc);
@@ -1794,6 +1834,17 @@ export function lowerServerProperty(L, expr) {
         const receiver = handleReceiver(L, expr.expression, NETSOCKET_T);
         return { kind: "libCall", fn: "net.sockWritable", args: [receiver], type: BOOL, loc };
     }
+    if (recvKind === "netSocket" && L.isStdlibMember(expr) && expr.name.text === "bytesWritten") {
+        // Every byte the write paths accepted (buffered included — Node
+        // counts those too; plaintext on TLS sockets).
+        const receiver = handleReceiver(L, expr.expression, NETSOCKET_T);
+        return { kind: "libCall", fn: "net.sockBytesWritten", args: [receiver], type: F64, loc };
+    }
+    if (recvKind === "netSocket" && L.isStdlibMember(expr) && expr.name.text === "readable") {
+        // true until the read half is done (peer FIN / destroy).
+        const receiver = handleReceiver(L, expr.expression, NETSOCKET_T);
+        return { kind: "libCall", fn: "net.sockReadable", args: [receiver], type: BOOL, loc };
+    }
     if (recvKind === "netSocket" && L.isStdlibMember(expr) && expr.name.text === "remoteAddress") {
         // `string | undefined` — Node's read-time caching: a value read while
         // connected survives destroy; never-read sockets answer undefined
@@ -1845,7 +1896,7 @@ export function lowerServerProperty(L, expr) {
         if (m === "pendingSettingsAck")
             return { kind: "libCall", fn: "http2.sessionPendingSettingsAck", args: [recv()], type: BOOL, loc };
         if (m === "localSettings" || m === "remoteSettings") {
-            // The settings record crosses as a DOM value (the d.ts types it
+            // The settings record crosses as a dyn value (the d.ts types it
             // `any`): member reads ride the checked-dynamic keyed read.
             return {
                 kind: "libCall", fn: "http2.sessionSettingsGet",
@@ -1900,7 +1951,7 @@ function lowerRequestHandlerArg(L, node) {
         // A CHECKED-DYNAMIC handler (test/common's mustCall wrapper around
         // the (req, res) listener — the canonical suite shape): adapt
         // through the dynCheck function boundary. The adapter boxes req/res
-        // as DOM HANDLE values (SCR_DYN_HANDLE — reference identity) and
+        // as dyn HANDLE values (SCR_DYN_HANDLE — reference identity) and
         // calls the wrapper through the checked-dynamic machinery; member
         // uses inside the wrapped body dispatch back onto the same http
         // entry points at runtime.
@@ -2037,6 +2088,113 @@ function lowerHttpCreateServerForms(L, expr, what, loc) {
  * createServer (Node's Server class IS the factory's product); called
  * from lowerNew ahead of the stdlib-constructor fence. Null when the
  * callee is not the http module's Server. */
+/** `new http.Agent(opts?)` / `new https.Agent(opts?)` (property access or
+ * named import): the Agent lowers to a checked-dynamic HANDLE —
+ * getName/destroy and the sockets/requests/freeSockets counters dispatch
+ * through the dyn handle ops, and the request path threads it (the
+ * requestAgent rows). Options parse at the LITERAL construction site:
+ * keepAlive (a boolean value — TRUE throws the runtime's named pooling
+ * fence: this client dials one connection per request), keepAliveMsecs /
+ * maxSockets / maxFreeSockets / timeout / port as numbers, scheduling
+ * DROPS (no free pool exists, so selection order cannot observe), other
+ * documented keys fence by name, and undocumented keys drop like Node
+ * drops them. Null when the callee isn't the http/https Agent. */
+export function lowerHttpAgentNew(L, expr) {
+    const callee = expr.expression;
+    const bi = ts.isPropertyAccessExpression(callee) && callee.name.text === "Agent"
+        ? L.builtinMemberOf(callee)
+        : ts.isIdentifier(callee)
+            ? L.builtinImportOf(callee)
+            : null;
+    if (!bi || bi.member !== "Agent" || (bi.module !== "http" && bi.module !== "https"))
+        return null;
+    const loc = locOf(expr);
+    const api = `new ${bi.module}.Agent`;
+    const numLit = (value) => ({ kind: "numLit", value, type: F64, loc });
+    const boolAt = (value) => ({ kind: "boolLit", value, type: BOOL, loc });
+    let keepAlive = boolAt(false);
+    let kaMsecs = numLit(-1);
+    let maxSockets = numLit(-1);
+    let maxFree = numLit(-1);
+    let timeout = numLit(-1);
+    let port = numLit(-1);
+    const args = expr.arguments ?? [];
+    if (args.length > 1) {
+        L.noLowering(`${api} with ${args.length} arguments`, expr, "the supported form is new Agent(options?)");
+    }
+    if (args.length === 1) {
+        const optsNode = stripParensAndCasts(args[0]);
+        if (!ts.isObjectLiteralExpression(optsNode)) {
+            L.noLowering(`${api} with a non-literal options value`, args[0], "spell the options as an object literal at the construction site");
+        }
+        for (const prop of optsNode.properties) {
+            if (ts.isSpreadAssignment(prop)) {
+                L.noLowering(`${api} with an options spread`, prop, "write each option inline");
+            }
+            let initializer;
+            if (ts.isPropertyAssignment(prop) &&
+                (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name))) {
+                initializer = prop.initializer;
+            }
+            else if (ts.isShorthandPropertyAssignment(prop)) {
+                initializer = null;
+            }
+            else {
+                L.noLowering(`${api} options with computed keys`, prop, "each option must be a plain `name: value` (or shorthand) entry with a literal key");
+            }
+            const key = prop.name.text;
+            const lowerVal = (want) => {
+                const v = initializer !== null
+                    ? L.lowerExpr(initializer)
+                    : L.lowerShorthandValue(prop);
+                if (v.type.kind === "dyn") {
+                    return { kind: "dynCheck", value: v, type: want === "bool" ? BOOL : F64, loc: locOf(prop) };
+                }
+                if (v.type.kind !== want) {
+                    L.noLowering(`a ${api} '${key}' option of '${L.fmt(v.type)}' values`, prop, want === "bool" ? "the option value must be a boolean" : "the option value must be a number");
+                }
+                return v;
+            };
+            switch (key) {
+                case "keepAlive":
+                    keepAlive = lowerVal("bool");
+                    break;
+                case "keepAliveMsecs":
+                    kaMsecs = lowerVal("f64");
+                    break;
+                case "maxSockets":
+                    maxSockets = lowerVal("f64");
+                    break;
+                case "maxFreeSockets":
+                    maxFree = lowerVal("f64");
+                    break;
+                case "timeout":
+                    timeout = lowerVal("f64");
+                    break;
+                case "port":
+                    // Node merges agent options under portless request options —
+                    // the settable defaultPort carries this one.
+                    port = lowerVal("f64");
+                    break;
+                case "scheduling":
+                    // Free-socket selection order: no free pool exists here (no
+                    // keep-alive reuse), so the choice cannot observe — dropped.
+                    if (initializer !== null)
+                        L.lowerExpr(initializer); // evaluate, like Node
+                    break;
+                default:
+                    fenceOrDropOptionKey(L, prop, key, api, AGENT_DOCUMENTED_OPTIONS, "keepAlive, keepAliveMsecs, maxSockets, maxFreeSockets, timeout, port, and scheduling are the supported options");
+            }
+        }
+    }
+    return {
+        kind: "libCall",
+        fn: "http.agentNew",
+        args: [boolAt(bi.module === "https"), keepAlive, kaMsecs, maxSockets, maxFree, timeout, port],
+        type: DYN,
+        loc,
+    };
+}
 export function lowerHttpServerNew(L, expr) {
     const callee = expr.expression;
     const isHttpServer = (ts.isPropertyAccessExpression(callee) &&
@@ -2176,7 +2334,7 @@ function lowerTlsServerOptionsOrDyn(L, node, what) {
         return { dyn: v };
     // A typed options RECORD binding (`const options = { key, cert, ... };
     // createServer(options)` — the Node-suite spelling): box it into the
-    // DOM and hand the whole record to the runtime walk (the divergence-66
+    // dyn and hand the whole record to the runtime walk (the divergence-66
     // stance — members read at runtime, out-of-bounds ones throw the
     // catchable fence, undefined/undocumented ones drop). canConvertToDyn
     // now folds in the bytes-bearing option records the walker can box.
@@ -2246,7 +2404,7 @@ function lowerTlsConnectCall(L, expr, loc) {
         }
     }
     // The options value rides whole to the runtime walk: dyn passes
-    // directly; a typed record that converts boxes into the DOM.
+    // directly; a typed record that converts boxes into the checked-dynamic tree.
     let opts;
     if (optsNode !== null) {
         const o = L.lowerExpr(optsNode);
@@ -2265,7 +2423,7 @@ function lowerTlsConnectCall(L, expr, loc) {
             L.noLowering("tls.connect without a port or options", expr, FORMS_HINT);
         }
         // No options: Node's defaults (rejectUnauthorized: true) — the
-        // runtime walk reads an absent record (the DOM undefined).
+        // runtime walk reads an absent record (the dyn undefined).
         opts = {
             kind: "dynFrom",
             value: { kind: "unitLit", unit: "undefined", type: UNDEFINED_T, loc },
@@ -2341,9 +2499,45 @@ function lowerTlsModuleCall(L, expr, bi, loc) {
         }
         return { kind: "libCall", fn: "tls.createSecureContext", args: [opts.cert, opts.key], type: SECURECTX_T, loc };
     }
+    // The CA-store introspection pair (scr_tls_ca.c — its own link gate, no
+    // mbedTLS): getCACertificates(type?) answers the per-type cached PEM
+    // string array (an omitted type completes to "default", Node's own
+    // default; unknown strings throw Node's ERR_INVALID_ARG_VALUE at
+    // runtime), and setDefaultCACertificates(certs) replaces the default
+    // set and the client trust anchors. rootCertificates is a VALUE read —
+    // lowerTlsRootCertificates below.
+    if (bi.member === "getCACertificates") {
+        if (args.length > 1) {
+            L.noLowering(`getCACertificates with ${args.length} arguments`, expr);
+        }
+        const typeArg = args.length === 1
+            ? L.lowerExprExpecting(args[0], STRING)
+            : { kind: "strLit", value: "default", type: STRING, loc };
+        return { kind: "libCall", fn: "tlsca.get", args: [typeArg], type: arrayOf(STRING), loc };
+    }
+    if (bi.member === "setDefaultCACertificates") {
+        if (args.length !== 1) {
+            L.noLowering(`setDefaultCACertificates with ${args.length} arguments`, expr);
+        }
+        const certs = L.lowerExpr(args[0]);
+        if (certs.type.kind !== "array" || certs.type.elem.kind !== "string") {
+            L.noLowering(`setDefaultCACertificates of a '${L.fmt(certs.type)}' value`, args[0], "a string[] of PEM certificates is the lowered shape — decode Buffer/typed-array entries to strings first");
+        }
+        return { kind: "libCall", fn: "tlsca.set", args: [certs], type: VOID, loc };
+    }
     L.noLowering(`tls.${bi.member}`, expr, builtinFenceHintOf("tls", bi.member) ??
         "createServer({ cert, key }, handler) and createSecureContext({ cert, key }) are the lowered tls module functions", L.resolveValueSymbol(expr.expression));
 }
+/** The tls.rootCertificates VALUE read (any import spelling): the same
+ * cached array getCACertificates("bundled") answers — Node's own
+ * equality (test-tls-get-ca-certificates-bundled pins certs ===
+ * rootCertificates). Null for other members (the property chains keep
+ * trying). */
+export function lowerTlsRootCertificates(L, bi, loc) {
+    if (bi.module !== "tls" || bi.member !== "rootCertificates")
+        return null;
+    return { kind: "libCall", fn: "tlsca.root", args: [], type: arrayOf(STRING), loc };
+}
 const httpClientFnBindings = new WeakMap();
 export function httpClientFnBindingOf(L, sym) {
     return httpClientFnBindings.get(L)?.get(sym);
@@ -2663,17 +2857,42 @@ function lowerHttp2ModuleCall(L, expr, bi, loc) {
         return { kind: "libCall", fn: "http2.connect", args: [auth, reject, ca], type: HTTP2SESSION_T, loc };
     }
     if (bi.member === "getDefaultSettings") {
-        // The constant defaults record, as a DOM value (the d.ts types it
+        // The constant defaults record, as a dyn value (the d.ts types it
         // `any` — reads ride the checked-dynamic keyed read).
         return { kind: "libCall", fn: "http2.getDefaultSettings", args: [], type: DYN, loc };
     }
     if (bi.member === "createSecureServer") {
-        if (args.length !== 1) {
-            L.noLowering(`createSecureServer with ${args.length} arguments`, expr, "the supported form is createSecureServer({ allowHTTP1: true, cert, key }) — register the handler with server.on(\"request\", (req, res) => ...)");
+        if (args.length < 1 || args.length > 2) {
+            L.noLowering(`createSecureServer with ${args.length} arguments`, expr, "the supported forms are createSecureServer(options[, onRequestHandler]) with options { allowHTTP1?, cert, key }");
         }
         const optsNode = args[0];
+        // The eager (req, res) handler — Node routes it as the first
+        // 'request' listener; both flavors' compat layers serve it (the
+        // allowHTTP1 server's HTTP/1.1 handles, the h2 server's compat
+        // handles over streams).
+        const handlerNode = args.length === 2 ? args[1] : null;
         if (!ts.isObjectLiteralExpression(optsNode)) {
-            L.noLowering("createSecureServer with a non-literal options argument", optsNode, "pass the options as an object literal: { allowHTTP1: true, cert, key }");
+            // The RUNTIME options record (the divergence-66 stance, the
+            // tls/https.createServerDyn precedent): allowHTTP1/cert/key read
+            // at runtime, out-of-bounds TLS members throw the catchable
+            // runtime fence, h2 session-tuning keys drop exactly like the
+            // literal walk ignores them.
+            const v = L.lowerExpr(optsNode);
+            let dynOpts;
+            if (v.type.kind === "dyn") {
+                dynOpts = v;
+            }
+            else if (canConvertToDyn(v.type, (id) => L.shapes.get(id), (id) => L.unions.get(id))) {
+                dynOpts = { kind: "dynFrom", value: v, type: DYN, loc: locOf(optsNode) };
+            }
+            else {
+                L.noLowering("createSecureServer with a non-literal options argument", optsNode, "pass the options as an object literal ({ allowHTTP1: true, cert, key }) or a runtime record of those members");
+            }
+            if (handlerNode === null) {
+                return { kind: "libCall", fn: "http2.createSecureServerDyn", args: [dynOpts], type: NETSERVER_T, loc };
+            }
+            const cb = lowerRequestHandlerArg(L, handlerNode);
+            return { kind: "libCall", fn: "http2.createSecureServerDynCb", args: [dynOpts, cb], type: NETSERVER_T, loc };
         }
         let cert = null;
         let key = null;
@@ -2835,6 +3054,9 @@ function lowerHttp2ModuleCall(L, expr, bi, loc) {
         if (cert === null || key === null) {
             L.noLowering("createSecureServer without both cert and key", optsNode, "the supported options object is { allowHTTP1?, cert, key } (PEM strings or Buffers)");
         }
+        if (sni !== null && handlerNode !== null) {
+            L.noLowering("createSecureServer with both an SNICallback and an eager handler", expr, "register the handler separately: server.on(\"request\", (req, res) => ...)");
+        }
         if (!allowHttp1) {
             // The REAL h2-over-TLS server (scr_http2.c + scr_tls.c): ALPN
             // advertises h2 alone and the h2 session attaches at establishment
@@ -2844,11 +3066,19 @@ function lowerHttp2ModuleCall(L, expr, bi, loc) {
             if (sni !== null) {
                 L.noLowering("createSecureServer with an SNICallback and no allowHTTP1", optsNode, "SNICallback lowers on the allowHTTP1 compatibility server — the ALPN=h2 server serves one cert/key pair");
             }
+            if (handlerNode !== null) {
+                const cb = lowerRequestHandlerArg(L, handlerNode);
+                return { kind: "libCall", fn: "http2.createSecureServerH2Req", args: [cert, key, cb], type: NETSERVER_T, loc };
+            }
             return { kind: "libCall", fn: "http2.createSecureServerH2", args: [cert, key], type: NETSERVER_T, loc };
         }
         if (sni !== null) {
             return { kind: "libCall", fn: "http2.createSecureServerSni", args: [cert, key, sni], type: NETSERVER_T, loc };
         }
+        if (handlerNode !== null) {
+            const cb = lowerRequestHandlerArg(L, handlerNode);
+            return { kind: "libCall", fn: "http2.createSecureServerReq", args: [cert, key, cb], type: NETSERVER_T, loc };
+        }
         return { kind: "libCall", fn: "http2.createSecureServer", args: [cert, key], type: NETSERVER_T, loc };
     }
     L.noLowering(`http2.${bi.member}`, expr, builtinFenceHintOf("http2", bi.member) ??
@@ -2918,6 +3148,8 @@ function lowerHttpClientCall(L, expr, member, loc, secure = false) {
     let connCb = null;
     /** agent: false — inject Connection: close into the request head. */
     let agentClose = null;
+    /** agent: <Agent value> — the requestAgent rows thread the handle. */
+    let agentVal = null;
     for (const prop of optsNode.properties) {
         // Shorthand entries ({ port } for { port: port }) are the natural
         // spelling at these call sites — the shorthand's VALUE lowering
@@ -3055,8 +3287,11 @@ function lowerHttpClientCall(L, expr, member, loc, secure = false) {
                 // model, so it LOWERS (the header injects below). null/undefined
                 // pick the default agent, whose keep-alive request header the
                 // compiled client already sends (socket REUSE stays the
-                // documented divergence either way). Agent instances configure
-                // pooling the runtime does not have — fence.
+                // documented divergence either way). An Agent VALUE (the lowered
+                // `new http.Agent(...)` handle — a checked-dynamic value) threads
+                // through the requestAgent rows: getName-keyed maxSockets
+                // accounting over one-dial-per-request connections; a runtime
+                // non-Agent value is Node's ERR_INVALID_ARG_TYPE.
                 const e = initializer !== null ? stripParensAndCasts(initializer) : null;
                 if (e !== null && e.kind === ts.SyntaxKind.FalseKeyword) {
                     agentClose = prop;
@@ -3067,9 +3302,14 @@ function lowerHttpClientCall(L, expr, member, loc, secure = false) {
                         (ts.isIdentifier(e) && e.text === "undefined"))) {
                     break; // the default agent: what the agent-free call compiles
                 }
-                L.noLowering(`a ${member} 'agent' option carrying an Agent value`, prop, "compiled clients dial one connection per request and close it with the response — " +
-                    "agent: false (lowered: sends Connection: close) and agent: null/undefined (the default) " +
-                    "compile; pooling Agent instances have no lowering");
+                const v = initializer !== null
+                    ? L.lowerExpr(initializer)
+                    : L.lowerShorthandValue(prop);
+                if (v.type.kind !== "dyn") {
+                    L.noLowering(`a ${member} 'agent' option of '${L.fmt(v.type)}' values`, prop, "the agent is the checked-dynamic Agent handle new http.Agent(...) answers " +
+                        "(or false / null / undefined)");
+                }
+                agentVal = v;
                 break;
             }
             default:
@@ -3107,12 +3347,21 @@ function lowerHttpClientCall(L, expr, member, loc, secure = false) {
         // exists — a silent half-use; set headers.host instead.
         L.noLowering(`${member} mixing createConnection with hostname/host/port`, optsNode, "the dialer supplies the socket — set the Host header via headers: { host: ... } instead");
     }
+    if (agentVal !== null && connCb !== null) {
+        L.noLowering(`${member} mixing an agent value with createConnection`, optsNode, "both own the dial — pass one or the other");
+    }
+    if (agentVal !== null && binding !== null) {
+        L.noLowering(`${member} through a module-function binding with an agent value`, optsNode, "call http.request/https.request directly when passing an Agent");
+    }
     host ??= strLit("localhost");
     // The binding mode's default port follows the runtime dial: 443 on the
     // TLS arm, 80 on the plain one — exactly each client's own default.
+    // With an AGENT the sentinel -1 says "no port option": the runtime
+    // consults the agent's (settable) defaultPort first, Node's merge.
     port ??= binding !== null
         ? { kind: "ternary", cond: secureExpr(), then: numLit(443), else_: numLit(80), type: F64, loc }
-        : numLit(secure === true ? 443 : 80);
+        : agentVal !== null ? numLit(-1)
+            : numLit(secure === true ? 443 : 80);
     path ??= strLit("/");
     method ??= strLit("GET");
     timeout ??= numLit(0);
@@ -3132,14 +3381,20 @@ function lowerHttpClientCall(L, expr, member, loc, secure = false) {
         ca ??= strLit(""); /* none: /etc/ssl/cert.pem stands in for Node's roots */
         base.push(reject, ca);
     }
+    if (agentVal !== null)
+        base.push(agentVal);
     if (binding !== null)
         base.unshift(secureExpr());
     if (args.length === 1) {
-        const fn = binding !== null ? "https.requestFn" : secure === true ? "https.request" : "http.request";
+        const fn = binding !== null ? "https.requestFn"
+            : secure === true ? (agentVal !== null ? "https.requestAgent" : "https.request")
+                : agentVal !== null ? "http.requestAgent" : "http.request";
         return { kind: "libCall", fn, args: base, type: HTTPCLIENTREQ_T, loc };
     }
     const { cb } = lowerCallbackArg(L, args[1], "response callbacks", 1, (p) => p.kind === "httpReq", "use (res) or ()", [HTTPREQ_T]);
-    const fn = binding !== null ? "https.requestFnCb" : secure === true ? "https.requestCb" : "http.requestCb";
+    const fn = binding !== null ? "https.requestFnCb"
+        : secure === true ? (agentVal !== null ? "https.requestAgentCb" : "https.requestCb")
+            : agentVal !== null ? "http.requestAgentCb" : "http.requestCb";
     return { kind: "libCall", fn, args: [...base, cb], type: HTTPCLIENTREQ_T, loc };
 }
 /** The headers option of http.request: an object literal with literal