functionalscript 0.38.0 → 0.40.0

package/fjs/effects/module.f.js

@@ -1,51 +1,248 @@
 /**
  * Core effect type constructors and combinators.
  *
- * Effect helpers are **step adapters**: functions that return a continuation
- * `(t: T) => Effect<Q, R>` meant to be passed into `.step`, never wrappers
- * that take the effect itself as an argument. `Effect` has no pipeline
- * operator to lean on and must not be extended with new methods, so
- * `.step(adapterA).step(adapterB)` is how helpers compose — flat,
- * left-to-right, in evaluation order. See {@link okStep} for an example.
+ * An `Effect<O, T>` **is** the raw value — a `Pure` thunk (`() => T`) or a `Do`
+ * node (`{ command, payload, continuation }`). It is plain data with no methods.
+ * Composition is provided externally by {@link step}. The optional
+ * method-chaining wrapper lives in `fjs/effects/eff/module.f.ts`.
+ *
+ * **Three functions discriminate `Pure` from `Do`** — {@link step},
+ * {@link match}, and {@link runPure} — plus the node proof in
+ * `fjs/effects/proof.f.ts` that pins the representation on purpose. Everything
+ * else, interpreters included, goes through `match` or `runPure`. The count is
+ * the point: a `typeof e === 'function'` check appearing in a fifth place is a
+ * review flag, because the representation is only cheap to change while its
+ * readers stay enumerable.
+ *
+ * A `decode` function (`(e: Effect<O, T>) => Decoded<O, T>`) once funnelled all
+ * of that through a single `{ done, result }` / `{ done, command, payload,
+ * continuation }` record, so that exactly one function held the shape test. It
+ * has been removed. `Effect` is a function type unioned with an object type, so
+ * `typeof e === 'function'` is already a complete discriminant: `decode` bought
+ * no narrowing, it re-encoded that narrowing as a `done` flag to be re-narrowed
+ * one indirection later, and its `Decoded` record was declared in terms of the
+ * node it claimed to hide. The price was a second vocabulary every consumer had
+ * to learn for a shape it could already read. Reintroducing it would buy back
+ * the same nothing — and with {@link Do} now carrying named fields there is not
+ * even a positional layout left for it to insulate anyone from.
+ *
+ * Effect helpers come in two shapes. **Step adapters** return a continuation
+ * `(t: T) => Effect<Q, R>` meant to be passed into a step — see {@link okStep}.
+ * **Step variants** take the effect itself first, like {@link step} — see
+ * {@link historyStep}. {@link mapStep} is the variant for the end of a chain:
+ * a pure projection over an effect's result, which is a `step` that continues
+ * with no further effect.
+ *
+ * **Do not nest steps.** Bind each intermediate effect to its own name, so a
+ * sequence reads top-to-bottom in evaluation order:
+ *
+ * ```ts
+ * // avoid — reads inside-out, and gains a level of indentation per link
+ * step(a, x => step(f(x), y => step(g(y), z => h(z))))
+ *
+ * // prefer — flat, one name per link
+ * const x0 = step(a, f)
+ * const x1 = step(x0, g)
+ * return step(x1, h)
+ * ```
+ *
+ * **A step call that does not fit one line breaks after `(`, one argument per
+ * line.** This holds for every step variant — {@link step}, {@link mapStep},
+ * {@link historyStep}, {@link foldStep}, {@link forEachStep} — and it is the
+ * same rule as taking the effect first, written out at the call site. A step
+ * variant is this module's
+ * `do` notation: the arguments are a statement list in execution order, so each
+ * one gets a line and the sequence reads down the page. Packing the leading
+ * effect onto the `(` line and wrapping the rest beneath it hides which of them
+ * runs first. The closing `)` may sit on its own line or trail the last
+ * argument:
+ *
+ * ```ts
+ * return step(
+ *     collectRead(cas.read(hash)),
+ *     ([tag, value]) => pure(tag === 'error' ? null : decodeRevisionVec(value)))
+ * ```
+ *
+ * When a later link needs a value from an earlier one, that is not a reason to
+ * nest: a nested continuation only reaches back because it closes over the
+ * enclosing scope. {@link historyStep} carries the value forward instead, so
+ * the chain stays flat:
+ *
+ * ```ts
+ * // avoid — nested only so `h` can still see `x`
+ * step(a, x => step(f(x), y => h(x, y)))
+ *
+ * // prefer — the history tuple carries `x` forward alongside `y`
+ * const x0 = historyStep(history(a), f)
+ * return step(x0, ([y, x]) => h(x, y))
+ * ```
+ *
+ * Nesting is often forced by nothing more than a local declared inside a
+ * continuation that does not depend on it. Hoist such locals above the chain
+ * and the nesting usually dissolves on its own.
+ *
+ * That advice is for code *using* this module, and the combinators defined
+ * here are what make it followable. The nesting has to exist somewhere: a name
+ * cannot be bound to an effect that has not been produced yet, so `f(param)`
+ * cannot become a `const` until `e` resolves. {@link step} recurses into
+ * itself inside the continuation it rebuilds, {@link foldStep} composes one
+ * step per item, and {@link historyStep} runs `f` inside `e`'s continuation.
+ * Each writes that nesting down **once**, in one line, so that no caller ever
+ * writes it again — that is what a combinator here is *for*. Without
+ * {@link historyStep} the flat form would be unavailable the moment a later
+ * link needed an earlier link's value.
  *
  * @module
  */
 import { fold } from '../types/list/module.f.js';
