functionalscript 0.46.0 → 0.47.0

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

@@ -18,6 +18,12 @@
  * - `eachEntry`: the container entry loop (array/record/tuple/struct). Callers
  *   choose what (if anything) to accumulate, so a caller that only needs
  *   pass/fail pays no allocation per entry.
+ * - `tupleSchemaEntries`/`structSchemaEntries`: what a container schema
+ *   declares, per kind — the entry list its readers walk.
+ * - `undeclaredMembers`: the other half of the loop — the members a container
+ *   schema does not name, which a bare schema rejects and a `rest` one holds
+ *   to its rest. The data form walks it too, so the two readers state one
+ *   rule.
  * - `orVisit`: the shared `or` handler — try each variant's recursive walker,
  *   return the first match.
  *
@@ -27,16 +33,16 @@
  * @module
  *
  * @import { Primitive, Unknown } from '../ts/types.ts'
- * @import { Const, Info0, Primitive0, Tag1, Tuple, Type } from '../types.ts'
+ * @import { Const, Info0, Primitive0, Struct, Tag1, Tuple, Type } from '../types.ts'
  * @import { Error, Result as CommonResult } from '../../result/types.ts'
  * @import { StringMap } from '../../object/types.ts'
- * @import { Validate, Visitor, IsContainer, Container, ResultE, ValidateE, ValidationError } from './types.ts'
+ * @import { Validate, Visitor, IsContainer, Container, ResultE, SchemaEntries, ValidateE, ValidationError } from './types.ts'
  */
 import type { Primitive, Unknown } from '../ts/types.ts';
-import type { Info0, Primitive0, Type } from '../types.ts';
+import type { Info0, Primitive0, Struct, Tuple, Type } from '../types.ts';
 import type { Error, Result as CommonResult } from '../../result/types.ts';
 import type { StringMap } from '../../object/types.ts';
-import type { Validate, Visitor, IsContainer, ResultE, ValidateE, ValidationError } from './types.ts';
+import type { Validate, Visitor, IsContainer, ResultE, SchemaEntries, ValidateE, ValidationError } from './types.ts';
 /** Builds an error result with empty path and the given message. */
 /** @type {(message: string) => Error<ValidationError>} */
 export declare const verror: (message: string) => Error<ValidationError>;
@@ -85,6 +91,73 @@ export declare const isObject: IsContainer<StringMap<Unknown>>;
  * instead and pays no allocation per entry.
  */
 export declare const eachEntry: <V, R, A>(entries: ReadonlyArray<readonly [string, V]>, item: (k: string, v: V) => CommonResult<R, ValidationError>, init: A, accumulate: (acc: A, k: string, value: R) => A) => CommonResult<A, ValidationError>;
