functionalscript 0.13.1 → 0.14.0

package/fs/sul/module.f.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Streaming encoder for the full SUL pipeline.
+ * Processes bits one at a time through literal levels L1→L2→L3, then through a dynamic array of hash levels.
+ *
+ * @module
+ */
+import { type PipelineState } from './level/literal/module.f.ts';
+import { type Add } from './level/hash/module.f.ts';
+import { type Id } from './id/module.f.ts';
+import type { InternalState } from '../types/patricia_trie/module.f.ts';
+type HashState = InternalState<Id>;
+export type EncodeState<S> = readonly [
+    PipelineState,
+    S,
+    readonly HashState[]
+];
+export type Encode<S> = {
+    readonly push: (bit: bigint, state: EncodeState<S>) => EncodeState<S>;
+    readonly end: (state: EncodeState<S>) => Id;
+};
+export declare const emptyEncodeState: <S>(storage: S) => EncodeState<S>;
+export declare const encode: <S>(add: Add<S>) => Encode<S>;
+export {};

package/fs/sul/module.f.js

@@ -0,0 +1,46 @@
+/**
+ * Streaming encoder for the full SUL pipeline.
+ * Processes bits one at a time through literal levels L1→L2→L3, then through a dynamic array of hash levels.
+ *
+ * @module
+ */
+import { emptyPipelineState, pipelineStep } from "./level/literal/module.f.js";
+import { encode as hashEncode } from "./level/hash/module.f.js";
+import { level3Id } from "./id/module.f.js";
+export const emptyEncodeState = (storage) => [emptyPipelineState, storage, []];
+export const encode = (add) => {
+    const step = hashEncode(add);
+    const cascade = (id0, storage0, stacks0) => {
+        let id = id0, storage = storage0, stacks = stacks0;
+        for (let index = 0;; index++) {
+            if (index >= stacks.length) {
+                const [, [newStorage, newStack]] = step(id, [storage, []]);
+                return [id, newStorage, [...stacks, newStack]];
+            }
+            const [out, [newStorage, newStack]] = step(id, [storage, stacks[index]]);
+            stacks = [...stacks.slice(0, index), newStack, ...stacks.slice(index + 1)];
+            storage = newStorage;
+            if (out === undefined)
+                return [undefined, storage, stacks];
+            id = out;
+        }
+    };
+    const literalStep = (bit, state) => {
+        const [ps, storage, stacks] = state;
+        const [l3Out, newPs] = pipelineStep(bit, ps);
+        if (l3Out === undefined)
+            return [undefined, [newPs, storage, stacks]];
+        const [finalId, newStorage, newStacks] = cascade(level3Id(l3Out), storage, stacks);
+        return [finalId, [newPs, newStorage, newStacks]];
+    };
+    return {
+        push: (bit, state) => literalStep(bit, state)[1],
+        end: state => {
+            let [id, s] = literalStep(1n, state);
+            while (id === undefined) {
+                [id, s] = literalStep(0n, s);
+            }
+            return id;
+        }
+    };
+};

package/fs/sul/test.f.d.ts

@@ -0,0 +1,10 @@
+declare const _default: {
+    deterministic: () => void;
+    distinct: () => void;
+    order_matters: () => void;
+    length_matters: () => void;
+    has_merges: () => void;
+    compress_correct: () => void;
+    isSymbol_terminal_only: () => void;
+};
+export default _default;

package/fs/sul/test.f.js

