functionalscript 0.38.0 → 0.39.0

package/fjs/cas/evo/module.f.js

@@ -30,9 +30,17 @@
  * both fold through the same {@link addRevisionToCache}, the former over the
  * whole store at once, the latter incrementally for one new revision.
  *
+ * Not everything here is cache-backed: {@link readRevision} answers "what is
+ * the revision at this hash" straight from the store, decoded, validated, and
+ * with every hash canonicalized ({@link toRevisionData}). It is the typed
+ * counterpart of a raw blob read — {@link addRevision} validates on the way
+ * in, {@link readRevision} on the way out — and both speak the same
+ * {@link RevisionData} vocabulary.
+ *
  * @module
  */
 import { pure, foldStep } from '../../effects/module.f.js';
+import { eff } from '../../effects/eff/module.f.js';
 import { create, read, write } from '../../effects/memory/module.f.js';
 import { collectRead } from '../module.f.js';
 import { cBase32ToVec, vecToCBase32 } from '../../basen/cbase32/module.f.js';
@@ -45,6 +53,7 @@ import { ok, error } from '../../types/result/module.f.js';
 import { nonEmpty, empty as elEmpty } from '../../effects/list/module.f.js';
 import { at, definedEntries } from '../../types/object/module.f.js';
 import { unwrap } from '../../types/nullable/module.f.js';
+import { isNotFound } from '../../effects/node/module.f.js';
 /** A cache with no known subjects yet — the starting point for {@link buildCache}. */
 export const emptyCache = { bySubject: {} };
 /** Canonical JSON encoder for a `Revision` — key order carries no meaning for detection. */
@@ -76,7 +85,7 @@ const headsOf = (state) => state.hashes.filter(h => !state.parents.includes(h));
  *
  * Looks `revision.subject` up via {@link at} (own-property only), not plain
  * bracket indexing: a subject is an arbitrary caller-supplied string
- * (`AddRevision.subject`, or the MCP `evo_add`/`evo_head` argument), so it
+ * (`RevisionData.subject`, or the MCP `evo_add`/`evo_head` argument), so it
  * can collide with an inherited `Object.prototype` name (`toString`,
  * `constructor`, …) — bracket indexing would then return that inherited
  * value instead of "no entry yet" and crash on the (non-array) `.hashes`
