functionalscript 0.36.0 → 0.38.0

package/fjs/media/revision/module.f.js

@@ -0,0 +1,122 @@
+/**
+ * `vnd.fjs.revision` — one step in the evolution of a mutable object on top
+ * of an immutable content-addressable store.
+ *
+ * A revision BLOB links back to its parent revision(s) (a DAG, not just a
+ * chain, so concurrent edits can merge) and carries the full materialized
+ * content of that step — never an incremental diff (see the versioning rule
+ * in the README). This module is the pure format only: the rtti schema, the
+ * `dialect` tag, and decode/validate. No store access, no effects — head
+ * resolution, materialization, and reverse indexes are a separate, deferred
+ * concern.
+ *
+ * See `README.md` for the full spec.
+ *
+ * @module
+ */
+import { array, number, option, string } from '../../types/rtti/module.f.js';
+import { validate as rttiValidate } from '../../types/rtti/validate/module.f.js';
+import { parse as jsonParse } from '../json/parser/module.f.js';
+import { tokenize as jsonTokenize } from '../json/tokenizer/module.f.js';
+import { stringToList } from '../../text/utf16/module.f.js';
+import { cBase32ToVec } from '../../basen/cbase32/module.f.js';
+import { error, ok } from '../../types/result/module.f.js';
+/**
+ * Format tag: names the dialect of this BLOB. The media type it is served
+ * with is derived mechanically: `application/` + `dialect` + `+json`.
+ */
+export const dialect = 'vnd.fjs.revision';
+/** The media type derived from {@link dialect}: `application/vnd.fjs.revision+json`. */
+export const mediaType = `application/${dialect}+json`;
+/**
+ * rtti schema for the snapshot-reference type: a cbase32 CAS hash string.
+ *
+ * This is `string` at the rtti (structural) level — rtti schemas can't
+ * express string-content refinements — so cbase32 decodability, and the
+ * rejection of `https://` bridge URLs and any other location-addressed
+ * reference form, is enforced by {@link isHash} / {@link validate} below,
+ * not by this schema on its own.
+ */
+export const hash = string;
+/**
+ * rtti schema for a `revision` BLOB. See the README for the full semantics of
+ * each field; `dialect` is the type discriminant, matched here as an exact
+ * literal so structural validation alone rejects any other dialect's blob.
+ */
+export const revisionSchema = {
+    dialect,
+    subject: string,
+    parents: array(hash),
+    snapshot: hash,
+    generation: number,
+    archived: option(true),
+};
+/** Structural-only validator: checks the shape, not the hash / generation semantics. */
+const validateShape = rttiValidate(revisionSchema);
+/** True when `s` decodes as a cbase32 CAS hash (rejects `https://` and any other non-cbase32 string). */
+export const isHash = (s) => cBase32ToVec(s) !== null;
+/**
+ * Checks the semantic refinements the structural schema can't express on an
+ * already shape-valid revision: every `parents` entry and the `snapshot` must
+ * decode as a cbase32 hash ({@link isHash}), and `generation` must be a
+ * non-negative *safe* integer. `subject` is not checked — it is an identity
+ * string, never a snapshot reference, so any string is valid.
+ *
+ * `generation` uses `Number.isSafeInteger`, not `Number.isInteger`: a value at
+ * or above `2 ** 53` passes `isInteger` but is no longer uniquely
+ * representable, so `1 + max(parents' generations)` — how a writer derives the
+ * next generation — can round back to the parent's value and fail to advance.
+ * Rejecting unsafe integers keeps stored generations exact.
+ *
+ * Both `snapshot` and `generation` are required by the schema, so no absence
+ * ever has to be resolved here: a revision states its content and its
+ * generation explicitly, and is fully interpretable in isolation (see the
+ * README). The former snapshot-resolution algorithm (subject-as-fallback,
+ * single-parent inheritance, multi-parent rejection) is gone.
+ *
+ * Exported separately from {@link validate} for callers that assemble a
+ * `Revision` themselves from already-typed fields (e.g. `fjs/cas/evo`'s
+ * `addRevision`): the shape is then guaranteed by TypeScript already, so only
+ * these semantic (string-only error) checks are worth re-running — routing
+ * through the combined structural-plus-semantic `validate` would add an
+ * unreachable structural-error branch on the caller's side.
+ */
+export const checkReferences = (r) => {
+    for (const p of r.parents) {
+        if (!isHash(p)) {
+            return error(`parent is not a valid hash: ${p}`);
+        }
+    }
+    if (!isHash(r.snapshot)) {
+        return error(`snapshot is not a valid hash: ${r.snapshot}`);
+    }
+    if (!Number.isSafeInteger(r.generation) || r.generation < 0) {
+        return error(`generation must be a non-negative safe integer: ${r.generation}`);
+    }
+    return ok(r);
+};
+/**
+ * Validates an already-parsed JSON value as a `revision` BLOB: structural
+ * (rtti) validation followed by the hash / generation semantic checks.
+ */
+export const validate = (value) => {
+    const [t, v] = validateShape(value);
+    if (t === 'error') {
+        return error(v);
+    }
+    return checkReferences(v);
+};
+/** Parses `text` as JSON without relying on `JSON.parse` (the shared `fjs/media/json` parser/tokenizer). */
+const parseJson = (text) => jsonParse(jsonTokenize(stringToList(text)));
+/**
+ * Decodes `text` as a `revision` BLOB: JSON-parses it, then validates it per
+ * {@link validate}. Detection is semantic, not syntactic — any JSON that
+ * satisfies the schema is a revision, regardless of key order or whitespace.
+ */
+export const decodeText = (text) => {
+    const [t, v] = parseJson(text);
+    if (t === 'error') {
+        return error(v);
+    }
+    return validate(v);
+};