@@ -0,0 +1,47 @@
+import { assert, assertEq } from "../dev/module.f.js";
+import { compress } from "./id/module.f.js";
+import { encode, emptyEncodeState } from "./module.f.js";
+const run = (bits) => {
+    const log = [];
+    const add = (l, r, m, isSymbol) => { log.push([l, r, m, isSymbol]); return null; };
+    const enc = encode(add);
+    let s = emptyEncodeState(null);
+    for (const b of bits) {
+        s = enc.push(b, s);
+    }
+    return [enc.end(s), log];
+};
+const id = (bits) => run(bits)[0];
+const zeros = (n) => new Array(n).fill(0n);
+export default {
+    deterministic: () => {
+        assertEq(id(zeros(16)), id(zeros(16)));
+    },
+    distinct: () => {
+        assert(id([0n]) !== id([1n]));
+    },
+    order_matters: () => {
+        assert(id([0n, 1n]) !== id([1n, 0n]));
+    },
+    length_matters: () => {
+        assert(id(zeros(8)) !== id(zeros(16)));
+    },
+    // Enough bits to trigger at least one hash merge
+    has_merges: () => {
+        const [, log] = run(zeros(16));
+        assert(log.length > 0);
+    },
+    // Every recorded merge satisfies merged === compress(left, right)
+    compress_correct: () => {
+        const [, log] = run(zeros(16));
+        for (const [l, r, m] of log) {
+            assertEq(m, compress(l, r));
+        }
+    },
+    // Patricia-trie internal merges are isSymbol=false; terminal merges are isSymbol=true
+    isSymbol_terminal_only: () => {
+        const [, log] = run(zeros(16));
+        assert(log.some(([, , , isSymbol]) => isSymbol));
+        assert(log.every(([l, r, m, isSymbol]) => !isSymbol || m === compress(l, r)));
+    },
+};

package/{text → fs/text}/module.f.d.ts

@@ -1,4 +1,4 @@
-import { type Vec } from "../types/bit_vec/module.f.ts";
+import { type Vec } from '../types/bit_vec/module.f.ts';
 import { type List } from '../types/list/module.f.ts';
 export type Block = ItemThunk | ItemArray;
 type ItemArray = readonly Item[];

package/{text → fs/text}/utf16/module.f.js

@@ -150,7 +150,7 @@ const u16 = contains([0x0000, 0xFFFF]);
  * ```ts
  * const state: Utf16State = null;
  * const word: U16 = 0xD83D;  // High surrogate for 😀 emoji
- * const [decodedCodePoints, newState] = utf16ByteToCodePointOp(state)(word);
+ * const [decodedCodePoints, newState] = utf16ByteToCodePointOp(word, state);
  * ```
  *
  * @example
@@ -158,10 +158,10 @@ const u16 = contains([0x0000, 0xFFFF]);
  * ```ts
  * const state: Utf16State = 0xD83D;  // High surrogate already stored
  * const word: U16 = 0xDC00;  // Low surrogate for 😀 emoji
- * const [decodedCodePoints, newState] = utf16ByteToCodePointOp(state)(word);
+ * const [decodedCodePoints, newState] = utf16ByteToCodePointOp(word, state);
  * ```
  */
