functionalscript 0.44.0 → 0.46.0

package/fjs/types/rtti/data/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Types for the serializable RTTI data form.
+ *
+ * A schema in data form denotes a set of values. The representation
+ * partitions that set into six disjoint *kinds* — unit values (`null`,
+ * `undefined`, `false`, `true`), numbers, strings, bigints, arrays and
+ * objects — so that union, equality and subset reduce to kind-wise set
+ * operations. See `./README.md` for the design rationale.
+ *
+ * @module
+ */
+import type { StringMap } from '../../object/types.ts';
+/**
+ * A set of values of one kind: `true` is the whole kind, an array lists its
+ * members (literals or patterns), canonically sorted and deduplicated. An
+ * empty kind is an absent property of {@link UnionSet}, never an empty array.
+ */
+export type KindSet<T> = true | readonly T[];
+/**
+ * A set of arrays: a tuple with an optional rest.
+ *
+ * - `prefix` constrains the value set of each leading position.
+ * - `rest` present: the array may be any length `>= prefix.length`, and every
+ *   element past the prefix belongs to `rest`.
+ * - `rest` absent: the array length is exactly `prefix.length`.
+ *
+ * A tuple schema is `{ prefix }`; a uniform array schema is
+ * `{ prefix: [], rest }`. Both are points of the same kind, so
+ * `readonly [number] ⊂ readonly number[]` is a plain pattern inclusion.
+ */
+export type ArraySet = {
+    readonly prefix: readonly Node[];
+    readonly rest?: Node;
+};
+/**
+ * A set of objects: per-key value sets with an optional rest.
+ *
+ * - `props` constrains, per declared key, the value *read* at that key — an
+ *   absent property reads as `undefined`, so a key is required exactly when
+ *   its set excludes `undefined`. Keys are canonically sorted, and a key
+ *   whose set is the whole value domain is omitted.
+ * - `rest` present: the value at every other *present* key belongs to `rest`.
+ * - `rest` absent: other keys are unconstrained.
+ *
+ * A struct schema is `{ props }`; a uniform record schema is
+ * `{ props: {}, rest }`.
+ */
+export type ObjectSet = {
+    readonly props: StringMap<Node>;
+    readonly rest?: Node;
+};
+/**
+ * A set of values as a disjoint union over the six kinds. An absent
+ * component is the empty set of that kind, so `{}` is `never` and a union
+ * with every component at its maximum (see `unknown` in `./module.f.mjs`)
+ * is `unknown`.
+ *
+ * `unit` is a bitset over the four singleton values; bit `1 << i` stands for
+ * `unitList[i]` from `./module.f.mjs` (`['null', 'undefined', 'false',
+ * 'true']`), so `or(true, false)` collapses to the two boolean bits with no
+ * special-case rule.
+ */
+export type UnionSet = {
+    readonly unit?: number;
+    readonly number?: KindSet<number>;
+    readonly string?: KindSet<string>;
+    readonly bigint?: KindSet<bigint>;
+    readonly array?: KindSet<ArraySet>;
+    readonly object?: KindSet<ObjectSet>;
+};
+/**
+ * A nested type position: an inline {@link UnionSet}, or the name of a rule
+ * in the enclosing {@link RuleSet}. Only recursive definitions are named;
+ * everything else is inlined, so non-recursive schemas are pure trees.
+ */
+export type Node = UnionSet | string;
+/** Named recursive definitions, referenced by {@link Node} strings. */
+export type RuleSet = StringMap<UnionSet>;
+/**
+ * A complete serializable schema: the named recursive definitions plus the
+ * entry node. Produced by `toData` in `./module.f.mjs`.
+ */
+export type Data = readonly [RuleSet, Node];

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

