@loopdive/js2 0.57.0

package/dist/ir/backend/emitter.d.ts

@@ -0,0 +1,121 @@
+import { IrBackendKind } from './legality.js';
+import { IrBinop, IrInstr, IrType, IrUnop } from '../nodes.js';
+import { BlockType, Instr } from '../types.js';
+import { IrClassLowering, IrClosureLowering, IrObjectStructLowering, IrRefCellLowering, IrUnionLowering, IrVecLowering, LinearVecLowering } from './handles.js';
+type VecLayout = IrVecLowering | LinearVecLowering;
+/**
+ * #1584: the trait is generic over its SINK type `S`. `WasmGcEmitter` /
+ * `LinearEmitter` use `S = Instr[]` (the default — every pre-#1584 caller is
+ * unchanged). `BytecodeEmitter` uses `S = BytecodeSink` (a flat opcode stream).
+ * The sink abstraction is the ONE representation-specific seam the #1715 finding
+ * identified; this generic parameter realizes it.
+ *
+ * Two sink operations belong to the trait (not the per-node primitives) because
+ * `lower.ts` itself touches the sink directly:
+ *  - `newSink()` — the sink factory `lower.ts` uses to build `if`-arm buffers
+ *    (it builds each arm into its own sink, then hands both to `emitIf`).
+ *  - `pushRaw(out, instr)` — the raw-`Instr` escape hatch (#1584 contract
+ *    §0a-1). `lower.ts` still has ~119 inline pushes for op families not yet
+ *    migrated behind the trait. On WasmGC these append to the `Instr[]`; on the
+ *    bytecode sink they hit an unrealized op family and throw (the
+ *    not-yet-migrated boundary, surfaced loudly). As each family migrates
+ *    (§2a), its sites move from `pushRaw` to a typed primitive.
+ */
+export interface BackendEmitter<S = Instr[]> {
+    /** Backend identity used by the IR legality verifier at the emit boundary. */
+    readonly backend: IrBackendKind;
+    /** Create a fresh empty sink (for `if`-arm buffers built by lower.ts). */
+    newSink(): S;
+    /** Raw-`Instr` escape hatch for op families not yet routed through the trait. */
+    pushRaw(out: S, instr: Instr): void;
+    /**
+     * vec ref on stack -> i32 length. The caller appends `f64.convert_i32_s`
+     * when the IR result type is f64 (that is an IR-result-type coercion, not
+     * a backend op, so it stays in lower.ts).
+     */
+    emitVecLen(layout: VecLayout, out: S): void;
+    /**
+     * vec ref on stack -> data-region handle. WasmGC leaves a `(ref $arr)`;
+     * a linear backend would leave an `i32` base pointer. Both feed
+     * `emitElemGet`, which closes the abstraction so `lower.ts` never reasons
+     * about what is on the stack between the two calls.
+     */
+    emitVecDataPtr(layout: VecLayout, out: S): void;
+    /** data-region handle + i32 index on stack -> element value. */
+    emitElemGet(layout: VecLayout, out: S): void;
+    /**
+     * #1804 — N element values on the stack (e0 deepest … eN top) -> a fully
+     * built vec ref. WasmGC: `array.new_fixed $arr N`, stash the data ref in
+     * `dataScratchLocal`, push `i32.const N` (length, field 0), re-load the data
+     * ref (field 1), `struct.new $vec`. Linear: bump-allocate
+     * `[header][len=N][cap=N][e0…eN]` and leave the base i32 (or `notImplemented`).
+     * `dataScratchLocal` is a function-local index of the array's ValType,
+     * allocated lazily by `lower.ts`.
+     */
+    emitVecNewFixed(layout: VecLayout, count: number, dataScratchLocal: number, out: S): void;
+    /** Emit a `const` IR instr's literal op(s). Delegates to the shared free fn. */
+    emitConst(instr: Extract<IrInstr, {
+        kind: "const";
+    }>, funcName: string, out: S): void;
+    /** Pass-through binary op (`f64.add`, `i32.eq`, `i32.and`, ...). Bitwise
+     * `js.*` ops are lowered earlier in lower.ts and never reach here. */
+    emitBinary(op: IrBinop, out: S): void;
+    /** Pass-through unary op. */
+    emitUnary(op: IrUnop, out: S): void;
+    emitLocalGet(index: number, out: S): void;
+    emitLocalSet(index: number, out: S): void;
+    emitLocalTee(index: number, out: S): void;
+    emitGlobalGet(index: number, out: S): void;
+    emitGlobalSet(index: number, out: S): void;
+    emitDrop(out: S): void;
+    emitSelect(out: S): void;
+    emitReturn(out: S): void;
+    emitUnreachable(out: S): void;
+    /** Structured if. then/else are already lowered into their own sink. */
+    emitIf(blockType: BlockType, then: S, els: S, out: S): void;
+    emitBr(depth: number, out: S): void;
+    emitBrIf(depth: number, out: S): void;
+    /** Wrap `body` in a structured block; `body` was built via `newSink()`. */
+    emitBlock(blockType: BlockType, body: S, out: S): void;
+    /** Wrap `body` in a structured loop; `body` was built via `newSink()`. */
+    emitLoop(blockType: BlockType, body: S, out: S): void;
+    emitBox?(layout: IrUnionLowering, out: Instr[]): void;
+    emitUnbox?(layout: IrUnionLowering, out: Instr[]): void;
+    emitTagLoad?(layout: IrUnionLowering, out: Instr[]): void;
+    emitNull?(irType: IrType, out: Instr[]): void;
+    emitToExternref?(out: Instr[]): void;
+    emitFromExternref?(layout: {
+        typeIdx: number;
+    } | IrType, out: Instr[]): void;
+    emitFuncRef?(funcIdx: number, out: Instr[]): void;
+    emitClosureNew?(layout: IrClosureLowering, captureCount: number, out: Instr[]): void;
+    emitClosureFuncGet?(layout: IrClosureLowering, out: Instr[]): void;
+    emitCaptureGet?(layout: IrClosureLowering, index: number, out: Instr[]): void;
+    emitRefCellNew?(layout: IrRefCellLowering, out: Instr[]): void;
+    emitRefCellGet?(layout: IrRefCellLowering, out: Instr[]): void;
+    emitRefCellSet?(layout: IrRefCellLowering, out: Instr[]): void;
+    /** Direct call to compiled function `funcIdx`. Args already on the stack. */
+    emitCall(funcIdx: number, out: S): void;
+    /** Indirect call through a typed funcref already on the stack. */
+    emitCallRef(funcTypeIdx: number, out: S): void;
+    /** Allocate an aggregate from `fieldCount` values already on the stack
+     * (canonical field order, field0 deepest); leaves the new struct ref. */
+    emitAggregateNew(layout: IrObjectStructLowering, fieldCount: number, out: S): void;
+    /** struct ref on stack -> the named field's value. */
+    emitFieldGet(layout: IrObjectStructLowering | IrClassLowering, name: string, out: S): void;
+    /** struct ref + value on stack -> writes the named field (void). */
+    emitFieldSet(layout: IrObjectStructLowering | IrClassLowering, name: string, out: S): void;
+    /** Throw the exception value already on the stack via the `__exn` tag. */
+    emitThrow(tagIdx: number, out: S): void;
+    /** Re-throw the currently-caught exception (`depth` levels out; lower.ts
+     * only emits depth 0 today). */
+    emitRethrow(depth: number, out: S): void;
+    /** Structured try. `body` / each catch `body` / `catchAll` are pre-lowered
+     * into their own sinks (built via `newSink()`). `catches[i].tagIdx` selects
+     * the handler by exception tag. */
+    emitTry(blockType: BlockType, body: S, catches: {
+        tagIdx: number;
+        body: S;
+    }[], catchAll: S | undefined, out: S): void;
+}
+export {};