-export const pure = (v) => ({
-    value: () => v,
-    step: f => f(v)
-});
+export const pure = (v) => () => v;
 /**
- * A lazy pure effect. Like {@link pure}, but takes a thunk and evaluates it on
- * demand instead of holding an already-computed value. Use this to produce the
- * next item of a list without instantiating the rest — the thunk runs only when
- * the effect is decoded (or stepped into).
+ * Composes effects: run `e`, then continue with `f` applied to its result.
+ * The data-first primitive — raw `Effect` in, raw `Effect` out. Chains as
+ * `step(step(e, f), g)`.
+ *
+ * **`step` is not lazy.** It reads `e`'s shape immediately, so a `Pure` head is
+ * forced and `f` is called right there: `step(pure(v), f)` *is* `f(v)`,
+ * evaluated where the composition is written rather than where the effect is
+ * run. Only the `Do` case defers — the continuation rebuilt around `f` runs
+ * when a runner reaches that node.
+ *
+ * That is sound rather than an oversight, and it is sound only because of
+ * {@link Pure}'s contract: a `Pure` holds a value that has already been
+ * computed, so forcing it early observes nothing, repeats nothing, and can
+ * throw nothing. `step` never performs a `Do` node, which is where anything
+ * real lives. Break the contract — hide work behind the thunk — and merely
+ * composing a chain starts running the program.
+ *
+ * A composition cannot be suspended, and no combinator can fix that:
+ * `defer: (() => Effect<O, T>) => Effect<O, T>` cannot be written here, because
+ * the `Pure` / `Do` tag must be known before anything runs and the union has no
+ * third case meaning "not yet decided". That is inherent to the representation,
+ * not a gap in this module's API. A caller that needs to name a composition
+ * without performing it yet has to keep the ingredients and defer the `step`
+ * itself — `Eff` does exactly this, holding its history tuple as a thunk (`h`)
+ * precisely because composing it eagerly is the one thing it cannot take back.
  */
