functionalscript 0.37.0 → 0.39.0

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

@@ -0,0 +1,126 @@
+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'; },
+            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);
+        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_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: () => {
+        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,202 @@
+/**
+ * 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.
+ *
+ * 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';
+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;
+/**
+ * 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 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
+ * 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`.
+ *
+ * `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 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. */
+    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: 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>;