functionalscript 0.44.0 → 0.45.0

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

@@ -29,16 +29,14 @@
  *
  * @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 { Response } from '../../json_rpc/types.ts'
+ * @import { Step } from './types.ts'
  */
-import type { Unknown } from '../../../media/json/types.ts';
 import type { Effect, Operation } from '../../../effects/types.ts';
 import type { Read, Write } from '../../../effects/node/types.ts';
-import type { Response } from '../../json_rpc/types.ts';
-export type Step<O extends Operation> = (value: Unknown) => Effect<O, Response | null>;
+import type { Step } from './types.ts';
 /**
  * Drives the read-parse-dispatch-write loop for `handler` over stdin/stdout.
  *

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

@@ -29,10 +29,10 @@
  *
  * @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 { Response } from '../../json_rpc/types.ts'
+ * @import { Step } from './types.ts'
  */
 
 import { pure, step } from '../../../effects/module.f.mjs'
@@ -43,13 +43,6 @@ 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
- */
-
 const stringifyJson = stringify(sort)
 
 /** The parse-error response (`-32700`, `id: null`) for a malformed input line. */

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

@@ -3,7 +3,7 @@
  * @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 { Step } from './types.ts'
  */
 export declare const proof: {
     eofImmediately: () => void;

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

@@ -3,7 +3,7 @@
  * @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 { Step } from './types.ts'
  */
 
 import { assertEq } from '../../../asserts/module.f.mjs'

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>;

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

@@ -5,6 +5,11 @@
  * See `./types.ts` for the `Id` type.
  *
  * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Point2D } from '../../crypto/secp/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,22 @@
  * See `./types.ts` for the `Id` type.
  *
  * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Point2D } from '../../crypto/secp/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 { 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.
 //

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,15 @@
  * 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 { 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.

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 { Id } from '../../id/types.ts'
+ * @import { EncodeState } from './types.ts'
+ */
+
 import { assert, assertEq } 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 */
 

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 */
 

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: {

package/fjs/sul/proof.f.mjs

@@ -1,8 +1,11 @@
+/**
+ * @import { Id } from './id/types.ts'
+ * @import { Add } from './level/hash/types.ts'
+ */
+
 import { assert, assertEq } from '../asserts/module.f.mjs'
 import { compress } from './id/module.f.mjs'
-/** @import { Id } from './id/types.ts' */
 import { encode, emptyEncodeState } from './module.f.mjs'
-/** @import { Add } from './level/hash/types.ts' */
 
 /** @typedef {readonly [Id, Id, Id, boolean]} _Merge */
 

package/fjs/text/ascii/module.f.d.mts

@@ -1,8 +1,16 @@
 /**
  * Provides ASCII code point constants and helpers for creating numeric code points and inclusive ranges.
  *
+ * It also owns the hexadecimal digit codec (`hexDigitValue` /
+ * `hexDigitCodePoint`), so no consumer has to rederive the `'0'`, `'a' - 10`
+ * and `'A' - 10` offsets for itself.
+ *
  * @module
+ *
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Range } from '../../types/range/types.ts'
  */
+import type { Nullable } from '../../types/nullable/types.ts';
 import type { Range } from '../../types/range/types.ts';
 /** Returns the code point value of the first character in a string. @type {(s: string) => number} */
 export declare const one: (s: string) => number;
@@ -94,6 +102,8 @@ export declare const latinCapitalLetterA: number;
 export declare const latinCapitalLetterE: number;
 /** 0x46 */
 export declare const latinCapitalLetterF: number;
+/** 0x41..0x46, the uppercase hexadecimal digits. */
+export declare const latinCapitalLetterAFRange: Range;
 /** 0x5B */
 export declare const leftSquareBracket: number;
 /** 0x5C */
@@ -116,6 +126,8 @@ export declare const latinSmallLetterB: number;
 export declare const latinSmallLetterE: number;
 /** 0x66 */
 export declare const latinSmallLetterF: number;
+/** 0x61..0x66, the lowercase hexadecimal digits. */
+export declare const latinSmallLetterAFRange: Range;
 /** 0x6E */
 export declare const latinSmallLetterN: number;
 /** 0x72 */
@@ -134,3 +146,17 @@ export declare const verticalLine: number;
 export declare const rightCurlyBracket: number;
 /** 0x7E */
 export declare const tilde: number;
+/**
+ * The value `0..15` denoted by a hexadecimal digit code point, or `null` when
+ * the code point is not one of `0-9`, `a-f`, `A-F`.
+ *
+ * @type {(codePoint: number) => Nullable<number>}
+ */
+export declare const hexDigitValue: (codePoint: number) => Nullable<number>;
+/**
+ * The lowercase hexadecimal digit code point denoting a value in `0..15`.
+ * `hexDigitValue(hexDigitCodePoint(v))` is `v` for every such value.
+ *
+ * @type {(value: number) => number}
+ */
+export declare const hexDigitCodePoint: (value: number) => number;

package/fjs/text/ascii/module.f.mjs

@@ -1,10 +1,17 @@
 /**
  * Provides ASCII code point constants and helpers for creating numeric code points and inclusive ranges.
  *
+ * It also owns the hexadecimal digit codec (`hexDigitValue` /
+ * `hexDigitCodePoint`), so no consumer has to rederive the `'0'`, `'a' - 10`
+ * and `'A' - 10` offsets for itself.
+ *
  * @module
+ *
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Range } from '../../types/range/types.ts'
  */
 
-/** @import { Range } from '../../types/range/types.ts' */
+import { contains } from '../../types/range/module.f.mjs'
 
 /** @type {(s: string) => (i: number) => number} */
 const at = s => i => {
@@ -161,6 +168,9 @@ export const latinCapitalLetterE = one('E')
 /** 0x46 */
 export const latinCapitalLetterF = one('F')
 
+/** 0x41..0x46, the uppercase hexadecimal digits. */
+export const latinCapitalLetterAFRange = range('AF')
+
 /** 0x5B */
 export const leftSquareBracket = one('[')
 
@@ -196,6 +206,9 @@ export const latinSmallLetterE = one('e')
 /** 0x66 */
 export const latinSmallLetterF = one('f')
 
+/** 0x61..0x66, the lowercase hexadecimal digits. */
+export const latinSmallLetterAFRange = range('af')
+
 /** 0x6E */
 export const latinSmallLetterN = one('n')
 
@@ -222,3 +235,38 @@ export const rightCurlyBracket = one('}')
 
 /** 0x7E */
 export const tilde = one('~')
+
+// hexadecimal digits
+
+const isDigit = contains(...digitRange)
+
+const isLatinSmallLetterAF = contains(...latinSmallLetterAFRange)
+
+const isLatinCapitalLetterAF = contains(...latinCapitalLetterAFRange)
+
+/** The distance from a lowercase hexadecimal letter to the value it denotes. */
+const latinSmallLetterAFOffset = latinSmallLetterA - 10
+
+/** The distance from an uppercase hexadecimal letter to the value it denotes. */
+const latinCapitalLetterAFOffset = latinCapitalLetterA - 10
+
+/**
+ * The value `0..15` denoted by a hexadecimal digit code point, or `null` when
+ * the code point is not one of `0-9`, `a-f`, `A-F`.
+ *
+ * @type {(codePoint: number) => Nullable<number>}
+ */
+export const hexDigitValue = codePoint =>
+    isDigit(codePoint) ? codePoint - digit0
+        : isLatinSmallLetterAF(codePoint) ? codePoint - latinSmallLetterAFOffset
+            : isLatinCapitalLetterAF(codePoint) ? codePoint - latinCapitalLetterAFOffset
+                : null
+
+/**
+ * The lowercase hexadecimal digit code point denoting a value in `0..15`.
+ * `hexDigitValue(hexDigitCodePoint(v))` is `v` for every such value.
+ *
+ * @type {(value: number) => number}
+ */
+export const hexDigitCodePoint = value =>
+    value < 10 ? digit0 + value : latinSmallLetterAFOffset + value

package/fjs/text/ascii/proof.f.d.mts

@@ -1,5 +1,15 @@
 export declare const proof: {
     range: () => void;
+    hexDigitValue: {
+        digit: () => void;
+        latinSmallLetterAF: () => void;
+        latinCapitalLetterAF: () => void;
+        notAHexDigit: () => void;
+    };
+    hexDigitCodePoint: {
+        lowercaseDigits: () => void;
+        roundTrip: () => void;
+    };
     throw: {
         oneThrowsOnEmpty: () => number;
     };

package/fjs/text/ascii/proof.f.mjs

@@ -1,15 +1,47 @@
-import { one, range } from './module.f.mjs'
+import { hexDigitCodePoint, hexDigitValue, one, range } from './module.f.mjs'
 import { stringify as jsonStringify } from '../../media/json/module.f.mjs'
 import { sort } from '../../types/object/module.f.mjs'
 import { assertEq } from '../../asserts/module.f.mjs'
 
 const stringify = jsonStringify(sort)
 
+const values = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
+
 export const proof = {
     range: () => {
         const r = stringify(range("A"))
         assertEq(r, '[65,65]')
     },
+    hexDigitValue: {
+        digit: () => {
+            assertEq(hexDigitValue(one('0')), 0)
+            assertEq(hexDigitValue(one('9')), 9)
+        },
+        latinSmallLetterAF: () => {
+            assertEq(hexDigitValue(one('a')), 10)
+            assertEq(hexDigitValue(one('f')), 15)
+        },
+        latinCapitalLetterAF: () => {
+            assertEq(hexDigitValue(one('A')), 10)
+            assertEq(hexDigitValue(one('F')), 15)
+        },
+        notAHexDigit: () => {
+            assertEq(hexDigitValue(one('/')), null)
+            assertEq(hexDigitValue(one(':')), null)
+            assertEq(hexDigitValue(one('@')), null)
+            assertEq(hexDigitValue(one('G')), null)
+            assertEq(hexDigitValue(one('`')), null)
+            assertEq(hexDigitValue(one('g')), null)
+        },
+    },
+    hexDigitCodePoint: {
+        lowercaseDigits: () => {
+            assertEq(String.fromCodePoint(...values.map(v => hexDigitCodePoint(v))), '0123456789abcdef')
+        },
+        roundTrip: () => {
+            assertEq(stringify(values.map(v => hexDigitValue(hexDigitCodePoint(v)))), stringify(values))
+        },
+    },
     throw: {
         oneThrowsOnEmpty: () => one(''),
     },

package/fjs/text/code_point/module.f.d.mts

@@ -2,11 +2,14 @@
  * Shared Unicode code-point contract for the UTF-8 and UTF-16 decoders: the
  * error-tag mask used to flag invalid sequences, the streaming `decoder`
  * factory that wraps a per-unit step and an end-of-input step into a single
- * `List`-to-`List` conversion, and the code-point classification predicates
- * (BMP / surrogate / supplementary-plane / overall validity) that both codecs
- * share.
+ * `List`-to-`List` conversion, the `eofFlush` factory that builds that
+ * end-of-input step, and the code-point classification predicates (BMP /
+ * surrogate / supplementary-plane / overall validity) that both codecs share.
  *
  * @module
+ *
+ * @import { List } from '../../types/list/types.ts'
+ * @import { StateScan } from '../../types/function/operator/types.ts'
  */
 import type { List } from '../../types/list/types.ts';
 import type { StateScan } from '../../types/function/operator/types.ts';
@@ -31,6 +34,21 @@ export declare const errorMask = 2147483648;
  * @returns {(input: List<Unit>) => List<Cp>} A function converting a list of code units into a list of code points.
  */
 export declare const decoder: <Unit, S, Cp>(byteOp: StateScan<Unit, S | null, List<Cp>>, eofOp: (state: S | null) => readonly [List<Cp>, S | null]) => (input: List<Unit>) => List<Cp>;
+/**
+ * Builds the end-of-input step {@link decoder} needs, from the one function
+ * that differs between codecs.
+ *
+ * The flush contract is the same for every decoder: leftover state at the end
+ * of the input becomes **exactly one** error unit and the state resets to
+ * empty (`null`); with no leftover state nothing is emitted. Only the mapping
+ * from a non-empty state to its error unit is codec-specific.
+ *
+ * @template S
+ * @template Cp
+ * @param {(state: S) => Cp} toError - Turns a non-empty leftover state into a single error unit.
+ * @returns {(state: S | null) => readonly [List<Cp>, S | null]} The end-of-input step.
+ */
+export declare const eofFlush: <S, Cp>(toError: (state: S) => Cp) => (state: S | null) => readonly [List<Cp>, S | null];
 /**
  * Checks whether the 16-bit word (U16) is a high surrogate.
  * Range: 0xD800 - 0xDBFF.

package/fjs/text/code_point/module.f.mjs

@@ -2,18 +2,17 @@
  * Shared Unicode code-point contract for the UTF-8 and UTF-16 decoders: the
  * error-tag mask used to flag invalid sequences, the streaming `decoder`
  * factory that wraps a per-unit step and an end-of-input step into a single
- * `List`-to-`List` conversion, and the code-point classification predicates
- * (BMP / surrogate / supplementary-plane / overall validity) that both codecs
- * share.
+ * `List`-to-`List` conversion, the `eofFlush` factory that builds that
+ * end-of-input step, and the code-point classification predicates (BMP /
+ * surrogate / supplementary-plane / overall validity) that both codecs share.
  *
  * @module
+ *
+ * @import { List } from '../../types/list/types.ts'
+ * @import { StateScan } from '../../types/function/operator/types.ts'
  */
 
-import { flat, stateScan } from '../../types/list/module.f.mjs'
-/** @import { List } from '../../types/list/types.ts' */
-
-/** @import { StateScan } from '../../types/function/operator/types.ts' */
-
+import { empty, flat, stateScan } from '../../types/list/module.f.mjs'
 import { contains } from '../../types/range/module.f.mjs'
 
 //
@@ -50,6 +49,23 @@ export const decoder = (
     return input => flat(run(flat(/** @type {List<List<Unit|null>>} */([input, [null]]))))
 }
 
+/**
+ * Builds the end-of-input step {@link decoder} needs, from the one function
+ * that differs between codecs.
+ *
+ * The flush contract is the same for every decoder: leftover state at the end
+ * of the input becomes **exactly one** error unit and the state resets to
+ * empty (`null`); with no leftover state nothing is emitted. Only the mapping
+ * from a non-empty state to its error unit is codec-specific.
+ *
+ * @template S
+ * @template Cp
+ * @param {(state: S) => Cp} toError - Turns a non-empty leftover state into a single error unit.
+ * @returns {(state: S | null) => readonly [List<Cp>, S | null]} The end-of-input step.
+ */
+export const eofFlush = toError => state =>
+    [state === null ? empty : [toError(state)], null]
+
 /**
  * Unicode code-point classification boundaries. The surrogate block
  * (`0xD800`–`0xDFFF`) splits into a high half (`0xD800`–`0xDBFF`) and a low half

package/fjs/text/code_point/proof.f.d.mts

@@ -1,4 +1,5 @@
 export declare const proof: {
+    eofFlush: (() => void)[];
     isHighSurrogate: (() => void)[];
     isLowSurrogate: (() => void)[];
     isBmpCodePoint: (() => void)[];

package/fjs/text/code_point/proof.f.mjs

@@ -1,4 +1,7 @@
+import { assertEq } from '../../asserts/module.f.mjs'
+import { toArray } from '../../types/list/module.f.mjs'
 import {
+    eofFlush,
     isBmpCodePoint,
     isHighSurrogate,
     isLowSurrogate,
@@ -12,7 +15,32 @@ const check = (actual, expected) => {
     if (actual !== expected) { throw `${actual} !== ${expected}` }
 }
 
+/**
+ * A stand-in for a codec's state-to-error function.
+ *
+ * @type {(state: number) => number}
+ */
+const negate = state => -state
+
+const flush = eofFlush(negate)
+
 export const proof = {
+    eofFlush: [
+        // no leftover state: nothing is flushed, the state stays empty
+        () => {
+            const [out, next] = flush(null)
+            assertEq(toArray(out).length, 0)
+            assertEq(next, null)
+        },
+        // leftover state: exactly one error unit, then the state resets
+        () => {
+            const [out, next] = flush(42)
+            const [first, ...rest] = toArray(out)
+            assertEq(first, -42)
+            assertEq(rest.length, 0)
+            assertEq(next, null)
+        },
+    ],
     isHighSurrogate: [
         () => check(isHighSurrogate(0xd800), true),
         () => check(isHighSurrogate(0xdbff), true),