Merge lane E5: alarm comment audit table (#748)

Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT
2026-10-22 17:06:37 -04:00
parent 92dea29547 dad28d37a2
commit d1f24cf6a7
9 changed files with 1360 additions and 123 deletions
@@ -7,7 +7,7 @@ namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;

 /// <summary>
 ///     The <c>onReady</c> callback handed to <c>AddZbLocalDb</c>: creates the deployment-cache,
-///     alarm store-and-forward, and scripted-alarm condition-state tables and — when this node
+///     alarm store-and-forward, and scripted-alarm condition-state + comment tables and — when this node
 ///     actually replicates — opts them into change capture.
 /// </summary>
 /// <remarks>
@@ -21,7 +21,7 @@ namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;
 public static class LocalDbSetup
 {
    /// <summary>
-    ///     The four tables that participate in replication — registered when this node is configured
+    ///     The five tables that participate in replication — registered when this node is configured
    ///     to replicate, and deregistered (stale capture triggers dropped) when it is not.
    /// </summary>
    /// <remarks>
@@ -36,6 +36,7 @@ public static class LocalDbSetup
        DeploymentCacheSchema.PointerTable,
        AlarmSfSchema.EventsTable,
        AlarmConditionStateSchema.StateTable,
+        AlarmConditionStateSchema.CommentsTable,
    ];

    /// <summary>
@@ -47,8 +48,9 @@ public static class LocalDbSetup
    ///         <c>RegisterReplicated</c> is what installs the three AFTER triggers that capture
    ///         changes into the oplog. Any row written before that call is never captured, so it
    ///         never reaches the peer — silently, and permanently, because nothing ever revisits
-    ///         history. <see cref="AlarmSfLegacyMigrator"/> therefore runs <b>last</b>, after every
-    ///         registration — it writes rows, and they must be captured like any other write.
+    ///         history. <see cref="AlarmConditionStateSchema.MigrateInlineComments"/> and
+    ///         <see cref="AlarmSfLegacyMigrator"/> therefore run <b>last</b>, after every
+    ///         registration — they write rows, and those must be captured like any other write.
    ///     </para>
    ///     <para>
    ///         <b>Registration is CONDITIONAL on <see cref="ReplicationIsConfigured"/>.</b> It used
@@ -68,7 +70,7 @@ public static class LocalDbSetup
    ///     </para>
    ///     <para>
    ///         <b>A failure part-way through either loop fails host start, and that is deliberate.</b>
-    ///         Neither branch catches, so a throw on the third of four tables leaves two flipped and
+    ///         Neither branch catches, so a throw on the third of five tables leaves two flipped and
    ///         propagates out of the <c>AddZbLocalDb</c> singleton factory — a node that came up
    ///         anyway would be capturing (or not) on an arbitrary subset, which is silently partial
    ///         replication with nothing in the log to say so. Both library calls are idempotent, so
@@ -116,7 +118,36 @@ public static class LocalDbSetup
        else
            RemoveStaleCapture(db, logger ?? Serilog.Log.Logger);

-        // LAST, and only here. This is the one call in OnReady that writes rows.
+        // LAST, and only here. These are the only calls in OnReady that write rows.
+        // Copies any pre-split inline comment trail (alarm_condition_state.comments_json) into the
+        // append-only alarm_condition_comment table (review R05:4). Idempotent: an ordinal already
+        // held is never rewritten, and the condition row itself is never touched (the alarm's next
+        // save clears the column). An unreadable trail is reported, not skipped silently.
+        AlarmConditionStateSchema.InlineCommentMigrationResult commentMigration;
+        using (var connection = db.CreateConnection())
+        {
+            commentMigration = AlarmConditionStateSchema.MigrateInlineComments(connection);
+        }
+
+        var migrationLog = logger ?? Serilog.Log.Logger;
+        if (commentMigration.RowsMoved > 0)
+        {
+            migrationLog.Information(
+                "LocalDb: copied the inline comment trail of {AlarmCount} scripted alarm(s) into {Table}.",
+                commentMigration.RowsMoved,
+                AlarmConditionStateSchema.CommentsTable);
+        }
+
+        foreach (var alarmId in commentMigration.UnparseableAlarmIds)
+        {
+            migrationLog.Warning(
+                "LocalDb: scripted alarm {AlarmId} has an unreadable inline comment trail "
+                + "(alarm_condition_state.comments_json is not valid JSON); its history was NOT moved to {Table} "
+                + "and the alarm's state will not load until the row is repaired.",
+                alarmId,
+                AlarmConditionStateSchema.CommentsTable);
+        }
+
        AlarmSfLegacyMigrator.Migrate(db, configuration);
    }

