functionalscript 0.37.0 → 0.38.0

package/{fs → fjs}/bnf/module.f.js

@@ -10,6 +10,8 @@ import { codePointListToString, stringToCodePointList } from '../text/utf16/modu
 import { definedValues } from '../types/object/module.f.js';
 import { isArray2 } from '../types/array/module.f.js';
 import { map, toArray, repeat as listRepeat } from '../types/list/module.f.js';
+import { contains } from '../types/range/module.f.js';
+import { assert } from '../asserts/module.f.js';
 /**
  * Full 24-bit symbol range packed into a single {@link TerminalRange}.
  */
@@ -18,10 +20,6 @@ export const fullRange = 0x000000_FFFFFF;
  * Unicode scalar value range packed into a single {@link TerminalRange}.
  */
 export const unicodeRange = 0x000000_10FFFF;
-/**
- * Maximal non-Unicode symbol encoded as a string value.
- */
-export const max = codePointListToString([0xFFFFFF]);
 /**
  * Maximal Unicode code point encoded as a string value.
  */
@@ -34,11 +32,9 @@ const { fromCodePoint } = String;
  */
 const offset = 24;
 const mask = (1 << offset) - 1;
-const isValid = (r) => r >= 0 && r <= mask;
+const isValid = contains(0, mask);
 export const rangeEncode = (a, b) => {
-    if (!isValid(a) || !isValid(b) || a > b) {
-        throw `Invalid range ${a} ${b}.`;
-    }
+    assert(isValid(a) && isValid(b) && a <= b);
     return Number((BigInt(a) << BigInt(offset)) | BigInt(b));
 };
 /**
@@ -46,13 +42,16 @@ export const rangeEncode = (a, b) => {
  */
 export const oneEncode = (a) => rangeEncode(a, a);
 /**
- * End-of-file marker represented as one code point beyond Unicode range.
+ * End-of-file marker: `mask`, the single largest value the 24-bit symbol
+ * space can hold (the top of `fullRange`). Deliberately outside Unicode
+ * (`unicodeRange` tops out at `0x10FFFF`) so it can never collide with a
+ * real code point.
  */
-export const eof = oneEncode(0x110000);
+export const eof = oneEncode(mask);
 /**
  * Decodes a packed range into `[start, end]` symbols.
  */