@@ -1,11 +1,18 @@
+/**
+ * Runtime type information (RTTI) — a type-safe schema system for describing and
+ * converting TypeScript types. See `./types.ts` for the type-level API.
+ *
+ * @module
+ *
+ * @import { Includes } from '../array/types.ts'
+ * @import { Assert } from '../../asserts/types.ts'
+ * @import { Equal } from '../ts/types.ts'
+ * @import { Tag0, Primitive0, _Type0, Bigint, Unknown, Tag1, _MakeType1, Array, Record, Or, Type } from './types.ts'
+ */
 import type { Includes } from '../array/types.ts';
 import type { Assert } from '../../asserts/types.ts';
 import type { Equal } from '../ts/types.ts';
 import type { Primitive0, _Type0, Bigint, Unknown, Tag1, _MakeType1, Or, Type } from './types.ts';
-/** @import { Includes } from '../array/types.ts' */
-/** @import { Assert } from '../../asserts/types.ts' */
-/** @import { Equal } from '../ts/types.ts' */
-/** @import { Tag0, Primitive0, _Type0, Bigint, Unknown, Tag1, _MakeType1, Array, Record, Or, Type } from './types.ts' */
 declare const primitive0List: readonly ['bigint', 'boolean', 'number', 'string'];
 export type _Primitive0Pinned = Assert<Equal<Primitive0, typeof primitive0List[number]>>;
 /** @typedef {Assert<Equal<Primitive0, typeof primitive0List[number]>>} _Primitive0Pinned */
@@ -53,7 +60,7 @@ export declare const record: _MakeType1<'record'>;
  * `or` is intentionally a lazy, allocation-free constructor: it captures its
  * arguments in a thunk and does no flattening, deduplication, subset analysis,
  * or canonical-form work. All such algebra lives on the serializable data form
- * — see `issues/143-rtti-data.md`.
+ * — see `./data/README.md`.
  *
  * @template {readonly Type[]} T
  * @param {T} types

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

@@ -3,12 +3,14 @@
  * converting TypeScript types. See `./types.ts` for the type-level API.
  *
  * @module
+ *
+ * @import { Includes } from '../array/types.ts'
+ * @import { Assert } from '../../asserts/types.ts'
+ * @import { Equal } from '../ts/types.ts'
+ * @import { Tag0, Primitive0, _Type0, Bigint, Unknown, Tag1, _MakeType1, Array, Record, Or, Type } from './types.ts'
  */
+
 import { includes } from '../array/module.f.mjs'
-/** @import { Includes } from '../array/types.ts' */
-/** @import { Assert } from '../../asserts/types.ts' */
-/** @import { Equal } from '../ts/types.ts' */
-/** @import { Tag0, Primitive0, _Type0, Bigint, Unknown, Tag1, _MakeType1, Array, Record, Or, Type } from './types.ts' */
 
 const primitive0List = /** @type {const} */ (['bigint', 'boolean', 'number', 'string'])
 
@@ -84,7 +86,7 @@ export const record = type1('record')
  * `or` is intentionally a lazy, allocation-free constructor: it captures its
  * arguments in a thunk and does no flattening, deduplication, subset analysis,
  * or canonical-form work. All such algebra lives on the serializable data form
- * — see `issues/143-rtti-data.md`.
+ * — see `./data/README.md`.
  *
  * @template {readonly Type[]} T
  * @param {T} types

package/fjs/types/rtti/parse/module.f.d.mts

