fix(modbus): review r3 - one address authority (ModbusTagAddressResolution)

N3: a keyless blob carrying the addressResolved marker was served from its
string by the driver but saved as HR[0] by the editor model / CSV path. The
precedence rule now lives in ONE pure resolver in Driver.Modbus.Contracts
(ModbusTagAddressResolution.Classify/Resolve): keys when region+address are
both present, else a string-only addressString resolved with the driver's
family (refused when it cannot parse), else refused. The marker never decides.

Consumers that now ask it instead of restating it: the driver's tag reader
(ModbusTagDefinitionFactory.FromTagConfig), the deploy gate (Inspect /
DescribeRejection), the editor model (AddressShape / IsStringOnly /
HasKeyAddress / ResolveWith, ToJson stamping, Validate), the CSV export cells
and the editor hint. The model writes keys only when it loaded them or a field
was authored - never defaults it did not resolve (also closes two divergences
the new matrix found: malformed-string+marker and non-string addressString were
saved as HR[0]).

One table-driven test (ModbusAddressAuthorityAgreementTests) runs 15 persisted
shapes through driver, deploy gate, model load/save/Validate and the real CSV
export->import under all four families; breaking the CSV export or reverting
the model to the marker rule fails it.

Minors: m1 CSV address cells keep the string+marker while it still describes
them (lossless unchanged round trip), drop it when contradicted, and the review
grid reports the drop; m2 the pre-lane test uses the real export residual; m3
unmarked string-only + typed-cell case added; m4 stale docs/summary and the
unused factory parameter removed.

Refs #741

Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT
This commit is contained in:
Joseph Doherty
2026-10-22 16:46:21 -04:00
parent 13b29e8d4a
commit 92749402b5
12 changed files with 807 additions and 206 deletions
@@ -55,7 +55,8 @@ public sealed class ModbusFamilyWiringTests
/// <summary>
/// Fix round 1 (review m2): persisted region/address are authoritative over an addressString, so a
/// later Family / MelsecSubFamily change can never silently remap a live tag the editor resolved.
/// later Family / MelsecSubFamily change can never silently remap a live tag the editor resolved. (Since
/// fix round 3 the keys win by PRESENCE; the marker in this blob is display state only.)
/// </summary>
[Fact]
public void Persisted_resolved_keys_win_over_the_address_string_so_a_family_change_cannot_remap()
@@ -69,11 +70,6 @@ public sealed class ModbusFamilyWiringTests
}
}
/// <summary>
/// Fix round 2 (review r1 N1): region/address that were merely STAMPED (an unmarked string beside them —
/// what a model round-trip of a string-only tag used to produce) never win: the string is resolved with
/// the driver's family, so the tag cannot collapse onto HoldingRegisters[0].
/// </summary>
/// <summary>
/// Fix round 3 (review r2 N2): the persisted-shape matrix. Every shape that carries region + address loads
/// from them under every family — including the pre-#741 "keys + addressString, no marker" row, which the
@@ -0,0 +1,64 @@
using Shouldly;
using Xunit;
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
/// <summary>
/// #741 fix round 4 (review r3 N3): <see cref="ModbusTagAddressResolution"/> is the one authority for which part
/// of a Modbus TagConfig names the address. The cross-consumer agreement matrix lives in AdminUI.Tests
/// (<c>ModbusAddressAuthorityAgreementTests</c>); these pin the resolver's own classification and refusals.
/// </summary>
[Trait("Category", "Unit")]
public sealed class ModbusTagAddressResolutionTests
{
[Theory]
[InlineData("""{"region":"InputRegisters","address":5}""", ModbusAddressShape.Keys)]
[InlineData("""{"region":"HoldingRegisters","address":0,"addressString":"D100"}""", ModbusAddressShape.Keys)]
[InlineData("""{"addressString":"D100","addressResolved":true,"region":"HoldingRegisters","address":100}""", ModbusAddressShape.Keys)]
[InlineData("""{"addressString":"40011:F"}""", ModbusAddressShape.StringOnly)]
[InlineData("""{"addressString":"40011:F","addressResolved":true}""", ModbusAddressShape.StringOnly)]
[InlineData("""{"addressString":"40011:F","region":"InputRegisters"}""", ModbusAddressShape.StringOnly)]
[InlineData("""{"addressString":"ZZ9"}""", ModbusAddressShape.StringOnly)]
[InlineData("""{"addressString":5}""", ModbusAddressShape.InvalidAddressString)]
[InlineData("""{"addressString":" "}""", ModbusAddressShape.NoAddress)]
[InlineData("""{"addressString":null}""", ModbusAddressShape.NoAddress)]
[InlineData("""{}""", ModbusAddressShape.NoAddress)]
[InlineData("""[1]""", ModbusAddressShape.NoAddress)]
[InlineData("""not json""", ModbusAddressShape.NoAddress)]
public void Classify_decides_shape_by_key_presence_never_by_the_marker(string json, ModbusAddressShape shape)
=> ModbusTagAddressResolution.Classify(json).ShouldBe(shape);
[Fact]
public void A_string_only_blob_is_refused_with_a_reason_when_the_family_cannot_parse_it()
{
var r = ModbusTagAddressResolution.Resolve("""{"addressString":"D100"}""", ModbusFamily.Generic, MelsecFamily.Q_L_iQR);
r.IsResolved.ShouldBeFalse();
r.Shape.ShouldBe(ModbusAddressShape.StringOnly);
r.Refusal.ShouldNotBeNull().ShouldContain("D100");
var melsec = ModbusTagAddressResolution.Resolve("""{"addressString":"D100"}""", ModbusFamily.MELSEC, MelsecFamily.Q_L_iQR);
melsec.Address.ShouldNotBeNull().Address.ShouldBe((ushort)100);
}
[Fact]
public void Keys_are_read_strictly_and_a_bit_region_is_coerced_to_Bool()
{
ModbusTagAddressResolution.Resolve("""{"region":"Holding","address":1}""", ModbusFamily.Generic, MelsecFamily.Q_L_iQR)
.IsResolved.ShouldBeFalse();
ModbusTagAddressResolution.Resolve("""{"region":"HoldingRegisters","address":70000}""", ModbusFamily.Generic, MelsecFamily.Q_L_iQR)
.IsResolved.ShouldBeFalse();
var coil = ModbusTagAddressResolution.Resolve("""{"region":"Coils","address":3,"dataType":"Int16"}""", ModbusFamily.Generic, MelsecFamily.Q_L_iQR);
coil.Address.ShouldNotBeNull().DataType.ShouldBe(ModbusDataType.Bool);
}
[Fact]
public void AddressStringDescribes_matches_only_the_fields_some_family_parses_it_to()
{
ModbusTagAddressResolution.AddressStringDescribes("D100", ModbusRegion.HoldingRegisters, 100, ModbusDataType.Int16,
ModbusByteOrder.BigEndian, 0, 0).ShouldBeTrue();
ModbusTagAddressResolution.AddressStringDescribes("D100", ModbusRegion.HoldingRegisters, 101, ModbusDataType.Int16,
ModbusByteOrder.BigEndian, 0, 0).ShouldBeFalse();
ModbusTagAddressResolution.AddressStringDescribes("ZZ9", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16,
ModbusByteOrder.BigEndian, 0, 0).ShouldBeFalse();
}
}