functionalscript 0.44.0 → 0.46.0

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

@@ -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/protocol/mcp/module.f.mjs` — in the
+ * `(value) => Effect<O, Response | null, never>` from `fjs/protocol/mcp/module.f.mjs` — 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,26 +29,20 @@
  *
  * @module
  *
- * @import { Unknown } from '../../../media/json/types.ts'
- * @import { Effect, Operation } from '../../../effects/types.ts'
- * @import { IoResult, Read, Write } from '../../../effects/node/types.ts'
+ * @import { Operation } from '../../../effects/types.ts'
+ * @import { IoChannel, Read, Write } from '../../../effects/node/types.ts'
+ * @import { Effect } from '../../../effects/types.ts'
  * @import { Response } from '../../json_rpc/types.ts'
+ * @import { Step } from './types.ts'
  */
 
-import { pure, step } from '../../../effects/module.f.mjs'
-import { readLine, write } from '../../../effects/node/module.f.mjs'
+import { pureError, pureOk, resultStep, step } from '../../../effects/module.f.mjs'
+import { ioError, readLine, write } from '../../../effects/node/module.f.mjs'
 import { tryUtf8 } from '../../../text/module.f.mjs'
 import { parse, stringify } from '../../../media/json/module.f.mjs'
 import { sort } from '../../../types/object/module.f.mjs'
 import { internalError, jsonrpc, parseError } from '../../json_rpc/module.f.mjs'
-import { error, ok } from '../../../types/result/module.f.mjs'
-
-/**
- * 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)`.
- * @template {Operation} O
- * @typedef {(value: Unknown) => Effect<O, Response | null>} Step
- */
+import { error } from '../../../types/result/module.f.mjs'
 
 const stringifyJson = stringify(sort)
 
