functionalscript 0.45.0 → 0.46.0

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

@@ -1,18 +1,24 @@
 /**
  * @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 { assert, assertEq } from '../../asserts/module.f.mjs'
-import { history, historyStep, mapStep, pure, step, runPure } from '../../effects/module.f.mjs'
+import { runPure } from '../../effects/module.f.mjs'
+import { history, historyStep, mapStep, pureOk, step } from '../../effects/module.f.mjs'
+import { error, ok, unwrap as unwrapResult } from '../../types/result/module.f.mjs'
 import { run } from '../../effects/mock/module.f.mjs'
+import { internalError } from '../json_rpc/module.f.mjs'
 import { asBase, asNominal, create, read } from '../../effects/memory/module.f.mjs'
 import {
     uninitializedState, mcpStep, notInitialized, fromRegistry, toolEntry, okResult,
@@ -34,12 +40,12 @@ const mock = {
         const id = `k${state.next}`
         /** @type {Key<unknown>} */
         const key = asNominal(id)
-        return [{ next: state.next + 1, values: { ...state.values, [id]: value } }, key]
+        return [{ next: state.next + 1, values: { ...state.values, [id]: value } }, ok(key)]
     },
-    memRead: key => state => [state, state.values[asBase(key)]],
+    memRead: key => state => [state, ok(state.values[asBase(key)])],
     memWrite: (key, value) => state => {
         const id = asBase(key)
-        return [{ ...state, values: { ...state.values, [id]: value } }, undefined]
+        return [{ ...state, values: { ...state.values, [id]: value } }, ok(undefined)]
     },
 }
 
@@ -59,66 +65,149 @@ const configNoTools = { ...config, capabilities: {} }
 const handlers = {
     // Echoes a received cursor as `nextCursor` so tests can observe pagination params.
     toolsList: (/** @type {ToolsListParams} */ p) =>
-        /** @type {Effect<_Op, ToolsListResult>} */
-        (pure(p.cursor === undefined
+        pureOk(p.cursor === undefined
             ? { tools: [{ name: 'greet', inputSchema: {} }] }
-            : { tools: [], nextCursor: p.cursor })),
+            : { tools: [], nextCursor: p.cursor }),
     toolsCall: (/** @type {ToolsCallParams} */ _p) =>
-        /** @type {Effect<_Op, ToolsCallResult>} */
-        (pure({ content: [{ type: 'text', text: 'hello' }] })),
+        pureOk({ content: [{ type: 'text', text: 'hello' }] }),
 }
 
 /** @typedef {readonly [unknown, McpSessionState]} _StepResult */
 
-// Run a memory effect against the mock, return the result.
-/** @type {<T>(effect: Effect<MemOp, T>) => T} */
+// Run a memory effect against the mock and unwrap what it answered. The
+// channel stays generic because nothing here interprets it: a proof has nobody
+// to report a failure to, so an `error` is a panic and the tests read the `ok`.
+/** @type {<T, E>(effect: Effect<MemOp, T, E>) => T} */
 const runMem = effect =>
-    run(mock)(initial)(effect)[1]
+    unwrapResult(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.
-/** @type {<T>(e: Effect<Operation, T>) => Effect<MemOp, T>} */
-const asMemEffect = e => /** @type {Effect<MemOp, any>} */ (/** @type {unknown} */ (e))
+/** @type {<T, E>(e: Effect<Operation, T, E>) => Effect<MemOp, T, E>} */
+const asMemEffect = e => /** @type {Effect<MemOp, any, any>} */ (e)
 
 // Pairs the last step's response with the session state read back afterwards.
 // The response is still needed after the read, so it is carried forward in a
 // history rather than closed over by a nested continuation.
-/** @type {(key: Key<McpSessionState>) => (e: Effect<Operation, unknown>) => Effect<Operation, _StepResult>} */
+/** @type {(key: Key<McpSessionState>) => (e: Effect<Operation, unknown, never>) => Effect<Operation, _StepResult, NotImplemented>} */
 const withState = key => e => {
     const read0 = historyStep(history(e), () => read(key))
+    // A history holds `ok` values, so `resp` is the response itself rather
+    // than a `Result` around it: a failed link short-circuits, contributing
+    // nothing to the tuple and skipping this projection with it.
     return mapStep(read0, ([state, resp]) => /** @type {const} */ ([resp, state]))
 }
 
 // Run one step from uninitializedState, return [response, newState].
-/** @type {(cfg: McpConfig) => (msg: unknown) => _StepResult} */
+/** @type {(cfg: McpConfig) => (msg: Unknown) => _StepResult} */
 const step1 = cfg => msg =>
     runMem(asMemEffect(step(
-        create(/** @type {McpSessionState} */ (uninitializedState)),
-        key => withState(key)(mcpStep(cfg)(handlers)(key)(/** @type {Unknown} */ (msg))))))
+        create(uninitializedState),
+        key => withState(key)(mcpStep(cfg)(handlers)(key)(msg)))))
 
 // Run initialize then a second step, return [response, newState] of the second.
