@flux-control/effect-modbus-rs 0.8.0 → 0.8.1

package/README.md

@@ -1,134 +1,114 @@
 # Effect-modbus-rs
 
-**Type-safe Modbus communication via Effect-TS**, wrapping the [`modbus-rs`](https://github.com/Raghava-Ch/modbus-rs) npm bindings (Rust napi-rs under the hood).
+Typed Effect 4 services for Modbus communication through the
+[`modbus-rs`](https://github.com/Raghava-Ch/modbus-rs) Rust bindings.
 
-For the complete API reference, see the [GitHub Pages documentation](https://flux-control-solutions.github.io/Effect-modbus-rs/).
+The package provides native TCP, RTU, and ASCII transports.
+Browser transports use WebSocket or Web Serial through `modbus-rs/web`.
+Each transport owns its connection, clients, and optional batching state within a scope.
 
-Provides scoped [`Context.Service`](https://effect.website) constructors for RTU (serial), TCP, and ASCII Modbus transports. Clients expose a typed `Effect`-based API for all standard Modbus function codes.
-
-> This project is under active development. Its API may change before the 1.0 release.
+For the API reference, see the [GitHub Pages documentation](https://flux-control-solutions.github.io/Effect-modbus-rs/).
+The API can change before version 1.0.
 
 ## Install
 
 ```sh
-bun add @flux-control/effect-modbus-rs
+bun add @flux-control/effect-modbus-rs effect@4.0.0-rc.118
 ```
 
-TypeScript only while prototyping (JS consumers will be supported before 1.0).
+The current package requires Effect `^4.0.0-rc.118` as a peer dependency.
+It depends on `modbus-rs@0.16.3`.
+The published package exports JavaScript and TypeScript declarations from `dist/`.
 
 ## Quick start
 
-### RTU (serial)
-
 ```ts
 import { Console, Effect } from 'effect';
-import { RtuTransportService } from '@flux-control/effect-modbus-rs';
-
-const program = Effect.gen(function* () {
-  const transport = yield* RtuTransportService;
-  const client = yield* transport.withClient(1);
-
-  const registers = yield* client.readHoldingRegisters({
-    address: 0,
-    quantity: 10,
-  });
-  console.log('Holding registers:', registers);
-});
-
-program.pipe(
-  Effect.catchTags({
-    ModbusTimeoutError: (err) => Console.log(`Timeout: ${err.message}`),
-    ModbusTransportError: (err) => Console.log(`Transport error: ${err.message}`),
-    ModbusConnectionClosedError: (err) => Console.log(`Connection lost: ${err.message}`),
-    ModbusExceptionError: (err) => Console.log(`Modbus exception ${err.exception}: ${err.message}`),
-    ModbusInvalidArgumentError: (err) => Console.log(`Invalid argument: ${err.message}`),
-  }),
-  Effect.catch((err) => Console.log(`Unhandled error: ${err.message}`)),
-  Effect.provide(RtuTransportService.make({ portPath: '/dev/ttyUSB0', baudRate: 9600 })),
-  Effect.scoped,
-  Effect.runPromise,
-);
-```
-
-### TCP
-
-```ts
-import { Effect } from 'effect';
 import { TcpTransportService } from '@flux-control/effect-modbus-rs';
 
 const program = Effect.gen(function* () {
   const transport = yield* TcpTransportService;
   const client = yield* transport.withClient(1);
-  const coils = yield* client.readCoils({ address: 0, quantity: 8 });
-  console.log('Coils:', coils);
+  const registers = yield* client.readHoldingRegisters({ address: 0, quantity: 2 });
+  yield* Console.log(registers);
 });
 
 program.pipe(
-  Effect.provide(TcpTransportService.make({ host: '192.168.1.100', port: 502 })),
+  Effect.provide(TcpTransportService.make({ host: '192.0.2.1', port: 502 })),
   Effect.scoped,
   Effect.runPromise,
 );
 ```
 
-### ASCII
-
-```ts
-import { Effect } from 'effect';
-import { AsciiTransportService } from '@flux-control/effect-modbus-rs';
+The transport opens on the first client request, not when the service tag is read.
+It caches raw clients by unit ID and closes the connection when its scope ends.
+All clients from one transport share the same connection.
 
-const program = Effect.gen(function* () {
-  const transport = yield* AsciiTransportService;
-  const client = yield* transport.withClient(1);
-  const registers = yield* client.readInputRegisters({
-    address: 0,
-    quantity: 5,
-  });
-  console.log('Input registers:', registers);
-});
+## Transports
 
-program.pipe(
-  Effect.provide(AsciiTransportService.make({ portPath: '/dev/ttyUSB0', baudRate: 9600 })),
-  Effect.scoped,
-  Effect.runPromise,
-);
-```
+| Service                     | Connection options                      | Binding               |
+| --------------------------- | --------------------------------------- | --------------------- |
+| `TcpTransportService`       | `host`, `port`                          | `AsyncTcpTransport`   |
+| `RtuTransportService`       | `portPath`, `baudRate`, serial settings | `AsyncRtuTransport`   |
+| `AsciiTransportService`     | `portPath`, `baudRate`, serial settings | `AsyncAsciiTransport` |
+| `WasmWsTransportService`    | `wsUrl`, optional request timeout       | `WasmWsTransport`     |
+| `WasmRtuTransportService`   | `port`, `baudRate`, serial settings     | `WasmRtuTransport`    |
+| `WasmAsciiTransportService` | `port`, `baudRate`, serial settings     | `WasmAsciiTransport`  |
 
-### Browser / WASM (`modbus-rs/web`)
+Concrete services expose `make(options)` layer factories and `makeScoped(options)` constructor effects.
+Bindings load dynamically when a live connection is requested.
+Browser initialization does not need to load native transports.
 
-`modbus-rs` ships its browser bindings through the `modbus-rs/web` WASM module. This package loads that module dynamically and exposes the same scoped, typed `Effect` client API as its native transports. Since browsers can't open raw TCP or serial connections directly, there are two browser-specific transports:
+### Serial transports
 
-- **`WasmWsTransportService`** — Modbus TCP over a WebSocket-to-TCP gateway (e.g. the `modbus-gateway` application).
-- **`WasmRtuTransportService`** / **`WasmAsciiTransportService`** — Modbus RTU/ASCII over the [Web Serial API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Serial_API), via `WasmSerialTransportService.fromRtu` / `.fromAscii`.
+For native serial connections, provide `RtuTransportService.make` or `AsciiTransportService.make` with a port path and baud rate.
+`SerialTransportService` provides one service tag for either framing format.
+Its `fromRtu(options)` and `fromAscii(options)` methods provide that tag.
 
 ```ts
 import { Console, Effect } from 'effect';
-import { WasmWsTransportService } from '@flux-control/effect-modbus-rs';
+import { SerialTransportService } from '@flux-control/effect-modbus-rs';
 
 const program = Effect.gen(function* () {
-  const transport = yield* WasmWsTransportService;
+  const transport = yield* SerialTransportService;
   const client = yield* transport.withClient(1);
-  const registers = yield* client.readHoldingRegisters({ address: 0, quantity: 10 });
-  console.log('Holding registers:', registers);
+  yield* Console.log(yield* client.readCoils({ address: 0, quantity: 2 }));
 });
 
 program.pipe(
-  Effect.provide(WasmWsTransportService.make({ wsUrl: 'ws://localhost:8080' })),
+  Effect.provide(SerialTransportService.fromRtu({ portPath: '/dev/ttyUSB0', baudRate: 9600 })),
   Effect.scoped,
   Effect.runPromise,
 );
 ```
 
-Web Serial requires a user-granted port handle. **`requestSerialPort()` must be called synchronously from within a user-gesture event handler** (e.g. a button click) — this is a Web Serial API / browser security requirement, not a library restriction:
+### Browser transports
+
+`WasmWsTransportService.make({ wsUrl })` connects to a WebSocket-to-TCP gateway.
+A browser cannot open a raw Modbus TCP socket.
+The gateway must connect to the target Modbus device.
+
+Web Serial client transports require a `WasmSerialPortHandle` from `requestSerialPort()`.
+Run the request effect from a user-gesture handler, such as a button click.
+The helper imports the browser binding asynchronously before it requests the port.
+It does not call the browser permission API synchronously in the handler.
+Permission behavior depends on browser support and transient user activation.
 
 ```ts
-import { Effect, Layer } from 'effect';
+import { Console, Effect } from 'effect';
 import { requestSerialPort, WasmRtuTransportService } from '@flux-control/effect-modbus-rs';
 
-connectButton.addEventListener('click', () => {
-  Effect.runPromise(
+const connectButton = document.querySelector<HTMLButtonElement>('#connect');
+
+connectButton?.addEventListener('click', () => {
+  void Effect.runPromise(
     Effect.gen(function* () {
       const port = yield* requestSerialPort();
-      yield* program.pipe(
+      yield* Effect.gen(function* () {
+        const transport = yield* WasmRtuTransportService;
+        const client = yield* transport.withClient(1);
+        yield* Console.log(yield* client.readHoldingRegisters({ address: 0, quantity: 2 }));
+      }).pipe(
         Effect.provide(WasmRtuTransportService.make({ port, baudRate: 19200 })),
         Effect.scoped,
       );
@@ -137,808 +117,495 @@ connectButton.addEventListener('click', () => {
 });
 ```
 
-See `examples/wasm/` for a real, runnable Vite app exercising both transports in an actual browser (`cd examples/wasm && npm install && npm run dev`).
-
-#### Browser server (experimental)
-
-`wasmWsServerLayer` and `wasmSerialRtuServerLayer` / `wasmSerialAsciiServerLayer` wrap `modbus-rs`'s experimental browser server bindings — same `ServerHandlers` callback shape as the native servers below. Two things differ from native:
+`WasmSerialTransportService.fromRtu` and `.fromAscii` provide the abstract browser serial tag.
+Both accept a port handle obtained through the same helper.
+See [the browser example](examples/wasm/README.md) for setup and browser requirements.
+
+## Raw client API
+
+`transport.withClient(unitId, options?)` returns an `EffectModbusClient`.
+Each operation returns an `Effect` with typed `ModbusError` failures.
+Addresses are zero-based protocol addresses.
+Support for a function code depends on the device and binding.
+
+| Method                                                                                 | Function code | Success value                  |
+| -------------------------------------------------------------------------------------- | ------------- | ------------------------------ |
+| `readHoldingRegisters({ address, quantity })`                                          | FC03          | `Uint16Array`                  |
+| `readInputRegisters({ address, quantity })`                                            | FC04          | `Uint16Array`                  |
+| `writeSingleRegister({ address, value })`                                              | FC06          | `void`                         |
+| `writeMultipleRegisters({ address, values })`                                          | FC16          | `void`                         |
+| `readWriteMultipleRegisters({ readAddress, readQuantity, writeAddress, writeValues })` | FC23          | `Uint16Array`                  |
+| `readCoils({ address, quantity })`                                                     | FC01          | `CoilState[]`                  |
+| `readDiscreteInputs({ address, quantity })`                                            | FC02          | `CoilState[]`                  |
+| `writeSingleCoil({ address, value })`                                                  | FC05          | `void`                         |
+| `writeMultipleCoils({ address, values })`                                              | FC15          | `void`                         |
+| `readExceptionStatus()`                                                                | FC07          | `number`                       |
+| `diagnostics({ subFunction, data })`                                                   | FC08          | `DiagnosticsResponse`          |
+| `readFileRecord({ requests })`                                                         | FC20          | `Uint16Array[]`                |
+| `writeFileRecord({ requests })`                                                        | FC21          | `void`                         |
+| `readFifoQueue({ address })`                                                           | FC24          | `FifoQueueResponse`            |
+| `readDeviceIdentification({ readDeviceIdCode, objectId })`                             | FC43 / MEI 14 | `DeviceIdentificationResponse` |
+
+Coil operations use `CoilState.On` and `CoilState.Off` from `modbus-rs`, rather than boolean values.
+FC23 performs its write and read within one Modbus request.
+It does not make separate application operations atomic.
 
-- Unlike native servers, the WASM server doesn't start serving on bind — these layers fork the required `serve()` loop into the layer's scope automatically, so usage looks the same as the native `tcpServerLayer`.
-- For the serial variants, `options.serialPort` comes from your own app's `navigator.serial.requestPort()` call (not from this package's `requestSerialPort()`, which returns a different wrapper type used only by the client transports).
-
-Not demonstrated in `examples/wasm/` (see that app's README) — the same `import { wasmWsServerLayer } from "@flux-control/effect-modbus-rs"` pattern applies.
-
-## Transports
-
-Each transport is a scoped `Context.Service`. You provide it with `Effect.provide`, and the connection is opened on service access and closed when the scope ends.
-
-| Service                               | Options                        | Connection                    |
-| ------------------------------------- | ------------------------------ | ----------------------------- |
-| `RtuTransportService`                 | `{ portPath, baudRate, ... }`  | `AsyncRtuTransport.open()`    |
-| `TcpTransportService`                 | `{ host, port, ... }`          | `AsyncTcpTransport.connect()` |
-| `AsciiTransportService`               | `{ portPath, baudRate, ... }`  | `AsyncAsciiTransport.open()`  |
-| `WasmWsTransportService` (browser)    | `{ wsUrl, requestTimeoutMs? }` | `WasmWsTransport.connect()`   |
-| `WasmRtuTransportService` (browser)   | `{ port, baudRate, ... }`      | `WasmRtuTransport.open()`     |
-| `WasmAsciiTransportService` (browser) | `{ port, baudRate, ... }`      | `WasmAsciiTransport.open()`   |
-
-Browser transport option types are re-exported from `modbus-rs/web` unchanged. The native ones are narrowed — `RtuTransportOpenOptions`, `AsciiTransportOpenOptions`, and `TcpTransportOpenOptions` are their `modbus-rs` counterparts minus the retry knobs, for the reasons in [Why the upstream retry knobs are withheld](#why-the-upstream-retry-knobs-are-withheld).
-
-### Abstract serial transport
+## Transaction batching
 
-`SerialTransportService` is a transport-agnostic tag that can be backed by either RTU or ASCII framing — useful when writing code that doesn't need to commit to a specific serial protocol. Provide it with `fromRtu` or `fromAscii`:
+Use `withClient` when the caller selects exact Modbus transactions.
+Use `withBatchingClient` to collect register operations, plan contiguous transactions, and suppress redundant writes.
+Batching does not cover coils, diagnostics, or file records.
 
 ```ts
 import { Console, Effect } from 'effect';
-import { SerialTransportService } from '@flux-control/effect-modbus-rs';
+import { TcpTransportService } from '@flux-control/effect-modbus-rs';
 
 const program = Effect.gen(function* () {
-  const transport = yield* SerialTransportService;
-  const client = yield* transport.withClient(1);
-  const coils = yield* client.readCoils({ address: 0, quantity: 2 });
-  console.log('Coils:', coils);
+  const transport = yield* TcpTransportService;
+  const client = yield* transport.withBatchingClient(3, {
+    debounce: {
+      writes: { window: '250 millis', maxHold: '1 second' },
+      reads: { window: '5 millis' },
+    },
+  });
+
+  yield* client.writeAllNow([
+    { address: 2000, value: 512 },
+    { address: 2001, value: 256 },
+  ]);
+  yield* Console.log(yield* client.readAllNow([0, 1, 2, 32, 33]));
+  yield* client.onShutdown(client.writeAllNow([{ address: 2000, value: 0 }]));
 });
 
-// RTU framing
 program.pipe(
-  Effect.provide(SerialTransportService.fromRtu({ portPath: '/dev/ttyUSB0', baudRate: 9600 })),
+  Effect.provide(TcpTransportService.make({ host: '192.0.2.1', port: 502 })),
   Effect.scoped,
   Effect.runPromise,
 );
-
-// Or ASCII framing
-// program.pipe(
-//   Effect.provide(SerialTransportService.fromAscii({ portPath: "/dev/ttyUSB0", baudRate: 9600 })),
-//   Effect.scoped,
-//   Effect.runPromise,
-// );
-```
-
-`WasmSerialTransportService` is the browser equivalent. Provide it with `fromRtu` or `fromAscii`, and give it a port handle from `requestSerialPort`.
-
-Both abstract tags also have `makeMockTransport` for tests. The option set is the same as the option set of the concrete tags. Thus a test that keeps the framing abstract can also set `retry`, `reconnect`, and the mock fault hooks:
-
-```ts
-import {
-  ModbusTimeoutError,
-  RetryPolicies,
-  SerialTransportService,
-} from '@flux-control/effect-modbus-rs';
-
-let attempts = 0;
-
-const layer = SerialTransportService.makeMockTransport([device])({
-  portPath: '/dev/ttyUSB0',
-  baudRate: 9600,
-  retry: RetryPolicies.serial(),
-  // The first two attempts of each operation fail. The policy retries them.
-  fault: () =>
-    attempts++ < 2
-      ? new ModbusTimeoutError({ message: 'no response', cause: new Error('timeout') })
-      : undefined,
-});
 ```
 
-See [Testing with mocks](#testing-with-mocks) for the `fault` hook and the `reconnectFault` hook.
+### Batching client methods
 
-## Client API
+| Method                                    | Behavior                                                         |
+| ----------------------------------------- | ---------------------------------------------------------------- |
+| `write(write, attributes?)`               | Collect one holding-register write for the configured window.    |
+| `writeNow(write, attributes?)`            | Enqueue one write and flush pending writes immediately.          |
+| `writeAll(writes, attributes?)`           | Collect a group as one caller for the configured window.         |
+| `writeAllNow(writes, attributes?)`        | Enqueue a group and flush pending writes immediately.            |
+| `read(address)`                           | Collect one holding-register read.                               |
+| `readNow(address)`                        | Enqueue one address and flush collected reads immediately.       |
+| `readAll(addresses)`                      | Collect a group and return values in the requested order.        |
+| `readAllNow(addresses)`                   | Enqueue a group and flush collected reads immediately.           |
+| `inputs.read` through `inputs.readAllNow` | Apply the same read methods to input registers.                  |
+| `flush`                                   | Flush writes, holding-register reads, then input-register reads. |
+| `onShutdown(action)`                      | Register an action in the calling scope.                         |
 
-`transport.withClient(unitId)` returns an `EffectModbusClient` — a typed wrapper around the raw modbus-rs client. All methods return `Effect.Effect<T, ModbusError>`.
+`flush` reports batch outcomes to waiting callers, not through its own typed error channel.
+`client.cache` exposes the write cache, or `undefined` when caching is disabled.
+`client.debounce` exposes frozen, resolved debounce durations when configured.
 
-### Registers
+### Collection windows and completion
 
-| Method                                                                                 | Returns    |
-| -------------------------------------------------------------------------------------- | ---------- |
-| `readHoldingRegisters({ address, quantity })`                                          | `number[]` |
-| `readInputRegisters({ address, quantity })`                                            | `number[]` |
-| `writeSingleRegister({ address, value })`                                              | `void`     |
-| `writeMultipleRegisters({ address, values })`                                          | `void`     |
-| `readWriteMultipleRegisters({ readAddress, readQuantity, writeAddress, writeValues })` | `number[]` |
+Debounce windows default to zero.
+A zero window issues operations without a collection timer, including grouped operations.
+With a positive window, `writeAll` and `readAll` also collect before issuing their groups.
+Use the `Now` methods to flush immediately.
 
-### Coils / discrete inputs
-
-| Method                                      | Returns     |
-| ------------------------------------------- | ----------- |
-| `readCoils({ address, quantity })`          | `boolean[]` |
-| `writeSingleCoil({ address, value })`       | `void`      |
-| `writeMultipleCoils({ address, values })`   | `void`      |
-| `readDiscreteInputs({ address, quantity })` | `boolean[]` |
-
-### Diagnostics & file access
-
-| Method                                                     | Returns                        |
-| ---------------------------------------------------------- | ------------------------------ |
-| `readExceptionStatus()`                                    | `number`                       |
-| `diagnostics({ subFunction, data })`                       | `DiagnosticsResponse`          |
-| `readFifoQueue({ address })`                               | `FifoQueueResponse`            |
-| `readFileRecord({ requests })`                             | `number[][]`                   |
-| `writeFileRecord({ requests })`                            | `void`                         |
-| `readDeviceIdentification({ readDeviceIdCode, objectId })` | `DeviceIdentificationResponse` |
-
-## Transaction batching
-
-`withClient` issues exactly the transaction you name, and stays the right client when you know what the bus should carry. `withBatchingClient` is its sibling for the other case — code with one accessor per register, which knows what it wants to read and write but not what that ought to cost.
-
-```ts
-Effect.gen(function* () {
-  const client = yield* transport.withClient(3); // exact read
-  yield* client.readHoldingRegisters({ address: 2000, quantity: 2 });
-
-  const batched = yield* transport.withBatchingClient(3); // decides the transactions
-  yield* batched.writeAll([
-    { address: 2000, value: 512 },
-    { address: 2001, value: 256 },
-  ]); // one FC16
-  yield* batched.readAll([0x0000, 0x0001, 0x0002, 0x0020, 0x0021]); // two FC03
-});
-```
-
-Three things bring the transaction count down, and each is exported on its own:
-
-| Piece                                          | What it does                                                                        |
-| ---------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `planWrites` / `planReads`                     | Pack neighbouring addresses into the fewest transactions. Pure, no state, no I/O.   |
-| `createWriteDebouncer` / `createReadDebouncer` | Collect operations that arrive near each other, so a planner has something to pack. |
-| `createRegisterCache`                          | Drop a write whose value the device already holds.                                  |
-
-### Batching client API
-
-| Method                              | Function code | Notes                                                      |
-| ----------------------------------- | ------------- | ---------------------------------------------------------- |
-| `write({ address, value })`         | FC06 / FC16   | Held for the write window, if one is configured.           |
-| `writeNow({ address, value })`      | FC06 / FC16   | Enqueue with supersede, then flush and join. Newest wins.  |
-| `writeAll(writes)`                  | FC06 / FC16   | One caller, one group, planned together.                   |
-| `writeAllNow(writes)`               | FC06 / FC16   | The same, issued immediately.                              |
-| `read(address)`                     | FC03          | Collected for the read window, if one is configured.       |
-| `readNow(address)`                  | FC03          | Immediate, and answers every reader already collected.     |
-| `readAll(addresses)`                | FC03          | One caller, planned into spans, values in the order asked. |
-| `readAllNow(addresses)`             | FC03          | The same, issued immediately.                              |
-| `inputs.read` … `inputs.readAllNow` | FC04          | The same four reads over the input registers.              |
-| `flush`                             | —             | Issue everything pending, now. Never fails.                |
-| `cache`                             | —             | The cache this client filters against, or `undefined`.     |
-
-**A `BatchingModbusClient` is not an `EffectModbusClient`.** It deliberately does not extend `ModbusOperations`: there is no `writeSingleRegister` and no `readHoldingRegisters` on it. For a given unit, choose one holding-register write path for the transport's lifetime. Once a batching client exists, raw FC06, FC16, and FC23 operations for that unit fail with `ModbusInvalidArgumentError`; otherwise they could bypass the pending batch and its cache. A raw client for the same unit remains available for exact reads, coils, file records, diagnostics, and the other non-register-write operations. Coils are not covered by batching because the planners pack registers.
-
-Each unit can have a low-level client, a batching client, or both at once. Once a batching client exists for a unit, the low-level client can still read registers, read/write coils, and use diagnostics — but it can no longer write holding registers directly. A direct write is blocked with a typed error, so it cannot slip past the batch or leave the cache out of date. All holding-register writes for that unit must go through the batching client instead.
-
-```mermaid
-sequenceDiagram
-    participant App
-    participant Registry as Batching registry
-    participant Raw as Low-level client
-    participant Batch as Batching client
-    participant Dev as Device
-
-    App->>Registry: withBatchingClient(unitId)
-    Registry-->>App: BatchingModbusClient
-    Note over Registry: unit now has a batching client
-
-    App->>Raw: writeSingleRegister(unitId, ...)
-    Raw->>Registry: guarded write check
-    Registry-->>Raw: fails: ModbusInvalidArgumentError
-    Note over Raw: reads, coils, diagnostics,\nfile records still work on Raw
-
-    App->>Batch: write(...)
-    Batch->>Registry: enqueue in debouncer
-    Registry->>Dev: flush (via the same underlying client)
-    Dev-->>Registry: ack
-    Registry-->>Batch: resolve
-```
-
-### Windows
-
-Nothing is debounced unless you ask for it, the same way nothing retries or reconnects unless you ask:
-
-```ts
-Effect.gen(function* () {
-  const batched = yield* transport.withBatchingClient(3, {
-    debounce: {
-      writes: { window: '250 millis', maxHold: '1 second' },
-      reads: { window: '5 millis' },
-    },
-  });
-});
-```
-
-A write is held for `window`, and each new arrival restarts it. `maxHold` caps the total hold, so a register that updates faster than the window still reaches the wire — without the ceiling, every arrival would postpone the wait forever. It defaults to four times `window`.
-
-A write does not go to the device right away. It waits in the debouncer for the length of `window`. Each new write to the same address resets that wait, so a burst of updates can still land as one transaction. `maxHold` sets a limit on the total wait, so a register that updates fast still reaches the device on time. When the window ends, or `maxHold` is reached, the debouncer sends the batch and tells every waiting caller the result.
+Each new write restarts the write window.
+`maxHold` limits the total delay from the first write in the batch.
+It defaults to four times the write window.
+The read window starts with the first reader and does not restart.
 
 ```mermaid
 stateDiagram-v2
     [*] --> Idle
-    Idle --> Open: first write arrives\n(opens window, starts maxHold clock)
-    Open --> Open: new write arrives\n(same address is superseded, timer restarts)
-    Open --> Flushing: window elapses, or maxHold reached
-    Flushing --> Idle: batch sent to device,\nall waiting callers resolve
-```
-
-```mermaid
-sequenceDiagram
-    participant A as Caller A
-    participant B as Caller B
-    participant D as Debouncer
-    participant Dev as Device
-
-    A->>D: write(2000, 10)
-    Note over D: batch opens, window timer starts
-    B->>D: write(2001, 20)
-    Note over D: new arrival restarts window\n(unless maxHold is closer)
-    Note over D: window elapses OR maxHold reached
-    D->>Dev: flush (one packed transaction)
-    Dev-->>D: ack / error
-    D-->>A: write() resolves
-    D-->>B: write() resolves
-```
-
-A read window does not restart: it opens on the first arrival and expires on time, which a stream of readers cannot push out. A useful size is on the order of one transaction; measure one on your bus before choosing.
-
-`writeAll` and `readAll` plan whatever they are given, so code that already holds a group of registers needs no window at all.
-
-### The cache
-
-The cache records what this process wrote, keyed by unit and address. It is not a read cache and never answers a read. One cache serves every device on a transport, because a cache is a belief about a physical device and two caches on one unit disagree.
-
-It is emptied for a unit after a failed write, and emptied entirely when the link is lost — a device that power-cycles comes back holding something else. An invalidation that lands while a write is still on the wire wins over the observation that follows it, so losing the link cannot be undone by a write that was already in flight. Pass `cache: false` to write every value, or pass your own `RegisterCache` to share one.
-
-Suppressing a write is not always cheaper. Dropping one address out of the middle of a contiguous run splits that run into one FC06 per register, so a cache meant to save turnarounds can spend them instead. Each batch is therefore planned both ways — filtered, and whole — and the plan with fewer transactions wins, with a tie going to the filtered one because its frames are shorter. Keeping a run whole rewrites a register with the value the cache believes it already holds, and never sends more than `cache: false` would have. If you need a register left alone rather than rewritten, use `withClient`: it issues exactly the transaction you name.
-
-The cache and the fiber that watches the link are created on first use, so a transport nobody batches on carries neither.
-
-### Declaring a unit, and reaching for it
-
-Every option a batching client takes is a fact about the unit, not about a caller. One unit holds one batch, one belief about what the device contains, and one window — so two callers can only ever configure a unit correctly by passing identical options. Rather than compare them, the two operations are separate:
-
-```ts
-const damper =
-  yield * transport.withBatchingClient(3, { debounce: { writes: { window: '50 millis' } } });
-const same = yield * transport.batchingClient(3); // elsewhere, no options to restate
-```
-
-`withBatchingClient` declares. Declaring a unit twice fails with `ModbusUnitAlreadyDeclaredError`, whatever the second call asks for. `batchingClient` looks up, and fails with `ModbusInvalidArgumentError` when nothing has declared that unit. A lookup that arrives while a declaration is still in flight waits for it, so neither call has to know which one ran first.
-
-A declaration belongs to the transport scope, not to the caller. It stays when the caller is interrupted, and when the owner that made it closes while the transport stays open. An owner that can start again over the same transport can catch the error and recover the existing client:
-
-```ts
-const damper =
-  yield *
-  transport
-    .withBatchingClient(3, { debounce })
-    .pipe(
-      Effect.catchTag('ModbusUnitAlreadyDeclaredError', (error) =>
-        transport.batchingClient(error.unitId),
-      ),
-    );
-```
-
-The recovered client keeps the options of the first declaration. `client.debounce` gives its debounce windows as frozen, resolved `Duration` values, so the owner can compare them with the windows that it expects. An omitted `maxHold` shows as four times the write window, which is the limit that the client applies.
-
-### Shutdown
-
-```ts
-Effect.gen(function* () {
-  const damper = yield* transport.withBatchingClient(3);
-  yield* damper.onShutdown(damper.writeAllNow([{ address: 2000, value: 0 }]));
-
-  const motor = yield* transport.withBatchingClient(7);
-  yield* motor.onShutdown(motor.writeNow({ address: 40, value: MOTOR_STOP }));
-});
-```
-
-A safe state is the device's own answer — zero volts for one, a stopped motor for
-another — so it is stated on the client that addresses the device. A unit whose
-client registers nothing is left alone. The action runs when the calling scope
-closes, while the transport is still open, and before the client is torn down.
-
-A failure is logged and raised as a defect. The other actions in the scope still
-run, so a device that cannot be reached does not cost the rest of the bus its
-turn. Wrap the action in `Effect.ignoreLogged` to accept the failure instead.
-
-`transport.touchedUnits` reports which units a client was built for. That is
-transport-wide diagnostic state, not device ownership, and it is not the input to
-a shutdown policy.
-
-### Spans
-
-A batching client opens `modbus.write` and `modbus.read` spans, carrying:
-
-| Attribute                  | Content                     |
-| -------------------------- | --------------------------- |
-| `modbus.unit_ids`          | The units the batch reached |
-| `modbus.register_count`    | Registers written or read   |
-| `modbus.suppressed_count`  | Writes the cache removed    |
-| `modbus.transaction_count` | Transactions issued         |
-
-The write span opens _after_ the cache filter, and only when a write survives it, so it records what reached the bus rather than what was proposed. Only the callers whose values are in the transaction contribute their vocabulary to it — a suppressed caller does not name itself on a frame that did not carry its value. Attach your own vocabulary as a second argument:
-
-```ts
-Effect.gen(function* () {
-  yield* batched.write({ address: 2000, value: 512 }, { 'app.point': 'Supply fan' });
-});
-```
-
-Your keys are opaque to this package and are applied first; the `modbus.*` keys are applied last and win a collision, so a caller cannot overwrite the record of what the library wrote. When a batch carries several callers' worth of vocabulary, values for a repeated key are joined with a comma rather than one silently winning.
-
-### Using the layers directly
-
-The batching client is a composition, not a wall. Each layer is exported, and each works without the layer above it.
-
-#### The planners
-
-Pure — no Effect, no state, no I/O. Use them when you own your own scheduling and only want the packing.
-
-```ts
-import { planReads, planWrites } from '@flux-control/effect-modbus-rs';
-
-planWrites([
-  { address: 2003, value: 40 },
-  { address: 2000, value: 10 },
-  { address: 2010, value: 99 },
-  { address: 2001, value: 20 },
-  { address: 2002, value: 30 },
-]);
-// [
-//   { kind: "multiple", address: 2000, values: Uint16Array [10, 20, 30, 40] },
-//   { kind: "single",   address: 2010, value: 99 },
-// ]
-
-const plan = planReads([0x0000, 0x0001, 0x0002, 0x0020, 0x0021]);
-plan.spans; // [{ address: 0, quantity: 3 }, { address: 32, quantity: 2 }]
-plan.locate(0x0021); // { span: 1, offset: 1 } — index back into the responses
-plan.locate(0x0010); // undefined
-```
-
-Each step maps onto exactly one client call: `single` onto `writeSingleRegister`, `multiple` onto `writeMultipleRegisters`. `locate` answers for every address a span covers, so you issue the spans, keep the responses in order, and read each value out without tracking the grouping yourself.
-
-`planWrites(writes, options?)`:
-
-| Option                 | Default                            | What it does                                                                    |
-| ---------------------- | ---------------------------------- | ------------------------------------------------------------------------------- |
-| `maxRegistersPerWrite` | `MODBUS_MAX_WRITE_REGISTERS` (123) | Registers one FC16 may carry. A longer run splits into consecutive steps.       |
-| `minRunLength`         | `2`                                | Shortest run that becomes FC16. Anything shorter becomes one FC06 per register. |
-
-`planReads(addresses, options?)`:
-
-| Option                | Default                           | What it does                                                  |
-| --------------------- | --------------------------------- | ------------------------------------------------------------- |
-| `maxRegistersPerRead` | `MODBUS_MAX_READ_REGISTERS` (125) | Registers one read may return. A span never grows past this.  |
-| `maxGap`              | `0`                               | Unrequested registers the planner may read to join two spans. |
-
-Both constants are the specification's limits, and both are exported. Many devices stop short of them — pass the device's own number when it does.
-
-> **Raising `maxGap` can take healthy registers down with it.** A gap may cover an address the device does not implement. That span then fails with `ILLEGAL_DATA_ADDRESS`, and every address in it fails, including the ones that would have answered. Raise it only against a register map that says the gap is readable.
-
-Both planners throw `RangeError` for an address, a value, or an option that is out of range, since those are programming errors rather than bus conditions. `encodeRegisterValue` is exported for the same reason the planners use it: `-1` and `65535` are the same register contents, so anything comparing a proposed value against a device value has to encode first or it will rewrite the register forever.
-
-#### The debouncers and the cache
-
-Stateful, scoped, and driven by callbacks you supply — use these to batch over a client this package did not hand out.
-
-```ts
-Effect.gen(function* () {
-  const writes = yield* createWriteDebouncer({
-    window: '250 millis',
-    maxHold: '1 second',
-    flush: (batch) => issueHowever(batch), // yours: cache, plan, span, write
-  });
-
-  // Two callers that never meet, one transaction:
-  yield* Effect.all(
-    [writes.write({ address: 2000, value: 10 }), writes.write({ address: 2001, value: 20 })],
-    {
-      concurrency: 'unbounded',
-    },
-  );
-});
-```
-
-`createWriteDebouncer` takes `window`, an optional `maxHold` (four times `window` by default), and `flush`. It returns `write` / `writeNow` / `writeAll` / `writeAllNow`, a `flush` you can force, and a `pending` count for tests.
-
-`createReadDebouncer` takes `window`, an optional `plan` (the `planReads` options), and `fetch`, which must return one response per span. Its callback owns the function code, so reading input registers rather than holding registers means a second debouncer. It returns `read` / `readNow` / `readAll` / `readAllNow`, plus `flush` and `pending`.
-
-Both take a `Scope` and flush in it rather than in the caller's, so a caller interrupted mid-wait cannot take the pending batch down with it. When that scope closes, callers still waiting are interrupted — their operations never reached the device, and reporting success would break the invariant the `Deferred` exists to hold.
+    Idle --> Collecting: first write
+    Collecting --> Collecting: new write restarts window
+    Collecting --> Flushing: window expires, maxHold reached, or immediate flush
+    Flushing --> Idle: notify waiting callers
+```
 
-`createRegisterCache` returns `filter(unitId, writes)`, `observe(unitId, address, value)`, and `invalidate(unitId?)`. Call `observe` only after the device acknowledged the write: a value recorded early suppresses the retry that would have fixed it.
-
-#### Composing them yourself
-
-`makeBatchingClient({ unitId, client, cache, debounce, plan })` builds a `BatchingModbusClient` over any `EffectModbusClient`, which is the escape hatch when you are driving an Effect-wrapped client this package did not hand out, or a stub implementing that interface. A raw promise-based `modbus-rs` client is not accepted directly.
-
-`createBatchingRegistry(deps)` is one level below that: it is what `withBatchingClient` and `batchingClient` are made of, including the per-unit declarations and the fiber that watches the link. You need it only if you are writing a transport of your own; both this package's transports and its mock use it. A custom transport must pass each public raw client through `registry.guardRawWrites(unitId, client)` so selecting batching also enforces the one-register-write-path rule.
-
-`mergeSpanAttributes(sources)` is the join rule described under [Spans](#spans), exported so a custom `flush` can apply the same one.
+For repeated writes to the same address, the latest pending value replaces earlier values.
+Earlier callers receive the result of the batch that contains the latest value.
+Success does not prove that each caller's original value reached the device.
+Cache filtering can also suppress a physical write.
+
+A group can require several Modbus transactions.
+If a later transaction fails, earlier writes can remain applied.
+The package does not roll them back.
+Batch completion does not prove that the device completed a physical action.
+
+Closing the debouncer scope discards pending requests and interrupts their waiting callers.
+Already-issued operations are not rolled back.
+Interrupting one caller does not remove its request from the shared pending batch.
+
+### Raw register-write guards
+
+A `BatchingModbusClient` does not extend `ModbusOperations`.
+After a unit has a batching declaration, raw FC06, FC16, and FC23 operations for that unit fail with `ModbusInvalidArgumentError`.
+This guard prevents raw writes from bypassing pending writes and their cache.
+Raw reads, coils, diagnostics, and file-record operations remain available through `withClient`.
+
+### Declaring and retrieving clients
+
+`withBatchingClient(unitId, options?)` declares one batching client per unit in the transport scope.
+A second declaration fails with `ModbusUnitAlreadyDeclaredError`, including when the first declaration is still pending.
+`batchingClient(unitId)` retrieves a declared client.
+It waits for a pending declaration or fails with `ModbusInvalidArgumentError` if no declaration exists.
+
+The declaration remains until the transport scope closes.
+Interrupting its caller or closing a separate caller scope does not remove it.
+To recover an existing declaration, catch `ModbusUnitAlreadyDeclaredError` and call `batchingClient(error.unitId)`.
+The recovered client retains the first declaration's options.
+Compare `client.debounce` with the durations the caller expects.
+
+### Write cache
+
+The cache records acknowledged writes by unit ID and address.
+It does not read the device and does not answer reads.
+It cannot detect changes made by another process or device logic.
+One default cache serves the batching clients on a transport.
+The cache and connection watcher are created when batching is first requested.
+
+Cache comparisons use encoded unsigned 16-bit values.
+For example, `-1` and `65535` have the same wire encoding.
+After an issued write fails, the unit's cached values are invalidated.
+When the connection state leaves `Connected`, all cached writes are invalidated.
+An invalidation during an in-flight write prevents a later acknowledgement from restoring stale cache entries.
+
+The client compares filtered and unfiltered write plans.
+If the unfiltered plan uses fewer transactions, it can resend unchanged values to preserve a contiguous run.
+If the counts are equal, it selects the filtered plan.
+Pass `cache: false` to disable suppression.
+Pass a `RegisterCache` instance to supply a custom cache.
+
+### Shutdown actions
+
+`client.onShutdown(action)` registers a finalizer in the calling scope.
+Use an immediate write method for an action that must run before transport cleanup.
+Close the caller scope while the transport remains open.
+Call `transport.close(callerScope)` to finalize the caller scope before closing the connection.
+Closing a different scope first can prevent the action from reaching the device.
+
+An unhandled action failure is logged and raised as a defect.
+Other finalizers still run.
+Wrap the action in `Effect.ignoreLogged` to accept its failure.
+The application selects the shutdown value; the library does not guarantee a device's safe state.
+`transport.touchedUnits` is diagnostic state, not a shutdown policy or an ownership record.
+
+### Tracing
+
+Batching reads and writes use `modbus.read` and `modbus.write` spans.
+Write spans are created after cache filtering and only when the chosen plan contains writes.
+The span describes the selected plan; failed execution can leave some transactions unissued.
+
+| Attribute                  | Meaning                                             |
+| -------------------------- | --------------------------------------------------- |
+| `modbus.unit_ids`          | Unit ID addressed by the batch.                     |
+| `modbus.register_count`    | Registers in the selected write plan or read spans. |
+| `modbus.suppressed_count`  | Proposed writes excluded from the selected plan.    |
+| `modbus.transaction_count` | Transactions in the selected plan.                  |
+
+Write methods accept caller span attributes as their second argument.
+Only attributes from the entries in the chosen write plan contribute.
+`mergeSpanAttributes` deduplicates repeated values by string form and joins them with commas in first-seen order.
+Reserved `modbus.*` attributes apply last and replace conflicting caller values.
+
+## Independent batching utilities
+
+The planners, debouncers, and cache can be used independently.
+
+### Planners
+
+`planWrites(writes, options?)` sorts addresses and keeps the latest value for each duplicate address.
+It groups consecutive addresses and splits groups at the configured limit.
+A `single` step maps to FC06; a `multiple` step maps to FC16.
+
+`planReads(addresses, options?)` sorts and deduplicates addresses into spans.
+The returned `locate(address)` finds the span index and offset for an address covered by a span.
+It returns `undefined` outside the spans.
+
+| Planner option         | Default                           | Purpose                                                  |
+| ---------------------- | --------------------------------- | -------------------------------------------------------- |
+| `maxRegistersPerWrite` | `MODBUS_MAX_WRITE_REGISTERS`, 123 | Limit each FC16 transaction.                             |
+| `minRunLength`         | 2                                 | Minimum contiguous run for FC16.                         |
+| `maxRegistersPerRead`  | `MODBUS_MAX_READ_REGISTERS`, 125  | Limit each read span.                                    |
+| `maxGap`               | 0                                 | Allow unrequested addresses between requested addresses. |
+
+Use lower transaction limits when required by the device.
+If a gap includes an unreadable address, its entire read transaction can fail.
+Increase `maxGap` only when those addresses are readable.
+The planners throw `RangeError` for invalid addresses, values, or options.
+`encodeRegisterValue(value)` validates and encodes signed or unsigned 16-bit register values.
+
+### Debouncers and cache
+
+`createWriteDebouncer({ window, maxHold?, flush })` collects writes and invokes the supplied batch callback.
+`createReadDebouncer({ window, plan?, fetch })` collects addresses and invokes the supplied span callback.
+`fetch` must return one `Uint16Array` per span, with the requested quantity of values.
+Both constructors require a scope.
+Both expose normal and immediate operations, `flush`, and a `pending` address count.
+Standalone debouncers do not provide a transport, retry policy, or cache.
+
+`createRegisterCache()` provides `filter`, `observe`, `invalidate`, and generation tracking.
+Call `observe` only after a successful write acknowledgement.
+Use its generation token to preserve invalidations during an in-flight write.
+
+`makeBatchingClient({ unitId, client, cache, debounce?, plan? })` composes these utilities over an `EffectModbusClient`.
+Its `cache` field is required; pass `undefined` to omit a cache.
+A raw promise-based binding client is not accepted directly.
+
+`createBatchingRegistry(deps)` provides per-unit declarations and connection-driven cache invalidation for custom transports.
+Pass public raw clients through `registry.guardRawWrites(unitId, client)` to enforce the register-write guard.
 
 ## Error handling
 
-Errors from the underlying Rust layer are mapped to typed `Effect` errors via `Data.TaggedError`:
-
-| Error class                   | Meaning                                               |
-| ----------------------------- | ----------------------------------------------------- |
-| `ModbusExceptionError`        | Modbus protocol exception (contains `exception` code) |
-| `ModbusTimeoutError`          | Request timed out                                     |
-| `ModbusTransportError`        | Transport-level failure                               |
-| `ModbusInvalidArgumentError`  | Invalid parameters                                    |
-| `ModbusConnectionClosedError` | Connection lost                                       |
-| `ModbusNotConnectedError`     | Operation attempted before connection                 |
-| `ModbusInternalError`         | Unclassified error                                    |
-
-Handle with `Effect.catchTags`. The `ModbusError` union type covers all seven variants.
-
-`withBatchingClient` can also fail with `ModbusUnitAlreadyDeclaredError` when the unit already has a batching client. This error is not a member of `ModbusError`, because it never comes from the bus. See [Declaring a unit, and reaching for it](#declaring-a-unit-and-reaching-for-it).
-
-## Resilience: retries, reconnection, and circuit breaking
-
-> **These are application-level policies, and they are opt-in.**
->
-> They are also the _only_ retries in play. The **transport-level** knobs the underlying `modbus-rs` library offers — `retryAttempts`, `retryDelayMs`, and `retryBackoffStrategy` — are **not accepted** by any transport constructor here. Passing one is a type error. See [Why the upstream retry knobs are withheld](#why-the-upstream-retry-knobs-are-withheld).
-
-Resilience belongs to the **transport**, not to call sites. Attach a policy where the transport is created and every client derived from it carries it:
-
-```ts
-const layer = TcpTransportService.make({
-  host: '192.168.1.50',
-  port: 502,
-  retry: RetryPolicies.tcp(), // applied to every operation
-  reconnect: {}, // supervised reconnect + circuit breaker
-});
-
-// call sites never mention retries
-Effect.gen(function* () {
-  const client = yield* transport.withClient(1);
-  yield* client.readHoldingRegisters({ address: 0, quantity: 10 });
-});
-```
-
-With neither option set, a transport behaves exactly as it always has: one attempt per operation, reconnection only when you ask for it.
-
-### Templates
-
-| Template                     | Shape                                                   | For                                   |
-| ---------------------------- | ------------------------------------------------------- | ------------------------------------- |
-| `RetryPolicies.none()`       | 1 attempt                                               | Opting out of a wider policy          |
-| `RetryPolicies.serial()`     | 3 retries, 50 ms base, ×2, 1 s ceiling                  | RS-232/485 — collisions, noise bursts |
-| `RetryPolicies.tcp()`        | 4 retries, 100 ms base, ×2, 5 s ceiling                 | Modbus/TCP — sockets and gateways     |
-| `RetryPolicies.persistent()` | 10 retries, 250 ms base, ×2, 30 s ceiling, 5 min budget | Long-running background polling       |
-
-All four jitter their delays — see [Backoff and jitter](#backoff-and-jitter) — and none retry `ModbusInvalidArgumentError` or a deterministic exception code.
-
-Every template is a factory taking overrides, so it doubles as a starting point. Overrides merge into the template rather than replacing it wholesale:
-
-```ts
-RetryPolicies.serial({
-  maxRetries: 6,
-  errors: { ModbusTimeoutError: { baseDelay: '80 millis' } },
-});
-```
-
-`createRetryPolicy(options)` builds one from scratch with the same options.
-
-### Overriding per client and per operation
-
-One bus often hosts device types that need different logic. A per-client policy **replaces** the transport's, so overrides can never multiply attempt counts:
-
-```ts
-Effect.gen(function* () {
-  const meter = yield* transport.withClient(1, { retry: RetryPolicies.serial() });
-  const plc = yield* transport.withClient(2, { retry: RetryPolicies.serial({ maxRetries: 8 }) });
-  const legacy = yield* transport.withClient(3, { retry: RetryPolicies.none() });
-});
-```
-
-Clients built for the same unit ID under different policies share one underlying connection.
-
-`client.withRetry(policy)` does the same for a single operation:
-
-```ts
-Effect.gen(function* () {
-  yield* client.withRetry(RetryPolicies.none()).writeSingleCoil({ address: 0, value });
-});
-```
-
-Resolution order is **per-operation → per-client → transport → none**. First match wins; the others are discarded, not combined.
+Binding failures are converted to tagged errors through `toModbusError`.
+Handle typed failures with `Effect.catchTag` or `Effect.catchTags`.
+
+| Error                         | Meaning                                                     |
+| ----------------------------- | ----------------------------------------------------------- |
+| `ModbusExceptionError`        | Device returned a protocol exception; includes its code.    |
+| `ModbusTimeoutError`          | Request or connection wait timed out.                       |
+| `ModbusTransportError`        | Transport or malformed-response failure.                    |
+| `ModbusInvalidArgumentError`  | Invalid operation parameters or local API use.              |
+| `ModbusConnectionClosedError` | Connection closed unexpectedly.                             |
+| `ModbusNotConnectedError`     | Operation needs an open transport or scope.                 |
+| `ModbusCircuitOpenError`      | Reconnection guard refused an operation without sending it. |
+| `ModbusInternalError`         | Unclassified failure.                                       |
+
+`ModbusError` includes these eight variants.
+`ModbusUnitAlreadyDeclaredError` is a separate local declaration error and is not retryable through Modbus policies.
+
+## Retries and reconnection
+
+Retries and supervised reconnection are opt-in transport policies.
+Without a retry policy, each operation has one attempt.
+Without `reconnect`, no reconnection supervisor or circuit guard starts.
+
+Configure `retry` and `reconnect` on the transport layer.
+`reconnect: {}` enables the default supervisor policy and circuit guard.
+
+### Retry policies
+
+| Factory                      | Default budget and delay                                                      |
+| ---------------------------- | ----------------------------------------------------------------------------- |
+| `RetryPolicies.none()`       | One attempt, no retries.                                                      |
+| `RetryPolicies.serial()`     | Three retries, 50 ms base, factor 2, 1 s maximum.                             |
+| `RetryPolicies.tcp()`        | Four retries, 100 ms base, factor 2, 5 s maximum.                             |
+| `RetryPolicies.persistent()` | Ten retries, 250 ms base, factor 2, 30 s maximum, five-minute elapsed budget. |
+
+Factories accept overrides.
+`createRetryPolicy(options)` creates a policy without a template.
+Policies retry timeouts, transport failures, closed connections, and open circuits by default.
+Protocol exceptions retry only for codes 5, 6, 10, and 11 by default.
+Invalid arguments, not-connected errors, and internal errors do not retry by default.
+Per-error settings can disable or enable retries and set separate backoff values.
+The retry count is shared across error categories.
+
+Backoff uses `min(maxDelay, baseDelay × factor ** retryIndex)` before jitter.
+Jitter defaults to a multiplier from 0.8 to 1.2.
+Set `jitter: false` for deterministic delays, or provide `{ min, max }` multipliers.
+
+### Policy replacement and compound retries
+
+`withClient(unitId, { retry })` replaces the transport retry policy for that client.
+`client.withRetry(policy)` replaces the active policy for operations through the returned client.
+These policies do not combine.
+Resolution order is operation override, client override, transport policy, then no retries.
+
+`retryModbus(policy)` wraps an effect, including retries already inside it.
+Nested policies multiply operation attempt counts.
+For a compound read/write retry, first obtain a client with `RetryPolicies.none()`.
+Then wrap the compound effect with `retryModbus`.
+Repeating a compound operation can repeat earlier successful writes; it does not provide atomicity or rollback.
+See [the retry example](examples/retry-policies.ts).
+
+### Connection state and circuit guard
+
+`transport.connectionState` is a `SubscriptionRef` of connection states.
+One supervisor serves each transport, including when several callers report connection failures.
+Default trigger errors are `ModbusConnectionClosedError` and `ModbusTransportError`.
+The default reconnect policy allows five retries with 250 ms base delay, factor 2, and 10 s maximum delay.
+The circuit reset interval defaults to 30 seconds.
+Use `reconnect.policy`, `resetAfter`, and `triggerOn` to change these settings.
+
+| State          | Meaning                                                                               |
+| -------------- | ------------------------------------------------------------------------------------- |
+| `Disconnected` | No open connection. Client acquisition opens it unless the transport has been closed. |
+| `Connected`    | The connection is available.                                                          |
+| `Reconnecting` | The supervisor is reconnecting. The enabled guard rejects operations.                 |
+| `Down`         | A connection failure was observed. The enabled supervisor waits before probing again. |
+
+With supervision enabled, operations in `Reconnecting` or `Down` fail with `ModbusCircuitOpenError`.
+Retry policies can wait for recovery within their budgets.
+Without supervision, `Down` does not activate a circuit guard.
+Call `transport.reconnect()` for manual recovery.
+A later successful operation also restores `Connected`.
+
+### Connection and request timeouts
+
+`connectTimeout` limits each caller's wait for an open or reconnect.
+It is unbounded by default.
+When the wait expires, the caller fails with `ModbusTimeoutError`.
+The native connection attempt cannot be cancelled and continues after that timeout.
+Later callers wait for the same pending attempt, each with their own timeout.
+A late successful connection remains usable.
+
+`requestTimeoutMs` limits requests through binding options.
+It does not limit connection acquisition.
+`setRequestTimeout(ms)` and `clearRequestTimeout()` require an open transport.
+`transport.close(scope)` finalizes the supplied caller scope, then closes the transport even if a finalizer fails.
+Later use cannot reopen that closed transport.
+
+### Native request limits
+
+The native services use `modbus-rs` 0.16.3.
+`responseTimeoutMs` limits a device response. `requestTimeoutMs` limits admission to the native queue.
+If `responseTimeoutMs` is absent, the services use `requestTimeoutMs` as its fallback.
+The native default response limit is 1000 ms.
+The services do not replace the response option with an automatic `setRequestTimeout` call.
+An isolated request timeout does not cause an automatic reconnect.
+
+The native `setRequestTimeout` method changes both limits. `clearRequestTimeout` removes both limits.
+Serial calls retain one drain lock, including their guard and failure report.
+An Effect interruption waits for a bounded native call to finish.
+If a serial call has no response limit, interruption closes its handle instead of waiting indefinitely.
+Later operations open a new handle and preserve explicit runtime limit settings.
+An interrupted caller that is still waiting for the lock sends no request.
+
+The 0.16.3 binding drains a cancelled serial response before it sends the next request.
+This fixes the follow-up checksum error reproduced with a raw native `AbortSignal` in 0.16.2.
+Use Effect fiber interruption to cancel service operations.
+TCP requests remain concurrent. The WASM service code does not change.
+
+Serial paths can contain up to 128 characters in this binding version.
+A longer stable link uses a short scoped alias to the configured path.
+The alias follows link changes during device re-enumeration. Scope close removes the alias.
+`resolveSerialPortPath` resolves one snapshot only. Do not cache its target across device re-enumeration.
+
+### Upstream retry options
+
+The constructors exclude `retryAttempts`, `retryDelayMs`, and `retryBackoffStrategy` through `WithoutUpstreamRetry`.
+Use Effect-level `retry` and `reconnect` instead.
+This prevents nested binding retries and competing reconnection policies.
+The package exports narrowed native option types, `WithoutUpstreamRetry<T>`, and `UpstreamRetryOptionKey`.
+
+## Servers and gateway
+
+| Layer factory                                   | Binding                                                            |
+| ----------------------------------------------- | ------------------------------------------------------------------ |
+| `tcpServerLayer(options, handlers)`             | Native Modbus TCP server.                                          |
+| `serialRtuServerLayer(options, handlers)`       | Native serial RTU server.                                          |
+| `serialAsciiServerLayer(options, handlers)`     | Native serial ASCII server.                                        |
+| `tcpGatewayLayer(options, gatewayConfig)`       | Native gateway with downstream entries and unit-to-channel routes. |
+| `wasmWsServerLayer(options, handlers)`          | Experimental browser WebSocket server.                             |
+| `wasmSerialRtuServerLayer(options, handlers)`   | Experimental browser serial RTU server.                            |
+| `wasmSerialAsciiServerLayer(options, handlers)` | Experimental browser serial ASCII server.                          |
+
+Server layers bind during layer acquisition and attempt shutdown during scope finalization.
+Bind failures enter the typed `ModbusError` channel.
+Shutdown failures are ignored.
+Browser server layers also fork the binding's `serve()` loop within the layer scope and log loop failures.
+Serial browser servers require a raw `SerialPort` from application code, not the client helper's opaque port handle.
+Handlers use the upstream `ServerHandlers` interface.
+See [the TCP server example](examples/tcp-server.ts), [serial server example](examples/serial-server.ts), and [gateway example](examples/tcp-gateway.ts).
 
-#### Replacing vs. wrapping
-
-Two things look alike at a call site — both read as "attach a policy here" — but behave differently, and the difference is worth internalising:
-
-| Form                            | Effect on the policy already in force |
-| ------------------------------- | ------------------------------------- |
-| `withClient(unitId, { retry })` | **Replaces** it                       |
-| `client.withRetry(policy)`      | **Replaces** it                       |
-| `.pipe(retryModbus(policy))`    | **Wraps** it — the two nest           |
-
-The deciding factor is whether the policy goes _through_ the client or _around_ it. The first two are resolved inside the client when it is built, so the previous policy is never applied. `retryModbus` is a free function piped around an effect the client has **already** wrapped in its own retry — nothing in that path can see the inner policy, so both run and the attempt counts multiply.
+## Testing with mocks
 
-Concretely, against a transport policy of `maxRetries: 2` (3 attempts):
+Each transport tag provides `makeMockTransport(devices)(options)`.
+The result is a scoped layer with in-memory device state and no browser, network, or serial I/O.
+Options include the transport's connection settings, resilience settings, and mock fault hooks.
+The abstract serial tags accept either framing's connection settings.
 
 ```ts
-transport.withClient(1, { retry: fast(3) })          // 4 attempts  (replaced)
-client.withRetry(fast(4)).readHoldingRegisters(...)  // 5 attempts  (replaced)
-client.readHoldingRegisters(...).pipe(retryModbus(fast(3))) // 12 attempts (3 × 4)
-```
-
-That last form is only correct over a `RetryPolicies.none()` client — see [Retrying a transaction](#retrying-a-transaction).
-
-### Error-aware by construction
-
-Retrying is only correct for failures that can plausibly resolve themselves, so the policy decides per error:
-
-| Error                         | Retried by default                                                 |
-| ----------------------------- | ------------------------------------------------------------------ |
-| `ModbusTimeoutError`          | yes — slow turnaround, bus contention                              |
-| `ModbusTransportError`        | yes — framing/CRC corruption                                       |
-| `ModbusConnectionClosedError` | yes — and hands the link to the supervisor                         |
-| `ModbusCircuitOpenError`      | yes — refused without touching the bus, so it is cheap to wait out |
-| `ModbusExceptionError`        | only for codes `5`, `6`, `10`, `11` (busy / gateway)               |
-| `ModbusInvalidArgumentError`  | no — the answer will not change                                    |
-| `ModbusNotConnectedError`     | no                                                                 |
-| `ModbusInternalError`         | no                                                                 |
-
-Any of these can be switched off (`errors: { ModbusTimeoutError: false }`), switched on, or given their own backoff curve (`errors: { ModbusConnectionClosedError: { baseDelay: '250 millis' } }`). The retry budget is shared across categories — only the delay curve is per-error — so a mixed failure sequence still stops after `maxRetries`.
-
-### Backoff and jitter
-
-Delays follow `min(maxDelay, baseDelay × factor ** retryIndex)`, then get jittered.
-
-**Jitter is on by default** — for `createRetryPolicy()` and for every template, none of which opts out. Each delay is multiplied by a random factor so a fleet of pollers does not re-hit a recovering device in lockstep:
-
-| `jitter`                     | Delay                                                    |
-| ---------------------------- | -------------------------------------------------------- |
-| omitted, or `true` (default) | ±20% — Effect's `0.8 – 1.2` multiplier range             |
-| `false`                      | exact, unrandomised delays — useful for assertable tests |
-| `{ min: 0.5, max: 1.5 }`     | custom multiplier range                                  |
-
-So `RetryPolicies.tcp()` waits roughly 80–120 ms before its first retry, not exactly 100 ms.
-
-### Supervised reconnection and the circuit breaker
-
-Passing `reconnect` hands reconnection to a supervisor fiber owned by the transport — **one reconnect for the whole application**, however many fibers were in flight when the link dropped:
+import { Console, Effect } from 'effect';
+import { TcpTransportService } from '@flux-control/effect-modbus-rs';
 
-```ts
-TcpTransportService.make({
-  host,
-  port,
-  reconnect: {
-    policy: RetryPolicies.tcp(), // how reconnect attempts are spaced
-    resetAfter: '30 seconds', // how long the circuit stays open before probing
-    triggerOn: ['ModbusConnectionClosedError', 'ModbusTransportError'],
+const layer = TcpTransportService.makeMockTransport([
+  {
+    unitId: 1,
+    coils: [],
+    discreteInputs: [],
+    holdingRegisters: [{ address: 0, default: 100 }],
+    inputRegisters: [],
   },
-});
-```
-
-While the link is being re-established, operations are refused with `ModbusCircuitOpenError` instead of queueing requests onto a dead bus. Because that error is retryable by default and costs nothing on the wire, a polling loop with a generous policy simply rides out the outage; one with a short budget fails fast and lets the caller decide.
-
-Without `reconnect`, a connection-level failure still publishes `Down`, but no
-supervisor starts and no circuit breaker is enabled. Call `transport.reconnect()`
-to recover manually. A later successful operation also restores `Connected`, so
-a transient failure recovered by an operation retry does not leave stale state.
-
-State transitions are published on `transport.connectionState`:
-
-| State          | Meaning                                                                                       |
-| -------------- | --------------------------------------------------------------------------------------------- |
-| `Disconnected` | Never opened, or closed. The next operation opens it lazily.                                  |
-| `Connected`    | Usable.                                                                                       |
-| `Reconnecting` | Supervisor is re-establishing the link. Operations refused.                                   |
-| `Down`         | Link failure observed. A configured supervisor waits to probe; manual mode remains unguarded. |
-
-```ts
-Effect.gen(function* () {
-  yield* Stream.runForEach(SubscriptionRef.changes(transport.connectionState), (state) =>
-    Console.log(`link: ${state._tag}`),
-  );
-});
-```
-
-### Connect timeout
+])({ host: '192.0.2.1', port: 502 });
 
-The `modbus-rs` bindings do not limit the time of a connect. A TCP connect to a host that does not answer waits until the operating system stops it. On Linux with default settings, this takes about 2 minutes. During that time, every operation joins the same pending connect.
-
-Set `connectTimeout` to limit how long each operation waits for an open or a reconnect:
-
-```ts
-TcpTransportService.make({
-  host: '192.0.2.1',
-  port: 502,
-  connectTimeout: '3 seconds', // limit for each wait on an open or reconnect
-  reconnect: {},
-});
-```
-
-The limit applies to each operation that waits for an open or reconnect. When it expires, that operation fails with `ModbusTimeoutError`.
-
-The native connect cannot be cancelled, so it continues after the timeout:
-
-- Later operations wait for the same native connect, each for at most the limit. A transport never has more than one pending native connect.
-- When the native connect succeeds later, the transport uses it. A late reconnect that succeeds after the supervisor published `Down` publishes `Connected` at once.
-- When the native connect fails, the next operation starts a new connect.
-- A supervised reconnect attempt that times out is retried by the reconnect policy by default. When the attempts are exhausted, the transport publishes `Down`.
-
-The option applies to every transport. It is unbounded by default. `requestTimeoutMs` limits each request, but it does not limit the connect.
-
-### Retrying a transaction
-
-`retryModbus(policy)` remains exported for the one case the transport cannot express: driving a **compound** operation as a unit, where retrying individual frames would be wrong.
-
-```ts
 Effect.gen(function* () {
-  const client = yield* transport.withClient(1, { retry: RetryPolicies.none() });
-
-  yield* Effect.gen(function* () {
-    const current = yield* client.readHoldingRegisters({ address: 0, quantity: 2 });
-    yield* client.writeMultipleRegisters({ address: 0, values: bump(current) });
-  }).pipe(retryModbus(RetryPolicies.tcp()));
-});
-```
-
-Take a `RetryPolicies.none()` client first. Unlike `withClient({ retry })` and `client.withRetry()`, which replace the policy in force, `retryModbus` wraps whatever the client is already doing — so over a policied client the two nest and the attempt counts multiply. See [Replacing vs. wrapping](#replacing-vs-wrapping).
-
-See `examples/retry-policies.ts` for a runnable walkthrough.
-
-### Why the upstream retry knobs are withheld
-
-`modbus-rs` exposes `retryAttempts`, `retryDelayMs`, and `retryBackoffStrategy` on its transport options. This package removes all three from every transport constructor, so setting one is a compile error rather than a documented hazard:
-
-```ts
-TcpTransportService.make({ host, port, retryAttempts: 3 });
-//                                        ^^^^^^^^^^^^^ Object literal may only specify
-//                                        known properties, and 'retryAttempts' does not
-//                                        exist in type 'TcpTransportOpenOptions & …'
-```
-
-They are withheld rather than merely discouraged because enabling them is never the right call under this design:
-
-- **They retry below the Effect boundary.** A failure they paper over never reaches your policy, the circuit breaker, or your logs. The caller sees one slow success instead of several failures and a recovery, and any caller-side `Effect.timeout` is measuring inflated time.
-- **They reconnect.** Upstream re-establishes the link inline and replays in-flight requests after it, which races the single supervisor fiber that is supposed to own reconnection for the whole transport.
-- **They multiply.** Neither layer knows about the other, so attempt counts compound and the two backoff curves interleave.
-- **`retryDelayMs` is flat and unjittered** — exactly the lockstep-collision pattern `RetryPolicies.serial()` exists to break up on a shared RS-485 segment.
-- **`retryBackoffStrategy` does nothing.** It is documented upstream as inert and reserved for future implementation, so `'exponential'` silently gets you a flat delay.
-
-Use `retry` and `reconnect` on the transport instead. If you genuinely need frame-level resends, construct a raw `modbus-rs` client directly, where that trade-off is explicit rather than hidden under an Effect service.
-
-The narrowed option types are exported as `RtuTransportOpenOptions`, `AsciiTransportOpenOptions`, and `TcpTransportOpenOptions`, alongside the generic `WithoutUpstreamRetry<T>` and the `UpstreamRetryOptionKey` union.
-
-## Testing with mocks
-
-Each transport service provides a `makeMockTransport(devices)` static method that returns an in-memory mock `Layer` — no serial port or network required.
-
-```ts
-import { Console, Effect } from 'effect';
-import { RtuTransportService } from '@flux-control/effect-modbus-rs';
-
-const device = {
-  unitId: 1,
-  coils: [
-    { address: 0, default: true },
-    { address: 1, default: false },
-  ],
-  discreteInputs: [],
-  holdingRegisters: [
-    { address: 0, default: 100 },
-    { address: 1, default: 200 },
-  ],
-  inputRegisters: [],
-};
-
-const program = Effect.gen(function* () {
-  const transport = yield* RtuTransportService;
+  const transport = yield* TcpTransportService;
   const client = yield* transport.withClient(1);
-  const coils = yield* client.readCoils({ address: 0, quantity: 2 });
-  console.log('Coils:', coils);
-});
-
-const mockLayer = RtuTransportService.makeMockTransport([device])({
-  portPath: '/dev/ttyUSB0',
-  baudRate: 9600,
-});
-
-program.pipe(Effect.provide(mockLayer), Effect.scoped, Effect.runPromise);
+  yield* Console.log(yield* client.readHoldingRegisters({ address: 0, quantity: 1 }));
+}).pipe(Effect.provide(layer), Effect.scoped, Effect.runPromise);
 ```
 
-The mock factory is the same for every transport. Each tag has a static `makeMockTransport` method, and each accepts the same options: the open options of that transport, the resilience options (`retry` and `reconnect`), and the two fault hooks below. To change transport, use a different tag and adjust the shape of the open options.
-
-See `examples/rtu-mock.ts`, `examples/tcp-mock.ts`, and `examples/ascii-mock.ts` for full walkthroughs covering read, write, multi-device access, and error-case testing.
-
-### Fault injection
+### Device definitions
 
-Two mock-only hooks make a policy testable without hardware:
+| Field              | Contents                 | Default      |
+| ------------------ | ------------------------ | ------------ |
+| `unitId`           | Device unit ID.          | Required.    |
+| `coils`            | `{ address, default }[]` | Empty array. |
+| `discreteInputs`   | `{ address, default }[]` | Empty array. |
+| `holdingRegisters` | `{ address, default }[]` | Empty array. |
+| `inputRegisters`   | `{ address, default }[]` | Empty array. |
 
-| Hook             | When it runs                   | Return value                                                                 |
-| ---------------- | ------------------------------ | ---------------------------------------------------------------------------- |
-| `fault`          | Before every operation attempt | A `ModbusError` fails that attempt. `undefined` lets it through.             |
-| `reconnectFault` | Before every reconnect attempt | A `ModbusError` keeps the link down. `undefined` lets the reconnect succeed. |
+The schema supplies defaults when decoding omitted fields.
+The typed mock factory accepts decoded definitions, so TypeScript callers must provide those fields explicitly.
+Address-level coil defaults are `false`; register defaults are zero.
+Each register space extends through its highest configured address, with zero or false values in gaps.
+Reads beyond that range fail with `ModbusInvalidArgumentError`.
+Invalid device definitions throw a synchronous schema decode error when the factory is called.
+FIFO and file-record operations are not implemented by the mock and fail with `ModbusInvalidArgumentError`.
 
-Because `fault` runs before each _attempt_, an error from it is the same as a device that refused that attempt. A retry policy, the backoff, and the circuit breaker therefore behave as they do on a real bus:
+### Fault hooks
 
-```ts
-import {
-  ModbusTimeoutError,
-  RetryPolicies,
-  RtuTransportService,
-} from '@flux-control/effect-modbus-rs';
-
-let attempts = 0;
-
-const mockLayer = RtuTransportService.makeMockTransport([device])({
-  portPath: '/dev/ttyUSB0',
-  baudRate: 9600,
-  retry: RetryPolicies.serial(),
-  fault: () =>
-    attempts++ < 2
-      ? new ModbusTimeoutError({ message: 'no response', cause: new Error('timeout') })
-      : undefined,
-});
-```
-
-### Slave device schema
-
-| Property           | Type                     | Default  |
-| ------------------ | ------------------------ | -------- |
-| `unitId`           | `number`                 | required |
-| `coils`            | `{ address, default }[]` | `[]`     |
-| `discreteInputs`   | `{ address, default }[]` | `[]`     |
-| `holdingRegisters` | `{ address, default }[]` | `[]`     |
-| `inputRegisters`   | `{ address, default }[]` | `[]`     |
-
-Coil/default values default to `false` if omitted at the address level; register values default to `0`. Reads beyond the highest configured address produce a `ModbusInvalidArgumentError`.
+`fault` runs before each operation attempt.
+`reconnectFault` runs before each reconnect attempt.
+Return a `ModbusError` to fail that attempt, or `undefined` to allow it.
+Because hooks run per attempt, retry and reconnection policies can be tested without hardware.
+See [RTU mocks](examples/rtu-mock.ts), [TCP mocks](examples/tcp-mock.ts), and [ASCII mocks](examples/ascii-mock.ts).
 
 ## Development
 
-| Action      | Command                      |
-| ----------- | ---------------------------- |
-| Install     | `bun install`                |
-| Type-check  | `bun run typecheck`          |
-| Test        | `bun test`                   |
-| Run example | `bun run examples/<name>.ts` |
-
-No build step — `noEmit` is on; Bun runs `.ts` directly.
+Run these commands from the package root.
+If a parent workspace manages dependencies, install from that workspace's root.
+
+| Action                            | Command                      |
+| --------------------------------- | ---------------------------- |
+| Install                           | `bun install`                |
+| Check formatting                  | `bun run format`             |
+| Apply formatting                  | `bun run format:fix`         |
+| Lint                              | `bun run lint`               |
+| Type-check                        | `bun run typecheck`          |
+| Test package and native examples  | `bun run test`               |
+| Build JavaScript and declarations | `bun run build`              |
+| Generate API documentation        | `bun run docs`               |
+| Run a native example              | `bun run examples/<name>.ts` |
+
+Package exports use `dist/`.
+Build before testing package imports or running the browser example.
+Native examples can run from TypeScript with Bun.
+The separate [browser example](examples/wasm/README.md) uses npm and Vite.
+Package checks do not check that application.
 
 ## Source layout
 
-```
-src/
-  errors.ts                  — Data.TaggedError types + toModbusError converter
-  modbus-client.ts           — EffectModbusClient interface + factory (native + WASM)
-  mocks.ts                   — Schema-validated mock transport + slave device definitions
-  connection.ts              — Connection state machine, reconnect supervisor, circuit breaker
-  retry.ts                   — Opt-in retry policies (backoff, jitter, per-error rules)
-  shared-transport.ts        — Generic scoped transport lifecycle management, WithoutUpstreamRetry
-  register-plan.ts           — planWrites / planReads: pure transaction packing
-  register-cache.ts          — createRegisterCache: what each device already holds
-  write-debouncer.ts         — createWriteDebouncer: coalesces writes that arrive separately
-  read-debouncer.ts          — createReadDebouncer: collects reads that arrive separately
-  batching-client.ts         — the batching client and the per-transport registry
-  span-attributes.ts         — ModbusSpanAttributes and the merge rule for a batch
-  RtuTransportService.ts     — Scoped Context.Service wrapping AsyncRtuTransport
-  TcpTransportService.ts     — Scoped Context.Service wrapping AsyncTcpTransport
-  AsciiTransportService.ts   — Scoped Context.Service wrapping AsyncAsciiTransport
-  SerialTransportService.ts  — Abstract serial transport (RTU/ASCII) tag
-  TcpModbusServerService.ts  — tcpServerLayer
-  SerialModbusServerService.ts — serialRtuServerLayer / serialAsciiServerLayer
-  TcpGatewayService.ts       — tcpGatewayLayer
-  WasmSerialPort.ts          — requestSerialPort() Effect helper (browser, user-gesture gated)
-  WasmWsTransportService.ts  — Scoped Context.Service wrapping WasmWsTransport (browser, WS gateway)
-  WasmRtuTransportService.ts — Scoped Context.Service wrapping WasmRtuTransport (browser, Web Serial RTU)
-  WasmAsciiTransportService.ts — Scoped Context.Service wrapping WasmAsciiTransport (browser, Web Serial ASCII)
-  WasmSerialTransportService.ts — Abstract browser serial transport (RTU/ASCII) tag
-  WasmTcpServerService.ts    — wasmWsServerLayer (experimental)
-  WasmSerialModbusServerService.ts — wasmSerialRtuServerLayer / wasmSerialAsciiServerLayer (experimental)
-examples/
-  rtu-basic.ts               — RTU usage pattern
-  tcp-basic.ts               — TCP usage pattern
-  ascii-basic.ts             — ASCII usage pattern
-  serial-abstract.ts         — Abstract serial transport (RTU or ASCII)
-  rtu-mock.ts                — RTU with in-memory mock
-  tcp-mock.ts                — TCP with in-memory mock (multi-device)
-  ascii-mock.ts              — ASCII with in-memory mock (error-case)
-  retry-policies.ts          — Transport-owned resilience: policies, overrides, transactions
-  batching.ts                — Transaction batching: planners, cache, windows, spans
-  tcp-polling-stream.ts      — TCP polling, reconnect, and stream
-  tcp-finalizer-reset.ts     — TCP scope finalizer reset demo
-  tcp-server.ts              — TCP server example
-  serial-server.ts           — Serial RTU server example
-  wasm/                      — Standalone runnable Vite app for the browser transports (own README, own npm project)
-index.ts                     — Re-exports public API
-```
+- `index.ts`: Public exports and package overview.
+- `src/*TransportService.ts`: Concrete and abstract transport services.
+- `src/*ServerService.ts` and `src/TcpGatewayService.ts`: Scoped servers and gateway.
+- `src/WasmSerialPort.ts`: Browser port-request helper.
+- `src/shared-transport.ts`: Connection ownership, client caching, and raw-write guards.
+- `src/modbus-client.ts`: Typed operations over native and browser binding clients.
+- `src/errors.ts`: Tagged failures and binding-error conversion.
+- `src/retry.ts` and `src/connection.ts`: Retry policies, reconnection supervisor, and circuit guard.
+- `src/register-plan.ts`: Pure read and write transaction planners.
+- `src/register-cache.ts`: Acknowledged-write cache and generation-based invalidation.
+- `src/read-debouncer.ts` and `src/write-debouncer.ts`: Scoped request collection.
+- `src/batching-client.ts`: Batching composition and per-unit registry.
+- `src/span-attributes.ts`: Caller attribute merging.
+- `src/mocks.ts`: Device schemas and in-memory transports.
+- `test/`: Operation, lifecycle, retry, batching, and compile-time option checks.
+- `examples/`: Native examples and the separate browser application.
 
 ## License