@scriptc/compiler 0.3.0 → 0.3.2

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

@@ -2,9 +2,12 @@ import type { IrBytesElem, IrExpr, IrFfiImport, IrFunction, IrLocal, IrModule, I
 import { type SplitSpan } from "./split-loops.js";
 import { type IntegerRanges } from "../../ir/integer-ranges.js";
 import { type Int32Slots } from "../../ir/int32-slots.js";
+import { type Int32Abi } from "./int32-abi.js";
+import { type Int32Local } from "./int32-locals.js";
 import { type ConstantNumericTable } from "../../ir/constant-tables.js";
 import { type FfiCallbackAdapter } from "../ffi-callbacks.js";
 import { type CallLifetimes } from "./call-lifetimes.js";
+import { type UnionSources } from "./local-union-storage.js";
 import { BlockBuilder } from "./blocks.js";
 import { NullableRefFields, type NullableRefField } from "./nullable-fields.js";
 import { OptionalArrayReads, type LocalArrayRead } from "./local-array-reads.js";
@@ -61,6 +64,10 @@ export declare class LlEmitter {
     private scalarStringSlices;
     readonly stringSlices: Map<string, StringSliceSnapshot>;
     private localStackUnions;
+    private localStackObjects;
+    private reassignedStackObjects;
+    /** The binding slot of each reassigned stack-object local. */
+    private stackObjectSlots;
     private localUnionStorageProofs;
     private localUnionStorage;
     integerArrayBindings: Set<string>;
@@ -72,17 +79,30 @@ export declare class LlEmitter {
      * operations and record views conservatively alias all of them. */
     private markFieldPointer;
     markMemoryPointer(ptr: string, field: string): void;
+    /** The alias tag of a runtime word that emitted code reads and writes
+     * outside every field (the lifetime-region count, owner and cursors). */
+    memoryAliasAttachment(category: string): string;
     fieldAliasAttachment(ptr: string): string;
     private fieldAliasMetadata;
     private readonly debug;
+    /** Projection-only scalar objects may live in frame storage (stack-objects.ts). */
+    readonly stackObjects: boolean;
     private debugScope;
     readonly sizeType: "i32" | "i64";
     readonly ffiExtendNarrowIntegers: boolean;
-    readonly cycleBufferedOffset: number;
+    readonly cycleBufOffset: number;
     /** Emitted ScrCycType descriptors so far (their collector statistics
      * indices; see ShapeHost.nextCycKind). */
     private cycKinds;
     readonly wasi: boolean;
+    /** Synchronous generator bodies compile to LLVM switched coroutines (a
+     * heap frame resumed by an ordinary call) instead of running on a fiber
+     * stack. Worker programs keep fibers (context shutdown unwinds suspended
+     * generator stacks) and so do debug builds (the debugger reads locals
+     * from the native frame). */
+    private stacklessGenerators;
+    /** Some function in the module is lowered as a coroutine. */
+    private usesCoroutines;
     /** The target lacks a rounding instruction at its baseline CPU (x86-64
      * before SSE4.1), so `llvm.trunc` would lower to a libm call: emit
      * truncation inline through an integer round trip instead. */
@@ -102,6 +122,10 @@ export declare class LlEmitter {
     /** Interned string literals: UTF-8 text → { symbol, byte length } —
      * first-use order, the runtime ABI’s determinism discipline. */
     private readonly literals;
+    /** Literal equality helpers: literal text → helper symbol (literalEquals). */
+    private readonly literalEqualities;
+    /** Interned bigint literals: hex magnitude with sign → { symbol, value }. */
+    private readonly bigintLiterals;
     /** Symbols of interned constant data, named by content (contentSymbol). */
     private readonly contentSymbols;
     /** Interned unit-armed union instances: "unionId:tag" → symbol — one
@@ -110,6 +134,10 @@ export declare class LlEmitter {
     private readonly unitInstances;
     /** unionId → symbol of the union's immortal ABSENT field-slot instance. */
     private readonly absentInstances;
+    /** unionId → symbol of a flag set once a checked-dynamic cast caches one
+     * of the union's boxes. A cached box is refreshed in place, possibly with
+     * a tag that another union numbers apart, so it is never shared. */
+    private readonly retypeGuards;
     /** The nullable-union ABSENT sentinel was referenced (absentInstanceRef). */
     private needsNullableAbsent;
     private readonly immortalValues;
@@ -122,6 +150,8 @@ export declare class LlEmitter {
         sym: string;
         src: string;
         fl: string;
+        pattern: string;
+        flags: string;
     }>;
     /** Interned tagged-template strings objects: per-site key → { symbol,
      * interned cooked-literal refs }. One immortal ScrArr of string slots
@@ -156,6 +186,8 @@ export declare class LlEmitter {
      * when inline RC is off. */
     private readonly rcHelpers;
     readonly fnByName: Map<string, IrFunction>;
+    /** Empty literals that construct with inline slots (appended-array-literals.ts). */
+    appendedArrayLiterals: ReadonlySet<IrExpr>;
     /** Emitted LLVM text of every IR function body, by function name: the
      * fiberless-async analysis scans it for suspension entry points. */
     private readonly fnDefText;
@@ -167,6 +199,8 @@ export declare class LlEmitter {
      * whose bindings end with the list (emitBlock and function bodies). */
     private stmtCursor;
     readonly optionalArrayReads: OptionalArrayReads;
+    /** Union sources a binding or projection can hold in a stack box. */
+    readonly unionSources: UnionSources;
     readonly checkedNarrows: CheckedNarrows;
     callArrayReads: Map<IrExpr, LocalArrayRead>;
     mapReadLifetimes: MapReadLifetimes;
@@ -182,6 +216,9 @@ export declare class LlEmitter {
     private readonly lazyCaptureBoxes;
     private readonly lazyStackBoxes;
     private borrowedParameters;
+    /** Captures of the current closure body that its environment holds
+     * unchanged for the closure's whole life (LazyCaptures.stableCaptures). */
+    private stableCaptureIds;
     /** Parameters proven projection-only: callers may pass stack boxes. */
     private projectedParameters;
     private stableCallBindings;
@@ -237,6 +274,17 @@ export declare class LlEmitter {
     /** Method names with at least one may-throw implementation — the
      * virtualCall pending check's key. */
     readonly mayThrowMethods: Set<string>;
+    /** Async functions awaited directly at some `await f(...)` site; each
+     * gets an await-call entry (emitAsyncAwaitCall). */
+    readonly awaitCallees: Set<string>;
+    /** Async functions returned directly at some `return f(...)` site of an
+     * async function; each gets an adopting entry (emitAsyncAwaitCall). */
+    readonly adoptCallees: Set<string>;
+    /** The promise a `return` emitted past its finally regions already
+     * produced for its adopting await (borrowed from the return's parked
+     * slot); that await takes it instead of evaluating its operand. */
+    private adoptedOperand;
+    takeAdoptedOperand(): LlValue | null;
     /** setTimeout and friends appeared somewhere: main must run the event
      * loop even in programs with no async functions. */
     usesTimers: boolean;
@@ -244,6 +292,8 @@ export declare class LlEmitter {
      * typeKey → thunk symbol. */
     readonly resolveThunks: Map<string, string>;
     readonly resolveThunkDefs: string[];
+    /** Typed-ref recipe constants by type key (lazy receivers). */
+    readonly typedRefRecipes: Map<string, string>;
     /** ReadableStream.from adapters keep typed arrays by reference and box
      * one current element per pull. */
     readonly streamFromArrayAdapters: Map<string, string>;
@@ -309,6 +359,8 @@ export declare class LlEmitter {
     private readonly initializerBindings;
     /** Whole-program int32 storage and parameter/result facts. */
     readonly int32Slots: Int32Slots;
+    /** Functions whose direct calls use i32 parameters or results. */
+    readonly int32Abis: ReadonlyMap<string, Int32Abi>;
     /** Immutable module constants (contract types) whose graphs become
      * immortal once initialized: their reads need no reference counting. */
     readonly immortalGlobals: ReadonlySet<string>;
@@ -334,10 +386,17 @@ export declare class LlEmitter {
      * not a constructor (where they change), not async or a generator. */
     private finalFieldBorrows;
     integerRanges: IntegerRanges;
+    /** Sums whose result only feeds 32-bit conversions (wrapping-sums.ts). */
+    wrappingSums: Set<IrExpr>;
     private byteWindowsEnabled;
     private byteWindowEntries;
     bytesBounds: ReadonlySet<IrExpr | IrStmt>;
     integerViews: Map<string, string>;
+    /** Number locals of the current function stored only as an i32
+     * (int32-locals.ts); their slots are `alloca i32`. */
+    int32Locals: Map<string, Int32Local>;
+    /** The written values (and `++`/`--` nodes) the int32 proof covers. */
+    int32LocalWrites: ReadonlySet<IrExpr>;
     /** 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
@@ -356,10 +415,16 @@ export declare class LlEmitter {
     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: {
+    currentReturnType: IrType;
+    /** The current body returns its number result as i32. */
+    private currentInt32Result;
+    /** The function's i32 entry returns its scalar union result as tag and
+     * payload bits (Int32Abi.union). */
+    private currentUnionResult;
+    /** Active only while emitting a body lowered with LLVM's
+     * switched-coroutine intrinsics (wasm32 async bodies and generators,
+     * native synchronous generators; see coroLowered). */
+    currentCoro: {
         kind: "async" | "generator";
         id: string;
         handle: string;
@@ -375,6 +440,8 @@ export declare class LlEmitter {
         yieldT: IrType;
         nextT: IrType;
     } | null;
+    /** The function being emitted is an async generator body. */
+    private currentAsyncGenerator;
     /** Active optional-chain bind slots, by chain id (chainRecv reads). */
     readonly chainSlots: Map<string, LlValue>;
     logArgSlots: number;
@@ -445,6 +512,24 @@ export declare class LlEmitter {
      * fresh promise from its outcome — the fiber trampoline's epilogue,
      * without the fiber. */
     private emitFiberlessAsyncSpawn;
+    /** Whether `await f(...)` may enter f through its await-call entry. The
+     * entry's result is the awaited value of f's own body type; direct calls
+     * never carry a lifted environment. */
+    awaitCallEligible(fnName: string): boolean;
+    /** The await-call entry of an async function (`sc_aw_*`): one direct
+     * `await f(...)` as a call returning the awaited value, so the call site
+     * needs no promise of its own. A fiberless body runs on the caller's
+     * stack as in its spawn wrapper; a clean result then takes the await's
+     * one microtask turn (scr_await_hop) and is returned without ever
+     * materializing the promise, which nothing else could observe. A throw
+     * builds the rejected promise exactly as the spawn wrapper would and
+     * awaits it, so the rejection reaches the awaiter on the same turn. Other
+     * bodies pack their arguments as the spawn wrapper does and enter
+     * scr_async_spawn_await_*, which parks the caller on the promise as soon
+     * as the body first suspends. The adopting entry (`sc_ad_*`, for
+     * `return f(...)` in an async function) adds the turn of the then job
+     * that adopts the returned promise, before the await proper. */
+    private emitAsyncAwaitCall;
     /** 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
@@ -453,6 +538,9 @@ export declare class LlEmitter {
      * closures enter through (packs the args +1, scr_async_spawn runs the
      * fiber eagerly to its first suspension and returns the promise). */
     private emitAsyncScaffolding;
+    /** Whether `fn`'s body is emitted as an LLVM switched coroutine: every
+     * wasm32 async or generator body, and native synchronous generators. */
+    private coroLowered;
     /** 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
@@ -467,6 +555,14 @@ export declare class LlEmitter {
      * collision retries with a counter, still in first-use order. */
     private contentSymbol;
     internLiteral(text: string): string;
+    /** The inline equality test against one string literal (an
+     * `i1 (ptr)` helper LLVM inlines at each site), by literal symbol. */
+    literalEquals(text: string): string;
+    /** `@`-ref of an immortal ScrBigInt holding `value`, or null when the
+     * text is not a valid StringToBigInt input (the runtime parse then
+     * throws as usual). BigInt here is the same StringToBigInt as the
+     * program's, so every accepted spelling folds to the value Node gives. */
+    internBigIntLiteral(text: string): string | null;
     /** Interned NUL-terminated C-string constant (the scr_jb_puts /
      * stringify-indent currency) — `@`-ref, first-use order. */
     cstr(text: string): string;
@@ -476,6 +572,9 @@ export declare class LlEmitter {
      * emission initializes undefined-admitting fields through it
      * (ClassHost). */
     unitInstanceRef(unionId: string, tag: number): string;
+    /** The i8 flag that a checked-dynamic cast sets before caching one of
+     * this tagged union's boxes (unionRetype rebuilds once it is set). */
+    retypeGuardRef(unionId: string): string;
     /** The immortal ABSENT state of an undefined-armed record field slot
      * (IR fieldAbsent). */
     absentInstanceRef(unionId: string): string;
@@ -699,6 +798,11 @@ export declare class LlEmitter {
     /** 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;
+    /** True when `fnName`'s borrowing body lends every reference parameter
+     * and returns an owned result: a closure over it then carries that body
+     * as its borrowing entry (ScrClosure.fn_borrowed), which callers that
+     * keep their arguments alive across the call may enter instead of `fn`. */
+    lendsEveryArgument(fnName: string): boolean;
     /** 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);
@@ -711,13 +815,34 @@ export declare class LlEmitter {
     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;
+    emitCoroSuspendPrepared(): void;
     /** Move a clean async return value into the current fiber's promise. */
     private emitWasiFulfill;
     private emitFunction;
+    /** The double-ABI entry of a function with an i32 entry: every caller
+     * that is not a direct call (closures, dispatch, adapters, the runtime)
+     * enters here. A pending exception passes through to its caller. */
+    private emitInt32AbiWrapper;
+    /** The SCALAR_UNION_RESULT pair of a `%ScrUnion` box of `type`. */
+    scalarUnionPair(box: string, type: IrType): string;
+    /** A private stack box holding a SCALAR_UNION_RESULT pair of `type`. */
+    stackScalarUnion(pair: string, type: IrType): LlValue;
+    /** A direct call whose i32 entry returns its scalar union in registers. */
+    scalarResultCall(e: IrExpr): boolean;
+    /** A fresh heap box (+1) for a SCALAR_UNION_RESULT pair of `type`; the
+     * exception dummy (tag -1) answers NULL. */
+    boxScalarUnion(pair: string, type: IrType): string;
+    /** The i32 bits of a number proven an int32 (a direct call's i32
+     * argument or an i32 result): its exact integer when the value carries
+     * one, else the conversion the proof makes exact. */
+    int32Argument(value: LlValue, expr: IrExpr): string;
+    /** A direct call's i32 result as a number, with the i32 as its integer
+     * and ToUint32 forms. */
+    int32Result(bits: string, type: IrType): LlValue;
     /** Keep the ordinary owned ABI for closures, virtual dispatch, generated
-     * runtime adapters and library exports. Only direct IR calls select the
-     * borrowing body. Ownership of other parameters moves into that body;
+     * runtime adapters and library exports. Only direct IR calls, calls of a
+     * known closure body and borrowing closure entries (fn_borrowed) select
+     * the borrowing body. Ownership of other parameters moves into that body;
      * borrowed parameters are released here on normal and exceptional exits.
      * The pending exception remains for the adapter's caller to handle. */
     /** With `kept`, the virtual adapter of a borrowing slot instead: the
@@ -751,6 +876,17 @@ export declare class LlEmitter {
      * borrow the element when the callee and later arguments (`writes`)
      * write no array element and nothing keeping the array alive. */
     unwrittenCallArrayRead(read: LocalArrayRead, writes: Writes): boolean;
+    /** `return p` of a promise inside try regions of an async function. JS
+     * completes the return first: p is evaluated, every crossed finally runs,
+     * and only then does the function's promise adopt p's settlement (a then
+     * job, then p's reaction). So the promise parks in a slot through the
+     * finally copies, like any pending return value, and the adopting await
+     * runs afterwards with no handler in scope: a rejection settles the
+     * function's promise instead of reaching its own catch clauses. */
+    private emitAdoptingReturn;
+    /** An async generator completing without a further turn: its request
+     * settles as the body returns (scr_async_gen_hop_done). */
+    private emitAsyncGenSettled;
     /** `return x` of a local whose slot is an owned scope entry of the same
      * type: the return can take over the local's reference. */
     private movableReturn;
@@ -851,9 +987,18 @@ export declare class LlEmitter {
     private emitMovedSelfConcat;
     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;
+    /** A direct async call an enclosing `await` consumes whole: emitted
+     * through the callee's await-call entry, yielding the awaited value. */
+    emitAwaitedCall(e: ExprOf<"call">, adopt?: boolean): LlValue;
     emitRecordExpr(e: ExprOf<"fieldGet" | "recordGet" | "recordLit" | "recordClone" | "recordKeyGet" | "recordOvfKeys" | "recordOvfHas" | "recordHas" | "fieldAbsent">): LlValue;
     emitDynamicExpr(e: ExprOf<"dynFrom" | "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;
+    /** Lifetime regions in modules with lifetimeRegions (llvm/regions.ts).
+     * Created with the class graph; null elsewhere. */
+    private regions;
+    /** LifetimeRegion's runtime calls: create answers the region id, enter
+     * and leave bracket run(), release condemns. */
+    private emitRegionIntrinsic;
     private publishWalkersCache;
     /** Per-type publication walkers, created on the first publish. */
     private get publishWalkers();
@@ -887,6 +1032,8 @@ export declare class LlEmitter {
      * their ordinary statement-frame ownership. The caller must retain any
      * reference result before evaluating another expression. */
     emitReadReceiver(e: IrExpr): LlValue;
+    /** The frame slot a reassigned stack-object local keeps for its value. */
+    private stackObjectSlot;
     /** A private stack union source with an independently owned payload. */
     canStackReceiver(e: IrExpr): boolean;
     /** True for union sources that emitReadReceiver can produce as a private
@@ -1032,6 +1179,14 @@ export declare class LlEmitter {
     emitBytesLength(elem: IrBytesElem, receiver: string, bytes: boolean): LlValue;
     emitBytesGet(elem: IrBytesElem, receiver: string, index: LlValue, expr?: IrExpr, inBounds?: boolean, invalidNaN?: boolean): LlValue;
     emitToUint32(value: string, expr?: IrExpr, uint32?: string): string;
+    /** Stores a number into its int32-stored local, when it is one. The
+     * value is proven to be in the local's range, so its low 32 bits are the
+     * exact value. */
+    storeInt32Local(localId: string, value: LlValue, expr?: IrExpr): boolean;
+    /** The number of an int32-stored local's i32, with the i32 as its
+     * integer and ToUint32 forms. A parameter the body never writes reads
+     * as its incoming double, which is the same number. */
+    int32LocalValue(localId: string, bits: string, type: IrType): LlValue;
     storeIntegerView(localId: string, value: LlValue, expr?: IrExpr): void;
     private emitBytesSet;
     emitBytesIntrinsic(e: IrExpr & {