functionalscript 0.44.0 → 0.46.0

package/fjs/common/monoid/module.f.d.mts

@@ -2,17 +2,17 @@
  * Monoids: the `Monoid<T>` algebraic structure (identity plus associative
  * binary operation), `repeat`, which applies the operation `n` times using
  * exponentiation by squaring, and `fold`, which applies it across every element
- * of a list.
+ * of a list as a balanced binary tree.
  *
  * @module
  *
- * @import { Fold } from '../../types/function/operator/types.ts'
- * @import { List } from  '../../types/list/types.ts'
- * @import { Monoid } from './types.ts'
+ * @import { Fold, Reduce } from '../../types/function/operator/types.ts'
+ * @import { Accumulator, List } from  '../../types/list/types.ts'
+ * @import { Absorbing, Monoid } from './types.ts'
  */
 import type { Fold } from '../../types/function/operator/types.ts';
 import type { List } from '../../types/list/types.ts';
-import type { Monoid } from './types.ts';
+import type { Absorbing, Monoid } from './types.ts';
 /**
  * Repeats a monoid operation `n` times on the given element `a`.
  * This function efficiently performs the operation using exponentiation by squaring.
@@ -43,6 +43,12 @@ import type { Monoid } from './types.ts';
  * ```
  */
 export declare const repeat: <T>({ identity, operation }: Monoid<T>) => Fold<bigint, T>;
+export type _Run<T> = {
+    readonly size: number;
+    readonly value: T;
+    readonly rest: _Stack<T>;
+};
+export type _Stack<T> = _Run<T> | null;
 /**
  * Reduces a `List<T>` with the monoid's associative `operation`, seeded at its
  * `identity`. An empty list folds to `identity`.
@@ -54,12 +60,26 @@ export declare const repeat: <T>({ identity, operation }: Monoid<T>) => Fold<big
  * so the identity paired with each operation is stated once at the call site
  * instead of hand-seeding a raw `reduce`.
  *
- * Like `repeat`, `fold` applies the operation **accumulator-first**:
- * `operation(accumulator)(element)`, seeded at `identity`, so
- * `[a, b, c]` folds to `((identity op a) op b) op c`. Left-to-right order is
- * therefore preserved and `fold` is correct for non-commutative monoids (e.g.
- * string concatenation as `a => b => a + b`). `list.reduce` calls its reducer
- * element-first, so the operation is `flip`ped before it is handed over.
+ * The reduction is **balanced**, not a left fold: `[a, b, c, d]` folds to
+ * `(a op b) op (c op d)`, not `((a op b) op c) op d`. A `Monoid`'s
+ * associativity is what licenses the re-grouping — `list.reduce` takes an
+ * arbitrary operation with no such contract and therefore stays strictly
+ * left-to-right. Balancing matters for size-growing exact operations
+ * (`bigint.product`, `string`/`bit_vec` concatenation): a left fold grows the
+ * accumulator while every new operand stays small, so step *k* costs work
+ * proportional to *k* and the total is O(n²), while merging runs of comparable
+ * size costs O(n log n). It is the list-shaped sibling of {@link repeat}'s
+ * exponentiation by squaring.
+ *
+ * Only the grouping changes, never the order: each merge keeps the earlier
+ * operand on the left, so `fold` stays correct for non-commutative monoids
+ * (e.g. string concatenation as `a => b => a + b`).
+ *
+ * Re-grouping does move the rounding of an inexact operation. IEEE-754 addition
+ * is not truly associative, so `number.sum` returns a (marginally more
+ * accurate — O(log n · ε) instead of O(n · ε)) different value than a left fold
+ * for some inputs. That is a consequence of the uniform treatment, not a goal:
+ * a `Monoid` promises associativity, and every monoid folds the same way.
  *
  * @template T The type of the elements in the monoid.
  * @param {Monoid<T>} monoid The monoid structure, including the identity and binary operation.
@@ -84,4 +104,42 @@ export declare const repeat: <T>({ identity, operation }: Monoid<T>) => Fold<big
  * fold(concat)(['a', 'b', 'c']) // 'abc' — order preserved
  * ```
  */
