effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/unstable/http/HttpServerError.ts

@@ -1,23 +1,36 @@
 /**
- * Error types and response conversion helpers used by the HTTP server runtime.
- *
- * This module models the failure cases that can happen around a server request:
- * malformed or unreadable requests, unmatched routes, unexpected handler
- * failures, response construction or delivery failures, and lower-level server
- * implementation failures. These errors keep the relevant request, and for
- * response failures the response that was being produced, so applications can
- * report, inspect, or translate failures without losing HTTP context.
- *
- * Most users encounter these errors when decoding request bodies, implementing
- * fallback routes, adding error reporting, or customizing how handler failures
- * become responses. Request parse errors become `400` responses, missing routes
- * become `404` responses and are ignored by the error reporter, and internal or
- * response errors become `500` responses. A `ResponseError` records the response
- * involved in the failure, but its default conversion intentionally sends an
- * empty `500` instead of reusing a response that may already be invalid or
- * partially failed. Handler causes can also contain respondable failures,
- * response defects, or interrupts; the conversion helpers preserve those
- * distinctions, including `499` for client aborts and `503` for server aborts.
+ * Error model used by the unstable HTTP server runtime.
+ *
+ * This module defines the tagged failures that can occur while a server accepts
+ * a request, matches a route, runs a handler, or builds and sends a response.
+ * Request-scoped failures keep the request that caused them, and response
+ * failures keep the response that was being produced, so applications can log,
+ * report, or translate failures without reconstructing HTTP context.
+ *
+ * **Mental model**
+ *
+ * {@link HttpServerError} wraps a concrete {@link HttpServerErrorReason}.
+ * {@link RequestParseError}, {@link RouteNotFound}, and {@link InternalError}
+ * describe failures before or during request handling, while
+ * {@link ResponseError} describes a failure tied to a response that was already
+ * being built or sent. {@link ServeError} represents lower-level server
+ * implementation failures outside an individual handler response.
+ *
+ * **Common tasks**
+ *
+ * Use {@link isHttpServerError} to refine unknown failures, inspect `request`
+ * and `response` when reporting failures, and use {@link causeResponse} or
+ * {@link exitResponse} when a handler cause or exit must be translated into the
+ * HTTP response sent to the client.
+ *
+ * **Gotchas**
+ *
+ * The default response mapping is intentionally small: request parse errors
+ * become `400`, route misses become ignored `404` failures, internal and
+ * response errors become `500`, client aborts marked with {@link ClientAbort}
+ * become `499`, and server-side interrupts become `503`. A
+ * {@link ResponseError} does not reuse the failed response when converted; it
+ * produces an empty `500` because that response may be invalid or partly sent.
  *
  * @since 4.0.0
  */