+/**
+ * What a `Tuple` schema declares, read by **length**.
+ *
+ * `Array.from` yields `undefined` for a hole and preserves the schema's
+ * length, so a hole is a declared position whose schema is `undefined` — which
+ * is a `Const` schema in its own right, and exactly what reading index `0` of
+ * `new Array(1)` gives. That is the reading `../data/module.f.mjs`'s
+ * `containerUnion` has always had, so the canonical data form stays fixed.
+ *
+ * `Array.from` walks the iterator, which is the *same* walk `containerUnion`
+ * makes, and that is the point rather than an accident: the two agree by
+ * construction. It holds even for a schema carrying an overridden
+ * `Symbol.iterator`, where reading indices here would disagree with the data
+ * form all over again — verified: such a schema is read as `number` by the
+ * entry reading and as `string` by `containerUnion`. Reading *both* by index
+ * is defensible, but it changes the canonical, content-addressed data form and
+ * belongs with that decision, not here. FunctionalScript cannot build such a
+ * schema in the first place: it has no symbols and no mutation, so the case is
+ * reachable only from plain JavaScript, which is also why no proof can pin it.
+ *
+ * `Object.entries` skips holes, which is why it is not used here: it would
+ * make `new Array(1)` and `[]` the same schema while `[undefined]` stayed
+ * different from both. It also yields a non-index own property, which is no
+ * position either — `getItem` reads a tuple by index, so such a key was
+ * declared and then matched against `value[NaN]`. `Array.from` answers
+ * positions only. On a plain dense array the two agree exactly.
+ *
+ * @type {SchemaEntries<Tuple>}
+ */
+export declare const tupleSchemaEntries: SchemaEntries<Tuple>;
+/**
+ * What a `Struct` schema declares: its enumerable own keys. A struct has no
+ * holes, so there is nothing for this to disagree with.
+ *
+ * @type {SchemaEntries<Struct>}
+ */
+export declare const structSchemaEntries: SchemaEntries<Struct>;
+/**
+ * The members of `value` that `declared` does not name — every one the
+ * schema's `rest` has to answer for, as `[key, value]` pairs.
+ *
+ * `declared` is a container schema's own key list, so for a struct these are
+ * its undeclared own keys, and for a tuple they are the positions past the
+ * prefix together with every own key that is no position at all.
+ *
+ * **A tuple's positions are read, not enumerated.** `length` is what says how
+ * far an array reaches, and every index below it that *reads* a value is a
+ * member the `rest` must answer for — including one supplied by the prototype,
+ * which no own-entry walk sees ({@link readIndices} is the walk). Filtering
+ * `Object.entries` alone accepted `[42, , ]` carrying an inherited `1: 99`
+ * against `rest([42], string)`, handing back an array whose index 1 reads a
+ * number the rendered tail types as `string`. A genuinely absent index is
+ * skipped instead: a hole is no member, so it meets no `rest` — the same rule
+ * the struct kind states by walking own keys.
+ *
+ * An index at or above `length` is a different matter and is not answered
+ * here: it is readable through the prototype and no walk bounded by the value
+ * reaches it. See "Beyond `length`" in `../README.md`.
+ *
+ * Passing an empty `declared` asks for every member, which is what the uniform
+ * `array`/`record` readers want — so they share this walk rather than reaching
+ * for `Object.entries` and disagreeing with the data form on an inherited
+ * index.
+ *
+ * @type {(declared: readonly string[], value: ReadonlyArray<Unknown> | StringMap<Unknown>) => ReadonlyArray<readonly [string, Unknown]>}
+ */
+export declare const undeclaredMembers: (declared: readonly string[], value: ReadonlyArray<Unknown> | StringMap<Unknown>) => ReadonlyArray<readonly [string, Unknown]>;
 /**
  * First variant in `variants` that `recurse` accepts, else `verror('no match')`.
  *
@@ -103,7 +176,7 @@ export declare const orVisit: (recurse: (t: Type) => ValidateE) => (variants: re
  *
  * - `Thunk` schemas are evaluated once to read the `Info` descriptor, then
  *   routed by tag (`'const'`, `'array'`, `'record'`, `'unknown'`, `'or'`,
- *   or a `Tag0` primitive).
+ *   `'rest'`, or a `Tag0` primitive).
  * - `Const` schemas (primitives, tuples, structs) are routed directly to
  *   `tuple`, `struct`, or `constPrimitive`.
  */

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

@@ -18,6 +18,12 @@
  * - `eachEntry`: the container entry loop (array/record/tuple/struct). Callers
  *   choose what (if anything) to accumulate, so a caller that only needs
  *   pass/fail pays no allocation per entry.
+ * - `tupleSchemaEntries`/`structSchemaEntries`: what a container schema
+ *   declares, per kind — the entry list its readers walk.
+ * - `undeclaredMembers`: the other half of the loop — the members a container
+ *   schema does not name, which a bare schema rejects and a `rest` one holds
+ *   to its rest. The data form walks it too, so the two readers state one
+ *   rule.
  * - `orVisit`: the shared `or` handler — try each variant's recursive walker,
  *   return the first match.
  *
@@ -27,10 +33,10 @@
  * @module
  *
  * @import { Primitive, Unknown } from '../ts/types.ts'
- * @import { Const, Info0, Primitive0, Tag1, Tuple, Type } from '../types.ts'
+ * @import { Const, Info0, Primitive0, Struct, Tag1, Tuple, Type } from '../types.ts'
  * @import { Error, Result as CommonResult } from '../../result/types.ts'
  * @import { StringMap } from '../../object/types.ts'
