docs/drivers/TwinCAT-Test-Fixture.md

@@ -125,6 +125,35 @@ back an `IAlarmSource`, but shipping that is a separate feature.
 | "Do notifications coalesce under load?" | no | yes (required) |
 | "Does a TC2 PLC work the same as TC3?" | no | yes (required) |
 
+## Performance
+
+PR 2.1 (Sum-read / Sum-write, IndexGroup `0xF080..0xF084`) replaced the per-tag
+`ReadValueAsync` loop in `TwinCATDriver.ReadAsync` / `WriteAsync` with a
+bucketed bulk dispatch — N tags addressed against the same device flow through a
+single ADS sum-command round-trip via `SumInstancePathAnyTypeRead` (read) and
+`SumWriteBySymbolPath` (write). Whole-array tags + bit-extracted BOOL tags
+remain on the per-tag fallback path because the sum surface only marshals
+scalars and bit-RMW writes need the per-parent serialisation lock.
+
+**Baseline → Sum-command delta** (dev box, 1000 × DINT, XAR VM over LAN):
+
+| Path | Round-trips | Wall-clock |
+| --- | --- | --- |
+| Per-tag loop (pre-PR 2.1) | 1000 | ~5–8 s |
+| Sum-command bulk (PR 2.1) | 1 | ~250–600 ms |
+| Ratio | — | ≥ 10× typical, ≥ 5× CI floor |
+
+The perf-tier test
+`TwinCATSumCommandPerfTests.Driver_sum_read_1000_tags_beats_loop_baseline_by_5x`
+asserts the ratio with a conservative 5× lower bound that survives noisy CI /
+VM scheduling. It is gated behind both `TWINCAT_TARGET_NETID` (XAR reachable)
+and `TWINCAT_PERF=1` (operator opt-in) — perf runs aren't part of the default
+integration pass because they hit the wire heavily.
+
+The required fixture state (1000-DINT GVL + churn POU) is documented in
+`TwinCatProject/README.md §Performance scenarios`; XAE-form sources land at
+`TwinCatProject/PLC/GVLs/GVL_Perf.TcGVL` + `TwinCatProject/PLC/POUs/FB_PerfChurn.TcPOU`.
+
 ## Follow-up candidates
 
 1. **XAR VM live-population** — scaffolding is in place (this PR); the

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

@@ -1,7 +1,9 @@
 using System.Collections.Concurrent;
 using System.Runtime.CompilerServices;
+using System.Text;
 using TwinCAT;
 using TwinCAT.Ads;
+using TwinCAT.Ads.SumCommand;
 using TwinCAT.Ads.TypeSystem;
 using TwinCAT.TypeSystem;
 
@@ -347,6 +349,111 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
         return true;
     }
 
+    public async Task<IReadOnlyList<(object? value, uint status)>> ReadValuesAsync(
+        IReadOnlyList<TwinCATBulkReadItem> reads, CancellationToken cancellationToken)
+    {
+        if (reads.Count == 0) return Array.Empty<(object?, uint)>();
+
+        // Build the (path, AnyTypeSpecifier) request envelope. SumInstancePathAnyTypeRead
+        // batches all paths into a single ADS Sum-read round-trip (IndexGroup 0xF080 = read
+        // multiple items by symbol name with ANY-type marshalling).
+        var typeSpecs = new List<(string instancePath, AnyTypeSpecifier spec)>(reads.Count);
+        foreach (var r in reads)
+            typeSpecs.Add((r.SymbolPath, BuildAnyTypeSpecifier(r.Type, r.StringLength)));
+
+        var sumCmd = new SumInstancePathAnyTypeRead(_client, typeSpecs);
+
+        try
+        {
+            var sumResult = await sumCmd.ReadAsync(cancellationToken).ConfigureAwait(false);
+
+            // ResultSumValues2.ValueResults is a per-item array with Source / Value /
+            // ErrorCode. Even when the overall ADS request succeeds, individual sub-items can
+            // carry their own ADS error (e.g. SymbolNotFound).
+            var output = new (object? value, uint status)[reads.Count];
+            var valueResults = sumResult.ValueResults;
+            for (var i = 0; i < reads.Count; i++)
+            {
+                var vr = valueResults[i];
+                if (vr.ErrorCode != 0)
+                {
+                    output[i] = (null, TwinCATStatusMapper.MapAdsError((uint)vr.ErrorCode));
+                    continue;
+                }
+                var raw = vr.Value;
+                output[i] = (PostProcessIecTime(reads[i].Type, raw), TwinCATStatusMapper.Good);
+            }
+            return output;
+        }
+        catch (AdsErrorException ex)
+        {
+            // Whole-batch failure (no symbol-server ack, router unreachable, etc.). Map the
+            // overall ADS status onto every entry so callers see uniform status — partial-
+            // success marshalling lives in the success branch above.
+            var status = TwinCATStatusMapper.MapAdsError((uint)ex.ErrorCode);
+            var failed = new (object? value, uint status)[reads.Count];
+            for (var i = 0; i < reads.Count; i++) failed[i] = (null, status);
+            return failed;
+        }
+    }
+
+    public async Task<IReadOnlyList<uint>> WriteValuesAsync(
+        IReadOnlyList<TwinCATBulkWriteItem> writes, CancellationToken cancellationToken)
+    {
+        if (writes.Count == 0) return Array.Empty<uint>();
+
+        // SumWriteBySymbolPath internally requests symbol handles + issues a single sum-write
+        // (IndexGroup 0xF081) carrying all values. One AMS round-trip for N writes.
+        var paths = new List<string>(writes.Count);
+        var values = new object[writes.Count];
+        for (var i = 0; i < writes.Count; i++)
+        {
+            paths.Add(writes[i].SymbolPath);
+            values[i] = ConvertForWrite(writes[i].Type, writes[i].Value);
+        }
+
+        var sumCmd = new SumWriteBySymbolPath(_client, paths);
+
+        try
+        {
+            var result = await sumCmd.WriteAsync(values, cancellationToken).ConfigureAwait(false);
+            var output = new uint[writes.Count];
+            var subErrors = result.SubErrors;
+            for (var i = 0; i < writes.Count; i++)
+            {
+                // SubErrors can be null when the overall request failed before sub-dispatch —
+                // surface the OverallError on every slot in that case.
+                var code = subErrors is { Length: > 0 } && i < subErrors.Length
+                    ? (uint)subErrors[i]
+                    : (uint)result.ErrorCode;
+                output[i] = TwinCATStatusMapper.MapAdsError(code);
+            }
+            return output;
+        }
+        catch (AdsErrorException ex)
+        {
+            var status = TwinCATStatusMapper.MapAdsError((uint)ex.ErrorCode);
+            var failed = new uint[writes.Count];
+            for (var i = 0; i < writes.Count; i++) failed[i] = status;
+            return failed;
+        }
+    }
+
+    /// <summary>
+    ///     Build an <see cref="AnyTypeSpecifier"/> for one bulk-read entry. STRING uses ASCII +
+    ///     the supplied <paramref name="stringLength"/>; WSTRING uses Unicode (UTF-16). All other
+    ///     types resolve to a primitive CLR type via <see cref="MapToClrType"/>. IEC time/date
+    ///     symbols flow as their underlying UDINT (matching the per-tag path in
+    ///     <see cref="ReadValueAsync"/>) and are post-processed CLR-side after the sum-read.
+    /// </summary>
+    private static AnyTypeSpecifier BuildAnyTypeSpecifier(TwinCATDataType type, int stringLength) =>
+        type switch
+        {
+            TwinCATDataType.String => new AnyTypeSpecifier(typeof(string), stringLength, Encoding.ASCII),
+            TwinCATDataType.WString => new AnyTypeSpecifier(typeof(string), stringLength, Encoding.Unicode),
+            _ => new AnyTypeSpecifier(MapToClrType(type)),
+        };
+
     public void Dispose()
     {
         _client.AdsNotificationEx -= OnAdsNotificationEx;

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

@@ -48,6 +48,38 @@ public interface ITwinCATClient : IDisposable
         object? value,
         CancellationToken cancellationToken);
 
