fix(alarms): #647 review — Raise on an active condition is a re-statement; FOCAS outage quality + health

MAJOR-1: a deploy that changes a driver's config respawns it, and the fresh instance's empty told record re-sent Raise for every still-active alarm, un-acking acknowledged conditions and writing a duplicate "Activated" alerts row. NativeAlarmProjector now treats Raise on an already-active condition as a re-statement (keeps Acked; ForwardNativeAlarm skips the alerts row); only Retrigger (or inactive->active) un-acks. Sources whose upstream ack state is authoritative send Retrigger for an unacked re-statement: OpcUaClient on first sight (no prior told), Galaxy for an unacked active snapshot entry. Runtime E2E drives a FRESH FOCAS driver after a redeploy and asserts the ack survives. MAJOR-2: a failed FOCAS alarm read annotates each subscribed condition BadNoCommunication once per outage (#626 quality-only path) with one Warning (MINOR-6), lifted to Good on recovery; failed alarm reads degrade driver health with LastSuccessfulRead frozen (successful ones advance it), so an alarm-only driver trips the #527 comms-loss watchdog. MINOR-3 CLAUDE.md #630 bullet; MINOR-4 split line; MINOR-5 a non-empty cnc_rdalmmsg2 payload that fits neither stride throws; MINOR-7 value-tag + parsed-address tables are built and swapped, never cleared in place under the retained poll engine. Docs corrected (FOCAS.md, AlarmTracking.md, CLAUDE.md). Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
2026-10-08 20:18:03 -04:00
parent 482bafdfac
commit 89961af6e6
17 changed files with 516 additions and 66 deletions
@@ -57,6 +57,22 @@ internal sealed class FocasAlarmProjection : IAsyncDisposable
    /// <summary>Devices whose last read came back at the per-read cap. Guarded by <see cref="_alarmLock"/>.</summary>
    private readonly HashSet<string> _truncationWarned = new(StringComparer.OrdinalIgnoreCase);

+    /// <summary>Devices whose alarm read is currently failing (one Warning per episode). Guarded by <see cref="_alarmLock"/>.</summary>
+    private readonly HashSet<string> _failingDevices = new(StringComparer.OrdinalIgnoreCase);
+
+    /// <summary>
+    ///     ConditionIds this projection has annotated <c>BadNoCommunication</c> and not yet lifted. Guarded by
+    ///     <see cref="_alarmLock"/>. Kept apart from <see cref="_told"/>: a quality annotation never touches a
+    ///     condition's Active/Acked state.
+    /// </summary>
+    private readonly HashSet<string> _qualityBadTold = new(StringComparer.Ordinal);
+
+    /// <summary>Canonical <c>Opc.Ua.StatusCodes.Good</c>.</summary>
+    private const uint QualityGood = 0x00000000u;
+
+    /// <summary>Canonical <c>Opc.Ua.StatusCodes.BadNoCommunication</c>.</summary>
+    private const uint QualityBadNoCommunication = 0x80310000u;
+
    /// <summary>Serializes loop start/stop.</summary>
    private readonly SemaphoreSlim _loopGate = new(1, 1);

@@ -95,7 +111,11 @@ internal sealed class FocasAlarmProjection : IAsyncDisposable
        lock (_alarmLock)
        {
            // Forget only the conditions that LEFT the set (#641) — the SAME set (a reconnect) prunes nothing.
-            foreach (var gone in _told.Keys.Where(k => !refs.Contains(k)).ToList()) _told.Remove(gone);            Volatile.Write(ref _current, sub);
+            foreach (var gone in _told.Keys.Where(k => !refs.Contains(k)).ToList()) _told.Remove(gone);
+            // A (re)subscribe follows a reconnect, where the host re-annotates every condition Good (#477); forget
+            // which conditions this projection marked Bad, so a still-failing device re-asserts its Bad.
+            _qualityBadTold.Clear();
+            Volatile.Write(ref _current, sub);
        }
        await RestartLoopAsync().ConfigureAwait(false);
        return sub.Handle;
@@ -225,10 +245,14 @@ internal sealed class FocasAlarmProjection : IAsyncDisposable
            catch (OperationCanceledException) when (ct.IsCancellationRequested) { throw; }
            catch (Exception ex)
            {
-                // Not "no alarms": keep every condition on this device exactly as the server was last told.
-                _logger.LogDebug(ex, "FOCAS alarm read failed for {Host}; its conditions keep their state", host);
+                // Not "no alarms": keep every condition on this device exactly as the server was last told, but say
+                // its source is unreachable — and let the failure reach driver health (an alarm-only driver has no
+                // other read to trip the comms-loss watchdog with).
+                _driver.NoteAlarmReadFailed(host, ex);
+                TickFailed(sub, host, tags, ex);
                continue;
            }
+            _driver.NoteAlarmReadSucceeded();
            Tick(sub, host, alarms, tags);
        }
    }
