functionalscript 0.33.0 → 0.34.0

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

@@ -1,15 +1,13 @@
 import { assert, assertEq } from "../../asserts/module.f.js";
 import { pure } from "../../effects/module.f.js";
 import { run } from "../../effects/mock/module.f.js";
-import { asBase, asNominal, create, read, write } from "../../effects/memory/module.f.js";
-import { msb, u8ListToVec, vec8 } from "../../types/bit_vec/module.f.js";
+import { asBase, asNominal, create } from "../../effects/memory/module.f.js";
+import { msb, u8ListToVec, vec8, repeat, length, maxLengthBytes } from "../../types/bit_vec/module.f.js";
 import { vecToCBase32 } from "../../cbase32/module.f.js";
 import { encode as base64Encode } from "../../base64/module.f.js";
-import { computeSync, sha256 } from "../../crypto/sha2/module.f.js";
 import { utf8 } from "../../text/module.f.js";
-import { fileCas } from "../module.f.js";
+import {} 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";
 import { ok as resultOk } from "../../types/result/module.f.js";
@@ -32,18 +30,15 @@ const mock = {
     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'); },
+    now: () => state => [state, 0],
+    access: (_path) => _ => { throw new Error('access not supported in memory mock'); },
+    createExclusive: (_path) => _ => { throw new Error('createExclusive not supported in memory mock'); },
+    readdir: (_path, _opts) => _ => { throw new Error('readdir not supported in memory mock'); },
+    rm: (_path) => _ => { throw new Error('rm not supported in memory mock'); },
+    stat: (_path) => _ => { throw new Error('stat not supported in memory mock'); },
+    writeBytes: (_path, _offset, _data) => _ => { throw new Error('writeBytes not supported in memory mock'); },
 };
 const runMem = (effect) => run(mock)(initialTestState)(effect)[1];
