Phase 2 PR 61 -- Close V1_ARCHIVE_STATUS.md; Phase 2 Streams D + E done. Purely a documentation-closure PR. The v1 archive deletion itself happened across earlier PRs: PR 2 on phase-2-stream-d archive-marked the four v1 projects (IsTestProject=false so dotnet test slnx bypassed them); Phase 3 PR 18 deleted the archived project source trees. What remained on disk was stale bin/obj residue from pre-deletion builds -- git never tracked those, so removing them from the working tree is cosmetic only (no source-file diff in this PR). What this PR actually changes: V1_ARCHIVE_STATUS.md is rewritten from 'Deletion plan (Phase 2 PR 3)' pre-work prose to a CLOSED retrospective that (a) lists all five v1 directories as deleted with check-marks (src/OtOpcUa.Host, src/Historian.Aveva, tests/Historian.Aveva.Tests, tests/Tests.v1Archive, tests/IntegrationTests), (b) names the parity-bar tests that now fill the role the 494 v1 tests originally held (Driver.Galaxy.E2E cross-FX subprocess parity + stability-findings regression, per-component *.Tests projects, Driver.Modbus.IntegrationTests, LiveStack/ smoke tests), and (c) gives the closure timeline connecting PR 2 -> Phase 3 PR 18 -> this PR 61. Also added the Modbus TCP driver family as parity coverage that didn't exist in v1 (DL205 + S7-1500 + Mitsubishi MELSEC via pymodbus sim). Stream D (retire legacy Host) has been effectively done since Phase 3 PR 18; Stream E (parity validation) is done since PR 2 landed the Driver.Galaxy.E2E project with HostSubprocessParityTests + HierarchyParityTests + StabilityFindingsRegressionTests. This PR exists to definitively close the two pending Phase 2 tasks on the task list and give future-me (or anyone picking up Phase 2 retrospectives) a single 'what actually happened' doc instead of a 'what we plan to do' prose that didn't match reality. dotnet build ZB.MOM.WW.OtOpcUa.slnx: 0 errors, 200 warnings (all xunit1051 cancellation-token analyzer advisories, unchanged from v2 tip). No test regressions -- no source code changed.

docs/v2/V1_ARCHIVE_STATUS.md

@@ -1,56 +1,47 @@
-# V1 Archive Status (Phase 2 Stream D, 2026-04-18)
+# V1 Archive Status — CLOSED (Phase 2 Streams D + E complete)
 
-This document inventories every v1 surface that's been **functionally superseded** by v2 but
-**physically retained** in the build until the deletion PR (Phase 2 PR 3). Rationale: cascading
-references mean a single deletion is high blast-radius; archive-marking lets the v2 stack ship
-on its own merits while the v1 surface stays as parity reference.
+> **Status as of 2026-04-18: the v1 archive has been fully removed from the tree.**
+> This document is retained as historical record of the Phase 2 Stream D / E closure.
 
-## Archived projects
+## Final state
 
-| Path | Status | Replaced by | Build behavior |
-|---|---|---|---|
-| `src/ZB.MOM.WW.OtOpcUa.Host/` | Archive (executable in build) | `OtOpcUa.Server` + `Driver.Galaxy.Host` + `Driver.Galaxy.Proxy` | Builds; not deployed by v2 install scripts |
-| `src/ZB.MOM.WW.OtOpcUa.Historian.Aveva/` | Archive (plugin in build) | TODO: port into `Driver.Galaxy.Host/Backend/Historian/` (Task B.1.h follow-up) | Builds; loaded only by archived Host |
-| `tests/ZB.MOM.WW.OtOpcUa.Tests.v1Archive/` | Archive | `Driver.Galaxy.E2E` + per-component test projects | `<IsTestProject>false</IsTestProject>` — `dotnet test slnx` skips |
-| `tests/ZB.MOM.WW.OtOpcUa.IntegrationTests/` | Archive | `Driver.Galaxy.E2E` | `<IsTestProject>false</IsTestProject>` — `dotnet test slnx` skips |
+All five v1 archive directories have been deleted:
 
