TwinCAT PR 2 — IReadable + IWritable. ITwinCATClient + ITwinCATClientFactory abstraction — one client per AMS target, reused across reads/writes/probes. Shape differs from AbCip/AbLegacy where libplctag handles are per-tag — TwinCAT's AdsClient is a single connection with symbolic reads/writes issued against it, so the abstraction is coarser. AdsTwinCATClient is the default implementation wrapping Beckhoff.TwinCAT.Ads's AdsClient — ConnectAsync calls AdsClient.Connect(AmsNetId.Parse(netId), port) after setting Timeout in ms; ReadValueAsync dispatches TwinCATDataType to the CLR Type via MapToClrType (bool/sbyte/byte/short/ushort/int/uint/long/ulong/float/double/string/uint for time types) and calls AdsClient.ReadValueAsync(symbol, type, ct) which returns ResultAnyValue; unwraps .Value + .ErrorCode and maps non-NoError codes via TwinCATStatusMapper.MapAdsError. BOOL-within-word reads extract the bit after the underlying word read using ExtractBit over short/ushort/int/uint/long/ulong. WriteValueAsync converts the boxed value via ConvertForWrite (Convert.ToXxx per type) then calls AdsClient.WriteValueAsync returning ResultWrite; checks .ErrorCode for status mapping. BOOL-within-word writes throw NotSupportedException with a pointer to task #181 — same RMW gap as Modbus BitInRegister / AbCip BOOL-in-DINT / AbLegacy bit-within-N-file. ProbeAsync calls AdsClient.ReadStateAsync + checks AdsErrorCode.NoError. TwinCATDriver implements IReadable + IWritable — per-device ITwinCATClient cached in DeviceState.Client, lazy-connected on first read/write via EnsureConnectedAsync, connect-failure path disposes + clears the client so next call re-attempts cleanly. ReadAsync ordered-snapshot pattern matching AbCip/AbLegacy: unknown ref → BadNodeIdUnknown, unknown device → BadNodeIdUnknown, OperationCanceledException rethrow, any other exception → BadCommunicationError + Degraded health. WriteAsync similar — non-Writable tag → BadNotWritable upfront, NotSupportedException → BadNotSupported, FormatException/InvalidCastException (guard pattern) → BadTypeMismatch, OverflowException → BadOutOfRange, generic → BadCommunicationError. Symbol name resolution goes through TwinCATSymbolPath.TryParse(def.SymbolPath) with fallback to the raw def.SymbolPath if the path doesn't parse — the Beckhoff AdsClient handles the final validation at wire time. ShutdownAsync disposes each device's client. 14 new unit tests in TwinCATReadWriteTests using FakeTwinCATClient + FakeTwinCATClientFactory — unknown ref → BadNodeIdUnknown, successful DInt read with Good status + captured value + IsConnected=true after EnsureConnectedAsync, repeat reads reuse the connection (one Connect + multiple reads), ADS error code mapping via FakeTwinCATClient.ReadStatuses, read exception → BadCommunicationError + Degraded health, connect exception disposes the client, batched reads preserve order across DInt/Real/String types, non-Writable rejection, successful write logs symbol+type+value+bit for test inspection, write status-code mapping, write exception → BadCommunicationError, batch preserves order across success/non-writable/unknown, cancellation propagation, ShutdownAsync disposes the client. Total TwinCAT unit tests now 75/75 passing (+14 from PR 1's 61); full solution builds 0 errors; Modbus / AbCip / AbLegacy / other drivers untouched.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/ITwinCATClient.cs

@@ -0,0 +1,55 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+/// <summary>
+///     Wire-layer abstraction over one connection to a TwinCAT AMS target. One instance per
+///     <see cref="TwinCATAmsAddress"/>; reused across reads / writes / probes for the device.
+///     Tests swap in a fake via <see cref="ITwinCATClientFactory"/>.
+/// </summary>
+/// <remarks>
+///     Unlike libplctag-backed drivers where one native handle exists per tag, TwinCAT's
+///     AdsClient is one connection per target with symbolic reads / writes issued against it.
+///     The abstraction reflects that — single <see cref="ConnectAsync"/>, many
+///     <see cref="ReadValueAsync"/> / <see cref="WriteValueAsync"/> calls.
+/// </remarks>
+public interface ITwinCATClient : IDisposable
+{
+    /// <summary>Establish the AMS connection. Idempotent — subsequent calls are no-ops when already connected.</summary>
+    Task ConnectAsync(TwinCATAmsAddress address, TimeSpan timeout, CancellationToken cancellationToken);
+
+    /// <summary>True when the AMS router + target both accept commands.</summary>
+    bool IsConnected { get; }
+
+    /// <summary>
+    ///     Read a symbolic value. Returns a boxed .NET value matching the requested
+    ///     <paramref name="type"/>, or <c>null</c> when the read produced no data; the
+    ///     <c>status</c> tuple member carries the mapped OPC UA status (0 = Good).
+    /// </summary>
+    Task<(object? value, uint status)> ReadValueAsync(
+        string symbolPath,
+        TwinCATDataType type,
+        int? bitIndex,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    ///     Write a symbolic value. Returns the mapped OPC UA status for the operation
+    ///     (0 = Good, non-zero = error mapped via <see cref="TwinCATStatusMapper"/>).
+    /// </summary>
+    Task<uint> WriteValueAsync(
+        string symbolPath,
+        TwinCATDataType type,
+        int? bitIndex,
+        object? value,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    ///     Cheap health probe — returns <c>true</c> when the target's AMS state is reachable.
+    ///     Used by <see cref="Core.Abstractions.IHostConnectivityProbe"/>'s probe loop.
+    /// </summary>
+    Task<bool> ProbeAsync(CancellationToken cancellationToken);
+}
+
+/// <summary>Factory for <see cref="ITwinCATClient"/>s. One client per device.</summary>
+public interface ITwinCATClientFactory
+{
+    ITwinCATClient Create();
+}