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

package/src/unstable/cluster/Runners.ts

@@ -1,33 +1,12 @@
 /**
- * The `Runners` module defines the service used by the unstable cluster runtime
- * to communicate with processes that host entity shards. It is the transport
- * boundary between sharding decisions and runner execution: callers can ping a
- * runner, send requests or envelopes, notify a runner that persisted work is
- * available, and report an address as unavailable.
+ * Handles communication between Effect Cluster runners.
  *
- * The default implementation wraps lower-level runner callbacks with cluster
- * message semantics. Persisted messages are written to `MessageStorage` before
- * delivery, duplicate requests can resume from stored replies, and local sends
- * can optionally serialize and deserialize messages to exercise the same path as
- * remote delivery.
- *
- * **Common tasks**
- *
- * - Provide runner communication with {@link layerRpc}
- * - Build a custom implementation with {@link make}
- * - Use {@link makeNoop} or {@link layerNoop} when no remote runners are
- *   available
- * - Define runner-to-runner protocol support with {@link Rpcs} and
- *   {@link RpcClientProtocol}
- *
- * **Gotchas**
- *
- * - `notify` is only for RPCs annotated as persisted; non-persisted messages
- *   should be sent directly.
- * - Failed remote sends can fall back to reading replies from storage, so reply
- *   polling and `entityReplyPollInterval` affect recovery latency.
- * - Unavailable runners invalidate cached RPC clients, but shard ownership and
- *   rebalancing are coordinated by the sharding layer rather than this module.
+ * `Runners` sits between sharding decisions and runner execution. It can ping a
+ * runner, send requests or control envelopes, notify a runner that persisted
+ * work is available, and record that a runner address is unavailable. This
+ * module defines the runner communication service, its RPC protocol, no-op and
+ * RPC-backed implementations, local persistence support, reply recovery, and
+ * the protocol service used by transport-specific runner layers.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/ShardId.ts

@@ -5,23 +5,6 @@
  * schema support, and conversion to and from the `group:id` string form used by
  * routing and storage boundaries.
  *
- * **Common tasks**
- *
- * - Create or reuse a cached shard identifier with {@link make}
- * - Check runtime values with {@link isShardId}
- * - Encode or decode shard identifiers with {@link ShardId}
- * - Format for logs, persistence, or transport with {@link toString}
- * - Parse encoded shard keys with {@link fromString} or {@link fromStringEncoded}
- *
- * **Gotchas**
- *
- * - Equality and hashing are based on the `group:id` representation, so both
- *   fields must match for two shard ids to be equal
- * - Encoded strings are split at the last `:`; groups may contain colons, but
- *   ids must parse as numbers
- * - This module identifies shards after a routing or hashing decision; it does
- *   not choose a shard for an arbitrary entity key
- *
  * @since 4.0.0
  */
 import * as Equal from "../../Equal.ts"

package/src/unstable/cluster/Sharding.ts

