functionalscript 0.44.0 → 0.45.0

package/fjs/ci/config/module.f.d.mts

@@ -18,7 +18,7 @@ export declare const images: {
         readonly arm: 'windows-11-arm';
     };
 };
-export declare const functionalscript = /** @type {const} */ "0.43.1";
+export declare const functionalscript = /** @type {const} */ "0.44.0";
 export declare const bun = "1.3.14";
 export declare const deno = "2.9.5";
 export declare const node: {
@@ -40,6 +40,6 @@ export declare const actions: {
     readonly 'oven-sh/setup-bun': 'v2.2.0';
     readonly 'bytecodealliance/actions/wasmtime/setup': 'v1.1.3';
     readonly 'wasmerio/setup-wasmer': 'v3.1';
-    readonly 'cachix/install-nix-action': 'v31.11.0';
+    readonly 'cachix/install-nix-action': 'v31.11.1';
     readonly 'dtolnay/rust-toolchain': '1.97.1';
 };

package/fjs/ci/config/module.f.mjs

@@ -25,7 +25,7 @@ export const images = /** @type {const} */({
 // published FunctionalScript release; do not tie it to package.json's current
 // in-repo version.
 // https://www.npmjs.com/package/functionalscript
-export const functionalscript = /** @type {const} */ '0.43.1'
+export const functionalscript = /** @type {const} */ '0.44.0'
 
 // https://bun.sh/
 export const bun = '1.3.14'
@@ -83,7 +83,7 @@ export const actions = /** @type {const} */({
     'wasmerio/setup-wasmer': 'v3.1',
     // https://github.com/marketplace/actions/install-nix
     // Enables the `nix-command` and `flakes` experimental features by default.
-    'cachix/install-nix-action': 'v31.11.0',
+    'cachix/install-nix-action': 'v31.11.1',
     // https://rust-lang.org/ - value is Rust version, not action version
     'dtolnay/rust-toolchain': '1.97.1',
 })

package/fjs/ci/nix/proof.f.d.mts

@@ -2,6 +2,8 @@
  * Proofs for generated CI flakes.
  *
  * @module
+ *
+ * @import { NixJob } from './types.ts'
  */
 export declare const proof: {
     flakeText: {

package/fjs/ci/nix/proof.f.mjs

@@ -2,10 +2,10 @@
  * Proofs for generated CI flakes.
  *
  * @module
+ *
+ * @import { NixJob } from './types.ts'
  */
 
-/** @import { NixJob } from './types.ts' */
-
 import { assert, assertEq } from '../../asserts/module.f.mjs'
 import { step } from '../../effects/module.f.mjs'
 import { readUtf8File } from '../../effects/node/module.f.mjs'

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

@@ -1,5 +1,7 @@
-/** @import { MetaStep, Os, GitHubAction } from './common/types.ts' */
-/** @import { Dir, State } from '../effects/node/virtual/types.ts' */
+/**
+ * @import { MetaStep, Os, GitHubAction } from './common/types.ts'
+ * @import { Dir, State } from '../effects/node/virtual/types.ts'
+ */
 export declare const proof: {
     matrixShape: () => void;
     rust: () => void;

package/fjs/ci/proof.f.mjs

@@ -1,5 +1,7 @@
-/** @import { MetaStep, Os, GitHubAction } from './common/types.ts' */
-/** @import { Dir, State } from '../effects/node/virtual/types.ts' */
+/**
+ * @import { MetaStep, Os, GitHubAction } from './common/types.ts'
+ * @import { Dir, State } from '../effects/node/virtual/types.ts'
+ */
 
 import { ci, main } from './module.f.mjs'
 import { functionalscript, node } from './config/module.f.mjs'
@@ -11,7 +13,6 @@ import { assert, assertEq } from '../asserts/module.f.mjs'
 import { emptyState, virtual } from '../effects/node/virtual/module.f.mjs'
 import { unwrap } from '../types/result/module.f.mjs'
 import { definedValues } from '../types/object/module.f.mjs'
-
 import { parse as jsonParse } from '../media/json/module.f.mjs'
 
 /** @type {(cmd: string) => (gha: GitHubAction) => boolean} */

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

@@ -1,5 +1,7 @@
-/** @import { NodeOp, NodeProgramOptions } from '../effects/node/types.ts' */
-/** @import { Commands } from './types.ts' */
+/**
+ * @import { NodeOp, NodeProgramOptions } from '../effects/node/types.ts'
+ * @import { Commands } from './types.ts'
+ */
 export declare const proof: {
     knownCommand: () => void;
     alias: () => void;

package/fjs/cli/proof.f.mjs

@@ -1,5 +1,7 @@
-/** @import { NodeOp, NodeProgramOptions } from '../effects/node/types.ts' */
-/** @import { Commands } from './types.ts' */
+/**
+ * @import { NodeOp, NodeProgramOptions } from '../effects/node/types.ts'
+ * @import { Commands } from './types.ts'
+ */
 
 import { pure } from '../effects/module.f.mjs'
 import { defaultNodeProgramOptions, emptyState, virtual } from '../effects/node/virtual/module.f.mjs'

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 (`AGENTS.md` §6.2).
+ */
+export type Absorbing<T> = {
+    readonly monoid: Monoid<T>;
+    readonly absorbing: T;
+};

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/proof.f.d.mts

@@ -1,4 +1,6 @@
-/** @import { Sha2 } from './types.ts' */
+/**
+ * @import { Sha2 } from './types.ts'
+ */
 export declare const proof: {
     base: {
         b32: () => {

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'