functionalscript 0.45.0 → 0.46.1

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

@@ -1,17 +1,35 @@
 /**
  * @import { Evo } from '../../cas/evo/types.ts'
  * @import { ToolEntry, ToolsCallResult } from '../../protocol/mcp/types.ts'
- * @import { Operation } from '../../effects/types.ts'
+ * @import { NotImplemented, Operation } from '../../effects/types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { State } from '../../effects/node/virtual/types.ts'
  */
 
 import { assert, assertEq } from '../../asserts/module.f.mjs'
 import { fileCas } from '../../cas/module.f.mjs'
 import { sha256 } from '../../crypto/sha2/module.f.mjs'
 import { emptyState, virtual } from '../../effects/node/virtual/module.f.mjs'
+import { runPure } from '../../effects/module.f.mjs'
+import { pureError } from '../../effects/module.f.mjs'
+import { unwrap as unwrapResult } from '../../types/result/module.f.mjs'
 import { vec8 } from '../../types/bit_vec/module.f.mjs'
 import { vecToCBase32 } from '../../basen/cbase32/module.f.mjs'
 import { initEvo, evo } from '../../cas/evo/module.f.mjs'
-import { evoToolRegistry } from './module.f.mjs'
+import { evoAddArgs, evoToolRegistry } from './module.f.mjs'
+import { toJsonSchema } from '../../media/json/schema/module.f.mjs'
+import { at } from '../../types/object/module.f.mjs'
+
+/**
+ * Unwraps what a run answered, keeping the state beside it.
+ *
+ * These cases drive the tools against a virtual filesystem that always
+ * cooperates, so a channel failure here is a broken fixture rather than a case
+ * under test — and the unwrap is where that assumption is stated.
+ *
+ * @type {<T, E>(r: readonly [State, Result<T, E>]) => readonly [State, T]}
+ */
+const unwrapRun = ([state, r]) => [state, unwrapResult(r)]
 import { parse as parseJson } from '../../media/json/module.f.mjs'
 import { array, string as rttiString } from '../../types/rtti/module.f.mjs'
 import { parse as rttiParse } from '../../types/rtti/parse/module.f.mjs'