@@ -266,24 +290,92 @@ internal sealed class FocasAlarmProjection : IAsyncDisposable
            var handlers = _driver.AlarmHandlers;
            if (handlers is null) return;

+            if (_failingDevices.Remove(deviceHostAddress))
+                _logger.LogInformation("FOCAS alarm read for {Host} recovered", deviceHostAddress);
+
            foreach (var tag in deviceTags.Where(t => sub.References.Contains(t.RawPath)))
            {
+                // Lift a Bad this projection put there BEFORE the normal diff, so a recovery that also changed the
+                // alarm state (cleared during the outage) lands as Good then Clear.
+                if (_qualityBadTold.Remove(tag.RawPath))
+                    Deliver(handlers, QualityOnly(tag, sub.Handle, QualityGood, now), tag.RawPath);
+
                var view = FocasAlarmMatcher.Evaluate(tag.Selector, alarms, deviceSelectors, truncated);
                _told.TryGetValue(tag.RawPath, out var told);
                var (evt, nowTold) = FocasAlarmConditionMapper.Transition(told, view, tag, sub.Handle, now);
                _told[tag.RawPath] = nowTold;
                if (evt is null) continue;
+                Deliver(handlers, evt, tag.RawPath);
+            }
+        }
+    }

-                foreach (var registration in handlers.GetInvocationList())
-                {
-                    try { ((EventHandler<AlarmEventArgs>)registration).Invoke(_driver, evt); }
-                    catch (Exception ex)
-                    {
-                        _logger.LogWarning(ex,
-                            "FOCAS driver caught a fault from an alarm subscriber for {ConditionId}; delivery continues.",
-                            tag.RawPath);
-                    }
-                }
+    /// <summary>
+    ///     A FAILED read of <paramref name="deviceHostAddress"/> (Gitea #647 review): conditions keep their state, but
+    ///     each subscribed one is annotated <c>BadNoCommunication</c> once per outage through the #626 quality-only
+    ///     path (no Active/Acked change, no <c>/alerts</c> row), and the first failure of the episode logs one
+    ///     Warning. The next successful read lifts the Bad in <see cref="Tick"/>.
+    /// </summary>
+    /// <param name="sub">The subscription the read was taken for; a superseded one emits nothing.</param>
+    /// <param name="deviceHostAddress">The device whose read failed.</param>
+    /// <param name="tags">The driver's alarm-tag table (RawPath → tag).</param>
+    /// <param name="error">Why the read failed.</param>
+    internal void TickFailed(
+        Subscription sub, string deviceHostAddress, IReadOnlyDictionary<string, FocasAlarmTag> tags, Exception error)
+    {
+        var now = DateTime.UtcNow;
+        lock (_alarmLock)
+        {
+            if (!ReferenceEquals(Volatile.Read(ref _current), sub)) return;
+
+            if (_failingDevices.Add(deviceHostAddress))
+                _logger.LogWarning(error,
+                    "FOCAS alarm read (cnc_rdalmmsg2) failed for {Host}; its alarm conditions keep their state and are " +
+                    "marked BadNoCommunication until a read succeeds", deviceHostAddress);
+            else
+                _logger.LogDebug(error, "FOCAS alarm read for {Host} still failing", deviceHostAddress);
+
+            // As for transitions: with nobody listening, record nothing, so the next failure tells it.
+            var handlers = _driver.AlarmHandlers;
+            if (handlers is null) return;
+
+            foreach (var tag in tags.Values.Where(t =>
+                         string.Equals(t.DeviceHostAddress, deviceHostAddress, StringComparison.OrdinalIgnoreCase)
+                         && sub.References.Contains(t.RawPath)))
+            {
+                if (!_qualityBadTold.Add(tag.RawPath)) continue;
+                Deliver(handlers, QualityOnly(tag, sub.Handle, QualityBadNoCommunication, now), tag.RawPath);
+            }
+        }
+    }
+
+    /// <summary>A quality-only annotation (#626): <see cref="AlarmTransitionKind.Unspecified"/> + a status code.</summary>
+    private AlarmEventArgs QualityOnly(FocasAlarmTag tag, IAlarmSubscriptionHandle handle, uint quality, DateTime now)
+    {
+        _told.TryGetValue(tag.RawPath, out var told);
+        return new AlarmEventArgs(handle,
+            SourceNodeId: tag.DeviceHostAddress,
+            ConditionId: tag.RawPath,
+            AlarmType: told?.Winner is { } w ? FocasAlarmConditionMapper.TypeLabel(w.Type) : "CncAlarm",
+            Message: told?.Message ?? "",
+            Severity: told?.Severity ?? AlarmSeverity.Low,
+            SourceTimestampUtc: now,
+            Kind: AlarmTransitionKind.Unspecified,
+            OpcUaSeverity: told?.OpcUaSeverity,
+            QualityStatusCode: quality);
+    }
+
+    /// <summary>Invokes every handler, isolating a faulting one. Caller holds the lock.</summary>
+    private void Deliver(EventHandler<AlarmEventArgs> handlers, AlarmEventArgs evt, string conditionId)
+    {
+        foreach (var registration in handlers.GetInvocationList())
+        {
+            try { ((EventHandler<AlarmEventArgs>)registration).Invoke(_driver, evt); }
+            catch (Exception ex)
+            {
+                _logger.LogWarning(ex,
+                    "FOCAS driver caught a fault from an alarm subscriber for {ConditionId}; delivery continues.",
+                    conditionId);
            }
        }
    }
