functionalscript 0.24.0 → 0.25.0

package/fs/json/schema/module.f.js

@@ -0,0 +1,112 @@
+/**
+ * Converts an rtti schema to a JSON Schema (draft 2020-12) object.
+ *
+ * Mirrors the visitor structure of `fs/types/rtti/ts/module.f.ts` (`printer` / `toTs`),
+ * but emits a JSON Schema object instead of a TypeScript type string.
+ *
+ * @module
+ */
+import { array, option, or, record, string } from "../../types/rtti/module.f.js";
+import { unknown as jsonUnknown } from "../module.f.js";
+const unknownThunk = () => ['const', unknownConst];
+/** rtti schema for a JSON Schema (draft 2020-12) document. */
+export const unknown = unknownThunk;
+const unknownConst = {
+    type: or('boolean', 'number', 'string', 'integer', 'array', 'object', undefined),
+    const: option(jsonUnknown),
+    not: option(unknown),
+    anyOf: option(array(unknown)),
+    items: or(unknown, false, undefined),
+    prefixItems: option(array(unknown)),
+    properties: option(record(unknown)),
+    required: option(array(string)),
+    additionalProperties: option(unknown),
+};
+/** Returns true if the rtti schema admits the value `undefined`. */
+const admitsUndefined = (rtti) => {
+    if (rtti === undefined) {
+        return true;
+    }
+    if (typeof rtti !== 'function') {
+        return false;
+    }
+    const [t, ...r] = rtti();
+    return t === 'or' ? r.some(admitsUndefined) : false;
+};
+/** Returns the schema with `undefined` removed from any top-level `or`. */
+const stripUndefined = (rtti) => {
+    if (typeof rtti !== 'function') {
+        return rtti;
+    }
+    const [t, ...r] = rtti();
+    if (t !== 'or') {
+        return rtti;
+    }
+    const rest = r.flatMap(t => t !== undefined ? [t] : []);
+    return rest.length === 1 ? rest[0] : or(...rest);
+};
+const constToJsonSchema = (rtti) => {
+    if (typeof rtti === 'undefined') {
+        return { not: {} };
+    }
+    if (typeof rtti !== 'object' || rtti === null) {
+        // bigint consts are represented as numbers (lossy for |value| > MAX_SAFE_INTEGER)
+        return { const: typeof rtti === 'bigint' ? Number(rtti) : rtti };
+    }
+    if (rtti instanceof Array) {
+        return {
+            type: 'array',
+            prefixItems: rtti.map(toJsonSchema),
+            items: false,
+        };
+    }
+    // Struct: keys not admitting undefined go into `required`; optional keys have
+    // undefined stripped from their property schema. additionalProperties is omitted
+    // (lenient), matching rtti's open-struct validation semantics.
+    const ents = Object.entries(rtti);
+    const properties = Object.fromEntries(ents.map(([k, v]) => [k, toJsonSchema(stripUndefined(v))]));
+    const required = ents
+        .filter(([, v]) => !admitsUndefined(v))
+        .map(([k]) => k);
+    return {
+        type: 'object',
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+    };
+};
+/**
+ * Converts an rtti `Type` to a JSON Schema (draft 2020-12) object.
+ *
+ * | rtti                                          | JSON Schema                                                                         |
+ * |-----------------------------------------------|-------------------------------------------------------------------------------------|
+ * | `boolean` / `number` / `string`               | `{ "type": "..." }`                                                                 |
+ * | `bigint`                                      | `{ "type": "integer" }` (lossy; JSON integers are IEEE-754 doubles)                 |
+ * | `unknown`                                     | `{}` (always-true schema)                                                           |
+ * | primitive const (`42`, `'x'`, `true`, `null`) | `{ "const": <value> }`                                                              |
+ * | `bigint` const                                | `{ "const": Number(value) }` (lossy for \|value\| > MAX_SAFE_INTEGER)               |
+ * | `undefined` const                             | `{ "not": {} }` (no JSON value satisfies this)                                      |
+ * | struct `{ a: T, … }`                          | `{ "type": "object", "properties": { "a": …T… }, "required": [non-optional keys] }` |
+ * | tuple `[A, B]`                                | `{ "type": "array", "prefixItems": […A…, …B…], "items": false }`                    |
+ * | `array(T)`                                    | `{ "type": "array", "items": …T… }`                                                 |
+ * | `record(T)`                                   | `{ "type": "object", "additionalProperties": …T… }`                                 |
+ * | `or(...types)`                                | `{ "anyOf": […each…] }`                                                             |
+ */
+export const toJsonSchema = (rtti) => {
+    if (typeof rtti !== 'function') {
+        return constToJsonSchema(rtti);
+    }
+    const [tag, ...rest] = rtti();
+    switch (tag) {
+        case 'const': return constToJsonSchema(rest[0]);
+        case 'boolean': return { type: 'boolean' };
+        case 'number': return { type: 'number' };
+        case 'string': return { type: 'string' };
+        // bigint is not representable in JSON Schema; 'integer' is the closest approximation
+        case 'bigint': return { type: 'integer' };
+        case 'unknown': return {};
+        case 'array': return { type: 'array', items: toJsonSchema(rest[0]) };
+        case 'record': return { type: 'object', additionalProperties: toJsonSchema(rest[0]) };
+        case 'or': return { anyOf: rest.map(toJsonSchema) };
+        default: return {};
+    }
+};

