using System.Buffers.Binary;
using System.Collections.Concurrent;
using System.Text.Json;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.OtOpcUa.Commons.Observability;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;

namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus;

/// <summary>
///     Modbus TCP implementation of <see cref="IDriver"/> + <see cref="ITagDiscovery"/> +
///     <see cref="IReadable"/> + <see cref="IWritable"/>. First native-protocol greenfield
///     driver for the v2 stack — validates the driver-agnostic <c>IAddressSpaceBuilder</c> +
///     <c>IReadable</c>/<c>IWritable</c> abstractions generalize beyond Galaxy.
/// </summary>
/// <remarks>
///     Scope limits: Historian + alarm capabilities are out of scope (the protocol doesn't
///     express them). Subscriptions overlay a polling loop via the shared
///     <see cref="PollGroupEngine"/> since Modbus has no native push model.
/// </remarks>
public sealed class ModbusDriver
    : IDriver, ITagDiscovery, IReadable, IWritable, IBatchSubscribable, IHostConnectivityProbe, IPerCallHostResolver, ISkippedTagReporter, IDisposable, IAsyncDisposable
{
    /// <summary>Authored tags this driver could not build into its poll table.</summary>
    private readonly SkippedTagLedger _skippedTags = new();

    /// <inheritdoc />
    public SkippedTagReport? GetSkippedTags() => _skippedTags.Snapshot();

    // ---- instance fields (grouped at top for auditability) ----

    /// <summary>Mutable so <see cref="InitializeAsync"/> can adopt a re-parsed config on reinitialize.
    /// Only ever written on the init path, before any reader/transport uses it.</summary>
    private ModbusDriverOptions _options;
    private readonly Func<ModbusDriverOptions, IModbusTransport> _transportFactory;
    private readonly string _driverInstanceId;
    private readonly ILogger<ModbusDriver> _logger;

    // Polled subscriptions delegate to the shared PollGroupEngine. The driver only supplies
    // the reader + on-change bridge; the engine owns the loop, interval floor, and lifecycle.
    private readonly PollGroupEngine _poll;

    // v3 authored-tag table, keyed by RawPath (the tag identity + driver wire reference). RawPath is
    // case-sensitive ordinal. Built in InitializeAsync from _options.RawTags via the pure mapper.
    // BUILD-AND-SWAP: a fresh dictionary is built off to the side and published by reference
    // (Volatile.Write, under _stateLock with the generation check); it is never mutated or .Clear()ed
    // in place, because retained poll loops read it concurrently across a re-initialize.
    private Dictionary<string, ModbusTagDefinition> _tagsByRawPath = new(StringComparer.Ordinal);

    /// <summary>
    ///     Lifecycle generation. Every InitializeAsync / ShutdownAsync bumps it under
    ///     <see cref="_stateLock"/>; every health write and every table/transport publish carries the
    ///     generation it was computed under and is DROPPED once the generation has moved on — so a
    ///     superseded (abandoned) initialize can never publish over a newer one, a read that straddled a
    ///     re-initialize cannot write health about the new transport, and a shutdown's final health
    ///     write cannot clobber a newer init.
    /// </summary>
    private int _generation;

    /// <summary>Guards <see cref="_generation"/>, the transport/table publish and the health fields.</summary>
    private readonly object _stateLock = new();

    // ONE comms-fault slot for reads AND writes: a fault is a property of the shared transport, so the
    // latest batch of either kind decides — a good read clears a Degraded a write's timeout raised and vice
    // versa (two independent sides latched a single write blip as Degraded forever in a read-mostly plant).
    // LastSuccessfulRead advances on any evidence the device answered — a good read, a good write, a
    // refusal, or a probe answer.
    private string? _commsFault;

    // Once-per-tag Warning for deterministic device refusals (exception 01/02/03, undecodable data).
    // Replaced (never cleared in place) on every table publish.
    private ConcurrentDictionary<string, byte> _refusalWarned = new(StringComparer.Ordinal);

    // Resolves a read/write/subscribe RawPath reference to its tag definition via a single hit on the
    // authored _tagsByRawPath table (v3: the reference is always a RawPath; a miss is a miss).
    private readonly EquipmentTagRefResolver<ModbusTagDefinition> _resolver;

    // Last-published (value, status) per tag, keyed by FullReference. Used by ShouldPublish to apply
    // the deadband filter. The value is stored as object so all numeric types share one map; the
    // comparison does a typed cast inside. The status is part of the baseline — see ShouldPublish.
    private readonly ConcurrentDictionary<string, (object Value, uint Status)> _lastPublishedByRef = new(StringComparer.OrdinalIgnoreCase);

    // Per-cycle buffer of the items this driver actually PUBLISHED (i.e. that passed ShouldPublish),
    // keyed by subscription handle. The poll engine collects its own batch list unconditionally — it
    // has no knowledge of the deadband filter — so the batch event is raised from this buffer instead,
    // using the engine's onBatch purely as the end-of-cycle signal.
    //
    // No lock is needed on the per-handle List: the engine runs one loop task per subscription, so for
    // ONE handle all of a cycle's onChange calls and that cycle's single onBatch run sequentially on
    // that subscription's own task. Different subscriptions run concurrently — hence the per-handle
    // ConcurrentDictionary.
    private readonly ConcurrentDictionary<ISubscriptionHandle, List<DataChangeItem>> _cycleBatchItems = new();

    // Last-written value per tag for the WriteOnChangeOnly suppression. Invalidated by reads
    // that return a different value (so an HMI-side change doesn't get masked).
    private readonly Dictionary<string, object?> _lastWrittenByRef = new(StringComparer.OrdinalIgnoreCase);
    private readonly object _lastWrittenLock = new();

    // BitInRegister writes need a read-modify-write against the full holding register. A
    // per-register lock keeps concurrent bit-write callers from stomping on each other.
    private readonly ConcurrentDictionary<ushort, SemaphoreSlim> _rmwLocks = new();

    private readonly Dictionary<(byte Unit, ModbusRegion Region, ushort Start, ushort End), ProhibitionState> _autoProhibited = new();
    private readonly object _autoProhibitedLock = new();

    // Single-host probe state — Modbus driver talks to exactly one endpoint so the "hosts"
    // collection has at most one entry. HostName is the Host:Port string so the Admin UI can
    // display the PLC endpoint uniformly with Galaxy platforms/engines.
    private readonly object _probeLock = new();
    private HostState _hostState = HostState.Unknown;
    private DateTime _hostStateChangedUtc = DateTime.UtcNow;

    private IModbusTransport? _transport;
    private CancellationTokenSource? _probeCts;
    private CancellationTokenSource? _reprobeCts;
    private Task? _probeTask;
    private Task? _reprobeTask;

    /// <summary>Bounded join on the probe / re-probe loops at teardown — they honour their token, so this is a backstop.</summary>
    private static readonly TimeSpan BackgroundLoopJoinTimeout = TimeSpan.FromSeconds(2);

    /// <summary>
    ///     Guards <see cref="InitializeAsync"/> / <see cref="ReinitializeAsync"/> /
    ///     <see cref="ShutdownAsync"/> / <see cref="DisposeAsync"/> against each other. The three
    ///     fields above are published by one lifecycle operation and released by the next, so two
    ///     concurrent operations would dispose each other's freshly-built transport or null
    ///     <c>_transport</c> out from under an in-flight connect. Not hypothetical:
    ///     <c>DriverInstanceActor</c> dispatches initialize on a fire-and-forget <c>Task.Run</c> and
    ///     a reconnect retry tick can start a second attempt while the first is still running. Same shape as
    ///     <c>MqttDriver._lifecycleGate</c>.
    /// </summary>
    private readonly SemaphoreSlim _lifecycleGate = new(1, 1);

    /// <summary>
    ///     Bounded wait the teardown paths take on <see cref="_lifecycleGate"/>. A wedged initialize
    ///     (a connect that never returns) must not turn shutdown or dispose into a hang — past the
    ///     timeout they tear down anyway, which is the lesser evil of the two.
    /// </summary>
    internal TimeSpan LifecycleGateTimeout { get; set; } = TimeSpan.FromSeconds(10);

    private DriverHealth _health = new(DriverState.Unknown, null, null);

    /// <summary>Occurs when a subscribed tag value changes.</summary>
    public event EventHandler<DataChangeEventArgs>? OnDataChange;
    /// <summary>
    ///     Occurs once per poll cycle that produced at least one change, carrying that cycle's
    ///     changed tags. Both data-change events fire by design — this one once per cycle,
    ///     <see cref="OnDataChange"/> once per changed tag — so a consumer subscribes to EXACTLY
    ///     ONE of the two; subscribing both double-delivers.
    /// </summary>
    public event EventHandler<DataChangeBatchEventArgs>? OnDataChangeBatch;
    /// <summary>Occurs when host connectivity status changes.</summary>
    public event EventHandler<HostStatusChangedEventArgs>? OnHostStatusChanged;

    // ---- nested types ----

    /// <summary>
    ///     Per-prohibition state. <c>SplitPending</c> drives the re-probe loop's
    ///     bisection: when true and the range spans &gt; 1 register, the next re-probe
    ///     tries the two halves separately to narrow the actual offending register(s).
    ///     Single-register prohibitions can't be split further; they stay re-probed as-is.
    /// </summary>
    private sealed class ProhibitionState
    {
        public DateTime LastProbedUtc;
        public bool SplitPending;
    }

    // ---- ctor + identity ----

    /// <summary>Initializes a new Modbus TCP driver with the specified options and transport factory.</summary>
    /// <param name="options">Driver configuration options.</param>
    /// <param name="driverInstanceId">Unique identifier for this driver instance.</param>
    /// <param name="transportFactory">Factory to create the Modbus transport; defaults to
    /// <see cref="ModbusTransportFactory.Create"/>, which honours <see cref="ModbusDriverOptions.Transport"/>.</param>
    /// <param name="logger">Logger instance; defaults to null logger if not provided.</param>
    public ModbusDriver(ModbusDriverOptions options, string driverInstanceId,
        Func<ModbusDriverOptions, IModbusTransport>? transportFactory = null,
        ILogger<ModbusDriver>? logger = null)
    {
        ArgumentNullException.ThrowIfNull(options);
        _options = options;
        _driverInstanceId = driverInstanceId;
        _logger = logger ?? NullLogger<ModbusDriver>.Instance;
        _resolver = new EquipmentTagRefResolver<ModbusTagDefinition>(
            r => Volatile.Read(ref _tagsByRawPath).TryGetValue(r, out var t) ? t : null);
        _transportFactory = transportFactory
            ?? (o => ModbusTransportFactory.Create(o));
        _poll = new PollGroupEngine(
            reader: ReadAsync,
            onChange: (handle, tagRef, snapshot) =>
            {
                if (!ShouldPublish(tagRef, snapshot)) return;
                // Buffer what we publish so the cycle-end batch carries exactly the same items.
                // The append stays OUTSIDE the catch below on purpose: as far as the batch contract
                // is concerned the item WAS published — only the per-tag subscriber faulted — so it
                // must still appear in this cycle's batch, keeping the two events content-identical.
                _cycleBatchItems.GetOrAdd(handle, _ => new List<DataChangeItem>())
                    .Add(new DataChangeItem(tagRef, snapshot));
                // Defensive, mirroring PollGroupEngine.ReportError: the engine invokes this bridge
                // UNGUARDED, so a throwing external subscriber would unwind PollOnceAsync mid-loop
                // and the cycle would never reach onBatch. Because the buffer above persists across
                // cycles (it is drained only by onBatch), those items would then silently MERGE into
                // a later cycle's batch — cross-cycle contamination unique to this driver. Swallowing
                // is what keeps the cycle running so onBatch drains the buffer on schedule.
                try { OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, tagRef, snapshot)); }
                catch { /* a buggy subscriber must not corrupt the poll cycle */ }
            },
            onError: HandlePollError,
            backoffCap: PollBackoffCap,
            // The engine's own items list is deliberately IGNORED: it is collected pre-deadband
            // (PollGroupEngine has no knowledge of ShouldPublish), so forwarding it would carry
            // changes the per-tag event suppressed — and a consumer that prefers the batch event
            // would see deadband silently stop working. The buffer holds exactly what the per-tag
            // event published, keeping the two events content-identical per the IBatchSubscribable
            // contract. onBatch is used only as the end-of-cycle signal. A cycle whose every change
            // was suppressed leaves the buffer empty and raises nothing.
            onBatch: (handle, _) =>
            {
                if (_cycleBatchItems.TryRemove(handle, out var published) && published.Count > 0)
                    OnDataChangeBatch?.Invoke(this, new DataChangeBatchEventArgs(handle, published));
            },
            // The engine owns no Meter (Core.Abstractions takes no metrics dependency), so this
            // closure IS the production consumer of its overrun signal.
            onOverrun: _ => OtOpcUaTelemetry.PollOverruns.Add(1,
                new KeyValuePair<string, object?>(OtOpcUaTelemetry.PollOverrunDriverTypeTag, DriverTypeNames.Modbus),
                new KeyValuePair<string, object?>(OtOpcUaTelemetry.PollOverrunDriverInstanceTag, driverInstanceId)));
    }

    /// <summary>Upper bound on the poll-loop failure backoff — adopts the S7-proven 30 s cap fleet-wide.</summary>
    private static readonly TimeSpan PollBackoffCap = TimeSpan.FromSeconds(30);

    /// <summary>
    ///     Routes a poll-loop reader failure to the driver health surface: logs it and
    ///     degrades to <see cref="DriverState.Degraded"/> preserving <c>LastSuccessfulRead</c>.
    ///     Never downgrades a <see cref="DriverState.Faulted"/> state (a stronger, config-level signal).
    /// </summary>
    /// <param name="ex">The exception caught by the poll engine.</param>
    internal void HandlePollError(Exception ex)
    {
        _logger.LogWarning(ex, "Modbus poll reader failed. Driver={DriverInstanceId}", _driverInstanceId);
        lock (_stateLock)
        {
            // Lifecycle-owned states are left alone: Faulted is a stronger, config-level signal, and an
            // Initializing/Unknown driver has no transport for a poll to have failed against — the
            // failure is the re-initialize window itself, which the lifecycle reports on its own.
            var current = _health;
            if (current.State is DriverState.Faulted or DriverState.Initializing or DriverState.Unknown) return;
            _commsFault = ex.Message;
            PublishComposedHealthLocked(current.LastSuccessfulRead);
        }
    }

    // ---- health composition ----

    /// <summary>
    ///     Per-batch accounting: did the device answer anything, did a comms fault happen, and which units
    ///     (or the whole endpoint) must the rest of this batch fail fast against.
    /// </summary>
    private sealed class BatchOutcome
    {
        public bool Answered;
        public string? CommsFault;
        public bool EndpointDown;
        private HashSet<byte>? _failedUnits;

        public void FailUnit(byte unit) => (_failedUnits ??= []).Add(unit);

        public bool IsFailedFast(byte unit) => EndpointDown || (_failedUnits?.Contains(unit) ?? false);
    }

    /// <summary>
    ///     Applies one batch's outcome to the driver health, under <see cref="_stateLock"/>, and only when
    ///     <paramref name="generation"/> is still current. A batch that touched no device (every reference
    ///     unknown, every write refused before the wire) changes nothing.
    /// </summary>
    private void ReportOutcome(int generation, BatchOutcome batch, DateTime now)
    {
        if (!batch.Answered && batch.CommsFault is null) return;
        lock (_stateLock)
        {
            if (generation != _generation) return;
            var current = _health;
            if (current.State is DriverState.Faulted or DriverState.Initializing or DriverState.Unknown) return;
            _commsFault = batch.CommsFault;
            PublishComposedHealthLocked(batch.Answered ? now : current.LastSuccessfulRead);
        }
    }

    /// <summary>Writes Healthy/Degraded from the comms-fault slot. Caller holds <see cref="_stateLock"/>.</summary>
    private void PublishComposedHealthLocked(DateTime? lastSuccessfulRead)
    {
        var fault = _commsFault;
        WriteHealth(fault is null
            ? new DriverHealth(DriverState.Healthy, lastSuccessfulRead, null)
            : new DriverHealth(DriverState.Degraded, lastSuccessfulRead, fault));
    }

    /// <summary>
    ///     A probe answer proves the device is reachable: advance <c>LastSuccessfulRead</c> without
    ///     touching either fault side (it says nothing about the tags).
    /// </summary>
    private void NoteDeviceAnswered(int generation)
    {
        lock (_stateLock)
        {
            if (generation != _generation) return;
            var current = _health;
            if (current.State is not (DriverState.Healthy or DriverState.Degraded)) return;
            WriteHealth(current with { LastSuccessfulRead = DateTime.UtcNow });
        }
    }

    /// <summary>Lifecycle health write, dropped when <paramref name="generation"/> has been superseded.</summary>
    private void WriteLifecycleHealth(int generation, DriverHealth health)
    {
        lock (_stateLock)
        {
            if (generation != _generation) return;
            _commsFault = null;
            WriteHealth(health);
        }
    }

    /// <summary>
    ///     Classifies one failed read/write against the health contract and returns the per-tag status:
    ///     <list type="bullet">
    ///         <item>Exception 01/02/03 — a deterministic REFUSAL: the device answered; per-tag Bad, a
    ///         once-per-tag Warning, no Degraded (it used to latch Degraded and, if every tag refused,
    ///         trip the 90 s watchdog against a reachable device).</item>
    ///         <item>Exception 04/05/06 — the device answered but is not serving: Degraded, answered.</item>
    ///         <item>Exception 0A/0B (and unknown codes) — the gateway answered for a target that did not:
    ///         Degraded, not answered; 0B fails the rest of that unit's batch fast.</item>
    ///         <item>Undecodable data — the device answered with a value we cannot represent: per-tag
    ///         <c>BadDecodingError</c>, once-per-tag Warning, no Degraded.</item>
    ///         <item>No socket / throttled reconnect — the endpoint is down: Degraded, the rest of the
    ///         batch fails fast.</item>
    ///         <item>Any other transport failure (timeout, desync, EOF) — Degraded; the rest of that
    ///         unit's batch fails fast instead of serialising N timeouts.</item>
    ///     </list>
    /// </summary>
    private uint ClassifyFailure(Exception ex, byte unit, string tagRef, BatchOutcome batch, bool isWrite)
    {
        switch (ex)
        {
            case ModbusException mex when IsRefusalCode(mex.ExceptionCode):
                batch.Answered = true;
                WarnRefusalOnce(tagRef, isWrite, $"exception 0x{mex.ExceptionCode:X2} (fc 0x{mex.FunctionCode:X2})");
                return MapModbusExceptionToStatus(mex.ExceptionCode);
            case ModbusException mex when mex.ExceptionCode is 0x04 or 0x05 or 0x06:
                batch.Answered = true;
                batch.CommsFault ??= mex.Message;
                return MapModbusExceptionToStatus(mex.ExceptionCode);
            case ModbusException mex:
                batch.CommsFault ??= mex.Message;
                if (mex.ExceptionCode == 0x0B) batch.FailUnit(unit);
                return MapModbusExceptionToStatus(mex.ExceptionCode);
            case ModbusDecodeException dex:
                batch.Answered = true;
                WarnRefusalOnce(tagRef, isWrite, dex.Message);
                return StatusBadDecodingError;
            case ModbusTransportUnavailableException or ObjectDisposedException or System.Net.Sockets.SocketException:
                batch.CommsFault ??= ex.Message;
                batch.EndpointDown = true;
                return StatusBadCommunicationError;
            default:
                batch.CommsFault ??= ex.Message;
                // Fail the unit fast only when nothing came back in time (timeout / desync / socket-level IO):
                // a malformed-but-delivered reply (byte-count mismatch) proves the unit responds, so its
                // siblings are still tried.
                if (ex is IOException or TimeoutException or OperationCanceledException) batch.FailUnit(unit);
                return StatusBadCommunicationError;
        }
    }

    /// <summary>Exception 01 Illegal Function / 02 Illegal Data Address / 03 Illegal Data Value — the device refused the request.</summary>
    internal static bool IsRefusalCode(byte exceptionCode) => exceptionCode is 0x01 or 0x02 or 0x03;

    private void WarnRefusalOnce(string tagRef, bool isWrite, string detail)
    {
        if (!Volatile.Read(ref _refusalWarned).TryAdd((isWrite ? "w:" : "r:") + tagRef, 0)) return;
        _logger.LogWarning(
            "Modbus device refused {Operation} of tag {RawPath}: {Detail}. The tag reads/writes Bad; driver health is unaffected (the device answered). Driver={DriverInstanceId}",
            isWrite ? "a write" : "a read", tagRef, detail, _driverInstanceId);
    }

    // <summary>
    //     Resolve a reference to the per-slave host key (<c>host:port/unitN</c>) that keys its
    //     per-host resilience (bulkhead / circuit breaker). Routes through
    //     <see cref="EquipmentTagRefResolver{TDef}"/> so an equipment-tag reference (raw TagConfig
    //     JSON) keys its OWN authored unit — via the tag's optional <c>unitId</c> or the driver
    //     default — rather than the single-slave fallback. The resolver caches parses, so this adds
    //     no per-call cost after first use.
    // </summary>
    /// <inheritdoc />
    public string ResolveHost(string fullReference)
    {
        if (_resolver.TryResolve(fullReference, out var tag))
            return BuildSlaveHostName(ResolveUnitId(tag));
        // Unknown reference — fall back to driver-instance host (single-slave behaviour).
        return HostName;
    }

    /// <summary>Format a per-slave host string. Multi-slave deployments distinguish breakers by this string.</summary>
    private string BuildSlaveHostName(byte unitId) => $"{_options.Host}:{_options.Port}/unit{unitId}";

    /// <summary>
    ///     Deadband filter for the subscribe path. The baseline is keyed on <b>(value, status)</b>, never
    ///     value alone: a Bad/null publish drops the baseline, and a status change always publishes. A
    ///     device that comes back after a comms drop usually comes back holding the SAME reading, so the
    ///     old value-only comparison (<c>|10 − 10| &lt; deadband</c>) swallowed the Good recovery and left
    ///     the node Bad until the value drifted past the deadband — the #527 trap.
    /// </summary>
    /// <param name="tagRef">The subscribed reference.</param>
    /// <param name="snapshot">The snapshot the poll engine is about to raise.</param>
    /// <returns><see langword="true"/> when the snapshot must be published.</returns>
    internal bool ShouldPublish(string tagRef, DataValueSnapshot snapshot)
    {
        if (!_resolver.TryResolve(tagRef, out var tag) || tag.Deadband is null) return true;
        // Deadband only applies to numeric scalar types — array / Bool / String publishes
        // unconditionally. Easier to special-case skip than to enumerate the supported types.
        if (tag.ArrayCount.HasValue || tag.DataType is ModbusDataType.Bool or ModbusDataType.BitInRegister or ModbusDataType.String)
            return true;

        if (snapshot.Value is null || StatusCodeIsBad(snapshot.StatusCode))
        {
            // A Bad publish always passes AND drops the baseline, so the next Good sample is
            // compared against nothing and publishes — whatever value it carries.
            _lastPublishedByRef.TryRemove(tagRef, out _);
            return true;
        }

        if (!_lastPublishedByRef.TryGetValue(tagRef, out var prev) || prev.Status != snapshot.StatusCode)
        {
            // First sample, or a quality transition (Good ↔ Uncertain): passes unconditionally and
            // (re)seeds the comparison. The threshold cannot be evaluated across a status change.
            _lastPublishedByRef[tagRef] = (snapshot.Value, snapshot.StatusCode);
            return true;
        }

        var newD = Convert.ToDouble(snapshot.Value);
        var oldD = Convert.ToDouble(prev.Value);
        if (Math.Abs(newD - oldD) < tag.Deadband.Value) return false;

        _lastPublishedByRef[tagRef] = (snapshot.Value, snapshot.StatusCode);
        return true;
    }

    /// <summary>OPC UA severity bits 31..30 = 10 ⇒ Bad.</summary>
    private static bool StatusCodeIsBad(uint statusCode) => (statusCode & 0xC0000000u) == 0x80000000u;

    /// <inheritdoc />
    public string DriverInstanceId => _driverInstanceId;
    /// <inheritdoc />
    public string DriverType => "Modbus";

    /// <summary>True when the supplied DriverConfig JSON carries a real body. The bootstrapper always
    /// passes a populated document; some unit tests pass <c>"{}"</c> or an empty string to exercise
    /// lifecycle shape without a config — those keep the constructor-supplied options.</summary>
    private static bool HasConfigBody(string? driverConfigJson)
    {
        if (string.IsNullOrWhiteSpace(driverConfigJson)) return false;
        var trimmed = driverConfigJson.Trim();
        return trimmed is not "{}" and not "[]";
    }

    /// <inheritdoc />
    public async Task InitializeAsync(string driverConfigJson, CancellationToken cancellationToken)
    {
        await _lifecycleGate.WaitAsync(cancellationToken).ConfigureAwait(false);
        try
        {
            await InitializeCoreAsync(driverConfigJson, cancellationToken).ConfigureAwait(false);
        }
        finally
        {
            _lifecycleGate.Release();
        }
    }

    /// <summary>The gate-held body of <see cref="InitializeAsync"/>.</summary>
    private async Task InitializeCoreAsync(string driverConfigJson, CancellationToken cancellationToken)
    {
        // Claim a new generation and take the previous transport out of service atomically: any read or
        // write that captured the old generation can no longer write health, and nothing can capture the
        // old transport from here on.
        int generation;
        IModbusTransport? previous;
        lock (_stateLock)
        {
            generation = ++_generation;
            previous = _transport;
            _transport = null;
            _commsFault = null;
            WriteHealth(new DriverHealth(DriverState.Initializing, null, null));
        }

        IModbusTransport? transport = null;
        try
        {
            // Release whatever a PREVIOUS initialize published before building the replacements. All
            // fields assigned below (_transport, _probeCts, _reprobeCts) were simply overwritten,
            // so a second initialize on a live driver stranded a connected transport plus two running
            // background loops that no later dispose could reach. The IDriver contract lets a
            // caller re-initialise a live driver without ShutdownAsync, and DriverInstanceActor's retry tick
            // can overlap a still-running attempt, so this must not rely on a teardown having happened.
            // Deliberately NOT the shared TeardownAsync(): that also disposes _poll, which tears down
            // every ACTIVE SUBSCRIPTION — and nothing re-subscribes them afterwards, because a
            // mid-life re-initialize is not a shutdown the OPC UA layer knows to re-drive. A caller
            // that genuinely wants the subscriptions gone calls ShutdownAsync. A first initialize
            // sees nulls, so this block is a no-op on the initial call.
            await StopBackgroundLoopsAsync().ConfigureAwait(false);
            if (previous is not null) await previous.DisposeAsync().ConfigureAwait(false);

            // re-parse the supplied DriverConfig so a config change delivered through the IDriver
            // contract is honoured. Without this the driver keeps serving the options it was CONSTRUCTED
            // with, so an operator's edit is discarded while the deployment still seals green. An empty /
            // placeholder document (the "{}" some unit tests pass) keeps the constructor-supplied options.
            if (HasConfigBody(driverConfigJson))
                _options = ModbusDriverFactoryExtensions.ParseOptions(_driverInstanceId, driverConfigJson);

            transport = _transportFactory(_options);
            await transport.ConnectAsync(cancellationToken).ConfigureAwait(false);

            // Build the RawPath → definition table OFF TO THE SIDE from the authored raw tags. Each
            // entry's TagConfig blob is mapped by the pure factory; the entry's WriteIdempotent flag is
            // threaded onto the def (it lives on the RawTagEntry, not inside the blob). A mapper miss is
            // skipped (logged), never thrown — a bad tag must not fail the whole driver init.
            var table = new Dictionary<string, ModbusTagDefinition>(StringComparer.Ordinal);
            _skippedTags.BeginRebuild(_options.RawTags.Count);
            foreach (var entry in _options.RawTags)
            {
                if (ModbusTagDefinitionFactory.FromTagConfig(entry.TagConfig, entry.RawPath, _options.Family, _options.MelsecSubFamily, out var def))
                    table[entry.RawPath] = def with { WriteIdempotent = entry.WriteIdempotent };
                else
                {
                    _skippedTags.Skip(entry.RawPath, "TagConfig did not map to a definition");
                    _logger.LogWarning(
                        "Modbus tag config did not map to a definition; skipping. Driver={DriverInstanceId} RawPath={RawPath}",
                        _driverInstanceId, entry.RawPath);
                }
            }
            _skippedTags.Commit();

            // Publish transport + table + Healthy as ONE generation-checked step. A superseded attempt
            // (a shutdown/initialize ran while this one was abandoned mid-connect) publishes nothing and
            // releases its own transport.
            lock (_stateLock)
            {
                if (generation != _generation)
                    throw new OperationCanceledException(
                        "Modbus initialize was superseded by a later lifecycle operation; its transport was released");
                _transport = transport;
                Volatile.Write(ref _tagsByRawPath, table);
                Volatile.Write(ref _refusalWarned, new ConcurrentDictionary<string, byte>(StringComparer.Ordinal));
                Volatile.Write(ref _fc23Unsupported, new ConcurrentDictionary<byte, byte>());
                WriteHealth(new DriverHealth(DriverState.Healthy, DateTime.UtcNow, null));

                // PR 23: kick off the probe loop once the transport is up. Initial state stays
                // Unknown until the first probe tick succeeds — avoids broadcasting a premature
                // Running transition before any register round-trip has happened. Started inside the
                // generation-checked publish so a teardown that bypassed the lifecycle gate can never
                // run between the publish and the loop start and strand a loop.
                //
                // #729: each loop's CancellationToken VALUE is snapshotted here, before scheduling, and the
                // worker delegate closes over that value — never over the CTS (or the mutable _probeCts /
                // _reprobeCts fields). The scheduling token only suppresses a still-queued task; once the
                // pool has committed to running the delegate, teardown can complete underneath it (the
                // bounded join in StopBackgroundLoopsAsync gives up and disposes the CTS). A delegate that
                // then read cts.Token would throw ObjectDisposedException; one that read the field would
                // see null or adopt the NEXT initialization's token. A token value stays valid after its
                // source is disposed and still reports the cancellation, so the late worker exits cleanly
                // on its own generation's cancelled token.
                if (_options.Probe.Enabled)
                {
                    var cts = new CancellationTokenSource();
                    var probeToken = cts.Token;
                    var probeTransport = transport;
                    _probeCts = cts;
                    _probeTask = Task.Run(() => ProbeLoopAsync(generation, probeTransport, probeToken), probeToken);
                }

                if (_options.AutoProhibitReprobeInterval is not null)
                {
                    var cts = new CancellationTokenSource();
                    var reprobeToken = cts.Token;
                    _reprobeCts = cts;
                    _reprobeTask = Task.Run(() => ReprobeLoopAsync(reprobeToken), reprobeToken);
                }
            }
            transport = null; // published — owned by the driver now
        }
        catch (Exception ex)
        {
            // A failed attempt releases the transport it built — it is never left half-published.
            if (transport is not null)
            {
                try { await transport.DisposeAsync().ConfigureAwait(false); } catch { }
            }
            WriteLifecycleHealth(generation, new DriverHealth(DriverState.Faulted, null, ex.Message));
            throw;
        }
    }

    /// <summary>Cancels, bounded-joins and disposes the probe and re-probe loops. Idempotent.</summary>
    /// <remarks>
    ///     Limits (#729): the join is bounded by <see cref="BackgroundLoopJoinTimeout"/>, so this does NOT
    ///     guarantee a loop has finished when it returns — a loop stuck in a transport call that ignores its
    ///     token, or a worker the pool had committed to but not yet invoked, is abandoned, not awaited. Such
    ///     a worker holds its own already-cancelled token value (never the CTS or the fields), so it exits on
    ///     its first token check without faulting. Transport lifetime is NOT bound to the loops: the caller
    ///     disposes the transport after this returns, so a probe send that ignores its token and outlives the
    ///     join completes (or faults) against a disposed transport; the loop then sees its cancelled token and
    ///     returns without a health transition.
    /// </remarks>
    private async Task StopBackgroundLoopsAsync()
    {
        var probeCts = _probeCts;
        var reprobeCts = _reprobeCts;
        var tasks = new[] { _probeTask, _reprobeTask }.Where(t => t is not null).Cast<Task>().ToArray();
        _probeCts = null;
        _reprobeCts = null;
        _probeTask = null;
        _reprobeTask = null;

        try { probeCts?.Cancel(); } catch { }
        try { reprobeCts?.Cancel(); } catch { }
        if (tasks.Length > 0)
        {
            try { await Task.WhenAll(tasks).WaitAsync(BackgroundLoopJoinTimeout).ConfigureAwait(false); }
            catch { /* a loop that ignores its token is abandoned, never awaited forever */ }
        }
        probeCts?.Dispose();
        reprobeCts?.Dispose();
    }

    /// <inheritdoc />
    public async Task ReinitializeAsync(string driverConfigJson, CancellationToken cancellationToken)
    {
        // Holds the gate across BOTH halves and calls the ungated cores: taking it once here is what
        // makes the shutdown-then-initialize pair atomic. Routing through the public (gated) methods
        // instead would both self-deadlock and leave a window between them for a concurrent
        // initialize to slip into.
        await _lifecycleGate.WaitAsync(cancellationToken).ConfigureAwait(false);
        try
        {
            await ShutdownCoreAsync().ConfigureAwait(false);
            await InitializeCoreAsync(driverConfigJson, cancellationToken).ConfigureAwait(false);
        }
        finally
        {
            _lifecycleGate.Release();
        }
    }

    /// <inheritdoc />
    public async Task ShutdownAsync(CancellationToken cancellationToken)
    {
        if (await _lifecycleGate.WaitAsync(LifecycleGateTimeout, cancellationToken).ConfigureAwait(false))
        {
            try
            {
                await ShutdownCoreAsync().ConfigureAwait(false);
            }
            finally
            {
                _lifecycleGate.Release();
            }
        }
        else
        {
            _logger.LogWarning(
                "Modbus lifecycle gate still held at shutdown; tearing the transport down anyway. Driver={DriverInstanceId}",
                _driverInstanceId);
            await ShutdownCoreAsync().ConfigureAwait(false);
        }
    }

    /// <summary>The gate-held body of <see cref="ShutdownAsync"/>, shared with
    /// <see cref="ReinitializeAsync"/>.</summary>
    private async Task ShutdownCoreAsync()
    {
        int generation;
        DateTime? lastRead;
        lock (_stateLock)
        {
            // A shutdown is a lifecycle operation too: it supersedes any in-flight (abandoned) initialize,
            // and its own final write below is dropped if a NEWER initialize started meanwhile.
            generation = ++_generation;
            lastRead = _health.LastSuccessfulRead;
        }
        await TeardownAsync().ConfigureAwait(false);
        WriteLifecycleHealth(generation, new DriverHealth(DriverState.Unknown, lastRead, null));
    }

    /// <inheritdoc />
    public DriverHealth GetHealth() => ReadHealth();

    /// <summary>
    ///     Barrier-protected read of the multi-thread <c>_health</c> field.
    ///     <c>Volatile.Read</c> guarantees <c>GetHealth()</c> and the in-driver self-reads (the
    ///     Degraded paths that retain <c>LastSuccessfulRead</c>) observe the most recently
    ///     published snapshot rather than a per-core cached stale copy.
    /// </summary>
    private DriverHealth ReadHealth() => Volatile.Read(ref _health);

    /// <summary>
    ///     Barrier-protected publish of a new <c>_health</c> snapshot.
    /// </summary>
    private void WriteHealth(DriverHealth value) => Volatile.Write(ref _health, value);

    // ---- ITagDiscovery ----

    /// <inheritdoc />
    public DiscoveryRediscoverPolicy RediscoverPolicy => DiscoveryRediscoverPolicy.Once;

    /// <inheritdoc />
    public Task DiscoverAsync(IAddressSpaceBuilder builder, CancellationToken cancellationToken)
    {
        ArgumentNullException.ThrowIfNull(builder);
        var folder = builder.Folder("Modbus", "Modbus");
        // Surface the authored raw tags (mapped into the RawPath → def table at Initialize). The def's
        // Name is the RawPath, used for both the browse name and the driver FullName.
        foreach (var t in _tagsByRawPath.Values)
        {
            folder.Variable(t.Name, t.Name, new DriverAttributeInfo(
                FullName: t.Name,
                DriverDataType: MapDataType(t.DataType),
                IsArray: t.ArrayCount.HasValue,
                ArrayDim: t.ArrayCount.HasValue ? (uint)t.ArrayCount.Value : null,
                SecurityClass: t.Writable ? SecurityClassification.Operate : SecurityClassification.ViewOnly,
                IsHistorized: false,
                IsAlarm: false,
                WriteIdempotent: t.WriteIdempotent));
        }
        return Task.CompletedTask;
    }

    // ---- IReadable ----

    /// <inheritdoc />
    public async Task<IReadOnlyList<DataValueSnapshot>> ReadAsync(
        IReadOnlyList<string> fullReferences, CancellationToken cancellationToken)
    {
        var (generation, transport, table) = CaptureLifecycle();
        var now = DateTime.UtcNow;
        var results = new DataValueSnapshot[fullReferences.Count];
        var batch = new BatchOutcome();

        // MaxReadGap 0 = coalescing OFF (its pre-lane meaning, kept for every persisted config that authored
        // it); the gap-8 default applies only to an absent key.
        var coalesced = !_options.DisableReadCoalescing && _options.MaxReadGap > 0
            ? await ReadCoalescedAsync(transport, table, fullReferences, results, now, batch, cancellationToken).ConfigureAwait(false)
            : new HashSet<int>();

        for (var i = 0; i < fullReferences.Count; i++)
        {
            if (coalesced.Contains(i)) continue;
            if (!table.TryGetValue(fullReferences[i], out var tag))
            {
                results[i] = new DataValueSnapshot(null, StatusBadNodeIdUnknown, null, now);
                continue;
            }
            var unit = ResolveUnitId(tag);
            if (batch.IsFailedFast(unit))
            {
                // Fail fast: this unit (or the whole endpoint) already failed at the transport this batch;
                // paying the same timeout once per remaining tag would stall the poll N-fold.
                results[i] = new DataValueSnapshot(null, StatusBadCommunicationError, null, now);
                InvalidateWriteCache(fullReferences[i]);
                continue;
            }
            try
            {
                var value = await ReadOneAsync(transport, tag, cancellationToken).ConfigureAwait(false);
                results[i] = new DataValueSnapshot(value, 0u, now, now);
                batch.Answered = true;

                // Invalidate the WriteOnChangeOnly cache when the read returns a different value
                // — typically an HMI-side or PLC-internal change. Without this, a setpoint
                // tweaked at the panel could be silently re-suppressed when our client tried
                // to restore it.
                InvalidateWriteCacheIfDiverged(fullReferences[i], value);
            }
            catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
            {
                throw;
            }
            catch (Exception ex)
            {
                results[i] = new DataValueSnapshot(null, ClassifyFailure(ex, unit, fullReferences[i], batch, isWrite: false), null, now);
                InvalidateWriteCache(fullReferences[i]);
            }
        }

        // ONE health write per batch, worst-wins over the batch, generation-checked. It used to be
        // last-writer-wins per tag, so health flapped with tag order.
        ReportOutcome(generation, batch, now);
        return results;
    }

    /// <summary>
    ///     Captures the generation, transport and tag table a read/write batch runs against, atomically
    ///     with respect to a lifecycle publish.
    /// </summary>
    private (int Generation, IModbusTransport Transport, Dictionary<string, ModbusTagDefinition> Table) CaptureLifecycle()
    {
        lock (_stateLock)
        {
            var transport = _transport ?? throw new InvalidOperationException("ModbusDriver not initialized");
            return (_generation, transport, _tagsByRawPath);
        }
    }

    /// <summary>Runs a codec decode, normalising its failure to <see cref="ModbusDecodeException"/> so the
    /// classifier can tell undecodable device data from a transport fault.</summary>
    private static object Decode(Func<object> decode, ModbusTagDefinition tag)
    {
        try { return decode(); }
        catch (Exception ex) when (ex is InvalidDataException or OverflowException or ArgumentException or InvalidCastException)
        {
            throw new ModbusDecodeException($"value of {tag.Name} ({tag.DataType}) could not be decoded: {ex.Message}", ex);
        }
    }

    private async Task<object> ReadOneAsync(IModbusTransport transport, ModbusTagDefinition tag, CancellationToken ct)
    {
        var arrayCount = tag.ArrayCount ?? 1;

        switch (tag.Region)
        {
            case ModbusRegion.Coils:
            case ModbusRegion.DiscreteInputs:
            {
                // FC01 (Coils) / FC02 (DiscreteInputs). Auto-chunk when array count exceeds the
                // coil cap — Modbus spec says ≤ 2000 bits per request; some devices cap lower
                // (we trust the caller-provided MaxCoilsPerRead).
                var fc = tag.Region == ModbusRegion.Coils ? (byte)0x01 : (byte)0x02;
                var cap = _options.MaxCoilsPerRead == 0 ? (ushort)2000 : _options.MaxCoilsPerRead;
                var unitId = ResolveUnitId(tag);
                var bitmap = arrayCount <= cap
                    ? await ReadBitBlockAsync(transport, unitId, fc, tag.Address, (ushort)arrayCount, ct).ConfigureAwait(false)
                    : await ReadBitBlockChunkedAsync(transport, unitId, fc, tag.Address, arrayCount, cap, ct).ConfigureAwait(false);
                return DecodeBitArray(bitmap, arrayCount, tag.ArrayCount.HasValue);
            }
            case ModbusRegion.HoldingRegisters:
            case ModbusRegion.InputRegisters:
            {
                var elementRegs = RegisterCount(tag);
                var totalRegs = (ushort)(elementRegs * arrayCount);
                var fc = tag.Region == ModbusRegion.HoldingRegisters ? (byte)0x03 : (byte)0x04;
                // Auto-chunk when the tag's register span exceeds the caller-configured cap.
                // Affects long strings + arrays (FC03/04 > 125 regs is spec-forbidden; DL205 caps
                // at 128, Mitsubishi Q caps at 64). Scalar non-string tags max out at 4 regs so
                // the cap never triggers for them.
                var cap = _options.MaxRegistersPerRead == 0 ? (ushort)125 : _options.MaxRegistersPerRead;
                var unitId = ResolveUnitId(tag);
                var data = totalRegs <= cap
                    ? await ReadRegisterBlockAsync(transport, unitId, fc, tag.Address, totalRegs, ct).ConfigureAwait(false)
                    : await ReadRegisterBlockChunkedAsync(transport, unitId, fc, tag.Address, totalRegs, cap, ct).ConfigureAwait(false);

                if (!tag.ArrayCount.HasValue)
                    return Decode(() => DecodeRegister(data, tag), tag);

                return Decode(() => DecodeRegisterArray(data, tag, elementRegs, arrayCount), tag);
            }
            default:
                throw new InvalidOperationException($"Unknown region {tag.Region}");
        }
    }

    /// <summary>
    ///     Decode an FC01/FC02 coil-bitmap response into either a single bool (scalar tag) or a
    ///     bool[] of <paramref name="count"/> elements (array tag). Modbus packs coils LSB-first
    ///     within each byte, ascending address across bytes.
    /// </summary>
    private static object DecodeBitArray(ReadOnlySpan<byte> bitmap, int count, bool isArray)
    {
        if (bitmap.IsEmpty)
            throw new InvalidDataException("Modbus bit response produced an empty bitmap — cannot decode coil value");
        if (!isArray) return (bitmap[0] & 0x01) == 1;
        var result = new bool[count];
        for (var i = 0; i < count; i++)
            result[i] = ((bitmap[i / 8] >> (i % 8)) & 0x01) == 1;
        return result;
    }

    /// <summary>
    ///     Decode an array of register-backed values from a contiguous block. Each element
    ///     occupies <paramref name="elementRegs"/> registers and is decoded with the same
    ///     codec the scalar path uses, sliced from its position in the block.
    /// </summary>
    private static object DecodeRegisterArray(byte[] data, ModbusTagDefinition tag, int elementRegs, int count)
    {
        var elementBytes = elementRegs * 2;
        // Element type drives the array CLR type. Boxed into Array so the Read pipeline can
        // surface it directly without a per-call type-switch on the caller side.
        switch (tag.DataType)
        {
            case ModbusDataType.Int16:
            {
                var arr = new short[count];
                for (var i = 0; i < count; i++)
                    arr[i] = (short)DecodeRegister(data.AsSpan(i * elementBytes, elementBytes), tag);
                return arr;
            }
            case ModbusDataType.UInt16:
            {
                var arr = new ushort[count];
                for (var i = 0; i < count; i++)
                    arr[i] = (ushort)DecodeRegister(data.AsSpan(i * elementBytes, elementBytes), tag);
                return arr;
            }
            case ModbusDataType.Int32:
            case ModbusDataType.Bcd16:
            case ModbusDataType.Bcd32:
            {
                var arr = new int[count];
                for (var i = 0; i < count; i++)
                    arr[i] = (int)DecodeRegister(data.AsSpan(i * elementBytes, elementBytes), tag);
                return arr;
            }
            case ModbusDataType.UInt32:
            {
                var arr = new uint[count];
                for (var i = 0; i < count; i++)
                    arr[i] = (uint)DecodeRegister(data.AsSpan(i * elementBytes, elementBytes), tag);
                return arr;
            }
            case ModbusDataType.Int64:
            {
                var arr = new long[count];
                for (var i = 0; i < count; i++)
                    arr[i] = (long)DecodeRegister(data.AsSpan(i * elementBytes, elementBytes), tag);
                return arr;
            }
            case ModbusDataType.UInt64:
            {
                var arr = new ulong[count];
                for (var i = 0; i < count; i++)
                    arr[i] = (ulong)DecodeRegister(data.AsSpan(i * elementBytes, elementBytes), tag);
                return arr;
            }
            case ModbusDataType.Float32:
            {
                var arr = new float[count];
                for (var i = 0; i < count; i++)
                    arr[i] = (float)DecodeRegister(data.AsSpan(i * elementBytes, elementBytes), tag);
                return arr;
            }
            case ModbusDataType.Float64:
            {
                var arr = new double[count];
                for (var i = 0; i < count; i++)
                    arr[i] = (double)DecodeRegister(data.AsSpan(i * elementBytes, elementBytes), tag);
                return arr;
            }
            case ModbusDataType.String:
            {
                // Each element occupies elementRegs registers = elementBytes bytes, encoding
                // StringLength chars packed high-byte-first or low-byte-first per tag.StringByteOrder.
                // DecodeRegister handles the per-element slice identically to the scalar path.
                var arr = new string[count];
                for (var i = 0; i < count; i++)
                    arr[i] = (string)DecodeRegister(data.AsSpan(i * elementBytes, elementBytes), tag);
                return arr;
            }
            case ModbusDataType.BitInRegister:
            {
                // Each element is 1 holding register (2 bytes). The same BitIndex is applied to
                // every element. DecodeRegister returns bool for BitInRegister scalar slices.
                var arr = new bool[count];
                for (var i = 0; i < count; i++)
                    arr[i] = (bool)DecodeRegister(data.AsSpan(i * elementBytes, elementBytes), tag);
                return arr;
            }
            default:
                throw new InvalidOperationException(
                    $"Array decode not supported for {tag.DataType} (use scalar tags or split by element)");
        }
    }

    /// <summary>Resolve the UnitId for a tag — per-tag override or driver-level fallback.</summary>
    private byte ResolveUnitId(ModbusTagDefinition tag) => tag.UnitId ?? _options.UnitId;

    private bool RangeIsAutoProhibited(byte unit, ModbusRegion region, ushort start, ushort end)
    {
        lock (_autoProhibitedLock)
        {
            foreach (var p in _autoProhibited.Keys)
            {
                // A candidate (start..end) range is prohibited if it overlaps any recorded
                // failure. Overlap rule: max-start ≤ min-end. We don't try to be smart about
                // partial overlap — once a range fails, any superset of it is also untrusted.
                if (p.Unit != unit || p.Region != region) continue;
                if (Math.Max(start, p.Start) <= Math.Min(end, p.End)) return true;
            }
            return false;
        }
    }

    private void RecordAutoProhibition(byte unit, ModbusRegion region, ushort start, ushort end)
    {
        bool isNew;
        lock (_autoProhibitedLock)
        {
            // Multi-register prohibitions enter the bisection workflow on the next re-probe;
            // single-register prohibitions are already minimal and skip bisection.
            isNew = !_autoProhibited.ContainsKey((unit, region, start, end));
            _autoProhibited[(unit, region, start, end)] = new ProhibitionState
            {
                LastProbedUtc = DateTime.UtcNow,
                SplitPending = end > start,
            };
        }

        if (isNew)
            _logger.LogWarning(
                "Modbus coalesced read failed; auto-prohibited range recorded. Driver={DriverInstanceId} Unit={Unit} Region={Region} Start={Start} End={End} Span={Span}",
                _driverInstanceId, unit, region, start, end, end - start + 1);
    }

    /// <summary>
    ///     Info log when a re-probe clears a prohibition. Operators see recovery
    ///     events without having to poll <see cref="GetAutoProhibitedRanges"/>.
    /// </summary>
    private void LogProhibitionCleared(byte unit, ModbusRegion region, ushort start, ushort end) =>
        _logger.LogInformation(
            "Modbus auto-prohibition cleared by re-probe. Driver={DriverInstanceId} Unit={Unit} Region={Region} Start={Start} End={End}",
            _driverInstanceId, unit, region, start, end);

    /// <summary>
    ///     Operator-visible snapshot of every range the planner has learned to read
    ///     individually. Exposed through the driver-diagnostics surface; consumers (Admin UI,
    ///     log-aggregation, dashboards) call this to show what's been auto-isolated. Populated
    ///     on coalesced-read failure, narrowed by bisection, cleared by the
    ///     re-probe loop when ranges become healthy again.
    /// </summary>
    /// <returns>The current set of auto-prohibited register ranges.</returns>
    public IReadOnlyList<ModbusAutoProhibition> GetAutoProhibitedRanges()
    {
        lock (_autoProhibitedLock)
            return _autoProhibited
                .Select(kv => new ModbusAutoProhibition(
                    kv.Key.Unit, kv.Key.Region, kv.Key.Start, kv.Key.End,
                    kv.Value.LastProbedUtc, kv.Value.SplitPending))
                .ToArray();
    }

    /// <summary>Test/diagnostic accessor — returns the current auto-prohibited range count.</summary>
    internal int AutoProhibitedRangeCount
    {
        get { lock (_autoProhibitedLock) return _autoProhibited.Count; }
    }

    /// <summary>
    ///     Periodic re-probe loop, augmented with bisection-style narrowing.
    ///     Each tick processes every prohibition: split-pending multi-register ranges get
    ///     bisected (try left + right halves; replace with whichever halves still fail),
    ///     single-register or non-split-pending ranges get a straight re-probe. Lives for
    ///     the driver lifetime; cancelled by <c>ShutdownAsync</c>.
    /// </summary>
    private async Task ReprobeLoopAsync(CancellationToken ct)
    {
        var interval = _options.AutoProhibitReprobeInterval!.Value;
        while (!ct.IsCancellationRequested)
        {
            try { await Task.Delay(interval, ct).ConfigureAwait(false); }
            catch (OperationCanceledException) { return; }
            try { await RunReprobeOnceForTestAsync(ct).ConfigureAwait(false); }
            catch (OperationCanceledException) when (ct.IsCancellationRequested) { return; }
            catch (ObjectDisposedException) when (ct.IsCancellationRequested)
            {
                return;
            }
        }
    }

    /// <summary>
    ///     One re-probe pass. Public-but-internal so tests can drive it synchronously rather
    ///     than wait on the background timer. Iterates a snapshot of the prohibition set; for
    ///     each entry decides between bisection (multi-register + SplitPending) or straight
    ///     retry (single-register or already-narrowed).
    /// </summary>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    internal async Task RunReprobeOnceForTestAsync(CancellationToken ct)
    {
        var transport = _transport ?? throw new InvalidOperationException("Transport not connected");

        ((byte Unit, ModbusRegion Region, ushort Start, ushort End) Key, bool SplitPending)[] candidates;
        lock (_autoProhibitedLock)
            candidates = _autoProhibited
                .Select(kv => (Key: kv.Key, SplitPending: kv.Value.SplitPending))
                .ToArray();

        foreach (var (key, splitPending) in candidates)
        {
            if (ct.IsCancellationRequested) return;
            if (splitPending && key.End > key.Start)
                await BisectAndReprobeAsync(transport, key, ct).ConfigureAwait(false);
            else
                await StraightReprobeAsync(transport, key, ct).ConfigureAwait(false);
        }
    }

    private async Task StraightReprobeAsync(IModbusTransport transport,
        (byte Unit, ModbusRegion Region, ushort Start, ushort End) key, CancellationToken ct)
    {
        var qty = (ushort)(key.End - key.Start + 1);
        try
        {
            _ = await ReadRangeAsync(transport, key.Unit, key.Region, key.Start, qty, ct).ConfigureAwait(false);
            lock (_autoProhibitedLock) _autoProhibited.Remove(key);
            LogProhibitionCleared(key.Unit, key.Region, key.Start, key.End);
        }
        catch (OperationCanceledException) when (ct.IsCancellationRequested) { throw; }
        catch
        {
            lock (_autoProhibitedLock)
                if (_autoProhibited.TryGetValue(key, out var st)) st.LastProbedUtc = DateTime.UtcNow;
        }
    }

    /// <summary>
    ///     Bisect a multi-register prohibition. Removes the parent entry and re-adds
    ///     whichever halves still fail. Over multiple re-probe ticks the prohibition narrows
    ///     log2(span) times until it pinpoints the actual protected register(s).
    /// </summary>
    private async Task BisectAndReprobeAsync(IModbusTransport transport,
        (byte Unit, ModbusRegion Region, ushort Start, ushort End) key, CancellationToken ct)
    {
        var mid = (ushort)((key.Start + key.End) / 2);
        var leftEnd = mid;
        var rightStart = (ushort)(mid + 1);

        var leftFailed = await ProbeFailsAsync(transport, key.Region, key.Unit, key.Start, leftEnd, ct).ConfigureAwait(false);
        var rightFailed = await ProbeFailsAsync(transport, key.Region, key.Unit, rightStart, key.End, ct).ConfigureAwait(false);

        lock (_autoProhibitedLock)
        {
            _autoProhibited.Remove(key);
            if (leftFailed)
            {
                _autoProhibited[(key.Unit, key.Region, key.Start, leftEnd)] = new ProhibitionState
                {
                    LastProbedUtc = DateTime.UtcNow,
                    SplitPending = leftEnd > key.Start,
                };
            }
            if (rightFailed)
            {
                _autoProhibited[(key.Unit, key.Region, rightStart, key.End)] = new ProhibitionState
                {
                    LastProbedUtc = DateTime.UtcNow,
                    SplitPending = key.End > rightStart,
                };
            }
            // Both halves succeeded → entry is just removed. The parent prohibition is gone
            // and the next normal scan can re-coalesce across the whole original range.
        }

        if (!leftFailed && !rightFailed)
            LogProhibitionCleared(key.Unit, key.Region, key.Start, key.End);
        else
        {
            if (!leftFailed)
                LogProhibitionCleared(key.Unit, key.Region, key.Start, leftEnd);
            if (!rightFailed)
                LogProhibitionCleared(key.Unit, key.Region, rightStart, key.End);
        }
    }

    private async Task<bool> ProbeFailsAsync(IModbusTransport transport, ModbusRegion region, byte unit,
        ushort start, ushort end, CancellationToken ct)
    {
        var qty = (ushort)(end - start + 1);
        try
        {
            _ = await ReadRangeAsync(transport, unit, region, start, qty, ct).ConfigureAwait(false);
            return false;
        }
        catch (OperationCanceledException) when (ct.IsCancellationRequested) { throw; }
        catch { return true; }
    }

    /// <summary>
    ///     Block-read coalescing planner. Groups eligible tags by (UnitId, Region), sorts by start address,
    ///     and merges adjacent / near-adjacent tags (gap ≤ <see cref="ModbusDriverOptions.MaxReadGap"/>, 0 =
    ///     adjacent or overlapping only) into one read per block: FC03/FC04 for the register regions (scalar
    ///     numeric, <c>String</c> and <c>BitInRegister</c> tags — several bit tags on ONE status word fold into
    ///     a single read of it), FC01/FC02 for Coils / DiscreteInputs (gap counted in bits). Per block: emit
    ///     one PDU, slice the response back into per-tag values, populate <paramref name="results"/> and the
    ///     WriteOnChangeOnly cache. Returns the set of <paramref name="fullReferences"/> indices the planner
    ///     handled — the caller falls back to the per-tag path for the rest (arrays, lone tags, prohibited,
    ///     unknown, refused ranges).
    /// </summary>
    private async Task<HashSet<int>> ReadCoalescedAsync(
        IModbusTransport transport,
        Dictionary<string, ModbusTagDefinition> table,
        IReadOnlyList<string> fullReferences,
        DataValueSnapshot[] results,
        DateTime timestamp,
        BatchOutcome batch,
        CancellationToken ct)
    {
        // Eligible: known scalar tag, not CoalesceProhibited, with a region/type pair the codec can slice.
        var eligible = new List<(int Index, ModbusTagDefinition Tag)>();
        for (var i = 0; i < fullReferences.Count; i++)
        {
            if (!table.TryGetValue(fullReferences[i], out var tag)) continue;
            if (tag.CoalesceProhibited) continue;
            // Defensive: the factory refuses incompatible pairs, but the planner's register math must never
            // throw for a tag that slipped through — one bad tag would otherwise fail the whole batch.
            if (!ModbusTagDefinitionFactory.IsRegionTypeCompatible(tag.Region, tag.DataType)) continue;
            if (tag.ArrayCount.HasValue) continue;
            eligible.Add((i, tag));
        }
        if (eligible.Count == 0) return new HashSet<int>();

        var handled = new HashSet<int>();

        // Group by (UnitId, Region) — coalescing across slaves or regions is unsafe.
        foreach (var group in eligible.GroupBy(e => (Unit: ResolveUnitId(e.Tag), e.Tag.Region)))
        {
            var isBits = IsBitRegion(group.Key.Region);
            var cap = isBits
                ? (_options.MaxCoilsPerRead == 0 ? 2000 : _options.MaxCoilsPerRead)
                : (_options.MaxRegistersPerRead == 0 ? 125 : _options.MaxRegistersPerRead);
            var sorted = group.OrderBy(e => e.Tag.Address).ToList();

            // Build merged blocks. A "block" is (start, lastEnd, members[]) where lastEnd is the inclusive
            // end of the widest member span seen so far. A new tag joins the block if its start ≤ lastEnd +
            // 1 + MaxReadGap AND the resulting span ≤ cap AND the span crosses no auto-prohibited range.
            var blocks = new List<(int Start, int End, List<(int Index, ModbusTagDefinition Tag)> Members)>();
            foreach (var (idx, tag) in sorted)
            {
                var tagStart = (int)tag.Address;
                var tagEnd = tagStart + (isBits ? 1 : RegisterCount(tag)) - 1;
                if (tagEnd > ushort.MaxValue || tagEnd - tagStart + 1 > cap) continue; // per-tag path chunks / refuses it
                if (blocks.Count > 0)
                {
                    var last = blocks[^1];
                    var gap = tagStart - last.End - 1;
                    var newEnd = Math.Max(tagEnd, last.End);
                    var newSpan = newEnd - last.Start + 1;
                    var crossesProhibition = RangeIsAutoProhibited(group.Key.Unit, group.Key.Region, (ushort)last.Start, (ushort)newEnd);
                    if (gap <= _options.MaxReadGap && newSpan <= cap && !crossesProhibition)
                    {
                        last.Members.Add((idx, tag));
                        blocks[^1] = (last.Start, newEnd, last.Members);
                        continue;
                    }
                }
                blocks.Add((tagStart, tagEnd, new List<(int, ModbusTagDefinition)> { (idx, tag) }));
            }

            // Issue one PDU per block. On a device REFUSAL (illegal data address / protected register),
            // record the range as auto-prohibited, leave the member indices UNhandled, and let the per-tag
            // fallback in ReadAsync read each surviving address individually. On a transport-level failure
            // (timeout / socket drop) mark members Bad and short-circuit the per-tag fallback (hitting the
            // dead socket again won't help). Bisection narrows the prohibition over subsequent re-probe ticks.
            foreach (var block in blocks)
            {
                if (block.Members.Count == 1)
                {
                    // Lone tag — let the per-tag path handle it for symmetry with WriteOnChange
                    // cache invalidation. Costs nothing because one tag = one PDU either way.
                    continue;
                }

                var start = (ushort)block.Start;
                var qty = (ushort)(block.End - block.Start + 1);
                if (batch.IsFailedFast(group.Key.Unit))
                {
                    foreach (var (idx, _) in block.Members)
                    {
                        results[idx] = new DataValueSnapshot(null, StatusBadCommunicationError, null, timestamp);
                        InvalidateWriteCache(fullReferences[idx]);
                        handled.Add(idx);
                    }
                    continue;
                }
                byte[] data;
                try
                {
                    data = await ReadRangeAsync(transport, group.Key.Unit, group.Key.Region, start, qty, ct).ConfigureAwait(false);
                }
                catch (OperationCanceledException) when (ct.IsCancellationRequested)
                {
                    throw;
                }
                catch (ModbusException mex) when (IsRefusalCode(mex.ExceptionCode))
                {
                    // The device refused the merged range (a protected hole inside it): record the range
                    // as auto-prohibited and leave the members UNhandled so the per-tag fallback reads each
                    // surviving address individually. The device answered, so health is not degraded.
                    batch.Answered = true;
                    RecordAutoProhibition(group.Key.Unit, group.Key.Region, start, (ushort)block.End);
                    continue;
                }
                catch (Exception ex)
                {
                    // Communication failures (timeout, socket drop) and non-refusal exception codes aren't
                    // a structural reason to prohibit the range — the same coalesced read might succeed
                    // once the transport recovers. Mark members Bad for this scan but don't auto-prohibit
                    // and don't deflect to per-tag fallback (which would just hit the same dead socket).
                    var status = ClassifyFailure(ex, group.Key.Unit, fullReferences[block.Members[0].Index], batch, isWrite: false);
                    foreach (var (idx, _) in block.Members)
                    {
                        results[idx] = new DataValueSnapshot(null, status, null, timestamp);
                        InvalidateWriteCache(fullReferences[idx]);
                        handled.Add(idx);
                    }
                    continue;
                }

                batch.Answered = true;
                foreach (var (idx, tag) in block.Members)
                {
                    handled.Add(idx);
                    try
                    {
                        object value;
                        if (isBits)
                        {
                            var bit = tag.Address - block.Start;
                            value = ((data[bit / 8] >> (bit % 8)) & 0x01) == 1;
                        }
                        else
                        {
                            var sliceOffsetBytes = (tag.Address - block.Start) * 2;
                            var sliceLenBytes = RegisterCount(tag) * 2;
                            value = Decode(() => DecodeRegister(data.AsSpan(sliceOffsetBytes, sliceLenBytes), tag), tag);
                        }
                        results[idx] = new DataValueSnapshot(value, 0u, timestamp, timestamp);
                        InvalidateWriteCacheIfDiverged(fullReferences[idx], value);
                    }
                    catch (ModbusDecodeException dex)
                    {
                        // One undecodable member never fails its neighbours.
                        results[idx] = new DataValueSnapshot(null,
                            ClassifyFailure(dex, group.Key.Unit, fullReferences[idx], batch, isWrite: false), null, timestamp);
                    }
                }
            }
        }
        return handled;
    }

    private static bool IsBitRegion(ModbusRegion region) => region is ModbusRegion.Coils or ModbusRegion.DiscreteInputs;

    private static byte ReadFunctionCode(ModbusRegion region) => region switch
    {
        ModbusRegion.Coils => 0x01,
        ModbusRegion.DiscreteInputs => 0x02,
        ModbusRegion.HoldingRegisters => 0x03,
        _ => 0x04,
    };

    /// <summary>Reads one contiguous range of the region with the matching function code — registers as
    /// big-endian bytes, bits as an LSB-first bitmap.</summary>
    private Task<byte[]> ReadRangeAsync(
        IModbusTransport transport, byte unit, ModbusRegion region, ushort start, ushort qty, CancellationToken ct)
        => IsBitRegion(region)
            ? ReadBitBlockAsync(transport, unit, ReadFunctionCode(region), start, qty, ct)
            : ReadRegisterBlockAsync(transport, unit, ReadFunctionCode(region), start, qty, ct);

    /// <summary>
    ///     A failed read leaves the device's value UNKNOWN (it may have rebooted holding anything), so the
    ///     WriteOnChangeOnly suppression for that tag is dropped — otherwise re-asserting the same setpoint
    ///     after an outage would be swallowed, the write-side twin of the value-only recovery dedup trap.
    /// </summary>
    private void InvalidateWriteCache(string fullRef)
    {
        if (!_options.WriteOnChangeOnly) return;
        lock (_lastWrittenLock) _lastWrittenByRef.Remove(fullRef);
    }

    private void InvalidateWriteCacheIfDiverged(string fullRef, object value)
    {
        if (!_options.WriteOnChangeOnly) return;
        lock (_lastWrittenLock)
        {
            if (_lastWrittenByRef.TryGetValue(fullRef, out var prev) && !Equals(prev, value))
                _lastWrittenByRef.Remove(fullRef);
        }
    }


    private async Task<byte[]> ReadRegisterBlockAsync(
        IModbusTransport transport, byte unitId, byte fc, ushort address, ushort quantity, CancellationToken ct)
    {
        var pdu = new byte[] { fc, (byte)(address >> 8), (byte)(address & 0xFF),
                               (byte)(quantity >> 8), (byte)(quantity & 0xFF) };
        var resp = await transport.SendAsync(unitId, pdu, ct).ConfigureAwait(false);
        // resp = [fc][byte-count][data...] — validate before indexing to surface a clean error
        // rather than an IndexOutOfRangeException when a device returns a truncated PDU.
        if (resp.Length < 2)
            throw new InvalidDataException(
                $"Modbus register response too short: expected at least 2 bytes (fc+bytecount), got {resp.Length}");
        if (resp.Length < 2 + resp[1])
            throw new InvalidDataException(
                $"Modbus register response truncated: byte-count field declares {resp[1]} bytes but only {resp.Length - 2} available");
        var expectedByteCount = quantity * 2;
        if (resp[1] != expectedByteCount)
            throw new InvalidDataException(
                $"Modbus register response byte-count mismatch: requested {quantity} registers ({expectedByteCount} bytes), got {resp[1]} bytes");
        var data = new byte[resp[1]];
        Buffer.BlockCopy(resp, 2, data, 0, resp[1]);
        return data;
    }

    private async Task<byte[]> ReadBitBlockAsync(
        IModbusTransport transport, byte unitId, byte fc, ushort address, ushort qty, CancellationToken ct)
    {
        var pdu = new byte[] { fc, (byte)(address >> 8), (byte)(address & 0xFF),
                               (byte)(qty >> 8), (byte)(qty & 0xFF) };
        var resp = await transport.SendAsync(unitId, pdu, ct).ConfigureAwait(false);
        if (resp.Length < 2)
            throw new InvalidDataException(
                $"Modbus bit response too short: expected at least 2 bytes (fc+bytecount), got {resp.Length}");
        if (resp.Length < 2 + resp[1])
            throw new InvalidDataException(
                $"Modbus bit response truncated: byte-count field declares {resp[1]} bytes but only {resp.Length - 2} available");
        var expectedByteCount = (qty + 7) / 8;
        if (resp[1] < expectedByteCount)
            throw new InvalidDataException(
                $"Modbus bit response byte-count mismatch: requested {qty} bits ({expectedByteCount} bytes), got {resp[1]} bytes");
        var bitmap = new byte[resp[1]];
        Buffer.BlockCopy(resp, 2, bitmap, 0, resp[1]);
        return bitmap;
    }

    /// <summary>
    ///     Auto-chunk coil-array reads above MaxCoilsPerRead. Reassembles per-chunk bitmaps into
    ///     one logical bitmap byte array sized for the full <paramref name="totalBits"/>; the
    ///     downstream <see cref="DecodeBitArray"/> walks bits LSB-first the same way it would
    ///     for a single-chunk response.
    /// </summary>
    private async Task<byte[]> ReadBitBlockChunkedAsync(
        IModbusTransport transport, byte unitId, byte fc, ushort address, int totalBits, ushort cap, CancellationToken ct)
    {
        var assembled = new byte[(totalBits + 7) / 8];
        var done = 0;
        while (done < totalBits)
        {
            var chunk = (ushort)Math.Min(cap, totalBits - done);
            var chunkBitmap = await ReadBitBlockAsync(transport, unitId, fc, (ushort)(address + done), chunk, ct).ConfigureAwait(false);
            // Re-pack per-chunk LSB-first bits into the assembled bitmap at the right offset.
            for (var i = 0; i < chunk; i++)
            {
                if (((chunkBitmap[i / 8] >> (i % 8)) & 0x01) == 0) continue;
                var dest = done + i;
                assembled[dest / 8] |= (byte)(1 << (dest % 8));
            }
            done += chunk;
        }
        return assembled;
    }

    private async Task<byte[]> ReadRegisterBlockChunkedAsync(
        IModbusTransport transport, byte unitId, byte fc, ushort address, ushort totalRegs, ushort cap, CancellationToken ct)
    {
        var assembled = new byte[totalRegs * 2];
        ushort done = 0;
        while (done < totalRegs)
        {
            var chunk = (ushort)Math.Min(cap, totalRegs - done);
            var chunkBytes = await ReadRegisterBlockAsync(transport, unitId, fc, (ushort)(address + done), chunk, ct).ConfigureAwait(false);
            Buffer.BlockCopy(chunkBytes, 0, assembled, done * 2, chunkBytes.Length);
            done += chunk;
        }
        return assembled;
    }

    // ---- IWritable ----

    /// <inheritdoc />
    public async Task<IReadOnlyList<WriteResult>> WriteAsync(
        IReadOnlyList<WriteRequest> writes, CancellationToken cancellationToken)
    {
        var (generation, transport, table) = CaptureLifecycle();
        var results = new WriteResult[writes.Count];
        var batch = new BatchOutcome();
        for (var i = 0; i < writes.Count; i++)
        {
            var w = writes[i];
            if (!table.TryGetValue(w.FullReference, out var tag))
            {
                results[i] = new WriteResult(StatusBadNodeIdUnknown);
                continue;
            }
            if (!tag.Writable || tag.Region is ModbusRegion.DiscreteInputs or ModbusRegion.InputRegisters)
            {
                results[i] = new WriteResult(StatusBadNotWritable);
                continue;
            }
            if (_options.WriteOnChangeOnly && IsRedundantWrite(w.FullReference, w.Value))
            {
                results[i] = new WriteResult(0u);
                continue;
            }
            var unit = ResolveUnitId(tag);
            if (batch.IsFailedFast(unit))
            {
                results[i] = new WriteResult(StatusBadCommunicationError);
                continue;
            }

            try
            {
                await WriteOneAsync(transport, tag, w.Value, cancellationToken).ConfigureAwait(false);
                results[i] = new WriteResult(0u);
                batch.Answered = true;
                if (_options.WriteOnChangeOnly)
                    lock (_lastWrittenLock) _lastWrittenByRef[w.FullReference] = w.Value;
            }
            catch (Exception ex)
            {
                results[i] = new WriteResult(MapWriteFailure(ex, unit, w.FullReference, batch, cancellationToken));
                // A failed write may or may not have landed — the device value is unknown now.
                InvalidateWriteCache(w.FullReference);
            }
        }

        // Write outcome feeds the same single health slot as reads: a comms failure degrades (LastSuccessfulRead
        // preserved); a good write or a device refusal proves the device answered and clears it. Generation-checked.
        ReportOutcome(generation, batch, DateTime.UtcNow);
        return results;
    }

    /// <summary>
    ///     Write-status mapping (review 07 H7). Failures raised BEFORE the wire — a value that does not fit
    ///     (<c>BadOutOfRange</c>), cannot convert (<c>BadTypeMismatch</c>) or is not supported
    ///     (<c>BadNotSupported</c>) — never touch health. Device answers go through
    ///     <see cref="ClassifyFailure"/> (refusal / device fault / comms fault). Transport failures —
    ///     desync, timeout, socket, EOF — are <c>BadCommunicationError</c>, no longer
    ///     <c>BadInternalError</c>; only a genuinely unexpected exception still is.
    /// </summary>
    private uint MapWriteFailure(Exception ex, byte unit, string tagRef, BatchOutcome batch, CancellationToken ct)
    {
        switch (ex)
        {
            case OperationCanceledException when ct.IsCancellationRequested:
                // The caller's write deadline fired (e.g. waiting on the single-flight gate). The device
                // said nothing, so health is untouched.
                return StatusBadTimeout;
            case ModbusWriteRefusedException refused:
                return refused.StatusCode;
            case OverflowException or ArgumentOutOfRangeException:
                return StatusBadOutOfRange;
            case FormatException or InvalidCastException or ArgumentException:
                return StatusBadTypeMismatch;
            case NotSupportedException:
                return StatusBadNotSupported;
            case ModbusException or ModbusDecodeException or IOException or InvalidDataException
                or System.Net.Sockets.SocketException or ObjectDisposedException or TimeoutException
                or OperationCanceledException:
                return ClassifyFailure(ex, unit, tagRef, batch, isWrite: true);
            default:
                _logger.LogWarning(ex, "Modbus write to {RawPath} failed unexpectedly. Driver={DriverInstanceId}", tagRef, _driverInstanceId);
                return StatusBadInternalError;
        }
    }

    private bool IsRedundantWrite(string tagRef, object? value)
    {
        lock (_lastWrittenLock)
        {
            if (!_lastWrittenByRef.TryGetValue(tagRef, out var prev)) return false;
            // Object.Equals handles boxed-numeric equality (5 == 5 even if one was short and
            // one int through boxing). For arrays we deliberately don't suppress — equality
            // semantics on arrays are reference-only so the cache miss is the safer answer.
            if (prev is null || value is null) return Equals(prev, value);
            if (prev is Array || value is Array) return false;
            return prev.Equals(value);
        }
    }

    // BitInRegister writes need a read-modify-write against the full holding register. The
    // per-register lock (declared at the top of the class) keeps concurrent bit-write callers
    // from stomping on each other — Write bit 0 and Write bit 5 targeting the same register
    // can arrive on separate subscriber threads, and without serialising the RMW the
    // second-to-commit value wins + the first bit update is lost.
    private SemaphoreSlim GetRmwLock(ushort address) =>
        _rmwLocks.GetOrAdd(address, _ => new SemaphoreSlim(1, 1));

    private async Task WriteOneAsync(IModbusTransport transport, ModbusTagDefinition tag, object? value, CancellationToken ct)
    {
        // BitInRegister → RMW dispatch ahead of the normal encode path so the lock + read-modify-
        // write sequence doesn't hit EncodeRegister's defensive throw.
        if (tag.DataType == ModbusDataType.BitInRegister &&
            tag.Region is ModbusRegion.HoldingRegisters)
        {
            if (tag.ArrayCount.HasValue)
                await WriteBitInRegisterArrayAsync(transport, tag, value, ct).ConfigureAwait(false);
            else
                await WriteBitInRegisterAsync(transport, tag, value, ct).ConfigureAwait(false);
            return;
        }

        switch (tag.Region)
        {
            case ModbusRegion.Coils:
            {
                if (!tag.ArrayCount.HasValue && !_options.UseFC15ForSingleCoilWrites)
                {
                    var on = Convert.ToBoolean(value);
                    var pdu = new byte[] { 0x05, (byte)(tag.Address >> 8), (byte)(tag.Address & 0xFF),
                                           on ? (byte)0xFF : (byte)0x00, 0x00 };
                    await transport.SendAsync(ResolveUnitId(tag), pdu, ct).ConfigureAwait(false);
                    return;
                }
                // FC15 path: either an explicit array, or UseFC15ForSingleCoilWrites=true forced
                // it for a scalar (synthesise a 1-element bool[] from the scalar value).
                var arrayLen = tag.ArrayCount ?? 1;
                if (!tag.ArrayCount.HasValue)
                    value = new[] { Convert.ToBoolean(value) };
                // FC15 — Write Multiple Coils. Pack the bool[] into LSB-first bitmap.
                var values = ToBoolArray(value, arrayLen, tag.Name);
                var byteCount = (values.Length + 7) / 8;
                var bitmap = new byte[byteCount];
                for (var i = 0; i < values.Length; i++)
                    if (values[i]) bitmap[i / 8] |= (byte)(1 << (i % 8));
                var qty = (ushort)values.Length;
                // [fc][addr:2][qty:2][byteCount] + data: exactly 6 + byteCount (no trailing byte past the declared data).
                var pdu15 = new byte[6 + byteCount];
                pdu15[0] = 0x0F;
                pdu15[1] = (byte)(tag.Address >> 8); pdu15[2] = (byte)(tag.Address & 0xFF);
                pdu15[3] = (byte)(qty >> 8); pdu15[4] = (byte)(qty & 0xFF);
                pdu15[5] = (byte)byteCount;
                Buffer.BlockCopy(bitmap, 0, pdu15, 6, byteCount);
                await transport.SendAsync(ResolveUnitId(tag), pdu15, ct).ConfigureAwait(false);
                return;
            }
            case ModbusRegion.HoldingRegisters:
            {
                var bytes = tag.ArrayCount.HasValue
                    ? EncodeRegisterArray(value, tag)
                    : EncodeRegister(value, tag);

                if (bytes.Length == 2 && !tag.ArrayCount.HasValue && !_options.UseFC16ForSingleRegisterWrites)
                {
                    // FC06 fast-path for single-register scalar writes only. Arrays always use
                    // FC16 even when the array is one element wide, because the encoder shape
                    // may need it. UseFC16ForSingleRegisterWrites=true forces FC16 even here for
                    // PLCs that only accept the multi-write codes.
                    var pdu = new byte[] { 0x06, (byte)(tag.Address >> 8), (byte)(tag.Address & 0xFF),
                                           bytes[0], bytes[1] };
                    await transport.SendAsync(ResolveUnitId(tag), pdu, ct).ConfigureAwait(false);
                }
                else
                {
                    // FC 16 (Write Multiple Registers) for 32-bit / 64-bit / array / string types.
                    var qty = (ushort)(bytes.Length / 2);
                    var writeCap = _options.MaxRegistersPerWrite == 0 ? (ushort)123 : _options.MaxRegistersPerWrite;
                    if (qty > writeCap)
                        throw new ModbusWriteRefusedException(StatusBadOutOfRange,
                            $"Write of {qty} registers to {tag.Name} exceeds MaxRegistersPerWrite={writeCap}. " +
                            $"Split the tag (e.g. shorter StringLength or smaller ArrayCount) — partial FC16 chunks would lose atomicity.");
                    if (await TryWriteViaFc23Async(transport, tag, bytes, qty, ct).ConfigureAwait(false)) return;
                    // [fc][addr:2][qty:2][byteCount] + data: exactly 6 + byteCount.
                    var pdu = new byte[6 + bytes.Length];
                    pdu[0] = 0x10;
                    pdu[1] = (byte)(tag.Address >> 8); pdu[2] = (byte)(tag.Address & 0xFF);
                    pdu[3] = (byte)(qty >> 8); pdu[4] = (byte)(qty & 0xFF);
                    pdu[5] = (byte)bytes.Length;
                    Buffer.BlockCopy(bytes, 0, pdu, 6, bytes.Length);
                    await transport.SendAsync(ResolveUnitId(tag), pdu, ct).ConfigureAwait(false);
                }
                return;
            }
            default:
                throw new ModbusWriteRefusedException(StatusBadNotWritable, $"Writes not supported for region {tag.Region}");
        }
    }

    /// <summary>FC23's spec ceiling on the write quantity (0x79); larger multi-register writes use FC16.</summary>
    private const ushort Fc23MaxWriteRegisters = 121;

    /// <summary>
    ///     Units that refused FC23 (exception 01) or failed it at the transport; their multi-register writes
    ///     use FC16 for the rest of this driver generation. Replaced (never cleared in place) on re-init.
    /// </summary>
    private ConcurrentDictionary<byte, byte> _fc23Unsupported = new();

    /// <summary>
    ///     Multi-register write via FC23 (Read/Write Multiple Registers): the device writes the block and
    ///     returns the SAME block read back in one transaction, so the write is confirmed by the device's own
    ///     post-write registers. OPT-IN via <see cref="ModbusDriverOptions.UseFC23ForMultiRegisterWrites"/>,
    ///     and <see cref="ModbusDriverOptions.DisableFC23"/> is the hard kill-switch. A device that does
    ///     not implement FC23 (MELSEC QJ71MT91, S7 Modbus servers — exception 01) falls back to FC16 for this
    ///     write and every later one on that unit, which is safe because an Illegal Function wrote nothing.
    ///     A transport failure on FC23 is reported (its outcome is unknown, so it is not retried as FC16) and
    ///     also moves the unit to FC16, so a gateway that cannot frame FC23 costs one failed write, not all.
    ///     A read-back that differs from what was written (PLC logic overwrote it in the same scan, or the
    ///     device clamped it) is logged once per tag; the write itself was accepted.
    /// </summary>
    /// <returns><see langword="true"/> when FC23 performed the write; <see langword="false"/> to use FC16.</returns>
    private async Task<bool> TryWriteViaFc23Async(
        IModbusTransport transport, ModbusTagDefinition tag, byte[] bytes, ushort qty, CancellationToken ct)
    {
        var unit = ResolveUnitId(tag);
        var unsupported = Volatile.Read(ref _fc23Unsupported);
        // Only genuinely multi-register writes: a single register forced onto FC16 (UseFC16ForSingleRegisterWrites)
        // stays on the function code the operator named.
        if (!_options.UseFC23ForMultiRegisterWrites || _options.DisableFC23
            || qty < 2 || qty > Fc23MaxWriteRegisters || unsupported.ContainsKey(unit)) return false;

        // [fc][readAddr:2][readQty:2][writeAddr:2][writeQty:2][writeByteCount] + data: exactly 10 + byteCount.
        var pdu = new byte[10 + bytes.Length];
        pdu[0] = 0x17;
        pdu[1] = (byte)(tag.Address >> 8); pdu[2] = (byte)(tag.Address & 0xFF); // read start
        pdu[3] = (byte)(qty >> 8); pdu[4] = (byte)(qty & 0xFF);                 // read quantity
        pdu[5] = (byte)(tag.Address >> 8); pdu[6] = (byte)(tag.Address & 0xFF); // write start
        pdu[7] = (byte)(qty >> 8); pdu[8] = (byte)(qty & 0xFF);                 // write quantity
        pdu[9] = (byte)bytes.Length;
        Buffer.BlockCopy(bytes, 0, pdu, 10, bytes.Length);

        byte[] resp;
        try
        {
            resp = await transport.SendAsync(unit, pdu, ct).ConfigureAwait(false);
        }
        catch (ModbusException mex) when (mex.ExceptionCode == 0x01)
        {
            if (unsupported.TryAdd(unit, 0))
                _logger.LogInformation(
                    "Modbus unit {Unit} does not implement FC23 (Illegal Function); multi-register writes use FC16 until the driver is re-initialized. Driver={DriverInstanceId}",
                    unit, _driverInstanceId);
            return false;
        }
        catch (Exception ex) when (ex is not ModbusException && !(ex is OperationCanceledException && ct.IsCancellationRequested))
        {
            if (unsupported.TryAdd(unit, 0))
                _logger.LogWarning(ex,
                    "Modbus FC23 write to unit {Unit} failed at the transport; later multi-register writes to it use FC16 until the driver is re-initialized (a redeploy or reconnect restores FC23). Driver={DriverInstanceId}",
                    unit, _driverInstanceId);
            throw;
        }

        // resp = [0x17][byteCount][read-back registers…]
        if (resp.Length < 2 || resp[1] != bytes.Length || resp.Length < 2 + resp[1])
            throw new InvalidDataException(
                $"Modbus FC23 response for {tag.Name} malformed: expected {bytes.Length} read-back bytes, got {(resp.Length < 2 ? -1 : resp[1])}");
        if (!resp.AsSpan(2, bytes.Length).SequenceEqual(bytes)
            && Volatile.Read(ref _refusalWarned).TryAdd("fc23:" + tag.Name, 0))
            _logger.LogWarning(
                "Modbus FC23 read-back of {RawPath} differs from the value written (device logic or clamping changed it); the write was accepted. Driver={DriverInstanceId}",
                tag.Name, _driverInstanceId);
        return true;
    }

    /// <summary>
    ///     Encode an array-typed write value into a contiguous byte block by encoding each
    ///     element with the scalar codec. Caller submits IList / Array of the element CLR type.
    /// </summary>
    private static byte[] EncodeRegisterArray(object? value, ModbusTagDefinition tag)
    {
        var count = tag.ArrayCount!.Value;
        if (value is not System.Collections.IList list)
            throw new ModbusWriteRefusedException(StatusBadTypeMismatch,
                $"Array write to {tag.Name} expects an IList of length {count}; got {value?.GetType().Name ?? "null"}");
        if (list.Count != count)
            throw new ModbusWriteRefusedException(StatusBadOutOfRange,
                $"Array write to {tag.Name} expects {count} elements; got {list.Count}");

        var elementBytes = ElementByteCount(tag);
        var result = new byte[count * elementBytes];
        for (var i = 0; i < count; i++)
        {
            var element = list[i];
            var encoded = EncodeRegister(element, tag);
            if (encoded.Length != elementBytes)
                throw new InvalidOperationException(
                    $"Encoder returned {encoded.Length} bytes for element {i} of {tag.Name}, expected {elementBytes}");
            Buffer.BlockCopy(encoded, 0, result, i * elementBytes, elementBytes);
        }
        return result;
    }

    private static bool[] ToBoolArray(object? value, int expectedCount, string tagName)
    {
        if (value is bool[] direct && direct.Length == expectedCount) return direct;
        if (value is System.Collections.IList list && list.Count == expectedCount)
        {
            var arr = new bool[expectedCount];
            for (var i = 0; i < expectedCount; i++) arr[i] = Convert.ToBoolean(list[i]);
            return arr;
        }
        if (value is System.Collections.IList wrong)
            throw new ModbusWriteRefusedException(StatusBadOutOfRange,
                $"Coil-array write to {tagName} expects {expectedCount} elements; got {wrong.Count}");
        throw new ModbusWriteRefusedException(StatusBadTypeMismatch,
            $"Coil-array write to {tagName} expects a bool[] (or convertible IList) of length {expectedCount}; got {value?.GetType().Name ?? "null"}");
    }

    private static int ElementByteCount(ModbusTagDefinition tag) => tag.DataType switch
    {
        ModbusDataType.Int16 or ModbusDataType.UInt16 or ModbusDataType.Bcd16 => 2,
        ModbusDataType.Int32 or ModbusDataType.UInt32 or ModbusDataType.Float32 or ModbusDataType.Bcd32 => 4,
        ModbusDataType.Int64 or ModbusDataType.UInt64 or ModbusDataType.Float64 => 8,
        // A String element is StringLength chars at 2 per register, rounded up — the read path's width.
        ModbusDataType.String => RegisterCount(tag) * 2,
        _ => throw new ModbusWriteRefusedException(StatusBadNotSupported,
            $"Array writes are not supported for {tag.DataType} tags ({tag.Name})"),
    };

    /// <summary>
    ///     <c>BitInRegister[]</c> write: element i is bit <c>BitIndex</c> of holding register
    ///     <c>Address + i</c> (the read path's layout). One FC03 of the whole span, flip the addressed bit of
    ///     each register, one FC16 back — so the other 15 bits of every register are preserved. Serialised
    ///     per register with the scalar bit-write path (locks taken in ascending address order, so two
    ///     overlapping array writes cannot deadlock). Not atomic against the PLC's own writes between the
    ///     read and the write, exactly like the scalar RMW.
    /// </summary>
    private async Task WriteBitInRegisterArrayAsync(
        IModbusTransport transport, ModbusTagDefinition tag, object? value, CancellationToken ct)
    {
        var count = tag.ArrayCount!.Value;
        var bits = ToBoolArray(value, count, tag.Name);
        var writeCap = _options.MaxRegistersPerWrite == 0 ? (ushort)123 : _options.MaxRegistersPerWrite;
        if (count > writeCap || tag.Address + count - 1 > ushort.MaxValue)
            throw new ModbusWriteRefusedException(StatusBadOutOfRange,
                $"BitInRegister array write of {count} registers to {tag.Name} exceeds MaxRegistersPerWrite={writeCap}");
        if (tag.BitIndex > 15)
            throw new ModbusWriteRefusedException(StatusBadOutOfRange,
                $"BitInRegister bit index {tag.BitIndex} out of range (0-15) for tag {tag.Name}.");

        var locks = new List<SemaphoreSlim>(count);
        try
        {
            for (var i = 0; i < count; i++)
            {
                var l = GetRmwLock((ushort)(tag.Address + i));
                await l.WaitAsync(ct).ConfigureAwait(false);
                locks.Add(l);
            }

            var unit = ResolveUnitId(tag);
            var current = await ReadRegisterBlockAsync(transport, unit, 0x03, tag.Address, (ushort)count, ct).ConfigureAwait(false);
            var payload = new byte[count * 2];
            for (var i = 0; i < count; i++)
            {
                var reg = (ushort)((current[i * 2] << 8) | current[i * 2 + 1]);
                reg = bits[i] ? (ushort)(reg | (1 << tag.BitIndex)) : (ushort)(reg & ~(1 << tag.BitIndex));
                payload[i * 2] = (byte)(reg >> 8);
                payload[i * 2 + 1] = (byte)(reg & 0xFF);
            }
            // [fc][addr:2][qty:2][byteCount] + data: exactly 6 + byteCount.
            var pdu = new byte[6 + payload.Length];
            pdu[0] = 0x10;
            pdu[1] = (byte)(tag.Address >> 8); pdu[2] = (byte)(tag.Address & 0xFF);
            pdu[3] = (byte)(count >> 8); pdu[4] = (byte)(count & 0xFF);
            pdu[5] = (byte)payload.Length;
            Buffer.BlockCopy(payload, 0, pdu, 6, payload.Length);
            await transport.SendAsync(unit, pdu, ct).ConfigureAwait(false);
        }
        finally
        {
            for (var i = locks.Count - 1; i >= 0; i--) locks[i].Release();
        }
    }

    /// <summary>
    ///     Read-modify-write one bit in a holding register. FC03 → bit-swap → FC06. Serialised
    ///     against other bit writes targeting the same register via <see cref="GetRmwLock"/>.
    /// </summary>
    private async Task WriteBitInRegisterAsync(
        IModbusTransport transport, ModbusTagDefinition tag, object? value, CancellationToken ct)
    {
        var bit = tag.BitIndex;
        if (bit > 15)
            throw new InvalidOperationException(
                $"BitInRegister bit index {bit} out of range (0-15) for tag {tag.Name}.");
        var on = Convert.ToBoolean(value);

        var rmwLock = GetRmwLock(tag.Address);
        await rmwLock.WaitAsync(ct).ConfigureAwait(false);
        try
        {
            // FC03 read 1 holding register at tag.Address.
            var readRaw = await ReadRegisterBlockAsync(transport, ResolveUnitId(tag), 0x03, tag.Address, 1, ct).ConfigureAwait(false);
            // readRaw = [hi][lo] — ReadRegisterBlockAsync strips the fc+byte-count header and
            // validates the payload length, so [0] and [1] are always safe to index here.
            var current = (ushort)((readRaw[0] << 8) | readRaw[1]);

            var updated = on
                ? (ushort)(current | (1 << bit))
                : (ushort)(current & ~(1 << bit));

            // FC06 write single holding register.
            var writePdu = new byte[] { 0x06, (byte)(tag.Address >> 8), (byte)(tag.Address & 0xFF),
                                        (byte)(updated >> 8), (byte)(updated & 0xFF) };
            await transport.SendAsync(ResolveUnitId(tag), writePdu, ct).ConfigureAwait(false);
        }
        finally
        {
            rmwLock.Release();
        }
    }

    // ---- ISubscribable (polling overlay via shared engine) ----

    /// <inheritdoc />
    public Task<ISubscriptionHandle> SubscribeAsync(
        IReadOnlyList<string> fullReferences, TimeSpan publishingInterval, CancellationToken cancellationToken) =>
        Task.FromResult(_poll.Subscribe(fullReferences, publishingInterval));

    /// <inheritdoc />
    public async Task UnsubscribeAsync(ISubscriptionHandle handle, CancellationToken cancellationToken)
    {
        // Async teardown: the engine drains the in-flight poll without blocking the caller's
        // thread — this runs inside a DriverInstanceActor mailbox turn.
        await _poll.UnsubscribeAsync(handle).ConfigureAwait(false);
        // Drop any partially-collected cycle buffer so a torn-down subscription leaks nothing.
        // The teardown above awaits the loop task, so no onChange can re-add after this point.
        _cycleBatchItems.TryRemove(handle, out _);
    }

    // ---- IHostConnectivityProbe ----

    /// <inheritdoc />
    public IReadOnlyList<HostConnectivityStatus> GetHostStatuses()
    {
        lock (_probeLock)
            return [new HostConnectivityStatus(HostName, _hostState, _hostStateChangedUtc)];
    }

    /// <summary>
    ///     Host identifier surfaced to <c>IHostConnectivityProbe.GetHostStatuses</c> and the Admin UI.
    ///     Formatted as <c>host:port</c> so multiple Modbus drivers in the same server disambiguate
    ///     by endpoint without needing the driver-instance-id in the Admin dashboard.
    /// </summary>
    public string HostName => $"{_options.Host}:{_options.Port}";

    private async Task ProbeLoopAsync(int generation, IModbusTransport transport, CancellationToken ct)
    {
        // The transport is captured at start; disposal tears the loop down via ct.
        while (!ct.IsCancellationRequested)
        {
            var answered = false;
            try
            {
                using var probeCts = CancellationTokenSource.CreateLinkedTokenSource(ct);
                probeCts.CancelAfter(_options.Probe.Timeout);
                var pdu = new byte[] { 0x03,
                    (byte)(_options.Probe.ProbeAddress >> 8),
                    (byte)(_options.Probe.ProbeAddress & 0xFF), 0x00, 0x01 };
                _ = await transport.SendAsync(_options.UnitId, pdu, probeCts.Token).ConfigureAwait(false);
                answered = true;
            }
            catch (OperationCanceledException) when (ct.IsCancellationRequested)
            {
                return;
            }
            catch (ModbusException mex) when (mex.ExceptionCode is not (0x0A or 0x0B))
            {
                // An exception PDU from the device itself (e.g. a locked probe register) proves the host
                // is up — it answered. Only a gateway reporting its target unreachable (0A/0B) is Stopped.
                answered = true;
            }
            catch
            {
                // transport / timeout / gateway-target failure — treated as Stopped below
            }

            // A probe that finished after teardown cancelled the loop must not raise a stale transition.
            if (ct.IsCancellationRequested) return;
            if (answered) NoteDeviceAnswered(generation);
            TransitionTo(answered ? HostState.Running : HostState.Stopped);

            try { await Task.Delay(_options.Probe.Interval, ct).ConfigureAwait(false); }
            catch (OperationCanceledException) { return; }
        }
    }

    private void TransitionTo(HostState newState)
    {
        HostState old;
        lock (_probeLock)
        {
            old = _hostState;
            if (old == newState) return;
            _hostState = newState;
            _hostStateChangedUtc = DateTime.UtcNow;
        }
        OnHostStatusChanged?.Invoke(this, new HostStatusChangedEventArgs(HostName, old, newState));
    }

    // ---- codec ----

    /// <summary>
    ///     How many 16-bit registers a given tag occupies. Accounts for multi-register logical
    ///     types (Int32/Float32 = 2 regs, Int64/Float64 = 4 regs) and for strings (rounded up
    ///     from 2 chars per register).
    /// </summary>
    /// <param name="tag">Tag definition to measure.</param>
    /// <returns>The number of 16-bit registers the tag occupies.</returns>
    internal static ushort RegisterCount(ModbusTagDefinition tag) => tag.DataType switch
    {
        ModbusDataType.Int16 or ModbusDataType.UInt16 or ModbusDataType.BitInRegister or ModbusDataType.Bcd16 => 1,
        ModbusDataType.Int32 or ModbusDataType.UInt32 or ModbusDataType.Float32 or ModbusDataType.Bcd32 => 2,
        ModbusDataType.Int64 or ModbusDataType.UInt64 or ModbusDataType.Float64 => 4,
        ModbusDataType.String => (ushort)((tag.StringLength + 1) / 2), // 2 chars per register
        _ => throw new InvalidOperationException($"Non-register data type {tag.DataType}"),
    };

    /// <summary>
    ///     Re-order the input bytes into the big-endian (ABCD) layout the decoders expect.
    ///     The four orders refer to how bytes A, B, C, D appear on the wire when reading a
    ///     32-bit value from two consecutive registers (extends pairwise for 64-bit / 4 regs):
    ///     <list type="bullet">
    ///         <item><b>BigEndian (ABCD)</b>: bytes as-is — Modbus spec default.</item>
    ///         <item><b>WordSwap (CDAB)</b>: swap word pairs (full register reversal across the value).</item>
    ///         <item><b>ByteSwap (BADC)</b>: swap bytes within each register.</item>
    ///         <item><b>FullReverse (DCBA)</b>: full byte reversal — equivalent to little-endian.</item>
    ///     </list>
    /// </summary>
    private static byte[] NormalizeWordOrder(ReadOnlySpan<byte> data, ModbusByteOrder order)
    {
        if (order == ModbusByteOrder.BigEndian) return data.ToArray();

        var result = new byte[data.Length];
        var registers = data.Length / 2;

        switch (order)
        {
            case ModbusByteOrder.WordSwap:
                // Reverse register order; bytes within each register stay big-endian.
                for (var word = 0; word < registers; word++)
                {
                    var srcWord = registers - 1 - word;
                    result[word * 2] = data[srcWord * 2];
                    result[word * 2 + 1] = data[srcWord * 2 + 1];
                }
                break;
            case ModbusByteOrder.ByteSwap:
                // Keep register order, swap two bytes within each register.
                for (var word = 0; word < registers; word++)
                {
                    result[word * 2] = data[word * 2 + 1];
                    result[word * 2 + 1] = data[word * 2];
                }
                break;
            case ModbusByteOrder.FullReverse:
                // Full byte-by-byte reversal — equivalent to interpreting the value little-endian.
                for (var i = 0; i < data.Length; i++)
                    result[i] = data[data.Length - 1 - i];
                break;
            default:
                throw new InvalidOperationException($"Unhandled byte order {order}");
        }
        return result;
    }

    /// <summary>Decodes a register value according to the tag's data type.</summary>
    /// <param name="data">Raw register bytes.</param>
    /// <param name="tag">Tag definition specifying the data type.</param>
    /// <returns>The decoded value, boxed as the CLR type matching the tag's data type.</returns>
    internal static object DecodeRegister(ReadOnlySpan<byte> data, ModbusTagDefinition tag)
    {
        switch (tag.DataType)
        {
            case ModbusDataType.Int16: return BinaryPrimitives.ReadInt16BigEndian(data);
            case ModbusDataType.UInt16: return BinaryPrimitives.ReadUInt16BigEndian(data);
            case ModbusDataType.Bcd16:
            {
                var raw = BinaryPrimitives.ReadUInt16BigEndian(data);
                return (int)DecodeBcd(raw, nibbles: 4);
            }
            case ModbusDataType.Bcd32:
            {
                var b = NormalizeWordOrder(data, tag.ByteOrder);
                var raw = BinaryPrimitives.ReadUInt32BigEndian(b);
                return (int)DecodeBcd(raw, nibbles: 8);
            }
            case ModbusDataType.BitInRegister:
            {
                var raw = BinaryPrimitives.ReadUInt16BigEndian(data);
                return (raw & (1 << tag.BitIndex)) != 0;
            }
            case ModbusDataType.Int32:
            {
                var b = NormalizeWordOrder(data, tag.ByteOrder);
                return BinaryPrimitives.ReadInt32BigEndian(b);
            }
            case ModbusDataType.UInt32:
            {
                var b = NormalizeWordOrder(data, tag.ByteOrder);
                return BinaryPrimitives.ReadUInt32BigEndian(b);
            }
            case ModbusDataType.Float32:
            {
                var b = NormalizeWordOrder(data, tag.ByteOrder);
                return BinaryPrimitives.ReadSingleBigEndian(b);
            }
            case ModbusDataType.Int64:
            {
                var b = NormalizeWordOrder(data, tag.ByteOrder);
                return BinaryPrimitives.ReadInt64BigEndian(b);
            }
            case ModbusDataType.UInt64:
            {
                var b = NormalizeWordOrder(data, tag.ByteOrder);
                return BinaryPrimitives.ReadUInt64BigEndian(b);
            }
            case ModbusDataType.Float64:
            {
                var b = NormalizeWordOrder(data, tag.ByteOrder);
                return BinaryPrimitives.ReadDoubleBigEndian(b);
            }
            case ModbusDataType.String:
            {
                // ASCII, 2 chars per register. HighByteFirst (standard) packs the first char in
                // the high byte of each register; LowByteFirst (DL205/DL260) packs the first char
                // in the low byte. Respect StringLength (truncate nul-padded regions).
                var chars = new char[tag.StringLength];
                for (var i = 0; i < tag.StringLength; i++)
                {
                    var regIdx = i / 2;
                    var highByte = data[regIdx * 2];
                    var lowByte  = data[regIdx * 2 + 1];
                    byte b;
                    if (tag.StringByteOrder == ModbusStringByteOrder.HighByteFirst)
                        b = (i % 2 == 0) ? highByte : lowByte;
                    else
                        b = (i % 2 == 0) ? lowByte : highByte;
                    if (b == 0) return new string(chars, 0, i);
                    chars[i] = (char)b;
                }
                return new string(chars);
            }
            default:
                throw new InvalidOperationException($"Non-register data type {tag.DataType}");
        }
    }

    /// <summary>Encodes a value into register bytes according to the tag's data type.</summary>
    /// <param name="value">Value to encode.</param>
    /// <param name="tag">Tag definition specifying the data type.</param>
    /// <returns>The encoded register bytes.</returns>
    internal static byte[] EncodeRegister(object? value, ModbusTagDefinition tag)
    {
        switch (tag.DataType)
        {
            case ModbusDataType.Int16:
            {
                var v = Convert.ToInt16(value);
                var b = new byte[2]; BinaryPrimitives.WriteInt16BigEndian(b, v); return b;
            }
            case ModbusDataType.UInt16:
            {
                var v = Convert.ToUInt16(value);
                var b = new byte[2]; BinaryPrimitives.WriteUInt16BigEndian(b, v); return b;
            }
            case ModbusDataType.Bcd16:
            {
                var v = Convert.ToUInt32(value);
                if (v > 9999) throw new OverflowException($"BCD16 value {v} exceeds 4 decimal digits");
                var raw = (ushort)EncodeBcd(v, nibbles: 4);
                var b = new byte[2]; BinaryPrimitives.WriteUInt16BigEndian(b, raw); return b;
            }
            case ModbusDataType.Bcd32:
            {
                var v = Convert.ToUInt32(value);
                if (v > 99_999_999u) throw new OverflowException($"BCD32 value {v} exceeds 8 decimal digits");
                var raw = EncodeBcd(v, nibbles: 8);
                var b = new byte[4]; BinaryPrimitives.WriteUInt32BigEndian(b, raw);
                return NormalizeWordOrder(b, tag.ByteOrder);
            }
            case ModbusDataType.Int32:
            {
                var v = Convert.ToInt32(value);
                var b = new byte[4]; BinaryPrimitives.WriteInt32BigEndian(b, v);
                return NormalizeWordOrder(b, tag.ByteOrder);
            }
            case ModbusDataType.UInt32:
            {
                var v = Convert.ToUInt32(value);
                var b = new byte[4]; BinaryPrimitives.WriteUInt32BigEndian(b, v);
                return NormalizeWordOrder(b, tag.ByteOrder);
            }
            case ModbusDataType.Float32:
            {
                var v = Convert.ToSingle(value);
                var b = new byte[4]; BinaryPrimitives.WriteSingleBigEndian(b, v);
                return NormalizeWordOrder(b, tag.ByteOrder);
            }
            case ModbusDataType.Int64:
            {
                var v = Convert.ToInt64(value);
                var b = new byte[8]; BinaryPrimitives.WriteInt64BigEndian(b, v);
                return NormalizeWordOrder(b, tag.ByteOrder);
            }
            case ModbusDataType.UInt64:
            {
                var v = Convert.ToUInt64(value);
                var b = new byte[8]; BinaryPrimitives.WriteUInt64BigEndian(b, v);
                return NormalizeWordOrder(b, tag.ByteOrder);
            }
            case ModbusDataType.Float64:
            {
                var v = Convert.ToDouble(value);
                var b = new byte[8]; BinaryPrimitives.WriteDoubleBigEndian(b, v);
                return NormalizeWordOrder(b, tag.ByteOrder);
            }
            case ModbusDataType.String:
            {
                var s = Convert.ToString(value) ?? string.Empty;
                var regs = (tag.StringLength + 1) / 2;
                var b = new byte[regs * 2];
                for (var i = 0; i < tag.StringLength && i < s.Length; i++)
                {
                    var regIdx = i / 2;
                    var destIdx = tag.StringByteOrder == ModbusStringByteOrder.HighByteFirst
                        ? (i % 2 == 0 ? regIdx * 2 : regIdx * 2 + 1)
                        : (i % 2 == 0 ? regIdx * 2 + 1 : regIdx * 2);
                    b[destIdx] = (byte)s[i];
                }
                // remaining bytes stay 0 — nul-padded per PLC convention
                return b;
            }
            case ModbusDataType.BitInRegister:
                // Reached only if BitInRegister is somehow passed outside the HoldingRegisters
                // path. Normal BitInRegister writes dispatch through WriteBitInRegisterAsync via
                // the RMW shortcut in WriteOneAsync.
                throw new InvalidOperationException(
                    "BitInRegister writes must go through WriteBitInRegisterAsync (HoldingRegisters region only).");
            default:
                throw new InvalidOperationException($"Non-register data type {tag.DataType}");
        }
    }

    /// <summary>
    ///     Map a Modbus logical type to the driver-agnostic <see cref="DriverDataType"/> used
    ///     by the address-space builder.
    /// </summary>
    /// <param name="t">Modbus logical data type to map.</param>
    /// <returns>The corresponding driver-agnostic data type.</returns>
    internal static DriverDataType MapDataType(ModbusDataType t) => t switch
    {
        ModbusDataType.Bool or ModbusDataType.BitInRegister => DriverDataType.Boolean,
        ModbusDataType.Int16 or ModbusDataType.Int32 => DriverDataType.Int32,
        ModbusDataType.UInt16 or ModbusDataType.UInt32 => DriverDataType.Int32,
        ModbusDataType.Int64 => DriverDataType.Int64,
        ModbusDataType.UInt64 => DriverDataType.UInt64,
        ModbusDataType.Float32 => DriverDataType.Float32,
        ModbusDataType.Float64 => DriverDataType.Float64,
        ModbusDataType.String => DriverDataType.String,
        ModbusDataType.Bcd16 or ModbusDataType.Bcd32 => DriverDataType.Int32,
        _ => DriverDataType.Int32,
    };

    /// <summary>
    ///     Decode an N-nibble binary-coded-decimal value. Each nibble of <paramref name="raw"/>
    ///     encodes one decimal digit (most-significant nibble first). Rejects nibbles &gt; 9 —
    ///     the hardware sometimes produces garbage during transitions and silent non-BCD reads
    ///     would quietly corrupt the caller's data.
    /// </summary>
    /// <param name="raw">Raw BCD value.</param>
    /// <param name="nibbles">Number of nibbles to decode.</param>
    /// <returns>The decoded decimal value.</returns>
    internal static uint DecodeBcd(uint raw, int nibbles)
    {
        uint result = 0;
        for (var i = nibbles - 1; i >= 0; i--)
        {
            var digit = (raw >> (i * 4)) & 0xF;
            if (digit > 9)
                throw new InvalidDataException(
                    $"Non-BCD nibble 0x{digit:X} at position {i} of raw=0x{raw:X}");
            result = result * 10 + digit;
        }
        return result;
    }

    /// <summary>
    ///     Encode a decimal value as N-nibble BCD. Caller is responsible for range-checking
    ///     against the nibble capacity (10^nibbles - 1).
    /// </summary>
    /// <param name="value">Decimal value to encode.</param>
    /// <param name="nibbles">Number of nibbles to encode.</param>
    /// <returns>The encoded N-nibble BCD value.</returns>
    internal static uint EncodeBcd(uint value, int nibbles)
    {
        uint result = 0;
        for (var i = 0; i < nibbles; i++)
        {
            var digit = value % 10;
            result |= digit << (i * 4);
            value /= 10;
        }
        return result;
    }


    private const uint StatusBadInternalError = 0x80020000u;
    private const uint StatusBadNodeIdUnknown = 0x80340000u;
    private const uint StatusBadNotWritable = 0x803B0000u;
    private const uint StatusBadOutOfRange = 0x803C0000u;
    private const uint StatusBadNotSupported = 0x803D0000u;
    private const uint StatusBadDeviceFailure = 0x808B0000u;
    private const uint StatusBadCommunicationError = 0x80050000u;
    private const uint StatusBadDecodingError = 0x80070000u;
    private const uint StatusBadTimeout = 0x800A0000u;
    private const uint StatusBadTypeMismatch = 0x80740000u;

    /// <summary>
    ///     Map a server-returned Modbus exception code to the most informative OPC UA
    ///     StatusCode. Keeps the driver's outward-facing status surface aligned with what a
    ///     Modbus engineer would expect when reading the spec: exception 02 (Illegal Data
    ///     Address) surfaces as BadOutOfRange so clients can distinguish "tag wrong" from
    ///     generic BadInternalError, exception 04 (Server Failure) as BadDeviceFailure so
    ///     operators see a CPU-mode problem rather than a driver bug, etc. Per
    ///     <c>docs/v2/dl205.md</c>, DL205/DL260 returns only codes 01-04 — no proprietary
    ///     extensions.
    /// </summary>
    /// <param name="exceptionCode">Modbus exception code.</param>
    /// <returns>The mapped OPC UA StatusCode value.</returns>
    internal static uint MapModbusExceptionToStatus(byte exceptionCode) => exceptionCode switch
    {
        0x01 => StatusBadNotSupported,     // Illegal Function — FC not in supported list
        0x02 => StatusBadOutOfRange,       // Illegal Data Address — register outside mapped range
        0x03 => StatusBadOutOfRange,       // Illegal Data Value — quantity over per-FC cap
        0x04 => StatusBadDeviceFailure,    // Server Failure — CPU in PROGRAM mode during protected write
        0x05 or 0x06 => StatusBadDeviceFailure, // Acknowledge / Server Busy — long-running op / busy
        0x0A or 0x0B => StatusBadCommunicationError, // Gateway path unavailable / target failed to respond
        _ => StatusBadInternalError,
    };

    /// <summary>Releases resources used by the driver.</summary>
    public void Dispose() => DisposeAsync().AsTask().GetAwaiter().GetResult();

    /// <summary>
    ///     DisposeAsync must perform the same teardown as ShutdownAsync so
    ///     callers that use <c>await using</c> (without an explicit <c>ShutdownAsync</c>) do not
    ///     leak the probe loop, re-probe loop, and poll-engine background tasks. Shares
    ///     <see cref="TeardownAsync"/> with <see cref="ShutdownAsync"/> to keep them in sync.
    /// </summary>
    /// <returns>A task that represents the asynchronous operation.</returns>
    public async ValueTask DisposeAsync()
    {
        // Dispose supersedes any in-flight (abandoned) initialize up front, even when it then has to
        // bypass the gate: that initialize will find its generation moved on and release its own
        // transport instead of publishing it after this teardown.
        int generation;
        DateTime? lastRead;
        lock (_stateLock)
        {
            generation = ++_generation;
            lastRead = _health.LastSuccessfulRead;
        }
        if (await _lifecycleGate.WaitAsync(LifecycleGateTimeout).ConfigureAwait(false))
        {
            try
            {
                await TeardownAsync().ConfigureAwait(false);
            }
            finally
            {
                _lifecycleGate.Release();
            }
        }
        else
        {
            _logger.LogWarning(
                "Modbus lifecycle gate still held at dispose; tearing the transport down anyway. Driver={DriverInstanceId}",
                _driverInstanceId);
            await TeardownAsync().ConfigureAwait(false);
        }

        // Dispose's own final health write. Bumping the generation above drops a still-running shutdown's
        // Unknown write, so without this a disposed driver kept reporting whatever it last was (e.g. Healthy).
        WriteLifecycleHealth(generation, new DriverHealth(DriverState.Unknown, lastRead, null));
    }

    /// <summary>
    ///     Shared teardown helper used by both <see cref="ShutdownAsync"/> and
    ///     <see cref="DisposeAsync"/>. Cancels both background loops, disposes the poll engine,
    ///     and disposes the transport. Idempotent — safe to call more than once.
    /// </summary>
    private async Task TeardownAsync()
    {
        await StopBackgroundLoopsAsync().ConfigureAwait(false);

        // Drain the poll loops BEFORE dropping the tables and caches they read, so no in-flight cycle can
        // re-seed a cache after it was cleared.
        await _poll.DisposeAsync().ConfigureAwait(false);
        // After the engine's loops are drained, no onChange can re-populate the per-cycle buffers.
        _cycleBatchItems.Clear();

        IModbusTransport? transport;
        lock (_stateLock)
        {
            transport = _transport;
            _transport = null;
            // Swap, never .Clear() in place: a reader that captured the old table keeps a consistent view.
            Volatile.Write(ref _tagsByRawPath, new Dictionary<string, ModbusTagDefinition>(StringComparer.Ordinal));
        }
        _resolver.Clear(); // no-op in v3 (the resolver reads the live table by closure); kept for symmetry
        _lastPublishedByRef.Clear();
        lock (_lastWrittenLock) _lastWrittenByRef.Clear();
        lock (_autoProhibitedLock) _autoProhibited.Clear();

        if (transport is not null) await transport.DisposeAsync().ConfigureAwait(false);
    }
}