functionalscript 0.46.0 → 0.47.0

package/fjs/types/bigfloat/module.f.mjs

@@ -3,46 +3,49 @@
  *
  * @module
  *
- * @import { BigFloat } from './types.ts'
+ * @import { BigFloat, Format } from './types.ts'
+ * @import { Nullable } from '../nullable/types.ts'
  */
 
-import { abs, sign } from '../bigint/module.f.mjs'
+import { abs, bitLength, mask, sign } from '../bigint/module.f.mjs'
 
-/** @typedef {readonly [BigFloat, bigint]} _BigFloatWithRemainder */
+/**
+ * A magnitude that has been truncated, paired with what was cut off: the exact
+ * value is `m * 2^e` when `r` is `0n`, and strictly between `m * 2^e` and
+ * `(m + 1) * 2^e` otherwise. Only `r === 0n` is ever asked, so any non-zero
+ * `r` — a division remainder, the bits a shift dropped, or both — says the
+ * same thing.
+ *
+ * @typedef {readonly [BigFloat, bigint]} _BigFloatWithRemainder
+ */
 
-const twoPow53 = 0b0010_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n
-const twoPow54 = 0b0100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n
+/** @type {(exp: number) => bigint} */
+const twoPow = exp => 1n << BigInt(exp)
 
 /**
- * Shifts the mantissa magnitude one bit at a time, compensating the exponent,
- * until `done(magnitude, bound)` holds; the sign is restored on return.
- * A zero mantissa is returned unchanged: it can never satisfy a lower bound,
- * so shifting it would not terminate.
- *
- * @param {(m: bigint) => bigint} shift
- * @param {number} de
- * @param {(m: bigint, bound: bigint) => boolean} done
- * @returns {(_: BigFloat) => (bound: bigint) => BigFloat}
+ * Doubles the mantissa magnitude one bit at a time, compensating the exponent,
+ * until it reaches `min`; the sign is restored on return. A zero mantissa is
+ * returned unchanged: it can never reach a lower bound, so shifting it would
+ * not terminate.
+ *
+ * There is no downward twin: a magnitude that overshoots is brought back by
+ * `truncate`, which has to know what it cut off and so cannot be a shift loop.
+ *
+ * @type {(_: BigFloat) => (min: bigint) => BigFloat}
  */
