functionalscript 0.43.1 → 0.45.0

package/fjs/asn.1/proof.f.d.mts

@@ -0,0 +1,53 @@
+/**
+ * @import { Vec } from '../types/bit_vec/types.ts'
+ * @import { SupportedRecord, ObjectIdentifier } from './types.ts'
+ */
+export declare const proof: {
+    encodeSmall: () => void;
+    encode7F: () => void;
+    encode80: () => void;
+    encodeFF: () => void;
+    encode103: () => void;
+    ed: ((() => void) | {
+        x80: () => void;
+        x100: () => void;
+        x1000: () => void;
+        x10000: () => void;
+        x20000: () => void;
+        x40000: () => void;
+        x80000: () => void;
+        xC0000: () => void;
+        xE0000: () => void;
+        xF0000: () => void;
+        xFFF00: () => void;
+        xFFF80: () => void;
+        xFFFC0: () => void;
+        xFFFD0: () => void;
+    })[];
+    integerValue: {
+        zero: () => void;
+        one: () => void;
+        minusOne: () => void;
+        x7F: () => void;
+        x80: () => void;
+        xFF: () => void;
+        nx7F: () => void;
+        nx80: () => void;
+        nx81: () => void;
+        nx7FFF: () => void;
+        nx8000: () => void;
+        nx8001: () => void;
+    };
+    encodeDecode: {
+        integer: () => void;
+        sequence: () => void;
+        set: () => void;
+        objectIdentifier: () => void;
+    };
+    objectIdentifier: {
+        simple: () => void;
+        withArc: () => void;
+    };
+    unknownTag: () => void;
+    raw: (() => void)[];
+};

package/fjs/asn.1/proof.f.mjs

