functionalscript 0.45.0 → 0.46.1

package/fjs/effects/types.d.ts

@@ -3,19 +3,102 @@
  *
  * @module
  */
-export type Operation = readonly [string, (..._: readonly never[]) => unknown];
+import type { Ok, Error, Result } from '../types/result/types.ts';
 /**
- * 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`.
+ * A command name paired with the signature a runner implements it at.
+ *
+ * **The return type is a {@link Result}, and that is a rule rather than a
+ * convention every operation happens to follow.** A runner may decline any
+ * command it was not given a handler for — `partialMatch` answers
+ * `error(notImplemented(command))` through the command's own output — so an
+ * operation whose return admitted no error would be a hole in that mechanism:
+ * there would be nowhere to put the refusal. Every *host* operation already
+ * returned `OpResult<…>` or `IoResult<…>` when this constraint was added, and
+ * so did four of the six declared inside proofs — through a bare `Result`
+ * rather than either alias, since those two are node conveniences. The two in
+ * `./proof.f.mjs` returned a bare `number`, and the commit that added the rule
+ * rewrote them.
+ *
+ * It is also the latch the whole representation now rests on. An operation
+ * *cannot* be declared infallible, so every {@link Effect} built from one has a
+ * `Result` to carry — which is what lets {@link Effect} name its error channel
+ * rather than leaving it inside an opaque payload.
  */
