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

package/src/unstable/observability/Otlp.ts

@@ -1,22 +1,37 @@
 /**
- * Convenience layers for exporting Effect logs, metrics, and traces over
- * OTLP/HTTP.
+ * Combined OTLP/HTTP export for Effect logs, metrics, and traces.
  *
- * This module wires the signal-specific OTLP logger, metrics, and tracer
- * exporters together so an application can install full observability with a
- * single layer. It is useful for services that report to an OpenTelemetry
- * Collector, vendor OTLP endpoint, or local collector during development
- * without configuring each signal independently.
+ * This module installs the signal-specific OTLP logger, metrics exporter, and
+ * tracer exporter from one shared configuration. Use it when an application
+ * sends all three observability signals to the same OpenTelemetry Collector,
+ * vendor OTLP intake, or local development collector and should not configure
+ * each exporter separately.
  *
- * Pass `baseUrl` as the OTLP/HTTP root URL, such as `http://localhost:4318`;
- * this module appends `/v1/logs`, `/v1/metrics`, and `/v1/traces` itself.
- * Use `layerJson` or `layerProtobuf` when you want the serialization layer
- * provided for you, or use `layer` with a custom `OtlpSerialization`
- * implementation. Configure authentication with `headers`, provide resource
- * metadata explicitly or through the standard OTEL resource environment
- * variables, and tune batch size, export intervals, metric temporality, and
- * shutdown timeout for the target backend so buffered telemetry is accepted
- * and flushed before shutdown.
+ * **Mental model**
+ *
+ * `baseUrl` is the OTLP/HTTP root, such as `http://localhost:4318`. The
+ * combined layer appends `/v1/logs`, `/v1/metrics`, and `/v1/traces`, then
+ * delegates batching, resource handling, and payload construction to the
+ * signal-specific modules. `layerJson` and `layerProtobuf` provide the
+ * serialization layer; `layer` leaves `OtlpSerialization` in the requirements
+ * so callers can provide a custom encoder.
+ *
+ * **Common tasks**
+ *
+ * - Use `layerJson` for JSON OTLP/HTTP endpoints and `layerProtobuf` for
+ *   protobuf endpoints.
+ * - Pass `headers` for collector authentication or routing.
+ * - Set `resource` to define service name, service version, and additional
+ *   resource attributes.
+ * - Tune export intervals, `maxBatchSize`, `metricsTemporality`, and
+ *   `shutdownTimeout` for the target backend.
+ *
+ * **Gotchas**
+ *
+ * Do not include a signal path in `baseUrl`; this module adds the paths itself.
+ * Buffered telemetry flushes when the scoped exporters finalize, subject to
+ * `shutdownTimeout`, so long-running services should keep the layer installed
+ * for the lifetime of the runtime.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpLogger.ts

@@ -1,20 +1,36 @@
 /**
- * Exports Effect log records to an OpenTelemetry Protocol (OTLP) logs endpoint.
+ * OTLP/HTTP log exporter for Effect's logging system.
  *
- * Use this module to send Effect log messages, annotations, fiber identifiers,
- * causes, and active span identifiers to an OpenTelemetry Collector or OTLP
- * compatible observability backend. `make` is useful for custom logger wiring,
- * while `layer` installs the logger for an application and can merge it with
- * any existing loggers.
+ * This module turns Effect log entries into OTLP log records and sends them to
+ * a logs endpoint such as an OpenTelemetry Collector or vendor OTLP intake. It
+ * is the signal-specific logger used by the higher-level `Otlp` module when an
+ * application wants logs, metrics, and traces configured together.
  *
- * Records are buffered by the shared OTLP exporter. `exportInterval`,
- * `maxBatchSize`, and `shutdownTimeout` control periodic exports, early batch
- * flushes, and how long scope finalization waits for the final flush. Resource
- * options are attached to every export and override OpenTelemetry resource
- * environment variables, so ensure a `service.name` is available through the
- * options, `OTEL_RESOURCE_ATTRIBUTES`, or `OTEL_SERVICE_NAME`; use `headers`
- * for collector authentication and `excludeLogSpans` when log span duration
- * attributes would be too noisy.
+ * **Mental model**
+ *
+ * Each call to Effect logging APIs becomes one OTLP log record. The logger
+ * serializes the message body, severity, timestamp, fiber id, log annotations,
+ * failure cause, and current trace/span identifiers. Active log spans are
+ * exported as duration attributes named `logSpan.<label>` unless
+ * `excludeLogSpans` is enabled.
+ *
+ * **Common tasks**
+ *
+ * - Use `layer` to install the logger in an application; it merges with
+ *   existing loggers by default.
+ * - Use `make` when composing a custom `Logger` or logger layer manually.
+ * - Pass the concrete `/v1/logs` endpoint, or use `Otlp` when a shared
+ *   `baseUrl` should construct all signal paths.
+ * - Provide `headers` for collector authentication or routing, and choose an
+ *   `OtlpSerialization` layer accepted by the endpoint.
+ *
+ * **Gotchas**
+ *
+ * Batches are flushed on `exportInterval`, when `maxBatchSize` is reached, and
+ * during scope finalization up to `shutdownTimeout`. Resource options are
+ * attached to every export and override OpenTelemetry resource environment
+ * variables, so ensure a stable `service.name` is available through options,
+ * `OTEL_RESOURCE_ATTRIBUTES`, or `OTEL_SERVICE_NAME`.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpResource.ts

@@ -1,22 +1,40 @@
 /**
- * Helpers and data types for describing the OTLP resource attached to exported
- * logs, metrics, and traces.
+ * OTLP resource metadata for logs, metrics, and traces exported by Effect.
  *
- * A resource identifies the service that produced telemetry and carries
- * process- or deployment-level attributes that should be shared across every
- * signal sent by the Effect OTLP logger, metrics exporter, and tracer. Use this
- * module when building explicit resource metadata, reading the standard OTEL
- * resource environment variables, or converting application metadata into OTLP
- * `KeyValue` / `AnyValue` shapes before serialization.
+ * This module builds the resource object attached to every OTLP signal sent by
+ * the Effect observability exporters. A resource carries service identity such
+ * as `service.name` and `service.version`, plus process, host, deployment, or
+ * application attributes that should be shared by all exported telemetry.
+ *
+ * **Mental model**
+ *
+ * A {@link Resource} is the OTLP envelope for service-level metadata. Use
+ * {@link make} when the service metadata is already known, or use
+ * {@link fromConfig} when explicit options should be merged with standard
+ * OpenTelemetry environment variables before export. Attribute helpers convert
+ * JavaScript values into OTLP {@link KeyValue} and {@link AnyValue} structures
+ * used by JSON and protobuf serialization.
+ *
+ * **Common tasks**
+ *
+ * - Create explicit resource metadata with {@link make}.
+ * - Read `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, and
+ *   `OTEL_SERVICE_VERSION` with {@link fromConfig}.
+ * - Convert custom attribute records with {@link entriesToAttributes}.
+ * - Convert individual runtime values with {@link unknownToAttributeValue}.
+ *
+ * **Gotchas**
  *
  * `service.name` is required because the signal exporters also use it as the
- * instrumentation scope name. Explicit resource options take precedence over
- * `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, and
- * `OTEL_SERVICE_VERSION`; `service.name` and `service.version` are normalized
- * through the service metadata inputs and re-added as canonical OTLP
- * attributes rather than left in the custom attribute map. Attribute values are
- * converted to OTLP scalar or array values where possible, with unsupported
- * runtime values formatted as strings.
+ * instrumentation scope name. Explicit options take precedence over
+ * environment variables. `service.name` and `service.version` are normalized
+ * into canonical OTLP attributes instead of being left in the custom attribute
+ * map. Unsupported runtime values are formatted as strings.
+ *
+ * **See also**
+ *
+ * {@link Resource}, {@link make}, {@link fromConfig},
+ * {@link unknownToAttributeValue}.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpSerialization.ts

@@ -1,20 +1,31 @@
 /**
- * Defines the serialization boundary used by the OTLP observability layers.
+ * OTLP/HTTP serialization service shared by logs, metrics, and traces.
  *
- * `OtlpSerialization` converts Effect's in-memory OTLP trace, metric, and log
- * data into `HttpBody` values so exporters can send them to collectors over
- * OTLP/HTTP. Use this module to choose between the JSON encoding that is useful
- * for debugging and collector endpoints that explicitly accept OTLP/HTTP JSON,
- * and the protobuf encoding commonly expected by production OpenTelemetry
- * collectors.
+ * This module decides how in-memory OTLP payloads become HTTP request bodies.
+ * The signal exporters build trace, metric, and log data structures, then call
+ * `OtlpSerialization` immediately before posting them to a collector.
  *
- * The JSON layer writes the telemetry structures directly with
- * `HttpBody.jsonUnsafe`; the protobuf layer encodes the same structures with
- * the internal OTLP protobuf encoder and sets the `application/x-protobuf`
- * content type. Endpoint paths, authentication headers, batching, retries, and
- * shutdown flushing are handled by the OTLP exporter layers that consume this
- * service, while this module focuses only on preserving the wire format chosen
- * for traces, metrics, and logs.
+ * **Mental model**
+ *
+ * `OtlpSerialization` has one encoder per OTLP signal. `layerJson` writes the
+ * structures directly with `HttpBody.jsonUnsafe`, which is useful for debugging
+ * or endpoints that explicitly accept OTLP/HTTP JSON. `layerProtobuf` encodes
+ * the same structures with the internal OTLP protobuf encoder and sets the
+ * `application/x-protobuf` content type expected by many production collectors.
+ *
+ * **Common tasks**
+ *
+ * - Provide `layerProtobuf` for collectors that expect binary OTLP payloads.
+ * - Provide `layerJson` when inspecting payloads or using an OTLP/HTTP JSON
+ *   endpoint.
+ * - Provide a custom `OtlpSerialization` service only when an exporter needs a
+ *   non-standard body format.
+ *
+ * **Gotchas**
+ *
+ * This module only controls the wire format for traces, metrics, and logs.
+ * Endpoint paths, authentication headers, batching, retries, and shutdown
+ * flushing are handled by the OTLP exporter layers that consume the service.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/PrometheusMetrics.ts

@@ -143,7 +143,7 @@ export const format: (options?: FormatOptions | undefined) => Effect.Effect<stri
  *
  * **When to use**
  *
- * Use this low-level function when you already have access to the context. Most
+ * Use when you use this low-level function when you already have access to the context. Most
  * users should use `format` instead.
  *
  * @category Formatting

package/src/unstable/observability/index.ts

@@ -5,224 +5,41 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * Convenience layers for exporting Effect logs, metrics, and traces over
- * OTLP/HTTP.
- *
- * This module wires the signal-specific OTLP logger, metrics, and tracer
- * exporters together so an application can install full observability with a
- * single layer. It is useful for services that report to an OpenTelemetry
- * Collector, vendor OTLP endpoint, or local collector during development
- * without configuring each signal independently.
- *
- * Pass `baseUrl` as the OTLP/HTTP root URL, such as `http://localhost:4318`;
- * this module appends `/v1/logs`, `/v1/metrics`, and `/v1/traces` itself.
- * Use `layerJson` or `layerProtobuf` when you want the serialization layer
- * provided for you, or use `layer` with a custom `OtlpSerialization`
- * implementation. Configure authentication with `headers`, provide resource
- * metadata explicitly or through the standard OTEL resource environment
- * variables, and tune batch size, export intervals, metric temporality, and
- * shutdown timeout for the target backend so buffered telemetry is accepted
- * and flushed before shutdown.
- *
  * @since 4.0.0
  */
 export * as Otlp from "./Otlp.ts"
 
 /**
- * Low-level OTLP/HTTP batch exporter used by the observability modules for
- * logs, metrics, and traces.
- *
- * This module owns the scoped transport loop for already-encoded telemetry
- * payloads: callers provide the OTLP endpoint, request headers, a body encoder,
- * and batching settings, then push records that should be delivered to a
- * collector. It is useful when implementing a concrete signal exporter, such
- * as the OTLP logger or tracer, or when wiring a snapshot-based exporter like
- * metrics into the same lifecycle and retry behavior.
- *
- * The exporter sends HTTP POST requests with the provided `HttpClient`, disables
- * tracer propagation for its own traffic, retries transient failures, and
- * honors numeric `retry-after` values on 429 responses. Exports run on
- * `exportInterval`, flush during scope finalization up to `shutdownTimeout`,
- * and can also be triggered early when the buffered item count reaches
- * `maxBatchSize`.
- *
- * Use `maxBatchSize: "disabled"` only for pull-style exporters whose `body`
- * callback builds a fresh payload without relying on drained buffered items,
- * because pushed data is not cleared in that mode. After an unrecovered export
- * failure the exporter drops the buffered batch and disables exporting for 60
- * seconds, so choose intervals, batch sizes, headers, and shutdown timeouts with
- * collector limits and process shutdown behavior in mind.
- *
  * @since 4.0.0
  */
 export * as OtlpExporter from "./OtlpExporter.ts"
 
 /**
- * Exports Effect log records to an OpenTelemetry Protocol (OTLP) logs endpoint.
- *
- * Use this module to send Effect log messages, annotations, fiber identifiers,
- * causes, and active span identifiers to an OpenTelemetry Collector or OTLP
- * compatible observability backend. `make` is useful for custom logger wiring,
- * while `layer` installs the logger for an application and can merge it with
- * any existing loggers.
- *
- * Records are buffered by the shared OTLP exporter. `exportInterval`,
- * `maxBatchSize`, and `shutdownTimeout` control periodic exports, early batch
- * flushes, and how long scope finalization waits for the final flush. Resource
- * options are attached to every export and override OpenTelemetry resource
- * environment variables, so ensure a `service.name` is available through the
- * options, `OTEL_RESOURCE_ATTRIBUTES`, or `OTEL_SERVICE_NAME`; use `headers`
- * for collector authentication and `excludeLogSpans` when log span duration
- * attributes would be too noisy.
- *
  * @since 4.0.0
  */
 export * as OtlpLogger from "./OtlpLogger.ts"
 
 /**
- * OTLP/HTTP metrics exporter for Effect's Metric system.
- *
- * This module periodically snapshots the metrics registered in the current
- * Effect context, serializes them as OTLP resource metrics, and posts them to a
- * metrics endpoint such as an OpenTelemetry Collector or vendor OTLP intake.
- * It is typically installed with `layer` in long-running services that already
- * update `Metric` counters, gauges, histograms, frequencies, or summaries and
- * need those values exported without adding instrumentation-specific plumbing
- * to the application code.
- *
- * Pass the concrete `/v1/metrics` endpoint to `make` or `layer`, or use the
- * higher-level `Otlp` module when you want `baseUrl` path construction for all
- * signals. The exporter requires an `HttpClient` and an `OtlpSerialization`
- * implementation, takes resource metadata from explicit options or standard
- * OTEL resource environment variables, and uses the resource `service.name` as
- * the instrumentation scope name. Choose `temporality` for the target backend:
- * cumulative is the default, while delta derives per-export changes from the
- * previous snapshot. Gauges always report their current value, and delta
- * histograms and summaries keep interval counts and sums from previous
- * snapshots, so tune export intervals and shutdown timeouts with backend
- * expectations and process shutdown behavior in mind.
- *
  * @since 4.0.0
  */
 export * as OtlpMetrics from "./OtlpMetrics.ts"
 
 /**
- * Helpers and data types for describing the OTLP resource attached to exported
- * logs, metrics, and traces.
- *
- * A resource identifies the service that produced telemetry and carries
- * process- or deployment-level attributes that should be shared across every
- * signal sent by the Effect OTLP logger, metrics exporter, and tracer. Use this
- * module when building explicit resource metadata, reading the standard OTEL
- * resource environment variables, or converting application metadata into OTLP
- * `KeyValue` / `AnyValue` shapes before serialization.
- *
- * `service.name` is required because the signal exporters also use it as the
- * instrumentation scope name. Explicit resource options take precedence over
- * `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, and
- * `OTEL_SERVICE_VERSION`; `service.name` and `service.version` are normalized
- * through the service metadata inputs and re-added as canonical OTLP
- * attributes rather than left in the custom attribute map. Attribute values are
- * converted to OTLP scalar or array values where possible, with unsupported
- * runtime values formatted as strings.
- *
  * @since 4.0.0
  */
 export * as OtlpResource from "./OtlpResource.ts"
 
 /**
- * Defines the serialization boundary used by the OTLP observability layers.
- *
- * `OtlpSerialization` converts Effect's in-memory OTLP trace, metric, and log
- * data into `HttpBody` values so exporters can send them to collectors over
- * OTLP/HTTP. Use this module to choose between the JSON encoding that is useful
- * for debugging and collector endpoints that explicitly accept OTLP/HTTP JSON,
- * and the protobuf encoding commonly expected by production OpenTelemetry
- * collectors.
- *
- * The JSON layer writes the telemetry structures directly with
- * `HttpBody.jsonUnsafe`; the protobuf layer encodes the same structures with
- * the internal OTLP protobuf encoder and sets the `application/x-protobuf`
- * content type. Endpoint paths, authentication headers, batching, retries, and
- * shutdown flushing are handled by the OTLP exporter layers that consume this
- * service, while this module focuses only on preserving the wire format chosen
- * for traces, metrics, and logs.
- *
  * @since 4.0.0
  */
 export * as OtlpSerialization from "./OtlpSerialization.ts"
 
 /**
- * Exports Effect spans to an OpenTelemetry Protocol (OTLP) traces endpoint.
- *
- * This module creates a `Tracer.Tracer` backed by the shared OTLP/HTTP batch
- * exporter, so Effect spans created with tracing APIs can be delivered to an
- * OpenTelemetry Collector, vendor OTLP intake, or local development collector.
- * Use `make` when you need to install the tracer manually, or `layer` when an
- * application should provide it through the Effect environment.
- *
- * Pass a concrete traces endpoint, typically `/v1/traces`, or use the
- * higher-level `Otlp` module when you want `baseUrl` path construction for all
- * observability signals. The tracer exports only ended sampled spans, converts
- * span attributes, events, links, status, parent identifiers, and failure
- * causes into OTLP trace data, and groups every batch under the configured
- * resource. Resource options are resolved through `OtlpResource`, so ensure a
- * stable `service.name` is available through options or standard OTEL resource
- * environment variables because it is also used as the instrumentation scope
- * name. Tune `exportInterval`, `maxBatchSize`, and `shutdownTimeout` for the
- * target backend and process shutdown behavior, provide `headers` for
- * authentication or routing, choose an `OtlpSerialization` layer accepted by
- * the endpoint, and use `context` only when a backend needs custom evaluation
- * around the active span.
- *
  * @since 4.0.0
  */
 export * as OtlpTracer from "./OtlpTracer.ts"
 
 /**
- * Prometheus metrics exporter for Effect's Metric system.
- *
- * This module snapshots the metrics registered in the current Effect context
- * and renders them in the Prometheus text exposition format. It is intended for
- * services that already record `Metric` counters, gauges, histograms,
- * frequencies, or summaries and need a pull-based `/metrics` endpoint, or for
- * integrations that want the formatted scrape body for a custom HTTP server.
- *
- * Use `format` when you need the current runtime's registry rendered as a
- * string, `formatUnsafe` when you already have the `Context`, and `layerHttp`
- * when an `HttpRouter` should serve `GET /metrics` directly. Formatting happens
- * at scrape time; the module does not push metrics, schedule exports, or start
- * an HTTP server on its own. Make sure the route is installed in the same
- * application context that records the metrics you want to expose.
- *
- * Metric and label names are sanitized for Prometheus, optional prefixes and
- * name mappers are applied before output, and metric attributes become labels.
- * Keep attributes low-cardinality, avoid relying on invalid characters being
- * preserved exactly, and configure Prometheus to scrape the route served by
- * `layerHttp` with the expected `text/plain; version=0.0.4` response.
- *
- * **Example** (Exporting Prometheus metrics)
- *
- * ```ts
- * import { Effect, Metric } from "effect"
- * import { PrometheusMetrics } from "effect/unstable/observability"
- *
- * const program = Effect.gen(function*() {
- *   // Create and update metrics
- *   const counter = Metric.counter("http_requests_total", {
- *     description: "Total HTTP requests"
- *   })
- *   yield* Metric.update(counter, 42)
- *
- *   // Format metrics for Prometheus
- *   const output = yield* PrometheusMetrics.format()
- *   console.log(output)
- *   // # HELP http_requests_total Total HTTP requests
- *   // # TYPE http_requests_total counter
- *   // http_requests_total 42
- * })
- * ```
- *
  * @since 4.0.0
  */
 export * as PrometheusMetrics from "./PrometheusMetrics.ts"

