effect 4.0.0-beta.78 → 4.0.0-beta.79

package/src/unstable/rpc/RpcGroup.ts

@@ -1,35 +1,10 @@
 /**
- * Protocol composition for typed RPC definitions.
+ * Collects typed RPC definitions and server handlers.
  *
- * An {@link RpcGroup} collects RPC definitions under their tags and preserves
- * the payload, success, error, defect, middleware, and annotation metadata used
- * by clients, servers, tests, cluster entities, workflows, and other RPC
- * integrations.
- *
- * **Mental model**
- *
- * A group is a typed map from RPC tag to RPC definition. The `add`, `merge`,
- * `omit`, `prefix`, `middleware`, and `annotateRpcs` methods return new groups
- * whose type tracks the changed protocol. The final group can then be turned
- * into handler contexts or layers with `toHandlers`, `toLayer`, or
- * `toLayerHandler`.
- *
- * **Common tasks**
- *
- * Use {@link make} to define a service surface once, split large protocols into
- * feature groups that are merged later, prefix generated or proxied names, and
- * attach metadata for higher-level runtimes. Use {@link HandlersFrom} and
- * {@link HandlerFrom} when implementing handlers separately from the group
- * expression that declares them.
- *
- * **Gotchas**
- *
- * Composition order matters. `middleware` and `annotateRpcs` affect only the
- * RPCs already in the group, duplicate tags from `add` or `merge` replace the
- * existing definition, and handlers are keyed by tags after any prefixing.
- * Schema requirements still come from each RPC's payload, success, error,
- * defect, and middleware schemas; grouping preserves those requirements but
- * does not provide the services needed to encode, decode, or handle them.
+ * An `RpcGroup` stores RPC definitions by tag and keeps annotations shared by
+ * the group. This module provides helpers for composing groups, applying
+ * middleware or annotations, deriving handler types, and turning handler objects
+ * into `Context` or `Layer` values used by RPC servers.
  *
  * @since 4.0.0
  */

package/src/unstable/rpc/RpcMessage.ts

@@ -8,32 +8,6 @@
  * streaming, acknowledgement, interrupt, keepalive, and defect signals as the
  * built-in HTTP, socket, worker, and test transports.
  *
- * **Mental model**
- *
- * A request is identified by a `RequestId` from the first `Request` through any
- * `Chunk` batches, the terminal `Exit`, optional `Ack`s, and optional
- * `Interrupt`s. Decoded messages carry branded ids, typed RPC tags, headers,
- * and typed payload, chunk, or exit values. Encoded messages use string ids and
- * `unknown` payloads that have already crossed the schema serialization
- * boundary.
- *
- * **Message families**
- *
- * Client-to-server messages start work (`Request`), acknowledge streamed chunks
- * (`Ack`), cancel in-flight work (`Interrupt`), close client input (`Eof`), or
- * check liveness (`Ping`). Server-to-client messages stream successful values
- * (`Chunk`), complete work (`Exit`), report connection-level defects
- * (`Defect`), end a client connection (`ClientEnd`), answer keepalives
- * (`Pong`), or report client protocol errors.
- *
- * **Gotchas**
- *
- * `Ack` is part of streaming back pressure, not call completion. `Eof` closes
- * client input but does not replace terminal `Exit` responses. `Ping` and
- * `Pong` are connection liveness messages. Transports must preserve request ids
- * exactly across encoded strings and decoded branded values, or responses,
- * interrupts, and acknowledgements can be routed to the wrong in-flight call.
- *
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts"

package/src/unstable/rpc/RpcMiddleware.ts

@@ -7,34 +7,6 @@
  * implementation, the schema for server-visible failures, the client-only error
  * type, and whether generated clients must require the matching client layer.
  *
