functionalscript 0.45.0 → 0.46.1

package/fjs/types/rtti/validate/proof.f.mjs

@@ -1,14 +1,17 @@
 /**
- * @import { ValidationError } from '../common/types.ts'
+ * @import { ValidationError, ValidateE } from '../common/types.ts'
+ * @import { Type } from '../types.ts'
  * @import { Equal } from '../../ts/types.ts'
- * @import { Ts } from '../ts/types.ts'
+ * @import { Ts, Unknown } from '../ts/types.ts'
  * @import { Unknown as DjsUnknown } from '../../../djs/types.ts'
  * @import { Assert } from '../../../asserts/types.ts'
  */
 
 import { validate } from './module.f.mjs'
+import { parse } from '../parse/module.f.mjs'
 import { boolean, number, string, bigint, unknown, array, record, or, option } from '../module.f.mjs'
-import { assert, assertEq } from '../../../asserts/module.f.mjs'
+import { unwrap } from '../../result/module.f.mjs'
+import { assert, assertEq, assertStructurallySame } from '../../../asserts/module.f.mjs'
 
 /** @type {(r: readonly [string, unknown]) => void} */
 const assertOk = ([k]) => { assertEq(k, 'ok', 'expected ok') }
@@ -21,13 +24,115 @@ const assertErrorPath = expected =>
     r => {
         assert(r[0] === 'error', 'expected error')
         const e = /** @type {ValidationError} */ (r[1])
-        if (e.path.length !== expected.length) { throw `path length ${e.path.length} != ${expected.length}` }
-        for (let i = 0; i < expected.length; i++) {
-            if (e.path[i] !== expected[i]) { throw `path[${i}] ${e.path[i]} != ${expected[i]}` }
-        }
+        assertStructurallySame(e.path, expected, 'unexpected error path')
     }
 