-/** @type {(cfg: McpConfig) => (msg1: unknown) => (msg2: unknown) => _StepResult} */
+/** @type {(cfg: McpConfig) => (msg1: Unknown) => (msg2: Unknown) => _StepResult} */
 const step2 = cfg => msg1 => msg2 =>
     runMem(asMemEffect(step(
-        create(/** @type {McpSessionState} */ (uninitializedState)),
+        create(uninitializedState),
         key => {
-            const r1 = mcpStep(cfg)(handlers)(key)(/** @type {Unknown} */ (msg1))
-            const r2 = step(r1, () => mcpStep(cfg)(handlers)(key)(/** @type {Unknown} */ (msg2)))
+            const r1 = mcpStep(cfg)(handlers)(key)(msg1)
+            const r2 = step(r1, () => mcpStep(cfg)(handlers)(key)(msg2))
             return withState(key)(r2)
         })))
 
 // Run initialize, notifications/initialized, then a third step; return [response, newState] of the third.
-/** @type {(cfg: McpConfig) => (msg1: unknown) => (msg2: unknown) => (msg3: unknown) => _StepResult} */
+/** @type {(cfg: McpConfig) => (msg1: Unknown) => (msg2: Unknown) => (msg3: Unknown) => _StepResult} */
 const step3 = cfg => msg1 => msg2 => msg3 =>
     runMem(asMemEffect(step(
-        create(/** @type {McpSessionState} */ (uninitializedState)),
+        create(uninitializedState),
         key => {
-            const r1 = mcpStep(cfg)(handlers)(key)(/** @type {Unknown} */ (msg1))
-            const r2 = step(r1, () => mcpStep(cfg)(handlers)(key)(/** @type {Unknown} */ (msg2)))
-            const r3 = step(r2, () => mcpStep(cfg)(handlers)(key)(/** @type {Unknown} */ (msg3)))
+            const r1 = mcpStep(cfg)(handlers)(key)(msg1)
+            const r2 = step(r1, () => mcpStep(cfg)(handlers)(key)(msg2))
+            const r3 = step(r2, () => mcpStep(cfg)(handlers)(key)(msg3))
             return withState(key)(r3)
         })))
 
