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

package/dist/src/batching-client.d.ts

@@ -1,12 +1,5 @@
 /**
- * @fileoverview A client that decides the transactions, rather than issuing the
- * ones a caller names.
- *
- * `withClient` returns an {@link EffectModbusClient}: it issues exactly the
- * transaction asked for, and it is the right client when a caller knows what the
- * bus should carry. This module is its sibling for the other case — a caller with
- * one accessor per register, which knows what it wants to read and write but not
- * what that ought to cost.
+ * @fileoverview Batching clients collect and plan register operations for a unit.
  *
  * @module
  */
@@ -82,13 +75,29 @@ export interface BatchingClientOptions {
 }
 /** Reads over one register space. */
 export interface BatchingRegisterReader {
-    /** Collects an address for the read window, then returns its value. */
+    /**
+     * Collects an address for the read window, then returns its value.
+     * @param address - Register address.
+     * @returns The register value, or a Modbus error.
+     */
     read(address: number): Effect.Effect<number, ModbusError>;
-    /** Adds an address to the batch and reads immediately, answering every reader in it. */
+    /**
+     * Adds an address and flushes collected reads immediately.
+     * @param address - Register address.
+     * @returns The register value, or a Modbus error.
+     */
     readNow(address: number): Effect.Effect<number, ModbusError>;
-    /** Reads a group as one reader, planned into spans, in the order asked for. */
+    /**
+     * Collects a group as one reader and returns values in the requested order.
+     * @param addresses - Register addresses, in result order.
+     * @returns Register values in the requested order, or a Modbus error.
+     */
     readAll(addresses: ReadonlyArray<number>): Effect.Effect<ReadonlyArray<number>, ModbusError>;
-    /** Adds a group to the batch and reads immediately. */
+    /**
+     * Adds a group and flushes collected reads immediately.
+     * @param addresses - Register addresses, in result order.
+     * @returns Register values in the requested order, or a Modbus error.
+     */
     readAllNow(addresses: ReadonlyArray<number>): Effect.Effect<ReadonlyArray<number>, ModbusError>;
 }
 /**
@@ -111,13 +120,37 @@ export interface BatchingRegisterReader {
 export interface BatchingModbusClient extends BatchingRegisterReader {
     /** The unit this client addresses. */
     readonly unitId: number;
-    /** Holds a write for the write window, then issues it with whatever else arrived. */
+    /**
+     * Holds a write for the write window, then issues it with other pending writes.
+     * Completion means the carrying batch succeeded; a cache can suppress its bus write.
+     * @param write - Register address and value.
+     * @param attributes - Optional span attributes for this caller.
+     * @returns Completion after the carrying batch succeeds, or its Modbus error.
+     */
     write(write: RegisterWrite, attributes?: ModbusSpanAttributes): Effect.Effect<void, ModbusError>;
-    /** Adds a write to the batch and issues it immediately, newest value winning. */
+    /**
+     * Adds a write and flushes pending writes immediately. The newest value wins.
+     * Completion means the carrying batch succeeded; a cache can suppress its bus write.
+     * @param write - Register address and value.
+     * @param attributes - Optional span attributes for this caller.
+     * @returns Completion after the carrying batch succeeds, or its Modbus error.
+     */
     writeNow(write: RegisterWrite, attributes?: ModbusSpanAttributes): Effect.Effect<void, ModbusError>;
-    /** Holds a group of writes as one caller. The group succeeds or fails together. */
+    /**
+     * Submits the group to the write debouncer as one caller.
+     * Completion reports its flush result; cache filtering can suppress physical writes.
+     * @param writes - Register writes.
+     * @param attributes - Optional span attributes for this caller.
+     * @returns Completion after the carrying batch succeeds, or its Modbus error.
+     */
     writeAll(writes: ReadonlyArray<RegisterWrite>, attributes?: ModbusSpanAttributes): Effect.Effect<void, ModbusError>;
