functionalscript 0.43.1 → 0.45.0

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

@@ -0,0 +1,267 @@
+/**
+ * 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 as a balanced binary tree.
+ *
+ * @module
+ *
+ * @import { Fold, Reduce } from '../../types/function/operator/types.ts'
+ * @import { Accumulator, List } from  '../../types/list/types.ts'
+ * @import { Absorbing, Monoid } from './types.ts'
+ */
+
+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`.
+ * This function efficiently performs the operation using exponentiation by squaring.
+ *
+ * @template T The type of the elements in the monoid.
+ * @param {Monoid<T>} monoid The monoid structure, including the identity and binary operation.
+ * @returns {Fold<bigint, T>} A function that takes an element `a` and a repetition count `n`,
+ * and returns the result of applying the operation `n` times.
+ *
+ * See also {@link https://en.wikipedia.org/wiki/Exponentiation_by_squaring}.
+ *
+ * @example
+ *
+ * ```ts
+ * const add: Monoid<number> = {
+ *     identity: 0,
+ *     operation: a => b => a + b,
+ * };
+ *
+ * const resultAdd = repeat(add)(10n)(2) // 20
+ *
+ * const concat: Monoid<string> = {
+ *     identity: '',
+ *     operation: a => b => a + b,
+ * };
+ *
+ * const resultConcat = repeat(concat)(3n)('ha') // 'hahaha'
+ * ```
+ */
+export const repeat = ({ identity, operation }) => n => a => {
+    let ai = a
+    let ni = n
+    let result = identity
+    while (true) {
+        if ((ni & 1n) !== 0n) {
+            result = operation(result)(ai)
+        }
+        ni >>= 1n
+        if (ni === 0n) {
+            return result
+        }
+        ai = operation(ai)(ai)
+    }
+}
+
+/**
+ * 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`.
+ *
+ * `fold` is the reduction companion of {@link repeat}: where `repeat` applies
+ * the operation a fixed number of times to a single element, `fold` applies it
+ * across every element of a list. Together they let list reductions such as
+ * `sum`, `product`, and string `concat` be expressed directly as monoid folds,
+ * so the identity paired with each operation is stated once at the call site
+ * instead of hand-seeding a raw `reduce`.
+ *
+ * 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.
+ * @returns {(list: List<T>) => T} A function that reduces a `List<T>` to a single `T`.
+ *
+ * @example
+ *
+ * ```ts
+ * const add: Monoid<number> = {
+ *     identity: 0,
+ *     operation: a => b => a + b,
+ * };
+ *
+ * fold(add)([1, 2, 3, 4]) // 10
+ * fold(add)([])           // 0
+ *
+ * const concat: Monoid<string> = {
+ *     identity: '',
+ *     operation: a => b => a + b,
+ * };
+ *
+ * fold(concat)(['a', 'b', 'c']) // 'abc' — order preserved
+ * ```
+ */
+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

