functionalscript 0.44.0 → 0.46.0

package/fjs/cas/evo/types.d.ts

@@ -4,11 +4,32 @@
  *
  * @module
  */
-import type { Operation, Effect } from '../../effects/types.ts';
+import type { Effect, NotImplemented, Operation } from '../../effects/types.ts';
 import type { MemOp } from '../../effects/memory/types.ts';
-import type { Result } from '../../types/result/types.ts';
 import type { StringMap } from '../../types/object/types.ts';
-import type { LockMap } from '../../media/revision/types.ts';
+import type { LockField } from '../../media/revision/types.ts';
+/**
+ * A revision was rejected on its own terms: a parent that does not resolve, a
+ * hash that is not cBase32, a blob that holds something other than a
+ * `vnd.fjs.revision`, a store that would not take the write.
+ *
+ * A tagged tuple rather than a bare `string` so it joins {@link NotImplemented}
+ * and `IoError` as a discriminated union rather than a structural one — a
+ * renderer switches on the tag it already switches on, instead of testing
+ * `typeof`.
+ */
+export type EvoError = readonly ['evoError', string];
+/**
+ * The error channel of the Evo API: the revision was rejected, or the runner
+ * could not dispatch an operation.
+ *
+ * Host IO failures do **not** appear here as `IoError`. A store that cannot be
+ * read or written is reported as an {@link EvoError} whose message says so,
+ * because from this API's outside a blob that cannot be delivered and a blob
+ * that is not a revision are the same answer — "no revision at that hash" —
+ * and the caller has the same recourse to both.
+ */
+export type EvoChannel = EvoError | NotImplemented;
 /** A cBase32 content hash, as accepted/returned by `Cas<O>`. */
 export type Hash = string;
 /** The identity of a mutable object whose revisions are being evolved. */
@@ -38,6 +59,12 @@ export type Subject = string;
  * - `generation` — input: **ignored**, {@link computeGeneration} derives the
  *   authoritative value from the parents; output: always present. It exists as
  *   an input field only so a read value round-trips into `add` as-is.
+ * - `lock` — the format's own field, so it is an inline map or the hash of a
+ *   `vnd.fjs.lock` blob (`fjs/media/lock`) holding one. Both directions
+ *   validate and canonicalize every hash it names — the reference itself, or
+ *   each direct value at every depth of a map. Following a reference is not
+ *   done here: evo stores and reads revisions, it does not resolve
+ *   dependencies.
  *
  * Relaxing what the format requires is the point, not an oversight. The stored
  * `vnd.fjs.revision` blob requires `subject`, `snapshot` and `generation`, and
@@ -58,7 +85,7 @@ export type RevisionData = {
     readonly subject?: Subject | undefined;
     readonly archived?: true | undefined;
     readonly generation?: number | undefined;
-    readonly lock?: LockMap | undefined;
+    readonly lock?: LockField | undefined;
 };
 /**
  * Per-subject bookkeeping: every revision hash seen for the subject, every
@@ -94,11 +121,20 @@ export type Evo<O extends Operation> = {
      * adding it later is a compatible extension of this parameter, while
      * removing it would not be.
      */
-    readonly list: (archived?: true) => Effect<MemOp, readonly Subject[]>;
+    readonly list: (archived?: true) => Effect<MemOp, readonly Subject[], NotImplemented>;
     /** Returns the current head hashes of `subject` (empty if unknown). */
