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/python/src/zb_mom_ww_mxgateway/__init__.py

@@ -11,6 +11,7 @@ from .generated.galaxy_repository_pb2 import (
 )
 from .events import ReplayGap
 from .errors import (
+    MalformedReplyError,
     MxAccessError,
     MxGatewayAuthenticationError,
     MxGatewayAuthorizationError,
@@ -35,6 +36,7 @@ __all__ = [
     "GalaxyRepositoryClient",
     "GatewayClient",
     "LazyBrowseNode",
+    "MalformedReplyError",
     "MxAccessError",
     "MxGatewayAuthenticationError",
     "MxGatewayAuthorizationError",

clients/python/src/zb_mom_ww_mxgateway/errors.py

@@ -53,6 +53,10 @@ class MxAccessError(MxGatewayCommandError):
     """MXAccess HRESULT or status failure."""
 
 
+class MalformedReplyError(MxGatewayError):
+    """Raised when an OK reply lacks the expected typed payload and any usable return_value fallback."""
+
+
 def map_rpc_error(operation: str, error: grpc.RpcError) -> MxGatewayTransportError:
     """Map a generated gRPC exception to the client exception hierarchy."""
 
@@ -153,8 +157,18 @@ def ensure_mxaccess_success(operation: str, reply: pb.MxCommandReply) -> pb.MxCo
 def _mxaccess_message(operation: str, reply: pb.MxCommandReply) -> str:
     status_text = reply.protocol_status.message or "MXAccess command failed"
     hresult = reply.hresult if reply.HasField("hresult") else None
-    return (
+    message = (
         f"{operation} failed: {status_text}; "
         f"session={reply.session_id}; correlation={reply.correlation_id}; "
         f"hresult={hresult}; statuses={len(reply.statuses)}"
     )
+    # Append a per-status breakdown that carries the raw `success` COM member
+    # verbatim for diagnostic parity with the other clients. `category` remains
+    # the authoritative verdict; `success` is diagnostics only.
+    for status in reply.statuses:
+        category = pb.MxStatusCategory.Name(status.category)
+        message += (
+            f" [success={status.success}, category={category}, "
+            f"detail={status.detail}, {status.diagnostic_text}]"
+        )
+    return message

clients/python/src/zb_mom_ww_mxgateway/session.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from collections.abc import AsyncIterator, Sequence
 
 from .auth import redact_secret
-from .errors import MxGatewayError, ensure_mxaccess_success
+from .errors import MalformedReplyError, MxGatewayError, ensure_mxaccess_success
 from .events import ReplayGap
 from .generated import mxaccess_gateway_pb2 as pb
 from .values import MxValueInput, to_mx_value
@@ -710,7 +710,15 @@ class Session:
             correlation_id=correlation_id,
             secrets=[verify_user_password],
         )
-        return reply.authenticate_user.user_id
+        if reply.HasField("authenticate_user"):
+            return reply.authenticate_user.user_id
+        if reply.HasField("return_value") and reply.return_value.WhichOneof("kind") == "int32_value":
+            return reply.return_value.int32_value
+        raise MalformedReplyError(
+            "authenticate_user returned a malformed reply: OK reply carried "
+            "neither the typed payload nor an int32 return_value",
+            raw_reply=reply,
+        )
 
     async def archestra_user_to_id(
         self,
@@ -730,7 +738,15 @@ class Session:
             ),
             correlation_id=correlation_id,
         )
-        return reply.archestra_user_to_id.user_id
+        if reply.HasField("archestra_user_to_id"):
+            return reply.archestra_user_to_id.user_id
+        if reply.HasField("return_value") and reply.return_value.WhichOneof("kind") == "int32_value":
+            return reply.return_value.int32_value
+        raise MalformedReplyError(
+            "archestra_user_to_id returned a malformed reply: OK reply carried "
+            "neither the typed payload nor an int32 return_value",
+            raw_reply=reply,
+        )
 
     async def add_buffered_item(
         self,
@@ -752,7 +768,15 @@ class Session:
             ),
             correlation_id=correlation_id,
         )