- * **Mental model**
- *
- * A server {@link RpcMiddleware} receives the target RPC, decoded payload,
- * request headers, request id, and `Rpc.ServerClient`, then wraps the handler
- * effect. `provides` removes services from the downstream handler requirement,
- * while `requires` adds the services needed by the middleware. A client
- * {@link RpcMiddlewareClient} is installed with {@link layerClient}; it can
- * inspect, rewrite, retry, or short-circuit outgoing requests before calling
- * `next`.
- *
- * **Common tasks**
- *
- * Use {@link Service} to define authentication, authorization, logging,
- * tracing, metrics, rate limiting, header propagation, or request-scoped
- * service injection. Attach the service to individual RPCs or whole groups,
- * then provide the server implementation like any other `Context.Service`.
- * Provide a client implementation with {@link layerClient} when outgoing
- * requests need matching behavior.
- *
- * **Gotchas**
- *
- * Middleware failures that cross the RPC boundary must be declared with a
- * `Schema`, and any encoding or decoding services required by that schema stay
- * in the generated RPC environments. `clientError` contributes only to the
- * client-side call error channel, while the middleware `error` schema is shared
- * with server failures. Set `requiredForClient` only when typed clients must
- * reject calls unless the matching client middleware layer is installed.
- *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"

package/src/unstable/rpc/RpcSchema.ts

@@ -6,31 +6,6 @@
  * streamed responses and annotates interruptions that came from a remote client
  * closing or cancelling a request.
  *
- * **Mental model**
- *
- * A streaming RPC still has a normal RPC exit, but its success schema is marked
- * with {@link Stream}. The marker stores the stream element schema and the
- * stream error schema so transports can encode and decode each chunk while
- * keeping stream failures on the chunk stream.
- *
- * **Common tasks**
- *
- * - Use {@link Stream} when constructing RPC metadata directly
- * - Use {@link isStreamSchema} to branch between one-shot and streaming
- *   responses in protocol implementations
- * - Read the stored `success` and `error` schemas when encoding or decoding
- *   stream chunks
- * - Use {@link ClientAbort} to tag interruptions caused by client disconnects
- *
- * **Gotchas**
- *
- * - `Rpc.make(..., { stream: true })` installs this marker for you
- * - For streaming RPCs, the immediate RPC exit succeeds with `void`; stream
- *   elements and stream errors are encoded separately
- * - Request payload schemas live on the `Rpc` definition, not in this module
- * - `Stream` is RPC metadata, not a general-purpose codec for arbitrary
- *   `Stream` values
- *
  * @since 4.0.0
  */
 import * as Cause from "../../Cause.ts"

package/src/unstable/rpc/RpcSerialization.ts

@@ -1,37 +1,11 @@
 /**
- * Serialization support for the unstable RPC protocol.
+ * Serializes RPC protocol messages for transports.
  *
- * `RpcSerialization` is the boundary between encoded RPC protocol messages and
- * the bytes or strings carried by a transport. RPC clients and servers use the
- * service to turn `RpcMessage` envelopes into JSON, newline-delimited JSON,
- * JSON-RPC 2.0, or MessagePack payloads, and to parse those payloads back into
- * protocol messages.
- *
- * **Mental model**
- *
- * RPC schemas are responsible for encoding payloads, successes, failures, and
- * stream chunks into transport-safe values. This module then chooses how those
- * values are represented on the wire and whether message boundaries are part of
- * that representation. The parser returned by `makeUnsafe` may be stateful, so
- * transports should create a parser for the lifetime of the stream, connection,
- * or request body they are decoding.
- *
- * **Common tasks**
- *
- * Use `layerJson` or `layerJsonRpc` when the transport already frames each
- * payload, such as ordinary HTTP request and response bodies. Use
- * `layerNdjson`, `layerNdJsonRpc`, or `layerMsgPack` for sockets, workers, and
- * other streaming transports that can receive partial chunks or several
- * messages in one chunk. Provide a custom `RpcSerialization` service when a
- * transport requires a different content type, frame format, or binary codec.
- *
- * **Gotchas**
- *
- * Both ends of the connection must use compatible serialization and framing.
- * `json` and `jsonRpc` expect a complete payload for each decode call, while
- * `ndjson`, `ndJsonRpc`, and `msgPack` keep parser state for incomplete input.
- * JSON is easy to inspect but needs schema encodings for arbitrary binary
- * values; MessagePack is more compact and carries binary data more naturally.
+ * `RpcSerialization` is the boundary between `RpcMessage` envelopes and the
+ * bytes or strings carried by a transport. This module provides built-in
+ * serializers for JSON, newline-delimited JSON, JSON-RPC 2.0, and MessagePack,
+ * including framed formats that can decode multiple messages from streaming
+ * chunks.
  *
  * @since 4.0.0
  */

