functionalscript 0.45.0 → 0.46.1

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

@@ -2,6 +2,7 @@
  * @import { NodeProgramOptions } from '../../effects/node/types.ts'
  */
 
+import { exitCode } from '../../effects/node/module.f.mjs'
 import { commands } from './module.f.mjs'
 import { computeSync, sha256 } from '../../crypto/sha2/module.f.mjs'
 import { maxLength, vec, vec8 } from '../../types/bit_vec/module.f.mjs'
@@ -20,8 +21,8 @@ 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])
+        const [finalState, code] = virtual(state)(main(makeOptions(['add', 'myfile'])))
+        assertEq(exitCode(code), 0, ['expected exit 0', code])
         assert(finalState.stdout.length !== 0, 'expected hash in stdout')
     },
     mainAddGetBig: () => {
@@ -29,8 +30,8 @@ export const proof = {
         const content = [chunk, chunk]
         const state = { ...emptyState, root: { myfile: content } }
         //
-        const [finalState, exitCode] = virtual(state)(main(makeOptions(['add', 'myfile'])))
-        assertEq(exitCode, 0)
+        const [finalState, code] = virtual(state)(main(makeOptions(['add', 'myfile'])))
+        assertEq(exitCode(code), 0)
         const stdout = finalState.stdout
         assert(stdout.length !== 0)
         //
@@ -40,32 +41,33 @@ export const proof = {
         //
         const [finalState2, exitCode2] = virtual(finalState)(main(makeOptions(['get', hs, 'myfile2'])))
         // console.log(finalState2.stderr)
-        assertEq(exitCode2, 0, 'e2')
+        assertEq(exitCode(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)
+        const [finalState, code] = virtual(emptyState)(main(makeOptions(['add'])))
+        assertEq(exitCode(code), 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)
+        // The source path doesn't exist, so `streamFile`'s first read comes back as a
+        // stream failure; `write` fails closed with that error and the handler exits 1
+        // without ever calling `log` — covers `exitStep`'s error branch.
+        const [finalState, code] = virtual(emptyState)(main(makeOptions(['add', 'missing'])))
+        assertEq(exitCode(code), 1)
+        assertEq(finalState.stderr, 'no such file or directory\n', finalState.stderr)
     },
     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])
+        assertEq(exitCode(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])
+        assertEq(exitCode(exitCode2), 0, ['expected get exit 0', exitCode2])
     },
     mainGetNotFound: () => {
         // valid cBase32 hash that has not been stored
@@ -74,47 +76,56 @@ export const proof = {
         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')
+        const [finalState, code] = virtual(emptyState)(main(makeOptions(['get', hashStr, 'output'])))
+        assertEq(exitCode(code), 1, ['expected exit 1', code])
+        // The *message*, not just a non-empty line: the failure reaches the user
+        // as the host's own words. Asserting only that something was written is
+        // what let a stringified error tuple (`ioError,[object Object]`) pass.
+        assertEq(finalState.stderr, 'no such file or directory\n', finalState.stderr)
     },
     mainGetWrongArgs: () => {
-        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['get'])))
-        assertEq(exitCode, 1, ['expected exit 1', exitCode])
+        const [finalState, code] = virtual(emptyState)(main(makeOptions(['get'])))
+        assertEq(exitCode(code), 1, ['expected exit 1', code])
         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])
+        const [finalState, code] = virtual(emptyState)(main(makeOptions(['get', 'not-a-valid-hash', 'output'])))
+        assertEq(exitCode(code), 1, ['expected exit 1', code])
         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])
+        const [, code] = virtual(state1)(main(makeOptions(['list'])))
+        assertEq(exitCode(code), 0, ['expected exit 0', code])
     },
     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])
+        const [finalState, code] = virtual(emptyState)(main(makeOptions(['list'])))
+        assertEq(exitCode(code), 0, ['expected exit 0', code])
         assertEq(finalState.stdout, '', ['expected empty stdout', finalState.stdout])
     },
     mainNoCmd: () => {
-        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions([])))
-        assertEq(exitCode, 1, ['expected exit 1', exitCode])
+        const [finalState, code] = virtual(emptyState)(main(makeOptions([])))
+        assertEq(exitCode(code), 1, ['expected exit 1', code])
         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])
+        const [finalState, code] = virtual(emptyState)(main(makeOptions(['bogus'])))
+        assertEq(exitCode(code), 1, ['expected exit 1', code])
         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']))),
+    // `.cas` exists but is a file, not a directory: a real storage error that
+    // must surface, not be masked as an empty list. It is no longer a panic
+    // either — `list` answers with the error and the CLI reports it on stderr
+    // and exits 1, which is why this is an ordinary proof rather than a
+    // `throw` one.
+    mainListCorruptStore: () => {
+        const [state, code] = virtual({ ...emptyState, root: { '.cas': [vec8(0x2An)] } })(main(makeOptions(['list'])))
+        assertEq(exitCode(code), 1)
+        assert(state.stderr !== '', ['expected the storage error reported on stderr', state.stderr])
+        assertEq(state.stdout, '')
     },
 }

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,9 +141,9 @@ 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`.
  *
@@ -126,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
@@ -144,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}).
  *