-export type Effect<O extends Operation, T> = Pure<T> | Do<O, T>;
+export type Operation = readonly [string, (..._: readonly never[]) => Result<unknown, unknown>];
 /**
- * A pure effect: an *already-computed* `T` behind a thunk.
+ * The runner cannot dispatch this operation and has **not** started it.
+ *
+ * It is ordinary recoverable effect data rather than a fatal runner condition:
+ * the program receives control back and decides what an incompatible runner
+ * means for it — recover, choose a fallback operation, or treat it as fatal and
+ * panic itself (`throw`, e.g. via `unwrap`). Escalation belongs to the program,
+ * so the missing-handler path answers with `error(notImplemented)` rather than
+ * panicking on the program's behalf.
+ *
+ * **It identifies the operation by command name only.** An operation's payload
+ * may hold functions — `createServer`'s listener, `sandbox`'s thunk, `test`'s
+ * body — so carrying it would break the serializability the asserts in
+ * the asserts at the bottom of this file pin against the JSON data model.
+ *
+ * **It is not a security boundary.** A runner keeps its authority over
+ * execution through a separate, out-of-band mechanism: it may interrupt or
+ * terminate a program that is malicious, over budget, or violating host policy,
+ * and nothing in the error channel obliges it to hand control back. A
+ * capability the runner merely lacks is answered with this error; a refusal to
+ * continue is an interruption, never dressed up as `NotImplemented`.
+ *
+ * **It is why there is no infallible effect.** Every {@link Do} node is
+ * dispatched by a runner that may decline the command, so an effect that
+ * declared no error channel would be describing today's runner rather than the
+ * computation. That observation is what collapsed the representation into this
+ * one type — see {@link Effect}.
+ */
+export type NotImplemented = readonly ['notImplemented', string];
+/**
+ * An `Effect<O, T, E>` is the raw value: a {@link Pure} thunk yielding
+ * `Result<T, E>`, or a {@link Do} node describing a command to perform. It is
+ * plain data — compose effects with the combinators in
+ * [`./module.f.mjs`](./module.f.mjs), which are eager wherever the head
+ * is `Pure`.
+ *
+ * **The error channel is part of the representation, not a wrapper over it.**
+ * This used to be two types: a `RawEffect<O, T>` with an opaque payload, and an
+ * `Effect<O, T, E>` alias for `RawEffect<O, Result<T, E>>`. The division was
+ * described as *composition* against *representation*, and it was defended on
+ * the grounds that the representation is generic over its payload by
+ * definition — the runners, {@link match}, `runPure`, `do_`. That is true and
+ * it is not a reason for two names: {@link Operation} requires a `Result`
+ * return, so the payload a runner is generic over is *always* `Result<T, E>`
+ * already. Naming its two halves costs nothing and lets every signature in the
+ * system say which half it means.
  *
- * 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
+ * **`E` defaults to {@link NotImplemented}**, the one error every operation can
+ * answer with, so the common case is written `Effect<Sandbox, T>`. An
+ * operation's own failures extend the channel — `Effect<ReadFile, Vec,
+ * IoChannel>`, that alias being the node standard of
+ * `NotImplemented | IoError`.
+ *
+ * **`Effect<O, T, never>` is a claim, not an absence.** It says this code
+ * absorbs its own failures *here* — an MCP handler turning one into a JSON-RPC
+ * error response, a decoder turning one into `null`, a test body turning one
+ * into a panic. A reader who thinks the absorption is wrong has something to
+ * point at, which is what the opaque payload could not offer.
+ *
+ * The channel is where **short-circuiting** lives, not specifically where a
+ * runner's refusal lives. A parse failure, a domain verdict, or a non-zero exit
+ * code belongs in it for the same reason {@link NotImplemented} does: `step`
+ * should stop the chain and carry it out.
+ *
+ * It widens and does not narrow, in both channels and in `O` — the asserts in
+ * the asserts at the bottom of this file pin each direction, so an unhandled error
+ * type is a compile error rather than a value nobody looked at.
+ */
+export type Effect<O extends Operation, T, E = NotImplemented> = Pure<T, E> | Do<O, T, E>;
+/**
+ * A pure effect: an *already-computed* `Result<T, E>` behind a thunk.
+ *
+ * The thunk is a **discriminator, not a suspension**. {@link 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
@@ -26,19 +109,19 @@ export type Effect<O extends Operation, T> = Pure<T> | Do<O, T>;
  * - **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.
+ *   can be decoded repeatedly, 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 Pure<T, E> = () => Result<T, E>;
 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.
+ * A {@link 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*
@@ -55,7 +138,7 @@ export type Pr<O extends Operation, K extends O[0]> = O extends readonly [K, (..
  * 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>;
+export type Cont<out O extends Operation, T, E> = (_: Pr<O, O[0]>[1]) => Effect<O, T, E>;
 /**
  * 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,
@@ -64,7 +147,7 @@ export type Cont<out O extends Operation, T> = (_: Pr<O, O[0]>[1]) => Effect<O,
  *
  * 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
+ * (`TS2637` forbids `out` on a tuple), and the {@link 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
@@ -78,27 +161,25 @@ export type Cont<out O extends Operation, T> = (_: Pr<O, O[0]>[1]) => Effect<O,
  * 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> = {
+export type Do<out O extends Operation, T, E> = {
     readonly command: O[0];
     readonly payload: Pr<O, O[0]>[0];
-    readonly continuation: Cont<O, T>;
+    readonly continuation: Cont<O, T, E>;
 };
+export type Param<O extends Operation> = F<O>[0];
+export type Return<O extends Operation> = F<O>[1];
 /**
- * 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.
+ * The success half of a {@link Result} type, and {@link ErrOf} the error half.
  *
- * 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.
+ * These read an operation's *declared* return apart so that {@link Func} can
+ * state the effect `do_` builds from it. {@link Operation} guarantees the
+ * return is a `Result`, so neither is ever the `never` its fallback branch
+ * names; and both distribute over the union, which is what makes
+ * `Result<T, E>` decompose back into exactly `T` and `E`.
  */
