functionalscript 0.43.1 → 0.44.0

package/fjs/cas/cli/proof.f.js

@@ -1,112 +0,0 @@
-import { commands } from './module.f.js';
-import { computeSync, sha256 } from '../../crypto/sha2/module.f.js';
-import { maxLength, vec, vec8 } from '../../types/bit_vec/module.f.js';
-import { defaultNodeProgramOptions, emptyState, virtual } from '../../effects/node/virtual/module.f.js';
-import {} from '../../effects/node/module.f.js';
-import { dispatch } from '../../cli/module.f.js';
-import { vecToCBase32 } from '../../basen/cbase32/module.f.js';
-import { assert, assertEq } from '../../asserts/module.f.js';
-const makeOptions = (args) => ({ ...defaultNodeProgramOptions, args });
-const main = dispatch(commands);
-export const proof = {
-    mainAdd: () => {
-        const content = vec8(0x2an);
-        const state = { ...emptyState, root: { myfile: [content] } };
-        const [finalState, exitCode] = virtual(state)(main(makeOptions(['add', 'myfile'])));
-        assertEq(exitCode, 0, ['expected exit 0', exitCode]);
-        assert(finalState.stdout.length !== 0, 'expected hash in stdout');
-    },
-    mainAddGetBig: () => {
-        const chunk = vec(maxLength)(1n);
-        const content = [chunk, chunk];
-        const state = { ...emptyState, root: { myfile: content } };
-        //
-        const [finalState, exitCode] = virtual(state)(main(makeOptions(['add', 'myfile'])));
-        assertEq(exitCode, 0);
-        const stdout = finalState.stdout;
-        assert(stdout.length !== 0);
-        //
-        const h = computeSync(sha256)(content);
-        const hs = vecToCBase32(h);
-        assertEq(stdout, `${hs}\n`);
-        //
-        const [finalState2, exitCode2] = virtual(finalState)(main(makeOptions(['get', hs, 'myfile2'])));
-        // console.log(finalState2.stderr)
-        assertEq(exitCode2, 0, 'e2');
-        const { myfile2 } = finalState2.root;
-        assert(myfile2 instanceof Array);
-        const h2 = computeSync(sha256)(myfile2);
-        assertEq(h, h2, 'h');
-    },
-    mainAddWrongArgs: () => {
-        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['add'])));
-        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'])));
-        assertEq(exitCode1, 0, ['expected add exit 0', exitCode1]);
-        const hashStr = state1.stdout.trim();
-        const [, exitCode2] = virtual(state1)(main(makeOptions(['get', hashStr, 'output'])));
-        assertEq(exitCode2, 0, ['expected get exit 0', exitCode2]);
-    },
-    mainGetNotFound: () => {
-        // valid cBase32 hash that has not been stored
-        const content = vec8(0x2an);
-        const state = { ...emptyState, root: { myfile: [content] } };
-        const [state1] = virtual(state)(main(makeOptions(['add', 'myfile'])));
-        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'])));
-        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'])));
-        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'])));
-        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'])));
-        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'])));
-        assertEq(exitCode, 0, ['expected exit 0', exitCode]);
-        assertEq(finalState.stdout, '', ['expected empty stdout', finalState.stdout]);
-    },
-    mainNoCmd: () => {
-        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions([])));
-        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'])));
-        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/module.f.d.ts

@@ -1,223 +0,0 @@
-/**
- * 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}). 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 { 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 LockMap, 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;
-    readonly lock?: LockMap | undefined;
-};
-/**
- * Per-subject bookkeeping: every revision hash seen for the subject, every
- * hash any of those revisions names as a parent, and which of the seen
- * revisions are `archived`. See the module doc for why the first two sets are
- * kept (rather than a running head list), {@link headsOf} for how heads are
- * derived from them, and {@link subjectListed} for how `archived` classifies a
- * subject once its heads are known.
- *
- * `archived` is keyed by revision hash, not by subject, for the same reason
- * heads are computed at read time: which revisions are heads is only known
- * once the whole store has been folded in, so a per-subject archived flag
- * would have to be revised every time a later fold changes the head set.
- */
-export type SubjectState = {
-    readonly hashes: readonly Hash[];
-    readonly parents: readonly Hash[];
-    readonly archived: readonly Hash[];
-};
-/** In-memory index: subject → its {@link SubjectState}. */
-export type Cache = {
-    readonly bySubject: StringMap<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/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 the subjects matching a status filter: the active ones by
-     * default, the archived ones when `archived` is `true`. A subject's status
-     * is derived from its current heads — see {@link subjectListed}, which
-     * also explains why a subject with no current heads is in neither result.
-     *
-     * There is deliberately no all-subjects mode: nothing needs one yet, and
-     * adding it later is a compatible extension of this parameter, while
-     * removing it would not be.
-     */
-    readonly list: (archived?: true) => 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>;