@@ -1,6 +1,4 @@
 using System.Collections.Immutable;
-using System.Globalization;
-using System.Text.Json;
 using Microsoft.Data.Sqlite;
 using Microsoft.Extensions.Logging;
 using ZB.MOM.WW.LocalDb;
@@ -11,9 +9,11 @@ namespace ZB.MOM.WW.OtOpcUa.Runtime.ScriptedAlarms;

 /// <summary>
 ///     Node-local <see cref="IAlarmStateStore"/> backed by the replicated
-///     <see cref="AlarmConditionStateSchema.StateTable"/> table in the node's consolidated LocalDb.
-///     Maps the full Part 9 <see cref="AlarmConditionState"/> — Enabled / Acked / Confirmed /
-///     Shelving + the ack/confirm audit trail + operator comments.
+///     <see cref="AlarmConditionStateSchema.StateTable"/> and
+///     <see cref="AlarmConditionStateSchema.CommentsTable"/> tables in the node's consolidated
+///     LocalDb. Maps the full Part 9 <see cref="AlarmConditionState"/> — Enabled / Acked / Confirmed /
+///     Shelving + the ack/confirm audit fields on the condition row, and the append-only comment
+///     trail one row per entry.
 /// </summary>
 /// <remarks>
 ///     <para>
@@ -24,44 +24,75 @@ namespace ZB.MOM.WW.OtOpcUa.Runtime.ScriptedAlarms;
 ///         state then mirrors to its redundant pair peer instead of depending on central SQL.
 ///     </para>
 ///     <para>
-///         <b>The round-trip is byte-identical to the EF store</b> — the enum↔string mappers and the
-///         comment serialization below are duplicated verbatim from it (it is deleted in a later
-///         task; the ported round-trip tests prove parity). The persistence rules carry over
-///         unchanged:
-///     </para>
-///     <para>
 ///         <b>ActiveState is NOT persisted</b> — there is no column; on <see cref="LoadAsync"/> it is
 ///         restored as <see cref="AlarmActiveState.Inactive"/> and the engine re-derives it from the
 ///         live predicate. <b>LastTransitionUtc ↔ updated_at_utc</b>: no dedicated transition column,
 ///         so the last transition rides the row-write timestamp. <b>LastActiveUtc / LastClearedUtc</b>
-///         have no columns and default to <c>null</c> on load. <see cref="AlarmConditionState.Comments"/>
-///         serializes to/from <c>comments_json</c>; an empty list round-trips as <c>"[]"</c>.
+///         have no columns and default to <c>null</c> on load.
 ///     </para>
 ///     <para>