-const memCas = (mapKey) => ({
-    read: (key) => read(mapKey).step(m => pure(m[vecToCBase32(key)]?.[1])),
-    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 ──────────────────────────────────────────────────────────────
 // Feeds each message to `step` in order, collecting every response.
 const feed = (step) => (msgs) => {
@@ -52,19 +47,12 @@ const feed = (step) => (msgs) => {
         : step(msgs[i]).step(r => go(i + 1, [...acc, r]));
     return go(0, []);
 };
-// 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 = 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);
+        const step = mcpStep(casConfig)(casMcpHandlers(home))(sessionKey);
         return feed(step)(msgs);
     });
     return virtual({ ...emptyState, root })(effect)[1];
@@ -76,7 +64,7 @@ const initialized = { jsonrpc: '2.0', method: 'notifications/initialized' };
 const call = (id, name, args) => ({ jsonrpc: '2.0', method: 'tools/call', id, params: { name, arguments: args } });
 const list = (id) => ({ jsonrpc: '2.0', method: 'tools/list', id });
 // Runs `init`, `notifications/initialized`, then `msgs`; returns the tool responses.
-const session = (...msgs) => runSession([init, initialized, ...msgs]).slice(2);
+const session = (...msgs) => runSessionVirtual({}, '/home/user')([init, initialized, ...msgs]).slice(2);
 const resultOf = (resp) => resp.result;
 const item0 = (resp) => resultOf(resp).content[0];
 const textOf = (resp) => item0(resp).text;
@@ -88,9 +76,47 @@ const binarySample = base64Encode(vec8(0x2an));
 // `cas_get` detects its type and returns base64 with mime_type image/png.
 const pngSample = base64Encode(u8ListToVec(msb)([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x01]));
 // ── Tests ───────────────────────────────────────────────────────────────────────
+// A blob larger than one read chunk (> 128 KiB) used to fail metadata-only
+// cas_get because `collectRead` overflowed `maxLength`. With `detectStream`,
+// content:false returns correct metadata regardless of size. Each chunk is
+// exactly `maxLengthBytes` (the largest single `Vec` the runtime allows), so the
+// two-chunk blob spans two read chunks without any one `Vec` exceeding the cap.
+const largeMultiChunkBlobMeta = (chunk0, chunk1, expectedType, expectedMime) => () => {
+    const root = { 'home': { 'user': { 'cas_upload': { 'big': [chunk0, chunk1] } } } };
+    const [addResp] = runSessionVirtual(root)([
+        init, initialized,
+        call(2, 'cas_add', { content: '/home/user/cas_upload/big', type: 'url' }),
+    ]).slice(2);
+    assert(!resultOf(addResp).isError);
+    const hash = textOf(addResp);
+    const [, metaResp] = runSessionVirtual(root)([
+        init, initialized,
+        call(2, 'cas_add', { content: '/home/user/cas_upload/big', type: 'url' }),
+        call(3, 'cas_get', { hash }),
+    ]).slice(2);
+    assert(!resultOf(metaResp).isError);
+    const meta = JSON.parse(textOf(metaResp));
+    assertEq(meta.type, expectedType);
+    assertEq(meta.mime_type, expectedMime);
+    assertEq(meta.length, Number((length(chunk0) + length(chunk1)) / 8n));
+    assertEq(meta.content, undefined);
+};
+// A full `maxLengthBytes`-long chunk of repeated ASCII 'a' — valid UTF-8.
+const asciiChunk = repeat(maxLengthBytes)(vec8(0x61n));
+// The same length, but repeated 2-byte "é" (C3 A9) — valid UTF-8 of multi-byte symbols.
+const symbolChunk = repeat(maxLengthBytes / 2n)(u8ListToVec(msb)([0xc3, 0xa9]));
+// A full chunk of 0xFF — an invalid UTF-8 lead byte, so binary (no magic match).
+const binaryChunk = repeat(maxLengthBytes)(vec8(0xffn));
 export const proof = {
+    // Both chunks repeated ASCII → text/plain, no error on a > 128 KiB blob.
+    getMetaLargeMultiChunkBlobNoError: largeMultiChunkBlobMeta(asciiChunk, asciiChunk, 'text', 'text/plain'),
+    // Both chunks valid UTF-8 sequences of multi-byte symbols → text/plain.
+    getMetaLargeMultiChunkUtf8Symbols: largeMultiChunkBlobMeta(symbolChunk, symbolChunk, 'text', 'text/plain'),
+    // First chunk valid UTF-8, second chunk binary → base64/octet-stream. The
+    // streaming validator must see the trailing binary chunk to reject text.
+    getMetaLargeMultiChunkTextThenBinary: largeMultiChunkBlobMeta(asciiChunk, binaryChunk, 'base64', 'application/octet-stream'),
     toolsListAdvertisesThreeTools: () => {
-        const [resp] = runSession([init, initialized, list(2)]).slice(2);
+        const [resp] = runSessionVirtual({})([init, initialized, list(2)]).slice(2);
         const tools = resp.result.tools;
         assertEq(tools.length, 3);
         assertEq(tools.map(t => t.name).join(','), 'cas_add,cas_get,cas_list');
@@ -278,7 +304,7 @@ export const proof = {
         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)));
+        assertEq(meta.length, 12);
         assertEq(meta.content, undefined);
     },
     getMetaBinaryBlob: () => {
@@ -304,15 +330,18 @@ export const proof = {
         assertEq(meta.type, 'base64');
         assertEq(meta.content, undefined);
     },
-    getMetaNoUrlWhenToUrlAbsent: () => {
-        const content = utf8('no url');
-        const binaryB64 = base64Encode(content);
-        const [addResp] = session(call(2, 'cas_add', { content: binaryB64 }));
+    // A NUL-bearing blob is valid UTF-8 yet binary: cas_get must report
+    // base64/octet-stream, not text/plain.
+    getMetaOctetStreamForNulBlob: () => {
+        const nulContent = u8ListToVec(msb)([0x00, 0x00, 0x00]);
+        const nulB64 = base64Encode(nulContent);
+        const [addResp] = session(call(2, 'cas_add', { content: nulB64, type: 'base64' }));
         const hash = textOf(addResp);
-        const [, metaResp] = session(call(2, 'cas_add', { content: binaryB64 }), call(3, 'cas_get', { hash }));
+        const [, metaResp] = session(call(2, 'cas_add', { content: nulB64, type: 'base64' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
         const meta = JSON.parse(textOf(metaResp));
-        assertEq(meta.url, undefined);
+        assertEq(meta.mime_type, 'application/octet-stream');
+        assertEq(meta.type, 'base64');
     },
     getMetaMissingHashIsError: () => {
         const absent = vecToCBase32(vec8(0x77n));
@@ -357,4 +386,17 @@ export const proof = {
         assert(resultOf(resp).isError === true);
         assert(textOf(resp).includes('/home/user/cas_upload/'));
     },
+    // cas_get with content:true on octet-stream (no magic bytes, not UTF-8) returns inline base64.
+    getOctetStreamWithContentIncludesBase64: () => {
+        const binaryContent = u8ListToVec(msb)([0xFF, 0xFE, 0x00, 0x01]);
+        const binaryB64 = base64Encode(binaryContent);
+        const [addResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }));
+        const hash = textOf(addResp);
+        const [, getResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }), call(3, 'cas_get', { hash, content: true }));
+        assert(!resultOf(getResp).isError);
+        const result = JSON.parse(textOf(getResp));
+        assertEq(result.mime_type, 'application/octet-stream');
+        assertEq(result.type, 'base64');
+        assertEq(result.content, binaryB64);
+    },
 };

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

@@ -6,29 +6,49 @@
 import { type Sha2 } from '../crypto/sha2/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 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';
+import { type Access, type CreateExclusive, type IoResult, type Mkdir, type Now, type RandomInt, type ReadBytes, type Readdir, type Rename, type Rm, type Stat, type WriteBytes } from '../effects/node/module.f.ts';
+import { type List } from '../effects/list/module.f.ts';
 /** Converts a content key to its sharded relative CAS file path. */
 export declare const toPath: (key: Vec) => string;
-export type FileCasOperation = ReadFile | Mkdir | WriteFile | Access | Readdir;
+/**
+ * The filesystem effects the streaming CAS performs: `read` pulls shards
+ * (`ReadBytes`); `list` walks the store (`Access`/`Readdir`); `write` runs the
+ * lock-free staging upload (`Mkdir`/`CreateExclusive`/`WriteBytes`/`Rename`/`Rm`/
+ * `Stat`, lease deadlines from `Now`, staging names from `RandomInt`) and GC's
+ * expired staging files (`Readdir`/`Rm`).
+ */
+export type FileCasOperation = ReadBytes | Mkdir | Readdir | Access | Rename | Rm | RandomInt | Now | CreateExclusive | WriteBytes | Stat | Now | Readdir | Rm;
 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 | undefined>;
+    /**
+     * Streams the content for `hash` out in `<=128 KiB` chunks. Every pull yields an
+     * explicit `ok(chunk)` or `error` item, so a missing shard or I/O error is a distinct
+     * error *item* in the stream, never collapsed into end-of-stream (`undefined`).
+     */
+    readonly read: (hash: Vec) => List<O, IoResult<Vec>>;
+    /**
+     * Consumes a chunk stream — each item `ok(chunk)` or `error` — hashing incrementally,
+     * and returns the content address. An error item aborts the upload.
+     */
+    readonly write: <O1 extends Operation>(payload: List<O1, IoResult<Vec>>) => Effect<O | O1, IoResult<Vec>>;
     /** Lists all stored content hashes. */
     readonly list: () => Effect<O, readonly Vec[]>;
 };