package/dist/ir/backend/handles.d.ts

@@ -0,0 +1,133 @@
+import { ValType } from '../types.js';
+/**
+ * Information about a tagged-union struct type emitted into the WasmGC module.
+ * See `passes/tagged-union-types.ts` for the registry that produces these.
+ */
+export interface IrUnionLowering {
+    /** WasmGC type index of the `$union_<members>` struct. */
+    readonly typeIdx: number;
+    /** Field index of the `$tag` i32 discriminator. */
+    readonly tagFieldIdx: number;
+    /** Field index of the `$val` field carrying the member scalar. */
+    readonly valFieldIdx: number;
+    /** Canonical tag value (i32 constant) for each ValType kind. */
+    tagFor(member: ValType): number;
+}
+/**
+ * Information about a heap-allocated scalar box -- see
+ * `IrType { kind: "boxed", inner }`. Resolved lazily by the lowering pass.
+ */
+export interface IrBoxedLowering {
+    /** WasmGC type index of the `$box_<inner>` struct. */
+    readonly typeIdx: number;
+    /** Field index of the inner `$val`. */
+    readonly valFieldIdx: number;
+}
+/**
+ * Information about a registered WasmGC struct that backs an
+ * `IrType.object` shape. The resolver memoizes one of these per shape.
+ *
+ * `fieldIdx(name)` returns the WasmGC struct's field index for the given
+ * shape field name (in the shape's canonical order). It throws when the
+ * name is not a member of the shape -- the lowerer catches via the
+ * surrounding try/catch and emits a clean fall-back error.
+ */
+export interface IrObjectStructLowering {
+    /** WasmGC type index of the registered struct. */
+    readonly typeIdx: number;
+    /** Field index for each field name in the shape's canonical order. */
+    fieldIdx(name: string): number;
+}
+/**
+ * Slice 3 (#1169c): WasmGC type info for a closure value. Two structs
+ * are involved per closure construction site:
+ *   - The SUPERTYPE struct (`structTypeIdx`): contains only the funcref
+ *     field. Carried by the IrType.closure ValType so all closures
+ *     sharing a signature have the same Wasm-level type.
+ *   - The SUBTYPE struct (resolved via `resolveClosureSubtype`): adds
+ *     the capture fields. Constructed at the closure's creation site
+ *     (`struct.new <subtype>`) and `ref.cast`-ed inside the lifted
+ *     body to read captures.
+ *
+ * `funcTypeIdx` is the lifted function's Wasm func type
+ * `(ref $base, ...sig.params) -> sig.returnType` -- used by `call_ref`
+ * at the call site.
+ */
+export interface IrClosureLowering {
+    readonly structTypeIdx: number;
+    readonly funcFieldIdx: number;
+    /** Field index for capture position `i` (0-based). Valid only for subtype lowerings. */
+    capFieldIdx(index: number): number;
+    readonly funcTypeIdx: number;
+}
+/**
+ * Slice 3 (#1169c): WasmGC type info for a ref cell over a primitive
+ * value type. Single-field struct `(struct (field $value (mut T)))`.
+ */
+export interface IrRefCellLowering {
+    readonly typeIdx: number;
+    readonly fieldIdx: number;
+}
+/**
+ * Slice 6 (#1169e): WasmGC type info for a vec struct (the runtime layout
+ * for `Array<T>` / tuple types). The struct is `{ length: i32, data: (ref
+ * $arr) }` where `$arr` is the element array type. This interface is the
+ * lowerer's contract for emitting `vec.len` and `vec.get` against a known
+ * vec value's IrType.
+ *
+ *   - `vecStructTypeIdx`   Wasm struct type index of the vec.
+ *   - `lengthFieldIdx`     field index of the i32 length (typically 0).
+ *   - `dataFieldIdx`       field index of the data array ref (typically 1).
+ *   - `arrayTypeIdx`       Wasm array type index of the data array.
+ *   - `elementValType`     element ValType -- used by `vec.get` to lower
+ *                           the result and (recursively, via the resolver)
+ *                           to widen the element to the loop variable's
+ *                           declared type when needed.
+ */
+export interface IrVecLowering {
+    readonly vecStructTypeIdx: number;
+    readonly lengthFieldIdx: number;
+    readonly dataFieldIdx: number;
+    readonly arrayTypeIdx: number;
+    readonly elementValType: ValType;
+}
+/**
+ * Slice 4 (#1169d): WasmGC type info for a class declared in the
+ * compilation unit. The class's struct + constructor + method funcs
+ * are all registered by the legacy `collectClassDeclaration` pass before
+ * the IR runs; this interface just exposes them by name.
+ *
+ *   - `structTypeIdx`        Wasm struct type index for the class
+ *   - `fieldIdx(name)`       Wasm struct field index for a user field name
+ *                             (the legacy `__tag` prefix at field 0 is
+ *                             accounted for here so the IR doesn't need to
+ *                             reason about it).
+ *   - `constructorFuncName`  legacy-registered name of the constructor
+ *                             function (`<className>_new`); the resolver's
+ *                             `resolveFunc` maps it to the funcIdx.
+ *   - `methodFuncName(name)` legacy-registered name of an instance method
+ *                             (`<className>_<methodName>`); the resolver's
+ *                             `resolveFunc` maps it to the funcIdx.
+ */
+export interface IrClassLowering {
+    readonly structTypeIdx: number;
+    fieldIdx(name: string): number;
+    readonly constructorFuncName: string;
+    methodFuncName(name: string): string;
+}
+/**
+ * #1714: linear-memory layout handle for a vec (array). Sibling to
+ * {@link IrVecLowering} (the WasmGC handle). The linear backend stores an
+ * array as a base `i32` pointer to `[header 8B][len:u32 @+8][cap:u32
+ * @+12][elements @+16…]` (see `src/codegen-linear/runtime.ts:339`), so the
+ * only representation detail the emitter needs is the element ValType (for
+ * stride + load op). Field offsets are fixed by the layout, not per-instance.
+ *
+ * This is the "different handle shape the linear resolver returns" that the
+ * #1713 spec §7 anticipated. The `BackendEmitter` vec methods accept
+ * `IrVecLowering | LinearVecLowering`; each emitter narrows to its own shape.
+ */
+export interface LinearVecLowering {
+    /** Element ValType — drives stride (4 vs 8) and the load op. */
+    readonly elementValType: ValType;
+}

