functionalscript 0.44.0 → 0.46.0

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

@@ -2,16 +2,33 @@
  * Virtual Node-effect operations for filesystem and process tests.
  *
  * @module
+ *
+ * @import { Vec } from '../../../types/bit_vec/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';
 import type { NodeOp, NodeProgramOptions } from '../types.ts';
 import type { State } from './types.ts';
-/** @import { Key } from '../../memory/types.ts' */
-/** @import { Dirent, FileStat, IoResult, Module, NodeOp, NodeProgramOptions, SandboxResult } from '../types.ts' */
-/** @import { Dir, State, _Entity } 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

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

@@ -2,20 +2,23 @@
  * Virtual Node-effect operations for filesystem and process tests.
  *
  * @module
+ *
+ * @import { Vec } from '../../../types/bit_vec/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 { todo } from '../../../asserts/module.f.mjs'
+import { assert, todo } from '../../../asserts/module.f.mjs'
 import { isProperPrefix, join, parse } from '../../../path/module.f.mjs'
 import { utf8ToString } from '../../../text/module.f.mjs'
-/** @import { Vec } from '../../../types/bit_vec/types.ts' */
 import { empty, length, maxLengthBytes, msb, vec } from '../../../types/bit_vec/module.f.mjs'
 import { error, ok } from '../../../types/result/module.f.mjs'
-import { run } from '../../mock/module.f.mjs'
-/** @import { MemOperationMap, RunInstance } from '../../mock/types.ts' */
+import { ioError, nodeCommands } from '../module.f.mjs'
+import { partialRun } from '../../mock/module.f.mjs'
 import { asBase, asNominal } from '../../memory/module.f.mjs'