@@ -110,16 +119,24 @@ export const decodeRevisionVec = (value) => {
  * parse/validate as the dialect — so a store containing arbitrary other
  * content can be scanned without failing the whole cache build.
  */
-export const decodeRevisionBlob = (cas) => (hash) => collectRead(cas.read(hash)).step(([tag, value]) => pure(tag === 'error' ? null : decodeRevisionVec(value)));
+export const decodeRevisionBlob = (cas) => (hash) => eff(collectRead(cas.read(hash)))
+    .map(([tag, value]) => tag === 'error' ? null : decodeRevisionVec(value))
+    .value;
 /**
  * Scans every hash in `cas` and builds a fresh {@link Cache} from the
  * `vnd.fjs.revision` blobs found among them. Non-revision blobs are ignored.
  */
-export const buildCache = (cas) => cas.list().step(hashes => foldStep((hash) => (cache) => decodeRevisionBlob(cas)(hash).step(revision => pure(revision === null ? cache : addRevisionToCache(vecToCBase32(hash), revision)(cache))))(emptyCache)(hashes));
+export const buildCache = (cas) => foldStep(cas.list(), emptyCache, hash => cache => eff(decodeRevisionBlob(cas)(hash))
+    .step(revision => pure(revision === null ? cache : addRevisionToCache(vecToCBase32(hash), revision)(cache)))
+    .value);
 /** Scans `cas` once and allocates a memory slot holding the resulting {@link Cache}. */
-export const initEvo = (cas) => buildCache(cas).step(cache => create(cache));
+export const initEvo = (cas) => eff(buildCache(cas))
+    .step(cache => create(cache))
+    .value;
 /** Reads, then rewrites, the cache at `cacheKey` with `revision` folded in at `hash`. */
-const foldIntoCache = (cacheKey) => (hash) => (revision) => read(cacheKey).step(cache => write(cacheKey, addRevisionToCache(hash, revision)(cache)).step(() => pure(undefined)));
+const foldIntoCache = (cacheKey) => (hash) => (revision) => eff(read(cacheKey))
+    .step(cache => write(cacheKey, addRevisionToCache(hash, revision)(cache)))
+    .value;
 /**
  * Folds `value` — bytes already written to a `Cas` at `hash` by some other
  * caller — into the cache at `cacheKey` if it decodes as a `vnd.fjs.revision`
@@ -145,17 +162,21 @@ const resolveParent = (cas) => (parentRef) => {
     if (parentHash === null) {
         return pure(error(`invalid parent hash: ${parentRef}`));
     }
-    return decodeRevisionBlob(cas)(parentHash).step(parent => pure(parent === null ? error(`parent is not a revision blob: ${parentRef}`) : ok(parent)));
+    return eff(decodeRevisionBlob(cas)(parentHash))
+        .step(parent => pure(parent === null ? error(`parent is not a revision blob: ${parentRef}`) : ok(parent)))
+        .value;
 };
 /** Resolves and validates every entry of `parents`, in order, short-circuiting on the first failure. */
 const resolveParents = (cas) => (parents) => {
     const init = ok([]);
-    return foldStep((parentRef) => (acc) => {
+    return foldStep(pure(parents), init, parentRef => (acc) => {
         if (acc[0] === 'error') {
             return pure(acc);
         }
-        return resolveParent(cas)(parentRef).step((parentResult) => pure(parentResult[0] === 'error' ? parentResult : ok([...acc[1], parentResult[1]])));
-    })(init)(parents);
+        return eff(resolveParent(cas)(parentRef))
+            .step((parentResult) => pure(parentResult[0] === 'error' ? parentResult : ok([...acc[1], parentResult[1]])))
+            .value;
+    });
 };
 /**
  * Resolves the `subject` of a new revision from its already-resolved
@@ -220,7 +241,8 @@ const resolveSnapshot = (input) => (subject) => (parents) => {
  * (`parents: []`), else `1 + max(parents' generations)`. Computed here from
  * the already-decoded parents, never taken from input — everything evo writes
  * follows the formula by construction (see the `generation` semantics in
- * [`fjs/cas/evo/todo/evo-revision.md`](todo/evo-revision.md)).
+ * [`fjs/media/revision/README.md`](../../media/revision/README.md), where a
+ * deviation is a readable epoch-reset signal rather than an invalid blob).
  *
  * The max is a `reduce`, not `Math.max(...parents.map(...))`: `parents` is
  * caller-sized (the direct API or the `evo_add` MCP tool), and argument-spread
@@ -244,8 +266,14 @@ const computeGeneration = (parents) => parents.length === 0 ? 0 : 1 + parents.re
  * revision, a blob too large to encode, or a store write failure — is
  * reported as `error(message)` rather than thrown, so a caller (e.g. an MCP
  * tool handler) can surface it without a `throw`/`catch`.
+ *
+ * `input.generation` is ignored: it exists on {@link RevisionData} only so a
+ * value read back by {@link readRevision} round-trips into `add` unchanged,
+ * and {@link computeGeneration} always derives the stored value from the
+ * resolved parents.
  */
-export const addRevision = (cas) => (cacheKey) => (input) => resolveParents(cas)(input.parents).step((parentsResult) => {
+export const addRevision = (cas) => (cacheKey) => (input) => eff(resolveParents(cas)(input.parents))
+    .step((parentsResult) => {
     if (parentsResult[0] === 'error') {
         return pure(parentsResult);
     }
@@ -289,21 +317,105 @@ export const addRevision = (cas) => (cacheKey) => (input) => resolveParents(cas)
     if (bytes === null) {
         return pure(error('revision too large to encode'));
     }
-    return cas.write(nonEmpty(ok(bytes), elEmpty()))
+    return eff(cas.write(nonEmpty(ok(bytes), elEmpty())))
         .step((writeResult) => {
         if (writeResult[0] === 'error') {
             return pure(error('failed to write revision to CAS'));
         }
         const hash = vecToCBase32(writeResult[1]);
-        return foldIntoCache(cacheKey)(hash)(canonicalRevision).step(() => pure(ok(hash)));
-    });
+        return eff(foldIntoCache(cacheKey)(hash)(canonicalRevision))
+            .step(() => pure(ok(hash)))
+            .value;
+    })
+        .value;
+})
+    .value;
+/**
+ * Projects a decoded `Revision` into the shared {@link RevisionData}
+ * vocabulary: `dialect` is dropped (a serialization tag with no information
+ * left once decoding has validated it), and every hash is re-spelled
+ * canonically ({@link canonicalHash}) so a read compares directly against
+ * {@link Evo.head}'s output instead of against whatever spelling the blob's
+ * writer happened to use. `checkReferences` ran as part of decoding, so every
+ * `parents` entry and the `snapshot` are known to decode and the `unwrap`
+ * inside `canonicalHash` is safe. Field order follows the stored blob's
+ * (minus `dialect`), which is what a JSON encoding of the result shows.
+ */
+const toRevisionData = ({ subject, parents, snapshot, generation, archived }) => ({
+    subject,
+    parents: parents.map(canonicalHash),
+    snapshot: canonicalHash(snapshot),
+    generation,
+    archived,
 });
+/**
+ * Second stage of {@link readRevision}: interprets an already-performed read
+ * of `hash`. Kept apart from the read itself so the failures stay
+ * distinguishable — "not present in the store" and "present but not a
+ * revision" are different answers to a client, and
+ * {@link decodeRevisionBlob}, which composes the same two stages internally,
+ * deliberately collapses both into `null` for store scanning.
+ *
+ * A failed read is only reported as *not found* when it is a genuine miss —
+ * `isNotFound`, the same ENOENT test `fjs/cas`'s `list` uses to tell an
+ * unwritten store from an unreadable one. A `Cas` read can also fail on a
+ * blob that exists: a permission or mid-stream I/O error, or content too
+ * large to buffer into one `Vec` (`collectRead`). Calling any of those "not
+ * found" would deny a stored revision exists, so they are their own message.
+ *
+ * A blob deleted *during* the read lands here as a miss too, and that is the
+ * honest answer rather than a gap in the split. `fileCas` streams in chunks,
+ * so a delete between two of them fails a later chunk with ENOENT after
+ * earlier ones succeeded — but by the time this result is produced the store
+ * genuinely no longer has the blob, and the very next read says "not found"
+ * with no race left to observe. `collectRead` reports how a read ended, not
+ * how far it got; recovering that difference would mean folding the chunk
+ * stream here instead of reusing `collectRead`, for a distinction no client
+ * can act on differently.
+ */
+const decodeReadRevision = (hash) => ([tag, value]) => {
+    if (tag === 'error') {
+        return error(isNotFound(value)
+            ? `revision not found: ${hash}`
+            : `failed to read revision: ${hash}`);
+    }
+    const revision = decodeRevisionVec(value);
+    return revision === null
+        ? error(`not a revision blob: ${hash}`)
+        : ok(toRevisionData(revision));
+};
+/**
+ * Reads the revision at `hash`: decoded, validated, and canonicalized
+ * ({@link toRevisionData}). The typed counterpart of a raw `cas.read` — the
+ * store's generic "bytes by hash" read stays available for arbitrary content
+ * (snapshots and everything else that is not a revision), while this is the
+ * view for revisions specifically: `add` validates on the way in, this
+ * validates on the way out, so no caller re-implements JSON parsing, schema
+ * validation, the `dialect` check, or hash canonicalization.
+ *
+ * Every way to fail is its own message: `hash` is not cBase32, the store has
+ * nothing under it, the store has it but could not deliver it, or what it
+ * holds is not a `vnd.fjs.revision` (see {@link decodeReadRevision}).
+ */
+export const readRevision = (cas) => (hash) => {
+    const hashVec = cBase32ToVec(hash);
+    return hashVec === null
+        ? pure(error(`invalid hash: ${hash}`))
+        : eff(collectRead(cas.read(hashVec)))
+            .map(decodeReadRevision(hash))
+            .value;
+};
 /** Builds the {@link Evo} API over `cas`, backed by the cache at `cacheKey` (see {@link initEvo}). */
 export const evo = (cas) => (cacheKey) => ({
-    list: () => read(cacheKey).step(cache => pure(definedEntries(cache.bySubject).map(([subject]) => subject))),
-    head: subject => read(cacheKey).step(cache => {
+    list: () => eff(read(cacheKey))
+        .step(cache => pure(definedEntries(cache.bySubject).map(([subject]) => subject)))
+        .value,
+    head: subject => eff(read(cacheKey))
+        .step(cache => {
         const state = at(subject)(cache.bySubject);
         return pure(state === null ? [] : headsOf(state));
-    }),
+    })
+        .value,
     add: input => addRevision(cas)(cacheKey)(input),
+    revision: readRevision(cas),
 });

package/fjs/cas/evo/proof.f.d.ts

@@ -14,6 +14,7 @@ export declare const proof: {
     addRevisionResolvesSubjectFromSingleParent: () => void;
     addComputesGenerationAndResolvesSnapshot: () => void;
     addComputesMergeGenerationFromMaxOfParents: () => void;
+    addIgnoresSuppliedGeneration: () => void;
     addRevisionSubjectRequiredForZeroParents: () => void;
     addRevisionNonHashSubjectWithoutSnapshotIsError: () => void;
     addRevisionInvalidParentHashIsError: () => void;
@@ -24,6 +25,12 @@ export declare const proof: {
     addRevisionInvalidReferencesIsError: () => void;
     addRevisionTooLargeToEncodeIsError: () => void;
     addRevisionWriteFailureIsError: () => void;
+    revisionInvalidHashIsError: () => void;
+    revisionMissingHashIsError: () => void;
+    revisionReadFailureIsNotReportedAsMissing: () => void;
+    revisionNonRevisionBlobIsError: () => void;
+    revisionCanonicalizesReferenceSpellings: () => void;
+    revisionRoundTripsThroughAdd: () => void;
     syncRevisionFoldsValidRevisionIntoCache: () => void;
     syncRevisionIgnoresNonRevisionContent: () => void;
     evoHeadUnknownSubjectIsEmpty: () => void;

package/fjs/cas/evo/proof.f.js

@@ -19,6 +19,14 @@ const writeFailingCas = {
     write: () => pure(error('boom')),
     list: () => pure([]),
 };
+// A `Cas<never>` whose `read` yields an error item that is *not* a missing
+// shard — what a permission error, a mid-stream I/O failure, or a blob too
+// large for `collectRead` to buffer looks like to a caller.
+const readFailingCas = {
+    read: () => nonEmpty(error('boom'), elEmpty()),
+    write: () => pure(error('write not supported')),
+    list: () => pure([]),
+};
 // A `Cas<never>` backed by a fixed set of (hash, content) entries, returned
 // from `list()` in exactly the given order — used to control the order
 // `buildCache` sees hashes in, independent of any real filesystem's
@@ -282,6 +290,24 @@ export const proof = {
         assert(mergeRev !== null, 'expected the stored merge to decode');
         assertEq(mergeRev?.generation, 3);
     },
+    // `generation` is an input field only so a value read back by
+    // `revision` round-trips into `add` unchanged: `add` never reads it, and
+    // supplying a wrong one must not reach the stored blob — the revision is
+    // byte-identical to the same `add` without it.
+    addIgnoresSuppliedGeneration: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const subjectHash = vecToCBase32(vec8(0x73n));
+        const [state1, claimed] = virtual(state0)(e.add({ parents: [], subject: subjectHash, generation: 42 }));
+        assert(claimed[0] === 'ok', ['expected add ok', claimed]);
+        const [state2, plain] = virtual(state1)(e.add({ parents: [], subject: subjectHash }));
+        assert(plain[0] === 'ok', ['expected add ok', plain]);
+        assertEq(claimed[1], plain[1]);
+        const [, revision] = virtual(state2)(e.revision(claimed[1]));
+        assert(revision[0] === 'ok', ['expected revision ok', revision]);
+        assertEq(revision[1].generation, 0);
+    },
     addRevisionSubjectRequiredForZeroParents: () => {
         const c = fileCas(sha256)(home);
         const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
@@ -396,6 +422,99 @@ export const proof = {
         assertEq(result[0], 'error');
         assert(result[0] === 'error' && result[1] === 'failed to write revision to CAS', ['unexpected message', result]);
     },
+    // Every way `revision` can fail is its own message, not one `null`: an
+    // undecodable hash, a hash the store has nothing under, a read that failed
+    // for any other reason, and a blob that is not a revision.
+    // `decodeRevisionBlob` collapses all but the first (it exists to scan
+    // stores of arbitrary content); this read keeps them apart.
+    revisionInvalidHashIsError: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const [, result] = virtual(state0)(e.revision('not a valid cbase32!'));
+        assertEq(result[0], 'error');
+        assert(result[0] === 'error' && result[1].includes('invalid hash'), ['unexpected message', result]);
+    },
+    revisionMissingHashIsError: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const [, result] = virtual(state0)(e.revision(vecToCBase32(vec8(0x9an))));
+        assertEq(result[0], 'error');
+        assert(result[0] === 'error' && result[1].includes('revision not found'), ['unexpected message', result]);
+    },
+    // Regression: a read failure that is not a missing shard — a permission or
+    // mid-stream I/O error, or a blob too large to buffer into one `Vec` —
+    // must not be reported as "not found". The blob may well be there; saying
+    // it is absent would be a false answer, not merely a vague one.
+    revisionReadFailureIsNotReportedAsMissing: () => {
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(readFailingCas));
+        const e = evo(readFailingCas)(cacheKey);
+        const [, result] = virtual(state0)(e.revision(vecToCBase32(vec8(0x9bn))));
+        assertEq(result[0], 'error');
+        assert(result[0] === 'error' && result[1].includes('failed to read revision'), ['unexpected message', result]);
+    },
+    revisionNonRevisionBlobIsError: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const content = vec8(0x41n); // 'A' — valid UTF-8, not revision JSON
+        const [state1, w] = virtual(state0)(c.write(nonEmpty(ok(content), elEmpty())));
+        assert(w[0] === 'ok', ['expected write ok', w]);
+        const [, result] = virtual(state1)(e.revision(vecToCBase32(w[1])));
+        assertEq(result[0], 'error');
+        assert(result[0] === 'error' && result[1].includes('not a revision blob'), ['unexpected message', result]);
+    },
+    // A blob written by somebody else can spell its references in any accepted
+    // cbase32 alias (case, `i`/`l`/`o`). What `revision` returns is
+    // canonicalized, so a client can compare it against `head` output
+    // directly instead of knowing about cbase32 aliasing.
+    revisionCanonicalizesReferenceSpellings: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const parentCanonical = vecToCBase32(vec8(0xffn));
+        const snapshotCanonical = vecToCBase32(vec8(0xfen));
+        const parentAlias = parentCanonical.toUpperCase();
+        const snapshotAlias = snapshotCanonical.toUpperCase();
+        assert(parentAlias !== parentCanonical && snapshotAlias !== snapshotCanonical, 'expected the sample hashes to contain letters');
+        const text = `{"dialect":"${revisionDialect}","subject":"doc","parents":["${parentAlias}"],"snapshot":"${snapshotAlias}","generation":1}`;
+        const bytes = tryUtf8(text);
+        assert(bytes !== null, 'expected the sample revision text to encode as UTF-8');
+        const [state1, w] = virtual(state0)(c.write(nonEmpty(ok(bytes), elEmpty())));
+        assert(w[0] === 'ok', ['expected write ok', w]);
+        const [, result] = virtual(state1)(e.revision(vecToCBase32(w[1])));
+        assert(result[0] === 'ok', ['expected revision ok', result]);
+        assertEq(result[1].parents.length, 1);
+        assertEq(result[1].parents[0], parentCanonical);
+        assertEq(result[1].snapshot, snapshotCanonical);
+        assertEq(result[1].subject, 'doc');
+        assertEq(result[1].archived, undefined);
+    },
+    // What you add is what you get back: every field of a stored revision
+    // comes back in the same `RevisionData` shape `add` takes, so the value
+    // can be added again unchanged — same content, same hash.
+    revisionRoundTripsThroughAdd: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const subjectHash = vecToCBase32(vec8(0x74n));
+        const [state1, root] = virtual(state0)(e.add({ parents: [], subject: subjectHash }));
+        assert(root[0] === 'ok', ['expected root ok', root]);
+        const [state2, child] = virtual(state1)(e.add({ parents: [root[1]], archived: true }));
+        assert(child[0] === 'ok', ['expected child ok', child]);
+        const [state3, result] = virtual(state2)(e.revision(child[1]));
+        assert(result[0] === 'ok', ['expected revision ok', result]);
+        assertEq(result[1].subject, subjectHash);
+        assertEq(result[1].snapshot, subjectHash);
+        assertEq(result[1].generation, 1);
+        assertEq(result[1].archived, true);
+        assertEq(result[1].parents.length, 1);
+        assertEq(result[1].parents[0], root[1]);
+        const [, readded] = virtual(state3)(e.add(result[1]));
+        assert(readded[0] === 'ok', ['expected re-add ok', readded]);
+        assertEq(readded[1], child[1]);
+    },
     // A raw CAS write (e.g. `cas_add`) of valid revision content is folded
     // into the cache exactly as `addRevision` would, without going through
     // `evo.add` — this is what keeps `cas_add` and `evo_add` writes to the

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

