contracts: round-trip degraded provenance/watch-list/mode-changed; proto doc (Contracts-018,019)

src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto

@@ -315,8 +315,15 @@ message SubscribeBulkCommand {
   repeated string tag_addresses = 2;
 }
 
-// Provider selection / current provider for the alarm feed. UNSPECIFIED on a
-// SubscribeAlarmsCommand means auto: alarmmgr primary with subtag fallback.
+// Provider selection / current provider for the alarm feed. The zero value
+// has two distinct meanings depending on the use site:
+//   - As SubscribeAlarmsCommand.forced_mode, UNSPECIFIED means auto: alarmmgr
+//     primary with subtag fallback.
+//   - As a provenance value (OnAlarmTransitionEvent.source_provider,
+//     ActiveAlarmSnapshot.source_provider, OnAlarmProviderModeChangedEvent.mode,
+//     AlarmProviderStatus.mode), the worker always emits ALARMMGR or SUBTAG and
+//     never UNSPECIFIED; clients should treat a UNSPECIFIED provenance value as
+//     "unknown / not yet determined".
 enum AlarmProviderMode {
   ALARM_PROVIDER_MODE_UNSPECIFIED = 0;
   ALARM_PROVIDER_MODE_ALARMMGR = 1;
@@ -847,7 +854,14 @@ message ActiveAlarmSnapshot {
   string operator_comment = 11;
   MxValue current_value = 12;
   MxValue limit_value = 13;
+  // True when this snapshot came from the subtag-monitoring fallback rather
+  // than the native alarmmgr provider — synthesized from data changes, reduced
+  // fidelity (synthetic GUID, no native raise time). Mirrors
+  // OnAlarmTransitionEvent.degraded.
   bool degraded = 14;
+  // Which provider produced this snapshot. Mirrors
+  // OnAlarmTransitionEvent.source_provider; always ALARMMGR or SUBTAG on the
+  // wire (never UNSPECIFIED).
   AlarmProviderMode source_provider = 15;
 }