using Akka.Actor;
using Akka.Event;
using ScadaLink.Commons.Interfaces.Protocol;
using ScadaLink.Commons.Messages.DataConnection;
using ScadaLink.Commons.Types.Enums;
using ScadaLink.HealthMonitoring;
using ScadaLink.SiteEventLogging;

namespace ScadaLink.DataConnectionLayer.Actors;

/// <summary>
/// WP-6: Connection actor using Akka.NET Become/Stash pattern for lifecycle state machine.
///
/// States:
/// - Connecting: stash subscribe/write requests; attempts connection
/// - Connected: unstash and process all requests
/// - Reconnecting: push bad quality for all subscribed tags, stash new requests,
///   fixed-interval reconnect
///
/// WP-9: Auto-reconnect with bad quality on disconnect.
/// WP-10: Transparent re-subscribe after reconnection.
/// WP-11: Write-back support (synchronous failure to caller, no S&amp;F).
/// WP-12: Tag path resolution with retry.
/// WP-13: Health reporting (connection status + tag resolution counts).
/// WP-14: Subscription lifecycle (register on create, cleanup on stop).
/// </summary>
public class DataConnectionActor : UntypedActor, IWithStash, IWithTimers
{
    public enum ActiveEndpoint { Primary, Backup }

    private readonly ILoggingAdapter _log = Context.GetLogger();
    private readonly string _connectionName;
    private IDataConnection _adapter;
    private readonly DataConnectionOptions _options;
    private readonly ISiteHealthCollector _healthCollector;
    private readonly IDataConnectionFactory _factory;
    private readonly string _protocolType;
    private readonly ISiteEventLogger? _siteEventLogger;

    public IStash Stash { get; set; } = null!;
    public ITimerScheduler Timers { get; set; } = null!;

    /// <summary>
    /// Active subscriptions: instanceUniqueName → set of tag paths.
    /// </summary>
    private readonly Dictionary<string, HashSet<string>> _subscriptionsByInstance = new();

    /// <summary>
    /// Subscription IDs returned by the adapter: tagPath → subscriptionId.
    /// </summary>
    private readonly Dictionary<string, string> _subscriptionIds = new();

    /// <summary>
    /// Tags whose path resolution failed and are awaiting retry.
    /// </summary>
    private readonly HashSet<string> _unresolvedTags = new();

    /// <summary>
    /// DataConnectionLayer-010: tags whose retry SubscribeAsync is currently in flight.
    /// They are excluded from the next retry tick so a slow attempt is not duplicated
    /// (which would leak monitored items / subscription ids).
    /// </summary>
    private readonly HashSet<string> _resolutionInFlight = new();

    /// <summary>
    /// Subscribers: instanceUniqueName → IActorRef (the Instance Actor).
    /// </summary>
    private readonly Dictionary<string, IActorRef> _subscribers = new();

    /// <summary>
    /// Tracks total subscribed and resolved tags for health reporting.
    /// </summary>
    private int _totalSubscribed;
    private int _resolvedTags;

    private int _tagsGoodQuality;
    private int _tagsBadQuality;
    private int _tagsUncertainQuality;
    private readonly Dictionary<string, QualityCode> _lastTagQuality = new();

    private IDictionary<string, string> _connectionDetails;
    private readonly IDictionary<string, string> _primaryConfig;
    private readonly IDictionary<string, string>? _backupConfig;
    private readonly int _failoverRetryCount;
    private ActiveEndpoint _activeEndpoint = ActiveEndpoint.Primary;
    private int _consecutiveFailures;
    private int _consecutiveUnstableDisconnects;
    private DateTimeOffset _lastConnectedAt;

    /// <summary>
    /// DataConnectionLayer-011: monotonically increasing tag that identifies the
    /// current adapter instance. Subscription callbacks capture the generation in
    /// effect when they were created; a <see cref="TagValueReceived"/> whose
    /// generation no longer matches comes from a disposed adapter and is dropped so
    /// stale pre-failover device data is never forwarded to Instance Actors.
    /// </summary>
    private int _adapterGeneration;

    /// <summary>
    /// Captured Self reference for use from non-actor threads (event handlers, callbacks).
    /// Akka.NET's Self property is only valid inside the actor's message loop.
    /// </summary>
    private IActorRef _self = null!;

    public DataConnectionActor(
        string connectionName,
        IDataConnection adapter,
        DataConnectionOptions options,
        ISiteHealthCollector healthCollector,
        IDataConnectionFactory factory,
        string protocolType,
        IDictionary<string, string>? primaryConfig = null,
        IDictionary<string, string>? backupConfig = null,
        int failoverRetryCount = 3,
        ISiteEventLogger? siteEventLogger = null)
    {
        _connectionName = connectionName;
        _adapter = adapter;
        _options = options;
        _healthCollector = healthCollector;
        _factory = factory;
        _protocolType = protocolType;
        _primaryConfig = primaryConfig ?? new Dictionary<string, string>();
        _backupConfig = backupConfig;
        _failoverRetryCount = failoverRetryCount;
        _siteEventLogger = siteEventLogger;
        _connectionDetails = _primaryConfig;
    }

