AbCip whole-UDT read optimization (#194) — declaration-driven member grouping collapses N per-member reads into one parent-UDT read + client-side decode. Closes task #194. On a batch that includes multiple members of the same hand-declared UDT tag, ReadAsync now issues one libplctag read on the parent + decodes each member from the runtime's buffer at its computed byte offset. A 6-member Motor UDT read goes from 6 libplctag round-trips to 1 — the Rockwell-suggested pattern for minimizing CIP request overhead on batch reads of UDT state (decision #11's follow-through on what the template decoder from task #179 was meant to enable). AbCipUdtMemberLayout is a pure-function helper that computes declared-member byte offsets under Logix natural-alignment rules (SInt 1-byte / Int 2-byte / DInt + Real + Dt 4-byte / LInt + ULInt + LReal 8-byte; alignment pad inserted before each member as needed). Opts out for BOOL / String / Structure members — BOOL storage in Logix UDTs packs into a hidden host byte whose position can't be computed from declaration-only info, and String members need length-prefix + STRING[82] fan-out which libplctag already handles via a per-tag DecodeValue path. The CIP Template Object shape from task #179 (when populated via FetchUdtShapeAsync) carries real offsets for those members — layering that richer path on top of the planner is a separate follow-up and does not change this PR's conservative behaviour. AbCipUdtReadPlanner is the scheduling function ReadAsync consults each batch — pure over (requests, tagsByName), emits Groups + Fallbacks. A group is formed when (a) the reference resolves to "parent.member"; (b) parent is a Structure tag with declared Members; (c) the layout helper succeeds on those members; (d) the specific member appears in the computed offset map; (e) at least two members of the same parent appear in the batch — single-member groups demote to the fallback path because one whole-UDT read vs one per-member read is equivalent cost but more client-side work. Original batch indices are preserved through the plan so out-of-order batches write decoded values back at the right output slot; the caller's result array order is invariant. IAbCipTagRuntime.DecodeValueAt(AbCipDataType, int offset, int? bitIndex) is the new hot-path method — LibplctagTagRuntime delegates to libplctag's offset-aware Get*(offset) calls (GetInt32, GetFloat32, etc.) that were always there; previously every call passed offset 0. DecodeValue(type, bitIndex) stays as the shorthand + forwards to DecodeValueAt with offset 0, preserving the existing single-tag read path + every test that exercises it. FakeAbCipTag gains a ValuesByOffset dictionary so tests can drive multi-member decoding by setting offset→value before the read fires; unmapped offsets fall back to the existing Value field so the 200+ existing tests that never set ValuesByOffset keep working unchanged. AbCipDriver.ReadAsync refactored: planner splits the batch, ReadGroupAsync handles each UDT group (one EnsureTagRuntimeAsync on the parent + one ReadAsync + N DecodeValueAt calls), ReadSingleAsync handles each fallback (the pre-#194 per-tag path, now extracted + threaded through). A per-group failure stamps the mapped libplctag status across every grouped member only — sibling groups + fallback refs are unaffected. Health-surface updates happen once per successful group rather than once per member to avoid ping-ponging the DriverState bookkeeping. Five AbCipUdtMemberLayoutTests: packed atomics get natural-alignment offsets including 8-byte pad before LInt; SInts pack without padding; BOOL/String/Structure opt out + return null; empty member list returns null. Six AbCipUdtReadPlannerTests: two members group; single-member demotes to fallback; unknown references fall back without poisoning groups; atomic top-level tags fall back untouched; UDTs containing BOOL don't group; original indices survive out-of-order batches. Five AbCipDriverWholeUdtReadTests (real driver + fake runtime): two grouped members trigger exactly one parent read + one fake runtime (proving the optimization engages); each member decodes at its own offset via ValuesByOffset; parent-read non-zero status stamps Bad across the group; mixed UDT-member + atomic top-level batch produces 2 runtimes + 2 reads (not 3); single-member-of-UDT still uses the member-level runtime (proving demotion works). Driver builds 0 errors; AbCip.Tests 227/227 (was 211, +16 new).

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

src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipDriver.cs

@@ -287,56 +287,127 @@ public sealed class AbCipDriver : IDriver, IReadable, IWritable, ITagDiscovery,
         var now = DateTime.UtcNow;
         var results = new DataValueSnapshot[fullReferences.Count];
 
-        for (var i = 0; i < fullReferences.Count; i++)
-        {
-            var reference = fullReferences[i];
-            if (!_tagsByName.TryGetValue(reference, out var def))
-            {
-                results[i] = new DataValueSnapshot(null, AbCipStatusMapper.BadNodeIdUnknown, null, now);
-                continue;
-            }
-            if (!_devices.TryGetValue(def.DeviceHostAddress, out var device))
-            {
-                results[i] = new DataValueSnapshot(null, AbCipStatusMapper.BadNodeIdUnknown, null, now);
-                continue;
-            }
+        // Task #194 — plan the batch: members of the same parent UDT get collapsed into one
+        // whole-UDT read + in-memory member decode; every other reference falls back to the
+        // per-tag path that's been here since PR 3. Planner is a pure function over the
+        // current tag map; BOOL/String/Structure members stay on the fallback path because
+        // declaration-only offsets can't place them under Logix alignment rules.
+        var plan = AbCipUdtReadPlanner.Build(fullReferences, _tagsByName);
 
-            try
-            {
-                var runtime = await EnsureTagRuntimeAsync(device, def, cancellationToken).ConfigureAwait(false);
-                await runtime.ReadAsync(cancellationToken).ConfigureAwait(false);
+        foreach (var group in plan.Groups)
+            await ReadGroupAsync(group, results, now, cancellationToken).ConfigureAwait(false);
 
-                var status = runtime.GetStatus();
-                if (status != 0)
-                {
-                    results[i] = new DataValueSnapshot(null,
-                        AbCipStatusMapper.MapLibplctagStatus(status), null, now);
-                    _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead,
-                        $"libplctag status {status} reading {reference}");
-                    continue;
-                }
-
-                var tagPath = AbCipTagPath.TryParse(def.TagPath);
-                var bitIndex = tagPath?.BitIndex;
-                var value = runtime.DecodeValue(def.DataType, bitIndex);
-                results[i] = new DataValueSnapshot(value, AbCipStatusMapper.Good, now, now);
-                _health = new DriverHealth(DriverState.Healthy, now, null);
-            }
-            catch (OperationCanceledException)
-            {
-                throw;
-            }
-            catch (Exception ex)
-            {
-                results[i] = new DataValueSnapshot(null,
-                    AbCipStatusMapper.BadCommunicationError, null, now);
-                _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, ex.Message);
-            }
-        }
+        foreach (var fb in plan.Fallbacks)
+            await ReadSingleAsync(fb, fullReferences[fb.OriginalIndex], results, now, cancellationToken).ConfigureAwait(false);
 
         return results;
     }
 