-    readonly head: (subject: Subject) => Effect<MemOp, readonly Hash[]>;
-    /** Adds a new head; see {@link addRevision}. */
-    readonly add: (input: RevisionData) => Effect<O | MemOp, Result<Hash, string>>;
+    readonly head: (subject: Subject) => Effect<MemOp, readonly Hash[], NotImplemented>;
+    /**
+     * Adds a new head; see {@link addRevision}.
+     *
+     * A rejected revision and an undispatchable operation are both failures and
+     * share the channel, as {@link EvoChannel}'s two cases. They stay tellable
+     * apart — that is what the tags are for, and a caller that renders them
+     * differently switches on one — but they do not need separate *layers* to
+     * be told apart, and giving them separate layers costs every intermediate
+     * step a hand-written short-circuit that `step` would otherwise do.
+     */
+    readonly add: (input: RevisionData) => Effect<O | MemOp, Hash, EvoChannel>;
     /**
      * The revision at `hash`, decoded, validated, and canonicalized; see
      * {@link readRevision}. Served from the store today, so the `MemOp` in the
@@ -107,5 +143,5 @@ export type Evo<O extends Operation> = {
      * operations read, which must not become a breaking change to this type
      * when it happens.
      */
-    readonly revision: (hash: Hash) => Effect<O | MemOp, Result<RevisionData, string>>;
+    readonly revision: (hash: Hash) => Effect<O | MemOp, RevisionData, EvoChannel>;
 };

package/fjs/cas/module.f.d.mts

@@ -5,24 +5,19 @@
  *
  * @import { Sha2, State as Sha2State } from '../crypto/sha2/types.ts'
  * @import { Vec } from '../types/bit_vec/types.ts'
- * @import { Effect, Operation } from '../effects/types.ts'
- * @import {
- *  IoResult,
- *  Now,
- *  RandomInt,
- *  ReadBytes,
- *  Readdir,
- *  Rm,
- * } from '../effects/node/types.ts'
+ * @import { Operation } from '../effects/types.ts'
+ * @import { Effect, NotImplemented } from '../effects/types.ts'
+ * @import { IoChannel, Now, RandomInt, ReadBytes, Readdir, Rm } from '../effects/node/types.ts'
  *  @import { List } from '../effects/list/types.ts'
  * @import { Cas, FileCas, FileCasOperation } from './types.ts'
  */
 import type { Sha2 } from '../crypto/sha2/types.ts';
 import type { Vec } from '../types/bit_vec/types.ts';
-import type { Effect, Operation } from '../effects/types.ts';
-import type { IoResult, ReadBytes } from '../effects/node/types.ts';
+import type { Operation } from '../effects/types.ts';
+import type { Effect } from '../effects/types.ts';
+import type { IoChannel, ReadBytes } from '../effects/node/types.ts';
 import type { List } from '../effects/list/types.ts';
-import type { Cas, FileCas, FileCasOperation } from './types.ts';
+import type { Cas, FileCas } from './types.ts';
 /** Converts a content key to its sharded relative CAS file path.
  *
  * @type {(key: Vec) => string}
@@ -31,17 +26,16 @@ export declare const toPath: (key: Vec) => string;
 /**
  * Drains a `Cas<O>.read` chunk stream into a single `Vec`. Used by any caller
  * that needs the whole blob at once (an MCP `content: true` fetch, an Evo
- * revision decode): the chunk stream is concatenated and an error item is
- * surfaced as the result. A single `Vec` cannot exceed `maxLength` bits;
- * concatenating past it would overflow the runtime's `bigint` constraint, so
- * that case is surfaced as an error item too, rather than crashing the
- * process.
+ * revision decode): the chunk stream is concatenated, and a stream that fails
+ * fails this. A single `Vec` cannot exceed `maxLength` bits; concatenating past
+ * it would overflow the runtime's `bigint` constraint, so that case fails here
+ * too rather than crashing the process.
  *
  * @template {Operation} O
- * @param {List<O, IoResult<Vec>>} stream
- * @returns {Effect<O, IoResult<Vec>>}
+ * @param {List<O, Vec, IoChannel>} stream
+ * @returns {Effect<O, Vec, IoChannel>}
  */