@@ -0,0 +1,321 @@
+/**
+ * @import { Vec } from '../types/bit_vec/types.ts'
+ * @import { SupportedRecord, ObjectIdentifier } from './types.ts'
+ */
+
+import { empty, isVec, length, msb, uint, unpack, vec, vec8 } from '../types/bit_vec/module.f.mjs'
+import { asBase } from '../types/nominal/module.f.mjs'
+
+import {
+    decodeRaw,
+    decodeInteger,
+    encodeRaw,
+    encodeInteger,
+    integer,
+    encode,
+    decode,
+    constructedSequence,
+    octetString,
+    boolean,
+    constructedSet,
+    objectIdentifier,
+    encodeObjectIdentifier,
+    decodeObjectIdentifier,
+} from './module.f.mjs'
+
+import { assert, assertEq } from '../asserts/module.f.mjs'
+
+const { concat, popFront: pop, listToVec } = msb
+const pop8 = pop(8n)
+
+/**
+ * @param {bigint} tag
+ * @param {Vec} v
+ * @param {Vec} rest
+ */
+const check = (tag, v, rest) => {
+    const s = encodeRaw([tag, v])
+    const [[t0, v0], r] = decodeRaw(concat(s)(rest))
+    if (t0 !== tag) { throw `t0: ${t0}` }
+    if (v0 !== v) { throw `v0: ${asBase(v0)}` }
+    if (r !== rest) { throw `r: ${asBase(r)}` }
+}
+
+/**
+ * @param {bigint} i
+ * @param {Vec} v
+ */
+const integerValueCheck = (i, v) => {
+    const v0 = encodeInteger(i)
+    if (v !== v0) { throw `encode: ${asBase(v)}, ${asBase(v0)}` }
+    const i0 = decodeInteger(v)
+    assertEq(i, i0, [i, i0])
+}
+
+/**
+ * @param {SupportedRecord} r
+ * @param {Vec} v
+ * @param {Vec} rest
+ */
+const ch0 = (r, v, rest) => {
+    const [r0, rest0] = decode(concat(v)(rest))
+    if (rest0 !== rest) { throw `rest: ${asBase(rest0)}` }
+    const v0 = encode(r)
+    const v1 = encode(r0)
+    if (v !== v0) { throw `encode: ${asBase(v)}, ${asBase(v0)}` }
+    if (v !== v1) { throw `encode: ${asBase(v)}, ${asBase(v1)}` }
+}
+
+/**
+ * @param {SupportedRecord} r
+ * @param {Vec} v
+ */
+const ch = (r, v) => {
+    ch0(r, v, empty)
+    ch0(r, v, vec8(0x23n))
+    ch0(r, v, vec(16n)(0x2345n))
+}
+
+export const proof = {
+    encodeSmall: () => {
+        const v = vec8(0x13n)
+        const x = encodeRaw([integer, v])
+        const lx = length(x)
+        assertEq(lx, 24n)
+        const [tag, x1] = pop8(x)
+        assertEq(tag, BigInt(integer))
+        const [len, x2] = pop8(x1)
+        assertEq(len, 1n)
+        const { length: intLen, uint } = unpack(x2)
+        assertEq(intLen, 8n)
+        assertEq(uint, 0x13n)
+    },
+    encode7F: () => {
+        const valueLen = 0x7Fn << 3n
+        const value = 0x1234n
+        const v = vec(valueLen)(value)
+        const x = encodeRaw([integer, v])
+        const lx = length(x)
+        assertEq(lx, 0x81n << 3n)
+        const [tag, x1] = pop8(x)
+        assertEq(tag, BigInt(integer))
+        const [len, x2] = pop8(x1)
+        assertEq(len, 0x7Fn)
+        const { length: intLen, uint } = unpack(x2)
+        assertEq(intLen, valueLen)
+        assertEq(uint, value)
+    },
+    encode80: () => {
+        const valueLen = 0x80n << 3n
+        const value = 0x123456n
+        const v = vec(valueLen)(value)
+        const x = encodeRaw([integer, v])
+        const lx = length(x)
+        assertEq(lx, 0x83n << 3n)
+        const [tag, x1] = pop8(x)
+        assertEq(tag, BigInt(integer))
+        const [lenLen, x2] = pop8(x1)
+        assertEq(lenLen, 0x81n)
+        const [len, x3] = pop8(x2)
+        assertEq(len, 0x80n)
+        const { length: intLen, uint } = unpack(x3)
+        assertEq(intLen, valueLen)
+        assertEq(uint, value)
+    },
+    encodeFF: () => {
+        const valueLen = 0xFFn << 3n
+        const value = 0x123456n
+        const v = vec(valueLen)(value)
+        const x = encodeRaw([integer, v])
+        const lx = length(x)
+        if (lx !== valueLen + (3n << 3n)) { throw `lx: ${lx}` }
+        const [tag, x1] = pop8(x)
+        assertEq(tag, BigInt(integer))
+        const [lenLen, x2] = pop8(x1)
+        assertEq(lenLen, 0x81n)
+        const [len, x3] = pop8(x2)
+        assertEq(len, 0xFFn)
+        const { length: intLen, uint } = unpack(x3)
+        assertEq(intLen, valueLen)
+        assertEq(uint, value)
+    },
+    encode103: () => {
+        const valueLen = 0x103n << 3n
+        const value = 0x123456n
+        const v = vec(valueLen)(value)
+        const x = encodeRaw([integer, v])
+        const lx = length(x)
+        if (lx !== valueLen + (4n << 3n)) { throw `lx: ${lx}` }
+        const [tag, x1] = pop8(x)
+        assertEq(tag, BigInt(integer))
+        const [lenLen, x2] = pop8(x1)
+        assertEq(lenLen, 0x82n)
+        const [len, x3] = pop(16n)(x2)
+        assertEq(len, 0x103n)
+        const { length: intLen, uint } = unpack(x3)
+        assertEq(intLen, valueLen)
+        assertEq(uint, value)
+    },
+    ed: [
+        () => {
+            const tag = integer
+            const v = vec(0x10n)(0x8234n)
+            assertEq(asBase(v), 0x8234n, asBase(v).toString(16))
+            check(integer, v, empty)
+        },
+        {
+            x80: () => check(integer, vec(0x80n)(0x8234n), empty),
+            x100: () => check(integer, vec(0x100n)(0x8234n), vec8(0x23n)),
+            x1000: () => check(integer, vec(0x1000n)(0x8234n), vec8(0x23n)),
+            x10000: () => check(integer, vec(0x1_0000n)(0x8234n), vec8(0x23n)),
+            x20000: () => check(integer, vec(0x2_0000n)(0x8234n), vec8(0x23n)),
+            x40000: () => check(integer, vec(0x4_0000n)(0x8234n), empty),
+            x80000: () => check(integer, vec(0x8_0000n)(0x8234n), empty),
+            xC0000: () => check(integer, vec(0xC_0000n)(0x8234n), empty),
+            xE0000: () => check(integer, vec(0xE_0000n)(0x8234n), empty),
+            xF0000: () => check(integer, vec(0xF_0000n)(0x8234n), empty),
+            xFFF00: () => check(integer, vec(0xF_FF00n)(0x8234n), empty),
+            xFFF80: () => check(integer, vec(0xF_FF80n)(0x8234n), empty),
+            xFFFC0: () => check(integer, vec(0xF_FFC0n)(0x8234n), empty),
+            xFFFD0: () => check(integer, vec(0xF_FFD0n)(0x8234n), empty),
+            //// fail on Bun because it has a smaller limit for BigInt
+            //xFFFD8: () => check(integer, vec(0xF_FFD8n)(0x8234n), empty),
+            //xFFFE0: () => check(integer, vec(0xF_FFE0n)(0x8234n), empty),
+            //e100000: () => check(integer, vec(0x10_0000n)(0x8234n), empty),
+            //x100000: () => check(integer, vec(0x10_0000n)(0x8234n), vec8(0x23n)),
+            //x1000000: () => check(integer, vec(0x100_0000n)(0x8234n), vec8(0x23n)),
+            //x10000000: () => check(integer, vec(0x1000_0000n)(0x8234n), vec8(0x23n)),
+            //x20000000: () => check(integer, vec(0x2000_0000n)(0x8234n), vec8(0x23n)),
+            //x30000000: () => check(integer, vec(0x3000_0000n)(0x8234n), vec8(0x23n)),
+            //x38000000: () => check(integer, vec(0x3800_0000n)(0x8234n), vec8(0x23n)),
+            //x3C000000: () => check(integer, vec(0x3800_0000n)(0x8234n), vec8(0x23n)),
+            //x3E000000: () => check(integer, vec(0x3E00_0000n)(0x8234n), vec8(0x23n)),
+            //x3F000000: () => check(integer, vec(0x3F00_0000n)(0x8234n), vec8(0x23n)),
+            //x3F800000: () => check(integer, vec(0x3F80_0000n)(0x8234n), vec8(0x23n)),
+            //x3FFFFFC0: () => check(integer, vec(0x3FFF_FFC0n)(0x8234n), vec8(0x23n)),
+            //e3FFFFFC8: () => check(integer, vec(0x3FFF_FFC8n)(0x8234n), empty),
+            //// fail on Node
+            //x3FFFFFC8: () => check(integer, vec(0x3FFF_FFC1n)(0x8234n), vec8(0x23n)),
+            //x40000000: () => check(integer, vec(0x4000_0000n)(0x8234n), vec8(0x23n)),
+            // check(integer, vec(0x1_0000_0000n)(0x8234n), vec8(0x23n))
+        },
+    ],
+    integerValue: {
+        zero: () => integerValueCheck(0n, vec8(0n)),
+        one: () => integerValueCheck(1n, vec8(1n)),
+        minusOne: () => integerValueCheck(-1n, vec8(0xFFn)),
+        x7F: () => integerValueCheck(0x7Fn, vec8(0x7Fn)),
+        x80: () => integerValueCheck(0x80n, vec(16n)(0x80n)),
+        xFF: () => integerValueCheck(0xFFn, vec(16n)(0xFFn)),
+        nx7F: () => integerValueCheck(-0x7Fn, vec8(0x81n)),
+        nx80: () => integerValueCheck(-0x80n, vec8(0x80n)),
+        nx81: () => integerValueCheck(-0x81n, vec(16n)(0xFF7Fn)),
+        nx7FFF: () => integerValueCheck(-0x7FFFn, vec(16n)(0x8001n)),
+        nx8000: () => integerValueCheck(-0x8000n, vec(16n)(0x8000n)),
+        nx8001: () => integerValueCheck(-0x8001n, vec(24n)(0xFF7FFFn)),
+    },
+    encodeDecode: {
+        integer: () => {
+            ch([integer, 0n], listToVec([vec8(BigInt(integer)), vec8(1n), vec8(0n)]))
+            ch([integer, 1n], listToVec([vec8(BigInt(integer)), vec8(1n), vec8(1n)]))
+        },
+        sequence: () => {
+            ch([constructedSequence, []], listToVec([vec8(BigInt(constructedSequence)), vec8(0n)]))
+            ch(
+                [constructedSequence, [[integer, 0n]]],
+                listToVec([vec8(BigInt(constructedSequence)), vec8(3n), encode([integer, 0n])])
+            )
+            ch(
+                [constructedSequence, [[integer, 1n], [integer, 2n]]],
+                listToVec([
+                    vec8(BigInt(constructedSequence)),
+                    vec8(6n),
+                    encode([integer, 1n]),
+                    encode([integer, 2n])
+                ])
+            )
+            ch(
+                [constructedSequence, [[octetString, vec8(0x23n)], [boolean, true], [boolean, false]]],
+                listToVec([
+                    vec8(BigInt(constructedSequence)),
+                    vec8(9n),
+                    encode([octetString, vec8(0x23n)]),
+                    encode([boolean, true]),
+                    encode([boolean, false]),
+                ])
+            )
+        },
+        set: () => {
+            ch([constructedSet, [[integer, 2n], [integer, 1n]]],
+                listToVec([
+                    vec8(BigInt(constructedSet)),
+                    vec8(6n),
+                    encode([integer, 1n]),
+                    encode([integer, 2n])
+                ])
+            )
+        },
+        objectIdentifier: () => {
+            // exercises the objectIdentifier case in recordToRaw/rawToRecord
+            // via the generic encode/decode dispatch (the objectIdentifier
+            // tests below only call encodeObjectIdentifier/decodeObjectIdentifier
+            // directly, never through decode()).
+            /** @type {SupportedRecord} */
+            const r = [objectIdentifier, [1n, 2n, 840n, 113549n]]
+            ch0(r, encode(r), empty)
+        },
+    },
+    objectIdentifier: {
+        simple: () => {
+            /** @type {ObjectIdentifier} */
+            const oid = [1n, 2n]
+            const encoded = encodeObjectIdentifier(oid)
+            const decoded = decodeObjectIdentifier(encoded)
+            assertEq(decoded.length, 2)
+            assertEq(decoded[0], 1n)
+            assertEq(decoded[1], 2n)
+        },
+        withArc: () => {
+            // OID 1.2.840.113549 (RSA)
+            /** @type {ObjectIdentifier} */
+            const oid = [1n, 2n, 840n, 113549n]
+            const decoded = decodeObjectIdentifier(encodeObjectIdentifier(oid))
+            assertEq(decoded.length, 4)
+            assertEq(decoded[0], 1n)
+            assertEq(decoded[1], 2n)
+            assertEq(decoded[2], 840n)
+            assertEq(decoded[3], 113549n)
+        },
+    },
+    unknownTag: () => {
+        // bitString (0x03) is not in SupportedRecord, exercises the default case in rawToRecord
+        const raw = encodeRaw([0x03n, vec8(0x42n)])
+        const [decoded, rest] = decode(raw)
+        assert(isVec(decoded), 'expected UnsupportedRecord (Vec)')
+        assertEq(rest, empty, 'expected empty rest')
+        // Re-encoding an UnsupportedRecord returns it unchanged (it is already the TLV bytes)
+        assertEq(encode(decoded), raw, 'encode should round-trip UnsupportedRecord')
+    },
+    raw: [
+        () => {
+            const e = encodeRaw([0x00n, vec8(0x23n)])
+            if (e !== listToVec([vec8(0x00n), vec8(1n), vec8(0x23n)])) { throw `encode: ${length(e)}: ${uint(e).toString(2)}` }
+            const [[tag, value], rest] = decodeRaw(e)
+            if (rest !== empty) { throw `rest: ${asBase(rest)}` }
+            if (tag !== 0x00n) { throw `tag: ${tag}` }
+            if (value !== vec8(0x23n)) { throw `value: ${asBase(value)}` }
+        },
+        () => {
+            const e = encodeRaw([0x1F20n, vec(16n)(0x1234n)])
+            if (e !== listToVec([vec8(0x1Fn), vec8(0x20n), vec8(2n), vec(16n)(0x1234n)])) {
+                const l = length(e)
+                const u = uint(e)
+                throw `encode: ${l}: ${u.toString(16)}`
+            }
+            const [[tag, value], rest] = decodeRaw(e)
+            if (rest !== empty) { throw `rest: ${asBase(rest)}` }
+            if (tag !== 0x1F20n) { throw `tag: ${tag}` }
+            if (value !== vec(16n)(0x1234n)) { throw `value: ${asBase(value)}` }
+        }
+    ]
+}

