effect 4.0.0-beta.70 → 4.0.0-beta.71

package/dist/Runtime.d.ts

@@ -4,9 +4,16 @@ import type * as Fiber from "./Fiber.ts";
 /**
  * Represents a teardown function that handles program completion and determines the exit code.
  *
+ * **When to use**
+ *
+ * Use when integrating {@link makeRunMain} with a host platform that needs to
+ * translate an Effect `Exit` into a process, worker, or application exit code.
+ *
  * **Details**
  *
- * A teardown function is called when an Effect program completes, either successfully or with a failure. It determines the appropriate exit code and can perform cleanup before invoking the supplied `onExit` callback.
+ * A teardown function is called when an Effect program completes, either
+ * successfully or with a failure. It determines the appropriate exit code and
+ * can perform cleanup before invoking the supplied `onExit` callback.
  *
  * **Example** (Customizing teardown behavior)
  *
@@ -46,9 +53,25 @@ export interface Teardown {
 /**
  * The default teardown function that determines exit codes from an Effect exit.
  *
+ * **When to use**
+ *
+ * Use as the standard teardown for main programs when you want conventional
+ * process exit codes and support for {@link errorExitCode}.
+ *
  * **Details**
  *
- * This teardown function follows standard Unix conventions: exit code `0` for successful completion, exit code `1` for failures unless the squashed error has a `Runtime.errorExitCode` marker, and exit code `130` for interruption-only failures.
+ * This teardown follows these exit-code rules:
+ *
+ * - `0` for successful completion.
+ * - `130` for interruption-only failures.
+ * - The squashed error's {@link errorExitCode} value for other failures when
+ *   present.
+ * - `1` for other failures.
+ *
+ * **Gotchas**
+ *
+ * The `130` code is used only when the Cause contains interruptions and no
+ * other failure reasons. Mixed causes use the squashed error path instead.
  *
  * **Example** (Using default teardown)
  *
@@ -71,17 +94,36 @@ export interface Teardown {
  * // Output: Exit code: 130
  * ```
  *
- * @category Teardown
+ * @see {@link errorExitCode} for customizing failure exit codes
+ *
+ * @category running
  * @since 4.0.0
  */
 export declare const defaultTeardown: Teardown;
 /**
  * Creates a platform-specific main program runner that handles Effect execution lifecycle.
  *
+ * **When to use**
+ *
+ * Use when building a runtime adapter for a host platform. Most applications
+ * should use a platform-provided runner, such as `NodeRuntime.runMain`, rather
+ * than constructing one directly.
+ *
  * **Details**
  *
  * The runner executes Effect programs as main entry points. The provided function receives a forked fiber and a teardown callback so it can install platform-specific signal handling, fiber observers, and final exit behavior.
  *
+ * `disableErrorReporting` disables the automatic log emitted for unreported
+ * non-interruption failures. It does not change exit-code calculation or the
+ * custom teardown callback.
+ *
+ * **Gotchas**
+ *
+ * The setup function is responsible for observing the fiber and eventually
+ * invoking teardown. `makeRunMain` also tries to keep the host process alive
+ * with a long interval while the main fiber is running; if the host blocks
+ * timers, the runner still starts but cannot use that keep-alive fallback.
+ *
  * **Example** (Creating platform runners)
  *
  * ```ts
@@ -150,10 +192,14 @@ declare global {
     }
 }
 /**
- * Type-level key for the `Runtime.errorExitCode` property that can be attached
- * to an `Error` to customize the process exit code used by `runMain`.
+ * Type-level key for the `Runtime.errorExitCode` marker.
+ *
+ * **When to use**
+ *
+ * Use to type properties keyed by `Runtime.errorExitCode` on custom error
+ * values.
  *
- * @category Exit code management
+ * @category symbols
  * @since 4.0.0
  */
 export type errorExitCode = "~effect/Runtime/errorExitCode";
