@scriptc/compiler 0.3.4 → 0.3.5

package/dist/ir/capture-values.d.ts

@@ -0,0 +1,107 @@
+import { type IrFunction, type IrModule } from "./ir.js";
+/** Captured bindings that hold one value for their whole observable life
+ * read through plain immutable locals.
+ *
+ * A captured binding lives in a shared box: the declaring function and
+ * every closure environment that captures it address the same cell, so a
+ * write anywhere is visible everywhere. When nothing ever writes the cell
+ * after its declaration fills it, the box is only a carrier: every read
+ * observes the declaration's value. Analyses and code generation exclude
+ * boxed locals, though, so a boxed `const N` turns all integer index math
+ * that reads it into checked f64 arithmetic and every reference read into
+ * an out-of-line retained box load.
+ *
+ * This pass keeps the boxes (environments still capture and trace them
+ * exactly as before, so ownership and cycle collection are unchanged) and
+ * moves the reads onto plain locals:
+ *
+ * - In the declaring function, `varDecl x = init` becomes
+ *   `varDecl x' = init; varDecl x = x'`, and every read of `x` reads `x'`.
+ *   An unchanged captured number parameter `p` gets `varDecl p' = p` at
+ *   entry in the same way.
+ * - In a closure body, an entry `varDecl c' = c` copies the environment's
+ *   value once and every read of `c` reads `c'`. When every creation site
+ *   captures a declaration of the same closed numeric constant, `c'`
+ *   starts from that literal instead, so range analysis sees the constant.
+ *
+ * Nested environments still capture the original box. A call through such
+ * a binding whose only value is an environment-free function (a nested
+ * function declaration or arrow that captures nothing) becomes a direct
+ * call of a capture-free copy of that body, as a call of a top-level
+ * function is: the closure value itself still exists for every other use.
+ *
+ * Soundness. A binding qualifies when its box is filled exactly once
+ * before any environment can observe it and nothing rebinds it in any
+ * function that shares the box:
+ *
+ * - the declaration is the binding's only `varDecl` and has an
+ *   initializer that does not itself create an environment over it; a
+ *   temporal-dead-zone binding (an environment exists before its
+ *   initializing `assign`) qualifies only when no code can run any such
+ *   environment, or read the binding, before that assignment (orderedTdz),
+ *   and otherwise keeps every checked read,
+ * - no `assign`, `assignExpr`, `incDec`, `forOf`, catch or rethrow binding
+ *   targets it, here or in any closure body reached through capture edges,
+ * - local classes keep their boxes (method bodies are not followed).
+ *
+ * A closure capture qualifies when every creation site supplies such a
+ * binding, an unchanged parameter, or a qualifying capture of the creating
+ * closure. A closure can only run after its creation, so its entry copy
+ * reads the final value. Every execution of a declaration (for example
+ * per loop iteration) fills its own fresh box, so environments created in
+ * different iterations keep seeing their own value. */
+export declare function copyStableCaptures(mod: IrModule): IrModule;
+/** Capture-flow facts over the whole module. Capture chains follow lexical
+ * nesting and cannot cycle; provisional memo entries only bound work on
+ * malformed input. */
+export declare class CaptureFlow {
+    private readonly functions;
+    private readonly facts;
+    private readonly unchangedMemo;
+    private readonly stableMemo;
+    private readonly sites;
+    private readonly receivers;
+    private readonly directMemo;
+    /** Environment-free bodies called directly, and their copies' names. */
+    private readonly clones;
+    constructor(functions: readonly IrFunction[]);
+    directClones(): ReadonlyMap<string, string>;
+    /** A lifted body that captures nothing and can be entered like a declared
+     * function: synchronous, never naming its own closure, and unable to
+     * observe the ambient receiver a closure call would bracket. */
+    private direct;
+    /** The environment-free function every execution binds to `id`, if any. */
+    private target;
+    private readonly statementIds;
+    /** The bindings a statement reads (with counts) and captures, at any depth. */
+    private idsIn;
+    /** Reads of `id` in the statements of `body` after index `after`. */
+    private readsAfter;
+    /** A temporal-dead-zone binding no read can reach before its
+     * initialization: every environment created before the initializing
+     * assignment is the direct value of an unshared local of this function
+     * whose every read follows that assignment, and so is every read of the
+     * binding itself. Its box is then filled before any code can observe it. */
+    private orderedTdz;
+    /** An unboxed binding (no environment shares it) of `fn` itself that
+     * holds its single definition from its first read on. */
+    private plainConstant;
+    /** `callValue` through a binding bound to one environment-free function,
+     * as a direct call of its capture-free copy. */
+    private directCall;
+    private factsOf;
+    private local;
+    /** Nothing rebinds `id` in `fnName` (declarations aside, and `ownWrites`
+     * writes of its own body) or in any body that shares its box through
+     * closure captures. */
+    unchanged(fnName: string, id: string, ownWrites?: number): boolean;
+    /** A boxed binding of `fn` itself (not a capture) whose box is filled
+     * once, before any environment observes it, and never written again. */
+    stableOrigin(fn: IrFunction, id: string): boolean;
+    /** A closure capture holding one value for the environment's life. */
+    stableCapture(fnName: string, id: string): boolean;
+    private computeStableCapture;
+    /** The numeric constant every execution binds to `id`, if any. */
+    private literal;
+    rewrite(fn: IrFunction): IrFunction;
+}