    protected override void PreStart()
    {
        _log.Info("DataConnectionActor [{0}] starting in Connecting state", _connectionName);

        // Capture Self for use from non-actor threads (event handlers, callbacks).
        // Akka.NET's Self property is only valid inside the actor's message loop.
        _self = Self;

        // Listen for unexpected adapter disconnections
        _adapter.Disconnected += OnAdapterDisconnected;

        BecomeConnecting();
    }

    private void OnAdapterDisconnected()
    {
        // Marshal the event onto the actor's message loop using captured _self reference.
        // This runs on a background thread (gRPC stream reader), so Self would throw.
        _self.Tell(new AdapterDisconnected());
    }

    protected override void PostStop()
    {
        _log.Info("DataConnectionActor [{0}] stopping — disposing adapter", _connectionName);
        _adapter.Disconnected -= OnAdapterDisconnected;
        _ = _adapter.DisposeAsync().AsTask();
    }

    protected override void OnReceive(object message)
    {
        // Default handler — should not be reached due to Become
        Unhandled(message);
    }

    // ── Connecting State ──

    private void BecomeConnecting()
    {
        _log.Info("[{0}] Entering Connecting state", _connectionName);
        _healthCollector.UpdateConnectionHealth(_connectionName, ConnectionHealth.Connecting);
        _healthCollector.UpdateConnectionEndpoint(_connectionName, "Connecting");
        Become(Connecting);
        Self.Tell(new AttemptConnect());
    }

    private void Connecting(object message)
    {
        switch (message)
        {
            case AttemptConnect:
                HandleAttemptConnect();
                break;
            case ConnectResult result:
                HandleConnectResult(result);
                break;
            case SubscribeTagsRequest:
            case WriteTagRequest:
            case UnsubscribeTagsRequest:
                Stash.Stash();
                break;
            case SubscribeCompleted sc:
                // A subscribe started while Connected can complete after a transition;
                // apply it so its state survives into the next ReSubscribeAll.
                HandleSubscribeCompleted(sc);
                break;
            case GetHealthReport:
                ReplyWithHealthReport();
                break;
            default:
                Unhandled(message);
                break;
        }
    }

    // ── Connected State ──

    private void BecomeConnected()
    {
        _log.Info("[{0}] Entering Connected state", _connectionName);
        _lastConnectedAt = DateTimeOffset.UtcNow;
        _healthCollector.UpdateConnectionHealth(_connectionName, ConnectionHealth.Connected);
        _healthCollector.UpdateTagResolution(_connectionName, _totalSubscribed, _resolvedTags);
        var endpointLabel = _backupConfig == null ? "Connected" : $"Connected to {_activeEndpoint.ToString().ToLower()}";
        _healthCollector.UpdateConnectionEndpoint(_connectionName, endpointLabel);
        Become(Connected);
        Stash.UnstashAll();
    }

    private void Connected(object message)
    {
        switch (message)
        {
            case SubscribeTagsRequest req:
                HandleSubscribe(req);
                break;
            case SubscribeCompleted sc:
                // In Connected state, a connection-level subscribe failure must drive
                // the reconnection state machine (DataConnectionLayer-004).
                if (HandleSubscribeCompleted(sc))
                {
                    _log.Warning("[{0}] Connection-level subscribe failure — entering Reconnecting", _connectionName);
                    BecomeReconnecting();
                }
                break;
            case UnsubscribeTagsRequest req:
                HandleUnsubscribe(req);
                break;
            case WriteTagRequest req:
                HandleWrite(req);
                break;
            case TagValueReceived tvr:
                HandleTagValueReceived(tvr);
                break;
            case TagResolutionSucceeded trs:
                HandleTagResolutionSucceeded(trs);
                break;
            case TagResolutionFailed trf:
                HandleTagResolutionFailed(trf);
                break;
            case AdapterDisconnected:
                HandleDisconnect();
                break;
            case RetryTagResolution:
                HandleRetryTagResolution();
                break;
            case GetHealthReport:
                ReplyWithHealthReport();
                break;
            default:
                Unhandled(message);
                break;
        }
    }

    // ── Reconnecting State ──

