opencode-effect-enforcer 0.2.8 → 0.3.0

package/skills/effect-rpc-api/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: effect-rpc-api
-description: Define type-safe RPC contracts with effect/unstable/rpc — Rpc.make payload/success/error/defect schemas, RpcSchema.Stream streaming responses, RpcGroup composition (add/merge/omit/prefix/annotate), and RpcMiddleware.Service definitions shared by client and server. Use when declaring or evolving RPC procedures, building a shared contract package, adding streaming endpoints, or defining auth/observability middleware types.
+description: Define type-safe RPC contracts with effect/rpc — Rpc.make payload/success/error/defect schemas, RpcSchema.Stream streaming responses, RpcGroup composition (add/merge/omit/prefix/annotate), and RpcMiddleware.Service definitions shared by client and server. Use when declaring or evolving RPC procedures, building a shared contract package, adding streaming endpoints, or defining auth/observability middleware types.
 ---
 
-You are an Effect TypeScript expert specializing in defining shared RPC contracts with `Rpc`, `RpcGroup`, `RpcSchema`, and `RpcMiddleware` from `effect/unstable/rpc`.
+You are an Effect TypeScript expert specializing in defining shared RPC contracts with `Rpc`, `RpcGroup`, `RpcSchema`, and `RpcMiddleware` from `effect/rpc`.
 
 This skill covers the **contract layer**: the definitions that client and server packages both import. Wiring handlers into a server is the `effect-rpc-server` skill; constructing clients and protocols is the `effect-rpc-client` skill; distributed entities are the `effect-rpc-cluster` skill.
 
@@ -16,17 +16,17 @@ implementations must supply `codecFor` (see `effect-rpc-client` /
 `effect-rpc-server`). JSON, NDJSON, and JSON-RPC formats use
 their wire representation; the new SchemaBinary transport has its own codecs.
 
-The Effect v4 source is at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`. Read it directly when in doubt — these modules are under `unstable` and move between betas.
+The Effect v4 source is at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`. Read the `effect@4.0.0` tag for this skill; main may be newer. These APIs remain `@stability unstable` and may break in minor releases despite the shorter imports. Keep Effect-family packages on the same release.
 
 Key files:
 
-- `packages/effect/src/unstable/rpc/Rpc.ts` — `Rpc.make`, `Rpc.custom`, per-rpc combinators, `exitSchema`, `Wrapper` (`fork`/`uninterruptible`/`wrap`), `ServerClient`, every type helper (`Payload`, `Success`, `Error`, `Exit`, `ToHandlerFn`, `ResultFrom`, ...)
-- `packages/effect/src/unstable/rpc/RpcGroup.ts` — group construction and composition (`add`/`merge`/`omit`/`prefix`/`middleware`), group vs per-rpc annotations, handler-conversion surface (`toLayer`/`toHandlers`/`toLayerHandler`/`accessHandler`/`of`)
-- `packages/effect/src/unstable/rpc/RpcSchema.ts` — the `Stream` schema marker, `isStreamSchema`, `ClientAbort` cause annotation
-- `packages/effect/src/unstable/rpc/RpcMiddleware.ts` — `Service` constructor, `layerClient`, `ForClient`, `ApplyServices` and the middleware function shapes
-- `packages/effect/src/unstable/rpc/RpcMessage.ts` — wire envelopes: `Request`, `Ack`, `Interrupt`, `Eof`, `Ping`, `ResponseChunk`, `ResponseExit`, `ExitEncoded`, `RequestId`
-- `packages/effect/src/unstable/rpc/RpcClientError.ts` — the transport error type referenced when typing shared client aliases
-- `packages/effect/src/unstable/rpc/index.ts` — public exports of the rpc namespace
+- `packages/effect/src/rpc/Rpc.ts` — `Rpc.make`, `Rpc.custom`, per-rpc combinators, `exitSchema`, `Wrapper` (`fork`/`uninterruptible`/`wrap`), `ServerClient`, every type helper (`Payload`, `Success`, `Error`, `Exit`, `ToHandlerFn`, `ResultFrom`, ...)
+- `packages/effect/src/rpc/RpcGroup.ts` — group construction and composition (`add`/`merge`/`omit`/`prefix`/`middleware`), group vs per-rpc annotations, handler-conversion surface (`toLayer`/`toHandlers`/`toLayerHandler`/`accessHandler`/`of`)
+- `packages/effect/src/rpc/RpcSchema.ts` — the `Stream` schema marker, `isStreamSchema`, `ClientAbort` cause annotation
+- `packages/effect/src/rpc/RpcMiddleware.ts` — `Service` constructor, `layerClient`, `ForClient`, `ApplyServices` and the middleware function shapes
+- `packages/effect/src/rpc/RpcMessage.ts` — wire envelopes: `Request`, `Ack`, `Interrupt`, `Eof`, `Ping`, `ResponseChunk`, `ResponseExit`, `ExitEncoded`, `RequestId`
+- `packages/effect/src/rpc/RpcClientError.ts` — the transport error type referenced when typing shared client aliases
+- `packages/effect/src/rpc/index.ts` — public exports of the rpc namespace
 - `packages/platform/node/test/fixtures/rpc-schemas.ts` — the best real-world contract fixture: rpcs, streaming, middleware, deferred responses
 - `packages/effect/test/rpc/Rpc.test.ts` — `exitSchema`, custom defect schemas, `getStreamSchemas` semantics
 
