functionalscript 0.34.0 → 0.35.1

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,6 @@ export declare const proof: {
     invalidInput: () => void;
     validPadding: () => void;
     knownVectors: () => void;
+    decodeOverflow: () => void;
+    encodeLargeVecIsSlow: () => void;
 };

package/fs/base64/proof.f.js

@@ -1,14 +1,9 @@
-import { empty, vec } from "../types/bit_vec/module.f.js";
+import { assertEq } from "../asserts/module.f.js";
+import { empty, vec, repeat, vec8 } 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,35 @@ 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);
+    },
+    // Regression guard: `encode` used to be quadratic in the input size, not
+    // linear. `baseN`'s `vecToString` (`fs/base_n/module.f.ts`) popped one
+    // 6-bit chunk off the front at a time via `popFront`, and each `popFront`
+    // re-masked the entire remaining bigint through `vec()`'s `m & ui` —
+    // O(remaining length) — so encoding a vector of `n` bits cost O(n²). A
+    // 90,000-byte input took ~5.6s on Node and ~18.4s on Bun (Bun's `bigint`
+    // has a much higher per-operation constant, see PR #1190), reliably
+    // blowing `bun test`'s 5s per-test timeout — the same class of failure
+    // that hit `cas_get content:true` on a comparably-sized binary blob in CI
+    // (PR #1201).
+    //
+    // Fixed by rewriting `vecToString` as a balanced recursive split
+    // (`unpackToString`), mirroring the `chunkList`/`unpackChunkList`
+    // divide-and-conquer already used by `u8List` and by concatenation
+    // (`msb.concat` / `unpackListToVec`, PR #1192) — true O(n log n) now,
+    // since each half is masked to its own length before recursing. The same
+    // call now takes ~50ms on Node and ~225ms on Bun. No timing assertion
+    // (duration varies by engine/machine) — this just exercises the call and
+    // relies on the test runner's own per-test timing to catch a regression.
+    encodeLargeVecIsSlow: () => {
+        const big = repeat(90000n)(vec8(0xffn));
+        const result = encode(big);
+        assertEq(result?.length, 120_000);
+    },
 };

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

@@ -18,9 +18,10 @@ import type { Nullable } from '../types/nullable/module.f.ts';
  */
 export type BaseN = {
     /**
-     * Encodes a bit vector by repeatedly popping `bits`-wide MSB chunks and
-     * indexing them into the alphabet. A trailing partial chunk shorter than
-     * `bits` is left-padded with zeros (the underlying `popFront` semantics).
+     * Encodes a bit vector by splitting it into `bits`-wide MSB chunks
+     * (`chunkList`, a balanced divide-and-conquer split, not a linear scan)
+     * and indexing each into the alphabet. A trailing partial chunk shorter
+     * than `bits` is left-padded with zeros.
      */
     readonly vecToString: (v: Vec) => string;
     /**

package/fs/base_n/module.f.js

@@ -11,8 +11,14 @@
  *
  * @module
  */
-import { msb, length, vec, empty } from "../types/bit_vec/module.f.js";
-const { popFront, concat } = msb;
+import { msb, lsb, vec, chunkList, unpack } from "../types/bit_vec/module.f.js";
+import { fold } from "../types/list/module.f.js";
+import { compose } from "../types/function/module.f.js";
+const { unpackSplit } = msb;
+const { tryListToVec: reversedListToVec } = lsb;
+// `chunkList(msb)` doesn't depend on `bits` or `v` — shared across every
+// `baseN(...)` codec (base64, cbase32, ...).
+const chunkListMsb = chunkList(msb);
 /**
  * Builds a {@link BaseN} codec for a fixed chunk width and alphabet.
  *
@@ -24,31 +30,43 @@ const { popFront, concat } = msb;
  *   `i`/`l`→`1`, `o`→`0`.
  */
 export const baseN = (bits, alphabet, normalize) => {
-    const popFrontN = popFront(bits);
     const vecN = vec(bits);
     const toIndex = normalize === undefined
         ? (c) => alphabet.indexOf(c)
         : (c) => alphabet.indexOf(normalize(c));
+    const unpackSplitBits = unpackSplit(bits);
+    // Converts one `<= bits`-wide chunk (as yielded by `chunkList`, already
+    // masked to its own length) to its alphabet index. A trailing partial
+    // chunk shorter than `bits` is left-padded with zeros: `unpackSplit`'s
+    // shift amount goes negative, which per spec becomes a left shift.
+    const chunkToIndex = (chunk) => {
+        const u = unpack(chunk);
+        return Number(u.length < bits ? unpackSplitBits(u)[0] : u.uint);
+    };
+    // Folds directly over `chunkList`'s lazy list in one pass — faster than
+    // `map` into a second lazy list before joining, since there's no second
+    // list to allocate/traverse.
+    const chunkToString = (chunk) => (acc) => acc + alphabet[chunkToIndex(chunk)];
     return {
-        vecToString: v => {
-            let result = '';
-            while (length(v) > 0n) {
-                const [r, rest] = popFrontN(v);
-                result += alphabet[Number(r)];
-                v = rest;
-            }
-            return result;
-        },
+        // `chunkListMsb(bits)` then `fold(chunkToString)('')` — neither half
+        // depends on `v`, so `compose` builds (and this closure captures)
+        // the composed function once per `baseN(...)` codec; no need to name
+        // the halves separately just to get that one-time build.
+        vecToString: compose(chunkListMsb(bits))(fold(chunkToString)('')),
         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,11 @@ export declare const proof: {
     getMetaLargeMultiChunkBlobNoError: () => void;
     getMetaLargeMultiChunkUtf8Symbols: () => void;
     getMetaLargeMultiChunkTextThenBinary: () => void;
+    getContentLargeBlobTooLargeError: () => void;
+    getContentMissingHashIsError: () => void;
+    getContentBase64InflationOverflowWritesInternalError: () => void;
+    getContentBase64NearBoundarySucceeds: () => void;
+    getContentDoubleEscapedOverflowWritesInternalError: () => void;
     toolsListAdvertisesThreeTools: () => void;
     addReturnsHash: () => void;
     textAddGetMetaRoundTrips: () => void;
@@ -14,6 +19,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;