functionalscript 0.38.0 → 0.39.0

package/fjs/bnf/token_symbol/module.f.d.ts

@@ -0,0 +1,38 @@
+import { type Nullable } from '../../types/nullable/module.f.ts';
+/**
+ * How many names one encoding holds: every symbol from {@link start} up to but
+ * not including `eof` (`0xFFFFFF`, the top of the 24-bit symbol space).
+ */
+export declare const capacity: number;
+/**
+ * A bidirectional map between a fixed alphabet of token names and the symbol
+ * range reserved for them.
+ */
+export type Encoding<T extends string> = {
+    /**
+     * The input symbol standing for `name`.
+     *
+     * The result is a bare symbol, the form a tokenizer emits. Wrap it in
+     * `oneEncode` to use it as a terminal of a grammar rule — a symbol and a
+     * `TerminalRange` are both plain numbers, so passing one where the other
+     * belongs is not a type error.
+     */
+    readonly encode: (name: T) => number;
+    /**
+     * The name a symbol stands for, or `null` when the symbol belongs to no
+     * registered name — a code point, `eof`, or a symbol past the end of the
+     * alphabet.
+     */
+    readonly decode: (symbol: number) => Nullable<T>;
+};
+/**
+ * Builds an encoding over the complete list of token names.
+ *
+ * A name takes the symbol at its index in `names`, so the list is append-only:
+ * inserting or reordering names changes the symbols of everything after the
+ * edit.
+ *
+ * @throws When `names` holds more than {@link capacity} entries, or when a name
+ * repeats — a repeated name has no single symbol to decode back to.
+ */
+export declare const encoding: <T extends string>(names: readonly T[]) => Encoding<T>;

package/fjs/bnf/token_symbol/module.f.js

@@ -0,0 +1,48 @@
+/**
+ * Encoding of multi-character token names as single BNF input symbols.
+ *
+ * A parser built on top of a tokenizer consumes one input symbol per token, so
+ * multi-character operators (`>>>=`) and keywords (`instanceof`) each need a
+ * symbol of their own. Names are registered as one fixed alphabet and get a
+ * symbol from their position in it, above the Unicode range and below `eof`.
+ *
+ * @module
+ */
+import { assert } from '../../asserts/module.f.js';
+import { fromUndefined } from '../../types/nullable/module.f.js';
+import { eof, rangeDecode, unicodeRange } from '../module.f.js';
+const [, unicodeLast] = rangeDecode(unicodeRange);
+const [eofSymbol] = rangeDecode(eof);
+/**
+ * The symbol of the first registered name: `0x110000`, one past the last
+ * Unicode scalar value, so a token symbol can never be mistaken for a code
+ * point of the layer below.
+ */
+const start = unicodeLast + 1;
+/**
+ * How many names one encoding holds: every symbol from {@link start} up to but
+ * not including `eof` (`0xFFFFFF`, the top of the 24-bit symbol space).
+ */
+export const capacity = eofSymbol - start;
+/**
+ * Builds an encoding over the complete list of token names.
+ *
+ * A name takes the symbol at its index in `names`, so the list is append-only:
+ * inserting or reordering names changes the symbols of everything after the
+ * edit.
+ *
+ * @throws When `names` holds more than {@link capacity} entries, or when a name
+ * repeats — a repeated name has no single symbol to decode back to.
+ */
+export const encoding = (names) => {
+    assert(names.length <= capacity, ['too many token names', names.length]);
+    assert(new Set(names).size === names.length, ['duplicate token name', names]);
+    return {
+        encode: name => {
+            const index = names.indexOf(name);
+            assert(index !== -1, ['unregistered token name', name]);
+            return start + index;
+        },
+        decode: symbol => fromUndefined(names[symbol - start]),
+    };
+};

package/fjs/bnf/token_symbol/proof.f.d.ts

@@ -0,0 +1,10 @@
+export declare const proof: {
+    encode: () => void;
+    decode: (() => void)[];
+    roundTrip: () => void;
+    throw: {
+        duplicateName: () => void;
+        unregisteredName: () => void;
+        tooManyNames: () => void;
+    };
+};

package/fjs/bnf/token_symbol/proof.f.js

