functionalscript 0.43.1 → 0.44.0

package/fjs/protocol/mcp/stdio/proof.f.mjs

@@ -0,0 +1,190 @@
+/**
+ * @import { Unknown } from '../../../media/json/types.ts'
+ * @import { Effect } from '../../../effects/types.ts'
+ * @import { State } from '../../../effects/node/virtual/types.ts'
+ * @import { Id, Response } from '../../json_rpc/types.ts'
+ * @import { Step } from './module.f.mjs'
+ */
+
+import { assertEq } from '../../../asserts/module.f.mjs'
+import { pure } from '../../../effects/module.f.mjs'
+import { emptyState, virtual } from '../../../effects/node/virtual/module.f.mjs'
+import { stringify } from '../../../media/json/module.f.mjs'
+import { utf8 } from '../../../text/module.f.mjs'
+import { fromVec } from '../../../types/uint8array/module.f.mjs'
+import { maxLengthBytes } from '../../../types/bit_vec/module.f.mjs'
+import { sort } from '../../../types/object/module.f.mjs'
+import { internalError, jsonrpc, parseError } from '../../json_rpc/module.f.mjs'
+import { stdioTransport } from './module.f.mjs'
+
+const stringifyJson = stringify(sort)
+
+// Extracts the request `id` (a request has one; a notification does not).
+/** @type {(value: Unknown) => Id | undefined} */
+const idOf = value =>
+    value !== null && typeof value === 'object' && !(value instanceof Array)
+        ? /** @type {{ readonly id?: Id }} */ (value).id
+        : undefined
+
+// A step that mirrors the mcpStep contract closely enough to drive the loop:
+// a message carrying an `id` (a request) gets an echo success response; a
+// message without an `id` (a notification) yields `null` — no reply.
+/** @type {Step<never>} */
+const echoStep = value => {
+    const id = idOf(value)
+    return pure(id === undefined
+        ? null
+        : { jsonrpc, result: { ok: true }, id })
+}
+
+// UTF-8 bytes of `s` as a plain array — the virtual stdin byte stream.
+/** @type {(s: string) => readonly number[]} */
+const toBytes = s => [...fromVec(utf8(s))]
+
+// Run the transport with `step` over `input` fed to stdin one byte at a time;
+// return the final state. `input` is raw text so tests control newline framing.
+/** @type {(step: Step<never>) => (input: string) => State} */
+const runStep = step => input =>
+    virtual({ ...emptyState, stdin: toBytes(input) })(stdioTransport(step))[0]
+
+const run = runStep(echoStep)
+
+/** @type {(id: Id) => string} */
+const okResponse = id =>
+    stringifyJson(/** @type {Unknown} */ ({ jsonrpc, result: { ok: true }, id })) + '\n'
+
+/** @type {string} */
+const parseErrorLine =
+    stringifyJson(/** @type {Unknown} */ ({ jsonrpc, error: parseError, id: null })) + '\n'
+
+/** @type {(id: Id) => string} */
+const internalErrorLine = id =>
+    stringifyJson(/** @type {Unknown} */ ({ jsonrpc, error: internalError, id })) + '\n'
+
+/** @type {(id: number) => string} */
+const ping = id => `{"jsonrpc":"2.0","method":"ping","id":${id}}`
+
+// One byte past `maxLengthBytes` on its own; embedded in a response envelope
+// it stays comfortably over the limit despite the surrounding JSON overhead.
+const oversizedString = 'a'.repeat(Number(maxLengthBytes) + 1)
+
+const notification = '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+
+export const proof = {
+    // EOF on the very first read: clean shutdown, nothing written, no further reads.
+    eofImmediately: () => {
+        const state = run('')
+        assertEq(state.stdout, '')
+        assertEq(state.stdin.length, 0)
+    },
+
+    // A newline-terminated request is parsed, dispatched, and its response
+    // written; stdin is fully drained before the terminating EOF.
+    requestWritesResponse: () => {
+        const state = run(ping(1) + '\n')
+        assertEq(state.stdout, okResponse(1))
+        assertEq(state.stdin.length, 0)
+    },
+
+    // A final line lacking a trailing newline is still flushed and dispatched
+    // (covers `readLine`'s EOF-with-buffered-bytes branch).
+    requestWithoutTrailingNewline: () => {
+        const state = run(ping(2))
+        assertEq(state.stdout, okResponse(2))
+    },
+
+    // A notification (no `id`) yields a `null` step result → nothing is written.
+    notificationWritesNothing: () => {
+        const state = run(notification + '\n')
+        assertEq(state.stdout, '')
+    },
+
+    // A malformed JSON line produces a JSON-RPC parse-error response (-32700),
+    // not a silent discard.
+    malformedJsonWritesParseError: () => {
+        const state = run('not json\n')
+        assertEq(state.stdout, parseErrorLine)
+    },
+
+    // A request that is not strict JSON (trailing comma) must be rejected with
+    // a parse error, never dispatched to the step.
+    trailingCommaWritesParseError: () => {
+        const state = run('{"jsonrpc":"2.0","method":"ping","id":1,}\n')
+        assertEq(state.stdout, parseErrorLine)
+    },
+
+    // A response with an optional field explicitly `undefined` serializes like
+    // JSON.stringify — the field is omitted, not a thrown TypeError that would
+    // abort the loop.
+    undefinedFieldOmitted: () => {
+        /** @type {Step<never>} */
+        const step = value => {
+            const id = idOf(value)
+            return pure(id === undefined
+                ? null
+                : /** @type {Response} */ (/** @type {unknown} */ ({ jsonrpc, result: { ok: true, nextCursor: undefined }, id })))
+        }
+        const state = runStep(step)(ping(1) + '\n')
+        assertEq(state.stdout, okResponse(1))
+    },
+
+    // A response that would exceed `maxLengthBytes` once UTF-8 encoded cannot
+    // be written as a single bit vector (`tryUtf8` reports overflow); the loop
+    // writes a JSON-RPC internal-error response — carrying the original
+    // request's `id`, not `null` — instead of throwing or silently dropping
+    // the reply.
+    oversizedResponseWritesInternalError: () => {
+        /** @type {Step<never>} */
+        const step = value => {
+            const id = idOf(value)
+            return pure(id === undefined
+                ? null
+                : { jsonrpc, result: { big: oversizedString }, id })
+        }
+        const state = runStep(step)(ping(1) + '\n')
+        assertEq(state.stdout, internalErrorLine(1))
+    },
+    // The loop recovers from the oversized-response error and keeps draining
+    // stdin: a well-behaved request on the next line still gets its normal
+    // reply.
+    loopContinuesAfterOversizedResponse: () => {
+        /** @type {Step<never>} */
+        const step = value => {
+            const id = idOf(value)
+            return pure(id === undefined
+                ? null
+                : id === 1
+                    ? { jsonrpc, result: { big: oversizedString }, id }
+                    : { jsonrpc, result: { ok: true }, id })
+        }
+        const state = runStep(step)([ping(1), ping(2)].join('\n'))
+        assertEq(state.stdout, internalErrorLine(1) + okResponse(2))
+        assertEq(state.stdin.length, 0)
+    },
+
+    // When even the `id`-preserving internal-error fallback would overflow —
+    // because the `id` itself is the oversized part, not just `result` — the
+    // loop falls back once more to a fixed `id: null` internal-error, the only
+    // shape in this transport guaranteed to always fit. Without this second
+    // fallback tier the request would get no response line at all.
+    oversizedIdFallsBackToNullId: () => {
+        /** @type {Step<never>} */
+        const step = value => {
+            const id = idOf(value)
+            return pure(id === undefined
+                ? null
+                : { jsonrpc, result: { ok: true }, id: oversizedString })
+        }
+        const state = runStep(step)(ping(1) + '\n')
+        assertEq(state.stdout, internalErrorLine(null))
+    },
+
+    // A multi-line session interleaving all cases: request, notification, and
+    // malformed line, ending with an unterminated request. Order is preserved
+    // and the notification contributes nothing.
+    multipleLines: () => {
+        const state = run([ping(1), notification, 'not json', ping(2)].join('\n'))
+        assertEq(state.stdout, okResponse(1) + parseErrorLine + okResponse(2))
+        assertEq(state.stdin.length, 0)
+    },
+}

