@scriptc/compiler 0.0.7 → 0.0.9

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

@@ -9,7 +9,7 @@ import { type ClassInfo } from "./lower-classes.js";
  * 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";
+export type ParamMode = "required" | "omittable" | "rest" | "dynRest" | "islandRest";
 /** 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`
@@ -57,6 +57,12 @@ export interface GenericFnInfo {
     qualifiedName: string;
     /** Declaration-order type parameter symbols. */
     typeParams: ts.Symbol[];
+    /** Lazily computed (keyofConstrainedTypeParams): the type parameters
+     * declared `K extends keyof …`. Their bound LITERAL keys are semantic —
+     * the body's `o[k]` reads the named field — so instances key on the
+     * literal (no cross-literal sharing) and keep the checker types
+     * (tsBindings) the body resolves through. */
+    keyofTps?: Set<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
@@ -99,6 +105,11 @@ export interface GenericInstance {
     /** Type-parameter symbol → concrete IR type, consulted by mapType (via
      * typeParamResolver) while the instance body lowers. */
     bindings: Map<ts.Symbol, IrType>;
+    /** Call-keyed instances: type-parameter symbol → the bound CHECKER type
+     * (pre-widening), consulted while the body lowers where the IrType
+     * binding has already lost what the body needs — `T[K]` and `o[k]` reads
+     * whose K is bound to one literal key (typeParamTsBindings). */
+    tsBindings?: Map<ts.Symbol, ts.Type>;
     /** Rendered type arguments ("<number, string>") for diagnostics. */
     typeArgsText: string;
     /** Implicit instances only: param symbol → the call site's (widened)
@@ -242,28 +253,36 @@ export declare function genericCallInstance(L: Lowerer, expr: ts.CallExpression,
    * (`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;
+export declare function internGenericInstance(L: Lowerer, blame: ts.Node, info: GenericFnInfo, params: ParamShape[], returnType: IrType, makeBindings: (tsBindings: Map<ts.Symbol, ts.Type>) => Map<ts.Symbol, IrType>, opts?: {
+    extraKey?: string;
+    tsBindings?: Map<ts.Symbol, ts.Type>;
+}): GenericInstance;
+/** The type parameters of `info` declared with a `keyof` CONSTRAINT
+   * (`K extends keyof T`) — the parameters whose bound literal is semantic
+   * (the body's `o[k]` reads the named field), computed once per info from
+   * the declaration's syntax. */
+export declare function keyofConstrainedTypeParams(info: GenericFnInfo): Set<ts.Symbol>;
 /** 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>;
+   * mentions it, where mapType fails and badType names the shape
+   * (carrying the instantiation context). */
+export declare function inferTypeParamBindings(L: Lowerer, expr: ts.CallExpression, info: GenericFnInfo, rsig: ts.Signature, tsBindings?: Map<ts.Symbol, ts.Type>): 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;
+export declare function bindDefaultTypeParams(L: Lowerer, typeParams: readonly ts.Symbol[], typeParamDecls: readonly ts.TypeParameterDeclaration[] | undefined, bindings: Map<ts.Symbol, IrType>, tsBindings?: Map<ts.Symbol, ts.Type>): 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;
+export declare function unifySignatureBindings(L: Lowerer, info: GenericFnInfo, rsig: ts.Signature, bindings: Map<ts.Symbol, IrType>, tsBindings?: Map<ts.Symbol, ts.Type>): 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
@@ -354,6 +373,36 @@ export declare const TIMER_MODULE_MEMBERS: ReadonlySet<string>;
    * 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 RUNTIME-ARITY spread call — `f(...args)`, the rest-forwarding idiom
+   * (`const f = (...args) => from(...args)`): a spread whose length is a
+   * runtime fact has no home in the compile-time completion, so the call
+   * rides a dynamic boundary instead. Two lanes, picked by the spread
+   * source's tier:
+   *
+   * - CHECKED-DYNAMIC (dyn spread sources — a JS rest binding, a dyn
+   *   value): box the callee (dynFrom; a dyn callee is already boxed),
+   *   convert every argument into dyn, and emit the spread-marked dynCall
+   *   — the emitters build one fresh DOM argument array (spreads flatten
+   *   left-to-right, non-iterables throw V8's TypeError) and apply through
+   *   it; the boxed thunk delivers JS arity exactly. Result dyn, checked
+   *   per use like every any-origin value.
+   * - ISLAND (a jsval spread source — the --dynamic rest binding is the
+   *   engine's own arguments array): marshal the callee in and emit jsOp
+   *   callSpread — the prelude helper's REAL `f(...pre, ...s)`, so
+   *   iterator protocols and the not-iterable TypeError are the engine's
+   *   own. One trailing spread after the fixed arguments is the modeled
+   *   shape (exactly the forwarding idiom).
+   *
+   * Answers null when neither lane fits (typed .ts spreads keep
+   * completeArgs' rest packing and its fences). JS sources only — the
+   * same guard as the over-arity dynCall precedent. */
+export declare function lowerSpreadArgsCall(L: Lowerer, expr: ts.CallExpression, callee: IrExpr, loc: SrcLoc): IrExpr | null;
+/** True when a spread argument lands where the compile-time completion
+   * cannot take it — a FIXED parameter position, or a dynamic rest slot
+   * (dynRest/islandRest, whose packs are built per-argument): the shapes
+   * the runtime-arity lane (lowerSpreadArgsCall) serves. Typed `rest`
+   * slots keep completeArgs' same-element spread packing. */
+export declare function spreadNeedsRuntimeArity(shapes: readonly ParamShape[], argNodes: readonly ts.Expression[]): boolean;
 /** 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
@@ -534,6 +583,15 @@ export declare function bindingNeverReassigned(L: Lowerer, sym: ts.Symbol, decl:
    * 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 CONTEXTUAL twin of bindingGenericFnNodeOf: `const g: Mapper = (x)
+   * => x` where `type Mapper = <T>(x: T) => T` — the initializer declares
+   * no type parameters of its own, but the ANNOTATION's one call signature
+   * does, and the checker types the arrow's parameters by those (`x: T`).
+   * Such a binding monomorphizes exactly like `const g = <T>(x: T) => x`;
+   * bindingGenericFnInfoOf reads the type parameters off the annotation's
+   * signature. Null when the shape doesn't match (a concrete annotation, a
+   * generic arrow — the syntactic probe's case, an overloaded alias). */
+export declare function bindingContextualGenericFnNodeOf(L: Lowerer, 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
@@ -550,6 +608,18 @@ export declare function bindingGenericFnNodeOf(decl: ts.VariableDeclaration): ts
    * (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;
+/** `const h = id` — a binding ALIASING a generic function (a top-level
+   * declaration, a registered generic binding, or another alias — resolved
+   * left to right in declaration order). The alias registers the SAME info
+   * under its own symbol, so calls (`h(3)`) and pinned values (`take(h)`)
+   * resolve exactly like the target's own name, and the binding itself has
+   * no runtime value (a generic function value cannot materialize). Claims
+   * only bindings whose OWN type still keeps type parameters — a
+   * concrete-annotated alias (`const h: (x: number) => number = id`) is a
+   * pinned VALUE, the existing lowerGenericFnValue story. Null when the
+   * shape doesn't match or the target isn't a registered generic; fences
+   * (reassignment, var redeclaration) report by name inside. */
+export declare function bindingGenericFnAliasInfoOf(L: Lowerer, decl: ts.VariableDeclaration): GenericFnInfo | null;
 /** 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
@@ -560,17 +630,6 @@ export declare function bindingGenericFnInfoOf(L: Lowerer, decl: ts.VariableDecl
    * 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