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

package/src/unstable/reactivity/Reactivity.ts

@@ -1,42 +1,11 @@
 /**
- * The `Reactivity` module provides process-local invalidation for connecting
- * writes to dependent reads. It does not cache values itself; it tracks keys,
- * registers query handlers, and reruns effects when matching keys are
- * invalidated so queues, streams, UI subscriptions, and read models can stay
- * fresh after successful writes.
+ * Process-local invalidation for connecting writes to dependent reads.
  *
- * **Mental model**
- *
- * A query registers one or more keys, runs once immediately, and publishes each
- * result to a queue or stream. Invalidating any registered key schedules the
- * query to rerun. Mutations wrap an effect and invalidate keys only after it
- * succeeds. Keys can be a flat array, or a record whose property names act as
- * broad namespaces and whose ids address individual records.
- *
- * **Common tasks**
- *
- * - Provide the default in-memory service with {@link layer}.
- * - Use {@link query} when callers need a queue of rerun results.
- * - Use {@link stream} when downstream code should consume reruns as a stream.
- * - Wrap writes with {@link mutation}, or call {@link invalidate} directly when
- *   invalidation is already part of the workflow.
- * - Use the {@link Reactivity} service directly when many invalidations should
- *   be coalesced until a batch exits.
- *
- * **Gotchas**
- *
- * - The default layer is process-local; it does not coordinate invalidations
- *   across processes or cluster runners.
- * - Non-primitive keys are matched by their `Hash.hash` value, so prefer stable
- *   key values over mutable objects.
- * - If a query fails, its queue or stream fails with the same cause.
- * - Invalidations that arrive while a query is already running coalesce into one
- *   follow-up run.
- *
- * **See also**
- *
- * - {@link query}, {@link stream}, {@link mutation}, and {@link invalidate}
- * - {@link layer} and {@link Reactivity}
+ * This module does not cache values itself. It lets callers register handlers
+ * for keys, invalidate those keys, wrap successful mutations so they invalidate
+ * keys, and expose effects as queues or streams that rerun when matching keys
+ * change. The service can also batch invalidations so handlers run after the
+ * batch completes.
  *
  * @since 4.0.0
  */

package/src/unstable/rpc/Rpc.ts

@@ -1,44 +1,12 @@
 /**
- * Schema-backed declarations for individual RPC procedures.
- *
- * An {@link Rpc} is the shared contract for one remote procedure. It records
- * the procedure tag, payload schema, success schema, error schema, defect
- * schema, middleware, annotations, and the type information used to derive
- * client calls and server handler signatures. The declaration is transport
- * independent; RPC groups, clients, and servers all read the same metadata.
- *
- * **Mental model**
- *
- * An RPC definition is data. The tag names the procedure, the schemas describe
- * the values crossing the wire, and middleware or annotations attach
- * procedure-local behavior and metadata. Nothing is sent or handled until the
- * definition is placed in a group and interpreted by a client or server.
- *
- * **Common tasks**
- *
- * Use {@link make} for ordinary request/response procedures, {@link custom} for
- * constructors that transform success or error schemas, and the instance
- * methods on {@link Rpc} to refine payloads, attach middleware, prefix tags, or
- * add annotations. Helper types such as {@link Payload}, {@link Success},
- * {@link Error}, and {@link ToHandlerFn} expose the derived TypeScript shapes
- * used by client and handler code. Server handlers can wrap object results with
- * {@link fork} or {@link uninterruptible} to control how those results are run.
- *
- * **Gotchas**
- *
- * - Payloads default to `Schema.Void`; passing struct fields creates a
- *   `Schema.Struct`, while `primaryKey` creates a payload class with a derived
- *   `PrimaryKey`
- * - Success values default to `Schema.Void`, ordinary errors default to
- *   `Schema.Never`, and middleware errors are included in the effective RPC
- *   error channel
- * - Streaming RPCs store element and stream-error schemas in
- *   `RpcSchema.Stream`; the immediate exit success is `void` and the ordinary
- *   RPC error schema is `Schema.Never`
- * - Defects use a separate defect schema, defaulting to `Schema.Defect()`; custom
- *   defect schemas must not require decoding or encoding services
- * - Schema services are directional: clients encode payloads and decode
- *   responses, while servers decode payloads and encode responses
+ * Defines schema-backed contracts for individual RPC procedures.
+ *
+ * An `Rpc` describes one remote procedure by recording its tag, payload schema,
+ * success schema, error schema, defect schema, middleware, and annotations.
+ * Clients and servers read the same declaration, so the procedure contract is
+ * independent of the transport used to call it. This module includes
+ * constructors, type helpers for deriving client and handler shapes, exit
+ * schemas, and handler wrappers for special execution modes.
  *
  * @since 4.0.0
  */

