@loopdive/js2 0.57.0

package/dist/ir/nodes.d.ts

@@ -0,0 +1,1452 @@
+import { ValType } from './types.js';
+export interface IrFuncRef {
+    readonly kind: "func";
+    /** Unique function name (same namespace as `ctx.funcMap`). */
+    readonly name: string;
+}
+export interface IrGlobalRef {
+    readonly kind: "global";
+    /** Unique global name (same namespace as `ctx.globalMap` or similar). */
+    readonly name: string;
+}
+export interface IrTypeRef {
+    readonly kind: "type";
+    /** Unique WasmGC type name (same namespace as `ctx.typeNames`). */
+    readonly name: string;
+}
+export type IrSymRef = IrFuncRef | IrGlobalRef | IrTypeRef;
+/**
+ * A canonical object shape — a sorted list of named fields with their IR
+ * types. Equal shapes (same names, same types in the same canonical order)
+ * resolve to the same WasmGC struct via the lowerer's resolver. Carrying
+ * the field types as `IrType` (not `ValType`) lets a struct-of-string or
+ * struct-of-object compose cleanly: the resolver recursively materializes
+ * field types when registering the WasmGC struct.
+ *
+ * Names must be unique. The constructor in `from-ast.ts` sorts by name
+ * before constructing the IrType so structurally-identical shapes compare
+ * equal regardless of source order.
+ */
+export interface IrObjectShape {
+    readonly fields: readonly {
+        readonly name: string;
+        readonly type: IrType;
+    }[];
+}
+/**
+ * Slice 3 (#1169c) — a closure's caller-visible signature. Used both as
+ * the IR-level type discriminator for closure values and as the resolver
+ * lookup key for the supertype struct + lifted func type. The implicit
+ * `__self` struct param at index 0 of the lifted body is NOT present in
+ * `params` — it's added by the resolver when synthesizing the func type.
+ */
+export interface IrClosureSignature {
+    readonly params: readonly IrType[];
+    readonly returnType: IrType;
+}
+/**
+ * Slice 4 (#1169d) — descriptor for one field on a class.
+ */
+export interface IrClassFieldDescriptor {
+    readonly name: string;
+    readonly type: IrType;
+}
+/**
+ * Slice 4 (#1169d) — descriptor for one instance method on a class. The
+ * implicit `this` receiver is NOT listed in `params` — the lowerer
+ * prepends it when emitting the call. A void method has
+ * `returnType: null`.
+ */
+export interface IrClassMethodDescriptor {
+    readonly name: string;
+    readonly params: readonly IrType[];
+    readonly returnType: IrType | null;
+}
+/**
+ * Slice 4 (#1169d) — symbolic descriptor for a class declared in the
+ * compilation unit. Carries the structural info the IR builder needs to
+ * type-check `new`/field-access/method-call expressions on instances of
+ * this class without consulting the lowering resolver.
+ *
+ *   - `className`        unique discriminator (one class per name per unit)
+ *   - `fields`           user fields in canonical order (alphabetical)
+ *                        — the lowerer maps each field `name` to a Wasm
+ *                        struct field index via `resolveClass`, which knows
+ *                        about the legacy `__tag` prefix at field 0.
+ *   - `methods`          instance methods with caller-visible signatures.
+ *                        Static methods are out of slice 4 scope and are
+ *                        not listed.
+ *   - `constructorParams` user-visible param list for `new C(...)`.
+ *
+ * Class methods themselves are NOT IR-claimable in slice 4 — they remain
+ * on the legacy class-bodies path. The IR only references them by name
+ * (`<className>_<methodName>`) at call-site lowering, where the resolver
+ * maps the name to the legacy-allocated funcIdx.
+ */
+export interface IrClassShape {
+    readonly className: string;
+    readonly fields: readonly IrClassFieldDescriptor[];
+    readonly methods: readonly IrClassMethodDescriptor[];
+    readonly constructorParams: readonly IrType[];
+}
+export type IrType = {
+    readonly kind: "val";
+    readonly val: ValType;
+    readonly signed?: boolean;
+} | {
+    readonly kind: "string";
+} | {
+    readonly kind: "object";
+    readonly shape: IrObjectShape;
+} | {
+    readonly kind: "closure";
+    readonly signature: IrClosureSignature;
+} | {
+    readonly kind: "class";
+    readonly shape: IrClassShape;
+} | {
+    readonly kind: "extern";
+    readonly className: string;
+} | {
+    readonly kind: "union";
+    readonly members: readonly IrType[];
+} | {
+    readonly kind: "boxed";
+    readonly inner: IrType;
+};
+/** Wrap a plain ValType as an IrType — the common path for Phase 1/2 callers. */
+export declare function irVal(v: ValType): IrType;
+/**
+ * Wrap a ValType as an IrType with an explicit signedness fact (#1126 Stage 1).
+ * Use this only for `i32` ValTypes where the value-domain (signed `int32` vs
+ * unsigned `uint32`) is known. For non-i32 ValTypes the `signed` flag is
+ * meaningless; callers should use `irVal()` instead.
+ *
+ * The flag is read by Stage 3 emit decisions (signed vs unsigned shifts,
+ * comparisons, conversions back to f64). For Stage 1 it is purely additive —
+ * no existing emitter consults it yet.
+ */
+export declare function irValSigned(v: ValType, signed: boolean): IrType;
+/**
+ * Return the single underlying ValType for a `val`-kind IrType, else `null`.
+ * Call sites that previously did `t.kind === "f64"` against an `IrType` now
+ * do `asVal(t)?.kind === "f64"`.
+ */
+export declare function asVal(t: IrType): ValType | null;
+/**
+ * Structural equality for IrType. Two types are equal iff they have the same
+ * shape and their underlying ValType members compare structurally equal.
+ *
+ * Used by the verifier and by migration assertions. We keep the implementation
+ * local to avoid pulling a full deep-equal dep into the IR layer.
+ */
+export declare function irTypeEquals(a: IrType, b: IrType): boolean;
+/**
+ * Slice 4 (#1169d): structural equality for class shapes. `className` is
+ * the discriminator — every class is unique within a compilation unit, so
+ * two `IrClassShape` values with the same `className` represent the same
+ * class. We don't recurse into `fields` / `methods` / `constructorParams`
+ * because they're a deterministic projection of `className` (one
+ * declaration per class per unit). Cross-unit class types are out of
+ * slice 4 scope.
+ */
+export declare function classShapeEquals(a: IrClassShape, b: IrClassShape): boolean;
+/**
+ * Structural equality for closure signatures. Recurses through param /
+ * return IrTypes via `irTypeEquals` so a closure-of-closure or a
+ * closure-of-object compares correctly.
+ */
+export declare function closureSignatureEquals(a: IrClosureSignature, b: IrClosureSignature): boolean;
+/**
+ * Structural equality for object shapes. Field lists must be parallel
+ * (same length, same order, same name and IrType per slot). Recursing
+ * via `irTypeEquals` lets nested object fields compare correctly.
+ */
+export declare function objectShapeEquals(a: IrObjectShape, b: IrObjectShape): boolean;
+/**
+ * An SSA value ID — uniquely identifies one defining instruction or block arg
+ * within one IrFunction. Values are NOT shared across functions.
+ *
+ * Represented as a branded number for cheap comparison + map-key use. `-1`
+ * is reserved as an intentionally invalid sentinel and must never appear in
+ * an emitted IR graph.
+ */
+export type IrValueId = number & {
+    readonly __brand: "IrValueId";
+};
+export declare function asValueId(n: number): IrValueId;
+/**
+ * Stable identity of an allocation site (#1586).
+ *
+ * Unlike {@link IrValueId} — which is a per-function SSA index that inlining
+ * and monomorphization renumber — an `AllocSiteId` is **module-global** and
+ * travels on the instruction itself (`IrInstrBase.alloc`). It survives every
+ * IR transformation: passes preserve it through value-preserving rewrites,
+ * alias it through fusion, and retire it on deletion (see the pass-discipline
+ * rules in docs/adr/0013-ir-allocation-sites.md).
+ *
+ * Identity MUST NOT be keyed on `IrValueId` — that breaks under renumbering.
+ */
+export type AllocSiteId = number & {
+    readonly __brand: "AllocSiteId";
+};
+export declare function asAllocSiteId(n: number): AllocSiteId;
+/**
+ * The category of value an allocation site brings into existence. Mirrors the
+ * value-creating IR instr kinds (object.new, closure.new, …). Black-box
+ * built-in internal allocations are out of scope (#1586 non-goals).
+ */
+export type AllocKind = "object" | "array" | "string" | "closure" | "refcell" | "box" | "extern" | "iterator" | "generator";
+/** Allocate sequential IrValueIds within a function. */
+export declare class IrValueIdAllocator {
+    private next;
+    fresh(): IrValueId;
+    get count(): number;
+}
+export type IrConst = {
+    readonly kind: "i32";
+    readonly value: number;
+} | {
+    readonly kind: "i64";
+    readonly value: bigint;
+} | {
+    readonly kind: "f32";
+    readonly value: number;
+} | {
+    readonly kind: "f64";
+    readonly value: number;
+} | {
+    readonly kind: "bool";
+    readonly value: boolean;
+} | {
+    readonly kind: "null";
+    readonly ty: IrType;
+} | {
+    readonly kind: "undefined";
+};
+export interface IrSiteId {
+    readonly line: number;
+    readonly column: number;
+}
+export interface IrInstrBase {
+    /** SSA def produced by this instr. `null` for void instrs. */
+    readonly result: IrValueId | null;
+    /** Static type of the result, if any. Redundant w/ `result`'s type but kept local for verifier speed. */
+    readonly resultType: IrType | null;
+    /** Source location for diagnostics. Optional in Phase 1. */
+    readonly site?: IrSiteId;
+    /**
+     * Stable allocation-site identity (#1586). Present iff this instr is a
+     * value-creating (allocation) site — see {@link AllocKind} and the audit
+     * table in docs/adr/0013-ir-allocation-sites.md. Distinct from `result`
+     * (an `IrValueId`, which inlining/monomorphize renumber). Inert at
+     * lowering, so the emitted Wasm is byte-identical whether or not it is set.
+     */
+    readonly alloc?: AllocSiteId;
+}
+/** Materialize a constant into an SSA value. */
+export interface IrInstrConst extends IrInstrBase {
+    readonly kind: "const";
+    readonly value: IrConst;
+}
+/** Call a function by symbolic reference. Return value (if any) is `result`. */
+export interface IrInstrCall extends IrInstrBase {
+    readonly kind: "call";
+    readonly target: IrFuncRef;
+    readonly args: readonly IrValueId[];
+}
+/** Read a global by symbolic reference. */
+export interface IrInstrGlobalGet extends IrInstrBase {
+    readonly kind: "global.get";
+    readonly target: IrGlobalRef;
+}
+/** Write a global by symbolic reference. Void-result. */
+export interface IrInstrGlobalSet extends IrInstrBase {
+    readonly kind: "global.set";
+    readonly target: IrGlobalRef;
+    readonly value: IrValueId;
+}
+/**
+ * Typed binary primitive. The `op` tag encodes both operand type(s) and the
+ * operation, so the lowerer can map 1:1 to a Wasm instruction without
+ * re-inferring types. Phase 1 covers the numeric/bool subset.
+ */
+export type IrBinop = "f64.add" | "f64.sub" | "f64.mul" | "f64.div" | "f64.eq" | "f64.ne" | "f64.lt" | "f64.le" | "f64.gt" | "f64.ge" | "i32.eq" | "i32.ne" | "i32.and" | "i32.or" | "i32.lt_s" | "i32.le_s" | "i32.gt_s" | "i32.ge_s" | "i32.lt_u" | "i32.le_u" | "i32.gt_u" | "i32.ge_u" | "js.bitand" | "js.bitor" | "js.bitxor" | "js.shl" | "js.shr_s" | "js.shr_u";
+/**
+ * Typed unary primitive. `f64.neg` negates a number. `i32.eqz` implements
+ * bool negation (`!x` where x is bool — 0↔1).
+ *
+ * Slice 12 (#1169o) adds `i32.trunc_sat_f64_s` — saturating f64 → i32
+ * truncation. Used to convert a JS-style f64 array index into the i32
+ * the backend `vec.get` instruction expects. Saturation handles
+ * NaN→0 and out-of-range values gracefully (no trap), matching what
+ * test262's array-indexing patterns expect.
+ */
+export type IrUnop = "f64.neg" | "i32.eqz" | "i32.trunc_sat_f64_s" | "f64.abs" | "f64.sqrt" | "f64.floor" | "f64.ceil" | "f64.trunc" | "ref.is_null";
+export interface IrInstrBinary extends IrInstrBase {
+    readonly kind: "binary";
+    readonly op: IrBinop;
+    readonly lhs: IrValueId;
+    readonly rhs: IrValueId;
+}
+export interface IrInstrUnary extends IrInstrBase {
+    readonly kind: "unary";
+    readonly op: IrUnop;
+    readonly rand: IrValueId;
+}
+/**
+ * Conditional expression — lowers to Wasm `select`. Both arms are evaluated;
+ * this is safe for pure Phase 1 expressions (no calls, no side effects).
+ * Branching control flow (for statements with side effects) comes in Phase 2
+ * via `br_if` terminators.
+ */
+export interface IrInstrSelect extends IrInstrBase {
+    readonly kind: "select";
+    readonly condition: IrValueId;
+    readonly whenTrue: IrValueId;
+    readonly whenFalse: IrValueId;
+}
+/**
+ * (#1392) Value-producing if/else expression. UNLIKE `select`, this
+ * SHORT-CIRCUITS — only one branch's instructions are executed. Used by
+ * the optional-chain lowering (`recv?.prop`) where the right-hand side
+ * (`recv.prop`) MUST NOT execute when `recv` is null.
+ *
+ * The two arm buffers (`then` / `else`) are self-contained instruction
+ * lists collected via `IrFunctionBuilder.collectBodyInstrs(...)`. They
+ * may reference SSA values defined OUTSIDE the if-instr (those are
+ * available through Wasm locals), but values defined INSIDE one arm are
+ * NOT visible to the other arm or to instructions following the if.
+ *
+ * The carrier values are `thenValue` / `elseValue` — IrValueIds defined
+ * inside the corresponding arm. The lowerer emits a Wasm
+ * `if (result T) ... else ... end` block where each arm leaves its
+ * carrier value on the stack; the post-block `local.set` binds the
+ * result to the if-instr's `result` SSA value.
+ *
+ * Both arms must produce values of `resultType`. The verifier rejects
+ * shape mismatches.
+ */
+export interface IrInstrIf extends IrInstrBase {
+    readonly kind: "if";
+    readonly cond: IrValueId;
+    readonly then: readonly IrInstr[];
+    readonly thenValue: IrValueId;
+    readonly else: readonly IrInstr[];
+    readonly elseValue: IrValueId;
+}
+/**
+ * (#1373 Phase B) `await <expr>` — suspend the current async function until
+ * `expr`'s Promise settles, then resume with the resolved value. The IR
+ * node carries the operand whose evaluation produces a Promise (or a
+ * non-Promise value that must be wrapped in `Promise.resolve` before
+ * suspension per spec §27.2.1.4).
+ *
+ * Phase B (this slice) defines the type only — no lowering. Phase C
+ * (CPS transform, follow-up #1373b) splits the function at each await
+ * point, lifts the post-await tail into a continuation closure, and
+ * emits microtask-queue calls (`__promise_then(promise, continuation)`)
+ * to schedule resumption.
+ *
+ * The result IrValueId carries the resolved value. Its IrType must
+ * match the surrounding expression context (typically the unwrapped
+ * `T` from `Promise<T>`).
+ */
+export interface IrInstrAwait extends IrInstrBase {
+    readonly kind: "await";
+    readonly operand: IrValueId;
+}
+/**
+ * (#1373 Phase B) `return <value>` from an async function body. UNLIKE
+ * `IrTerminatorReturn`, which produces the bare value, this wraps the
+ * value in `Promise.resolve(value)` per the async function spec
+ * §15.8.5.5. The IR node defines the wrap intent; lowering (Phase C)
+ * emits the wrap via the existing `Promise_resolve` host import in
+ * JS-host mode or via the standalone `$Promise` struct.new in WASI
+ * mode (the latter wired in #1326 Phase 1B).
+ *
+ * Used in tail position only — non-tail `return` inside an async
+ * function flows through the IR's normal block terminator, which the
+ * Phase C lowerer recognises and routes through the same wrap.
+ */
+export interface IrInstrAsyncReturn extends IrInstrBase {
+    readonly kind: "async.return";
+    readonly value: IrValueId;
+}
+/**
+ * (#1373 Phase B) Synchronous throw inside an async function body.
+ * UNLIKE `IrInstrThrow`, which propagates as a Wasm exception, this
+ * wraps the thrown value in `Promise.reject(reason)` so the async
+ * function's outer Promise settles in the rejected state. Lowering
+ * (Phase C) emits the wrap via `Promise_reject` (host) or `$Promise`
+ * struct.new with `state = REJECTED` (standalone, #1326 Phase 1B).
+ *
+ * Currently NOT emitted by from-ast — Phase C wires it from
+ * `ts.ThrowStatement` nodes inside async function bodies.
+ */
+export interface IrInstrAsyncThrow extends IrInstrBase {
+    readonly kind: "async.throw";
+    readonly reason: IrValueId;
+}
+/**
+ * Escape hatch: a raw backend instruction sequence with no SSA structure.
+ * Phase 1 uses this as a bridge so we can describe any function without
+ * re-encoding the whole Wasm opcode set in IR. Phase 2 will narrow uses.
+ * The verifier treats it as an opaque block: stack contract must match.
+ */
+export interface IrInstrRawWasm extends IrInstrBase {
+    readonly kind: "raw.wasm";
+    /** Backend ops to emit verbatim. */
+    readonly ops: readonly import('./types.js').Instr[];
+    /** Wasm value-stack delta after running `ops` (positive = pushes). */
+    readonly stackDelta: number;
+}
+/**
+ * Box a scalar into a tagged-union struct. `toType` must be an `IrType.union`
+ * whose `members` contains `value`'s static ValType. Lowering emits
+ * `struct.new $union_<members>` with the matching tag constant + the value
+ * in the `$val` field. Result is `(ref $union_<members>)` / the `toType`.
+ */
+export interface IrInstrBox extends IrInstrBase {
+    readonly kind: "box";
+    readonly value: IrValueId;
+    readonly toType: IrType;
+}
+/**
+ * Unbox a tagged-union value to one of its member ValTypes. The caller must
+ * have proved the tag already (via `tag.test` earlier in the same IR path);
+ * lowering emits a plain `struct.get $val` without a tag check at runtime.
+ * A debug-mode assertion can still verify the tag.
+ */
+export interface IrInstrUnbox extends IrInstrBase {
+    readonly kind: "unbox";
+    readonly value: IrValueId;
+    readonly tag: ValType;
+}
+/**
+ * Runtime tag discriminator — result (via `IrInstrBase.result`) is `i32`,
+ * 1 if `value`'s runtime tag matches `tag`, else 0. `value` must be a
+ * tagged-union type containing `tag` as a member. Lowers to
+ * `struct.get $tag; i32.const <N>; i32.eq`.
+ */
+export interface IrInstrTagTest extends IrInstrBase {
+    readonly kind: "tag.test";
+    readonly value: IrValueId;
+    readonly tag: ValType;
+}
+/**
+ * Materialize a string literal as an SSA value of `IrType.string`. The
+ * backend representation is determined by `IrLowerResolver.emitStringConst`:
+ *   - host strings → register a `string_constants.<value>` global import,
+ *                    emit `global.get`.
+ *   - native       → emit inline `array.new_fixed` of the WTF-16 code units,
+ *                    then `struct.new $NativeString`.
+ */
+export interface IrInstrStringConst extends IrInstrBase {
+    readonly kind: "string.const";
+    /** Raw JS string; the lowerer treats `value.length` as UTF-16 code units. */
+    readonly value: string;
+}
+/**
+ * Concatenate two strings — the ECMAScript `s1 + s2` operator restricted to
+ * the case where both operands are statically known to be strings. Result
+ * type: `IrType.string`.
+ */
+export interface IrInstrStringConcat extends IrInstrBase {
+    readonly kind: "string.concat";
+    readonly lhs: IrValueId;
+    readonly rhs: IrValueId;
+}
+/**
+ * String equality. `===` and `!==` are both modeled via this single instr —
+ * `negate: true` ↔ `!==`. Result type: `i32` (bool).
+ */
+export interface IrInstrStringEq extends IrInstrBase {
+    readonly kind: "string.eq";
+    readonly lhs: IrValueId;
+    readonly rhs: IrValueId;
+    readonly negate: boolean;
+}
+/**
+ * String length — corresponds to the JS `s.length` property access. Despite
+ * the underlying Wasm op returning `i32`, the IR result is `f64` to match
+ * JS Number semantics, so consumers can compose with the rest of the
+ * numeric IR without an extra coercion step. Lowering inserts the
+ * `f64.convert_i32_s` after the backend's length op.
+ */
+export interface IrInstrStringLen extends IrInstrBase {
+    readonly kind: "string.len";
+    readonly value: IrValueId;
+}
+/**
+ * Materialize an object literal as a WasmGC struct. `shape` declares the
+ * struct's field layout (already canonically sorted by name); `values` is
+ * parallel to `shape.fields` and must have the same length. Lowering emits
+ * each value in canonical order followed by `struct.new $obj_<shape>`.
+ *
+ * Result type: `{ kind: "object", shape }`.
+ */
+export interface IrInstrObjectNew extends IrInstrBase {
+    readonly kind: "object.new";
+    readonly shape: IrObjectShape;
+    readonly values: readonly IrValueId[];
+}
+/**
+ * Read a named field from an object. `value` must be of `IrType.object`
+ * with a shape whose `fields` contain `name`. Lowering emits
+ * `struct.get $obj_<shape> <fieldIdx>`.
+ *
+ * Result type: the field's IrType (must match `resultType`).
+ */
+export interface IrInstrObjectGet extends IrInstrBase {
+    readonly kind: "object.get";
+    readonly value: IrValueId;
+    readonly name: string;
+}
+/**
+ * Write a named field on an object. `value` must be `IrType.object`,
+ * `newValue` must match the field's IrType. Void result. Lowering emits
+ * `struct.set $obj_<shape> <fieldIdx>`.
+ */
+export interface IrInstrObjectSet extends IrInstrBase {
+    readonly kind: "object.set";
+    readonly value: IrValueId;
+    readonly name: string;
+    readonly newValue: IrValueId;
+}
+/**
+ * Materialize a closure value. `liftedFunc` names the lifted top-level
+ * function (registered in the IR module as a synthesized BuiltFn).
+ * `signature` is the caller-visible signature (used to look up the
+ * supertype struct + funcref type). `captures` populates the subtype's
+ * capture fields parallel to `captureFieldTypes`.
+ *
+ * Lowering emits:
+ *   ref.func $lifted
+ *   <push each capture>
+ *   struct.new $closure_<signature>_<captureSig>
+ *
+ * Result type: `{ kind: "closure"; signature }`. The Wasm-level value
+ * type is the supertype struct so call_ref against the base func type
+ * accepts any subtype.
+ */
+export interface IrInstrClosureNew extends IrInstrBase {
+    readonly kind: "closure.new";
+    readonly liftedFunc: IrFuncRef;
+    readonly signature: IrClosureSignature;
+    /** Capture-field IrTypes in struct field order (post-funcref). */
+    readonly captureFieldTypes: readonly IrType[];
+    /** SSA values populating the capture fields, parallel to captureFieldTypes. */
+    readonly captures: readonly IrValueId[];
+}
+/**
+ * Read a capture field from the implicit `__self` closure struct. Only
+ * valid inside a lifted closure body whose IrFunction carries
+ * `closureSubtype` metadata. `index` is the 0-based capture position
+ * (post-funcref).
+ *
+ * Lowering emits:
+ *   <self>
+ *   ref.cast $self_subtype
+ *   struct.get $self_subtype (index+1)
+ */
+export interface IrInstrClosureCap extends IrInstrBase {
+    readonly kind: "closure.cap";
+    /** SSA value of the closure-typed __self param (the lifted func's param 0). */
+    readonly self: IrValueId;
+    readonly index: number;
+}
+/**
+ * Invoke a closure value. `callee` must be `IrType.closure`. `args` must
+ * match the signature's params arity and types.
+ *
+ * Lowering emits:
+ *   <emit callee>          ;; pushes self
+ *   <emit args>
+ *   <emit callee>          ;; pushes self again — second use forces a Wasm local
+ *   struct.get $base_struct $func
+ *   call_ref $base_funcType
+ *
+ * Result type: `signature.returnType`.
+ */
+export interface IrInstrClosureCall extends IrInstrBase {
+    readonly kind: "closure.call";
+    readonly callee: IrValueId;
+    readonly args: readonly IrValueId[];
+}
+/**
+ * Wrap a primitive value in a fresh ref cell. Lowering:
+ *   <emit value>
+ *   struct.new $refcell_<inner>
+ *
+ * Result type: `{ kind: "boxed"; inner: <ValType of value> }`.
+ */
+export interface IrInstrRefCellNew extends IrInstrBase {
+    readonly kind: "refcell.new";
+    readonly value: IrValueId;
+}
+/**
+ * Read the inner value out of a ref cell. `cell` must be `IrType.boxed`.
+ * Result type is `irVal(cell.inner)`.
+ *
+ * Lowering: `<emit cell>; struct.get $refcell 0`.
+ */
+export interface IrInstrRefCellGet extends IrInstrBase {
+    readonly kind: "refcell.get";
+    readonly cell: IrValueId;
+}
+/**
+ * Write a new value through a ref cell. `cell` must be `IrType.boxed`,
+ * `value` ValType must equal `cell.inner`. Void result.
+ *
+ * Lowering: `<emit cell>; <emit value>; struct.set $refcell 0`.
+ */
+export interface IrInstrRefCellSet extends IrInstrBase {
+    readonly kind: "refcell.set";
+    readonly cell: IrValueId;
+    readonly value: IrValueId;
+}
+/**
+ * Construct a class instance via the legacy-registered constructor.
+ *
+ * Lowering:
+ *   <emit each arg in order>
+ *   call $<className>_new
+ *
+ * Result type: `{ kind: "class"; shape }`. The Wasm-level value type is
+ * `(ref $ClassStruct)` (non-null) — `<className>_new` is registered with
+ * a non-null ref result by `collectClassDeclaration`.
+ */
+export interface IrInstrClassNew extends IrInstrBase {
+    readonly kind: "class.new";
+    readonly shape: IrClassShape;
+    readonly args: readonly IrValueId[];
+}
+/**
+ * Read a named field from a class instance. `value` must be `IrType.class`
+ * with a shape containing `fieldName`. Lowering emits:
+ *   <emit value>
+ *   struct.get $<className> <wasmFieldIdx>
+ *
+ * The wasm field index accounts for the legacy `__tag` prefix at field 0
+ * — see `IrLowerResolver.resolveClass`.
+ *
+ * Result type: the field's IrType (also placed in `resultType`).
+ */
+export interface IrInstrClassGet extends IrInstrBase {
+    readonly kind: "class.get";
+    readonly value: IrValueId;
+    readonly fieldName: string;
+}
+/**
+ * Write a named field on a class instance. Void result. Lowering emits:
+ *   <emit value>
+ *   <emit newValue>
+ *   struct.set $<className> <wasmFieldIdx>
+ *
+ * The legacy `collectClassDeclaration` pass widens all class fields to
+ * `mutable: true`, so `struct.set` is always valid.
+ */
+export interface IrInstrClassSet extends IrInstrBase {
+    readonly kind: "class.set";
+    readonly value: IrValueId;
+    readonly fieldName: string;
+    readonly newValue: IrValueId;
+}
+/**
+ * Invoke an instance method. `receiver` must be `IrType.class` whose
+ * shape contains `methodName`. The implicit `this` is prepended as the
+ * first call argument. Lowering emits:
+ *   <emit receiver>
+ *   <emit each arg in order>
+ *   call $<className>_<methodName>
+ *
+ * Result type: the method descriptor's `returnType`. A void method has
+ * `result: null` and `resultType: null`; the AST→IR lowerer rejects
+ * such calls in expression position so we never see a void method as
+ * `lowerExpr` output.
+ */
+export interface IrInstrClassCall extends IrInstrBase {
+    readonly kind: "class.call";
+    readonly receiver: IrValueId;
+    readonly methodName: string;
+    readonly args: readonly IrValueId[];
+}
+/**
+ * Read a Wasm-local slot. `index` is the function-level slot index assigned
+ * at IR build time (allocated via `IrFunctionBuilder.declareSlot`). The slot's
+ * declared type must be a primitive ValType; the result IrType is `irVal`
+ * of that ValType.
+ *
+ * Lowering: `local.get <slotIndex>`.
+ */
+export interface IrInstrSlotRead extends IrInstrBase {
+    readonly kind: "slot.read";
+    readonly slotIndex: number;
+}
+/**
+ * Write a value to a Wasm-local slot. The value's IrType must be `val` with
+ * a ValType matching the slot's declared type. Void result.
+ *
+ * Lowering: `<emit value>; local.set <slotIndex>`.
+ */
+export interface IrInstrSlotWrite extends IrInstrBase {
+    readonly kind: "slot.write";
+    readonly slotIndex: number;
+    readonly value: IrValueId;
+}
+/**
+ * Read `vec.length` (i32) from a vec struct. The vec must have an IrType
+ * that the lowerer's resolver recognises as a vec (typeIdx with a layout of
+ * `{ length: i32, data: (ref $arr) }`). Result is f64 (matching JS Number
+ * semantics — same approach as `string.len`); lowering inserts the
+ * `f64.convert_i32_s` after the i32 read.
+ */
+export interface IrInstrVecLen extends IrInstrBase {
+    readonly kind: "vec.len";
+    readonly vec: IrValueId;
+}
+/**
+ * Index into a vec struct's data array. `index` must be an SSA value of
+ * IrType `irVal({ kind: "i32" })` (f64-to-i32 conversion happens at the
+ * caller — for-of always uses an i32 counter so this is always already i32).
+ *
+ * `resultType` carries the vec element's IrType (the lowerer matches it
+ * against the vec struct's data array's element type).
+ *
+ * Lowering: `<emit vec>; struct.get $vec data; <emit index>; array.get $arr`.
+ */
+export interface IrInstrVecGet extends IrInstrBase {
+    readonly kind: "vec.get";
+    readonly vec: IrValueId;
+    readonly index: IrValueId;
+}
+/**
+ * #1804 — Construct a vec from a fixed, statically-known set of element SSA
+ * values. All `elements` share the IrType `elementType` (the from-ast lowerer
+ * coerces each element to this type before emitting). `resultType` is the vec
+ * ref IrType (a `ref` to the registered vec struct for `elementType`).
+ *
+ * Lowering (WasmGC): push e0…eN, `array.new_fixed $arr N`, stash the data ref
+ * in a scratch local, push `i32.const N` (length, field 0), re-load the data
+ * ref (field 1), `struct.new $vec`. The backend emitter owns the exact op
+ * sequence (see `emitVecNewFixed`) so the linear backend can realize the same
+ * node over its `[header][len][cap][elements…]` layout.
+ *
+ * Empty literals (`[]`) carry `elements: []`; the `elementType` is supplied by
+ * the from-ast layer from the declared/inferred array type (it cannot be
+ * inferred from zero elements).
+ */
+export interface IrInstrVecNewFixed extends IrInstrBase {
+    readonly kind: "vec.new_fixed";
+    readonly elements: readonly IrValueId[];
+    readonly elementType: IrType;
+}
+/**
+ * Statement-level `for (const <bind> of <vec>) <body>` loop instruction.
+ *
+ * Encodes the array fast path declaratively. The lowerer emits:
+ *   <emit vec>
+ *   local.set <vecSlot>
+ *   local.get <vecSlot>
+ *   struct.get $vec data
+ *   local.set <dataSlot>
+ *   local.get <vecSlot>
+ *   struct.get $vec length
+ *   local.set <lenSlot>
+ *   i32.const 0
+ *   local.set <counterSlot>
+ *   block
+ *     loop
+ *       local.get <counterSlot>
+ *       local.get <lenSlot>
+ *       i32.ge_s
+ *       br_if 1                  ;; exit loop
+ *       local.get <dataSlot>
+ *       local.get <counterSlot>
+ *       array.get $arr
+ *       local.set <elementSlot>
+ *       <body instrs>
+ *       local.get <counterSlot>
+ *       i32.const 1
+ *       i32.add
+ *       local.set <counterSlot>
+ *       br 0                     ;; continue
+ *     end
+ *   end
+ *
+ * The vec must have a non-null ref type pointing to a registered vec struct
+ * (the resolver's `resolveVec` resolves it to typeIdx + length/data field
+ * indices + element array typeIdx + element ValType). Nullable vec types
+ * are not in slice 6 — the selector keeps them on the legacy path.
+ *
+ * Slot indices are pre-allocated via `IrFunctionBuilder.declareSlot` before
+ * the from-ast layer emits this instr.
+ *
+ * Result: void (`result: null`).
+ */
+export interface IrInstrForOfVec extends IrInstrBase {
+    readonly kind: "forof.vec";
+    /** SSA value of the iterable. Lowered as the vec ref. */
+    readonly vec: IrValueId;
+    /** Element type — must match the vec's data array's element ValType. */
+    readonly elementType: IrType;
+    /** Pre-allocated slot indices (Wasm local indices) for the loop's state. */
+    readonly counterSlot: number;
+    readonly lengthSlot: number;
+    readonly vecSlot: number;
+    readonly dataSlot: number;
+    readonly elementSlot: number;
+    /** Body instrs emitted inside the loop. */
+    readonly body: readonly IrInstr[];
+}
+/**
+ * Coerce a reference-typed IR value to externref. Used by the iterator-
+ * protocol arm of `lowerForOfStatement` to feed an arbitrary iterable
+ * into the externref-typed `__iterator` host import.
+ *
+ * The input value must have a reference IrType (val/ref, val/ref_null,
+ * val/externref, object, class, closure, or string). Numeric values
+ * (i32, f64, etc.) cannot be coerced — the from-ast layer rejects them
+ * upstream.
+ *
+ * Lowering:
+ *   - val/externref input → no-op (input already externref)
+ *   - any other ref input → `extern.convert_any` after pushing the value.
+ *
+ * Result type: `irVal({ kind: "externref" })`.
+ */
+export interface IrInstrCoerceToExternref extends IrInstrBase {
+    readonly kind: "coerce.to_externref";
+    readonly value: IrValueId;
+}
+/**
+ * Slice 7a (#1169f) — push a yielded value onto the generator function's
+ * `__gen_buffer` Wasm-local. The lowerer dispatches on the value's IrType:
+ *   - `irVal({ kind: "f64" })` → `__gen_push_f64(buffer, value)`
+ *   - (later slices: `i32` → `__gen_push_i32`; `externref` → `__gen_push_ref`)
+ *
+ * Result is void (`result: null`, `resultType: null`). Only valid inside
+ * functions whose `funcKind === "generator"`. The lowerer reads the
+ * `IrFunction.generatorBufferSlot` for the `local.get` of the buffer.
+ *
+ * Lowering pattern (slice 7a — f64 only):
+ *   local.get $__gen_buffer
+ *   <emit value>
+ *   call $__gen_push_f64
+ */
+export interface IrInstrGenPush extends IrInstrBase {
+    readonly kind: "gen.push";
+    readonly value: IrValueId;
+}
+/**
+ * Slice 6 part 3 (#1182) — opaque iterator handle for the host iterator
+ * protocol. Calls `__iterator(iterable)` to obtain the iterator object.
+ *
+ * Lowering:
+ *   <emit iterable>           ;; pushes externref
+ *   call $__iterator           ;; -> externref (the iterator)
+ *
+ * Result type: `irVal({ kind: "externref" })`.
+ */
+export interface IrInstrIterNew extends IrInstrBase {
+    readonly kind: "iter.new";
+    readonly iterable: IrValueId;
+    /** True if this is a `for await` loop — calls `__async_iterator` instead. False for slice 6. */
+    readonly async: boolean;
+}
+/**
+ * Call iter.next() and return the result object handle (externref).
+ * The result is later split into `done` / `value` via separate instrs
+ * so the optimizer can decide whether to evaluate `value` (skip if done).
+ *
+ * Lowering: <emit iter>; call $__iterator_next  -> externref
+ *
+ * Result type: `irVal({ kind: "externref" })`. Side-effecting (advances
+ * the iterator) — DCE must not eliminate it.
+ */
+export interface IrInstrIterNext extends IrInstrBase {
+    readonly kind: "iter.next";
+    readonly iter: IrValueId;
+}
+/**
+ * Test whether an iterator-result object's `.done` is true.
+ *
+ * Lowering: <emit resultObj>; call $__iterator_done -> i32
+ *
+ * Result type: `irVal({ kind: "i32" })`. The operand field is named
+ * `resultObj` (not `result`) to avoid colliding with the SSA-def
+ * `result` field inherited from `IrInstrBase`.
+ */
+export interface IrInstrIterDone extends IrInstrBase {
+    readonly kind: "iter.done";
+    readonly resultObj: IrValueId;
+}
+/**
+ * Read the `.value` slot of an iterator-result object.
+ *
+ * Lowering: <emit resultObj>; call $__iterator_value -> externref
+ *
+ * Result type: `irVal({ kind: "externref" })`. See `IrInstrIterDone`
+ * for the `resultObj` naming rationale.
+ */
+export interface IrInstrIterValue extends IrInstrBase {
+    readonly kind: "iter.value";
+    readonly resultObj: IrValueId;
+}
+/**
+ * Call `iter.return()` if defined. Used by the iterator-close try/finally
+ * so abrupt exits notify the iterator (slice 6 step E, deferred to a
+ * try/finally-aware follow-up).
+ *
+ * Lowering: <emit iter>; call $__iterator_return
+ *
+ * Result type: void (`result: null`). Side-effecting.
+ */
+export interface IrInstrIterReturn extends IrInstrBase {
+    readonly kind: "iter.return";
+    readonly iter: IrValueId;
+}
+/**
+ * Statement-level `for (const <bind> of <iterable>) <body>` loop using
+ * the host iterator protocol. The lowerer emits:
+ *
+ *   <emit iterable>
+ *   call $__iterator
+ *   local.set <iterSlot>
+ *   block
+ *     loop
+ *       local.get <iterSlot>
+ *       call $__iterator_next
+ *       local.tee <resultSlot>
+ *       call $__iterator_done
+ *       br_if 1                  ;; exit loop on done=true
+ *       local.get <resultSlot>
+ *       call $__iterator_value
+ *       local.set <elementSlot>
+ *       <body instrs>
+ *       br 0                     ;; continue
+ *     end
+ *   end
+ *   local.get <iterSlot>
+ *   call $__iterator_return       ;; normal-exit close
+ *
+ * The iterable must be an IR value of externref type (the from-ast
+ * layer inserts a `coerce.to_externref` if the source value isn't
+ * already externref). Slot indices are pre-allocated via
+ * `IrFunctionBuilder.declareSlot`.
+ *
+ * Result: void (`result: null`).
+ */
+export interface IrInstrForOfIter extends IrInstrBase {
+    readonly kind: "forof.iter";
+    /** SSA value of the iterable as externref (caller pre-coerces). */
+    readonly iterable: IrValueId;
+    /** Pre-allocated externref slot for the iterator handle. */
+    readonly iterSlot: number;
+    /** Pre-allocated externref slot for the iterator-result object. */
+    readonly resultSlot: number;
+    /** Pre-allocated externref slot for the current element value. */
+    readonly elementSlot: number;
+    /** Body instrs emitted inside the loop. */
+    readonly body: readonly IrInstr[];
+}
+/**
+ * Slice 7a (#1169f) — generator function epilogue. Pushes the buffer + the
+ * pending-throw cell (always `ref.null.extern` in slice 7a) and calls
+ * `__create_generator(buffer, pendingThrow)` to produce the Generator-like
+ * object the function returns.
+ *
+ * Lowering pattern (slice 7a — synchronous-throw subset):
+ *   local.get $__gen_buffer
+ *   ref.null.extern                ;; pendingThrow always null in 7a
+ *   call $__create_generator
+ *   ;; result: externref Generator object — left on stack for the
+ *   ;; surrounding `return` terminator.
+ *
+ * Slice 7a does NOT yet emit the try/catch wrapping that legacy uses for
+ * deferred-throw semantics (#928). Throws inside the body propagate
+ * immediately (matches V8 generators on the FIRST `.next()` call but
+ * differs from spec on subsequent calls). A future slice (7-throw) will
+ * add the wrapping by carrying the preceding body instrs in this instr,
+ * similar to `forof.vec.body`.
+ *
+ * Result type: `irVal({ kind: "externref" })` — the Generator object.
+ * The function's terminator should be `return [result]`.
+ */
+export interface IrInstrGenEpilogue extends IrInstrBase {
+    readonly kind: "gen.epilogue";
+}
+/**
+ * Slice 7b (#1169f) — `yield* <iterable>` delegation. Drains the inner
+ * iterable into the outer generator's `__gen_buffer` by calling the
+ * `__gen_yield_star(buf, iterable)` host import (signature
+ * `(externref, externref) → void`; the host iterates the inner via
+ * `Symbol.iterator` and pushes each value).
+ *
+ * The `inner` operand MUST already be coerced to externref by the
+ * caller (`lowerYield` in `from-ast.ts` inserts a `coerce.to_externref`
+ * upstream). The lowerer just emits the buffer-load, value, and call.
+ *
+ * Result is void. Only valid inside `funcKind === "generator"`. The
+ * lowerer reads `IrFunction.generatorBufferSlot` for the buffer
+ * `local.get`.
+ *
+ * Lowering pattern:
+ *   local.get $__gen_buffer
+ *   <emit inner>          ;; already externref
+ *   call $__gen_yield_star
+ *
+ * Spec divergence note: ECMA-262 §27.5.3.7 says `yield*` evaluates to
+ * the inner iterator's `return` value (the `IteratorResult.value` when
+ * `done` becomes true). Under the eager-buffer model this is discarded;
+ * `yield*` evaluates to `undefined`. Matches the legacy compiler's
+ * behaviour (`misc.ts:177-202`).
+ */
+export interface IrInstrGenYieldStar extends IrInstrBase {
+    readonly kind: "gen.yieldStar";
+    readonly inner: IrValueId;
+}
+/**
+ * Slice 10 (#1169i) — `new ExternClass(arg1, arg2, ...)` where
+ * `ExternClass` is a host-provided builtin (RegExp, Uint8Array, …). The
+ * Wasm-level result is opaque externref; downstream code accesses it
+ * via `extern.call` / `extern.prop`.
+ *
+ * Lowering:
+ *   <emit each arg>
+ *   call $<className>_new
+ *
+ * Result type: `{ kind: "extern", className }`.
+ */
+export interface IrInstrExternNew extends IrInstrBase {
+    readonly kind: "extern.new";
+    readonly className: string;
+    readonly args: readonly IrValueId[];
+}
+/**
+ * Slice 10 (#1169i) — method call on an extern-class value. `receiver`
+ * is the externref handle; `method` names a method registered on the
+ * class via `ctx.externClasses`.
+ *
+ * Lowering:
+ *   <emit receiver>
+ *   <emit each arg>
+ *   call $<className>_<method>
+ *
+ * Result type: matches the registered method's first result. Void
+ * methods carry `result: null` and `resultType: null`.
+ */
+export interface IrInstrExternCall extends IrInstrBase {
+    readonly kind: "extern.call";
+    readonly className: string;
+    readonly method: string;
+    readonly receiver: IrValueId;
+    readonly args: readonly IrValueId[];
+}
+/**
+ * Slice 10 (#1169i) — property read on an extern-class value.
+ *
+ * Lowering:
+ *   <emit receiver>
+ *   call $<className>_get_<property>
+ *
+ * Result type: the property's registered ValType, wrapped as `IrType.val`.
+ */
+export interface IrInstrExternProp extends IrInstrBase {
+    readonly kind: "extern.prop";
+    readonly className: string;
+    readonly property: string;
+    readonly receiver: IrValueId;
+}
+/**
+ * Slice 10 (#1169i) — property write on an extern-class value (for
+ * non-readonly props).
+ *
+ * Lowering:
+ *   <emit receiver>
+ *   <emit value>
+ *   call $<className>_set_<property>
+ */
+export interface IrInstrExternPropSet extends IrInstrBase {
+    readonly kind: "extern.propSet";
+    readonly className: string;
+    readonly property: string;
+    readonly receiver: IrValueId;
+    readonly value: IrValueId;
+}
+/**
+ * Slice 10 (#1169i) — RegExp literal `/pattern/flags`. Lowers to
+ * `RegExp_new(pattern, flags)`. The pattern + flags are registered as
+ * string-literal globals (the legacy `collectStringLiterals` pass
+ * already collects RegExp pattern/flags as string literals — see
+ * `src/codegen/index.ts:3274-3278` — so by the time the IR emits this
+ * instr the corresponding string globals exist).
+ *
+ * Result type: `{ kind: "extern", className: "RegExp" }`.
+ */
+export interface IrInstrRegExpLiteral extends IrInstrBase {
+    readonly kind: "extern.regex";
+    readonly pattern: string;
+    readonly flags: string;
+}
+/**
+ * Statement-level `for (const c of <string>) <body>` loop using the
+ * native-strings counter pattern. Emitted only when the resolver
+ * reports `nativeStrings(): true` — host-strings mode falls through
+ * to `forof.iter` upstream in `lowerForOfStatement`.
+ *
+ * The lowerer emits:
+ *   <emit str>
+ *   local.set <strSlot>
+ *   local.get <strSlot>
+ *   struct.get $AnyString $len
+ *   local.set <lengthSlot>
+ *   i32.const 0
+ *   local.set <counterSlot>
+ *   block
+ *     loop
+ *       local.get <counterSlot>
+ *       local.get <lengthSlot>
+ *       i32.ge_s
+ *       br_if 1
+ *       local.get <strSlot>
+ *       local.get <counterSlot>
+ *       call $__str_charAt
+ *       local.set <elementSlot>
+ *       <body instrs>
+ *       local.get <counterSlot>
+ *       i32.const 1
+ *       i32.add
+ *       local.set <counterSlot>
+ *       br 0
+ *     end
+ *   end
+ *
+ * Slot types (set by from-ast):
+ *   counterSlot — i32
+ *   lengthSlot  — i32
+ *   strSlot     — `(ref $AnyString)` (resolver.resolveString())
+ *   elementSlot — `(ref $AnyString)` — each iteration produces a
+ *                 single-char string
+ *
+ * Result: void (`result: null`).
+ */
+export interface IrInstrForOfString extends IrInstrBase {
+    readonly kind: "forof.string";
+    /** SSA value of the string (IrType.string). */
+    readonly str: IrValueId;
+    readonly counterSlot: number;
+    readonly lengthSlot: number;
+    readonly strSlot: number;
+    readonly elementSlot: number;
+    /** Body instrs emitted inside the loop. */
+    readonly body: readonly IrInstr[];
+}
+/**
+ * Slice 9 (#1169h) — throw an exception. The `value` is coerced to externref
+ * upstream (the `__exn` tag's signature is `(externref)`). After throw,
+ * control transfers to the nearest enclosing catch matching the tag, or
+ * unwinds out of the function.
+ *
+ * The instr produces NO SSA value (control doesn't fall through), so
+ * `result` and `resultType` are always null. The verifier treats it as a
+ * "stop" instr — instructions after it in the same block are unreachable
+ * in source but still validated structurally.
+ *
+ * Lowering:
+ *   <emit value>          ;; pushes externref
+ *   throw $__exn
+ */
+export interface IrInstrThrow extends IrInstrBase {
+    readonly kind: "throw";
+    readonly value: IrValueId;
+}
+/**
+ * Slice 12 (#1280) — `while (cond) body` loop.
+ *
+ * Lowering pattern:
+ *   block
+ *     loop
+ *       <cond instrs>          ;; computes condValue
+ *       <emit condValue>       ;; pushes the i32 boolean
+ *       i32.eqz
+ *       br_if 1                ;; exit on falsy
+ *       <body instrs>
+ *       br 0                   ;; continue
+ *     end
+ *   end
+ *
+ * `condValue` MUST be the SSA result of an instruction in `cond` (or
+ * an outer-scope value that's loaded into `cond`'s last instr). The
+ * resolver coerces non-i32 values to i32 via the standard truthy
+ * lowering path — for now the from-ast layer enforces an i32 result.
+ *
+ * Result: void (`result: null`).
+ */
+export interface IrInstrWhileLoop extends IrInstrBase {
+    readonly kind: "while.loop";
+    /** Instructions that compute the condition. Re-evaluated per iteration. */
+    readonly cond: readonly IrInstr[];
+    /** SSA value of the condition (an i32 boolean). */
+    readonly condValue: IrValueId;
+    /** Body instructions executed each iteration when the cond is truthy. */
+    readonly body: readonly IrInstr[];
+}
+/**
+ * Slice 12 (#1280) — `for (init; cond; update) body` loop.
+ *
+ * The init clause is emitted by the from-ast layer as ordinary IR
+ * statements BEFORE the `for.loop` instr (init is just a let-decl or
+ * an assignment expression statement, no special encoding needed).
+ * The instr carries cond, body, update.
+ *
+ * Lowering pattern:
+ *   block
+ *     loop
+ *       <cond instrs>
+ *       <emit condValue>
+ *       i32.eqz
+ *       br_if 1
+ *       <body instrs>
+ *       <update instrs>        ;; runs after body, before re-evaluating cond
+ *       br 0
+ *     end
+ *   end
+ *
+ * Result: void (`result: null`).
+ */
+export interface IrInstrForLoop extends IrInstrBase {
+    readonly kind: "for.loop";
+    /** Instructions that compute the condition. Re-evaluated per iteration. */
+    readonly cond: readonly IrInstr[];
+    /** SSA value of the condition (an i32 boolean). */
+    readonly condValue: IrValueId;
+    /** Body instructions executed each iteration when the cond is truthy. */
+    readonly body: readonly IrInstr[];
+    /** Update instructions executed after the body each iteration. */
+    readonly update: readonly IrInstr[];
+}
+/**
+ * Slice 9 (#1169h) — try / catch / finally as a declarative statement-level
+ * instr. Mirrors the slice-6 `forof.vec` shape: the body / catch handler /
+ * finally are self-contained Instr[] buffers, and the lowerer emits the
+ * structured Wasm `try`/`catch`/`catch_all` op directly without
+ * restructuring the IR's block graph.
+ *
+ * Encoding:
+ *   - `body`              the try block's instructions.
+ *   - `catchClause`       optional. When present, encodes a source-level
+ *                         `catch (e) { ... }` (or `catch { ... }`).
+ *                            * `payloadSlot` — slot of `(externref)` that
+ *                              receives the thrown value at handler entry
+ *                              (or -1 when there is no source binding).
+ *                            * `body`        — handler instructions.
+ *   - `finallyBody`       optional. When present, the lowerer inlines this
+ *                         buffer at every "abrupt completion" path:
+ *                            * normal exit of try body
+ *                            * normal exit of catch body
+ *                            * a synthesized catch_all that re-throws
+ *
+ * Acceptable shapes (selector-enforced):
+ *   try { ... } catch (e) { ... }              catchClause set
+ *   try { ... } catch { ... }                  catchClause set, payloadSlot=-1
+ *   try { ... } finally { ... }                finallyBody set
+ *   try { ... } catch (e) { ... } finally { ... }   both set
+ *
+ * Result is void (`result: null`).
+ */
+export interface IrInstrTry extends IrInstrBase {
+    readonly kind: "try";
+    /** Try block instructions. */
+    readonly body: readonly IrInstr[];
+    /** Optional source-level catch handler. */
+    readonly catchClause?: {
+        /**
+         * Externref-typed slot index that the lowerer writes the caught
+         * exception into at handler entry. `-1` when the source has no
+         * binding (`catch { ... }`).
+         */
+        readonly payloadSlot: number;
+        readonly body: readonly IrInstr[];
+    };
+    /** Optional finally body, inlined at every exit path. */
+    readonly finallyBody?: readonly IrInstr[];
+}
+export type IrInstr = IrInstrConst | IrInstrCall | IrInstrGlobalGet | IrInstrGlobalSet | IrInstrBinary | IrInstrUnary | IrInstrSelect | IrInstrIf | IrInstrRawWasm | IrInstrBox | IrInstrUnbox | IrInstrTagTest | IrInstrStringConst | IrInstrStringConcat | IrInstrStringEq | IrInstrStringLen | IrInstrObjectNew | IrInstrObjectGet | IrInstrObjectSet | IrInstrClosureNew | IrInstrClosureCap | IrInstrClosureCall | IrInstrRefCellNew | IrInstrRefCellGet | IrInstrRefCellSet | IrInstrClassNew | IrInstrClassGet | IrInstrClassSet | IrInstrClassCall | IrInstrSlotRead | IrInstrSlotWrite | IrInstrVecLen | IrInstrVecGet | IrInstrVecNewFixed | IrInstrForOfVec | IrInstrCoerceToExternref | IrInstrIterNew | IrInstrIterNext | IrInstrIterDone | IrInstrIterValue | IrInstrIterReturn | IrInstrForOfIter | IrInstrGenPush | IrInstrGenEpilogue | IrInstrGenYieldStar | IrInstrForOfString | IrInstrThrow | IrInstrTry | IrInstrExternNew | IrInstrExternCall | IrInstrExternProp | IrInstrExternPropSet | IrInstrRegExpLiteral | IrInstrWhileLoop | IrInstrForLoop | IrInstrAwait | IrInstrAsyncReturn | IrInstrAsyncThrow;
+/**
+ * Slice 6 (#1169e) — declaration of one Wasm-local slot used for cross-
+ * iteration mutable state. Slots are allocated by the IR builder and
+ * surface in the lowered Wasm function as additional locals appended
+ * after the params and the SSA-driven locals.
+ *
+ *   - `index`        stable slot index, used by `slot.read` / `slot.write`.
+ *                    NOT a Wasm local index — the lowerer translates slot
+ *                    index N to Wasm local index `params + ssaLocals + N`.
+ *   - `name`         debug name for the local.
+ *   - `type`         primitive ValType (i32 / f64 / etc.) — slots only
+ *                    carry primitives; reference-typed cross-iteration
+ *                    state is rare in slice-6 loop bodies.
+ */
+export interface IrSlotDef {
+    readonly index: number;
+    readonly name: string;
+    readonly type: ValType;
+}
+export interface IrBranch {
+    readonly target: IrBlockId;
+    readonly args: readonly IrValueId[];
+}
+export type IrBlockId = number & {
+    readonly __brand: "IrBlockId";
+};
+export declare function asBlockId(n: number): IrBlockId;
+export interface IrTerminatorReturn {
+    readonly kind: "return";
+    readonly values: readonly IrValueId[];
+    readonly site?: IrSiteId;
+}
+export interface IrTerminatorBr {
+    readonly kind: "br";
+    readonly branch: IrBranch;
+    readonly site?: IrSiteId;
+}
+export interface IrTerminatorBrIf {
+    readonly kind: "br_if";
+    readonly condition: IrValueId;
+    readonly ifTrue: IrBranch;
+    readonly ifFalse: IrBranch;
+    readonly site?: IrSiteId;
+}
+export interface IrTerminatorUnreachable {
+    readonly kind: "unreachable";
+    readonly site?: IrSiteId;
+}
+export type IrTerminator = IrTerminatorReturn | IrTerminatorBr | IrTerminatorBrIf | IrTerminatorUnreachable;
+export interface IrBlock {
+    readonly id: IrBlockId;
+    /** SSA values bound on entry (replace phi nodes). Types are parallel to `blockArgTypes`. */
+    readonly blockArgs: readonly IrValueId[];
+    readonly blockArgTypes: readonly IrType[];
+    readonly instrs: readonly IrInstr[];
+    readonly terminator: IrTerminator;
+}
+export interface IrParam {
+    readonly value: IrValueId;
+    readonly type: IrType;
+    readonly name: string;
+}
+export interface IrFunction {
+    readonly name: string;
+    readonly params: readonly IrParam[];
+    readonly resultTypes: readonly IrType[];
+    /** Entry block is always `blocks[0]`. */
+    readonly blocks: readonly IrBlock[];
+    readonly exported: boolean;
+    /** Highest IrValueId allocated + 1 (useful for re-entering the builder). */
+    readonly valueCount: number;
+    /**
+     * Slice 3 (#1169c): for closure-lifted bodies only, identifies the
+     * subtype struct that captures live on. Set by `liftClosureBody` in
+     * `from-ast.ts`. The lowerer reads this when emitting `closure.cap`
+     * to compute the correct ref.cast target. Absent for nested function
+     * declarations (which don't take a __self param) and for outer
+     * functions.
+     */
+    readonly closureSubtype?: {
+        readonly signature: IrClosureSignature;
+        readonly captureFieldTypes: readonly IrType[];
+    };
+    /**
+     * Slice 6 (#1169e): Wasm-local slots used for cross-iteration mutable
+     * state in for-of loops. Empty for functions that don't contain a
+     * for-of (or any other slot user). Slot indices are stable; the
+     * lowerer maps slot index N to Wasm local index
+     *   `params.length + ssaLocalCount + N`
+     * — i.e. slots come AFTER the SSA-driven locals.
+     */
+    readonly slots?: readonly IrSlotDef[];
+    /**
+     * Slice 7a (#1169f) — distinguishes regular / generator / async
+     * functions. Set by `lowerFunctionAstToIr` from the AST node's
+     * `asteriskToken` and `async` modifier. The lowerer reads this to:
+     *   - `"generator"`: select the externref Wasm-result type regardless
+     *     of the source-level annotation (the function returns a
+     *     Generator-like object, not the source-declared yield element
+     *     type), AND register the function name in `ctx.generatorFunctions`
+     *     downstream (for any name-based dispatch the legacy already wires).
+     *   - `"async"`: register in `ctx.asyncFunctions` so the export glue's
+     *     `wrapAsyncReturn` wraps the result in `Promise.resolve`. (Slice
+     *     7d, not 7a.)
+     *   - `"regular"`: no special treatment (default if absent).
+     */
+    readonly funcKind?: "regular" | "generator" | "async";
+    /**
+     * Slice 7a (#1169f) — for `funcKind === "generator"` functions only,
+     * the slot index (in `slots`) of the `__gen_buffer` Wasm-local. The
+     * lowerer reads this when emitting `gen.push` / `gen.epilogue` to
+     * produce the `local.get $__gen_buffer` op.
+     */
+    readonly generatorBufferSlot?: number;
+}
+export interface IrModule {
+    readonly functions: readonly IrFunction[];
+}
+export declare function isIrFuncRef(x: unknown): x is IrFuncRef;
+export declare function isIrGlobalRef(x: unknown): x is IrGlobalRef;
+export declare function isIrTypeRef(x: unknown): x is IrTypeRef;
+/**
+ * Invoke `fn` once per nested `IrInstr[]` buffer carried directly by `instr`
+ * (NOT recursively — see `forEachInstrDeep` for the deep walk). The exhaustive
+ * switch is the authoritative list of buffer-bearing kinds; the trailing
+ * `never` assignment makes a missing case a compile error, so a new
+ * buffer-bearing instr kind cannot be added without extending this one place.
+ *
+ * Buffer order is the lowering/evaluation order (cond before body before
+ * update; then before else; body/catch/finally) so callers that care about
+ * order (def registration) get it for free.
+ */
+export declare function forEachNestedBuffer(instr: IrInstr, fn: (buffer: readonly IrInstr[]) => void): void;
+/**
+ * Visit `instr` and every instruction nested within its buffers, recursively
+ * (pre-order: the containing instr before its buffer contents). The single
+ * deep-walk primitive shared by the verifier (def registration) and the
+ * alloc-discipline pass (allocation retirement).
+ */
+export declare function forEachInstrDeep(instr: IrInstr, visit: (i: IrInstr) => void): void;
+/**
+ * Rebuild `instr` with each nested buffer replaced by `mapBuffer(buffer)` — the
+ * write-side companion to `forEachNestedBuffer`, used by the hygiene passes
+ * (#1925) to fold / DCE *inside* control-flow buffers. Buffers are passed in the
+ * same evaluation order `forEachNestedBuffer` yields them.
+ *
+ * Reference-equality preserving: when `mapBuffer` returns each buffer unchanged
+ * (same array reference), the original `instr` is returned as-is, so callers can
+ * detect "no change" by `===` and keep their fixpoint contract. A non-buffer
+ * instr is always returned unchanged.
+ */
+export declare function mapNestedBuffers(instr: IrInstr, mapBuffer: (buffer: readonly IrInstr[]) => readonly IrInstr[]): IrInstr;
+/**
+ * The direct SSA-value operands of `instr` — the values it reads at its own
+ * level, NOT including operands buried in nested buffers. This is the canonical
+ * single-count mapping used by the verifier and DCE (so e.g. `closure.call`'s
+ * callee is counted once; the lowering use-counter's intentional double-count
+ * for Wasm-local materialisation stays local to lower.ts).
+ *
+ * For buffer-bearing control-flow instrs, the operands surfaced here are only
+ * the ones evaluated at the instr's own level: `if` → cond; `while/for` →
+ * condValue; `forof.*` → the iterable/vec/str; `try` → none. Buffer-interior
+ * uses are reached via `collectUses(instr, { deep: true })`.
+ */
+export declare function directUses(instr: IrInstr): readonly IrValueId[];
+/**
+ * Collect the SSA-value uses of `instr`. Shallow by default (== `directUses`);
+ * with `{ deep: true }` it also walks every nested buffer via
+ * `forEachNestedBuffer`, surfacing buffer-interior uses too. The deep form is
+ * what DCE needs so values referenced only inside a loop/if/for-of/try buffer
+ * survive liveness — the exact bug (#1922) the per-kind ad-hoc walkers caused
+ * for `while.loop`/`for.loop`.
+ */
+export declare function collectUses(instr: IrInstr, opts?: {
+    readonly deep?: boolean;
+}): readonly IrValueId[];