@@ -1,3 +1,51 @@
+/**
+ * Runtime deserialization of unknown values against RTTI schemas.
+ *
+ * The main entry point is `parse(rtti)`, which takes a schema `Type` and returns
+ * a `Parse<T>` function. When called with an unknown value, it returns a `Result`
+ * that is either `['ok', newValue]` or `['error', { path, message }]`.
+ *
+ * **Structs and tuples are open.** A value carrying more than the schema
+ * declares is accepted; `parse` then returns a freshly constructed value that
+ * contains only the declared fields/elements, so the extras are accepted on
+ * the way in and absent on the way out:
+ *
+ * - Tuples: a longer array is accepted; the result has the schema's length.
+ * - Structs: undeclared properties are accepted; the result has only the
+ *   schema's keys.
+ * - Arrays/records: every element/value is itself parsed, so a fresh container is
+ *   always returned even if the inner type is a primitive.
+ *
+ * A member is required exactly when its set excludes `undefined` — an absent
+ * member reads as `undefined`, on both kinds — so a shorter array whose
+ * trailing position admits `undefined` is accepted and the gap is filled.
+ *
+ * Openness is what makes this forward-compatible with extended serialization
+ * formats: a schema-based parser keeps working when newer versions of the
+ * format add extra fields or tuple elements.
+ *
+ * **Do not read "the result has the schema's length" as "tuples are closed"
+ * and add a length check here.** The set a tuple schema describes includes
+ * longer arrays; `Ts<T>` renders the closed approximation only because
+ * TypeScript cannot express the open one (see `../ts/types.ts` `TupleTs`), and
+ * taking that rendering for the model is what produced #1622. A schema that
+ * wants exact members says so — see `../todo/close-type.md`.
+ *
+ * The error shape, path bookkeeping, primitive checks, and schema
+ * recognition (`visit`) come from `../common/module.f.mjs`.
+ *
+ * See `./types.ts` for the `Result`/`Parse` type-level API.
+ *
+ * @module
+ *
+ * @import { Info1, Struct, Tag1, Tuple, Type } from '../types.ts'
+ * @import { Result as CommonResult } from '../../result/types.ts'
+ * @import { StringMap } from '../../object/types.ts'
+ * @import { List } from '../../list/types.ts'
+ * @import { Container, IsContainer, ValidationError, Visitor } from '../common/types.ts'
+ * @import { Unknown } from '../ts/types.ts'
+ * @import { Parse } from './types.ts'
+ */
 import type { Type } from '../types.ts';
 import type { Result as CommonResult } from '../../result/types.ts';
 import type { ValidationError } from '../common/types.ts';

package/fjs/types/rtti/parse/module.f.mjs

@@ -5,34 +5,49 @@
  * a `Parse<T>` function. When called with an unknown value, it returns a `Result`
  * that is either `['ok', newValue]` or `['error', { path, message }]`.
  *
- * Unlike `validate`, which checks an existing value in-place and returns it
- * unchanged on success, `parse` always returns a freshly constructed value that
- * contains only the fields/elements declared by the schema. This makes both
- * structs and tuples effectively closed at runtime, matching the TypeScript
- * type produced by `Ts<T>`:
+ * **Structs and tuples are open.** A value carrying more than the schema
+ * declares is accepted; `parse` then returns a freshly constructed value that
+ * contains only the declared fields/elements, so the extras are accepted on
+ * the way in and absent on the way out:
  *
- * - Tuples: the result has exactly the schema's length; extra elements are dropped.
- * - Structs: the result contains only the schema's keys; extra properties are dropped.
+ * - Tuples: a longer array is accepted; the result has the schema's length.
+ * - Structs: undeclared properties are accepted; the result has only the
+ *   schema's keys.
  * - Arrays/records: every element/value is itself parsed, so a fresh container is
  *   always returned even if the inner type is a primitive.
  *
- * This also provides forward compatibility with extended serialization formats:
- * a schema-based parser keeps working when newer versions of the format add
- * extra fields or tuple elements.
+ * A member is required exactly when its set excludes `undefined` — an absent
+ * member reads as `undefined`, on both kinds — so a shorter array whose
+ * trailing position admits `undefined` is accepted and the gap is filled.
+ *
+ * Openness is what makes this forward-compatible with extended serialization
+ * formats: a schema-based parser keeps working when newer versions of the
+ * format add extra fields or tuple elements.
+ *
+ * **Do not read "the result has the schema's length" as "tuples are closed"
+ * and add a length check here.** The set a tuple schema describes includes
+ * longer arrays; `Ts<T>` renders the closed approximation only because
+ * TypeScript cannot express the open one (see `../ts/types.ts` `TupleTs`), and
+ * taking that rendering for the model is what produced #1622. A schema that
+ * wants exact members says so — see `../todo/close-type.md`.
  *
  * The error shape, path bookkeeping, primitive checks, and schema
