@loopdive/js2 0.57.0

package/dist/ir/builder.d.ts

@@ -0,0 +1,401 @@
+import { IrBinop, IrBlockId, IrClassShape, IrClosureSignature, IrConst, IrFuncRef, IrFunction, IrGlobalRef, IrInstr, IrObjectShape, IrTerminator, IrType, IrUnop, IrValueId } from './nodes.js';
+import { AllocSiteRegistry } from './alloc-registry.js';
+import { Instr, ValType } from './types.js';
+export declare class IrFunctionBuilder {
+    private readonly name;
+    private readonly resultTypes;
+    private readonly exported;
+    private readonly allocRegistry?;
+    private readonly allocator;
+    private readonly params;
+    private readonly finished;
+    private readonly valueTypes;
+    private current;
+    private nextBlockId;
+    private readonly reserved;
+    private readonly slotDefs;
+    private bodyBuffer;
+    private funcKind;
+    private generatorBufferSlot;
+    constructor(name: string, resultTypes: readonly IrType[], exported?: boolean, allocRegistry?: AllocSiteRegistry | undefined);
+    /**
+     * #1586: mint a stable allocation-site id for a value-creating instr. Returns
+     * `undefined` when no registry is wired (test builders), in which case the
+     * instr's `alloc` field stays absent — lowering ignores it either way.
+     */
+    private allocId;
+    addParam(name: string, type: IrType): IrValueId;
+    openBlock(blockArgTypes?: readonly IrType[]): IrBlockId;
+    /**
+     * Allocate a block ID without opening it — for forward references in a
+     * terminator that must branch to a block we haven't emitted yet. The caller
+     * MUST later activate it with `openReservedBlock(id)` before `finish()`.
+     */
+    reserveBlockId(): IrBlockId;
+    /**
+     * Activate a previously reserved block ID as the current open block.
+     */
+    openReservedBlock(id: IrBlockId, blockArgTypes?: readonly IrType[]): void;
+    private makeOpen;
+    blockArg(slot: number): IrValueId;
+    terminate(terminator: IrTerminator): void;
+    emitConst(value: IrConst, resultType: IrType): IrValueId;
+    emitCall(target: IrFuncRef, args: readonly IrValueId[], resultType: IrType | null): IrValueId | null;
+    emitGlobalGet(target: IrGlobalRef, resultType: IrType): IrValueId;
+    emitGlobalSet(target: IrGlobalRef, value: IrValueId): void;
+    emitBinary(op: IrBinop, lhs: IrValueId, rhs: IrValueId, resultType: IrType): IrValueId;
+    emitUnary(op: IrUnop, rand: IrValueId, resultType: IrType): IrValueId;
+    emitSelect(condition: IrValueId, whenTrue: IrValueId, whenFalse: IrValueId, resultType: IrType): IrValueId;
+    /**
+     * (#1392) Emit `unary("ref.is_null", val)` — tests a Wasm reference for
+     * null. Result is `i32` (1 if null, 0 otherwise). The architect-spec
+     * name `emitRefIsNull` mirrors the existing `emitUnary` /
+     * `emitBinary` / `emitSelect` family and surfaces the underlying op
+     * at the call site so #1375's optional-chain lowering reads naturally
+     * (`cx.builder.emitRefIsNull(recv)`).
+     *
+     * `val`'s IrType MUST be a `val`-kind wrapping a Wasm reference type
+     * (`ref` / `ref_null` / `externref` / `funcref`); the verifier and the
+     * Wasm validator together reject other operand shapes.
+     */
+    emitRefIsNull(val: IrValueId): IrValueId;
+    /**
+     * (#1392) Emit a value-producing short-circuiting if/else. Both `then`
+     * and `else` are pre-collected instruction buffers (typically built
+     * via `collectBodyInstrs(...)`); the lowerer emits a Wasm
+     * `if (result T) ... else ... end` so only the matching branch
+     * executes.
+     *
+     * `thenValue` / `elseValue` are SSA value IDs DEFINED INSIDE the
+     * corresponding arm — the lowerer emits each arm's instruction tree
+     * and leaves the carrier value on the Wasm stack at end-of-arm; the
+     * post-block `local.set` binds the if-instr's result to whichever
+     * carrier ran.
+     */
+    emitIfElse(args: {
+        cond: IrValueId;
+        then: readonly IrInstr[];
+        thenValue: IrValueId;
+        else: readonly IrInstr[];
+        elseValue: IrValueId;
+        resultType: IrType;
+    }): IrValueId;
+    emitStringConst(value: string): IrValueId;
+    emitStringConcat(lhs: IrValueId, rhs: IrValueId): IrValueId;
+    emitStringEq(lhs: IrValueId, rhs: IrValueId, negate: boolean): IrValueId;
+    emitStringLen(value: IrValueId): IrValueId;
+    /**
+     * Emit `object.new` to materialize an object literal. The caller is
+     * responsible for canonicalizing `shape.fields` (sorted ascending by
+     * name) and for ensuring `values[i]` matches `shape.fields[i].type`.
+     * The arity check is enforced here so a stray slice-2 selector miss
+     * surfaces immediately instead of as a malformed Wasm struct.new.
+     */
+    emitObjectNew(shape: IrObjectShape, values: readonly IrValueId[]): IrValueId;
+    /**
+     * Emit `object.get` to read a named field. Caller passes the field's
+     * declared IrType so the SSA def's static type matches the shape's
+     * field type without a second lookup at lowering time.
+     */
+    emitObjectGet(value: IrValueId, name: string, resultType: IrType): IrValueId;
+    /**
+     * Emit `object.set` to write a named field. Void result.
+     */
+    emitObjectSet(value: IrValueId, name: string, newValue: IrValueId): void;
+    /**
+     * Materialize a closure value. Caller is responsible for ensuring
+     * `captureFieldTypes[i]` matches the IR type of the SSA value at
+     * `captures[i]`. The arity check below catches mistakes early.
+     */
+    emitClosureNew(liftedFunc: IrFuncRef, signature: IrClosureSignature, captureFieldTypes: readonly IrType[], captures: readonly IrValueId[]): IrValueId;
+    /**
+     * Read a capture field from the implicit `__self` closure struct.
+     * Caller passes the field's IrType so the SSA def's static type is
+     * stable without a second resolver lookup at lowering time.
+     */
+    emitClosureCap(self: IrValueId, index: number, resultType: IrType): IrValueId;
+    /**
+     * Invoke a closure value. Caller passes `resultType` (= signature.returnType)
+     * for the SSA def.
+     */
+    emitClosureCall(callee: IrValueId, args: readonly IrValueId[], resultType: IrType): IrValueId;
+    /**
+     * Wrap a primitive value in a fresh ref cell. The SSA def's type is
+     * `{ kind: "boxed", inner }`. #1926 — the `boxed` IrType carries an IrType
+     * `inner`, so the ValType arg is wrapped with `irVal` here; the resolver
+     * unwraps it back to the ValType at lowering time.
+     */
+    emitRefCellNew(value: IrValueId, inner: ValType): IrValueId;
+    /**
+     * Read the inner value out of a ref cell. The SSA def's type is the cell's
+     * `inner` IrType. #1926 — `inner` is now the `boxed` IrType's `inner`
+     * field (an IrType), passed straight through as the result type. Callers
+     * pass the same `inner` they used for the matching `boxed` cell (for V1
+     * primitive cells this is `irVal(scalar)`, so the result type is
+     * `{ kind: "val", val: scalar }` exactly as before).
+     */
+    emitRefCellGet(cell: IrValueId, inner: IrType): IrValueId;
+    /**
+     * Write a new value through the ref cell. Void result.
+     */
+    emitRefCellSet(cell: IrValueId, value: IrValueId): void;
+    /**
+     * Phase 1 escape hatch — emit raw backend ops with a stated stack delta.
+     * Verifier requires stackDelta to match the effective push count.
+     */
+    emitRawWasm(ops: readonly Instr[], stackDelta: number): void;
+    /**
+     * Emit `class.new` to construct a class instance via the legacy-registered
+     * `<className>_new` constructor. Caller is responsible for ensuring
+     * `args[i]` matches `shape.constructorParams[i]`. The arity check below
+     * catches mistakes early.
+     */
+    emitClassNew(shape: IrClassShape, args: readonly IrValueId[]): IrValueId;
+    /**
+     * Emit `class.get` to read a named field on a class instance. Caller
+     * passes the field's IrType (looked up against the receiver's shape) so
+     * the SSA def's static type matches without a second resolver lookup.
+     */
+    emitClassGet(value: IrValueId, fieldName: string, resultType: IrType): IrValueId;
+    /**
+     * Emit `class.set` to write a named field on a class instance. Void
+     * result. The receiver's shape must contain `fieldName`; arity / type
+     * checks happen at the AST→IR layer.
+     */
+    emitClassSet(value: IrValueId, fieldName: string, newValue: IrValueId): void;
+    /**
+     * Emit `class.call` to invoke an instance method. `resultType` is the
+     * method descriptor's `returnType` (or `null` for void). Returns `null`
+     * for void methods — callers using the result in expression position
+     * must reject `null` themselves.
+     */
+    emitClassCall(receiver: IrValueId, methodName: string, args: readonly IrValueId[], resultType: IrType | null): IrValueId | null;
+    /**
+     * Slice 10 (#1169i) — emit `extern.new` for `new ExternClass(args)`.
+     * Result type is `{ kind: "extern", className }` — opaque externref
+     * carrying the class identity statically.
+     */
+    emitExternNew(className: string, args: readonly IrValueId[]): IrValueId;
+    /**
+     * Slice 10 (#1169i) — emit `extern.call` for `<recv>.<method>(args)` on
+     * an extern-class receiver. `resultType` is the method's registered
+     * result IrType (or `null` for void). Returns `null` for void methods.
+     */
+    emitExternCall(className: string, method: string, receiver: IrValueId, args: readonly IrValueId[], resultType: IrType | null): IrValueId | null;
+    /**
+     * Slice 10 (#1169i) — emit `extern.prop` for a property read on an
+     * extern-class receiver.
+     */
+    emitExternProp(className: string, property: string, receiver: IrValueId, resultType: IrType): IrValueId;
+    /**
+     * Slice 10 (#1169i) — emit `extern.propSet` for a property write on an
+     * extern-class receiver. Void result.
+     */
+    emitExternPropSet(className: string, property: string, receiver: IrValueId, value: IrValueId): void;
+    /**
+     * Slice 10 (#1169i) — emit `extern.regex` for a `/pattern/flags`
+     * RegExp literal. Result is `{ kind: "extern", className: "RegExp" }`
+     * (opaque externref handle to the RegExp instance).
+     */
+    emitRegExpLiteral(pattern: string, flags: string): IrValueId;
+    typeOf(value: IrValueId): IrType;
+    finish(closureSubtype?: {
+        readonly signature: IrClosureSignature;
+        readonly captureFieldTypes: readonly IrType[];
+    }): IrFunction;
+    /**
+     * Slice 7a (#1169f): set the function kind. Must be called before any
+     * `gen.push` / `gen.epilogue` is emitted. Idempotent — subsequent calls
+     * with the same value are no-ops; calls with a different value throw.
+     */
+    setFuncKind(kind: "regular" | "generator" | "async"): void;
+    /**
+     * Slice 7a (#1169f): record the slot index of the `__gen_buffer`
+     * Wasm-local. Called from the generator-prologue emitter in from-ast
+     * after `declareSlot("__gen_buffer", { kind: "externref" })` allocates
+     * the slot. The lowerer reads this when expanding `gen.push` /
+     * `gen.epilogue`.
+     */
+    setGeneratorBufferSlot(slotIndex: number): void;
+    /** Emit a `gen.push` instr — push a yielded value onto the buffer. */
+    emitGenPush(value: IrValueId): void;
+    /**
+     * Emit a `gen.epilogue` instr — produce the Generator-like object via
+     * `__create_generator(buffer, pendingThrow)`. Returns the SSA value of
+     * the resulting externref (the Generator object), suitable for use in a
+     * `return [result]` terminator.
+     */
+    emitGenEpilogue(): IrValueId;
+    /**
+     * Slice 7b (#1169f): emit a `gen.yieldStar` instr — drain the inner
+     * iterable into the outer generator's buffer via
+     * `__gen_yield_star(buf, inner)`. The caller MUST coerce `inner` to
+     * externref upstream (e.g. via `emitCoerceToExternref`) — the host
+     * import expects an externref in arg position 1.
+     */
+    emitGenYieldStar(inner: IrValueId): void;
+    private requireBlock;
+    /**
+     * Slice 6 (#1169e): single push site for IR instrs. Routes to either the
+     * current open block's instr list or — if a body buffer is active — into
+     * that buffer instead. The for-of-body builder uses this redirection so
+     * its lowered statements end up in `IrInstrForOfVec.body` rather than in
+     * the surrounding block's instr list.
+     */
+    private pushInstr;
+    /**
+     * Allocate a Wasm-local slot for cross-iteration mutable state. Returns
+     * the slot's stable index, usable with `slot.read` / `slot.write`.
+     * `type` must be a primitive ValType (no struct refs in slice 6).
+     */
+    declareSlot(name: string, type: ValType): number;
+    /** Read a slot by its index. Returns the SSA value of the load. */
+    emitSlotRead(slotIndex: number): IrValueId;
+    /**
+     * Slice 6 part 4 refactor (#1185): read a slot but tag the SSA def
+     * with a caller-supplied IrType instead of `irVal(slot.type)`.
+     * The Wasm-level value produced is identical — `slot.read` lowers
+     * to a single `local.get` either way — so this is purely a
+     * type-system rewrite. The caller is responsible for ensuring
+     * `asType` is interconvertible with `irVal(slot.type)` at the
+     * Wasm level (e.g. `IrType.string` and `(ref $AnyString)` are
+     * interconvertible in native-strings mode).
+     *
+     * Used by the slot-binding `asType` widening in `lowerExpr`'s
+     * identifier handler — see the `slot` arm of `ScopeBinding`.
+     */
+    emitSlotReadAs(slotIndex: number, asType: IrType): IrValueId;
+    /** Write a value to a slot by its index. */
+    emitSlotWrite(slotIndex: number, value: IrValueId): void;
+    /** Read `vec.length` (returned as f64 to match JS Number semantics). */
+    emitVecLen(vec: IrValueId): IrValueId;
+    /**
+     * Index into a vec's data array. `indexI32` MUST be an i32-typed SSA value
+     * (not f64). `elemType` is the element's IrType, and the result carries it.
+     */
+    emitVecGet(vec: IrValueId, indexI32: IrValueId, elemType: IrType): IrValueId;
+    /**
+     * #1804 — construct a fixed-length vec from element SSA values. `elementType`
+     * is the shared element IrType; `vecRefType` is the vec ref IrType the
+     * caller obtained from the resolver (`resolveVecForElement`) and becomes the
+     * result's type so downstream `vec.get`/`.length`/`for-of` reads resolve.
+     */
+    emitVecNewFixed(elements: readonly IrValueId[], elementType: IrType, vecRefType: IrType): IrValueId;
+    /**
+     * Run a callback that emits the loop body's IR instrs into a side buffer.
+     * The callback typically calls `lowerStmt` on each TS body statement;
+     * those calls go through `lowerExpr` etc. and produce IR via the normal
+     * builder methods, which route into the side buffer instead of the
+     * current block.
+     *
+     * Returns the captured body instrs.
+     */
+    collectBodyInstrs(emit: () => void): IrInstr[];
+    emitForOfVec(args: {
+        vec: IrValueId;
+        elementType: IrType;
+        counterSlot: number;
+        lengthSlot: number;
+        vecSlot: number;
+        dataSlot: number;
+        elementSlot: number;
+        body: readonly IrInstr[];
+    }): void;
+    /**
+     * Coerce a reference-typed IR value to externref. Caller is responsible
+     * for ensuring `value` has a reference IrType — numeric ValTypes
+     * (i32/f64) cannot be coerced and produce an invalid Wasm body.
+     */
+    emitCoerceToExternref(value: IrValueId): IrValueId;
+    /**
+     * Construct a host iterator handle from an externref iterable.
+     * `async: false` calls `__iterator`; `async: true` calls
+     * `__async_iterator` (reserved for #1169f, slice 7).
+     */
+    emitIterNew(iterable: IrValueId, async: boolean): IrValueId;
+    /**
+     * Advance the iterator (`iter.next()`). Result is the iterator-result
+     * object as externref. Side-effecting — DCE must not eliminate.
+     */
+    emitIterNext(iter: IrValueId): IrValueId;
+    /** Read `.done` off an iterator-result object. Returns i32 (bool). */
+    emitIterDone(resultObj: IrValueId): IrValueId;
+    /** Read `.value` off an iterator-result object. Returns externref. */
+    emitIterValue(resultObj: IrValueId): IrValueId;
+    /** Call `iter.return()`. Void result. */
+    emitIterReturn(iter: IrValueId): void;
+    emitForOfIter(args: {
+        iterable: IrValueId;
+        iterSlot: number;
+        resultSlot: number;
+        elementSlot: number;
+        body: readonly IrInstr[];
+    }): void;
+    /**
+     * Emit a `forof.string` declarative instr — the native-strings counter
+     * loop over a string. Caller pre-allocates all four slots and passes
+     * the body buffer collected via `collectBodyInstrs`. The lowerer is
+     * responsible for emitting the `__str_charAt` calls + counter
+     * arithmetic; this builder method just records the structured node.
+     */
+    emitForOfString(args: {
+        str: IrValueId;
+        counterSlot: number;
+        lengthSlot: number;
+        strSlot: number;
+        elementSlot: number;
+        body: readonly IrInstr[];
+    }): void;
+    /**
+     * Slice 9 (#1169h): emit a `throw` instruction. The `value` MUST be an
+     * SSA value of `(externref)` ValType — callers coerce upstream via
+     * `emitCoerceToExternref` for ref / object / class / closure values,
+     * and via the legacy box helper for f64 / i32 (boxed by the host).
+     *
+     * The instruction produces no SSA value; control doesn't fall through.
+     * The current block must still be terminated by the caller (typically
+     * with `unreachable` for top-level throws, or implicitly by the surrounding
+     * try-body buffer mechanism).
+     */
+    emitThrow(value: IrValueId): void;
+    /**
+     * Slice 9 (#1169h): emit a `try` instruction with a body, optional catch
+     * handler, and optional finally body. Mirrors the for-of declarative
+     * shape — the caller pre-collects each buffer via `collectBodyInstrs`.
+     * Result is void.
+     */
+    emitTry(args: {
+        body: readonly IrInstr[];
+        catchClause?: {
+            payloadSlot: number;
+            body: readonly IrInstr[];
+        };
+        finallyBody?: readonly IrInstr[];
+    }): void;
+    /**
+     * Slice 12 (#1280): emit a `while (cond) body` declarative loop. The
+     * caller pre-collects the cond + body buffers via `collectBodyInstrs`
+     * and threads through the SSA value emitted by the cond's last
+     * instruction. The lowerer emits the canonical
+     * `block { loop { <cond>; i32.eqz; br_if 1; <body>; br 0 } }`
+     * Wasm pattern.
+     */
+    emitWhileLoop(args: {
+        cond: readonly IrInstr[];
+        condValue: IrValueId;
+        body: readonly IrInstr[];
+    }): void;
+    /**
+     * Slice 12 (#1280): emit a `for (init; cond; update) body` declarative
+     * loop. `init` is emitted as separate IR instructions BEFORE this
+     * instr (a `let i = 0` is just a `lowerVarDecl`, no special encoding
+     * needed). The instr carries cond, body, update.
+     */
+    emitForLoop(args: {
+        cond: readonly IrInstr[];
+        condValue: IrValueId;
+        body: readonly IrInstr[];
+        update: readonly IrInstr[];
+    }): void;
+}
+export declare function v(n: number): IrValueId;

