fix(galaxy): #866 map MxStatus failure details by the MxStatusDetail vocabulary, not as OPC DA quality

The gateway copies MXSTATUS_PROXY.detail verbatim, so a failure row's detail is
always an MxStatusDetail code. FromMxStatus routed any detail <= 0xFF through the
OPC DA quality table: MX_E_PlatformCommunicationError (2) on a stopped platform's
ScanState logged "Unrecognised MXAccess quality byte 0x02" and published generic
Bad (VD03 live capture), MX_E_InvalidObjectId (8) became BadNotConnected,
MX_E_Overflow (20) BadCommunicationError, and a detail in the Uncertain band
published Uncertain for a failure.

Every non-zero detail now maps per the gateway.md vocabulary (timeout,
communication, configuration, type, range, access, initialising), then by
category; the category-fallback warning logs once per (detail, category).

Claude-Session: https://claude.ai/code/session_01GT67AD99zQQqpLCVm3p7xk
This commit is contained in:
Joseph Doherty
2026-11-11 15:06:26 -05:00
parent 7a27ef1f67
commit 71b3b7f35f
2 changed files with 100 additions and 40 deletions
@@ -84,12 +84,60 @@ public sealed class StatusCodeMapTests
StatusCodeMap.FromMxStatus(s).ShouldNotBe(StatusCodeMap.Good);
}
/// <summary>Verifies that known detail codes map to their specific status codes.</summary>
/// <summary>
/// #866: a low detail is an MxStatusDetail code, not an OPC DA quality byte. Detail 8 is
/// MX_E_InvalidObjectId — it used to surface as BadNotConnected (quality byte 8).
/// </summary>
[Fact]
public void FromMxStatus_SuccessZeroAndCategoryNotOk_DetailKnown_MapsToSpecificCode()
{
var s = new MxStatusProxy { Success = 0, Category = MxStatusCategory.OperationalError, Detail = 8 /* Bad_NotConnected */ };
StatusCodeMap.FromMxStatus(s).ShouldBe(StatusCodeMap.BadNotConnected);
var s = new MxStatusProxy { Success = 0, Category = MxStatusCategory.OperationalError, Detail = 8 };
StatusCodeMap.FromMxStatus(s).ShouldBe(StatusCodeMap.BadConfigurationError);
}
/// <summary>
/// #866 live capture (VD03 2026-11-11): reading <c>JoePlatform.ScanState</c> on a deployed but
/// not-running platform returns a failure row with detail 2 = MX_E_PlatformCommunicationError,
/// which logged "Unrecognised MXAccess quality byte 0x02" and published generic Bad.
/// </summary>
[Fact]
public void FromMxStatus_PlatformCommunicationError_IsCommunicationError_AndDoesNotLogAsQuality()
{
var logger = new CapturingLogger();
var s = new MxStatusProxy { Success = 0, Category = MxStatusCategory.CommunicationError, Detail = 2 };
StatusCodeMap.FromMxStatus(s, logger).ShouldBe(StatusCodeMap.BadCommunicationError);
logger.Entries.ShouldBeEmpty();
}
/// <summary>Low MxStatusDetail codes map per the gateway.md vocabulary regardless of category.</summary>
[Theory]
[InlineData(1, 0x800A0000u)] // MX_E_RequestTimedOut → BadTimeout
[InlineData(2, 0x80050000u)] // MX_E_PlatformCommunicationError → BadCommunicationError
[InlineData(5, 0x80050000u)] // MX_E_EngineCommunicationError → BadCommunicationError
[InlineData(3, 0x80890000u)] // MX_E_InvalidPlatformId → BadConfigurationError
[InlineData(4, 0x80890000u)] // MX_E_InvalidEngineId (was BadConfigurationError by quality-byte accident)
[InlineData(6, 0x80890000u)] // MX_E_InvalidReference
[InlineData(12, 0x80000000u)] // MX_E_ResolvingObject → category (was BadDeviceFailure)
[InlineData(13, 0x80740000u)] // MX_E_WrongDataType → BadTypeMismatch
[InlineData(16, 0x80000000u)] // MX_E_IndexOutOfOrder → category (was BadSensorFailure)
[InlineData(19, 0x80740000u)] // MX_E_UnableToConvertString → BadTypeMismatch
[InlineData(20, 0x803C0000u)] // MX_E_Overflow → BadOutOfRange (was BadCommunicationError)
[InlineData(24, 0x80000000u)] // MX_E_LmxInvalidCommand → category (was BadOutOfService)
[InlineData(32, 0x80000000u)] // not a vocabulary code → category (was BadWaitingForInitialData)
public void FromMxStatus_LowDetailCodes_MapByVocabulary(int detail, uint expected)
{
var s = new MxStatusProxy { Success = 0, Category = MxStatusCategory.OperationalError, Detail = detail };
StatusCodeMap.FromMxStatus(s).ShouldBe(expected);
}
/// <summary>The category fallback logs once per (detail, category), not on every data change.</summary>
[Fact]
public void FromMxStatus_CategoryFallback_LogsOncePerDetailAndCategory()
{
var logger = new CapturingLogger();
var s = new MxStatusProxy { Success = 0, Category = MxStatusCategory.SoftwareError, Detail = 23 /* MX_E_LmxVersionMismatch */ };
for (var i = 0; i < 5; i++) StatusCodeMap.FromMxStatus(s, logger).ShouldBe(StatusCodeMap.Bad);
logger.Entries.Count.ShouldBe(1);
}
/// <summary>Verifies that non-zero DetectedBy maps to communication error when detail is zero.</summary>
@@ -155,9 +203,8 @@ public sealed class StatusCodeMapTests
}
/// <summary>
/// Invariant: a row that is not IsSuccess() must NEVER map to Good — a Good-band quality
/// byte (e.g. 216 = GoodLocalOverride) on a failure row is contradictory and falls back to
/// the category route. Uncertain-band substatuses remain allowed (uncertain is not Good).
/// Invariant: a row that is not IsSuccess() must NEVER map to Good — a detail that happens to sit in
/// the OPC DA Good band (216) is not a quality byte and routes on the category.
/// </summary>
[Fact]
public void FromMxStatus_FailureRow_GoodBandQualityByte_NeverMapsGood()
@@ -166,12 +213,12 @@ public sealed class StatusCodeMapTests
StatusCodeMap.FromMxStatus(s).ShouldBe(StatusCodeMap.BadUserAccessDenied);
}
/// <summary>An Uncertain-band quality substatus on a failure row still maps to its specific Uncertain code.</summary>
/// <summary>A failure row is Bad: a detail in the OPC DA Uncertain band (68) is not a quality byte (#866).</summary>
[Fact]
public void FromMxStatus_FailureRow_UncertainBandQualityByte_KeepsUncertainCode()
public void FromMxStatus_FailureRow_UncertainBandDetail_IsBad()
{
var s = new MxStatusProxy { Success = 0, Category = MxStatusCategory.OperationalError, Detail = 68 };
StatusCodeMap.FromMxStatus(s).ShouldBe(StatusCodeMap.UncertainLastUsableValue);
StatusCodeMap.FromMxStatus(s).ShouldBe(StatusCodeMap.Bad);
}
/// <summary>Verifies that top two bits of status codes follow OPC UA convention.</summary>