docs(historian): HistorizeToAveva opt-out semantics + config knobs + startup validation

docs/AlarmTracking.md

@@ -175,13 +175,25 @@ AB CIP ALMD) route to AVEVA Historian via the Wonderware sidecar:
   historian outage, older non-dead-lettered rows are evicted (oldest
   first) to make room for new events. The `HistorianSinkStatus.EvictedCount`
   counter surfaces lifetime eviction events so operators can detect
-  silent data loss without log scraping.
+  silent data loss without log scraping. The drain cadence, queue
+  capacity, and dead-letter retention are tunable via the `AlarmHistorian`
+  config section (`DrainIntervalSeconds`, `Capacity`,
+  `DeadLetterRetentionDays`); `AlarmHistorianOptions.Validate()` logs a
+  startup warning for an empty `SharedSecret`, a relative `DatabasePath`,
+  or a non-positive knob.
 - `HistorianAdapterActor`
   (`src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Historian/HistorianAdapterActor.cs`)
   subscribes to the cluster `alerts` DPS topic, translates each
   `AlarmTransitionEvent` → `AlarmHistorianEvent`, and calls
-  `EnqueueAsync` fire-and-forget. Primary-gated — only the Primary node
-  historizes, giving exactly-once writes across a redundant pair. See
+  `EnqueueAsync` fire-and-forget. The durable write is gated two ways:
+  (1) **Primary-gated** — only the Primary node historizes, giving
+  exactly-once writes across a redundant pair; (2) **per-alarm** — a
+  transition whose `HistorizeToAveva` is `false` is skipped (the flag
+  rides on `AlarmTransitionEvent` as a nullable bool; missing/`null`/`true`
+  historize, only an explicit `false` suppresses, so a cross-version
+  rolling restart defaults to historizing rather than dropping an audit
+  row). Neither gate touches the live `alerts` publish — the `/alerts`
+  UI always sees every transition. See
   [AlarmHistorian.md §Configuration](AlarmHistorian.md#configuration)
   for the `AlarmHistorian` appsettings section that enables the real sink.