functionalscript 0.43.1 → 0.45.0

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

@@ -0,0 +1,521 @@
+/**
+ * @import { Sign } from '../function/compare/types.ts'
+ * @import { Vec, BitOrder } from './types.ts'
+ * @import { List } from '../list/types.ts'
+ */
+
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { mask } from '../bigint/module.f.mjs'
+import { asBase, asNominal } from '../nominal/module.f.mjs'
+import { length, empty, uint, vec, lsb, msb, repeat, vec8, maxLength, u8ListToVec, tryU8ListToVec, u8List, chunkList, fromSentinel } from './module.f.mjs'
+import { repeat as listRepeat, toArray } from '../list/module.f.mjs'
+
+/** @type {(a: bigint) => Vec} */
+const unsafeVec = a => asNominal(a)
+
+// 0x8 = 0b1000 = 0 + 8
+// 0x9 = 0b1001 = 1 + 8
+// 0xA = 0b1010 = 2 + 8
+// 0xB = 0b1011 = 3 + 8
+// 0xC = 0b1100 = 4 + 8
+// 0xD = 0b1101 = 5 + 8
+// 0xE = 0b1110 = 6 + 8
+// 0xF = 0b1111 = 7 + 8
+
+/**
+ * @template T
+ * @param {readonly [bigint, T]} a
+ * @param {readonly [bigint, T]} b
+ */
+const assertEq2 = ([a0, a1], [b0, b1]) => {
+    assertEq(a0, b0)
+    assertEq(a1, b1)
+}
+
+/** @type {(e: BitOrder) => (r0: bigint) => (r1: bigint) => () => void} */
+const frontTest = e => r0 => r1 => () => {
+    const vector = vec(8n)(0xF5n) // 0xF5n
+    assertEq(vector, unsafeVec(0xF5n))
+    const result = e.front(4n)(vector)
+    assertEq(result, r0)
+    const result2 = e.front(16n)(vector)
+    assertEq(result2, r1)
+}
+
+/** @type {(e: BitOrder) => (r0: readonly [bigint, bigint]) => (r1: readonly [bigint, bigint]) => () => void} */
+const popFront = e => ([r00, r01]) => ([r10, r11]) => () => {
+    const vector = vec(8n)(0xF5n) // 0xF5n
+    const [result, rest] = e.popFront(4n)(vector)
+    assertEq(result, r00)
+    assertEq(rest, unsafeVec(r01))
+    const [result2, rest2] = e.popFront(16n)(vector)
+    assertEq(result2, r10)
+    assertEq(rest2, unsafeVec(r11))
+}
+
+/** @type {(e: BitOrder) => (r0: Vec) => (r1: Vec) => () => void} */
+const removeFront = e => r0 => r1 => () => {
+    const v = vec(16n)(0x3456n) // -0xB456n
+    assertEq(v, unsafeVec(-0xB456n))
+    const r = e.removeFront(4n)(v)
+    assertEq(r, r0)
+    const r2 = e.removeFront(24n)(v)
+    assertEq(r2, r1)
+}
+
+/** @type {(e: BitOrder) => (r: Vec) => () => void} */
+const concat = e => r => () => {
+    const u8 = vec(8n)
+    const a = u8(0x45n) // -0xC5n
+    assertEq(a, unsafeVec(-0xC5n))
+    const b = u8(0x89n) // 0x89n
+    assertEq(b, unsafeVec(0x89n))
+    const ab = e.concat(a)(b) // 0x8945n
+    assertEq(ab, r)
+}
+
+export const proof = {
+    fromSentinel: () => {
+        // Two data bytes; the leading 0x1 nibble is the sentinel, stripped out.
+        const v = fromSentinel(0x1_89_50n)
+        assertEq(length(v), 16n)
+        assertEq(uint(v), 0x8950n)
+        // Leading zero bytes survive because the sentinel pins the length.
+        const z = fromSentinel(0x1_00_05n)
+        assertEq(length(z), 16n)
+        assertEq(uint(z), 0x0005n)
+        // A bare sentinel yields the empty vector.
+        assertEq(fromSentinel(0x1n), empty)
+    },
+    examples: {
+        vec: () => {
+            const vec4 = vec(4n)
+            const v0 = vec4(5n) // 0b0101 => -0b1101
+            assertEq(v0, unsafeVec(-0xDn))
+            const v1 = vec4(0x5FEn) // 0xEn
+            assertEq(v1, unsafeVec(0xEn))
+        },
+        uint: () => {
+            const vector = vec(8n)(0x5n) // -0x85n
+            assertEq(vector, unsafeVec(-0x85n))
+            const result = uint(vector) // result is 0x5n
+            assertEq(result, 0x5n)
+        },
+        front: () => {
+            const vector = vec(8n)(0xF5n) // 0xF5n
+
+            assertEq(lsb.front(4n)(vector), 5n)
+            assertEq(lsb.front(16n)(vector), 0xF5n)
+
+            assertEq(msb.front(4n)(vector), 0xFn)
+            assertEq(msb.front(16n)(vector), 0xF500n)
+        },
+        removeFront: () => {
+            const v = vec(16n)(0x3456n) // -0xB456n
+
+            assertEq(lsb.removeFront(4n)(v), asNominal(-0xB45n))
+            assertEq(lsb.removeFront(24n)(v), empty)
+
+            assertEq(msb.removeFront(4n)(v), asNominal(-0xC56n))
+            assertEq(msb.removeFront(24n)(v), empty)
+        },
+        popFront: () => {
+            const vector = vec(8n)(0xF5n) // 0xF5n
+
+            assertEq2(lsb.popFront(4n)(vector), [5n, asNominal(0xFn)])
+            assertEq2(lsb.popFront(16n)(vector), [0xF5n, empty])
+
+            assertEq2(msb.popFront(4n)(vector), [0xFn, asNominal(-0xDn)])
+            assertEq2(msb.popFront(16n)(vector), [0xF500n, empty])
+        },
+        concat: () => {
+            const u8 = vec(8n)
+            const a = u8(0x45n) // -0xC5n
+            const b = u8(0x89n) // 0x89n
+
+            assertEq(lsb.concat(a)(b), asNominal(0x8945n))
+            assertEq(msb.concat(a)(b), asNominal(-0xC589n))
+        }
+    },
+    front: {
+        lsbf: frontTest(lsb)(5n)(0xF5n),
+        msbf: frontTest(msb)(0xFn)(0xF500n),
+    },
+    popFront: {
+        lsbm: popFront(lsb)([5n, 0xFn])([0xF5n, 0n]),
+        msbm: popFront(msb)([0xFn, -0xDn])([0xF500n, 0n]),
+    },
+    removeFront: {
+        lsbm: removeFront(lsb)(asNominal(-0xB45n))(empty),
+        msbm: removeFront(msb)(asNominal(-0xC56n))(empty),
+    },
+    concat: {
+        lsbm: concat(lsb)(asNominal(0x8945n)),
+        msbm: concat(msb)(asNominal(-0xC589n)),
+    },
+    uintLsb: () => {
+        /** @type {Vec} */
+        const vector = asNominal(0b110101n)
+        const extract3Bits = lsb.front(3n)
+        const result = extract3Bits(vector) // result is 0b101n (5n)
+        assertEq(result, 0b101n)
+    },
+    uintSmall: () => {
+        /** @type {Vec} */
+        const vector = asNominal(0b1n)
+        const extract3Bits = lsb.front(3n)(vector)
+        assertEq(extract3Bits, 0b1n)
+    },
+    vecExample: () => {
+        const createVector = vec(4n)
+        const vector = createVector(5n) // vector is -0b1101n
+        assertEq(vector, unsafeVec(-0b1101n))
+    },
+    length: () => {
+        const len = length(empty)
+        assertEq(len, 0n)
+    },
+    bitset: () => {
+        const v = vec(8n)(0x5FEn)
+        assertEq(v, unsafeVec(0xFEn))
+        assertEq(length(v), 8n, 'len')
+        const u = lsb.front(8n)(v)
+        assertEq(u, 0xFEn, v)
+    },
+    appendBack: () => {
+        const vec8 = vec(8n)
+        const a = vec8(0x345n)
+        const b = vec8(0x789n)
+        const ab = lsb.concat(a)(b)
+        assertEq(ab, unsafeVec(0x8945n))
+        const s = length(ab)
+        if (s !== 16n) { throw `appendBack: ${s}` }
+    },
+    removeBack: () => {
+        const v = vec(17n)(0x12345n)
+        assertEq(v, unsafeVec(0x12345n), (/** @type {bigint} */ (asBase(v))).toString(16))
+        const r = lsb.removeFront(9n)(v)
+        assertEq(r, unsafeVec(0x91n), (/** @type {bigint} */ (asBase(r))).toString(16))
+    },
+    uint: [
+        // 0
+        () => {
+            const x = uint(asNominal(0n))
+            assertEq(x, 0n)
+        },
+        // 1
+        () => {
+            /** @type {Vec} */
+            const v = asNominal(1n)
+            const x = uint(v)
+            assertEq(x, 1n)
+            const len = length(v)
+            assertEq(len, 1n)
+        },
+        // 2
+        () => {
+            /** @type {Vec} */
+            const v = asNominal(0b10n)
+            const x = uint(v)
+            assertEq(x, 0b10n)
+            const len = length(v)
+            assertEq(len, 2n)
+        },
+        // 3
+        () => {
+            /** @type {Vec} */
+            const v = asNominal(0b11n)
+            const x = uint(v)
+            assertEq(x, 0b11n)
+            const len = length(v)
+            assertEq(len, 2n)
+        },
+        // 4
+        () => {
+            /** @type {Vec} */
+            const v = asNominal(-1n)
+            const x = uint(v)
+            assertEq(x, 0n)
+            const len = length(v)
+            assertEq(len, 1n)
+        },
+        () => {
+            /** @type {Vec} */
+            const v = asNominal(-0b10n)
+            const x = uint(v)
+            assertEq(x, 0n)
+            const len = length(v)
+            assertEq(len, 2n)
+        },
+        () => {
+            /** @type {Vec} */
+            const v = asNominal(-0b11n)
+            const x = uint(v)
+            assertEq(x, 1n)
+            const len = length(v)
+            assertEq(len, 2n)
+        }
+    ],
+    vec: [
+        // 0
+        () => {
+            const v = asBase(vec(0n)(0n))
+            assertEq(v, 0n)
+        },
+        () => {
+            const v = asBase(vec(0n)(1n))
+            assertEq(v, 0n)
+        },
+        () => {
+            const v = asBase(vec(0n)(-1n))
+            assertEq(v, 0n)
+        },
+        // 1
+        () => {
+            const v = asBase(vec(1n)(0n))
+            assertEq(v, -1n)
+        },
+        () => {
+            const v = asBase(vec(1n)(1n))
+            assertEq(v, 1n)
+        },
+        () => {
+            const v = asBase(vec(1n)(-1n))
+            assertEq(v, 1n)
+        },
+        () => {
+            const v = asBase(vec(1n)(0b10n))
+            assertEq(v, -1n)
+        },
+        () => {
+            const v = asBase(vec(1n)(0b11n))
+            assertEq(v, 1n)
+        }
+    ],
+    both: () => {
+        const c = (/** @type {bigint} */ len) => (/** @type {bigint} */ ui) => (/** @type {bigint} */ raw) => {
+            const v = vec(len)(ui)
+            const x = asBase(v)
+            if (x !== raw) { throw `x: ${x}, raw: ${raw}` }
+            const len2 = length(v)
+            assertEq(len2, len)
+            const u = uint(v)
+            const mui = mask(len) & ui
+            assertEq(u, mui, [u, mui])
+        }
+        // 0n
+        for (const i of [0n, 1n, -1n, 2n, -2n, 3n, -3n]) {
+            c(0n)(i)(0n)
+        }
+        return [
+            // 1n
+            () => c(1n)(0n)(-1n),
+            () => c(1n)(1n)(1n),
+            () => c(1n)(-11n)(1n), //< overflow
+            // 2n
+            () => c(2n)(0n)(-0b10n),
+            () => c(2n)(1n)(-0b11n),
+            () => c(2n)(0b10n)(0b10n),
+            () => c(2n)(0b11n)(0b11n),
+            // -1 is 0b.....1
+            // -2 is 0b....10
+            // -3 is 0b...101
+            // -4 is 0b...100
+            // -5 is 0b..1011
+            // -6 is 0b..1010
+            // -7 is 0b..1011, cut 0b11, vec: -0b11
+            // -8 is 0b..1100 = ~(8-1) = ~7
+            () => c(2n)(-0b111n)(-0b11n), //< overflow.
+        ]
+    },
+    concat2: () => {
+        const c = (/** @type {Vec} */ a) => (/** @type {Vec} */ b) => (/** @type {Vec} */ abx) => {
+            const ab = msb.concat(a)(b)
+            const abLen = length(ab)
+            const abxLen = length(abx)
+            assertEq(abLen, abxLen)
+            const abU = uint(ab)
+            const abxU = uint(abx)
+            assertEq(abU, abxU)
+        }
+        c(vec(4n)(0xFn))(vec(8n)(0xA7n))(vec(12n)(0xFA7n))
+        c(vec(4n)(0xFn))(vec(8n)(0x57n))(vec(12n)(0xF57n))
+        c(vec(4n)(0x5n))(vec(8n)(0xA7n))(vec(12n)(0x5A7n))
+        c(vec(4n)(0x5n))(vec(8n)(0x79n))(vec(12n)(0x579n))
+    },
+    lsbXor: () => {
+        const c = (/** @type {Vec} */ a) => (/** @type {Vec} */ b) => (/** @type {Vec} */ e) => {
+            const r = lsb.xor(a)(b)
+            assertEq(r, e)
+        }
+        c(vec(4n)(0x7n))(vec(8n)(0x12n))(vec(8n)(0x7n ^ 0x12n))
+    },
+    msbXor: () => {
+        const c = (/** @type {Vec} */ a) => (/** @type {Vec} */ b) => (/** @type {Vec} */ e) => {
+            const r = msb.xor(a)(b)
+            assertEq(r, e)
+        }
+        c(vec(4n)(0x7n))(vec(8n)(0x12n))(vec(8n)(0x70n ^ 0x12n))
+    },
+    repeat: () => {
+        assertEq(repeat(4n)(vec8(0xA5n)), vec(32n)(0xA5A5A5A5n), 'repeat failed')
+        assertEq(repeat(7n)(vec(5n)(0x13n)), vec(35n)(0b10011_10011_10011_10011_10011_10011_10011n), 'repeat failed')
+    },
+    lsbCmp: () => {
+        const c = (/** @type {Vec} */ a) => (/** @type {Vec} */ b) => (/** @type {Sign} */ r) => {
+            const result = lsb.cmp(a)(b)
+            if (result !== r) { throw `result: ${result}, expected: ${r}` }
+        }
+        c(vec(4n)(0x5n))(vec(4n)(0x5n))(0)   // [1,0,1,0] == [1,0,1,0]
+        c(vec(4n)(0x5n))(vec(4n)(0x6n))(1)   // bit0: 1 > 0
+        c(vec(4n)(0x6n))(vec(4n)(0x5n))(-1)  // bit0: 0 < 1
+        c(vec(4n)(0x5n))(vec(5n)(0x5n))(-1)  // equal prefix, shorter is less
+        c(vec(5n)(0x5n))(vec(4n)(0x5n))(1)   // equal prefix, longer is greater
+        c(vec(4n)(0x5n))(vec(5n)(0xAn))(1)   // bit0: 1 > 0
+    },
+    msbCmp: () => {
+        const c = (/** @type {Vec} */ a) => (/** @type {Vec} */ b) => (/** @type {Sign} */ r) => {
+            const result = msb.cmp(a)(b)
+            if (result !== r) { throw `result: ${result}, expected: ${r}` }
+        }
+        c(vec(4n)(0x5n))(vec(4n)(0x5n))(0)  // 0b0101 == 0b0101
+        c(vec(4n)(0x5n))(vec(4n)(0x6n))(-1) // 0b0101 < 0b0110
+        c(vec(4n)(0x6n))(vec(4n)(0x5n))(1)  // 0b0110 > 0b0101
+        c(vec(4n)(0x5n))(vec(5n)(0x5n))(1)  // 0b0101_ < 0b00101
+        c(vec(5n)(0x5n))(vec(4n)(0x5n))(-1) // 0b00101 < 0b0101_
+        c(vec(4n)(0x5n))(vec(5n)(0xAn))(-1) // 0b0101_ < 0b01010
+    },
+    startsWith: {
+        // vector 0xF5 = 0b1111_0101 (8 bits)
+        // LSB reads from the low end: bits 0-3 = 0101 = 0x5, bits 4-7 = 1111 = 0xF
+        lsb: () => {
+            const v = vec(8n)(0xF5n)
+            assertEq(lsb.startsWith(vec(4n)(0x5n))(v), true)   // low nibble matches
+            assertEq(lsb.startsWith(vec(4n)(0xFn))(v), false)  // low nibble doesn't match
+            assertEq(lsb.startsWith(v)(vec(4n)(0x5n)), false)  // prefix longer than vector
+            assertEq(lsb.startsWith(empty)(v), true)            // empty prefix always matches
+        },
+        // MSB reads from the high end: bits 0-3 = 1111 = 0xF, bits 4-7 = 0101 = 0x5
+        msb: () => {
+            const v = vec(8n)(0xF5n)
+            assertEq(msb.startsWith(vec(4n)(0xFn))(v), true)   // high nibble matches
+            assertEq(msb.startsWith(vec(4n)(0x5n))(v), false)  // high nibble doesn't match
+            assertEq(msb.startsWith(v)(vec(4n)(0xFn)), false)  // prefix longer than vector
+            assertEq(msb.startsWith(empty)(v), true)            // empty prefix always matches
+        },
+        emptyVec: () => {
+            assertEq(lsb.startsWith(empty)(empty), true)
+            assertEq(msb.startsWith(empty)(empty), true)
+        },
+    },
+    u8ListToVec: () => {
+        // 131_072 is too much for Bun
+        const x = u8ListToVec(msb)(listRepeat(0x12)(131_071))
+        return () => {
+            const m = u8List(msb)(x)
+            const y = toArray(m)
+            if (y.length !== 131_071) {
+                throw `y.lenght: ${y.length}`
+            }
+        }
+    },
+    tryListToVecOverflow: () => {
+        /** @type {List<Vec>} */
+        const list = [vec(maxLength)(1n), vec(1n)(1n)]
+        assertEq(lsb.tryListToVec(list), null)
+        assertEq(msb.tryListToVec(list), null)
+        // Overflow is an absorbing element, so it survives every later
+        // combination: here the failed pair ends up on the left of the last
+        // one, and on the right in the two-element case above.
+        /** @type {List<Vec>} */
+        const longer = [vec(maxLength)(1n), vec(1n)(1n), vec(1n)(1n)]
+        assertEq(lsb.tryListToVec(longer), null)
+        assertEq(msb.tryListToVec(longer), null)
+    },
+    tryListToVecUnbounded: () => {
+        // `List` includes `Thunk`, so an unbounded lazy list is a legal input —
+        // and at 128 KiB, `maxLength` is an ordinary amount for a stream to
+        // exceed. Overflow being absorbing is what lets the fold answer instead
+        // of reading forever: each element here is half of `maxLength`, so the
+        // total crosses the cap at the third and the merge that sees it happens
+        // at the fourth. The rest of the list asserts it is never read.
+        const half = vec(maxLength / 2n)(1n)
+        /** @type {(n: number) => List<Vec>} */
+        const from = n => () => {
+            assert(n <= 8)
+            return { first: half, tail: from(n + 1) }
+        }
+        assertEq(lsb.tryListToVec(from(1)), null)
+        assertEq(msb.tryListToVec(from(1)), null)
+    },
+    listToVecOverflow: {
+        // Same oversized input, but through the throwing `listToVec` wrapper.
+        throw: () => {
+            /** @type {List<Vec>} */
+            const list = { first: vec(maxLength + 1n)(1n), tail: null }
+            lsb.listToVec(list)
+        },
+    },
+    u8ListToVecOverflow: {
+        // 131_073 bytes is 8 bits past `maxLength`; same null/throw split as
+        // `tryListToVec`/`listToVec` above, exercised through the byte-list API.
+        try: () => {
+            assertEq(tryU8ListToVec(msb)(listRepeat(0x12)(131_073)), null)
+        },
+        throw: () => {
+            u8ListToVec(msb)(listRepeat(0x12)(131_073))
+        },
+    },
+    u8ListUnaligned: () => {
+        const x = vec(9n)(0x83n)
+        const a = toArray(u8List(msb)(x))
+        if (a.length !== 2) {
+            throw `a.lenght: ${a.length}`
+        }
+        const [a0, a1] = a
+        if (a0 !== 0x41) {
+            throw `a0: ${a0.toString(16)}`
+        }
+        if (a1 !== 0x80) {
+            throw `a1: ${a1.toString(16)}`
+        }
+    },
+    chunkList: {
+        empty: () => {
+            const chunks = toArray(chunkList(lsb)(4n)(empty))
+            assertEq(chunks.length, 0)
+        },
+        // 8-bit vector 0xF5 = 0b1111_0101, aligned to 4-bit chunks
+        lsb_aligned: () => {
+            const chunks = toArray(chunkList(lsb)(4n)(vec(8n)(0xF5n)))
+            // LSB: low nibble first — bits 0-3 = 0101 = 5, bits 4-7 = 1111 = 15
+            assertEq(chunks.length, 2)
+            assert(!(length(chunks[0]) !== 4n || uint(chunks[0]) !== 5n), chunks[0])
+            assert(!(length(chunks[1]) !== 4n || uint(chunks[1]) !== 0xFn), chunks[1])
+        },
+        msb_aligned: () => {
+            const chunks = toArray(chunkList(msb)(4n)(vec(8n)(0xF5n)))
+            // MSB: high nibble first — bits 0-3 = 1111 = 15, bits 4-7 = 0101 = 5
+            assertEq(chunks.length, 2)
+            assert(!(length(chunks[0]) !== 4n || uint(chunks[0]) !== 0xFn), chunks[0])
+            assert(!(length(chunks[1]) !== 4n || uint(chunks[1]) !== 5n), chunks[1])
+        },
+        // 10-bit vector 0x1B5 = 0b01_1011_0101, unaligned to 4-bit chunks (last chunk is 2 bits)
+        lsb_unaligned: () => {
+            const chunks = toArray(chunkList(lsb)(4n)(vec(10n)(0x1B5n)))
+            // LSB: bits 0-3 = 0101 = 5, bits 4-7 = 1011 = 11, bits 8-9 = 01 = 1
+            assertEq(chunks.length, 3)
+            assert(!(length(chunks[0]) !== 4n || uint(chunks[0]) !== 5n), chunks[0])
+            assert(!(length(chunks[1]) !== 4n || uint(chunks[1]) !== 0xBn), chunks[1])
+            assert(!(length(chunks[2]) !== 2n || uint(chunks[2]) !== 1n), chunks[2])
+        },
+        msb_unaligned: () => {
+            const chunks = toArray(chunkList(msb)(4n)(vec(10n)(0x1B5n)))
+            // MSB: bits 0-3 = 0110 = 6, bits 4-7 = 1101 = 13, bits 8-9 = 01 = 1
+            assertEq(chunks.length, 3)
+            assert(!(length(chunks[0]) !== 4n || uint(chunks[0]) !== 6n), chunks[0])
+            assert(!(length(chunks[1]) !== 4n || uint(chunks[1]) !== 0xDn), chunks[1])
+            assert(!(length(chunks[2]) !== 2n || uint(chunks[2]) !== 1n), chunks[2])
+        },
+    },
+}