@@ -161,6 +207,22 @@ export type errorExitCode = "~effect/Runtime/errorExitCode";
  * Allows associating an exit code with an error for determining the process
  * exit code on failure.
  *
+ * **When to use**
+ *
+ * Use when error classes should map failures to a specific process exit code
+ * when handled by {@link defaultTeardown}.
+ *
+ * **Details**
+ *
+ * Attach this marker as a readonly property on an error object. When the main
+ * program fails, {@link defaultTeardown} squashes the Cause and reads the marker
+ * from the resulting error value.
+ *
+ * **Gotchas**
+ *
+ * The marker is read from the squashed failure value. If a Cause contains
+ * multiple failures, the selected squashed error determines the exit code.
+ *
  * **Example** (Setting a process exit code)
  *
  * ```ts
@@ -175,40 +237,73 @@ export type errorExitCode = "~effect/Runtime/errorExitCode";
  * NodeRuntime.runMain(Effect.fail(new MyError()))
  * ```
  *
- * @category Exit code management
+ * @see {@link errorReported} for controlling automatic error logging
+ * @see {@link defaultTeardown} for the default failure exit-code rules that read this marker
+ * @see {@link getErrorExitCode} for reading the marker from unknown error values
+ *
+ * @category symbols
  * @since 4.0.0
  */
 export declare const errorExitCode: errorExitCode;
 /**
  * Reads the runtime exit-code marker from an unknown error value.
  *
+ * **When to use**
+ *
+ * Use to read a custom failure exit code from an unknown error value, falling
+ * back to the default failure code.
+ *
  * **Details**
  *
  * Returns the numeric `[Runtime.errorExitCode]` property when it is present on
  * an object. Otherwise returns `1`, the default failure exit code used by
  * `defaultTeardown`.
  *
- * @category Exit code management
+ * **Gotchas**
+ *
+ * Non-object values, missing markers, and non-number marker values all return
+ * `1`.
+ *
+ * @see {@link errorExitCode} for the marker read by this function
+ *
+ * @category accessors
  * @since 4.0.0
  */
 export declare const getErrorExitCode: (u: unknown) => number;
 /**
- * Type-level key for the `Runtime.errorReported` property that controls default
- * `runMain` error logging for an `Error`.
+ * Type-level key for the `Runtime.errorReported` marker.
+ *
+ * **When to use**
+ *
+ * Use to type properties keyed by `Runtime.errorReported` on custom error
+ * values.
  *
- * @category Error reporting management
+ * @category symbols
  * @since 4.0.0
  */
 export type errorReported = "~effect/Runtime/errorReported";
 /**
  * Runtime marker that controls default `runMain` error logging for an error.
  *
+ * **When to use**
+ *
+ * Use when error classes are already reported by application code and should
+ * not be logged again by the default main runner.
+ *
  * **Details**
  *
  * Set `[Runtime.errorReported]` to `false` on an error object to suppress the
  * runtime log because the error has already been reported. Omitted or
  * non-boolean values are treated as `true`, so failures are logged by default.
  *
+ * **Gotchas**
+ *
+ * This marker controls only automatic error logging. It does not change the
+ * failure Cause or the process exit code.
+ * `makeRunMain` reads the marker from `Cause.squash(cause)`, so for causes
+ * with multiple failures, the squashed error determines whether default logging
+ * is suppressed.
+ *
  * **Example** (Suppressing error reporting)
  *
  * ```ts
@@ -224,19 +319,34 @@ export type errorReported = "~effect/Runtime/errorReported";
  * NodeRuntime.runMain(Effect.fail(new MyError()))
  * ```
  *
- * @category Error reporting management
+ * @see {@link errorExitCode} for controlling failure exit codes
+ * @see {@link getErrorReported} for reading the marker from unknown error values
+ *
+ * @category symbols
  * @since 4.0.0
  */
 export declare const errorReported: errorReported;
 /**
  * Reads the runtime error-reporting marker from an unknown error value.
  *
+ * **When to use**
+ *
+ * Use to read whether an unknown error value should be treated as already
+ * reported by the default main runner.
+ *
  * **Details**
  *
  * Returns a boolean `[Runtime.errorReported]` property when it is present on an
  * object. Otherwise returns `true`, so failures are logged by default.
  *
- * @category Error reporting management
+ * **Gotchas**
+ *
+ * Non-object values, missing markers, and non-boolean marker values all return
+ * `true`.
+ *
+ * @see {@link errorReported} for the marker read by this function
+ *
+ * @category accessors
  * @since 4.0.0
  */
 export declare const getErrorReported: (u: unknown) => boolean;