package/fs/json/schema/proof.f.d.ts

@@ -0,0 +1,33 @@
+export declare const proof: {
+    tag0: {
+        boolean: () => void;
+        number: () => void;
+        string: () => void;
+        bigint: () => void;
+        unknown: () => void;
+    };
+    const: {
+        null: () => void;
+        true: () => void;
+        false: () => void;
+        number: () => void;
+        string: () => void;
+        undefined: () => void;
+        bigint: () => void;
+    };
+    array: () => void;
+    record: () => void;
+    or: () => void;
+    tuple: () => void;
+    struct: {
+        allRequired: () => void;
+        withOptional: () => void;
+        allOptional: () => void;
+        empty: () => void;
+    };
+    nested: {
+        arrayOfRecords: () => void;
+        orWithConst: () => void;
+        structWithOr: () => void;
+    };
+};

package/fs/json/schema/proof.f.js

@@ -0,0 +1,71 @@
+import { boolean, number, string, bigint, unknown, array, record, or, option } from "../../types/rtti/module.f.js";
+import { stringify } from "../module.f.js";
+import { toJsonSchema } from "./module.f.js";
+const serialize = (v) => stringify(e => e)(v);
+const eq = (rtti, expected) => () => {
+    const result = serialize(toJsonSchema(rtti));
+    const exp = serialize(expected);
+    if (result !== exp) {
+        throw [result, exp];
+    }
+};
+export const proof = {
+    tag0: {
+        boolean: eq(boolean, { type: 'boolean' }),
+        number: eq(number, { type: 'number' }),
+        string: eq(string, { type: 'string' }),
+        bigint: eq(bigint, { type: 'integer' }),
+        unknown: eq(unknown, {}),
+    },
+    const: {
+        null: eq(null, { const: null }),
+        true: eq(true, { const: true }),
+        false: eq(false, { const: false }),
+        number: eq(42, { const: 42 }),
+        string: eq('hello', { const: 'hello' }),
+        undefined: eq(undefined, { not: {} }),
+        bigint: eq(7n, { const: 7 }),
+    },
+    array: eq(array(number), { type: 'array', items: { type: 'number' } }),
+    record: eq(record(string), { type: 'object', additionalProperties: { type: 'string' } }),
+    or: eq(or(string, number), { anyOf: [{ type: 'string' }, { type: 'number' }] }),
+    tuple: eq([number, string], {
+        type: 'array',
+        prefixItems: [{ type: 'number' }, { type: 'string' }],
+        items: false,
+    }),
+    struct: {
+        allRequired: eq({ x: number, y: string }, {
+            type: 'object',
+            properties: { x: { type: 'number' }, y: { type: 'string' } },
+            required: ['x', 'y'],
+        }),
+        withOptional: eq({ x: number, y: option(string) }, {
+            type: 'object',
+            properties: { x: { type: 'number' }, y: { type: 'string' } },
+            required: ['x'],
+        }),
+        allOptional: eq({ x: option(number) }, {
+            type: 'object',
+            properties: { x: { type: 'number' } },
+        }),
+        empty: eq({}, { type: 'object', properties: {} }),
+    },
+    nested: {
+        arrayOfRecords: eq(array(record(boolean)), {
+            type: 'array',
+            items: { type: 'object', additionalProperties: { type: 'boolean' } },
+        }),
+        orWithConst: eq(or(null, string, 42), {
+            anyOf: [{ const: null }, { type: 'string' }, { const: 42 }],
+        }),
+        structWithOr: eq({ id: or(string, number), name: option(string) }, {
+            type: 'object',
+            properties: {
+                id: { anyOf: [{ type: 'string' }, { type: 'number' }] },
+                name: { type: 'string' },
+            },
+            required: ['id'],
+        }),
+    },
+};

