functionalscript 0.46.0 → 0.47.0

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

@@ -1,14 +1,84 @@
 /**
- * @import { Type } from '../types.ts'
+ * @import { Or, Type } from '../types.ts'
  * @import { Data } from '../data/types.ts'
+ * @import { Ts, TupleTs } from './types.ts'
+ * @import { Assert } from '../../../asserts/types.ts'
+ * @import { Equal } from '../../ts/types.ts'
  */
 
 import { assertEq } from '../../../asserts/module.f.mjs'
 import { toData, unitBit } from '../data/module.f.mjs'
-import { boolean, number, string, bigint, unknown, array, record, or, option, never } from '../module.f.mjs'
+import { boolean, number, string, bigint, unknown, array, open, record, or, option, rest, never } from '../module.f.mjs'
 import { dataToTs, printer } from './module.f.mjs'
 
+// ── `Ts<T>` over a tuple schema ─────────────────────────────────────────────
+//
+// Spelled as schema *types* rather than `typeof` a value: these are type-level
+// facts, and a value existing only to be pointed at is an unused one.
+//
+// `TupleTs` splits off the trailing run of positions admitting `undefined` and
+// renders it optional, which needs a known length. A schema array of non-fixed
+// length — what `.map()` produces — has no trailing position to split off, so
+// it keeps its element type instead, the homomorphic mapping's answer. Pinned
+// because a split that falls back to the empty tuple silently renders such a
+// schema `readonly []`, and nothing else here would have caught it.
+/** @typedef {Assert<Equal<Ts<readonly (typeof number | typeof bigint)[]>, readonly (number | bigint)[]>>} _NonFixedLength */
+
+// `option(t)` is `or(t, undefined)`; these are the schema types it produces.
+/** @typedef {Or<readonly [typeof boolean, undefined]>} _OptionBoolean */
+/** @typedef {Or<readonly [typeof string, undefined]>} _OptionString */
+
+// A variadic tuple is the shape the `length` guard exists for, and the only
+// one: its peel *succeeds*, binding the unknown-length prefix to `I`, so
+// without the guard the reconstruction flattens it. The others below reach the
+// fallback because their peel fails, and are held by that alone.
+//
+// Asserted as assignability rather than with `Equal<>`. `Equal<>` reports this
+// shape as unchanged whether or not the guard is in place — it cannot see the
+// difference — so an `Equal<>` pin here passes over the bug it is meant to
+// catch. What the flattening actually costs is a string admitted in the number
+// prefix, so that is what these state.
+/** @typedef {readonly [...(typeof number)[], _OptionString]} _VariadicSchema */
+/** @typedef {Assert<readonly [1, 'x', 2] extends Ts<_VariadicSchema> ? false : true>} _VariadicPrefixRejectsMixedPrefix */
+/** @typedef {Assert<readonly [1, 2, 'x'] extends Ts<_VariadicSchema> ? true : false>} _VariadicPrefixAdmitsItsOwnShape */
+
+// A rest element after a fixed prefix is the same shape from the other side,
+// and is held for the same reason: `length` is `number`, so the mapping stands.
+//
+// This row and `_NonFixedLength` document intent rather than discriminate a
+// mechanism. The guard and the fallback both answer `M` for these two shapes,
+// so neither single mutation moves them — only removing both at once does.
+// The rows that pin one mechanism each are `_VariadicPrefixRejectsMixedPrefix`
+// (the guard), `_OptionalMember` (the fallback) and
+// `_UnionKeepsBranchCorrelation` (the distribution).
+/** @typedef {Assert<Equal<Ts<readonly [typeof number, ...(typeof string)[]]>, readonly [number, ...string[]]>>} _RestTuple */
+
+// A schema whose own tuple type already marks a member optional is held by the
+// *fallback* rather than the length guard: its length is `1 | 2`, not `number`,
+// so it reaches the split, where the peel needs a required last element and
+// finds none. An optional position is what this transform produces, so one the
+// caller wrote is already in the target form and the mapping stands.
+/** @typedef {Assert<Equal<Ts<readonly [typeof number, (typeof string)?]>, readonly [number, string?]>>} _OptionalMember */
+
+// A union of tuple schemas is split per member, not once across the union.
+// Splitting the union lets the two halves distribute independently and the
+// spread then pairs every prefix with every suffix, so `[number, boolean]` —
+// A's prefix with B's suffix — would pass. Assignability again: this is a
+// statement about which values the union admits.
+/** @typedef {readonly [typeof number, _OptionString]} _BranchA */
+/** @typedef {readonly [typeof string, _OptionBoolean, _OptionNumber]} _BranchB */
+/** @typedef {Or<readonly [typeof number, undefined]>} _OptionNumber */
+/** @typedef {Assert<readonly [1, true] extends TupleTs<_BranchA | _BranchB> ? false : true>} _UnionKeepsBranchCorrelation */
+/** @typedef {Assert<readonly [1, 'x'] extends TupleTs<_BranchA | _BranchB> ? true : false>} _UnionAdmitsItsOwnBranches */
+
+/** @typedef {Assert<Equal<Ts<readonly [typeof number, typeof bigint, _OptionBoolean, _OptionString]>, readonly [number, bigint, (boolean | undefined)?, (string | undefined)?]>>} _OptionalTail */
+
+// Only the *trailing* run: TypeScript forbids a required element after an
+// optional one, so an interior position that admits `undefined` stays required.
+/** @typedef {Assert<Equal<Ts<readonly [_OptionString, typeof number]>, readonly [string | undefined, number]>>} _InteriorStaysRequired */
+
 const toTs = printer()