- * recognition (`visit`) are shared with `validate` through
- * `../common/module.f.mjs`; only container construction differs.
+ * recognition (`visit`) come from `../common/module.f.mjs`.
  *
  * See `./types.ts` for the `Result`/`Parse` type-level API.
  *
  * @module
+ *
+ * @import { Info1, Struct, Tag1, Tuple, Type } from '../types.ts'
+ * @import { Result as CommonResult } from '../../result/types.ts'
+ * @import { StringMap } from '../../object/types.ts'
+ * @import { List } from '../../list/types.ts'
+ * @import { Container, IsContainer, ValidationError, Visitor } from '../common/types.ts'
+ * @import { Unknown } from '../ts/types.ts'
+ * @import { Parse } from './types.ts'
  */
-/** @import { Info1, Struct, Tag1, Tuple, Type } from '../types.ts' */
-/** @import { Result as CommonResult } from '../../result/types.ts' */
+
 import { ok } from '../../result/module.f.mjs'
-/** @import { StringMap } from '../../object/types.ts' */
-/** @import { List } from '../../list/types.ts' */
 import { reverse, toArray } from '../../list/module.f.mjs'
 import {
     constPrimitiveValidate,
@@ -44,9 +59,6 @@ import {
     verror,
     visit,
 } from '../common/module.f.mjs'
-/** @import { Container, IsContainer, ValidateE, ValidationError, Visitor } from '../common/types.ts' */
-/** @import { Unknown } from '../ts/types.ts' */
-/** @import { Parse } from './types.ts' */
 
 const { entries } = Object
 
@@ -76,11 +88,10 @@ const orderedEntries = list =>
     toArray(reverse(list))
 
 /**
- * Builds a parser for `array` or `record` schemas. Mirrors `validate`'s
- * `containerValidate`, but rebuilds a fresh container from each item's parsed
- * result instead of returning the value unchanged. The inner item parser is
- * instantiated lazily (only when the container is non-empty) so recursive
- * schemas don't recurse forever on empty containers.
+ * Builds a parser for `array` or `record` schemas: rebuilds a fresh container
+ * from each item's parsed result. The inner item parser is instantiated lazily
+ * (only when the container is non-empty) so recursive schemas don't recurse
+ * forever on empty containers.
  */
 const containerParse =
     /**
@@ -98,7 +109,7 @@ const containerParse =
         if (e.length === 0) {
             return /** @type {any} */ (ok(rebuild([])))
         }
-        const itemParse = /** @type {(v: Unknown) => _ItemResult} */ (/** @type {any} */ (parse(item)))
+        const itemParse = /** @type {any} */ (parse(item))
         const r = eachEntry(e, (_k, v) => itemParse(v), emptyEntries, consEntry)
         return r[0] === 'error' ? r : /** @type {any} */ (ok(rebuild(orderedEntries(r[1]))))
     }
@@ -108,10 +119,10 @@ const arrayParse = containerParse(isArray, arrayRebuild)
 const recordParse = containerParse(isObject, recordRebuild)
 
 /**
- * Builds a parser for `Tuple` or `Struct` const schemas. Mirrors `validate`'s
- * `constContainerValidate`: it iterates the schema's entries (so extra tuple
- * elements and undeclared struct keys are dropped) and rebuilds the result
- * from each parsed item.
+ * Builds a parser for `Tuple` or `Struct` const schemas. It iterates the
+ * *schema's* entries, which is what makes both kinds open: a longer array or
+ * an undeclared key is never visited, so it is accepted and left out of the
+ * rebuilt result.
  */
 const constContainerParse =
     /**
@@ -128,7 +139,7 @@ const constContainerParse =
         }
         const r = eachEntry(
             entries(rtti),
-            (k, t) => /** @type {_ItemResult} */ (/** @type {any} */ (parse(t))(getItem(value, k))),
+            (k, t) => (/** @type {any} */ (parse(t))(getItem(value, k))),
             emptyEntries,
             consEntry,
         )