-export declare const collectRead: <O extends Operation>(stream: List<O, IoResult<Vec>>) => Effect<O, IoResult<Vec>>;
+export declare const collectRead: <O extends Operation>(stream: List<O, Vec, IoChannel>) => Effect<O, Vec, IoChannel>;
 /**
  * Builds a content-addressable storage facade from a SHA-2 implementation.
  *
@@ -50,19 +44,11 @@ export declare const collectRead: <O extends Operation>(stream: List<O, IoResult
 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.
+ * Its one consumer is the CLI's `cas add`; the MCP `cas_add` tool takes inline
+ * content and calls `write` itself, so it does not come through here.
  *
  * @template {Operation} O
  * @param {Cas<O>} cas
- * @returns {(path: string) => Effect<O | ReadBytes, IoResult<Vec>>}
+ * @returns {(path: string) => Effect<O | ReadBytes, Vec, IoChannel>}
  */
-export declare const casAddFile: <O extends Operation>(cas: Cas<O>) => (path: string) => Effect<O | ReadBytes, IoResult<Vec>>;
-/**
- * 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.
- *
- * @type {(home: string) => (fileName: string) => Effect<FileCasOperation, IoResult<Vec>>}
- */
-export declare const casUpload: (home: string) => (fileName: string) => Effect<FileCasOperation, IoResult<Vec>>;
+export declare const casAddFile: <O extends Operation>(cas: Cas<O>) => (path: string) => Effect<O | ReadBytes, Vec, IoChannel>;

package/fjs/cas/module.f.mjs

@@ -5,28 +5,33 @@
  *
  * @import { Sha2, State as Sha2State } from '../crypto/sha2/types.ts'
  * @import { Vec } from '../types/bit_vec/types.ts'
- * @import { Effect, Operation } from '../effects/types.ts'
- * @import {
- *  IoResult,
- *  Now,
- *  RandomInt,
- *  ReadBytes,
- *  Readdir,
- *  Rm,
- * } from '../effects/node/types.ts'
+ * @import { Operation } from '../effects/types.ts'
+ * @import { Effect, NotImplemented } from '../effects/types.ts'
+ * @import { IoChannel, Now, RandomInt, ReadBytes, Readdir, Rm } from '../effects/node/types.ts'
  *  @import { List } from '../effects/list/types.ts'
  * @import { Cas, FileCas, FileCasOperation } from './types.ts'
  */
 
-import { sha256 } from '../crypto/sha2/module.f.mjs'
 import { join, normalize, parse } from '../path/module.f.mjs'
 import { empty, length, maxLength, maxLengthBytes, msb, vec } from '../types/bit_vec/module.f.mjs'
 import { cBase32ToVec, vecToCBase32 } from '../basen/cbase32/module.f.mjs'
