functionalscript 0.44.0 → 0.46.0

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

@@ -1,11 +1,46 @@
+/**
+ * The FJS MCP server: the composition root the `fjs mcp` / `m` CLI command
+ * runs. Session configuration (`McpConfig`), the top-level entry point
+ * (`casMcpServer`, wiring `mcpStep` + `stdioTransport` from
+ * `fjs/protocol/mcp/`), and the composed tool registry — nothing CAS- or
+ * Evo-specific lives here, it only knows about tool *registries*, not what is
+ * in them, so a future non-CAS tool set can land as a new sibling of
+ * `fjs/mcp/cas/` and `fjs/mcp/evo/` without touching either of them.
+ *
+ * ## Tools
+ *
+ * | Tool           | args                                          | action           | result                              |
+ * |----------------|------------------------------------------------|------------------|--------------------------------------|
+ * | `cas_add`      | `{ content, type? }`                          | `c.write(...)`   | hash (cBase32)                      |
+ * | `cas_get`      | `{ hash, content?: boolean }`                 | `c.read(key)`    | JSON `{length,mimeType,type[,uri][,text\|blob]}` |
+ * | `cas_list`     | `{}`                                          | `c.list()`       | hashes, one per line                |
+ * | `evo_list`     | `{ archived? }`                               | `e.list(...)`    | subjects, as a JSON array of strings |
+ * | `evo_head`     | `{ subject }`                                 | `e.head(...)`    | head hashes, one per line           |
+ * | `evo_revision` | `{ hash }`                                    | `e.revision(...)`| the revision, as JSON               |
+ * | `evo_add`      | `{ parents, snapshot?, subject?, archived? }` | `e.add(...)`     | hash (cBase32)                      |
+ *
+ * `cas_add`/`cas_get`/`cas_list` are `fjs/mcp/cas` — see that module for tool
+ * documentation (input encoding, output shape, error convention). `evo_*` is
+ * `fjs/mcp/evo`. Both tool sets run in one process, sharing one `~/.cas/`
+ * store and one in-memory Evo cache scanned once at startup (`initEvo`).
+ *
+ * @module
+ *
+ * @import { Effect } from '../effects/types.ts'
+ * @import { MemOp } from '../effects/memory/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 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';
 import type { Key } from '../effects/memory/types.ts';
-/** @import { Key } from '../effects/memory/types.ts' */
 /**
  * MCP handlers for `FileCas` (`fjs/mcp/cas`) plus the Evo API (`fjs/mcp/evo`)
  * layered on it, bound to `home` and an already-built Evo cache slot (see
@@ -24,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

@@ -25,25 +25,27 @@
  * store and one in-memory Evo cache scanned once at startup (`initEvo`).
  *
  * @module
+ *
+ * @import { Effect } from '../effects/types.ts'
+ * @import { MemOp } from '../effects/memory/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 { Effect } from '../effects/types.ts' */
+
+import { step as ioStep } from '../effects/module.f.mjs'
 import { create } from '../effects/memory/module.f.mjs'
-/** @import { MemOp } from '../effects/memory/types.ts' */
-/** @import { Read, Write } from '../effects/node/types.ts' */
 import { stdioTransport } from '../protocol/mcp/stdio/module.f.mjs'
 import {
     mcpStep, uninitializedState, fromRegistry,
 } from '../protocol/mcp/module.f.mjs'
-/** @import { McpConfig, McpHandlers } from '../protocol/mcp/types.ts' */
 import { fileCas } from '../cas/module.f.mjs'
-/** @import { FileCasOperation } from '../cas/types.ts' */
 import { initEvo, evo } from '../cas/evo/module.f.mjs'
-/** @import { Cache } from '../cas/evo/types.ts' */
 import { sha256 } from '../crypto/sha2/module.f.mjs'
 import { casToolRegistry } from './cas/module.f.mjs'
 import { evoToolRegistry } from './evo/module.f.mjs'
-/** @import { Key } from '../effects/memory/types.ts' */
 
 // ── Handlers ────────────────────────────────────────────────────────────────────
 
@@ -76,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)),
@@ -91,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,4 +1,16 @@
-/** @import { Unknown } from '../media/json/types.ts' */
+/**
+ * @import { Unknown } from '../media/json/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 { 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: {
     getMetaLargeMultiChunkBlobNoError: () => void;
     getMetaLargeMultiChunkUtf8Symbols: () => void;