lmxopcua/docs/plans/abcip-plan.md

# AbCip Driver — Implementation Plan

> Source of gap analysis: [featuregaps.md → AbCip](../featuregaps.md#abcip-allen-bradley-ethernetip--logix)
>
> This plan covers the **Build = Yes** items only. Skip-rated gaps are listed at the bottom for traceability.

## Summary

This plan closes the 16 Build-rated AbCip gaps in five phases ordered to ship correctness fixes
first, then engineering workflow, then performance, then operability, and finally redundancy.
Phase 1 lands the data-type fidelity work (LINT/ULINT, native STRINGnn, array slicing,
write-multi packing) that today silently truncates 64-bit values and serialises adjacent reads
into N round-trips. Phase 2 introduces the offline tag-import workflow (L5K/L5X + CSV) that
Studio 5000 shops require before they will switch off Kepware. Phase 3 exposes the
performance levers commercial drivers ship as field knobs — symbolic vs logical addressing,
configurable Connection Size, and the logical-blocking / logical-non-blocking strategy
selector. Phase 4 surfaces per-tag scan rates, write deadband, online tag-DB refresh trigger,
and the diagnostic system tags an HMI dashboard expects. Phase 5 adds HSBY paired-IP failover
for continuous-process plants. Headline outcome: parity with Kepware's Logix Database Settings
and TOP Server's protocol-mode picker, with measurable throughput wins (3-5x on dense rigs via
logical addressing, single-PDU reads on contiguous arrays, single-PDU writes on multi-tag
recipe pushes).

## Phased delivery

### Phase 1 — Data-type correctness (4 PRs)

Goal: stop silently losing data. None of the items in this phase are user-visible features —
they are correctness fixes against existing capability surfaces.

#### PR 1.1 — LINT / ULINT 64-bit fidelity
- **Scope**: replace the truncating `Int32` widening at `AbCipDataType.cs:53` with `Int64`
  routing across decode + encode + the `DriverDataType` map. Includes `DT` (epoch-millis on
  Logix v32+ surfaces as LINT, not DINT — verify against `LibplctagTagRuntime.cs:53` before
  reusing the same code-path).
- **Files**: `AbCipDataType.cs` (mapping), `LibplctagTagRuntime.cs` (already calls
  `_tag.GetInt64` / `SetInt64`, so the runtime is correct — the gap is the surface enum
  flattening into `Int32`), `Core.Abstractions/DriverDataType.cs` may need an `Int64` /
  `UInt64` member if not already present.
- **Test approach**: unit (xUnit + Shouldly) with a fake `IAbCipTagRuntime` that returns
  `long.MaxValue` on `DecodeValueAt(LInt, ...)`; assert the snapshot value round-trips through
  the read path without truncation. Integration test against pymodbus is N/A — needs a live
  Logix or a libplctag mock-server fixture; keep this unit-only and rely on smoke testing on
  the dev box with a real ControlLogix.
- **Effort**: S
- **Dependencies**: confirm `DriverDataType.Int64` exists; if not, that is a Core change
  shared with the Modbus TODO at `AbCipDataType.cs:53`.
- **Docs / fixture / e2e**: appends a Logix-types row to the type-mapping table in
  `docs/Driver.AbCip.Cli.md` (CLI gains `--type LInt` / `--type ULInt`); extends
  `docs/drivers/AbServer-Test-Fixture.md` §"What it actually covers" to list `LINT` once
  ab_server is reseeded with a `TestLINT:LINT[1]` tag; updates the
  `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Docker/docker-compose.yml`
  ControlLogix profile to seed `TestLINT`; adds a 64-bit assertion case in
  `AbCipReadSmokeTests`; extends `scripts/e2e/test-abcip.ps1` with an LInt loopback
  assertion (and a matching seeded `TestLINT` in `scripts/smoke/seed-abcip-smoke.sql`).

#### PR 1.2 — Native STRING / STRINGnn variant decoding
- **Scope**: Today `AbCipDataType.String` flattens any Logix `STRING` UDT into a .NET
  string via libplctag's `_tag.GetString(0)`. Logix programs commonly define
  `STRING_20`, `STRING_40`, `STRING_80` variants with different DATA-array sizes; libplctag
  honours these when the tag name resolves to the user-defined type, but our discovery
  emits them as the generic `String` placeholder. Add a `StringLength` field to
  `AbCipStructureMember` + `AbCipTagDefinition` so declared variants carry their cap, and
  thread it into the `Tag.Name` attribute or a libplctag string-cap hint.
- **Files**: `AbCipDataType.cs`, `AbCipDriverOptions.cs` (record fields), `LibplctagTagRuntime.cs`
  (string-length aware decode/encode), and the discovery emit at `AbCipDriver.cs:715`.
- **Test approach**: unit test with a fake runtime returning `string` values shorter and
  longer than the declared cap; integration test deferred until a sample L5X with mixed
  STRING variants is available.
- **Effort**: M
- **Dependencies**: investigate libplctag's `str_max_capacity` / `str_count_word_bytes`
  attributes — the docs reference them but the C# wrapper may not expose them; if not, this
  PR must extend `LibplctagTagRuntime` with a raw-buffer decode path.
- **Docs / fixture / e2e**: extends `docs/Driver.AbCip.Cli.md` with a new `--string-size`
  flag in the `read`/`write` cookbook plus a STRINGnn worked example; updates
  `docs/drivers/AbServer-Test-Fixture.md` §"What it actually covers" to list
  `STRING_20`/`STRING_80` once seeded; extends the ControlLogix profile in
  `tests/.../Docker/docker-compose.yml` with `TestSTRING80:STRING[1]` (plus a `STRING_20`
  variant if `ab_server` honours non-default DATA caps; otherwise documented as Emulate-tier
  only); adds `tests/.../IntegrationTests/AbCipStringDecodingTests.cs` round-trip; adds a
  short-string round-trip case to `scripts/e2e/test-abcip.ps1` and a `TestSTRING80` row to
  `scripts/smoke/seed-abcip-smoke.sql`.

