functionalscript 0.37.0 → 0.39.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/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/{fs → 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/{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,27 @@
+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_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]>;
+    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,94 @@
+/**
+ * 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_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
+ * `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, 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';
+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_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),
+    subject: option(string),
+    archived: option(true),
+};
+// ── Tool registry ────────────────────────────────────────────────────────────────
+/** 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) => [
+    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.
+    () => 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

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