@loopdive/js2 0.57.0

package/dist/ir/alloc-registry.d.ts

@@ -0,0 +1,75 @@
+import { AllocKind, AllocSiteId, IrSiteId, IrType } from './nodes.js';
+/**
+ * A live allocation site. `metadata` is stored out-of-band in the registry
+ * (keyed by id + namespace), not on this record, so analyses can annotate
+ * without mutating the IR.
+ */
+export interface AllocSite {
+    readonly id: AllocSiteId;
+    readonly kind: AllocKind;
+    readonly type: IrType;
+    /** Reuses the defining instr's source location, when present. */
+    readonly origin?: IrSiteId;
+}
+/**
+ * Reserved metadata namespaces. Each analysis owns exactly one and may not
+ * write to another's. Enforced by convention in this issue (#1586); the ADR
+ * documents the ownership table.
+ */
+export declare const ALLOC_NAMESPACES: {
+    /** #1587 — ownership and access-semantics analysis. */
+    readonly ownership: "ownership";
+    /** #1588 — string encoding tracking. */
+    readonly encoding: "encoding";
+    /** #1585 — dual-target IR / lifetime analysis. */
+    readonly lifetime: "lifetime";
+    /** Closure-capture escape analysis (#747). */
+    readonly escape: "escape";
+};
+/**
+ * Module-global allocation-site registry. One per `IrModule` compile, threaded
+ * through every pass invocation (see integration.ts). Not a per-function
+ * singleton — inlining merges functions, so ids must be module-stable.
+ */
+export declare class AllocSiteRegistry {
+    /** index === AllocSiteId. */
+    private readonly sites;
+    /** metadata[id] = Map<namespace, value>. Sparse — created lazily. */
+    private readonly meta;
+    /** Mint a fresh, live allocation-site id. */
+    fresh(kind: AllocKind, type: IrType, origin?: IrSiteId): AllocSiteId;
+    /** True iff `id` indexes a known site (any state). */
+    isKnown(id: AllocSiteId): boolean;
+    /**
+     * Resolve through alias chains to the canonical live site, or `null` if the
+     * id is unknown, retired, or its chain terminates in a non-live entry. The
+     * `seen` guard makes a malformed cycle resolve to `null` rather than loop.
+     */
+    resolve(id: AllocSiteId): AllocSite | null;
+    /**
+     * Resolve `id` to the index of its canonical entry (following alias chains),
+     * or `null` on a broken/cyclic/unknown chain. Used internally so metadata
+     * writes after fusion land on the canonical site.
+     */
+    private canonicalIndex;
+    /**
+     * Record that `from` was fused into `to` (rule 2 — alias). Any metadata on
+     * `from` is merged onto the canonical site `to` (existing keys on `to` win,
+     * so a deliberate annotation is never clobbered by a fused-in default).
+     * No-op if either id is unknown.
+     */
+    alias(from: AllocSiteId, to: AllocSiteId): void;
+    /** Mark an allocation dead and removed (rule 3 — retire). No-op if unknown. */
+    retire(id: AllocSiteId): void;
+    /**
+     * Attach `value` under `ns` to the canonical site behind `id`. No-op if the
+     * id resolves to nothing live (retired/unknown/broken chain).
+     */
+    annotate<T>(id: AllocSiteId, ns: string, value: T): void;
+    /** Read the `ns` annotation on the canonical site behind `id`. */
+    read<T>(id: AllocSiteId, ns: string): T | undefined;
+    /** Number of sites ever minted (including aliased/retired). For diagnostics. */
+    get size(): number;
+    /** Snapshot of live sites — for debugging / tooling, not hot paths. */
+    liveSites(): AllocSite[];
+}

package/dist/ir/analysis/encoding.d.ts