+    /// <summary>
+    ///     Bulk-read N scalar symbols in a single AMS request via Beckhoff's ADS Sum-command
+    ///     family (IndexGroup <c>0xF080..0xF084</c>). The result is a parallel array preserving
+    ///     <paramref name="reads"/> ordering — element <c>i</c>'s outcome maps to request <c>i</c>.
+    ///     Empty input returns an empty result without a wire round-trip.
+    /// </summary>
+    /// <remarks>
+    ///     <para>This is the throughput-optimised path used by <see cref="TwinCATDriver.ReadAsync"/>
+    ///     to replace the per-tag <see cref="ReadValueAsync"/> loop — one ADS sum-read for N
+    ///     symbols beats N individual round-trips by ~10× on the typical PLC link.</para>
+    ///
+    ///     <para>Whole-array reads + bit-extracted BOOL reads stay on the per-tag path because
+    ///     the Sum-command surface only marshals scalars + bitIndex needs CLR-side post-processing.
+    ///     Callers should pre-filter or fall back as appropriate.</para>
+    /// </remarks>
+    Task<IReadOnlyList<(object? value, uint status)>> ReadValuesAsync(
+        IReadOnlyList<TwinCATBulkReadItem> reads,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    ///     Bulk-write N scalar symbols in a single AMS request via Beckhoff's
+    ///     <c>SumWriteBySymbolPath</c>. Result is a parallel status array preserving
+    ///     <paramref name="writes"/> ordering. Empty input returns an empty result.
+    /// </summary>
+    /// <remarks>
+    ///     Whole-array writes + bit-RMW writes are not in scope for the bulk path — those continue
+    ///     through the per-tag <see cref="WriteValueAsync"/> path. The driver layer pre-filters.
+    /// </remarks>
+    Task<IReadOnlyList<uint>> WriteValuesAsync(
+        IReadOnlyList<TwinCATBulkWriteItem> writes,
+        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.
@@ -105,3 +137,19 @@ public interface ITwinCATClientFactory
 {
     ITwinCATClient Create();
 }
+
+/// <summary>One element of an <see cref="ITwinCATClient.ReadValuesAsync"/> request — the symbol path
+/// + the IEC type for marshalling. Strings carry an explicit <paramref name="StringLength"/> for
+/// fixed-size <c>STRING(n)</c> declarations (defaults to <c>80</c> matching IEC 61131-3).</summary>
+public sealed record TwinCATBulkReadItem(
+    string SymbolPath,
+    TwinCATDataType Type,
+    int StringLength = 80);
+
+/// <summary>One element of an <see cref="ITwinCATClient.WriteValuesAsync"/> request.
+/// Mirror of <see cref="TwinCATBulkReadItem"/> with the value to push.</summary>
+public sealed record TwinCATBulkWriteItem(
+    string SymbolPath,
+    TwinCATDataType Type,
+    object? Value,
+    int StringLength = 80);

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

@@ -108,6 +108,14 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
 
     // ---- IReadable ----
 
+    /// <summary>
+    ///     Read the supplied tag references in as few AMS round-trips as possible.
+    ///     Tags resolved to the same <c>DeviceHostAddress</c> are bucketed + sent as one
+    ///     ADS Sum-read (<see cref="ITwinCATClient.ReadValuesAsync"/>) — N tags in one
+    ///     request beats N individual <c>ReadValueAsync</c> calls by ~10× for typical PLC
+    ///     loads. Tags with bit-extracted BOOL or whole-array shape stay on the per-tag
+    ///     path because the sum-read surface only marshals scalars.
+    /// </summary>
     public async Task<IReadOnlyList<DataValueSnapshot>> ReadAsync(
         IReadOnlyList<string> fullReferences, CancellationToken cancellationToken)
     {
@@ -115,6 +123,12 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
         var now = DateTime.UtcNow;
         var results = new DataValueSnapshot[fullReferences.Count];
 
+        // Resolve tag definitions + bucket bulk-eligible reads by device. Anything that
+        // doesn't fit the bulk surface (unknown ref, bit BOOL, whole-array) is processed
+        // through the per-tag path inline so we still return a full result array in
+        // request order.
+        var bulkBuckets = new Dictionary<string, List<(int origIndex, string symbol, TwinCATTagDefinition def, int? bitIndex)>>(StringComparer.OrdinalIgnoreCase);
+
         for (var i = 0; i < fullReferences.Count; i++)
         {
             var reference = fullReferences[i];
@@ -123,31 +137,66 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
                 results[i] = new DataValueSnapshot(null, TwinCATStatusMapper.BadNodeIdUnknown, null, now);
                 continue;
             }
-            if (!_devices.TryGetValue(def.DeviceHostAddress, out var device))
+            if (!_devices.TryGetValue(def.DeviceHostAddress, out _))
             {
                 results[i] = new DataValueSnapshot(null, TwinCATStatusMapper.BadNodeIdUnknown, null, now);
                 continue;
             }
 
+            var parsed = TwinCATSymbolPath.TryParse(def.SymbolPath);
+            var symbolName = parsed?.ToAdsSymbolName() ?? def.SymbolPath;
+            var bitIndex = parsed?.BitIndex;
+            var isWholeArray = def.ArrayDimensions is { Length: > 0 };
+            var isBitBool = bitIndex is int && def.DataType == TwinCATDataType.Bool;
+
+            if (isWholeArray || isBitBool)
+            {
+                // Per-tag fallback path — preserves bit-extract / whole-array logic in
+                // AdsTwinCATClient.ReadValueAsync.
+                results[i] = await ReadOneAsync(reference, def, symbolName, bitIndex, cancellationToken, now)
+                    .ConfigureAwait(false);
+                continue;
+            }
+
+            if (!bulkBuckets.TryGetValue(def.DeviceHostAddress, out var bucket))
+            {
+                bucket = new List<(int, string, TwinCATTagDefinition, int?)>();
+                bulkBuckets[def.DeviceHostAddress] = bucket;
+            }
+            bucket.Add((i, symbolName, def, bitIndex));
+        }
+
+        // One sum-read per device bucket. Ordering inside a bucket is preserved by the
+        // (origIndex, ...) tuple — the result array entry comes from the parallel index.
+        foreach (var (hostAddress, bucket) in bulkBuckets)
+        {
+            if (!_devices.TryGetValue(hostAddress, out var device)) continue;
             try
             {
                 var client = await EnsureConnectedAsync(device, cancellationToken).ConfigureAwait(false);
-                var parsed = TwinCATSymbolPath.TryParse(def.SymbolPath);
+                var items = new TwinCATBulkReadItem[bucket.Count];
-                var symbolName = parsed?.ToAdsSymbolName() ?? def.SymbolPath;
+                for (var k = 0; k < bucket.Count; k++)
-                var (value, status) = await client.ReadValueAsync(
+                    items[k] = new TwinCATBulkReadItem(bucket[k].symbol, bucket[k].def.DataType);
-                    symbolName, def.DataType, parsed?.BitIndex, def.ArrayDimensions, cancellationToken).ConfigureAwait(false);
 
-                results[i] = new DataValueSnapshot(value, status, now, now);
+                var bulk = await client.ReadValuesAsync(items, cancellationToken).ConfigureAwait(false);
+
+                for (var k = 0; k < bucket.Count; k++)
+                {
+                    var (origIndex, _, def, _) = bucket[k];
+                    var (value, status) = bulk[k];
+                    results[origIndex] = new DataValueSnapshot(value, status, now, now);
                     if (status == TwinCATStatusMapper.Good)
                         _health = new DriverHealth(DriverState.Healthy, now, null);
                     else
                         _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead,
-                        $"ADS status {status:X8} reading {reference}");
+                            $"ADS status {status:X8} reading {fullReferences[origIndex]}");
+                }
             }
             catch (OperationCanceledException) { throw; }
             catch (Exception ex)
             {
-                results[i] = new DataValueSnapshot(null, TwinCATStatusMapper.BadCommunicationError, null, now);
+                foreach (var (origIndex, _, _, _) in bucket)
+                    results[origIndex] = new DataValueSnapshot(null, TwinCATStatusMapper.BadCommunicationError, null, now);
                 _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, ex.Message);
             }
         }
