fix(CLI-40,CLI-41,CLI-44): exact-secret scrub, uniform malformed-reply contract, Go terminal-error mislabel

CLI-40: port the exact-secret credential scrub to Rust/Java/.NET (Go/Python
already did it). AuthenticateUser/WriteSecured(2) helpers now redact the exact
caller-supplied secret from any surfaced error, as defense-in-depth on top of the
by-construction guarantee. Rust hand-writes a redacting Debug (derived Debug would
leak the reply); Java/.NET rebuild the same exception type with the redacted
message and do not carry the secret-bearing original forward (so ToString/stack
traces stay clean too).

CLI-41: uniform malformed-reply contract for AuthenticateUser/ArchestrAUserToId/
AddBufferedItem across all five clients — typed payload, else a present int32
return_value, else a typed malformed-reply error. Fixes Go/Java silent-0, .NET
NRE, and Rust's own internal inconsistency.

CLI-44: the Go event goroutine's Recv-error path now uses a non-blocking
sendTerminalEventResult on the reserved slot, so a genuine terminal stream error
is reported as itself instead of being mislabeled ErrSlowConsumer under overflow.

Riders from the CLI-37/38 review: (a) .NET ToDiagnosticSummary and Python
_mxaccess_message surface the raw success member (diagnostics-only parity with
Rust); (b) the status-conversion fixture carries an independent wantSuccess
boolean and the Go/.NET fixture tests assert against it instead of recomputing
the formula under test.

Shared fixtures (authenticate-user.{echoed-credential,missing-payload,
return-value-only}.reply.json) + manifest + ClientBehaviorFixtures.md +
ClientLibrariesDesign.md updated in the same change. Tracking: CLI-40/41/44 -> Done.

clients/go/mxgateway/client_session_test.go

@@ -10,7 +10,9 @@ import (
 
 	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
 	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/metadata"
+	"google.golang.org/grpc/status"
 	"google.golang.org/grpc/test/bufconn"
 )
 
@@ -200,6 +202,68 @@ func TestEventsSlowConsumerYieldsErrSlowConsumerBeforeClose(t *testing.T) {
 	}
 }
 