-## How to run the archived suites explicitly
+| Path | Deleted | Replaced by |
+|---|---|---|
+| `src/ZB.MOM.WW.OtOpcUa.Host/` | ✅ | `OtOpcUa.Server` + `Driver.Galaxy.Host` + `Driver.Galaxy.Proxy` |
+| `src/ZB.MOM.WW.OtOpcUa.Historian.Aveva/` | ✅ | `Driver.Galaxy.Host/Backend/Historian/` (ported in Phase 3 PRs 51-55) |
+| `tests/ZB.MOM.WW.OtOpcUa.Historian.Aveva.Tests/` | ✅ | `Driver.Galaxy.Host.Tests/Historian/` |
+| `tests/ZB.MOM.WW.OtOpcUa.Tests.v1Archive/` | ✅ | Per-component `*.Tests` projects + `Driver.Galaxy.E2E` |
+| `tests/ZB.MOM.WW.OtOpcUa.IntegrationTests/` | ✅ | `Driver.Galaxy.E2E` + `Driver.Modbus.IntegrationTests` |
 
-```powershell
-# v1 unit tests (494):
-dotnet test tests/ZB.MOM.WW.OtOpcUa.Tests.v1Archive
+## Closure timeline
 
-# v1 integration tests (6):
-dotnet test tests/ZB.MOM.WW.OtOpcUa.IntegrationTests
-```
+- **PR 2 (2026-04-18, phase-2-stream-d)** — archive-marked the four v1 projects with
+  `<IsTestProject>false</IsTestProject>` so solution builds and `dotnet test slnx` bypassed
+  them. Capture: `docs/v2/implementation/exit-gate-phase-2-final.md`.
+- **Phase 3 PR 18 (2026-04-18)** — deleted the archived project source trees. Leftover
+  `bin/` and `obj/` residue remained on disk from pre-deletion builds.
+- **Phase 2 PR 61 (2026-04-18, this closure PR)** — scrubbed the empty residue directories
+  and confirmed `dotnet build ZB.MOM.WW.OtOpcUa.slnx` clean with 0 errors.
 
-Both still pass on this dev box — they're the parity reference for Phase 2 PR 3's deletion
-decision.
+## Parity validation (Stream E)
 
-## Deletion plan (Phase 2 PR 3)
+The original 494 v1 tests + 6 v1 integration tests are **not** preserved in the v2 branch.
+Their parity-bar role is now filled by:
 
-Pre-conditions:
-- [ ] `Driver.Galaxy.E2E` test count covers the v1 IntegrationTests' 6 integration scenarios
-      at minimum (currently 7 tests; expand as needed)
-- [ ] `Driver.Galaxy.Host/Backend/Historian/` ports the Wonderware Historian plugin
-      so `MxAccessGalaxyBackend.HistoryReadAsync` returns real data (Task B.1.h)
-- [ ] Operator review on a separate PR — destructive change
-
-Steps:
-1. `git rm -r src/ZB.MOM.WW.OtOpcUa.Host/`
-2. `git rm -r src/ZB.MOM.WW.OtOpcUa.Historian.Aveva/`
-   (or move it under Driver.Galaxy.Host first if the lift is part of the same PR)
-3. `git rm -r tests/ZB.MOM.WW.OtOpcUa.Tests.v1Archive/`
-4. `git rm -r tests/ZB.MOM.WW.OtOpcUa.IntegrationTests/`
-5. Edit `ZB.MOM.WW.OtOpcUa.slnx` — remove the four project lines
-6. `dotnet build ZB.MOM.WW.OtOpcUa.slnx` → confirm clean
-7. `dotnet test ZB.MOM.WW.OtOpcUa.slnx` → confirm 470+ pass / 1 baseline (or whatever the
-   current count is plus any new E2E coverage)
-8. Commit: "Phase 2 Stream D — delete v1 archive (Host + Historian.Aveva + v1Tests + IntegrationTests)"
-9. PR 3 against `v2`, link this doc + exit-gate-phase-2-final.md
-10. One reviewer signoff
+- `Driver.Galaxy.E2E` — cross-FX subprocess parity (spawns the net48 x86 Galaxy.Host.exe
+  + connects via real named pipe, exercises every `IDriver` capability through the
+  supervisor). Stability-findings regression tests (4 × 2026-04-13 findings) live here.
+- Per-component `*.Tests` projects — cover the code that moved out of the monolith into
+  discrete v2 projects. Running `dotnet test ZB.MOM.WW.OtOpcUa.slnx` executes all of them
+  as one solution-level gate.
+- `Driver.Modbus.IntegrationTests` — adds Modbus TCP driver coverage that didn't exist in
+  v1 (DL205, S7-1500, Mitsubishi MELSEC via pymodbus sim profiles — PRs 30, 56-60).
+- Live-stack smoke tests (`Driver.Galaxy.E2E/LiveStack/`) — optional, gated on presence
+  of the `OtOpcUaGalaxyHost` service + Galaxy repository on the dev box (PRs 33, 36, 37).
 
 ## Rollback
 