package/dist/Runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Runtime.d.ts","sourceRoot":"","sources":["../src/Runtime.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AAEnC,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,QAAQ;IACvB,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAA;CACpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,eAAe,EAAE,QAO7B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,WAAW,GACtB,GAAG,CAAC,CAAC,EAAE,CAAC,EACN,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAC5B,KACE,IAAI,KACR;IACD,CACE,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;QACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;KACzC,GACA,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,CAAA;IAC9C,CAAC,CAAC,EAAE,CAAC,EACH,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAC3B,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;QACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;KACzC,GACA,IAAI,CAAA;CAuBL,CAAA;AAEJ,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,KAAK;QACb,QAAQ,CAAC,CAAC,aAAa,CAAC,CAAC,EAAE,MAAM,CAAA;QACjC,QAAQ,CAAC,CAAC,aAAa,CAAC,CAAC,EAAE,OAAO,CAAA;KACnC;CACF;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,+BAA+B,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,aAAa,EAAE,aAA+C,CAAA;AAE3E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,GAAI,GAAG,OAAO,KAAG,MAQ7C,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,+BAA+B,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,aAAa,EAAE,aAA+C,CAAA;AAE3E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,GAAG,OAAO,KAAG,OAQ7C,CAAA"}
+{"version":3,"file":"Runtime.d.ts","sourceRoot":"","sources":["../src/Runtime.ts"],"names":[],"mappings":"AA4DA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AAEnC,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,MAAM,WAAW,QAAQ;IACvB,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAA;CACpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,eAAe,EAAE,QAO7B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,eAAO,MAAM,WAAW,GACtB,GAAG,CAAC,CAAC,EAAE,CAAC,EACN,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAC5B,KACE,IAAI,KACR;IACD,CACE,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;QACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;KACzC,GACA,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,CAAA;IAC9C,CAAC,CAAC,EAAE,CAAC,EACH,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAC3B,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;QACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;KACzC,GACA,IAAI,CAAA;CAuBL,CAAA;AAEJ,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,KAAK;QACb,QAAQ,CAAC,CAAC,aAAa,CAAC,CAAC,EAAE,MAAM,CAAA;QACjC,QAAQ,CAAC,CAAC,aAAa,CAAC,CAAC,EAAE,OAAO,CAAA;KACnC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GAAG,+BAA+B,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,aAAa,EAAE,aAA+C,CAAA;AAE3E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,gBAAgB,GAAI,GAAG,OAAO,KAAG,MAQ7C,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GAAG,+BAA+B,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,aAAa,EAAE,aAA+C,CAAA;AAE3E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,gBAAgB,GAAI,GAAG,OAAO,KAAG,OAQ7C,CAAA"}

package/dist/Runtime.js