package/fjs/protocol/mcp/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Type-level API for `fjs/protocol/mcp/module.f.mjs`: the MCP message
+ * schemas' derived types, plus the `McpHandlers`/`ToolEntry`/`Handle`/
+ * session-state shapes `mcpStep` is built from.
+ *
+ * @module
+ */
+import type { Ts } from '../../types/rtti/ts/types.ts';
+import type { Unknown } from '../../media/json/types.ts';
+import type { Operation, Effect } from '../../effects/types.ts';
+import type { Type } from '../../types/rtti/types.ts';
+import type { Response } from '../json_rpc/types.ts';
+import type { implementation, serverCapabilities, initializeParams, initializeResult, textContent, blobResource, embeddedResource, contentItem, tool, toolsListParams, toolsListResult, toolsCallParams, toolsCallResult } from './module.f.mjs';
+export type Implementation = Ts<typeof implementation>;
+export type ServerCapabilities = Ts<typeof serverCapabilities>;
+export type InitializeParams = Ts<typeof initializeParams>;
+export type InitializeResult = Ts<typeof initializeResult>;
+export type TextContent = Ts<typeof textContent>;
+export type BlobResource = Ts<typeof blobResource>;
+export type EmbeddedResource = Ts<typeof embeddedResource>;
+export type ContentItem = Ts<typeof contentItem>;
+export type Tool = Ts<typeof tool>;
+export type ToolsListParams = Ts<typeof toolsListParams>;
+export type ToolsListResult = Ts<typeof toolsListResult>;
+export type ToolsCallParams = Ts<typeof toolsCallParams>;
+export type ToolsCallResult = Ts<typeof toolsCallResult>;
+/** Per-method handlers for a hello-world MCP tool server. */
+export type McpHandlers<O extends Operation> = {
+    readonly toolsList: (params: ToolsListParams) => Effect<O, ToolsListResult>;
+    readonly toolsCall: (params: ToolsCallParams) => Effect<O, ToolsCallResult>;
+};
+/**
+ * A single declarative tool entry combining metadata, input schema, and type-safe handler.
+ *
+ * The handler receives pre-validated arguments of type `Ts<inputRtti>`, eliminating the need
+ * for manual validation or type casting. All validation is encapsulated in the entry.
+ */
+export type ToolEntry<O extends Operation> = {
+    readonly name: string;
+    readonly description: string;
+    readonly inputRtti: Type;
+    readonly handle: (args: Unknown) => Effect<O, ToolsCallResult>;
+};
+/** Top-level handler: maps a raw JSON value to a JSON-RPC response (or `null` for notifications). */
+export type Handle<O extends Operation> = (value: Unknown) => Effect<O, Response | null>;
+/** State carried before the peer sends `initialize`. */
+export type Uninitialized = readonly ['uninitialized'];
+/** State after `initialize` response was sent but before `notifications/initialized` arrives. */
+export type Initializing = readonly ['initializing'];
+/** State carried after a successful `initialize` exchange. */
+export type InitializedState = true;
+/** The three phases of an MCP session. */
+export type McpSessionState = Uninitialized | Initializing | readonly ['initialized', InitializedState];
+/** Static configuration supplied by the server implementer. */
+export type McpConfig = {
+    readonly serverInfo: Implementation;
+    readonly capabilities: ServerCapabilities;
+    readonly protocolVersion: string;
+};