-export const lazy = (t) => ({
-    value: t,
-    step: f => f(t())
-});
-export const doFull = (cmd, param, cont) => ({
-    value: [cmd, param, cont],
-    step: (f) => doFull(cmd, param, x => cont(x).step(f)),
-});
-export const do_ = (cmd) => (...param) => doFull(cmd, param, pure);
+export const step = (e, f) => typeof e === 'function'
+    ? f(e())
+    : { ...e, continuation: x => step(e.continuation(x), f) };
 /**
- * Sequentially threads a state value through an effect for each item in `items`.
+ * Applies a pure function to an effect's result: the functor `map` of the
+ * effect monad, and a {@link step} whose continuation performs nothing further.
+ *
+ * Prefer it over the `step(e, t => pure(f(t)))` it abbreviates. The two are the
+ * same value, but they read as different things: a `step` announces another
+ * link in a sequence of effects, and a trailing pure projection is not one —
+ * it is where the sequence ends. Saying so in the combinator's name keeps the
+ * "one name per link" shape of a chain honest about how many effects it runs.
  *
- * Given `f: item => state => Effect<O, state>`, `init: S`, and `items: [x₀, x₁, …]`,
- * builds `f(x₀)(init).step(f(x₁)).step(f(x₂)).…` and yields a single
- * `Effect<O, S>` that produces the final state.
+ * **The operation set does not widen.** The result is `Effect<O, R>`, not
+ * `Effect<O | Q, R>`, because a pure projection issues no commands — nothing a
+ * runner has to know how to interpret is added by `f`. That is what separates
+ * this from `step`, beyond the shorter spelling.
+ *
+ * A constant variant (`constStep(e, v)`) is deliberately absent: `mapStep(e,
+ * () => v)` already reads clearly, and it keeps `v`'s evaluation inside the
+ * continuation where `step` puts it, rather than moving it to where the
+ * composition is written.
+ */
+export const mapStep = (e, f) => step(e, t => pure(f(t)));
+/**
+ * Like {@link step}, but keeps the values instead of discarding them: runs `e`
+ * to get the history `p`, continues with `f(...p)` to get `r`, and yields
+ * `[r, ...p]` — the same history with `r` prepended.
+ *
+ * This is what a chain of named intermediate effects cannot otherwise express.
+ * Each `step`'s continuation sees only the result of the effect it consumes, so
+ * a later link has no way to reach an earlier one. `historyStep` carries every
+ * earlier value forward, and the next destructuring names the parts:
+ *
+ * ```ts
+ * const b = historyStep(history(a), decodeRevisionBlob(cas))
+ * const c = step(b, ([revision, hash]) => ...)
+ * ```
+ *
+ * Chaining mimics an async function, one `await` per link — `const hash = ...`
+ * then `const revision = ...`, with both still reachable at the end. It takes a
+ * history and returns one, so it composes with itself to any depth; only the
+ * entry point needs {@link history}:
+ *
+ * ```ts
+ * const h0 = history(readHash(cas))
+ * const h1 = historyStep(h0, hash => decodeRevisionBlob(cas)(hash))
+ * const h2 = historyStep(h1, (revision, hash) => ...)
+ * ```
+ *
+ * **Newest first.** A position is distance back from the current link, not
+ * evaluation order, so a destructuring reads reverse-chronologically:
+ * `([z, y, x]) => ...` binds `x` earliest. Reaching further back costs an index
+ * rather than a traversal, but a long chain makes the positions hard to count.
+ * When that starts to hurt, collapse it into a record of named fields
+ * (`pure({ hash, revision } as const)`) and start a fresh history from there.
+ */
+export const historyStep = (e, 
+// `Readonly<P>` is load-bearing: inferring `P` from a bare rest parameter
+// yields a *mutable*, labelled tuple (`[next: string]`), which then rejects
+// the `readonly` tuples every history is built from.
+f) => step(e, param => step(f(...param), result => pure([result, ...param])));
+/**
+ * Starts a history, lifting a plain result into a one-element tuple so that
+ * {@link historyStep} can extend it.
+ *
+ * Creating a history is the *only* thing this does — every later link goes
+ * through `historyStep`, which is what lets one combinator cover chains of any
+ * length. Fusing the two (a step that both starts and extends) is what makes
+ * chains stop composing: such a step nests its predecessor's tuple instead of
+ * flattening it, so link two would have to be spelled differently from link
+ * three.
+ */
+export const history = (e) => step(e, v => pure([v]));
+export const do_ = (command) => (...payload) => ({ command, payload, continuation: pure });
+/**
+ * Sequentially threads a state value through an effect for each item produced by
+ * `items`.
+ *
+ * Given `f: item => state => Effect<Q, state>`, `init: S`, and an `items` that
+ * yields `[x₀, x₁, …]`, builds `step(step(f(x₀)(init), f(x₁)), f(x₂))…` and
+ * yields a single effect producing the final state.
  *
  * Sequential — each step depends on the previous state. Compare to `all`,
  * which fans out independent effects.
+ *
+ * **A step variant** (see the two shapes described in this module's header): the
+ * effect comes first, as in {@link step} and {@link historyStep}. `items` is an
+ * `Effect<O, List<T>>` rather than a bare `List<T>` because the list a caller
+ * folds over is normally *produced* by an effect — `cas.list()`, a `readdir`.
+ * Taking the plain list would force every such caller to open a continuation
+ * just to name the list (`step(cas.list(), foldStep(…))`), which is the nesting
+ * this module exists to keep out of call sites. A caller that already holds the
+ * list lifts it with `pure`, which costs a wrapper but no indentation.
+ *
+ * `O` and `Q` are separate on purpose: the operations needed to produce the list
+ * are rarely the ones the body performs, and the result unions them.
+ *
+ * **The argument order is deliberately not `fold`'s** from `fjs/types/list`, and
+ * the difference is what the two combinators are *for*. `fold` is a data
+ * pipeline: it is curried `f`-first because the list is the thing being threaded
+ * through, and nothing about it happens in time. A step variant is a sequencing
+ * construct — it is this module's `do` notation, and reading one top-to-bottom
+ * is reading the order the program executes in. The effect therefore has to come
+ * first, because it is what happens first. Currying `f` ahead of `items` would
+ * put the *body* of the loop above the thing it loops over, which is exactly the
+ * inversion `do` exists to remove.
+ *
+ * That is also why the whole family — `step`, `historyStep`, `foldStep`,
+ * `forEachStep` — takes its effect first and breaks one argument per line when
+ * it wraps (see this module's header): every such call is a statement list, and
+ * each line is one statement in execution order.
  */
