functionalscript 0.43.1 → 0.45.0

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

@@ -0,0 +1,88 @@
+/**
+ * MCP tool definitions for the Evo API (`fjs/cas/evo/module.f.mjs`): subjects,
+ * revision heads, and the typed read of a single revision over the
+ * content-addressable store, backed by the in-memory cache the core module
+ * maintains.
+ *
+ * ## Tools
+ *
+ * | Tool           | args                                          | action            | result                               |
+ * |----------------|-----------------------------------------------|-------------------|--------------------------------------|
+ * | `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 `RevisionData` |
+ * | `evo_add`      | `{ parents, snapshot?, subject?, archived? }`  | `e.add(...)`      | hash (cBase32)                       |
+ *
+ * `evo_add` and `evo_revision` speak the same structure — `fjs/cas/evo`'s
+ * `RevisionData` — in opposite directions, so a revision read back can be
+ * added again as-is. `evo_add`'s advertised arguments stay as they are: the
+ * one field `evo_revision` returns that `evo_add` does not accept is
+ * `generation`, which the server computes, and rtti's struct validation
+ * ignores properties the schema does not name, so a whole `evo_revision`
+ * result can be passed straight back to `evo_add`.
+ *
+ * ## Result size
+ *
+ * `evo_list` and `evo_revision` answer with JSON carried as MCP *text*
+ * content, so the JSON-RPC serializer escapes it a second time on the way
+ * out and a modest result can encode to a much longer line (a subject of
+ * quote characters is the worst case). A response whose encoded line exceeds
+ * the transport cap is not lost: `fjs/protocol/mcp/stdio` retries with a small
+ * `-32603` body carrying the request's `id`, so every request still gets a
+ * response and the process never crashes. That is the transport's contract
+ * for every tool — `cas_get` has proofs for the same double-escaping path —
+ * and no tool here can pre-empt it: whether the encoded response fits is
+ * known only by encoding it, which is the transport's job, and guessing from
+ * an unencoded size is exactly the size estimate that must never be made.
+ *
+ * These tools are not served by their own process: `fjs/mcp` (the same
+ * server as `cas_add`/`cas_get`/`cas_list`) builds one `Evo<O>` from its own
+ * `Cas<O>` and cache slot, concatenates `evoToolRegistry` onto its own
+ * registry, and serves everything from that single process — one `~/.cas/`
+ * store, one Evo cache, one server.
+ *
+ * @module
+ *
+ * @import { Effect, Operation } from '../../effects/types.ts'
+ * @import { MemOp } from '../../effects/memory/types.ts'
+ * @import { ToolEntry, ToolsCallResult } from '../../protocol/mcp/types.ts'
+ * @import { Evo } from '../../cas/evo/types.ts'
+ * @import { Ts } from '../../types/rtti/ts/types.ts'
+ */
+import type { Operation } from '../../effects/types.ts';
+import type { MemOp } from '../../effects/memory/types.ts';
+import type { ToolEntry } from '../../protocol/mcp/types.ts';
+import type { Evo } from '../../cas/evo/types.ts';
+/**
+ * Arguments for `evo_list`: an optional status filter, forwarded unchanged to
+ * `Evo.list` — omitted lists the active subjects, `true` the archived ones.
+ */
+export declare const evoListArgs: {
+    readonly archived: import("../../types/rtti/types.ts").Or<readonly [true, undefined]>;
+};
+/** Arguments for `evo_head`: the subject whose current heads are requested. */
+export declare const evoHeadArgs: {
+    readonly subject: import("../../types/rtti/types.ts")._Type0<"string">;
+};
+/** Arguments for `evo_revision`: the hash of the revision to read. */
+export declare const evoRevisionArgs: {
+    readonly hash: import("../../types/rtti/types.ts")._Type0<"string">;
+};
+/**
+ * Arguments for `evo_add`: a new revision, per `fjs/cas/evo`'s
+ * `RevisionData` — every field of it the caller supplies, i.e. all but
+ * `generation`, which the server computes.
+ */
+export declare const evoAddArgs: {
+    readonly parents: import("../../types/rtti/types.ts").Type1<"array", import("../../types/rtti/types.ts")._Type0<"string">>;
+    readonly snapshot: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+    readonly subject: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+    readonly archived: import("../../types/rtti/types.ts").Or<readonly [true, undefined]>;
+};
+/**
+ * Registry of all Evo tools, bound to an `Evo<O>`.
+ * @template {Operation} O
+ * @param {Evo<O>} e
+ * @returns {readonly ToolEntry<O | MemOp>[]}
+ */
+export declare const evoToolRegistry: <O extends Operation>(e: Evo<O>) => readonly ToolEntry<O | MemOp>[];

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