package/fjs/protocol/mcp/types.js

@@ -0,0 +1,8 @@
+/**
+ * Type-level API for `fjs/protocol/mcp/module.f.mjs`: the MCP message
+ * schemas' derived types, plus the `McpHandlers`/`ToolEntry`/`Handle`/
+ * session-state shapes `mcpStep` is built from.
+ *
+ * @module
+ */
+export {};

package/fjs/sul/id/module.f.d.mts

@@ -0,0 +1,37 @@
+/**
+ * 256-bit content-addressed identifiers for SUL values.
+ * Every identifier is one of three variants: a level-3 literal (inline), a raw bit vector (inline),
+ * or a SHA2-based hash, selected automatically by `compress` based on size and input type.
+ * See `./types.ts` for the `Id` type.
+ *
+ * @module
+ */
+import type { Vec } from '../../types/bit_vec/types.ts';
+import type { Id } from './types.ts';
+/**
+ * Note: no need to add a prefix.
+ *
+ * @type {(v: bigint) => Id}
+ */
+export declare const level3Id: (v: bigint) => Id;
+/**
+ * Note: length(symbol) <= 253n
+ *
+ * @param {Vec} symbol
+ * @returns {Id}
+ */
+export declare const rawId: (symbol: Vec) => Id;
+/** @type {(v: Id) => boolean} */
+export declare const isRaw: (v: Id) => boolean;
+/** @type {(v: Id) => boolean} */
+export declare const isHash: (v: Id) => boolean;
+/**
+ * Note: we don't need to remove the prefix bits from the hash because
+ * the prefix equals the prefix mask (`1n << 0xFFn`).
+ *
+ * @param {bigint} hash
+ * @returns {Id}
+ */
+export declare const hashId: (hash: bigint) => Id;
+/** @type {(a: Id, b: Id) => Id} */
+export declare const compress: (a: Id, b: Id) => Id;

