functionalscript 0.45.0 → 0.46.0

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

@@ -1,34 +1,33 @@
 /**
- * Shared kernel for RTTI consumers (`validate`, `parse`).
+ * Shared kernel for RTTI consumers.
  *
- * Both consumers traverse the same schema shape and produce the same
- * `Result<T, ValidationError>` outcome. Only the per-variant handling differs
- * — `validate` keeps the original value, `parse` constructs a fresh one.
- *
- * This module hosts the parts that do not differ:
+ * `parse` (`../parse/module.f.mjs`) is the schema-form consumer; the data form
+ * (`../data/module.f.mjs`) is the other, walking a `Data` instead of a thunk
+ * graph. They produce the same `Result<T, ValidationError>` outcome and differ
+ * in how they dispatch, so this module hosts the parts that do not differ:
  *
  * - The error shape (`ValidationError`, `Path`) and path bookkeeping
  *   (`verror`, `prependPath`).
  * - Primitive checks (`primitive0Validate`, `constPrimitiveValidate`).
- * - The `Validate<T>`/`Result<T>` signatures — `parse` uses the same shape.
+ * - The `Validate<T>`/`Result<T>` signatures, which `parse` reuses
+ *   (`Parse<T> = Validate<T>`).
  * - `visit`: a visitor over the `Type` ADT. Callers supply a `Visitor<R>`
  *   with one handler per variant; `visit(v)(rtti)` recognizes `rtti` and
- *   calls the matching handler. Both consumers compose their top-level
- *   function from a visitor.
- * - `eachEntry`: the container entry loop (array/record/tuple/struct), shared
- *   by both consumers' container builders. Callers choose what (if anything)
- *   to accumulate, so `validate`'s pure pass/fail check pays no allocation.
+ *   calls the matching handler. `parse` composes its top-level function from
+ *   a visitor.
+ * - `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.
  * - `orVisit`: the shared `or` handler — try each variant's recursive walker,
  *   return the first match.
  *
- * Keeping the kernel here also removes `parse`'s incidental dependency on
- * `validate` and gives schema-driven consumers (e.g. the data form in
- * `../data/module.f.mjs`) a stable shared base.
+ * Keeping the kernel here gives schema-driven consumers a stable shared base
+ * that does not depend on any one of them.
  *
  * @module
  *
  * @import { Primitive, Unknown } from '../ts/types.ts'
- * @import { Const, Info0, Primitive0, Struct, Tag1, Tuple, Type } from '../types.ts'
+ * @import { Const, Info0, Primitive0, 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'
@@ -67,10 +66,10 @@ export declare const constPrimitiveValidate: <T extends Primitive>(
  * @returns {Validate<T>}
  */
 rtti: T) => Validate<T>;
-/** `IsContainer` guard for arrays, shared by `validate` and `parse`. */
+/** `IsContainer` guard for arrays. */
 /** @type {IsContainer<ReadonlyArray<Unknown>>} */
 export declare const isArray: IsContainer<ReadonlyArray<Unknown>>;