@@ -154,7 +165,7 @@ const orParse =
      * @returns {Parse<() => readonly ['or', ...T]>}
      */
     rtti =>
-        /** @type {any} */ (orVisit(/** @type {(t: Type) => ValidateE} */ (/** @type {any} */ (parse)))(rtti))
+        /** @type {any} */ (orVisit(/** @type {any} */ (parse))(rtti))
 
 /**
  * Creates a parser function for the given RTTI schema.
@@ -173,10 +184,10 @@ const orParse =
  * p([1, 2, 3])         // ['ok', [1, 2, 3]]   (a new array)
  * p([1, 'two'])        // ['error', { path: ['1'], message: 'unexpected value' }]
  *
- * // tuples are closed: extra elements are dropped
+ * // open: a longer array is accepted, and the extra is not carried over
  * parse([number, number])([1, 2, 3]) // ['ok', [1, 2]]
  *
- * // structs drop undeclared keys
+ * // open: an undeclared key is accepted, and not carried over
  * parse({ a: number })({ a: 1, b: 2 }) // ['ok', { a: 1 }]
  * ```
  */
@@ -193,4 +204,4 @@ const parseVisitor = /** @type {any} */ ({
 
 /** @type {<T extends Type>(rtti: T) => Parse<T>} */
 export const parse = rtti =>
-    /** @type {any} */ (visit(parseVisitor)(rtti))
+    (visit(parseVisitor)(rtti))

package/fjs/types/rtti/parse/proof.f.d.mts

@@ -64,12 +64,13 @@ export declare const proof: {
         };
         tuple: {
             ok: () => void;
-            extraItemsDropped: () => void;
+            extraItemsAcceptedAndDropped: () => void;
+            shortArrayFillsAnOptionalPosition: () => void;
             error: () => void;
         };
         struct: {
             ok: () => void;
-            extraKeysDropped: () => void;
+            extraKeysAcceptedAndDropped: () => void;
             error: () => void;
         };
     };

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

@@ -8,7 +8,11 @@
 
 import { parse } from './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 {
+    assert,
+    assertEq,
+    assertStructurallySame,
+} from '../../../asserts/module.f.mjs'
 
 /** @type {(r: readonly [string, unknown]) => void} */
 const assertOk = ([k]) => { assertEq(k, 'ok', 'expected ok') }
@@ -31,33 +35,9 @@ 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')
     }
 
