@scriptc/compiler 0.0.0 → 0.0.1

package/dist/frontend/lowering/lower-calls.d.ts

@@ -0,0 +1,581 @@
+import * as ts from "../ts7/adapter.js";
+import type { Lowerer } from "./lowerer.js";
+import { IrExpr, IrFunction, IrStmt, IrType, SrcLoc } from "../../ir/nodes.js";
+import { type ClassInfo } from "./lower-classes.js";
+/** How a parameter participates in CALL-SITE COMPLETION (the frontend
+ * completes every call to the one full signature, so the IR and backends
+ * stay count-exact — see docs/ir.md). `required` params must be passed;
+ * `omittable` params (declared `x?: T` or `x: T = e`) may be omitted by a
+ * trailing-suffix call, and the frontend appends the interned undefined arm;
+ * `rest` (always last) receives the surplus arguments packed into one array
+ * literal at each call site. */
+export type ParamMode = "required" | "omittable" | "rest" | "dynRest";
+/** One parameter of a signature, as call sites and callee prologues see it.
+ * `type` is the ABI type — what the emitted C parameter carries: the
+ * checker's `T | undefined` union for `x?: T`, a synthesized `T | undefined`
+ * union for `x: T = e`, `T[]` for `...xs: T[]`, the plain declared type
+ * otherwise. `bodyType` is present exactly for DEFAULTED params: the plain T
+ * the body sees after the prologue applies the default (see declareParams). */
+export interface ParamShape {
+    type: IrType;
+    mode: ParamMode;
+    bodyType?: IrType;
+}
+export interface FnSig {
+    name: string;
+    params: ParamShape[];
+    /** Call-site result type — Promise<inner> for async functions, the
+     * generator type for generator functions. */
+    returnType: IrType;
+    /** Async: the IrFunction's returnType is the promise's INNER type. */
+    isAsync?: boolean;
+    /** Generator: the IrFunction's returnType is the TReturn channel; the
+     * yield/next channels ride here (IrFunction.generator's exact shape). */
+    generator?: {
+        yieldT: IrType;
+        nextT: IrType;
+    };
+}
+/** Instantiation cap per generic function: same-key recursion (`len<T>`
+ * calling itself) converges, but POLYMORPHIC recursion (`f<T>` calling
+ * `f<T[]>`) would request new instances forever — the cap turns that into a
+ * diagnostic instead of a hang. */
+export declare const MAX_GENERIC_INSTANCES = 100;
+/** A generic function-like declaration, collected instead of an FnSig —
+ * top-level generic function declarations, class GENERIC METHODS (own type
+ * parameters, instance and static), and object-literal generic methods.
+ * The body is NOT lowered at collection: each call site's checker-resolved
+ * signature (type arguments substituted) becomes an instantiation key, and
+ * the body is lowered once per distinct key (monomorphization). */
+export interface GenericFnInfo {
+    decl: ts.FunctionDeclaration | ts.MethodDeclaration | ts.FunctionExpression | ts.ArrowFunction;
+    /** Unqualified source name, for diagnostics. */
+    baseName: string;
+    /** Program-wide qualified name; instance `n` is named `<qualified>%<n>`
+     * ('%' cannot appear in a TS identifier, so instance names can never
+     * collide with user functions). */
+    qualifiedName: string;
+    /** Declaration-order type parameter symbols. */
+    typeParams: ts.Symbol[];
+    /** Instantiation key (comma-joined typeKeys of the mapped param types +
+     * `=>` + return typeKey) → instance. Key identity IS signature identity:
+     * two call sites whose inferred types map to the same IR types share one
+     * native function. */
+    instances: Map<string, GenericInstance>;
+    /** CLASS-member generic methods: the declaring ClassInfo and flavor.
+     * Instance methods take `this` (object:<declarer>) as param 0 and lower
+     * under the declarer's instantiation bindings (generic-class receivers)
+     * MERGED with the method instantiation's own; statics lower as plain
+     * module functions with the static-method this/super fence. Absent for
+     * top-level functions and object-literal methods. */
+    member?: {
+        cls: ClassInfo;
+        kind: "method" | "static";
+    };
+    /** Object-literal generic methods (`{ m<T>(x: T) {...} }` and generic
+     * arrow/function-expression properties): lowered as plain module
+     * functions — `this` inside is fenced (rejectThisInObjectMethod) and the
+     * defining literal must sit at module scope (no enclosing frame to
+     * capture). */
+    objectLiteral?: true;
+    /** IMPLICIT-ANY monomorphization (npm-static JS): parallel to
+     * decl.parameters — the param's own symbol when the slot is a BINDABLE
+     * implicit-any parameter (untyped, identifier-named, never written in
+     * the body), null for typed or unbindable slots. Present ⇔ this info
+     * monomorphizes over its implicit-any params instead of declared type
+     * parameters (typeParams stays empty): each call site's WIDENED argument
+     * checker types key an instantiation, exactly the generic machinery —
+     * the untyped params ARE the type parameters (see implicitCallInstance). */
+    implicitParams?: (ts.Symbol | null)[];
+}
+export interface GenericInstance {
+    name: string;
+    /** 0 for the first instance of a base function — the only one whose
+     * statements count toward coverage stats (re-instantiations re-visit the
+     * same source lines). */
+    ordinal: number;
+    params: ParamShape[];
+    returnType: IrType;
+    /** Type-parameter symbol → concrete IR type, consulted by mapType (via
+     * typeParamResolver) while the instance body lowers. */
+    bindings: Map<ts.Symbol, IrType>;
+    /** Rendered type arguments ("<number, string>") for diagnostics. */
+    typeArgsText: string;
+    /** Implicit instances only: param symbol → the call site's (widened)
+     * checker type, consulted by the Lowerer's typeOf while this instance's
+     * body lowers (the implicit twin of `bindings`). */
+    implicitArgTypes?: Map<ts.Symbol, ts.Type>;
+    /** Implicit instances only: eager-lowering lifecycle. "lowering" while
+     * the body builds (a re-demand is same-key recursion: the caller uses
+     * the PINNED fallback returnType and returnPinned locks it); "done" once
+     * returnType holds the inferred (or pinned) truth. */
+    implicitState?: "lowering" | "done";
+    /** Same-key recursion observed the fallback return type mid-lowering, so
+     * the ABI is locked to it — the return post-pass coerces every return
+     * value to the pinned type instead of adopting the inferred one. */
+    returnPinned?: boolean;
+    /** Implicit instances only: the declared return did not map (the
+     * any-params poisoned it) — the body lowers in return-INFERENCE mode
+     * (returnType holds the DYN recursion pin until the post-pass settles). */
+    implicitInferReturn?: true;
+}
+/** One parameter's ParamShape — the shared signature-shaped collection
+   * point for function declarations, methods, constructors, and lambdas
+   * (generic declarations defer to their call sites, where the resolved
+   * types exist; see lowerGenericCall).
+   *
+   * - `x?: T`: the checker already types the param `T | undefined` under
+   *   strictNullChecks, so the ABI type IS that union and the body narrows
+   *   with `!== undefined` like any union local.
+   * - `x: T = e`: the ABI type is a synthesized `T | undefined` union (the
+   *   caller may omit the arg or pass undefined — both trigger the default,
+   *   JS-exact); the body sees plain T through the two-local prologue
+   *   (declareParams). A single-arm T narrows in the prologue; a UNION T
+   *   re-tags through the interned retag helper (the undefined arm is the
+   *   one stranded case, unreachable from the else-branch by construction).
+   * - `...xs: T[]`: the ABI type is the array; call sites pack the surplus.
+   */
+export declare function paramShape(L: Lowerer, param: ts.ParameterDeclaration): ParamShape;
+/** ParamShapes for a whole parameter list. */
+/** A `this` PARAMETER declaration (`function f(this: void, x: {}) ...`)
+   * — type-world only: tsc types the receiver with it, callers never pass
+   * it, and signature.getParameters() excludes it. The syntactic walks
+   * (paramShapes, declareParams) skip it with this predicate so ABI slots
+   * and call completion stay aligned with what JS actually passes. */
+export declare function isThisParameter(param: ts.ParameterDeclaration): boolean;
+export declare function paramShapes(L: Lowerer, params: readonly ts.ParameterDeclaration[]): ParamShape[];
+/** The fences on a defaulted parameter's body type: it becomes the value
+   * arm of the synthesized `T | undefined` ABI union, so it must be a valid
+   * single arm. func and Set ARE valid here: the ABI union's only test is
+   * the prologue's own undefined-tag check (never a user narrowing, which
+   * is what keeps map/set out of general unions), so `runner: Runner =
+   * defaultRunner` and `skip: Set<string> = new Set()` arm like any ref
+   * kind — the nullable-callback union shape, built by the compiler. */
+export declare function checkDefaultParamBodyType(L: Lowerer, param: ts.ParameterDeclaration, bodyType: IrType): void;
+/** CALL-SITE COMPLETION — the frontend half of the one-signature contract
+   * (docs/ir.md): every call lowers to exactly the callee's full ABI
+   * parameter list, so backends and the validator stay count-exact and no
+   * runtime arity machinery exists. Omitted trailing args for omittable
+   * params become the interned undefined arm (which is also what an
+   * explicitly-passed `undefined` wraps to — both trigger a default, JS-
+   * exact); a rest param packs the surplus args (possibly zero) into one
+   * array literal, evaluated in source order at the call site. */
+export declare function completeArgs(L: Lowerer, argNodes: readonly ts.Expression[], shapes: readonly ParamShape[], loc: SrcLoc, blame: ts.Node, 
+/** Pre-lowered values virtually PREPENDED to the argument list — the
+ * tagged-template strings object, which has no ts.Expression to lower
+ * (lowerTaggedTemplate builds it). Each rides the same slot-directed
+ * coercion an ordinary argument gets (coerceInto against its shape,
+ * DYN conversion in a dyn rest, element coercion in a typed rest). */
+leading?: readonly IrExpr[]): IrExpr[];
+/** The undefined arm of an undefined-armed union `type`, wrapped (a
+   * unitLit under a unionWrap) — the value every "absent" slot holds: an
+   * omitted optional argument, an omitted optional record field. Null when
+   * `type` has no undefined arm to wrap into. */
+export declare function wrappedUndefined(L: Lowerer, type: IrType, loc: SrcLoc): IrExpr | null;
+/** The synthesized argument for an omitted omittable param: the interned
+   * undefined arm of the param's `T | undefined` ABI union, or the DOM
+   * undefined for a checked-dynamic param (`bar?: any`). */
+/** The "absent argument" value for a param SLOT type, or null when the
+   * slot cannot hold one: the interned undefined arm for undefined-armed
+   * unions, the DOM undefined for checked-dynamic slots, the engine's own
+   * undefined for island slots. Shared by every call-completion loop
+   * (direct calls and calls through func-typed values). */
+export declare function omittedArgFor(L: Lowerer, type: IrType, loc: SrcLoc): IrExpr | null;
+export declare function undefinedArgFor(L: Lowerer, type: IrType, loc: SrcLoc, blame: ts.Node): IrExpr;
+/** DECISION (docs/ir.md): function VALUES keep exact-arity semantics — a
+   * func-typed IrType spells one completed signature, so a function whose
+   * declaration has optional/default/rest parameters can become a value only
+   * where the target type spells that exact signature with required
+   * parameters (`x?: T` / `x: T = e` params appear as literal `T | undefined`
+   * unions; a rest signature is never spellable without `...`, which func
+   * types reject). Direct calls get the full feature. */
+export declare function requireExactArityValue(L: Lowerer, blame: ts.Node, contextual: ts.Expression | null, shapes: readonly ParamShape[], funcType: IrType): void;
+/** The BODY-facing return type of a (possibly async) function: an async
+   * body's `return v` fulfills its promise with v, so the body returns the
+   * promise's INNER type while call sites keep Promise<T>. The declared
+   * type of an async function is always a promise (collectSignature /
+   * lowerLambda reject anything else before calling this). */
+export declare function bodyReturnType(L: Lowerer, isAsync: boolean, declared: IrType): IrType;
+/** A union-returning body may complete WITHOUT returning — JS yields
+   * undefined then (`(): string | undefined => { if (c) return "x"; }`), so
+   * an undefined-armed union return gets a trailing `return <undefined
+   * arm>` appended unless the body's last statement already returns or
+   * throws (deeper always-returning control flow keeps the appended return
+   * as dead code — harmless).
+   *
+   * Every OTHER non-void body gets a trailing UNREACHABLE trap instead:
+   * tsc's reachability can prove completions the validator's conservative
+   * alwaysReturns cannot (an exhaustive `switch (typeof x)` with a return
+   * in every case — signature 16), and those bodies end without a terminal
+   * statement of their own. The trap satisfies the must-return rule as the
+   * dead code it is; it can only fire if the checker's proof was violated,
+   * which would be a lowering bug — hence the please-report wording. */
+export declare function appendImplicitUndefinedReturn(L: Lowerer, body: IrStmt[], bodyReturn: IrType, loc: SrcLoc): void;
+/** A declaration's checker-derived IR return type. The unmappable-type
+   * diagnostic points at `blame` (the name for top-level declarations, the
+   * whole node for lambda-likes — preserving each caller's historical loc). */
+export declare function declaredReturnType(L: Lowerer, decl: ts.SignatureDeclaration, blame: ts.Node): IrType;
+export declare function collectSignature(L: Lowerer, decl: ts.FunctionDeclaration): void;
+export declare function collectSignatureInner(L: Lowerer, decl: ts.FunctionDeclaration): void;
+/** Registers a top-level generic function. Only the SYNTAX is checked
+   * here — parameter/return types mention the type parameters and cannot
+   * map yet; the body is lowered per instantiation, on demand (an unused
+   * generic function costs nothing, like a C++ template). Called inside
+   * collectSignature's poison catch. */
+export declare function collectGenericSignature(L: Lowerer, decl: ts.FunctionDeclaration): void;
+export declare function genericFnOf(L: Lowerer, ident: ts.Identifier): GenericFnInfo | null;
+/** Call of a generic top-level function. The checker already inferred (or
+   * was told, via explicit type arguments) the concrete signature —
+   * getResolvedSignature returns it with type arguments substituted. The
+   * mapped param+return IR types form the INSTANTIATION KEY; the first call
+   * with a new key queues the body for monomorphic lowering as
+   * `<qualifiedName>%<n>`, and every call lowers to a direct `call` of that
+   * instance. */
+export declare function lowerGenericCall(L: Lowerer, expr: ts.CallExpression, info: GenericFnInfo): IrExpr;
+/** The instance a CALL of a generic function-like names: resolved
+   * signature → mapped param shapes/return → interned instance. Shared by
+   * top-level generic calls, class generic-method calls (the caller
+   * prepends the receiver), and object-literal generic-method calls. */
+export declare function genericCallInstance(L: Lowerer, expr: ts.CallExpression, info: GenericFnInfo): GenericInstance;
+/** The one instance table both instantiation routes share: key identity IS
+   * signature identity, so a call (`identity(1)`) and a pinned VALUE
+   * (`const f: (x: number) => number = identity`) reuse one compiled
+   * instance. `makeBindings` runs only for a NEW key (binding inference
+   * costs checker walks). */
+export declare function internGenericInstance(L: Lowerer, blame: ts.Node, info: GenericFnInfo, params: ParamShape[], returnType: IrType, makeBindings: () => Map<ts.Symbol, IrType>): GenericInstance;
+/** Type-parameter symbol → concrete IR type for one instantiation.
+   * Explicit type arguments bind directly; the rest come from structurally
+   * matching each DECLARED param/return type (which mentions the type
+   * parameters) against the checker's INSTANTIATED one — the latter is the
+   * former with the substitution applied, so the shapes are parallel by
+   * construction. A type parameter left unbound only matters if the body
+   * mentions it, where mapType fails with SC2001 (carrying the
+   * instantiation context). */
+export declare function inferTypeParamBindings(L: Lowerer, expr: ts.CallExpression, info: GenericFnInfo, rsig: ts.Signature): Map<ts.Symbol, IrType>;
+/** Type parameters still unbound after unification take their declared
+   * DEFAULT (`<T = number>`), mapped — the checker already substituted the
+   * default into every resolved signature, so this only fills the bindings
+   * an instance body's mapType consults. */
+export declare function bindDefaultTypeParams(L: Lowerer, typeParams: readonly ts.Symbol[], typeParamDecls: readonly ts.TypeParameterDeclaration[] | undefined, bindings: Map<ts.Symbol, IrType>): void;
+/** The structural half of binding inference: unify the DECLARED signature
+   * (whose types mention the type parameters) against a TARGET signature
+   * with the substitution applied — a call's resolved signature, or the
+   * completed signature a VALUE reference is pinned to (the contextual
+   * type's one call signature). Mutates `bindings`; already-bound
+   * parameters (explicit type arguments) win. */
+export declare function unifySignatureBindings(L: Lowerer, info: GenericFnInfo, rsig: ts.Signature, bindings: Map<ts.Symbol, IrType>): void;
+/** Lowers ONE monomorphic instance of a generic function: the same body
+   * AST, re-lowered with the type parameters bound (threaded into every
+   * mapType call via typeParamResolver — the checker keeps reporting the
+   * unsubstituted `T`s inside the body). Coverage stats count a base
+   * function's statements once: only the FIRST instance contributes. */
+export declare function lowerGenericInstance(L: Lowerer, info: GenericFnInfo, inst: GenericInstance): IrFunction;
+/** A generic function taken as a VALUE, monomorphized by flow. A function
+   * value needs ONE concrete signature; tsc pins one at exactly two
+   * reference shapes — an instantiation EXPRESSION (`identity<number>`,
+   * whose own checker type is the substituted signature) and a reference
+   * whose CONTEXTUAL type completes the signature (`const f: (x: number) =>
+   * number = identity`, `take(identity)`). The declared signature unifies
+   * against the pinned one to recover the bindings; the instance then
+   * registers in the SAME table call sites use (one compiled copy per
+   * signature however it is reached), and the value is the instance's
+   * zero-capture closure — `f === f` holds within an instantiation, the
+   * declared-function identity rule. References with no pinning context
+   * (the slot keeps `<T>(x: T) => T`) fence by name. */
+export declare function lowerGenericFnValue(L: Lowerer, ref: ts.Expression, info: GenericFnInfo): IrExpr;
+/** The npm-static gate: implicit-any monomorphization applies to functions
+   * DECLARED in an opted-in package's JS files (user JS keeps today's
+   * checked-dynamic story until the corpus is re-baselined). */
+export declare function implicitMonoFile(sf: ts.SourceFile): boolean;
+/** The implicit-type-parameter slots of a JS function-like: parallel to
+   * decl.parameters, the param SYMBOL where the slot is a bindable
+   * implicit-any param (identifier-named, no annotation/JSDoc type, not
+   * rest/optional/defaulted, never written), null elsewhere. Null overall
+   * when nothing qualifies — the declaration keeps today's path. */
+export declare function implicitAnyParamSymbolsOf(L: Lowerer, decl: ts.FunctionDeclaration | ts.MethodDeclaration | ts.FunctionExpression | ts.ArrowFunction): (ts.Symbol | null)[] | null;
+/** The instance a CALL of an implicit-any function-like names: each
+   * bindable implicit param takes the call's WIDENED argument checker type
+   * when it maps statically (DYN otherwise — today's slot), typed params
+   * keep their declared shapes, and the param-type tuple is the
+   * instantiation key. New keys lower EAGERLY (return inference — see the
+   * section comment); a same-key re-demand mid-lowering pins the fallback
+   * return type. */
+export declare function implicitCallInstance(L: Lowerer, call: ts.CallExpression, info: GenericFnInfo): GenericInstance;
+/** The all-dyn DEFAULT instance — today's compiled body exactly: what a
+   * VALUE reference of an implicit-any function names (indirect calls
+   * carry no per-site types to bind). */
+export declare function implicitDefaultInstance(L: Lowerer, blame: ts.Node, info: GenericFnInfo): GenericInstance;
+/** The implicit-any twin of bindingGenericFnNodeOf, for LOCAL and module
+   * bindings alike (`const knownBy = (cmd) => [cmd.name()].concat(...)`
+   * inside a method body — commander's _registerCommand shape): the
+   * initializer function-like when the WHOLE declaration qualifies for
+   * implicit monomorphization, else null — non-qualifying shapes keep
+   * today's closure story silently (never a fence: the flag must not make
+   * working code worse). Qualification: an npm-static JS file, a const (or
+   * never-reassigned, never-redeclared) identifier binding, an
+   * arrow/function-expression initializer with bindable implicit-any
+   * params, and a body with NO captures — no `this`/`super`, and no
+   * reference to a function-scoped declaration outside itself (compiled
+   * instances are module functions; module-scope references are fine).
+   * Cached per declaration on L.implicitLocalFns. */
+export declare function implicitLocalFnNodeOf(L: Lowerer, decl: ts.VariableDeclaration): ts.FunctionExpression | ts.ArrowFunction | null;
+/** Registers (or returns) the GenericFnInfo of a qualifying implicit-any
+   * function-value binding — implicitLocalFnNodeOf's companion, the
+   * bindingGenericFnInfoOf shape: the info enters genericFnsBySymbol under
+   * the binding's symbol (and a named function expression's inner name),
+   * so calls and value references resolve through genericFnOf; the
+   * declaration statement emits nothing and the binding has no runtime
+   * value. The declaration's source position joins the qualified name —
+   * two same-named locals in one file stay distinct. */
+export declare function implicitLocalFnInfoOf(L: Lowerer, decl: ts.VariableDeclaration, fnNode: ts.FunctionExpression | ts.ArrowFunction): GenericFnInfo;
+/** An island call result the .d.ts DECLARES as a primitive exits eagerly
+ * to that static type — the member-read rule's call sibling (see the
+ * getProp lowering in lower-exprs.ts): primitives copy by value, every
+ * static consumer works on the result, and a lying declaration throws the
+ * catchable TypeError. Chain-handled forms stay jsval (the optChain's
+ * unit path is the engine's undefined). */
+export declare function islandPrimitiveExit(L: Lowerer, call: ts.CallExpression, result: IrExpr): IrExpr;
+/** The trailing-argument timer forms — `setTimeout(cb, ms, ...args)`,
+   * `setInterval(cb, ms, ...args)`, `setImmediate(cb, ...args)` — invoke
+   * the callback WITH those arguments (Node passes them through). The
+   * callback and every argument box into dyn and an interned per-arity
+   * thunk delivers the dynCall at fire time: JS's exact call semantics
+   * (per-argument checks against the callee's declared signature, extras
+   * ignored, a non-function callee throwing the catchable TypeError).
+   * Non-boxable callbacks fence. */
+export declare function timerStyleCallback(L: Lowerer, callArgs: readonly ts.Expression[], what: string, loc: SrcLoc): IrExpr;
+/** The timer surface's member names — the ambient globals AND the
+   * node:timers module's exports (one set: Node's timers module re-exports
+   * the globals). */
+export declare const TIMER_MODULE_MEMBERS: ReadonlySet<string>;
+/** One timer call by MEMBER NAME — the shared lowering behind the ambient
+   * globals, the node:timers named/destructured imports, and the namespace
+   * form (`timers.setTimeout(...)`). Null when the member isn't a lowered
+   * timer function (the caller's fence machinery takes over). */
+export declare function lowerTimersMemberCall(L: Lowerer, expr: ts.CallExpression, member: string, loc: SrcLoc): IrExpr | null;
+export declare function lowerCall(L: Lowerer, expr: ts.CallExpression): IrExpr;
+/** The SHARED prototype names scr_dyn_invoke dispatches at runtime (the
+ * subset of DOM_PROTO_METHOD_NAMES with a receiver-kind dispatch): the
+ * runtime runs the real method for the receiver's kind, throws Node's
+ * is-not-a-function where the kind's prototype lacks the name, and
+ * fences LOUDLY on real-but-unimplemented pairs. */
+export declare const DYN_DISPATCH_METHODS: Set<string>;
+/** Radix-free `.toString()` on a PRIMITIVE receiver: numbers take the
+   * STATIC JS-exact number formatter — the same `toString` node templates
+   * and String(n) lower to (Number::toString with radix 10 IS that
+   * conversion, per spec) — booleans the "true"/"false" texts, and strings
+   * the identity read (String.prototype.toString returns `this`). The
+   * explicit-radix number form keeps its island lowering (ISLAND_SURFACE);
+   * null for other receivers, argument shapes, or non-lib members (a
+   * user's own `.toString` takes the ordinary paths). */
+export declare function lowerNumberToStringCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** Radix-free `.toString()` on a UNION receiver whose every arm has one
+   * (string identity, JS-exact number/bool texts, and the Buffer arm's
+   * utf8 decode — Node's default encoding): the per-union ToString
+   * helper dispatches on the tag, so `chunk.toString()` over the ngrok
+   * `Buffer | string` listener param needs no narrowing. Unit-armed
+   * unions stay out — `(undefined).toString()` THROWS in JS, and
+   * claiming it here would silently print "undefined" instead. Null for
+   * other receivers/arms (the narrow-first fences stay). */
+export declare function lowerUnionToStringCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** `x.toString()` resolving to Object.prototype.toString (stdlib
+   * provenance, zero arguments) on a RECORD or program-class receiver:
+   * the spec's default answer is the constant "[object Object]". Records
+   * carry no method storage at all, and a class receiver folds only when
+   * neither its chain nor ANY subclass declares toString (dynamic
+   * dispatch could reach an override otherwise — and a resolved override
+   * is the USER's symbol, which never lands here). Pure receivers elide
+   * evaluation; effectful ones evaluate through an interned identity
+   * helper so the receiver's effects keep their place. */
+export declare function lowerDefaultToStringCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** The remaining PRIMITIVE prototype surface with a static story, in both
+   * member spellings (`x.hasOwnProperty(...)` and `x['hasOwnProperty'](...)`
+   * — JS resolves the two identically, so the element spelling routes here
+   * from lowerCall's element-access hook):
+   *   - `n.toExponential()` / `n.toFixed()` with the fraction digits
+   *     OMITTED — the static runtime formatters (num.toExponential's
+   *     shortest-mantissa form, num.toFixed0's ties-up integer). The
+   *     explicit-digits forms keep their island/fence story.
+   *   - `hasOwnProperty(lit)` on number/boolean receivers — the boxes own
+   *     NOTHING, so any key answers false (a compile-time constant; the
+   *     receiver must be effect-free since the constant elides it).
+   *   - `hasOwnProperty(lit)` on string receivers — "length" is true,
+   *     a canonical array index answers `index < s.length` (indices ARE
+   *     own properties of the box, per spec), every other literal false.
+   *   - the element-access spellings of `toString()` (the primitive
+   *     lowering above) and `charAt(i)` — the two the element hook needs
+   *     beyond this file's own claims.
+   * Null elsewhere: non-literal keys, other members, other receivers. */
+export declare function lowerPrimitiveProtoCall(L: Lowerer, call: ts.CallExpression, recv: ts.Expression, name: string, memberSym: ts.Symbol | undefined): IrExpr | null;
+/** Tagged templates `tag\`a${x}b\`` — ES's call: tag(strings, ...values).
+   * The strings object is the per-SITE interned cooked array (the
+   * templateStrings node: one immortal string[] per occurrence, so the
+   * spec's identity contract holds — the same site evaluated twice hands
+   * the tag the SAME array; two sites never share). TemplateStringsArray
+   * maps to string[] (types.ts), so the array rides the ordinary
+   * slot-directed coercion into whatever the tag's first parameter wants
+   * — string[] exactly, an `any` slot through the dyn boundary, a rest
+   * pack's first element. `.raw` does not exist on the lowered object:
+   * reads fence per member, and String.raw itself lowered above (the raw
+   * spans splice directly, no array materializes).
+   *
+   * Tag forms: a top-level declared function (the direct-call fast path —
+   * overload sets reconcile through the resolved signature exactly like
+   * plain calls), an island value under --dynamic (engine method/function
+   * call: the engine side sees a plain marshaled array — a tag reading
+   * `.raw` there answers undefined where Node carries the raw spans), and
+   * a checked-dynamic value (the dynCall boundary — a non-function tag
+   * throws Node's catchable TypeError). Everything else — generic tags,
+   * method tags, function-value bindings — fences by name. */
+export declare function lowerTaggedTemplate(L: Lowerer, expr: ts.TaggedTemplateExpression): IrExpr;
+/** True when the identifier resolves (through import aliases) to a
+   * top-level function declaration of ANY program file (not merely a
+   * same-named local shadowing one). Functions declared directly in a
+   * FLATTENED namespace block count — splitFiles hoisted them into the
+   * same collection lists top-level declarations ride. */
+export declare function isTopLevelFnSymbol(L: Lowerer, ident: ts.Identifier): boolean;
+/** Nested `function name(...) {...}`: lowered as `const name = <lambda>`
+   * at the declaration's statement position (JS hoists function declarations
+   * to the top of the enclosing function — calling one before this statement
+   * is a compile error here, not a silent divergence). Self-references inside
+   * the body lower to `selfRef`, not a capture: a box holding its own
+   * closure would be an RC cycle. */
+export declare function lowerNestedFunctionDecl(L: Lowerer, stmt: ts.FunctionDeclaration): IrStmt;
+/** Signature checks + param shapes + IR func type for any lambda-like
+   * node. The func type's params are the ABI types, so a lambda with
+   * optional/default params has the same IR type as one spelling the
+   * `T | undefined` unions with required params — exactly the exact-arity
+   * value rule (requireExactArityValue decides who may become a value). */
+export declare function lambdaSignature(L: Lowerer, node: ts.ArrowFunction | ts.FunctionExpression | ts.FunctionDeclaration | ts.MethodDeclaration | ts.GetAccessorDeclaration | ts.SetAccessorDeclaration): {
+    shapes: ParamShape[];
+    funcType: IrType & {
+        kind: "func";
+    };
+};
+/** Does this function's OWN body read `arguments`? Nested plain functions
+   * and methods have their own `arguments` (the walk skips them); arrows
+   * see the enclosing one (the walk descends). Exported for the lowerer's
+   * dynFallbackType: tsgo does not synthesize the `arguments` rest
+   * parameter into inferred signatures (5.9.3 did — its param-count
+   * mismatch was the detector), so the 7 world asks the BODY directly. */
+export declare function bodyReadsArguments(fn: {
+    body?: ts.Node | undefined;
+}): boolean;
+/** Lifts an arrow function / function expression / nested declaration /
+   * object-literal shorthand method to a module-level function and yields
+   * the `closure` expression creating it. */
+export declare function lowerLambda(L: Lowerer, node: ts.ArrowFunction | ts.FunctionExpression | ts.FunctionDeclaration | ts.MethodDeclaration | ts.GetAccessorDeclaration | ts.SetAccessorDeclaration): IrExpr;
+export declare function lowerPromiseMethodCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** NARROWING `a.filter(...)` — the two callback forms whose result the
+   * checker types as a NARROWER array than the receiver:
+   *
+   *   xs.filter((x) => x !== undefined)   // TS-inferred type predicate
+   *   xs.filter(Boolean)                  // BooleanConstructor overload
+   *
+   * Trust discipline: only tests the RUNTIME actually performs may re-tag.
+   * An INFERRED predicate (inline arrow/function expression with no return
+   * annotation — TS 5.5 only infers `x is T` when the body proves it) and
+   * `Boolean` (retained elements are truthy, hence never the undefined/
+   * null arm) both qualify; a HAND-WRITTEN `x is T` annotation is an
+   * unchecked assertion (a lying one would corrupt the extraction) and
+   * stays fenced. The narrowed element must be a SINGLE arm of the
+   * receiver's union — retained elements re-tag through unionNarrow in the
+   * synthesized loop; a multi-arm target would need the union-to-union
+   * re-tag that doesn't exist (fenced with the annotate-the-callback
+   * escape). Null hands non-narrowing filters to the generic HOF path. */
+export declare function lowerFilterNarrowCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** The interned keys-array helper over a FIXED record shape: a call of a
+ * lifted helper whose body pushes each declared field name in first-seen
+ * DECLARATION order, skipping fields currently holding the undefined arm
+ * of their union at runtime (Node's missing key — an unset optional
+ * never made it into the object; SEMANTICS.md 37's rules). ONE
+ * construction, interned per shape, shared by Object.keys and for-in —
+ * for-in iterates exactly the keys Object.keys answers. */
+export declare function recordKeysArrayCall(L: Lowerer, receiver: IrExpr, argIr: IrType & {
+    kind: "record";
+}, shape: {
+    declaredOrder?: string[];
+    fields: {
+        name: string;
+        type: IrType;
+    }[];
+}, loc: SrcLoc): IrExpr;
+export declare function lowerFunction(L: Lowerer, decl: ts.FunctionDeclaration): IrFunction | null;
+export declare function lowerRecordFieldCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** The function-like node behind an object-literal generic-method member:
+   * the MethodDeclaration itself (`{ m<T>(x: T) {...} }`) or a generic
+   * arrow/function-expression property's initializer (`{ m: <T>(x: T) =>
+   * ... }`). Null when the property's declaration isn't that shape. */
+export declare function objLitGenericFnNodeOf(L: Lowerer, propSym: ts.Symbol): {
+    fnNode: ts.MethodDeclaration | ts.FunctionExpression | ts.ArrowFunction;
+    literal: ts.ObjectLiteralExpression;
+} | null;
+/** The interned GenericFnInfo for one object-literal generic method, with
+   * the supportability fences applied ONCE per declaration: the defining
+   * literal must sit at module scope (the compiled instance is a plain
+   * module function — an enclosing frame would need captures), and
+   * async/generator forms keep the method fences. The name is source-
+   * position-derived (`%ol<start>.<name>`, qualified per file) —
+   * deterministic across the discovery and emit passes. */
+export declare function objLitGenericFnInfoOf(L: Lowerer, blame: ts.Node, name: string, found: {
+    fnNode: ts.MethodDeclaration | ts.FunctionExpression | ts.ArrowFunction;
+    literal: ts.ObjectLiteralExpression;
+}): GenericFnInfo;
+/** True when nothing in `sym`'s DECLARING FILE ever writes it after the
+   * initializer: assignments (plain and compound, destructuring targets
+   * included), ++/--, and for-of/for-in expression targets all count.
+   * Sound file-locally for module-scope bindings because ESM import
+   * bindings are read-only — no other file can write one. Cached per
+   * symbol (the scan walks the whole file once). */
+export declare function bindingNeverReassigned(L: Lowerer, sym: ts.Symbol, decl: ts.Node): boolean;
+/** The generic function-like INITIALIZER behind a binding declaration —
+   * `const f = <T>(x: T) => x` or `const f = function g<T>(x: T) {...}`
+   * (parens stripped). Null when the declaration isn't that shape; the
+   * SHAPE only — whether the binding qualifies (module scope, never
+   * reassigned) is bindingGenericFnInfoOf's business. */
+export declare function bindingGenericFnNodeOf(decl: ts.VariableDeclaration): ts.FunctionExpression | ts.ArrowFunction | null;
+/** The interned GenericFnInfo for one generic arrow/function-expression
+   * binding initializer, with the supportability fences applied ONCE per
+   * declaration: the binding must sit at module scope (the compiled
+   * instances are plain module functions — an enclosing frame would need
+   * captures) and must provably HOLD the initializer once initialized — a
+   * const, or a let/var nothing in its declaring file ever writes (ESM
+   * import bindings are read-only, so the file scan is the whole story;
+   * observing the UNINITIALIZED state needs a hoisted early call, the
+   * same temporal hole const TDZ leaves — the object-literal generic-
+   * method receiver stance). Successful registration enters the info
+   * in genericFnsBySymbol under the binding's symbol — and under a named
+   * function expression's own inner name (it binds itself inside the
+   * body, the class-expression rule) — so every genericFnOf consumer
+   * (calls, pinned values, instantiation expressions, namespace and CJS
+   * member paths) resolves it like a top-level generic declaration. */
+export declare function bindingGenericFnInfoOf(L: Lowerer, decl: ts.VariableDeclaration, fnNode: ts.FunctionExpression | ts.ArrowFunction): GenericFnInfo;
+/** Static resolution stands in for the receiver's runtime value, so an
+   * object-literal generic-method receiver must provably HOLD the defining
+   * literal: a direct read of a binding whose initializer IS that literal
+   * and that nothing ever reassigns — a const, or a let with no write in
+   * its declaring file (ESM import bindings are read-only, so the file
+   * scan is the whole story). The read is pure — call and value sites skip
+   * evaluating it entirely. A reassignable binding could hold a
+   * structurally identical literal with a DIFFERENT body, which static
+   * resolution would silently miss. */
+export declare function requireObjLitGenericReceiver(L: Lowerer, blame: ts.Node, recvExpr: ts.Expression, literal: ts.ObjectLiteralExpression, name: string): void;
+/** `o.m(args)` where `m` is an object-literal GENERIC method (own type
+   * parameters — the member is excluded from the record shape, see
+   * isGenericCallableMemberType): monomorphized per call site against the
+   * DEFINING literal's declaration, exactly like top-level generic
+   * functions. Resolution is static, so the receiver must provably BE the
+   * defining literal: a const binding whose initializer is that literal,
+   * read directly. The receiver read is pure and the compiled instance is
+   * a plain module function (no `this`, fenced), so the call lowers to a
+   * direct `call` of the instance with the receiver unevaluated. Claims
+   * every call whose member is generic-callable — lowering it or fencing
+   * with a named message. */
+export declare function lowerObjLitGenericMethodCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** `obj.method(args)` — whole-program devirtualization decides the form:
+   * a method some strict subclass of the receiver's STATIC class overrides
+   * must dispatch on the dynamic class (`virtualCall`, through the vtable);
+   * everything else — standalone classes, non-overridden methods, leaf
+   * receivers — stays a direct `call` of the nearest declaration, exactly
+   * as before inheritance existed. */
+export declare function lowerObjectMethodCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;