@@ -1,44 +1,12 @@
 /**
- * The `Sharding` module provides the runtime service that maps entity ids to
- * shard ids, decides which runner owns each shard, and delivers cluster
- * messages to the owning runner. It connects typed entity protocols with runner
- * membership, shard locks, mailbox storage, and the transport used between
- * runners.
+ * Runs shard ownership and message routing for Effect Cluster.
  *
- * **Mental model**
- *
- * - Entity ids are hashed into shard ids inside a shard group.
- * - Healthy runners are placed on a hash ring for each shard group.
- * - The local runner starts handlers only for shards it currently owns.
- * - Clients created by {@link Sharding.Service.makeClient} route encoded RPC requests
- *   to the current owner instead of calling handlers directly.
- * - Persisted messages are polled from storage and replayed only for shards the
- *   local runner owns.
- *
- * **Common tasks**
- *
- * - Register entity handlers with {@link Sharding.Service.registerEntity}.
- * - Register singleton effects that run once per shard group with
- *   {@link Sharding.Service.registerSingleton}.
- * - Build typed entity clients with {@link Sharding.Service.makeClient}.
- * - Send an already encoded incoming message with {@link Sharding.Service.send}.
- * - Generate runner-local snowflake ids with {@link Sharding.Service.getSnowflake}.
- *
- * **Gotchas**
- *
- * - Assignment and acquisition are separate: a runner may be assigned a shard
- *   before it has acquired the storage lock.
- * - Changing shard group names, shard counts, or runner weights changes
- *   placement for entity ids.
- * - Ownership can move during shutdown, runner failure, or health refreshes, so
- *   callers must handle routing and mailbox errors.
- * - Durable replay depends on the configured message storage; in-memory storage
- *   does not provide process restart recovery.
- *
- * **See also**
- *
- * - {@link ShardingConfig} for runner identity, shard counts, and timing.
- * - {@link Runner} for the membership record used during shard assignment.
+ * `Sharding` decides which shard owns an entity id, tracks which shards belong
+ * to the local runner, and sends cluster messages to local handlers or remote
+ * runners. It also registers entities and singletons, creates clients for
+ * entity requests, polls stored messages, and tracks shutdown state. The main
+ * layer connects these responsibilities to runner communication, storage,
+ * health checks, configuration, and local resources.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/ShardingConfig.ts

@@ -1,39 +1,12 @@
 /**
- * The `ShardingConfig` module describes how an Effect Cluster runner joins and
- * participates in sharding. It combines the runner network identity, shard group
- * membership, shard-count and weight settings, storage-lock timing, entity
- * mailbox and lifecycle limits, and polling intervals used by the local runner.
+ * Configures how an Effect Cluster runner participates in sharding.
  *
- * **Mental model**
- *
- * - {@link ShardingConfig} is provided as a service so cluster components read
- *   one consistent set of sharding settings.
- * - {@link defaults} is the local-development baseline; {@link layer} overlays
- *   explicit values, and {@link layerFromEnv} loads constant-case environment
- *   variables before applying optional overrides.
- * - `runnerAddress` is the externally reachable address advertised to other
- *   runners; `runnerListenAddress` can differ when the process binds a
- *   different interface.
- * - `availableShardGroups`, `assignedShardGroups`, `shardsPerGroup`, and
- *   `runnerShardWeight` decide which shards a runner may own and how assignment
- *   is balanced.
- *
- * **Common tasks**
- *
- * - Provide default local configuration with {@link layerDefaults}.
- * - Override selected fields in code with {@link layer}.
- * - Load deployment configuration from the environment with
- *   {@link configFromEnv} or {@link layerFromEnv}.
- * - Normalize configured shard groups with {@link shardGroupConfig}.
- *
- * **Gotchas**
- *
- * - Keep cluster-wide values such as `availableShardGroups` and
- *   `shardsPerGroup` consistent for runners sharing the same storage backend.
- * - Use stable, reachable `runnerAddress` values; client-only nodes should use
- *   `Option.none()` for `runnerAddress`.
- * - Tune lock expiration, refresh intervals, and termination timeouts together
- *   so normal shutdown does not look like runner failure.
+ * `ShardingConfig` describes the runner address, shard group membership, shard
+ * counts and weights, lock timing, entity mailbox and lifecycle limits, polling
+ * intervals, health checks, and local serialization simulation. This module
+ * includes the service, default values, programmatic and environment-based
+ * layers, a `Config` description for loading values, and helpers for normalizing
+ * assigned shard groups.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/ShardingRegistrationEvent.ts

@@ -5,28 +5,6 @@
  * inspect which capabilities a runner made available, or assert registration
  * behavior in tests.
  *
- * **Mental model**
- *
- * Registration is local capability discovery. An `EntityRegistered` event means
- * this runner has installed handlers for an entity type; a `SingletonRegistered`
- * event carries the `SingletonAddress` computed for the singleton name and shard
- * group. Neither event means the runner currently owns the relevant shard or has
- * started processing stored messages.
- *
- * **Common tasks**
- *
- * - Consume `Sharding.getRegistrationEvents` in tests or startup coordination
- * - Match on entity and singleton registrations with the generated `match`
- *   helper
- * - Record registered entity types and singleton addresses for diagnostics
- *
- * **Gotchas**
- *
- * - Events are live in-memory notifications; they are not stored or replayed for
- *   later subscribers
- * - Shard acquisition, singleton execution, and persisted mailbox polling happen
- *   after registration and may move as runner membership changes
- *
  * @since 4.0.0
  */
 import * as Data from "../../Data.ts"

package/src/unstable/cluster/SingleRunner.ts