+
 const toTsMut = printer(true)
 
 /** @type {(rtti: Type, expected: string) => void} */
@@ -96,10 +166,24 @@ export const proof = {
         negInf: () => eq(-Infinity, 'number'),
         string: () => eq('hello', '"hello"'),
         bigint: () => eq(7n, '7n'),
+        // a bare tuple is closed, so it prints exactly — the same rendering
+        // `Ts<>` gives it, which is what makes that cast sound
         emptyTuple: () => eq([], 'readonly[]'),
         tuple: () => eq([12, true], 'readonly[12,true]'),
-        // an unconstrained struct is the whole object kind
-        emptyStruct: () => eq({}, '{readonly[k in string]?:unknown}'),
+        // a position the array may end before prints optional, as the key it
+        // is the array counterpart of does
+        optionalTuplePosition: () => eq(
+            [number, option(string)],
+            'readonly[number,(undefined|string)?]',
+        ),
+        allOptionalTuple: () => eq(
+            [option(number)],
+            'readonly[(undefined|number)?]',
+        ),
+        // a declared `unknown` key is a key the container has, so it is not
+        // dropped the way an `open` struct's is
+        emptyStruct: () => eq({}, '{}'),
+        unknownProp: () => eq({ a: unknown }, '{readonly"a"?:unknown}'),
         struct: () => eq(
             { a: number, b: string },
             '{readonly"a":number,readonly"b":string}',
@@ -128,7 +212,45 @@ export const proof = {
         thunks: () => eq(or(number, string), 'number|string'),
         mixed: () => eq(or(42, string), '42|string'),
     },
+    // The open and stated-rest forms. An object type is structurally open in
+    // TypeScript, so an `open` struct prints as wide as it can be printed;
+    // a tuple has a rest element, so this printer says exactly what the schema
+    // says — `Ts<>` renders the same tail, for the same reason.
+    open: {
+        // an unconstrained tuple, or struct, is the whole kind
+        emptyTuple: () => eq(open([]), 'readonly(unknown)[]'),
+        unconstrainedTuple: () => eq(open([unknown]), 'readonly(unknown)[]'),
+        tuple: () => eq(open([12, true]), 'readonly[12,true,...readonly(unknown)[]]'),
+        emptyStruct: () => eq(open({}), '{readonly[k in string]?:unknown}'),
+        struct: () => eq(open({ a: number }), '{readonly"a":number}'),
+        // an unconstrained key *is* dropped once the container is open
+        unknownProp: () => eq(open({ a: unknown }), '{readonly[k in string]?:unknown}'),
+        // a stated rest prints as the rest element / index signature it is.
+        // The tail admits `undefined` because a hole past the prefix is no
+        // member, so a reader skips it and the index reads `undefined`.
+        tupleRest: () => eq(rest([number], string), 'readonly[number,...readonly(undefined|string)[]]'),
+        structRest: () => eq(
+            rest({ a: number }, string),
+            '{readonly"a":number}&{readonly[k in string]?:number|string}',
+        ),
+        // `unknown` already admits `undefined`, so the open tail is unchanged
+        openIsAnUnconstrainedRest: () => {
+            assertEq(toTs(rest([number], unknown)), toTs(open([number])))
+            assertEq(toTs(rest({ a: number }, unknown)), toTs(open({ a: number })))
+        },
+        // an empty rest is the bare form, recognized here through the data
+        // form — including the `[or()]` spelling, which `RestTs` cannot see
+        // and so renders with a (wider, still sound) tail
+        emptyRestIsTheBareForm: () => {
+            assertEq(toTs(rest([number], never)), toTs([number]))
+            assertEq(toTs(rest([number], [never])), toTs([number]))
+        },
+        mut: () => eqMut(rest([number], string), '[number,...(undefined|string)[]]'),
+    },
     never: () => eq(never, 'never'),
+    // an array with no admissible element is the empty array, and nothing
+    // past a prefix is what prints as an exact-length tuple
+    arrayOfNever: () => eq(array(never), 'readonly[]'),
     // union members follow the canonical kind order, `undefined` first
     option: () => eq(option(number), 'undefined|number'),
     normalization: {
@@ -198,9 +320,20 @@ export const proof = {
         },
     },
     data: {
+        // The tail admits `undefined` on top of the rest — a hole past the
+        // prefix is no member, so a reader skips it and the index reads
+        // `undefined`. A rest that already admits it is printed as it is.
         tupleWithRest: () => {
             eqData([{}, { array: [{ prefix: [{ number: true }], rest: { string: true } }] }],
-                [[], 'readonly[number,...readonly(string)[]]'])
+                [[], 'readonly[number,...readonly(undefined|string)[]]'])
+            eqData([{}, { array: [{ prefix: [{ number: true }], rest: { unit: unitBit(undefined), string: true } }] }],
+                [[], 'readonly[number,...readonly(undefined|string)[]]'])
+        },
+        // an exact-length pattern is the one that prints without a rest
+        // element — what a bare, closed tuple converts to
+        exactLengthTuple: () => {
+            eqData([{}, { array: [{ prefix: [{ number: true }, { string: true }] }] }],
+                [[], 'readonly[number,string]'])
         },
         structWithRest: () => {
             // the index signature must cover the declared keys too, so the
@@ -226,7 +359,7 @@ export const proof = {
         array: () => eqMut(array(number), '(number)[]'),
         nestedArray: () => eqMut(array(array(boolean)), '((boolean)[])[]'),
         record: () => eqMut(record(string), '{[k in string]?:string}'),
-        tuple: () => eqMut([12, true], '[12,true]'),
+        tuple: () => eqMut(open([12, true]), '[12,true,...(unknown)[]]'),
         struct: () => eqMut({ a: number, b: string }, '{"a":number,"b":string}'),
     },
     throw: {

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

@@ -9,7 +9,8 @@
  *
  * @module
  */
-import type { Tag0, Tag1, Struct, Tuple, Type } from '../types.ts';
+import type { And, Equal } from '../../ts/types.ts';
+import type { Tag0, Tag1, Or, Struct, Tuple, Type, ConstObject } from '../types.ts';
 import type { phantomKey } from '../../phantom/types.ts';
 import type { StringMap } from '../../object/types.ts';
 /**
@@ -52,28 +53,132 @@ export type RecordTs<T extends Type> = {
     readonly [K in string]?: Ts<T>;
 };
 /**
- * Maps a tuple schema to a readonly tuple of resolved types.
- *
- * **The commented-out line is the accurate mapping.** A tuple schema is *open*
- * — a longer array is a member of the set it describes (see "Structs and
- * tuples are open" in `../README.md`) — and the open form below says so. It is
- * commented out because TypeScript could not handle it, so this renders the
- * closed approximation instead.
- *
- * That is a limitation of this renderer, **not** a statement about the value
- * model. Do not cite the exact mapping as evidence that tuples are closed and
- * add a length check to `../parse/module.f.mjs`; that inference is what
- * produced #1622.
+ * Maps a tuple schema to a readonly tuple of resolved types, with the
+ * **trailing** positions whose sets admit `undefined` rendered optional:
+ * `[number, bigint, option(boolean), option(string)]` becomes
+ * `readonly[number, bigint, (boolean|undefined)?, (string|undefined)?]`.
+ *
+ * That is the same rule {@link StructTs} applies per key — a member is
+ * required exactly when its set excludes `undefined` — so an array may stop
+ * at the last required position, which is what `../parse/module.f.mjs` and
+ * `../validate/module.f.mjs` accept. Only the trailing run: TypeScript
+ * forbids a required element after an optional one, so a position that admits
+ * `undefined` with a required one after it stays required with `undefined` in
+ * its type (see {@link _tupleInteriorOption}).
+ *
+ * **Deriving this generically took three specific moves**, each defeating an
+ * error that sank the obvious spellings — do not simplify it back:
+ *
+ * - `MappedTs` resolves `Ts<>` **once per position**, and the split then walks
+ *   the mapped tuple rather than the schema. Testing `undefined extends
+ *   Ts<Last>` during the walk evaluates `Ts<>` twice per position and raises
+ *   TS2589 (excessively deep).
+ * - `Extract<…, readonly unknown[]>` is what makes a mapped type spreadable.
+ *   Spreading it directly raises TS2574 ("a rest element type must be an array
+ *   type") — TypeScript cannot prove a mapped type over a generic `keyof T` is
+ *   array-shaped. An `& readonly unknown[]` intersection silences that too,
+ *   but leaves the intersection in the rendered type, so `Equal<>` against a
+ *   hand-written tuple fails; `Extract` resolves clean.
+ * - `extends infer M extends …` forces each intermediate to resolve before it
+ *   is used in rest position. Without it the concrete instantiation works and
+ *   the generic one does not.
+ *
+ * A recursive form that prepends onto an all-optional tail (rather than
+ * splitting) crashes the compiler outright — a Go stack overflow in tsgo
+ * 7.0.2, not a diagnostic.
+ *
+ * **The exact length is the model, not an approximation of it.** A bare tuple
+ * schema is *closed* — the positions it declares and no others (see "Structs
+ * and tuples are closed" in `../README.md`) — which is what a TypeScript tuple
+ * already means, so this rendering and the schema denote the same set and
+ * `validate`'s success cast is sound. A schema admitting more says so, and
+ * {@link RestTs} renders the tail it says it with.
  */
-export type TupleTs<T extends Tuple> = {
+type MappedTs<T extends Tuple> = Extract<{
     readonly [K in keyof T]: Ts<T[K]>;
-};
+}, readonly unknown[]>;
+type RequiredPart<M extends readonly unknown[]> = M extends readonly [...infer I extends readonly unknown[], infer L] ? undefined extends L ? RequiredPart<I> : M : M;
+type OmittablePart<M extends readonly unknown[], Acc extends readonly unknown[] = readonly []> = M extends readonly [...infer I extends readonly unknown[], infer L] ? undefined extends L ? OmittablePart<I, readonly [L, ...Acc]> : Acc : Acc;
+type AsOptional<O extends readonly unknown[]> = Extract<{
+    readonly [K in keyof O]+?: O[K];
+}, readonly unknown[]>;
+export type TupleTs<T extends Tuple> = MappedTs<T> extends infer M extends readonly unknown[] ? SplitTs<M> : never;
+/**
+ * Splits one mapped tuple. `M` is naked in the first conditional on purpose:
+ * that distributes over a union of tuples, so each member is split and rebuilt
+ * whole. Splitting the union instead lets `RequiredPart` and `OmittablePart`
+ * distribute separately, and the spread then recombines every prefix with
+ * every suffix — a union of `[number, option(string)]` and
+ * `[string, option(boolean), option(number)]` would admit `[number, boolean]`.
+ *
+ * Splitting a trailing run off also needs a *fixed* length. A schema array of
+ * non-fixed length (what `.map()` produces) and a variadic tuple
+ * (`[...(typeof number)[], option(string)]`) both have `length: number` and no
+ * last position to peel, so they keep the mapping as it is — splitting them
+ * would drop the element type and the prefix's shape respectively, and widen
+ * what `Ts<T>` admits.
+ */
+type SplitTs<M extends readonly unknown[]> = M extends readonly unknown[] ? number extends M['length'] ? M : RequiredPart<M> extends infer R extends readonly unknown[] ? OmittablePart<M> extends infer O extends readonly unknown[] ? readonly [...R, ...AsOptional<O>] : never : never : never;
 type OptionalFields<T extends Struct> = {
     readonly [K in keyof T as undefined extends Ts<T[K]> ? K : never]?: Ts<T[K]>;
 };
 type RequiredFields<T extends Struct> = {
     readonly [K in keyof T as undefined extends Ts<T[K]> ? never : K]: Ts<T[K]>;
 };
+/**
+ * Maps a container with a stated rest to the resolved type of its declared
+ * members, **plus the tail the rest states**.
+ *
+ * The struct kind needs no tail: an object type is width-open in TypeScript,
+ * so `ConstTs<C>` already admits the undeclared keys — as wide as TypeScript
+ * can render either way.
+ *
+ * The tuple kind does, and a rename of the old exact-only rendering would have
+ * relocated the unsound cast rather than removing it: `Ts<typeof open([42])>`
+ * would be the exact `readonly[42]` while `validate(open([42]))([42, 'x'])`
+ * accepts and hands back two elements.
+ *
+ * **The tail admits `undefined`.** Both readers check an undeclared member as
+ * a member, and a hole past the prefix is no member, so
+ * `validate(rest([42], string))([42, , ])` is `ok` and index 1 reads
+ * `undefined`. `...(Ts<R> | undefined)[]` is what "a rest never sees an absent
+ * member" says on the type side. The common case pays nothing: `open(c)`'s
+ * rest is `unknown`, which already admits `undefined`.
+ *
+ * **An empty rest renders no tail**, since `rest(c, or())` is the bare `c` —
+ * one set, so one rendering, and `readonly[42, ...undefined[]]` would admit
+ * the `[42, undefined]` both readers reject. What counts as empty is
+ * `emptyRest`'s question in `../data/module.f.mjs`, and that is a `toData`
+ * conversion plus `subset` both ways, which `types.ts` cannot invoke. Nor is
+ * `Ts<R> extends never` a substitute — `Ts<readonly[Or<readonly[]>]>` is
+ * `readonly[never]`, whose `length` is `1`. So this recognizes the one
+ * directly spellable empty rest, `or()`, and **keeps the tail whenever it
+ * cannot tell**. The conservatism has a direction: a kept tail is wider than
+ * the schema but sound — every accepted value still has the rendered type,
+ * which is the only direction a success cast needs — while a wrongly dropped
+ * one is the unsound cast. Where that leaves this and the runtime printer
+ * disagreeing (`rest([42], readonly[Or<readonly[]>])`, which the data form
+ * recognizes as empty and this does not) the printer is the narrower of the
+ * two; see {@link _restEmptyIndirect}.
+ *
+ * The other place the two differ is a rest with **no prefix**, which is the
+ * uniform array: `rest([], string)` and `array(string)` are one set, so the
+ * printer — which goes through the data form and sees one node — prints
+ * `ArrayTs`'s `readonly(string)[]` for both, while this renders the tail and
+ * so answers `readonly(string|undefined)[]` for the first. The tail is the
+ * sound one of the two, a hole being no member on either spelling; `ArrayTs`
+ * carries that gap already and closing it is its own change, not this one's.
+ * See {@link _restNoPrefix}.
+ */
+export type RestTs<C extends ConstObject, R extends Type> = C extends Tuple ? TupleRestTs<C, R> : ConstTs<C>;
+/**
+ * `[R] extends [...]` rather than a naked `R`: a naked one distributes, and a
+ * union rest would then render a union of tuples rather than a tuple whose
+ * tail is a union.
+ */
+type TupleRestTs<C extends Tuple, R extends Type> = [
+    R
+] extends [Or<readonly []>] ? TupleTs<C> : TupleTs<C> extends infer M extends readonly unknown[] ? readonly [...M, ...ReadonlyArray<Ts<R> | undefined>] : never;
 /** Maps a struct schema to a readonly object of resolved types, with optional fields for schemas that include `undefined`. */
 export type StructTs<T extends Struct> = (keyof OptionalFields<T> extends never ? unknown : OptionalFields<T>) & (keyof RequiredFields<T> extends never ? unknown : RequiredFields<T>);
 /**
@@ -96,6 +201,33 @@ export type StructTs<T extends Struct> = (keyof OptionalFields<T> extends never
  * // Ts<typeof my>  →  MyType
  * ```
  *
+ * `MyType` here is an unchecked annotation — nothing derives it, so a typo
+ * (the wrong type, or one that has drifted from `myConst`) is trusted
+ * silently. Pin it down with two asserts, one against the un-annotated
+ * `myThunk` (forces the real structural walk) and one against the
+ * phantom-wrapped `my` (catches the two drifting apart):
+ *
+ * ```ts
+ * type _Check0 = Assert<Check<MyType, typeof myThunk>>
+ * type _Check1 = Assert<Check<MyType, typeof my>>
+ * ```
+ *
+ * {@link Check3} is the same pair written once:
+ *
+ * ```ts
+ * type _Check = Assert<Check3<MyType, typeof myThunk, typeof my>>
+ * ```
+ *
+ * See `fjs/edag/module.f.mjs` (`_exp`/`exp`) for this in practice. Note also
+ * that the phantom branch below does `Exclude<O, undefined>`, so a `MyType`
+ * that includes bare `undefined` at its top level will never satisfy
+ * `_Check1`. That is a constraint on the wrapped type, not on how wide it
+ * is: a union is fine when no member contributes a top-level `undefined` —
+ * `fjs/edag` wraps `Exp`, the whole node union, because its `undefined` is
+ * the tagged `['undefined']` rather than the bare value. Wrap one type per
+ * recursive cycle, and if the natural one does carry a top-level
+ * `undefined`, wrap a narrower node type inside the cycle instead.
+ *
  * @example
  * ```ts
  * type A = Ts<typeof string>          // string
@@ -108,5 +240,21 @@ export type Ts<T extends Type> = unknown extends T ? Unknown : T extends {
     readonly [phantomKey]?: infer O;
 } ? Exclude<O, undefined> : T extends () => infer I ? (I extends readonly ['const', infer C] ? ConstTs<C> : I extends readonly ['boolean'] ? boolean : I extends readonly ['number'] ? number : I extends readonly ['string'] ? string : I extends readonly ['bigint'] ? bigint : I extends readonly ['unknown'] ? Unknown : I extends readonly ['array', infer E extends Type] ? readonly Ts<E>[] : I extends readonly ['record', infer E extends Type] ? {
     readonly [k in string]?: Ts<E>;
-} : I extends readonly ['or', ...infer A extends readonly Type[]] ? Ts<A[number]> : never) : ConstTs<T>;
+} : I extends readonly ['or', ...infer A extends readonly Type[]] ? Ts<A[number]> : I extends readonly ['rest', infer C extends ConstObject, infer R extends Type] ? RestTs<C, R> : never) : ConstTs<T>;
+/**
+ * Pins a hand-written TypeScript type `A` against the type an rtti schema `B`
+ * actually derives to — `Assert<Check<A, B>>` reads as "`A` is `Ts<B>`".
+ * This is the assertion the {@link Ts} doc above uses for the two-Phantom-check
+ * pattern, and the one every hand-written recursive type in this codebase (a
+ * `Tree`, a `LockMap`, …) pins against its rtti schema with.
+ */
+export type Check<A, B extends Type> = Equal<A, Ts<B>>;
+/**
+ * The two-assert `Phantom` pattern from the {@link Ts} doc, in one
+ * assert: `T` is both `Ts<R0>` (the raw thunk, forcing the structural walk)
+ * and `Ts<R1>` (the phantom-wrapped export). Checking only the wrapped
+ * export is a tautology — `Ts<>` short-circuits to the annotation — so the
+ * `R0` half is what gives this teeth.
+ */
+export type Check3<T, R0 extends Type, R1 extends Type> = And<Equal<T, Ts<R0>>, Equal<T, Ts<R1>>>;
 export {};

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

@@ -11,7 +11,7 @@
  * ```
  * Type = Const | Thunk
  * Thunk = () => Info
- * Info = ['const', Const] | Info0<Tag0> | Info1<Tag1, Type>
+ * Info = ['const', Const] | Info0<Tag0> | Info1<Tag1, Type> | InfoRest<ConstObject, Type>
  * ```
  *
  * ## Nullary schemas (no type parameter)
@@ -32,6 +32,13 @@
  * Inside a recursive `Thunk`-based definition, wrap consts with `() => ['const', c]`
  * to keep the schema uniform.
  *
+ * ## Undeclared members
+ *
+ * A `Struct` or a `Tuple` on its own is **closed** — it admits the members it
+ * declares and no others. `rest(c, r)` states the set every undeclared member
+ * belongs to, and `open(c)` is `rest(c, unknown)`: any undeclared member at
+ * all. See "Structs and tuples are closed" in `./README.md`.
+ *
  * ## Converting to TypeScript types
  *
  * See `./ts/module.f.ts` for `Ts<T>` and the `*Ts` transformer types.
@@ -55,7 +62,7 @@ export type Tag0 = typeof tag0List[number];
 /** Info tuple for a nullary tag: `readonly[tag]`. */
 export type Info0<T extends Tag0> = T extends Tag0 ? readonly [T] : never;
 /** Any schema: a `Const` used directly, or a `Thunk` for tag-based/recursive schemas. */
-export type Type = (() => (readonly ['const', Const] | readonly ['bigint'] | readonly ['boolean'] | readonly ['number'] | readonly ['string'] | readonly ['unknown'] | readonly ['array', Type] | readonly ['record', Type] | readonly ['or', ...readonly Type[]])) | Const;
+export type Type = (() => (readonly ['const', Const] | readonly ['bigint'] | readonly ['boolean'] | readonly ['number'] | readonly ['string'] | readonly ['unknown'] | readonly ['array', Type] | readonly ['record', Type] | readonly ['or', ...readonly Type[]] | readonly ['rest', ConstObject, Type])) | Const;
 /** The type of a nullary thunk for `Tag0`. */
 export type _Type0<T extends Tag0> = () => Info0<T>;
 /** Schema type for `boolean`. */
@@ -74,10 +81,31 @@ export type Tag1 = 'array' | 'record';
 export type Info1<K extends Tag1, T extends Type> = K extends Tag1 ? readonly [K, T] : never;
 /** The type of a unary thunk for `Tag1` with inner type `T`. */
 export type Type1<K extends Tag1, T extends Type> = () => Info1<K, T>;
-export type _MakeType1<K extends Tag1> = <T extends Type>(t: T) => Type1<K, T>;
+export type _MakeType1<K extends Tag1> = <const T extends Type>(t: T) => Type1<K, T>;
 /** Schema type for a readonly array with element type `T`. */
 export type Array<T extends Type> = Type1<'array', T>;
 /** Schema type for a record (index signature) with value type `T`. */
 export type Record<T extends Type> = Type1<'record', T>;
 /** Schema type for a union of types `T`. */
 export type Or<T extends readonly Type[]> = () => readonly ['or', ...T];
+/**
+ * Info tuple for a container with a stated rest: `readonly[tag, container,
+ * rest]`, where `rest` is the set every member the container does not declare
+ * belongs to. A bare `C` is the same set with a rest of `never`, and needs no
+ * spelling of its own.
+ */
+export type InfoRest<C extends ConstObject, R extends Type> = readonly ['rest', C, R];
+/**
+ * Schema type for a container `C` whose undeclared members are `R`. Both
+ * parameters are required: `never` — the bare `C` — is the identity a schema
+ * writes by leaving the wrapper off, so there is no default to state.
+ */
+export type Rest<C extends ConstObject, R extends Type> = () => InfoRest<C, R>;
+export type _MakeRest = <const C extends ConstObject, const R extends Type>(c: C, r: R) => Rest<C, R>;
+/**
+ * `open`'s signature. It is not `_MakeRest` partially applied: the `const`
+ * modifier is what keeps `open([42])` a literal tuple rather than widening it
+ * to `Type[]`, so the modifier has to be restated here. `../proof.f.mjs` pins
+ * that, as it does for every other `const`-taking constructor.
+ */
+export type _MakeOpen = <const C extends ConstObject>(c: C) => Rest<C, Unknown>;

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

@@ -0,0 +1,120 @@
+/**
+ * Runtime validation of unknown values against RTTI schemas — the verbatim
+ * reader.
+ *
+ * The main entry point is `validate(rtti)`, which takes a schema `Type` and
+ * returns a `Validate<T>` function. When called with an unknown value, it
+ * returns a `Result` that is either `['ok', value]` — **the value it was
+ * given** — or `['error', { path, message }]`.
+ *
+ * ## What distinguishes it from `parse`
+ *
+ * `../parse/module.f.mjs` answers "read this value as `T`" and builds a fresh
+ * value holding exactly what the schema declares. `validate` answers "is this
+ * value a `T`?" about the value itself, so on success the caller keeps the
+ * object it passed in — same reference, same members, same serialization:
+ *
+ * ```js
+ * const schema = { a: number, b: option(string) }
+ * parse(schema)({ a: 1, extra: 'x' })     // ['ok', { a: 1, b: undefined }]
+ * validate(schema)({ a: 1, extra: 'x' })  // ['ok', { a: 1, extra: 'x' }]
+ * ```
+ *
+ * The two agree on **acceptance**: every value one accepts the other accepts,
+ * with the same error `path` and `message`. They differ only in what a success
+ * carries. `./proof.f.mjs` pins that agreement as a table rather than leaving
+ * it to convention. Which reader a caller wants, and why both exist, is in
+ * "The two schema-form readers" in `../README.md`.
+ *
+ * ## Structs and tuples are closed
+ *
+ * Closedness is the shared rule, not a `parse` detail — see "Structs and
+ * tuples are closed" in `../README.md`. A bare `Struct` or `Tuple` admits the
+ * members it declares and no others, so an undeclared key or an index past the
+ * prefix rejects the value. A tuple answers by **length** as well as by
+ * member, because a hole past the prefix is no member and would slip through
+ * the member check alone.
+ *
+ * Closedness is about *undeclared* members and leaves the required/optional
+ * rule alone: an absent member reads as `undefined`, so a member is required
+ * exactly when its set excludes `undefined`, and a schema whose trailing
+ * position admits it still accepts a shorter array. A tuple schema declares by
+ * length, so a hole in the *schema* is a position whose schema is `undefined`
+ * — see "A hole is a declared position" in `../README.md`.
+ *
+ * The length check is the model rather than an inference from `Ts<>`. #1622
+ * added one by reading `Ts<readonly[42]>`'s exact tuple as the value model
+ * while the model said open, and it was reverted for that reason; what has
+ * changed since is the model, not the reading.
+ *
+ * ## Stated rests
+ *
+ * `rest(c, r)` admits the declared members plus any number of members
+ * belonging to `r`, and `open(c)` — `rest(c, unknown)` — admits anything else
+ * besides. This widens what is accepted and changes nothing else: a success
+ * still carries the very value it was given, undeclared members included.
+ *
+ * ## Dispatch strategy
+ *
+ * Schema recognition is delegated to `visit` in `../common/module.f.mjs`,
+ * which routes each `Type` variant to a handler in the `Visitor` record
+ * defined below; nothing here walks the `Type` ADT itself. The container
+ * handlers drive `eachEntry` in its no-accumulator mode — the mode its JSDoc
+ * describes for "a caller whose whole question is 'did every entry
+ * succeed?'" — so a validation allocates nothing per entry. The data form's
+ * `validate` (`../data/module.f.mjs`) is the same shape over `Data`.
+ *
+ * ## Recursion safety
+ *
+ * The inner validator of an `array`, a `record` or a `rest` is instantiated
+ * lazily — only after confirming there is a member for it to read. This
+ * prevents infinite recursion when validating recursive schemas like
+ * `const list = () => ['array', list]`.
+ *
+ * See `./types.ts` for the `Path`/`Result`/`Validate`/`ValidationError`
+ * type-level API.
+ *
+ * @module
+ *
+ * @import { Unknown } from '../ts/types.ts'
+ * @import { ConstObject, Info1, Tag1, Type } from '../types.ts'
+ * @import { Container, Fits, IsContainer, SchemaEntries, Validate, ValidateE, Visitor } from '../common/types.ts'
+ * @import { StringMap } from '../../object/types.ts'
+ */
+import type { Type } from '../types.ts';
+import type { Validate } from '../common/types.ts';
+/**
+ * Creates a validator function for the given RTTI schema: a `Thunk` for
+ * tag-based schemas, or a `Const` (primitive literal, tuple, or struct) for
+ * exact-value schemas.
+ *
+ * The returned function takes an unknown value and returns either
+ * `['ok', value]` — the very value it was given, not a reconstruction — or
+ * `['error', { path, message }]` describing the failure location.
+ *
+ * Use it when the question is "is this value of this shape?" and the value has
+ * to survive the question intact. Use `../parse/module.f.mjs` when the answer
+ * wanted is a value built to the schema.
+ *
+ * @example
+ * ```js
+ * const v = validate(array(number))
+ * const input = [1, 2, 3]
+ * v(input)      // ['ok', input] — the same array, not a copy
+ * v([1, 'two']) // ['error', { path: ['1'], message: 'unexpected value' }]
+ *
+ * // closed, so a member the schema does not name rejects the value
+ * validate([number, number])([1, 2, 3])    // ['error', …]
+ * validate({ a: number })({ a: 1, b: 2 })  // ['error', …]
+ *
+ * // an absent optional member stays absent
+ * validate({ a: number, b: option(string) })({ a: 1 })  // ['ok', { a: 1 }]
+ *
+ * // a stated rest says what the undeclared members may be; `open` says anything
+ * validate(rest({ a: number }, number))({ a: 1, b: 2 })  // ['ok', { a: 1, b: 2 }]
+ * validate(open({ a: number }))({ a: 1, b: 'x' })        // ['ok', { a: 1, b: 'x' }]
+ * ```
+ *
+ * @type {<const T extends Type>(rtti: T) => Validate<T>}
+ */
+export declare const validate: <const T extends Type>(rtti: T) => Validate<T>;