+/** Both readers with their payload type erased, so a table can hold rows of mixed schemas. */
+
+/** @type {(t: Type) => ValidateE} */
+const v = t => /** @type {any} */ (validate(t))
+
+/** @type {(t: Type) => ValidateE} */
+const p = t => /** @type {any} */ (parse(t))
+
 export const proof = {
+    // ── the three properties this module exists for ──────────────────────────
+    //
+    // `parse` rebuilds: it materializes a declared-but-absent member as
+    // `undefined`, drops an undeclared one, and returns a new object. For a
+    // caller whose value is a document whose bytes are its identity — a
+    // content-addressed store, a signed payload — each of those is a
+    // different document. `validate` answers the same question about the
+    // value it was handed and hands it back.
+    verbatim: {
+        // An absent optional member stays absent. `'b' in out` is the
+        // assertion, not `out.b === undefined`: `parse` satisfies the latter.
+        absentOptionalStaysAbsent: () => {
+            const schema = { a: number, b: option(string) }
+            const input = { a: 1 }
+            const out = unwrap(validate(schema)(input))
+            assert(!('b' in out), 'an absent optional member must stay absent')
+            // The contrast that motivates the module.
+            assert('b' in unwrap(parse(schema)(input)), 'parse materializes it')
+        },
+        // An undeclared member survives. `parse` accepts it too — structs and
+        // tuples are open — but does not carry it into what it builds.
+        undeclaredMemberSurvives: () => {
+            const schema = { a: number }
+            const struct = { a: 1, b: 'extra' }
+            assertStructurallySame(unwrap(validate(schema)(struct)), { a: 1, b: 'extra' })
+            assert(!('b' in unwrap(parse(schema)(struct))), 'parse drops it')
+            // The same on the other kind: a longer array keeps its tail.
+            const tuple = [1, 'extra']
+            assertStructurallySame(unwrap(validate([number])(tuple)), [1, 'extra'])
+        },
+        // On success the result *is* the argument. This is the property the
+        // other two follow from, and the mirror of `../parse/proof.f.mjs`'s
+        // `freshArray` / `freshRecord`.
+        referenceIdentity: () => {
+            /** @type {(t: Type, value: Unknown) => void} */
+            const same = (t, value) => {
+                const r = v(t)(value)
+                assert(r[0] === 'ok', 'expected ok')
+                assert(Object.is(r[1], value), 'expected the original value')
+            }
+            const arr = [1, 2, 3]
+            same(array(number), arr)
+            same([number, number, number], arr)
+            same(unknown, arr)
+            const obj = { a: 1, b: 2 }
+            same(record(number), obj)
+            same({ a: number }, obj)
+            same(or(string, record(number)), obj)
+            const nested = { xs: [{ a: 1 }] }
+            same({ xs: array({ a: number }) }, nested)
+            assert(Object.is(unwrap(validate({ xs: array({ a: number }) })(nested)).xs, nested.xs),
+                'nested containers are not rebuilt either')
+        },
+    },
+    // Acceptance is `parse`'s, exactly: the two readers differ in what a
+    // success carries and in nothing else. Rows cover both container kinds,
+    // openness on both, the short-array rule, primitives, `or`, and misses.
+    sameAcceptanceAsParse: () => {
+        /** @type {readonly (readonly [Type, Unknown])[]} */
+        const rows = [
+            [number, 42],
+            [number, '42'],
+            [string, 42],
+            [boolean, false],
+            [bigint, 7n],
+            [unknown, { a: [1, 'x'] }],
+            [/** @type {const} */ (42), 42],
+            [/** @type {const} */ (42), 43],
+            [array(number), [1, 2, 3]],
+            [array(number), [1, 'two']],
+            [array(number), {}],
+            [record(number), { a: 1 }],
+            [record(number), { a: 'one' }],
+            [record(number), []],
+            // the four openness rows
+            [[/** @type {const} */ (42)], [42, 'extra']],
+            [{ a: /** @type {const} */ (42) }, { a: 42, b: 'x' }],
+            [[number, option(string)], [42]],
+            [[/** @type {const} */ (42)], []],
+            [{ a: number, b: option(string) }, { a: 1 }],
+            [{ a: number }, { a: 'one' }],
+            [or(number, string), true],
+            [or(number, string), 'hello'],
+            [option(number), undefined],
+            [option(number), null],
+            [{ user: { name: string, age: number } }, { user: { name: 'A', age: 'old' } }],
+        ]
+        for (const [t, value] of rows) {
+            const rv = v(t)(value)
+            const rp = p(t)(value)
+            assertEq(rv[0], rp[0], 'validate and parse must agree on acceptance')
+            if (rv[0] === 'error') {
+                assert(rp[0] === 'error', 'expected error')
+                assertStructurallySame(rv[1], rp[1], 'the two readers report the same error')
+            }
+        }
+    },
     boolean: {
         ok: () => {
             /** @typedef {Assert<Equal<Ts<typeof boolean>, boolean>>} _RoundTrip */
@@ -83,98 +188,99 @@ export const proof = {
     },
     const: {
         null: {
-            ok: () => {
-                /** @typedef {Assert<Equal<Ts<null>, null>>} _RoundTrip */
-                assertOk(validate(null)(null))
-            },
+            ok: () => assertOk(validate(null)(null)),
             error: () => {
                 assertError(validate(null)(undefined))
                 assertError(validate(null)(0))
             },
         },
         undefined: {
-            ok: () => {
-                /** @typedef {Assert<Equal<Ts<undefined>, undefined>>} _RoundTrip */
-                assertOk(validate(undefined)(undefined))
-            },
+            ok: () => assertOk(validate(undefined)(undefined)),
             error: () => assertError(validate(undefined)(null)),
         },
         number: {
-            ok: () => {
-                /** @typedef {Assert<Equal<Ts<42>, 42>>} _RoundTrip */
-                assertOk(validate(/** @type {const} */ (42))(42))
-            },
+            ok: () => assertOk(validate(/** @type {const} */ (42))(42)),
             error: () => assertError(validate(/** @type {const} */ (42))(43)),
         },
         nan: {
-            ok: () => assertOk(validate(/** @type {number} */ (NaN))(NaN)),
+            ok: () => assertOk(validate(NaN)(NaN)),
             error: () => {
-                assertError(validate(/** @type {number} */ (NaN))(0))
+                assertError(validate(NaN)(0))
                 assertError(validate(/** @type {const} */ (0))(NaN))
                 assertError(validate(/** @type {const} */ (42))(NaN))
             },
         },
         infinity: {
             ok: () => {
-                assertOk(validate(/** @type {number} */ (Infinity))(Infinity))
-                assertOk(validate(/** @type {number} */ (-Infinity))(-Infinity))
+                assertOk(validate(Infinity)(Infinity))
+                assertOk(validate(-Infinity)(-Infinity))
             },
             error: () => {
-                assertError(validate(/** @type {number} */ (Infinity))(-Infinity))
-                assertError(validate(/** @type {number} */ (Infinity))(0))
+                assertError(validate(Infinity)(-Infinity))
+                assertError(validate(Infinity)(0))
             },
         },
         signedZero: {
             // `Object.is` distinguishes +0 and -0; `===` treats them equal.
             distinct: () => {
                 assertError(validate(/** @type {const} */ (0))(-0))
-                assertError(validate(/** @type {number} */ (-0))(0))
+                assertError(validate(-0)(0))
             },
             self: () => {
                 assertOk(validate(/** @type {const} */ (0))(0))
-                assertOk(validate(/** @type {number} */ (-0))(-0))
+                assertOk(validate(-0)(-0))
             },
         },
         string: {
-            ok: () => {
-                /** @typedef {Assert<Equal<Ts<'hello'>, 'hello'>>} _RoundTrip */
-                assertOk(validate(/** @type {const} */ ('hello'))('hello'))
-            },
+            ok: () => assertOk(validate(/** @type {const} */ ('hello'))('hello')),
             error: () => assertError(validate(/** @type {const} */ ('hello'))('world')),
         },
         bigint: {
-            ok: () => {
-                /** @typedef {Assert<Equal<Ts<7n>, 7n>>} _RoundTrip */
-                assertOk(validate(/** @type {const} */ (7n))(7n))
-            },
+            ok: () => assertOk(validate(/** @type {const} */ (7n))(7n)),
             error: () => assertError(validate(/** @type {const} */ (7n))(8n)),
         },
         boolean: {
-            ok: () => {
-                /** @typedef {Assert<Equal<Ts<true>, true>>} _RoundTrip */
-                assertOk(validate(/** @type {const} */ (true))(true))
-            },
+            ok: () => assertOk(validate(/** @type {const} */ (true))(true)),
             error: () => assertError(validate(/** @type {const} */ (true))(false)),
         },
         tuple: {
             ok: () => {
                 const t = /** @type {const} */ ([42, 'hello'])
-                /** @typedef {Assert<Equal<Ts<typeof t>, readonly[42, 'hello']>>} _RoundTrip */
-                assertOk(validate(t)([42, 'hello']))
+                assertStructurallySame(unwrap(validate(t)([42, 'hello'])), [42, 'hello'])
+            },
+            // A tuple is OPEN, and the extras are still there afterwards. This
+            // is deliberate — see "Structs and tuples are open" in
+            // ../README.md. Do not restore #1622's length check on the
+            // strength of `Ts<readonly [42]>` being an exact tuple; that
+            // mapping is exact only because TypeScript could not express the
+            // open one (see ../ts/types.ts `TupleTs`).
+            extraItemsAcceptedAndKept: () => {
+                const long = [42, 1, 2, 3]
+                assert(Object.is(unwrap(validate(/** @type {const} */ ([42]))(long)), long),
+                    'the longer array comes back as it went in')
+            },
+            // An absent member reads as `undefined`, so a position is required
+            // exactly when its set excludes `undefined` — and nothing is
+            // filled in, so the array keeps its length.
+            shortArrayKeepsItsLength: () => {
+                const short = [42]
+                const out = unwrap(validate([number, option(string)])(short))
+                assert(Object.is(out, short), 'expected the original array')
+                assertEq(short.length, 1, 'no gap is filled')
             },
-            extraItems: () => assertOk(validate(/** @type {const} */ ([42]))([42, 'extra'])),
+            empty: () => assertOk(validate(/** @type {const} */ ([]))([])),
             error: () => {
                 assertError(validate(/** @type {const} */ ([42]))([99]))
                 assertError(validate(/** @type {const} */ ([42]))({}))
+                // `42` excludes `undefined`, so position 0 is required.
+                assertError(validate(/** @type {const} */ ([42]))([]))
             },
         },
         struct: {
             ok: () => {
                 const t = /** @type {const} */ ({ a: 42, b: 'hello' })
-                /** @typedef {Assert<Equal<Ts<typeof t>, { readonly a: 42, readonly b: 'hello' }>>} _RoundTrip */
-                assertOk(validate(t)({ a: 42, b: 'hello' }))
+                assertStructurallySame(unwrap(validate(t)({ a: 42, b: 'hello' })), { a: 42, b: 'hello' })
             },
-            extraKeys: () => assertOk(validate(/** @type {const} */ ({ a: /** @type {const} */ (42) }))({ a: 42, b: 'extra' })),
             error: () => {
                 assertError(validate(/** @type {const} */ ({ a: 42 }))({ a: 99 }))
                 assertError(validate(/** @type {const} */ ({ a: 42 }))([]))
@@ -182,31 +288,30 @@ export const proof = {
         },
     },
     array: {
-        empty: () => assertOk(validate(array(number))([])),
-        ok: () => {
-            const t = array(number)
-            /** @typedef {Assert<Equal<Ts<typeof t>, readonly number[]>>} _RoundTrip */
-            assertOk(validate(array(number))([1, 2, 3]))
+        empty: () => {
+            const input = /** @type {readonly number[]} */ ([])
+            assert(Object.is(unwrap(validate(array(number))(input)), input), 'expected the original array')
         },
+        ok: () => assertStructurallySame(unwrap(validate(array(number))([1, 2, 3])), [1, 2, 3]),
         error: () => {
             assertError(validate(array(number))([1, 'two', 3]))
             assertError(validate(array(number))({}))
             assertError(validate(array(number))(null))
         },
         nested: () => {
-            const t = array(array(boolean))
-            /** @typedef {Assert<Equal<Ts<typeof t>, readonly (readonly boolean[])[]>>} _RoundTrip */
             assertOk(validate(array(array(boolean)))([[true, false], [false]]))
             assertError(validate(array(array(boolean)))([[true, 42]]))
         },
     },
     record: {
-        empty: () => assertOk(validate(record(number))({})),
-        ok: () => {
-            const t = record(string)
-            /** @typedef {Assert<Equal<Ts<typeof t>, { readonly[K in string]?: string }>>} _RoundTrip */
-            assertOk(validate(t)({ a: 'hello', b: 'world' }))
+        empty: () => {
+            const input = /** @type {{ readonly[K in string]?: number }} */ ({})
+            assert(Object.is(unwrap(validate(record(number))(input)), input), 'expected the original record')
         },
+        ok: () => assertStructurallySame(
+            unwrap(validate(record(string))({ a: 'hello', b: 'world' })),
+            { a: 'hello', b: 'world' },
+        ),
         error: () => {
             assertError(validate(record(number))({ a: 1, b: 'two' }))
             assertError(validate(record(number))(null))
@@ -216,7 +321,6 @@ export const proof = {
     constThunk: {
         primitive: () => {
             const t = () => /** @type {const} */ (['const', 7n])
-            /** @typedef {Assert<Equal<Ts<typeof t>, 7n>>} _RoundTrip */
             assertOk(validate(t)(7n))
             assertError(validate(t)(8n))
         },
@@ -224,8 +328,7 @@ export const proof = {
     or: {
         consts: {
             ok: () => {
-                const t = or(.../** @type {const} */ ([false,42, 'hello']))
-                /** @typedef {Assert<Equal<Ts<typeof t>, false | 42 | 'hello'>>} _RoundTrip */
+                const t = or(.../** @type {const} */ ([false, 42, 'hello']))
                 assertOk(validate(t)(false))
                 assertOk(validate(t)(42))
                 assertOk(validate(t)('hello'))
@@ -241,7 +344,6 @@ export const proof = {
         thunks: {
             ok: () => {
                 const t = or(number, string)
-                /** @typedef {Assert<Equal<Ts<typeof t>, number | string>>} _RoundTrip */
                 assertOk(validate(t)(42))
                 assertOk(validate(t)('hello'))
             },
@@ -251,24 +353,20 @@ export const proof = {
                 assertError(validate(t)(null))
             },
         },
-        mixed: {
-            ok: () => {
-                const t = or(/** @type {const} */ (42), string)
-                /** @typedef {Assert<Equal<Ts<typeof t>, 42 | string>>} _RoundTrip */
-                assertOk(validate(t)(42))
-                assertOk(validate(t)('hello'))
-            },
-            error: () => {
-                const t = or(/** @type {const} */ (42), string)
-                assertError(validate(t)(43))
-                assertError(validate(t)(null))
-            },
+        // The first matching variant wins, and it returns the value itself —
+        // so, unlike `parse`, which variant matched is not observable in the
+        // result. `parse` here returns a length-1 array; `validate` returns
+        // the length-3 one it was given.
+        firstMatchWins: () => {
+            const t = or(/** @type {const} */ ([number]), array(number))
+            const input = [1, 2, 3]
+            assert(Object.is(unwrap(validate(t)(input)), input), 'expected the original array')
+            assertStructurallySame(unwrap(parse(t)(input)), [1])
         },
     },
     option: {
         ok: () => {
             const t = option(number)
-            /** @typedef {Assert<Equal<Ts<typeof t>, number | undefined>>} _RoundTrip */
             assertOk(validate(t)(42))
             assertOk(validate(t)(undefined))
         },
@@ -281,11 +379,7 @@ export const proof = {
     path: {
         rootMismatch: () => assertErrorPath([])(validate(number)('not a number')),
         arrayIndex: () => assertErrorPath(['1'])(validate(array(number))([1, 'two', 3])),
-        recordKey: () => {
-            const r = validate(record(number))({ a: 1, b: 'two', c: 3 })
-            // record iteration order matches Object.entries; 'b' is the failing key
-            assertErrorPath(['b'])(r)
-        },
+        recordKey: () => assertErrorPath(['b'])(validate(record(number))({ a: 1, b: 'two', c: 3 })),
         nestedArray: () => assertErrorPath(['0', '1'])(
             validate(array(array(number)))([[1, 'x'], [2, 3]])
         ),
@@ -297,13 +391,11 @@ export const proof = {
         ),
         deepStruct: () => {
             const schema = /** @type {const} */ ({ user: { name: string, age: number } })
-            const r = validate(schema)({ user: { name: 'A', age: 'old' } })
-            assertErrorPath(['user', 'age'])(r)
+            assertErrorPath(['user', 'age'])(validate(schema)({ user: { name: 'A', age: 'old' } }))
         },
         recursiveSchema: () => {
             /** @typedef {readonly _A[]} _A */
             const list = () => /** @type {const} */ (['array', list])
-            // [[[42]]] — innermost element 42 is a number, not an array
             const r = validate(list)([/** @type {_A} */ (/** @type {unknown} */ ([[42]]))])
             assertErrorPath(['0', '0', '0'])(r)
         },
@@ -312,126 +404,23 @@ export const proof = {
     recursive: {
         arrayOfArrays: () => {
             /** @typedef {readonly _A[]} _A */
-            // self-referential schema: an array whose elements are also arrays of the same type
             const list = () => /** @type {const} */ (['array', list])
-            /** @typedef {Assert<Equal<_A, Ts<typeof list>>>} _RoundTripA */
-            const v = validate(list)
-            assertOk(v([]))
-            assertOk(v([[], []]))
-            assertOk(v([[[], []], []]))
-            assertError(v([42]))
-            assertError(v(null))
+            /** @typedef {Assert<Equal<_A, Ts<typeof list>>>} _ListRoundTrip */
+            const x = validate(list)
+            assertOk(x([]))
+            assertOk(x([[], []]))
+            assertOk(x([[[], []], []]))
+            assertError(x([42]))
+            assertError(x(null))
         },
         recordOfRecords: () => {
             const tree = () => /** @type {const} */ (['record', tree])
             /** @typedef {{ readonly[K in string]?: _A }} _A */
-            /** @typedef {Assert<Equal<_A, Ts<typeof tree>>>} _RoundTrip */
-            const v = validate(tree)
-            assertOk(v({}))
-            assertOk(v({ a: {}, b: { c: {} } }))
-            assertError(v({ a: 42 }))
+            /** @typedef {Assert<Equal<_A, Ts<typeof tree>>>} _TreeRoundTrip */
+            const x = validate(tree)
+            assertOk(x({}))
+            assertOk(x({ a: {}, b: { c: {} } }))
+            assertError(x({ a: 42 }))
         },
     },
-    funcParam: () => {
-        const paramSet0 = /** @type {const} */ (['hello', bigint])
-        const paramSet1 = /** @type {const} */ (['goodbye', string, 43])
-
-        const paramSet01 = or(paramSet0, paramSet1)
-
-        /** @typedef {Ts<typeof paramSet0>} _Param0 */
-        /** @typedef {Ts<typeof paramSet1>} _Param1 */
-        /** @typedef {Ts<typeof paramSet01>} _Param01 */
-
-        const v0 = validate(paramSet0)
-        const v1 = validate(paramSet1)
-
-        /** @template T @typedef {(...args: _Param0) => T} _F0 */
-        /** @template T @typedef {(...args: _Param1) => T} _F1 */
-
-        /**
-         * @template T
-         * @param {_F0<T>} f0
-         * @param {_F1<T>} f1
-         * @returns {(...args: _Param01) => T}
-         */
-        const func = (f0, f1) => (...args) => {
-            {
-                const [t, r] = v0(args)
-                if (t === 'ok') {
-                    return f0(...r)
-                }
-            }
-            {
-                const [t, r] = v1(args)
-                if (t === 'ok') {
-                    return f1(...r)
-                }
-            }
-            throw 'unreachable: args did not match any parameter set'
-        }
-
-        /** @type {(a: 'hello', b: bigint) => number} */
-        const f0 = (a, b) => 42
-        /** @type {(a: 'goodbye', b: string, c: 43) => number} */
-        const f1 = (a, b, c) => 13
-
-        /** @type {(...args: _Param01) => number} */
-        const x = func(f0, f1)
-
-        return () => {
-            assertEq(x('hello', 42n), 42)
-            assertEq(x('goodbye', 'world', 43), 13)
-        }
-    },
-    funcObj: () => {
-        const param0 = { a: 'hello', b: bigint }
-        const param1 = { a: 'goodbye', b: string, c: 43 }
-
-        const param01 = or(param0, param1)
-
-        /** @typedef {Ts<typeof param0>} _Param0 */
-        /** @typedef {Ts<typeof param1>} _Param1 */
-        /** @typedef {Ts<typeof param01>} _Param01 */
-
-        const v0 = validate(param0)
-        const v1 = validate(param1)
-
-        /** @template T @typedef {(args: _Param0) => T} _F0 */
-        /** @template T @typedef {(args: _Param1) => T} _F1 */
-
-        /**
-         * @template T
-         * @param {_F0<T>} f0
-         * @param {_F1<T>} f1
-         * @returns {(args: _Param01) => T}
-         */
-        const func = (f0, f1) => args => {
-            {
-                const [t, r] = v0(args)
-                if (t === 'ok') {
-                    return f0(r)
-                }
-            }
-            {
-                const [t, r] = v1(args)
-                if (t === 'ok') {
-                    return f1(r)
-                }
-            }
-            throw 'unreachable: args did not match any parameter set'
-        }
-
-        /** @type {(args: _Param0) => number} */
-        const f0 = args => Number(args.b) + args.a.length
-        /** @type {(args: _Param1) => number} */
-        const f1 = args => args.c
-
-        /** @type {(args: _Param01) => number} */
-        const x = func(f0, f1)
-
-        return () => {
-            assertEq(x({ a: 'hello', b: 42n }), 47)
-            assertEq(x({ a: 'goodbye', b: 'world', c: 43 }), 43)
-        }
-    }
 }

package/fjs/types/sorted_set/module.f.d.mts

@@ -52,3 +52,21 @@ export declare const has: <T>(
  * @returns {(value: T) => (set: SortedSet<T>) => boolean}
  */
 cmp: Cmp<T>) => (value: T) => (set: SortedSet<T>) => boolean;
+/**
+ * A canonical key for a set of strings: equal sets always produce the same
+ * key, and unequal sets never produce the same one. Useful wherever a set has
+ * to index a `StringMap` — the subset construction in `fjs/fsm`, say.
+ *
+ * Each element is written length-prefixed (`3:abc`) and the parts are
+ * concatenated. Joining on a separator would **not** be canonical: elements
+ * are arbitrary strings, so `['a,b']` and `['a', 'b']` would both produce
+ * `a,b` and two different sets would share one key. A length prefix is
+ * readable back — take the digits, the `:`, then exactly that many code
+ * units — so the encoding is injective without an escaping table.
+ *
+ * The key is canonical for the *set* only because `SortedSet` is sorted:
+ * element order is fixed by the set's own invariant, not by this function.
+ *
+ * @type {(set: SortedSet<string>) => string}
+ */
+export declare const toKey: (set: SortedSet<string>) => string;

package/fjs/types/sorted_set/module.f.mjs

@@ -56,3 +56,25 @@ export const has =
      * @returns {(value: T) => (set: SortedSet<T>) => boolean}
      */
     cmp => value => set => find(cmp)(value)(set) === value
+
+/** @type {(s: string) => string} */
+const lengthPrefixed = s => `${s.length}:${s}`
+
+/**
+ * A canonical key for a set of strings: equal sets always produce the same
+ * key, and unequal sets never produce the same one. Useful wherever a set has
+ * to index a `StringMap` — the subset construction in `fjs/fsm`, say.
+ *
+ * Each element is written length-prefixed (`3:abc`) and the parts are
+ * concatenated. Joining on a separator would **not** be canonical: elements
+ * are arbitrary strings, so `['a,b']` and `['a', 'b']` would both produce
+ * `a,b` and two different sets would share one key. A length prefix is
+ * readable back — take the digits, the `:`, then exactly that many code
+ * units — so the encoding is injective without an escaping table.
+ *
+ * The key is canonical for the *set* only because `SortedSet` is sorted:
+ * element order is fixed by the set's own invariant, not by this function.
+ *
+ * @type {(set: SortedSet<string>) => string}
+ */
+export const toKey = set => set.map(lengthPrefixed).join('')

package/fjs/types/sorted_set/proof.f.d.mts

@@ -2,6 +2,7 @@
  * @import { Unknown } from '../../media/json/types.ts'
  */
 export declare const proof: {
+    toKey: (() => void)[];
     example: () => void;
     union: (() => void)[];
     intersect: (() => void)[];

package/fjs/types/sorted_set/proof.f.mjs

@@ -2,7 +2,7 @@
  * @import { Unknown } from '../../media/json/types.ts'
  */
 
-import { has, intersect, union } from './module.f.mjs'
+import { has, intersect, toKey, union } from './module.f.mjs'
 import { stringify } from '../../media/json/module.f.mjs'
 import { sort } from '../object/module.f.mjs'
 import { toArray, countdown, length } from '../list/module.f.mjs'
@@ -16,6 +16,21 @@ const str = a => stringify(sort)(a)
 const reverseCmp = flip(cmp)
 
 export const proof = {
+    toKey: [
+        () => assertEq(toKey([]), ''),
+        () => assertEq(toKey(['']), '0:'),
+        () => assertEq(toKey(['a']), '1:a'),
+        () => assertEq(toKey(['a', 'b']), '1:a1:b'),
+        // The reason the key is length-prefixed rather than separator-joined:
+        // these two sets are different and must not share a key, but any
+        // fixed separator that can occur in an element collapses them.
+        () => assert(toKey(['a,b']) !== toKey(['a', 'b']), 'comma'),
+        () => assert(toKey(['a:b']) !== toKey(['a', 'b']), 'colon'),
+        () => assert(toKey(['a\nb']) !== toKey(['a', 'b']), 'newline'),
+        // A prefix of one element must not be confused with a shorter one.
+        () => assert(toKey(['ab']) !== toKey(['a']), 'prefix'),
+        () => assert(toKey(['']) !== toKey([]), 'empty element vs empty set'),
+    ],
     example: () => {
         const cmp = (/** @type {number} */ a) => (/** @type {number} */ b) => a < b ? -1 : a > b ? 1 : 0
 

package/fjs/types/uint8array/module.f.d.mts

@@ -19,7 +19,7 @@ import type { List } from '../list/types.ts';
  *
  * Throws if the result would exceed `maxLength`. The bound is not precomputed:
  * `tryU8ListToVec` attempts the real conversion and reports `null` when it does
- * not fit (AGENTS.md §5.6).
+ * not fit (`DESIGN.md` §6).
  *
  * @type {(input: List<Uint8Array>) => Vec}
  */

package/fjs/types/uint8array/module.f.mjs

@@ -29,7 +29,7 @@ const m = map(fromArrayLike)
  *
  * Throws if the result would exceed `maxLength`. The bound is not precomputed:
  * `tryU8ListToVec` attempts the real conversion and reports `null` when it does
- * not fit (AGENTS.md §5.6).
+ * not fit (`DESIGN.md` §6).
  *
  * @type {(input: List<Uint8Array>) => Vec}
  */