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

package/src/unstable/eventlog/SqlEventLogServerUnencrypted.ts

@@ -1,21 +1,40 @@
 /**
- * SQL-backed storage for an unencrypted event-log server.
+ * SQL-backed storage for unencrypted event-log servers.
  *
- * This module provides the persistence layer used by
+ * This module provides the durable `Storage` implementation used by
  * `EventLogServerUnencrypted` when remote entries should be stored in a SQL
- * database and streamed back to clients by store sequence. It creates and uses
+ * database and streamed back to clients by store sequence. It creates
  * dialect-specific tables for the server remote id, per-store sequence state,
- * plaintext entries, and session authentication bindings, which makes it useful
- * for durable local or service-side event-log deployments where database
- * backup, replication, and transactional ordering are desired.
+ * plaintext entries, and session authentication bindings.
+ *
+ * **Mental model**
+ *
+ * Each server store is an append-only SQL sequence. A write transaction ensures
+ * the store row exists, locks its next sequence, inserts the plaintext entry
+ * rows, advances the sequence, and publishes the committed remote entries to
+ * in-process subscribers. A change stream first reads the SQL backlog from the
+ * requested sequence, applies compaction, and then continues with entries
+ * published by this process.
+ *
+ * **Common tasks**
+ *
+ * - Persist an unencrypted event-log server across process restarts.
+ * - Use database backup, replication, and transactional ordering for remote
+ *   event-log entries.
+ * - Choose table names with `entryTablePrefix` and `remoteIdTable`, or tune
+ *   insert batching with `insertBatchSize`.
+ *
+ * **Gotchas**
  *
  * Entry payloads are intentionally written as plaintext bytes. Use this storage
  * only when the database, transport, backups, logs, and operators are trusted,
- * or when encryption is handled outside this module. Table names are derived
- * from the provided prefixes, and writes rely on SQL transactions plus
- * store-level sequence rows, so deployments should provision compatible
- * isolation/locking behavior and account for dialect-specific binary and text
- * column limits.
+ * or when encryption is handled outside this module. Live notifications are
+ * process-local after the initial SQL backlog read, so multi-process
+ * deployments need routing, reconnect/backfill behavior, or an external
+ * notification channel for writes made elsewhere. Writes also rely on SQL
+ * transactions and store-level locking, so deployments should provision
+ * compatible isolation behavior and account for dialect-specific binary and
+ * text column limits.
  *
  * @since 4.0.0
  */

package/src/unstable/eventlog/index.ts

