functionalscript 0.39.0 → 0.41.0

package/fjs/mcp/proof.f.js

@@ -1,208 +1,516 @@
 import { assert, assertEq } from '../asserts/module.f.js';
 import { pure, step } from '../effects/module.f.js';
-import { eff } from '../effects/eff/module.f.js';
-import { run } from '../effects/mock/module.f.js';
-import { asBase, asNominal, create, read } from '../effects/memory/module.f.js';
-import { uninitializedState, mcpStep, notInitialized, } from './module.f.js';
-const initial = { next: 0, values: {} };
-const mock = {
-    memCreate: value => state => {
-        const id = `k${state.next}`;
-        const key = asNominal(id);
-        return [{ next: state.next + 1, values: { ...state.values, [id]: value } }, key];
-    },
-    memRead: key => state => [state, state.values[asBase(key)]],
-    memWrite: (key, value) => state => {
-        const id = asBase(key);
-        return [{ ...state, values: { ...state.values, [id]: value } }, undefined];
-    },
+import { 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 '../cas/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 '../protocol/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 '../protocol/mcp/stdio/module.f.js';
+import { fromVec } from '../types/uint8array/module.f.js';
+import { initEvo } from '../cas/evo/module.f.js';
+// ── Session driver ──────────────────────────────────────────────────────────────
+// Feeds each message to `handler` in order, collecting every response.
+const feed = (handler) => (msgs) => {
+    const go = (i, acc) => i === msgs.length
+        ? pure(acc)
+        : step(handler(msgs[i]), r => go(i + 1, [...acc, r]));
+    return go(0, []);
+};
+// Runs a session backed by the virtual node runner (for cas_upload which uses
+// 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 = step(initEvo(fileCas(sha256)(home)), cacheKey => step(create(uninitializedState), sessionKey => {
+        const step = mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey);
+        return feed(step)(msgs);
+    }));
+    return virtual({ ...emptyState, root })(effect)[1];
+};
+// Seeds a blob directly into the virtual store via `c.write`, bypassing the
+// MCP `cas_add` tool entirely — used by tests that need a stored blob larger
+// than `cas_add`'s inline limit, now that the removed `type:'url'` path is no
+// longer available to stage one through MCP. Returns the resulting root
+// `Dir` (with the new shard written) and the blob's cBase32 hash so a
+// subsequent `runSessionVirtual` call can read it back via `cas_get`.
+const seedBlob = (root, home = '/home/user') => (chunks) => {
+    const c = fileCas(sha256)(home);
+    const stream = chunks.reduceRight((tail, chunk) => nonEmpty(resultOk(chunk), tail), elEmpty());
+    const [state, result] = virtual({ ...emptyState, root })(c.write(stream));
+    assert(result[0] === 'ok', result);
+    return [state.root, vecToCBase32(result[1])];
 };
-// ── Fixtures ──────────────────────────────────────────────────────────────────
-const config = {
-    serverInfo: { name: 'test-server', version: '0.1.0' },
-    capabilities: { tools: {} },
-    protocolVersion: '2024-11-05',
+// ── Messages ────────────────────────────────────────────────────────────────────
+const init = { jsonrpc: '2.0', method: 'initialize', id: 1,
+    params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'c', version: '0' } } };
+const initialized = { jsonrpc: '2.0', method: 'notifications/initialized' };
+const call = (id, name, args) => ({ jsonrpc: '2.0', method: 'tools/call', id, params: { name, arguments: args } });
+const list = (id) => ({ jsonrpc: '2.0', method: 'tools/list', id });
+// Runs `init`, `notifications/initialized`, then `msgs`; returns the tool responses.
+const session = (...msgs) => runSessionVirtual({}, '/home/user')([init, initialized, ...msgs]).slice(2);
+// UTF-8 bytes of `s` as a plain array — the virtual stdin byte stream.
+const toBytes = (s) => [...fromVec(utf8(s))];
+// Runs `init`, `notifications/initialized`, then `msgs` through the *real*
+// stdio pipeline — `mcpStep` wrapped in `stdioTransport`, driving
+// `writeResponse`'s `tryUtf8` encode over actual stdin/stdout bytes. Unlike
+// `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
+// `fjs/protocol/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 = step(initEvo(fileCas(sha256)(home)), cacheKey => step(create(uninitializedState), 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.
+    return stdout.split('\n').filter(line => line.length > 0).slice(1).map(line => JSON.parse(line));
 };
