functionalscript 0.45.0 → 0.46.1

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

@@ -11,9 +11,10 @@
  * @module
  *
  * @import { Vec } from '../../types/bit_vec/types.ts'
- * @import { Effect, Func, Operation } from '../types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { Commands, CommandSet, Effect, Func, NotImplemented, Operation } from '../types.ts'
  * @import { List } from '../list/types.ts'
- * @import { All, Access, Await, Console, CreateExclusive, CreateServer, Dirent, Engine, Env, Exec, ExecResult, Fetch, FileStat, Forever, Fs, Headers, Http, IncomingMessage, Import, IoResult, Listen, MakeDirectoryOptions, Mkdir, Module, Now, NodeOp, NodeProgramOptions, RandomInt, Read, ReadBytes, ReadConsoles, ReadFile, Readdir, ReaddirOptions, RequestListener, Rename, Rm, Sandbox, SandboxResult, Server, ServerResponse, Stat, Test, TestContext, TestFn, Write, WriteBytes, WriteConsoles, WriteFile, _UtfList, _WriteLoop, } from './types.ts'
+ * @import { All, Access, Await, Console, CreateExclusive, CreateServer, Dirent, Engine, Env, Exec, ExecResult, Fetch, FileStat, Forever, Fs, Headers, Http, IncomingMessage, Import, IoChannel, IoError, IoErrorInfo, Listen, MakeDirectoryOptions, Mkdir, Module, Now, NodeOp, NodeProgramOptions, RandomInt, Read, ReadBytes, ReadConsoles, ReadFile, Readdir, ReaddirOptions, RequestListener, Rename, Rm, Sandbox, SandboxResult, Server, ServerResponse, Stat, Test, TestContext, TestFn, Write, WriteBytes, WriteConsoles, WriteFile, _UtfList, _WriteLoop } from './types.ts'
  */
 
 import { utf8, utf8ToString } from '../../text/module.f.mjs'
@@ -21,37 +22,153 @@ import { toCodePointList } from '../../text/utf8/module.f.mjs'
 import { codePointListToString } from '../../text/utf16/module.f.mjs'
 import { reverse } from '../../types/list/module.f.mjs'
 import { length } from '../../types/bit_vec/module.f.mjs'
-import { ok, error as resultError, mapOk } from '../../types/result/module.f.mjs'
-import { do_, mapStep, okStep, pure, step } from '../module.f.mjs'
+import { error as resultError, ok as resultOk, unwrap } from '../../types/result/module.f.mjs'
+import { do_, pure } from '../module.f.mjs'
+import {
+    mapStep as ioMapStep, pureError, pureOk, resultMapStep, resultStep, step as ioStep,
+} from '../module.f.mjs'
+
+/**
+ * Builds a normalized host error. The constructor exists so the shape is
+ * written once: every runner reports its failures through it, and a consumer
+ * matching on `'ioError'` knows what the payload holds.
+ *
+ * @type {(info: IoErrorInfo) => IoError}
+ */
+export const ioError = info => ['ioError', info]
+
+/**
+ * Normalizes a **thrown** value into an {@link IoError}: the OS error code when
+ * the host attached a string one, and a message that is the `Error`'s own or
+ * the value's string form.
+ *
+ * This is the boundary where an impure runner's `catch` becomes ordinary effect
+ * data. Nothing past it sees the thrown object, which is the point — a stack, a
+ * `cause`, and arbitrary own properties do not survive a wire hop, and a
+ * program that branched on them would be reading the host's implementation
+ * rather than the operation's contract.
+ *
+ * @type {(e: unknown) => IoError}
+ */
+export const toIoError = e => {
+    const message = e instanceof Error ? e.message : String(e)
+    if (typeof e !== 'object' || e === null || !('code' in e) || typeof e.code !== 'string') {
+        return ioError({ message })
+    }
+    return ioError({ code: e.code, message })
+}
 
 /**
  * True if `e` is a "file or directory does not exist" (`ENOENT`) error.
  *
- * Node's filesystem rejections are `Error`s carrying `code: 'ENOENT'`; the
- * virtual interpreter mirrors that shape for absent paths. Lets callers swallow
- * only the missing-path case (e.g. a fresh store) while propagating genuine
- * failures (permissions, corruption) rather than masking them.
+ * Node's filesystem rejections are `Error`s carrying `code: 'ENOENT'`, which
+ * {@link toIoError} keeps; the virtual interpreter reports the same code for
+ * absent paths. Lets callers swallow only the missing-path case (e.g. a fresh
+ * store) while propagating genuine failures (permissions, corruption) rather
+ * than masking them.
  *
- * @type {(e: unknown) => boolean}
+ * A {@link NotImplemented} is never "not found": a runner that cannot perform
+ * the operation has not looked for the path at all, so the two must not
+ * collapse into one benign branch — which is exactly what a bare `unknown`
+ * error channel used to allow.
+ *
+ * @type {(e: IoChannel) => boolean}
  */