-/** `IsContainer` guard for records/structs, shared by `validate` and `parse`. */
+/** `IsContainer` guard for records/structs. */
 /** @type {IsContainer<StringMap<Unknown>>} */
 export declare const isObject: IsContainer<StringMap<Unknown>>;
 /**
@@ -79,21 +78,19 @@ export declare const isObject: IsContainer<StringMap<Unknown>>;
  * result into `acc` (starting from `init`) with `accumulate` and returns the
  * final accumulator.
  *
- * Shared by `validate` and `parse`'s container builders (array/record/tuple/
- * struct), which differ only in what `item` does with the value and what
- * they accumulate: `validate` has nothing to collect — its entire schema is
- * "did every entry succeed?" — so it passes `undefined`/`(acc) => acc` and
- * pays no allocation per entry; `parse` needs the rebuilt `[key, value]`
- * pairs, so it folds them into a `List` (see its call site) and converts to
- * an array once at the end.
+ * Used by `parse`'s container builders (array/record/tuple/struct), which
+ * need the rebuilt `[key, value]` pairs, so they fold them into a `List` (see
+ * the call site) and convert to an array once at the end. A caller whose
+ * whole question is "did every entry succeed?" passes `undefined`/`acc => acc`
+ * 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>;
 /**
  * First variant in `variants` that `recurse` accepts, else `verror('no match')`.
  *
- * Shared `or` handler for `validate` and `parse`: both try each variant
- * against the value and return the first `'ok'` verbatim, differing only in
- * which recursive function (`validate` or `parse`) walks each variant. `recurse`
+ * Shared `or` handler: try each variant against the value and return the
+ * first `'ok'` verbatim, parameterized by the recursive function that walks
+ * each variant. `recurse`
  * is typed over the erased `ValidateE` alias — annotating it as `(t: Type) =>
  * Validate<Type>` would itself instantiate `Validate<Type>` and hit TS2589 —
  * so each caller passes its recursive function through one boundary cast.

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

@@ -1,39 +1,39 @@
 /**
- * Shared kernel for RTTI consumers (`validate`, `parse`).
+ * Shared kernel for RTTI consumers.
  *
- * Both consumers traverse the same schema shape and produce the same
- * `Result<T, ValidationError>` outcome. Only the per-variant handling differs
- * — `validate` keeps the original value, `parse` constructs a fresh one.
- *
- * This module hosts the parts that do not differ:
+ * `parse` (`../parse/module.f.mjs`) is the schema-form consumer; the data form
+ * (`../data/module.f.mjs`) is the other, walking a `Data` instead of a thunk
+ * graph. They produce the same `Result<T, ValidationError>` outcome and differ
+ * in how they dispatch, so this module hosts the parts that do not differ:
  *
  * - The error shape (`ValidationError`, `Path`) and path bookkeeping
  *   (`verror`, `prependPath`).
  * - Primitive checks (`primitive0Validate`, `constPrimitiveValidate`).
- * - The `Validate<T>`/`Result<T>` signatures — `parse` uses the same shape.
+ * - The `Validate<T>`/`Result<T>` signatures, which `parse` reuses
+ *   (`Parse<T> = Validate<T>`).
  * - `visit`: a visitor over the `Type` ADT. Callers supply a `Visitor<R>`
  *   with one handler per variant; `visit(v)(rtti)` recognizes `rtti` and
- *   calls the matching handler. Both consumers compose their top-level
- *   function from a visitor.
- * - `eachEntry`: the container entry loop (array/record/tuple/struct), shared
- *   by both consumers' container builders. Callers choose what (if anything)
- *   to accumulate, so `validate`'s pure pass/fail check pays no allocation.
+ *   calls the matching handler. `parse` composes its top-level function from
+ *   a visitor.
+ * - `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.
  * - `orVisit`: the shared `or` handler — try each variant's recursive walker,
  *   return the first match.
  *
- * Keeping the kernel here also removes `parse`'s incidental dependency on
- * `validate` and gives schema-driven consumers (e.g. the data form in
- * `../data/module.f.mjs`) a stable shared base.
+ * Keeping the kernel here gives schema-driven consumers a stable shared base
+ * that does not depend on any one of them.
  *
  * @module
  *
  * @import { Primitive, Unknown } from '../ts/types.ts'
- * @import { Const, Info0, Primitive0, Struct, Tag1, Tuple, Type } from '../types.ts'
+ * @import { Const, Info0, Primitive0, 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 { assert } from '../../../asserts/module.f.mjs'
 import { error, ok } from '../../result/module.f.mjs'
 import { isArray as commonIsArray } from '../../array/module.f.mjs'
 import { isObject as commonIsObject } from '../../object/module.f.mjs'
@@ -80,15 +80,15 @@ export const constPrimitiveValidate =
 /** @type {<R>(v: Visitor<R>) => (c: Const) => R} */
 const visitConst = v => c =>
     typeof c === 'object' && c !== null
-        ? (commonIsArray(c) ? v.tuple(c) : v.struct(/** @type {Struct} */ (c)))
-        : v.constPrimitive(/** @type {Primitive} */ (c))
+        ? (commonIsArray(c) ? v.tuple(c) : v.struct(c))
+        : v.constPrimitive(c)
 