-const configNoTools = { ...config, capabilities: {} };
-const handlers = {
-    // Echoes a received cursor as `nextCursor` so tests can observe pagination params.
-    toolsList: (p) => pure(p.cursor === undefined
-        ? { tools: [{ name: 'greet', inputSchema: {} }] }
-        : { tools: [], nextCursor: p.cursor }),
-    toolsCall: (_p) => pure({ content: [{ type: 'text', text: 'hello' }] }),
+const resultOf = (resp) => resp.result;
+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 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
+// don't rely on the correctness of the function they're indirectly exercising
+// (`cas_add` decodes the string via `base64.decode`). Handles every n%3
+// residue: rem=0 → no padding, rem=1 → 'AA==', rem=2 → 'AAA='.
+const base64OfA = (n) => {
+    const groups = Number(n / 3n);
+    const rem = Number(n % 3n);
+    const body = 'AAAA'.repeat(groups);
+    if (rem === 0) {
+        return body;
+    }
+    if (rem === 1) {
+        return body + 'AA==';
+    }
+    return body + 'AAA=';
 };
-// Run a memory effect against the mock, return the result.
-const runMem = (effect) => run(mock)(initial)(effect)[1];
-// TypeScript infers O = Operation (the upper bound) rather than O = never when
-// O flows through McpHandlers<never>, so we cast the widened type down to MemOp.
-const asMemEffect = (e) => e;
-// Run one step from uninitializedState, return [response, newState].
-const step1 = (cfg) => (msg) => runMem(asMemEffect(step(create(uninitializedState), key => step(mcpStep(cfg)(handlers)(key)(msg), resp => step(read(key), state => pure([resp, state]))))));
-// Run initialize then a second step, return [response, newState] of the second.
-const step2 = (cfg) => (msg1) => (msg2) => runMem(asMemEffect(eff(create(uninitializedState)).step(key => eff(mcpStep(cfg)(handlers)(key)(msg1)).step(() => eff(mcpStep(cfg)(handlers)(key)(msg2)).step(resp => step(read(key), state => pure([resp, state]))).value).value).value));
-// Run initialize, notifications/initialized, then a third step; return [response, newState] of the third.
-const step3 = (cfg) => (msg1) => (msg2) => (msg3) => runMem(asMemEffect(eff(create(uninitializedState)).step(key => eff(mcpStep(cfg)(handlers)(key)(msg1)).step(() => eff(mcpStep(cfg)(handlers)(key)(msg2)).step(() => eff(mcpStep(cfg)(handlers)(key)(msg3)).step(resp => eff(read(key)).step(state => pure([resp, state])).value).value).value).value).value));
-// ── Test messages ─────────────────────────────────────────────────────────────
-const initMsg = { jsonrpc: '2.0', method: 'initialize', id: 1,
-    params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'client', version: '0.0.1' } } };
-const initNotif = { jsonrpc: '2.0', method: 'notifications/initialized' };
-// ── Tests ─────────────────────────────────────────────────────────────────────
+// ── Tests ───────────────────────────────────────────────────────────────────────
+// A blob larger than one read chunk (> 128 KiB) used to fail metadata-only
+// cas_get because `collectRead` overflowed `maxLength`. With `detectStream`,
+// content:false returns correct metadata regardless of size. Each chunk is
+// exactly `maxLengthBytes` (the largest single `Vec` the runtime allows), so the
+// two-chunk blob spans two read chunks without any one `Vec` exceeding the cap.
+const largeMultiChunkBlobMeta = (chunk0, chunk1, expectedType, expectedMime) => () => {
+    const [root, hash] = seedBlob({})([chunk0, chunk1]);
+    const [metaResp] = runSessionVirtual(root)([
+        init, initialized,
+        call(2, 'cas_get', { hash }),
+    ]).slice(2);
+    assert(!resultOf(metaResp).isError);
+    const meta = JSON.parse(textOf(metaResp));
+    assertEq(meta.type, expectedType);
+    assertEq(meta.mimeType, expectedMime);
+    assertEq(meta.length, Number((length(chunk0) + length(chunk1)) / 8n));
+    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));
+// The same length, but repeated 2-byte "é" (C3 A9) — valid UTF-8 of multi-byte symbols.
+const symbolChunk = repeat(maxLengthBytes / 2n)(u8ListToVec(msb)([0xc3, 0xa9]));
+// A full chunk of 0xFF — an invalid UTF-8 lead byte, so binary (no magic match).
+const binaryChunk = repeat(maxLengthBytes)(vec8(0xffn));
+// 100,000 raw bytes of 0xFF: comfortably under `maxLengthBytes` (so `cas_get`'s
+// own `length > maxLengthBytes` guard does not fire), but base64 inflates it to
+// ceil(100_000/3)*4 = 133,336 chars — already past `maxLength` (131,072 bytes)
+// before the JSON-RPC envelope adds anything.
+const oversizedBase64Chunk = repeat(100000n)(vec8(0xffn));
+// 90,000 raw bytes: base64 inflates to 120,000 chars, leaving ~11 KiB of margin
+// under `maxLength` once the envelope is added — the paired "still succeeds" case.
+const boundaryBase64Chunk = repeat(90000n)(vec8(0xffn));
+// 33,000 `"` bytes (0x22): valid UTF-8, so `cas_get` classifies it as text and
+// takes the double-JSON-escaping path (`toJson` builds the inner CAS JSON, then
+// the outer `stringifyJson` embeds that as the `text` field). Each quote costs
+// 4 final bytes (2 on each escaping pass), so 33,000 of them alone push the
+// encoded line past `maxLength` (131,072 bytes) — well above the strict 32,769
+// minimum needed, without approaching any other size-related edge case.
+const quotesChunk = repeat(33000n)(vec8(0x22n));
 export const proof = {
-    lifecycle: {
-        initialStateIsUninitialized: () => {
-            assert(uninitializedState[0] === 'uninitialized');
-        },
-        initializeTransitionsToInitializing: () => {
-            const [, newState] = step1(config)(initMsg);
-            assert(newState[0] === 'initializing');
-        },
-        initializedNotificationTransitionsToInitialized: () => {
-            const [resp, newState] = step2(config)(initMsg)(initNotif);
-            assertEq(resp, null);
-            assert(newState[0] === 'initialized');
-        },
-        initializeReturnsResult: () => {
-            const [resp] = step1(config)(initMsg);
-            assert(resp !== null && typeof resp === 'object' && 'result' in resp);
-            const r = resp.result;
-            assertEq(r.protocolVersion, '2024-11-05');
-        },
-        initializeWithBadParamsReturnsInvalidParams: () => {
-            const bad = { jsonrpc: '2.0', method: 'initialize', id: 2, params: { wrong: true } };
-            const [resp, newState] = step1(config)(bad);
-            assert(newState[0] === 'uninitialized');
-            assertEq(resp.error.code, -32602);
-        },
-        notificationBeforeInitReturnNull: () => {
-            const [resp, newState] = step1(config)(initNotif);
-            assert(newState[0] === 'uninitialized');
-            assertEq(resp, null);
-        },
-        unknownNotificationReturnNull: () => {
-            const notif = { jsonrpc: '2.0', method: 'notifications/unknown' };
-            const [resp] = step2(config)(initMsg)(notif);
-            assertEq(resp, null);
-        },
-        doubleInitializeReturnsInvalidRequest: () => {
-            const [resp, newState] = step2(config)(initMsg)(initMsg);
-            assert(newState[0] === 'initializing');
-            assertEq(resp.error.code, -32600);
-        },
-        pingBeforeInitSucceeds: () => {
-            const msg = { jsonrpc: '2.0', method: 'ping', id: 11 };
-            const [resp, newState] = step1(config)(msg);
-            assert(newState[0] === 'uninitialized');
-            assert(!('error' in resp));
-        },
-        pingDuringInitializingSucceeds: () => {
-            const msg = { jsonrpc: '2.0', method: 'ping', id: 12 };
-            const [resp, newState] = step2(config)(initMsg)(msg);
-            assert(newState[0] === 'initializing');
-            assert(!('error' in resp));
-        },
-        pingAfterInitSucceeds: () => {
-            const msg = { jsonrpc: '2.0', method: 'ping', id: 15 };
-            const [resp] = step3(config)(initMsg)(initNotif)(msg);
-            assert(!('error' in resp));
-        },
-        pingWithObjectParamsSucceeds: () => {
-            const msg = { jsonrpc: '2.0', method: 'ping', id: 19, params: {} };
-            const [resp] = step1(config)(msg);
-            assert(!('error' in resp));
-        },
-        pingInvalidParamsReturnsInvalidParams: () => {
-            const msg = { jsonrpc: '2.0', method: 'ping', id: 20, params: 1 };
-            const [resp] = step1(config)(msg);
-            assertEq(resp.error.code, -32602);
-        },
-        initializedNotificationObjectParamsTransitions: () => {
-            const notif = { jsonrpc: '2.0', method: 'notifications/initialized', params: {} };
-            const [resp, newState] = step2(config)(initMsg)(notif);
-            assertEq(resp, null);
-            assert(newState[0] === 'initialized');
-        },
-        initializedNotificationBadParamsIgnored: () => {
-            const notif = { jsonrpc: '2.0', method: 'notifications/initialized', params: 1 };
-            const [resp, newState] = step2(config)(initMsg)(notif);
-            assertEq(resp, null);
-            assert(newState[0] === 'initializing');
-        },
-        methodBeforeInitReturnsNotInitialized: () => {
-            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 3 };
-            const [resp, newState] = step1(config)(msg);
-            assert(newState[0] === 'uninitialized');
-            assertEq(resp.error.code, notInitialized.code);
-        },
-        methodDuringInitializingReturnsNotInitialized: () => {
-            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 16 };
-            const [resp, newState] = step2(config)(initMsg)(msg);
-            assert(newState[0] === 'initializing');
-            assertEq(resp.error.code, notInitialized.code);
-        },
-        invalidEnvelopeReturnsInvalidRequest: () => {
-            const bad = { jsonrpc: '1.0', method: 'ping', id: 4 };
-            const [resp] = step1(config)(bad);
-            assertEq(resp.error.code, -32600);
-            assertEq(resp.id, null);
-        },
-    },
-    tools: {
-        toolsListSucceeds: () => {
-            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 5 };
-            const [resp] = step3(config)(initMsg)(initNotif)(msg);
-            assertEq(resp.result.tools.length, 1);
-            assertEq(resp.result.tools[0].name, 'greet');
-        },
-        toolsListPassesCursorToHandler: () => {
-            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 17,
-                params: { cursor: 'page-2' } };
-            const [resp] = step3(config)(initMsg)(initNotif)(msg);
-            assertEq(resp.result.nextCursor, 'page-2');
-        },
-        toolsListInvalidCursorReturnsInvalidParams: () => {
-            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 18,
-                params: { cursor: 42 } };
-            const [resp] = step3(config)(initMsg)(initNotif)(msg);
-            assertEq(resp.error.code, -32602);
-        },
-        toolsCallSucceeds: () => {
-            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 6,
-                params: { name: 'greet', arguments: {} } };
-            const [resp] = step3(config)(initMsg)(initNotif)(msg);
-            assertEq(resp.result.content[0].text, 'hello');
-        },
-        toolsCallBadParamsReturnsInvalidParams: () => {
-            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 7, params: { missing: true } };
-            const [resp] = step3(config)(initMsg)(initNotif)(msg);
-            assertEq(resp.error.code, -32602);
-        },
-        toolsCallAbsentArgumentsSucceeds: () => {
-            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 13,
-                params: { name: 'greet' } };
-            const [resp] = step3(config)(initMsg)(initNotif)(msg);
-            assertEq(resp.result.content[0].text, 'hello');
-        },
-        toolsCallNullArgumentsReturnsInvalidParams: () => {
-            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 14,
-                params: { name: 'greet', arguments: null } };
-            const [resp] = step3(config)(initMsg)(initNotif)(msg);
-            assertEq(resp.error.code, -32602);
-        },
-        toolsListWithoutCapabilityReturnsMethodNotFound: () => {
-            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 8 };
-            const [resp] = step3(configNoTools)(initMsg)(initNotif)(msg);
-            assertEq(resp.error.code, -32601);
-        },
-        toolsCallWithoutCapabilityReturnsMethodNotFound: () => {
-            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 9,
-                params: { name: 'greet', arguments: {} } };
-            const [resp] = step3(configNoTools)(initMsg)(initNotif)(msg);
-            assertEq(resp.error.code, -32601);
-        },
-        unknownMethodReturnsMethodNotFound: () => {
-            const msg = { jsonrpc: '2.0', method: 'resources/list', id: 10 };
-            const [resp] = step3(config)(initMsg)(initNotif)(msg);
-            assertEq(resp.error.code, -32601);
-        },
+    // Both chunks repeated ASCII → text/plain, no error on a > 128 KiB blob.
+    getMetaLargeMultiChunkBlobNoError: largeMultiChunkBlobMeta(asciiChunk, asciiChunk, 'text', 'text/plain'),
+    // Both chunks valid UTF-8 sequences of multi-byte symbols → text/plain.
+    getMetaLargeMultiChunkUtf8Symbols: largeMultiChunkBlobMeta(symbolChunk, symbolChunk, 'text', 'text/plain'),
+    // First chunk valid UTF-8, second chunk binary → base64/octet-stream. The
+    // streaming validator must see the trailing binary chunk to reject text.
+    getMetaLargeMultiChunkTextThenBinary: largeMultiChunkBlobMeta(asciiChunk, binaryChunk, 'base64', 'application/octet-stream'),
+    // content:true on a present blob larger than `maxLength` reports a distinct
+    // "too large" error, not "no such hash" — the blob exists, it just can't be
+    // buffered inline. The metadata-only path (above) still returns its size/type.
+    getContentLargeBlobTooLargeError: () => {
+        const [root, hash] = seedBlob({})([asciiChunk, asciiChunk]);
+        const [getResp] = runSessionVirtual(root)([
+            init, initialized,
+            call(2, 'cas_get', { hash, content: true }),
+        ]).slice(2);
+        assertEq(resultOf(getResp).isError, true);
+        const text = textOf(getResp);
+        assert(text.includes('too large'));
+        assert(!text.includes('no such hash'));
+    },
+    // content:true on a genuinely absent hash still reports "no such hash" — the
+    // oversized branch above must not absorb the absent case.
+    getContentMissingHashIsError: () => {
+        const absent = vecToCBase32(vec8(0x55n));
+        const [resp] = session(call(2, 'cas_get', { hash: absent, content: true }));
+        assertEq(resultOf(resp).isError, true);
+        assert(textOf(resp).includes('no such hash'));
+    },
+    // A blob at exactly `maxLengthBytes` passes cas_get's own raw-length guard
+    // (it checks the *stored* size, not the encoded response), but base64
+    // inflation of a 100,000-byte blob alone already exceeds `maxLength` before
+    // 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 `fjs/protocol/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
+    // `fjs/basen/base64/proof.f.ts` `encodeLargeVecIsSlow`). Now well under budget on
+    // both engines.
+    getContentBase64InflationOverflowWritesInternalError: () => {
+        const [root, hash] = seedBlob({})([oversizedBase64Chunk]);
+        const [getResp] = runStdio(root)([
+            call(2, 'cas_get', { hash, content: true }),
+        ]);
+        const err = getResp;
+        assertEq(err.error?.code, -32603);
+        assertEq(err.id, 2);
+    },
+    // The paired boundary case: a blob whose base64 inflation leaves enough
+    // margin under `maxLength` for the envelope — confirms the fallback above
+    // only triggers on genuine overflow, not on every `content:true` binary read.
+    getContentBase64NearBoundarySucceeds: () => {
+        const [root, hash] = seedBlob({})([boundaryBase64Chunk]);
+        const [getResp] = runStdio(root)([
+            call(2, 'cas_get', { hash, content: true }),
+        ]);
+        assert(!resultOf(getResp).isError);
+        const result = JSON.parse(textOf(getResp));
+        assertEq(result.type, 'base64');
+        assertEq(result.length, 90_000);
+    },
+    // A text blob made entirely of `"` characters keeps the *raw* content
+    // (33,000 bytes) well under `maxLengthBytes`, but each quote costs 2 bytes on
+    // the inner CAS-JSON escape and 4 bytes once the outer JSON-RPC envelope
+    // re-escapes that backslash-quote pair — no `cas_get`-level size guard could
+    // see this coming, only the transport's real encode attempt can. Seeded
+    // directly into the store via `seedBlob` (not an inlined `cas_add` JSON
+    // string) so the test exercises `cas_get`'s response-side escaping without
+    // also paying for parsing a huge inline `content` argument on the request
+    // side. Confirms `writeResponse`'s
+    // `tryUtf8` fallback (not a crash) handles double-escaping overflow, again
+    // preserving the request's `id`.
+    getContentDoubleEscapedOverflowWritesInternalError: () => {
+        const [root, hash] = seedBlob({})([quotesChunk]);
+        const [getResp] = runStdio(root)([
+            call(2, 'cas_get', { hash, content: true }),
+        ]);
+        const err = getResp;
+        assertEq(err.error?.code, -32603);
+        assertEq(err.id, 2);
+    },
+    toolsListAdvertisesSevenTools: () => {
+        const [resp] = runSessionVirtual({})([init, initialized, list(2)]).slice(2);
+        const tools = resp.result.tools;
+        assertEq(tools.length, 7);
+        assertEq(tools.map(t => t.name).join(','), 'cas_add,cas_get,cas_list,evo_list,evo_head,evo_revision,evo_add');
+        const add = 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);
+        assert(textOf(resp).length > 0);
+    },
+    // Text add→get round-trip: store as UTF-8 text, retrieve metadata.
+    textAddGetMetaRoundTrips: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: textSample }));
+        const hash = textOf(addResp);
+        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.mimeType, 'text/plain');
+        assertEq(result.type, 'text');
+        assertEq(result.length, textSample.length);
+        assertEq(result.text, undefined);
+    },
+    // cas_get with content:true returns inline content.
+    textAddGetContentRoundTrips: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: textSample }));
+        const hash = textOf(addResp);
+        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.type, 'text');
+        assertEq(result.mimeType, 'text/plain');
+        assertEq(result.text, textSample);
+    },
+    // Binary add→get round-trip: store as base64, retrieve metadata without content.
+    binaryAddGetMetaRoundTrips: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: binarySample, type: 'base64' }));
+        const hash = textOf(addResp);
+        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.text, undefined);
+        assertEq(result.type, 'text');
+        assertEq(result.mimeType, 'text/plain');
+    },
+    // Binary add→get with content:true returns inline base64 content.
+    binaryAddGetContentRoundTrips: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: binarySample, type: 'base64' }));
+        const hash = textOf(addResp);
+        const [, getResp] = session(call(2, 'cas_add', { content: binarySample, type: 'base64' }), call(3, 'cas_get', { hash, content: true }));
+        assert(!resultOf(getResp).isError);
+        const result = JSON.parse(textOf(getResp));
+        assertEq(result.type, 'text');
+        assertEq(result.text, '*');
+    },
+    addGetRoundTrips: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: textSample }));
+        const hash = textOf(addResp);
+        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.text, textSample);
+    },
+    // Text content (no magic-byte match, valid UTF-8) comes back with type:'text' when content requested.
+    getUntypedReturnsText: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: textSample }));
+        const hash = textOf(addResp);
+        const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash, content: true }));
+        assertEq(item0(getResp) === null ? null : item0(getResp).type, 'text');
+        const result = JSON.parse(textOf(getResp));
+        assertEq(result.type, 'text');
+        assertEq(result.mimeType, 'text/plain');
+    },
+    // 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);
+        const [, getResp] = session(call(2, 'cas_add', { content: pngSample, type: 'base64' }), call(3, 'cas_get', { hash, content: true }));
+        assert(!resultOf(getResp).isError);
+        assertEq(item0(getResp).type, 'text');
+        const result = JSON.parse(textOf(getResp));
+        assertEq(result.type, 'base64');
+        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', {}));
+        const hash = textOf(addResp);
+        assert(!resultOf(listResp).isError);
+        assertEq(textOf(listResp), hash);
+    },
+    addInvalidContentIsError: () => {
+        const [resp] = session(call(2, 'cas_add', { content: 'not valid!', type: 'base64' }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    addBadLengthContentIsError: () => {
+        const [resp] = session(call(2, 'cas_add', { content: 'A', type: 'base64' }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    // 174_764 'A' chars × 6 bits = 1_048_584 bits, 8 over maxLength — base64Decode
+    // returns null and cas_add surfaces an error.
+    addBase64OverLimitIsError: () => {
+        const [resp] = session(call(2, 'cas_add', { content: 'A'.repeat(174_764), type: 'base64' }));
+        assertEq(resultOf(resp).isError, true);
+        assert(textOf(resp).includes('too large or malformed'));
+        assert(textOf(resp).includes('cas add'));
+    },
+    // One ASCII byte past maxLengthBytes — tryUtf8 returns null and cas_add
+    // surfaces an error.
+    addTextOverLimitIsError: () => {
+        const [resp] = session(call(2, 'cas_add', { content: 'a'.repeat(Number(maxLengthBytes) + 1) }));
+        assertEq(resultOf(resp).isError, true);
+        assert(textOf(resp).includes('too large or malformed'));
+        assert(textOf(resp).includes('cas add'));
+    },
+    // Exactly maxLengthBytes (131,072) ASCII bytes — tryUtf8 returns a non-null
+    // Vec (len === maxLength, not over), so cas_add stores cleanly.
+    addTextAtLimitSucceeds: () => {
+        const [resp] = session(call(2, 'cas_add', { content: 'a'.repeat(Number(maxLengthBytes)) }));
+        assert(!resultOf(resp).isError);
+        assert(textOf(resp).length > 0);
+    },
+    // 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' }));
+        assert(!resultOf(resp).isError);
+        assert(textOf(resp).length > 0);
+    },
+    getUnterminatedHashIsError: () => {
+        const [resp] = session(call(2, 'cas_get', { hash: '0' }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    addMissingContentIsError: () => {
+        const [resp] = session(call(2, 'cas_add', {}));
+        assertEq(resultOf(resp).isError, true);
+    },
+    getMissingHashArgumentIsError: () => {
+        const [resp] = session(call(2, 'cas_get', {}));
+        assertEq(resultOf(resp).isError, true);
+    },
+    getInvalidHashIsError: () => {
+        const [resp] = session(call(2, 'cas_get', { hash: 'not valid!' }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    getMissingHashIsError: () => {
+        const absent = vecToCBase32(vec8(0x99n));
+        const [resp] = session(call(2, 'cas_get', { hash: absent }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    unknownToolIsError: () => {
+        const [resp] = session(call(2, 'cas_remove', { hash: binarySample }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    toolErrorIsNotJsonRpcError: () => {
+        const [resp] = session(call(2, 'cas_add', { content: 'not valid!', type: 'base64' }));
+        assert(!('error' in resp));
+        assert('result' in resp);
+    },
+    // cas_get without content:true returns only metadata.
+    getMetaReturnsLengthAndMimeType: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: 'text content' }));
+        const hash = textOf(addResp);
+        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.mimeType, 'text/plain');
+        assertEq(meta.type, 'text');
+        assertEq(meta.length, 12);
+        assertEq(meta.text, undefined);
+    },
+    getMetaBinaryBlob: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: pngSample, type: 'base64' }));
+        const hash = textOf(addResp);
+        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.mimeType, 'image/png');
+        assertEq(meta.type, 'base64');
+        assertEq(meta.length, 10);
+        assertEq(meta.blob, undefined);
+    },
+    getMetaOctetStreamForUnknownBinary: () => {
+        const binaryContent = u8ListToVec(msb)([0xFF, 0xFE, 0x00, 0x01]);
+        const binaryB64 = base64Encode(binaryContent);
+        const [addResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }));
+        const hash = textOf(addResp);
+        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.mimeType, 'application/octet-stream');
+        assertEq(meta.type, 'base64');
+        assertEq(meta.blob, undefined);
+    },
+    // A NUL-bearing blob is valid UTF-8 yet binary: cas_get must report
+    // base64/octet-stream, not text/plain.
+    getMetaOctetStreamForNulBlob: () => {
+        const nulContent = u8ListToVec(msb)([0x00, 0x00, 0x00]);
+        const nulB64 = base64Encode(nulContent);
+        const [addResp] = session(call(2, 'cas_add', { content: nulB64, type: 'base64' }));
+        const hash = textOf(addResp);
+        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.mimeType, 'application/octet-stream');
+        assertEq(meta.type, 'base64');
+    },
+    getMetaMissingHashIsError: () => {
+        const absent = vecToCBase32(vec8(0x77n));
+        const [resp] = session(call(2, 'cas_get', { hash: absent }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    getMetaInvalidHashIsError: () => {
+        const [resp] = session(call(2, 'cas_get', { hash: 'bad!' }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    // cas_get with content:true on octet-stream (no magic bytes, not UTF-8) returns inline base64.
+    getOctetStreamWithContentIncludesBase64: () => {
+        const binaryContent = u8ListToVec(msb)([0xFF, 0xFE, 0x00, 0x01]);
+        const binaryB64 = base64Encode(binaryContent);
+        const [addResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }));
+        const hash = textOf(addResp);
+        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.mimeType, 'application/octet-stream');
+        assertEq(result.type, 'base64');
+        assertEq(result.blob, binaryB64);
     },
 };