package/dist/ir/from-ast.d.ts

@@ -0,0 +1,192 @@
+import { ts } from '../ts-api.js';
+import { AllocSiteRegistry } from './alloc-registry.js';
+import { IrVecLowering } from './lower.js';
+import { closureSignatureEquals, IrClassShape, IrFunction, IrType, IrUnop } from './nodes.js';
+import { ValType } from './types.js';
+/**
+ * Slice 10 (#1169i) — the from-ast view of one extern-class entry. Mirrors
+ * `ExternClassInfo` from `src/codegen/context/types.ts` but limits the
+ * surface to what the from-ast layer needs to validate `new ExternClass(...)`,
+ * `recv.method(...)`, and property access on extern-class receivers.
+ *
+ * Methods carry the LEGACY-registered signature shape: `params[0]` is the
+ * receiver `externref` and `params[1..]` are the user args. The from-ast
+ * lowerer slices off the receiver when matching call args against
+ * `params.slice(1)`. Slicing here keeps the from-ast logic dispatch-free.
+ */
+export interface IrExternClassMeta {
+    readonly className: string;
+    readonly constructorParams: readonly ValType[];
+    readonly methods: ReadonlyMap<string, {
+        readonly params: readonly ValType[];
+        readonly results: readonly ValType[];
+    }>;
+    readonly properties: ReadonlyMap<string, {
+        readonly type: ValType;
+        readonly readonly: boolean;
+    }>;
+}
+/**
+ * Slice 6 part 4 refactor (#1185): a narrowed view of `IrLowerResolver`
+ * restricted to the methods the AST→IR build phase actually consults.
+ * Threading this subset through `LowerCtx` retires per-feature shortcuts
+ * (`nativeStrings: boolean`, `anyStrTypeIdx: number`,
+ * `inferVecElementValTypeFromContext`, etc.) without forcing the full
+ * resolver — including its lazy struct registries that don't exist
+ * yet at Phase-1 build time — into the from-ast layer.
+ *
+ * Phase-1 callable methods only:
+ *   - `nativeStrings()` — backend mode discriminator
+ *   - `resolveString()` — `IrType.string` ValType (extern vs native struct ref)
+ *   - `resolveVec(valType)` — vec struct shape recovery
+ *
+ * Slice 10 (#1169i) adds:
+ *   - `getExternClassInfo(name)` — extern-class metadata for slice-10
+ *     lowering of `new ExternClass(...)`, `recv.method(...)`, and
+ *     property access on extern-class receivers. Returns undefined if
+ *     `name` isn't a registered extern class.
+ *
+ * The full `IrLowerResolver` (in `src/ir/lower.ts`) extends this and
+ * adds Phase-3 methods like `resolveObject`, `resolveClass`,
+ * `resolveClosure`. Those depend on registries that aren't populated
+ * until Phase 3, so from-ast doesn't see them.
+ */
+export interface IrFromAstResolver {
+    nativeStrings?(): boolean;
+    resolveString?(): ValType;
+    resolveVec?(valType: ValType): IrVecLowering | null;
+    /**
+     * #1804 — register-or-recover the vec struct for an element ValType so
+     * `lowerArrayLiteral` can type a constructed `vec.new_fixed`'s result SSA
+     * value as `{ kind: "ref", typeIdx: vecStructTypeIdx }`.
+     */
+    resolveVecForElement?(elementValType: ValType): IrVecLowering | null;
+    /**
+     * Slice 10 (#1169i) — return metadata for the named extern class, or
+     * `undefined` if no such class is registered.
+     */
+    getExternClassInfo?(className: string): IrExternClassMeta | undefined;
+    /**
+     * #1375 narrow slice — TS-narrowing fast-path for optional chaining.
+     * Returns `true` when the TypeScript type of `expr` is provably non-null
+     * (i.e. `getNonNullableType(t) === t`). Used by `lowerPropertyAccess`
+     * to skip the `?.`-on-nullable-receiver throw when TS has already
+     * narrowed away null/undefined — the IR's `isIrTypeNullable` is more
+     * conservative (treats `extern` as always nullable), so this gate
+     * recovers a small set of well-typed `m?.x` cases where `m: Map<...>`
+     * (no `| undefined`) is genuinely non-null at TS level.
+     *
+     * When unimplemented or returns `undefined`, `lowerPropertyAccess`
+     * keeps the existing throw → legacy fallback.
+     */
+    isExpressionTsNonNullable?(expr: ts.Expression): boolean | undefined;
+}
+export interface AstToIrOptions {
+    readonly exported?: boolean;
+    /**
+     * #1370 Phase B: explicit name for the lowered function. Required for
+     * MethodDeclaration (where `.name` is `PropertyName`, not Identifier)
+     * and ConstructorDeclaration (which has no name node at all). For
+     * top-level FunctionDeclaration this can be omitted; the caller's
+     * `fn.name.text` is used as a fallback.
+     */
+    readonly funcName?: string;
+    /**
+     * #1370 Phase B: when set, the lowered function gets an implicit
+     * `__self` parameter as its FIRST parameter, and `this` is bound in
+     * the body's scope to that parameter's SSA value. Pass when lowering
+     * an instance method — the legacy `class-bodies.ts` pre-allocates
+     * instance method signatures as `[(ref $structTypeIdx), ...userParams]`
+     * (see `class-bodies.ts:301`); the IR-lowered body must mirror that
+     * layout exactly so existing legacy callers' `call $methodFuncIdx`
+     * ops route to the correct typeIdx.
+     *
+     * The `IrType` should be `{ kind: "class"; shape }` so `this.field`
+     * accesses resolve via `class.get` / `class.set` against the shape's
+     * field list.
+     *
+     * Static methods don't get a `selfParam`; constructors don't either —
+     * Phase C synthesises `struct.new + __self` inside the body.
+     */
+    readonly selfParam?: {
+        readonly type: IrType;
+    };
+    /**
+     * If present, overrides the IR types for the function's own parameters.
+     * Indexed by parameter position. Used when the AST lacks explicit TS
+     * type annotations and the Phase-2 propagation pass has inferred types.
+     */
+    readonly paramTypeOverrides?: readonly IrType[];
+    /**
+     * If present, overrides the IR return type. Same rationale as
+     * `paramTypeOverrides`.
+     *
+     * Slice 14 (#1228) — null = void return (zero Wasm result types). The
+     * IrFunctionBuilder is constructed with `[]` results and the lowerer
+     * accepts bare `return;` and fall-through tails.
+     */
+    readonly returnTypeOverride?: IrType | null;
+    /**
+     * Map from callee function name to that callee's IR types (param +
+     * return). Consulted when lowering a CallExpression whose callee is a
+     * local function. Missing entries cause the lowerer to throw — the
+     * selector's call-graph closure should guarantee every call we reach
+     * has an entry.
+     *
+     * Slice 14 (#1228) — `returnType: IrType | null`. Null means a void
+     * callee — calls in expression position (`x = f();`) are spec-illegal
+     * for void; calls in statement position (`f();`) are fine.
+     */
+    readonly calleeTypes?: ReadonlyMap<string, {
+        params: readonly IrType[];
+        returnType: IrType | null;
+    }>;
+    /**
+     * Slice 4 (#1169d): map from class name to that class's IR shape
+     * (fields + methods + constructor signature). Consulted when lowering
+     * NewExpression / class-receiver PropertyAccess / class-receiver
+     * method calls. Missing entries cause the relevant lowering case to
+     * throw, falling back to legacy.
+     */
+    readonly classShapes?: ReadonlyMap<string, IrClassShape>;
+    /**
+     * Slice 6 part 4 refactor (#1185): the from-ast view of the IR
+     * lowerer's resolver. Replaces the per-feature shortcuts that
+     * #1181 / #1182 / #1183 each added (`nativeStrings`,
+     * `anyStrTypeIdx`, `inferVecElementValTypeFromContext`).
+     *
+     * Optional so existing tests / callers that don't need string or
+     * vec type resolution can keep working. The `lowerForOfStatement`
+     * arms that DO need it (string + vec) throw a clean fall-back-to-
+     * legacy error when the resolver is absent or returns `null`.
+     *
+     * The integration layer (`compileIrPathFunctions`) is the canonical
+     * supplier — it builds the resolver (or its subset) eagerly and
+     * passes it in.
+     */
+    readonly resolver?: IrFromAstResolver;
+    /** Optional-chain nullability check (#1281). When absent, `?.` / `?.()` throw to legacy. */
+    readonly checker?: ts.TypeChecker;
+    /**
+     * #1586: module-global allocation-site registry. When supplied, the builder
+     * mints a stable `AllocSiteId` for every value-creating instr (object.new,
+     * closure.new, string.const, …). Optional — when absent, `alloc` fields stay
+     * unset, which is inert at lowering (byte-identical output).
+     */
+    readonly allocRegistry?: AllocSiteRegistry;
+}
+/**
+ * Slice 3 (#1169c): lowering an outer function may produce additional
+ * lifted IR functions (one per nested function declaration / closure
+ * expression). The integration layer treats these as synthesized
+ * BuiltFns that get fresh funcIdx slots.
+ */
+export interface LoweredFunctionResult {
+    readonly main: IrFunction;
+    readonly lifted: readonly IrFunction[];
+}
+export declare function lowerFunctionAstToIr(fn: ts.FunctionDeclaration | ts.MethodDeclaration | ts.ConstructorDeclaration, options?: AstToIrOptions): LoweredFunctionResult;
+/** Result-type hints aren't used in Phase 1 (we always know from the op). */
+export type _Unused = IrUnop;
+export declare const _CLOSURE_SIG_EQ_REF: typeof closureSignatureEquals;
+export type _UnusedVal = ValType;