@@ -1,25 +1,12 @@
 /**
- * The `SingleRunner` module provides a ready-to-use layer for running the
- * cluster sharding services in a single process. It wires together sharding,
- * message storage, runner registration, runner health, and sharding
- * configuration so durable entities and workflows can run without a fleet of
- * external runners.
+ * Single-process cluster layer for durable entities and workflows. It wires
+ * `Sharding` with no-op runner communication, no-op runner health checks,
+ * SQL-backed message storage, environment-based sharding configuration, and
+ * either SQL-backed or in-memory runner storage.
  *
- * **Common tasks**
- *
- * - Start a local or embedded cluster runner backed by SQL message storage
- * - Run durable entities and workflows in development, tests, or small
- *   single-node deployments
- * - Choose SQL runner storage for persistence or in-memory runner storage for
- *   short-lived scenarios
- * - Override sharding configuration while still using the standard
- *   environment-based defaults
- *
- * **Gotchas**
- *
- * - The layer still requires a `SqlClient` because message storage is SQL-backed
- * - Runner health and runner coordination are no-op implementations, so this is
- *   for single-node use rather than multi-runner cluster coordination
+ * This layer is meant for local, embedded, or small single-node setups where the
+ * process handles all cluster work itself. It still requires a SQL client
+ * because mailbox messages and replies are stored in SQL.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/Singleton.ts

@@ -6,29 +6,6 @@
  * sharding starts the effect; when ownership moves or the layer scope closes,
  * the running fiber is interrupted and the registration is removed.
  *
- * **Mental model**
- *
- * A singleton is still placed on a shard. Its name and optional shard group
- * determine the shard id, and the runner that acquires that shard lock is the
- * only runner allowed to execute it. Failover is handled by shard ownership, so
- * another runner can resume the singleton after the previous owner leaves.
- *
- * **Common tasks**
- *
- * - Start one scheduler, consumer, polling loop, or maintenance process for a
- *   whole cluster
- * - Register that process as part of application wiring with `Layer`
- * - Choose a `shardGroup` when singleton ownership should be coordinated with a
- *   specific group of clustered work
- *
- * **Gotchas**
- *
- * - Design the effect to be interruptible and idempotent; ownership can move
- *   while work is in flight.
- * - Duplicate singleton names in the same shard group fail during registration.
- * - Handle expected failures inside the effect when it should keep running,
- *   because unhandled failures are surfaced as defects by sharding.
- *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.ts"

package/src/unstable/cluster/SingletonAddress.ts

@@ -5,28 +5,6 @@
  * stable value for registration events, equality, hashing, and local singleton
  * fiber tracking.
  *
- * **Mental model**
- *
- * A singleton does not have an entity id supplied by the caller. During
- * registration, `Sharding` hashes the singleton name within a shard group and
- * records the resulting shard id next to the name. When the local runner
- * acquires that shard, the singleton can run; when ownership moves away, the
- * address stays the same and the local singleton fiber is stopped.
- *
- * **Common tasks**
- *
- * - Read the address carried by singleton registration events
- * - Compare singleton registrations by both name and shard id
- * - Include the name and shard id in logs or diagnostics about singleton
- *   ownership changes
- *
- * **Gotchas**
- *
- * - The same singleton name in different shard groups produces different
- *   addresses
- * - An address identifies the shard responsible for a singleton, not the runner
- *   currently executing it
- *
  * @since 4.0.0
  */
 import * as Equal from "../../Equal.ts"

package/src/unstable/cluster/Snowflake.ts