-export const foldStep = (f) => (init) => (items) => fold(item => acc => acc.step(f(item)))(pure(init))(items);
+export const foldStep = (items, init, f) => step(items, fold(item => acc => step(acc, f(item)))(pure(init)));
 /**
- * Sequentially runs `f(item)` for each item in `items`, discarding intermediate
- * results. The `void` accumulator sibling of `foldStep`.
+ * Sequentially runs `f(item)` for each item produced by `items`, discarding
+ * intermediate results. The `void` accumulator sibling of {@link foldStep}, and
+ * a step variant on the same grounds.
  */
-export const forEachStep = (f) => (items) => foldStep((item) => () => f(item))(undefined)(items);
+export const forEachStep = (items, f) => foldStep(items, undefined, (item) => () => f(item));
 /**
  * A step adapter for the `error` short-circuit: `error` → pass it through
  * unchanged as `pure`, `ok` → continue with `f`. Collapses the hand-written
@@ -54,17 +251,27 @@ export const forEachStep = (f) => (items) => foldStep((item) => () => f(item))(u
  */
 export const okStep = (f) => (r) => r[0] === 'error' ? pure(r) : f(r[1]);
 /**
- * Decodes an effect's next step: a pure result, or a command to perform.
+ * Runs an effect that reaches its value without performing a command: `[t]` for
+ * a {@link Pure}, empty for a {@link Do}. Forces the thunk in the `Pure` case,
+ * which {@link Pure}'s contract makes free of consequence.
+ *
+ * The eliminator for callers that expect no operations at all — the other side
+ * of {@link match}, which is for callers that intend to perform them.
+ *
+ * **The result is tagged on purpose.** Returning `T | null` would collapse two
+ * distinct outcomes whenever `T` itself admits `null`: `runPure(pure(null))` and
+ * `runPure(someDo)` would both be `null`, so a caller asserting `null` would
+ * accept an effect that unexpectedly stopped at a command — exactly the case
+ * this exists to rule out. `Option<T>` keeps them apart: `[null]` is a pure
+ * `null`, `[]` is a `Do`.
  *
- * This is the only function that knows how `Value` is laid out (a thunk
- * `() => T` for `Pure`, a `[command, payload, continuation]` tuple for `Do`).
- * Interpreters and proofs must go through `decode` (or `match`) instead of
- * inspecting the value, so the representation can change without touching
- * them.
+ * `O` stays generic rather than narrowing to `Effect<never, T>`. `Effect` is
+ * covariant in `O`, so `Effect<never, T>` is assignable to `Effect<O, T>` and
+ * not the reverse — a continuation's result is always the wider type and would
+ * be rejected. `Do<never, T>` is uninhabited besides, which would make the empty
+ * case unreachable without a cast.
  */