+export type FileCas = Cas<FileCasOperation> & {
+    url: (v: Vec) => string;
+};
 /**
  * Builds a content-addressable storage facade from a SHA-2 implementation.
  */
-export declare const fileCas: (sha2: Sha2) => (path: string) => Cas<FileCasOperation>;
+export declare const fileCas: (sha2: Sha2) => (path: string) => FileCas;
+/**
+ * Streams the file at `path` through `cas.write`, returning the content hash.
+ * Both the CLI `cas add` and the MCP `add` delegate to this; the MCP layer
+ * additionally deletes the source file on success.
+ */
+export declare const casAddFile: <O extends Operation>(cas: Cas<O>) => (path: string) => Effect<O | ReadBytes, IoResult<Vec>>;
 /**
- * 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.
+ * Upload pipeline: streams `fileName` from `~/cas_upload/` through `casAddFile`,
+ * then deletes the source on success. On failure the source is left in place so
+ * the upload can be retried; `write` already cleans up its own partial staging file.
  */
-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>;
+export declare const casUpload: (home: string) => (fileName: string) => Effect<FileCasOperation, IoResult<Vec>>;

package/fs/cas/module.f.js

@@ -3,16 +3,16 @@
  *
  * @module
  */
-import { computeSync, sha256 } from "../crypto/sha2/module.f.js";
+import { 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 { 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 { access, createExclusive, isNotFound, mkdir, now, randomInt, readBytes, readdir, rename, rm, stat, writeBytes, } from "../effects/node/module.f.js";
 import { toOption } from "../types/nullable/module.f.js";
 import { error, ok, unwrap } from "../types/result/module.f.js";
 import { splitAt } from "../types/string/module.f.js";
+import { nonEmpty, empty as elEmpty } from "../effects/list/module.f.js";
 const split2 = splitAt(2);
 const prefix = '.cas';
 /** Converts a content key to its sharded relative CAS file path. */
@@ -22,151 +22,188 @@ export const toPath = (key) => {
     const [b, c] = split2(bc);
     return join(prefix, a, b, c);
 };
+/** Maximum chunk size for streaming reads: the largest `Vec` the runtime allows. */
+const chunkBytes = Number(maxLengthBytes);
+/** Staging directory under the store root; GC and every uploader share it. */
+const stageRel = '_stage';
+/**
+ * Lease duration in ms: a staging file's deadline is `now() + leaseDelta`.
+ * Renewed after every chunk, so it only has to cover the gap between two
+ * consecutive chunks (see [staging-lease.md](../../issues/cas/staging-lease.md)).
+ */
+const leaseDelta = 30_000;
+/**
+ * Fixed width for the zero-padded epoch-ms deadline embedded in a staging name,
+ * so names sort lexically exactly as they sort chronologically. 19 digits keeps
+ * epoch-ms (13 digits today) padded with headroom well past year 2286.
+ */
+const deadlineWidth = 19;
+/** Builds a `<deadline>-<random256>` staging file name. */
+const stageName = (deadline, rnd) => `${String(deadline).padStart(deadlineWidth, '0')}-${rnd}`;
+/** Recovers the deadline (epoch ms) from a `<deadline>-<random256>` name. */
+const deadlineOf = (name) => Number(name.slice(0, name.indexOf('-')));
+/**
+ * Reclaims expired staging files: any `_stage/<deadline>-<rand>` whose deadline
+ * is already in the past. Lazy and piggy-backed on `write`. Best-effort — a
+ * missing `_stage/` (fresh store) or any `readdir`/`rm` error is ignored, and a
+ * still-live lease is left alone; the fencing rename keeps even a misjudged
+ * reclaim fail-safe (worst case: that upload restarts).
+ */
+const gcStage = (stageDir) => now().step(t => readdir(stageDir, {}).step(([k, v]) => {
+    if (k === 'error') {
+        return pure(undefined);
+    }
+    const expired = v.flatMap(d => d.isFile && deadlineOf(d.name) < t ? [d.name] : []);
+    return forEachStep((name) => rm(join(stageDir, name)).step(() => pure(undefined)))(expired);
+}));
 /**
  * Builds a content-addressable storage facade from a SHA-2 implementation.
  */
-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([]);
+export const fileCas = (sha2) => (path) => {
+    const storePrefix = join(path, prefix);
+    const normalizedStorePrefix = normalize(storePrefix);
+    const stageDir = join(storePrefix, stageRel);
+    return {
+        read: (hash) => {
+            const p = join(path, toPath(hash));
+            const loop = (offset) => readBytes(p, offset, chunkBytes)
+                .step((result) => {
+                const [t, v] = result;
+                // A missing shard or read error is an explicit error item, never EOF.
+                if (t === 'error') {
+                    return nonEmpty(result, elEmpty());
+                }
+                // End the stream only on an empty read; every non-empty read — including a
+                // final short (`< CHUNK_BYTES`) chunk — is emitted as an `ok` item.
+                return length(v) === 0n
+                    ? elEmpty()
+                    : nonEmpty(ok(v), loop(offset + chunkBytes));
+            });
+            return loop(0);
+        },
+        // Lock-free staging upload (issues/cas/staging-lease.md): stream each chunk straight
+        // to a `_stage/<deadline>-<rand>` file via `writeBytes` while folding it into the
+        // running SHA-2 state — the payload never lives in memory as a whole. The lease is
+        // renewed (rename to a fresh deadline) after every chunk; any error deletes the
+        // partial file and fails. On end-of-stream the file is published to its hash-derived
+        // shard path by a replace-`rename` (which also dedups/repairs a same-content shard),
+        // and success is confirmed by a `stat` size check. GC of expired staging files is
+        // piggy-backed at the start.
+        write: (payload) => {
+            // Publish the finished staging file to its content-addressed shard. The three
+            // filesystem steps run best-effort with their results ignored; success is decided
+            // afterward by observing the target's size (see staging-lease.md "Publish ignores
+            // results and checks the end state").
+            const publish = (state, offset, curPath) => {
+                const hash = sha2.end(state);
+                const rel = toPath(hash);
+                const dst = join(path, rel);
+                const dstDir = join(path, ...parse(rel).slice(0, -1));
+                return mkdir(dstDir, { recursive: true })
+                    .step(() => rename(curPath, dst))
+                    .step(() => rm(curPath))
+                    .step(() => stat(dst))
+                    .step(st => pure(st[0] === 'ok' && st[1].size === offset ? ok(hash) : error('publish size mismatch')));
+            };
+            // Any streaming error fails closed: delete the partial file, return the error.
+            const fail = (curPath, e) => rm(curPath).step(() => pure(error(e)));
+            return gcStage(stageDir).step(() => random256.step(rnd => {
+                const rndStr = vecToCBase32(rnd);
+                const loop = (state, offset, curPath) => (stream) => stream
+                    .step((node) => {
+                    if (node === undefined) {
+                        return publish(state, offset, curPath);
                     }
-                    throw a[1];
+                    const { first, tail } = node;
+                    if (first[0] === 'error') {
+                        return fail(curPath, first[1]);
+                    }
+                    const chunk = first[1];
+                    return writeBytes(curPath, offset, chunk)
+                        .step(wb => {
+                        if (wb[0] === 'error') {
+                            return fail(curPath, wb[1]);
+                        }
+                        const newState = sha2.append(chunk)(state);
+                        const newOffset = offset + Number(length(chunk) / 8n);
+                        // Renew the lease: rename to a fresh deadline (keeps `delta` constant).
+                        return now()
+                            .step(t => {
+                            const next = join(stageDir, stageName(t + leaseDelta, rndStr));
+                            return rename(curPath, next).step(([t, v]) => t === 'error'
+                                ? fail(curPath, v)
+                                : loop(newState, newOffset, next)(tail));
+                        });
+                    });
+                });
+                return mkdir(stageDir, { recursive: true })
+                    .step(() => now()
+                    .step(t0 => {
+                    const path0 = join(stageDir, stageName(t0 + leaseDelta, rndStr));
+                    return createExclusive(path0)
+                        .step(([c, e]) => c === 'error'
+                        ? pure(error(e))
+                        : loop(sha2.init, 0, path0)(payload));
+                }));
+            }));
+        },
+        list: () => 
+        // A fresh store has no `.cas` directory yet. Treat *only* that case as an
+        // empty store, mirroring how `read` maps a missing shard to an error item.
+        // 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([]);
                 }
-                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))));
-            }),
-        };
+                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))));
+        }),
+        url: (hash) => join(path, toPath(hash))
     };
 };
