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

package/src/unstable/socket/Socket.ts

@@ -1,25 +1,10 @@
 /**
- * Effect-based socket abstractions for bidirectional connections that exchange
- * text frames, binary frames, and close events.
- *
- * This module defines the `Socket` service, constructors for WebSocket-backed
- * and transform-stream-backed sockets, typed socket errors, and adapters that
- * expose a socket as a bidirectional `Channel`. It is intended for WebSocket
- * clients, HTTP server upgrades, protocol clients and servers, and tests or
- * adapters that need a scoped duplex transport inside Effect programs.
- *
- * Incoming data can be consumed as raw frames, binary bytes, or strings.
- * `runRaw` preserves whether the transport delivered a string or `Uint8Array`,
- * while `run` encodes string frames as UTF-8 bytes and `runString` decodes
- * binary frames with `TextDecoder`. Use the raw or mapping APIs when preserving
- * frame boundaries, binary payloads, or text encodings matters.
- *
- * Writers are scoped to an active run and are gated until the underlying
- * connection is open; use `onOpen` when startup writes must wait for that
- * point. Outgoing strings and bytes are sent as data frames, while `CloseEvent`
- * values request a close. Close events are modeled as `SocketCloseError` by
- * default, and `closeCodeIsError` controls which close codes should fail a run
- * versus complete cleanly.
+ * Models bidirectional socket connections in Effect.
+ *
+ * The `Socket` service runs handlers for binary, string, or raw frames and
+ * provides a scoped writer for outgoing bytes, text, or close events. This
+ * module also includes socket errors, channel adapters, WebSocket layers, and
+ * transform-stream-backed sockets.
  *
  * @since 4.0.0
  */

package/src/unstable/socket/SocketServer.ts

@@ -1,25 +1,11 @@
 /**
- * Effect service model for servers that accept socket connections and hand each
- * accepted connection to an Effect handler as a `Socket.Socket`.
+ * Service contract for servers that accept socket connections.
  *
- * This module contains the shared, platform-independent contract for socket
- * servers: a bound `address`, a long-running `run` accept loop, the TCP and
- * Unix socket address models, and the server-level errors reported while
- * opening or running a server. Concrete transports, such as Node TCP servers or
- * WebSocket servers, provide this service through platform-specific layers.
- *
- * `SocketServer` is commonly used as the server transport for RPC protocols,
- * cluster runners, developer tools, and tests that need an ephemeral TCP port or
- * Unix-domain socket. A server address may differ from the requested listen
- * options after binding, for example when listening on port `0`, so consumers
- * should read the provided `address` from the service.
- *
- * The `run` effect represents the server accept loop and is expected to remain
- * alive until interrupted or until the providing scope is closed. Protocol
- * framing is intentionally outside this module: handlers receive a generic
- * `Socket.Socket`, so callers are responsible for choosing byte, string, raw
- * frame, or higher-level protocol adapters and for treating connection-level
- * failures separately from `SocketServerError` values.
+ * `SocketServer` exposes the bound server `address` and a long-running `run`
+ * loop that hands each accepted connection to a handler as a `Socket.Socket`.
+ * The module also defines TCP and Unix socket address models plus the
+ * server-level errors reported while opening or running a server. Platform
+ * layers provide concrete implementations of this service.
  *
  * @since 4.0.0
  */

package/src/unstable/sql/Migrator.ts