package/fs/mcp/module.f.d.ts

@@ -0,0 +1,88 @@
+import { type Unknown } from '../json/module.f.ts';
+import type { Ts } from '../types/rtti/ts/module.f.ts';
+import type { Operation, Effect } from '../effects/module.f.ts';
+import type { Response } from '../json/rpc/module.f.ts';
+/** Name + version pair sent in `initialize` requests and responses. */
+export declare const implementation: {
+    readonly name: import("../types/rtti/module.f.ts").String;
+    readonly version: import("../types/rtti/module.f.ts").String;
+};
+export type Implementation = Ts<typeof implementation>;
+/** Server capabilities advertised in the `initialize` response. */
+export declare const serverCapabilities: {
+    readonly tools: import("../types/rtti/module.f.ts").Or<readonly [{
+        readonly listChanged: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").Boolean, undefined]>;
+    }, undefined]>;
+};
+export type ServerCapabilities = Ts<typeof serverCapabilities>;
+/** Params for the `initialize` request. */
+export declare const initializeParams: {
+    readonly protocolVersion: import("../types/rtti/module.f.ts").String;
+    readonly capabilities: () => readonly ["or", import("../types/rtti/module.f.ts").Or<[null, import("../types/rtti/module.f.ts").Boolean, import("../types/rtti/module.f.ts").Number, import("../types/rtti/module.f.ts").String]>, import("../types/rtti/module.f.ts").Type1<"record", /*elided*/ any>, import("../types/rtti/module.f.ts").Type1<"array", /*elided*/ any>];
+    readonly clientInfo: {
+        readonly name: import("../types/rtti/module.f.ts").String;
+        readonly version: import("../types/rtti/module.f.ts").String;
+    };
+};
+export type InitializeParams = Ts<typeof initializeParams>;
+/** Result for the `initialize` request. */
+export declare const initializeResult: {
+    readonly protocolVersion: import("../types/rtti/module.f.ts").String;
+    readonly capabilities: {
+        readonly tools: import("../types/rtti/module.f.ts").Or<readonly [{
+            readonly listChanged: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").Boolean, undefined]>;
+        }, undefined]>;
+    };
+    readonly serverInfo: {
+        readonly name: import("../types/rtti/module.f.ts").String;
+        readonly version: import("../types/rtti/module.f.ts").String;
+    };
+    readonly instructions: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
+};
+export type InitializeResult = Ts<typeof initializeResult>;
+/** Plain-text content item returned by a tool call. */
+export declare const textContent: {
+    readonly type: "text";
+    readonly text: import("../types/rtti/module.f.ts").String;
+};
+export type TextContent = Ts<typeof textContent>;
+/**
+ * A tool descriptor returned by `tools/list`.
+ * `inputSchema` is a JSON Schema object — use `toJsonSchema` to derive it from
+ * an rtti schema.
+ */
+export declare const tool: {
+    readonly name: import("../types/rtti/module.f.ts").String;
+    readonly description: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
+    readonly inputSchema: () => readonly ["or", import("../types/rtti/module.f.ts").Or<[null, import("../types/rtti/module.f.ts").Boolean, import("../types/rtti/module.f.ts").Number, import("../types/rtti/module.f.ts").String]>, import("../types/rtti/module.f.ts").Type1<"record", /*elided*/ any>, import("../types/rtti/module.f.ts").Type1<"array", /*elided*/ any>];
+};
+export type Tool = Ts<typeof tool>;
+export declare const toolsListResult: {
+    readonly tools: import("../types/rtti/module.f.ts").Type1<"array", {
+        readonly name: import("../types/rtti/module.f.ts").String;
+        readonly description: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
+        readonly inputSchema: () => readonly ["or", import("../types/rtti/module.f.ts").Or<[null, import("../types/rtti/module.f.ts").Boolean, import("../types/rtti/module.f.ts").Number, import("../types/rtti/module.f.ts").String]>, import("../types/rtti/module.f.ts").Type1<"record", /*elided*/ any>, import("../types/rtti/module.f.ts").Type1<"array", /*elided*/ any>];
+    }>;
+    readonly nextCursor: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
+};
+export type ToolsListResult = Ts<typeof toolsListResult>;
+export declare const toolsCallParams: {
+    readonly name: import("../types/rtti/module.f.ts").String;
+    readonly arguments: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").Type1<"record", () => readonly ["or", import("../types/rtti/module.f.ts").Or<[null, import("../types/rtti/module.f.ts").Boolean, import("../types/rtti/module.f.ts").Number, import("../types/rtti/module.f.ts").String]>, import("../types/rtti/module.f.ts").Type1<"record", /*elided*/ any>, import("../types/rtti/module.f.ts").Type1<"array", /*elided*/ any>]>, undefined]>;
+};
+export type ToolsCallParams = Ts<typeof toolsCallParams>;
+export declare const toolsCallResult: {
+    readonly content: import("../types/rtti/module.f.ts").Type1<"array", {
+        readonly type: "text";
+        readonly text: import("../types/rtti/module.f.ts").String;
+    }>;
+    readonly isError: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").Boolean, undefined]>;
+};
+export type ToolsCallResult = Ts<typeof toolsCallResult>;
+/** Per-method handlers for a hello-world MCP tool server. */
+export type McpHandlers<O extends Operation> = {
+    readonly toolsList: () => Effect<O, ToolsListResult>;
+    readonly toolsCall: (params: ToolsCallParams) => Effect<O, ToolsCallResult>;
+};
+/** Top-level handler: maps a raw JSON value to a JSON-RPC response (or `null` for notifications). */
+export type Handle<O extends Operation> = (value: Unknown) => Effect<O, Response | null>;

