docs(contracts): document unpropagated operator_full_name, reserved enum values, correlation echo

docs/MxAccessWorkerInstanceDesign.md

@@ -1019,10 +1019,10 @@ and relies on the gateway to kill the process.
 
 ## Fault Handling
 
-Worker fault categories:
+Worker fault categories (`InvalidArguments` and `GatewayAuthenticationFailed`
+are reserved and never emitted: bootstrap failures exit via `WorkerExitCode`
+before the pipe exists):
 
-- `InvalidArguments`
-- `GatewayAuthenticationFailed`
 - `ProtocolMismatch`
 - `ProtocolViolation`
 - `PipeDisconnected`

src/ZB.MOM.WW.MxGateway.Contracts/Generated/MxaccessGateway.cs

@@ -727,6 +727,10 @@ namespace ZB.MOM.WW.MxGateway.Contracts.Proto {
     [pbr::OriginalName("ALARM_TRANSITION_KIND_RAISE")] Raise = 1,
     [pbr::OriginalName("ALARM_TRANSITION_KIND_ACKNOWLEDGE")] Acknowledge = 2,
     [pbr::OriginalName("ALARM_TRANSITION_KIND_CLEAR")] Clear = 3,
+    /// <summary>
+    /// Reserved: never produced by the gateway or worker. Retained so the numeric
+    /// value is not reused.
+    /// </summary>
     [pbr::OriginalName("ALARM_TRANSITION_KIND_RETRIGGER")] Retrigger = 4,
   }
 