@@ -47,7 +47,9 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
    private readonly Dictionary<string, DeviceState> _devices = new(StringComparer.OrdinalIgnoreCase);
    // v3: RawPath → definition, case-sensitive ordinal. Built in InitializeAsync from _options.RawTags
    // via the pure FocasTagDefinitionFactory mapper (the reference is always a RawPath).
-    private readonly Dictionary<string, FocasTagDefinition> _tagsByRawPath = new(StringComparer.Ordinal);
+    // Built whole in InitializeAsync and SWAPPED in (Gitea #647 review): the #630-retained poll engine keeps calling
+    // ReadAsync during a re-initialise, and a table cleared and refilled in place reads BadNodeIdUnknown in between.
+    private Dictionary<string, FocasTagDefinition> _tagsByRawPath = new(StringComparer.Ordinal);
    // Resolves a read/write fullReference (always a RawPath in v3) to a tag definition by a single
    // authored-table hit. A miss is a miss — the driver surfaces BadNodeIdUnknown, never a blob-parse.
    private readonly EquipmentTagRefResolver<FocasTagDefinition> _resolver;
@@ -56,7 +58,7 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
    // call. ConcurrentDictionary is required because the poll loop
    // (ReadAsync) and the host write thread (WriteAsync) both mutate this cache when resolver-
    // produced equipment tags are encountered for the first time.
-    private readonly ConcurrentDictionary<string, FocasAddress> _parsedAddressesByTagName =
+    private ConcurrentDictionary<string, FocasAddress> _parsedAddressesByTagName =
        new(StringComparer.OrdinalIgnoreCase);
    /// <summary>
    ///     Whether this driver instance runs its per-device fixed-tree poll loop, and therefore