-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];
+export type OkOf<R> = R extends Ok<infer T> ? T : never;
+/** The error half of a {@link Result} type — see {@link OkOf}. */
+export type ErrOf<R> = R extends Error<infer E> ? E : never;
 /**
  * An operation map whose entries take a command's payload and return some
  * output `R`. Generalizes `ToAsyncOperationMap` (`R = Promise<…>`) and the
@@ -107,9 +188,56 @@ export type Return<O extends Operation> = F<O>[1];
 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']];
+/**
+ * An {@link OperationMap} a runner may leave holes in: every handler it *does*
+ * provide has the same type, and any of them may be absent.
+ *
+ * Partiality is opt-in, and deliberately not the default. A total map means a
+ * runner that forgets a handler is a compile error, which is what should happen
+ * to the Node runner; this type is for a runner that is *meant* to lack
+ * operations — a virtual filesystem with no subprocesses, a mock that answers
+ * the three commands its proof issues. An absent handler here is an answer
+ * (`error(notImplemented)`), not an oversight.
+ */
+export type PartialOperationMap<O extends Operation, R> = {
+    readonly [K in O[0]]?: (...payload: Pr<O, K>[0]) => R;
+};
+/**
+ * The runtime witness of `O`'s command set.
+ *
+ * A {@link PartialOperationMap} cannot say, at runtime, whether a command it
+ * has no handler for is one the operation set declares — types are erased, so
+ * an omitted `readFile` and a garbled `readFilee` reach the interpreter as the
+ * same missing lookup. They are not the same thing: the first is a capability
+ * this runner lacks and a program may recover from, the second is a `Do` node
+ * whose `command` was never the one its type claimed. Telling them apart needs
+ * `O`'s commands as data.
+ *
+ * Declare it as a record rather than an array — a `Record<O[0], null>` is
+ * checked for *completeness*, so a command added to `O` and forgotten here is a
+ * compile error, whereas an array literal only has its members checked and
+ * drifts silently.
+ */
+export type CommandSet<O extends Operation> = Readonly<Record<O[0], null>>;
+/** `O`'s commands, in the form {@link match} tests membership against. */
+export type Commands<O extends Operation> = readonly O[0][];
+/**
+ * What one decoding step of an effect yields: the finished `Result`, or the
+ * operation's output `R` paired with the continuation to resume with.
+ *
+ * The `done` payload is the whole `Result`, not its `ok` half. An interpreter
+ * is the one reader that must not short-circuit — a runner hands a failed
+ * command's `error` back *through* the continuation, so the two channels only
+ * separate above this layer.
+ */
+export type MatchResult<O extends Operation, T, E, R> = readonly ['done', Result<T, E>] | readonly ['cont', R, Cont<O, T, E>];
 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>>;
+/**
+ * The effect-returning function `do_` builds for a single operation: its
+ * payload in, an {@link Effect} whose two channels are the halves of the
+ * operation's declared `Result` out.
+ */
+export type Func<O extends Operation> = (..._: Param<O>) => Effect<O, OkOf<Return<O>>, ErrOf<Return<O>>>;

package/fjs/emergent_testing/module.f.d.mts

@@ -10,15 +10,17 @@
  *
  * @module
  *
- * @import { Effect, Operation } from '../effects/types.ts'
+ * @import { Operation } from '../effects/types.ts'
+ * @import { Effect, NotImplemented } from '../effects/types.ts'
  * @import { LoadModuleOperations, ModuleMap } from '../dev/types.ts'
  * @import { TestFn, TestEntry, TestSet, Path, Reporter, _TestState, _TestAndPath } from './types.ts'
- * @import { All, Await, Env, NodeProgram, NodeProgramOptions, Program, Sandbox, SandboxResult, Test, TestContext, Write, WriteConsoles } from '../effects/node/types.ts'
+ * @import { All, Await, Env, IoChannel, NodeProgram, NodeProgramOptions, Program, Sandbox, SandboxResult, Test, TestContext, Write, WriteConsoles } from '../effects/node/types.ts'
  */
-import type { Effect, Operation } from '../effects/types.ts';
+import type { Operation } from '../effects/types.ts';
+import type { Effect, NotImplemented } from '../effects/types.ts';
 import type { LoadModuleOperations, ModuleMap } from '../dev/types.ts';
 import type { TestEntry, TestSet, Path, Reporter, _TestAndPath } from './types.ts';
-import type { All, Await, NodeProgram, NodeProgramOptions, Program, Sandbox, SandboxResult, Test, TestContext, Write } from '../effects/node/types.ts';
+import type { All, Await, IoChannel, NodeProgram, NodeProgramOptions, Program, Sandbox, SandboxResult, Test, TestContext, Write } from '../effects/node/types.ts';
 /**
  * Converts an arbitrary JS value into a `TestSet`.
  *
@@ -54,9 +56,9 @@ export declare const collectTests: (path: Path, throws: boolean, v: unknown) =>
  * This is the correct model for Node `--test`, Bun, and Deno, where tests must
  * be declared upfront and the framework drives execution.
  *
- * @type {(ctx: TestContext, k: string, v: unknown, star: string) => Effect<Test | All | Await, void>}
+ * @type {(ctx: TestContext, k: string, v: unknown, star: string) => Effect<Test | All | Await, void, NotImplemented>}
  */