-/** 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 => {
+/** Streams any file at `filePath` in `<=128 KiB` chunks as a `ListEffect` of `ok` items. */
+const streamFile = (filePath) => {
+    const loop = (offset) => readBytes(filePath, offset, chunkBytes).step((result) => {
         if (result[0] === 'error') {
-            return pure(error(result[1]));
+            return nonEmpty(result, elEmpty());
         }
         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 length(chunk) === 0n
+            ? elEmpty()
+            : nonEmpty(ok(chunk), loop(offset + chunkBytes));
     });
-    return loop(sha2.init, 0);
+    return loop(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.
+ * Streams the file at `path` through `cas.write`, returning the content hash.
+ * Both the CLI `cas add` and the MCP `add` delegate to this; the MCP layer
+ * additionally deletes the source file on success.
+ */
+export const casAddFile = (cas) => (path) => 
+// streamFile produces only ReadBytes effects. TypeScript can't prove ListEffect<ReadBytes,T>
+// ≤ ListEffect<O,T> for generic O (recursive type), but the cast is sound: every concrete
+// caller passes a Cas<O> where ReadBytes ⊆ O (e.g. FileCasOperation).
+cas.write(streamFile(path));
+/**
+ * Upload pipeline: streams `fileName` from `~/cas_upload/` through `casAddFile`,
+ * then deletes the source on success. On failure the source is left in place so
+ * the upload can be retried; `write` already cleans up its own partial staging file.
  */
 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)));