package/fs/mcp/module.f.js

@@ -0,0 +1,69 @@
+/**
+ * MCP (Model Context Protocol) message schemas — minimal subset for a
+ * hello-world tool server.
+ *
+ * Covers the three exchanges a minimal server must handle:
+ * - `initialize` / `notifications/initialized` lifecycle
+ * - `tools/list` — advertise available tools
+ * - `tools/call` — invoke a tool and return text content
+ *
+ * Each schema is both a runtime decoder (`validate(schema)`) and a static
+ * TypeScript type (`Ts<typeof schema>`). Transport framing (stdio) and the
+ * JSON-RPC dispatcher are in `fs/json/rpc/module.f.ts`.
+ *
+ * @module
+ */
+import { boolean, string, option, array, record } from "../types/rtti/module.f.js";
+import { unknown } from "../json/module.f.js";
+// ── Shared ─────────────────────────────────────────────────────────────────────
+/** Name + version pair sent in `initialize` requests and responses. */
+export const implementation = {
+    name: string,
+    version: string,
+};
+// ── Capabilities ───────────────────────────────────────────────────────────────
+const toolsCapability = { listChanged: option(boolean) };
+/** Server capabilities advertised in the `initialize` response. */
+export const serverCapabilities = {
+    tools: option(toolsCapability),
+};
+// ── Lifecycle ──────────────────────────────────────────────────────────────────
+/** Params for the `initialize` request. */
+export const initializeParams = {
+    protocolVersion: string,
+    capabilities: unknown,
+    clientInfo: implementation,
+};
+/** Result for the `initialize` request. */
+export const initializeResult = {
+    protocolVersion: string,
+    capabilities: serverCapabilities,
+    serverInfo: implementation,
+    instructions: option(string),
+};
+// ── Content ────────────────────────────────────────────────────────────────────
+/** Plain-text content item returned by a tool call. */
+export const textContent = { type: 'text', text: string };
+// ── Tools ──────────────────────────────────────────────────────────────────────
+/**
+ * A tool descriptor returned by `tools/list`.
+ * `inputSchema` is a JSON Schema object — use `toJsonSchema` to derive it from
+ * an rtti schema.
+ */
+export const tool = {
+    name: string,
+    description: option(string),
+    inputSchema: unknown,
+};
+export const toolsListResult = {
+    tools: array(tool),
+    nextCursor: option(string),
+};
+export const toolsCallParams = {
+    name: string,
+    arguments: option(record(unknown)),
+};
+export const toolsCallResult = {
+    content: array(textContent),
+    isError: option(boolean),
+};