-/** @type {(a: unknown, b: unknown) => void} */
-const assertDeepEqual = (a, b) => {
-    if (a === b) { return }
-    if (a instanceof Array && b instanceof Array) {
-        if (a.length !== b.length) { throw `array length ${a.length} != ${b.length}` }
-        for (let i = 0; i < a.length; i++) { assertDeepEqual(a[i], b[i]) }
-        return
-    }
-    if (typeof a === 'object' && a !== null && typeof b === 'object' && b !== null) {
-        const ka = Object.keys(a).sort()
-        const kb = Object.keys(b).sort()
-        if (ka.length !== kb.length) { throw `key count ${ka.length} != ${kb.length}` }
-        for (let i = 0; i < ka.length; i++) {
-            if (ka[i] !== kb[i]) { throw `key ${ka[i]} != ${kb[i]}` }
-            assertDeepEqual((/** @type {any} */ (a))[ka[i]], (/** @type {any} */ (b))[kb[i]])
-        }
-        return
-    }
-    throw `not deep-equal: ${String(a)} vs ${String(b)}`
-}
-
 export const proof = {
     boolean: {
         ok: () => {
@@ -129,32 +109,32 @@ export const proof = {
             error: () => assertError(parse(/** @type {const} */ (42))(43)),
         },
         nan: {
-            ok: () => assertOk(parse(/** @type {number} */ (NaN))(NaN)),
+            ok: () => assertOk(parse(NaN)(NaN)),
             error: () => {
-                assertError(parse(/** @type {number} */ (NaN))(0))
+                assertError(parse(NaN)(0))
                 assertError(parse(/** @type {const} */ (0))(NaN))
                 assertError(parse(/** @type {const} */ (42))(NaN))
             },
         },
         infinity: {
             ok: () => {
-                assertOk(parse(/** @type {number} */ (Infinity))(Infinity))
-                assertOk(parse(/** @type {number} */ (-Infinity))(-Infinity))
+                assertOk(parse(Infinity)(Infinity))
+                assertOk(parse(-Infinity)(-Infinity))
             },
             error: () => {
-                assertError(parse(/** @type {number} */ (Infinity))(-Infinity))
-                assertError(parse(/** @type {number} */ (Infinity))(0))
+                assertError(parse(Infinity)(-Infinity))
+                assertError(parse(Infinity)(0))
             },
         },
         signedZero: {
             // `Object.is` distinguishes +0 and -0; `===` treats them equal.
             distinct: () => {
                 assertError(parse(/** @type {const} */ (0))(-0))
-                assertError(parse(/** @type {number} */ (-0))(0))
+                assertError(parse(-0)(0))
             },
             self: () => {
                 assertOk(parse(/** @type {const} */ (0))(0))
-                assertOk(parse(/** @type {number} */ (-0))(-0))
+                assertOk(parse(-0)(-0))
             },
         },
         string: {
@@ -173,28 +153,47 @@ export const proof = {
             ok: () => {
                 const t = /** @type {const} */ ([42, 'hello'])
                 const r = parse(t)([42, 'hello'])
-                assertDeepEqual(unwrap(r), [42, 'hello'])
+                assertStructurallySame(unwrap(r), [42, 'hello'])
             },
-            // The key behavior change vs `validate`: extra tuple elements are dropped.
-            extraItemsDropped: () => {
+            // A tuple is OPEN: a longer array is accepted, and the extras are
+            // absent from what `parse` builds. This is deliberate — see
+            // "Structs and tuples are open" in ../README.md. Do not add a
+            // length check here 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`),
+            // and reading it as a design decision is what produced #1622.
+            extraItemsAcceptedAndDropped: () => {
                 const r = parse(/** @type {const} */ ([42]))([42, 'extra'])
-                assertDeepEqual(unwrap(r), [42])
+                assertStructurallySame(unwrap(r), [42])
+                const long = parse(/** @type {const} */ ([42]))([42, 1, 2, 3])
+                assertStructurallySame(unwrap(long), [42])
+            },
+            // An absent member reads as `undefined`, so a position is required
+            // exactly when its set excludes `undefined` — the same rule the
+            // data form states for object keys, applied to arrays.
+            shortArrayFillsAnOptionalPosition: () => {
+                const r = parse([number, option(string)])([42])
+                assertStructurallySame(unwrap(r), [42, undefined])
             },
             error: () => {
                 assertError(parse(/** @type {const} */ ([42]))([99]))
                 assertError(parse(/** @type {const} */ ([42]))({}))
+                // `42` excludes `undefined`, so position 0 is required.
+                assertError(parse(/** @type {const} */ ([42]))([]))
             },
         },
         struct: {
             ok: () => {
                 const t = /** @type {const} */ ({ a: 42, b: 'hello' })
                 const r = parse(t)({ a: 42, b: 'hello' })
-                assertDeepEqual(unwrap(r), { a: 42, b: 'hello' })
+                assertStructurallySame(unwrap(r), { a: 42, b: 'hello' })
             },
-            // Undeclared properties are dropped from the constructed value.
-            extraKeysDropped: () => {
+            // A struct is OPEN, on the same terms as a tuple: undeclared
+            // properties are accepted and absent from what `parse` builds.
+            // See "Structs and tuples are open" in ../README.md.
+            extraKeysAcceptedAndDropped: () => {
                 const r = parse(/** @type {const} */ ({ a: /** @type {const} */ (42) }))({ a: 42, b: 'extra' })
-                assertDeepEqual(unwrap(r), { a: 42 })
+                assertStructurallySame(unwrap(r), { a: 42 })
             },
             error: () => {
                 assertError(parse(/** @type {const} */ ({ a: 42 }))({ a: 99 }))
@@ -205,19 +204,19 @@ export const proof = {
     array: {
         empty: () => {
             const r = parse(array(number))([])
-            assertDeepEqual(unwrap(r), [])
+            assertStructurallySame(unwrap(r), [])
         },
         ok: () => {
             const r = parse(array(number))([1, 2, 3])
-            assertDeepEqual(unwrap(r), [1, 2, 3])
+            assertStructurallySame(unwrap(r), [1, 2, 3])
         },
         // `parse` always constructs a new array, even when the inner type is a primitive.
         freshArray: () => {
             const input = [1, 2, 3]
             /** @type {readonly number[]} */
             const out = unwrap(parse(array(number))(input))
-            assert(out !== /** @type {unknown} */ (input), 'expected a fresh array')
-            assertDeepEqual(out, [1, 2, 3])
+            assert(out !== input, 'expected a fresh array')
+            assertStructurallySame(out, [1, 2, 3])
         },
         error: () => {
             assertError(parse(array(number))([1, 'two', 3]))
@@ -226,26 +225,26 @@ export const proof = {
         },
         nested: () => {
             const r = parse(array(array(boolean)))([[true, false], [false]])
-            assertDeepEqual(unwrap(r), [[true, false], [false]])
+            assertStructurallySame(unwrap(r), [[true, false], [false]])
             assertError(parse(array(array(boolean)))([[true, 42]]))
         },
     },
     record: {
         empty: () => {
             const r = parse(record(number))({})
-            assertDeepEqual(unwrap(r), {})
+            assertStructurallySame(unwrap(r), {})
         },
         ok: () => {
             const r = parse(record(string))({ a: 'hello', b: 'world' })
-            assertDeepEqual(unwrap(r), { a: 'hello', b: 'world' })
+            assertStructurallySame(unwrap(r), { a: 'hello', b: 'world' })
         },
         // `parse` always constructs a new record.
         freshRecord: () => {
             const input = { a: 1, b: 2 }
             /** @type {Record<string, number>} */
             const out = unwrap(parse(record(number))(input))
-            assert(out !== /** @type {unknown} */ (input), 'expected a fresh record')
-            assertDeepEqual(out, { a: 1, b: 2 })
+            assert(out !== input, 'expected a fresh record')
+            assertStructurallySame(out, { a: 1, b: 2 })
         },
         error: () => {
             assertError(parse(record(number))({ a: 1, b: 'two' }))
@@ -294,7 +293,7 @@ export const proof = {
             /** @type {readonly number[]} */
             const out = unwrap(parse(t)([1, 2, 3]))
             // The const tuple `[number]` matches first and returns a length-1 result.
-            assertDeepEqual(out, [1])
+            assertStructurallySame(out, [1])
         },
     },
     option: {

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

@@ -1,4 +1,6 @@
-/** @import { StringMap } from '../object/types.ts' */
+/**
+ * @import { StringMap } from '../object/types.ts'
+ */
 import type { StringMap } from '../object/types.ts';
 export type _Tests = StringMap<readonly unknown[]>;
 export declare const proof: {

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

@@ -1,4 +1,8 @@
-/** @import { StringMap } from '../object/types.ts' */
+/**
+ * @import { StringMap } from '../object/types.ts'
+ */
+
+import { assertNotNullish } from '../../asserts/module.f.mjs'
 
 /** @typedef {StringMap<readonly unknown[]>} _Tests */
 
@@ -14,7 +18,7 @@ const tests = {
 }
 
 export const proof = {
-    typeof: Object.fromEntries(Object.entries(tests).map(([k, a]) => [k, /** @type {readonly unknown[]} */ (a).map(v => () => {
+    typeof: Object.fromEntries(Object.entries(tests).map(([k, a]) => [k, assertNotNullish(a).map(v => () => {
         if (typeof v !== k) { throw `typeof ${v} !== ${k}` }
     })])),
 }