package/src/unstable/rpc/RpcServer.ts

@@ -1,45 +1,12 @@
 /**
- * Server-side runtime for RPC groups.
+ * Runs server-side handlers for RPC groups.
  *
- * This module connects typed handlers for an RPC group to a transport. It
- * receives client messages, decodes request payloads, runs the matching
- * handler, and writes exits, stream chunks, defects, interrupts, and client-end
- * notifications back through the active server protocol. It supports encoded
- * protocols such as HTTP, websocket, socket, stdio, and worker transports, plus
- * already-decoded channels through {@link makeNoSerialization}.
- *
- * **Mental model**
- *
- * {@link Protocol} is the transport boundary. It owns how encoded client
- * messages arrive, how encoded server responses are written, and whether the
- * channel supports acknowledgements, transferable objects, or span
- * propagation. {@link make} and {@link layer} combine that protocol with an RPC
- * group and the handler context required by `Rpc.ToHandler` and
- * `Rpc.Middleware`.
- *
- * **Common tasks**
- *
- * Use {@link layerHttp} for route-mounted HTTP or websocket serving,
- * {@link toHttpEffect} and {@link toHttpEffectWebsocket} for standalone HTTP
- * effects, the `layerProtocol*` constructors for socket, stdio, or worker
- * transports, and {@link makeNoSerialization} when another component already
- * owns message serialization.
- *
- * **Gotchas**
- *
- * - Server handlers are looked up from `Rpc.ToHandler`, while RPC middleware
- *   is looked up from `Rpc.Middleware` and wraps handlers with metadata that
- *   includes `Rpc.ServerClient`, request id, headers, and decoded payload
- * - Payloads are decoded on the server; exits, stream chunks, and request
- *   defects are encoded on the server using the RPC schemas and the handler's
- *   schema services
- * - Encode failures are reported as request defects and interrupt the
- *   in-flight request
- * - Streaming RPCs send chunks before the final exit, and protocols with
- *   acknowledgement support wait for client acknowledgements between chunks to
- *   provide back pressure
- * - Fatal handler defects are sent as protocol defects by default; set
- *   `disableFatalDefects` when defects should remain ordinary request exits
+ * This module connects typed handlers for an `RpcGroup` to a server `Protocol`.
+ * It receives client messages, decodes request payloads, runs matching handlers
+ * and middleware, tracks in-flight requests, handles acknowledgements and
+ * interrupts, and sends responses back to clients. It also provides constructors
+ * and layers for decoded messages, HTTP, WebSocket, sockets, stdio, and worker
+ * runner protocols.
  *
  * @since 4.0.0
  */

package/src/unstable/rpc/RpcTest.ts

@@ -7,30 +7,6 @@
  * middleware metadata travel through the normal client/server machinery without
  * opening HTTP, socket, worker, or serializer infrastructure.
  *
- * **Mental model**
- *
- * `makeClient` builds an in-memory server, wires the client and server write
- * callbacks together, and returns the scoped generated client. The handlers,
- * server middleware, client middleware, and `Scope` still come from the Effect
- * environment just as they would for a real transport; only the byte-level
- * protocol is skipped.
- *
- * **Common tasks**
- *
- * Use this module for tests that should exercise RPC routing, handler lookup,
- * middleware, headers, typed errors, interruptions, and streaming behavior
- * quickly. Use a real transport plus `RpcSerialization` coverage when you need
- * to test HTTP status handling, socket framing, worker transferables, schema
- * encoding or decoding, or wire compatibility.
- *
- * **Gotchas**
- *
- * Because no serialization happens, invalid wire payloads and mismatched codecs
- * will not be discovered here. The client is scoped to the in-memory
- * connection; acquire it inside a scoped test or provide `Scope` explicitly.
- * The `flatten` option matches `RpcClient.makeNoSerialization`, and
- * acknowledgements are enabled to mirror the bidirectional streaming protocol.
- *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.ts"