package/src/unstable/rpc/RpcClient.ts

@@ -1,38 +1,12 @@
 /**
- * Client-side runtime for typed RPC calls.
+ * Runs typed RPC calls from the client side.
  *
  * This module turns RPC definitions from an `RpcGroup` into callable client
- * methods. Each method encodes its payload, sends a request through the active
- * transport, and routes the matching server response back to the waiting
- * `Effect` or `Stream`.
- *
- * **Mental model**
- *
- * `make` builds a schema-aware client on top of a client `Protocol`. The
- * protocol owns the encoded transport boundary: HTTP sends one request per
- * call, while socket and worker protocols keep receive loops alive for
- * streaming, acknowledgements, interruption, and protocol-level failures.
- * `makeNoSerialization` keeps the same request lifecycle when another layer has
- * already decoded messages.
- *
- * **Common tasks**
- *
- * - Build a typed client with {@link make} and a provided protocol layer
- * - Use {@link makeNoSerialization} for in-process or already-decoded channels
- * - Provide HTTP, socket, or worker transports with {@link layerProtocolHttp},
- *   {@link layerProtocolSocket}, or {@link layerProtocolWorker}
- * - Add request headers with {@link withHeaders} or per-call options
- *
- * **Gotchas**
- *
- * HTTP does not support client acknowledgements, so streaming back pressure is
- * only available on protocols that keep a live channel. Streaming RPCs return
- * `Stream`s by default; enabling `asQueue` returns a scoped queue whose buffer
- * size is controlled by `streamBufferSize`. Payloads, exits, stream chunks, and
- * middleware errors are encoded and decoded through RPC schemas, so any schema
- * services required by those codecs remain in the generated method
- * environment. Client middleware can rewrite or short-circuit requests and adds
- * its client error type to the call signature.
+ * methods. Each call encodes its payload, sends a message through the active
+ * `Protocol`, decodes exits or stream chunks from the server, and routes the
+ * response back to the waiting `Effect`, `Stream`, or queue. It also defines
+ * the protocol service and includes protocol layers for HTTP, sockets, and
+ * workers.
  *
  * @since 4.0.0
  */

package/src/unstable/rpc/RpcClientError.ts

@@ -6,29 +6,6 @@
  * covers built-in transport failures from HTTP, sockets, and workers, plus
  * `RpcClientDefect` values for malformed or incompatible protocol data.
  *
- * **Mental model**
- *
- * Handler errors belong to the RPC's declared error schema and are decoded from
- * the response exit. Client errors describe the client or transport boundary:
- * unavailable transport, aborted connections, unreadable response bodies,
- * failed response decoding, or protocol shapes that do not match the RPC group
- * the client was built for. Treat them as infrastructure or compatibility
- * failures rather than business-domain failures.
- *
- * **Common tasks**
- *
- * Inspect `error.reason._tag` to decide whether to retry, reconnect, report a
- * transport issue, or surface a schema or codec mismatch. Custom protocols can
- * use `RpcClientDefect` to put invalid client-side protocol state in the same
- * public error channel used by the built-in transports.
- *
- * **Gotchas**
- *
- * Server defects are sent through protocol messages and normally fail the call
- * as defects rather than as declared RPC errors. Serialization and schema
- * decode failures can appear as client defects because the client cannot safely
- * produce the typed success or error value promised by the RPC definition.
- *
  * @since 4.0.0
  */
 import * as Schema from "../../Schema.ts"

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