-export declare const registerModule: (ctx: TestContext, k: string, v: unknown, star: string) => Effect<Test | All | Await, void>;
+export declare const registerModule: (ctx: TestContext, k: string, v: unknown, star: string) => Effect<Test | All | Await, void, NotImplemented>;
 /**
  * Runs all test modules in `moduleMap` whose names pass `isTest`, accumulates
  * pass/fail/time via `reporter`, and returns an exit code (0 = all passed,
@@ -64,19 +66,24 @@ export declare const registerModule: (ctx: TestContext, k: string, v: unknown, s
  *
  * @template {Operation} O
  * @param {Reporter<O>} reporter
- * @returns {(moduleMap: ModuleMap) => Effect<O | All, number>}
+ * @returns {(moduleMap: ModuleMap) => Effect<O | All, number, IoChannel>}
  */
-export declare const runModuleMap: <O extends Operation>(reporter: Reporter<O>) => (moduleMap: ModuleMap) => Effect<O | All, number>;
+export declare const runModuleMap: <O extends Operation>(reporter: Reporter<O>) => (moduleMap: ModuleMap) => Effect<O | All, number, IoChannel>;
 /**
  * Discovers all test modules via `loadModuleMap`, then runs them through
  * `runModuleMap`. The composed effect is a `NodeProgram` entry point for the
  * `fjs t` test runner.
  *
+ * The chain leaves the error channel here, because this is where a `Program` ends
+ * and a `Program`'s answer is an exit code rather than a `Result`. A run that
+ * could not report its own results is a failed run, so it exits `1` with the
+ * reason on `stderr` instead of unwinding as a panic.
+ *
  * @template {Operation} O
  * @param {Reporter<O>} reporter
- * @returns {Program<O | All | LoadModuleOperations>}
+ * @returns {Program<O | All | LoadModuleOperations | Write>}
  */
-export declare const testAll: <O extends Operation>(reporter: Reporter<O>) => Program<O | All | LoadModuleOperations>;
+export declare const testAll: <O extends Operation>(reporter: Reporter<O>) => Program<O | All | LoadModuleOperations | Write>;
 /** Returns `true` if `s` is a non-negative decimal integer without a leading zero.
  *
  * @type {(s: string) => boolean}
@@ -125,9 +132,9 @@ export declare const ghEscape: (s: string) => string;
  * Default `Reporter.test` implementation: sandboxes `fn` once and inverts the
  * result when `throws` is `true` (caught error → pass, clean return → fail).
  *
- * @type {(file: string, path: Path, entry: TestEntry) => Effect<Sandbox, SandboxResult<unknown>>}
+ * @type {(file: string, path: Path, entry: TestEntry) => Effect<Sandbox, SandboxResult<unknown>, NotImplemented>}
  */
-export declare const defaultTest: (file: string, path: Path, entry: TestEntry) => Effect<Sandbox, SandboxResult<unknown>>;
+export declare const defaultTest: (file: string, path: Path, entry: TestEntry) => Effect<Sandbox, SandboxResult<unknown>, NotImplemented>;
 /**
  * The terminal/GitHub reporter used by `fjs t`. Output goes through
  * `csiWrite`, so ANSI styles are stripped on non-TTY streams. When

package/fjs/emergent_testing/module.f.mjs

@@ -10,15 +10,18 @@
  *
  * @module
  *
- * @import { Effect, Operation } from '../effects/types.ts'
+ * @import { Operation } from '../effects/types.ts'
+ * @import { Effect, NotImplemented } from '../effects/types.ts'
  * @import { LoadModuleOperations, ModuleMap } from '../dev/types.ts'
  * @import { TestFn, TestEntry, TestSet, Path, Reporter, _TestState, _TestAndPath } from './types.ts'
- * @import { All, Await, Env, NodeProgram, NodeProgramOptions, Program, Sandbox, SandboxResult, Test, TestContext, Write, WriteConsoles } from '../effects/node/types.ts'
+ * @import { All, Await, Env, IoChannel, NodeProgram, NodeProgramOptions, Program, Sandbox, SandboxResult, Test, TestContext, Write, WriteConsoles } from '../effects/node/types.ts'
  */
 
 import { reset, fgGreen, fgRed, bold, csiWrite } from '../text/sgr/module.f.mjs'