@@ -5,311 +5,71 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * Defines typed event-log events for use with `EventLog` and event groups.
- *
- * An event definition names a durable domain event with a tag, derives the
- * aggregate or entity primary key from the payload, and records the schemas used
- * to encode the payload and decode handler success or failure values. These
- * definitions are the shared contract between clients that write events and
- * servers that register handlers, so they are useful for command-style writes,
- * replicated logs, audit trails, and workflows that need replayable domain
- * facts.
- *
- * Payloads are serialized with MessagePack, while success and error values are
- * described separately for the handler result. Keep payload schemas stable once
- * events have been persisted or replicated, prefer explicit versioned event tags
- * or backward-compatible schemas for changes, and make primary keys deterministic
- * so related entries are grouped consistently across stores and remotes.
- *
  * @since 4.0.0
  */
 export * as Event from "./Event.ts"
 
 /**
- * Defines typed groups of event-log event definitions.
- *
- * Event groups describe the events that belong to one event-log domain, such as
- * commands for an aggregate, application workflow, or synced local store. Start
- * from `empty`, add event tags with their payload, success, and error schemas,
- * then use the group with `EventLog.group` to provide the handlers that execute
- * and commit those events.
- *
- * Each event tag becomes the key in the group's events record, so tags should be
- * unique within a group. The `primaryKey` function is part of the event
- * definition and should derive the stable partition key from the decoded
- * payload. Omitted schemas default to `Schema.Void` for payload and success, and
- * `Schema.Never` for errors; use `addError` when every event in the group shares
- * an additional error schema.
- *
  * @since 4.0.0
  */
 export * as EventGroup from "./EventGroup.ts"
 
 /**
- * Low-level storage and replay primitives for the unstable event-log system.
- *
- * An `EventJournal` records committed event entries, exposes them for replay,
- * and tracks the replication state needed to exchange entries with remote
- * journals. It is the persistence boundary used by higher-level event-log
- * schemas and handlers for workflows such as rebuilding projections, syncing
- * offline clients, importing remote changes, and coordinating per-store writes.
- *
- * Journal entries are ordered by their UUID v7 entry ids, so persistence and
- * replay code should account for clock-derived ordering when detecting
- * conflicts. Payloads are stored as encoded bytes and must remain compatible
- * with the event schemas that will decode them later. Remote writes may include
- * duplicate entries, compaction can rewrite the set of imported entries before
- * effects run, and replay handlers should be prepared for entries that arrive
- * after local changes for the same event and primary key.
- *
  * @since 4.0.0
  */
 export * as EventJournal from "./EventJournal.ts"
 
 /**
- * Typed event-log runtime for appending domain events to an `EventJournal` and
- * replaying entries from remote replicas.
- *
- * This module is used to define event-log schemas, register handlers for event
- * groups, build clients that write typed payloads, and connect local journals to
- * authenticated remote sessions. It is useful for event-sourced state,
- * offline-first synchronization, audit trails, and replicated stores where each
- * event must run its handler before the entry is committed.
- *
- * Local appends encode payloads with the event schema and commit only after the
- * registered handler succeeds. Remote replay decodes entries with the same
- * schema, passes duplicate or conflicting entries to handlers, may run
- * compaction before committing, and invalidates registered reactivity keys.
- * Remote sessions depend on the current `Identity` and `CurrentStoreId`, so use
- * stable values when multiple replicas or stores must share the same log.
- *
  * @since 4.0.0
  */
 export * as EventLog from "./EventLog.ts"
 
 /**
- * Event-log encryption primitives for encrypted remote replication.
- *
- * This module defines the `EventLogEncryption` service used by encrypted
- * `EventLogRemote` clients to turn local journal entries into encrypted remote
- * payloads, decrypt encrypted changes received from a server, hash byte data,
- * and create event-log identities. It is useful when events need to be
- * replicated through infrastructure that stores or transports only ciphertext,
- * such as an encrypted event-log server, offline-first synchronization backend,
- * or multi-device replicated store.
- *
- * Encryption keys are deterministically derived from the identity private key
- * material, so the same stable identity is required to decrypt entries across
- * sessions and devices. The public key identifies the replicated log, while the
- * private key material must remain secret and must not be rotated without a
- * migration plan for existing encrypted entries. The default implementation
- * uses Web Crypto AES-GCM with generated initialization vectors that are stored
- * alongside encrypted entries; persisted ciphertext, IVs, entry schemas, and
- * identity key derivation labels are part of the compatibility surface for
- * future event-log encryption versions.
- *
  * @since 4.0.0
  */
 export * as EventLogEncryption from "./EventLogEncryption.ts"
 
 /**
- * Defines the wire messages used by event-log remotes to authenticate clients,
- * write event batches, and stream changes back to replicas.
- *
- * This module is the protocol boundary between `EventLogRemote` clients and
- * event-log servers: it provides schemas for store identifiers, protocol
- * errors, session handshake payloads, authenticated RPCs, and the msgpack
- * payloads used to carry encrypted or plaintext journal entries.
- *
- * Event batches are serialized as binary payloads before transport. Small
- * payloads can be sent as a single frame, while larger payloads are split into
- * `ChunkedMessage` parts and must be reassembled by message id after every part
- * has arrived. Transports should preserve `Uint8Array` bytes exactly and avoid
- * treating msgpack data as text.
- *
  * @since 4.0.0
  */
 export * as EventLogMessage from "./EventLogMessage.ts"
 
 /**
- * Client-side remote replica support for writing event-log entries and
- * receiving change streams over the event-log RPC protocol.
- *
- * This module builds `EventLogRemote` services backed by `EventLogRemoteRpcs`.
- * It is used by local event logs that need to replicate entries to another
- * journal, subscribe to remote changes from a sequence number, or run effects
- * only after the current event-log identity has completed the remote
- * authentication handshake. The encrypted constructor is the default choice for
- * synchronizing browser, edge, or service replicas across an untrusted network,
- * while the unencrypted constructor is intended for trusted transports or tests.
- *
- * Remote sessions begin with `Hello` and `Authenticate`, cache authentication by
- * identity public key, and retry forbidden responses by refreshing the handshake.
- * The RPC transport must preserve a stable client session across hello,
- * authentication, writes, and change streams. Entries and change batches may be
- * split into protocol chunks, so callers should treat `changes` as a scoped
- * streaming queue and rely on the remote `Registry` registration instead of
- * manually sharing partially assembled payloads between sessions.
- *
  * @since 4.0.0
  */
 export * as EventLogRemote from "./EventLogRemote.ts"
 
 /**
- * Server-side RPC handlers for accepting remote event-log writes and streaming
- * changes back to authenticated clients.
- *
- * This module is the protocol glue used by concrete event-log servers: it
- * performs the hello / authenticate challenge flow, attaches the authenticated
- * `EventLog.Identity` to subsequent RPC requests, reassembles chunked writes,
- * and chunks large change payloads before they are sent to clients. It is useful
- * when exposing an event-log replica over HTTP-backed RPC, for example to sync
- * browser, edge, or service replicas with a central journal.
- *
- * The authentication state is tied to the RPC client session annotations, so the
- * transport must preserve a stable client session between `Hello`,
- * `Authenticate`, writes, and change streams. Deployments should run the endpoint
- * over TLS, avoid exposing unauthenticated write or changes routes, and persist
- * session-auth key bindings with the same trust boundary as the event-log data.
- *
  * @since 4.0.0
  */
 export * as EventLogServer from "./EventLogServer.ts"
 
 /**
- * Server-side RPC layers and storage contracts for encrypted event-log
- * replication.
- *
- * This module is used by encrypted `EventLogRemote` clients that need a remote
- * synchronization endpoint without exposing plaintext events to the server. The
- * server stores ciphertext, initialization vectors, entry ids, and remote
- * sequence numbers keyed by the client's public key and store id, then streams
- * encrypted changes back to clients so they can decrypt locally with their
- * identity private key material. This makes it suitable for offline-first
- * synchronization, multi-device replication, and hosted backends where the
- * transport or storage layer should not inspect event payloads.
- *
- * The server does not derive or hold encryption keys. It treats public keys as
- * log identities, persists one session authentication binding per public key,
- * and reuses the initialization vector supplied with each encrypted write
- * request for the entries in that batch. Persisted remote ids, session signing
- * key bindings, ciphertext, IVs, and sequence numbers are therefore part of the
- * encrypted replication protocol and should be kept stable by durable storage
- * implementations.
- *
  * @since 4.0.0
  */
 export * as EventLogServerEncrypted from "./EventLogServerEncrypted.ts"
 
 /**
- * Server implementation for event logs whose entries are persisted and streamed
- * in plaintext.
- *
- * This module is useful for trusted deployments, local development, tests, and
- * server-side event sources that need typed event handlers, conflict detection,
- * compaction, and RPC change streams without an encryption layer. It includes
- * services for mapping client store ids to server stores, authorizing reads and
- * writes, storing remote entries, and binding session authentication keys.
- *
- * Because payloads and journals are unencrypted, storage must be protected by
- * the surrounding infrastructure. Session authentication bindings are part of
- * the storage contract and must be persisted by durable implementations so a
- * public key cannot silently bind to a different signing key after a restart.
- * The provided memory storage is process-local and intended for ephemeral
- * servers, tests, or examples rather than durable multi-process use.
- *
  * @since 4.0.0
  */
 export * as EventLogServerUnencrypted from "./EventLogServerUnencrypted.ts"
 
 /**
- * Utilities for authenticating event log sessions with short-lived challenges
- * and Ed25519 signatures.
- *
- * This module builds and verifies the canonical payload that a remote peer signs
- * when proving control of a session signing key. It is used by event log
- * transports that need to bind a connection attempt to a remote identifier,
- * session challenge, advertised event log public key, and signing public key
- * before accepting session traffic.
- *
- * Callers are responsible for issuing fresh challenges, enforcing the challenge
- * time-to-live, and tracking whether a challenge has already been consumed. The
- * helpers here provide deterministic payload encoding, algorithm checks,
- * signature validation, and Web Crypto integration; they do not establish peer
- * trust by themselves. Trust decisions still need to compare the supplied keys
- * and remote identity against the application's authorization policy, and
- * signed payloads should be treated as bearer authentication material until the
- * challenge expires.
- *
  * @since 4.0.0
  */
 export * as EventLogSessionAuth from "./EventLogSessionAuth.ts"
 
 /**
- * SQL-backed persistence for the unstable event-log journal.
- *
- * This module provides an `EventJournal` implementation that stores local
- * entries and remote replication metadata in a `SqlClient` database. It is
- * useful when event-log data needs to survive process restarts, be replayed to
- * rebuild projections, or be synchronized with other journals such as remote
- * servers, peer replicas, or offline clients that later reconnect.
- *
- * The adapter creates the entry and remotes tables with dialect-specific UUID,
- * binary payload, and timestamp column types, but it only performs the minimal
- * `CREATE TABLE IF NOT EXISTS` setup needed by the journal. Applications that
- * customize table names, add indexes, or evolve storage should manage those
- * migrations explicitly and keep encoded payloads compatible with the schemas
- * that will decode historical entries. Remote sequence rows are persisted
- * separately from entries, duplicate imports are ignored by primary key, and
- * conflict checks rely on event name, primary key, and the timestamp derived
- * from the entry id.
- *
  * @since 4.0.0
  */
 export * as SqlEventJournal from "./SqlEventJournal.ts"
 
 /**
- * SQL-backed storage for encrypted event-log servers.
- *
- * This module provides the encrypted server-side storage implementation used
- * when event-log entries should be durable in a SQL database without exposing
- * plaintext event data to that database. It is intended for remote event-log
- * servers, sync services, and multi-client deployments where the server assigns
- * stable sequence numbers and broadcasts changes while clients retain control of
- * event encryption and decryption.
- *
- * The storage creates dialect-specific tables for the server remote id and
- * session authentication bindings, then creates per-identity/store entry tables
- * using a SHA-256-derived table suffix. Those entry tables store IVs, entry ids,
- * encrypted entry bytes, and the SQL sequence used for ordering. Operators
- * should account for these dynamically created tables in migrations, backups,
- * retention policies, and table-prefix changes. Encryption key material is not
- * stored here, so rotating encryption schemes or moving data between databases
- * requires compatibility with the clients that produced the encrypted entries.
- *
  * @since 4.0.0
  */
 export * as SqlEventLogServerEncrypted from "./SqlEventLogServerEncrypted.ts"
 
 /**
- * SQL-backed storage for an unencrypted event-log server.
- *
- * This module provides the persistence layer used by
- * `EventLogServerUnencrypted` when remote entries should be stored in a SQL
- * database and streamed back to clients by store sequence. It creates and uses
- * dialect-specific tables for the server remote id, per-store sequence state,
- * plaintext entries, and session authentication bindings, which makes it useful
- * for durable local or service-side event-log deployments where database
- * backup, replication, and transactional ordering are desired.
- *
- * Entry payloads are intentionally written as plaintext bytes. Use this storage
- * only when the database, transport, backups, logs, and operators are trusted,
- * or when encryption is handled outside this module. Table names are derived
- * from the provided prefixes, and writes rely on SQL transactions plus
- * store-level sequence rows, so deployments should provision compatible
- * isolation/locking behavior and account for dialect-specific binary and text
- * column limits.
- *
  * @since 4.0.0
  */
 export * as SqlEventLogServerUnencrypted from "./SqlEventLogServerUnencrypted.ts"

