@scriptc/compiler 0.1.7 → 0.2.0

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

@@ -1,6 +1,16 @@
-import type { IrModule } from "../../ir/ir.js";
+import type { IrBytesElem, IrExpr, IrFfiImport, IrFunction, IrLocal, IrModule, IrRecordShape, IrStmt, IrType, IrUnionDef, SrcLoc } from "../../ir/ir.js";
+import { type IntegerRanges } from "../../ir/integer-ranges.js";
+import { type ConstantNumericTable } from "../../ir/constant-tables.js";
+import { type FfiCallbackAdapter } from "../ffi-callbacks.js";
+import { BlockBuilder } from "./blocks.js";
+import { type LlClassMeta } from "./classes.js";
+import { LlDyn, type DynHost } from "./dyn.js";
+import { LlWalkers } from "./walkers.js";
+import type { ExprOf, LibCallExpr, LlStreamTypedRefAdapter, LlValue } from "./expr-context.js";
 export { LlvmUnsupportedError } from "./unsupported.js";
 export interface LlvmTargetOptions {
+    /** C ABI target; omitted direct emission uses the host ABI. */
+    targetTriple?: string;
     /** Exact frontend sources for dev-build locations and variable metadata. */
     debugSources?: ReadonlyMap<string, string>;
     /** Pointer width of the target C ABI. Native targets are 64-bit today. */
@@ -15,3 +25,588 @@ export interface LlvmTargetOptions {
     runtimeAbiMarker?: boolean;
 }
 export declare function emitLlvmModule(mod: IrModule, options?: LlvmTargetOptions): string;
+export declare class LlEmitter {
+    readonly mod: IrModule;
+    private readonly debug;
+    private debugScope;
+    readonly sizeType: "i32" | "i64";
+    readonly ffiExtendNarrowIntegers: boolean;
+    readonly cycleColorOffset: number;
+    readonly wasi: boolean;
+    private readonly emitLibraryIdentity;
+    private readonly runtimeAbiMarker;
+    /** Interned string literals: UTF-8 text → { symbol, byte length } —
+     * first-use order, the runtime ABI’s determinism discipline. */
+    private readonly literals;
+    /** Interned unit-armed union instances: "unionId:tag" → symbol — one
+     * immortal (rc == SIZE_MAX) static per (union, unit tag).
+     * RC entry points and the collector skip immortals. */
+    private readonly unitInstances;
+    /** Interned regex literals: "<flags>/<pattern>" → { symbol, interned
+     * source/flags literal refs } — one immortal ScrRegex per distinct
+     * (pattern, flags) pair; the bytecode slot starts null and the runtime
+     * compiles it lazily on first use. The source/flags strings intern at
+     * REGISTRATION (bodies emit before the literal table flushes). */
+    readonly regexInstances: Map<string, {
+        sym: string;
+        src: string;
+        fl: string;
+    }>;
+    /** Interned tagged-template strings objects: per-site key → { symbol,
+     * interned cooked-literal refs }. One immortal ScrArr of string slots
+     * per template SITE (the spec's per-occurrence identity — the C
+     * emitter's templateStringsInstances discipline). */
+    readonly templateStringsInstances: Map<string, {
+        sym: string;
+        slots: string[];
+    }>;
+    /** Interned NUL-terminated C-string constants (scr_jb_puts labels, the
+     * stringify indent text): UTF-8 text → { symbol, byte length }. */
+    private readonly cstrs;
+    /** Type-directed walker functions (JSON serializers, the indent
+     * rewriter, union ToString/join) — interned per typeKey/unionId, defs
+     * flushed with the shape helpers. */
+    readonly walkers: LlWalkers;
+    /** The dyn (ScrDyn dyn) helper registry — dyn.ts's interned ports of
+     * walkers.ts's dyn slice. */
+    readonly dyn: LlDyn;
+    /** Explicit callback boundary for standalone layout and walker stages. */
+    readonly shapeHost: DynHost;
+    /** External declarations, in first-use order. */
+    private readonly decls;
+    /** Declared functions referenced as values: each needs an env-signature
+     * wrapper + an interned immortal closure (so `f === f` holds). */
+    readonly fnValues: Set<string>;
+    private needsOom;
+    needsBadTag: boolean;
+    needsBadKey: boolean;
+    private needsRetainBox;
+    readonly fnByName: Map<string, IrFunction>;
+    /** Manifest-bound native imports, used by ffiCall emission. */
+    readonly ffiByName: Map<string, IrFfiImport>;
+    /** C-ABI callback trampolines and (for raw/no-userdata callbacks) their
+     * distinct call-scoped TLS closure slots. */
+    private readonly ffiCallbackAdapters;
+    /** Module-level constant consulted per ffiCall: with a retained
+     * descriptor anywhere in the manifest, every native call is a
+     * pending-exception checkpoint (may-throw derives the same fact from
+     * the same helper). */
+    readonly ffiHasRetainedCallback: boolean;
+    private readonly ffiHasForeignCallback;
+    private readonly globalTypes;
+    private readonly tdzGlobals;
+    readonly constantNumericTables: ReadonlyMap<string, ConstantNumericTable>;
+    /** May-throw analysis (computeMayThrow): pending
+     * checks are emitted only after calls that can actually raise. */
+    readonly mayThrow: Set<string>;
+    readonly indirectMayThrow: boolean;
+    /** Method names with at least one may-throw implementation — the
+     * virtualCall pending check's key. */
+    readonly mayThrowMethods: Set<string>;
+    /** setTimeout and friends appeared somewhere: main must run the event
+     * loop even in programs with no async functions. */
+    usesTimers: boolean;
+    /** Emitted ref-kind resolve thunks for new Promise, interned per inner
+     * typeKey → thunk symbol. */
+    readonly resolveThunks: Map<string, string>;
+    readonly resolveThunkDefs: string[];
+    /** ReadableStream.from adapters keep typed arrays by reference and box
+     * one current element per pull. */
+    readonly streamFromArrayAdapters: Map<string, string>;
+    /** Identity-preserving static→dyn capsules for program classes and Web
+     * APIs whose values remain directly observable. */
+    readonly liveDynRefAdapters: Map<string, LlStreamTypedRefAdapter>;
+    /** Runtime-arm dispatchers for live union values. */
+    readonly liveDynUnionRefAdapters: Map<string, string>;
+    readonly dynPromiseAdapters: Map<string, string>;
+    readonly unionsById: Map<string, IrUnionDef>;
+    readonly recordsById: Map<string, IrRecordShape>;
+    readonly recordCloneShapes: Set<string>;
+    readonly tracedShapes: Set<string>;
+    readonly tracedUnions: Set<string>;
+    /** The class graph (buildClassGraph): preorder numbering, hierarchy
+     * membership, virtual slot lists. */
+    readonly classMeta: Map<string, LlClassMeta>;
+    /** Class objects (classes as first-class values): className → the
+     * interned .name literal ref — registered during body emission, the
+     * statics and construct thunks assemble around the bodies. */
+    private readonly classObjs;
+    private readonly unionFieldReadGroups;
+    /** Preorder intervals of the runtime error classes under THIS module's
+     * class-forest numbering (main() stamps scr_error_vts with them, exactly
+     * like the runtime ABI’s errorVtStampLines). */
+    private readonly errorIntervals;
+    /** The runtime emitter vtable's preorder interval, when the program
+     * touches node:events (the class def rides the module exactly then) —
+     * main() stamps scr_emitter_vt with it (emitterVtStampLines, ported). */
+    private emitterInterval;
+    /** The runtime stream vtables' preorder intervals (streamVtStampLines,
+     * ported): the defs ride every emitter-touching module (the frontend
+     * collects the whole emitter-rooted tree), and scr_stream.c links on
+     * the same predicate, so the stamps always have their globals. */
+    private readonly streamIntervals;
+    B: BlockBuilder;
+    frames: LlValue[][];
+    private scopes;
+    /** Scope slots dominate every throw site. Share their exceptional cleanup
+     * for identical live bindings and handlers; statement temporaries stay at
+     * their own throw sites because their SSA values are path-dependent. */
+    private readonly unwindCleanups;
+    /** Enclosing break/continue targets. `kind` separates loops from
+     * switches and labeled blocks: an unlabeled break binds to the innermost
+     * NON-BLOCK entry (loop or switch — blocks only enter the stack when
+     * labeled, and only a labeled break can target one); an unlabeled
+     * continue binds to the innermost LOOP; a labeled jump binds to the
+     * entry whose `labels` contains its label. `contLabel` is null exactly
+     * for blocks and switches. */
+    private jumpTargets;
+    private currentLocals;
+    private captureIds;
+    /** Active canonical byte-loop induction bindings: local id → size_t slot. */
+    integerLoopBindings: Map<string, string>;
+    integerRanges: IntegerRanges;
+    /** Enclosing try-with-FINALLY regions, innermost last: a `return`
+     * inside one runs every crossed finally (innermost first) before the
+     * actual ret — the runtime ABI’s pending-return path, with the finally
+     * bodies emitted inline at the return site instead of behind a goto.
+     * `tryDepth` snapshots tryStack.length at region entry: a throw inside
+     * a pending-return finally copy propagates OUT of the completing try
+     * (past its own catch), so the copies emit under the truncated stack.
+     * break/continue use the same region snapshots through
+     * emitFinallysForJump. */
+    private finallyStack;
+    /** Enclosing try contexts, innermost last — the compile-time unwind
+     * targets: a pending check or `throw` inside a try
+     * releases frames/scopes down to the recorded depths and branches to
+     * `label` (the catch, or the exception-path finally) instead of
+     * returning out of the function. Entering a try emits no code. */
+    private tryStack;
+    /** Return type of the function being emitted — the unwind path returns
+     * a dummy of this type (never read: callers check the flag first). */
+    private currentReturnType;
+    /** Active only while emitting a wasm32 async body lowered with LLVM's
+     * switched-coroutine intrinsics. */
+    currentWasiCoro: {
+        kind: "async" | "generator";
+        id: string;
+        handle: string;
+        self: string;
+        finalLabel: string;
+        cleanupLabel: string;
+        suspendLabel: string;
+    } | null;
+    /** The generator channels of the function being emitted (null outside
+     * generator bodies): yieldExpr emission reads them, and emitTryCatch's
+     * catch prologue emits the GENRET sentinel re-unwind exactly here. */
+    currentGenerator: {
+        yieldT: IrType;
+        nextT: IrType;
+    } | null;
+    /** Active optional-chain bind slots, by chain id (chainRecv reads). */
+    readonly chainSlots: Map<string, LlValue>;
+    logArgSlots: number;
+    private readonly stackTraces;
+    constructor(mod: IrModule, options: LlvmTargetOptions);
+    abiOffset(native64: number, wasm32: number): number;
+    llType(t: IrType): string;
+    ffiCallbackAdapter(binding: string, id: string): FfiCallbackAdapter;
+    /** C-callable scalar callback trampolines. A callback with an explicit
+     * context entry receives the closure at that exact ABI position. A raw
+     * callback loads it from a call-scoped TLS slot installed around the
+     * outer native call. */
+    private emitFfiCallbackDefs;
+    emit(): string;
+    /** LIBRARY mode: the profile-declared external definitions — the
+     * export-map wrappers plus init / sink-registration / reset / collect.
+     * Plain `define` (not `define internal`) — the exact linkage distinction
+     * that separates the executable lane's @main from everything else. The
+     * bodies delegate every runtime half to scr_library.c, mirroring the C
+     * emission line for line, so the two lanes are identical by
+     * construction. */
+    private emitLibDefs;
+    /** The shared abort helpers (emitted only when referenced): the OOM
+     * abort of untraced shape allocation and the invalid-union-tag abort —
+     * both print the runtime ABI’s exact message on fd 2 and abort. */
+    private helperDefs;
+    /** Env-signature wrappers + interned immortal closures for declared
+     * functions used as values (the runtime ABI’s sc_w_/sc_fc_ pair): every
+     * mention of `f` yields the same pointer, so `f === f` holds. */
+    private emitFnValueDefs;
+    /** The argument-pack ABI and trampoline prefix shared by async functions
+     * and generators. Their promise/generator completion and spawn tails stay
+     * with the callers below. */
+    private emitArgPackAndTrampolinePrologue;
+    /** Per-async-function machinery — async.ts's scaffolding, .ll
+     * flavored: an argument-pack struct type, a fiber trampoline (unpacks,
+     * frees the pack, runs the ordinary compiled body, settles the
+     * promise — fulfilling on clean return, leaving a pending exception
+     * for the runtime to reject with), and a spawn wrapper call sites and
+     * closures enter through (packs the args +1, scr_async_spawn runs the
+     * fiber eagerly to its first suspension and returns the promise). */
+    private emitAsyncScaffolding;
+    /** Per-generator-function machinery — the async scaffolding's lazy
+     * sibling (async.ts's emitGenScaffolding): the same argument pack,
+     * a fiber trampoline whose epilogue stores the COMPLETION value (or
+     * consumes the GENRET sentinel, promoting the parked .return value), a
+     * spawn wrapper that only ALLOCATES the suspended fiber, and the
+     * never-started teardown that drops the packed (+1) arguments. */
+    private emitGenScaffolding;
+    internLiteral(text: string): string;
+    /** Interned NUL-terminated C-string constant (the scr_jb_puts /
+     * stringify-indent currency) — `@`-ref, first-use order. */
+    cstr(text: string): string;
+    needBadTag(): void;
+    /** The interned immortal instance for a UNIT arm of a union — asserts
+     * the arm really is payload-less (undefined/null). Public: class
+     * emission initializes undefined-admitting fields through it
+     * (ClassHost). */
+    unitInstanceRef(unionId: string, tag: number): string;
+    declare(decl: string): void;
+    needOom(): void;
+    private currentFrame;
+    /** Registers an owned refcounted value on the current statement frame. */
+    own(v: LlValue): LlValue;
+    /** Registers a SLOT whose current contents the frame owns (conditional
+     * results: optional chains, branch joins that park ownership). */
+    ownSlot(slot: string, type: IrType): void;
+    /** Strike a refcounted temp from its frame: ownership is being moved. */
+    moveTemp(v: LlValue): void;
+    /** The retained (+1) read of a refcounted value — type-directed through
+     * the `_v` table (immortals skip, exactly the C retain calls). */
+    retainValue(name: string, type: IrType): string;
+    /** The release call for one owned refcounted value — type-directed like
+     * releaseCallC (all runtime releases are NULL-tolerant). */
+    releaseValue(name: string, type: IrType): void;
+    releaseFrame(frame: LlValue[]): void;
+    private releaseScope;
+    /** THE release-on-jump path (break/continue/return): pending statement
+     * frames and entered scopes down to the given depths, innermost first —
+     * everything whose normal fall-through releases the jump bypasses.
+     * Release every scope crossed by the control-flow edge. */
+    private releaseForJump;
+    /** Run the finally regions an abrupt loop/block jump crosses, then
+     * release to the already-resolved target. This is the return path's
+     * completion walk without a parked result value. */
+    private emitFinallysForJump;
+    /** THE unwind path at a point where an exception is pending: release
+     * everything between here and the innermost try handler — or the whole
+     * function — and branch to the handler / return a dummy value (never
+     * read: callers of a may-throw function test the pending flag before
+     * using the result). Callers own the surrounding pending branch; a
+     * `throw` unwinds unconditionally. */
+    private emitUnwind;
+    /** The emitter contract for exceptions: after EVERY call that can throw
+     * (per the may-throw analysis), test the pending flag and unwind. The
+     * call's result temp must join its frame BEFORE this runs so the unwind
+     * releases the dummy (NULL for refcounted kinds) harmlessly. */
+    emitPendingCheck(): void;
+    /** Moves an already-evaluated value into the runtime's exception cell —
+     * the `throw` statement's kind dispatch (stmts.ts's), shared with
+     * every synthetic thrower. Ownership of a refcounted payload must have
+     * been moved off its frame by the caller. */
+    emitThrowValue(v: LlValue): void;
+    /** JS truthiness of a value (falsy: false, 0, -0, NaN, "", nullish
+     * union arms): one fcmp for f64 (NaN and both zeros compare !one), a
+     * length load for strings, an inline tag switch for unions, `!= null`
+     * for the always-truthy object kinds (JS: [] and {} are truthy). */
+    truthy(v: LlValue): string;
+    /** Emit truthiness for one non-union kind. Union arms are known-present,
+     * so object kinds become the constant true instead of a pointer test. */
+    private truthyOf;
+    /** Loads a union box's tag (i32). */
+    unionTag(uName: string): string;
+    /** The BORROWED payload pointer of a ref arm (scr_union_peek inlined —
+     * the runtime's is a static inline). */
+    unionPeek(uName: string): string;
+    /** Emits `switch` over a union's tag with one block per arm; each arm
+     * body must TERMINATE its block (the callers branch to a join). The
+     * default block is the runtime ABI’s invalid-tag abort. Shared field
+     * reads can group equivalent storage prefixes and emit one representative. */
+    unionTagSwitch(uName: string, def: IrUnionDef, arm: (armType: IrType, tag: number) => void, fieldGroups?: number[][]): void;
+    /** The +1 extraction of a union's single narrowed arm (unionNarrow /
+     * the nullish-family reads): scalars via the runtime getters, ref arms
+     * a retained peek. */
+    unionExtract(uName: string, arm: IrType): string;
+    /** Constructs a union box around an OWNED (+1, already moved) value —
+     * the scr_union_new_* dispatch of unionWrap and the wrap-into-join
+     * sites (shift). */
+    unionNewOwned(tag: number, v: LlValue): string;
+    classMetaOf(className: string): LlClassMeta;
+    /** The field-slot pointer of a class member: rc at 0, the vtable word at
+     * 1 on hierarchy members, then the flattened field list. Runtime error
+     * classes GEP through %ScrError (their structs live in the runtime; the
+     * def's [name, message, %code, %cause] order matches the layout). */
+    classFieldPtr(objName: string, className: string, field: string): {
+        ptr: string;
+        type: IrType;
+    };
+    /** `o->vt->pre` — the dynamic class's preorder number (borrowed object;
+     * the static class names which struct spelling carries the vt word). */
+    loadVtPre(objName: string, staticClassName: string): string;
+    /** The class object's static symbol (classes as values), registering it
+     * for assembly on first use and interning the .name literal while the
+     * table is still open (the regex-literal discipline). */
+    classObjSym(className: string): string;
+    recordShape(shapeId: string): IrRecordShape;
+    /** Record prefixes with the same LLVM storage types put a field at the
+     * same offset on every target. Share one field-read block per matching
+     * prefix; class variants retain their own concrete layout dispatch. */
+    unionFieldGroups(def: IrUnionDef, field: string): number[][];
+    /** The field-slot pointer of a record member (rc header at index 0). */
+    recordFieldPtr(objName: string, shapeId: string, field: string): {
+        ptr: string;
+        type: IrType;
+    };
+    /** The overflow map's slot pointer on an index-signature shape. */
+    recordOvfPtr(objName: string, shapeId: string): string;
+    /** Loads a record field (i8-stored bools trunc to i1). */
+    loadField(ptr: string, t: IrType): string;
+    /** Stores a record field (i1 zext to the i8 storage). */
+    storeField(ptr: string, t: IrType, value: string): void;
+    /** A binding's storage: a module global, a plain local slot, or a boxed
+     * local (the slot holds the capture BOX; access goes through it). */
+    binding(id: string): {
+        kind: "global" | "local" | "boxed";
+        slot: string;
+        type: IrType;
+        local?: IrLocal;
+    };
+    private emitDebugLocal;
+    /** Loads a boxed binding's box pointer out of its slot. */
+    loadBox(slot: string): string;
+    boxGet(box: string, t: IrType): string;
+    /** scr_box_set_* — the ref form takes ownership of the passed value. */
+    boxSet(box: string, t: IrType, value: string): void;
+    retainBox(box: string): string;
+    /** The initializing write of a scalar TDZ box: mint the one-element
+     * array cell holding the value and move it into the ARR-kind box
+     * (set_ref releases nothing — the slot was the empty sentinel). */
+    private tdzScalarInit;
+    /** The TDZ-guarded read of a boxed binding: an empty payload slot is
+     * the temporal dead zone — throw Node's exact catchable ReferenceError
+     * (exprs.ts's varRef guard). Scalars then peek the one-element
+     * array cell; ref kinds read the box normally (+1). */
+    private checkTdz;
+    checkGlobalTdz(id: string): void;
+    private throwIfUninitialized;
+    tdzBoxRead(box: string, t: IrType, name: string): string;
+    /** Declaration stores initialize an empty TDZ box. Later stores check
+     * it after the RHS and update scalar cells in place. References move in. */
+    writeBindingBox(box: string, local: IrLocal, value: string, initializes?: boolean, borrowed?: boolean): void;
+    /** The LLVM symbol a direct call or closure enters a function through:
+     * async bodies are entered via their emitted spawn wrapper (which runs
+     * the fiber eagerly to its first suspension and returns the promise);
+     * generator bodies via theirs (which only ALLOCATES the suspended
+     * fiber and returns the generator object). */
+    callTarget(fnName: string): string;
+    /** Queue the current wasm coroutine and suspend it. The runtime decides
+     * whether the promise waiter list or the ready FIFO owns the continuation;
+     * LLVM keeps all live locals in the coroutine frame. */
+    emitWasiSuspend(promise: string | null): void;
+    /** Suspend after a target-specific runtime helper already queued the
+     * continuation (used by module awaits, which skip the hop when settled). */
+    emitWasiSuspendPrepared(): void;
+    /** Move a clean async return value into the current fiber's promise. */
+    private emitWasiFulfill;
+    private emitFunction;
+    private emitStmts;
+    /** Emits a block in its own lexical scope (refcounted locals released at
+     * end). `setup` runs after the
+     * scope opens, before the statements — the catch-binding hook: it may
+     * emit prelude lines and register entries the scope owns (released on
+     * every exit, jumps and unwinds included). */
+    private emitBlock;
+    emitStmt(s: IrStmt): void;
+    private emitStmtBody;
+    /** try/catch/finally via pending-flag unwinding — stmts.ts's
+     * emitTryCatch, block-flavored. Entering a try emits NO code: the try
+     * context is compile-time state (tryStack) redirecting unwinds inside
+     * the region to a label here. Shape:
+     *
+     *   { try body }           unwinds inside release frames/scopes down to
+     *                          this statement's depths, then br the handler
+     *   br after               (normal completion skips the handler)
+     *   try.c:                 (emitted only when some unwind targets it)
+     *     binding = scr_exc_take()   (or scr_exc_clear() when bindingless)
+     *     { catch body }
+     *   after: { finally body }      normal path
+     *   br try.e
+     *   try.fx:                exception path: the pending exception is
+     *     stash = scr_exc_take()     STASHED across the finally body so the
+     *     { finally body }           body's own pending checks answer for
+     *     scr_rethrow(stash)         themselves; a throw inside REPLACES the
+     *     <unwind>                   stash (it unwinds through the synthetic
+     *   try.e:                       scope entry) — JS's semantics exactly
+     *
+     * Abrupt completions inside tryBody/catchBody ride the finallyStack:
+     * returns inline copies at the return site, while break/continue use the
+     * shared region walk before branching to their resolved target. */
+    private emitTryCatch;
+    /** JS-exact switch: lazily evaluated, arbitrary-expression case tests in
+     * source order, bodies falling through in source order until a break —
+     * A chain of conditional branches. All case bodies
+     * share ONE scope; because dispatch can jump PAST a varDecl into a later
+     * case, refcounted/boxed case-body locals are NULL-reset up front and
+     * the scope-exit releases rely on NULL tolerance. */
+    private emitSwitch;
+    /** Evaluates a condition (IR conds are bool-typed) and releases its
+     * temps BEFORE the branch — safe because the result is a scalar i1, and
+     * required in loop-condition blocks (their temps must not survive into
+     * later blocks across the back edge). */
+    private emitCondition;
+    /** Evaluates `expr` in its own statement frame inside an already-open
+     * branch and moves the result into `slot`: the chosen value's ownership
+     * transfers, every other temp the arm allocated releases inside the
+     * branch. The shared core of ternary/logical. */
+    emitBranchInto(slot: string, expr: IrExpr): void;
+    emitLiteralExpr(e: ExprOf<"numLit" | "boolLit" | "strLit" | "moduleNsRef" | "unitLit" | "varRef">): LlValue;
+    emitOperatorExpr(e: ExprOf<"bin" | "unary" | "incDec" | "fieldIncDec" | "assignExpr" | "seqExpr">): LlValue;
+    emitControlExpr(e: ExprOf<"dynDestrCheck" | "dynIterN" | "toBool" | "logical" | "ternary" | "optChain" | "chainRecv" | "orDefault" | "nullish">): LlValue;
+    emitStringExpr(e: ExprOf<"strConcat" | "strEq" | "strCmp" | "toString" | "strIntrinsic" | "regexLit" | "templateStrings" | "regexIntrinsic">): LlValue;
+    /**
+     * Lower canonical `target = target + suffix` after evaluating the old
+     * left side and suffix in JavaScript order.  The snapshot stays owned by
+     * the statement frame while the destination relinquishes its CURRENT
+     * value, making the snapshot unique unless a real observable alias exists.
+     */
+    emitStringSelfConcatAssign(localId: string, left: IrExpr, suffix: IrExpr, retainForYield: boolean): LlValue;
+    emitContainerExpr(e: ExprOf<"arrayLit" | "arrayNewLen" | "arrayGet" | "arrayHas" | "arrayState" | "arrIntrinsic" | "bytesNew" | "bytesIntrinsic" | "mapNew" | "mapIntrinsic" | "setIntrinsic" | "setNew">): LlValue;
+    emitCallExpr(e: ExprOf<"call" | "ffiCall" | "closure" | "callValue" | "selfRef" | "new" | "classRef" | "newValue" | "instanceOfValue" | "promiseVoidWiden" | "upcast" | "downcast" | "instanceOf" | "virtualCall">): LlValue;
+    emitRecordExpr(e: ExprOf<"fieldGet" | "recordGet" | "recordLit" | "recordClone" | "recordKeyGet" | "recordOvfKeys" | "recordOvfHas">): LlValue;
+    emitDynamicExpr(e: ExprOf<"dynFrom" | "dynFromJsval" | "dynCall" | "dynInvoke" | "dynArrLit" | "dynObjLit" | "unionWrap" | "unionNarrow" | "unionDisc" | "unionKeyGet" | "unionIsTag" | "dynKeyGet" | "dynHasKey" | "dynScalarEq" | "dynTest" | "unionEq" | "unionFuncEq" | "caughtTest" | "caughtCheck" | "caughtNarrow" | "caughtToDyn">): LlValue;
+    emitIntrinsicExpr(e: ExprOf<"intrinsic">): LlValue;
+    emitSerializationExpr(e: ExprOf<"jsonStringify" | "dynCheck">): LlValue;
+    emitAsyncExpr(e: ExprOf<"yieldExpr" | "genResume" | "awaitExpr" | "awaitUnionExpr" | "newPromise" | "promiseWithResolvers">): LlValue;
+    emitJsInteropExpr(e: ExprOf<"jsMarshal" | "jsOp" | "jsExit" | "jsBridgePromise">): LlValue;
+    /** Read a receiver whose value is consumed immediately by a field or tag
+     * load. No user code may run between this read and its consumer. Locals
+     * and their projections already have an owner; other expressions keep
+     * their ordinary statement-frame ownership. The caller must retain any
+     * reference result before evaluating another expression. */
+    emitReadReceiver(e: IrExpr): LlValue;
+    emitExpr(e: IrExpr): LlValue;
+    emitJsMarshal(e: IrExpr & {
+        kind: "jsMarshal";
+    }): LlValue;
+    emitJsOp(e: IrExpr & {
+        kind: "jsOp";
+    }): LlValue;
+    emitJsExit(e: IrExpr & {
+        kind: "jsExit";
+    }): LlValue;
+    islandAdapter(arity: number, retKind: "void" | "jsval" | "f64" | "bool" | "string"): string;
+    islandTypedAdapter(fn: IrType & {
+        kind: "func";
+    }): string;
+    dynKind(d: string): string;
+    raceAdapterFor(from: IrType, to: IrType): string;
+    genResultThunkFor(genT: IrType & {
+        kind: "generator";
+    }, recT: IrType & {
+        kind: "record";
+    }): string;
+    childExitThunkFor(param: IrType): string;
+    execFileThunkFor(cbT: IrType & {
+        kind: "func";
+    }): string;
+    ipcMessageThunkFor(cbT: IrType & {
+        kind: "func";
+    }): string;
+    ipcSendThunkFor(cbT: IrType & {
+        kind: "func";
+    }): string;
+    childExitSignalThunkFor(codeParam: IrType, sigParam: IrType): string;
+    childDataThunkFor(param: IrType): string;
+    emitterFixedAdapter(cbT: IrType & {
+        kind: "func";
+    }): {
+        fn: string;
+        shim: string;
+    };
+    wrapEmitterListener(target: string, adapterFn: string): string;
+    unwrapNullableClosure(u: string, funcTag: number): string;
+    closeBindThunkFor(cbUnion: IrType, retServer: boolean): string;
+    closeOverrideWrapFor(cbUnion: IrType, retServer: boolean): string;
+    streamDataAdapter(cbT: IrType & {
+        kind: "func";
+    }): string;
+    streamDoneFnFor(kind: "w" | "f" | "d" | "t" | "l", doneT: IrType & {
+        kind: "func";
+    }): string;
+    fsRenameThunkFor(cbT: IrType & {
+        kind: "func";
+    }): string;
+    cryptoBytesThunkFor(cbT: IrType & {
+        kind: "func";
+    }): string;
+    zlibBytesThunkFor(cbT: IrType & {
+        kind: "func";
+    }): string;
+    streamCbThunkFor(kind: "r" | "w" | "f" | "d" | "t" | "l" | "e", cbT: IrType): string;
+    resolveThunkFor(inner: IrType): string;
+    tagInSet(uName: string, tags: number[]): string;
+    arrPush(arr: string, acc: "f64" | "bool" | "ref", value: string): string;
+    emitArrayCopyLoop(dst: string, src: string, acc: "f64" | "bool" | "ref"): void;
+    emitStrIntrinsic(e: IrExpr & {
+        kind: "strIntrinsic";
+    }): LlValue;
+    emitArrIntrinsic(e: IrExpr & {
+        kind: "arrIntrinsic";
+    }): LlValue;
+    wrapNullable(raw: string, present: string, valueType: IrType, valueTag: number, resultType: IrType & {
+        kind: "union";
+    }, absentTag: number): LlValue;
+    emitMapNew(e: IrExpr & {
+        kind: "mapNew";
+    }): LlValue;
+    mapSet(m: string, kAcc: "f64" | "str" | "ref", vAcc: "f64" | "bool" | "ref", key: string, value: string): void;
+    emitMapLikeIntrinsic(e: Extract<IrExpr, {
+        kind: "mapIntrinsic" | "setIntrinsic";
+    }>): LlValue;
+    emitSetNew(e: IrExpr & {
+        kind: "setNew";
+    }): LlValue;
+    emitStableReceiver(receiver: IrExpr, following: IrExpr[]): LlValue;
+    emitIntegerLoopIndex(expr: IrExpr): string | null;
+    emitBytesIndex(receiver: string, index: string, integerIndex?: boolean): string;
+    emitBytesData(receiver: string): string;
+    emitBytesLength(elem: IrBytesElem, receiver: string, bytes: boolean): LlValue;
+    emitBytesGet(elem: IrBytesElem, receiver: string, index: string, integerIndex?: boolean): LlValue;
+    emitToUint32(value: string, expr?: IrExpr): string;
+    private emitBytesSet;
+    emitBytesIntrinsic(e: IrExpr & {
+        kind: "bytesIntrinsic";
+    }): LlValue;
+    emitRegexIntrinsic(e: IrExpr & {
+        kind: "regexIntrinsic";
+    }): LlValue;
+    emitRecordKeyGet(e: IrExpr & {
+        kind: "recordKeyGet";
+    }): LlValue;
+    keyedRecordReadInto(slot: string, join: string, objName: string, keyName: string, shapeId: string, resultType: IrType, overflowOnly: boolean, loc?: SrcLoc): void;
+    dynPromiseAdapter(inner: IrType): string;
+    streamTypedRefCommitAdapter(t: IrType, snapshot: string): string;
+    liveDynRefAdapter(t: IrType): LlStreamTypedRefAdapter;
+    liveDynUnionRefAdapter(t: IrType & {
+        kind: "union";
+    }): string;
+    streamTypedRefBoxValue(B: BlockBuilder, t: IrType, value: string): string;
+    streamFromArrayAdapter(t: IrType & {
+        kind: "array";
+    }): string;
+    emitWebLibCall(e: LibCallExpr): LlValue;
+    emitDynamicLibCall(e: LibCallExpr): LlValue;
+    emitFilesystemLibCall(e: LibCallExpr): LlValue;
+    emitPathUrlLibCall(e: LibCallExpr): LlValue;
+    emitPrimitiveLibCall(e: LibCallExpr): LlValue;
+    emitChildProcessLibCall(e: LibCallExpr): LlValue;
+    emitAsyncContextLibCall(e: LibCallExpr): LlValue;
+    emitProcessLibCall(e: LibCallExpr): LlValue;
+    emitErrorsEventsLibCall(e: LibCallExpr): LlValue;
+    emitStreamLibCall(e: LibCallExpr): LlValue;
+    emitNetworkHttpLibCall(e: LibCallExpr): LlValue;
+    emitAssertInspectLibCall(e: LibCallExpr): LlValue;
+    emitIoLibCall(e: LibCallExpr): LlValue;
+    emitGenericLibCall(e: LibCallExpr): LlValue;
+    emitLibCall(e: LibCallExpr): LlValue;
+}