@flux-control/effect-modbus-rs 0.2.0 → 0.3.0

package/dist/src/AsciiTransportService.d.ts

@@ -1,9 +1,30 @@
 import { Effect, Layer } from 'effect';
 import type { AsciiTransportOptions } from 'modbus-rs';
 import { SlaveDeviceDefinitions } from './mocks';
+import type { MockFaultOptions } from './mocks';
+import type { TransportResilienceOptions, WithoutUpstreamRetry } from './shared-transport';
+/**
+ * {@link AsciiTransportOptions} minus the upstream retry knobs.
+ *
+ * @see WithoutUpstreamRetry — Why they are withheld.
+ */
+export type AsciiTransportOpenOptions = WithoutUpstreamRetry<AsciiTransportOptions>;
 declare const AsciiTransportService_base: Effect.Service.Class<AsciiTransportService, "AsciiTransportService", {
-    readonly scoped: (options: AsciiTransportOptions) => Effect.Effect<{
-        withClient: (unitId: number) => Effect.Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
+    readonly scoped: (options: AsciiTransportOpenOptions & TransportResilienceOptions) => Effect.Effect<{
+        connectionState: import("effect/SubscriptionRef").SubscriptionRef<{
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: import("./errors").ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }>;
+        withClient: (unitId: number, clientOptions?: {
+            readonly retry?: import("./retry").ModbusRetryPolicy;
+        } | undefined) => Effect.Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
         setRequestTimeout: (timeoutMs: number) => Effect.Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
         clearRequestTimeout: () => Effect.Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
         reconnect: () => Effect.Effect<undefined, import("./errors").ModbusError, never>;
@@ -24,7 +45,7 @@ declare const AsciiTransportService_base: Effect.Service.Class<AsciiTransportSer
  * requests for the same unit ID reuse the same client.
  *
  * @see AsyncAsciiTransport — Upstream `modbus-rs` ASCII transport.
- * @see AsciiTransportOptions — Configuration for the ASCII serial port.
+ * @see AsciiTransportOpenOptions — Configuration for the ASCII serial port.
  * @see makeTransportScoped — Generic lifecycle logic from shared-transport.
  */
 export declare class AsciiTransportService extends AsciiTransportService_base {
@@ -36,11 +57,11 @@ export declare class AsciiTransportService extends AsciiTransportService_base {
      * simulated Modbus slaves and their register/coil maps.
      *
      * @param devices - Slave device definitions for the mock.
-     * @returns A function that takes {@link AsciiTransportOptions} and
+     * @returns A function that takes {@link AsciiTransportOpenOptions} and
      *          returns a scoped {@link Layer} providing the mock service.
      *
      * @see makeMockTransport — The underlying mock factory.
      */
-    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: AsciiTransportOptions) => Layer.Layer<AsciiTransportService, never, never>;
+    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: AsciiTransportOpenOptions & TransportResilienceOptions & MockFaultOptions) => Layer.Layer<AsciiTransportService, never, never>;
 }
 export {};

package/dist/src/RtuTransportService.d.ts

@@ -1,9 +1,30 @@
 import { Effect, Layer } from 'effect';
 import type { RtuTransportOptions } from 'modbus-rs';
+import type { MockFaultOptions } from './mocks';
 import type { SlaveDeviceDefinitions } from './mocks';
+import type { TransportResilienceOptions, WithoutUpstreamRetry } from './shared-transport';
+/**
+ * {@link RtuTransportOptions} minus the upstream retry knobs.
+ *
+ * @see WithoutUpstreamRetry — Why they are withheld.
+ */
+export type RtuTransportOpenOptions = WithoutUpstreamRetry<RtuTransportOptions>;
 declare const RtuTransportService_base: Effect.Service.Class<RtuTransportService, "RtuTransportService", {
-    readonly scoped: (options: RtuTransportOptions) => Effect.Effect<{
-        withClient: (unitId: number) => Effect.Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
+    readonly scoped: (options: RtuTransportOpenOptions & TransportResilienceOptions) => Effect.Effect<{
+        connectionState: import("effect/SubscriptionRef").SubscriptionRef<{
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: import("./errors").ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }>;
+        withClient: (unitId: number, clientOptions?: {
+            readonly retry?: import("./retry").ModbusRetryPolicy;
+        } | undefined) => Effect.Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
         setRequestTimeout: (timeoutMs: number) => Effect.Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
         clearRequestTimeout: () => Effect.Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
         reconnect: () => Effect.Effect<undefined, import("./errors").ModbusError, never>;
@@ -24,7 +45,7 @@ declare const RtuTransportService_base: Effect.Service.Class<RtuTransportService
  * requests for the same unit ID reuse the same client.
  *
  * @see AsyncRtuTransport — Upstream `modbus-rs` RTU transport.
- * @see RtuTransportOptions — Configuration for the RTU serial port.
+ * @see RtuTransportOpenOptions — Configuration for the RTU serial port.
  * @see makeTransportScoped — Generic lifecycle logic from shared-transport.
  */
 export declare class RtuTransportService extends RtuTransportService_base {
@@ -36,11 +57,11 @@ export declare class RtuTransportService extends RtuTransportService_base {
      * simulated Modbus slaves and their register/coil maps.
      *
      * @param devices - Slave device definitions for the mock.
-     * @returns A function that takes {@link RtuTransportOptions} and
+     * @returns A function that takes {@link RtuTransportOpenOptions} and
      *          returns a scoped {@link Layer} providing the mock service.
      *
      * @see makeMockTransport — The underlying mock factory.
      */
-    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: RtuTransportOptions) => Layer.Layer<RtuTransportService, never, never>;
+    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: RtuTransportOpenOptions & TransportResilienceOptions & MockFaultOptions) => Layer.Layer<RtuTransportService, never, never>;
 }
 export {};

package/dist/src/SerialTransportService.d.ts

@@ -1,7 +1,8 @@
 import { Context, Layer } from 'effect';
-import type { AsciiTransportOptions, RtuTransportOptions } from 'modbus-rs';
+import { type AsciiTransportOpenOptions } from './AsciiTransportService';
 import { type SlaveDeviceDefinitions } from './mocks';
-import type { TransportServiceApi } from './shared-transport';
+import { type RtuTransportOpenOptions } from './RtuTransportService';
+import type { TransportResilienceOptions, TransportServiceApi } from './shared-transport';
 declare const SerialTransportService_base: Context.TagClass<SerialTransportService, "SerialTransportService", TransportServiceApi>;
 /**
  * Abstract serial Modbus transport service tag.
@@ -27,12 +28,12 @@ export declare class SerialTransportService extends SerialTransportService_base
      * Creates a {@link Layer} providing {@link SerialTransportService}
      * backed by an ASCII transport.
      */
-    static fromAscii(options: AsciiTransportOptions): Layer.Layer<SerialTransportService>;
+    static fromAscii(options: AsciiTransportOpenOptions & TransportResilienceOptions): Layer.Layer<SerialTransportService>;
     /**
      * Creates a {@link Layer} providing {@link SerialTransportService}
      * backed by an RTU transport.
      */
-    static fromRtu(options: RtuTransportOptions): Layer.Layer<SerialTransportService>;
+    static fromRtu(options: RtuTransportOpenOptions & TransportResilienceOptions): Layer.Layer<SerialTransportService>;
     /**
      * Creates a mock {@link Layer} providing {@link SerialTransportService}
      * for testing or development.
@@ -40,6 +41,6 @@ export declare class SerialTransportService extends SerialTransportService_base
      * Accepts an array of {@link SlaveDeviceDefinition} describing the
      * simulated Modbus slaves and their register/coil maps.
      */
-    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: AsciiTransportOptions | RtuTransportOptions) => Layer.Layer<SerialTransportService>;
+    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: (AsciiTransportOpenOptions | RtuTransportOpenOptions) & TransportResilienceOptions) => Layer.Layer<SerialTransportService>;
 }
 export {};

package/dist/src/TcpTransportService.d.ts

@@ -1,9 +1,30 @@
 import { Effect, Layer } from 'effect';
 import type { TcpTransportOptions } from 'modbus-rs';
 import { SlaveDeviceDefinitions } from './mocks';
+import type { MockFaultOptions } from './mocks';
+import type { TransportResilienceOptions, WithoutUpstreamRetry } from './shared-transport';
+/**
+ * {@link TcpTransportOptions} minus the upstream retry knobs.
+ *
+ * @see WithoutUpstreamRetry — Why they are withheld.
+ */
+export type TcpTransportOpenOptions = WithoutUpstreamRetry<TcpTransportOptions>;
 declare const TcpTransportService_base: Effect.Service.Class<TcpTransportService, "TcpTransportService", {
-    readonly scoped: (options: TcpTransportOptions) => Effect.Effect<{
-        withClient: (unitId: number) => Effect.Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
+    readonly scoped: (options: TcpTransportOpenOptions & TransportResilienceOptions) => Effect.Effect<{
+        connectionState: import("effect/SubscriptionRef").SubscriptionRef<{
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: import("./errors").ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }>;
+        withClient: (unitId: number, clientOptions?: {
+            readonly retry?: import("./retry").ModbusRetryPolicy;
+        } | undefined) => Effect.Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
         setRequestTimeout: (timeoutMs: number) => Effect.Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
         clearRequestTimeout: () => Effect.Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
         reconnect: () => Effect.Effect<undefined, import("./errors").ModbusError, never>;
@@ -24,7 +45,7 @@ declare const TcpTransportService_base: Effect.Service.Class<TcpTransportService
  * requests for the same unit ID reuse the same client.
  *
  * @see AsyncTcpTransport — Upstream `modbus-rs` TCP transport.
- * @see TcpTransportOptions — Configuration for the TCP connection.
+ * @see TcpTransportOpenOptions — Configuration for the TCP connection.
  * @see makeTransportScoped — Generic lifecycle logic from shared-transport.
  */
 export declare class TcpTransportService extends TcpTransportService_base {
@@ -36,11 +57,11 @@ export declare class TcpTransportService extends TcpTransportService_base {
      * simulated Modbus slaves and their register/coil maps.
      *
      * @param devices - Slave device definitions for the mock.
-     * @returns A function that takes {@link TcpTransportOptions} and
+     * @returns A function that takes {@link TcpTransportOpenOptions} and
      *          returns a scoped {@link Layer} providing the mock service.
      *
      * @see makeMockTransport — The underlying mock factory.
      */
-    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: TcpTransportOptions) => Layer.Layer<TcpTransportService, never, never>;
+    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: TcpTransportOpenOptions & TransportResilienceOptions & MockFaultOptions) => Layer.Layer<TcpTransportService, never, never>;
 }
 export {};

package/dist/src/WasmAsciiTransportService.d.ts

@@ -1,6 +1,8 @@
 import { Effect, Layer } from 'effect';
 import type { WasmSerialPortHandle, WasmSerialTransportOptions } from 'modbus-rs/web';
 import { SlaveDeviceDefinitions } from './mocks';
+import type { MockFaultOptions } from './mocks';
+import type { TransportResilienceOptions } from './shared-transport';
 /**
  * Options for {@link WasmAsciiTransportService}. `WasmAsciiTransport.open()` takes the
  * serial port handle and the connection options as two separate arguments; this
@@ -13,8 +15,23 @@ export type WasmAsciiTransportOpenOptions = WasmSerialTransportOptions & {
     port: WasmSerialPortHandle;
 };
 declare const WasmAsciiTransportService_base: Effect.Service.Class<WasmAsciiTransportService, "WasmAsciiTransportService", {
-    readonly scoped: (options: WasmAsciiTransportOpenOptions) => Effect.Effect<{
-        withClient: (unitId: number) => Effect.Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
+    readonly scoped: (options: WasmSerialTransportOptions & {
+        port: WasmSerialPortHandle;
+    } & TransportResilienceOptions) => Effect.Effect<{
+        connectionState: import("effect/SubscriptionRef").SubscriptionRef<{
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: import("./errors").ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }>;
+        withClient: (unitId: number, clientOptions?: {
+            readonly retry?: import("./retry").ModbusRetryPolicy;
+        } | undefined) => Effect.Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
         setRequestTimeout: (timeoutMs: number) => Effect.Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
         clearRequestTimeout: () => Effect.Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
         reconnect: () => Effect.Effect<undefined, import("./errors").ModbusError, never>;
@@ -51,6 +68,6 @@ export declare class WasmAsciiTransportService extends WasmAsciiTransportService
      *
      * @see makeMockTransport — The underlying mock factory.
      */
-    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: WasmAsciiTransportOpenOptions) => Layer.Layer<WasmAsciiTransportService, never, never>;
+    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: WasmAsciiTransportOpenOptions & TransportResilienceOptions & MockFaultOptions) => Layer.Layer<WasmAsciiTransportService, never, never>;
 }
 export {};