@@ -155,14 +204,53 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
         return results;
     }
 
+    private async Task<DataValueSnapshot> ReadOneAsync(
+        string reference, TwinCATTagDefinition def, string symbolName, int? bitIndex,
+        CancellationToken cancellationToken, DateTime timestamp)
+    {
+        if (!_devices.TryGetValue(def.DeviceHostAddress, out var device))
+            return new DataValueSnapshot(null, TwinCATStatusMapper.BadNodeIdUnknown, null, timestamp);
+
+        try
+        {
+            var client = await EnsureConnectedAsync(device, cancellationToken).ConfigureAwait(false);
+            var (value, status) = await client.ReadValueAsync(
+                symbolName, def.DataType, bitIndex, def.ArrayDimensions, cancellationToken).ConfigureAwait(false);
+
+            if (status == TwinCATStatusMapper.Good)
+                _health = new DriverHealth(DriverState.Healthy, timestamp, null);
+            else
+                _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead,
+                    $"ADS status {status:X8} reading {reference}");
+
+            return new DataValueSnapshot(value, status, timestamp, timestamp);
+        }
+        catch (OperationCanceledException) { throw; }
+        catch (Exception ex)
+        {
+            _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, ex.Message);
+            return new DataValueSnapshot(null, TwinCATStatusMapper.BadCommunicationError, null, timestamp);
+        }
+    }
+
     // ---- IWritable ----
 