@@ -7,20 +7,22 @@
  * what is stored — without shelling out to the `cas` CLI. The store itself
  * (`fjs/cas/module.f.ts`) stays transport-agnostic; this is an additional
  * front end alongside the CLI `main`. The same server also exposes
- * `fjs/cas/evo`'s subject/head API (`evo_list`/`evo_head`/`evo_add`,
- * `fjs/cas/evo/mcp`) — one process, one `~/.cas/` store, one in-memory Evo
- * cache scanned once at startup (`initEvo`).
+ * `fjs/cas/evo`'s subject/head API
+ * (`evo_list`/`evo_head`/`evo_revision`/`evo_add`, `fjs/cas/evo/mcp`) — one
+ * process, one `~/.cas/` store, one in-memory Evo cache scanned once at
+ * startup (`initEvo`).
  *
  * ## Tools
  *
- * | Tool        | args                                           | action        | result                              |
- * |-------------|-------------------------------------------------|---------------|--------------------------------------|
- * | `cas_add`   | `{ content, type? }`                            | `c.write(...)`| hash (cBase32)                      |
- * | `cas_get`   | `{ hash, content?: boolean }`                    | `c.read(key)` | JSON `{length,mimeType,type[,uri][,text\|blob]}` |
- * | `cas_list`  | `{}`                                             | `c.list()`    | hashes, one per line                |
- * | `evo_list`  | `{}`                                             | `e.list()`    | subjects, one per line              |
- * | `evo_head`  | `{ subject }`                                    | `e.head(...)` | head hashes, one per line           |
- * | `evo_add`   | `{ parents, snapshot?, subject?, archived? }`    | `e.add(...)`  | hash (cBase32)                      |
+ * | Tool           | args                                         | action           | result                              |
+ * |----------------|----------------------------------------------|------------------|--------------------------------------|
+ * | `cas_add`      | `{ content, type? }`                         | `c.write(...)`   | hash (cBase32)                      |
+ * | `cas_get`      | `{ hash, content?: boolean }`                | `c.read(key)`    | JSON `{length,mimeType,type[,uri][,text\|blob]}` |
+ * | `cas_list`     | `{}`                                         | `c.list()`       | hashes, one per line                |
+ * | `evo_list`     | `{}`                                         | `e.list()`       | subjects, one per line              |
+ * | `evo_head`     | `{ subject }`                                | `e.head(...)`    | head hashes, one per line           |
+ * | `evo_revision` | `{ hash }`                                   | `e.revision(...)`| the revision, as JSON               |
+ * | `evo_add`      | `{ parents, snapshot?, subject?, archived? }` | `e.add(...)`     | hash (cBase32)                      |
  *
  * ## `cas_add` input encoding
  *
