functionalscript 0.38.0 → 0.39.0

package/fjs/ci/node/module.f.js

@@ -5,38 +5,40 @@
  * @module
  */
 import { node } from '../config/module.f.js';
-import { clean, install, test, ubuntuArm, uses } from '../common/module.f.js';
+import { install, test, ubuntuArm, uses } from '../common/module.f.js';
 export const major = (v) => v.split('.')[0];
 const installNode = (version) => uses('actions/setup-node', { 'node-version': version });
 const nodeInstall = (v) => [
     install(installNode(v)),
     test({ run: 'npm ci' }),
 ];
-export const basicNode = (version) => (extra) => clean([
+export const basicNode = (version) => (extra) => [
     ...nodeInstall(version),
     ...extra,
-]);
+];
 const fjsGlobalInstall = (version) => install({ run: `npm install -g functionalscript@${version}` });
 export const platformNodeSteps = (version) => [
     ...nodeInstall(node.default),
     fjsGlobalInstall(version),
     test({ run: 'fjs t' }),
 ];
-const node22Steps = (version) => clean([
+const node22Steps = (version) => [
     ...nodeInstall(node.node22),
     fjsGlobalInstall(version),
     test({ run: 'fjs t' }),
-]);
-const node24Steps = clean([
+];
+const node24Steps = [
     ...nodeInstall(node.node24),
     test({ run: 'node --test' }),
-]);
-const node26Steps = clean([
+];
+const node26Steps = [
     ...nodeInstall(node.default),
+    test({ run: 'npm run ci-update' }),
+    test({ run: 'git add -A && git diff --cached --exit-code' }),
     test({ run: 'npx tsc' }),
     test({ run: 'npm run cov' }),
     test({ run: 'npm pack' }),
-]);
+];
 const nodeJob = (steps) => ubuntuArm(steps);
 export const nodeVersionJobs = (version) => ({
     [`node${major(node.node22)}`]: nodeJob(node22Steps(version)),

package/fjs/ci/proof.f.js

@@ -62,6 +62,8 @@ export const proof = {
         assert(!hasExactRunInJob('wasm', 'cargo test --target wasm32-wasip1-threads --release')(gha), 'unexpected Wasmtime WASM threads release check');
         assert(hasRunInJob('node22', 'fjs t')(gha), 'expected Node 22 FunctionalScript smoke test');
         assert(hasRunInJob('node26', 'npm pack')(gha), 'expected Node 26 package check');
+        assert(hasRunInJob('node26', 'npm run ci-update')(gha), 'expected Node 26 workflow regeneration');
+        assert(hasRunInJob('node26', 'git add -A && git diff --cached --exit-code')(gha), 'expected Node 26 generated-file drift check');
         assert(!hasRun('npm publish --dry-run')(gha), 'unexpected npm publish dry-run');
         for (const id of [
             'ubuntu-intel',

package/fjs/cli/module.f.js

@@ -1,5 +1,5 @@
 import { errorExit, log } from '../effects/node/module.f.js';
-import { pure } from '../effects/module.f.js';
+import { pure, step } from '../effects/module.f.js';
 import { at, fromEntries } from '../types/object/module.f.js';
 const helpMeta = { names: ['help', 'h', '?'], description: 'Print this help message' };
 export const dispatch = (commands) => (options) => {
@@ -23,7 +23,7 @@ export const dispatch = (commands) => (options) => {
                 return dispatch(targetCmd.handler)({ ...options, args: ['help'] });
             }
         }
-        return log(helpText).step(() => pure(0));
+        return step(log(helpText), () => pure(0));
     }
     const found = at(cmd)(map);
     if (found === null) {

package/fjs/common/monoid/module.f.d.ts

@@ -1,11 +1,13 @@
 /**
  * Monoids: the `Monoid<T>` algebraic structure (identity plus associative
- * binary operation) and `repeat`, which applies the operation `n` times using
- * exponentiation by squaring.
+ * binary operation), `repeat`, which applies the operation `n` times using
+ * exponentiation by squaring, and `fold`, which applies it across every element
+ * of a list.
  *
  * @module
  */
 import type { Fold, Reduce } from '../../types/function/operator/module.f.ts';
+import { type List } from '../../types/list/module.f.ts';
 /**
  * Represents a monoid, an algebraic structure with a binary operation
  * and an identity (neutral) element.
@@ -80,3 +82,45 @@ export type Monoid<T> = {
  * ```
  */
 export declare const repeat: <T>({ identity, operation }: Monoid<T>) => Fold<bigint, T>;
+/**
+ * Reduces a `List<T>` with the monoid's associative `operation`, seeded at its
+ * `identity`. An empty list folds to `identity`.
+ *
+ * `fold` is the reduction companion of {@link repeat}: where `repeat` applies
+ * the operation a fixed number of times to a single element, `fold` applies it
+ * across every element of a list. Together they let list reductions such as
+ * `sum`, `product`, and string `concat` be expressed directly as monoid folds,
+ * so the identity paired with each operation is stated once at the call site
+ * instead of hand-seeding a raw `reduce`.
+ *
+ * Like `repeat`, `fold` applies the operation **accumulator-first**:
+ * `operation(accumulator)(element)`, seeded at `identity`, so
+ * `[a, b, c]` folds to `((identity op a) op b) op c`. Left-to-right order is
+ * therefore preserved and `fold` is correct for non-commutative monoids (e.g.
+ * string concatenation as `a => b => a + b`). `list.reduce` calls its reducer
+ * element-first, so the operation is `flip`ped before it is handed over.
+ *
+ * @template T The type of the elements in the monoid.
+ * @param monoid The monoid structure, including the identity and binary operation.
+ * @returns A function that reduces a `List<T>` to a single `T`.
+ *
+ * @example
+ *
+ * ```ts
+ * const add: Monoid<number> = {
+ *     identity: 0,
+ *     operation: a => b => a + b,
+ * };
+ *
+ * fold(add)([1, 2, 3, 4]) // 10
+ * fold(add)([])           // 0
+ *
+ * const concat: Monoid<string> = {
+ *     identity: '',
+ *     operation: a => b => a + b,
+ * };
+ *
+ * fold(concat)(['a', 'b', 'c']) // 'abc' — order preserved
+ * ```
+ */
+export declare const fold: <T>({ identity, operation }: Monoid<T>) => (list: List<T>) => T;

package/fjs/common/monoid/module.f.js

@@ -1,3 +1,5 @@
+import { reduce } from '../../types/list/module.f.js';
+import { flip } from '../../types/function/module.f.js';
 /**
  * Repeats a monoid operation `n` times on the given element `a`.
  * This function efficiently performs the operation using exponentiation by squaring.
@@ -42,3 +44,45 @@ export const repeat = ({ identity, operation }) => n => a => {
         ai = operation(ai)(ai);
     }
 };
+/**
+ * Reduces a `List<T>` with the monoid's associative `operation`, seeded at its
+ * `identity`. An empty list folds to `identity`.
+ *
+ * `fold` is the reduction companion of {@link repeat}: where `repeat` applies
+ * the operation a fixed number of times to a single element, `fold` applies it
+ * across every element of a list. Together they let list reductions such as
+ * `sum`, `product`, and string `concat` be expressed directly as monoid folds,
+ * so the identity paired with each operation is stated once at the call site
+ * instead of hand-seeding a raw `reduce`.
+ *
+ * Like `repeat`, `fold` applies the operation **accumulator-first**:
+ * `operation(accumulator)(element)`, seeded at `identity`, so
+ * `[a, b, c]` folds to `((identity op a) op b) op c`. Left-to-right order is
+ * therefore preserved and `fold` is correct for non-commutative monoids (e.g.
+ * string concatenation as `a => b => a + b`). `list.reduce` calls its reducer
+ * element-first, so the operation is `flip`ped before it is handed over.
+ *
+ * @template T The type of the elements in the monoid.
+ * @param monoid The monoid structure, including the identity and binary operation.
+ * @returns A function that reduces a `List<T>` to a single `T`.
+ *
+ * @example
+ *
+ * ```ts
+ * const add: Monoid<number> = {
+ *     identity: 0,
+ *     operation: a => b => a + b,
+ * };
+ *
+ * fold(add)([1, 2, 3, 4]) // 10
+ * fold(add)([])           // 0
+ *
+ * const concat: Monoid<string> = {
+ *     identity: '',
+ *     operation: a => b => a + b,
+ * };
+ *
+ * fold(concat)(['a', 'b', 'c']) // 'abc' — order preserved
+ * ```
+ */
+export const fold = ({ identity, operation }) => reduce(flip(operation))(identity);

package/fjs/common/monoid/proof.f.d.ts

@@ -1,4 +1,9 @@
 export declare const proof: {
     numberAdd: () => void;
     stringConcat: () => void;
+    fold: {
+        nonEmpty: () => void;
+        order: () => void;
+        empty: () => void;
+    };
 };

package/fjs/common/monoid/proof.f.js

@@ -1,4 +1,4 @@
-import { repeat } from "./module.f.js";
+import { repeat, fold } from "./module.f.js";
 import { assertEq } from '../../asserts/module.f.js';
 export const proof = {
     numberAdd: () => {
@@ -18,5 +18,31 @@ export const proof = {
         };
         const resultConcat = repeat(concat)(3n)('ha'); // 'hahaha'
         assertEq(resultConcat, 'hahaha');
+    },
+    fold: {
+        nonEmpty: () => {
+            const add = {
+                identity: 0,
+                operation: a => b => a + b,
+            };
+            assertEq(fold(add)([1, 2, 3, 4]), 10);
+        },
+        order: () => {
+            // a non-commutative monoid: `fold` must preserve left-to-right order
+            // (`((('' + 'a') + 'b') + 'c')`), not reverse it to `'cba'`.
+            const concat = {
+                identity: '',
+                operation: a => b => a + b,
+            };
+            assertEq(fold(concat)(['a', 'b', 'c']), 'abc');
+        },
+        empty: () => {
+            const concat = {
+                identity: '',
+                operation: a => b => a + b,
+            };
+            // an empty list folds to the identity
+            assertEq(fold(concat)([]), '');
+        },
     }
 };

package/fjs/dev/module.f.js

@@ -6,7 +6,7 @@
 import { all, import_, readdir } from '../effects/node/module.f.js';
 import { cmp as strCmp } from '../types/string/module.f.js';
 import { unwrap } from '../types/result/module.f.js';
-import { pure } from '../effects/module.f.js';
+import { pure, step } from '../effects/module.f.js';
 import { join, relativize, toPosix } from '../path/module.f.js';
 import { assert } from '../asserts/module.f.js';
 /**
@@ -25,32 +25,33 @@ export const shouldLoad = (s) => s.endsWith('.f.ts') || s.endsWith('.f.js') ||
     s.endsWith('proof.mts') || s.endsWith('proof.mjs');
 const isSourceFile = (path) => path.endsWith('.js') || path.endsWith('.ts') || path.endsWith('.mts') || path.endsWith('.mjs');
 const allFiles = (s, predicate) => {
-    const load = (p) => readdir(p, {})
-        .step(d => {
-        let result = [];
-        for (const i of unwrap(d)) {
-            const { name } = i;
-            if (name.startsWith('.')) {
-                continue;
-            }
-            const file = join(p, name);
-            if (!i.isFile) {
-                if (name === 'node_modules') {
+    const load = (p) => {
+        const x0 = step(readdir(p, {}), d => {
+            let result = [];
+            for (const i of unwrap(d)) {
+                const { name } = i;
+                if (name.startsWith('.')) {
                     continue;
                 }
-                result = [...result, load(file)];
-                continue;
-            }
-            if (predicate(file)) {
-                result = [...result, pure([file])];
+                const file = join(p, name);
+                if (!i.isFile) {
+                    if (name === 'node_modules') {
+                        continue;
+                    }
+                    result = [...result, load(file)];
+                    continue;
+                }
+                if (predicate(file)) {
+                    result = [...result, pure([file])];
+                }
             }
-        }
-        return all(...result);
-    })
-        .step(v => pure(v.flat()));
+            return all(...result);
+        });
+        return step(x0, v => pure(v.flat()));
+    };
     return load(s);
 };
-const loadFile = (f) => import_(f).step(r => pure([[f, unwrap(r)]]));
+const loadFile = (f) => step(import_(f), r => pure([[f, unwrap(r)]]));
 const { fromEntries } = Object;
 /**
  * Discovers all source files under `INIT_CWD` (or `.` if unset) that match
@@ -74,9 +75,8 @@ export const loadModuleMap = (env) => {
     //       we should consider optimize them by ALIQ technique or something similar.
     //       For example, we should be able to write it like `allFiles(s).flatMap(loadFile)`,
     //       then an effect runner can batch all file loading operations together.
-    return allFiles(s, shouldLoad)
-        .step(files => all(...files.map(loadFile)))
-        .step(entries => pure(fromEntries(entries
+    const x0 = step(allFiles(s, shouldLoad), files => all(...files.map(loadFile)));
+    return step(x0, entries => pure(fromEntries(entries
         .flat()
         .map(([k, v]) => [relativize(prefix, k), v])
         .toSorted(([a], [b]) => strCmp(a)(b)))));

package/fjs/djs/module.f.js

@@ -1,25 +1,22 @@
 import { transpile } from './transpiler/module.f.js';
 import { stringify, stringifyAsTree } from './serializer/module.f.js';
 import { sort } from '../types/object/module.f.js';
-import { pure } from '../effects/module.f.js';
+import { pure, step } from '../effects/module.f.js';
 import { writeUtf8File, error, } from '../effects/node/module.f.js';
 export const compile = args => {
     if (args.length < 2) {
-        return error('Error: Requires 2 or more arguments')
-            .step(() => pure(1));
+        return step(error('Error: Requires 2 or more arguments'), () => pure(1));
     }
     const inputFileName = args[0];
     const outputFileName = args[1];
-    return transpile(inputFileName).step((result) => {
+    return step(transpile(inputFileName), (result) => {
         if (result[0] === 'error') {
             const metadata = result[1].metadata;
-            return error(`${metadata?.path}:${metadata?.line}:${metadata?.column} - error: ${result[1].message}`)
-                .step(() => pure(0));
+            return step(error(`${metadata?.path}:${metadata?.line}:${metadata?.column} - error: ${result[1].message}`), () => pure(0));
         }
         const content = outputFileName.endsWith('.json')
             ? stringifyAsTree(sort)(result[1])
             : stringify(sort)(result[1]);
-        return writeUtf8File(outputFileName, content)
-            .step(() => pure(0));
+        return step(writeUtf8File(outputFileName, content), () => pure(0));
     });
 };

package/fjs/djs/parser/module.f.d.ts

@@ -17,4 +17,7 @@ export declare const proof: {
     pushKey: {
         nonObjectTop: () => void;
     };
+    endArray: {
+        nonArrayTop: () => void;
+    };
 };

package/fjs/djs/parser/module.f.js

@@ -380,4 +380,21 @@ export const proof = {
             assertEq(result.state, 'error');
         },
     },
+    endArray: {
+        // `endArray` is only ever invoked while `state.top` is an array (the
+        // `'['`/`'[v'`/`'[,'` value-states guarantee it), so its non-array
+        // guard is a defensive branch unreachable through `parseFromTokens`.
+        // Call it directly to cover that branch.
+        nonArrayTop: () => {
+            const state = {
+                state: 'exportValue',
+                module: { refs: null, modules: null, consts: null },
+                valueState: '[,',
+                top: null,
+                stack: null,
+            };
+            const result = endArray(state);
+            assertEq(result.state, 'result');
+        },
+    },
 };

package/fjs/djs/transpiler/module.f.js

@@ -12,7 +12,7 @@ import { stringToList } from '../../text/utf16/module.f.js';
 import { concat as pathConcat } from '../../path/module.f.js';
 import { parseFromTokens } from '../parser/module.f.js';
 import { run } from '../ast/module.f.js';
-import { foldStep, pure } from '../../effects/module.f.js';
+import { foldStep, pure, step } from '../../effects/module.f.js';
 import { readUtf8File } from '../../effects/node/module.f.js';
 const mapDjs = context => path => {
     const res = at(path)(context.complete);
@@ -21,7 +21,7 @@ const mapDjs = context => path => {
     }
     return res.djs;
 };
-const parseModule = path => readUtf8File(path).step(result => {
+const parseModule = path => step(readUtf8File(path), result => {
     if (result[0] === 'error') {
         return pure(error({ message: 'file not found', metadata: null }));
     }
@@ -34,8 +34,8 @@ const transpileWithImports = path => parseModuleResult => context => {
         const pathsCombine = listMap(pathConcat(dir))(parseModuleResult[1][0]);
         const pathsArray = toArray(pathsCombine);
         const contextWithStack = { ...context, stack: { first: path, tail: context.stack } };
-        return foldStep(foldNextModuleOp)(contextWithStack)(pathsArray)
-            .step(contextWithImports => {
+        const x0 = foldStep(pure(pathsArray), contextWithStack, foldNextModuleOp);
+        return step(x0, contextWithImports => {
             if (contextWithImports.error !== null) {
                 return pure(contextWithImports);
             }
@@ -60,7 +60,7 @@ const foldNextModuleOp = path => context => {
     if (at(path)(context.complete) !== null) {
         return pure(context);
     }
-    return parseModule(path).step(parseModuleResult => transpileWithImports(path)(parseModuleResult)(context));
+    return step(parseModule(path), parseModuleResult => transpileWithImports(path)(parseModuleResult)(context));
 };
 /**
  * Transpiles a DJS module graph rooted at `path` into a single `Unknown` value.
@@ -69,7 +69,7 @@ const foldNextModuleOp = path => context => {
  * evaluates the AST. Returns `['ok', value]` on success, or `['error', ParseError]`
  * on a parse failure or circular dependency.
  */
-export const transpile = path => foldNextModuleOp(path)({ stack: null, complete: null, error: null }).step((context) => {
+export const transpile = path => step(foldNextModuleOp(path)({ stack: null, complete: null, error: null }), (context) => {
     if (context.error !== null) {
         return pure(error(context.error));
     }

package/fjs/effects/eff/module.f.d.ts

@@ -0,0 +1,72 @@
+import { type Effect, type Operation } from '../module.f.ts';
+/**
+ * A fluent, method-chaining monad over a raw {@link Effect} that also
+ * accumulates the history of every value the chain has produced. `.step(f)`
+ * is bind — `f` receives the current value followed by every prior value,
+ * most recent first (`f(t, ...p)`), and returns a raw `Effect`; `.step`
+ * re-wraps the result together with that history so `.step(f).step(g)`
+ * chains and stays in the `Eff` world throughout. `.map(f)` is the functor
+ * map — the same thing for an `f` that returns a plain value rather than an
+ * effect, so it is exactly `.step((...tp) => pure(f(...tp)))`. `P` is the
+ * tuple of prior values available to the *next* `.step` call; it grows by one
+ * element (the current `T`) on every step, starting empty at {@link eff}.
+ * `.value` is the exit back to a raw `Effect`, discarding the history. An
+ * `Eff` is not assignable to `Effect`; unwrap through `.value`.
+ *
+ * **`.map` grows the history just as `.step` does, and does not widen `O`.**
+ * Both follow from it being that `.step` call and nothing else: a chain
+ * rewritten from `.step(v => pure(f(v)))` to `.map(f)` must hand later
+ * callbacks the same prior values it did before, and a projection performs no
+ * command, so it contributes no operation for a runner to interpret.
+ *
+ * **The history is positional, so every parameter a callback declares is
+ * meaningful.** `f` is applied as `f(...tp)`, so a callback written
+ * `(v, n = 1) => …` or `(v, ...rest) => …` receives prior chain values in `n` /
+ * `rest` rather than the default or an empty rest — and where the types line up,
+ * TypeScript will not object. Declare exactly as many parameters as the callback
+ * intends to read; a defaulted or rest parameter after the current value is a
+ * bug, not a convenience. This is what makes `.map(g)` a *different* call from
+ * `.step(v => pure(g(v)))` whenever `g` is not genuinely unary — the lambda
+ * pins the arity at one, while passing `g` point-free exposes it to the prior
+ * values, the way `['1', '2', '3'].map(parseInt)` does.
+ *
+ * **`.value` is always an already-built `Effect`.** Reading it composes
+ * nothing: the projection that drops the history tuple to its current value is
+ * performed by the `.step` that produced the link, not deferred to the read.
+ * An `Eff` is a record to look into, not an object with a method that quietly
+ * does work when called.
+ *
+ * That costs one projection per link, paid whether or not the link is ever
+ * unwrapped — an n-link chain builds n of them where a deferred `.result()`
+ * method would build one. It is a constant factor on construction, with no
+ * extra forcing of the wrapped effect and no change in growth rate, bought in
+ * exchange for a uniform rule at the boundary every caller touches.
+ *
+ * At the entry it costs nothing at all: `eff(e).value` **is** `e`, because
+ * {@link eff} stores what it was handed rather than rebuilding it from the
+ * history, so wrapping and unwrapping round-trip to identity. `h` is still a
+ * thunk, so `eff(e)` composes nothing and never forces `e`: an `Eff` that is
+ * built and only read does no work at all.
+ *
+ * **`P` has no default, on purpose.** A default of `readonly[]` would make
+ * `Eff<O, T>` a spelling that silently erases history: an
+ * `Eff<O, T, readonly[A]>` is assignable to it, because `f` sits in a
+ * contravariant position and TypeScript accepts a callback declaring fewer
+ * parameters than the type it is checked against. The next `.step` callback
+ * would then be typed as receiving no prior values while the runtime still
+ * passes them, and any callback destructuring a rest parameter would be handed
+ * entries its type says cannot exist. Requiring the third argument means that
+ * erasure cannot be written at all, rather than merely being discouraged;
+ * {@link eff} spells `readonly[]` itself.
+ */
+export type Eff<O extends Operation, T, P extends readonly unknown[]> = {
+    readonly value: Effect<O, T>;
+    readonly step: <Q extends Operation, R>(f: (...tp: readonly [T, ...P]) => Effect<Q, R>) => Eff<O | Q, R, readonly [T, ...P]>;
+    readonly map: <R>(f: (...tp: readonly [T, ...P]) => R) => Eff<O, R, readonly [T, ...P]>;
+};
+/**
+ * Wraps a raw {@link Effect}; the bridge into the `Eff` world, with an empty
+ * history. The empty tuple is spelled out because {@link Eff} deliberately has
+ * no default for `P` — see its docs.
+ */
+export declare const eff: <O extends Operation, T>(value: Effect<O, T>) => Eff<O, T, readonly []>;

package/fjs/effects/eff/module.f.js

@@ -0,0 +1,46 @@
+import { history, historyStep, mapStep, pure } from '../module.f.js';
+/**
+ * Builds an `Eff` from two views of the same chain: `value`, the effect for the
+ * current value alone, and `h`, a thunk for the `[current, ...history]` tuple.
+ *
+ * **The two must denote the same computation** — `value` has to be what `h()`
+ * produces with the history dropped. Nothing enforces it. The
+ * redundancy is deliberate: `value` used to be derived from `h` on demand,
+ * which made disagreement impossible but also forced the entry case to rebuild
+ * an effect it was already holding. Passing it in is what lets {@link eff} hand
+ * the original back.
+ *
+ * The asymmetry between the two — one built, one deferred — is the point.
+ * `value` is either already in hand ({@link eff} was given it) or already built
+ * (`.step` has just composed the chain it projects from), so storing it costs
+ * no more than the projection itself. `h` is different: nothing needs the
+ * history tuple until a later `.step` asks for it, and composing effects is
+ * eager, so holding a thunk is the only way to not compose it yet. That keeps
+ * `eff(e)` free of work entirely.
+ *
+ * `.step` calls `h()` once and closes over the effect, so everything built
+ * from that link shares it. `eff`'s thunk is not memoized, so calling `.step`
+ * twice on the same `eff(e)` rebuilds and re-forces `e` — harmless under
+ * `Pure`'s contract, which requires the thunk to be pure and to tolerate
+ * repeat calls.
+ */
+const create = (value, h) => {
+    // `self` is named so `.map` can be *defined* as the `.step` call it is
+    // documented to equal, rather than as a second copy of `.step`'s body that
+    // has to be re-checked against it.
+    const self = {
+        value,
+        step: f => {
+            const x1 = historyStep(h(), f);
+            return create(mapStep(x1, ([t]) => t), () => x1);
+        },
+        map: f => self.step((...tp) => pure(f(...tp)))
+    };
+    return self;
+};
+/**
+ * Wraps a raw {@link Effect}; the bridge into the `Eff` world, with an empty
+ * history. The empty tuple is spelled out because {@link Eff} deliberately has
+ * no default for `P` — see its docs.
+ */
+export const eff = (value) => create(value, () => history(value));

package/fjs/effects/eff/proof.f.d.ts

@@ -0,0 +1,11 @@
+export declare const proof: {
+    value: () => void;
+    pure: () => void;
+    chain: () => void;
+    overDo: () => void;
+    map: {
+        chain: () => void;
+        growsHistory: () => void;
+        overDo: () => void;
+    };
+};

package/fjs/effects/eff/proof.f.js

@@ -0,0 +1,58 @@
+import { do_, match, pure } from '../module.f.js';
+import { assert, assertEq } from '../../asserts/module.f.js';
+import { assertPure } from '../proof.f.js';
+import { eff } from './module.f.js';
+const next = match({ add: (a, b) => a + b });
+export const proof = {
+    value: () => {
+        assertPure(eff(pure(5)).value, 5);
+    },
+    pure: () => {
+        assertPure(pure(5), 5);
+    },
+    chain: () => {
+        const x = eff(pure(5))
+            .step(v => pure(v + 1))
+            .step(v => pure(v * 2))
+            .value;
+        assertPure(x, 12);
+    },
+    overDo: () => {
+        const e = eff(do_('add')(2, 3))
+            .step(r => pure(r + 1))
+            .value;
+        const r = next(e);
+        assert(r[0] === 'cont', r);
+        assertEq(r[1], 5);
+        assertPure(r[2](r[1]), 6);
+    },
+    map: {
+        chain: () => {
+            const x = eff(pure(5))
+                .map(v => v + 1)
+                .map(v => v * 2)
+                .value;
+            assertPure(x, 12);
+        },
+        // `.map` grows the history exactly as `.step` does, so a callback after
+        // it still reaches the pre-`map` value. This is the contract that makes
+        // rewriting `.step(v => pure(f(v)))` into `.map(f)` a pure readability
+        // change rather than one that alters what later callbacks receive.
+        growsHistory: () => {
+            const x = eff(pure(5))
+                .map(v => v + 1)
+                .step((v, prev) => pure(`${prev}${v}`))
+                .value;
+            assertPure(x, '56');
+        },
+        overDo: () => {
+            const e = eff(do_('add')(2, 3))
+                .map(r => r + 1)
+                .value;
+            const r = next(e);
+            assert(r[0] === 'cont', r);
+            assertEq(r[1], 5);
+            assertPure(r[2](r[1]), 6);
+        },
+    },
+};

package/fjs/effects/list/module.f.d.ts

@@ -7,10 +7,15 @@ export type NonEmpty<O extends Operation, T> = {
  * The payload of a `List` effect: the next cons cell, or `undefined` at
  * end-of-stream.
  *
- * Since `Pure<T>` is now itself a lazy thunk (`() => T`), the effect alone is the
- * suspension point and the cell needs no extra wrapping thunk. `Effect<O, Next<O, T>>`
- * is used directly in places where `List<O, T>` cannot be written as a return type
- * (see {@link empty}).
+ * A `List` suspends only where a `Do` node does. `Pure` is a thunk, but that
+ * thunk is a discriminator rather than a suspension, and {@link nonEmpty} takes
+ * `tail` as an ordinary argument — already evaluated by the time the cell is
+ * built. A chain of pure cells is therefore constructed in full, up front;
+ * streaming comes from cells produced inside a command's continuation, where
+ * the tail is not reached until a runner performs the command.
+ *
+ * `Effect<O, Next<O, T>>` is used directly in places where `List<O, T>` cannot
+ * be written as a return type (see {@link empty}).
  */
 export type Next<O extends Operation, T> = NonEmpty<O, T> | undefined;
 export type List<O extends Operation, T> = Effect<O, Next<O, T>>;
@@ -26,6 +31,7 @@ export type List<O extends Operation, T> = Effect<O, Next<O, T>>;
  */
 export declare const empty: <O extends Operation, T>() => Effect<O, Next<O, T>>;
 /**
- * Prepends `head` to a `ListEffect` `tail`, as a pure cons cell. See {@link empty}.
+ * Prepends `first` to a {@link List} `tail`, as a pure cons cell. `tail` is an
+ * ordinary argument, so it is built before the cell is — see {@link Next}.
  */
 export declare const nonEmpty: <O extends Operation, T>(first: T, tail: List<O, T>) => Effect<O, Next<O, T>>;

package/fjs/effects/list/module.f.js

@@ -11,6 +11,7 @@ import { pure } from "../module.f.js";
  */
 export const empty = () => pure(undefined);
 /**
- * Prepends `head` to a `ListEffect` `tail`, as a pure cons cell. See {@link empty}.
+ * Prepends `first` to a {@link List} `tail`, as a pure cons cell. `tail` is an
+ * ordinary argument, so it is built before the cell is — see {@link Next}.
  */
 export const nonEmpty = (first, tail) => pure({ first, tail });