package/fjs/media/revision/proof.f.d.ts

@@ -0,0 +1,31 @@
+export declare const proof: {
+    dialectAndMediaType: () => void;
+    isHash: {
+        validHash: () => void;
+        httpsRejected: () => void;
+        arbitraryStringRejected: () => void;
+    };
+    validate: {
+        allFieldsPresent: () => void;
+        nonHashSubjectAccepted: () => void;
+        multiParentAccepted: () => void;
+        missingSnapshotRejected: () => void;
+        nonHashSnapshotRejected: () => void;
+        missingGenerationRejected: () => void;
+        nonIntegerGenerationRejected: () => void;
+        negativeGenerationRejected: () => void;
+        unsafeIntegerGenerationRejected: () => void;
+        positiveGenerationAccepted: () => void;
+        httpsRejectedInParents: () => void;
+        archivedAccepted: () => void;
+        wrongDialectRejected: () => void;
+        missingSubjectRejected: () => void;
+        extraFieldsAccepted: () => void;
+    };
+    decodeText: {
+        validJson: () => void;
+        keyOrderIndependent: () => void;
+        malformedJsonRejected: () => void;
+        ordinaryJsonRejected: () => void;
+    };
+};

package/fjs/media/revision/proof.f.js

@@ -0,0 +1,140 @@
+import { assert, assertEq } from '../../asserts/module.f.js';
+import { dialect, mediaType, isHash, validate, decodeText } from './module.f.js';
+// Valid cbase32 hashes (round-tripped in fjs/basen/cbase32/proof.f.ts): single
+// cbase32 symbols, cheap to write inline here.
+const h1 = '8';
+const h2 = 'r';
+// A shape-valid revision: every required field present (`snapshot` and
+// `generation` included), with `extra` overriding or adding fields per test.
+const revisionOf = (extra) => ({
+    dialect,
+    subject: h1,
+    parents: [],
+    snapshot: h2,
+    generation: 0,
+    ...extra,
+});
+export const proof = {
+    dialectAndMediaType: () => {
+        assertEq(dialect, 'vnd.fjs.revision');
+        assertEq(mediaType, 'application/vnd.fjs.revision+json');
+    },
+    isHash: {
+        validHash: () => assert(isHash(h1)),
+        httpsRejected: () => assert(!isHash('https://example.com/blob/abc')),
+        arbitraryStringRejected: () => assert(!isHash('not-a-hash!')),
+    },
+    validate: {
+        // A fully explicit revision validates.
+        allFieldsPresent: () => {
+            const [t] = validate(revisionOf({}));
+            assertEq(t, 'ok');
+        },
+        // `subject` is a pure identity string, never a snapshot reference: a
+        // zero-parent revision whose `subject` is not a hash is now valid,
+        // because `snapshot` is always stated explicitly.
+        nonHashSubjectAccepted: () => {
+            const r = validate(revisionOf({ subject: 'my-config' }));
+            assert(r[0] === 'ok', ['expected ok', r]);
+            assertEq(r[1].subject, 'my-config');
+        },
+        // A merge revision (more than one parent) is valid like any other —
+        // there is no "multiple parents without snapshot" case left, because
+        // `snapshot` is required.
+        multiParentAccepted: () => {
+            const r = validate(revisionOf({ subject: 'my-config', parents: [h1, h2], snapshot: h2 }));
+            assert(r[0] === 'ok', ['expected ok', r]);
+            assertEq(r[1].snapshot, h2);
+        },
+        // `snapshot` is required: absent is a shape error.
+        missingSnapshotRejected: () => {
+            const [t] = validate({ dialect, subject: h1, parents: [], generation: 0 });
+            assertEq(t, 'error');
+        },
+        // `snapshot` must decode as a hash — `https://` bridge URLs rejected.
+        nonHashSnapshotRejected: () => {
+            const [t] = validate(revisionOf({ snapshot: 'https://example.com/x' }));
+            assertEq(t, 'error');
+        },
+        // `generation` is required: absent is a shape error.
+        missingGenerationRejected: () => {
+            const [t] = validate({ dialect, subject: h1, parents: [], snapshot: h2 });
+            assertEq(t, 'error');
+        },
+        // `generation` must be an integer: a fractional value is rejected.
+        nonIntegerGenerationRejected: () => {
+            const [t] = validate(revisionOf({ generation: 1.5 }));
+            assertEq(t, 'error');
+        },
+        // `generation` must be non-negative.
+        negativeGenerationRejected: () => {
+            const [t] = validate(revisionOf({ generation: -1 }));
+            assertEq(t, 'error');
+        },
+        // `generation` must be a *safe* integer: at `2 ** 53` and above the
+        // value is no longer uniquely representable, so `1 + max(...)` could
+        // fail to advance — such a blob is rejected (`Number.isInteger` would
+        // accept it; `Number.isSafeInteger` does not).
+        unsafeIntegerGenerationRejected: () => {
+            const [t] = validate(revisionOf({ generation: 2 ** 53 }));
+            assertEq(t, 'error');
+        },
+        // A positive integer generation is accepted.
+        positiveGenerationAccepted: () => {
+            const r = validate(revisionOf({ parents: [h1], generation: 3 }));
+            assert(r[0] === 'ok', ['expected ok', r]);
+            assertEq(r[1].generation, 3);
+        },
+        // `https://` bridge URLs are rejected wherever a hash is required.
+        httpsRejectedInParents: () => {
+            const [t] = validate(revisionOf({ parents: ['https://example.com/x'] }));
+            assertEq(t, 'error');
+        },
+        // `archived` follows the presence-only `option(true)` idiom.
+        archivedAccepted: () => {
+            const [t] = validate(revisionOf({ archived: true }));
+            assertEq(t, 'ok');
+        },
+        // Wrong dialect tag: structural validation rejects it outright.
+        wrongDialectRejected: () => {
+            const [t] = validate({ dialect: 'vnd.fjs.other', subject: h1, parents: [], snapshot: h2, generation: 0 });
+            assertEq(t, 'error');
+        },
+        // Missing required fields: rejected.
+        missingSubjectRejected: () => {
+            const [t] = validate({ dialect, parents: [], snapshot: h2, generation: 0 });
+            assertEq(t, 'error');
+        },
+        // rtti structs are open: extra fields don't break validation — the
+        // additive forward-compatibility path the versioning rule relies on.
+        extraFieldsAccepted: () => {
+            const [t] = validate(revisionOf({ future: 'field' }));
+            assertEq(t, 'ok');
+        },
+    },
+    decodeText: {
+        validJson: () => {
+            const r = decodeText(JSON.stringify(revisionOf({})));
+            assert(r[0] === 'ok', ['expected ok', r]);
+            assertEq(r[1].subject, h1);
+        },
+        // Key order carries no meaning: detection parses the JSON and
+        // validates the parsed value, so `dialect` need not be first.
+        keyOrderIndependent: () => {
+            const text = `{"generation":0,"snapshot":"${h2}","parents":[],"subject":"${h1}","dialect":"${dialect}"}`;
+            const [t] = decodeText(text);
+            assertEq(t, 'ok');
+        },
+        malformedJsonRejected: () => {
+            const [t] = decodeText('{not json');
+            assertEq(t, 'error');
+        },
+        // Ordinary JSON that isn't a revision at all falls through as an error
+        // here — `fjs/media`'s composed detector is what falls back to the
+        // ordinary detector; this module only reports validity.
+        ordinaryJsonRejected: () => {
+            const [t] = decodeText('{"hello":"world"}');
+            assertEq(t, 'error');
+        },
+    },
+};

