fix(CLI-37,CLI-38): make status/HRESULT reply validation conformant across all five clients

One cross-client conformance pass; also closes first-cycle CLI-08.

CLI-37: an MxStatusProxy entry is a failure iff `category !=
MX_STATUS_CATEGORY_OK`. The proto contract has always said so — `success` is
the raw 16-bit COM member carried verbatim for diagnostics, not a boolean — but
four clients branched on `success` alone and .NET required both, so the same
gateway reply produced opposite verdicts per language. An absent entry stays
success; a present entry with an UNSPECIFIED category is a failure, because the
worker always maps a category and an unmapped one is not proven OK.

CLI-38: a reply fails on HRESULT iff `hresult` is present and negative, so
positive COM success codes such as S_FALSE (1) pass. .NET/Go/Java used `!= 0`,
which errored on a parity-preserving S_FALSE that Python and Rust accepted.
This makes the existing ClientLibrariesDesign.md claim true rather than
rewriting the doc to describe the divergence.

Four shared fixtures pin both rules cross-client, and each language suite also
carries a table test for the two edges a fixture cannot express (absent entry,
UNSPECIFIED category). A Java test fake that built a status with a bare
`setSuccess(1)` and no category is fixed — under the category rule that reply
was never a success.

clients/go/README.md

@@ -94,6 +94,12 @@ goroutine cleanup. Raw protobuf messages remain available through the
 `errors.As` for `GatewayError`, `CommandError`, and `MxAccessError`; command
 errors preserve the raw reply.
 
+`EnsureMxAccessSuccess` follows COM semantics: only a **negative** HRESULT is a
+failure, so positive success codes such as `S_FALSE` (1) pass. `StatusSucceeded`
+judges each `MXSTATUS_PROXY` entry by its category — an entry fails when
+`Category` is not `MX_STATUS_CATEGORY_OK`, and the raw `Success` member is a
+diagnostic that never decides the verdict. A nil entry is success.
+
 ### Reconnect-replay gap
 
 Each `EventResult` carries exactly one of `Event`, `ReplayGap`, or `Err`. When

clients/go/mxgateway/conversion_test.go

@@ -65,7 +65,8 @@ func TestStatusConversionFixtures(t *testing.T) {
 			if err := protojson.Unmarshal(tc.Status, &status); err != nil {
 				t.Fatalf("parse status: %v", err)
 			}
-			if got, want := StatusSucceeded(&status), status.GetSuccess() != 0; got != want {
+			want := status.GetCategory() == pb.MxStatusCategory_MX_STATUS_CATEGORY_OK
+			if got := StatusSucceeded(&status); got != want {
 				t.Fatalf("StatusSucceeded() = %v, want %v", got, want)
 			}
 		})

clients/go/mxgateway/errors.go