package/src/unstable/rpc/RpcWorker.ts

@@ -1,35 +1,11 @@
 /**
- * Bootstrap messages for worker-backed RPC protocols.
+ * Initial messages for worker-backed RPC protocols.
  *
- * Worker-backed RPC clients sometimes need to send data before the first RPC
- * request is handled: per-worker configuration, credentials, feature flags,
- * preloaded caches, or transferable handles. This module defines the
- * {@link InitialMessage} service plus helpers that encode that bootstrap value
- * on the client side and decode it on the worker server side.
- *
- * **Mental model**
- *
- * The initial message is a one-time envelope outside the normal RPC request and
- * response stream. {@link makeInitialMessage} runs the build effect, encodes
- * its value with the supplied schema's JSON codec, and collects transferables.
- * {@link layerInitialMessage} stores that encoded payload in context for the
- * RPC client runtime. Inside the worker, {@link initialMessage} reads the
- * protocol's bootstrap payload and decodes it with the same schema.
- *
- * **Common tasks**
- *
- * - Provide typed worker startup data with {@link layerInitialMessage}
- * - Precompute encoded data and transfer lists with {@link makeInitialMessage}
- * - Read typed startup data in the worker with {@link initialMessage}
- *
- * **Gotchas**
- *
- * The payload is posted with worker `postMessage`, so encoded values still must
- * cross the structured clone boundary. Transferables collected during encoding
- * are moved to the worker; buffers and ports may no longer be usable by the
- * sender after transfer. The initial message is separate from
- * `RpcSerialization`, so changing request/response serialization does not
- * change how this bootstrap payload is encoded.
+ * A worker-backed RPC client can send one schema-encoded value before normal RPC
+ * requests are handled. This module defines the `InitialMessage` service, a
+ * helper for encoding that value while collecting transferables, a layer for
+ * providing it to the client protocol, and a decoder for reading it from the
+ * worker server protocol.
  *
  * @since 4.0.0
  */

package/src/unstable/rpc/Utils.ts

@@ -1,26 +1,10 @@
 /**
- * Internal helpers for constructing RPC protocol services whose receive loop is
- * installed separately from the operations that write to it.
+ * Helps RPC protocol services buffer messages until their receive loop starts.
  *
- * This module is used by the client and server `Protocol.make` constructors to
- * let transports expose a stable service immediately while buffering messages
- * until the protocol's `run` method has installed the active receiver. Buffered
- * writes keep the `Context` that was current at the time of the write, so
- * replaying early messages preserves fiber-local services such as tracing or
- * request metadata.
- *
- * The general `withRun` helper is for single receive-loop services, such as
- * server transports, while `withRunClient` specializes the same pattern for
- * client transports by tracking active client ids and keeping a separate buffer
- * per client. They are most useful when implementing custom RPC transports or
- * test protocols that need to send before the consumer fiber has started.
- *
- * These helpers intentionally work on `Omit<Service, "run">` and re-add `run`
- * so generated `Context.Service` static `make` members can preserve their
- * exact service shape. When using them from generated or type-helper-heavy
- * protocol code, keep the `run` signature aligned with the target service:
- * the server helper has one shared writer, but the client helper requires a
- * `clientId` because responses and buffered messages are routed per client.
+ * Client and server protocol constructors use these helpers to expose a stable
+ * service before the active receiver is installed. Writes made before `run`
+ * starts are buffered with their current `Context`, then replayed once the
+ * receiver is ready.
  *
  * @since 4.0.0
  */

package/src/unstable/schema/Model.ts

