functionalscript 0.43.1 → 0.45.0

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

@@ -0,0 +1,157 @@
+/**
+ * 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.mjs))
+ * 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.mjs)) 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}). Alongside them it records
+ * which of the seen revisions are `archived`, so {@link Evo.list} can classify
+ * a subject as active or archived from its heads' flags
+ * ({@link subjectListed}) without touching the store. 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 { Effect, Operation } from '../../effects/types.ts'
+ * @import { Key, MemOp } from '../../effects/memory/types.ts'
+ * @import { Cas } from '../types.ts'
+ * @import { Ok, Result } from '../../types/result/types.ts'
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { IoResult } from '../../effects/node/types.ts'
+ * @import { List } from '../../effects/list/types.ts'
+ * @import { LockMap, Revision } from '../../media/revision/types.ts'
+ * @import { Hash, Subject, RevisionData, SubjectState, Cache, Evo } from './types.ts'
+ */
+import type { Effect, Operation } from '../../effects/types.ts';
+import type { Key, MemOp } from '../../effects/memory/types.ts';
+import type { Cas } from '../types.ts';
+import type { Result } from '../../types/result/types.ts';
+import type { Vec } from '../../types/bit_vec/types.ts';
+import type { Revision } from '../../media/revision/types.ts';
+import type { Hash, RevisionData, Cache, Evo } from './types.ts';
+/** 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.
+ * @type {(value: Vec) => Revision | null}
+ */
+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.
+ *
+ * @template {Operation} O
+ * @param {Cas<O>} cas
+ * @returns {(hash: Vec) => Effect<O, Revision | null>}
+ */
+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.
+ *
+ * @template {Operation} O
+ * @param {Cas<O>} cas
+ * @returns {Effect<O, Cache>}
+ */
+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}.
+ *
+ * @template {Operation} O
+ * @param {Cas<O>} cas
+ * @returns {Effect<O | MemOp, Key<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/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.
+ * @type {(cacheKey: Key<Cache>) => (hash: Vec) => (value: Vec) => Effect<MemOp, void>}
+ */
+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}), derive
+ * the revision to store from them ({@link buildRevision}), then encode it,
+ * write it to `cas`, and fold it 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.
+ *
+ * @template {Operation} O
+ * @param {Cas<O>} cas
+ * @returns {(cacheKey: Key<Cache>) => (input: RevisionData) => Effect<O | MemOp, Result<Hash, string>>}
+ */
+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}).
+ *
+ * @template {Operation} O
+ * @param {Cas<O>} cas
+ * @returns {(hash: Hash) => Effect<O, Result<RevisionData, string>>}
+ */
+export declare const readRevision: <O extends Operation>(cas: Cas<O>) => (hash: Hash) => Effect<O, Result<RevisionData, string>>;
+/**
+ * Builds the {@link Evo} API over `cas`, backed by the cache at `cacheKey` (see {@link initEvo}).
+ *
+ * @template {Operation} O
+ * @param {Cas<O>} cas
+ * @returns {(cacheKey: Key<Cache>) => Evo<O>}
+ */
+export declare const evo: <O extends Operation>(cas: Cas<O>) => (cacheKey: Key<Cache>) => Evo<O>;