Merge branch 'worktree-agent-a465fb3cd6ec48cd3' into arch-review-remediation

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Services/ISiteAuditQueue.cs

@@ -143,6 +143,29 @@ public interface ISiteAuditQueue
     /// <paramref name="sinceUtc"/> are proven received; rows at the boundary instant are left
     /// alone. Idempotent; already-Reconciled rows are untouched.
     /// </para>
+    /// <para>
+    /// <b>Only-served-rows-retire.</b> The cursor is a timestamp, and
+    /// <see cref="AuditEvent.OccurredAtUtc"/> is stamped by the caller, so a row can be
+    /// INSERTED after a batch was served yet carry a timestamp below the (by then advanced)
+    /// cursor. Implementations MUST NOT retire such a row: it was never served, the keyset
+    /// read has moved past it, and retiring it would make it purgeable — silent audit loss.
+    /// The SQLite implementation bounds the flip by insertion order (<c>rowid</c> high-water
+    /// mark of rows it has served), exempting rows already
+    /// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Enums.AuditForwardState.Forwarded"/>
+    /// because central ACKED those through the telemetry push path.
+    /// </para>
+    /// <para>
+    /// <b>Liveness dependency (documented, accepted).</b> A row that WAS served but is never
+    /// covered by a later cursor — central reconciliation stopped for good, or the site node
+    /// restarted and its bound reset — stays
+    /// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Enums.AuditForwardState.Pending"/>
+    /// indefinitely, and <see cref="PurgeExpiredAsync"/> never purges Pending. That is the
+    /// retention invariant working as designed (an unacknowledged row is not droppable), but
+    /// it means the site store's floor is bounded by reconciliation actually running. The
+    /// backlog is observable: <see cref="GetBacklogStatsAsync"/> reports the pending count and
+    /// oldest-pending instant on every site health report, and the site reporter logs a
+    /// warning once the oldest pending row exceeds its stale threshold.
+    /// </para>
     /// </remarks>
     /// <param name="sinceUtc">The cursor timestamp central has consumed up to (UTC).</param>
     /// <param name="afterId">The last consumed <see cref="AuditEvent.EventId"/> at that instant, or null.</param>