functionalscript 0.32.3 → 0.33.0

package/fs/bnf/data/proof.f.d.ts

@@ -11,4 +11,7 @@ export declare const proof: {
     repeat: (() => void)[];
     repeatParser: (() => void)[];
     example: () => void;
+    throw: {
+        ambiguousVariantDispatch: () => void;
+    };
 };

package/fs/bnf/data/proof.f.js

@@ -763,5 +763,12 @@ export const proof = {
                 'digit': 'digit',
             }
         };
+    },
+    throw: {
+        ambiguousVariantDispatch: () => {
+            // Two alternatives covering the same code point — dispatch merge throws.
+            const conflictRule = { 'a': range('AA'), 'b': range('AA') };
+            dispatchMap(toData(conflictRule)[0]);
+        }
     }
 };

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);
@@ -110,7 +112,9 @@ const casToolRegistry = (c, home, toUrl) => {
             }
             return x.step(value => typeof value === 'string'
                 ? pure(errorResult(value))
-                : c.write(value).step(hash => pure(okResult(vecToCBase32(hash)))));
+                : c.write(value).step(hash => pure(hash === undefined
+                    ? errorResult('write')
+                    : 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);

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

@@ -5,13 +5,15 @@ import { asBase, asNominal, create, read, write } from "../../effects/memory/mod
 import { msb, u8ListToVec, vec8 } from "../../types/bit_vec/module.f.js";
 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 { computeSync, sha256 } from "../../crypto/sha2/module.f.js";
 import { utf8 } from "../../text/module.f.js";
-import { cas } from "../module.f.js";
+import { fileCas } 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,18 +28,20 @@ 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) => ({
+const memCas = (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] })),
+    write: (value) => {
+        const key = computeSync(sha256)([value]);
+        return read(mapKey)
+            .step(m => write(mapKey, { ...m, [vecToCBase32(key)]: [key, value] }))
+            .step(() => pure(key));
+    },
     list: () => read(mapKey).step(m => pure(Object.values(m).map(([k]) => k))),
 });
 // ── Session driver ──────────────────────────────────────────────────────────────