#### PR 1.3 — Array-slice read addressing `Tag[0..N]`
- **Scope**: today `AbCipTagPath` parses `Tag[3,5]` as a single element. Add slice syntax
  `Tag[0..15]` (parsed in `AbCipTagPath.TryParse`) and a planner that issues one libplctag
  read with `elem_count=N` per Rockwell array semantics, decoding the buffer at element
  stride into N output snapshots. Mirrors the whole-UDT planner pattern.
- **Files**: `AbCipTagPath.cs` (parser — add `IsSlice` + `SliceLength` to the path segment
  record, or carry it on `AbCipTagPath` itself), new `AbCipArrayReadPlanner.cs` next to
  `AbCipUdtReadPlanner.cs`, `AbCipDriver.ReadAsync` to dispatch through the planner,
  `IAbCipTagRuntime` to add `DecodeArrayAt(type, elementStride, count)` or build on
  `DecodeValueAt`. Investigate libplctag's `elem_count` attribute on `Tag` create to confirm
  the right wire-level switch.
- **Test approach**: parser unit tests for the new syntax, planner unit tests with fake
  runtime, integration smoke against a live ControlLogix DINT[100] tag using the dev-box
  PLC.
- **Effort**: L
- **Dependencies**: PR 1.1 must land first if the array element type is LINT — otherwise the
  slice path silently truncates 64-bit elements.
- **Docs / fixture / e2e**: extends `docs/Driver.AbCip.Cli.md` `read` section with the
  `Tag[0..N]` slice syntax + a worked example reading `Recipe[0..15]` in one round-trip;
  updates `docs/drivers/AbServer-Test-Fixture.md` §"What it actually covers" to mention
  the existing `DINT[16]` array tag is now exercised end-to-end via slicing; extends
  `AbCipReadSmokeTests` with a slice-read assertion against the seeded `TestDINTArray`;
  adds `tests/.../IntegrationTests/AbCipArraySliceTests.cs` covering edge cases
  (boundary, single-element, full-range); adds a slice-read assertion to
  `scripts/e2e/test-abcip.ps1`.

#### PR 1.4 — CIP multi-tag write packing
- **Scope**: `AbCipDriver.WriteAsync` (`AbCipDriver.cs:460-546`) loops over writes one-by-one.
  Group writes by `(device, no-bit-RMW)` and submit one CIP Multi-Service Packet (0x0A)
  carrying up to N write-singles per round-trip. Honours the per-family
  `SupportsRequestPacking` flag at `AbCipPlcFamilyProfile.cs:36,43,51,59` — Micro800 falls
  back to the existing per-write loop because its profile already disables packing.
- **Files**: `AbCipDriver.cs` (add a write planner mirroring the read planner), new
  `AbCipMultiWritePlanner.cs`, possibly a new `IAbCipTagRuntime.WriteBatchAsync` method or a
  new `IAbCipMultiWriter` capability since libplctag's high-level `Tag.WriteAsync` is
  per-tag — investigate libplctag's `cip-msg-multi` raw-CIP path or whether building a
  Multi-Service Packet via `plc_tag_create("name=@raw,...")` is feasible.
- **Test approach**: unit test the planner with a synthetic batch (mixed-device, mixed
  bit-RMW, one Micro800); integration test recipe-style 50-tag write against ControlLogix
  measuring round-trip count via Wireshark or via a libplctag debug-trace sink.
- **Effort**: L
- **Dependencies**: investigate libplctag multi-service-packet API; if absent, this PR may
  need to drop down to raw CIP via the `@raw` pseudo-tag or be deferred.
- **Docs / fixture / e2e**: appends a "Multi-tag writes" subsection to
  `docs/Driver.AbCip.Cli.md` (no flag — automatic batching when multiple writes queue
  inside one publish) plus a note that Micro800 falls back per profile; updates
  `docs/drivers/AbServer-Test-Fixture.md` §7 ("Capability surfaces beyond read") to flip
  `IWritable.WriteAsync` from "no smoke test" to covered for the multi-write path; adds
  `tests/.../IntegrationTests/AbCipMultiWriteTests.cs` asserting 50-tag batch lands in one
  round-trip (count via libplctag debug-trace sink); extends `scripts/e2e/test-abcip.ps1`
  with a recipe-style multi-write step; extends seed SQL with two extra DINT tags so the
  e2e has a packing target.

### Phase 2 — Tag-import workflows (4 PRs)

Goal: replicate Kepware's Logix Database Settings — point the driver at an L5K/L5X export or
a CSV and have the tag table populate without an online controller.

#### PR 2.1 — L5K parser + ingest
- **Scope**: parse a Studio 5000 L5K export (a labelled-section text format with
  `TAG ... END_TAG` blocks, `DATATYPE ... END_DATATYPE` UDT definitions, and program-scope
  qualifiers). Produce `AbCipTagDefinition` + `AbCipStructureMember` records that match the
  declarative options shape. Includes Description ingest (PR 2.3 lifts it to OPC UA
  `Description`).
- **Files**: new `Import/L5kParser.cs`, new `Import/IL5kSource.cs` for testability, new
  `Import/L5kIngest.cs` that converts parsed records into `AbCipTagDefinition`. Hook into
  `AbCipDriverOptions` via a new `TagImports` collection (filenames or inline blobs) parsed
  on `AbCipDriver.InitializeAsync`.
- **Test approach**: unit-only with sample L5K files in `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.Tests/Import/Fixtures/`
  covering controller-scope tags, program-scope tags, alias tags (skipped per Kepware
  precedent), and UDTs with nested structures.
- **Effort**: L
- **Dependencies**: none — pure-text parser.
- **Docs / fixture / e2e**: new doc `docs/drivers/AbCip-TagImport.md` covering the L5K
  format support matrix (controller-scope / program-scope / UDT / alias-skipped) and a
  worked example of pointing `AbCipDriverOptions.TagImports` at an L5K export; appends a
  `tag-import` command section to `docs/Driver.AbCip.Cli.md` (CLI gains
  `tag-import --file foo.L5K`); fixture-side no change to `ab_server` (offline parse —
  no PLC needed) but adds sample L5K files under
  `tests/.../AbCip.Tests/Import/Fixtures/`; extends `scripts/e2e/test-abcip.ps1` with an
  offline `tag-import` smoke that diffs the parsed tag set against a golden JSON.