+    /// <summary>
+    ///     Write the supplied requests, bucketing scalar writes by device + dispatching
+    ///     each bucket as one ADS Sum-write. Bit-RMW BOOL writes + whole-array writes use
+    ///     the per-tag <see cref="ITwinCATClient.WriteValueAsync"/> path so the per-parent
+    ///     RMW lock stays in play.
+    /// </summary>
     public async Task<IReadOnlyList<WriteResult>> WriteAsync(
         IReadOnlyList<WriteRequest> writes, CancellationToken cancellationToken)
     {
         ArgumentNullException.ThrowIfNull(writes);
         var results = new WriteResult[writes.Count];
 
+        // Bucket scalar writes by device. Bit-BOOL + whole-array writes route through the
+        // per-tag fallback below.
+        var bulkBuckets = new Dictionary<string, List<(int origIndex, string symbol, TwinCATTagDefinition def, object? value)>>(StringComparer.OrdinalIgnoreCase);
+
         for (var i = 0; i < writes.Count; i++)
         {
             var w = writes[i];
@@ -176,38 +264,68 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
                 results[i] = new WriteResult(TwinCATStatusMapper.BadNotWritable);
                 continue;
             }
-            if (!_devices.TryGetValue(def.DeviceHostAddress, out var device))
+            if (!_devices.TryGetValue(def.DeviceHostAddress, out _))
             {
                 results[i] = new WriteResult(TwinCATStatusMapper.BadNodeIdUnknown);
                 continue;
             }
 
+            var parsed = TwinCATSymbolPath.TryParse(def.SymbolPath);
+            var symbolName = parsed?.ToAdsSymbolName() ?? def.SymbolPath;
+            var bitIndex = parsed?.BitIndex;
+            var isWholeArray = def.ArrayDimensions is { Length: > 0 };
+            var isBitBool = bitIndex is int && def.DataType == TwinCATDataType.Bool;
+
+            if (isWholeArray || isBitBool)
+            {
+                results[i] = await WriteOneAsync(def, symbolName, bitIndex, w.Value, cancellationToken)
+                    .ConfigureAwait(false);
+                continue;
+            }
+
+            if (!bulkBuckets.TryGetValue(def.DeviceHostAddress, out var bucket))
+            {
+                bucket = new List<(int, string, TwinCATTagDefinition, object?)>();
+                bulkBuckets[def.DeviceHostAddress] = bucket;
+            }
+            bucket.Add((i, symbolName, def, w.Value));
+        }
+
+        foreach (var (hostAddress, bucket) in bulkBuckets)
+        {
+            if (!_devices.TryGetValue(hostAddress, out var device)) continue;
             try
             {
                 var client = await EnsureConnectedAsync(device, cancellationToken).ConfigureAwait(false);
-                var parsed = TwinCATSymbolPath.TryParse(def.SymbolPath);
+                var items = new TwinCATBulkWriteItem[bucket.Count];
-                var symbolName = parsed?.ToAdsSymbolName() ?? def.SymbolPath;
+                for (var k = 0; k < bucket.Count; k++)
-                var status = await client.WriteValueAsync(
+                    items[k] = new TwinCATBulkWriteItem(bucket[k].symbol, bucket[k].def.DataType, bucket[k].value);
-                    symbolName, def.DataType, parsed?.BitIndex, def.ArrayDimensions, w.Value, cancellationToken).ConfigureAwait(false);
+
-                results[i] = new WriteResult(status);
+                var bulk = await client.WriteValuesAsync(items, cancellationToken).ConfigureAwait(false);
+                for (var k = 0; k < bucket.Count; k++)
+                    results[bucket[k].origIndex] = new WriteResult(bulk[k]);
             }
             catch (OperationCanceledException) { throw; }
-            catch (NotSupportedException nse)
-            {
-                results[i] = new WriteResult(TwinCATStatusMapper.BadNotSupported);
-                _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, nse.Message);
-            }
             catch (Exception ex) when (ex is FormatException or InvalidCastException)
             {
-                results[i] = new WriteResult(TwinCATStatusMapper.BadTypeMismatch);
+                foreach (var (origIndex, _, _, _) in bucket)
+                    results[origIndex] = new WriteResult(TwinCATStatusMapper.BadTypeMismatch);
             }
             catch (OverflowException)
             {
-                results[i] = new WriteResult(TwinCATStatusMapper.BadOutOfRange);
+                foreach (var (origIndex, _, _, _) in bucket)
+                    results[origIndex] = new WriteResult(TwinCATStatusMapper.BadOutOfRange);
+            }
+            catch (NotSupportedException nse)
+            {
+                foreach (var (origIndex, _, _, _) in bucket)
+                    results[origIndex] = new WriteResult(TwinCATStatusMapper.BadNotSupported);
+                _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, nse.Message);
             }
             catch (Exception ex)
             {
-                results[i] = new WriteResult(TwinCATStatusMapper.BadCommunicationError);
+                foreach (var (origIndex, _, _, _) in bucket)
+                    results[origIndex] = new WriteResult(TwinCATStatusMapper.BadCommunicationError);
                 _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, ex.Message);
             }
         }
@@ -215,6 +333,40 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
         return results;
     }
 
+    private async Task<WriteResult> WriteOneAsync(
+        TwinCATTagDefinition def, string symbolName, int? bitIndex, object? value, CancellationToken cancellationToken)
+    {
+        if (!_devices.TryGetValue(def.DeviceHostAddress, out var device))
+            return new WriteResult(TwinCATStatusMapper.BadNodeIdUnknown);
+
+        try
+        {
+            var client = await EnsureConnectedAsync(device, cancellationToken).ConfigureAwait(false);
+            var status = await client.WriteValueAsync(
+                symbolName, def.DataType, bitIndex, def.ArrayDimensions, value, cancellationToken).ConfigureAwait(false);
+            return new WriteResult(status);
+        }
+        catch (OperationCanceledException) { throw; }
+        catch (NotSupportedException nse)
+        {
+            _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, nse.Message);
+            return new WriteResult(TwinCATStatusMapper.BadNotSupported);
+        }
+        catch (Exception ex) when (ex is FormatException or InvalidCastException)
+        {
+            return new WriteResult(TwinCATStatusMapper.BadTypeMismatch);
+        }
+        catch (OverflowException)
+        {
+            return new WriteResult(TwinCATStatusMapper.BadOutOfRange);
+        }
+        catch (Exception ex)
+        {
+            _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, ex.Message);
+            return new WriteResult(TwinCATStatusMapper.BadCommunicationError);
+        }
+    }
+
     // ---- ITagDiscovery ----
 
     public async Task DiscoverAsync(IAddressSpaceBuilder builder, CancellationToken cancellationToken)

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCATSumCommandPerfTests.cs