+// ── Response accessors ────────────────────────────────────────────────────────
+//
+// A step's response is `unknown`, and its shape is exactly what these proofs
+// exist to check — so reading it through a cast would assume the thing being
+// proved. These accessors check their way in instead, and fail at the read
+// rather than somewhere downstream.
+
+/** Whether `resp` is an object carrying an `error` member. */
+/** @type {(resp: unknown) => boolean} */
+const hasError = resp =>
+    typeof resp === 'object' && resp !== null && 'error' in resp
+
+/** @type {(resp: unknown) => number} */
+const errorCode = resp => {
+    assert(hasError(resp) && typeof resp === 'object' && resp !== null && 'error' in resp, resp)
+    const { error } = resp
+    assert(typeof error === 'object' && error !== null && 'code' in error, error)
+    const { code } = error
+    assert(typeof code === 'number', code)
+    return code
+}
+
+/** @type {(resp: unknown) => unknown} */
+const errorId = resp => {
+    assert(typeof resp === 'object' && resp !== null && 'id' in resp, resp)
+    return resp.id
+}
+
+/** @type {(resp: unknown) => object} */
+const resultOf = resp => {
+    assert(typeof resp === 'object' && resp !== null && 'result' in resp, resp)
+    const { result } = resp
+    assert(typeof result === 'object' && result !== null, result)
+    return result
+}
+
+/** @type {(resp: unknown) => string} */
+const protocolVersion = resp => {
+    const result = resultOf(resp)
+    assert('protocolVersion' in result, result)
+    const { protocolVersion: v } = result
+    assert(typeof v === 'string', v)
+    return v
+}
+
+/** @type {(resp: unknown) => readonly string[]} */
+const toolNames = resp => {
+    const result = resultOf(resp)
+    assert('tools' in result, result)
+    const { tools } = result
+    assert(tools instanceof Array, tools)
+    return tools.map(t => {
+        assert(typeof t === 'object' && t !== null && 'name' in t, t)
+        const { name } = t
+        assert(typeof name === 'string', name)
+        return name
+    })
+}
+
+/** @type {(resp: unknown) => unknown} */
+const nextCursor = resp => {
+    const result = resultOf(resp)
+    assert('nextCursor' in result, result)
+    return result.nextCursor
+}
+
+/** The `text` of the first content item of a `tools/call` result. */
+/** @type {(resp: unknown) => string} */
+const firstText = resp => {
+    const result = resultOf(resp)
+    assert('content' in result, result)
+    const { content } = result
+    assert(content instanceof Array && content.length !== 0, content)
+    const [item] = content
+    assert(typeof item === 'object' && item !== null && 'text' in item, item)
+    const { text } = item
+    assert(typeof text === 'string', text)
+    return text
+}
+
 // ── Test messages ─────────────────────────────────────────────────────────────
 
 const initMsg = { jsonrpc: '2.0', method: 'initialize', id: 1,
@@ -126,9 +215,53 @@ const initMsg = { jsonrpc: '2.0', method: 'initialize', id: 1,
 
 const initNotif = { jsonrpc: '2.0', method: 'notifications/initialized' }
 
+/** A memory handler that answers as a runner with no such operation. */
+const memNotImplemented = () => (/** @type {_MemoryState} */ state) =>
+    /** @type {const} */ ([state, error(/** @type {const} */ (['notImplemented', 'memRead']))])
+
+// Runs one step against a memory mock with `overrides` applied, from a session
+// slot created before them so the slot itself always exists.
+/** @type {(overrides: Partial<MemOperationMap<MemOp, _MemoryState>>) => (msg: Unknown) => unknown} */
+const failingStep = overrides => msg => {
+    const [state, key] = run(mock)(initial)(create(uninitializedState))
+    const runner = run(/** @type {MemOperationMap<MemOp, _MemoryState>} */ ({ ...mock, ...overrides }))
+    // A `Handle` answers `Effect<…, Response | null, never>`, so the payload
+    // the runner hands back is the `ok` around the response and the unwrap is
+    // total — the failures these tests inject are the ones `mcpStep` itself
+    // absorbs into an error response.
+    return unwrapResult(runner(state)(asMemEffect(mcpStep(config)(handlers)(unwrapResult(key))(msg)))[1])
+}
+
 // ── Tests ─────────────────────────────────────────────────────────────────────
 
 export const proof = {
+    // A session slot the runner cannot reach is `-32603`, not `-32002`.
+    // `notInitialized` tells the client to run the handshake it has already
+    // run, so it would run it forever; an internal error says the fault is the
+    // server's. Three sites answer it — the `initialize` read, the transition
+    // write, and the gate every other method passes through — and a
+    // notification, having no response frame at all, answers `null` instead.
+    sessionStateFailure: {
+        initializeRead: () => {
+            const resp = failingStep({ memRead: memNotImplemented })(initMsg)
+            assertEq(errorCode(resp), internalError.code)
+        },
+        initializeWrite: () => {
+            const resp = failingStep({ memWrite: memNotImplemented })(initMsg)
+            assertEq(errorCode(resp), internalError.code)
+        },
+        gatedMethod: () => {
+            const resp = failingStep({ memRead: memNotImplemented })(
+                { jsonrpc: '2.0', method: 'tools/list', id: 3 })
+            assertEq(errorCode(resp), internalError.code)
+        },
+        // The notification path has nowhere to report, so it stays silent and
+        // leaves the session gated rather than claiming the transition.
+        initializedNotification: () => {
+            const resp = failingStep({ memRead: memNotImplemented })(initNotif)
+            assertEq(resp, null)
+        },
+    },
     lifecycle: {
         initialStateIsUninitialized: () => {
             assert(uninitializedState[0] === 'uninitialized')
@@ -147,16 +280,14 @@ export const proof = {
 
         initializeReturnsResult: () => {
             const [resp] = step1(config)(initMsg)
-            assert(resp !== null && typeof resp === 'object' && 'result' in /** @type {object} */ (resp))
-            const r = /** @type {{ result: { protocolVersion: string } }} */ (resp).result
-            assertEq(r.protocolVersion, '2024-11-05')
+            assertEq(protocolVersion(resp), '2024-11-05')
         },
 
         initializeWithBadParamsReturnsInvalidParams: () => {
             const bad = { jsonrpc: '2.0', method: 'initialize', id: 2, params: { wrong: true } }
             const [resp, newState] = step1(config)(bad)
             assert(newState[0] === 'uninitialized')
-            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32602)
+            assertEq(errorCode(resp), -32602)
         },
 
         notificationBeforeInitReturnNull: () => {
@@ -174,39 +305,39 @@ export const proof = {
         doubleInitializeReturnsInvalidRequest: () => {
             const [resp, newState] = step2(config)(initMsg)(initMsg)
             assert(newState[0] === 'initializing')
-            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32600)
+            assertEq(errorCode(resp), -32600)
         },
 
         pingBeforeInitSucceeds: () => {
             const msg = { jsonrpc: '2.0', method: 'ping', id: 11 }
             const [resp, newState] = step1(config)(msg)
             assert(newState[0] === 'uninitialized')
-            assert(!('error' in /** @type {object} */ (resp)))
+            assert(!hasError(resp), resp)
         },
 
         pingDuringInitializingSucceeds: () => {
             const msg = { jsonrpc: '2.0', method: 'ping', id: 12 }
             const [resp, newState] = step2(config)(initMsg)(msg)
             assert(newState[0] === 'initializing')
-            assert(!('error' in /** @type {object} */ (resp)))
+            assert(!hasError(resp), resp)
         },
 
         pingAfterInitSucceeds: () => {
             const msg = { jsonrpc: '2.0', method: 'ping', id: 15 }
             const [resp] = step3(config)(initMsg)(initNotif)(msg)
-            assert(!('error' in /** @type {object} */ (resp)))
+            assert(!hasError(resp), resp)
         },
 
         pingWithObjectParamsSucceeds: () => {
             const msg = { jsonrpc: '2.0', method: 'ping', id: 19, params: {} }
             const [resp] = step1(config)(msg)
-            assert(!('error' in /** @type {object} */ (resp)))
+            assert(!hasError(resp), resp)
         },
 
         pingInvalidParamsReturnsInvalidParams: () => {
             const msg = { jsonrpc: '2.0', method: 'ping', id: 20, params: 1 }
             const [resp] = step1(config)(msg)
-            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32602)
+            assertEq(errorCode(resp), -32602)
         },
 
         initializedNotificationObjectParamsTransitions: () => {
@@ -227,21 +358,21 @@ export const proof = {
             const msg = { jsonrpc: '2.0', method: 'tools/list', id: 3 }
             const [resp, newState] = step1(config)(msg)
             assert(newState[0] === 'uninitialized')
-            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, notInitialized.code)
+            assertEq(errorCode(resp), notInitialized.code)
         },
 
         methodDuringInitializingReturnsNotInitialized: () => {
             const msg = { jsonrpc: '2.0', method: 'tools/list', id: 16 }
             const [resp, newState] = step2(config)(initMsg)(msg)
             assert(newState[0] === 'initializing')
-            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, notInitialized.code)
+            assertEq(errorCode(resp), notInitialized.code)
         },
 
         invalidEnvelopeReturnsInvalidRequest: () => {
             const bad = { jsonrpc: '1.0', method: 'ping', id: 4 }
             const [resp] = step1(config)(bad)
-            assertEq(/** @type {{ error: { code: number }; id: unknown }} */ (resp).error.code, -32600)
-            assertEq(/** @type {{ error: { code: number }; id: unknown }} */ (resp).id, null)
+            assertEq(errorCode(resp), -32600)
+            assertEq(errorId(resp), null)
         },
     },
 
@@ -249,68 +380,68 @@ export const proof = {
         toolsListSucceeds: () => {
             const msg = { jsonrpc: '2.0', method: 'tools/list', id: 5 }
             const [resp] = step3(config)(initMsg)(initNotif)(msg)
-            assertEq(/** @type {{ result: ToolsListResult }} */ (resp).result.tools.length, 1)
-            assertEq(/** @type {{ result: ToolsListResult }} */ (resp).result.tools[0].name, 'greet')
+            assertEq(toolNames(resp).length, 1)
+            assertEq(toolNames(resp)[0], 'greet')
         },
 
         toolsListPassesCursorToHandler: () => {
             const msg = { jsonrpc: '2.0', method: 'tools/list', id: 17,
                 params: { cursor: 'page-2' } }
             const [resp] = step3(config)(initMsg)(initNotif)(msg)
-            assertEq(/** @type {{ result: ToolsListResult }} */ (resp).result.nextCursor, 'page-2')
+            assertEq(nextCursor(resp), 'page-2')
         },
 
         toolsListInvalidCursorReturnsInvalidParams: () => {
             const msg = { jsonrpc: '2.0', method: 'tools/list', id: 18,
                 params: { cursor: 42 } }
             const [resp] = step3(config)(initMsg)(initNotif)(msg)
-            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32602)
+            assertEq(errorCode(resp), -32602)
         },
 
         toolsCallSucceeds: () => {
             const msg = { jsonrpc: '2.0', method: 'tools/call', id: 6,
                 params: { name: 'greet', arguments: {} } }
             const [resp] = step3(config)(initMsg)(initNotif)(msg)
-            assertEq(/** @type {{ text: string }} */ (/** @type {{ result: ToolsCallResult }} */ (resp).result.content[0]).text, 'hello')
+            assertEq(firstText(resp), 'hello')
         },
 
         toolsCallBadParamsReturnsInvalidParams: () => {
             const msg = { jsonrpc: '2.0', method: 'tools/call', id: 7, params: { missing: true } }
             const [resp] = step3(config)(initMsg)(initNotif)(msg)
-            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32602)
+            assertEq(errorCode(resp), -32602)
         },
 
         toolsCallAbsentArgumentsSucceeds: () => {
             const msg = { jsonrpc: '2.0', method: 'tools/call', id: 13,
                 params: { name: 'greet' } }
             const [resp] = step3(config)(initMsg)(initNotif)(msg)
-            assertEq(/** @type {{ text: string }} */ (/** @type {{ result: ToolsCallResult }} */ (resp).result.content[0]).text, 'hello')
+            assertEq(firstText(resp), '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(/** @type {{ error: { code: number } }} */ (resp).error.code, -32602)
+            assertEq(errorCode(resp), -32602)
         },
 
         toolsListWithoutCapabilityReturnsMethodNotFound: () => {
             const msg = { jsonrpc: '2.0', method: 'tools/list', id: 8 }
             const [resp] = step3(configNoTools)(initMsg)(initNotif)(msg)
-            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32601)
+            assertEq(errorCode(resp), -32601)
         },
 
         toolsCallWithoutCapabilityReturnsMethodNotFound: () => {
             const msg = { jsonrpc: '2.0', method: 'tools/call', id: 9,
                 params: { name: 'greet', arguments: {} } }
             const [resp] = step3(configNoTools)(initMsg)(initNotif)(msg)
-            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32601)
+            assertEq(errorCode(resp), -32601)
         },
 
         unknownMethodReturnsMethodNotFound: () => {
             const msg = { jsonrpc: '2.0', method: 'resources/list', id: 10 }
             const [resp] = step3(config)(initMsg)(initNotif)(msg)
-            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32601)
+            assertEq(errorCode(resp), -32601)
         },
     },
 