@@ -1,21 +1,12 @@
 /**
- * The `Snowflake` module provides compact, sortable identifiers for cluster
- * resources and events. A snowflake id is a branded `bigint` made from a
- * millisecond timestamp, a machine id, and a per-machine sequence number.
+ * Creates compact, sortable identifiers for cluster messages and runtime
+ * events.
  *
- * **Common use cases**
- *
- * - Creating ids without coordinating through a central database
- * - Ordering cluster events, entity ids, or log records by generation time
- * - Encoding ids as strings at service boundaries with {@link SnowflakeFromString}
- * - Decoding a generated id into timestamp, machine id, and sequence parts with {@link toParts}
- *
- * **Gotchas**
- *
- * - Uniqueness depends on each concurrent generator using a distinct machine id
- * - Generated ids are time-sortable, but they are not random or secret values
- * - The default generator prevents local clock drift from moving ids backward
- * - More than 4096 ids in the same millisecond advance the logical timestamp
+ * A snowflake id is a branded `bigint` built from a millisecond timestamp, a
+ * machine id, and a sequence number for that machine. The parts make generated
+ * ids sortable by time while still being unique for a runner. This module
+ * includes schemas for bigint and string encodings, helpers for creating and
+ * reading ids, and a `Clock`-backed generator service for cluster runtime use.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/SocketRunner.ts

@@ -1,24 +1,11 @@
 /**
- * The `SocketRunner` module wires cluster runner RPCs to socket transports. It
- * provides a complete runner layer that serves RPC handlers on a `SocketServer`
- * and installs `Sharding` and `Runners` clients for talking to other runners
- * through the socket RPC protocol.
+ * Runs cluster runner RPCs over a socket transport.
  *
- * **Common tasks**
- *
- * - Run a cluster worker over TCP or Unix sockets with {@link layer}
- * - Connect to other runners while exposing `Sharding` and `Runners` clients
- * - Embed a client-only cluster participant with {@link layerClientOnly} when
- *   the process should send messages but not receive shard assignments
- *
- * **Transport gotchas**
- *
- * - The server listen address comes from the provided `SocketServer` and is
- *   logged when {@link layer} starts
- * - TCP addresses are logged as `hostname:port`, while Unix socket addresses
- *   are logged as their filesystem path
- * - The client-only layer does not start a socket server; provide the full
- *   layer when the process must accept runner RPCs
+ * The full layer serves runner RPC handlers on a provided `SocketServer`, logs
+ * the bound address, and provides `Sharding` and `Runners` clients when an
+ * outgoing runner client protocol is available. This module also includes a
+ * client-only socket runner layer for processes that need cluster clients
+ * without starting a runner server or receiving shard assignments.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/SqlMessageStorage.ts

@@ -1,41 +1,12 @@
 /**
- * SQL-backed `MessageStorage` implementation for the unstable cluster runtime.
+ * Persists cluster mailbox messages and replies in SQL.
  *
- * This module persists encoded cluster envelopes and replies in SQL so runners
- * can recover mailbox state after restarts, redeliver unprocessed messages,
- * deduplicate requests by primary key, and replay reply chunks until they are
- * acknowledged. It is the durable alternative to an in-memory mailbox when
- * cluster request/reply state must survive process restarts.
- *
- * **Mental model**
- *
- * The storage owns two durable streams: a messages table for requests and
- * control envelopes, and a replies table for chunk and final replies. Saving a
- * request or envelope writes encoded data into the messages table; reading
- * unprocessed messages claims due rows for assigned shards; reading replies
- * replays unacknowledged chunks or final exits until the runtime acknowledges
- * or clears them. Primary keys are stored as `message_id` so repeated requests
- * can resume from the original request and last persisted reply.
- *
- * **Common tasks**
- *
- * - Use `layer` for the default `cluster` table prefix and default snowflake
- *   generator.
- * - Use `layerWith` before deployment when the application needs a stable
- *   custom table prefix.
- * - Use `make` when composing the storage service with an existing
- *   `Snowflake.Generator`.
- * - Provide `SqlClient` and `ShardingConfig` to the layer that installs the
- *   storage.
- *
- * **Gotchas**
- *
- * `make` runs migrations and creates `<prefix>_messages`, `<prefix>_replies`,
- * and `<prefix>_migrations`. Changing `prefix` after deployment points the
- * runtime at a different mailbox and migration history, so keep the generated
- * migration table with the message tables. Unprocessed-message reads use
- * `last_read` as a lease marker, so messages can be redelivered after the lease
- * window if a runner stops before processing them.
+ * The SQL-backed `MessageStorage` stores encoded cluster envelopes and reply
+ * chunks so runners can recover mailbox state after restarts. It supports
+ * redelivering unprocessed messages, deduplicating requests by primary key, and
+ * replaying reply chunks until they are acknowledged. This module includes the
+ * storage constructor, layers, migrations, optional table prefixes, and the row
+ * mapping needed by encoded message storage.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/SqlRunnerStorage.ts

@@ -1,32 +1,11 @@
 /**
- * SQL-backed storage for Effect Cluster runner metadata and shard ownership.
+ * Stores cluster runner registration and shard ownership in SQL.
  *
- * The `SqlRunnerStorage` module builds a `RunnerStorage` implementation from a
- * `SqlClient`, creating the runner and lock tables it needs using the configured
- * table prefix. It is used by clustered applications that need runner
- * registration, health tracking, shard acquisition, refresh, and release to be
- * coordinated through an external database instead of in-memory state.
- *
- * **Common tasks**
- *
- * - Provide the default storage layer with {@link layer}
- * - Use {@link layerWith} when multiple clusters share the same database and
- *   need distinct table prefixes
- * - Create a storage implementation directly with {@link make} for custom layer
- *   composition
- *
- * **Gotchas**
- *
- * - Runner heartbeats and persisted shard locks expire according to
- *   `ShardingConfig.shardLockExpiration`; stale rows may be reused or cleaned up
- *   by later storage operations.
- * - PostgreSQL and MySQL use advisory locks by default, keeping shard ownership
- *   tied to a reserved database connection. Set
- *   `ShardingConfig.shardLockDisableAdvisory` when persisted lock rows should be
- *   used instead.
- * - The selected table prefix controls the generated `runners` and `locks`
- *   table names, so changing it points the cluster at a different storage
- *   namespace.
+ * The SQL-backed `RunnerStorage` records runners, health flags, machine ids,
+ * and shard locks so multiple processes can coordinate which runner owns each
+ * shard. This module creates the required runner and lock tables, supports an
+ * optional table prefix, uses advisory locks for PostgreSQL and MySQL when
+ * enabled, and provides constructors and layers for the storage service.
  *
  * @since 4.0.0
  */