- * @import { Validate, Visitor, IsContainer, Container, ResultE, ValidateE, ValidationError } from './types.ts'
+ * @import { Validate, Visitor, IsContainer, Container, ResultE, SchemaEntries, ValidateE, ValidationError } from './types.ts'
  */
 
 import { assert } from '../../../asserts/module.f.mjs'
@@ -128,6 +134,157 @@ export const eachEntry =
         return ok(acc)
     }
 
+/**
+ * What a `Tuple` schema declares, read by **length**.
+ *
+ * `Array.from` yields `undefined` for a hole and preserves the schema's
+ * length, so a hole is a declared position whose schema is `undefined` — which
+ * is a `Const` schema in its own right, and exactly what reading index `0` of
+ * `new Array(1)` gives. That is the reading `../data/module.f.mjs`'s
+ * `containerUnion` has always had, so the canonical data form stays fixed.
+ *
+ * `Array.from` walks the iterator, which is the *same* walk `containerUnion`
+ * makes, and that is the point rather than an accident: the two agree by
+ * construction. It holds even for a schema carrying an overridden
+ * `Symbol.iterator`, where reading indices here would disagree with the data
+ * form all over again — verified: such a schema is read as `number` by the
+ * entry reading and as `string` by `containerUnion`. Reading *both* by index
+ * is defensible, but it changes the canonical, content-addressed data form and
+ * belongs with that decision, not here. FunctionalScript cannot build such a
+ * schema in the first place: it has no symbols and no mutation, so the case is
+ * reachable only from plain JavaScript, which is also why no proof can pin it.
+ *
+ * `Object.entries` skips holes, which is why it is not used here: it would
+ * make `new Array(1)` and `[]` the same schema while `[undefined]` stayed
+ * different from both. It also yields a non-index own property, which is no
+ * position either — `getItem` reads a tuple by index, so such a key was
+ * declared and then matched against `value[NaN]`. `Array.from` answers
+ * positions only. On a plain dense array the two agree exactly.
+ *
+ * @type {SchemaEntries<Tuple>}
+ */
+export const tupleSchemaEntries = rtti =>
+    Array.from(rtti, (t, i) => [String(i), t])
+
+/**
+ * What a `Struct` schema declares: its enumerable own keys. A struct has no
+ * holes, so there is nothing for this to disagree with.
+ *
+ * @type {SchemaEntries<Struct>}
+ */
+export const structSchemaEntries = rtti =>
+    Object.entries(rtti)
+
+/**
+ * The position `k` names, or `undefined` when `k` names no position at all.
+ *
+ * Only the canonical spelling of a non-negative integer is an index: `'-1'`,
+ * `'01'`, `'1.5'` and `' 1'` are ordinary properties of an array object,
+ * however `Number` maps them. Round-tripping the number back through `String`
+ * is what rejects every non-canonical spelling at once, rather than one at a
+ * time.
+ *
+ * And only one **below `2 ** 32 - 1`**, which is where the language draws the
+ * line rather than a bound chosen here: assigning `a['4294967295']` creates an
+ * ordinary enumerable property and leaves `a.length` alone. Reading such a key
+ * as an index put it past every `length`-bounded walk *and* past the non-index
+ * filter, so it was no member on either path and an undeclared property rode
+ * through a closed container.
+ *
+ * @type {(k: string) => number | undefined}
+ */
+const arrayIndex = k => {
+    const i = Number(k)
+    return Number.isInteger(i) && i >= 0 && i < 2 ** 32 - 1 && String(i) === k ? i : undefined
+}
+
+/**
+ * Every index below `length` at which `value` reads something, ascending.
+ *
+ * Bounded by what the value and its prototypes **carry** rather than by
+ * `length`: an index that reads a value is an own property of the array or of
+ * something on its prototype chain, so enumerating those names finds every one
+ * without materializing the range. Walking `0 … length - 1` instead turned a
+ * `new Array(2 ** 32 - 1)` — which carries one own property, `length` — into
+ * billions of iterations before any check could reject it.
+ *
+ * The own names are **already the answer** for all but a pathological value:
+ * `[[OwnPropertyKeys]]` yields integer indices ascending and without repeats,
+ * so an ordinary array pays one linear pass and no sort. Only an index the
+ * chain supplies and the value does not is merged in, and that set is empty
+ * unless someone has put an index on a prototype — which is why the dedup it
+ * needs may be quadratic without costing an ordinary array anything. Deduping
+ * the whole list instead made every `array(t)` read quadratic in its length:
+ * 829 ms at 40 000 elements against 3 ms at 1 000.
+ *
+ * No `in` test: a name reached this way is a property of the value or of
+ * something it inherits from, so the array reads at it by construction.
+ *
+ * @type {(value: ReadonlyArray<Unknown>) => readonly number[]}
+ */
+const readIndices = value => {
+    const { length } = value
+    /** @type {(names: readonly string[]) => readonly number[]} */
+    const indices = names => names.flatMap(k => {
+        const i = arrayIndex(k)
+        return i !== undefined && i < length ? [i] : []
+    })
+    const own = indices(Object.getOwnPropertyNames(value))
+    /** @type {readonly number[]} */
+    let chain = []
+    for (let o = Object.getPrototypeOf(value); o !== null; o = Object.getPrototypeOf(o)) {
+        chain = [...chain, ...indices(Object.getOwnPropertyNames(o))]
+    }
+    if (chain.length === 0) { return own }
+    const inherited = chain
+        .filter(i => !Object.hasOwn(value, i))
+        .filter((i, at, a) => a.indexOf(i) === at)
+    return inherited.length === 0 ? own : [...own, ...inherited].toSorted((a, b) => a - b)
+}
+
+/**
+ * The members of `value` that `declared` does not name — every one the
+ * schema's `rest` has to answer for, as `[key, value]` pairs.
+ *
+ * `declared` is a container schema's own key list, so for a struct these are
+ * its undeclared own keys, and for a tuple they are the positions past the
+ * prefix together with every own key that is no position at all.
+ *
+ * **A tuple's positions are read, not enumerated.** `length` is what says how
+ * far an array reaches, and every index below it that *reads* a value is a
+ * member the `rest` must answer for — including one supplied by the prototype,
+ * which no own-entry walk sees ({@link readIndices} is the walk). Filtering
+ * `Object.entries` alone accepted `[42, , ]` carrying an inherited `1: 99`
+ * against `rest([42], string)`, handing back an array whose index 1 reads a
+ * number the rendered tail types as `string`. A genuinely absent index is
+ * skipped instead: a hole is no member, so it meets no `rest` — the same rule
+ * the struct kind states by walking own keys.
+ *
+ * An index at or above `length` is a different matter and is not answered
+ * here: it is readable through the prototype and no walk bounded by the value
+ * reaches it. See "Beyond `length`" in `../README.md`.
+ *
+ * Passing an empty `declared` asks for every member, which is what the uniform
+ * `array`/`record` readers want — so they share this walk rather than reaching
+ * for `Object.entries` and disagreeing with the data form on an inherited
+ * index.
+ *
+ * @type {(declared: readonly string[], value: ReadonlyArray<Unknown> | StringMap<Unknown>) => ReadonlyArray<readonly [string, Unknown]>}
+ */
+export const undeclaredMembers = (declared, value) => {
+    /** @type {(k: string) => boolean} */
+    const undeclared = k => !declared.some(d => d === k)
+    if (!commonIsArray(value)) {
+        return Object.entries(value).filter(([k]) => undeclared(k))
+    }
+    return [
+        ...readIndices(value)
+            .filter(i => undeclared(String(i)))
+            .map(i => /** @type {const} */ ([String(i), value[i]])),
+        ...Object.entries(value).filter(([k]) => arrayIndex(k) === undefined && undeclared(k)),
+    ]
+}
+
 /**
  * First variant in `variants` that `recurse` accepts, else `verror('no match')`.
  *
@@ -157,7 +314,7 @@ export const orVisit =
  *
  * - `Thunk` schemas are evaluated once to read the `Info` descriptor, then
  *   routed by tag (`'const'`, `'array'`, `'record'`, `'unknown'`, `'or'`,
- *   or a `Tag0` primitive).
+ *   `'rest'`, or a `Tag0` primitive).
  * - `Const` schemas (primitives, tuples, structs) are routed directly to
  *   `tuple`, `struct`, or `constPrimitive`.
  */