    private void BecomeReconnecting()
    {
        _log.Warning("[{0}] Entering Reconnecting state", _connectionName);
        _healthCollector.UpdateConnectionHealth(_connectionName, ConnectionHealth.Disconnected);
        _healthCollector.UpdateConnectionEndpoint(_connectionName, "Disconnected");

        // Track unstable connections toward failover.
        // If we were connected for less than the stability threshold, this counts
        // as an unstable cycle (e.g., connect succeeded but heartbeat went stale).
        var connectionDuration = DateTimeOffset.UtcNow - _lastConnectedAt;
        if (_lastConnectedAt != default && connectionDuration < _options.StableConnectionThreshold)
        {
            _consecutiveUnstableDisconnects++;
            _log.Warning("[{0}] Unstable connection (lasted {1:F0}s) — consecutive unstable disconnects: {2}/{3}",
                _connectionName, connectionDuration.TotalSeconds, _consecutiveUnstableDisconnects,
                _backupConfig != null ? _failoverRetryCount : 0);
        }
        else
        {
            _consecutiveUnstableDisconnects = 0;
        }

        // Failover if we keep connecting and going stale repeatedly
        if (_backupConfig != null && _consecutiveUnstableDisconnects >= _failoverRetryCount)
        {
            var previousEndpoint = _activeEndpoint;
            _activeEndpoint = _activeEndpoint == ActiveEndpoint.Primary
                ? ActiveEndpoint.Backup
                : ActiveEndpoint.Primary;
            _consecutiveUnstableDisconnects = 0;
            _consecutiveFailures = 0;

            var newConfig = _activeEndpoint == ActiveEndpoint.Primary
                ? _primaryConfig
                : _backupConfig;

            // Dispose old adapter
            _adapter.Disconnected -= OnAdapterDisconnected;
            _ = _adapter.DisposeAsync().AsTask();

            // Create new adapter for the target endpoint
            _adapter = _factory.Create(_protocolType, newConfig);
            _connectionDetails = newConfig;
            _adapter.Disconnected += OnAdapterDisconnected;

            // DataConnectionLayer-011: new adapter — bump the generation so callbacks
            // from the disposed adapter are recognised as stale and dropped.
            _adapterGeneration++;

            _log.Warning("[{0}] Failing over from {1} to {2} (unstable connection pattern)",
                _connectionName, previousEndpoint, _activeEndpoint);

            if (_siteEventLogger != null)
            {
                _ = _siteEventLogger.LogEventAsync(
                    "connection", "Warning", null, _connectionName,
                    $"Failover from {previousEndpoint} to {_activeEndpoint} (unstable connection)",
                    $"Connection lasted {connectionDuration.TotalSeconds:F0}s, threshold {_options.StableConnectionThreshold.TotalSeconds:F0}s");
            }
        }

        // Log disconnect to site event log
        if (_siteEventLogger != null)
        {
            _ = _siteEventLogger.LogEventAsync(
                "connection", "Warning", null, _connectionName,
                $"Connection lost — entering reconnect cycle", null);
        }

        Become(Reconnecting);

        // WP-9: Push bad quality for all subscribed tags on disconnect
        PushBadQualityForAllTags();

        // Schedule reconnect attempt
        Timers.StartSingleTimer("reconnect", new AttemptConnect(), _options.ReconnectInterval);
    }

    private void Reconnecting(object message)
    {
        switch (message)
        {
            case AttemptConnect:
                HandleAttemptConnect();
                break;
            case ConnectResult result:
                HandleReconnectResult(result);
                break;
            case SubscribeTagsRequest:
            case WriteTagRequest:
                Stash.Stash();
                break;
            case UnsubscribeTagsRequest req:
                // Allow unsubscribe even during reconnect (for cleanup on instance stop)
                HandleUnsubscribe(req);
                break;
            case TagValueReceived:
                // Ignore — stale callback from previous connection
                break;
            case TagResolutionSucceeded:
            case TagResolutionFailed:
                // Ignore — stale results from previous connection; ReSubscribeAll runs after reconnect
                break;
            case SubscribeCompleted sc:
                // A subscribe started while Connected can complete after a transition;
                // apply it so its state survives into the next ReSubscribeAll.
                HandleSubscribeCompleted(sc);
                break;
            case GetHealthReport:
                ReplyWithHealthReport();
                break;
            default:
                Unhandled(message);
                break;
        }
    }

    // ── Connection Management ──

    private void HandleAttemptConnect()
    {
        _log.Debug("[{0}] Attempting connection...", _connectionName);
        var self = Self;
        _adapter.ConnectAsync(_connectionDetails).ContinueWith(t =>
        {
            if (t.IsCompletedSuccessfully)
                return new ConnectResult(true, null);
            return new ConnectResult(false, t.Exception?.GetBaseException().Message);
        }).PipeTo(self);
    }