-export const rangeDecode = (r) => [Number(BigInt(r) >> BigInt(offset)), Number(BigInt(r) & BigInt(mask))];
+export const rangeDecode = (r) => [Number(BigInt(r) >> BigInt(offset)), r & mask];
 const mapOneEncode = map(oneEncode);
 export const toSequence = (s) => toArray(mapOneEncode(stringToCodePointList(s)));
 /**

package/fjs/bnf/proof.f.js

@@ -0,0 +1,69 @@
+import { assert, assertEq } from '../asserts/module.f.js';
+import { classic, deterministic } from './testlib.f.js';
+import { rangeEncode, str, set, range, commaJoin0Plus, isEmpty, oneEncode, repeat1Plus, } from './module.f.js';
+export const proof = {
+    test: () => {
+        classic();
+        deterministic();
+    },
+    throw: {
+        rangeEncodeInvalid: [
+            () => { rangeEncode(-1, 0); },
+            () => { rangeEncode(0, -1); },
+            () => { rangeEncode(5, 3); },
+        ],
+        rangeInvalid: [
+            () => { range('a'); },
+            () => { range('abc'); },
+        ],
+    },
+    str: [
+        () => {
+            const result = str('a');
+            assertEq(typeof result, 'number', result);
+            assertEq(result, oneEncode(0x61));
+        },
+        () => {
+            const result = str('ab');
+            assert(Array.isArray(result), result);
+            assertEq(result.length, 2, result);
+        },
+    ],
+    set: () => {
+        const result = set('abc');
+        assert(!(typeof result !== 'object' || result === null), result);
+        assert('a' in result, result);
+        assert('b' in result, result);
+        assert('c' in result, result);
+    },
+    commaJoin0Plus: () => {
+        const ws = '';
+        const item = 'x';
+        const result = commaJoin0Plus(ws)('[]', item);
+        assert(Array.isArray(result), result);
+        assert(result[0] === '[', result);
+    },
+    isEmpty: [
+        () => { assert(isEmpty(''), 'empty string should be empty'); },
+        () => { assert(isEmpty([]), 'empty array should be empty'); },
+        () => { assert(!(isEmpty('a')), 'non-empty string should not be empty'); },
+        () => {
+            const f = () => '';
+            assert(isEmpty(f), 'function returning empty string should be empty');
+        },
+    ],
+    repeat1Plus: [
+        () => {
+            const result = repeat1Plus('x');
+            assert(result[0] === 'x');
+            assertEq(typeof result[1], 'function', 'expected repeat0Plus function');
+        },
+        () => {
+            const rule = 'ab';
+            const result = repeat1Plus(rule);
+            assertEq(result[0], rule);
+            const inner = result[1]();
+            assert(!(!('some' in inner) || !('none' in inner)), 'expected Option shape');
+        },
+    ],
+};

package/{fs → fjs}/bnf/testlib.f.js

@@ -1,4 +1,4 @@
-import { commaJoin0Plus, max, none, option, range, remove, repeat, repeat0Plus, set } from './module.f.js';
+import { commaJoin0Plus, none, option, range, remove, repeat, repeat0Plus, set, unicodeMax } from './module.f.js';
 export const classic = () => {
     // https://www.json.org/json-en.html
     const json = () => [element];
@@ -93,7 +93,7 @@ export const deterministic = () => {
     const string = [
         '"',
         repeat0Plus({
-            ...remove(range(` ${max}`), set('"\\')),
+            ...remove(range(` ${unicodeMax}`), set('"\\')),
             escape: [
                 '\\',
                 {

package/{fs → fjs}/cas/cli/proof.f.d.ts

@@ -2,13 +2,16 @@ export declare const proof: {
     mainAdd: () => void;
     mainAddGetBig: () => void;
     mainAddWrongArgs: () => void;
+    mainAddMissingFile: () => void;
     mainGetFound: () => void;
     mainGetNotFound: () => void;
     mainGetWrongArgs: () => void;
     mainGetInvalidHash: () => void;
     mainList: () => void;
     mainListEmptyStore: () => void;
-    mainListCorruptStore: () => void;
     mainNoCmd: () => void;
     mainUnknownCmd: () => void;
+    throw: {
+        mainListCorruptStore: () => readonly [import("../../effects/node/virtual/module.f.ts").State, number];
+    };
 };

package/{fs → fjs}/cas/cli/proof.f.js

@@ -13,12 +13,8 @@ export const proof = {
         const content = vec8(0x2an);
         const state = { ...emptyState, root: { myfile: [content] } };
         const [finalState, exitCode] = virtual(state)(main(makeOptions(['add', 'myfile'])));
-        if (exitCode !== 0) {
-            throw ['expected exit 0', exitCode];
-        }
-        if (finalState.stdout.length === 0) {
-            throw 'expected hash in stdout';
-        }
+        assertEq(exitCode, 0, ['expected exit 0', exitCode]);
+        assert(finalState.stdout.length !== 0, 'expected hash in stdout');
     },
     mainAddGetBig: () => {
         const chunk = vec(maxLength)(1n);
@@ -47,18 +43,21 @@ export const proof = {
         assertEq(exitCode, 1);
         assert(finalState.stderr.length !== 0);
     },
+    mainAddMissingFile: () => {
+        // The source path doesn't exist, so `streamFile`'s first read comes back as an
+        // error item; `write` fails closed with that error and the handler exits 1
+        // without ever calling `log` — covers the `hashResult[0] === 'error'` branch.
+        const [, exitCode] = virtual(emptyState)(main(makeOptions(['add', 'missing'])));
+        assertEq(exitCode, 1);
+    },
     mainGetFound: () => {
         const content = vec8(0x2an);
         const state = { ...emptyState, root: { myfile: [content] } };
         const [state1, exitCode1] = virtual(state)(main(makeOptions(['add', 'myfile'])));
-        if (exitCode1 !== 0) {
-            throw ['expected add exit 0', exitCode1];
-        }
+        assertEq(exitCode1, 0, ['expected add exit 0', exitCode1]);
         const hashStr = state1.stdout.trim();
         const [, exitCode2] = virtual(state1)(main(makeOptions(['get', hashStr, 'output'])));
-        if (exitCode2 !== 0) {
-            throw ['expected get exit 0', exitCode2];
-        }
+        assertEq(exitCode2, 0, ['expected get exit 0', exitCode2]);
     },
     mainGetNotFound: () => {
         // valid cBase32 hash that has not been stored
@@ -68,82 +67,46 @@ export const proof = {
         const hashStr = state1.stdout.trim();
         // use an empty store so the hash is not found
         const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['get', hashStr, 'output'])));
-        if (exitCode !== 1) {
-            throw ['expected exit 1', exitCode];
-        }
-        if (finalState.stderr.length === 0) {
-            throw 'expected error in stderr';
-        }
+        assertEq(exitCode, 1, ['expected exit 1', exitCode]);
+        assert(finalState.stderr.length !== 0, 'expected error in stderr');
     },
     mainGetWrongArgs: () => {
         const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['get'])));
-        if (exitCode !== 1) {
-            throw ['expected exit 1', exitCode];
-        }
-        if (finalState.stderr.length === 0) {
-            throw 'expected error in stderr';
-        }
+        assertEq(exitCode, 1, ['expected exit 1', exitCode]);
+        assert(finalState.stderr.length !== 0, 'expected error in stderr');
     },
     mainGetInvalidHash: () => {
         const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['get', 'not-a-valid-hash', 'output'])));
-        if (exitCode !== 1) {
-            throw ['expected exit 1', exitCode];
-        }
-        if (finalState.stderr.length === 0) {
-            throw 'expected error in stderr';
-        }
+        assertEq(exitCode, 1, ['expected exit 1', exitCode]);
+        assert(finalState.stderr.length !== 0, 'expected error in stderr');
     },
     mainList: () => {
         const content = vec8(0x2an);
         const state = { ...emptyState, root: { myfile: [content] } };
         const [state1] = virtual(state)(main(makeOptions(['add', 'myfile'])));
         const [, exitCode] = virtual(state1)(main(makeOptions(['list'])));
-        if (exitCode !== 0) {
-            throw ['expected exit 0', exitCode];
-        }
+        assertEq(exitCode, 0, ['expected exit 0', exitCode]);
     },
     mainListEmptyStore: () => {
         // A fresh directory has no `.cas` yet; listing must succeed (empty),
         // not crash unwrapping a readdir ENOENT.
         const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['list'])));
-        if (exitCode !== 0) {
-            throw ['expected exit 0', exitCode];
-        }
-        if (finalState.stdout !== '') {
-            throw ['expected empty stdout', finalState.stdout];
-        }
-    },
-    mainListCorruptStore: () => {
-        // `.cas` exists but is a file, not a directory: a real storage error
-        // that must surface, not be masked as an empty list.
-        const state = { ...emptyState, root: { '.cas': [vec8(0x2an)] } };
-        let threw = false;
-        try {
-            virtual(state)(main(makeOptions(['list'])));
-        }
-        catch {
-            threw = true;
-        }
-        if (!threw) {
-            throw 'expected list to surface the storage error';
-        }
+        assertEq(exitCode, 0, ['expected exit 0', exitCode]);
+        assertEq(finalState.stdout, '', ['expected empty stdout', finalState.stdout]);
     },
     mainNoCmd: () => {
         const [finalState, exitCode] = virtual(emptyState)(main(makeOptions([])));
-        if (exitCode !== 1) {
-            throw ['expected exit 1', exitCode];
-        }
-        if (finalState.stderr.length === 0) {
-            throw 'expected error in stderr';
-        }
+        assertEq(exitCode, 1, ['expected exit 1', exitCode]);
+        assert(finalState.stderr.length !== 0, 'expected error in stderr');
     },
     mainUnknownCmd: () => {
         const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['bogus'])));
-        if (exitCode !== 1) {
-            throw ['expected exit 1', exitCode];
-        }
-        if (finalState.stderr.length === 0) {
-            throw 'expected error in stderr';
-        }
+        assertEq(exitCode, 1, ['expected exit 1', exitCode]);
+        assert(finalState.stderr.length !== 0, 'expected error in stderr');
+    },
+    throw: {
+        // `.cas` exists but is a file, not a directory: a real storage error
+        // that must surface, not be masked as an empty list.
+        mainListCorruptStore: () => virtual({ ...emptyState, root: { '.cas': [vec8(0x2an)] } })(main(makeOptions(['list']))),
     },
 };

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

@@ -0,0 +1,19 @@
+import { type Operation } from '../../../effects/module.f.ts';
+import { type MemOp } from '../../../effects/memory/module.f.ts';
+import { type ToolEntry } from '../../../mcp/module.f.ts';
+import { type Evo } from '../module.f.ts';
+/** Arguments for `evo_list`: none. */
+export declare const evoListArgs: {};
+/** Arguments for `evo_head`: the subject whose current heads are requested. */
+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`. */
+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]>;
+    readonly subject: import("../../../types/rtti/module.f.ts").Or<readonly [import("../../../types/rtti/module.f.ts").String, undefined]>;
+    readonly archived: import("../../../types/rtti/module.f.ts").Or<readonly [true, undefined]>;
+};
+/** Registry of all Evo tools, bound to an `Evo<O>`. */
+export declare const evoToolRegistry: <O extends Operation>(e: Evo<O>) => readonly ToolEntry<O | MemOp>[];

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

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ *
+ * ## 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)            |
+ *
+ * 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
+ * `Cas<O>` and cache slot, concatenates `evoToolRegistry` onto its own
+ * registry, and serves everything from that single process — one `~/.cas/`
+ * store, one Evo cache, one server.
+ *
+ * @module
+ */
+import { string, option, array } from '../../../types/rtti/module.f.js';
+import { pure } 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';
+import { identity } from '../../../types/function/module.f.js';
+import {} from '../module.f.js';
+// ── Argument schemas (declared once, used for both inputSchema and validate) ─────
+/** Arguments for `evo_list`: none. */
+export const evoListArgs = {};
+/** Arguments for `evo_head`: the subject whose current heads are requested. */
+export const evoHeadArgs = {
+    subject: string,
+};
+/** Arguments for `evo_add`: a new revision, per `fjs/cas/evo`'s `AddRevision`. */
+export const evoAddArgs = {
+    parents: array(string),
+    snapshot: option(string),
+    subject: option(string),
+    archived: option(true),
+};
+// ── Tool registry ────────────────────────────────────────────────────────────────
+/** Canonical JSON encoder for `evo_list`'s result. */
+const toJson = stringify(identity);
+/** Registry of all Evo tools, bound to an `Evo<O>`. */
+export const evoToolRegistry = (e) => [
+    toolEntry('evo_list', 'List all subjects with at least one stored revision, as a JSON array of strings.', evoListArgs, 
+    // Subjects are arbitrary caller-supplied strings (unlike hashes, not
+    // 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])))),
+];

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

@@ -0,0 +1,9 @@
+export declare const proof: {
+    toolNamesMatchTheDesign: () => void;
+    evoListReflectsTheCache: () => void;
+    evoListEncodesArbitrarySubjectsAsJson: () => void;
+    evoHeadReflectsTheCache: () => void;
+    evoHeadMissingSubjectIsInvalidArguments: () => void;
+    evoAddSuccessReturnsHash: () => void;
+    evoAddDomainErrorIsError: () => void;
+};

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

@@ -0,0 +1,95 @@
+import { assert, assertEq } from '../../../asserts/module.f.js';
+import { fileCas } from '../../module.f.js';
+import { sha256 } from '../../../crypto/sha2/module.f.js';
+import { emptyState, virtual } from '../../../effects/node/virtual/module.f.js';
+import { vec8 } from '../../../types/bit_vec/module.f.js';
+import { vecToCBase32 } from '../../../basen/cbase32/module.f.js';
+import { initEvo, evo } from '../module.f.js';
+import { evoToolRegistry } from './module.f.js';
+const home = '/home/user';
+const findEntry = (registry, name) => {
+    const entry = registry.find(e => e.name === name);
+    assert(entry !== undefined, ['missing tool entry', name]);
+    return entry;
+};
+const textOf = (result) => {
+    const [item] = result.content;
+    assert(item.type === 'text', ['expected a text content item', item]);
+    return item.text;
+};
+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');
+    },
+    evoListReflectsTheCache: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const entry = findEntry(evoToolRegistry(e), 'evo_list');
+        const [, result] = virtual(state0)(entry.handle({}));
+        assert(!result.isError);
+        assertEq(textOf(result), '[]');
+    },
+    // Regression: subjects are arbitrary strings, not constrained to a
+    // newline-free alphabet like hashes, so evo_list must not join them with
+    // '\n' — a subject containing a newline, or an empty subject, would be
+    // indistinguishable from multiple/no subjects in that format. JSON
+    // encoding preserves both exactly.
+    evoListEncodesArbitrarySubjectsAsJson: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const [state1, addA] = virtual(state0)(e.add({ parents: [], subject: 'line one\nline two', snapshot: vecToCBase32(vec8(0x2an)) }));
+        assert(addA[0] === 'ok', ['expected add ok', addA]);
+        const [state2, addB] = virtual(state1)(e.add({ parents: [], subject: '', snapshot: vecToCBase32(vec8(0x2bn)) }));
+        assert(addB[0] === 'ok', ['expected add ok', addB]);
+        const entry = findEntry(evoToolRegistry(e), 'evo_list');
+        const [, result] = virtual(state2)(entry.handle({}));
+        assert(!result.isError);
+        const subjects = JSON.parse(textOf(result));
+        assertEq(subjects.length, 2);
+        assert(subjects.includes('line one\nline two'), ['unexpected subjects', subjects]);
+        assert(subjects.includes(''), ['unexpected subjects', subjects]);
+    },
+    evoHeadReflectsTheCache: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const entry = findEntry(evoToolRegistry(e), 'evo_head');
+        const [, result] = virtual(state0)(entry.handle({ subject: 'nope' }));
+        assert(!result.isError);
+        assertEq(textOf(result), '');
+    },
+    evoHeadMissingSubjectIsInvalidArguments: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const entry = findEntry(evoToolRegistry(e), 'evo_head');
+        const [, result] = virtual(state0)(entry.handle({}));
+        assertEq(result.isError, true);
+    },
+    // Covers evo_add's success branch: a valid revision is stored and its
+    // hash comes back as plain, non-error text.
+    evoAddSuccessReturnsHash: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const entry = findEntry(evoToolRegistry(e), 'evo_add');
+        const args = { parents: [], subject: 'doc', snapshot: vecToCBase32(vec8(0x1n)) };
+        const [, result] = virtual(state0)(entry.handle(args));
+        assert(!result.isError);
+        assert(textOf(result).length > 0);
+    },
+    // Covers evo_add's error branch: a domain-level failure (Evo.add's
+    // Result) is surfaced as isError with the failure message as text.
+    evoAddDomainErrorIsError: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const entry = findEntry(evoToolRegistry(e), 'evo_add');
+        const [, result] = virtual(state0)(entry.handle({ parents: [] }));
+        assertEq(result.isError, true);
+        assert(textOf(result).includes('subject is required'));
+    },
+};

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

@@ -0,0 +1,138 @@
+/**
+ * Evo API: subjects and revision heads, cached in memory over an immutable
+ * content-addressable store.
+ *
+ * A `Cas<O>` stores `vnd.fjs.revision` blobs ([`fjs/media/revision`](../../media/revision/module.f.ts))
+ * like any other content: as immutable bytes under a hash. Resolving "what
+ * are the current heads of subject X" from that store means walking every
+ * stored revision and reversing the parent links — too expensive to redo on
+ * every query. This module scans the store once into an in-memory `Cache`
+ * ([`fjs/effects/memory`](../../effects/memory/module.f.ts)) mapping subject →
+ * head hashes, then keeps the cache current as new revisions are `add`ed
+ * through it — or, for a revision stored some other way (e.g. the generic
+ * `cas_add` MCP tool), via {@link syncRevision}.
+ *
+ * A **head** of a subject is any stored revision of that subject whose hash
+ * is not referenced as a `parents` entry by another revision of the same
+ * subject (see [`fjs/media/revision/README.md`](../../media/revision/README.md)).
+ * `Cache` therefore tracks, per subject, every revision hash seen and every
+ * hash referenced as somebody's parent; heads are the set difference between
+ * the two, computed at read time ({@link headsOf}). Storing both sets rather
+ * than a running head list is what makes folding revisions truly order
+ * independent: `cas.list()` (used by {@link buildCache} to scan an existing
+ * store) returns hashes in hash order, not revision ancestry, so a child can
+ * be seen before its parent — an incremental "drop this hash from the head
+ * set, then re-add whichever hash we just saw" would wrongly resurrect the
+ * parent as a head once it is scanned after its child. Tracking the two sets
+ * separately and only subtracting at read time has no such ordering
+ * dependency: whichever order revisions are folded in, `hashes − parents`
+ * converges to the same result. {@link buildCache} and {@link addRevision}
+ * both fold through the same {@link addRevisionToCache}, the former over the
+ * whole store at once, the latter incrementally for one new revision.
+ *
+ * @module
+ */
+import { type Effect, type Operation } from '../../effects/module.f.ts';
+import { type Key, type MemOp } from '../../effects/memory/module.f.ts';
+import { type Cas } from '../module.f.ts';
+import { type Revision } from '../../media/revision/module.f.ts';
+import { type Result } from '../../types/result/module.f.ts';
+import { type StringMap } from '../../types/object/module.f.ts';
+import type { Vec } from '../../types/bit_vec/module.f.ts';
+/** A cBase32 content hash, as accepted/returned by `Cas<O>`. */
+export type Hash = string;
+/** The identity of a mutable object whose revisions are being evolved. */
+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.
+ */
+export type AddRevision = {
+    readonly parents: readonly Hash[];
+    readonly snapshot?: Hash | undefined;
+    readonly subject?: Subject | undefined;
+    readonly archived?: true | undefined;
+};
+/**
+ * Per-subject bookkeeping: every revision hash seen for the subject, and
+ * every hash any of those revisions names as a parent. See the module doc
+ * for why both sets are kept (rather than a running head list) and
+ * {@link headsOf} for how heads are derived from them.
+ */
+export type SubjectState = {
+    readonly hashes: readonly Hash[];
+    readonly parents: readonly Hash[];
+};
+/** In-memory index: subject → its {@link SubjectState}. */
+export type Cache = {
+    readonly bySubject: StringMap<string, SubjectState>;
+};
+/** A cache with no known subjects yet — the starting point for {@link buildCache}. */
+export declare const emptyCache: Cache;
+/**
+ * Decodes already-read bytes as a `vnd.fjs.revision`. Returns `null` for
+ * anything that is not a valid revision — bytes that are not valid UTF-8, or
+ * text that does not parse/validate as the dialect.
+ */
+export declare const decodeRevisionVec: (value: Vec) => Revision | null;
+/**
+ * Reads and decodes the blob at `hash` as a `vnd.fjs.revision`. Returns
+ * `null` for anything that is not a valid revision — a missing hash, or (via
+ * {@link decodeRevisionVec}) bytes that are not valid UTF-8 or do not
+ * parse/validate as the dialect — so a store containing arbitrary other
+ * content can be scanned without failing the whole cache build.
+ */
+export declare const decodeRevisionBlob: <O extends Operation>(cas: Cas<O>) => (hash: Vec) => Effect<O, Revision | null>;
+/**
+ * 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 declare const buildCache: <O extends Operation>(cas: Cas<O>) => Effect<O, Cache>;
+/** Scans `cas` once and allocates a memory slot holding the resulting {@link Cache}. */
+export declare const initEvo: <O extends Operation>(cas: Cas<O>) => Effect<O | MemOp, Key<Cache>>;
+/**
+ * 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`
+ * 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.
+ */
+export declare const syncRevision: (cacheKey: Key<Cache>) => (hash: Vec) => (value: Vec) => Effect<MemOp, void>;
+/**
+ * Adds a new revision to `cas` and folds it into the cache at `cacheKey`.
+ *
+ * Steps: resolve and validate every parent ({@link resolveParents}), resolve
+ * `subject` from them ({@link resolveSubject}) and check every parent
+ * actually belongs to it ({@link validateParentSubjects}), resolve `snapshot`
+ * ({@link resolveSnapshot}) and compute `generation`
+ * ({@link computeGeneration}), assemble a `Revision` and check its hash /
+ * generation semantics (`fjs/media/revision` `checkReferences` — the same rule
+ * a reader applies; the shape itself is already guaranteed by this function's
+ * own field types), encode and write it to `cas`, then fold the new revision
+ * into the cache. Every failure — an invalid or missing parent, a
+ * cross-subject parent, an unresolvable subject or snapshot, an invalid
+ * 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`.
+ */
+export declare const addRevision: <O extends Operation>(cas: Cas<O>) => (cacheKey: Key<Cache>) => (input: AddRevision) => Effect<O | MemOp, Result<Hash, 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. */
+    readonly list: () => Effect<MemOp, readonly Subject[]>;
+    /** 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>>;
+};
+/** 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>;