effect 4.0.0-beta.77 → 4.0.0-beta.79

package/src/unstable/observability/Otlp.ts

@@ -1,37 +1,10 @@
 /**
- * Combined OTLP/HTTP export for Effect logs, metrics, and traces.
+ * Configures OpenTelemetry Protocol (OTLP) HTTP export for Effect telemetry.
  *
- * 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.
- *
- * **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.
+ * This module installs the OTLP logger, metrics exporter, and tracer exporter
+ * from one shared configuration. Use it when an application sends logs, metrics,
+ * and traces to the same OpenTelemetry Collector, vendor OTLP endpoint, or local
+ * development collector.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpExporter.ts

@@ -1,27 +1,10 @@
 /**
- * Low-level OTLP/HTTP batch exporter used by the observability modules for
- * logs, metrics, and traces.
+ * Shared batch exporter for OTLP/HTTP observability modules.
  *
- * 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.
+ * Signal modules use this exporter to buffer already-encoded telemetry and post
+ * it to a configured OTLP endpoint. It owns the scoped transport loop, batching,
+ * retry behavior, temporary disabling after repeated failures, and final flush
+ * during shutdown.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpLogger.ts

@@ -1,36 +1,10 @@
 /**
- * OTLP/HTTP log exporter for Effect's logging system.
+ * Exports Effect log entries over OTLP/HTTP.
  *
- * 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.
- *
- * **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`.
+ * The logger turns Effect log entries into OTLP log records and sends them to a
+ * logs endpoint, such as an OpenTelemetry Collector or vendor OTLP endpoint. It
+ * includes log levels, messages, annotations, causes, fiber ids, optional log
+ * spans, and current trace/span ids when they are present.
  *
  * @since 4.0.0
  */