@@ -108,7 +110,7 @@
  */
 import { string, option, or, boolean } from '../../types/rtti/module.f.js';
 import { stringify } from '../../media/json/module.f.js';
-import { pure } from '../../effects/module.f.js';
+import { pure, step } from '../../effects/module.f.js';
 import { create } from '../../effects/memory/module.f.js';
 import { cBase32ToVec, vecToCBase32 } from '../../basen/cbase32/module.f.js';
 import { decode as base64Decode, encode as base64Encode } from '../../basen/base64/module.f.js';
@@ -116,7 +118,7 @@ import { tryUtf8 } from '../../text/module.f.js';
 import { detectStream } from '../../media/type/module.f.js';
 import { detect as detectDialect } from '../../media/module.f.js';
 import { maxLengthBytes } from '../../types/bit_vec/module.f.js';
-import { ok, error } from '../../types/result/module.f.js';
+import { ok } from '../../types/result/module.f.js';
 import {} from '../../effects/node/module.f.js';
 import { stdioTransport } from '../../mcp/stdio/module.f.js';
 import { mcpStep, uninitializedState, toolEntry, fromRegistry, errorResult, okResult, } from '../../mcp/module.f.js';
@@ -162,12 +164,12 @@ export const casToolRegistry = (home) => (cacheKey) => {
             return x === null
                 ? pure(errorResult('too large or malformed — for large content, run `npx functionalscript cas add <path>` (or have the user run it) instead'))
                 // The resolved content fits in one chunk; feed it as a single-item stream.
-                : c.write(nonEmpty(ok(x), elEmpty())).step((writeResult) => {
+                : step(c.write(nonEmpty(ok(x), elEmpty())), (writeResult) => {
                     if (writeResult[0] === 'error') {
                         return pure(errorResult('write'));
                     }
                     const hash = writeResult[1];
-                    return syncRevision(cacheKey)(hash)(x).step(() => pure(okResult(vecToCBase32(hash))));
+                    return step(syncRevision(cacheKey)(hash)(x), () => pure(okResult(vecToCBase32(hash))));
                 });
         }),
         toolEntry('cas_get', 'Inspect a blob by hash. Always returns JSON {length,mimeType,type[,uri]} where type is "text" or "base64". Pass content:true to also include the inline payload as text (type:"text") or blob (type:"base64"), but content is capped at 128 KiB (131072 bytes) — a larger blob is rejected with an error. To download a blob, prefer the uri field returned in the result instead of requesting inline content.', casGetArgs, r => {
@@ -176,7 +178,7 @@ export const casToolRegistry = (home) => (cacheKey) => {
                 return pure(errorResult(`invalid cBase32 hash: ${r.hash}`));
             }
             const uri = c.url(key);
-            return detectStream(c.read(key)).step(([tag, detected]) => {
+            return step(detectStream(c.read(key)), ([tag, detected]) => {
                 if (tag === 'error') {
                     return pure(errorResult(`no such hash: ${r.hash}`));
                 }
@@ -189,7 +191,7 @@ export const casToolRegistry = (home) => (cacheKey) => {
                     if (type !== 'text' || length > maxLengthBytes) {
                         return pure(okResult(toJson(meta)));
                     }
-                    return collectRead(c.read(key)).step(([collectTag, value]) => {
+                    return step(collectRead(c.read(key)), ([collectTag, value]) => {
                         // Already known to fit from the streaming pass above, so an
                         // error here means the hash vanished between reads; fall back
                         // to the streaming verdict rather than fail the whole request.
@@ -207,7 +209,7 @@ export const casToolRegistry = (home) => (cacheKey) => {
                 if (length > maxLengthBytes) {
                     return pure(errorResult(`blob too large to fetch inline (${length} bytes, limit ${maxLengthBytes} bytes); use the uri field (${uri}) or omit content for metadata`));
                 }
-                return collectRead(c.read(key)).step(([collectTag, value]) => {
+                return step(collectRead(c.read(key)), ([collectTag, value]) => {
                     if (collectTag === 'error') {
                         return pure(errorResult(`no such hash: ${r.hash}`));
                     }
@@ -232,7 +234,7 @@ export const casToolRegistry = (home) => (cacheKey) => {
                 });
             });
         }),
-        toolEntry('cas_list', 'List all stored content hashes (cBase32), one per line.', casListArgs, () => c.list().step(hashes => pure(okResult(hashes.map(vecToCBase32).join('\n'))))),
+        toolEntry('cas_list', 'List all stored content hashes (cBase32), one per line.', casListArgs, () => step(c.list(), hashes => pure(okResult(hashes.map(vecToCBase32).join('\n'))))),
     ];
 };
 // ── Handlers ────────────────────────────────────────────────────────────────────
@@ -258,7 +260,7 @@ export const casConfig = {
  * slot, builds the `mcpStep` for the merged tool registry, and drives the
  * read → parse → dispatch → write loop until stdin EOF.
  */
-export const casMcpServer = (home) => initEvo(fileCas(sha256)(home)).step(cacheKey => create(uninitializedState).step(sessionKey => stdioTransport(mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey))));
+export const casMcpServer = (home) => step(initEvo(fileCas(sha256)(home)), cacheKey => step(create(uninitializedState), sessionKey => stdioTransport(mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey))));
 // ── Tests ────────────────────────────────────────────────────────────────────
 export const proof = {
     // casMcpServer is never called in integration tests because it drives a

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

@@ -7,7 +7,7 @@ export declare const proof: {
     getContentBase64InflationOverflowWritesInternalError: () => void;
     getContentBase64NearBoundarySucceeds: () => void;
     getContentDoubleEscapedOverflowWritesInternalError: () => void;
-    toolsListAdvertisesSixTools: () => void;
+    toolsListAdvertisesSevenTools: () => void;
     evoAddListHeadRoundTripsThroughCasServer: () => void;
     evoAddDomainErrorIsErrorThroughCasServer: () => void;
     casAddSyncsEvoCacheForRevisionContent: () => void;

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

@@ -1,5 +1,5 @@
 import { assert, assertEq } from '../../asserts/module.f.js';
-import { pure } from '../../effects/module.f.js';
+import { pure, step } from '../../effects/module.f.js';
 import { run } from '../../effects/mock/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';
@@ -46,18 +46,18 @@ const mock = {
 };
 const runMem = (effect) => run(mock)(initialTestState)(effect)[1];
 // ── Session driver ──────────────────────────────────────────────────────────────
-// Feeds each message to `step` in order, collecting every response.
-const feed = (step) => (msgs) => {
+// Feeds each message to `handler` in order, collecting every response.
+const feed = (handler) => (msgs) => {
     const go = (i, acc) => i === msgs.length
         ? pure(acc)
-        : step(msgs[i]).step(r => go(i + 1, [...acc, r]));
+        : step(handler(msgs[i]), r => go(i + 1, [...acc, r]));
     return go(0, []);
 };
 // 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 = initEvo(fileCas(sha256)(home)).step(cacheKey => create(uninitializedState).step(sessionKey => {
+    const effect = step(initEvo(fileCas(sha256)(home)), cacheKey => step(create(uninitializedState), sessionKey => {
         const step = mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey);
         return feed(step)(msgs);
     }));
@@ -95,7 +95,7 @@ const toBytes = (s) => [...fromVec(utf8(s))];
 // `fjs/mcp/stdio/module.f.ts` `writeResponse`).
 const runStdio = (root, home = '/home/user') => (msgs) => {
     const input = [init, initialized, ...msgs].map(m => JSON.stringify(m)).join('\n') + '\n';
-    const effect = initEvo(fileCas(sha256)(home)).step(cacheKey => create(uninitializedState).step(sessionKey => stdioTransport(mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey))));
+    const effect = step(initEvo(fileCas(sha256)(home)), cacheKey => step(create(uninitializedState), sessionKey => stdioTransport(mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey))));
     const stdout = virtual({ ...emptyState, root, stdin: toBytes(input) })(effect)[0].stdout;
     // Only requests get a written line (notifications, like `initialized`,
     // write nothing) — drop the `init` response, keep one line per `msgs` entry.
@@ -257,11 +257,11 @@ export const proof = {
         assertEq(err.error?.code, -32603);
         assertEq(err.id, 2);
     },
-    toolsListAdvertisesSixTools: () => {
+    toolsListAdvertisesSevenTools: () => {
         const [resp] = runSessionVirtual({})([init, initialized, list(2)]).slice(2);
         const tools = resp.result.tools;
-        assertEq(tools.length, 6);
-        assertEq(tools.map(t => t.name).join(','), 'cas_add,cas_get,cas_list,evo_list,evo_head,evo_add');
+        assertEq(tools.length, 7);
+        assertEq(tools.map(t => t.name).join(','), 'cas_add,cas_get,cas_list,evo_list,evo_head,evo_revision,evo_add');
         const add = resp.result.tools[0];
         assertEq(add.inputSchema.type, 'object');
     },