-export declare const fold: <T>({ identity, operation }: Monoid<T>) => (list: List<T>) => T;
+export declare const fold: <T>(monoid: Monoid<T>) => (list: List<T>) => T;
+/**
+ * {@link fold} for a monoid with an absorbing element, stopping at the first
+ * element that reaches it.
+ *
+ * The result is the same as `fold`'s — combining `absorbing` with the rest of
+ * the list is `absorbing` again — but the rest of the list is never read. That
+ * is what makes it usable on an unbounded lazy `List`, where `fold` keeps
+ * pulling elements forever after the answer is already decided.
+ *
+ * It stops as soon as a **run** reaches `absorbing`: immediately when an element
+ * is absorbing on its own (`0` in a product), otherwise at the merge that first
+ * produces it. When only a combination is absorbing — `bit_vec`'s length cap —
+ * that merge can lag the element that actually decided the answer, because runs
+ * merge at power-of-two boundaries: at most one doubling, so under twice as many
+ * elements as a left fold's per-element check would read. Bounded either way,
+ * which is the property that matters against an unbounded list.
+ *
+ * Grouping, order, and the `log2(n)` stack bound are `fold`'s; only the walk
+ * gains an exit. `foldAbsorbing(a)(list)` and `fold(a.monoid)(list)` agree on
+ * every finite list, including one whose folded value is itself `null`.
+ *
+ * @template T The type of the elements in the monoid.
+ * @param {Absorbing<T>} absorbing The monoid together with its absorbing element.
+ * @returns {(list: List<T>) => T} A function that reduces a `List<T>` to a single `T`.
+ *
+ * @example
+ *
+ * ```ts
+ * const multiply: Absorbing<number> = {
+ *     monoid: { identity: 1, operation: a => b => a * b },
+ *     absorbing: 0,
+ * }
+ *
+ * foldAbsorbing(multiply)([2, 3, 4]) // 24
+ * foldAbsorbing(multiply)([2, 0, 4]) // 0 — `4` is never read
+ * ```
+ */
+export declare const foldAbsorbing: <T>({ monoid, absorbing }: Absorbing<T>) => (list: List<T>) => T;

package/fjs/common/monoid/module.f.mjs

@@ -2,17 +2,17 @@
  * Monoids: the `Monoid<T>` algebraic structure (identity plus associative
  * binary operation), `repeat`, which applies the operation `n` times using
  * exponentiation by squaring, and `fold`, which applies it across every element
- * of a list.
+ * of a list as a balanced binary tree.
  *
  * @module
  *
- * @import { Fold } from '../../types/function/operator/types.ts'
- * @import { List } from  '../../types/list/types.ts'
- * @import { Monoid } from './types.ts'
+ * @import { Fold, Reduce } from '../../types/function/operator/types.ts'
+ * @import { Accumulator, List } from  '../../types/list/types.ts'
+ * @import { Absorbing, Monoid } from './types.ts'
  */
 
