functionalscript 0.46.1 → 0.47.0

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

@@ -1,5 +1,5 @@
 /**
- * @import { ValidationError, ValidateE } from '../common/types.ts'
+ * @import { ValidationError, ValidateE, Validate } from '../common/types.ts'
  * @import { Type } from '../types.ts'
  * @import { Equal } from '../../ts/types.ts'
  * @import { Ts, Unknown } from '../ts/types.ts'
@@ -9,7 +9,8 @@
 
 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 { toData, validate as dataValidate } from '../data/module.f.mjs'
+import { boolean, number, string, bigint, unknown, array, never, open, record, rest, or, option } from '../module.f.mjs'
 import { unwrap } from '../../result/module.f.mjs'
 import { assert, assertEq, assertStructurallySame } from '../../../asserts/module.f.mjs'
 
@@ -35,6 +36,170 @@ const v = t => /** @type {any} */ (validate(t))
 /** @type {(t: Type) => ValidateE} */
 const p = t => /** @type {any} */ (parse(t))
 
+/** The data form's reader, over the same erased signature. */
+/** @type {(t: Type) => ValidateE} */
+const d = t => dataValidate(toData(t))
+
+/**
+ * A rest that is its own container, so nothing about it is inline: the
+ * conversion keeps `rest: "recursiveRest"` rather than recognizing that no
+ * finite array inhabits it, and every reader accepts a hole past the prefix
+ * accordingly. It is one of the two rests {@link emptyRests} must *not*
+ * recognize.
+ *
+ * @typedef {() => readonly ['rest', readonly [_RecursiveRest], typeof never]} _RecursiveRest
+ */
+
+/** @type {_RecursiveRest} */
+const recursiveRest = () => ['rest', [recursiveRest], never]
+
+/**
+ * The other one: a pure `or` cycle. `toData(orCycleA)` **is** `never`, yet as a
+ * rest it converts to a reference and stays, so a test on the rest's own
+ * canonical data would answer the opposite of the criterion.
+ *
+ * @typedef {() => readonly ['or', _OrCycleB]} _OrCycleA
+ * @typedef {() => readonly ['or', _OrCycleA]} _OrCycleB
+ */
+
+/** @type {_OrCycleA} */
+const orCycleA = () => ['or', orCycleB]
+
+/** @type {_OrCycleB} */
+const orCycleB = () => ['or', orCycleA]
+
+/**
+ * Two separately constructed copies of one recursive rule. Converting a rest
+ * reserves its rule name first, so the container's copy is named `r0` where
+ * converting the container alone names it `r` — which is what rules `equal`
+ * out as the comparison behind {@link emptyRests}.
+ *
+ * @typedef {() => readonly ['or', undefined, () => readonly ['array', _SelfList]]} _SelfList
+ */
+
+/** @type {_SelfList} */
+const selfList0 = () => ['or', undefined, array(selfList0)]
+
+/** @type {_SelfList} */
+const selfList1 = () => ['or', undefined, array(selfList1)]
+
+/**
+ * The acceptance table. Rows cover both container kinds, the closed default
+ * and a stated rest on both, the short-array rule, primitives, `or`, and
+ * misses — every reader of a schema has to answer them the same way.
+ *
+ * @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), {}],
+    // an enumerable non-index key is an entry every reader walks, so it is
+    // held to the element type like any other — and a key is an index only in
+    // the canonical spelling, whatever `Number` makes of it
+    [array(number), Object.assign([1], { foo: 2 })],
+    [array(number), Object.assign([1], { foo: 'x' })],
+    [array(number), Object.assign([1], { '-1': 'x' })],
+    [array(number), Object.assign([1], { '01': 'x' })],
+    // an empty element set is the empty array, not "any number of holes": the
+    // data form normalizes such a rest away, which leaves the exact-length
+    // pattern, and the thunk readers bound the length to match
+    [array(or()), []],
+    [array(or()), new Array(1)],
+    [array(number), [, ,]],
+    [record(number), { a: 1 }],
+    [record(number), { a: 'one' }],
+    [record(number), []],
+    // the closed default, on both kinds
+    [[/** @type {const} */ (42)], [42, 'extra']],
+    [[/** @type {const} */ (42)], [42]],
+    [[/** @type {const} */ (42)], [42, undefined]],
+    [[/** @type {const} */ (42)], [42, ,]],
+    [[/** @type {const} */ (42)], Object.assign([42], { foo: 1 })],
+    [[/** @type {const} */ (42)], []],
+    [{ a: /** @type {const} */ (42) }, { a: 42, b: 'x' }],
+    [{ a: /** @type {const} */ (42) }, { a: 42 }],
+    // a key declared `unknown` is a member the schema has, so the canonical
+    // form must not drop it the way an `open` struct's is dropped
+    [{ a: unknown }, { a: 1 }],
+    [{ a: unknown }, { a: 1, b: 2 }],
+    // and the same rows under `open`, which is the form that admits them
+    [open([/** @type {const} */ (42)]), [42, 'extra']],
+    [open({ a: /** @type {const} */ (42) }), { a: 42, b: 'x' }],
+    [open([]), [1]],
+    [open({}), { a: 1 }],
+    // closedness is about *undeclared* members and leaves the short-array rule
+    // alone
+    [[number, option(string)], [42]],
+    // the rule is per position, not "the last one": every trailing position
+    // whose set admits `undefined` may be absent, so an array may stop at the
+    // last required one
+    [[number, bigint, option(string), option(null)], [2, 4n]],
+    [[number, bigint, option(string), option(null)], [2, 4n, 'x']],
+    [[number, bigint, option(string), option(null)], [2, 4n, 'x', null]],
+    [[number, bigint, option(string), option(null)], [2]],
+    [[number, bigint, option(string), option(null)], [2, 4n, 5]],
+    [{ a: number, b: option(string) }, { a: 1 }],
+    [{ a: number }, { a: 'one' }],
+    // a hole in a tuple schema is a declared position whose schema is
+    // `undefined`, so the schema's length is what it declares — the reading
+    // the data form has always had, and the one `Object.entries` lost
+    [new Array(1), [1, 2, 3]],
+    [new Array(1), new Array(1)],
+    [new Array(1), [undefined]],
+    [new Array(1), [1]],
+    [new Array(1), []],
+    [[, number], [9, 5]],
+    [[, number], [undefined, 5]],
+    // and a non-index enumerable own property is no position at all: a tuple
+    // schema is read by index, so `foo` declares nothing — which leaves a
+    // value's own `foo` an undeclared member like any other
+    [Object.assign([number], { foo: string }), [1]],
+    [Object.assign([number], { foo: string }), Object.assign([1], { foo: 'x' })],
+    [open(Object.assign([number], { foo: string })), Object.assign([1], { foo: 'x' })],
+    // a stated rest: what an undeclared member must be
+    [rest([number], string), [1, 'x', 'y']],
+    [rest([number], string), [1, 2]],
+    // a hole past the prefix is no member, so it meets no rest — which is what
+    // the `| undefined` in the rendered tail says
+    [rest([number], string), [1, ,]],
+    // An index the prototype supplies, and a key past the index range, are
+    // members too — both need in-place mutation to build, so their rows run
+    // through the same three readers in `../host.proof.mjs`.
+    [rest({ a: number }, string), { a: 1, b: 'x' }],
+    [rest({ a: number }, string), { a: 1, b: 2 }],
+    // a stated rest with nothing to answer for: the struct kind has no length,
+    // so it fits whatever the rest is
+    [rest({ a: number }, string), { a: 1 }],
+    // an unconstrained rest is `open`
+    [rest([number], unknown), [1, 'x']],
+    [rest({ a: number }, unknown), { a: 1, b: 'x' }],
+    // an empty one is the bare form, so the length is bounded again
+    [rest([number], never), [1, ,]],
+    [rest([number], or()), [1, ,]],
+    [rest([number], [or()]), [1, ,]],
+    [rest([number], [or()]), [1, 2]],
+    // …and a rest the conversion keeps is not empty, however few values it
+    // has: these two are the pair that tells the criterion from an emptiness
+    // analysis
+    [rest([number], recursiveRest), [1, ,]],
+    [rest([number], orCycleA), [1, ,]],
+    [rest([selfList0], [selfList1, never]), [undefined, ,]],
+    [or(number, string), true],
+    [or(number, string), 'hello'],
+    [option(number), undefined],
+    [option(number), null],
+    [{ user: { name: string, age: number } }, { user: { name: 'A', age: 'old' } }],
+]
+
 export const proof = {
     // ── the three properties this module exists for ──────────────────────────
     //
@@ -55,16 +220,17 @@ export const proof = {
             // 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.
+        // An undeclared member survives — where the schema admits one at all.
+        // `parse` accepts the same values and does not carry the member into
+        // what it builds.
         undeclaredMemberSurvives: () => {
-            const schema = { a: number }
+            const schema = open({ 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'])
+            assertStructurallySame(unwrap(validate(open([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
@@ -82,7 +248,7 @@ export const proof = {
             same(unknown, arr)
             const obj = { a: 1, b: 2 }
             same(record(number), obj)
-            same({ a: number }, obj)
+            same({ a: number, b: number }, obj)
             same(or(string, record(number)), obj)
             const nested = { xs: [{ a: 1 }] }
             same({ xs: array({ a: number }) }, nested)
@@ -91,38 +257,8 @@ export const proof = {
         },
     },
     // 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.
+    // success carries and in nothing else.
     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)
@@ -133,6 +269,130 @@ export const proof = {
             }
         }
     },
+    // The same table against the third reader, the data form's — the one that
+    // consumes `toData` output rather than the thunk graph. A schema denotes
+    // one set of values, so a conversion that changed which values a schema
+    // admits would be a bug in `toData`, and this is where it shows up: an
+    // open tuple whose data form was exact-length passed every row above and
+    // still disagreed here. Acceptance only: the data form reaches a value
+    // through the canonical union rather than through the schema's syntax, so
+    // it reports a miss as its own kind-wise failure rather than repeating
+    // `or`'s `no match`.
+    sameAcceptanceInTheDataForm: () => {
+        for (const [t, value] of rows) {
+            assertEq(d(t)(value)[0], p(t)(value)[0], 'the data form must accept what `parse` accepts')
+        }
+    },
+    // The two proofs above compare the readers with one another, so a
+    // regression all three shared would pass them both. The table's rows for
+    // a schema with several optional positions therefore carry their expected
+    // answer here as well.
+    //
+    // The rule is *per position*, not "the last one": a position is required
+    // exactly when its set excludes `undefined`, independently of the others.
+    // A dense prefix alone would only show that an optional *suffix* may be
+    // truncated, so the cases below also omit position 2 while position 3 is
+    // present, and omit a required position with everything after it present.
+    //
+    // Every case runs against the `open` form too. A stated rest is a separate
+    // reader on all three — `restContainerValidate`/`restContainerParse`, and
+    // its own conversion in the data form — and it widens *which values are
+    // members*, not which positions are required, so it must answer these
+    // identically. The one case where opening does change the answer is at the
+    // end.
+    optionalPositions: () => {
+        const t = /** @type {const} */ ([number, bigint, option(string), option(null)])
+        /** @type {(rtti: Type) => (check: (r: readonly [string, unknown]) => void) => (value: Unknown) => void} */
+        const every = rtti =>
+            check =>
+                value => {
+                    for (const read of [v, p, d]) { check(read(rtti)(value)) }
+                }
+        for (const rtti of [t, open(t)]) {
+            const accepted = every(rtti)(assertOk)
+            const rejected = every(rtti)(assertError)
+            accepted([2, 4n])                  // stops at the last required position
+            accepted([2, 4n, 'x'])             // the first optional present
+            accepted([2, 4n, 'x', null])       // both present
+            // Omission is independent, not just truncation: an absent member
+            // reads as `undefined` wherever it sits, so position 2 may be
+            // missing while position 3 is present. A hole and an explicit
+            // `undefined` are the same value, so both spellings are accepted.
+            accepted([2, 4n, , null])          //< a hole at position 2
+            accepted([2, 4n, undefined, null]) //< the same value, spelled densely
+            rejected([2])                      // `bigint` excludes `undefined`
+            rejected([2, 4n, 5])               // an optional that is present is still checked
+            // The mirror of the two rows above: `bigint` excludes `undefined`,
+            // so omitting position 1 fails however much of the rest is present.
+            rejected([2, , 'x', null])         //< a hole at position 1
+        }
+        // What opening does change: an element past the declared positions is
+        // a member of the open set and not of the bare, closed one.
+        const extra = /** @type {const} */ ([2, 4n, 'x', null, 'extra'])
+        every(t)(assertError)(extra)
+        every(open(t))(assertOk)(extra)
+        // How stopping short composes with running long: the two rules are
+        // independent, so the open form's accepted lengths run from the last
+        // required position upwards without a gap or a cap — 2, 3, 4, 5, and
+        // on. The bare form caps the top at the declared count and leaves the
+        // bottom where it is.
+        every(open(t))(assertOk)([2, 4n, 'x', null, 'a', 'b'])
+    },
+    // An interior omittable position may be absent with a *required* position
+    // after it, which is the sharpest witness that absence is per position
+    // rather than truncation: `optionalPositions`'s hole is followed by
+    // another omittable position, so it cannot say this. Absence is also
+    // positional, not a shift — `[, 5]` holds `5` at position 1 and is
+    // accepted, while `[5]` holds it at position 0 and is not.
+    interiorOptionBeforeRequired: () => {
+        const t = /** @type {const} */ ([option(string), number])
+        /** @type {(rtti: Type) => (check: (r: readonly [string, unknown]) => void) => (value: Unknown) => void} */
+        const every = rtti =>
+            check =>
+                value => {
+                    for (const read of [v, p, d]) { check(read(rtti)(value)) }
+                }
+        // Open too, for the reason `optionalPositions` runs both: a stated
+        // rest is its own reader on all three, and this schema is not one of
+        // the shapes the trailing-option cases there already put through it.
+        for (const rtti of [t, open(t)]) {
+            every(rtti)(assertOk)([, 5])          //< a hole at position 0
+            every(rtti)(assertOk)([undefined, 5]) //< the same value, spelled densely
+            every(rtti)(assertOk)(['x', 5])
+            every(rtti)(assertError)([5])         //< `number` at position 1 is required
+        }
+        // And the one answer opening changes here as well.
+        const extra = /** @type {const} */ (['x', 5, 'extra'])
+        every(t)(assertError)(extra)
+        every(open(t))(assertOk)(extra)
+    },
+    // The two tables above pin that the three readers *agree*; these pin what
+    // they agree on, which is what the changelog entry claims.
+    sparseTuple: {
+        holeIsDeclaredUndefined: () => {
+            assertError(validate([, number])([9, 5]))
+            assertOk(validate([, number])([undefined, 5]))
+            assertError(validate(new Array(1))([1, 2, 3]))
+            assertOk(validate(new Array(1))([undefined]))
+        },
+        // A hole is a position, so a sparse schema is as long as it looks:
+        // `declared.length` is the schema's length, not its key count.
+        arityIsTheSchemaLength: () => {
+            assertOk(validate(new Array(1))([undefined]))
+            assertError(validate(new Array(1))([1]))
+        },
+        // A tuple schema is read by index, so `foo` declares no position — it
+        // is not matched against anything, and on the value side it is an
+        // undeclared member like any other, which the closed form rejects and
+        // `open` admits.
+        nonIndexPropertyIsNotDeclared: () => {
+            const schema = Object.assign([number], { foo: string })
+            assertOk(validate(schema)([1]))
+            assertError(validate(schema)(Object.assign([1], { foo: 'x' })))
+            assertOk(validate(open(schema))(Object.assign([1], { foo: 'x' })))
+            assertError(validate(schema)(['x']))
+        },
+    },
     boolean: {
         ok: () => {
             /** @typedef {Assert<Equal<Ts<typeof boolean>, boolean>>} _RoundTrip */
@@ -199,15 +459,15 @@ export const proof = {
             error: () => assertError(validate(undefined)(null)),
         },
         number: {
-            ok: () => assertOk(validate(/** @type {const} */ (42))(42)),
-            error: () => assertError(validate(/** @type {const} */ (42))(43)),
+            ok: () => assertOk(validate(42)(42)),
+            error: () => assertError(validate(42)(43)),
         },
         nan: {
             ok: () => assertOk(validate(NaN)(NaN)),
             error: () => {
                 assertError(validate(NaN)(0))
-                assertError(validate(/** @type {const} */ (0))(NaN))
-                assertError(validate(/** @type {const} */ (42))(NaN))
+                assertError(validate(0)(NaN))
+                assertError(validate(42)(NaN))
             },
         },
         infinity: {
@@ -223,40 +483,36 @@ export const proof = {
         signedZero: {
             // `Object.is` distinguishes +0 and -0; `===` treats them equal.
             distinct: () => {
-                assertError(validate(/** @type {const} */ (0))(-0))
+                assertError(validate(0)(-0))
                 assertError(validate(-0)(0))
             },
             self: () => {
-                assertOk(validate(/** @type {const} */ (0))(0))
+                assertOk(validate(0)(0))
                 assertOk(validate(-0)(-0))
             },
         },
         string: {
-            ok: () => assertOk(validate(/** @type {const} */ ('hello'))('hello')),
-            error: () => assertError(validate(/** @type {const} */ ('hello'))('world')),
+            ok: () => assertOk(validate('hello')('hello')),
+            error: () => assertError(validate('hello')('world')),
         },
         bigint: {
-            ok: () => assertOk(validate(/** @type {const} */ (7n))(7n)),
-            error: () => assertError(validate(/** @type {const} */ (7n))(8n)),
+            ok: () => assertOk(validate(7n)(7n)),
+            error: () => assertError(validate(7n)(8n)),
         },
         boolean: {
-            ok: () => assertOk(validate(/** @type {const} */ (true))(true)),
-            error: () => assertError(validate(/** @type {const} */ (true))(false)),
+            ok: () => assertOk(validate(true)(true)),
+            error: () => assertError(validate(true)(false)),
         },
         tuple: {
-            ok: () => {
-                const t = /** @type {const} */ ([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: () => {
+            ok: () => assertStructurallySame(
+                unwrap(validate([42, 'hello'])([42, 'hello'])), [42, 'hello']),
+            // A tuple is CLOSED, so a longer array is not one of its values —
+            // see "Structs and tuples are closed" in ../README.md. Under
+            // `open` it is, and it comes back as it went in.
+            extraItemsRejected: () => {
                 const long = [42, 1, 2, 3]
-                assert(Object.is(unwrap(validate(/** @type {const} */ ([42]))(long)), long),
+                assertError(validate([42])(long))
+                assert(Object.is(unwrap(validate(open([42]))(long)), long),
                     'the longer array comes back as it went in')
             },
             // An absent member reads as `undefined`, so a position is required
@@ -268,22 +524,28 @@ export const proof = {
                 assert(Object.is(out, short), 'expected the original array')
                 assertEq(short.length, 1, 'no gap is filled')
             },
-            empty: () => assertOk(validate(/** @type {const} */ ([]))([])),
+            empty: () => assertOk(validate([])([])),
             error: () => {
-                assertError(validate(/** @type {const} */ ([42]))([99]))
-                assertError(validate(/** @type {const} */ ([42]))({}))
+                assertError(validate([42])([99]))
+                assertError(validate([42])({}))
                 // `42` excludes `undefined`, so position 0 is required.
-                assertError(validate(/** @type {const} */ ([42]))([]))
+                assertError(validate([42])([]))
             },
         },
         struct: {
+            // `validate` takes a `const` type parameter, so a struct literal
+            // keeps its literal members without an `@type {const}` cast at the
+            // call site: this is a reader for `{ a: 42, b: 'hello' }`, not for
+            // `{ a: number, b: string }`. Dropping the modifier is what makes
+            // the assertion fail.
             ok: () => {
-                const t = /** @type {const} */ ({ a: 42, b: 'hello' })
-                assertStructurallySame(unwrap(validate(t)({ a: 42, b: 'hello' })), { a: 42, b: 'hello' })
+                const v = validate({ a: 42, b: 'hello' })
+                /** @typedef {Assert<Equal<typeof v, Validate<{ readonly a: 42, readonly b: 'hello' }>>>} _ConstParameter */
+                assertStructurallySame(unwrap(v({ a: 42, b: 'hello' })), { a: 42, b: 'hello' })
             },
             error: () => {
-                assertError(validate(/** @type {const} */ ({ a: 42 }))({ a: 99 }))
-                assertError(validate(/** @type {const} */ ({ a: 42 }))([]))
+                assertError(validate({ a: 42 })({ a: 99 }))
+                assertError(validate({ a: 42 })([]))
             },
         },
     },
@@ -328,13 +590,13 @@ export const proof = {
     or: {
         consts: {
             ok: () => {
-                const t = or(.../** @type {const} */ ([false, 42, 'hello']))
+                const t = or(false, 42, 'hello')
                 assertOk(validate(t)(false))
                 assertOk(validate(t)(42))
                 assertOk(validate(t)('hello'))
             },
             error: () => {
-                const t = or(.../** @type {const} */ ([false, 42, 'hello']))
+                const t = or(false, 42, 'hello')
                 assertError(validate(t)(true))
                 assertError(validate(t)(43))
                 assertError(validate(t)('world'))
@@ -358,7 +620,7 @@ export const proof = {
         // 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 t = or(open([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])
@@ -384,10 +646,10 @@ export const proof = {
             validate(array(array(number)))([[1, 'x'], [2, 3]])
         ),
         tupleIndex: () => assertErrorPath(['1'])(
-            validate(/** @type {const} */ ([number, number]))([1, 'two'])
+            validate([number, number])([1, 'two'])
         ),
         structKey: () => assertErrorPath(['b'])(
-            validate(/** @type {const} */ ({ a: number, b: number }))({ a: 1, b: 'two' })
+            validate({ a: number, b: number })({ a: 1, b: 'two' })
         ),
         deepStruct: () => {
             const schema = /** @type {const} */ ({ user: { name: string, age: number } })
@@ -423,4 +685,97 @@ export const proof = {
             assertError(x({ a: 42 }))
         },
     },
+    // A stated rest widens acceptance and nothing else: a success still carries
+    // the very value it was given. The acceptance half is in the table above,
+    // run through all three readers; what is left to pin here is that
+    // `validate` stays verbatim on that form too.
+    rest: {
+        verbatim: () => {
+            const value = [1, 'x', 'y']
+            assert(Object.is(unwrap(validate(rest([number], string))(value)), value),
+                'the value comes back as it went in')
+            const struct = { a: 1, b: 'x' }
+            assert(Object.is(unwrap(validate(rest({ a: number }, string))(struct)), struct),
+                'and so does an object with rest-matching keys')
+        },
+        // An absent optional member still stays absent — a container's rest
+        // says nothing about a member it declares.
+        absentOptionalStaysAbsent: () => {
+            const out = unwrap(validate({ a: number, b: option(string) })({ a: 1 }))
+            assert(!('b' in out), 'an absent optional member must stay absent')
+        },
+        path: () => {
+            assertErrorPath(['1'])(validate([number, number])([1, 'two']))
+            assertErrorPath(['b'])(validate(rest({ a: number }, string))({ a: 1, b: 2 }))
+            // The rejection of an undeclared member is about the container, so
+            // it is reported at the container.
+            assertErrorPath([])(validate({ a: number })({ a: 1, b: 2 }))
+        },
+        notAContainer: () => {
+            assertError(validate(rest([number], string))({}))
+            assertError(validate(rest({ a: number }, string))([]))
+        },
+    },
+    // The three-reader table pins that the readers *agree* on the empty-rest
+    // criterion; these assert the verdict outright, since a row alone passes
+    // whenever all three move together. Each spelling is named rather than
+    // covered by "an independently constructed empty rest": an implementation
+    // recognizing empty unions but not `[or()]` passes the `or()` row while
+    // keeping that spelling's disagreement, and one keyed on the exported
+    // `never`'s identity passes the converse.
+    emptyRests: {
+        dropped: () => {
+            for (const r of [never, or(), [or()]]) {
+                assertError(validate(rest([number], r))([42, ,]))
+            }
+            // The name collision: converting the rest reserves `r`, so the
+            // container's own rule is named `r0` — which `equal` reads as a
+            // different schema and `subset` both ways does not.
+            assertError(v(rest([selfList0], [selfList1, never]))([undefined, ,]))
+        },
+        kept: () => {
+            // A rest the conversion keeps is not empty however few values it
+            // has: `recursiveRest` catches an emptiness analysis that reaches
+            // container cycles, `orCycleA` one that tests the rest's own
+            // canonical data, and `unknown` one that reads the absence of a
+            // `rest` key as elimination.
+            // `v` rather than `validate`: `Ts<>` walks a recursive schema
+            // structurally, and these two exist to be recursive.
+            assertOk(v(rest([number], recursiveRest))([42, ,]))
+            assertOk(v(rest([number], orCycleA))([42, ,]))
+            assertOk(validate(open([]))([1]))
+        },
+    },
+    // The two ways an array can reach past a closed prefix, told apart. The
+    // acceptance table pins that the three readers agree on both; these assert
+    // the verdict, since a row alone passes whenever all three move together.
+    // The hole is rejected by *length* — it is no member, so the member check
+    // alone would let it through — and the explicit `undefined` by the member
+    // check, since it is a member and the schema declares no position for it.
+    // A closed tuple therefore has exactly one spelling per value.
+    beyondAClosedPrefix: () => {
+        for (const read of [v, p, d]) {
+            assertError(read([/** @type {const} */ (42)])([42, ,]))
+            assertError(read([/** @type {const} */ (42)])([42, undefined]))
+            assertOk(read([/** @type {const} */ (42)])([42]))
+        }
+    },
+    // The walk is bounded by what the value and its prototypes carry rather
+    // than by `length`: a sparse array as long as the index space allows
+    // answers at once, where materializing the range exhausted memory first.
+    // The verdicts are the ordinary ones — a bare tuple is too short for it,
+    // a rest with nothing present past the prefix admits it.
+    lengthDoesNotBoundTheWalk: () => {
+        const big = new Array(2 ** 32 - 1)
+        assertError(v([option(string)])(big))
+        assertOk(v(rest([], string))(big))
+    },
+    arrayOptional: () => {
+        const a = /** @type {const} */([number, option(string)])
+        const v = validate(a)
+        assertOk(v([5]))
+        assertError(v(["n"]))
+        assertOk(v([6, "3"]))
+        assertError(v([6, 9]))
+    }
 }

package/fjs/types/ts/types.d.ts

@@ -5,6 +5,10 @@
  * @module
  */
 export type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+export type And<A extends boolean, B extends boolean> = [
+    A,
+    B
+] extends [true, true] ? true : false;
 /**
  * A `struct` field: the key, its type expression, and — when the third
  * element is `true` — an optional-key marker (`"key"?: type`).