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

package/src/unstable/sql/Statement.ts

@@ -1,20 +1,40 @@
 /**
- * Building blocks for Effect's unstable SQL statement API.
+ * Low-level SQL statement and fragment primitives.
  *
- * This module defines the low-level `Statement` and `Fragment` model used by
- * SQL clients, the tagged-template `Constructor` for creating executable
- * parameterized statements, and dialect compilers that turn statement segments
- * into SQL text plus bind parameters. It also provides helpers for escaped
- * identifiers, `IN` lists, comma-separated clause fragments, record inserts and
- * updates, custom segments, and row or identifier transforms.
+ * This module is the foundation used by SQL clients to build executable,
+ * parameterized SQL. It defines the {@link Statement} and {@link Fragment}
+ * models, the tagged-template {@link Constructor}, segment constructors for
+ * identifiers, parameters, literals, arrays, records, and custom dialect data,
+ * plus compilers that render those segments into dialect-specific SQL text and
+ * bind parameters.
  *
- * In tagged templates, interpolated `Fragment`s and known `Segment`s are
- * spliced into the statement, while ordinary values become bound parameters. Use
- * identifiers for table and column names and the record helpers for generated
- * column lists; `literal` and `unsafe` insert SQL text directly and should only
- * be used with trusted SQL. Compilation is dialect-specific, caches rendered SQL
- * on the statement, and has a `withoutTransform` path for bypassing identifier
- * transforms, so compiled output can differ from normal transformed execution.
+ * **Mental model**
+ *
+ * A statement is a sequence of {@link Segment} values. In a tagged template,
+ * nested fragments and known segments are spliced into that sequence, while
+ * ordinary interpolated values become bound parameters. A {@link Compiler}
+ * turns the sequence into SQL for one dialect, escaping identifiers and
+ * formatting placeholders for that dialect. Executing a {@link Statement} uses
+ * the connection acquirer captured by {@link make} and can return rows, raw
+ * results, streams, values, or unprepared execution paths.
+ *
+ * **Common tasks**
+ *
+ * - Build statements with a {@link Constructor} tagged template
+ * - Use {@link identifier} for table and column names rather than interpolating
+ *   plain strings
+ * - Compose optional clauses with {@link and}, {@link or}, {@link csv}, and
+ *   {@link join}
+ * - Create insert and update fragments with record helpers
+ * - Add custom segment handling with {@link custom} and {@link makeCompiler}
+ *
+ * **Gotchas**
+ *
+ * Bound parameters protect values, not SQL syntax. Use `literal` and `unsafe`
+ * only for trusted SQL text, and use identifiers for names that need escaping.
+ * Compiled SQL is dialect-specific and cached on the statement;
+ * `withoutTransform` intentionally bypasses identifier or row transforms, so
+ * its output can differ from normal execution.
  *
  * @since 4.0.0
  */
