functionalscript 0.37.0 → 0.38.0

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

@@ -1,19 +1,26 @@
 /**
- * MCP adapter for the content-addressable store.
+ * 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
- * (`fs/cas/module.f.ts`) stays transport-agnostic; this is an additional
- * front end alongside the CLI `main`.
+ * (`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                |
+ * | 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
  *
@@ -26,7 +33,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 `fs/cas/mcp/README.md`); large files go
+ * 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
@@ -40,7 +47,7 @@
  * 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 `fs/media/type` detector state machine (length ×
+ * 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:
  *
@@ -51,12 +58,12 @@
  *
  * **Metadata-only (`content: false`, the default) is size-independent for
  * non-text and oversized blobs.** It folds the read stream through
- * `fs/media/type` `detectStream` and never buffers the blob. Because a single
+ * `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 `fs/media/module.f.ts`) can only be recognized by
+ * `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
@@ -65,12 +72,12 @@
  * alone, unbuffered.
  *
  * **`content: true`** first derives `{ length, mimeType, type }` with the same
- * size-independent `fs/media/type` `detectStream` machine (to decide whether the
+ * 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
- * (`fs/media/module.f.ts` `detect`) — now that the whole blob is in hand, a
+ * (`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 `fs/text/utf8` `fromVec` string on `text` (for `type: 'text'`),
+ * 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
@@ -80,7 +87,7 @@
  * ## Encoding split: hashes vs. content
  *
  * `Cas<O>` deals in `Vec` (bit vectors); MCP models only `textContent` today.
- * **Hashes** travel as cBase32 (`fs/basen/cbase32`) — the canonical CAS hash format,
+ * **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.
  *
@@ -101,23 +108,25 @@
  */
 import { string, option, or, boolean } from '../../types/rtti/module.f.js';
 import { stringify } from '../../media/json/module.f.js';
-import { pure, decode } from '../../effects/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 { empty, length as bitVecLength, maxLength, maxLengthBytes, msb, vec } from '../../types/bit_vec/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, } from '../../mcp/module.f.js';
-import { fileCas } from '../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 = {
@@ -131,38 +140,18 @@ export const casGetArgs = {
 };
 /** Arguments for `cas_list`: none. */
 export const casListArgs = {};
-// ── Stream helper ────────────────────────────────────────────────────────────────
-/**
- * Drains a CAS read stream into a single `Vec`. Used only on the `content: true`
- * path, where the whole blob is needed for inline base64 / UTF-8 transfer; the
- * chunk stream is concatenated and an error item is surfaced as the result.
- * Metadata-only `cas_get` avoids this entirely via `fs/media/type` `detectStream`,
- * which is why it is not bound by the `maxLength` ceiling below.
- */
-const collectRead = (stream) => {
-    const loop = (acc) => (s) => s.step((node) => {
-        if (node === undefined) {
-            return pure(ok(acc));
-        }
-        const { first, tail } = node;
-        const [t, v] = first;
-        if (t === 'error') {
-            return pure(first);
-        }
-        // A single `Vec` cannot exceed `maxLength` bits; concatenating past it would
-        // overflow the runtime's `bigint` constraint. Surface that as an error item
-        // so the tool reports a failure rather than crashing the process.
-        if (bitVecLength(acc) + bitVecLength(v) > maxLength) {
-            return pure(error(`cas blob exceeds maximum vector length of ${maxLength} bits`));
-        }
-        return loop(msb.concat(acc)(v))(tail);
-    });
-    return loop(empty)(stream);
-};
 // ── Tool registry ──────────────────────────────────────────────────────────────
 const toJson = stringify(identity);