#### PR 2.2 — L5X (XML) parser + ingest
- **Scope**: same surface as PR 2.1 but parses Studio 5000's XML export. L5X is the de-facto
  modern format (Studio 5000 v21+) and carries richer metadata than L5K including
  ExternalAccess attributes and AOI definitions.
- **Files**: new `Import/L5xParser.cs` using `System.Xml.XPath`, share the `IL5kSource` /
  `L5kIngest` ingest layer with PR 2.1 by introducing a common `ParsedTagsBundle` record.
- **Test approach**: unit tests with sample L5X fixtures including an AOI-typed tag (sets up
  the AOI work in PR 2.7).
- **Effort**: L
- **Dependencies**: PR 2.1 is preferred first to settle the shared ingest seam.
- **Docs / fixture / e2e**: extends `docs/drivers/AbCip-TagImport.md` (created in PR 2.1)
  with the L5X-specific section — namespace handling, ExternalAccess attributes, AOI
  references; extends the `tag-import` CLI section in `docs/Driver.AbCip.Cli.md` to note
  L5X auto-detection by file extension; sample L5X files added under
  `tests/.../AbCip.Tests/Import/Fixtures/` (one with an AOI-typed tag for PR 2.6);
  reuses the offline `tag-import` step from `scripts/e2e/test-abcip.ps1` (now driven by
  L5X) — no fixture container change because parse is offline; cross-links from
  `tests/.../IntegrationTests/LogixProject/README.md` so the on-site Emulate L5X export
  doubles as a parser fixture.

#### PR 2.3 — Tag descriptions surfaced as OPC UA `Description`
- **Scope**: extend `AbCipTagDefinition` with `Description` (string?), populate it from the
  L5K/L5X parsers, and thread it through to `DriverAttributeInfo` so the address-space
  builder sets the OPC UA `Description` attribute. Also lifts the description onto
  `AbCipStructureMember` for member-level metadata.
- **Files**: `AbCipDriverOptions.cs` (record fields), `AbCipDriver.cs:760-770`
  (`ToAttributeInfo` helper), `Core.Abstractions/DriverAttributeInfo.cs` (verify it carries
  a Description field; if not, that becomes a Core PR shared across drivers).
- **Test approach**: unit — a discovery test asserts that a tag with a description ends up
  with that description on the `DriverAttributeInfo` record.
- **Effort**: S
- **Dependencies**: PR 2.1 / PR 2.2 (descriptions only land via importer).
- **Docs / fixture / e2e**: appends a "Description metadata" subsection to
  `docs/drivers/AbCip-TagImport.md` documenting how Studio 5000 descriptions surface as
  OPC UA `Description`; no CLI surface change (read-side only — the existing
  `otopcua-cli read` already projects `Description`); no fixture container change; adds
  a cross-driver assertion to the existing OPC UA browse test in
  `tests/.../IntegrationTests/` verifying the description survives the full
  parser → driver → server → client path; extends `scripts/e2e/test-abcip.ps1` with a
  one-line `Description != null` assertion after the import smoke step.

#### PR 2.4 — CSV tag import / export
- **Scope**: a CSV round-trip matching the Kepware column layout (`Tag Name, Address, Data
  Type, Respect Data Type, Client Access, Scan Rate, Description, Scaling`). Import populates
  `AbCipTagDefinition`; export dumps the live tag table for editing in Excel.
- **Files**: new `Import/CsvTagImporter.cs`, new `Import/CsvTagExporter.cs`, integration
  point in `AbCipDriverOptions.TagImports` parallel to PR 2.1's hook. Export hook is
  exposed via the CLI (`docs/Driver.AbCip.Cli.md`) — add a `tag-export` command.
- **Test approach**: unit tests for parser + writer with fixture CSVs; CLI integration test
  using a synthetic options payload.
- **Effort**: M
- **Dependencies**: lighter than 2.1/2.2 — could ship in either order, but landing CSV after
  L5X means the CSV export reuses the `ParsedTagsBundle` shape.
- **Docs / fixture / e2e**: appends a "CSV tag table" section to
  `docs/drivers/AbCip-TagImport.md` documenting the column layout (Kepware-compatible) and
  round-trip semantics; appends `tag-export` and CSV-flavour `tag-import` commands to
  `docs/Driver.AbCip.Cli.md`; adds sample CSVs under
  `tests/.../AbCip.Tests/Import/Fixtures/` plus a CLI integration test
  (`tests/.../AbCip.Tests/Import/CsvRoundTripTests.cs`); extends
  `scripts/e2e/test-abcip.ps1` with an export-then-import-then-diff scenario (no PLC
  required); fixture-side no change.

#### PR 2.5 — Online tag-DB refresh trigger (`$Sys$UpdateTagInfo` parity)
- **Scope**: AVEVA exposes `$Sys$UpdateTagInfo` so an HMI can write `1` to force the driver
  to re-walk the controller's symbol table after a Studio 5000 download — without restarting
  the driver. Implement as a new `IDriverControl.RebrowseAsync()` invoked by the server or
  via a system-tag write (PR 4.4 will surface system tags as browseable variables — once
  that lands, this becomes the writeable system tag `_RefreshTagDb`). For now expose it
  via the CLI and via a new `AbCipDriver.RebrowseAsync` method.
- **Files**: `AbCipDriver.cs` (new method that re-runs the `@tags` enumerator without going
  through full `ReinitializeAsync`), CLI command in `src/ZB.MOM.WW.OtOpcUa.Driver.AbCip.Cli/`,
  documentation update in `docs/Driver.AbCip.Cli.md`.
- **Test approach**: unit test that two consecutive `RebrowseAsync` calls produce two
  enumeration passes; integration smoke against the dev-box ControlLogix verifying the
  address space picks up a tag added between rebrowses.
- **Effort**: M
- **Dependencies**: ties cleanly into PR 4.4 (system tags) but ships earlier as a
  programmatic API.
