functionalscript 0.45.0 → 0.46.0

package/fjs/effects/node/proof.f.d.mts

@@ -1,11 +1,37 @@
 /**
  * @import { Vec } from "../../types/bit_vec/types.ts"
- * @import { IoResult, ReadFile } from "./types.ts"
- * @import { Dir } from "./virtual/types.ts"
+ * @import { IoChannel, IoError, IoResult, ReadFile } from "./types.ts"
+ * @import { Result } from "../../types/result/types.ts"
  * @import { List } from "../list/types.ts"
  * @import { OperationMap } from "../types.ts"
  */
 export declare const proof: {
+    toIoError: {
+        error: () => void;
+        withCode: () => void;
+        string: () => void;
+        null: () => void;
+        nonStringCode: () => void;
+        noCode: () => void;
+    };
+    isNotFound: {
+        enoent: () => void;
+        otherCode: () => void;
+        notImplemented: () => void;
+    };
+    errorMessage: {
+        io: () => void;
+        notImplemented: () => void;
+    };
+    errorSummary: {
+        io: () => void;
+        ioWithoutCode: () => void;
+        notImplemented: () => void;
+    };
+    exitStep: {
+        ok: () => void;
+        error: () => void;
+    };
     externalTestContext: () => void;
     map: () => void;
     fetch: () => void;

package/fjs/effects/node/proof.f.mjs

@@ -1,15 +1,16 @@
 /**
  * @import { Vec } from "../../types/bit_vec/types.ts"
- * @import { IoResult, ReadFile } from "./types.ts"
- * @import { Dir } from "./virtual/types.ts"
+ * @import { IoChannel, IoError, IoResult, ReadFile } from "./types.ts"
+ * @import { Result } from "../../types/result/types.ts"
  * @import { List } from "../list/types.ts"
  * @import { OperationMap } from "../types.ts"
  */
 
 import { empty, isVec, uint, vec, vec8 } from "../../types/bit_vec/module.f.mjs"
 import { utf8, utf8ToString } from "../../text/module.f.mjs"
-import { match, pure, step } from "../module.f.mjs"
-import { both, fetch, mkdir, now, readdir, readFile, readUtf8File, rm, sandbox, writeFile, writeUtf8File, rename, readBytes, randomInt, writeFromStream, usesInlineTestContext, versionLessThan } from "./module.f.mjs"
+import { match } from "../module.f.mjs"
+import { mapStep, step as ioStep } from "../module.f.mjs"
+import { both, errorMessage, errorSummary, exitStep, fetch, ioError, isNotFound, mkdir, now, readdir, readFile, readUtf8File, rm, sandbox, toIoError, writeFile, writeUtf8File, rename, readBytes, randomInt, writeFromStream, usesInlineTestContext, versionLessThan } from "./module.f.mjs"
 import { create as memCreate, read as memRead, write as memWrite } from "../memory/module.f.mjs"
 import { empty as listEmpty, nonEmpty as listNonEmpty } from "../list/module.f.mjs"
 import { emptyState, virtual } from "./virtual/module.f.mjs"
@@ -29,7 +30,115 @@ const readHelloMap = {
 
 const readHello = match(readHelloMap)
 
+/**
+ * Asserts that a channel error is a host failure carrying `message`. Every
+ * runner reports through the same normalized {@link IoError}, so a proof
+ * against the virtual filesystem names the message rather than the shape.
+ * @type {(e: IoChannel, message: string) => void}
+ */
+const assertIoMessage = (e, message) => {
+    assert(e[0] === 'ioError', e)
+    assertEq(e[1].message, message)
+}
+
+/** Asserts that an operation succeeded with `expected`.
+ * @type {<T, E>(r: Result<T, E>, expected: T) => void}
+ */
+const assertOk = (r, expected) => {
+    assert(r[0] === 'ok', r)
+    assertEq(r[1], expected)
+}
+
 export const proof = {
+    // The one boundary where a runner's `catch` becomes effect data: whatever
+    // was thrown is reduced to a code (when the host attached a string one)
+    // and a message.
+    toIoError: {
+        error: () => {
+            assertIoMessage(toIoError(new Error('boom')), 'boom')
+        },
+        withCode: () => {
+            const e = toIoError(Object.assign(new Error('missing'), { code: 'ENOENT' }))
+            assert(e[0] === 'ioError', e)
+            assertEq(e[1].code, 'ENOENT', e)
+            assertEq(e[1].message, 'missing', e)
+        },
+        // A thrown non-`Error` still normalizes: the value's string form is the
+        // message, and there is no code to carry.
+        string: () => {
+            const e = toIoError('plain')
+            assert(e[0] === 'ioError', e)
+            assertEq(e[1].code, undefined, e)
+            assertEq(e[1].message, 'plain', e)
+        },
+        null: () => {
+            assertIoMessage(toIoError(null), 'null')
+        },
+        // An object whose `code` is not a string is not an OS error code, so it
+        // is dropped rather than carried as one.
+        nonStringCode: () => {
+            const e = toIoError({ code: 42 })
+            assert(e[0] === 'ioError', e)
+            assertEq(e[1].code, undefined, e)
+        },
+        noCode: () => {
+            const e = toIoError({})
+            assert(e[0] === 'ioError', e)
+            assertEq(e[1].code, undefined, e)
+        },
+    },
+    isNotFound: {
+        enoent: () => {
+            assert(isNotFound(ioError({ code: 'ENOENT', message: 'no such file or directory' })))
+        },
+        otherCode: () => {
+            assert(!isNotFound(ioError({ code: 'EACCES', message: 'permission denied' })))
+        },
+        // A runner that cannot perform the operation has not looked for the
+        // path at all, so a missing handler is never "not found".
+        notImplemented: () => {
+            assert(!isNotFound(['notImplemented', 'readFile']))
+        },
+    },
+    errorMessage: {
+        io: () => {
+            assertEq(errorMessage(ioError({ message: 'disk full' })), 'disk full')
+        },
+        notImplemented: () => {
+            assertEq(errorMessage(['notImplemented', 'readFile']), 'operation not implemented: readFile')
+        },
+    },
+    errorSummary: {
+        // The distinction that matters: `errorMessage` hands back the host's
+        // words, which is where the path lives; `errorSummary` never does.
+        io: () => {
+            assertEq(errorSummary(ioError({ code: 'ENOENT', message: "no such file or directory, scandir '/home/u/.cas'" })), 'io error: ENOENT')
+        },
+        ioWithoutCode: () => {
+            assertEq(errorSummary(ioError({ message: "cannot read '/home/u/.cas'" })), 'io error')
+        },
+        notImplemented: () => {
+            assertEq(errorSummary(['notImplemented', 'readdir']), 'operation not implemented: readdir')
+        },
+    },
+    exitStep: {
+        // The exit-code policy a `NodeProgram` ends with: success is `0`...
+        ok: () => {
+            const [state, code] = virtual(emptyState)(exitStep(writeFile('hello', vec8(0x2An))))
+            assertEq(code[0], 'ok')
+            assertEq(code[1], 0)
+            assertEq(state.stderr, '')
+        },
+        // ...and a failure is reported on `stderr` and exits `1`.
+        // ...and the code is `[1]` either way, which is what lets a runner
+        // read it without asking which branch it came from.
+        error: () => {
+            const [state, code] = virtual(emptyState)(exitStep(readFile('missing')))
+            assertEq(code[0], 'error')
+            assertEq(code[1], 1)
+            assertEq(state.stderr, 'no such file or directory\n')
+        },
+    },
     externalTestContext: () => {
         assert(usesInlineTestContext('node', 'v22.20.0'))
         assert(usesInlineTestContext('node', '25.99.99'))
@@ -44,18 +153,15 @@ export const proof = {
         assert(!versionLessThan('26.1.1', '26.1.1'))
     },
     map: () => {
-        const e = step(
-            readFile('hello'),
-            ([k, v]) => {
-                assert(k !== 'error', v)
-                return pure(uint(v) * 2n)
-            })
+        const e = mapStep(readFile('hello'), v => uint(v) * 2n)
         //
         let r = readHello(e)
         while (r[0] === 'cont') {
             r = readHello(r[2](r[1]))
         }
-        assertEq(r[1], 0x2An)
+        // `done` carries the whole `Result`: an interpreter never separates the
+        // channels, so the projection's value is inside the `ok`.
+        assertEq(r[1][1], 0x2An)
     },
     fetch: () => {
         const [_, [t, result]] = virtual({
@@ -81,8 +187,11 @@ export const proof = {
             )
             assert(t === 'ok', result)
             const tmp = state.root.tmp
-            assert(!(typeof tmp !== 'object' || Array.isArray(tmp)), state.root)
-            const cache = (/** @type {Dir} */ (tmp)).cache
+            // `instanceof Array`, not `Array.isArray`: only the former's negative
+            // branch removes a `readonly` array from a union, so only it narrows
+            // `_Entity` to `Dir`.
+            assert(!(typeof tmp !== 'object' || tmp instanceof Array), state.root)
+            const cache = tmp.cache
             assert(!(typeof cache !== 'object' || Array.isArray(cache)), tmp)
         },
         nonRec: () => {
@@ -122,7 +231,8 @@ export const proof = {
         nestedPath: () => {
             const [_, [t, result]] = virtual(emptyState)(readFile('tmp/cache'))
             assert(t === 'error', result)
-            if ((/** @type {{ code?: unknown }} */ (result)).code !== 'ENOENT') { throw result }
+            assert(result[0] === 'ioError', result)
+            assertEq(result[1].code, 'ENOENT', result)
         },
         withinLimit: () => {
             // Test with a small file well within the 131,072 byte limit
@@ -197,7 +307,7 @@ export const proof = {
         noSuchDir: () => {
             const [_, [t, result]] = virtual(emptyState)(readdir('tmp', { recursive: true }))
             assert(t === 'error', result)
-            assertEq(result, 'invalid path')
+            assertIoMessage(result, 'invalid path')
         },
     },
     writeFile: {
@@ -229,7 +339,7 @@ export const proof = {
                 writeFile('tmp/cache', vec8(0x2An))
             )
             assert(t === 'error', result)
-            assertEq(result, 'invalid file')
+            assertIoMessage(result, 'invalid file')
             assertEq(state.root.tmp, undefined, state.root)
         },
         directory: () => {
@@ -242,7 +352,7 @@ export const proof = {
                 writeFile('tmp', vec8(0x2An))
             )
             assert(t === 'error', result)
-            assertEq(result, 'invalid file')
+            assertIoMessage(result, 'invalid file')
             const tmp = state.root.tmp
             assert(!(tmp === undefined || Array.isArray(tmp)), tmp)
         },
@@ -272,13 +382,13 @@ export const proof = {
             })(rm('tmp/cache'))
             assert(t === 'ok', result)
             const tmp = state.root.tmp
-            assert(!(typeof tmp !== 'object' || Array.isArray(tmp)), state.root)
-            assertEq((/** @type {Dir} */ (tmp)).cache, undefined, tmp)
+            assert(!(typeof tmp !== 'object' || tmp instanceof Array), state.root)
+            assertEq(tmp.cache, undefined, tmp)
         },
         noSuchFile: () => {
             const [_, [t, result]] = virtual(emptyState)(rm('hello'))
             assert(t === 'error', result)
-            assertEq(result, 'no such file')
+            assertIoMessage(result, 'no such file')
         },
         isDirectory: () => {
             const [state, [t, result]] = virtual({
@@ -286,18 +396,20 @@ export const proof = {
                 root: { tmp: {} },
             })(rm('tmp'))
             assert(t === 'error', result)
-            assertEq(result, 'invalid path')
+            assertIoMessage(result, 'invalid path')
             assert(state.root.tmp !== undefined, state.root)
         },
     },
     both: () => {
-        const [_, results] = virtual({
+        const [_, both2] = virtual({
             ...emptyState,
             root: {
                 a: [vec8(0x2An)],
                 b: [vec8(0x15n)],
             },
         })(both(readFile('a'))(readFile('b')))
+        assert(both2[0] === 'ok', both2)
+        const results = both2[1]
         assert(results[0][0] === 'ok', results[0])
         assert(results[1][0] === 'ok', results[1])
         assertEq(uint(results[0][1]), 0x2An, results[0][1])
@@ -305,41 +417,48 @@ export const proof = {
     },
     now: () => {
         const [_, result] = virtual({ ...emptyState, epochNs: 1_000_000 })(now())
-        assertEq(result, 1_000_000)
+        assertOk(result, 1_000_000)
     },
     sandbox: {
         // Virtual `sandbox` is now a pass-through: the function is expected
         // to return a `SandboxResult` directly. Fixtures dictate the result
         // (and `duration`) instead of the runner measuring.
         ok: () => {
-            const [_, { result, duration }] = virtual(emptyState)(
-                sandbox(() => /** @type {never} */ ({ result: ['ok', 42], duration: 0 })))
+            const [_, sandboxed] = virtual(emptyState)(
+                sandbox(() => ({ result: ['ok', 42], duration: 0 })))
+            // Two `Result`s, one inside the other on purpose: the outer one is
+            // the operation's own status, the inner one is the sandboxed
+            // function's outcome — returned data, not effect status.
+            assert(sandboxed[0] === 'ok', sandboxed)
+            const { result, duration } = sandboxed[1]
             assert(result[0] === 'ok', result)
             assertEq(result[1], 42)
             assertEq(duration, 0)
         },
         error: () => {
             const err = new Error('fail')
-            const [_, { result }] = virtual(emptyState)(
-                sandbox(() => /** @type {never} */ ({ result: ['error', err], duration: 0 })))
+            const [_, sandboxed] = virtual(emptyState)(
+                sandbox(() => ({ result: ['error', err], duration: 0 })))
+            assert(sandboxed[0] === 'ok', sandboxed)
+            const { result } = sandboxed[1]
             assert(result[0] === 'error', result)
             assertEq(result[1], err)
         },
     },
     memory: {
         createAndRead: () => {
-            const effect = step(memCreate(42), key => memRead(key))
+            const effect = ioStep(memCreate(42), key => memRead(key))
             const [_, value] = virtual(emptyState)(effect)
-            assertEq(value, 42)
+            assertOk(value, 42)
         },
         createAndWrite: () => {
-            const effect = step(
+            const effect = ioStep(
                     memCreate(1),
-                    key => step(
+                    key => ioStep(
                         memWrite(key, 99),
                         () => memRead(key)))
             const [_, value] = virtual(emptyState)(effect)
-            assertEq(value, 99)
+            assertOk(value, 99)
         },
     },
     rename: {
@@ -351,7 +470,7 @@ export const proof = {
             assert(t === 'ok', result)
             assertEq(state.root.src, undefined, state.root)
             assert(Array.isArray(state.root.dst), state.root)
-            assertEq(uint((/** @type {readonly Vec[]} */ (state.root.dst))[0]), 0x2An, state.root)
+            assertEq(uint(state.root.dst[0]), 0x2An, state.root)
         },
         nestedRename: () => {
             const [state, [t, result]] = virtual({
@@ -360,8 +479,8 @@ export const proof = {
             })(rename('tmp/src', 'tmp/dst'))
             assert(t === 'ok', result)
             const tmp = state.root.tmp
-            assert(!(typeof tmp !== 'object' || Array.isArray(tmp)), state.root)
-            assertEq((/** @type {Dir} */ (tmp)).src, undefined, tmp)
+            assert(!(typeof tmp !== 'object' || tmp instanceof Array), state.root)
+            assertEq(tmp.src, undefined, tmp)
         },
         dirOverFile: () => {
             const [state, [t, result]] = virtual({
@@ -408,18 +527,18 @@ export const proof = {
     randomInt: {
         increments: () => {
             const [state1, r1] = virtual(emptyState)(randomInt())
-            assertEq(r1, 0)
+            assertOk(r1, 0)
             const [state2, r2] = virtual(state1)(randomInt())
-            assertEq(r2, 1)
+            assertOk(r2, 1)
             const [_, r3] = virtual(state2)(randomInt())
-            assertEq(r3, 2)
+            assertOk(r3, 2)
         },
     },
     writeFromStream: {
         createExclusiveFails: () => {
             // The destination already exists, so `createExclusive` fails (EEXIST) and
             // the error propagates without ever touching `writeBytes`.
-            /** @type {List<never, IoResult<Vec>>} */
+            /** @type {List<never, Vec, IoChannel>} */
             const chunks = listEmpty()
             const [state, [t, result]] = virtual({
                 ...emptyState,
@@ -432,13 +551,13 @@ export const proof = {
         invalidBufferSize: () => {
             // A chunk whose bit length isn't a multiple of 8 trips the
             // byte-alignment guard before `writeBytes` is ever called.
-            /** @type {List<never, IoResult<Vec>>} */
-            const chunks = listNonEmpty(['ok', vec(4n)(0b1010n)], listEmpty())
+            /** @type {List<never, Vec, IoChannel>} */
+            const chunks = listNonEmpty(vec(4n)(0b1010n), listEmpty())
             const [_, [t, result]] = virtual(emptyState)(
                 writeFromStream('hello', chunks)
             )
             assert(t === 'error', result)
-            assertEq(result, 'invalid buffer size')
+            assertIoMessage(result, 'invalid buffer size')
         },
     },
 }

package/fjs/effects/node/types.d.ts

@@ -9,10 +9,70 @@ import type { MemOp } from '../memory/types.ts';
 import type { Nominal } from '../../types/nominal/types.ts';
 import type { Result } from '../../types/result/types.ts';
 import type { StringMap } from '../../types/object/types.ts';
-import type { Effect, Operation, ToAsyncOperationMap } from '../types.ts';
+import type { Effect, NotImplemented, Operation, ToAsyncOperationMap } from '../types.ts';
 import type { List } from '../list/types.ts';
-export type IoResult<T> = Result<T, unknown>;
-export type All = ['all', <T>(...effects: Effect<never, T>[]) => readonly T[]];
+/**
+ * A host failure, normalized: whatever the runtime threw reduced to a
+ * serializable record. `code` is the OS error code when the host supplied one
+ * (`'ENOENT'`, `'EEXIST'`), absent otherwise.
+ *
+ * It is a tagged tuple for the same reason {@link NotImplemented} is — the two
+ * share an error channel, and the tag is what tells them apart. That
+ * distinction is the whole reason this type exists: with a bare `unknown`
+ * error, `NotImplemented | unknown` collapses to `unknown` and a program can no
+ * longer tell "this runner cannot do it" from "the host tried and failed".
+ *
+ * Normalizing also keeps the channel serializable. A thrown `Error` carries a
+ * stack, a `cause`, and arbitrary own properties; none of it survives a wire
+ * hop, and a runner in another process could not reproduce it.
+ */
+export type IoError = readonly ['ioError', IoErrorInfo];
+export type IoErrorInfo = {
+    readonly code?: string;
+    readonly message: string;
+};
+/**
+ * The result of an operation with no failures of its own: it either produces
+ * its value or reports that the runner does not implement it.
+ *
+ * Every operation's return type is a `Result`, including the ones that cannot
+ * fail on their own terms — an operation left on a raw contract would be a hole
+ * in the error channel, and a runner may omit a handler for any of them.
+ */
+export type OpResult<T> = Result<T, NotImplemented>;
+/**
+ * The error channel of anything that performs host IO: a normalized host
+ * failure, or the report that the runner does not implement the operation.
+ *
+ * It is one name rather than a union spelled at each site, and that is a
+ * migration property rather than brevity. An effect that does no IO *yet* is
+ * one added `readFile` away from doing some, and if each signature names its
+ * own errors, that one change walks up every enclosing signature — the failure
+ * mode that sank `throws` clauses elsewhere, where engineers eventually
+ * declared everything throwing rather than maintain the cascade. Declaring the
+ * standard channel once is that concession made deliberately: an IO-touching
+ * effect says it fails *the way node IO fails*, and gaining a new way to do so
+ * changes nothing above it.
+ *
+ * It is not a licence to widen. An operation with failures of its own extends
+ * the channel (`IoChannel | ParseError`), and a computation whose errors are
+ * genuinely narrower should say so — this is the default for IO, not a ceiling.
+ */
+export type IoChannel = NotImplemented | IoError;
+/**
+ * The result of an operation that performs host IO: its value, a normalized
+ * host failure, or the missing-handler report.
+ */
+export type IoResult<T> = Result<T, IoChannel>;
+/**
+ * Runs its effects concurrently and answers each one's whole `Result`.
+ *
+ * The nesting is deliberate and belongs to the runner: this envelope says
+ * whether `all` itself could be dispatched, and each inner `Result` is what
+ * that effect answered. `allOk` (`./module.f.mjs`) is the collapse a fallible
+ * chain wants.
+ */
+export type All = ['all', <T, E>(...effects: Effect<never, T, E>[]) => OpResult<readonly Result<T, E>[]>];
 export type Fetch = ['fetch', (url: string) => IoResult<Vec>];
 export type MakeDirectoryOptions = {
     readonly recursive: true;
@@ -42,7 +102,7 @@ export type WriteFile = readonly ['writeFile', (path: string, data: Vec) => IoRe
 export type Rm = readonly ['rm', (path: string) => IoResult<void>];
 export type Rename = readonly ['rename', (src: string, dst: string) => IoResult<void>];
 export type ReadBytes = readonly ['readBytes', (path: string, offset: number, size: number) => IoResult<Vec>];
-export type RandomInt = readonly ['randomInt', () => number];
+export type RandomInt = readonly ['randomInt', () => OpResult<number>];
 export type ExecResult = {
     readonly stdout: string;
     readonly stderr: string;
@@ -66,7 +126,7 @@ export type CreateExclusive = readonly ['createExclusive', (path: string) => IoR
  */
 export type WriteBytes = readonly ['writeBytes', (path: string, offset: number, data: Vec) => IoResult<void>];
 /** @internal */
-export type _WriteLoop = <O extends Operation>(offset: number, e: List<O, IoResult<Vec>>) => Effect<O | WriteBytes, IoResult<void>>;
+export type _WriteLoop = <O extends Operation>(offset: number, e: List<O, Vec, IoChannel>) => Effect<O | WriteBytes, void, IoChannel>;
 /** File metadata returned by `stat`. Only `size` (in bytes) for now. */
 export type FileStat = {
     readonly size: number;
@@ -86,11 +146,16 @@ export type ServerResponse = {
     readonly headers: Headers;
     readonly body: Vec;
 };
-export type RequestListener<O extends Operation> = (_: IncomingMessage) => Effect<O, ServerResponse>;
-export type CreateServer = ['createServer', (listener: RequestListener<Operation>) => Server];
-export type Listen = ['listen', (server: Server, port: number) => void];
+/**
+ * An HTTP request handler. The channel is `never` because the response frame
+ * *is* where a failure goes — a listener that cannot answer still has a status
+ * code to answer with, so absorbing is the contract rather than an omission.
+ */
+export type RequestListener<O extends Operation> = (_: IncomingMessage) => Effect<O, ServerResponse, never>;
+export type CreateServer = ['createServer', (listener: RequestListener<Operation>) => OpResult<Server>];
+export type Listen = ['listen', (server: Server, port: number) => OpResult<void>];
 export type Http = CreateServer | Listen;
-export type Forever = ['forever', () => never];
+export type Forever = ['forever', () => OpResult<never>];
 export type Module = StringMap<unknown>;
 export type Import = ['import', (path: string) => IoResult<Module>];
 /** Named output streams accepted by the `Write` effect. */
@@ -100,7 +165,7 @@ export type WriteConsoles = 'stdout' | 'stderr';
  * a `Vec`. The Node runner maps each stream name to the appropriate fd and
  * delegates to the OS via `stream.write()` with backpressure handling.
  */
-export type Write = readonly ['write', (stream: WriteConsoles, data: Vec) => void];
+export type Write = readonly ['write', (stream: WriteConsoles, data: Vec) => OpResult<void>];
 export type Console = (s: string) => Effect<Write, void>;
 /** Named input streams accepted by the `Read` effect. */
 export type ReadConsoles = 'stdin';
@@ -112,10 +177,10 @@ export type ReadConsoles = 'stdin';
  * rather than the interpreter. Back-pressure is naturally sequential — the next
  * `read` is only issued once the previous byte is consumed.
  */
-export type Read = readonly ['read', (stream: ReadConsoles) => number | null];
+export type Read = readonly ['read', (stream: ReadConsoles) => OpResult<number | null>];
 /** @internal */
 export type _UtfList = EffectList<number>;
-export type Now = readonly ['now', () => number];
+export type Now = readonly ['now', () => OpResult<number>];
 /**
  * The outcome of a `Sandbox` operation.
  *
@@ -132,7 +197,7 @@ export type SandboxResult<T> = {
      */
     readonly duration: number;
 };
-export type Sandbox = readonly ['sandbox', <T>(f: () => T) => SandboxResult<T>];
+export type Sandbox = readonly ['sandbox', <T>(f: () => T) => OpResult<SandboxResult<T>>];
 /**
  * Resolves the return value of a test function inside the effect runner.
  * If `p` is a real `Promise`, it is awaited and rejections propagate as
@@ -140,7 +205,7 @@ export type Sandbox = readonly ['sandbox', <T>(f: () => T) => SandboxResult<T>];
  * (objects with a `.then` method that are not `instanceof Promise`) are
  * treated as ordinary values — not awaited. See `fjs/dev/tf/README.md`.
  */
-export type Await = readonly ['await', (p: unknown) => readonly [unknown]];
+export type Await = readonly ['await', (p: unknown) => OpResult<readonly [unknown]>];
 /**
  * Signature of a framework test-registration function (e.g. `nodeTest.test`,
  * `bunTest.test`). Returns `Promise<void>` so async sub-tests can be awaited.
@@ -157,10 +222,18 @@ export type TestFn = (name: string, options: {
 export type TestContext = {
     readonly test: TestFn;
 };
-/** Effect operation that registers a named test with the active `TestContext`. */
-export type Test = readonly ['test', (ctx: TestContext, name: string, expectFailure: boolean, test: (t: TestContext) => Effect<Test | All | Await, void>) => void];
+/**
+ * Operation that registers a named test with the active `TestContext`.
+ *
+ * The callback's `never` is the honest reading of what an external framework
+ * accepts. Node `--test`, Bun and Deno take a body that either returns or
+ * throws; there is no channel to answer a failure through, so the body absorbs
+ * its own — which `emergent_testing` does, by panicking, since a throw is the
+ * one failure signal those frameworks understand.
+ */
+export type Test = readonly ['test', (ctx: TestContext, name: string, expectFailure: boolean, test: (t: TestContext) => Effect<Test | All | Await, void, never>) => OpResult<void>];
 export type NodeOp = Access | All | Await | Fetch | Fs | Http | Forever | Import | MemOp | Now | RandomInt | Read | Sandbox | Write | Test;
-export type NodeEffect<T> = Effect<NodeOp, T>;
+export type NodeEffect<T, E = IoChannel> = Effect<NodeOp, T, E>;
 export type NodeOperationMap = ToAsyncOperationMap<NodeOp>;
 /**
  * The environment variables.
@@ -199,5 +272,20 @@ export type NodeProgramOptions = {
     readonly nodeVersion?: string;
     readonly inlineTestContext: boolean;
 };
-export type Program<O extends Operation> = (options: NodeProgramOptions) => Effect<O, number>;
+/**
+ * A program: run it, and it answers an exit code.
+ *
+ * The code lives in a `Result` rather than in a bare `number`, and the two
+ * branches say which kind of code it is — `ok(0)` for success, `error(n)` for
+ * failure. A bare `number` could not: nothing could short-circuit on it, so a
+ * chain that ran one program and then another had to re-test the code by hand,
+ * and `step(…, () => pure(0))` was a way to report a failed program as a clean
+ * exit that the type system had no opinion about.
+ *
+ * **`T` is the literal `0`**, so a success carries no information beyond
+ * having succeeded, and `r[1]` is the exit code in *either* branch. A runner
+ * reads the code without asking which branch it came from; a caller that cares
+ * whether the program failed asks `r[0]`.
+ */
+export type Program<O extends Operation> = (options: NodeProgramOptions) => Effect<O, 0, number>;
 export type NodeProgram = Program<NodeOp>;

package/fjs/effects/node/virtual/module.f.d.mts

@@ -4,9 +4,10 @@
  * @module
  *
  * @import { Vec } from '../../../types/bit_vec/types.ts'
- * @import { MemOperationMap, RunInstance } from '../../mock/types.ts'
- * @import { Key } from '../../memory/types.ts'
- * @import { Dirent, FileStat, IoResult, Module, NodeOp, NodeProgramOptions, SandboxResult } from '../types.ts'
+ * @import { PartialMemOperationMap, RunInstance } from '../../mock/types.ts'
+ * @import { Dirent, FileStat, IoError, IoResult, Module, NodeOp, NodeProgramOptions, SandboxResult } from '../types.ts'
+ * @import { Result } from '../../../types/result/types.ts'
+ * @import { Error } from '../../../types/result/types.ts'
  * @import { Dir, State, _Entity } from './types.ts'
  */
 import type { RunInstance } from '../../mock/types.ts';
@@ -14,7 +15,20 @@ import type { NodeOp, NodeProgramOptions } from '../types.ts';
 import type { State } from './types.ts';
 /** @type {State} */
 export declare const emptyState: State;
-/** @type {RunInstance<NodeOp, State>} */
+/**
+ * The virtual runner.
+ *
+ * **It implements part of `NodeOp`, and says so.** `exec`, `createServer`,
+ * `listen`, `forever` and `test` have no meaning against an in-memory
+ * filesystem, and they used to be present as `todo` handlers — entries that
+ * existed only to satisfy a total operation map and threw when reached. They
+ * are simply absent now, so a program that asks for one gets
+ * `error(notImplemented)` back through its own continuation and decides what an
+ * incompatible runner means for it, which is what `NotImplemented` was
+ * introduced for. A command that is not a `NodeOp` at all still panics.
+ *
+ * @type {RunInstance<NodeOp, State>}
+ */
 export declare const virtual: RunInstance<NodeOp, State>;
 /**
  * Safe, inert defaults for every {@link NodeProgramOptions} field, intended for