@@ -0,0 +1,38 @@
+import { AllocSiteRegistry } from '../alloc-registry.js';
+import { IrFunction } from '../nodes.js';
+/**
+ * Encoding lattice. Ordering (most → least restrictive):
+ *   ascii  ⊑  utf8-guaranteed  ⊑  wtf16
+ * `wtf16` is top (the conservative default); `ascii` is bottom (the
+ * strongest claim). The join of two encodings is their least upper bound:
+ * any operand being `wtf16` forces `wtf16`; otherwise `utf8-guaranteed`
+ * unless both are `ascii`.
+ */
+export type Encoding = "ascii" | "utf8-guaranteed" | "wtf16";
+/** Least upper bound of two encodings (the conservative join). */
+export declare function joinEncoding(a: Encoding, b: Encoding): Encoding;
+/**
+ * Classify a statically known string literal by its code units.
+ *   - all code units ≤ 0x7F           → `ascii`
+ *   - else, no lone surrogates        → `utf8-guaranteed`
+ *   - else (a lone surrogate present) → `wtf16`
+ *
+ * A surrogate is lone when a high surrogate (0xD800–0xDBFF) is not
+ * immediately followed by a low surrogate (0xDC00–0xDFFF), or a low
+ * surrogate appears without a preceding high surrogate. Such a string
+ * cannot be encoded as UTF-8, so it must stay `wtf16`.
+ */
+export declare function classifyLiteral(value: string): Encoding;
+/**
+ * Run the encoding analysis over a single IR function, writing `encoding`
+ * annotations onto the string allocation sites in `registry`. Read-only on
+ * the IR. Idempotent: re-running overwrites the same annotations with the
+ * same values.
+ *
+ * The analysis is a single forward pass. SSA dominance guarantees each
+ * value is defined before use within a block, and string values in Phase 1
+ * are produced and consumed locally (literals + concat), so a per-function
+ * value→encoding map filled in instruction order is sufficient. Values with
+ * no tracked origin are absent from the map and treated as `wtf16`.
+ */
+export declare function analyzeEncoding(fn: IrFunction, registry: AllocSiteRegistry): void;

package/dist/ir/analysis/escape.d.ts

@@ -0,0 +1,32 @@
+import { AllocSiteRegistry } from '../alloc-registry.js';
+import { IrFunction, IrValueId } from '../nodes.js';
+import { OwnershipResult } from './ownership.js';
+/**
+ * How an allocation escapes its defining function. Ordered most-precise →
+ * most-conservative; `local` is the only stack-allocatable classification.
+ */
+export type EscapeClass = "local" | "returned" | "stored" | "captured" | "opaque";
+export interface EscapeInfo {
+    readonly classification: EscapeClass;
+    /** True iff `classification === "local"` — safe for scalar replacement. */
+    readonly stackAllocatable: boolean;
+}
+/** Per-function escape-analysis result, keyed by allocation result value. */
+export declare class EscapeResult {
+    private readonly infos;
+    constructor(infos: ReadonlyMap<IrValueId, EscapeInfo>);
+    /** Escape info for an allocation value, or `undefined` if it is not an alloc. */
+    of(value: IrValueId): EscapeInfo | undefined;
+    classOf(value: IrValueId): EscapeClass | undefined;
+    /** Allocation values proven `local` — the stack-allocation candidates. */
+    localAllocations(): IrValueId[];
+    entries(): Iterable<[IrValueId, EscapeInfo]>;
+}
+/**
+ * Run escape analysis on `fn`. Uses the #1587 ownership result (computed fresh
+ * when not supplied) as the escape oracle, then walks the IR to attribute the
+ * strongest escape edge per allocation. When `registry` is supplied, each
+ * allocation's classification is written under the `escape` namespace keyed by
+ * the defining instr's alloc id.
+ */
+export declare function analyzeEscape(fn: IrFunction, registry?: AllocSiteRegistry, precomputedOwnership?: OwnershipResult): EscapeResult;