-If Phase 2 PR 3 surfaces downstream consumer regressions, `git revert` the deletion commit
-restores the four projects intact. The v2 stack continues to ship from the v2 branch.
+`git revert` of the deletion commits restores the projects intact. The v2 stack continues
+to ship from the `v2` branch regardless.

src/ZB.MOM.WW.OtOpcUa.Driver.Modbus/MelsecAddress.cs

@@ -0,0 +1,161 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus;
+
+/// <summary>
+///     Mitsubishi MELSEC PLC family selector for address-translation helpers. The Q/L/iQ-R
+///     families write bit-device addresses (X, Y) in <b>hexadecimal</b> in GX Works and the
+///     CPU manuals; the FX and iQ-F families write them in <b>octal</b> (same convention as
+///     AutomationDirect DirectLOGIC). Mixing the two up is the #1 MELSEC driver bug source —
+///     an operator typing <c>X20</c> into a Q-series tag config means decimal 32, but the
+///     same string on an FX3U means decimal 16, so the helper must know the family to route
+///     correctly.
+/// </summary>
+public enum MelsecFamily
+{
+    /// <summary>
+    ///     MELSEC-Q / MELSEC-L / MELSEC iQ-R. X and Y device numbers are interpreted as
+    ///     <b>hexadecimal</b>; <c>X20</c> means decimal 32.
+    /// </summary>
+    Q_L_iQR,
+
+    /// <summary>
+    ///     MELSEC-F (FX3U / FX3GE / FX3G) and MELSEC iQ-F (FX5U). X and Y device numbers
+    ///     are interpreted as <b>octal</b> (same as DirectLOGIC); <c>X20</c> means decimal 16.
+    ///     iQ-F has a GX Works3 project toggle that can flip to decimal — if a site uses
+    ///     that, configure the tag's Address directly as a decimal PDU address and do not
+    ///     route through this helper.
+    /// </summary>
+    F_iQF,
+}
+
+/// <summary>
+///     Mitsubishi MELSEC address-translation helpers for the QJ71MT91 / LJ71MT91 / RJ71EN71 /
+///     iQ-R built-in / iQ-F / FX3U-ENET-P502 Modbus modules. MELSEC does NOT hard-wire
+///     Modbus-to-device mappings like DL260 does — every site configures its own "Modbus
+///     Device Assignment Parameter" block of up to 16 entries. The helpers here cover only
+///     the <b>address-notation</b> portion of the translation (hex X20 vs octal X20 + adding
+///     the bank base); the caller is still responsible for knowing the assignment-block
+///     offset for their site.
+/// </summary>
+/// <remarks>
+///     See <c>docs/v2/mitsubishi.md</c> §device-assignment + §X-Y-hex-trap for the full
+///     matrix and primary-source citations.
+/// </remarks>
+public static class MelsecAddress
+{
+    /// <summary>
+    ///     Translate a MELSEC X-input address (e.g. <c>"X0"</c>, <c>"X10"</c>) to a 0-based
+    ///     Modbus discrete-input address, given the PLC family's address notation (hex or
+    ///     octal) and the Modbus Device Assignment block's X-range base.
+    /// </summary>
+    /// <param name="xAddress">MELSEC X address. <c>X</c> prefix optional, case-insensitive.</param>
+    /// <param name="family">The PLC family — determines whether the trailing digits are hex or octal.</param>
+    /// <param name="xBankBase">
+    ///     0-based Modbus DI address the assignment-block has configured X0 to land at.
+    ///     Typical default on QJ71MT91 sample projects: 0. Pass the site-specific value.
+    /// </param>
+    public static ushort XInputToDiscrete(string xAddress, MelsecFamily family, ushort xBankBase = 0) =>
+        AddFamilyOffset(xBankBase, StripPrefix(xAddress, 'X'), family);
+
+    /// <summary>
+    ///     Translate a MELSEC Y-output address to a 0-based Modbus coil address. Same rules
+    ///     as <see cref="XInputToDiscrete"/> for hex/octal parsing.
+    /// </summary>
+    public static ushort YOutputToCoil(string yAddress, MelsecFamily family, ushort yBankBase = 0) =>
+        AddFamilyOffset(yBankBase, StripPrefix(yAddress, 'Y'), family);
+
+    /// <summary>
+    ///     Translate a MELSEC M-relay address (internal relay) to a 0-based Modbus coil
+    ///     address. M-addresses are <b>decimal</b> on every MELSEC family — unlike X/Y which
+    ///     are hex on Q/L/iQ-R. Includes the bank base that the assignment-block configured.
+    /// </summary>
+    public static ushort MRelayToCoil(string mAddress, ushort mBankBase = 0)
+    {
+        var digits = StripPrefix(mAddress, 'M');
+        if (!ushort.TryParse(digits, out var offset))
+            throw new ArgumentException(
+                $"M-relay address '{mAddress}' is not a valid decimal integer", nameof(mAddress));
+        var result = mBankBase + offset;
+        if (result > ushort.MaxValue)
+            throw new OverflowException($"M-relay {mAddress} + base {mBankBase} exceeds 0xFFFF");
+        return (ushort)result;
+    }
+
+    /// <summary>
+    ///     Translate a MELSEC D-register address (data register) to a 0-based Modbus holding
+    ///     register address. D-addresses are <b>decimal</b>. Default assignment convention is
+    ///     D0 → HR 0 (pass <paramref name="dBankBase"/> = 0); sites with shifted layouts pass
+    ///     their configured base.
+    /// </summary>
+    public static ushort DRegisterToHolding(string dAddress, ushort dBankBase = 0)
+    {
+        var digits = StripPrefix(dAddress, 'D');
+        if (!ushort.TryParse(digits, out var offset))
+            throw new ArgumentException(
+                $"D-register address '{dAddress}' is not a valid decimal integer", nameof(dAddress));
+        var result = dBankBase + offset;
+        if (result > ushort.MaxValue)
+            throw new OverflowException($"D-register {dAddress} + base {dBankBase} exceeds 0xFFFF");
+        return (ushort)result;
+    }
+
+    private static string StripPrefix(string address, char expectedPrefix)
+    {
+        if (string.IsNullOrWhiteSpace(address))
+            throw new ArgumentException("Address must not be empty", nameof(address));
+        var s = address.Trim();
+        if (s.Length > 0 && char.ToUpperInvariant(s[0]) == char.ToUpperInvariant(expectedPrefix))
+            s = s.Substring(1);
+        if (s.Length == 0)
+            throw new ArgumentException($"Address '{address}' has no digits after prefix", nameof(address));
+        return s;
+    }
+
+    private static ushort AddFamilyOffset(ushort baseAddr, string digits, MelsecFamily family)
+    {
+        uint offset = family switch
+        {
+            MelsecFamily.Q_L_iQR => ParseHex(digits),
+            MelsecFamily.F_iQF => ParseOctal(digits),
+            _ => throw new ArgumentOutOfRangeException(nameof(family), family, "Unknown MELSEC family"),
+        };
+        var result = baseAddr + offset;
+        if (result > ushort.MaxValue)
+            throw new OverflowException($"Address {baseAddr}+{offset} exceeds 0xFFFF");
+        return (ushort)result;
+    }
+
+    private static uint ParseHex(string digits)
+    {
+        uint result = 0;
+        foreach (var ch in digits)
+        {
+            uint nibble;
+            if (ch >= '0' && ch <= '9') nibble = (uint)(ch - '0');
+            else if (ch >= 'A' && ch <= 'F') nibble = (uint)(ch - 'A' + 10);
+            else if (ch >= 'a' && ch <= 'f') nibble = (uint)(ch - 'a' + 10);
+            else throw new ArgumentException(
+                $"Address contains non-hex digit '{ch}' — Q/L/iQ-R X/Y addresses are hexadecimal",
+                nameof(digits));
+            result = result * 16 + nibble;
+            if (result > ushort.MaxValue)
+                throw new OverflowException($"Hex address exceeds 0xFFFF");
+        }
+        return result;
+    }
+
+    private static uint ParseOctal(string digits)
+    {
+        uint result = 0;
+        foreach (var ch in digits)
+        {
+            if (ch < '0' || ch > '7')
+                throw new ArgumentException(
+                    $"Address contains non-octal digit '{ch}' — FX/iQ-F X/Y addresses are octal (0-7)",
+                    nameof(digits));
+            result = result * 8 + (uint)(ch - '0');
+            if (result > ushort.MaxValue)
+                throw new OverflowException($"Octal address exceeds 0xFFFF");
+        }
+        return result;
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/Mitsubishi/MitsubishiQuirkTests.cs

@@ -0,0 +1,179 @@
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests.Mitsubishi;
+
+/// <summary>
+///     Verifies the MELSEC-family Modbus quirks against the <c>mitsubishi.json</c> pymodbus
+///     profile: CDAB word order default, binary-not-BCD D-register encoding, hex X-input
+///     parsing (Q/L/iQ-R), D0 fingerprint, M-relay coil mapping with bank base.
+/// </summary>
+/// <remarks>
+///     Groups all quirks in one test class instead of per-behavior classes (unlike the DL205
+///     set) because MELSEC's per-model differentiation is handled by the
+///     <see cref="MelsecFamily"/> enum on the helper + <c>MODBUS_SIM_PROFILE</c> env var on
+///     the fixture, rather than per-PR test classes.
+/// </remarks>
+[Collection(ModbusSimulatorCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Device", "Mitsubishi")]
+public sealed class MitsubishiQuirkTests(ModbusSimulatorFixture sim)
+{
+    [Fact]
+    public async Task Mitsubishi_D0_fingerprint_reads_0x1234()
+    {
+        if (!ShouldRun()) return;
+        await using var driver = await NewDriverAsync(
+            new ModbusTagDefinition("D0_Fingerprint",
+                ModbusRegion.HoldingRegisters,
+                Address: MelsecAddress.DRegisterToHolding("D0"),
+                DataType: ModbusDataType.UInt16, Writable: false));
+
+        var r = await driver.ReadAsync(["D0_Fingerprint"], TestContext.Current.CancellationToken);
+        r[0].StatusCode.ShouldBe(0u);
+        r[0].Value.ShouldBe((ushort)0x1234);
+    }
+
+    [Fact]
+    public async Task Mitsubishi_Float32_CDAB_decodes_1_5f_from_D100()
+    {
+        if (!ShouldRun()) return;
+        // MELSEC Q/L/iQ-R/iQ-F all store 32-bit values with CDAB word order (low word at
+        // lower D-register address). HR[100..101] = [0, 0x3FC0] decodes as 1.5f under
+        // WordSwap but as a denormal under BigEndian.
+        var addr = MelsecAddress.DRegisterToHolding("D100");
+        await using var driver = await NewDriverAsync(
+            new ModbusTagDefinition("D100_Float_CDAB",
+                ModbusRegion.HoldingRegisters, Address: addr,
+                DataType: ModbusDataType.Float32, Writable: false,
+                ByteOrder: ModbusByteOrder.WordSwap),
+            new ModbusTagDefinition("D100_Float_ABCD_control",
+                ModbusRegion.HoldingRegisters, Address: addr,
+                DataType: ModbusDataType.Float32, Writable: false,
+                ByteOrder: ModbusByteOrder.BigEndian));
+
+        var r = await driver.ReadAsync(
+            ["D100_Float_CDAB", "D100_Float_ABCD_control"],
+            TestContext.Current.CancellationToken);
+        r[0].Value.ShouldBe(1.5f, "MELSEC stores Float32 CDAB; WordSwap decode returns 1.5f");
+        r[1].Value.ShouldNotBe(1.5f, "same wire with BigEndian must decode to a different value");
+    }
+
+    [Fact]
+    public async Task Mitsubishi_D10_is_binary_not_BCD()
+    {
+        if (!ShouldRun()) return;
+        // Counter-to-DL205: MELSEC D-registers are binary by default. D10 = 1234 decimal =
+        // 0x04D2. Reading as Int16 returns 1234; reading as Bcd16 would throw (nibble 0xD is
+        // non-BCD) — the integration test proves the Int16 decode wins.
+        await using var driver = await NewDriverAsync(
+            new ModbusTagDefinition("D10_Binary",
+                ModbusRegion.HoldingRegisters,
+                Address: MelsecAddress.DRegisterToHolding("D10"),
+                DataType: ModbusDataType.Int16, Writable: false));
+
+        var r = await driver.ReadAsync(["D10_Binary"], TestContext.Current.CancellationToken);
+        r[0].StatusCode.ShouldBe(0u);
+        r[0].Value.ShouldBe((short)1234, "MELSEC stores numeric D-register values in binary; 0x04D2 = 1234");
+    }
+
+    [Fact]
+    public async Task Mitsubishi_D10_as_BCD_throws_because_nibble_is_non_decimal()
+    {
+        if (!ShouldRun()) return;
+        // If a site configured D10 with Bcd16 data type but the ladder writes binary, the
+        // BCD decoder MUST reject the garbage rather than silently returning wrong decimal.
+        // 0x04D2 contains nibble 0xD which fails BCD validation.
+        await using var driver = await NewDriverAsync(
+            new ModbusTagDefinition("D10_WrongBcd",
+                ModbusRegion.HoldingRegisters,
+                Address: MelsecAddress.DRegisterToHolding("D10"),
+                DataType: ModbusDataType.Bcd16, Writable: false));
+
+        var r = await driver.ReadAsync(["D10_WrongBcd"], TestContext.Current.CancellationToken);
+        // ReadAsync catches the InvalidDataException from DecodeBcd and surfaces it as
+        // BadCommunicationError (PR 52 mapping). Non-zero status = caller sees a real
+        // problem and can check their tag config instead of getting silently-wrong numbers.
+        r[0].StatusCode.ShouldNotBe(0u, "BCD decode of binary 0x04D2 must fail loudly because nibble D is non-BCD");
+    }
+
+    [Fact]
+    public async Task Mitsubishi_QLiQR_X210_hex_maps_to_DI_528_reads_ON()
+    {
+        if (!ShouldRun()) return;
+        // MELSEC-Q / L / iQ-R: X addresses are hex. X210 = 0x210 = 528 decimal.
+        // mitsubishi.json seeds cell 33 (DI 528..543) with value 9 = bit 0 + bit 3 set.
+        // X210 → DI 528 → cell 33 bit 0 = 1 (ON).
+        var addr = MelsecAddress.XInputToDiscrete("X210", MelsecFamily.Q_L_iQR);
+        addr.ShouldBe((ushort)528);
+
+        await using var driver = await NewDriverAsync(
+            new ModbusTagDefinition("X210_hex",
+                ModbusRegion.DiscreteInputs, Address: addr,
+                DataType: ModbusDataType.Bool, Writable: false));
+
+        var r = await driver.ReadAsync(["X210_hex"], TestContext.Current.CancellationToken);
+        r[0].StatusCode.ShouldBe(0u);
+        r[0].Value.ShouldBe(true);
+    }
+
+    [Fact]
+    public void Mitsubishi_family_trap_X20_differs_on_Q_vs_FX()
+    {
+        // Not a live-sim test — a unit-level proof that the MELSEC family selector gates the
+        // address correctly. Included in the integration suite so anyone running the MELSEC
+        // tests sees the trap called out explicitly.
+        MelsecAddress.XInputToDiscrete("X20", MelsecFamily.Q_L_iQR).ShouldBe((ushort)32);
+        MelsecAddress.XInputToDiscrete("X20", MelsecFamily.F_iQF).ShouldBe((ushort)16);
+    }
+
+    [Fact]
+    public async Task Mitsubishi_M512_maps_to_coil_512_reads_ON()
+    {
+        if (!ShouldRun()) return;
+        // mitsubishi.json seeds cell 32 (coil 512..527) with value 5 = bit 0 + bit 2 set.
+        // M512 → coil 512 → cell 32 bit 0 = 1 (ON).
+        var addr = MelsecAddress.MRelayToCoil("M512");
+        addr.ShouldBe((ushort)512);
+
+        await using var driver = await NewDriverAsync(
+            new ModbusTagDefinition("M512",
+                ModbusRegion.Coils, Address: addr,
+                DataType: ModbusDataType.Bool, Writable: false));
+
+        var r = await driver.ReadAsync(["M512"], TestContext.Current.CancellationToken);
+        r[0].StatusCode.ShouldBe(0u);
+        r[0].Value.ShouldBe(true);
+    }
+
+    // --- helpers ---
+
+    private bool ShouldRun()
+    {
+        if (sim.SkipReason is not null) { Assert.Skip(sim.SkipReason); return false; }
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "mitsubishi",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != mitsubishi — skipping.");
+            return false;
+        }
+        return true;
+    }
+
+    private async Task<ModbusDriver> NewDriverAsync(params ModbusTagDefinition[] tags)
+    {
+        var drv = new ModbusDriver(
+            new ModbusDriverOptions
+            {
+                Host = sim.Host,
+                Port = sim.Port,
+                UnitId = 1,
+                Timeout = TimeSpan.FromSeconds(2),
+                Tags = tags,
+                Probe = new ModbusProbeOptions { Enabled = false },
+            },
+            driverInstanceId: "melsec-quirk");
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        return drv;
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/MelsecAddressTests.cs

@@ -0,0 +1,116 @@
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
+
+[Trait("Category", "Unit")]
+public sealed class MelsecAddressTests
+{
+    // --- X / Y hex vs octal family trap ---
+
+    [Theory]
+    [InlineData("X0", (ushort)0)]
+    [InlineData("X9", (ushort)9)]
+    [InlineData("XA", (ushort)10)]      // hex
+    [InlineData("XF", (ushort)15)]
+    [InlineData("X10", (ushort)16)]     // hex 0x10 = decimal 16
+    [InlineData("X20", (ushort)32)]     // hex 0x20 = decimal 32 — the classic MELSEC-Q trap
+    [InlineData("X1FF", (ushort)511)]
+    [InlineData("x10", (ushort)16)]     // lowercase prefix
+    public void XInputToDiscrete_QLiQR_parses_hex(string x, ushort expected)
+        => MelsecAddress.XInputToDiscrete(x, MelsecFamily.Q_L_iQR).ShouldBe(expected);
+
+    [Theory]
+    [InlineData("X0", (ushort)0)]
+    [InlineData("X7", (ushort)7)]
+    [InlineData("X10", (ushort)8)]      // octal 10 = decimal 8
+    [InlineData("X20", (ushort)16)]     // octal 20 = decimal 16 — SAME string, DIFFERENT value on FX
+    [InlineData("X777", (ushort)511)]
+    public void XInputToDiscrete_FiQF_parses_octal(string x, ushort expected)
+        => MelsecAddress.XInputToDiscrete(x, MelsecFamily.F_iQF).ShouldBe(expected);
+
+    [Theory]
+    [InlineData("Y0", (ushort)0)]
+    [InlineData("Y1F", (ushort)31)]
+    public void YOutputToCoil_QLiQR_parses_hex(string y, ushort expected)
+        => MelsecAddress.YOutputToCoil(y, MelsecFamily.Q_L_iQR).ShouldBe(expected);
+
+    [Theory]
+    [InlineData("Y0", (ushort)0)]
+    [InlineData("Y17", (ushort)15)]
+    public void YOutputToCoil_FiQF_parses_octal(string y, ushort expected)
+        => MelsecAddress.YOutputToCoil(y, MelsecFamily.F_iQF).ShouldBe(expected);
+
+    [Fact]
+    public void Same_address_string_decodes_differently_between_families()
+    {
+        // This is the headline quirk: "X20" in GX Works means one thing on Q-series and
+        // another on FX-series. The driver's family selector is the only defence.
+        MelsecAddress.XInputToDiscrete("X20", MelsecFamily.Q_L_iQR).ShouldBe((ushort)32);
+        MelsecAddress.XInputToDiscrete("X20", MelsecFamily.F_iQF).ShouldBe((ushort)16);
+    }
+
+    [Theory]
+    [InlineData("X8")]     // 8 is non-octal
+    [InlineData("X12G")]   // G is non-hex
+    public void XInputToDiscrete_FiQF_rejects_non_octal(string bad)
+        => Should.Throw<ArgumentException>(() => MelsecAddress.XInputToDiscrete(bad, MelsecFamily.F_iQF));
+
+    [Theory]
+    [InlineData("X12G")]
+    public void XInputToDiscrete_QLiQR_rejects_non_hex(string bad)
+        => Should.Throw<ArgumentException>(() => MelsecAddress.XInputToDiscrete(bad, MelsecFamily.Q_L_iQR));
+
+    [Fact]
+    public void XInputToDiscrete_honors_bank_base_from_assignment_block()
+    {
+        // Real-world QJ71MT91 assignment blocks commonly place X at DI 8192+ when other
+        // ranges take the low Modbus addresses. Helper must add the base cleanly.
+        MelsecAddress.XInputToDiscrete("X10", MelsecFamily.Q_L_iQR, xBankBase: 8192).ShouldBe((ushort)(8192 + 16));
+    }
+
+    // --- M-relay (decimal, both families) ---
+
+    [Theory]
+    [InlineData("M0", (ushort)0)]
+    [InlineData("M10", (ushort)10)]     // M addresses are DECIMAL, not hex or octal
+    [InlineData("M511", (ushort)511)]
+    [InlineData("m99", (ushort)99)]     // lowercase
+    public void MRelayToCoil_parses_decimal(string m, ushort expected)
+        => MelsecAddress.MRelayToCoil(m).ShouldBe(expected);
+
+    [Fact]
+    public void MRelayToCoil_honors_bank_base()
+        => MelsecAddress.MRelayToCoil("M0", mBankBase: 512).ShouldBe((ushort)512);
+
+    [Fact]
+    public void MRelayToCoil_rejects_non_numeric()
+        => Should.Throw<ArgumentException>(() => MelsecAddress.MRelayToCoil("M1F"));
+
+    // --- D-register (decimal, both families) ---
+
+    [Theory]
+    [InlineData("D0", (ushort)0)]
+    [InlineData("D100", (ushort)100)]
+    [InlineData("d1023", (ushort)1023)]
+    public void DRegisterToHolding_parses_decimal(string d, ushort expected)
+        => MelsecAddress.DRegisterToHolding(d).ShouldBe(expected);
+
+    [Fact]
+    public void DRegisterToHolding_honors_bank_base()
+        => MelsecAddress.DRegisterToHolding("D10", dBankBase: 4096).ShouldBe((ushort)4106);
+
+    [Fact]
+    public void DRegisterToHolding_rejects_empty()
+        => Should.Throw<ArgumentException>(() => MelsecAddress.DRegisterToHolding("D"));
+
+    // --- overflow ---
+
+    [Fact]
+    public void XInputToDiscrete_overflow_throws()
+    {
+        // 0xFFFF + base 1 = 0x10000 — past ushort.
+        Should.Throw<OverflowException>(() =>
+            MelsecAddress.XInputToDiscrete("XFFFF", MelsecFamily.Q_L_iQR, xBankBase: 1));
+    }
+}