@@ -128,7 +130,7 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
        _logger = logger ?? NullLogger<FocasDriver>.Instance;
        _alarmProjection = new FocasAlarmProjection(this, _logger);
        _resolver = new EquipmentTagRefResolver<FocasTagDefinition>(
-            r => _tagsByRawPath.TryGetValue(r, out var t) ? t : null);
+            r => Volatile.Read(ref _tagsByRawPath).TryGetValue(r, out var t) ? t : null);
        _poll = new PollGroupEngine(
            reader: ReadAsync,
            onChange: (handle, tagRef, snapshot) =>
@@ -234,8 +236,9 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
            _skippedTags.BeginRebuild(_options.RawTags.Count);
            // A re-initialise without teardown (#630) rebuilds the tables from scratch: a tag the new config
            // removed — or moved between the value and alarm tables (#647) — must not survive in the old one.
-            _tagsByRawPath.Clear();
-            _parsedAddressesByTagName.Clear();
+            // Built into fresh tables and swapped in below, never cleared in place under a live reader.
+            var tagsByRawPath = new Dictionary<string, FocasTagDefinition>(StringComparer.Ordinal);
+            var parsedAddresses = new ConcurrentDictionary<string, FocasAddress>(StringComparer.OrdinalIgnoreCase);
            var alarmTags = new Dictionary<string, FocasAlarmTag>(StringComparer.Ordinal);
            foreach (var entry in _options.RawTags)
            {
@@ -298,7 +301,7 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
                        entry.RawPath, why, _driverInstanceId);
                    continue;
                }
-                _tagsByRawPath[entry.RawPath] = def with
+                tagsByRawPath[entry.RawPath] = def with
                {
                    DeviceHostAddress = deviceHost,
                    WriteIdempotent = entry.WriteIdempotent,
@@ -306,12 +309,14 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
                // Cache the parsed FocasAddress so ReadAsync / WriteAsync don't re-parse on every
                // hot-path call. The address string has already been validated by FocasAddress.TryParse
                // above; reusing the parsed record avoids per-tick allocs on subscription pollers.
-                _parsedAddressesByTagName[entry.RawPath] = parsed;
+                parsedAddresses[entry.RawPath] = parsed;
            }
            // Publish the skip tally only once the whole table is built. An unknown-device throw above
            // leaves the previous snapshot standing rather than a truncated one that would read as
            // "we now skip fewer tags".
            _skippedTags.Commit();
+            Volatile.Write(ref _parsedAddressesByTagName, parsedAddresses);
+            Volatile.Write(ref _tagsByRawPath, tagsByRawPath);
            Volatile.Write(ref _alarmTags, alarmTags);

            if (_options.Probe.Enabled)
@@ -465,7 +470,7 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
            state.DisposeClient();
        }
        _devices.Clear();
-        _tagsByRawPath.Clear();
+        Volatile.Write(ref _tagsByRawPath, new Dictionary<string, FocasTagDefinition>(StringComparer.Ordinal));
        Volatile.Write(ref _alarmTags, new Dictionary<string, FocasAlarmTag>(StringComparer.Ordinal));
        _resolver.Clear(); // no-op in v3 (the resolver reads the live table by closure); kept for symmetry
        _parsedAddressesByTagName.Clear();
@@ -1693,6 +1698,35 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
    /// <summary>Gets the alarm poll cadence — one <c>cnc_rdalmmsg2</c> per alarm-owning device per tick.</summary>
    internal TimeSpan AlarmPollInterval => _options.AlarmProjection.PollInterval;