package/dist/ir/analysis/lattice.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Ownership state — a totally ordered lattice from most-precise (`owned`) to
+ * most-permissive (`escaped`). Higher = more conservative = safer default.
+ *
+ *   owned  ⊑ borrowed ⊑ shared ⊑ escaped
+ *
+ * - `owned`    — exactly one live reference (this one) for its liveness.
+ * - `borrowed` — referenced elsewhere; this ref must not deallocate/invalidate.
+ * - `shared`   — multiple references; mutation must be observable to all.
+ * - `escaped`  — lifetime extends beyond this function (return, capture,
+ *                store-to-heap, pass to opaque code).
+ */
+export type Ownership = "owned" | "borrowed" | "shared" | "escaped";
+/** Bottom of the ownership lattice — the most precise classification. */
+export declare const OWNERSHIP_BOTTOM: Ownership;
+/** Top of the ownership lattice — the conservative default. */
+export declare const OWNERSHIP_TOP: Ownership;
+/**
+ * Join (least upper bound) of two ownership states. Used at control-flow merge
+ * points and whenever an operation widens a value's classification: the result
+ * is the *more conservative* of the two. Commutative, associative, idempotent.
+ */
+export declare function joinOwnership(a: Ownership, b: Ownership): Ownership;
+/** True iff `a` is at least as precise as `b` (`a ⊑ b`). */
+export declare function ownershipLeq(a: Ownership, b: Ownership): boolean;
+/**
+ * Access operation — how a reference is used. The access lattice is the
+ * powerset of these tags ordered by ⊆; join is set union, bottom is `{}`, top
+ * is the full set. A value that escapes to opaque code conservatively widens
+ * to the full set (the callee may do anything).
+ */
+export type AccessOp = "read" | "write" | "mutate" | "identity" | "escape";
+/**
+ * An access set — a small immutable wrapper over `Set<AccessOp>` with union
+ * (join) and subset (⊑) operations. Kept as a class so the query API can hand
+ * consumers a value they cannot accidentally mutate.
+ */
+export declare class AccessSet {
+    private readonly ops;
+    private constructor();
+    /** Bottom — no observed access. */
+    static empty(): AccessSet;
+    /** Top — the conservative full access set. */
+    static full(): AccessSet;
+    static of(...ops: readonly AccessOp[]): AccessSet;
+    has(op: AccessOp): boolean;
+    /** Join — set union. Returns `this` unchanged when `op` is already present. */
+    with(op: AccessOp): AccessSet;
+    /** Join — set union of two access sets. */
+    union(other: AccessSet): AccessSet;
+    /** True iff `this ⊆ other`. */
+    subsetOf(other: AccessSet): boolean;
+    equals(other: AccessSet): boolean;
+    /** Stable, sorted array view — for annotations, tests, and diagnostics. */
+    toArray(): AccessOp[];
+}
+/**
+ * The full classification the analysis attaches to a value. This is the shape
+ * stored in the registry `ownership` namespace and the parallel `ValueAnnot`
+ * map. Consumers must treat it as the analysis's *tightest provable* result
+ * and fall back to their conservative path when it is not tight enough — they
+ * may never assume a tighter classification than this carries (ADR-0014).
+ */
+export interface OwnershipAnnotation {
+    readonly ownership: Ownership;
+    readonly access: AccessSet;
+}
+/** The conservative TOP annotation — used for anything not provably tighter. */
+export declare function topAnnotation(): OwnershipAnnotation;
+/** Join two annotations component-wise (used at CFG merges). */
+export declare function joinAnnotations(a: OwnershipAnnotation, b: OwnershipAnnotation): OwnershipAnnotation;
+export declare function annotationsEqual(a: OwnershipAnnotation, b: OwnershipAnnotation): boolean;

package/dist/ir/analysis/ownership.d.ts