    private void HandleConnectResult(ConnectResult result)
    {
        if (result.Success)
        {
            _log.Info("[{0}] Connection established", _connectionName);
            BecomeConnected();
        }
        else
        {
            _log.Warning("[{0}] Connection failed: {1}. Retrying in {2}s",
                _connectionName, result.Error, _options.ReconnectInterval.TotalSeconds);
            Timers.StartSingleTimer("reconnect", new AttemptConnect(), _options.ReconnectInterval);
        }
    }

    private void HandleReconnectResult(ConnectResult result)
    {
        if (result.Success)
        {
            _log.Info("[{0}] Reconnected successfully on {1} endpoint", _connectionName, _activeEndpoint);
            _consecutiveFailures = 0;

            // Log restoration event to site event log
            if (_siteEventLogger != null)
            {
                _ = _siteEventLogger.LogEventAsync(
                    "connection", "Info", null, _connectionName,
                    $"Connection restored on {_activeEndpoint} endpoint", null);
            }

            // WP-10: Transparent re-subscribe — re-establish all active subscriptions
            ReSubscribeAll();

            BecomeConnected();
        }
        else
        {
            _consecutiveFailures++;

            // Failover: switch endpoint after exhausting retry count (only if backup is configured)
            if (_backupConfig != null && _consecutiveFailures >= _failoverRetryCount)
            {
                var previousEndpoint = _activeEndpoint;
                _activeEndpoint = _activeEndpoint == ActiveEndpoint.Primary
                    ? ActiveEndpoint.Backup
                    : ActiveEndpoint.Primary;
                _consecutiveFailures = 0;

                var newConfig = _activeEndpoint == ActiveEndpoint.Primary
                    ? _primaryConfig
                    : _backupConfig;

                // Dispose old adapter (fire-and-forget — don't await in actor context)
                _adapter.Disconnected -= OnAdapterDisconnected;
                _ = _adapter.DisposeAsync().AsTask();

                // Create new adapter for the target endpoint
                _adapter = _factory.Create(_protocolType, newConfig);
                _connectionDetails = newConfig;

                // Wire disconnect handler on new adapter
                _adapter.Disconnected += OnAdapterDisconnected;

                // DataConnectionLayer-011: new adapter — bump the generation so callbacks
                // from the disposed adapter are recognised as stale and dropped.
                _adapterGeneration++;

                _log.Warning("[{0}] Failing over from {1} to {2}",
                    _connectionName, previousEndpoint, _activeEndpoint);

                // Log failover event to site event log
                if (_siteEventLogger != null)
                {
                    _ = _siteEventLogger.LogEventAsync(
                        "connection", "Warning", null, _connectionName,
                        $"Failover from {previousEndpoint} to {_activeEndpoint}",
                        $"After {_failoverRetryCount} consecutive failures");
                }
            }
            else
            {
                var retryLimit = _backupConfig != null ? _failoverRetryCount.ToString() : "∞";
                _log.Warning("[{0}] Reconnect failed: {1}. Retrying in {2}s (attempt {3}/{4})",
                    _connectionName, result.Error, _options.ReconnectInterval.TotalSeconds,
                    _consecutiveFailures, retryLimit);
            }

            Timers.StartSingleTimer("reconnect", new AttemptConnect(), _options.ReconnectInterval);
        }
    }

    private void HandleDisconnect()
    {
        _log.Warning("[{0}] AdapterDisconnected message received — transitioning to Reconnecting", _connectionName);
        BecomeReconnecting();
    }

    // ── Subscription Management (WP-14) ──

