effect 4.0.0-beta.78 → 4.0.0-beta.79

package/src/Equal.ts

@@ -1,71 +1,11 @@
 /**
- * Structural and custom equality for Effect values.
- *
- * The `Equal` module provides deep structural comparison for primitives, plain
- * objects, arrays, Maps, Sets, Dates, and RegExps. Types that implement the
- * {@link Equal} interface can supply their own comparison logic while staying
- * compatible with the rest of the ecosystem (HashMap, HashSet, etc.).
- *
- * ## Mental model
- *
- * - **Structural equality** — two values are equal when their contents match,
- *   not when they share the same reference.
- * - **Hash-first shortcut** — before comparing fields, the module checks
- *   {@link Hash.hash}. If the hashes differ the objects are unequal without
- *   further traversal.
- * - **Equal interface** — any object that implements both {@link symbol} (the
- *   equality method) and `Hash.symbol` (the hash method) can define custom
- *   comparison logic.
- * - **Caching** — comparison results for object pairs are cached in a WeakMap.
- *   This makes repeated checks fast but **requires immutability** after the
- *   first comparison.
- * - **By-reference opt-out** — {@link byReference} and {@link byReferenceUnsafe}
- *   let you switch individual objects back to reference equality when you need
- *   mutable identity semantics.
- *
- * ## Common tasks
- *
- * - Compare two values → {@link equals}
- * - Check if a value implements `Equal` → {@link isEqual}
- * - Use `equals` where an `Equivalence` is expected → {@link asEquivalence}
- * - Implement custom equality on a class → implement {@link Equal} (see
- *   example on the interface)
- * - Opt an object out of structural equality → {@link byReference} /
- *   {@link byReferenceUnsafe}
- *
- * ## Gotchas
- *
- * - Objects **must be treated as immutable** after their first equality check.
- *   Results are cached; mutating an object afterwards yields stale results.
- * - `NaN` is considered equal to `NaN` (unlike `===`).
- * - Functions without an `Equal` implementation are compared by reference.
- * - Map and Set comparisons are order-independent but O(n²) in size.
- * - If only one of two objects implements `Equal`, they are never equal.
- *
- * ## Quickstart
- *
- * **Example** (basic structural comparison)
+ * Compares values with Effect's structural equality rules.
  *
- * ```ts
- * import { Equal } from "effect"
- *
- * // Primitives
- * console.log(Equal.equals(1, 1))       // true
- * console.log(Equal.equals("a", "b"))   // false
- *
- * // Objects and arrays
- * console.log(Equal.equals({ x: 1 }, { x: 1 })) // true
- * console.log(Equal.equals([1, 2], [1, 2]))       // true
- *
- * // Curried form
- * const is42 = Equal.equals(42)
- * console.log(is42(42)) // true
- * console.log(is42(0))  // false
- * ```
- *
- * @see {@link equals} — the main comparison function
- * @see {@link Equal} — the interface for custom equality
- * @see {@link Hash} — the companion hashing module
+ * `equals` compares primitives, arrays, plain objects, maps, sets, dates,
+ * regular expressions, and values that implement the `Equal` interface. This
+ * module also defines the equality symbol, guards, adapters, map and set
+ * comparison builders, and helpers for marking objects that should compare only
+ * by reference.
  *
  * @since 2.0.0
  */

package/src/Equivalence.ts