package/fs/sul/level/literal/proof.f.d.ts

@@ -7,5 +7,6 @@ export declare const proof: {
         level2: () => void;
         level3: () => void;
     };
+    wordToString: () => void;
     pipeline: () => void;
 };

package/fs/sul/level/literal/proof.f.js

@@ -686,6 +686,12 @@ export const proof = {
             w(0x10000000000000000000000000000000000n, vec(0x008n)(255n));
         }
     },
+    wordToString: () => {
+        const result = wordToString([0n, 1n, 0xabn]);
+        if (result !== '0,1,ab') {
+            throw result;
+        }
+    },
     pipeline: () => {
         // 4 L1 [0,0] words → 2 L2 [0,0] words → L3 [0,0] word → symbol 0
         // First 7 zero bits accumulate without emitting

package/fs/types/array/module.f.d.ts

@@ -7,6 +7,13 @@ export declare const isArray: (value: unknown) => value is readonly unknown[];
 export type Array1<T> = readonly [T];
 export type Index1 = 0;
 export type Array2<T> = readonly [T, T];
+/**
+ * Currently, TypeScript can't narrow the type of `readonly T[]` to `Array2<T>`
+ * only by checking `a.length === 2`, so we need a user-defined type guard.
+ *
+ * @param a An array of unknown length.
+ * @returns True if `a` has length 2, and `a` is narrowed to `Array2<T>` in that case.
+ */
 export declare const isArray2: <T>(a: readonly T[]) => a is Array2<T>;
 export type Tuple2<T0, T1> = readonly [T0, T1];
 export type Index2 = 0 | 1;

package/fs/types/array/module.f.js

@@ -5,6 +5,13 @@
  */
 import { fromUndefined, map } from "../nullable/module.f.js";
 export const isArray = (value) => value instanceof Array;
+/**
+ * Currently, TypeScript can't narrow the type of `readonly T[]` to `Array2<T>`
+ * only by checking `a.length === 2`, so we need a user-defined type guard.
+ *
+ * @param a An array of unknown length.
+ * @returns True if `a` has length 2, and `a` is narrowed to `Array2<T>` in that case.
+ */
 export const isArray2 = (a) => a.length === 2;
 const uncheckTail = (a) => a.slice(1);
 const uncheckHead = (a) => a.slice(0, -1);

package/fs/types/prime_field/module.f.d.ts

@@ -24,6 +24,10 @@ export type PrimeField = {
     readonly pow: Reduce;
     readonly pow2: Unary;
     readonly pow3: Unary;
+    /** Reduces an arbitrary `bigint` into `[0, p)`. */
+    readonly reduce: Unary;
+    /** Euler criterion: `true` when `x` is a quadratic residue mod `p`. */
+    readonly quadRes: (x: bigint) => boolean;
 };
 /**
  * Creates a prime field with the specified prime modulus and associated operations.
@@ -46,3 +50,7 @@ export declare const prime_field: (p: bigint) => PrimeField;
  * ```
  */
 export declare const sqrt: ({ p, pow, pow2 }: PrimeField) => (a: bigint) => bigint | null;
+/**
+ * Modular square root mod `p` (`p ≡ 3 (mod 4)`); uses {@link PrimeField.neg} when `x` is not a residue.
+ */
+export declare const modSqrt: (field: PrimeField) => Unary;

package/fs/types/prime_field/module.f.js

@@ -1,4 +1,5 @@
 import { repeat } from "../monoid/module.f.js";
+import { assert } from "../../asserts/module.f.js";
 /**
  * Creates a prime field with the specified prime modulus and associated operations.
  *
@@ -33,23 +34,32 @@ export const prime_field = (p) => {
     const middle = p >> 1n;
     const pow2 = a => mul(a)(a);
     const pow = repeat({ identity: 1n, operation: mul });
+    const add = a => b => {
+        const r = a + b;
+        return r < p ? r : r - p;
+    };
+    const reduce = x => {
+        const r = x % p;
+        return r < 0n ? add(p)(r) : r;
+    };
+    const half = (p - 1n) / 2n;
+    const quadRes = (x) => pow(half)(reduce(x)) === 1n;
     return {
         p,
         middle,
         max: p - 1n,
         neg: a => a === 0n ? 0n : p - a,
         sub,
-        add: a => b => {
-            const r = a + b;
-            return r < p ? r : r - p;
-        },
+        add,
         abs: a => middle < a ? p - a : a,
         mul,
         reciprocal,
         div: a => b => mul(a)(reciprocal(b)),
         pow,
         pow2,
-        pow3: a => mul(a)(pow2(a))
+        pow3: a => mul(a)(pow2(a)),
+        reduce,
+        quadRes,
     };
 };
 /**
@@ -76,3 +86,25 @@ export const sqrt = ({ p, pow, pow2 }) => {
         return pow2(result) === a ? result : null;
     };
 };
+/**
+ * Modular square root mod `p` (`p ≡ 3 (mod 4)`); uses {@link PrimeField.neg} when `x` is not a residue.
+ */
+export const modSqrt = (field) => {
+    const { neg, reduce } = field;
+    const sqrt_p = sqrt(field);
+    return x => {
+        const v = reduce(x);
+        const r = sqrt_p(v);
+        if (r !== null) {
+            return r;
+        }
+        // For a prime `p ≡ 3 (mod 4)`, `−1` is a non-residue, so exactly one of
+        // `±v` is a quadratic residue: if `v` has no root, `neg(v)` must — hence
+        // `s` is non-null. `sqrt` already enforces `p ≡ 3 (mod 4)`, but primality
+        // is never checked, so the only way to reach `s === null` is a *composite*
+        // modulus (where the residue argument breaks).
+        const s = sqrt_p(neg(v));
+        assert(s !== null, 'modSqrt');
+        return s;
+    };
+};

package/fs/types/prime_field/proof.f.d.ts

@@ -8,5 +8,8 @@ export declare const proof: {
         pow: () => void;
         sqrtExample: () => void;
         sqrt: () => void;
+        reduce: () => void;
+        quadRes: () => void;
+        modSqrt: () => void;
     };
 };