-export const decode = ({ value }) => typeof value === 'function'
-    ? { done: true, result: value() }
-    : { done: false, command: value[0], payload: value[1], continuation: value[2] };
+export const runPure = (e) => typeof e === 'function' ? [e()] : [];
 /**
  * Decodes an effect's next step and dispatches its command to `map`,
  * returning either the final result or the operation's output `R` paired
@@ -72,9 +279,10 @@ export const decode = ({ value }) => typeof value === 'function'
  * runners, state threading for sync ones — is left to the caller, so every
  * interpreter loop is this skeleton plus a single eliminator line.
  */
-export const match = (map) => (effect) => {
-    const d = decode(effect);
-    return d.done
-        ? ['done', d.result]
-        : ['cont', map[d.command](...d.payload), d.continuation];
+export const match = (map) => (e) => {
+    if (typeof e === 'function') {
+        return ['done', e()];
+    }
+    const { command, payload, continuation } = e;
+    return ['cont', map[command](...payload), continuation];
 };

package/fjs/effects/node/memory/proof.js

@@ -7,10 +7,11 @@ import { asyncRun } from '../../module.js';
 import { asNominal, create, read, write, } from '../../memory/module.f.js';
 import { memoryOperationMap, run } from './module.js';
 import { assert, assertEq } from '../../../asserts/module.f.js';
+import { step } from '../../module.f.js';
 export const proof = {
     nodeInterpreter: async () => {
-        const result = await run(create(1).step(key => write(key, 2).step(() => read(key))));
-        assertEq(result, 2);
+        const x = step(create(1), key => step(write(key, 2), () => read(key)));
+        assertEq(await run(x), 2);
     },
     reusedOperationMapPersists: async () => {
         const runner = asyncRun(memoryOperationMap());

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

@@ -4,9 +4,9 @@ import { type NodeProgram } from './module.f.ts';
  * resolving to its exit code **without** terminating the process.
  *
  * Use this when the caller must stay alive afterwards — e.g. when proofs are
- * registered under an external test runner (Node `--test`, Bun, Playwright)
- * that owns the process lifecycle. For a standalone CLI entry point that should
- * exit with the program's code, use {@link run} instead.
+ * registered under an external test runner (Node `--test`, Bun, Deno) that owns
+ * the process lifecycle. For a standalone CLI entry point that should exit with
+ * the program's code, use {@link run} instead.
  */
 export declare const runEffect: (p: NodeProgram) => Promise<number>;
 /**

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

@@ -224,8 +224,7 @@ export type Await = readonly ['await', (p: unknown) => readonly [unknown]];
 export declare const awaitIfPromise: (p: unknown) => Effect<Await, unknown>;
 /**
  * Signature of a framework test-registration function (e.g. `nodeTest.test`,
- * `bunTest.test`, `pwTest`). Returns `Promise<void>` so async sub-tests can
- * be awaited.
+ * `bunTest.test`). Returns `Promise<void>` so async sub-tests can be awaited.
  */
 export type TestFn = (name: string, options: {
     readonly expectFailure: boolean;
@@ -233,8 +232,8 @@ export type TestFn = (name: string, options: {
 /**
  * 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 and Playwright, which do not support nested
- * `test()` calls inside a callback).
+ * (e.g. `inlineContext` on Bun, which does not support nested `test()` calls
+ * inside a callback).
  */
 export type TestContext = {
     readonly test: TestFn;
@@ -247,7 +246,7 @@ export type NodeEffect<T> = Effect<NodeOp, T>;
 /**
  * Writes an error line to `stderr` and yields exit code `1`. The canonical
  * "fail with a message" program for a `NodeProgram`. For non-`1` exit codes,
- * compose `error(s).step(() => pure(n))` directly.
+ * compose `mapStep(error(s), () => n)` directly.
  */
 export declare const errorExit: (s: string) => Effect<Write, number>;
 export type NodeOperationMap = ToAsyncOperationMap<NodeOp>;
@@ -258,7 +257,16 @@ export type Env = {
     readonly [k: string]: string | undefined;
 };
 /** Identifies the JavaScript runtime detected at startup. */
-export type Engine = 'node' | 'bun' | 'playwright';
+export type Engine = 'node' | 'bun' | 'deno';
+/** Compares semantic versions numerically by major, minor, then patch. */
+export declare const versionLessThan: (version: string, minimum: string) => boolean;
+/**
+ * Reports whether an external runner needs FunctionalScript's flattened test
+ * registration strategy. Node uses the native `expectFailure` option only
+ * from the Node 26 baseline; Deno is deliberately exempt from this Node-only
+ * version check.
+ */
+export declare const usesInlineTestContext: (engine: Engine, nodeVersion?: string) => boolean;
 /**
  * Runtime options passed to every `NodeProgram`.
  *
@@ -269,8 +277,9 @@ export type Engine = 'node' | 'bun' | 'playwright';
  * - `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.
- * - `playwrightTestContext`: Playwright context using the same inline strategy.
  * - `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[];
@@ -283,8 +292,9 @@ export type NodeProgramOptions = {
     };
     readonly testContext: TestContext;
     readonly bunTestContext: TestContext;
-    readonly playwrightTestContext: 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/module.f.js

@@ -14,7 +14,7 @@ import { codePointListToString } from '../../text/utf16/module.f.js';
 import { reverse } from '../../types/list/module.f.js';
 import { length } from '../../types/bit_vec/module.f.js';
 import { ok, error as resultError, mapOk } from '../../types/result/module.f.js';
-import { do_, okStep, pure } from '../module.f.js';
+import { do_, mapStep, okStep, pure, step } from '../module.f.js';
 /**
  * True if `e` is a "file or directory does not exist" (`ENOENT`) error.
  *
@@ -43,7 +43,7 @@ export const readFile = do_('readFile');
  * on errors (e.g. convert them into domain-specific errors) or `unwrap` at the
  * call site.
  */
-export const readUtf8File = (path) => readFile(path).step(r => pure(mapOk(utf8ToString)(r)));
+export const readUtf8File = (path) => mapStep(readFile(path), mapOk(utf8ToString));
 export const readdir = do_('readdir');
 export const writeFile = do_('writeFile');
 /** Writes a string to `path` as UTF-8 bytes. */
@@ -57,7 +57,7 @@ export const access = do_('access');
 export const createExclusive = do_('createExclusive');
 export const writeBytes = do_('writeBytes');
 const writeLoop = (path) => {
-    const f = (offset, e) => e.step(r => {
+    const f = (offset, e) => step(e, r => {
         if (r === undefined) {
             return pure(ok(undefined));
         }
@@ -69,13 +69,11 @@ const writeLoop = (path) => {
         if ((lenV & 7n) !== 0n) {
             return pure(resultError('invalid buffer size'));
         }
-        return writeBytes(path, offset, v)
-            .step(okStep(() => f(offset + Number(lenV >> 3n), tail)));
+        return step(writeBytes(path, offset, v), okStep(() => f(offset + Number(lenV >> 3n), tail)));
     });
     return f;
 };
-export const writeFromStream = (path, e) => createExclusive(path)
-    .step(okStep(() => writeLoop(path)(0, e)));
+export const writeFromStream = (path, e) => step(createExclusive(path), okStep(() => writeLoop(path)(0, e)));
 export const stat = do_('stat');
 export const createServer = do_('createServer');
 export const listen = do_('listen');
@@ -113,7 +111,7 @@ const lf = 0x0a;
  * rather than the O(n²) of copying a growing array on every byte.
  */
 export const readLine = (stream) => {
-    const loop = (acc) => read(stream).step(b => b === null
+    const loop = (acc) => step(read(stream), b => b === null
         ? pure(acc === null ? null : utf8ListToString(reverse(acc)))
         : b === lf
             ? pure(utf8ListToString(reverse(acc)))
@@ -141,11 +139,33 @@ export const now = do_('now');
  */
 export const sandbox = do_('sandbox');
 const awaitPromise = do_('await');
-export const awaitIfPromise = (p) => awaitPromise(p).step(([x]) => pure(x));
+export const awaitIfPromise = (p) => mapStep(awaitPromise(p), ([x]) => x);
 export const test = do_('test');
 /**
  * Writes an error line to `stderr` and yields exit code `1`. The canonical
  * "fail with a message" program for a `NodeProgram`. For non-`1` exit codes,
- * compose `error(s).step(() => pure(n))` directly.
+ * compose `mapStep(error(s), () => n)` directly.
  */
-export const errorExit = (s) => error(s).step(() => pure(1));
+export const errorExit = (s) => mapStep(error(s), () => 1);
+const versionParts = (version) => version.replace(/^v/, '').split('.').map(Number);
+/** Compares semantic versions numerically by major, minor, then patch. */
+export const versionLessThan = (version, minimum) => {
+    const [major = 0, minor = 0, patch = 0] = versionParts(version);
+    const [minMajor = 0, minMinor = 0, minPatch = 0] = versionParts(minimum);
+    return major < minMajor || major === minMajor && (minor < minMinor || minor === minMinor && patch < minPatch);
+};
+/**
+ * Reports whether an external runner needs FunctionalScript's flattened test
+ * registration strategy. Node uses the native `expectFailure` option only
+ * from the Node 26 baseline; Deno is deliberately exempt from this Node-only
+ * version check.
+ */
+export const usesInlineTestContext = (engine, nodeVersion) => {
+    if (engine === 'bun') {
+        return true;
+    }
+    if (engine !== 'node' || nodeVersion === undefined) {
+        return false;
+    }
+    return versionLessThan(nodeVersion, '26.0.0');
+};

package/fjs/effects/node/module.js

@@ -32,7 +32,7 @@ import { concat, normalize, toPosix } from '../../path/module.f.js';
 import {} from '../module.f.js';
 import { asyncRun } from '../module.js';
 import { memoryOperationMap } from './memory/module.js';
-import {} from './module.f.js';
+import { usesInlineTestContext, } from './module.f.js';
 import { asBase, asNominal } from '../../types/nominal/module.f.js';
 import { error, ok } from '../../types/result/module.f.js';
 import { asyncTryCatch } from '../../types/result/module.js';
@@ -250,10 +250,6 @@ const runNodeEffect = asyncRun({
     read: readStdinByte,
     test: async (ctx, name, expectFailure, test) => ctx.test(name, { expectFailure }, async (t) => runNodeEffect(test(t))),
 });
-const isPlaywright = 'PLAYWRIGHT_TEST' in (process?.env ?? {});
-const pwTest = isPlaywright
-    ? (await import('@playwright/test')).test
-    : undefined;
 const inlineTest = async (name, { expectFailure }, fn) => {
     if (expectFailure) {
         try {
@@ -273,25 +269,29 @@ const wrapInlineTest = (register) => ({
     test: (name, opts, fn) => register(name, () => inlineTest(name, opts, fn))
 });
 const bunTestContext = wrapInlineTest(testContext.test);
-const playwrightTestContext = wrapInlineTest(pwTest);
+const engine = 'Bun' in globalThis ? 'bun' :
+    'Deno' in globalThis ? 'deno' : 'node';
+const nodeVersion = engine === 'node' ? process.version : undefined;
+const inlineTestContext = usesInlineTestContext(engine, nodeVersion);
 const options = {
     args: process.argv.slice(2),
     env: process.env,
     home: toPosix(os.homedir()),
     std: { stdout: process.stdout, stderr: process.stderr },
-    testContext,
+    testContext: inlineTestContext ? wrapInlineTest(testContext.test) : testContext,
     bunTestContext,
-    playwrightTestContext,
-    engine: isPlaywright ? 'playwright' : 'Bun' in globalThis ? 'bun' : 'node',
+    engine,
+    ...(nodeVersion === undefined ? {} : { nodeVersion }),
+    inlineTestContext,
 };
 /**
  * Runs a `NodeProgram` against the real Node globals and process arguments,
  * resolving to its exit code **without** terminating the process.
  *
  * Use this when the caller must stay alive afterwards — e.g. when proofs are
- * registered under an external test runner (Node `--test`, Bun, Playwright)
- * that owns the process lifecycle. For a standalone CLI entry point that should
- * exit with the program's code, use {@link run} instead.
+ * registered under an external test runner (Node `--test`, Bun, Deno) that owns
+ * the process lifecycle. For a standalone CLI entry point that should exit with
+ * the program's code, use {@link run} instead.
  */
 export const runEffect = program => runNodeEffect(program(options));
 /**

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

@@ -1,4 +1,5 @@
 export declare const proof: {
+    externalTestContext: () => void;
     map: () => void;
     fetch: () => void;
     mkdir: {