@loopdive/js2 0.57.0

package/dist/ir/lower.d.ts

@@ -0,0 +1,203 @@
+import { BackendEmitter } from './backend/emitter.js';
+import { IrBoxedLowering, IrClassLowering, IrClosureLowering, IrObjectStructLowering, IrRefCellLowering, IrUnionLowering, IrVecLowering } from './backend/handles.js';
+import { IrClassShape, IrClosureSignature, IrFuncRef, IrFunction, IrGlobalRef, IrInstr, IrObjectShape, IrType, IrTypeRef, IrValueId } from './nodes.js';
+import { FuncTypeDef, Instr, LocalDef, ValType, WasmFunction } from './types.js';
+export type { IrBoxedLowering, IrClassLowering, IrClosureLowering, IrObjectStructLowering, IrRefCellLowering, IrUnionLowering, IrVecLowering, };
+export interface IrLowerResolver {
+    resolveFunc(ref: IrFuncRef): number;
+    resolveGlobal(ref: IrGlobalRef): number;
+    resolveType(ref: IrTypeRef): number;
+    internFuncType(type: FuncTypeDef): number;
+    /**
+     * Resolve (and memoise) the WasmGC struct type for a `union` IrType. V1
+     * scope: homogeneous-width unions only — see
+     * `passes/tagged-union-types.ts`. Returns `null` when the union is not
+     * representable (heterogeneous, or contains reference members); callers
+     * must treat that as `dynamic` upstream.
+     *
+     * Optional so Phase-1 resolvers without tagged-union support can omit it;
+     * a Phase-3 function that actually emits `box`/`unbox`/`tag.test` will
+     * fail at lowering time when it's missing, which is the correct behavior
+     * (caller should have rejected the IR earlier).
+     */
+    resolveUnion?(members: readonly ValType[]): IrUnionLowering | null;
+    /**
+     * Resolve (and memoise) the WasmGC struct type for a `boxed` IrType.
+     * Optional for the same reason as `resolveUnion`.
+     */
+    resolveBoxed?(inner: ValType): IrBoxedLowering | null;
+    /**
+     * Resolve (and memoise) the WasmGC struct type for an `IrType.object`
+     * shape. Returns `null` if the shape contains a field type the backend
+     * can't lower (e.g. a nested boxed-IrType the V1 boxed registry doesn't
+     * support).
+     *
+     * The slice-2 implementation in `integration.ts` delegates to a shared
+     * `ObjectStructRegistry` that hashes shapes against
+     * `ctx.anonStructHash`, so legacy `ensureStructForType` and the IR path
+     * converge on a single WasmGC struct for any given shape.
+     */
+    resolveObject?(shape: IrObjectShape): IrObjectStructLowering | null;
+    /**
+     * Slice 3 (#1169c): resolve the SUPERTYPE WasmGC struct for a closure
+     * signature. Carried by the IrType.closure ValType so all
+     * same-signature closures share one Wasm type. Returns `null` if the
+     * signature contains an IrType the backend can't lower (e.g. a
+     * nested object shape the slice-2 resolver hasn't pre-walked).
+     */
+    resolveClosure?(signature: IrClosureSignature): IrClosureLowering | null;
+    /**
+     * Slice 3 (#1169c): resolve the SUBTYPE WasmGC struct for a specific
+     * closure-construction site. Different `(signature, captureFieldTypes)`
+     * pairs produce different subtypes of the supertype struct, so the
+     * lifted body's `ref.cast` recovers capture-field positions.
+     */
+    resolveClosureSubtype?(signature: IrClosureSignature, captureFieldTypes: readonly IrType[]): IrClosureLowering | null;
+    /**
+     * Slice 3 (#1169c): resolve the WasmGC struct type for a ref cell
+     * over a primitive ValType. Delegates to the legacy
+     * `getOrRegisterRefCellType` so legacy and IR ref cells share one
+     * type per inner ValType.
+     */
+    resolveRefCell?(inner: ValType): IrRefCellLowering | null;
+    /**
+     * Slice 4 (#1169d): resolve the WasmGC struct + constructor + method
+     * funcs for a class declared in the compilation unit. Returns `null`
+     * if `shape.className` was not registered by the legacy class
+     * collection pass — that's a selector bug.
+     */
+    resolveClass?(shape: IrClassShape): IrClassLowering | null;
+    /**
+     * Slice 6 (#1169e): resolve a vec struct given its top-level Wasm
+     * ValType. The IR carries the vec's value as a `ref`/`ref_null` to a
+     * registered vec struct; the resolver inspects the struct's fields to
+     * verify the layout is `{ length: i32, data: (ref $arr) }` and returns
+     * the typeIdx + field indices + element ValType. Returns `null` when
+     * the type isn't a recognisable vec — caller treats that as a bug
+     * (selector should have rejected the for-of).
+     */
+    resolveVec?(valType: ValType): IrVecLowering | null;
+    /**
+     * #1804 — resolve (registering if needed) the vec struct for an *element*
+     * ValType, used by `vec.new_fixed` construction where a fresh literal has no
+     * vec typeIdx yet. Unlike `resolveVec` (read-only — recognizes an existing
+     * `(ref $vec)`), this get-or-creates the `$arr`/`$vec` types for the element
+     * via the legacy registry so the constructed vec shares identity with the
+     * legacy `compileArrayLiteral` output (===, instanceof Array, the for-of fast
+     * path). Returns the same `IrVecLowering` shape as `resolveVec`.
+     */
+    resolveVecForElement?(elementValType: ValType): IrVecLowering | null;
+    /**
+     * Resolve the Wasm value type used for `IrType.string` in the active
+     * backend.
+     *   - `wasm:js-string` mode → `{ kind: "externref" }`.
+     *   - `nativeStrings` mode  → `{ kind: "ref", typeIdx: ctx.anyStrTypeIdx }`.
+     * Optional so Phase-1 resolvers without string support can omit it; a
+     * function that actually emits a `string.*` instr will fail at lowering
+     * time when it's missing.
+     */
+    resolveString?(): ValType;
+    /**
+     * Slice 6 part 4 (#1183) refactored in #1185: returns whether the
+     * compiler is in native-strings mode. Drives the for-of strategy
+     * switch for `string`-typed iterables in `lowerForOfStatement`.
+     * Optional for the same reason as `resolveString` — Phase-1
+     * resolvers without string support can omit it.
+     */
+    nativeStrings?(): boolean;
+    /**
+     * Emit the Wasm op sequence that materializes a string literal.
+     *   - host strings → register a `string_constants.<value>` global import
+     *                    and emit `[global.get]`.
+     *   - native       → inline `i32.const len`, `i32.const 0`, code-unit
+     *                    `i32.const`s, `array.new_fixed`, `struct.new`.
+     */
+    emitStringConst?(value: string, alloc?: import('./nodes.js').AllocSiteId): readonly Instr[];
+    /** `[call concat]` (host) or `[call __str_concat]` (native). */
+    emitStringConcat?(): readonly Instr[];
+    /** `[call equals]` (host) or `[call __str_equals]` (native). */
+    emitStringEquals?(): readonly Instr[];
+    /**
+     * `[call length]` (host) or `[struct.get $AnyString $len]` (native).
+     * Result is i32 — the `string.len` IR instr appends an
+     * `f64.convert_i32_s` after this.
+     */
+    emitStringLen?(): readonly Instr[];
+    /**
+     * Slice 9 (#1169h): resolve (and lazily register) the shared `__exn`
+     * exception tag. The tag carries an `externref` payload — every
+     * thrown value is coerced to externref upstream. Returning the
+     * `tagIdx` lets the lowerer emit `throw $exnTagIdx` and `try ...
+     * catch $exnTagIdx`. IR-compiled throws are catchable by
+     * legacy-compiled handlers (and vice versa) because both paths go
+     * through the same single tag.
+     */
+    ensureExnTag?(): number;
+    /**
+     * #1373b Phase C scaffolding — resolve (and lazily register) the
+     * standalone `$Promise` WasmGC struct type. The struct's layout is
+     * `{ state: i32, value: externref, callbacks: externref }` (see
+     * `src/codegen/async-scheduler.ts` for the canonical registration).
+     *
+     * Returns the struct's typeIdx. Used by IR's `async.return`,
+     * `async.throw`, and `await` lowering to construct or inspect
+     * Promise values without going through the JS-host `Promise.resolve`
+     * / `Promise.reject` imports.
+     *
+     * Optional — Phase-1 resolvers (pre-#1373b) can omit it; lowering
+     * falls back to a throw stub when missing.
+     */
+    resolvePromiseType?(): number;
+}
+export interface IrLowerResult {
+    readonly func: WasmFunction;
+}
+/**
+ * #1584 (a0-tail): the backend-agnostic lowering result. `lowerIrFunctionBody`
+ * is generic over the emitter sink `S`; it returns the lowered body in that
+ * sink plus the backend-independent function metadata (`typeIdx`, `locals`,
+ * `name`, `exported`). The WasmGC wrapper (`lowerIrFunctionToWasm`, `S =
+ * Instr[]`) assembles the concrete `WasmFunction` from this; a bytecode driver
+ * consumes `body: BytecodeSink` directly. The `typeIdx`, `locals`, `name`, and
+ * `exported` fields are identical regardless of `S` — only `body` changes
+ * representation, which is exactly the #1715 sink-is-the-one-seam finding.
+ */
+export interface IrLoweredBody<S> {
+    readonly name: string;
+    readonly body: S;
+    readonly locals: LocalDef[];
+    readonly typeIdx: number;
+    readonly exported: boolean;
+}
+/**
+ * #1584 (a0-tail): thin WasmGC wrapper. Every pre-#1584 caller is unchanged —
+ * it still returns `IrLowerResult` (`{ func: WasmFunction }`) with `S = Instr[]`
+ * lowering, byte-identical to the previous monolithic body. The generic body
+ * does all the work; this only assembles the `WasmFunction` shape from the
+ * `Instr[]` sink.
+ */
+export declare function lowerIrFunctionToWasm(func: IrFunction, resolver: IrLowerResolver, emitter?: BackendEmitter): IrLowerResult;
+/**
+ * #1584 (a0-tail): the real lowering, generic over the emitter sink `S`. With
+ * `S = Instr[]` (WasmGC, the default) the emitted stream is byte-identical to
+ * the pre-#1584 monolith. With `S = BytecodeSink` the SAME drive shape produces
+ * a flat opcode stream — the bytecode arm is then produced by the REAL
+ * `lower.ts`, not a hand-lowerer (the (a0) acceptance criterion).
+ *
+ * Op families that structurally embed nested `Instr[]` sub-buffers into a raw
+ * WasmGC `Instr` (loop / try / await — see `requireInstrSink` below) are still
+ * WasmGC-only: on a non-`Instr[]` sink they throw the not-yet-migrated boundary
+ * loudly. Each migrates behind a typed trait primitive in §2a (a1..a6).
+ */
+export declare function lowerIrFunctionBody<S>(func: IrFunction, resolver: IrLowerResolver, emitter?: BackendEmitter<S>): IrLoweredBody<S>;
+/**
+ * Slice 6 (#1169e): walk a `forof.vec` body recursively and collect every
+ * SSA value referenced. Used by the cross-block use counter to ensure
+ * outer-scope values used inside the loop body are materialised in Wasm
+ * locals before the loop starts.
+ */
+export declare function collectForOfBodyUses(body: readonly IrInstr[]): IrValueId[];
+export declare function lowerIrTypeToValType(t: IrType, resolver: IrLowerResolver, funcName: string): ValType;
+export declare function emitConstInstr(instr: Extract<IrInstr, {
+    kind: "const";
+}>, out: Instr[], funcName: string): void;