@@ -1,45 +1,10 @@
 /**
- * SQL migration runner for Effect applications.
+ * Runs SQL migrations with `SqlClient`.
  *
- * A migrator loads numbered migration effects, records which ids have already
- * run in a migrations table, and executes only the pending migrations through a
- * `SqlClient`. The helpers in this module cover the common ways migrations are
- * discovered: dynamic glob imports, Babel-style glob records, in-memory
- * records, and filesystem directories.
- *
- * **Mental model**
- *
- * - A {@link Loader} resolves an ordered list of {@link ResolvedMigration}
- *   values
- * - {@link make} creates a runner that ensures the migrations table exists,
- *   reads the latest recorded id, loads pending migration effects, records
- *   them, and runs them in a transaction
- * - The default migrations table is `effect_sql_migrations`; pass `table` when
- *   a database needs a different name
- * - On PostgreSQL the migrations table is explicitly locked; other dialects use
- *   the table constraint to detect concurrent runners
- * - `schemaDirectory` runs the `dumpSchema` hook after successful migrations
- *
- * **Common tasks**
- *
- * - Load bundler migration modules with {@link fromGlob} or
- *   {@link fromBabelGlob}
- * - Load test or programmatic migrations with {@link fromRecord}
- * - Load migration files from a directory with {@link fromFileSystem}
- * - Customize schema dumps by passing `dumpSchema` to {@link make}
- *
- * **Gotchas**
- *
- * - Migration ids must be unique numbers; duplicate ids fail before any pending
- *   migration is run
- * - Only ids greater than the latest recorded id are considered pending, so
- *   editing or inserting an older migration does not make it run again
- * - File-based migrations must match `<id>_<name>.js`, `<id>_<name>.ts`,
- *   `<id>_<name>.mjs`, or `<id>_<name>.mts`
- * - File-based migration modules should default-export an `Effect` value that
- *   uses the current `SqlClient`; records can supply effects directly
- * - DDL transaction behavior is dialect-specific; coordinate custom table
- *   names, schema dumps, and external migration tooling accordingly
+ * A migrator loads numbered migration effects, records completed ids in a
+ * migrations table, and runs only pending migrations in a transaction. It
+ * creates the table when needed, detects duplicate ids, treats concurrent runs
+ * as locked, and can dump the schema after successful migrations.
  *
  * @since 4.0.0
  */

package/src/unstable/sql/SqlClient.ts

@@ -1,24 +1,10 @@
 /**
- * Defines the `SqlClient` service, the central runtime entry point for Effect's
- * unstable SQL support.
+ * Main SQL client service for tagged-template queries.
  *
- * 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.
+ * `SqlClient` combines the tagged-template statement constructor with
+ * connection acquisition, dialect compilation, transactions, row transforms,
+ * tracing, and reactive query helpers. Driver integrations build this service
+ * from their connection and compiler pieces.
  *
  * @since 4.0.0
  */

package/src/unstable/sql/SqlConnection.ts

@@ -1,23 +1,11 @@
 /**
- * Defines the low-level SQL connection service and shared row/acquirer types
- * used by Effect's unstable SQL driver integrations.
+ * Low-level SQL connection contract used by 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.
+ * A `Connection` is the driver-facing layer under `SqlClient`. It executes
+ * already-compiled SQL with positional parameters and can return transformed
+ * rows, raw driver results, streams, value arrays, or unprepared statement
+ * results. This module also defines the scoped connection acquirer type, the
+ * connection service tag, and the generic row shape.
  *
  * @since 4.0.0
  */

package/src/unstable/sql/SqlError.ts

@@ -1,37 +1,12 @@
 /**
- * Structured SQL failures for unstable SQL clients and driver integrations.
+ * Defines structured failures for SQL clients and driver integrations.
  *
- * This module provides the top-level `SqlError` wrapper, the concrete
- * `SqlErrorReason` variants used by adapters, schemas for encoding or decoding
- * those errors, guards for recognizing them, and a SQLite classifier for native
- * driver causes. The model keeps query mistakes, authentication and
- * authorization failures, constraint violations, connection failures, lock
- * waits, deadlocks, serialization conflicts, statement timeouts, and unknown
- * failures distinguishable in the Effect error channel.
- *
- * **Mental model**
- *
- * `SqlError` wraps exactly one reason. Its `message`, `cause`, and
- * `isRetryable` values are delegated to that reason, so recovery code can branch
- * on either the reason tag or the retryability flag without losing the original
- * native cause. Reasons are intentionally driver-neutral; adapters translate
- * database-specific error codes into this shared vocabulary.
- *
- * **Common tasks**
- *
- * Construct a reason when adapting a driver failure, wrap it in `SqlError` for
- * client APIs, use `isSqlError` or `isSqlErrorReason` at boundaries that receive
- * unknown failures, and use `classifySqliteError` when mapping SQLite `code` or
- * `errno` values.
- *
- * **Gotchas**
- *
- * Preserve the native `cause` and `operation` metadata when constructing these
- * errors; they are often the only way to diagnose dialect-specific failures.
- * Retryable reasons represent transient infrastructure or concurrency problems,
- * while syntax, credential, permission, and constraint failures generally need a
- * changed query, configuration, or data set. SQLite unique violations include a
- * best-effort constraint name when one can be extracted.
+ * `SqlError` wraps the different reasons a SQL operation can fail, such as
+ * connection, authentication, authorization, syntax, constraint, or transaction
+ * problems. Each reason keeps the original cause, optional message and
+ * operation metadata, and whether retrying may succeed. This module also
+ * includes schemas, guards, a SQLite error classifier, and the
+ * `ResultLengthMismatch` error used by ordered batched SQL resolvers.
  *
  * @since 4.0.0
  */