@@ -180,11 +180,15 @@ func EnsureProtocolSuccess(op string, status *ProtocolStatus, reply *MxCommandRe
 
 // EnsureMxAccessSuccess returns a typed MxAccessError for failing HRESULTs or
 // MXSTATUS_PROXY entries.
+//
+// Following COM semantics, only a negative HRESULT is a failure — positive
+// success codes such as S_FALSE (1) pass. Status entries are judged by
+// StatusSucceeded, which branches on the authoritative category.
 func EnsureMxAccessSuccess(op string, reply *MxCommandReply) error {
 	if reply == nil {
 		return nil
 	}
-	if reply.Hresult != nil && reply.GetHresult() != 0 {
+	if reply.Hresult != nil && reply.GetHresult() < 0 {
 		return &MxAccessError{Reply: reply}
 	}
 	for _, status := range reply.GetStatuses() {

clients/go/mxgateway/protofixtures_test.go

@@ -48,6 +48,89 @@ func TestGeneratedGoldenFixturesParse(t *testing.T) {
 	}
 }
 
+// TestCommandReplyValidationFixtures locks the shared reply-validation rules to
+// the behavior fixtures: a status entry fails iff its category is not OK (the
+// raw success member is diagnostics only), and an HRESULT fails iff it is
+// present and negative (S_FALSE and other positive COM success codes pass).
+func TestCommandReplyValidationFixtures(t *testing.T) {
+	tests := []struct {
+		fixture     string
+		wantFailure bool
+	}{
+		{fixture: "register.ok.reply.json", wantFailure: false},
+		{fixture: "write.mxaccess-failure.reply.json", wantFailure: true},
+		{fixture: "write.status-category-error-success-set.reply.json", wantFailure: true},
+		{fixture: "write.status-category-ok-success-zero.reply.json", wantFailure: false},
+		{fixture: "write.hresult-s-false.reply.json", wantFailure: false},
+		{fixture: "write.hresult-e-fail.reply.json", wantFailure: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.fixture, func(t *testing.T) {
+			data, err := os.ReadFile(filepath.Join(
+				"..", "..", "proto", "fixtures", "behavior", "command-replies", tt.fixture))
+			if err != nil {
+				t.Fatalf("read fixture: %v", err)
+			}
+
+			var reply pb.MxCommandReply
+			if err := protojson.Unmarshal(data, &reply); err != nil {
+				t.Fatalf("parse fixture: %v", err)
+			}
+
+			err = EnsureMxAccessSuccess("invoke", &reply)
+			if got := err != nil; got != tt.wantFailure {
+				t.Fatalf("EnsureMxAccessSuccess() failed = %v (err %v), want %v", got, err, tt.wantFailure)
+			}
+		})
+	}
+}
+
+// TestStatusSucceededBranchesOnCategory pins the per-entry rule directly,
+// including the two edges the fixtures cannot express: a nil entry is success
+// and a present entry with an unspecified category is a failure.
+func TestStatusSucceededBranchesOnCategory(t *testing.T) {
+	tests := []struct {
+		name   string
+		status *MxStatusProxy
+		want   bool
+	}{
+		{name: "nil entry", status: nil, want: true},
+		{
+			name: "ok category with zero success",
+			status: &pb.MxStatusProxy{
+				Success:  0,
+				Category: pb.MxStatusCategory_MX_STATUS_CATEGORY_OK,
+			},
+			want: true,
+		},
+		{
+			name: "error category with success set",
+			status: &pb.MxStatusProxy{
+				Success:  1,
+				Category: pb.MxStatusCategory_MX_STATUS_CATEGORY_COMMUNICATION_ERROR,
+			},
+			want: false,
+		},
+		{
+			name: "unspecified category with success set",
+			status: &pb.MxStatusProxy{
+				Success:  1,
+				Category: pb.MxStatusCategory_MX_STATUS_CATEGORY_UNSPECIFIED,
+			},
+			want: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := StatusSucceeded(tt.status); got != tt.want {
+				t.Fatalf("StatusSucceeded() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
 func TestOpenSessionFixtureProtocolVersions(t *testing.T) {
 	data, err := os.ReadFile(filepath.Join("..", "..", "proto", "fixtures", "golden", "open-session-reply.ok.json"))
 	if err != nil {

clients/go/mxgateway/status.go

@@ -1,6 +1,17 @@
 package mxgateway
 
+import (
+	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
+)
+
 // StatusSucceeded reports whether an MXSTATUS_PROXY entry represents success.
+//
+// The wire contract makes Category authoritative: an entry succeeds only when
+// its category is MX_STATUS_CATEGORY_OK. The Success member mirrors the raw
+// 16-bit COM value verbatim for diagnostics and is not a boolean, so it takes
+// no part in the verdict. A nil entry is success (nothing was reported); a
+// present entry with an unspecified category is a failure, because the worker
+// always maps a category and an unmapped one is not proven OK.
 func StatusSucceeded(status *MxStatusProxy) bool {
-	return status == nil || status.GetSuccess() != 0
+	return status == nil || status.GetCategory() == pb.MxStatusCategory_MX_STATUS_CATEGORY_OK
 }