@scriptc/compiler 0.2.7 → 0.2.8

package/dist/ir/int32-slots.d.ts

@@ -0,0 +1,72 @@
+import type { IrClassDef, IrExpr, IrModule } from "./ir.js";
+import { type IntegerSlotFacts } from "./integer-ranges.js";
+/** Whole-program int32 specialization of numeric storage.
+ *
+ * A class field typed `number` whose every write provably stores an int32
+ * (never -0, never NaN, never a fraction or an out-of-range integer) can be
+ * stored as an i32: reading it back as a double is exact, so every program
+ * observation is unchanged. The same proof seeds parameters of functions
+ * that are only ever called directly (every call site passes an int32) and
+ * results of functions whose every return is an int32. Parameter and result
+ * ABIs stay double; only the facts reach the callee and the call sites.
+ *
+ * The analysis is optimistic: every candidate slot starts as int32, each
+ * function is analyzed by analyzeIntegerRanges under the current facts, and
+ * any write the analysis cannot prove disqualifies its slot. Functions that
+ * read a disqualified slot are analyzed again, until no write fails. At the
+ * fixpoint every assumption was proven against every write.
+ *
+ * Writes the IR does not show disqualify a slot up front. Instances that
+ * reach checked-dynamic code get live views whose runtime stores commit
+ * back into the fields; a field of such a class stays a double when any
+ * dynamic store in the program can name it (literal-keyed stores name one
+ * property, every other store any property, islands everything). Classes
+ * with runtime-provided ancestors, generic families, fields under
+ * `++`/`--`, and parameters of functions that escape as values, are
+ * constructed through class values, or are virtual-dispatch targets are
+ * excluded as well. Library builds keep ordinary storage: their instances
+ * cross a native boundary. Worker builds do not: instances reach another
+ * thread only through postMessage/workerData, whose dyn views read (and
+ * commit) fields like every other dynamic reader. Reads are never
+ * restricted: every reader (static code, dyn views, JSON, inspect) widens
+ * the i32 exactly. */
+export declare class Int32Slots {
+    private readonly classes;
+    /** Field families (topmost declaring class and field) stored as i32. */
+    private readonly fields;
+    private readonly familyOf;
+    private readonly paramFacts;
+    private readonly returns;
+    /** Captured-binding groups (one shared box) that hold an int32, and the
+     * group of each `function\0local` member. */
+    private readonly boxes;
+    private readonly boxGroupOf;
+    /** Field write values proven int32 by the final analysis. */
+    readonly provenWrites: Set<IrExpr>;
+    /** Disqualified candidates and the first reason, for tests. */
+    readonly reasons: Map<string, string>;
+    constructor(classes?: ReadonlyMap<string, IrClassDef>);
+    /** The family key of a class field: the topmost class in the base chain
+     * that declares a field of that name (all subclasses share its slot). */
+    family(className: string, field: string): string | null;
+    isField(className: string, field: string): boolean;
+    /** The facts analyzeIntegerRanges may assume inside one function. */
+    facts(fnName: string): IntegerSlotFacts;
+    boxGroup(fnName: string, localId: string): string | null;
+    addBox(group: string, members: readonly string[]): void;
+    dropBox(group: string): boolean;
+    hasBox(group: string | null): boolean;
+    addField(family: string): void;
+    dropField(family: string): boolean;
+    hasFamily(family: string): boolean;
+    addParam(fnName: string, localId: string): void;
+    dropParam(fnName: string, localId: string): boolean;
+    hasParam(fnName: string, localId: string): boolean;
+    addReturn(fnName: string): void;
+    dropReturn(fnName: string): boolean;
+    hasReturn(fnName: string): boolean;
+    get fieldCount(): number;
+    get returnCount(): number;
+    get paramCount(): number;
+}
+export declare function analyzeInt32Slots(mod: IrModule): Int32Slots;