@@ -12714,6 +12718,11 @@ namespace ZB.MOM.WW.MxGateway.Contracts.Proto {
     /// <summary>Field number for the "operator_full_name" field.</summary>
     public const int OperatorFullNameFieldNumber = 6;
     private string operatorFullName_ = "";
+    /// <summary>
+    /// Accepted for wire compatibility but NOT propagated to MXAccess: the 8-arg
+    /// AlarmAckByName that carried it returns -55. operator_domain IS used (the
+    /// AuthenticateUser identity is "&lt;operator_domain>\&lt;operator_user>").
+    /// </summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute]
     [global::System.CodeDom.Compiler.GeneratedCode("protoc", null)]
     public string OperatorFullName {
@@ -13384,6 +13393,11 @@ namespace ZB.MOM.WW.MxGateway.Contracts.Proto {
     /// <summary>Field number for the "operator_full_name" field.</summary>
     public const int OperatorFullNameFieldNumber = 8;
     private string operatorFullName_ = "";
+    /// <summary>
+    /// Accepted for wire compatibility but NOT propagated to MXAccess: the 8-arg
+    /// AlarmAckByName that carried it returns -55. operator_domain IS used (the
+    /// AuthenticateUser identity is "&lt;operator_domain>\&lt;operator_user>").
+    /// </summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute]
     [global::System.CodeDom.Compiler.GeneratedCode("protoc", null)]
     public string OperatorFullName {
@@ -17527,6 +17541,9 @@ namespace ZB.MOM.WW.MxGateway.Contracts.Proto {
     /// <summary>Field number for the "correlation_id" field.</summary>
     public const int CorrelationIdFieldNumber = 2;
     private string correlationId_ = "";
+    /// <summary>
+    /// Echoes the request's client_correlation_id.
+    /// </summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute]
     [global::System.CodeDom.Compiler.GeneratedCode("protoc", null)]
     public string CorrelationId {
@@ -26125,7 +26142,7 @@ namespace ZB.MOM.WW.MxGateway.Contracts.Proto {
     /// <summary>
     /// When the alarm originally entered the active state. Preserved across
     /// acknowledge transitions so the Part 9 condition keeps the original raise
-    /// time. Unset on retrigger from a previously-cleared condition.
+    /// time. Unset when the raise time is unknown (RETRIGGER is reserved and never produced).
     /// </summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute]
     [global::System.CodeDom.Compiler.GeneratedCode("protoc", null)]

src/ZB.MOM.WW.MxGateway.Contracts/Generated/MxaccessWorker.cs

@@ -132,6 +132,12 @@ namespace ZB.MOM.WW.MxGateway.Contracts.Proto {
 
   public enum WorkerFaultCategory {
     [pbr::OriginalName("WORKER_FAULT_CATEGORY_UNSPECIFIED")] Unspecified = 0,
+    /// <summary>
+    /// Values 1 and 2 are reserved: never emitted. Bootstrap failures (bad
+    /// arguments, gateway authentication) exit via WorkerExitCode before the pipe
+    /// exists, so there is no channel to carry a fault. Names kept so the numbers
+    /// are not reused.
+    /// </summary>
     [pbr::OriginalName("WORKER_FAULT_CATEGORY_INVALID_ARGUMENTS")] InvalidArguments = 1,
     [pbr::OriginalName("WORKER_FAULT_CATEGORY_GATEWAY_AUTHENTICATION_FAILED")] GatewayAuthenticationFailed = 2,
     [pbr::OriginalName("WORKER_FAULT_CATEGORY_PROTOCOL_MISMATCH")] ProtocolMismatch = 3,

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

@@ -405,6 +405,9 @@ message AcknowledgeAlarmCommand {
   string operator_user = 3;
   string operator_node = 4;
   string operator_domain = 5;
+  // Accepted for wire compatibility but NOT propagated to MXAccess: the 8-arg
+  // AlarmAckByName that carried it returns -55. operator_domain IS used (the
+  // AuthenticateUser identity is "<operator_domain>\<operator_user>").
   string operator_full_name = 6;
   // Operator credential used for AuthenticateUser before the AckMsg write.
   // Implementations must keep this field out of logs, metrics labels, command
@@ -435,6 +438,9 @@ message AcknowledgeAlarmByNameCommand {
   string operator_user = 5;
   string operator_node = 6;
   string operator_domain = 7;
+  // Accepted for wire compatibility but NOT propagated to MXAccess: the 8-arg
+  // AlarmAckByName that carried it returns -55. operator_domain IS used (the
+  // AuthenticateUser identity is "<operator_domain>\<operator_user>").
   string operator_full_name = 8;
   // Operator credential used for AuthenticateUser before the AckMsg write.
   // Implementations must keep this field out of logs, metrics labels, command
@@ -549,6 +555,7 @@ message ShutdownWorkerCommand {
 
 message MxCommandReply {
   string session_id = 1;
+  // Echoes the request's client_correlation_id.
   string correlation_id = 2;
   MxCommandKind kind = 3;
   ProtocolStatus protocol_status = 4;
@@ -880,7 +887,7 @@ message OnAlarmTransitionEvent {
 
   // When the alarm originally entered the active state. Preserved across
   // acknowledge transitions so the Part 9 condition keeps the original raise
-  // time. Unset on retrigger from a previously-cleared condition.
+  // time. Unset when the raise time is unknown (RETRIGGER is reserved and never produced).
   google.protobuf.Timestamp original_raise_timestamp = 6;
 
   // When this specific transition occurred (raise time on Raise, ack time on
@@ -930,6 +937,8 @@ enum AlarmTransitionKind {
   ALARM_TRANSITION_KIND_RAISE = 1;
   ALARM_TRANSITION_KIND_ACKNOWLEDGE = 2;
   ALARM_TRANSITION_KIND_CLEAR = 3;
+  // Reserved: never produced by the gateway or worker. Retained so the numeric
+  // value is not reused.
   ALARM_TRANSITION_KIND_RETRIGGER = 4;
 }
 

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

@@ -127,6 +127,10 @@ enum WorkerState {
 
 enum WorkerFaultCategory {
   WORKER_FAULT_CATEGORY_UNSPECIFIED = 0;
+  // Values 1 and 2 are reserved: never emitted. Bootstrap failures (bad
+  // arguments, gateway authentication) exit via WorkerExitCode before the pipe
+  // exists, so there is no channel to carry a fault. Names kept so the numbers
+  // are not reused.
   WORKER_FAULT_CATEGORY_INVALID_ARGUMENTS = 1;
   WORKER_FAULT_CATEGORY_GATEWAY_AUTHENTICATION_FAILED = 2;
   WORKER_FAULT_CATEGORY_PROTOCOL_MISMATCH = 3;