functionalscript 0.38.0 → 0.40.0

package/fjs/emergent_testing/proof.f.js

@@ -218,41 +218,72 @@ export const githubReporterOutput = () => {
     assertEq(exit, 1);
     assertEq(stderr, '::error file=./s.proof.f.ts,line=1,title=import("./s.proof.f.ts").proof["a%3Ab%2Cc%25d"]()::oops\n');
 };
-// registerModule appends ' ...' for inline runners (Bun/Playwright).
-// Uses a minimal synchronous mock for the Test/All/Await effect operations.
-export const registerSuffixes = () => {
+const registerNoopCtx = { test: (_n, _o, _f) => Promise.resolve() };
+/**
+ * Builds a synchronous mock runner for `registerModule`'s `Test`/`All`/`Await`
+ * effect operations. Only the `test` op varies between call sites (whether it
+ * invokes the registered callback), so `all`/`await` are shared here.
+ */
+const makeRegisterRunner = (testOp) => {
     let runner;
-    const noopCtx = { test: (_n, _o, _f) => Promise.resolve() };
-    const makeRunner = () => mockRun({
-        test: (_ctx, name, _xf, _fn) => (s) => [[...s, name], undefined],
-        all: (...effects) => (s) => {
-            let st = s;
-            const rs = [];
-            for (const e of effects) {
-                const [ns, r] = runner(st)(e);
-                st = ns;
-                rs.push(r);
-            }
-            return [st, rs];
-        },
-        await: p => (s) => [s, [p]],
+    runner = mockRun({
+        test: (ctx, name, xf, fn) => testOp(runner, ctx, name, xf, fn),
+        all: (...effects) => (s) => effects.reduce(([st, rs], e) => {
+            const [ns, r] = runner(st)(e);
+            return [ns, [...rs, r]];
+        }, [s, []]),
+        await: (p) => (s) => [s, [p]],
     });
-    runner = makeRunner();
+    return runner;
+};
+// registerModule appends ' ...' for inline runners (Bun).
+// This mock never invokes the registered callback; it only records names.
+export const registerSuffixes = () => {
+    const runner = makeRegisterRunner((_runner, _ctx, name, _xf, _fn) => (s) => [[...s, name], undefined]);
     const proof = {
         ok: () => { },
         throw: { a: () => { throw 'expected'; } },
     };
     // Node (star = ''): no suffixes
-    const [nodeNames] = runner([])(registerModule(noopCtx, './a.f.ts', proof, ''));
+    const [nodeNames] = runner([])(registerModule(registerNoopCtx, './a.f.ts', proof, ''));
     assertEq(nodeNames.length, 2);
     assert(nodeNames[0] === 'import("./a.f.ts").proof.ok()');
     assertEq(nodeNames[1], 'import("./a.f.ts").proof.throw.a()');
-    // Bun/Playwright (star = ' ...'): ... on normal tests, path shows throw for throw-tests
-    const [inlineNames] = runner([])(registerModule(noopCtx, './a.f.ts', proof, ' ...'));
+    // Bun (star = ' ...'): ... on normal tests, path shows throw for throw-tests
+    const [inlineNames] = runner([])(registerModule(registerNoopCtx, './a.f.ts', proof, ' ...'));
     assertEq(inlineNames.length, 2);
     assert(inlineNames[0] === 'import("./a.f.ts").proof.ok() ...');
     assertEq(inlineNames[1], 'import("./a.f.ts").proof.throw.a()');
 };
+// A `throw`-tagged test whose function completes without throwing (the
+// external framework, not this module, is responsible for turning that into
+// a failure via `expectFailure`). registerModule's own callback must still
+// short-circuit before walking the returned value for sub-tests: it invokes
+// the callback and returns without recursing, rather than treating the
+// returned object as a sub-tree.
+export const registerThrowsWithoutThrowing = () => {
+    // Unlike registerSuffixes' mock, this one actually invokes the registered
+    // callback so registerOne's inner `.step` body runs, and asserts the
+    // callback is registered with `expectFailure: true`.
+    const runner = makeRegisterRunner((runner, ctx, name, xf, fn) => (s) => {
+        assert(xf);
+        const [ns] = runner(s)(fn(ctx));
+        return [[...ns, name], undefined];
+    });
+    // Returns a sub-tree that would register more tests if it were walked.
+    const proof = { throw: { a: () => ({ sub: () => { } }) } };
+    const [names] = runner([])(registerModule(registerNoopCtx, './a.f.ts', proof, ''));
+    // Only the throw-test itself is registered; `sub` is never reached.
+    assertEq(names.length, 1);
+    assertEq(names[0], 'import("./a.f.ts").proof.throw.a()');
+};
+// registerModule with an empty proof object registers zero tests and
+// returns without invoking the mock's `test` op at all.
+export const registerEmptyProof = () => {
+    const runner = makeRegisterRunner((_runner, _ctx, name, _xf, _fn) => (s) => [[...s, name], undefined]);
+    const [names] = runner([])(registerModule(registerNoopCtx, './a.f.ts', {}, ''));
+    assertEq(names.length, 0);
+};
 // direct unit tests for the pure path-format helpers
 export const helpers = {
     isInteger: () => {
@@ -361,6 +392,8 @@ export const proof = {
     defaultReporterFailOutput,
     githubReporterOutput,
     registerSuffixes,
+    registerThrowsWithoutThrowing,
+    registerEmptyProof,
     defaultReporterExpectedToThrow,
     helpers
 };

package/fjs/emergent_testing/scenarios/thenable.pass.js

@@ -1,6 +1,6 @@
 // A test that returns a thenable (Promise-like object, not a real Promise).
 // Per FunctionalScript convention, thenables are treated as plain values —
-// not awaited. Both sandbox (fjs) and registerModule (node/bun/deno/playwright)
+// not awaited. Both sandbox (fjs) and registerModule (node/bun/deno)
 // must exit 0: the thenable object is walked as a sub-tree whose only key
 // `then` is a function with parameters, so no leaf tests are found and the
 // test trivially passes.

package/fjs/fsc/module.f.js

@@ -7,7 +7,7 @@ import { strictEqual } from '../types/function/operator/module.f.js';
 import { merge as rangeMapMerge, fromRange, get, } from '../types/range_map/module.f.js';
 import { reduce as listReduce, toArray, map } from '../types/list/module.f.js';
 import { range as asciiRange } from '../text/ascii/module.f.js';
-import { fn } from '../types/function/module.f.js';
+import { flip, fn } from '../types/function/module.f.js';
 import { one } from '../types/range/module.f.js';
 import { assertEq } from '../asserts/module.f.js';
 const fromCharCode = String.fromCharCode;
@@ -31,17 +31,17 @@ const reduce = (a) => {
     });
     return toArray(listReduce(merge)(empty)(a));
 };
-const codePointRange = fromRange(def);
+const codePointRange = flip(fromRange(def));
 const range = fn(asciiRange).map(codePointRange).result;
 const rangeSet = (l) => (f) => {
-    const codePointRange = fromRange(def);
+    const codePointRange = flip(fromRange(def));
     const g = r => codePointRange(asciiRange(r))(f);
     return reduce(map(g)(l));
 };
 const create = (a) => {
     const i = reduce(a);
     const x = get(def);
-    return v => c => x(c)(i)(v)(c);
+    return v => c => x(i)(c)(v)(c);
 };
 export const terminal = -1;
 const toInit = () => () => [[], init];

package/fjs/fsm/module.f.js

@@ -51,5 +51,5 @@ const initialState = [''];
 const initialStateStringify = stringifyIdentity(initialState);
 export const dfa = grammar => addEntry(grammar)(initialState)({});
 const get = rangeMapGet(emptyStateStringify);
-const runOp = dfa => input => s => get(input)(dfa[s] ?? []);
+const runOp = dfa => input => s => get(dfa[s] ?? [])(input);
 export const run = (dfa) => (input) => foldScan(runOp(dfa))(initialStateStringify)(input);

package/fjs/js/tokenizer/module.f.d.ts

@@ -96,6 +96,7 @@ type ErrorMessage = '" are missing' | 'unescaped character' | 'invalid hex value
 export declare const isKeywordToken: (token: JsToken) => boolean;
 export declare const tokenize: (input: List<number>) => (path: string) => List<JsTokenWithMetadata>;
 export declare const proof: {
+    getOperatorTokenInvalid: () => void;
     throw: {
         unionConflict: () => void;
     };

package/fjs/js/tokenizer/module.f.js

@@ -27,7 +27,7 @@ leftSquareBracket, reverseSolidus, rightSquareBracket, lowLine,
 latinSmallLetterRange, latinSmallLetterA, latinSmallLetterB, latinSmallLetterE, latinSmallLetterF, latinSmallLetterN, latinSmallLetterR, latinSmallLetterT, latinSmallLetterU, 
 //
 leftCurlyBracket, rightCurlyBracket, dollarSign } from '../../text/ascii/module.f.js';
-import { todo } from '../../asserts/module.f.js';
+import { todo, assertEq } from '../../asserts/module.f.js';
 const { fromCharCode } = String;
 const rangeOneNine = range('19');
 const rangeSetNewLine = [
@@ -111,21 +111,20 @@ const rangeMapMerge = def => merge({
     equal: strictEqual,
     def,
 });
-const rangeFunc = r => f => def => fromRange(def)(r)(f);
+const rangeFunc = r => f => def => fromRange(def)(f)(r);
 const scanRangeOp = def => f => [f(def), scanRangeOp(def)];
 const reduceRangeMap = def => a => {
     const rm = scan(scanRangeOp(def))(a);
     return toArray(listReduce(rangeMapMerge(def))(empty)(rm));
 };
-const scanRangeSetOp = def => f => r => [fromRange(def)(r)(f), scanRangeSetOp(def)(f)];
+const scanRangeSetOp = def => f => r => [fromRange(def)(f)(r), scanRangeSetOp(def)(f)];
 const rangeSetFunc = rs => f => def => {
     const rm = scan(scanRangeSetOp(def)(f))(rs);
     return toArray(listReduce(rangeMapMerge(def))(empty)(rm));
 };
 const create = (def) => (a) => {
-    const i = reduceRangeMap(def)(a);
-    const x = get(def);
-    return v => c => x(c)(i)(v)(c);
+    const x = get(def)(reduceRangeMap(def)(a));
+    return v => c => x(c)(v)(c);
 };
 const digitToBigInt = d => BigInt(d - digit0);
 const startNumber = digit => ({ s: 1n, m: digitToBigInt(digit), f: 0, es: 1, e: 0 });
@@ -527,6 +526,14 @@ export const tokenize = input => path => {
     return flat(scan(flat([input /*satisfies List<CharCodeOrEof>*/, [null]])));
 };
 export const proof = {
+    // `getOperatorToken` is only ever called with a value already confirmed to be
+    // a known operator (`hasOperatorToken`, or a single char from `rangeOpStart`),
+    // so its `??` fallback is unreachable through `tokenize`. Call it directly
+    // with a non-operator string to cover that branch.
+    getOperatorTokenInvalid: () => {
+        const result = getOperatorToken('@');
+        assertEq(result.kind, 'error');
+    },
     throw: {
         // union throws when two distinct non-default handlers are merged for the same range;
         // this path is unreachable through the public API (no overlapping ranges in practice).

package/fjs/{cas/mcp → mcp/cas}/module.f.d.ts

@@ -1,9 +1,7 @@
-import { type Effect } from '../../effects/module.f.ts';
 import { type MemOp } from '../../effects/memory/module.f.ts';
-import { type Read, type Write } from '../../effects/node/module.f.ts';
-import { type McpConfig, type McpHandlers, type ToolEntry } from '../../mcp/module.f.ts';
-import { type FileCasOperation } from '../module.f.ts';
-import { type Cache } from '../evo/module.f.ts';
+import { type ToolEntry } from '../../protocol/mcp/module.f.ts';
+import { type FileCasOperation } from '../../cas/module.f.ts';
+import { type Cache } from '../../cas/evo/module.f.ts';
 import type { Key } from '../../effects/memory/module.f.ts';
 /** Arguments for `cas_add`: content to store, with optional encoding type. */
 export declare const casAddArgs: {
@@ -27,23 +25,3 @@ export declare const casListArgs: {};
  * rescan.
  */
 export declare const casToolRegistry: (home: string) => (cacheKey: Key<Cache>) => readonly ToolEntry<FileCasOperation | MemOp>[];
-/**
- * MCP handlers for `FileCas` plus the Evo API (`fjs/cas/evo`) layered on it,
- * bound to `home` and an already-built Evo cache slot (see `initEvo`).
- */
-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.
- */
-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.
- */
-export declare const casMcpServer: (home: string) => Effect<Read | Write | MemOp | FileCasOperation, void>;
-export declare const proof: {
-    casMcpServer: () => void;
-};

package/fjs/{cas/mcp → mcp/cas}/module.f.js

@@ -1,26 +1,21 @@
 /**
- * MCP adapter for the content-addressable store and the Evo API layered on
- * top of it.
- *
- * Maps `Cas<O>` operations onto MCP tools, so an agent that speaks MCP can
- * store a blob and get back its hash, fetch a blob by hash, and enumerate
- * what is stored — without shelling out to the `cas` CLI. The store itself
+ * The `cas_add` / `cas_get` / `cas_list` tool registry: maps `Cas<O>`
+ * operations onto MCP tools, so an agent that speaks MCP can store a blob and
+ * get back its hash, fetch a blob by hash, and enumerate what is stored —
+ * without shelling out to the `cas` CLI. The store itself
  * (`fjs/cas/module.f.ts`) stays transport-agnostic; this is an additional
- * front end alongside the CLI `main`. The same server also exposes
- * `fjs/cas/evo`'s subject/head API (`evo_list`/`evo_head`/`evo_add`,
- * `fjs/cas/evo/mcp`) — one process, one `~/.cas/` store, one in-memory Evo
- * cache scanned once at startup (`initEvo`).
+ * front end alongside the CLI `main`. This registry is one of the tool sets
+ * `fjs/mcp/module.f.ts` composes into the FJS MCP server — see that module
+ * for the full tool table (including `fjs/mcp/evo`'s `evo_*` tools) and the
+ * server entry point.
  *
  * ## 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`  | `{}`                                             | `e.list()`    | subjects, one per line              |
- * | `evo_head`  | `{ subject }`                                    | `e.head(...)` | head hashes, one per line           |
- * | `evo_add`   | `{ parents, snapshot?, subject?, archived? }`    | `e.add(...)`  | hash (cBase32)                      |
+ * | 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                |
  *
  * ## `cas_add` input encoding
  *
@@ -33,7 +28,7 @@
  *
  * Inline content (either encoding) is capped at 128 KiB (`maxLength`). There is
  * no MCP route for larger content — the server never opens a local path named by
- * the client (see the invariant in `fjs/cas/mcp/README.md`); large files go
+ * the client (see the invariant in `fjs/mcp/README.md`); large files go
  * through the `cas` CLI (`cas add <path>`) instead, run directly by the user.
  *
  * ## `cas_get` output
@@ -108,25 +103,22 @@
  */
 import { string, option, or, boolean } from '../../types/rtti/module.f.js';
 import { stringify } from '../../media/json/module.f.js';
-import { pure } from '../../effects/module.f.js';
-import { create } from '../../effects/memory/module.f.js';
+import { pure, step } from '../../effects/module.f.js';
+import {} from '../../effects/memory/module.f.js';
 import { cBase32ToVec, vecToCBase32 } from '../../basen/cbase32/module.f.js';
 import { decode as base64Decode, encode as base64Encode } from '../../basen/base64/module.f.js';
 import { tryUtf8 } from '../../text/module.f.js';
 import { detectStream } from '../../media/type/module.f.js';
 import { detect as detectDialect } from '../../media/module.f.js';
 import { maxLengthBytes } from '../../types/bit_vec/module.f.js';
-import { ok, error } from '../../types/result/module.f.js';
-import {} from '../../effects/node/module.f.js';
-import { stdioTransport } from '../../mcp/stdio/module.f.js';
-import { mcpStep, uninitializedState, toolEntry, fromRegistry, errorResult, okResult, } from '../../mcp/module.f.js';
-import { collectRead, fileCas } from '../module.f.js';
+import { ok } from '../../types/result/module.f.js';
+import { toolEntry, errorResult, okResult, } from '../../protocol/mcp/module.f.js';
+import { collectRead, fileCas } from '../../cas/module.f.js';
 import { fromVec } from '../../text/utf8/module.f.js';
 import { identity } from '../../types/function/module.f.js';
 import { sha256 } from '../../crypto/sha2/module.f.js';
 import { nonEmpty, empty as elEmpty } from '../../effects/list/module.f.js';
-import { initEvo, evo, syncRevision } from '../evo/module.f.js';
-import { evoToolRegistry } from '../evo/mcp/module.f.js';
+import { syncRevision } from '../../cas/evo/module.f.js';
 // ── Argument schemas (declared once, used for both inputSchema and validate) ─────
 /** Arguments for `cas_add`: content to store, with optional encoding type. */
 export const casAddArgs = {
@@ -162,12 +154,12 @@ export const casToolRegistry = (home) => (cacheKey) => {
             return x === null
                 ? pure(errorResult('too large or malformed — for large content, run `npx functionalscript cas add <path>` (or have the user run it) instead'))
                 // The resolved content fits in one chunk; feed it as a single-item stream.
-                : c.write(nonEmpty(ok(x), elEmpty())).step((writeResult) => {
+                : step(c.write(nonEmpty(ok(x), elEmpty())), (writeResult) => {
                     if (writeResult[0] === 'error') {
                         return pure(errorResult('write'));
                     }
                     const hash = writeResult[1];
-                    return syncRevision(cacheKey)(hash)(x).step(() => pure(okResult(vecToCBase32(hash))));
+                    return step(syncRevision(cacheKey)(hash)(x), () => pure(okResult(vecToCBase32(hash))));
                 });
         }),
         toolEntry('cas_get', 'Inspect a blob by hash. Always returns JSON {length,mimeType,type[,uri]} where type is "text" or "base64". Pass content:true to also include the inline payload as text (type:"text") or blob (type:"base64"), but content is capped at 128 KiB (131072 bytes) — a larger blob is rejected with an error. To download a blob, prefer the uri field returned in the result instead of requesting inline content.', casGetArgs, r => {
@@ -176,7 +168,7 @@ export const casToolRegistry = (home) => (cacheKey) => {
                 return pure(errorResult(`invalid cBase32 hash: ${r.hash}`));
             }
             const uri = c.url(key);
-            return detectStream(c.read(key)).step(([tag, detected]) => {
+            return step(detectStream(c.read(key)), ([tag, detected]) => {
                 if (tag === 'error') {
                     return pure(errorResult(`no such hash: ${r.hash}`));
                 }
@@ -189,7 +181,7 @@ export const casToolRegistry = (home) => (cacheKey) => {
                     if (type !== 'text' || length > maxLengthBytes) {
                         return pure(okResult(toJson(meta)));
                     }
-                    return collectRead(c.read(key)).step(([collectTag, value]) => {
+                    return step(collectRead(c.read(key)), ([collectTag, value]) => {
                         // Already known to fit from the streaming pass above, so an
                         // error here means the hash vanished between reads; fall back
                         // to the streaming verdict rather than fail the whole request.
@@ -207,7 +199,7 @@ export const casToolRegistry = (home) => (cacheKey) => {
                 if (length > maxLengthBytes) {
                     return pure(errorResult(`blob too large to fetch inline (${length} bytes, limit ${maxLengthBytes} bytes); use the uri field (${uri}) or omit content for metadata`));
                 }
-                return collectRead(c.read(key)).step(([collectTag, value]) => {
+                return step(collectRead(c.read(key)), ([collectTag, value]) => {
                     if (collectTag === 'error') {
                         return pure(errorResult(`no such hash: ${r.hash}`));
                     }
@@ -232,36 +224,6 @@ export const casToolRegistry = (home) => (cacheKey) => {
                 });
             });
         }),
-        toolEntry('cas_list', 'List all stored content hashes (cBase32), one per line.', casListArgs, () => c.list().step(hashes => pure(okResult(hashes.map(vecToCBase32).join('\n'))))),
+        toolEntry('cas_list', 'List all stored content hashes (cBase32), one per line.', casListArgs, () => step(c.list(), hashes => pure(okResult(hashes.map(vecToCBase32).join('\n'))))),
     ];
 };
-// ── Handlers ────────────────────────────────────────────────────────────────────
-/**
- * MCP handlers for `FileCas` plus the Evo API (`fjs/cas/evo`) layered on it,
- * bound to `home` and an already-built Evo cache slot (see `initEvo`).
- */
-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.
- */
-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.
- */
-export const casMcpServer = (home) => initEvo(fileCas(sha256)(home)).step(cacheKey => create(uninitializedState).step(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/evo/module.f.d.ts

@@ -0,0 +1,27 @@
+import { type Operation } from '../../effects/module.f.ts';
+import { type MemOp } from '../../effects/memory/module.f.ts';
+import { type ToolEntry } from '../../protocol/mcp/module.f.ts';
+import { type Evo } from '../../cas/evo/module.f.ts';
+/** Arguments for `evo_list`: none. */
+export declare const evoListArgs: {};
+/** Arguments for `evo_head`: the subject whose current heads are requested. */
+export declare const evoHeadArgs: {
+    readonly subject: import("../../types/rtti/module.f.ts").String;
+};
+/** Arguments for `evo_revision`: the hash of the revision to read. */
+export declare const evoRevisionArgs: {
+    readonly hash: import("../../types/rtti/module.f.ts").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/module.f.ts").Type1<"array", import("../../types/rtti/module.f.ts").String>;
+    readonly snapshot: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
+    readonly subject: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
+    readonly archived: import("../../types/rtti/module.f.ts").Or<readonly [true, undefined]>;
+};
+/** Registry of all Evo tools, bound to an `Evo<O>`. */
+export declare const evoToolRegistry: <O extends Operation>(e: Evo<O>) => readonly ToolEntry<O | MemOp>[];

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

@@ -0,0 +1,94 @@
+/**
+ * MCP tool definitions for the Evo API (`fjs/cas/evo/module.f.ts`): 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`     | `{}`                                          | `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 { string, option, array } from '../../types/rtti/module.f.js';
+import { pure, step } from '../../effects/module.f.js';
+import {} from '../../effects/memory/module.f.js';
+import { toolEntry, errorResult, okResult, } from '../../protocol/mcp/module.f.js';
+import { stringify } from '../../media/json/module.f.js';
+import { identity } from '../../types/function/module.f.js';
+import {} from '../../cas/evo/module.f.js';
+// ── Argument schemas (declared once, used for both inputSchema and validate) ─────
+/** Arguments for `evo_list`: none. */
+export const evoListArgs = {};
+/** Arguments for `evo_head`: the subject whose current heads are requested. */
+export const evoHeadArgs = {
+    subject: string,
+};
+/** Arguments for `evo_revision`: the hash of the revision to read. */
+export const evoRevisionArgs = {
+    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 = {
+    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>`. */
+export const evoToolRegistry = (e) => [
+    toolEntry('evo_list', 'List all subjects with at least one stored revision, as a JSON array of strings.', 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.
+    () => step(e.list(), 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, ({ 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.
+    ({ 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, (input) => step(e.add(input), result => pure(result[0] === 'error' ? errorResult(result[1]) : okResult(result[1])))),
+];

package/fjs/{cas/evo/mcp → mcp/evo}/proof.f.d.ts

@@ -4,6 +4,8 @@ export declare const proof: {
     evoListEncodesArbitrarySubjectsAsJson: () => void;
     evoHeadReflectsTheCache: () => void;
     evoHeadMissingSubjectIsInvalidArguments: () => void;
+    evoRevisionReturnsRevisionJson: () => void;
+    evoRevisionDomainErrorIsError: () => void;
     evoAddSuccessReturnsHash: () => void;
     evoAddDomainErrorIsError: () => void;
 };

package/fjs/{cas/evo/mcp → mcp/evo}/proof.f.js

@@ -1,10 +1,10 @@
-import { assert, assertEq } from '../../../asserts/module.f.js';
-import { fileCas } from '../../module.f.js';
-import { sha256 } from '../../../crypto/sha2/module.f.js';
-import { emptyState, virtual } from '../../../effects/node/virtual/module.f.js';
-import { vec8 } from '../../../types/bit_vec/module.f.js';
-import { vecToCBase32 } from '../../../basen/cbase32/module.f.js';
-import { initEvo, evo } from '../module.f.js';
+import { assert, assertEq } from '../../asserts/module.f.js';
+import { fileCas } from '../../cas/module.f.js';
+import { sha256 } from '../../crypto/sha2/module.f.js';
+import { emptyState, virtual } from '../../effects/node/virtual/module.f.js';
+import { vec8 } from '../../types/bit_vec/module.f.js';
+import { vecToCBase32 } from '../../basen/cbase32/module.f.js';
+import { initEvo, evo } from '../../cas/evo/module.f.js';
 import { evoToolRegistry } from './module.f.js';
 const home = '/home/user';
 const findEntry = (registry, name) => {
@@ -19,8 +19,13 @@ const textOf = (result) => {
 };
 export const proof = {
     toolNamesMatchTheDesign: () => {
-        const e = { list: () => { throw 'unused'; }, head: () => { throw 'unused'; }, add: () => { throw 'unused'; } };
-        assertEq(evoToolRegistry(e).map(entry => entry.name).join(','), 'evo_list,evo_head,evo_add');
+        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);
@@ -69,6 +74,32 @@ export const proof = {
         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: () => {