package/src/unstable/cluster/TestRunner.ts

@@ -6,27 +6,6 @@
  * coordination, and mailbox persistence without starting RPC servers or
  * external databases.
  *
- * **Mental model**
- *
- * The layer behaves like a single in-process runner using the default
- * `ShardingConfig`. Sharding still computes shard ids, acquires in-memory shard
- * locks, stores persisted messages, and emits registration events, but remote
- * runner communication is deliberately absent.
- *
- * **Common tasks**
- *
- * - Provide cluster services around tests for sharded entities and singletons
- * - Exercise persisted mailbox behavior with the in-memory message store
- * - Observe registration events without starting a real runner process
- *
- * **Gotchas**
- *
- * - State is scoped to each layer instance and disappears when the layer closes
- * - No-op runner transport cannot deliver work to another process, so
- *   multi-runner tests should provide their own `Runners` implementation
- * - No-op health checks treat every runner as healthy and do not model
- *   failure-driven rebalancing
- *
  * @since 4.0.0
  */
 import * as Layer from "../../Layer.ts"

package/src/unstable/cluster/internal/entityManager.ts

@@ -145,7 +145,8 @@ export const make = Effect.fnUntraced(function*<
     )
 
     const activeRequests: EntityState["activeRequests"] = new Map()
-    let defectRequestIds: Array<bigint> = []
+    let defectRequestIds = new Set<bigint>()
+    let isRestartingDueToDefect = false
 
     // the server is stored in a ref, so if there is a defect, we can
     // swap the server without losing the active requests
@@ -186,6 +187,14 @@ export const make = Effect.fnUntraced(function*<
 
                 request.sentReply = true
 
+                if (
+                  isShuttingDown &&
+                  Exit.hasInterrupts(response.exit) &&
+                  defectRequestIds.has(response.requestId)
+                ) {
+                  return Effect.void
+                }
+
                 // For durable messages, ignore interrupts during shutdown.
                 // They will be retried when the entity is restarted.
                 // Also, if the request is uninterruptible, we ignore the
@@ -281,9 +290,11 @@ export const make = Effect.fnUntraced(function*<
           })
         )
 
-        if (defectRequestIds.length > 0) {
+        if (defectRequestIds.size > 0) {
           for (const id of defectRequestIds) {
-            const { lastSentChunk, message } = activeRequests.get(id)!
+            const request = activeRequests.get(id)
+            if (!request) continue
+            const { lastSentChunk, message } = request
             yield* server.write(0, {
               ...message.envelope,
               id: RequestId(message.envelope.requestId),
@@ -294,7 +305,7 @@ export const make = Effect.fnUntraced(function*<
               } as any) as any
             })
           }
-          defectRequestIds = []
+          defectRequestIds.clear()
         }
 
         return server.write