@@ -0,0 +1,31 @@
+import { AllocSiteRegistry } from '../alloc-registry.js';
+import { IrFunction, IrValueId } from '../nodes.js';
+import { AccessSet, OwnershipAnnotation, Ownership } from './lattice.js';
+/**
+ * The analysis result for one function. `of` returns the inferred annotation
+ * for any value; values the analysis never saw resolve to the conservative
+ * TOP, so consumers always get a correctness-preserving answer.
+ */
+export declare class OwnershipResult {
+    private readonly annots;
+    /** Value -> the alloc id of the instr that defined it, when allocated. */
+    private readonly allocOf;
+    constructor(annots: ReadonlyMap<IrValueId, OwnershipAnnotation>, 
+    /** Value -> the alloc id of the instr that defined it, when allocated. */
+    allocOf: ReadonlyMap<IrValueId, number>);
+    /** Inferred annotation for `value` — TOP if the value was never classified. */
+    of(value: IrValueId): OwnershipAnnotation;
+    ownershipOf(value: IrValueId): Ownership;
+    accessOf(value: IrValueId): AccessSet;
+    /** True iff `value` is a heap allocation proven `owned` and never `escaped`. */
+    isStackAllocatable(value: IrValueId): boolean;
+    /** All classified values — for diagnostics / tests. */
+    entries(): Iterable<[IrValueId, OwnershipAnnotation]>;
+}
+/**
+ * Run the analysis on `fn`. When `registry` is supplied, the result for each
+ * allocated value is also written under the `ownership` namespace keyed by the
+ * defining instr's alloc id (the durable cross-pass channel). The returned
+ * `OwnershipResult` is the in-function view keyed by `IrValueId`.
+ */
+export declare function analyzeOwnership(fn: IrFunction, registry?: AllocSiteRegistry): OwnershipResult;

package/dist/ir/analysis/stack-alloc.d.ts

@@ -0,0 +1,20 @@
+import { AllocSiteRegistry } from '../alloc-registry.js';
+import { AllocKind, IrFunction } from '../nodes.js';
+import { OwnershipResult } from './ownership.js';
+/** A value-creating instr the analysis proved safe to stack-allocate. */
+export interface StackAllocCandidate {
+    readonly allocId: number;
+    readonly kind: AllocKind;
+}
+/**
+ * Find stack-allocation candidates in `fn` using an ownership result (computed
+ * fresh when not supplied). A candidate is an allocation that is:
+ *   - of a "small" kind (object / refcell / box — not array/closure/string),
+ *   - proven `owned`, and
+ *   - never `escaped`.
+ *
+ * When `registry` is supplied, each candidate's site is marked with a
+ * `stackCandidate: true` flag merged into its existing ownership annotation.
+ * The marker is inert at lowering — it changes no emitted Wasm.
+ */
+export declare function findStackAllocCandidates(fn: IrFunction, registry?: AllocSiteRegistry, precomputed?: OwnershipResult): StackAllocCandidate[];

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