package/fjs/asn.1/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Types for ASN.1 BER/DER encoding and decoding over bit vectors.
+ *
+ * @module
+ */
+import type { Vec } from '../types/bit_vec/types.ts';
+import type { boolean as booleanTag, constructedSequence, constructedSet, integer, objectIdentifier, octetString } from './module.f.mjs';
+/**
+ * ASN.1 tag number.
+ */
+export type _Tag = bigint;
+/**
+ * Raw ASN.1 TLV tuple.
+ */
+export type Raw = readonly [_Tag, Vec];
+/**
+ * ASN.1 OBJECT IDENTIFIER components.
+ */
+export type ObjectIdentifier = readonly bigint[];
+/**
+ * ASN.1 ordered collection of records.
+ */
+export type Sequence = readonly Record[];
+/**
+ * ASN.1 SET represented as a sequence of records.
+ */
+export type Set = Sequence;
+/**
+ * Supported ASN.1 record variants.
+ */
+export type SupportedRecord = readonly [typeof booleanTag, boolean] | readonly [typeof integer, bigint] | readonly [typeof octetString, Vec] | readonly [typeof objectIdentifier, ObjectIdentifier] | readonly [typeof constructedSequence, Sequence] | readonly [typeof constructedSet, Set];
+/**
+ * For unsupported tags, we just store the raw value including the tag and
+ * length, so that it can be re-encoded without loss of information.
+ */
+export type UnsupportedRecord = Vec;
+export type Record = SupportedRecord | UnsupportedRecord;

