Auto: abcip-3.3 — read-strategy selector (WholeUdt / MultiPacket / Auto)

Closes #237

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

@@ -124,12 +124,83 @@ public sealed class AbCipDriverOptions
 ///     misconfiguration does not fault the driver. <see cref="AbCip.AddressingMode.Auto"/> currently
 ///     resolves to symbolic — a future PR will plumb a real auto-detection heuristic; the docs
 ///     in <c>docs/drivers/AbCip-Performance.md</c> §"Addressing mode" call this out.</param>
+/// <param name="ReadStrategy">PR abcip-3.3 — picks how a multi-member UDT batch is read on this
+///     device. <see cref="AbCip.ReadStrategy.WholeUdt"/> issues one read per parent UDT and decodes
+///     each subscribed member from the buffer in-memory (the historical behaviour that ships in
+///     task #194 — best when a large fraction of a UDT's members are subscribed).
+///     <see cref="AbCip.ReadStrategy.MultiPacket"/> bundles per-member reads into one CIP
+///     Multi-Service Packet — best for sparse UDT subscriptions where reading the whole UDT
+///     buffer just to extract one or two fields wastes wire bandwidth. <see cref="AbCip.ReadStrategy.Auto"/>
+///     (the default) lets the planner pick per-batch using
+///     <paramref name="MultiPacketSparsityThreshold"/>: if the subscribed-member fraction is below
+///     the threshold MultiPacket wins, otherwise WholeUdt wins. Family compatibility — Micro800 /
+///     SLC500 / PLC5 lack Multi-Service-Packet support per
+///     <see cref="PlcFamilies.AbCipPlcFamilyProfile.SupportsRequestPacking"/>; user-forced
+///     <see cref="AbCip.ReadStrategy.MultiPacket"/> against those families logs a warning + falls
+///     back to <see cref="AbCip.ReadStrategy.WholeUdt"/> at device-init time. The libplctag .NET
+///     wrapper (1.5.x) does not expose a public knob for explicit Multi-Service-Packet bundling,
+///     so today's MultiPacket runtime issues one libplctag read per member; the planner's grouping
+///     is still load-bearing because it gives the runtime the right plan to execute when an
+///     upstream wrapper release exposes wire-level bundling.</param>
+/// <param name="MultiPacketSparsityThreshold">PR abcip-3.3 — sparsity-threshold knob the planner
+///     uses when <paramref name="ReadStrategy"/> is <see cref="AbCip.ReadStrategy.Auto"/>. The
+///     planner divides <c>subscribedMembers / totalMembers</c> for each parent UDT in a batch;
+///     a fraction strictly less than the threshold picks
+///     <see cref="AbCip.ReadStrategy.MultiPacket"/>, else <see cref="AbCip.ReadStrategy.WholeUdt"/>.
+///     Default <c>0.25</c> — picked because reading 1/4 of a UDT's members is the rough break-even
+///     where the wire-cost of one whole-UDT read still beats N member reads on ControlLogix's
+///     4002-byte connection size; see <c>docs/drivers/AbCip-Performance.md</c> §"Read strategy".
+///     Clamped to <c>[0..1]</c> at planner time; values outside the range silently saturate.</param>
 public sealed record AbCipDeviceOptions(
     string HostAddress,
     AbCipPlcFamily PlcFamily = AbCipPlcFamily.ControlLogix,
     string? DeviceName = null,
     int? ConnectionSize = null,
-    AddressingMode AddressingMode = AddressingMode.Auto);
+    AddressingMode AddressingMode = AddressingMode.Auto,
+    ReadStrategy ReadStrategy = ReadStrategy.Auto,
+    double MultiPacketSparsityThreshold = 0.25);
+
+/// <summary>
+///     PR abcip-3.3 — per-device strategy for reading multi-member UDT batches. <see cref="WholeUdt"/>
+///     mirrors the task #194 behaviour: one libplctag read on the parent tag, each subscribed member
+///     decoded from the buffer at its computed offset. <see cref="MultiPacket"/> bundles per-member
+///     reads into one CIP Multi-Service Packet so sparse UDT subscriptions don't pay for the whole
+///     UDT buffer. <see cref="Auto"/> lets the planner pick per-batch using
+///     <see cref="AbCipDeviceOptions.MultiPacketSparsityThreshold"/>.
+/// </summary>
+/// <remarks>
+///     <para>Strategy resolution lives at two layers:</para>
+///     <list type="bullet">
+///         <item><b>Device init</b> — user-forced <see cref="MultiPacket"/> against a family whose
+///             profile sets <see cref="PlcFamilies.AbCipPlcFamilyProfile.SupportsRequestPacking"/>
+///             = <c>false</c> (Micro800, SLC500, PLC5) falls back to <see cref="WholeUdt"/> with a
+///             warning. <see cref="Auto"/> stays as-is (the planner re-evaluates per batch).</item>
+///         <item><b>Per-batch (Auto only)</b> — for each parent UDT in the request set, the planner
+///             computes <c>subscribedMembers / totalMembers</c> and routes the group through
+///             <see cref="MultiPacket"/> when the fraction is below the threshold, else
+///             <see cref="WholeUdt"/>.</item>
+///     </list>
+///     <para>libplctag .NET wrapper (1.5.x) does not expose explicit Multi-Service-Packet bundling,
+///     so today's runtime issues one libplctag read per member when the planner picks MultiPacket —
+///     the same wrapper limitation called out in PR abcip-3.1 (ConnectionSize) and PR abcip-3.2
+///     (instance-ID addressing). The planner's grouping is still observable from tests + future-proofs
+///     the driver for when an upstream wrapper release exposes wire-level bundling.</para>
+/// </remarks>
+public enum ReadStrategy
+{
+    /// <summary>Driver picks per-batch based on
+    ///     <see cref="AbCipDeviceOptions.MultiPacketSparsityThreshold"/>. Default.</summary>
+    Auto = 0,
+
+    /// <summary>One read per parent UDT; members decoded from the buffer in-memory. Best when a
+    ///     large fraction of the UDT's members are subscribed (dense reads).</summary>
+    WholeUdt = 1,
+
+    /// <summary>Bundle per-member reads into one CIP Multi-Service Packet. Best when only a few
+    ///     members of a large UDT are subscribed (sparse reads). Unsupported on Micro800 / SLC500 /
+    ///     PLC5; the driver warns + falls back to <see cref="WholeUdt"/> at device init.</summary>
+    MultiPacket = 2,
+}
 
 /// <summary>
 ///     PR abcip-3.2 — how the AB CIP driver addresses tags on a given device. <see cref="Symbolic"/>