@@ -0,0 +1,37 @@
+import { assertEq } from '../../asserts/module.f.js';
+import { capacity, encoding } from './module.f.js';
+const names = ['>>', '>>>=', 'instanceof'];
+export const proof = {
+    encode: () => {
+        const { encode } = encoding(names);
+        assertEq(encode('>>'), 0x110000);
+        assertEq(encode('instanceof'), 0x110002);
+    },
+    decode: [
+        () => {
+            const { decode } = encoding(names);
+            assertEq(decode(0x110000), '>>');
+            assertEq(decode(0x110002), 'instanceof');
+        },
+        () => {
+            const { decode } = encoding(names);
+            // past the end of the alphabet, a code point, and `eof`
+            assertEq(decode(0x110003), null);
+            assertEq(decode(0x10FFFF), null);
+            assertEq(decode(0xFFFFFF), null);
+        },
+    ],
+    roundTrip: () => {
+        const { encode, decode } = encoding(names);
+        for (const name of names) {
+            assertEq(decode(encode(name)), name);
+        }
+    },
+    throw: {
+        duplicateName: () => { encoding(['a', 'b', 'a']); },
+        unregisteredName: () => { encoding(['a']).encode('b'); },
+        // `capacity` names fit, so one more is the smallest list that doesn't.
+        // The array is sparse, so this costs a length, not the strings.
+        tooManyNames: () => { encoding(new Array(capacity + 1)); },
+    },
+};

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

@@ -5,7 +5,7 @@
  */
 import { sha256 } from '../../crypto/sha2/module.f.js';
 import { cBase32ToVec, vecToCBase32 } from '../../basen/cbase32/module.f.js';
-import { forEachStep, pure } from '../../effects/module.f.js';
+import { forEachStep, pure, step } from '../../effects/module.f.js';
 import { errorExit, log, writeFromStream } from '../../effects/node/module.f.js';
 import { dispatch } from '../../cli/module.f.js';
 import {} from '../../effects/memory/module.f.js';
@@ -19,10 +19,9 @@ export const commands = [
                 return errorExit("'cas add' expects one parameter");
             }
             const c = fileCas(sha256)(home);
-            return casAddFile(c)(path)
-                .step(hashResult => hashResult[0] === 'error'
+            return step(casAddFile(c)(path), hashResult => hashResult[0] === 'error'
                 ? pure(1)
-                : log(vecToCBase32(hashResult[1])).step(() => pure(0)));
+                : step(log(vecToCBase32(hashResult[1])), () => pure(0)));
         },
     },
     {
@@ -38,8 +37,7 @@ export const commands = [
             }
             const c = fileCas(sha256)(home);
             const x = c.read(hash);
-            return writeFromStream(path, x)
-                .step(([r, v]) => r === 'error' ? errorExit(`e: ` + String(v)) : pure(0));
+            return step(writeFromStream(path, x), ([r, v]) => r === 'error' ? errorExit(`e: ` + String(v)) : pure(0));
         },
     },
     {
@@ -47,9 +45,8 @@ export const commands = [
         description: 'List all stored content hashes',
         handler: ({ home }) => {
             const c = fileCas(sha256)(home);
-            return c.list()
-                .step(forEachStep(j => log(vecToCBase32(j))))
-                .step(() => pure(0));
+            const x0 = forEachStep(c.list(), j => log(vecToCBase32(j)));
+            return step(x0, () => pure(0));
         },
     },
 ];

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

@@ -8,7 +8,15 @@ export declare const evoListArgs: {};
 export declare const evoHeadArgs: {
     readonly subject: import("../../../types/rtti/module.f.ts").String;
 };