package/fjs/asserts/module.f.d.mts

@@ -0,0 +1,51 @@
+/**
+ * Assertion helpers for runtime checks and compile-time type-level tests.
+ *
+ * @module
+ */
+/**
+ * Marks a code path as unimplemented. Always throws.
+ * @type {() => never}
+ */
+export declare const todo: () => never;
+/**
+ * Throws `msg` (default `'assertion failed'`) if `v` is `false`.
+ *
+ * Narrows `v` to `true` via `asserts v`, so callers can rely on the
+ * condition holding for the rest of the enclosing scope.
+ *
+ * @type {(v: boolean, msg?: unknown) => asserts v}
+ */
+export declare const assert: (v: boolean, msg?: unknown) => asserts v;
+/**
+ * Asserts that `a` and `b` are `===`, throwing `x` (the `[a, b]` pair, plus
+ * an optional third element used as an extra message) if they differ.
+ *
+ * @type {<T>(...x: readonly[T, T, unknown?]) => void}
+ */
+export declare const assertEq: <T>(...x: readonly [T, T, unknown?]) => void;
+/**
+ * Asserts that `a` and `b` are structurally the same — equal leaves under the
+ * same shape, property order irrelevant — throwing `x` (the `[a, b]` pair, plus
+ * an optional third element used as an extra message) if they differ.
+ *
+ * This is the assertion to reach for when comparing two independently
+ * constructed values. `assertEq` is `===`, so it only ever answers "the same
+ * reference?" for objects, which is why proofs fell back to comparing
+ * `JSON.stringify` output; see `types/object/structurally_same/README.md` for
+ * why that is the wrong question and what this one does *not* cover.
+ *
+ * @type {(...x: readonly[unknown, unknown, unknown?]) => void}
+ */
+export declare const assertStructurallySame: (...x: readonly [unknown, unknown, unknown?]) => void;
+/**
+ * Asserts that `a` is neither `null` nor `undefined` and returns it,
+ * narrowed to `T`.
+ *
+ * Use this to chain directly off a call that may return a nullish value,
+ * e.g. `const r = assertNotNullish(f(x))`. For a variable that already
+ * exists, prefer `assert(a !== null && a !== undefined)` instead.
+ *
+ * @type {<T>(a: T|null|undefined, msg?: unknown) => T}
+ */
+export declare const assertNotNullish: <T>(a: T | null | undefined, msg?: unknown) => T;