package/fjs/sul/id/module.f.mjs

@@ -0,0 +1,143 @@
+/**
+ * 256-bit content-addressed identifiers for SUL values.
+ * Every identifier is one of three variants: a level-3 literal (inline), a raw bit vector (inline),
+ * or a SHA2-based hash, selected automatically by `compress` based on size and input type.
+ * See `./types.ts` for the `Id` type.
+ *
+ * @module
+ */
+
+import { toArray } from '../../types/list/module.f.mjs'
+/** @import { Vec } from '../../types/bit_vec/types.ts' */
+import { length, msb, uint, uintChunkList, unpack, vec } from '../../types/bit_vec/module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+import { utf8 } from '../../text/module.f.mjs'
+/** @import { Point2D } from '../../crypto/secp/types.ts' */
+import { secp256r1 } from '../../crypto/secp/module.f.mjs'
+/** @import { V8 } from '../../crypto/sha2/types.ts' */
+import { base32 } from '../../crypto/sha2/module.f.mjs'
+import { literal3ToVec } from '../level/literal/module.f.mjs'
+import { log2 } from '../../types/bigint/module.f.mjs'
+import { asBase, asNominal } from '../../types/nominal/module.f.mjs'
+/** @import { Id } from './types.ts' */
+
+// 32 bytes = 256 bits.
+//
+//              0               1
+//              0123456789ABCDEF0123456789ABCDEF
+const ivSeed = "Synthetic Universal Language 001"
+
+const utf8IvSeed = utf8(ivSeed)
+
+const c = secp256r1
+
+/** @type {bigint} */
+const ivUint = /** @type {Point2D} */ (c.mul(uint(utf8IvSeed))(c.g))[0]
+
+// 64 hex = 256 bits = 32 bytes:
+assertEq(
+    ivUint,
+//    0                 1                 2                 3
+//    01234567_89ABCDEF_01234567_89ABCDEF_01234567_89ABCDEF_01234567_89ABCDEF
+    0x325d5666_573eb118_f32191de_20d17f64_33392ba3_291ae46c_1474a5ed_a5383f25n
+)
+
+const iv = /** @type {V8} */ (toArray(uintChunkList(msb)(32n)({ length: 256n, uint: ivUint })))
+
+assertEq(iv.length, 8)
+
+/**
+ * Note: no need to add a prefix.
+ *
+ * @type {(v: bigint) => Id}
+ */
+export const level3Id =
+    asNominal
+
+const rawPrefixOffset = 0xFEn
+
+const rawPrefix = 1n << rawPrefixOffset
+
+assertEq(
+    rawPrefix,
+//    0                 1                 2                 3
+//    01234567_89ABCDEF_01234567_89ABCDEF_01234567_89ABCDEF_01234567_89ABCDEF
+    0x40000000_00000000_00000000_00000000_00000000_00000000_00000000_00000000n
+)
+
+// 253
+const rawLenMax = 0xFDn
+
+/**
+ * Note: length(symbol) <= 253n
+ *
+ * @param {Vec} symbol
+ * @returns {Id}
+ */
+export const rawId = symbol => {
+    const { length, uint } = unpack(symbol)
+    return asNominal(rawPrefix | uint | (1n << length))
+}
+
+/** @type {(v: Id) => boolean} */
+export const isRaw = v =>
+    asBase(v) >> rawPrefixOffset === 1n
+
+/** @type {(a: Id) => Vec} */
+const toRaw = a => {
+    if (!isRaw(a)) {
+        return literal3ToVec(asBase(a))
+    }
+    const raw = asBase(a) ^ rawPrefix
+    const len = log2(raw)
+    return vec(len)(raw ^ (1n << len))
+}
+
+const hashPrefixOffset = 0xFFn
+
+const hashPrefix = 1n << hashPrefixOffset
+
+assertEq(
+    hashPrefix,
+//    0                 1                 2                 3
+//    01234567_89ABCDEF_01234567_89ABCDEF_01234567_89ABCDEF_01234567_89ABCDEF
+    0x80000000_00000000_00000000_00000000_00000000_00000000_00000000_00000000n
+)
+
+/** @type {(v: Id) => boolean} */
+export const isHash = v =>
+    asBase(v) >> hashPrefixOffset === 1n
+
+/**
+ * Note: we don't need to remove the prefix bits from the hash because
+ * the prefix equals the prefix mask (`1n << 0xFFn`).
+ *
+ * @param {bigint} hash
+ * @returns {Id}
+ */
+export const hashId = hash =>
+    asNominal(hashPrefix | hash)
+
+const hash2 = base32.compress(iv)
+
+const vecX20 = vec(0x20n)
+
+const { concat, listToVec } = msb
+
+/** @type {(a: Id, b: Id) => Id} */
+const hashMerge = (a, b) =>
+    hashId(uint(listToVec(hash2((asBase(a) << 0x100n) | asBase(b)).map(vecX20))))
+
+/** @type {(a: Id, b: Id) => Id} */
+export const compress = (a, b) => {
+    if (isHash(a) || isHash(b)) {
+        return hashMerge(a, b)
+    }
+    const ra = toRaw(a)
+    const rb = toRaw(b)
+    const len = length(ra) + length(rb)
+    if (len > rawLenMax) {
+        return hashMerge(a, b)
+    }
+    return rawId(concat(ra)(rb))
+}

