functionalscript 0.38.0 → 0.40.0

package/fjs/protocol/mcp/proof.f.js

@@ -0,0 +1,208 @@
+import { assert, assertEq } from '../../asserts/module.f.js';
+import { pure, step } from '../../effects/module.f.js';
+import { eff } from '../../effects/eff/module.f.js';
+import { run } from '../../effects/mock/module.f.js';
+import { asBase, asNominal, create, read } from '../../effects/memory/module.f.js';
+import { uninitializedState, mcpStep, notInitialized, } from './module.f.js';
+const initial = { next: 0, values: {} };
+const mock = {
+    memCreate: value => state => {
+        const id = `k${state.next}`;
+        const key = asNominal(id);
+        return [{ next: state.next + 1, values: { ...state.values, [id]: value } }, key];
+    },
+    memRead: key => state => [state, state.values[asBase(key)]],
+    memWrite: (key, value) => state => {
+        const id = asBase(key);
+        return [{ ...state, values: { ...state.values, [id]: value } }, undefined];
+    },
+};
+// ── Fixtures ──────────────────────────────────────────────────────────────────
+const config = {
+    serverInfo: { name: 'test-server', version: '0.1.0' },
+    capabilities: { tools: {} },
+    protocolVersion: '2024-11-05',
+};
+const configNoTools = { ...config, capabilities: {} };
+const handlers = {
+    // Echoes a received cursor as `nextCursor` so tests can observe pagination params.
+    toolsList: (p) => pure(p.cursor === undefined
+        ? { tools: [{ name: 'greet', inputSchema: {} }] }
+        : { tools: [], nextCursor: p.cursor }),
+    toolsCall: (_p) => pure({ content: [{ type: 'text', text: 'hello' }] }),
+};
+// Run a memory effect against the mock, return the result.
+const runMem = (effect) => run(mock)(initial)(effect)[1];
+// TypeScript infers O = Operation (the upper bound) rather than O = never when
+// O flows through McpHandlers<never>, so we cast the widened type down to MemOp.
+const asMemEffect = (e) => e;
+// Run one step from uninitializedState, return [response, newState].
+const step1 = (cfg) => (msg) => runMem(asMemEffect(step(create(uninitializedState), key => step(mcpStep(cfg)(handlers)(key)(msg), resp => step(read(key), state => pure([resp, state]))))));
+// Run initialize then a second step, return [response, newState] of the second.
+const step2 = (cfg) => (msg1) => (msg2) => runMem(asMemEffect(eff(create(uninitializedState)).step(key => eff(mcpStep(cfg)(handlers)(key)(msg1)).step(() => eff(mcpStep(cfg)(handlers)(key)(msg2)).step(resp => step(read(key), state => pure([resp, state]))).value).value).value));
+// Run initialize, notifications/initialized, then a third step; return [response, newState] of the third.
+const step3 = (cfg) => (msg1) => (msg2) => (msg3) => runMem(asMemEffect(eff(create(uninitializedState)).step(key => eff(mcpStep(cfg)(handlers)(key)(msg1)).step(() => eff(mcpStep(cfg)(handlers)(key)(msg2)).step(() => eff(mcpStep(cfg)(handlers)(key)(msg3)).step(resp => eff(read(key)).step(state => pure([resp, state])).value).value).value).value).value));
+// ── Test messages ─────────────────────────────────────────────────────────────
+const initMsg = { jsonrpc: '2.0', method: 'initialize', id: 1,
+    params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'client', version: '0.0.1' } } };
+const initNotif = { jsonrpc: '2.0', method: 'notifications/initialized' };
+// ── Tests ─────────────────────────────────────────────────────────────────────
+export const proof = {
+    lifecycle: {
+        initialStateIsUninitialized: () => {
+            assert(uninitializedState[0] === 'uninitialized');
+        },
+        initializeTransitionsToInitializing: () => {
+            const [, newState] = step1(config)(initMsg);
+            assert(newState[0] === 'initializing');
+        },
+        initializedNotificationTransitionsToInitialized: () => {
+            const [resp, newState] = step2(config)(initMsg)(initNotif);
+            assertEq(resp, null);
+            assert(newState[0] === 'initialized');
+        },
+        initializeReturnsResult: () => {
+            const [resp] = step1(config)(initMsg);
+            assert(resp !== null && typeof resp === 'object' && 'result' in resp);
+            const r = resp.result;
+            assertEq(r.protocolVersion, '2024-11-05');
+        },
+        initializeWithBadParamsReturnsInvalidParams: () => {
+            const bad = { jsonrpc: '2.0', method: 'initialize', id: 2, params: { wrong: true } };
+            const [resp, newState] = step1(config)(bad);
+            assert(newState[0] === 'uninitialized');
+            assertEq(resp.error.code, -32602);
+        },
+        notificationBeforeInitReturnNull: () => {
+            const [resp, newState] = step1(config)(initNotif);
+            assert(newState[0] === 'uninitialized');
+            assertEq(resp, null);
+        },
+        unknownNotificationReturnNull: () => {
+            const notif = { jsonrpc: '2.0', method: 'notifications/unknown' };
+            const [resp] = step2(config)(initMsg)(notif);
+            assertEq(resp, null);
+        },
+        doubleInitializeReturnsInvalidRequest: () => {
+            const [resp, newState] = step2(config)(initMsg)(initMsg);
+            assert(newState[0] === 'initializing');
+            assertEq(resp.error.code, -32600);
+        },
+        pingBeforeInitSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 11 };
+            const [resp, newState] = step1(config)(msg);
+            assert(newState[0] === 'uninitialized');
+            assert(!('error' in resp));
+        },
+        pingDuringInitializingSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 12 };
+            const [resp, newState] = step2(config)(initMsg)(msg);
+            assert(newState[0] === 'initializing');
+            assert(!('error' in resp));
+        },
+        pingAfterInitSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 15 };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assert(!('error' in resp));
+        },
+        pingWithObjectParamsSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 19, params: {} };
+            const [resp] = step1(config)(msg);
+            assert(!('error' in resp));
+        },
+        pingInvalidParamsReturnsInvalidParams: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 20, params: 1 };
+            const [resp] = step1(config)(msg);
+            assertEq(resp.error.code, -32602);
+        },
+        initializedNotificationObjectParamsTransitions: () => {
+            const notif = { jsonrpc: '2.0', method: 'notifications/initialized', params: {} };
+            const [resp, newState] = step2(config)(initMsg)(notif);
+            assertEq(resp, null);
+            assert(newState[0] === 'initialized');
+        },
+        initializedNotificationBadParamsIgnored: () => {
+            const notif = { jsonrpc: '2.0', method: 'notifications/initialized', params: 1 };
+            const [resp, newState] = step2(config)(initMsg)(notif);
+            assertEq(resp, null);
+            assert(newState[0] === 'initializing');
+        },
+        methodBeforeInitReturnsNotInitialized: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 3 };
+            const [resp, newState] = step1(config)(msg);
+            assert(newState[0] === 'uninitialized');
+            assertEq(resp.error.code, notInitialized.code);
+        },
+        methodDuringInitializingReturnsNotInitialized: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 16 };
+            const [resp, newState] = step2(config)(initMsg)(msg);
+            assert(newState[0] === 'initializing');
+            assertEq(resp.error.code, notInitialized.code);
+        },
+        invalidEnvelopeReturnsInvalidRequest: () => {
+            const bad = { jsonrpc: '1.0', method: 'ping', id: 4 };
+            const [resp] = step1(config)(bad);
+            assertEq(resp.error.code, -32600);
+            assertEq(resp.id, null);
+        },
+    },
+    tools: {
+        toolsListSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 5 };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.result.tools.length, 1);
+            assertEq(resp.result.tools[0].name, 'greet');
+        },
+        toolsListPassesCursorToHandler: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 17,
+                params: { cursor: 'page-2' } };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.result.nextCursor, 'page-2');
+        },
+        toolsListInvalidCursorReturnsInvalidParams: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 18,
+                params: { cursor: 42 } };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.error.code, -32602);
+        },
+        toolsCallSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 6,
+                params: { name: 'greet', arguments: {} } };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.result.content[0].text, 'hello');
+        },
+        toolsCallBadParamsReturnsInvalidParams: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 7, params: { missing: true } };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.error.code, -32602);
+        },
+        toolsCallAbsentArgumentsSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 13,
+                params: { name: 'greet' } };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.result.content[0].text, 'hello');
+        },
+        toolsCallNullArgumentsReturnsInvalidParams: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 14,
+                params: { name: 'greet', arguments: null } };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.error.code, -32602);
+        },
+        toolsListWithoutCapabilityReturnsMethodNotFound: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 8 };
+            const [resp] = step3(configNoTools)(initMsg)(initNotif)(msg);
+            assertEq(resp.error.code, -32601);
+        },
+        toolsCallWithoutCapabilityReturnsMethodNotFound: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 9,
+                params: { name: 'greet', arguments: {} } };
+            const [resp] = step3(configNoTools)(initMsg)(initNotif)(msg);
+            assertEq(resp.error.code, -32601);
+        },
+        unknownMethodReturnsMethodNotFound: () => {
+            const msg = { jsonrpc: '2.0', method: 'resources/list', id: 10 };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.error.code, -32601);
+        },
+    },
+};