@@ -0,0 +1,153 @@
+/**
+ * MCP tool definitions for the Evo API (`fjs/cas/evo/module.f.mjs`): subjects,
+ * revision heads, and the typed read of a single revision over the
+ * content-addressable store, backed by the in-memory cache the core module
+ * maintains.
+ *
+ * ## Tools
+ *
+ * | Tool           | args                                          | action            | result                               |
+ * |----------------|-----------------------------------------------|-------------------|--------------------------------------|
+ * | `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 `RevisionData` |
+ * | `evo_add`      | `{ parents, snapshot?, subject?, archived? }`  | `e.add(...)`      | hash (cBase32)                       |
+ *
+ * `evo_add` and `evo_revision` speak the same structure — `fjs/cas/evo`'s
+ * `RevisionData` — in opposite directions, so a revision read back can be
+ * added again as-is. `evo_add`'s advertised arguments stay as they are: the
+ * one field `evo_revision` returns that `evo_add` does not accept is
+ * `generation`, which the server computes, and rtti's struct validation
+ * ignores properties the schema does not name, so a whole `evo_revision`
+ * result can be passed straight back to `evo_add`.
+ *
+ * ## Result size
+ *
+ * `evo_list` and `evo_revision` answer with JSON carried as MCP *text*
+ * content, so the JSON-RPC serializer escapes it a second time on the way
+ * out and a modest result can encode to a much longer line (a subject of
+ * quote characters is the worst case). A response whose encoded line exceeds
+ * the transport cap is not lost: `fjs/protocol/mcp/stdio` retries with a small
+ * `-32603` body carrying the request's `id`, so every request still gets a
+ * response and the process never crashes. That is the transport's contract
+ * for every tool — `cas_get` has proofs for the same double-escaping path —
+ * and no tool here can pre-empt it: whether the encoded response fits is
+ * known only by encoding it, which is the transport's job, and guessing from
+ * an unencoded size is exactly the size estimate that must never be made.
+ *
+ * These tools are not served by their own process: `fjs/mcp` (the same
+ * server as `cas_add`/`cas_get`/`cas_list`) builds one `Evo<O>` from its own
+ * `Cas<O>` and cache slot, concatenates `evoToolRegistry` onto its own
+ * registry, and serves everything from that single process — one `~/.cas/`
+ * store, one Evo cache, one server.
+ *
+ * @module
+ *
+ * @import { Effect, Operation } from '../../effects/types.ts'
+ * @import { MemOp } from '../../effects/memory/types.ts'
+ * @import { ToolEntry, ToolsCallResult } from '../../protocol/mcp/types.ts'
+ * @import { Evo } from '../../cas/evo/types.ts'
+ * @import { Ts } from '../../types/rtti/ts/types.ts'
+ */
+
+import { string, option, array } from '../../types/rtti/module.f.mjs'
+import { pure, step } from '../../effects/module.f.mjs'
+import {
+    toolEntry, errorResult, okResult,
+} from '../../protocol/mcp/module.f.mjs'
+import { stringify } from '../../media/json/module.f.mjs'
+import { identity } from '../../types/function/module.f.mjs'
+
+// ── Argument schemas (declared once, used for both inputSchema and validate) ─────
+
+/**
+ * Arguments for `evo_list`: an optional status filter, forwarded unchanged to
+ * `Evo.list` — omitted lists the active subjects, `true` the archived ones.
+ */
+export const evoListArgs = /** @type {const} */ ({
+    archived: option(true),
+})
+
+/** Arguments for `evo_head`: the subject whose current heads are requested. */
+export const evoHeadArgs = /** @type {const} */ ({
+    subject: string,
+})
+
+/** Arguments for `evo_revision`: the hash of the revision to read. */
+export const evoRevisionArgs = /** @type {const} */ ({
+    hash: string,
+})
+
+/**
+ * Arguments for `evo_add`: a new revision, per `fjs/cas/evo`'s
+ * `RevisionData` — every field of it the caller supplies, i.e. all but
+ * `generation`, which the server computes.
+ */
+export const evoAddArgs = /** @type {const} */ ({
+    parents: array(string),
+    snapshot: option(string),
+    subject: option(string),
+    archived: option(true),
+})
+
+// ── Tool registry ────────────────────────────────────────────────────────────────
+
+/** Canonical JSON encoder for the `evo_list` and `evo_revision` results. */
+const toJson = stringify(identity)
+
+/**
+ * Registry of all Evo tools, bound to an `Evo<O>`.
+ * @template {Operation} O
+ * @param {Evo<O>} e
+ * @returns {readonly ToolEntry<O | MemOp>[]}
+ */
+export const evoToolRegistry = e => [
+    toolEntry(
+        'evo_list',
+        'List subjects, as a JSON array of strings. By default only the active ones: a subject is active while at least one of its current heads is not archived. Pass `archived: true` to list the archived subjects instead — those with at least one current head, all of them archived. A subject with no current heads is in neither list.',
+        evoListArgs,
+        // Subjects are arbitrary caller-supplied strings (unlike hashes, not
+        // constrained to a newline-free alphabet), so a `join('\n')` line
+        // format could not represent an empty subject or one containing a
+        // newline without ambiguity — JSON encoding can.
+        /** @type {(args: Ts<typeof evoListArgs>) => Effect<MemOp, ToolsCallResult>} */
+        (({ archived }) => step(
+            e.list(archived),
+            subjects => pure(okResult(toJson(subjects)))
+        )),
+    ),
+    toolEntry(
+        'evo_head',
+        'List the current head hashes (cBase32) of a subject, one per line. Empty when the subject is unknown.',
+        evoHeadArgs,
+        /** @type {(args: Ts<typeof evoHeadArgs>) => Effect<MemOp, ToolsCallResult>} */
+        (({ subject }) => step(
+            e.head(subject),
+            heads => pure(okResult(heads.join('\n'))),
+        )),
+    ),
+    toolEntry(
+        'evo_revision',
+        'Read one revision by hash, as JSON: `{ subject, parents, snapshot, generation, archived? }`. `parents[0]` is the mainline parent and every further entry is a merged-in branch; `parents` and `snapshot` come back in their canonical cBase32 spelling, so they compare directly against `evo_head` output. Errors when the hash is not cBase32, is not present in the store, could not be read, or does not hold a `vnd.fjs.revision` blob — use `cas_get` for raw bytes of non-revision content.',
+        evoRevisionArgs,
+        // The revision goes out as JSON in a text content item, like
+        // `evo_list`'s. An encoded response that outgrows the transport cap is
+        // the transport's `-32603`, not a tool-level error — see "Result size"
+        // in the module doc.
+        /** @type {(args: Ts<typeof evoRevisionArgs>) => Effect<O | MemOp, ToolsCallResult>} */
+        (({ hash }) => step(
+            e.revision(hash),
+            result => pure(result[0] === 'error' ? errorResult(result[1]) : okResult(toJson(result[1])))
+        )),
+    ),
+    toolEntry(
+        'evo_add',
+        'Add a new revision (a `vnd.fjs.revision` blob) and return its hash (cBase32). `subject` is required unless there is exactly one parent, from which it is inherited. `snapshot`, when omitted, is resolved from the parents (zero parents → `subject`, one parent → the parent\'s snapshot; a merge requires an explicit `snapshot`) and written explicitly. `generation` is computed by the server.',
+        evoAddArgs,
+        /** @type {(input: Ts<typeof evoAddArgs>) => Effect<O | MemOp, ToolsCallResult>} */
+        (input => step(
+            e.add(input),
+            result => pure(result[0] === 'error' ? errorResult(result[1]) : okResult(result[1]))
+        )),
+    ),
+]

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

