@scriptc/compiler 0.2.7 → 0.2.8

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

@@ -1,20 +1,24 @@
 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";
+import { type Int32Slots } from "../../ir/int32-slots.js";
 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 { NullableRefFields, type NullableRefField } from "./nullable-fields.js";
 import { OptionalArrayReads, type LocalArrayRead } from "./local-array-reads.js";
+import { CheckedNarrows } from "./checked-narrows.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 PublishedTypes } from "../publication.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 { ExprOf, LibCallExpr, LlStreamTypedRefAdapter, LlValue } from "./expr-context.js";
 export { LlvmUnsupportedError } from "./unsupported.js";
@@ -71,17 +75,23 @@ export declare class LlEmitter {
     readonly ffiExtendNarrowIntegers: boolean;
     readonly cycleColorOffset: number;
     readonly wasi: boolean;
+    /** ELF worker executables give thread-locals the executable TLS models. */
+    private readonly executableTls;
     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;
+    /** Symbols of interned constant data, named by content (contentSymbol). */
+    private readonly contentSymbols;
     /** 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;
     /** unionId → symbol of the union's immortal ABSENT field-slot instance. */
     private readonly absentInstances;
+    /** The nullable-union ABSENT sentinel was referenced (absentInstanceRef). */
+    private needsNullableAbsent;
     private readonly immortalValues;
     /** Regex literal templates: "<flags>/<pattern>" → { symbol, interned
      * source/flags literal refs } — one immortal ScrRegex template per distinct
@@ -131,6 +141,7 @@ export declare class LlEmitter {
     private readonly fnDefText;
     readonly referenceEffects: ReferenceEffects;
     readonly optionalArrayReads: OptionalArrayReads;
+    readonly checkedNarrows: CheckedNarrows;
     callArrayReads: Map<IrExpr, LocalArrayRead>;
     mapReadLifetimes: MapReadLifetimes;
     readonly callLifetimes: CallLifetimes;
@@ -148,6 +159,18 @@ export declare class LlEmitter {
     /** Parameters proven projection-only: callers may pass stack boxes. */
     private projectedParameters;
     private stableCallBindings;
+    /** Locals and rebound parameters holding borrowed pointers for their
+     * whole lifetime (walk-borrows.ts), per function and for the current one. */
+    private readonly walkBorrowsByFunction;
+    private walkBorrows;
+    /** Functions whose borrowing body returns its result without a reference
+     * (analyzeBorrowedReturns), and whether the current body is one. */
+    readonly borrowedReturns: Set<string>;
+    /** Rebound parameters that keep the borrowed convention with an owner
+     * slot (rebound-parameters.ts), per function, and the current owner slots. */
+    private readonly reboundByFunction;
+    private readonly reboundOwnerSlots;
+    private currentBorrowedReturn;
     /** Manifest-bound native imports, used by ffiCall emission. */
     readonly ffiByName: Map<string, IrFfiImport>;
     /** C-ABI callback trampolines and (for raw/no-userdata callbacks) their
@@ -166,6 +189,15 @@ export declare class LlEmitter {
      * checks are emitted only after calls that can actually raise. */
     readonly mayThrow: Set<string>;
     readonly indirectMayThrow: boolean;
+    /** Worker programs: the functions that poll for termination on entry
+     * (workerTerminationPolls); null outside worker programs. */
+    private readonly workerEntryPolls;
+    /** Functions that check the native stack guard on entry
+     * (stackCheckedFunctions); null where the runtime has no guard. */
+    private readonly stackChecks;
+    /** Static types whose values can be published (@scriptc/threads): their
+     * stores carry the frozen-object guard. Null without publish calls. */
+    readonly publishedTypes: PublishedTypes | null;
     /** Method names with at least one may-throw implementation — the
      * virtualCall pending check's key. */
     readonly mayThrowMethods: Set<string>;
@@ -187,6 +219,10 @@ export declare class LlEmitter {
     readonly dynPromiseAdapters: Map<string, string>;
     readonly unionsById: Map<string, IrUnionDef>;
     readonly nullableFields: NullableRefFields;
+    /** Unions whose values are nullable arm pointers (nullable-unions.ts). */
+    readonly nullableUnions: NullableUnions;
+    /** The union table without nullable unions: the stack-box analyses. */
+    readonly boxedUnionsById: Map<string, IrUnionDef>;
     readonly recordsById: Map<string, IrRecordShape>;
     readonly recordCloneShapes: Set<string>;
     readonly tracedShapes: Set<string>;
@@ -194,6 +230,8 @@ export declare class LlEmitter {
     /** The class graph (buildClassGraph): preorder numbering, hierarchy
      * membership, virtual slot lists. */
     readonly classMeta: Map<string, LlClassMeta>;
+    /** Which vtable slots borrow which parameters (virtual-borrows.ts). */
+    private virtualBorrows;
     /** 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. */
@@ -233,6 +271,8 @@ export declare class LlEmitter {
     private storedSplits;
     private streamingSplitsEnabled;
     private readonly initializerBindings;
+    /** Whole-program int32 storage and parameter/result facts. */
+    readonly int32Slots: Int32Slots;
     private numericLocals;
     private captureIds;
     /** Active induction bindings retain their width independently of size_t. */
@@ -293,6 +333,11 @@ export declare class LlEmitter {
     logArgSlots: number;
     private readonly stackTraces;
     constructor(mod: IrModule, options: LlvmTargetOptions);
+    /** The borrowed parameters of a hierarchy's vtable slot (empty: owned). */
+    virtualSlotBorrowed(rootName: string, slotIndex: number): ReadonlySet<number>;
+    /** The vtable entry for one implementation (VirtualBorrows.entry). */
+    virtualEntry(implFn: string): string;
+    private implSlotBorrowed;
     abiOffset(native64: number, wasm32: number): number;
     llType(t: IrType): string;
     ffiCallbackAdapter(binding: string, id: string): FfiCallbackAdapter;
@@ -303,6 +348,7 @@ export declare class LlEmitter {
     private emitFfiCallbackDefs;
     emit(): string;
     emitParts(): string[];
+    private emitModuleParts;
     /** 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
@@ -367,6 +413,12 @@ export declare class LlEmitter {
      * spawn wrapper that only ALLOCATES the suspended fiber, and the
      * never-started teardown that drops the packed (+1) arguments. */
     private emitGenScaffolding;
+    /** A symbol derived from the constant's text rather than its first-use
+     * index, so an edit that interns one more string leaves every other
+     * constant's symbol, and the code referencing it, unchanged. This lets
+     * native builds reuse the compiled partitions an edit does not touch. A
+     * collision retries with a counter, still in first-use order. */
+    private contentSymbol;
     internLiteral(text: string): string;
     /** Interned NUL-terminated C-string constant (the scr_jb_puts /
      * stringify-indent currency) — `@`-ref, first-use order. */
@@ -383,6 +435,9 @@ export declare class LlEmitter {
     /** 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;
+    /** fieldAbsentTest in another block builder (helper generators). A
+     * nullable union's ABSENT state is the module's immortal sentinel. */
+    fieldAbsentTestIn(B: BlockBuilder, 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
@@ -391,6 +446,12 @@ export declare class LlEmitter {
     declare(decl: string): void;
     needOom(): void;
     private currentFrame;
+    /** Whether a value is immortal: an interned constant, or a temp marked by
+     * markImmortal. */
+    private isImmortal;
+    /** Record that a temp holds an immortal value (a choice between interned
+     * literals): nothing owns it, and retains, releases and moves skip it. */
+    markImmortal(v: LlValue): LlValue;
     /** Registers an owned refcounted value on the current statement frame. */
     own(v: LlValue): LlValue;
     /** Registers a SLOT whose current contents the frame owns (conditional
@@ -420,13 +481,40 @@ export declare class LlEmitter {
      * 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. */
+     * `throw` unwinds unconditionally. `passThrough` names a scalar call
+     * result of the function's own return type: with nothing to release, the
+     * unwind returns it as the dummy, so a call in tail position keeps a single
+     * return and stays eligible for tail-call and recursion elimination. */
     private emitUnwind;
+    /** Instructions (two-space indented) that set the i1 `dest` to "an
+     * exception is pending in the active context" — scr_exc_pending()'s
+     * meaning — for the helper and adapter bodies that test it outside
+     * emitPendingCheck. Executables read the runtime's exported active-cell
+     * pointer and compare its i32 kind (offset 0) against SCR_EXC_NONE inline,
+     * as emitPendingCheck does; the out-of-line call would be opaque to LLVM
+     * because the runtime links as prebuilt objects. Libraries and worker
+     * programs keep the runtime call, which is emitPendingCheck's path there
+     * too (workers also observe cross-thread termination in it). */
+    pendingTestLines(dest: string): string[];
     /** 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;
+     * releases the dummy (NULL for refcounted kinds) harmlessly. A scalar
+     * call result of the function's return type may be passed as the unwind's
+     * dummy value (see emitUnwind). */
+    emitPendingCheck(passThrough?: {
+        name: string;
+        type: IrType;
+    }): void;
+    /** After a runtime call that ALWAYS leaves an exception pending (the
+     * compiler-resolved Node throws): the pending test would always answer
+     * true, so unwind unconditionally. Emission continues in a block with no
+     * predecessors so the caller's remaining instructions stay well-formed;
+     * LLVM deletes it. */
+    emitAlwaysPendingUnwind(): void;
+    /** A recursive function's entry check: below the running stack's guard,
+     * throw Node's RangeError and unwind like any other pending exception. */
+    private emitStackCheck;
     private workerLoopBudget;
     private emitWorkerLoopCheck;
     /** Moves an already-evaluated value into the runtime's exception cell —
@@ -442,11 +530,16 @@ export declare class LlEmitter {
     /** 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;
+    /** A union value's tag (i32): the box's tag word, or the NULL test of a
+     * nullable union's pointer. */
+    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. */
+    requireBoxedUnion(unionId: string): void;
     /** The BORROWED payload pointer of a ref arm (scr_union_peek inlined —
-     * the runtime's is a static inline). */
-    unionPeek(uName: string): string;
+     * the runtime's is a static inline); a nullable union is its payload. */
+    unionPeek(uName: string, unionId: 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
@@ -455,7 +548,7 @@ export declare class LlEmitter {
     /** The +1 extraction of a union's single narrowed arm (unionNarrow /
      * the nullish-family reads): scalars via inline payload loads, ref arms
      * a retained peek. */
-    unionExtract(uName: string, arm: IrType): string;
+    unionExtract(uName: string, unionId: 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;
@@ -464,7 +557,7 @@ export declare class LlEmitter {
     /** 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;
+    unionNewOwned(unionId: string, 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
@@ -497,6 +590,12 @@ export declare class LlEmitter {
     loadField(ptr: string, t: IrType): string;
     /** Stores a record field (i1 zext to the i8 storage). */
     storeField(ptr: string, t: IrType, value: string): 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;
+    /** Stores a value the whole-program analysis proved to be an int32 (never
+     * -0, NaN or fractional) into an int32-specialized class field. */
+    storeInt32Field(ptr: string, value: LlValue, expr: IrExpr): 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): {
@@ -556,6 +655,9 @@ export declare class LlEmitter {
      * 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
+     * slot's parameters stay borrowed, the body's other borrowed ones are
+     * released here. */
     private emitOwnedCallAdapter;
     /** A local stable binding keeps its value alive while later arguments
      * and the callee execute. A proven local union box cannot escape or be
@@ -615,6 +717,22 @@ export declare class LlEmitter {
     emitBranchInto(slot: string, expr: IrExpr, integerSlot?: string): boolean;
     emitLiteralExpr(e: ExprOf<"numLit" | "boolLit" | "strLit" | "moduleNsRef" | "unitLit" | "varRef">): LlValue;
     emitOperatorExpr(e: ExprOf<"bin" | "unary" | "incDec" | "fieldIncDec" | "assignExpr" | "seqExpr">): LlValue;
+    /** Saved operands can feed later call arguments. Transfer ownership of a
+     * sequence's locals to this expression's frame so they survive those
+     * reads and still die on the path that created them, including inside
+     * lazy branches. */
+    private emitSequence;
+    /** A statement-position expression whose value is dropped. When a
+     * sequence's result only reads an unchanged local (a derived
+     * constructor's `super()` evaluates to `this`), its statements still run
+     * in place, but the result is neither retained nor released. */
+    /** Whether a discarded value can be skipped entirely: a borrowable read
+     * with no effect of its own. canBorrowCallArgument also accepts checked
+     * projections (a ternary or narrow whose failing arm throws, and the
+     * throwing call itself) because a borrowed use still evaluates them;
+     * skipping those would drop the throw. */
+    private discardableRead;
+    private emitDiscarded;
     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;
     /**
@@ -624,11 +742,39 @@ 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;
+    /** `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
+     * left side had, so it moves into a consuming concat, and the result takes
+     * its place. Null when the general snapshot path is needed. */
+    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;
     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;
+    private publishWalkersCache;
+    /** Per-type publication walkers, created on the first publish. */
+    private get publishWalkers();
+    /** `publish(value)` (@scriptc/threads): makes the graph immortal and
+     * immutable (scr_publish with the static type's walker) and answers the
+     * same value. Throws (pending) when a dyn part is unpublishable. */
+    private emitPublish;
+    /** Branches on "`obj` is published" (rc == SIZE_MAX); leaves the builder
+     * in the cold block and answers the continuation label. */
+    private emitPublishedTest;
+    private publishedNamesSym;
+    /** The class-name table the hierarchy field guards index by preorder. */
+    private publishedClassNamesDefs;
+    /** The frozen-object guard of a class field or record field store:
+     * Node's "Cannot assign to read only property" TypeError when the target
+     * is published. `className` null means a record (`#<Object>`). */
+    emitPublishedFieldGuard(obj: string, className: string | null, field: string): void;
+    /** The frozen-array guard (scr_throw_published_array's ops): `index` and
+     * `count` are doubles (the written index, the argument count). */
+    emitPublishedArrayGuard(arr: string, arrType: IrType, op: number, index?: string, count?: string): void;
+    /** The published Map/Set guard: "Cannot modify a published Map/Set". */
+    emitPublishedCollectionGuard(m: string, t: IrType): void;
     emitSerializationExpr(e: ExprOf<"jsonStringify" | "dynCheck">): LlValue;
     emitAsyncExpr(e: ExprOf<"yieldExpr" | "genResume" | "awaitExpr" | "awaitUnionExpr" | "newPromise" | "promiseWithResolvers">): LlValue;
     emitJsInteropExpr(e: ExprOf<"jsMarshal" | "jsOp" | "jsExit" | "jsBridgePromise">): LlValue;
@@ -679,6 +825,33 @@ export declare class LlEmitter {
      * box must only be projected: never retained, released, or stored. */
     isStackUnionLocal(localId: string): boolean;
     canBorrowReceiver(e: IrExpr): boolean;
+    /** A reference held as one plain pointer that emitReadReceiver can read
+     * without owning: class instances, records, arrays, strings and
+     * nullable-pointer unions. Tagged union boxes, closures and dynamic
+     * values keep ordinary ownership. */
+    plainReference(type: IrType): boolean;
+    /** Functions returning a walk of their borrowed parameters return it
+     * without a reference (+0) from their borrowing body; direct callers
+     * either consume it as a receiver/walk or retain it at once, and the owned
+     * adapter retains before releasing its parameters. Candidates preserve
+     * every heap edge (so the result stays reachable from the arguments),
+     * borrow every reference parameter and return plain pointers. The set
+     * grows to a fixpoint because a call to a borrowed-return function with
+     * walk arguments is itself a walk; walk facts are then recomputed with
+     * the final set, admitting only parameters whose convention borrows. */
+    private analyzeBorrowedReturns;
+    /** emitReadReceiver produces this node's pointer without acquiring a
+     * reference, given operands (and ternary arms) that do the same: plain
+     * class/record field reads, class casts, nullable-pointer narrows and
+     * wraps, and checked ternaries. Stack-boxed, map-read and boxed-field
+     * sources are owned. Depends only on module facts, not the current
+     * function. */
+    borrowsWithoutOwning(e: IrExpr): boolean;
+    /** A wrap into a nullable-pointer union is the payload pointer itself
+     * (the reference arm) or an immortal constant (a unit arm), so it can
+     * borrow exactly when its payload can. Void payloads run for effects and
+     * keep the ordinary path; tagged unions still construct a box. */
+    borrowableNullableWrap(e: IrExpr): "unit" | "ref" | null;
     materializeSplitLocal(localId: string): void;
     emitExpr(e: IrExpr): LlValue;
     emitJsMarshal(e: IrExpr & {
@@ -740,7 +913,7 @@ export declare class LlEmitter {
     }): string;
     streamCbThunkFor(kind: "r" | "w" | "f" | "d" | "t" | "l" | "e", cbT: IrType): string;
     resolveThunkFor(inner: IrType): string;
-    tagInSet(uName: string, tags: number[]): string;
+    tagInSet(uName: string, unionId: 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 & {
@@ -767,7 +940,7 @@ export declare class LlEmitter {
     emitBytesIndex(receiver: string, index: LlValue, expr?: IrExpr, inBounds?: boolean): string;
     emitBytesData(receiver: string): string;
     emitBytesLength(elem: IrBytesElem, receiver: string, bytes: boolean): LlValue;
-    emitBytesGet(elem: IrBytesElem, receiver: string, index: LlValue, expr?: IrExpr, inBounds?: boolean): LlValue;
+    emitBytesGet(elem: IrBytesElem, receiver: string, index: LlValue, expr?: IrExpr, inBounds?: boolean, invalidNaN?: boolean): LlValue;
     emitToUint32(value: string, expr?: IrExpr, uint32?: string): string;
     storeIntegerView(localId: string, value: LlValue, expr?: IrExpr): void;
     private emitBytesSet;