@@ -305,11 +316,18 @@ export const make = Effect.fnUntraced(function*<
       if (!activeServers.has(address.entityId)) {
         return endLatch.open
       }
+      if (isRestartingDueToDefect) {
+        return Effect.void
+      }
+      defectRequestIds = new Set(activeRequests.keys())
+      isRestartingDueToDefect = true
       const effect = writeRef.rebuildUnsafe()
-      defectRequestIds = Array.from(activeRequests.keys())
       return Effect.logError("Defect in entity, restarting", cause).pipe(
         Effect.andThen(Effect.ignore(retryDriver(void 0))),
         Effect.flatMap(() => activeServers.has(address.entityId) ? effect : endLatch.open),
+        Effect.ensuring(Effect.sync(() => {
+          isRestartingDueToDefect = false
+        })),
         Effect.annotateLogs({
           module: "EntityManager",
           address,

package/src/unstable/devtools/DevTools.ts

@@ -7,23 +7,6 @@
  * and metric snapshots to an external devtools process. Lower-level socket
  * protocol details live in `DevToolsClient`.
  *
- * **Common tasks**
- *
- * - Use {@link layer} when the runtime provides a global `WebSocket`
- * - Use {@link layerWebSocket} when the environment should provide the
- *   `WebSocketConstructor`
- * - Use {@link layerSocket} when an integration already has a `Socket`
- *   transport
- *
- * **Gotchas**
- *
- * - The WebSocket helpers default to `ws://localhost:34437`.
- * - These layers install only the client-side tracer; start or connect the
- *   devtools server separately.
- * - The tracer is scoped to the runtime or layer graph that receives the layer.
- * - This module is under `unstable`, so the transport protocol and exports may
- *   change between releases.
- *
  * @since 4.0.0
  */
 import * as Layer from "../../Layer.ts"

package/src/unstable/devtools/DevToolsClient.ts

@@ -6,30 +6,6 @@
  * ping messages, and metric snapshots through a socket, then exposes tracer
  * layers that forward telemetry while preserving the current tracer's behavior.
  *
- * **Mental model**
- *
- * {@link make} creates the scoped client service over the provided `Socket`;
- * {@link makeTracer} wraps the current tracer and sends each span update
- * through that client; {@link layerTracer} combines both steps for integrations
- * that already have a socket transport. The higher-level `DevTools` module
- * provides WebSocket defaults for applications.
- *
- * **Common tasks**
- *
- * - Build the client service directly with {@link make} or {@link layer}
- * - Install only the forwarding tracer with {@link makeTracer}
- * - Create the client and tracer together with {@link layerTracer}
- * - Send custom span or span-event messages through `DevToolsClient.sendUnsafe`
- *
- * **Gotchas**
- *
- * - The client is scoped because it starts background fibers for the socket
- *   stream and heartbeat.
- * - `sendUnsafe` enqueues telemetry without back pressure and should stay on
- *   the tracer hot path.
- * - This module does not create a socket transport; provide `Socket` yourself
- *   or use the higher-level `DevTools` module.
- *
  * @since 4.0.0
  */
 import * as Cause from "../../Cause.ts"

package/src/unstable/devtools/DevToolsSchema.ts

@@ -7,23 +7,6 @@
  * boundaries to encode, decode, or validate custom transports that need to
  * interoperate with the built-in unstable devtools client and server.
  *
- * **Mental model**
- *
- * `Request` messages flow from the runtime-side devtools client to the server:
- * `Ping`, `Span`, `SpanEvent`, and `MetricsSnapshot`. `Response` messages flow
- * back from the server: `Pong` and `MetricsRequest`. The `WithoutPing` and
- * `WithoutPong` helper types match the server behavior, where heartbeat
- * messages are handled internally and user handlers see only application-level
- * protocol messages.
- *
- * **Gotchas**
- *
- * These schemas describe transport payloads, not the full in-memory tracer or
- * metric data structures. Ended span exits erase successful values with
- * `Exit.asVoid`, timestamps are represented as `bigint`s, and attributes remain
- * intentionally open-ended. Because this module lives under `unstable`, the
- * protocol shape may change between releases.
- *
  * @since 4.0.0
  */
 import * as Exit from "../../Exit.ts"

package/src/unstable/devtools/DevToolsServer.ts

@@ -7,19 +7,6 @@
  * metrics itself; it gives handlers a typed surface for the telemetry described
  * by `DevToolsSchema`.
  *
- * **Mental model**
- *
- * Each accepted socket becomes one `Client`. Incoming `Ping` requests are
- * answered internally with `Pong`, while all other decoded requests are offered
- * to the client's queue. Handler code reads that queue and sends non-pong
- * responses such as `MetricsRequest` through `Client.send`.
- *
- * **Gotchas**
- *
- * The client queue is scoped to the socket-processing fiber and is shut down
- * when that fiber terminates. Treat it as per-connection state, not as a
- * process-wide telemetry bus.
- *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.ts"