package/fjs/asserts/module.f.mjs

@@ -0,0 +1,69 @@
+/**
+ * Assertion helpers for runtime checks and compile-time type-level tests.
+ *
+ * @module
+ */
+
+import { structurallySame } from '../types/object/structurally_same/module.f.mjs'
+
+/**
+ * Marks a code path as unimplemented. Always throws.
+ * @type {() => never}
+ */
+export const todo = () => { throw 'not implemented' }
+
+/**
+ * Throws `msg` (default `'assertion failed'`) if `v` is `false`.
+ *
+ * Narrows `v` to `true` via `asserts v`, so callers can rely on the
+ * condition holding for the rest of the enclosing scope.
+ *
+ * @type {(v: boolean, msg?: unknown) => asserts v}
+ */
+export const assert = (v, msg = 'assertion failed') => {
+    if (!v) throw msg
+}
+
+/**
+ * Asserts that `a` and `b` are `===`, throwing `x` (the `[a, b]` pair, plus
+ * an optional third element used as an extra message) if they differ.
+ *
+ * @type {<T>(...x: readonly[T, T, unknown?]) => void}
+ */
+export const assertEq = (...x) => {
+    const [a, b] = x
+    assert(a === b, x)
+}
+
+/**
+ * Asserts that `a` and `b` are structurally the same — equal leaves under the
+ * same shape, property order irrelevant — throwing `x` (the `[a, b]` pair, plus
+ * an optional third element used as an extra message) if they differ.
+ *
+ * This is the assertion to reach for when comparing two independently
+ * constructed values. `assertEq` is `===`, so it only ever answers "the same
+ * reference?" for objects, which is why proofs fell back to comparing
+ * `JSON.stringify` output; see `types/object/structurally_same/README.md` for
+ * why that is the wrong question and what this one does *not* cover.
+ *
+ * @type {(...x: readonly[unknown, unknown, unknown?]) => void}
+ */
+export const assertStructurallySame = (...x) => {
+    const [a, b] = x
+    assert(structurallySame(a, b), x)
+}
+
+/**
+ * Asserts that `a` is neither `null` nor `undefined` and returns it,
+ * narrowed to `T`.
+ *
+ * Use this to chain directly off a call that may return a nullish value,
+ * e.g. `const r = assertNotNullish(f(x))`. For a variable that already
+ * exists, prefer `assert(a !== null && a !== undefined)` instead.
+ *
+ * @type {<T>(a: T|null|undefined, msg?: unknown) => T}
+ */
+export const assertNotNullish = (a, msg) => {
+    assert(a !== null && a !== undefined, msg)
+    return a
+}

