functionalscript 0.45.0 → 0.46.0

package/fjs/cas/evo/module.f.mjs

@@ -42,18 +42,29 @@
  *
  * @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 { pure, foldStep, mapStep, step } from '../../effects/module.f.mjs'
+import {
+    catchStep,
+    foldStep as ioFoldStep,
+    mapStep as ioMapStep,
+    pureError,
+    pureOk,
+    resultMapStep,
+    step as ioStep,
+} from '../../effects/module.f.mjs'
 import { create, read, write } from '../../effects/memory/module.f.mjs'
 import { collectRead } from '../module.f.mjs'
 import { cBase32ToVec, vecToCBase32 } from '../../basen/cbase32/module.f.mjs'
@@ -63,11 +74,33 @@ import { ok, error, okThen } from '../../types/result/module.f.mjs'
 import { nonEmpty, empty as elEmpty } from '../../effects/list/module.f.mjs'
 import { at, definedEntries } from '../../types/object/module.f.mjs'
 import { unwrap } from '../../types/nullable/module.f.mjs'
-import { isNotFound } from '../../effects/node/module.f.mjs'
+import { errorSummary, isNotFound } from '../../effects/node/module.f.mjs'
 import { decodeText, encodeText, dialect, checkReferences, isHash } from '../../media/revision/module.f.mjs'
 
+/**
+ * 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 const evoError = message => ['evoError', message]
+
+/**
+ * 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 const evoSummary = e => e[0] === 'evoError' ? e[1] : errorSummary(e)
+
 /** A cache with no known subjects yet — the starting point for {@link buildCache}. */
-export const emptyCache = /** @type {Cache} */ ({ bySubject: {} })
+/** @type {Cache} */
+export const emptyCache = { bySubject: {} }
 
 /** @type {SubjectState} */
 const emptySubjectState = { hashes: [], parents: [], archived: [] }
@@ -93,11 +126,26 @@ const union = set => items =>
  */
 const canonicalHash = h => vecToCBase32(unwrap(cBase32ToVec(h)))
 
-/** Canonicalizes every direct hash in a structurally validated flat lock map.
+/**
+ * Canonicalizes every direct hash of a structurally validated lock map, at
+ * every depth, preserving its nested scope structure. Nested maps are scopes
+ * rather than references, so only the strings are re-spelled — the same split
+ * `fjs/media/revision`'s `checkReferences` validates along.
  * @type {(lock: LockMap) => LockMap}
  */
 const canonicalLock = lock =>
