functionalscript 0.34.0 → 0.35.0

package/README.md

@@ -28,22 +28,39 @@ Install FunctionalScript via npm:
 npm install -g functionalscript
 ```
 
-The FunctionalScript compiler command (`fjs compile`) currently supports:
+The `fjs` CLI provides several commands:
 
-* `import` statements
-* `const` declarations
+| Command          | Description                                               |
+|------------------|-----------------------------------------------------------|
+| `fjs test` / `t` | Run the FunctionalScript test suite                       |
+| `fjs compile` / `c` | Compile a `.f.ts` module to JavaScript                 |
+| `fjs run` / `r`  | Run a FunctionalScript module as a Node program           |
+| `fjs cas` / `s`  | Content-addressable storage (`add`, `get`, `list`)        |
+| `fjs mcp` / `m`  | Run an MCP server over stdio exposing the CAS as tools    |
+| `fjs ci` / `i`   | Generate the GitHub Actions CI workflow                   |
 
-It does **not** yet support functions or complex expressions.
+### Content-Addressable Storage (CAS)
 
-Example usage with `fjs`:
+FunctionalScript ships a built-in CAS for storing and retrieving blobs by their cryptographic hash:
 
 ```bash
-fjs compile example.f.js output.json
-# or
-fjs compile example.f.js output.f.js
+fjs cas add myfile.txt   # store a file, print its cBase32 hash
+fjs cas get <hash>       # restore a blob by hash
+fjs cas list             # list all stored hashes
 ```
 
-FunctionalScript code can be compiled directly into either JSON or JavaScript without imports.
+Blobs are stored under `~/.cas/` and addressed by their SHA-256 hash encoded in cBase32.
+
+### MCP Server
+
+The CAS is also exposed as an [MCP](https://modelcontextprotocol.io/) server so LLM agents can read and write blobs without a shell:
+
+```bash
+# register with Claude CLI
+claude mcp add cas -- npx functionalscript m
+```
+
+See [`fs/cas/mcp/README.md`](fs/cas/mcp/README.md) for details on the `cas_add`, `cas_get`, and `cas_list` tools.
 
 ## Vision
 
@@ -67,10 +84,6 @@ In FunctionalScript:
 - A module can depend only on another FunctionalScript module.
 - It also has no standard library. Only a safe subset of standard JavaScript API can be used without referencing other modules.
 
-## Our Next Step
-
-[Re-architecture of NaNVM](https://medium.com/@sergeyshandar/nanvm-re-architecture-8097f766ec1c?sk=d14ec1daf73ac5442f12ce20b2bc037a).
-
 ## Sponsors
 
 - [KirillOsenkov](https://github.com/KirillOsenkov),

package/fs/base64/proof.f.d.ts

@@ -8,4 +8,5 @@ export declare const proof: {
     invalidInput: () => void;
     validPadding: () => void;
     knownVectors: () => void;
+    decodeOverflow: () => void;
 };

package/fs/base64/proof.f.js

@@ -1,14 +1,9 @@
+import { assertEq } from "../asserts/module.f.js";
 import { empty, vec } from "../types/bit_vec/module.f.js";
 import { encode, decode } from "./module.f.js";
 const check = (s, v) => {
-    const sr = encode(v);
-    if (sr !== s) {
-        throw ['encode', sr, s];
-    }
-    const vr = decode(s);
-    if (vr !== v) {
-        throw ['decode', vr, v];
-    }
+    assertEq(encode(v), s);
+    assertEq(decode(s), v);
 };
 export const proof = {
     empty: () => {
@@ -46,62 +41,29 @@ export const proof = {
     },
     nonOctet: () => {
         // encode rejects bit vectors whose length is not a multiple of 8
-        if (encode(vec(1n)(0n)) !== null) {
-            throw '1-bit input should return null';
-        }
-        if (encode(vec(6n)(0n)) !== null) {
-            throw '6-bit input should return null';
-        }
-        if (encode(vec(12n)(0n)) !== null) {
-            throw '12-bit input should return null';
-        }
+        assertEq(encode(vec(1n)(0n)), null);
+        assertEq(encode(vec(6n)(0n)), null);
+        assertEq(encode(vec(12n)(0n)), null);
     },
     invalidInput: () => {
-        if (decode('!') !== null) {
-            throw 'invalid char should return null';
-        }
-        if (decode('A!AA') !== null) {
-            throw 'invalid char mid-string should return null';
-        }
-        if (decode('A===') !== null) {
-            throw 'three equals signs should return null';
-        }
-        if (decode('A') !== null) {
-            throw 'length 1 (not multiple of 4) should return null';
-        }
-        if (decode('AA') !== null) {
-            throw 'length 2 (no padding) should return null';
-        }
-        if (decode('AAA') !== null) {
-            throw 'length 3 (no padding) should return null';
-        }
-        if (decode('=AAA') !== null) {
-            throw 'padding not at end should return null';
-        }
+        assertEq(decode('!'), null);
+        assertEq(decode('A!AA'), null);
+        assertEq(decode('A==='), null);
+        assertEq(decode('A'), null);
+        assertEq(decode('AA'), null);
+        assertEq(decode('AAA'), null);
+        assertEq(decode('=AAA'), null);
         // Non-zero padding bits must be rejected (RFC 4648 §3.5)
-        if (decode('AB==') !== null) {
-            throw 'non-zero 4-pad-bit should return null';
-        }
-        if (decode('AAB=') !== null) {
-            throw 'non-zero 2-pad-bit should return null';
-        }
+        assertEq(decode('AB=='), null);
+        assertEq(decode('AAB='), null);
     },
     validPadding: () => {
         // "==" padding
-        const v2 = decode('AA==');
-        if (v2 !== vec(8n)(0n)) {
-            throw ['AA== should decode to 8-bit zero', v2];
-        }
+        assertEq(decode('AA=='), vec(8n)(0n));
         // "=" padding
-        const v1 = decode('AAA=');
-        if (v1 !== vec(16n)(0n)) {
-            throw ['AAA= should decode to 16-bit zero', v1];
-        }
+        assertEq(decode('AAA='), vec(16n)(0n));
         // No padding
-        const v0 = decode('AAAA');
-        if (v0 !== vec(24n)(0n)) {
-            throw ['AAAA should decode to 24-bit zero', v0];
-        }
+        assertEq(decode('AAAA'), vec(24n)(0n));
     },
     knownVectors: () => {
         // RFC 4648 §10 test vectors (byte-aligned, treating bytes as 8-bit MSB vectors)
@@ -114,4 +76,11 @@ export const proof = {
         // 0x66 0x6f 0x6f ('foo') → Zm9v
         check('Zm9v', vec(24n)(0x666f6fn));
     },
+    decodeOverflow: () => {
+        // 174_764 base64 chars decode to 1_048_584 bits, 8 over `maxLength`;
+        // `decode` should return `null` instead of throwing on (or hanging
+        // while building) an oversized `bigint`.
+        const oversized = 'A'.repeat(174_764);
+        assertEq(decode(oversized), null);
+    },
 };

package/fs/base_n/module.f.js

@@ -11,8 +11,10 @@
  *
  * @module
  */
-import { msb, length, vec, empty } from "../types/bit_vec/module.f.js";
-const { popFront, concat } = msb;
+import { msb, lsb, length, vec } from "../types/bit_vec/module.f.js";
+import {} from "../types/list/module.f.js";
+const { popFront } = msb;
+const { tryListToVec: reversedListToVec } = lsb;
 /**
  * Builds a {@link BaseN} codec for a fixed chunk width and alphabet.
  *
@@ -40,15 +42,19 @@ export const baseN = (bits, alphabet, normalize) => {
             return result;
         },
         stringToVec: s => {
-            let result = empty;
+            // Build a reversed chunk list, bailing out at the first invalid
+            // character so malformed input is rejected in O(prefix) time and
+            // `normalize` is never run past it. `listToVec` then concatenates in
+            // O(n log n).
+            let chunks = null;
             for (const c of s) {
                 const index = toIndex(c);
                 if (index < 0) {
                     return null;
                 }
-                result = concat(result)(vecN(BigInt(index)));
+                chunks = { first: vecN(BigInt(index)), tail: chunks };
             }
-            return result;
+            return reversedListToVec(chunks);
         },
     };
 };

package/fs/base_n/proof.f.d.ts

@@ -7,4 +7,5 @@ export declare const proof: {
     decodeInvalid: () => void;
     normalizeHit: () => void;
     normalizeMiss: () => void;
+    big: () => void;
 };

package/fs/base_n/proof.f.js

@@ -1,4 +1,5 @@
-import { empty, vec } from "../types/bit_vec/module.f.js";
+import { assertEq } from "../asserts/module.f.js";
+import { empty, maxLength, vec, length } from "../types/bit_vec/module.f.js";
 import { baseN } from "./module.f.js";
 const hex = baseN(4n, '0123456789abcdef');
 const cb32 = baseN(5n, '0123456789abcdefghjkmnpqrstvwxyz', c => {
@@ -18,6 +19,9 @@ const cb32 = baseN(5n, '0123456789abcdefghjkmnpqrstvwxyz', c => {
         }
     }
 });
+// Sample input for the `big` proof below: 262 144 `f` characters decode into a
+// 1 Mibit (`maxLength`) vector.
+const bigSampleHex = `f`.repeat(Number(maxLength >> 2n));
 export const proof = {
     encodeEmpty: () => {
         const s = hex.vecToString(empty);
@@ -83,4 +87,11 @@ export const proof = {
             throw 'unknown char should return null';
         }
     },
+    // Decodes a 1 Mibit hex string. With the O(n log n) `listToVec` builder this
+    // runs in well under a second (was ~13 s node / ~43 s bun under the old
+    // per-chunk `concat`).
+    big: () => {
+        const x = hex.stringToVec(bigSampleHex);
+        assertEq(length(x), maxLength);
+    }
 };

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

@@ -47,11 +47,14 @@
  * only metadata was asked for; streaming detection returns correct
  * `{ length, mime_type, type[, url] }` regardless of size.
  *
- * **`content: true`** materializes the bytes (via `collectRead`, bounded by
- * `maxLength`), classifies them with the same machine via `fs/mime` `detectVec`,
- * then encodes the inline payload by `type` — a `fs/text/utf8` `fromVec` string for
- * `text`, base64 for `base64`. A blob larger than `maxLength` is unsupported here
- * and should be fetched via `url`.
+ * **`content: true`** first derives `{ length, mime_type, type }` with the same
+ * size-independent `fs/mime` `detectStream` machine, then materializes the bytes
+ * (via `collectRead`, bounded by `maxLength`) and encodes the inline payload by
+ * `type` — a `fs/text/utf8` `fromVec` string for `text`, base64 for `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 `url`) rather than being misreported as absent; it should be fetched via
+ * `url` or inspected with metadata-only `cas_get`.
  *
  * ## Encoding split: hashes vs. content
  *