-import { reduce } from '../../types/list/module.f.mjs'
-import { flip } from '../../types/function/module.f.mjs'
+import { fold as listFold, tryFold } from '../../types/list/module.f.mjs'
+import { compose } from '../../types/function/module.f.mjs'
 
 /**
  * Repeats a monoid operation `n` times on the given element `a`.
@@ -59,6 +59,72 @@ export const repeat = ({ identity, operation }) => n => a => {
     }
 }
 
+/**
+ * A run of `size` already-combined elements. Runs live on a stack whose top is
+ * the most recent — and smallest — run, so `rest` holds everything to the left
+ * of `value`.
+ *
+ * @template T
+ * @typedef {{
+ *  readonly size: number
+ *  readonly value: T
+ *  readonly rest: _Stack<T>
+ * }} _Run
+ */
+
+/**
+ * A stack of runs, `null` when empty.
+ *
+ * @template T
+ * @typedef {_Run<T> | null} _Stack
+ */
+
+/**
+ * Pushes a run of `size` combined elements onto the stack, merging while the
+ * top run has the same size — exactly the carry of incrementing a binary
+ * counter, so every merge joins two runs of equal size and the stack never
+ * holds more than `log2(n)` runs.
+ *
+ * The merge keeps the earlier run on the left (`operation(stack.value)(value)`),
+ * so re-associating never re-orders.
+ *
+ * The result is always a run, never the empty stack — which is what lets
+ * {@link absorbingAccumulator} read `null` as a stop signal rather than a state.
+ *
+ * @type {<T>(operation: Reduce<T>) => (size: number) => (value: T) => (stack: _Stack<T>) => _Run<T>}
+ */
+const push = operation => size => value => stack =>
+    stack === null || stack.size !== size
+        ? { size, value, rest: stack }
+        : push(operation)(size * 2)(operation(stack.value)(value))(stack.rest)
+
+/**
+ * `push` seeded for a single element — the step both {@link fold} and
+ * {@link absorbingAccumulator} walk a list with.
+ *
+ * @type {<T>(operation: Reduce<T>) => (value: T) => (stack: _Stack<T>) => _Run<T>}
+ */
+const step = operation => push(operation)(1)
+
+/**
+ * {@link step} seen as the {@link Fold} `list.fold` takes: the same function,
+ * with its result widened from a run to the stack `list.fold` threads.
+ *
+ * @type {<T>(operation: Reduce<T>) => Fold<T, _Stack<T>>}
+ */
+const foldStep = step
+
+/**
+ * Combines the stack's runs into one value, earliest (bottom, largest) first,
+ * seeded at `identity`.
+ *
+ * @type {<T>(monoid: Monoid<T>) => (stack: _Stack<T>) => T}
+ */
+const combine = monoid => stack =>
+    stack === null
+        ? monoid.identity
+        : monoid.operation(combine(monoid)(stack.rest))(stack.value)
+
 /**
  * Reduces a `List<T>` with the monoid's associative `operation`, seeded at its
  * `identity`. An empty list folds to `identity`.
@@ -70,12 +136,26 @@ export const repeat = ({ identity, operation }) => n => a => {
  * so the identity paired with each operation is stated once at the call site
  * instead of hand-seeding a raw `reduce`.
  *
- * Like `repeat`, `fold` applies the operation **accumulator-first**:
- * `operation(accumulator)(element)`, seeded at `identity`, so
- * `[a, b, c]` folds to `((identity op a) op b) op c`. Left-to-right order is
- * therefore preserved and `fold` is correct for non-commutative monoids (e.g.
- * string concatenation as `a => b => a + b`). `list.reduce` calls its reducer
- * element-first, so the operation is `flip`ped before it is handed over.
+ * The reduction is **balanced**, not a left fold: `[a, b, c, d]` folds to
+ * `(a op b) op (c op d)`, not `((a op b) op c) op d`. A `Monoid`'s
+ * associativity is what licenses the re-grouping — `list.reduce` takes an
+ * arbitrary operation with no such contract and therefore stays strictly
+ * left-to-right. Balancing matters for size-growing exact operations
+ * (`bigint.product`, `string`/`bit_vec` concatenation): a left fold grows the
+ * accumulator while every new operand stays small, so step *k* costs work
+ * proportional to *k* and the total is O(n²), while merging runs of comparable
+ * size costs O(n log n). It is the list-shaped sibling of {@link repeat}'s
+ * exponentiation by squaring.
+ *
+ * Only the grouping changes, never the order: each merge keeps the earlier
+ * operand on the left, so `fold` stays correct for non-commutative monoids
+ * (e.g. string concatenation as `a => b => a + b`).
+ *
+ * Re-grouping does move the rounding of an inexact operation. IEEE-754 addition
+ * is not truly associative, so `number.sum` returns a (marginally more
+ * accurate — O(log n · ε) instead of O(n · ε)) different value than a left fold
+ * for some inputs. That is a consequence of the uniform treatment, not a goal:
+ * a `Monoid` promises associativity, and every monoid folds the same way.
  *
  * @template T The type of the elements in the monoid.
  * @param {Monoid<T>} monoid The monoid structure, including the identity and binary operation.
@@ -100,5 +180,88 @@ export const repeat = ({ identity, operation }) => n => a => {
  * fold(concat)(['a', 'b', 'c']) // 'abc' — order preserved
  * ```
  */