package/dist/ir/backend/legality.d.ts

@@ -0,0 +1,9 @@
+import { IrFunction } from '../nodes.js';
+export type IrBackendKind = "wasmgc" | "linear" | "bytecode";
+export interface IrBackendLegalityError {
+    readonly message: string;
+    readonly func: string;
+    readonly block?: number;
+    readonly instr?: string;
+}
+export declare function verifyIrBackendLegality(func: IrFunction, backend: IrBackendKind): IrBackendLegalityError[];

package/dist/ir/backend/linear-emitter.d.ts

@@ -0,0 +1,41 @@
+import { Instr } from '../types.js';
+import { BackendEmitter } from './emitter.js';
+import { LinearVecLowering } from './handles.js';
+/**
+ * #1714: a BackendEmitter that lowers the vec primitives to LINEAR memory.
+ * Only the three vec methods are implemented; the rest fail loudly.
+ */
+export declare class LinearEmitter implements BackendEmitter<Instr[]> {
+    readonly backend: "linear";
+    newSink(): Instr[];
+    pushRaw(out: Instr[], instr: Instr): void;
+    emitVecLen(layout: LinearVecLowering, out: Instr[]): void;
+    emitVecDataPtr(layout: LinearVecLowering, out: Instr[]): void;
+    emitElemGet(layout: LinearVecLowering, out: Instr[]): void;
+    emitVecNewFixed(): void;
+    emitConst(): void;
+    emitBinary(): void;
+    emitUnary(): void;
+    emitLocalGet(): void;
+    emitLocalSet(): void;
+    emitLocalTee(): void;
+    emitGlobalGet(): void;
+    emitGlobalSet(): void;
+    emitDrop(): void;
+    emitSelect(): void;
+    emitReturn(): void;
+    emitUnreachable(): void;
+    emitIf(): void;
+    emitBr(): void;
+    emitBrIf(): void;
+    emitBlock(): void;
+    emitLoop(): void;
+    emitThrow(): void;
+    emitRethrow(): void;
+    emitTry(): void;
+    emitAggregateNew(): void;
+    emitFieldGet(): void;
+    emitFieldSet(): void;
+    emitCall(): void;
+    emitCallRef(): void;
+}