    private void HandleSubscribe(SubscribeTagsRequest request)
    {
        _log.Debug("[{0}] Subscribing {1} tags for instance {2}",
            _connectionName, request.TagPaths.Count, request.InstanceUniqueName);

        _subscribers[request.InstanceUniqueName] = Sender;

        if (!_subscriptionsByInstance.ContainsKey(request.InstanceUniqueName))
            _subscriptionsByInstance[request.InstanceUniqueName] = new HashSet<string>();

        var self = Self;
        var sender = Sender;
        // DataConnectionLayer-011: capture the current adapter generation so callbacks
        // from this adapter can be distinguished from a later (post-failover) adapter.
        var generation = _adapterGeneration;

        // Snapshot the already-subscribed tag set on the actor thread. The background
        // task below must NOT read or mutate actor state — it performs only adapter
        // I/O and reports results back via a SubscribeCompleted message, which is
        // applied to actor state on the actor thread (see HandleSubscribeCompleted).
        var alreadySubscribed = new HashSet<string>(_subscriptionIds.Keys);

        Task.Run(async () =>
        {
            var results = new List<SubscribeTagResult>(request.TagPaths.Count);
            var tagsToSeed = new List<string>();

            foreach (var tagPath in request.TagPaths)
            {
                if (alreadySubscribed.Contains(tagPath))
                {
                    // Already subscribed by another instance — just track for this one.
                    results.Add(new SubscribeTagResult(tagPath, AlreadySubscribed: true, Success: true, null, null));
                    tagsToSeed.Add(tagPath);
                    continue;
                }

                try
                {
                    var subId = await _adapter.SubscribeAsync(tagPath, (path, value) =>
                    {
                        self.Tell(new TagValueReceived(path, value, generation));
                    });
                    results.Add(new SubscribeTagResult(tagPath, AlreadySubscribed: false, Success: true, subId, null));
                    tagsToSeed.Add(tagPath);
                }
                catch (Exception ex)
                {
                    // DataConnectionLayer-004: distinguish a connection-level fault
                    // (adapter not connected / transport down) from a genuine
                    // node-not-found. Connection-level faults must drive the
                    // reconnection state machine, not be retried as unresolved tags.
                    var connectionLevel = IsConnectionLevelFailure(ex);
                    results.Add(new SubscribeTagResult(
                        tagPath, AlreadySubscribed: false, Success: false, null, ex.Message,
                        ConnectionLevelFailure: connectionLevel));
                }
            }

            // Initial read — seed current values for resolved tags so the Instance Actor
            // doesn't stay Uncertain until the next OPC UA data change notification.
            // Tell is thread-safe, so seeded values are delivered directly as messages.
            foreach (var tagPath in tagsToSeed)
            {
                try
                {
                    var readResult = await _adapter.ReadAsync(tagPath);
                    if (readResult.Success && readResult.Value != null)
                    {
                        self.Tell(new TagValueReceived(tagPath, readResult.Value, generation));
                    }
                }
                catch
                {
                    // Best-effort — subscription will deliver subsequent changes
                }
            }

            return new SubscribeCompleted(request, sender, results);
        }).PipeTo(self);
    }

    /// <summary>
    /// Applies the result of an asynchronous subscribe on the actor thread. ALL mutation
    /// of subscription state and counters happens here — never on the background task —
    /// so the actor model's single-threaded state guarantee holds.
    /// Returns <c>true</c> if any tag failed at connection level (DataConnectionLayer-004),
    /// signalling the caller (only the Connected state) to enter Reconnecting.
    /// </summary>
    private bool HandleSubscribeCompleted(SubscribeCompleted msg)
    {
        var instanceName = msg.Request.InstanceUniqueName;
        if (!_subscriptionsByInstance.TryGetValue(instanceName, out var instanceTags))
        {
            // The instance was unsubscribed while the subscribe I/O was in flight.
            instanceTags = new HashSet<string>();
            _subscriptionsByInstance[instanceName] = instanceTags;
        }

        // DataConnectionLayer-004: if any tag failed because the adapter is not
        // connected (a connection-level fault), the subscribe needs the reconnection
        // state machine, not the tag-resolution retry. Drive a disconnect and let the
        // request be re-stashed/retried after reconnect via ReSubscribeAll.
        var connectionLevelFailure = msg.Results.Any(r => !r.Success && r.ConnectionLevelFailure);

        foreach (var result in msg.Results)
        {
            instanceTags.Add(result.TagPath);

            // Re-check against current state: another subscribe may have resolved the
            // same tag while this request's I/O was in flight.
            if (result.AlreadySubscribed || _subscriptionIds.ContainsKey(result.TagPath))
                continue;

            if (result.Success)
            {
                _subscriptionIds[result.TagPath] = result.SubscriptionId!;
                _totalSubscribed++;
                _resolvedTags++;
            }
            else if (result.ConnectionLevelFailure)
            {
                // Connection-level fault — do not count as an unresolved tag.
                // ReSubscribeAll after reconnect derives the tag from
                // _subscriptionsByInstance (already updated above).
                _log.Warning("[{0}] Subscribe for {1} failed at connection level: {2}",
                    _connectionName, result.TagPath, result.Error);
            }
            else
            {
                // WP-12: genuine tag resolution failure — mark unresolved so the
                // periodic retry timer picks it up.
                _unresolvedTags.Add(result.TagPath);
                _totalSubscribed++;
                _log.Debug("[{0}] Tag resolution failed for {1}: {2}",
                    _connectionName, result.TagPath, result.Error);

                // DataConnectionLayer-004 / design doc Tag Path Resolution step 2:
                // mark the attribute quality `bad` so the Instance Actor sees a
                // signal rather than staying Uncertain indefinitely.
                if (_subscribers.TryGetValue(instanceName, out var subscriber))
                {
                    subscriber.Tell(new TagValueUpdate(
                        _connectionName, result.TagPath, null, QualityCode.Bad, DateTimeOffset.UtcNow));
                }
            }
        }

        // Start the tag-resolution retry timer if any tags are unresolved.
        if (_unresolvedTags.Count > 0)
        {
            Timers.StartPeriodicTimer(
                "tag-resolution-retry",
                new RetryTagResolution(),
                _options.TagResolutionRetryInterval,
                _options.TagResolutionRetryInterval);
        }

        msg.ReplyTo.Tell(new SubscribeTagsResponse(
            msg.Request.CorrelationId, instanceName, true, null, DateTimeOffset.UtcNow));

        // The caller (Connected state only) decides whether to enter Reconnecting.
        // In Connecting/Reconnecting the connection is not established anyway, so the
        // existing reconnect cycle handles recovery without a re-trigger here.
        return connectionLevelFailure;
    }