@@ -1,53 +1,11 @@
 /**
- * Utilities for defining equivalence relations - binary relations that determine when two values
- * should be considered equivalent. Equivalence relations are used for comparing, deduplicating,
- * and organizing data in collections and data structures.
+ * Defines reusable equality functions for values of the same type.
  *
- * ## Mental model
- *
- * - **Equivalence relation**: A function `(a: A, b: A) => boolean` that returns `true` when values are equivalent
- * - **Reflexive property**: Every value is equivalent to itself (`eq(a, a) === true`)
- * - **Symmetric property**: If `a` is equivalent to `b`, then `b` is equivalent to `a` (`eq(a, b) === eq(b, a)`)
- * - **Transitive property**: If `a` is equivalent to `b` and `b` is equivalent to `c`, then `a` is equivalent to `c`
- * - **Reference equality optimization**: {@link make} checks `===` first for performance before calling the custom function
- * - **Composition**: Equivalences can be combined using {@link combine} and {@link combineAll} to create more complex relations
- *
- * ## Common tasks
- *
- * - Creating custom equivalences → {@link make}
- * - Using strict equality (`===`) → {@link strictEqual}
- * - Combining multiple equivalences (AND logic) → {@link combine}, {@link combineAll}
- * - Transforming input before comparison → {@link mapInput}
- * - Creating equivalences for structured types → {@link Struct}, {@link Tuple}, {@link Array_}, {@link Record}
- *
- * ## Gotchas
- *
- * - `strictEqual` uses `===`, so `NaN !== NaN` and objects are compared by reference, not structure
- * - `make` optimizes with a reference equality check, so identical references return `true` without calling the function
- * - `combineAll` with an empty collection returns an equivalence that always returns `true`
- * - `Tuple` and `Array` require matching lengths; different lengths are never equivalent
- *
- * ## Quickstart
- *
- * **Example** (Case-insensitive string equivalence)
- *
- * ```ts
- * import { Array, Equivalence } from "effect"
- *
- * const caseInsensitive = Equivalence.make<string>((a, b) =>
- *   a.toLowerCase() === b.toLowerCase()
- * )
- *
- * const strings = ["Hello", "world", "HELLO", "World"]
- * const deduplicated = Array.dedupeWith(strings, caseInsensitive)
- * console.log(deduplicated) // ["Hello", "world"]
- * ```
- *
- * ## See also
- *
- * - `Equal` - For structural equality (can convert to Equivalence)
- * - `Array.dedupeWith` - Remove duplicates using an equivalence
- * - `Chunk` - Collections that use equivalences for operations
+ * An `Equivalence<A>` returns `true` when two `A` values should be treated as
+ * the same for a particular purpose. This module includes strict equality
+ * instances for primitive types, constructors for custom comparisons, and
+ * helpers for tuples, arrays, structs, records, dates, and values compared
+ * through a derived field.
  *
  * @since 2.0.0
  */

package/src/ErrorReporter.ts

@@ -1,51 +1,12 @@
 /**
- * Pluggable error reporting for Effect programs.
- *
- * Reporting is triggered by `Effect.withErrorReporting`,
- * `ErrorReporter.report`, or built-in reporting boundaries in the HTTP and
- * RPC server modules.
- *
- * Each reporter receives a structured callback with the failing `Cause`, a
- * pretty-printed `Error`, severity, and any extra attributes attached to the
- * original error — making it straightforward to forward failures to Sentry,
- * Datadog, or a custom logging backend.
- *
- * Use the annotation symbols (`ignore`, `severity`, `attributes`) on your
- * error classes to control reporting behavior per-error.
- *
- * **Example** (Reporting errors with annotations)
- *
- * ```ts
- * import { Data, Effect, ErrorReporter } from "effect"
- *
- * // A reporter that logs to the console
- * const consoleReporter = ErrorReporter.make(({ error, severity }) => {
- *   console.error(`[${severity}]`, error.message)
- * })
- *
- * // An error that should be ignored by reporters
- * class NotFoundError extends Data.TaggedError("NotFoundError")<{}> {
- *   readonly [ErrorReporter.ignore] = true
- * }
- *
- * // An error with custom severity and attributes
- * class RateLimitError extends Data.TaggedError("RateLimitError")<{
- *   readonly retryAfter: number
- * }> {
- *   readonly [ErrorReporter.severity] = "Warn" as const
- *   readonly [ErrorReporter.attributes] = {
- *     retryAfter: this.retryAfter
- *   }
- * }
- *
- * // Opt in to error reporting with Effect.withErrorReporting
- * const program = Effect.gen(function*() {
- *   return yield* new RateLimitError({ retryAfter: 60 })
- * }).pipe(
- *   Effect.withErrorReporting,
- *   Effect.provide(ErrorReporter.layer([consoleReporter]))
- * )
- * ```
+ * Reports Effect failures to external code.
+ *
+ * An `ErrorReporter` receives `Cause` values from `Effect.withErrorReporting`,
+ * manual `report` calls, or built-in reporting boundaries. It forwards each
+ * non-interruption error to a callback, so applications can send failures to
+ * logging, monitoring, or error-tracking systems. This module also includes
+ * layers for installing reporters and symbols for marking errors as ignored or
+ * attaching severity and attributes.
  *
  * @since 4.0.0
  */