+func TestEventsFullBufferTerminalErrorKeepsRootCause(t *testing.T) {
+	fake := &fakeGatewayServer{
+		streamStarted:     make(chan struct{}),
+		streamDone:        make(chan struct{}),
+		streamEventCount:  eventBufferSize,
+		streamTerminalErr: status.Error(codes.Internal, "boom"),
+	}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	events, err := session.EventsAfter(context.Background(), 0)
+	if err != nil {
+		t.Fatalf("EventsAfter() error = %v", err)
+	}
+	<-fake.streamStarted
+
+	// Do not drain until the stream has fully ended: the server sends exactly
+	// eventBufferSize events (filling the data slots) and then returns a genuine
+	// terminal gRPC error. The client must report that error as itself, using the
+	// reserved slot, rather than mislabeling it as ErrSlowConsumer.
+	select {
+	case <-fake.streamDone:
+	case <-time.After(2 * time.Second):
+		t.Fatal("event stream did not stop after terminal error")
+	}
+	// streamDone fires when the server returns; the client's producer goroutine
+	// still needs a moment to drain the gRPC stream, fill all data slots, and
+	// enqueue the terminal result. Let it settle before draining so the buffer is
+	// genuinely full when the terminal error is processed (which is what makes the
+	// mislabel bug observable).
+	time.Sleep(250 * time.Millisecond)
+
+	var last EventResult
+	gotResult := false
+	for {
+		select {
+		case res, ok := <-events:
+			if !ok {
+				if !gotResult {
+					t.Fatal("events channel closed without yielding any result")
+				}
+				var gwErr *GatewayError
+				if !errors.As(last.Err, &gwErr) {
+					t.Fatalf("final event result err is %T, want *GatewayError", last.Err)
+				}
+				if code := status.Code(last.Err); code != codes.Internal {
+					t.Fatalf("final event result gRPC code = %s, want %s", code, codes.Internal)
+				}
+				if errors.Is(last.Err, ErrSlowConsumer) {
+					t.Fatalf("final event result err = %v, must not be mislabeled as ErrSlowConsumer", last.Err)
+				}
+				return
+			}
+			last = res
+			gotResult = true
+		case <-time.After(2 * time.Second):
+			t.Fatal("events channel did not close after terminal error")
+		}
+	}
+}
+
 func TestEventsSurfacesReplayGapSentinelAsTypedSignal(t *testing.T) {
 	fake := &fakeGatewayServer{
 		streamStarted: make(chan struct{}),
@@ -694,15 +758,16 @@ func newBufconnClient(t *testing.T, fake *fakeGatewayServer) (*Client, func()) {
 type fakeGatewayServer struct {
 	pb.UnimplementedMxAccessGatewayServer
 
-	openReply        *pb.OpenSessionReply
-	openAuth         string
-	streamAuth       string
-	streamStarted    chan struct{}
-	streamDone       chan struct{}
-	streamEventCount int
-	streamReplayGap  *pb.ReplayGap
-	invokeReply      *pb.MxCommandReply
-	invokeRequest    *pb.MxCommandRequest
+	openReply         *pb.OpenSessionReply
+	openAuth          string
+	streamAuth        string
+	streamStarted     chan struct{}
+	streamDone        chan struct{}
+	streamEventCount  int
+	streamReplayGap   *pb.ReplayGap
+	streamTerminalErr error
+	invokeReply       *pb.MxCommandReply
+	invokeRequest     *pb.MxCommandRequest
 }
 
 func (s *fakeGatewayServer) OpenSession(ctx context.Context, req *pb.OpenSessionRequest) (*pb.OpenSessionReply, error) {
@@ -772,6 +837,12 @@ func (s *fakeGatewayServer) StreamEvents(req *pb.StreamEventsRequest, stream grp
 			return err
 		}
 	}
+	if s.streamTerminalErr != nil {
+		// Return a genuine terminal stream error immediately after sending the
+		// events, without waiting on the client to cancel. This exercises the
+		// Recv-error path while the client's result buffer is still full.
+		return s.streamTerminalErr
+	}
 	<-stream.Context().Done()
 	return io.EOF
 }

clients/go/mxgateway/command_reply_fixtures_test.go

@@ -0,0 +1,129 @@
+package mxgateway
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
+	"google.golang.org/protobuf/encoding/protojson"
+)
+
+// loadCommandReplyFixture parses a shared command-reply fixture into an
+// MxCommandReply so the Go client can be driven through the same wire shapes the
+// other language clients exercise.
+func loadCommandReplyFixture(t *testing.T, name string) *pb.MxCommandReply {
+	t.Helper()
+	path := filepath.Join("..", "..", "proto", "fixtures", "behavior", "command-replies", name)
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read fixture %s: %v", name, err)
+	}
+	var reply pb.MxCommandReply
+	if err := protojson.Unmarshal(data, &reply); err != nil {
+		t.Fatalf("parse fixture %s: %v", name, err)
+	}
+	return &reply
+}
+
+func TestAuthenticateUserMissingPayloadReturnsMalformedReplyError(t *testing.T) {
+	fake := &fakeGatewayServer{
+		invokeReply: loadCommandReplyFixture(t, "authenticate-user.missing-payload.reply.json"),
+	}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	_, err := session.AuthenticateUser(context.Background(), 12, "operator", "secret")
+	var malformed *MalformedReplyError
+	if !errors.As(err, &malformed) {
+		t.Fatalf("AuthenticateUser() error = %v (%T), want *MalformedReplyError", err, err)
+	}
+	if malformed.Op != "authenticate user" {
+		t.Fatalf("MalformedReplyError.Op = %q, want %q", malformed.Op, "authenticate user")
+	}
+}
+
+func TestAuthenticateUserReturnValueOnlyUsesInt32ReturnValue(t *testing.T) {
+	fake := &fakeGatewayServer{
+		invokeReply: loadCommandReplyFixture(t, "authenticate-user.return-value-only.reply.json"),
+	}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	userID, err := session.AuthenticateUser(context.Background(), 12, "operator", "secret")
+	if err != nil {
+		t.Fatalf("AuthenticateUser() error = %v", err)
+	}
+	if userID != 7 {
+		t.Fatalf("AuthenticateUser() = %d, want 7", userID)
+	}
+}
+
+// AddBufferedItem shares the prefer-payload / int32-return-value / malformed
+// fallback code path; cover both branches for one of the siblings.
+func TestAddBufferedItemFallbackHonoursReturnValueAndReportsMalformed(t *testing.T) {
+	t.Run("return-value-only", func(t *testing.T) {
+		fake := &fakeGatewayServer{
+			invokeReply: loadCommandReplyFixture(t, "authenticate-user.return-value-only.reply.json"),
+		}
+		client, cleanup := newBufconnClient(t, fake)
+		defer cleanup()
+		session := NewSessionForID(client, "session-1")
+
+		itemHandle, err := session.AddBufferedItem(context.Background(), 12, "Area001.Pump001.Speed", "runtime")
+		if err != nil {
+			t.Fatalf("AddBufferedItem() error = %v", err)
+		}
+		if itemHandle != 7 {
+			t.Fatalf("AddBufferedItem() = %d, want 7", itemHandle)
+		}
+	})
+
+	t.Run("missing-payload", func(t *testing.T) {
+		fake := &fakeGatewayServer{
+			invokeReply: loadCommandReplyFixture(t, "authenticate-user.missing-payload.reply.json"),
+		}
+		client, cleanup := newBufconnClient(t, fake)
+		defer cleanup()
+		session := NewSessionForID(client, "session-1")
+
+		_, err := session.AddBufferedItem(context.Background(), 12, "Area001.Pump001.Speed", "runtime")
+		var malformed *MalformedReplyError
+		if !errors.As(err, &malformed) {
+			t.Fatalf("AddBufferedItem() error = %v (%T), want *MalformedReplyError", err, err)
+		}
+		if malformed.Op != "add buffered item" {
+			t.Fatalf("MalformedReplyError.Op = %q, want %q", malformed.Op, "add buffered item")
+		}
+	})
+}
+
+// TestAuthenticateUserScrubsEchoedCredentialFromError is the CLI-40 regression:
+// a gateway diagnostic that echoes the raw credential back must never reach the
+// caller's surfaced error text.
+func TestAuthenticateUserScrubsEchoedCredentialFromError(t *testing.T) {
+	const credential = "sup3rSecretVerify9f3a2b"
+	fake := &fakeGatewayServer{
+		invokeReply: loadCommandReplyFixture(t, "authenticate-user.echoed-credential.reply.json"),
+	}
+	client, cleanup := newBufconnClient(t, fake)
+	defer cleanup()
+	session := NewSessionForID(client, "session-1")
+
+	_, err := session.AuthenticateUser(context.Background(), 12, "operator", credential)
+	if err == nil {
+		t.Fatal("AuthenticateUser() error = nil, want an MXAccess failure")
+	}
+	message := err.Error()
+	if strings.Contains(message, credential) {
+		t.Fatalf("surfaced error leaked the credential: %q", message)
+	}
+	if !strings.Contains(message, "<redacted>") {
+		t.Fatalf("surfaced error missing redaction marker: %q", message)
+	}
+}