package/fjs/sul/id/proof.f.mjs

@@ -0,0 +1,72 @@
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { mask } from '../../types/bigint/module.f.mjs'
+import { vec } from '../../types/bit_vec/module.f.mjs'
+import { compress, hashId, isHash, isRaw, level3Id, rawId } from './module.f.mjs'
+import { asBase } from '../../types/nominal/module.f.mjs'
+
+// literal3ToVec bit patterns for symbols used below:
+//   0  → vec(8n)(0n)     4  → vec(8n)(3n)
+//   1  → vec(8n)(1n)     10 → vec(8n)(5n)
+//                        128 → vec(8n)(15n)
+
+// Two 127-bit raw payloads overflow the 253-bit inline limit, producing a hash value.
+const rawX7F = rawId(vec(0x7Fn)(mask(0x7Fn)))
+const overflowHash = compress(rawX7F, rawX7F)
+
+const hFF = hashId(mask(0xFFn))
+const hFE = hashId(mask(0xFFn) - 1n)
+
+assertEq(asBase(level3Id(0n)), 0n)
+assertEq(asBase(hashId(0n)), 1n << 0xFFn)
+assertEq(asBase(hFF), mask(0x100n))
+
+export const proof = {
+    // Two level-3 literals whose combined bit vectors fit inline (≤ 253 bits)
+    inline_00_00: () => assertEq(compress(level3Id(0x00n), level3Id(0x00n)), rawId(vec(16n)(0x0000n))),
+    inline_00_01: () => assertEq(compress(level3Id(0x00n), level3Id(0x01n)), rawId(vec(16n)(0x0001n))),
+    inline_01_00: () => assertEq(compress(level3Id(0x01n), level3Id(0x00n)), rawId(vec(16n)(0x0100n))),
+    inline_01_01: () => assertEq(compress(level3Id(0x01n), level3Id(0x01n)), rawId(vec(16n)(0x0101n))),
+    inline_00_04: () => assertEq(compress(level3Id(0x00n), level3Id(0x04n)), rawId(vec(16n)(0x0003n))),
+    inline_04_00: () => assertEq(compress(level3Id(0x04n), level3Id(0x00n)), rawId(vec(16n)(0x0300n))),
+    inline_0A_80: () => assertEq(compress(level3Id(0x0An), level3Id(0x80n)), rawId(vec(16n)(0x050Fn))),
+
+    // Inline outputs are raw-encoded (bit 254 set, bit 255 not set)
+    inline_is_raw: () => assert(isRaw(compress(level3Id(0x00n), level3Id(0x00n)))),
+
+    // Non-commutativity: argument order is preserved in concatenation
+    non_commutative: () => {
+        assert(compress(level3Id(0n), level3Id(1n)) !== compress(level3Id(1n), level3Id(0n)), compress(level3Id(0n), level3Id(1n)))
+    },
+
+    // Overflow: two 127-bit raw payloads sum to 254 bits, exceeding the 253-bit inline limit
+    overflow_is_hash: () => assert(isHash(overflowHash)),
+
+    // Hash input: either argument being a hash always triggers SHA2-based merge
+    hash_left_is_hash:  () => assert(isHash(compress(overflowHash, level3Id(0n)))),
+    hash_right_is_hash: () => assert(isHash(compress(level3Id(0n), overflowHash))),
+    hash_non_commutative: () => {
+        assert(compress(overflowHash, level3Id(0n)) !== compress(level3Id(0n), overflowHash), compress(overflowHash, level3Id(0n)))
+    },
+
+    // High-bit sensitivity: prefix bit of `a` is included in the SHA2 upper half
+    hash_merge_a_high_bits: () => {
+        assert(compress(hashId(0n), hashId(0n)) !== compress(level3Id(0n), hashId(0n)), compress(hashId(0n), hashId(0n)))
+    },
+    // High-bit sensitivity: prefix bit of `b` is included in the SHA2 lower half
+    hash_merge_b_high_bits: () => {
+        assert(compress(hashId(0n), hashId(0n)) !== compress(hashId(0n), level3Id(0n)), compress(hashId(0n), hashId(0n)))
+    },
+
+    // Shift correctness: changing a bit in `a` (upper 256 bits of SHA2 input) changes result
+    hash_merge_a_sensitivity: () => {
+        assert(compress(hFF, hFF) !== compress(hFE, hFF), compress(hFF, hFF))
+    },
+    // Shift correctness: changing a bit in `b` (lower 256 bits of SHA2 input) changes result
+    hash_merge_b_sensitivity: () => {
+        assert(compress(hFF, hFF) !== compress(hFF, hFE), compress(hFF, hFF))
+    },
+    // Shift correctness: same bit-flip in `a` vs `b` lands at different SHA2 input positions
+    hash_merge_shift: () => {
+        assert(compress(hFE, hFF) !== compress(hFF, hFE), compress(hFE, hFF))
+    },
+}