package/fjs/types/bit_vec/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Types for bit vectors normalized on the most-significant bit.
+ *
+ * @module
+ */
+import type { Sign } from '../function/compare/types.ts';
+import type { Binary, Reduce as OpReduce } from '../function/operator/types.ts';
+import type { List } from '../list/types.ts';
+import type { Nominal } from '../nominal/types.ts';
+import type { Nullable } from '../nullable/types.ts';
+type _Revision = '1a23a4336197e6158b6936cad34e90d146cd84b9b40ff7ab75a17c6d79e31d89';
+/**
+ * A vector of bits represented as a signed `bigint`.
+ */
+export type Vec = Nominal<'bit_vec', _Revision, bigint>;
+/**
+ * Structure describing the unpacked view of a vector.
+ */
+export type Unpacked = {
+    readonly length: bigint;
+    readonly uint: bigint;
+};
+export type _Norm = (len: bigint) => {
+    readonly a: bigint;
+    readonly b: bigint;
+};
+export type _NormOp = Binary<Unpacked, Unpacked, _Norm>;
+export type _UnpackConcat = (a: Unpacked) => (b: Unpacked) => Unpacked;
+export type Reduce = OpReduce<Vec>;
+export type PopFront<T> = (len: bigint) => (u: T) => readonly [bigint, T];
+/**
+ * Represents operations for handling bit vectors with a specific bit order.
+ *
+ * https://en.wikipedia.org/wiki/Bit_numbering
+ */
+export type BitOrder = {
+    readonly front: (len: bigint) => (v: Vec) => bigint;
+    readonly removeFront: (len: bigint) => (v: Vec) => Vec;
+    readonly popFront: PopFront<Vec>;
+    readonly concat: Reduce;
+    readonly tryListToVec: (list: List<Vec>) => Nullable<Vec>;
+    readonly listToVec: (list: List<Vec>) => Vec;
+    readonly xor: Reduce;
+    readonly unpackPopFront: PopFront<Unpacked>;
+    readonly norm: _NormOp;
+    readonly cmp: (a: Vec) => (b: Vec) => Sign;
+    readonly unpackSplit: (len: bigint) => (u: Unpacked) => readonly [bigint, bigint];
+    readonly unpackConcat: _UnpackConcat;
+    readonly startsWith: (prefix: Vec) => (v: Vec) => boolean;
+};
+export {};

