functionalscript 0.45.0 → 0.46.0

package/fjs/protocol/mcp/module.f.mjs

@@ -7,7 +7,7 @@
  * - `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
+ * Each schema is both a runtime decoder (`parse(schema)`) and a static
  * TypeScript type (`Ts<typeof schema>`). Transport framing (stdio) and the
  * JSON-RPC dispatcher are in `fjs/protocol/json_rpc/module.f.mjs`.
  *
@@ -15,26 +15,23 @@
  *
  * @import { Unknown } from '../../media/json/types.ts'
  * @import { Ts } from '../../types/rtti/ts/types.ts'
- * @import { Operation, Effect } from '../../effects/types.ts'
+ * @import { Effect, Operation } from '../../effects/types.ts'
  * @import { Key, MemOp } from '../../effects/memory/types.ts'
  * @import { Response, Id, RpcError } from '../json_rpc/types.ts'
  * @import { Type } from '../../types/rtti/types.ts'
- * @import {
- *   Implementation, ServerCapabilities, InitializeResult, Tool,
- *   ToolsListParams, ToolsCallResult, McpHandlers, ToolEntry,
- *   InitializedState, McpSessionState, McpConfig,
- * } from './types.ts'
+ * @import { Implementation, ServerCapabilities, InitializeResult, Tool, ToolsListParams, ToolsCallResult, McpHandlers, ToolEntry, McpSessionState, McpConfig } from './types.ts'
  */
 
 import { boolean, string, option, array, record, or } from '../../types/rtti/module.f.mjs'
-import { pure, step } from '../../effects/module.f.mjs'
+import { pureOk, resultMapStep, resultStep, step as ioStep } from '../../effects/module.f.mjs'
+import { ok } from '../../types/result/module.f.mjs'
 import { read, write } from '../../effects/memory/module.f.mjs'
 import {
     decodeRequest,
-    rpcError, invalidRequest, invalidParams, methodNotFound,
+    rpcError, internalError, invalidRequest, invalidParams, methodNotFound,
     jsonrpc,
 } from '../json_rpc/module.f.mjs'
-import { validate } from '../../types/rtti/validate/module.f.mjs'
+import { parse } from '../../types/rtti/parse/module.f.mjs'
 import { toJsonSchema } from '../../media/json/schema/module.f.mjs'
 import { unknown } from '../../media/json/rtti/module.f.mjs'
 
@@ -152,18 +149,18 @@ export const toolsCallResult = /** @type {const} */ ({
  * @param {string} name - The tool name (used in `tools/call` requests)
  * @param {string} description - Human-readable description for `tools/list`
  * @param {T} inputRtti - Runtime type info for input validation
- * @param {(args: Ts<T>) => Effect<O, ToolsCallResult>} handle - Handler receiving validated arguments of type `Ts<inputRtti>`
+ * @param {(args: Ts<T>) => Effect<O, ToolsCallResult, never>} handle - Handler receiving validated arguments of type `Ts<inputRtti>`
  * @returns {ToolEntry<O>} A `ToolEntry` ready to be added to a registry
  */
 export const toolEntry = (name, description, inputRtti, handle) => ({
     name,
     description,
     inputRtti,
-    /** @type {(a: Unknown) => Effect<O, ToolsCallResult>} */
+    /** @type {(a: Unknown) => Effect<O, ToolsCallResult, never>} */
     handle: a => {
-        const [t, r] = validate(/** @type {any} */ (inputRtti))(a)
+        const [t, r] = parse(/** @type {any} */ (inputRtti))(a)
         return t === 'error'
-            ? pure(errorResult(`invalid arguments: ${r.message}`))
+            ? pureOk(errorResult(`invalid arguments: ${r.message}`))
             : handle(/** @type {Ts<T>} */ (r))
     }
 })
@@ -206,12 +203,12 @@ export const fromRegistry = registry => ({
             description: entry.description,
             inputSchema: toJsonSchema(entry.inputRtti),
         }))
-        return pure({ tools })
+        return pureOk({ tools })
     },
     toolsCall: ({ name, arguments: args }) => {
         const entry = registry.find(e => e.name === name)
         return entry === undefined
-            ? pure(errorResult(`unknown tool: ${name}`))
+            ? pureOk(errorResult(`unknown tool: ${name}`))
             : entry.handle(args === undefined ? {} : args)
     },
 })
@@ -232,13 +229,14 @@ export const notInitialized = rpcError(-32002)('Server not initialized')
 const _noParams = option(record(unknown))
 
 /** Initial session state — always start here. */
-export const uninitializedState = /** @type {McpSessionState} */ (['uninitialized'])
+/** @type {McpSessionState} */
+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>`.
+ * returns a function `(value) => Effect<MemOp | O, Response | null, never>`.
  *
  * Rules:
  * - `ping` returns an empty success regardless of session state; non-object