- **Docs / fixture / e2e**: appends a `rebrowse` command to `docs/Driver.AbCip.Cli.md`
  with a Studio 5000 download recipe ("after a download, run
  `otopcua-abcip-cli rebrowse -g …`"); cross-references the future `_RefreshTagDb` system
  tag once PR 4.4 lands; updates `docs/drivers/AbServer-Test-Fixture.md` §7 to mark
  `ITagDiscovery.DiscoverAsync` as covered for the rebrowse path; adds
  `tests/.../IntegrationTests/AbCipRebrowseTests.cs` driving two consecutive
  enumerations (the second sees a tag added between calls — ab_server supports runtime
  reseed via its REST hook); extends `scripts/e2e/test-abcip.ps1` with a
  rebrowse-after-reseed assertion (or marks it `[OnlyIfRig]` if the simulator's reseed
  hook isn't reachable).

#### PR 2.6 — AOI (Add-On Instruction) input/output handling
- **Scope**: AOIs are first-class types in L5X (`AddOnInstructionDefinition` blocks). The
  Template Object decoder at `CipTemplateObjectDecoder.cs` likely already handles them at
  the wire level (an AOI is a Logix UDT with InOut/Input/Output qualifiers). This PR adds:
  (a) AOI-aware browse paths so an AOI instance shows up as a folder with `Inputs/`,
  `Outputs/`, `InOut/` sub-folders; (b) skip-on-discovery for `InOut` parameters per
  Kepware's documented limitation (InOut is a pointer, not a value).
- **Files**: extend `AbCipStructureMember` with an `AoiQualifier` enum
  (Input/Output/InOut/Local), L5K/L5X parser extends to set it, `AbCipDriver.DiscoverAsync`
  groups members into qualifier-named sub-folders.
- **Test approach**: unit test discovery against an AOI-containing fixture.
- **Effort**: M
- **Dependencies**: PR 2.2 (L5X) lands the AOI definition parsing.
- **Docs / fixture / e2e**: appends an "AOI handling" section to
  `docs/drivers/AbCip-TagImport.md` covering Inputs/Outputs/InOut grouping + the InOut
  skip rationale; updates `docs/drivers/AbServer-Test-Fixture.md` §"What it does NOT
  cover" to keep AOIs flagged as ab_server-blocked but call out Logix Emulate as the
  authoritative tier; adds a sample AOI-bearing L5X under
  `tests/.../AbCip.Tests/Import/Fixtures/` and a discovery test that asserts the
  Inputs/Outputs sub-folder shape; promotes
  `tests/.../IntegrationTests/Emulate/AbCipEmulateAoiTests.cs` (gated on
  `AB_SERVER_PROFILE=emulate`) — no `scripts/e2e/test-abcip.ps1` change because AOIs
  need Emulate or a rig.

### Phase 3 — Performance levers (3 PRs)

Goal: expose the protocol-mode + connection-tuning knobs that commercial drivers expose as
device-level config.

#### PR 3.1 — Configurable CIP Connection Size per device
- **Scope**: today the family profile hard-codes 4002 / 504 / 488 at
  `AbCipPlcFamilyProfile.cs:33,42,49`. Add an optional `ConnectionSize` field to
  `AbCipDeviceOptions` that overrides the family default; thread it through to the
  libplctag tag-create attribute (`connection_size=N`). Validate against a sensible range
  (500-4002 per Kepware's slider).
- **Files**: `AbCipDriverOptions.cs:70-73` (extend `AbCipDeviceOptions` record),
  `IAbCipTagRuntime.cs` (extend `AbCipTagCreateParams` with `ConnectionSize`),
  `LibplctagTagRuntime.cs` (set the `Tag.PlcType`-adjacent attribute — investigate libplctag
  C# wrapper's exposure of `connection_size`; may need to set via `Tag.AddAttribute` if a
  named property doesn't exist).
- **Test approach**: unit test that custom Connection Size flows from options into the
  `AbCipTagCreateParams`; integration smoke against the dev-box ControlLogix verifying
  reduced-size connections succeed on legacy v19 firmware. Live test required because
  libplctag rejects out-of-range values silently in some versions.
- **Effort**: S
- **Dependencies**: investigate libplctag `connection_size` attribute exposure.
- **Docs / fixture / e2e**: appends a "Connection Size" subsection to a new
  `docs/drivers/AbCip-Performance.md` (consolidates the Phase 3 knobs in one place) and a
  brief note + warning-symptom callout in `docs/Driver.AbCip.Cli.md` for the new
  per-device option in the Driver config; updates
  `docs/drivers/AbServer-Test-Fixture.md` §5 (CompactLogix narrow cap) noting that
  ab_server still doesn't enforce the cap so live coverage stays Emulate/rig-only;
  extends `scripts/smoke/seed-abcip-smoke.sql` with a `ConnectionSize` field demo;
  no `scripts/e2e/test-abcip.ps1` change (boot-time config knob, no per-call surface).

#### PR 3.2 — Symbolic vs logical (instance-ID) addressing toggle
- **Scope**: libplctag exposes `use_connected_msg=1&allow_packet_response_packing=1&logical_segment=1`
  (or similar — investigate the exact attribute name) for instance-ID addressing that skips
  per-poll ASCII parsing. Add a per-device `AddressingMode` enum
  (`Symbolic | Logical | Auto`) and thread it through `AbCipTagCreateParams`. `Auto` is the
  default and matches today's behaviour; `Logical` flips libplctag into instance-ID mode.
  Logical mode requires a one-time symbol-table walk to map names to instance IDs — reuse
  `LibplctagTagEnumerator` for the bootstrap.
- **Files**: `AbCipDriverOptions.cs` (per-device enum), `IAbCipTagRuntime.cs`
  (`AbCipTagCreateParams.AddressingMode`), `LibplctagTagRuntime.cs` (translate to libplctag
  attributes), `AbCipDriver.cs` (run a one-time symbol-walk on first read in Logical mode).
- **Test approach**: unit test attribute construction; integration benchmark — read 1000
  tags in Symbolic vs Logical and assert >2x throughput on the dev-box ControlLogix.
- **Effort**: L
- **Dependencies**: investigate libplctag's instance-ID API; the mapping pseudo-tag is
  `@tags` (already used for browse) but the per-tag wire flag needs research. If libplctag
  doesn't expose this cleanly, the PR drops down to the raw `cip_addr` attribute.
- **Docs / fixture / e2e**: appends an "Addressing mode" section to
  `docs/drivers/AbCip-Performance.md` (Symbolic / Logical / Auto trade-offs); adds a
  per-device `addressing-mode` knob to `docs/Driver.AbCip.Cli.md` (CLI gains
  `--addressing-mode` on `read`/`subscribe`/`write` for ad-hoc benchmarking); updates
  `docs/drivers/AbServer-Test-Fixture.md` §"What it actually covers" to add Logical-mode
  reads if ab_server's symbol table walks correctly under instance IDs (otherwise
  marked Emulate-tier-only); adds a benchmark test
  `tests/.../IntegrationTests/AbCipAddressingModeBenchTests.cs`; extends
  `scripts/e2e/test-abcip.ps1` with a Symbolic-vs-Logical sanity assertion
  (read 1000 tags both modes, assert Logical >= Symbolic throughput).

#### PR 3.3 — Logical-blocking / non-blocking strategy selector
- **Scope**: TOP Server names two modes: "logical-blocking" (whole-UDT read, decode members
  in-memory) and "logical-non-blocking" (per-member reads packed into one Multi-Service
  Packet). We have one direction shipped via `AbCipUdtReadPlanner`. Add a per-device
  `ReadStrategy` enum with three values: `WholeUdt` (current behaviour), `MultiPacket`
  (new: use libplctag request-packing to bundle per-member reads into one PDU when the UDT
  is sparse — i.e. only 2-of-50 members subscribed), and `Auto` (planner picks based on
  fraction-of-members-subscribed threshold). Strategy is per-device because Micro800
  doesn't support packing.
- **Files**: `AbCipDriverOptions.cs` (per-device enum), `AbCipUdtReadPlanner.cs` (add the
  threshold heuristic), new `AbCipMultiPacketReadPlanner.cs`, `AbCipDriver.ReadAsync`
  dispatch. Honours `AbCipPlcFamilyProfile.SupportsRequestPacking` at the family level so a
  user-selected `MultiPacket` on Micro800 falls back to per-tag with a warning logged.
- **Test approach**: unit test the heuristic on synthetic batches of varying sparsity;
  integration benchmark with a 50-member UDT where 5 members are subscribed — verify
  MultiPacket beats WholeUdt by buffer-size delta.
- **Effort**: L
- **Dependencies**: PR 1.4 (multi-tag write packing) builds the same libplctag-multi-service
  primitive; landing 1.4 first reduces scope here.
- **Docs / fixture / e2e**: appends a "Read strategy" section to
  `docs/drivers/AbCip-Performance.md` covering WholeUdt / MultiPacket / Auto plus the
  sparsity-threshold heuristic; updates `docs/drivers/AbServer-Test-Fixture.md` §1
  (UDT coverage) with a note that strategy switching is decided in the planner and
  unit-tested only — Emulate is the authoritative wire-level coverage; adds
  `tests/.../IntegrationTests/Emulate/AbCipEmulateMultiPacketReadTests.cs` (gated on
  `AB_SERVER_PROFILE=emulate`); no CLI surface change beyond the existing
  per-device option, no `scripts/e2e/test-abcip.ps1` change because the simulator
  doesn't differentiate the two strategies on the wire.

### Phase 4 — Operability (4 PRs)

Goal: make the driver behave like a SCADA driver — per-tag scan rates, write deadband,
diagnostic system tags, online refresh trigger.

#### PR 4.1 — Per-tag scan rate / scan group bucketing
- **Scope**: today subscriptions key on a single `publishingInterval` per
  `_poll.Subscribe(...)` call. Add an optional `ScanRate` field to `AbCipTagDefinition` that,
  when set, overrides the subscription interval for that tag. The shared `PollGroupEngine`
  already buckets by interval — the change is to read the per-tag rate at subscribe-time
  and place the tag into its own bucket.
- **Files**: `AbCipDriverOptions.cs` (record field), `AbCipDriver.SubscribeAsync` (look up
  per-tag override before passing to `_poll.Subscribe`). `PollGroupEngine` may need a new
  `Subscribe(tags, defaultInterval, perTagOverrides)` overload — check Core for the current
  signature.
- **Test approach**: unit test that two tags with different ScanRate values produce two
  poll buckets; integration test verifying the faster-rate tag publishes more frequently
  than the slower-rate tag inside one subscription.
- **Effort**: M
- **Dependencies**: may require a small change to `PollGroupEngine` in Core.
- **Docs / fixture / e2e**: new doc `docs/drivers/AbCip-Operability.md` (consolidates the
  Phase 4 knobs); appends a "Per-tag scan rate" section to it covering Kepware "scan
  classes" parity + the OPC UA publishing-interval interaction; no CLI surface change;
  fixture-side no change to ab_server; adds
  `tests/.../IntegrationTests/AbCipPerTagScanRateTests.cs` driving two tags at
  different rates against ab_server and asserting bucket separation; extends
  `scripts/e2e/test-abcip.ps1` with a two-tag subscribe-rate-divergence assertion.

#### PR 4.2 — Write deadband / write-on-change
- **Scope**: `AbCipDriver.WriteAsync` writes every request through. Add per-tag
  `WriteDeadband` (numeric) and `WriteOnChange` (boolean). When set, the driver tracks the
  last successfully-written value per `(tag, deviceHostAddress)` and suppresses the next
  write if `|new - last| < deadband` (numeric) or `new == last` (any). Suppressed writes
  return `Good` so OPC UA semantics are unaffected.
- **Files**: `AbCipDriverOptions.cs` (record fields), new `AbCipWriteCoalescer.cs` holding
  the per-tag last-value cache, `AbCipDriver.WriteAsync` consults the coalescer before
  hitting the runtime.
- **Test approach**: unit tests with synthetic writes — assert that a sequence of jittery
  setpoint values within deadband triggers a single PLC write.
- **Effort**: M
- **Dependencies**: none.
- **Docs / fixture / e2e**: appends a "Write deadband / write-on-change" section to
  `docs/drivers/AbCip-Operability.md` with a worked setpoint-jitter example; updates
  `docs/drivers/AbServer-Test-Fixture.md` §7 to flip the multi-write coverage line to
  also cover suppression; adds
  `tests/.../IntegrationTests/AbCipWriteDeadbandTests.cs` driving a jittery setpoint and
  asserting the actual PLC write count via libplctag debug-trace; extends
  `scripts/e2e/test-abcip.ps1` with a write-coalesce assertion (write the same value
  twice, verify only one PLC-side change).

#### PR 4.3 — Diagnostic / system tags as browseable variables
- **Scope**: surface the `IHostConnectivityProbe` + `DriverHealth` data as browseable OPC UA
  variables under `AbCip/<device>/_System/`. Variables: `_ConnectionStatus`, `_ScanRate`
  (current effective publishing interval), `_TagCount`, `_DeviceError`, `_LastScanTimeMs`.
  Read-only; updated on each driver health transition.
- **Files**: `AbCipDriver.DiscoverAsync` (`AbCipDriver.cs:674-758`) emits the system folder
  per device; new `AbCipSystemTagSource.cs` produces the live values; `ReadAsync` routes
  `_System/...` references to the source instead of the libplctag runtime.
- **Test approach**: unit test that the discovery emits the expected nodes; unit test that
  reading a system tag returns the current health snapshot.
- **Effort**: M
- **Dependencies**: none, but PR 2.5 (online refresh trigger) becomes nicer once this lands —
  `_RefreshTagDb` writes `1` to invoke `RebrowseAsync`.
- **Docs / fixture / e2e**: appends a "System tags / `_System` folder" section to
  `docs/drivers/AbCip-Operability.md` enumerating `_ConnectionStatus`, `_ScanRate`,
  `_TagCount`, `_DeviceError`, `_LastScanTimeMs`; cross-link from
  `docs/Driver.AbCip.Cli.md` (the `read` cookbook gains a system-tag example); updates
  `docs/drivers/AbServer-Test-Fixture.md` §7 to flip `IHostConnectivityProbe` state-
  transition coverage from "no" to covered (system tag observation provides the assertion
  hook); adds `tests/.../IntegrationTests/AbCipSystemTagDiscoveryTests.cs`; extends
  `scripts/e2e/test-abcip.ps1` with a `_System/_ConnectionStatus` browse-and-read step.

#### PR 4.4 — Online tag-DB refresh trigger as `_RefreshTagDb` system tag
- **Scope**: thin follow-up to PR 2.5 + PR 4.3 — wire the writeable system tag to the
  existing `RebrowseAsync` method.
- **Files**: `AbCipSystemTagSource.cs` (writeable variable), `AbCipDriver.WriteAsync`
  intercepts `_RefreshTagDb` writes and dispatches to `RebrowseAsync`.
- **Test approach**: unit + CLI integration.
- **Effort**: S
- **Dependencies**: PR 2.5 and PR 4.3.
- **Docs / fixture / e2e**: extends the `_System` table in
  `docs/drivers/AbCip-Operability.md` to mark `_RefreshTagDb` as writeable; appends a
  "Refreshing the tag DB" recipe to `docs/Driver.AbCip.Cli.md` that pairs the system-tag
  write with the existing `rebrowse` command from PR 2.5; reuses the
  `AbCipRebrowseTests` fixture from PR 2.5 with an added system-tag-write entry point;
  extends `scripts/e2e/test-abcip.ps1` with a `_RefreshTagDb` write-then-verify
  assertion (chained off the rebrowse step from PR 2.5).

### Phase 5 — Redundancy (2 PRs)

Goal: HSBY paired-IP failover for continuous-process plants. Heavier than the rest because
it changes the `(device, hostName)` axiom — one logical device now has two host addresses.

#### PR 5.1 — Paired host address syntax + role probing
- **Scope**: extend `AbCipDeviceOptions` with `PartnerHostAddress` (optional). When set, the
  device probes both gateways concurrently using the existing probe loop machinery
  (`AbCipDriver.cs:235-281`). A ControlLogix HSBY pair exposes
  `WallClockTime`/`Module.Status` tags that identify the active chassis — investigate the
  exact tag name; `WallClockTime.SyncStatus` is one option, `S:34` (Module Status)
  carries the role bit on some versions.
- **Files**: `AbCipDriverOptions.cs` (extend `AbCipDeviceOptions`), `AbCipDriver.cs`
  (extend `DeviceState` with `ActiveAddress` field, run two probe loops), new
  `AbCipHsbyRoleProber.cs` reading the role tag and returning Active/Standby.
- **Test approach**: unit test with two fake probe runtimes returning different role bits;
  integration test deferred until a true HSBY pair is available — note in
  `MEMORY.md/project_aveva_platform_installed.md` that the dev box has a single chassis.
- **Effort**: L
- **Dependencies**: investigate the canonical HSBY role tag — the AVEVA ABCIP docs name it
  but the wire-level tag varies by firmware.
- **Docs / fixture / e2e**: new doc `docs/drivers/AbCip-HSBY.md` covering the paired-IP
  config, the role-tag detection matrix (v20 / v24 / v32+), and the feature-flag gate
  (`Redundancy.Hsby.Enabled`); extends `docs/Driver.AbCip.Cli.md` with a `--partner`
  flag plus an `hsby-status` command that prints the active partner; updates
  `docs/drivers/AbServer-Test-Fixture.md` §"What it does NOT cover" with a new entry
  marking HSBY as ab_server-blocked but adds a "paired-fixture" mode to
  `tests/.../Docker/docker-compose.yml` (two `controllogix` services on different
  ports + a `hsby-mux` sidecar that flips the role bit on demand); adds
  `tests/.../IntegrationTests/AbCipHsbyRoleProberTests.cs`; no
  `scripts/e2e/test-abcip.ps1` change yet — HSBY e2e is gated behind a sibling
  `scripts/e2e/test-abcip-hsby.ps1` script introduced in PR 5.2.

#### PR 5.2 — Failover routing in IPerCallHostResolver
- **Scope**: `AbCipDriver.ResolveHost` returns the device's primary address today
  (`AbCipDriver.cs:307-312`). Change it to return the currently-Active partner. On role
  transition, the existing bulkhead/breaker per-host keying isolates a stuck primary
  without affecting the failover path because the partner address has its own breaker.
- **Files**: `AbCipDriver.cs:ResolveHost` consults `DeviceState.ActiveAddress`, plus a
  small change to per-tag runtime caching so handles are keyed on the active address —
  failover invalidates the handle cache and re-creates against the new gateway.
- **Test approach**: unit test that toggling the role flag flips `ResolveHost` output;
  integration test deferred per PR 5.1.
- **Effort**: M
- **Dependencies**: PR 5.1.
- **Docs / fixture / e2e**: appends a "Failover behaviour" section to
  `docs/drivers/AbCip-HSBY.md` documenting handle-cache invalidation + bulkhead key
  semantics; appends a "Failure-mode walkthrough" to the same doc covering
  primary-stuck / secondary-stuck / both-stuck cases; reuses the paired-fixture from
  PR 5.1; adds `tests/.../IntegrationTests/AbCipHsbyFailoverTests.cs` driving the
  role-flip via the `hsby-mux` sidecar and asserting reads route to the new active
  partner; ships the new `scripts/e2e/test-abcip-hsby.ps1` (paired-fixture variant of
  the standard e2e — flips the role mid-stream and asserts subscribe stream survives).

## Per-PR detail

The summary above already includes each PR's title, motivation (linked to the
featuregaps.md table row), files, test plan, and effort. To keep this section from
duplicating, here are the cross-cutting design notes and risks per phase rather than per PR.

### Phase 1 risks
- **Int64 surface change** (PR 1.1) ripples through the address-space builder + the OPC UA
  variant emit. Confirm `Core.Abstractions.DriverDataType` already has `Int64`; if not, this
  PR pulls in a Core change other drivers will share (Modbus has the same TODO).
- **STRINGnn variant addressing** (PR 1.2) is the smallest data-correctness PR but has the
  highest unknown — libplctag's C# wrapper may flatten all string variants to its built-in
  `GetString(0)` helper. If true, PR 1.2 must add a raw-buffer decode path and is then
  upgraded from M to L.
- **Array-slice planner** (PR 1.3) introduces a third planner alongside the UDT planner +
  the future write planner (1.4). Build them on a shared `IAbCipReadPlanner` seam so
  Phase 3's strategy selector has one slot to pivot on, not three.
- **Multi-write packing** (PR 1.4) hinges on libplctag exposing CIP Multi-Service Packet
  construction. If it does not, the work-around is a raw-CIP `@raw` send, which is a
  bigger lift and may push 1.4 to an L-plus that drags into Phase 3.

### Phase 2 risks
- **L5K text format** has documented edge cases (escape sequences in DESCRIPTION strings,
  alias resolution, nested DATATYPE blocks). Lean on Rockwell's published L5K BNF and treat
  unknown sections as warnings, not failures.
- **L5X namespace handling** — Studio 5000 v32+ adds optional XML namespaces. Use
  XPath with prefix-agnostic queries to avoid version-pinning the parser.
- **CSV column drift** — Kepware's column order has shifted over major versions. Implement
  the importer to read by header name, not column index.

### Phase 3 risks
- **Logical addressing bootstrap cost** (PR 3.2) — symbol-table walk on first read can
  stall the first poll batch. Cache the instance-ID map per `(device, last symbol-table
  hash)` and persist it across `ReinitializeAsync` if feasible.
- **MultiPacket vs WholeUdt heuristic** (PR 3.3) — the threshold (e.g. "switch to
  MultiPacket when fewer than 30% of UDT members are subscribed") needs benchmarking on
  real rigs. Ship an explicit per-device override + pick a conservative default.
- **Connection Size on legacy firmware** (PR 3.1) — v19-and-earlier ControlLogix firmware
  rejects Large Forward Open silently. Document the symptom in `docs/Driver.AbCip.md` and
  emit a warning when ConnectionSize > 511 against a family profile that is
  ControlLogix-typed but probed-as-v19.

### Phase 4 risks
- **Per-tag scan rate** (PR 4.1) interacts with the OPC UA subscription's
  publishing-interval contract. Document that the per-tag override is a *driver-side*
  publish bucket that fires `OnDataChange` events at the per-tag rate; the OPC UA layer
  still aggregates them on its own publishing-interval and the client may see them at the
  larger of the two intervals. This matches Kepware's "scan classes" semantics.
- **Write deadband** (PR 4.2) on UDT-fanned-out members must use the member-level cache, not
  the parent UDT's cache.

### Phase 5 risks
- **HSBY role tag name** (PR 5.1) varies by firmware version; without a real HSBY pair on
  the dev box the integration coverage is deferred to a customer-site smoke test. Consider
  parking PR 5.1+5.2 behind a feature flag (`Redundancy.Hsby.Enabled`) and shipping unit
  coverage only.
- **Bulkhead key** assumed to be `(driver, hostName)`; once `ResolveHost` returns the active
  partner address that key is correct by construction, but verify Polly's per-key state is
  invalidated cleanly when the active address changes mid-call.

## Documentation, fixture, and e2e impact

Cross-cutting roll-up of the per-PR `Docs / fixture / e2e` lines above. Read this before
starting any phase to plan doc + fixture + e2e work in parallel with the code change.

### New documents

- `docs/drivers/AbCip-TagImport.md` (Phase 2, lands with PR 2.1; extended by PR 2.2,
  PR 2.3, PR 2.4, PR 2.6) — L5K / L5X / CSV / AOI tag-import reference.
- `docs/drivers/AbCip-Performance.md` (Phase 3, lands with PR 3.1; extended by PR 3.2,
  PR 3.3) — Connection Size, Addressing Mode, Read Strategy.
- `docs/drivers/AbCip-Operability.md` (Phase 4, lands with PR 4.1; extended by PR 4.2,
  PR 4.3, PR 4.4) — per-tag scan rate, write deadband, system tags.
- `docs/drivers/AbCip-HSBY.md` (Phase 5, lands with PR 5.1; extended by PR 5.2) —
  paired-IP redundancy, role-tag matrix, failover semantics.

### Documents with appended sections

- `docs/Driver.AbCip.Cli.md` — gains type-table rows (PR 1.1), `--string-size` flag
  (PR 1.2), slice syntax (PR 1.3), multi-write subsection (PR 1.4), `tag-import` /
  `tag-export` commands (PR 2.1, PR 2.2, PR 2.4), `rebrowse` command (PR 2.5),
  Connection Size note (PR 3.1), `--addressing-mode` flag (PR 3.2), system-tag
  read example (PR 4.3), `_RefreshTagDb` recipe (PR 4.4), `--partner` flag plus
  `hsby-status` command (PR 5.1).
- `docs/drivers/AbServer-Test-Fixture.md` — coverage map updated by every PR that
  changes what ab_server actually exercises (1.1, 1.2, 1.3, 1.4, 2.6, 3.1, 3.2,
  3.3, 4.2, 4.3, 5.1).

### Fixture / simulator scaffolding

- `tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Docker/docker-compose.yml` —
  ControlLogix profile gains seeded `TestLINT`, `TestSTRING80`, extra DINT tags for
  multi-write (PRs 1.1, 1.2, 1.4); a new paired-fixture mode with `hsby-mux` sidecar
  for HSBY (PR 5.1).
- `tests/.../AbCip.IntegrationTests/AbServerProfile.cs` — the `KnownProfiles`
  records get extended Notes lines for each new seeded tag class.
- `tests/.../AbCip.Tests/Import/Fixtures/` — new directory hosting sample L5K, L5X,
  and CSV files (PRs 2.1, 2.2, 2.6, 2.4).
- `tests/.../AbCip.IntegrationTests/Emulate/` — new gated tests for AOI (PR 2.6) and
  MultiPacket strategy (PR 3.3); reuses the existing `AB_SERVER_PROFILE=emulate`
  gate.
- `tests/.../AbCip.IntegrationTests/LogixProject/README.md` — cross-link added when
  PR 2.2 lands so the on-site Studio 5000 export doubles as a parser fixture.

### Integration / e2e scripts

- `scripts/e2e/test-abcip.ps1` — gains assertions for: LInt loopback (1.1),
  STRING round-trip (1.2), array-slice read (1.3), recipe multi-write (1.4),
  tag-import diff (2.1, 2.2, 2.4), Description survival (2.3), rebrowse-after-reseed
  (2.5), Symbolic-vs-Logical sanity (3.2), per-tag scan-rate divergence (4.1),
  write-coalesce (4.2), `_System` browse-and-read (4.3), `_RefreshTagDb` write-then-
  verify (4.4).
- `scripts/smoke/seed-abcip-smoke.sql` — extended with `TestLINT`, `TestSTRING80`,
  multi-write target tags, and a `ConnectionSize` field demo (PRs 1.1, 1.2, 1.4,
  3.1).
- `scripts/e2e/test-abcip-hsby.ps1` — new paired-fixture variant of the standard
  e2e, ships with PR 5.2; not chained into `scripts/e2e/test-all.ps1` until HSBY
  exits feature-flag gating.

### Cross-cutting work

- The `Docs / fixture / e2e` lines deliberately reuse the existing
  `Test-Probe` / `Test-DriverLoopback` / `Test-ServerBridge` / `Test-OpcUaWriteBridge` /
  `Test-SubscribeSeesChange` helpers in `scripts/e2e/_common.ps1` — no new helper
  functions are required for Phases 1-4. Phase 5 is the first phase that introduces a
  new helper (`Test-FailoverDuringSubscribe`) in `_common.ps1`, shipped alongside
  PR 5.2; if other drivers (TwinCAT, S7) later adopt a paired-fixture mode they can
  reuse it.
- `tests/.../AbCip.IntegrationTests/AbServerFixture.cs` may need a small extension in
  PR 5.1 to support the paired-port probe; the change is additive (probe both
  `127.0.0.1:44818` and `127.0.0.1:44819`), keeping single-fixture tests working
  unchanged.

## Skip-rated items (for context)

Copied from the Recommendations table at `docs/featuregaps.md`:

- **#7 Inactivity timeout / keep-alive cadence** — Rarely an issue with libplctag-managed
  connections.
- **#9 "Respect tag-specified scan rate" mode** — Niche; OPC UA subscription rate already
  covers it.
- **#10 Initial value cache / first-update from cache** — OPC UA subscription sampling
  already handles first-update.
- **#15 UDT as first-class OPC UA structured type** — Member fan-out already works;
  structured-type plumbing is heavy.
- **#17 PLC-5 / SLC bridging through CLX** — AbLegacy driver covers this protocol family.
- **#21 Unsolicited CIP MSG ingestion** — Separate driver in commercial; design-heavy;
  niche.
- **#22 CIP Generic / Class 3 passthrough** — Niche custom-tooling territory.
- **#23 Per-device connection count / pooling** — libplctag manages connections;
  premature.

## Open questions

1. **libplctag instance-ID API** (PR 3.2) — does the C# wrapper expose
   `logical_segment` / `cip_addr` attributes directly, or do we have to drop down to
   `Tag.AddAttribute` calls? Affects scope of Phase 3.
2. **libplctag CIP Multi-Service Packet** (PR 1.4) — is there a wrapper-level multi-write
   helper, or must we go through the `@raw` pseudo-tag? Affects scope of Phase 1.
3. **`DriverDataType.Int64` / `Int64Array`** (PR 1.1) — does Core already carry it, or is
   this a shared Core change with Modbus's matching TODO?
4. **HSBY role tag** (PR 5.1) — confirm the canonical Active/Standby indicator across
   ControlLogix v20 / v24 / v32+; without a known tag the role-prober is speculative.
5. **AOI InOut handling** (PR 2.6) — Kepware skips InOut parameters because they are
   pointers, not values. Do we follow the same precedent or attempt to dereference at
   read-time? Skip is the cheap default.
6. **L5K vs L5X coverage** — if the customer base has standardised on L5X (Studio 5000
   v21+), can we ship PR 2.2 first and make PR 2.1 best-effort? Affects phasing within
   Phase 2.
7. **HSBY scope for v2 vs v3** — Phase 5 carries the largest unknowns; if no continuous-
   process customer demands it for the v2 release, deferring Phase 5 to v3 is reasonable.
8. **Per-tag scan rate plumbing** (PR 4.1) — does `PollGroupEngine` in Core already accept
   per-reference interval overrides, or does that need a Core extension shared with the
   other polling-overlay drivers (Modbus, FOCAS)?