-const normalizeMantissa = (shift, de, done) => ([m, e]) => bound => {
+const increaseMantissa = ([m, e]) => min => {
     if (m === 0n) {
         return [m, e]
     }
     const s = sign(m)
     m = abs(m)
-    while (true) {
-        if (done(m, bound)) {
-            return [BigInt(s) * m, e]
-        }
-        m = shift(m)
-        e += de
+    while (m < min) {
+        m <<= 1n
+        e -= 1
     }
+    return [BigInt(s) * m, e]
 }
 
-const increaseMantissa = normalizeMantissa(m => m << 1n, -1, (m, min) => m >= min)
-
-const decreaseMantissa = normalizeMantissa(m => m >> 1n, +1, (m, max) => m < max)
-
 /** @type {(base: bigint) => (exp: number) => bigint} */
 const pow = base => exp => base ** BigInt(exp)
 
@@ -54,6 +57,21 @@ export const multiply = ([m, e]) => mul => [m * mul, e]
 /** @type {(_: BigFloat) => (div: bigint) => _BigFloatWithRemainder} */
 const divide = ([m, e]) => div => [[m / div, e], m % div]
 
+/**
+ * IEEE-754 binary64 — the format of a JavaScript `number`.
+ *
+ * Both exponents are *ulp* exponents, the same units a `BigFloat`'s own
+ * exponent is in: `minExp` is the exponent of the smallest subnormal
+ * (`2^-1074`), not the smallest normal's `-1022`, and `maxExp` is the exponent
+ * the largest finite value carries once its mantissa fills `precision` bits
+ * (`(2^53 - 1) * 2^971`). The two conventions differ by the precision, and a
+ * `Format` that mixes them is off by exactly that much, so this one never
+ * leaves `BigFloat`'s units.
+ *
+ * @type {Format}
+ */
+export const binary64 = { precision: 53, minExp: -1074, maxExp: 971 }
+
 /**
  * Runs `f` on the magnitude `[abs(m), e]` and restores the sign of `m` on the
  * result: operations on signed mantissas factor through the magnitude.
@@ -63,25 +81,66 @@ const divide = ([m, e]) => div => [[m / div, e], m % div]
 const withSign = (m, e) => f => multiply(f([abs(m), e]))(BigInt(sign(m)))
 
 /**
- * Re-normalizes a magnitude that rounding carried out of 53 bits: rounding
- * `2^53 - 1` up yields exactly `2^53`, one bit wider than `round53` promises.
- * The bit shifted out is always 0 there, so the value is unchanged and no
- * second rounding decision is needed.
+ * Truncates a magnitude to `precision + 1` bits, folding the bits it drops
+ * into the remainder. A magnitude already that narrow is returned unchanged.
+ *
+ * @type {(precision: number) => (_: _BigFloatWithRemainder) => _BigFloatWithRemainder}
+ */
+const truncate = precision => ([[m, e], r]) => {
+    const k = bitLength(m) - BigInt(precision + 1)
+    return k <= 0n ? [[m, e], r] : [[m >> k, e + Number(k)], r | (m & mask(k))]
+}
+
+/**
+ * Scales a non-zero decimal magnitude `dm * 10^de` into `[[m, e], r]` where
+ * `m` holds exactly `precision + 1` bits.
+ *
+ * One bit more than the precision is kept on purpose. Truncating to *any*
+ * position at or below the bit the rounding turns on, plus a remainder saying
+ * whether anything was cut off, is everything a single correctly-rounded
+ * decision needs — at this precision or at any coarser one, which is what
+ * makes the subnormal range reachable without rounding twice.
  *
- * @type {(magnitude: BigFloat) => BigFloat}
+ * @type {(precision: number) => (magnitude: BigFloat) => _BigFloatWithRemainder}
  */
-const renormalize53 = ([m, e]) => m === twoPow53 ? [m >> 1n, e + 1] : [m, e]
-
-/** @type {(_: _BigFloatWithRemainder) => BigFloat} */
-const round53 = ([[m, e], r]) =>
-    withSign(m, e)(([mAbs]) => {
-        const [m54, e54] = decreaseMantissa([mAbs, e])(twoPow54)
-        const o54 = m54 & 1n
-        const m53 = m54 >> 1n
-        const e53 = e54 + 1
-        const tie = o54 === 1n && r === 0n && mAbs === m54 >> BigInt(e - e54)
-        return renormalize53([m53 + (tie ? m53 & 1n : o54), e53])
-    })
+const scale = precision => ([dm, de]) => {
+    const lo = twoPow(precision)
+    if (de >= 0) {
+        // `dm * 10^de` is a whole number, so nothing is lost until `truncate`.
+        return truncate(precision)([increaseMantissa([dm * pow5(de), de])(lo), 0n])
+    }
+    const p5 = pow5(-de)
+    return truncate(precision)(divide(increaseMantissa([dm, de])(p5 * lo))(p5))
+}
+
+/**
+ * Rounds a truncated magnitude to a multiple of `2^(e + k)`, ties to even.
+ *
+ * `k` is at least 1, so the bit the decision turns on is still inside `m`:
+ * `dropped` against `half` is the comparison against the midpoint, and a
+ * non-zero remainder is what lifts an apparent midpoint above it.
+ *
+ * @type {(k: number) => (_: _BigFloatWithRemainder) => BigFloat}
+ */
+const round = k => ([[m, e], r]) => {
+    const kb = BigInt(k)
+    const q = m >> kb
+    const dropped = m & mask(kb)
+    const half = 1n << (kb - 1n)
+    const up = dropped > half || (dropped === half && (r !== 0n || (q & 1n) === 1n))
+    return [up ? q + 1n : q, e + k]
+}
+
+/**
+ * Re-normalizes a magnitude that rounding carried out of `precision` bits:
+ * rounding `2^precision - 1` up yields exactly `2^precision`, one bit wider
+ * than the caller promises. The bit shifted out is always 0 there, so the
+ * value is unchanged and no second rounding decision is needed.
+ *
+ * @type {(precision: number) => (magnitude: BigFloat) => BigFloat}
+ */
+const renormalize = precision => ([m, e]) =>
+    m === twoPow(precision) ? [m >> 1n, e + 1] : [m, e]
 
 /**
  * Converts a decimal big-float `m * 10^e` into the nearest binary big-float,
@@ -92,29 +151,58 @@ const round53 = ([[m, e], r]) =>
  * even when rounding carries out of the top bit.
  *
  * The **exponent is unbounded**: this is the correctly-rounded 53-bit value,
- * not a `number`. Nothing here knows binary64's exponent range, so a result
- * is neither turned into an infinity when it is too large for a `double` nor
- * cut down to the fewer-than-53 bits a subnormal actually carries. A consumer
- * that rounds one of these results onto the subnormal grid therefore rounds
- * twice and can land an ulp away from the correctly-rounded `double`: reaching
- * the subnormal range needs a single rounding to a precision chosen from the
- * target exponent, which this function does not offer yet.
+ * not a `number`. A result too large for a `double` is not turned into an
+ * infinity, and one below the normal range keeps all 53 bits instead of the
+ * fewer a subnormal carries. That is the honest answer when the target is not
+ * a `double` — and the wrong starting point when it is, because rounding one
+ * of these results onto the subnormal grid rounds twice and can land an ulp
+ * away from the correctly-rounded `double`. Use {@link tryDecToFormat} with
+ * {@link binary64} for that; it rounds once.
  *
  * @type {(dec: BigFloat) => BigFloat}
  */
-export const decToBin = dec => {
-    if (dec[0] === 0n) {
+export const decToBin = ([dm, de]) => {
+    if (dm === 0n) {
+        return [0n, 0]
+    }
+    const { precision } = binary64
+    return withSign(dm, de)(magnitude =>
+        renormalize(precision)(round(1)(scale(precision)(magnitude))))
+}
+
+/**
+ * Converts a decimal big-float `m * 10^e` into the nearest value of `format`,
+ * rounding ties to even, or `null` when the magnitude is too large for the
+ * format to hold — the caller decides what an overflow becomes, since
+ * `BigFloat` has no encoding for an infinity.
+ *
+ * The result is a multiple of `2^format.minExp` carrying **at most**
+ * `format.precision` significant bits: exactly that many above the format's
+ * normal range, fewer below it, and `[0n, 0]` when the value rounds away
+ * entirely. Underflow to zero is not a separate signal, because `[0n, 0]` is
+ * the correctly-rounded answer rather than a failure to produce one.
+ *
+ * The rounding happens **once**, on the exact decimal, which is the whole
+ * point of taking the format rather than post-processing {@link decToBin}. The
+ * grid it rounds onto is `2^max(minExp, e + 1)`, where `e + 1` is the exponent
+ * a full-precision result would carry: full precision above the normal range's
+ * floor, shrinking by a bit per binade below it, down to none at all. Rounding
+ * to `precision` bits first and onto that grid afterwards is two roundings,
+ * and the first can manufacture a midpoint the true value only approached.
+ *
+ * @type {(format: Format) => (dec: BigFloat) => Nullable<BigFloat>}
+ */
+export const tryDecToFormat = ({ precision, minExp, maxExp }) => ([dm, de]) => {
+    if (dm === 0n) {
         return [0n, 0]
     }
-    if (dec[1] >= 0) {
-        /** @type {BigFloat} */
-        const bin = [dec[0] * pow5(dec[1]), dec[1]]
-        const inc = increaseMantissa(bin)(twoPow53)
-        return round53([inc, 0n])
+    const scaled = scale(precision)([abs(dm), de])
+    const [, e] = scaled[0]
+    const [m, resultE] = renormalize(precision)(round(Math.max(minExp - e, 1))(scaled))
+    if (bitLength(m) + BigInt(resultE) > BigInt(precision + maxExp)) {
+        return null
     }
-    const p = pow5(-dec[1])
-    const [m, e] = increaseMantissa(dec)(p * twoPow53)
-    return withSign(m, e)(magnitude => round53(divide(magnitude)(p)))
+    return m === 0n ? [0n, 0] : multiply([m, resultE])(BigInt(sign(dm)))
 }
 
 export const proof = {

package/fjs/types/bigfloat/proof.f.d.mts

@@ -3,4 +3,6 @@ export declare const proof: {
     roundingPositive: (() => void)[];
     roundingNegative: (() => void)[];
     roundingCarry: (() => void)[];
+    tryDecToFormat: (() => void)[];
+    binary64AgreesWithNumber: () => void;
 };

package/fjs/types/bigfloat/proof.f.mjs

@@ -1,6 +1,6 @@
-import { decToBin } from './module.f.mjs'
-import { assertEq } from '../../asserts/module.f.mjs'
-import { bitLength } from '../bigint/module.f.mjs'
+import { binary64, decToBin, tryDecToFormat } from './module.f.mjs'
+import { assert, assertEq, assertStructurallySame } from '../../asserts/module.f.mjs'
+import { abs, bitLength } from '../bigint/module.f.mjs'
 
 /**
  * Checks `decToBin`'s postcondition on a non-zero result: the mantissa holds
@@ -17,6 +17,75 @@ const assertRounded = dec => value => {
     assertEq(m << BigInt(e), value, m.toString(2))
 }
 
+const toBinary64 = tryDecToFormat(binary64)
+
+/**
+ * The exact decimal for the dyadic value `m * 2^k`, as a `BigFloat` this
+ * module's own functions take: `2^k = 5^-k * 10^k` for a negative `k`, so no
+ * decimal digit is ever approximated on the way in. Every boundary below is
+ * stated as a power of two, which is the grid the format is defined on.
+ *
+ * @type {(m: bigint, k: number) => readonly [bigint, number]}
+ */
+const dyadic = (m, k) => k >= 0 ? [m << BigInt(k), 0] : [m * 5n ** BigInt(-k), k]
+
+/**
+ * Asserts that `toBinary64` answers exactly `[m, e]` for the exact decimal of
+ * `dyadic(dm, dk)`, and that the answer respects the format: on the
+ * `2^-1074` grid, and no wider than 53 bits.
+ *
+ * @type {(dyad: readonly [bigint, number]) => (expected: readonly [bigint, number]) => void}
+ */
+const assertBinary64 = ([dm, dk]) => expected => {
+    const result = toBinary64(dyadic(dm, dk))
+    assertStructurallySame(result, expected, [dm, dk])
+    const [m, e] = expected
+    assert(e >= binary64.minExp, expected)
+    assert(bitLength(abs(m)) <= BigInt(binary64.precision), expected)
+}
+
+/**
+ * Asserts that the exact decimal of `dyadic(dm, dk)` overflows the format.
+ *
+ * @type {(dyad: readonly [bigint, number]) => void}
+ */
+const assertOverflow = ([dm, dk]) => assertEq(toBinary64(dyadic(dm, dk)), null, [dm, dk])
+
+/**
+ * Cross-checks `toBinary64` against `Number(decimal)`, which the language
+ * specifies to be correctly rounded — the same claim this function makes, so
+ * disagreement on any input is a defect in one of them.
+ *
+ * A `null` stands for an infinity, which `BigFloat` cannot encode. `-0` is
+ * folded into `0` by the addition: a bigint mantissa has no signed zero, so
+ * the sign of an underflowed value is information this representation does
+ * not carry.
+ *
+ * @type {(dec: readonly [bigint, number]) => void}
+ */
+const assertSameAsNumber = ([dm, de]) => {
+    const expected = Number(`${dm}e${de}`)
+    const result = toBinary64([dm, de])
+    const actual = result === null
+        ? (dm < 0n ? -Infinity : Infinity)
+        : Number(result[0]) * 2 ** result[1]
+    assertEq(actual + 0, expected + 0, [dm, de, result])
+}
+
+/** @type {(from: number) => (to: number) => readonly number[]} */
+const range = from => to => Array.from({ length: to - from + 1 }, (_, i) => from + i)
+
+/**
+ * A deterministic corpus of decimals: ten mantissas of both signs against
+ * every decimal exponent from below the subnormal range to past the top of
+ * the format, so every branch of the conversion is crossed by construction.
+ *
+ * @type {readonly (readonly [bigint, number])[]}
+ */
+const corpus = [1n, 2n, 3n, 5n, 7n, 9n, 10n, 4999999999999999n, 5000000000000001n, 12345678901234567890n]
+    .flatMap(dm => [dm, -dm])
+    .flatMap(dm => range(-340)(320).map(de => /** @type {readonly [bigint, number]} */([dm, de])))
+
 export const proof = {
     decToBin: [
         () => {
@@ -260,5 +329,68 @@ export const proof = {
             assertRounded([0b11_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1101n, 0])(
                 0b11_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1100n)
         },
-    ]
+    ],
+    // `tryDecToFormat(binary64)` rounds once, onto the grid the target format
+    // actually has. Every case below is stated as an exact decimal for a
+    // dyadic value, so the input names a point on that grid or a known
+    // distance from one.
+    tryDecToFormat: [
+        // The case this function exists for. One part in 2^126 below the
+        // midpoint between the subnormals 3*2^-1074 and 4*2^-1074: the
+        // correctly-rounded answer is 3, and `decToBin`'s 53-bit answer is the
+        // midpoint itself, which rounds the other way because 3 is odd.
+        () => {
+            const dec = /** @type {const} */([(7n * 2n ** 125n - 1n) * 5n ** 1200n, -1200])
+            assertStructurallySame(decToBin(dec), [7881299347898368n, -1125], 'the midpoint decToBin lands on')
+            assertStructurallySame(toBinary64(dec), [3n, -1074], 'rounded once, below the midpoint')
+        },
+        // minExp exactly: the smallest value the format holds.
+        () => assertBinary64([1n, -1074])([1n, -1074]),
+        () => assertBinary64([3n, -1074])([3n, -1074]),
+        // Half of it is an exact tie, and 0 is the even side.
+        () => assertBinary64([1n, -1075])([0n, 0]),
+        // A hair above that tie rounds up; a hair below rounds down.
+        () => assertEq(toBinary64([5n ** 1075n + 1n, -1075])?.[0], 1n),
+        () => assertEq(toBinary64([5n ** 1075n - 1n, -1075])?.[0], 0n),
+        // Ties inside the subnormal range go to even in both directions.
+        () => assertBinary64([7n, -1075])([4n, -1074]),
+        () => assertBinary64([11n, -1075])([6n, -1074]),
+        // minExp + 52: the smallest normal, where full precision resumes. Its
+        // mantissa fills all 53 bits and its exponent is still minExp.
+        () => assertBinary64([1n, -1022])([1n << 52n, -1074]),
+        () => assertBinary64([(1n << 52n) - 1n, -1074])([(1n << 52n) - 1n, -1074]),
+        // maxExp exactly: the largest finite value.
+        () => assertBinary64([(1n << 53n) - 1n, 971])([(1n << 53n) - 1n, 971]),
+        () => assertBinary64([-((1n << 53n) - 1n), 971])([-((1n << 53n) - 1n), 971]),
+        // Rounding up out of the top bit has to come back as `precision` bits,
+        // not `precision + 1`. Nothing else here catches a missing
+        // re-normalization: the overflow check is invariant under it
+        // (`54 + (e + 1)` is `53 + (e + 2)`) and the value is the same either
+        // way, so only the width assertion sees it.
+        () => assertBinary64([(1n << 54n) - 1n, -54])([1n << 52n, -52]),
+        () => assertBinary64([-((1n << 54n) - 1n), -54])([-(1n << 52n), -52]),
+        // Past it: 2^1024 outright, and the midpoint below it, which overflows
+        // by rounding up rather than by magnitude.
+        () => assertOverflow([1n, 1024]),
+        () => assertOverflow([-1n, 1024]),
+        () => assertOverflow([(1n << 54n) - 1n, 970]),
+        () => assertBinary64([(((1n << 54n) - 1n) << 970n) - 1n, 0])([(1n << 53n) - 1n, 971]),
+        // Underflow is an answer, not a failure: it is the correctly-rounded
+        // one. A bigint mantissa has no signed zero, so both signs give `0n`.
+        () => assertBinary64([1n, -1200])([0n, 0]),
+        () => assertBinary64([-1n, -1200])([0n, 0]),
+        () => assertBinary64([0n, 0])([0n, 0]),
+        () => assertEq(toBinary64([0n, -400])?.[1], 0),
+        // Negatives mirror positives exactly, subnormals included.
+        () => assertBinary64([-3n, -1074])([-3n, -1074]),
+        () => assertBinary64([-1n, -1022])([-(1n << 52n), -1074]),
+        () => assertBinary64([-1n, 0])([-(1n << 52n), -52]),
+        // A whole-number input takes the other scaling branch (`de >= 0`),
+        // both when it needs widening and when it needs truncating.
+        () => assertBinary64([1n, 0])([1n << 52n, -52]),
+        () => assertBinary64([(1n << 60n) + 1n, 0])([1n << 52n, 8]),
+    ],
+    // Cross-check against `Number(decimal)`, which the language specifies to
+    // be correctly rounded. 13220 decimals, every one of them agreeing.
+    binary64AgreesWithNumber: () => corpus.forEach(assertSameAsNumber),
 }

package/fjs/types/bigfloat/types.d.ts

@@ -4,3 +4,20 @@
  * @module
  */
 export type BigFloat = readonly [bigint, number];
+/**
+ * A binary floating-point format: how many significant bits a value may carry,
+ * and the range its exponent may take.
+ *
+ * `minExp` and `maxExp` are in `BigFloat`'s own units — the exponent of the
+ * mantissa's last bit, not of its first. So `minExp` is the exponent of the
+ * smallest representable value, and `maxExp` the one the largest finite value
+ * carries with a full `precision`-bit mantissa. The other convention (the
+ * exponent of the *leading* bit, as IEEE-754 states it) differs by
+ * `precision - 1` on one end and `precision` on the other; keeping one set of
+ * units is why this type restates them rather than naming IEEE's.
+ */
+export type Format = {
+    readonly precision: number;
+    readonly minExp: number;
+    readonly maxExp: number;
+};

package/fjs/types/function/module.f.d.mts

@@ -1,6 +1,6 @@
 /**
- * Function combinators: composition, identity, argument flipping, and the
- * chainable `Fn` wrapper.
+ * Function combinators: composition, identity, sequential iteration, argument
+ * flipping, and the chainable `Fn` wrapper.
  *
  * @module
  *
@@ -19,6 +19,15 @@ export declare const compose: <I, X>(g: Func<I, X>) => <O>(f: Func<X, O>) => Fun
  * @type {<T>(value: T) => T}
  */
 export declare const identity: <T>(value: T) => T;
+/**
+ * Applies `f` to `value` `n` times sequentially.
+ *
+ * Unlike monoid `repeat`, this performs every application, taking O(n)
+ * applications. A non-positive `n` leaves `value` unchanged.
+ *
+ * @type {(n: bigint) => <T>(value: T) => (f: (value: T) => T) => T}
+ */
+export declare const iterate: (n: bigint) => <T>(value: T) => (f: (value: T) => T) => T;
 /**
  * Flips the arguments of a curried function.
  *

package/fjs/types/function/module.f.mjs

@@ -1,6 +1,6 @@
 /**
- * Function combinators: composition, identity, argument flipping, and the
- * chainable `Fn` wrapper.
+ * Function combinators: composition, identity, sequential iteration, argument
+ * flipping, and the chainable `Fn` wrapper.
  *
  * @module
  *
@@ -21,6 +21,24 @@ export const compose = g => f => x => f(g(x))
  */
 export const identity = value => value
 
+/**
+ * Applies `f` to `value` `n` times sequentially.
+ *
+ * Unlike monoid `repeat`, this performs every application, taking O(n)
+ * applications. A non-positive `n` leaves `value` unchanged.
+ *
+ * @type {(n: bigint) => <T>(value: T) => (f: (value: T) => T) => T}
+ */
+export const iterate = n => value => f => {
+    let v = value
+    let i = 0n
+    while (i < n) {
+        v = f(v)
+        i = i + 1n
+    }
+    return v
+}
+
 /**
  * Flips the arguments of a curried function.
  *

package/fjs/types/function/proof.f.mjs

@@ -1,4 +1,4 @@
-import { fn } from './module.f.mjs'
+import { fn, iterate } from './module.f.mjs'
 import { assertEq } from '../../asserts/module.f.mjs'
 
 export const proof = () => {
@@ -13,4 +13,8 @@ export const proof = () => {
 
     const result = r('hello')
     assertEq(result, 5, r)
+
+    assertEq(iterate(0n)(5)(x => x + 1), 5, iterate)
+    assertEq(iterate(3n)(5)(x => x + 1), 8, iterate)
+    assertEq(iterate(-1n)(5)(x => x + 1), 5, iterate)
 }

package/fjs/types/phantom/types.d.ts

@@ -16,6 +16,27 @@ export type { phantomKey };
  * The field is optional (`?`) so it never needs to be present at runtime.
  * Use `phantomKey` to read the phantom type back out via a conditional type:
  * `S extends Phantom<unknown, infer T> ? T : never`.
+ *
+ * **`T` is an unchecked annotation, not a derivation** — nothing stops it from
+ * being wrong, and once something reads it back (e.g. `Ts<>` in
+ * `fjs/types/rtti/ts/types.ts`, which short-circuits to `T` instead of
+ * structurally recursing), a wrong `T` is trusted silently. Guard every
+ * `Phantom<typeof rawThunk, T>` with two asserts: one against the
+ * un-annotated `rawThunk` (forces the real structural check, catching a
+ * wrong `T`) and one against the phantom-wrapped export (catches the export
+ * and the raw thunk drifting apart), using `Check` from
+ * `fjs/types/rtti/ts/types.ts` — or `Check3`, which pairs the two into one
+ * assert. See `fjs/edag/module.f.mjs` (`_exp`/`exp`) for the pattern:
+ *
+ * ```ts
+ * const rawThunk = () => [...] as const
+ * export const thunk: Phantom<typeof rawThunk, MyType> = rawThunk
+ * type _Check = Assert<Check3<MyType, typeof rawThunk, typeof thunk>>
+ * ```
+ *
+ * One phantom per recursive cycle is enough: `fjs/edag` wraps only `exp`,
+ * the union every node kind recurses through, and the node schemas
+ * themselves stay un-phantomed, each pinned with a plain `Check`.
  */
 export type Phantom<S, T> = S & {
     readonly [phantomKey]?: T;

package/fjs/types/result/module.f.d.mts

@@ -27,19 +27,19 @@ import type { Ok, Error, Result } from './types.ts';
 /**
  * Creates a successful result.
  *
- * @template T
+ * @template const T
  * @param {T} value - The value to wrap.
  * @returns {Ok<T>} A successful result containing the value.
  */
-export declare const ok: <T>(value: T) => Ok<T>;
+export declare const ok: <const T>(value: T) => Ok<T>;
 /**
  * Creates a failed result.
  *
- * @template E
+ * @template const E
  * @param {E} e - The error to wrap.
  * @returns {Error<E>} A failed result containing the error.
  */
-export declare const error: <E>(e: E) => Error<E>;
+export declare const error: <const E>(e: E) => Error<E>;
 /**
  * Unwraps a result, returning the value if successful or throwing the error if failed.
  *

package/fjs/types/result/module.f.mjs

@@ -27,7 +27,7 @@
 /**
  * Creates a successful result.
  *
- * @template T
+ * @template const T
  * @param {T} value - The value to wrap.
  * @returns {Ok<T>} A successful result containing the value.
  */
@@ -36,7 +36,7 @@ export const ok = value  => ['ok', value]
 /**
  * Creates a failed result.
  *
- * @template E
+ * @template const E
  * @param {E} e - The error to wrap.
  * @returns {Error<E>} A failed result containing the error.
  */

package/fjs/types/result/proof.f.d.mts

@@ -1,17 +1,21 @@
 /**
- * @import { Result } from './types.ts'
+ * @import { Error, Ok, Result } from './types.ts'
+ * @import { Assert } from '../../asserts/types.ts'
+ * @import { Equal } from '../ts/types.ts'
  */
 declare const example: () => void;
+declare const constInference: () => void;
 declare const invertTest: () => void;
 declare const mapOkTest: () => void;
 declare const okThenTest: () => void;
 export declare const proof: {
     example: typeof example;
+    constInference: typeof constInference;
     invertTest: typeof invertTest;
     mapOkTest: typeof mapOkTest;
     okThenTest: typeof okThenTest;
     throw: {
-        unwrapError: () => string;
+        unwrapError: () => "oops";
     };
 };
 export {};

package/fjs/types/result/proof.f.mjs

@@ -1,5 +1,7 @@
 /**
- * @import { Result } from './types.ts'
+ * @import { Error, Ok, Result } from './types.ts'
+ * @import { Assert } from '../../asserts/types.ts'
+ * @import { Equal } from '../ts/types.ts'
  */
 
 import { error, ok, unwrap, invert, mapOk, okThen } from './module.f.mjs'
@@ -18,6 +20,19 @@ const example = () => {
     assertEq(v, 'Something went wrong', 'error')
 }
 
+// `ok` and `error` take `const` type parameters, so a literal argument keeps
+// its literal type without an `@type {const}` cast at the call site — a tagged
+// error stays a tuple of literals instead of widening to `string[]`. These two
+// assertions are what fail if a modifier is dropped.
+const constInference = () => {
+    const o = ok([1, 2])
+    /** @typedef {Assert<Equal<typeof o, Ok<readonly [1, 2]>>>} _ConstOk */
+    const e = error(['notImplemented', 'read'])
+    /** @typedef {Assert<Equal<typeof e, Error<readonly ['notImplemented', 'read']>>>} _ConstError */
+    assertEq(o[1][1], 2)
+    assertEq(e[1][0], 'notImplemented')
+}
+
 const invertTest = () => {
     const [k0, v0] = invert(ok(42))
     assert(!(k0 !== 'error' || v0 !== 42), [k0, v0])
@@ -52,6 +67,7 @@ const okThenTest = () => {
 
 export const proof = {
     example,
+    constInference,
     invertTest,
     mapOkTest,
     okThenTest,