@@ -45,7 +58,7 @@ const TypeId = "~effect/http/HttpServerError"
  * response, and can be converted to an HTTP response through the `Respondable`
  * protocol.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class HttpServerError extends Data.TaggedError("HttpServerError")<{
@@ -96,7 +109,7 @@ export class HttpServerError extends Data.TaggedError("HttpServerError")<{
  *
  * When converted to a response it produces an empty `400` response.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class RequestParseError extends Data.TaggedError("RequestParseError")<{
@@ -130,7 +143,7 @@ export class RequestParseError extends Data.TaggedError("RequestParseError")<{
  * When converted to a response it produces an empty `404` response, and it is
  * ignored by the error reporter.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class RouteNotFound extends Data.TaggedError("RouteNotFound")<{
@@ -160,7 +173,7 @@ export class RouteNotFound extends Data.TaggedError("RouteNotFound")<{
  *
  * When converted to a response it produces an empty `500` response.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class InternalError extends Data.TaggedError("InternalError")<{
@@ -202,7 +215,7 @@ export const isHttpServerError = (u: unknown): u is HttpServerError => hasProper
  * It carries the request and response involved in the failure. When converted to
  * a response it produces an empty `500` response.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class ResponseError extends Data.TaggedError("ResponseError")<{
@@ -228,7 +241,7 @@ export class ResponseError extends Data.TaggedError("ResponseError")<{
 /**
  * Union of errors that are tied directly to an incoming server request.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export type RequestError = RequestParseError | RouteNotFound | InternalError
@@ -236,7 +249,7 @@ export type RequestError = RequestParseError | RouteNotFound | InternalError
 /**
  * Reason carried by an `HttpServerError`, either a request-level error or a response-level error.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export type HttpServerErrorReason = RequestError | ResponseError
@@ -244,7 +257,7 @@ export type HttpServerErrorReason = RequestError | ResponseError
 /**
  * Error wrapping a low-level failure from the HTTP server implementation.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class ServeError extends Data.TaggedError("ServeError")<{
@@ -337,7 +350,7 @@ export const causeResponse = <E>(
 }
 
 /**
- * Synchronously derives an HTTP response from a failed handler cause.
+ * Derives an HTTP response from a failed handler cause synchronously.
  *
  * **Details**
  *

package/src/unstable/http/HttpServerRequest.ts

@@ -1,20 +1,37 @@
 /**
- * Utilities for working with the request visible to HTTP server handlers.
+ * Server-side access to the current incoming HTTP request.
  *
- * This module defines `HttpServerRequest`, the request-scoped context service
- * used by server effects, middleware, schema decoders, multipart parsers,
- * WebSocket upgrades, and conversions between Effect HTTP requests, client
- * requests, and Web `Request` values. Handlers commonly use it to inspect the
- * method, URL, headers, cookies, remote address, and body, or to decode those
- * parts with schemas instead of parsing raw values by hand.
+ * This module defines the `HttpServerRequest` context service used by HTTP
+ * handlers, middleware, schema decoders, multipart parsers, WebSocket upgrades,
+ * and adapters. A request value carries the method, URL, original URL, headers,
+ * cookies, remote address, body stream, and platform source object, plus helpers
+ * for converting to and from Effect client requests and Web `Request` values.
  *
- * Body access is effectful because reading, parsing, schema decoding, or
- * multipart persistence can fail. Streaming request bodies may be single-use
- * depending on the underlying platform, while cached accessors such as text,
- * JSON, URL parameters, array buffers, and persisted multipart data reuse the
- * first read. Multipart persistence also requires `Scope`, `FileSystem`, and
- * `Path` services, and search parameter decoding depends on the
- * `ParsedSearchParams` service being provided by the router or adapter.
+ * **Mental model**
+ *
+ * Server handlers read the current request from context. Metadata such as the
+ * method, URL, headers, and cookies is available directly, while body access is
+ * effectful because reading, parsing, schema decoding, or multipart persistence
+ * can fail. Schema helpers decode cookies, headers, search parameters, JSON
+ * bodies, URL-encoded bodies, multipart bodies, and form JSON without each
+ * handler needing to parse raw values by hand.
+ *
+ * **Common tasks**
+ *
+ * - Inspect request metadata or derive a modified request view.
+ * - Decode cookies, headers, search parameters, or body content with schemas.
+ * - Upgrade a request to a WebSocket channel.
+ * - Convert between server requests, client requests, and Web `Request` values.
+ *
+ * **Gotchas**
+ *
+ * Streaming request bodies may be single-use depending on the underlying
+ * platform. Cached accessors such as text, JSON, URL parameters, array buffers,
+ * and persisted multipart data reuse the first read. Multipart persistence
+ * requires `Scope`, `FileSystem`, and `Path` services. Search parameter decoding
+ * depends on the `ParsedSearchParams` service being provided by the router or
+ * adapter, and body size limits are controlled through the re-exported
+ * `MaxBodySize` fiber reference.
  *
  * @since 4.0.0
  */
@@ -45,7 +62,12 @@ import * as UrlParams from "./UrlParams.ts"
 
 export {
   /**
-   * Re-exports the `MaxBodySize` fiber reference for configuring request body limits.
+   * Provides the `MaxBodySize` fiber reference for configuring request body limits.
+   *
+   * **When to use**
+   *
+   * Use to configure the maximum body size accepted while reading server
+   * request bodies.
    *
    * @category fiber refs
    * @since 4.0.0
@@ -100,7 +122,12 @@ export interface HttpServerRequest extends HttpIncomingMessage.HttpIncomingMessa
 }
 
 /**
- * Service tag for the current `HttpServerRequest`.
+ * Service tag for the active server-side HTTP request.
+ *
+ * **When to use**
+ *
+ * Use to access the request currently being handled by HTTP server routes and
+ * middleware.
  *
  * @category context
  * @since 4.0.0
@@ -110,7 +137,12 @@ export const HttpServerRequest: Context.Service<HttpServerRequest, HttpServerReq
 )
 
 /**
- * Request-scoped service containing parsed search parameters.
+ * Service that contains decoded URL query parameters for the current request.
+ *
+ * **When to use**
+ *
+ * Use to access query parameters that have already been parsed for the current
+ * server request.
  *
  * **Details**
  *
@@ -989,7 +1021,7 @@ const isFormData = (u: unknown): u is FormData => typeof FormData !== "undefined
 const textDecoder = new TextDecoder()
 
 /**
- * Attempts to construct an absolute `URL` for a server request.
+ * Attempts to construct an absolute `URL` for a server request safely.
  *
  * **Details**
  *
@@ -1011,7 +1043,7 @@ export const toURL = (self: HttpServerRequest): Option.Option<URL> => {
 }
 
 /**
- * Converts an `HttpServerRequest` to a Web `Request` as a `Result`.
+ * Converts an `HttpServerRequest` safely to a Web `Request` as a `Result`.
  *
  * **Details**
  *

package/src/unstable/http/HttpServerRespondable.ts

@@ -1,20 +1,34 @@
 /**
- * Protocol and conversion helpers for values that can become HTTP server
- * responses.
+ * Protocol for values that can render themselves as HTTP server responses.
  *
  * This module lets server-side domain errors, HTTP API errors, and helper
- * modules describe how they should be sent to a client without constructing an
- * `HttpServerResponse` at every call site. Implement `Respondable` on values
- * that should choose their own status, headers, cookies, or body when a route
- * fails or a server helper recovers by sending a response.
- *
- * Conversion is intentionally conservative. Existing `HttpServerResponse`
- * values are returned directly, fallback conversion maps schema errors to `400`
- * and no-such-element errors to `404`, and otherwise uses the caller-provided
- * fallback. Errors raised while running a respondable conversion become defects
- * with `toResponse`, while the fallback helpers catch conversion failures and
- * use the fallback response. Defect conversion only gives special handling to
- * `HttpServerResponse` and `Respondable` values.
+ * values describe the response they should send to a client. Implement
+ * `Respondable` when a value should choose its own status, headers, cookies, or
+ * body during route error handling without forcing every call site to construct
+ * an `HttpServerResponse` directly.
+ *
+ * **Mental model**
+ *
+ * A respondable value owns the last step from domain-level information to an
+ * `HttpServerResponse`. Server error handling can ask the value for a response,
+ * while unknown failures still go through a caller-provided fallback response.
+ * Existing `HttpServerResponse` values are already respondable for conversion
+ * purposes and are returned directly.
+ *
+ * **Common tasks**
+ *
+ * Use `toResponse` when the value is known to implement the protocol and
+ * conversion failures should become defects. Use `toResponseOrElse` when
+ * handling unknown failures from route effects and a fallback response should be
+ * used when no conversion is available. Use `toResponseOrElseDefect` for defect
+ * recovery, where only explicit response-like values receive special handling.
+ *
+ * **Gotchas**
+ *
+ * Fallback conversion is intentionally conservative. Schema errors become `400`
+ * responses, no-such-element errors become `404` responses, and other values use
+ * the supplied fallback. The fallback helpers also catch failures raised while
+ * running a respondable conversion; `toResponse` does not.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpServerResponse.ts

@@ -1,23 +1,45 @@
 /**
- * Server-side HTTP response values and constructors for Effect HTTP handlers.
- *
- * This module defines `HttpServerResponse`, the immutable response model returned
- * from routers and server effects, together with constructors for empty,
- * redirect, text, HTML, JSON, URL-encoded, raw, form-data, stream, and file
- * bodies. It also includes combinators for adjusting status, headers, cookies,
- * and bodies, plus conversions to and from Web `Response` and client responses.
- *
- * Response constructors choose status defaults for common cases: `204` for
- * `empty`, `302` for `redirect`, and `200` for responses with bodies. Body
- * metadata is mirrored into headers, so content type and content length carried
- * by the body are written to `content-type` and `content-length`, overriding
- * existing values when present. JSON helpers can fail while encoding or
- * serializing unless the unsafe constructor is used.
- *
- * Cookies are tracked separately from the normal header map so they can be
- * encoded as `Set-Cookie` headers when converting to platform responses. Use the
- * effectful cookie helpers when invalid cookie names, values, or options should
- * stay in the Effect error channel.
+ * The `HttpServerResponse` module provides immutable response values for Effect
+ * HTTP servers. Handlers return an {@link HttpServerResponse}, then the runtime
+ * converts it to a platform response such as a Web `Response`.
+ *
+ * **Mental model**
+ *
+ * - A response is a status, optional status text, headers, cookies, and an HTTP
+ *   body.
+ * - Constructors set practical defaults: {@link empty} uses `204`,
+ *   {@link redirect} uses `302`, and body constructors use `200`.
+ * - Body metadata is reflected into headers when a response is created or when
+ *   the body is replaced.
+ * - Cookies are stored separately from the normal header map and become
+ *   `Set-Cookie` headers during conversion.
+ * - Constructors that encode data can return effects when encoding may fail.
+ *
+ * **Common tasks**
+ *
+ * - Create empty, redirect, text, HTML, JSON, or URL-encoded responses with
+ *   {@link empty}, {@link redirect}, {@link text}, {@link html}, {@link json},
+ *   {@link schemaJson}, or {@link urlParams}.
+ * - Send binary, raw, form-data, stream, or file bodies with {@link uint8Array},
+ *   {@link raw}, {@link formData}, {@link stream}, {@link file}, or
+ *   {@link fileWeb}.
+ * - Adjust status, headers, and bodies with {@link setStatus},
+ *   {@link setHeader}, {@link setHeaders}, and {@link setBody}.
+ * - Manage cookies with {@link setCookie}, {@link expireCookie},
+ *   {@link removeCookie}, and their unsafe variants.
+ * - Convert responses with {@link toWeb}, {@link fromWeb},
+ *   {@link toClientResponse}, and {@link fromClientResponse}.
+ *
+ * **Gotchas**
+ *
+ * - Body content type and content length override existing `content-type` and
+ *   `content-length` headers when body metadata is present.
+ * - {@link json} and {@link schemaJson} capture encoding failures in the Effect
+ *   error channel; {@link jsonUnsafe} throws instead.
+ * - {@link setCookie} and {@link expireCookie} validate cookie output in the
+ *   Effect error channel; unsafe cookie helpers throw on invalid cookies.
+ * - `Set-Cookie` headers are produced from the response cookie collection, not
+ *   by manually editing the normal header map.
  *
  * @since 4.0.0
  */
@@ -420,7 +442,7 @@ export const urlParams = (
  *
  * **When to use**
  *
- * Use this when the underlying runtime already understands the body value, such
+ * Use when the underlying runtime already understands the body value, such
  * as a Web `Response`, `Blob`, or `ReadableStream`; the body is passed through
  * for later platform conversion.
  *
@@ -720,7 +742,7 @@ export const setCookie: {
 )
 
 /**
- * Expires a cookie on an `HttpServerResponse`.
+ * Sets an expired cookie on an `HttpServerResponse`.
  *
  * **Details**
  *
@@ -732,7 +754,7 @@ export const setCookie: {
  */
 export const expireCookie: {
   /**
-   * Expires a cookie on an `HttpServerResponse`.
+   * Sets an expired cookie on an `HttpServerResponse`.
    *
    * **Details**
    *
@@ -749,7 +771,7 @@ export const expireCookie: {
     self: HttpServerResponse
   ) => Effect.Effect<HttpServerResponse, Cookies.CookiesError>
   /**
-   * Expires a cookie on an `HttpServerResponse`.
+   * Sets an expired cookie on an `HttpServerResponse`.
    *
    * **Details**
    *
@@ -787,8 +809,8 @@ export const expireCookie: {
  *
  * **When to use**
  *
- * Use `setCookie` when cookie errors should be represented as `CookiesError`
- * failures.
+ * Use when setting one trusted cookie and encoding failures should throw
+ * instead of being represented as `CookiesError` failures.
  *
  * @category combinators
  * @since 4.0.0
@@ -800,8 +822,8 @@ export const setCookieUnsafe: {
    *
    * **When to use**
    *
-   * Use `setCookie` when cookie errors should be represented as `CookiesError`
-   * failures.
+   * Use when setting one trusted cookie and encoding failures should throw
+   * instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -813,8 +835,8 @@ export const setCookieUnsafe: {
    *
    * **When to use**
    *
-   * Use `setCookie` when cookie errors should be represented as `CookiesError`
-   * failures.
+   * Use when setting one trusted cookie and encoding failures should throw
+   * instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -840,26 +862,26 @@ export const setCookieUnsafe: {
 )
 
 /**
- * Expires a cookie on an `HttpServerResponse`, throwing if the expiration cookie
+ * Sets an expired cookie on an `HttpServerResponse`, throwing if the expiration cookie
  * cannot be encoded.
  *
  * **When to use**
  *
- * Use `expireCookie` when cookie errors should be represented as `CookiesError`
- * failures.
+ * Use when expiring one trusted cookie and encoding failures should throw
+ * instead of being represented as `CookiesError` failures.
  *
  * @category combinators
  * @since 4.0.0
  */
 export const expireCookieUnsafe: {
   /**
-   * Expires a cookie on an `HttpServerResponse`, throwing if the expiration cookie
+   * Sets an expired cookie on an `HttpServerResponse`, throwing if the expiration cookie
    * cannot be encoded.
    *
    * **When to use**
    *
-   * Use `expireCookie` when cookie errors should be represented as `CookiesError`
-   * failures.
+   * Use when expiring one trusted cookie and encoding failures should throw
+   * instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -869,13 +891,13 @@ export const expireCookieUnsafe: {
     options?: Omit<NonNullable<Cookies.Cookie["options"]>, "expires" | "maxAge">
   ): (self: HttpServerResponse) => HttpServerResponse
   /**
-   * Expires a cookie on an `HttpServerResponse`, throwing if the expiration cookie
+   * Sets an expired cookie on an `HttpServerResponse`, throwing if the expiration cookie
    * cannot be encoded.
    *
    * **When to use**
    *
-   * Use `expireCookie` when cookie errors should be represented as `CookiesError`
-   * failures.
+   * Use when expiring one trusted cookie and encoding failures should throw
+   * instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -1074,8 +1096,8 @@ export const setCookies: {
  *
  * **When to use**
  *
- * Use `setCookies` when cookie errors should be represented as `CookiesError`
- * failures.
+ * Use when setting multiple trusted cookies and encoding failures should throw
+ * instead of being represented as `CookiesError` failures.
  *
  * @category combinators
  * @since 4.0.0
@@ -1087,8 +1109,8 @@ export const setCookiesUnsafe: {
    *
    * **When to use**
    *
-   * Use `setCookies` when cookie errors should be represented as `CookiesError`
-   * failures.
+   * Use when setting multiple trusted cookies and encoding failures should throw
+   * instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -1108,8 +1130,8 @@ export const setCookiesUnsafe: {
    *
    * **When to use**
    *
-   * Use `setCookies` when cookie errors should be represented as `CookiesError`
-   * failures.
+   * Use when setting multiple trusted cookies and encoding failures should throw
+   * instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0

package/src/unstable/http/HttpStaticServer.ts

@@ -1,19 +1,36 @@
 /**
  * Static file serving for Effect HTTP applications.
  *
- * This module builds request handlers and router layers that serve files from a
- * configured root directory. It is intended for public assets such as compiled
- * front-end bundles, images, fonts, downloads, documentation sites, and single
- * page applications that need an `index.html` fallback.
+ * `HttpStaticServer` turns HTTP requests into file responses rooted at a
+ * configured directory. Use {@link make} when you need an application value, or
+ * {@link layer} when static files should be mounted onto an `HttpRouter`,
+ * optionally under a URL prefix.
  *
- * Requests are resolved relative to the configured root after decoding and
- * normalizing the URL path. Malformed paths, null bytes, and `..` traversal
- * outside the root are rejected, but the module still serves anything the
- * configured `FileSystem` can reach below that root. Keep secrets out of the
- * served tree, be careful with symlinks or generated files, and remember that
- * dotfiles are not hidden automatically. File responses include content type,
- * optional cache control, byte-range support, and conditional request handling
- * based on the metadata supplied by `HttpPlatform`.
+ * **Mental model**
+ *
+ * The request path is decoded, normalized, and resolved below `root`. Invalid
+ * paths, null bytes, and `..` traversal outside `root` fail as route-not-found
+ * errors. A matching file is served through `HttpPlatform.fileResponse`, a
+ * matching directory serves `index` when configured, and `spa: true` falls back
+ * to the index file for extensionless HTML requests.
+ *
+ * **Common tasks**
+ *
+ * - Serve a public assets directory with {@link make}
+ * - Mount static assets beside API routes with {@link layer}
+ * - Add `Cache-Control` headers with `cacheControl`
+ * - Extend MIME type detection with `mimeTypes`
+ * - Support single-page application routing with `spa: true`
+ *
+ * **Gotchas**
+ *
+ * - {@link layer} installs `GET` routes only; handle other methods elsewhere.
+ * - Dotfiles are served when they live under `root`; keep secrets outside the
+ *   served tree.
+ * - Symlinks or generated files reachable from `root` may expose more than
+ *   expected.
+ * - Conditional requests and byte ranges depend on metadata supplied by
+ *   `HttpPlatform`.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpTraceContext.ts

@@ -1,21 +1,34 @@
 /**
- * Utilities for HTTP trace-context propagation.
+ * HTTP propagation helpers for Effect tracing context.
  *
- * This module converts Effect `Tracer.Span` values to outbound tracing headers
+ * This module converts Effect `Tracer.Span` values into outbound trace headers
  * and decodes inbound propagation headers into `Tracer.ExternalSpan` parents.
- * It is used by traced HTTP clients to continue the current span across an
- * outbound request, and by server middleware to parent request spans from
- * upstream services. The helpers are also useful for adapters or middleware
- * that need to bridge Effect tracing with W3C Trace Context or B3-compatible
- * systems.
- *
- * Outbound propagation writes both W3C `traceparent` and compact B3 `b3`
- * headers. Inbound decoding prefers W3C `traceparent`, then compact B3, then
- * multi-header B3 (`x-b3-*`). Header names in `Headers.Headers` are expected to
- * be lowercase; use the safe header constructors when accepting raw platform
- * headers. Invalid or unsupported header shapes simply decode to `Option.none`,
- * so callers should treat missing trace context as "start a new trace" rather
- * than as an error.
+ * HTTP clients use it to continue the current span across outgoing requests, and
+ * server middleware uses it to parent request spans from upstream services.
+ *
+ * **Mental model**
+ *
+ * Propagation is metadata, not tracing storage. {@link toHeaders} serializes the
+ * current span into HTTP headers for the next service. {@link fromHeaders}
+ * inspects incoming headers and returns an external parent span when a supported
+ * propagation format is present.
+ *
+ * **Common tasks**
+ *
+ * - Add outbound propagation headers with {@link toHeaders}
+ * - Decode an inbound parent span with {@link fromHeaders}
+ * - Use {@link w3c}, {@link b3}, or {@link xb3} directly when an adapter needs a
+ *   specific propagation format
+ *
+ * **Gotchas**
+ *
+ * - Outbound propagation writes both W3C `traceparent` and compact B3 `b3`
+ *   headers
+ * - Inbound decoding prefers W3C `traceparent`, then compact B3, then
+ *   multi-header B3 (`x-b3-*`)
+ * - Header names in `Headers.Headers` are expected to be lowercase
+ * - Missing or unsupported trace context decodes to `Option.none`, so callers
+ *   should start a new trace when no parent is returned
  *
  * @since 4.0.0
  */
@@ -61,7 +74,7 @@ export const toHeaders = (span: Tracer.Span): Headers.Headers =>
   })
 
 /**
- * Decodes an external span from HTTP trace propagation headers.
+ * Decodes an external span safely from HTTP trace propagation headers.
  *
  * **Details**
  *
@@ -84,7 +97,7 @@ export const fromHeaders = (headers: Headers.Headers): Option.Option<Tracer.Exte
 }
 
 /**
- * Decodes an external span from the compact B3 `b3` header.
+ * Decodes an external span safely from the compact B3 `b3` header.
  *
  * **Details**
  *
@@ -110,7 +123,7 @@ export const b3: FromHeaders = (headers) => {
 }
 
 /**
- * Decodes an external span from multi-header B3 propagation headers.
+ * Decodes an external span safely from multi-header B3 propagation headers.
  *
  * **Details**
  *
@@ -135,7 +148,7 @@ const w3cTraceId = /^[0-9a-f]{32}$/i
 const w3cSpanId = /^[0-9a-f]{16}$/i
 
 /**
- * Decodes an external span from the W3C `traceparent` header.
+ * Decodes an external span safely from the W3C `traceparent` header.
  *
  * **Details**
  *