@@ -0,0 +1,17 @@
+/**
+ * @import { Evo } from '../../cas/evo/types.ts'
+ * @import { ToolEntry, ToolsCallResult } from '../../protocol/mcp/types.ts'
+ * @import { Operation } from '../../effects/types.ts'
+ */
+export declare const proof: {
+    toolNamesMatchTheDesign: () => void;
+    evoListReflectsTheCache: () => void;
+    evoListEncodesArbitrarySubjectsAsJson: () => void;
+    evoListForwardsTheArchivedFilter: () => void;
+    evoHeadReflectsTheCache: () => void;
+    evoHeadMissingSubjectIsInvalidArguments: () => void;
+    evoRevisionReturnsRevisionJson: () => void;
+    evoRevisionDomainErrorIsError: () => void;
+    evoAddSuccessReturnsHash: () => void;
+    evoAddDomainErrorIsError: () => void;
+};

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

@@ -0,0 +1,166 @@
+/**
+ * @import { Evo } from '../../cas/evo/types.ts'
+ * @import { ToolEntry, ToolsCallResult } from '../../protocol/mcp/types.ts'
+ * @import { Operation } from '../../effects/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 { 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 { 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'
+import { unwrap } from '../../types/result/module.f.mjs'
+
+const home = '/home/user'
+
+const parseSubjects = rttiParse(array(rttiString))
+
+/**
+ * @template {Operation} O
+ * @param {readonly ToolEntry<O>[]} registry
+ * @param {string} name
+ * @returns {ToolEntry<O>}
+ */
+const findEntry = (registry, name) => {
+    const entry = registry.find(e => e.name === name)
+    assert(entry !== undefined, ['missing tool entry', name])
+    return /** @type {ToolEntry<O>} */ (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
+}
+
+export const proof = {
+    toolNamesMatchTheDesign: () => {
+        /** @type {Evo<never>} */
+        const e = {
+            list: () => { throw 'unused' },
+            head: () => { throw 'unused' },
+            add: () => { throw 'unused' },
+            revision: () => { throw 'unused' },
+        }
+        assertEq(evoToolRegistry(e).map(entry => entry.name).join(','), 'evo_list,evo_head,evo_revision,evo_add')
+    },
+    evoListReflectsTheCache: () => {
+        const c = fileCas(sha256)(home)
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c))
+        const e = evo(c)(cacheKey)
+        const entry = findEntry(evoToolRegistry(e), 'evo_list')
+        const [, result] = virtual(state0)(entry.handle({}))
+        assert(!result.isError)
+        assertEq(textOf(result), '[]')
+    },
+    // Regression: subjects are arbitrary strings, not constrained to a
+    // newline-free alphabet like hashes, so evo_list must not join them with
+    // '\n' — a subject containing a newline, or an empty subject, would be
+    // indistinguishable from multiple/no subjects in that format. JSON
+    // encoding preserves both exactly.
+    evoListEncodesArbitrarySubjectsAsJson: () => {
+        const c = fileCas(sha256)(home)
+        const [state0, cacheKey] = 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 entry = findEntry(evoToolRegistry(e), 'evo_list')
+        const [, result] = virtual(state2)(entry.handle({}))
+        assert(!result.isError)
+        const subjects = unwrap(parseSubjects(unwrap(parseJson(textOf(result)))))
+        assertEq(subjects.length, 2)
+        assert(subjects.includes('line one\nline two'), ['unexpected subjects', subjects])
+        assert(subjects.includes(''), ['unexpected subjects', subjects])
+    },
+    // The `archived` argument is a pass-through to `Evo.list`'s status filter:
+    // omitted lists the active subjects, `true` the archived ones.
+    evoListForwardsTheArchivedFilter: () => {
+        const c = fileCas(sha256)(home)
+        const [state0, cacheKey] = 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 entry = findEntry(evoToolRegistry(e), 'evo_list')
+        const [state2, active] = virtual(state1)(entry.handle({}))
+        assert(!active.isError)
+        assertEq(textOf(active), '[]')
+        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 e = evo(c)(cacheKey)
+        const entry = findEntry(evoToolRegistry(e), 'evo_head')
+        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 e = evo(c)(cacheKey)
+        const entry = findEntry(evoToolRegistry(e), 'evo_head')
+        const [, result] = virtual(state0)(entry.handle({}))
+        assertEq(result.isError, true)
+    },
+    // Covers evo_revision's success branch: the stored revision comes back as
+    // the JSON of `RevisionData` — `dialect` dropped, `generation` and the
+    // resolved `snapshot` included.
+    evoRevisionReturnsRevisionJson: () => {
+        const c = fileCas(sha256)(home)
+        const [state0, cacheKey] = 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 entry = findEntry(evoToolRegistry(e), 'evo_revision')
+        const [, result] = virtual(state1)(entry.handle({ hash: added[1] }))
+        assert(!result.isError)
+        assertEq(textOf(result), `{"subject":"${subject}","parents":[],"snapshot":"${subject}","generation":0}`)
+    },
+    // Covers evo_revision's error branch: a domain-level failure (a hash the
+    // 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 e = evo(c)(cacheKey)
+        const entry = findEntry(evoToolRegistry(e), 'evo_revision')
+        const [, result] = virtual(state0)(entry.handle({ hash: vecToCBase32(vec8(0x4n)) }))
+        assertEq(result.isError, true)
+        assert(textOf(result).includes('revision not found'))
+    },
+    // Covers evo_add's success branch: a valid revision is stored and its
+    // hash comes back as plain, non-error text.
+    evoAddSuccessReturnsHash: () => {
+        const c = fileCas(sha256)(home)
+        const [state0, cacheKey] = 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))
+        assert(!result.isError)
+        assert(textOf(result).length > 0)
+    },
+    // 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 e = evo(c)(cacheKey)
+        const entry = findEntry(evoToolRegistry(e), 'evo_add')
+        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