    /// <summary>
    /// DataConnectionLayer-004: classifies a subscribe exception as a connection-level
    /// fault (adapter not connected / transport down) versus a genuine tag-resolution
    /// failure (the node does not exist on the device). Connection-level faults must
    /// drive the reconnection state machine; resolution failures are retried on the
    /// tag-resolution timer.
    /// </summary>
    private static bool IsConnectionLevelFailure(Exception ex)
    {
        var baseEx = ex is AggregateException agg ? agg.GetBaseException() : ex;
        return baseEx is InvalidOperationException
            or System.Net.Sockets.SocketException
            or TimeoutException
            or System.IO.IOException;
    }

    private void HandleUnsubscribe(UnsubscribeTagsRequest request)
    {
        _log.Debug("[{0}] Unsubscribing all tags for instance {1}",
            _connectionName, request.InstanceUniqueName);

        if (!_subscriptionsByInstance.TryGetValue(request.InstanceUniqueName, out var tags))
            return;

        // WP-14: Cleanup on Instance Actor stop
        foreach (var tagPath in tags)
        {
            // Check if any other instance is still subscribed to this tag
            var otherSubscribers = _subscriptionsByInstance
                .Where(kvp => kvp.Key != request.InstanceUniqueName && kvp.Value.Contains(tagPath))
                .Any();

            if (!otherSubscribers && _subscriptionIds.TryGetValue(tagPath, out var subId))
            {
                _ = _adapter.UnsubscribeAsync(subId);
                _subscriptionIds.Remove(tagPath);
                _unresolvedTags.Remove(tagPath);
                _resolutionInFlight.Remove(tagPath);
                _totalSubscribed--;
                if (!_unresolvedTags.Contains(tagPath))
                    _resolvedTags--;

                // DataConnectionLayer-006: drop the tag's tracked quality so it is no
                // longer counted by PushBadQualityForAllTags (which sets _tagsBadQuality
                // from _lastTagQuality.Count). Leaving it here drifts the quality
                // counters above _totalSubscribed across disconnect cycles.
                if (_lastTagQuality.Remove(tagPath, out var droppedQuality))
                {
                    switch (droppedQuality)
                    {
                        case QualityCode.Good: _tagsGoodQuality--; break;
                        case QualityCode.Bad: _tagsBadQuality--; break;
                        case QualityCode.Uncertain: _tagsUncertainQuality--; break;
                    }
                }
            }
        }

        _subscriptionsByInstance.Remove(request.InstanceUniqueName);
        _subscribers.Remove(request.InstanceUniqueName);

        // DataConnectionLayer-006: keep the reported quality counters in sync after the
        // unsubscribed tags' buckets were decremented above.
        _healthCollector.UpdateTagQuality(_connectionName, _tagsGoodQuality, _tagsBadQuality, _tagsUncertainQuality);
        _healthCollector.UpdateTagResolution(_connectionName, _totalSubscribed, _resolvedTags);
    }

    // ── Write Support (WP-11) ──

    private void HandleWrite(WriteTagRequest request)
    {
        _log.Debug("[{0}] Writing to tag {1}", _connectionName, request.TagPath);
        var sender = Sender;

        // DataConnectionLayer-005: bound the write with WriteTimeout. A hung device
        // write (TCP black-hole) would otherwise never complete, so PipeTo never
        // fires and the calling script gets no DCL-level error. The CancellationToken
        // is passed to the adapter; on timeout we translate cancellation into a
        // failed WriteTagResponse so the failure is returned synchronously (WP-11).
        var cts = new CancellationTokenSource(_options.WriteTimeout);

        // WP-11: Write through DCL to device, failure returned synchronously
        _adapter.WriteAsync(request.TagPath, request.Value, cts.Token).ContinueWith(t =>
        {
            cts.Dispose();
            if (t.IsCompletedSuccessfully)
            {
                var result = t.Result;
                return new WriteTagResponse(
                    request.CorrelationId, result.Success, result.ErrorMessage, DateTimeOffset.UtcNow);
            }
            if (t.IsCanceled || t.Exception?.GetBaseException() is OperationCanceledException)
            {
                return new WriteTagResponse(
                    request.CorrelationId, false,
                    $"Write timeout after {_options.WriteTimeout.TotalSeconds:F0}s", DateTimeOffset.UtcNow);
            }
            return new WriteTagResponse(
                request.CorrelationId, false, t.Exception?.GetBaseException().Message, DateTimeOffset.UtcNow);
        }).PipeTo(sender);
    }