@@ -0,0 +1,237 @@
+import { IrBinop, IrInstr, IrUnop } from '../nodes.js';
+import { BlockType, Instr } from '../types.js';
+import { BackendEmitter } from './emitter.js';
+import { IrClassLowering, IrObjectStructLowering } from './handles.js';
+export declare const OP: {
+    readonly CONST: 0;
+    readonly LOAD: 1;
+    readonly STORE: 2;
+    readonly ADD: 3;
+    readonly SUB: 4;
+    readonly MUL: 5;
+    readonly CMP_GT: 6;
+    readonly CMP_LT: 7;
+    readonly CMP_GE: 8;
+    readonly CMP_LE: 9;
+    readonly CMP_EQ: 10;
+    readonly NEG: 11;
+    readonly JZ: 12;
+    readonly JMP: 13;
+    readonly RET: 14;
+    readonly DIV: 15;
+    readonly CMP_NE: 16;
+    readonly TEE: 17;
+    readonly GLOBAL_GET: 18;
+    readonly GLOBAL_SET: 19;
+    readonly SELECT: 20;
+    readonly DROP: 21;
+    readonly UNREACHABLE: 22;
+    readonly CALL: 23;
+    readonly CALL_REF: 24;
+    readonly STRUCT_NEW: 25;
+    readonly STRUCT_GET: 26;
+    readonly STRUCT_SET: 27;
+    readonly JNZ: 28;
+    readonly THROW: 29;
+    readonly TRY_START: 30;
+    readonly TRY_END: 31;
+};
+export type Opcode = (typeof OP)[keyof typeof OP];
+/**
+ * The bytecode equivalent of `BackendEmitter`'s `Instr[]` sink — the ONE seam
+ * generalisation #1715 required. A flat `code` opcode stream plus a side
+ * constant pool for f64 immediates. A label backpatch list lets `emitIf`
+ * forward-reference jump targets it does not yet know.
+ */
+export declare class BytecodeSink {
+    readonly code: number[];
+    readonly constPool: number[];
+    /**
+     * (a3 #1584) Structured-branch backpatch list. A `br` / `br_if` (`emitBr` /
+     * `emitBrIf`) emits a `JMP` / `JNZ` placeholder whose target is the construct
+     * `depth` levels out (De Bruijn) — UNKNOWN until the enclosing `block`/`loop`
+     * splices this sink. Each entry pins the operand slot + its outward depth.
+     * `emitBlock`/`emitLoop` resolve depth-0 entries (this construct) and carry
+     * deeper ones outward (depth-1). A sink with a non-empty list at function exit
+     * is an internal error (a `br` with no enclosing construct).
+     */
+    readonly pendingBranches: {
+        slot: number;
+        depth: number;
+    }[];
+    /**
+     * (a4 #1584) Per-function exception table (table-scan model, §1c). One entry
+     * per `try` region: the protected code range `[tryStart, tryEnd)` (absolute
+     * code indices), the `catchTarget` THROW jumps to on a covered throw, and
+     * `spAtEntry` — the value-stack depth to truncate to on catch (always 0: a
+     * `try` is a statement-level node lowered at empty operand-stack depth).
+     * The VM scans this for the innermost covering entry on THROW; TRY_START/
+     * TRY_END are runtime no-ops (the table is authoritative). Travels with the
+     * function on its FuncEntry, alongside `code`/`constPool`.
+     */
+    readonly exceptionTable: {
+        tryStart: number;
+        tryEnd: number;
+        catchTarget: number;
+        spAtEntry: number;
+    }[];
+    /** Intern an f64 immediate into the constant pool, returning its index. */
+    internConst(value: number): number;
+    /** Current write position (a jump target / patch site is a code index). */
+    here(): number;
+    /** Emit an opcode followed by zero or more inline integer operands. */
+    emit(op: Opcode, ...operands: number[]): void;
+    /**
+     * Emit a jump whose target is not yet known; returns the code index of the
+     * *operand slot* to backpatch once the target is known.
+     */
+    emitJumpPlaceholder(op: typeof OP.JZ | typeof OP.JMP | typeof OP.JNZ | typeof OP.TRY_START): number;
+    /** Fill a previously-reserved jump operand slot with the resolved target. */
+    patch(slot: number, target: number): void;
+    /**
+     * (a3 #1584) Record a structured branch (`br`/`br_if`) whose target is the
+     * construct `depth` levels out. The placeholder jump was just emitted; `slot`
+     * is its operand index. Resolved by the enclosing `emitBlock`/`emitLoop`.
+     */
+    recordPendingBranch(slot: number, depth: number): void;
+    /**
+     * #1584: append another sink's code at the current position, relocating its
+     * internal jump targets into this sink's address space and remapping its
+     * const-pool indices into this sink's pool. Used by the production
+     * `BytecodeEmitter.emitIf` to splice already-lowered `if`-arm buffers (the
+     * real `lower.ts` builds each arm into its own sink, exactly as it builds the
+     * WasmGC `if`'s `then`/`else` as separate `Instr[]`).
+     *
+     * (a3) An arm may carry UNPATCHED structured branches (`br`/`br_if` in
+     * `pendingBranches`) bound for an enclosing `block`/`loop`. Those slots
+     * relocate by `+base` and their depth-tagged entries migrate onto THIS sink's
+     * `pendingBranches` so the enclosing construct can resolve them. A leftover
+     * unpatched jump that is NOT a recorded structured branch is still an internal
+     * error (a forward `if`/`block` exit the owner forgot to patch).
+     */
+    spliceArm(arm: BytecodeSink): void;
+}
+/**
+ * #1584 PRODUCTION emitter. Implements the {@link BackendEmitter}<{@link
+ * BytecodeSink}> trait surface so the REAL `lower.ts` drives it identically to
+ * how it drives {@link WasmGcEmitter}<Instr[]> — same primitive set, same
+ * caller-owns-operand-order contract, different execution model. (This
+ * supersedes the #1715 proof's hand-driven emitter: the proof's thunked
+ * `emitIf` is replaced by the trait's pre-built-arm `emitIf`, since real
+ * `lower.ts` builds each arm into its own sink then hands them over.)
+ *
+ * STACK encoding for the first increment (contract §1a staging note). The opcode
+ * set lives above (`OP`, the single source of truth the VM imports read-only);
+ * this class only decides which opcode each primitive emits.
+ */
+export declare class BytecodeEmitter implements BackendEmitter<BytecodeSink> {
+    readonly backend: "bytecode";
+    /** Factory for a child sink — used by `lower.ts` to build `if`-arm buffers. */
+    newSink(): BytecodeSink;
+    /**
+     * The raw-`Instr` escape hatch (the #1584 contract §0a-1). `lower.ts` still
+     * has ~119 inline `out.push({op})` sites for op families not yet migrated
+     * behind the trait. On the WasmGC path those append to the `Instr[]`; on the
+     * bytecode path they reach a node family with no opcode realization yet, so
+     * this throws — surfacing the not-yet-migrated boundary loudly rather than
+     * silently mis-lowering. As each op family migrates (§2a), its `lower.ts`
+     * sites move from `pushRaw` to a typed emitter primitive + opcode.
+     */
+    pushRaw(_out: BytecodeSink, instr: Instr): void;
+    emitConst(instr: Extract<IrInstr, {
+        kind: "const";
+    }>, funcName: string, out: BytecodeSink): void;
+    emitBinary(op: IrBinop, out: BytecodeSink): void;
+    emitUnary(op: IrUnop, out: BytecodeSink): void;
+    emitLocalGet(index: number, out: BytecodeSink): void;
+    emitLocalSet(index: number, out: BytecodeSink): void;
+    emitLocalTee(index: number, out: BytecodeSink): void;
+    emitGlobalGet(index: number, out: BytecodeSink): void;
+    emitGlobalSet(index: number, out: BytecodeSink): void;
+    emitDrop(out: BytecodeSink): void;
+    emitSelect(out: BytecodeSink): void;
+    emitReturn(out: BytecodeSink): void;
+    emitUnreachable(out: BytecodeSink): void;
+    /**
+     * Structured two-arm conditional. Mirrors `WasmGcEmitter.emitIf(blockType,
+     * then: Instr[], els: Instr[], out)`: the caller (real `lower.ts`) pre-lowers
+     * each arm into its own {@link BytecodeSink} (via `newSink()`), then hands
+     * them here. The cond value is already on the stack. The stack VM has no
+     * structured block, so we lower to JZ/JMP + spliced arms with backpatched
+     * targets:
+     *
+     *   <cond on stack>
+     *   JZ elseLabel
+     *   <then arm>
+     *   JMP endLabel
+     *   elseLabel: <else arm>
+     *   endLabel:
+     *
+     * `blockType` is ignored (the bytecode VM is untyped over boxed values); it is
+     * part of the trait signature for the WasmGC realization.
+     */
+    emitIf(_blockType: BlockType, then: BytecodeSink, els: BytecodeSink, out: BytecodeSink): void;
+    emitBr(depth: number, out: BytecodeSink): void;
+    emitBrIf(depth: number, out: BytecodeSink): void;
+    /**
+     * Structured `block`. Splices the pre-lowered `body` sink at the current
+     * position, then resolves the body's pending structured branches: a branch
+     * with `depth === 0` targets THIS block, so it jumps to the block's EXIT (the
+     * code position just past the spliced body); deeper branches belong to an
+     * outer construct and migrate outward with `depth - 1`. `blockType` is ignored
+     * (the VM is untyped over boxed values) — it is part of the trait signature
+     * for the WasmGC realization.
+     */
+    emitBlock(_blockType: BlockType, body: BytecodeSink, out: BytecodeSink): void;
+    /**
+     * Structured `loop`. Like `emitBlock`, but a `depth === 0` branch targets the
+     * loop HEADER (the code position where the body begins) — `br 0` is "continue"
+     * — so the back-edge target is captured BEFORE the splice.
+     */
+    emitLoop(_blockType: BlockType, body: BytecodeSink, out: BytecodeSink): void;
+    /**
+     * Resolve the structured branches `spliceArm` just migrated onto `out`
+     * (`out.pendingBranches[firstNew..]`): patch each `depth === 0` branch to
+     * `selfTarget` (block exit / loop header) and drop it; decrement the depth of
+     * each deeper branch so the next-outer construct resolves it. Entries added
+     * before `firstNew` (already-pending outer branches) are untouched.
+     */
+    private resolveSplicedBranches;
+    emitCall(funcIdx: number, out: BytecodeSink): void;
+    emitCallRef(funcTypeIdx: number, out: BytecodeSink): void;
+    emitAggregateNew(_layout: IrObjectStructLowering, fieldCount: number, out: BytecodeSink): void;
+    emitFieldGet(layout: IrObjectStructLowering | IrClassLowering, name: string, out: BytecodeSink): void;
+    emitFieldSet(layout: IrObjectStructLowering | IrClassLowering, name: string, out: BytecodeSink): void;
+    emitThrow(_tagIdx: number, out: BytecodeSink): void;
+    emitRethrow(_depth: number, out: BytecodeSink): void;
+    /**
+     * Structured `try`. Table-scan realization:
+     *
+     *   TRY_START <catchTarget>     ; no-op marker
+     *   <tryBody>
+     *   TRY_END                     ; no-op marker (end of protected region)
+     *   JMP endLabel                ; normal exit skips the handler
+     *   catchTarget: <handler>      ; THROW lands here (VM pushed exn, truncated sp)
+     *   endLabel:
+     *
+     * + an exceptionTable entry {tryStart, tryEnd, catchTarget, spAtEntry:0}.
+     * The protected region is [tryStart, tryEnd) = the spliced tryBody (between the
+     * markers). spAtEntry is 0: `try` is a statement-level node lowered at empty
+     * operand-stack depth, so on catch the VM truncates back to the empty base.
+     *
+     * Handler selection: our system has ONE exception tag (`__exn`), so a thrown
+     * value always matches a source `catch` if present; `catchAll` (emitted for
+     * the finally-leak path) is the handler only when there is no `catch`. With a
+     * single tag, `catchAll`-alongside-`catch` is the unreachable non-`__exn`
+     * leak path — we still splice it after the catch for structural fidelity, but
+     * `catchTarget` points at the live handler.
+     */
+    emitTry(_blockType: BlockType, body: BytecodeSink, catches: {
+        tagIdx: number;
+        body: BytecodeSink;
+    }[], catchAll: BytecodeSink | undefined, out: BytecodeSink): void;
+    emitVecLen(): void;
+    emitVecDataPtr(): void;
+    emitElemGet(): void;
+    emitVecNewFixed(): void;
+}

