@geastack/compiler 1.0.15

package/dist/ir/integers.d.ts

@@ -0,0 +1,161 @@
+import type { DeclarationId, IrValueId } from '../identity/ids.js';
+import type { IrBody } from './model.js';
+/**
+ * Which `number` values a body may hold in a 64-bit integer instead of a
+ * double, and why the answer is a MAGNITUDE question rather than a type one.
+ *
+ * Every JS number is a double, so narrowing one to `long long` is only
+ * observationally neutral while the two agree -- which they do exactly while
+ * the value is an integer whose magnitude stays under 2^53. Above that a
+ * double starts rounding and an integer does not, so the two computations
+ * diverge, and the program's own answer changes. The benchmark fixtures are
+ * built around precisely that: `loop_overhead` accumulates `total += i` past
+ * 2^53 on purpose and its hand-written baseline keeps `total` a double to
+ * reproduce node's rounded sum, and `factorial`'s `acc * i` leaves the exact
+ * range within nine million iterations, which is why ITS baseline carries a
+ * `p < 2^53` guard. A narrowing that reads only "is this an integer" turns
+ * both of those into silently different programs.
+ *
+ * So each value carries how big it can get:
+ *
+ *   - `bounded(k)` -- never exceeds a constant `k`. A literal, a `% C`, a
+ *     masked bitwise result, an array's `length`, a counter whose loop test
+ *     compares it against something bounded.
+ *   - `linear(c)` -- grows at most `c` per loop iteration. A counter stepping
+ *     by one is `linear(1)`; `i * 3` is `linear(3)`.
+ *
+ * A `bounded` value narrows when its bound is under 2^53: the two carriers
+ * cannot disagree. A `linear` value narrows when its coefficient is small,
+ * because reaching 2^53 then costs 2^53/c iterations -- for c at or under 256
+ * that is at least 2^45 turns of a loop, which no program that terminates will
+ * execute. Everything else stays a double. `total += i` is a linear increment
+ * of a linear value and has no coefficient at all -- it is quadratic, and 2^53
+ * arrives after 2^27 iterations, so it is refused. `acc * i` multiplies a
+ * value bounded by a billion by a counter, giving `linear(1000000007)`, far
+ * over the cap, so it is refused too. Both keep the double their baselines
+ * keep, for the same reason.
+ *
+ * What this deliberately does NOT model is the loop trip count as a symbol: a
+ * counter bounded by a `number` PARAMETER is `linear`, not `bounded`, because
+ * nothing here knows what the caller passes.
+ */
+export interface IntegerNarrowing {
+    /** SSA values whose C++ storage may be `long long`. */
+    readonly values: ReadonlySet<IrValueId>;
+    /** Binding cells whose C++ storage may be `long long`. Every read of one is in `values`. */
+    readonly bindings: ReadonlySet<DeclarationId>;
+    /**
+     * How large each value this body examined can get.
+     *
+     * Published because a whole-program census over STORAGE -- a record field, an
+     * array's element -- has to widen the magnitudes of every write to one slot,
+     * and those writes are in bodies this call never sees. Reading them back out
+     * is what lets that census reach an answer without a second lattice of its
+     * own to disagree with this one.
+     */
+    readonly magnitudes: ReadonlyMap<IrValueId, IntegerMagnitude>;
+    /**
+     * Values that are integers at all, whatever their magnitude.
+     *
+     * Separate from `values` because the two questions settle in opposite
+     * directions: integrality is an optimistic fixed point (see below) and a
+     * whole-program census has to run it to convergence before any magnitude is
+     * meaningful.
+     */
+    readonly integral: ReadonlySet<IrValueId>;
+    /**
+     * `%` results whose dividend is an integer of ANY size and whose divisor is a
+     * non-zero constant.
+     *
+     * Narrower than `values`, and deliberately: a remainder is bounded by its
+     * divisor, so a `%` in `values` is one this body can hold in a `long long`
+     * outright. This is the case one step short of that -- `acc = (acc * i) % MOD`
+     * in `factorial.ts`, whose dividend runs past 2^53 and must stay a `double` --
+     * where the DIVISION is still an integer one. What it buys is skipping the
+     * round trip `gea::remainder` pays to discover at run time what this already
+     * knows: two conversions, two equality checks and a range test, on the
+     * loop-carried dependency of a modular accumulation.
+     */
+    readonly integralRemainders: ReadonlySet<IrValueId>;
+    /**
+     * `%` results whose dividend AND divisor are both integers, but whose divisor
+     * is not a constant this census can read -- `i % ring.length`, the shape
+     * every ring buffer and hash bucket is written in.
+     *
+     * Distinct from `integralRemainders` because the divisor's non-zeroness is
+     * the thing that cannot be settled here: `x % 0` is NaN in the language and
+     * a fault in C++, so the answer stays a double and the emitted form tests the
+     * divisor at run time. That test costs a perfectly predicted branch; `fmod`
+     * costs a libcall.
+     */
+    readonly dynamicRemainders: ReadonlySet<IrValueId>;
+}
+export declare const emptyIntegerNarrowing: IntegerNarrowing;
+/**
+ * What a whole-program census over storage knows that one body cannot.
+ *
+ * A field of a record and an element of an Array are one storage shared by
+ * every body that touches them, so whether either holds an integer is not a
+ * question a single body can answer -- and it is exactly the question that
+ * decides whether `total = (total + o.x + o.y + o.z) % 1000000000` is four
+ * integer operations or four calls into `fmod`. The census that answers it
+ * lives outside this file; what arrives here is its conclusion, keyed by
+ * whatever slot identity that census uses.
+ */
+export interface IntegerStorageFacts {
+    /** The storage slot each `get` result in this body reads, where the census identified one. */
+    readonly reads: ReadonlyMap<IrValueId, string>;
+    /** Slots that hold an integer. */
+    readonly integral: ReadonlySet<string>;
+    /** The magnitude each integral slot holds, where the census settled one. */
+    readonly magnitudes: ReadonlyMap<string, IntegerMagnitude>;
+}
+export type IntegerMagnitude = {
+    readonly kind: 'bounded';
+    readonly limit: number;
+} | {
+    readonly kind: 'linear';
+    readonly coefficient: number;
+};
+type Magnitude = IntegerMagnitude;
+/**
+ * A value that grows by at most `coefficient` each time the thing that produces
+ * it runs again -- the same judgement `growsBy` makes for a loop counter,
+ * published for the whole-program census over storage.
+ *
+ * A RECURSION is a loop for this purpose and the argument is the one the cap
+ * was set from: `fib(n - 1)` steps its own formal by one per call, so reaching
+ * 2^53 would take 2^53 nested frames and the stack ends the program first.
+ */
+export declare const integerLinearMagnitude: (coefficient: number) => IntegerMagnitude | null;
+/**
+ * The worse of two magnitudes -- what a value reachable by either path can be.
+ *
+ * Exported because a whole-program census over STORAGE has exactly this join to
+ * perform: one record field is written from many bodies, and the magnitude it
+ * holds is the worse of all of them. Reusing this rather than restating it is
+ * what keeps the two censuses one lattice instead of two that can disagree.
+ */
+export declare const widenIntegerMagnitude: (left: Magnitude | null, right: Magnitude | null) => Magnitude | null;
+/**
+ * The magnitude model for one body, and the narrowing it implies.
+ *
+ * A cell is judged as a whole -- every write into it and every read out of it
+ * share one storage, so they share one answer. A counter is recognized here
+ * rather than fixed up afterwards, because the recurrence `i = i + 1` is a
+ * cycle: asking for its magnitude by walking its operands would ask for its
+ * own magnitude, and the honest reading of that cycle is "grows by the step".
+ */
+export declare const narrowableIntegersOf: (body: IrBody, storage?: IntegerStorageFacts) => IntegerNarrowing;
+/**
+ * Which spelling of `%` an operation gets, or `null` for the general one.
+ *
+ * `'narrowed'`: both sides are held in a `long long`, so C++'s own `%` is the
+ * answer -- ECMA-262 6.1.6.1.6 truncates toward zero exactly as C++ does.
+ * `'restated'` and `'dynamic'` are the two integer-valued-but-not-narrowed
+ * cases the census separates (`ir/integers.ts`); everything else keeps
+ * `gea::remainder`, which rediscovers at run time what neither could prove.
+ */
+/** The two cheaper `%` spellings the census settled, as the emitter records them: one pass, so `emit.ts` states the wiring once. */
+export declare const remainderFormGroups: (narrowed: IntegerNarrowing) => readonly (readonly [form: "restated" | "dynamic", values: ReadonlySet<IrValueId>])[];
+export {};