package/fjs/{mcp → protocol/mcp}/stdio/module.f.d.ts

@@ -2,7 +2,7 @@
  * stdio transport for JSON-RPC / MCP servers.
  *
  * `stdioTransport` wraps a step function — the `mcpStep`-shaped
- * `(value) => Effect<O, Response | null>` from `fjs/mcp/module.f.ts` — in the
+ * `(value) => Effect<O, Response | null>` from `fjs/protocol/mcp/module.f.ts` — in the
  * canonical read → parse → dispatch → write loop, expressed as a recursive
  * effect so it stays in the pure effect model and is fully testable against a
  * mock stdin / stdout (see `fjs/effects/node/virtual`) with no real process.
@@ -29,19 +29,19 @@
  *
  * @module
  */
-import { type Effect, type Operation } from '../../effects/module.f.ts';
-import { type Read, type Write } from '../../effects/node/module.f.ts';
-import { type Unknown } from '../../media/json/module.f.ts';
-import { type Response } from '../../media/json/rpc/module.f.ts';
+import { type Effect, type Operation } from '../../../effects/module.f.ts';
+import { type Read, type Write } from '../../../effects/node/module.f.ts';
+import { type Unknown } from '../../../media/json/module.f.ts';
+import { type Response } from '../../json_rpc/module.f.ts';
 /**
  * A transport step: maps one parsed JSON-RPC message to a response, or `null`
  * for a notification that needs no reply. The shape of `mcpStep(config)(handlers)(key)`.
  */
 export type Step<O extends Operation> = (value: Unknown) => Effect<O, Response | null>;
 /**
- * Drives the read-parse-dispatch-write loop for `step` over stdin/stdout.
+ * Drives the read-parse-dispatch-write loop for `handler` over stdin/stdout.
  *
  * Recurses after each handled line; terminates (resolving to `void`) when
  * `readLine` reports EOF.
  */