-///         <b>Save is a single unconditional PK upsert.</b> No application-level last-write-wins or
-///         HLC comparison is layered on top — the LocalDb replication HLC handles convergence, and an
-///         unconditional upsert keyed by the primary key is HLC-safe (the same discipline the
-///         alarm-sf sink and the deployment pointer follow).
+///         <b>The comment trail is written incrementally (review R05:4).</b> Each save writes only
+///         the entries the table does not yet hold, so a transition's write — and its replication
+///         payload — is constant however long the history is; the condition row's
+///         <c>comments_json</c> is always written as <c>"[]"</c>. What is "already stored" is read
+///         from the table inside the save's transaction (a bounded read of the trail's tail) rather
+///         than cached, so the store holds no per-alarm state. The pair peer's copy of the same
+///         command is recognised and not duplicated; a local entry that collides with a peer entry
+///         this node never applied is appended after it with a Warning, never dropped — see
+///         <c>AppendNewCommentsAsync</c> and, for why the ordinal is the key,
+///         <see cref="AlarmConditionStateSchema"/>.
+///     </para>
+///     <para>
+///         <b>Remove vs. a lagging peer.</b> <see cref="RemoveAsync"/> deletes the whole trail; if the
+///         pair peer has not yet applied the same deploy, its next save finds no stored trail and
+///         re-inserts every entry, which replicates back. The next deploy removes them again — the
+///         same resurrection class the single-row store had, with n+1 rows instead of one (review m3).
+///     </para>
+///     <para>
+///         <b>Old-shape rows load exactly as before.</b> A row still carrying an inline
+///         <c>comments_json</c> trail (written by the pre-split store and not yet moved by
+///         <see cref="AlarmConditionStateSchema.MigrateInlineComments"/>) is read through the same
+///         parser the old store used, merged by ordinal with whatever the comment table holds (the
+///         table wins an ordinal both hold), and moved to the table on that alarm's next save.
+///     </para>
+///     <para>
+///         <b>Save is one transaction:</b> the comment append and an unconditional PK upsert of the
+///         condition row. No application-level last-write-wins or HLC comparison is layered on top —
+///         the LocalDb replication HLC handles convergence.
 ///     </para>
 /// </remarks>
 public sealed class LocalDbAlarmConditionStateStore : IAlarmStateStore
 {
-    private static readonly JsonSerializerOptions JsonOptions = new(JsonSerializerDefaults.Web);
-
    // Fixed column order shared by every read — the reader map below indexes by these ordinals.
    private const string SelectColumns =
        "scripted_alarm_id, enabled_state, acked_state, confirmed_state, shelving_state, " +
        "shelving_expires_utc, last_ack_user, last_ack_comment, last_ack_utc, " +
        "last_confirm_user, last_confirm_comment, last_confirm_utc, comments_json, updated_at_utc";

+    private const string SelectCommentColumns = "scripted_alarm_id, seq, timestamp_utc, user_name, kind, text";
+
+    /// <summary>
+    ///     How many trailing in-memory entries each save reconciles against the stored trail by
+    ///     content. The engine appends at most one entry per save, so this comfortably covers a few
+    ///     missed commands while keeping each save's read bounded.
+    /// </summary>
+    private const int MatchWindow = 16;
+
+    /// <summary>
+    ///     How far apart two nodes' timestamps for the SAME command may be and still count as one
+    ///     entry: command fan-out latency plus inter-node clock skew. Beyond it both copies are kept
+    ///     (the safe direction — a duplicate, never a loss).
+    /// </summary>
+    private static readonly TimeSpan SameCommandSkew = TimeSpan.FromMinutes(5);
+
    private readonly ILocalDb _db;
    private readonly ILogger<LocalDbAlarmConditionStateStore> _logger;

    /// <summary>Initializes a new instance of the <see cref="LocalDbAlarmConditionStateStore"/> class.</summary>
    /// <param name="db">
-    ///     The node's local database. Its <see cref="AlarmConditionStateSchema.StateTable"/> table
-    ///     must already exist and be registered for replication — the host does both in
-    ///     <c>LocalDbSetup.OnReady</c>, before any consumer can resolve this store.
+    ///     The node's local database. Its condition-state and comment tables must already exist and
+    ///     be registered for replication — the host does both in <c>LocalDbSetup.OnReady</c>, before
+    ///     any consumer can resolve this store.
    /// </param>
    /// <param name="logger">The logger instance.</param>
    public LocalDbAlarmConditionStateStore(ILocalDb db, ILogger<LocalDbAlarmConditionStateStore> logger)
@@ -79,7 +110,15 @@ public sealed class LocalDbAlarmConditionStateStore : IAlarmStateStore
            MapRow,
            new { Id = alarmId },
            ct).ConfigureAwait(false);