package/fs/types/prime_field/proof.f.js

@@ -1,4 +1,4 @@
-import { prime_field, sqrt } from "./module.f.js";
+import { modSqrt, prime_field, sqrt } from "./module.f.js";
 export const proof = {
     prime_field_test: () => {
         const p = 0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2fn;
@@ -143,7 +143,32 @@ export const proof = {
                 }
                 test(f.middle);
                 test(f.max);
-            }
+            },
+            reduce: () => {
+                if (f.reduce(13n) !== 13n) {
+                    throw f.reduce(13n);
+                }
+                if (f.reduce(-1n) !== p - 1n) {
+                    throw [f.reduce(-1n), p - 1n];
+                }
+            },
+            quadRes: () => {
+                if (!f.quadRes(1n)) {
+                    throw 1n;
+                }
+                if (f.quadRes(3n)) {
+                    throw 3n;
+                }
+            },
+            modSqrt: () => {
+                const root = modSqrt(f);
+                if (root(4n) !== 2n) {
+                    throw root(4n);
+                }
+                if (f.pow2(root(2n)) !== 2n) {
+                    throw root(2n);
+                }
+            },
         };
     }
 };

package/fs/types/rtti/parse/module.f.d.ts

@@ -1,3 +1,31 @@
+/**
+ * Runtime deserialization of unknown values against RTTI schemas.
+ *
+ * The main entry point is `parse(rtti)`, which takes a schema `Type` and returns
+ * 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.
+ * - 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.
+ *
+ * The error shape, path bookkeeping, primitive checks, and schema
+ * recognition (`visit`) are shared with `validate` through
+ * `../common/module.f.ts`; only container construction differs.
+ *
+ * @module
+ */
 import { type Type } from '../module.f.ts';
 import { type Result as CommonValidateResult, type Validate } from '../common/module.f.ts';
 export { type Path, type ValidationError } from '../common/module.f.ts';