package/src/unstable/http/Cookies.ts

@@ -1,17 +1,63 @@
 /**
- * Utilities for representing, validating, parsing, and serializing HTTP cookies.
- *
- * This module provides an immutable `Cookies` collection keyed by cookie name,
- * constructors for validated `Cookie` values, and helpers for common server and
- * client flows such as reading `Cookie` request headers, emitting `Set-Cookie`
- * response headers, merging cookie sets, and expiring cookies.
- *
- * Cookie parsing is intentionally tolerant of malformed input: unsupported or
- * invalid `Set-Cookie` attributes are ignored, values are percent-decoded on a
- * best-effort basis, and collections keep one cookie per name. Security
- * attributes such as `HttpOnly`, `Secure`, `SameSite`, and `Partitioned` are
- * serialized when present, but browsers enforce their final behavior, so set
- * them explicitly for session, cross-site, and HTTPS-sensitive cookies.
+ * Immutable HTTP cookie values and collections for request and response
+ * workflows.
+ *
+ * The module models a validated {@link Cookie}, an immutable {@link Cookies}
+ * collection keyed by cookie name, and the conversions needed around HTTP
+ * headers. Use it to read request `Cookie` headers, build cookies with standard
+ * attributes, merge or remove cookies immutably, expire cookies, and emit
+ * response `Set-Cookie` headers.
+ *
+ * **Mental model**
+ *
+ * - A `Cookie` stores both the decoded `value` and the encoded `valueEncoded`
+ *   used in headers
+ * - A `Cookies` collection contains at most one cookie per name; later writes,
+ *   merges, and iterable inputs replace earlier cookies with the same name
+ * - `Cookie` request headers carry name/value pairs, while `Set-Cookie`
+ *   response headers carry one cookie plus optional attributes
+ * - Safe constructors return `Result` failures for invalid names, values,
+ *   domains, paths, or infinite `Max-Age` values
+ *
+ * **Common tasks**
+ *
+ * - Create cookies: {@link makeCookie}, {@link makeCookieUnsafe}
+ * - Build collections: {@link empty}, {@link fromIterable},
+ *   {@link fromSetCookie}, {@link fromReadonlyRecord}
+ * - Read values: {@link get}, {@link getValue}, {@link toRecord},
+ *   {@link isEmpty}
+ * - Update collections: {@link set}, {@link setUnsafe}, {@link setAll},
+ *   {@link setCookie}, {@link setAllCookie}, {@link remove}, {@link merge}
+ * - Expire cookies: {@link expireCookie}, {@link expireCookieUnsafe}
+ * - Encode and decode headers: {@link toCookieHeader},
+ *   {@link toSetCookieHeaders}, {@link serializeCookie}, {@link parseHeader}
+ *
+ * **Gotchas**
+ *
+ * - Use {@link toCookieHeader} for an outbound request `Cookie` header and
+ *   {@link toSetCookieHeaders} for response `Set-Cookie` headers.
+ * - Parsing is intentionally tolerant: malformed `Set-Cookie` input can be
+ *   ignored, unsupported attributes are skipped, and percent-decoding falls
+ *   back to the original text.
+ * - Security attributes such as `HttpOnly`, `Secure`, `SameSite`, and
+ *   `Partitioned` are serialized when present, but browser policy enforces
+ *   their final behavior.
+ *
+ * **Example** (Serializing a session cookie)
+ *
+ * ```ts
+ * import { Cookies } from "effect/unstable/http"
+ *
+ * const cookies = Cookies.setUnsafe(Cookies.empty, "session", "abc123", {
+ *   httpOnly: true,
+ *   path: "/",
+ *   sameSite: "lax",
+ *   secure: true
+ * })
+ *
+ * console.log(Cookies.toSetCookieHeaders(cookies))
+ * // ["session=abc123; Path=/; HttpOnly; Secure; SameSite=Lax"]
+ * ```
  *
  * @since 4.0.0
  */