package/dist/src/WasmRtuTransportService.d.ts

@@ -1,6 +1,8 @@
 import { Effect, Layer } from 'effect';
 import type { WasmSerialPortHandle, WasmSerialTransportOptions } from 'modbus-rs/web';
 import { SlaveDeviceDefinitions } from './mocks';
+import type { MockFaultOptions } from './mocks';
+import type { TransportResilienceOptions } from './shared-transport';
 /**
  * Options for {@link WasmRtuTransportService}. `WasmRtuTransport.open()` takes the
  * serial port handle and the connection options as two separate arguments; this
@@ -13,8 +15,23 @@ export type WasmRtuTransportOpenOptions = WasmSerialTransportOptions & {
     port: WasmSerialPortHandle;
 };
 declare const WasmRtuTransportService_base: Effect.Service.Class<WasmRtuTransportService, "WasmRtuTransportService", {
-    readonly scoped: (options: WasmRtuTransportOpenOptions) => Effect.Effect<{
-        withClient: (unitId: number) => Effect.Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
+    readonly scoped: (options: WasmSerialTransportOptions & {
+        port: WasmSerialPortHandle;
+    } & TransportResilienceOptions) => Effect.Effect<{
+        connectionState: import("effect/SubscriptionRef").SubscriptionRef<{
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: import("./errors").ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }>;
+        withClient: (unitId: number, clientOptions?: {
+            readonly retry?: import("./retry").ModbusRetryPolicy;
+        } | undefined) => Effect.Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
         setRequestTimeout: (timeoutMs: number) => Effect.Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
         clearRequestTimeout: () => Effect.Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
         reconnect: () => Effect.Effect<undefined, import("./errors").ModbusError, never>;
@@ -51,6 +68,6 @@ export declare class WasmRtuTransportService extends WasmRtuTransportService_bas
      *
      * @see makeMockTransport — The underlying mock factory.
      */