-    /** Adds a group of writes to the batch and issues it immediately. */
+    /**
+     * Adds a group of writes and flushes pending writes immediately.
+     * Completion means the carrying batch succeeded; a cache can suppress bus writes.
+     * @param writes - Register writes.
+     * @param attributes - Optional span attributes for this caller.
+     * @returns Completion after the carrying batch succeeds, or its Modbus error.
+     */
     writeAllNow(writes: ReadonlyArray<RegisterWrite>, attributes?: ModbusSpanAttributes): Effect.Effect<void, ModbusError>;
     /** Reads over the input registers (FC04). The unqualified reads are holding registers (FC03). */
     readonly inputs: BatchingRegisterReader;
@@ -140,17 +173,17 @@ export interface BatchingModbusClient extends BatchingRegisterReader {
      */
     readonly debounce: BatchingDebounceWindows | undefined;
     /**
-     * Runs an action when the calling scope closes, while the bus is still open
-     * and before this client is torn down.
+     * Registers an action for the calling scope's finalization.
+     * Keep the transport open until that scope closes.
+     *
+     * The application selects the shutdown value. Use an immediate write method
+     * to avoid waiting for a collection window during cleanup.
      *
-     * A device's safe state is the device's own answer — zero volts for one, a
-     * stopped motor for another — so it is stated here, on the client that
-     * addresses it, rather than dispatched from one action over a set of units.
+     * An unhandled failure is logged and raised as a defect. Other finalizers
+     * still run. Wrap the action in `Effect.ignoreLogged` to accept its failure.
      *
-     * A failure is logged and then raised as a defect. The other finalizers 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.
+     * @param action - Shutdown action to run before client teardown.
+     * @returns An effect that registers the action in the calling scope.
      *
      * @example
      * const damper = yield* transport.withBatchingClient(3);
@@ -165,7 +198,7 @@ export interface BatchingModbusClient extends BatchingRegisterReader {
  * normally meets it. Call it directly to drive a client this package did not
  * hand out, such as another adapter implementing `EffectModbusClient`, or a stub.
  *
- * @param options - The unit, the Effect-wrapped client, and the policies.
+ * @param options - Unit, client, cache or `undefined`, debounce windows, and planner limits.
  * @returns The batching client, bound to the current scope.
  */
 export declare const makeBatchingClient: (options: {
@@ -222,7 +255,7 @@ export interface BatchingRegistry {
  * `withBatchingClient` declares. `batchingClient` looks up, and waits for a
  * declaration already under way rather than depending on which fiber ran first.
  *
- * @param deps - The transport's raw client factory, link state, and scope.
- * @returns The batching methods, ready to spread onto a transport API.
+ * @param deps - Raw client factory, link state, and transport scope.
+ * @returns Registry methods for declaring and retrieving per-unit clients.
  */
 export declare const createBatchingRegistry: (deps: BatchingRegistryDeps) => BatchingRegistry;

package/dist/src/connection.d.ts

@@ -1,3 +1,4 @@
+/** Models transport connection state and supervised reconnection with a circuit guard. */
 import { Data, Duration, Effect, type Scope, SubscriptionRef } from 'effect';
 import { ModbusCircuitOpenError, type ModbusError } from './errors';
 import { type ModbusErrorTag, type ModbusRetryPolicy } from './retry';
@@ -5,7 +6,7 @@ import { type ModbusErrorTag, type ModbusRetryPolicy } from './retry';
  * Live connection state of a transport.
  *
  * Owned by the transport and published through
- * {@link TransportServiceApi.connectionState}, so an application can show link
+ * `transport.connectionState`, so an application can show link
  * status without inferring it from failed reads.
  *
  * - `Disconnected` — never opened, or closed. Operations open it lazily.
@@ -143,7 +144,10 @@ export interface ResolvedReconnect {
     readonly resetAfter: Duration.Duration;
     readonly triggers: (error: ModbusError) => boolean;
 }
-/** Applies defaults to {@link ReconnectOptions}. */
+/** Applies defaults to reconnection options.
+ * @param options - Optional policy, reset interval, and trigger tags.
+ * @returns Resolved policy, reset duration, and failure predicate.
+ */
 export declare const resolveReconnect: (options: ReconnectOptions) => ResolvedReconnect;
 /**
  * Refuses an operation while the link is being re-established.

package/dist/src/errors.d.ts

@@ -27,8 +27,7 @@ declare const ModbusTimeoutError_base: new <A extends Record<string, any> = {}>(
  *
  * Mapped from {@link ModbusErrorCode.TIMEOUT} via `modbus-rs`.
  * Adjust timeouts via `setRequestTimeout` on the transport, or configure
- * with {@link RtuTransportOptions.requestTimeoutMs | requestTimeoutMs} /
- * {@link RtuTransportOptions.responseTimeoutMs | responseTimeoutMs}.
+ * with `requestTimeoutMs` or `responseTimeoutMs`, where the binding supports them.
  *
  * The transport also raises this error locally when an operation waits for an
  * open or reconnect longer than the `connectTimeout` transport option.
@@ -122,9 +121,8 @@ declare const ModbusNotConnectedError_base: new <A extends Record<string, any> =
  * connection was established or after it was closed.
  *
  * This is a **local** error — it is never returned by `modbus-rs`.
- * It is thrown by the transport service when `setRequestTimeout`,
- * `clearRequestTimeout`, or `withClient` is called before a
- * successful connection.
+ * Timeout setters require an open connection. Client acquisition opens the
+ * connection lazily, but fails after the transport scope has closed.
  *
  * Connect by calling `withClient(unitId)` on the transport service.
  * The connection is established lazily on the first call.
@@ -147,11 +145,10 @@ declare const ModbusCircuitOpenError_base: new <A extends Record<string, any> =
  * so the request was refused without touching the wire.
  *
  * This is a **local** error — it is never returned by `modbus-rs`. It is raised
- * by the transport when its connection state is `Reconnecting` or `Down`,
- * which keeps a dead device from being hammered by every caller at once.
+ * by the transport when supervision is enabled and its state is `Reconnecting`
+ * or `Down`. Refused operations do not send a request to the device.
  *
- * Retryable by default: a policy with enough budget rides out the outage
- * cheaply, since each refused attempt costs nothing on the bus.
+ * Retry policies retry this error by default within their configured budgets.
  *
  * @see ConnectionState — The transport state that produces this error.
  */
@@ -199,9 +196,10 @@ export declare class ModbusUnitAlreadyDeclaredError extends ModbusUnitAlreadyDec
 }> {
 }
 /**
- * Union of all typed Modbus errors emitted by this library.
+ * Union of typed operation and connection errors.
+ * Declaration errors are separate from this union.
  *
- * Handle with {@linkcode Effect.catchTags}:
+ * Handle with `Effect.catchTags`:
  *
  * ```ts
  * Effect.catchTags(client.readHoldingRegisters({ address: 0, quantity: 10 }), {
@@ -211,7 +209,8 @@ export declare class ModbusUnitAlreadyDeclaredError extends ModbusUnitAlreadyDec
  * })
  * ```
  *
- * Each variant maps to a specific {@link ModbusErrorCode} from `modbus-rs`.
+ * Binding failures map from {@link ModbusErrorCode}. Local guards can also
+ * produce errors in this union.
  *
  * @see ModbusErrorCode — The upstream error code enum driving this mapping.
  */

package/dist/src/mocks.d.ts

@@ -1,3 +1,4 @@
+/** Defines in-memory Modbus device schemas and mock transports for deterministic tests. */
 import { Effect, Schema, Scope, SubscriptionRef } from 'effect';
 import { type AsciiTransportOptions, type RtuTransportOptions, type TcpTransportOptions } from 'modbus-rs';
 import type { WasmWsTransportOptions, WasmSerialTransportOptions } from 'modbus-rs/web';
@@ -133,8 +134,8 @@ export type SlaveDeviceDefinitions = Schema.Schema.Type<typeof SlaveDeviceDefini
  * {@link ModbusInvalidArgumentError}.
  *
  * @param devices - Array of slave device definitions to simulate.
- * @returns A transport factory function that returns a scoped Effect
- *          providing the mock transport.
+ * @returns A factory that accepts transport and fault options and returns the mock transport Effect.
+ * @throws A schema decode error when `devices` does not match the device-definition schema.
  */
 export declare const createMockTransport: (devices: SlaveDeviceDefinitions) => (options: (WithoutUpstreamRetry<RtuTransportOptions> | WithoutUpstreamRetry<AsciiTransportOptions> | WithoutUpstreamRetry<TcpTransportOptions> | WasmWsTransportOptions | WasmSerialTransportOptions) & TransportResilienceOptions & MockFaultOptions) => Effect.Effect<{
     connectionState: SubscriptionRef.SubscriptionRef<{
@@ -159,6 +160,6 @@ export declare const createMockTransport: (devices: SlaveDeviceDefinitions) => (
     setRequestTimeout: (_timeoutMs: number) => Effect.Effect<void, ModbusNotConnectedError, never>;
     clearRequestTimeout: () => Effect.Effect<void, ModbusNotConnectedError, never>;
     reconnect: () => Effect.Effect<void, ModbusError, never>;
-    close: () => Effect.Effect<void, never, Scope.Scope>;
+    close: (scope: Scope.Closeable) => Effect.Effect<void, never, never>;
     hasPendingRequests: () => false;
 }, never, Scope.Scope>;

package/dist/src/modbus-client.d.ts

@@ -1,3 +1,4 @@
+/** Adapts native and WASM Modbus clients to typed Effect operations and transport resilience. */
 import { Effect } from 'effect';
 import type { ReadRegistersOptions, WriteSingleRegisterOptions, WriteMultipleRegistersOptions, ReadWriteMultipleRegistersOptions, ReadBitsOptions, WriteSingleCoilOptions, WriteMultipleCoilsOptions, ReadFifoQueueOptions, ReadFileRecordOptions, WriteFileRecordOptions, DiagnosticsOptions, ReadDeviceIdentificationOptions, FifoQueueResponse, DiagnosticsResponse, DeviceIdentificationResponse, AsyncSerialModbusClient, AsyncTcpModbusClient, CoilState } from 'modbus-rs';
 import type { WasmWsModbusClient, WasmSerialModbusClient } from 'modbus-rs/web';
@@ -9,6 +10,8 @@ export type NativeModbusClient = AsyncSerialModbusClient | AsyncTcpModbusClient;
 export type WasmModbusClient = WasmSerialModbusClient | WasmWsModbusClient;
 /** Any client this package knows how to wrap into an {@link EffectModbusClient}. */
 export type AnyModbusClient = NativeModbusClient | WasmModbusClient;
+/** Wraps one native call. A transport uses it to control when a request reaches the native queue. */
+export type NativeCallWrapper = <T>(call: Effect.Effect<T, ModbusError>) => Effect.Effect<T, ModbusError>;
 /**
  * The Modbus function-code surface, before any resilience is layered on.
  *
@@ -64,10 +67,10 @@ export interface ModbusOperations {
      */
     writeMultipleRegisters(opts: WriteMultipleRegistersOptions): Effect.Effect<void, ModbusError>;
     /**
-     * Atomic read-write of multiple registers (FC23).
+     * Writes and reads multiple registers within one request (FC23).
      *
-     * Performs a write operation and a read operation atomically within
-     * a single Modbus transaction.
+     * The device performs the write before the read. This does not make separate
+     * application operations atomic.
      *
      * @param opts - Separate read and write addresses/quantities/values.
      * @returns An Effect resolving to the read register values.
@@ -79,7 +82,7 @@ export interface ModbusOperations {
      * Reads coils (digital outputs) from the Modbus device (FC01).
      *
      * @param opts - Starting address, quantity, and optional `AbortSignal`.
-     * @returns An Effect resolving to an array of boolean coil states.
+     * @returns An Effect resolving to `CoilState` values.
      *
      * @see ReadBitsOptions — Options shape from `modbus-rs`.
      */
@@ -87,7 +90,7 @@ export interface ModbusOperations {
     /**
      * Writes a single coil (digital output) (FC05).
      *
-     * @param opts - Coil address, boolean value, and optional `AbortSignal`.
+     * @param opts - Coil address, `CoilState` value, and optional `AbortSignal`.
      * @returns An Effect that completes when the write is acknowledged.
      *
      * @see WriteSingleCoilOptions — Options shape from `modbus-rs`.
@@ -96,7 +99,7 @@ export interface ModbusOperations {
     /**
      * Writes multiple consecutive coils (FC15).
      *
-     * @param opts - Starting address, array of boolean values, and optional `AbortSignal`.
+     * @param opts - Starting address, array of `CoilState` values, and optional `AbortSignal`.
      * @returns An Effect that completes when the write is acknowledged.
      *
      * @see WriteMultipleCoilsOptions — Options shape from `modbus-rs`.
@@ -106,7 +109,7 @@ export interface ModbusOperations {
      * Reads discrete inputs (digital inputs) from the Modbus device (FC02).
      *
      * @param opts - Starting address, quantity, and optional `AbortSignal`.
-     * @returns An Effect resolving to an array of boolean input states.
+     * @returns An Effect resolving to `CoilState` values.
      *
      * @see ReadBitsOptions — Options shape from `modbus-rs`.
      */
@@ -182,13 +185,12 @@ export interface ModbusOperations {
  * transport-specific reshaping is needed.
  *
  * @param client - The upstream `modbus-rs` or `modbus-rs/web` client instance.
- * @returns An `EffectModbusClient` that can be used within Effect
- *          workflows.
+ * @returns A client whose methods return typed Effects.
  *
  * @see AsyncSerialModbusClient — Upstream native serial client API.
  * @see AsyncTcpModbusClient — Upstream native TCP client API.
  */
-export declare const createEffectModbusClient: (client: AnyModbusClient) => ModbusOperations;
+export declare const createEffectModbusClient: (client: AnyModbusClient | Effect.Effect<AnyModbusClient, ModbusError>, around?: NativeCallWrapper) => ModbusOperations;
 /**
  * Transport-owned resilience applied to every operation of a client.
  *
@@ -197,6 +199,8 @@ export declare const createEffectModbusClient: (client: AnyModbusClient) => Modb
  * reconnect serves every client derived from it.
  */
 export interface ClientResilience {
+    /** Protects the guard, native call, and failure report as one transport attempt. */
+    readonly aroundAttempt?: NativeCallWrapper;
     /** Refuses the operation while the transport's circuit is open. */
     readonly guard: Effect.Effect<void, ModbusError>;
     /** Records that an operation reached the device successfully. */

package/dist/src/read-debouncer.d.ts

@@ -1,19 +1,6 @@
 /**
- * @fileoverview Collects register reads that arrive separately into one span.
- *
- * `planReads` merges the addresses a caller holds at one moment. A caller with an
- * accessor per parameter never holds two addresses at the same moment, so a
- * planner alone would force every such caller to be rewritten around a batch API.
- *
- * This module collects the addresses on time instead, so a caller keeps its
- * per-parameter accessors and still gets one transaction per span.
- *
- * The read debouncer is deliberately simpler than the write debouncer. There is
- * no supersede rule, because a second request for an address is not a newer
- * value, it is a second reader. There is no cache, because this package records
- * only what it wrote. There is no ceiling on the hold, because the window does
- * not restart: it opens on the first arrival of a batch and expires on time,
- * which a stream of arrivals can never push out.
+ * @fileoverview Collects concurrent register reads and plans them into spans.
+ * The first request starts a fixed collection window; later requests do not restart it.
  *
  * @module
  */
@@ -25,10 +12,9 @@ export interface ReadDebouncerOptions {
     /**
      * How long addresses are collected before the spans are read.
      *
-     * The window opens on the first arrival and does not restart, so it bounds the
-     * latency a reader pays. One transaction is the unit to compare it against:
-     * a window far shorter than a transaction collects nothing, and a window much
-     * longer than one delays every reader for a batch it did not need.
+     * The first arrival starts the window. Later arrivals do not restart it.
+     * Compare the window with measured transaction time when selecting a value.
+     * Device response time adds to the collection delay.
      *
      * A window of zero disables the debouncer: every read is issued on its own,
      * with no timer and no batch.
@@ -52,8 +38,8 @@ export interface ReadDebouncer {
     /**
      * Adds an address to the batch and reads immediately, rather than waiting.
      *
-     * Every reader already collected is answered by the same transaction, so no
-     * reader waits longer because of this call.
+     * The flush includes readers already collected. Its plan can require several
+     * transactions, and their results are delivered to the waiting readers.
      */
     readNow(address: number): Effect.Effect<number, ModbusError>;
     /**
@@ -87,7 +73,7 @@ export interface ReadDebouncer {
  * When the scope closes, readers still waiting are interrupted.
  *
  * @param options - The window, the planner limits, and the callback that reads.
- * @returns The debouncer.
+ * @returns The scoped debouncer. Waiting readers are interrupted when its scope closes.
  *
  * @example
  * const debouncer = yield* createReadDebouncer({

package/dist/src/register-cache.d.ts

@@ -1,11 +1,5 @@
 /**
- * @fileoverview A record of what each device already holds, used to drop writes
- * that would change nothing.
- *
- * A caller that recomputes an output on every cycle proposes the same value most
- * of the time. In steady state roughly four out of five proposals are a repeat of
- * what the register already holds, and on a half-duplex bus each one costs a
- * turnaround that carries no information.
+ * @fileoverview Tracks acknowledged register values to suppress unchanged writes.
  *
  * @module
  */

package/dist/src/register-plan.d.ts

@@ -1,16 +1,6 @@
 /**
- * @fileoverview Pure planners that turn a set of register addresses into the
- * smallest set of Modbus transactions that covers them.
- *
- * A caller that derives each register independently — one fiber per output, one
- * accessor per parameter — naturally produces one transaction per register. On a
- * half-duplex multi-drop bus that is the dominant cost: every transaction is a
- * turnaround, and the registers a caller wants are usually neighbours.
- *
- * These functions hold no state, run no I/O, and return no `Effect`. They are the
- * bottom layer of the batching stack and are usable on their own — a caller that
- * already owns its scheduling can plan the transactions here and issue them with
- * a plain {@link EffectModbusClient}.
+ * @fileoverview Pure functions that plan register reads and writes as Modbus transactions.
+ * They do not perform I/O or return Effects.
  *
  * @module
  */

package/dist/src/retry.d.ts

@@ -1,3 +1,4 @@
+/** Defines opt-in Modbus retry schedules and an Effect retry combinator. */
 import { Duration, Effect, Schedule } from 'effect';
 import type { ModbusError } from './errors';
 /**

package/dist/src/serial-port-path.d.ts

@@ -0,0 +1,21 @@
+import { Effect } from 'effect';
+/** Maximum serial path length in the native 0.16.2 binding. */
+export declare const MAX_SERIAL_PORT_PATH = 128;
+/**
+ * Gives a serial port path that `modbus-rs` accepts.
+ *
+ * Stable device links, such as `/dev/serial/by-id/...`, can be longer than
+ * {@link MAX_SERIAL_PORT_PATH}. Such a link points to a short device path,
+ * so a long path is replaced with its target. This function resolves one
+ * snapshot. Transport services keep a short alias to the configured path for reconnects.
+ *
+ * @param portPath - The configured serial port path.
+ * @returns The configured path, or the target of a long path.
+ * @throws An error with the `MODBUS_INVALID_ARGUMENT` code when the path and
+ *   its target are both too long. The same error occurs when a long link has
+ *   no target, for example while its device is unplugged. Retry policies do
+ *   not retry this error. A later open succeeds after the device returns.
+ */
+export declare const resolveSerialPortPath: (portPath: string) => Promise<string>;
+/** Keeps a short alias in the transport scope. Its target remains the configured stable link. */
+export declare const serialPortPathScoped: (portPath: string) => Effect.Effect<() => Promise<string>, never, import("effect/Scope").Scope>;

package/dist/src/shared-transport.d.ts

@@ -1,3 +1,4 @@
+/** Provides scoped lifecycle, lazy connection, client caching, and optional transport resilience. */
 import { Duration, Effect, Scope, SubscriptionRef } from 'effect';
 import type { AsyncAsciiTransport, AsyncRtuTransport, AsyncTcpTransport } from 'modbus-rs';
 import type { WasmAsciiTransport, WasmRtuTransport, WasmWsTransport } from 'modbus-rs/web';
@@ -32,7 +33,7 @@ export interface TransportResilienceOptions {
      * host that does not answer waits until the operating system stops it, which
      * takes about 2 minutes on Linux with default settings.
      *
-     * The limit applies to each caller that waits for an open or reconnect.
+     * The limit applies independently to each caller that waits for an open or reconnect.
      * When it expires, that caller fails with {@link ModbusTimeoutError}.
      *
      * The native connect cannot be cancelled, so it continues. Later callers wait
@@ -103,6 +104,7 @@ export interface TransportServiceApi {
      *
      * @param unitId - Modbus unit ID to address.
      * @param options - Per-client policy replacing the transport default.
+     * @returns An Effect that succeeds with the client or fails with a Modbus error.
      */
     withClient(unitId: number, options?: {
         readonly retry?: ModbusRetryPolicy;
@@ -119,9 +121,17 @@ export interface TransportServiceApi {
      * ```
      */
     readonly connectionState: SubscriptionRef.SubscriptionRef<ConnectionState>;
-    /** Sets a request timeout (ms) on the underlying transport. Fails if not connected. */
+    /**
+     * Sets native response and admission limits in milliseconds.
+     * @param timeoutMs - Request timeout in milliseconds.
+     * @returns An Effect that completes after the timeout is set, or fails if the transport is not connected.
+     */
     setRequestTimeout(timeoutMs: number): Effect.Effect<void, ModbusError>;
-    /** Clears the request timeout. Fails if not connected. */
+    /**
+     * Clears native response and admission limits. Fails if not connected.
+     * Interruption of an unbounded serial call closes its handle. Later operations reopen it lazily.
+     * @returns An Effect that completes after the limits are cleared, or fails if the transport is not connected.
+     */
     clearRequestTimeout(): Effect.Effect<void, ModbusError>;
     /**
      * Reconnects the transport. Opens lazily if no prior connection exists.
@@ -130,10 +140,19 @@ export interface TransportServiceApi {
      * flight join it rather than starting another, and all of them observe its
      * result. Fails with `ModbusNotConnectedError` if the transport was closed
      * while the reconnect was running.
+     * @returns An Effect that completes when the transport is open or reconnected, or fails on connection error.
      */
     reconnect(): Effect.Effect<void, ModbusError>;
-    /** Closes the transport and its scope immediately. */
-    close(): Effect.Effect<void, ModbusError, Scope.Scope>;
+    /**
+     * Closes `scope`, then closes the transport.
+     *
+     * Pass the scope that holds the work to finish first, such as
+     * `onShutdown` writes. The transport closes even if a finalizer fails.
+     *
+     * @param scope - Caller scope to finalize before closing the connection.
+     * @returns An Effect that finalizes the caller scope and attempts transport closure.
+     */
+    close(scope: Scope.Closeable): Effect.Effect<void, ModbusError>;
     /**
      * Declares the {@link BatchingModbusClient} for a unit.
      *
@@ -157,6 +176,7 @@ export interface TransportServiceApi {
      *
      * @param unitId - Modbus unit ID to address.
      * @param options - The cache, the windows, and the planner limits.
+     * @returns An Effect that succeeds with the client or fails with a Modbus or declaration error.
      */
     withBatchingClient(unitId: number, options?: BatchingClientOptions & {
         readonly retry?: ModbusRetryPolicy;
@@ -169,6 +189,7 @@ export interface TransportServiceApi {
      * which fiber ran first.
      *
      * @param unitId - Modbus unit ID to address.
+     * @returns An Effect that succeeds with the declared client, or fails if no declaration exists.
      */
     batchingClient(unitId: number): Effect.Effect<BatchingModbusClient, ModbusError>;
     /**
@@ -202,7 +223,7 @@ type TransportConstructorName = 'AsyncAsciiTransport' | 'AsyncRtuTransport' | 'A
  * lifecycle, client caching, timeouts, and reconnection.
  *
  * The transport is opened lazily on the first `withClient()` call and
- * automatically closed when the consuming {@link Effect.Scope | Scope}
+ * automatically closed when the consuming scope
  * finalizes via `Effect.addFinalizer`.
  *
  * @typeParam TOptions - Transport options (e.g. `RtuTransportOptions`).
@@ -213,11 +234,15 @@ type TransportConstructorName = 'AsyncAsciiTransport' | 'AsyncRtuTransport' | 'A
  *   returning a promise for the opened transport.
  * @param serviceName - Logical name used in log messages and the finalizer guard.
  * @param config - Optional module specifier override for browser WASM transports.
- * @returns An `Effect` that produces a {@link TransportServiceApi}.
+ * @returns A scoped service constructor that produces a {@link TransportServiceApi}.
  */
 export declare function createTransportScoped<TOptions, TClient extends AnyModbusClient, TTransport extends TransportHandle<TClient>>(transportKey: TransportConstructorName, openMethod: (TC: TransportConstructor, options: TOptions) => Promise<TTransport>, serviceName: string, config?: {
     /** Which `modbus-rs` conditional export to import from. Defaults to `"modbus-rs"` (native). */
     moduleSpecifier?: 'modbus-rs' | 'modbus-rs/web';
+    /** Keeps serial calls and reconnects outside an in-flight native call. TCP and WASM do not use it. */
+    serializeRequests?: boolean;
+    /** Reads the initial serial response limit. Native 0.16.2 defaults to 1000 ms. */
+    responseTimeoutMs?: (options: TOptions) => number | undefined;
 }): (options: TOptions & TransportResilienceOptions) => Effect.Effect<{
     connectionState: SubscriptionRef.SubscriptionRef<{
         readonly _tag: "Connected";
@@ -236,7 +261,7 @@ export declare function createTransportScoped<TOptions, TClient extends AnyModbu
     setRequestTimeout: (timeoutMs: number) => Effect.Effect<undefined, ModbusNotConnectedError, never>;
     clearRequestTimeout: () => Effect.Effect<undefined, ModbusNotConnectedError, never>;
     reconnect: () => Effect.Effect<undefined, ModbusError, never>;
-    close: () => Effect.Effect<void, ModbusError, Scope.Scope>;
+    close: (scope: Scope.Closeable) => Effect.Effect<void, ModbusError, never>;
     withBatchingClient: (unitId: number, options?: BatchingClientOptions & {
         readonly retry?: ModbusRetryPolicy;
     }) => Effect.Effect<BatchingModbusClient, ModbusError | ModbusUnitAlreadyDeclaredError>;

package/dist/src/span-attributes.d.ts

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Caller-supplied span attributes, and the rule for merging them.
+ * @fileoverview Defines caller span attributes and merges values from batched callers.
  *
  * @module
  */