-export const fold = ({ identity, operation }) =>
-    reduce(flip(operation))(identity)
+export const fold = monoid =>
+    compose(listFold(foldStep(monoid.operation))(null))(combine(monoid))
+
+/**
+ * The run stack as a short-circuiting {@link Accumulator}: `update` returns
+ * `null` — `tryFold`'s stop signal — as soon as a merge produces the absorbing
+ * element.
+ *
+ * Only the newest run can be `absorbing`: an earlier one would have stopped the
+ * walk already.
+ *
+ * `end` wraps the folded value in a one-element tuple because `tryFold` reports
+ * both "stopped" and "finished with this result" through the same
+ * `Nullable<R>`: a monoid whose `T` includes `null` would otherwise be unable to
+ * tell a completed fold that produced `null` from an abandoned walk. The tuple
+ * costs one allocation per fold, not per element.
+ */
+const absorbingAccumulator =
+    /**
+     * @template T
+     * @param {Monoid<T>} monoid
+     */
+    monoid => {
+        const p = step(monoid.operation)
+        const c = combine(monoid)
+        /**
+         * @param {T} absorbing
+         * @returns {Accumulator<T, _Stack<T>, readonly[T]>}
+         */
+        return absorbing => ({
+            init: null,
+            update: (value, stack) => {
+                const next = p(value)(stack)
+                return next.value === absorbing ? null : next
+            },
+            end: stack => [c(stack)],
+        })
+    }
+
+/**
+ * {@link fold} for a monoid with an absorbing element, stopping at the first
+ * element that reaches it.
+ *
+ * The result is the same as `fold`'s — combining `absorbing` with the rest of
+ * the list is `absorbing` again — but the rest of the list is never read. That
+ * is what makes it usable on an unbounded lazy `List`, where `fold` keeps
+ * pulling elements forever after the answer is already decided.
+ *
+ * It stops as soon as a **run** reaches `absorbing`: immediately when an element
+ * is absorbing on its own (`0` in a product), otherwise at the merge that first
+ * produces it. When only a combination is absorbing — `bit_vec`'s length cap —
+ * that merge can lag the element that actually decided the answer, because runs
+ * merge at power-of-two boundaries: at most one doubling, so under twice as many
+ * elements as a left fold's per-element check would read. Bounded either way,
+ * which is the property that matters against an unbounded list.
+ *
+ * Grouping, order, and the `log2(n)` stack bound are `fold`'s; only the walk
+ * gains an exit. `foldAbsorbing(a)(list)` and `fold(a.monoid)(list)` agree on
+ * every finite list, including one whose folded value is itself `null`.
+ *
+ * @template T The type of the elements in the monoid.
+ * @param {Absorbing<T>} absorbing The monoid together with its absorbing element.
+ * @returns {(list: List<T>) => T} A function that reduces a `List<T>` to a single `T`.
+ *
+ * @example
+ *
+ * ```ts
+ * const multiply: Absorbing<number> = {
+ *     monoid: { identity: 1, operation: a => b => a * b },
+ *     absorbing: 0,
+ * }
+ *
+ * foldAbsorbing(multiply)([2, 3, 4]) // 24
+ * foldAbsorbing(multiply)([2, 0, 4]) // 0 — `4` is never read
+ * ```
+ */
+export const foldAbsorbing = ({ monoid, absorbing }) => {
+    const f = tryFold(absorbingAccumulator(monoid)(absorbing))
+    return list => {
+        const result = f(list)
+        if (result === null) { return absorbing }
+        const [value] = result
+        return value
+    }
+}

package/fjs/common/monoid/proof.f.d.mts

@@ -1,4 +1,8 @@
-/** @import { Monoid } from './types.ts' */
+/**
+ * @import { List } from '../../types/list/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Absorbing, Monoid } from './types.ts'
+ */
 export declare const proof: {
     numberAdd: () => void;
     stringConcat: () => void;
@@ -6,5 +10,12 @@ export declare const proof: {
         nonEmpty: () => void;
         order: () => void;
         empty: () => void;
+        balanced: () => void;
+    };
+    foldAbsorbing: {
+        plain: () => void;
+        absorbed: () => void;
+        nullValued: () => void;
+        stopsEarly: () => void;
     };
 };

package/fjs/common/monoid/proof.f.mjs

@@ -1,7 +1,20 @@
-/** @import { Monoid } from './types.ts' */
+/**
+ * @import { List } from '../../types/list/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Absorbing, Monoid } from './types.ts'
+ */
 
