functionalscript 0.45.0 → 0.46.1

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

@@ -109,32 +109,32 @@ export const proof = {
             error: () => assertError(parse(/** @type {const} */ (42))(43)),
         },
         nan: {
-            ok: () => assertOk(parse(/** @type {number} */ (NaN))(NaN)),
+            ok: () => assertOk(parse(NaN)(NaN)),
             error: () => {
-                assertError(parse(/** @type {number} */ (NaN))(0))
+                assertError(parse(NaN)(0))
                 assertError(parse(/** @type {const} */ (0))(NaN))
                 assertError(parse(/** @type {const} */ (42))(NaN))
             },
         },
         infinity: {
             ok: () => {
-                assertOk(parse(/** @type {number} */ (Infinity))(Infinity))
-                assertOk(parse(/** @type {number} */ (-Infinity))(-Infinity))
+                assertOk(parse(Infinity)(Infinity))
+                assertOk(parse(-Infinity)(-Infinity))
             },
             error: () => {
-                assertError(parse(/** @type {number} */ (Infinity))(-Infinity))
-                assertError(parse(/** @type {number} */ (Infinity))(0))
+                assertError(parse(Infinity)(-Infinity))
+                assertError(parse(Infinity)(0))
             },
         },
         signedZero: {
             // `Object.is` distinguishes +0 and -0; `===` treats them equal.
             distinct: () => {
                 assertError(parse(/** @type {const} */ (0))(-0))
-                assertError(parse(/** @type {number} */ (-0))(0))
+                assertError(parse(-0)(0))
             },
             self: () => {
                 assertOk(parse(/** @type {const} */ (0))(0))
-                assertOk(parse(/** @type {number} */ (-0))(-0))
+                assertOk(parse(-0)(-0))
             },
         },
         string: {
@@ -155,14 +155,31 @@ export const proof = {
                 const r = parse(t)([42, 'hello'])
                 assertStructurallySame(unwrap(r), [42, 'hello'])
             },
-            // The key behavior change vs `validate`: extra tuple elements are dropped.
-            extraItemsDropped: () => {
+            // A tuple is OPEN: a longer array is accepted, and the extras are
+            // absent from what `parse` builds. This is deliberate — see
+            // "Structs and tuples are open" in ../README.md. Do not add a
+            // length check here on the strength of `Ts<readonly [42]>` being
+            // an exact tuple; that mapping is exact only because TypeScript
+            // could not express the open one (see ../ts/types.ts `TupleTs`),
+            // and reading it as a design decision is what produced #1622.
+            extraItemsAcceptedAndDropped: () => {
                 const r = parse(/** @type {const} */ ([42]))([42, 'extra'])
                 assertStructurallySame(unwrap(r), [42])
+                const long = parse(/** @type {const} */ ([42]))([42, 1, 2, 3])
+                assertStructurallySame(unwrap(long), [42])
+            },
+            // An absent member reads as `undefined`, so a position is required
+            // exactly when its set excludes `undefined` — the same rule the
+            // data form states for object keys, applied to arrays.
+            shortArrayFillsAnOptionalPosition: () => {
+                const r = parse([number, option(string)])([42])
+                assertStructurallySame(unwrap(r), [42, undefined])
             },
             error: () => {
                 assertError(parse(/** @type {const} */ ([42]))([99]))
                 assertError(parse(/** @type {const} */ ([42]))({}))
+                // `42` excludes `undefined`, so position 0 is required.
+                assertError(parse(/** @type {const} */ ([42]))([]))
             },
         },
         struct: {
@@ -171,8 +188,10 @@ export const proof = {
                 const r = parse(t)({ a: 42, b: 'hello' })
                 assertStructurallySame(unwrap(r), { a: 42, b: 'hello' })
             },
-            // Undeclared properties are dropped from the constructed value.
-            extraKeysDropped: () => {
+            // A struct is OPEN, on the same terms as a tuple: undeclared
+            // properties are accepted and absent from what `parse` builds.
+            // See "Structs and tuples are open" in ../README.md.
+            extraKeysAcceptedAndDropped: () => {
                 const r = parse(/** @type {const} */ ({ a: /** @type {const} */ (42) }))({ a: 42, b: 'extra' })
                 assertStructurallySame(unwrap(r), { a: 42 })
             },
@@ -196,7 +215,7 @@ export const proof = {
             const input = [1, 2, 3]
             /** @type {readonly number[]} */
             const out = unwrap(parse(array(number))(input))
-            assert(out !== /** @type {unknown} */ (input), 'expected a fresh array')
+            assert(out !== input, 'expected a fresh array')
             assertStructurallySame(out, [1, 2, 3])
         },
         error: () => {
@@ -224,7 +243,7 @@ export const proof = {
             const input = { a: 1, b: 2 }
             /** @type {Record<string, number>} */
             const out = unwrap(parse(record(number))(input))
-            assert(out !== /** @type {unknown} */ (input), 'expected a fresh record')
+            assert(out !== input, 'expected a fresh record')
             assertStructurallySame(out, { a: 1, b: 2 })
         },
         error: () => {

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

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

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

@@ -19,6 +19,7 @@
  */
 
 import { assertNotNullish } from '../../../asserts/module.f.mjs'
+import { reservedWords, strictModeReservedWords } from '../../../js/keywords/module.f.mjs'
 import { at, definedEntries } from '../../object/module.f.mjs'
 import { primitive, union, printer as tsPrinter } from '../../ts/module.f.mjs'
 import { cmp, toData, unitBit, unknown as top } from '../data/module.f.mjs'
@@ -30,27 +31,22 @@ const trueBit = unitBit(true)
 const booleanBits = falseBit | trueBit
 
 /**
- * Names that cannot name a TypeScript type alias: the predefined type
- * names (`TS2457`), the ECMAScript reserved words — those reserved only in
- * strict-mode code included, since every module is strict-mode code
- * (`TS1214`) — and the type keywords that fail in the alias-name position.
+ * Names that cannot name a TypeScript type alias: the ECMAScript reserved
+ * words — from the one source of truth for JavaScript keywords,
+ * `fjs/js/keywords`, the strict-mode ones included since every module is
+ * strict-mode code (`TS1214`) — plus TypeScript's predefined type names
+ * (`TS2457`) and the type keywords that fail in the alias-name position.
  */
-const reserved = /** @type {const} */ ([
+/** @type {readonly string[]} */
+const reserved = [
+    ...reservedWords,
+    ...strictModeReservedWords,
     // predefined type names
-    'any', 'bigint', 'boolean', 'false', 'never', 'null', 'number', 'object',
-    'string', 'symbol', 'true', 'undefined', 'unknown', 'void',
-    // ECMAScript reserved words
-    'await', 'break', 'case', 'catch', 'class', 'const', 'continue',
-    'debugger', 'default', 'delete', 'do', 'else', 'enum', 'export',
-    'extends', 'finally', 'for', 'function', 'if', 'import', 'in',
-    'instanceof', 'new', 'return', 'super', 'switch', 'this', 'throw', 'try',
-    'typeof', 'var', 'while', 'with',
-    // reserved in strict-mode code — and every module is strict-mode code
-    'implements', 'interface', 'let', 'package', 'private', 'protected',
-    'public', 'static', 'yield',
+    'any', 'bigint', 'boolean', 'never', 'number', 'object', 'string',
+    'symbol', 'undefined', 'unknown',
     // type-operator keywords, and `intrinsic` (TS2795 outside lib.d.ts)
     'infer', 'intrinsic', 'keyof', 'readonly', 'unique',
-])
+]
 
 /** @type {(c: string) => boolean} */
 const isIdStart = c => (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || c === '_' || c === '$'

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

@@ -51,7 +51,20 @@ export type ArrayTs<T extends Type> = ReadonlyArray<Ts<T>>;
 export type RecordTs<T extends Type> = {
     readonly [K in string]?: Ts<T>;
 };
-/** Maps a tuple schema to a readonly tuple of resolved types. */
+/**
+ * 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.
+ */
 export type TupleTs<T extends Tuple> = {
     readonly [K in keyof T]: Ts<T[K]>;
 };

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

@@ -1,41 +1,103 @@
 /**
- * Runtime validation of unknown values against RTTI schemas.
+ * 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', typedValue]` or `['error', { path, message }]`.
+ * 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 }]`.
  *
- * ## Error path
+ * ## What distinguishes it from `parse`
  *
- * On failure, the error carries a `path` pointing at the offending sub-value:
- * each step is the string property name (for structs/records) or the stringified
- * index (for tuples/arrays). The path is empty when the failure is at the root.
+ * `../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 open
+ *
+ * Openness is the shared rule, not a `parse` detail — see "Structs and tuples
+ * are open" in `../README.md`. `validate` iterates the *schema's* entries, so
+ * an undeclared key or a longer array is never visited: it is accepted, and it
+ * is still there afterwards because the value is returned as-is. An absent
+ * member reads as `undefined`, so a member is required exactly when its set
+ * excludes `undefined`.
+ *
+ * **Do not add a length check for tuples here.** `Ts<readonly [42]>` is the
+ * exact tuple only because TypeScript cannot express the open one (see
+ * `../ts/types.ts` `TupleTs`); reading that rendering as the value model is
+ * what produced #1622, whose check lived in this module's ancestor and was
+ * deleted with it. A schema that wants exact members says so — see
+ * `../todo/close-type.md`.
  *
  * ## 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. `validate` returns the original value on success — no
- * fresh allocation — which is the only behavior that distinguishes it
- * from `parse`.
+ * 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
  *
- * For `array` and `record` schemas, the inner item validator is instantiated lazily —
- * only after confirming the container is non-empty. This prevents infinite recursion
- * when validating recursive schemas like `const list = () => ['array', list]`.
+ * For `array` and `record` schemas, the inner item validator is instantiated
+ * lazily — only after confirming the container is non-empty. 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.
+ * See `./types.ts` for the `Path`/`Result`/`Validate`/`ValidationError`
+ * type-level API.
  *
  * @module
  *
  * @import { Unknown } from '../ts/types.ts'
  * @import { Info1, Struct, Tag1, Tuple, Type } from '../types.ts'
- * @import { StringMap } from '../../object/types.ts'
- * @import { Container, IsContainer, Validate, ValidateE, Visitor } from '../common/types.ts'
+ * @import { Container, IsContainer, Validate, Visitor } from '../common/types.ts'
  */
 import type { Type } from '../types.ts';
 import type { Validate } from '../common/types.ts';
-export { constPrimitiveValidate, prependPath, primitive0Validate, verror, } from '../common/module.f.mjs';
-/** @type {<T extends Type>(rtti: T) => Validate<T>} */
+/**
+ * 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' }]
+ *
+ * // open, and the extras are still there afterwards
+ * validate([number, number])([1, 2, 3])    // ['ok', [1, 2, 3]]
+ * validate({ a: number })({ a: 1, b: 2 })  // ['ok', { a: 1, b: 2 }]
+ *
+ * // an absent optional member stays absent
+ * validate({ a: number, b: option(string) })({ a: 1 })  // ['ok', { a: 1 }]
+ * ```
+ *
+ * @type {<T extends Type>(rtti: T) => Validate<T>}
+ */
 export declare const validate: <T extends Type>(rtti: T) => Validate<T>;

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

@@ -1,38 +1,72 @@
 /**
- * Runtime validation of unknown values against RTTI schemas.
+ * 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', typedValue]` or `['error', { path, message }]`.
+ * 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 }]`.
  *
- * ## Error path
+ * ## What distinguishes it from `parse`
  *
- * On failure, the error carries a `path` pointing at the offending sub-value:
- * each step is the string property name (for structs/records) or the stringified
- * index (for tuples/arrays). The path is empty when the failure is at the root.
+ * `../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 open
+ *
+ * Openness is the shared rule, not a `parse` detail — see "Structs and tuples
+ * are open" in `../README.md`. `validate` iterates the *schema's* entries, so
+ * an undeclared key or a longer array is never visited: it is accepted, and it
+ * is still there afterwards because the value is returned as-is. An absent
+ * member reads as `undefined`, so a member is required exactly when its set
+ * excludes `undefined`.
+ *
+ * **Do not add a length check for tuples here.** `Ts<readonly [42]>` is the
+ * exact tuple only because TypeScript cannot express the open one (see
+ * `../ts/types.ts` `TupleTs`); reading that rendering as the value model is
+ * what produced #1622, whose check lived in this module's ancestor and was
+ * deleted with it. A schema that wants exact members says so — see
+ * `../todo/close-type.md`.
  *
  * ## 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. `validate` returns the original value on success — no
- * fresh allocation — which is the only behavior that distinguishes it
- * from `parse`.
+ * 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
  *
- * For `array` and `record` schemas, the inner item validator is instantiated lazily —
- * only after confirming the container is non-empty. This prevents infinite recursion
- * when validating recursive schemas like `const list = () => ['array', list]`.
+ * For `array` and `record` schemas, the inner item validator is instantiated
+ * lazily — only after confirming the container is non-empty. 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.
+ * See `./types.ts` for the `Path`/`Result`/`Validate`/`ValidationError`
+ * type-level API.
  *
  * @module
  *
  * @import { Unknown } from '../ts/types.ts'
  * @import { Info1, Struct, Tag1, Tuple, Type } from '../types.ts'
- * @import { StringMap } from '../../object/types.ts'
- * @import { Container, IsContainer, Validate, ValidateE, Visitor } from '../common/types.ts'
+ * @import { Container, IsContainer, Validate, Visitor } from '../common/types.ts'
  */
 
 import { ok } from '../../result/module.f.mjs'
@@ -47,13 +81,6 @@ import {
     visit,
 } from '../common/module.f.mjs'
 
-export {
-    constPrimitiveValidate,
-    prependPath,
-    primitive0Validate,
-    verror,
-} from '../common/module.f.mjs'
-
 const { entries } = Object
 
 /** `validate` has nothing to collect from a successful entry — only pass/fail matters. */
@@ -77,7 +104,7 @@ const containerValidate =
         }
         const e = entries(value)
         if (e.length === 0) {
-            return ok(value)
+            return /** @type {any} */ (ok(value))
         }
         // Note: we shouldn't instantiate `itemValidate` until we make sure `entries` is not empty.
         //       Otherwise, we can get infinite recursion on empty arrays and objects
@@ -93,9 +120,10 @@ const arrayValidate = containerValidate(isArray)
 const recordValidate = containerValidate(isObject)
 
 /**
- * Builds a validator for `Tuple` or `Struct` const schemas.
- * Iterates over the schema's entries and validates each corresponding
- * element/property of the value.
+ * Builds a validator 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, the value being
+ * returned as it came, it survives.
  */
 const constContainerValidate =
     /**
@@ -105,29 +133,34 @@ const constContainerValidate =
      * @returns {<T extends Tuple | Struct>(rtti: T) => Validate<T>}
      */
     (isContainer, getItem) =>
-    rtti => value => {
-        if (!isContainer(value)) {
-            return verror('unexpected value')
+    rtti => {
+        // Depends on `rtti` alone, so it is computed once per schema rather
+        // than once per validated value.
+        const rttiEntries = entries(rtti)
+        return value => {
+            if (!isContainer(value)) {
+                return verror('unexpected value')
+            }
+            const r = eachEntry(
+                rttiEntries,
+                (k, v) => /** @type {any} */ (validate(v))(getItem(value, k)),
+                undefined,
+                noAccumulate,
+            )
+            // `value` is C (Unknown container), but Ts<T> for T extends Tuple|Struct is not
+            // structurally equivalent to C — TypeScript can't narrow element types through the loop.
+            return r[0] === 'error' ? r : /** @type {any} */ (ok(value))
         }
-        const r = eachEntry(
-            Object.entries(rtti),
-            (k, v) => /** @type {any} */ (validate(v))(getItem(value, k)),
-            undefined,
-            noAccumulate,
-        )
-        // `value` is C (Unknown container), but Ts<T> for T extends Tuple|Struct is not
-        // structurally equivalent to C — TypeScript can't narrow element types through the loop.
-        return r[0] === 'error' ? r : /** @type {any} */ (ok(value))
     }
 
 const tupleValidate = constContainerValidate(
     isArray,
-    (value, k) => value[Number(k)]
+    (value, k) => value[Number(k)],
 )
 
 const structValidate = constContainerValidate(
     isObject,
-    (value, k) => value[k]
+    (value, k) => value[k],
 )
 
 const orValidate =
@@ -137,24 +170,8 @@ const orValidate =
      * @returns {Validate<() => readonly ['or', ...T]>}
      */
     rtti =>
-        /** @type {any} */ (orVisit(/** @type {(t: Type) => ValidateE} */ (/** @type {any} */ (validate)))(rtti))
+        /** @type {any} */ (orVisit(/** @type {any} */ (validate))(rtti))
 
-/**
- * Creates a validator function for the given RTTI schema.
- *
- * @param rtti - A schema `Type`: a `Thunk` for tag-based schemas, or a `Const`
- *   (primitive literal, tuple, or struct) for exact-value schemas.
- * @returns A `Validate<T>` function that checks an unknown value and returns
- *   `['ok', value]` or `['error', { path, message }]`.
- *
- * @example
- * ```js
- * const v = validate(array(number))
- * v([1, 2, 3])         // ['ok', [1, 2, 3]]
- * v([1, 'two'])        // ['error', { path: ['1'], message: 'unexpected value' }]
- * v(['a'])             // ['error', { path: ['0'], message: 'unexpected value' }]
- * ```
- */
 const validateVisitor = /** @type {any} */ ({
     tuple: tupleValidate,
     struct: structValidate,
@@ -166,6 +183,35 @@ const validateVisitor = /** @type {any} */ ({
     unknown: () => ok,
 })
 
-/** @type {<T extends Type>(rtti: T) => Validate<T>} */
+/**
+ * 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' }]
+ *
+ * // open, and the extras are still there afterwards
+ * validate([number, number])([1, 2, 3])    // ['ok', [1, 2, 3]]
+ * validate({ a: number })({ a: 1, b: 2 })  // ['ok', { a: 1, b: 2 }]
+ *
+ * // an absent optional member stays absent
+ * validate({ a: number, b: option(string) })({ a: 1 })  // ['ok', { a: 1 }]
+ * ```
+ *
+ * @type {<T extends Type>(rtti: T) => Validate<T>}
+ */
 export const validate = rtti =>
-    /** @type {any} */ (visit(validateVisitor)(rtti))
+    (visit(validateVisitor)(rtti))

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

@@ -1,11 +1,18 @@
 /**
- * @import { ValidationError } from '../common/types.ts'
+ * @import { ValidationError, ValidateE } from '../common/types.ts'
+ * @import { Type } from '../types.ts'
  * @import { Equal } from '../../ts/types.ts'
- * @import { Ts } from '../ts/types.ts'
+ * @import { Ts, Unknown } from '../ts/types.ts'
  * @import { Unknown as DjsUnknown } from '../../../djs/types.ts'
  * @import { Assert } from '../../../asserts/types.ts'
  */
 export declare const proof: {
+    verbatim: {
+        absentOptionalStaysAbsent: () => void;
+        undeclaredMemberSurvives: () => void;
+        referenceIdentity: () => void;
+    };
+    sameAcceptanceAsParse: () => void;
     boolean: {
         ok: () => void;
         error: () => void;
@@ -64,12 +71,13 @@ export declare const proof: {
         };
         tuple: {
             ok: () => void;
-            extraItems: () => void;
+            extraItemsAcceptedAndKept: () => void;
+            shortArrayKeepsItsLength: () => void;
+            empty: () => void;
             error: () => void;
         };
         struct: {
             ok: () => void;
-            extraKeys: () => void;
             error: () => void;
         };
     };
@@ -96,10 +104,7 @@ export declare const proof: {
             ok: () => void;
             error: () => void;
         };
-        mixed: {
-            ok: () => void;
-            error: () => void;
-        };
+        firstMatchWins: () => void;
     };
     option: {
         ok: () => void;
@@ -120,6 +125,4 @@ export declare const proof: {
         arrayOfArrays: () => void;
         recordOfRecords: () => void;
     };
-    funcParam: () => () => void;
-    funcObj: () => () => void;
 };