package/fjs/sul/id/types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Type-level API for SUL identifiers.
+ *
+ * @module
+ */
+import type { Nominal } from '../../types/nominal/types.ts';
+/** A 256-bit SUL identifier. One of three variants: level-3 literal, raw bit vector, or SHA2 hash. */
+export type Id = Nominal<'sul/id', '6f5f6da053a6ac70e9687d42b7a09e925c3be21027f55beb2cba3040bf3d5b71', bigint>;

package/fjs/sul/id/types.js

@@ -0,0 +1,6 @@
+/**
+ * Type-level API for SUL identifiers.
+ *
+ * @module
+ */
+export {};

package/fjs/sul/level/hash/module.f.d.mts

@@ -0,0 +1,37 @@
+/**
+ * Streaming encoder for SUL hash-level symbols using a Patricia trie and 256-bit content-addressed hashes.
+ * See `./types.ts` for the `Add`/`EncodeState` type-level API.
+ *
+ * @module
+ */
+import type { Id } from '../../id/types.ts';
+import type { Add, EncodeState } from './types.ts';
+/** @import { Add, EncodeState } from './types.ts' */
+/**
+ * Returns a streaming encoder for hash-level symbols.
+ *
+ * The returned step function processes one level-3 symbol at a time.
+ * It returns `undefined` while the strictly-decreasing prefix is still
+ * being accumulated. When the terminating symbol `t` arrives (`t >= last`),
+ * the word `[s0 > ... > sk, t]` is finalised:
+ *
+ * 1. The Patricia trie of `[s0, ..., sk]` is collapsed to a root hash.
+ * 2. The root is merged with `t` via `compress`, producing the output symbol.
+ * 3. State is reset to an empty stack (storage is preserved).
+ *
+ * `add` is called once for every `compress` call. `isSymbol` is `false` for
+ * Patricia trie internal merges and `true` for the terminal `compress(root, t)`.
+ */
+export declare const encode: <S>(
+/**
+ * @template S
+ * @param {Add<S>} add
+ * @returns {(symbol: Id, state: EncodeState<S>) => readonly [Id | undefined, EncodeState<S>]}
+ */
+add: Add<S>) => (symbol: Id, state: EncodeState<S>) => readonly [Id | undefined, EncodeState<S>];
+/**
+ * Returns the initial encoding state wrapping `storage`.
+ *
+ * @type {<S>(storage: S) => EncodeState<S>}
+ */
+export declare const emptyEncodeState: <S>(storage: S) => EncodeState<S>;