package/fjs/asserts/proof.f.d.mts

@@ -0,0 +1,14 @@
+export declare const proof: {
+    assertPassesOnTrue: () => void;
+    assertEqPassesOnEqual: () => void;
+    assertStructurallySamePassesOnSame: () => void;
+    throw: {
+        assertEqThrowsOnUnequal: () => void;
+        assertEqThrowsOnUnequal3: () => void;
+        assertStructurallySameThrowsOnDifferent: () => void;
+        assertStructurallySameThrowsOnDifferent3: () => void;
+        assertThrowsDefaultMsg: () => void;
+        assertThrowsCustomMsg: () => void;
+        todoThrows: () => never;
+    };
+};

package/fjs/asserts/proof.f.mjs

@@ -0,0 +1,33 @@
+import {
+    assert,
+    assertEq,
+    assertStructurallySame,
+    todo,
+} from './module.f.mjs'
+
+export const proof = {
+    assertPassesOnTrue: () => {
+        assert(true)
+        assert(true, 'with message')
+    },
+    assertEqPassesOnEqual: () => {
+        assertEq(1, 1)
+        assertEq('x', 'x')
+    },
+    assertStructurallySamePassesOnSame: () => {
+        // the case `assertEq` cannot do: two separately built values
+        assertStructurallySame({ a: 1, b: [2, { c: 3 }] }, { b: [2, { c: 3 }], a: 1 })
+        assertStructurallySame(1, 1, 'with message')
+    },
+    throw: {
+        assertEqThrowsOnUnequal: () => assertEq(1, 2),
+        assertEqThrowsOnUnequal3: () => assertEq(1, 2, "message"),
+        assertStructurallySameThrowsOnDifferent:
+            () => assertStructurallySame({ a: 1 }, { a: 2 }),
+        assertStructurallySameThrowsOnDifferent3:
+            () => assertStructurallySame({ a: 1 }, { a: 2 }, 'message'),
+        assertThrowsDefaultMsg: () => assert(false),
+        assertThrowsCustomMsg: () => assert(false, 'oops'),
+        todoThrows: () => todo(),
+    },
+}