@@ -0,0 +1,67 @@
+/**
+ * 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 { 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 { 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';
+/**
+ * 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
+ * `initEvo`).
+ * @type {(home: string) => (cacheKey: Key<Cache>) => McpHandlers<FileCasOperation | MemOp>}
+ */
+export declare const casMcpHandlers: (home: string) => (cacheKey: Key<Cache>) => McpHandlers<FileCasOperation | MemOp>;
+/**
+ * Static MCP configuration for the CAS server: advertises the `tools`
+ * capability, identifies the server, and pins the protocol version.
+ * @type {McpConfig}
+ */
+export declare const casConfig: McpConfig;
+/**
+ * Runs the combined CAS + Evo MCP server over stdio: scans `~/.cas/` once to
+ * 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>}
+ */
+export declare const casMcpServer: (home: string) => Effect<Read | Write | MemOp | FileCasOperation, void>;
+export declare const proof: {
+    casMcpServer: () => void;
+};

package/fjs/mcp/module.f.mjs

@@ -0,0 +1,98 @@
+/**
+ * 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 { 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 { create } from '../effects/memory/module.f.mjs'
+import { stdioTransport } from '../protocol/mcp/stdio/module.f.mjs'
+import {
+    mcpStep, uninitializedState, fromRegistry,
+} from '../protocol/mcp/module.f.mjs'
+import { fileCas } from '../cas/module.f.mjs'
+import { initEvo, evo } from '../cas/evo/module.f.mjs'
+import { sha256 } from '../crypto/sha2/module.f.mjs'
+import { casToolRegistry } from './cas/module.f.mjs'
+import { evoToolRegistry } from './evo/module.f.mjs'
+
+// ── Handlers ────────────────────────────────────────────────────────────────────
+
+/**
+ * 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
+ * `initEvo`).
+ * @type {(home: string) => (cacheKey: Key<Cache>) => McpHandlers<FileCasOperation | MemOp>}
+ */
+export const casMcpHandlers = home => cacheKey =>
+    fromRegistry([...casToolRegistry(home)(cacheKey), ...evoToolRegistry(evo(fileCas(sha256)(home))(cacheKey))])
+
+// ── Session configuration ───────────────────────────────────────────────────────
+
+/**
+ * Static MCP configuration for the CAS server: advertises the `tools`
+ * capability, identifies the server, and pins the protocol version.
+ * @type {McpConfig}
+ */
+export const casConfig = {
+    serverInfo: { name: 'functionalscript-cas', version: '0.30.0' },
+    capabilities: { tools: {} },
+    protocolVersion: '2024-11-05',
+}
+
+// ── Server ──────────────────────────────────────────────────────────────────────
+
+/**
+ * Runs the combined CAS + Evo MCP server over stdio: scans `~/.cas/` once to
+ * 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>}
+ */
+export const casMcpServer = home => step(
+    initEvo(fileCas(sha256)(home)),
+    cacheKey => step(
+        create(uninitializedState),
+        sessionKey =>
+            stdioTransport(mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey)),
+    ),
+)
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+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.
+    casMcpServer: () => { casMcpServer('/') },
+}

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