@@ -497,7 +517,7 @@ export interface Constructor {
    *
    * **When to use**
    *
-   * Useful for `ORDER BY` and `GROUP BY` clauses.
+   * Use when `ORDER BY` and `GROUP BY` clauses.
    */
   readonly csv: {
     (values: ReadonlyArray<string | Fragment>): Fragment

package/src/unstable/sql/index.ts

@@ -5,224 +5,46 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * Effect SQL migration helpers for loading, ordering, and running schema
- * changes against a `SqlClient`.
- *
- * This module provides a migrator constructor plus loaders for common migration
- * layouts, including dynamic glob imports, Babel-style glob records, in-memory
- * records, and filesystem directories. It is intended for applications and
- * libraries that need to apply numbered SQL migrations on startup, in tests, or
- * as part of deployment tooling while keeping migration effects inside the
- * Effect environment.
- *
- * The migrator tracks applied migrations in a configurable table, defaults that
- * table to `effect_sql_migrations`, rejects duplicate migration ids, and only
- * runs migrations with an id greater than the latest recorded id. Pending
- * migrations are recorded and executed inside a `SqlClient` transaction; on
- * PostgreSQL the migrations table is explicitly locked, while other dialects
- * rely on the table's primary key or unique constraint to detect concurrent
- * runners. Migration effects should therefore be written to be transaction-aware,
- * and callers should account for dialect-specific DDL transaction behavior and
- * custom table names when coordinating schema dumps or external migration
- * tooling.
- *
  * @since 4.0.0
  */
 export * as Migrator from "./Migrator.ts"
 
 /**
- * Defines the `SqlClient` service, the central runtime entry point for Effect's
- * unstable SQL support.
- *
- * A `SqlClient` combines the tagged-template statement constructor with a
- * scoped connection acquirer, dialect compiler, tracing attributes, optional row
- * transforms, reactive query helpers, and transaction management. Applications
- * typically consume it from `Context` to build parameterized queries, stream
- * rows, run raw driver operations, reserve a connection for lower-level work, or
- * wrap several query effects in `withTransaction`.
- *
- * Transactions are tracked through a per-client context service. Top-level
- * transactions acquire the configured transaction connection and issue the
- * dialect's begin/commit/rollback SQL; nested transactions reuse that
- * connection and rely on dialect-provided savepoint SQL. A query only joins a
- * transaction when it is run with the same client service, so avoid mixing
- * clients or manually reserved connections when atomicity matters. Dialect
- * integrations are also responsible for the compiler and transaction
- * statements, which means placeholder syntax, identifier escaping, row
- * transforms, savepoint support, and unprepared/raw statement behavior can
- * differ by database.
- *
  * @since 4.0.0
  */
 export * as SqlClient from "./SqlClient.ts"
 
 /**
- * Defines the low-level SQL connection service and shared row/acquirer types
- * used by Effect's unstable SQL driver integrations.
- *
- * A `Connection` is the driver-facing layer underneath `SqlClient`: it executes
- * already-compiled SQL with positional parameters and exposes transformed row
- * results, raw driver results, streams, value arrays, and unprepared statement
- * execution. Most applications should work through `SqlClient`, while driver
- * integrations and advanced code use this module to provide scoped connection
- * acquisition, implement pooling, reserve a connection for a workflow, or adapt
- * a dialect-specific client into Effect.
- *
- * Connections are resources and should be acquired through an `Acquirer` in a
- * `Scope` so pool checkout, transaction pinning, and release semantics are
- * preserved. Transaction coordination lives at the `SqlClient` layer, so mixing
- * manually reserved connections with transactional client queries can bypass the
- * expected atomic boundary. Raw, unprepared, streaming, parameter, and row
- * transformation behavior ultimately comes from the driver and dialect; check
- * each integration for differences in placeholders, prepared statement support,
- * cursor lifetime, and result shapes.
- *
  * @since 4.0.0
  */
 export * as SqlConnection from "./SqlConnection.ts"
 
 /**
- * Structured SQL errors used by the unstable SQL APIs.
- *
- * This module defines the top-level `SqlError` wrapper, the concrete
- * `SqlErrorReason` variants used by drivers and adapters, and helpers for
- * recognizing and classifying database failures. It is useful when turning
- * native driver errors into typed Effect failures, choosing retry policies from
- * `isRetryable`, or distinguishing user-facing query problems such as syntax
- * and constraint failures from infrastructure problems such as connection,
- * lock, statement timeout, deadlock, and serialization failures.
- *
- * Query, connection, and migration code should preserve the original cause and
- * operation metadata when constructing these errors. Retrying can be appropriate
- * for transient connection and concurrency failures, but syntax, authorization,
- * authentication, and constraint failures generally require changing the query,
- * credentials, permissions, or migration data. When classifying SQLite errors,
- * the helpers inspect `code` and `errno` values and extract unique constraint
- * names when available.
- *
  * @since 4.0.0
  */
 export * as SqlError from "./SqlError.ts"
 
 /**
- * Builds SQL repositories and request resolvers from Effect schema models.
- *
- * Use this module when a `Model` describes rows in a concrete SQL table and
- * you want the common insert, update, find-by-id, and delete operations without
- * hand-writing the schema encoding, row decoding, and resolver batching each
- * time. The helpers are intended for model-backed tables where the model field
- * names line up with the encoded table columns and the chosen `idColumn` is
- * present in both the model fields and update schema.
- *
- * Returned rows are decoded with the full model schema, while insert and update
- * requests are encoded with the model's dedicated input schemas. Soft deletes
- * are opt-in via `softDeleteColumn`: reads and updates only see rows where that
- * column is `null`, and deletes set it to `CURRENT_TIMESTAMP` instead of
- * removing the row. Dialects with `returning` support return changed rows
- * directly; MySQL performs a follow-up `select`, so generated ids, defaults,
- * and trigger-updated values must be observable from that query.
- *
  * @since 4.0.0
  */
 export * as SqlModel from "./SqlModel.ts"
 
 /**
- * Schema-aware `RequestResolver` helpers for SQL-backed data loading.
- *
- * This module bridges `Effect.request` with `SqlClient` by representing each
- * lookup or mutation as a `SqlRequest` and batching concurrent requests into a
- * single SQL operation. Request payloads are encoded with the request schema
- * before `execute` is called, and rows returned by the query are decoded with
- * the result schema before entries are completed.
- *
- * Use `ordered` when a query returns exactly one row per request in the same
- * order, `findById` for `where id in (...)` lookups, `grouped` for one-to-many
- * relationships, and `void` for inserts, updates, deletes, or other
- * side-effecting statements where no row is needed.
- *
- * **Gotchas**
- *
- * - `ordered` requires the result count and order to match the request batch.
- * - `grouped` and `findById` rely on stable request/result keys and fail
- *   missing requests with `NoSuchElementError`.
- * - Equal payloads are equal `SqlRequest`s, which enables request batching,
- *   deduplication, and cache reuse; model payload identity deliberately.
- * - Batches are split by the active SQL transaction connection, so requests
- *   made in different transactions are not resolved together.
- * - Queries like `where id in (...)` often return rows in database order; use
- *   `findById` or `grouped`, or preserve input order explicitly before choosing
- *   `ordered`.
- *
  * @since 4.0.0
  */
 export * as SqlResolver from "./SqlResolver.ts"
 
 /**
- * Schema-driven helpers for wrapping SQL executions in typed query functions.
- *
- * This module connects `Schema` request and result definitions to an `execute`
- * callback that runs the actual SQL statement. The returned functions accept
- * the request schema's decoded `Type`, encode it to the SQL-facing `Encoded`
- * shape, run the callback, and then decode unknown driver rows through the
- * result schema. This is useful for repository methods, CRUD helpers, request
- * resolvers, and write operations where callers should work with domain values
- * instead of raw SQL parameters or rows.
- *
- * The `execute` callback always receives `Req["Encoded"]`, so schema
- * transformations, required encoding services, and database representations
- * such as nullable columns, JSON values, dates, and bigints must line up with
- * the statement builder and dialect in use. Result schemas decode the rows
- * returned by the driver after any SQL client row transforms; `findOne` and
- * `findOneOption` only inspect the first row, `findNonEmpty` requires at least
- * one row, and `void` discards any driver result after request encoding.
- *
  * @since 4.0.0
  */
 export * as SqlSchema from "./SqlSchema.ts"
 
 /**
- * Low-level helpers for adapting push-based SQL row sources into Effect
- * streams.
- *
- * SQL drivers often expose large query results through cursors, event emitters,
- * or driver-specific streams that push rows as they arrive. This module
- * provides the small interop layer used by SQL integrations to turn those
- * producers into `Stream` values for `Statement.stream` and
- * `Connection.executeStream`, so callers can process large result sets
- * incrementally instead of materializing every row in memory.
- *
- * The adapter is scoped: driver cursors, query streams, or reserved
- * connections should be acquired in the registration effect and released with
- * finalizers. The internal queue is bounded and calls the producer's
- * `onPause`/`onResume` hooks when downstream consumption falls behind, but the
- * underlying driver still has to honor those hooks for backpressure to be
- * effective. Slow consumers may keep a database cursor and connection open for
- * the lifetime of the stream, so integrations should close or destroy driver
- * resources on interruption, failure, or normal completion and should signal
- * terminal events with `fail` or `end` exactly once.
- *
  * @since 4.0.0
  */
 export * as SqlStream from "./SqlStream.ts"
 
 /**
- * Building blocks for Effect's unstable SQL statement API.
- *
- * This module defines the low-level `Statement` and `Fragment` model used by
- * SQL clients, the tagged-template `Constructor` for creating executable
- * parameterized statements, and dialect compilers that turn statement segments
- * into SQL text plus bind parameters. It also provides helpers for escaped
- * identifiers, `IN` lists, comma-separated clause fragments, record inserts and
- * updates, custom segments, and row or identifier transforms.
- *
- * In tagged templates, interpolated `Fragment`s and known `Segment`s are
- * spliced into the statement, while ordinary values become bound parameters. Use
- * identifiers for table and column names and the record helpers for generated
- * column lists; `literal` and `unsafe` insert SQL text directly and should only
- * be used with trusted SQL. Compilation is dialect-specific, caches rendered SQL
- * on the statement, and has a `withoutTransform` path for bypassing identifier
- * transforms, so compiled output can differ from normal transformed execution.
- *
  * @since 4.0.0
  */
 export * as Statement from "./Statement.ts"

package/src/unstable/workers/Transferable.ts

@@ -1,19 +1,33 @@
 /**
- * Utilities for marking the parts of worker messages that should be transferred
- * through `postMessage` instead of copied by the structured clone algorithm.
- *
- * This module is used with worker message schemas to collect
- * `globalThis.Transferable` values while encoding a message, so the worker
- * platform can pass the collected list as the `postMessage` transfer list.
- * Common cases include sending large `Uint8Array` payloads, `ImageData` pixel
- * buffers, or `MessagePort` channels without paying for an extra copy.
- *
- * Transferable annotations do not make an otherwise unsupported value
- * structured-cloneable; the encoded message still has to be valid for
- * `postMessage`. Transferring also moves ownership to the receiver, so buffers
- * are detached from the sender after the send completes. Be careful when a
- * typed array view shares a backing buffer with other data, since collecting
- * that buffer transfers ownership of the whole buffer.
+ * Marks encoded worker message fields that should move through `postMessage` as
+ * transfer-list entries.
+ *
+ * Worker messages still pass through schema encoding and structured clone, but
+ * schemas wrapped with `schema` can also report backing resources such as
+ * `ArrayBuffer`, `ImageData.data.buffer`, or `MessagePort` to a `Collector`.
+ * Worker platforms then pass the collected values as the transfer list for the
+ * same `postMessage` call, avoiding copies for large payloads and ports.
+ *
+ * **Mental model**
+ *
+ * A `Collector` is an optional context service. During encoding, `getterAddAll`
+ * and `schema` add transferable values when a collector is present and leave the
+ * encoded value unchanged. The built-in `Uint8Array`, `ImageData`, and
+ * `MessagePort` schemas are convenience wrappers around the same behavior.
+ *
+ * **Common tasks**
+ *
+ * Wrap a worker message field with `schema` when the transferable is nested or
+ * derived from the encoded value. Provide a fresh collector around each message
+ * encode, read or clear it after encoding, and pass the resulting list to the
+ * worker transport.
+ *
+ * **Gotchas**
+ *
+ * Transfer annotations do not make unsupported values structured-cloneable.
+ * Ownership moves to the receiver after `postMessage`, so buffers are detached
+ * from the sender. For typed array views, collecting `view.buffer` transfers the
+ * whole backing buffer, including bytes used by other views.
  *
  * @since 4.0.0
  */

package/src/unstable/workers/Worker.ts

@@ -1,27 +1,40 @@
 /**
- * Client-side worker primitives shared by browser, Node, and Bun platform
- * packages.
+ * Client-side worker primitives shared by browser, Node, and Bun adapters.
  *
- * A `WorkerPlatform` turns a numeric worker id into a long-lived `Worker`
- * client using a runtime-specific `Spawner`. This module is the low-level
- * building block used by worker-backed RPC clients and by platform adapters
- * that need to communicate with dedicated workers, shared workers,
- * `MessagePort`s, worker threads, or child-process transports while keeping
- * setup, message handling, and cleanup inside `Effect` scopes.
+ * This module defines the platform-neutral {@link Worker} client and the
+ * {@link WorkerPlatform} service that creates one for a numeric worker id.
+ * Platform packages provide the runtime-specific spawn, setup, listen, and
+ * cleanup logic; higher-level code uses the resulting worker to send messages
+ * and run an Effect handler for messages coming back from the worker.
  *
- * The worker protocol separates spawning from message delivery. Calls to
- * `send` made before the platform reports readiness are buffered and flushed
- * after `run` receives the ready signal, so a spawned worker must eventually be
- * run or buffered messages will never leave the client. Message values are
- * passed through `postMessage`, which means callers are responsible for
- * encoding payloads into values supported by the selected runtime's structured
- * clone implementation. Transfer lists can avoid copies for buffers, ports, or
- * other transferable values, but ownership moves to the worker and invalid
- * transfer lists surface as `WorkerSendError`s. Incoming messages are handled
- * by forking each handler invocation into the worker run's `FiberSet`, so
- * processing is concurrent rather than serialized; use an explicit queue,
- * semaphore, or protocol-level acknowledgement when ordering or back pressure
- * matters.
+ * **Mental model**
+ *
+ * A {@link Spawner} locates or creates the native worker value, and
+ * {@link makePlatform} turns platform hooks into a scoped {@link Worker}.
+ * Sending and receiving are separate: `send` queues outbound values until
+ * `run` observes the platform ready signal, then `run` keeps the message loop
+ * alive and owns the cleanup scope for the active port.
+ *
+ * **Common tasks**
+ *
+ * Use {@link layerSpawner} to provide the runtime's worker lookup function,
+ * {@link makePlatform} to build browser, Node, Bun, or custom adapters, and
+ * {@link makeUnsafe} when an adapter already exposes the low-level platform
+ * protocol. Worker-backed RPC clients use these primitives to communicate with
+ * dedicated workers, shared workers, `MessagePort`s, worker threads, or child
+ * processes.
+ *
+ * **Gotchas**
+ *
+ * - Messages sent before readiness are buffered, so the returned worker must be
+ *   run or those messages never leave the client
+ * - Values pass through `postMessage`; callers must use values supported by
+ *   the selected runtime's structured clone implementation
+ * - Transfer lists can avoid copies, but ownership moves to the worker and
+ *   invalid transfer lists fail with `WorkerSendError`
+ * - Incoming messages are handled concurrently in the run fiber set; add a
+ *   queue, semaphore, or protocol acknowledgement when ordering or back
+ *   pressure matters
  *
  * @since 4.0.0
  */

package/src/unstable/workers/WorkerError.ts

@@ -1,22 +1,38 @@
 /**
- * Typed error definitions for the unstable worker APIs.
- *
- * `WorkerError` is the shared error channel for `WorkerPlatform` and
- * `WorkerRunnerPlatform` implementations. The nested reason identifies where a
- * platform failure happened: spawning or setting up a worker, sending through
- * `postMessage`, receiving worker events, or handling a runtime-specific
- * failure that does not fit the other categories. This is useful when building
- * worker-backed RPC clients and servers, implementing a platform adapter, or
- * recovering differently from startup, transport, and worker-exit failures.
- *
- * Worker transports cross browser, Node, Bun, and child-process runtimes, so the
- * original cause is best treated as diagnostic data. Spawn failures can mean the
- * runner is not actually executing inside a worker context, send failures often
- * come from structured-clone or transfer-list problems, and receive failures
- * may be reported as `messageerror`, `error`, or exit events depending on the
- * runtime. The `WorkerErrorReason` schema supports encoding and decoding the
- * tagged reasons, but message payloads still need to be valid for the selected
- * worker protocol and runtime.
+ * The `WorkerError` module defines the typed error model shared by the
+ * unstable worker APIs. Worker client and runner platforms use
+ * {@link WorkerError} when platform setup, sending, receiving, or
+ * runtime-specific worker behavior fails.
+ *
+ * **Mental model**
+ *
+ * - {@link WorkerError} is the outer error exposed in worker effect error
+ *   channels
+ * - {@link WorkerErrorReason} records one tagged reason: spawn, send,
+ *   receive, or unknown
+ * - The outer error delegates `message` and `cause` to the nested reason
+ * - Reason schemas can be encoded and decoded when worker or RPC layers need
+ *   structured diagnostics
+ *
+ * **Common tasks**
+ *
+ * - Detect worker failures with {@link isWorkerError}
+ * - Classify startup and setup problems with {@link WorkerSpawnError}
+ * - Classify `postMessage` or transfer-list failures with
+ *   {@link WorkerSendError}
+ * - Classify inbound event, `messageerror`, or worker-exit failures with
+ *   {@link WorkerReceiveError}
+ * - Preserve runtime-specific failures that do not fit another case with
+ *   {@link WorkerUnknownError}
+ *
+ * **Gotchas**
+ *
+ * - The `cause` is diagnostic data and can have different shapes across
+ *   browser, Node, Bun, and child-process transports
+ * - A `WorkerSendError` often means the payload was invalid for the selected
+ *   structured-clone or transfer-list rules
+ * - A `WorkerSpawnError` can mean the runner code is not executing inside the
+ *   expected worker context
  *
  * @since 4.0.0
  */

package/src/unstable/workers/WorkerRunner.ts

@@ -1,24 +1,35 @@
 /**
- * Server-side worker runner primitives shared by the browser, Node, and Bun
- * platform packages.
+ * Platform-neutral primitives for code running inside worker-like runtimes.
  *
- * A `WorkerRunnerPlatform` is installed in code that is already running inside
- * a worker-like runtime. Starting it yields a `WorkerRunner`, which listens for
- * parent or client requests, identifies each connection with a numeric port id,
- * and sends responses back through the same transport. The main Effect use case
- * is `RpcServer.layerProtocolWorkerRunner`, but platform adapters can also use
- * these types to expose lower-level request handlers for dedicated workers,
- * shared workers, worker threads, or child-process channels.
+ * This module gives browser workers, shared workers, Node worker threads, Bun
+ * workers, and child-process adapters the same server-side shape: start a
+ * runner, receive messages tagged by a numeric port id, and send replies back
+ * through the matching transport.
  *
- * The wire protocol is intentionally small: inbound messages are
- * `PlatformMessage` values where `[0, payload]` is a request and `[1]` closes a
- * port. Higher-level protocols are responsible for encoding request and
- * response payloads before they cross the worker boundary. Values must still be
- * accepted by the selected runtime's message mechanism, so structured-clone
- * support, transfer lists, `messageerror` events, and single-port runtimes such
- * as Node or Bun should be considered when choosing payload schemas and
- * resource lifetimes. Handler effects run on the runtime captured by `run`, so
- * services required by the handler must be provided to the running effect.
+ * **Mental model**
+ *
+ * `WorkerRunnerPlatform` is installed inside the worker-like runtime. Starting
+ * it yields a `WorkerRunner`, and `WorkerRunner.run` attaches the message
+ * handler. Incoming values use the small `PlatformMessage` protocol:
+ * `[0, payload]` delivers a request and `[1]` closes a port. Higher-level
+ * protocols, such as RPC over workers, decide how payloads are encoded before
+ * they reach this layer.
+ *
+ * **Common tasks**
+ *
+ * - Start the current platform from the {@link WorkerRunnerPlatform} service
+ * - Handle inbound messages with `WorkerRunner.run`
+ * - Send responses or notifications with `WorkerRunner.send`
+ * - Observe optional disconnect notifications through `WorkerRunner.disconnects`
+ *
+ * **Gotchas**
+ *
+ * This module does not serialize payloads; values must already be acceptable to
+ * the selected runtime's message mechanism. Structured-clone support, transfer
+ * lists, `messageerror` events, and single-port runtimes such as Node or Bun
+ * all affect which payloads and resource lifetimes are safe. Handler effects
+ * run on the runtime captured by `run`, so services required by a handler must
+ * be provided to that running effect.
  *
  * @since 4.0.0
  */

package/src/unstable/workers/index.ts

@@ -5,101 +5,21 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * Utilities for marking the parts of worker messages that should be transferred
- * through `postMessage` instead of copied by the structured clone algorithm.
- *
- * This module is used with worker message schemas to collect
- * `globalThis.Transferable` values while encoding a message, so the worker
- * platform can pass the collected list as the `postMessage` transfer list.
- * Common cases include sending large `Uint8Array` payloads, `ImageData` pixel
- * buffers, or `MessagePort` channels without paying for an extra copy.
- *
- * Transferable annotations do not make an otherwise unsupported value
- * structured-cloneable; the encoded message still has to be valid for
- * `postMessage`. Transferring also moves ownership to the receiver, so buffers
- * are detached from the sender after the send completes. Be careful when a
- * typed array view shares a backing buffer with other data, since collecting
- * that buffer transfers ownership of the whole buffer.
- *
  * @since 4.0.0
  */
 export * as Transferable from "./Transferable.ts"
 
 /**
- * Client-side worker primitives shared by browser, Node, and Bun platform
- * packages.
- *
- * A `WorkerPlatform` turns a numeric worker id into a long-lived `Worker`
- * client using a runtime-specific `Spawner`. This module is the low-level
- * building block used by worker-backed RPC clients and by platform adapters
- * that need to communicate with dedicated workers, shared workers,
- * `MessagePort`s, worker threads, or child-process transports while keeping
- * setup, message handling, and cleanup inside `Effect` scopes.
- *
- * The worker protocol separates spawning from message delivery. Calls to
- * `send` made before the platform reports readiness are buffered and flushed
- * after `run` receives the ready signal, so a spawned worker must eventually be
- * run or buffered messages will never leave the client. Message values are
- * passed through `postMessage`, which means callers are responsible for
- * encoding payloads into values supported by the selected runtime's structured
- * clone implementation. Transfer lists can avoid copies for buffers, ports, or
- * other transferable values, but ownership moves to the worker and invalid
- * transfer lists surface as `WorkerSendError`s. Incoming messages are handled
- * by forking each handler invocation into the worker run's `FiberSet`, so
- * processing is concurrent rather than serialized; use an explicit queue,
- * semaphore, or protocol-level acknowledgement when ordering or back pressure
- * matters.
- *
  * @since 4.0.0
  */
 export * as Worker from "./Worker.ts"
 
 /**
- * Typed error definitions for the unstable worker APIs.
- *
- * `WorkerError` is the shared error channel for `WorkerPlatform` and
- * `WorkerRunnerPlatform` implementations. The nested reason identifies where a
- * platform failure happened: spawning or setting up a worker, sending through
- * `postMessage`, receiving worker events, or handling a runtime-specific
- * failure that does not fit the other categories. This is useful when building
- * worker-backed RPC clients and servers, implementing a platform adapter, or
- * recovering differently from startup, transport, and worker-exit failures.
- *
- * Worker transports cross browser, Node, Bun, and child-process runtimes, so the
- * original cause is best treated as diagnostic data. Spawn failures can mean the
- * runner is not actually executing inside a worker context, send failures often
- * come from structured-clone or transfer-list problems, and receive failures
- * may be reported as `messageerror`, `error`, or exit events depending on the
- * runtime. The `WorkerErrorReason` schema supports encoding and decoding the
- * tagged reasons, but message payloads still need to be valid for the selected
- * worker protocol and runtime.
- *
  * @since 4.0.0
  */
 export * as WorkerError from "./WorkerError.ts"
 
 /**
- * Server-side worker runner primitives shared by the browser, Node, and Bun
- * platform packages.
- *
- * A `WorkerRunnerPlatform` is installed in code that is already running inside
- * a worker-like runtime. Starting it yields a `WorkerRunner`, which listens for
- * parent or client requests, identifies each connection with a numeric port id,
- * and sends responses back through the same transport. The main Effect use case
- * is `RpcServer.layerProtocolWorkerRunner`, but platform adapters can also use
- * these types to expose lower-level request handlers for dedicated workers,
- * shared workers, worker threads, or child-process channels.
- *
- * The wire protocol is intentionally small: inbound messages are
- * `PlatformMessage` values where `[0, payload]` is a request and `[1]` closes a
- * port. Higher-level protocols are responsible for encoding request and
- * response payloads before they cross the worker boundary. Values must still be
- * accepted by the selected runtime's message mechanism, so structured-clone
- * support, transfer lists, `messageerror` events, and single-port runtimes such
- * as Node or Bun should be considered when choosing payload schemas and
- * resource lifetimes. Handler effects run on the runtime captured by `run`, so
- * services required by the handler must be provided to the running effect.
- *
  * @since 4.0.0
  */
 export * as WorkerRunner from "./WorkerRunner.ts"