@@ -69,6 +72,8 @@
  * - `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
@@ -79,9 +84,9 @@ import { pure } from "../../effects/module.f.js";
 import { create } from "../../effects/memory/module.f.js";
 import { cBase32ToVec, vecToCBase32 } from "../../cbase32/module.f.js";
 import { decode as base64Decode, encode as base64Encode } from "../../base64/module.f.js";
-import { utf8 } from "../../text/module.f.js";
-import { detectVec, detectStream } from "../../mime/module.f.js";
-import { empty, length as bitVecLength, maxLength, msb } from "../../types/bit_vec/module.f.js";
+import { tryUtf8 } from "../../text/module.f.js";
+import { detectStream } from "../../mime/module.f.js";
+import { empty, length as bitVecLength, maxLength, maxLengthBytes, msb } from "../../types/bit_vec/module.f.js";
 import { ok, error } from "../../types/result/module.f.js";
 import { rm } from "../../effects/node/module.f.js";
 import { stdioTransport } from "../../mcp/stdio/module.f.js";
@@ -139,7 +144,7 @@ const casToolRegistry = (home) => {
     const c = fileCas(sha256)(home);
     const casUploadDir = `${home}/cas_upload`;
     return [
-        toolEntry('cas_add', 'Store content and return its hash (cBase32). Pass type:"base64" for binary; type:"url" to stream a file from $HOME/cas_upload/ (no size limit); omit or pass type:"text" for UTF-8 text (default).', casAddArgs, ({ type, content }) => {
+        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 (text/base64) is capped at 128 KiB (131072 bytes) — larger content is rejected. For larger content use type:"url" to stream a file from $HOME/cas_upload/ (no size limit).', casAddArgs, ({ type, content }) => {
             // type:'url' — stream the file into cas, then delete the source on success
             if (type === 'url') {
                 if (!content.startsWith(`${casUploadDir}/`) || content.includes('..')) {
@@ -150,66 +155,56 @@ const casToolRegistry = (home) => {
                     : rm(content).step(() => pure(okResult(vecToCBase32(v)))));
             }
             // type:'text' or 'base64' — resolve content to Vec, store via c.write()
-            let x;
-            switch (type) {
-                case 'base64':
-                    const value = base64Decode(content);
-                    x = pure(value === null ? `invalid base64 content: ${content}` : value);
-                    break;
-                default:
-                    x = pure(utf8(content));
-                    break;
-            }
-            return x.step(value => typeof value === 'string'
-                ? pure(errorResult(value))
+            let x = type === 'base64'
+                ? base64Decode(content)
+                : tryUtf8(content);
+            return x === null
+                ? pure(errorResult('too large or malformed — use type:"url" for large content'))
                 // The resolved content fits in one chunk; feed it as a single-item stream.
-                : c.write(nonEmpty(ok(value), elEmpty())).step(hashResult => pure(hashResult[0] === 'error'
+                : c.write(nonEmpty(ok(x), elEmpty())).step(([tag, hash]) => pure(tag === 'error'
                     ? errorResult('write')
-                    : okResult(vecToCBase32(hashResult[1])))));
+                    : okResult(vecToCBase32(hash))));
         }),
-        toolEntry('cas_get', 'Inspect a blob by hash. Always returns JSON {length,mime_type,type[,url]} where type is "text" or "base64". Pass content:true to also include the inline content string.', casGetArgs, r => {
+        toolEntry('cas_get', 'Inspect a blob by hash. Always returns JSON {length,mime_type,type[,url]} where type is "text" or "base64". Pass content:true to also include the inline content string, but content is capped at 128 KiB (131072 bytes) — a larger blob is rejected with an error. To download a blob, prefer the url 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 url = c.url(key);
-            // Metadata-only (the default): derive `{ length, mime_type, type }` by
-            // streaming the blob through the detector state machine. Never buffers
-            // the blob, so this is size-independent — large blobs that overflow a
-            // single `Vec` still return correct metadata instead of an error.
-            if (r.content !== true) {
-                return detectStream(c.read(key)).step(result => {
-                    if (result[0] === 'error') {
-                        return pure(errorResult(`no such hash: ${r.hash}`));
-                    }
-                    const { length, mime_type, type } = result[1];
-                    const meta = { length: Number(length), mime_type, type, url };
-                    return pure(okResult(toJson(meta)));
-                });
-            }
-            // content:true — collect the bytes (bounded by `maxLength`) so they can
-            // be encoded inline. Classification uses the *same* `detectVec` state
-            // machine as the metadata-only path; `type` then selects the encoding —
-            // a UTF-8 string for `text`, base64 for `base64`.
-            return collectRead(c.read(key)).step(result => {
-                if (result[0] === 'error') {
+            return detectStream(c.read(key)).step(([tag, detected]) => {
+                if (tag === 'error') {
                     return pure(errorResult(`no such hash: ${r.hash}`));
                 }
-                const value = result[1];
-                const { length, mime_type, type } = detectVec(value);
+                const { length, mime_type, type } = detected;
                 const meta = { length: Number(length), mime_type, type, url };
-                if (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({ ...meta, content: str })));
+                if (r.content !== true) {
+                    // content:true path continues below; this is just the metadata step.
+                    return pure(okResult(toJson(meta)));
+                }
+                // 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 url field (${url}) or omit content for metadata`));
                 }