clients/go/mxgateway/conversion_test.go

@@ -51,8 +51,9 @@ func TestStatusConversionFixtures(t *testing.T) {
 
 	var fixture struct {
 		Cases []struct {
-			ID     string          `json:"id"`
-			Status json.RawMessage `json:"status"`
+			ID          string          `json:"id"`
+			WantSuccess bool            `json:"wantSuccess"`
+			Status      json.RawMessage `json:"status"`
 		} `json:"cases"`
 	}
 	if err := json.Unmarshal(data, &fixture); err != nil {
@@ -65,9 +66,8 @@ func TestStatusConversionFixtures(t *testing.T) {
 			if err := protojson.Unmarshal(tc.Status, &status); err != nil {
 				t.Fatalf("parse status: %v", err)
 			}
-			want := status.GetCategory() == pb.MxStatusCategory_MX_STATUS_CATEGORY_OK
-			if got := StatusSucceeded(&status); got != want {
-				t.Fatalf("StatusSucceeded() = %v, want %v", got, want)
+			if got := StatusSucceeded(&status); got != tc.WantSuccess {
+				t.Fatalf("StatusSucceeded() = %v, want %v", got, tc.WantSuccess)
 			}
 		})
 	}

clients/go/mxgateway/errors.go

@@ -72,6 +72,25 @@ func redactSecrets(err error, secrets ...string) error {
 // dropping events. Match it with errors.Is.
 var ErrSlowConsumer = errors.New("mxgateway: event consumer fell behind; stream terminated")
 
+// MalformedReplyError reports an OK command reply that carried neither the
+// typed payload the operation expected nor a usable int32 return_value, so the
+// client cannot produce a result. It gives every affected helper one uniform,
+// inspectable failure instead of silently returning a zero value.
+type MalformedReplyError struct {
+	// Op names the operation whose reply was malformed.
+	Op string
+	// Detail explains what the reply was missing.
+	Detail string
+}
+
+// Error returns the formatted malformed-reply message.
+func (e *MalformedReplyError) Error() string {
+	if e == nil {
+		return ""
+	}
+	return fmt.Sprintf("mxgateway: %s returned a malformed reply: %s", e.Op, e.Detail)
+}
+
 // GatewayError wraps transport-level gRPC failures.
 type GatewayError struct {
 	// Op names the operation that failed (for example "dial" or "invoke").

clients/go/mxgateway/session.go

@@ -812,7 +812,13 @@ func (s *Session) AuthenticateUser(ctx context.Context, serverHandle int32, veri
 	if reply.GetAuthenticateUser() != nil {
 		return reply.GetAuthenticateUser().GetUserId(), nil
 	}
-	return reply.GetReturnValue().GetInt32Value(), nil
+	if x, ok := reply.GetReturnValue().GetKind().(*pb.MxValue_Int32Value); ok {
+		return x.Int32Value, nil
+	}
+	return 0, &MalformedReplyError{
+		Op:     "authenticate user",
+		Detail: "reply carried neither an AuthenticateUser payload nor an int32 return_value",
+	}
 }
 
 // AuthenticateUserRaw invokes MXAccess AuthenticateUser and returns the raw
@@ -847,7 +853,13 @@ func (s *Session) ArchestrAUserToId(ctx context.Context, serverHandle int32, use
 	if reply.GetArchestraUserToId() != nil {
 		return reply.GetArchestraUserToId().GetUserId(), nil
 	}
-	return reply.GetReturnValue().GetInt32Value(), nil
+	if x, ok := reply.GetReturnValue().GetKind().(*pb.MxValue_Int32Value); ok {
+		return x.Int32Value, nil
+	}
+	return 0, &MalformedReplyError{
+		Op:     "archestra user to id",
+		Detail: "reply carried neither an ArchestrAUserToId payload nor an int32 return_value",
+	}
 }
 
 // ArchestrAUserToIdRaw invokes MXAccess ArchestrAUserToId and returns the raw reply.
@@ -876,7 +888,13 @@ func (s *Session) AddBufferedItem(ctx context.Context, serverHandle int32, itemD
 	if reply.GetAddBufferedItem() != nil {
 		return reply.GetAddBufferedItem().GetItemHandle(), nil
 	}
-	return reply.GetReturnValue().GetInt32Value(), nil
+	if x, ok := reply.GetReturnValue().GetKind().(*pb.MxValue_Int32Value); ok {
+		return x.Int32Value, nil
+	}
+	return 0, &MalformedReplyError{
+		Op:     "add buffered item",
+		Detail: "reply carried neither an AddBufferedItem payload nor an int32 return_value",
+	}
 }
 
 // AddBufferedItemRaw invokes MXAccess AddBufferedItem and returns the raw reply.
@@ -981,10 +999,12 @@ func stringSecrets(values ...*MxValue) []string {
 // context cancellation stops Recv, or a terminal error is sent.
 //
 // The returned channel is buffered. If the consumer falls behind and the buffer
-// overflows, the stream is terminated and a final EventResult carrying a
-// GatewayError that wraps ErrSlowConsumer is delivered before the channel
-// closes. Callers must match it with errors.Is(res.Err, ErrSlowConsumer) to
-// distinguish a slow-consumer drop from a graceful server end. Use
+// overflows with data, the stream is terminated and a final EventResult carrying
+// a GatewayError that wraps ErrSlowConsumer is delivered before the channel
+// closes; match it with errors.Is(res.Err, ErrSlowConsumer) to distinguish a
+// slow-consumer drop from a graceful server end. A genuine stream error is
+// reported as itself even under overflow — it is never relabeled as
+// ErrSlowConsumer, so the underlying gRPC status stays inspectable. Use
 // SubscribeEvents for a blocking, backpressured stream that never drops.
 func (s *Session) Events(ctx context.Context) (<-chan EventResult, error) {
 	return s.EventsAfter(ctx, 0)
@@ -994,7 +1014,9 @@ func (s *Session) Events(ctx context.Context) (<-chan EventResult, error) {
 //
 // Like Events, the returned channel is buffered and terminates with a final
 // EventResult wrapping ErrSlowConsumer (matchable via errors.Is) if the consumer
-// falls behind and the buffer overflows, rather than silently closing.
+// falls behind and the buffer overflows with data, rather than silently closing.
+// A genuine stream error is reported as itself even under overflow, never
+// relabeled as ErrSlowConsumer.
 func (s *Session) EventsAfter(ctx context.Context, afterWorkerSequence uint64) (<-chan EventResult, error) {
 	subscription, err := s.subscribeEventsAfter(ctx, afterWorkerSequence, true)
 	if err != nil {
@@ -1048,12 +1070,11 @@ func (s *Session) subscribeEventsAfter(ctx context.Context, afterWorkerSequence
 			if err == io.EOF || status.Code(err) == codes.Canceled || streamCtx.Err() != nil {
 				return
 			}
-			sendEventResult(
-				streamCtx,
-				results,
-				EventResult{Err: &GatewayError{Op: "stream events", Err: err}},
-				cancelWhenResultBufferFull,
-				cancel)
+			// A genuine terminal stream error must be reported as itself, even
+			// when the data slots are full. Routing it through sendEventResult
+			// would let the overflow branch substitute ErrSlowConsumer and lose
+			// the real gRPC status, so send it directly on the reserved slot.
+			sendTerminalEventResult(results, EventResult{Err: &GatewayError{Op: "stream events", Err: err}})
 			return
 		}
 	}()
@@ -1072,6 +1093,23 @@ func ensureBulkSize(name string, length int) error {
 	return nil
 }
 
+// sendTerminalEventResult enqueues a terminal EventResult with a non-blocking
+// send. The eventBufferReservedSlots reserve (beyond the eventBufferSize data
+// slots) guarantees the send lands unless a terminal result was already
+// enqueued; because this goroutine is the sole producer, at most one terminal
+// send ever races for the reserved slot, so the select default only fires when
+// the reserve is already spent — never dropping a first terminal error.
+//
+// Unlike sendEventResult, this bypasses the overflow branch: a genuine terminal
+// stream error is reported verbatim even when the data slots are full, rather
+// than being relabeled as ErrSlowConsumer.
+func sendTerminalEventResult(results chan<- EventResult, result EventResult) {
+	select {
+	case results <- result:
+	default:
+	}
+}
+
 func sendEventResult(
 	ctx context.Context,
 	results chan<- EventResult,