@scriptc/compiler 0.2.6 → 0.2.7

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

@@ -5,10 +5,12 @@ import { type ConstantNumericTable } from "../../ir/constant-tables.js";
 import { type FfiCallbackAdapter } from "../ffi-callbacks.js";
 import { type CallLifetimes } from "./call-lifetimes.js";
 import { BlockBuilder } from "./blocks.js";
-import { type LocalArrayRead } from "./local-array-reads.js";
+import { NullableRefFields, type NullableRefField } from "./nullable-fields.js";
+import { OptionalArrayReads, type LocalArrayRead } from "./local-array-reads.js";
 import { type MapReadLifetimes } from "./map-read-lifetimes.js";
 import { ReferenceEffects } from "./reference-effects.js";
 import { StackCallbacks } from "./stack-callbacks.js";
+import { AmbientReceiverReaders } from "./constant-callbacks.js";
 import { type StringSliceSnapshot } from "./string-slices.js";
 import { type LlClassMeta } from "./classes.js";
 import { LlDyn, type DynHost } from "./dyn.js";
@@ -31,6 +33,14 @@ export interface LlvmTargetOptions {
     /** Program objects carry a strong reference to the matching runtime ABI
      * marker so manual links against an incompatible runtime fail loudly. */
     runtimeAbiMarker?: boolean;
+    /** Emit live-object audit notes in emitted new/free helpers. Only the
+     * sanitized lane's SCR_RC_AUDIT runtime counts them; production plain
+     * builds pass false so release/dev objects carry no empty calls.
+     * Defaults to true for direct emission. */
+    objectAudit?: boolean;
+    /** Emit retain/release fast paths inline (the `speed` posture). Off, every
+     * retain and release is a runtime call. */
+    inlineRc?: boolean;
 }
 export declare function emitLlvmModule(mod: IrModule, options?: LlvmTargetOptions): string;
 /** Keep large translation units below the host's single-string limit. */