-    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: WasmRtuTransportOpenOptions) => Layer.Layer<WasmRtuTransportService, never, never>;
+    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: WasmRtuTransportOpenOptions & TransportResilienceOptions & MockFaultOptions) => Layer.Layer<WasmRtuTransportService, never, never>;
 }
 export {};

package/dist/src/WasmWsTransportService.d.ts

@@ -1,9 +1,24 @@
 import { Effect, Layer } from 'effect';
 import type { WasmWsTransportOptions } from 'modbus-rs/web';
 import { SlaveDeviceDefinitions } from './mocks';
+import type { MockFaultOptions } from './mocks';
+import type { TransportResilienceOptions } from './shared-transport';
 declare const WasmWsTransportService_base: Effect.Service.Class<WasmWsTransportService, "WasmWsTransportService", {
-    readonly scoped: (options: WasmWsTransportOptions) => Effect.Effect<{
-        withClient: (unitId: number) => Effect.Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
+    readonly scoped: (options: WasmWsTransportOptions & TransportResilienceOptions) => Effect.Effect<{
+        connectionState: import("effect/SubscriptionRef").SubscriptionRef<{
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: import("./errors").ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }>;
+        withClient: (unitId: number, clientOptions?: {
+            readonly retry?: import("./retry").ModbusRetryPolicy;
+        } | undefined) => Effect.Effect<import("./modbus-client").EffectModbusClient, import("./errors").ModbusError, never>;
         setRequestTimeout: (timeoutMs: number) => Effect.Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
         clearRequestTimeout: () => Effect.Effect<undefined, import("./errors").ModbusNotConnectedError, never>;
         reconnect: () => Effect.Effect<undefined, import("./errors").ModbusError, never>;
@@ -40,6 +55,6 @@ export declare class WasmWsTransportService extends WasmWsTransportService_base
      *
      * @see makeMockTransport — The underlying mock factory.
      */
-    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: WasmWsTransportOptions) => Layer.Layer<WasmWsTransportService, never, never>;
+    static makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: WasmWsTransportOptions & TransportResilienceOptions & MockFaultOptions) => Layer.Layer<WasmWsTransportService, never, never>;
 }
 export {};

