@scriptc/compiler 0.0.0 → 0.0.2

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

@@ -0,0 +1,727 @@
+import * as ts from "../ts7/adapter.js";
+import type { Lowerer } from "./lowerer.js";
+import { IrClassDef, IrExpr, IrFunction, IrLocal, IrStmt, IrType, SrcLoc } from "../../ir/nodes.js";
+import { type GenericFnInfo, type ParamShape } from "./lower-calls.js";
+import { type MixinInstanceInfo } from "./lower-mixins.js";
+export interface ClassInfo {
+    def: IrClassDef;
+    /** ALL fields visible on instances — the inherited ones included — for
+     * receiver-side lookup (def.fields carries the layout order). */
+    fields: Map<string, IrType>;
+    /** OWN fields only (declaration order) with their initializers: the
+     * class's constructor runs exactly these — inherited fields initialize in
+     * the base constructor, before/via super(). */
+    fieldOrder: {
+        name: string;
+        type: IrType;
+        initializer: ts.Expression | undefined;
+    }[];
+    /** OWN declared methods only — inherited lookups walk the base chain
+     * (findMethodOn). An `abstract` entry is a signature with no body (and
+     * no module function): it declares the vtable slot; concrete subclasses
+     * fill it (tsc guarantees every instantiable class implements). */
+    methods: Map<string, {
+        params: ParamShape[];
+        ret: IrType;
+        abstract?: true;
+        async?: true;
+    }>;
+    /** OWN GENERIC instance methods (own type parameters — `m<T>(x: T)`),
+     * monomorphized per call site like top-level generic functions: instance
+     * `n` is the module function `%C.m%n` taking `this` as param 0. They
+     * never enter `methods` (no single ABI signature, no vtable slot), so
+     * dispatch is STATIC — calls resolve the nearest declarer on the
+     * receiver's static class, and a receiver whose runtime class could
+     * override (genericOverrideBelow) must be exact or fences. Inherited
+     * lookups walk the base chain (findGenericMethodOn). */
+    genericMethods?: Map<string, GenericFnInfo>;
+    /** OWN GENERIC static methods — `%C.static:m%n` module functions, the
+     * generic twin of staticMethods (same this/super fence, same
+     * through-a-VALUE shadowing rules via staticShadowBelow). */
+    genericStatics?: Map<string, GenericFnInfo>;
+    /** null for the builtin error classes (runtime-provided; no source).
+     * Class EXPRESSIONS carry their ts.ClassExpression here — members,
+     * accessors, and locs read identically off either form. */
+    decl: ts.ClassLikeDeclaration | null;
+    /** Runtime-provided builtin (the Error hierarchy): no bodies lower, `new`
+     * and super() calls become error.* libCalls, toString is the runtime's. */
+    builtinError?: true;
+    /** Runtime-provided node:events EventEmitter: no bodies lower, `new` and
+     * super() become emitter.* libCalls, and the whole method surface
+     * (on/emit/...) lowers through lower-emitter.ts over any class rooted
+     * here. Subclass structs embed the ScrEmitter prefix. */
+    builtinEmitter?: true;
+    /** Runtime-provided node:stream class (Readable/Writable/Duplex/
+     * Transform/PassThrough — emitter-rooted): no bodies lower, `new`
+     * becomes a stream constructor libCall, the stream method/property
+     * surface lowers through lower-stream.ts, and the emitter surface rides
+     * the base chain. The value names which SIDES the class carries. User
+     * `extends` of these classes is fenced at the declaration (phase 1). */
+    builtinStream?: "r" | "w" | "rw";
+    ctor: ts.ConstructorDeclaration | null;
+    /** PARAMETER PROPERTIES (`constructor(public x: number)`), in parameter
+     * order: each declares a field (placed BEFORE the class's declared
+     * fields in the layout — Node's transform hoists the definitions to the
+     * top of the class body, verified) and assigns it from the parameter's
+     * body local AFTER the field initializers run (Node's order: super() →
+     * field initializers → parameter-property assignments → ctor body). */
+    paramProps?: {
+        name: string;
+        type: IrType;
+        param: ts.ParameterDeclaration;
+    }[];
+    /** EFFECTIVE constructor params: the own constructor's, or (constructor
+     * omitted) the base's — `new Derived(...)` is typed by tsc against the
+     * inherited signature, and the synthesized constructor forwards to it
+     * (forwarding the completed ABI values; defaults apply in the base). */
+    ctorParams: ParamShape[];
+    base: ClassInfo | null;
+    /** DIRECT subclasses, filled as derived classes collect — the frontend's
+     * side of whole-program devirtualization (overrideBelow). */
+    subclasses: ClassInfo[];
+    /** Property names whose setter this class SYNTHESIZES as a throw: a
+     * getter-only override shadows an inherited get/set pair in JS, so a
+     * base-typed write reaches this class and throws TypeError (Node's
+     * behavior, matched exactly — see collectClassShape). */
+    throwingSetters: string[];
+    /** STATIC fields with initializers — the honest static subset: each is
+     * a module global (`%g.s.<C>.<name>`), assigned once in the declaring
+     * file's %init at the class statement's source position (exactly when
+     * JS evaluates static initializers, so an initializer reading earlier
+     * module bindings sees their values), and read as `C.name` anywhere
+     * (lowerStaticFieldRead). Writable (non-readonly) fields are MUTABLE
+     * globals; writes lower only through the DECLARING class's own name
+     * (`D.x = v` where x is inherited creates an OWN property on D in JS —
+     * different storage — and writes through class VALUES would need the
+     * same dynamic story: both are named fences). Accessors and
+     * initializer-less fields keep the fence. */
+    staticFields: {
+        name: string;
+        type: IrType;
+        initializer: ts.Expression;
+        globalId: string;
+        readonly: boolean;
+    }[];
+    /** STATIC methods — ordinary module functions named `%C.static:m` (the
+     * accessor-colon trick: no user identifier can spell it, and statics
+     * never join vtables, so IrClassDef doesn't know them). `C.m(args)` is
+     * a direct call; `const f = C.m` a zero-capture closure; calls through
+     * class VALUES devirtualize when no strict descendant redeclares the
+     * member. `this`/`super` inside fence at lowering (JS binds `this` to
+     * the RECEIVER class — dynamic). Absent on builtin classes. */
+    staticMethods?: Map<string, {
+        params: ParamShape[];
+        ret: IrType;
+        member: ts.MethodDeclaration;
+    }>;
+    /** `static { ... }` blocks, in declaration order. They are DECLARATION-TIME
+     * CODE, not shape: JS runs each block once when the class statement
+     * evaluates, whether or not anything ever references the class — so their
+     * statements lower into the declaring file's %init at the class statement's
+     * source position, interleaved with the static field initializers in member
+     * order (lowerStaticFieldInits). `this` inside a block (the class
+     * constructor value — no value form here) fences at collection. Absent on
+     * builtin classes and classes without blocks. */
+    staticBlocks?: ts.ClassStaticBlockDeclaration[];
+    /** SYMBOL-KEYED fields (`this[kLimit] = v` where kLimit is a module-level
+     * `const k = Symbol(...)`): the key's unique-symbol identity is a
+     * compile-time constant, so each key resolves to an ORDINARY hidden slot
+     * in the static layout — no runtime symbol table exists. The map goes
+     * key-symbol → layout field name (`Symbol(limit)`, Node's inspect
+     * spelling); inherited entries are seeded from the base like `fields`.
+     * Absent on builtin classes and classes with no symbol-keyed fields. */
+    symbolFields?: Map<ts.Symbol, string>;
+    /** GENERIC class FAMILY (`class Box<T>` itself): the synthetic,
+     * never-constructed ancestor every instantiation extends. It owns what
+     * JS's one runtime `Box` owns — the statics (one storage location for
+     * every instantiation) and the `instanceof Box` interval — and declares
+     * no fields, no instance methods, no constructor function. Construction
+     * and instance types resolve to instantiations instead (`generic`
+     * carries the instance table). */
+    generic?: GenericClassInfo;
+    /** GENERIC class INSTANTIATION (`Box%0` for `Box<number>`): the family,
+     * the type-parameter bindings member lowering runs under (the
+     * generic-fn typeParamResolver mechanism), the rendered type arguments
+     * for diagnostics, and the demand ordinal (only the FIRST instantiation
+     * counts statements toward coverage — re-instantiations re-visit the
+     * same source lines). */
+    genericInstance?: {
+        family: ClassInfo;
+        bindings: Map<ts.Symbol, IrType>;
+        typeArgsText: string;
+        ordinal: number;
+    };
+    /** MIXIN instantiation (`%mx<start>.<name>` for `M(Base)` at one call
+     * site): the call that minted it, the base-parameter type binding its
+     * members lower under, the forwarding-constructor flag, and where its
+     * static declaration-time code emits (lower-mixins.ts). */
+    mixinInstance?: MixinInstanceInfo;
+    /** CLASS decorators (`@dec class C`) — standard (TC39 stage-3 / TS 5+)
+     * semantics, lowered statically as declaration-time CALLS in %init at
+     * the class statement's position: decorator expressions evaluate in
+     * source order, applications run in REVERSE order over the class object,
+     * and static field initializers/blocks run AFTER the applications (the
+     * verified Node order). Present exactly when the declaration carries
+     * class-level decorators; `shapes` fills in the post-collection analysis
+     * pass (a decorator's return type may name a subclass declared BELOW the
+     * class, so analysis cannot run while shapes are still collecting). */
+    classDecorators?: ClassDecorationInfo;
+    /** The class's decoration PROVABLY throws before anything else in its
+     * definition evaluates (the first effectful item in TC39 evaluation
+     * order — class decorators, then heritage, then member decorators and
+     * computed keys interleaved — is an AMBIENT decorator name nothing
+     * defines; Node erases the declaration, so the read is a
+     * ReferenceError). The class registers as an empty SHELL: no members
+     * collect (nothing after the throw ever runs — member fences would be
+     * fences on dead code), the %init at the class statement is exactly the
+     * throw, and every VALUE use (new, the class as a value, extends)
+     * fences — the binding never initializes, so compiled code can never
+     * legitimately reach one. */
+    decorationThrows?: {
+        name: string;
+    };
+}
+/** A decorated class's decoration state (see ClassInfo.classDecorators). */
+export interface ClassDecorationInfo {
+    /** The class-level decorator nodes, source order. */
+    nodes: ts.Decorator[];
+    /** Per-decorator analysis (parallel to `nodes`). `call`: the decorator
+     * expression's completed function type — the type its VALUE lowers to
+     * and the ABI the application call dispatches — and whether it can
+     * REPLACE the class (return type is the class or a subclass, per the
+     * classval flow rule) rather than returning void/undefined.
+     * `ambientThrow`: the decorator names an ambient declaration NOTHING
+     * defines (`declare let dec: any`, `declare function dec<T>(t: T): T`)
+     * — Node erases it, so evaluating the decorator expression throws the
+     * ReferenceError; the program compiles to exactly that crash. */
+    shapes?: ({
+        kind: "call";
+        funcType: Extract<IrType, {
+            kind: "func";
+        }>;
+        replaces: boolean;
+    } | {
+        kind: "ambientThrow";
+        name: string;
+    })[];
+    /** Analysis fenced — diagnostics already reported; emission skips. */
+    poisoned?: true;
+    /** The MUTABLE classval module global holding the decoration RESULT,
+     * present exactly when some decorator can replace the class. TC39 binds
+     * the class NAME to the last non-undefined decorator return, so every
+     * reference to the name routes through this value: bare reads load it,
+     * `new C()` dispatches newValue through it, `C.x` takes the
+     * through-a-VALUE static paths, and `instanceof C` reads its interval
+     * (instanceOfValue). Absent when every decorator returns void/undefined
+     * — the binding provably stays the original class object and every
+     * direct path stays direct. */
+    valueGlobalId?: string;
+}
+/** A generic class declaration's monomorphization state, hung off the
+ * FAMILY ClassInfo (registered under the class's own qualified name and
+ * bound to its symbol — `new`, `instanceof`, statics, and extends all
+ * resolve to the family first and reroute to instantiations from there).
+ * Instances key by comma-joined type-argument typeKeys; `info` is null
+ * WHILE the instance's shape collects (self-referential layouts — `next:
+ * Box<T> | null` — re-enter by key and take the name without recursing)
+ * and stays null with `poisoned` set when collection fenced. */
+export interface GenericClassInfo {
+    decl: ts.ClassDeclaration;
+    /** Unqualified source name, for diagnostics. */
+    baseName: string;
+    /** Declaration-order type parameter symbols. */
+    typeParams: ts.Symbol[];
+    family: ClassInfo;
+    instances: Map<string, {
+        name: string;
+        info: ClassInfo | null;
+        poisoned?: boolean;
+    }>;
+}
+/** The builtin Error hierarchy (Error + TypeError/RangeError/SyntaxError)
+   * as eagerly-registered ClassInfos: mapType names them the moment a lib
+   * Error type appears, so the infos must exist before any lowering. They
+   * are runtime-provided — no decl, no lowerable bodies; `new`/super()/
+   * toString reach them through dedicated error.* libCall lowerings, and
+   * user classes extend them like any base (the emitted subclass struct
+   * embeds ScrError's prefix). */
+export declare function registerBuiltinErrorClasses(L: Lowerer): void;
+/** The runtime-provided node:events EventEmitter as an eagerly-registered
+   * ClassInfo (the error-hierarchy story): mapType names `%EventEmitter`
+   * the moment an emitter type appears, so the info must exist before any
+   * lowering. No decl, no lowerable bodies — `new`/super() reach it
+   * through emitter.* libCalls, the method surface lowers through
+   * lower-emitter.ts, and user classes extend it like any base (the
+   * emitted subclass struct embeds ScrEmitter's registry/name prefix —
+   * carried by the BACKEND, not by IR fields, so the fields list stays
+   * empty and subclass field layout starts right after the prefix). */
+export declare function registerBuiltinEmitterClass(L: Lowerer): void;
+/** The runtime-provided node:stream classes as eagerly-registered
+   * ClassInfos (the emitter story): mapType names `%Readable` et al the
+   * moment a stream type appears, so the infos must exist before any
+   * lowering. Each roots at the emitter through its base chain, so the
+   * EventEmitter method surface, upcasts, and instanceof intervals apply
+   * unchanged; the stream method/property surface lowers through
+   * lower-stream.ts. No decl, no lowerable bodies, empty field lists —
+   * every instance is runtime-allocated (user `extends` is fenced). */
+export declare function registerBuiltinStreamClasses(L: Lowerer): void;
+/** The stream ClassInfo a VALUE symbol refers to (`new Readable(...)`,
+   * `x instanceof Writable`) — any import spelling resolves to the
+   * ambient class. Provenance: a stdlib-file CLASS declaration inside the
+   * "stream" ambient module, EXCLUDING @types/node's (whose stream.Readable
+   * also types child stdio — under @types/node the childStream mapping
+   * keeps priority and the static stream classes stand down; the shipped
+   * fallback declarations are the supported surface). */
+export declare function builtinStreamInfoOf(L: Lowerer, symbol: ts.Symbol | null | undefined): ClassInfo | null;
+/** The emitter ClassInfo a VALUE symbol refers to (`new EventEmitter`,
+   * `extends EventEmitter`, `x instanceof EventEmitter`) — any import
+   * spelling (named/default/namespace member, CJS require) resolves to
+   * the ambient class. Provenance-checked like the error classes: only a
+   * stdlib-file declaration inside the "events" ambient module counts. */
+export declare function builtinEmitterInfoOf(L: Lowerer, symbol: ts.Symbol | null | undefined): ClassInfo | null;
+/** The builtin error ClassInfo a VALUE symbol refers to (`new Error`,
+   * `extends TypeError`, `x instanceof RangeError`), or null. Provenance-
+   * checked: only the standard library's declarations count — a user's own
+   * `class Error` resolves through classBySymbol instead. */
+export declare function builtinErrorInfoOf(L: Lowerer, symbol: ts.Symbol | null | undefined): ClassInfo | null;
+/** The instance-method surface the runtime EventEmitter owns — subclass
+ * members with these names are fenced (collectClassShapeInner) and calls
+ * to them on emitter-rooted receivers lower through lower-emitter.ts. */
+export declare const EMITTER_API_MEMBERS: ReadonlySet<string>;
+/** The decorators of a class-like or member node (they live in
+   * `modifiers` since TS 4.8). */
+export declare function decoratorNodesOf(n: ts.Node): ts.Decorator[];
+/** The AMBIENT name a decorator expression's evaluation throws on, or
+   * null. Node erases ambient declarations (`declare let dec: any`,
+   * `declare const instance: T`, `declare function dec<T>(t: T): T`), so
+   * reading the name is a ReferenceError. Factory spellings ride along —
+   * `@dec(...)` evaluates the CALLEE before any argument — and property
+   * chains throw at their ROOT (`@instance.decorate` reads `instance`
+   * first). */
+export declare function ambientDecoratorThrowNameOf(L: Lowerer, dExpr: ts.Expression): string | null;
+/** The guaranteed decoration THROW of a decorated class, or null. Walks
+   * the class definition's evaluation-order items — class decorators
+   * (source order), the heritage expression, then per member in body
+   * order its decorators and computed key (the verified TC39/tsc-downlevel
+   * order) — and answers the first AMBIENT decorator name, provided every
+   * item BEFORE it is provably effect-free and non-throwing: bare
+   * identifier decorators over defined values (a pure read), an absent /
+   * `null` / bare-identifier heritage, literal or bare-identifier
+   * computed keys. Anything richer (factory calls over defined values,
+   * property-access reads, computed-key calls) stops the proof — the
+   * named fences answer instead. */
+export declare function guaranteedDecorationThrow(L: Lowerer, decl: ts.ClassLikeDeclaration): {
+    name: string;
+    node: ts.Decorator;
+} | null;
+export declare function collectClassShape(L: Lowerer, decl: ts.ClassDeclaration): void;
+export declare function collectClassShapeInner(L: Lowerer, decl: ts.ClassLikeDeclaration, jsNameOverride?: string, inst?: {
+    family: ClassInfo;
+    name: string;
+    bindings: Map<ts.Symbol, IrType>;
+    typeArgsText: string;
+    ordinal: number;
+}, 
+/** MIXIN instantiation mode (lower-mixins.ts): the class inside a
+ * mixin function, collected per call site — `base` is the ARGUMENT
+ * class (the heritage clause names the mixin's parameter and is
+ * resolved here, never through the loop below), `name` the
+ * position-derived instance name. */
+mixin?: {
+    base: ClassInfo;
+    name: string;
+    call: ts.CallExpression;
+    bindings: Map<ts.Symbol, IrType>;
+    context: string;
+    ordinal: number;
+}): void;
+/** mapType's generic-class hook: the INSTANTIATION a concrete type
+   * reference (`Box<number>`) names — registered on first demand. The
+   * instance's NAME reserves its key before the shape collects, so
+   * self-referential layouts (`next: Box<T> | null`) re-enter here and
+   * take the name without recursing; a poisoned collection (a field type
+   * with no lowering under these bindings — the diagnostic carries the
+   * instantiation context) leaves the entry poisoned and the type
+   * unmapped, the fenced-JS-class story. Null answers (unmappable type
+   * arguments, the instance cap, an uncollected family) make the whole
+   * reference unmappable — per-site diagnostics own the fence. */
+export declare function genericClassInstanceType(L: Lowerer, decl: ts.ClassLikeDeclaration, ref: ts.Type): IrType | null;
+/** Runs a member-lowering thunk under an INSTANTIATION's type-parameter
+   * bindings (the generic-fn typeParamResolver mechanism) — the checker
+   * keeps reporting the unsubstituted `T`s inside the shared body AST.
+   * Coverage counts a generic class's statements once: only the FIRST
+   * instantiation contributes (the lowerGenericInstance rule). A no-op
+   * for ordinary classes. */
+export declare function withInstanceBindings<T>(L: Lowerer, info: ClassInfo, fn: () => T): T;
+/** The `%init` statements for one class's static readonly fields AND
+   * static blocks, interleaved in member order — emitted at the class
+   * statement's source position (see lowerFileInit's merge), exactly when
+   * JS evaluates static initializers and blocks. Field failures poison per
+   * field, like fieldInitStmts; a block lowers as the block statement it
+   * is, so its statements poison individually inside lowerStmts. */
+export declare function lowerStaticFieldInits(L: Lowerer, info: ClassInfo): IrStmt[];
+/** Post-collection analysis of a decorated class (all shapes registered —
+   * a decorator's return type may name a subclass declared BELOW the
+   * class). Classifies every class-level decorator by its checker type:
+   * exactly one parameter, itself a classval the decorated class legally
+   * flows into (the class, or a base sharing its completed constructor
+   * ABI — the classval widening rule), returning void/undefined (an
+   * effect-only decorator) or the class/a same-ABI subclass (a REPLACING
+   * decorator, whose result rebinds the name). Everything else is a named
+   * fence: the standard context parameter, structural sibling
+   * replacements tsc admits but the nominal classval world cannot carry,
+   * unions mixing the class with undefined. A replacing decorator
+   * registers the mutable classval global the name rebinds through, and
+   * fences the two shapes the value rebinding cannot keep exact —
+   * subclasses of the decorated class (the compiled hierarchy is fixed at
+   * build time; the runtime base would be the decoration result) and
+   * namespace-nested declarations (qualified references resolve the class
+   * directly, not through the rebound value). */
+export declare function analyzeClassDecoration(L: Lowerer, info: ClassInfo): void;
+/** The decoration statements of a decorated class — the %init code that
+   * runs at the class statement's position, BEFORE its static field
+   * initializers and blocks (lowerStaticFieldInits composes them; the
+   * lower-modules interleave places the whole bundle). Verified Node
+   * order: decorator expressions evaluate in SOURCE order (factories run
+   * here), then applications run in REVERSE member order over the class
+   * object, each replacing decorator's non-undefined result feeding the
+   * next application; the final value binds the class name (the mutable
+   * classval global) when any decorator can replace. */
+export declare function lowerClassDecoration(L: Lowerer, info: ClassInfo): IrStmt[];
+/** The nearest declaration of static member `name` at or above `info` —
+   * the compile-time prototype-chain walk (`D.x` reads C's global when C
+   * declared x and nothing between redeclares it; a redeclaration shadows
+   * with its OWN storage, exactly JS). */
+export declare function findStaticOn(L: Lowerer, info: ClassInfo | null, name: string): {
+    declarer: ClassInfo;
+    field: ClassInfo["staticFields"][number];
+    method?: undefined;
+} | {
+    declarer: ClassInfo;
+    method: {
+        params: ParamShape[];
+        ret: IrType;
+        member: ts.MethodDeclaration;
+    };
+    field?: undefined;
+} | null;
+/** True when some STRICT descendant of `info` redeclares static `name` —
+   * the through-a-VALUE devirtualization test: a classval(info) slot can
+   * hold any descendant, and a shadowing redeclaration means the runtime
+   * class decides which storage answers. */
+export declare function staticShadowBelow(L: Lowerer, info: ClassInfo, name: string): boolean;
+/** The nearest GENERIC static declaration of `name` at/above `info` —
+   * findStaticOn's twin over the genericStatics tables. */
+export declare function findGenericStaticOn(L: Lowerer, info: ClassInfo | null, name: string): {
+    declarer: ClassInfo;
+    info: GenericFnInfo;
+} | null;
+/** The class itself taken as a VALUE (`const X = C`, an argument, an
+   * array element, a class expression's result): the classRef over the
+   * per-class immortal class object. The construct thunk needs a thunk-
+   * shaped constructor, so classes whose construction is libCall-shaped —
+   * the runtime-provided builtins and anything inheriting a builtin
+   * constructor (Error/EventEmitter/stream chains complete their `new`
+   * by special rules) — are named fences here. The constructor edge is
+   * noted at every classRef: a value can always be constructed through. */
+export declare function classValueRef(L: Lowerer, info: ClassInfo, blame: ts.Node): IrExpr;
+/** Constructor-ABI equality — the classval widening rule: a classval(D)
+   * value may flow into a classval(C) slot only when D's completed
+   * constructor signature equals C's (same count, modes, and ABI types),
+   * which is what keeps newValue completion against C's one signature
+   * sound for every value legally in the slot. */
+export declare function ctorAbiEquals(L: Lowerer, sub: ClassInfo, sup: ClassInfo): boolean;
+/** `C.x` where C is a class declared in the program and x a static
+   * member of its chain: field reads are the module global, static
+   * methods become interned closures, and `.name` folds to the class's
+   * compile-time name. Null for everything else — unresolved members
+   * fall through to the ordinary chain so the static fence or the
+   * generic member rejection names the site. */
+export declare function lowerStaticFieldRead(L: Lowerer, expr: ts.PropertyAccessExpression): IrExpr | null;
+/** A class EXPRESSION's ClassInfo: collection on first encounter (the
+   * declaration path over the shared ClassLikeDeclaration machinery, with
+   * NamedEvaluation supplying the runtime .name), idempotent per node —
+   * probeLower's speculative visits and the heritage recursion reuse the
+   * first collection. The honest v1 boundary is TOP-LEVEL evaluation
+   * positions only: each evaluation of a class expression in JS mints a
+   * DISTINCT class (fresh identity, fresh statics), and one immortal
+   * class object is exact only for expressions that evaluate exactly
+   * once. Statics-bearing expressions additionally restrict to positions
+   * where "immediately before the enclosing statement" IS the evaluation
+   * point (lowerFileInit drains pendingClassExprInits there). */
+export declare function lowerClassExpressionInfo(L: Lowerer, expr: ts.ClassExpression): ClassInfo;
+/** `class {…}` in expression position: a class definition bound to no
+   * statement — once the static side is a value, the expression IS the
+   * definition plus a classRef over it. A DECORATED class expression
+   * whose decoration provably throws (the ambient-decorator shape) never
+   * mints a class at all: evaluating the expression IS the
+   * ReferenceError, so it lowers to exactly that read — every evaluation
+   * throws identically, which is why the once-evaluated restriction and
+   * the member fences don't apply. */
+export declare function lowerClassExpression(L: Lowerer, expr: ts.ClassExpression): IrExpr;
+/** The EXACT class a receiver expression is statically known to BE (not
+   * merely be typed by): the class name itself, or a `const` binding
+   * whose initializer is a class expression / class name. Such receivers
+   * can never hold a subclass at runtime, so static WRITES through them
+   * hit the declaring class's storage exactly (the shadowing hazards of
+   * general class values don't arise). Null for everything else. */
+export declare function exactClassOfReceiver(L: Lowerer, expr: ts.Expression): ClassInfo | null;
+/** The class a PROPERTY-ASSIGNMENT binding pins — the salsa/CJS
+   * declaration forms of a class expression: `Common.I = class {…}`
+   * (expando members of a plain object), `exports.I = class {…}` /
+   * `module.exports.I = class {…}` (CJS member exports), and
+   * `module.exports = class {…}` (the whole-export replacement, whose
+   * export symbol requirer bindings alias to). The symbol arrives in two
+   * shapes — an ALIAS resolving to the class expression's own symbol
+   * (valueDeclaration IS the ts.ClassExpression), or the expando property
+   * symbol whose declarations are the assignment BinaryExpressions — and
+   * both pin the class exactly when ONE top-level assignment declares it:
+   * a reassigned property is a dynamic binding (the runtime class is
+   * whichever assignment ran last), so it answers null and the caller's
+   * fence names it. Collection is on demand and idempotent
+   * (lowerClassExpressionInfo), so resolution order between files and
+   * passes never matters. */
+export declare function propertyAssignedClassInfoOf(L: Lowerer, symbol: ts.Symbol | null | undefined): ClassInfo | null;
+/** `C.m(args)` / `X.m(args)` — static method calls, on the class name
+   * directly or through a class VALUE. Resolution walks the chain
+   * (nearest declarer, the compile-time prototype chain); through a
+   * VALUE the call devirtualizes exactly when no strict descendant
+   * redeclares the member (values never leave the static class's
+   * subtree). A func-typed static FIELD in call position reads the
+   * global and calls through the value. Null when the receiver isn't a
+   * class name/value or the member doesn't resolve (the fences name the
+   * site downstream). */
+export declare function lowerStaticMethodCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
+/** Static member access through a class VALUE (`X.m` where X is
+   * classval-typed): devirtualized — the member resolves against the
+   * static class's chain, exact when no strict descendant redeclares it
+   * (values in the slot never leave the subtree). `X.name` is the one
+   * genuinely dynamic member: the class.name libCall reads the runtime
+   * class object's stored name. Null when the receiver isn't a class
+   * value or the member doesn't resolve. */
+export declare function lowerClassValueProperty(L: Lowerer, expr: ts.PropertyAccessExpression): IrExpr | null;
+/** The nearest declaration of `name` at or above `info` — the method a
+   * receiver of that static class runs when nothing below overrides it. */
+export declare function findMethodOn(L: Lowerer, info: ClassInfo | null, name: string): {
+    declarer: ClassInfo;
+    sig: {
+        params: ParamShape[];
+        ret: IrType;
+        abstract?: true;
+        async?: true;
+    };
+} | null;
+/** True when `sub` is a STRICT descendant of `sup` in the class graph. */
+export declare function isSubclassOf(L: Lowerer, sub: string, sup: string): boolean;
+/** In an extends-hierarchy (as base or derived): the class carries a
+   * vtable and participates in dynamic instanceof; standalone classes keep
+   * their exact pre-inheritance layout and behavior. */
+export declare function inHierarchy(L: Lowerer, info: ClassInfo): boolean;
+/** True when some STRICT descendant of `info` declares `name` with a BODY
+   * — the whole-program devirtualization test: a call through this static
+   * class can reach a distinct implementation, so it must dispatch
+   * dynamically. Abstract re-declarations don't count (they carry no
+   * implementation; the concrete ones below them do, via the recursion). */
+export declare function overrideBelow(L: Lowerer, info: ClassInfo, name: string): boolean;
+/** The nearest GENERIC-method declaration of `name` at/above `info` —
+   * findMethodOn's twin over the genericMethods tables. */
+export declare function findGenericMethodOn(L: Lowerer, info: ClassInfo | null, name: string): {
+    declarer: ClassInfo;
+    info: GenericFnInfo;
+} | null;
+/** True when some STRICT descendant of `info` re-declares the generic
+   * method `name` — overrideBelow's twin: generic methods have no vtable
+   * slot, so a call that could reach an override compiles only when the
+   * receiver's runtime class is statically exact. */
+export declare function genericOverrideBelow(L: Lowerer, info: ClassInfo, name: string): boolean;
+/** The receiver's EXACT runtime class, when the expression proves it: a
+   * `new C(...)` expression directly, or a const binding initialized with
+   * one (the binding can never be reassigned to a subclass instance).
+   * The class is read off the mapped INITIALIZER type — a `const b: Base =
+   * new D()` receiver is exactly D, not its annotation. Distinct from
+   * exactClassOfReceiver, which answers for CLASS-VALUE receivers. */
+export declare function exactInstanceClassOf(L: Lowerer, expr: ts.Expression): ClassInfo | null;
+/** `recv.m<T>(args)` — a GENERIC method call, dispatched STATICALLY: the
+   * checker's resolved signature (type arguments substituted, inferred or
+   * explicit) keys one instantiation of the nearest declarer's body, and
+   * the call is a direct `call` of `%C.m%n` over the (up/down)cast
+   * receiver. No per-instantiation vtable slots exist, so a receiver whose
+   * runtime class could OVERRIDE the method (genericOverrideBelow) must be
+   * statically exact (exactInstanceClassOf) — the override set then
+   * resolves at compile time — or fences by name. */
+export declare function lowerClassGenericMethodCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression, recvInfo: ClassInfo, found: {
+    declarer: ClassInfo;
+    info: GenericFnInfo;
+}): IrExpr;
+/** Wraps a derived-class expression in an upcast when the target base
+   * class differs (a no-op reinterpret at runtime; keeps IR types exact). */
+export declare function upcastTo(L: Lowerer, expr: IrExpr, className: string): IrExpr;
+export declare function lowerClassMembers(L: Lowerer, info: ClassInfo): IrFunction[];
+/** The constructor function `%C.constructor`. Synthesized when absent: a
+   * base class runs just its field initializers; a derived class inherits
+   * the base's signature — forward every param to super(), then run own
+   * field initializers. */
+export declare function lowerClassCtor(L: Lowerer, info: ClassInfo): IrFunction;
+/** The lowered method-map name of a class member: identifier text, a
+   * COMPUTED name that folds to one compile-time string
+   * (foldedStringKeyOf — the object-literal computed-key machinery
+   * applied to method positions; tsc late-bound the member under exactly
+   * that name), or the reserved slot "sym:iterator" for
+   * `[Symbol.iterator]` (a name no user identifier can spell — the
+   * accessor "get:x" convention; for-of, spreads, and array destructuring
+   * dispatch to it through the iterator protocol). Null for genuinely
+   * runtime-keyed names — the computed-member fences stay. */
+export declare function classMemberNameOf(L: Lowerer, name: ts.PropertyName): string | null;
+/** A class type's ITERATOR PROTOCOL shape, statically resolved: the
+   * receiver declares (or inherits) `[Symbol.iterator]()` (the
+   * "sym:iterator" method slot) returning a class whose zero-parameter
+   * `next()` returns a record with a `value` field and an optional
+   * boolean `done` field (`{ value, done: false }` — the self-iterator
+   * idiom returns `this`, so the iterator class is usually the receiver
+   * itself). A MISSING done field never terminates — exactly JS, where
+   * `undefined` is falsy forever (Node loops forever too; corpus
+   * iterators of that shape are deliberately infinite). Iterator classes
+   * declaring `return`/`throw` members stay out — the desugars below
+   * never call IteratorClose, and silently skipping a declared return()
+   * would drop user cleanup. Null when the shape doesn't hold — callers
+   * keep their fences. */
+export interface ClassIteratorInfo {
+    /** The `[Symbol.iterator]()` call's receiver class + its declarer. */
+    className: string;
+    /** The iterator object's type (the method's return). */
+    iterT: IrType & {
+        kind: "object";
+    };
+    /** next()'s result record type. */
+    resultT: IrType & {
+        kind: "record";
+    };
+    valueT: IrType;
+    /** False: no done field — the protocol never terminates. */
+    hasDone: boolean;
+}
+export declare function classIteratorOf(L: Lowerer, t: IrType): ClassIteratorInfo | null;
+/** The `it.next()` step of a class iterator as an ordinary (possibly
+   * virtual) method call. */
+export declare function classIteratorNextCall(L: Lowerer, cit: ClassIteratorInfo, itRef: IrExpr, loc: SrcLoc): IrExpr;
+/** `recv[Symbol.iterator]()` as an ordinary method call. */
+export declare function classIteratorOpenCall(L: Lowerer, cit: ClassIteratorInfo, recv: IrExpr, loc: SrcLoc): IrExpr;
+/** `[...new C]` / `f(...new C)` over a CLASS ITERABLE: the eager drain —
+   * an interned `%iter.drain.<n>(recv)` lifted function running the
+   * whole protocol into a fresh element array (a doneless iterator loops
+   * forever, exactly Node's spread of an infinite iterator). `elemT`
+   * (default: the iterator's own value type) is the DESTINATION element —
+   * a spread into a union-element literal (`[...numbers, ...symbols]` as
+   * `(number | symbol)[]`) pushes each value wrapped into its arm. Null
+   * when the value isn't a recognized class iterable or the element
+   * doesn't coerce — spread fences stay. */
+export declare function classIteratorDrainCall(L: Lowerer, src: IrExpr, loc: SrcLoc, elemT?: IrType): IrExpr | null;
+/** The tail of a class iterable's protocol from an already-open ITERATOR
+   * object (`var [a, ...rest] = new C` — the rest element drains whatever
+   * next() still yields): the drain loop keyed by the iterator class. */
+export declare function classIteratorRestDrainCall(L: Lowerer, cit: ClassIteratorInfo, itVal: IrExpr, loc: SrcLoc): IrExpr;
+/** One method or accessor body as its module function `%C.name`
+   * (accessors are methods with property syntax: "get:x"/"set:x" entries —
+   * see collectClassShape). */
+export declare function lowerClassMethodMember(L: Lowerer, info: ClassInfo, fnLike: ts.MethodDeclaration | ts.AccessorDeclaration): IrFunction | null;
+/** One static method body as its module function `%C.static:m` — an
+   * ordinary function with NO `this` param. `this` and `super` inside
+   * name the RECEIVER class in JS (dynamic — `F.who()` sees F even when
+   * who() is declared on E), which has no static story here: both are
+   * named fences, with arrow functions transparent (they inherit the
+   * method's `this`) and this-binding function forms opaque — the static-
+   * block rule verbatim. */
+export declare function lowerStaticMethod(L: Lowerer, info: ClassInfo, name: string): IrFunction | null;
+/** A synthesized throwing setter: a getter-only override shadows the
+   * inherited pair (JS), so a base-typed write dispatches HERE and must
+   * throw exactly like Node's TypeError — a real instance (a typed catch's
+   * `e instanceof TypeError` matches), catchable, exit 1 uncaught (message
+   * text is compiler-worded; stdout and exit code are the contract). */
+export declare function throwingSetterFn(L: Lowerer, info: ClassInfo, prop: string): IrFunction;
+/** The base a constructor chain actually CALLS into: generic FAMILIES are
+   * never constructed (no `%<family>.constructor` exists), so an
+   * instantiation's construction-relevant base is the family's own base —
+   * null when the generic class extends nothing, exactly the source's
+   * story (tsc forbids super() there). Ordinary classes answer their base
+   * unchanged. */
+export declare function superBaseOf(info: ClassInfo): ClassInfo | null;
+/** The class's OWN field initializers as fieldSet statements (declaration
+   * order) — a base constructor's prologue, a derived constructor's
+   * super()-return continuation. */
+export declare function fieldInitStmts(L: Lowerer, info: ClassInfo, thisLocal: IrLocal): IrStmt[];
+/** PARAMETER-PROPERTY assignments (`this.x = x`, synthesized): run AFTER
+   * the field initializers — Node's transform defines the fields at the
+   * top of the class body (undefined until assigned) and injects the
+   * assignments at the start of the constructor body, i.e. after super()
+   * and after the (native) field initializers ran (probed: a field
+   * initializer reading `this.x` sees undefined; the body sees the value).
+   * Each assignment reads the parameter's BODY local (defaults already
+   * applied by the declareParams prologue), whose type the collection made
+   * the field's type — slot-exact by construction. */
+export declare function paramPropInitStmts(L: Lowerer, info: ClassInfo, thisLocal: IrLocal): IrStmt[];
+/** A derived constructor's body: statements lower as usual EXCEPT the
+   * top-level `super(...)` statement, which becomes a direct call to the
+   * base constructor over the same `this`, immediately followed by this
+   * class's field initializers (JS runs them when super returns). tsc
+   * guarantees a super call exists and runs before any this-use; the
+   * supported form is a top-level expression statement — anywhere else
+   * (conditionals, expression positions) is rejected, not misordered. */
+export declare function lowerDerivedCtorBody(L: Lowerer, info: ClassInfo, thisLocal: IrLocal, 
+/** Mixin forwarding-constructor mode: `super(...args)` forwards these
+ * pre-declared synthetic params directly (the spread never lowers —
+ * the base's ABI is this constructor's ABI). */
+forward?: IrExpr[]): IrStmt[];
+/** `super(args)` → direct call of the base constructor with the SAME
+   * `this` (upcast; retained by the varRef read — the callee owns and
+   * releases its param per the universal convention). */
+export declare function superCallStmt(L: Lowerer, info: ClassInfo, thisLocal: IrLocal, args: IrExpr[], loc: SrcLoc): IrStmt;
+/** `super.method(args)`: the base chain's implementation, called
+   * DIRECTLY over this method's own `this` (upcast to the declarer) —
+   * super dispatch is static in JS too, never through the dynamic class. */
+export declare function lowerSuperMethodCall(L: Lowerer, call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr;
+/** The `this` reference for super accessor reads/writes, with the shared
+   * validity checks (derived-class body, resolvable this). */
+export declare function superThisRef(L: Lowerer, access: ts.PropertyAccessExpression): {
+    thisRef: IrExpr;
+    base: ClassInfo;
+};
+/** `super.x` read: a DIRECT call of the base chain's getter over this
+   * method's own `this` (upcast to the declarer) — like super.method(),
+   * never through the vtable. */
+export declare function lowerSuperAccessorRead(L: Lowerer, access: ts.PropertyAccessExpression): IrExpr;
+/** `super.x = v`: a DIRECT call of the base chain's setter (same
+   * static-dispatch rule as every super member access). */
+export declare function lowerSuperAccessorWrite(L: Lowerer, access: ts.PropertyAccessExpression, rhs: ts.Expression, loc: SrcLoc): IrStmt;
+/** True when `info`'s EFFECTIVE constructor — its own, or the one
+   * inherited through ctor-less bases — is a builtin error class's. Such
+   * classes construct with the error message rule, and their synthesized
+   * constructors forward one plain string to error.ctor. */
+export declare function inheritsBuiltinErrorCtor(L: Lowerer, info: ClassInfo): boolean;
+/** The EventEmitter twin: a ctor-less chain into the emitter base
+   * inherits `new C()` — zero arguments (the options bag fences). */
+export declare function inheritsBuiltinEmitterCtor(L: Lowerer, info: ClassInfo): boolean;
+/** The stream twin: a ctor-less chain into a runtime stream base
+   * inherits `new C()` — zero arguments (the synthesized constructor runs
+   * super() with default options; passing options through an inherited
+   * constructor would need the literal at the new-site to plumb, so it
+   * asks for a declared constructor instead). */
+export declare function inheritsBuiltinStreamCtor(L: Lowerer, info: ClassInfo): boolean;
+/** `new C(args)` for a class declared in the program (imports resolve
+   * through aliases, so cross-module classes construct too). */
+/** The single message argument of a builtin Error construction or
+ * super() call: "" when omitted or explicitly undefined (Node's message
+ * property default), the string otherwise. The lib signature's second
+ * parameter (options/cause) has no lowering. */
+export declare function errorMessageArg(L: Lowerer, args: readonly ts.Expression[], loc: SrcLoc, blame: ts.Node): IrExpr;
+/** A class whose decoration provably throws has no reachable VALUE form:
+ * the binding never initializes (the %init ReferenceError unwinds first),
+ * so `new`, the class as a value, and `extends` all fence — reaching one
+ * in compiled code would require executing past the throw. */
+export declare function fenceDecorationThrows(L: Lowerer, info: ClassInfo, blame: ts.Node): void;
+export declare function lowerNew(L: Lowerer, expr: ts.NewExpression): IrExpr;
+/** A getter/setter invocation over an accessor target's receiver — the
+   * same whole-program devirtualization as method calls: a virtualCall
+   * when some strict subclass of the receiver's static class overrides
+   * this HALF of the accessor (get and set devirtualize independently),
+   * a direct call of the nearest declaration otherwise. */
+export declare function accessorCall(L: Lowerer, className: string, member: string, obj: IrExpr, extraArgs: IrExpr[], ret: IrType, loc: SrcLoc): IrExpr;