package/src/ExecutionPlan.ts

@@ -1,84 +1,11 @@
 /**
- * Defines finite fallback plans for effects and streams that should retry the
- * same work with different services. An `ExecutionPlan` is a non-empty
- * sequence of steps. Each step provides a `Context` or `Layer`, and can limit
- * or shape retries with `attempts`, `schedule`, and `while`.
+ * Describes ordered fallback steps for running effects or streams.
  *
- * Use a plan with `Effect.withExecutionPlan` or `Stream.withExecutionPlan`.
- * Those APIs run the wrapped work with the first step, retry within that step
- * as directed, then move to later steps until the work succeeds or the plan is
- * exhausted.
- *
- * **Mental model**
- *
- * - A step is a resource profile for one part of a fallback strategy
- * - The active step supplies the services visible to the wrapped effect or
- *   stream
- * - `attempts` caps the number of tries for a step
- * - `schedule` controls retry timing and receives the wrapped work's failure
- *   value
- * - `while` can stop the current step early by inspecting the same failure
- *   value
- * - `CurrentMetadata` exposes the 1-based attempt number and 0-based step
- *   index to code running under the active step
- *
- * **Common tasks**
- *
- * - Build a plan with {@link make}
- * - Append fallback plans with {@link merge}
- * - Apply a plan with `Effect.withExecutionPlan` or `Stream.withExecutionPlan`
- * - Read active step and attempt information with {@link CurrentMetadata}
- * - Carry the current environment into a plan with `captureRequirements`
- *
- * **Quickstart**
- *
- * **Example** (Retry with one layer, then fall back)
- *
- * ```ts
- * import { Context, Effect, ExecutionPlan, Layer, Schedule } from "effect"
- *
- * class Endpoint extends Context.Service<Endpoint>()("Endpoint", {
- *   make: Effect.succeed({ url: "primary" })
- * }) {}
- *
- * const primary = Layer.succeed(Endpoint, Endpoint.of({ url: "primary" }))
- * const fallback = Layer.succeed(Endpoint, Endpoint.of({ url: "fallback" }))
- *
- * const plan = ExecutionPlan.make(
- *   {
- *     provide: primary,
- *     attempts: 2,
- *     schedule: Schedule.recurs(1)
- *   },
- *   {
- *     provide: fallback
- *   }
- * )
- *
- * const program = Effect.gen(function*() {
- *   const endpoint = yield* Endpoint
- *   if (endpoint.url === "primary") {
- *     return yield* Effect.fail("unavailable")
- *   }
- *   return endpoint.url
- * }).pipe(Effect.withExecutionPlan(plan))
- * ```
- *
- * **Gotchas**
- *
- * - Plans must contain at least one step
- * - `attempts` must be greater than zero when provided
- * - Without `attempts` or `schedule`, a step is tried once
- * - A `schedule` can keep a step active until bounded by `attempts` or
- *   stopped by `while`
- * - Layer, schedule, and predicate requirements stay in the plan type until
- *   they are provided or captured
- *
- * **See also**
- *
- * - {@link make} for constructing plans
- * - {@link merge} for combining plans in order
- * - {@link CurrentMetadata} for inspecting the active attempt
+ * An `ExecutionPlan` contains one or more steps. Each step provides a `Context`
+ * or `Layer`, and may also define attempt limits, retry schedules, or
+ * predicates that decide whether to keep trying. The runtime tries steps in
+ * order until the workflow succeeds or the plan is exhausted. This module also
+ * supports merging plans and reading metadata for the active step and attempt.
  *
  * @since 3.16.0
  */