-export declare const stdioTransport: <O extends Operation>(step: Step<O>) => Effect<Read | Write | O, void>;
+export declare const stdioTransport: <O extends Operation>(handler: Step<O>) => Effect<Read | Write | O, void>;

package/fjs/{mcp → protocol/mcp}/stdio/module.f.js

@@ -2,7 +2,7 @@
  * stdio transport for JSON-RPC / MCP servers.
  *
  * `stdioTransport` wraps a step function — the `mcpStep`-shaped
- * `(value) => Effect<O, Response | null>` from `fjs/mcp/module.f.ts` — in the
+ * `(value) => Effect<O, Response | null>` from `fjs/protocol/mcp/module.f.ts` — in the
  * canonical read → parse → dispatch → write loop, expressed as a recursive
  * effect so it stays in the pure effect model and is fully testable against a
  * mock stdin / stdout (see `fjs/effects/node/virtual`) with no real process.
@@ -29,16 +29,16 @@
  *
  * @module
  */
-import { pure } from '../../effects/module.f.js';
-import { readLine, write } from '../../effects/node/module.f.js';
-import { tryUtf8 } from '../../text/module.f.js';
-import { stringToList } from '../../text/utf16/module.f.js';
-import { stringify } from '../../media/json/module.f.js';
-import { tokenize } from '../../media/json/tokenizer/module.f.js';
-import { parse } from '../../media/json/parser/module.f.js';
-import { sort } from '../../types/object/module.f.js';
-import { internalError, jsonrpc, parseError } from '../../media/json/rpc/module.f.js';
-import { error, ok } from '../../types/result/module.f.js';
+import { pure, step } from '../../../effects/module.f.js';
+import { readLine, write } from '../../../effects/node/module.f.js';
+import { tryUtf8 } from '../../../text/module.f.js';
+import { stringToList } from '../../../text/utf16/module.f.js';
+import { stringify } from '../../../media/json/module.f.js';
+import { tokenize } from '../../../media/json/tokenizer/module.f.js';
+import { parse } from '../../../media/json/parser/module.f.js';
+import { sort } from '../../../types/object/module.f.js';
+import { internalError, jsonrpc, parseError } from '../../json_rpc/module.f.js';
+import { error, ok } from '../../../types/result/module.f.js';
 const stringifyJson = stringify(sort);
 /** The parse-error response (`-32700`, `id: null`) for a malformed input line. */
 const parseErrorResponse = { jsonrpc, error: parseError, id: null };