@@ -324,12 +455,13 @@ export const proof = {
         toolsCallAbsentArgumentsDefaultsToEmptyObject: () => {
             const echoArgs = /** @type {const} */ ({})
             const entry = toolEntry('echo', 'echoes', echoArgs,
-                /** @type {(a: Ts<typeof echoArgs>) => Effect<never, ToolsCallResult>} */
-                (() => pure(okResult('ok'))))
+                () => pureOk(okResult('ok')))
             const handlers = fromRegistry([entry])
-            const [result] = runPure(handlers.toolsCall({ name: 'echo' }))
-            assert(result !== undefined)
-            assertEq(/** @type {{ readonly text: string }} */ (result.content[0]).text, 'ok')
+            const [r] = runPure(handlers.toolsCall({ name: 'echo' }))
+            assert(r !== undefined && r[0] === 'ok', r)
+            const [item] = r[1].content
+            assert(item.type === 'text', item)
+            assertEq(item.text, 'ok')
         },
     },
 }

package/fjs/protocol/mcp/stdio/module.f.d.mts

@@ -2,7 +2,7 @@
  * stdio transport for JSON-RPC / MCP servers.
  *
  * `stdioTransport` wraps a step function — the `mcpStep`-shaped
- * `(value) => Effect<O, Response | null>` from `fjs/protocol/mcp/module.f.mjs` — in the
+ * `(value) => Effect<O, Response | null, never>` from `fjs/protocol/mcp/module.f.mjs` — in the
  * canonical read → parse → dispatch → write loop, expressed as a recursive
  * effect so it stays in the pure effect model and is fully testable against a
  * mock stdin / stdout (see `fjs/effects/node/virtual`) with no real process.