-import { foldStep, forEachStep, history, historyStep, okStep, pure, step } from '../effects/module.f.mjs'
-import { eff } from '../effects/eff/module.f.mjs'
+import {
+    catchStep,
+    foldStep,
+    forEachStep,
+    history,
+    historyStep,
+    mapStep as ioMapStep,
+    pureError,
+    pureOk,
+    resultMapStep,
+    resultStep,
+    step as ioStep,
+} from '../effects/module.f.mjs'
 import {
     access,
     createExclusive,
+    ioError,
     isNotFound,
     mkdir,
     now,
@@ -39,7 +44,7 @@ import {
     writeBytes,
 } from '../effects/node/module.f.mjs'
 import { toOption } from '../types/nullable/module.f.mjs'
-import { error, ok, unwrap } from '../types/result/module.f.mjs'
+import { error, ok } from '../types/result/module.f.mjs'
 import { splitAt } from '../types/string/module.f.mjs'
 import { nonEmpty, empty as elEmpty } from '../effects/list/module.f.mjs'
 
@@ -61,31 +66,26 @@ export const toPath = key => {
 /**
  * Drains a `Cas<O>.read` chunk stream into a single `Vec`. Used by any caller
  * that needs the whole blob at once (an MCP `content: true` fetch, an Evo
- * revision decode): the chunk stream is concatenated and an error item is
- * surfaced as the result. A single `Vec` cannot exceed `maxLength` bits;
- * concatenating past it would overflow the runtime's `bigint` constraint, so
- * that case is surfaced as an error item too, rather than crashing the
- * process.
+ * revision decode): the chunk stream is concatenated, and a stream that fails
+ * fails this. A single `Vec` cannot exceed `maxLength` bits; concatenating past
+ * it would overflow the runtime's `bigint` constraint, so that case fails here
+ * too rather than crashing the process.
  *
  * @template {Operation} O
- * @param {List<O, IoResult<Vec>>} stream
- * @returns {Effect<O, IoResult<Vec>>}
+ * @param {List<O, Vec, IoChannel>} stream
+ * @returns {Effect<O, Vec, IoChannel>}
  */
 export const collectRead = stream => {
-    /** @type {(acc: Vec) => (s: List<O, IoResult<Vec>>) => Effect<O, IoResult<Vec>>} */
+    /** @type {(acc: Vec) => (s: List<O, Vec, IoChannel>) => Effect<O, Vec, IoChannel>} */
     const loop = acc => s =>
-        eff(s)
-            .step((/** @type {*} */ node) => {
-                if (node === undefined) { return pure(ok(acc)) }
-                const { first, tail } = node
-                const [t, v] = first
-                if (t === 'error') { return pure(first) }
-                if (length(acc) + length(v) > maxLength) {
-                    return pure(error(`cas blob exceeds maximum vector length of ${maxLength} bits`))
-                }
-                return loop(msb.concat(acc)(v))(tail)
-            })
-            .value
+        ioStep(s, node => {
+            if (node === undefined) { return pureOk(acc) }
+            const { first, tail } = node
+            if (length(acc) + length(first) > maxLength) {
+                return pureError(ioError({ message: `cas blob exceeds maximum vector length of ${maxLength} bits` }))
+            }
+            return loop(msb.concat(acc)(first))(tail)
+        })
     return loop(empty)(stream)
 }
 
@@ -129,25 +129,34 @@ const deadlineOf = name => Number(name.slice(0, name.indexOf('-')))
  * still-live lease is left alone; the fencing rename keeps even a misjudged
  * reclaim fail-safe (worst case: that upload restarts).
  *
- * @template {Now | Readdir | Rm} O
- * @param {string} stageDir
- * @returns {Effect<O, void>}
+ * The error channel is `never`, and that is the claim this function makes: it
+ * catches every failure it can produce, so an upload composing it cannot fail
+ * because of a sweep.
+ *
+ * @type {(stageDir: string) => Effect<Now | Readdir | Rm, void, never>}
  */
-const gcStage = stageDir =>
-    eff(now())
-        .step(() => readdir(stageDir, {}))
-        .step(([k, v], t) => {
-            if (k === 'error') { return pure(undefined) }
-            const expired = v.flatMap(d =>
+const gcStage = stageDir => {
+    // The `readdir` result and the `now()` timestamp are both needed by the last
+    // link, so the timestamp is carried forward in a history rather than closed
+    // over by a nested continuation.
+    const listed = historyStep(
+        history(now()),
+        () => readdir(stageDir, {}))
+    const swept = ioStep(
+        listed,
+        ([dirents, t]) => {
+            const expired = dirents.flatMap(d =>
                 d.isFile && deadlineOf(d.name) < t ? [d.name] : [])
+            // Each `rm` recovers on its own, so one undeletable file does not
+            // stop the sweep at the file before it.
             return forEachStep(
-                pure(expired),
-                name =>
-                    eff(rm(join(stageDir, name)))
-                        .step(() => pure(undefined))
-                        .value)
+                pureOk(expired),
+                name => catchStep(rm(join(stageDir, name)), () => pureOk(undefined)))
         })
-        .value
+    // A fresh store has no `_stage/` yet, and a sweep that cannot run must not
+    // fail the upload it is piggy-backed on.
+    return catchStep(swept, () => pureOk(undefined))
+}
 
 // Lock-free staging upload (plan/staging-lease.md): stream each chunk straight
 // to a `_stage/<deadline>-<rand>` file via `writeBytes` while folding it into the
@@ -162,83 +171,86 @@ const gcStage = stageDir =>
  * @param {Sha2} sha2
  * @param {string} path
  * @param {string} stageDir
- * @param {List<O1, IoResult<Vec>>} payload
- * @returns {Effect<O1 | FileCasOperation, IoResult<Vec>>}
+ * @param {List<O1, Vec, IoChannel>} payload
+ * @returns {Effect<O1 | FileCasOperation, Vec, IoChannel>}
  */
 const writeImpl = (sha2, path, stageDir, 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").
-    /** @type {(state: Sha2State, offset: number, curPath: string) => Effect<FileCasOperation, IoResult<Vec>>} */
+    /** @type {(state: Sha2State, offset: number, curPath: string) => Effect<FileCasOperation, Vec, IoChannel>} */
     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 eff(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')))
-            .value
+        // `resultStep` throughout, and that is the "ignores results" above
+        // written in the type: each link runs whatever the previous one
+        // answered, and only the closing `stat` decides the outcome.
+        const created = resultStep(mkdir(dstDir, { recursive: true }), () => rename(curPath, dst))
+        const removed = resultStep(created, () => rm(curPath))
+        const stated = resultStep(removed, () => stat(dst))
+        return resultMapStep(
+            stated,
+            st => st[0] === 'ok' && st[1].size === offset ? ok(hash) : error(ioError({ message: 'publish size mismatch' })))
     }
     // Any streaming error fails closed: delete the partial file, return the error.
-    /** @type {(curPath: string, e: unknown) => Effect<FileCasOperation, IoResult<Vec>>} */
+    /** @type {(curPath: string, e: IoChannel) => Effect<FileCasOperation, Vec, IoChannel>} */
     const fail = (curPath, e) =>
-        eff(rm(curPath))
-            .step(() => pure(error(e)))
-            .value
-    return eff(gcStage(stageDir)).step(() =>
-        eff(random256).step(rnd => {
-            const rndStr = vecToCBase32(rnd)
-            /** @type {(state: Sha2State, offset: number, curPath: string) => (stream: List<O1, IoResult<Vec>>) => Effect<O1 | FileCasOperation, IoResult<Vec>>} */
-            const loop = (state, offset, curPath) =>
-                stream =>
-                    eff(stream)
-                        .step((node) => {
-                            if (node === undefined) {
-                                return publish(state, offset, curPath)
-                            }
-                            const { first, tail } = node
-                            if (first[0] === 'error') {
-                                return fail(curPath, first[1])
-                            }
-                            const chunk = first[1]
-                            return eff(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).
-                                    // The new path is still needed after the rename, to recurse with,
-                                    // so the rename captures it rather than closing over it.
-                                    const nextPath = step(
-                                        now(),
-                                        t => pure(join(stageDir, stageName(t + leaseDelta, rndStr))))
-                                    const renamed = historyStep(
-                                        history(nextPath),
-                                        next => rename(curPath, next))
-                                    return step(
-                                        renamed,
-                                        ([[rt, v], next]) =>
-                                            rt === 'error'
-                                                ? fail(curPath, v)
-                                                : loop(newState, newOffset, next)(tail))
-                                })
-                                .value
-                        })
-                        .value
-            return eff(mkdir(stageDir, { recursive: true }))
-                .step(() => now())
-                .step(t0 => {
-                    const path0 = join(stageDir, stageName(t0 + leaseDelta, rndStr))
-                    return eff(createExclusive(path0))
-                        .step(okStep(() => loop(sha2.init, 0, path0)(payload)))
-                        .value
+        // The cleanup's own outcome is discarded on purpose: `e` is what the
+        // caller needs to hear, and a failed `rm` has no better answer.
+        resultMapStep(rm(curPath), () => error(e))
+    const rndEffect = ioStep(gcStage(stageDir), () => random256)
+    return ioStep(rndEffect, rnd => {
+        const rndStr = vecToCBase32(rnd)
+        /** @type {(state: Sha2State, offset: number, curPath: string) => (stream: List<O1, Vec, IoChannel>) => Effect<O1 | FileCasOperation, Vec, IoChannel>} */
+        const loop = (state, offset, curPath) =>
+            stream =>
+                // `resultStep`, not `step`: a stream that fails must still be
+                // cleaned up after, so this handles the failure rather than
+                // letting it propagate past the partial file.
+                resultStep(stream, r => {
+                    if (r[0] === 'error') {
+                        return fail(curPath, r[1])
+                    }
+                    const node = r[1]
+                    if (node === undefined) {
+                        return publish(state, offset, curPath)
+                    }
+                    const { first: chunk, tail } = node
+                    // Both branches matter: a failed write is cleaned up after,
+                    // rather than propagated with the partial file left behind.
+                    return resultStep(writeBytes(curPath, offset, chunk), 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).
+                        // The new path is still needed after the rename, to recurse with,
+                        // so the rename captures it rather than closing over it.
+                        const nextPath = ioMapStep(
+                            now(),
+                            t => join(stageDir, stageName(t + leaseDelta, rndStr)))
+                        const renamed = historyStep(
+                            history(nextPath),
+                            next => rename(curPath, next))
+                        return resultStep(
+                            renamed,
+                            r => {
+                                if (r[0] === 'error') { return fail(curPath, r[1]) }
+                                const [, next] = r[1]
+                                return loop(newState, newOffset, next)(tail)
+                            })
+                    })
                 })
-                .value
-        }).value).value
+        const started = ioStep(mkdir(stageDir, { recursive: true }), () => now())
+        return ioStep(started, t0 => {
+            const path0 = join(stageDir, stageName(t0 + leaseDelta, rndStr))
+            return ioStep(
+                createExclusive(path0),
+                () => loop(sha2.init, 0, path0)(payload))
+        })
+    })
 }
 
 /**
@@ -253,44 +265,41 @@ export const fileCas = sha2 => path => {
     return {
         read: hash => {
             const p = join(path, toPath(hash))
-            /** @type {(offset: number) => List<FileCasOperation, IoResult<Vec>>} */
+            /** @type {(offset: number) => List<FileCasOperation, Vec, IoChannel>} */
             const loop = offset =>
-                eff(readBytes(p, offset, chunkBytes))
-                    .step(/** @type {(result: IoResult<Vec>) => List<FileCasOperation, IoResult<Vec>>} */ (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))
-                    })
-                    .value
+                // A missing shard or read error fails the stream, and `step`
+                // propagates it — the cell's own failure can never be mistaken
+                // for the `undefined` that ends one.
+                ioStep(
+                    readBytes(p, offset, chunkBytes),
+                    // End the stream only on an empty read; every non-empty read — including a
+                    // final short (`< CHUNK_BYTES`) chunk — is emitted as a cell.
+                    chunk => length(chunk) === 0n
+                        ? elEmpty()
+                        : nonEmpty(chunk, loop(offset + chunkBytes)))
             return loop(0)
         },
         write: payload => writeImpl(sha2, path, stageDir, 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.
+            // empty store, mirroring how `read` fails a stream on a missing shard.
             // A `.cas` that exists but cannot be read (permissions, corruption) is a
             // genuine storage error and is surfaced, not masked as "no hashes".
-            eff(access(storePrefix))
-                .step(a => {
-                    if (a[0] === 'error') {
-                        if (isNotFound(a[1])) { return pure(/** @type {readonly Vec[]} */ ([])) }
-                        throw a[1]
-                    }
-                    return eff(readdir(storePrefix, { recursive: true }))
-                        .step(r => pure(unwrap(r).flatMap(({ name, parentPath, isFile }) =>
+            //
+            // `resultStep` because both branches genuinely matter: the absent
+            // store is a success answering `ok([])`, and every other failure is
+            // the caller's to see. It used to `throw` here, which is what the
+            // paragraph above always meant by "surfaced" but could not say
+            // while the return type had no error channel to say it in.
+            resultStep(access(storePrefix), a =>
+                a[0] === 'error'
+                    ? isNotFound(a[1]) ? pureOk([]) : pureError(a[1])
+                    : ioMapStep(
+                        readdir(storePrefix, { recursive: true }),
+                        r => r.flatMap(({ name, parentPath, isFile }) =>
                             toOption(isFile
                                 ? cBase32ToVec(normalize(parentPath).substring(normalizedStorePrefix.length).replaceAll('/', '') + name)
-                                : null))))
-                        .value
-                })
-                .value,
+                                : null)))),
         url: hash =>
             join(path, toPath(hash))
     }