package/src/Exit.ts

@@ -1,58 +1,11 @@
 /**
- * Represents the outcome of an Effect computation as a plain, synchronously
- * inspectable value.
+ * Represents the result of an Effect computation as a plain value.
  *
- * ## Mental model
- *
- * - `Exit<A, E>` is a union of two cases: `Success<A, E>` and `Failure<A, E>`
- * - A `Success` wraps a value of type `A`
- * - A `Failure` wraps a `Cause<E>`, which may contain typed errors, defects, or interruptions
- * - `Exit` is also an `Effect`, so you can yield it directly inside `Effect.gen`
- * - Constructors mirror the failure modes: {@link fail} for typed errors, {@link die} for defects, {@link interrupt} for fiber interruptions
- * - Use `Exit` when you need to inspect an Effect result without running further effects
- *
- * ## Common tasks
- *
- * - Create a success: {@link succeed}
- * - Create a typed failure: {@link fail}
- * - Create a failure from a Cause: {@link failCause}
- * - Create a defect: {@link die}
- * - Create an interruption: {@link interrupt}
- * - Check the outcome: {@link isSuccess}, {@link isFailure}, {@link match}
- * - Extract values optionally: {@link getSuccess}, {@link getCause}, {@link findErrorOption}
- * - Transform the result: {@link map}, {@link mapError}, {@link mapBoth}
- * - Combine multiple exits: {@link asVoidAll}
- * - Inspect failure categories: {@link hasFails}, {@link hasDies}, {@link hasInterrupts}
- *
- * ## Gotchas
- *
- * - A `Failure` wraps a `Cause<E>`, not a bare `E`. Use Cause utilities to drill into it.
- * - {@link mapError} and {@link mapBoth} only transform typed errors (Fail reasons in the Cause). If the Cause contains only defects or interruptions, the original failure passes through unchanged.
- * - Filter-based APIs ({@link filterSuccess}, {@link filterValue}, etc.) return `Result.fail` values for pipeline composition. They are not `Option` values or Effect failures.
- * - {@link findError} and {@link findDefect} return only the first matching reason from the Cause.
- *
- * ## Quickstart
- *
- * **Example** (Creating and inspecting exits)
- *
- * ```ts
- * import { Exit } from "effect"
- *
- * const success = Exit.succeed(42)
- * const failure = Exit.fail("not found")
- *
- * const message = Exit.match(success, {
- *   onSuccess: (value) => `Got: ${value}`,
- *   onFailure: () => "Failed"
- * })
- * console.log(message) // "Got: 42"
- * ```
- *
- * ## See also
- *
- * - {@link Exit} the core union type
- * - {@link succeed} and {@link fail} the most common constructors
- * - {@link match} for pattern matching on an Exit
+ * An `Exit<A, E>` is either a success with an `A` or a failure with a
+ * `Cause<E>`. The failure cause preserves typed errors, defects, and
+ * interruptions after a workflow has finished. Use this module when completed
+ * Effect results need to be inspected, transformed, filtered, or matched
+ * synchronously as data.
  *
  * @since 2.0.0
  */

package/src/Fiber.ts

