functionalscript 0.43.1 → 0.44.0

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

@@ -0,0 +1,444 @@
+/**
+ * @import { Vec } from "../../types/bit_vec/types.ts"
+ * @import { IoResult, ReadFile } from "./types.ts"
+ * @import { Dir } from "./virtual/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 { 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"
+import { assert, assertEq, assertNotNullish } from '../../asserts/module.f.mjs'
+import { ok } from '../../types/result/module.f.mjs'
+
+// Answers the one command the `map` proof below drives. Routing the loop
+// through `match` keeps the `Pure`/`Do` layout out of this module: the map key
+// is the command assertion, and `MatchResult` types the continuation.
+/** @type {OperationMap<ReadFile, IoResult<Vec>>} */
+const readHelloMap = {
+    readFile: path => {
+        assertEq(path, 'hello')
+        return ok(vec8(0x15n))
+    },
+}
+
+const readHello = match(readHelloMap)
+
+export const proof = {
+    externalTestContext: () => {
+        assert(usesInlineTestContext('node', 'v22.20.0'))
+        assert(usesInlineTestContext('node', '25.99.99'))
+        assert(!usesInlineTestContext('node', '26.0.0'))
+        assert(!usesInlineTestContext('node', '26.1.0'))
+        assert(!usesInlineTestContext('node'))
+        assert(usesInlineTestContext('bun'))
+        assert(!usesInlineTestContext('deno', '22.0.0'))
+        assert(versionLessThan('25.99.99', '26.0.0'))
+        assert(versionLessThan('26.0.0', '26.1.0'))
+        assert(versionLessThan('26.1.0', '26.1.1'))
+        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)
+            })
+        //
+        let r = readHello(e)
+        while (r[0] === 'cont') {
+            r = readHello(r[2](r[1]))
+        }
+        assertEq(r[1], 0x2An)
+    },
+    fetch: () => {
+        const [_, [t, result]] = virtual({
+            ...emptyState,
+            internet: {
+                'https://example.com/data': vec8(0x2An),
+            },
+        })(fetch('https://example.com/data'))
+        assert(t !== 'error', result)
+        assert(isVec(result), result)
+        assertEq(uint(result), 0x2An, result)
+    },
+    mkdir: {
+        one: () => {
+            const [state, [t, result]] = virtual(emptyState)(mkdir('a'))
+            assert(t !== 'error', result)
+            const a = state.root.a
+            assert(!(a === undefined || Array.isArray(a)), a)
+        },
+        rec: () => {
+            const [state, [t, result]] = virtual(emptyState)(
+                mkdir('tmp/cache', { recursive: true })
+            )
+            assert(t === 'ok', result)
+            const tmp = state.root.tmp
+            assert(!(typeof tmp !== 'object' || Array.isArray(tmp)), state.root)
+            const cache = (/** @type {Dir} */ (tmp)).cache
+            assert(!(typeof cache !== 'object' || Array.isArray(cache)), tmp)
+        },
+        nonRec: () => {
+            const [state, [t, result]] = virtual(emptyState)(
+                mkdir('tmp/cache')
+            )
+            assert(t === 'error', result)
+            assertEq(state.root.tmp, undefined)
+        }
+    },
+    readFile: {
+        one: () => {
+            const initial = {
+                ...emptyState,
+                root: {
+                    hello: [vec8(0x2An)],
+                },
+            }
+            const [state, [t, result]] = virtual(initial)(readFile('hello'))
+            assert(t !== 'error', result)
+            assert(isVec(result), result)
+            assertEq(uint(result), 0x2An, result)
+            assert(state.root.hello !== undefined, state.root)
+        },
+        nested: () => {
+            const [_, [tag, result]] = virtual({
+                ...emptyState,
+                root: { tmp: { cache: [vec8(0x15n)] } }
+            })(readFile('tmp/cache'))
+            assert(tag !== 'error', result)
+            assertEq(uint(result), 0x15n, result)
+        },
+        noSuchFile: () => {
+            const [_, [t, result]] = virtual(emptyState)(readFile('hello'))
+            assert(t === 'error', result)
+        },
+        nestedPath: () => {
+            const [_, [t, result]] = virtual(emptyState)(readFile('tmp/cache'))
+            assert(t === 'error', result)
+            if ((/** @type {{ code?: unknown }} */ (result)).code !== 'ENOENT') { throw result }
+        },
+        withinLimit: () => {
+            // Test with a small file well within the 131,072 byte limit
+            const initial = {
+                ...emptyState,
+                root: {
+                    smallFile: [vec8(0x2An)],
+                },
+            }
+            const [_, [t, result]] = virtual(initial)(readFile('smallFile'))
+            assert(t !== 'error', result)
+            assert(isVec(result), result)
+        }
+    },
+    readUtf8File: {
+        ok: () => {
+            const [_, [t, result]] = virtual({
+                ...emptyState,
+                root: { hello: [utf8('Hello, world!')] },
+            })(readUtf8File('hello'))
+            assert(t === 'ok', result)
+            assertEq(result, 'Hello, world!')
+        },
+        noSuchFile: () => {
+            const [_, [t, result]] = virtual(emptyState)(readUtf8File('hello'))
+            assert(t === 'error', result)
+        },
+    },
+    readdir: {
+        one: () => {
+            const [_, [t, result]] = virtual({
+                ...emptyState,
+                root: {
+                    file: [vec8(0x2An)],
+                    dir: {
+                        a: [empty]
+                    },
+                },
+            })(readdir('', { recursive: true }))
+            assert(t === 'ok', result)
+            const file = result.find(x => x.name === 'file')
+            if (file === undefined || file.parentPath !== '' || !file.isFile) { throw `file: ${file}` }
+            const dirA = result.find(x => x.name === 'a')
+            if (dirA === undefined || dirA.parentPath !== '/dir') { throw `dirA: ${dirA?.parentPath}` }
+        },
+        nonRecursive: () => {
+            const [_, [t, result]] = virtual({
+                ...emptyState,
+                root: {
+                    file: [vec8(0x2An)],
+                    dir: {
+                        a: [empty]
+                    },
+                },
+            })(readdir('', { }))
+            assert(t === 'ok', result)
+            assertEq(result.length, 2, result)
+            assertNotNullish(result.find(x => x.name === 'file'))
+            assertNotNullish(result.find(x => x.name === 'dir'))
+        },
+        nested: () => {
+            const [_, [t, result]] = virtual({
+                ...emptyState,
+                root: { tmp: { cache: [vec8(0x15n)] } }
+            })(readdir('tmp', { recursive: true }))
+            assert(t === 'ok', result)
+            assertEq(result.length, 1, result)
+            const [r0] = result
+            assertEq(r0.name, 'cache', r0)
+            assertEq(r0.parentPath, 'tmp', r0)
+        },
+        noSuchDir: () => {
+            const [_, [t, result]] = virtual(emptyState)(readdir('tmp', { recursive: true }))
+            assert(t === 'error', result)
+            assertEq(result, 'invalid path')
+        },
+    },
+    writeFile: {
+        one: () => {
+            const [state, [t, result]] = virtual(emptyState)(
+                writeFile('hello', vec8(0x2An))
+            )
+            assert(t === 'ok', result)
+            const file = state.root.hello
+            assert(Array.isArray(file), file)
+            assertEq(uint(file[0]), 0x2An, file)
+        },
+        overwrite: () => {
+            const [state, [t, result]] = virtual({
+                ...emptyState,
+                root: {
+                    hello: [vec8(0x15n)],
+                },
+            })(
+                writeFile('hello', vec8(0x2An))
+            )
+            assert(t === 'ok', result)
+            const file = state.root.hello
+            assert(Array.isArray(file), file)
+            assertEq(uint(file[0]), 0x2An, file)
+        },
+        nestedPath: () => {
+            const [state, [t, result]] = virtual(emptyState)(
+                writeFile('tmp/cache', vec8(0x2An))
+            )
+            assert(t === 'error', result)
+            assertEq(result, 'invalid file')
+            assertEq(state.root.tmp, undefined, state.root)
+        },
+        directory: () => {
+            const [state, [t, result]] = virtual({
+                ...emptyState,
+                root: {
+                    tmp: {},
+                },
+            })(
+                writeFile('tmp', vec8(0x2An))
+            )
+            assert(t === 'error', result)
+            assertEq(result, 'invalid file')
+            const tmp = state.root.tmp
+            assert(!(tmp === undefined || Array.isArray(tmp)), tmp)
+        },
+    },
+    writeUtf8File: () => {
+        const [state, [t, result]] = virtual(emptyState)(
+            writeUtf8File('hello', 'Hello, world!')
+        )
+        assert(t === 'ok', result)
+        const file = state.root.hello
+        assert(Array.isArray(file), file)
+        assertEq(utf8ToString(file[0]), 'Hello, world!', file)
+    },
+    rm: {
+        one: () => {
+            const [state, [t, result]] = virtual({
+                ...emptyState,
+                root: { hello: [vec8(0x2An)] },
+            })(rm('hello'))
+            assert(t === 'ok', result)
+            assertEq(state.root.hello, undefined, state.root)
+        },
+        nested: () => {
+            const [state, [t, result]] = virtual({
+                ...emptyState,
+                root: { tmp: { cache: [vec8(0x15n)] } },
+            })(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)
+        },
+        noSuchFile: () => {
+            const [_, [t, result]] = virtual(emptyState)(rm('hello'))
+            assert(t === 'error', result)
+            assertEq(result, 'no such file')
+        },
+        isDirectory: () => {
+            const [state, [t, result]] = virtual({
+                ...emptyState,
+                root: { tmp: {} },
+            })(rm('tmp'))
+            assert(t === 'error', result)
+            assertEq(result, 'invalid path')
+            assert(state.root.tmp !== undefined, state.root)
+        },
+    },
+    both: () => {
+        const [_, results] = virtual({
+            ...emptyState,
+            root: {
+                a: [vec8(0x2An)],
+                b: [vec8(0x15n)],
+            },
+        })(both(readFile('a'))(readFile('b')))
+        assert(results[0][0] === 'ok', results[0])
+        assert(results[1][0] === 'ok', results[1])
+        assertEq(uint(results[0][1]), 0x2An, results[0][1])
+        assertEq(uint(results[1][1]), 0x15n, results[1][1])
+    },
+    now: () => {
+        const [_, result] = virtual({ ...emptyState, epochNs: 1_000_000 })(now())
+        assertEq(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 })))
+            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 })))
+            assert(result[0] === 'error', result)
+            assertEq(result[1], err)
+        },
+    },
+    memory: {
+        createAndRead: () => {
+            const effect = step(memCreate(42), key => memRead(key))
+            const [_, value] = virtual(emptyState)(effect)
+            assertEq(value, 42)
+        },
+        createAndWrite: () => {
+            const effect = step(
+                    memCreate(1),
+                    key => step(
+                        memWrite(key, 99),
+                        () => memRead(key)))
+            const [_, value] = virtual(emptyState)(effect)
+            assertEq(value, 99)
+        },
+    },
+    rename: {
+        fileOverFile: () => {
+            const [state, [t, result]] = virtual({
+                ...emptyState,
+                root: { src: [vec8(0x2An)], dst: [vec8(0x15n)] },
+            })(rename('src', 'dst'))
+            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)
+        },
+        nestedRename: () => {
+            const [state, [t, result]] = virtual({
+                ...emptyState,
+                root: { tmp: { src: [vec8(0x2An)] } },
+            })(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)
+        },
+        dirOverFile: () => {
+            const [state, [t, result]] = virtual({
+                ...emptyState,
+                root: { src: {}, dst: [vec8(0x15n)] },
+            })(rename('src', 'dst'))
+            assert(t === 'error', result)
+            assert(Array.isArray(state.root.dst), state.root)
+        },
+        missingSource: () => {
+            const [_, [t, result]] = virtual(emptyState)(rename('missing', 'dst'))
+            assert(t === 'error', result)
+        },
+    },
+    readBytes: {
+        simple: () => {
+            const [_, [t, result]] = virtual({
+                ...emptyState,
+                root: { file: [vec8(0xABn)] },
+            })(readBytes('file', 0, 1))
+            assert(t === 'ok', result)
+            assert(isVec(result), result)
+        },
+        withOffset: () => {
+            const [_, [t, result]] = virtual({
+                ...emptyState,
+                root: { file: [vec8(0xABn), vec8(0xCDn)] },
+            })(readBytes('file', 1, 1))
+            assert(t === 'ok', result)
+            assert(isVec(result), result)
+        },
+        oversizeChunk: () => {
+            const [_, [t, result]] = virtual({
+                ...emptyState,
+                root: { file: [vec8(0x2An)] },
+            })(readBytes('file', 0, Number(2n ** 32n)))
+            assert(t === 'error', result)
+        },
+        missingFile: () => {
+            const [_, [t, result]] = virtual(emptyState)(readBytes('missing', 0, 4))
+            assert(t === 'error', result)
+        },
+    },
+    randomInt: {
+        increments: () => {
+            const [state1, r1] = virtual(emptyState)(randomInt())
+            assertEq(r1, 0)
+            const [state2, r2] = virtual(state1)(randomInt())
+            assertEq(r2, 1)
+            const [_, r3] = virtual(state2)(randomInt())
+            assertEq(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>>} */
+            const chunks = listEmpty()
+            const [state, [t, result]] = virtual({
+                ...emptyState,
+                root: { hello: [vec8(0x2An)] },
+            })(writeFromStream('hello', chunks))
+            assert(t === 'error', result)
+            const file = state.root.hello
+            assert(!(!Array.isArray(file) || uint(file[0]) !== 0x2An), file)
+        },
+        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())
+            const [_, [t, result]] = virtual(emptyState)(
+                writeFromStream('hello', chunks)
+            )
+            assert(t === 'error', result)
+            assertEq(result, 'invalid buffer size')
+        },
+    },
+}

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