    // ── Tag Resolution Retry (WP-12) ──

    private void HandleRetryTagResolution()
    {
        if (_unresolvedTags.Count == 0)
        {
            Timers.Cancel("tag-resolution-retry");
            return;
        }

        var self = Self;

        // DataConnectionLayer-010: only dispatch retries for tags that do not already
        // have an attempt in flight. A slow SubscribeAsync overlapping the next tick
        // would otherwise produce duplicate concurrent subscribes for the same tag.
        var toResolve = _unresolvedTags.Where(t => !_resolutionInFlight.Contains(t)).ToList();

        if (toResolve.Count == 0)
        {
            _log.Debug("[{0}] Tag-resolution retry skipped — {1} attempt(s) still in flight",
                _connectionName, _resolutionInFlight.Count);
            return;
        }

        _log.Debug("[{0}] Retrying resolution for {1} unresolved tags", _connectionName, toResolve.Count);

        var generation = _adapterGeneration;
        foreach (var tagPath in toResolve)
        {
            _resolutionInFlight.Add(tagPath);
            _adapter.SubscribeAsync(tagPath, (path, value) =>
            {
                self.Tell(new TagValueReceived(path, value, generation));
            }).ContinueWith(t =>
            {
                if (t.IsCompletedSuccessfully)
                    return new TagResolutionSucceeded(tagPath, t.Result) as object;
                return new TagResolutionFailed(tagPath, t.Exception?.GetBaseException().Message ?? "Unknown error");
            }).PipeTo(self);
        }
    }

    // ── Bad Quality Push (WP-9) ──

    private void PushBadQualityForAllTags()
    {
        var now = DateTimeOffset.UtcNow;
        foreach (var (instanceName, tags) in _subscriptionsByInstance)
        {
            if (!_subscribers.TryGetValue(instanceName, out var subscriber))
                continue;

            subscriber.Tell(new ConnectionQualityChanged(_connectionName, QualityCode.Bad, now));
        }

        // All tags now bad quality
        _tagsGoodQuality = 0;
        _tagsUncertainQuality = 0;
        _tagsBadQuality = _lastTagQuality.Count;
        foreach (var key in _lastTagQuality.Keys.ToList())
            _lastTagQuality[key] = QualityCode.Bad;
        _healthCollector.UpdateTagQuality(_connectionName, _tagsGoodQuality, _tagsBadQuality, _tagsUncertainQuality);
    }

    // ── Re-subscribe (WP-10) ──

    private void ReSubscribeAll()
    {
        // Derive tag list from _subscriptionsByInstance (durable source of truth),
        // not _subscriptionIds which gets cleared and is only repopulated on success.
        var allTags = _subscriptionsByInstance.Values
            .SelectMany(tags => tags)
            .Distinct()
            .ToList();

        _log.Info("[{0}] Re-subscribing {1} tags after reconnect", _connectionName, allTags.Count);

        var self = Self;
        _subscriptionIds.Clear();
        _unresolvedTags.Clear();
        _resolutionInFlight.Clear();
        _resolvedTags = 0;

        // DataConnectionLayer-006: reset the quality tracking too. Otherwise tags
        // resolved for the first time after reconnect (never in _lastTagQuality) only
        // increment their bucket and the totals drift above _totalSubscribed. They are
        // repopulated from fresh TagValueReceived messages once subscriptions activate.
        _lastTagQuality.Clear();
        _tagsGoodQuality = 0;
        _tagsBadQuality = 0;
        _tagsUncertainQuality = 0;
        _healthCollector.UpdateTagQuality(_connectionName, _tagsGoodQuality, _tagsBadQuality, _tagsUncertainQuality);

        var generation = _adapterGeneration;
        foreach (var tagPath in allTags)
        {
            _adapter.SubscribeAsync(tagPath, (path, value) =>
            {
                self.Tell(new TagValueReceived(path, value, generation));
            }).ContinueWith(t =>
            {
                if (t.IsCompletedSuccessfully)
                    return new TagResolutionSucceeded(tagPath, t.Result) as object;
                return new TagResolutionFailed(tagPath, t.Exception?.GetBaseException().Message ?? "Unknown error");
            }).PipeTo(self);
        }
    }