-        return rows.Count > 0 ? rows[0] : null;
+        if (rows.Count == 0) return null;
+
+        var comments = await _db.QueryAsync(
+            $"SELECT {SelectCommentColumns} FROM alarm_condition_comment WHERE scripted_alarm_id = @Id ORDER BY seq",
+            MapComment,
+            new { Id = alarmId },
+            ct).ConfigureAwait(false);
+
+        return WithComments(rows[0], comments);
    }

    /// <inheritdoc />
@@ -90,7 +129,19 @@ public sealed class LocalDbAlarmConditionStateStore : IAlarmStateStore
            MapRow,
            parameters: null,
            ct).ConfigureAwait(false);
-        return rows;
+
+        var comments = await _db.QueryAsync(
+            $"SELECT {SelectCommentColumns} FROM alarm_condition_comment ORDER BY scripted_alarm_id, seq",
+            MapComment,
+            parameters: null,
+            ct).ConfigureAwait(false);
+        var byAlarm = comments
+            .GroupBy(c => c.AlarmId, StringComparer.Ordinal)
+            .ToDictionary(g => g.Key, g => (IReadOnlyList<StoredComment>)g.ToList(), StringComparer.Ordinal);
+
+        return rows
+            .Select(r => WithComments(r, byAlarm.TryGetValue(r.State.AlarmId, out var c) ? c : []))
+            .ToList();
    }

    /// <inheritdoc />