-import { repeat, fold } from './module.f.mjs'
-import { assertEq } from '../../asserts/module.f.mjs'
+import { repeat, fold, foldAbsorbing } from './module.f.mjs'
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+
+/** @type {Absorbing<number>} */
+const multiply = {
+    monoid: {
+        identity: 1,
+        operation: a => b => a * b,
+    },
+    absorbing: 0,
+}
 
 export const proof = {
     numberAdd: () => {
@@ -54,5 +67,76 @@ export const proof = {
             // an empty list folds to the identity
             assertEq(fold(concat)([]), '')
         },
-    }
+        balanced: () => {
+            // `operation` brackets each combination so the *grouping* `fold`
+            // chose is visible in the result. It is deliberately **not**
+            // associative — a lawful monoid could not observe the grouping at
+            // all, which is exactly why re-associating is allowed. The identity
+            // still behaves as one (both branches return the other operand
+            // unchanged), so `fold`'s contract is respected.
+            /** @type {Monoid<string>} */
+            const bracket = {
+                identity: '',
+                operation: a => b => a === '' ? b : b === '' ? a : `(${a}${b})`,
+            }
+            const f = fold(bracket)
+            assertEq(f(['a']), 'a')
+            assertEq(f(['a', 'b']), '(ab)')
+            // three elements keep the trailing run separate: `c` merges with
+            // nothing, so it combines against `(ab)` only at the end.
+            assertEq(f(['a', 'b', 'c']), '((ab)c)')
+            // four is where balancing separates from a left fold, which would
+            // give `(((ab)c)d)`.
+            assertEq(f(['a', 'b', 'c', 'd']), '((ab)(cd))')
+            assertEq(f(['a', 'b', 'c', 'd', 'e']), '(((ab)(cd))e)')
+        },
+    },
+    foldAbsorbing: {
+        plain: () => {
+            // with no absorbing element in the list, it is `fold`
+            assertEq(foldAbsorbing(multiply)([2, 3, 4]), 24)
+            assertEq(foldAbsorbing(multiply)([]), 1)
+            assertEq(foldAbsorbing(multiply)([2, 3, 4]), fold(multiply.monoid)([2, 3, 4]))
+        },
+        absorbed: () => {
+            assertEq(foldAbsorbing(multiply)([2, 0, 4]), 0)
+        },
+        nullValued: () => {
+            // `min` over non-negative numbers, where `null` is the identity
+            // (+infinity) and `0` is the absorbing element. `T` therefore
+            // includes `null` without `null` being the stop condition — and
+            // `tryFold` signals "stopped" and "finished" through one
+            // `Nullable`, so a completed fold whose value is `null` must not be
+            // read as an abandoned walk.
+            /** @type {Absorbing<Nullable<number>>} */
+            const min = {
+                monoid: {
+                    identity: null,
+                    operation: a => b =>
+                        a === null ? b : b === null ? a : a <= b ? a : b,
+                },
+                absorbing: 0,
+            }
+            assertEq(foldAbsorbing(min)([]), null)
+            assertEq(foldAbsorbing(min)([3, null, 5]), 3)
+            assertEq(foldAbsorbing(min)([3, 0, 5]), 0)
+        },
+        stopsEarly: () => {
+            // `List` includes `Thunk`, so this list is unbounded: `fold` would
+            // pull from it forever. The elements past the absorbing one assert
+            // that they are never read.
+            /** @type {(n: number) => List<number>} */
+            const rest = n => () => {
+                assert(false)
+                return { first: n, tail: rest(n + 1) }
+            }
+            // `0` is absorbing on its own, so the walk stops at the element
+            // itself...
+            assertEq(foldAbsorbing(multiply)({ first: 0, tail: rest(1) }), 0)
+            // ...and here only the merge of `2` and `0` reaches it.
+            assertEq(
+                foldAbsorbing(multiply)({ first: 2, tail: { first: 0, tail: rest(1) } }),
+                0)
+        },
+    },
 }

package/fjs/common/monoid/types.d.ts

@@ -48,3 +48,26 @@ export type Monoid<T> = {
     readonly identity: T;
     readonly operation: Reduce<T>;
 };
+/**
+ * A monoid that additionally has an
+ * {@link https://en.wikipedia.org/wiki/Absorbing_element absorbing element}
+ * (also called a zero or annihilator): a value that swallows the operation
+ * from either side.
+ *
+ * For all `a`: `operation(absorbing)(a) = operation(a)(absorbing) = absorbing`.
+ *
+ * Once a fold reaches `absorbing`, the result is decided — every remaining
+ * element combines to `absorbing` again — so `foldAbsorbing` may stop reading
+ * the list there instead of walking to its end. That is the difference between
+ * answering and not returning at all when the list is an unbounded `Thunk`.
+ *
+ * Multiplication over numbers has `0`; `bit_vec`'s length-capped concatenation
+ * has `null`, meaning "longer than `maxLength`".
+ *
+ * The monoid is carried as a field rather than intersected in, so it stays
+ * independently constructed and consumed (`fjs/AGENTS.md` §3.2).
+ */
+export type Absorbing<T> = {
+    readonly monoid: Monoid<T>;
+    readonly absorbing: T;
+};