package/{fs/mime → fjs/media/type}/module.f.d.ts

@@ -32,12 +32,12 @@
  *
  * @module
  */
-import { type Vec } from '../types/bit_vec/module.f.ts';
-import type { Nullable } from '../types/nullable/module.f.ts';
-import { type Effect, type Operation } from '../effects/module.f.ts';
-import type { List } from '../effects/list/module.f.ts';
-import type { IoResult } from '../effects/node/module.f.ts';
-import { type Utf8State } from '../text/utf8/module.f.ts';
+import { type Vec } from '../../types/bit_vec/module.f.ts';
+import type { Nullable } from '../../types/nullable/module.f.ts';
+import { type Effect, type Operation } from '../../effects/module.f.ts';
+import type { List } from '../../effects/list/module.f.ts';
+import type { IoResult } from '../../effects/node/module.f.ts';
+import { type Utf8State } from '../../text/utf8/module.f.ts';
 /**
  * Detects the MIME type of `bytes` from its leading magic-byte signature.
  *

package/{fs/mime → fjs/media/type}/module.f.js

@@ -32,12 +32,12 @@
  *
  * @module
  */
-import { msb, fromSentinel, length, u8List } from "../types/bit_vec/module.f.js";
-import { iterable } from "../types/list/module.f.js";
-import { pure } from "../effects/module.f.js";
-import { ok, error } from "../types/result/module.f.js";
-import { isValidCodePoint, isTextCodePoint } from "../text/code_point/module.f.js";
-import { utf8ByteToCodePointOp } from "../text/utf8/module.f.js";
+import { msb, fromSentinel, length, u8List } from '../../types/bit_vec/module.f.js';
+import { iterable } from '../../types/list/module.f.js';
+import { pure } from '../../effects/module.f.js';
+import { ok, error } from '../../types/result/module.f.js';
+import { isValidCodePoint, isTextCodePoint } from '../../text/code_point/module.f.js';
+import { utf8ByteToCodePointOp } from '../../text/utf8/module.f.js';
 const { startsWith, removeFront } = msb;
 // Each signature is written as a hex literal whose leading `1` nibble is a
 // sentinel marking the start of the byte run (so leading zero bytes survive)