@@ -62,16 +56,13 @@ const parseErrorResponse = { jsonrpc, error: parseError, id: null }
 const internalErrorResponse = id => ({ jsonrpc, error: internalError, id })
 
 /** Encodes a response as a newline-terminated UTF-8 line and writes it to `stdout`.
- * @type {(resp: Response) => Effect<Write, IoResult<void>>}
+ * @type {(resp: Response) => Effect<Write, void, IoChannel>}
  */
 const writeResponse = resp => {
     const v = tryUtf8(stringifyJson(resp) + '\n')
     return v === null
-        ? pure(error(undefined))
-        : step(
-            write('stdout', v),
-            () => pure(ok(undefined)),
-        )
+        ? pureError(ioError({ message: 'response does not encode as UTF-8' }))
+        : write('stdout', v)
 }
 
 /**
@@ -80,35 +71,48 @@ const writeResponse = resp => {
  * Recurses after each handled line; terminates (resolving to `void`) when
  * `readLine` reports EOF.
  *
+ * A transport that cannot read its own input has no fallback to choose, but it
+ * does not have to decide that here: the failure ends the loop and travels to
+ * whoever started the server, which for `fjs mcp` is a message on `stderr` and
+ * exit `1`. EOF is not that — `readLine` answers `ok(null)`, the loop ends, and
+ * the server has done its job.
+ *
  * @template {Operation} O
  * @param {Step<O>} handler
- * @returns {Effect<Read | Write | O, void>}
+ * @returns {Effect<Read | Write | O, void, IoChannel>}
  */
 export const stdioTransport = handler =>
     step(
         readLine('stdin'),
         line => line === null
-            ? pure(undefined)
+            ? pureOk(undefined)
             : handleLine(handler)(line),
     )
 
 /**
  * @template {Operation} O
  * @param {Step<O>} handler
- * @returns {(line: string) => Effect<Read | Write | O, void>}
+ * @returns {(line: string) => Effect<Read | Write | O, void, IoChannel>}
  */
 const handleLine = handler => line => {
     const [t, value] = parse(line)
-    return step(
+    return resultStep(
         t === 'error'
             ? writeResponse(parseErrorResponse)
+            // `step`, because a `Handle` answers `Effect<O, Response | null,
+            // never>` — it absorbs its own failures into the response body — so
+            // the continuation receives the response itself and there is no
+            // error branch left for this chain to consider.
             : step(
                 handler(value),
                 resp => resp === null
-                    ? pure(undefined)
-                    : step(
+                    ? pureOk(undefined)
+                    // `resultStep` from here down: each write's *failure* is
+                    // what selects the next, smaller fallback, so these are the
+                    // both-branches case rather than a chain to short-circuit.
+                    : resultStep(
                         writeResponse(resp),
-                        ([t2]) => t2 === 'error'
+                        r2 => r2[0] === '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
@@ -116,17 +120,19 @@ const handleLine = handler => 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.
-                            ? step(
+                            ? resultStep(
                                 writeResponse(internalErrorResponse(resp.id)),
-                                ([t3]) => t3 === 'error'
-                                    ? step(
+                                r3 => r3[0] === 'error'
+                                    ? resultStep(
                                         writeResponse(internalErrorResponse(null)),
-                                        () => pure(undefined),
+                                        () => pureOk(undefined),
                                     )
-                                    : pure(undefined)
+                                    : pureOk(undefined)
                             )
-                            : pure(undefined)),
+                            : pureOk(undefined)),
             ),
+        // The loop continues whatever the line's own handling answered: a
+        // transport that could not write one response still serves the next.
         () => stdioTransport(handler),
     )
 }

package/fjs/protocol/mcp/stdio/proof.f.d.mts

@@ -1,11 +1,13 @@
 /**
  * @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 { Id } from '../../json_rpc/types.ts'
+ * @import { Step } from './types.ts'
+ * @import { Read, Write } from '../../../effects/node/types.ts'
  */
 export declare const proof: {
+    readFailurePropagates: () => void;
+    readFailureAfterALinePropagates: () => void;
     eofImmediately: () => void;
     requestWritesResponse: () => void;
     requestWithoutTrailingNewline: () => void;

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

@@ -1,13 +1,14 @@
 /**
  * @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 { Id } from '../../json_rpc/types.ts'
+ * @import { Step } from './types.ts'
+ * @import { Read, Write } from '../../../effects/node/types.ts'
  */
 
-import { assertEq } from '../../../asserts/module.f.mjs'
+import { assert, assertEq } from '../../../asserts/module.f.mjs'
 import { pure } from '../../../effects/module.f.mjs'
+import { pureOk } 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'
@@ -16,6 +17,8 @@ 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'
+import { run as mockRun } from '../../../effects/mock/module.f.mjs'
+import { error, ok } from '../../../types/result/module.f.mjs'
 
 const stringifyJson = stringify(sort)
 
@@ -32,7 +35,7 @@ const idOf = value =>
 /** @type {Step<never>} */
 const echoStep = value => {
     const id = idOf(value)
-    return pure(id === undefined
+    return pureOk(id === undefined
         ? null
         : { jsonrpc, result: { ok: true }, id })
 }
@@ -51,15 +54,15 @@ const run = runStep(echoStep)
 
 /** @type {(id: Id) => string} */
 const okResponse = id =>
-    stringifyJson(/** @type {Unknown} */ ({ jsonrpc, result: { ok: true }, id })) + '\n'
+    stringifyJson({ jsonrpc, result: { ok: true }, id }) + '\n'
 
 /** @type {string} */
 const parseErrorLine =
-    stringifyJson(/** @type {Unknown} */ ({ jsonrpc, error: parseError, id: null })) + '\n'
+    stringifyJson({ jsonrpc, error: parseError, id: null }) + '\n'
 
 /** @type {(id: Id) => string} */
 const internalErrorLine = id =>
-    stringifyJson(/** @type {Unknown} */ ({ jsonrpc, error: internalError, id })) + '\n'
+    stringifyJson({ jsonrpc, error: internalError, id }) + '\n'
 
 /** @type {(id: number) => string} */
 const ping = id => `{"jsonrpc":"2.0","method":"ping","id":${id}}`
@@ -71,6 +74,36 @@ const oversizedString = 'a'.repeat(Number(maxLengthBytes) + 1)
 const notification = '{"jsonrpc":"2.0","method":"notifications/initialized"}'
 
 export const proof = {
+    // A stdin that cannot be read ends the loop and hands the failure back,
+    // where it used to panic. EOF is not this case: that is `ok(null)`, and
+    // `eofImmediately` above pins it as the clean shutdown it should be.
+    readFailurePropagates: () => {
+        const runner = mockRun(/** @type {Parameters<typeof mockRun<Read | Write, undefined>>[0]} */ ({
+            read: () => (/** @type {undefined} */ s) => [s, error(/** @type {const} */ (['notImplemented', 'read']))],
+            write: () => (/** @type {undefined} */ s) => [s, ok(undefined)],
+        }))
+        const [, result] = runner(undefined)(stdioTransport(echoStep))
+        assert(result[0] === 'error', result)
+    },
+
+    // The same, one turn of the loop later. The proof above only reaches the
+    // *first* read, so a tail that swallowed the failure on recursion would
+    // still pass it: here stdin yields one complete line, the handler answers
+    // it, and the read after that fails.
+    readFailureAfterALinePropagates: () => {
+        const bytes = toBytes(ping(1) + '\n')
+        const runner = mockRun(/** @type {Parameters<typeof mockRun<Read | Write, readonly number[]>>[0]} */ ({
+            read: () => (/** @type {readonly number[]} */ s) =>
+                s.length === 0
+                    ? [s, error(/** @type {const} */ (['notImplemented', 'read']))]
+                    : [s.slice(1), ok(s[0])],
+            write: () => (/** @type {readonly number[]} */ s) => [s, ok(undefined)],
+        }))
+        const [rest, result] = runner(bytes)(stdioTransport(echoStep))
+        assertEq(rest.length, 0, 'expected the line to be consumed before the failure')
+        assert(result[0] === 'error', result)
+    },
+
     // EOF on the very first read: clean shutdown, nothing written, no further reads.
     eofImmediately: () => {
         const state = run('')
@@ -120,9 +153,9 @@ export const proof = {
         /** @type {Step<never>} */
         const step = value => {
             const id = idOf(value)
-            return pure(id === undefined
+            return pureOk(id === undefined
                 ? null
-                : /** @type {Response} */ (/** @type {unknown} */ ({ jsonrpc, result: { ok: true, nextCursor: undefined }, id })))
+                : { jsonrpc, result: { ok: true, nextCursor: undefined }, id })
         }
         const state = runStep(step)(ping(1) + '\n')
         assertEq(state.stdout, okResponse(1))
@@ -137,7 +170,7 @@ export const proof = {
         /** @type {Step<never>} */
         const step = value => {
             const id = idOf(value)
-            return pure(id === undefined
+            return pureOk(id === undefined
                 ? null
                 : { jsonrpc, result: { big: oversizedString }, id })
         }
@@ -151,7 +184,7 @@ export const proof = {
         /** @type {Step<never>} */
         const step = value => {
             const id = idOf(value)
-            return pure(id === undefined
+            return pureOk(id === undefined
                 ? null
                 : id === 1
                     ? { jsonrpc, result: { big: oversizedString }, id }
@@ -171,7 +204,7 @@ export const proof = {
         /** @type {Step<never>} */
         const step = value => {
             const id = idOf(value)
-            return pure(id === undefined
+            return pureOk(id === undefined
                 ? null
                 : { jsonrpc, result: { ok: true }, id: oversizedString })
         }

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

@@ -0,0 +1,14 @@
+/**
+ * Types for the stdio transport of JSON-RPC / MCP servers.
+ *
+ * @module
+ */
+import type { Unknown } from '../../../media/json/types.ts';
+import type { Effect, Operation } from '../../../effects/types.ts';
+import type { Response } from '../../json_rpc/types.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, never>;

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

@@ -7,7 +7,7 @@
  */
 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 { Effect, Operation } 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';
@@ -26,8 +26,8 @@ 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>;
+    readonly toolsList: (params: ToolsListParams) => Effect<O, ToolsListResult, never>;
+    readonly toolsCall: (params: ToolsCallParams) => Effect<O, ToolsCallResult, never>;
 };
 /**
  * A single declarative tool entry combining metadata, input schema, and type-safe handler.
@@ -39,10 +39,21 @@ export type ToolEntry<O extends Operation> = {
     readonly name: string;
     readonly description: string;
     readonly inputRtti: Type;
-    readonly handle: (args: Unknown) => Effect<O, ToolsCallResult>;
+    readonly handle: (args: Unknown) => Effect<O, ToolsCallResult, never>;
 };
-/** 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>;
+/**
+ * A JSON-RPC step: given a decoded message, produce the response to write, or
+ * `null` for a notification.
+ *
+ * **`never` is a claim, not an absence.** The handler behind this does perform
+ * effects and they can fail — a session-state read is dispatched by a runner
+ * that may decline it. It says `never` because it has *absorbed* those: a
+ * request's failure becomes `_errResponse(id)(internalError)` and a
+ * notification's is dropped, there being no frame to put it in. Spelling that
+ * as `Effect<…, never>` puts the decision in the type where a reader can
+ * disagree with it, which an opaque payload could not.
+ */
+export type Handle<O extends Operation> = (value: Unknown) => Effect<O, Response | null, never>;
 /** State carried before the peer sends `initialize`. */
 export type Uninitialized = readonly ['uninitialized'];
 /** State after `initialize` response was sent but before `notifications/initialized` arrives. */

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

@@ -5,6 +5,10 @@
  * See `./types.ts` for the `Id` type.
  *
  * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { V8 } from '../../crypto/sha2/types.ts'
+ * @import { Id } from './types.ts'
  */
 import type { Vec } from '../../types/bit_vec/types.ts';
 import type { Id } from './types.ts';

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

@@ -5,21 +5,21 @@
  * See `./types.ts` for the `Id` type.
  *
  * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { V8 } from '../../crypto/sha2/types.ts'
+ * @import { Id } from './types.ts'
  */
 
 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 { assertEq, assertNotNullish } 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.
 //
@@ -32,7 +32,7 @@ const utf8IvSeed = utf8(ivSeed)
 const c = secp256r1
 
 /** @type {bigint} */
-const ivUint = /** @type {Point2D} */ (c.mul(uint(utf8IvSeed))(c.g))[0]
+const ivUint = assertNotNullish(c.mul(uint(utf8IvSeed))(c.g))[0]
 
 // 64 hex = 256 bits = 32 bytes:
 assertEq(

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

@@ -3,10 +3,13 @@
  * See `./types.ts` for the `Add`/`EncodeState` type-level API.
  *
  * @module
+ *
+ * @import { Create } from '../../../types/patricia_trie/types.ts'
+ * @import { Id } from '../../id/types.ts'
+ * @import { Add, EncodeState } from './types.ts'
  */
 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.
  *

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

@@ -3,14 +3,16 @@
  * See `./types.ts` for the `Add`/`EncodeState` type-level API.
  *
  * @module
+ *
+ * @import { Create } from '../../../types/patricia_trie/types.ts'
+ * @import { Id } from '../../id/types.ts'
+ * @import { Add, EncodeState } from './types.ts'
  */
 
-/** @import { Create } from '../../../types/patricia_trie/types.ts' */
+import { assertNotNullish } from '../../../asserts/module.f.mjs'
 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.
@@ -48,7 +50,7 @@ export const encode =
                 return [undefined, push([asBase(symbol), symbol], state)]
             }
             const [root1, storage1] = end(state)
-            const [root2, storage2] = rootCreate(/** @type {Id} */ (root1), symbol, storage1)
+            const [root2, storage2] = rootCreate(assertNotNullish(root1), symbol, storage1)
             return [root2, [storage2, []]]
         }
     }

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

@@ -1,3 +1,7 @@
+/**
+ * @import { Id } from '../../id/types.ts'
+ * @import { EncodeState } from './types.ts'
+ */
 import type { Id } from '../../id/types.ts';
 export type _NodeList = readonly (readonly [Id, Id, Id, boolean])[];
 export declare const proof: {

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

@@ -1,8 +1,11 @@
-import { assert, assertEq } from '../../../asserts/module.f.mjs'
+/**
+ * @import { Id } from '../../id/types.ts'
+ * @import { EncodeState } from './types.ts'
+ */
+
+import { assert, assertEq, assertNotNullish } from '../../../asserts/module.f.mjs'
 import { compress, level3Id } from '../../id/module.f.mjs'
-/** @import { Id } from '../../id/types.ts' */
 import { emptyEncodeState, encode } from './module.f.mjs'
-/** @import { EncodeState } from './types.ts' */
 
 /** @typedef {readonly (readonly [Id, Id, Id, boolean])[]} _NodeList */
 
@@ -77,7 +80,7 @@ export const proof = {
     // Output equals the merged value in the last add call
     output_is_last_add: () => {
         const [out, storage] = runWord([s1, s0, s1])
-        assertEq(out, /** @type {_NodeList[number]} */ (storage.at(-1))[2])
+        assertEq(out, assertNotNullish(storage.at(-1))[2])
     },
 
     // Stack is empty after flush; storage is preserved

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

@@ -4,11 +4,14 @@
  * `Word`/`EncodeState`/`Level`/`PipelineState`/`LiteralToVec` type-level API.
  *
  * @module
+ *
+ * @import { Equal, StateScan } from '../../../types/function/operator/types.ts'
+ * @import { List } from '../../../types/list/types.ts'
+ * @import { EncodeState, Level, LiteralToVec, PipelineState } from './types.ts'
  */
 import type { Equal, StateScan } from '../../../types/function/operator/types.ts';
 import type { List } from '../../../types/list/types.ts';
 import type { EncodeState, Level, LiteralToVec, PipelineState } from './types.ts';
-/** @import { EncodeState, Level, LiteralToVec, PipelineState } from './types.ts' */
 /** @type {(s: bigint) => string} */
 export declare const symbolToString: (s: bigint) => string;
 /** @type {(word: List<bigint>) => string} */

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

@@ -4,16 +4,17 @@
  * `Word`/`EncodeState`/`Level`/`PipelineState`/`LiteralToVec` type-level API.
  *
  * @module
+ *
+ * @import { Equal, StateScan } from '../../../types/function/operator/types.ts'
+ * @import { List } from '../../../types/list/types.ts'
+ * @import { EncodeState, Level, LiteralToVec, PipelineState } from './types.ts'
  */
 
 import { log2 } from '../../../types/bigint/module.f.mjs'
 import { msb, vec } from '../../../types/bit_vec/module.f.mjs'
-/** @import { Equal, StateScan } from '../../../types/function/operator/types.ts' */
 import { strictEqual } from '../../../types/function/operator/module.f.mjs'
-/** @import { List } from '../../../types/list/types.ts' */
 import { equal, map } from '../../../types/list/module.f.mjs'
 import { join } from '../../../types/string/module.f.mjs'
-/** @import { EncodeState, Level, LiteralToVec, PipelineState } from './types.ts' */
 
 /** @type {(s: bigint) => string} */
 export const symbolToString = s => s.toString(16)

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

@@ -1,3 +1,6 @@
+/**
+ * @import { Vec } from '../../../types/bit_vec/types.ts'
+ */
 export declare const proof: {
     x2: () => void;
     x5: () => void;

package/fjs/sul/level/literal/proof.f.mjs

@@ -1,4 +1,7 @@
-/** @import { Vec } from '../../../types/bit_vec/types.ts' */
+/**
+ * @import { Vec } from '../../../types/bit_vec/types.ts'
+ */
+
 import { chunkList, msb, vec } from '../../../types/bit_vec/module.f.mjs'
 import { assert, assertEq } from '../../../asserts/module.f.mjs'
 import { map, stateScan, toArray } from '../../../types/list/module.f.mjs'

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

@@ -4,15 +4,17 @@
  * See `./types.ts` for the `EncodeState`/`Encode` type-level API.
  *
  * @module
+ *
+ * @import { Add } from './level/hash/types.ts'
+ * @import { Id } from './id/types.ts'
+ * @import { InternalState } from '../types/patricia_trie/types.ts'
+ * @import { EncodeState, Encode } from './types.ts'
  */
 import type { Add } from './level/hash/types.ts';
 import type { Id } from './id/types.ts';
 import type { InternalState } from '../types/patricia_trie/types.ts';
 import type { EncodeState, Encode } from './types.ts';
 export type _HashState = InternalState<Id>;
-/** @import { Id } from './id/types.ts' */
-/** @import { InternalState } from '../types/patricia_trie/types.ts' */
-/** @import { EncodeState, Encode } from './types.ts' */
 /** @typedef {InternalState<Id>} _HashState */
 /** @type {<S>(storage: S) => EncodeState<S>} */
 export declare const emptyEncodeState: <S>(storage: S) => EncodeState<S>;

package/fjs/sul/module.f.mjs

@@ -4,15 +4,16 @@
  * See `./types.ts` for the `EncodeState`/`Encode` type-level API.
  *
  * @module
+ *
+ * @import { Add } from './level/hash/types.ts'
+ * @import { Id } from './id/types.ts'
+ * @import { InternalState } from '../types/patricia_trie/types.ts'
+ * @import { EncodeState, Encode } from './types.ts'
  */
 
 import { emptyPipelineState, pipelineStep } from './level/literal/module.f.mjs'
 import { encode as hashEncode } from './level/hash/module.f.mjs'
-/** @import { Add } from './level/hash/types.ts' */
 import { level3Id } from './id/module.f.mjs'
-/** @import { Id } from './id/types.ts' */
-/** @import { InternalState } from '../types/patricia_trie/types.ts' */
-/** @import { EncodeState, Encode } from './types.ts' */
 
 /** @typedef {InternalState<Id>} _HashState */
 
@@ -31,22 +32,27 @@ export const encode =
 
         /** @typedef {readonly [Id | undefined, S, readonly _HashState[]]} _CascadeResult */
 
-        /** @type {(id0: Id, storage0: S, stacks0: readonly _HashState[]) => _CascadeResult} */
-        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
+        // Recursive rather than a `for(;;)` loop: every exit is one of the two
+        // `return`s below, so a bare `for(;;)` picks up a phantom "loop falls
+        // through" branch that V8's coverage instrumentation can never mark
+        // taken — there is no third way out to take it. Recursion has no such
+        // branch to begin with.
+        /** @type {(id: Id, storage: S, stacks: readonly _HashState[], index: number) => _CascadeResult} */
+        const cascadeFrom = (id, storage, stacks, 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]])
+            const newStacks = [...stacks.slice(0, index), newStack, ...stacks.slice(index + 1)]
+            return out === undefined
+                ? [undefined, newStorage, newStacks]
+                : cascadeFrom(out, newStorage, newStacks, index + 1)
         }
 
+        /** @type {(id0: Id, storage0: S, stacks0: readonly _HashState[]) => _CascadeResult} */
+        const cascade = (id0, storage0, stacks0) => cascadeFrom(id0, storage0, stacks0, 0)
+
         /** @type {(bit: bigint, state: EncodeState<S>) => readonly [Id | undefined, EncodeState<S>]} */
         const literalStep = (bit, state) => {
             const [ps, storage, stacks] = state

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

@@ -1,3 +1,7 @@
+/**
+ * @import { Id } from './id/types.ts'
+ * @import { Add } from './level/hash/types.ts'
+ */
 import type { Id } from './id/types.ts';
 export type _Merge = readonly [Id, Id, Id, boolean];
 export declare const proof: {