@@ -29,13 +29,15 @@
  *
  * @module
  *
- * @import { Effect, Operation } from '../../../effects/types.ts'
- * @import { IoResult, Read, Write } from '../../../effects/node/types.ts'
+ * @import { Operation } from '../../../effects/types.ts'
+ * @import { IoChannel, Read, Write } from '../../../effects/node/types.ts'
+ * @import { Effect } from '../../../effects/types.ts'
  * @import { Response } from '../../json_rpc/types.ts'
  * @import { Step } from './types.ts'
  */
-import type { Effect, Operation } from '../../../effects/types.ts';
-import type { Read, Write } from '../../../effects/node/types.ts';
+import type { Operation } from '../../../effects/types.ts';
+import type { IoChannel, Read, Write } from '../../../effects/node/types.ts';
+import type { Effect } from '../../../effects/types.ts';
 import type { Step } from './types.ts';
 /**
  * Drives the read-parse-dispatch-write loop for `handler` over stdin/stdout.
@@ -43,8 +45,14 @@ import type { Step } from './types.ts';
  * Recurses after each handled line; terminates (resolving to `void`) when
  * `readLine` reports EOF.
  *
+ * A transport that cannot read its own input has no fallback to choose, but it
+ * does not have to decide that here: the failure ends the loop and travels to
+ * whoever started the server, which for `fjs mcp` is a message on `stderr` and
+ * exit `1`. EOF is not that — `readLine` answers `ok(null)`, the loop ends, and
+ * the server has done its job.
+ *
  * @template {Operation} O
  * @param {Step<O>} handler
- * @returns {Effect<Read | Write | O, void>}
+ * @returns {Effect<Read | Write | O, void, IoChannel>}
  */