package/dist/ir/backend/bytecode-vm.d.ts

@@ -0,0 +1,74 @@
+import { BytecodeSink } from './bytecode-emitter.js';
+/**
+ * One entry in a {@link Program}'s function table. A function lowers to its own
+ * {@link BytecodeSink} (own `code` + own `constPool` + own jump address-space),
+ * so a call switches BOTH `code` and `constPool` and the call frame restores
+ * both on return.
+ */
+export interface FuncEntry {
+    /** The function's opcode stream (`sink.code`). */
+    code: number[];
+    /** The function's f64 immediate pool (`sink.constPool`). */
+    constPool: number[];
+    /** Declared parameter count — `CALL` pops this many args (arity not inline). */
+    arity: number;
+    /**
+     * Local-slot count (params + declared locals). A call installs a fresh
+     * `locals[nLocals]` seeded `locals[0..arity-1]` with the popped args; higher
+     * slots are lazily 0-init on first `LOAD` (same contract as `runBytecode`).
+     */
+    nLocals: number;
+    /**
+     * #1584 a4 try-throw: the STATIC per-function exception table (table-scan
+     * model). `THROW` scans it for the innermost entry whose `[tryStart, tryEnd)`
+     * covers the throwing pc, then truncates the value stack to `spAtEntry`, pushes
+     * the exn, and jumps to `catchTarget`. `TRY_START`/`TRY_END` are runtime
+     * no-ops (the table is authoritative). Array-of-objects with number-only
+     * fields (no `readonly`/nested-struct — same js2wasm-codegen accommodation as
+     * the FuncEntry array fields). `spAtEntry` is always 0 today (`try` is a
+     * statement-level node with an empty operand stack at entry), but it travels
+     * in the entry for correctness if a non-statement `try` ever appears.
+     */
+    exceptionTable: ExcEntry[];
+}
+/** One protected region in a {@link FuncEntry}'s {@link FuncEntry.exceptionTable}. */
+export interface ExcEntry {
+    /** Absolute code index of the region start (inclusive). */
+    tryStart: number;
+    /** Absolute code index of the region end (exclusive). */
+    tryEnd: number;
+    /** Absolute code index of the catch arm to jump to on a covered throw. */
+    catchTarget: number;
+    /** Value-stack depth at try-entry; the stack is truncated to this on catch. */
+    spAtEntry: number;
+}
+/**
+ * A whole compiled program: a function table plus the entry function index.
+ * `runProgram` runs `functions[entry]` as the bottom frame.
+ */
+export interface Program {
+    functions: FuncEntry[];
+    entry: number;
+}
+/**
+ * Run a whole {@link Program} — the multi-frame call-stack VM (#1584 a1).
+ *
+ * @param program  function table + entry index
+ * @param args     initial values of the entry function's locals 0..arity-1
+ * @returns the number the entry function's `RET` leaves on the stack
+ */
+export declare function runProgram(program: Program, args: readonly number[]): number;
+/**
+ * Run a single compiled bytecode function (the #1715 numeric proof entry).
+ * Implemented as a one-function {@link Program} so the single- and multi-frame
+ * paths share one dispatch loop.
+ *
+ * @param code      flat opcode + inline-operand stream (`sink.code`)
+ * @param constPool f64 immediates referenced by `OP.CONST <poolIdx>` (`sink.constPool`)
+ * @param args      initial values of locals 0..n-1 (the function parameters);
+ *                  any higher local index used by STORE/LOAD is lazily 0-init.
+ * @returns the number left on the stack by `OP.RET`
+ */
+export declare function runBytecode(code: readonly number[], constPool: readonly number[], args: readonly number[]): number;
+/** Convenience: run a {@link BytecodeSink}'s program as a single function. */
+export declare function runSink(sink: BytecodeSink, args: readonly number[]): number;