-    Object.fromEntries(definedEntries(lock).map(([subject, hash]) => [subject, canonicalHash(hash)]))
+    Object.fromEntries(definedEntries(lock).map(
+        ([subject, value]) => [subject, typeof value === 'string' ? canonicalHash(value) : canonicalLock(value)]))
+
+/**
+ * Canonicalizes a revision's `lock` field: a shared-lock reference is one hash
+ * to re-spell, an inline map is walked to the bottom ({@link canonicalLock}).
+ * The split is the same one `fjs/media/revision`'s `lockFieldError` validates
+ * along, so what this re-spells is exactly what was checked.
+ * @type {(value: LockField) => LockField}
+ */
+const canonicalLockField = value =>
+    typeof value === 'string' ? canonicalHash(value) : canonicalLock(value)
 
 /** A subject's current heads: revision hashes seen that no other revision of the same subject names as a parent.
  * @type {(state: SubjectState) => readonly Hash[]}
@@ -181,46 +229,62 @@ export const decodeRevisionVec = value => {
  *
  * @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 const decodeRevisionBlob = cas => hash =>
-    mapStep(
+    resultMapStep(
         collectRead(cas.read(hash)),
-        ([tag, value]) => tag === 'error' ? null : decodeRevisionVec(value))
+        ([tag, value]) => ok(tag === 'error' ? null : decodeRevisionVec(value)))
 
 /**
  * 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 const buildCache = cas =>
-    foldStep(
-        cas.list(),
-        emptyCache,
-        hash => cache =>
-            mapStep(
-                decodeRevisionBlob(cas)(hash),
-                revision =>
-                    revision === null ? cache : addRevisionToCache(vecToCBase32(hash), revision)(cache)))
+export const buildCache = cas => {
+    // Annotated rather than inferred: the body's `ok(…)` is an `Ok<Cache>`,
+    // which unifies with `Result<S, E>` for any `E`, so the fold's error type
+    // has nothing to pin it and drifts into the accumulator's.
+    /** @type {(hash: Vec) => (cache: Cache) => Effect<O, Cache, IoChannel>} */
+    const foldOne = hash => cache =>
+        ioMapStep(
+            decodeRevisionBlob(cas)(hash),
+            revision =>
+                revision === null ? cache : addRevisionToCache(vecToCBase32(hash), revision)(cache))
+    return ioStep(cas.list(), hashes => ioFoldStep(pureOk(hashes), emptyCache, foldOne))
+}
 
 /**
  * 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 const initEvo = cas =>
-    step(buildCache(cas), cache => create(cache))
+    ioStep(buildCache(cas), cache => create(cache))
 
 /** Reads, then rewrites, the cache at `cacheKey` with `revision` folded in at `hash`.
- * @type {(cacheKey: Key<Cache>) => (hash: Hash) => (revision: Revision) => Effect<MemOp, void>}
+ * @type {(cacheKey: Key<Cache>) => (hash: Hash) => (revision: Revision) => Effect<MemOp, void, NotImplemented>}
  */
 const foldIntoCache = cacheKey => hash => revision =>