@@ -0,0 +1,56 @@
+/**
+ * @import { Unknown } from '../media/json/types.ts'
+ * @import { Effect, Operation } from '../effects/types.ts'
+ * @import { Response } from '../protocol/json_rpc/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 { Dir } from '../effects/node/virtual/types.ts'
+ */
+export declare const proof: {
+    getMetaLargeMultiChunkBlobNoError: () => void;
+    getMetaLargeMultiChunkUtf8Symbols: () => void;
+    getMetaLargeMultiChunkTextThenBinary: () => void;
+    getContentLargeBlobTooLargeError: () => void;
+    getContentMissingHashIsError: () => void;
+    getContentBase64InflationOverflowWritesInternalError: () => void;
+    getContentBase64NearBoundarySucceeds: () => void;
+    getContentDoubleEscapedOverflowWritesInternalError: () => void;
+    toolsListAdvertisesSevenTools: () => void;
+    evoAddListHeadRoundTripsThroughCasServer: () => void;
+    evoAddDomainErrorIsErrorThroughCasServer: () => void;
+    casAddSyncsEvoCacheForRevisionContent: () => void;
+    addReturnsHash: () => void;
+    textAddGetMetaRoundTrips: () => void;
+    textAddGetContentRoundTrips: () => void;
+    binaryAddGetMetaRoundTrips: () => void;
+    binaryAddGetContentRoundTrips: () => void;
+    addGetRoundTrips: () => void;
+    getUntypedReturnsText: () => void;
+    getTypedReturnsBinaryJson: () => void;
+    getMetaRecognizesRevisionDialect: () => void;
+    getContentRecognizesRevisionDialect: () => void;
+    listEnumeratesStoredHashes: () => void;
+    addInvalidContentIsError: () => void;
+    addBadLengthContentIsError: () => void;
+    addBase64OverLimitIsError: () => void;
+    addTextOverLimitIsError: () => void;
+    addTextAtLimitSucceeds: () => void;
+    addBase64AtLimitSucceeds: () => void;
+    getUnterminatedHashIsError: () => void;
+    addMissingContentIsError: () => void;
+    getMissingHashArgumentIsError: () => void;
+    getInvalidHashIsError: () => void;
+    getMissingHashIsError: () => void;
+    unknownToolIsError: () => void;
+    toolErrorIsNotJsonRpcError: () => void;
+    getMetaReturnsLengthAndMimeType: () => void;
+    getMetaBinaryBlob: () => void;
+    getMetaOctetStreamForUnknownBinary: () => void;
+    getMetaOctetStreamForNulBlob: () => void;
+    getMetaMissingHashIsError: () => void;
+    getMetaInvalidHashIsError: () => void;
+    getOctetStreamWithContentIncludesBase64: () => void;
+};