functionalscript 0.43.1 → 0.45.0

package/fjs/text/utf8/proof.f.mjs

@@ -0,0 +1,217 @@
+import { toCodePointList, fromCodePointList, fromVec, utf8ByteToCodePointOp } from './module.f.mjs'
+import { stringify as jsonStringify } from '../../media/json/module.f.mjs'
+import { sort } from '../../types/object/module.f.mjs'
+import { toArray } from '../../types/list/module.f.mjs'
+import { msb, u8ListToVec, vec } from '../../types/bit_vec/module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+
+const stringify = jsonStringify(sort)
+
+export const proof = {
+    toCodePoint: [
+        () => {
+            const result = stringify(toArray(toCodePointList([-1, 256])))
+            assertEq(result, '[2147483648,2147483648]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([128, 193, 245, 255])))
+            assertEq(result, '[-2147483520,-2147483455,-2147483403,-2147483393]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([0, 1, 127])))
+            assertEq(result, '[0,1,127]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([194, 128, 194, 169, 223, 191])))
+            assertEq(result, '[128,169,2047]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([194, 194, 127, 194, 192, 194])))
+            assertEq(result, '[-2147483454,-2147483454,127,-2147483454,-2147483456,-2147483454]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([224, 160, 128, 224, 160, 129, 239, 191, 191])))
+            assertEq(result, '[2048,2049,65535]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([224, 224, 160, 127, 239, 191])))
+            assertEq(result, '[-2147483424,-2147482592,127,-2147481601]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 144, 128, 128, 240, 144, 128, 129, 244, 143, 191, 191])))
+            assertEq(result, '[65536,65537,1114111]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 240, 160, 127, 244, 191])))
+            assertEq(result, '[-2147483408,-2147483104,127,-2147482817]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 160, 160, 244, 160, 160])))
+            assertEq(result, '[-2147448800,-2147432416]')
+        },
+        // Overlong 3-byte encodings (E0 80..9F ..) are rejected, not decoded.
+        () => {
+            const result = stringify(toArray(toCodePointList([224, 128, 128])))
+            assertEq(result, '[-2147483424,-2147483520,-2147483520]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([224, 159, 191])))
+            assertEq(result, '[-2147483424,-2147483489,-2147483457]')
+        },
+        // Overlong 4-byte encodings (F0 80..8F .. ..) are rejected, not decoded.
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 128, 128, 128])))
+            assertEq(result, '[-2147483408,-2147483520,-2147483520,-2147483520]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 143, 191, 191])))
+            assertEq(result, '[-2147483408,-2147483505,-2147483457,-2147483457]')
+        },
+        // Valid boundary cases still decode: E0 A0 80 -> U+0800, F0 90 80 80 -> U+10000.
+        () => {
+            const result = stringify(toArray(toCodePointList([224, 160, 128])))
+            assertEq(result, '[2048]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 144, 128, 128])))
+            assertEq(result, '[65536]')
+        },
+        // A byte stream never accumulates a 2-byte state whose lead is >= F8
+        // (isLeadByte caps leads at F4), so this defensive fallthrough is
+        // only reachable by calling the scan op directly with such a state.
+        () => {
+            const result = stringify(utf8ByteToCodePointOp(0x80, [0xf8, 0x80]))
+            assertEq(result, '[[-2147483136,-2147483520],null]')
+        }
+    ],
+    fromCodePointList: [
+        () => {
+            const result = stringify(toArray(fromCodePointList([0, 1, 0x7F])))
+            assertEq(result, '[0,1,127]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x80])))
+            assertEq(result, '[194,128]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0xa9])))
+            assertEq(result, '[194,169]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x7ff])))
+            assertEq(result, '[223,191]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x800])))
+            assertEq(result, '[224,160,128]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x801])))
+            assertEq(result, '[224,160,129]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0xffff])))
+            assertEq(result, '[239,191,191]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x10000])))
+            assertEq(result, '[240,144,128,128]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x10001])))
+            assertEq(result, '[240,144,128,129]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x10FFFF])))
+            assertEq(result, '[244,143,191,191]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x110000, 2147483648])))
+            assertEq(result, '[2147483648,2147483648]')
+        }
+    ],
+    toFrom: [
+        () => {
+            const codePointList = toCodePointList([128, 193, 245, 255])
+            const result = stringify(toArray(fromCodePointList(codePointList)))
+            assertEq(result, '[128,193,245,255]')
+        },
+        () => {
+            const codePointList = toCodePointList([194, 194, 127, 194, 192, 194])
+            const result = stringify(toArray(fromCodePointList(codePointList)))
+            assertEq(result, '[194,194,127,194,192,194]')
+        },
+        () => {
+            const codePointList = toCodePointList([224, 224, 160, 127, 239, 191])
+            const result = stringify(toArray(fromCodePointList(codePointList)))
+            assertEq(result, '[224,224,160,127,239,191]')
+        },
+        () => {
+            const codePointList = toCodePointList([240, 240, 160, 127, 244, 191])
+            const result = stringify(toArray(fromCodePointList(codePointList)))
+            assertEq(result, '[240,240,160,127,244,191]')
+        },
+        () => {
+            const codePointList = toCodePointList([240, 160, 160, 244, 160, 160])
+            const result = stringify(toArray(fromCodePointList(codePointList)))
+            assertEq(result, '[240,160,160,244,160,160]')
+        }
+    ],
+    fromVec: [
+        // Valid ASCII → decoded string
+        () => {
+            const v = u8ListToVec(msb)([0x68, 0x65, 0x6c, 0x6c, 0x6f]) // "hello"
+            assertEq(fromVec(v), 'hello', 'expected "hello"')
+        },
+        // Valid multi-byte UTF-8 → decoded string (U+00A9 COPYRIGHT SIGN, 2-byte)
+        () => {
+            const v = u8ListToVec(msb)([0xc2, 0xa9]) // "©"
+            assertEq(fromVec(v), '©', 'expected copyright sign')
+        },
+        // Valid 3-byte UTF-8 (U+4E2D CJK)
+        () => {
+            const v = u8ListToVec(msb)([0xe4, 0xb8, 0xad]) // "中"
+            assertEq(fromVec(v), '中', 'expected CJK character')
+        },
+        // Valid 4-byte UTF-8 (U+1F600 GRINNING FACE)
+        () => {
+            const v = u8ListToVec(msb)([0xf0, 0x9f, 0x98, 0x80])
+            if (fromVec(v) !== '\u{1f600}') { throw 'expected emoji' }
+        },
+        // Invalid byte sequence → null
+        () => {
+            const v = u8ListToVec(msb)([0xff, 0xfe]) // not valid UTF-8
+            assertEq(fromVec(v), null, 'expected null for invalid UTF-8')
+        },
+        // Lone continuation byte → null
+        () => {
+            const v = u8ListToVec(msb)([0x80])
+            assertEq(fromVec(v), null, 'expected null for lone continuation byte')
+        },
+        // Surrogate half (U+D800, encoded as CESU-8 0xED 0xA0 0x80) → null
+        () => {
+            const v = u8ListToVec(msb)([0xed, 0xa0, 0x80])
+            assertEq(fromVec(v), null, 'expected null for surrogate')
+        },
+        // Empty Vec → empty string
+        () => {
+            const v = u8ListToVec(msb)([])
+            assertEq(fromVec(v), '', 'expected empty string')
+        },
+        // Overlong 3-byte encoding (E0 80 80, would decode to U+0000) → null
+        () => {
+            const v = u8ListToVec(msb)([0xe0, 0x80, 0x80])
+            assertEq(fromVec(v), null, 'expected null for overlong 3-byte encoding')
+        },
+        // Overlong 4-byte encoding (F0 80 80 80, would decode to U+0000) → null
+        () => {
+            const v = u8ListToVec(msb)([0xf0, 0x80, 0x80, 0x80])
+            assertEq(fromVec(v), null, 'expected null for overlong 4-byte encoding')
+        },
+        // Vec length not a multiple of 8 bits → null
+        () => {
+            const v = vec(4n)(0n)
+            assertEq(fromVec(v), null)
+        },
+    ]
+}

package/fjs/text/utf8/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Types for UTF-8 byte-level encoding and decoding.
+ *
+ * @module
+ */
+import type { Tuple } from '../../types/array/types.ts';
+/** An unsigned 8-bit integer, represents a single byte. */
+export type U8 = number;
+/** A singed 32-bit integer. */
+export type I32 = number;
+/**
+ * Represents an unsigned 8-bit type - U8 or the end-of-file indicator.
+ * The U8 represents the byte itself, and null indicates that reading does not
+ * return anything else.
+ */
+export type ByteOrEof = U8 | null;
+/**
+ * Represents the state of a UTF-8 decoding operation that contains at least one
+ * byte.
+ */
+export type Utf8NonEmptyState = Tuple<1, number> | Tuple<2, number> | Tuple<3, number>;
+/**
+ * Represents the state of a UTF-8 decoding operation, which can be either
+ * `null` (no state) or a non-empty state containing one or more bytes.
+ */
+export type Utf8State = null | Utf8NonEmptyState;

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

@@ -0,0 +1,69 @@
+/**
+ * JavaScript immutable arrays.
+ *
+ * @module
+ *
+ * @import { Tuple } from './types.ts'
+ */
+import type { Tuple } from './types.ts';
+/**
+ * @type {(value: unknown) => value is readonly unknown[]}
+ */
+export declare const isArray: (value: unknown) => value is readonly unknown[];
+/**
+ * Currently, TypeScript can't narrow the type of `readonly T[]` to `Array2<T>`
+ * only by checking `a.length === 2`, so we need a user-defined type guard.
+ */
+export declare const isTuple: <N extends number>(
+/**
+ * @template {number} N
+ * @param {N} n
+ */
+n: N) => <T>(
+/**
+ * @template T
+ * @param {readonly T[]} a An array of unknown length.
+ * @return {a is Tuple<N, T>} True if `a` has length 2, and `a` is narrowed to `Array2<T>` in that case.
+ */
+a: readonly T[]) => a is Tuple<N, T>;
+/**
+ * @type {(i: number) => <T>(a: readonly T[]) => T | null}
+ */
+export declare const at: (i: number) => <T>(a: readonly T[]) => T | null;
+export declare const first: <T>(a: readonly T[]) => T | null;
+/**
+ * @type {<T>(a: readonly T[]) => T | null}
+ */
+export declare const last: <T>(a: readonly T[]) => T | null;
+/**
+ * @type {<T>(a: readonly T[]) => readonly T[] | null}
+ */
+export declare const tail: <T>(a: readonly T[]) => readonly T[] | null;
+/**
+ * @type {<T>(a: readonly T[]) => readonly [T, readonly T[]] | null}
+ */
+export declare const splitFirst: <T>(a: readonly T[]) => readonly [T, readonly T[]] | null;
+/** @type {<T>(a: readonly T[]) => readonly T[] | null} */
+export declare const head: <T>(a: readonly T[]) => readonly T[] | null;
+/** @type {<T>(a: readonly T[]) => readonly [readonly T[], T] | null} */
+export declare const splitLast: <T>(a: readonly T[]) => readonly [readonly T[], T] | null;
+/**
+ * An empty immutable array.
+ *
+ * Two JavaScript empty arrays are different and has to have two different values.
+ * Usually, it requires memory allocation. If we use the same an empty array everywhere,
+ * we may minimize memory a number of memory allocations.
+ */
+export declare const empty: readonly [];
+export declare const includes: <I, T extends readonly I[]>(
+/**
+ * @template I
+ * @template {readonly I[]} T
+ * @param {T} a
+ */
+a: T) => (
+/**
+ * @param {I} v
+ * @return {v is T[number]}
+ */
+v: I) => v is T[number];

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

@@ -0,0 +1,101 @@
+/**
+ * JavaScript immutable arrays.
+ *
+ * @module
+ *
+ * @import { Tuple } from './types.ts'
+ */
+
+import { fromUndefined, map } from '../nullable/module.f.mjs'
+
+/**
+ * @type {(value: unknown) => value is readonly unknown[]}
+ */
+export const isArray = value => value instanceof Array
+
+/**
+ * Currently, TypeScript can't narrow the type of `readonly T[]` to `Array2<T>`
+ * only by checking `a.length === 2`, so we need a user-defined type guard.
+ */
+export const isTuple =
+    /**
+     * @template {number} N
+     * @param {N} n
+     */
+    n =>
+    /**
+     * @template T
+     * @param {readonly T[]} a An array of unknown length.
+     * @return {a is Tuple<N, T>} True if `a` has length 2, and `a` is narrowed to `Array2<T>` in that case.
+     */
+    a =>
+        a.length === n
+
+/**
+ * @type {<T>(a: readonly T[]) => readonly T[]}
+ */
+const uncheckTail = a => a.slice(1)
+
+/**
+ * @type {<T>(a: readonly T[]) => readonly T[]}
+ */
+const uncheckHead = a => a.slice(0, -1)
+
+/**
+ * @type {(i: number) => <T>(a: readonly T[]) => T | null}
+ */
+export const at = i => a => fromUndefined(a[i])
+
+export const first = at(0)
+
+/**
+ * @type {<T>(a: readonly T[]) => T | null}
+ */
+export const last = a => at(a.length - 1)(a)
+
+/**
+ * @type {<T>(a: readonly T[]) => readonly T[] | null}
+ */
+export const tail = a => a.length === 0 ? null : uncheckTail(a)
+
+/**
+ * @type {<T>(a: readonly T[]) => readonly [T, readonly T[]] | null}
+ */
+export const splitFirst = a => {
+    /** @typedef {(typeof a)[0]} T */
+    const split = (/** @type {T} */first) =>
+        /** @type {const} */([first, uncheckTail(a)])
+    return map(split)(first(a))
+}
+
+/** @type {<T>(a: readonly T[]) => readonly T[] | null} */
+export const head = a => a.length === 0 ? null : uncheckHead(a)
+
+/** @type {<T>(a: readonly T[]) => readonly [readonly T[], T] | null} */
+export const splitLast = a => {
+    const lastA = last(a)
+    return lastA === null ? null : [uncheckHead(a), lastA]
+}
+
+/**
+ * An empty immutable array.
+ *
+ * Two JavaScript empty arrays are different and has to have two different values.
+ * Usually, it requires memory allocation. If we use the same an empty array everywhere,
+ * we may minimize memory a number of memory allocations.
+ */
+export const empty = /** @type {const} */([])
+
+export const includes =
+    /**
+     * @template I
+     * @template {readonly I[]} T
+     * @param {T} a
+     */
+    a =>
+    /**
+     * @param {I} v
+     * @return {v is T[number]}
+     */
+    v =>
+    a.includes(v)

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

@@ -0,0 +1,98 @@
+import { at, first, last, head, tail, splitFirst, splitLast, empty } from './module.f.mjs'
+import { stringify as jsonStringify } from '../../media/json/module.f.mjs'
+import { sort } from '../object/module.f.mjs'
+import { assertEq, assertNotNullish } from '../../asserts/module.f.mjs'
+
+const stringify = jsonStringify(sort)
+
+export const proof = {
+    stringify: () => {
+        const result = stringify([1, 20, 300])
+        assertEq(result, '[1,20,300]')
+    },
+    at: [
+        () => {
+            const result = at(2)([1, 20, 300])
+            assertEq(result, 300)
+        },
+
+        () => {
+            const result = at(3)([1, 20, 300])
+            assertEq(result, null)
+        }
+    ],
+    first: [
+        () => {
+            const result = first([1, 20, 300])
+            assertEq(result, 1)
+        },
+        () => {
+            const result = first([])
+            assertEq(result, null)
+        }
+    ],
+    last: [
+        () => {
+            const result = last([1, 20, 300])
+            assertEq(result, 300)
+        },
+        () => {
+            const result = last([])
+            assertEq(result, null)
+        }
+    ],
+    head: [
+        () => {
+            const result = assertNotNullish(head([1, 20, 300]))
+            const str = stringify(result)
+            assertEq(str, '[1,20]')
+        },
+        () => {
+            const result = head([])
+            assertEq(result, null)
+        }
+    ],
+    tail: [
+        () => {
+            const result = tail([1, 20, 300])
+            const str = stringify(result)
+            assertEq(str, '[20,300]')
+        },
+        () => {
+            const result = tail([])
+            assertEq(result, null)
+        }
+    ],
+
+    splitFirst: [
+        () => {
+            const result = splitFirst([1, 20, 300])
+            const str = stringify(result)
+            assertEq(str, '[1,[20,300]]')
+        },
+        () => {
+            const result = splitFirst([])
+            assertEq(result, null)
+        },
+    ],
+    splitLast: [
+        () => {
+            const result = splitLast([1, 20, 300])
+            const str = stringify(result)
+            assertEq(str, '[[1,20],300]')
+        },
+        () => {
+            const result = splitLast([])
+            assertEq(result, null)
+        }
+    ],
+    empty: () => {
+        const x = empty
+        /** @type {readonly number[]} */
+        const a = x
+        /** @type {readonly string[]} */
+        const b = x
+        const c = [...a, ...b, ...x]
+        assertEq(c.length, 0, c)
+    }
+}

package/fjs/types/array/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Types for JavaScript immutable arrays.
+ *
+ * @module
+ */
+type _Tuple<N extends number, T, R extends readonly T[]> = N extends R['length'] ? R : _Tuple<N, T, readonly [...R, T]>;
+type _Index<N extends number, R extends readonly unknown[]> = R['length'] extends N ? never : R['length'] | _Index<N, readonly [...R, unknown]>;
+export type Index<N extends number> = number extends N ? number : N extends number ? _Index<N, readonly []> : never;
+export type Tuple<N extends number, T> = _Tuple<N, T, readonly []>;
+export type KeyOf<T extends readonly unknown[]> = Index<T['length']>;
+export type Array1_5<T> = Tuple<1, T> | Tuple<2, T> | Tuple<3, T> | Tuple<4, T> | Tuple<5, T>;
+export type Includes<I, T extends readonly I[]> = (v: I) => v is T[number];
+export {};

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

@@ -0,0 +1,34 @@
+/**
+ * Big-float helpers built from bigint mantissa and exponent parts.
+ *
+ * @module
+ *
+ * @import { BigFloat } from './types.ts'
+ */
+import type { BigFloat } from './types.ts';
+export type _BigFloatWithRemainder = readonly [BigFloat, bigint];
+/** @type {(_: BigFloat) => (mul: bigint) => BigFloat} */
+export declare const multiply: (_: BigFloat) => (mul: bigint) => BigFloat;
+/**
+ * Converts a decimal big-float `m * 10^e` into the nearest binary big-float,
+ * rounding ties to even.
+ *
+ * A zero input returns `[0n, 0]`; every other input returns a mantissa of
+ * exactly 53 significant bits, `2^52 <= abs(m) < 2^53`. The upper bound holds
+ * 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.
+ *
+ * @type {(dec: BigFloat) => BigFloat}
+ */
+export declare const decToBin: (dec: BigFloat) => BigFloat;
+export declare const proof: {
+    normalizeMantissaZero: () => void;
+};

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

@@ -0,0 +1,125 @@
+/**
+ * Big-float helpers built from bigint mantissa and exponent parts.
+ *
+ * @module
+ *
+ * @import { BigFloat } from './types.ts'
+ */
+
+import { abs, sign } from '../bigint/module.f.mjs'
+
+/** @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
+
+/**
+ * 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}
+ */
+const normalizeMantissa = (shift, de, done) => ([m, e]) => bound => {
+    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
+    }
+}
+
+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)
+
+const pow5 = pow(5n)
+
+/** @type {(_: BigFloat) => (mul: bigint) => BigFloat} */
+export const multiply = ([m, e]) => mul => [m * mul, e]
+
+/** @type {(_: BigFloat) => (div: bigint) => _BigFloatWithRemainder} */
+const divide = ([m, e]) => div => [[m / div, e], m % div]
+
+/**
+ * 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.
+ *
+ * @type {(m: bigint, e: number) => (f: (magnitude: BigFloat) => BigFloat) => BigFloat}
+ */
+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.
+ *
+ * @type {(magnitude: BigFloat) => BigFloat}
+ */
+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])
+    })
+
+/**
+ * Converts a decimal big-float `m * 10^e` into the nearest binary big-float,
+ * rounding ties to even.
+ *
+ * A zero input returns `[0n, 0]`; every other input returns a mantissa of
+ * exactly 53 significant bits, `2^52 <= abs(m) < 2^53`. The upper bound holds
+ * 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.
+ *
+ * @type {(dec: BigFloat) => BigFloat}
+ */
+export const decToBin = dec => {
+    if (dec[0] === 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 p = pow5(-dec[1])
+    const [m, e] = increaseMantissa(dec)(p * twoPow53)
+    return withSign(m, e)(magnitude => round53(divide(magnitude)(p)))
+}
+
+export const proof = {
+    // normalizeMantissa guards against zero mantissa to prevent an infinite loop;
+    // this path is unreachable through decToBin (which returns early for 0n),
+    // so we exercise it here where the private helper is in scope.
+    normalizeMantissaZero: () => { increaseMantissa([0n, 5])(1n) }
+}