-            });
-        });
+    const c = fileCas(sha256)(home);
+    return casAddFile(c)(src).step((result) => {
+        if (result[0] === 'error') {
+            return pure(result);
+        }
+        return rm(src).step(() => pure(result));
     });
 };
-export const commands = [
-    {
-        names: ['add'],
-        description: 'Store file content and print its hash',
-        handler: ({ home, args: [path, ...rest] }) => {
-            if (path === undefined || rest.length !== 0) {
-                return errorExit("'cas add' expects one parameter");
-            }
-            const c = fileCas(sha256)(home);
-            return readFile(path)
-                .step(v => c.write(unwrap(v)))
-                .step(hash => hash === undefined
-                ? pure(1)
-                : log(vecToCBase32(hash)).step(() => pure(0)));
-        },
-    },
-    {
-        names: ['get'],
-        description: 'Restore content by hash into a file',
-        handler: ({ home, args: [hashCBase32, path, ...rest] }) => {
-            if (hashCBase32 === undefined || path === undefined || rest.length !== 0) {
-                return errorExit("'cas get' expects two parameters");
-            }
-            const hash = cBase32ToVec(hashCBase32);
-            if (hash === null) {
-                return errorExit(`invalid hash format: ${hashCBase32}`);
-            }
-            const c = fileCas(sha256)(home);
-            return c.read(hash)
-                .step(v => {
-                const result = v === undefined
-                    ? errorExit(`no such hash: ${hashCBase32}`)
-                    : writeFile(path, v)
-                        .step(() => pure(0));
-                return result;
-            });
-        },
-    },
-    {
-        names: ['list'],
-        description: 'List all stored content hashes',
-        handler: ({ home }) => {
-            const c = fileCas(sha256)(home);
-            return c.list()
-                .step(forEachStep(j => log(vecToCBase32(j))))
-                .step(() => pure(0));
-        },
-    },
-];
-export const main = dispatch(commands);

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