package/fjs/asserts/types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Type-level assertion helpers.
+ *
+ * @module
+ */
+/**
+ * Compile-time-only check: a type resolves only if it is exactly `true`.
+ * Used to assert type-level properties without any runtime cost, e.g.
+ * `type _ = Assert<Equal<A, B>>`.
+ */
+export type Assert<T extends true> = T;

package/fjs/basen/base128/module.f.d.mts

@@ -0,0 +1,22 @@
+/**
+ * Base-128 encoding and decoding utilities over bit vectors.
+ *
+ * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ */
+import type { Vec } from '../../types/bit_vec/types.ts';
+/**
+ * Encodes a bigint into an MSB Base128 vector.
+ *
+ * @param {bigint} uint The bigint to encode.
+ * @returns {Vec} The encoded MSB Base128 vector.
+ */
+export declare const encode: (uint: bigint) => Vec;
+/**
+ * Decodes an MSB Base128 vector into a bigint.
+ *
+ * @param {Vec} v The MSB Base128 vector to decode.
+ * @returns {readonly[bigint, Vec]} A tuple containing the decoded bigint and the remaining vector.
+ */
+export declare const decode: (v: Vec) => readonly [bigint, Vec];

package/fjs/basen/base128/module.f.mjs

@@ -0,0 +1,51 @@
+/**
+ * Base-128 encoding and decoding utilities over bit vectors.
+ *
+ * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ */
+
+import { vec8, msb, empty } from '../../types/bit_vec/module.f.mjs'
+
+const { concat, popFront } = msb
+
+const pop8 = popFront(8n)
+
+/**
+ * Encodes a bigint into an MSB Base128 vector.
+ *
+ * @param {bigint} uint The bigint to encode.
+ * @returns {Vec} The encoded MSB Base128 vector.
+ */
+export const encode = uint => {
+    /** @type {Vec} */
+    let result = empty
+    while (true) {
+        const item = uint & 0x7Fn
+        const flag = result === empty ? 0n : 0x80n
+        result = concat(vec8(flag | item))(result)
+        uint >>= 7n
+        if (uint === 0n) {
+            return result
+        }
+    }
+}
+
+/**
+ * Decodes an MSB Base128 vector into a bigint.
+ *
+ * @param {Vec} v The MSB Base128 vector to decode.
+ * @returns {readonly[bigint, Vec]} A tuple containing the decoded bigint and the remaining vector.
+ */
+export const decode = v => {
+    let result = 0n
+    while (true) {
+        const [byte, rest] = pop8(v)
+        result = (result << 7n) | (byte & 0x7Fn)
+        if (byte < 0x80n) {
+            return [result, rest]
+        }
+        v = rest
+    }
+}

package/fjs/basen/base128/proof.f.d.mts

@@ -0,0 +1,4 @@
+/**
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ */
+export declare const proof: () => void;