package/{fs/mime → fjs/media/type}/proof.f.js

@@ -1,9 +1,9 @@
-import { assert, assertEq } from "../asserts/module.f.js";
-import { msb, u8ListToVec, vec8, repeat, empty } from "../types/bit_vec/module.f.js";
-import { decode } from "../effects/module.f.js";
-import { nonEmpty, empty as emptyList } from "../effects/list/module.f.js";
-import { ok } from "../types/result/module.f.js";
-import { detect, detectStream, detectVec } from "./module.f.js";
+import { assert, assertEq } from '../../asserts/module.f.js';
+import { msb, u8ListToVec, vec8, repeat, empty } from '../../types/bit_vec/module.f.js';
+import { decode } from '../../effects/module.f.js';
+import { nonEmpty, empty as emptyList } from '../../effects/list/module.f.js';
+import { ok } from '../../types/result/module.f.js';
+import { detect, detectStream, detectVec } from './module.f.js';
 // Builds a big-endian `Vec` from a list of byte values — mirrors how the CAS
 // store would hold the leading bytes of a stored blob.
 const bytes = (...b) => u8ListToVec(msb)(b);
@@ -11,9 +11,7 @@ const bytes = (...b) => u8ListToVec(msb)(b);
 // Evaluates a fully pure effect (no operations) to its result.
 const runPure = (e) => {
     const d = decode(e);
-    if (!d.done) {
-        throw 'effect is not pure';
-    }
+    assert(d.done, 'effect is not pure');
     return d.result;
 };
 // Builds a CAS-style read stream from a sequence of ok(chunk) items.