@@ -1,56 +1,9 @@
 /**
- * The `Fiber` module provides operations for handles returned by forking
- * effects. A `Fiber<A, E>` is a lightweight runtime execution of an `Effect`
- * that may still be running, may already have completed, and can be observed or
- * interrupted by other fibers.
- *
- * Applications create fibers with operations such as `Effect.forkChild`,
- * `Effect.forkScoped`, `Effect.forkIn`, or `Effect.forkDetach`, then use this
- * module to wait for results, inspect exits, or cancel work that is no longer
- * needed.
- *
- * **Mental model**
- *
- * - A fiber is a handle to a running or completed effect, not the effect itself
- * - {@link await_ await} observes completion as an `Exit` without failing the current
- *   effect
- * - {@link join} waits for success and propagates the fiber's failure into the
- *   current effect
- * - {@link interrupt} requests cancellation and waits until the target fiber
- *   finishes running finalizers
- * - Group operations such as {@link awaitAll}, {@link joinAll}, and
- *   {@link interruptAll} apply the same ideas to collections of fibers
- *
- * **Common tasks**
- *
- * - Wait for one fiber with {@link await_ await} or {@link join}
- * - Wait for many fibers with {@link awaitAll} or {@link joinAll}
- * - Stop work with {@link interrupt}, {@link interruptAs},
- *   {@link interruptAll}, or {@link interruptAllAs}
- * - Recognize fiber handles with {@link isFiber}
- * - Link a manually managed fiber to a `Scope` with {@link runIn}
- *
- * **Gotchas**
- *
- * - `await` gives you an `Exit`; use `join` when the current effect should fail
- *   if the fiber failed
- * - Interruption is cooperative, so a fiber can continue through
- *   uninterruptible regions and finalizers before it finishes
- * - `joinAll` stops waiting on the first failure, but it does not interrupt the
- *   remaining fibers for you
- *
- * **Example** (Joining a forked effect)
- *
- * ```ts
- * import { Effect, Fiber } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const fiber = yield* Effect.forkChild(Effect.succeed(42))
- *   const value = yield* Fiber.join(fiber)
- *
- *   return value
- * })
- * ```
+ * Operations for handles returned by forking effects. A `Fiber<A, E>` is a
+ * lightweight execution of an `Effect` that may still be running or may already
+ * have completed. This module lets callers await or join fiber results,
+ * interrupt one or many fibers, check unknown values, access the current fiber,
+ * and attach manually managed fibers to a `Scope` for cleanup.
  *
  * @since 2.0.0
  */

package/src/FiberHandle.ts

@@ -1,42 +1,12 @@
 /**
- * The `FiberHandle` module provides a scoped handle for managing the lifecycle
- * of at most one fiber at a time. A `FiberHandle<A, E>` can hold one
- * `Fiber<A, E>`; when a new fiber is installed, the previous fiber is
- * interrupted unless the operation is configured with `onlyIfMissing`.
- *
- * **Mental model**
- *
- * - A handle is either open with zero or one current fiber, or closed by its
- *   surrounding `Scope`
- * - Closing the scope interrupts the current fiber and prevents new work from
- *   being accepted
- * - Completed fibers remove themselves from the handle, so the handle can be
- *   reused for later work
- * - Replacing a fiber uses the handle's internal interruption id, allowing
- *   expected replacement interruptions to be distinguished from real failures
- *
- * **Common tasks**
- *
- * - Create a scoped handle: {@link make}
- * - Fork an effect into the handle: {@link run}
- * - Store an existing fiber: {@link set}
- * - Read or clear the current fiber: {@link get}, {@link clear}
- * - Capture runtime-specific runners: {@link makeRuntime}, {@link runtime}
- * - Run handled effects as Promises: {@link makeRuntimePromise},
- *   {@link runtimePromise}
- * - Wait for failure or closure: {@link join}
- * - Wait until the current fiber is gone: {@link awaitEmpty}
- *
- * **Gotchas**
- *
- * - The handle never contains more than one live fiber; starting or setting
- *   another fiber interrupts the previous one by default
- * - Use `onlyIfMissing` when a call should leave an already running fiber in
- *   place instead of replacing it
- * - `join` observes the handle's failure/close signal; successful fiber
- *   completion only empties the handle
- * - `awaitEmpty` waits for the fiber that is current when it starts; later
- *   calls to {@link run} or {@link set} can install new work
+ * Manages at most one fiber inside a scope.
+ *
+ * A `FiberHandle<A, E>` can hold one `Fiber<A, E>`. Installing a new fiber
+ * interrupts the previous one unless the operation is configured with
+ * `onlyIfMissing`, and closing the owning scope interrupts the current fiber.
+ * This module includes constructors for handles and scoped runtimes, helpers
+ * for setting, reading, clearing, and running fibers, and operations for joining
+ * the current fiber or waiting until the handle is empty.
  *
  * @since 2.0.0
  */