-const utf16ByteToCodePointOp = state => word => {
+const utf16ByteToCodePointOp = (word, state) => {
     if (!u16(word)) {
         return [[0xffffffff], state];
     }
@@ -233,19 +233,19 @@ const utf16EofToCodePointOp = (state) => [state === null ? empty : [state | erro
  * ```ts
  * // Example 1: Process a valid UTF-16 word
  * const input1 = 0x0041 // 'A' (BMP code point)
- * const result1 = utf16ByteOrEofToCodePointOp(null)(input1)
+ * const result1 = utf16ByteOrEofToCodePointOp(input1, null)
  * console.log(result1) // [[0x0041], null]
  * // Example 2: Process a high surrogate, followed by EOF
  * const input2 = 0xD83D // High surrogate
- * const result2 = utf16ByteOrEofToCodePointOp(null)(input2)
+ * const result2 = utf16ByteOrEofToCodePointOp(input2, null)
  * console.log(result2) // [[], 0xD83D] (waiting for a low surrogate)
- * const eofResult = utf16ByteOrEofToCodePointOp(0xD83D)(null)
+ * const eofResult = utf16ByteOrEofToCodePointOp(null, 0xD83D)
  * console.log(eofResult) // [[0xD83D | errorMask], null] (unpaired high surrogate)
  * // Example 3: Handle EOF with no pending state
- * const eofResult2 = utf16ByteOrEofToCodePointOp(null)(null)
+ * const eofResult2 = utf16ByteOrEofToCodePointOp(null, null)
  * ```
  */
-const utf16ByteOrEofToCodePointOp = state => input => input === null ? utf16EofToCodePointOp(state) : utf16ByteToCodePointOp(state)(input);
+const utf16ByteOrEofToCodePointOp = (input, state) => input === null ? utf16EofToCodePointOp(state) : utf16ByteToCodePointOp(input, state);
 /**
  * Represents an end-of-file (EOF) indicator in a list of UTF-16 code units.
  *

package/{text → fs/text}/utf8/module.f.js

@@ -113,7 +113,7 @@ const utf8StateToError = (state) => {
  *   - A list of decoded Unicode code points or error codes.
  *   - The updated UTF-8 state.
  */
-const utf8ByteToCodePointOp = (state) => (byte) => {
+const utf8ByteToCodePointOp = (byte, state) => {
     if (byte < 0x00 || byte > 0xff) {
         return [[errorMask], state];
     }
@@ -184,7 +184,7 @@ const utf8EofToCodePointOp = (state) => [
  *   - A list of decoded Unicode code points or error codes.
  *   - The updated UTF-8 state.
  */
-const utf8ByteOrEofToCodePointOp = (state) => (input) => input === null ? utf8EofToCodePointOp(state) : utf8ByteToCodePointOp(state)(input);
+const utf8ByteOrEofToCodePointOp = (input, state) => input === null ? utf8EofToCodePointOp(state) : utf8ByteToCodePointOp(input, state);
 /**
  * A constant representing the end-of-file (EOF) marker for UTF-8 decoding.
  *

package/{types → fs/types}/bit_vec/module.f.d.ts

@@ -56,6 +56,7 @@ export declare const unpack: (v: Vec) => Unpacked;
  * Packs an unpacked representation back into a vector.
  */
 export declare const pack: ({ length, uint }: Unpacked) => Vec;
+export declare const unpackedUint: ({ uint }: Unpacked) => bigint;
 type Norm = (len: bigint) => {
     readonly a: bigint;
     readonly b: bigint;
@@ -189,6 +190,17 @@ export declare const msb: BitOrder;
  * @returns The resulting vector based on the provided bit order.
  */
 export declare const u8ListToVec: ({ unpackConcat }: BitOrder) => (list: List<number>) => Vec;
+/**
+ * Chunks an unpacked vector into fixed-size pieces of `n` bits using the provided bit order,
+ * returning each chunk as an unsigned integer.
+ * The last chunk may be smaller than `n` bits if the vector length is not a multiple of `n`.
+ *
+ * @param bitOrder The bit order for the conversion.
+ * @param n The chunk size in bits.
+ * @param u The unpacked vector to be chunked.
+ * @returns A thunk that produces a list of unsigned integers, each representing one chunk.
+ */
+export declare const uintChunkList: (bo: BitOrder) => (n: bigint) => (u: Unpacked) => Thunk<bigint>;
 /**
  * Chunks a bit vector into fixed-size pieces of `n` bits using the provided bit order.
  * The last chunk may be smaller than `n` bits if the vector length is not a multiple of `n`.
@@ -198,7 +210,7 @@ export declare const u8ListToVec: ({ unpackConcat }: BitOrder) => (list: List<nu
  * @param v The vector to be chunked.
  * @returns A thunk that produces a list of bit vectors, each representing one chunk.
  */
-export declare const chunkList: ({ unpackSplit }: BitOrder) => (n: bigint) => (v: Vec) => Thunk<Vec>;
+export declare const chunkList: (bo: BitOrder) => (n: bigint) => (v: Vec) => Thunk<Vec>;
 /**
  * Converts a bit vector to a list of unsigned 8-bit integers based on the provided bit order.
  *

package/{types → fs/types}/bit_vec/module.f.js

@@ -22,7 +22,7 @@
  * @module
  */
 import { bitLength, divUp, mask, max, min, xor } from "../bigint/module.f.js";
-import { flip } from "../function/module.f.js";
+import { flip, identity } from "../function/module.f.js";
 import { fold, iterable, map } from "../list/module.f.js";
 import { asBase, asNominal } from "../nominal/module.f.js";
 import { repeat as mRepeat } from "../monoid/module.f.js";
@@ -97,6 +97,7 @@ export const unpack = (v) => ({
  * Packs an unpacked representation back into a vector.
  */
 export const pack = ({ length, uint }) => vec(length)(uint);
+export const unpackedUint = ({ uint }) => uint;
 /**
  * Normalizes two vectors to the same length before applying a bigint reducer.
  */
@@ -234,19 +235,10 @@ export const u8ListToVec = ({ unpackConcat }) => (list) => {
     }
     return pack(result.reduce((p, c) => unpackConcat(c)(p), unpackEmpty));
 };
-/**
- * Chunks a bit vector into fixed-size pieces of `n` bits using the provided bit order.
- * The last chunk may be smaller than `n` bits if the vector length is not a multiple of `n`.
- *
- * @param bitOrder The bit order for the conversion.
- * @param n The chunk size in bits.
- * @param v The vector to be chunked.
- * @returns A thunk that produces a list of bit vectors, each representing one chunk.
- */
-export const chunkList = ({ unpackSplit }) => (n) => {
+const unpackChunkList = ({ unpackSplit }) => (n) => {
     const divUpN2 = divUp(n << 1n);
-    return v => {
-        if (v === empty) {
+    return u => {
+        if (u.length === 0n) {
             return () => null;
         }
         const f = (stack) => () => {
@@ -254,7 +246,7 @@ export const chunkList = ({ unpackSplit }) => (n) => {
                 const [first, rest] = stack;
                 const { length } = first;
                 if (length <= n) {
-                    return { first: pack(first), tail: rest !== undefined ? f(rest) : null };
+                    return { first, tail: rest !== undefined ? f(rest) : null };
                 }
                 const aLength = divUpN2(length) * n;
                 const bLength = length - aLength;
@@ -265,9 +257,35 @@ export const chunkList = ({ unpackSplit }) => (n) => {
                 ];
             }
         };
-        return f([unpack(v), undefined]);
+        return f([u, undefined]);
     };
 };
+const mappedChunkList = (g) => (f) => (bo) => (n) => {
+    const ucl = unpackChunkList(bo)(n);
+    const mf = map(f);
+    return i => mf(ucl(g(i)));
+};
+/**
+ * Chunks an unpacked vector into fixed-size pieces of `n` bits using the provided bit order,
+ * returning each chunk as an unsigned integer.
+ * The last chunk may be smaller than `n` bits if the vector length is not a multiple of `n`.
+ *
+ * @param bitOrder The bit order for the conversion.
+ * @param n The chunk size in bits.
+ * @param u The unpacked vector to be chunked.
+ * @returns A thunk that produces a list of unsigned integers, each representing one chunk.
+ */
+export const uintChunkList = mappedChunkList((identity))(unpackedUint);
+/**
+ * Chunks a bit vector into fixed-size pieces of `n` bits using the provided bit order.
+ * The last chunk may be smaller than `n` bits if the vector length is not a multiple of `n`.
+ *
+ * @param bitOrder The bit order for the conversion.
+ * @param n The chunk size in bits.
+ * @param v The vector to be chunked.
+ * @returns A thunk that produces a list of bit vectors, each representing one chunk.
+ */
+export const chunkList = mappedChunkList(unpack)(pack);
 const vecToU8 = ({ unpackSplit }) => {
     const unpackSplit8 = unpackSplit(8n);
     return chunk => {

package/{types → fs/types}/effects/module.f.d.ts

@@ -27,3 +27,4 @@ export type ToAsyncOperationMap<O extends Operation> = {
 export type F<O extends Operation> = Pr<O, O[0]>;
 export type Func<O extends Operation> = (_: Param<O>) => Effect<O, Return<O>>;
 export type RestFunc<O extends Operation> = (..._: Param<O>) => Effect<O, Return<O>>;
+export type ListEffect<O extends Operation, T> = Effect<O, readonly [T, ListEffect<O, T>] | undefined>;

package/{types → fs/types}/effects/node/virtual/module.f.d.ts

@@ -1,6 +1,6 @@
-import { type Vec } from "../../../bit_vec/module.f.ts";
-import { type RunInstance } from "../../mock/module.f.ts";
-import type { NodeOp } from "../module.f.ts";
+import { type Vec } from '../../../bit_vec/module.f.ts';
+import { type RunInstance } from '../../mock/module.f.ts';
+import type { NodeOp } from '../module.f.ts';
 export type Dir = {
     readonly [name in string]?: Dir | Vec;
 };

package/{types → fs/types}/function/operator/module.f.d.ts

@@ -12,7 +12,7 @@ export declare const logicalNot: Unary<boolean, boolean>;
 export type Equal<T> = Binary<T, T, boolean>;
 export declare const strictEqual: <T>(a: T) => (b: T) => boolean;
 export type Scan<I, O> = (input: I) => readonly [O, Scan<I, O>];
-export type StateScan<I, S, O> = (prior: S) => (input: I) => readonly [O, S];
+export type StateScan<I, S, O> = (input: I, prior: S) => readonly [O, S];
 export declare const stateScanToScan: <I, S, O>(op: StateScan<I, S, O>) => (prior: S) => Scan<I, O>;
 export declare const foldToScan: <I, O>(fold: Fold<I, O>) => (prior: O) => Scan<I, O>;
 export type Reduce<T> = Fold<T, T>;

package/{types → fs/types}/function/operator/module.f.js

@@ -3,7 +3,7 @@ export const concat = i => acc => `${acc}${i}`;
 export const logicalNot = v => !v;
 export const strictEqual = (a) => (b) => a === b;
 export const stateScanToScan = (op) => (prior) => i => {
-    const [o, s] = op(prior)(i);
+    const [o, s] = op(i, prior);
     return [o, stateScanToScan(op)(s)];
 };
 export const foldToScan = (fold) => (prior) => i => {

package/{types → fs/types}/list/module.f.js

@@ -146,7 +146,7 @@ const lengthList = list => () => {
 };
 const sum = reduce(addition)(0);
 export const length = input => sum(lengthList(input));
-const entryOperator = index => value => [[index, value], index + 1];
+const entryOperator = (value, index) => [[index, value], index + 1];
 export const entries = input => {
     const o = entryOperator;
     return stateScan(o)(0)(input);

package/fs/types/patricia_trie/module.f.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Streaming Patricia trie for building content-addressed binary trees from sorted leaf sequences.
+ *
+ * @module
+ */
+/** Merges two child identities into a parent. Values first, storage last in both params and return. */
+export type Create<S, T> = (a: T, b: T, storage: S) => readonly [T, S];
+/** A leaf entry: `[sortKey, identity]`. The sort key is used only for XOR comparisons. */
+export type Candidate<T> = readonly [bigint, T];
+export type InternalState<T> = readonly Candidate<T>[];
+/** Streaming state: `[storage, right-spine stack]`. */
+export type State<S, T> = readonly [S, InternalState<T>];
+export type PatriciaTrie<S, T> = {
+    /** Add one leaf. Merges any tightly-coupled stack candidates before pushing. */
+    readonly push: (c: Candidate<T>, state: State<S, T>) => State<S, T>;
+    /**
+     * Drain the stack right-to-left, returning the root identity and final storage.
+     * Returns `undefined` as the root if no leaves were pushed.
+     */
+    readonly end: (state: State<S, T>) => readonly [T | undefined, S];
+};
+/** Creates a Patricia trie whose node merging is delegated to `create`. */
+export declare const patriciaTrie: <S, T>(create: Create<S, T>) => PatriciaTrie<S, T>;
+/** Constructs the initial state from a storage value. */
+export declare const emptyState: <S>(storage: S) => readonly [S, readonly []];

package/fs/types/patricia_trie/module.f.js

@@ -0,0 +1,35 @@
+/**
+ * Streaming Patricia trie for building content-addressed binary trees from sorted leaf sequences.
+ *
+ * @module
+ */
+/** Creates a Patricia trie whose node merging is delegated to `create`. */
+export const patriciaTrie = (create) => ({
+    push: (c, [storage, stack]) => {
+        const [u] = c;
+        while (stack.length >= 2) {
+            const [rLeaf, rHash] = stack[stack.length - 1];
+            const [lLeaf, lHash] = stack[stack.length - 2];
+            if ((lLeaf ^ rLeaf) >= (rLeaf ^ u)) {
+                break;
+            }
+            const [h, newS] = create(lHash, rHash, storage);
+            storage = newS;
+            stack = [...stack.slice(0, -2), [rLeaf, h]];
+        }
+        return [storage, [...stack, c]];
+    },
+    end: ([storage, stack]) => {
+        if (stack.length === 0) {
+            return [undefined, storage];
+        }
+        let h = stack[stack.length - 1][1];
+        for (let i = stack.length - 2; i >= 0; i--) {
+            const lHash = stack[i][1];
+            [h, storage] = create(lHash, h, storage);
+        }
+        return [h, storage];
+    }
+});
+/** Constructs the initial state from a storage value. */
+export const emptyState = (storage) => [storage, []];

package/fs/types/patricia_trie/test.f.d.ts

@@ -0,0 +1,8 @@
+declare const _default: {
+    empty: () => void;
+    singleLeaf: () => void;
+    twoLeaves: () => void;
+    descending: () => void;
+    ascending: () => void;
+};
+export default _default;

package/fs/types/patricia_trie/test.f.js

@@ -0,0 +1,121 @@
+import { assert } from "../../dev/module.f.js";
+import { emptyState, patriciaTrie } from "./module.f.js";
+const combine = (a, b) => a * 1000n + b;
+const create = (a, b, s) => {
+    const h = combine(a, b);
+    return [h, [...s, [a, b, h]]];
+};
+const { push, end } = patriciaTrie(create);
+const leaves = ([, candidates]) => candidates.map(([leaf]) => leaf);
+const runExample = (inputs, expectedLeaves, expectedNodeCounts) => {
+    let state = emptyState([]);
+    for (let i = 0; i < inputs.length; i++) {
+        const x = inputs[i];
+        const prevCount = state[0].length;
+        state = push([x, x], state);
+        const actual = leaves(state);
+        assert(actual.length === expectedLeaves[i].length);
+        for (let j = 0; j < actual.length; j++) {
+            assert(actual[j] === expectedLeaves[i][j]);
+        }
+        const newNodes = state[0].slice(prevCount);
+        assert(newNodes.length === expectedNodeCounts[i]);
+        for (const [l, r, h] of newNodes) {
+            assert(h === combine(l, r));
+        }
+    }
+    const prevCount = state[0].length;
+    const [root, finalStorage] = end(state);
+    const finalNodes = finalStorage.slice(prevCount);
+    assert(finalNodes.length === expectedLeaves[expectedLeaves.length - 1].length - 1);
+    assert(root !== undefined);
+    for (const [l, r, h] of finalNodes) {
+        assert(h === combine(l, r));
+    }
+};
+const empty = () => {
+    const [root, storage] = end(emptyState([]));
+    assert(storage.length === 0);
+    assert(root === undefined);
+};
+const singleLeaf = () => {
+    const state = push([42n, 42n], emptyState([]));
+    assert(state[0].length === 0);
+    assert(leaves(state).length === 1);
+    assert(leaves(state)[0] === 42n);
+    const [root, finalStorage] = end(state);
+    assert(finalStorage.length === 0);
+    assert(root === 42n);
+};
+const twoLeaves = () => {
+    const s1 = push([7n, 7n], emptyState([]));
+    const prevCount = s1[0].length;
+    const s2 = push([3n, 3n], s1);
+    assert(s2[0].slice(prevCount).length === 0);
+    assert(leaves(s2).length === 2);
+    const prevCount2 = s2[0].length;
+    const [root, finalStorage] = end(s2);
+    const finalNodes = finalStorage.slice(prevCount2);
+    assert(finalNodes.length === 1);
+    assert(finalNodes[0][0] === 7n);
+    assert(finalNodes[0][1] === 3n);
+    assert(finalNodes[0][2] === combine(7n, 3n));
+    assert(root === combine(7n, 3n));
+};
+// example.md — descending
+// merges happen at: step 2 (1), 3 (1), 4 (1), 7 (2), 8 (2), A (1), C (2), F (1)
+const descending = () => runExample([
+    249n, 242n, 227n, 200n,
+    179n, 166n, 163n, 159n,
+    119n, 110n, 89n, 73n,
+    39n, 23n, 16n, 14n,
+], [
+    [249n],
+    [249n, 242n],
+    [242n, 227n],
+    [227n, 200n],
+    [200n, 179n],
+    [200n, 179n, 166n],
+    [200n, 179n, 166n, 163n],
+    [200n, 163n, 159n],
+    [159n, 119n],
+    [159n, 119n, 110n],
+    [159n, 110n, 89n],
+    [159n, 110n, 89n, 73n],
+    [159n, 73n, 39n],
+    [159n, 73n, 39n, 23n],
+    [159n, 73n, 39n, 23n, 16n],
+    [159n, 73n, 39n, 16n, 14n],
+], [0, 0, 1, 1, 1, 0, 0, 2, 2, 0, 1, 0, 2, 0, 0, 1]);
+// example.md — ascending (same values, reversed)
+// merges happen at: step 3 (2), 4 (1), 6 (1), 8 (3), B (1), C (2)
+const ascending = () => runExample([
+    14n, 16n, 23n, 39n,
+    73n, 89n, 110n, 119n,
+    159n, 163n, 166n, 179n,
+    200n, 227n, 242n, 249n,
+], [
+    [14n],
+    [14n, 16n],
+    [14n, 16n, 23n],
+    [23n, 39n],
+    [39n, 73n],
+    [39n, 73n, 89n],
+    [39n, 89n, 110n],
+    [39n, 89n, 110n, 119n],
+    [119n, 159n],
+    [119n, 159n, 163n],
+    [119n, 159n, 163n, 166n],
+    [119n, 159n, 166n, 179n],
+    [119n, 179n, 200n],
+    [119n, 179n, 200n, 227n],
+    [119n, 179n, 200n, 227n, 242n],
+    [119n, 179n, 200n, 227n, 242n, 249n],
+], [0, 0, 0, 2, 1, 0, 1, 0, 3, 0, 0, 1, 2, 0, 0, 0]);
+export default {
+    empty,
+    singleLeaf,
+    twoLeaves,
+    descending,
+    ascending
+};

package/fs/types/rtti/parse/module.f.d.ts

@@ -0,0 +1,32 @@
+import { type Type } from '../module.f.ts';
+import { type Result as ValidateResult, type Validate } from '../validate/module.f.ts';
+export type { Path, ValidationError } from '../validate/module.f.ts';
+/** Parse result: either the freshly constructed typed value or a `ValidationError`. */
+export type Result<T extends Type> = ValidateResult<T>;
+/** A function that parses an unknown value into the schema `T`. */
+export type Parse<T extends Type> = Validate<T>;
+/**
+ * Creates a parser function for the given RTTI schema.
+ *
+ * The returned function takes an unknown value and returns either
+ * `['ok', newValue]` containing a freshly constructed value matching the schema,
+ * or `['error', { path, message }]` describing the failure location.
+ *
+ * @param rtti - A schema `Type`: a `Thunk` for tag-based schemas, or a `Const`
+ *   (primitive literal, tuple, or struct) for exact-value schemas.
+ * @returns A `Parse<T>` function.
+ *
+ * @example
+ * ```ts
+ * const p = parse(array(number))
+ * p([1, 2, 3])         // ['ok', [1, 2, 3]]   (a new array)
+ * p([1, 'two'])        // ['error', { path: ['1'], message: 'unexpected value' }]
+ *
+ * // tuples are closed: extra elements are dropped
+ * parse([number, number] as const)([1, 2, 3]) // ['ok', [1, 2]]
+ *
+ * // structs drop undeclared keys
+ * parse({ a: number } as const)({ a: 1, b: 2 }) // ['ok', { a: 1 }]
+ * ```
+ */
+export declare const parse: <T extends Type>(rtti: T) => Parse<T>;