@@ -70,6 +80,8 @@ export declare class LlEmitter {
      * immortal (rc == SIZE_MAX) static per (union, unit tag).
      * RC entry points and the collector skip immortals. */
     private readonly unitInstances;
+    /** unionId → symbol of the union's immortal ABSENT field-slot instance. */
+    private readonly absentInstances;
     private readonly immortalValues;
     /** Regex literal templates: "<flags>/<pattern>" → { symbol, interned
      * source/flags literal refs } — one immortal ScrRegex template per distinct
@@ -110,17 +122,31 @@ export declare class LlEmitter {
     needsBadTag: boolean;
     needsBadKey: boolean;
     private needsRetainBox;
+    /** Inline RC fast-path helpers requested by call sites (shapes.ts); null
+     * when inline RC is off. */
+    private readonly rcHelpers;
     readonly fnByName: Map<string, IrFunction>;
+    /** Emitted LLVM text of every IR function body, by function name: the
+     * fiberless-async analysis scans it for suspension entry points. */
+    private readonly fnDefText;
     readonly referenceEffects: ReferenceEffects;
-    private readonly optionalArrayReads;
+    readonly optionalArrayReads: OptionalArrayReads;
     callArrayReads: Map<IrExpr, LocalArrayRead>;
     mapReadLifetimes: MapReadLifetimes;
     readonly callLifetimes: CallLifetimes;
     readonly constantCallbacks: Map<string, Map<string, string>>;
     currentConstantCallbacks: ReadonlyMap<string, string>;
     readonly stackCallbacks: StackCallbacks;
+    readonly receiverReaders: AmbientReceiverReaders;
     private readonly stackCaptures;
+    private readonly lazyCaptures;
+    /** Unchanged captured parameters of the current function: each maps to
+     * the slot caching its box, NULL until the first closure needs it. */
+    private readonly lazyCaptureBoxes;
+    private readonly lazyStackBoxes;
     private borrowedParameters;
+    /** Parameters proven projection-only: callers may pass stack boxes. */
+    private projectedParameters;
     private stableCallBindings;
     /** Manifest-bound native imports, used by ffiCall emission. */
     readonly ffiByName: Map<string, IrFfiImport>;
@@ -160,6 +186,7 @@ export declare class LlEmitter {
     readonly liveDynUnionRefAdapters: Map<string, string>;
     readonly dynPromiseAdapters: Map<string, string>;
     readonly unionsById: Map<string, IrUnionDef>;
+    readonly nullableFields: NullableRefFields;
     readonly recordsById: Map<string, IrRecordShape>;
     readonly recordCloneShapes: Set<string>;
     readonly tracedShapes: Set<string>;
@@ -288,6 +315,11 @@ export declare class LlEmitter {
      * 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;
+    /** The inline RC helpers every call site requested, emitted last so
+     * requests from main/library epilogues are included. Slow-path
+     * declarations a late request added after the extern block flushed land
+     * here too. */
+    private inlineRcTail;
     /** 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. */
@@ -296,6 +328,30 @@ export declare class LlEmitter {
      * and generators. Their promise/generator completion and spawn tails stay
      * with the callers below. */
     private emitArgPackAndTrampolinePrologue;
+    /** Settles `promise` from a clean async body result `%r` (moved in). */
+    private asyncFulfillLines;
+    /** Async functions whose calls can skip the fiber (scr_async_inline_*).
+     * A body qualifies only when nothing it runs can park its execution
+     * context: its emitted text, and the text of every module function it
+     * mentions (transitively), contains no suspension entry point. Such a
+     * body always completes before the call returns, which is exactly the
+     * behavior of a fiber that never suspends. Excluded conservatively:
+     * wasm32 (its coroutine lowering owns async bodies), programs embedding
+     * the dynamic engine, module-evaluation bodies (their promise caches),
+     * `dyn` results (resolution may adopt a thenable), and every program
+     * that uses node:test subtests — `t.test()` runs a subtest inline and
+     * awaits it on the CURRENT fiber even from synchronous code. Worker
+     * programs keep fibers too: their fiber epilogue owns context
+     * termination (a stopping worker rejects and observes the promise), which
+     * the fiberless wrapper does not reproduce. A missed suspension still
+     * cannot reorder silently: the runtime traps when a context parks while a
+     * fiberless body is on its stack. */
+    private fiberlessAsyncFunctions;
+    /** The spawn wrapper of a fiberless async function: runs the body on the
+     * caller's stack between scr_async_inline_enter/leave and settles the
+     * fresh promise from its outcome — the fiber trampoline's epilogue,
+     * without the fiber. */
+    private emitFiberlessAsyncSpawn;
     /** 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
@@ -321,6 +377,17 @@ export declare class LlEmitter {
      * emission initializes undefined-admitting fields through it
      * (ClassHost). */
     unitInstanceRef(unionId: string, tag: number): string;
+    /** The immortal ABSENT state of an undefined-armed record field slot
+     * (IR fieldAbsent). */
+    absentInstanceRef(unionId: string): string;
+    /** i1: a union value loaded from a field slot is the ABSENT state — the
+     * undefined arm's tag with the absent payload marker. */
+    fieldAbsentTest(value: string, unionId: string): string;
+    /** Loads a record field slot as a VALUE: an undefined-armed union slot
+     * holding the ABSENT state surfaces as the ordinary undefined arm, so
+     * absence never travels beyond its slot (a later `{ f: r.f }` is an
+     * explicit, present property). */
+    loadRecordField(ptr: string, t: IrType): string;
     declare(decl: string): void;
     needOom(): void;
     private currentFrame;
@@ -386,9 +453,14 @@ export declare class LlEmitter {
      * 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
+     * the nullish-family reads): scalars via inline payload loads, ref arms
      * a retained peek. */
     unionExtract(uName: string, arm: IrType): string;
+    /** A scalar f64 arm's payload (scr_union_get_f64 inlined). Inline loads
+     * keep stack boxes free of escaping calls, so LLVM can scalarize them. */
+    unionGetF64(uName: string): string;
+    /** A bool arm's payload (scr_union_get_bool inlined: nonzero slot). */
+    unionGetBool(uName: string): 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). */
@@ -436,9 +508,15 @@ export declare class LlEmitter {
     private emitDebugLocal;
     /** Loads a boxed binding's box pointer out of its slot. */
     loadBox(slot: string): string;
+    /** The payload slot of a capture box (ScrBox.slot, field 5). */
+    private boxSlot;
     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;
+    /** The box a new environment captures for `localId` (borrowed). An
+     * unchanged parameter gets one box on first capture, holding its own
+     * reference to the value; the function scope releases the cached box. */
+    captureBox(localId: string): string;
     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
@@ -450,6 +528,8 @@ export declare class LlEmitter {
      * array cell; ref kinds read the box normally (+1). */
     private checkTdz;
     checkGlobalTdz(id: string): void;
+    /** Throws the TDZ ReferenceError for `name` unless the i1 `flag` is set. */
+    checkInitializedFlag(flag: string, name: string): void;
     private throwIfUninitialized;
     tdzBoxRead(box: string, t: IrType, name: string): string;
     /** Declaration stores initialize an empty TDZ box. Later stores check
@@ -546,7 +626,7 @@ export declare class LlEmitter {
     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;
+    emitRecordExpr(e: ExprOf<"fieldGet" | "recordGet" | "recordLit" | "recordClone" | "recordKeyGet" | "recordOvfKeys" | "recordOvfHas" | "recordHas" | "fieldAbsent">): 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;
@@ -558,6 +638,46 @@ export declare class LlEmitter {
      * their ordinary statement-frame ownership. The caller must retain any
      * reference result before evaluating another expression. */
     emitReadReceiver(e: IrExpr): LlValue;
+    /** 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
+     * stack box with an independently owned payload (no heap union). */
+    isStackUnionSource(e: IrExpr): boolean;
+    /** The nullable-pointer representation behind a union-typed class field
+     * read, or null for every other expression. */
+    nullableFieldGet(e: IrExpr): NullableRefField | null;
+    /** A union operand consumed only by a projection (tag test, payload
+     * extraction, arm compare, truthiness). A nullable-pointer field read
+     * becomes a private stack box whose payload is borrowed from the field:
+     * the consumer must finish before any later expression can store to the
+     * field, and must never retain, release, or store the box. Every other
+     * operand takes the ordinary borrowed-receiver path. */
+    emitUnionProjection(e: IrExpr): LlValue;
+    /** A private stack box over a nullable-pointer field read whose payload
+     * is retained into the current frame: an independent owner, so the box
+     * may outlive later stores to the field (call arguments, local copies).
+     * The box itself must still never reach an RC entry point. */
+    emitOwnedNullableStack(e: IrExpr): {
+        box: string;
+        owner: LlValue;
+    };
+    /** A private stack box over a borrowed nullable pointer. */
+    stackNullableBox(p: string, nullable: NullableRefField): string;
+    /** The owned (+1) union value of a nullable-pointer slot: the unit arm's
+     * immortal instance, or a fresh heap box around a retained instance. */
+    nullableToOwnedUnion(p: string, nullable: NullableRefField): string;
+    /** The owned (+1) instance pointer (NULL for the unit arm) of a union
+     * box, which stays owned by its existing owner. */
+    unionToNullable(u: string, nullable: NullableRefField): string;
+    /** `obj.f = value` for a nullable-pointer field: the new instance pointer
+     * is produced without a union box where the value is a wrap, and as a
+     * retained payload of a borrowed box otherwise. Unlink-then-release like
+     * every field store. */
+    emitNullableFieldStore(obj: string, className: string, field: string, nullable: NullableRefField, value: IrExpr): void;
+    /** A union binding whose slot may hold a private stack box: stack locals
+     * and projection-only parameters (callers may pass stack boxes). Such a
+     * box must only be projected: never retained, released, or stored. */
+    isStackUnionLocal(localId: string): boolean;
     canBorrowReceiver(e: IrExpr): boolean;
     materializeSplitLocal(localId: string): void;
     emitExpr(e: IrExpr): LlValue;