package/dist/ir/backend/wasmgc-emitter.d.ts

@@ -0,0 +1,43 @@
+import { IrBinop, IrInstr, IrUnop } from '../nodes.js';
+import { BlockType, Instr } from '../types.js';
+import { BackendEmitter } from './emitter.js';
+import { IrClassLowering, IrObjectStructLowering, IrVecLowering } from './handles.js';
+export declare class WasmGcEmitter implements BackendEmitter<Instr[]> {
+    readonly backend: "wasmgc";
+    newSink(): Instr[];
+    pushRaw(out: Instr[], instr: Instr): void;
+    emitVecLen(layout: IrVecLowering, out: Instr[]): void;
+    emitVecDataPtr(layout: IrVecLowering, out: Instr[]): void;
+    emitElemGet(layout: IrVecLowering, out: Instr[]): void;
+    emitVecNewFixed(layout: IrVecLowering, count: number, dataScratchLocal: number, out: Instr[]): void;
+    emitConst(instr: Extract<IrInstr, {
+        kind: "const";
+    }>, funcName: string, out: Instr[]): void;
+    emitBinary(op: IrBinop, out: Instr[]): void;
+    emitUnary(op: IrUnop, out: Instr[]): void;
+    emitLocalGet(index: number, out: Instr[]): void;
+    emitLocalSet(index: number, out: Instr[]): void;
+    emitLocalTee(index: number, out: Instr[]): void;
+    emitGlobalGet(index: number, out: Instr[]): void;
+    emitGlobalSet(index: number, out: Instr[]): void;
+    emitDrop(out: Instr[]): void;
+    emitSelect(out: Instr[]): void;
+    emitReturn(out: Instr[]): void;
+    emitUnreachable(out: Instr[]): void;
+    emitIf(blockType: BlockType, then: Instr[], els: Instr[], out: Instr[]): void;
+    emitBr(depth: number, out: Instr[]): void;
+    emitBrIf(depth: number, out: Instr[]): void;
+    emitBlock(blockType: BlockType, body: Instr[], out: Instr[]): void;
+    emitLoop(blockType: BlockType, body: Instr[], out: Instr[]): void;
+    emitCall(funcIdx: number, out: Instr[]): void;
+    emitCallRef(funcTypeIdx: number, out: Instr[]): void;
+    emitAggregateNew(layout: IrObjectStructLowering, _fieldCount: number, out: Instr[]): void;
+    emitFieldGet(layout: IrObjectStructLowering | IrClassLowering, name: string, out: Instr[]): void;
+    emitFieldSet(layout: IrObjectStructLowering | IrClassLowering, name: string, out: Instr[]): void;
+    emitThrow(tagIdx: number, out: Instr[]): void;
+    emitRethrow(depth: number, out: Instr[]): void;
+    emitTry(blockType: BlockType, body: Instr[], catches: {
+        tagIdx: number;
+        body: Instr[];
+    }[], catchAll: Instr[] | undefined, out: Instr[]): void;
+}