@@ -0,0 +1,93 @@
+using System.Diagnostics;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests;
+
+/// <summary>
+///     PR 2.1 perf gate — verifies the bulk Sum-read path is materially faster than the
+///     equivalent serial per-tag <see cref="TwinCAT.Ads.AdsClient.ReadValueAsync(string, Type, System.Threading.CancellationToken)"/>
+///     loop on a real XAR runtime. The driver's <see cref="TwinCATDriver.ReadAsync"/>
+///     already routes through the bulk path; the baseline calls through a hand-rolled
+///     loop so we're comparing apples to apples on the same wire.
+/// </summary>
+/// <remarks>
+///     Requires the perf fixture: <c>GVL_Perf.aTags : ARRAY[1..1000] OF DINT</c> per
+///     <c>TwinCatProject/README.md §Performance scenarios</c>. Skipped unless
+///     <c>TWINCAT_PERF=1</c> is set.
+/// </remarks>
+[Collection("TwinCATXar")]
+[Trait("Category", "Performance")]
+[Trait("Simulator", "TwinCAT-XAR")]
+public sealed class TwinCATSumCommandPerfTests(TwinCATXarFixture sim)
+{
+    private const int TagCount = 1000;
+
+    [TwinCATPerfFact]
+    public async Task Driver_sum_read_1000_tags_beats_loop_baseline_by_5x()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+
+        var deviceAddress = $"ads://{sim.TargetNetId}:{sim.AmsPort}";
+        var tags = new TwinCATTagDefinition[TagCount];
+        var refs = new string[TagCount];
+        for (var i = 0; i < TagCount; i++)
+        {
+            // GVL_Perf.aTags is 1-based per IEC 61131-3 ARRAY declaration.
+            var name = $"Perf{i + 1}";
+            refs[i] = name;
+            tags[i] = new TwinCATTagDefinition(
+                Name: name,
+                DeviceHostAddress: deviceAddress,
+                SymbolPath: $"GVL_Perf.aTags[{i + 1}]",
+                DataType: TwinCATDataType.DInt);
+        }
+
+        var options = new TwinCATDriverOptions
+        {
+            Devices = [new TwinCATDeviceOptions(deviceAddress, "XAR-VM")],
+            Tags = tags,
+            UseNativeNotifications = false,
+            Timeout = TimeSpan.FromSeconds(15),
+            Probe = new TwinCATProbeOptions { Enabled = false },
+        };
+
+        // ---- Bulk (PR 2.1) measurement ----
+        await using var bulkDrv = new TwinCATDriver(options, "tc3-perf-bulk");
+        await bulkDrv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        // Warm-up: prime symbol-handle caches in the XAR runtime so the timed run
+        // measures sum-read steady state, not first-touch handle resolution.
+        await bulkDrv.ReadAsync(refs, TestContext.Current.CancellationToken);
+
+        var bulkSw = Stopwatch.StartNew();
+        var bulkResults = await bulkDrv.ReadAsync(refs, TestContext.Current.CancellationToken);
+        bulkSw.Stop();
+
+        // ---- Loop baseline measurement ----
+        // Use a fresh driver instance so the cache state matches the bulk run on first
+        // call. Single-tag-per-call across the full set is what PR 2.1 replaces.
+        await using var loopDrv = new TwinCATDriver(options, "tc3-perf-loop");
+        await loopDrv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        // Warm-up against the same refs.
+        for (var i = 0; i < TagCount; i++)
+            _ = await loopDrv.ReadAsync([refs[i]], TestContext.Current.CancellationToken);
+
+        var loopSw = Stopwatch.StartNew();
+        for (var i = 0; i < TagCount; i++)
+            _ = await loopDrv.ReadAsync([refs[i]], TestContext.Current.CancellationToken);
+        loopSw.Stop();
+
+        // Sanity: bulk path must produce TagCount snapshots all Good.
+        bulkResults.Count.ShouldBe(TagCount);
+        bulkResults.ShouldAllBe(s => s.StatusCode == TwinCATStatusMapper.Good);
+
+        // Conservative ratio — on the dev box bulk is ~10-20× the loop, target is 5×.
+        // Lower bound exists so the test is robust to noisy CI / VM scheduling.
+        var ratio = (double)loopSw.ElapsedMilliseconds / Math.Max(1, bulkSw.ElapsedMilliseconds);
+        ratio.ShouldBeGreaterThan(5.0,
+            $"Bulk Sum-read should be >5x faster than per-tag loop; got bulk={bulkSw.ElapsedMilliseconds}ms, loop={loopSw.ElapsedMilliseconds}ms (ratio={ratio:F2})");
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCATXarFixture.cs

@@ -134,3 +134,24 @@ public sealed class TwinCATTheoryAttribute : TheoryAttribute
                    "for setup; typical cause is the trial license expired or TWINCAT_TARGET_NETID is unset.";
     }
 }