@@ -54,10 +54,10 @@ Imports used throughout (all from the `effect` package; there is no `@effect/rpc
 
 ```ts
 import { Context, Schema } from 'effect';
-import { Rpc, RpcGroup, RpcMiddleware, RpcSchema } from 'effect/unstable/rpc';
+import { Rpc, RpcGroup, RpcMiddleware, RpcSchema } from 'effect/rpc';
 ```
 
-Deep subpath imports also work (the package exports a `./*` wildcard), e.g. `import * as RpcSchema from 'effect/unstable/rpc/RpcSchema'` or `import { RpcClientError } from 'effect/unstable/rpc/RpcClientError'`.
+Deep subpath imports also work (the package exports a `./*` wildcard), e.g. `import * as RpcSchema from 'effect/rpc/RpcSchema'` or `import { RpcClientError } from 'effect/rpc/RpcClientError'`.
 
 ---
 
@@ -78,7 +78,7 @@ Two declaration styles, both official:
 
 ```ts
 import { Schema } from 'effect';
-import { Rpc } from 'effect/unstable/rpc';
+import { Rpc } from 'effect/rpc';
 
 export class User extends Schema.Class<User>('User')({
 	id: Schema.String,
@@ -308,7 +308,7 @@ A middleware is declared as a `Context.Service` class with two parameter slots:
 
 ```ts
 import { Context, Schema } from 'effect';
-import { RpcMiddleware } from 'effect/unstable/rpc';
+import { RpcMiddleware } from 'effect/rpc';
 
 export class CurrentUser extends Context.Service<CurrentUser, User>()('CurrentUser') {}
 
@@ -347,7 +347,7 @@ The service value is a function `(effect, options) => Effect` — options: `{ cl
 Defined alongside the contract so client packages can provide it. The function receives `{ rpc, request, next }` and **must** call `next` (with the original or a modified request):
 
 ```ts
-import { Headers } from 'effect/unstable/http';
+import { Headers } from 'effect/http';
 
 export const AuthClient = RpcMiddleware.layerClient(AuthMiddleware, ({ next, request }) =>
 	next({
@@ -368,7 +368,7 @@ export const AuthClient = RpcMiddleware.layerClient(AuthMiddleware, ({ next, req
 
 ```ts
 import { Schema } from 'effect';
-import { Rpc } from 'effect/unstable/rpc';
+import { Rpc } from 'effect/rpc';
 
 // Type-level definition: how success/error transform
 export interface RpcWithPagination extends Rpc.Custom {
@@ -451,8 +451,8 @@ You rarely touch `RpcMessage` directly, but the envelope explains several contra
 Key facts:
 
 - A `RequestEncoded` carries `{ _tag: 'Request', id: string | number, tag: string, payload: unknown, headers: Array<[string, string]>, isNotification?, traceId?, spanId?, sampled? }`. The rpc's `_tag` **is the wire identity** — renaming or re-prefixing an rpc is a breaking protocol change for deployed clients.
-- `RequestId` is a branded `string | number`; construct it with `RequestId(1)` or `RequestId('1')` (from `effect/unstable/rpc/RpcMessage`). You need it when invoking handlers manually in tests via `accessHandler`. `bigint` is not accepted.
-- Terminal results travel as `ExitEncoded` — `Success` with a value, or `Failure` with a cause array of `Fail` (your error union, encoded), `Die` (via `defectSchema`), and `Interrupt` entries. This is exactly what `Rpc.exitSchema` encodes/decodes.
+- `RequestId` is a branded `string | number`; construct it with `RequestId(1)` or `RequestId('1')` (from `effect/rpc/RpcMessage`). You need it when invoking handlers manually in tests via `accessHandler`. `bigint` is not accepted.
+- Terminal results travel as `ExitEncoded` — `Success` with a value, or `Failure` with a cause array of `Fail` (your error union, encoded), `Die` (via `defectSchema`), and `Interrupt` entries. This is exactly what `Rpc.exitSchema` encodes/decodes. Encoded interrupt `fiberId` may be `null` as well as absent/`undefined`; JSON encoding can produce `null`. Custom envelope consumers must accept both absence forms.
 - Stream elements travel as batched `Chunk` messages, acknowledged by `Ack` on ack-capable protocols (sockets, workers); the HTTP protocol declares `supportsAck: false`. Incremental delivery requires a serialization with framing (e.g. ndjson) — with non-framed json over HTTP the chunks are buffered and returned in one final batch (see serialization notes in the `effect-rpc-cluster` skill).
 - Servers represent server-originated calls and notifications with `RequestEncoded` in `FromServerEncoded`. Set `isNotification: true` for a notification; JSON-RPC serialization then omits `id`. Buffered, unframed JSON-RPC HTTP cannot deliver notifications and drops them, while framed HTTP, sockets, stdio, and workers support them.
 
@@ -493,8 +493,8 @@ RpcGroup.HandlerFrom<R, Tag>; // one handler fn type
 The canonical use — typing a client service in the shared package without constructing anything:
 
 ```ts
-import type { RpcClient } from 'effect/unstable/rpc';
-import type { RpcClientError } from 'effect/unstable/rpc/RpcClientError';
+import type { RpcClient } from 'effect/rpc';
+import type { RpcClientError } from 'effect/rpc/RpcClientError';
 
 export type UsersClient = RpcClient.RpcClient<
 	RpcGroup.Rpcs<typeof UsersGroup>,
@@ -513,7 +513,7 @@ Everything client and server need, with zero runtime wiring:
 ```ts
 // contracts/users.ts — imported by both server and client packages
 import { Context, Schema } from 'effect';
-import { Rpc, RpcGroup, RpcMiddleware } from 'effect/unstable/rpc';
+import { Rpc, RpcGroup, RpcMiddleware } from 'effect/rpc';
 
 // --- domain schemas ---
 export class User extends Schema.Class<User>('User')({
@@ -591,7 +591,7 @@ export const PublicGroup = AdminGroup.omit('DeleteUser', 'PurgeAll').middleware(
 Contracts double as entity protocols — annotate, then hand to `Entity.fromRpcGroup`:
 
 ```ts
-import { ClusterSchema } from 'effect/unstable/cluster';
+import { ClusterSchema } from 'effect/cluster';
 
 export const DurableUsers = UsersGroup.annotateRpcs(ClusterSchema.Persisted, true);
 // Entity.fromRpcGroup('Users', DurableUsers) — see the effect-rpc-cluster skill
@@ -602,7 +602,7 @@ export const DurableUsers = UsersGroup.annotateRpcs(ClusterSchema.Persisted, tru
 ```ts
 import { assert, it } from '@effect/vitest';
 import { Exit, Schema } from 'effect';
-import { Rpc } from 'effect/unstable/rpc';
+import { Rpc } from 'effect/rpc';
 
 it('GetUser exits round-trip', () => {
 	const schema = Rpc.exitSchema(GetUser);
@@ -614,7 +614,7 @@ it('GetUser exits round-trip', () => {
 
 ## Common Mistakes
 
-1. **Importing from `@effect/rpc`.** The package does not exist in v4 — everything is `effect/unstable/rpc` (deep subpaths like `effect/unstable/rpc/RpcMessage` also work).
+1. **Importing from `@effect/rpc`.** The package does not exist in v4 — everything is `effect/rpc` (deep subpaths like `effect/rpc/RpcMessage` also work).
 2. **Reaching for `Rpc.fromTaggedRequest` / `Schema.TaggedRequest`.** Neither exists in v4. The tag is `Rpc.make`'s first argument; the payload schema carries no `_tag` field — the wire envelope transports the tag separately.
 3. **Expecting `error` to stay the Effect error with `stream: true`.** It becomes the *stream* error schema and the rpc's `errorSchema` is set to `Schema.Never`. Likewise `success` becomes the *element* schema.
 4. **Passing `primaryKey` with a schema payload.** It is typed `never` unless `payload` is inline struct fields — wrap the fields inline or drop `primaryKey`.

package/skills/effect-rpc-client/SKILL.md

@@ -3,23 +3,23 @@ name: effect-rpc-client
 description: Consume typed RPC services with Effect's RpcClient — protocol layers (HTTP, WebSocket, TCP, worker, in-memory), RpcSerialization codecs, per-call and ambient headers, streaming calls, interruption, reconnection, and RpcClientError handling. Use when calling an RpcGroup from a client, wiring a client transport + serialization stack, debugging RPC transport failures or reconnects, or testing RPC consumers with RpcTest.
 ---
 
-You are an Effect TypeScript expert specializing in consuming RPC services with `RpcClient` from `effect/unstable/rpc`.
+You are an Effect TypeScript expert specializing in consuming RPC services with `RpcClient` from `effect/rpc`.
 
 This skill covers the client side only: building clients, transports, serialization, headers, streaming consumption, interruption, errors, and testing. Defining `Rpc`/`RpcGroup` contracts is the `effect-rpc-api` skill; serving them is the `effect-rpc-server` skill; cluster entity clients are the `effect-rpc-cluster` skill.
 
 ## Effect Source Reference
 
-The Effect v4 source is at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`. Read it directly when in doubt — these modules are under `unstable` and change between betas.
+The Effect v4 source is at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`. Read the `effect@4.0.0` tag for this skill; main may be newer. These APIs remain `@stability unstable` and may break in minor releases. Keep Effect-family packages on the same release.
 
 Key files:
 
-- `packages/effect/src/unstable/rpc/RpcClient.ts` — `make`, `makeNoSerialization`, the `Protocol` service, `layerProtocolHttp`/`layerProtocolSocket`/`layerProtocolWorker` (+ `makeProtocol*`), `CurrentHeaders`, `withHeaders`, `ConnectionHooks`
-- `packages/effect/src/unstable/rpc/RpcClientError.ts` — `RpcClientError` and `RpcClientDefect`
-- `packages/effect/src/unstable/rpc/RpcSerialization.ts` — JSON, NDJSON, JSON-RPC, SchemaBinary codecs, their layers, the `Parser` interface and `includesFraming`
-- `packages/effect/src/unstable/rpc/RpcTest.ts` — `makeClient` in-process test client
-- `packages/effect/src/unstable/rpc/RpcWorker.ts` — `InitialMessage`, `layerInitialMessage`, `initialMessage`
-- `packages/effect/src/unstable/rpc/RpcMessage.ts` — wire vocabulary: `Request`, `Ack`, `Interrupt`, `Chunk`, `Exit`, `Defect`, `Ping`/`Pong`, `ClientProtocolError`, `RequestId`
-- `packages/effect/src/unstable/socket/Socket.ts` — `Socket` service, `layerWebSocket`, `WebSocketConstructor`
+- `packages/effect/src/rpc/RpcClient.ts` — `make`, `makeNoSerialization`, the `Protocol` service, `layerProtocolHttp`/`layerProtocolSocket`/`layerProtocolWorker` (+ `makeProtocol*`), `CurrentHeaders`, `withHeaders`, `ConnectionHooks`
+- `packages/effect/src/rpc/RpcClientError.ts` — `RpcClientError` and `RpcClientDefect`
+- `packages/effect/src/rpc/RpcSerialization.ts` — JSON, NDJSON, JSON-RPC, SchemaBinary codecs, their layers, the `Parser` interface and `includesFraming`
+- `packages/effect/src/rpc/RpcTest.ts` — `makeClient` in-process test client
+- `packages/effect/src/rpc/RpcWorker.ts` — `InitialMessage`, `layerInitialMessage`, `initialMessage`
+- `packages/effect/src/rpc/RpcMessage.ts` — wire vocabulary: `Request`, `Ack`, `Interrupt`, `Chunk`, `Exit`, `Defect`, `Ping`/`Pong`, `ClientProtocolError`, `RequestId`
+- `packages/effect/src/socket/Socket.ts` — `Socket` service, `layerWebSocket`, `WebSocketConstructor`
 - `packages/platform/node/test/RpcServer.test.ts` + `test/fixtures/rpc-e2e.ts` + `test/fixtures/rpc-schemas.ts` — the best end-to-end reference: every transport × serialization combination, headers, streams, interrupts, defects
 - `packages/platform/browser/test/RpcWorker.test.ts` + `test/fixtures/rpc-worker.ts` — worker transport end to end
 
@@ -58,16 +58,16 @@ import {
 	RpcSerialization,
 	RpcTest,
 	RpcWorker
-} from 'effect/unstable/rpc';
-import { RpcClientError } from 'effect/unstable/rpc/RpcClientError';
-import { FetchHttpClient, Headers, HttpClient, HttpClientRequest } from 'effect/unstable/http';
-import { Socket } from 'effect/unstable/socket';
+} from 'effect/rpc';
+import { RpcClientError } from 'effect/rpc/RpcClientError';
+import { FetchHttpClient, Headers, HttpClient, HttpClientRequest } from 'effect/http';
+import { Socket } from 'effect/socket';
 // Platform transports:
 import { NodeSocket, NodeWorker } from '@effect/platform-node';
 import { BrowserWorker } from '@effect/platform-browser';
 ```
 
-Note the `RpcClientError` import: the `effect/unstable/rpc` barrel exports `RpcClientError` as a *namespace*; import the class from the module path `effect/unstable/rpc/RpcClientError` (this is what the upstream tests do).
+Note the `RpcClientError` import: the `effect/rpc` barrel exports `RpcClientError` as a *namespace*; import the class from the module path `effect/rpc/RpcClientError` (this is what the upstream tests do).
 
 ---
 
@@ -113,7 +113,7 @@ export class UsersClient extends Context.Service<
 
 ### `flatten: true` — single-function client
 
-The client becomes one function `(tag, payload, options?)` instead of a property-per-tag object. Useful for generic proxying (this is what `AtomRpc` uses internally):
+The client becomes one function `(tag, payload, options?)` instead of a property-per-tag object. Useful for generic proxying (this is what `AtomRpc` uses internally). Union-valued tags infer payloads/results from the selected RPCs rather than `never`; retain tag/payload correlation in application dispatch:
 
 ```ts
 const client = yield* RpcClient.make(UserRpcs, { flatten: true });
@@ -122,7 +122,7 @@ const user = yield* client('GetUser', { id: 'u1' });
 
 ### `generateRequestId`
 
-Request ids correlate requests with responses on a shared connection. The default is a process-wide incrementing `number`. Override only when ids need application-specific generation. The function must return `RequestId`, a branded `string | number`; construct it with `RequestId(1)` or `RequestId('1')` from `effect/unstable/rpc/RpcMessage`. `bigint` is not accepted.
+Request ids correlate requests with responses on a shared connection. The default is a process-wide incrementing `number`. Override only when ids need application-specific generation. The function must return `RequestId`, a branded `string | number`; construct it with `RequestId(1)` or `RequestId('1')` from `effect/rpc/RpcMessage`. `bigint` is not accepted.
 
 ### Tracing
 
@@ -311,14 +311,19 @@ full `RpcSerialization.CodecFor` contract.
 | `RpcSerialization.layerJson` | `application/json` | no | HTTP (response decoded once, as an array); WebSocket (each ws message is one frame already) |
 | `RpcSerialization.layerNdjson` | `application/ndjson` | yes (newline) | anything — the safe default; enables streaming over HTTP |
 | `RpcSerialization.layerSchemaBinary(options?)` | `application/vnd.effect.rpc+schema-binary` | yes | schema-derived binary framing and payload codecs; pair on both peers |
+| `RpcSerialization.layerJsonRpc({ contentType? })` | `application/json` | no | JSON-RPC 2.0 interop over HTTP/WebSocket; maps rpc tag ↔ `method`, supports batch arrays |
+| `RpcSerialization.layerNdJsonRpc({ contentType? })` | `application/json-rpc` | yes (newline) | JSON-RPC 2.0 over sockets |
 
 `layerSchemaBinary({ maxFrameSize?, fingerprintPayloads? })` defaults to a
 16 MiB frame limit and no payload fingerprint. Envelopes are fingerprinted and
 dictionary-enabled; payload fingerprints opt into strict layout agreement.
 Workers use
 `Schema.toCodecJson` with structured clone without a serialization layer.
-| `RpcSerialization.layerJsonRpc({ contentType? })` | `application/json` | no | JSON-RPC 2.0 interop over HTTP/WebSocket; maps rpc tag ↔ `method`, supports batch arrays |
-| `RpcSerialization.layerNdJsonRpc({ contentType? })` | `application/json-rpc` | yes (newline) | JSON-RPC 2.0 over sockets |
+
+NDJSON parsers skip malformed lines and continue with subsequent frames.
+JSON-RPC decoding skips non-object values (including batch entries), and guards
+non-string notification methods before interpreting internal protocol methods.
+This framing recovery does not replace payload/schema validation.
 
 Choose serialization according to transport framing:
 
@@ -403,8 +408,8 @@ On the server, a client-initiated interrupt carries the `RpcSchema.ClientAbort`
 | `reason._tag` | Transport | Meaning |
 |---|---|---|
 | `'HttpError'` | HTTP | `HttpClientErrorSchema`: has `kind: 'EncodeError' \| 'DecodeError' \| 'TransportError' \| 'InvalidUrlError' \| 'StatusCodeError' \| 'EmptyBodyError'` and optional `cause` |
-| `'SocketOpenError'` | socket | failed to (re)connect, includes ping timeouts |
-| `'SocketReadError'` / `'SocketWriteError'` | socket | I/O failure on a live connection |
+| `'SocketOpenError'` | socket | failed to (re)connect, including opening-handshake timeouts |
+| `'SocketReadError'` / `'SocketWriteError'` | socket | I/O failure on a live connection; a missed pong is a read error |
 | `'SocketCloseError'` | socket | connection closed (has `code`) |
 | `'WorkerSpawnError'` / `'WorkerSendError'` / `'WorkerReceiveError'` / `'WorkerUnknownError'` | worker | worker lifecycle failures |
 | `'RpcClientDefect'` | any | protocol bug: undecodable message, empty HTTP response, non-array unframed response; has `message` + `cause` |
@@ -438,11 +443,11 @@ Semantics to remember:
 
 The socket protocol owns a long-lived connection loop:
 
-- **Keepalive** — the client sends `Ping` every 5 seconds; a missing `Pong` by the next tick fails the connection with a `SocketOpenError` (kind `'Timeout'`) and triggers reconnect.
+- **Keepalive** — the client sends `Ping` every 5 seconds; a missing `Pong` by the next tick fails the connection with a `SocketReadError` and triggers reconnect. Every in-flight call fails even with `retryTransientErrors: true`; calls are not replayed automatically.
 - **Reconnect policy** — the loop retries with `Schedule.min([Schedule.exponential("500 millis", 1.5), Schedule.spaced("5 seconds")])`, capped at 5s between attempts, forever, by default. Customize the schedule via `makeProtocolSocket({ retryPolicy })` + `Layer.effect(RpcClient.Protocol)(...)`; both constructors accept `retryTransientErrors` and `onTransientError`.
 - **Failure broadcast** — on a connection error, all in-flight requests fail with `RpcClientError`, and subsequent `send`s fail fast with the same error until the socket reopens.
-- **`retryTransientErrors: true`** — `SocketOpenError` failures (failure to connect, and ping timeouts, which are classified as open errors) are not broadcast: pending requests stay pending across reconnect attempts instead of failing. Read/write/close errors on an established connection still fail in-flight requests.
-- **`onTransientError`** — called for every retried `SocketOpenError` (including ping timeouts) while `retryTransientErrors` is enabled. Its infallible, service-free effect is for logging/metrics; defects in the hook are logged and ignored.
+- **`retryTransientErrors: true`** — connection-establishment `SocketOpenError` failures are not broadcast: pending requests stay pending across those reconnect attempts instead of failing. Established-connection read/write/close errors, including missed pongs, still fail in-flight requests.
+- **`onTransientError`** — called for every retried `SocketOpenError` while `retryTransientErrors` is enabled. Missed pongs do **not** invoke it. Its infallible, service-free effect is for logging/metrics; defects in the hook are logged and ignored.
 
 ```ts
 const ProtocolLive = RpcClient.layerProtocolSocket({ retryTransientErrors: true }).pipe(
@@ -504,7 +509,7 @@ const BrowserClient = UsersClient.layer.pipe(
 
 No `RpcSerialization` is needed — structured clone carries the messages. The worker side runs `RpcServer.layerProtocolWorkerRunner` (see the effect-rpc-server skill).
 
-Transferables: to move binary data instead of copying it, wrap fields in the shared contract with `Transferable` from `effect/unstable/workers` — `Transferable.Uint8Array` transfers the backing `ArrayBuffer`, `Transferable.ImageData`/`Transferable.MessagePort` are prebuilt, and `Transferable.schema(s, (encoded) => [encoded.buffer])` wraps any schema with a custom transfer-list extractor. Transfer only happens on protocols with `supportsTransferables: true` — the worker protocol only.
+Transferables: to move binary data instead of copying it, wrap fields in the shared contract with `Transferable` from `effect/workers` — `Transferable.Uint8Array` transfers the backing `ArrayBuffer`, `Transferable.ImageData`/`Transferable.MessagePort` are prebuilt, and `Transferable.schema(s, (encoded) => [encoded.buffer])` wraps any schema with a custom transfer-list extractor. Transfer only happens on protocols with `supportsTransferables: true` — the worker protocol only.
 
 ### Typed startup config — `RpcWorker.InitialMessage`
 
@@ -578,9 +583,9 @@ The primitive under `RpcTest`: builds a client from a raw decoded-message channe
 ```ts
 // client.ts — UserRpcs comes from the shared contract module (effect-rpc-api skill)
 import { Context, Effect, Layer } from 'effect';
-import { FetchHttpClient } from 'effect/unstable/http';
-import { RpcClient, RpcGroup, RpcSerialization } from 'effect/unstable/rpc';
-import { RpcClientError } from 'effect/unstable/rpc/RpcClientError';
+import { FetchHttpClient } from 'effect/http';
+import { RpcClient, RpcGroup, RpcSerialization } from 'effect/rpc';
+import { RpcClientError } from 'effect/rpc/RpcClientError';
 import { AuthClient, UserRpcs } from './contract.ts';
 
 export class UsersClient extends Context.Service<
@@ -664,7 +669,7 @@ const WorkerClientLive = UsersClient.layer.pipe(
 
 ## Common Mistakes
 
-1. **Importing from `@effect/rpc`.** Gone in v4 — everything is `effect/unstable/rpc`. And `import { RpcClientError } from 'effect/unstable/rpc'` gives you a *namespace*; import the class from `effect/unstable/rpc/RpcClientError`.
+1. **Importing from `@effect/rpc`.** Gone in v4 — everything is `effect/rpc`. And `import { RpcClientError } from 'effect/rpc'` gives you a *namespace*; import the class from `effect/rpc/RpcClientError`.
 2. **Missing `Scope` for `RpcClient.make`.** The constructor is scoped. Build clients inside `Layer.effect(Tag)(RpcClient.make(group))` or under `Effect.scoped` — providing protocol layers alone will not discharge `Scope`.
 3. **Forgetting the client middleware layer.** A group with a `requiredForClient: true` middleware needs `Layer.provide(RpcMiddleware.layerClient(M, ...))` on the client (and in `RpcTest.makeClient`'s context). The compile error points at an unsatisfied `ForClient<M>` requirement — provide the layer, don't cast.
 4. **Wrong codec/transport pairing.** Raw TCP requires `layerNdjson`, `layerSchemaBinary()`, or `layerNdJsonRpc()`. HTTP with unframed JSON buffers the response; use a framed codec for streaming. WebSocket supplies its own framing.