@@ -1,21 +1,13 @@
 /**
- * Utilities for defining schema-backed domain models that need different shapes
- * for database access and JSON APIs.
+ * Defines schema-backed domain models with separate database and JSON shapes.
  *
- * A model defined with this module keeps one field declaration as the source of
- * truth and derives the `select`, `insert`, `update`, `json`, `jsonCreate`, and
- * `jsonUpdate` variants from it. This is useful for persistence models whose
- * database representation differs from the public API, for example generated
- * columns, application-generated identifiers, sensitive fields that must not be
- * serialized to JSON, nullable database columns exposed as `Option`, SQLite
- * booleans, JSON stored as text, date-time audit columns, and generated UUIDs.
- *
- * Each variant is a schema in its own right, so choose the variant that matches
- * the boundary you are validating or encoding. Plain schemas are included in all
- * variants, while `Field` helpers opt a property into only the variants they
- * declare. Overrideable defaults such as timestamp helpers can still be provided
- * explicitly with `Override`, and JSON variants may differ from database variants
- * in both optionality and encoded representation.
+ * A model keeps one field declaration as the source of truth and derives
+ * variants for selecting, inserting, updating, and JSON encoding. This is useful
+ * when the database shape is not exactly the same as the public API shape, such
+ * as generated ids, audit timestamps, nullable columns, private fields, or
+ * values that need different encodings at different boundaries. Each generated
+ * variant is its own schema, so callers can validate or encode the shape that
+ * matches the operation they are performing.
  *
  * @since 4.0.0
  */
@@ -193,8 +185,16 @@ export const fields: <A extends VariantSchema.Struct<any>>(self: A) => A[typeof
 export const Override: <A>(value: A) => A & Brand<"Override"> = VariantSchema.Override
 
 /**
- * Variant field type for a database-generated column that is present in select,
- * update, and read JSON variants but omitted from insert variants.
+ * Variant field type for a database-generated column that is present in read
+ * variants only.
+ *
+ * **Details**
+ *
+ * The field is included in `select` and `json`, and omitted from `insert`,
+ * `update`, `jsonCreate`, and `jsonUpdate`.
+ *
+ * @see {@link Field} for generated columns that need a custom variant set, such
+ * as primary keys used in update payloads.
  *
  * @category generated
  * @since 4.0.0
@@ -207,7 +207,16 @@ export interface GeneratedByDb<S extends Schema.Top> extends
 {}
 
 /**
- * A field that represents a database-generated column available for reads only.
+ * Creates a variant field for a database-generated column available in read
+ * variants only.
+ *
+ * **Details**
+ *
+ * The field is included in `select` and `json`, and omitted from `insert`,
+ * `update`, `jsonCreate`, and `jsonUpdate`.
+ *
+ * @see {@link Field} for generated columns that need a custom variant set, such
+ * as primary keys used in update payloads.
  *
  * @category generated
  * @since 4.0.0

package/src/unstable/schema/VariantSchema.ts

@@ -1,22 +1,10 @@
 /**
- * Build families of related struct schemas from one field definition.
+ * Builds related schemas for named variants from shared field definitions.
  *
- * `VariantSchema` is useful when the same domain object needs several schema
- * views, such as database select / insert / update shapes, JSON read / write
- * shapes, public versus private API views, or constructor schemas with
- * generated defaults. {@link make} fixes a closed set of variant names and a
- * default variant, then returns helpers for defining shared `Struct` values,
- * per-variant `Field` values, schema classes, unions, and extracted
- * `Schema.Struct` projections.
- *
- * A plain schema in a variant struct is present in every variant, a `Field`
- * contributes a property only to the variants named in its config, and nested
- * variant structs are extracted recursively. Variants are projections, not
- * discriminated alternatives: this module does not add a tag field, so include
- * an explicit literal tag when a decoded union needs runtime discrimination.
- * Also remember that the default variant is the schema used by generated
- * classes and ordinary variant unions; per-variant schemas are exposed
- * separately on those generated values.
+ * `make` fixes the variant names and default variant, then lets callers define
+ * fields that are shared by all variants or specific to some variants. From
+ * those definitions it can create schema classes, unions, extracted struct
+ * schemas, and helpers for changing fields across variants.
  *
  * @since 4.0.0
  */

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
  */