package/src/unstable/sql/SqlModel.ts

@@ -1,20 +1,12 @@
 /**
  * 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.
+ * Use this module when a schema `Model` represents rows in a SQL table and the
+ * usual insert, update, find-by-id, delete, and batching behavior should be
+ * derived from that model. The helpers encode insert and update input with the
+ * model's input schemas and decode returned rows with the full model schema.
+ * Soft deletes are optional, and SQL dialect differences such as `returning`
+ * support are handled by the repository implementation.
  *
  * @since 4.0.0
  */

package/src/unstable/sql/SqlResolver.ts

@@ -1,29 +1,12 @@
 /**
  * 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`.
+ * This module represents each lookup or mutation as a `SqlRequest` and batches
+ * concurrent requests into SQL operations. Request payloads are encoded with the
+ * request schema before `execute` is called, and returned rows are decoded with
+ * the result schema before requests are completed. It provides ordered,
+ * grouped, id-based, and side-effect-only resolver constructors, and keeps
+ * batches separated by the active SQL transaction connection.
  *
  * @since 4.0.0
  */

package/src/unstable/sql/SqlSchema.ts

@@ -4,33 +4,9 @@
  * `SqlSchema` is a small adapter between Effect Schema and SQL statements. Each
  * helper builds a function that accepts the decoded request type used by
  * application code, encodes it before calling `execute`, and decodes unknown
- * driver rows into the result schema. The helpers differ only in how many rows
- * they expect and how they represent an empty result set.
- *
- * **Mental model**
- *
- * The request schema protects the boundary going into SQL, and the result
- * schema protects the boundary coming back out. `execute` still owns statement
- * construction and database execution; this module only shapes the values that
- * cross that boundary.
- *
- * **Common tasks**
- *
- * - Use {@link findAll} for queries that may return any number of rows.
- * - Use {@link findNonEmpty} when an empty result is a failure.
- * - Use {@link findOne} when the first row is required.
- * - Use {@link findOneOption} when the first row is optional.
- * - Use `void` for writes where the encoded request matters but the driver
- *   result should be discarded.
- *
- * **Gotchas**
- *
- * `execute` receives `Req["Encoded"]`, not `Req["Type"]`. Any schema
- * transformations, encoding services, nullable columns, JSON values, dates, and
- * bigint representations must match the SQL builder and dialect in use. Result
- * schemas decode rows after SQL client row transforms have run. {@link findOne}
- * and {@link findOneOption} only inspect the first returned row; they do not
- * assert that the query returned exactly one row.
+ * driver rows into the result schema. The helpers cover returning all rows, a
+ * non-empty row list, the first row, an optional first row, or discarding the
+ * SQL result for side-effect-only statements.
  *
  * @since 4.0.0
  */

package/src/unstable/sql/SqlStream.ts