@@ -98,10 +149,15 @@ public sealed class LocalDbAlarmConditionStateStore : IAlarmStateStore
    {
        ArgumentNullException.ThrowIfNull(state);

+        await using var tx = await _db.BeginTransactionAsync(ct).ConfigureAwait(false);
+
+        await AppendNewCommentsAsync(tx, state, ct).ConfigureAwait(false);
+
        // A single unconditional upsert keyed on the alarm identity. Convergence across the pair is
        // last-writer-wins over the primary key, handled by the LocalDb replication HLC — no
-        // app-level LWW here (see the class remarks).
-        await _db.ExecuteAsync(
+        // app-level LWW here (see the class remarks). comments_json is always "[]": the trail lives
+        // in alarm_condition_comment, which is what keeps this row a fixed size.
+        await tx.ExecuteAsync(
            """
            INSERT INTO alarm_condition_state
                (scripted_alarm_id, enabled_state, acked_state, confirmed_state, shelving_state,
@@ -140,60 +196,243 @@ public sealed class LocalDbAlarmConditionStateStore : IAlarmStateStore
                LastConfirmUser = state.LastConfirmUser,
                LastConfirmComment = state.LastConfirmComment,
                LastConfirmUtc = FormatNullable(state.LastConfirmUtc),
-                CommentsJson = SerializeComments(state.Comments),
+                CommentsJson = AlarmConditionStateSchema.EmptyInlineComments,
                // No dedicated transition column — persist LastTransitionUtc into updated_at_utc.
                UpdatedAtUtc = Format(state.LastTransitionUtc),
            },
            ct).ConfigureAwait(false);

+        await tx.CommitAsync(ct).ConfigureAwait(false);
+
        _logger.LogTrace("Persisted alarm-condition state for {AlarmId}", state.AlarmId);
    }

+    /// <summary>
+    ///     Persists the trail entries <paramref name="state"/> holds that the table does not, writing
+    ///     a bounded number of rows however long the trail is.
+    /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         <b>Normal case.</b> The in-memory trail and the stored trail agree position by
+    ///         position; the only new entries are past <c>MAX(seq)</c> and land at their own ordinal.
+    ///     </para>
+    ///     <para>
+    ///         <b>Divergence (review I-1).</b> If this node missed a command its peer applied, the
+    ///         peer's entry arrives in this table at an ordinal this node's in-memory trail does not
+    ///         know about, and this node's NEXT entry has an in-memory index at or below
+    ///         <c>MAX(seq)</c>. Positional "already stored" would silently drop it — the survivor's
+    ///         newest operator action, in the failover case. So the tail of the in-memory trail
+    ///         (the last <see cref="MatchWindow"/> entries) is matched against the stored rows from
+    ///         that position on, by content: same Kind, User and Text, timestamps within
+    ///         <see cref="SameCommandSkew"/> (each node stamps the same command with its own clock).
+    ///         A matched stored row is consumed, so repeated identical entries are counted, not
+    ///         merged. An entry with no match is new: at its own ordinal when that is past the stored
+    ///         trail, otherwise appended after it (<c>MAX(seq)+1</c>) with a Warning — kept, never
+    ///         dropped, and never silent.
+    ///     </para>
+    ///     <para>
+    ///         <b>Why this cannot double-count.</b> Both pair nodes apply every command; the second
+    ///         node to save finds the first's copy among the stored rows (same Kind/User/Text, close
+    ///         timestamp) and consumes it instead of appending. A node's own earlier divergence-append
+    ///         is found the same way, so a re-save writes nothing. What it cannot tell apart: a peer
+    ///         entry this node missed and a byte-identical entry this node later records within the
+    ///         skew window — that pair is kept once. A clock skew between the nodes beyond the window
+    ///         errs the other way (both copies kept), never towards loss. True union semantics need an
+    ///         originator-assigned entry id on the alarm command (follow-up F3).
+    ///     </para>
+    ///     <para>
+    ///         ⚠️ <b>The in-memory index is the durable ordinal.</b> Trimming
+    ///         <see cref="AlarmConditionState.Comments"/> in the engine without carrying a persisted
+    ///         base offset would make every later save look "already stored" — do not bound that list
+    ///         without changing this method.
+    ///     </para>
+    /// </remarks>
+    private async Task AppendNewCommentsAsync(ILocalDbTransaction tx, AlarmConditionState state, CancellationToken ct)
+    {
+        var comments = state.Comments;
+        var count = comments.Count;
+
+        // An indexed MAX over the (scripted_alarm_id, seq) primary key — a read, so no replication cost.
+        var max = (await tx.QueryAsync(
+            "SELECT COALESCE(MAX(seq), -1) FROM alarm_condition_comment WHERE scripted_alarm_id = @Id",
+            static r => r.GetInt64(0),
+            new { Id = state.AlarmId },
+            ct).ConfigureAwait(false))[0];
+
+        var windowStart = Math.Max(0, count - MatchWindow);
+
+        // Entries below the window that lie past the stored trail (a first save of a long trail, an
+        // old-shape row's lazy move): plain appends at their own ordinal — nothing is stored there.
+        for (var seq = (int)Math.Max(max + 1, 0); seq < windowStart; seq++)
+        {
+            await InsertCommentAsync(tx, state.AlarmId, seq, comments[seq], ct).ConfigureAwait(false);
+            max = seq;
+        }
+
+        if (windowStart >= count) return;
+
+        // The stored rows the window can match: ordinal >= windowStart. Bounded by the window plus the
+        // number of commands this node missed.
+        var stored = max >= windowStart
+            ? await tx.QueryAsync(
+                $"SELECT {SelectCommentColumns} FROM alarm_condition_comment WHERE scripted_alarm_id = @Id AND seq >= @Lo ORDER BY seq",
+                MapComment,
+                new { Id = state.AlarmId, Lo = windowStart },
+                ct).ConfigureAwait(false)
+            : [];
+        var consumed = new bool[stored.Count];
+
+        for (var i = windowStart; i < count; i++)
+        {
+            var entry = comments[i];
+            var match = -1;
+            for (var j = 0; j < stored.Count; j++)
+            {
+                if (!consumed[j] && IsSameEntry(stored[j].Comment, entry))
+                {
+                    match = j;
+                    break;
+                }
+            }
+
+            if (match >= 0)
+            {
+                consumed[match] = true;
+                continue;
+            }
+
+            if (i > max)
+            {
+                await InsertCommentAsync(tx, state.AlarmId, i, entry, ct).ConfigureAwait(false);
+                max = i;
+                continue;
+            }
+
+            var target = max + 1;
+            await InsertCommentAsync(tx, state.AlarmId, target, entry, ct).ConfigureAwait(false);
+            max = target;
+            _logger.LogWarning(
+                "Alarm {AlarmId}: comment trail diverged from the pair peer — the {Kind} entry by {User} at in-memory "
+                + "position {Position} collides with a stored entry this node never applied (a missed command). "
+                + "Kept: appended at ordinal {Ordinal}.",
+                state.AlarmId, entry.Kind, entry.User, i, target);
+        }
+    }
+
+    private static bool IsSameEntry(AlarmComment stored, AlarmComment local) =>
+        string.Equals(stored.Kind, local.Kind, StringComparison.Ordinal)
+        && string.Equals(stored.User, local.User, StringComparison.Ordinal)
+        && string.Equals(stored.Text, local.Text, StringComparison.Ordinal)
+        && (stored.TimestampUtc - local.TimestampUtc).Duration() <= SameCommandSkew;
+
+    private static Task<int> InsertCommentAsync(
+        ILocalDbTransaction tx, string alarmId, long seq, AlarmComment c, CancellationToken ct) =>
+        tx.ExecuteAsync(
+            AlarmConditionStateSchema.InsertCommentSql,
+            new
+            {
+                Id = alarmId,
+                Seq = seq,
+                // AlarmComment.TimestampUtc must be DateTimeKind.Utc for a Utc round-trip; the engine
+                // always creates comments with Utc kind.
+                Ts = AlarmConditionStateSchema.FormatTimestamp(c.TimestampUtc),
+                User = c.User,
+                Kind = c.Kind,
+                Text = c.Text,
+            },
+            ct);
+
    /// <inheritdoc />
    public async Task RemoveAsync(string alarmId, CancellationToken ct)
    {
        ArgumentNullException.ThrowIfNull(alarmId);
-        await _db.ExecuteAsync(
+
+        // The trail goes with the condition, as it did when it was a column of the row.
+        await using var tx = await _db.BeginTransactionAsync(ct).ConfigureAwait(false);
+        await tx.ExecuteAsync(
+            "DELETE FROM alarm_condition_comment WHERE scripted_alarm_id = @Id",
+            new { Id = alarmId },
+            ct).ConfigureAwait(false);
+        await tx.ExecuteAsync(
            "DELETE FROM alarm_condition_state WHERE scripted_alarm_id = @Id",
            new { Id = alarmId },
            ct).ConfigureAwait(false);
+        await tx.CommitAsync(ct).ConfigureAwait(false);
    }

-    private static AlarmConditionState MapRow(SqliteDataReader r) => new(
+    /// <summary>A condition row as read, before its trail is attached.</summary>
+    private sealed record ConditionRow(AlarmConditionState State, string InlineCommentsJson);
+
+    /// <summary>One <c>alarm_condition_comment</c> row.</summary>
+    private sealed record StoredComment(string AlarmId, long Seq, AlarmComment Comment);
+
+    /// <summary>
+    ///     Attaches the trail: the comment table's entries by ordinal, plus — for an old-shape row not
+    ///     yet migrated — any inline entry at an ordinal the table does not hold.
+    /// </summary>
+    private static AlarmConditionState WithComments(ConditionRow row, IReadOnlyList<StoredComment> stored)
+    {
+        var inline = AlarmConditionStateSchema.ParseInlineComments(row.InlineCommentsJson);
+        if (inline.Count == 0)
+            return row.State with { Comments = stored.Select(s => s.Comment).ToImmutableList() };
+
+        var merged = new SortedDictionary<long, AlarmComment>();
+        foreach (var s in stored)
+            merged[s.Seq] = s.Comment;
+        for (var i = 0; i < inline.Count; i++)
+        {
+            var c = inline[i];
+            merged.TryAdd(i, new AlarmComment(c.TimestampUtc, c.User, c.Kind, c.Text));
+        }
+
+        return row.State with { Comments = merged.Values.ToImmutableList() };
+    }
+
+    private static StoredComment MapComment(SqliteDataReader r) => new(
        AlarmId: r.GetString(0),
-        Enabled: string.Equals(r.GetString(1), "Disabled", StringComparison.Ordinal)
-            ? AlarmEnabledState.Disabled
-            : AlarmEnabledState.Enabled,  // unknown string → Enabled (safe default)
-        // Active is not persisted — the engine re-derives it from the predicate at startup.
-        Active: AlarmActiveState.Inactive,
-        Acked: string.Equals(r.GetString(2), "Acknowledged", StringComparison.Ordinal)
-            ? AlarmAckedState.Acknowledged
-            : AlarmAckedState.Unacknowledged,  // unknown string → Unacknowledged (safe default)
-        Confirmed: string.Equals(r.GetString(3), "Confirmed", StringComparison.Ordinal)
-            ? AlarmConfirmedState.Confirmed
-            : AlarmConfirmedState.Unconfirmed,  // unknown string → Unconfirmed (safe default)
-        Shelving: new ShelvingState(MapShelvingFromColumn(r.GetString(4)), ParseNullable(r, 5)),
-        // No transition column — updated_at_utc carries the last transition timestamp.
-        LastTransitionUtc: Parse(r.GetString(13)),
-        // LastActiveUtc / LastClearedUtc have no columns — they re-derive with Active, so null on load.
-        LastActiveUtc: null,
-        LastClearedUtc: null,
-        LastAckUtc: ParseNullable(r, 8),
-        LastAckUser: r.IsDBNull(6) ? null : r.GetString(6),
-        LastAckComment: r.IsDBNull(7) ? null : r.GetString(7),
-        LastConfirmUtc: ParseNullable(r, 11),
-        LastConfirmUser: r.IsDBNull(9) ? null : r.GetString(9),
-        LastConfirmComment: r.IsDBNull(10) ? null : r.GetString(10),
-        Comments: DeserializeComments(r.GetString(12)));
+        Seq: r.GetInt64(1),
+        Comment: new AlarmComment(
+            AlarmConditionStateSchema.ParseTimestamp(r.GetString(2)),
+            r.GetString(3),
+            r.GetString(4),
+            r.GetString(5)));
+
+    private static ConditionRow MapRow(SqliteDataReader r) => new(
+        new AlarmConditionState(
+            AlarmId: r.GetString(0),
+            Enabled: string.Equals(r.GetString(1), "Disabled", StringComparison.Ordinal)
+                ? AlarmEnabledState.Disabled
+                : AlarmEnabledState.Enabled,  // unknown string → Enabled (safe default)
+            // Active is not persisted — the engine re-derives it from the predicate at startup.
+            Active: AlarmActiveState.Inactive,
+            Acked: string.Equals(r.GetString(2), "Acknowledged", StringComparison.Ordinal)
+                ? AlarmAckedState.Acknowledged
+                : AlarmAckedState.Unacknowledged,  // unknown string → Unacknowledged (safe default)
+            Confirmed: string.Equals(r.GetString(3), "Confirmed", StringComparison.Ordinal)
+                ? AlarmConfirmedState.Confirmed
+                : AlarmConfirmedState.Unconfirmed,  // unknown string → Unconfirmed (safe default)
+            Shelving: new ShelvingState(MapShelvingFromColumn(r.GetString(4)), ParseNullable(r, 5)),
+            // No transition column — updated_at_utc carries the last transition timestamp.
+            LastTransitionUtc: Parse(r.GetString(13)),
+            // LastActiveUtc / LastClearedUtc have no columns — they re-derive with Active, so null on load.
+            LastActiveUtc: null,
+            LastClearedUtc: null,
+            LastAckUtc: ParseNullable(r, 8),
+            LastAckUser: r.IsDBNull(6) ? null : r.GetString(6),
+            LastAckComment: r.IsDBNull(7) ? null : r.GetString(7),
+            LastConfirmUtc: ParseNullable(r, 11),
+            LastConfirmUser: r.IsDBNull(9) ? null : r.GetString(9),
+            LastConfirmComment: r.IsDBNull(10) ? null : r.GetString(10),
+            Comments: ImmutableList<AlarmComment>.Empty),
+        InlineCommentsJson: r.GetString(12));

    // Timestamps are stored as round-trip ("O") TEXT so lexicographic order stays chronological and
    // the DateTimeKind.Utc round-trips exactly.
-    private static string Format(DateTime value) => value.ToString("O", CultureInfo.InvariantCulture);
+    private static string Format(DateTime value) => AlarmConditionStateSchema.FormatTimestamp(value);

-    private static string? FormatNullable(DateTime? value) => value?.ToString("O", CultureInfo.InvariantCulture);
+    private static string? FormatNullable(DateTime? value) => value is { } v ? Format(v) : null;

-    private static DateTime Parse(string value) =>
-        DateTime.Parse(value, CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind);
+    private static DateTime Parse(string value) => AlarmConditionStateSchema.ParseTimestamp(value);

    private static DateTime? ParseNullable(SqliteDataReader r, int ordinal) =>
        r.IsDBNull(ordinal) ? null : Parse(r.GetString(ordinal));
@@ -220,45 +459,4 @@ public sealed class LocalDbAlarmConditionStateStore : IAlarmStateStore
        "TimedShelved" => ShelvingKind.Timed,
        _ => ShelvingKind.Unshelved,  // unknown string → Unshelved (safe default)
    };
-
-    private static string SerializeComments(ImmutableList<AlarmComment> comments)
-    {
-        if (comments.IsEmpty) return "[]";
-        var dtos = comments.Select(c => new CommentDto
-        {
-            // AlarmComment.TimestampUtc must be DateTimeKind.Utc for correct ISO-8601 round-trip;
-            // the engine always creates AlarmComment instances with Utc kind.
-            TimestampUtc = c.TimestampUtc,
-            User = c.User,
-            Kind = c.Kind,
-            Text = c.Text,
-        });
-        return JsonSerializer.Serialize(dtos, JsonOptions);
-    }
-
-    private static ImmutableList<AlarmComment> DeserializeComments(string? json)
-    {
-        if (string.IsNullOrWhiteSpace(json)) return ImmutableList<AlarmComment>.Empty;
-        var dtos = JsonSerializer.Deserialize<List<CommentDto>>(json, JsonOptions);
-        if (dtos is null || dtos.Count == 0) return ImmutableList<AlarmComment>.Empty;
-        return dtos
-            .Select(d => new AlarmComment(d.TimestampUtc, d.User ?? string.Empty, d.Kind ?? string.Empty, d.Text ?? string.Empty))
-            .ToImmutableList();
-    }
-
-    /// <summary>Stable on-disk shape for a persisted <see cref="AlarmComment"/> in <c>comments_json</c>.</summary>
-    private sealed class CommentDto
-    {
-        /// <summary>When the comment was recorded (UTC).</summary>
-        public DateTime TimestampUtc { get; set; }
-
-        /// <summary>Identity of the actor that wrote the comment.</summary>
-        public string? User { get; set; }
-
-        /// <summary>Human-readable classification of the comment (Acknowledge, Confirm, …).</summary>
-        public string? Kind { get; set; }
-
-        /// <summary>Operator-supplied or engine-generated comment text.</summary>
-        public string? Text { get; set; }
-    }
 }