@@ -0,0 +1,203 @@
+/**
+ * Types for Node.js effect operations.
+ *
+ * @module
+ */
+import type { List as EffectList } from '../../types/list/types.ts';
+import type { Vec } from '../../types/bit_vec/types.ts';
+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 { List } from '../list/types.ts';
+export type IoResult<T> = Result<T, unknown>;
+export type All = ['all', <T>(...effects: Effect<never, T>[]) => readonly T[]];
+export type Fetch = ['fetch', (url: string) => IoResult<Vec>];
+export type MakeDirectoryOptions = {
+    readonly recursive: true;
+};
+export type Mkdir = readonly ['mkdir', (path: string, options?: MakeDirectoryOptions) => IoResult<void>];
+/**
+ * Reads a file as a bit vector. File size is limited to 131,072 bytes (128 KiB)
+ * to respect Bun's `bigint` size constraint (1,048,575 bits), which is the
+ * minimal limit across all runtime environments supported by FunctionalScript.
+ * Files exceeding this limit will fail with a validation error.
+ */
+export type ReadFile = readonly ['readFile', (path: string) => IoResult<Vec>];
+/**
+ * Represents a directory entry (file or directory) in the filesystem
+ * @see https://nodejs.org/api/fs.html#class-fsdirent
+ */
+export type Dirent = {
+    readonly name: string;
+    readonly parentPath: string;
+    readonly isFile: boolean;
+};
+export type ReaddirOptions = {
+    readonly recursive?: true;
+};
+export type Readdir = readonly ['readdir', (path: string, options: ReaddirOptions) => IoResult<readonly Dirent[]>];
+export type WriteFile = readonly ['writeFile', (path: string, data: Vec) => IoResult<void>];
+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 ExecResult = {
+    readonly stdout: string;
+    readonly stderr: string;
+};
+export type Exec = readonly ['exec', (command: string, stdin?: string) => IoResult<ExecResult>];
+export type Access = readonly ['access', (path: string) => IoResult<void>];
+/**
+ * Creates `path` as an empty file with `O_CREAT|O_EXCL` — fails if it already
+ * exists. This is the exclusive create that claims a staging name in the
+ * lock-free upload ([staging-lease.md](../../cas/plan/staging-lease.md));
+ * with 256 random bits in the name `EEXIST` never happens in practice, so it
+ * is just a sanity guard.
+ */
+export type CreateExclusive = readonly ['createExclusive', (path: string) => IoResult<void>];
+/**
+ * Writes the **entire** `data` vector to an **existing** `path` at byte `offset`
+ * (positional write). The mirror of `readBytes`: it never creates the file
+ * (a missing path is `ENOENT`), and it writes every byte or returns an error —
+ * the runner loops over short writes — so a later size check can never pass over
+ * a hole. Bounded to ≤128 KiB per call, like `readBytes`.
+ */
+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>>;
+/** File metadata returned by `stat`. Only `size` (in bytes) for now. */
+export type FileStat = {
+    readonly size: number;
+};
+export type Stat = readonly ['stat', (path: string) => IoResult<FileStat>];
+export type Fs = Mkdir | ReadFile | ReadBytes | Readdir | WriteFile | Rm | Rename | Exec | Access | CreateExclusive | WriteBytes | Stat;
+export type Server = Nominal<'server', `160855c4f69310fece3273c1853ac32de43dee1eb41bf59d821917f8eebe9272`, unknown>;
+export type Headers = StringMap<string>;
+export type IncomingMessage = {
+    readonly method: string;
+    readonly url: string;
+    readonly headers: Headers;
+    readonly body: Vec;
+};
+export type ServerResponse = {
+    readonly status: number;
+    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];
+export type Http = CreateServer | Listen;
+export type Forever = ['forever', () => never];
+export type Module = StringMap<unknown>;
+export type Import = ['import', (path: string) => IoResult<Module>];
+/** Named output streams accepted by the `Write` effect. */
+export type WriteConsoles = 'stdout' | 'stderr';
+/**
+ * Raw byte write to a named output stream. Encoding-agnostic — callers supply
+ * 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 Console = (s: string) => Effect<Write, void>;
+/** Named input streams accepted by the `Read` effect. */
+export type ReadConsoles = 'stdin';
+/**
+ * Reads a single byte from a named input stream — the byte-granular dual of
+ * `write`. Resolves to the byte value (`0`–`255`) or `null` at end of
+ * input (EOF). One byte at a time: the effect carries no buffering or line
+ * policy, so higher-level framing (see `readLine`) lives in pure code
+ * 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];
+/** @internal */
+export type _UtfList = EffectList<number>;
+export type Now = readonly ['now', () => number];
+/**
+ * The outcome of a `Sandbox` operation.
+ *
+ * `result` carries either `['ok', value]` or `['error', thrown]`. `duration`
+ * is a floating-point millisecond count with up to microsecond precision,
+ * matching `performance.now()` directly. Additional fields (allocated memory,
+ * max stack depth, coverage) may be added in future without breaking consumers.
+ */
+export type SandboxResult<T> = {
+    readonly result: Result<T, unknown>;
+    /**
+     * Elapsed time in milliseconds (microsecond precision via `performance.now()`).
+     * The virtual runner returns `0` for deterministic tests.
+     */
+    readonly duration: number;
+};
+export type Sandbox = readonly ['sandbox', <T>(f: () => T) => 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
+ * throws. If `p` is any other value it is returned as-is. Plain thenables
+ * (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]];
+/**
+ * Signature of a framework test-registration function (e.g. `nodeTest.test`,
+ * `bunTest.test`). Returns `Promise<void>` so async sub-tests can be awaited.
+ */
+export type TestFn = (name: string, options: {
+    readonly expectFailure: boolean;
+}, fn: (t: TestContext) => Promise<void>) => Promise<void>;
+/**
+ * A thin wrapper around a framework's `test` function. Passed through
+ * `registerModule` so nested test registration uses the appropriate context
+ * (e.g. `inlineContext` on Bun, which does not support nested `test()` calls
+ * inside a callback).
+ */
+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];
+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 NodeOperationMap = ToAsyncOperationMap<NodeOp>;
+/**
+ * The environment variables.
+ */
+export type Env = {
+    readonly [k: string]: string | undefined;
+};
+/** Identifies the JavaScript runtime detected at startup. */
+export type Engine = 'node' | 'bun' | 'deno';
+/**
+ * Runtime options passed to every `NodeProgram`.
+ *
+ * - `args`: command-line arguments (equivalent to `process.argv.slice(2)`).
+ * - `env`: process environment variables.
+ * - `std`: TTY flags for `stdout` and `stderr`, known at startup and used by
+ *   `csiWrite` to decide whether to strip ANSI SGR sequences.
+ * - `testContext`: Node `--test` context; used by `register` on Node.
+ * - `bunTestContext`: Bun-compatible context that flattens nested tests inline,
+ *   working around Bun's lack of nested `test()` support.
+ * - `engine`: runtime detected at startup; controls which context `register` selects.
+ * - `nodeVersion`: detected Node version; absent for other and virtual runtimes.
+ * - `inlineTestContext`: whether the selected context flattens nested tests.
+ */
+export type NodeProgramOptions = {
+    readonly args: readonly string[];
+    readonly env: Env;
+    readonly home: string;
+    readonly std: {
+        readonly [k in WriteConsoles]: {
+            readonly isTTY: boolean;
+        };
+    };
+    readonly testContext: TestContext;
+    readonly bunTestContext: TestContext;
+    readonly engine: Engine;
+    readonly nodeVersion?: string;
+    readonly inlineTestContext: boolean;
+};
+export type Program<O extends Operation> = (options: NodeProgramOptions) => Effect<O, number>;
+export type NodeProgram = Program<NodeOp>;

package/fjs/effects/node/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for Node.js effect operations.
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,31 @@
+/**
+ * Virtual Node-effect operations for filesystem and process tests.
+ *
+ * @module
+ */
+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>} */
+export declare const virtual: RunInstance<NodeOp, State>;
+/**
+ * Safe, inert defaults for every {@link NodeProgramOptions} field, intended for
+ * proof files that need to call a program without owning the full literal.
+ *
+ * Proofs spread-override only what their test cares about:
+ *
+ * ```ts
+ * const opts: NodeProgramOptions = { ...defaultNodeProgramOptions, args }
+ * ```
+ *
+ * Future additions to `NodeProgramOptions` only need a default added here,
+ * keeping unrelated proof files from churning.
+ *
+ * @type {NodeProgramOptions}
+ */
+export declare const defaultNodeProgramOptions: NodeProgramOptions;