functionalscript 0.34.0 → 0.35.1

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,22 @@ 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));
+// 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. Small enough to stay clear of the
+// separate `base64Encode`-near-`maxLength` padding bug (see `base64OfA` above).
+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 = {
     // Both chunks repeated ASCII → text/plain, no error on a > 128 KiB blob.
     getMetaLargeMultiChunkBlobNoError: largeMultiChunkBlobMeta(asciiChunk, asciiChunk, 'text', 'text/plain'),
@@ -115,6 +166,103 @@ 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 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 `fs/mcp/stdio/module.f.ts` `writeResponse`.
+    //
+    // This test originally timed out under `bun test`'s native 5s per-test
+    // limit (12-14s observed in CI on PR #1201) — the cost was in
+    // `base64Encode`, quadratic before the `baseN.vecToString` fix (see
+    // `fs/base64/proof.f.ts` `encodeLargeVecIsSlow`). Now well under budget on
+    // both engines.
+    getContentBase64InflationOverflowWritesInternalError: () => {
+        const root = { 'home': { 'user': { 'cas_upload': { 'big': [oversizedBase64Chunk] } } } };
+        const [addResp] = runStdio(root)([
+            call(2, 'cas_add', { content: '/home/user/cas_upload/big', type: 'url' }),
+        ]);
+        const hash = textOf(addResp);
+        const [, getResp] = runStdio(root)([
+            call(2, 'cas_add', { content: '/home/user/cas_upload/big', type: 'url' }),
+            call(3, 'cas_get', { hash, content: true }),
+        ]);
+        const err = getResp;
+        assertEq(err.error?.code, -32603);
+        assertEq(err.id, 3);
+    },
+    // 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 = { 'home': { 'user': { 'cas_upload': { 'big': [boundaryBase64Chunk] } } } };
+        const [addResp] = runStdio(root)([
+            call(2, 'cas_add', { content: '/home/user/cas_upload/big', type: 'url' }),
+        ]);
+        const hash = textOf(addResp);
+        const [, getResp] = runStdio(root)([
+            call(2, 'cas_add', { content: '/home/user/cas_upload/big', type: 'url' }),
+            call(3, '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. 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 +364,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.