functionalscript 0.38.0 → 0.40.0

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

@@ -30,6 +30,13 @@
  * 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 { type Effect, type Operation } from '../../effects/module.f.ts';
@@ -44,21 +51,50 @@ export type Hash = string;
 /** The identity of a mutable object whose revisions are being evolved. */
 export type Subject = string;
 /**
- * Input to {@link addRevision}: everything the caller supplies for a new
- * revision. Both `subject` and `snapshot` are input conveniences the write
- * boundary resolves, because the stored `vnd.fjs.revision` blob requires
- * them explicitly (see `fjs/media/revision`): `subject`, when omitted, is
- * inherited from the single parent's own `subject` (see
- * {@link resolveSubject}); `snapshot`, when omitted, is resolved from the
- * parents (see {@link resolveSnapshot}) — the inference the format used to
- * carry, run once here with the parents already in hand. `generation` is
- * never an input: {@link computeGeneration} derives the authoritative value.
+ * The semantic content of a revision: the media-level `Revision`
+ * (`fjs/media/revision`) minus `dialect`, which is a serialization tag
+ * carrying no information once decoding has validated it. One structure is
+ * the vocabulary of both directions — {@link addRevision} takes it,
+ * {@link readRevision} returns it — so what you add is what you get back, and
+ * a value read back can be fed to `add` unchanged, without stripping fields.
+ * Every direction-specific field is therefore optional, with the guarantees
+ * documented per field rather than typed:
+ *
+ * - `parents` — required in both directions; index 0 is the mainline parent.
+ *   On output the entries are canonical cBase32 spellings
+ *   ({@link canonicalHash}), so they compare directly against {@link Evo.head}
+ *   output.
+ * - `subject` — input: absent means "inherit from my single parent" (see
+ *   {@link resolveSubject}); output: always present.
+ * - `snapshot` — input: absent is a write-boundary convenience resolved from
+ *   the parents (see {@link resolveSnapshot}), because the stored blob
+ *   requires it explicitly; output: always present, canonical, and exactly
+ *   what the stored blob names.
+ * - `archived` — genuinely optional in both directions; the only field that
+ *   can be absent from a read.
+ * - `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.
+ *
+ * Relaxing what the format requires is the point, not an oversight. The stored
+ * `vnd.fjs.revision` blob requires `subject`, `snapshot` and `generation`, and
+ * {@link readRevision} does return all three — but this is not that blob's
+ * type. It is the type of the API that *reads and constructs* revisions, and
+ * its purpose is to make both easy: `add` asks only for what a caller can
+ * actually know, resolving or computing the rest at the write boundary, and a
+ * read hands back a value that goes straight into `add` again. A separate
+ * output type with `subject`/`snapshot`/`generation` required would state that
+ * one direction more precisely, at the cost of splitting the one vocabulary
+ * into two — the trade this API declines, deliberately and not by omission.
+ * `fjs/media/revision`'s `Revision` remains the all-required type of the
+ * stored blob for anyone who wants it.
  */
-export type AddRevision = {
+export type RevisionData = {
     readonly parents: readonly Hash[];
     readonly snapshot?: Hash | undefined;
     readonly subject?: Subject | undefined;
     readonly archived?: true | undefined;
+    readonly generation?: number | undefined;
 };
 /**
  * Per-subject bookkeeping: every revision hash seen for the subject, and
@@ -101,7 +137,7 @@ export declare const initEvo: <O extends Operation>(cas: Cas<O>) => Effect<O | M
  * 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`
  * ({@link decodeRevisionVec}); a no-op otherwise. `cas_add`/`evo_add`
- * (`fjs/cas/mcp`) are two ways to reach the same store — a plain `cas_add`
+ * (`fjs/mcp`) are two ways to reach the same store — a plain `cas_add`
  * call can store a revision blob without going through {@link addRevision},
  * and this is what keeps the cache honest about it without rescanning the
  * whole store.
@@ -123,8 +159,27 @@ export declare const syncRevision: (cacheKey: Key<Cache>) => (hash: Vec) => (val
  * 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 declare const addRevision: <O extends Operation>(cas: Cas<O>) => (cacheKey: Key<Cache>) => (input: RevisionData) => Effect<O | MemOp, Result<Hash, string>>;
+/**
+ * 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 declare const addRevision: <O extends Operation>(cas: Cas<O>) => (cacheKey: Key<Cache>) => (input: AddRevision) => Effect<O | MemOp, Result<Hash, string>>;
+export declare const readRevision: <O extends Operation>(cas: Cas<O>) => (hash: Hash) => Effect<O, Result<RevisionData, string>>;
 /** The Evo API described in `fjs/cas/evo/README.md`, bound to a `Cas<O>` and its cache slot. */
 export type Evo<O extends Operation> = {
     /** Returns every subject with at least one stored revision. */
@@ -132,7 +187,16 @@ export type Evo<O extends Operation> = {
     /** 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: AddRevision) => Effect<O | MemOp, Result<Hash, string>>;
+    readonly add: (input: RevisionData) => Effect<O | MemOp, Result<Hash, string>>;
+    /**
+     * The revision at `hash`, decoded, validated, and canonicalized; see
+     * {@link readRevision}. Served from the store today, so the `MemOp` in the
+     * declared operation set is unused — it is there because a revision is
+     * immutable and therefore memoizable in the same cache slot the other
+     * 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>>;
 };
 /** Builds the {@link Evo} API over `cas`, backed by the cache at `cacheKey` (see {@link initEvo}). */
 export declare const evo: <O extends Operation>(cas: Cas<O>) => (cacheKey: Key<Cache>) => Evo<O>;

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,21 +119,29 @@ 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`
  * ({@link decodeRevisionVec}); a no-op otherwise. `cas_add`/`evo_add`
- * (`fjs/cas/mcp`) are two ways to reach the same store — a plain `cas_add`
+ * (`fjs/mcp`) are two ways to reach the same store — a plain `cas_add`
  * call can store a revision blob without going through {@link addRevision},
  * and this is what keeps the cache honest about it without rescanning the
  * whole store.
@@ -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,10 +422,103 @@ 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
-    // same store consistent (see `fjs/cas/mcp`).
+    // same store consistent (see `fjs/mcp`).
     syncRevisionFoldsValidRevisionIntoCache: () => {
         const c = fileCas(sha256)(home);
         const [state0, cacheKey] = virtual(emptyState)(initEvo(c));