@@ -298,46 +307,41 @@ export const fileCas = sha2 => path => {
 
 /** 256-bit random `Vec` built from 8 sequential `randomInt` (32-bit) calls.
  *
- * @type {Effect<RandomInt, Vec>}
+ * @type {Effect<RandomInt, Vec, NotImplemented>}
  */
 const random256 =
     foldStep(
-        pure([0, 1, 2, 3, 4, 5, 6, 7]),
+        pureOk([0, 1, 2, 3, 4, 5, 6, 7]),
         empty,
         () => (/** @type {Vec} */ acc) =>
-            eff(randomInt())
-                .step(r => pure(msb.concat(acc)(vec(32n)(BigInt(r)))))
-                .value)
+            ioMapStep(randomInt(), r => msb.concat(acc)(vec(32n)(BigInt(r)))))
 
-/** Streams any file at `filePath` in `<=128 KiB` chunks as a `ListEffect` of `ok` items.
+/** Streams any file at `filePath` in `<=128 KiB` chunks.
+ *
+ * A failed read fails the stream. It used to be yielded as an error *item*
+ * followed by an explicit empty tail — a tail no consumer would ever pull.
  *
- * @type {(filePath: string) => List<ReadBytes, IoResult<Vec>>}
+ * @type {(filePath: string) => List<ReadBytes, Vec, IoChannel>}
  */
 const streamFile = filePath => {
-    /** @type {(offset: number) => List<ReadBytes, IoResult<Vec>>} */
+    /** @type {(offset: number) => List<ReadBytes, Vec, IoChannel>} */
     const loop = offset =>
-        eff(readBytes(filePath, offset, chunkBytes))
-            .step(/** @type {(result: IoResult<Vec>) => List<ReadBytes, IoResult<Vec>>} */ (result) => {
-                if (result[0] === 'error') {
-                    return nonEmpty(result, elEmpty())
-                }
-                const chunk = result[1]
-                return length(chunk) === 0n
-                    ? elEmpty()
-                    : nonEmpty(ok(chunk), loop(offset + chunkBytes))
-            })
-            .value
+        ioStep(
+            readBytes(filePath, offset, chunkBytes),
+            chunk => length(chunk) === 0n
+                ? elEmpty()
+                : nonEmpty(chunk, loop(offset + chunkBytes)))
     return loop(0)
 }
 
 /**
  * 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.
+ * Its one consumer is the CLI's `cas add`; the MCP `cas_add` tool takes inline
+ * content and calls `write` itself, so it does not come through here.
  *
  * @template {Operation} O
  * @param {Cas<O>} cas
- * @returns {(path: string) => Effect<O | ReadBytes, IoResult<Vec>>}
+ * @returns {(path: string) => Effect<O | ReadBytes, Vec, IoChannel>}
  */
 export const casAddFile = cas => path =>
     // streamFile produces only ReadBytes effects. TypeScript can't prove ListEffect<ReadBytes,T>
@@ -345,19 +349,3 @@ export const casAddFile = cas => path =>
     // 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.
- *
- * @type {(home: string) => (fileName: string) => Effect<FileCasOperation, IoResult<Vec>>}
- */
-export const casUpload = home => fileName => {
-    const src = join(home, 'cas_upload', fileName)
-    const c = fileCas(sha256)(home)
-    return eff(casAddFile(c)(src))
-        .step(okStep(/** @type {(v: Vec) => Effect<Rm, IoResult<Vec>>} */ (v => eff(rm(src))
-            .step(() => pure(ok(v)))
-            .value)))
-        .value
-}