@@ -0,0 +1,21 @@
+/**
+ * @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;
+    fold: {
+        nonEmpty: () => void;
+        order: () => void;
+        empty: () => void;
+        balanced: () => void;
+    };
+    foldAbsorbing: {
+        plain: () => void;
+        absorbed: () => void;
+        nullValued: () => void;
+        stopsEarly: () => void;
+    };
+};

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

@@ -0,0 +1,142 @@
+/**
+ * @import { List } from '../../types/list/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Absorbing, Monoid } from './types.ts'
+ */
+
+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: () => {
+        /** @type {Monoid<number>} */
+        const add = {
+             identity: 0,
+             operation: a => b => a + b,
+        };
+        const resultAdd = repeat(add)(10n)(2) // 20
+        assertEq(resultAdd, 20)
+
+        const id = repeat(add)(0n)(42)
+        assertEq(id, 0)
+    },
+    stringConcat: () => {
+        /** @type {Monoid<string>} */
+        const concat = {
+             identity: '',
+             operation: a => b => a + b,
+        };
+
+        const resultConcat = repeat(concat)(3n)('ha') // 'hahaha'
+        assertEq(resultConcat, 'hahaha')
+    },
+    fold: {
+        nonEmpty: () => {
+            /** @type {Monoid<number>} */
+            const add = {
+                identity: 0,
+                operation: a => b => a + b,
+            };
+            assertEq(fold(add)([1, 2, 3, 4]), 10)
+        },
+        order: () => {
+            // a non-commutative monoid: `fold` must preserve left-to-right order
+            // (`((('' + 'a') + 'b') + 'c')`), not reverse it to `'cba'`.
+            /** @type {Monoid<string>} */
+            const concat = {
+                identity: '',
+                operation: a => b => a + b,
+            };
+            assertEq(fold(concat)(['a', 'b', 'c']), 'abc')
+        },
+        empty: () => {
+            /** @type {Monoid<string>} */
+            const concat = {
+                identity: '',
+                operation: a => b => a + b,
+            };
+            // 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

@@ -0,0 +1,73 @@
+/**
+ * The `Monoid<T>` algebraic structure.
+ *
+ * @module
+ */
+import type { Reduce } from '../../types/function/operator/types.ts';
+/**
+ * Represents a monoid, an algebraic structure with a binary operation
+ * and an identity (neutral) element.
+ *
+ * A monoid satisfies the following properties:
+ * 1. **Associativity**: The operation must be associative.
+ *    For all `a`, `b`, and `c` in the set, `(a operation b) operation c = a operation (b operation c)`.
+ *    {@link https://en.wikipedia.org/wiki/Associative_property Learn more about associativity}.
+ * 2. **Identity Element**: There exists an element (called the identity) such that,
+ *    when combined with any other element under the operation, it leaves the other element unchanged.
+ *    {@link https://en.wikipedia.org/wiki/Identity_element Learn more about identity elements}.
+ *
+ * Learn more about monoids: {@link https://en.wikipedia.org/wiki/Monoid}.
+ *
+ * @property identity
+ *
+ * The identity (neutral) element for the monoid.
+ * When combined with any value under the `operation`, it leaves the other value unchanged.
+ *
+ * Examples:
+ * - `0` for addition
+ * - `1` for multiplication
+ * - `""` for string concatenation
+ * - `[]` for array concatenation
+ *
+ * Learn more: {@link https://en.wikipedia.org/wiki/Identity_element}
+ *
+ * @property operation
+ *
+ * The associative binary operation of the monoid.
+ * Takes one value of type `T` and returns a function that takes another value of type `T`,
+ * producing a result of type `T`.
+ *
+ * Examples:
+ * - `(a, b) => a + b` for addition
+ * - `(a, b) => a * b` for multiplication
+ * - `(a, b) => a.concat(b)` for arrays or strings
+ *
+ * Learn more: {@link https://en.wikipedia.org/wiki/Binary_operation}
+ */
+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 (`AGENTS.md` §6.2).
+ */
+export type Absorbing<T> = {
+    readonly monoid: Monoid<T>;
+    readonly absorbing: T;
+};

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

@@ -0,0 +1,32 @@
+/**
+ * Provides an implementation of HMAC (Hash-based Message Authentication Code).
+ *
+ * https://en.wikipedia.org/wiki/HMAC
+ * https://www.rfc-editor.org/rfc/rfc2104
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```ts
+ * import { vec } from '../../types/bit_vec/module.f.mjs'
+ * import { msbUtf8 } from '../../text/module.f.mjs'
+ * import { sha256 } from '../sha2/module.f.mjs'
+ *
+ * const r = hmac(sha256)(msbUtf8('key'))(msbUtf8('The quick brown fox jumps over the lazy dog'))
+ * if (r !== vec(256n)(0xf7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8n)) { throw r }
+ * ```
+ *
+ * @import { Vec, Reduce } from '../../types/bit_vec/types.ts'
+ * @import { Sha2 } from '../sha2/types.ts'
+ */
+import type { Reduce } from '../../types/bit_vec/types.ts';
+import type { Sha2 } from '../sha2/types.ts';
+/**
+ * Generates an HMAC (Hash-based Message Authentication Code) using the specified hash function.
+ *
+ * @param {Sha2} hashFunc - The hash function implementation to use.
+ * @returns {Reduce} A function that takes a key and returns another function
+ * that takes a message and computes the HMAC.
+ */
+export declare const hmac: (hashFunc: Sha2) => Reduce;

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

@@ -0,0 +1,65 @@
+/**
+ * Provides an implementation of HMAC (Hash-based Message Authentication Code).
+ *
+ * https://en.wikipedia.org/wiki/HMAC
+ * https://www.rfc-editor.org/rfc/rfc2104
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```ts
+ * import { vec } from '../../types/bit_vec/module.f.mjs'
+ * import { msbUtf8 } from '../../text/module.f.mjs'
+ * import { sha256 } from '../sha2/module.f.mjs'
+ *
+ * const r = hmac(sha256)(msbUtf8('key'))(msbUtf8('The quick brown fox jumps over the lazy dog'))
+ * if (r !== vec(256n)(0xf7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8n)) { throw r }
+ * ```
+ *
+ * @import { Vec, Reduce } from '../../types/bit_vec/types.ts'
+ * @import { Sha2 } from '../sha2/types.ts'
+ */
+
+import { length, msb, vec, vec8, repeat } from '../../types/bit_vec/module.f.mjs'
+import { computeSync } from '../sha2/module.f.mjs'
+
+const { concat, xor } = msb
+
+/**
+ * Outer padding.
+ */
+const oPad = vec8(0x5cn)
+
+/**
+ * Inner padding.
+ */
+const iPad = vec8(0x36n)
+
+/**
+ * Generates an HMAC (Hash-based Message Authentication Code) using the specified hash function.
+ *
+ * @param {Sha2} hashFunc - The hash function implementation to use.
+ * @returns {Reduce} A function that takes a key and returns another function
+ * that takes a message and computes the HMAC.
+ */
+export const hmac = hashFunc => {
+    const { blockLength } = hashFunc
+    const p = repeat(blockLength >> 3n)
+    const ip = p(iPad)
+    const op = p(oPad)
+    const c = computeSync(hashFunc)
+    return k => {
+        const k1 = length(k) > blockLength ? c([k]) : k
+        const k2 = concat(k1)(vec(blockLength - length(k1))(0n))
+        const xk2 = xor(k2)
+        /** @type {(p: Vec) => (msg: Vec) => Vec} */
+        const f = p => {
+            const x = xk2(p)
+            return msg => c([x, msg])
+        }
+        const fip = f(ip)
+        const fop = f(op)
+        return m => fop(fip(m))
+    }
+}

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

@@ -0,0 +1,34 @@
+import { assertEq } from '../../asserts/module.f.mjs'
+import { utf8 } from '../../text/module.f.mjs'
+import { uint, vec } from '../../types/bit_vec/module.f.mjs'
+import { sha256, sha384, sha512 } from '../sha2/module.f.mjs'
+import { hmac } from './module.f.mjs'
+
+export const proof = {
+    example: () => {
+        const r = hmac(sha256)(utf8('key'))(utf8('The quick brown fox jumps over the lazy dog'))
+        assertEq(r, vec(256n)(0xf7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8n))
+    },
+    sha256: () => {
+        const r = hmac(sha256)(utf8('key'))(utf8('The quick brown fox jumps over the lazy dog'))
+        assertEq(uint(r), 0xf7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8n, r)
+    },
+    sha384: () => {
+        const k = vec(384n)(0n)
+        const m = vec(904n)(
+             0x0101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010069c7548c21d0dfea6b9a51c9ead4e27c33d3b3f180316e5bcab92c933f0e4dbc9a9083505bc92276aec4be312696ef7bf3bf603f4bbd381196a029f340585312n)
+        const r = hmac(sha384)(k)(m)
+        assertEq(r, vec(384n)(0x8F858157CE005CD52FD8E8F1A46B55E6CFAE21C8C183D9C2F7504BEDF450609EDD7D3C6171DC0BDD2D2444FAA28F18BAn), uint(r).toString(16))
+    },
+    sha512: () => {
+        const r = hmac(sha512)(utf8('key'))(utf8('The quick brown fox jumps over the lazy dog'))
+        assertEq(r, vec(512n)(0xb42af09057bac1e2d41708e48a902e09b5ff7f12ab428a4fe86653c73dd248fb82f948a549f7b791a5b41915ee4d1ec3935357e4e2317250d0372afa2ebeeb3an))
+    },
+    // RFC 4231 Test Case 6: key (131 bytes of 0xaa = 1048 bits) exceeds SHA-256 block size (512 bits),
+    // so the key is first compressed via the hash function before use.
+    longKey: () => {
+        const key = vec(1048n)(BigInt('0x' + 'aa'.repeat(131)))
+        const r = hmac(sha256)(key)(utf8('Test Using Larger Than Block-Size Key - Hash Key First'))
+        assertEq(uint(r), 0x60e431591ee0b67f0d8a26aacbf5b77f8e0bc6213728c5140546040f0ee37f54n)
+    }
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Bitcoin-style proof-of-work: compact **nBits** target decoding and
+ * hash-vs-target verification using an injected SHA-2 hash.
+ *
+ * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Sha2 } from '../sha2/types.ts'
+ * @import { Pow } from './types.ts'
+ */
+import type { Nullable } from '../../types/nullable/types.ts';
+import type { Sha2 } from '../sha2/types.ts';
+import type { Pow } from './types.ts';
+/** Genesis-block compact target (`0x1d00ffff`). */
+export declare const genesisNBits = 486604799n;
+/** Genesis-block uint256 target decoded from {@link genesisNBits}. */
+export declare const genesisTarget = 26959535291011309493156476344723991336010898738574164086137773096960n;
+/**
+ * Decodes compact **nBits** (32-bit block-header "bits") to a uint256 target:
+ *
+ * - `exponent = nBits >> 24`
+ * - `mantissa = nBits & 0xffffff`
+ * - `target = mantissa × 2^(8 × (exponent − 3))`
+ *
+ * Returns `null` for malformed encodings per Bitcoin `SetCompact` rules (negative
+ * sign bit, overflow, target wider than 256 bits).
+ *
+ * @param {bigint} nBits Compact target encoding.
+ * @returns {Nullable<bigint>} Decoded target, or `null` when **nBits** is invalid.
+ */
+export declare const targetFromNBits: (nBits: bigint) => Nullable<bigint>;
+/**
+ * Builds PoW helpers for a hash function (typical consumer: {@link sha256}).
+ *
+ * @param {Sha2} hash SHA-2 configuration whose digest is compared as uint256.
+ * @returns {Pow}
+ */
+export declare const pow: (hash: Sha2) => Pow;
+/** SHA-256 proof-of-work (`pow(sha256)`). */
+export declare const sha256Pow: Pow;
+/** Bitcoin block-header PoW; same as {@link sha256Pow}. */
+export declare const bitcoinPow: Pow;