package/src/unstable/http/Etag.ts

@@ -1,18 +1,32 @@
 /**
- * Utilities for representing and generating HTTP entity tags.
+ * HTTP entity tag values and metadata-based generator layers.
  *
- * ETags are validators that identify a particular representation of a
- * resource. Servers commonly attach them to responses so clients and
- * intermediaries can revalidate cached content with conditional requests such
- * as `If-None-Match`, or protect updates with preconditions such as `If-Match`.
+ * ETags are validators for a specific representation of a resource. Servers put
+ * them in `ETag` response headers so clients and intermediaries can revalidate
+ * cached content with `If-None-Match`, or protect writes with preconditions such
+ * as `If-Match`.
  *
- * This module models weak and strong ETags, formats them for the `ETag` header,
- * and provides generator layers that derive tags from file size and
- * modification-time metadata. Metadata-derived tags are convenient for static
- * files, but they are only as precise as the underlying metadata: choose strong
- * tags only when that metadata reliably changes for every byte-level change,
- * and use weak tags when the validator is suitable for cache revalidation but
- * not for operations that require byte-for-byte identity.
+ * **Mental model**
+ *
+ * A strong ETag represents byte-for-byte identity for the selected
+ * representation. A weak ETag represents a validator that is useful for cache
+ * revalidation but not for operations that require exact byte identity. The
+ * `Weak` and `Strong` models store the raw tag value; `toString` adds the
+ * required quotes and the `W/` prefix for weak tags.
+ *
+ * **Common tasks**
+ *
+ * - Format an `Etag` value for an HTTP header with `toString`.
+ * - Provide a `Generator` service with `layer` for strong metadata-derived tags.
+ * - Use `layerWeak` when size and modification time are good cache validators
+ *   but not a byte-for-byte guarantee.
+ *
+ * **Gotchas**
+ *
+ * The built-in generator derives tags only from file size and modification time.
+ * Choose the strong layer only when that metadata changes for every byte-level
+ * content change. This module formats ETags but does not parse incoming ETag
+ * headers or implement conditional request logic.
  *
  * @since 4.0.0
  */