@@ -1,28 +1,58 @@
 /**
- * This module provides utilities for running Effect programs and managing their execution lifecycle.
- *
- * The Runtime module contains functions for creating main program runners that handle process
- * teardown, error reporting, and exit code management. These utilities are particularly useful
- * for creating CLI applications and server processes that need to manage their lifecycle properly.
- *
- * **Example** (Creating a main runner)
+ * Runtime helpers for turning an `Effect` program into a host application's
+ * main entry point.
+ *
+ * This module is the low-level layer used by platform adapters to run a main
+ * effect, observe its fiber, report unhandled failures, and translate the
+ * resulting `Exit` into an application or process exit code. Application code
+ * usually calls the platform-provided runner; runtime integrations use
+ * {@link makeRunMain} directly.
+ *
+ * **Mental model**
+ *
+ * - {@link makeRunMain} forks the supplied `Effect` and gives the host adapter
+ *   the running fiber plus a teardown callback
+ * - The host adapter installs platform-specific hooks such as signal handlers,
+ *   fiber observers, process exits, worker termination, or test harness
+ *   callbacks
+ * - {@link defaultTeardown} maps successful exits to `0`, interruption-only
+ *   failures to `130`, failures with {@link errorExitCode} to that code, and
+ *   other failures to `1`
+ * - {@link errorReported} controls automatic failure logging; set it to
+ *   `false` on errors that have already been reported
+ *
+ * **Common tasks**
+ *
+ * - Build a platform runner: {@link makeRunMain}
+ * - Reuse the standard exit-code rules: {@link defaultTeardown}
+ * - Customize failure exit codes: {@link errorExitCode},
+ *   {@link getErrorExitCode}
+ * - Control automatic failure logging: {@link errorReported},
+ *   {@link getErrorReported}
+ *
+ * **Gotchas**
+ *
+ * - `makeRunMain` starts the main fiber, but the adapter callback is
+ *   responsible for observing that fiber and eventually invoking teardown.
+ * - `disableErrorReporting` only disables automatic failure logging. It does
+ *   not change the `Exit`, interruption behavior, or teardown exit-code rules.
+ * - Error markers are read from `Cause.squash(cause)`, so causes with multiple
+ *   failures use the squashed failure value to determine logging and exit code.
+ *
+ * **Example** (Creating a minimal runner)
  *
  * ```ts
- * import { Effect, Fiber, Runtime } from "effect"
+ * import { Effect, Runtime } from "effect"
  *
- * // Create a main runner for Node.js
- * const runMain = Runtime.makeRunMain((options) => {
- *   process.on("SIGINT", () => Effect.runFork(Fiber.interrupt(options.fiber)))
- *   process.on("SIGTERM", () => Effect.runFork(Fiber.interrupt(options.fiber)))
- *
- *   options.fiber.addObserver((exit) => {
- *     options.teardown(exit, (code) => process.exit(code))
+ * const runMain = Runtime.makeRunMain(({ fiber, teardown }) => {
+ *   fiber.addObserver((exit) => {
+ *     teardown(exit, (code) => {
+ *       console.log(`finished with exit code ${code}`)
+ *     })
  *   })
  * })
  *
- * // Use the runner
- * const program = Effect.log("Hello, World!")
- * runMain(program)
+ * runMain(Effect.log("booted"))
  * ```
  *
  * @since 4.0.0
@@ -34,9 +64,25 @@ import { constVoid, dual } from "effect/Function";
 /**
  * The default teardown function that determines exit codes from an Effect exit.
  *
+ * **When to use**
+ *
+ * Use as the standard teardown for main programs when you want conventional
+ * process exit codes and support for {@link errorExitCode}.
+ *
  * **Details**
  *
- * This teardown function follows standard Unix conventions: exit code `0` for successful completion, exit code `1` for failures unless the squashed error has a `Runtime.errorExitCode` marker, and exit code `130` for interruption-only failures.
+ * This teardown follows these exit-code rules:
+ *
+ * - `0` for successful completion.
+ * - `130` for interruption-only failures.
+ * - The squashed error's {@link errorExitCode} value for other failures when
+ *   present.
+ * - `1` for other failures.
+ *
+ * **Gotchas**
+ *
+ * The `130` code is used only when the Cause contains interruptions and no
+ * other failure reasons. Mixed causes use the squashed error path instead.
  *
  * **Example** (Using default teardown)
  *
@@ -59,7 +105,9 @@ import { constVoid, dual } from "effect/Function";
  * // Output: Exit code: 130
  * ```
  *
- * @category Teardown
+ * @see {@link errorExitCode} for customizing failure exit codes
+ *
+ * @category running
  * @since 4.0.0
  */
 export const defaultTeardown = (exit, onExit) => {
@@ -70,10 +118,27 @@ export const defaultTeardown = (exit, onExit) => {
 /**
  * Creates a platform-specific main program runner that handles Effect execution lifecycle.
  *
+ * **When to use**
+ *
+ * Use when building a runtime adapter for a host platform. Most applications
+ * should use a platform-provided runner, such as `NodeRuntime.runMain`, rather
+ * than constructing one directly.
+ *
  * **Details**
  *
  * The runner executes Effect programs as main entry points. The provided function receives a forked fiber and a teardown callback so it can install platform-specific signal handling, fiber observers, and final exit behavior.
  *
+ * `disableErrorReporting` disables the automatic log emitted for unreported
+ * non-interruption failures. It does not change exit-code calculation or the
+ * custom teardown callback.
+ *
+ * **Gotchas**
+ *
+ * The setup function is responsible for observing the fiber and eventually
+ * invoking teardown. `makeRunMain` also tries to keep the host process alive
+ * with a long interval while the main fiber is running; if the host blocks
+ * timers, the runner still starts but cannot use that keep-alive fallback.
+ *
  * **Example** (Creating platform runners)
  *
  * ```ts
@@ -144,6 +209,22 @@ export const makeRunMain = f => dual(args => Effect.isEffect(args[0]), (effect,
  * Allows associating an exit code with an error for determining the process
  * exit code on failure.
  *
+ * **When to use**
+ *
+ * Use when error classes should map failures to a specific process exit code
+ * when handled by {@link defaultTeardown}.
+ *
+ * **Details**
+ *
+ * Attach this marker as a readonly property on an error object. When the main
+ * program fails, {@link defaultTeardown} squashes the Cause and reads the marker
+ * from the resulting error value.
+ *
+ * **Gotchas**
+ *
+ * The marker is read from the squashed failure value. If a Cause contains
+ * multiple failures, the selected squashed error determines the exit code.
+ *
  * **Example** (Setting a process exit code)
  *
  * ```ts
@@ -158,20 +239,36 @@ export const makeRunMain = f => dual(args => Effect.isEffect(args[0]), (effect,
  * NodeRuntime.runMain(Effect.fail(new MyError()))
  * ```
  *
- * @category Exit code management
+ * @see {@link errorReported} for controlling automatic error logging
+ * @see {@link defaultTeardown} for the default failure exit-code rules that read this marker
+ * @see {@link getErrorExitCode} for reading the marker from unknown error values
+ *
+ * @category symbols
  * @since 4.0.0
  */
 export const errorExitCode = "~effect/Runtime/errorExitCode";
 /**
  * Reads the runtime exit-code marker from an unknown error value.
  *
+ * **When to use**
+ *
+ * Use to read a custom failure exit code from an unknown error value, falling
+ * back to the default failure code.
+ *
  * **Details**
  *
  * Returns the numeric `[Runtime.errorExitCode]` property when it is present on
  * an object. Otherwise returns `1`, the default failure exit code used by
  * `defaultTeardown`.
  *
- * @category Exit code management
+ * **Gotchas**
+ *
+ * Non-object values, missing markers, and non-number marker values all return
+ * `1`.
+ *
+ * @see {@link errorExitCode} for the marker read by this function
+ *
+ * @category accessors
  * @since 4.0.0
  */
 export const getErrorExitCode = u => {
@@ -186,12 +283,25 @@ export const getErrorExitCode = u => {
 /**
  * Runtime marker that controls default `runMain` error logging for an error.
  *
+ * **When to use**
+ *
+ * Use when error classes are already reported by application code and should
+ * not be logged again by the default main runner.
+ *
  * **Details**
  *
  * Set `[Runtime.errorReported]` to `false` on an error object to suppress the
  * runtime log because the error has already been reported. Omitted or
  * non-boolean values are treated as `true`, so failures are logged by default.
  *
+ * **Gotchas**
+ *
+ * This marker controls only automatic error logging. It does not change the
+ * failure Cause or the process exit code.
+ * `makeRunMain` reads the marker from `Cause.squash(cause)`, so for causes
+ * with multiple failures, the squashed error determines whether default logging
+ * is suppressed.
+ *
  * **Example** (Suppressing error reporting)
  *
  * ```ts
@@ -207,19 +317,34 @@ export const getErrorExitCode = u => {
  * NodeRuntime.runMain(Effect.fail(new MyError()))
  * ```
  *
- * @category Error reporting management
+ * @see {@link errorExitCode} for controlling failure exit codes
+ * @see {@link getErrorReported} for reading the marker from unknown error values
+ *
+ * @category symbols
  * @since 4.0.0
  */
 export const errorReported = "~effect/Runtime/errorReported";
 /**
  * Reads the runtime error-reporting marker from an unknown error value.
  *
+ * **When to use**
+ *
+ * Use to read whether an unknown error value should be treated as already
+ * reported by the default main runner.
+ *
  * **Details**
  *
  * Returns a boolean `[Runtime.errorReported]` property when it is present on an
  * object. Otherwise returns `true`, so failures are logged by default.
  *
- * @category Error reporting management
+ * **Gotchas**
+ *
+ * Non-object values, missing markers, and non-boolean marker values all return
+ * `true`.
+ *
+ * @see {@link errorReported} for the marker read by this function
+ *
+ * @category accessors
  * @since 4.0.0
  */
 export const getErrorReported = u => {

package/dist/Runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"Runtime.js","names":["Cause","Effect","Exit","constVoid","dual","defaultTeardown","exit","onExit","isSuccess","hasInterruptsOnly","cause","getErrorExitCode","squash","makeRunMain","f","args","isEffect","effect","options","fiber","disableErrorReporting","runFork","tapCause","void","isReported","getErrorReported","logError","keepAlive","globalThis","setInterval","addObserver","clearInterval","teardown","errorExitCode","u","code","errorReported"],"sources":["../src/Runtime.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,KAAKA,KAAK,MAAM,cAAc;AACrC,OAAO,KAAKC,MAAM,MAAM,eAAe;AACvC,OAAO,KAAKC,IAAI,MAAM,aAAa;AACnC,SAASC,SAAS,EAAEC,IAAI,QAAQ,iBAAiB;AA8CjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,OAAO,MAAMC,eAAe,GAAaA,CACvCC,IAAqB,EACrBC,MAA8B,KAC5B;EACF,IAAIL,IAAI,CAACM,SAAS,CAACF,IAAI,CAAC,EAAE,OAAOC,MAAM,CAAC,CAAC,CAAC;EAC1C,IAAIP,KAAK,CAACS,iBAAiB,CAACH,IAAI,CAACI,KAAK,CAAC,EAAE,OAAOH,MAAM,CAAC,GAAG,CAAC;EAC3D,OAAOA,MAAM,CAACI,gBAAgB,CAACX,KAAK,CAACY,MAAM,CAACN,IAAI,CAACI,KAAK,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,OAAO,MAAMG,WAAW,GACtBC,CAKS,IAgBTV,IAAI,CAAEW,IAAI,IAAKd,MAAM,CAACe,QAAQ,CAACD,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAACE,MAA+B,EAAEC,OAG1E,KAAI;EACH,MAAMC,KAAK,GAAGD,OAAO,EAAEE,qBAAqB,KAAK,IAAI,GACjDnB,MAAM,CAACoB,OAAO,CAACJ,MAAM,CAAC,GACtBhB,MAAM,CAACoB,OAAO,CACdpB,MAAM,CAACqB,QAAQ,CAACL,MAAM,EAAGP,KAAK,IAAI;IAChC,IAAIV,KAAK,CAACS,iBAAiB,CAACC,KAAK,CAAC,EAAE,OAAOT,MAAM,CAACsB,IAAI;IACtD,MAAMC,UAAU,GAAGC,gBAAgB,CAACzB,KAAK,CAACY,MAAM,CAACF,KAAK,CAAC,CAAC;IACxD,OAAOc,UAAU,GAAGvB,MAAM,CAACyB,QAAQ,CAAChB,KAAK,CAAC,GAAGT,MAAM,CAACsB,IAAI;EAC1D,CAAC,CAAC,CACH;EACH,IAAI;IACF,MAAMI,SAAS,GAAGC,UAAU,CAACC,WAAW,CAAC1B,SAAS,EAAE,aAAa,CAAC;IAClEgB,KAAK,CAACW,WAAW,CAAC,MAAK;MACrBC,aAAa,CAACJ,SAAS,CAAC;IAC1B,CAAC,CAAC;EACJ,CAAC,CAAC,MAAM,CAAC;EACT,MAAMK,QAAQ,GAAGd,OAAO,EAAEc,QAAQ,IAAI3B,eAAe;EACrD,OAAOS,CAAC,CAAC;IAAEK,KAAK;IAAEa;EAAQ,CAAE,CAAC;AAC/B,CAAC,CAAC;AAkBJ;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,MAAMC,aAAa,GAAkB,+BAA+B;AAE3E;;;;;;;;;;;;AAYA,OAAO,MAAMtB,gBAAgB,GAAIuB,CAAU,IAAY;EACrD,IAAI,OAAOA,CAAC,KAAK,QAAQ,IAAIA,CAAC,KAAK,IAAI,IAAID,aAAa,IAAIC,CAAC,EAAE;IAC7D,MAAMC,IAAI,GAAGD,CAAC,CAACD,aAAa,CAAC;IAC7B,IAAI,OAAOE,IAAI,KAAK,QAAQ,EAAE;MAC5B,OAAOA,IAAI;IACb;EACF;EACA,OAAO,CAAC;AACV,CAAC;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,MAAMC,aAAa,GAAkB,+BAA+B;AAE3E;;;;;;;;;;;AAWA,OAAO,MAAMX,gBAAgB,GAAIS,CAAU,IAAa;EACtD,IAAI,OAAOA,CAAC,KAAK,QAAQ,IAAIA,CAAC,KAAK,IAAI,IAAIE,aAAa,IAAIF,CAAC,EAAE;IAC7D,MAAMV,UAAU,GAAGU,CAAC,CAACE,aAAa,CAAC;IACnC,IAAI,OAAOZ,UAAU,KAAK,SAAS,EAAE;MACnC,OAAOA,UAAU;IACnB;EACF;EACA,OAAO,IAAI;AACb,CAAC","ignoreList":[]}
+{"version":3,"file":"Runtime.js","names":["Cause","Effect","Exit","constVoid","dual","defaultTeardown","exit","onExit","isSuccess","hasInterruptsOnly","cause","getErrorExitCode","squash","makeRunMain","f","args","isEffect","effect","options","fiber","disableErrorReporting","runFork","tapCause","void","isReported","getErrorReported","logError","keepAlive","globalThis","setInterval","addObserver","clearInterval","teardown","errorExitCode","u","code","errorReported"],"sources":["../src/Runtime.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,OAAO,KAAKA,KAAK,MAAM,cAAc;AACrC,OAAO,KAAKC,MAAM,MAAM,eAAe;AACvC,OAAO,KAAKC,IAAI,MAAM,aAAa;AACnC,SAASC,SAAS,EAAEC,IAAI,QAAQ,iBAAiB;AAqDjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA,OAAO,MAAMC,eAAe,GAAaA,CACvCC,IAAqB,EACrBC,MAA8B,KAC5B;EACF,IAAIL,IAAI,CAACM,SAAS,CAACF,IAAI,CAAC,EAAE,OAAOC,MAAM,CAAC,CAAC,CAAC;EAC1C,IAAIP,KAAK,CAACS,iBAAiB,CAACH,IAAI,CAACI,KAAK,CAAC,EAAE,OAAOH,MAAM,CAAC,GAAG,CAAC;EAC3D,OAAOA,MAAM,CAACI,gBAAgB,CAACX,KAAK,CAACY,MAAM,CAACN,IAAI,CAACI,KAAK,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,OAAO,MAAMG,WAAW,GACtBC,CAKS,IAgBTV,IAAI,CAAEW,IAAI,IAAKd,MAAM,CAACe,QAAQ,CAACD,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAACE,MAA+B,EAAEC,OAG1E,KAAI;EACH,MAAMC,KAAK,GAAGD,OAAO,EAAEE,qBAAqB,KAAK,IAAI,GACjDnB,MAAM,CAACoB,OAAO,CAACJ,MAAM,CAAC,GACtBhB,MAAM,CAACoB,OAAO,CACdpB,MAAM,CAACqB,QAAQ,CAACL,MAAM,EAAGP,KAAK,IAAI;IAChC,IAAIV,KAAK,CAACS,iBAAiB,CAACC,KAAK,CAAC,EAAE,OAAOT,MAAM,CAACsB,IAAI;IACtD,MAAMC,UAAU,GAAGC,gBAAgB,CAACzB,KAAK,CAACY,MAAM,CAACF,KAAK,CAAC,CAAC;IACxD,OAAOc,UAAU,GAAGvB,MAAM,CAACyB,QAAQ,CAAChB,KAAK,CAAC,GAAGT,MAAM,CAACsB,IAAI;EAC1D,CAAC,CAAC,CACH;EACH,IAAI;IACF,MAAMI,SAAS,GAAGC,UAAU,CAACC,WAAW,CAAC1B,SAAS,EAAE,aAAa,CAAC;IAClEgB,KAAK,CAACW,WAAW,CAAC,MAAK;MACrBC,aAAa,CAACJ,SAAS,CAAC;IAC1B,CAAC,CAAC;EACJ,CAAC,CAAC,MAAM,CAAC;EACT,MAAMK,QAAQ,GAAGd,OAAO,EAAEc,QAAQ,IAAI3B,eAAe;EACrD,OAAOS,CAAC,CAAC;IAAEK,KAAK;IAAEa;EAAQ,CAAE,CAAC;AAC/B,CAAC,CAAC;AAsBJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,OAAO,MAAMC,aAAa,GAAkB,+BAA+B;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,MAAMtB,gBAAgB,GAAIuB,CAAU,IAAY;EACrD,IAAI,OAAOA,CAAC,KAAK,QAAQ,IAAIA,CAAC,KAAK,IAAI,IAAID,aAAa,IAAIC,CAAC,EAAE;IAC7D,MAAMC,IAAI,GAAGD,CAAC,CAACD,aAAa,CAAC;IAC7B,IAAI,OAAOE,IAAI,KAAK,QAAQ,EAAE;MAC5B,OAAOA,IAAI;IACb;EACF;EACA,OAAO,CAAC;AACV,CAAC;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,OAAO,MAAMC,aAAa,GAAkB,+BAA+B;AAE3E;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAMX,gBAAgB,GAAIS,CAAU,IAAa;EACtD,IAAI,OAAOA,CAAC,KAAK,QAAQ,IAAIA,CAAC,KAAK,IAAI,IAAIE,aAAa,IAAIF,CAAC,EAAE;IAC7D,MAAMV,UAAU,GAAGU,CAAC,CAACE,aAAa,CAAC;IACnC,IAAI,OAAOZ,UAAU,KAAK,SAAS,EAAE;MACnC,OAAOA,UAAU;IACnB;EACF;EACA,OAAO,IAAI;AACb,CAAC","ignoreList":[]}