package/dist/src/connection.d.ts

@@ -0,0 +1,170 @@
+import { Data, Duration, Effect, SubscriptionRef } from 'effect';
+import { ModbusCircuitOpenError, type ModbusError } from './errors';
+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
+ * status without inferring it from failed reads.
+ *
+ * - `Disconnected` — never opened, or closed. Operations open it lazily.
+ * - `Connected` — usable.
+ * - `Reconnecting` — the supervisor is re-establishing the link. Operations are
+ *   refused with {@link ModbusCircuitOpenError} rather than queued on a dead bus.
+ * - `Down` — reconnect attempts were exhausted; the supervisor is waiting out
+ *   `resetAfter` before probing again. Operations are refused.
+ */
+export type ConnectionState = Data.TaggedEnum<{
+    Disconnected: object;
+    Connected: object;
+    Reconnecting: {
+        readonly attempt: number;
+    };
+    Down: {
+        readonly cause: ModbusError;
+    };
+}>;
+/** Constructors and matchers for {@link ConnectionState}. */
+export declare const ConnectionState: {
+    readonly $is: <Tag extends "Connected" | "Disconnected" | "Down" | "Reconnecting">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "Connected";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Disconnected";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Down";
+        readonly cause: ModbusError;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Reconnecting";
+        readonly attempt: number;
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <const Cases extends { readonly [Tag in "Connected" | "Disconnected" | "Down" | "Reconnecting"]: (args: Extract<{
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(cases: Cases & { [K in Exclude<keyof Cases, "Connected" | "Disconnected" | "Down" | "Reconnecting">]: never; }): (value: {
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }) => import("effect/Unify").Unify<ReturnType<Cases["Connected" | "Disconnected" | "Down" | "Reconnecting"]>>;
+        <const Cases extends { readonly [Tag in "Connected" | "Disconnected" | "Down" | "Reconnecting"]: (args: Extract<{
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(value: {
+            readonly _tag: "Connected";
+        } | {
+            readonly _tag: "Disconnected";
+        } | {
+            readonly _tag: "Down";
+            readonly cause: ModbusError;
+        } | {
+            readonly _tag: "Reconnecting";
+            readonly attempt: number;
+        }, cases: Cases & { [K in Exclude<keyof Cases, "Connected" | "Disconnected" | "Down" | "Reconnecting">]: never; }): import("effect/Unify").Unify<ReturnType<Cases["Connected" | "Disconnected" | "Down" | "Reconnecting"]>>;
+    };
+    readonly Connected: Data.Case.Constructor<{
+        readonly _tag: "Connected";
+    }, "_tag">;
+    readonly Disconnected: Data.Case.Constructor<{
+        readonly _tag: "Disconnected";
+    }, "_tag">;
+    readonly Down: Data.Case.Constructor<{
+        readonly _tag: "Down";
+        readonly cause: ModbusError;
+    }, "_tag">;
+    readonly Reconnecting: Data.Case.Constructor<{
+        readonly _tag: "Reconnecting";
+        readonly attempt: number;
+    }, "_tag">;
+};
+/**
+ * Transport-level reconnection and circuit-breaking configuration.
+ *
+ * Supplying this on a transport hands reconnection to a supervisor fiber owned
+ * by that transport: one reconnect for the whole application rather than one
+ * per failing call site. Omit it and the transport keeps its manual behaviour —
+ * `reconnect()` still works, nothing happens on its own.
+ */
+export interface ReconnectOptions {
+    /**
+     * How reconnect attempts are spaced. Defaults to 5 attempts, `250 millis`
+     * base, factor 2, `10 seconds` ceiling, jittered.
+     */
+    readonly policy?: ModbusRetryPolicy;
+    /**
+     * How long the circuit stays open after attempts are exhausted, before the
+     * supervisor probes again. Default `30 seconds`.
+     */
+    readonly resetAfter?: Duration.DurationInput;
+    /**
+     * Which operation failures hand control to the supervisor.
+     * Default `["ModbusConnectionClosedError", "ModbusTransportError"]`.
+     */
+    readonly triggerOn?: ReadonlyArray<ModbusErrorTag>;
+}
+/** {@link ReconnectOptions} with defaults applied. */
+export interface ResolvedReconnect {
+    readonly policy: ModbusRetryPolicy;
+    readonly resetAfter: Duration.Duration;
+    readonly triggers: (error: ModbusError) => boolean;
+}
+/** Applies defaults to {@link ReconnectOptions}. */
+export declare const resolveReconnect: (options: ReconnectOptions) => ResolvedReconnect;
+/**
+ * Refuses an operation while the link is being re-established.
+ *
+ * `Disconnected` is allowed through so the first call still opens the
+ * transport lazily; only `Reconnecting` and `Down` are refused.
+ *
+ * @param state - The transport's connection state.
+ * @returns An Effect failing with {@link ModbusCircuitOpenError} when the
+ *   circuit is open, and succeeding otherwise.
+ */
+export declare const guardCircuit: (state: SubscriptionRef.SubscriptionRef<ConnectionState>) => Effect.Effect<void, ModbusCircuitOpenError>;
+/**
+ * The supervisor loop: re-establishes the link, then keeps probing for as long
+ * as the transport lives.
+ *
+ * Each round runs `reconnect` under the configured policy. Success publishes
+ * `Connected` and ends the loop; exhausting the policy publishes `Down` and
+ * waits out `resetAfter` before the next round, so an unplugged device is
+ * retried at a steady cadence instead of being hammered or given up on.
+ *
+ * @param reconnect - The transport's own reconnect operation.
+ * @param state - The state cell to publish transitions to.
+ * @param resolved - Reconnect configuration with defaults applied.
+ * @returns An Effect that runs until the link is restored.
+ */
+export declare const superviseReconnect: (reconnect: Effect.Effect<void, ModbusError>, state: SubscriptionRef.SubscriptionRef<ConnectionState>, resolved: ResolvedReconnect) => Effect.Effect<void>;

package/dist/src/errors.d.ts

@@ -135,6 +135,30 @@ export declare class ModbusNotConnectedError extends ModbusNotConnectedError_bas
     readonly message: string;
 }> {
 }
+declare const ModbusCircuitOpenError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ModbusCircuitOpenError";
+} & Readonly<A>;
+/**
+ * Error indicating the transport's circuit breaker is open: the device is
+ * unreachable and the transport is reconnecting (or waiting to probe again),
+ * 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.
+ *
+ * Retryable by default: a policy with enough budget rides out the outage
+ * cheaply, since each refused attempt costs nothing on the bus.
+ *
+ * @see ConnectionState — The transport state that produces this error.
+ */
+export declare class ModbusCircuitOpenError extends ModbusCircuitOpenError_base<{
+    /** The failure that opened the circuit, or a descriptive error. */
+    readonly cause: Error;
+    /** Human-readable explanation of the error. */
+    readonly message: string;
+}> {
+}
 /**
  * Union of all typed Modbus errors emitted by this library.
  *
@@ -152,7 +176,7 @@ export declare class ModbusNotConnectedError extends ModbusNotConnectedError_bas
  *
  * @see ModbusErrorCode — The upstream error code enum driving this mapping.
  */
-export type ModbusError = ModbusExceptionError | ModbusTimeoutError | ModbusTransportError | ModbusInvalidArgumentError | ModbusConnectionClosedError | ModbusNotConnectedError | ModbusInternalError;
+export type ModbusError = ModbusExceptionError | ModbusTimeoutError | ModbusTransportError | ModbusInvalidArgumentError | ModbusConnectionClosedError | ModbusNotConnectedError | ModbusCircuitOpenError | ModbusInternalError;
 /**
  * Converts a raw `Error` from `modbus-rs` into a typed {@link ModbusError}.
  *

package/dist/src/mocks.d.ts

@@ -1,8 +1,34 @@
-import { Effect, Schema } from 'effect';
+import { Effect, Schema, SubscriptionRef } from 'effect';
 import { type AsciiTransportOptions, type RtuTransportOptions, type TcpTransportOptions } from 'modbus-rs';
 import type { WasmWsTransportOptions, WasmSerialTransportOptions } from 'modbus-rs/web';
 import { ModbusInvalidArgumentError, type ModbusError } from './errors';
-import type { EffectModbusClient } from './modbus-client';
+import type { ModbusRetryPolicy } from './retry';
+import type { TransportResilienceOptions, WithoutUpstreamRetry } from './shared-transport';
+/**
+ * Mock-only fault injection.
+ *
+ * Lets a test or example drive retry policies, backoff, and circuit-breaker
+ * behaviour end to end without hardware: the hook runs before each operation
+ * *attempt*, so returning an error is indistinguishable from a device that
+ * refused that attempt.
+ */
+export interface MockFaultOptions {
+    /**
+     * Called before every operation attempt. Return an error to fail that
+     * attempt, or `undefined` to let it through.
+     *
+     * ```ts
+     * let remaining = 2;
+     * const fault = () => (remaining-- > 0 ? new ModbusTimeoutError({ ... }) : undefined);
+     * ```
+     */
+    readonly fault?: () => ModbusError | undefined;
+    /**
+     * Called before every mock reconnect attempt. Return an error to keep the
+     * link down, or `undefined` to let the reconnect succeed.
+     */
+    readonly reconnectFault?: () => ModbusError | undefined;
+}
 /**
  * Schema for a single coil (digital output) definition.
  *
@@ -115,8 +141,8 @@ export type SlaveDeviceDefinitions = Schema.Schema.Type<typeof SlaveDeviceDefini
  * Accepts an array of {@link SlaveDeviceDefinition} that describe the
  * simulated Modbus slaves, their register maps, and coil states.
  * The returned factory matches the signature expected by the transport
- * service constructors (`RtuTransportOptions | AsciiTransportOptions |
- * TcpTransportOptions`) so it can be injected into any service layer.
+ * service constructors (`RtuTransportOpenOptions | AsciiTransportOpenOptions |
+ * TcpTransportOpenOptions`) so it can be injected into any service layer.
  *
  * Unsupported function codes (FIFO queue, file records) return
  * {@link ModbusInvalidArgumentError}.
@@ -125,11 +151,24 @@ export type SlaveDeviceDefinitions = Schema.Schema.Type<typeof SlaveDeviceDefini
  * @returns A transport factory function that returns a scoped Effect
  *          providing the mock transport.
  */
-export declare const makeMockTransport: (devices: SlaveDeviceDefinitions) => (_options: RtuTransportOptions | AsciiTransportOptions | TcpTransportOptions | WasmWsTransportOptions | WasmSerialTransportOptions) => Effect.Effect<{
-    withClient: (unitId: number) => Effect.Effect<EffectModbusClient, ModbusInvalidArgumentError, never>;
+export declare const makeMockTransport: (devices: SlaveDeviceDefinitions) => (options: (WithoutUpstreamRetry<RtuTransportOptions> | WithoutUpstreamRetry<AsciiTransportOptions> | WithoutUpstreamRetry<TcpTransportOptions> | WasmWsTransportOptions | WasmSerialTransportOptions) & TransportResilienceOptions & MockFaultOptions) => Effect.Effect<{
+    connectionState: SubscriptionRef.SubscriptionRef<{
+        readonly _tag: "Connected";
+    } | {
+        readonly _tag: "Disconnected";
+    } | {
+        readonly _tag: "Down";
+        readonly cause: ModbusError;
+    } | {
+        readonly _tag: "Reconnecting";
+        readonly attempt: number;
+    }>;
+    withClient: (unitId: number, clientOptions?: {
+        readonly retry?: ModbusRetryPolicy;
+    } | undefined) => Effect.Effect<import("./modbus-client").EffectModbusClient, ModbusInvalidArgumentError, never>;
     setRequestTimeout: (_timeoutMs: number) => Effect.Effect<void, never, never>;
     clearRequestTimeout: () => Effect.Effect<void, never, never>;
     reconnect: () => Effect.Effect<void, ModbusError, never>;
     close: () => Effect.Effect<void, ModbusError, never>;
     hasPendingRequests: () => false;
-}, never, never>;
+}, never, import("effect/Scope").Scope>;