functionalscript 0.36.0 → 0.38.0

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

@@ -0,0 +1,267 @@
+/**
+ * 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
+ * (`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`).
+ *
+ * ## 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)                      |
+ *
+ * ## `cas_add` input encoding
+ *
+ * The optional `type` field controls how `content` is interpreted:
+ * - `'text'` (default, or omitted): `content` is a UTF-8 string stored as raw
+ *   bytes. Most agent-generated content (scripts, JSON, prompts) can be stored
+ *   without any encoding step.
+ * - `'base64'`: `content` is RFC 4648 base64, decoded to bytes before storage.
+ *   Use this for pre-encoded binary payloads.
+ *
+ * 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
+ * through the `cas` CLI (`cas add <path>`) instead, run directly by the user.
+ *
+ * ## `cas_get` output
+ *
+ * Always returns a JSON object `{ length, mimeType, type[, uri][, text | blob] }`.
+ * These field names mirror the MCP resource-contents shape (`resources/read`
+ * results), so the tool view and the future resource view of a blob use the same
+ * vocabulary: `mimeType` (not `mime_type`), `uri` (not `url`) — the resource URI
+ * under which the same blob will be readable via `resources/read` — and `text` /
+ * `blob` (not a `type`-tagged `content`) for inline payloads. `type` is always
+ * present (`'text'` or `'base64'`) as the discriminator for which of `text` /
+ * `blob` a later `content: true` fetch would populate — MCP allows extra fields,
+ * so `type` and `length` simply stay alongside the required resource-contents
+ * fields. A single classifier — the `fjs/media/type` detector state machine (length ×
+ * magic-byte eliminator × UTF-8 DFA) — produces the same three-way verdict on
+ * both paths, so there is no second, divergent copy of the rules:
+ *
+ * 1. **Magic-byte hit** (PNG/JPEG/GIF/WebP/PDF/ZIP) → `type: 'base64'` with the
+ *    detected `mimeType`.
+ * 2. **Whole-blob-valid UTF-8** → `type: 'text'`, `mimeType: 'text/plain'`.
+ * 3. **Fallback** → `type: 'base64'`, `mimeType: 'application/octet-stream'`.
+ *
+ * **Metadata-only (`content: false`, the default) is size-independent for
+ * non-text and oversized blobs.** It folds the read stream through
+ * `fjs/media/type` `detectStream` and never buffers the blob. Because a single
+ * `Vec` caps at `maxLength` bits (128 KiB), the old drain-into-one-`Vec`
+ * approach failed on any blob larger than one chunk even when only metadata
+ * was asked for; streaming detection returns correct
+ * `{ length, mimeType, type[, uri] }` regardless of size. A dialect (e.g.
+ * `vnd.fjs.revision`, see `fjs/media/module.f.ts`) can only be recognized by
+ * parsing the whole blob as JSON, so when the streaming verdict is
+ * whole-blob-valid text within the same bounded inline cap as `content: true`
+ * (`maxLengthBytes`), one extra bounded read materializes the blob purely to
+ * refine `mimeType` through the dialect-aware detector; a larger or non-text
+ * blob is never a dialect match and is returned from the streaming verdict
+ * alone, unbuffered.
+ *
+ * **`content: true`** first derives `{ length, mimeType, type }` with the same
+ * size-independent `fjs/media/type` `detectStream` machine (to decide whether the
+ * blob even fits inline), then materializes the bytes (via `collectRead`, bounded
+ * by `maxLength`) and re-derives the verdict from the dialect-aware detector
+ * (`fjs/media/module.f.ts` `detect`) — now that the whole blob is in hand, a
+ * dialect match is reflected in the result — before encoding the inline payload
+ * by `type` — a `fjs/text/utf8` `fromVec` string on `text` (for `type: 'text'`),
+ * base64 on `blob` (for `type: 'base64'`). A blob larger than `maxLength` (128
+ * KiB) cannot be buffered into one `Vec`, so it is rejected here with a
+ * descriptive *"too large"* error (carrying the byte size and `uri`) rather than
+ * being misreported as absent; it should be fetched via `uri` or inspected with
+ * metadata-only `cas_get`.
+ *
+ * ## Encoding split: hashes vs. content
+ *
+ * `Cas<O>` deals in `Vec` (bit vectors); MCP models only `textContent` today.
+ * **Hashes** travel as cBase32 (`fjs/basen/cbase32`) — the canonical CAS hash format,
+ * shared with the CLI and the on-disk store layout. **Content** encoding is
+ * determined at read time as described above.
+ *
+ * ## Error convention
+ *
+ * MCP draws a line the dispatcher already respects: *protocol* failures
+ * (unknown method, malformed JSON-RPC params) are JSON-RPC errors handled by
+ * `mcpStep`. *Tool* failures come back as a normal `tools/call` result with
+ * `isError: true` and a text explanation, so the model can read and react:
+ * - `type: 'base64'` with malformed content (base64 `decode` → `null`) → `isError`
+ * - malformed `hash` (`cBase32ToVec` → `null`) → `isError`
+ * - `cas_get` on an absent hash (`c.read` → `undefined`) → `isError`
+ * - `cas_get` with `content: true` on a blob larger than `maxLength` → `isError`
+ *   (distinct "too large" message, not "no such hash")
+ * - unknown tool `name` → `isError`
+ *
+ * @module
+ */
+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 { 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 { 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';
+// ── Argument schemas (declared once, used for both inputSchema and validate) ─────
+/** Arguments for `cas_add`: content to store, with optional encoding type. */
+export const casAddArgs = {
+    content: string,
+    type: or('text', 'base64', undefined)
+};
+/** Arguments for `cas_get`: the cBase32 hash to look up; optionally request inline content. */
+export const casGetArgs = {
+    hash: string,
+    content: option(boolean)
+};
+/** Arguments for `cas_list`: none. */
+export const casListArgs = {};
+// ── Tool registry ──────────────────────────────────────────────────────────────
+const toJson = stringify(identity);
+/**
+ * Registry of all CAS tools, bound to `home` and the Evo cache at
+ * `cacheKey`. `cas_add` is the only tool that writes, so it is the only one
+ * that needs `cacheKey`: a successfully stored blob is folded into the Evo
+ * cache via `syncRevision` when it happens to be a `vnd.fjs.revision` — a
+ * plain `cas_add` and `evo_add` are two ways to reach the same store, and
+ * this keeps `evo_list`/`evo_head` honest about either one without a
+ * rescan.
+ */
+export const casToolRegistry = (home) => (cacheKey) => {
+    const c = fileCas(sha256)(home);
+    return [
+        toolEntry('cas_add', 'Store content and return its hash (cBase32). Pass type:"base64" for binary; omit or pass type:"text" for UTF-8 text (default). Inline content is capped at 128 KiB (131072 bytes) — larger content is rejected. For larger content, store the file with the `cas` CLI instead: run `npx functionalscript cas add <path>` yourself if you have shell access, or give the user that exact command to run — it prints the resulting hash on stdout.', casAddArgs, ({ type, content }) => {
+            // type:'text' or 'base64' — resolve content to Vec, store via c.write()
+            let x = type === 'base64'
+                ? base64Decode(content)
+                : tryUtf8(content);
+            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) => {
+                    if (writeResult[0] === 'error') {
+                        return pure(errorResult('write'));
+                    }
+                    const hash = writeResult[1];
+                    return syncRevision(cacheKey)(hash)(x).step(() => 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 => {
+            const key = cBase32ToVec(r.hash);
+            if (key === null) {
+                return pure(errorResult(`invalid cBase32 hash: ${r.hash}`));
+            }
+            const uri = c.url(key);
+            return detectStream(c.read(key)).step(([tag, detected]) => {
+                if (tag === 'error') {
+                    return pure(errorResult(`no such hash: ${r.hash}`));
+                }
+                const { length, mime_type: mimeType, type } = detected;
+                const meta = { length: Number(length), mimeType, type, uri };
+                if (r.content !== true) {
+                    // A dialect match can only be decided from the whole parsed blob;
+                    // only attempt the extra bounded read when it stands a chance
+                    // (whole-blob text within the same cap `content: true` allows).
+                    if (type !== 'text' || length > maxLengthBytes) {
+                        return pure(okResult(toJson(meta)));
+                    }
+                    return collectRead(c.read(key)).step(([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.
+                        if (collectTag === 'error') {
+                            return pure(okResult(toJson(meta)));
+                        }
+                        const refined = detectDialect(value);
+                        return pure(okResult(toJson({ ...meta, mimeType: refined.mime_type })));
+                    });
+                }
+                // A single `Vec` caps at `maxLength` bits (`maxLengthBytes` bytes), so
+                // a larger blob cannot be buffered for inline transfer. Report the
+                // size and point at the size-independent alternatives instead of
+                // misreporting an existing blob as `no such hash`.
+                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]) => {
+                    if (collectTag === 'error') {
+                        return pure(errorResult(`no such hash: ${r.hash}`));
+                    }
+                    // Re-derive the verdict from the now-materialized blob so a
+                    // dialect match — only decidable with the whole parsed JSON in
+                    // hand — is reflected in the inline result too, not just the
+                    // streaming guess.
+                    const refined = detectDialect(value);
+                    const refinedMeta = { length: Number(refined.length), mimeType: refined.mime_type, type: refined.type, uri };
+                    if (refined.type === 'text') {
+                        // `type: 'text'` means the detector validated `value` as UTF-8,
+                        // so `fromVec` is non-null here; guard defensively regardless.
+                        const str = fromVec(value);
+                        return pure(str === null
+                            ? errorResult(`content is not byte-aligned: ${r.hash}`)
+                            : okResult(toJson({ ...refinedMeta, text: str })));
+                    }
+                    const blob = base64Encode(value);
+                    return pure(blob === null
+                        ? errorResult(`content is not byte-aligned: ${r.hash}`)
+                        : okResult(toJson({ ...refinedMeta, blob })));
+                });
+            });
+        }),
+        toolEntry('cas_list', 'List all stored content hashes (cBase32), one per line.', casListArgs, () => c.list().step(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/{fs → fjs}/cas/mcp/proof.f.d.ts

@@ -7,7 +7,10 @@ export declare const proof: {
     getContentBase64InflationOverflowWritesInternalError: () => void;
     getContentBase64NearBoundarySucceeds: () => void;
     getContentDoubleEscapedOverflowWritesInternalError: () => void;
-    toolsListAdvertisesThreeTools: () => void;
+    toolsListAdvertisesSixTools: () => void;
+    evoAddListHeadRoundTripsThroughCasServer: () => void;
+    evoAddDomainErrorIsErrorThroughCasServer: () => void;
+    casAddSyncsEvoCacheForRevisionContent: () => void;
     addReturnsHash: () => void;
     textAddGetMetaRoundTrips: () => void;
     textAddGetContentRoundTrips: () => void;
@@ -16,13 +19,15 @@ export declare const proof: {
     addGetRoundTrips: () => void;
     getUntypedReturnsText: () => void;
     getTypedReturnsBinaryJson: () => void;
+    getMetaRecognizesRevisionDialect: () => void;
+    getContentRecognizesRevisionDialect: () => void;
     listEnumeratesStoredHashes: () => void;
     addInvalidContentIsError: () => void;
     addBadLengthContentIsError: () => void;
     addBase64OverLimitIsError: () => void;
     addTextOverLimitIsError: () => void;
     addTextAtLimitSucceeds: () => void;
-    addBase64AtLimitIsError: () => void;
+    addBase64AtLimitSucceeds: () => void;
     getUnterminatedHashIsError: () => void;
     addMissingContentIsError: () => void;
     getMissingHashArgumentIsError: () => void;

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

@@ -1,20 +1,22 @@
-import { assert, assertEq } from "../../asserts/module.f.js";
-import { pure } from "../../effects/module.f.js";
-import { run } from "../../effects/mock/module.f.js";
-import { asBase, asNominal, create } from "../../effects/memory/module.f.js";
-import { msb, u8ListToVec, vec8, repeat, length, maxLengthBytes } from "../../types/bit_vec/module.f.js";
-import { vecToCBase32 } from "../../cbase32/module.f.js";
-import { encode as base64Encode } from "../../base64/module.f.js";
-import { utf8 } from "../../text/module.f.js";
-import { fileCas } from "../module.f.js";
-import { sha256 } from "../../crypto/sha2/module.f.js";
-import { nonEmpty, empty as elEmpty } from "../../effects/list/module.f.js";
-import { mcpStep, uninitializedState, } from "../../mcp/module.f.js";
-import { emptyState, virtual } from "../../effects/node/virtual/module.f.js";
-import { casConfig, casMcpHandlers } from "./module.f.js";
-import { ok as resultOk } from "../../types/result/module.f.js";
-import { stdioTransport } from "../../mcp/stdio/module.f.js";
-import { fromVec } from "../../types/uint8array/module.f.js";
+import { assert, assertEq } from '../../asserts/module.f.js';
+import { pure } from '../../effects/module.f.js';
+import { run } from '../../effects/mock/module.f.js';
+import { asBase, asNominal, create } from '../../effects/memory/module.f.js';
+import { msb, u8ListToVec, vec8, repeat, length, maxLengthBytes } from '../../types/bit_vec/module.f.js';
+import { vecToCBase32 } from '../../basen/cbase32/module.f.js';
+import { encode as base64Encode } from '../../basen/base64/module.f.js';
+import { utf8 } from '../../text/module.f.js';
+import { fileCas } from '../module.f.js';
+import { dialect as revisionDialect, mediaType as revisionMediaType } from '../../media/revision/module.f.js';
+import { sha256 } from '../../crypto/sha2/module.f.js';
+import { nonEmpty, empty as elEmpty } from '../../effects/list/module.f.js';
+import { mcpStep, uninitializedState, } from '../../mcp/module.f.js';
+import { emptyState, virtual } from '../../effects/node/virtual/module.f.js';
+import { casConfig, casMcpHandlers } from './module.f.js';
+import { ok as resultOk } from '../../types/result/module.f.js';
+import { stdioTransport } from '../../mcp/stdio/module.f.js';
+import { fromVec } from '../../types/uint8array/module.f.js';
+import { initEvo } from '../evo/module.f.js';
 const initialTestState = { memory: { next: 0, values: {} } };
 const mock = {
     memCreate: value => state => {
@@ -55,10 +57,10 @@ const feed = (step) => (msgs) => {
 // Rename/ReadBytes/RandomInt/Mkdir). Uses fileKvStore so upload and get share
 // the same filesystem-backed CAS.
 const runSessionVirtual = (root, home = '/home/user') => (msgs) => {
-    const effect = create(uninitializedState).step(sessionKey => {
-        const step = mcpStep(casConfig)(casMcpHandlers(home))(sessionKey);
+    const effect = initEvo(fileCas(sha256)(home)).step(cacheKey => create(uninitializedState).step(sessionKey => {
+        const step = mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey);
         return feed(step)(msgs);
-    });
+    }));
     return virtual({ ...emptyState, root })(effect)[1];
 };
 // Seeds a blob directly into the virtual store via `c.write`, bypassing the
@@ -90,10 +92,10 @@ const toBytes = (s) => [...fromVec(utf8(s))];
 // `session`/`runSessionVirtual`, which collect `mcpStep`'s `Response` values
 // as plain JS objects and never serialize/encode them, this is the only
 // helper that can observe the transport's oversized-response fallback (see
-// `fs/mcp/stdio/module.f.ts` `writeResponse`).
+// `fjs/mcp/stdio/module.f.ts` `writeResponse`).
 const runStdio = (root, home = '/home/user') => (msgs) => {
     const input = [init, initialized, ...msgs].map(m => JSON.stringify(m)).join('\n') + '\n';
-    const effect = create(uninitializedState).step(sessionKey => stdioTransport(mcpStep(casConfig)(casMcpHandlers(home))(sessionKey)));
+    const effect = initEvo(fileCas(sha256)(home)).step(cacheKey => create(uninitializedState).step(sessionKey => stdioTransport(mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey))));
     const stdout = virtual({ ...emptyState, root, stdin: toBytes(input) })(effect)[0].stdout;
     // Only requests get a written line (notifications, like `initialized`,
     // write nothing) — drop the `init` response, keep one line per `msgs` entry.
@@ -104,10 +106,13 @@ const item0 = (resp) => resultOf(resp).content[0];
 const textOf = (resp) => item0(resp).text;
 // A plain text sample for text add→get round-trips.
 const textSample = 'hello, world!';
+// A valid `vnd.fjs.revision` blob: every required field present, including the
+// explicit `snapshot` and `generation` the format now mandates.
+const revisionSample = `{"dialect":"${revisionDialect}","subject":"8","parents":[],"snapshot":"8","generation":0}`;
 // A base64-encoded binary payload for binary add→get round-trips.
 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 mime_type image/png.
+// `cas_get` detects its type and returns base64 with mimeType image/png.
 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
@@ -141,9 +146,10 @@ const largeMultiChunkBlobMeta = (chunk0, chunk1, expectedType, expectedMime) =>
     assert(!resultOf(metaResp).isError);
     const meta = JSON.parse(textOf(metaResp));
     assertEq(meta.type, expectedType);
-    assertEq(meta.mime_type, expectedMime);
+    assertEq(meta.mimeType, expectedMime);
     assertEq(meta.length, Number((length(chunk0) + length(chunk1)) / 8n));
-    assertEq(meta.content, undefined);
+    assertEq(meta.text, undefined);
+    assertEq(meta.blob, undefined);
 };
 // A full `maxLengthBytes`-long chunk of repeated ASCII 'a' — valid UTF-8.
 const asciiChunk = repeat(maxLengthBytes)(vec8(0x61n));
@@ -202,12 +208,12 @@ export const proof = {
     // the JSON-RPC envelope is even added. The transport's `writeResponse`
     // (`tryUtf8`) must catch this and write a JSON-RPC internal-error response —
     // carrying the *original request's* `id` — instead of crashing the process.
-    // See `fs/mcp/stdio/module.f.ts` `writeResponse`.
+    // See `fjs/mcp/stdio/module.f.ts` `writeResponse`.
     //
     // This test originally timed out under `bun test`'s native 5s per-test
     // limit (12-14s observed in CI on PR #1201) — the cost was in
     // `base64Encode`, quadratic before the `baseN.vecToString` fix (see
-    // `fs/base64/proof.f.ts` `encodeLargeVecIsSlow`). Now well under budget on
+    // `fjs/basen/base64/proof.f.ts` `encodeLargeVecIsSlow`). Now well under budget on
     // both engines.
     getContentBase64InflationOverflowWritesInternalError: () => {
         const [root, hash] = seedBlob({})([oversizedBase64Chunk]);
@@ -251,14 +257,41 @@ export const proof = {
         assertEq(err.error?.code, -32603);
         assertEq(err.id, 2);
     },
-    toolsListAdvertisesThreeTools: () => {
+    toolsListAdvertisesSixTools: () => {
         const [resp] = runSessionVirtual({})([init, initialized, list(2)]).slice(2);
         const tools = resp.result.tools;
-        assertEq(tools.length, 3);
-        assertEq(tools.map(t => t.name).join(','), 'cas_add,cas_get,cas_list');
+        assertEq(tools.length, 6);
+        assertEq(tools.map(t => t.name).join(','), 'cas_add,cas_get,cas_list,evo_list,evo_head,evo_add');
         const add = resp.result.tools[0];
         assertEq(add.inputSchema.type, 'object');
     },
+    // The same server also exposes Evo (fjs/cas/evo): add a revision, then
+    // find it via evo_list/evo_head — one process, one store, one cache.
+    evoAddListHeadRoundTripsThroughCasServer: () => {
+        const [addResp, listResp, headResp] = session(call(2, 'evo_add', { parents: [], subject: 'doc', snapshot: vecToCBase32(vec8(0x1n)) }), call(3, 'evo_list', {}), call(4, 'evo_head', { subject: 'doc' }));
+        assert(!resultOf(addResp).isError);
+        const hash = textOf(addResp);
+        assert(hash.length > 0);
+        assertEq(textOf(listResp), '["doc"]');
+        assertEq(textOf(headResp), hash);
+    },
+    evoAddDomainErrorIsErrorThroughCasServer: () => {
+        // Valid arguments, but the domain rule fails: `subject` is required
+        // unless there is exactly one parent.
+        const [resp] = session(call(2, 'evo_add', { parents: [] }));
+        assertEq(resultOf(resp).isError, true);
+        assert(textOf(resp).includes('subject is required'));
+    },
+    // A plain `cas_add` of `vnd.fjs.revision` content is folded into the Evo
+    // cache too (`syncRevision`), not just `evo_add` — `cas_add`/`evo_add`
+    // are two ways to reach the same store and cache.
+    casAddSyncsEvoCacheForRevisionContent: () => {
+        const [addResp, listResp, headResp] = session(call(2, 'cas_add', { content: revisionSample }), call(3, 'evo_list', {}), call(4, 'evo_head', { subject: '8' }));
+        assert(!resultOf(addResp).isError);
+        const hash = textOf(addResp);
+        assertEq(textOf(listResp), '["8"]');
+        assertEq(textOf(headResp), hash);
+    },
     addReturnsHash: () => {
         const [resp] = session(call(2, 'cas_add', { content: textSample }));
         assert(!resultOf(resp).isError);
@@ -271,10 +304,10 @@ export const proof = {
         const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash }));
         assert(!resultOf(getResp).isError);
         const result = JSON.parse(textOf(getResp));
-        assertEq(result.mime_type, 'text/plain');
+        assertEq(result.mimeType, 'text/plain');
         assertEq(result.type, 'text');
         assertEq(result.length, textSample.length);
-        assertEq(result.content, undefined);
+        assertEq(result.text, undefined);
     },
     // cas_get with content:true returns inline content.
     textAddGetContentRoundTrips: () => {
@@ -284,8 +317,8 @@ export const proof = {
         assert(!resultOf(getResp).isError);
         const result = JSON.parse(textOf(getResp));
         assertEq(result.type, 'text');
-        assertEq(result.mime_type, 'text/plain');
-        assertEq(result.content, textSample);
+        assertEq(result.mimeType, 'text/plain');
+        assertEq(result.text, textSample);
     },
     // Binary add→get round-trip: store as base64, retrieve metadata without content.
     binaryAddGetMetaRoundTrips: () => {
@@ -294,9 +327,9 @@ export const proof = {
         const [, getResp] = session(call(2, 'cas_add', { content: binarySample, type: 'base64' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(getResp).isError);
         const result = JSON.parse(textOf(getResp));
-        assertEq(result.content, undefined);
+        assertEq(result.text, undefined);
         assertEq(result.type, 'text');
-        assertEq(result.mime_type, 'text/plain');
+        assertEq(result.mimeType, 'text/plain');
     },
     // Binary add→get with content:true returns inline base64 content.
     binaryAddGetContentRoundTrips: () => {
@@ -306,7 +339,7 @@ export const proof = {
         assert(!resultOf(getResp).isError);
         const result = JSON.parse(textOf(getResp));
         assertEq(result.type, 'text');
-        assertEq(result.content, '*');
+        assertEq(result.text, '*');
     },
     addGetRoundTrips: () => {
         const [addResp] = session(call(2, 'cas_add', { content: textSample }));
@@ -314,7 +347,7 @@ export const proof = {
         const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash, content: true }));
         assert(!resultOf(getResp).isError);
         const result = JSON.parse(textOf(getResp));
-        assertEq(result.content, textSample);
+        assertEq(result.text, textSample);
     },
     // Text content (no magic-byte match, valid UTF-8) comes back with type:'text' when content requested.
     getUntypedReturnsText: () => {
@@ -324,9 +357,9 @@ export const proof = {
         assertEq(item0(getResp) === null ? null : item0(getResp).type, 'text');
         const result = JSON.parse(textOf(getResp));
         assertEq(result.type, 'text');
-        assertEq(result.mime_type, 'text/plain');
+        assertEq(result.mimeType, 'text/plain');
     },
-    // Bytes with a recognised PNG signature come back as base64 with mime_type image/png when content requested.
+    // Bytes with a recognised PNG signature come back as base64 with mimeType image/png when content requested.
     getTypedReturnsBinaryJson: () => {
         const [addResp] = session(call(2, 'cas_add', { content: pngSample, type: 'base64' }));
         const hash = textOf(addResp);
@@ -335,8 +368,33 @@ export const proof = {
         assertEq(item0(getResp).type, 'text');
         const result = JSON.parse(textOf(getResp));
         assertEq(result.type, 'base64');
-        assertEq(result.mime_type, 'image/png');
-        assertEq(result.content, pngSample);
+        assertEq(result.mimeType, 'image/png');
+        assertEq(result.blob, pngSample);
+    },
+    // A stored `vnd.fjs.revision` blob is recognized by metadata-only
+    // `cas_get` (content:false, the default) — the CAS read path routes the
+    // bounded, whole-blob-text case through the dialect-aware detector rather
+    // than only reporting the streaming text/plain verdict.
+    getMetaRecognizesRevisionDialect: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: revisionSample }));
+        const hash = textOf(addResp);
+        const [, metaResp] = session(call(2, 'cas_add', { content: revisionSample }), call(3, 'cas_get', { hash }));
+        assert(!resultOf(metaResp).isError);
+        const meta = JSON.parse(textOf(metaResp));
+        assertEq(meta.mimeType, revisionMediaType);
+        assertEq(meta.type, 'text');
+    },
+    // Same dialect recognition on the `content: true` path, alongside the
+    // inline text payload.
+    getContentRecognizesRevisionDialect: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: revisionSample }));
+        const hash = textOf(addResp);
+        const [, getResp] = session(call(2, 'cas_add', { content: revisionSample }), call(3, 'cas_get', { hash, content: true }));
+        assert(!resultOf(getResp).isError);
+        const result = JSON.parse(textOf(getResp));
+        assertEq(result.mimeType, revisionMediaType);
+        assertEq(result.type, 'text');
+        assertEq(result.text, revisionSample);
     },
     listEnumeratesStoredHashes: () => {
         const [addResp, listResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_list', {}));
@@ -375,16 +433,14 @@ export const proof = {
         assert(!resultOf(resp).isError);
         assert(textOf(resp).length > 0);
     },
-    // base64 of exactly maxLengthBytes — currently returns isError because
-    // base64Decode measures the raw pre-trim body (1_048_578 bits) against
-    // maxLength before stripping the 2 padding bits that would land it exactly at
-    // maxLength. Assert the current failing behavior; flip to a success assertion
-    // once `fs/base64/todo/decode-rejects-max-size-input.md` is fixed.
-    addBase64AtLimitIsError: () => {
+    // base64 of exactly maxLengthBytes — base64Decode trims the encoding's
+    // padding bits from the last character before measuring the result
+    // against maxLength, so a payload landing exactly at the limit decodes
+    // and stores cleanly.
+    addBase64AtLimitSucceeds: () => {
         const [resp] = session(call(2, 'cas_add', { content: base64OfA(maxLengthBytes), type: 'base64' }));
-        assertEq(resultOf(resp).isError, true);
-        assert(textOf(resp).includes('too large or malformed'));
-        assert(textOf(resp).includes('cas add'));
+        assert(!resultOf(resp).isError);
+        assert(textOf(resp).length > 0);
     },
     getUnterminatedHashIsError: () => {
         const [resp] = session(call(2, 'cas_get', { hash: '0' }));
@@ -423,10 +479,10 @@ export const proof = {
         const [, metaResp] = session(call(2, 'cas_add', { content: 'text content' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
         const meta = JSON.parse(textOf(metaResp));
-        assertEq(meta.mime_type, 'text/plain');
+        assertEq(meta.mimeType, 'text/plain');
         assertEq(meta.type, 'text');
         assertEq(meta.length, 12);
-        assertEq(meta.content, undefined);
+        assertEq(meta.text, undefined);
     },
     getMetaBinaryBlob: () => {
         const [addResp] = session(call(2, 'cas_add', { content: pngSample, type: 'base64' }));
@@ -434,10 +490,10 @@ export const proof = {
         const [, metaResp] = session(call(2, 'cas_add', { content: pngSample, type: 'base64' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
         const meta = JSON.parse(textOf(metaResp));
-        assertEq(meta.mime_type, 'image/png');
+        assertEq(meta.mimeType, 'image/png');
         assertEq(meta.type, 'base64');
         assertEq(meta.length, 10);
-        assertEq(meta.content, undefined);
+        assertEq(meta.blob, undefined);
     },
     getMetaOctetStreamForUnknownBinary: () => {
         const binaryContent = u8ListToVec(msb)([0xFF, 0xFE, 0x00, 0x01]);
@@ -447,9 +503,9 @@ export const proof = {
         const [, metaResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
         const meta = JSON.parse(textOf(metaResp));
-        assertEq(meta.mime_type, 'application/octet-stream');
+        assertEq(meta.mimeType, 'application/octet-stream');
         assertEq(meta.type, 'base64');
-        assertEq(meta.content, undefined);
+        assertEq(meta.blob, undefined);
     },
     // A NUL-bearing blob is valid UTF-8 yet binary: cas_get must report
     // base64/octet-stream, not text/plain.
@@ -461,7 +517,7 @@ export const proof = {
         const [, metaResp] = session(call(2, 'cas_add', { content: nulB64, type: 'base64' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
         const meta = JSON.parse(textOf(metaResp));
-        assertEq(meta.mime_type, 'application/octet-stream');
+        assertEq(meta.mimeType, 'application/octet-stream');
         assertEq(meta.type, 'base64');
     },
     getMetaMissingHashIsError: () => {
@@ -482,8 +538,8 @@ export const proof = {
         const [, getResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }), call(3, 'cas_get', { hash, content: true }));
         assert(!resultOf(getResp).isError);
         const result = JSON.parse(textOf(getResp));
-        assertEq(result.mime_type, 'application/octet-stream');
+        assertEq(result.mimeType, 'application/octet-stream');
         assertEq(result.type, 'base64');
-        assertEq(result.content, binaryB64);
+        assertEq(result.blob, binaryB64);
     },
 };