-/** Arguments for `evo_add`: a new revision, per `fjs/cas/evo`'s `AddRevision`. */
+/** Arguments for `evo_revision`: the hash of the revision to read. */
+export declare const evoRevisionArgs: {
+    readonly hash: import("../../../types/rtti/module.f.ts").String;
+};
+/**
+ * Arguments for `evo_add`: a new revision, per `fjs/cas/evo`'s
+ * `RevisionData` — every field of it the caller supplies, i.e. all but
+ * `generation`, which the server computes.
+ */
 export declare const evoAddArgs: {
     readonly parents: import("../../../types/rtti/module.f.ts").Type1<"array", import("../../../types/rtti/module.f.ts").String>;
     readonly snapshot: import("../../../types/rtti/module.f.ts").Or<readonly [import("../../../types/rtti/module.f.ts").String, undefined]>;

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

@@ -1,15 +1,39 @@
 /**
- * MCP tool definitions for the Evo API (`fjs/cas/evo/module.f.ts`): subjects
- * and revision heads over the content-addressable store, backed by the
- * in-memory cache the core module maintains.
+ * MCP tool definitions for the Evo API (`fjs/cas/evo/module.f.ts`): subjects,
+ * revision heads, and the typed read of a single revision over the
+ * content-addressable store, backed by the in-memory cache the core module
+ * maintains.
  *
  * ## Tools
  *
- * | Tool        | args                                     | action        | result                    |
- * |-------------|-------------------------------------------|---------------|---------------------------|
- * | `evo_list`  | `{}`                                       | `e.list()`    | subjects, as a JSON array of strings |
- * | `evo_head`  | `{ subject }`                              | `e.head(...)` | head hashes, one per line |
- * | `evo_add`   | `{ parents, snapshot?, subject?, archived? }` | `e.add(...)`  | hash (cBase32)            |
+ * | Tool           | args                                          | action            | result                               |
+ * |----------------|-----------------------------------------------|-------------------|--------------------------------------|
+ * | `evo_list`     | `{}`                                          | `e.list()`        | subjects, as a JSON array of strings |
+ * | `evo_head`     | `{ subject }`                                 | `e.head(...)`     | head hashes, one per line            |
+ * | `evo_revision` | `{ hash }`                                    | `e.revision(...)` | the revision, as JSON `RevisionData` |
+ * | `evo_add`      | `{ parents, snapshot?, subject?, archived? }`  | `e.add(...)`      | hash (cBase32)                       |
+ *
+ * `evo_add` and `evo_revision` speak the same structure — `fjs/cas/evo`'s
+ * `RevisionData` — in opposite directions, so a revision read back can be
+ * added again as-is. `evo_add`'s advertised arguments stay as they are: the
+ * one field `evo_revision` returns that `evo_add` does not accept is
+ * `generation`, which the server computes, and rtti's struct validation
+ * ignores properties the schema does not name, so a whole `evo_revision`
+ * result can be passed straight back to `evo_add`.
+ *
+ * ## Result size
+ *
+ * `evo_list` and `evo_revision` answer with JSON carried as MCP *text*
+ * content, so the JSON-RPC serializer escapes it a second time on the way
+ * out and a modest result can encode to a much longer line (a subject of
+ * quote characters is the worst case). A response whose encoded line exceeds
+ * the transport cap is not lost: `fjs/mcp/stdio` retries with a small
+ * `-32603` body carrying the request's `id`, so every request still gets a
+ * response and the process never crashes. That is the transport's contract
+ * for every tool — `cas_get` has proofs for the same double-escaping path —
+ * and no tool here can pre-empt it: whether the encoded response fits is
+ * known only by encoding it, which is the transport's job, and guessing from
+ * an unencoded size is exactly the size estimate that must never be made.
  *
  * These tools are not served by their own process: `fjs/cas/mcp` (the same
  * server as `cas_add`/`cas_get`/`cas_list`) builds one `Evo<O>` from its own
@@ -20,7 +44,7 @@
  * @module
  */
 import { string, option, array } from '../../../types/rtti/module.f.js';
-import { pure } from '../../../effects/module.f.js';
+import { pure, step } from '../../../effects/module.f.js';
 import {} from '../../../effects/memory/module.f.js';
 import { toolEntry, errorResult, okResult, } from '../../../mcp/module.f.js';
 import { stringify } from '../../../media/json/module.f.js';
@@ -33,7 +57,15 @@ export const evoListArgs = {};
 export const evoHeadArgs = {
     subject: string,
 };
-/** Arguments for `evo_add`: a new revision, per `fjs/cas/evo`'s `AddRevision`. */
+/** Arguments for `evo_revision`: the hash of the revision to read. */
+export const evoRevisionArgs = {
+    hash: string,
+};
+/**
+ * Arguments for `evo_add`: a new revision, per `fjs/cas/evo`'s
+ * `RevisionData` — every field of it the caller supplies, i.e. all but
+ * `generation`, which the server computes.
+ */
 export const evoAddArgs = {
     parents: array(string),
     snapshot: option(string),
@@ -41,7 +73,7 @@ export const evoAddArgs = {
     archived: option(true),
 };
 // ── Tool registry ────────────────────────────────────────────────────────────────
-/** Canonical JSON encoder for `evo_list`'s result. */
+/** Canonical JSON encoder for the `evo_list` and `evo_revision` results. */
 const toJson = stringify(identity);
 /** Registry of all Evo tools, bound to an `Evo<O>`. */
 export const evoToolRegistry = (e) => [
@@ -50,7 +82,13 @@ export const evoToolRegistry = (e) => [
     // constrained to a newline-free alphabet), so a `join('\n')` line
     // format could not represent an empty subject or one containing a
     // newline without ambiguity — JSON encoding can.
-    () => e.list().step(subjects => pure(okResult(toJson(subjects))))),
-    toolEntry('evo_head', 'List the current head hashes (cBase32) of a subject, one per line. Empty when the subject is unknown.', evoHeadArgs, ({ subject }) => e.head(subject).step(heads => pure(okResult(heads.join('\n'))))),
-    toolEntry('evo_add', 'Add a new revision (a `vnd.fjs.revision` blob) and return its hash (cBase32). `subject` is required unless there is exactly one parent, from which it is inherited. `snapshot`, when omitted, is resolved from the parents (zero parents → `subject`, one parent → the parent\'s snapshot; a merge requires an explicit `snapshot`) and written explicitly. `generation` is computed by the server.', evoAddArgs, (input) => e.add(input).step(result => pure(result[0] === 'error' ? errorResult(result[1]) : okResult(result[1])))),
+    () => step(e.list(), subjects => pure(okResult(toJson(subjects))))),
+    toolEntry('evo_head', 'List the current head hashes (cBase32) of a subject, one per line. Empty when the subject is unknown.', evoHeadArgs, ({ subject }) => step(e.head(subject), heads => pure(okResult(heads.join('\n'))))),
+    toolEntry('evo_revision', 'Read one revision by hash, as JSON: `{ subject, parents, snapshot, generation, archived? }`. `parents[0]` is the mainline parent and every further entry is a merged-in branch; `parents` and `snapshot` come back in their canonical cBase32 spelling, so they compare directly against `evo_head` output. Errors when the hash is not cBase32, is not present in the store, could not be read, or does not hold a `vnd.fjs.revision` blob — use `cas_get` for raw bytes of non-revision content.', evoRevisionArgs, 
+    // The revision goes out as JSON in a text content item, like
+    // `evo_list`'s. An encoded response that outgrows the transport cap is
+    // the transport's `-32603`, not a tool-level error — see "Result size"
+    // in the module doc.
+    ({ hash }) => step(e.revision(hash), result => pure(result[0] === 'error' ? errorResult(result[1]) : okResult(toJson(result[1]))))),
+    toolEntry('evo_add', 'Add a new revision (a `vnd.fjs.revision` blob) and return its hash (cBase32). `subject` is required unless there is exactly one parent, from which it is inherited. `snapshot`, when omitted, is resolved from the parents (zero parents → `subject`, one parent → the parent\'s snapshot; a merge requires an explicit `snapshot`) and written explicitly. `generation` is computed by the server.', evoAddArgs, (input) => step(e.add(input), result => pure(result[0] === 'error' ? errorResult(result[1]) : okResult(result[1])))),
 ];

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

@@ -4,6 +4,8 @@ export declare const proof: {
     evoListEncodesArbitrarySubjectsAsJson: () => void;
     evoHeadReflectsTheCache: () => void;
     evoHeadMissingSubjectIsInvalidArguments: () => void;
+    evoRevisionReturnsRevisionJson: () => void;
+    evoRevisionDomainErrorIsError: () => void;
     evoAddSuccessReturnsHash: () => void;
     evoAddDomainErrorIsError: () => void;
 };

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

@@ -19,8 +19,13 @@ const textOf = (result) => {
 };
 export const proof = {
     toolNamesMatchTheDesign: () => {
-        const e = { list: () => { throw 'unused'; }, head: () => { throw 'unused'; }, add: () => { throw 'unused'; } };
-        assertEq(evoToolRegistry(e).map(entry => entry.name).join(','), 'evo_list,evo_head,evo_add');
+        const e = {
+            list: () => { throw 'unused'; },
+            head: () => { throw 'unused'; },
+            add: () => { throw 'unused'; },
+            revision: () => { throw 'unused'; },
+        };
+        assertEq(evoToolRegistry(e).map(entry => entry.name).join(','), 'evo_list,evo_head,evo_revision,evo_add');
     },
     evoListReflectsTheCache: () => {
         const c = fileCas(sha256)(home);
@@ -69,6 +74,32 @@ export const proof = {
         const [, result] = virtual(state0)(entry.handle({}));
         assertEq(result.isError, true);
     },
+    // Covers evo_revision's success branch: the stored revision comes back as
+    // the JSON of `RevisionData` — `dialect` dropped, `generation` and the
+    // resolved `snapshot` included.
+    evoRevisionReturnsRevisionJson: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const subject = vecToCBase32(vec8(0x3n));
+        const [state1, added] = virtual(state0)(e.add({ parents: [], subject }));
+        assert(added[0] === 'ok', ['expected add ok', added]);
+        const entry = findEntry(evoToolRegistry(e), 'evo_revision');
+        const [, result] = virtual(state1)(entry.handle({ hash: added[1] }));
+        assert(!result.isError);
+        assertEq(textOf(result), `{"subject":"${subject}","parents":[],"snapshot":"${subject}","generation":0}`);
+    },
+    // Covers evo_revision's error branch: a domain-level failure (a hash the
+    // store has nothing under) is surfaced as isError with the message.
+    evoRevisionDomainErrorIsError: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const entry = findEntry(evoToolRegistry(e), 'evo_revision');
+        const [, result] = virtual(state0)(entry.handle({ hash: vecToCBase32(vec8(0x4n)) }));
+        assertEq(result.isError, true);
+        assert(textOf(result).includes('revision not found'));
+    },
     // Covers evo_add's success branch: a valid revision is stored and its
     // hash comes back as plain, non-error text.
     evoAddSuccessReturnsHash: () => {

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
@@ -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>;