-/** @import { Key } from '../../memory/types.ts' */
-/** @import { Dirent, FileStat, IoResult, Module, NodeOp, NodeProgramOptions, SandboxResult } from '../types.ts' */
-/** @import { Dir, State, _Entity } from './types.ts' */
 
 /** @type {State} */
 export const emptyState = {
@@ -43,10 +46,13 @@ const operation = op => {
         }
         const [first, ...rest] = path
         const subDir = dir[first]
-        if (typeof subDir !== 'object' || Array.isArray(subDir)) {
+        // `instanceof Array`, not `Array.isArray`: the latter narrows to `any[]`,
+        // which `readonly Vec[]` is not assignable to, so its negative branch never
+        // removes a `readonly` array from `_Entity`. Only `instanceof` narrows here.
+        if (typeof subDir !== 'object' || subDir instanceof Array) {
             return op(dir, path)
         }
-        const [newSubDir, r] = f(/** @type {Dir} */ (subDir), rest)
+        const [newSubDir, r] = f(subDir, rest)
         return [{ ...dir, [first]: newSubDir }, r]
     }
     return path => state => {
@@ -64,12 +70,22 @@ const readOperation = op => operation((dir, path) => [dir, op(dir, path)])
 
 const okVoid = ok(undefined)
 
+/**
+ * A virtual host failure. The virtual runner reports the same normalized
+ * {@link IoError} the Node runner does, so a program cannot tell the two apart
+ * by the shape of what it catches — which is what makes a proof against the
+ * virtual filesystem evidence about the real one.
+ *
+ * @type {(message: string) => Error<IoError>}
+ */
+const fail = message => error(ioError({ message }))
+
 /** @type {(recursive: boolean) => (dir: Dir, path: readonly string[]) => readonly [Dir, IoResult<void>]} */
 const mkdirOp = recursive => (dir, path) => {
     let d = {}
     let i = path.length
     if (i > 1 && !recursive) {
-        return [dir, error('non-recursive')]
+        return [dir, fail('non-recursive')]
     }
     while (i > 0) {
         i -= 1
@@ -83,7 +99,7 @@ const mkdirOp = recursive => (dir, path) => {
 const mkdir = recursive => operation(mkdirOp(recursive))
 
 /** Absent-path error mirroring Node's `ENOENT`, so `isNotFound` recognizes it. */
-const enoent = error({ code: 'ENOENT' })
+const enoent = error(ioError({ code: 'ENOENT', message: 'no such file or directory' }))
 
 /** @type {(path: string) => (state: State) => readonly [State, IoResult<Vec>]} */
 const readFile = readOperation((dir, path) => {
@@ -91,15 +107,18 @@ const readFile = readOperation((dir, path) => {
     const file = dir[path[0]]
     if (typeof file === 'function') { throw new Error(`'${path[0]}' is a JsModule; readFile not supported`) }
     if (file === undefined) { return enoent }
-    if (!Array.isArray(file)) { return error(`'${path[0]}' is not a file`) }
-    const chunks = /** @type {readonly Vec[]} */ (file)
+    // `operation`'s wrapper descends into every plain-object (`Dir`) entry
+    // before this op ever runs, and the `JsModule` case already threw above,
+    // so `file` here is always a `Vec[]` — never a bare `Dir`.
+    assert(Array.isArray(file), `'${path[0]}' is not a file`)
+    const chunks = file
     const capBits = maxLengthBytes * 8n
     let result = empty
     for (const chunk of chunks) {
         const chunkLen = length(chunk)
         if (chunkLen === 0n) { continue }
         if (length(result) + chunkLen > capBits) {
-            return error(`File size exceeds maximum allowed size of ${maxLengthBytes} bytes`)
+            return fail(`File size exceeds maximum allowed size of ${maxLengthBytes} bytes`)
         }
         result = msb.concat(result)(chunk)
     }
@@ -108,13 +127,13 @@ const readFile = readOperation((dir, path) => {
 
 /** @type {(path: string) => (state: State) => readonly [State, IoResult<Module>]} */
 const import_ = readOperation((dir, path) => {
-    if (path.length !== 1) { return error('no such file') }
+    if (path.length !== 1) { return fail('no such file') }
     const entry = dir[path[0]]
-    if (typeof entry !== 'function') { return error(`'${path[0]}' is not a JsModule`) }
+    if (typeof entry !== 'function') { return fail(`'${path[0]}' is not a JsModule`) }
     return ok(entry())
 })
 
-const writeFileError = error('invalid file')
+const writeFileError = fail('invalid file')
 
 /** @type {(payload: Vec) => (dir: Dir, path: readonly string[]) => readonly [Dir, IoResult<void>]} */
 const writeFileOp = payload => (dir, path) => {
@@ -129,7 +148,7 @@ const writeFileOp = payload => (dir, path) => {
 /** @type {(payload: Vec) => (path: string) => (state: State) => readonly [State, IoResult<void>]} */
 const writeFile = payload => operation(writeFileOp(payload))
 
-const invalidPath = error('invalid path')
+const invalidPath = fail('invalid path')
 
 const { entries } = Object
 
@@ -142,10 +161,10 @@ const readdir = (base, recursive) => readOperation((dir, path) => {
         let result = []
         for (const [name, content] of entries(d)) {
             if (content === undefined) { continue }
-            const isFile = Array.isArray(content) || typeof content !== 'object'
+            const isFile = content instanceof Array || typeof content !== 'object'
             result = [...result, { name, parentPath, isFile }]
             if (!isFile && recursive) {
-                result = [...result, ...f(join(parentPath, name), /** @type {Dir} */ (content))]
+                result = [...result, ...f(join(parentPath, name), content)]
             }
         }
         return result
@@ -162,11 +181,15 @@ const access = readOperation((dir, path) => {
 
 /** @type {(dir: Dir, path: readonly string[]) => readonly [Dir, IoResult<void>]} */
 const rmOp = (dir, path) => {
-    if (path.length !== 1) { return [dir, error('invalid path')] }
+    if (path.length !== 1) { return [dir, fail('invalid path')] }
     const [name] = path
     const entry = dir[name]
-    if (entry === undefined) { return [dir, error('no such file')] }
-    if (!Array.isArray(entry) && typeof entry === 'object') { return [dir, error('is a directory')] }
+    if (entry === undefined) { return [dir, fail('no such file')] }
+    // No "is a directory" guard here: `operation`'s wrapper descends into
+    // every plain-object (`Dir`) entry before this op ever runs, so `entry`
+    // is always a `Vec[]` or a `JsModule` — never a bare `Dir` — and rm can
+    // always proceed. (`rm` on a genuinely non-empty directory instead hits
+    // `path.length !== 1` above, once the wrapper has descended into it.)
     const { [name]: _, ...rest } = dir
     return [rest, okVoid]
 }
@@ -176,7 +199,7 @@ const rm = operation(rmOp)
 
 /** @type {(dir: Dir, path: readonly string[]) => readonly [Dir, IoResult<_Entity>]} */
 const extractEntity = (dir, path) => {
-    if (path.length === 0) { return [dir, error('cannot extract root')] }
+    if (path.length === 0) { return [dir, fail('cannot extract root')] }
     if (path.length === 1) {
         const [name] = path
         const entry = dir[name]
@@ -186,15 +209,21 @@ const extractEntity = (dir, path) => {
     }
     const [first, ...rest] = path
     const sub = dir[first]
-    if (sub === undefined || Array.isArray(sub) || typeof sub === 'function') { return [dir, enoent] }
-    const [newSub, result] = extractEntity(/** @type {Dir} */ (sub), rest)
+    if (sub === undefined || sub instanceof Array || typeof sub === 'function') { return [dir, enoent] }
+    const [newSub, result] = extractEntity(sub, rest)
     if (result[0] === 'error') { return [dir, result] }
     return [{ ...dir, [first]: newSub }, result]
 }
 
 /** @type {(dir: Dir, path: readonly string[], entity: _Entity) => readonly [Dir, IoResult<void>]} */
 const insertEntityAt = (dir, path, entity) => {
-    if (path.length === 0) { return [dir, error('cannot insert at root')] }
+    // `insertEntityAt`'s only external caller, `rename`, always rejects an
+    // empty `dst` earlier — `isProperPrefix([], srcParsed)` is true whenever
+    // `srcParsed` is non-empty, so renaming onto root is already caught as
+    // "onto an ancestor" before this function runs. The recursive self-calls
+    // below never pass an empty path either (they only recurse when
+    // `path.length > 1`, with a non-empty remainder).
+    assert(path.length > 0, 'cannot insert at root')
     if (path.length === 1) {
         const [name] = path
         const existing = dir[name]
@@ -202,16 +231,16 @@ const insertEntityAt = (dir, path, entity) => {
             const entityIsDir = !Array.isArray(entity) && typeof entity === 'object'
             const existingIsDir = !Array.isArray(existing) && typeof existing === 'object'
             if (entityIsDir && !existingIsDir) {
-                return [dir, error(`cannot overwrite file '${name}' with a directory`)]
+                return [dir, fail(`cannot overwrite file '${name}' with a directory`)]
             }
             if (!entityIsDir && existingIsDir) {
-                return [dir, error(`'${name}' is a directory`)]
+                return [dir, fail(`'${name}' is a directory`)]
             }
             if (entityIsDir && existingIsDir) {
-                const existingDir = /** @type {Dir} */ (existing)
+                const existingDir = existing
                 const hasContent = Object.values(existingDir).some(v => v !== undefined)
                 if (hasContent) {
-                    return [dir, error(`cannot overwrite non-empty directory '${name}'`)]
+                    return [dir, fail(`cannot overwrite non-empty directory '${name}'`)]
                 }
             }
         }
@@ -220,8 +249,8 @@ const insertEntityAt = (dir, path, entity) => {
     const [first, ...rest] = path
     const sub = dir[first]
     if (sub === undefined) { return [dir, enoent] }
-    if (Array.isArray(sub) || typeof sub === 'function') { return [dir, error('not a directory')] }
-    const [newSub, result] = insertEntityAt(/** @type {Dir} */ (sub), rest, entity)
+    if (sub instanceof Array || typeof sub === 'function') { return [dir, fail('not a directory')] }
+    const [newSub, result] = insertEntityAt(sub, rest, entity)
     if (result[0] === 'error') { return [dir, result] }
     return [{ ...dir, [first]: newSub }, result]
 }
@@ -236,7 +265,7 @@ const rename = (src, dst) => state => {
     // now that source exists, reject if dst is strictly inside src's subtree (rename into own descendant)
     // or if src is strictly inside dst's subtree (rename onto own ancestor)
     if (isProperPrefix(srcParsed, dstParsed) || isProperPrefix(dstParsed, srcParsed)) {
-        return [state, error('cannot rename a directory into its own subtree or onto an ancestor')]
+        return [state, fail('cannot rename a directory into its own subtree or onto an ancestor')]
     }
     const [dstRoot, dstResult] = insertEntityAt(srcRoot, dstParsed, srcResult[1])
     if (dstResult[0] === 'error') { return [state, dstResult] }
@@ -249,13 +278,16 @@ const readBytesOp = (path, offset, size) => readOperation((dir, p) => {
     const file = dir[p[0]]
     if (typeof file === 'function') { throw new Error(`'${p[0]}' is a JsModule; readBytes not supported`) }
     if (file === undefined) { return enoent }
-    if (!Array.isArray(file)) { return error(`'${p[0]}' is not a file`) }
-    if (!Number.isInteger(offset)) { return error(`Offset ${offset} is not an integer`) }
-    if (!Number.isInteger(size)) { return error(`Chunk size ${size} is not an integer`) }
-    if (offset < 0) { return error(`Offset ${offset} is negative`) }
-    if (size < 0) { return error(`Chunk size ${size} is negative`) }
-    if (BigInt(size) > maxLengthBytes) { return error(`Chunk size ${size} exceeds maximum allowed size of ${maxLengthBytes} bytes`) }
-    const chunks = /** @type {readonly Vec[]} */ (file)
+    // `operation`'s wrapper descends into every plain-object (`Dir`) entry
+    // before this op ever runs, and the `JsModule` case already threw above,
+    // so `file` here is always a `Vec[]` — never a bare `Dir`.
+    assert(Array.isArray(file), `'${p[0]}' is not a file`)
+    if (!Number.isInteger(offset)) { return fail(`Offset ${offset} is not an integer`) }
+    if (!Number.isInteger(size)) { return fail(`Chunk size ${size} is not an integer`) }
+    if (offset < 0) { return fail(`Offset ${offset} is negative`) }
+    if (size < 0) { return fail(`Chunk size ${size} is negative`) }
+    if (BigInt(size) > maxLengthBytes) { return fail(`Chunk size ${size} exceeds maximum allowed size of ${maxLengthBytes} bytes`) }
+    const chunks = file
     let toSkip = BigInt(offset) * 8n
     let toRead = BigInt(size) * 8n
     let result = empty
@@ -282,7 +314,7 @@ const fileSizeBytes = chunks =>
     chunks.reduce((acc, c) => acc + Number(length(c) / 8n), 0)
 
 /** Absent-path error for an already-existing exclusive create, mirroring `EEXIST`. */
-const eexist = error({ code: 'EEXIST' })
+const eexist = error(ioError({ code: 'EEXIST', message: 'file already exists' }))
 
 /** @type {(dir: Dir, path: readonly string[]) => readonly [Dir, IoResult<void>]} */
 const createExclusiveOp = (dir, path) => {
@@ -307,11 +339,11 @@ const writeBytesRawOp = (offset, data) => (dir, p) => {
     const [name] = p
     const file = dir[name]
     if (file === undefined) { return [dir, enoent] }              // writeBytes never creates
-    if (!Array.isArray(file)) { return [dir, error(`'${name}' is not a file`)] }
-    if (!Number.isInteger(offset) || offset < 0) { return [dir, error(`Offset ${offset} is invalid`)] }
-    const chunks = /** @type {readonly Vec[]} */ (file)
+    if (!Array.isArray(file)) { return [dir, fail(`'${name}' is not a file`)] }
+    if (!Number.isInteger(offset) || offset < 0) { return [dir, fail(`Offset ${offset} is invalid`)] }
+    const chunks = file
     if (offset !== fileSizeBytes(chunks)) {
-        return [dir, error(`writeBytes offset ${offset} must equal the file size (append-only)`)]
+        return [dir, fail(`writeBytes offset ${offset} must equal the file size (append-only)`)]
     }
     return [{ ...dir, [name]: [...chunks, data] }, okVoid]
 }
@@ -324,43 +356,46 @@ const statOp = readOperation((dir, path) => {
     if (path.length !== 1) { return enoent }
     const file = dir[path[0]]
     if (file === undefined) { return enoent }
-    if (!Array.isArray(file)) { return error(`'${path[0]}' is not a file`) }
-    return ok({ size: fileSizeBytes(/** @type {readonly Vec[]} */ (file)) })
+    if (!Array.isArray(file)) { return fail(`'${path[0]}' is not a file`) }
+    return ok({ size: fileSizeBytes(file) })
 })
 
-/** @type {MemOperationMap<NodeOp, State>} */
+/** @type {PartialMemOperationMap<NodeOp, State>} */
 const map = {
     all: (...a) => state => {
-        /** @type {readonly unknown[]} */
+        // Each entry is the effect's whole `Result`: `all`'s own envelope says
+        // only whether the runner could dispatch it, so the inner answers pass
+        // through untouched for `allOk` to collapse.
+        /** @type {readonly Result<unknown, unknown>[]} */
         let e = []
         for (const i of a) {
             const [ns, ei] = virtual(state)(i)
             state = ns
             e = [...e, ei]
         }
-        return [state, e]
+        return [state, ok(e)]
     },
     memCreate: value => state => {
         const id = `mem${state.memoryNext}`
-        const key = /** @type {Key<unknown>} */ (asNominal(id))
+        const key = asNominal(id)
         return [{
             ...state,
             memoryNext: state.memoryNext + 1,
             memoryValues: { ...state.memoryValues, [id]: value },
-        }, key]
+        }, ok(key)]
     },
     memRead: key => state =>
-        [state, state.memoryValues[asBase(key)]],
+        [state, ok(state.memoryValues[asBase(key)])],
     memWrite: (key, value) => state => {
         const id = asBase(key)
         return [{
             ...state,
             memoryValues: { ...state.memoryValues, [id]: value },
-        }, undefined]
+        }, okVoid]
     },
     fetch: url => state => {
         const result = state.internet[url]
-        return result === undefined ? [state, error('not found')] : [state, ok(result)]
+        return result === undefined ? [state, fail('not found')] : [state, ok(result)]
     },
     mkdir: (path, p) => mkdir(p !== undefined)(path),
     readFile,
@@ -374,12 +409,8 @@ const map = {
     createExclusive,
     writeBytes: writeBytesOp,
     stat: statOp,
-    randomInt: () => state => [{ ...state, randomNext: state.randomNext + 1 }, state.randomNext],
-    exec: todo,
-    createServer: todo,
-    listen: todo,
-    forever: todo,
-    now: () => state => [state, state.epochNs],
+    randomInt: () => state => [{ ...state, randomNext: state.randomNext + 1 }, ok(state.randomNext)],
+    now: () => state => [state, ok(state.epochNs)],
     // Virtual sandbox is a pass-through: the fixture's test function is
     // expected to return a `SandboxResult` directly (encoding pass/fail and a
     // chosen duration), so the handler invokes it without try/catch or clock
@@ -387,23 +418,35 @@ const map = {
     // result instead of the runner measuring real execution. A genuine
     // exception in a fixture propagates loudly as a bug in the fixture.
     // See: issues/156-tf-virtual-tests.md
-    sandbox: f => state => [state, /** @type {SandboxResult<unknown>} */ (f())],
-    await: p => state => [state, [p]],
-    test: todo,
+    sandbox: f => state => [state, ok(/** @type {SandboxResult<unknown>} */ (f()))],
+    await: p => state => [state, ok([p])],
     write: (stream, data) => state => {
         const s = utf8ToString(data)
-        return [{ ...state, [stream]: `${state[stream]}${s}` }, undefined]
+        return [{ ...state, [stream]: `${state[stream]}${s}` }, okVoid]
     },
     read: () => state => {
         const [first, ...rest] = state.stdin
         return state.stdin.length === 0
-            ? [state, null]
-            : [{ ...state, stdin: rest }, first]
+            ? [state, ok(null)]
+            : [{ ...state, stdin: rest }, ok(first)]
     },
 }
 
-/** @type {RunInstance<NodeOp, State>} */
-export const virtual = run(map)
+/**
+ * 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 const virtual = partialRun(nodeCommands)(map)
 
 const testContext = { test: todo }