docs(alarms): document alarmmgr->subtag fallback (providers, failover, config, contract, parity)

docs/DesignDecisions.md

@@ -411,6 +411,58 @@ a per-channel skip-verify hook:
 See [Gateway Configuration — Automatic self-signed certificate](./GatewayConfiguration.md#automatic-self-signed-certificate)
 and the per-client READMEs for the as-built behavior.
 
+## Alarm-Manager to Subtag Fallback
+
+Decision: add a second alarm provider (subtag monitoring) that the worker
+activates automatically when the native wnwrap alarm manager fails, and fails
+back to automatically when the manager recovers.
+
+### Worker-side synthesis
+
+Synthesis of alarm transitions from subtag value changes happens entirely in
+the worker (`SubtagAlarmConsumer` / `SubtagAlarmStateMachine`). The gateway
+still forwards only events the worker emits and synthesizes nothing itself.
+This satisfies the parity rule even though the subtag path is inherently
+non-parity: the parity rule governs where synthesis lives, not whether
+synthesis is permitted when the native source is unavailable.
+
+### Degraded is explicit
+
+Every subtag-mode transition carries `degraded = true` on the
+`OnAlarmTransitionEvent` and `ActiveAlarmSnapshot` proto messages, and the
+`AlarmFeedMessage` feed carries an `AlarmProviderStatus` payload on stream
+open and on every switch. No client can mistake a subtag-mode alarm for an
+authoritative alarmmgr record. Subtag mode has lower fidelity: synthetic
+deterministic GUID (SHA-derived from the alarm reference), best-effort
+original-raise timestamp, narrower field set. Clients that need full fidelity
+must wait for failback.
+
+### Failover trigger
+
+The failover trigger is N consecutive wnwrap COM failures — a `COMException`
+thrown by `Subscribe` or `PollOnce`, or a failure HRESULT from
+`GetXmlCurrentAlarms2`. A single poll failure does not trigger a switch; the
+threshold (default 3, floored at 1) guards against transient COM hiccups. The
+counter resets on any clean poll so a flapping provider does not permanently
+latch in subtag mode.
+
+### Acknowledge via ack-comment write
+
+In subtag mode, `AcknowledgeAlarm` writes the operator comment to the alarm
+attribute's ack-comment subtag (`Fallback:Subtags:AckComment`). The write
+performs the native ack in AVEVA. This differs from alarmmgr mode, where
+`AlarmAckByName` on `wwAlarmConsumerClass` is called directly. The `AckComment`
+subtag name is empty by default; configuring it is required for ack to work in
+subtag mode. The exact AVEVA subtag names are not hard-coded — the `Subtags`
+config block exists precisely so names are not guessed without validation
+against the live MXAccess attribute set.
+
+### Related documentation
+
+- [Gateway Configuration — Alarm Fallback options](./GatewayConfiguration.md#alarm-fallback-options)
+- [Alarm Client Discovery — Subtag provider](./AlarmClientDiscovery.md)
+- [gRPC Contract — provider_status and degraded fields](./Grpc.md)
+
 ## Later Revisit Items
 
 These are explicit post-v1 revisit items, not open blockers: