@scriptc/compiler 0.3.1 → 0.3.3

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

@@ -1,3 +1,4 @@
+import { type ArraySearchKind } from "./array-search.js";
 import type { IrBytesElem, IrExpr, IrFfiImport, IrFunction, IrLocal, IrModule, IrRecordShape, IrStmt, IrType, IrUnionDef, SrcLoc } from "../../ir/ir.js";
 import { type SplitSpan } from "./split-loops.js";
 import { type IntegerRanges } from "../../ir/integer-ranges.js";
@@ -7,8 +8,10 @@ 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 { InlineUnionFields } from "./inline-unions.js";
 import { OptionalArrayReads, type LocalArrayRead } from "./local-array-reads.js";
 import { CheckedNarrows } from "./checked-narrows.js";
 import { type MapReadLifetimes } from "./map-read-lifetimes.js";
@@ -18,11 +21,12 @@ import { StackCallbacks } from "./stack-callbacks.js";
 import { AmbientReceiverReaders } from "./constant-callbacks.js";
 import { type StringSliceSnapshot } from "./string-slices.js";
 import { type PublishedTypes } from "../publication.js";
+import { type BytesThunkValue } from "./expr-stream-callbacks.js";
 import { type LlClassMeta } from "./classes.js";
 import { LlDyn, type DynHost } from "./dyn.js";
 import { LlWalkers } from "./walkers.js";
 import { NullableUnions } from "./nullable-unions.js";
-import { type MapKeyAccess } from "./shapes.js";
+import { type InlineRcMode, type MapKeyAccess } from "./shapes.js";
 import type { ExprOf, LibCallExpr, LlStreamTypedRefAdapter, LlValue } from "./expr-context.js";
 export { LlvmUnsupportedError } from "./unsupported.js";
 export interface LlvmTargetOptions {
@@ -38,16 +42,20 @@ export interface LlvmTargetOptions {
      * separate translation unit. Public/direct emission keeps them by default. */
     emitLibraryIdentity?: boolean;
     /** Program objects carry a strong reference to the matching runtime ABI
-     * marker so manual links against an incompatible runtime fail loudly. */
+     * marker so a manual link against an incompatible runtime fails. */
     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;
+    /** Emit retain/release fast paths inline: `speed` for every family with a
+     * fast path, `release` for the string retain and the dyn retain and
+     * release (shapes.ts InlineRcMode). Off, every retain and release is a
+     * runtime call. */
+    inlineRc?: InlineRcMode;
+    /** Define the inline RC fast-path helpers `noinline` (sanitized builds). */
+    rcHelpersNoinline?: boolean;
     /** Define `scr_detached_exit` so the Linux runtime hands the address-space
      * teardown after `process.exit` to a helper process (`--detached-exit`).
      * Executables only; the runtime's weak default keeps it off. */
@@ -63,6 +71,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>;
@@ -74,13 +86,18 @@ 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;
@@ -124,6 +141,8 @@ export declare class LlEmitter {
     private readonly unitInstances;
     /** unionId → symbol of the union's immortal ABSENT field-slot instance. */
     private readonly absentInstances;
+    /** The zeroed box an inline store reads for a NULL union dummy. */
+    private needsUnionNone;
     /** 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. */
@@ -175,7 +194,11 @@ export declare class LlEmitter {
     /** Inline RC fast-path helpers requested by call sites (shapes.ts); null
      * when inline RC is off. */
     private readonly rcHelpers;
+    private readonly rcMode;
+    private readonly rcHelpersNoinline;
     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;
@@ -187,6 +210,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;
@@ -278,6 +303,10 @@ export declare class LlEmitter {
      * typeKey → thunk symbol. */
     readonly resolveThunks: Map<string, string>;
     readonly resolveThunkDefs: string[];
+    /** Inline array searches used by the module (array-search.ts). */
+    readonly arraySearchKinds: Set<ArraySearchKind>;
+    /** 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>;
@@ -289,6 +318,7 @@ export declare class LlEmitter {
     readonly dynPromiseAdapters: Map<string, string>;
     readonly unionsById: Map<string, IrUnionDef>;
     readonly nullableFields: NullableRefFields;
+    readonly inlineUnions: InlineUnionFields;
     /** Unions whose values are nullable arm pointers (nullable-unions.ts). */
     readonly nullableUnions: NullableUnions;
     /** The union table without nullable unions: the stack-box analyses. */
@@ -399,9 +429,12 @@ 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;
+    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). */
@@ -421,6 +454,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;
@@ -483,7 +518,7 @@ export declare class LlEmitter {
      * 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
+     * cannot reorder execution undetected: 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
@@ -567,7 +602,7 @@ export declare class LlEmitter {
      * 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;
+    loadRecordField(ptr: string, t: IrType, inline: boolean): string;
     declare(decl: string): void;
     needOom(): void;
     private currentFrame;
@@ -671,7 +706,7 @@ export declare class LlEmitter {
     unionTag(uName: string, unionId: string): string;
     /** Guard for helpers that build or read a union's `%ScrUnion` box
      * directly (library-shaped unions with fixed arms): a nullable union
-     * reaching one is an emitter bug, never a silent miscompile. */
+     * reaching one is an emitter bug and throws InternalCompilerError. */
     requireBoxedUnion(unionId: string): void;
     /** The BORROWED payload pointer of a ref arm (scr_union_peek inlined —
      * the runtime's is a static inline); a nullable union is its payload. */
@@ -702,6 +737,7 @@ export declare class LlEmitter {
     classFieldPtr(objName: string, className: string, field: string): {
         ptr: string;
         type: IrType;
+        inline: boolean;
     };
     /** `o->vt->pre` — the dynamic class's preorder number (borrowed object;
      * the static class names which struct spelling carries the vt word). */
@@ -715,17 +751,35 @@ export declare class LlEmitter {
      * 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). */
+    /** The zeroed `%ScrUnion` constant (inline-unions.ts unionBoxBits). */
+    unionNoneRef(): string;
+    /** The field-slot pointer of a record member (rc header at index 0).
+     * `inline`: the slot stores a scalar union's tag and bits. */
     recordFieldPtr(objName: string, shapeId: string, field: string): {
         ptr: string;
         type: IrType;
+        inline: boolean;
     };
     /** 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;
+    /** Loads a record field (i8-stored bools trunc to i1). An inline union
+     * field answers a private stack box with the slot's own bits, ABSENT
+     * included: it may only be borrowed. */
+    loadField(ptr: string, t: IrType, inline: boolean): string;
+    /** A record field of this shape stores its scalar union inline. */
+    recordFieldInline(shapeId: string, field: string): boolean;
+    /** The value a field store writes: an inline union slot copies the tag
+     * and bits of a borrowed projection, so no box is built for it. */
+    emitFieldValue(value: IrExpr, inline: boolean): LlValue;
+    /** Overwrites a field with `v` (from emitFieldValue). A reference moves
+     * in, and the old value is released AFTER the field is overwritten. */
+    replaceField(ptr: string, type: IrType, inline: boolean, v: LlValue): void;
+    /** Stores `v` (from emitFieldValue) into a fresh field slot. */
+    initField(ptr: string, type: IrType, inline: boolean, v: LlValue): void;
+    /** Stores a record field (i1 zext to the i8 storage). An inline union
+     * field copies the tag and bits of the union value, which its owner
+     * keeps. */
+    storeField(ptr: string, t: IrType, value: string, inline: boolean): void;
     /** Reads an int32-specialized class field: the i32 slot is the value,
      * and its widening is the exact double every program observation sees. */
     loadInt32Field(ptr: string, type: IrType): LlValue;
@@ -802,6 +856,21 @@ export declare class LlEmitter {
      * 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;
+    /** A fresh heap box (+1) for an inline union field's value; the ABSENT
+     * state reads as the undefined arm. */
+    inlineFieldUnion(ptr: string, type: IrType): string;
+    /** boxScalarUnion over a separate tag and payload bits. Unit arms answer
+     * their immortal instances whatever the bits. */
+    boxScalarUnionBits(tag: string, bits: 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. */
@@ -854,6 +923,9 @@ export declare class LlEmitter {
      * 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;
@@ -946,6 +1018,10 @@ export declare class LlEmitter {
      * value, making the snapshot unique unless a real observable alias exists.
      */
     emitStringSelfConcatAssign(localId: string, left: IrExpr, suffix: IrExpr, retainForYield: boolean): LlValue;
+    /** The code of a one-argument `String.fromCharCode(c)` suffix, emitted, so
+     * `s += String.fromCharCode(c)` appends the character without building
+     * the one-character string; null for any other suffix. */
+    private emitSingleCharCode;
     /** `local = local + suffix` when the suffix cannot read or write the
      * local (an unboxed binding is only reachable through this function's own
      * expressions): reading the binding after the suffix gives the value the
@@ -960,6 +1036,12 @@ export declare class LlEmitter {
     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();
@@ -993,11 +1075,16 @@ 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
      * stack box with an independently owned payload (no heap union). */
     isStackUnionSource(e: IrExpr): boolean;
+    /** A read of a record or class field that stores its scalar union
+     * inline. */
+    inlineFieldGet(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;
@@ -1033,6 +1120,8 @@ export declare class LlEmitter {
      * 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;
+    /** The instance of a capsule known to hold exactly this class (borrowed). */
+    emitExactCapsuleObject(value: IrExpr, type: IrType): LlValue;
     canBorrowReceiver(e: IrExpr): boolean;
     /** A reference held as one plain pointer that emitReadReceiver can read
      * without owning: class instances, records, arrays, strings and
@@ -1103,7 +1192,10 @@ export declare class LlEmitter {
     }): string;
     cryptoBytesThunkFor(cbT: IrType & {
         kind: "func";
-    }, arrayBuffer?: boolean): string;
+    }, arrayBuffer?: boolean, valueMode?: BytesThunkValue): string;
+    cryptoIntThunkFor(cbT: IrType & {
+        kind: "func";
+    }): string;
     zlibBytesThunkFor(cbT: IrType & {
         kind: "func";
     }): string;