functionalscript 0.31.1 → 0.32.1

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

@@ -63,8 +63,6 @@
  * @module
  */
 import { string, option, or, boolean } from "../../types/rtti/module.f.js";
-import { validate } from "../../types/rtti/validate/module.f.js";
-import { toJsonSchema } from "../../json/schema/module.f.js";
 import { pure } from "../../effects/module.f.js";
 import { create } from "../../effects/memory/module.f.js";
 import { cBase32ToVec, vecToCBase32 } from "../../cbase32/module.f.js";
@@ -74,7 +72,7 @@ import { detect } from "../../mime/module.f.js";
 import { length as bitVecLength } from "../../types/bit_vec/module.f.js";
 import { readFile } from "../../effects/node/module.f.js";
 import { stdioTransport } from "../../mcp/stdio/module.f.js";
-import { mcpStep, uninitializedState, } from "../../mcp/module.f.js";
+import { mcpStep, uninitializedState, toolEntry, fromRegistry, errorResult, } from "../../mcp/module.f.js";
 import { fromVec } from "../../text/utf8/module.f.js";
 // ── Argument schemas (declared once, used for both inputSchema and validate) ─────
 /** Arguments for `cas_add`: content to store, with optional encoding type. */
@@ -83,27 +81,91 @@ export const casAddArgs = { content: string, type: option(or(or('text', 'base64'
 export const casGetArgs = { hash: string, content: option(boolean) };
 /** Arguments for `cas_list`: none. */
 export const casListArgs = {};
-// ── Tool descriptors ────────────────────────────────────────────────────────────
-const casAddTool = {
-    name: 'cas_add',
-    description: 'Store content and return its hash (cBase32). Pass type:"base64" for binary; type:"url" to read from a filesystem path; omit or pass type:"text" for UTF-8 text (default).',
-    inputSchema: toJsonSchema(casAddArgs),
-};
-const casGetTool = {
-    name: 'cas_get',
-    description: '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.',
-    inputSchema: toJsonSchema(casGetArgs),
-};
-const casListTool = {
-    name: 'cas_list',
-    description: 'List all stored content hashes (cBase32), one per line.',
-    inputSchema: toJsonSchema(casListArgs),
-};
+// ── Tool registry ──────────────────────────────────────────────────────────────
+/** Registry of all CAS tools. */
+const casToolRegistry = (c, toUrl) => [
+    toolEntry('cas_add', 'Store content and return its hash (cBase32). Pass type:"base64" for binary; type:"url" to read from a filesystem path; omit or pass type:"text" for UTF-8 text (default).', casAddArgs, ({ type, content }) => {
+        let x;
+        switch (type) {
+            case 'url':
+                x = readFile(content).step(([t, v]) => pure(t === 'error'
+                    ? `cannot read file: ${content}: ${v}`
+                    : v));
+                break;
+            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))
+            : c.write(value).step(hash => pure(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 => {
+        const key = cBase32ToVec(r.hash);
+        if (key === null) {
+            return pure(errorResult(`invalid cBase32 hash: ${r.hash}`));
+        }
+        return c.read(key).step(value => {
+            if (value === undefined) {
+                return pure(errorResult(`no such hash: ${r.hash}`));
+            }
+            const byteLength = Number(bitVecLength(value) / 8n);
+            // Phase 1: magic-byte sniffing for known binary formats.
+            const detectedMime = detect(value);
+            if (detectedMime !== null) {
+                const url = toUrl?.(key);
+                const meta = {
+                    length: byteLength,
+                    mime_type: detectedMime,
+                    type: 'base64',
+                    ...(url !== undefined && { url })
+                };
+                if (r.content === true) {
+                    const blob = base64Encode(value);
+                    return pure(blob === null
+                        ? errorResult(`content is not byte-aligned: ${r.hash}`)
+                        : okResult(JSON.stringify({ ...meta, content: blob })));
+                }
+                return pure(okResult(JSON.stringify(meta)));
+            }
+            // Phase 2: UTF-8 validation — text if valid, octet-stream otherwise.
+            const str = fromVec(value);
+            const url = toUrl?.(key);
+            if (str !== null) {
+                const meta = {
+                    length: byteLength,
+                    mime_type: 'text/plain',
+                    type: 'text',
+                    ...(url !== undefined && { url })
+                };
+                return pure(r.content === true
+                    ? okResult(JSON.stringify({ ...meta, content: str }))
+                    : okResult(JSON.stringify(meta)));
+            }
+            const meta = {
+                length: byteLength,
+                mime_type: 'application/octet-stream',
+                type: 'base64',
+                ...(url !== undefined && { url })
+            };
+            if (r.content === true) {
+                const blob = base64Encode(value);
+                return pure(blob === null
+                    ? errorResult(`content is not byte-aligned: ${r.hash}`)
+                    : okResult(JSON.stringify({ ...meta, content: blob })));
+            }
+            return pure(okResult(JSON.stringify(meta)));
+        });
+    }),
+    toolEntry('cas_list', 'List all stored content hashes (cBase32), one per line.', casListArgs, () => c.list().step(hashes => pure(okResult(hashes.map(vecToCBase32).join('\n'))))),
+];
 // ── Result helpers ──────────────────────────────────────────────────────────────
 /** A successful single-text-block tool result. */
 const okResult = (text) => ({ content: [{ type: 'text', text }] });
-/** A tool-level failure: in-band `isError` result with a text explanation. */
-const errorResult = (text) => ({ content: [{ type: 'text', text }], isError: true });
 // ── Handlers ────────────────────────────────────────────────────────────────────
 /**
  * MCP handlers for an injected `Cas<O>` — generic in `O` exactly like `Cas`
@@ -113,95 +175,7 @@ const errorResult = (text) => ({ content: [{ type: 'text', text }], isError: tru
  * the blob on the local filesystem. When absent (e.g. memory-backed tests),
  * `url` is omitted.
  */
-export const casMcpHandlers = (c, toUrl) => ({
-    toolsList: () => pure({ tools: [casAddTool, casGetTool, casListTool] }),
-    toolsCall: ({ name, arguments: args }) => {
-        const a = args === undefined ? {} : args;
-        switch (name) {
-            case 'cas_add': {
-                const [t, r] = validate(casAddArgs)(a);
-                if (t === 'error') {
-                    return pure(errorResult(`invalid arguments: ${r.message}`));
-                }
-                const encoding = r.type ?? 'text';
-                if (encoding === 'url') {
-                    return readFile(r.content).step(result => {
-                        if (result[0] === 'error') {
-                            return pure(errorResult(`cannot read file: ${r.content}: ${result[1]}`));
-                        }
-                        return c.write(result[1]).step(hash => pure(okResult(vecToCBase32(hash))));
-                    });
-                }
-                let value;
-                if (encoding === 'base64') {
-                    value = base64Decode(r.content);
-                    if (value === null) {
-                        return pure(errorResult(`invalid base64 content: ${r.content}`));
-                    }
-                }
-                else {
-                    value = utf8(r.content);
-                }
-                return c.write(value).step(hash => pure(okResult(vecToCBase32(hash))));
-            }
-            case 'cas_get': {
-                const [t, r] = validate(casGetArgs)(a);
-                if (t === 'error') {
-                    return pure(errorResult(`invalid arguments: ${r.message}`));
-                }
-                const key = cBase32ToVec(r.hash);
-                if (key === null) {
-                    return pure(errorResult(`invalid cBase32 hash: ${r.hash}`));
-                }
-                return c.read(key).step(value => {
-                    if (value === undefined) {
-                        return pure(errorResult(`no such hash: ${r.hash}`));
-                    }
-                    const byteLength = Number(bitVecLength(value) / 8n);
-                    // Phase 1: magic-byte sniffing for known binary formats.
-                    const detectedMime = detect(value);
-                    if (detectedMime !== null) {
-                        const url = toUrl?.(key);
-                        const meta = { length: byteLength, mime_type: detectedMime, type: 'base64', ...(url !== undefined && { url }) };
-                        if (r.content === true) {
-                            const blob = base64Encode(value);
-                            if (blob === null) {
-                                return pure(errorResult(`content is not byte-aligned: ${r.hash}`));
-                            }
-                            return pure(okResult(JSON.stringify({ ...meta, content: blob })));
-                        }
-                        return pure(okResult(JSON.stringify(meta)));
-                    }
-                    // Phase 2: UTF-8 validation — text if valid, octet-stream otherwise.
-                    const str = fromVec(value);
-                    const url = toUrl?.(key);
-                    if (str !== null) {
-                        const meta = { length: byteLength, mime_type: 'text/plain', type: 'text', ...(url !== undefined && { url }) };
-                        if (r.content === true) {
-                            return pure(okResult(JSON.stringify({ ...meta, content: str })));
-                        }
-                        return pure(okResult(JSON.stringify(meta)));
-                    }
-                    const meta = { length: byteLength, mime_type: 'application/octet-stream', type: 'base64', ...(url !== undefined && { url }) };
-                    if (r.content === true) {
-                        const blob = base64Encode(value);
-                        if (blob === null) {
-                            return pure(errorResult(`content is not byte-aligned: ${r.hash}`));
-                        }
-                        return pure(okResult(JSON.stringify({ ...meta, content: blob })));
-                    }
-                    return pure(okResult(JSON.stringify(meta)));
-                });
-            }
-            case 'cas_list': {
-                return c.list().step(hashes => pure(okResult(hashes.map(vecToCBase32).join('\n'))));
-            }
-            default: {
-                return pure(errorResult(`unknown tool: ${name}`));
-            }
-        }
-    },
-});
+export const casMcpHandlers = (c, toUrl) => fromRegistry(casToolRegistry(c, toUrl));
 // ── Session configuration ───────────────────────────────────────────────────────
 /**
  * Static MCP configuration for the CAS server: advertises the `tools`

package/fs/cas/module.f.js

@@ -129,14 +129,6 @@ export const commands = [
                 .step(forEachStep(j => log(vecToCBase32(j))))
                 .step(() => pure(0));
         },
-    },
-    {
-        names: ['mcp'],
-        description: 'Run an MCP server over stdio exposing the CAS as tools',
-        handler: ({ home }) => {
-            const c = cas(sha256)(fileKvStore(home));
-            return casMcpServer(c, hash => join(home, toPath(hash))).step(() => pure(0));
-        },
-    },
+    }
 ];
 export const main = dispatch(commands);

package/fs/effects/node/module.f.d.ts

@@ -31,6 +31,12 @@ export type MakeDirectoryOptions = {
 };
 export type Mkdir = readonly ['mkdir', (path: string, options?: MakeDirectoryOptions) => IoResult<void>];
 export declare const mkdir: Func<Mkdir>;
+/**
+ * Reads a file as a bit vector. File size is limited to 131,072 bytes (128 KiB)
+ * to respect Bun's `bigint` size constraint (1,048,575 bits), which is the
+ * minimal limit across all runtime environments supported by FunctionalScript.
+ * Files exceeding this limit will fail with a validation error.
+ */
 export type ReadFile = readonly ['readFile', (path: string) => IoResult<Vec>];
 export declare const readFile: Func<ReadFile>;
 /**

package/fs/effects/node/module.js

@@ -35,6 +35,7 @@ import {} from "./module.f.js";
 import { asBase, asNominal } from "../../types/nominal/module.f.js";
 import { error, ok } from "../../types/result/module.f.js";
 import { fromVec, listToVec, toVec } from "../../types/uint8array/module.f.js";
+import { maxLengthBytes } from "../../types/bit_vec/module.f.js";
 /**
  * Narrowed structural view of `node:http`'s `createServer`. The official types
  * declare `method`/`url` optional and header values as
@@ -57,8 +58,9 @@ const collect = async (v) => {
     }
     return result;
 };
-const { mkdir, readFile, readdir, writeFile, rm, access } = fs.promises;
+const { mkdir, readFile, readdir, writeFile, rm, access, stat } = fs.promises;
 const { exec } = childProcess;
+const maxFileSizeBytes = Number(maxLengthBytes);
 const prefix = 'file:///';
 const asyncImport = (v) => {
     const s0 = v.includes(':') || v.startsWith('/') ? v : concat(process.cwd())(v);
@@ -161,7 +163,14 @@ const runNodeEffect = asyncRun({
         return toVec(new Uint8Array(await response.arrayBuffer()));
     }),
     mkdir: (...p) => tc(async () => { await mkdir(...p); }),
-    readFile: path => tc(async () => toVec(await readFile(path))),
+    readFile: path => tc(async () => {
+        const fileStats = await stat(path);
+        // if the file is too big, toVec should fail anyway but in this case we don't want to load the file.
+        if (fileStats.size > maxFileSizeBytes) {
+            throw new Error(`File size ${fileStats.size} exceeds maximum allowed size of ${Number(maxFileSizeBytes)} bytes`);
+        }
+        return toVec(await readFile(path));
+    }),
     readdir: (path, r) => tc(async () => (await readdir(path, { ...r, withFileTypes: true }))
         .map(v => ({
         name: v.name,
@@ -191,8 +200,7 @@ const runNodeEffect = asyncRun({
                 .writeHead(status, outHeaders)
                 .end(fromVec(outBody));
         };
-        const server = asNominal(createServer(nodeRl));
-        return server;
+        return asNominal(createServer(nodeRl));
     },
     listen: async (server, port) => {
         const s = asBase(server);

package/fs/effects/node/proof.f.d.ts

@@ -11,6 +11,7 @@ export declare const proof: {
         nested: () => void;
         noSuchFile: () => void;
         nestedPath: () => void;
+        withinLimit: () => void;
     };
     readUtf8File: {
         ok: () => void;

package/fs/effects/node/proof.f.js

@@ -127,6 +127,22 @@ export const proof = {
             if (result.code !== 'ENOENT') {
                 throw result;
             }
+        },
+        withinLimit: () => {
+            // Test with a small file well within the 131,072 byte limit
+            const initial = {
+                ...emptyState,
+                root: {
+                    smallFile: vec8(0x2an),
+                },
+            };
+            const [_, [t, result]] = virtual(initial)(readFile('smallFile'));
+            if (t === 'error') {
+                throw result;
+            }
+            if (!isVec(result)) {
+                throw result;
+            }
         }
     },
     readUtf8File: {

package/fs/fjs/module.f.js

@@ -9,6 +9,11 @@ import { commands as casCommands } from "../cas/module.f.js";
 import { main as ciMain } from "../ci/module.f.js";
 import { import_ } from "../effects/node/module.f.js";
 import { dispatch } from "../cli/module.f.js";
+import { casMcpServer } from "../cas/mcp/module.f.js";
+import { cas, fileKvStore, toPath } from "../cas/module.f.js";
+import { sha256 } from "../crypto/sha2/module.f.js";
+import { join } from "../path/module.f.js";
+import { pure } from "../effects/module.f.js";
 const commands = [
     {
         names: ['test', 't'],
@@ -25,6 +30,14 @@ const commands = [
         description: 'Content-addressable storage operations',
         handler: casCommands,
     },
+    {
+        names: ['mcp', 'm'],
+        description: 'Run an MCP server over stdio exposing the CAS as tools',
+        handler: ({ home }) => {
+            const c = cas(sha256)(fileKvStore(home));
+            return casMcpServer(c, hash => join(home, toPath(hash))).step(() => pure(0));
+        },
+    },
     {
         names: ['ci', 'i'],
         description: 'Generate the GitHub Actions CI workflow',

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

@@ -3,6 +3,7 @@ import type { Ts } from '../types/rtti/ts/module.f.ts';
 import { type Operation, type Effect } from '../effects/module.f.ts';
 import { type Key, type MemOp } from '../effects/memory/module.f.ts';
 import { type Response } from '../json/rpc/module.f.ts';
+import type { Type } from '../types/rtti/module.f.ts';
 /** Name + version pair sent in `initialize` requests and responses. */
 export declare const implementation: {
     readonly name: import("../types/rtti/module.f.ts").String;
@@ -139,6 +140,51 @@ export type McpHandlers<O extends Operation> = {
     readonly toolsList: (params: ToolsListParams) => Effect<O, ToolsListResult>;
     readonly toolsCall: (params: ToolsCallParams) => Effect<O, ToolsCallResult>;
 };
+/**
+ * A single declarative tool entry combining metadata, input schema, and type-safe handler.
+ *
+ * The handler receives pre-validated arguments of type `Ts<inputRtti>`, eliminating the need
+ * for manual validation or type casting. All validation is encapsulated in the entry.
+ */
+export type ToolEntry<O extends Operation> = {
+    readonly name: string;
+    readonly description: string;
+    readonly inputRtti: Type;
+    readonly handle: (args: Unknown) => Effect<O, ToolsCallResult>;
+};
+/**
+ * Creates a type-safe tool entry that binds an RTTI schema with a handler.
+ *
+ * The builder validates arguments at runtime using the RTTI and passes pre-validated
+ * arguments (typed as `Ts<T>`) to the handler. This eliminates manual validation
+ * boilerplate and type assertions.
+ *
+ * @param name - The tool name (used in `tools/call` requests)
+ * @param description - Human-readable description for `tools/list`
+ * @param inputRtti - Runtime type info for input validation
+ * @param handle - Handler receiving validated arguments of type `Ts<inputRtti>`
+ * @returns A `ToolEntry` ready to be added to a registry
+ */
+export declare const toolEntry: <T extends Type, O extends Operation>(name: string, description: string, inputRtti: T, handle: (args: Ts<T>) => Effect<O, ToolsCallResult>) => ToolEntry<O>;
+/**
+ * Helper to create a tool-level error result with plain text explanation.
+ *
+ * @param text - The error message to return to the client
+ * @returns A `ToolsCallResult` with `isError: true` and the text explanation
+ */
+export declare const errorResult: (text: string) => ToolsCallResult;
+/**
+ * Builds `McpHandlers` from a registry of tool entries.
+ *
+ * This factory generates `toolsList` and `toolsCall` handlers that work with a
+ * declarative registry, eliminating boilerplate. The `toolsList` handler converts
+ * entries into MCP `Tool` descriptors, and `toolsCall` dispatches by name and
+ * delegates to the appropriate handler.
+ *
+ * @param registry - Array of tool entries
+ * @returns Complete `McpHandlers` ready for use with `mcpStep`
+ */
+export declare const fromRegistry: <O extends Operation>(registry: readonly ToolEntry<O>[]) => McpHandlers<O>;
 /** Top-level handler: maps a raw JSON value to a JSON-RPC response (or `null` for notifications). */
 export type Handle<O extends Operation> = (value: Unknown) => Effect<O, Response | null>;
 /** MCP error -32002: the client called a method before `initialize`. */

package/fs/mcp/module.f.js

@@ -19,6 +19,7 @@ import { pure } from "../effects/module.f.js";
 import { read, write } from "../effects/memory/module.f.js";
 import { decodeRequest, rpcError, invalidRequest, invalidParams, methodNotFound, jsonrpc, } from "../json/rpc/module.f.js";
 import { validate } from "../types/rtti/validate/module.f.js";
+import { toJsonSchema } from "../json/schema/module.f.js";
 // ── Shared ─────────────────────────────────────────────────────────────────────
 /** Name + version pair sent in `initialize` requests and responses. */
 export const implementation = {
@@ -100,6 +101,64 @@ export const toolsCallResult = {
     content: array(contentItem),
     isError: option(boolean),
 };
+/**
+ * Creates a type-safe tool entry that binds an RTTI schema with a handler.
+ *
+ * The builder validates arguments at runtime using the RTTI and passes pre-validated
+ * arguments (typed as `Ts<T>`) to the handler. This eliminates manual validation
+ * boilerplate and type assertions.
+ *
+ * @param name - The tool name (used in `tools/call` requests)
+ * @param description - Human-readable description for `tools/list`
+ * @param inputRtti - Runtime type info for input validation
+ * @param handle - Handler receiving validated arguments of type `Ts<inputRtti>`
+ * @returns A `ToolEntry` ready to be added to a registry
+ */
+export const toolEntry = (name, description, inputRtti, handle) => ({
+    name,
+    description,
+    inputRtti,
+    handle: (a) => {
+        const [t, r] = validate(inputRtti)(a);
+        return t === 'error'
+            ? pure(errorResult(`invalid arguments: ${r.message}`))
+            : handle(r);
+    }
+});
+/**
+ * Helper to create a tool-level error result with plain text explanation.
+ *
+ * @param text - The error message to return to the client
+ * @returns A `ToolsCallResult` with `isError: true` and the text explanation
+ */
+export const errorResult = (text) => ({ content: [{ type: 'text', text }], isError: true });
+/**
+ * Builds `McpHandlers` from a registry of tool entries.
+ *
+ * This factory generates `toolsList` and `toolsCall` handlers that work with a
+ * declarative registry, eliminating boilerplate. The `toolsList` handler converts
+ * entries into MCP `Tool` descriptors, and `toolsCall` dispatches by name and
+ * delegates to the appropriate handler.
+ *
+ * @param registry - Array of tool entries
+ * @returns Complete `McpHandlers` ready for use with `mcpStep`
+ */
+export const fromRegistry = (registry) => ({
+    toolsList: () => {
+        const tools = registry.map(entry => ({
+            name: entry.name,
+            description: entry.description,
+            inputSchema: toJsonSchema(entry.inputRtti),
+        }));
+        return pure({ tools });
+    },
+    toolsCall: ({ name, arguments: args }) => {
+        const entry = registry.find(e => e.name === name);
+        return entry === undefined
+            ? pure(errorResult(`unknown tool: ${name}`))
+            : entry.handle(args === undefined ? {} : args);
+    },
+});
 // ── Lifecycle / capability state machine ───────────────────────────────────────
 const _errResponse = (id) => (error) => ({ jsonrpc, error, id });
 const _okResponse = (id) => (result) => ({ jsonrpc, result, id });

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

@@ -129,6 +129,8 @@ export declare const bitLength: (v: bigint) => bigint;
  * ```
  */
 export declare const mask: (len: bigint) => bigint;
+export declare const maxLength = 1048576n;
+export declare const max: bigint;
 /**
  * Calculates the partial factorial `b!/a!`.
  *

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

@@ -172,7 +172,16 @@ export const bitLength = (v) => log2(abs(v)) + 1n;
  * const result = mask(3n) // 7n
  * ```
  */
-export const mask = (len) => (1n << len) - 1n;
+export const mask = (len) => {
+    // we compute this way to avoid overflowing in Bun when len === maxLength.
+    const r = len & 1n;
+    const h = len >> 1n;
+    const x = (((1n << h) - 1n) << r) | r;
+    return (x << h) | x;
+};
+export const maxLength = 0x100000n;
+// max + 1n // bun throws an error
+export const max = mask(maxLength);
 /**
  * Calculates the partial factorial `b!/a!`.
  *

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

@@ -1,3 +1,27 @@
+/**
+ * Bit vectors that normalize the most-significant bit using signed `bigint` values.
+ *
+ * A value whose top bit is already set remains positive, while other values are
+ * negated after toggling the leading bit so the stop bit is always `1`. The sign bit
+ * therefore acts as the stop bit that encodes the logical length of the vector.
+ *
+ * MSb is most-significant bit first.
+ *
+ * ```
+ * - byte: 0x53 = 0b0101_0011
+ * -                0123_4567
+ * ```
+ *
+ * LSb is least-significant bit first.
+ *
+ * ```
+ * - byte: 0x53 = 0b0101_0011
+ * -                7654_3210
+ * ```
+ *
+ * @module
+ */
+import { maxLength } from '../bigint/module.f.ts';
 import type { Binary, Fold, Reduce as OpReduce } from '../function/operator/module.f.ts';
 import { type List, type Thunk } from '../list/module.f.ts';
 import { type Nominal } from '../nominal/module.f.ts';
@@ -6,6 +30,13 @@ import { type Sign } from '../function/compare/module.f.ts';
  * A vector of bits represented as a signed `bigint`.
  */
 export type Vec = Nominal<'bit_vec', '1a23a4336197e6158b6936cad34e90d146cd84b9b40ff7ab75a17c6d79e31d89', bigint>;
+/**
+ * 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
+ * across all runtime environments supported by FunctionalScript.
+ */
+export { maxLength };
+export declare const maxLengthBytes: bigint;
 /**
  * An empty vector of bits.
  */
@@ -251,4 +282,3 @@ export declare const u8List: (bo: BitOrder) => (v: Vec) => Thunk<number>;
  */
 export declare const repeat: Fold<bigint, Vec>;
 export declare const isVec: <T>(v: Vec | T) => v is Vec;
-export {};

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

@@ -21,12 +21,19 @@
  *
  * @module
  */
-import { bitLength, divUp, mask, xor } from "../bigint/module.f.js";
+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 { 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";
+/**
+ * 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
+ * across all runtime environments supported by FunctionalScript.
+ */
+export { maxLength };
+export const maxLengthBytes = maxLength >> 3n;
 /**
  * An empty vector of bits.
  */

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

@@ -10,7 +10,7 @@
  * @module
  */
 import { utf8, utf8ToString } from "../../text/module.f.js";
-import { msb, u8List, u8ListToVec } from "../bit_vec/module.f.js";
+import { maxLengthBytes, msb, u8List, u8ListToVec } from "../bit_vec/module.f.js";
 import { compose } from "../function/module.f.js";
 import { flat, fromArrayLike, iterable, map } from "../list/module.f.js";
 const u8ListToVecMsb = u8ListToVec(msb);
@@ -18,7 +18,12 @@ const u8ListMsb = u8List(msb);
 /**
  * Converts a Uint8Array into an MSB-first bit vector.
  */
-export const toVec = (input) => u8ListToVecMsb(fromArrayLike(input));
+export const toVec = (input) => {
+    if (input.length > maxLengthBytes) {
+        throw "the array is too big";
+    }
+    return u8ListToVecMsb(fromArrayLike(input));
+};
 const m = map(fromArrayLike);
 export const listToVec = (input) => u8ListToVecMsb(flat(m(input)));
 /**

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

@@ -9,4 +9,6 @@ export declare const proof: {
     decodeUtf8Multibyte: () => void;
     utf8RoundTrip: () => void;
     listToVec: () => void;
+    maxLength: () => import("../bit_vec/module.f.ts").Vec;
+    throw: () => import("../bit_vec/module.f.ts").Vec;
 };

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

@@ -1,4 +1,4 @@
-import { vec } from "../bit_vec/module.f.js";
+import { maxLength, maxLengthBytes, vec } from "../bit_vec/module.f.js";
 import { toVec, fromVec, listToVec, decodeUtf8, encodeUtf8 } from "./module.f.js";
 import { strictEqual } from "../function/operator/module.f.js";
 import { equal, fromArrayLike } from "../list/module.f.js";
@@ -58,5 +58,7 @@ export const proof = {
     listToVec: () => {
         const result = listToVec([Uint8Array.from([1, 2]), Uint8Array.from([3])]);
         assertArrayEq(fromVec(result), Uint8Array.from([1, 2, 3]));
-    }
+    },
+    maxLength: () => toVec(new Uint8Array(Number(maxLengthBytes))),
+    throw: () => toVec(new Uint8Array(Number(maxLengthBytes) + 1)),
 };

package/nanvm-lib/tests/proof.f.d.ts

@@ -88,4 +88,26 @@ export declare const proof: {
         };
         function: () => void;
     };
+    stringCoercion: {
+        number: () => void;
+        bool: () => void;
+        null: () => void;
+        undefined: () => void;
+        bigint: () => void;
+        array: () => void;
+        func: () => void;
+        object: {
+            norm: () => void;
+            toString: () => void;
+            toStringThrow: {
+                throw: () => void;
+            };
+            toStringNotFunc: {
+                throw: () => void;
+            };
+            toStringNonPrimitive: {
+                throw: () => void;
+            };
+        };
+    };
 };

package/nanvm-lib/tests/proof.f.js

@@ -12,6 +12,7 @@ const nanRes = (op) => (n) => {
         throw result;
     }
 };
+const stringCoercion = String;
 export const proof = {
     eq: () => {
         const e = (a) => (b) => {
@@ -172,5 +173,107 @@ export const proof = {
             },
             function: () => nan(op(() => { }))
         };
+    },
+    stringCoercion: {
+        number: () => {
+            if (stringCoercion(123) !== '123') {
+                throw [123, 'toString', '123'];
+            }
+            if (stringCoercion(-456) !== '-456') {
+                throw [-456, 'toString', '-456'];
+            }
+            if (stringCoercion(0) !== '0') {
+                throw [0, 'toString', '0'];
+            }
+            if (stringCoercion(-0) !== '0') {
+                throw [0, 'toString', '0'];
+            }
+            if (stringCoercion(1 / (-0)) !== '-Infinity') {
+                throw [0, 'toString', '-Infinity'];
+            }
+            if (stringCoercion(Infinity) !== 'Infinity') {
+                throw [Infinity, 'toString', 'Infinity'];
+            }
+            if (stringCoercion(-Infinity) !== '-Infinity') {
+                throw [-Infinity, 'toString', '-Infinity'];
+            }
+            if (stringCoercion(1 / -Infinity) !== '0') {
+                throw [-Infinity, 'toString', '0'];
+            }
+            if (stringCoercion(NaN) !== 'NaN') {
+                throw [NaN, 'toString', 'NaN'];
+            }
+        },
+        bool: () => {
+            if (stringCoercion(true) !== 'true') {
+                throw [true, 'toString', 'true'];
+            }
+            if (stringCoercion(false) !== 'false') {
+                throw [false, 'toString', 'false'];
+            }
+        },
+        null: () => {
+            if (stringCoercion(null) !== 'null') {
+                throw [null, 'toString', 'null'];
+            }
+        },
+        undefined: () => {
+            if (stringCoercion(undefined) !== 'undefined') {
+                throw [undefined, 'toString', 'undefined'];
+            }
+        },
+        bigint: () => {
+            if (stringCoercion(123n) !== '123') {
+                throw [123n, 'toString', '123'];
+            }
+            if (stringCoercion(-456n) !== '-456') {
+                throw [-456n, 'toString', '-456'];
+            }
+        },
+        array: () => {
+            const arr = [1, 2, 3];
+            if (stringCoercion(arr) !== '1,2,3') {
+                throw [arr, 'toString', '1,2,3'];
+            }
+        },
+        func: () => {
+            const func = () => 5;
+            if (typeof stringCoercion(func) !== 'string') {
+                throw [func, 'toString'];
+            }
+            // if (stringCoercion(func) !== '() => 5') { throw [func, 'toString', 'function result'] }
+        },
+        object: {
+            norm: () => {
+                const obj = { a: 1, b: 2 };
+                if (stringCoercion(obj) !== '[object Object]') {
+                    throw [obj, 'toString', '[object Object]'];
+                }
+            },
+            toString: () => {
+                const x = { toString: () => 'custom string' };
+                if (stringCoercion(x) !== 'custom string') {
+                    throw [x, 'toString', 'custom string'];
+                }
+            },
+            toStringThrow: {
+                throw: () => {
+                    const x = { toString: () => { throw new Error('Custom error'); } };
+                    stringCoercion(x);
+                }
+            },
+            toStringNotFunc: {
+                throw: () => {
+                    const x = { toString: 'hello' };
+                    stringCoercion(x);
+                }
+            },
+            toStringNonPrimitive: {
+                throw: () => {
+                    const x = { toString: () => [] };
+                    stringCoercion(x);
+                }
+            }
+        }
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.31.1",
+  "version": "0.32.1",
   "type": "module",
   "files": [
     "**/*.js",

package/nanvm-lib/tests/vm/proof.f.d.ts

@@ -1,24 +0,0 @@
-export declare const proof: {
-    stringCoercion: {
-        number: () => void;
-        bool: () => void;
-        null: () => void;
-        undefined: () => void;
-        bigint: () => void;
-        array: () => void;
-        func: () => void;
-        object: {
-            norm: () => void;
-            toString: () => void;
-            toStringThrow: {
-                throw: () => void;
-            };
-            toStringNotFunc: {
-                throw: () => void;
-            };
-            toStringNonPrimitive: {
-                throw: () => void;
-            };
-        };
-    };
-};

package/nanvm-lib/tests/vm/proof.f.js

@@ -1,105 +0,0 @@
-const stringCoercion = String;
-export const proof = {
-    stringCoercion: {
-        number: () => {
-            if (stringCoercion(123) !== '123') {
-                throw [123, 'toString', '123'];
-            }
-            if (stringCoercion(-456) !== '-456') {
-                throw [-456, 'toString', '-456'];
-            }
-            if (stringCoercion(0) !== '0') {
-                throw [0, 'toString', '0'];
-            }
-            if (stringCoercion(-0) !== '0') {
-                throw [0, 'toString', '0'];
-            }
-            if (stringCoercion(1 / (-0)) !== '-Infinity') {
-                throw [0, 'toString', '-Infinity'];
-            }
-            if (stringCoercion(Infinity) !== 'Infinity') {
-                throw [Infinity, 'toString', 'Infinity'];
-            }
-            if (stringCoercion(-Infinity) !== '-Infinity') {
-                throw [-Infinity, 'toString', '-Infinity'];
-            }
-            if (stringCoercion(1 / -Infinity) !== '0') {
-                throw [-Infinity, 'toString', '0'];
-            }
-            if (stringCoercion(NaN) !== 'NaN') {
-                throw [NaN, 'toString', 'NaN'];
-            }
-        },
-        bool: () => {
-            if (stringCoercion(true) !== 'true') {
-                throw [true, 'toString', 'true'];
-            }
-            if (stringCoercion(false) !== 'false') {
-                throw [false, 'toString', 'false'];
-            }
-        },
-        null: () => {
-            if (stringCoercion(null) !== 'null') {
-                throw [null, 'toString', 'null'];
-            }
-        },
-        undefined: () => {
-            if (stringCoercion(undefined) !== 'undefined') {
-                throw [undefined, 'toString', 'undefined'];
-            }
-        },
-        bigint: () => {
-            if (stringCoercion(123n) !== '123') {
-                throw [123n, 'toString', '123'];
-            }
-            if (stringCoercion(-456n) !== '-456') {
-                throw [-456n, 'toString', '-456'];
-            }
-        },
-        array: () => {
-            const arr = [1, 2, 3];
-            if (stringCoercion(arr) !== '1,2,3') {
-                throw [arr, 'toString', '1,2,3'];
-            }
-        },
-        func: () => {
-            const func = () => 5;
-            if (typeof stringCoercion(func) !== 'string') {
-                throw [func, 'toString'];
-            }
-            // if (stringCoercion(func) !== '() => 5') { throw [func, 'toString', 'function result'] }
-        },
-        object: {
-            norm: () => {
-                const obj = { a: 1, b: 2 };
-                if (stringCoercion(obj) !== '[object Object]') {
-                    throw [obj, 'toString', '[object Object]'];
-                }
-            },
-            toString: () => {
-                const x = { toString: () => 'custom string' };
-                if (stringCoercion(x) !== 'custom string') {
-                    throw [x, 'toString', 'custom string'];
-                }
-            },
-            toStringThrow: {
-                throw: () => {
-                    const x = { toString: () => { throw new Error('Custom error'); } };
-                    stringCoercion(x);
-                }
-            },
-            toStringNotFunc: {
-                throw: () => {
-                    const x = { toString: 'hello' };
-                    stringCoercion(x);
-                }
-            },
-            toStringNonPrimitive: {
-                throw: () => {
-                    const x = { toString: () => [] };
-                    stringCoercion(x);
-                }
-            }
-        }
-    }
-};