-import { all, awaitIfPromise, sandbox, test } from '../effects/node/module.f.mjs'
-import { history, historyStep, mapStep, pure, step } from '../effects/module.f.mjs'
+import { allOk, awaitIfPromise, errorExit, errorMessage, errorSummary, exitStep, sandbox, test } from '../effects/node/module.f.mjs'
+import {
+    catchStep, history, historyStep, mapStep, pureError, pureOk, resultStep, step,
+} from '../effects/module.f.mjs'
 import { loadModuleMap } from '../dev/module.f.mjs'
 import { invert } from '../types/result/module.f.mjs'
 import { definedEntries } from '../types/object/module.f.mjs'
@@ -104,10 +107,10 @@ export const collectTests = (path, throws, v) => {
  * This is the correct model for Node `--test`, Bun, and Deno, where tests must
  * be declared upfront and the framework drives execution.
  *
- * @type {(ctx: TestContext, k: string, v: unknown, star: string) => Effect<Test | All | Await, void>}
+ * @type {(ctx: TestContext, k: string, v: unknown, star: string) => Effect<Test | All | Await, void, NotImplemented>}
  */
 export const registerModule = (ctx, k, v, star) => {
-    /** @type {(ctx: TestContext, entry: _TestAndPath) => Effect<Test | All | Await, void>} */
+    /** @type {(ctx: TestContext, entry: _TestAndPath) => Effect<Test | All | Await, void, NotImplemented>} */
     const registerOne = (ctx, [path, { fn, throws }]) => {
         // `star` (non-empty for Bun and for Node below the 26 baseline) signals
         // that all sub-tests run inline inside this single registration, so an
@@ -117,22 +120,38 @@ export const registerModule = (ctx, k, v, star) => {
         // extra suffix is needed.
         const base = fmtImport(k, path)
         const name = throws ? base : `${base}${star}`
-        return test(ctx, name, throws, (/** @type {TestContext} */ t) =>
-            step(awaitIfPromise(fn()), resolved => {
+        // The registered callback panics on failure, deliberately. `Test` hands
+        // it to an external framework (node `--test`, Bun, Deno) that takes a
+        // body which either returns or throws: there is no channel to answer a
+        // failure through, so propagating it here would only discard it one
+        // level up.
+        // A throw is what that framework *does* understand — it reports the
+        // test as failed, which is the outcome a caller wants anyway. The `test`
+        // operation's own result is propagated normally, just below.
+        //
+        // `catchStep` rather than `unwrapStep`, so the absorption is visible in
+        // the type: the body answers `Effect<…, void, never>`, and the `never`
+        // is *because* this handler panics. `errorSummary` still names what is
+        // being panicked on and pins it, so if the body's channel ever widens
+        // past the node one, the compiler asks here rather than turning a new
+        // recoverable failure into a crash.
+        /** @type {(t: TestContext) => Effect<Test | All | Await, void, never>} */
+        const body = t =>
+            catchStep(step(awaitIfPromise(fn()), resolved => {
                 if (throws) {
-                    return pure(undefined)
+                    return pureOk(undefined)
                 }
                 const sub = collectTests([...path, null], false, resolved)
                 if (sub.length === 0) {
-                    return pure(undefined)
+                    return pureOk(undefined)
                 }
-                return mapStep(all(...sub.map(e => registerOne(t, e))), () => undefined)
-            })
-        )
+                return mapStep(allOk(...sub.map(e => registerOne(t, e))), () => undefined)
+            }), e => { throw errorSummary(e) })
+        return test(ctx, name, throws, body)
     }
     const tests = collectTests([], false, v)
-    if (tests.length === 0) { return pure(undefined) }
-    return mapStep(all(...tests.map(e => registerOne(ctx, e))), () => undefined)
+    if (tests.length === 0) { return pureOk(undefined) }
+    return mapStep(allOk(...tests.map(e => registerOne(ctx, e))), () => undefined)
 }
 
 /** @type {(a: _TestState, b: _TestState) => _TestState} */
@@ -145,10 +164,10 @@ const zero = { time: 0, pass: 0, fail: 0 }
 /**
  * @template {Operation} O
  * @param {Reporter<O>} reporter
- * @returns {(k: string, v: unknown) => (ts: _TestState) => Effect<O | All, _TestState>}
+ * @returns {(k: string, v: unknown) => (ts: _TestState) => Effect<O | All, _TestState, IoChannel>}
  */
 const runModule = ({ result, test }) => (k, v) => ts => {
-    /** @type {(entry: _TestAndPath) => Effect<O | All, _TestState>} */
+    /** @type {(entry: _TestAndPath) => Effect<O | All, _TestState, IoChannel>} */
     const one = ([testPath, set]) => {
         // The sandbox result is still needed after it has been reported, so the
         // reporting call is captured rather than nested inside its own step.
@@ -160,22 +179,22 @@ const runModule = ({ result, test }) => (k, v) => ts => {
             ([, sr]) => {
                 const { result: [s, r], duration } = sr
                 if (s !== 'ok') {
-                    return pure(addFail(duration)(zero))
+                    return pureOk(addFail(duration)(zero))
                 }
                 if (set.throws) {
-                    return pure(addPass(duration)(zero))
+                    return pureOk(addPass(duration)(zero))
                 }
                 // Walk return-value sub-tree; null marks the call boundary so
                 // paths render as e.g. `outer().inner`. throws resets to false.
-                return step(
+                return mapStep(
                     walk([...testPath, null], false, r),
-                    sub => pure(mergeState(addPass(duration)(zero), sub)))
+                    sub => mergeState(addPass(duration)(zero), sub))
             })
     }
-    /** @type {(path: Path, throws: boolean, v: unknown) => Effect<O | All, _TestState>} */
+    /** @type {(path: Path, throws: boolean, v: unknown) => Effect<O | All, _TestState, IoChannel>} */
     const walk = (path, throws, v) => {
         const effects = collectTests(path, throws, v).map(one)
-        return mapStep(all(...effects), states => states.reduce(mergeState, zero))
+        return mapStep(allOk(...effects), states => states.reduce(mergeState, zero))
     }
     return mapStep(walk([], false, v), delta => mergeState(ts, delta))
 }
@@ -192,13 +211,13 @@ const proofEntries = moduleMap =>
  *
  * @template {Operation} O
  * @param {Reporter<O>} reporter
- * @returns {(moduleMap: ModuleMap) => Effect<O | All, number>}
+ * @returns {(moduleMap: ModuleMap) => Effect<O | All, number, IoChannel>}
  */
 export const runModuleMap = reporter => moduleMap => {
     const { summary } = reporter
     const modules = proofEntries(moduleMap)
     const total = mapStep(
-        all(...modules.map(([k, v]) => runModule(reporter)(k, v)(zero))),
+        allOk(...modules.map(([k, v]) => runModule(reporter)(k, v)(zero))),
         m => m.reduce(mergeState, zero))
     // The totals are still needed after the summary has been printed, so they
     // are carried forward in a history rather than closed over by a nested
@@ -209,28 +228,57 @@ export const runModuleMap = reporter => moduleMap => {
     return mapStep(reported, ([, ts]) => ts.fail !== 0 ? 1 : 0)
 }
 
+/**
+ * Ends a run with the exit code it computed, reporting a channel failure on
+ * `stderr` as exit `1`.
+ *
+ * Not `exitStep`, which answers `0` for every success: this chain's success
+ * value **is** the exit code, `1` when a test failed. The two policies differ
+ * only in what an `ok` means, and conflating them would report a failing suite
+ * as a passing run.
+ *
+ * A non-zero code therefore leaves through the *error* branch, which is what it
+ * means — a suite with failures is a failed program — and is why a caller
+ * cannot chain past it by accident.
+ *
+ * @type {<O extends Operation>(e: Effect<O, number, IoChannel>) => Effect<O | Write, 0, number>}
+ */
+const exitCodeStep = e =>
+    resultStep(e, r => {
+        /** @type {Effect<Write, 0, number>} */
+        const code = r[0] === 'error'
+            ? errorExit(errorMessage(r[1]))
+            : r[1] === 0 ? pureOk(0) : pureError(r[1])
+        return code
+    })
+
 /**
  * Discovers all test modules via `loadModuleMap`, then runs them through
  * `runModuleMap`. The composed effect is a `NodeProgram` entry point for the
  * `fjs t` test runner.
  *
+ * The chain leaves the error channel here, because this is where a `Program` ends
+ * and a `Program`'s answer is an exit code rather than a `Result`. A run that
+ * could not report its own results is a failed run, so it exits `1` with the
+ * reason on `stderr` instead of unwinding as a panic.
+ *
  * @template {Operation} O
  * @param {Reporter<O>} reporter
- * @returns {Program<O | All | LoadModuleOperations>}
+ * @returns {Program<O | All | LoadModuleOperations | Write>}
  */
 export const testAll = reporter => options =>
-    step(loadModuleMap(options.env), runModuleMap(reporter))
+    exitCodeStep(step(loadModuleMap(options.env), runModuleMap(reporter)))
 
 /**
  * Registers all modules in `moduleMap` that export a `proof` property with
  * `ctx`. Delegates to `registerModule` for each matching entry.
  *
- * @type {(ctx: TestContext, star: string) => (moduleMap: ModuleMap) => Effect<Test | All | Await, void>}
+ * @type {(ctx: TestContext, star: string) => (moduleMap: ModuleMap) => Effect<Test | All | Await, void, NotImplemented>}
  */
 const registerModuleMap = (ctx, star) => moduleMap => {
     const modules = proofEntries(moduleMap)
-    if (modules.length === 0) { return pure(undefined) }
-    return mapStep(all(...modules.map(([k, v]) => registerModule(ctx, k, v, star))), () => undefined)
+    if (modules.length === 0) { return pureOk(undefined) }
+    return mapStep(allOk(...modules.map(([k, v]) => registerModule(ctx, k, v, star))), () => undefined)
 }
 
 /** @type {(c: string) => boolean} */
@@ -316,7 +364,7 @@ export const ghEscape = s =>
  * Default `Reporter.test` implementation: sandboxes `fn` once and inverts the
  * result when `throws` is `true` (caught error → pass, clean return → fail).
  *
- * @type {(file: string, path: Path, entry: TestEntry) => Effect<Sandbox, SandboxResult<unknown>>}
+ * @type {(file: string, path: Path, entry: TestEntry) => Effect<Sandbox, SandboxResult<unknown>, NotImplemented>}
  */
 export const defaultTest = (file, path, { fn, throws }) =>
     mapStep(sandbox(fn), r => throws ? { ...r, result: invert(r.result) } : r)
@@ -336,7 +384,12 @@ const fmtResultLine = (file, path, color, label, duration) =>
  */
 export const defaultReporter = options => {
     const write = csiWrite(options)
-    /** @type {(w: WriteConsoles) => (s: string) => Effect<Write, void>} */
+    // A reporter that cannot emit its own output has no fallback to choose —
+    // there is nowhere left to report the failure — but it does not have to
+    // decide that here: the failure travels to the program's tail, which ends
+    // the run with the reason on `stderr` and exit `1`. That is the same
+    // outcome a panic produced, minus the stack trace.
+    /** @type {(w: WriteConsoles) => (s: string) => Effect<Write, void, NotImplemented>} */
     const line = w => {
         const x = write(w)
         return s => x(s + '\n')
@@ -351,6 +404,9 @@ export const defaultReporter = options => {
                 ? csiLog(fmtResultLine(file, path, fgGreen, 'ok', duration) + (throws ? ' # EXPECTED TO THROW' : ''))
                 : isGitHub
                     ? csiError(`::error file=${file},line=1,title=${ghEscape(fmtImport(file, path))}::${ghEscape(String(v))}`)
+                    // `step`, so the detail line is attempted only when the
+                    // header line was written: two halves of one report, and
+                    // half of it is worse than none.
                     : step(
                         csiError(fmtResultLine(file, path, fgRed, 'error', duration)),
                         () => csiError(`${fgRed}${v}${reset}`)),
@@ -384,5 +440,9 @@ export const register = o => {
     const star = o.inlineTestContext ? ' ...' : ''
     const ctx = o.engine === 'bun' ? o.bunTestContext : o.testContext
     const registered = step(loadModuleMap(o.env), registerModuleMap(ctx, star))
-    return mapStep(registered, () => 0)
+    // `exitStep`, not `mapStep(…, () => 0)`: registering is the whole job here,
+    // so "registered nothing, exit 0" is the answer this used to give and the
+    // one it must not. A success has no code of its own, which is exactly the
+    // shape `exitStep` is for.
+    return exitStep(registered)
 }

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

@@ -1,15 +1,17 @@
 /**
- * @import { Effect } from '../effects/types.ts'
- * @import { NodeProgramOptions, Sandbox, Write } from '../effects/node/types.ts'
+ * @import { RunInstance } from '../effects/mock/types.ts'
+ * @import { Effect, NotImplemented } from '../effects/types.ts'
+ * @import { NodeProgramOptions, OpResult, Sandbox, Write } from '../effects/node/types.ts'
  * @import { JsModule } from '../effects/node/virtual/types.ts'
  * @import { Reporter } from './types.ts'
- * @import { All, Await, Test, TestContext } from '../effects/node/types.ts'
+ * @import { All, Await, Import, Readdir, Test, TestContext } from '../effects/node/types.ts'
  * @import { Ts } from '../types/rtti/ts/types.ts'
  */
+import type { RunInstance } from '../effects/mock/types.ts';
 import type { Effect } from '../effects/types.ts';
-import type { Sandbox, Write } from '../effects/node/types.ts';
+import type { OpResult, Sandbox, Write } from '../effects/node/types.ts';
 import type { Reporter } from './types.ts';
-import type { All, Await, Test, TestContext } from '../effects/node/types.ts';
+import type { All, Await, Import, Readdir, Test, TestContext } from '../effects/node/types.ts';
 import type { Ts } from '../types/rtti/ts/types.ts';
 /**
  * The mock reporter's stdout lines. A schema rather than a hand-written type:
@@ -39,13 +41,19 @@ export declare const defaultReporterOutput: () => void;
 export declare const defaultReporterOutputLargeDuration: () => void;
 export declare const defaultReporterFailOutput: () => void;
 export declare const githubReporterOutput: () => void;
+export type _FailOps = All | Import | Readdir | Sandbox | Write;
+/** @typedef {All | Import | Readdir | Sandbox | Write} _FailOps */
+export declare const reporterWriteFailure: () => void;
 export type _RegisterMockState = readonly string[];
 export type _RegisterMockOps = Test | All | Await;
-export type _RegisterRunner = (s: _RegisterMockState) => <T>(e: Effect<_RegisterMockOps, T>) => readonly [_RegisterMockState, T];
-export type _RegisterTestOp = (runner: _RegisterRunner, ctx: TestContext, name: string, expectFailure: boolean, fn: (t: TestContext) => Effect<_RegisterMockOps, void>) => (s: _RegisterMockState) => readonly [_RegisterMockState, void];
+export type _RegisterRunner = RunInstance<_RegisterMockOps, _RegisterMockState>;
+export type _RegisterTestOp = (runner: _RegisterRunner, ctx: TestContext, name: string, expectFailure: boolean, fn: (t: TestContext) => Effect<_RegisterMockOps, void, never>) => (s: _RegisterMockState) => readonly [_RegisterMockState, OpResult<void>];
 export declare const registerSuffixes: () => void;
+declare const registerBodyPanicsOnUndispatchableEffect: () => void;
 export declare const registerThrowsWithoutThrowing: () => void;
 export declare const registerEmptyProof: () => void;
+export declare const registerEmptyModuleMap: () => void;
+export declare const registerSelectsContextAndStar: () => void;
 export declare const helpers: {
     isInteger: () => void;
     isIdentifier: () => void;
@@ -61,6 +69,9 @@ export declare const helpers: {
 };
 declare const defaultReporterExpectedToThrow: () => void;
 export declare const proof: {
+    throw: {
+        registerBodyPanicsOnUndispatchableEffect: typeof registerBodyPanicsOnUndispatchableEffect;
+    };
     flat: typeof flat;
     nested: typeof nested;
     throwKey: typeof throwKey;
@@ -76,9 +87,12 @@ export declare const proof: {
     defaultReporterOutputLargeDuration: typeof defaultReporterOutputLargeDuration;
     defaultReporterFailOutput: typeof defaultReporterFailOutput;
     githubReporterOutput: typeof githubReporterOutput;
+    reporterWriteFailure: typeof reporterWriteFailure;
     registerSuffixes: typeof registerSuffixes;
     registerThrowsWithoutThrowing: typeof registerThrowsWithoutThrowing;
     registerEmptyProof: typeof registerEmptyProof;
+    registerEmptyModuleMap: typeof registerEmptyModuleMap;
+    registerSelectsContextAndStar: typeof registerSelectsContextAndStar;
     defaultReporterExpectedToThrow: typeof defaultReporterExpectedToThrow;
     helpers: {
         isInteger: () => void;