@@ -9,16 +9,6 @@
  * `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
  */
 import * as Cause from "../../Cause.ts"

package/src/unstable/sql/Statement.ts

@@ -1,40 +1,12 @@
 /**
  * Low-level SQL statement and fragment primitives.
  *
- * 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.
- *
- * **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.
+ * `SqlClient` uses this module to build executable, parameterized SQL from
+ * reusable fragments. A statement can be executed, streamed, run without row
+ * transformation, or compiled to SQL text and parameters for a specific
+ * dialect. The module also contains helpers for identifiers, parameters,
+ * inserts, updates, custom dialect fragments, statement compilation, and row
+ * transformation.
  *
  * @since 4.0.0
  */

package/src/unstable/workers/Transferable.ts

@@ -8,27 +8,6 @@
  * 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
  */
 import * as Context from "../../Context.ts"

package/src/unstable/workers/Worker.ts

@@ -1,40 +1,12 @@
 /**
  * Client-side worker primitives shared by browser, Node, and Bun adapters.
  *
- * 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.
- *
- * **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
+ * This module defines the platform-neutral `Worker` client, the `WorkerPlatform`
+ * service that creates workers by numeric id, and the `Spawner` service used to
+ * find platform-specific worker instances. `makePlatform` wraps platform setup
+ * and listen hooks into a `WorkerPlatform`, buffers outgoing messages until the
+ * worker is ready, runs incoming messages with Effect handlers, and ties worker
+ * cleanup to scope lifetime.
  *
  * @since 4.0.0
  */

package/src/unstable/workers/WorkerError.ts

@@ -1,38 +1,9 @@
 /**
- * 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.
+ * Typed error model for worker APIs.
  *
- * **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
+ * This module defines the `WorkerError` wrapper, the reason variants for spawn,
+ * send, receive, and unknown worker failures, a schema union for those reasons,
+ * and a guard for recognizing worker errors at runtime.
  *
  * @since 4.0.0
  */

package/src/unstable/workers/WorkerRunner.ts

@@ -1,35 +1,10 @@
 /**
- * Platform-neutral primitives for code running inside worker-like runtimes.
+ * Worker-side primitives for worker-like runtimes.
  *
- * 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.
- *
- * **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.
+ * A `WorkerRunner` receives messages tagged by a numeric port id, sends replies
+ * back through the same transport, and can expose disconnect notifications. The
+ * module also defines the small platform message shape and the
+ * `WorkerRunnerPlatform` service that starts a platform-specific runner.
  *
  * @since 4.0.0
  */

package/src/unstable/workflow/Activity.ts

@@ -1,23 +1,10 @@
 /**
- * The `Activity` module defines named, schema-backed effects that run at the
- * side-effect boundary of a durable workflow. Activities are executed through a
- * `WorkflowEngine`, encode their success and failure values with the provided
- * schemas, and can be replayed from persisted results instead of rerunning the
- * underlying effect.
+ * Defines named effects whose results can be stored by a workflow engine.
  *
- * Use activities for work that should not be embedded directly in workflow
- * control flow, such as calling external services, writing to databases,
- * enqueueing durable jobs, short sleeps delegated by `DurableClock`, or racing
- * multiple external operations with `raceAll`. Keep activity names and schemas
- * stable because engines use them, together with the workflow execution and
- * retry attempt, to identify stored results.
- *
- * Activities can be interrupted and retried, and workflow resumes may observe a
- * completed encoded result or run the activity again depending on what the
- * engine has persisted. Make external side effects idempotent, use
- * `idempotencyKey` for stable request keys derived from the workflow execution,
- * and include the current attempt only when each retry must address a distinct
- * external operation.
+ * An `Activity` is an `Effect` with a stable name and schemas for its success
+ * and error values. `make` wraps an effect so the `WorkflowEngine` can execute
+ * it, store its result, or replay that result during a workflow run. This module
+ * also includes helpers for retry attempts, idempotency keys, and durable races.
  *
  * @since 4.0.0
  */

package/src/unstable/workflow/DurableClock.ts

@@ -1,29 +1,10 @@
 /**
- * Workflow-safe sleeps that can be replayed, suspended, and resumed by a
- * workflow engine.
+ * Durable timers for workflow sleeps.
  *
- * Use this module when a workflow needs to pause for a timeout, reminder,
- * deadline, retry delay, or scheduled wake-up. `sleep` keeps very short delays
- * in the current process as an activity, and turns longer delays into durable
- * clocks that the engine can schedule and resume through a durable deferred.
- *
- * **Mental model**
- *
- * A `DurableClock` is a stable timer name, a normalized duration, and the
- * deferred completed when the timer wakes. `sleep` is the workflow-facing
- * helper: zero durations complete immediately, durations at or below the
- * in-memory threshold run with `Effect.sleep` inside an activity, and longer
- * durations are scheduled with the `WorkflowEngine` before awaiting the
- * clock's deferred.
- *
- * **Gotchas**
- *
- * Timer names, durations, and thresholds are part of workflow behavior. Keep
- * them deterministic for a given workflow path, avoid deriving them from
- * ambient wall-clock state, and give distinct logical waits distinct names so
- * replayed executions match the correct scheduled wake-up. Lower the in-memory
- * threshold when a delay must survive the current process rather than relying
- * on an in-process sleep.
+ * `make` creates a `DurableClock` with a name, duration, and deferred wake-up
+ * signal. `sleep` ignores zero durations, runs short sleeps through an
+ * in-memory activity, and schedules longer sleeps through the `WorkflowEngine`
+ * before awaiting the durable deferred tied to the clock.
  *
  * @since 4.0.0
  */