-/** `IsContainer` guard for arrays, shared by `validate` and `parse`. */
+/** `IsContainer` guard for arrays. */
 /** @type {IsContainer<ReadonlyArray<Unknown>>} */
 export const isArray =
     value => commonIsArray(value)
 
-/** `IsContainer` guard for records/structs, shared by `validate` and `parse`. */
+/** `IsContainer` guard for records/structs. */
 /** @type {IsContainer<StringMap<Unknown>>} */
 export const isObject =
     value => commonIsObject(value)
@@ -99,13 +99,11 @@ export const isObject =
  * result into `acc` (starting from `init`) with `accumulate` and returns the
  * final accumulator.
  *
- * Shared by `validate` and `parse`'s container builders (array/record/tuple/
- * struct), which differ only in what `item` does with the value and what
- * they accumulate: `validate` has nothing to collect — its entire schema is
- * "did every entry succeed?" — so it passes `undefined`/`(acc) => acc` and
- * pays no allocation per entry; `parse` needs the rebuilt `[key, value]`
- * pairs, so it folds them into a `List` (see its call site) and converts to
- * an array once at the end.
+ * Used by `parse`'s container builders (array/record/tuple/struct), which
+ * need the rebuilt `[key, value]` pairs, so they fold them into a `List` (see
+ * the call site) and convert to an array once at the end. A caller whose
+ * whole question is "did every entry succeed?" passes `undefined`/`acc => acc`
+ * instead and pays no allocation per entry.
  */
 export const eachEntry =
     /**
@@ -133,9 +131,9 @@ export const eachEntry =
 /**
  * First variant in `variants` that `recurse` accepts, else `verror('no match')`.
  *
- * Shared `or` handler for `validate` and `parse`: both try each variant
- * against the value and return the first `'ok'` verbatim, differing only in
- * which recursive function (`validate` or `parse`) walks each variant. `recurse`
+ * Shared `or` handler: try each variant against the value and return the
+ * first `'ok'` verbatim, parameterized by the recursive function that walks
+ * each variant. `recurse`
  * is typed over the erased `ValidateE` alias — annotating it as `(t: Type) =>
  * Validate<Type>` would itself instantiate `Validate<Type>` and hit TS2589 —
  * so each caller passes its recursive function through one boundary cast.
@@ -173,13 +171,19 @@ export const visit =
         if (typeof rtti === 'function') {
             const [tag, ...value] = rtti()
             switch (tag) {
-                case 'const': return visitConst(v)(/** @type {Const} */ (value[0]))
+                case 'const': {
+                    const [c] = value
+                    // `Type` is `Const | Thunk`, and a `Thunk` is a function, so
+                    // this is exactly the check that defines `Const`.
+                    assert(typeof c !== 'function', c)
+                    return visitConst(v)(c)
+                }
                 case 'array': return v.array(value[0])
                 case 'record': return v.record(value[0])
                 case 'unknown': return v.unknown()
                 case 'or': return v.or(value)
             }
-            return v.primitive0(/** @type {Primitive0} */ (tag))
+            return v.primitive0(tag)
         }
         return visitConst(v)(rtti)
     }

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