    // ── Health Reporting (WP-13) ──

    private void ReplyWithHealthReport()
    {
        var status = _adapter.Status;
        var endpointLabel = _backupConfig == null
            ? "Primary (no backup)"
            : _activeEndpoint.ToString();
        Sender.Tell(new DataConnectionHealthReport(
            _connectionName, status, _totalSubscribed, _resolvedTags, endpointLabel, DateTimeOffset.UtcNow));
    }

    // ── Internal message handlers for piped async results ──

    private void HandleTagResolutionSucceeded(TagResolutionSucceeded msg)
    {
        // DataConnectionLayer-010: the retry attempt for this tag has completed.
        _resolutionInFlight.Remove(msg.TagPath);

        if (_unresolvedTags.Remove(msg.TagPath))
        {
            _subscriptionIds[msg.TagPath] = msg.SubscriptionId;
            _resolvedTags++;
            _healthCollector.UpdateTagResolution(_connectionName, _totalSubscribed, _resolvedTags);
            _log.Info("[{0}] Tag resolved: {1}", _connectionName, msg.TagPath);
        }

        if (_unresolvedTags.Count == 0)
        {
            Timers.Cancel("tag-resolution-retry");
        }
    }

    private void HandleTagResolutionFailed(TagResolutionFailed msg)
    {
        _log.Debug("[{0}] Tag resolution still failing for {1}: {2}",
            _connectionName, msg.TagPath, msg.Error);

        // DataConnectionLayer-010: the retry attempt for this tag has completed —
        // it is eligible for the next retry tick again.
        _resolutionInFlight.Remove(msg.TagPath);

        // Track as unresolved so periodic retry picks it up
        if (_unresolvedTags.Add(msg.TagPath))
        {
            Timers.StartPeriodicTimer(
                "tag-resolution-retry",
                new RetryTagResolution(),
                _options.TagResolutionRetryInterval,
                _options.TagResolutionRetryInterval);
        }
    }

    private void HandleTagValueReceived(TagValueReceived msg)
    {
        // DataConnectionLayer-011: drop values delivered by a disposed adapter. After a
        // failover the old adapter's OPC UA SDK threads may still fire callbacks; those
        // carry a stale generation and must not be forwarded to Instance Actors.
        if (msg.AdapterGeneration != _adapterGeneration)
        {
            _log.Debug("[{0}] Dropping stale tag value for {1} from adapter generation {2} (current {3})",
                _connectionName, msg.TagPath, msg.AdapterGeneration, _adapterGeneration);
            return;
        }

        // Fan out to all subscribed instances
        foreach (var (instanceName, tags) in _subscriptionsByInstance)
        {
            if (!tags.Contains(msg.TagPath))
                continue;

            if (_subscribers.TryGetValue(instanceName, out var subscriber))
            {
                subscriber.Tell(new TagValueUpdate(
                    _connectionName, msg.TagPath, msg.Value.Value, msg.Value.Quality, msg.Value.Timestamp));
            }
        }

        // Track quality transitions
        if (_lastTagQuality.TryGetValue(msg.TagPath, out var prevQuality))
        {
            // Decrement old quality bucket
            switch (prevQuality)
            {
                case QualityCode.Good: _tagsGoodQuality--; break;
                case QualityCode.Bad: _tagsBadQuality--; break;
                case QualityCode.Uncertain: _tagsUncertainQuality--; break;
            }
        }
        // Increment new quality bucket
        switch (msg.Value.Quality)
        {
            case QualityCode.Good: _tagsGoodQuality++; break;
            case QualityCode.Bad: _tagsBadQuality++; break;
            case QualityCode.Uncertain: _tagsUncertainQuality++; break;
        }
        _lastTagQuality[msg.TagPath] = msg.Value.Quality;
        _healthCollector.UpdateTagQuality(_connectionName, _tagsGoodQuality, _tagsBadQuality, _tagsUncertainQuality);
    }

    // ── Internal messages ──

    internal record AttemptConnect;
    internal record ConnectResult(bool Success, string? Error);
    internal record AdapterDisconnected;
    internal record TagValueReceived(string TagPath, TagValue Value, int AdapterGeneration);
    internal record TagResolutionFailed(string TagPath, string Error);
    internal record TagResolutionSucceeded(string TagPath, string SubscriptionId);
    internal record RetryTagResolution;
    internal record SubscribeTagResult(
        string TagPath, bool AlreadySubscribed, bool Success, string? SubscriptionId, string? Error,
        bool ConnectionLevelFailure = false);
    internal record SubscribeCompleted(
        SubscribeTagsRequest Request, IActorRef ReplyTo, IReadOnlyList<SubscribeTagResult> Results);
    public record GetHealthReport;
}