package/dist/ir/index.d.ts

@@ -0,0 +1,16 @@
+export * from './types.js';
+export * from './nodes.js';
+export * from './alloc-registry.js';
+export * from './builder.js';
+export * from './verify.js';
+export * from './verify-alloc.js';
+export * from './lower.js';
+export * from './backend/legality.js';
+export * from './select.js';
+export * from './from-ast.js';
+export * from './integration.js';
+export * from './analysis/encoding.js';
+export * from './analysis/lattice.js';
+export * from './analysis/ownership.js';
+export * from './analysis/stack-alloc.js';
+export * from './analysis/escape.js';

package/dist/ir/integration.d.ts

@@ -0,0 +1,27 @@
+import { ts } from '../ts-api.js';
+import { CodegenContext } from '../codegen/context/types.js';
+import { IrClassShape, IrType } from './nodes.js';
+import { IrSelection } from './select.js';
+export interface IrIntegrationReport {
+    readonly compiled: readonly string[];
+    readonly errors: readonly IrIntegrationError[];
+}
+export interface IrIntegrationError {
+    readonly func: string;
+    readonly message: string;
+    readonly kind?: "verify" | "build" | "lower" | "backend-legality";
+}
+/**
+ * Per-function IR type overrides sourced from the Phase-2 propagation
+ * pass. Indexed by function name. When present for a selected function,
+ * these types are used in place of (or alongside) any explicit TS
+ * annotations. They are also used to derive the `calleeTypes` map that
+ * the AST→IR lowerer consults when lowering `CallExpression`.
+ */
+export interface IrTypeOverrideMap {
+    get(name: string): {
+        readonly params: readonly IrType[];
+        readonly returnType: IrType | null;
+    } | undefined;
+}
+export declare function compileIrPathFunctions(ctx: CodegenContext, sourceFile: ts.SourceFile, selection?: IrSelection, overrides?: IrTypeOverrideMap, classShapes?: ReadonlyMap<string, IrClassShape>): IrIntegrationReport;