@@ -255,7 +253,7 @@ export const uninitializedState = /** @type {McpSessionState} */ (['uninitialize
  *   to the handler; invalid params → -32602.
  *
  * @param {McpConfig} config
- * @returns {<O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null>}
+ * @returns {<O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null, never>}
  */
 export const mcpStep = ({
         protocolVersion,
@@ -267,7 +265,7 @@ export const mcpStep = ({
     value => {
         const [t, message] = decodeRequest(value)
         if (t === 'error') {
-            return pure(_errResponse(null)(invalidRequest))
+            return pureOk(_errResponse(null)(invalidRequest))
         }
         const { id, method, params } = message
 
@@ -275,44 +273,51 @@ export const mcpStep = ({
         // `notifications/initialized` transitions the session from initializing → initialized.
         if (id === undefined) {
             if (method === 'notifications/initialized') {
-                const [pt] = validate(_noParams)(params)
+                const [pt] = parse(_noParams)(params)
                 if (pt === 'error') {
                     // Malformed handshake — ignore it; the session stays gated.
-                    return pure(null)
+                    return pureOk(null)
                 }
-                return step(
-                    read(stateKey),
-                    ([t]) => t === 'initializing'
-                        ? step(
-                            write(stateKey, ['initialized', /** @type {InitializedState} */ (true)]),
-                            () => pure(null),
-                        )
-                        : pure(null),
-                )
+                // A notification never receives a response, so a session-state
+                // failure here has nowhere to be reported: the transition is
+                // skipped and the session stays gated, which the client then
+                // observes as `notInitialized` on its next call. That is the
+                // honest degradation — better than a panic, and there is no
+                // response frame to put an error in.
+                return resultStep(read(stateKey), r => {
+                    if (r[0] === 'error' || r[1][0] !== 'initializing') {
+                        return pureOk(null)
+                    }
+                    // `resultMapStep`: a notification has no response frame, so
+                    // the write's own outcome is absorbed here for the same
+                    // reason the read's is above.
+                    return resultMapStep(write(stateKey, ['initialized', true]), () => ok(null))
+                })
             }
-            return pure(null)
+            return pureOk(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)
+            const [pt] = parse(_noParams)(params)
             return pt === 'error'
-                ? pure(_errResponse(id)(invalidParams))
-                : pure(_okResponse(id)({}))
+                ? pureOk(_errResponse(id)(invalidParams))
+                : pureOk(_okResponse(id)({}))
         }
 
         // `initialize` transitions uninitialized → initializing; reject if already done.
         if (method === 'initialize') {
-            return step(
+            return resultStep(
                 read(stateKey),
-                ([t]) => {
-                    if (t !== 'uninitialized') {
-                        return pure(_errResponse(id)(invalidRequest))
+                r => {
+                    if (r[0] === 'error') { return pureOk(_errResponse(id)(internalError)) }
+                    if (r[1][0] !== 'uninitialized') {
+                        return pureOk(_errResponse(id)(invalidRequest))
                     }
-                    const [pr] = validate(initializeParams)(params)
+                    const [pr] = parse(initializeParams)(params)
                     if (pr === 'error') {
-                        return pure(_errResponse(id)(invalidParams))
+                        return pureOk(_errResponse(id)(invalidParams))
                     }
                     /** @type {InitializeResult} */
                     const result = {
@@ -320,50 +325,61 @@ export const mcpStep = ({
                         capabilities,
                         serverInfo,
                     }
-                    return step(
+                    // The write's outcome decides the answer. It used to be
+                    // discarded by a `() =>` continuation, so a session that
+                    // failed to record the transition still replied with a
+                    // successful handshake and then rejected every call after
+                    // it as `notInitialized`.
+                    return resultStep(
                         write(stateKey, ['initializing']),
-                        () => pure(_okResponse(id)(result))
+                        w => pureOk(w[0] === 'error'
+                            ? _errResponse(id)(internalError)
+                            : _okResponse(id)(result)),
                     )
                 },
             )
         }
 
         // All other methods require fully initialized state — read it first.
-        return step(
+        // A session whose state cannot be read is an internal server error, not
+        // an uninitialized one: `notInitialized` tells the client to run the
+        // handshake it has already run, and it would run it again forever.
+        return resultStep(
             read(stateKey),
-            ([t]) => {
-                if (t !== 'initialized') {
-                    return pure(_errResponse(id)(notInitialized))
+            r => {
+                if (r[0] === 'error') { return pureOk(_errResponse(id)(internalError)) }
+                if (r[1][0] !== 'initialized') {
+                    return pureOk(_errResponse(id)(notInitialized))
                 }
 
                 if (method === 'tools/list') {
                     if (capabilities.tools === undefined) {
-                        return pure(_errResponse(id)(methodNotFound))
+                        return pureOk(_errResponse(id)(methodNotFound))
                     }
                     // `params` may be absent — `tools/list` without a cursor.
-                    const [t, pr] = validate(toolsListParams)(params === undefined ? {} : params)
+                    const [t, pr] = parse(toolsListParams)(params === undefined ? {} : params)
                     return t === 'error'
-                        ? pure(_errResponse(id)(invalidParams))
-                        : step(
+                        ? pureOk(_errResponse(id)(invalidParams))
+                        : ioStep(
                             handlers.toolsList(pr),
-                            r => pure(_okResponse(id)(r)),
+                            r => pureOk(_okResponse(id)(r)),
                         )
                 }
 
                 if (method === 'tools/call') {
                     if (capabilities.tools === undefined) {
-                        return pure(_errResponse(id)(methodNotFound))
+                        return pureOk(_errResponse(id)(methodNotFound))
                     }
-                    const [t, pr] = validate(toolsCallParams)(params)
+                    const [t, pr] = parse(toolsCallParams)(params)
                     return t === 'error'
-                        ? pure(_errResponse(id)(invalidParams))
-                        : step(
+                        ? pureOk(_errResponse(id)(invalidParams))
+                        : ioStep(
                             handlers.toolsCall(pr),
-                            r => pure(_okResponse(id)(r)),
+                            r => pureOk(_okResponse(id)(r)),
                         )
                 }
 
-                return pure(_errResponse(id)(methodNotFound))
+                return pureOk(_errResponse(id)(methodNotFound))
             },
         )
     }

package/fjs/protocol/mcp/proof.f.d.mts

@@ -1,12 +1,15 @@
 /**
  * @import { Unknown } from '../../media/json/types.ts'
- * @import { Effect, Operation } from '../../effects/types.ts'
+ * @import { Operation } from '../../effects/types.ts'
+ * @import { Effect, NotImplemented } from '../../effects/types.ts'
  * @import { MemOperationMap } from '../../effects/mock/types.ts'
  * @import { Key, MemOp } from '../../effects/memory/types.ts'
- * @import { Ts } from '../../types/rtti/ts/types.ts'
  * @import {
- *   ToolsListParams, ToolsListResult, ToolsCallParams, ToolsCallResult,
- *   McpHandlers, McpConfig, McpSessionState,
+ *   ToolsListParams,
+ *   ToolsCallParams,
+ *   McpHandlers,
+ *   McpConfig,
+ *   McpSessionState,
  * } from './types.ts'
  */
 import type { McpSessionState } from './types.ts';
@@ -19,6 +22,12 @@ export type _MemoryState = {
 export type _Op = never;
 export type _StepResult = readonly [unknown, McpSessionState];
 export declare const proof: {
+    sessionStateFailure: {
+        initializeRead: () => void;
+        initializeWrite: () => void;
+        gatedMethod: () => void;
+        initializedNotification: () => void;
+    };
     lifecycle: {
         initialStateIsUninitialized: () => void;
         initializeTransitionsToInitializing: () => void;