@@ -50,16 +54,21 @@ const feed = (step) => (msgs) => {
 };
 // Runs a full session over a fresh in-memory CAS, returning all responses.
 const runSession = (msgs, home = '/home/user') => runMem(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 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 c = memCas(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 = fileCas(sha256)(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 +220,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 +233,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 +261,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 +323,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 +347,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,39 +4,31 @@
  * @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> = {
-    /** Reads a value by key; returns `undefined` when the key does not exist. */
-    readonly read: (key: Vec) => Effect<O, Vec | undefined>;
-    /** Writes a key/value pair to the underlying storage. */
-    readonly write: (key: Vec, value: Vec) => Effect<O, void>;
-    /** Lists all keys available in the store. */
-    readonly list: () => Effect<O, readonly Vec[]>;
-};
-/** A key/value tuple where index `0` is the key and index `1` is the value. */
-export type Kv = readonly [Vec, Vec];
 /** Converts a content key to its sharded relative CAS file path. */
 export declare const toPath: (key: Vec) => string;
-export type FileKvStoreOperation = ReadFile | Mkdir | WriteFile | Access | Readdir;
-/**
- * Creates a filesystem-backed key/value store under the provided root path.
- */
-export declare const fileKvStore: (path: string) => KvStore<FileKvStoreOperation>;
+export type FileCasOperation = ReadFile | Mkdir | WriteFile | Access | Readdir;
 export type Cas<O extends Operation> = {
     /** Reads content by hash; returns `undefined` when not found. */
     readonly read: (key: Vec) => Effect<O, Vec | undefined>;
     /** Stores content and returns its computed hash. */
-    readonly write: (value: Vec) => Effect<O, Vec>;
+    readonly write: (value: Vec) => Effect<O, Vec | undefined>;
     /** Lists all stored content hashes. */
     readonly list: () => Effect<O, readonly Vec[]>;
 };
 /**
  * Builds a content-addressable storage facade from a SHA-2 implementation.
  */
-export declare const cas: (sha2: Sha2) => <O extends Operation>(_: KvStore<O>) => Cas<O>;
-export declare const commands: Commands<FileKvStoreOperation | Write | All | MemOp | Read>;
-export declare const main: (options: NodeProgramOptions) => Effect<All | Read | Write | FileKvStoreOperation | MemOp, number>;
+export declare const fileCas: (sha2: Sha2) => (path: string) => Cas<FileCasOperation>;
+/**
+ * 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<FileCasOperation | Write | All | MemOp | Read>;
+export declare const main: (options: NodeProgramOptions) => Effect<All | Read | Write | FileCasOperation | MemOp, number>;

package/fs/cas/module.f.js

@@ -5,15 +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);
 const prefix = '.cas';
 /** Converts a content key to its sharded relative CAS file path. */
@@ -24,55 +23,101 @@ export const toPath = (key) => {
     return join(prefix, a, b, c);
 };
 /**
- * Creates a filesystem-backed key/value store under the provided root path.
+ * Builds a content-addressable storage facade from a SHA-2 implementation.
  */
-export const fileKvStore = (path) => {
-    const storePrefix = join(path, prefix);
-    const normalizedStorePrefix = normalize(storePrefix);
-    return {
-        // 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);
-            const dir = join(path, ...parts.slice(0, -1));
-            // TODO: error handling
-            return mkdir(dir, { recursive: true })
-                .step(() => writeFile(join(path, p), value))
-                .step(() => pure(undefined));
-        },
-        list: () => 
-        // A fresh store has no `.cas` directory yet. Treat *only* that case as an
-        // empty store, mirroring how `read` maps a missing file to `undefined`.
-        // A `.cas` that exists but cannot be read (permissions, corruption) is a
-        // genuine storage error and is surfaced, not masked as "no hashes".
-        access(storePrefix).step(a => {
-            if (a[0] === 'error') {
-                if (isNotFound(a[1])) {
-                    return pure([]);
+export const fileCas = (sha2) => {
+    const compute = computeSync(sha2);
+    return (path) => {
+        const storePrefix = join(path, prefix);
+        const normalizedStorePrefix = normalize(storePrefix);
+        return {
+            // 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: (value) => {
+                const hash = compute([value]);
+                const p = toPath(hash);
+                const parts = parse(p);
+                const dir = join(path, ...parts.slice(0, -1));
+                // TODO: error handling
+                return mkdir(dir, { recursive: true })
+                    .step(() => writeFile(join(path, p), value))
+                    .step(([t]) => pure(t === 'ok' ? hash : undefined));
+            },
+            list: () => 
+            // A fresh store has no `.cas` directory yet. Treat *only* that case as an
+            // empty store, mirroring how `read` maps a missing file to `undefined`.
+            // A `.cas` that exists but cannot be read (permissions, corruption) is a
+            // genuine storage error and is surfaced, not masked as "no hashes".
+            access(storePrefix).step(a => {
+                if (a[0] === 'error') {
+                    if (isNotFound(a[1])) {
+                        return pure([]);
+                    }
+                    throw a[1];
                 }
-                throw a[1];
-            }
-            return readdir(storePrefix, { recursive: true })
-                .step(r => pure(unwrap(r).flatMap(({ name, parentPath, isFile }) => toOption(isFile
-                ? cBase32ToVec(normalize(parentPath).substring(normalizedStorePrefix.length).replaceAll('/', '') + name)
-                : null))));
-        }),
+                return readdir(storePrefix, { recursive: true })
+                    .step(r => pure(unwrap(r).flatMap(({ name, parentPath, isFile }) => toOption(isFile
+                    ? cBase32ToVec(normalize(parentPath).substring(normalizedStorePrefix.length).replaceAll('/', '') + name)
+                    : null))));
+            }),
+        };
     };
 };
+/** 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]);
 /**
- * Builds a content-addressable storage facade from a SHA-2 implementation.
+ * 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.
  */
-export const cas = (sha2) => {
-    const compute = computeSync(sha2);
-    return ({ read, write, list }) => ({
-        read,
-        write: (value) => {
-            const hash = compute([value]);
-            return write(hash, value)
-                .step(() => pure(hash));
-        },
-        list,
+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 = [
@@ -83,11 +128,12 @@ export const commands = [
             if (path === undefined || rest.length !== 0) {
                 return errorExit("'cas add' expects one parameter");
             }
-            const c = cas(sha256)(fileKvStore(home));
+            const c = fileCas(sha256)(home);
             return readFile(path)
                 .step(v => c.write(unwrap(v)))
-                .step(hash => log(vecToCBase32(hash)))
-                .step(() => pure(0));
+                .step(hash => hash === undefined
+                ? pure(1)
+                : log(vecToCBase32(hash)).step(() => pure(0)));
         },
     },
     {
@@ -101,7 +147,7 @@ export const commands = [
             if (hash === null) {
                 return errorExit(`invalid hash format: ${hashCBase32}`);
             }
-            const c = cas(sha256)(fileKvStore(home));
+            const c = fileCas(sha256)(home);
             return c.read(hash)
                 .step(v => {
                 const result = v === undefined
@@ -116,11 +162,11 @@ export const commands = [
         names: ['list'],
         description: 'List all stored content hashes',
         handler: ({ home }) => {
-            const c = cas(sha256)(fileKvStore(home));
+            const c = fileCas(sha256)(home);
             return c.list()
                 .step(forEachStep(j => log(vecToCBase32(j))))
                 .step(() => pure(0));
         },
-    }
+    },
 ];
 export const main = dispatch(commands);