@@ -182,6 +339,14 @@ export const visit =
                 case 'record': return v.record(value[0])
                 case 'unknown': return v.unknown()
                 case 'or': return v.or(value)
+                case 'rest': {
+                    const [c, r] = value
+                    // `rest`'s container is a `ConstObject`, which is exactly
+                    // the non-null objects among the `Const`s — a `Thunk` is a
+                    // function, and every other `Const` is a primitive.
+                    assert(typeof c === 'object' && c !== null, c)
+                    return v.rest(c, r)
+                }
             }
             return v.primitive0(tag)
         }

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

@@ -9,5 +9,19 @@ export declare const proof: {
     noAccumulate: () => void;
     firstErrorWins: () => void;
     shortCircuits: () => void;
+    undeclared: {
+        struct: () => void;
+        tuple: () => void;
+        none: () => void;
+        holeIsNoMember: () => void;
+        lengthDoesNotBoundTheWalk: () => void;
+    };
+    schemaEntries: {
+        tuple: () => void;
+        tupleHole: () => void;
+        tupleHoleIsTheDenseReading: () => void;
+        struct: () => void;
+        empty: () => void;
+    };
     pathPrefixed: () => void;
 };

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

@@ -3,9 +3,9 @@
  * @import { ValidationError } from './types.ts'
  */
 