@@ -21,9 +19,7 @@ const stream = (...chunks) => chunks.reduceRight((tail, c) => nonEmpty(ok(c), ta
 // Runs the streaming detector over the given chunks and unwraps the metadata.
 const detectChunks = (...chunks) => {
     const r = runPure(detectStream(stream(...chunks)));
-    if (r[0] === 'error') {
-        throw r[1];
-    }
+    assert(r[0] !== 'error', r[1]);
     return r[1];
 };
 export const proof = {

package/fjs/module.f.d.ts

@@ -0,0 +1,2 @@
+import { type NodeProgram } from './effects/node/module.f.ts';
+export declare const main: NodeProgram;

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

@@ -3,14 +3,14 @@
  *
  * @module
  */
-import { compile } from "../djs/module.f.js";
-import { main as testMain } from "../emergent_testing/module.f.js";
-import { commands as casCommands } from "../cas/cli/module.f.js";
-import { main as ciMain } from "../ci/module.f.js";
-import { import_ } from "../effects/node/module.f.js";
-import { dispatch } from "../cli/module.f.js";
-import { casMcpServer } from "../cas/mcp/module.f.js";
-import { pure } from "../effects/module.f.js";
+import { compile } from './djs/module.f.js';
+import { main as testMain } from './emergent_testing/module.f.js';
+import { commands as casCommands } from './cas/cli/module.f.js';
+import { main as ciMain } from './ci/module.f.js';
+import { import_ } from './effects/node/module.f.js';
+import { dispatch } from './cli/module.f.js';
+import { casMcpServer } from './cas/mcp/module.f.js';
+import { pure } from './effects/module.f.js';
 const commands = [
     {
         names: ['test', 't'],
@@ -29,7 +29,7 @@ const commands = [
     },
     {
         names: ['mcp', 'm'],
-        description: 'Run an MCP server over stdio exposing the CAS as tools',
+        description: 'Run an MCP server over stdio exposing the CAS and Evo (subjects/heads) as tools',
         handler: ({ home }) => casMcpServer(home).step(() => pure(0)),
     },
     {

package/fjs/module.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from './module.f.js';
+import { run } from './effects/node/module.js';
+await run(main);

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

@@ -1,5 +1,5 @@
-import { fold, last, take, length, concat as listConcat, toArray } from "../types/list/module.f.js";
-import { join as listJoin, concat as stringConcat } from "../types/string/module.f.js";
+import { fold, last, take, length, concat as listConcat, toArray } from '../types/list/module.f.js';
+import { join as listJoin, concat as stringConcat } from '../types/string/module.f.js';
 const foldNormalizeOp = input => state => {
     switch (input) {
         case '':

package/{fs → fjs}/path/proof.f.js

@@ -1,170 +1,119 @@
 import { concat, isProperPrefix, join, normalize, relativize, toPosix } from "./module.f.js";
+import { assertEq } from '../asserts/module.f.js';
 const normalizeTest = [
     () => {
         const norm = normalize("dir/file.json");
-        if (norm !== "dir/file.json") {
-            throw norm;
-        }
+        assertEq(norm, "dir/file.json");
     },
     () => {
         const norm = normalize("dir//file.json");
-        if (norm !== "dir/file.json") {
-            throw norm;
-        }
+        assertEq(norm, "dir/file.json");
     },
     () => {
         const norm = normalize("../../dir/file.json");
-        if (norm !== "../../dir/file.json") {
-            throw norm;
-        }
+        assertEq(norm, "../../dir/file.json");
     },
     () => {
         const norm = normalize("../../dir/../file.json");
-        if (norm !== "../../file.json") {
-            throw norm;
-        }
+        assertEq(norm, "../../file.json");
     },
 ];
 const concatTest = [
     () => {
         const c = concat("a")("b");
-        if (c !== "a/b") {
-            throw c;
-        }
+        assertEq(c, "a/b");
     },
     () => {
         const c = concat("a///b/")("c");
-        if (c !== "a/b/c") {
-            throw c;
-        }
+        assertEq(c, "a/b/c");
     },
     () => {
         const c = concat("a/../b/..")("c");
-        if (c !== "c") {
-            throw c;
-        }
+        assertEq(c, "c");
     },
 ];
 const joinTest = [
     () => {
         const r = join('a', 'b');
-        if (r !== 'a/b') {
-            throw r;
-        }
+        assertEq(r, 'a/b');
     },
     () => {
         const r = join('/abs/root', 'x');
-        if (r !== '/abs/root/x') {
-            throw r;
-        }
+        assertEq(r, '/abs/root/x');
     },
     () => {
         const r = join('a', 'b', 'c', 'd');
-        if (r !== 'a/b/c/d') {
-            throw r;
-        }
+        assertEq(r, 'a/b/c/d');
     },
     () => {
         const r = join('', 'x');
-        if (r !== '/x') {
-            throw r;
-        }
+        assertEq(r, '/x');
     },
     () => {
         const r = join();
-        if (r !== '') {
-            throw r;
-        }
+        assertEq(r, '');
     },
     () => {
         const r = join('only');
-        if (r !== 'only') {
-            throw r;
-        }
+        assertEq(r, 'only');
     },
 ];
 const relativizeTest = [
     () => {
         const r = relativize('/repo', '/repo/fs/a.ts');
-        if (r !== './fs/a.ts') {
-            throw r;
-        }
+        assertEq(r, './fs/a.ts');
     },
     () => {
         const r = relativize('/repo', '/other/a.ts');
-        if (r !== '/other/a.ts') {
-            throw r;
-        }
+        assertEq(r, '/other/a.ts');
     },
     () => {
         const r = relativize('', './fs/a.ts');
-        if (r !== './fs/a.ts') {
-            throw r;
-        }
+        assertEq(r, './fs/a.ts');
     },
 ];
 const toPosixTest = [
     () => {
         const p = toPosix('a\\b\\c');
-        if (p !== 'a/b/c') {
-            throw p;
-        }
+        assertEq(p, 'a/b/c');
     },
     () => {
         const p = toPosix('a/b/c');
-        if (p !== 'a/b/c') {
-            throw p;
-        }
+        assertEq(p, 'a/b/c');
     },
     () => {
         const p = toPosix('C:\\Users\\x');
-        if (p !== 'C:/Users/x') {
-            throw p;
-        }
+        assertEq(p, 'C:/Users/x');
     },
     () => {
         const p = toPosix('');
-        if (p !== '') {
-            throw p;
-        }
+        assertEq(p, '');
     },
 ];
 const isProperPrefixTest = [
     () => {
         const r = isProperPrefix(['a', 'b'], ['a', 'b', 'c']);
-        if (r !== true) {
-            throw r;
-        }
+        assertEq(r, true);
     },
     () => {
         const r = isProperPrefix(['a', 'b'], ['a', 'b']);
-        if (r !== false) {
-            throw r;
-        }
+        assertEq(r, false);
     },
     () => {
         const r = isProperPrefix(['a', 'x'], ['a', 'b', 'c']);
-        if (r !== false) {
-            throw r;
-        }
+        assertEq(r, false);
     },
     () => {
         const r = isProperPrefix(['a', 'b', 'c'], ['a', 'b']);
-        if (r !== false) {
-            throw r;
-        }
+        assertEq(r, false);
     },
     () => {
         const r = isProperPrefix([], ['a']);
-        if (r !== true) {
-            throw r;
-        }
+        assertEq(r, true);
     },
     () => {
         const r = isProperPrefix([], []);
-        if (r !== false) {
-            throw r;
-        }
+        assertEq(r, false);
     },
 ];
 export const proof = { normalizeTest, concatTest, joinTest, relativizeTest, toPosixTest, isProperPrefixTest };

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

@@ -1,7 +1,7 @@
-import { assert, assertEq } from "../asserts/module.f.js";
-import { pure } from "../effects/module.f.js";
-import { defaultNodeProgramOptions, emptyState, virtual } from "../effects/node/virtual/module.f.js";
-import { main } from "./module.f.js";
+import { assert, assertEq } from './asserts/module.f.js';
+import { pure } from './effects/module.f.js';
+import { defaultNodeProgramOptions, emptyState, virtual } from './effects/node/virtual/module.f.js';
+import { main } from './module.f.js';
 const makeOptions = (args) => ({ ...defaultNodeProgramOptions, args });
 const run = (root) => (args) => virtual({ ...emptyState, root })(main(makeOptions(args)));
 const appMain = ({ args }) => pure(args.length);
@@ -25,6 +25,8 @@ export const proof = {
     mcp: () => {
         // stdin is empty in the virtual environment, so the server sees EOF
         // immediately and shuts down cleanly, exercising the `mcp` handler.
+        // The store is empty too, so `casMcpServer`'s Evo cache scan
+        // (`initEvo`) also runs and finds nothing.
         const [, code] = run({})(['mcp']);
         assertEq(code, 0);
     },