@scriptc/compiler 0.0.0 → 0.0.2

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

@@ -0,0 +1,650 @@
+/* Island-boundary lowering: jsval marshaling into the island (jsvalIn and
+ * its boundary fences), island-expression detection, the island method-call
+ * surface (Math and number/string methods under --dynamic), and the npm
+ * package boundary fences for node_modules-declared symbols. */
+import * as ts from "../ts7/adapter.js";
+import { F64, JSVAL, MAX_ISLAND_CALLBACK_ARITY, STRING, VOID, canMarshalTypedFuncIntoIsland, isUnitType } from "../../ir/nodes.js";
+import { ISLAND_SURFACE, STATIC_MATH_FNS, boundaryIntoIslandMsg } from "./surfaces.js";
+import { requiresDynamicApiDiag, requiresDynamicPackageDiag } from "../../diagnostics/diagnostic.js";
+import { isCjsJsFile, locOf, npmPackageNameOf } from "../program.js";
+import { pureReemittable } from "./lower-exprs.js";
+import { PoisonError, newFnCtx, own } from "./lowerer.js";
+/** True iff the checker's type for this node maps to jsval ('any') —
+   * the island test in front of every engine-op lowering (receivers,
+   * callees, assignment targets). ALSO true for an identifier bound to an
+   * island-HANDLE local whose declared type says otherwise (`const {
+   * readFileSync } = await import("fs")` — the binding's declared
+   * function/Buffer type never held the value; the handle is the value's
+   * only story), so its uses dispatch to engine ops instead of
+   * re-reporting the declared type. The one exclusion is promise-mapped
+   * declared types: a package promise held as a handle keeps its existing
+   * checker-driven dispatch (the await/.catch bridge lowerings own it). */
+export function isIslandExpr(L, node) {
+    const mapped = L.mapTypeOf(L.typeOf(node));
+    if (mapped?.kind === "jsval")
+        return true;
+    if (mapped?.kind !== "promise" && ts.isIdentifier(node)) {
+        const local = L.resolveLocal(node);
+        if (local?.type.kind === "jsval")
+            return true;
+        // File-scope handle bindings (a module global slotted jsval by the
+        // island-pattern or unchecked-overload rules) take the same rule as
+        // locals: the handle is the value's only story.
+        if (!local && L.globalOf(node)?.type.kind === "jsval")
+            return true;
+    }
+    return false;
+}
+/** Marshal a static value into the island (--dynamic): primitives by
+   * value, JSON-safe composites as a deep copy (the documented aliasing
+   * divergence). Values with no island representation — closures, class
+   * instances, promises, un-validated 'unknown' — are rejected with the
+   * boundary message. */
+export function jsvalIn(L, e, node) {
+    if (e.type.kind === "jsval")
+        return e;
+    // Bare unit literals (`undefined` / `null` in an 'any' slot): the
+    // engine's own units — unit-typed expressions are literals (units have
+    // no other producers), so dropping the operand loses nothing.
+    if (isUnitType(e.type)) {
+        return { kind: "jsOp", op: e.type.kind === "undefinedT" ? "undefLit" : "nullLit", args: [], type: JSVAL, loc: e.loc };
+    }
+    if (e.type.kind === "dyn") {
+        L.unsupported("SC1100", node, "passing 'unknown' values into dynamically-executed ('any'-typed) code (validate with 'as <type>' first)");
+    }
+    // Closures cross INTO the island as host functions — THE package
+    // callback pattern (`.action((a, b) => ...)`). Unannotated params stay
+    // 'any' (contextual typing against package signatures) and pass through
+    // as handles; TYPED params convert at call time through the validated-
+    // exit machinery (strict primitives, JSON round-trip composites,
+    // `T | undefined` taking the undefined arm for an absent argument), so
+    // a conversion failure throws back into the island as a TypeError.
+    // Anything outside both shapes gets the specific fix, not the generic
+    // boundary recitation.
+    if (e.type.kind === "func" &&
+        !canMarshalTypedFuncIntoIsland(e.type, (id) => L.shapes.get(id), (id) => L.unions.get(id))) {
+        L.unsupported("SC1090", node, `functions with this signature crossing into dynamically-executed code ` +
+            `(a callback passed to a package/'any' API may take 'any' parameters — ` +
+            `leave them unannotated so contextual typing keeps them 'any' — or parameters ` +
+            `convertible at the boundary (number, string, boolean, JSON-safe ` +
+            `records/arrays/unions, 'T | undefined'), and return 'any', void, number, ` +
+            `string, boolean, a JSON-safe composite, or a Promise of the primitive kinds${e.type.kind === "func" && e.type.params.length > MAX_ISLAND_CALLBACK_ARITY
+                ? `; at most ${MAX_ISLAND_CALLBACK_ARITY} parameters`
+                : ""})`);
+    }
+    if (e.type.kind !== "func" && !L.boundarySafe(e.type)) {
+        // A RegExp crossing INTO the island (`z.string().regex(/^a+$/)` —
+        // the validation-pattern argument): the engine compiles its own
+        // from source+flags. A fresh engine RegExp per marshal — identity
+        // and lastIndex state do not cross (SEMANTICS.md). Only literal
+        // and pure-read spellings lower (the rebuild reads the operand
+        // twice); computed regex values keep the boundary fence.
+        if (e.type.kind === "regex") {
+            const re = islandRegexpOf(e);
+            if (re)
+                return re;
+        }
+        // jsval-BEARING composites (an `any[]` value, a record holding one)
+        // have no JSON marshal but an honest per-field/per-element island
+        // construction — the same lift the implicit coercion path uses.
+        if (L.jsvalLiftable(e.type))
+            return L.jsvalLiftExpr(e, e.loc);
+        L.unsupported("SC1090", node, boundaryIntoIslandMsg(L.fmt(e.type)));
+    }
+    return { kind: "jsMarshal", value: e, type: JSVAL, loc: e.loc };
+}
+/** A static RegExp value as a fresh ENGINE RegExp — `new RegExp(source,
+   * flags)` in the island, the pattern TEXT crossing (both worlds compile
+   * the ES-spec grammar). Literals rebuild from their own pattern/flags;
+   * pure reads (a regex-typed binding) read the source/flags intrinsics —
+   * the rebuild emits the operand twice, so effectful producers return
+   * null into the caller's boundary fence. */
+export function islandRegexpOf(e) {
+    if (e.type.kind !== "regex")
+        return null;
+    const loc = e.loc;
+    let src;
+    let flags;
+    if (e.kind === "regexLit") {
+        src = { kind: "strLit", value: e.pattern, type: STRING, loc };
+        flags = { kind: "strLit", value: e.flags, type: STRING, loc };
+    }
+    else if (pureReemittable(e)) {
+        src = { kind: "regexIntrinsic", method: "source", receiver: e, args: [], type: STRING, loc };
+        flags = { kind: "regexIntrinsic", method: "flags", receiver: e, args: [], type: STRING, loc };
+    }
+    else {
+        return null;
+    }
+    const ctor = { kind: "jsOp", op: "globalGet", name: "RegExp", args: [], type: JSVAL, loc };
+    return {
+        kind: "jsOp",
+        op: "construct",
+        args: [
+            ctor,
+            { kind: "jsMarshal", value: src, type: JSVAL, loc },
+            { kind: "jsMarshal", value: flags, type: JSVAL, loc },
+        ],
+        type: JSVAL,
+        loc,
+    };
+}
+/** The gate on every ISLAND_SURFACE lowering: under --dynamic the caller
+   * proceeds to engine ops; without it the use site is a per-site SC2012
+   * (poison-recovered, so every site in the program reports — and the
+   * coverage report groups them under "runs with --dynamic"). */
+export function requireDynamicApi(L, feature, node) {
+    if (L.dynamic)
+        return;
+    L.pushDiag(requiresDynamicApiDiag(feature, locOf(node)));
+    throw new PoisonError();
+}
+/** Resolves an identifier to an island-backed ambient GLOBAL function
+   * (parseFloat, isFinite). Provenance, not name: the
+   * symbol's declaration must live in the ambient file, so a user function
+   * named `parseFloat` never matches. */
+export function islandGlobalFnOf(L, ident) {
+    const entry = own(ISLAND_SURFACE.globals, ident.text);
+    if (!entry)
+        return null;
+    const symbol = L.resolveValueSymbol(ident);
+    if (!symbol || !L.isStdlibSymbol(symbol))
+        return null;
+    return entry;
+}
+/** USER-code `fetch(url)` / `fetch(url, init)` — the island-backed ambient
+   * global (provenance, not the name: a user's own `fetch` never matches).
+   * The engine's own fetch executes (the same one embedded npm code calls —
+   * scr_fetch.c over the native net/tls stack): the url marshals in (strings; template
+   * results), an init OBJECT LITERAL builds natively in the island through
+   * the existing 'any'-contextual literal path (RequestInit maps to jsval,
+   * so field values marshal individually and an AbortSignal handle passes
+   * straight through), and the engine's promise bridges to a static
+   * `promise of jsval` (jsBridgePromise) — `await fetch(...)` parks the
+   * fiber like any await and resumes with the Response HANDLE. Member
+   * reads/calls on the handle are engine ops; typed extraction happens at
+   * the user's narrowing sites through the validated-exit machinery.
+   * Without --dynamic every call site is its own SC2012. Null for
+   * anything that isn't THE ambient fetch, so lowerCall keeps trying. */
+export function lowerFetchCall(L, call) {
+    const callee = call.expression;
+    if (!ts.isIdentifier(callee) || callee.text !== "fetch")
+        return null;
+    if (call.questionDotToken)
+        return null;
+    const symbol = L.resolveValueSymbol(callee);
+    if (!symbol || !L.isStdlibSymbol(symbol))
+        return null;
+    if (call.arguments.length < 1 || call.arguments.length > 2)
+        return null;
+    L.requireDynamicApi("'fetch'", call);
+    const loc = locOf(call);
+    const fetchFn = { kind: "jsOp", op: "globalGet", name: "fetch", args: [], type: JSVAL, loc };
+    // Init OBJECT LITERALS build natively in the island (the general
+    // 'any'-contextual literal path can't claim them: the optional param's
+    // contextual type is `RequestInit | undefined`, a union) — field
+    // values marshal individually, so an AbortSignal HANDLE passes
+    // through and dashed header keys ("content-type") are plain engine
+    // property names. Non-literal inits marshal as a whole (JSON-safe
+    // records; a signal field inside one fences with the boundary rule).
+    const args = call.arguments.map((a) => ts.isObjectLiteralExpression(a) ? lowerIslandObjectLiteral(L, a) : L.jsvalIn(L.lowerExpr(a), a));
+    const raw = { kind: "jsOp", op: "callFn", args: [fetchFn, ...args], type: JSVAL, loc };
+    return { kind: "jsBridgePromise", value: raw, type: { kind: "promise", inner: JSVAL }, loc };
+}
+/** Dynamic `import(spec)` — the island's module system at a USER site.
+   * Under --dynamic the call lowers to island.importDyn(key): the engine
+   * loads the module (embedded npm graph, a shipped local .js/.mjs the
+   * build embedded, or a builtin shim — collectDynamicImports resolved and
+   * embedded the specifier at collection time) and answers an ENGINE
+   * promise of the namespace object, bridged to a static
+   * `Promise<jsval>` (jsBridgePromise, the fetch precedent) — so `await
+   * import(x)` parks the fiber and resumes with the namespace HANDLE, and
+   * a load/evaluation failure crosses as a catchable rejection, exactly
+   * where Node puts it. Specifiers must be string literals: the module
+   * graph is a BUILD-time artifact — a runtime-computed name has nothing
+   * to embed, and the fence says so. Static builds report the per-site
+   * SC2012. Null for anything that isn't `import(...)`. */
+export function lowerDynamicImportCall(L, call) {
+    if (call.expression.kind !== ts.SyntaxKind.ImportKeyword)
+        return null;
+    L.requireDynamicApi("'import()'", call);
+    const loc = locOf(call);
+    const arg = call.arguments[0];
+    if (arg === undefined || !ts.isStringLiteralLike(arg)) {
+        L.unsupported("SC1090", call, "dynamic import() of computed specifiers (the module graph embeds at " +
+            "build time — the specifier must be a string literal)");
+    }
+    if (call.arguments.length !== 1) {
+        L.unsupported("SC1090", call, "dynamic import() with import attributes");
+    }
+    const res = L.dynImports.get(`${call.getSourceFile().fileName}\u0000${arg.text}`);
+    if (!res) {
+        // Collection walks every file before bodies lower, so a missing
+        // entry is a lowerer bug, not user error.
+        throw new Error(`lowerer bug: unresolved dynamic import '${arg.text}'`);
+    }
+    if (res.kind === "program-module") {
+        return lowerOwnModuleImport(L, call, arg);
+    }
+    if (res.kind !== "module") {
+        throw new PoisonError(); // resolution failed — collection reported it
+    }
+    const raw = {
+        kind: "libCall",
+        fn: "island.importDyn",
+        args: [{ kind: "strLit", value: res.key, type: STRING, loc }],
+        type: JSVAL,
+        loc,
+    };
+    return { kind: "jsBridgePromise", value: raw, type: { kind: "promise", inner: JSVAL }, loc };
+}
+/** Dynamic `import()` of one of the program's OWN modules: the compiled
+   * module's exports, marshaled into the engine as a namespace object.
+   * The site lowers to `Promise.resolve().then(<builder>)` in the engine —
+   * the builder is a synthesized compiled function (dynNsBuilderOf) that
+   * runs on the engine MICROTASK, calls the target module's run-once %init
+   * (Node's evaluation point for a module first reached through import():
+   * after the importer's synchronous code, before the .then handlers), and
+   * returns the exports object. Node differences (numbered divergences,
+   * pinned in island.test.ts): the namespace is a SNAPSHOT taken when the
+   * import resolves (Node's is live), a plain engine object (no Module
+   * toStringTag, keys still sorted like Node's, each import minting a
+   * fresh object where Node caches one), and exports with no island
+   * representation (classes, generic functions, un-marshalable
+   * signatures) cross as trap functions that throw a pointed TypeError
+   * when USED — the namespace still builds, exactly like Node still
+   * resolves it. */
+function lowerOwnModuleImport(L, call, arg) {
+    const loc = locOf(call);
+    let dep = null;
+    const modSym = L.checker.getSymbolAtLocation(arg);
+    for (const d of (modSym ? L.checker.declarationsOf(modSym) : [])) {
+        if (ts.isSourceFile(d) && !d.isDeclarationFile) {
+            dep = d;
+            break;
+        }
+    }
+    if (dep !== null && (dep.fileName.endsWith(".cts") || isCjsJsFile(dep))) {
+        L.unsupported("SC1090", call, `dynamic import of the program's own CommonJS module '${arg.text}' ` +
+            "(its namespace comes from module.exports through Node's CJS lexer, " +
+            "which has no compiled story — require it, or import it statically)");
+    }
+    const builder = dep !== null ? dynNsBuilderOf(L, dep, loc) : null;
+    if (builder === null) {
+        L.unsupported("SC1090", call, `dynamic import of the program's own module '${arg.text}' ` +
+            "(this module is not part of the compiled module graph — import it statically)");
+    }
+    const promiseCtor = { kind: "jsOp", op: "globalGet", name: "Promise", args: [], type: JSVAL, loc };
+    const resolved = { kind: "jsOp", op: "callMethod", name: "resolve", args: [promiseCtor], type: JSVAL, loc };
+    const builderFn = { kind: "func", params: [], ret: JSVAL };
+    const marshaled = {
+        kind: "jsMarshal",
+        value: { kind: "closure", fnName: builder, captures: [], type: builderFn, loc },
+        type: JSVAL,
+        loc,
+    };
+    const chained = { kind: "jsOp", op: "callMethod", name: "then", args: [resolved, marshaled], type: JSVAL, loc };
+    return { kind: "jsBridgePromise", value: chained, type: { kind: "promise", inner: JSVAL }, loc };
+}
+/** The namespace-BUILDER function for one program module, synthesized on
+   * first demand and shared by every import() of that module (deterministic
+   * name per file tag, so the discovery and emit passes agree). Body: the
+   * module's guarded %init (skipped for the entry — it is running or ran),
+   * then `return { <sorted exports> }` as an engine object. Null when the
+   * module never joined the compiled graph (no %init exists — an empty
+   * preflight order or a cycle the extension refused). */
+function dynNsBuilderOf(L, dep, loc) {
+    const cached = L.dynNsBuilders.get(dep);
+    if (cached !== undefined)
+        return cached;
+    const initName = L.initNameOf.get(dep);
+    if (initName === undefined)
+        return null;
+    const rawTag = L.fileTag.get(dep) ?? "";
+    const name = `%dynns.${rawTag === "" ? "e." : rawTag.replace(/^%/, "")}`;
+    L.dynNsBuilders.set(dep, name);
+    L.fnStack.push(newFnCtx(true, null, null, JSVAL));
+    try {
+        const body = [];
+        if (dep !== L.entry) {
+            body.push({
+                kind: "exprStmt",
+                expr: { kind: "call", callee: initName, args: [], type: VOID, loc },
+                loc,
+            });
+        }
+        // Node sorts module-namespace keys (code-unit order); tsc erases
+        // type-only exports, so only VALUE exports appear.
+        const entries = [];
+        const modSym = L.checker.getSymbolAtLocation(dep);
+        modSym?.getExports().forEach((sym, key) => {
+            const n = String(key);
+            if (!n.startsWith("__") && n !== "export=")
+                entries.push([n, sym]);
+        });
+        entries.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+        const args = [];
+        for (const [exportName, sym] of entries) {
+            const value = exportJsvalValue(L, exportName, sym, loc);
+            if (value === null)
+                continue;
+            args.push({ kind: "jsMarshal", value: { kind: "strLit", value: exportName, type: STRING, loc }, type: JSVAL, loc }, value);
+        }
+        body.push({ kind: "return", value: { kind: "jsOp", op: "objLit", args, type: JSVAL, loc }, loc });
+        const ctx = L.ctx;
+        L.liftedFns.push({
+            name,
+            params: [],
+            returnType: JSVAL,
+            locals: ctx.locals,
+            captures: ctx.captures ?? [],
+            body,
+            loc,
+        });
+    }
+    finally {
+        L.fnStack.pop();
+    }
+    return name;
+}
+/** One export's island value for the namespace object — the jsvalIn
+   * marshal set (primitives and JSON-safe composites by deep copy, units as
+   * the engine's own, marshalable closures as host functions, jsval-bearing
+   * composites through the per-field lift), with every UN-marshalable
+   * export crossing as a trap function that throws a pointed TypeError when
+   * called or constructed — the namespace still builds (Node resolves it;
+   * only the USE has no compiled story). Null for exports that do not exist
+   * at runtime (type-only). */
+function exportJsvalValue(L, name, sym, loc) {
+    const trap = (what) => islandTrapFnValue(L, `the '${name}' export is ${what} of the compiled program, which cannot cross into dynamically-executed code yet`, loc);
+    let resolved = sym;
+    if (sym.flags & ts.SymbolFlags.Alias) {
+        // `export type { x }` / `export { type x }`: erased at runtime.
+        for (const d of L.checker.declarationsOf(sym)) {
+            if (ts.isExportSpecifier(d)) {
+                const exportDecl = d.parent.parent;
+                if (d.isTypeOnly || (ts.isExportDeclaration(exportDecl) && exportDecl.isTypeOnly))
+                    return null;
+            }
+            if (ts.isImportSpecifier(d)) {
+                const clause = d.parent.parent;
+                if (d.isTypeOnly || (ts.isImportClause(clause) && clause.phaseModifier === ts.SyntaxKind.TypeKeyword))
+                    return null;
+            }
+        }
+        resolved = L.checker.getAliasedSymbol(sym);
+    }
+    if (!(resolved.flags & ts.SymbolFlags.Value))
+        return null; // pure type surface
+    const g = L.globalsBySymbol.get(resolved);
+    if (g) {
+        const ref = { kind: "varRef", localId: g.id, type: g.type, loc };
+        if (ref.type.kind === "jsval")
+            return ref;
+        if (isUnitType(ref.type)) {
+            return { kind: "jsOp", op: ref.type.kind === "undefinedT" ? "undefLit" : "nullLit", args: [], type: JSVAL, loc };
+        }
+        if (ref.type.kind === "func") {
+            return canMarshalTypedFuncIntoIsland(ref.type, (id) => L.shapes.get(id), (id) => L.unions.get(id))
+                ? { kind: "jsMarshal", value: ref, type: JSVAL, loc }
+                : trap(`a function value of type '${L.fmt(ref.type)}'`);
+        }
+        if (L.boundarySafe(ref.type))
+            return { kind: "jsMarshal", value: ref, type: JSVAL, loc };
+        if (L.jsvalLiftable(ref.type))
+            return L.jsvalLiftExpr(ref, loc);
+        return trap(`a value of type '${L.fmt(ref.type)}'`);
+    }
+    const sig = L.fnSigsBySymbol.get(resolved);
+    const decl0 = L.checker.declarationsOf(resolved).find((d) => ts.isFunctionDeclaration(d) && (ts.isSourceFile(d.parent) || L.nsBlocks.get(d.parent) === "flattened"));
+    if (sig && decl0) {
+        if (!sig.params.every((p) => p.mode === "required")) {
+            return trap("a function with optional, default, or rest parameters");
+        }
+        const funcType = {
+            kind: "func",
+            params: sig.params.map((p) => p.type),
+            ret: sig.returnType,
+        };
+        if (!canMarshalTypedFuncIntoIsland(funcType, (id) => L.shapes.get(id), (id) => L.unions.get(id))) {
+            return trap(`a function of type '${L.fmt(funcType)}'`);
+        }
+        L.noteEdge(sig.name);
+        return {
+            kind: "jsMarshal",
+            value: { kind: "closure", fnName: sig.name, captures: [], type: funcType, loc },
+            type: JSVAL,
+            loc,
+        };
+    }
+    if (L.genericFnsBySymbol.has(resolved))
+        return trap("a generic function");
+    const flags = resolved.flags;
+    if (flags & ts.SymbolFlags.Class)
+        return trap("a class");
+    if (flags & ts.SymbolFlags.Enum)
+        return trap("an enum object");
+    if (flags & ts.SymbolFlags.ValueModule || flags & ts.SymbolFlags.NamespaceModule) {
+        return trap("a namespace object");
+    }
+    return trap("a binding");
+}
+/** An engine value whose any USE throws: `new Function("<throw>")` — a
+   * real engine function, so the namespace member reads back fine (Node's
+   * namespace holds the value too), property probes answer like a
+   * function's, and calling or `new`-ing it runs the body, which throws
+   * the pointed TypeError. */
+function islandTrapFnValue(L, message, loc) {
+    void L;
+    const code = `throw new TypeError(${JSON.stringify(message)})`;
+    return {
+        kind: "jsOp",
+        op: "construct",
+        args: [
+            { kind: "jsOp", op: "globalGet", name: "Function", args: [], type: JSVAL, loc },
+            { kind: "jsMarshal", value: { kind: "strLit", value: code, type: STRING, loc }, type: JSVAL, loc },
+        ],
+        type: JSVAL,
+        loc,
+    };
+}
+/** An object literal built NATIVELY in the island — one engine object,
+   * each field marshaled individually (nested object/array literals
+   * recurse, island handles pass straight through, everything else takes
+   * the JSON-safe copy-marshal). The same jsOp the 'any'-contextual
+   * literal path emits, callable from lowerings that KNOW the literal is
+   * island-bound (fetch's init) even when the contextual type is a union
+   * the generic path declines. Identifier AND string-literal keys — engine
+   * property names have no identifier restriction ("content-type"). */
+export function lowerIslandObjectLiteral(L, expr) {
+    const loc = locOf(expr);
+    const args = [];
+    for (const prop of expr.properties) {
+        if (!ts.isPropertyAssignment(prop) ||
+            !(ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name))) {
+            L.unsupported("SC1090", prop, "this property form in an island-built object literal (only `name: value` is supported)");
+        }
+        const nameLoc = locOf(prop.name);
+        args.push({
+            kind: "jsMarshal",
+            value: { kind: "strLit", value: prop.name.text, type: STRING, loc: nameLoc },
+            type: JSVAL, loc: nameLoc,
+        });
+        const init = prop.initializer;
+        if (ts.isObjectLiteralExpression(init)) {
+            args.push(lowerIslandObjectLiteral(L, init));
+        }
+        else if (ts.isArrayLiteralExpression(init) && !init.elements.some(ts.isSpreadElement)) {
+            const elems = init.elements.map((el) => L.jsvalIn(L.lowerExpr(el), el));
+            args.push({ kind: "jsOp", op: "arrLit", args: elems, type: JSVAL, loc: locOf(init) });
+        }
+        else {
+            args.push(L.jsvalIn(L.lowerExpr(init), init));
+        }
+    }
+    return { kind: "jsOp", op: "objLit", args, type: JSVAL, loc };
+}
+/** Method calls on the island-backed ambient surface: `Math.<fn>(...)`
+   * (the engine's own Math object executes) and the number/string methods
+   * the static runtime doesn't implement (`x.toFixed(2)`,
+   * `s.toUpperCase()`, ...). Each site is self-contained — the receiver
+   * and arguments marshal in, the engine executes with JS-exact semantics,
+   * and the result exits (validated) to the DECLARED static return type,
+   * so no jsval leaks into the program's types. tsc has already checked
+   * receiver, arity, and argument types against ambient/scriptc.d.ts; an
+   * ambient member missing from ISLAND_SURFACE returns null into the
+   * existing generic rejections. */
+export function lowerIslandMethodCall(L, call, access) {
+    if (L.chainBlocked(access, call))
+        return null;
+    const name = access.name.text;
+    const loc = locOf(call);
+    const finish = (receiver, entry) => {
+        const args = call.arguments.map((a) => L.jsvalIn(L.lowerExpr(a), a));
+        const result = {
+            kind: "jsOp", op: "callMethod", name, args: [receiver, ...args], type: JSVAL, loc,
+        };
+        return { kind: "jsExit", value: result, type: entry.ret, loc };
+    };
+    // `AbortSignal.timeout(ms)` / `.abort(reason?)` / `.any(signals)` —
+    // the fetch-cancellation ambient: the engine's own AbortSignal mints
+    // the signal, which stays a HANDLE (its checker type, AbortSignal,
+    // maps to jsval — see ISLAND_AMBIENT_TYPES) so it can ride a
+    // RequestInit literal into fetch without a JSON detour. The prelude
+    // implements all three statics.
+    {
+        const sigMember = L.stdlibGlobalMember(access, "AbortSignal");
+        if ((sigMember === "timeout" || sigMember === "abort" || sigMember === "any") &&
+            call.arguments.length <= 1 &&
+            (sigMember === "abort" || call.arguments.length === 1)) {
+            L.requireDynamicApi(`'AbortSignal.${sigMember}'`, call);
+            const args = call.arguments.map((a) => L.jsvalIn(L.lowerExpr(a), a));
+            const signalGlobal = {
+                kind: "jsOp", op: "globalGet", name: "AbortSignal", args: [], type: JSVAL, loc,
+            };
+            return {
+                kind: "jsOp", op: "callMethod", name: sigMember,
+                args: [signalGlobal, ...args], type: JSVAL, loc,
+            };
+        }
+    }
+    const isMath = L.stdlibGlobalMember(access, "Math") !== null;
+    // The STATIC Math members (floor/min/max/random): one C call IS the
+    // JS operation — no island, no --dynamic. Only the tabled arity with
+    // plain (non-spread) arguments takes this path; other forms fall
+    // through to the spread fold / island / lib fence below.
+    const staticMath = isMath ? own(STATIC_MATH_FNS, name) : undefined;
+    if (staticMath &&
+        call.arguments.length === staticMath.arity &&
+        call.arguments.every((a) => !ts.isSpreadElement(a))) {
+        const args = call.arguments.map((a) => L.lowerExprExpecting(a, F64));
+        return { kind: "libCall", fn: staticMath.fn, args, type: F64, loc };
+    }
+    // `Math.max(...xs)` / `Math.min(...xs)` over a number[]: a STATIC
+    // runtime fold (JS-exact: NaN poisons, ±0 order by the JS rules, the
+    // empty array yields ∓Infinity like the zero-arg calls) — no island
+    // involved, so it works without --dynamic too. Only the exact
+    // one-spread form lowers; mixed spread/positional argument lists keep
+    // the nest-calls fence.
+    if (isMath &&
+        (name === "max" || name === "min") &&
+        call.arguments.length === 1 &&
+        ts.isSpreadElement(call.arguments[0])) {
+        const spread = call.arguments[0];
+        const src = L.lowerExpr(spread.expression);
+        if (src.type.kind !== "array" || src.type.elem.kind !== "f64") {
+            L.unsupported("SC1090", spread, `spreading '${L.fmt(src.type)}' into Math.${name} (only a number[] spreads)`);
+        }
+        return {
+            kind: "libCall",
+            fn: name === "max" ? "math.maxArr" : "math.minArr",
+            args: [src],
+            type: F64,
+            loc,
+        };
+    }
+    const mathFn = isMath ? own(ISLAND_SURFACE.math.fns, name) : undefined;
+    if (mathFn && call.arguments.length === mathFn.args.length) {
+        L.requireDynamicApi(`'Math.${name}'`, call);
+        return finish({ kind: "jsOp", op: "globalGet", name: "Math", args: [], type: JSVAL, loc }, mathFn);
+    }
+    const kind = L.mapTypeOf(L.typeOf(access.expression))?.kind;
+    const entry = kind === "f64"
+        ? own(ISLAND_SURFACE.number, name)
+        : kind === "string"
+            ? own(ISLAND_SURFACE.string, name)
+            : undefined;
+    if (!entry || call.arguments.length !== entry.args.length)
+        return null;
+    if (!L.isStdlibMember(access))
+        return null;
+    L.requireDynamicApi(`'.${name}()' on ${kind === "f64" ? "numbers" : "strings"}`, call);
+    return finish(L.jsvalIn(L.lowerExpr(access.expression), access.expression), entry);
+}
+/** `Math.PI` / `Math.E` property READS: getProp off globalGet("Math"),
+   * exiting to the declared number type. Math methods referenced without a
+   * call are rejected specifically (no value form exists, --dynamic or
+   * not). Null for non-Math receivers (the property chain keeps trying). */
+export function lowerMathProperty(L, expr) {
+    const member = L.stdlibGlobalMember(expr, "Math");
+    if (member === null)
+        return null;
+    const loc = locOf(expr);
+    const propType = own(ISLAND_SURFACE.math.props, member);
+    if (propType !== undefined) {
+        L.requireDynamicApi(`'Math.${member}'`, expr);
+        const math = { kind: "jsOp", op: "globalGet", name: "Math", args: [], type: JSVAL, loc };
+        const read = { kind: "jsOp", op: "getProp", name: member, args: [math], type: JSVAL, loc };
+        return { kind: "jsExit", value: read, type: propType, loc };
+    }
+    if (own(ISLAND_SURFACE.math.fns, member) !== undefined ||
+        own(STATIC_MATH_FNS, member) !== undefined) {
+        L.unsupported("SC1090", expr, `Math methods as values (call '${member}' directly)`);
+    }
+    return null; // declared-but-untabled members fall through generically
+}
+/** The npm package a type is declared by ("commander", "@scope/pkg"),
+   * or null when the type isn't package-declared. Union parts are searched
+   * too: `string | Command` fails mapping as a whole, but the blame (and
+   * the --dynamic attribution) belongs to the package-declared part. */
+export function npmPackageOf(L, type) {
+    const pkg = L.npmPackageOfSymbol(type.getAliasSymbol() ?? type.getSymbol());
+    if (pkg)
+        return pkg;
+    if (type.isUnionType()) {
+        for (const part of type.getTypes()) {
+            const partPkg = L.npmPackageOf(part);
+            if (partPkg)
+                return partPkg;
+        }
+    }
+    return null;
+}
+/** The npm chokepoint for member reads and method calls in a STATIC
+   * build: a receiver whose type (or member whose symbol) a package's
+   * .d.ts declares means the operation runs in the embedded engine —
+   * attribute the site to the package instead of the generic property/
+   * method rejection. No-op under --dynamic (the island paths claimed
+   * these) and for non-package receivers, so callers' fallbacks apply. */
+export function npmMemberFence(L, access) {
+    if (L.dynamic)
+        return;
+    const pkg = L.npmPackageOf(L.typeOf(access.expression)) ??
+        L.npmPackageOfSymbol(L.checker.getSymbolAtLocation(access.name));
+    if (!pkg)
+        return;
+    L.pushDiag(requiresDynamicPackageDiag(pkg, locOf(access)));
+    throw new PoisonError();
+}
+/** The npm package a SYMBOL is declared by, or null. The symbol half of
+   * npmPackageOf, also asked directly for import-alias bindings (whose
+   * aliased symbol is the package's export). */
+export function npmPackageOfSymbol(L, sym) {
+    const decls = sym ? L.checker.declarationsOf(sym) : undefined;
+    if (!decls || decls.length === 0)
+        return null;
+    if (!decls.every((d) => L.isNpmFile(d.getSourceFile())))
+        return null;
+    return npmPackageNameOf(decls[0].getSourceFile().fileName);
+}
+//# sourceMappingURL=lower-island.js.map