@@ -188,7 +162,7 @@ export const layerFromConfig = (options?: {
     const exportInterval = Option.map(scheduleDelay, (_) => Duration.millis(_))
 
     return layer({
-      url: endpoint,
+      url: endpoint.toString(),
       resource: options?.resource,
       headers: options?.headers ?? (yield* OtlpEnv.headers("LOGS")),
       exportInterval: Option.getOrUndefined(exportInterval),

package/src/unstable/observability/OtlpMetrics.ts

@@ -1,25 +1,13 @@
 /**
- * OTLP/HTTP metrics exporter for Effect's Metric system.
+ * Exports Effect metrics over OTLP/HTTP.
  *
- * 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.
+ * This module periodically snapshots metrics from the current Effect context,
+ * serializes them as OTLP resource metrics, and posts them to a metrics
+ * endpoint such as an OpenTelemetry Collector or vendor intake. It is meant for
+ * long-running services that already update `Metric` counters, gauges,
+ * histograms, frequencies, or summaries. The exporter supports cumulative
+ * reporting from a fixed start time and delta reporting from the previous
+ * export.
  *
  * @since 4.0.0
  */
@@ -506,7 +494,11 @@ export const layerFromConfig = (options?: {
       baseTimeout: Config.option(Config.int("OTEL_EXPORTER_OTLP_TIMEOUT")),
       metricsTimeout: Config.option(Config.int("OTEL_EXPORTER_OTLP_METRICS_TIMEOUT")),
       exportTimeout: Config.option(Config.int("OTEL_METRIC_EXPORT_TIMEOUT")),
-      exportInterval: Config.option(Config.int("OTEL_METRIC_EXPORT_INTERVAL")),
+      exportInterval: Config.option(
+        Config.int("OTEL_METRIC_EXPORT_INTERVAL").pipe(
+          Config.map(Duration.millis)
+        )
+      ),
       temporalityPreference: Config.option(
         Config.literals(["delta", "cumulative"], "OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE")
       )
@@ -517,10 +509,10 @@ export const layerFromConfig = (options?: {
     )
 
     return layer({
-      url: endpoint,
+      url: endpoint.toString(),
       resource: options?.resource,
       headers: options?.headers ?? (yield* OtlpEnv.headers("METRICS")),
-      exportInterval: Option.getOrUndefined(Option.map(exportInterval, (_) => Duration.millis(_))),
+      exportInterval: Option.getOrUndefined(exportInterval),
       shutdownTimeout: Option.getOrUndefined(shutdownTimeout),
       temporality: Option.getOrUndefined(temporalityPreference)
     })

package/src/unstable/observability/OtlpResource.ts

@@ -1,40 +1,10 @@
 /**
- * OTLP resource metadata for logs, metrics, and traces exported by Effect.
+ * Builds OTLP resource metadata shared by exported telemetry.
  *
- * 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. OpenTelemetry environment variables take
- * precedence over explicit options. `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}.
+ * An OTLP resource describes the service and other attributes attached to every
+ * exported log, metric, or trace. This module builds resources from explicit
+ * options or OpenTelemetry environment variables and converts JavaScript values
+ * into OTLP attribute values.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpSerialization.ts

@@ -1,31 +1,9 @@
 /**
- * OTLP/HTTP serialization service shared by logs, metrics, and traces.
+ * Serializes OTLP payloads into HTTP request bodies.
  *
- * 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.
- *
- * **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.
+ * Signal exporters build trace, metric, and log data structures in memory. This
+ * module provides the service that turns those structures into JSON or protobuf
+ * HTTP bodies before they are posted to an OTLP collector.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpTracer.ts

@@ -1,25 +1,12 @@
 /**
- * Exports Effect spans to an OpenTelemetry Protocol (OTLP) traces endpoint.
+ * Exports Effect tracing spans over OTLP/HTTP.
  *
- * 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.
+ * This module creates a `Tracer.Tracer` backed by the shared OTLP batch
+ * exporter, so spans created by Effect tracing APIs can be sent to an
+ * OpenTelemetry Collector, vendor endpoint, or local collector. Exported spans
+ * include identifiers, parent links, attributes, events, timing, kind, and
+ * status information. Use the constructor directly or install it through the
+ * provided layer.
  *
  * @since 4.0.0
  */
@@ -179,20 +166,23 @@ export const layerFromConfig = (options?: {
       baseTimeout: Config.option(Config.int("OTEL_EXPORTER_OTLP_TIMEOUT")),
       tracesTimeout: Config.option(Config.int("OTEL_EXPORTER_OTLP_TRACES_TIMEOUT")),
       exportTimeout: Config.option(Config.int("OTEL_BSP_EXPORT_TIMEOUT")),
-      scheduleDelay: Config.option(Config.int("OTEL_BSP_SCHEDULE_DELAY")),
+      scheduleDelay: Config.option(
+        Config.int("OTEL_BSP_SCHEDULE_DELAY").pipe(
+          Config.map(Duration.millis)
+        )
+      ),
       maxBatchSize: Config.option(Config.int("OTEL_BSP_MAX_EXPORT_BATCH_SIZE"))
     })
 
     const shutdownTimeout = Option.firstSomeOf([tracesTimeout, baseTimeout, exportTimeout]).pipe(
       Option.map((_) => Duration.millis(_))
     )
-    const exportInterval = Option.map(scheduleDelay, (_) => Duration.millis(_))
 
     return layer({
-      url: endpoint,
+      url: endpoint.toString(),
       resource: options?.resource,
       headers: options?.headers ?? (yield* OtlpEnv.headers("TRACES")),
-      exportInterval: Option.getOrUndefined(exportInterval),
+      exportInterval: Option.getOrUndefined(scheduleDelay),
       maxBatchSize: Option.getOrUndefined(maxBatchSize),
       context: options?.context,
       shutdownTimeout: Option.getOrUndefined(shutdownTimeout)

package/src/unstable/observability/PrometheusMetrics.ts

@@ -1,46 +1,9 @@
 /**
- * Prometheus metrics exporter for Effect's Metric system.
+ * Formats Effect metrics for Prometheus.
  *
- * 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
- * })
- * ```
+ * This module reads metrics from the current Effect context and renders them in
+ * the Prometheus text format. It can also register a pull-based HTTP endpoint,
+ * such as `/metrics`, for Prometheus to scrape.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/internal/otlpEnv.ts

@@ -1,21 +1,12 @@
 import * as Config from "../../../Config.ts"
-import * as Effect from "../../../Effect.ts"
-import * as Option from "../../../Option.ts"
 import * as Schema from "../../../Schema.ts"
 import * as SchemaGetter from "../../../SchemaGetter.ts"
-import * as SchemaTransformation from "../../../SchemaTransformation.ts"
-import * as HttpClientRequest from "../../http/HttpClientRequest.ts"
 
 export type Signal = "LOGS" | "METRICS" | "TRACES"
 
-const ExporterList = Config.Array(
-  Schema.String.pipe(
-    Schema.decode(SchemaTransformation.trim()),
-    Schema.decode(SchemaTransformation.toLowerCase())
-  )
-).pipe(
+const ExporterList = Config.Array(Schema.String).pipe(
   Schema.decode({
-    decode: SchemaGetter.transform((_: ReadonlyArray<string>) => _.filter((_) => _ !== "")),
+    decode: SchemaGetter.transform((_) => _.map((_) => _.toLowerCase().trim()).filter((_) => _ !== "")),
     encode: SchemaGetter.passthrough()
   })
 )
@@ -23,36 +14,26 @@ const ExporterList = Config.Array(
 const HeadersRecord = Config.Record(Schema.String, Schema.String)
 
 export const headers = (signal: Signal) =>
-  Config.make((provider) =>
-    Effect.gen(function*() {
-      const headers = yield* Config.option(Config.schema(HeadersRecord, `OTEL_EXPORTER_OTLP_${signal}_HEADERS`)).parse(
-        provider
-      )
-      if (Option.isSome(headers)) {
-        return headers.value
-      }
-
-      const fallback = yield* Config.option(Config.schema(HeadersRecord, "OTEL_EXPORTER_OTLP_HEADERS")).parse(provider)
-      return Option.getOrUndefined(fallback)
-    })
+  Config.schema(HeadersRecord, `OTEL_EXPORTER_OTLP_${signal}_HEADERS`).pipe(
+    Config.orElse(() => Config.schema(HeadersRecord, "OTEL_EXPORTER_OTLP_HEADERS")),
+    Config.withDefault(undefined)
   )
 
 export const endpoint = (signal: Signal) =>
-  Config.make((provider) =>
-    Effect.gen(function*() {
-      const endpoint = yield* Config.option(Config.string(`OTEL_EXPORTER_OTLP_${signal}_ENDPOINT`)).parse(provider)
-      if (Option.isSome(endpoint)) {
-        return endpoint.value
-      }
-
-      const fallback = yield* Config.option(Config.string("OTEL_EXPORTER_OTLP_ENDPOINT")).parse(provider)
-      return Option.isSome(fallback) && fallback.value !== ""
-        ? HttpClientRequest.appendUrl(HttpClientRequest.get(fallback.value), `/v1/${signal.toLowerCase()}`).url
-        : undefined
-    })
+  Config.url(`OTEL_EXPORTER_OTLP_${signal}_ENDPOINT`).pipe(
+    Config.orElse(() =>
+      Config.url("OTEL_EXPORTER_OTLP_ENDPOINT").pipe(
+        Config.map((url) => {
+          const slash = url.pathname.endsWith("/") ? "" : "/"
+          url.pathname += `${slash}v1/${signal.toLowerCase()}`
+          return url
+        })
+      )
+    ),
+    Config.withDefault(undefined)
   )
 
 export const exporters = (signal: Signal) =>
-  Config.option(Config.schema(ExporterList, `OTEL_${signal}_EXPORTER`)).pipe(
-    Config.map(Option.getOrElse<ReadonlyArray<string>>(() => []))
+  Config.schema(ExporterList, `OTEL_${signal}_EXPORTER`).pipe(
+    Config.withDefault<ReadonlyArray<string>>([])
   )

package/src/unstable/persistence/KeyValueStore.ts

@@ -1,24 +1,12 @@
 /**
- * Effectful key/value storage for persistence backends.
- *
- * This module defines the `KeyValueStore` service used by the persistence
- * package when a simple string or binary store is enough. It is useful for
- * lightweight durable state, browser storage, local file-backed data, SQL
- * tables, test stores, and as the storage primitive underneath higher-level
- * persistence APIs.
- *
- * Values are stored as strings or `Uint8Array`s, and `toSchemaStore` adds a
- * schema-aware JSON layer for typed values. Schema changes can make existing
- * JSON fail to decode, and `prefix` should be used to separate namespaces when
- * several logical stores share the same backend. This service does not provide
- * native TTL support; higher-level persistence layers encode expiration
- * metadata in stored values when they need TTLs.
- *
- * Backend behavior is intentionally small but not identical: Web Storage is
- * string-only, `makeStringOnly` stores binary values as base64, filesystem
- * keys become encoded file names, SQL stores value type metadata in a table,
- * and the memory layer is process-local. Choose keys, prefixes, table names,
- * and value formats with those backend constraints in mind.
+ * Provides effectful key/value storage for persistence backends.
+ *
+ * `KeyValueStore` is a service for storing string or binary values by key. It
+ * is useful for lightweight durable state, browser storage, local files, SQL
+ * tables, tests, and as a storage building block for higher-level persistence
+ * APIs. This module includes store operations, prefixed views, schema-aware JSON
+ * storage, error values, and layers for memory, filesystem, Web Storage, and
+ * SQL-backed stores.
  *
  * @since 4.0.0
  */

package/src/unstable/persistence/Persistable.ts

@@ -1,23 +1,9 @@
 /**
- * Defines the request-side contract used by the persistence layer.
+ * Describes request values whose results can be persisted.
  *
- * A `Persistable` request is a `PrimaryKey` value that carries the success and
- * error schemas needed to encode and decode the stored `Exit` for that request.
- * Persisted request resolvers and `PersistedCache` use this metadata to restore
- * previous lookup results from a backing store before running the lookup again.
- *
- * Use `Class` for cacheable or durable requests whose results can safely be
- * reused across fibers, processes, or restarts. The request primary key is the
- * entry id inside a persistence store, so it should be stable, collision-free,
- * and usually include a request-specific prefix. The `storeId` is configured on
- * `Persistence` or `PersistedCache`; it selects the backing store namespace and
- * is separate from the request primary key.
- *
- * Success and error schemas are encoded with the JSON codec, so persisted
- * values must be representable by those schemas and any required schema services
- * must be available where the store reads or writes entries. Changing a schema,
- * primary-key format, or store id can make existing persisted values fail to
- * decode or stop being found, so treat those changes as persistence migrations.
+ * A `Persistable` request has a primary key and schemas for its success and
+ * error results. `Persistence` and `PersistedCache` use that information to
+ * store the request's `Exit` value and restore it later from a backing store.
  *
  * @since 4.0.0
  */

package/src/unstable/persistence/PersistedCache.ts

@@ -1,33 +1,10 @@
 /**
- * Combines scoped memory caching with durable persistence for `Persistable`
- * lookup keys.
+ * Combines in-memory caching with durable storage for `Persistable` requests.
  *
- * 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.
- *
- * **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.
+ * A `PersistedCache` checks a process-local `Cache`, then a named `Persistence`
+ * store, before running the supplied lookup. It stores the lookup `Exit`, so
+ * expensive or idempotent results can be reused across fibers, process restarts,
+ * or workers that share the same backing store.
  *
  * @since 4.0.0
  */

package/src/unstable/persistence/PersistedQueue.ts

@@ -1,28 +1,12 @@
 /**
- * Schema-aware persisted queues for background work.
+ * Stores schema-encoded queue work in persistent storage.
  *
- * A `PersistedQueue` stores JSON-encoded values in a named queue and lets
- * workers `take` one value at a time inside a scoped processing window. It is
+ * A `PersistedQueue<A>` keeps JSON-encoded values in a named queue and lets
+ * workers take one value at a time inside a scoped processing window. It is
  * useful for durable handoffs, background jobs, outbox-style integrations, and
- * workloads where failed work should be retried across fibers, process
- * restarts, or multiple workers sharing Redis or SQL.
- *
- * Delivery is at-least-once: a handler that fails, is interrupted, or loses its
- * backing-store lock may see the same element again until `maxAttempts` is
- * reached. Use stable custom ids when offering idempotent work, and choose ids
- * that are collision-free for the backing store because stores can enforce
- * uniqueness at the queue, prefix, or table level. Ordering is intentionally a
- * store-level concern; retries, lock expiration, polling, and multiple workers
- * can move entries behind newer work, so handlers should not rely on strict
- * FIFO processing.
- *
- * Values are encoded and decoded with the supplied schema using the JSON codec,
- * so schema services must be available when offering and taking values. Changing
- * a queue name, schema, Redis prefix, SQL table, or id format is a persistence
- * migration: old entries may decode differently, stop being visible, or collide
- * with new entries. The memory store is process-local and volatile, while Redis
- * and SQL stores use leases that should be tuned for the expected processing
- * time.
+ * work that should retry across fibers, process restarts, or multiple workers.
+ * This module includes a queue factory, store service, id-based de-duplication,
+ * retry handling, and in-memory, Redis, and SQL-backed store layers.
  *
  * @since 4.0.0
  */

package/src/unstable/persistence/Persistence.ts

@@ -1,26 +1,10 @@
 /**
- * Durable storage for encoded `Persistable` request results.
+ * Stores encoded results for `Persistable` requests.
  *
- * The `Persistence` service creates scoped stores that read and write
- * schema-encoded `Exit` values keyed by each request's `PrimaryKey`. It is the
- * lower-level persistence layer used by `PersistedCache` and similar request
- * workflows to reuse expensive or idempotent lookup results across fibers,
- * process restarts, and workers that share a backing store.
- *
- * Each store is selected by a `storeId`, while each entry id comes from the
- * request's primary key. Keep both stable and collision-free: changing the
- * `storeId`, the primary-key format, or the success/error schemas is a
- * persistence migration, because old entries may stop being found or fail to
- * decode. Values are encoded with the request's success and error schemas using
- * the JSON codec, so any required schema services must be available at store
- * read and write time, and the backing value must stay JSON-compatible.
- *
- * TTLs are computed from the stored `Exit` and request key. Infinite TTLs are
- * stored without an expiration, finite TTLs become backing-store expirations,
- * and zero or negative TTLs skip the write entirely. Backing layers provide
- * process-local memory, `KeyValueStore`, Redis, and SQL implementations; store
- * ids are used as prefixes, table names, or SQL partitions and should be
- * chosen with the target backing store in mind.
+ * The `Persistence` service creates scoped stores keyed by each request's
+ * `PrimaryKey`. Stores read and write schema-encoded `Exit` values with
+ * optional TTLs, letting request workflows reuse expensive or idempotent results
+ * across fibers, process restarts, or workers that share a backing store.
  *
  * @since 4.0.0
  */