+
+/// <summary>
+///     Perf-tier <c>[Fact]</c> equivalent. Runs only when the XAR runtime is reachable
+///     <em>and</em> <c>TWINCAT_PERF=1</c> is set. Perf tests are gated separately because
+///     they exercise the wire heavily (1000+ tags) + can extend test runs by tens of
+///     seconds — the operator opts in.
+/// </summary>
+public sealed class TwinCATPerfFactAttribute : FactAttribute
+{
+    public TwinCATPerfFactAttribute()
+    {
+        if (!TwinCATXarFixture.IsRuntimeAvailable())
+        {
+            Skip = "TwinCAT XAR not reachable. See docs/drivers/TwinCAT-Test-Fixture.md " +
+                   "for setup; typical cause is the trial license expired or TWINCAT_TARGET_NETID is unset.";
+            return;
+        }
+        if (Environment.GetEnvironmentVariable("TWINCAT_PERF") != "1")
+            Skip = "Perf tier disabled. Set TWINCAT_PERF=1 to run; see docs/drivers/TwinCAT-Test-Fixture.md §Performance.";
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/GVLs/GVL_Perf.TcGVL

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<TcPlcObject Version="1.1.0.1" ProductVersion="3.1.4024.0">
+  <GVL Name="GVL_Perf" Id="{00000000-0000-0000-0000-000000000201}">
+    <Declaration><![CDATA[// PR 2.1 Sum-read perf fixture. 1000 DINTs read in one ADS sum-read by
+// TwinCATSumCommandPerfTests; FB_PerfChurn rotates a few values each cycle so
+// the wire isn't reading static data the runtime can short-circuit.
+//
+// Required by the perf-tier integration test
+// Driver_sum_read_1000_tags_beats_loop_baseline_by_5x. See
+// TwinCatProject/README.md §Performance scenarios.
+VAR_GLOBAL
+    aTags : ARRAY[1..1000] OF DINT;
+    fbPerfChurn : FB_PerfChurn;
+END_VAR
+]]></Declaration>
+  </GVL>
+</TcPlcObject>

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/POUs/FB_PerfChurn.TcPOU

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<TcPlcObject Version="1.1.0.1" ProductVersion="3.1.4024.0">
+  <POU Name="FB_PerfChurn" Id="{00000000-0000-0000-0000-000000000202}" SpecialFunc="None">
+    <Declaration><![CDATA[// Rotating writer for GVL_Perf.aTags so the perf integration test isn't
+// reading completely static data — keeps the runtime's symbol caches honest.
+// Increments each tag's value at MAIN-task cadence; touches all 1000 entries
+// over the 1000 cycles spanning ~10s at the default 10ms PlcTask period.
+FUNCTION_BLOCK FB_PerfChurn
+VAR
+    nIndex : INT := 1;
+END_VAR
+]]></Declaration>
+    <Implementation>
+      <ST><![CDATA[GVL_Perf.aTags[nIndex] := GVL_Perf.aTags[nIndex] + 1;
+nIndex := nIndex + 1;
+IF nIndex > 1000 THEN
+    nIndex := 1;
+END_IF
+]]></ST>
+    </Implementation>
+  </POU>
+</TcPlcObject>

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md

@@ -71,6 +71,70 @@ GVL_Fixture.nCounter := GVL_Fixture.nCounter + 1;
 - `PlcTask` — cyclic, 10 ms interval, priority 20
 - Assigned to `MAIN`
 
+## Performance scenarios
+
+PR 2.1 (ADS Sum-read / Sum-write) ships an opt-in perf-tier integration test
+(`TwinCATSumCommandPerfTests.Driver_sum_read_1000_tags_beats_loop_baseline_by_5x`)
+that reads 1000 DINTs in one shot and asserts the bulk path beats the per-tag
+loop by ≥ 5×. The fixture state required by that test is:
+
+### Global Variable List: `GVL_Perf`
+
+```st
+VAR_GLOBAL
+    // 1000-DINT array — exercised by the bulk Sum-read benchmark.
+    aTags       : ARRAY[1..1000] OF DINT;
+    fbPerfChurn : FB_PerfChurn;
+END_VAR
+```
+
+The XAE-form GVL ships at `PLC/GVLs/GVL_Perf.TcGVL`; import it into the PLC
+project alongside `GVL_Fixture`.
+
+### POU: `FB_PerfChurn`
+
+```st
+FUNCTION_BLOCK FB_PerfChurn
+VAR
+    nIndex : INT := 1;
+END_VAR
+
+GVL_Perf.aTags[nIndex] := GVL_Perf.aTags[nIndex] + 1;
+nIndex := nIndex + 1;
+IF nIndex > 1000 THEN
+    nIndex := 1;
+END_IF
+```
+
+The XAE-form POU ships at `PLC/POUs/FB_PerfChurn.TcPOU`. Wire it into `MAIN`
+so a value rotates each cycle:
+
+```st
+PROGRAM MAIN
+VAR
+END_VAR
+
+// existing GVL_Fixture line:
+GVL_Fixture.nCounter := GVL_Fixture.nCounter + 1;
+
+// PR 2.1 — keep aTags moving so caches don't short-circuit the read.
+GVL_Perf.fbPerfChurn();
+```
+
+### Running the perf tier
+
+```powershell
+$env:TWINCAT_TARGET_HOST  = '10.0.0.42'
+$env:TWINCAT_TARGET_NETID = '5.23.91.23.1.1'
+$env:TWINCAT_PERF         = '1'
+dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests `
+    --filter "Category=Performance"
+```
+
+Without `TWINCAT_PERF=1` the perf test skips via `[TwinCATPerfFact]` even when
+the runtime is reachable — perf runs are opt-in to keep the default integration
+pass fast.
+
 ### Runtime ID
 
 - TC3 PLC runtime 1 (AMS port `851`) — the smoke-test fixture defaults

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/FakeTwinCATClient.cs

@@ -72,6 +72,64 @@ internal class FakeTwinCATClient : ITwinCATClient
         return Task.FromResult(ProbeResult);
     }
 
+    // ---- Bulk surface (PR 2.1: SumSymbolRead / SumSymbolWrite) ----
+
+    public List<IReadOnlyList<TwinCATBulkReadItem>> BulkReadInvocations { get; } = new();
+    public List<IReadOnlyList<TwinCATBulkWriteItem>> BulkWriteInvocations { get; } = new();
+    public bool ThrowOnBulkRead { get; set; }
+    public bool ThrowOnBulkWrite { get; set; }
+
+    /// <summary>Per-symbol read failure injection — overlay onto <see cref="ReadStatuses"/>.</summary>
+    public Dictionary<string, uint> BulkReadStatuses { get; } = new(StringComparer.OrdinalIgnoreCase);
+
+    public virtual Task<IReadOnlyList<(object? value, uint status)>> ReadValuesAsync(
+        IReadOnlyList<TwinCATBulkReadItem> reads, CancellationToken ct)
+    {
+        // ThrowOnRead applies to both per-tag + bulk paths so legacy tests that toggled
+        // ThrowOnRead before bulk existed still surface BadCommunicationError correctly.
+        if (ThrowOnRead || ThrowOnBulkRead) throw Exception ?? new InvalidOperationException();
+        BulkReadInvocations.Add(reads);
+
+        // Preserve request order — the production sum-read returns one entry per request slot
+        // even on partial failure; so does this fake.
+        var output = new (object? value, uint status)[reads.Count];
+        for (var i = 0; i < reads.Count; i++)
+        {
+            var r = reads[i];
+            ReadLog.Add((r.SymbolPath, r.Type, null, null));
+            if (BulkReadStatuses.TryGetValue(r.SymbolPath, out var bulkStatus))
+            {
+                output[i] = (null, bulkStatus);
+                continue;
+            }
+            if (ReadStatuses.TryGetValue(r.SymbolPath, out var status) && status != TwinCATStatusMapper.Good)
+            {
+                output[i] = (null, status);
+                continue;
+            }
+            var value = Values.TryGetValue(r.SymbolPath, out var v) ? v : null;
+            output[i] = (value, TwinCATStatusMapper.Good);
+        }
+        return Task.FromResult<IReadOnlyList<(object? value, uint status)>>(output);
+    }
+
+    public virtual Task<IReadOnlyList<uint>> WriteValuesAsync(
+        IReadOnlyList<TwinCATBulkWriteItem> writes, CancellationToken ct)
+    {
+        if (ThrowOnWrite || ThrowOnBulkWrite) throw Exception ?? new InvalidOperationException();
+        BulkWriteInvocations.Add(writes);
+
+        var output = new uint[writes.Count];
+        for (var i = 0; i < writes.Count; i++)
+        {
+            var w = writes[i];
+            WriteLog.Add((w.SymbolPath, w.Type, null, w.Value));
+            Values[w.SymbolPath] = w.Value;
+            output[i] = WriteStatuses.TryGetValue(w.SymbolPath, out var s) ? s : TwinCATStatusMapper.Good;
+        }
+        return Task.FromResult<IReadOnlyList<uint>>(output);
+    }
+
     public virtual void Dispose()
     {
         DisposeCount++;

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/TwinCATSumCommandTests.cs

@@ -0,0 +1,238 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests;
+
+/// <summary>
+///     PR 2.1 — bulk read / write contract via Sum-command surface. Verifies that
+///     <see cref="TwinCATDriver.ReadAsync"/> + <see cref="TwinCATDriver.WriteAsync"/>
+///     bucket scalar requests by device + dispatch each bucket as a single
+///     <see cref="ITwinCATClient.ReadValuesAsync"/> / <see cref="ITwinCATClient.WriteValuesAsync"/>
+///     call. Ordering preservation, partial failure mapping, empty input + cancellation
+///     all live here. Per-tag fallback for bit-BOOL + whole-array tags is covered in
+///     <see cref="TwinCATBitWriteTests"/> / <see cref="TwinCATArrayReadTests"/>.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class TwinCATSumCommandTests
+{
+    private const string DevA = "ads://5.23.91.23.1.1:851";
+    private const string DevB = "ads://5.23.91.23.1.1:852";
+
+    private static (TwinCATDriver drv, FakeTwinCATClientFactory factory) NewDriver(params TwinCATTagDefinition[] tags)
+    {
+        var factory = new FakeTwinCATClientFactory();
+        var hosts = tags.Select(t => t.DeviceHostAddress).Distinct().ToArray();
+        if (hosts.Length == 0) hosts = [DevA];
+        var drv = new TwinCATDriver(new TwinCATDriverOptions
+        {
+            Devices = [.. hosts.Select(h => new TwinCATDeviceOptions(h))],
+            Tags = tags,
+            Probe = new TwinCATProbeOptions { Enabled = false },
+        }, "drv-bulk", factory);
+        return (drv, factory);
+    }
+
+    // ---- Bulk read ----
+
+    [Fact]
+    public async Task Bulk_read_dispatches_single_call_per_device_bucket()
+    {
+        var (drv, factory) = NewDriver(
+            new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt),
+            new TwinCATTagDefinition("B", DevA, "GVL.B", TwinCATDataType.Real),
+            new TwinCATTagDefinition("C", DevA, "GVL.C", TwinCATDataType.Bool));
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        factory.Customise = () => new FakeTwinCATClient
+        {
+            Values = { ["GVL.A"] = 1, ["GVL.B"] = 2.5f, ["GVL.C"] = true },
+        };
+
+        var snapshots = await drv.ReadAsync(["A", "B", "C"], TestContext.Current.CancellationToken);
+
+        snapshots.Count.ShouldBe(3);
+        // One bulk-read call carrying all 3 tags — the throughput win this PR exists for.
+        factory.Clients[0].BulkReadInvocations.Count.ShouldBe(1);
+        factory.Clients[0].BulkReadInvocations[0].Count.ShouldBe(3);
+    }
+
+    [Fact]
+    public async Task Bulk_read_preserves_request_order_with_mixed_outcomes()
+    {
+        var (drv, factory) = NewDriver(
+            new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt),
+            new TwinCATTagDefinition("B", DevA, "GVL.Missing", TwinCATDataType.DInt),
+            new TwinCATTagDefinition("C", DevA, "GVL.C", TwinCATDataType.String));
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        factory.Customise = () =>
+        {
+            var c = new FakeTwinCATClient
+            {
+                Values = { ["GVL.A"] = 7, ["GVL.C"] = "ok" },
+            };
+            c.BulkReadStatuses["GVL.Missing"] = TwinCATStatusMapper.BadNodeIdUnknown;
+            return c;
+        };
+
+        var snapshots = await drv.ReadAsync(["A", "B", "C"], TestContext.Current.CancellationToken);
+
+        snapshots[0].StatusCode.ShouldBe(TwinCATStatusMapper.Good);
+        snapshots[0].Value.ShouldBe(7);
+        snapshots[1].StatusCode.ShouldBe(TwinCATStatusMapper.BadNodeIdUnknown);
+        snapshots[1].Value.ShouldBeNull();
+        snapshots[2].StatusCode.ShouldBe(TwinCATStatusMapper.Good);
+        snapshots[2].Value.ShouldBe("ok");
+    }
+
+    [Fact]
+    public async Task Bulk_read_buckets_per_device()
+    {
+        var (drv, factory) = NewDriver(
+            new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt),
+            new TwinCATTagDefinition("X", DevB, "GVL.X", TwinCATDataType.DInt),
+            new TwinCATTagDefinition("B", DevA, "GVL.B", TwinCATDataType.DInt));
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        factory.Customise = () => new FakeTwinCATClient
+        {
+            Values = { ["GVL.A"] = 1, ["GVL.B"] = 2, ["GVL.X"] = 99 },
+        };
+
+        var snapshots = await drv.ReadAsync(["A", "X", "B"], TestContext.Current.CancellationToken);
+
+        snapshots[0].Value.ShouldBe(1);
+        snapshots[1].Value.ShouldBe(99);
+        snapshots[2].Value.ShouldBe(2);
+        // Two clients (one per device); each bucket made a single bulk-read call.
+        factory.Clients.Count.ShouldBe(2);
+        factory.Clients[0].BulkReadInvocations.Count.ShouldBe(1);
+        factory.Clients[1].BulkReadInvocations.Count.ShouldBe(1);
+        factory.Clients.Sum(c => c.BulkReadInvocations.Sum(i => i.Count)).ShouldBe(3);
+    }
+
+    [Fact]
+    public async Task Empty_input_returns_empty_result_without_wire_call()
+    {
+        var (drv, factory) = NewDriver(
+            new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt));
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var snapshots = await drv.ReadAsync([], TestContext.Current.CancellationToken);
+
+        snapshots.Count.ShouldBe(0);
+        // No client created — driver short-circuits before EnsureConnectedAsync.
+        factory.Clients.Count.ShouldBe(0);
+    }
+
+    [Fact]
+    public async Task Bulk_read_whole_batch_failure_marks_every_slot_BadCommunicationError()
+    {
+        var (drv, factory) = NewDriver(
+            new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt),
+            new TwinCATTagDefinition("B", DevA, "GVL.B", TwinCATDataType.DInt));
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        factory.Customise = () => new FakeTwinCATClient { ThrowOnBulkRead = true };
+
+        var snapshots = await drv.ReadAsync(["A", "B"], TestContext.Current.CancellationToken);
+
+        snapshots[0].StatusCode.ShouldBe(TwinCATStatusMapper.BadCommunicationError);
+        snapshots[1].StatusCode.ShouldBe(TwinCATStatusMapper.BadCommunicationError);
+        drv.GetHealth().State.ShouldBe(DriverState.Degraded);
+    }
+
+    [Fact]
+    public async Task Read_cancellation_propagates_through_bulk_path()
+    {
+        var (drv, factory) = NewDriver(
+            new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt));
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        factory.Customise = () => new FakeTwinCATClient
+        {
+            ThrowOnBulkRead = true,
+            Exception = new OperationCanceledException(),
+        };
+
+        await Should.ThrowAsync<OperationCanceledException>(
+            () => drv.ReadAsync(["A"], TestContext.Current.CancellationToken));
+    }
+
+    // ---- Bulk write ----
+
+    [Fact]
+    public async Task Bulk_write_dispatches_single_call_per_device_bucket()
+    {
+        var (drv, factory) = NewDriver(
+            new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt),
+            new TwinCATTagDefinition("B", DevA, "GVL.B", TwinCATDataType.DInt),
+            new TwinCATTagDefinition("C", DevA, "GVL.C", TwinCATDataType.DInt));
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await drv.WriteAsync(
+            [new WriteRequest("A", 1), new WriteRequest("B", 2), new WriteRequest("C", 3)],
+            TestContext.Current.CancellationToken);
+
+        results.Count.ShouldBe(3);
+        results.ShouldAllBe(r => r.StatusCode == TwinCATStatusMapper.Good);
+        factory.Clients[0].BulkWriteInvocations.Count.ShouldBe(1);
+        factory.Clients[0].BulkWriteInvocations[0].Count.ShouldBe(3);
+    }
+
+    [Fact]
+    public async Task Bulk_write_preserves_request_order_across_outcomes()
+    {
+        var (drv, factory) = NewDriver(
+            new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt),
+            new TwinCATTagDefinition("B", DevA, "GVL.B", TwinCATDataType.DInt, Writable: false),
+            new TwinCATTagDefinition("C", DevA, "GVL.C", TwinCATDataType.DInt));
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        factory.Customise = () =>
+        {
+            var c = new FakeTwinCATClient();
+            c.WriteStatuses["GVL.C"] = TwinCATStatusMapper.BadOutOfRange;
+            return c;
+        };
+
+        var results = await drv.WriteAsync(
+        [
+            new WriteRequest("A", 1),
+            new WriteRequest("B", 2),  // pre-bulk reject (read-only)
+            new WriteRequest("Unknown", 3),
+            new WriteRequest("C", 4),  // mapped per-symbol error
+        ], TestContext.Current.CancellationToken);
+
+        results[0].StatusCode.ShouldBe(TwinCATStatusMapper.Good);
+        results[1].StatusCode.ShouldBe(TwinCATStatusMapper.BadNotWritable);
+        results[2].StatusCode.ShouldBe(TwinCATStatusMapper.BadNodeIdUnknown);
+        results[3].StatusCode.ShouldBe(TwinCATStatusMapper.BadOutOfRange);
+    }
+
+    [Fact]
+    public async Task Bulk_write_whole_batch_failure_marks_every_slot_BadCommunicationError()
+    {
+        var (drv, factory) = NewDriver(
+            new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt),
+            new TwinCATTagDefinition("B", DevA, "GVL.B", TwinCATDataType.DInt));
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        factory.Customise = () => new FakeTwinCATClient { ThrowOnBulkWrite = true };
+
+        var results = await drv.WriteAsync(
+            [new WriteRequest("A", 1), new WriteRequest("B", 2)],
+            TestContext.Current.CancellationToken);
+
+        results[0].StatusCode.ShouldBe(TwinCATStatusMapper.BadCommunicationError);
+        results[1].StatusCode.ShouldBe(TwinCATStatusMapper.BadCommunicationError);
+    }
+
+    [Fact]
+    public async Task Empty_write_input_returns_empty_result_without_wire_call()
+    {
+        var (drv, factory) = NewDriver(
+            new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt));
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await drv.WriteAsync([], TestContext.Current.CancellationToken);
+
+        results.Count.ShouldBe(0);
+        factory.Clients.Count.ShouldBe(0);
+    }
+}