@@ -1,15 +1,18 @@
+import { type FileCasOperation } from './module.f.ts';
+import { type Effect } from '../effects/module.f.ts';
+import { type ReadFile, type WriteFile, type Rm, type Mkdir } from '../effects/node/module.f.ts';
+type TestOp = FileCasOperation | WriteFile | ReadFile | Rm | Mkdir;
 export declare const proof: {
-    mainAdd: () => void;
-    mainAddWrongArgs: () => void;
-    mainGetFound: () => void;
-    mainGetNotFound: () => void;
-    mainGetWrongArgs: () => void;
-    mainGetInvalidHash: () => void;
-    mainList: () => void;
-    mainListEmptyStore: () => void;
-    mainListCorruptStore: () => void;
-    mainNoCmd: () => void;
-    mainUnknownCmd: () => void;
-    casWrite: () => void;
-    casReadPassthrough: () => void;
+    addBigFile: () => Effect<TestOp, void>;
+    addAndGetBigFile: () => Effect<TestOp, void>;
+    casWriteRead: () => void;
+    casReadMissingShard: () => void;
+    casWriteMultiChunk: () => void;
+    casWriteDedup: () => void;
+    casWriteErrorItemAborts: () => void;
+    casWriteReadExceedsMaxLength: () => void;
+    casWriteGcReclaimsExpired: () => void;
+    casUploadSuccess: () => void;
+    casUploadFailureKeepsSource: () => void;
 };
+export {};