-export const isNotFound = e =>
-    typeof e === 'object' && e !== null && (/** @type {{ readonly code?: unknown }} */ (e)).code === 'ENOENT'
+export const isNotFound = ([tag, payload]) =>
+    tag === 'ioError' && payload.code === 'ENOENT'
+
+/**
+ * `NodeOp`'s commands as data, so a runner that implements only part of them
+ * can still tell an operation it lacks from a `Do` node whose `command` was
+ * never a `NodeOp` at all — see `CommandSet` in `../types.ts` for why the
+ * distinction needs the set at runtime.
+ *
+ * Declared as a record because `CommandSet<NodeOp>` is checked for
+ * *completeness*: adding a command to `NodeOp` and forgetting it here is a
+ * compile error, where an array literal would only have its members checked and
+ * would drift silently.
+ *
+ * @type {CommandSet<NodeOp>}
+ */
+const nodeCommandSet = {
+    access: null, all: null, await: null, createExclusive: null,
+    createServer: null, exec: null, fetch: null, forever: null,
+    import: null, listen: null, memCreate: null, memRead: null,
+    memWrite: null, mkdir: null, now: null, randomInt: null,
+    read: null, readBytes: null, readFile: null, readdir: null,
+    rename: null, rm: null, sandbox: null, stat: null,
+    test: null, write: null, writeBytes: null, writeFile: null,
+}
+
+/**
+ * The commands of {@link nodeCommandSet}, in the form a partial runner tests
+ * membership against. The cast is the one `Object.keys` always needs: it
+ * answers `string[]` for a record whose keys the type system knows exactly.
+ *
+ * @type {Commands<NodeOp>}
+ */
+export const nodeCommands = /** @type {Commands<NodeOp>} */ (Object.keys(nodeCommandSet))
 
 // all
 
 /**
  * To run the operation `O` should be known by the runner/engine.
- * This is the reason why we merge `O` with `All` in the resulted `Effect`.
+ * This is the reason why we merge `O` with `All` in the resulting effect.
  */
 export const all =
-    /** @type {<O extends Operation, T>(...a: readonly Effect<O, T>[]) => Effect<O | All, readonly T[]>} */
-    (do_('all'))
+    // `Func` cannot express a variadic generic operation, so the declared type
+    // is written out here and `do_`'s is set aside.
+    /** @type {<O extends Operation, T, E>(...a: readonly Effect<O, T, E>[]) => Effect<O | All, readonly Result<T, E>[], NotImplemented>} */
+    (/** @type {unknown} */ (do_('all')))
+
+/**
+ * Collapses a list of results into a result of the list, keeping the **first**
+ * error in list order and discarding the later ones.
+ *
+ * Keeping one is what makes this a `Result` rather than a report: the callers
+ * that need it are chains, and a chain has one error channel. A site that wants
+ * every failure wants a different return type and should not reach for this.
+ *
+ * @type {<T, E>(list: readonly Result<T, E>[]) => Result<readonly T[], E>}
+ */
+const okList = list => {
+    for (const r of list) {
+        if (r[0] === 'error') { return r }
+    }
+    return resultOk(list.map(unwrap))
+}
+
+/**
+ * {@link all} in the `ok` channel: collects the values when every effect
+ * succeeded, and answers with the first failure otherwise.
+ *
+ * `all` alone cannot serve a fallible chain. Its envelope is the runner's
+ * (`OpResult`, saying whether the *operation* could be dispatched), so handing
+ * it `Effect`s nests one `Result` inside another and the caller receives
+ * `readonly Result<T, E>[]`. That has to be collapsed before the chain can
+ * `step` again, and a continuation that forgets to is the value-discarding
+ * hazard this migration exists to remove — one level in, where it is harder to
+ * see.
+ *
+ * **Every effect still runs.** The short-circuit is in the *result*, not in the
+ * execution: `all` performs them concurrently and this reads the answers once
+ * they are all in, so a failure does not cancel its siblings the way it stops
+ * the sequential `forEachStep` in `./module.f.mjs`. The error channel
+ * unions the runner's
+ * `NotImplemented` with the effects' own `E` for the same reason every other
+ * step does — either can be what went wrong.
+ *
+ * @type {<O extends Operation, T, E>(...a: readonly Effect<O, T, E>[]) => Effect<O | All, readonly T[], NotImplemented | E>}
+ */
+export const allOk = (...a) =>
+    ioStep(all(...a), rs => pure(okList(rs)))
 
 /**
  * @template {Operation} O0
  * @template T0
- * @param {Effect<O0, T0>} a
- * @returns {<O1 extends Operation, T1>(b: Effect<O1, T1>) => Effect<O0 | O1 | All, readonly[T0, T1]>}
+ * @template E0
+ * @param {Effect<O0, T0, E0>} a
+ * @returns {<O1 extends Operation, T1, E1>(b: Effect<O1, T1, E1>) => Effect<O0 | O1 | All, readonly[Result<T0, E0>, Result<T1, E1>], NotImplemented>}
  */
 export const both = a => b =>
     /** @type {any} */ (all)(a, b)