package/src/FiberMap.ts

@@ -1,38 +1,11 @@
 /**
- * The `FiberMap` module provides a scoped, mutable collection for managing
- * fibers by key. A `FiberMap<K, A, E>` owns a set of running fibers, interrupts
- * them when its scope closes, and automatically removes each entry when the
- * corresponding fiber completes.
- *
- * **Mental model**
- *
- * - A `FiberMap` is a keyed registry of fibers with lifecycle management
- * - Keys identify the currently active fiber for a logical task or resource
- * - Adding a fiber under an existing key interrupts the previous fiber by default
- * - Completed fibers remove themselves from the map if they are still current
- * - Closing the map's scope interrupts every fiber that remains in the map
- * - The map can surface the first non-ignored managed fiber failure via {@link join}
- *
- * **Common tasks**
- *
- * - Create a scoped map: {@link make}
- * - Fork effects into the map: {@link run}
- * - Add existing fibers: {@link set}
- * - Create captured runners: {@link makeRuntime}, {@link runtime}
- * - Bridge to Promise-based callers: {@link makeRuntimePromise}, {@link runtimePromise}
- * - Inspect entries: {@link get}, {@link has}, {@link size}
- * - Stop work: {@link remove}, {@link clear}
- * - Coordinate completion or failure: {@link awaitEmpty}, {@link join}
- *
- * **Gotchas**
- *
- * - `FiberMap` is scoped; use it with `Effect.scoped` or another scope owner so
- *   managed fibers are interrupted when the scope closes
- * - Reusing a key is a replacement operation unless `onlyIfMissing` is enabled
- * - `join` waits for the map to fail or close; use {@link awaitEmpty} to wait
- *   until all currently managed fibers have completed
- * - The `Unsafe` variants mutate synchronously and should only be used when the
- *   caller already controls the surrounding execution context
+ * Manages fibers by key inside a scope.
+ *
+ * A `FiberMap<K, A, E>` owns a map of running fibers, interrupts them when its
+ * scope closes, and automatically removes each entry when the corresponding
+ * fiber completes. Use it when a program needs to start, replace, join, or
+ * interrupt background work by a stable key while keeping all fibers tied to
+ * one scope.
  *
  * @since 2.0.0
  */

package/src/FiberSet.ts