@@ -30,17 +48,43 @@ const parseSubjects = rttiParse(array(rttiString))
 const findEntry = (registry, name) => {
     const entry = registry.find(e => e.name === name)
     assert(entry !== undefined, ['missing tool entry', name])
-    return /** @type {ToolEntry<O>} */ (entry)
+    return entry
 }
 
 /** @type {(result: ToolsCallResult) => string} */
 const textOf = result => {
     const [item] = result.content
     assert(item.type === 'text', ['expected a text content item', item])
-    return /** @type {{ text: string }} */ (item).text
+    return item.text
 }
 
 export const proof = {
+    // Every Evo tool answers a channel failure — a cache slot the runner
+    // cannot reach — as an ordinary `isError` result. The client asked a
+    // question the server could not answer, which is a tool-level failure,
+    // not a reason to take the server down.
+    channelFailureIsToolError: () => {
+        /** @type {NotImplemented} */
+        const boom = ['notImplemented', 'memRead']
+        /** @type {Evo<never>} */
+        const failing = {
+            list: () => pureError(boom),
+            head: () => pureError(boom),
+            add: () => pureError(boom),
+            revision: () => { throw 'unused' },
+        }
+        const registry = evoToolRegistry(failing)
+        for (const [name, args] of /** @type {const} */ ([
+            ['evo_list', {}],
+            ['evo_head', { subject: 'x' }],
+            ['evo_add', { parents: [] }],
+        ])) {
+            const [r] = runPure(findEntry(registry, name).handle(args))
+            const result = r === undefined ? undefined : r[1]
+            assert(result !== undefined && result.isError === true, ['expected isError', name, result])
+            assert(textOf(result).includes('memRead'), ['expected the command name in the message', name])
+        }
+    },
     toolNamesMatchTheDesign: () => {
         /** @type {Evo<never>} */
         const e = {
@@ -53,10 +97,10 @@ export const proof = {
     },
     evoListReflectsTheCache: () => {
         const c = fileCas(sha256)(home)
-        const [state0, cacheKey] = virtual(emptyState)(initEvo(c))
+        const [state0, cacheKey] = unwrapRun(virtual(emptyState)(initEvo(c)))
         const e = evo(c)(cacheKey)
         const entry = findEntry(evoToolRegistry(e), 'evo_list')
-        const [, result] = virtual(state0)(entry.handle({}))
+        const [, [, result]] = virtual(state0)(entry.handle({}))
         assert(!result.isError)
         assertEq(textOf(result), '[]')
     },
@@ -67,14 +111,12 @@ export const proof = {
     // encoding preserves both exactly.
     evoListEncodesArbitrarySubjectsAsJson: () => {
         const c = fileCas(sha256)(home)
-        const [state0, cacheKey] = virtual(emptyState)(initEvo(c))
+        const [state0, cacheKey] = unwrapRun(virtual(emptyState)(initEvo(c)))
         const e = evo(c)(cacheKey)
-        const [state1, addA] = virtual(state0)(e.add({ parents: [], subject: 'line one\nline two', snapshot: vecToCBase32(vec8(0x2an)) }))
-        assert(addA[0] === 'ok', ['expected add ok', addA])
-        const [state2, addB] = virtual(state1)(e.add({ parents: [], subject: '', snapshot: vecToCBase32(vec8(0x2bn)) }))
-        assert(addB[0] === 'ok', ['expected add ok', addB])
+        const [state1] = unwrapRun(virtual(state0)(e.add({ parents: [], subject: 'line one\nline two', snapshot: vecToCBase32(vec8(0x2an)) })))
+        const [state2] = unwrapRun(virtual(state1)(e.add({ parents: [], subject: '', snapshot: vecToCBase32(vec8(0x2bn)) })))
         const entry = findEntry(evoToolRegistry(e), 'evo_list')
-        const [, result] = virtual(state2)(entry.handle({}))
+        const [, [, result]] = virtual(state2)(entry.handle({}))
         assert(!result.isError)
         const subjects = unwrap(parseSubjects(unwrap(parseJson(textOf(result)))))
         assertEq(subjects.length, 2)
@@ -85,33 +127,32 @@ export const proof = {
     // omitted lists the active subjects, `true` the archived ones.
     evoListForwardsTheArchivedFilter: () => {
         const c = fileCas(sha256)(home)
-        const [state0, cacheKey] = virtual(emptyState)(initEvo(c))
+        const [state0, cacheKey] = unwrapRun(virtual(emptyState)(initEvo(c)))
         const e = evo(c)(cacheKey)
-        const [state1, add] = virtual(state0)(e.add({ parents: [], subject: 'gone', snapshot: vecToCBase32(vec8(0x2cn)), archived: true }))
-        assert(add[0] === 'ok', ['expected add ok', add])
+        const [state1] = unwrapRun(virtual(state0)(e.add({ parents: [], subject: 'gone', snapshot: vecToCBase32(vec8(0x2cn)), archived: true })))
         const entry = findEntry(evoToolRegistry(e), 'evo_list')
-        const [state2, active] = virtual(state1)(entry.handle({}))
+        const [state2, [, active]] = virtual(state1)(entry.handle({}))
         assert(!active.isError)
         assertEq(textOf(active), '[]')
-        const [, archived] = virtual(state2)(entry.handle({ archived: true }))
+        const [, [, archived]] = virtual(state2)(entry.handle({ archived: true }))
         assert(!archived.isError)
         assertEq(textOf(archived), '["gone"]')
     },
     evoHeadReflectsTheCache: () => {
         const c = fileCas(sha256)(home)
-        const [state0, cacheKey] = virtual(emptyState)(initEvo(c))
+        const [state0, cacheKey] = unwrapRun(virtual(emptyState)(initEvo(c)))
         const e = evo(c)(cacheKey)
         const entry = findEntry(evoToolRegistry(e), 'evo_head')
-        const [, result] = virtual(state0)(entry.handle({ subject: 'nope' }))
+        const [, [, result]] = virtual(state0)(entry.handle({ subject: 'nope' }))
         assert(!result.isError)
         assertEq(textOf(result), '')
     },
     evoHeadMissingSubjectIsInvalidArguments: () => {
         const c = fileCas(sha256)(home)
-        const [state0, cacheKey] = virtual(emptyState)(initEvo(c))
+        const [state0, cacheKey] = unwrapRun(virtual(emptyState)(initEvo(c)))
         const e = evo(c)(cacheKey)
         const entry = findEntry(evoToolRegistry(e), 'evo_head')
-        const [, result] = virtual(state0)(entry.handle({}))
+        const [, [, result]] = virtual(state0)(entry.handle({}))
         assertEq(result.isError, true)
     },
     // Covers evo_revision's success branch: the stored revision comes back as
@@ -119,13 +160,12 @@ export const proof = {
     // resolved `snapshot` included.
     evoRevisionReturnsRevisionJson: () => {
         const c = fileCas(sha256)(home)
-        const [state0, cacheKey] = virtual(emptyState)(initEvo(c))
+        const [state0, cacheKey] = unwrapRun(virtual(emptyState)(initEvo(c)))
         const e = evo(c)(cacheKey)
         const subject = vecToCBase32(vec8(0x3n))
-        const [state1, added] = virtual(state0)(e.add({ parents: [], subject }))
-        assert(added[0] === 'ok', ['expected add ok', added])
+        const [state1, added] = unwrapRun(virtual(state0)(e.add({ parents: [], subject })))
         const entry = findEntry(evoToolRegistry(e), 'evo_revision')
-        const [, result] = virtual(state1)(entry.handle({ hash: added[1] }))
+        const [, [, result]] = virtual(state1)(entry.handle({ hash: added }))
         assert(!result.isError)
         assertEq(textOf(result), `{"subject":"${subject}","parents":[],"snapshot":"${subject}","generation":0}`)
     },
@@ -133,10 +173,10 @@ export const proof = {
     // store has nothing under) is surfaced as isError with the message.
     evoRevisionDomainErrorIsError: () => {
         const c = fileCas(sha256)(home)
-        const [state0, cacheKey] = virtual(emptyState)(initEvo(c))
+        const [state0, cacheKey] = unwrapRun(virtual(emptyState)(initEvo(c)))
         const e = evo(c)(cacheKey)
         const entry = findEntry(evoToolRegistry(e), 'evo_revision')
-        const [, result] = virtual(state0)(entry.handle({ hash: vecToCBase32(vec8(0x4n)) }))
+        const [, [, result]] = virtual(state0)(entry.handle({ hash: vecToCBase32(vec8(0x4n)) }))
         assertEq(result.isError, true)
         assert(textOf(result).includes('revision not found'))
     },
@@ -144,22 +184,66 @@ export const proof = {
     // hash comes back as plain, non-error text.
     evoAddSuccessReturnsHash: () => {
         const c = fileCas(sha256)(home)
-        const [state0, cacheKey] = virtual(emptyState)(initEvo(c))
+        const [state0, cacheKey] = unwrapRun(virtual(emptyState)(initEvo(c)))
         const e = evo(c)(cacheKey)
         const entry = findEntry(evoToolRegistry(e), 'evo_add')
         const args = { parents: [], subject: 'doc', snapshot: vecToCBase32(vec8(0x1n)) }
-        const [, result] = virtual(state0)(entry.handle(args))
+        const [, [, result]] = virtual(state0)(entry.handle(args))
         assert(!result.isError)
         assert(textOf(result).length > 0)
     },
+    // `evo_add` accepts a nested lock map and `evo_revision` gives it back —
+    // the two tools speak one recursive schema, so a revision read out can be
+    // added again as-is however deep its lock nests.
+    evoAddAndRevisionCarryNestedLocks: () => {
+        const c = fileCas(sha256)(home)
+        const [state0, cacheKey] = unwrapRun(virtual(emptyState)(initEvo(c)))
+        const e = evo(c)(cacheKey)
+        const registry = evoToolRegistry(e)
+        const snapshot = vecToCBase32(vec8(0x1n))
+        const d1 = vecToCBase32(vec8(0x2n))
+        const d2 = vecToCBase32(vec8(0x3n))
+        const args = {
+            parents: [], subject: 'doc', snapshot,
+            lock: { B: { D: d1 }, C: { D: d2 } },
+        }
+        const [state1, [, added]] = virtual(state0)(findEntry(registry, 'evo_add').handle(args))
+        assert(!added.isError)
+        const [, [, read]] = virtual(state1)(findEntry(registry, 'evo_revision').handle({ hash: textOf(added) }))
+        assert(!read.isError)
+        assertEq(
+            textOf(read),
+            `{"subject":"doc","parents":[],"snapshot":"${snapshot}","generation":0,"lock":{"B":{"D":"${d1}"},"C":{"D":"${d2}"}}}`)
+    },
+    // The advertised `inputSchema` publishes both halves of the format's
+    // `lock` field: either a shared-lock reference (a string) or an inline
+    // map, and the map's recursion the way JSON Schema expresses one — a named
+    // `$defs` rule reached through a local `$ref`, rather than a flat-only
+    // shape or an infinitely inlined one.
+    evoAddInputSchemaPublishesTheLockRecursion: () => {
+        const schema = toJsonSchema(evoAddArgs)
+        const lock = at('lock')(schema.properties ?? {})
+        assert(lock !== null, ['expected a lock property', schema])
+        const ref = '#/$defs/lockValue'
+        const [sharedRef, inlineMap] = lock.anyOf ?? []
+        assertEq(sharedRef?.type, 'string')
+        assertEq(inlineMap?.type, 'object')
+        assertEq(at('$ref')(inlineMap?.additionalProperties ?? {}), ref)
+        const rule = at('lockValue')(schema.$defs ?? {})
+        assert(rule !== null, ['expected a lockValue definition', schema])
+        const [directHash, nestedMap] = rule.anyOf ?? []
+        assertEq(directHash?.type, 'string')
+        assertEq(nestedMap?.type, 'object')
+        assertEq(at('$ref')(nestedMap?.additionalProperties ?? {}), ref)
+    },
     // Covers evo_add's error branch: a domain-level failure (Evo.add's
     // Result) is surfaced as isError with the failure message as text.
     evoAddDomainErrorIsError: () => {
         const c = fileCas(sha256)(home)
-        const [state0, cacheKey] = virtual(emptyState)(initEvo(c))
+        const [state0, cacheKey] = unwrapRun(virtual(emptyState)(initEvo(c)))
         const e = evo(c)(cacheKey)
         const entry = findEntry(evoToolRegistry(e), 'evo_add')
-        const [, result] = virtual(state0)(entry.handle({ parents: [] }))
+        const [, [, result]] = virtual(state0)(entry.handle({ parents: [] }))
         assertEq(result.isError, true)
         assert(textOf(result).includes('subject is required'))
     },

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

@@ -28,7 +28,7 @@
  *
  * @import { Effect } from '../effects/types.ts'
  * @import { MemOp } from '../effects/memory/types.ts'
- * @import { Read, Write } from '../effects/node/types.ts'
+ * @import { IoChannel, Read, Write } from '../effects/node/types.ts'
  * @import { McpConfig, McpHandlers } from '../protocol/mcp/types.ts'
  * @import { FileCasOperation } from '../cas/types.ts'
  * @import { Cache } from '../cas/evo/types.ts'
@@ -36,7 +36,7 @@
  */
 import type { Effect } from '../effects/types.ts';
 import type { MemOp } from '../effects/memory/types.ts';
-import type { Read, Write } from '../effects/node/types.ts';
+import type { IoChannel, Read, Write } from '../effects/node/types.ts';
 import type { McpConfig, McpHandlers } from '../protocol/mcp/types.ts';
 import type { FileCasOperation } from '../cas/types.ts';
 import type { Cache } from '../cas/evo/types.ts';
@@ -59,9 +59,9 @@ export declare const casConfig: McpConfig;
  * build the Evo subject/head cache (`initEvo`), allocates the session-state
  * slot, builds the `mcpStep` for the merged tool registry, and drives the
  * read → parse → dispatch → write loop until stdin EOF.
- * @type {(home: string) => Effect<Read | Write | MemOp | FileCasOperation, void>}
+ * @type {(home: string) => Effect<Read | Write | MemOp | FileCasOperation, void, IoChannel>}
  */
-export declare const casMcpServer: (home: string) => Effect<Read | Write | MemOp | FileCasOperation, void>;
+export declare const casMcpServer: (home: string) => Effect<Read | Write | MemOp | FileCasOperation, void, IoChannel>;
 export declare const proof: {
     casMcpServer: () => void;
 };

package/fjs/mcp/module.f.mjs

@@ -28,14 +28,14 @@
  *
  * @import { Effect } from '../effects/types.ts'
  * @import { MemOp } from '../effects/memory/types.ts'
- * @import { Read, Write } from '../effects/node/types.ts'
+ * @import { IoChannel, Read, Write } from '../effects/node/types.ts'
  * @import { McpConfig, McpHandlers } from '../protocol/mcp/types.ts'
  * @import { FileCasOperation } from '../cas/types.ts'
  * @import { Cache } from '../cas/evo/types.ts'
  * @import { Key } from '../effects/memory/types.ts'
  */
 
-import { step } from '../effects/module.f.mjs'
+import { step as ioStep } from '../effects/module.f.mjs'
 import { create } from '../effects/memory/module.f.mjs'
 import { stdioTransport } from '../protocol/mcp/stdio/module.f.mjs'
 import {
@@ -78,11 +78,11 @@ export const casConfig = {
  * build the Evo subject/head cache (`initEvo`), allocates the session-state
  * slot, builds the `mcpStep` for the merged tool registry, and drives the
  * read → parse → dispatch → write loop until stdin EOF.
- * @type {(home: string) => Effect<Read | Write | MemOp | FileCasOperation, void>}
+ * @type {(home: string) => Effect<Read | Write | MemOp | FileCasOperation, void, IoChannel>}
  */
-export const casMcpServer = home => step(
+export const casMcpServer = home => ioStep(
     initEvo(fileCas(sha256)(home)),
-    cacheKey => step(
+    cacheKey => ioStep(
         create(uninitializedState),
         sessionKey =>
             stdioTransport(mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey)),
@@ -93,6 +93,6 @@ export const casMcpServer = home => step(
 
 export const proof = {
     // casMcpServer is never called in integration tests because it drives a
-    // real stdio server; call it here to cover its Effect-building body.
+    // real stdio server; call it here to cover its effect-building body.
     casMcpServer: () => { casMcpServer('/') },
 }

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

@@ -1,12 +1,14 @@
 /**
  * @import { Unknown } from '../media/json/types.ts'
- * @import { Effect, Operation } from '../effects/types.ts'
+ * @import { Operation } from '../effects/types.ts'
  * @import { Response } from '../protocol/json_rpc/types.ts'
+ * @import { Handle } from '../protocol/mcp/types.ts'
  * @import { Vec } from '../types/bit_vec/types.ts'
  * @import { FileCasOperation } from '../cas/types.ts'
  * @import { List } from '../effects/list/types.ts'
- * @import { McpSessionState, ToolsCallResult } from '../protocol/mcp/types.ts'
- * @import { IoResult, Mkdir, Now, RandomInt, ReadBytes, Rename, } from '../effects/node/types.ts'
+ * @import { Effect } from '../effects/types.ts'
+ * @import { ContentItem, ToolsCallResult } from '../protocol/mcp/types.ts'
+ * @import { IoChannel, Mkdir, Now, RandomInt, ReadBytes, Rename } from '../effects/node/types.ts'
  * @import { Dir } from '../effects/node/virtual/types.ts'
  */
 export declare const proof: {

package/fjs/mcp/proof.f.mjs

@@ -1,17 +1,19 @@
 /**
  * @import { Unknown } from '../media/json/types.ts'
- * @import { Effect, Operation } from '../effects/types.ts'
+ * @import { Operation } from '../effects/types.ts'
  * @import { Response } from '../protocol/json_rpc/types.ts'
+ * @import { Handle } from '../protocol/mcp/types.ts'
  * @import { Vec } from '../types/bit_vec/types.ts'
  * @import { FileCasOperation } from '../cas/types.ts'
  * @import { List } from '../effects/list/types.ts'
- * @import { McpSessionState, ToolsCallResult } from '../protocol/mcp/types.ts'
- * @import { IoResult, Mkdir, Now, RandomInt, ReadBytes, Rename, } from '../effects/node/types.ts'
+ * @import { Effect } from '../effects/types.ts'
+ * @import { ContentItem, ToolsCallResult } from '../protocol/mcp/types.ts'
+ * @import { IoChannel, Mkdir, Now, RandomInt, ReadBytes, Rename } from '../effects/node/types.ts'
  * @import { Dir } from '../effects/node/virtual/types.ts'
  */
 
 import { assert, assertEq } from '../asserts/module.f.mjs'
-import { pure, step } from '../effects/module.f.mjs'
+import { pureOk, step } from '../effects/module.f.mjs'
 import { create } from '../effects/memory/module.f.mjs'
 import { parse as parseJson } from '../media/json/module.f.mjs'
 import { number as rttiNumber, option, string as rttiString } from '../types/rtti/module.f.mjs'
@@ -29,7 +31,7 @@ import {
 } from '../protocol/mcp/module.f.mjs'
 import { emptyState, virtual } from '../effects/node/virtual/module.f.mjs'
 import { casConfig, casMcpHandlers } from './module.f.mjs'
-import { ok as resultOk, unwrap } from '../types/result/module.f.mjs'
+import { ok as resultOk, unwrap, unwrap as unwrapResult } from '../types/result/module.f.mjs'
 import { stdioTransport } from '../protocol/mcp/stdio/module.f.mjs'
 import { fromVec } from '../types/uint8array/module.f.mjs'
 import { initEvo } from '../cas/evo/module.f.mjs'
@@ -55,14 +57,16 @@ const parseCasGetResult = rttiParse(casGetResult)
 // Feeds each message to `handler` in order, collecting every response.
 /**
  * @template {Operation} O
- * @param {(v: Unknown) => Effect<O, Response | null>} handler
- * @returns {(msgs: readonly unknown[]) => Effect<O, readonly unknown[]>}
+ * @param {Handle<O>} handler
+ * @returns {(msgs: readonly unknown[]) => Effect<O, readonly unknown[], never>}
  */
 const feed = handler => msgs => {
-    /** @type {(i: number, acc: readonly unknown[]) => Effect<O, readonly unknown[]>} */
+    /** @type {(i: number, acc: readonly unknown[]) => Effect<O, readonly unknown[], never>} */
     const go = (i, acc) => (
         i === msgs.length
-            ? pure(acc)
+            ? pureOk(acc)
+            // The channel stays `never`: a `Handle` has absorbed its own
+            // failures into the response, so every message contributes one.
             : step(
                 handler(/** @type {Unknown} */ (msgs[i])),
                 r => go(i + 1, [...acc, r]))
@@ -81,11 +85,10 @@ const runSessionVirtual =
             initEvo(fileCas(sha256)(home)),
             cacheKey => step(
                 create(uninitializedState),
-                sessionKey => {
-                    const step = mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey)
-                    return feed(step)(msgs)
-                }))
-        return virtual({ ...emptyState, root })(effect)[1]
+                sessionKey => feed(mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey))(msgs)))
+        // A proof has nobody to report a channel failure to, so it panics: the
+        // session either ran or the test is meaningless.
+        return unwrapResult(virtual({ ...emptyState, root })(effect)[1])
     }
 
 // Seeds a blob directly into the virtual store via `c.write`, bypassing the
@@ -98,8 +101,8 @@ const runSessionVirtual =
 const seedBlob = (root, home = '/home/user') => chunks => {
     const c = fileCas(sha256)(home)
     const stream = chunks.reduceRight(
-        (/** @type {List<never, IoResult<Vec>>} */ tail, chunk) => nonEmpty(resultOk(chunk), tail),
-        /** @type {List<never, IoResult<Vec>>} */ (elEmpty()))
+        (/** @type {List<never, Vec, IoChannel>} */ tail, chunk) => nonEmpty(chunk, tail),
+        /** @satisfies {List<never, Vec, IoChannel>} */ (elEmpty()))
     const [state, result] = virtual({ ...emptyState, root })(c.write(stream))
     assert(result[0] === 'ok', result)
     return [state.root, vecToCBase32(result[1])]
@@ -143,7 +146,7 @@ const runStdio =
         const effect = step(
             initEvo(fileCas(sha256)(home)),
             cacheKey => step(
-                create(/** @type {McpSessionState} */ (uninitializedState)),
+                create(uninitializedState),
                 sessionKey =>
                     stdioTransport(mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey))
             )
@@ -154,15 +157,80 @@ const runStdio =
         return stdout.split('\n').filter(line => line.length > 0).slice(1).map(line => unwrap(parseJson(line)))
     }
 
+/**
+ * The `result` of a `tools/call` response.
+ *
+ * This is the one place a response crosses from `unknown` to a typed
+ * {@link ToolsCallResult}. The structural essentials are checked here so the
+ * accessors below — and every call site — do not have to assume them; only the
+ * final step from a checked `content` array to `ToolsCallResult` is taken on
+ * trust, because rtti's `parse` reads `Unknown`, and getting there from
+ * `unknown` is the same problem one level down.
+ */
 /** @type {(resp: unknown) => ToolsCallResult} */
-const resultOf = resp =>
-    /** @type {{ readonly result: ToolsCallResult }} */ (resp).result
+const resultOf = resp => {
+    assert(typeof resp === 'object' && resp !== null && 'result' in resp, resp)
+    const { result } = resp
+    assert(typeof result === 'object' && result !== null && 'content' in result, result)
+    const { content } = result
+    assert(content instanceof Array, content)
+    return /** @type {ToolsCallResult} */ (result)
+}
 
-/** @type {(resp: unknown) => unknown} */
-const item0 = resp => resultOf(resp).content[0]
+/** @type {(resp: unknown) => ContentItem} */
+const item0 = resp => {
+    const [item] = resultOf(resp).content
+    assert(item !== undefined, resp)
+    return item
+}
 
 /** @type {(resp: unknown) => string} */
-const textOf = resp => (/** @type {{ readonly text: string }} */ (item0(resp))).text
+const textOf = resp => {
+    const item = item0(resp)
+    assert(item.type === 'text', item)
+    return item.text
+}
+
+// The accessors below read a response that is `unknown` at this boundary. They
+// check their way in rather than casting, so a malformed response fails at the
+// read with the offending value attached.
+
+/** Whether `resp` is an object carrying `key`. */
+/** @type {(resp: unknown, key: 'error' | 'result') => boolean} */
+const has = (resp, key) => typeof resp === 'object' && resp !== null && key in resp
+
+/** @type {(resp: unknown) => number} */
+const errorCode = resp => {
+    assert(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 idOf = resp => {
+    assert(typeof resp === 'object' && resp !== null && 'id' in resp, resp)
+    return resp.id
+}
+
+/** The `name` and `inputSchema.type` of each tool in a `tools/list` result. */
+/** @type {(resp: unknown) => readonly { readonly name: string, readonly schemaType: unknown }[]} */
+const toolsOf = resp => {
+    assert(typeof resp === 'object' && resp !== null && 'result' in resp, resp)
+    const { result } = resp
+    assert(typeof result === 'object' && result !== null && '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 && 'inputSchema' in t, t)
+        const { name, inputSchema } = t
+        assert(typeof name === 'string', name)
+        assert(typeof inputSchema === 'object' && inputSchema !== null && 'type' in inputSchema, inputSchema)
+        return { name, schemaType: inputSchema.type }
+    })
+}
 
 /** The `text` payload of a `cas_get` response, parsed and checked against {@link casGetResult}. */
 const casGetResultOf = (/** @type {unknown} */ resp) =>
@@ -176,12 +244,12 @@ const textSample = 'hello, world!'
 const revisionSample = `{"dialect":"${revisionDialect}","subject":"8","parents":[],"snapshot":"8","generation":0}`
 
 // A base64-encoded binary payload for binary add→get round-trips.
-const binarySample = /** @type {string} */ (base64Encode(vec8(0x2An)))
+const binarySample = base64Encode(vec8(0x2An))
 
 // A base64 blob whose leading bytes are the PNG magic-byte signature, so
 // `cas_get` detects its type and returns base64 with mimeType image/png.
-const pngSample = /** @type {string} */ (base64Encode(
-    u8ListToVec(msb)([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x01])))
+const pngSample = base64Encode(
+    u8ListToVec(msb)([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x01]))
 
 // Returns the RFC 4648 base64 encoding of `n` zero bytes, computed directly
 // without bigint arithmetic — independent of `base64.encode` so these tests
@@ -209,10 +277,10 @@ const largeMultiChunkBlobMeta =
     (/** @type {Vec} */ chunk0, /** @type {Vec} */ chunk1, /** @type {string} */ expectedType,
         /** @type {string} */ expectedMime) => () => {
         const [root, hash] = seedBlob({})([chunk0, chunk1])
-        const [metaResp] = /** @type {readonly unknown[]} */ (runSessionVirtual(root)([
+        const [metaResp] = runSessionVirtual(root)([
             init, initialized,
             call(2, 'cas_get', { hash }),
-        ]).slice(2))
+        ]).slice(2)
         assert(!resultOf(metaResp).isError)
         const meta = casGetResultOf(metaResp)
         assertEq(meta.type, expectedType)
@@ -265,10 +333,10 @@ export const proof = {
     // buffered inline. The metadata-only path (above) still returns its size/type.
     getContentLargeBlobTooLargeError: () => {
         const [root, hash] = seedBlob({})([asciiChunk, asciiChunk])
-        const [getResp] = /** @type {readonly unknown[]} */ (runSessionVirtual(root)([
+        const [getResp] = runSessionVirtual(root)([
             init, initialized,
             call(2, 'cas_get', { hash, content: true }),
-        ]).slice(2))
+        ]).slice(2)
         assertEq(resultOf(getResp).isError, true)
         const text = textOf(getResp)
         assert(text.includes('too large'))
@@ -302,9 +370,8 @@ export const proof = {
         const [getResp] = runStdio(root)([
             call(2, 'cas_get', { hash, content: true }),
         ])
-        const err = /** @type {{ readonly error?: { readonly code: number }, readonly id: unknown }} */ (getResp)
-        assertEq(err.error?.code, -32603)
-        assertEq(err.id, 2)
+        assertEq(errorCode(getResp), -32603)
+        assertEq(idOf(getResp), 2)
     },
 
     // The paired boundary case: a blob whose base64 inflation leaves enough
@@ -337,19 +404,18 @@ export const proof = {
         const [getResp] = runStdio(root)([
             call(2, 'cas_get', { hash, content: true }),
         ])
-        const err = /** @type {{ readonly error?: { readonly code: number }, readonly id: unknown }} */ (getResp)
-        assertEq(err.error?.code, -32603)
-        assertEq(err.id, 2)
+        assertEq(errorCode(getResp), -32603)
+        assertEq(idOf(getResp), 2)
     },
 
     toolsListAdvertisesSevenTools: () => {
         const [resp] = runSessionVirtual({})([init, initialized, list(2)]).slice(2)
-        const tools = (/** @type {{ result: { tools: readonly { name: string }[] } }} */ (resp)).result.tools
+        const tools = toolsOf(resp)
         assertEq(tools.length, 7)
         assertEq(tools.map(t => t.name).join(','), 'cas_add,cas_get,cas_list,evo_list,evo_head,evo_revision,evo_add')
-        const add = (/** @type {{ result: { tools: readonly { inputSchema: { type?: string } }[] } }} */ (resp))
-            .result.tools[0]
-        assertEq(add.inputSchema.type, 'object')
+        const [add] = tools
+        assert(add !== undefined, tools)
+        assertEq(add.schemaType, 'object')
     },
 
     // The same server also exposes Evo (fjs/cas/evo): add a revision, then
@@ -476,7 +542,7 @@ export const proof = {
             call(2, 'cas_add', { content: textSample }),
             call(3, 'cas_get', { hash, content: true }),
         )
-        assertEq(item0(getResp) === null ? null : (/** @type {{ type: string }} */ (item0(getResp))).type, 'text')
+        assertEq(item0(getResp).type, 'text')
         const result = casGetResultOf(getResp)
         assertEq(result.type, 'text')
         assertEq(result.mimeType, 'text/plain')
@@ -491,7 +557,7 @@ export const proof = {
             call(3, 'cas_get', { hash, content: true }),
         )
         assert(!resultOf(getResp).isError)
-        assertEq((/** @type {{ type: string }} */ (item0(getResp))).type, 'text')
+        assertEq(item0(getResp).type, 'text')
         const result = casGetResultOf(getResp)
         assertEq(result.type, 'base64')
         assertEq(result.mimeType, 'image/png')
@@ -620,8 +686,8 @@ export const proof = {
 
     toolErrorIsNotJsonRpcError: () => {
         const [resp] = session(call(2, 'cas_add', { content: 'not valid!', type: 'base64' }))
-        assert(!('error' in /** @type {object} */ (resp)))
-        assert('result' in /** @type {object} */ (resp))
+        assert(!has(resp, 'error'), resp)
+        assert(has(resp, 'result'), resp)
     },
 
     // cas_get without content:true returns only metadata.
@@ -657,7 +723,7 @@ export const proof = {
 
     getMetaOctetStreamForUnknownBinary: () => {
         const binaryContent = u8ListToVec(msb)([0xFF, 0xFE, 0x00, 0x01])
-        const binaryB64 = /** @type {string} */ (base64Encode(binaryContent))
+        const binaryB64 = base64Encode(binaryContent)
         const [addResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }))
         const hash = textOf(addResp)
         const [, metaResp] = session(
@@ -675,7 +741,7 @@ export const proof = {
     // base64/octet-stream, not text/plain.
     getMetaOctetStreamForNulBlob: () => {
         const nulContent = u8ListToVec(msb)([0x00, 0x00, 0x00])
-        const nulB64 = /** @type {string} */ (base64Encode(nulContent))
+        const nulB64 = base64Encode(nulContent)
         const [addResp] = session(call(2, 'cas_add', { content: nulB64, type: 'base64' }))
         const hash = textOf(addResp)
         const [, metaResp] = session(
@@ -702,7 +768,7 @@ export const proof = {
     // cas_get with content:true on octet-stream (no magic bytes, not UTF-8) returns inline base64.
     getOctetStreamWithContentIncludesBase64: () => {
         const binaryContent = u8ListToVec(msb)([0xFF, 0xFE, 0x00, 0x01])
-        const binaryB64 = /** @type {string} */ (base64Encode(binaryContent))
+        const binaryB64 = base64Encode(binaryContent)
         const [addResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }))
         const hash = textOf(addResp)
         const [, getResp] = session(