package/fjs/types/btree/find/module.f.d.mts

@@ -0,0 +1,19 @@
+/**
+ * Lookup operations for persistent B-tree structures.
+ *
+ * @module
+ *
+ * @import { TNode } from '../types/types.ts'
+ * @import { Compare } from '../../function/compare/types.ts'
+ * @import { KeyOf } from '../../array/types.ts'
+ * @import { First, Path, PathItem, Result } from './types.ts'
+ */
+import type { TNode } from '../types/types.ts';
+import type { Compare } from '../../function/compare/types.ts';
+import type { First, Result } from './types.ts';
+/** @type {<T>(c: Compare<T>) => (node: TNode<T>) => Result<T>} */
+export declare const find: <T>(c: Compare<T>) => (node: TNode<T>) => Result<T>;
+/** @type {<T>(first: First<T>) => boolean} */
+export declare const isFound: <T>(first: First<T>) => boolean;
+/** @type {<T>(first: First<T>) => T | null} */
+export declare const value: <T>(first: First<T>) => T | null;

package/fjs/types/btree/find/module.f.mjs

@@ -0,0 +1,80 @@
+/**
+ * Lookup operations for persistent B-tree structures.
+ *
+ * @module
+ *
+ * @import { TNode } from '../types/types.ts'
+ * @import { Compare } from '../../function/compare/types.ts'
+ * @import { KeyOf } from '../../array/types.ts'
+ * @import { First, Path, PathItem, Result } from './types.ts'
+ */
+
+import { index3, index5 } from '../../function/compare/module.f.mjs'
+
+/** @type {<T>(item: PathItem<T>) => TNode<T>} */
+const child = item => {
+    /** @typedef {typeof item extends PathItem<infer T> ? T : never} T */
+    return /** @type {TNode<T>} */ (item[1][item[0]])
+}
+
+/** @type {<T>(c: Compare<T>) => (node: TNode<T>) => Result<T>} */
+export const find = c => {
+    /** @typedef {typeof c extends Compare<infer T> ? T : never} T */
+    const i3 = index3(c)
+    const i5 = index5(c)
+    /** @type {(tail: Path<T>) => (node: TNode<T>) => Result<T>} */
+    const f = tail => node => {
+        /** @type {(index: KeyOf<typeof node>) => Result<T>} */
+        const append = index => {
+            const first = /** @type {PathItem<T>} */ ([index, node])
+            return f({ first, tail })(child(first))
+        }
+        /** @type {(index: KeyOf<typeof node>) => Result<T>} */
+        const done = index => ({ first: /** @type {First<T>} */ ([index, node]), tail })
+        switch (node.length) {
+            case 1: { return done(i3(node[0])) }
+            case 2: { return done(i5(node)) }
+            case 3: {
+                const i = i3(node[1])
+                switch (i) {
+                    case 0: case 2: { return append(i) }
+                    case 1: { return done(i) }
+                }
+            }
+            case 5: {
+                const i = i5([node[1], node[3]])
+                switch (i) {
+                    case 0: case 2: case 4: { return append(i) }
+                    case 1: case 3: { return done(i) }
+                }
+            }
+        }
+    }
+    return f(null)
+}
+
+/** @type {<T>(first: First<T>) => boolean} */
+export const isFound = ([i]) => {
+    switch (i) {
+        case 1: case 3: { return true }
+        default: { return false }
+    }
+}
+
+/** @type {<T>(first: First<T>) => T | null} */
+export const value = ([i, r]) => {
+    switch (i) {
+        case 1: {
+            switch (r.length) {
+                case 1: case 2: { return r[0] }
+                default: { return r[1] }
+            }
+        }
+        case 3: {
+            return r.length === 2 ? r[1] : r[3]
+        }
+        default: {
+            return null
+        }
+    }
+}

package/fjs/types/btree/find/proof.f.d.mts

@@ -0,0 +1,8 @@
+/**
+ * @import { Unknown } from '../../../media/json/types.ts'
+ * @import { Result } from './types.ts'
+ * @import { TNode } from '../types/types.ts'
+ */
+declare const test: () => void;
+export declare const proof: typeof test;
+export {};