functionalscript 0.29.1 → 0.31.0

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

@@ -7,32 +7,33 @@
  * @module
  */
 import { type Type as RttiType } from '../../types/rtti/module.f.ts';
-import type { Ts, WithOut } from '../../types/rtti/ts/module.f.ts';
+import type { Ts } from '../../types/rtti/ts/module.f.ts';
+import type { Phantom } from '../../types/phantom/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 not: import("../../types/rtti/module.f.ts").Or<readonly [Phantom<() => readonly ["const", /*elided*/ any], UnknownConst>, undefined]>;
+    readonly anyOf: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"array", Phantom<() => readonly ["const", /*elided*/ any], UnknownConst>>, undefined]>;
+    readonly items: import("../../types/rtti/module.f.ts").Or<[Phantom<() => 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", Phantom<() => readonly ["const", /*elided*/ any], UnknownConst>>, undefined]>;
+    readonly properties: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"record", Phantom<() => 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]>;
+    readonly additionalProperties: import("../../types/rtti/module.f.ts").Or<readonly [Phantom<() => readonly ["const", /*elided*/ any], UnknownConst>, undefined]>;
 }];
 /** rtti schema for a JSON Schema (draft 2020-12) document. */
-export declare const unknown: WithOut<typeof unknownThunk, UnknownConst>;
+export declare const unknown: Phantom<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 not: import("../../types/rtti/module.f.ts").Or<readonly [Phantom<() => readonly ["const", /*elided*/ any], UnknownConst>, undefined]>;
+    readonly anyOf: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"array", Phantom<() => readonly ["const", /*elided*/ any], UnknownConst>>, undefined]>;
+    readonly items: import("../../types/rtti/module.f.ts").Or<[Phantom<() => 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", Phantom<() => readonly ["const", /*elided*/ any], UnknownConst>>, undefined]>;
+    readonly properties: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Type1<"record", Phantom<() => 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]>;
+    readonly additionalProperties: import("../../types/rtti/module.f.ts").Or<readonly [Phantom<() => readonly ["const", /*elided*/ any], UnknownConst>, undefined]>;
 };
 /**
  * Hand-written base type used as the `$out` annotation on `unknown`.

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

@@ -24,7 +24,10 @@ export declare const proof: {
         withOptional: () => void;
         allOptional: () => void;
         empty: () => void;
+        orOptional: () => void;
+        withConst: () => void;
     };
+    schemaUnknownTag: () => void;
     nested: {
         arrayOfRecords: () => void;
         orWithConst: () => void;

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

@@ -1,6 +1,6 @@
 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";
+import { toJsonSchema, unknown as schemaUnknown } from "./module.f.js";
 const serialize = (v) => stringify(e => e)(v);
 const eq = (rtti, expected) => () => {
     const result = serialize(toJsonSchema(rtti));
@@ -50,6 +50,21 @@ export const proof = {
             properties: { x: { type: 'number' } },
         }),
         empty: eq({}, { type: 'object', properties: {} }),
+        orOptional: eq({ x: or(string, number, undefined) }, {
+            type: 'object',
+            properties: { x: { anyOf: [{ type: 'string' }, { type: 'number' }] } },
+        }),
+        withConst: eq({ x: null, y: string }, {
+            type: 'object',
+            properties: { x: { const: null }, y: { type: 'string' } },
+            required: ['x', 'y'],
+        }),
+    },
+    schemaUnknownTag: () => {
+        const r = schemaUnknown();
+        if (r[0] !== 'const') {
+            throw r[0];
+        }
     },
     nested: {
         arrayOfRecords: eq(array(record(boolean)), {

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

@@ -1,7 +1,8 @@
 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';
+import { type Operation, type Effect } from '../effects/module.f.ts';
+import { type Key, type MemOp } from '../effects/memory/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;
@@ -46,6 +47,45 @@ export declare const textContent: {
     readonly text: import("../types/rtti/module.f.ts").String;
 };
 export type TextContent = Ts<typeof textContent>;
+/**
+ * A binary resource carried inside an {@link embeddedResource}: a base64
+ * `blob`, an addressing `uri`, and an optional `mimeType`. This is MCP's
+ * `BlobResource` shape — the idiomatic way to return typed binary content so a
+ * `mimeType` travels alongside the bytes and clients know how to route them.
+ */
+export declare const blobResource: {
+    readonly uri: import("../types/rtti/module.f.ts").String;
+    readonly mimeType: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
+    readonly blob: import("../types/rtti/module.f.ts").String;
+};
+export type BlobResource = Ts<typeof blobResource>;
+/** An `EmbeddedResource` content item wrapping a {@link blobResource}. */
+export declare const embeddedResource: {
+    readonly type: "resource";
+    readonly resource: {
+        readonly uri: import("../types/rtti/module.f.ts").String;
+        readonly mimeType: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
+        readonly blob: import("../types/rtti/module.f.ts").String;
+    };
+};
+export type EmbeddedResource = Ts<typeof embeddedResource>;
+/**
+ * A single item in a `tools/call` result's `content` array: either plain
+ * {@link textContent} or an {@link embeddedResource} for typed binary. The
+ * `image` and `audio` variants are not modelled yet.
+ */
+export declare const contentItem: import("../types/rtti/module.f.ts").Or<[{
+    readonly type: "text";
+    readonly text: import("../types/rtti/module.f.ts").String;
+}, {
+    readonly type: "resource";
+    readonly resource: {
+        readonly uri: import("../types/rtti/module.f.ts").String;
+        readonly mimeType: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
+        readonly blob: import("../types/rtti/module.f.ts").String;
+    };
+}]>;
+export type ContentItem = Ts<typeof contentItem>;
 /**
  * A tool descriptor returned by `tools/list`.
  * `inputSchema` is a JSON Schema object — use `toJsonSchema` to derive it from
@@ -57,6 +97,14 @@ export declare const tool: {
     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>;
+/**
+ * Params for the `tools/list` request. `cursor` is an opaque pagination token
+ * from a previous `ToolsListResult.nextCursor`.
+ */
+export declare const toolsListParams: {
+    readonly cursor: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
+};
+export type ToolsListParams = Ts<typeof toolsListParams>;
 export declare const toolsListResult: {
     readonly tools: import("../types/rtti/module.f.ts").Type1<"array", {
         readonly name: import("../types/rtti/module.f.ts").String;
@@ -72,17 +120,67 @@ export declare const toolsCallParams: {
 };
 export type ToolsCallParams = Ts<typeof toolsCallParams>;
 export declare const toolsCallResult: {
-    readonly content: import("../types/rtti/module.f.ts").Type1<"array", {
+    readonly content: import("../types/rtti/module.f.ts").Type1<"array", import("../types/rtti/module.f.ts").Or<[{
         readonly type: "text";
         readonly text: import("../types/rtti/module.f.ts").String;
-    }>;
+    }, {
+        readonly type: "resource";
+        readonly resource: {
+            readonly uri: import("../types/rtti/module.f.ts").String;
+            readonly mimeType: import("../types/rtti/module.f.ts").Or<readonly [import("../types/rtti/module.f.ts").String, undefined]>;
+            readonly blob: 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 toolsList: (params: ToolsListParams) => 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>;
+/** MCP error -32002: the client called a method before `initialize`. */
+export declare const notInitialized: 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]>;
+}>;
+/** State carried before the peer sends `initialize`. */
+export type Uninitialized = readonly ['uninitialized'];
+/** State after `initialize` response was sent but before `notifications/initialized` arrives. */
+export type Initializing = readonly ['initializing'];
+/** State carried after a successful `initialize` exchange. */
+export type InitializedState = true;
+/** The three phases of an MCP session. */
+export type McpSessionState = Uninitialized | Initializing | readonly ['initialized', InitializedState];
+/** Initial session state — always start here. */
+export declare const uninitializedState: McpSessionState;
+/** Static configuration supplied by the server implementer. */
+export type McpConfig = {
+    readonly serverInfo: Implementation;
+    readonly capabilities: ServerCapabilities;
+    readonly protocolVersion: string;
+};
+/**
+ * State-machine step for an MCP session using memory effects.
+ *
+ * Given configuration, handlers, and a memory key holding the session state,
+ * returns a function `(value) => Effect<MemOp | O, Response | null>`.
+ *
+ * Rules:
+ * - `ping` returns an empty success regardless of session state; non-object
+ *   params → -32602.
+ * - `initialize` is accepted only while uninitialized; a second call returns -32600.
+ *   On success the state moves to `initializing`, not `initialized`.
+ * - `notifications/initialized` (no `id`) transitions `initializing` → `initialized`;
+ *   a malformed one (non-object params) is ignored and the session stays gated;
+ *   other notifications are silently ignored in any state.
+ * - Any other method before `notifications/initialized` → error -32002 (not initialized).
+ * - Methods gated by a capability (e.g. `tools/list`) → -32601 when the capability
+ *   is absent.
+ * - `tools/list` params (an optional pagination `cursor`) are validated and passed
+ *   to the handler; invalid params → -32602.
+ */
+export declare const mcpStep: <O extends Operation>({ protocolVersion, capabilities, serverInfo, }: McpConfig) => (handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null>;

package/fs/mcp/module.f.js

@@ -13,8 +13,12 @@
  *
  * @module
  */
-import { boolean, string, option, array, record } from "../types/rtti/module.f.js";
+import { boolean, string, option, array, record, or } from "../types/rtti/module.f.js";
 import { unknown } from "../json/module.f.js";
+import { pure } from "../effects/module.f.js";
+import { read, write } from "../effects/memory/module.f.js";
+import { decodeRequest, rpcError, invalidRequest, invalidParams, methodNotFound, jsonrpc, } from "../json/rpc/module.f.js";
+import { validate } from "../types/rtti/validate/module.f.js";
 // ── Shared ─────────────────────────────────────────────────────────────────────
 /** Name + version pair sent in `initialize` requests and responses. */
 export const implementation = {
@@ -44,6 +48,28 @@ export const initializeResult = {
 // ── Content ────────────────────────────────────────────────────────────────────
 /** Plain-text content item returned by a tool call. */
 export const textContent = { type: 'text', text: string };
+/**
+ * A binary resource carried inside an {@link embeddedResource}: a base64
+ * `blob`, an addressing `uri`, and an optional `mimeType`. This is MCP's
+ * `BlobResource` shape — the idiomatic way to return typed binary content so a
+ * `mimeType` travels alongside the bytes and clients know how to route them.
+ */
+export const blobResource = {
+    uri: string,
+    mimeType: option(string),
+    blob: string,
+};
+/** An `EmbeddedResource` content item wrapping a {@link blobResource}. */
+export const embeddedResource = {
+    type: 'resource',
+    resource: blobResource,
+};
+/**
+ * A single item in a `tools/call` result's `content` array: either plain
+ * {@link textContent} or an {@link embeddedResource} for typed binary. The
+ * `image` and `audio` variants are not modelled yet.
+ */
+export const contentItem = or(textContent, embeddedResource);
 // ── Tools ──────────────────────────────────────────────────────────────────────
 /**
  * A tool descriptor returned by `tools/list`.
@@ -55,6 +81,13 @@ export const tool = {
     description: option(string),
     inputSchema: unknown,
 };
+/**
+ * Params for the `tools/list` request. `cursor` is an opaque pagination token
+ * from a previous `ToolsListResult.nextCursor`.
+ */
+export const toolsListParams = {
+    cursor: option(string),
+};
 export const toolsListResult = {
     tools: array(tool),
     nextCursor: option(string),
@@ -64,6 +97,110 @@ export const toolsCallParams = {
     arguments: option(record(unknown)),
 };
 export const toolsCallResult = {
-    content: array(textContent),
+    content: array(contentItem),
     isError: option(boolean),
 };
+// ── Lifecycle / capability state machine ───────────────────────────────────────
+const _errResponse = (id) => (error) => ({ jsonrpc, error, id });
+const _okResponse = (id) => (result) => ({ jsonrpc, result, id });
+/** MCP error -32002: the client called a method before `initialize`. */
+export const notInitialized = rpcError(-32002)('Server not initialized');
+// Params for methods that take no arguments (`ping`, `notifications/initialized`):
+// absent, or an object (which may carry `_meta`).
+const _noParams = option(record(unknown));
+/** Initial session state — always start here. */
+export const uninitializedState = ['uninitialized'];
+/**
+ * State-machine step for an MCP session using memory effects.
+ *
+ * Given configuration, handlers, and a memory key holding the session state,
+ * returns a function `(value) => Effect<MemOp | O, Response | null>`.
+ *
+ * Rules:
+ * - `ping` returns an empty success regardless of session state; non-object
+ *   params → -32602.
+ * - `initialize` is accepted only while uninitialized; a second call returns -32600.
+ *   On success the state moves to `initializing`, not `initialized`.
+ * - `notifications/initialized` (no `id`) transitions `initializing` → `initialized`;
+ *   a malformed one (non-object params) is ignored and the session stays gated;
+ *   other notifications are silently ignored in any state.
+ * - Any other method before `notifications/initialized` → error -32002 (not initialized).
+ * - Methods gated by a capability (e.g. `tools/list`) → -32601 when the capability
+ *   is absent.
+ * - `tools/list` params (an optional pagination `cursor`) are validated and passed
+ *   to the handler; invalid params → -32602.
+ */
+export const mcpStep = ({ protocolVersion, capabilities, serverInfo, }) => (handlers) => (stateKey) => (value) => {
+    const [t, message] = decodeRequest(value);
+    if (t === 'error') {
+        return pure(_errResponse(null)(invalidRequest));
+    }
+    const { id, method, params } = message;
+    // Notifications (no `id`) never receive a response.
+    // `notifications/initialized` transitions the session from initializing → initialized.
+    if (id === undefined) {
+        if (method === 'notifications/initialized') {
+            const [pt] = validate(_noParams)(params);
+            if (pt === 'error') {
+                // Malformed handshake — ignore it; the session stays gated.
+                return pure(null);
+            }
+            return read(stateKey).step(([t]) => t === 'initializing'
+                ? write(stateKey, ['initialized', true]).step(() => pure(null))
+                : pure(null));
+        }
+        return pure(null);
+    }
+    // `ping` is always valid regardless of session state, but its params
+    // (if present) must be an object.
+    if (method === 'ping') {
+        const [pt] = validate(_noParams)(params);
+        return pt === 'error'
+            ? pure(_errResponse(id)(invalidParams))
+            : pure(_okResponse(id)({}));
+    }
+    // `initialize` transitions uninitialized → initializing; reject if already done.
+    if (method === 'initialize') {
+        return read(stateKey).step(([t]) => {
+            if (t !== 'uninitialized') {
+                return pure(_errResponse(id)(invalidRequest));
+            }
+            const [pr] = validate(initializeParams)(params);
+            if (pr === 'error') {
+                return pure(_errResponse(id)(invalidParams));
+            }
+            const result = {
+                protocolVersion,
+                capabilities,
+                serverInfo,
+            };
+            return write(stateKey, ['initializing']).step(() => pure(_okResponse(id)(result)));
+        });
+    }
+    // All other methods require fully initialized state — read it first.
+    return read(stateKey).step(([t]) => {
+        if (t !== 'initialized') {
+            return pure(_errResponse(id)(notInitialized));
+        }
+        if (method === 'tools/list') {
+            if (capabilities.tools === undefined) {
+                return pure(_errResponse(id)(methodNotFound));
+            }
+            // `params` may be absent — `tools/list` without a cursor.
+            const [t, pr] = validate(toolsListParams)(params === undefined ? {} : params);
+            return t === 'error'
+                ? pure(_errResponse(id)(invalidParams))
+                : handlers.toolsList(pr).step(r => pure(_okResponse(id)(r)));
+        }
+        if (method === 'tools/call') {
+            if (capabilities.tools === undefined) {
+                return pure(_errResponse(id)(methodNotFound));
+            }
+            const [t, pr] = validate(toolsCallParams)(params);
+            return t === 'error'
+                ? pure(_errResponse(id)(invalidParams))
+                : handlers.toolsCall(pr).step(r => pure(_okResponse(id)(r)));
+        }
+        return pure(_errResponse(id)(methodNotFound));
+    });
+};

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

@@ -0,0 +1,34 @@
+export declare const proof: {
+    lifecycle: {
+        initialStateIsUninitialized: () => void;
+        initializeTransitionsToInitializing: () => void;
+        initializedNotificationTransitionsToInitialized: () => void;
+        initializeReturnsResult: () => void;
+        initializeWithBadParamsReturnsInvalidParams: () => void;
+        notificationBeforeInitReturnNull: () => void;
+        unknownNotificationReturnNull: () => void;
+        doubleInitializeReturnsInvalidRequest: () => void;
+        pingBeforeInitSucceeds: () => void;
+        pingDuringInitializingSucceeds: () => void;
+        pingAfterInitSucceeds: () => void;
+        pingWithObjectParamsSucceeds: () => void;
+        pingInvalidParamsReturnsInvalidParams: () => void;
+        initializedNotificationObjectParamsTransitions: () => void;
+        initializedNotificationBadParamsIgnored: () => void;
+        methodBeforeInitReturnsNotInitialized: () => void;
+        methodDuringInitializingReturnsNotInitialized: () => void;
+        invalidEnvelopeReturnsInvalidRequest: () => void;
+    };
+    tools: {
+        toolsListSucceeds: () => void;
+        toolsListPassesCursorToHandler: () => void;
+        toolsListInvalidCursorReturnsInvalidParams: () => void;
+        toolsCallSucceeds: () => void;
+        toolsCallBadParamsReturnsInvalidParams: () => void;
+        toolsCallAbsentArgumentsSucceeds: () => void;
+        toolsCallNullArgumentsReturnsInvalidParams: () => void;
+        toolsListWithoutCapabilityReturnsMethodNotFound: () => void;
+        toolsCallWithoutCapabilityReturnsMethodNotFound: () => void;
+        unknownMethodReturnsMethodNotFound: () => void;
+    };
+};

package/fs/mcp/proof.f.js

@@ -0,0 +1,207 @@
+import { assert, assertEq } from "../asserts/module.f.js";
+import { pure } from "../effects/module.f.js";
+import { run } from "../effects/mock/module.f.js";
+import { asBase, asNominal, create, read } from "../effects/memory/module.f.js";
+import { uninitializedState, mcpStep, notInitialized, } from "./module.f.js";
+const initial = { next: 0, values: {} };
+const mock = {
+    memCreate: value => state => {
+        const id = `k${state.next}`;
+        const key = asNominal(id);
+        return [{ next: state.next + 1, values: { ...state.values, [id]: value } }, key];
+    },
+    memRead: key => state => [state, state.values[asBase(key)]],
+    memWrite: (key, value) => state => {
+        const id = asBase(key);
+        return [{ ...state, values: { ...state.values, [id]: value } }, undefined];
+    },
+};
+// ── Fixtures ──────────────────────────────────────────────────────────────────
+const config = {
+    serverInfo: { name: 'test-server', version: '0.1.0' },
+    capabilities: { tools: {} },
+    protocolVersion: '2024-11-05',
+};
+const configNoTools = { ...config, capabilities: {} };
+const handlers = {
+    // Echoes a received cursor as `nextCursor` so tests can observe pagination params.
+    toolsList: (p) => pure(p.cursor === undefined
+        ? { tools: [{ name: 'greet', inputSchema: {} }] }
+        : { tools: [], nextCursor: p.cursor }),
+    toolsCall: (_p) => pure({ content: [{ type: 'text', text: 'hello' }] }),
+};
+// Run a memory effect against the mock, return the result.
+const runMem = (effect) => run(mock)(initial)(effect)[1];
+// TypeScript infers O = Operation (the upper bound) rather than O = never when
+// O flows through McpHandlers<never>, so we cast the widened type down to MemOp.
+const asMemEffect = (e) => e;
+// Run one step from uninitializedState, return [response, newState].
+const step1 = (cfg) => (msg) => runMem(asMemEffect(create(uninitializedState).step(key => mcpStep(cfg)(handlers)(key)(msg).step(resp => read(key).step(state => pure([resp, state]))))));
+// Run initialize then a second step, return [response, newState] of the second.
+const step2 = (cfg) => (msg1) => (msg2) => runMem(asMemEffect(create(uninitializedState).step(key => mcpStep(cfg)(handlers)(key)(msg1).step(() => mcpStep(cfg)(handlers)(key)(msg2).step(resp => read(key).step(state => pure([resp, state])))))));
+// Run initialize, notifications/initialized, then a third step; return [response, newState] of the third.
+const step3 = (cfg) => (msg1) => (msg2) => (msg3) => runMem(asMemEffect(create(uninitializedState).step(key => mcpStep(cfg)(handlers)(key)(msg1).step(() => mcpStep(cfg)(handlers)(key)(msg2).step(() => mcpStep(cfg)(handlers)(key)(msg3).step(resp => read(key).step(state => pure([resp, state]))))))));
+// ── Test messages ─────────────────────────────────────────────────────────────
+const initMsg = { jsonrpc: '2.0', method: 'initialize', id: 1,
+    params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'client', version: '0.0.1' } } };
+const initNotif = { jsonrpc: '2.0', method: 'notifications/initialized' };
+// ── Tests ─────────────────────────────────────────────────────────────────────
+export const proof = {
+    lifecycle: {
+        initialStateIsUninitialized: () => {
+            assertEq(uninitializedState[0], 'uninitialized');
+        },
+        initializeTransitionsToInitializing: () => {
+            const [, newState] = step1(config)(initMsg);
+            assertEq(newState[0], 'initializing');
+        },
+        initializedNotificationTransitionsToInitialized: () => {
+            const [resp, newState] = step2(config)(initMsg)(initNotif);
+            assertEq(resp, null);
+            assertEq(newState[0], 'initialized');
+        },
+        initializeReturnsResult: () => {
+            const [resp] = step1(config)(initMsg);
+            assert(resp !== null && typeof resp === 'object' && 'result' in resp);
+            const r = resp.result;
+            assertEq(r.protocolVersion, '2024-11-05');
+        },
+        initializeWithBadParamsReturnsInvalidParams: () => {
+            const bad = { jsonrpc: '2.0', method: 'initialize', id: 2, params: { wrong: true } };
+            const [resp, newState] = step1(config)(bad);
+            assertEq(newState[0], 'uninitialized');
+            assertEq(resp.error.code, -32602);
+        },
+        notificationBeforeInitReturnNull: () => {
+            const [resp, newState] = step1(config)(initNotif);
+            assertEq(newState[0], 'uninitialized');
+            assertEq(resp, null);
+        },
+        unknownNotificationReturnNull: () => {
+            const notif = { jsonrpc: '2.0', method: 'notifications/unknown' };
+            const [resp] = step2(config)(initMsg)(notif);
+            assertEq(resp, null);
+        },
+        doubleInitializeReturnsInvalidRequest: () => {
+            const [resp, newState] = step2(config)(initMsg)(initMsg);
+            assertEq(newState[0], 'initializing');
+            assertEq(resp.error.code, -32600);
+        },
+        pingBeforeInitSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 11 };
+            const [resp, newState] = step1(config)(msg);
+            assertEq(newState[0], 'uninitialized');
+            assert(!('error' in resp));
+        },
+        pingDuringInitializingSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 12 };
+            const [resp, newState] = step2(config)(initMsg)(msg);
+            assertEq(newState[0], 'initializing');
+            assert(!('error' in resp));
+        },
+        pingAfterInitSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 15 };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assert(!('error' in resp));
+        },
+        pingWithObjectParamsSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 19, params: {} };
+            const [resp] = step1(config)(msg);
+            assert(!('error' in resp));
+        },
+        pingInvalidParamsReturnsInvalidParams: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 20, params: 1 };
+            const [resp] = step1(config)(msg);
+            assertEq(resp.error.code, -32602);
+        },
+        initializedNotificationObjectParamsTransitions: () => {
+            const notif = { jsonrpc: '2.0', method: 'notifications/initialized', params: {} };
+            const [resp, newState] = step2(config)(initMsg)(notif);
+            assertEq(resp, null);
+            assertEq(newState[0], 'initialized');
+        },
+        initializedNotificationBadParamsIgnored: () => {
+            const notif = { jsonrpc: '2.0', method: 'notifications/initialized', params: 1 };
+            const [resp, newState] = step2(config)(initMsg)(notif);
+            assertEq(resp, null);
+            assertEq(newState[0], 'initializing');
+        },
+        methodBeforeInitReturnsNotInitialized: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 3 };
+            const [resp, newState] = step1(config)(msg);
+            assertEq(newState[0], 'uninitialized');
+            assertEq(resp.error.code, notInitialized.code);
+        },
+        methodDuringInitializingReturnsNotInitialized: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 16 };
+            const [resp, newState] = step2(config)(initMsg)(msg);
+            assertEq(newState[0], 'initializing');
+            assertEq(resp.error.code, notInitialized.code);
+        },
+        invalidEnvelopeReturnsInvalidRequest: () => {
+            const bad = { jsonrpc: '1.0', method: 'ping', id: 4 };
+            const [resp] = step1(config)(bad);
+            assertEq(resp.error.code, -32600);
+            assertEq(resp.id, null);
+        },
+    },
+    tools: {
+        toolsListSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 5 };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.result.tools.length, 1);
+            assertEq(resp.result.tools[0].name, 'greet');
+        },
+        toolsListPassesCursorToHandler: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 17,
+                params: { cursor: 'page-2' } };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.result.nextCursor, 'page-2');
+        },
+        toolsListInvalidCursorReturnsInvalidParams: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 18,
+                params: { cursor: 42 } };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.error.code, -32602);
+        },
+        toolsCallSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 6,
+                params: { name: 'greet', arguments: {} } };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.result.content[0].text, 'hello');
+        },
+        toolsCallBadParamsReturnsInvalidParams: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 7, params: { missing: true } };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.error.code, -32602);
+        },
+        toolsCallAbsentArgumentsSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 13,
+                params: { name: 'greet' } };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.result.content[0].text, 'hello');
+        },
+        toolsCallNullArgumentsReturnsInvalidParams: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 14,
+                params: { name: 'greet', arguments: null } };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.error.code, -32602);
+        },
+        toolsListWithoutCapabilityReturnsMethodNotFound: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 8 };
+            const [resp] = step3(configNoTools)(initMsg)(initNotif)(msg);
+            assertEq(resp.error.code, -32601);
+        },
+        toolsCallWithoutCapabilityReturnsMethodNotFound: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 9,
+                params: { name: 'greet', arguments: {} } };
+            const [resp] = step3(configNoTools)(initMsg)(initNotif)(msg);
+            assertEq(resp.error.code, -32601);
+        },
+        unknownMethodReturnsMethodNotFound: () => {
+            const msg = { jsonrpc: '2.0', method: 'resources/list', id: 10 };
+            const [resp] = step3(config)(initMsg)(initNotif)(msg);
+            assertEq(resp.error.code, -32601);
+        },
+    },
+};