+    private async Task ReadSingleAsync(
+        AbCipUdtReadFallback fb, string reference, DataValueSnapshot[] results, DateTime now, CancellationToken ct)
+    {
+        if (!_tagsByName.TryGetValue(reference, out var def))
+        {
+            results[fb.OriginalIndex] = new DataValueSnapshot(null, AbCipStatusMapper.BadNodeIdUnknown, null, now);
+            return;
+        }
+        if (!_devices.TryGetValue(def.DeviceHostAddress, out var device))
+        {
+            results[fb.OriginalIndex] = new DataValueSnapshot(null, AbCipStatusMapper.BadNodeIdUnknown, null, now);
+            return;
+        }
+
+        try
+        {
+            var runtime = await EnsureTagRuntimeAsync(device, def, ct).ConfigureAwait(false);
+            await runtime.ReadAsync(ct).ConfigureAwait(false);
+
+            var status = runtime.GetStatus();
+            if (status != 0)
+            {
+                results[fb.OriginalIndex] = new DataValueSnapshot(null,
+                    AbCipStatusMapper.MapLibplctagStatus(status), null, now);
+                _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead,
+                    $"libplctag status {status} reading {reference}");
+                return;
+            }
+
+            var tagPath = AbCipTagPath.TryParse(def.TagPath);
+            var bitIndex = tagPath?.BitIndex;
+            var value = runtime.DecodeValue(def.DataType, bitIndex);
+            results[fb.OriginalIndex] = new DataValueSnapshot(value, AbCipStatusMapper.Good, now, now);
+            _health = new DriverHealth(DriverState.Healthy, now, null);
+        }
+        catch (OperationCanceledException)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            results[fb.OriginalIndex] = new DataValueSnapshot(null,
+                AbCipStatusMapper.BadCommunicationError, null, now);
+            _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, ex.Message);
+        }
+    }
+
+    /// <summary>
+    ///     Task #194 — perform one whole-UDT read on the parent tag, then decode each
+    ///     grouped member from the runtime's buffer at its computed byte offset. A per-group
+    ///     failure (parent read raised, non-zero libplctag status, or missing device) stamps
+    ///     the mapped fault across every grouped member only — sibling groups + the
+    ///     per-tag fallback list are unaffected.
+    /// </summary>
+    private async Task ReadGroupAsync(
+        AbCipUdtReadGroup group, DataValueSnapshot[] results, DateTime now, CancellationToken ct)
+    {
+        var parent = group.ParentDefinition;
+
+        if (!_devices.TryGetValue(parent.DeviceHostAddress, out var device))
+        {
+            StampGroupStatus(group, results, now, AbCipStatusMapper.BadNodeIdUnknown);
+            return;
+        }
+
+        try
+        {
+            var runtime = await EnsureTagRuntimeAsync(device, parent, ct).ConfigureAwait(false);
+            await runtime.ReadAsync(ct).ConfigureAwait(false);
+
+            var status = runtime.GetStatus();
+            if (status != 0)
+            {
+                var mapped = AbCipStatusMapper.MapLibplctagStatus(status);
+                StampGroupStatus(group, results, now, mapped);
+                _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead,
+                    $"libplctag status {status} reading UDT {group.ParentName}");
+                return;
+            }
+
+            foreach (var member in group.Members)
+            {
+                var value = runtime.DecodeValueAt(member.Definition.DataType, member.Offset, bitIndex: null);
+                results[member.OriginalIndex] = new DataValueSnapshot(value, AbCipStatusMapper.Good, now, now);
+            }
+            _health = new DriverHealth(DriverState.Healthy, now, null);
+        }
+        catch (OperationCanceledException)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            StampGroupStatus(group, results, now, AbCipStatusMapper.BadCommunicationError);
+            _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, ex.Message);
+        }
+    }
+
+    private static void StampGroupStatus(
+        AbCipUdtReadGroup group, DataValueSnapshot[] results, DateTime now, uint statusCode)
+    {
+        foreach (var member in group.Members)
+            results[member.OriginalIndex] = new DataValueSnapshot(null, statusCode, null, now);
+    }
+
     // ---- IWritable ----
 
     /// <summary>