-/** Registry of all CAS tools. */
-const casToolRegistry = (home) => {
+/**
+ * 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 }) => {
@@ -173,9 +162,13 @@ const casToolRegistry = (home) => {
             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(([tag, hash]) => pure(tag === 'error'
-                    ? errorResult('write')
-                    : okResult(vecToCBase32(hash))));
+                : 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);
@@ -242,14 +235,12 @@ const casToolRegistry = (home) => {
         toolEntry('cas_list', 'List all stored content hashes (cBase32), one per line.', casListArgs, () => c.list().step(hashes => pure(okResult(hashes.map(vecToCBase32).join('\n'))))),
     ];
 };
-// ── Result helpers ──────────────────────────────────────────────────────────────
-/** A successful single-text-block tool result. */
-const okResult = (text) => ({ content: [{ type: 'text', text }] });
 // ── Handlers ────────────────────────────────────────────────────────────────────
 /**
- * MCP handlers for `FileCas`.
+ * 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) => fromRegistry(casToolRegistry(home));
+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`
@@ -262,28 +253,15 @@ export const casConfig = {
 };
 // ── Server ──────────────────────────────────────────────────────────────────────
 /**
- * Runs the file CAS MCP server over stdio: allocates the session-state slot, builds
- * the `mcpStep` for `c`, and drives the read → parse → dispatch → write loop
- * until stdin EOF.
+ * 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) => create(uninitializedState).step(key => stdioTransport(mcpStep(casConfig)(casMcpHandlers(home))(key)));
+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('/'); },
-    // The overflow guard in collectRead (lines 125-126) is only reached when
-    // the running total of two stream chunks would exceed maxLength.  Feed a
-    // pure stream whose second chunk pushes it just over the limit so the
-    // error branch executes without any real I/O.
-    collectReadOverflow: () => {
-        const half = maxLength / 2n;
-        const v1 = vec(half)(0n);
-        const v2 = vec(half + 1n)(0n);
-        const stream = nonEmpty(ok(v1), nonEmpty(ok(v2), elEmpty()));
-        const d = decode(collectRead(stream));
-        if (!d.done || d.result[0] !== 'error') {
-            throw 'expected overflow error';
-        }
-    },
 };

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;

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

@@ -16,6 +16,7 @@ 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 => {
@@ -56,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
@@ -91,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.
@@ -105,9 +106,9 @@ 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: zero parents, so `subject` must be (and is,
-// per `fs/media/revision/proof.f.ts`) a valid cbase32 hash on its own.
-const revisionSample = `{"dialect":"${revisionDialect}","subject":"8","parents":[]}`;
+// 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
@@ -207,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/basen/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]);
@@ -256,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);

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

@@ -33,6 +33,16 @@ export type Cas<O extends Operation> = {
     /** Lists all stored content hashes. */
     readonly list: () => Effect<O, readonly Vec[]>;
 };
+/**
+ * Drains a `Cas<O>.read` chunk stream into a single `Vec`. Used by any caller
+ * that needs the whole blob at once (an MCP `content: true` fetch, an Evo
+ * revision decode): the chunk stream is concatenated and an error item is
+ * surfaced as the result. A single `Vec` cannot exceed `maxLength` bits;
+ * concatenating past it would overflow the runtime's `bigint` constraint, so
+ * that case is surfaced as an error item too, rather than crashing the
+ * process.
+ */
+export declare const collectRead: <O extends Operation>(stream: List<O, IoResult<Vec>>) => Effect<O, IoResult<Vec>>;
 export type FileCas = Cas<FileCasOperation> & {
     url: (v: Vec) => string;
 };

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

@@ -5,7 +5,7 @@
  */
 import { sha256 } from '../crypto/sha2/module.f.js';
 import { join, normalize, parse } from '../path/module.f.js';
-import { empty, length, maxLengthBytes, msb, vec } from '../types/bit_vec/module.f.js';
+import { empty, length, maxLength, maxLengthBytes, msb, vec } from '../types/bit_vec/module.f.js';
 import { cBase32ToVec, vecToCBase32 } from '../basen/cbase32/module.f.js';
 import { foldStep, forEachStep, okStep, pure } from '../effects/module.f.js';
 import { access, createExclusive, isNotFound, mkdir, now, randomInt, readBytes, readdir, rename, rm, stat, writeBytes, } from '../effects/node/module.f.js';
@@ -22,6 +22,32 @@ export const toPath = (key) => {
     const [b, c] = split2(bc);
     return join(prefix, a, b, c);
 };
+/**
+ * Drains a `Cas<O>.read` chunk stream into a single `Vec`. Used by any caller
+ * that needs the whole blob at once (an MCP `content: true` fetch, an Evo
+ * revision decode): the chunk stream is concatenated and an error item is
+ * surfaced as the result. A single `Vec` cannot exceed `maxLength` bits;
+ * concatenating past it would overflow the runtime's `bigint` constraint, so
+ * that case is surfaced as an error item too, rather than crashing the
+ * process.
+ */
+export const collectRead = (stream) => {
+    const loop = (acc) => (s) => s.step((node) => {
+        if (node === undefined) {
+            return pure(ok(acc));
+        }
+        const { first, tail } = node;
+        const [t, v] = first;
+        if (t === 'error') {
+            return pure(first);
+        }
+        if (length(acc) + length(v) > maxLength) {
+            return pure(error(`cas blob exceeds maximum vector length of ${maxLength} bits`));
+        }
+        return loop(msb.concat(acc)(v))(tail);
+    });
+    return loop(empty)(stream);
+};
 /** Maximum chunk size for streaming reads: the largest `Vec` the runtime allows. */
 const chunkBytes = Number(maxLengthBytes);
 /** Staging directory under the store root; GC and every uploader share it. */

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

@@ -16,5 +16,9 @@ export declare const proof: {
     casWriteGcReclaimsExpired: () => void;
     casUploadSuccess: () => void;
     casUploadFailureKeepsSource: () => void;
+    collectReadDrainsChunks: () => void;
+    collectReadPropagatesErrorItem: () => void;
+    collectReadOverflow: () => void;
+    casListPropagatesNonNotFoundAccessError: () => void;
 };
 export {};