@@ -19,12 +19,12 @@ const collect = (acc, k, v) => [...acc, [k, v]]
 
 export const proof = {
     empty: () => {
-        const r = eachEntry(/** @type {_Entries} */ ([]), item, /** @type {_Entries} */ ([]), collect)
+        const r = eachEntry([], item, [], collect)
         assert(r[0] === 'ok')
         assertEq(r[1].length, 0)
     },
     allOk: () => {
-        const r = eachEntry([['a', 1], ['b', 2]], item, /** @type {_Entries} */ ([]), collect)
+        const r = eachEntry([['a', 1], ['b', 2]], item, [], collect)
         assert(r[0] === 'ok')
         assertEq(r[1].length, 2)
         assertEq(r[1][0][0], 'a')
@@ -39,7 +39,7 @@ export const proof = {
         assertEq(r[1], undefined)
     },
     firstErrorWins: () => {
-        const r = eachEntry([['a', -1], ['b', -2]], item, /** @type {_Entries} */ ([]), collect)
+        const r = eachEntry([['a', -1], ['b', -2]], item, [], collect)
         assert(r[0] === 'error')
         assertEq(r[1].message, 'negative at a')
     },
@@ -50,7 +50,7 @@ export const proof = {
             calls++
             return item(k, v)
         }
-        const r = eachEntry([['a', -1], ['b', -2], ['c', -3]], counting, /** @type {_Entries} */ ([]), collect)
+        const r = eachEntry([['a', -1], ['b', -2], ['c', -3]], counting, [], collect)
         assert(r[0] === 'error')
         assertEq(calls, 1)
     },
@@ -58,7 +58,7 @@ export const proof = {
         /** @type {(k: string, v: number) => Result<number, ValidationError>} */
         const nested = (k, v) =>
             v < 0 ? error({ path: ['inner'], message: 'bad' }) : ok(v)
-        const r = eachEntry([['outer', -1]], nested, /** @type {_Entries} */ ([]), collect)
+        const r = eachEntry([['outer', -1]], nested, [], collect)
         assert(r[0] === 'error')
         assertEq(r[1].path.length, 2)
         assertEq(r[1].path[0], 'outer')

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

@@ -49,6 +49,20 @@ export declare const never: UnionSet;
  * @type {UnionSet}
  */
 export declare const unknown: UnionSet;
+/**
+ * The union with the given unit bits removed — set subtraction restricted to
+ * the unit kind. Dropping `undefined` from an optional property's value set is
+ * the motivating case.
+ *
+ * The other five kinds are carried through untouched rather than copied field
+ * by field. That is not only shorter: a caller that enumerates `UnionSet`'s
+ * members to rebuild the node silently **drops** any kind added to the type
+ * later, whereas spreading cannot. Removing every unit bit removes the `unit`
+ * key entirely, since an empty kind is an absent property here, never a zero.
+ *
+ * @type {(bits: number) => (n: UnionSet) => UnionSet}
+ */
+export declare const withoutUnits: (bits: number) => (n: UnionSet) => UnionSet;
 /**
  * Total order over the data form: negative, zero or positive, with zero
  * exactly on structural identity. {@link toData} output is canonical, so two

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

@@ -22,7 +22,7 @@
  * @import { ArraySet, Data, KindSet, Node, ObjectSet, RuleSet, UnionSet } from './types.ts'
  */
 
-import { assertNotNullish } from '../../../asserts/module.f.mjs'
+import { assert, assertNotNullish } from '../../../asserts/module.f.mjs'
 import { at, definedEntries, definedValues } from '../../object/module.f.mjs'
 import { ok } from '../../result/module.f.mjs'
 import { eachEntry, isArray, verror } from '../common/module.f.mjs'
@@ -68,6 +68,25 @@ export const unknown = {
     object: true,
 }
 
+/**
+ * The union with the given unit bits removed — set subtraction restricted to
+ * the unit kind. Dropping `undefined` from an optional property's value set is
+ * the motivating case.
+ *
+ * The other five kinds are carried through untouched rather than copied field
+ * by field. That is not only shorter: a caller that enumerates `UnionSet`'s
+ * members to rebuild the node silently **drops** any kind added to the type
+ * later, whereas spreading cannot. Removing every unit bit removes the `unit`
+ * key entirely, since an empty kind is an absent property here, never a zero.
+ *
+ * @type {(bits: number) => (n: UnionSet) => UnionSet}
+ */
+export const withoutUnits = bits => n => {
+    const unit = (n.unit ?? 0) & ~bits
+    const { unit: _, ...rest } = n
+    return unit === 0 ? rest : { unit, ...rest }
+}
+
 // ── canonical order ──────────────────────────────────────────────────────────
 
 /** @type {(a: string, b: string) => number} */
@@ -747,7 +766,11 @@ const orUnion = (state, t, operands) => {
 const thunkUnion = (state, t) => {
     const [tag, ...rest] = t()
     switch (tag) {
-        case 'const': { return constUnion(state, /** @type {Const} */ (rest[0])) }
+        case 'const': {
+            const [c] = rest
+            assert(typeof c !== 'function', c)
+            return constUnion(state, c)
+        }
         case 'boolean': { return [state, { unit: booleanUnits }] }
         case 'number': { return [state, { number: true }] }
         case 'string': { return [state, { string: true }] }

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

@@ -31,6 +31,7 @@ export type _Odd = () => readonly ['const', {
 }];
 export type _Rec = () => readonly ['array', _Rec];
 export declare const proof: {
+    withoutUnits: (() => void)[];
     unitBits: () => void;
     toData: {
         primitives: () => void;

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

@@ -3,7 +3,7 @@
  * @import { Data } from './types.ts'
  */
 
-import { assert, assertEq } from '../../../asserts/module.f.mjs'
+import { assert, assertEq, assertStructurallySame } from '../../../asserts/module.f.mjs'
 import {
     array,
     bigint,
@@ -16,7 +16,7 @@ import {
     string,
     unknown as unknownRtti,
 } from '../module.f.mjs'
-import { cmp, equal, never, subset, toData, unitBit, unitList, unknown, validate } from './module.f.mjs'
+import { cmp, equal, never, subset, toData, unitBit, unitList, unknown, validate, withoutUnits } from './module.f.mjs'
 
 /** @type {(actual: Data) => (expected: Data) => void} */
 const assertData = actual => expected =>
@@ -119,6 +119,29 @@ const tupleString = /** @type {const} */ ([string])
 const emptyTuple = /** @type {const} */ ([])
 
 export const proof = {
+    withoutUnits: [
+        // Removing the last unit bit removes the key: an empty kind is an
+        // absent property here, never a zero.
+        () => assertStructurallySame(
+            withoutUnits(unitBit(undefined))({ unit: unitBit(undefined) }),
+            never),
+        () => assertStructurallySame(
+            withoutUnits(unitBit(undefined))({ unit: unitBit(undefined) | unitBit(null) }),
+            { unit: unitBit(null) }),
+        // Bits that are not set are a no-op.
+        () => assertStructurallySame(
+            withoutUnits(unitBit(undefined))({ unit: unitBit(null) }),
+            { unit: unitBit(null) }),
+        () => assertStructurallySame(withoutUnits(unitBit(undefined))(never), never),
+        // The other five kinds are carried through untouched — this is what
+        // enumerating `UnionSet`'s members by hand would silently drop.
+        () => assertStructurallySame(
+            withoutUnits(unitBit(undefined))(unknown),
+            { ...unknown, unit: unitBit(null) | unitBit(false) | unitBit(true) }),
+        () => assertStructurallySame(
+            withoutUnits(unitBit(undefined))({ unit: unitBit(undefined), string: true }),
+            { string: true }),
+    ],
     unitBits: () => {
         // the literal bits are the encoding under test
         assertEq(unitList.join(), 'null,undefined,false,true')

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

@@ -5,24 +5,34 @@
  * 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>`:
- *
- * - 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.
+ * **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.
  *
- * 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.
  *
@@ -32,7 +42,7 @@
  * @import { Result as CommonResult } from '../../result/types.ts'
  * @import { StringMap } from '../../object/types.ts'
  * @import { List } from '../../list/types.ts'
- * @import { Container, IsContainer, ValidateE, ValidationError, Visitor } from '../common/types.ts'
+ * @import { Container, IsContainer, ValidationError, Visitor } from '../common/types.ts'
  * @import { Unknown } from '../ts/types.ts'
  * @import { Parse } from './types.ts'
  */

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

@@ -5,24 +5,34 @@
  * 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.
  *
@@ -32,7 +42,7 @@
  * @import { Result as CommonResult } from '../../result/types.ts'
  * @import { StringMap } from '../../object/types.ts'
  * @import { List } from '../../list/types.ts'
- * @import { Container, IsContainer, ValidateE, ValidationError, Visitor } from '../common/types.ts'
+ * @import { Container, IsContainer, ValidationError, Visitor } from '../common/types.ts'
  * @import { Unknown } from '../ts/types.ts'
  * @import { Parse } from './types.ts'
  */
@@ -78,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 =
     /**
@@ -100,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]))))
     }
@@ -110,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 =
     /**
@@ -130,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,
         )
@@ -156,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.
@@ -175,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 }]
  * ```
  */
@@ -195,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;
         };
     };