functionalscript 0.44.0 → 0.46.0

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

@@ -42,24 +42,49 @@
  *
  * @module
  *
- * @import { Effect, Operation } from '../../effects/types.ts'
+ * @import { Operation } from '../../effects/types.ts'
+ * @import { Effect, NotImplemented } from '../../effects/types.ts'
+ * @import { EvoChannel, EvoError } from './types.ts'
  * @import { Key, MemOp } from '../../effects/memory/types.ts'
  * @import { Cas } from '../types.ts'
- * @import { Ok, Result } from '../../types/result/types.ts'
+ * @import { Result } from '../../types/result/types.ts'
  * @import { Vec } from '../../types/bit_vec/types.ts'
- * @import { IoResult } from '../../effects/node/types.ts'
+ * @import { Ok } from '../../types/result/types.ts'
  * @import { List } from '../../effects/list/types.ts'
- * @import { LockMap, Revision } from '../../media/revision/types.ts'
+ * @import { IoChannel, IoResult } from '../../effects/node/types.ts'
+ * @import { LockField, 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 { Operation } from '../../effects/types.ts';
+import type { Effect, NotImplemented } from '../../effects/types.ts';
+import type { EvoChannel, EvoError } from './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 { IoChannel } from '../../effects/node/types.ts';
 import type { Revision } from '../../media/revision/types.ts';
 import type { Hash, RevisionData, Cache, Evo } from './types.ts';
+/**
+ * A rejected revision, tagged so it renders alongside `notImplemented` and
+ * `ioError` rather than needing a `typeof` test to be told from them.
+ *
+ * @type {(message: string) => EvoError}
+ */
+export declare const evoError: (message: string) => EvoError;
+/**
+ * Renders an {@link EvoChannel} failure as a message.
+ *
+ * The two cases are told apart by tag and nothing else — which is the whole
+ * reason {@link EvoError} is a tuple. A rejected revision already carries a
+ * message written for a caller; a runner that could not dispatch is described
+ * by `errorSummary`, the same renderer the node channel uses, so there is one
+ * phrasing of "operation not implemented" rather than two.
+ *
+ * @type {(e: EvoChannel) => string}
+ */
+export declare const evoSummary: (e: EvoChannel) => string;
 /** A cache with no known subjects yet — the starting point for {@link buildCache}. */
+/** @type {Cache} */
 export declare const emptyCache: Cache;
 /**
  * Decodes already-read bytes as a `vnd.fjs.revision`. Returns `null` for
@@ -77,26 +102,37 @@ export declare const decodeRevisionVec: (value: Vec) => Revision | null;
  *
  * @template {Operation} O
  * @param {Cas<O>} cas
- * @returns {(hash: Vec) => Effect<O, Revision | null>}
+ * The `never` is a decision, not an observation: reading the store *can* fail,
+ * and this maps that failure to `null` alongside "the bytes are not a
+ * revision". A scan wants exactly that — one unreadable blob must not fail the
+ * whole cache build — but the two are genuinely different answers, and this
+ * one loses the difference on purpose. Saying `never` puts that where a reader
+ * can disagree with it.
+ *
+ * @returns {(hash: Vec) => Effect<O, Revision | null, never>}
  */
-export declare const decodeRevisionBlob: <O extends Operation>(cas: Cas<O>) => (hash: Vec) => Effect<O, Revision | null>;
+export declare const decodeRevisionBlob: <O extends Operation>(cas: Cas<O>) => (hash: Vec) => Effect<O, Revision | null, never>;
 /**
  * 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.
  *
+ * A store that cannot be listed is a failure of the scan, not an empty cache:
+ * the fold never starts, and the caller is told. Blobs that fail to *read*
+ * remain "not a revision" and are skipped — see {@link decodeRevisionBlob}.
+ *
  * @template {Operation} O
  * @param {Cas<O>} cas
- * @returns {Effect<O, Cache>}
+ * @returns {Effect<O, Cache, IoChannel>}
  */
-export declare const buildCache: <O extends Operation>(cas: Cas<O>) => Effect<O, Cache>;
+export declare const buildCache: <O extends Operation>(cas: Cas<O>) => Effect<O, Cache, IoChannel>;
 /**
  * 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>>}
+ * @returns {Effect<O | MemOp, Key<Cache>, IoChannel>}
  */
-export declare const initEvo: <O extends Operation>(cas: Cas<O>) => Effect<O | MemOp, Key<Cache>>;
+export declare const initEvo: <O extends Operation>(cas: Cas<O>) => Effect<O | MemOp, Key<Cache>, IoChannel>;
 /**
  * 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`
@@ -105,25 +141,19 @@ export declare const initEvo: <O extends Operation>(cas: Cas<O>) => Effect<O | M
  * 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>}
+ * @type {(cacheKey: Key<Cache>) => (hash: Vec) => (value: Vec) => Effect<MemOp, void, NotImplemented>}
  */
-export declare const syncRevision: (cacheKey: Key<Cache>) => (hash: Vec) => (value: Vec) => Effect<MemOp, void>;
+export declare const syncRevision: (cacheKey: Key<Cache>) => (hash: Vec) => (value: Vec) => Effect<MemOp, void, NotImplemented>;
 /**
  * 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`.
+ * 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,
@@ -132,9 +162,19 @@ export declare const syncRevision: (cacheKey: Key<Cache>) => (hash: Vec) => (val
  *
  * @template {Operation} O
  * @param {Cas<O>} cas
- * @returns {(cacheKey: Key<Cache>) => (input: RevisionData) => Effect<O | MemOp, Result<Hash, string>>}
+ * A rejected revision and an unreachable cache slot share one channel — see
+ * {@link Evo.add} — so every branch below answers `pureError`, and the
+ * successful path never re-tests what an earlier step already decided.
+ *
+ * The `Cas` write is the one place a host failure is *translated* rather than
+ * propagated: {@link catchStep} turns any `IoChannel` error into one
+ * {@link EvoError}, because a caller of this API has the same recourse to a
+ * full disk as to a malformed parent, and the store's own error vocabulary is
+ * not part of this contract.
+ *
+ * @returns {(cacheKey: Key<Cache>) => (input: RevisionData) => Effect<O | MemOp, Hash, EvoChannel>}
  */
-export declare const addRevision: <O extends Operation>(cas: Cas<O>) => (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, Hash, EvoChannel>;
 /**
  * Reads the revision at `hash`: decoded, validated, and canonicalized
  * ({@link toRevisionData}). The typed counterpart of a raw `cas.read` — the
@@ -150,9 +190,9 @@ export declare const addRevision: <O extends Operation>(cas: Cas<O>) => (cacheKe
  *
  * @template {Operation} O
  * @param {Cas<O>} cas
- * @returns {(hash: Hash) => Effect<O, Result<RevisionData, string>>}
+ * @returns {(hash: Hash) => Effect<O, RevisionData, EvoError>}
  */
-export declare const readRevision: <O extends Operation>(cas: Cas<O>) => (hash: Hash) => Effect<O, Result<RevisionData, string>>;
+export declare const readRevision: <O extends Operation>(cas: Cas<O>) => (hash: Hash) => Effect<O, RevisionData, EvoError>;
 /**
  * Builds the {@link Evo} API over `cas`, backed by the cache at `cacheKey` (see {@link initEvo}).
  *