-export declare const stdioTransport: <O extends Operation>(handler: Step<O>) => Effect<Read | Write | O, void>;
+export declare const stdioTransport: <O extends Operation>(handler: Step<O>) => Effect<Read | Write | O, void, IoChannel>;

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

@@ -2,7 +2,7 @@
  * stdio transport for JSON-RPC / MCP servers.
  *
  * `stdioTransport` wraps a step function — the `mcpStep`-shaped
- * `(value) => Effect<O, Response | null>` from `fjs/protocol/mcp/module.f.mjs` — in the
+ * `(value) => Effect<O, Response | null, never>` from `fjs/protocol/mcp/module.f.mjs` — in the
  * canonical read → parse → dispatch → write loop, expressed as a recursive
  * effect so it stays in the pure effect model and is fully testable against a
  * mock stdin / stdout (see `fjs/effects/node/virtual`) with no real process.
@@ -29,19 +29,20 @@
  *
  * @module
  *
- * @import { Effect, Operation } from '../../../effects/types.ts'
- * @import { IoResult, Read, Write } from '../../../effects/node/types.ts'
+ * @import { Operation } from '../../../effects/types.ts'
+ * @import { IoChannel, Read, Write } from '../../../effects/node/types.ts'
+ * @import { Effect } from '../../../effects/types.ts'
  * @import { Response } from '../../json_rpc/types.ts'
  * @import { Step } from './types.ts'
  */
 
-import { pure, step } from '../../../effects/module.f.mjs'
-import { readLine, write } from '../../../effects/node/module.f.mjs'
+import { pureError, pureOk, resultStep, step } from '../../../effects/module.f.mjs'
+import { ioError, readLine, write } from '../../../effects/node/module.f.mjs'
 import { tryUtf8 } from '../../../text/module.f.mjs'
 import { parse, stringify } from '../../../media/json/module.f.mjs'
 import { sort } from '../../../types/object/module.f.mjs'
 import { internalError, jsonrpc, parseError } from '../../json_rpc/module.f.mjs'