package/src/unstable/persistence/KeyValueStore.ts

@@ -812,7 +812,10 @@ export const toSchemaStore = <S extends Schema.Top>(self: KeyValueStore, schema:
  * Provides a `KeyValueStore` backed by a Web `Storage` instance such as
  * `localStorage` or `sessionStorage`.
  *
- * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API
+ * **Details**
+ *
+ * This layer uses the Web Storage API:
+ * https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API
  *
  * @category layers
  * @since 4.0.0

package/src/unstable/persistence/PersistedCache.ts

@@ -1,20 +1,33 @@
 /**
- * Persistent caching for `Persistable` request keys.
+ * Combines scoped memory caching with durable persistence for `Persistable`
+ * lookup keys.
  *
- * A `PersistedCache` combines a scoped in-memory `Cache` with a named
- * `Persistence` store. It is useful for expensive or idempotent lookups such as
- * remote API calls, database reads, and request results that should be reused
- * across fibers, process restarts, or multiple workers sharing the same backing
- * store.
+ * A `PersistedCache` first checks a process-local `Cache`, then a named
+ * `Persistence` store, before running the supplied lookup. It is designed for
+ * expensive or idempotent requests whose encoded `Exit` can be reused across
+ * fibers, process restarts, or multiple workers sharing the same backing store.
  *
- * The persistent `timeToLive` is evaluated for the stored `Exit`, so successes
- * and failures can be cached with different lifetimes. The in-memory cache has
- * its own `inMemoryTTL` and capacity, and `invalidate` removes both the
- * persisted value and the in-memory entry. Persisted values are encoded with
- * the key's success and error schemas and stored under the key's primary key, so
- * schema changes, primary-key changes, or store-id collisions can make old
- * entries fail to decode until they are invalidated or written under a new
- * `storeId`.
+ * **Mental model**
+ *
+ * `make` creates a scoped cache backed by a scoped persistence store. The memory
+ * cache controls repeated reads inside the current runtime with `inMemoryTTL`
+ * and capacity, while the persistence store controls durable reuse with
+ * `timeToLive`, `storeId`, and request primary keys. Both successes and failures
+ * are stored as `Exit` values when the persistent TTL allows the write.
+ *
+ * **Common tasks**
+ *
+ * Use `get` for lookups that should reuse memory and persisted values, and use
+ * `invalidate` when the underlying data changes so both layers forget the key.
+ * Use `requireServicesAt` to choose whether lookup services are supplied when
+ * constructing the cache or when reading from it.
+ *
+ * **Gotchas**
+ *
+ * Persisted entries are decoded with the key's success and error schemas.
+ * Changing schemas, primary-key formats, or `storeId` values is a persistence
+ * migration; old entries can stop being found or fail to decode. `invalidate`
+ * removes the persisted value first and then the in-memory entry.
  *
  * @since 4.0.0
  */

package/src/unstable/persistence/Redis.ts

@@ -1,19 +1,37 @@
 /**
- * Low-level Redis integration for the persistence modules.
- *
- * This module defines the `Redis` service used by Redis-backed persistence,
- * persisted queues, and rate limiter stores. It adapts an external Redis
- * connection to Effect through `send` for raw commands and `eval` for typed
- * Lua scripts that are loaded with `SCRIPT LOAD` and executed with `EVALSHA`.
- *
- * The service does not create or manage Redis connections; callers provide a
- * command sender from their Redis client or pool. Higher-level stores layer on
- * key prefixes and store ids, so choose stable prefixes to avoid collisions
- * and remember that schema or primary-key changes can make previously persisted
- * JSON values fail to decode. Finite TTLs in the persistence stores are applied
- * with millisecond Redis expirations, while non-finite TTLs are stored without
- * expiration. Script parameters are stringified before execution, and the
- * script descriptor's key count controls how Redis splits `KEYS` from `ARGV`.
+ * Redis service adapter for Effect persistence modules.
+ *
+ * This module defines the low-level {@link Redis} service used by Redis-backed
+ * persistence, persisted queues, and rate limiter stores. It adapts a Redis
+ * client or pool into Effect through a raw `send` command function and cached
+ * Lua script execution.
+ *
+ * **Mental model**
+ *
+ * The service does not create or own Redis connections. {@link make} wraps a
+ * caller-provided command sender, while {@link script} describes a Lua script's
+ * source, parameters, key count, and result type. The service loads scripts
+ * with `SCRIPT LOAD`, caches the returned SHA, and runs them with `EVALSHA`
+ * through `Redis.eval`.
+ *
+ * **Common tasks**
+ *
+ * - Wrap an existing Redis client by implementing `send`.
+ * - Use `Redis.send` for ordinary Redis commands.
+ * - Use {@link script} for typed Lua helpers shared by persistence stores.
+ * - Map client or network failures into {@link RedisError} in the provided
+ *   command sender.
+ *
+ * **Gotchas**
+ *
+ * Script parameters are stringified before execution. The script descriptor's
+ * key count controls how Redis splits `KEYS` from `ARGV`. Higher-level stores
+ * add key prefixes and store ids on top of this service, so those identifiers
+ * must stay stable when persisted data is expected to survive deployments.
+ *
+ * **See also**
+ *
+ * {@link Redis}, {@link make}, {@link script}, {@link RedisError}.
  *
  * @since 4.0.0
  */