package/fjs/crypto/hmac/module.f.mjs

@@ -44,8 +44,8 @@ const iPad = vec8(0x36n)
  * that takes a message and computes the HMAC.
  */
 export const hmac = hashFunc => {
-    const { blockLength } = hashFunc
-    const p = repeat(blockLength >> 3n)
+    const { blockLength, blockBytes } = hashFunc
+    const p = repeat(blockBytes)
     const ip = p(iPad)
     const op = p(oPad)
     const c = computeSync(hashFunc)

package/fjs/crypto/secp/proof.f.d.mts

@@ -1,4 +1,6 @@
-/** @import { Point, Curve, Init } from './types.ts' */
+/**
+ * @import { Point, Curve, Init } from './types.ts'
+ */
 export declare const proof: {
     example: () => void;
     test: () => void;

package/fjs/crypto/secp/proof.f.mjs

@@ -1,4 +1,6 @@
-/** @import { Point, Curve, Init } from './types.ts' */
+/**
+ * @import { Point, Curve, Init } from './types.ts'
+ */
 
 import { assert, assertEq, assertNotNullish } from '../../asserts/module.f.mjs'
 import { prime_field } from '../../types/prime_field/module.f.mjs'

package/fjs/crypto/sha2/module.f.mjs

@@ -11,7 +11,7 @@
  * @import { Base, Sha2, State, V16, V8 } from './types.ts'
  */
 
-import { mask } from '../../types/bigint/module.f.mjs'
+import { divUp8, mask } from '../../types/bigint/module.f.mjs'
 import {
     vec,
     length,
@@ -257,6 +257,8 @@ const base = ({ logBitLen, k, bs0, bs1, ss0, ss1 }) => {
 const sha2 = ({ append, end, chunkLength }, hash, hashLength) => ({
     hashLength,
     blockLength: chunkLength,
+    hashBytes: divUp8(hashLength),
+    blockBytes: divUp8(chunkLength),
     init: {
         hash,
         len: 0n,

package/fjs/crypto/sha2/proof.f.d.mts

@@ -1,4 +1,6 @@
-/** @import { Sha2 } from './types.ts' */
+/**
+ * @import { Sha2 } from './types.ts'
+ */
 export declare const proof: {
     base: {
         b32: () => {
@@ -20,6 +22,7 @@ export declare const proof: {
         sha512x256: () => void;
         sha512x224: () => void;
     };
+    byteLengths: (() => void)[];
     utf8: (() => void)[];
     fill: () => {
         8: () => void;

package/fjs/crypto/sha2/proof.f.mjs

@@ -1,4 +1,6 @@
-/** @import { Sha2 } from './types.ts' */
+/**
+ * @import { Sha2 } from './types.ts'
+ */
 
 import { utf8 } from '../../text/module.f.mjs'
 import { repeat, uint, vec } from '../../types/bit_vec/module.f.mjs'
@@ -7,6 +9,19 @@ import { assertEq } from '../../asserts/module.f.mjs'
 import { map } from '../../types/list/module.f.mjs'
 import { base32, base64, computeSync, sha224, sha256, sha384, sha512, sha512x224, sha512x256 } from './module.f.mjs'
 
+/**
+ * Every SHA-2 length is a whole number of bytes, so the rounded-up byte count
+ * and the exact division agree — this pins both that identity and the values.
+ *
+ * @type {(sha2: Sha2) => (hashBytes: bigint, blockBytes: bigint) => void}
+ */
+const checkBytes = ({ hashLength, blockLength, hashBytes, blockBytes }) => (h, b) => {
+    assertEq(hashBytes, h)
+    assertEq(blockBytes, b)
+    assertEq(hashBytes, hashLength >> 3n)
+    assertEq(blockBytes, blockLength >> 3n)
+}
+
 /** @type {(sha2: Sha2) => (x: bigint) => void} */
 const checkEmpty = ({ init, end, hashLength }) => x => {
     const result = end(init)
@@ -69,6 +84,17 @@ export const proof = {
         sha512x256: () => checkEmpty(sha512x256)(0xc672b8d1ef56ed28ab87c3622c5114069bdd3ad7b8f9737498d0c01ecef0967an),
         sha512x224: () => checkEmpty(sha512x224)(0x6ed0dd02806fa89e25de060c19d3ac86cabb87d6a0ddd05c333b84f4n),
     },
+    // The byte counts consumers read instead of converting bit lengths
+    // themselves. Asserted against the bit length each is derived from, not
+    // against a hand-written number, so the pairing is what is pinned.
+    byteLengths: [
+        () => checkBytes(sha224)(28n, 64n),
+        () => checkBytes(sha256)(32n, 64n),
+        () => checkBytes(sha384)(48n, 128n),
+        () => checkBytes(sha512)(64n, 128n),
+        () => checkBytes(sha512x224)(28n, 128n),
+        () => checkBytes(sha512x256)(32n, 128n),
+    ],
     utf8: [
         () => {
             const e = 0x730e109bd7a8a32b1cb9d9a09aa2325d2430587ddbc0c38bad911525n

package/fjs/crypto/sha2/types.d.ts

@@ -51,6 +51,17 @@ export type Base = {
 export type Sha2 = {
     readonly hashLength: bigint;
     readonly blockLength: bigint;
+    /**
+     * `hashLength` and `blockLength` in whole bytes, rounded up. Consumers
+     * that size a byte buffer read these instead of converting: `hmac` and
+     * `sign` each used to do it themselves, with two different spellings
+     * (`>> 3n` and `divUp8`), leaving a reader to work out per site whether
+     * the two roundings agree. They do for every SHA-2 variant, whose lengths
+     * are byte multiples — which is exactly why the decision belongs here
+     * once rather than at each call site.
+     */
+    readonly hashBytes: bigint;
+    readonly blockBytes: bigint;
     readonly init: State;
     readonly append: Fold<Vec, State>;
     readonly end: (state: State) => Vec;

package/fjs/crypto/sign/module.f.mjs

@@ -12,7 +12,7 @@
  */
 
 import { assertNotNullish } from '../../asserts/module.f.mjs'
-import { bitLength, divUp8, roundUp8 } from '../../types/bigint/module.f.mjs'
+import { bitLength, roundUp8 } from '../../types/bigint/module.f.mjs'
 import { empty, length, msb, repeat, unpack, vec, vec8 } from '../../types/bit_vec/module.f.mjs'
 import { hmac } from '../hmac/module.f.mjs'
 import { computeSync } from '../sha2/module.f.mjs'
@@ -75,7 +75,7 @@ export const computeK =
         //    step and all subsequent steps, we use the same H function as the
         //    one used in step 'a' to process the input message; this choice
         //    will be discussed in more detail in Section 3.6.
-        const rep = repeat(divUp8(hf.hashLength))
+        const rep = repeat(hf.hashBytes)
         const v0 = rep(x01)
         // c. Set:
         //      K = 0x00 0x00 0x00 ... 0x00

package/fjs/crypto/vdf/module.f.d.mts

@@ -1,8 +1,27 @@
+/**
+ * Sloth verifiable delay function over a fixed 3072-bit safe prime.
+ *
+ * See `./types.ts` for the `Sloth` type-level API.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```js
+ * import { sloth } from './module.f.mjs'
+ *
+ * const steps = 4n
+ * const x = 42n
+ * const y = sloth.eval(steps)(x)
+ * if (y === null || !sloth.verify(steps)(x)(y)) { throw y }
+ * ```
+ *
+ * @import { PrimeField } from '../../types/prime_field/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Unary } from '../../types/bigint/types.ts'
+ * @import { Sloth } from './types.ts'
+ */
 import type { Sloth } from './types.ts';
-/** @import { PrimeField } from '../../types/prime_field/types.ts' */
-/** @import { Nullable } from '../../types/nullable/types.ts' */
-/** @import { Unary } from '../../types/bigint/types.ts' */
-/** @import { Sloth } from './types.ts' */
 /** Sloth VDF modulus (3072-bit safe prime, same as reference implementations). */
 export declare const p = 170082004324204494273811327264862981553264701145937538369570764779791492622392118654022654452947093285873855529044371650895045691292912712699015605832276411308653107069798639938826015099738961427172366594187783204437869906954750443653318078358839409699824714551430573905637228307966826784684174483831608534979n;
 /**