-import { error, ok } from '../../../types/result/module.f.mjs'
+import { error } from '../../../types/result/module.f.mjs'
 
 const stringifyJson = stringify(sort)
 
@@ -55,16 +56,13 @@ const parseErrorResponse = { jsonrpc, error: parseError, id: null }
 const internalErrorResponse = id => ({ jsonrpc, error: internalError, id })
 
 /** Encodes a response as a newline-terminated UTF-8 line and writes it to `stdout`.
- * @type {(resp: Response) => Effect<Write, IoResult<void>>}
+ * @type {(resp: Response) => Effect<Write, void, IoChannel>}
  */
 const writeResponse = resp => {
     const v = tryUtf8(stringifyJson(resp) + '\n')
     return v === null
-        ? pure(error(undefined))
-        : step(
-            write('stdout', v),
-            () => pure(ok(undefined)),
-        )
+        ? pureError(ioError({ message: 'response does not encode as UTF-8' }))
+        : write('stdout', v)
 }
 
 /**
@@ -73,35 +71,48 @@ const writeResponse = resp => {
  * Recurses after each handled line; terminates (resolving to `void`) when
  * `readLine` reports EOF.
  *
+ * A transport that cannot read its own input has no fallback to choose, but it
+ * does not have to decide that here: the failure ends the loop and travels to
+ * whoever started the server, which for `fjs mcp` is a message on `stderr` and
+ * exit `1`. EOF is not that — `readLine` answers `ok(null)`, the loop ends, and
+ * the server has done its job.
+ *
  * @template {Operation} O
  * @param {Step<O>} handler
- * @returns {Effect<Read | Write | O, void>}
+ * @returns {Effect<Read | Write | O, void, IoChannel>}
  */
 export const stdioTransport = handler =>
     step(
         readLine('stdin'),
         line => line === null
-            ? pure(undefined)
+            ? pureOk(undefined)
             : handleLine(handler)(line),
     )
 
 /**
  * @template {Operation} O
  * @param {Step<O>} handler
- * @returns {(line: string) => Effect<Read | Write | O, void>}
+ * @returns {(line: string) => Effect<Read | Write | O, void, IoChannel>}
  */
 const handleLine = handler => line => {
     const [t, value] = parse(line)
-    return step(
+    return resultStep(
         t === 'error'
             ? writeResponse(parseErrorResponse)
+            // `step`, because a `Handle` answers `Effect<O, Response | null,
+            // never>` — it absorbs its own failures into the response body — so
+            // the continuation receives the response itself and there is no
+            // error branch left for this chain to consider.
             : step(
                 handler(value),
                 resp => resp === null
-                    ? pure(undefined)
-                    : step(
+                    ? pureOk(undefined)
+                    // `resultStep` from here down: each write's *failure* is
+                    // what selects the next, smaller fallback, so these are the
+                    // both-branches case rather than a chain to short-circuit.
+                    : resultStep(
                         writeResponse(resp),
-                        ([t2]) => t2 === 'error'
+                        r2 => r2[0] === 'error'
                             // The real response didn't fit. Retry with a fixed, small
                             // internal-error body carrying `resp.id` — but a
                             // caller-controlled `id` (e.g. a very large string) can
@@ -109,17 +120,19 @@ const handleLine = handler => line => {
                             // that retry is bounded by one more: an `id: null`
                             // internal-error, whose fully-constant shape is the only
                             // line in this transport guaranteed to always encode.
-                            ? step(
+                            ? resultStep(
                                 writeResponse(internalErrorResponse(resp.id)),
-                                ([t3]) => t3 === 'error'
-                                    ? step(
+                                r3 => r3[0] === 'error'
+                                    ? resultStep(
                                         writeResponse(internalErrorResponse(null)),
-                                        () => pure(undefined),
+                                        () => pureOk(undefined),
                                     )
-                                    : pure(undefined)
+                                    : pureOk(undefined)
                             )
-                            : pure(undefined)),
+                            : pureOk(undefined)),
             ),
+        // The loop continues whatever the line's own handling answered: a
+        // transport that could not write one response still serves the next.
         () => stdioTransport(handler),
     )
 }