@@ -100,7 +114,23 @@ const fromFileWeb = (file: Body.HttpBody.FileLike) => {
 }
 
 /**
- * Layer that provides a `Generator` which produces strong ETags from file size and modification time metadata.
+ * Layer that provides a `Generator` which produces strong ETags from file size
+ * and modification time metadata.
+ *
+ * **When to use**
+ *
+ * Use when file size and modification time reliably change for every byte-level
+ * change and the consuming HTTP code needs strong ETags from the `Generator`
+ * service.
+ *
+ * **Gotchas**
+ *
+ * This layer marks metadata-derived tags as strong. If the underlying storage
+ * can update file contents without changing the recorded size or modification
+ * time, those tags can stop representing byte-for-byte identity.
+ *
+ * @see {@link layerWeak} for weak metadata-derived ETags when byte-for-byte identity is not required
+ * @see {@link Generator} for the service provided by this layer
  *
  * @category layers
  * @since 4.0.0

package/src/unstable/http/FetchHttpClient.ts

@@ -1,19 +1,33 @@
 /**
- * Provides an `HttpClient` implementation backed by the Web Fetch API.
- *
- * Use this module when an application should run HTTP requests through the
- * platform's `fetch` implementation, such as browser code, edge runtimes, or
- * Node.js environments that provide `globalThis.fetch`. The `Fetch` reference
- * allows tests and custom runtimes to supply a different fetch function, while
- * `RequestInit` can provide defaults such as credentials, redirect behavior,
- * cache mode, or other platform-specific fetch options.
- *
- * The client translates Effect HTTP requests into fetch calls and wraps Web
- * `Response` values as `HttpClientResponse`s. Fetch implementations control
- * details such as CORS, cookies, redirect handling, and abort semantics, so
- * behavior can vary by platform. Stream request bodies are sent as Web streams
- * with `duplex: "half"` for runtimes that require it, and `content-length` is
- * omitted so fetch can manage body framing itself.
+ * Fetch-based implementation of the Effect HTTP client service.
+ *
+ * This module provides an `HttpClient` layer that executes requests through a
+ * Web Fetch API implementation. It is the transport to use in browsers, edge
+ * runtimes, and Node.js environments where `globalThis.fetch` is available, or
+ * anywhere a compatible fetch function can be supplied.
+ *
+ * **Mental model**
+ *
+ * `layer` installs an `HttpClient` whose runtime boundary is a call to `fetch`.
+ * The `Fetch` reference chooses the fetch function and defaults to
+ * `globalThis.fetch`. The `RequestInit` service supplies default fetch options
+ * such as credentials, redirects, cache behavior, or other platform-specific
+ * settings. Request-specific method, headers, body, and abort signal are written
+ * by the client for each call.
+ *
+ * **Common tasks**
+ *
+ * Provide `layer` when an Effect program should run outbound HTTP through the
+ * current platform. Override `Fetch` in tests or custom runtimes to capture
+ * requests or route them to a different implementation. Provide `RequestInit`
+ * when all requests made by this client should share fetch defaults.
+ *
+ * **Gotchas**
+ *
+ * Fetch behavior is platform behavior: CORS, cookies, redirect handling, aborts,
+ * and streaming support can differ across runtimes. Stream request bodies are
+ * sent as Web streams with `duplex: "half"` for runtimes that require it, and
+ * `content-length` is removed so fetch can manage body framing.
  *
  * @since 4.0.0
  */