-                const blob = base64Encode(value);
-                return pure(blob === null
-                    ? errorResult(`content is not byte-aligned: ${r.hash}`)
-                    : okResult(toJson({ ...meta, content: blob })));
+                return collectRead(c.read(key)).step(([collectTag, value]) => {
+                    if (collectTag === 'error') {
+                        return pure(errorResult(`no such hash: ${r.hash}`));
+                    }
+                    if (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({ ...meta, content: str })));
+                    }
+                    const blob = base64Encode(value);
+                    return pure(blob === null
+                        ? errorResult(`content is not byte-aligned: ${r.hash}`)
+                        : okResult(toJson({ ...meta, content: 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'))))),

package/fs/cas/mcp/proof.f.d.ts

@@ -2,6 +2,9 @@ export declare const proof: {
     getMetaLargeMultiChunkBlobNoError: () => void;
     getMetaLargeMultiChunkUtf8Symbols: () => void;
     getMetaLargeMultiChunkTextThenBinary: () => void;
+    getContentLargeBlobTooLargeError: () => void;
+    getContentMissingHashIsError: () => void;
+    getContentDoubleEscapedOverflowWritesInternalError: () => void;
     toolsListAdvertisesThreeTools: () => void;
     addReturnsHash: () => void;
     textAddGetMetaRoundTrips: () => void;
@@ -14,6 +17,10 @@ export declare const proof: {
     listEnumeratesStoredHashes: () => void;
     addInvalidContentIsError: () => void;
     addBadLengthContentIsError: () => void;
+    addBase64OverLimitIsError: () => void;
+    addTextOverLimitIsError: () => void;
+    addTextAtLimitSucceeds: () => void;
+    addBase64AtLimitIsError: () => void;
     getUnterminatedHashIsError: () => void;
     addMissingContentIsError: () => void;
     getMissingHashArgumentIsError: () => void;

package/fs/cas/mcp/proof.f.js

@@ -11,6 +11,8 @@ 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";
 const initialTestState = { memory: { next: 0, values: {} } };
 const mock = {
     memCreate: value => state => {
@@ -65,6 +67,23 @@ const call = (id, name, args) => ({ jsonrpc: '2.0', method: 'tools/call', id, pa
 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
+// `fs/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 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 resultOf = (resp) => resp.result;
 const item0 = (resp) => resultOf(resp).content[0];
 const textOf = (resp) => item0(resp).text;
@@ -75,6 +94,22 @@ 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.
 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 — safe near maxLengthBytes where base64Encode on a
+// padded Vec would trigger the encode-padding-overflow bug. 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=';
+};
 // ── Tests ───────────────────────────────────────────────────────────────────────
 // A blob larger than one read chunk (> 128 KiB) used to fail metadata-only
 // cas_get because `collectRead` overflowed `maxLength`. With `detectStream`,
@@ -107,6 +142,13 @@ const asciiChunk = repeat(maxLengthBytes)(vec8(0x61n));
 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));
+// 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 = {
     // Both chunks repeated ASCII → text/plain, no error on a > 128 KiB blob.
     getMetaLargeMultiChunkBlobNoError: largeMultiChunkBlobMeta(asciiChunk, asciiChunk, 'text', 'text/plain'),
@@ -115,6 +157,58 @@ export const proof = {
     // 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 = { 'home': { 'user': { 'cas_upload': { 'big': [asciiChunk, asciiChunk] } } } };
+        const [addResp] = runSessionVirtual(root)([
+            init, initialized,
+            call(2, 'cas_add', { content: '/home/user/cas_upload/big', type: 'url' }),
+        ]).slice(2);
+        const hash = textOf(addResp);
+        const [, getResp] = runSessionVirtual(root)([
+            init, initialized,
+            call(2, 'cas_add', { content: '/home/user/cas_upload/big', type: 'url' }),
+            call(3, '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 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. Uploaded via
+    // `type: 'url'` (a file, not an inlined 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 = { 'home': { 'user': { 'cas_upload': { 'q': [quotesChunk] } } } };
+        const [addResp] = runStdio(root)([
+            call(2, 'cas_add', { content: '/home/user/cas_upload/q', type: 'url' }),
+        ]);
+        const hash = textOf(addResp);
+        const [, getResp] = runStdio(root)([
+            call(2, 'cas_add', { content: '/home/user/cas_upload/q', type: 'url' }),
+            call(3, 'cas_get', { hash, content: true }),
+        ]);
+        const err = getResp;
+        assertEq(err.error?.code, -32603);
+        assertEq(err.id, 3);
+    },
     toolsListAdvertisesThreeTools: () => {
         const [resp] = runSessionVirtual({})([init, initialized, list(2)]).slice(2);
         const tools = resp.result.tools;
@@ -216,6 +310,37 @@ export const proof = {
         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'));
+    },
+    // 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'));
+    },
+    // 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 — 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: () => {
+        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'));
+    },
     getUnterminatedHashIsError: () => {
         const [resp] = session(call(2, 'cas_get', { hash: '0' }));
         assertEq(resultOf(resp).isError, true);

package/fs/mcp/stdio/module.f.d.ts

@@ -18,6 +18,14 @@
  *   `null`) is written rather than silently discarded, per JSON-RPC 2.0 §5.
  * - the step yields `null` (a notification needing no reply) → nothing is
  *   written and the loop continues.
+ * - a response that doesn't fit in one encoded line (`tryUtf8` overflow —
+ *   `maxLength`, 128 KiB) never throws. `writeResponse` retries with a fixed,
+ *   small `-32603` internal-error body carrying the original `id`; if even
+ *   that overflows (a pathological caller-controlled `id`, e.g. a very large
+ *   string), it retries once more with `id: null` — a fully constant response
+ *   shape that is always small enough to encode. Every request that reaches
+ *   `step` therefore gets *some* response line, never silence and never a
+ *   crashed process.
  *
  * @module
  */

package/fs/mcp/stdio/module.f.js

@@ -18,25 +18,39 @@
  *   `null`) is written rather than silently discarded, per JSON-RPC 2.0 §5.
  * - the step yields `null` (a notification needing no reply) → nothing is
  *   written and the loop continues.
+ * - a response that doesn't fit in one encoded line (`tryUtf8` overflow —
+ *   `maxLength`, 128 KiB) never throws. `writeResponse` retries with a fixed,
+ *   small `-32603` internal-error body carrying the original `id`; if even
+ *   that overflows (a pathological caller-controlled `id`, e.g. a very large
+ *   string), it retries once more with `id: null` — a fully constant response
+ *   shape that is always small enough to encode. Every request that reaches
+ *   `step` therefore gets *some* response line, never silence and never a
+ *   crashed process.
  *
  * @module
  */
 import { pure } from "../../effects/module.f.js";
 import { readLine, write } from "../../effects/node/module.f.js";
-import { utf8 } from "../../text/module.f.js";
+import { tryUtf8 } from "../../text/module.f.js";
 import { stringToList } from "../../text/utf16/module.f.js";
 import { stringify } from "../../json/module.f.js";
 import { tokenize } from "../../json/tokenizer/module.f.js";
 import { parse } from "../../json/parser/module.f.js";
 import { sort } from "../../types/object/module.f.js";
-import { jsonrpc, parseError } from "../../json/rpc/module.f.js";
+import { internalError, jsonrpc, parseError } from "../../json/rpc/module.f.js";
+import { error, ok } from "../../types/result/module.f.js";
 const stringifyJson = stringify(sort);
 /** The parse-error response (`-32700`, `id: null`) for a malformed input line. */
 const parseErrorResponse = { jsonrpc, error: parseError, id: null };
+/** An internal-error response (`-32603`) carrying `id`. */
+const internalErrorResponse = (id) => ({ jsonrpc, error: internalError, id });
 /** Encodes a response as a newline-terminated UTF-8 line and writes it to `stdout`. */
-const writeResponse = (resp) => write('stdout', utf8(stringifyJson(resp) + '\n'));
-/** Writes `resp` when present, otherwise does nothing (notification). */
-const writeMaybe = (resp) => resp === null ? pure(undefined) : writeResponse(resp);
+const writeResponse = (resp) => {
+    const v = tryUtf8(stringifyJson(resp) + '\n');
+    return v === null
+        ? pure(error(undefined))
+        : write('stdout', v).step(() => pure(ok(undefined)));
+};
 /**
  * Drives the read-parse-dispatch-write loop for `step` over stdin/stdout.
  *
@@ -50,5 +64,18 @@ const handleLine = (step) => (line) => {
     const [t, value] = parse(tokenize(stringToList(line)));
     return (t === 'error'
         ? writeResponse(parseErrorResponse)
-        : step(value).step(writeMaybe)).step(() => stdioTransport(step));
+        : step(value).step(resp => resp === null
+            ? pure(undefined)
+            : writeResponse(resp).step(([t2]) => t2 === 'error'
+                // The real response didn't fit. Retry with a fixed, small
+                // internal-error body carrying `resp.id` — but a
+                // caller-controlled `id` (e.g. a very large string) can
+                // itself push even this fallback over `maxLength`, so
+                // that retry is bounded by one more: an `id: null`
+                // internal-error, whose fully-constant shape is the only
+                // line in this transport guaranteed to always encode.
+                ? writeResponse(internalErrorResponse(resp.id)).step(([t3]) => t3 === 'error'
+                    ? writeResponse(internalErrorResponse(null)).step(() => pure(undefined))
+                    : pure(undefined))
+                : pure(undefined)))).step(() => stdioTransport(step));
 };

package/fs/mcp/stdio/proof.f.d.ts

@@ -6,5 +6,8 @@ export declare const proof: {
     malformedJsonWritesParseError: () => void;
     trailingCommaWritesParseError: () => void;
     undefinedFieldOmitted: () => void;
+    oversizedResponseWritesInternalError: () => void;
+    loopContinuesAfterOversizedResponse: () => void;
+    oversizedIdFallsBackToNullId: () => void;
     multipleLines: () => void;
 };

package/fs/mcp/stdio/proof.f.js

@@ -4,8 +4,9 @@ import { emptyState, virtual } from "../../effects/node/virtual/module.f.js";
 import { stringify } from "../../json/module.f.js";
 import { utf8 } from "../../text/module.f.js";
 import { fromVec } from "../../types/uint8array/module.f.js";
+import { maxLengthBytes } from "../../types/bit_vec/module.f.js";
 import { sort } from "../../types/object/module.f.js";
-import { jsonrpc, parseError } from "../../json/rpc/module.f.js";
+import { internalError, jsonrpc, parseError } from "../../json/rpc/module.f.js";
 import { stdioTransport } from "./module.f.js";
 const stringifyJson = stringify(sort);
 // Extracts the request `id` (a request has one; a notification does not).
@@ -29,7 +30,11 @@ const runStep = (step) => (input) => virtual({ ...emptyState, stdin: toBytes(inp
 const run = runStep(echoStep);
 const okResponse = (id) => stringifyJson({ jsonrpc, result: { ok: true }, id }) + '\n';
 const parseErrorLine = stringifyJson({ jsonrpc, error: parseError, id: null }) + '\n';
+const internalErrorLine = (id) => stringifyJson({ jsonrpc, error: internalError, id }) + '\n';
 const ping = (id) => `{"jsonrpc":"2.0","method":"ping","id":${id}}`;
+// One byte past `maxLengthBytes` on its own; embedded in a response envelope
+// it stays comfortably over the limit despite the surrounding JSON overhead.
+const oversizedString = 'a'.repeat(Number(maxLengthBytes) + 1);
 const notification = '{"jsonrpc":"2.0","method":"notifications/initialized"}';
 export const proof = {
     // EOF on the very first read: clean shutdown, nothing written, no further reads.
@@ -81,6 +86,52 @@ export const proof = {
         const state = runStep(step)(ping(1) + '\n');
         assertEq(state.stdout, okResponse(1));
     },
+    // A response that would exceed `maxLengthBytes` once UTF-8 encoded cannot
+    // be written as a single bit vector (`tryUtf8` reports overflow); the loop
+    // writes a JSON-RPC internal-error response — carrying the original
+    // request's `id`, not `null` — instead of throwing or silently dropping
+    // the reply.
+    oversizedResponseWritesInternalError: () => {
+        const step = (value) => {
+            const id = idOf(value);
+            return pure(id === undefined
+                ? null
+                : { jsonrpc, result: { big: oversizedString }, id });
+        };
+        const state = runStep(step)(ping(1) + '\n');
+        assertEq(state.stdout, internalErrorLine(1));
+    },
+    // The loop recovers from the oversized-response error and keeps draining
+    // stdin: a well-behaved request on the next line still gets its normal
+    // reply.
+    loopContinuesAfterOversizedResponse: () => {
+        const step = (value) => {
+            const id = idOf(value);
+            return pure(id === undefined
+                ? null
+                : id === 1
+                    ? { jsonrpc, result: { big: oversizedString }, id }
+                    : { jsonrpc, result: { ok: true }, id });
+        };
+        const state = runStep(step)([ping(1), ping(2)].join('\n'));
+        assertEq(state.stdout, internalErrorLine(1) + okResponse(2));
+        assertEq(state.stdin.length, 0);
+    },
+    // When even the `id`-preserving internal-error fallback would overflow —
+    // because the `id` itself is the oversized part, not just `result` — the
+    // loop falls back once more to a fixed `id: null` internal-error, the only
+    // shape in this transport guaranteed to always fit. Without this second
+    // fallback tier the request would get no response line at all.
+    oversizedIdFallsBackToNullId: () => {
+        const step = (value) => {
+            const id = idOf(value);
+            return pure(id === undefined
+                ? null
+                : { jsonrpc, result: { ok: true }, id: oversizedString });
+        };
+        const state = runStep(step)(ping(1) + '\n');
+        assertEq(state.stdout, internalErrorLine(null));
+    },
     // A multi-line session interleaving all cases: request, notification, and
     // malformed line, ending with an unterminated request. Order is preserved
     // and the notification contributes nothing.

package/fs/text/module.f.d.ts

@@ -7,19 +7,29 @@
  */
 import { type Vec } from '../types/bit_vec/module.f.ts';
 import { type List } from '../types/list/module.f.ts';
+import { type Nullable } from '../types/nullable/module.f.ts';
 export type Block = ItemThunk | ItemArray;
 type ItemArray = readonly Item[];
 type ItemThunk = () => List<Item>;
 export type Item = string | ItemArray | ItemThunk;
 export declare const flat: (indent: string) => (text: Block) => List<string>;
 export type Utf8 = Vec;
+/**
+ * Converts a string to an UTF-8, represented as an MSB first bit vector,
+ * returning `null` instead of throwing if the result would exceed
+ * `maxLength`.
+ *
+ * @param s The input string to be converted.
+ * @returns The resulting UTF-8 bit vector, MSB first, or `null` on overflow.
+ */
+export declare const tryUtf8: (s: string) => Nullable<Utf8>;
 /**
  * Converts a string to an UTF-8, represented as an MSB first bit vector.
  *
  * @param s The input string to be converted.
  * @returns The resulting UTF-8 bit vector, MSB first.
  */
-export declare const utf8: (s: string) => Utf8;
+export declare const utf8: import("../types/function/module.f.ts").Func<string, Vec>;
 /**
  * Converts a UTF-8 bit vector with MSB first encoding to a string.
  *

package/fs/text/module.f.js

@@ -5,10 +5,11 @@
  *
  * @module
  */
-import { msb, u8List, u8ListToVec } from "../types/bit_vec/module.f.js";
+import { msb, tryU8ListToVec, u8List } from "../types/bit_vec/module.f.js";
 import { flatMap } from "../types/list/module.f.js";
 import { fromCodePointList, toCodePointList } from "./utf8/module.f.js";
 import { stringToCodePointList, codePointListToString } from "./utf16/module.f.js";
+import { mapUnwrap } from "../types/nullable/module.f.js";
 export const flat = (indent) => {
     const f = (prefix) => {
         const g = (item) => typeof (item) === 'string' ? [`${prefix}${item}`] : f(`${prefix}${indent}`)(item);
@@ -16,14 +17,23 @@ export const flat = (indent) => {
     };
     return f('');
 };
-const u8ListToVecMsb = u8ListToVec(msb);
+const tryU8ListToVecMsb = tryU8ListToVec(msb);
+/**
+ * Converts a string to an UTF-8, represented as an MSB first bit vector,
+ * returning `null` instead of throwing if the result would exceed
+ * `maxLength`.
+ *
+ * @param s The input string to be converted.
+ * @returns The resulting UTF-8 bit vector, MSB first, or `null` on overflow.
+ */
+export const tryUtf8 = (s) => tryU8ListToVecMsb(fromCodePointList(stringToCodePointList(s)));
 /**
  * Converts a string to an UTF-8, represented as an MSB first bit vector.
  *
  * @param s The input string to be converted.
  * @returns The resulting UTF-8 bit vector, MSB first.
  */
-export const utf8 = (s) => u8ListToVecMsb(fromCodePointList(stringToCodePointList(s)));
+export const utf8 = mapUnwrap(tryUtf8);
 /**
  * Converts a UTF-8 bit vector with MSB first encoding to a string.
  *

package/fs/text/proof.f.d.ts

@@ -1,4 +1,10 @@
 export declare const proof: {
     block: () => void;
     encoding: () => void;
+    tryUtf8RoundTrip: () => void;
+    tryUtf8Empty: () => void;
+    tryUtf8Overflow: {
+        try: () => void;
+        throw: () => void;
+    };
 };

package/fs/text/proof.f.js

@@ -1,5 +1,8 @@
-import { flat, utf8, utf8ToString } from "./module.f.js";
+import { assert, assertEq } from "../asserts/module.f.js";
+import { flat, utf8, utf8ToString, tryUtf8 } from "./module.f.js";
 import { join } from "../types/string/module.f.js";
+import { empty, maxLengthBytes } from "../types/bit_vec/module.f.js";
+const overflowStr = 'a'.repeat(Number(maxLengthBytes) + 1);
 export const proof = {
     block: () => {
         const text = [
@@ -22,5 +25,25 @@ export const proof = {
         if (r !== 'Hello world!') {
             throw r;
         }
-    }
+    },
+    tryUtf8RoundTrip: () => {
+        const v = tryUtf8('Hello world!');
+        assert(v !== null);
+        assertEq(v, utf8('Hello world!'));
+        assertEq(utf8ToString(v), 'Hello world!');
+    },
+    tryUtf8Empty: () => {
+        assertEq(tryUtf8(''), empty);
+    },
+    tryUtf8Overflow: {
+        // One byte past `maxLengthBytes`; `tryUtf8` should report `null`
+        // instead of building an oversized `bigint`, and the throwing `utf8`
+        // wrapper should raise on the same input.
+        try: () => {
+            assertEq(tryUtf8(overflowStr), null);
+        },
+        throw: () => {
+            utf8(overflowStr);
+        },
+    },
 };

package/fs/types/bit_vec/module.f.d.ts

@@ -26,6 +26,7 @@ import type { Binary, Fold, Reduce as OpReduce } from '../function/operator/modu
 import { type List, type Thunk } from '../list/module.f.ts';
 import { type Nominal } from '../nominal/module.f.ts';
 import { type Sign } from '../function/compare/module.f.ts';
+import { type Nullable } from '../nullable/module.f.ts';
 /**
  * A vector of bits represented as a signed `bigint`.
  */
@@ -195,6 +196,12 @@ export type BitOrder = {
      * ```
      */
     readonly concat: Reduce;
+    /**
+     * Folds a list of vectors into a single vector in this bit order, like
+     * `listToVec`, but returns `null` instead of throwing when the combined
+     * length would exceed `maxLength`.
+     */
+    readonly tryListToVec: (list: List<Vec>) => Nullable<Vec>;
     /**
      * Folds a list of vectors into a single vector in this bit order.
      *
@@ -221,9 +228,10 @@ export type BitOrder = {
      */
     readonly cmp: (a: Vec) => (b: Vec) => Sign;
     readonly unpackSplit: (len: bigint) => (u: Unpacked) => readonly [bigint, bigint];
-    readonly unpackConcat: (a: Unpacked) => (b: Unpacked) => Unpacked;
+    readonly unpackConcat: UnpackConcat;
     readonly startsWith: (prefix: Vec) => (v: Vec) => boolean;
 };
+type UnpackConcat = (a: Unpacked) => (b: Unpacked) => Unpacked;
 /**
  * Implements operations for handling vectors in a least-significant-bit (LSb) first order.
  *
@@ -240,6 +248,16 @@ export declare const lsb: BitOrder;
  * Usually associated with Big-Endian (BE) byte order.
  */
 export declare const msb: BitOrder;
+/**
+ * Converts a list of unsigned 8-bit integers to a bit vector using the provided
+ * bit order, like `u8ListToVec`, but returns `null` instead of throwing when the
+ * result would exceed `maxLength`.
+ *
+ * @param bo The bit order for the conversion
+ * @param list The list of unsigned 8-bit integers to be converted.
+ * @returns The resulting vector, or `null` if it would exceed `maxLength`.
+ */
+export declare const tryU8ListToVec: ({ unpackConcat }: BitOrder) => (list: List<number>) => Nullable<Vec>;
 /**
  * Converts a list of unsigned 8-bit integers to a bit vector using the provided bit order.
  *
@@ -247,7 +265,7 @@ export declare const msb: BitOrder;
  * @param list The list of unsigned 8-bit integers to be converted.
  * @returns The resulting vector based on the provided bit order.
  */
-export declare const u8ListToVec: ({ unpackConcat }: BitOrder) => (list: List<number>) => Vec;
+export declare const u8ListToVec: (bo: BitOrder) => import("../function/module.f.ts").Func<List<number>, Vec>;
 /**
  * Chunks an unpacked vector into fixed-size pieces of `n` bits using the provided bit order,
  * returning each chunk as an unsigned integer.

package/fs/types/bit_vec/module.f.js

@@ -23,10 +23,11 @@
  */
 import { bitLength, divUp, mask, maxLength, xor } from "../bigint/module.f.js";
 import { flip, identity } from "../function/module.f.js";
-import { fold, iterable, map } from "../list/module.f.js";
+import { iterable, map } from "../list/module.f.js";
 import { asBase, asNominal } from "../nominal/module.f.js";
 import { repeat as mRepeat } from "../monoid/module.f.js";
 import { cmp, max, min } from "../function/compare/module.f.js";
+import { mapUnwrap } from "../nullable/module.f.js";
 /**
  * Maximum length of a bit vector in bits (1_048_576 = 0x10_0000).
  * This limit is enforced by Bun's `bigint` size constraint, the minimal limit
@@ -133,6 +134,64 @@ const op = (norm) => (op) => ap => bp => {
     const { a, b } = norm(au)(bu)(len);
     return vec(len)(op(a)(b));
 };
+const unpackEmpty = { length: 0n, uint: 0n };
+const listToVecOp = (unpackConcat) => ({
+    init: { len: 0n, stack: [] },
+    update: (v, { len, stack }) => {
+        len += v.length;
+        if (len > maxLength) {
+            return null;
+        }
+        let i = 0;
+        while (true) {
+            if (stack.length <= i) {
+                stack = [...stack, v];
+                break;
+            }
+            const old = stack[i];
+            if (old.length === 0n) {
+                stack = stack.toSpliced(i, 1, v);
+                break;
+            }
+            stack = stack.toSpliced(i, 1, unpackEmpty);
+            v = unpackConcat(old)(v);
+            i++;
+        }
+        return { len, stack };
+    },
+    end: ({ stack }) => pack(stack.reduce((p, c) => unpackConcat(c)(p), unpackEmpty))
+});
+/**
+ * Concatenates a list of unpacked vectors using a binary-counter accumulator,
+ * giving O(n log n) total `bigint` shifting work instead of the O(n²) of a
+ * naive left fold.
+ *
+ * Slot `i` of `result` holds an already-combined run of the most recent
+ * `2 ** i` elements. Each arriving element "carries" upward, merging only with
+ * runs of comparable size — exactly like incrementing a binary number — so
+ * every merge joins two runs of similar length. Left-to-right element order is
+ * preserved: `unpackConcat(old)(cur)` keeps the earlier run on the left, and
+ * the final reduce prepends higher (earlier) slots in front of accumulated
+ * later runs. An empty list yields `unpackEmpty`.
+ *
+ * This is the bit-vector analogue of a builder that accumulates appended pieces
+ * and materializes the combined result on demand, such as `StringBuilder`
+ * (Java, C#) or `strings.Builder` (Go).
+ */
+const unpackListToVec = (unpackConcat) => {
+    const { init, update, end } = listToVecOp(unpackConcat);
+    return (list) => {
+        let result = init;
+        for (const e of iterable(list)) {
+            const candidate = update(e, result);
+            if (candidate === null) {
+                return null;
+            }
+            result = candidate;
+        }
+        return end(result);
+    };
+};
 const bo = ({ front, removeFront, norm, uintCmp, unpackSplit, unpackConcatUint }) => {
     const unpackPopFront = (len) => {
         const m = mask(len);
@@ -142,8 +201,9 @@ const bo = ({ front, removeFront, norm, uintCmp, unpackSplit, unpackConcatUint }
             return [uint & m, { length: v.length - len, uint: rest }];
         };
     };
-    const unpackConcat = (a) => (b) => ({
-        length: a.length + b.length, uint: unpackConcatUint(a)(b)
+    const unpackConcat = a => b => ({
+        length: a.length + b.length,
+        uint: unpackConcatUint(a)(b)
     });
     const popFront = len => {
         const f = unpackPopFront(len);
@@ -157,11 +217,13 @@ const bo = ({ front, removeFront, norm, uintCmp, unpackSplit, unpackConcatUint }
         const bu = unpack(b);
         return pack(unpackConcat(au)(bu));
     };
+    const tryListToVec = (list) => unpackListToVec(unpackConcat)(map(unpack)(list));
     return {
         front,
         removeFront,
         concat,
-        listToVec: fold(flip(concat))(empty),
+        tryListToVec,
+        listToVec: mapUnwrap(tryListToVec),
         xor: op(norm)(xor),
         unpackPopFront,
         popFront,
@@ -232,7 +294,16 @@ export const msb = bo({
     unpackSplit: len => ({ length, uint }) => [uint >> (length - len), uint],
     unpackConcatUint: flip(lsbUnpackConcatUint),
 });
-const unpackEmpty = { length: 0n, uint: 0n };
+/**
+ * Converts a list of unsigned 8-bit integers to a bit vector using the provided
+ * bit order, like `u8ListToVec`, but returns `null` instead of throwing when the
+ * result would exceed `maxLength`.
+ *
+ * @param bo The bit order for the conversion
+ * @param list The list of unsigned 8-bit integers to be converted.
+ * @returns The resulting vector, or `null` if it would exceed `maxLength`.
+ */
+export const tryU8ListToVec = ({ unpackConcat }) => (list) => unpackListToVec(unpackConcat)(map((b) => ({ length: 8n, uint: BigInt(b) }))(list));
 /**
  * Converts a list of unsigned 8-bit integers to a bit vector using the provided bit order.
  *
@@ -240,28 +311,7 @@ const unpackEmpty = { length: 0n, uint: 0n };
  * @param list The list of unsigned 8-bit integers to be converted.
  * @returns The resulting vector based on the provided bit order.
  */
-export const u8ListToVec = ({ unpackConcat }) => (list) => {
-    let result = [];
-    for (const b of iterable(list)) {
-        let v = { length: 8n, uint: BigInt(b) };
-        let i = 0;
-        while (true) {
-            if (result.length <= i) {
-                result = [...result, v];
-                break;
-            }
-            const old = result[i];
-            if (old.length === 0n) {
-                result = result.toSpliced(i, 1, v);
-                break;
-            }
-            result = result.toSpliced(i, 1, unpackEmpty);
-            v = unpackConcat(old)(v);
-            i++;
-        }
-    }
-    return pack(result.reduce((p, c) => unpackConcat(c)(p), unpackEmpty));
-};
+export const u8ListToVec = (bo) => mapUnwrap(tryU8ListToVec(bo));
 const unpackChunkList = ({ unpackSplit }) => (n) => {
     const divUpN2 = divUp(n << 1n);
     return u => {

package/fs/types/bit_vec/proof.f.d.ts

@@ -46,6 +46,14 @@ export declare const proof: {
         emptyVec: () => void;
     };
     u8ListToVec: () => () => void;
+    tryListToVecOverflow: () => void;
+    listToVecOverflow: {
+        throw: () => void;
+    };
+    u8ListToVecOverflow: {
+        try: () => void;
+        throw: () => void;
+    };
     u8ListUnaligned: () => void;
     chunkList: {
         empty: () => void;

package/fs/types/bit_vec/proof.f.js

@@ -1,6 +1,7 @@
+import { assertEq } from "../../asserts/module.f.js";
 import { mask } from "../bigint/module.f.js";
 import { asBase, asNominal } from "../nominal/module.f.js";
-import { length, empty, uint, vec, lsb, msb, repeat, vec8, u8ListToVec, u8List, chunkList, fromSentinel } from "./module.f.js";
+import { length, empty, uint, vec, lsb, msb, repeat, vec8, maxLength, u8ListToVec, tryU8ListToVec, u8List, chunkList, fromSentinel } from "./module.f.js";
 import { repeat as listRepeat, toArray } from "../list/module.f.js";
 const unsafeVec = (a) => asNominal(a);
 // 0x8 = 0b1000 = 0 + 8
@@ -11,11 +12,6 @@ const unsafeVec = (a) => asNominal(a);
 // 0xD = 0b1101 = 5 + 8
 // 0xE = 0b1110 = 6 + 8
 // 0xF = 0b1111 = 7 + 8
-const assertEq = (a, b) => {
-    if (a !== b) {
-        throw [a, b];
-    }
-};
 const assertEq2 = ([a0, a1], [b0, b1]) => {
     assertEq(a0, b0);
     assertEq(a1, b1);
@@ -504,6 +500,28 @@ export const proof = {
             }
         };
     },
+    tryListToVecOverflow: () => {
+        const list = [vec(maxLength)(1n), vec(1n)(1n)];
+        assertEq(lsb.tryListToVec(list), null);
+        assertEq(msb.tryListToVec(list), null);
+    },
+    listToVecOverflow: {
+        // Same oversized input, but through the throwing `listToVec` wrapper.
+        throw: () => {
+            const list = { first: vec(maxLength + 1n)(1n), tail: null };
+            lsb.listToVec(list);
+        },
+    },
+    u8ListToVecOverflow: {
+        // 131_073 bytes is 8 bits past `maxLength`; same null/throw split as
+        // `tryListToVec`/`listToVec` above, exercised through the byte-list API.
+        try: () => {
+            assertEq(tryU8ListToVec(msb)(listRepeat(0x12)(131_073)), null);
+        },
+        throw: () => {
+            u8ListToVec(msb)(listRepeat(0x12)(131_073));
+        },
+    },
     u8ListUnaligned: () => {
         const x = vec(9n)(0x83n);
         const a = toArray(u8List(msb)(x));

package/fs/types/nullable/module.f.d.ts

@@ -1,8 +1,3 @@
-/**
- * Utilities for nullable (`null`/`undefined`) value handling.
- *
- * @module
- */
 import type { Option } from '../option/module.f.ts';
 export type Nullable<T> = T | null;
 export declare const map: <T, R>(f: (value: T) => R) => (value: Nullable<T>) => Nullable<R>;
@@ -15,3 +10,12 @@ export declare const toOption: <T>(value: Nullable<T>) => Option<T>;
  * property/index lookups) and FunctionalScript (which uses `null` for absence).
  */
 export declare const fromUndefined: <T>(value: T | undefined) => Nullable<T>;
+/**
+ * Extracts the value from a `Nullable`, asserting that it is not `null`.
+ */
+export declare const unwrap: <T>(value: Nullable<T>) => T;
+/**
+ * Lifts a function that signals failure with `null` into one that asserts
+ * success instead, unwrapping the result.
+ */
+export declare const mapUnwrap: <I, T>(f: (i: I) => Nullable<T>) => import("../function/module.f.ts").Func<I, T>;

package/fs/types/nullable/module.f.js

@@ -1,3 +1,10 @@
+/**
+ * Utilities for nullable (`null`/`undefined`) value handling.
+ *
+ * @module
+ */
+import { assert } from "../../asserts/module.f.js";
+import { fn } from "../function/module.f.js";
 export const map = f => value => value === null ? null : f(value);
 export const match = f => none => value => value === null ? none() : f(value);
 export const toOption = (value) => value === null ? [] : [value];
@@ -8,3 +15,15 @@ export const toOption = (value) => value === null ? [] : [value];
  * property/index lookups) and FunctionalScript (which uses `null` for absence).
  */
 export const fromUndefined = (value) => value === undefined ? null : value;
+/**
+ * Extracts the value from a `Nullable`, asserting that it is not `null`.
+ */
+export const unwrap = (value) => {
+    assert(value !== null);
+    return value;
+};
+/**
+ * Lifts a function that signals failure with `null` into one that asserts
+ * success instead, unwrapping the result.
+ */
+export const mapUnwrap = (f) => fn(f).map(unwrap).result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "type": "module",
   "files": [
     "**/*.js",
@@ -44,7 +44,7 @@
   "homepage": "https://github.com/functionalscript/functionalscript#readme",
   "devDependencies": {
     "@playwright/test": "1.61.1",
-    "@types/node": "26.0.1",
+    "@types/node": "26.1.0",
     "typescript": "6.0.3"
   }
 }