functionalscript 0.32.2 → 0.32.4

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

@@ -1,9 +1,9 @@
 import { type Effect, type Operation } from '../../effects/module.f.ts';
 import { type MemOp } from '../../effects/memory/module.f.ts';
 import { type Vec } from '../../types/bit_vec/module.f.ts';
-import { type Read, type ReadFile, type Write } from '../../effects/node/module.f.ts';
+import { type Mkdir, type RandomInt, type Read, type ReadBytes, type Rename, type Write } from '../../effects/node/module.f.ts';
 import { type McpConfig, type McpHandlers } from '../../mcp/module.f.ts';
-import type { Cas } from '../module.f.ts';
+import { type Cas } from '../module.f.ts';
 /** Arguments for `cas_add`: content to store, with optional encoding type. */
 export declare const casAddArgs: {
     readonly content: import("../../types/rtti/module.f.ts").String;
@@ -24,7 +24,7 @@ export declare const casListArgs: {};
  * the blob on the local filesystem. When absent (e.g. memory-backed tests),
  * `url` is omitted.
  */
-export declare const casMcpHandlers: <O extends Operation>(c: Cas<O>, home: string, toUrl?: (hash: Vec) => string) => McpHandlers<ReadFile | O>;
+export declare const casMcpHandlers: <O extends Operation>(c: Cas<O>, home: string, toUrl?: (hash: Vec) => string) => McpHandlers<Mkdir | Rename | RandomInt | ReadBytes | O>;
 /**
  * Static MCP configuration for the CAS server: advertises the `tools`
  * capability, identifies the server, and pins the protocol version.
@@ -37,4 +37,4 @@ export declare const casConfig: McpConfig;
  *
  * When `toUrl` is provided, `cas_get` includes the blob's filesystem URL.
  */
-export declare const casMcpServer: <O extends Operation>(c: Cas<O>, home: string, toUrl?: (hash: Vec) => string) => Effect<Read | Write | MemOp | ReadFile | O, void>;
+export declare const casMcpServer: <O extends Operation>(c: Cas<O>, home: string, toUrl?: (hash: Vec) => string) => Effect<Read | Write | MemOp | Mkdir | Rename | RandomInt | ReadBytes | O, void>;

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

@@ -9,9 +9,9 @@
  *
  * ## Tools
  *
- * | Tool       | args                          | CAS call         | result                              |
+ * | Tool       | args                          | action           | result                              |
  * |------------|-------------------------------|------------------|-------------------------------------|
- * | `cas_add`  | `{ content, type? }`          | `c.write(value)` | hash (cBase32)                      |
+ * | `cas_add`  | `{ content, type? }`          | write/upload     | hash (cBase32)                      |
  * | `cas_get`  | `{ hash, content?: boolean }` | `c.read(key)`    | JSON `{length,mime_type,type[,content]}` |
  * | `cas_list` | `{}`                          | `c.list()`       | hashes, one per line                |
  *
@@ -24,8 +24,8 @@
  * - `'base64'`: `content` is RFC 4648 base64, decoded to bytes before storage.
  *   Use this for pre-encoded binary payloads.
  * - `'url'`: `content` is a filesystem path within `$HOME/cas_upload/`; the server
- *   reads the file at that path and stores its raw bytes. Paths outside
- *   `$HOME/cas_upload/` or containing `..` are rejected for security.
+ *   moves the file via the streaming move-hash-move pipeline (no size limit).
+ *   Paths outside `$HOME/cas_upload/` or containing `..` are rejected for security.
  *
  * ## `cas_get` output
  *
@@ -71,9 +71,10 @@ import { decode as base64Decode, encode as base64Encode } from "../../base64/mod
 import { utf8 } from "../../text/module.f.js";
 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 {} from "../../effects/node/module.f.js";
 import { stdioTransport } from "../../mcp/stdio/module.f.js";
 import { mcpStep, uninitializedState, toolEntry, fromRegistry, errorResult, } from "../../mcp/module.f.js";
+import { casUpload } from "../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. */
@@ -87,19 +88,20 @@ export const casListArgs = {};
 const casToolRegistry = (c, home, toUrl) => {
     const casUploadDir = `${home}/cas_upload`;
     return [
-        toolEntry('cas_add', 'Store content and return its hash (cBase32). Pass type:"base64" for binary; type:"url" to read from a filesystem path within $HOME/cas_upload/; 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; 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 }) => {
+            // type:'url' — streaming move-hash-move pipeline (no size limit)
+            if (type === 'url') {
+                if (!content.startsWith(`${casUploadDir}/`) || content.includes('..')) {
+                    return pure(errorResult(`cas_add type:url paths must be within ${casUploadDir}/ — got: ${content}`));
+                }
+                const fileName = content.slice(`${casUploadDir}/`.length);
+                return casUpload(home)(fileName).step(result => pure(result[0] === 'error'
+                    ? errorResult(`upload failed: ${result[1]}`)
+                    : okResult(vecToCBase32(result[1]))));
+            }
+            // type:'text' or 'base64' — resolve content to Vec, store via c.write()
             let x;
             switch (type) {
-                case 'url':
-                    if (!content.startsWith(`${casUploadDir}/`) || content.includes('..')) {
-                        x = pure(`cas_add type:url paths must be within ${casUploadDir}/ — got: ${content}`);
-                    }
-                    else {
-                        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);

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

@@ -27,6 +27,7 @@ export declare const proof: {
     getMetaNoUrlWhenToUrlAbsent: () => void;
     getMetaMissingHashIsError: () => void;
     getMetaInvalidHashIsError: () => void;
+    addUrlFromSubdirectorySucceeds: () => void;
     addUrlFromApprovedDirectorySucceeds: () => void;
     addUrlFromRandomDirectoryIsRejected: () => void;
     addUrlWithPathTraversalIsRejected: () => void;

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

@@ -7,11 +7,13 @@ import { vecToCBase32 } from "../../cbase32/module.f.js";
 import { encode as base64Encode } from "../../base64/module.f.js";
 import { sha256 } from "../../crypto/sha2/module.f.js";
 import { utf8 } from "../../text/module.f.js";
-import { cas } from "../module.f.js";
+import { cas, fileKvStore } from "../module.f.js";
 import { mcpStep, uninitializedState, } from "../../mcp/module.f.js";
 import {} from "../../effects/node/module.f.js";
+import { emptyState, virtual } from "../../effects/node/virtual/module.f.js";
 import { casConfig, casMcpHandlers } from "./module.f.js";
-const initialTestState = { memory: { next: 0, values: {} }, files: {} };
+import { ok as resultOk } from "../../types/result/module.f.js";
+const initialTestState = { memory: { next: 0, values: {} } };
 const mock = {
     memCreate: value => state => {
         const id = `k${state.memory.next}`;
@@ -26,15 +28,12 @@ const mock = {
         const id = asBase(key);
         return [{ ...state, memory: { ...state.memory, values: { ...state.memory.values, [id]: value } } }, undefined];
     },
-    readFile: path => state => {
-        const v = state.files[path];
-        return v !== undefined
-            ? [state, ['ok', v]]
-            : [state, ['error', new Error(`ENOENT: ${path}`)]];
-    },
+    mkdir: (_path, _opts) => state => [state, resultOk(undefined)],
+    rename: (_src, _dst) => _ => { throw new Error('rename not supported in memory mock'); },
+    readBytes: (_path, _offset, _size) => _ => { throw new Error('readBytes not supported in memory mock'); },
+    randomInt: () => _ => { throw new Error('randomInt not supported in memory mock'); },
 };
 const runMem = (effect) => run(mock)(initialTestState)(effect)[1];
-const runMemWithFiles = (files) => (effect) => run(mock)({ memory: { next: 0, values: {} }, files })(effect)[1];
 const memKvStore = (mapKey) => ({
     read: (key) => read(mapKey).step(m => pure(m[vecToCBase32(key)]?.[1])),
     write: (key, value) => read(mapKey).step(m => write(mapKey, { ...m, [vecToCBase32(key)]: [key, value] })),
@@ -54,12 +53,17 @@ const runSession = (msgs, home = '/home/user') => runMem(create({}).step(mapKey
     const step = mcpStep(casConfig)(casMcpHandlers(c, home))(sessionKey);
     return feed(step)(msgs);
 })));
-// Runs a session with a mocked filesystem (for cas_add with type:'url' tests).
-const runSessionWithFiles = (files, home = '/home/user') => (msgs) => runMemWithFiles(files)(create({}).step(mapKey => create(uninitializedState).step(sessionKey => {
-    const c = cas(sha256)(memKvStore(mapKey));
-    const step = mcpStep(casConfig)(casMcpHandlers(c, home))(sessionKey);
-    return feed(step)(msgs);
-})));
+// Runs a session backed by the virtual node runner (for cas_upload which uses
+// Rename/ReadBytes/RandomInt/Mkdir). Uses fileKvStore so upload and get share
+// the same filesystem-backed CAS.
+const runSessionVirtual = (root, home = '/home/user') => (msgs) => {
+    const effect = create(uninitializedState).step(sessionKey => {
+        const c = cas(sha256)(fileKvStore(home));
+        const step = mcpStep(casConfig)(casMcpHandlers(c, home))(sessionKey);
+        return feed(step)(msgs);
+    });
+    return virtual({ ...emptyState, root })(effect)[1];
+};
 // ── Messages ────────────────────────────────────────────────────────────────────
 const init = { jsonrpc: '2.0', method: 'initialize', id: 1,
     params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'c', version: '0' } } };
@@ -211,10 +215,11 @@ export const proof = {
         assert(!('error' in resp));
         assert('result' in resp);
     },
-    // cas_add with type:'url' reads a file from /home/user/cas_upload/ and stores it.
+    // cas_add with type:'url' streams a file from /home/user/cas_upload/ into CAS.
     addUrlStoresFileAndReturnsHash: () => {
         const fileContent = utf8('hello from file');
-        const [addUrlResp] = runSessionWithFiles({ '/home/user/cas_upload/hello.txt': fileContent })([
+        const root = { 'home': { 'user': { 'cas_upload': { 'hello.txt': fileContent } } } };
+        const [addUrlResp] = runSessionVirtual(root)([
             init, initialized,
             call(2, 'cas_add', { content: '/home/user/cas_upload/hello.txt', type: 'url' }),
         ]).slice(2);
@@ -223,23 +228,26 @@ export const proof = {
     },
     addUrlRoundTrips: () => {
         const fileContent = utf8('round-trip content');
-        const msgs = runSessionWithFiles({ '/home/user/cas_upload/rt.txt': fileContent })([
+        const root = { 'home': { 'user': { 'cas_upload': { 'rt.txt': fileContent } } } };
+        // First pass: add to get the hash (deterministic for same content).
+        const [addResp] = runSessionVirtual(root)([
             init, initialized,
             call(2, 'cas_add', { content: '/home/user/cas_upload/rt.txt', type: 'url' }),
         ]).slice(2);
-        const hash = textOf(msgs[0]);
-        const msgs2 = runSessionWithFiles({ '/home/user/cas_upload/rt.txt': fileContent })([
+        const hash = textOf(addResp);
+        // Second pass: add again + get in one session (file re-present in fresh virtual state).
+        const [, getResp] = runSessionVirtual(root)([
             init, initialized,
             call(2, 'cas_add', { content: '/home/user/cas_upload/rt.txt', type: 'url' }),
             call(3, 'cas_get', { hash, content: true }),
         ]).slice(2);
-        assert(!resultOf(msgs2[1]).isError);
-        const result = JSON.parse(textOf(msgs2[1]));
+        assert(!resultOf(getResp).isError);
+        const result = JSON.parse(textOf(getResp));
         assertEq(result.type, 'text');
         assertEq(result.content, 'round-trip content');
     },
     addUrlMissingFileIsError: () => {
-        const [resp] = runSessionWithFiles({})([
+        const [resp] = runSessionVirtual({})([
             init, initialized,
             call(2, 'cas_add', { content: '/home/user/cas_upload/nonexistent.txt', type: 'url' }),
         ]).slice(2);
@@ -248,18 +256,21 @@ export const proof = {
     // cas_get without content:true returns only metadata.
     getMetaReturnsLengthAndMimeType: () => {
         const fileContent = utf8('text content');
-        const [addResp] = runSessionWithFiles({ '/home/user/cas_upload/f': fileContent })([
+        const root = { 'home': { 'user': { 'cas_upload': { 'f': fileContent } } } };
+        // First pass: add to get the hash.
+        const [addResp] = runSessionVirtual(root)([
             init, initialized,
             call(2, 'cas_add', { content: '/home/user/cas_upload/f', type: 'url' }),
         ]).slice(2);
         const hash = textOf(addResp);
-        const [, metaResp2] = runSessionWithFiles({ '/home/user/cas_upload/f': fileContent })([
+        // Second pass: add + get metadata.
+        const [, metaResp] = runSessionVirtual(root)([
             init, initialized,
             call(2, 'cas_add', { content: '/home/user/cas_upload/f', type: 'url' }),
             call(3, 'cas_get', { hash }),
         ]).slice(2);
-        assert(!resultOf(metaResp2).isError);
-        const meta = JSON.parse(textOf(metaResp2));
+        assert(!resultOf(metaResp).isError);
+        const meta = JSON.parse(textOf(metaResp));
         assertEq(meta.mime_type, 'text/plain');
         assertEq(meta.type, 'text');
         assertEq(meta.length, Number(BigInt(/* 'text content'.length */ 12)));
@@ -307,10 +318,22 @@ export const proof = {
         const [resp] = session(call(2, 'cas_get', { hash: 'bad!' }));
         assertEq(resultOf(resp).isError, true);
     },
+    // cas_add type:'url' with a subdirectory path flattens slashes to '-' in staging.
+    addUrlFromSubdirectorySucceeds: () => {
+        const fileContent = utf8('nested file content');
+        const root = { 'home': { 'user': { 'cas_upload': { 'subdir': { 'file.txt': fileContent } } } } };
+        const [resp] = runSessionVirtual(root)([
+            init, initialized,
+            call(2, 'cas_add', { content: '/home/user/cas_upload/subdir/file.txt', type: 'url' }),
+        ]).slice(2);
+        assert(!resultOf(resp).isError);
+        assert(textOf(resp).length > 0);
+    },
     // cas_add with type:'url' accepts paths within /home/user/cas_upload/
     addUrlFromApprovedDirectorySucceeds: () => {
         const fileContent = utf8('approved file');
-        const [resp] = runSessionWithFiles({ '/home/user/cas_upload/test.txt': fileContent })([
+        const root = { 'home': { 'user': { 'cas_upload': { 'test.txt': fileContent } } } };
+        const [resp] = runSessionVirtual(root)([
             init, initialized,
             call(2, 'cas_add', { content: '/home/user/cas_upload/test.txt', type: 'url' }),
         ]).slice(2);
@@ -319,21 +342,13 @@ export const proof = {
     },
     // cas_add with type:'url' rejects paths outside /home/user/cas_upload/
     addUrlFromRandomDirectoryIsRejected: () => {
-        const fileContent = utf8('forbidden file');
-        const [resp] = runSessionWithFiles({ '/tmp/secret.txt': fileContent })([
-            init, initialized,
-            call(2, 'cas_add', { content: '/tmp/secret.txt', type: 'url' }),
-        ]).slice(2);
+        const [resp] = session(call(2, 'cas_add', { content: '/tmp/secret.txt', type: 'url' }));
         assert(resultOf(resp).isError === true);
         assert(textOf(resp).includes('/home/user/cas_upload/'));
     },
     // cas_add with type:'url' rejects path traversal attempts with ..
     addUrlWithPathTraversalIsRejected: () => {
-        const fileContent = utf8('secret content');
-        const [resp] = runSessionWithFiles({ '/home/user/cas_upload/../../etc/passwd': fileContent })([
-            init, initialized,
-            call(2, 'cas_add', { content: '/home/user/cas_upload/../../etc/passwd', type: 'url' }),
-        ]).slice(2);
+        const [resp] = session(call(2, 'cas_add', { content: '/home/user/cas_upload/../../etc/passwd', type: 'url' }));
         assert(resultOf(resp).isError === true);
         assert(textOf(resp).includes('/home/user/cas_upload/'));
     },

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

@@ -4,9 +4,9 @@
  * @module
  */
 import { type Sha2 } from '../crypto/sha2/module.f.ts';
-import type { Vec } from '../types/bit_vec/module.f.ts';
+import { type Vec } from '../types/bit_vec/module.f.ts';
 import { type Effect, type Operation } from '../effects/module.f.ts';
-import { type Access, type All, type Mkdir, type NodeProgramOptions, type Read, type Readdir, type ReadFile, type Write, type WriteFile } from '../effects/node/module.f.ts';
+import { type Access, type All, type IoResult, type Mkdir, type NodeProgramOptions, type RandomInt, type Read, type ReadBytes, type Readdir, type ReadFile, type Rename, type Write, type WriteFile } from '../effects/node/module.f.ts';
 import { type Commands } from '../cli/module.f.ts';
 import type { MemOp } from '../effects/memory/module.f.ts';
 export type KvStore<O extends Operation> = {
@@ -38,5 +38,11 @@ export type Cas<O extends Operation> = {
  * Builds a content-addressable storage facade from a SHA-2 implementation.
  */
 export declare const cas: (sha2: Sha2) => <O extends Operation>(_: KvStore<O>) => Cas<O>;
+/**
+ * Move-hash-move upload pipeline: moves `fileName` from `~/cas_upload/` to a
+ * random staging path, stream-hashes it, then renames it to its final CAS shard
+ * path. Returns `ok(hash)` on success or `error(reason)` on any I/O failure.
+ */
+export declare const casUpload: (home: string) => (fileName: string) => Effect<Mkdir | Rename | RandomInt | ReadBytes, IoResult<Vec>>;
 export declare const commands: Commands<FileKvStoreOperation | Write | All | MemOp | Read>;
 export declare const main: (options: NodeProgramOptions) => Effect<All | Read | Write | FileKvStoreOperation | MemOp, number>;

package/fs/cas/module.f.js

@@ -5,13 +5,14 @@
  */
 import { computeSync, sha256 } from "../crypto/sha2/module.f.js";
 import { join, normalize, parse } from "../path/module.f.js";
+import { empty, length, maxLengthBytes, msb, vec } from "../types/bit_vec/module.f.js";
 import { cBase32ToVec, vecToCBase32 } from "../cbase32/module.f.js";
-import { forEachStep, pure } from "../effects/module.f.js";
-import { access, errorExit, isNotFound, log, mkdir, readdir, readFile, writeFile } from "../effects/node/module.f.js";
+import { foldStep, forEachStep, pure } from "../effects/module.f.js";
+import { access, errorExit, isNotFound, log, mkdir, randomInt, readBytes, readdir, readFile, rename, writeFile } from "../effects/node/module.f.js";
 import { dispatch } from "../cli/module.f.js";
 import { casMcpServer } from "./mcp/module.f.js";
 import { toOption } from "../types/nullable/module.f.js";
-import { unwrap } from "../types/result/module.f.js";
+import { error, ok, unwrap } from "../types/result/module.f.js";
 import { splitAt } from "../types/string/module.f.js";
 const o = { withFileTypes: true };
 const split2 = splitAt(2);
@@ -30,16 +31,8 @@ export const fileKvStore = (path) => {
     const storePrefix = join(path, prefix);
     const normalizedStorePrefix = normalize(storePrefix);
     return {
-        read: (key) => readFile(join(path, toPath(key))).step(r => {
-            if (r[0] === 'ok') {
-                return pure(r[1]);
-            }
-            // A missing file means "no such content"; surface anything else.
-            if (isNotFound(r[1])) {
-                return pure(undefined);
-            }
-            throw r[1];
-        }),
+        // TODO: extend the interface with `Result<Vec, unknown>` instead of `Vec|undefined`.
+        read: (key) => readFile(join(path, toPath(key))).step(([t, v]) => pure(t === 'ok' ? v : undefined)),
         write: (key, value) => {
             const p = toPath(key);
             const parts = parse(p);
@@ -83,6 +76,63 @@ export const cas = (sha2) => {
         list,
     });
 };
+/** Maximum chunk size for streaming reads: the largest `Vec` the runtime allows. */
+const CHUNK_BYTES = Number(maxLengthBytes);
+/** 256-bit random `Vec` built from 8 sequential `randomInt` (32-bit) calls. */
+const random256 = foldStep((_) => (acc) => randomInt().step(r => pure(msb.concat(acc)(vec(32n)(BigInt(r))))))(empty)([0, 1, 2, 3, 4, 5, 6, 7]);
+/**
+ * Streams a file in `CHUNK_BYTES` chunks, feeding each into the SHA-2 state,
+ * and returns the final hash without loading the whole file into memory.
+ */
+const streamHash = (sha2) => (path) => {
+    const chunkBits = BigInt(CHUNK_BYTES) * 8n;
+    const loop = (state, offset) => readBytes(path, offset, CHUNK_BYTES).step(result => {
+        if (result[0] === 'error') {
+            return pure(error(result[1]));
+        }
+        const chunk = result[1];
+        const newState = sha2.append(chunk)(state);
+        if (length(chunk) < chunkBits) {
+            return pure(ok(sha2.end(newState)));
+        }
+        return loop(newState, offset + CHUNK_BYTES);
+    });
+    return loop(sha2.init, 0);
+};
+/**
+ * Move-hash-move upload pipeline: moves `fileName` from `~/cas_upload/` to a
+ * random staging path, stream-hashes it, then renames it to its final CAS shard
+ * path. Returns `ok(hash)` on success or `error(reason)` on any I/O failure.
+ */
+export const casUpload = (home) => (fileName) => {
+    const src = join(home, 'cas_upload', fileName);
+    const stageDir = join(home, prefix, '.stage');
+    return random256.step(rnd => {
+        const rndStr = vecToCBase32(rnd);
+        const stagePath = join(stageDir, `${rndStr}-${fileName.replaceAll('/', '-')}`);
+        return mkdir(stageDir, { recursive: true })
+            .step(() => rename(src, stagePath))
+            .step(r => {
+            if (r[0] === 'error') {
+                return pure(error(r[1]));
+            }
+            return streamHash(sha256)(stagePath)
+                .step(hashResult => {
+                if (hashResult[0] === 'error') {
+                    return pure(hashResult);
+                }
+                const hash = hashResult[1];
+                const p = toPath(hash);
+                const parts = parse(p);
+                const finalDir = join(home, ...parts.slice(0, -1));
+                const finalPath = join(home, p);
+                return mkdir(finalDir, { recursive: true })
+                    .step(() => rename(stagePath, finalPath))
+                    .step(r2 => pure(r2[0] === 'error' ? error(r2[1]) : ok(hash)));
+            });
+        });
+    });
+};
 export const commands = [
     {
         names: ['add'],
@@ -129,6 +179,6 @@ export const commands = [
                 .step(forEachStep(j => log(vecToCBase32(j))))
                 .step(() => pure(0));
         },
-    }
+    },
 ];
 export const main = dispatch(commands);

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

@@ -67,6 +67,12 @@ export declare const writeFile: Func<WriteFile>;
 export declare const writeUtf8File: (path: string, content: string) => Effect<WriteFile, IoResult<void>>;
 export type Rm = readonly ['rm', (path: string) => IoResult<void>];
 export declare const rm: Func<Rm>;
+export type Rename = readonly ['rename', (src: string, dst: string) => IoResult<void>];
+export declare const rename: Func<Rename>;
+export type ReadBytes = readonly ['readBytes', (path: string, offset: number, size: number) => IoResult<Vec>];
+export declare const readBytes: Func<ReadBytes>;
+export type RandomInt = readonly ['randomInt', () => number];
+export declare const randomInt: Func<RandomInt>;
 export type ExecResult = {
     readonly stdout: string;
     readonly stderr: string;
@@ -75,7 +81,7 @@ export type Exec = readonly ['exec', (command: string, stdin?: string) => IoResu
 export declare const exec: Func<Exec>;
 export type Access = readonly ['access', (path: string) => IoResult<void>];
 export declare const access: Func<Access>;
-export type Fs = Mkdir | ReadFile | Readdir | WriteFile | Rm | Exec | Access;
+export type Fs = Mkdir | ReadFile | ReadBytes | Readdir | WriteFile | Rm | Rename | Exec | Access;
 export type Server = Nominal<'server', `160855c4f69310fece3273c1853ac32de43dee1eb41bf59d821917f8eebe9272`, unknown>;
 export type Headers = StringMap<string, string>;
 export type IncomingMessage = {
@@ -210,7 +216,7 @@ export type TestContext = {
 /** Effect operation that registers a named test with the active `TestContext`. */
 export type Test = readonly ['test', (ctx: TestContext, name: string, expectFailure: boolean, test: (t: TestContext) => Effect<Test | All | Await, void>) => void];
 export declare const test: Func<Test>;
-export type NodeOp = All | Await | Fetch | Fs | Http | Forever | Import | MemOp | Now | Read | Sandbox | Write | Test;
+export type NodeOp = All | Await | Fetch | Fs | Http | Forever | Import | MemOp | Now | RandomInt | Read | Sandbox | Write | Test;
 export type NodeEffect<T> = Effect<NodeOp, T>;
 /**
  * Writes an error line to `stderr` and yields exit code `1`. The canonical

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

@@ -48,6 +48,9 @@ export const writeFile = do_('writeFile');
 /** Writes a string to `path` as UTF-8 bytes. */
 export const writeUtf8File = (path, content) => writeFile(path, utf8(content));
 export const rm = do_('rm');
+export const rename = do_('rename');
+export const readBytes = do_('readBytes');
+export const randomInt = do_('randomInt');
 export const exec = do_('exec');
 export const access = do_('access');
 export const createServer = do_('createServer');

package/fs/effects/node/module.js

@@ -22,6 +22,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  */
 import http from 'node:http';
 import childProcess from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import process from 'node:process';
@@ -58,7 +59,7 @@ const collect = async (v) => {
     }
     return result;
 };
-const { mkdir, readFile, readdir, writeFile, rm, access, stat } = fs.promises;
+const { mkdir, open, readFile, readdir, rename, writeFile, rm, access, stat } = fs.promises;
 const { exec } = childProcess;
 const maxFileSizeBytes = Number(maxLengthBytes);
 const prefix = 'file:///';
@@ -179,6 +180,25 @@ const runNodeEffect = asyncRun({
     }))),
     writeFile: (path, data) => tc(() => writeFile(path, fromVec(data))),
     rm: path => tc(() => rm(path)),
+    rename: (src, dst) => tc(() => rename(src, dst)),
+    readBytes: (path, offset, size) => tc(async () => {
+        if (offset < 0) {
+            throw new Error(`Offset ${offset} is negative`);
+        }
+        if (size > maxFileSizeBytes) {
+            throw new Error(`Chunk size ${size} exceeds maximum allowed size of ${maxFileSizeBytes} bytes`);
+        }
+        const fh = await open(path, 'r');
+        try {
+            const buffer = Buffer.alloc(size);
+            const { bytesRead } = await fh.read(buffer, 0, size, offset);
+            return toVec(buffer.subarray(0, bytesRead));
+        }
+        finally {
+            await fh.close();
+        }
+    }),
+    randomInt: async () => crypto.randomInt(2 ** 32),
     access: path => tc(() => access(path)),
     import: path => tc(() => asyncImport(path)),
     exec: (command, stdin) => new Promise(resolve => {

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

@@ -46,4 +46,19 @@ export declare const proof: {
         createAndRead: () => void;
         createAndWrite: () => void;
     };
+    rename: {
+        fileOverFile: () => void;
+        nestedRename: () => void;
+        dirOverFile: () => void;
+        missingSource: () => void;
+    };
+    readBytes: {
+        simple: () => void;
+        withOffset: () => void;
+        oversizeChunk: () => void;
+        missingFile: () => void;
+    };
+    randomInt: {
+        increments: () => void;
+    };
 };

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

@@ -1,7 +1,7 @@
 import { empty, isVec, uint, vec8 } from "../../types/bit_vec/module.f.js";
 import { utf8, utf8ToString } from "../../text/module.f.js";
 import { decode, pure } from "../module.f.js";
-import { both, fetch, mkdir, now, readdir, readFile, readUtf8File, rm, sandbox, writeFile, writeUtf8File } from "./module.f.js";
+import { both, fetch, mkdir, now, readdir, readFile, readUtf8File, rm, sandbox, writeFile, writeUtf8File, rename, readBytes, randomInt } from "./module.f.js";
 import { create as memCreate, read as memRead, write as memWrite } from "../memory/module.f.js";
 import { emptyState, virtual } from "./virtual/module.f.js";
 export const proof = {
@@ -442,4 +442,115 @@ export const proof = {
             }
         },
     },
+    rename: {
+        fileOverFile: () => {
+            const [state, [t, result]] = virtual({
+                ...emptyState,
+                root: { src: vec8(0x2an), dst: vec8(0x15n) },
+            })(rename('src', 'dst'));
+            if (t !== 'ok') {
+                throw result;
+            }
+            if (state.root.src !== undefined) {
+                throw state.root;
+            }
+            if (!isVec(state.root.dst)) {
+                throw state.root;
+            }
+            if (uint(state.root.dst) !== 0x2an) {
+                throw state.root;
+            }
+        },
+        nestedRename: () => {
+            const [state, [t, result]] = virtual({
+                ...emptyState,
+                root: { tmp: { src: vec8(0x2an) } },
+            })(rename('tmp/src', 'tmp/dst'));
+            if (t !== 'ok') {
+                throw result;
+            }
+            const tmp = state.root.tmp;
+            if (typeof tmp !== 'object') {
+                throw state.root;
+            }
+            if (tmp.src !== undefined) {
+                throw tmp;
+            }
+        },
+        dirOverFile: () => {
+            const [state, [t, result]] = virtual({
+                ...emptyState,
+                root: { src: {}, dst: vec8(0x15n) },
+            })(rename('src', 'dst'));
+            if (t !== 'error') {
+                throw result;
+            }
+            if (!isVec(state.root.dst)) {
+                throw state.root;
+            }
+        },
+        missingSource: () => {
+            const [_, [t, result]] = virtual(emptyState)(rename('missing', 'dst'));
+            if (t !== 'error') {
+                throw result;
+            }
+        },
+    },
+    readBytes: {
+        simple: () => {
+            const [_, [t, result]] = virtual({
+                ...emptyState,
+                root: { file: vec8(0xabcdn) },
+            })(readBytes('file', 0, 2));
+            if (t !== 'ok') {
+                throw result;
+            }
+            if (!isVec(result)) {
+                throw result;
+            }
+        },
+        withOffset: () => {
+            const [_, [t, result]] = virtual({
+                ...emptyState,
+                root: { file: vec8(0xabcdn) },
+            })(readBytes('file', 1, 1));
+            if (t !== 'ok') {
+                throw result;
+            }
+            if (!isVec(result)) {
+                throw result;
+            }
+        },
+        oversizeChunk: () => {
+            const [_, [t, result]] = virtual({
+                ...emptyState,
+                root: { file: vec8(0x2an) },
+            })(readBytes('file', 0, Number(2n ** 32n)));
+            if (t !== 'error') {
+                throw result;
+            }
+        },
+        missingFile: () => {
+            const [_, [t, result]] = virtual(emptyState)(readBytes('missing', 0, 4));
+            if (t !== 'error') {
+                throw result;
+            }
+        },
+    },
+    randomInt: {
+        increments: () => {
+            const [state1, r1] = virtual(emptyState)(randomInt());
+            if (r1 !== 0) {
+                throw r1;
+            }
+            const [state2, r2] = virtual(state1)(randomInt());
+            if (r2 !== 1) {
+                throw r2;
+            }
+            const [_, r3] = virtual(state2)(randomInt());
+            if (r3 !== 2) {
+                throw r3;
+            }
+        },
+    },
 };

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

@@ -28,6 +28,8 @@ export type State = {
     memoryValues: {
         readonly [key: string]: unknown;
     };
+    /** Monotonically increasing counter returned by `randomInt`; starts at 0. */
+    randomNext: number;
 };
 export declare const emptyState: State;
 export declare const virtual: RunInstance<NodeOp, State>;

package/fs/effects/node/virtual/module.f.js

@@ -6,7 +6,7 @@
 import { todo } from "../../../asserts/module.f.js";
 import { join, parse } from "../../../path/module.f.js";
 import { utf8ToString } from "../../../text/module.f.js";
-import { isVec } from "../../../types/bit_vec/module.f.js";
+import { isVec, length, maxLengthBytes, msb, vec } from "../../../types/bit_vec/module.f.js";
 import { error, ok } from "../../../types/result/module.f.js";
 import { run } from "../../mock/module.f.js";
 import { asBase, asNominal } from "../../memory/module.f.js";
@@ -19,6 +19,7 @@ export const emptyState = {
     epochNs: 0,
     memoryNext: 0,
     memoryValues: {},
+    randomNext: 0,
 };
 const operation = (op) => {
     const f = (dir, path) => {
@@ -142,6 +143,125 @@ const rm = operation((dir, path) => {
     const { [name]: _, ...rest } = dir;
     return [rest, okVoid];
 });
+const extractEntity = (dir, path) => {
+    if (path.length === 0) {
+        return [dir, error('cannot extract root')];
+    }
+    if (path.length === 1) {
+        const [name] = path;
+        const entry = dir[name];
+        if (entry === undefined) {
+            return [dir, enoent];
+        }
+        const { [name]: _, ...rest } = dir;
+        return [rest, ok(entry)];
+    }
+    const [first, ...rest] = path;
+    const sub = dir[first];
+    if (sub === undefined || isVec(sub) || typeof sub === 'function') {
+        return [dir, enoent];
+    }
+    const [newSub, result] = extractEntity(sub, rest);
+    if (result[0] === 'error') {
+        return [dir, result];
+    }
+    return [{ ...dir, [first]: newSub }, result];
+};
+const insertEntityAt = (dir, path, entity) => {
+    if (path.length === 0) {
+        return [dir, error('cannot insert at root')];
+    }
+    if (path.length === 1) {
+        const [name] = path;
+        const existing = dir[name];
+        if (existing !== undefined) {
+            const entityIsDir = typeof entity === 'object';
+            const existingIsDir = typeof existing === 'object';
+            if (entityIsDir && !existingIsDir) {
+                return [dir, error(`cannot overwrite file '${name}' with a directory`)];
+            }
+            if (!entityIsDir && existingIsDir) {
+                return [dir, error(`'${name}' is a directory`)];
+            }
+            if (entityIsDir && existingIsDir) {
+                const existingDir = existing;
+                const hasContent = Object.values(existingDir).some(v => v !== undefined);
+                if (hasContent) {
+                    return [dir, error(`cannot overwrite non-empty directory '${name}'`)];
+                }
+            }
+        }
+        return [{ ...dir, [name]: entity }, okVoid];
+    }
+    const [first, ...rest] = path;
+    const sub = dir[first];
+    if (sub === undefined) {
+        return [dir, enoent];
+    }
+    if (isVec(sub) || typeof sub === 'function') {
+        return [dir, error('not a directory')];
+    }
+    const [newSub, result] = insertEntityAt(sub, rest, entity);
+    if (result[0] === 'error') {
+        return [dir, result];
+    }
+    return [{ ...dir, [first]: newSub }, result];
+};
+const isProperPrefix = (prefix, path) => prefix.length < path.length && prefix.every((seg, i) => seg === path[i]);
+const rename = (src, dst) => (state) => {
+    const srcParsed = parse(src);
+    const dstParsed = parse(dst);
+    // extract source first to report ENOENT if it's missing, before checking subtree guards
+    const [srcRoot, srcResult] = extractEntity(state.root, srcParsed);
+    if (srcResult[0] === 'error') {
+        return [state, srcResult];
+    }
+    // now that source exists, reject if dst is strictly inside src's subtree (rename into own descendant)
+    // or if src is strictly inside dst's subtree (rename onto own ancestor)
+    if (isProperPrefix(srcParsed, dstParsed) || isProperPrefix(dstParsed, srcParsed)) {
+        return [state, error('cannot rename a directory into its own subtree or onto an ancestor')];
+    }
+    const [dstRoot, dstResult] = insertEntityAt(srcRoot, dstParsed, srcResult[1]);
+    if (dstResult[0] === 'error') {
+        return [state, dstResult];
+    }
+    return [{ ...state, root: dstRoot }, okVoid];
+};
+const readBytesOp = (path, offset, size) => readOperation((dir, p) => {
+    if (p.length !== 1) {
+        return enoent;
+    }
+    const file = dir[p[0]];
+    if (typeof file === 'function') {
+        throw new Error(`'${p[0]}' is a JsModule; readBytes not supported`);
+    }
+    if (file === undefined) {
+        return enoent;
+    }
+    if (!isVec(file)) {
+        return error(`'${p[0]}' is not a file`);
+    }
+    if (!Number.isInteger(offset)) {
+        return error(`Offset ${offset} is not an integer`);
+    }
+    if (!Number.isInteger(size)) {
+        return error(`Chunk size ${size} is not an integer`);
+    }
+    if (offset < 0) {
+        return error(`Offset ${offset} is negative`);
+    }
+    if (size < 0) {
+        return error(`Chunk size ${size} is negative`);
+    }
+    if (BigInt(size) > maxLengthBytes) {
+        return error(`Chunk size ${size} exceeds maximum allowed size of ${maxLengthBytes} bytes`);
+    }
+    const offsetBits = BigInt(offset) * 8n;
+    const sizeBits = BigInt(size) * 8n;
+    const remaining = msb.removeFront(offsetBits)(file);
+    const actualSizeBits = sizeBits < length(remaining) ? sizeBits : length(remaining);
+    return ok(vec(actualSizeBits)(msb.front(actualSizeBits)(remaining)));
+})(path);
 const map = {
     all: (...a) => state => {
         let e = [];
@@ -180,6 +300,9 @@ const map = {
     access,
     import: import_,
     rm,
+    rename,
+    readBytes: readBytesOp,
+    randomInt: () => state => [{ ...state, randomNext: state.randomNext + 1 }, state.randomNext],
     exec: todo,
     createServer: todo,
     listen: todo,

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

@@ -14,4 +14,14 @@ export declare const proof: {
     throw: {
         readFileOnJsModule: () => void;
     };
+    renameSamePath: () => void;
+    renameIntoOwnSubtree: () => void;
+    renameOntoOwnAncestor: () => void;
+    renameNonEmptyDirOverEmptyDir: () => void;
+    renameEmptyDirOverNonEmptyDir: () => void;
+    readBytesNegativeSize: () => void;
+    readBytesZeroSize: () => void;
+    readBytesNegativeOffset: () => void;
+    readBytesFractionalSize: () => void;
+    readBytesFractionalOffset: () => void;
 };

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

@@ -1,5 +1,5 @@
 import { assertEq } from "../../../asserts/module.f.js";
-import { awaitIfPromise, fetch, rm, writeFile, readFile, readdir, import_ } from "../module.f.js";
+import { awaitIfPromise, fetch, rm, writeFile, readFile, readdir, import_, rename, readBytes } from "../module.f.js";
 import { vec8 } from "../../../types/bit_vec/module.f.js";
 import { emptyState, virtual } from "./module.f.js";
 export const proof = {
@@ -76,4 +76,64 @@ export const proof = {
             virtual({ ...emptyState, root })(readFile('a.f.ts'));
         },
     },
+    renameSamePath: () => {
+        // rename('a', 'a') should succeed as a no-op, not reject
+        const root = { 'a': vec8(0x42n) };
+        const [, result] = virtual({ ...emptyState, root })(rename('a', 'a'));
+        assertEq(result[0], 'ok');
+    },
+    renameIntoOwnSubtree: () => {
+        // rename('a', 'a/b') should fail (dst inside src's subtree)
+        const root = { 'a': { 'b': vec8(0x42n) } };
+        const [, result] = virtual({ ...emptyState, root })(rename('a', 'a/b'));
+        assertEq(result[0], 'error');
+    },
+    renameOntoOwnAncestor: () => {
+        // rename('a/b', 'a') should fail (src inside dst's subtree)
+        const root = { 'a': { 'b': vec8(0x42n) } };
+        const [, result] = virtual({ ...emptyState, root })(rename('a/b', 'a'));
+        assertEq(result[0], 'error');
+    },
+    renameNonEmptyDirOverEmptyDir: () => {
+        // rename a directory onto an empty directory should succeed
+        const root = { 'src': { 'file': vec8(0x42n) }, 'dst': {} };
+        const [, result] = virtual({ ...emptyState, root })(rename('src', 'dst'));
+        assertEq(result[0], 'ok');
+    },
+    renameEmptyDirOverNonEmptyDir: () => {
+        // rename an empty directory onto a non-empty directory should fail
+        const root = { 'src': {}, 'dst': { 'file': vec8(0x42n) } };
+        const [, result] = virtual({ ...emptyState, root })(rename('src', 'dst'));
+        assertEq(result[0], 'error');
+    },
+    readBytesNegativeSize: () => {
+        // readBytes with negative size should fail
+        const root = { 'file': vec8(0x42n) };
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', 0, -1));
+        assertEq(result[0], 'error');
+    },
+    readBytesZeroSize: () => {
+        // readBytes with zero size should succeed and return empty vec
+        const root = { 'file': vec8(0x42n) };
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', 0, 0));
+        assertEq(result[0], 'ok');
+    },
+    readBytesNegativeOffset: () => {
+        // readBytes with negative offset should fail
+        const root = { 'file': vec8(0x42n) };
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', -1, 1));
+        assertEq(result[0], 'error');
+    },
+    readBytesFractionalSize: () => {
+        // readBytes with fractional size should fail rather than throw RangeError
+        const root = { 'file': vec8(0x42n) };
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', 0, 1.5));
+        assertEq(result[0], 'error');
+    },
+    readBytesFractionalOffset: () => {
+        // readBytes with fractional offset should fail rather than throw RangeError
+        const root = { 'file': vec8(0x42n) };
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', 0.5, 1));
+        assertEq(result[0], 'error');
+    },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.32.2",
+  "version": "0.32.4",
   "type": "module",
   "files": [
     "**/*.js",
@@ -44,7 +44,7 @@
   "homepage": "https://github.com/functionalscript/functionalscript#readme",
   "devDependencies": {
     "@playwright/test": "1.61.0",
-    "@types/node": "25.9.3",
+    "@types/node": "26.0.0",
     "typescript": "6.0.3"
   }
 }