@@ -96,7 +110,30 @@ const fetch: HttpClient.HttpClient = HttpClient.make((request, url, signal, fibe
 })
 
 /**
- * Layer that provides an `HttpClient` implementation backed by the configured `Fetch` function.
+ * Layer that provides an `HttpClient` implementation backed by the configured
+ * `Fetch` function.
+ *
+ * **When to use**
+ *
+ * Use when an Effect program should execute `HttpClient` requests through the
+ * platform `fetch` implementation, especially in browser, edge, or Node.js
+ * runtimes with `globalThis.fetch`.
+ *
+ * **Details**
+ *
+ * The layer uses the current `Fetch` reference and optional `RequestInit`
+ * service for each request. Request-specific method, headers, body, and abort
+ * signal are supplied by the client and override matching `RequestInit` fields.
+ *
+ * **Gotchas**
+ *
+ * Fetch behavior comes from the runtime's implementation, so CORS, cookies,
+ * redirects, abort handling, and streaming support can vary by platform. Stream
+ * request bodies are sent as Web streams with `duplex: "half"`, and any
+ * `content-length` header is removed before calling `fetch`.
+ *
+ * @see {@link Fetch} for supplying the fetch implementation used by this layer
+ * @see {@link RequestInit} for default `RequestInit` options applied before request-specific fields
  *
  * @category layers
  * @since 4.0.0