@@ -1,40 +1,10 @@
 /**
- * The `FiberSet` module provides a scoped container for managing many fibers as
- * one lifecycle. A `FiberSet<A, E>` tracks fibers whose successful values are
- * compatible with `A` and whose failures are compatible with `E`, removes each
- * fiber when it completes, and interrupts all still-running fibers when the
- * owning `Scope` closes.
- *
- * **Mental model**
- *
- * - A `FiberSet` is an owned, scoped collection of fibers
- * - Fibers can be added directly with {@link add} / {@link addUnsafe}
- * - Effects can be forked into the set with {@link run}, {@link runtime}, or
- *   {@link runtimePromise}
- * - Completed fibers are automatically removed from the set
- * - Closing the scope or calling {@link clear} interrupts the currently tracked
- *   fibers
- * - {@link join} waits for the set's first non-ignored failure, while
- *   {@link awaitEmpty} waits until all tracked fibers have completed
- *
- * **Common tasks**
- *
- * - Create a scoped set: {@link make}
- * - Create scoped runners: {@link makeRuntime}, {@link makeRuntimePromise}
- * - Add an existing fiber: {@link add}
- * - Fork an effect into the set: {@link run}
- * - Interrupt tracked fibers: {@link clear}
- * - Observe the set: {@link size}, {@link awaitEmpty}, {@link join}
- * - Check a value: {@link isFiberSet}
- *
- * **Gotchas**
- *
- * - `FiberSet` values are scoped; use them inside `Effect.scoped` or another
- *   scope owner so their fibers are interrupted reliably
- * - Adding or running into a closed set interrupts the fiber immediately
- * - By default, interruptions are not treated as failures for {@link join};
- *   use the `propagateInterruption` option when interruption should be
- *   propagated
+ * Manages many fibers together inside one scope.
+ *
+ * A `FiberSet<A, E>` tracks running fibers, removes each fiber when it
+ * completes, and interrupts all still-running fibers when the owning scope
+ * closes. This module includes scoped runtime constructors plus helpers for
+ * adding, clearing, running, counting, joining, and waiting for managed fibers.
  *
  * @since 2.0.0
  */

package/src/FileSystem.ts

@@ -1,55 +1,12 @@
 /**
- * Effect service for reading, writing, inspecting, and watching files.
- *
- * The `FileSystem` service is the portable boundary between Effect programs and
- * the host file system. Programs depend on the service from `effect/FileSystem`;
- * platform packages provide concrete layers at the edge. Operations return
- * `Effect`, `Stream`, or `Sink` values and report failures as `PlatformError`
- * instead of throwing.
- *
- * **Mental model**
- *
- * `FileSystem` is a capability, not a global singleton. Request it with
- * `yield* FileSystem.FileSystem` inside an effect, compose file work like any
- * other effect, and provide a platform or test implementation when the program
- * is run. Scoped operations such as `open`, `makeTempFileScoped`, and
- * `makeTempDirectoryScoped` bind resource cleanup to `Scope`.
- *
- * **Common tasks**
- *
- * - Create, copy, rename, remove, chmod, chown, link, and symlink paths.
- * - Read and write whole files as bytes or strings.
- * - Stream large files with `stream` and `sink`, using binary size helpers such
- *   as `KiB` and `MiB` for chunk sizes and offsets.
- * - Inspect metadata with `stat`, check accessibility with `access` or
- *   `exists`, and canonicalize paths with `realPath`.
- * - Watch files or directories with `watch` when the platform implementation
- *   supports it.
- *
- * **Example** (Write and clean up a temporary file)
- *
- * ```ts
- * import { Effect, FileSystem } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const fs = yield* FileSystem.FileSystem
- *
- *   const directory = yield* fs.makeTempDirectoryScoped()
- *   const path = `${directory}/message.txt`
- *
- *   yield* fs.writeFileString(path, "hello")
- *   return yield* fs.readFileString(path)
- * })
- * ```
- *
- * **Gotchas**
- *
- * Paths are interpreted by the provided implementation, so relative paths, case
- * sensitivity, permissions, links, and watch behavior are platform-dependent.
- * Size options are normalized to branded bigint byte counts; prefer the `Size`,
- * `KiB`, `MiB`, and related helpers for offsets, chunk sizes, and truncation
- * lengths. A program that uses this service still needs a concrete layer, such
- * as `NodeFileSystem.layer`, before it can access the real file system.
+ * Defines the portable file system service for Effect programs.
+ *
+ * `FileSystem` is the boundary between Effect code and the host file system.
+ * Platform packages provide concrete layers, while this module defines the
+ * operations for reading, writing, inspecting, streaming, and watching files.
+ * Operations return `Effect`, `Stream`, or `Sink` values and fail with
+ * `PlatformError`. The module also includes file handles, size helpers, open
+ * flags, watch events, and the watch backend service.
  *
  * @since 4.0.0
  */