functionalscript 0.24.0 → 0.26.0

package/fs/json/rpc/module.f.d.ts

@@ -0,0 +1,109 @@
+import type { Ts } from '../../types/rtti/ts/module.f.ts';
+import type { Result } from '../../types/result/module.f.ts';
+import { type Unknown } from '../module.f.ts';
+/** Request/response identifier: a string, a number, or `null`. */
+declare const id: import("../../types/rtti/module.f.ts").Or<[import("../../types/rtti/module.f.ts").String, import("../../types/rtti/module.f.ts").Number, null]>;
+/**
+ * A request or notification envelope. `id` present → request (a response is
+ * expected); `id` absent → notification (no response). `params` is optional.
+ */
+export declare const request: {
+    readonly jsonrpc: "2.0";
+    readonly method: import("../../types/rtti/module.f.ts").String;
+    readonly params: import("../../types/rtti/module.f.ts").Or<readonly [() => 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]>;
+    readonly id: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Or<[import("../../types/rtti/module.f.ts").String, import("../../types/rtti/module.f.ts").Number, null]>, undefined]>;
+};
+/** The JSON-RPC error object. */
+export declare const error: {
+    readonly code: import("../../types/rtti/module.f.ts").Number;
+    readonly message: import("../../types/rtti/module.f.ts").String;
+    readonly data: import("../../types/rtti/module.f.ts").Or<readonly [() => 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 Id = Ts<typeof id>;
+export type Request = Ts<typeof request>;
+export type RpcError = Ts<typeof error>;
+export declare const successResponse: {
+    readonly jsonrpc: "2.0";
+    readonly result: () => 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 id: import("../../types/rtti/module.f.ts").Or<[import("../../types/rtti/module.f.ts").String, import("../../types/rtti/module.f.ts").Number, null]>;
+};
+export declare const errorResponse: {
+    readonly jsonrpc: "2.0";
+    readonly error: {
+        readonly code: import("../../types/rtti/module.f.ts").Number;
+        readonly message: import("../../types/rtti/module.f.ts").String;
+        readonly data: import("../../types/rtti/module.f.ts").Or<readonly [() => 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]>;
+    };
+    readonly id: import("../../types/rtti/module.f.ts").Or<[import("../../types/rtti/module.f.ts").String, import("../../types/rtti/module.f.ts").Number, null]>;
+};
+/**
+ * A response envelope: either a success (`result`) or an error (`error`).
+ * Derived from the rtti schema via `Ts<>` — the same declaration is the
+ * runtime decoder and the static type, with no drift. rtti structs are open
+ * (extra keys allowed), so "result XOR error" is not enforced at runtime; in
+ * practice the dispatcher only ever constructs one or the other.
+ */
+export declare const response: import("../../types/rtti/module.f.ts").Or<[{
+    readonly jsonrpc: "2.0";
+    readonly result: () => 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 id: import("../../types/rtti/module.f.ts").Or<[import("../../types/rtti/module.f.ts").String, import("../../types/rtti/module.f.ts").Number, null]>;
+}, {
+    readonly jsonrpc: "2.0";
+    readonly error: {
+        readonly code: import("../../types/rtti/module.f.ts").Number;
+        readonly message: import("../../types/rtti/module.f.ts").String;
+        readonly data: import("../../types/rtti/module.f.ts").Or<readonly [() => 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]>;
+    };
+    readonly id: import("../../types/rtti/module.f.ts").Or<[import("../../types/rtti/module.f.ts").String, import("../../types/rtti/module.f.ts").Number, null]>;
+}]>;
+export type Response = Ts<typeof response>;
+/** Decodes an untrusted value as a JSON-RPC request / notification. */
+export declare const decodeRequest: import("../../types/rtti/common/module.f.ts").Validate<{
+    readonly jsonrpc: "2.0";
+    readonly method: import("../../types/rtti/module.f.ts").String;
+    readonly params: import("../../types/rtti/module.f.ts").Or<readonly [() => 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]>;
+    readonly id: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Or<[import("../../types/rtti/module.f.ts").String, import("../../types/rtti/module.f.ts").Number, null]>, undefined]>;
+}>;
+/** A method implementation: maps `params` to a result or an `RpcError`. */
+export type Handler = (params: Unknown | undefined) => Result<Unknown, RpcError>;
+/** A `method` name → `Handler` map. */
+export type Handlers = {
+    readonly [method: string]: Handler;
+};
+/** Builds an `RpcError` with the given `code` and `message` (no `data`). */
+export declare const rpcError: (code: number) => (message: string) => RpcError;
+export declare const parseError: import("../../types/rtti/ts/module.f.ts").StructTs<{
+    readonly code: import("../../types/rtti/module.f.ts").Number;
+    readonly message: import("../../types/rtti/module.f.ts").String;
+    readonly data: import("../../types/rtti/module.f.ts").Or<readonly [() => 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 declare const invalidRequest: import("../../types/rtti/ts/module.f.ts").StructTs<{
+    readonly code: import("../../types/rtti/module.f.ts").Number;
+    readonly message: import("../../types/rtti/module.f.ts").String;
+    readonly data: import("../../types/rtti/module.f.ts").Or<readonly [() => 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 declare const methodNotFound: import("../../types/rtti/ts/module.f.ts").StructTs<{
+    readonly code: import("../../types/rtti/module.f.ts").Number;
+    readonly message: import("../../types/rtti/module.f.ts").String;
+    readonly data: import("../../types/rtti/module.f.ts").Or<readonly [() => 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 declare const invalidParams: import("../../types/rtti/ts/module.f.ts").StructTs<{
+    readonly code: import("../../types/rtti/module.f.ts").Number;
+    readonly message: import("../../types/rtti/module.f.ts").String;
+    readonly data: import("../../types/rtti/module.f.ts").Or<readonly [() => 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 declare const internalError: import("../../types/rtti/ts/module.f.ts").StructTs<{
+    readonly code: import("../../types/rtti/module.f.ts").Number;
+    readonly message: import("../../types/rtti/module.f.ts").String;
+    readonly data: import("../../types/rtti/module.f.ts").Or<readonly [() => 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]>;
+}>;
+/**
+ * Dispatches an already-parsed JSON-RPC value against `handlers`.
+ *
+ * - invalid envelope → `Invalid Request` (`-32600`) with `id: null`
+ * - notification (no `id`) → `null` (never a response)
+ * - unknown method → `Method not found` (`-32601`)
+ * - otherwise the handler's `ok` / `error` result becomes a success / error response
+ */
+export declare const dispatch: (handlers: Handlers) => (value: Unknown) => Response | null;
+export {};

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

@@ -0,0 +1,84 @@
+/**
+ * JSON-RPC 2.0 envelopes and a pure dispatcher.
+ *
+ * The envelopes are rtti schemas, so one declaration yields both a runtime
+ * decoder (`validate(request)`) and the static type (`Ts<typeof request>`) — no
+ * drift between them. The dispatcher is pure: it maps an already-parsed request
+ * value to a response value (or `null` for a notification) and performs no I/O.
+ *
+ * Out of scope here (follow-ups): transports — stdio / HTTP framing — over
+ * `fs/effects/node`, and concrete method sets such as MCP (i665-mcp), which layer
+ * on top of `dispatch`.
+ *
+ * @module
+ */
+import { number, string, or, option } from "../../types/rtti/module.f.js";
+import { validate } from "../../types/rtti/validate/module.f.js";
+import { unknown } from "../module.f.js";
+const jsonrpc = '2.0';
+/** Request/response identifier: a string, a number, or `null`. */
+const id = or(string, number, null);
+/**
+ * A request or notification envelope. `id` present → request (a response is
+ * expected); `id` absent → notification (no response). `params` is optional.
+ */
+export const request = {
+    jsonrpc,
+    method: string,
+    params: option(unknown),
+    id: option(id),
+};
+/** The JSON-RPC error object. */
+export const error = {
+    code: number,
+    message: string,
+    data: option(unknown),
+};
+export const successResponse = { jsonrpc, result: unknown, id };
+export const errorResponse = { jsonrpc, error, id };
+/**
+ * A response envelope: either a success (`result`) or an error (`error`).
+ * Derived from the rtti schema via `Ts<>` — the same declaration is the
+ * runtime decoder and the static type, with no drift. rtti structs are open
+ * (extra keys allowed), so "result XOR error" is not enforced at runtime; in
+ * practice the dispatcher only ever constructs one or the other.
+ */
+export const response = or(successResponse, errorResponse);
+/** Decodes an untrusted value as a JSON-RPC request / notification. */
+export const decodeRequest = validate(request);
+/** Builds an `RpcError` with the given `code` and `message` (no `data`). */
+export const rpcError = (code) => (message) => ({ code, message });
+// The standard JSON-RPC 2.0 errors.
+export const parseError = rpcError(-32700)('Parse error');
+export const invalidRequest = rpcError(-32600)('Invalid Request');
+export const methodNotFound = rpcError(-32601)('Method not found');
+export const invalidParams = rpcError(-32602)('Invalid params');
+export const internalError = rpcError(-32603)('Internal error');
+const errorResponseOf = (id) => (e) => ({ jsonrpc, error: e, id });
+/**
+ * Dispatches an already-parsed JSON-RPC value against `handlers`.
+ *
+ * - invalid envelope → `Invalid Request` (`-32600`) with `id: null`
+ * - notification (no `id`) → `null` (never a response)
+ * - unknown method → `Method not found` (`-32601`)
+ * - otherwise the handler's `ok` / `error` result becomes a success / error response
+ */
+export const dispatch = (handlers) => (value) => {
+    const decoded = decodeRequest(value);
+    if (decoded[0] === 'error') {
+        return errorResponseOf(null)(invalidRequest);
+    }
+    const message = decoded[1];
+    const id = message.id;
+    if (id === undefined) {
+        return null;
+    }
+    const handler = handlers[message.method];
+    if (handler === undefined) {
+        return errorResponseOf(id)(methodNotFound);
+    }
+    const result = handler(message.params);
+    return result[0] === 'ok'
+        ? { jsonrpc, result: result[1], id }
+        : errorResponseOf(id)(result[1]);
+};

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

@@ -0,0 +1,35 @@
+export declare const proof: {
+    schema: {
+        request: {
+            full: () => void;
+            notification: () => void;
+            nullId: () => void;
+            stringId: () => void;
+            badVersion: () => void;
+            missingMethod: () => void;
+            badId: () => void;
+            notObject: () => void;
+        };
+        error: {
+            ok: () => void;
+            withData: () => void;
+            missingMessage: () => void;
+        };
+    };
+    errors: {
+        factory: () => void;
+        parseError: () => void;
+        invalidRequest: () => void;
+        methodNotFound: () => void;
+        invalidParams: () => void;
+        internalError: () => void;
+    };
+    dispatch: {
+        success: () => void;
+        paramsPassed: () => void;
+        handlerError: () => void;
+        methodNotFound: () => void;
+        invalidRequest: () => void;
+        notification: () => void;
+    };
+};

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

@@ -0,0 +1,68 @@
+import { assert, assertEq } from "../../asserts/module.f.js";
+import { ok, error } from "../../types/result/module.f.js";
+import { validate } from "../../types/rtti/validate/module.f.js";
+import { error as errorSchema, decodeRequest, dispatch, rpcError, parseError, invalidRequest, methodNotFound, invalidParams, internalError, } from "./module.f.js";
+const isOk = (r) => r[0] === 'ok';
+const handlers = {
+    ping: () => ok('pong'),
+    echo: params => ok(params ?? null),
+    boom: () => error(invalidParams),
+};
+const d = dispatch(handlers);
+export const proof = {
+    schema: {
+        request: {
+            full: () => assert(isOk(decodeRequest({ jsonrpc: '2.0', method: 'm', params: [1], id: 1 }))),
+            notification: () => assert(isOk(decodeRequest({ jsonrpc: '2.0', method: 'm' }))),
+            nullId: () => assert(isOk(decodeRequest({ jsonrpc: '2.0', method: 'm', id: null }))),
+            stringId: () => assert(isOk(decodeRequest({ jsonrpc: '2.0', method: 'm', id: 'abc' }))),
+            badVersion: () => assert(!isOk(decodeRequest({ jsonrpc: '1.0', method: 'm', id: 1 }))),
+            missingMethod: () => assert(!isOk(decodeRequest({ jsonrpc: '2.0', id: 1 }))),
+            badId: () => assert(!isOk(decodeRequest({ jsonrpc: '2.0', method: 'm', id: true }))),
+            notObject: () => assert(!isOk(decodeRequest(42))),
+        },
+        error: {
+            ok: () => assert(isOk(validate(errorSchema)({ code: -1, message: 'x' }))),
+            withData: () => assert(isOk(validate(errorSchema)({ code: -1, message: 'x', data: [1, 2] }))),
+            missingMessage: () => assert(!isOk(validate(errorSchema)({ code: -1 }))),
+        },
+    },
+    errors: {
+        factory: () => {
+            const e = rpcError(-7)('boom');
+            assertEq(e.code, -7);
+            assertEq(e.message, 'boom');
+        },
+        parseError: () => { assertEq(parseError.code, -32700); assertEq(parseError.message, 'Parse error'); },
+        invalidRequest: () => { assertEq(invalidRequest.code, -32600); assertEq(invalidRequest.message, 'Invalid Request'); },
+        methodNotFound: () => { assertEq(methodNotFound.code, -32601); assertEq(methodNotFound.message, 'Method not found'); },
+        invalidParams: () => { assertEq(invalidParams.code, -32602); assertEq(invalidParams.message, 'Invalid params'); },
+        internalError: () => { assertEq(internalError.code, -32603); assertEq(internalError.message, 'Internal error'); },
+    },
+    dispatch: {
+        success: () => {
+            const r = d({ jsonrpc: '2.0', method: 'ping', id: 1 });
+            assert(r !== null && 'result' in r && r.result === 'pong' && r.id === 1);
+        },
+        paramsPassed: () => {
+            const r = d({ jsonrpc: '2.0', method: 'echo', params: 'hi', id: 2 });
+            assert(r !== null && 'result' in r && r.result === 'hi');
+        },
+        handlerError: () => {
+            const r = d({ jsonrpc: '2.0', method: 'boom', id: 3 });
+            assert(r !== null && 'error' in r && r.error.code === -32602 && r.id === 3);
+        },
+        methodNotFound: () => {
+            const r = d({ jsonrpc: '2.0', method: 'nope', id: 4 });
+            assert(r !== null && 'error' in r && r.error.code === -32601);
+        },
+        invalidRequest: () => {
+            const r = d({ jsonrpc: '1.0', method: 'ping', id: 5 });
+            assert(r !== null && 'error' in r && r.error.code === -32600 && r.id === null);
+        },
+        notification: () => {
+            const r = d({ jsonrpc: '2.0', method: 'ping' });
+            assertEq(r, null);
+        },
+    },
+};

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

@@ -0,0 +1,76 @@
+/**
+ * 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 { type Type as RttiType } from '../../types/rtti/module.f.ts';
+import type { Ts, WithOut } from '../../types/rtti/ts/module.f.ts';
+declare const unknownThunk: () => readonly ["const", {
+    readonly type: import("../../types/rtti/module.f.ts").Or<["boolean", "number", "string", "integer", "array", "object", undefined]>;
+    readonly const: import("../../types/rtti/module.f.ts").Or<readonly [() => 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]>;
+    readonly not: import("../../types/rtti/module.f.ts").Or<readonly [WithOut<() => readonly ["const", /*elided*/ any], UnknownConst>, undefined]>;
+    readonly anyOf: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"array", WithOut<() => readonly ["const", /*elided*/ any], UnknownConst>>, undefined]>;
+    readonly items: import("../../types/rtti/module.f.ts").Or<[WithOut<() => readonly ["const", /*elided*/ any], UnknownConst>, false, undefined]>;
+    readonly prefixItems: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"array", WithOut<() => readonly ["const", /*elided*/ any], UnknownConst>>, undefined]>;
+    readonly properties: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"record", WithOut<() => readonly ["const", /*elided*/ any], UnknownConst>>, undefined]>;
+    readonly required: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"array", import("../../types/rtti/module.f.ts").String>, undefined]>;
+    readonly additionalProperties: import("../../types/rtti/module.f.ts").Or<readonly [WithOut<() => readonly ["const", /*elided*/ any], UnknownConst>, undefined]>;
+}];
+/** rtti schema for a JSON Schema (draft 2020-12) document. */
+export declare const unknown: WithOut<typeof unknownThunk, UnknownConst>;
+/** A JSON Schema (draft 2020-12) document — the subset of keywords that `toJsonSchema` emits. */
+export type Unknown = Ts<typeof unknown>;
+declare const unknownConst: {
+    readonly type: import("../../types/rtti/module.f.ts").Or<["boolean", "number", "string", "integer", "array", "object", undefined]>;
+    readonly const: import("../../types/rtti/module.f.ts").Or<readonly [() => 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]>;
+    readonly not: import("../../types/rtti/module.f.ts").Or<readonly [WithOut<() => readonly ["const", /*elided*/ any], UnknownConst>, undefined]>;
+    readonly anyOf: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"array", WithOut<() => readonly ["const", /*elided*/ any], UnknownConst>>, undefined]>;
+    readonly items: import("../../types/rtti/module.f.ts").Or<[WithOut<() => readonly ["const", /*elided*/ any], UnknownConst>, false, undefined]>;
+    readonly prefixItems: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"array", WithOut<() => readonly ["const", /*elided*/ any], UnknownConst>>, undefined]>;
+    readonly properties: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"record", WithOut<() => readonly ["const", /*elided*/ any], UnknownConst>>, undefined]>;
+    readonly required: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"array", import("../../types/rtti/module.f.ts").String>, undefined]>;
+    readonly additionalProperties: import("../../types/rtti/module.f.ts").Or<readonly [WithOut<() => readonly ["const", /*elided*/ any], UnknownConst>, undefined]>;
+};
+/**
+ * Hand-written base type used as the `$out` annotation on `unknown`.
+ *
+ * The `?` markers are required even though `Ts<>` already includes `undefined`
+ * in each field type. Without `?`, `Unknown = UnknownConst` would require all
+ * 9 fields to be present in every object literal returned by `toJsonSchema`,
+ * because TypeScript distinguishes "field absent" (`?`) from "field present but
+ * undefined" (`T | undefined`). JSON Schema objects only include the fields
+ * they need, so all fields must be optional.
+ */
+type UnknownConst = {
+    readonly type?: Ts<typeof unknownConst.type>;
+    readonly const?: Ts<typeof unknownConst.const>;
+    readonly not?: Ts<typeof unknownConst.not>;
+    readonly anyOf?: Ts<typeof unknownConst.anyOf>;
+    readonly items?: Ts<typeof unknownConst.items>;
+    readonly prefixItems?: Ts<typeof unknownConst.prefixItems>;
+    readonly properties?: Ts<typeof unknownConst.properties>;
+    readonly required?: Ts<typeof unknownConst.required>;
+    readonly additionalProperties?: Ts<typeof unknownConst.additionalProperties>;
+};
+/**
+ * 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 declare const toJsonSchema: (rtti: RttiType) => Unknown;
+export {};

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'],
+        }),
+    },
+};