+
+    /// <summary>
+    ///     A successful alarm read is a successful read (Gitea #647 review): it advances
+    ///     <see cref="DriverHealth.LastSuccessfulRead"/> exactly as a Good value read does, so an alarm-only driver's
+    ///     health tracks its CNC. Never lifts a <see cref="DriverState.Faulted"/> (a config-level signal).
+    /// </summary>
+    internal void NoteAlarmReadSucceeded()
+    {
+        var current = Volatile.Read(ref _health);
+        if (current.State != DriverState.Faulted)
+            Volatile.Write(ref _health, new DriverHealth(DriverState.Healthy, DateTime.UtcNow, null));
+    }
+
+    /// <summary>
+    ///     A failed alarm read degrades driver health, PRESERVING <see cref="DriverHealth.LastSuccessfulRead"/> — the
+    ///     conjunction the comms-loss watchdog (#527) trips on. Without it a driver whose only tags are <c>ALARM:</c>
+    ///     tags stayed Healthy through a total outage, the watchdog never fired, and the host's #477
+    ///     <c>BadNoCommunication</c> annotation never ran (Gitea #647 review).
+    /// </summary>
+    /// <param name="hostAddress">The device whose alarm read failed.</param>
+    /// <param name="error">Why.</param>
+    internal void NoteAlarmReadFailed(string hostAddress, Exception error)
+    {
+        var current = Volatile.Read(ref _health);
+        if (current.State != DriverState.Faulted)
+            Volatile.Write(ref _health, new DriverHealth(DriverState.Degraded, current.LastSuccessfulRead,
+                $"FOCAS alarm read failed for {hostAddress}: {error.Message}"));
+    }
+
    /// <summary>
    ///     Reads one device's active-alarm list. <b>Throws on any failure</b> — an unknown device, a connect that
    ///     fails, a read the CNC refuses — because the projection must never mistake a failed read for an empty
@@ -1101,10 +1101,24 @@ public sealed class FocasWireClient : IAsyncDisposable, IDisposable
        return new WireProgramName(name, number);
    }