src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipUdtMemberLayout.cs

@@ -0,0 +1,78 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip;
+
+/// <summary>
+///     Computes byte offsets for declared UDT members under Logix natural-alignment rules so
+///     a single whole-UDT read (task #194) can decode each member from one buffer without
+///     re-reading per member. Declaration-driven — the caller supplies
+///     <see cref="AbCipStructureMember"/> rows; this helper produces the offset each member
+///     sits at in the parent tag's read buffer.
+/// </summary>
+/// <remarks>
+///     <para>Alignment rules applied per Rockwell "Logix 5000 Data Access" manual + the
+///     libplctag test fixtures: each member aligns to its natural boundary (SInt 1, Int 2,
+///     DInt/Real/Dt 4, LInt/ULInt/LReal 8), padding inserted before the member as needed.
+///     The total size is padded to the alignment of the largest member so arrays-of-UDT also
+///     work at element stride — though this helper is used only on single instances today.</para>
+///
+///     <para><see cref="TryBuild"/> returns <c>null</c> on unsupported member types
+///     (<see cref="AbCipDataType.Bool"/>, <see cref="AbCipDataType.String"/>,
+///     <see cref="AbCipDataType.Structure"/>). Whole-UDT grouping opts out of those groups
+///     and falls back to the per-tag read path — BOOL members are packed into a hidden host
+///     byte at the top of the UDT under Logix, so their offset can't be computed from
+///     declared-member order alone. The CIP Template Object reader produces a
+///     <see cref="AbCipUdtShape"/> that carries real offsets for BOOL + nested structs; when
+///     that shape is cached the driver can take the richer path instead.</para>
+/// </remarks>
+public static class AbCipUdtMemberLayout
+{
+    /// <summary>
+    ///     Try to compute member offsets for the supplied declared members. Returns <c>null</c>
+    ///     if any member type is unsupported for declaration-only layout.
+    /// </summary>
+    public static IReadOnlyDictionary<string, int>? TryBuild(
+        IReadOnlyList<AbCipStructureMember> members)
+    {
+        ArgumentNullException.ThrowIfNull(members);
+        if (members.Count == 0) return null;
+
+        var offsets = new Dictionary<string, int>(members.Count, StringComparer.OrdinalIgnoreCase);
+        var cursor = 0;
+
+        foreach (var member in members)
+        {
+            if (!TryGetSizeAlign(member.DataType, out var size, out var align))
+                return null;
+
+            if (cursor % align != 0)
+                cursor += align - (cursor % align);
+
+            offsets[member.Name] = cursor;
+            cursor += size;
+        }
+
+        return offsets;
+    }
+
+    /// <summary>
+    ///     Natural size + alignment for a Logix atomic type. <c>false</c> for types excluded
+    ///     from declaration-only grouping (Bool / String / Structure).
+    /// </summary>
+    private static bool TryGetSizeAlign(AbCipDataType type, out int size, out int align)
+    {
+        switch (type)
+        {
+            case AbCipDataType.SInt: case AbCipDataType.USInt:
+                size = 1; align = 1; return true;
+            case AbCipDataType.Int: case AbCipDataType.UInt:
+                size = 2; align = 2; return true;
+            case AbCipDataType.DInt: case AbCipDataType.UDInt:
+            case AbCipDataType.Real: case AbCipDataType.Dt:
+                size = 4; align = 4; return true;
+            case AbCipDataType.LInt: case AbCipDataType.ULInt:
+            case AbCipDataType.LReal:
+                size = 8; align = 8; return true;
+            default:
+                size = 0; align = 0; return false;
+        }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipUdtReadPlanner.cs

@@ -0,0 +1,109 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip;
+
+/// <summary>
+///     Task #194 — groups a ReadAsync batch of full-references into whole-UDT reads where
+///     possible. A group is emitted for every parent UDT tag whose declared
+///     <see cref="AbCipStructureMember"/>s produced a valid offset map AND at least two of
+///     its members appear in the batch; every other reference stays in the per-tag fallback
+///     list that <see cref="AbCipDriver.ReadAsync"/> runs through its existing read path.
+///     Pure function — the planner never touches the runtime + never reads the PLC.
+/// </summary>
+public static class AbCipUdtReadPlanner
+{
+    /// <summary>
+    ///     Split <paramref name="requests"/> into whole-UDT groups + per-tag leftovers.
+    ///     <paramref name="tagsByName"/> is the driver's <c>_tagsByName</c> map — both parent
+    ///     UDT rows and their fanned-out member rows live there. Lookup is OrdinalIgnoreCase
+    ///     to match the driver's dictionary semantics.
+    /// </summary>
+    public static AbCipUdtReadPlan Build(
+        IReadOnlyList<string> requests,
+        IReadOnlyDictionary<string, AbCipTagDefinition> tagsByName)
+    {
+        ArgumentNullException.ThrowIfNull(requests);
+        ArgumentNullException.ThrowIfNull(tagsByName);
+
+        var fallback = new List<AbCipUdtReadFallback>(requests.Count);
+        var byParent = new Dictionary<string, List<AbCipUdtReadMember>>(StringComparer.OrdinalIgnoreCase);
+
+        for (var i = 0; i < requests.Count; i++)
+        {
+            var name = requests[i];
+            if (!tagsByName.TryGetValue(name, out var def))
+            {
+                fallback.Add(new AbCipUdtReadFallback(i, name));
+                continue;
+            }
+
+            var (parentName, memberName) = SplitParentMember(name);
+            if (parentName is null || memberName is null
+                || !tagsByName.TryGetValue(parentName, out var parent)
+                || parent.DataType != AbCipDataType.Structure
+                || parent.Members is not { Count: > 0 })
+            {
+                fallback.Add(new AbCipUdtReadFallback(i, name));
+                continue;
+            }
+
+            var offsets = AbCipUdtMemberLayout.TryBuild(parent.Members);
+            if (offsets is null || !offsets.TryGetValue(memberName, out var offset))
+            {
+                fallback.Add(new AbCipUdtReadFallback(i, name));
+                continue;
+            }
+
+            if (!byParent.TryGetValue(parentName, out var members))
+            {
+                members = new List<AbCipUdtReadMember>();
+                byParent[parentName] = members;
+            }
+            members.Add(new AbCipUdtReadMember(i, def, offset));
+        }
+
+        // A single-member group saves nothing (one whole-UDT read replaces one per-member read)
+        // — demote to fallback to avoid paying the cost of reading the full UDT buffer only to
+        // pull one field out.
+        var groups = new List<AbCipUdtReadGroup>(byParent.Count);
+        foreach (var (parentName, members) in byParent)
+        {
+            if (members.Count < 2)
+            {
+                foreach (var m in members)
+                    fallback.Add(new AbCipUdtReadFallback(m.OriginalIndex, m.Definition.Name));
+                continue;
+            }
+            groups.Add(new AbCipUdtReadGroup(parentName, tagsByName[parentName], members));
+        }
+
+        return new AbCipUdtReadPlan(groups, fallback);
+    }
+
+    private static (string? Parent, string? Member) SplitParentMember(string reference)
+    {
+        var dot = reference.IndexOf('.');
+        if (dot <= 0 || dot == reference.Length - 1) return (null, null);
+        return (reference[..dot], reference[(dot + 1)..]);
+    }
+}
+
+/// <summary>A planner output: grouped UDT reads + per-tag fallbacks.</summary>
+public sealed record AbCipUdtReadPlan(
+    IReadOnlyList<AbCipUdtReadGroup> Groups,
+    IReadOnlyList<AbCipUdtReadFallback> Fallbacks);
+
+/// <summary>One UDT parent whose members were batched into a single read.</summary>
+public sealed record AbCipUdtReadGroup(
+    string ParentName,
+    AbCipTagDefinition ParentDefinition,
+    IReadOnlyList<AbCipUdtReadMember> Members);
+
+/// <summary>
+///     One member inside an <see cref="AbCipUdtReadGroup"/>. <c>OriginalIndex</c> is the
+///     slot in the caller's request list so the decoded value lands at the correct output
+///     offset. <c>Definition</c> is the fanned-out member-level tag definition. <c>Offset</c>
+///     is the byte offset within the parent UDT buffer where this member lives.
+/// </summary>
+public sealed record AbCipUdtReadMember(int OriginalIndex, AbCipTagDefinition Definition, int Offset);
+
+/// <summary>A reference that falls back to the per-tag read path.</summary>
+public sealed record AbCipUdtReadFallback(int OriginalIndex, string Reference);

src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/IAbCipTagRuntime.cs

@@ -31,6 +31,17 @@ public interface IAbCipTagRuntime : IDisposable
     /// </summary>
     object? DecodeValue(AbCipDataType type, int? bitIndex);
 
+    /// <summary>
+    ///     Decode a value at an arbitrary byte offset in the local buffer. Task #194 —
+    ///     whole-UDT reads perform one <see cref="ReadAsync"/> on the parent UDT tag then
+    ///     call this per declared member with its computed offset, avoiding one libplctag
+    ///     round-trip per member. Implementations that do not support offset-aware decoding
+    ///     may fall back to <see cref="DecodeValue"/> when <paramref name="offset"/> is zero;
+    ///     offsets greater than zero against an unsupporting runtime should return <c>null</c>
+    ///     so the planner can skip grouping.
+    /// </summary>
+    object? DecodeValueAt(AbCipDataType type, int offset, int? bitIndex);
+
     /// <summary>
     ///     Encode <paramref name="value"/> into the local buffer per the tag's type. Callers
     ///     pair this with <see cref="WriteAsync"/>.

src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/LibplctagTagRuntime.cs

@@ -32,24 +32,26 @@ internal sealed class LibplctagTagRuntime : IAbCipTagRuntime
 
     public int GetStatus() => (int)_tag.GetStatus();
 
-    public object? DecodeValue(AbCipDataType type, int? bitIndex) => type switch
+    public object? DecodeValue(AbCipDataType type, int? bitIndex) => DecodeValueAt(type, 0, bitIndex);
+
+    public object? DecodeValueAt(AbCipDataType type, int offset, int? bitIndex) => type switch
     {
         AbCipDataType.Bool => bitIndex is int bit
             ? _tag.GetBit(bit)
-            : _tag.GetInt8(0) != 0,
-        AbCipDataType.SInt => (int)(sbyte)_tag.GetInt8(0),
-        AbCipDataType.USInt => (int)_tag.GetUInt8(0),
-        AbCipDataType.Int => (int)_tag.GetInt16(0),
-        AbCipDataType.UInt => (int)_tag.GetUInt16(0),
-        AbCipDataType.DInt => _tag.GetInt32(0),
-        AbCipDataType.UDInt => (int)_tag.GetUInt32(0),
-        AbCipDataType.LInt => _tag.GetInt64(0),
-        AbCipDataType.ULInt => (long)_tag.GetUInt64(0),
-        AbCipDataType.Real => _tag.GetFloat32(0),
-        AbCipDataType.LReal => _tag.GetFloat64(0),
-        AbCipDataType.String => _tag.GetString(0),
-        AbCipDataType.Dt => _tag.GetInt32(0), // seconds-since-epoch DINT; consumer widens as needed
-        AbCipDataType.Structure => null,       // UDT whole-tag decode lands in PR 6
+            : _tag.GetInt8(offset) != 0,
+        AbCipDataType.SInt => (int)(sbyte)_tag.GetInt8(offset),
+        AbCipDataType.USInt => (int)_tag.GetUInt8(offset),
+        AbCipDataType.Int => (int)_tag.GetInt16(offset),
+        AbCipDataType.UInt => (int)_tag.GetUInt16(offset),
+        AbCipDataType.DInt => _tag.GetInt32(offset),
+        AbCipDataType.UDInt => (int)_tag.GetUInt32(offset),
+        AbCipDataType.LInt => _tag.GetInt64(offset),
+        AbCipDataType.ULInt => (long)_tag.GetUInt64(offset),
+        AbCipDataType.Real => _tag.GetFloat32(offset),
+        AbCipDataType.LReal => _tag.GetFloat64(offset),
+        AbCipDataType.String => _tag.GetString(offset),
+        AbCipDataType.Dt => _tag.GetInt32(offset),
+        AbCipDataType.Structure => null,
         _ => null,
     };