package/fs/types/rtti/parse/module.f.js

@@ -1,3 +1,31 @@
+/**
+ * Runtime deserialization of unknown values against RTTI schemas.
+ *
+ * The main entry point is `parse(rtti)`, which takes a schema `Type` and returns
+ * 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.
+ * - 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.
+ *
+ * The error shape, path bookkeeping, primitive checks, and schema
+ * recognition (`visit`) are shared with `validate` through
+ * `../common/module.f.ts`; only container construction differs.
+ *
+ * @module
+ */
 import {} from "../module.f.js";
 import { ok } from "../../result/module.f.js";
 import {} from "../../object/module.f.js";
@@ -31,9 +59,9 @@ const containerParse = (isContainer, rebuild) => (item) => value => {
     const itemParse = parse(item);
     const results = e.map(([k, v]) => [k, itemParse(v)]);
     const err = keyedFirstError(results);
-    return (err === null
+    return err === null
         ? ok(rebuild(okEntries(results)))
-        : prependPath(err[0], err[1]));
+        : prependPath(err[0], err[1]);
 };
 const arrayParse = containerParse(isArray, arrayRebuild);
 const recordParse = containerParse(isObject, recordRebuild);
@@ -49,14 +77,16 @@ const constContainerParse = (isContainer, getItem, rebuild) => (rtti) => value =
     }
     const results = entries(rtti).map(([k, t]) => [k, parse(t)(getItem(value, k))]);
     const err = keyedFirstError(results);
-    return (err === null
+    return err === null
         ? ok(rebuild(okEntries(results)))
-        : prependPath(err[0], err[1]));
+        : prependPath(err[0], err[1]);
 };
 const tupleParse = constContainerParse(isArray, (value, k) => value[Number(k)], arrayRebuild);
 const structParse = constContainerParse(isObject, (value, k) => value[k], recordRebuild);
 const findFirst = find(verror('no match'))((k) => k[0] === 'ok');
-const orParse = (rtti) => value => findFirst(listMap(t => parse(t)(value))(rtti));
+const orParse = (rtti) => 
+// `parse(t)` where t: Type forces Ts<Type> evaluation → TS2589; cast keeps result as any.
+value => findFirst(listMap(t => parse(t)(value))(rtti));
 /**
  * Creates a parser function for the given RTTI schema.
  *