@@ -74,14 +191,14 @@ export const readFile = do_('readFile')
 /**
  * Reads a file as UTF-8 text.
  *
- * Preserves the `IoResult` instead of unwrapping so callers can pattern-match
- * on errors (e.g. convert them into domain-specific errors) or `unwrap` at the
- * call site.
+ * Preserves the error channel instead of unwrapping so callers can
+ * pattern-match on it (e.g. convert a failure into a domain-specific error) or
+ * `unwrap` at the call site.
  *
- * @type {(path: string) => Effect<ReadFile, IoResult<string>>}
+ * @type {(path: string) => Effect<ReadFile, string, IoChannel>}
  */
 export const readUtf8File = path =>
-    mapStep(readFile(path), mapOk(utf8ToString))
+    ioMapStep(readFile(path), utf8ToString)
 
 // readdir
 
@@ -96,7 +213,7 @@ export const writeFile = do_('writeFile')
 /**
  * Writes a string to `path` as UTF-8 bytes.
  *
- * @type {(path: string, content: string) => Effect<WriteFile, IoResult<void>>}
+ * @type {(path: string, content: string) => Effect<WriteFile, void, IoChannel>}
  */
 export const writeUtf8File = (path, content) =>
     writeFile(path, utf8(content))
@@ -145,21 +262,18 @@ export const writeBytes = do_('writeBytes')
 const writeLoop = path => {
     /** @type {_WriteLoop} */
     const f = (offset, e) =>
-        step(e, r => {
-            if (r === undefined) {
-                return pure(ok(undefined))
-            }
-            const { first: [t, v], tail } = r
-            if (t === 'error') {
-                return pure(resultError(v))
+        ioStep(e, node => {
+            if (node === undefined) {
+                return pureOk(undefined)
             }
+            const { first: v, tail } = node
             const lenV = length(v)
             if ((lenV & 0b111n) !== 0n) {
-                return pure(resultError('invalid buffer size'))
+                return pureError(ioError({ message: 'invalid buffer size' }))
             }
-            return step(
+            return ioStep(
                 writeBytes(path, offset, v),
-                okStep(() => f(offset + Number(lenV >> 3n), tail)))
+                () => f(offset + Number(lenV >> 3n), tail))
         })
     return f
 }
@@ -167,13 +281,13 @@ const writeLoop = path => {
 /**
  * @template {Operation} O
  * @param {string} path
- * @param {List<O, IoResult<Vec>>} e
- * @returns {Effect<O | WriteBytes | CreateExclusive, IoResult<void>>}
+ * @param {List<O, Vec, IoChannel>} e
+ * @returns {Effect<O | WriteBytes | CreateExclusive, void, IoChannel>}
  */
 export const writeFromStream = (path, e) =>
-    step(
+    ioStep(
         createExclusive(path),
-        okStep(() => /** @type {Effect<O | WriteBytes, IoResult<void>>} */ (writeLoop(path)(0, e))))
+        () => writeLoop(path)(0, e))
 
 // stat
 
@@ -204,27 +318,31 @@ export const import_ = do_('import')
 // write
 
 /** Emits a `Write` effect to the given named stream. */
-export const write = /** @type {Func<Write>} */ (do_('write'))
+/** @type {Func<Write>} */
+export const write = do_('write')
 
 /**
  * Encodes `s + '\n'` as UTF-8 and emits a `Write` effect to `stream`.
  * Shared implementation for `log` and `error`.
  *
- * @type {(stream: WriteConsoles) => (s: string) => Effect<Write, void>}
+ * @type {(stream: WriteConsoles) => Console}
  */
 const writeString = stream => s =>
     write(stream, utf8(s + '\n'))
 
 /** Writes a line to `stdout`. Replaces the retired `Log` effect. */
-export const log = /** @type {Console} */ (writeString('stdout'))
+/** @type {Console} */
+export const log = writeString('stdout')
 
 /** Writes a line to `stderr`. Replaces the retired `Error` effect. */
-export const error = /** @type {Console} */ (writeString('stderr'))
+/** @type {Console} */
+export const error = writeString('stderr')
 
 // read
 
 /** Emits a `Read` effect, yielding the next input byte or `null` at EOF. */
-export const read = /** @type {Func<Read>} */ (do_('read'))
+/** @type {Func<Read>} */
+export const read = do_('read')
 
 /** @type {(bytes: _UtfList) => string} */
 const utf8ListToString = bytes =>
@@ -247,17 +365,20 @@ const lf = 0x0a
  * reversed and decoded once at the terminator, so a large line costs O(n)
  * rather than the O(n²) of copying a growing array on every byte.
  *
- * @type {(stream: ReadConsoles) => Effect<Read, string | null>}
+ * A failed `read` — a runner without the operation — propagates: the line is
+ * not silently truncated into a `null` that a caller would read as EOF.
+ *
+ * @type {(stream: ReadConsoles) => Effect<Read, string | null, NotImplemented>}
  */
 export const readLine = stream => {
-    /** @type {(acc: _UtfList) => Effect<Read, string | null>} */
+    /** @type {(acc: _UtfList) => Effect<Read, string | null, NotImplemented>} */
     const loop = acc =>
-        step(
+        ioStep(
             read(stream),
             b => b === null
-                ? pure(acc === null ? null : utf8ListToString(reverse(acc)))
+                ? pureOk(acc === null ? null : utf8ListToString(reverse(acc)))
                 : b === lf
-                    ? pure(utf8ListToString(reverse(acc)))
+                    ? pureOk(utf8ListToString(reverse(acc)))
                     : loop({ first: b, tail: acc })
         )
     return loop(null)
@@ -295,9 +416,9 @@ export const sandbox = do_('sandbox')
 /** @type {Func<Await>} */
 const awaitPromise = do_('await')
 
-/** @type {(p: unknown) => Effect<Await, unknown>} */
+/** @type {(p: unknown) => Effect<Await, unknown, NotImplemented>} */
 export const awaitIfPromise = p =>
-    mapStep(awaitPromise(p), ([x]) => x)
+    ioMapStep(awaitPromise(p), ([x]) => x)
 
 // Test registration
 
@@ -307,14 +428,97 @@ export const test = do_('test')
 // Node
 
 /**
- * Writes an error line to `stderr` and yields exit code `1`. The canonical
+ * Writes an error line to `stderr` and fails with exit code `1`. The canonical
  * "fail with a message" program for a `NodeProgram`. For non-`1` exit codes,
- * compose `mapStep(error(s), () => n)` directly.
+ * compose `resultMapStep(error(s), () => resultError(n))` directly.
+ *
+ * **It never succeeds, and the type says so.** `E` is `number` and `T` is
+ * `never`, so `step`'s continuation takes a `never` and can never run. That is
+ * a continuation nobody reaches, not a compile error: writing one still type-
+ * checks, because a function accepting `never` accepts anything. What the type
+ * buys is that no *value* can be invented for the success branch, so nothing
+ * downstream can proceed as if this had succeeded.
+ *
+ * **The write's own outcome is deliberately discarded**, which is why this is
+ * `resultMapStep` rather than `mapStep`. The program is already failing and
+ * the exit code is `1` whether or not `stderr` accepted the bytes; propagating
+ * here would hand every caller a "failed to report a failure" branch with no
+ * better answer available to it than the one taken here.
  *
- * @type {(s: string) => Effect<Write, number>}
+ * @type {(s: string) => Effect<Write, never, number>}
  */
 export const errorExit = s =>
-    mapStep(error(s), () => 1)
+    resultMapStep(error(s), () => resultError(1))
+
+/**
+ * The exit code a {@link Program} answered, from whichever branch it came.
+ *
+ * `Result<0, number>` puts a number at `[1]` on both sides — `ok(0)` for
+ * success, `error(n)` for failure — so reading the code never asks which
+ * branch produced it, while a caller that cares *whether* it failed still asks
+ * `[0]`. That is why the success type is the literal `0` rather than `void`.
+ *
+ * A non-zero code belongs in the `error` branch and `0` in the `ok` branch; the
+ * type cannot say so, since there is no "non-zero number", and nothing depends
+ * on it — this reads `[1]` either way.
+ *
+ * @type {(r: Result<0, number>) => number}
+ */
+export const exitCode = ([, code]) => code
+
+/**
+ * Renders a channel error as a human line: an {@link IoError}'s own message, or
+ * the command name a runner could not dispatch.
+ *
+ * @type {(e: IoChannel) => string}
+ */
+export const errorMessage = ([tag, payload]) =>
+    tag === 'notImplemented' ? `operation not implemented: ${payload}` : payload.message
+
+/**
+ * Renders a channel error for a **remote** caller: the command name for a
+ * {@link NotImplemented}, the OS error code for an `IoError`, and nothing else.
+ *
+ * {@link errorMessage} is for the operator of the program, who is entitled to
+ * the host's own words — including the path that failed. A protocol client is
+ * not, and the difference is not stylistic: `payload.message` is where the
+ * host puts the absolute path it could not read, so answering an MCP tool call
+ * with it publishes the server's filesystem layout to whoever is on the other
+ * end. The code (`ENOENT`, `EACCES`) says *what* went wrong without saying
+ * *where*, which is the part a client can act on anyway.
+ *
+ * A host that attached no code leaves nothing safe to forward, so the answer is
+ * the bare kind. That is deliberate: guessing which part of a free-text message
+ * is path-free is exactly the mistake this exists to prevent.
+ *
+ * @type {(e: IoChannel) => string}
+ */
+export const errorSummary = ([tag, payload]) =>
+    tag === 'notImplemented'
+        ? `operation not implemented: ${payload}`
+        : payload.code === undefined ? 'io error' : `io error: ${payload.code}`
+
+/**
+ * Ends a program with an exit code that reflects `e`: `ok` yields `0`, and a
+ * failure is reported on `stderr` and yields `1` ({@link errorExit}).
+ *
+ * This is the exit-code policy a `NodeProgram` needs at the end of its chain,
+ * and the reason a program does not have to invent one per command. It is the
+ * counterpart of {@link isNotFound} at the other end of the channel: where that
+ * one asks which failure this is, this one stops asking and reports.
+ *
+ * @type {<O extends Operation, T>(e: Effect<O, T, IoChannel>) => Effect<O | Write, 0, number>}
+ */
+export const exitStep = e =>
+    resultStep(e, r => {
+        // Bound rather than returned inline: the two branches are
+        // `Effect<Write, never, number>` and `Effect<never, 0, never>`, both
+        // assignable to this, but `step` infers its continuation's type from
+        // the union and picks neither.
+        /** @type {Effect<Write, 0, number>} */
+        const code = r[0] === 'error' ? errorExit(errorMessage(r[1])) : pureOk(0)
+        return code
+    })
 
 /** @type {(version: string) => readonly number[]} */
 const versionParts = version =>

package/fjs/effects/node/module.mjs

@@ -1,5 +1,5 @@
 /**
- * Node.js effect runner: interprets `Effect<NodeOp, T>` directly against the
+ * Node.js effect runner: interprets `Effect<NodeOp, T, E>` directly against the
  * Node globals and built-in modules (`fs`, `http`, `child_process`, `process`,
  * `fetch`, …).
  *
@@ -13,7 +13,7 @@
  * @module
  *
  * @import { Effect } from '../types.ts'
- * @import { Server as EffectServer, Headers, Module, NodeOp, RequestListener as Erl, NodeProgram, NodeProgramOptions, WriteConsoles, TestContext, TestFn, } from './types.ts'
+ * @import { IoResult, Server as EffectServer, Headers, Module, NodeOp, RequestListener as Erl, NodeProgram, NodeProgramOptions, WriteConsoles, TestContext, TestFn, } from './types.ts'
  * @import { Result } from '../../types/result/types.ts'
  * @import { StringMap } from '../../types/object/types.ts'
  */
@@ -30,9 +30,9 @@ import * as testContext from 'node:test'
 import { concat, normalize, toPosix } from '../../path/module.f.mjs'
 import { asyncRun } from '../module.mjs'
 import { memoryOperationMap } from './memory/module.mjs'
-import { usesInlineTestContext } from './module.f.mjs'
+import { exitCode, toIoError, usesInlineTestContext } from './module.f.mjs'
 import { asBase, asNominal } from '../../types/nominal/module.f.mjs'
-import { error, ok } from '../../types/result/module.f.mjs'
+import { error, ok, unwrap } from '../../types/result/module.f.mjs'
 import { asyncTryCatch } from '../../types/result/module.mjs'
 import { fromVec, listToVec, toVec } from '../../types/uint8array/module.f.mjs'
 import { maxLengthBytes } from '../../types/bit_vec/module.f.mjs'
@@ -67,7 +67,23 @@ import { maxLengthBytes } from '../../types/bit_vec/module.f.mjs'
  */
 const createServer = http.createServer
 
-/** @typedef {<T>(effect: Effect<NodeOp, T>) => Promise<T>} _EffectToPromise */
+/** @typedef {<T, E>(effect: Effect<NodeOp, T, E>) => Promise<Result<T, E>>} _EffectToPromise */
+
+/**
+ * Performs host IO, reporting a thrown failure as an {@link IoResult} error.
+ *
+ * Every filesystem, network, and subprocess handler below goes through it, so
+ * the `catch` that turns an exception into effect data — and the normalization
+ * that keeps the channel serializable — happens in exactly one place.
+ *
+ * @template T
+ * @param {() => Promise<T>} f
+ * @returns {Promise<IoResult<T>>}
+ */
+const io = async f => {
+    const r = await asyncTryCatch(f)
+    return r[0] === 'ok' ? r : error(toIoError(r[1]))
+}
 
 /**
  * @template T
@@ -115,7 +131,7 @@ const sandbox = async f => {
             p = await p
             after = performance.now()
         }
-        result = ok(/** @type {T} */ (p))
+        result = ok(p)
     } catch (e) {
         after = performance.now()
         result = error(e)
@@ -190,7 +206,7 @@ const waitReadableOrEnd = stdin =>
 const readStdinByte = async () => {
     const stdin = process.stdin
     while (true) {
-        const chunk = /** @type {Uint8Array | null} */ (stdin.read(1))
+        const chunk = stdin.read(1)
         if (chunk !== null) {
             return chunk[0]
         }
@@ -210,16 +226,16 @@ const { randomInt } = crypto
 /** @type {_EffectToPromise} */
 const runNodeEffect = asyncRun({
     ...memoryOperationMap(),
-    all: async (...effects) => await Promise.all(effects.map(runNodeEffect)),
-    fetch: async url => asyncTryCatch(async () => {
+    all: async (...effects) => ok(await Promise.all(effects.map(runNodeEffect))),
+    fetch: url => io(async () => {
         const response = await fetch(url)
         if (!response.ok) {
             throw new Error(`Fetch error: ${response.status} ${response.statusText}`)
         }
         return toVec(new Uint8Array(await response.arrayBuffer()))
     }),
-    mkdir: (path, options) => asyncTryCatch(async () => { await mkdir(path, options) }),
-    readFile: path => asyncTryCatch(async () => {
+    mkdir: (path, options) => io(async () => { await mkdir(path, options) }),
+    readFile: path => io(async () => {
         const fileStats = await stat(path)
         // if the file is too big, toVec should fail anyway but in this case we don't want to load the file.
         if (fileStats.size > maxFileSizeBytes) {
@@ -227,7 +243,7 @@ const runNodeEffect = asyncRun({
         }
         return toVec(await readFile(path))
     }),
-    readdir: (path, r) => asyncTryCatch(async () =>
+    readdir: (path, r) => io(async () =>
         (await readdir(path, { ...r, withFileTypes: true }))
         .map(v => ({
             name: v.name,
@@ -235,10 +251,10 @@ const runNodeEffect = asyncRun({
             isFile: v.isFile()
         }))
     ),
-    writeFile: (path, data) => asyncTryCatch(() => writeFile(path, fromVec(data))),
-    rm: path => asyncTryCatch(() => rm(path)),
-    rename: (src, dst) => asyncTryCatch(() => rename(src, dst)),
-    readBytes: (path, offset, size) => asyncTryCatch(async () => {
+    writeFile: (path, data) => io(() => writeFile(path, fromVec(data))),
+    rm: path => io(() => rm(path)),
+    rename: (src, dst) => io(() => rename(src, dst)),
+    readBytes: (path, offset, size) => io(async () => {
         if (offset < 0) {
             throw new Error(`Offset ${offset} is negative`)
         }
@@ -254,13 +270,13 @@ const runNodeEffect = asyncRun({
             await fh.close()
         }
     }),
-    randomInt: async () => randomInt(randomMax),
-    access: path => asyncTryCatch(() => access(path)),
-    createExclusive: path => asyncTryCatch(async () => {
+    randomInt: async () => ok(randomInt(randomMax)),
+    access: path => io(() => access(path)),
+    createExclusive: path => io(async () => {
         const fh = await open(path, 'wx')
         await fh.close()
     }),
-    writeBytes: (path, offset, data) => asyncTryCatch(async () => {
+    writeBytes: (path, offset, data) => io(async () => {
         const fh = await open(path, 'r+')
         try {
             const buffer = fromVec(data)
@@ -275,11 +291,11 @@ const runNodeEffect = asyncRun({
             await fh.close()
         }
     }),
-    stat: path => asyncTryCatch(async () => ({ size: (await stat(path)).size })),
-    import: path => asyncTryCatch(() => asyncImport(path)),
+    stat: path => io(async () => ({ size: (await stat(path)).size })),
+    import: path => io(() => asyncImport(path)),
     exec: (command, stdin) => new Promise(resolve => {
         const child = exec(command, (e, stdout, stderr) =>
-            resolve(e !== null ? /** @type {const} */ (['error', e]) : ok({ stdout, stderr }))
+            resolve(e !== null ? error(toIoError(e)) : ok({ stdout, stderr }))
         )
         child.stdin?.end(stdin)
     }),
@@ -289,30 +305,37 @@ const runNodeEffect = asyncRun({
         const nodeRl = async (req, res) => {
             const reqBody = await collect(req)
             const { method, url, headers } = req
-            const { status, headers: outHeaders, body: outBody } = await runNodeEffect(erl({
+            // `RequestListener` answers `Effect<…, ServerResponse, never>` —
+            // the response frame is where a listener puts its failures — so
+            // this unwrap is total.
+            const { status, headers: outHeaders, body: outBody } = unwrap(await runNodeEffect(erl({
                 method,
                 url,
                 headers,
                 body: listToVec(reqBody)
-            }))
+            })))
             res
                 .writeHead(status, outHeaders)
                 .end(fromVec(outBody))
         }
-        return /** @satisfies {EffectServer} */ (asNominal(createServer(nodeRl)))
+        return ok(/** @satisfies {EffectServer} */ (asNominal(createServer(nodeRl))))
     },
     listen: async (server, port) => {
         const s = /** @type {_Server} */ (asBase(server))
         s.listen(port)
+        return ok(undefined)
     },
     forever: () => new Promise(() => {}),
-    now: async () => now(),
-    sandbox,
-    await: awaitPromise,
-    write: (stream, data) => writeAll(streams[stream], fromVec(data)),
-    read: readStdinByte,
+    now: async () => ok(now()),
+    sandbox: async f => ok(await sandbox(f)),
+    await: async p => ok(await awaitPromise(p)),
+    write: async (stream, data) => ok(await writeAll(streams[stream], fromVec(data))),
+    read: async () => ok(await readStdinByte()),
     test: async (ctx, name, expectFailure, test) =>
-        ctx.test(name, { expectFailure }, async t => runNodeEffect(test(t))),
+        // The body's answer is `ok(undefined)` — a `Test` callback absorbs its
+        // own failures by panicking, which is the only signal these frameworks
+        // read — so it is awaited and discarded rather than returned.
+        ok(await ctx.test(name, { expectFailure }, async t => { await runNodeEffect(test(t)) })),
 })
 
 /** @type {TestFn} */
@@ -365,8 +388,8 @@ const options = {
  * the program's code, use {@link run} instead.
  * @type {(p: NodeProgram) => Promise<number>}
  */
-export const runEffect = program =>
-    runNodeEffect(program(options))
+export const runEffect = async program =>
+    exitCode(await runNodeEffect(program(options)))
 
 /**
  * CLI entry point: runs a `NodeProgram` via {@link runEffect}, then calls