functionalscript 0.43.1 → 0.44.0

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

@@ -0,0 +1,226 @@
+import { assert, assertEq } from '../../../asserts/module.f.mjs'
+import { access, awaitIfPromise, fetch, rm, writeFile, readFile, readdir, import_, rename, readBytes, writeBytes, stat } from '../module.f.mjs'
+import { maxLengthBytes, vec, vec8 } from '../../../types/bit_vec/module.f.mjs'
+import { emptyState, virtual } from './module.f.mjs'
+/** @import { Dir, JsModule } from './types.ts' */
+
+export const proof = {
+    rm: {
+        success: () => {
+            /** @type {Dir} */
+            const root = { 'a.txt': [vec8(0x42n)] }
+            const [, result] = virtual({ ...emptyState, root })(rm('a.txt'))
+            assert(result[0] === 'ok')
+        },
+        notFound: () => {
+            const [, result] = virtual(emptyState)(rm('notexist.txt'))
+            assert(result[0] === 'error')
+        },
+        isDirectory: () => {
+            /** @type {Dir} */
+            const inner = {}
+            /** @type {Dir} */
+            const root = { 'mydir': inner }
+            const [, result] = virtual({ ...emptyState, root })(rm('mydir'))
+            assert(result[0] === 'error')
+        },
+    },
+    writeFileOnDirectory: () => {
+        /** @type {Dir} */
+        const inner = {}
+        /** @type {Dir} */
+        const root = { 'mydir': inner }
+        const [, result] = virtual({ ...emptyState, root })(writeFile('mydir', vec8(0x42n)))
+        assert(result[0] === 'error')
+    },
+    readdirRecursive: () => {
+        const file = /** @type {const} */ ([vec8(0x42n)])
+        /** @type {Dir} */
+        const sub = { 'file.txt': file }
+        /** @type {Dir} */
+        const outer = { 'sub': sub }
+        /** @type {Dir} */
+        const root = { 'mydir': outer }
+        const [, result] = virtual({ ...emptyState, root })(readdir('mydir', { recursive: true }))
+        assert(result[0] === 'ok')
+        assert(result[0] === 'ok', result)
+        assertEq(result[1].length, 2)
+    },
+    accessNestedPathThroughFile: () => {
+        // 'a/b/c' where 'a' is a file: the operation wrapper's "not a directory"
+        // fallback passes the full remaining path through unchanged, covering the
+        // path.length !== 1 branch of the access op (only path.length === 0 was
+        // otherwise exercised).
+        /** @type {Dir} */
+        const root = { 'a': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(access('a/b/c'))
+        assert(result[0] === 'error')
+    },
+    readFileIntoDir: () => {
+        // 'a/b' where both 'a' and 'b' are directories
+        // hits path.length === 0 in operation's f and path.length !== 1 in readFile op
+        /** @type {Dir} */
+        const inner = {}
+        /** @type {Dir} */
+        const outer = { 'b': inner }
+        /** @type {Dir} */
+        const root = { 'a': outer }
+        const [, result] = virtual({ ...emptyState, root })(readFile('a/b'))
+        assert(result[0] === 'error')
+    },
+    awaitNonPromise: () => {
+        // a non-promise value passes through the virtual `await` handler as-is
+        const [, result] = virtual(emptyState)(awaitIfPromise(42))
+        assertEq(result, 42)
+    },
+    fetchNotFound: () => {
+        // covers the `result === undefined` branch of the `fetch` handler
+        const [, result] = virtual(emptyState)(fetch('https://example.com/missing'))
+        assert(result[0] === 'error')
+    },
+    importNestedPath: () => {
+        // import_ on a path whose parent does not exist covers the
+        // path.length !== 1 branch of the import_ op
+        const [, result] = virtual(emptyState)(import_('a/b'))
+        assert(result[0] === 'error')
+    },
+    importNonModule: () => {
+        // import_ on a Vec (not a JsModule) covers typeof entry !== 'function' branch
+        /** @type {Dir} */
+        const root = { 'module.f.ts': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(import_('module.f.ts'))
+        assert(result[0] === 'error')
+    },
+    throw: {
+        readFileOnJsModule: () => {
+            // readFile on a JsModule path covers typeof file === 'function' branch
+            /** @type {Dir} */
+            const root = { 'a.f.ts': /** @type {JsModule} */ (() => ({})) }
+            virtual({ ...emptyState, root })(readFile('a.f.ts'))
+        },
+    },
+    renameSamePath: () => {
+        // rename('a', 'a') should succeed as a no-op, not reject
+        /** @type {Dir} */
+        const root = { 'a': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(rename('a', 'a'))
+        assert(result[0] === 'ok')
+    },
+    renameIntoOwnSubtree: () => {
+        // rename('a', 'a/b') should fail (dst inside src's subtree)
+        /** @type {Dir} */
+        const root = { 'a': { 'b': [vec8(0x42n)] } }
+        const [, result] = virtual({ ...emptyState, root })(rename('a', 'a/b'))
+        assert(result[0] === 'error')
+    },
+    renameOntoOwnAncestor: () => {
+        // rename('a/b', 'a') should fail (src inside dst's subtree)
+        /** @type {Dir} */
+        const root = { 'a': { 'b': [vec8(0x42n)] } }
+        const [, result] = virtual({ ...emptyState, root })(rename('a/b', 'a'))
+        assert(result[0] === 'error')
+    },
+    renameNonEmptyDirOverEmptyDir: () => {
+        // rename a directory onto an empty directory should succeed
+        /** @type {Dir} */
+        const root = { 'src': { 'file': [vec8(0x42n)] }, 'dst': {} }
+        const [, result] = virtual({ ...emptyState, root })(rename('src', 'dst'))
+        assert(result[0] === 'ok')
+    },
+    renameEmptyDirOverNonEmptyDir: () => {
+        // rename an empty directory onto a non-empty directory should fail
+        /** @type {Dir} */
+        const root = { 'src': {}, 'dst': { 'file': [vec8(0x42n)] } }
+        const [, result] = virtual({ ...emptyState, root })(rename('src', 'dst'))
+        assert(result[0] === 'error')
+    },
+    renameFileOntoDirectory: () => {
+        // rename a file to a path that is already an existing directory should fail
+        /** @type {Dir} */
+        const root = { 'myfile': [vec8(0x42n)], 'mydir': {} }
+        const [, result] = virtual({ ...emptyState, root })(rename('myfile', 'mydir'))
+        assert(result[0] === 'error')
+    },
+    readFileTooLarge: () => {
+        // a file stored as two max-size chunks exceeds the limit; readFile must return an error
+        const chunk0 = vec(maxLengthBytes * 8n)(0n)
+        const chunk1 = vec(1n)(1n)
+        /** @type {Dir} */
+        const root = { 'big': [chunk0, chunk1] }
+        const [, result] = virtual({ ...emptyState, root })(readFile('big'))
+        assert(result[0] === 'error')
+    },
+    readBytesNegativeSize: () => {
+        // readBytes with negative size should fail
+        /** @type {Dir} */
+        const root = { 'file': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', 0, -1))
+        assert(result[0] === 'error')
+    },
+    readBytesZeroSize: () => {
+        // readBytes with zero size should succeed and return empty vec
+        /** @type {Dir} */
+        const root = { 'file': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', 0, 0))
+        assert(result[0] === 'ok')
+    },
+    readBytesNegativeOffset: () => {
+        // readBytes with negative offset should fail
+        /** @type {Dir} */
+        const root = { 'file': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', -1, 1))
+        assert(result[0] === 'error')
+    },
+    readBytesFractionalSize: () => {
+        // readBytes with fractional size should fail rather than throw RangeError
+        /** @type {Dir} */
+        const root = { 'file': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', 0, 1.5))
+        assert(result[0] === 'error')
+    },
+    readBytesFractionalOffset: () => {
+        // readBytes with fractional offset should fail rather than throw RangeError
+        /** @type {Dir} */
+        const root = { 'file': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', 0.5, 1))
+        assert(result[0] === 'error')
+    },
+    readBytesAcrossChunkBoundary: () => {
+        // Two 128 KiB chunks; read 2 bytes spanning the boundary (last byte of chunk 0, first of chunk 1).
+        const chunkSize = Number(maxLengthBytes)
+        const chunk0 = vec(maxLengthBytes * 8n)(0xAAn)
+        const chunk1 = vec(maxLengthBytes * 8n)(0xBBn)
+        /** @type {Dir} */
+        const root = { 'big': [chunk0, chunk1] }
+        const [, result] = virtual({ ...emptyState, root })(readBytes('big', chunkSize - 1, 2))
+        assert(result[0] === 'ok')
+    },
+    writeBytesWrongOffset: () => {
+        // writeBytes is append-only; an offset that doesn't match the current
+        // file size must fail rather than silently create a hole.
+        /** @type {Dir} */
+        const root = { 'file': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(writeBytes('file', 5, vec8(0x43n)))
+        assert(result[0] === 'error')
+    },
+    statOnJsModule: () => {
+        // stat on a JsModule entry (neither an array nor a descendable
+        // directory) covers the !Array.isArray(file) branch of statOp.
+        /** @type {Dir} */
+        const root = { 'a.f.ts': /** @type {JsModule} */ (() => ({})) }
+        const [, result] = virtual({ ...emptyState, root })(stat('a.f.ts'))
+        assert(result[0] === 'error')
+        assertEq(result[1], `'a.f.ts' is not a file`)
+    },
+    largeFileReadBytes: () => {
+        // A file stored as two 128 KiB chunks is larger than maxLengthBytes.
+        // readBytes within the second chunk (offset = 128 KiB, size = 1) should succeed.
+        const chunkSize = Number(maxLengthBytes)
+        const chunk0 = vec(maxLengthBytes * 8n)(0n)
+        const chunk1 = vec(maxLengthBytes * 8n)(0xFFn)
+        /** @type {Dir} */
+        const root = { 'large': [chunk0, chunk1] }
+        const [, result] = virtual({ ...emptyState, root })(readBytes('large', chunkSize, 1))
+        assert(result[0] === 'ok')
+    },
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Types for the virtual Node-effect operations used by filesystem and
+ * process tests.
+ *
+ * @module
+ */
+import type { Vec } from '../../../types/bit_vec/types.ts';
+import type { Module } from '../types.ts';
+/**
+ * In-memory JS module entry. When `import_` is called on the path, the
+ * function is invoked and its return value is the module value (with a
+ * `default` export and optional named exports). Using a function (not a
+ * plain value) lets the entry be distinguished from `Vec`/`Dir` at runtime
+ * via `typeof === 'function'`, and lets the fixture compute the module on
+ * each import for closures/state.
+ */
+export type JsModule = () => Module;
+/** @internal */
+export type _Entity = readonly Vec[] | Dir | JsModule;
+export type Dir = {
+    readonly [name in string]?: _Entity;
+};
+export type State = {
+    stdout: string;
+    stderr: string;
+    /** Remaining stdin bytes; each `read` pops the first, `null` at EOF. */
+    stdin: readonly number[];
+    root: Dir;
+    internet: {
+        readonly [url: string]: Vec;
+    };
+    epochNs: number;
+    memoryNext: number;
+    memoryValues: {
+        readonly [key: string]: unknown;
+    };
+    /** Monotonically increasing counter returned by `randomInt`; starts at 0. */
+    randomNext: number;
+};

package/fjs/effects/node/virtual/types.js

@@ -0,0 +1,7 @@
+/**
+ * Types for the virtual Node-effect operations used by filesystem and
+ * process tests.
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,62 @@
+import type { Effect, Operation } from './types.ts';
+/**
+ * Asserts that `e` yields `expected` without performing a command. Exported so
+ * `eff/proof.f.ts` shares this definition instead of repeating it.
+ *
+ * Not `assertEq(runPure(e), [expected])`: `assertEq` compares with `===`, so a
+ * freshly allocated `[expected]` is never equal to the returned option. Assert
+ * the option's shape first, then compare the value inside it.
+ * @template {Operation} O
+ * @template T
+ * @param {Effect<O, T>} e
+ * @param {T} expected
+ */
+export declare const assertPure: <O extends Operation, T>(e: Effect<O, T>, expected: T) => void;
+export type _AddOp = readonly ['add', (a: number, b: number) => number];
+export type _AnyOp = readonly [string, (a: number) => number];
+export declare const proof: {
+    foldStep: {
+        empty: () => void;
+        threadsState: () => void;
+        order: () => void;
+    };
+    forEachStep: {
+        empty: () => void;
+        runs: () => void;
+    };
+    okStep: {
+        ok: () => void;
+        error: () => void;
+    };
+    runPure: {
+        pure: () => void;
+        pureNull: () => void;
+        do_: () => void;
+    };
+    doNode: () => void;
+    match: {
+        done: () => void;
+        cont: () => void;
+        ownCommand: () => void;
+        throw: {
+            constructorCommand: () => void;
+            toStringCommand: () => void;
+        };
+    };
+    step: {
+        pure: () => void;
+        chain: () => void;
+        overDo: () => void;
+    };
+    mapStep: {
+        pure: () => void;
+        constant: () => void;
+        overDo: () => void;
+    };
+    historyStep: {
+        pure: () => void;
+        overDo: () => void;
+        chain: () => void;
+        fReceivesWholeHistory: () => void;
+    };
+};

package/fjs/effects/proof.f.mjs

@@ -0,0 +1,231 @@
+import { step, do_, foldStep, forEachStep, mapStep, match, okStep, history, pure, runPure, historyStep } from './module.f.mjs'
+/** @import { Effect, Operation, OperationMap } from './types.ts' */
+import { error, ok } from '../types/result/module.f.mjs'
+import { assert, assertEq } from '../asserts/module.f.mjs'
+
+/**
+ * Asserts that `e` yields `expected` without performing a command. Exported so
+ * `eff/proof.f.ts` shares this definition instead of repeating it.
+ *
+ * Not `assertEq(runPure(e), [expected])`: `assertEq` compares with `===`, so a
+ * freshly allocated `[expected]` is never equal to the returned option. Assert
+ * the option's shape first, then compare the value inside it.
+ * @template {Operation} O
+ * @template T
+ * @param {Effect<O, T>} e
+ * @param {T} expected
+ */
+export const assertPure = (e, expected) => {
+    const o = runPure(e)
+    assert(o.length === 1, e)
+    assertEq(o[0], expected)
+}
+
+/** @typedef {readonly['add', (a: number, b: number) => number]} _AddOp */
+
+/** @type {(command: 'add') => (a: number, b: number) => Effect<_AddOp, number>} */
+const doAdd = do_
+
+const next = match(/** @type {OperationMap<_AddOp, number>} */ ({ add: (a, b) => a + b }))
+
+/**
+ * An operation set whose command is any `string`, which is what a `Do` node
+ * decoded from external input effectively is: `command` is runtime data, so
+ * nothing stops it naming a member `map` inherits from `Object.prototype`
+ * rather than an own handler. `match` must refuse those, and this type is how a
+ * proof says so without an `as` cast.
+ * @typedef {readonly[string, (a: number) => number]} _AnyOp
+ */
+
+/** @type {(command: string) => (a: number) => Effect<_AnyOp, number>} */
+const doAny = do_
+
+const anyNext = match(/** @type {OperationMap<_AnyOp, number>} */ ({ add: a => a + 1 }))
+
+export const proof = {
+    foldStep: {
+        empty: () => {
+            const e = foldStep(pure(/** @type {readonly number[]} */ ([])), 10, x => s => pure(s + x))
+            assertPure(e, 10)
+        },
+        threadsState: () => {
+            const e = foldStep(pure([1, 2, 3, 4]), 0, x => s => pure(s + x))
+            assertPure(e, 10)
+        },
+        order: () => {
+            const e = foldStep(pure(['a', 'b', 'c']), '', x => s => pure(s + x))
+            assertPure(e, 'abc')
+        },
+    },
+    forEachStep: {
+        empty: () => {
+            const e = forEachStep(pure(/** @type {readonly number[]} */ ([])), () => pure(undefined))
+            assertPure(e, undefined)
+        },
+        runs: () => {
+            const e = forEachStep(pure([1, 2, 3]), () => pure(undefined))
+            assertPure(e, undefined)
+        },
+    },
+    okStep: {
+        ok: () => {
+            const e = step(pure(ok(5)), okStep((/** @type {number} */ v) => pure(ok(v * 2))))
+            const o = runPure(e)
+            assert(o.length === 1, e)
+            const [r] = o
+            assert(r[0] === 'ok', r)
+            assertEq(r[1], 10)
+        },
+        error: () => {
+            const e = step(
+                pure(error(/** @type {string} */ ('oops'))),
+                okStep(/** @type {(value: number) => Effect<never, import('../types/result/types.ts').Result<number, string>>} */
+                    (v => pure(ok(v * 2)))))
+            const o = runPure(e)
+            assert(o.length === 1, e)
+            const [r] = o
+            assert(r[0] === 'error', r)
+            assertEq(r[1], 'oops')
+        },
+    },
+    runPure: {
+        pure: () => {
+            const o = runPure(pure(5))
+            assert(o.length === 1, o)
+            assertEq(o[0], 5)
+        },
+        // A pure `null` is `[null]`, never `[]`. Collapsing the two is what a
+        // `T | null` result would do, and why the option is tagged.
+        pureNull: () => {
+            const o = runPure(pure(null))
+            assertEq(o.length, 1, o)
+            assertEq(o[0], null)
+        },
+        do_: () => {
+            assertEq(runPure(doAdd('add')(2, 3)).length, 0)
+        },
+    },
+    // The one place a `Do` node is opened on purpose: `do_` builds the command,
+    // the payload it was called with, and a continuation that resumes with the
+    // command's output. Everything else goes through `step`, `match`, or
+    // `runPure`.
+    doNode: () => {
+        const e = doAdd('add')(2, 3)
+        assert(typeof e !== 'function', e)
+        const { command, payload, continuation } = e
+        assertEq(command, 'add')
+        const [a, b] = payload
+        assertEq(a, 2, payload)
+        assertEq(b, 3, payload)
+        assertPure(continuation(5), 5)
+    },
+    match: {
+        done: () => {
+            const r = next(pure(7))
+            assert(r[0] === 'done', r)
+            assertEq(r[1], 7)
+        },
+        cont: () => {
+            const r = next(doAdd('add')(2, 3))
+            assert(r[0] === 'cont', r)
+            assertEq(r[1], 5)
+            const r2 = next(r[2](r[1]))
+            assert(r2[0] === 'done', r2)
+            assertEq(r2[1], 5)
+        },
+        ownCommand: () => {
+            // The same map the two cases below dispatch against: an own
+            // property still resolves, so what they prove is refusal of
+            // inherited names, not a map that dispatches nothing.
+            const r = anyNext(doAny('add')(41))
+            assert(r[0] === 'cont', r)
+            assertEq(r[1], 42)
+        },
+        // A `command` naming an `Object.prototype` member must not dispatch to
+        // the inherited value. `map['constructor']` is `Object` and
+        // `map['toString']` is `Function.prototype.toString` — both callable,
+        // neither a handler — so a plain index read would call one of them with
+        // the node's payload instead of throwing.
+        throw: {
+            constructorCommand: () => {
+                anyNext(doAny('constructor')(1))
+            },
+            toStringCommand: () => {
+                anyNext(doAny('toString')(1))
+            },
+        },
+    },
+    step: {
+        pure: () => {
+            assertPure(step(pure(3), v => pure(v + 1)), 4)
+        },
+        chain: () => {
+            // Chains as step(step(e, f), g), raw effect in and out.
+            assertPure(step(step(pure(3), v => pure(v + 1)), v => pure(v * 2)), 8)
+        },
+        overDo: () => {
+            // Stepping a Do node preserves the command and threads the result
+            // through the rebuilt continuation.
+            const e = step(doAdd('add')(2, 3), r => pure(r * 10))
+            const r = next(e)
+            assert(r[0] === 'cont', r)
+            assertEq(r[1], 5)
+            assertPure(r[2](r[1]), 50)
+        },
+    },
+    mapStep: {
+        pure: () => {
+            assertPure(mapStep(pure(3), v => v + 1), 4)
+        },
+        constant: () => {
+            // The `() => v` shape a `constStep` would have covered.
+            assertPure(mapStep(pure('ignored'), () => 1), 1)
+        },
+        overDo: () => {
+            // A projection over a `Do` node keeps the command intact and is
+            // applied to the command's output when the continuation resumes.
+            const r = next(mapStep(doAdd('add')(2, 3), v => v * 10))
+            assert(r[0] === 'cont', r)
+            assertEq(r[1], 5)
+            assertPure(r[2](r[1]), 50)
+        },
+    },
+    historyStep: {
+        pure: () => {
+            const o = runPure(historyStep(history(pure(3)), v => pure(v * 2)))
+            assert(o.length === 1, o)
+            const [[result, param]] = o
+            assertEq(param, 3)
+            assertEq(result, 6)
+        },
+        overDo: () => {
+            // The captured value survives a command boundary: the history is
+            // rebuilt inside the continuation rather than lost when `e` is a Do.
+            const c = next(historyStep(history(doAdd('add')(2, 3)), r => pure(r * 10)))
+            assert(c[0] === 'cont', c)
+            assertEq(c[1], 5)
+            const o = runPure(c[2](c[1]))
+            assert(o.length === 1, o)
+            const [[result, param]] = o
+            assertEq(param, 5)
+            assertEq(result, 50)
+        },
+        chain: () => {
+            // `historyStep` takes a history and returns one, so link two is
+            // spelled exactly like link one. The tuple is newest first, so a
+            // destructuring reads reverse-chronologically.
+            const a = historyStep(history(pure(1)), x => pure(x + 1))
+            const b = historyStep(a, (result, param) => pure(result + param))
+            assertPure(
+                step(b, ([z, y, x]) => pure(`${x}${y}${z}`)),
+                '123')
+        },
+        fReceivesWholeHistory: () => {
+            // `f` is handed the whole history spread as arguments, not just the
+            // most recent value - which is what lets a later link reach back.
+            const a = historyStep(history(pure(1)), x => pure(x + 1))
+            const b = historyStep(a, (...p) => pure(p[1] * 100 + p[0]))
+            assertPure(step(b, ([result]) => pure(result)), 102)
+        },
+    },
+}

package/fjs/effects/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Types for the core effect system.
+ *
+ * @module
+ */
+export type Operation = readonly [string, (..._: readonly never[]) => unknown];
+/**
+ * An `Effect<O, T>` is the raw value: a {@link Pure} thunk that yields `T`, or a
+ * {@link Do} node describing a command to perform. It is plain data — compose
+ * effects with the external `step`, which is eager wherever the head is
+ * `Pure`.
+ */
+export type Effect<O extends Operation, T> = Pure<T> | Do<O, T>;
+/**
+ * A pure effect: an *already-computed* `T` behind a thunk.
+ *
+ * The thunk is a **discriminator, not a suspension**. `Effect` is a union with
+ * no tag field, so telling its two cases apart needs a runtime test, and
+ * `typeof e === 'function'` is it — wrapping the value in a function is what
+ * makes that test work. Deferral is not what the thunk is for. A `Pure` never
+ * holds work that has yet to happen; everything that *does* something is a
+ * {@link Do} node, and only a runner performs those.
+ *
+ * Two rules follow, and the rest of the module leans on both:
+ *
+ * - **The thunk must be pure and total.** Work hidden behind it is an effect
+ *   that no runner ever sees and no `OperationMap` can interpret or mock.
+ * - **It may be called more than once.** Nothing memoizes it. The same effect
+ *   can be decoded repeatedly — `Eff` re-forces the effect it wraps on each
+ *   `.step` — and under the first rule that costs nothing and changes nothing.
+ *
+ * A `lazy` constructor (`<T>(t: () => T): Effect<never, T> => t`) once existed
+ * to advertise the thunk as a suspension. It was the identity function, and it
+ * promised a deferral this representation does not keep; it has been removed.
+ * Reintroducing it would reintroduce the contradiction, not fix one.
+ */
+export type Pure<T> = () => T;
+export type Pr<O extends Operation, K extends O[0]> = O extends readonly [K, (...args: infer P) => infer R] ? readonly [P, R] : never;
+/**
+ * A `Do` node's continuation: given the command's output, produce the rest of
+ * the effect.
+ *
+ * The `out O` annotation asserts a covariance TypeScript cannot derive through
+ * the conditional `Pr` type: the command's output sits in the *contravariant*
+ * parameter position, so a bare function type would be measured contravariant
+ * in `O`, but the effect system only ever *widens* `O` (grows the op-set), never
+ * narrows it.
+ *
+ * **It is sound.** The `command` tag pins exactly which command's output the
+ * continuation receives, and every interpreter dispatches on the tag first
+ * (`match` → runner), so a `write` node's continuation is only ever
+ * called with `void`; the op-set can grow without any continuation ever being
+ * handed the wrong output. `out` enables only the widening direction
+ * (`Effect<A>` <: `Effect<A | B>`), never the unsound narrowing. Anyone changing
+ * the continuation representation must re-check this argument before keeping the
+ * annotation.
+ */
+export type Cont<out O extends Operation, T> = (_: Pr<O, O[0]>[1]) => Effect<O, T>;
+/**
+ * A `Do` node: the command to perform, its payload, and the continuation to
+ * resume with the command's output. Its runtime value is exactly this record,
+ * and every reader destructures it by name —
+ * `const { command, payload, continuation } = e`.
+ *
+ * It must be an object rather than a tuple, and that is not a style choice:
+ * only object / function / mapped-type aliases may carry a variance annotation
+ * (`TS2637` forbids `out` on a tuple), and the raw `Effect` union must be
+ * covariant in `O` end to end. `command` and `payload` are indexed/conditional
+ * types over `O` that TypeScript will not widen generically on their own —
+ * annotating only {@link Cont} is not enough — so the whole node carries
+ * `out O`. The same tag-dispatch soundness argument that justifies `Cont`'s
+ * `out O` applies here (see {@link Cont}); widening only ever grows the op-set.
+ *
+ * The fields were once numeric (`0` / `1` / `2`) over a real `[cmd, param,
+ * cont]` array, which is where the positional reads and the `Decoded` record
+ * that wrapped them came from. Nothing needed the positions: the constraint
+ * above is satisfied by any object type, so the numeric keys were paying a
+ * tuple's price without being a tuple. Named fields make the node
+ * self-describing at every read and leave no layout to memorize.
+ */
+export type Do<out O extends Operation, T> = {
+    readonly command: O[0];
+    readonly payload: Pr<O, O[0]>[0];
+    readonly continuation: Cont<O, T>;
+};
+/**
+ * An effect whose result is a **history tuple**: the values a chain has bound so
+ * far, newest first. `History<O, readonly[C, B, A]>` is three links deep, with
+ * `A` bound earliest.
+ *
+ * This is a transparent alias for `Effect`. It adds the tuple bound and
+ * nothing else, so any tuple-valued effect satisfies it whether or not
+ * `history` produced it — it names the convention at the signatures that
+ * rely on it rather than enforcing it.
+ *
+ * Heterogeneous by design: each element has its own type, so this is not a
+ * `List` and nothing that folds or maps a list applies to it.
+ */
+export type History<O extends Operation, H extends readonly unknown[]> = Effect<O, H>;
+export type Param<O extends Operation> = F<O>[0];
+export type Return<O extends Operation> = F<O>[1];
+/**
+ * An operation map whose entries take a command's payload and return some
+ * output `R`. Generalizes `ToAsyncOperationMap` (`R = Promise<…>`) and the
+ * curried `MemOperationMap` (`R = (state) => [state, …]`).
+ */
+export type OperationMap<O extends Operation, R> = {
+    readonly [K in O[0]]: (...payload: Pr<O, K>[0]) => R;
+};
+export type MatchResult<O extends Operation, T, R> = readonly ['done', T] | readonly ['cont', R, Do<O, T>['continuation']];
+export type ToAsyncOperationMap<O extends Operation> = {
+    readonly [K in O[0]]: (...payload: Pr<O, K>[0]) => Promise<Pr<O, K>[1]>;
+};
+export type F<O extends Operation> = Pr<O, O[0]>;
+export type Func<O extends Operation> = (..._: Param<O>) => Effect<O, Return<O>>;