-    private static IReadOnlyList<WireAlarm> ParseAlarms(byte[] payload, short count)
-        => payload.Length % 76 == 0
-            ? ParseVendorAlarms(payload, count)
-            : ParseLegacyWireAlarms(payload, count);
+    /// <summary>
+    ///     Decode a <c>cnc_rdalmmsg2</c> payload: the 76-byte vendor stride, else the 80-byte legacy one. An empty
+    ///     payload is "no alarms active". A non-empty payload that fits NEITHER stride is malformed and throws
+    ///     (Gitea #647 review): it used to fall into the legacy parser, decode zero records, and so read as "no
+    ///     alarms" — a mass Clear of every condition on the device, then an un-acknowledged re-raise next poll.
+    /// </summary>
+    /// <param name="payload">The reply payload.</param>
+    /// <param name="count">The requested record count.</param>
+    /// <returns>The decoded alarms.</returns>
+    /// <exception cref="FocasWireException">The payload length matches neither record layout.</exception>
+    internal static IReadOnlyList<WireAlarm> ParseAlarms(byte[] payload, short count)
+    {
+        if (payload.Length % 76 == 0) return ParseVendorAlarms(payload, count);
+        if (payload.Length % 80 == 0) return ParseLegacyWireAlarms(payload, count);
+        throw new FocasWireException(
+            $"cnc_rdalmmsg2 returned a {payload.Length}-byte payload, which fits neither the 76- nor the 80-byte " +
+            "record layout; refusing to read it as an empty alarm list.", rc: null);
+    }

    private static IReadOnlyList<WireAlarm> ParseVendorAlarms(byte[] payload, short count)
    {
@@ -171,14 +171,18 @@ internal sealed class GatewayGalaxyAlarmFeed : IGalaxyAlarmFeed
    ///     Decode one entry of the initial active-alarm snapshot. Each currently-active
    ///     alarm is surfaced as a transition so the OPC UA Part 9 condition layer sees
    ///     the alarm's present state on (re)connect: an unacknowledged active alarm as
-    ///     a <see cref="GalaxyAlarmTransitionKind.Raise"/>, an acknowledged one as a
+    ///     a <see cref="GalaxyAlarmTransitionKind.Retrigger"/>, an acknowledged one as a
    ///     <see cref="GalaxyAlarmTransitionKind.Acknowledge"/>.
+    ///     <para>Retrigger, not Raise (Gitea #647 review): the host treats a Raise on a condition it already
+    ///     shows Active as a re-statement that KEEPS the acknowledgement. A snapshot re-states upstream state and
+    ///     the upstream's ack state is authoritative, so an unacked entry must un-ack a host condition still
+    ///     holding an ack from before the reconnect.</para>
    /// </summary>
    private void DispatchSnapshotEntry(ActiveAlarmSnapshot snapshot)
    {
        var kind = snapshot.CurrentState switch
        {
-            AlarmConditionState.Active => GalaxyAlarmTransitionKind.Raise,
+            AlarmConditionState.Active => GalaxyAlarmTransitionKind.Retrigger,
            AlarmConditionState.ActiveAcked => GalaxyAlarmTransitionKind.Acknowledge,
            AlarmConditionState.Inactive => GalaxyAlarmTransitionKind.Clear,
            _ => GalaxyAlarmTransitionKind.Unspecified,
@@ -1982,12 +1982,11 @@ public sealed class OpcUaClientDriver : IDriver, ITagDiscovery, IReadable, IWrit

            // Fresh prior = the host projector's own default (inactive, acked).
            var told = new AlarmToldState(target.Active, target.Acked, e.Message, e.OpcUaSeverity);
-            var prior = _alarmStateByRawPath.TryGetValue(e.ConditionId, out var p)
-                ? p
-                : new AlarmToldState(false, true, null, null);
+            var priorKnown = _alarmStateByRawPath.TryGetValue(e.ConditionId, out var p);
+            var prior = priorKnown ? p! : new AlarmToldState(false, true, null, null);
            _alarmStateByRawPath[e.ConditionId] = told;

-            var kinds = AlarmTransitions((prior.Active, prior.Acked), target);
+            var kinds = AlarmTransitions((prior.Active, prior.Acked), target, priorKnown);
            if (kinds.Count == 0)
            {
                // Same state: a message/severity change still reaches the host; an identical copy does not.
@@ -2106,18 +2105,34 @@ public sealed class OpcUaClientDriver : IDriver, ITagDiscovery, IReadable, IWrit

    /// <summary>
    ///     #619 review — the <see cref="AlarmTransitionKind"/> sequence that moves the host's
-    ///     <c>NativeAlarmProjector</c> (which knows only kinds: Raise ⇒ active+unacked, Acknowledge ⇒ acked,
+    ///     <c>NativeAlarmProjector</c> (which knows only kinds: Raise ⇒ active+unacked — or, on an already-active condition, a re-statement keeping the ack (#647) — Acknowledge ⇒ acked,
    ///     Clear ⇒ inactive keeping acked) from <paramref name="prior"/> to <paramref name="target"/>. A single
    ///     upstream event can need two (an alarm that went active and was acknowledged between two notifications).
    ///     No state change ⇒ empty (the caller decides whether a message/severity change warrants an Unspecified).
    /// </summary>
    /// <param name="prior">The state last told to the host.</param>
    /// <param name="target">The upstream event's ActiveState/Id + AckedState/Id.</param>
+    /// <param name="priorKnown">
+    ///     False when this driver instance has told the host nothing about the condition yet (first sight after a
+    ///     start or a deploy respawn), so <paramref name="prior"/> is only the projector's default. Gitea #647 review:
+    ///     the host now treats a Raise on an already-active condition as a re-statement that KEEPS its ack, so an
+    ///     upstream that says <i>unacknowledged</i> must then be told with <see cref="AlarmTransitionKind.Retrigger"/>
+    ///     — the upstream's ack state is authoritative, and the host may be holding an ack from before the respawn.
+    /// </param>
    /// <returns>The kinds to emit, in order.</returns>
    internal static IReadOnlyList<AlarmTransitionKind> AlarmTransitions(
-        (bool Active, bool Acked) prior, (bool Active, bool Acked) target)
+        (bool Active, bool Acked) prior, (bool Active, bool Acked) target, bool priorKnown = true)
    {
        if (prior == target) return [];
+        var kinds = Transitions(prior, target);
+        return priorKnown || target.Acked
+            ? kinds
+            : [.. kinds.Select(k => k == AlarmTransitionKind.Raise ? AlarmTransitionKind.Retrigger : k)];
+    }
+
+    private static IReadOnlyList<AlarmTransitionKind> Transitions(
+        (bool Active, bool Acked) prior, (bool Active, bool Acked) target)
+    {
        return target switch
        {
            // Active+unacked: a fresh raise, or a re-arm of an active-acked condition.
@@ -1877,12 +1877,14 @@ public sealed class DriverHostActor : ReceiveActor, IWithTimers, IWithUnboundedS
        foreach (var n in nodeIds)
        {
            var nodeId = n.NodeId;
-            var snapshot = _nativeAlarmProjector.Project(nodeId, msg.Args);
+            var snapshot = _nativeAlarmProjector.Project(nodeId, msg.Args, out var restatement);
            _opcUaPublishActor.Tell(new ZB.MOM.WW.OtOpcUa.Runtime.OpcUa.OpcUaPublishActor.AlarmStateUpdate(
                nodeId, snapshot, msg.Args.SourceTimestampUtc, n.Realm));

-            // Only the Primary publishes the cluster-wide alerts transition (see the gate above).
-            if (!serviceAlertsAsPrimary) continue;
+            // Only the Primary publishes the cluster-wide alerts transition (see the gate above). A re-statement
+            // (Gitea #647 review: a Raise on an already-active condition, sent by a driver a deploy respawned) is
+            // not a transition — the condition was already Active, so a second "Activated" row would be a duplicate.
+            if (!serviceAlertsAsPrimary || restatement) continue;

            var meta = _alarmMetaByNodeId.TryGetValue(nodeId, out var m)
                ? m : (EquipmentId: nodeId, Name: nodeId, AlarmType: "AlarmCondition", HistorizeToAveva: (bool?)null,
@@ -18,13 +18,29 @@ public sealed class NativeAlarmProjector
    /// <param name="nodeId">The materialised condition node's id (the projection's state key).</param>
    /// <param name="e">The native alarm transition.</param>
    /// <returns>The full Part 9 condition snapshot to write to the node.</returns>
-    public AlarmConditionSnapshot Project(string nodeId, AlarmEventArgs e)
+    public AlarmConditionSnapshot Project(string nodeId, AlarmEventArgs e) => Project(nodeId, e, out _);
+
+    /// <summary>
+    ///     Project an alarm transition, reporting whether it was a <b>re-statement</b> (Gitea #647 review): a
+    ///     <see cref="AlarmTransitionKind.Raise"/> on a condition already projected Active. That is what a driver
+    ///     whose told-record died with its instance sends after a deploy respawns it — the alarm it re-reads is the
+    ///     one the server already shows, so the acknowledgement is KEPT and the host writes no second "Activated"
+    ///     row. Only <see cref="AlarmTransitionKind.Retrigger"/> (or inactive → active) un-acknowledges; a source
+    ///     that knows the alarm is a genuinely new statement must send Retrigger.
+    /// </summary>
+    /// <param name="nodeId">The materialised condition node's id (the projection's state key).</param>
+    /// <param name="e">The native alarm transition.</param>
+    /// <param name="restatement">True when <paramref name="e"/> re-stated an already-active condition.</param>
+    /// <returns>The full Part 9 condition snapshot to write to the node.</returns>
+    public AlarmConditionSnapshot Project(string nodeId, AlarmEventArgs e, out bool restatement)
    {
        var prev = _prior.TryGetValue(nodeId, out var p) ? p : (Active: false, Acked: true);
        // #626: a source with a finer scale than the four buckets supplies the exact Part 9 severity.
        var sev = e.OpcUaSeverity is { } exact ? (ushort)Math.Clamp(exact, 1, 1000) : MapSeverity(e.Severity);
+        restatement = e.Kind == AlarmTransitionKind.Raise && prev.Active;
        var (active, acked) = e.Kind switch
        {
+            AlarmTransitionKind.Raise when prev.Active => (true, prev.Acked),
            AlarmTransitionKind.Raise or AlarmTransitionKind.Retrigger => (true, false),
            AlarmTransitionKind.Acknowledge => (prev.Active, true),
            AlarmTransitionKind.Clear => (false, prev.Acked),