-        return reply.add_buffered_item.item_handle
+        if reply.HasField("add_buffered_item"):
+            return reply.add_buffered_item.item_handle
+        if reply.HasField("return_value") and reply.return_value.WhichOneof("kind") == "int32_value":
+            return reply.return_value.int32_value
+        raise MalformedReplyError(
+            "add_buffered_item returned a malformed reply: OK reply carried "
+            "neither the typed payload nor an int32 return_value",
+            raw_reply=reply,
+        )
 
     async def set_buffered_update_interval(
         self,

clients/python/tests/test_malformed_reply.py

@@ -0,0 +1,96 @@
+"""Tests for the uniform malformed-reply contract (CLI-41) and the CLI-40
+credential-redaction regression, driven through the shared fixtures.
+
+CLI-41: an OK reply that carries neither the expected typed payload nor a usable
+``return_value`` int32 fallback raises :class:`MalformedReplyError`; a legacy
+reply that populates only ``return_value`` falls back to that int32.
+
+CLI-40: an OK reply whose diagnostics echo the caller's credential must never
+surface that credential in the raised error message.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from google.protobuf.json_format import ParseDict
+
+from zb_mom_ww_mxgateway import MalformedReplyError, MxAccessError
+from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2 as pb
+
+from test_typed_command_helpers import _session_with
+
+FIXTURE_ROOT = Path(__file__).resolve().parents[2] / "proto" / "fixtures" / "behavior"
+
+
+def _load_reply(relative: str) -> pb.MxCommandReply:
+    path = FIXTURE_ROOT / relative
+    return ParseDict(json.loads(path.read_text()), pb.MxCommandReply())
+
+
+@pytest.mark.asyncio
+async def test_authenticate_user_missing_payload_raises_malformed_reply() -> None:
+    reply = _load_reply("command-replies/authenticate-user.missing-payload.reply.json")
+    session, _ = await _session_with([reply])
+
+    with pytest.raises(MalformedReplyError) as captured:
+        await session.authenticate_user(12, "operator", "any-password")
+
+    assert captured.value.raw_reply is reply
+    assert "malformed reply" in str(captured.value)
+
+
+@pytest.mark.asyncio
+async def test_authenticate_user_return_value_only_falls_back_to_int32() -> None:
+    reply = _load_reply("command-replies/authenticate-user.return-value-only.reply.json")
+    session, _ = await _session_with([reply])
+
+    user_id = await session.authenticate_user(12, "operator", "any-password")
+
+    assert user_id == 7
+
+
+@pytest.mark.asyncio
+async def test_add_buffered_item_falls_back_to_return_value_int32() -> None:
+    reply = pb.MxCommandReply(
+        session_id="session-1",
+        kind=pb.MX_COMMAND_KIND_ADD_BUFFERED_ITEM,
+        protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+        return_value=pb.MxValue(int32_value=99),
+    )
+    session, _ = await _session_with([reply])
+
+    item_handle = await session.add_buffered_item(12, "Object.Attribute", "ctx")
+
+    assert item_handle == 99
+
+
+@pytest.mark.asyncio
+async def test_add_buffered_item_missing_payload_raises_malformed_reply() -> None:
+    reply = pb.MxCommandReply(
+        session_id="session-1",
+        kind=pb.MX_COMMAND_KIND_ADD_BUFFERED_ITEM,
+        protocol_status=pb.ProtocolStatus(code=pb.PROTOCOL_STATUS_CODE_OK),
+    )
+    session, _ = await _session_with([reply])
+
+    with pytest.raises(MalformedReplyError) as captured:
+        await session.add_buffered_item(12, "Object.Attribute", "ctx")
+
+    assert captured.value.raw_reply is reply
+
+
+@pytest.mark.asyncio
+async def test_authenticate_user_echoed_credential_is_scrubbed() -> None:
+    credential = "sup3rSecretVerify9f3a2b"
+    reply = _load_reply("command-replies/authenticate-user.echoed-credential.reply.json")
+    session, _ = await _session_with([reply])
+
+    with pytest.raises(MxAccessError) as captured:
+        await session.authenticate_user(12, "operator", credential)
+
+    message = str(captured.value)
+    assert credential not in message
+    assert "[redacted]" in message