-    step(read(cacheKey), cache => write(cacheKey, addRevisionToCache(hash, revision)(cache)))
+    ioStep(
+        read(cacheKey),
+        cache => write(cacheKey, addRevisionToCache(hash, revision)(cache)))
 
 /**
  * Folds `value` — bytes already written to a `Cas` at `hash` by some other
@@ -230,11 +294,11 @@ const foldIntoCache = cacheKey => hash => revision =>
  * 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 const syncRevision = cacheKey => hash => value => {
     const revision = decodeRevisionVec(value)
-    return revision === null ? pure(undefined) : foldIntoCache(cacheKey)(vecToCBase32(hash))(revision)
+    return revision === null ? pureOk(undefined) : foldIntoCache(cacheKey)(vecToCBase32(hash))(revision)
 }
 
 /**
@@ -246,39 +310,39 @@ export const syncRevision = cacheKey => hash => value => {
  *
  * @template {Operation} O
  * @param {Cas<O>} cas
- * @returns {(parentRef: Hash) => Effect<O, Result<Revision, string>>}
+ * @returns {(parentRef: Hash) => Effect<O, Revision, EvoError>}
  */
 const resolveParent = cas => parentRef => {
     const parentHash = cBase32ToVec(parentRef)
     if (parentHash === null) {
-        return pure(error(`invalid parent hash: ${parentRef}`))
+        return pureError(evoError(`invalid parent hash: ${parentRef}`))
     }
-    return mapStep(
+    return ioStep(
         decodeRevisionBlob(cas)(parentHash),
-        parent => parent === null ? error(`parent is not a revision blob: ${parentRef}`) : ok(parent))
+        parent => parent === null
+            ? pureError(evoError(`parent is not a revision blob: ${parentRef}`))
+            : pureOk(parent))
 }
 
 /**
  * Resolves and validates every entry of `parents`, in order, short-circuiting on the first failure.
  *
+ * Short-circuiting is `foldStep`'s, not this function's. It used to be
+ * two hand-written `[0] === 'error'` tests, which is what a verdict costs when
+ * it rides in the value instead of the channel.
+ *
  * @template {Operation} O
  * @param {Cas<O>} cas
- * @returns {(parents: readonly Hash[]) => Effect<O, Result<readonly Revision[], string>>}
+ * @returns {(parents: readonly Hash[]) => Effect<O, readonly Revision[], EvoError>}
  */
 const resolveParents = cas => parents => {
-    /** @type {Result<readonly Revision[], string>} */
-    const init = ok([])
-    return foldStep(
-        pure(parents),
+    /** @type {readonly Revision[]} */
+    const init = []
+    return ioFoldStep(
+        pureOk(parents),
         init,
-        parentRef => (/** @type {Result<readonly Revision[], string>} */ acc) => {
-            if (acc[0] === 'error') { return pure(acc) }
-            return mapStep(
-                resolveParent(cas)(parentRef),
-                (/** @type {Result<Revision, string>} */ parentResult) =>
-                    /** @type {Result<readonly Revision[], string>} */
-                    (parentResult[0] === 'error' ? parentResult : ok([...acc[1], parentResult[1]])))
-        })
+        parentRef => (/** @type {readonly Revision[]} */ acc) =>
+            ioMapStep(resolveParent(cas)(parentRef), parent => [...acc, parent]))
 }
 
 /**
@@ -410,7 +474,7 @@ const buildRevision = input => parents => {
         ...revision,
         parents: revision.parents.map(canonicalHash),
         snapshot: canonicalHash(revision.snapshot),
-        lock: revision.lock === undefined ? undefined : canonicalLock(revision.lock),
+        lock: revision.lock === undefined ? undefined : canonicalLockField(revision.lock),
     })
 }
 
@@ -432,27 +496,41 @@ const buildRevision = input => parents => {
  *
  * @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 const addRevision = cas => cacheKey => input =>
-    step(
+    ioStep(
         resolveParents(cas)(input.parents),
-        (/** @type {Result<readonly Revision[], string>} */ parentsResult) => {
-            const revisionResult = okThen(buildRevision(input))(parentsResult)
-            if (revisionResult[0] === 'error') { return pure(revisionResult) }
+        (/** @type {readonly Revision[]} */ parents) => {
+            const revisionResult = buildRevision(input)(parents)
+            if (revisionResult[0] === 'error') { return pureError(evoError(revisionResult[1])) }
             const canonicalRevision = revisionResult[1]
             const bytes = tryUtf8(encodeText(canonicalRevision))
             if (bytes === null) {
-                return pure(error('revision too large to encode'))
+                return pureError(evoError('revision too large to encode'))
             }
-            return step(
-                cas.write(nonEmpty(ok(bytes), /** @type {List<never, Ok<Vec>>} */ (elEmpty()))),
-                (/** @type {IoResult<Vec>} */ writeResult) => {
-                    if (writeResult[0] === 'error') {
-                        return /** @type {Effect<MemOp, Result<Hash, string>>} */ (pure(error('failed to write revision to CAS')))
-                    }
-                    const hash = vecToCBase32(writeResult[1])
-                    return mapStep(foldIntoCache(cacheKey)(hash)(canonicalRevision), () => ok(hash))
+            // Annotated so the payload's operation set infers as `never`: the
+            // list is built from `pure` cells and requests no commands of its
+            // own, which `cas.write`'s `O1` has nothing else to pin it to.
+            /** @type {Effect<O, Vec, EvoError>} */
+            const written = catchStep(
+                cas.write((nonEmpty(bytes, elEmpty()))),
+                () => pureError(evoError('failed to write revision to CAS')))
+            return ioStep(
+                written,
+                (/** @type {Vec} */ writtenHash) => {
+                    const hash = vecToCBase32(writtenHash)
+                    return ioMapStep(foldIntoCache(cacheKey)(hash)(canonicalRevision), () => hash)
                 })
         })
 
@@ -474,7 +552,7 @@ const toRevisionData = ({ subject, parents, snapshot, generation, archived, lock
     snapshot: canonicalHash(snapshot),
     generation,
     archived,
-    lock: lock === undefined ? undefined : canonicalLock(lock),
+    lock: lock === undefined ? undefined : canonicalLockField(lock),
 })
 
 /**
@@ -501,17 +579,17 @@ const toRevisionData = ({ subject, parents, snapshot, generation, archived, lock
  * how far it got; recovering that difference would mean folding the chunk
  * stream here instead of reusing `collectRead`, for a distinction no client
  * can act on differently.
- * @type {(hash: Hash) => (result: IoResult<Vec>) => Result<RevisionData, string>}
+ * @type {(hash: Hash) => (result: IoResult<Vec>) => Result<RevisionData, EvoError>}
  */
 const decodeReadRevision = hash => ([tag, value]) => {
     if (tag === 'error') {
-        return error(isNotFound(value)
+        return error(evoError(isNotFound(value)
             ? `revision not found: ${hash}`
-            : `failed to read revision: ${hash}`)
+            : `failed to read revision: ${hash}`))
     }
     const revision = decodeRevisionVec(value)
     return revision === null
-        ? error(`not a revision blob: ${hash}`)
+        ? error(evoError(`not a revision blob: ${hash}`))
         : ok(toRevisionData(revision))
 }
 
@@ -530,13 +608,13 @@ const decodeReadRevision = hash => ([tag, value]) => {
  *
  * @template {Operation} O
  * @param {Cas<O>} cas
- * @returns {(hash: Hash) => Effect<O, Result<RevisionData, string>>}
+ * @returns {(hash: Hash) => Effect<O, RevisionData, EvoError>}
  */
 export const readRevision = cas => hash => {
     const hashVec = cBase32ToVec(hash)
     return hashVec === null
-        ? pure(error(`invalid hash: ${hash}`))
-        : mapStep(collectRead(cas.read(hashVec)), decodeReadRevision(hash))
+        ? pureError(evoError(`invalid hash: ${hash}`))
+        : resultMapStep(collectRead(cas.read(hashVec)), decodeReadRevision(hash))
 }
 
 /**
@@ -549,12 +627,12 @@ export const readRevision = cas => hash => {
 export const evo = cas => cacheKey => ({
     list: archived => {
         const listed = subjectListed(archived)
-        return mapStep(
+        return ioMapStep(
             read(cacheKey),
             cache => definedEntries(cache.bySubject)
                 .flatMap(([subject, state]) => listed(state) ? [subject] : []))
     },
-    head: subject => mapStep(read(cacheKey), cache => {
+    head: subject => ioMapStep(read(cacheKey), cache => {
         const state = at(subject)(cache.bySubject)
         return state === null ? [] : headsOf(state)
     }),

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

@@ -1,8 +1,12 @@
 /**
  * @import { Cas } from '../types.ts'
+ * @import { EvoChannel } from './types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { Effect } from '../../effects/types.ts'
+ * @import { IoChannel, NodeOp } from '../../effects/node/types.ts'
+ * @import { State } from '../../effects/node/virtual/types.ts'
  * @import { Vec } from '../../types/bit_vec/types.ts'
  * @import { Ok } from '../../types/result/types.ts'
- * @import { IoResult } from '../../effects/node/types.ts'
  * @import { List } from '../../effects/list/types.ts'
  * @import { RevisionData } from './types.ts'
  */
@@ -44,9 +48,14 @@ export declare const proof: {
     revisionCanonicalizesReferenceSpellings: () => void;
     revisionRoundTripsThroughAdd: () => void;
     revisionLockRoundTripsAndCanonicalizes: () => void;
+    revisionSharedLockReferenceRoundTripsAndCanonicalizes: () => void;
+    revisionInvalidSharedLockReferenceIsRejected: () => void;
+    revisionNestedLockRoundTripsAndCanonicalizes: () => void;
+    revisionInvalidNestedLockValueIsRejected: () => void;
     revisionAbsentAndEmptyLocksRemainDistinct: () => void;
     revisionInvalidLockValueIsRejected: () => void;
     equivalentLockOrdersReuseOneCasAddress: () => void;
+    equivalentNestedLockOrdersReuseOneCasAddress: () => void;
     syncRevisionFoldsValidRevisionIntoCache: () => void;
     syncRevisionIgnoresNonRevisionContent: () => void;
     evoHeadUnknownSubjectIsEmpty: () => void;