package/fjs/sul/level/hash/module.f.mjs

@@ -0,0 +1,61 @@
+/**
+ * Streaming encoder for SUL hash-level symbols using a Patricia trie and 256-bit content-addressed hashes.
+ * See `./types.ts` for the `Add`/`EncodeState` type-level API.
+ *
+ * @module
+ */
+
+/** @import { Create } from '../../../types/patricia_trie/types.ts' */
+import { emptyState, patriciaTrie } from '../../../types/patricia_trie/module.f.mjs'
+import { compress } from '../../id/module.f.mjs'
+/** @import { Id } from '../../id/types.ts' */
+import { asBase } from '../../../types/nominal/module.f.mjs'
+/** @import { Add, EncodeState } from './types.ts' */
+
+/**
+ * Returns a streaming encoder for hash-level symbols.
+ *
+ * The returned step function processes one level-3 symbol at a time.
+ * It returns `undefined` while the strictly-decreasing prefix is still
+ * being accumulated. When the terminating symbol `t` arrives (`t >= last`),
+ * the word `[s0 > ... > sk, t]` is finalised:
+ *
+ * 1. The Patricia trie of `[s0, ..., sk]` is collapsed to a root hash.
+ * 2. The root is merged with `t` via `compress`, producing the output symbol.
+ * 3. State is reset to an empty stack (storage is preserved).
+ *
+ * `add` is called once for every `compress` call. `isSymbol` is `false` for
+ * Patricia trie internal merges and `true` for the terminal `compress(root, t)`.
+ */
+export const encode =
+    /**
+     * @template S
+     * @param {Add<S>} add
+     * @returns {(symbol: Id, state: EncodeState<S>) => readonly [Id | undefined, EncodeState<S>]}
+     */
+    add => {
+        /** @type {(isSymbol: boolean) => Create<S, Id>} */
+        const create = isSymbol => (a, b, s) => {
+            const m = compress(a, b)
+            return [m, add(a, b, m, isSymbol, s)]
+        }
+        const { push, end } = patriciaTrie(create(false))
+        const rootCreate = create(true)
+        return (symbol, state) => {
+            const [, stack] = state
+            const last = stack.at(-1)
+            if (last === undefined || last[0] > asBase(symbol)) {
+                return [undefined, push([asBase(symbol), symbol], state)]
+            }
+            const [root1, storage1] = end(state)
+            const [root2, storage2] = rootCreate(/** @type {Id} */ (root1), symbol, storage1)
+            return [root2, [storage2, []]]
+        }
+    }
+
+/**
+ * Returns the initial encoding state wrapping `storage`.
+ *
+ * @type {<S>(storage: S) => EncodeState<S>}
+ */
+export const emptyEncodeState = emptyState

package/fjs/sul/level/hash/proof.f.d.mts

@@ -0,0 +1,15 @@
+import type { Id } from '../../id/types.ts';
+export type _NodeList = readonly (readonly [Id, Id, Id, boolean])[];
+export declare const proof: {
+    min_equal: () => void;
+    min_greater: () => void;
+    intermediate_undefined: () => void;
+    three_symbol: () => void;
+    output_is_last_add: () => void;
+    state_reset: () => void;
+    storage_accumulates: () => void;
+    two_words: () => void;
+    non_commutative: () => void;
+    isSymbol_terminal_only: () => void;
+    isSymbol_min_word: () => void;
+};