-import { eachEntry } from './module.f.mjs'
+import { eachEntry, structSchemaEntries, tupleSchemaEntries, undeclaredMembers } from './module.f.mjs'
 import { error, ok } from '../../result/module.f.mjs'
-import { assert, assertEq } from '../../../asserts/module.f.mjs'
+import { assert, assertEq, assertStructurallySame } from '../../../asserts/module.f.mjs'
 
 /** @typedef {ReadonlyArray<readonly [string, number]>} _Entries */
 
@@ -54,6 +54,65 @@ export const proof = {
         assert(r[0] === 'error')
         assertEq(calls, 1)
     },
+    // The other half of a container's loop: the members a bare schema rejects
+    // and a `rest` one holds to its rest. One function answers both kinds — a
+    // struct's undeclared own keys, and an array's positions past the prefix
+    // together with the own keys that are no position at all.
+    undeclared: {
+        struct: () => {
+            const r = undeclaredMembers(['a'], { a: 1, b: 2 })
+            assertStructurallySame(r, [['b', 2]])
+        },
+        // The positions come first, in index order, then the keys that name
+        // none — so the reported error path is the leftmost failing member.
+        tuple: () => {
+            const r = undeclaredMembers(['0'], Object.assign([1, 2], { foo: 3, '01': 4 }))
+            assertStructurallySame(r, [['1', 2], ['foo', 3], ['01', 4]])
+        },
+        none: () => assertEq(undeclaredMembers(['a'], { a: 1 }).length, 0),
+        // A hole is no member, so it meets no `rest` — which is why the array
+        // kind also answers with its `length`; see `fits` in
+        // `../parse/module.f.mjs`.
+        holeIsNoMember: () => assertEq(undeclaredMembers(['0'], [1, , 3]).length, 1),
+        // The walk is bounded by what the value and its prototypes carry, not
+        // by `length` — this one carries a single own property, `length`, so
+        // it answers at once. Materializing the range instead exhausted memory
+        // long before any check could reject the value.
+        lengthDoesNotBoundTheWalk: () =>
+            assertEq(undeclaredMembers([], new Array(2 ** 32 - 1)).length, 0),
+        // An index the prototype supplies is a member too, and a canonical
+        // numeric key past the index range is one by the non-index half. Both
+        // need in-place mutation to build, so they are pinned in
+        // `../host.proof.mjs` — see its module doc.
+    },
+    // What a container schema declares, per kind. A tuple is read by length,
+    // so a hole is a declared position whose schema is `undefined` — the same
+    // reading `../data/module.f.mjs` has, and the reason the two kinds need
+    // different entry readers at all.
+    schemaEntries: {
+        tuple: () => assertStructurallySame(
+            tupleSchemaEntries([1, 'a']),
+            [['0', 1], ['1', 'a']],
+        ),
+        // `Object.entries` would answer `[]` here, and `[['0', undefined]]` for
+        // `[undefined]` — two schemas that denote the same set, read as two.
+        tupleHole: () => assertStructurallySame(
+            tupleSchemaEntries(new Array(1)),
+            [['0', undefined]],
+        ),
+        tupleHoleIsTheDenseReading: () => assertStructurallySame(
+            tupleSchemaEntries(new Array(1)),
+            tupleSchemaEntries([undefined]),
+        ),
+        struct: () => assertStructurallySame(
+            structSchemaEntries({ a: 1, b: 'x' }),
+            [['a', 1], ['b', 'x']],
+        ),
+        empty: () => {
+            assertEq(tupleSchemaEntries([]).length, 0)
+            assertEq(structSchemaEntries({}).length, 0)
+        },
+    },
     pathPrefixed: () => {
         /** @type {(k: string, v: number) => Result<number, ValidationError>} */
         const nested = (k, v) =>

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

@@ -4,7 +4,7 @@
  * @module
  */
 import type { Primitive, Unknown } from '../ts/types.ts';
-import type { Primitive0, Struct, Tag1, Tuple, Type } from '../types.ts';
+import type { ConstObject, Primitive0, Struct, Tag1, Tuple, Type } from '../types.ts';
 import type { Result as CommonResult } from '../../result/types.ts';
 import type { Ts } from '../ts/types.ts';
 import type { StringMap } from '../../object/types.ts';
@@ -26,6 +26,13 @@ export type Validate<T extends Type> = (value: Unknown) => Result<T>;
 export type Visitor<R> = {
     readonly tuple: (rtti: Tuple) => R;
     readonly struct: (rtti: Struct) => R;
+    /**
+     * A container with a stated rest: the declared members of `rtti`, plus any
+     * number of members belonging to `r`. The bare `tuple`/`struct` handlers
+     * are the same thing with `r` of `never`, and are kept apart because the
+     * common case pays no rest walk.
+     */
+    readonly rest: (rtti: ConstObject, r: Type) => R;
     readonly array: (item: Type) => R;
     readonly record: (item: Type) => R;
     readonly or: (variants: readonly Type[]) => R;
@@ -33,6 +40,21 @@ export type Visitor<R> = {
     readonly primitive0: (tag: Primitive0) => R;
     readonly unknown: () => R;
 };
+/**
+ * Reads what a container schema declares, as `[key, Type]` pairs — one per
+ * container kind, since a `Tuple` is read by length and a `Struct` by
+ * enumerable key. See `tupleSchemaEntries` in `./module.f.mjs` for why the two
+ * readings are not interchangeable on a sparse array.
+ */
+export type SchemaEntries<S extends ConstObject> = (rtti: S) => ReadonlyArray<readonly [string, Type]>;
+/**
+ * Whether a container `value` reaches no further than the `declared` members
+ * of its schema. The array kind is the only one with an answer of its own:
+ * `length` says how far an array reaches whether or not anything is there, so
+ * a hole past the prefix is caught here and nowhere else. An object has no
+ * such measure, and always fits.
+ */
+export type Fits<C extends Unknown> = (value: C, declared: number) => boolean;
 /** Type guard narrowing `Unknown` to a specific container type `C`. */
 export type IsContainer<C extends Unknown> = (value: Unknown) => value is C;
 /** Maps a `Tag1` to its runtime container type. */

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

@@ -21,7 +21,7 @@
  * @import { StringMap } from '../../object/types.ts'
  * @import { ArraySet, Data, KindSet, Node, ObjectSet, RuleSet, UnionSet } from './types.ts'
  */
-import type { Const, Type } from '../types.ts';
+import type { Const, ConstObject, Type } from '../types.ts';
 import type { Primitive, Unknown } from '../ts/types.ts';
 import type { ResultE } from '../common/types.ts';
 import type { StringMap } from '../../object/types.ts';
@@ -95,6 +95,22 @@ export type _Keyed = readonly [Node, string | undefined];
  * @type {(a: Data) => (b: Data) => boolean}
  */
 export declare const subset: (a: Data) => (b: Data) => boolean;
+/**
+ * Whether `a` and `b` denote the same set: {@link subset} both ways.
+ *
+ * Weaker as a test than {@link equal} and stronger as an answer. `equal`
+ * compares canonical *structure*, so it reports two α-equivalent recursive
+ * definitions — the same shape under different rule names — as different;
+ * `subset` resolves references coinductively and sees through the renaming
+ * (see `./README.md`). It inherits `subset`'s incompleteness in exchange: an
+ * equality that holds only by distributing a union, or through a non-syntactic
+ * empty set, is answered `false`. That direction is the safe one — a `false`
+ * here never merges two memberships — so a caller may treat a `true` as
+ * conclusive and a `false` as "not established".
+ *
+ * @type {(a: Data) => (b: Data) => boolean}
+ */
+export declare const equivalent: (a: Data) => (b: Data) => boolean;
 export type _NodeMap = (n: Node) => Node;
 export type _Thunk = Exclude<Type, Const>;
 export type _Key = Exclude<Type, Primitive>;
@@ -123,6 +139,46 @@ export type _State = {
  * @type {(t: Type) => Data}
  */
 export declare const toData: (t: Type) => Data;
+/**
+ * Whether `r`, as the rest of the container `c`, admits nothing — so that
+ * `rest(c, r)` and the bare, closed `c` denote one set.
+ *
+ * This is what the schema-form readers bound an array's length by, and it is
+ * asked *here* on purpose: `arraySet` is where an empty rest normalizes away,
+ * so the readers agree with this form by asking it rather than by re-deriving
+ * the same rule and drifting. Stated as **making no difference to the
+ * canonical form** — the conversion of `rest(c, r)` denoting the same set as
+ * the conversion of `c` — and not as a judgement about `r` on its own, nor as
+ * a reading of whether the conversion kept a `rest` key. Five cases fix it
+ * between them, and only this equality satisfies all five:
+ *
+ * - `never`, `or()` and `[or()]` all convert `rest(c, r)` to `c`'s own
+ *   conversion, so all three are empty. Keying on the exported `never` alone
+ *   would pass a `never`-only proof with the other two spellings still
+ *   disagreeing.
+ * - `const r = () => ['rest', [r], never]` has no finite inhabitant, yet the
+ *   conversion keeps `rest: "r"`, so it is *not* empty here. A reader
+ *   recognizing that emptiness would start rejecting what this form accepts.
+ * - `const a = () => ['or', b]; const b = () => ['or', a]` rules out the
+ *   rest's *own* canonical data as the test: {@link toData} of `a` is `never`,
+ *   and the conversion still keeps `rest: "a"`.
+ * - `unknown` rules out "the conversion kept no `rest` key" as the test:
+ *   `toData(rest([], unknown))` is `{ array: true }` — the whole kind, with no
+ *   `rest` key — because a top rest collapses the pattern rather than being
+ *   dropped from it.
+ * - Two separately constructed copies of one recursive rule, one in `c` and
+ *   one in `r`, rule out {@link equal} as the comparison: converting the rest
+ *   reserves the name, so `c`'s rule is named `r0` where converting `c` alone
+ *   names it `r`, and `equal` compares recursive definitions by rule name.
+ *
+ * {@link equivalent} answers all five. It is incomplete, and in the direction
+ * that costs nothing here: an unrecognized empty rest leaves the length
+ * unbounded, which is what a *kept* `rest` key means in this form anyway, so
+ * the readers still agree with it.
+ *
+ * @type {(c: ConstObject, r: Type) => boolean}
+ */
+export declare const emptyRest: (c: ConstObject, r: Type) => boolean;
 /**
  * Data-driven validation — the counterpart of `../validate` that consumes a
  * {@link Data} produced by {@link toData} instead of walking the thunk