@@ -49,24 +49,24 @@ const writeResponse = (resp) => {
     const v = tryUtf8(stringifyJson(resp) + '\n');
     return v === null
         ? pure(error(undefined))
-        : write('stdout', v).step(() => pure(ok(undefined)));
+        : step(write('stdout', v), () => pure(ok(undefined)));
 };
 /**
- * Drives the read-parse-dispatch-write loop for `step` over stdin/stdout.
+ * Drives the read-parse-dispatch-write loop for `handler` over stdin/stdout.
  *
  * Recurses after each handled line; terminates (resolving to `void`) when
  * `readLine` reports EOF.
  */
-export const stdioTransport = (step) => readLine('stdin').step(line => line === null
+export const stdioTransport = (handler) => step(readLine('stdin'), line => line === null
     ? pure(undefined)
-    : handleLine(step)(line));
-const handleLine = (step) => (line) => {
+    : handleLine(handler)(line));
+const handleLine = (handler) => (line) => {
     const [t, value] = parse(tokenize(stringToList(line)));
-    return (t === 'error'
+    return step(t === 'error'
         ? writeResponse(parseErrorResponse)
-        : step(value).step(resp => resp === null
+        : step(handler(value), resp => resp === null
             ? pure(undefined)
-            : writeResponse(resp).step(([t2]) => t2 === 'error'
+            : step(writeResponse(resp), ([t2]) => t2 === 'error'
                 // The real response didn't fit. Retry with a fixed, small
                 // internal-error body carrying `resp.id` — but a
                 // caller-controlled `id` (e.g. a very large string) can
@@ -74,8 +74,8 @@ const handleLine = (step) => (line) => {
                 // that retry is bounded by one more: an `id: null`
                 // internal-error, whose fully-constant shape is the only
                 // line in this transport guaranteed to always encode.
-                ? writeResponse(internalErrorResponse(resp.id)).step(([t3]) => t3 === 'error'
-                    ? writeResponse(internalErrorResponse(null)).step(() => pure(undefined))
+                ? step(writeResponse(internalErrorResponse(resp.id)), ([t3]) => t3 === 'error'
+                    ? step(writeResponse(internalErrorResponse(null)), () => pure(undefined))
                     : pure(undefined))
-                : pure(undefined)))).step(() => stdioTransport(step));
+                : pure(undefined))), () => stdioTransport(handler));
 };

package/fjs/{mcp → protocol/mcp}/stdio/proof.f.js

@@ -1,12 +1,12 @@
-import { assertEq } from '../../asserts/module.f.js';
-import { pure } from '../../effects/module.f.js';
-import { emptyState, virtual } from '../../effects/node/virtual/module.f.js';
-import { stringify } from '../../media/json/module.f.js';
-import { utf8 } from '../../text/module.f.js';
-import { fromVec } from '../../types/uint8array/module.f.js';
-import { maxLengthBytes } from '../../types/bit_vec/module.f.js';
-import { sort } from '../../types/object/module.f.js';
-import { internalError, jsonrpc, parseError } from '../../media/json/rpc/module.f.js';
+import { assertEq } from '../../../asserts/module.f.js';
+import { pure } from '../../../effects/module.f.js';
+import { emptyState, virtual } from '../../../effects/node/virtual/module.f.js';
+import { stringify } from '../../../media/json/module.f.js';
+import { utf8 } from '../../../text/module.f.js';
+import { fromVec } from '../../../types/uint8array/module.f.js';
+import { maxLengthBytes } from '../../../types/bit_vec/module.f.js';
+import { sort } from '../../../types/object/module.f.js';
+import { internalError, jsonrpc, parseError } from '../../json_rpc/module.f.js';
 import { stdioTransport } from './module.f.js';
 const stringifyJson = stringify(sort);
 // Extracts the request `id` (a request has one; a notification does not).

package/fjs/types/bigint/module.f.js

@@ -17,7 +17,8 @@
  * ```
  */
 import { cmp } from '../function/compare/module.f.js';
-import { reduce } from '../list/module.f.js';
+import {} from '../list/module.f.js';
+import { fold } from '../../common/monoid/module.f.js';
 /**
  * Adds two `bigint` values.
  *
@@ -31,7 +32,7 @@ export const addition = a => b => a + b;
  * @param input - A list of bigint values.
  * @returns The sum of all values in the list.
  */
-export const sum = reduce(addition)(0n);
+export const sum = fold({ identity: 0n, operation: addition });
 /**
  * Multiplies two `bigint` values.
  *
@@ -45,7 +46,7 @@ export const multiple = a => b => a * b;
  * @param input - A list of bigint values.
  * @returns The product of all values in the list.
  */
-export const product = reduce(multiple)(1n);
+export const product = fold({ identity: 1n, operation: multiple });
 /**
  * Calculates the absolute value of a `bigint`.
  *

package/fjs/types/bit_vec/module.f.js

@@ -23,7 +23,7 @@
  */
 import { bitLength, divUp, mask, maxLength, xor } from '../bigint/module.f.js';
 import { flip, identity } from '../function/module.f.js';
-import { iterable, map } from '../list/module.f.js';
+import { map, tryFold } from '../list/module.f.js';
 import { asBase, asNominal } from '../nominal/module.f.js';
 import { repeat as mRepeat } from '../../common/monoid/module.f.js';
 import { cmp, max, min } from '../function/compare/module.f.js';
@@ -174,24 +174,14 @@ const listToVecOp = (unpackConcat) => ({
  * the final reduce prepends higher (earlier) slots in front of accumulated
  * later runs. An empty list yields `unpackEmpty`.
  *
+ * Returns `null` as soon as the accumulated length exceeds `maxLength`, which
+ * `tryFold` propagates by abandoning the rest of the list.
+ *
  * This is the bit-vector analogue of a builder that accumulates appended pieces
  * and materializes the combined result on demand, such as `StringBuilder`
  * (Java, C#) or `strings.Builder` (Go).
  */
-const unpackListToVec = (unpackConcat) => {
-    const { init, update, end } = listToVecOp(unpackConcat);
-    return (list) => {
-        let result = init;
-        for (const e of iterable(list)) {
-            const candidate = update(e, result);
-            if (candidate === null) {
-                return null;
-            }
-            result = candidate;
-        }
-        return end(result);
-    };
-};
+const unpackListToVec = (unpackConcat) => tryFold(listToVecOp(unpackConcat));
 const bo = ({ front, removeFront, norm, uintCmp, unpackSplit, unpackConcatUint }) => {
     const unpackPopFront = (len) => {
         const m = mask(len);

package/fjs/types/btree/remove/module.f.d.ts

@@ -7,3 +7,8 @@ import { type TNode, type Tree } from '../types/module.f.ts';
 import type { Compare } from '../../function/compare/module.f.ts';
 export declare const nodeRemove: <T>(c: Compare<T>) => (node: TNode<T>) => Tree<T>;
 export declare const remove: <T>(c: Compare<T>) => (tree: Tree<T>) => Tree<T>;
+export declare const proof: {
+    throw: {
+        reduceValue0DefaultBranch: () => void;
+    };
+};

package/fjs/types/btree/remove/module.f.js

@@ -172,3 +172,15 @@ export const nodeRemove = (c) => (node) => {
     return collapseRoot(reduce(initReduce(tf)(first))(tt));
 };
 export const remove = c => map(nodeRemove(c));
+// `reduceValue0`/`reduceValue2`/`initValue0`/`initValue1` merge a Branch1's lone
+// child into its Branch3 sibling. The sibling is always a Branch (length 3 or 5)
+// in every reachable tree shape, so the `default` arm guarding a mismatched
+// (leaf) sibling length can't be hit through the public `remove` API. Exercise
+// it directly here so the invariant guard itself stays covered.
+export const proof = {
+    throw: {
+        reduceValue0DefaultBranch: () => {
+            reduceValue0([['leaf']])([['x'], 's', ['y']]);
+        },
+    },
+};

package/fjs/types/list/module.f.d.ts

@@ -1,3 +1,4 @@
+import type { Nullable } from '../nullable/module.f.ts';
 import { type Scan, type StateScan, type Fold, type Reduce, type Equal } from '../function/operator/module.f.ts';
 export type List<T> = NotLazy<T> | Thunk<T>;
 type NotLazy<T> = Result<T> | Concat<T> | readonly T[];
@@ -44,6 +45,26 @@ export declare const stateScan: <I, S, O>(op: StateScan<I, S, O>) => (init: S) =
 export declare const foldScan: <I, O>(op: Fold<I, O>) => (init: O) => (input: List<I>) => Thunk<O>;
 export declare const fold: <I, O>(op: Fold<I, O>) => (init: O) => (input: List<I>) => O;
 export declare const reduce: <T>(op: Reduce<T>) => <D>(def: D) => (input: List<T>) => D | T;
+/**
+ * A fold that can bail out early, packaged as plain data.
+ *
+ * `init` is the starting state, `update` advances the state by one item and
+ * returns `null` to abort the whole fold, and `end` finalizes the surviving
+ * state into a result. Keeping the three parts together lets `tryFold` drive
+ * any short-circuiting accumulation without knowing its domain.
+ */
+export type Accumulator<I, T, R> = {
+    readonly init: T;
+    readonly update: (i: I, state: T) => Nullable<T>;
+    readonly end: (state: T) => R;
+};
+/**
+ * Folds `input` with an {@link Accumulator}, short-circuiting to `null` the
+ * moment `update` rejects an item; otherwise finalizes with `end`. This is the
+ * list-level `try*` sibling of {@link fold} for accumulations that can fail
+ * partway through (see the `try*`/`Nullable` convention in `AGENTS.md`).
+ */
+export declare const tryFold: <I, T, R>({ init, update, end }: Accumulator<I, T, R>) => (input: List<I>) => Nullable<R>;
 export declare const length: <T>(input: List<T>) => number;
 export type Entry<T> = readonly [number, T];
 export declare const entries: <T>(input: List<T>) => Thunk<Entry<T>>;

package/fjs/types/list/module.f.js

@@ -127,6 +127,23 @@ export const stateScan = op => compose(stateScanToScan(op))(scan);
 export const foldScan = op => compose(foldToScan(op))(scan);
 export const fold = op => init => compose(foldScan(op)(init))(last(init));
 export const reduce = op => def => compose(scan(reduceToScan(op)))(last(def));
+/**
+ * Folds `input` with an {@link Accumulator}, short-circuiting to `null` the
+ * moment `update` rejects an item; otherwise finalizes with `end`. This is the
+ * list-level `try*` sibling of {@link fold} for accumulations that can fail
+ * partway through (see the `try*`/`Nullable` convention in `AGENTS.md`).
+ */
+export const tryFold = ({ init, update, end }) => (input) => {
+    let state = init;
+    for (const i of iterable(input)) {
+        const candidate = update(i, state);
+        if (candidate === null) {
+            return null;
+        }
+        state = candidate;
+    }
+    return end(state);
+};
 const lengthList = list => () => {
     const notLazy = trampoline(list);
     if (notLazy === null) {

package/fjs/types/list/proof.f.d.ts

@@ -19,6 +19,7 @@ export declare const proof: {
     drop: (() => void)[];
     additionTests: (() => void)[];
     entries: (() => void)[];
+    tryFold: readonly [() => void, () => void, () => void];
     reverse: (() => void)[];
     zip: (() => void)[];
     logic: typeof logic;

package/fjs/types/list/proof.f.js

@@ -1,4 +1,4 @@
-import { length, concat, countdown, cycle, drop, dropWhile, entries, every, filter, find, flat, flatMap, map, next, reduce, reverse, scan, some, take, takeWhile, toArray, zip, first, filterMap, isEmpty, equal } from './module.f.js';
+import { length, concat, countdown, cycle, drop, dropWhile, entries, every, filter, find, flat, flatMap, map, next, reduce, reverse, scan, some, take, takeWhile, toArray, zip, first, filterMap, isEmpty, equal, tryFold } from './module.f.js';
 import { stringify } from '../../media/json/module.f.js';
 import { sort } from '../object/module.f.js';
 import { addition, strictEqual, reduceToScan } from '../function/operator/module.f.js';
@@ -112,6 +112,28 @@ const entriesTest = [
         assertEq(result, '[[0,"hello"],[1,"world"]]');
     }
 ];
+const sumUpTo = (limit) => ({
+    init: 0,
+    update: (i, state) => {
+        const next = state + i;
+        return next > limit ? null : next;
+    },
+    end: (state) => state * 10,
+});
+const tryFoldTest = [
+    () => {
+        const result = tryFold(sumUpTo(100))([1, 2, 3]);
+        assertEq(result, 60);
+    },
+    () => {
+        const result = tryFold(sumUpTo(4))([1, 2, 3]);
+        assertEq(result, null);
+    },
+    () => {
+        const result = tryFold(sumUpTo(100))([]);
+        assertEq(result, 0);
+    },
+];
 const reverseTest = [
     () => {
         const result = str(reverse([]));
@@ -257,6 +279,7 @@ export const proof = {
     drop: dropTest,
     additionTests,
     entries: entriesTest,
+    tryFold: tryFoldTest,
     reverse: reverseTest,
     zip: zipTest,
     logic,

package/fjs/types/number/module.f.js

@@ -7,7 +7,8 @@
 import { reduce } from '../list/module.f.js';
 import { addition } from '../function/operator/module.f.js';
 import { cmp as uCmp, min as uMin, max as uMax } from '../function/compare/module.f.js';
-export const sum = reduce(addition)(0);
+import { fold } from '../../common/monoid/module.f.js';
+export const sum = fold({ identity: 0, operation: addition });
 export const min = reduce(uMin)(null);
 export const max = reduce(uMax)(null);
 export const cmp = uCmp;

package/fjs/types/range_map/module.f.d.ts

@@ -13,25 +13,26 @@
  * })
  *
  * // Create range maps
- * const range1 = rmOps.fromRange([0, 10])(2)
- * const range2 = rmOps.fromRange([5, 15])(5)
+ * const range1 = rmOps.fromRange(2)([0, 10])
+ * const range2 = rmOps.fromRange(5)([5, 15])
  *
  * // Merge range maps
  * const merged = toArray(rmOps.merge(range1)(range2))
  *
  * // Retrieve values from the merged range map
+ * const get = rmOps.get(merged)
  * //
- * if (rmOps.get(-1)(merged) !== 0) { throw 'error' }
+ * if (get(-1) !== 0) { throw 'error' }
  * //
- * if (rmOps.get(0)(merged) !== 2) { throw 'error' }
- * if (rmOps.get(2)(merged) !== 2) { throw 'error' }
+ * if (get(0) !== 2) { throw 'error' }
+ * if (get(2) !== 2) { throw 'error' }
  * // overlapped: 2 | 5 = 7
- * if (rmOps.get(7)(merged) !== 7) { throw 'error' }
+ * if (get(7) !== 7) { throw 'error' }
  * //
- * if (rmOps.get(12)(merged) !== 5) { throw 'error' }
- * if (rmOps.get(15)(merged) !== 5) { throw 'error' }
+ * if (get(12) !== 5) { throw 'error' }
+ * if (get(15) !== 5) { throw 'error' }
  * //
- * if (rmOps.get(16)(merged) !== 0) { throw 'error' }
+ * if (get(16) !== 0) { throw 'error' }
  * ```
  */
 import { type SortedList } from '../sorted_list/module.f.ts';
@@ -63,8 +64,8 @@ export type Properties<T> = {
 };
 export type RangeMerge<T> = Reduce<RangeMap<T>>;
 export declare const merge: <T>(op: Properties<T>) => RangeMerge<T>;
-export declare const get: <T>(def: T) => (value: number) => (rm: RangeMapArray<T>) => T;
-export declare const fromRange: <T>(def: T) => (r: Range) => (value: T) => RangeMapArray<T>;
+export declare const get: <T>(def: T) => (rm: RangeMapArray<T>) => (value: number) => T;
+export declare const fromRange: <T>(def: T) => (value: T) => (r: Range) => RangeMapArray<T>;
 /**
  * Represents a set of operations for managing range maps.
  */
@@ -76,11 +77,11 @@ export type RangeMapOp<T> = {
     /**
      * Retrieves the value associated with a given numeric range.
      */
-    readonly get: (value: number) => (rm: RangeMapArray<T>) => T;
+    readonly get: (rm: RangeMapArray<T>) => (value: number) => T;
     /**
      * Constructs a range map for a single numeric range and value.
      */
-    readonly fromRange: (r: Range) => (value: T) => RangeMapArray<T>;
+    readonly fromRange: (value: T) => (r: Range) => RangeMapArray<T>;
 };
 /**
  * Creates a set of operations for managing range maps using the specified properties.