Recover stashed driver-gaps work from pre-v2-mxgw-merge working tree

Captures uncommitted work that lived in the working tree on v2-mxgw-integration but was orthogonal to the migration. Stashed during the v2-mxgw merge to master (2026-04-30) and replanted here on a feature branch off master so it's git-visible rather than living in the stash list. Two distinct buckets: 1. Tracked fixture/config refinements (10 files, ~36 lines): - scripts/e2e/test-opcuaclient.ps1 - src/ZB.MOM.WW.OtOpcUa.Admin/appsettings.json - 5 docker-compose.yml under tests/.../IntegrationTests/Docker/ (AbCip, Modbus, OpcUaClient, S7) - 4 fixture .cs files (AbServerFixture, ModbusSimulatorFixture, OpcPlcFixture, Snap7ServerFixture) 2. Untracked driver-gaps queue artifacts (~8000 lines): - docs/plans/{abcip,ablegacy,focas,opcuaclient,s7,twincat}-plan.md — per-driver gap plans - docs/featuregaps.md — cross-cutting analysis - docs/v2/focas-deployment.md, docs/v2/implementation/focas-simulator-plan.md - followup.md — auto/driver-gaps queue follow-ups - scripts/queue/ — PR-queue automation tooling (12 files including pr-manifest.yaml at 1473 lines) This commit is a snapshot for recoverability — review and split into focused PRs (or discard) before merging anywhere downstream. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-30 08:28:01 -04:00
33 changed files with 8074 additions and 14 deletions
--- a/docs/featuregaps.md
+++ b/docs/featuregaps.md
@@ -0,0 +1,623 @@
 # Driver Feature Gaps vs Commercial OPC/SCADA Gateways
 This document compares each non-Modbus, non-LMX driver in the OtOpcUa server against the feature surfaces of the dominant commercial gateways (Kepware KEPServerEX / PTC Kepware Edge, AVEVA OI Server / DAServer, Software Toolbox TOP Server, Matrikon, Unified Automation UaGateway, MTConnect-class Fanuc adapters, Beckhoff TF6100, etc.).
 The intent is to:
 - inventory what we already ship (with file:line citations into the current codebase)
 - list missing or under-served features that are table-stakes for sites replacing those commercial gateways
 - preserve the design choices that should NOT change just because a competitor does it differently
 LMX (Galaxy / MXAccess) and Modbus are tracked elsewhere and are excluded here.
 ## Drivers covered
 | Driver | Section | Implementation plan |
 |---|---|---|
 | AbCip — Allen-Bradley EtherNet/IP (ControlLogix / CompactLogix / Micro800 / GuardLogix) | [↓](#abcip-allen-bradley-ethernetip--logix) | [`plans/abcip-plan.md`](plans/abcip-plan.md) |
 | AbLegacy — Allen-Bradley PLC-5 / SLC / MicroLogix (PCCC) | [↓](#ablegacy-allen-bradley-plc-5--slc--micrologix) | [`plans/ablegacy-plan.md`](plans/ablegacy-plan.md) |
 | FOCAS — Fanuc CNC FOCAS / FOCAS2 | [↓](#focas-fanuc-cnc) | [`plans/focas-plan.md`](plans/focas-plan.md) |
 | OpcUaClient — OPC UA aggregation client | [↓](#opcuaclient-opc-ua-aggregation-client) | [`plans/opcuaclient-plan.md`](plans/opcuaclient-plan.md) |
 | S7 — Siemens S7-300 / 400 / 1200 / 1500 | [↓](#s7-siemens-s7-3004001200--1500) | [`plans/s7-plan.md`](plans/s7-plan.md) |
 | TwinCAT — Beckhoff TwinCAT 2 / 3 (ADS) | [↓](#twincat-beckhoff-ads) | [`plans/twincat-plan.md`](plans/twincat-plan.md) |
 ## How to read this document
 Every gap below is rated **[Build]** (recommended) or **[Skip]** (not recommended) inline at the start of the bullet. The same rating appears in the per-driver `### Recommendations` table with its rationale. The per-driver implementation plan in `docs/plans/` covers the **[Build]** items only.
 ---
 ## AbCip (Allen-Bradley EtherNet/IP — Logix)
 ### What we ship today
 - Per-device `ab://gateway[:port]/cip-path` host-address with multi-hop CIP path via a comma-separated string (e.g. `1,2,2,192.168.50.20,1,0`) — `src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipHostAddress.cs:23`.
 - Four PLC-family profiles (`ControlLogix`, `CompactLogix`, `Micro800`, `GuardLogix`) selecting libplctag plc attribute, ConnectionSize default (504/4002/488), default CIP path (`1,0` or empty), connected-vs-unconnected hint, request-packing flag, and MaxFragmentBytes — `src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/PlcFamilies/AbCipPlcFamilyProfile.cs:13-62`.
 - N devices per driver instance with per-device bulkhead/breaker keying — `src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipDriverOptions.cs:19`.
 - Pre-declared static tag map (`AbCipTagDefinition`) keyed by `Name`, with `TagPath`, `DataType`, `Writable`, `WriteIdempotent`, `Members`, `SafetyTag` — `AbCipDriverOptions.cs:95-103`.
 - Logix atomic types `BOOL/SINT/INT/DINT/LINT/USINT/UINT/UDINT/ULINT/REAL/LREAL/STRING/DT` plus `Structure` marker — `src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipDataType.cs:16-37`.
 - Optional online controller browse via libplctag `@tags` pseudo-tag, surfaced under a `Discovered/` sub-folder; controller- and program-scope (`Program:Main.X`) tags emitted; system/module/routine/task tags filtered — `AbCipDriver.cs:674-757`, `AbCipSystemTagFilter.cs`.
 - UDT / Predefined-Structure handling: declaration-driven member fan-out (Variable per member) plus runtime CIP Template Object (class 0x6C) decoder + per-device `(deviceHostAddress, templateInstanceId)` template cache — `CipTemplateObjectDecoder.cs`, `AbCipTemplateCache.cs`, `AbCipDriver.cs:70-103`.
 - Whole-UDT read coalescing — `AbCipUdtReadPlanner` groups members of the same parent and reads the parent once, decoding members from the buffer at computed byte offsets — `AbCipDriver.cs:323-449`, `AbCipUdtReadPlanner.cs`, `AbCipUdtMemberLayout.cs`.
 - BOOL-in-DINT addressing (`Tag.N` bit-index) with read-decode + RMW write through a per-parent `SemaphoreSlim` and cached parent-DINT runtime — `AbCipDriver.cs:494-614`, `AbCipTagPath.cs`.
 - Polling subscription overlay shared with other drivers (`PollGroupEngine`) — `AbCipDriver.cs:56-59,187-195`.
 - Per-device connectivity probe with configurable interval/timeout/probe tag (default off until tag configured) and `OnHostStatusChanged` events — `AbCipDriverOptions.cs:131-143`, `AbCipDriver.cs:235-295`.
 - ALMD alarm projection (opt-in) polling `InFaulted` + `Severity`, raising `OnAlarmEvent` on edges, with ack-write — `AbCipAlarmProjection.cs`, `AbCipDriverOptions.cs:42-58`.
 - GuardLogix safety-tag flag forces `SecurityClassification.ViewOnly` — `AbCipDriverOptions.cs:89-94`, `AbCipDriver.cs:474-478`.
 - libplctag-status → OPC UA StatusCode mapping (`BadCommunicationError`, `BadNotWritable`, `BadTypeMismatch`, `BadOutOfRange`, `BadNodeIdUnknown`) — `AbCipStatusMapper.cs`.
 - Tier-B reinit (`ReinitializeAsync`) tearing down all `IAbCipTagRuntime` handles — `AbCipDriver.cs:163-167`.
 - CLI test client: `probe`, `read`, `write`, `subscribe` against the same driver — `docs/Driver.AbCip.Cli.md`.
 ### Gaps vs commercial gateways
 - **[Build]** **Offline tag import from L5K / L5X** — present in: both (Kepware Logix Database Settings; TOP Server Auto Tag Generation). Why it matters: lets engineers stage a project against a Studio 5000 export with no PLC online, the de-facto config workflow at Rockwell shops.
 - **[Build]** **CSV tag import / export** — present in: both. Why it matters: Kepware/AVEVA users routinely round-trip tag lists through Excel; replacing them without CSV makes mass-config painful.
 - **[Build]** **Tag descriptions / engineering metadata** — present in: both (descriptions imported with L5X). Why it matters: descriptions become the OPC UA `Description`/`DisplayName`, expected by HMI/Historian engineers.
 - **[Build]** **Logical-blocking / logical-non-blocking protocol modes** — present in: both (TOP Server names them; Kepware exposes equivalent "Optimize for read" / structure-block reads). Why it matters: whole-UDT vs per-member read strategy is the single biggest performance lever; we have one-direction whole-UDT only via `AbCipUdtReadPlanner`, no structure-block read for non-grouped members.
 - **[Build]** **Symbolic vs logical (instance-ID) addressing toggle** — present in: both. Why it matters: logical addressing skips ASCII parsing on every poll, ~3-5x faster for high-tag-count rigs; libplctag supports it but we don't expose the choice.
 - **[Build]** **Configurable CIP Connection Size per device** — present in: both (Kepware 500-4000 byte slider, TOP Server "Max Packet Size"). Why it matters: we hard-code the family default (4002/504/488); no field knob to tune for switches that fragment large frames or for legacy v19 firmware that won't accept Large Forward Open.
 - **[Skip]** **Inactivity timeout / connection idle disconnect** — present in: both. Why it matters: long-idle CIP sessions get reaped silently by some firewalls; commercial drivers expose a keep-alive cadence we don't.
 - **[Build]** **Per-tag scan rate / scan group bucketing** — present in: both (Kepware "scan classes", AVEVA Topic update intervals). Why it matters: lets engineers separate fast 100ms machine-state tags from 5s recipe data; we have one publishing-interval-per-subscription with no per-tag override.
 - **[Skip]** **"Respect tag-specified scan rate" mode** — present in: Kepware. Why it matters: lets the static tag table override client-requested rate, important when an HMI subscribes too fast and overruns the PLC.
 - **[Skip]** **Initial value cache / "first updates from cache"** — present in: Kepware. Why it matters: avoids a stall while a fresh subscription waits for its first poll; common SCADA expectation.
 - **[Build]** **Multi-tag write packing (write-multi)** — present in: both. Why it matters: we serialise writes one-by-one in `AbCipDriver.WriteAsync`; without CIP multi-request packing for writes a recipe-download is N round-trips instead of one.
 - **[Build]** **AOI (Add-On Instruction) input/output handling** — present in: Kepware (with explicit InOut limitation note). Why it matters: AOIs are how modern Logix code is structured; the Template Object decoder probably handles the layout but we don't surface AOI-specific browse paths.
 - **[Build]** **Native STRING (Logix STRING / custom STRINGxx) decoding** — present in: both (Kepware preserves descriptors; AVEVA exposes as native string). Why it matters: we map Logix `STRING` to `DriverDataType.String` but `AbCipDataType.cs` flags whole-string only; no support for user-defined `STRINGnn` variants of different DATA-array sizes.
 - **[Build]** **64-bit integer surface (LINT/ULINT)** — present in: both. Why it matters: Logix v32+ exposes LINT for 64-bit counters/timestamps; we widen them into `Int32` per a TODO at `AbCipDataType.cs:53`, losing the upper bits.
 - **[Skip]** **Structure / UDT as first-class OPC UA structured type** — present in: both (Kepware emits child tags; AVEVA exposes via native UDT). Why it matters: we emit `DriverDataType.String` placeholder for whole-UDT, only members are fully typed; OPC UA clients can't bind to a UDT shape.
 - **[Build]** **Array element / array slice addressing** — present in: both (Kepware `Tag[3,5]`, slice `Tag[0..15]`). Why it matters: `AbCipTagPath` supports indexed elements but the driver has no array-slice read for adjacent indices; reading `Tag[0..99]` becomes 100 individual reads.
 - **[Skip]** **PLC-5 / SLC-500 bridging via ControlLogix gateway** — present in: both (Kepware Logix Gateway, TOP Server NET-ENI). Why it matters: thousands of legacy AB sites front a PLC-5/SLC behind a 1756-ENBT; without the bridge those plants can't migrate to us in one step.
 - **[Build]** **Hot-standby ControlLogix redundancy (paired EN2T IPs)** — present in: AVEVA (and Kepware via secondary device). Why it matters: ControlLogix HSBY pairs are standard in continuous-process plants; today our driver has one host address per device, no automatic failover to the partner chassis.
 - **[Build]** **Diagnostics / system tags (`_ConnectionStatus`, `_ScanRate`, `_TagCount`, `_DeviceError`)** — present in: both. Why it matters: SCADA dashboards bind to these for live driver health; we expose `IHostConnectivityProbe` + `DriverHealth` but not as browseable OPC UA variables.
 - **[Build]** **Tag-write deadband / write-on-change / write-coalesce** — present in: both. Why it matters: avoids hammering the PLC on jittery analogue setpoints; we write every request straight through.
 - **[Skip]** **Unsolicited messages (PLC-pushed CIP MSG)** — present in: AVEVA (DASABCIP unsolicited topic), Kepware (separate "ControlLogix Unsolicited" driver). Why it matters: event-driven alarm/recipe-complete signals from the PLC arrive with sub-100ms latency vs our 1s alarm-poll loop.
 - **[Skip]** **CIP Generic / Class 3 message passthrough** — present in: both. Why it matters: enables custom tooling (drive parameters, motion config, MSG instruction targets) for shops that have built around it.
 - **[Skip]** **Configurable per-device connection count / connection pooling** — present in: both (AVEVA: max 31). Why it matters: lets operators trade PLC CPU cost against parallelism for high-throughput rigs; we run one connection per tag handle implicitly.
 - **[Build]** **Online tag-database refresh trigger** — present in: AVEVA (`$Sys$UpdateTagInfo`). Why it matters: lets ops force re-browse after a Studio 5000 download without restarting the driver; we only re-browse on full driver reinit.
 ### Recommendations
 | # | Gap | Build? | Rationale |
 |---|-----|:------:|-----------|
 | 1 | Offline L5K / L5X import | Yes | De-facto Studio 5000 workflow; engineers won't switch without it |
 | 2 | CSV tag import / export | Yes | Common round-trip via Excel for mass config |
 | 3 | Tag descriptions / engineering metadata | Yes | Free once L5X import lands; expected as OPC UA `Description` |
 | 4 | Logical-blocking / non-blocking modes | Yes | Biggest perf lever; today only whole-UDT coalescing |
 | 5 | Symbolic vs logical (instance-ID) toggle | Yes | 3-5x perf on dense rigs; libplctag already supports it |
 | 6 | Configurable Connection Size per device | Yes | Cheap field knob for v19 firmware / fragmenting switches |
 | 7 | Inactivity timeout / keep-alive cadence | No | Rarely an issue with libplctag-managed connections |
 | 8 | Per-tag scan rate / scan groups | Yes | Standard SCADA expectation; mixed-rate tag tables |
 | 9 | "Respect tag-specified scan rate" mode | No | Niche; OPC UA subscription rate already covers it |
 | 10 | Initial value cache / first-update from cache | No | OPC UA subscription sampling already handles first-update |
 | 11 | Multi-tag write packing | Yes | Recipe-download speed; one PDU vs N |
 | 12 | AOI input / output handling | Yes | Standard modern Logix code structure |
 | 13 | Native STRING / STRINGnn decoding | Yes | Table-stakes; we passthrough as String only |
 | 14 | 64-bit LINT / ULINT fidelity | Yes | Correctness on Logix v32+; we silently truncate (TODO in code) |
 | 15 | UDT as first-class OPC UA structured type | No | Member fan-out already works; structured-type plumbing is heavy |
 | 16 | Array slice addressing `Tag[0..15]` | Yes | Perf; reads of N-element arrays in one call |
 | 17 | PLC-5 / SLC bridging through CLX | No | AbLegacy driver covers this protocol family |
 | 18 | Hot-standby ControlLogix redundancy | Yes | Continuous-process plants standardize on HSBY pairs |
 | 19 | Diagnostic system tags (`_ConnectionStatus` etc.) | Yes | HMI dashboards bind to them; cheap given DriverHealth |
 | 20 | Write deadband / write-on-change | Yes | Analog setpoints flood the PLC without it |
 | 21 | Unsolicited CIP MSG ingestion | No | Separate driver in commercial; design-heavy; niche |
 | 22 | CIP Generic / Class 3 passthrough | No | Niche custom-tooling territory |
 | 23 | Per-device connection count / pooling | No | libplctag manages connections; premature |
 | 24 | Online tag-DB refresh trigger | Yes | Cheap; avoids restart after PLC download |
 ### Notable parity (keep)
 - libplctag-class wire layer covering ControlLogix/CompactLogix/Micro800/GuardLogix on EtherNet/IP CIP — same controller coverage as the commercial drivers (minus PLC-5/SLC).
 - Multi-hop CIP path syntax with bridge-through chassis (`1,2,2,IP,1,0` form) — matches Kepware/AVEVA routing semantics.
 - Online controller browse with program-scope vs controller-scope distinction and system-tag filtering — same shape as Kepware Auto Tag Generation.
 - CIP Template Object (class 0x6C) decoder for live UDT-shape resolution + cache — feature-parity with Kepware's structure-aware Auto Tag Generation.
 - Whole-UDT read coalescing for grouped members — matches TOP Server "logical blocking" optimisation for the cases it covers.
 - BOOL-in-DINT bit-index addressing with RMW serialisation per parent — same semantics commercial drivers expose for `Tag.N` bit access.
 - Per-PLC-family Connection Size / connected-messaging / fragment-bytes profile — mirrors the per-controller "model" picker in Kepware.
 - ALMD alarm projection with edge-detected raise/clear — reasonable parity for the alarm subset of FT Alarms & Events that those drivers do not natively translate.
 - Per-device circuit-breaker / bulkhead isolation keyed on `(driver, hostName)` — better operational story than the typical commercial gateway, which trips the whole channel on one bad device.
 - GuardLogix safety-tag write rejection at config time — explicit, matches Rockwell's safety-partition rules.
 ### Sources
 - [Kepware Allen-Bradley ControlLogix Ethernet driver overview](https://support.ptc.com/help/kepware/drivers/en/kepware/drivers/CONTROLLOGIXETHERNET/Overview.html)
 - [Kepware Logix Database Settings (offline / online ATG, L5K/L5X)](https://support.ptc.com/help/kepware/drivers/en/kepware/drivers/CONTROLLOGIXETHERNET/Logix_Database_Settings.html)
 - [Kepware Preparing for Automatic Tag Database Generation](https://support.ptc.com/help/kepware/drivers/en/kepware/drivers/CONTROLLOGIXETHERNET/Preparing_for_Automatic_Tag_Database_Generation.html)
 - [Kepware Device Properties — Scan Mode (respect tag-specified, demand poll, initial cache)](https://support.ptc.com/help/kepware/drivers/en/kepware/drivers/Device_Properties_Scan_Mode.html)
 - [Kepware Allen-Bradley ControlLogix Ethernet driver manual (PDF, 2025)](https://downloads.softwaretoolbox.com/demodnld/prod_docs/topserver_help_pdf/Common/allen-bradley-controllogix-ethernet-manual.pdf)
 - [Kepware Allen-Bradley ControlLogix Server (Unsolicited)](https://www.ptc.com/en/store/kepware/drivers/allen-bradley-controllogix-unsolicited)
 - [Kepware System Tags](https://support.ptc.com/help/kepware/kepware_edge/en/kepware/kepware-edge/system-tags.html)
 - [TOP Server ControlLogix protocol modes (symbolic / logical-blocking / logical-non-blocking)](https://blog.softwaretoolbox.com/optimizing-controllogix-protocol-modes)
 - [TOP Server Rockwell ControlLogix Ethernet OPC driver details](https://softwaretoolbox.com/top-server/rockwell-ab-controllogix-ethernet)
 - [TOP Server ControlLogix Ethernet performance optimization](https://softwaretoolbox.com/top-server/rockwell-ab-controllogix-performance)
 - [Software Toolbox FAQ — making configuration choices for ControlLogix Ethernet](https://help.softwaretoolbox.com/faq/1658)
 - [AVEVA Communication Drivers Pack — ABCIP Driver user guide (PDF)](https://cdn.logic-control.com/docs/aveva/communications-pack/OIABCIP.pdf)
 - [Wonderware DASABCIP user guide (PDF)](https://cdn.logic-control.com/media/DASABCIP.pdf)
 - [Wonderware OI.ABCIP server user guide (PDF, v7.0)](https://s3-us-west-2.amazonaws.com/wonderwarepacwest/downloads/oi-abcip-user-guide.pdf)
 - [Industrial Software Solutions — DASABCIP unsolicited message handling](https://industrial-software.com/training-support/tech-notes/74-how-configure-wonderware-dasabcip-unsolicited-message-handling/)
 - [Industrial Software Solutions — `$Sys$UpdateTagInfo` with ABCIP](https://industrial-software.com/training-support/tech-notes/119-using-sysupdatetaginfo-with-abcip-oi-servers/)
 - [AVEVA — Configure the ABCIP Communication Driver](https://docs.aveva.com/bundle/sp-cdp-drivers/page/193749.html)
 ---
 ## AbLegacy (Allen-Bradley PLC-5 / SLC / MicroLogix)
 ### What we ship today
 - Per-device family knob: `Slc500` / `MicroLogix` / `Plc5` / `LogixPccc`, each mapped to a libplctag PLC attribute, default CIP path, max-tag-bytes, and string/long-file capability flags (`PlcFamilies/AbLegacyPlcFamilyProfile.cs:14-54`).
 - Single transport: PCCC encapsulated in EtherNet/IP via libplctag, with `ab://gateway[:port]/cip-path` host strings supporting CLX-bridged routing (`AbLegacyHostAddress.cs:14-52`).
 - File-letter set: `N`, `F`, `B`, `L`, `ST`, `T`, `C`, `R`, `I`, `O`, `S`, `A` parsed and validated; trailing `/N` bit index and `.SUBELEMENT` (ACC/PRE/EN/DN/TT/CU/CD/LEN/POS/ER) recognised (`AbLegacyAddress.cs:97-101`, `AbLegacyDataType.cs:9-29`).
 - Data types: `Bit`, `Int` (N/A), `Long` (L), `Float` (F), `String` (ST), `TimerElement`, `CounterElement`, `ControlElement` — all surfacing as `Boolean` / `Int32` / `Float32` / `String` driver types (`AbLegacyDataType.cs:34-44`).
 - Bit-within-N-word write path: read-modify-write against a parent-word runtime, serialised by per-parent `SemaphoreSlim` (`AbLegacyDriver.cs:353-409`).
 - Polling overlay via shared `PollGroupEngine` exposed through `ISubscribable`; per-publishing-interval grouping (`AbLegacyDriver.cs:268-276`).
 - Connectivity probe loop per device (default `S:0`, configurable interval/timeout) emitting `HostStatusChangedEventArgs` transitions (`AbLegacyDriver.cs:283-336`, `AbLegacyDriverOptions.cs:36-44`).
 - Capability surfaces: `IDriver`, `IReadable`, `IWritable`, `ITagDiscovery`, `ISubscribable`, `IHostConnectivityProbe`, `IPerCallHostResolver` — flat `AbLegacy/<host>/<tag>` browse tree built from static config (`AbLegacyDriver.cs:11-12`, `238-264`).
 - Static-config tag list only (`AbLegacyTagDefinition`); writes can be flagged `Writable=false` and `WriteIdempotent=true` (`AbLegacyDriverOptions.cs:28-34`).
 - Status mapping for libplctag error codes to OPC UA StatusCodes (`AbLegacyStatusMapper.cs`).
 ### Gaps vs commercial gateways
 - **[Skip]** **Serial DF1 transports (full-duplex, half-duplex master/slave, KF2/KF3, radio modem)** — present in: both. Why: libplctag PCCC is Ethernet-only; no COM-port path means PLC-5/SLC/ML serial deployments are unreachable.
 - **[Build]** **DH+ via 1756-DHRIO / 1784-PKTX gateway routing** — present in: both. Why: DH+ Gateway is the canonical way to reach PLC-5 nodes through a CLX rack today; we expose a CIP path but no station-number addressing or DH+ link-id concept.
 - **[Skip]** **DH-485 routing through 1761-NET-AIC / 1747-AIC** — present in: both. Why: MicroLogix 1000/1200 and SLC 5/03 multi-drop deployments need DH-485 station addressing.
 - **[Skip]** **`M0` / `M1` module file access (block-transfer / RIO data)** — present in: Kepware, AVEVA. Why: Required for any PLC-5 with RIO modules or specialty cards (motion, weigh, vision); PCCC has dedicated frames.
 - **[Build]** **`PD` (PID), `MG` (Message), `PLS` (programmable limit switch), `BT` (block transfer) function/structure files** — present in: both. Why: Standard SLC/PLC-5 file types for PID loops and message instructions; we cap at T/C/R structures only.
 - **[Skip]** **`D` (BCD) and Long-BCD types** — present in: both. Why: Some legacy SLC/PLC-5 programs store recipe / setpoint data as packed BCD; we only ship binary `Int`/`Long`.
 - **[Build]** **PLC-5 octal addressing for I/O word/bit (`I:001/17`)** — present in: both. Why: Native PLC-5 documentation and RSLogix 5 use octal; rejecting decimal-only addresses misreads real configs.
 - **[Build]** **Indirect / indexed addressing (`N7:[N7:0]`, `N[N7:0]:5`)** — present in: both. Why: Common pattern for recipe / batch lookup tables; libplctag supports it but our parser only accepts literal `<letter><file>:<word>`.
 - **[Build]** **Array reads / contiguous block addressing (`N7:0,10` or `N7:0[10]`)** — present in: both. Why: One PCCC request can pull up to ~120 words; absent array syntax forces N round-trips for 1-of-N tags and breaks block-read sizing optimisation.
 - **[Build]** **String-file (`ST`) read/write path in production** — present in: both. Why: Type is enum-listed but `AbLegacyDataTypeExtensions.ToDriverDataType` maps to `String` only; ST is an 82-byte fixed buffer with a length word and we have no integration coverage to confirm round-trip.
 - **[Build]** **Sub-element predefined symbol coverage (timer `.PRE/.ACC/.EN/.TT/.DN`, counter `.CU/.CD/.OV/.UN`, control `.LEN/.POS/.ER/.UL/.IN/.FD`)** — present in: both. Why: Parser admits any all-letters sub-element but the `TimerElement/CounterElement/ControlElement` types collapse to a single `Int32`, losing per-bit Boolean semantics that HMIs expect (`.DN` should be Bit, not Int32).
 - **[Skip]** **Block read-size negotiation per family** — present in: both. Why: We carry `MaxTagBytes` as a constant but never plumb it into a request optimiser; libplctag's PCCC chunking is implicit and not tunable per-tag-group.
 - **[Build]** **Auto-demote on comm failure** — present in: both. Why: Kepware/TOP Server temporarily off-scan a non-responsive device for N seconds so other devices on the channel keep flowing; we only switch a `HostState` flag and keep retrying.
 - **[Skip]** **Communication serialisation across multiple devices on one channel** — present in: both. Why: DH+/DF1 networks share a single physical link; we have no channel concept, so a slow PLC-5 can starve a fast SLC on the same DH+ link.
 - **[Build]** **RSLogix 500 (`.RSS`) / RSLogix 5 (`.RSP`) / `.SLC` symbol & data-table import for automatic tag generation** — present in: both (DF1, AB Ethernet drivers). Why: Manual `AbLegacyTagDefinition` entries scale poorly; commercial tools parse RSLogix exports to seed tags and descriptions.
 - **[Skip]** **Online browse / data-table discovery from the controller** — present in: Kepware (Create-from-Device). Why: PCCC has a "read file directory" frame; we don't issue it, so `DiscoverAsync` only ever returns the static config.
 - **[Skip]** **DF1 error checking selection (BCC vs CRC-16)** — present in: both. Why: Some serial gear (older modems) only does BCC; not applicable until serial transport ships, but flagged for parity.
 - **[Build]** **Per-tag deadband / change filter on subscriptions** — present in: both. Why: Polling overlay publishes every poll; commercial drivers suppress no-op publishes by absolute-deadband or scaling.
 - **[Skip]** **PLC-5 typed-write / typed-read selection vs SLC protected typed reads** — present in: both. Why: Kepware exposes "Optimization Method" and "Force Logical=Yes" knobs that materially affect performance on slower processors; we use libplctag defaults silently.
 - **[Build]** **Diagnostic counters (request count, response time, retries, last-error per device, comm-failures)** — present in: both (built-in `_System` / `_DiagnosticTags`). Why: We surface a `DriverHealth` enum but no per-device tag-level diagnostics for an HMI to bind to.
 - **[Build]** **Per-device timeout / retry overrides** — present in: both. Why: We have one driver-wide `Timeout` (`AbLegacyDriverOptions.cs:16`) and one probe timeout; SLC 5/01 vs SLC 5/05 vs MicroLogix 1100 need very different values on a shared driver.
 - **[Skip]** **Write completion semantics — synchronous-confirmation vs queued** — present in: both. Why: Commercial drivers offer "write optimization (latest value only / write-through / disable)"; ours always writes through, which floods slow channels with redundant writes.
 - **[Build]** **MicroLogix-specific item naming (e.g. `RTC:0.HR`, `HSC:0`, `DLS:0` for daylight savings)** — present in: both. Why: MicroLogix 1100/1400 have proprietary function files that don't share file letters with SLC and our `IsKnownFileLetter` whitelist rejects them.
 ### Recommendations
 | # | Gap | Build? | Rationale |
 |---|-----|:------:|-----------|
 | 1 | Serial DF1 transports | No | Declining install base; libplctag has no serial path; major scope |
 | 2 | DH+ via 1756-DHRIO bridging | Yes | Real-world PLC-5 path; libplctag CIP routing already supports it |
 | 3 | DH-485 routing (1761/1747-AIC) | No | Very legacy; rare in greenfield |
 | 4 | M0 / M1 module file access | No | Niche RIO modules; declining |
 | 5 | PD / MG / PLS / BT files | Yes | PID files are common in real SLC programs |
 | 6 | D (BCD) and Long-BCD types | No | Very legacy data convention |
 | 7 | PLC-5 octal addressing | Yes | Correctness for actual PLC-5 sites |
 | 8 | Indirect / indexed addressing | Yes | Standard recipe / lookup pattern |
 | 9 | Array contiguous block addressing | Yes | Big perf gain; one PCCC frame vs N |
 | 10 | ST string read / write production verification | Yes | Type is enum-listed but untested; cheap to validate |
 | 11 | Sub-element bit semantics (`.DN` as Bit, etc.) | Yes | Correctness; HMIs expect Boolean for `.DN`/`.EN`/`.TT` |
 | 12 | Block read-size negotiation per family | No | libplctag handles chunking implicitly |
 | 13 | Auto-demote on comm failure | Yes | Standard SCADA resilience; one slow PLC starves fast ones |
 | 14 | Channel-shared comm serialisation | No | Only matters for serial / DH+ (transport not built) |
 | 15 | RSLogix 500/5 (.RSS / .RSP) symbol import | Yes | Workflow parity; manual config doesn't scale |
 | 16 | Online controller browse / data-table discovery | No | PCCC dir frame limited; libplctag support unclear |
 | 17 | DF1 BCC vs CRC-16 selection | No | Predicated on DF1 transport (gap #1) |
 | 18 | Per-tag deadband / change filter | Yes | Polling overlay floods every poll without it |
 | 19 | PLC-5 typed-read selection / Force Logical | No | libplctag defaults are sound; niche tuning |
 | 20 | Diagnostic counters as tags | Yes | HMI binding; cheap given existing health probe |
 | 21 | Per-device timeout / retry overrides | Yes | SLC 5/01 vs 5/05 vs ML1100 differ; cheap |
 | 22 | Write completion semantics options | No | Niche tuning; current write-through is safe default |
 | 23 | MicroLogix function-file naming (RTC/HSC/DLS) | Yes | Correctness for ML1100/1400 deployments |
 ### Notable parity (keep)
 - Family enum + per-family profile keeps SLC 500 / MicroLogix / PLC-5 / LogixPccc-mode behavioural differences explicit instead of probed at runtime (`PlcFamilies/AbLegacyPlcFamilyProfile.cs:14-54`).
 - ControlLogix-bridged routing string (`ab://gw/1,0`) matches Kepware's "Routing Path" concept and is how real PLC-5 deployments are reached today (`AbLegacyHostAddress.cs:14-52`).
 - Bit-within-N-word RMW with per-parent serialisation prevents the classic two-writer-tear bug other drivers ship (`AbLegacyDriver.cs:353-384`).
 - Probe loop with explicit `HostState` transitions gives a cleaner diagnostic surface than Kepware's lump-sum auto-demote (`AbLegacyDriver.cs:283-336`).
 - Status-file probe (`S:0`) is the same heartbeat Rockwell HMIs traditionally use, and it's family-agnostic (`AbLegacyDriverOptions.cs:43`).
 - libplctag back-end inherits ongoing community fixes for PCCC frame edge-cases without us owning the wire decoder.
 ### Sources
 - [Kepware Allen-Bradley Ethernet Driver Manual (PDF)](https://cdn.logic-control.com/docs/kepware/Manuals/Drivers/Allen-Bradley/Allen-Bradley%20Ethernet%20Driver.pdf)
 - [Kepware Allen-Bradley DF1 Driver Manual (PDF)](https://cdn.logic-control.com/docs/kepware/Manuals/Drivers/Allen-Bradley/Allen-Bradley%20DF1%20Driver.pdf)
 - [Kepware Allen-Bradley ControlLogix Ethernet Driver Manual (PDF, 2025)](https://downloads.softwaretoolbox.com/demodnld/prod_docs/topserver_help_pdf/Common/allen-bradley-controllogix-ethernet-manual.pdf)
 - [Kepware Allen-Bradley ControlLogix Driver Manual (PDF, 2017)](https://ftp.softwaretoolbox.com/demodnld/prod_docs/topserver_help_pdf/v5_20/controllogix_ethernet.pdf)
 - [Kepware Allen-Bradley Ethernet driver product page](https://www.kepware.com/en-us/products/kepserverex/drivers/allen-bradley-ethernet/)
 - [TOP Server Rockwell DF1 Serial driver](https://softwaretoolbox.com/top-server/rockwell-ab-df1)
 - [AVEVA Communication Drivers Pack 2023 R2 readme](https://www.wmkit.com/archives/aveva-communication-drivers-pack-2023-r2-readme.html)
 - [AVEVA Communication Drivers Pack 2020 R2 readme](https://industrial-software.com/wp-content/uploads/Communication_Drivers/oi-communication-drivers-pack-2020-r2/Readme.html)
 - [AVEVA Communication Drivers datasheet (PDF)](https://www.aveva.com/content/dam/aveva/documents/datasheets/Datasheet_AVEVA-CommunicationDrivers_11-19.pdf)
 - [AVEVA OI ABCIP user guide (PDF)](https://s3-us-west-2.amazonaws.com/wonderwarepacwest/downloads/oi-abcip-user-guide.pdf)
 - [Kepware Logix Database Settings (Create-from-Device / .L5K import)](https://support.ptc.com/help/kepware/drivers/en/kepware/drivers/CONTROLLOGIXETHERNET/Logix_Database_Settings.html)
 - [Rockwell DF1 Protocol and Command Set reference (1770-RM516, PDF)](https://literature.rockwellautomation.com/idc/groups/literature/documents/rm/1770-rm516_-en-p.pdf)
 ---
 ## FOCAS (Fanuc CNC)
 ### What we ship today
 - TCP-only Ethernet transport on port 8193 via the pure-managed `Focas.Wire` client; no Fwlib DLL, no P/Invoke, no out-of-process Tier-C host (`docs/drivers/FOCAS.md:8-13`, retired Host noted at `:25-27`).
 - One driver instance can host N CNCs, each keyed by `focas://{ip}[:{port}]` (`FocasDriverOptions.cs:10`, `FocasDeviceOptions:92-95`).
 - Per-device CNC series declaration (`Zero_i_D/F/MF/TF`, `Sixteen_i`, `Thirty_i`, `ThirtyOne_i`, `ThirtyTwo_i`, `PowerMotion_i`, `Unknown`) with init-time capability matrix validating macro / parameter / PMC ranges per series (`FocasCncSeries.cs:21-47`, `FocasCapabilityMatrix.cs:29-138`).
 - User-authored tag addressing for: PMC bits/bytes (`X0.0`, `R100`, `R100.3`), CNC parameters (`PARAM:1815/0`), and macro variables (`MACRO:500`) — wired through `cnc_rdpmcrng` / `cnc_rdparam` / `cnc_rdmacro` (`docs/drivers/FOCAS.md:62-66, 90`).
 - Atomic data types: Bit, Byte, Int16, Int32, Float32, Float64, String (`FocasDataType.cs:10-26`).
 - Read-only by design — `WriteAsync` returns `BadNotWritable`; no `cnc_wrparam` / `pmc_wrpmcrng` / `cnc_wrmacro` paths exist (`FocasDriver.cs:222-279`, `docs/drivers/FOCAS.md:17-18, 91`).
 - Optional `FixedTree` auto-populated subtree per device (`FocasFixedTreeOptions:26-51`) populated at bootstrap from `cnc_sysinfo` + `cnc_rdaxisname` + `cnc_rdspdlname`, polled at three cadences (axis 250 ms, program 1 s, timer 30 s):
  - `Identity/` — `SeriesNumber`, `Version`, `MaxAxes`, `CncType`, `MtType`, `AxisCount` (`FocasDriver.cs:299-304`).
  - `Axes/{name}/` — `AbsolutePosition`, `MachinePosition`, `RelativePosition`, `DistanceToGo`, `ServoLoad` (cap-gated) (`FocasDriver.cs:307-316`).
  - `Axes/FeedRate/Actual`, `Axes/SpindleSpeed/Actual` (single-channel rates — first axis only, `FocasDriver.cs:317-318`, `:646-651`).
  - `Spindle/{name}/Load`, `Spindle/{name}/MaxRpm` (cap-gated, multi-spindle aware) (`FocasDriver.cs:323-336`).
  - `Program/Name`, `ONumber`, `Number`, `MainNumber`, `Sequence`, `BlockCount` (`FocasDriver.cs:339-347`).
  - `OperationMode/Mode` + `ModeText` ("MDI"/"AUTO"/"EDIT"/"HANDLE"/"JOG"/"TEACH_IN_HANDLE"/"REFERENCE"/"REMOTE"/"TEST"/"TJOG") (`IFocasClient.cs:213-226`).
  - `Timers/PowerOnSeconds`, `OperatingSeconds`, `CuttingSeconds`, `CycleSeconds` (`FocasDriver.cs:355-362`).
 - Per-series node suppression: optional API probes at bootstrap, `EW_FUNC` / `EW_NOOPT` / `EW_VERSION` causes the corresponding subtree to not be emitted (`docs/drivers/FOCAS.md:134-142`, `FocasDriver.cs:497-526`).
 - Active-alarm projection via `IAlarmSource` (opt-in, polls `cnc_rdalmmsg2` at 2 s default), differential raise/clear with mapped alarm types `Parameter / PulseCode / Overtravel / Overheat / Servo / DataIo / MemoryCheck / MacroAlarm`, severity buckets, and ack as no-op (`FocasAlarmProjectionOptions:79-85`, `IFocasClient.cs:275-287`, `docs/drivers/FOCAS.md:154-181`).
 - Connectivity probe via `cnc_rdcncstat` on configurable interval; transitions fire `OnHostStatusChanged` (`FocasProbeOptions:110-115`, `docs/drivers/FOCAS.md:94`).
 - Optional proactive handle-recycle loop to release FWLIB session handles on a cadence (defends against the documented handle-leak bugs and finite ~5–10 connection pool) (`FocasHandleRecycleOptions:68-72`, `docs/drivers/FOCAS.md:184-205`).
 - Subscriptions are emulated via the shared `PollGroupEngine` (FOCAS has no push) (`FocasDriver.cs:451-461`).
 - `IPerCallHostResolver` so each tag's reads route to its declared device, enabling per-host bulkhead resilience (decision #144) (`FocasDriver.cs:850-857`, `FocasDriverOptions.cs:3-7`).
 ### Gaps vs commercial gateways / MTConnect adapters
 - **[Build]** **Writes (parameters / PMC / macro)** — Kepware "Fanuc Focas HSSB and Ethernet Driver", Ignition Fanuc, Memex Merlin, Predator MDC. Why: Macro / PMC writes are the canonical mechanism for DPRNT-free supervisory feedback to ladder logic; we explicitly return `BadNotWritable`.
 - **[Skip]** **HSSB (high-speed serial bus) transport** — Kepware, MTConnect Fanuc Adapter (Cincinnati), Memex. Why: HSSB is the only path on machines with no FOCAS Ethernet option licensed; we are TCP:8193 only, no `hssb` discovery, no PCI handle.
 - **[Build]** **FOCAS password / unlock parameter** — Kepware ("Password" property), MTConnect adapter. Why: Some controllers gate `cnc_wrparam` and certain reads behind a connection-level password; we have no such property in `FocasDeviceOptions`.
 - **[Build]** **Multi-path / multi-channel CNC support** — Kepware (Path number 1..n), MTConnect (per-path Components). Why: 30i/31i/32i can host 2-10 paths each with their own program / position / mode; our `cnc_setpath`-equivalent never runs and the fixed tree implicitly assumes path 1.
 - **[Skip]** **Series 15, Series 15i, Power Mate D/H, Series 35i** — Kepware lists 15/15i, MTConnect adapter handles legacy. Why: Our `FocasCncSeries` enum stops at Power Motion i + 16i; legacy Series 15 deployments would either fail validation or be forced to `Unknown`.
 - **[Build]** **`cnc_getfigure` decimal scaling** — Kepware, MTConnect, Memex. Why: Position values are exposed as raw scaled ints (Float64-typed) and we punt the divide-by-10^N onto the client; commercial gateways present pre-scaled millimeters/inches. (Acknowledged TODO in `docs/drivers/FOCAS.md:144-148`.)
 - **[Build]** **G-code / modal info (`cnc_modal`)** — Kepware ModalCodes group, MTConnect (FunctionalMode, MotionMode, PlaneCode, etc.), Ignition. Why: Modal G/M-code state (G54 active, G90/91, G17/18/19, M03/04/05, S/F overrides) is one of the most-asked CNC tag groups; we have neither a fixed-tree exposure nor a `MODAL:` address scheme.
 - **[Build]** **Tool number, current tool, tool life management** — Kepware (T-code, ToolLife group), MTConnect (`ToolNumber`, `ToolGroup`), Memex, Predator MDC. Why: Live `cnc_rdtlife*` / current T-code are core MES integration data; absent.
 - **[Skip]** **Tool offset table read/write (`cnc_rdtofs` / `cnc_wrtofs`)** — Kepware, Ignition. Why: Tool length / wear / radius compensation tables are often supervisory-edited; we have no `TOFS:` address scheme.
 - **[Build]** **Work coordinate offsets (G54..G59 + extended via `cnc_rdzofs` / `cnc_wrzofs`)** — Kepware "WorkOffsets" group, MTConnect (`PartCount` and `WorkCoordinate`). Why: Setup automation needs to read/poke work offsets; absent.
 - **[Build]** **Override values (Feedrate %, Rapid %, Spindle %, Jog %)** — Kepware OverrideGroup, MTConnect (`PathFeedrateOverride`, `RotaryVelocityOverride`). Why: Operator-modulated speeds are crucial for OEE/MES; not in the dynamic snapshot.
 - **[Build]** **Status / running flags surfaced as nodes (Auto, Run, Motion, Mstb, EmergencyStop, Edit, Tmmode, Alarm bool)** — MTConnect adapter exposes `Execution`, `ControllerMode`, `EmergencyStop` directly. Why: We poll `cnc_rdcncstat` only as a Boolean probe; the 9-field ODBST struct (tmmode/aut/run/motion/mstb/emergency/alarm/edit) is never projected to nodes.
 - **[Build]** **Parts count / required parts (`cnc_rdparam` 6711/6712/6713)** — Kepware "PartCount", MTConnect `PartCountAct/Min/Max`. Why: Part counters are MES bread-and-butter; reachable today only by user-authored `PARAM:6711` tag, not in the fixed tree.
 - **[Build]** **Diagnostic numbers (`cnc_rddiag` / `cnc_rddiagdgn`)** — Kepware Diagnostic group, MTConnect. Why: Servo/spindle diagnostics (axis position errors, current, temperature) are essential for predictive maintenance; no `DIAG:` address scheme.
 - **[Build]** **PMC data ranges (D/T/C/K/F/G addresses) for Series 16i** — partially limited by our matrix (`PmcLetters(Sixteen_i)` only allows X/Y/R/D, `FocasCapabilityMatrix.cs:80`). Why: Real 16i ladders use F/G signals for handshakes; users would have to set Series=Unknown to bypass validation.
 - **[Build]** **Bulk PMC range read (`pmc_rdpmcrng` multi-byte)** — Kepware coalesces consecutive PMC bytes; we issue one request per tag. Why: One TCP RTT per PMC byte at scale will saturate; commercial drivers batch into ranges of up to 1KB.
 - **[Build]** **Alarm history (`cnc_rdalmhistry` / `cnc_rdalmhistry5`)** — MTConnect adapter, Memex. Why: Acked alarms persist in a CNC ring buffer; we surface only the active alarm list.
 - **[Build]** **External operator messages (`cnc_rdopmsg` / `cnc_rdopmsg2` / `cnc_rdopmsg3`)** — Kepware OpMessage tag, MTConnect (`Message` data item). Why: Macro programmers display operator messages via #3006 / G65 P9099 etc.; not exposed.
 - **[Skip]** **Program list / upload / download / delete (`cnc_rdprogdir` / `cnc_upstart` / `cnc_dnstart` family)** — Kepware program-management group, Predator MDC, Memex Merlin. Why: DNC drip-feed is a primary use case for MDC products; entirely absent.
 - **[Build]** **Currently-executing program text (`cnc_rdactpt` / `cnc_rdexecprog`)** — Kepware "CurrentProgram", MTConnect `Block` and `Line`. Why: Live block display / current sequence content; we expose `Sequence` (number) but not the block text.
 - **[Skip]** **DPRNT / external data input (`cnc_rdmacrohk` / external macro)** — Predator MDC, Forcam, Memex (DPRNT collector). Why: DPRNT is the standard 1980s-vintage CNC-to-MES messaging path; we have no DPRNT TCP listener and no macro-call subscription.
 - **[Skip]** **Servo / spindle deep info (`cnc_rdsvinfo` / `cnc_rdspinfo`)** — Kepware, Memex. Why: Servo cycle counts, spindle motor speed/temp; absent (we only expose load percent).
 - **[Skip]** **Per-axis acceleration / jerk / feed-per-rev** — MTConnect (`AccelerationSpec`, `Jerk`, `Feedrate`). Why: Beyond actual feed; absent.
 - **[Build]** **Cycle time per part / last cycle time / cycle start timestamp** — MTConnect (`ProcessTimer`), Memex. Why: We expose accumulating timers but not "last completed cycle" deltas.
 - **[Skip]** **`cnc_rdrelpos` reset / preset, `cnc_setpath`, `cnc_wrabsmac`** — operator-style write commands. Why: Read-only-by-design covers it, but commercial parity assumes selective writes.
 - **[Skip]** **CNC time/date sync (`cnc_rdtimer` clock variant / `cnc_rtime`)** — Kepware, Memex. Why: Setting CNC system clock from a master time source is common in audited environments; absent.
 - **[Build]** **Connection-level statistics + retry counters surfaced as variables** — Kepware exposes per-channel stats; we publish health but not as variables.
 ### Recommendations
 | # | Gap | Build? | Rationale |
 |---|-----|:------:|-----------|
 | 1 | Writes (parameters / PMC / macro) | Yes | Key MES feedback path; current read-only is too narrow |
 | 2 | HSSB transport | No | PCI hardware; declining; reopens fwlib distribution problem |
 | 3 | FOCAS password / unlock | Yes | Cheap once writes ship; some controllers gate reads too |
 | 4 | Multi-path / multi-channel CNC | Yes | 30i/31i/32i routinely have multiple paths |
 | 5 | Series 15 / Power Mate D-H / Series 35i | No | Very legacy; small install base |
 | 6 | `cnc_getfigure` decimal scaling | Yes | Already TODO; clients shouldn't compute scaling |
 | 7 | Modal G-code / M-code state | Yes | One of the most-asked CNC tag groups |
 | 8 | Tool number / tool life management | Yes | Core MES integration data |
 | 9 | Tool offset table read / write | No | Write-heavy; defer with general write decision |
 | 10 | Work coordinate offsets (G54..) | Yes | Setup automation needs read / poke |
 | 11 | Override values (Feed / Rapid / Spindle / Jog) | Yes | OEE / MES bread-and-butter |
 | 12 | ODBST status flags as nodes | Yes | Cheap; project the 9 fields we already read |
 | 13 | Parts count in fixed tree | Yes | MES table-stakes; simple `cnc_rdparam` projection |
 | 14 | Diagnostic numbers (`cnc_rddiag`) | Yes | Predictive maintenance |
 | 15 | PMC F / G letters for 16i | Yes | Correctness; real ladders use F/G handshakes |
 | 16 | Bulk PMC range read | Yes | Big perf gain at scale |
 | 17 | Alarm history (`cnc_rdalmhistry`) | Yes | Auditing; small extension to alarm projection |
 | 18 | Operator messages (`cnc_rdopmsg*`) | Yes | Cheap; common macro feedback |
 | 19 | Program list / upload / download / delete | No | DNC product territory; significant scope |
 | 20 | Currently-executing program text | Yes | HMI displays expect block view |
 | 21 | DPRNT TCP listener | No | Significant scope; modern paths supersede it |
 | 22 | Servo / spindle deep info | No | Specialty; load% covers most needs |
 | 23 | Per-axis acceleration / jerk / feed-per-rev | No | Niche advanced telemetry |
 | 24 | Cycle time per part / last cycle delta | Yes | OEE-essential |
 | 25 | Operator write commands (preset etc.) | No | Read-only design choice; revisit only with general writes |
 | 26 | CNC time / date sync | No | Rare ask; commonly handled by CNC NTP |
 | 27 | Connection statistics as variables | Yes | Cheap given existing health |
 ### Notable parity (keep)
 - Pure-managed wire client (no Fwlib distribution problem) — significant operational win vs Kepware's HSSB driver DLL stack.
 - Per-series capability matrix at `InitializeAsync` time prevents silent runtime `BadOutOfRange` on misconfigured macro/parameter/PMC numbers.
 - Fixed-tree per-API capability probes auto-suppress nodes the CNC doesn't support — operators don't see nodes that perpetually return `BadDeviceFailure`.
 - `IPerCallHostResolver` integrates each device into the shared resilience bulkhead (Phase 6.1) — comparable to Kepware's per-device "channel" isolation.
 - Three-tier poll cadence (axis fast / program medium / timer slow) is closer to MTConnect adapter behaviour than Kepware's single-rate channel scan.
 - Handle-recycle loop is a thoughtful defence against documented Fanuc handle-leak firmware bugs — not present in many commercial drivers.
 - Alarm projection differentiates raise vs clear and maps `ALM_TYPE_*` to OPC UA severity buckets — closer to A&E semantics than the simple "alarm bit" Kepware exposes.
 ### Sources
 - https://www.kepware.com/en-us/products/kepserverex/drivers/fanuc-focas-hssb-ethernet/ — Kepware Fanuc Focas HSSB and Ethernet Driver
 - https://github.com/mtconnect/cppagent_dev/tree/main/agent/adapter/fanuc — MTConnect Fanuc adapter reference
 - https://github.com/Ladder99/focas-mock — managed Focas wire client (the OSS basis we consume)
 - https://www.inductiveautomation.com/exchange/2218 — Ignition Fanuc FOCAS driver module
 - https://memex.ca/merlin-tempus-mes-suite/ — Memex Merlin OEE / Fanuc connectivity
 - https://www.predator-software.com/cnc-data-collection.htm — Predator MDC / DNC capabilities
 - https://www.forcam.com/en/products/factory-data-collection/ — Forcam Force MES Fanuc driver
 - Fanuc FOCAS Developer Kit `fwlib32.h` (mirrored at `strangesast/fwlib`) — authoritative API surface
 - https://www.mtconnect.org/standard-2 — MTConnect Standard Part 2 Devices Information Model
 ---
 ## OpcUaClient (OPC UA Aggregation Client)
 ### What we ship today
 - **Endpoint config**: single `EndpointUrl` plus ordered `EndpointUrls` failover list with `PerEndpointConnectTimeout` per-attempt budget (`OpcUaClientDriverOptions.cs:22-40`); failover sweep tries each in order on init and on session drop (`OpcUaClientDriver.cs:95-118`).
 - **Security policies**: `None`, `Basic128Rsa15`, `Basic256`, `Basic256Sha256`, `Aes128_Sha256_RsaOaep`, `Aes256_Sha256_RsaPss` plus `Sign` / `SignAndEncrypt` modes; explicit policy+mode matching against the server's `GetEndpoints` response, no silent fallback to a weaker cipher (`OpcUaClientDriver.cs:299-336`).
 - **Identity tokens**: Anonymous, Username/Password, and X509 user-certificate (PFX with private key) — built once and reused across every failover attempt (`OpcUaClientDriver.cs:244-369`).
 - **Certificate management**: per-process PKI store rooted at `%LocalAppData%\OtOpcUa\pki` with own/trusted/issuers/rejected directories; SDK auto-creates the application instance certificate at startup; `AutoAcceptCertificates` dev knob hooks the validator's `BadCertificateUntrusted` path (`OpcUaClientDriver.cs:163-217`).
 - **Session lifecycle**: configurable `SessionTimeout`, `KeepAliveInterval`, `ReconnectPeriod`, `ApplicationUri`, `SessionName`, operation `Timeout` (`OpcUaClientDriverOptions.cs:82-112`).
 - **Reconnect**: native `Session.KeepAlive` event drives a `SessionReconnectHandler` with a 2-minute max retry period; SDK's automatic `TransferSubscriptions` migrates monitored items onto the rebuilt channel; keep-alive is rewired onto the new session post-recovery (`OpcUaClientDriver.cs:1297-1359`).
 - **Discovery**: two-pass recursive browse from `BrowseRoot` (default `ObjectsFolder`) with `MaxBrowseDepth=10` and `MaxDiscoveredNodes=10_000` caps; pass 2 batch-reads `DataType` + `ValueRank` + `UserAccessLevel` + `Historizing` per variable in one Session.ReadAsync (`OpcUaClientDriver.cs:596-810`).
 - **Type mapping**: built-in OPC UA scalar types → `DriverDataType`; structs/enums/extension objects fall through to String passthrough; `ValueRank>=0` flags arrays (`OpcUaClientDriver.cs:820-836`).
 - **ACL bridge**: `UserAccessLevel.CurrentWrite` → `SecurityClassification.Operate`, otherwise `ViewOnly`; gating happens server-side in DriverNodeManager (`OpcUaClientDriver.cs:844-850`).
 - **Read/Write**: batched ReadAsync/WriteAsync with NodeId pre-parse + per-tag `BadNodeIdInvalid` short-circuit; cascading-quality preserves upstream `StatusCode` and `SourceTimestamp` verbatim; transport faults fan out as `BadCommunicationError` (`OpcUaClientDriver.cs:441-568`).
 - **Subscriptions**: native MonitoredItem forwarding with publishing-interval floor of 50 ms, `KeepAliveCount=10`, `LifetimeCount=1000`, `QueueSize=1`, `DiscardOldest=true`, `Reporting` mode, `TimestampsToReturn.Both` (`OpcUaClientDriver.cs:854-914`).
 - **Alarms (A&C)**: EventFilter SelectClauses on `BaseEventType` + `ConditionType` (EventId/EventType/SourceNode/Message/Severity/Time/ConditionId), source-node filter set, `QueueSize=1000` for burst tolerance, `Acknowledge` method invocation forwarded as `CallAsync`; severity bucketed Low/Medium/High/Critical per OPC UA Part 9 (`OpcUaClientDriver.cs:967-1143`).
 - **HistoryRead pass-through**: `ReadRawAsync`, `ReadProcessedAsync` (Average/Min/Max/Total/Count standard aggregates), `ReadAtTimeAsync` with continuation point support (`OpcUaClientDriver.cs:1154-1264`).
 - **Diagnostics**: per-driver `HostName` reflects the URL actually connected (not the first candidate); `HostState` transitions Running/Stopped/Unknown driven by keep-alive; `DriverHealth` carries `LastSuccessfulRead` + last error (`OpcUaClientDriver.cs:1281-1372`).
 - **Capability surface**: 8/8 — `IDriver`, `ITagDiscovery`, `IReadable`, `IWritable`, `ISubscribable`, `IHostConnectivityProbe`, `IAlarmSource`, `IHistoryProvider`.
 ### Gaps vs commercial UA aggregators
 - **[Build]** **Reverse Connect (server-initiated client connect)** — present in: UaGateway, Prosys Forge, Kepware (1.5+), Matrikon. Why: lets the upstream server traverse outbound-only firewalls (typical OT-DMZ direction); a hard requirement for many regulated plant networks.
 - **[Build]** **Discovery URL with `FindServers` / `FindServersOnNetwork`** — present in: Kepware, UaGateway, Matrikon. Why: we accept only an explicit endpoint URL; commercial gateways resolve a discovery URL and let the operator pick from advertised endpoints in a UI without copying the policy/mode tuple by hand.
 - **[Skip]** **Multicast / LDS-ME registration** — present in: UaGateway, Prosys. Why: lets clients discover this gateway via the Local Discovery Server without static config.
 - **[Skip]** **GDS push management (Part 12)** — present in: UaGateway, Prosys. Why: certificate provisioning, renewal, trust-list updates pushed from a central GDS — required for fleets >10 endpoints; we have no `ServerConfigurationType` method support and no automatic renewal hook.
 - **[Build]** **Per-tag advanced subscription tuning** — present in: Kepware, UaGateway, Cogent. Why: `SamplingInterval`, `QueueSize`, `DiscardOldest`, `MonitoringMode`, `DataChangeFilter` (DeadbandType=Absolute/Percent, Trigger=Status/StatusValue/StatusValueTimestamp) are hard-coded (50 ms / 1 / true / Reporting / no deadband). No way to set deadbands per tag — a baseline aggregator feature for analog noise filtering.
 - **[Build]** **Per-subscription tuning (`PublishingInterval` / `KeepAliveCount` / `LifetimeCount` / `MaxNotificationsPerPublish` / `Priority`)** — present in: all listed gateways. Why: we hard-code 10/1000/0/0 in `Subscription` and `MaxNotificationsPerPublish=0` (unlimited) is a denial-of-service surface against high-event-rate servers; high-tag-count deployments need to split subscriptions across priorities.
 - **[Build]** **Selective import / namespace remap** — present in: Kepware, Matrikon, UaGateway, Cogent. Why: we mirror everything under `BrowseRoot` and re-prefix with a single "Remote" folder; commercial aggregators support per-branch include/exclude rules, namespace-URI remapping, alias paths, and re-keyed BrowseNames.
 - **[Build]** **Type definition mirroring (ObjectTypes / VariableTypes / DataTypes / ReferenceTypes)** — present in: UaGateway, Prosys, Kepware. Why: we walk Object + Variable nodes only; HasTypeDefinition references and custom type nodes are dropped, so downstream UI clients lose type-aware rendering and structured DataTypes decode as String passthrough.
 - **[Build]** **Method node mirroring + pass-through `Call`** — present in: UaGateway, Matrikon, Kepware. Why: `NodeClass.Method` is filtered out of the browse and `IDriver` has no `CallMethodAsync` capability; clients cannot invoke remote methods through the gateway. (`Acknowledge` is the only call we forward, hard-coded for A&C.)
 - **[Build]** **Automatic re-import on remote `ServerStatus.NodeVersion` / `ModelChangeEvent`** — present in: UaGateway, Kepware, Prosys. Why: we don't subscribe to `ServerStatus.State` or `BaseModelChangeEventType`; if the upstream server adds nodes mid-flight the new tags don't appear until the driver is reinitialized.
 - **[Skip]** **HistoryUpdate / HistoryRead-Modified / Annotation pass-through** — present in: UaGateway, Prosys Historian, Kepware (LocalHistorian). Why: we ship Raw/Processed/AtTime only; `IsReadModified=false` is hard-coded; no `HistoryUpdate`, no `DeleteRawModified`, no annotation forwarding. Many MES integrations need backfill writes.
 - **[Build]** **`ReadEventsAsync` (HistoryRead Events)** — explicitly deferred per memory entry. Why: `IHistoryProvider.ReadEventsAsync` interface lacks an `EventFilter SelectClauses` parameter to carry the field projection.
 - **[Build]** **Aggregate function set** — present in: UaGateway, Prosys, Kepware. Why: we map only Average/Minimum/Maximum/Total/Count; OPC UA Part 13 standard catalog has 30+ (TimeAverage, Interpolative, StdDev, DurationGood, NumberOfTransitions, etc.) that historian-class clients expect.
 - **[Build]** **Redundant-server URI list (`ServerUriArray`) and transparent failover** — present in: Kepware, UaGateway, Matrikon. Why: our `EndpointUrls` is a one-shot connect-attempt list, not a live redundancy group; we don't read the upstream `ServerRedundancyType` or fail over mid-session on `ServiceLevel` drop.
 - **[Build]** **Maximum nodes per Read/Write/Browse honored from server capabilities** — present in: all listed gateways. Why: we delegate chunking to the SDK but never query `Server.ServerCapabilities.OperationLimits.MaxNodesPerRead/Write/Browse`; on undersized servers this can produce `BadTooManyOperations` instead of automatic fragmentation.
 - **[Skip]** **Connection / session pooling for multi-instance scale-out** — present in: UaGateway, Cogent. Why: each driver instance opens its own session even when N drivers point at the same upstream; commercial gateways multiplex one session per remote across multiple downstream contexts to cut session count and cert-handshake load.
 - **[Build]** **Diagnostics counters (PublishRequest count, NotificationsPerSecond, MissingPublishRequests, dropped-notification rate)** — present in: UaGateway, Prosys. Why: `DriverHealth` carries `LastSuccessfulRead` + last error string only; no per-server message-rate counters or publish-queue health metrics for the Admin dashboard.
 - **[Skip]** **Kerberos / OAuth2 / IssuedToken (JWT) user identity** — present in: Kepware (Kerberos), UaGateway, Prosys. Why: we support Anonymous/Username/Certificate only; no `IssuedIdentityToken` token type, no Kerberos SPNEGO, no JWT bearer flow that newer security stacks (Azure AD) expect.
 - **[Skip]** **WriteAsync attribute scope beyond Value** — present in: UaGateway, Matrikon. Why: `WriteAsync` hard-codes `AttributeId = Attributes.Value`; no way to write `StatusCode`, `SourceTimestamp`, or non-Value attributes (rare but a documented OPC UA capability).
 - **[Build]** **CRL / revocation list configuration** — present in: Kepware, UaGateway. Why: the cert-validator hooks `BadCertificateUntrusted` only; revoked-cert chains aren't explicitly checked or surfaced as a distinct fault, and there's no `RejectSHA1SignedCertificates` knob.
 ### Recommendations
 | # | Gap | Build? | Rationale |
 |---|-----|:------:|-----------|
 | 1 | Reverse Connect | Yes | OT-DMZ outbound-only is the standard plant-network direction |
 | 2 | Discovery URL `FindServers` | Yes | Standard UX; saves manual policy / mode tuple copy |
 | 3 | Multicast / LDS-ME registration | No | Server-side responsibility, not aggregator's |
 | 4 | GDS push management (Part 12) | No | Significant infra; rare for our deployment scale |
 | 5 | Per-tag advanced subscription tuning (deadband, queue, mode) | Yes | Deadbands are baseline analog filtering |
 | 6 | Per-subscription tuning (publishing / keep-alive / lifetime) | Yes | Avoid DoS on bursty servers; operability |
 | 7 | Selective import / namespace remap | Yes | Curation is a baseline aggregator feature |
 | 8 | Type definition mirroring | Yes | UI clients lose structure decoding without it |
 | 9 | Method node mirroring + `Call` passthrough | Yes | Clear functional gap; `IDriver` capability missing |
 | 10 | Auto re-import on `ModelChangeEvent` | Yes | Correctness when remote topology changes |
 | 11 | HistoryUpdate / Modified / Annotation passthrough | No | MES backfill scope; defer |
 | 12 | `ReadEventsAsync` (HistoryRead Events) | Yes | Fix the `IHistoryProvider` abstraction gap |
 | 13 | Full Aggregate function set (Part 13) | Yes | Cheap to forward; historian clients expect it |
 | 14 | `ServerUriArray` redundant failover | Yes | HA expectation when upstream is redundant |
 | 15 | Honor server `OperationLimits` | Yes | Correctness; avoids `BadTooManyOperations` |
 | 16 | Connection / session pooling | No | Premature; current per-instance model is simple and adequate |
 | 17 | Diagnostics counters | Yes | Operability; admin dashboard needs publish-rate visibility |
 | 18 | Kerberos / OAuth2 / JWT identity | No | Significant security work; defer until AD integration drives it |
 | 19 | Write attribute scope beyond Value | No | Niche; rarely used in OPC UA practice |
 | 20 | CRL / revocation handling | Yes | Security baseline expectation |
 ### Notable parity (keep)
 - Cascading-quality contract: upstream `StatusCode` and `SourceTimestamp` preserved verbatim across Read, Subscribe, History — a baseline OPC-to-OPC bridging requirement.
 - Native subscription forwarding (no polling translation layer) — matches Kepware/UaGateway architecture, not Matrikon Tunneller's COM-bridge approach.
 - Two-pass discovery batching attribute reads — many naive aggregators issue per-node Reads which makes 10k-node servers take minutes.
 - Explicit policy+mode endpoint matching (no silent downgrade) — matches UaGateway's behavior; Kepware historically defaulted to "best available" which has been a CVE source.
 - Per-endpoint connect-timeout in failover sweep — bounded init budget is a property most of the listed gateways added late.
 - SDK-managed `TransferSubscriptions` on reconnect — matches the OPC Foundation reference behavior; no hand-rolled migration code.
 ### Sources
 - OPC Foundation UA-.NETStandard SDK docs — https://github.com/OPCFoundation/UA-.NETStandard
 - Kepware KEPServerEX OPC UA Client — https://www.ptc.com/en/products/kepware/kepserverex/clients/opc-ua-client
 - Matrikon OPC UA Tunneller — https://www.matrikonopc.com/products/opc-tunneller/
 - Unified Automation UaGateway — https://www.unified-automation.com/products/wrapper-and-gateway/ua-gateway.html
 - Prosys OPC UA Forge / Historian — https://www.prosysopc.com/products/opc-ua-forge/
 - Cogent DataHub OPC UA — https://www.cogentdatahub.com/products/opc-ua/
 - AVEVA System Platform OI.UACLIENT — https://docs.aveva.com (Operations Integration UACLIENT)
 - OPC UA Part 4 (Services), Part 5 (Information Model), Part 9 (A&C), Part 11 (HistoricalAccess), Part 12 (Discovery & GDS), Part 13 (Aggregates), Part 14 (PubSub) — https://reference.opcfoundation.org/
 ---
 ## S7 (Siemens S7-300/400/1200/1500)
 ### What we ship today
 - Native S7comm over ISO-on-TCP via S7netplus; default port 102, configurable so an in-CI Snap7 server can bind 1102 (`S7DriverOptions.cs:32`, `S7Driver.cs:87`).
 - CPU family selector — `S71200`, `S71500`, `S71200Smart`, `S7200`, `S7300`, `S7400` — enum forwarded straight to S7netplus to pick the remote TSAP slot byte (`S7DriverOptions.cs:34-38`).
 - Rack/slot configuration with documented conventions (S7-300 slot 2, S7-400 slot 2/3, S7-1200/1500 slot 0) (`S7DriverOptions.cs:42-51`).
 - Single-connection-per-PLC policy enforced by a `SemaphoreSlim` because the CPU's comms mailbox is scanned at most once per cycle (`S7Driver.cs:23-27,60-67`).
 - Static tag table parsed at `InitializeAsync` so syntactic typos fail fast instead of bleeding through as `BadInternalError` per read (`S7Driver.cs:103-110`).
 - Address parser accepts DB / M / I / Q / T / C with X/B/W/D widths and 0-7 bit offsets, case-insensitive, with structured `FormatException` messages (`S7AddressParser.cs:65-216`).
 - Scalar reads/writes for Bool, Byte, Int16/UInt16, Int32/UInt32, Float32 with explicit signed/unsigned reinterpret of S7netplus' boxed unsigned return values (`S7Driver.cs:231-251,306-322`).
 - PUT/GET-disabled detection — `S7.Net.PlcException` mapped to `BadDeviceFailure` and surfaced as a configuration alert rather than retried via Polly (`S7Driver.cs:200-208`, `S7DriverOptions.cs:14-25`).
 - Polled `ISubscribable` overlay floored at 100 ms to avoid wire-side queueing past CPU scan; per-tag last-value diffing for change-of-value publishing (`S7Driver.cs:365-425`).
 - `IHostConnectivityProbe` using `ReadStatusAsync` (CPU Run/Stop) every probe interval, gated on the same semaphore so it doesn't race a live read (`S7Driver.cs:457-489`).
 - Per-tag `WriteIdempotent` flag for replay-safe write retry policy (`S7DriverOptions.cs:91-104`).
 - Snap7-server-backed integration fixture covers atomic typed reads + DB write-then-read round-trip on `localhost:1102` (`docs/drivers/S7-Test-Fixture.md:1-60`).
 - Test CLI — probe / read / write / subscribe — with the same address grammar and CPU/slot flags (`docs/Driver.S7.Cli.md`).
 ### Gaps vs commercial gateways
 - **[Build]** **S7-1500 Optimized DB / Symbolic addressing (S7Plus)** — present in: Kepware "Siemens S7 Plus", Ignition, AVEVA OI.SIDIRECT (limited). Why: S7netplus speaks classic S7comm only; optimized DBs reorder fields and have no fixed byte offsets, so absolute `DB1.DBW0` reads return `BadDeviceFailure` until "Optimized block access" is unchecked in TIA Portal.
 - **[Build]** **PDU size negotiation surfaced to operators** — present in: Kepware, TOP Server, AVEVA OI.SIDIRECT. Why: Modern S7 CPUs negotiate PDU sizes from 240 up to 960 bytes; we accept whatever S7netplus negotiates with no operator visibility into the cap and no per-request packing strategy that uses the negotiated size.
 - **[Build]** **Multi-variable PDU packing / read coalescing** — present in: every commercial gateway. Why: `ReadAsync(IReadOnlyList<string>)` issues one S7netplus call per tag inside the semaphore (`S7Driver.cs:182-214`); commercial gateways bin-pack contiguous DB ranges into a single multi-item PDU which is 5-50× faster on dense tag groups.
 - **[Build]** **TSAP / Connection Type selector (PG / OP / S7-Basic / Other)** — present in: Kepware, TOP Server, AVEVA. Why: S7netplus picks PG-style TSAPs; sites that need OP-class slots (e.g. fenced HMI connections, license-counted PG slots) cannot pick. Some S7-1500 hardening modes refuse PG access from non-allowlisted clients.
 - **[Build]** **Symbol-table / TIA Portal export browse** — present in: Kepware (online symbol upload on S7-1500), Ignition (TIA tag CSV import), TOP Server (tag-import wizard from `.AWL`/`.udt`/`.xml`). Why: We ship a static tag table only (`S7DriverOptions.cs:55-57`); operators must hand-edit the JSON. No `.tia`/`.s7p` import, no online symbol read of the S7-1500 PG symbol table.
 - **[Build]** **UDT / STRUCT / nested-DB handling** — present in: Kepware, Ignition, TOP Server. Why: Tag map is flat scalar-only — no UDT fan-out into member variables, no `Array of <UDT>` indexing. Real S7-1500 projects expose hundreds of UDT-typed DBs.
 - **[Build]** **Array tags (ValueRank=1)** — present in: every commercial gateway. Why: `S7TagDefinition` has no array dimension; `MapDataType` always returns `IsArray: false` (`S7Driver.cs:337-345`). OPC UA arrays of S7 `Array[0..n]` are unaddressable.
 - **[Build]** **STRING / WSTRING / DTL / S5TIME / TIME / DATE_AND_TIME read+write** — present in: every commercial gateway. Why: Enum entries exist but every code path throws `NotSupportedException` (`S7Driver.cs:241-245,316-320`); S7 `STRING` has a 2-byte header, `WString` is UTF-16 with a 4-byte header, `DTL` is 12 bytes, `S5TIME` is BCD-encoded — none are wired up.
 - **[Build]** **64-bit types (LInt / ULInt / LReal / LWord)** — present in: Kepware S7 Plus, Ignition, TOP Server S7-1500 driver. Why: `Int64`/`UInt64`/`Float64` cases throw `NotSupportedException` (`S7Driver.cs:241-243`); S7-1500 `LReal` (8-byte double) is the standard analog representation in modern projects.
 - **[Build]** **Instance-DB / FB-block parameter access** — present in: Kepware, Ignition (with TIA import). Why: We address by absolute DB number; instance DBs of multi-instance FBs need symbolic resolution (`MyFB_Instance.MyParam`) which our parser doesn't accept.
 - **[Build]** **CPU diagnostic buffer / SZL reads** — present in: Kepware (CPU diagnostic tags), TOP Server (`@Diagnostic` tags), AVEVA OI.SIDIRECT. Why: We probe `ReadStatusAsync` only (`S7Driver.cs:476`); SZL IDs 0x0000-0xFFFF (CPU type, firmware version, cycle time min/max/avg, diagnostic-buffer entries, hardware module status) are not exposed as system tags.
 - **[Skip]** **AS-Alarms / Alarm_S/SQ/D/DQ / S7 ProDiag** — present in: Kepware (Alarms suite), Ignition. Why: No `IAlarmSource` implementation; CPU-resident alarms (Alarm_S blocks, ProDiag supervision messages, system diagnostic messages) are invisible to OPC UA A&E clients. CPU diagnostic-buffer entries similarly not surfaced.
 - **[Skip]** **CPU Run/Stop control / block download / PG functions** — present in: Kepware (limited), AVEVA OI.SIDIRECT. Why: `ReadStatusAsync` is the only PG-class call we make; remote `WriteCpuStop` / `WriteCpuStart`, block download, password authentication for PG functions are absent.
 - **[Build]** **PLC password / protection-level handling** — present in: Kepware, TOP Server, AVEVA. Why: S7-300/400 protection levels 1-3 and S7-1200/1500's "Connection mechanisms" / "Full access incl. fail-safe" tiers can require a password on connect; S7netplus's `Plc` ctor takes no password and we have no place to plumb one through.
 - **[Skip]** **S7-1500 "Secure Communication" (TLS / certificate-based)** — present in: Siemens-direct (OPC UA on S7-1500), Kepware S7 Plus partial. Why: S7-1500 firmware V3.0+ supports authenticated PG connections with certificates; we connect plaintext over TCP only. Sites with hardened CPUs (`Access protection = high` + cert required) won't accept the driver.
 - **[Skip]** **S7-400H / redundant H-system support** — present in: Kepware (paired-IP with sticky-master), AVEVA OI.SIDIRECT. Why: We have one host/port; H-systems present two sync'd CPUs on two IPs and the driver should fail over without losing subscriptions. Driver-level redundancy is unimplemented (server-level redundancy in `docs/Redundancy.md` is a separate axis).
 - **[Skip]** **Multi-CPU rack / multiple TSAPs per rack** — present in: Kepware, TOP Server. Why: One Plc instance binds one (rack, slot); S7-400 multi-CPU racks expose 2-4 CPUs that need parallel sessions to drive in parallel.
 - **[Skip]** **MPI / Profibus / RFC1006-routed transports** — present in: Kepware, AVEVA OI.SIDIRECT (DASSIDirect legacy paths), TOP Server. Why: S7netplus is Ethernet-only. Brownfield S7-300 sites still routed via CP 5611/5613 MPI cards or via S7-1500-as-router for fenced subnets are out of reach.
 - **[Build]** **LOGO! 8 / S7-200 / S7-200 Smart variant tuning** — present in: Kepware "Siemens TCP/IP Ethernet" (LOGO!), Sharp7 (S7-200 Smart), Ignition. Why: `CpuType.S7200`/`S7200Smart` exists in S7netplus but the V-memory area (`V` letter) is not in our parser's switch (`S7AddressParser.cs:88-97`). LOGO!'s VM range and S7-200's V/SM areas are unaddressable.
 - **[Build]** **Per-tag scan group / publish rate** — present in: Kepware (scan classes), Ignition (tag groups), TOP Server (scan rate per tag). Why: Subscriptions take one publishingInterval for the whole tag list (`S7Driver.cs:365-380`); a CPU with mixed 100 ms / 1 s / 10 s tags needs three subscribe calls and three semaphore-serialized poll loops.
 - **[Build]** **Deadband / on-change suppression with absolute or percent thresholds** — present in: every commercial gateway. Why: We diff exact-equal only (`S7Driver.cs:419`); no analog deadband — a noisy float tag floods the bus.
 - **[Build]** **Block-read coalescing for contiguous DB regions** — present in: every commercial gateway. Why: Reading `DB1.DBW0`, `DB1.DBW2`, `DB1.DBW4` issues 3 calls; commercial drivers issue a single FC=04 ReadVarRequest covering bytes 0-5 and slice client-side.
 - **[Skip]** **Connection-resource budget management / max-parallel-jobs (AmqLen)** — present in: Kepware, TOP Server. Why: S7-1200/1500 expose 8-64 connection-resources and a per-connection parallel-jobs cap (Amq); we hold one connection and serialize, but commercial drivers open 2-4 connections per CPU to multiplex. We have no operator knob.
 - **[Build]** **Pre-flight / online-test of PUT/GET enablement** — present in: Kepware (config validation step), AVEVA. Why: We surface `BadDeviceFailure` only at first read (`S7Driver.cs:200-208`); commercial drivers warn during connection wizard via SZL probe before the operator commits config.
 ### Recommendations
 | # | Gap | Build? | Rationale |
 |---|-----|:------:|-----------|
 | 1 | S7-1500 Optimized DB / Symbolic addressing (S7Plus) | Yes | Hard blocker on modern S7-1500 sites |
 | 2 | PDU size negotiation surfaced | Yes | Cheap operability; no behavior change |
 | 3 | Multi-variable PDU packing | Yes | 5-50x perf; current per-tag-per-call is the baseline gap |
 | 4 | TSAP / Connection Type selector | Yes | Hardened CPUs reject PG-class slots |
 | 5 | Symbol-table / TIA Portal export browse | Yes | Workflow parity; static JSON doesn't scale |
 | 6 | UDT / STRUCT / nested-DB handling | Yes | Real S7-1500 projects expose hundreds of UDTs |
 | 7 | Array tags (ValueRank=1) | Yes | Table-stakes; currently unaddressable |
 | 8 | STRING / WSTRING / DTL / S5TIME / TIME / DT | Yes | Standard datatypes; currently throw `NotSupported` |
 | 9 | 64-bit types (LInt / ULInt / LReal / LWord) | Yes | LReal is the standard analog representation on S7-1500 |
 | 10 | Instance-DB / FB parameter access | Yes | Modern symbolic structure; absolute DBs alone are limiting |
 | 11 | CPU diagnostic buffer / SZL reads | Yes | Operability; firmware / cycle-time visibility |
 | 12 | AS-Alarms / Alarm_S / ProDiag | No | Significant scope; alarms are a separate workstream |
 | 13 | CPU Run / Stop control / block download | No | Security / safety risk; out of scope |
 | 14 | PLC password / protection-level handling | Yes | Hardened CPUs require it (S7netplus support permitting) |
 | 15 | S7-1500 Secure Communication / TLS | No | Significant work; defer |
 | 16 | S7-400H redundant H-system support | No | Rare in our deployment scope |
 | 17 | Multi-CPU rack parallel sessions | No | Rare; one session per CPU works |
 | 18 | MPI / Profibus / RFC1006-routed transports | No | Declining; brownfield only |
 | 19 | LOGO! 8 / S7-200 V-memory area | Yes | Small parser fix broadens coverage materially |
 | 20 | Per-tag scan group / publish rate | Yes | Operability; mixed-rate is normal |
 | 21 | Deadband / on-change with thresholds | Yes | Analog noise mitigation |
 | 22 | Block-read coalescing for contiguous DBs | Yes | Big perf win; complements multi-variable PDU packing |
 | 23 | Connection-resource budget / parallel jobs | No | Premature; one connection works for most rigs |
 | 24 | Pre-flight PUT/GET enablement test | Yes | UX improvement; cheap |
 ### Notable parity (keep)
 - Single-connection-per-PLC + semaphore serialization is the documented S7netplus / Snap7 best practice and matches what TOP Server / AVEVA do in their default profile.
 - 100 ms minimum publishing interval correctly reflects CPU mailbox scan reality — commercial gateways advertise "1 ms scan" in marketing then quietly floor to ~100 ms in practice.
 - Strict address-parse-at-init with structured exceptions (rather than per-read `BadInternalError`) is better operator UX than Kepware's "you'll find out at runtime" default.
 - PUT/GET-disabled mapped to a sticky `BadDeviceFailure` instead of being retried by Polly — Polly retry against a CPU that will keep refusing is exactly the failure mode that floods commercial deployments.
 - `WriteIdempotent` per-tag flag is finer-grained than Kepware's connection-level `Auto Demote` and matches the safe-replay reality: DB set-points are replayable, M/Q edge-triggered bits are not.
 - Probe path uses `ReadStatusAsync` (single CPU-state PDU) rather than a tag read — doubles as "PLC actually up" without polluting the comms mailbox.
 - Driver-instance host/port format (`host:port`) matches the Modbus driver so Admin UI can render both families uniformly.
 - Snap7-server CI fixture closes the "no commercial vendor offers a meaningful S7 simulator" gap that Kepware/TOP Server users hit on day one.
 ### Sources
 - https://www.kepserverexopc.com/products/siemens-tcpip-ethernet/ (Kepware Siemens TCP/IP Ethernet)
 - https://www.kepware.com/en-us/products/kepserverex/drivers/siemens-s7-plus/ (Kepware S7 Plus — Optimized DB / Symbolic addressing)
 - https://www.aveva.com/en/products/communication-drivers/ (AVEVA OI Server / DASSIDirect)
 - https://www.softwaretoolbox.com/topserver-siemens-suite (TOP Server Siemens Suite)
 - https://docs.inductiveautomation.com/docs/8.1/platform/connecting-to-devices/siemens (Ignition Siemens driver guide)
 - https://github.com/S7NetPlus/s7netplus (S7netplus library)
 - https://snap7.sourceforge.net/ (Snap7)
 - https://github.com/evcc-io/sharp7 (Sharp7 fork — S7-1200/1500 PUT/GET semantics)
 - https://cache.industry.siemens.com/dl/files/591/68018591/att_956083/v1/s71500_communication_function_manual_en-US_en-US.pdf (Siemens S7-1500 Communication Function Manual)
 - https://support.industry.siemens.com/cs/document/26224811 (Siemens — TSAPs and connection resources)
 - https://support.industry.siemens.com/cs/document/89260861 (Siemens — SZL list IDs / system status lists)
 - https://docs.tia.siemens.cloud/r/en-us/v20/safety-and-security/secure-communication (S7-1500 secure communication)
 ---
 ## TwinCAT (Beckhoff ADS)
 ### What we ship today
 - `TwinCATDriver` implements `IReadable`, `IWritable`, `ISubscribable`, `ITagDiscovery`, `IHostConnectivityProbe`, `IPerCallHostResolver` over Beckhoff's `Beckhoff.TwinCAT.Ads` v6 `AdsClient` (`src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs:11-12`, `AdsTwinCATClient.cs:22-24`).
 - AMS addressing parses `ads://{netId}:{port}` with the six-octet AmsNetId and TC3 default port 851 (also documents 801/811/821 for TC2 and 10000 for system service) (`TwinCATAmsAddress.cs:20-64`).
 - Native ADS notifications via `AddDeviceNotificationExAsync` with `AdsTransMode.OnChange` and per-tag cycle time; falls back to shared `PollGroupEngine` when `UseNativeNotifications=false` (`TwinCATDriver.cs:296-339`, `AdsTwinCATClient.cs:130-160`).
 - IEC 61131-3 atomic data type surface — Bool, S/U Int 8/16/32/64, Real, LReal, String, WString, Time, Date, DT, TOD (`TwinCATDataType.cs:9-30`).
 - Symbol path parser supports POU/GVL prefix, struct member walks, array subscripts incl. multi-dim `Matrix[1,2]`, and bit-access `.0..31` (`TwinCATSymbolPath.cs:1-104`).
 - Bit-indexed BOOL **read** path: read parent word as `uint`, mask locally (`AdsTwinCATClient.cs:57-64`, `ExtractBit`).
 - Optional controller-side symbol browse via `SymbolLoaderFactory` (flat mode), with system-symbol filter for `TwinCAT_*`, `Constants.*`, `Mc_*`, `__*` (`AdsTwinCATClient.cs:178-195`, `TwinCATSystemSymbolFilter.cs`).
 - Per-device probe loop calls `ReadStateAsync` and emits `OnHostStatusChanged` Running/Stopped transitions (`TwinCATDriver.cs:366-402`).
 - Status-code mapping `AdsErrorCode` → OPC UA via `TwinCATStatusMapper`; auto-reconnect on dropped client (`TwinCATDriver.cs:413-429`).
 - Sized strings `STRING(80)` / `WSTRING(80)` are tolerated in browse — type name parens stripped to bare atom (`AdsTwinCATClient.cs:200-206`).
 - Live-tested against TCBSD VM and Hyper-V XAR — 30 integration test cases (read/write/array/subscribe/browse/reconnect/probe), 110 unit tests (`docs/drivers/TwinCAT-Test-Fixture.md`).
 ### Gaps vs commercial gateways
 - **[Build]** **ADS Sum commands (sum-read / sum-write / sum-add-notification)** — present in: Kepware, TF6100, Ignition, TwinCAT.Ads itself. Why: we issue one `ReadValueAsync` per tag in a loop (`TwinCATDriver.cs:118-156`); commercial drivers batch into `IndexGroup=0xF080..0xF084` sum requests for ~10x throughput on multi-thousand tag scans.
 - **[Build]** **Handle-based access (CreateVariableHandle / ReadByHandle)** — present in: Kepware, TF6100, AdsClient itself. Why: we resolve the symbolic name on every read; cached handles cut per-request bytes and AMS overhead, especially over WAN/multi-hop.
 - **[Build]** **STRUCT / UDT decomposition with offline TMC parsing** — present in: Kepware (TwinCAT TMC import), TF6100 (native), Ignition. Why: `TwinCATDataType.Structure` is declared but discovery skips non-atomic symbols (`AdsTwinCATClient.cs:224`); we can't expose nested UDT trees without hand-declaring every leaf.
 - **[Build]** **Bit-indexed BOOL writes** — present in: Kepware, TF6100. Why: we throw `NotSupportedException` (`AdsTwinCATClient.cs:99-100`); commercial drivers do read-modify-write or use `ADSIGRP_SYM_VALBYNAME` with the `.N` syntax the runtime supports for some primitives.
 - **[Build]** **Multi-dim / whole-array reads** — present in: Kepware, TF6100. Why: we parse `Matrix[1,2]` element-by-element but never read the array in one ADS call; sized-array marshalling is in `TwinCAT.Ads` but unused here.
 - **[Build]** **Int64 fidelity** — present in: TF6100, Ignition. Why: `LInt`/`ULInt` map to `DriverDataType.Int32` (`TwinCATDataType.ToDriverDataType` line 40 with explicit "matches Int64 gap" comment) — silent precision loss above 2^31.
 - **[Build]** **TIME / DATE / DT / TOD as native OPC UA types** — present in: TF6100 (DateTime/Duration), Kepware. Why: we marshal all four as raw `UDINT` (`AdsTwinCATClient.cs:278-280`) leaving timestamp interpretation to the client.
 - **[Build]** **ENUM / ALIAS / REFERENCE / POINTER / INTERFACE / UNION** — present in: TF6100, Kepware (partial). Why: not in `TwinCATDataType`; symbol-mapper returns `null` and skips.
 - **[Skip]** **Multi-target / multi-route AMS gateway** — present in: Kepware, Ignition (one driver instance, many devices). Why: we accept N `Devices` but each requires its own `TwinCATDeviceOptions`; no central route table, no `StaticRoutes.xml` management, no AMS-router credential handling.
 - **[Skip]** **TwinCAT 3.1.4024+ Secure ADS / ADS-over-TLS** — present in: TF6100, recent TwinCAT.Ads. Why: `AdsClient.Connect` is called without secure-ADS opts; no certificate or pre-shared-key knobs in `TwinCATDriverOptions`.
 - **[Skip]** **Route credential management** — present in: Kepware (route auth UI), TF6100. Why: relies entirely on the host AMS router's pre-authorized routes; we have no in-driver way to add a route or supply credentials.
 - **[Skip]** **NC-axis / CNC channel / EtherCAT slave I/O surfaces** — present in: TF6100 (full NC namespace), Kepware (NC variables). Why: our system-symbol filter actively drops `Mc_*` (`TwinCATSystemSymbolFilter.cs:28`); we treat NC plumbing as noise.
 - **[Skip]** **System-service ports** (`AMSPORT_R0_REALTIME=200`, `R0_TCOMSERVER=10000`, `EVENTLOG=110`) — present in: TF6100, Kepware (system data). Why: only `Devices` are PLC-runtime ports in practice; no helpers for system-service requests, run/config-mode switches, or Real-Time diagnostic counters.
 - **[Build]** **Event log ingest (TwinCAT EventLogger / TC3 Eventing)** — present in: TF6100 (alarms/conditions), Ignition. Why: we don't implement `IAlarmSource`; AMS port 110 events never surface as OPC UA AC events.
 - **[Skip]** **PLC RPC / method invocation (TC3 method calls via ADS)** — present in: TF6100. Why: `IWritable` is value-only; no surface for `RpcInvoke`-style method calls on FB instances.
 - **[Skip]** **Per-PLC-runtime fan-out (port 851/852/853)** — partially present. Why: technically supported via separate `Devices` entries, but no helper that auto-discovers which runtimes exist on a controller via the system service.
 - **[Build]** **Sub-millisecond cycle accuracy / max-delay tuning** — present in: TF6100, Kepware. Why: `NotificationSettings(OnChange, cycleMs, 0)` clamps cycle to 1 ms and sets max-delay to 0 (`AdsTwinCATClient.cs:144-145`); no per-tag override of `MaxDelay` to coalesce bursty signals.
 - **[Build]** **Cycle-time / jitter / PLC-state diagnostics** — present in: TF6100, Kepware. Why: probe only checks reachability; we don't surface cycle-time, jitter, RT-state or `_AppInfo.OnlineChangeCnt` as health signals.
 - **[Build]** **Online change / symbol-version invalidation** — present in: TF6100, Ignition. Why: no listener on `ADSIGRP_SYMVAL_BYHND` invalidation event; an online change silently invalidates cached handles (we have none, but adding handles needs this).
 - **[Skip]** **File-system access via ADS (`ADSIGRP_FOPEN/FREAD`)** — present in: TF6100. Why: not implemented; useful for reading recipe files / log uploads without a separate transport.
 ### Recommendations
 | # | Gap | Build? | Rationale |
 |---|-----|:------:|-----------|
 | 1 | ADS Sum commands | Yes | ~10x throughput for multi-thousand-tag scans; blocker at scale |
 | 2 | Handle-based access (caching) | Yes | Perf; reduces per-request bytes and AMS overhead |
 | 3 | STRUCT / UDT decomposition with TMC parsing | Yes | Real projects have nested UDTs we currently can't expose |
 | 4 | Bit-indexed BOOL writes | Yes | Correctness; we read bits but throw on write |
 | 5 | Multi-dim / whole-array reads | Yes | Perf; library supports it |
 | 6 | Int64 fidelity (LInt / ULInt) | Yes | Correctness; we silently truncate |
 | 7 | TIME / DATE / DT / TOD as native UA types | Yes | Correctness; raw UDINT pushes interpretation to clients |
 | 8 | ENUM / ALIAS / REFERENCE / POINTER / INTERFACE / UNION | Yes | At least ENUM and ALIAS are common in real projects |
 | 9 | Multi-target / multi-route AMS gateway | No | Per-device config already works |
 | 10 | Secure ADS / ADS-over-TLS | No | Significant work; defer |
 | 11 | Route credential management | No | Host-level AMS router responsibility |
 | 12 | NC-axis / CNC channel / EtherCAT slave I/O surfaces | No | Specialty; not in target use cases |
 | 13 | System-service ports | No | Niche operational tooling |
 | 14 | Event log / TC3 alarms (`IAlarmSource`) | Yes | Currently no `IAlarmSource` implementation; capability gap |
 | 15 | PLC RPC / method invocation | No | Niche; design-heavy |
 | 16 | Per-PLC-runtime auto-discover | No | Cosmetic; manual port config works |
 | 17 | Sub-millisecond max-delay tuning | Yes | Cheap; helps coalesce bursty signals |
 | 18 | Cycle-time / jitter / PLC-state diagnostics | Yes | Operability; cheap given existing probe |
 | 19 | Online-change / symbol-version invalidation | Yes | Required if handle caching lands (gap #2) |
 | 20 | File-system access via ADS | No | Niche; out of scope |
 ### Notable parity (keep)
 - Native `OnChange` notifications (not polling) — matches TF6100/Kepware default and is the right CPU/latency posture.
 - Symbolic addressing (no manual index-group/offset arithmetic) — same DX as Kepware's TwinCAT driver.
 - Live integration suite against a real runtime (TCBSD + XAR), not just mocks — better than Ignition's stock TwinCAT module which lacks bundled hardware tests.
 - System-symbol filter so `Discovered/` doesn't drown the address space — Kepware ships an equivalent.
 - Config-driven tag declarations as the authoritative path; `EnableControllerBrowse` is opt-in — matches "tag-import-then-curate" workflow Kepware encourages.
 - AmsNetId + port modelled correctly with TC3-vs-TC2 default port awareness — matches TF6100 conventions.
 ### Sources
 - https://infosys.beckhoff.com/english.php?content=../content/1033/tc3_ads_intro/index.html
 - https://infosys.beckhoff.com/english.php?content=../content/1033/tcadsdll2/117571083.html (Sum commands / index groups)
 - https://infosys.beckhoff.com/english.php?content=../content/1033/tf6100_tc3_opcua/index.html (TF6100)
 - https://github.com/Beckhoff/TF6100-OPC-UA-Sample
 - https://github.com/Beckhoff/TC3-AdsClient-Csharp / `Beckhoff.TwinCAT.Ads` NuGet docs
 - https://www.kepserverexlibrary.kepware.com/Beckhoff%20TwinCAT (Kepware Beckhoff TwinCAT driver manual)
 - https://docs.inductiveautomation.com/docs/8.1/platform/connections/devices (Ignition device drivers)
 - https://infosys.beckhoff.com/english.php?content=../content/1033/tc3_security_management/ (Secure ADS)
 - https://infosys.beckhoff.com/english.php?content=../content/1033/tc3_adsnetref/ (NotificationSettings, AdsTransMode)
--- a/docs/plans/abcip-plan.md
+++ b/docs/plans/abcip-plan.md
@@ -0,0 +1,682 @@
 # 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)?
--- a/docs/plans/ablegacy-plan.md
+++ b/docs/plans/ablegacy-plan.md
@@ -0,0 +1,470 @@
 # AbLegacy Driver — Implementation Plan
 > Source of gap analysis: [featuregaps.md → AbLegacy](../featuregaps.md#ablegacy-allen-bradley-plc-5--slc--micrologix)
 >
 > Covers Build = Yes items only. Skip-rated gaps listed at bottom for traceability.
 ## Summary
 The AbLegacy driver (PCCC over EtherNet/IP via libplctag) currently ships with parsing for the canonical SLC/PLC-5/MicroLogix file letters, four PLC-family profiles, bit-within-N-word RMW writes, a probe loop, and a flat static-config tag list. The `featuregaps.md` Recommendations table flags 13 gaps as **Build = Yes**:
 1. DH+ via 1756-DHRIO bridging (#2)
 2. PD/MG/PLS/BT files (#5)
 3. PLC-5 octal addressing (#7)
 4. Indirect/indexed addressing (#8)
 5. Array contiguous block addressing (#9)
 6. ST string read/write production verification (#10)
 7. Sub-element bit semantics (`.DN` as Bit) (#11)
 8. Auto-demote on comm failure (#13)
 9. RSLogix 500/5 symbol import (#15)
 10. Per-tag deadband / change filter (#18)
 11. Diagnostic counters as tags (#20)
 12. Per-device timeout / retry overrides (#21)
 13. MicroLogix function-file naming (RTC/HSC/DLS) (#23)
 The plan splits these across **5 phases / 13 PRs** (one PR per gap, with a couple of small ones bundled). Phases are ordered by coupling — addressing correctness first because everything downstream depends on the parser, then file/type coverage, then performance, then workflow tooling, then resilience. Each PR is sized to fit comfortably under the project's per-PR review budget (most S/M; only the RSLogix import is L).
 ## Phased delivery
 | Phase | Theme | PRs | Gaps |
 |-------|-------|-----|------|
 | 1 | Addressing correctness | 4 | #7 octal, #8 indirect, #11 sub-element bits, #23 ML function files |
 | 2 | File / type coverage | 2 | #5 PD/MG/PLS/BT, #10 ST verification |
 | 3 | Performance | 2 | #9 array block, #18 per-tag deadband |
 | 4 | Workflow | 3 | #15 RSLogix import, #21 per-device timeouts, #20 diagnostic counters |
 | 5 | Resilience | 2 | #13 auto-demote, #2 DH+ bridging |
 Phase 1 lands first because Phase 2 (PD/MG/PLS/BT) and Phase 3 (array reads) both extend the parser shipped in Phase 1. Phase 5 (auto-demote) reads diagnostic counters from Phase 4 #20, so 4 precedes 5.
 ---
 ## Per-PR detail
 ### Phase 1 — Addressing correctness
 #### PR 1 — PLC-5 octal I/O addressing (#7)
 **Scope**: PLC-5 documentation and RSLogix 5 use octal for `I:` / `O:` word and bit indices (`I:001/17` is rack 0 group 0 word 1, bit 17₈ = bit 15₁₀). Today `AbLegacyAddress.TryParse` does `int.TryParse` on the word number and bit index, silently accepting decimal. For `PlcFamily=Plc5` (and only that family) `I` / `O` files must parse as octal.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyAddress.cs` — add `TryParse(string, AbLegacyPlcFamily)` overload; existing `TryParse(string)` keeps decimal semantics (back-compat for non-PLC-5 callers and pure shape validation).
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs` — `EnsureTagRuntimeAsync` and the bit-RMW path call the family-aware overload using `device.Options.PlcFamily`.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/PlcFamilies/AbLegacyPlcFamilyProfile.cs` — add `OctalIoAddressing` flag (true for `Plc5` only).
 **Test plan**:
 - Unit (`tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/AbLegacyAddressTests.cs`): `I:001/17` parses to word=1, bit=15 under PLC-5; same string parses to bit=17 under SLC500. `O:7/10` (decimal under SLC500 = bit 10; octal under PLC-5 = bit 8).
 - Round-trip: `ToLibplctagName()` must emit the format libplctag expects (verify libplctag's PLC-5 PCCC layer accepts octal-formatted I/O addresses, or whether we must convert decimal→octal-text before forwarding).
 **Docs / fixture / e2e**:
 - Update `docs/Driver.AbLegacy.Cli.md` — extend the "PCCC address primer" with an `I:` / `O:` row noting PLC-5 octal vs SLC500 decimal semantics; worked example showing `I:001/17` resolved differently per family.
 - Update `docs/drivers/AbLegacy-Test-Fixture.md` — note octal-vs-decimal addressing as a covered family-aware parser dimension under the unit-coverage list.
 - Fixture: extend `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/docker-compose.yml` `plc5` profile to seed an `I:001` (or equivalent module-image word) tag if `ab_server --plc=PLC/5` accepts it; otherwise document the gap in `Docker/README.md`.
 - E2E: add `--plc-type Plc5 -a "I:001/17"` octal-bit assertion to `scripts/e2e/test-ablegacy.ps1` (gated on the `plc5` compose profile being up); no change to `scripts/smoke/seed-ablegacy-smoke.sql` required (existing `N7:5` tag continues to cover the SLC500 path).
 **Effort**: S
 **Dependencies**: none
 ---
 #### PR 2 — MicroLogix function-file letters (RTC / HSC / DLS / MMI / PTO / PWM / STI / EII / IOS / BHI) (#23)
 **Scope**: MicroLogix 1100/1400 expose proprietary function files that don't share file letters with SLC. Today `IsKnownFileLetter` (`AbLegacyAddress.cs:97-101`) only allows the SLC/PLC-5 set, so any tag like `RTC:0.HR` is rejected at parse time even though libplctag's `micrologix` PlcType supports them.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyAddress.cs` — extend `IsKnownFileLetter` to recognise multi-letter function-file types (`RTC`, `HSC`, `DLS`, `MMI`, `PTO`, `PWM`, `STI`, `EII`, `IOS`, `BHI`). Permit only when family is `MicroLogix`. The letter-scan loop already accepts any contiguous letters (`AbLegacyAddress.cs:80-82`).
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDataType.cs` — define a sub-element catalogue per function-file (RTC has YR/MON/DAY/HR/MIN/SEC/DOW; HSC has ACC/HIP/LOP/OFS/etc.). Map each sub-element to the right `DriverDataType`.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/PlcFamilies/AbLegacyPlcFamilyProfile.cs` — `SupportsFunctionFiles` flag.
 **Test plan**:
 - Unit: `RTC:0.HR` parses with `FileLetter="RTC"`, `WordNumber=0`, `SubElement="HR"`. `HSC:0.ACC` parses. Same strings under PlcFamily=Slc500 must reject (ML1100 file types not present on SLC).
 - Integration (`tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests`): only if a MicroLogix simulator profile exists; flag as TODO otherwise — verify libplctag `micrologix` PlcType accepts these tag names.
 **Docs / fixture / e2e**:
 - New doc `docs/drivers/AbLegacy-MicroLogix-FunctionFiles.md` — catalogue of supported function files (RTC/HSC/DLS/MMI/PTO/PWM/STI/EII/IOS/BHI), per-family availability matrix (ML1100 vs ML1400 vs ML1500), sub-element-to-DriverDataType table.
 - Update `docs/Driver.AbLegacy.Cli.md` — add a "MicroLogix function files" row to the PCCC address primer with `RTC:0.HR` / `HSC:0.ACC` examples and a CLI worked example.
 - Update `docs/drivers/AbLegacy-Test-Fixture.md` — record fixture coverage status for function files and link to the `micrologix` profile gap (only if `ab_server --plc=Micrologix` rejects function-file addresses, document the unit-only fallback).
 - Fixture: extend `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/docker-compose.yml` `micrologix` profile with `--tag=RTC0[1]` / `--tag=HSC0[1]` if accepted by `ab_server`, else mark as hardware-gated in `Docker/README.md`.
 - E2E: add a parametric `-PlcType MicroLogix -Address RTC:0.HR` invocation to `scripts/e2e/test-ablegacy.ps1` (skip-when-fixture-gap, mirroring the existing `BadCommunicationError` gate); no `seed-ablegacy-smoke.sql` change unless the fixture supports function-file tags.
 **Effort**: M
 **Dependencies**: PR 1 (parser overload signature settled)
 ---
 #### PR 3 — Sub-element bit semantics (`.DN`, `.EN`, `.TT`, `.CU`, `.CD`, `.OV`, `.UN`, `.ER`) (#11)
 **Scope**: Today `T4:0.DN` parses fine but the `TimerElement`/`CounterElement`/`ControlElement` types collapse to `Int32` (`AbLegacyDataType.cs:41-44`). HMIs expect `.DN` / `.EN` / `.TT` / `.CU` / `.CD` / `.OV` / `.UN` / `.ER` to surface as `Boolean`. The fix is to detect the sub-element at tag-runtime build time and override the driver-surface type.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDataType.cs` — new helper `SubElementBitNames` (HashSet of bit-typed sub-elements per parent type — Timer: EN/TT/DN; Counter: CU/CD/DN/OV/UN; Control: EN/EU/DN/EM/ER/UL/IN/FD). New `EffectiveDriverDataType(AbLegacyDataType, string? subElement)` returning `Boolean` for bit-typed sub-elements, otherwise the existing mapping.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs` — `DiscoverAsync` uses `EffectiveDriverDataType(def.DataType, parsed.SubElement)`; `ReadAsync` decodes the parent word and masks the bit instead of returning the whole word as Int32.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/LibplctagLegacyTagRuntime.cs` — verify libplctag exposes `.DN` etc. as a single bit when read with `GetBit` against the sub-element address. If not, fall back to read-the-word + mask.
 **Test plan**:
 - Unit (`AbLegacyDriverTests` + new `AbLegacyDataTypeTests`): `T4:0.DN` discovers as Boolean; `T4:0.ACC` discovers as Int32; counter `.OV` is Boolean; control `.LEN` is Int32.
 - Bit-write semantics: writing Boolean `true` to `T4:0.DN` should be rejected with `BadNotWritable` (timer status bits are PLC-set; verify by integration smoke test against the AbLegacy simulator).
 **Docs / fixture / e2e**:
 - Update `docs/Driver.AbLegacy.Cli.md` — extend the Timer/Counter/Control rows in the address primer with a "bit sub-elements surface as Boolean" note and a `--type Bool -a T4:0.DN` CLI example.
 - Update `docs/drivers/AbLegacy-Test-Fixture.md` — note `AbLegacyDataTypeTests` as a new unit-coverage class under "What it actually covers".
 - Fixture: no compose change required (T4/C5/R6 already seeded by `ab_server` defaults — verify; if not, add `--tag=T4[5]`/`--tag=C5[5]`/`--tag=R6[5]` to the `slc500` profile in `Docker/docker-compose.yml`).
 - E2E: extend `scripts/e2e/test-ablegacy.ps1` with a Boolean sub-element read assertion (`read --type Bool -a T4:0.DN`) once the simulator round-trip works. Update `scripts/smoke/seed-ablegacy-smoke.sql` to add a Boolean tag binding `T4:0.DN` so the server-bridge assertion exercises the new mapping.
 **Effort**: M
 **Dependencies**: none (independent of PR 1/2 parser changes)
 ---
 #### PR 4 — Indirect / indexed addressing parser (`N7:[N7:0]`, `N[N7:0]:5`) (#8)
 **Scope**: Recipe / batch lookup tables use `N7:[N7:0]` (read N7 word indexed by the value at N7:0) or `N[N7:0]:5`. Today `AbLegacyAddress.TryParse` rejects both because it requires literal integer word and file numbers.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyAddress.cs` — record gains nullable `IndirectFileSource` and `IndirectWordSource` (each itself an `AbLegacyAddress`). Parser handles `[<inner>]` segments at file-number or word-number positions. Recursion depth capped at 1 (libplctag accepts only one level of indirection per address — verify against libplctag PCCC docs).
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDataType.cs` — no change.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs` — pass-through; `ToLibplctagName()` re-emits the bracket form.
 **Test plan**:
 - Unit: `N7:[N7:0]` → outer file=N7, indirect word source = (N, 7, 0); `B3:[N7:0]/0` → bit, indirect word source = (N, 7, 0); `N[N7:0]:5` → indirect file source = (N, 7, 0), word=5; depth-2 (`N[N[N7:0]:5]:0`) must reject.
 - Integration: verify libplctag's `slc500`/`plc5` PlcType accepts a `Name` of form `N7:[N7:0]` and resolves at read time. (If libplctag rejects indirect text, fall back to two-step read: resolve the inner address, then read the outer with the resolved index. Document the chosen strategy in the PR.)
 **Docs / fixture / e2e**:
 - New doc `docs/drivers/AbLegacy-Indirect-Addressing.md` — explain `N7:[N7:0]` and `N[N7:0]:5` syntax, the depth-1 limit, the chosen libplctag strategy (verbatim pass-through vs two-step resolve), and recipe-table use cases.
 - Update `docs/Driver.AbLegacy.Cli.md` — add an indirect-addressing row to the address primer with `--address "N7:[N7:0]"` example.
 - Update `docs/drivers/AbLegacy-Test-Fixture.md` — under unit coverage, list `AbLegacyAddressTests` indirect-parsing cases.
 - Fixture: no `Docker/docker-compose.yml` change required (`N7[10]` already seeded; the inner index tag at `N7:0` is already addressable). Document recipe-pattern in `Docker/README.md`.
 - E2E: extend `scripts/e2e/test-ablegacy.ps1` with an indirect-address driver-loopback case (write to `N7:0` to set the index, then read `N7:[N7:0]` and assert the value matches the previously-written content of the resolved word). Skip-gate behind libplctag capability check.
 **Effort**: M
 **Dependencies**: PR 1 (octal resolution must apply to inner address too if the outer file is `I:`/`O:` on PLC-5)
 ---
 ### Phase 2 — File / type coverage
 #### PR 5 — PD / MG / PLS / BT structure files (#5)
 **Scope**: Add PD (PID), MG (Message), PLS (Programmable Limit Switch), BT (Block Transfer) file types to the parser and the data-type catalogue. PD has SP/PV/CV/Error/Bias plus 25+ sub-elements; MG has Error/Length/Position/etc.; PLS has LEN/POS; BT is similar to MG.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyAddress.cs` — extend `IsKnownFileLetter` with `PD`, `MG`, `PLS`, `BT`.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDataType.cs` — new enum members `PidElement`, `MessageElement`, `PlsElement`, `BlockTransferElement`. Sub-element catalogue per type — many PD sub-elements are Float32 (`SP`, `PV`, `CV`, `KP`, `KI`, `KD`), some are Boolean (`EN`, `DN`, `MO`, `PE`), some Int16 (`SPS`, `MAXS`, `MINS`).
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/LibplctagLegacyTagRuntime.cs` — verify libplctag PCCC supports addressing PD/MG/PLS/BT sub-elements by name; if not, the driver reads the parent struct as a byte block and offsets internally (libplctag docs to consult).
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/PlcFamilies/AbLegacyPlcFamilyProfile.cs` — `SupportsPidFile` etc. flags (PLC-5 supports PD/BT; SLC supports PD; ML1100/1400 generally do not — verify per family docs).
 **Test plan**:
 - Unit: `PD9:0.SP` → Float32; `PD9:0.EN` → Boolean; `MG10:0.LEN` → Int32; reject `PD9:0` (no sub-element on a struct file).
 - Integration: smoke test against a simulator with PD file configured (verify pylogix/pycomm3 sim supports PD, otherwise mark as TODO and lean on unit coverage).
 **Docs / fixture / e2e**:
 - New doc `docs/drivers/AbLegacy-Structure-Files.md` — sub-element catalogues for PD / MG / PLS / BT, per-family availability matrix (PLC-5 vs SLC vs ML), DriverDataType per sub-element.
 - Update `docs/Driver.AbLegacy.Cli.md` — add PD / MG / PLS / BT rows to the file-letter primer with `--type PidElement` etc. examples.
 - Update `docs/drivers/AbLegacy-Test-Fixture.md` — list new structure-file file letters under unit coverage and note any fixture limitations (pd/mg likely not supported by `ab_server`).
 - Fixture: extend `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/docker-compose.yml` `slc500` and `plc5` profiles with `--tag=PD9[2]` / `--tag=MG10[2]` if `ab_server` accepts; otherwise document gap in `Docker/README.md` and rely on unit coverage.
 - E2E: extend `scripts/e2e/test-ablegacy.ps1` with a `read --type Float -a PD9:0.SP` assertion when fixture exposes the file; add a corresponding tag row to `scripts/smoke/seed-ablegacy-smoke.sql` (skip-gated).
 **Effort**: M
 **Dependencies**: PR 3 (sub-element bit semantics machinery must exist first — PD `.EN` is Boolean by the same mechanism as Timer `.EN`)
 ---
 #### PR 6 — ST string read/write production verification (#10)
 **Scope**: ST is enum-listed and `LibplctagLegacyTagRuntime.DecodeValue` calls `_tag.GetString(0)`, but there's no integration coverage that ST round-trips through libplctag's 82-byte length-word format. This PR is verification + any fixes uncovered.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/LibplctagLegacyTagRuntime.cs` — likely no source change if libplctag's `GetString`/`SetString` already handles the length-word convention; if not, add `GetByteArrayBuffer` + manual length-word decode.
 - `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/AbLegacyReadSmokeTests.cs` — add `ST_RoundTrip_*` tests against the simulator: write 82-char string, write 0-char, write 41-char, write embedded null/non-ASCII; round-trip each through ReadAsync.
 - New `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/AbLegacyStringEncodingTests.cs` — unit-level decode of a known length-word + payload byte buffer (mock `IAbLegacyTagRuntime` returning fixed bytes).
 **Test plan**:
 - Integration: 4 round-trip cases above; covers PlcFamily=Slc500 and PlcFamily=Plc5 (libplctag may handle the length word differently between the two PCCC layers — verify).
 - Quality: unit test that `BadOutOfRange` surfaces when caller writes a 100-char string to an 82-byte ST.
 **Docs / fixture / e2e**:
 - Update `docs/Driver.AbLegacy.Cli.md` — expand the `ST` row in the address primer with the 82-byte limit, length-word convention, and a `write --type String --value "Hello"` worked example.
 - Update `docs/drivers/AbLegacy-Test-Fixture.md` — list the new `AbLegacyStringEncodingTests` unit class and the four `ST_RoundTrip_*` integration cases under coverage.
 - Fixture: extend `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/docker-compose.yml` `slc500` and `plc5` profiles with `--tag=ST20[5]` so the round-trip tests have a real address to write against; document any `ab_server` ST gaps in `Docker/README.md`.
 - E2E: extend `scripts/e2e/test-ablegacy.ps1` with a String round-trip case (`-a "ST20:0" --type String`) and a `String` tag row in `scripts/smoke/seed-ablegacy-smoke.sql` so the bridge assertion exercises ST.
 **Effort**: S (mostly tests; small encoding fix if any)
 **Dependencies**: none
 ---
 ### Phase 3 — Performance
 #### PR 7 — Array contiguous block addressing (`N7:0,10` or `N7:0[10]`) (#9)
 **Scope**: One PCCC frame can pull up to ~120 words. Today every tag is a separate libplctag instance and a separate request. The fix exposes array tags as a single tag with `IsArray=true` + `ArrayDim`, backed by a libplctag tag with `elem_count=N`.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyAddress.cs` — record gains `ArrayCount` (nullable). Parser accepts `,N` suffix (Rockwell convention) and `[N]` suffix (libplctag convention) on the word number. Reject combination with sub-element or bit index.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriverOptions.cs` — `AbLegacyTagDefinition` gains optional `ArrayLength` (overrides parsed value; convenient when address is parameterised).
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/IAbLegacyTagRuntime.cs` — `AbLegacyTagCreateParams` gains `ElementCount` (default 1).
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/LibplctagLegacyTagRuntime.cs` — pass `ElementCount` to libplctag `Tag.ElementCount` (verify libplctag supports element counts on PCCC PlcTypes — it does for ab_eip CIP tags but PCCC may behave differently).
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs` — `DiscoverAsync` emits `IsArray=true`, `ArrayDim=[N]`; `ReadAsync` decodes via per-index `_tag.GetInt16(i*2)` etc.
 **Test plan**:
 - Unit: `N7:0,10` parses ArrayCount=10; `N7:0[10]` same; `N7:0,10/3` rejects (array+bit); `T4:0,5.ACC` rejects (array+sub-element).
 - Integration: read `N7:0,10` returns 10 elements in one frame; latency measurement vs 10 individual tags should be ≥ 5x faster (target).
 **Docs / fixture / e2e**:
 - Update `docs/Driver.AbLegacy.Cli.md` — add an "Array reads" section explaining `N7:0,10` vs `N7:0[10]` syntax and the per-PCCC-frame ~120-word ceiling, plus a `read --array-length 10 -a N7:0,10` CLI example.
 - Update `docs/drivers/AbLegacy-Test-Fixture.md` — list array-block reads under unit coverage and note the latency benchmark integration test as a new perf-flagged case.
 - Fixture: confirm `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/docker-compose.yml` `--tag=N7[10]` / `--tag=F8[10]` already provide enough contiguous words; otherwise bump array sizes (`N7[120]` to allow max-frame tests).
 - E2E: extend `scripts/e2e/test-ablegacy.ps1` with a `read -a "N7:0,10"` array assertion (parse comma-separated CLI output); add a matching `IsArray=1` tag row in `scripts/smoke/seed-ablegacy-smoke.sql` to exercise the address-space side.
 **Effort**: M
 **Dependencies**: PR 1 (octal applies to array index when the file is I/O on PLC-5)
 ---
 #### PR 8 — Per-tag deadband / change filter (#18)
 **Scope**: Today `PollGroupEngine` publishes every poll. Add absolute and percent deadband per tag — only emit `OnDataChange` when the new value differs by ≥ deadband.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriverOptions.cs` — `AbLegacyTagDefinition` gains `AbsoluteDeadband` (double?), `PercentDeadband` (double?).
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs` — wrap the `PollGroupEngine` callback with a per-tag last-published-value cache and the deadband test. Booleans bypass deadband (always change-on-edge). Strings + status changes always publish.
 - Verify: `PollGroupEngine` (in `Core.Drivers`) doesn't already centralise this — if it does, this PR threads the per-tag config through the engine instead of layering on top.
 **Test plan**:
 - Unit (new `AbLegacyDeadbandTests`): tag with `AbsoluteDeadband=1.0` reading `[10.0, 10.5, 11.5, 11.6]` publishes only `10.0` and `11.5`. Boolean tag publishes every transition. Status code change always publishes.
 - Quality: ensure last-value cache doesn't leak across `ReinitializeAsync`.
 **Docs / fixture / e2e**:
 - Update `docs/Driver.AbLegacy.Cli.md` — add a "Deadband" subsection under subscribe with `--deadband-absolute` / `--deadband-percent` CLI flags and example.
 - Update `docs/drivers/AbLegacy-Test-Fixture.md` — list `AbLegacyDeadbandTests` under unit coverage.
 - Fixture: no compose change required (per-tag deadband is a config-side concern, not a server simulator one).
 - E2E: extend `scripts/e2e/test-ablegacy.ps1` with a deadband subscribe assertion (subscribe with `--deadband-absolute 5`, write three small deltas, assert only one notification fires); add a tag row to `scripts/smoke/seed-ablegacy-smoke.sql` with `AbsoluteDeadband=5` to exercise the seed-from-config path.
 **Effort**: S
 **Dependencies**: none
 ---
 ### Phase 4 — Workflow
 #### PR 9 — Per-device timeout / retry overrides (#21)
 **Scope**: Replace single driver-wide `Timeout` with per-device override (SLC 5/01 needs ~5 s, SLC 5/05 fine at 2 s, ML1100 sometimes 3 s). Optional retry count per device.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriverOptions.cs` — `AbLegacyDeviceOptions` gains optional `Timeout`, `Retries`. `AbLegacyDriverOptions.Timeout` becomes the driver-wide default.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs` — `EnsureTagRuntimeAsync` and `ProbeLoopAsync` use `device.Options.Timeout ?? _options.Timeout`. `ReadAsync` retry loop honours `device.Options.Retries`.
 **Test plan**:
 - Unit: device with `Timeout=TimeSpan.FromSeconds(5)` propagates into `AbLegacyTagCreateParams.Timeout`; absent override falls back to driver-wide.
 - Integration: simulate a slow device (1 s artificial delay) — driver-wide 2 s passes; reducing per-device to 500 ms surfaces `BadCommunicationError` on the slow device while the fast device keeps reading.
 **Docs / fixture / e2e**:
 - Update `docs/Driver.AbLegacy.Cli.md` — document per-device `--timeout-ms` / `--retries` precedence vs driver-wide defaults; add a tuning cheat-sheet for SLC 5/01 vs 5/05 vs ML1100.
 - Update `docs/drivers/AbLegacy-Test-Fixture.md` — note per-device options under the AbLegacyDeviceOptions surface.
 - Fixture: no compose change. Add a slow-device test harness using a `tc qdisc add dev eth0 delay 1000ms` sidecar (or a Linux `iptables -j DELAY` shim) — document in `Docker/README.md` as an optional perf-tuning fixture.
 - E2E: no `test-ablegacy.ps1` change needed (per-device timeout is integration-test territory). Add a `Timeout=PT500MS` device-level row to `scripts/smoke/seed-ablegacy-smoke.sql` so the seed path exercises the new column.
 **Effort**: S
 **Dependencies**: none
 ---
 #### PR 10 — Diagnostic counters as tags (#20)
 **Scope**: Per-device diagnostic counters (request count, response count, retry count, last-error code, comm-failures) surface as auto-generated tags under `AbLegacy/<host>/_Diagnostics/*` so HMIs can bind directly. Mirrors what other drivers expose.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs` — `DeviceState` gains `Counters` (record of int64s). `ReadAsync`, `WriteAsync`, `ProbeLoopAsync` increment counters on success/failure paths. `DiscoverAsync` emits a `_Diagnostics` folder per device with seven Variables: `RequestCount`, `ResponseCount`, `ErrorCount`, `RetryCount`, `LastErrorCode`, `LastErrorMessage`, `CommFailures`.
 - New `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDiagnosticTags.cs` — generates the 7 well-known tag names; reading them returns counter snapshots from `DeviceState.Counters`.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs` `ReadAsync` short-circuits diagnostic tag references before dispatching to libplctag.
 **Test plan**:
 - Unit (new `AbLegacyDiagnosticsTests`): force 5 reads (3 success, 2 fail) → `RequestCount=5`, `ErrorCount=2`. `LastErrorCode` reflects the last libplctag status. Counters reset on `ReinitializeAsync`.
 - Quality: verify the 7 well-known names don't collide with user-config tag names (reject overlap at `InitializeAsync`).
 **Docs / fixture / e2e**:
 - New doc `docs/drivers/AbLegacy-Diagnostics.md` — the seven well-known counter tag names, their semantics, namespace convention (`_Diagnostics` folder per device), reset behaviour on `ReinitializeAsync`, and HMI binding examples.
 - Update `docs/Driver.AbLegacy.Cli.md` — note that diagnostic tags surface alongside user-config tags and can be `read --address _Diagnostics/RequestCount` (or whatever the canonical CLI shape ends up being).
 - Update `docs/drivers/AbLegacy-Test-Fixture.md` — list `AbLegacyDiagnosticsTests` and call out the collision-rejection contract.
 - Fixture: no compose change.
 - E2E: extend `scripts/e2e/test-ablegacy.ps1` with a "after N reads, RequestCount==N" assertion against the diagnostic NodeId published by the OPC UA server-bridge step; add a `_Diagnostics/RequestCount` Tag row to `scripts/smoke/seed-ablegacy-smoke.sql` if the addr-space team requires explicit registration.
 **Effort**: M
 **Dependencies**: none
 ---
 #### PR 11 — RSLogix 500 / PLC-5 symbol & data-table import (#15)
 **Scope**: Import RSLogix exports (`.RSS` Slc500, `.RSP` Plc5, `.SLC` text export) to seed `AbLegacyTagDefinition` entries. The binary `.RSS`/`.RSP` formats are proprietary and largely undocumented; the practical strategy is to support the `.SLC` / `.CSV` text exports that RSLogix can produce ("save as text" / "Database Export"). Verify whether libplctag or a sister project ships an `.RSS` parser — if not, scope to text exports only and document the binary case as a future enhancement.
 **Files**:
 - New `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/Import/RsLogixSymbolImport.cs` — parses RSLogix text export (CSV: `Symbol,Address,Description,DataType,Scope`).
 - New `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/Import/IRsLogixImporter.cs` — abstraction for future binary support.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriverFactoryExtensions.cs` — extension method `AddRsLogixImport(string path, string deviceHostAddress)` materialises `AbLegacyTagDefinition` entries from the file at startup-time.
 - New CLI command in `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Cli/` (mirrors AbCip CLI patterns — verify: confirm the AbLegacy CLI project layout): `import-rslogix --file foo.csv --device ab://... --emit appsettings-fragment`.
 **Test plan**:
 - Unit (new `RsLogixSymbolImportTests`): canonical CSV with one of each file letter (N/F/B/L/ST/T/C/R) generates 8 `AbLegacyTagDefinition` entries with correct `DataType`. Malformed rows skipped with logged warning. Comments and header rows skipped.
 - Integration: an end-to-end test with a recorded RSLogix CSV (committed under `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/Fixtures/`) produces an addr-space matching a golden snapshot.
 **Docs / fixture / e2e**:
 - New doc `docs/drivers/AbLegacy-RSLogix-Import.md` — supported export formats (CSV / .SLC text), CSV column convention, scope handling, the `import-rslogix` CLI subcommand, and the explicit non-goal of binary `.RSS`/`.RSP` parsing for v1.
 - Update `docs/Driver.AbLegacy.Cli.md` — add an `import-rslogix` subcommand row to the commands table with `--file foo.csv --device ab://... --emit appsettings-fragment` example.
 - Update `docs/DriverClis.md` if it carries a per-CLI command matrix.
 - Update `docs/drivers/AbLegacy-Test-Fixture.md` — list `RsLogixSymbolImportTests`, the new `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/Fixtures/` golden CSV, and the import-then-read integration scenario.
 - Fixture: new committed CSV under `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/Fixtures/rslogix-canonical.csv` plus the corresponding golden snapshot. No `Docker/docker-compose.yml` change.
 - E2E: extend `scripts/e2e/test-ablegacy.ps1` with an `import-rslogix` invocation that emits an appsettings fragment, then asserts the resulting tag count matches the CSV row count. No `seed-ablegacy-smoke.sql` change (importer is offline tooling).
 **Effort**: L (parser + CLI + golden-snapshot fixture)
 **Dependencies**: PR 1–5 complete (importer must produce addresses the parser accepts)
 ---
 ### Phase 5 — Resilience
 #### PR 12 — Auto-demote on comm failure (#13)
 **Scope**: When a device fails N consecutive reads/probes, mark it Demoted and skip its tags for `DemoteFor` seconds — so one slow PLC doesn't starve fast PLCs sharing the same driver/poll cadence.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriverOptions.cs` — new `AbLegacyDemoteOptions { FailureThreshold=3, DemoteFor=TimeSpan.FromSeconds(30), Enabled=true }` on `AbLegacyDeviceOptions`.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs` — `DeviceState` gains `ConsecutiveFailures`, `DemotedUntilUtc`. `ReadAsync` short-circuits demoted devices with `BadCommunicationError` until `DemotedUntilUtc`. `ProbeLoopAsync` clears demote on first success. New `HostState.Demoted` enum value (verify `HostState` is in `Core.Abstractions` and adding a member is non-breaking).
 - Diagnostic tags from PR 10 gain `DemoteCount` and `LastDemotedUtc`.
 **Test plan**:
 - Unit (new `AbLegacyAutoDemoteTests`): force 3 consecutive failures → device transitions to `Demoted`; reads while demoted return `BadCommunicationError` without invoking libplctag (verify via test fake counting `ReadAsync` calls). After `DemoteFor` expires, the next read attempt goes through.
 - Integration: two devices on the same driver, one with a fault — fault doesn't slow down the healthy one.
 **Docs / fixture / e2e**:
 - New doc `docs/drivers/AbLegacy-AutoDemote.md` (or a section appended to `AbLegacy-Diagnostics.md` from PR 10) — failure-threshold + demote-window semantics, interaction with the probe loop, the `HostState.Demoted` enum value, recovery path.
 - Update `docs/Driver.AbLegacy.Cli.md` — add `--demote-failure-threshold` / `--demote-for` per-device flags and document how `probe` reflects the Demoted state.
 - Update `docs/drivers/AbLegacy-Test-Fixture.md` — list `AbLegacyAutoDemoteTests` and the two-device fault-isolation integration case.
 - Fixture: extend `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/docker-compose.yml` with a second `slc500-faulty` service that listens on `:44819` but rejects every read (or doesn't bind, simulating ECONNREFUSED). The driver test then targets both `:44818` (healthy) and `:44819` (faulty) to exercise demotion.
 - E2E: extend `scripts/e2e/test-ablegacy.ps1` with a "kill simulator, observe demotion in `_Diagnostics/DemoteCount`" assertion (gated on PR 10's diagnostic tags being present). Add a `DemoteFor=PT30S` device row to `scripts/smoke/seed-ablegacy-smoke.sql`.
 **Effort**: M
 **Dependencies**: PR 10 (diagnostic counters)
 ---
 #### PR 13 — DH+ via 1756-DHRIO bridging (#2)
 **Scope**: Allow addressing a PLC-5 sitting on a DH+ link reached through a ControlLogix chassis with a 1756-DHRIO module. The CIP path syntax is `1,<slot>,2,<dh+_station_octal>` — already accepted as a string by `AbLegacyHostAddress`, but we should validate and document it, and verify libplctag's `plc5` PlcType resolves DH+ stations correctly through the DHRIO port.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyHostAddress.cs` — add validation for the DH+ path form `1,<slot>,2,<station>` where station is 0..77 octal. Surface the parsed components (`BackplaneSlot`, `DhPlusPort`, `DhPlusStation`) for diagnostics.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/PlcFamilies/AbLegacyPlcFamilyProfile.cs` — note that DH+ bridging is a `Plc5`-only path (DHRIO doesn't bridge to SLC/ML).
 - `docs/Driver.AbLegacy.Cli.md` — add a worked example of DHRIO routing.
 **Test plan**:
 - Unit (`AbLegacyHostAndStatusTests`): `ab://10.0.0.1/1,3,2,07` parses with slot=3, station=7₈=7. `ab://10.0.0.1/1,3,2,77` parses station=77₈=63. `ab://10.0.0.1/1,3,2,80` rejects (octal range).
 - Integration: requires a real DHRIO + PLC-5 — flag as hardware-gated; cover with unit-only for now and document the manual smoke procedure (`docs/Driver.AbLegacy.Cli.md`).
 **Docs / fixture / e2e**:
 - New doc `docs/drivers/AbLegacy-DH-Bridging.md` — the `1,<slot>,2,<station_octal>` CIP path syntax, DHRIO module wiring overview, octal-station-number reference (00..77 octal = 0..63), restriction to PLC-5 family, and the manual smoke procedure since DHRIO can't be simulated.
 - Update `docs/Driver.AbLegacy.Cli.md` — extend the family/cip-path cheat sheet with a "PLC-5 via DHRIO" row showing `ab://logix-host/1,3,2,07` and a worked CLI example. (Plan already calls this out at line 279 — keep it, but link to the new dedicated doc.)
 - Update `docs/drivers/AbLegacy-Test-Fixture.md` — note that DH+ bridging is unit-only (no fixture support possible) and reference the manual hardware smoke procedure.
 - Fixture: no `Docker/docker-compose.yml` change is feasible (DHRIO is hardware-only).
 - E2E: no new automated `test-ablegacy.ps1` case (would require real DHRIO). Add a `-DhPlusStation 7` parameter form documented in the script comment header for hardware-gated runs only. No `seed-ablegacy-smoke.sql` change.
 **Effort**: S
 **Dependencies**: PR 1 (octal parsing utility) — share the octal-int helper between PR 1 and PR 13.
 ---
 ## Documentation, fixture, and e2e impact
 Consolidated view of every doc, fixture, and e2e/smoke artefact this plan touches, so reviewers and PR authors can size the non-code surface area at a glance.
 ### New docs (created by this plan)
 | Doc | Created by | Purpose |
 |-----|-----------|---------|
 | `docs/drivers/AbLegacy-MicroLogix-FunctionFiles.md` | PR 2 | Function-file catalogue (RTC/HSC/DLS/MMI/PTO/PWM/STI/EII/IOS/BHI), per-family availability, sub-element types |
 | `docs/drivers/AbLegacy-Indirect-Addressing.md` | PR 4 | `N7:[N7:0]` and `N[N7:0]:5` syntax, depth-1 limit, libplctag strategy |
 | `docs/drivers/AbLegacy-Structure-Files.md` | PR 5 | PD / MG / PLS / BT sub-element catalogues + per-family availability matrix |
 | `docs/drivers/AbLegacy-Diagnostics.md` | PR 10 | Seven well-known counter tag names, namespace convention, reset semantics |
 | `docs/drivers/AbLegacy-RSLogix-Import.md` | PR 11 | CSV / `.SLC` text-export schema, `import-rslogix` CLI, binary-format non-goals |
 | `docs/drivers/AbLegacy-AutoDemote.md` (or PR 10 doc extension) | PR 12 | Demote thresholds, recovery, `HostState.Demoted` semantics |
 | `docs/drivers/AbLegacy-DH-Bridging.md` | PR 13 | `1,<slot>,2,<station_octal>` CIP path, DHRIO wiring, manual smoke procedure |
 ### Updated docs (extended by this plan)
 - `docs/Driver.AbLegacy.Cli.md` — extended by **every** PR (octal I/O, function files, sub-element bits, indirect, structure files, ST round-trip, array reads, deadband flags, per-device timeouts, diagnostic tags, RSLogix import subcommand, demote flags, DHRIO cheat-sheet row).
 - `docs/drivers/AbLegacy-Test-Fixture.md` — extended by **every** PR with new unit test classes, integration cases, and fixture limitations.
 - `docs/DriverClis.md` — touched by PR 11 (new `import-rslogix` subcommand row).
 - `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/README.md` — touched by PRs 1, 2, 4, 5, 9, 12 (fixture limitations, optional perf-tuning sidecars, faulty-device service, recipe-pattern note).
 ### Fixture / scaffolding work
 - `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/docker-compose.yml`:
  - PR 1: extend `plc5` profile with `I:001`-style tags (if `ab_server` accepts).
  - PR 2: extend `micrologix` profile with `RTC0[1]`/`HSC0[1]` (if accepted).
  - PR 3: extend `slc500` profile with `T4[5]`/`C5[5]`/`R6[5]` if not already seeded by `ab_server` defaults.
  - PR 5: extend `slc500` and `plc5` profiles with `PD9[2]`/`MG10[2]` (if accepted).
  - PR 6: extend `slc500` and `plc5` profiles with `ST20[5]`.
  - PR 7: bump array sizes (`N7[120]`) for max-frame array-read tests.
  - PR 12: add a second `slc500-faulty` service for demotion/fault-isolation tests.
 - `tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/Fixtures/`:
  - PR 11: new `rslogix-canonical.csv` + golden snapshot for the symbol-import integration test.
 ### E2E / smoke scripts
 - `scripts/e2e/test-ablegacy.ps1`:
  - PR 1: octal-bit `Plc5` assertion.
  - PR 2: `MicroLogix RTC:0.HR` parametric.
  - PR 3: Boolean sub-element read (`T4:0.DN`).
  - PR 4: indirect-address loopback.
  - PR 5: `PD9:0.SP` Float read (skip-gated).
  - PR 6: ST round-trip.
  - PR 7: array-read `N7:0,10`.
  - PR 8: deadband subscribe assertion.
  - PR 10: `_Diagnostics/RequestCount` assertion via OPC UA bridge.
  - PR 11: `import-rslogix` invocation + tag-count assertion.
  - PR 12: kill-simulator-and-observe-demote assertion.
  - PR 13: parameter-only header note for hardware-gated DHRIO runs.
 - `scripts/smoke/seed-ablegacy-smoke.sql`:
  - PR 3: `T4:0.DN` Boolean tag row.
  - PR 5: `PD9:0.SP` PidElement tag row (skip-gated).
  - PR 6: `ST20:0` String tag row.
  - PR 7: `N7:0,10` array tag row (`IsArray=1`).
  - PR 8: tag row with `AbsoluteDeadband=5`.
  - PR 9: device row with `Timeout=PT500MS`.
  - PR 10: `_Diagnostics/RequestCount` tag row (if explicit registration required).
  - PR 12: device row with `DemoteFor=PT30S`.
 ---
 ## Skip-rated items (for context)
 For traceability, the gaps the recommendations table flagged **No**:
 | # | Gap | Skip rationale |
 |---|-----|----------------|
 | 1 | Serial DF1 transports (full-duplex, half-duplex, KF2/KF3) | libplctag has no serial path; declining install base |
 | 3 | DH-485 routing (1761/1747-AIC) | Very legacy; rare in greenfield |
 | 4 | M0 / M1 module file access | Niche RIO modules; declining |
 | 6 | D (BCD) and Long-BCD types | Very legacy data convention |
 | 12 | Block read-size negotiation per family | libplctag handles chunking implicitly |
 | 14 | Channel-shared comm serialisation | Only matters for serial / DH+ transport (not built) |
 | 16 | Online controller browse / data-table discovery | PCCC dir frame limited; libplctag support unclear |
 | 17 | DF1 BCC vs CRC-16 selection | Predicated on DF1 transport (gap #1) |
 | 19 | PLC-5 typed-read selection / Force Logical | libplctag defaults are sound; niche tuning |
 | 22 | Write completion semantics options | Niche tuning; current write-through is safe default |
 These remain documented in `featuregaps.md` and can be reopened if customer feedback warrants.
 ---
 ## Open questions
 1. **libplctag PCCC capability verification** — several PRs (especially 2, 4, 5, 7) hinge on what libplctag's `slc500` / `micrologix` / `plc5` / `logixpccc` PlcTypes actually accept in the `Name` attribute. Before scheduling Phase 2 we should run a one-day spike with the AbLegacy simulator to confirm:
   - Does libplctag accept indirect addresses (`N7:[N7:0]`) verbatim, or do we need to resolve in two steps?
   - Does it accept array notation (`N7:0,10` vs `N7:0[10]`) for PCCC PlcTypes?
   - Does it expose PD/MG/PLS/BT sub-elements by name, or do we read the parent struct as a byte block?
   - Does it correctly handle PLC-5 octal in I:/O: addresses, or does the driver need to convert?
 2. **MicroLogix simulator fidelity** — we don't currently know whether the AbLegacy integration-test fixture (`AbLegacyServerFixture`) simulates the MicroLogix function files (RTC/HSC/DLS). PR 2's integration coverage is gated on this. If not, we either extend the fixture or scope PR 2 to unit-only tests + a hardware smoke-test playbook.
 3. **RSLogix import format coverage** — binary `.RSS` / `.RSP` parsing is non-trivial. PR 11 scopes to text/CSV exports. Should we instead invest in shelling out to the (free) Rockwell `RSWho` / `RSLogix Emulate` tooling for binary conversion, or accept text-only as the v1 scope and revisit?
 4. **Address-space rebuild on tag-set change** — when PR 11 (RSLogix import) adds 1000+ tags, does `ReinitializeAsync` perform acceptably, or do we need an incremental discovery path? Out of scope for this plan but worth flagging.
 5. **Diagnostic tag namespace collision** — PR 10 reserves `_Diagnostics` under each device folder. Confirm with the address-space team that the leading underscore is the established convention (other drivers use `_System` or `_DiagnosticTags`); align before implementation.
--- a/docs/plans/focas-plan.md
+++ b/docs/plans/focas-plan.md
@@ -0,0 +1,807 @@
 # FOCAS Driver — Implementation Plan
 > Source of gap analysis: [featuregaps.md → FOCAS](../featuregaps.md#focas-fanuc-cnc)
 >
 > Covers Build = Yes items only.
 ## Summary
 The FOCAS driver today is a pure-managed, read-only FOCAS/2 wire client
 (`src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Wire/`) backing a fixed-tree projection
 plus user-authored `PARAM:` / `MACRO:` / PMC tags. It exposes a thin set of
 calls (`cnc_sysinfo`, `cnc_rdcncstat`, `cnc_rdaxisname`, `cnc_rdspdlname`,
 `cnc_rddynamic2`, `cnc_rdsvmeter`, `cnc_rdspload`, `cnc_rdspmaxrpm`,
 `cnc_exeprgname2`, `cnc_rdblkcount`, `cnc_rdopmode`, `cnc_rdtimer`,
 `cnc_rdparam`, `cnc_rdmacro`, `pmc_rdpmcrng`, `cnc_rdalmmsg2`).
 The featuregaps table marks **18** items as Build = Yes. They cluster into
 five distinct workstreams:
 1. **Phase 1 — fixed-tree expansion** (#6, #7, #8, #10, #11, #12, #13, #14,
   #18, #20, #24, #27). These are mostly new wire calls plumbed into the
   existing `FixedTree*` poll cadences; no architectural change.
 2. **Phase 2 — addressing additions** (#4, #14 DIAG scheme, #15, #16). New
   `FocasAreaKind` values, new capability-matrix entries, multi-path
   `PathId`. Touches the parser + matrix + wire envelope; mostly additive.
 3. **Phase 3 — alarm history** (#17). Extends the existing
   `FocasAlarmProjection` with a one-shot history pull on connect plus
   periodic delta polls.
 4. **Phase 4 — write path** (#1, #3). The biggest behavioural change in
   the driver's lifetime: removes the `BadNotWritable` short-circuit, adds
   `cnc_wrparam` / `pmc_wrpmcrng` / `cnc_wrmacro` plus FOCAS password
   handling. Material risk surface — see Risks.
 5. **Phase 5 — derived telemetry** (#24 cycle-delta computation). Optional
   companion to #24 raw cycle time; computes "last completed cycle" from
   the existing cumulative `Cycle` timer.
 DIAG (#14) is in Phase 2 (addressing) rather than Phase 1 because it
 needs a new address scheme, but the fixed-tree status flag projection
 (#12) is the cheapest item and should land first as a vertical slice.
 The remaining 9 items in the featuregaps table (HSSB, Series 15 / 35i,
 tool-offset write, program upload/download, DPRNT, deep servo info,
 acceleration/jerk, operator preset commands, NTP) are scoped out as
 Build = No; they appear in [Skip-rated items](#skip-rated-items-for-context)
 for context only.
 ## Phased delivery
 | Phase | Scope | Gaps closed | Approx PRs | Risk |
 |-------|-------|-------------|------------|------|
 | 1 | Fixed-tree expansion (read-only) | 12, 13, 7, 8, 10, 11, 20, 18, 6, 24, 27, 14 (read-only piece) | 6 | Low |
 | 2 | Addressing additions | 4, 15, 16, 14 (DIAG: scheme) | 4 | Medium (multi-path) |
 | 3 | Alarm history | 17 | 1 | Low |
 | 4 | Write path + password | 1, 3 | 4 | High (read-only design choice removed) |
 | 5 | Cycle-delta derived telemetry | 24 (delta companion) | 1 | Low |
 Phases 1–3 are mutually independent and can ship in any order. Phase 4
 deliberately follows Phase 2 so writes ride on top of the multi-path
 addressing already in place. Phase 5 tags onto the cycle-time node from
 Phase 1.
 ## Per-PR detail
 ### Phase 1 — fixed-tree expansion
 Common shape: each PR adds one or more wire calls in
 `Wire/FocasWireClient.cs`, surfaces them on `IFocasClient`, plumbs them
 into `FocasDriver`'s `FixedTreeLoopAsync` cadences (axis 250 ms / program
 1 s / timer 30 s) and the `TryReadFixedTree` synthesizer, then adds
 fakes + assertions.
 **PR F1-a — ODBST status flags as fixed-tree nodes (#12)**
 - Scope: project the 9 fields of `cnc_rdcncstat` (`tmmode`, `aut`, `run`,
  `motion`, `mstb`, `emergency`, `alarm`, `edit`, `dummy`) under
  `Status/` per device. We already issue this call in `ProbeAsync`; this
  PR keeps the boolean probe but additionally caches the full struct on
  every poll tick.
 - Files:
  `Wire/FocasWireClient.cs` (extend `ReadStatusAsync` to return the
  whole `WireStatus` rather than only `IsOk`), `IFocasClient.cs` (new
  `GetStatusAsync`), `FocasDriver.cs` (new `Status/*` branch in
  `TryReadFixedTree`, status cache on `DeviceState`).
 - Tests:
  `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FocasFixedTreeStatusTests.cs`
  (new) — `FakeFocasClient` returns canned ODBST, assert each field maps
  to the expected `Status/*` browse name. Integration: extend
  `FocasSimFixture` to seed the simulator's status response and assert
  via the OPC UA client.
 - **Docs / fixture / e2e**: extend `docs/drivers/FOCAS.md` fixed-tree
  table with the 9 `Status/*` nodes; mention the boolean-probe →
  full-struct change in `docs/drivers/FOCAS-Test-Fixture.md` integration
  bullet list; teach `focas-mock` (under
  `tests/.../IntegrationTests/Docker/focas-mock/`) the `cnc_rdcncstat`
  payload shape per `docs/v2/implementation/focas-wire-protocol.md`
  (add ODBST struct entry); extend `FocasSimFixture` with a helper to
  patch the canned status payload; new
  `Series/StatusFlagsPopulateTests.cs` integration test.
 - Effort: small; one wire call already exists.
 - Risk: Low.
 **PR F1-b — parts count + cycle time (#13, #24 raw)**
 - Scope: surface `cnc_rdparam(6711)` (parts produced), `6712` (parts
  required), `6713` (parts total since power-on) under `Production/`,
  plus `Production/CycleTimeSeconds` (already exposed as
  `Timers/CycleSeconds` — promote to the `Production/` group too with
  the same backing). The existing `cnc_rdtimer` call is sufficient.
 - Files: `FocasDriver.cs` (`Production/*` branch, parameter-cached
  reads on the timer poll cadence), `IFocasClient.cs` (no new call —
  rides on `ReadParameterInt32Async`).
 - Tests: `FakeFocasClient` returns canned parameter values; assert
  `Production/PartsTotal` equals the canned value.
 - **Docs / fixture / e2e**: add `Production/*` rows to the fixed-tree
  table in `docs/drivers/FOCAS.md`; add `Production:` example to
  `docs/Driver.FOCAS.Cli.md` (a `read -a PARAM:6711` snippet); the
  parts-count parameters (6711/6712/6713) are already in the
  simulator profile range, so only the `dl205`-style profile JSON
  under `tests/.../Docker/focas-mock/profiles/` needs seeded values
  added; extend `FocasSimFixture` with a `SeedPartsCount` helper;
  integration test under `Series/ProductionPopulatesTests.cs`.
 - Effort: small.
 - Risk: Low.
 **PR F1-c — modal G/M/T codes (#7) + override values (#11)**
 - Scope: add `cnc_modal` (command id TBD per `fwlib32.h` — the wire
  protocol uses the same numeric command convention seen in
  `FocasWireClient`; capture during simulator iteration). Project:
  `Modal/G_Group{n}` (groups 1..21), `Modal/MCode`, `Modal/SCode`,
  `Modal/TCode`, `Modal/BCode`. Adds `Override/Feed`, `Override/Rapid`,
  `Override/Spindle`, `Override/Jog` from `cnc_rdparam(...)` — the
  override percent registers live at known parameter numbers; numbers
  are MTB-specific so pull defaults from
  `docs/v2/focas-version-matrix.md` and let operators override per device.
 - Files: `Wire/FocasWireClient.cs` (new `ReadModalAsync`), new
  `Wire/FocasWireModels.cs` records `WireModal` / `WireModalGroup`,
  `IFocasClient.cs` (new `GetModalAsync`), `FocasDriver.cs` (new
  poll-medium branches under the program-poll cadence).
 - Tests: `FocasModalTests.cs` (unit), simulator handler returns canned
  modal payload, integration asserts `Modal/G_Group1` text.
 - **Docs / fixture / e2e**: add `Modal/*` and `Override/*` sections to
  the fixed-tree table in `docs/drivers/FOCAS.md`, including the
  G-group decode table for groups 01/03/06/07/14; add a `MODAL:`
  address example row to `docs/Driver.FOCAS.Cli.md` (new `read -a
  MODAL:G1` style — note: this PR does NOT add a new address scheme,
  the modal data is fixed-tree only, so the CLI example reads via
  `read -n "ns=2;s=Modal/G_Group1"` over the OPC UA endpoint);
  document MTB-specific override register defaults in
  `docs/v2/focas-version-matrix.md` (new `Override registers per
  series` table); capture the `cnc_modal` command id resolved during
  simulator iteration into `docs/v2/implementation/focas-wire-protocol.md`
  (new struct entry — promote out of the open-questions list);
  update `docs/v2/implementation/focas-simulator-plan.md` Stream C
  protocol-surface table with the new `cnc_modal` handler;
  extend focas-mock with a `cnc_modal` command-id handler + canned
  modal payload per profile; integration test reading G54/G90 modal
  state via `Series/ModalPopulatesTests.cs`.
 - Effort: medium — `cnc_modal` returns a multi-group struct; encoding
  needs care.
 - Risk: Medium — modal-group numbering varies by series; treat the
  raw integer as the value the CNC reports and surface a string
  decode table only for the universally-present groups (G-group 01
  motion, 03 absolute/incremental, 06 input units, 07 cutter comp,
  14 work coordinate). Document MTB-specific groups as raw int.
 **PR F1-d — tool number / tool life (#8) + work coordinate offsets (#10)**
 - Scope: add `cnc_rdtofs` / `cnc_rdtlife*` / `cnc_rdzofs`. Project
  `Tooling/CurrentTool`, `Tooling/CurrentOffset`,
  `Tooling/Life/{group}/Remaining`, `Tooling/Life/{group}/Total`,
  `Offsets/G54..G59[+ extended]/{X,Y,Z}`.
 - Files: new wire calls in `Wire/FocasWireClient.cs` (`ReadToolOffsetAsync`,
  `ReadToolLifeAsync`, `ReadWorkOffsetAsync`), `Wire/FocasWireModels.cs`
  (records), `IFocasClient.cs`, `FocasDriver.cs` (new `Tooling/` and
  `Offsets/` branches; both poll on the slow timer cadence — these
  change at setup time, not per-cycle), capability matrix per-call
  suppression like the existing `Spindle/` gating.
 - Tests: unit + simulator. Tool-life is the largest payload; assert
  array projection rather than per-tool nodes (one ValueRank=1 array
  per group keeps the address-space size bounded on machines with
  500+ tool slots).
 - **Docs / fixture / e2e**: add `Tooling/*` and `Offsets/*` sections to
  the fixed-tree table in `docs/drivers/FOCAS.md`, including the
  ValueRank=1 array note for tool-life groups; add a per-series
  capability-suppression row to `docs/v2/focas-version-matrix.md`
  (which series support `cnc_rdtlife*` vs not); document the three
  new structs (`ODBTOFS`, `ODBTLIFE5`, `IODBZOR`) in
  `docs/v2/implementation/focas-wire-protocol.md`; add
  `cnc_rdtofs` / `cnc_rdtlife*` / `cnc_rdzofs` rows to the protocol
  surface table in `docs/v2/implementation/focas-simulator-plan.md`;
  extend focas-mock with three new command-id handlers + per-profile
  seed data (tool table + work-offset table); add a
  `tools_per_series` matrix to the `focas-mock` per-series profile
  JSON so 0i-D's small tool table differs from 30i's; new
  `Series/ToolingPopulatesTests.cs` and `Series/OffsetsPopulatesTests.cs`
  integration tests; update `docs/drivers/FOCAS-Test-Fixture.md`
  coverage map with the three new wire calls.
 - Effort: large — three new calls, each with its own struct; tool-life
  is variable-length.
 - Risk: Medium — payload shapes are series-specific; keep the
  capability matrix as the authoritative gate.
 **PR F1-e — operator messages (#18) + currently-executing block text (#20)**
 - Scope: `cnc_rdopmsg3` (gives all four FANUC opmsg classes in one
  call), `cnc_rdactpt` (current block text). Project `Messages/External`
  (variable, last-N strings), `Program/CurrentBlock` (single string).
 - Files: `Wire/FocasWireClient.cs` (`ReadOperatorMessagesAsync`,
  `ReadCurrentBlockAsync`), `IFocasClient.cs`, `FocasDriver.cs` (new
  branches under program-poll cadence).
 - Tests: simulator returns canned ASCII; assert string round-trip is
  trim-stable (FANUC right-pads with `\0` or space).
 - **Docs / fixture / e2e**: add `Messages/External` and
  `Program/CurrentBlock` rows to the fixed-tree table in
  `docs/drivers/FOCAS.md`, including the ring-buffer / last-N
  semantics for opmsg; document the `OPMSG3` and `ODBACT2`
  payload shapes in `docs/v2/implementation/focas-wire-protocol.md`;
  add `cnc_rdopmsg3` / `cnc_rdactpt` rows to the protocol surface
  table in `docs/v2/implementation/focas-simulator-plan.md`; extend
  focas-mock with the two new command-id handlers (per-profile
  canned message text + canned current-block text); add a
  `mock_patch_opmsg` admin endpoint hook on `FocasSimFixture` for
  tests that need to push a canned message; integration test
  `Series/OperatorMessagesPopulateTests.cs` asserts trim-stable
  round-trip and last-N retention.
 - Effort: medium.
 - Risk: Low — ASCII-only payloads.
 **PR F1-f — `cnc_getfigure` decimal scaling (#6) + connection statistics (#27)**
 - Scope: `cnc_getfigure` returns per-axis decimal-place counts; cache
  the result at bootstrap and divide each `AbsolutePosition` /
  `MachinePosition` / `RelativePosition` / `DistanceToGo` /
  `ActualFeedRate` value before publishing. Existing nodes already
  carry `Float64`; the change is invisible to clients except that
  values become real-world units. Adds `Diagnostics/` subtree:
  `Diagnostics/ReadCount`, `Diagnostics/ReadFailureCount`,
  `Diagnostics/LastErrorMessage`, `Diagnostics/LastSuccessfulRead`,
  `Diagnostics/ReconnectCount` — driven by counters already maintained
  on `DeviceState`.
 - Files: `Wire/FocasWireClient.cs` (new `ReadFigureAsync`),
  `IFocasClient.cs`, `FocasDriver.cs` (cache decimal places per axis,
  multiply on the read path, expose counters under `Diagnostics/`).
 - Tests: assert that with a canned `cnc_getfigure` returning 3, an
  `AbsolutePosition` of 12345 becomes `12.345`. Connection-stat tests
  assert counters increment under known conditions.
 - **Docs / fixture / e2e**: significant `docs/drivers/FOCAS.md` change —
  add a "Decimal-place scaling" subsection explaining the
  `FixedTree.ApplyFigureScaling` flag (default true on new installs,
  false on migrations) and the unit-correctness semantics it enforces;
  add `Diagnostics/*` rows to the fixed-tree table; add a
  Diagnostics-counters subsection to `docs/v2/focas-deployment.md`
  for operator dashboards; document `cnc_getfigure` (`ODBAXDP` /
  `ODBAXIS`) struct in `docs/v2/implementation/focas-wire-protocol.md`;
  add `cnc_getfigure` to the protocol surface in
  `docs/v2/implementation/focas-simulator-plan.md`; extend focas-mock
  with the per-axis decimal-place command handler + a `decimal_places`
  field on each profile JSON; update
  `docs/drivers/FOCAS-Test-Fixture.md` "When to trust each layer"
  table with a "Are axis values reported in real-world units?" row;
  add an opt-in `-CheckDecimalScaling` switch to `scripts/e2e/test-focas.ps1`
  that asserts AbsolutePosition is scaled when the flag is on;
  integration test `Series/DecimalScalingTests.cs` and
  `Series/DiagnosticsCountersTests.cs`.
 - Effort: medium — touches every axis read.
 - Risk: Medium — this is a behavioural change for any existing
  consumer that was already dividing client-side. Surface as a
  `FixedTree.ApplyFigureScaling` opt-in flag (default true on new
  installs, false when migrating); document in `docs/drivers/FOCAS.md`.
 ### Phase 2 — addressing additions
 **PR F2-a — DIAG: address scheme (#14)**
 - Scope: new `FocasAreaKind.Diagnostic` parsed from `DIAG:nnn` /
  `DIAG:nnn/axis`, dispatched to `cnc_rddiag` (or `cnc_rddiagdgn` for
  series that support it).
 - Files: `FocasAddress.cs` (new prefix branch), `FocasCapabilityMatrix.cs`
  (new `DiagnosticRange` per series), `Wire/FocasWireClient.cs`
  (`ReadDiagnosticAsync`), `WireFocasClient.ReadAsync` (new dispatch
  branch).
 - Tests: parser unit tests, capability matrix unit tests, simulator
  read-round-trip.
 - **Docs / fixture / e2e**: add a `DIAG:` row to the address-syntax
  table in `docs/Driver.FOCAS.Cli.md` with `read -a DIAG:301` and
  `DIAG:301/0` (axis-scoped) examples; add a `DIAG:` row to the
  addressing table in `docs/drivers/FOCAS.md`; add per-series
  `DiagnosticRange` columns to `docs/v2/focas-version-matrix.md`;
  document the `ODBDGN` struct in
  `docs/v2/implementation/focas-wire-protocol.md`; add `cnc_rddiag`
  / `cnc_rddiagdgn` to the protocol surface in
  `docs/v2/implementation/focas-simulator-plan.md`; extend focas-mock
  with the diagnostic-range command handler + per-profile seeded
  diagnostic numbers; integration test
  `Series/DiagAddressTests.cs` round-trips a seeded diagnostic
  number; update `docs/drivers/FOCAS-Test-Fixture.md` capability list
  with the new `Diagnostic` `FocasAreaKind`.
 - Effort: medium.
 - Risk: Low — additive.
 **PR F2-b — Multi-path / multi-channel CNC (#4)**
 - Scope: 30i/31i/32i can host 2–10 paths; today every request block is
  built with `PathId = 1` (`Wire/FocasWireProtocol.cs:216`). Add
  optional `Path` segment to `FocasAddress` (e.g. `PARAM:1815@2`,
  `R100@3.0`, `MACRO:500@2`); thread it into the `RequestBlock.PathId`
  field. Fixed-tree gets a `Paths/{n}/` folder pivot.
 - Files: `FocasAddress.cs` (new `Path` field + parser), `IFocasClient.cs`
  (every read call gains an optional `pathId` parameter, defaulting to
  1 for backward compatibility), `Wire/FocasWireClient.cs`
  (thread the param through every `RequestBlock` constructor),
  `FocasDriver.cs` (per-device `PathCount` discovery via
  `cnc_rdpathnum`; iterate fixed-tree per path).
 - Tests: unit on the parser; simulator with two paths configured;
  assert that a `PARAM:1815@2` read targets path 2.
 - **Docs / fixture / e2e**: significant `docs/drivers/FOCAS.md`
  update — new "Multi-path / multi-channel CNC" subsection explaining
  the `@N` suffix syntax, `Paths/{n}/` browse pivot, and per-path
  capability gating; add `@N` to every address row in the
  addressing table in `docs/Driver.FOCAS.Cli.md`; document
  `cnc_rdpathnum` (`ODBPATHNUM` struct) in
  `docs/v2/implementation/focas-wire-protocol.md`, and update the
  `RequestBlock.PathId` discussion (was hard-coded to 1 — now a
  parameter); add `cnc_rdpathnum` to the protocol surface and the
  per-profile `path_count` field to the profile schema in
  `docs/v2/implementation/focas-simulator-plan.md`; extend focas-mock
  with per-path state isolation (separate PMC / param / macro tables
  per `path_id`) and a new `multi_path` profile (e.g.
  `thirtyone_i_dual_path`); add a `-Paths` switch to
  `scripts/e2e/test-focas.ps1` that runs the matrix once per
  declared path; document the new compose profile in
  `docs/drivers/FOCAS-Test-Fixture.md`; new
  `Series/MultiPathTests.cs` integration test asserting independent
  per-path reads.
 - Effort: large — touches every wire call's `RequestBlock` shape.
 - Risk: Medium — backward compatibility for existing single-path
  configs. Default `PathId = 1` everywhere; only deviate when the
  address explicitly carries a `@N` suffix or when the fixed-tree
  loop is iterating discovered paths.
 **PR F2-c — PMC F/G letters for 16i (#15)**
 - Scope: capability matrix bug — `PmcLetters(Sixteen_i)` currently
  returns `{X, Y, R, D}`; real 16i ladders use F/G for handshakes.
  Widen the set; verify the address `pmc_rdpmcrng` numeric letter
  codes match.
 - Files: `FocasCapabilityMatrix.cs` (one-line fix to the 16i case),
  `tests/.../FocasCapabilityMatrixTests.cs` (assert F0.0 and G50.5
  parse against `Sixteen_i`).
 - **Docs / fixture / e2e**: update the 16i row of the PMC-letters
  column in `docs/v2/focas-version-matrix.md` (the row currently lists
  X/Y/R/D — add F/G); add a one-line "fixed in v…" callout to the
  changelog section of the same doc; no simulator change required (the
  16i profile JSON in `tests/.../Docker/focas-mock/profiles/sixteen_i.json`
  already has F/G ranges declared from Stream B); add F0.0 / G50.5
  probes to the 16i row of the per-series matrix in
  `scripts/e2e/test-focas.ps1`; no fixture-doc change needed.
 - Effort: trivial.
 - Risk: Low — correctness fix.
 **PR F2-d — Bulk PMC range read (#16)**
 - Scope: today the driver issues one `pmc_rdpmcrng` per tag (one TCP
  RTT each). The wire call already supports a range `[start, end]`;
  the missing piece is coalescing on the read side. Add a coalescer:
  group same-letter contiguous (or near-contiguous within a small
  gap budget) PMC bytes from the request batch into one wire call
  per group, then slice client-side. Reuse the Modbus coalescing
  infrastructure pattern (per-group-id ProhibitedRanges) where it
  applies.
 - Files: new `Wire/FocasPmcCoalescer.cs`, hook into
  `FocasDriver.ReadAsync` between the per-tag path and the wire call
  layer. Surface coalesce stats on the `Diagnostics/` subtree (PR F1-f).
 - Tests: unit — given a request batch of `R100..R110`, assert that
  the coalescer issues one call covering 100..110 and slices the
  result. Integration — assert observed wire-call count drops with
  coalescing on.
 - **Docs / fixture / e2e**: add a "PMC range coalescing" subsection
  to `docs/drivers/FOCAS.md` (wire-call reduction, gap budget,
  per-series byte cap); document the new `Diagnostics/CoalesceStats/*`
  counters added on top of PR F1-f's diagnostics tree; add a
  PMC-byte-cap column to `docs/v2/focas-version-matrix.md`;
  no new wire calls (`pmc_rdpmcrng` is already in the surface), but
  document the supported max-bytes-per-call in
  `docs/v2/implementation/focas-wire-protocol.md`; extend focas-mock
  with a request-counter admin endpoint so integration tests can
  assert the call-count reduction (counter visible via
  `FocasSimFixture.GetWireCallCountAsync`); update
  `docs/v2/implementation/focas-simulator-plan.md` Stream B
  validation harness with the request-counter handler; integration
  test `Series/PmcCoalescingTests.cs` asserts an `R100..R110` batch
  produces exactly 1 wire call against the mock.
 - Effort: medium.
 - Risk: Medium — the FANUC max-bytes-per-`pmc_rdpmcrng` ceiling is
  series-specific; cap conservatively (≤ 256 bytes per range) and
  let operators raise it via config if their CNC accepts more.
 ### Phase 3 — alarm history
 **PR F3-a — `cnc_rdalmhistry` extension to alarm projection (#17)**
 - Scope: extend `FocasAlarmProjection` with two modes — `ActiveOnly`
  (today's behaviour) and `ActivePlusHistory`. In the latter, on
  connect (and on a configurable cadence — default 5 min, since the
  CNC ring buffer changes only on alarm raise/clear) issue
  `cnc_rdalmhistry` for the most-recent N entries; project as
  historic events through `IAlarmSource` with `OccurrenceTime` from
  the CNC's timestamp field.
 - Files: new `Wire/FocasWireClient.ReadAlarmHistoryAsync`, new
  `IFocasClient.ReadAlarmHistoryAsync`,
  `FocasAlarmProjection.cs` (mode switch + history poll loop),
  `FocasDriverOptions.cs` (`AlarmProjection.Mode` enum +
  `HistoryPollInterval` + `HistoryDepth`).
 - Tests: simulator returns canned history payload; assert events
  fire with the timestamps from the canned data and don't re-fire
  on every poll.
 - **Docs / fixture / e2e**: add an "Alarm history" subsection to
  `docs/drivers/FOCAS.md` documenting the `ActiveOnly` vs
  `ActivePlusHistory` mode switch, the `HistoryDepth` cap, and the
  dedup key; add a configuration-knob row to
  `docs/v2/focas-deployment.md` for operator dashboards; document
  `ODBALMHIS` struct in
  `docs/v2/implementation/focas-wire-protocol.md`; add
  `cnc_rdalmhistry` to the protocol surface in
  `docs/v2/implementation/focas-simulator-plan.md`; extend focas-mock
  with a ring-buffer alarm history (per profile) + `mock_patch_alarmhistory`
  admin endpoint; expose a `SeedAlarmHistoryAsync` helper on
  `FocasSimFixture`; add `Series/AlarmHistoryProjectionTests.cs`
  asserting historic events fire once and active events still fire
  raise/clear; update `docs/drivers/FOCAS-Test-Fixture.md` integration
  bullet list with `cnc_rdalmhistry`.
 - Effort: medium.
 - Risk: Medium — duplicate-event suppression; key history events on
  `(timestamp, alarmNumber, type)` to deduplicate against the active
  list.
 ### Phase 4 — write path
 This phase is the major behavioural change. The driver's read-only
 contract has been the documented design choice in
 `docs/drivers/FOCAS.md:14-18` and is reinforced by tests
 (`FocasReadWriteTests.WriteAsync_ReturnsBadNotWritable`). Removing it
 deserves a deliberate decision-record entry in the v2 decisions log
 before any code lands.
 **PR F4-a — write infrastructure + per-tag opt-in (no wire calls yet)**
 - Scope: drop the `BadNotWritable` short-circuit in
  `WireFocasClient.WriteAsync` and replace with a kind-based dispatch
  that returns `BadNotWritable` only for kinds the wire client
  doesn't yet implement. Honour `FocasTagDefinition.Writable` (already
  present, default `true` — flip default to `false` per #1's safer
  posture). Plumb `WriteIdempotent` through Polly retry.
 - Files: `WireFocasClient.cs`, `FocasDriverOptions.cs`,
  `FocasDriver.cs`, `docs/drivers/FOCAS.md` (rewrite the read-only
  paragraph), new `docs/v2/decisions.md` entry.
 - Tests: assert that with `Writable=false` the path still returns
  `BadNotWritable`; with `Writable=true` and an unimplemented kind
  the write returns `BadNotSupported` (distinct from the per-tag
  policy denial).
 - **Docs / fixture / e2e**: this is the heaviest doc PR in the plan.
  - **`docs/drivers/FOCAS.md` lines 14–18** — revoke the unconditional
    "OtOpcUa is read-only against FOCAS… Writes return BadNotWritable
    by design" callout. Replace with a "Writes (opt-in, off by
    default)" subsection that names `Writes.Enabled`, the per-tag
    `Writable` flag (default flipped to `false`), and links to the
    Phase 4 decision-record entry.
  - **`docs/drivers/FOCAS-Test-Fixture.md` lines 42–43** — revoke the
    "`IWritable` intentionally returns `BadNotWritable` — OtOpcUa is
    read-only against FOCAS" callout. Replace with a qualified
    "default behaviour" note plus a pointer to the new write-enabled
    test profile.
  - **`docs/Driver.FOCAS.Cli.md` lines 100–116** — the existing
    `write` section already documents the CLI shape; expand the
    "**Writes are non-idempotent by default**" warning with a
    server-side note that the OtOpcUa endpoint enforces the
    `Writes.Enabled` flag and rejects writes when off, and that
    the CLI itself talks to the driver directly so its writes are
    not gated by the server flag (operator must consciously use
    the right tool).
  - New `docs/v2/decisions.md` entry "FOCAS write-path opt-in"
    capturing the design-choice reversal.
  - Update `docs/featuregaps.md` row for #1 / #3 — flip Build = Yes
    annotation to "shipping behind flag".
  - Simulator: no new commands; existing read commands gain a
    "writes when not unlocked" branch wired up here for symmetry
    even though no write commands ship yet (returns
    `BadNotSupported` until F4-b lands).
  - E2E: add `-Write` switch (no-op stage in this PR; populated by
    F4-b) to `scripts/e2e/test-focas.ps1`.
 - Effort: medium.
 - Risk: High — design-choice reversal. Mitigation: ship behind a
  driver-level `Writes.Enabled` flag (default `false`); operators
  must explicitly enable in `appsettings.json`.
 **PR F4-b — `cnc_wrmacro` + `cnc_wrparam`**
 - Scope: implement macro and parameter writes. Both have well-defined
  payload shapes mirroring their read counterparts (IODBPSD for
  parameters, ODBM for macros).
 - Files: `Wire/FocasWireClient.cs` (new `WriteParameterAsync`,
  `WriteMacroAsync`), `WireFocasClient.WriteAsync` (dispatch).
 - Tests: simulator extension — accept writes and reflect them on
  subsequent reads. ACL tests in
  `tests/ZB.MOM.WW.OtOpcUa.IntegrationTests` to verify the
  server-layer enforcement (per the memory entry: ACL decisions
  happen in `DriverNodeManager`, never in driver-level code).
 - **Docs / fixture / e2e**:
  - `docs/drivers/FOCAS.md` — extend the "Writes" subsection
    (introduced in F4-a) with the two new write kinds, the
    `Writes.AllowParameter` and `Writes.AllowMacro` granular flags,
    and a security note: parameter writes require LDAP group
    `WriteConfigure`, macro writes require `WriteOperate` (cross-link
    to `docs/Security.md`).
  - `docs/v2/focas-deployment.md` — significant addition: a "Write
    safety" section covering operator pre-checks (CNC in MDI mode,
    parameter-write switch enabled), audit-log expectations, and the
    LDAP group requirements.
  - `docs/Driver.FOCAS.Cli.md` — populate the existing `write`
    examples for `PARAM:` and `MACRO:` (already present at lines
    105–108) with a "Server-enforced ACL" note linking to
    `docs/Security.md`.
  - Document `IODBPSD` (write side) and `ODBM` (write side) in
    `docs/v2/implementation/focas-wire-protocol.md` (the read-side
    structs are already there — flag the byte layout symmetry).
  - `docs/v2/implementation/focas-simulator-plan.md` — add
    `cnc_wrparam` / `cnc_wrmacro` to the protocol surface table
    and update Stream C status accordingly.
  - Extend focas-mock with `cnc_wrparam` / `cnc_wrmacro` handlers
    that mutate the per-profile state and return
    `EW_PASSWD` when the unlock state is off (sets up F4-d's
    test path); add `mock_get_last_write` admin endpoint for
    audit-log assertions.
  - New `Series/ParameterWriteTests.cs` and `Series/MacroWriteTests.cs`
    integration tests; ACL test under
    `tests/ZB.MOM.WW.OtOpcUa.IntegrationTests/Authz/FocasWriteAclTests.cs`
    asserting `WriteConfigure` is required for `PARAM:` writes and
    `WriteOperate` for `MACRO:` writes.
  - `scripts/e2e/test-focas.ps1` — populate the `-Write` stage from
    F4-a with macro and parameter round-trip writes against the
    Docker mock.
 - Effort: medium.
 - Risk: High — a misdirected parameter write can put the CNC into a
  bad state. Surface a `Writes.AllowParameter` flag separate from
  `Writes.Enabled` so operators can grant macro writes without
  parameter writes.
 **PR F4-c — `pmc_wrpmcrng`**
 - Scope: PMC range writes. Read-modify-write semantics for bit-level
  writes (the wire call is byte-addressed). Existing tests
  (`FocasPmcBitRmwTests.cs`) prove the read-modify-write pattern
  shape that the write path needs.
 - Files: `Wire/FocasWireClient.cs` (new `WritePmcRangeAsync`),
  bit-level RMW helper in `WireFocasClient`.
 - Tests: simulator round-trip on byte writes; bit-level write asserts
  the unrelated bits in the same byte are preserved.
 - **Docs / fixture / e2e**:
  - `docs/drivers/FOCAS.md` — extend the "Writes" subsection with
    PMC writes; loud safety callout block ("PMC is ladder working
    memory — a mistargeted bit can move motion"); document the
    read-modify-write semantics for bit-level writes; document the
    new `Writes.AllowPmc` granular flag.
  - `docs/v2/focas-deployment.md` — extend the "Write safety"
    section with PMC-specific pre-checks (e-stop, jog mode); add an
    ops-runbook bullet on auditing PMC writes from the
    `Diagnostics/CoalesceStats/` (extended) tree.
  - `docs/Driver.FOCAS.Cli.md` — the existing `write` example
    `write -h … -a G50.3 -t Bit -v on` (line 107) is already PMC-bit;
    update its surrounding warning to call out RMW behaviour.
  - Document the `pmc_wrpmcrng` request frame in
    `docs/v2/implementation/focas-wire-protocol.md` (the read frame
    is already there — flag the inverted shape).
  - `docs/v2/implementation/focas-simulator-plan.md` — add
    `pmc_wrpmcrng` to the protocol surface table.
  - Extend focas-mock with `pmc_wrpmcrng` handler that mutates
    per-profile PMC tables; assert byte-aligned writes preserve
    untouched bytes (mirrors the driver's RMW contract).
  - New `Series/PmcRangeWriteTests.cs` and
    `Series/PmcBitRmwIntegrationTests.cs` integration tests; ACL
    test under
    `tests/ZB.MOM.WW.OtOpcUa.IntegrationTests/Authz/FocasPmcWriteAclTests.cs`
    asserting `WriteOperate` is required.
  - `scripts/e2e/test-focas.ps1` — extend the `-Write` stage with a
    PMC bit round-trip.
 - Effort: medium.
 - Risk: High — PMC is the ladder logic's working memory; a
  mistargeted write can move motion. Document loudly.
 **PR F4-d — FOCAS password / unlock parameter (#3)**
 - Scope: some controllers gate `cnc_wrparam` and certain reads behind
  a connection-level password. Add `Password` to `FocasDeviceOptions`;
  emit the FOCAS password block during connect (`cnc_wrunlockparam`
  per FOCAS docs — confirm the exact command id during simulator
  iteration). On any read/write returning `EW_PASSWD`
  re-issue the password and retry once.
 - Files: `Wire/FocasWireClient.cs` (`UnlockAsync`),
  `FocasDriverOptions.cs` (`Password` field, treated as a secret —
  redact in logs), `FocasDriver.cs` (call on connect).
 - Tests: simulator extension — emit `EW_PASSWD` on writes when not
  unlocked; assert the unlock+retry path.
 - **Docs / fixture / e2e**:
  - `docs/drivers/FOCAS.md` — new "FOCAS password" subsection under
    Writes describing the optional `Password` device-option, when
    the CNC requires it (16i + some 30i firmwares with parameter-
    protect on), and the redaction guarantee.
  - **Security-note in `docs/v2/focas-deployment.md`** — significant
    addition: a "FOCAS password handling" subsection covering
    storage in `appsettings.json` (and the dev redaction pattern at
    `.local/`), the no-log invariant, and a runbook for password
    rotation. Cross-link to `docs/Security.md`.
  - `docs/Driver.FOCAS.Cli.md` — add a `--cnc-password` flag row to
    the "Common flags" table with the redaction note.
  - Document `cnc_wrunlockparam` (or the resolved command id) in
    `docs/v2/implementation/focas-wire-protocol.md`; resolve the
    open question raised by F4-d into the doc.
  - `docs/v2/implementation/focas-simulator-plan.md` — add
    `cnc_wrunlockparam` to the protocol surface; document the
    per-profile `unlock_password` field on the JSON profile schema.
  - Extend focas-mock with locked-state semantics on parameter
    writes (already half-stubbed in F4-b's `EW_PASSWD` branch);
    add `cnc_wrunlockparam` handler; add `mock_set_password`
    admin endpoint so integration tests can pin the unlock value.
  - New `Series/PasswordUnlockTests.cs` integration test asserts
    a write returning `EW_PASSWD` triggers exactly one unlock
    retry, and the second write succeeds.
  - `scripts/e2e/test-focas.ps1` — add `-CncPassword` parameter,
    threaded through to the CLI for the `-Write` stage.
 - Effort: small — once Phase 4-a/b are in.
 - Risk: Medium — password storage. Use the existing
  `appsettings.json` redaction pattern (memory entry: `dohertj2`
  AppData path); never log the password value.
 ### Phase 5 — derived telemetry
 **PR F5-a — Cycle time per part / last cycle delta (#24 derivation)**
 - Scope: with `Production/CycleTimeSeconds` in place from F1-b and
  the parts-count from `cnc_rdparam`, compute "last completed cycle"
  as the delta in `Timers/CycleSeconds` between successive
  parts-count increments. Project `Production/LastCycleSeconds`,
  `Production/LastCycleStartUtc`.
 - Files: `FocasDriver.cs` only — pure derivation in the program-poll
  cadence handler.
 - Tests: simulate a parts-count increment from 5→6; assert
  `LastCycleSeconds` equals the cycle-timer delta over the same
  window.
 - **Docs / fixture / e2e**: add `Production/LastCycleSeconds` and
  `Production/LastCycleStartUtc` rows to the fixed-tree table in
  `docs/drivers/FOCAS.md` with the rollover / counter-reset
  behaviour documented; add a `Derived telemetry` callout in
  `docs/v2/focas-deployment.md` explaining the derivation is
  client-visible only (no new wire calls); no
  `docs/v2/implementation/focas-wire-protocol.md` change (pure
  derivation); no focas-mock change beyond `FocasSimFixture`'s
  existing parameter-patch / timer-patch helpers — add a
  `SimulateCycleCompletionAsync` convenience helper that increments
  parts-count and advances the cycle timer atomically; new
  `Series/CycleDeltaTests.cs` integration test simulates a 5→6
  parts-count transition; no `scripts/e2e/test-focas.ps1` change.
 - Effort: small.
 - Risk: Low — pure derivation.
 ## Documentation, fixture, and e2e impact
 Consolidated view of every doc, fixture, and e2e artefact this plan
 touches. FOCAS has the largest doc surface of any driver in the v2
 roadmap because Phase 4 reverses a long-standing read-only design
 choice that is referenced from at least three user-facing docs and one
 test-fixture doc.
 ### Docs touched (per file, with the heaviest PR called out)
 | Doc | Touched by | Heaviest change |
 | --- | --- | --- |
 | `docs/drivers/FOCAS.md` | F1-a, F1-b, F1-c, F1-d, F1-e, F1-f, F2-a, F2-b, F2-d, F3-a, F4-a, F4-b, F4-c, F4-d, F5-a | **F4-a** revokes the read-only callout at lines 14–18; **F2-b** adds the multi-path subsection |
 | `docs/drivers/FOCAS-Test-Fixture.md` | F1-a, F1-d, F1-f, F2-a, F2-b, F3-a, F4-a | **F4-a** revokes the "`IWritable` intentionally returns `BadNotWritable`" callout at lines 42–43 |
 | `docs/Driver.FOCAS.Cli.md` | F1-b, F1-c, F2-a, F2-b, F4-a, F4-b, F4-c, F4-d | **F4-a** qualifies the read-only stance at lines 100–116; **F4-d** adds `--cnc-password` flag |
 | `docs/v2/focas-deployment.md` | F1-f, F3-a, F4-a, F4-b, F4-c, F4-d | **F4-b** adds "Write safety" section; **F4-d** adds "FOCAS password handling" section |
 | `docs/v2/focas-version-matrix.md` | F1-c, F1-d, F2-a, F2-c, F2-d | **F1-d** adds capability-suppression rows for tooling/offsets |
 | `docs/v2/implementation/focas-wire-protocol.md` | F1-a, F1-c, F1-d, F1-e, F1-f, F2-a, F2-b, F2-d, F3-a, F4-b, F4-c, F4-d | **F1-d** documents three new structs (ODBTOFS, ODBTLIFE5, IODBZOR); **F4-d** resolves the `cnc_wrunlockparam` open question |
 | `docs/v2/implementation/focas-simulator-plan.md` | F1-c, F1-d, F1-e, F1-f, F2-a, F2-b, F2-d, F3-a, F4-a, F4-b, F4-c, F4-d | Each PR appends to the protocol surface table; F4-* close out Stream C status |
 | `docs/v2/decisions.md` (new entry) | F4-a | Net-new decision-record for the read-only reversal |
 | `docs/featuregaps.md` | F4-a | Updates Build = Yes annotation for #1 / #3 with "shipping behind flag" |
 ### Fixture (focas-mock) extensions
 The vendored Python `focas-mock` simulator under
 `tests/.../IntegrationTests/Docker/focas-mock/` gains the following
 new command-id handlers and per-profile state:
 | PR | Mock extension |
 | --- | --- |
 | F1-a | `cnc_rdcncstat` full-struct response |
 | F1-b | Seeded values for parameters 6711/6712/6713 in every profile JSON |
 | F1-c | New `cnc_modal` handler + canned modal payload per profile |
 | F1-d | `cnc_rdtofs` / `cnc_rdtlife*` / `cnc_rdzofs` handlers + per-profile tool/offset tables, plus a `tools_per_series` profile knob |
 | F1-e | `cnc_rdopmsg3` / `cnc_rdactpt` handlers + `mock_patch_opmsg` admin endpoint |
 | F1-f | `cnc_getfigure` handler + per-profile `decimal_places` field |
 | F2-a | `cnc_rddiag` / `cnc_rddiagdgn` handlers + per-profile diagnostic numbers |
 | F2-b | Per-path state isolation; new `path_count` profile field; new `thirtyone_i_dual_path` compose profile |
 | F2-c | No mock change (16i profile already declares F/G ranges) |
 | F2-d | Wire-call counter admin endpoint |
 | F3-a | Ring-buffer alarm history + `mock_patch_alarmhistory` admin endpoint |
 | F4-a | Stub branch returning `BadNotSupported` for write commands |
 | F4-b | `cnc_wrparam` / `cnc_wrmacro` handlers (with `EW_PASSWD` when locked); `mock_get_last_write` admin endpoint |
 | F4-c | `pmc_wrpmcrng` handler with byte-aligned write semantics |
 | F4-d | `cnc_wrunlockparam` handler; `mock_set_password` admin endpoint; locked-state on the param-write path |
 | F5-a | `SimulateCycleCompletionAsync` helper on `FocasSimFixture` (no new mock command) |
 `FocasSimFixture` (in
 `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/FocasSimFixture.cs`)
 gains corresponding admin-API client helpers for each new endpoint.
 ### Integration tests (per phase)
 | Phase | New / extended integration tests under `tests/.../FOCAS.IntegrationTests/Series/` |
 | --- | --- |
 | Phase 1 | `StatusFlagsPopulateTests.cs`, `ProductionPopulatesTests.cs`, `ModalPopulatesTests.cs`, `ToolingPopulatesTests.cs`, `OffsetsPopulatesTests.cs`, `OperatorMessagesPopulateTests.cs`, `DecimalScalingTests.cs`, `DiagnosticsCountersTests.cs` |
 | Phase 2 | `DiagAddressTests.cs`, `MultiPathTests.cs`, `PmcCoalescingTests.cs` (plus a 16i row in `FocasCapabilityMatrixTests.cs` for F2-c) |
 | Phase 3 | `AlarmHistoryProjectionTests.cs` |
 | Phase 4 | `ParameterWriteTests.cs`, `MacroWriteTests.cs`, `PmcRangeWriteTests.cs`, `PmcBitRmwIntegrationTests.cs`, `PasswordUnlockTests.cs` plus ACL tests under `tests/ZB.MOM.WW.OtOpcUa.IntegrationTests/Authz/FocasWriteAclTests.cs` and `FocasPmcWriteAclTests.cs` |
 | Phase 5 | `CycleDeltaTests.cs` |
 ### E2E script (`scripts/e2e/test-focas.ps1`) updates
 | PR | Change |
 | --- | --- |
 | F1-f | New `-CheckDecimalScaling` switch |
 | F2-b | New `-Paths` switch (matrix mode iterates per declared path) |
 | F2-c | Adds F0.0 / G50.5 probes to the 16i row of the per-series matrix |
 | F4-a | Adds `-Write` switch (no-op stage in F4-a; populated by F4-b/c) |
 | F4-b | Populates `-Write` stage with macro + parameter round-trip writes |
 | F4-c | Extends `-Write` stage with PMC bit round-trip |
 | F4-d | Adds `-CncPassword` parameter, threaded through to the CLI |
 `scripts/integration/run-focas.ps1` does not change shape across the
 plan — it remains the compose up/test/compose down wrapper. New
 profiles registered by F2-b are automatically picked up via the
 existing `-Profile` switch.
 ### Read-only callouts requiring revocation in Phase 4
 For reviewer benefit, the explicit read-only callouts that **F4-a
 must revoke or qualify** in the same PR that flips the design choice:
 - `docs/drivers/FOCAS.md` lines 14–18 ("OtOpcUa is **read-only**
  against FOCAS… Writes return `BadNotWritable` by design.")
 - `docs/drivers/FOCAS-Test-Fixture.md` lines 42–43 ("`IWritable`
  intentionally returns `BadNotWritable` — OtOpcUa is read-only
  against FOCAS.")
 - `docs/Driver.FOCAS.Cli.md` lines 100–116 (write section is already
  documented but predates the server-side flag; needs a
  server-enforced-ACL note)
 - `docs/featuregaps.md` (FOCAS row entries for #1 and #3 carry the
  same read-only-by-design framing — flip annotation)
 ## Skip-rated items (for context)
 These appear in the featuregaps recommendations table as Build = No;
 recapped here so reviewers can confirm the scope decision rather than
 re-deriving it from `featuregaps.md`:
 - **#2 HSSB transport** — PCI hardware, declining install base,
  reopens the Fwlib distribution problem the wire client deliberately
  closed.
 - **#5 Series 15 / Power Mate D-H / Series 35i** — very legacy; small
  install base. Capability matrix already accepts `Unknown` as a
  permissive escape hatch.
 - **#9 Tool-offset write** — write-heavy; defer alongside the general
  write decision (F4 covers reads via tool-life only).
 - **#19 Program list / upload / download / delete** — DNC product
  territory; significant scope; out of OtOpcUa's MES focus.
 - **#21 DPRNT TCP listener** — significant scope; modern OPC UA
  alarms / events supersede it.
 - **#22 Servo / spindle deep info (`cnc_rdsvinfo` / `cnc_rdspinfo`)** —
  specialty; load-percent already covers most needs.
 - **#23 Per-axis acceleration / jerk / feed-per-rev** — niche
  advanced telemetry.
 - **#25 Operator write commands (preset, `cnc_setpath`, `cnc_wrabsmac`)** —
  read-only-by-design covers it; parameter / PMC / macro writes from
  Phase 4 are the supervisory writes operators actually need.
 - **#26 CNC time / date sync** — rare ask; commonly handled by CNC NTP.
 ## Open questions
 - **Modal command id** (PR F1-c): `cnc_modal` numeric command code is
  not in the existing wire-protocol notes
  (`docs/v2/implementation/focas-wire-protocol.md`). Capture during
  the simulator iteration loop; if the simulator can't yet emit the
  shape, gate F1-c behind a bench-CNC trace per the
  diminishing-returns checkpoint.
 - **Override parameter numbers** (PR F1-c): feedrate / rapid /
  spindle override register numbers are MTB-specific. Default to the
  documented Fanuc factory numbers and let operators override per
  device (`Devices[].OverrideRegisters` map).
 - **Multi-path discovery** (PR F2-b): does the simulator support
  multi-path responses today? If not, F2-b lands gated behind the
  `OTOPCUA_FOCAS_SIM_WIRE_COMPAT=1` flag the wire-protocol doc
  describes.
 - **Decimal-scaling migration** (PR F1-f): existing `Float64` axis
  nodes are scaled integers today. Decision: ship F1-f with
  scaling-on default, add a one-release deprecation window with the
  flag default-off so existing dashboards don't silently scale by
  10^N when the driver is upgraded. Need explicit operator opt-in.
 - **Write security posture** (Phase 4): should writes require LDAP
  group `WriteConfigure` (parameters) vs `WriteOperate` (macros /
  PMC)? Per the memory entry on ACL-at-server-layer, the driver only
  reports `SecurityClassification`; the server enforces. Need the
  driver to surface the right classification per address kind:
  `Configure` for `PARAM:`, `Operate` for `MACRO:` and PMC writes.
 - **Phase 4 rollout**: ship behind a feature flag in `appsettings.json`
  (`Drivers.{name}.Config.Writes.Enabled`) with `false` default for at
  least one release before flipping the default. Update
  `docs/drivers/FOCAS.md` and `docs/featuregaps.md` in the same PR
  that flips the default.
 - **Cycle-delta edge cases** (PR F5-a): parts-count rollover; counter
  reset by the operator. Default behaviour: emit the delta only when
  the counter strictly increments by 1; on any other transition emit
  `Production/LastCycleSeconds` as `null` with `BadOutOfRange` and
  let the operator interpret.
--- a/docs/plans/opcuaclient-plan.md
+++ b/docs/plans/opcuaclient-plan.md
@@ -0,0 +1,863 @@
 # OpcUaClient Driver — Implementation Plan
 > Source of gap analysis: [featuregaps.md → OpcUaClient](../featuregaps.md#opcuaclient-opc-ua-aggregation-client)
 >
 > Covers Build = Yes items only. Numbering matches the featuregaps Recommendations table.
 ## Summary
 The OpcUaClient driver already ships 8/8 capability interfaces and a working
 end-to-end Session/Subscription/MonitoredItem/HistoryRead pipeline backed by
 the OPC Foundation `OPCFoundation.NetStandard.Opc.Ua.Client` SDK. Most of the
 14 Build = Yes gaps are operability or curation knobs — config surface +
 plumbing into existing SDK calls — rather than new protocol implementation.
 A small number need genuinely new SDK plumbing (Reverse Connect,
 ModelChangeEvent subscribe) and one (`ReadEventsAsync`) needs a coordinated
 cross-driver interface change.
 The plan groups the work into five phases, ordered to deliver per-tag /
 per-subscription operability first (highest-frequency operator pain), then
 curation, then change tracking, then connectivity, then historical+HA. Each
 PR sticks to one feature-gap row so reviews stay narrow.
 ## Phased delivery
 | Phase | Theme | Gaps | PRs | Notes |
 | :---: | --- | --- | :---: | --- |
 | 1 | Operability knobs | #5, #6, #15, #17, #20 | 5 | Pure SDK config surface; no new wire flows |
 | 2 | Discovery & curation | #2, #7, #8, #9 | 4 | Touches `ITagDiscovery` + adds method invoke |
 | 3 | Change tracking | #10 | 1 | New session-level subscription on `Server` node |
 | 4 | Connectivity | #1 | 1 | Reverse Connect — new listener path |
 | 5 | Historical & redundancy | #12, #13, #14 | 3 | Includes the cross-driver `IHistoryProvider` change |
 **Total: 14 PRs across 5 phases.** Phases 1-3 land independently against
 the existing single-session model. Phase 4 ships in parallel with phases 2-3
 since it doesn't touch `OpcUaClientDriver` proper. Phase 5's first PR is a
 prerequisite for the `ReadEventsAsync` work in every other history-capable
 driver and must coordinate with them.
 ## Per-PR detail
 ### Phase 1 — Operability knobs
 #### PR-1: Per-subscription tuning (gap #6)
 **Goal**: lift the hard-coded `KeepAliveCount=10`, `LifetimeCount=1000`,
 `MaxNotificationsPerPublish=0`, `Priority=0`, `PublishingInterval` floor of
 50 ms into `OpcUaClientDriverOptions` so high-event-rate servers can be
 defended against (`MaxNotificationsPerPublish=0` is unlimited — the
 documented DoS surface) and high-tag-count deployments can split by
 priority.
 **SDK API**:
 - `Subscription.SetPublishingMode(bool, ct)` for runtime enable/disable
 - `SubscriptionOptions.PublishingInterval / KeepAliveCount / LifetimeCount /
  MaxNotificationsPerPublish / Priority` set at create-time
 - New options class `OpcUaSubscriptionDefaults` (publish interval floor,
  keep-alive count, lifetime count, max notifications, priority)
 **Files**:
 - `src/.../OpcUaClient/OpcUaClientDriverOptions.cs` — add `Subscriptions`
  sub-section
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` — `SubscribeAsync` reads from
  options
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` — `SubscribeAlarmsAsync` reuses
  same defaults but with `Priority=1` higher than data subscriptions so
  alarms aren't starved during data bursts
 **Tests**: `OpcUaClientSubscribeAndProbeTests` — assert options propagate;
 add a stress unit test (mocked `Subscription`) that asserts custom
 `MaxNotificationsPerPublish` is forwarded so a value > 0 actually reaches
 the SDK.
 **Risks**: Setting `LifetimeCount` too low against a server with publish-
 throttling can drop subscriptions; doc the formula (`LifetimeCount >=
 3 * KeepAliveCount`).
 **Docs / fixture / e2e**: new "Subscription tuning" subsection in
 `docs/drivers/OpcUaClient.md` (create if missing) documenting the
 `Subscriptions` options block with the `LifetimeCount >= 3 *
 KeepAliveCount` formula; cross-link from the "Advanced options" section
 of `docs/Client.CLI.md` so CLI users discover the knobs. Fixture: opc-plc
 already publishes fast tickers (`FastUInt1` @ 100 ms) sufficient for
 coverage — no fixture-side change. Integration test in
 `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/` asserting
 custom `KeepAliveCount` / `Priority` reach the wire (capture via
 `OpcPlcFixture` keepalive count). E2E: extend
 `scripts/e2e/test-opcuaclient.ps1` with a stage that sets a non-default
 publish interval and confirms the local subscription honours it.
 ---
 #### PR-2: Per-tag advanced subscription tuning incl. deadband (gap #5)
 **Goal**: surface `SamplingInterval`, `QueueSize`, `DiscardOldest`,
 `MonitoringMode`, and `DataChangeFilter` (DeadbandType=Absolute/Percent +
 Trigger=Status/StatusValue/StatusValueTimestamp) per-tag. Deadband is the
 baseline analog noise filter every commercial UA aggregator ships and the
 single feature most likely to cut bandwidth on busy plants.
 **SDK API**:
 - `MonitoredItem.Filter = new DataChangeFilter { Trigger =
  DataChangeTrigger.StatusValue, DeadbandType = (uint)DeadbandType.Absolute,
  DeadbandValue = 0.5 }`
 - `MonitoredItemOptions.QueueSize / DiscardOldest / SamplingInterval /
  MonitoringMode`
 - Per-tag override structure: extend the `SubscribeAsync` parameter shape
  (or add an overload accepting a `IReadOnlyList<MonitoredTagSpec>`) — note
  this requires coordinating with `ISubscribable` so the per-tag carrier
  reaches the driver.
 **Files**:
 - `src/.../Core.Abstractions/ISubscribable.cs` — add overload
  `SubscribeAsync(IReadOnlyList<MonitoredTagSpec>, ...)` keeping old API
  for source compat
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` — translate spec → SDK filter
 **Tests**: assert `DataChangeFilter` lands on the `MonitoredItem.Filter` for
 each kind of trigger; assert PercentDeadband requires server-side
 EURange (server returns `BadFilterNotAllowed` if not configured) — capture
 the StatusCode and surface as a usable error.
 **Risks**: cross-cutting `ISubscribable` change. Mitigation: ship the
 overload as additive — existing single-arg path still exists.
 **Docs / fixture / e2e**: new "Per-tag deadband and monitoring filters"
 section in `docs/drivers/OpcUaClient.md` (create if missing) with worked
 examples of Absolute vs Percent deadband + the EURange prerequisite;
 update `docs/Client.CLI.md` `subscribe` command page with the new tag-
 config syntax for `--deadband` / `--queue-size` / `--discard-oldest`;
 update `docs/Client.UI.md` Subscriptions tab section to mirror. Fixture:
 `OpcPlcFixture` / `OpcPlcProfile` seeds an analog (`StepUp` already
 oscillates) and confirms `EURange` is published — extend the profile to
 flag noisy nodes. Integration test in
 `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/` asserts
 publish suppression below the deadband threshold. E2E: add a
 `-DeadbandValue` stage to `scripts/e2e/test-opcuaclient.ps1` (and a
 `deadband` knob to `scripts/e2e/e2e-config.sample.json`) that subscribes,
 asserts no spurious updates within the band.
 ---
 #### PR-3: Honor server `OperationLimits` (gap #15)
 **Goal**: read `Server.ServerCapabilities.OperationLimits.MaxNodesPerRead /
 Write / Browse / HistoryReadData` once after Session activation, cache,
 and chunk batch operations to those caps client-side. Today the SDK chunks
 on its internal default; against an undersized embedded UA server this
 results in `BadTooManyOperations`.
 **SDK API**:
 - After session open: `Session.ReadAsync` of
  `VariableIds.Server_ServerCapabilities_OperationLimits_MaxNodesPerRead`
  + sibling NodeIds. The SDK exposes `Session.OperationLimits` after
  `FetchOperationLimits` is called — prefer that path.
 - `Session.FetchOperationLimitsAsync(ct)` (1.5+); fallback: explicit Read.
 **Files**:
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` — call
  `FetchOperationLimitsAsync` post-`OpenSessionOnEndpointAsync`; honour
  caps in `ReadAsync`, `WriteAsync`, `BrowseRecursiveAsync`,
  `EnrichAndRegisterVariablesAsync`, `ExecuteHistoryReadAsync`.
 **Tests**: mock `Session.OperationLimits` to a value below the test batch
 size and assert the driver issues N wire calls instead of one.
 **Risks**: a zero on the server means "no limit" per Part 5 — don't divide
 by zero.
 **Docs / fixture / e2e**: new "Server OperationLimits handling"
 subsection in `docs/drivers/OpcUaClient.md` documenting the auto-fetch
 behaviour, the zero-means-unlimited semantics, and how to override via
 options if the server reports an under-truthful value. Fixture: opc-plc
 publishes the standard ServerCapabilities tree out of the box — no
 container-side change; the `OpcPlcFixture` seed validates the IDs at
 collection init. Integration test asserts batch reads chunk to the
 fetched cap. No e2e change needed (the script's batch sizes are already
 small).
 ---
 #### PR-4: Diagnostics counters (gap #17)
 **Goal**: expose per-driver counters on `DriverHealth` (or a sibling
 `DriverDiagnostics` surface): publish-request count, notifications-per-
 second EWMA, missing-publish-request count, dropped-notification rate,
 session resets count. Operators currently see only `LastSuccessfulRead`
 + last error.
 **SDK API**:
 - `Subscription.Notification` event fires per published notification — bump
  a counter
 - `Subscription.PublishStateChanged` event for missed-publish detection
 - `Session.PublishError` event for channel-level errors
 - `Session.SessionClosing`/`SessionConfigurationChanged` for session-reset
  attribution
 **Files**:
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` — instrument hooks; expose via
  `IDriver.GetDiagnostics()` or extend `DriverHealth`
 - `src/.../Core.Abstractions/IDriver.cs` — confirm where the counter shape
  lives; if `DriverHealth` is too rigid, add `IDriverDiagnostics` (mirrors
  the Modbus `driver-diagnostics` RPC pattern from #154)
 **Tests**: synthetic notification fan-out → assert counters increment;
 session close → assert reset count bumps.
 **Risks**: counters need to be lock-free hot-path safe; use
 `Interlocked.Increment` and a single sliding-window clock per counter.
 **Docs / fixture / e2e**: new "Driver diagnostics" section in
 `docs/drivers/OpcUaClient.md` enumerating each counter and the event
 that bumps it; cross-link to the `driver-diagnostics` Admin RPC
 documented for Modbus (#154 pattern). Fixture: no opc-plc change
 required. Integration test exercises `IDriverDiagnostics` after
 forcing a session close. E2E: extend
 `scripts/e2e/test-opcuaclient.ps1` with a "diagnostics snapshot" stage
 that asserts publish/notification counters are non-zero after the
 subscribe stage.
 ---
 #### PR-5: CRL / revocation handling (gap #20)
 **Goal**: explicit revoked-cert handling in `CertificateValidator` plus a
 `RejectSHA1SignedCertificates` knob. Today the validator hooks
 `BadCertificateUntrusted` only — a revoked cert silently fails as
 "untrusted" with no operator-visible distinction.
 **SDK API**:
 - `CertificateValidator.CertificateValidation` event — inspect
  `e.Error.StatusCode` for `BadCertificateRevoked`,
  `BadCertificateRevocationUnknown`,
  `BadCertificateIssuerRevocationUnknown`,
  `BadCertificatePolicyCheckFailed`
 - `SecurityConfiguration.RejectSHA1SignedCertificates`,
  `SecurityConfiguration.RejectUnknownRevocationStatus`,
  `SecurityConfiguration.MinimumCertificateKeySize` — direct config
  bool/int knobs already on the SDK type
 - `CertificateTrustList.AddCRL` / per-store CRL directories under
  `%LocalAppData%\OtOpcUa\pki\{trusted,issuers}\crl\`
 **Files**:
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` — `BuildApplicationConfigurationAsync`
  honours new options, validator handler distinguishes revoked vs untrusted
  in the surfaced error message
 - `src/.../OpcUaClient/OpcUaClientDriverOptions.cs` — add
  `RejectSHA1SignedCertificates`, `RejectUnknownRevocationStatus`,
  `MinimumCertificateKeySize`
 **Tests**: feed a SHA1-signed test cert and a revoked cert through the
 validator with the new knobs on/off.
 **Risks**: PKI directory layout changes — existing deployments need a
 migration note.
 **Docs / fixture / e2e**: new "Certificate revocation and SHA1 rejection"
 subsection in `docs/drivers/OpcUaClient.md` documenting the CRL
 directory layout under `%LocalAppData%\OtOpcUa\pki\{trusted,issuers}\crl\`
 and the new options (with a migration note for existing PKI stores);
 cross-link from `docs/security.md`. Fixture: extend
 `OpcPlcFixture` / `Docker/docker-compose.yml` with an optional secured
 endpoint variant and a SHA1-signed test cert checked into the test
 project's resources for the validator unit test. Integration test
 exercises a revoked cert via a local CRL drop. E2E: add a
 `-Insecure:$false` smoke stage to `scripts/e2e/test-opcuaclient.ps1`
 that asserts a revoked cert produces a distinguishable error message.
 ---
 ### Phase 2 — Discovery & curation
 #### PR-6: Discovery URL `FindServers` (gap #2)
 **Goal**: accept a discovery URL (`opc.tcp://host:4840` pointing at the
 LDS or the server's own discovery endpoint) and surface advertised servers
 + endpoints to the operator without manual policy/mode tuple copy.
 **SDK API**:
 - `DiscoveryClient.CreateAsync(appConfig, new Uri(url), DiagnosticsMasks.None, ct)`
 - `DiscoveryClient.FindServersAsync(null, ct)` → `ApplicationDescription[]`
 - `DiscoveryClient.GetEndpointsAsync(null, ct)` per advertised `DiscoveryUrl`
 **Files**:
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` — new internal
  `DiscoverServersAsync` helper; extend the Admin-side discovery RPC to
  invoke it (driver-diagnostics pattern from #154)
 - `src/.../OpcUaClient/OpcUaClientDriverOptions.cs` — add
  `DiscoveryUrl` knob (alternative to explicit `EndpointUrls` — when set
  the driver runs `FindServers` at init and feeds the result into the
  failover candidate list)
 **Tests**: mock `DiscoveryClient` returning two advertised servers each
 with three endpoints; assert the candidate list reflects the policy/mode
 filter applied client-side.
 **Risks**: `FindServers` itself usually requires `SecurityMode=None` —
 spec out in the doc that the discovery channel is unsecured even when
 the data channel will be encrypted.
 **Docs / fixture / e2e**: new "Discovery URL (`FindServers`)" section in
 `docs/drivers/OpcUaClient.md` with the unsecured-discovery-vs-secured-
 data caveat called out; cross-link from `docs/Client.CLI.md` if a
 `discover` CLI command surfaces. Fixture: opc-plc already responds to
 `FindServers` on the same endpoint — `OpcPlcFixture` adds a discovery
 probe at collection init. Integration test exercises the helper against
 the live opc-plc container and asserts at least one
 `ApplicationDescription` returned. E2E: replace the hard-coded
 `-RemoteUrl` stage in `scripts/e2e/test-opcuaclient.ps1` with an
 optional `-DiscoveryUrl` mode that picks the first advertised endpoint.
 ---
 #### PR-7: Selective import / namespace remap (gap #7)
 **Goal**: per-branch include/exclude rules, namespace-URI remapping, and
 re-keyed BrowseNames — the curation surface every commercial aggregator
 ships.
 **Approach**: extend `OpcUaClientDriverOptions` with a `Curation` section:
 - `IncludePaths: string[]` — glob or NodeId-rooted prefix list; only paths
  matching are imported
 - `ExcludePaths: string[]` — wins over Include (Include is allow-list,
  Exclude is block-list)
 - `NamespaceRemap: Dictionary<string,string>` — upstream NS URI →
  local-side alias for BrowseName generation
 - `RootAlias: string` — default `"Remote"`; replaces the hardcoded folder
  name today
 **SDK API** — none new; this is pure local filtering inside
 `BrowseRecursiveAsync` and `EnrichAndRegisterVariablesAsync`.
 **Files**:
 - `src/.../OpcUaClient/OpcUaClientDriverOptions.cs`
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` —
  `BrowseRecursiveAsync` consults the rule set; helper
  `MapNamespaceForBrowseName` handles NS remap
 **Tests**: synthetic browse tree, exercise include/exclude/remap each
 independently and combined; verify the cap accounting in
 `MaxDiscoveredNodes` excludes filtered nodes.
 **Risks**: glob semantics — pin to a small subset (`*`, `?` only — no
 character classes or `**`) to keep the doc + behaviour simple.
 **Docs / fixture / e2e**: new "Curation: include/exclude and namespace
 remap" section in `docs/drivers/OpcUaClient.md` with worked examples of
 each rule kind and the supported glob subset; update
 `docs/drivers/OpcUaClient-Test-Fixture.md` "Coverage map" with the new
 filtering rows. Fixture: extend `OpcPlcProfile` to enumerate which
 upstream namespaces are exercised so curation tests can target them.
 Integration test seeds an Include + Exclude + Remap rule and asserts
 the local tree reflects the filter. E2E: add a
 `-IncludePath` / `-NamespaceRemap` set of params to
 `scripts/e2e/test-opcuaclient.ps1` that asserts the local browse depth
 matches the rule.
 ---
 #### PR-8: Type definition mirroring (gap #8)
 **Goal**: walk the upstream `Types` folder (`ObjectTypes`,
 `VariableTypes`, `DataTypes`, `ReferenceTypes`) and project them into the
 local address space so downstream UI clients keep type-aware rendering and
 structured DataTypes decode correctly.
 **SDK API**:
 - `Session.NodeCache.FetchNode(typeNodeId)` for type metadata
 - `Session.LoadDataTypeSystem` — for structured DataType encoding
 - `Session.FetchTypeTree(NodeIdCollection)` — populates the session's
  type cache from the server
 **Files**:
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` — new pass-3 in `DiscoverAsync`
  that walks `i=86` (Types folder) under the curation rules, registers a
  parallel type subtree, and links variables to their TypeDefinition via
  HasTypeDefinition references on the address-space builder
 - `src/.../Core.Abstractions/IAddressSpaceBuilder.cs` — confirm whether
  the builder accepts type nodes; if not, extend it (this likely is a
  prerequisite — if so, it gets its own preceding PR-8a)
 **Tests**: mock browse returning `BaseObjectType -> DerivedThing`;
 assert local builder receives the type node + the HasTypeDefinition link.
 **Risks**: significant. Type mirroring touches `IAddressSpaceBuilder`
 which is a cross-cutting interface every driver depends on. If
 `IAddressSpaceBuilder` already supports type nodes (Galaxy has type-like
 templates), reuse that surface; otherwise this PR splits.
 **Docs / fixture / e2e**: new "Type mirroring" section in
 `docs/drivers/OpcUaClient.md` documenting which type nodes get walked
 and how downstream UA clients see the HasTypeDefinition references; also
 note in `docs/Client.UI.md` that the Browse tree now shows mirrored
 types. Fixture: opc-plc already exposes the standard `Types` folder;
 extend `OpcPlcProfile` to assert at least one custom ObjectType is
 present. Integration test browses the local Types folder post-discovery
 and asserts the upstream type chain landed. No e2e change needed beyond
 extending the existing browse stage to walk under `Types`.
 ---
 #### PR-9: Method node mirroring + `Call` passthrough (gap #9)
 **Goal**: discover `NodeClass.Method` nodes in the browse pass, expose
 them on the local address space, and forward `Call` invocations as
 `Session.CallAsync` against the upstream node. The driver already calls
 `AcknowledgeableConditionType.Acknowledge` for A&C — generalize that path.
 **SDK API**:
 - `Session.CallAsync(requestHeader, methodsToCall: CallMethodRequestCollection, ct)`
  returning `CallMethodResultCollection`
 - Browse already covers Method nodes by lifting the `NodeClassMask`; need
  to additionally browse `HasProperty` to discover `InputArguments` /
  `OutputArguments` for argument translation
 **Files**:
 - `src/.../Core.Abstractions/IDriver.cs` — add `IMethodInvoker` capability
  interface (this is a NEW capability, not a tweak to an existing one)
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` — implement
  `IMethodInvoker.InvokeAsync(string objectId, string methodId,
  IReadOnlyList<object?> inputs, ct)`; refactor `AcknowledgeAsync` to
  reuse the common path
 - `src/.../Server/...` node-manager — wire `IMethodInvoker` to the OPC UA
  server's `MethodNode.OnCallMethod` hook so downstream Call requests
  reach the driver
 **Tests**: mock `Session.CallAsync` returning Good + an output collection;
 assert pass-through fidelity. Also assert per-argument `BadInvalidArgument`
 codes pass through.
 **Risks**: high — adds a new capability interface. Other drivers that
 *could* support methods (Galaxy via `OnExecute` scripts, FOCAS via FOCAS
 commands) gain a clean extension point but each is its own follow-up.
 **Docs / fixture / e2e**: new "Method nodes and Call passthrough"
 section in `docs/drivers/OpcUaClient.md` explaining how method calls
 flow through the aggregator (input/output argument translation, error-
 code passthrough); add a `call` command page to `docs/Client.CLI.md`
 covering the new path; mirror in `docs/Client.UI.md` if a UI surface
 ships. Fixture: opc-plc already exposes the standard
 `Server.GetMonitoredItems` method — `OpcPlcFixture` registers it as the
 canonical method-call target. Integration test in
 `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/` invokes
 `Server.GetMonitoredItems` through the aggregator. E2E: add a
 `-MethodNodeId` stage to `scripts/e2e/test-opcuaclient.ps1` that calls
 the method through the local server and asserts the output matches the
 direct upstream call.
 ---
 ### Phase 3 — Change tracking
 #### PR-10: Auto re-import on `ModelChangeEvent` (gap #10)
 **Goal**: subscribe to `BaseModelChangeEventType` /
 `GeneralModelChangeEventType` on the upstream server's `i=2253` Server
 node so when the upstream topology changes (new tag added, type modified)
 the driver triggers a `ReinitializeAsync`-style re-import without
 operator action.
 **SDK API**:
 - A second `Subscription` on the Session, monitoring `Server` node
  (`ObjectIds.Server`) with an `EventFilter` whose SelectClauses reference
  `BaseModelChangeEventType` and (optionally) `GeneralModelChangeEventType`
  Changes property
 - On notification: enqueue a debounced re-discover (don't react to every
  event during a bulk topology edit — coalesce 2-5s window)
 **Files**:
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` — add `_modelChangeSubscription`
  field; new `SubscribeModelChangesAsync` invoked at the end of
  `InitializeAsync`; debounce timer that calls `ReinitializeAsync` on the
  driver host
 - `src/.../OpcUaClient/OpcUaClientDriverOptions.cs` — add
  `WatchModelChanges: bool` (default true) +
  `ModelChangeDebounce: TimeSpan` (default 5s)
 **Tests**: synthetic event injection on the mock Session's notification
 stream; assert one debounced re-import call regardless of N events
 arriving in the window.
 **Risks**: re-import while a downstream client is mid-browse — needs
 serialization on `_gate` like the rest of the driver; document that
 clients see a brief gap in the address space during reload.
 **Docs / fixture / e2e**: new "Auto re-import on ModelChangeEvent"
 section in `docs/drivers/OpcUaClient.md` documenting the debounce window,
 the `_gate` serialization, and the brief browse-gap during reload.
 Fixture: opc-plc supports runtime topology mutation via the
 `addnode`/`addtag` HTTP control endpoint — extend `OpcPlcFixture` with
 a helper that triggers a model change. Integration test asserts a
 single re-import call after a burst of synthetic model change events.
 E2E: add a "topology change" stage to
 `scripts/e2e/test-opcuaclient.ps1` that calls the opc-plc control
 endpoint, then asserts the local server reflects the new node within
 the debounce window.
 ---
 ### Phase 4 — Connectivity
 #### PR-11: Reverse Connect (gap #1)
 **Goal**: support server-initiated client connect for OT-DMZ outbound-only
 firewalls. The upstream server connects *to* us on a TCP listener; we
 respond as the client. Hard requirement for many regulated plant networks.
 **SDK API**:
 - `Opc.Ua.Client.ReverseConnectManager` — manages a TCP listener on the
  configured port and dispatches incoming reverse-connect requests
 - `ReverseConnectManager.AddEndpoint(Uri reverseEndpoint)` — listener URI
  e.g. `opc.tcp://0.0.0.0:4844`
 - `ReverseConnectManager.WaitForConnection(serverUri, serverUri, ct)` —
  blocks until the configured server initiates a reverse connect
 - `Session.Create(appConfig, reverseConnection, endpoint, ...)` —
  alternative session-create overload accepting the
  `ITransportWaitingConnection` returned by the manager
 **Files**:
 - `src/.../OpcUaClient/OpcUaClientDriverOptions.cs` — add
  `ReverseConnect: { Enabled, ListenerUrl, ExpectedServerUri }` section
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` — when reverse-connect is
  enabled, replace the failover sweep with `WaitForConnection` and fall
  through into the same session-create path
 - New helper `ReverseConnectListener` — owns the manager lifecycle, one
  listener per driver-host process (singleton across instances if multiple
  reverse-connect drivers are configured)
 **Tests**: spin up a `ReverseConnectClient` test against an opc-plc
 container started with `--rc opc.tcp://host:4844` to verify end-to-end.
 Unit tests mock `ITransportWaitingConnection`.
 **Risks**: highest of the plan. Reverse Connect changes the
 listen-vs-dial direction; if multiple OpcUaClient driver instances both
 listen on the same port the manager must multiplex. opc-plc supports
 reverse connect (`--rc` flag) so the integration test pattern from
 `docs/drivers/OpcUaClient-Test-Fixture.md` extends cleanly.
 **Docs / fixture / e2e**: new "Reverse Connect" section in
 `docs/drivers/OpcUaClient.md` (create if missing) documenting the
 listener URL config, the OT-DMZ outbound-only use case, and the shared-
 listener singleton model; update `docs/drivers/OpcUaClient-Test-Fixture.md`
 with the new "Reverse Connect coverage" row. Fixture: extend
 `Docker/docker-compose.yml` with an `opc-plc-rc` service variant that
 adds `--rc opc.tcp://host.docker.internal:4844`; `OpcPlcFixture` gains
 a `[CollectionDefinition]` that wires up the reverse-connect listener
 on the test side. Integration test asserts a session opens via the
 reverse path. E2E: add a `-ReverseConnect` switch to
 `scripts/e2e/test-opcuaclient.ps1` that flips the driver to listener
 mode and verifies the bridge stage still passes.
 ---
 ### Phase 5 — Historical & redundancy
 #### PR-12: `IHistoryProvider.ReadEventsAsync` interface fix + driver impl (gap #12)
 **Goal**: extend `IHistoryProvider.ReadEventsAsync` to carry an
 `EventFilter SelectClauses` parameter so HistoryRead Events can return
 the right field projection, and implement the OPC UA Client passthrough.
 **This is a cross-driver concern.** `IHistoryProvider` lives in
 `Core.Abstractions` and every driver that opts into history (Galaxy,
 OpcUaClient, plus any future historian-backed Tier-A driver) inherits the
 default. Changing the signature is source-breaking — coordinate as one PR
 that:
 1. Adds the `IReadOnlyList<EventFieldProjection>` (or equivalent
   abstract `EventFilterSpec`) parameter
 2. Updates Galaxy's existing override (currently the only override) to
   honour the projection (best-effort — the Galaxy A&E log has a fixed
   field set so most projections degrade to the default columns)
 3. Lands the OpcUaClient passthrough using `Session.HistoryReadAsync` with
   `ReadEventDetails`
 **SDK API**:
 - `ReadEventDetails { StartTime, EndTime, NumValuesPerNode, Filter }`
 - `Session.HistoryReadAsync` is already the call we use for Raw — pass
  `new ExtensionObject(new ReadEventDetails { ... })` for events
 - `HistoryEvent.Events: HistoryEventFieldList[]` — unwrap into
  `HistoricalEvent` records
 **Files**:
 - `src/.../Core.Abstractions/IHistoryProvider.cs` — interface change
 - `src/.../Driver.Galaxy.../*HistoryProvider*.cs` — adjust signature
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` — implement
  `ReadEventsAsync`; reuse `ExecuteHistoryReadAsync` shape
 - Server-side history facade — propagate the new parameter
 **Tests**: integration test against opc-plc with
 `--alm` (alarm sim already enabled per the fixture doc) — verify the
 SelectClause projection comes back correctly.
 **Risks**: the cross-driver interface change is the riskiest single
 ergonomic call in this plan. If we can't fit the new parameter without
 breaking every driver's `IHistoryProvider` impl, fall back to a sibling
 `IEventHistoryProvider` interface and only the OPC UA Client + Galaxy
 implement it. **Decide this in the PR review.**
 **Docs / fixture / e2e**: new "HistoryRead Events" section in
 `docs/drivers/OpcUaClient.md` documenting the `EventFilter`-aware
 passthrough; update `docs/Client.CLI.md` `historyread` page to cover
 event-mode reads. **Cross-driver doc updates** (this PR adds an
 "`IHistoryProvider.ReadEventsAsync` signature change — see
 `docs/plans/opcuaclient-plan.md` PR-12" note to every other driver
 plan that has a history surface): `docs/plans/abcip-plan.md`,
 `docs/plans/ablegacy-plan.md`, `docs/plans/focas-plan.md`,
 `docs/plans/s7-plan.md`, `docs/plans/twincat-plan.md`, the Galaxy plan
 family (`docs/plans/galaxy-*.md` if/when present, and the LMX equivalent
 if it lands), and any Modbus plan. Galaxy is the only existing
 implementor and gets a real signature update in this PR; the others
 get a heads-up note so future work tracks the new shape. Fixture: opc-
 plc runs with `--alm` already (per existing fixture doc) — no compose
 change. Integration test issues a HistoryRead Events with a non-default
 SelectClause and asserts the projected fields. E2E: extend
 `scripts/e2e/test-opcuaclient.ps1` with a "history events" stage
 gated on the `--alm` simulator producing at least one event.
 ---
 #### PR-13: Full Aggregate function set (gap #13)
 **Goal**: extend `HistoryAggregateType` from the 5 enum values today
 (Average/Minimum/Maximum/Total/Count) to the OPC UA Part 13 standard
 catalog of 30+ aggregates that historian-class clients expect.
 **SDK API**: `ObjectIds.AggregateFunction_*` constants — one per
 aggregate. The SDK already exposes them; this is pure mapping work.
 Aggregates to add (Part 13 §5):
 - `TimeAverage`, `TimeAverage2`
 - `Interpolative`
 - `MinimumActualTime`, `MaximumActualTime`, `Range`, `Range2`
 - `AnnotationCount`, `DurationGood`, `DurationBad`,
  `PercentGood`, `PercentBad`
 - `WorstQuality`, `WorstQuality2`
 - `StandardDeviationSample`, `StandardDeviationPopulation`,
  `VarianceSample`, `VariancePopulation`
 - `NumberOfTransitions`
 - `Start`, `End`, `Delta`, `StartBound`, `EndBound`
 - `DurationInStateZero`, `DurationInStateNonZero`
 **Files**:
 - `src/.../Core.Abstractions/IHistoryProvider.cs` — extend
  `HistoryAggregateType` enum (additive — existing values keep their
  ordinal)
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` —
  `MapAggregateToNodeId` switch grows; default arm rejects `out of range`
 **Tests**: parametrized unit test sweeping every enum value — assert
 each maps to a non-null `NodeId` in the SDK's well-known set.
 **Risks**: low — this is mapping work. Drivers without a real historian
 (everything except Galaxy + OpcUaClient) keep throwing `NotSupported`.
 **Docs / fixture / e2e**: extend the "HistoryRead aggregates" section in
 `docs/drivers/OpcUaClient.md` with the full Part 13 catalog and which
 aggregates require server-side support; update
 `docs/Client.CLI.md` `historyread` page enumerating the new
 `--aggregate` values. Fixture: opc-plc historian support is limited —
 flag in `docs/drivers/OpcUaClient-Test-Fixture.md` that the new
 aggregates are unit-tested via the SDK's well-known NodeId set, not
 exercised wire-side. Integration test sweeps every enum value and
 asserts the mapping; gated-skip for aggregates the live opc-plc image
 doesn't honour. No e2e change.
 ---
 #### PR-14: `ServerUriArray` redundant failover (gap #14)
 **Goal**: read upstream `Server.ServerArray` /
 `ServerStatus.ServerArray` and `ServerRedundancyType.RedundancySupport` at
 session activation; when the upstream server advertises non-`None`
 redundancy, fail over mid-session on `ServiceLevel` drop without losing
 client subscriptions. Today our `EndpointUrls` is a one-shot connect-
 attempt list, not a live redundancy group.
 **SDK API**:
 - `Session.ReadValueAsync(VariableIds.Server_ServerStatus_ServerArray, ct)`
  → URI list
 - `Session.ReadValueAsync(VariableIds.Server_ServiceLevel, ct)` polled or
  subscribed via MonitoredItem
 - Subscribe `Server_ServiceLevel` on the existing alarm subscription so
  drops propagate via the publish channel
 - On low-`ServiceLevel`: open a parallel session against the next URI in
  `ServerArray`, `Session.TransferSubscriptionsAsync(otherSession, ...)`
  the live subscriptions, swap `Session` reference
 **Files**:
 - `src/.../OpcUaClient/OpcUaClientDriver.cs` — new
  `MonitorServerRedundancyAsync` method; integrate with the existing
  `OnKeepAlive` / `SessionReconnectHandler` machinery so reconnect and
  redundancy-failover share the subscription-transfer code path
 - `src/.../OpcUaClient/OpcUaClientDriverOptions.cs` — add
  `Redundancy: { Enabled, ServiceLevelThreshold (default 200) }`
 **Tests**: with two opc-plc containers behind the driver,
 artificially drop ServiceLevel on the active one and assert the
 secondary takes over; assert subscription handles stay valid.
 **Risks**: redundancy is the second-riskiest item after Reverse Connect.
 The SDK's `TransferSubscriptions` has known edge cases when the
 secondary's `SecureChannel` rejects the source-channel's authentication
 token; doc that the secondary must trust the same client cert as the
 primary.
 **Docs / fixture / e2e**: new "Upstream redundancy (`ServerArray`)"
 section in `docs/drivers/OpcUaClient.md` with the ServiceLevel
 threshold, the shared-cert prerequisite for `TransferSubscriptions`,
 and the ops runbook for forcing a failover; cross-link from
 `docs/Redundancy.md` (which today covers OUR server's redundancy —
 add a "vs upstream-side redundancy" note). Fixture: extend
 `Docker/docker-compose.yml` with a second `opc-plc-secondary` service
 on a different port; `OpcPlcFixture` gains a multi-endpoint variant.
 Integration test drops the active server's ServiceLevel and asserts
 the secondary takes over with subscription handles intact. E2E: add a
 `-PrimaryUrl` / `-SecondaryUrl` pair to
 `scripts/e2e/test-opcuaclient.ps1` (and matching keys to
 `scripts/e2e/e2e-config.sample.json`) that scripts a primary stop +
 asserts the bridge stage continues to pass.
 ---
 ## Documentation, fixture, and e2e impact
 Consolidated index of every doc page, fixture asset, and e2e script touched
 by the plan above. Authoritative for review — if a PR's `Docs / fixture /
 e2e` line references a path not listed here, that's a checklist gap.
 ### Driver user docs
 - `docs/drivers/OpcUaClient.md` — **create on first PR that needs it
  (PR-1)** if not present, then extend with one section per PR-1 through
  PR-14 covering: subscription tuning, per-tag deadband, OperationLimits
  handling, diagnostics counters, CRL/SHA1, FindServers, curation,
  type mirroring, methods, ModelChangeEvent, Reverse Connect, history
  events, aggregates, upstream redundancy.
 - `docs/drivers/OpcUaClient-Test-Fixture.md` — coverage map updated for
  curation (PR-7), Reverse Connect (PR-11), aggregates note (PR-13),
  redundancy multi-endpoint variant (PR-14).
 - `docs/Client.CLI.md` — extended for subscribe deadband syntax (PR-2),
  any `discover` command (PR-6), `call` command (PR-9), `historyread`
  event mode (PR-12), `--aggregate` enum expansion (PR-13).
 - `docs/Client.UI.md` — extended for Subscriptions tab deadband fields
  (PR-2), Browse-tree type rendering note (PR-8), Method-call surface
  (PR-9) if it ships.
 - `docs/security.md` — cross-link from PR-5 (CRL/SHA1 knobs).
 - `docs/Redundancy.md` — cross-link from PR-14 (note distinguishing
  server-side redundancy from upstream-side redundancy).
 ### Fixture assets
 - `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/Docker/docker-compose.yml`
  — add `opc-plc-rc` (PR-11) and `opc-plc-secondary` (PR-14) service
  variants; optional secured endpoint (PR-5).
 - `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/OpcPlcFixture.cs`
  — discovery probe at collection init (PR-6), reverse-connect listener
  (PR-11), multi-endpoint variant (PR-14), model-change helper (PR-10).
 - `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/OpcPlcProfile.cs`
  — flag noisy analogs for deadband (PR-2), enumerate exercised
  namespaces for curation (PR-7), record at least one custom ObjectType
  (PR-8).
 - New integration tests added per PR; all live under the existing
  `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/`
  collection.
 - Test certs (PR-5): SHA1-signed + revoked test fixtures checked into
  the unit-test project's resources.
 ### E2E scripts
 - `scripts/e2e/test-opcuaclient.ps1` — new stages added per PR (subscription
  tuning PR-1, deadband PR-2, diagnostics PR-4, CRL PR-5, discovery
  PR-6, curation PR-7, method call PR-9, topology change PR-10,
  reverse connect PR-11, history events PR-12, redundancy failover
  PR-14). The script is the single integration point for every
  driver-level e2e — keep the stages ordered top-down by phase.
 - `scripts/e2e/e2e-config.sample.json` — new keys: `deadband`,
  `discoveryUrl`, `includePath`, `namespaceRemap`, `methodNodeId`,
  `reverseConnect`, `primaryUrl`, `secondaryUrl`.
 - `scripts/e2e/test-all.ps1` — no structural change; the existing
  `opcuaclient` block forwards new params after wiring them through
  `e2e-config.sample.json`.
 ### Cross-driver impact (PR-12 — `IHistoryProvider.ReadEventsAsync`)
 PR-12 changes the `IHistoryProvider.ReadEventsAsync` signature in
 `Core.Abstractions` (or introduces a sibling `IEventHistoryProvider`
 — pinned in PR-12 review per Open Question 2). That decision is
 source-breaking for every driver that opts into history. PR-12 must
 add an explicit "interface change — adopt new signature when this
 driver implements `ReadEventsAsync`" note to:
 - `docs/plans/abcip-plan.md`
 - `docs/plans/ablegacy-plan.md`
 - `docs/plans/focas-plan.md`
 - `docs/plans/s7-plan.md`
 - `docs/plans/twincat-plan.md`
 - The Galaxy plan family — `docs/plans/galaxy-*.md` if/when those
  pages exist; Galaxy is the only current implementor and gets the
  real signature update in PR-12, not just a note.
 - The LMX plan — `docs/plans/lmx-*.md` if/when it lands (current state:
  the LMX driver's history surface is implicit through Galaxy; revisit
  during PR-12 review).
 - A Modbus plan page if/when one exists; Modbus does not implement
  history today but the heads-up note tracks the cross-driver shape.
 The cross-driver note text should be a one-paragraph "Heads up: the
 `IHistoryProvider.ReadEventsAsync` interface gained an
 `EventFilterSpec` parameter in OpcUaClient PR-12 (`docs/plans/opcuaclient-plan.md`).
 If/when this driver implements event-history, adopt the new signature."
 This pattern keeps each driver plan stable while the cross-cutting
 breakage is owned by one PR.
 ---
 ## Skip-rated items (for context)
 These featuregaps rows are **Build = No** and intentionally omitted from
 the plan above:
 | # | Gap | Why we're skipping |
 | :---: | --- | --- |
 | 3 | Multicast / LDS-ME registration | Server-side responsibility, not aggregator's. |
 | 4 | GDS push management (Part 12) | Significant infra; rare for our deployment scale. |
 | 11 | HistoryUpdate / Modified / Annotation passthrough | MES backfill scope; defer. |
 | 16 | Connection / session pooling for multi-instance scale-out | Premature; current per-instance model is simple and adequate. |
 | 18 | Kerberos / OAuth2 / JWT identity | Significant security work; defer until AD integration drives it (separate workstream). |
 | 19 | Write attribute scope beyond `Value` | Niche; rarely used in OPC UA practice. |
 If any of these get prioritized later they slot cleanly between the phases
 above — none have prerequisites among the Build = Yes items.
 ## Open questions
 1. **`ISubscribable` overload vs new method (PR-2)**: per-tag spec
   carrier is needed for deadband; do we extend the existing
   `SubscribeAsync` overload or add `SubscribeWithSpecsAsync`? The
   former is source-breaking but cleaner; the latter is additive but
   leaves two parallel paths.
 2. **`IHistoryProvider.ReadEventsAsync` shape (PR-12)**: does the
   `EventFilterSpec` parameter live on `IHistoryProvider` (one interface,
   every driver gets it) or on a sibling `IEventHistoryProvider` (two
   interfaces, only event-history drivers implement)? Memory entry
   suggests the former; preference depends on whether non-OPC-UA drivers
   ever expect to project arbitrary event fields. **Pin this in PR-12
   review.**
 3. **`IMethodInvoker` capability (PR-9)**: does this become the 9th
   capability interface (currently 8/8) or is it folded into
   `IWritable` as a method-invoke variant? Adding a 9th interface is
   the cleaner model and matches the spec layering.
 4. **Type mirroring address-space surface (PR-8)**: does
   `IAddressSpaceBuilder` already accept type nodes? If yes, PR-8 is
   straightforward; if no, it splits into a prerequisite PR-8a that
   extends the builder, then PR-8b for the OPC UA Client wire-up. The
   answer determines whether PR-8 ships in Phase 2 or slips to a later
   phase.
 5. **Reverse Connect listener ownership (PR-11)**: one listener per
   driver instance (port collision when multiple reverse-connect
   drivers run in the same process) vs one shared listener with a
   `expectedServerUri` dispatcher. Shared is the right answer; pin
   the singleton lifetime to the driver-host.
 6. **Phase 1 ship order**: PR-1, PR-3, PR-4, PR-5 are independent and can
   land in parallel. PR-2 depends on the `ISubscribable` interface
   decision (Q1) — recommend landing PR-1 first to validate the
   `OpcUaSubscriptionDefaults` shape, then PR-2.
--- a/docs/plans/s7-plan.md
+++ b/docs/plans/s7-plan.md
@@ -0,0 +1,807 @@
 # S7 Driver — Implementation Plan
 > Source of gap analysis: [featuregaps.md → S7](../featuregaps.md#s7-siemens-s7-3004001200--1500)
 >
 > Covers Build = Yes items only. Skip-rated rows are noted at the end for context.
 ## Summary
 The S7 driver (`src/ZB.MOM.WW.OtOpcUa.Driver.S7/`) ships a working scaffold over
 **S7netplus 0.20**: ISO-on-TCP / S7comm, single-connection-per-PLC (`SemaphoreSlim`),
 DB / M / I / Q / T / C address parsing, atomic scalar reads/writes for Bool / Byte
 / I16 / U16 / I32 / U32 / F32, polled `ISubscribable` overlay, `IHostConnectivityProbe`
 via `ReadStatusAsync`, and a Snap7-server-backed CI fixture on `localhost:1102`.
 The 16 Build = Yes gaps fall into six tractable phases. **The hard one is gap #1
 (S7-1500 Optimized DB / Symbolic addressing)** — S7netplus speaks classic S7comm
 only and cannot reach optimized DBs at all. Phase 6 calls that out as an explicit
 architectural decision: ship the constraint as documentation and the rest as
 S7netplus-compatible features, *or* fork to a library that supports S7Plus
 (Sharp7-fork, Snap7 v2, custom S7Plus). Phases 1-5 do not depend on that decision
 and are landable on the current S7netplus base.
 Every PR ships unit-test coverage and — where wire semantics matter — extends the
 Snap7-server profile in `Docker/server.py` so the integration fixture exercises
 the new path. PRs that need real S7-1500 firmware features the simulator doesn't
 mimic (PUT/GET protection, password-tier auth, SZL diagnostic buffer) call that
 out and gate the live-firmware test on the dev-box S7-1500 lab rig.
 Architectural invariants we explicitly preserve:
 - Single connection per PLC; `_gate` (SemaphoreSlim) serializes every PDU.
 - Strict address-parse-at-init; bad config fails fast with `FormatException`.
 - PUT/GET-disabled mapped to sticky `BadDeviceFailure`, not Polly-retried.
 - 100 ms minimum publishing interval (matches CPU mailbox scan reality).
 - `WriteIdempotent` per-tag flag is the only retry-policy lever.
 ## Phased delivery
 | Phase | Theme | PRs | Gaps closed |
 |------:|-------|-----|-------------|
 | 1 | Data-type correctness | PR-S7-A1..A5 | #7, #8, #9, #19 |
 | 2 | Performance — multi-tag PDU packing | PR-S7-B1..B2 | #3, #22 |
 | 3 | Operability knobs | PR-S7-C1..C5 | #2, #4, #20, #21, #24 |
 | 4 | Workflow — symbol import + UDTs | PR-S7-D1..D3 | #5, #6, #10 |
 | 5 | Diagnostics & security | PR-S7-E1..E2 | #11, #14 |
 | 6 | S7-1500 Optimized DB / Symbolic | PR-S7-F (decision) | #1 |
 Phases 1-3 run sequentially because Phase 2 packing and Phase 3 deadbands are
 both keyed off the type-decode work in Phase 1. Phase 4 (UDT/symbol import) is
 parallelizable with Phase 5; Phase 6 is gated on the library-choice decision
 in Open Questions (a).
 ---
 ## Per-PR detail
 ### Phase 1 — Data-type correctness
 #### PR-S7-A1 — 64-bit scalar types (LInt / ULInt / LReal / LWord)
 Closes gap #9. `Float64`/`Int64`/`UInt64` cases in `S7Driver.ReadOneAsync`/
 `WriteOneAsync` currently throw `NotSupportedException`.
 - **Files**: `S7Driver.cs` (read + write switch), `S7DriverOptions.cs` (extend
  `S7Size` with `LWord` for 8-byte access), `S7AddressParser.cs` (accept `DBL` /
  `LD` size suffix; S7netplus encodes 8-byte access via byte-array reads, so the
  parser converts `DB1.LD0` to a byte-range read internally).
 - **Tests**: unit decode tests for the byte-pattern → `long` / `ulong` / `double`
  conversion; Snap7-server profile gets `f64` and `i64` seed types.
 - **Risks**: S7netplus's `ReadAsync(string)` does not accept `LD` natively;
  fallback path is `Plc.ReadBytes(DataType.DataBlock, db, byteOffset, 8)` then
  `BitConverter` with explicit endian flip (S7 is big-endian on the wire,
  `BitConverter` is little-endian on x86/x64).
 - **Effort**: M (3-4 days incl. tests).
 - **Deps**: none.
 - **Docs / fixture / e2e**: extends the type-mapping table in `docs/v2/s7.md`
  with `LInt` / `ULInt` / `LReal` / `LWord` rows; adds the new sizes
  (`LInt`, `ULInt`, `LReal`) to the `read` / `write` cookbook in
  `docs/Driver.S7.Cli.md`; updates `docs/drivers/S7-Test-Fixture.md`
  §"What it actually covers" to list the new 64-bit types and removes them
  from §5 "Data types beyond the scalars"; extends the snap7 seed-type set
  in `tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/server.py`
  with `i64`, `u64`, `f64` cases; adds seeds at known offsets
  (e.g. `DB1.DBL40` for i64, `DB1.DBL48` for f64) to
  `Docker/profiles/s7_1500.json`; adds `S7_1500Profile` constants for the
  new tags + a `Driver_reads_seeded_64bit_batch` smoke test in
  `S7_1500SmokeTests`; adds an LInt loopback assertion to
  `scripts/e2e/test-s7.ps1`.
 #### PR-S7-A2 — STRING / WSTRING / CHAR / WCHAR
 Closes gap #8 (string portion). S7 `STRING(n)` is `[max-len][actual-len][bytes...]`
 (2-byte header + ASCII). `WSTRING(n)` is 4-byte header + UTF-16BE bytes. `CHAR`
 is 1 byte; `WCHAR` is 2 bytes UTF-16BE.
 - **Files**: `S7Driver.cs` (new `ReadStringAsync` / `WriteStringAsync` private
  helpers using `Plc.ReadBytes` for raw byte-range fetch), `S7DriverOptions.cs`
  (already has `StringLength`; add `S7DataType.WString`, `Char`, `WChar`).
 - **Tests**: unit tests for header parsing including the "actual-len > max-len"
  PLC bug case (clamp on read, reject on write); Snap7 `ascii` seed type already
  exists, add `wstring` seed.
 - **Risks**: write must respect the configured `StringLength` to avoid overrunning
  the DB; mismatched max-len is a common field bug.
 - **Effort**: M.
 - **Deps**: PR-S7-A1 (byte-range read helper lands there).
 - **Docs / fixture / e2e**: extends the type-mapping section in
  `docs/v2/s7.md` with `STRING(n)` / `WSTRING(n)` / `CHAR` / `WCHAR`
  layouts (2-byte vs 4-byte header, UTF-16BE encoding, the "actual-len >
  max-len" PLC bug); extends the `read` / `write` cookbook in
  `docs/Driver.S7.Cli.md` with `--type WString` / `--type Char` / `--type
  WChar` examples and the `--string-length` flag for WString; updates
  `docs/drivers/S7-Test-Fixture.md` §"What it actually covers" to list
  ascii/wstring/char/wchar; adds `wstring`, `char`, `wchar` seed types to
  `Docker/server.py` (existing `ascii` covers STRING); seeds a
  `DB1.WSTRING[256]` and a `DB1.CHAR[300]` in
  `Docker/profiles/s7_1500.json`; adds `Driver_round_trips_string_types`
  smoke test exercising read + write of every variant; adds a string
  round-trip assertion to `scripts/e2e/test-s7.ps1`.
 #### PR-S7-A3 — DTL / DATE_AND_TIME / S5TIME / TIME / TOD / DATE
 Closes gap #8 (date/time portion).
 - DTL is 12 bytes: year(u16) / month / day / weekday / hour / minute / second / nanos(u32).
 - DATE_AND_TIME (DT) is 8 bytes BCD: yy mm dd hh mm ss msH msL+dow.
 - S5TIME is 16-bit BCD with a 2-bit time-base.
 - TIME is `Int32` ms since 1972 (S7-300/400) or signed-ms duration (S7-1200/1500).
 - TOD is `UInt32` ms since midnight; DATE is `UInt16` days since 1990-01-01.
 - **Files**: `S7Driver.cs` + new `S7DateTimeCodec.cs` static class encapsulating
  every encode/decode (keep the driver lean; codec is unit-testable in isolation).
 - **Tests**: round-trip tests per type with golden byte vectors taken from the
  Siemens "STEP 7 V18 — Programming Reference" document. Snap7-server seed
  profile gains `dtl`, `dt`, `s5time`, `time` types.
 - **Risks**: BCD parsing must reject invalid month/day combinations; PLC programs
  occasionally write 0x00 0x00 ... when uninitialized — surface as `BadOutOfRange`
  rather than parsing to year 0.
 - **Effort**: L (4-5 days incl. all six types and the golden-vector suite).
 - **Deps**: PR-S7-A1.
 - **Docs / fixture / e2e**: extends `docs/v2/s7.md` with a new "Date / time
  types" subsection documenting DTL / DT (BCD) / S5TIME / TIME / TOD /
  DATE byte layouts and the S7-300/400 vs S7-1200/1500 TIME-encoding
  split; adds `--type Dtl` / `--type DateAndTime` / `--type S5Time` /
  `--type Time` / `--type TimeOfDay` / `--type Date` to the
  `docs/Driver.S7.Cli.md` cookbook; updates
  `docs/drivers/S7-Test-Fixture.md` §"What it actually covers" with the
  new datetime types and removes "DTL / DATE_AND_TIME" from §5 "Data
  types beyond the scalars"; adds `dtl`, `dt`, `s5time`, `time`, `tod`,
  `date` seed types to `Docker/server.py` with golden-byte vectors
  documented in comments; seeds `DB1.DTL[260]`, `DB1.DT[272]`,
  `DB1.S5TIME[280]`, `DB1.TIME[284]`, `DB1.TOD[288]`, `DB1.DATE[292]` in
  `Docker/profiles/s7_1500.json`; adds
  `S7DateTimeCodecTests` (unit) + `Driver_round_trips_datetime_types`
  smoke test; no `scripts/e2e/test-s7.ps1` change required (CLI cookbook
  examples cover the manual surface).
 #### PR-S7-A4 — Array tags (ValueRank=1)
 Closes gap #7. `S7TagDefinition` currently has no array dimension; `MapDataType`
 hard-codes `IsArray: false`.
 - **Files**: `S7DriverOptions.cs` (extend `S7TagDefinition` with `ArrayDim` int?
  and `ElementCount` int?), `S7Driver.cs` (read path: detect array tag, issue
  one byte-range read covering N elements, slice client-side; write path: same
  in reverse), `DiscoverAsync` reports `IsArray: true, ArrayDim: [N]`.
 - **Tests**: unit tests for `Array[0..9] of Int` and `Array[0..9] of Real`;
  Snap7-server profile adds an array seed type. Round-trip array-write test
  proves slice ordering.
 - **Risks**: S7-1500 supports multi-dim arrays; declare ValueRank=1 only and
  document multi-dim as a follow-up. Array-of-UDT lands with PR-S7-D2.
 - **Effort**: M.
 - **Deps**: PR-S7-A1 (byte-range reads).
 - **Docs / fixture / e2e**: adds an "Array tags (ValueRank=1)" subsection
  to `docs/v2/s7.md` documenting `Array[0..N]` syntax + the multi-dim
  follow-up note; extends `docs/Driver.S7.Cli.md` with an
  `--array-count N` flag in the `read` / `write` cookbook and worked
  examples for `Array[0..9] of Int` and `Array[0..9] of Real`; updates
  `docs/drivers/S7-Test-Fixture.md` §"What it actually covers" to list
  array round-trips and removes "arrays of structs" from §5 (struct
  arrays land in PR-S7-D2); extends `Docker/server.py` with an `array`
  meta-seed-type that takes an inner-type + count and lays out N elements
  contiguously; seeds `DB1.ArrayInt[300]` (10×Int) and
  `DB1.ArrayReal[320]` (10×Real) in `Docker/profiles/s7_1500.json`;
  adds `Driver_round_trips_array_int10` + `Driver_round_trips_array_real10`
  smoke tests proving slice ordering; adds an array round-trip assertion
  to `scripts/e2e/test-s7.ps1`.
 #### PR-S7-A5 — LOGO! 8 + S7-200 V-memory area
 Closes gap #19. `S7AddressParser` currently rejects the `V` area letter.
 - **Files**: `S7AddressParser.cs` (add `V` case → maps to `S7Area.DataBlock` with
  `DbNumber=1` for S7-200 / DbNumber per LOGO! VM-mapping table; document the
  conversion), `S7DriverOptions.cs` (note CpuType-dependent meaning of V).
 - **Tests**: unit tests for `VW0` / `VD4` / `V0.0` parsing, both S7-200 and
  LOGO! conventions; document caller responsibility to set `CpuType.S7200` or
  `S7200Smart`.
 - **Risks**: LOGO! VM base address differs by firmware (V0=0 vs V0=1024 depending
  on block); document the offset table rather than auto-detecting.
 - **Effort**: S (1-2 days, mostly parser + tests; no wire changes).
 - **Deps**: none.
 - **Docs / fixture / e2e**: adds a "LOGO! 8 / S7-200 V-memory" subsection
  to `docs/v2/s7.md` covering the `V` area letter, the `S7200` /
  `S7200Smart` CpuType pre-requisite, the LOGO! VM-mapping table by
  firmware band, and the "V0 = DB1.DBX0.0" semantic; extends the address
  grammar cheat sheet in `docs/Driver.S7.Cli.md` with `VW0` / `VD4` /
  `V0.0` rows and a `-c S7200Smart` worked example; updates
  `docs/drivers/S7-Test-Fixture.md` §"What it does NOT cover" item 4 to
  note S7-200 / LOGO! parser coverage now exists at unit level; adds
  unit-only `S7AddressParserTests` cases — no Snap7 fixture change
  (server.py already exposes DB1, which is where V-memory aliases land);
  no `scripts/e2e/test-s7.ps1` change required (live-LOGO! testing is
  documented as field-only).
 ### Phase 2 — Performance (multi-tag PDU packing + block coalescing)
 #### PR-S7-B1 — Multi-variable PDU packing
 Closes gap #3. `ReadAsync(IReadOnlyList<string>)` currently issues one
 `plc.ReadAsync` per tag inside the semaphore — N PDUs for N tags.
 - **Files**: `S7Driver.cs` (replace per-tag loop with a packer that builds a
  list of `S7.Net.Types.DataItem`, calls `plc.ReadMultipleVarsAsync`, then
  fans the results back to the per-tag decoder). Keep the existing per-tag
  decode switch — only the wire fetch becomes batched.
 - **Tests**: integration test that subscribes to 100 tags and asserts the
  packet count seen by the Snap7 server is 1 (or N / packing-budget) rather
  than 100. Unit-level test covers packer chunking when the negotiated PDU
  size won't fit all items.
 - **Risks**: `ReadMultipleVarsAsync` errors are per-item; we must surface
  per-tag StatusCodes correctly rather than failing the whole batch on one
  bad tag. Packing budget = `negotiatedPduSize - 18 (header) - per_item(12)`,
  conservatively cap at 19 items per PDU on a 240-byte PDU.
 - **Effort**: L (5-6 days incl. the per-item-error fan-out semantics).
 - **Deps**: Phase 1 PRs do not block this — but conflicts in `S7Driver.cs`
  are likely, so land Phase 1 first.
 - **Docs / fixture / e2e**: adds a "Performance — multi-variable PDU
  packing" subsection to `docs/v2/s7.md` describing
  `ReadMultipleVarsAsync`, the negotiated-PDU packing budget formula
  (`pdu - 18 - 12·N`), the 19-items-per-240-byte-PDU rule of thumb, and
  the per-item-error semantics; no `docs/Driver.S7.Cli.md` change (CLI
  is single-tag); no Snap7-server seed change required (existing seeds
  cover the wire path); adds
  `S7MultiVarPduPackingTests` to the unit suite (planner chunking when
  items don't fit) + a 100-tag perf integration test
  `Driver_packs_100_tags_into_minimum_pdus` that asserts request-count
  reduction; no `scripts/e2e/test-s7.ps1` change required.
 #### PR-S7-B2 — Block-read coalescing for contiguous DBs
 Closes gap #22. Reading `DB1.DBW0`, `DB1.DBW2`, `DB1.DBW4` should issue one
 6-byte byte-range read against DB1 starting at offset 0, sliced client-side.
 - **Files**: `S7Driver.cs` adds a planner pass: group same-DB tags by
  contiguous byte ranges (gap-merge threshold = configurable, default 16
  bytes; over-fetching 16 bytes is cheaper than one extra PDU). Merged ranges
  become a single `Plc.ReadBytes` call; the result is sliced per-tag.
 - **Tests**: unit tests for the merge planner (input list → expected ranges);
  integration test with 50 contiguous DB words proves wire-level reduction.
 - **Risks**: STRINGs / arrays should opt out of merging because the per-tag
  byte size is variable. Add an "opaque-size" flag so the planner skips them.
 - **Effort**: M.
 - **Deps**: PR-S7-B1 (the multi-var packer). The two interact: the planner
  emits sum-reads, then the packer puts multiple sum-reads on one PDU.
 - **Docs / fixture / e2e**: extends the §"Performance" section in
  `docs/v2/s7.md` with a "Block-read coalescing" subsection — the
  default 16-byte gap-merge threshold, the opaque-size opt-out for
  STRINGs / arrays, and operator guidance for tuning the threshold per
  DB; no CLI doc change; no Snap7-server seed change (existing
  contiguous DB1 seeds — DBW0 / DBW10 / DBD20 — already exercise
  contiguous-merge); adds
  `S7BlockCoalescingPlannerTests` (unit) covering the merge planner +
  opaque opt-out; adds a 50-contiguous-DBW integration test
  `Driver_coalesces_contiguous_DBWs_into_single_byte_range_read` that
  asserts wire-level reduction; no `scripts/e2e/test-s7.ps1` change.
 ### Phase 3 — Operability
 #### PR-S7-C1 — PDU size negotiation surfaced
 Closes gap #2. S7netplus's `Plc` instance exposes the negotiated PDU size after
 `OpenAsync` via `Plc.MaxPDUSize`.
 - **Files**: `S7Driver.cs` (read `Plc.MaxPDUSize` after open, store on
  `_health`; expose via `GetHealth().Diagnostics["NegotiatedPduSize"]` —
  this requires adding a `Diagnostics` dictionary to `DriverHealth`, which
  is a Core change). Operator-visible via the Admin UI driver-diagnostics
  panel that already renders Modbus diagnostic stats.
 - **Tests**: integration test asserts the value is non-zero after init.
 - **Risks**: `DriverHealth` extension must be backward-compatible — existing
  drivers should still compile against the unchanged record. Make the new
  property nullable with a default of `null`.
 - **Effort**: S.
 - **Deps**: Core `DriverHealth` shape change (single PR coordinated with
  the Modbus diagnostic surface).
 - **Docs / fixture / e2e**: adds a "Diagnostics surfacing" subsection to
  `docs/v2/s7.md` documenting the `Diagnostics["NegotiatedPduSize"]`
  surface + how it renders in the Admin UI driver-diagnostics panel;
  no CLI doc change (CLI doesn't expose diagnostics); updates
  `docs/drivers/S7-Test-Fixture.md` §"What it actually covers" with a
  "negotiated PDU size surfaces in driver health" line; no Snap7
  seed-type change (snap7's PDU negotiation is fixed at 240 bytes —
  document the fixture's negotiated size in the README); adds
  `Driver_exposes_negotiated_pdu_size_post_init` smoke test asserting
  the value is non-zero; no `scripts/e2e/test-s7.ps1` change.
 #### PR-S7-C2 — TSAP / Connection Type selector
 Closes gap #4. S7netplus picks PG-class TSAPs by default; hardened CPUs may
 require OP / S7-Basic / Other.
 - **Files**: `S7DriverOptions.cs` (new `TsapMode` enum: `Auto` / `Pg` / `Op` /
  `S7Basic` / `Other`; `Auto` preserves current behavior. Optional
  `LocalTsap` / `RemoteTsap` `ushort?` for explicit override). `S7Driver.cs`
  branches on the mode to pick the S7netplus `Plc(CpuType, ...)` constructor
  vs the `Plc(string ip, byte rack, byte slot, ushort localTsap, ushort remoteTsap)`
  raw-TSAP overload. Document the raw-TSAP table in `docs/v2/s7.md`.
 - **Tests**: unit test on the mode → TSAP-byte mapping; live-firmware test
  documented but only runnable against the dev-box S7-1500 lab rig.
 - **Risks**: wrong TSAP causes connection refused at handshake — same failure
  shape as wrong slot. Document the mapping prominently.
 - **Effort**: M.
 - **Deps**: none.
 - **Docs / fixture / e2e**: adds a "TSAP / Connection Type" section to
  `docs/v2/s7.md` covering the `TsapMode` enum, the raw-TSAP table
  (PG = 0x0100/0x0102, OP = 0x0200/0x0202, S7-Basic = 0x0300/0x0302,
  Other = caller-supplied), and the hardened-CPU motivation; adds
  `--tsap-mode` and `--local-tsap` / `--remote-tsap` flags to
  `docs/Driver.S7.Cli.md`'s common-flags table with a worked example
  hitting an OP-class TSAP; no Snap7 seed change (snap7 accepts any
  TSAP from the CLI, so the unit-level mapping test is sufficient); no
  smoke test change (live-firmware-only); no `scripts/e2e/test-s7.ps1`
  change.
 #### PR-S7-C3 — Per-tag scan group / publish rate
 Closes gap #20. `SubscribeAsync` takes one publishing interval for the whole
 list; mixed 100 ms / 1 s / 10 s tags need three subscribe calls today.
 - **Files**: `S7DriverOptions.cs` (extend `S7TagDefinition` with optional
  `ScanGroup` string). `S7Driver.cs` (`SubscribeAsync` partitions the input
  list into one poll loop per distinct interval; `PollGroupEngine`-style
  internal group, but driver-local — same engine the TwinCAT driver uses).
 - **Tests**: unit test with three tags at three rates asserts three independent
  poll-tick streams; integration test asserts no group starves the others.
 - **Risks**: the `_gate` semaphore still serializes — three poll loops can
  contend. Document the contention as part of the "1 connection / 1 mailbox"
  invariant; if it bites, follow-up adds a fairness queue.
 - **Effort**: M.
 - **Deps**: none.
 - **Docs / fixture / e2e**: adds a "Per-tag scan groups" subsection to
  `docs/v2/s7.md` documenting `S7TagDefinition.ScanGroup`, the multi-rate
  partitioning semantics, and the `_gate` contention caveat; no CLI doc
  change (CLI is single-tag); no Snap7 seed change required (existing
  scalar seeds suffice); adds `S7ScanGroupPartitioningTests` (unit) +
  `Driver_three_scan_groups_publish_independently` smoke test that
  subscribes 3 tags at 100 ms / 1 s / 10 s rates and asserts
  independent tick streams; no `scripts/e2e/test-s7.ps1` change
  (subscribe assertion already covers the polling path).
 #### PR-S7-C4 — Deadband / on-change with thresholds
 Closes gap #21. `PollOnceAsync` currently does `!Equals(prev, current)` only —
 no analog deadband.
 - **Files**: `S7DriverOptions.cs` (extend `S7TagDefinition` with
  `DeadbandAbsolute double?` and `DeadbandPercent double?`). `S7Driver.cs`
  (`PollOnceAsync` evaluates per-tag deadband for numeric types; non-numeric
  types fall through to exact equality).
 - **Tests**: unit tests for absolute and percent deadbands at edge cases
  (NaN, ±Infinity, sign flip, near-zero percent).
 - **Risks**: percent deadband against a zero baseline diverges; document and
  fall back to absolute when |baseline| < 1e-6.
 - **Effort**: S.
 - **Deps**: PR-S7-C3 helpful but not required.
 - **Docs / fixture / e2e**: adds a "Deadband / on-change" subsection to
  `docs/v2/s7.md` documenting `DeadbandAbsolute` / `DeadbandPercent` per
  tag, NaN / ±Infinity / sign-flip / near-zero-percent edge cases, and
  the |baseline| < 1e-6 fallback; no CLI doc change (CLI's `subscribe`
  already polls on change); no Snap7 seed change; adds
  `S7DeadbandTests` (unit) covering all edge cases — no integration test
  required since deadband is pre-publish filtering inside the polling
  loop; no `scripts/e2e/test-s7.ps1` change.
 #### PR-S7-C5 — Pre-flight PUT/GET enablement test
 Closes gap #24. We currently surface `BadDeviceFailure` only at first read.
 Add a pre-flight check during `InitializeAsync` (after `OpenAsync`) that issues
 one trivial read (`MW0` or the configured `Probe.ProbeAddress`) and surfaces
 the dedicated diagnostic message before declaring `DriverState.Healthy`.
 - **Files**: `S7Driver.cs` (`InitializeAsync` adds the probe read; on
  `S7.Net.PlcException` with the PUT/GET-disabled error code, throw a
  typed `S7PutGetDisabledException` with a configuration-fix hint).
 - **Tests**: integration test toggles a Snap7 simulator quirk that mimics
  the PUT/GET-disabled response (Snap7 doesn't model this; gate the test
  on a `--with-real-plc` opt-in or document as live-firmware-only).
 - **Risks**: pre-flight against a real `Probe.ProbeAddress` requires the
  address to exist in the PLC; document that the default `MW0` is fine for
  most installs but allow `null` / "skip" for sites that haven't wired one.
 - **Effort**: S.
 - **Deps**: none.
 - **Docs / fixture / e2e**: extends the "PUT/GET must be enabled" section
  of `docs/Driver.S7.Cli.md` with the new typed
  `S7PutGetDisabledException` message + the "skip pre-flight" knob;
  adds the same content as a "Pre-flight PUT/GET enablement" subsection
  in `docs/v2/s7.md`; no Snap7 seed change (snap7 doesn't model
  PUT/GET-disabled — the test for the success path uses the existing
  MW0 seed); adds `Driver_preflight_passes_when_probe_address_seeded`
  smoke test; documents the live-firmware test as gated on a
  `--with-real-plc` opt-in flag in `docs/drivers/S7-Test-Fixture.md`
  §"Follow-up candidates"; no `scripts/e2e/test-s7.ps1` change (probe
  test already runs first).
 ### Phase 4 — Workflow (symbol import + UDTs + instance DBs)
 #### PR-S7-D1 — Symbol-table / TIA Portal export browse
 Closes gap #5. Operators currently hand-edit `S7TagDefinition` JSON. TIA Portal
 exports symbols as **`.s7p` archive → External tags → CSV / SDF**. The lighter
 target is the CSV format used by the "Generate source from blocks" exporter.
 - **Files**: new `src/ZB.MOM.WW.OtOpcUa.Driver.S7/SymbolImport/` directory:
  - `TiaCsvImporter.cs` — parses TIA Portal "Show all tags" CSV (`Name`,
    `Address`, `Data type`, `Comment`, `Visible in HMI`). Output: list of
    `S7TagDefinition`.
  - `AwlImporter.cs` — best-effort AWL `VAR_GLOBAL` / `DATA_BLOCK` parser
    for legacy STEP 7 Classic projects.
 - **Files (Admin UI)**: a "Import S7 symbols" button on the Driver Tags tab
  that POSTs the file to a new `POST /api/drivers/{id}/import-s7-symbols`
  endpoint and reports the diff.
 - **Tests**: unit tests with golden-input CSV / AWL fixtures; round-trip
  test that imports → produces tags → reads against simulator.
 - **Risks**: TIA Portal CSV is locale-dependent (decimal-comma in DE locale).
  Detect from the header row and accept both. UDT-typed symbols import as
  a placeholder until PR-S7-D2.
 - **Effort**: L (5-7 days incl. the Admin UI flow).
 - **Deps**: see Open Question (c) — confirm CSV+AWL is the right scope, or
  whether `.s7p` / `.zip` archive parsing is required.
 - **Docs / fixture / e2e**: adds new doc
  `docs/drivers/S7-TIA-Import.md` documenting the supported TIA Portal
  CSV format (column names, locale-comma detection, UDT-typed
  placeholders) and the AWL `VAR_GLOBAL` / `DATA_BLOCK` parser scope;
  cross-links it from `docs/v2/s7.md`'s new "Symbol import" section
  and from `docs/Driver.S7.Cli.md` with a future `import` subcommand
  hook; adds golden-input fixtures
  `tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Fixtures/sample_tia_export.csv`,
  `sample_tia_export_de_locale.csv`, and `sample_step7_classic.awl`;
  no Snap7 seed change required (existing DB1 seeds support
  the import-then-read round-trip); adds `TiaCsvImporterTests` and
  `AwlImporterTests` (unit) + `Driver_imports_csv_then_reads_seeded_tags`
  integration test that imports the sample CSV → reads via Snap7;
  no `scripts/e2e/test-s7.ps1` change (Admin-UI flow has its own
  end-to-end coverage in the Admin UI test suite).
 #### PR-S7-D2 — UDT / STRUCT / nested-DB handling
 Closes gap #6. Today's tag map is flat scalar-only; UDT-typed DBs are
 unusable without hand-flattening every member.
 - **Files**: `S7DriverOptions.cs` (extend `S7TagDefinition` with `UdtName string?`;
  alongside, a new `IReadOnlyList<S7UdtDefinition> Udts` on the options that
  declares the layout: name, ordered members `(Name, Offset, S7DataType, ArrayDim?)`).
  `S7Driver.cs` fans a UDT-typed tag into per-member sub-tags at `InitializeAsync`,
  so the read/write path stays scalar-only.
 - **Tests**: unit tests for fan-out with nested UDTs (UDT-of-UDT); integration
  test with a Snap7 DB seeded as a UDT-shape byte array proves the fan-out
  decodes correctly.
 - **Risks**: UDT-of-UDT arbitrary nesting depth — cap at 4 levels and reject
  deeper with a clear error. Optimized DBs would let TIA reorder members,
  re-introducing gap #1; document that user-defined UDTs require "Optimized
  block access" off, same as the general DB rule.
 - **Effort**: L (1-2 weeks).
 - **Deps**: PR-S7-D1 (symbol importer drops UDT-typed entries with a
  placeholder; D2 makes those usable).
 - **Docs / fixture / e2e**: adds a "UDT / STRUCT support" section to
  `docs/v2/s7.md` documenting `S7UdtDefinition`, the fan-out
  semantics, the 4-level nesting cap, and the "Optimized block access
  must be off" prerequisite; extends `docs/drivers/S7-TIA-Import.md`
  (created in PR-S7-D1) with a UDT-typed-entry section showing how
  the importer + `Udts` declaration cooperate; updates
  `docs/drivers/S7-Test-Fixture.md` §"What it does NOT cover" item 5 to
  remove "UDT fan-out"; extends `Docker/server.py` with a
  `udt_layout` meta-seed-type that lays out per-member offsets within
  a DB byte range; seeds a `DB1.MyUdt[400]` (e.g. Real + Int + Bool)
  in `Docker/profiles/s7_1500.json`; adds `S7UdtFanOutTests` (unit) +
  `Driver_fans_out_udt_into_member_tags` integration test covering a
  nested-UDT case; adds a UDT-member round-trip assertion to
  `scripts/e2e/test-s7.ps1`.
 #### PR-S7-D3 — Instance-DB / FB parameter access
 Closes gap #10. Multi-instance FBs are addressed symbolically (`MyFB_Instance.MyParam`)
 with no fixed absolute DB byte offset visible without a TIA project export.
 - **Files**: extends PR-S7-D1's importer to recognize "instance DB" entries
  (TIA export shows them with a different "DB type" column value); the
  importer translates `MyFB_Instance.MyParam` to the resolved
  `DBn.DBW_offset` based on the FB's interface declaration in the export.
 - **Tests**: golden-input test with an FB-instance DB export; resolved
  addresses match Siemens reference.
 - **Risks**: when the FB interface changes (TIA "online change"), instance-DB
  layouts shift. Document that re-import is required after any FB-interface
  edit. Eventually surface this as a startup warning when the symbol-table
  hash differs from the imported snapshot — out of scope for this PR.
 - **Effort**: M.
 - **Deps**: PR-S7-D1, PR-S7-D2.
 - **Docs / fixture / e2e**: extends `docs/drivers/S7-TIA-Import.md` with
  an "Instance DBs / FB parameters" section covering the importer's
  `MyFB_Instance.MyParam` → `DBn.DBW_offset` resolution, the "DB type"
  column convention, and the "re-import on FB-interface edit" caveat;
  adds the same caveat as a paragraph in `docs/v2/s7.md`'s "UDT /
  STRUCT" section; adds a golden-input fixture
  `Fixtures/sample_tia_export_with_fb_instance.csv` to the integration
  tests; no Snap7 seed change required (resolved addresses land in DB1
  which the existing seeds back); adds
  `InstanceDbResolverTests` (unit) +
  `Driver_resolves_fb_instance_then_reads_seeded_member` integration
  test; no `scripts/e2e/test-s7.ps1` change (FB-instance lookup is an
  import-time concern).
 ### Phase 5 — Diagnostics & security
 #### PR-S7-E1 — CPU diagnostic buffer / SZL reads
 Closes gap #11. SZL (System Status List) IDs surface CPU type, firmware
 version, cycle-time min/avg/max, and the diagnostic-buffer entries.
 - **Files**: `S7Driver.cs` exposes a small set of "system tags" alongside
  `Tags` — virtual addresses prefixed `@System.` that the read path
  recognizes and dispatches to S7netplus's `ReadSzlAsync` (or, if not
  exposed, a raw `Plc.ReadBytes` against the SZL-via-S7comm sub-protocol):
  - `@System.CpuType`, `@System.Firmware`, `@System.OrderNo` — SZL 0x0011
  - `@System.CycleMs.Min` / `.Max` / `.Avg` — SZL 0x0132 / 0x0432
  - `@System.DiagBuffer[0..N]` — SZL 0x00A0 ring-buffer entries
 - **Files (discovery)**: `DiscoverAsync` adds a `Diagnostics/` subfolder
  with the system-tag set when `S7DriverOptions.ExposeSystemTags = true`.
 - **Tests**: unit tests for the SZL response parser (golden bytes); live-
  firmware test against the dev-box S7-1500.
 - **Risks**: S7netplus's SZL surface is incomplete; may need a raw
  `Plc.ReadBytes` against `0x84` register or a small SZL-PDU helper.
 - **Effort**: M-L.
 - **Deps**: PR-S7-C1 (`DriverHealth.Diagnostics` dictionary already there).
 - **Docs / fixture / e2e**: adds a "CPU diagnostics (SZL)" section to
  `docs/v2/s7.md` listing the exposed `@System.*` virtual addresses, the
  underlying SZL IDs, and the `ExposeSystemTags` opt-in; extends
  `docs/Driver.S7.Cli.md` with a worked `read -a @System.CpuType` example
  in the cookbook; updates `docs/drivers/S7-Test-Fixture.md` §"What it
  does NOT cover" with a note that snap7 does not implement SZL — golden-
  byte unit tests cover the parser, live SZL is gated on a real S7-1500;
  no Snap7 seed change (snap7 returns a fixed handshake banner that the
  test checks for "SZL not supported on simulator" branch); adds
  `S7SzlParserTests` (unit) with golden bytes; documents the live SZL
  test in `docs/drivers/S7-Test-Fixture.md` §"Follow-up candidates"; no
  `scripts/e2e/test-s7.ps1` change.
 #### PR-S7-E2 — PLC password / protection-level handling
 Closes gap #14. S7-300/400 protection levels 1-3 and S7-1200/1500 connection
 mechanisms can require a password on connect.
 - **Files**: `S7DriverOptions.cs` (new `Password string?` and `ProtectionLevel`
  enum). `S7Driver.cs` calls S7netplus's `SetPassword` (if the API surfaces it
  — newer S7netplus versions ship `Plc.SendPassword(string)`; if not, raw-PDU
  fallback per Siemens "Communication Function Manual" §5.2).
 - **Tests**: live-firmware-gated; password-tier failure modes don't reproduce
  in Snap7. Unit-level coverage for the options-binding shape only.
 - **Risks**: S7netplus may not expose password auth — fallback is to call into
  the lower-level `S7.Net.S7Protocol` types or to fork. Land the options
  surface unconditionally, gate the wire path on library support, document
  the limitation if the library doesn't oblige.
 - **Effort**: M (S if S7netplus ships it; L if we need a fallback path).
 - **Deps**: none.
 - **Docs / fixture / e2e**: adds a "PLC password / protection levels"
  section to `docs/v2/s7.md` documenting the `Password` /
  `ProtectionLevel` options + the S7-300/400 levels 1-3 vs S7-1200/1500
  connection-mechanism semantics + the "limitation if S7netplus
  doesn't ship `SendPassword`" note; adds a `--password` flag to
  `docs/Driver.S7.Cli.md`'s common-flags table with a hardened-CPU
  worked example; updates `docs/drivers/S7-Test-Fixture.md` §"What it
  does NOT cover" with a "password / protection levels not modelled by
  snap7" note; no Snap7 seed change (snap7 doesn't enforce protection
  levels); adds options-binding unit tests only — no integration test
  (live-firmware-only); no `scripts/e2e/test-s7.ps1` change.
 ### Phase 6 — S7-1500 Optimized DB / Symbolic addressing (decision PR)
 #### PR-S7-F — Optimized DB / S7Plus
 Closes gap #1. **This is an architectural decision PR, not a code PR.**
 S7netplus speaks classic S7comm only. Optimized DBs on S7-1500 (default for
 new TIA projects) reorder fields and have no fixed byte offsets — absolute
 `DB1.DBW0` reads return `BadDeviceFailure`. Three tracks:
 1. **Document the constraint and stay on S7netplus.** Operators must uncheck
   "Optimized block access" in TIA Portal for any DB the driver reads. This
   is what the test fixture already documents. Effort: S (docs only).
 2. **Migrate to a library that supports S7Plus.**
   - **Snap7 v2 / `Snap7Net`** — C-library wrapper, supports classic S7comm
     only (same limitation as S7netplus). Not a fix.
   - **Sharp7 fork** — community fork of Snap7 with **partial** S7-1200/1500
     PUT/GET semantics. Still classic S7comm.
   - **Custom S7Plus implementation** — Wireshark dissector exists; reverse
     engineering is substantial. Effort: ≥ 4 weeks; ongoing protocol-version
     maintenance. Risk: Siemens has not published S7Plus.
 3. **Embed an OPC UA → OPC UA bridge to the S7-1500's onboard OPC UA server.**
   The S7-1500 V2.5+ exposes its own OPC UA server with full symbolic access.
   Our `OPC UA Client driver` (already shipping per memory) could read the
   target CPU's OPC UA server and re-publish — sidesteps S7Plus entirely.
   Effort: S; semantics: requires the customer to license Siemens OPC UA
   on the CPU. Most modern S7-1500 deployments already license it.
 **Recommendation**: ship Track 1 docs immediately (closes the operator
 expectation gap) and Track 3 as the Optimized-DB workflow path (re-uses
 existing OPC UA Client driver). Track 2 (S7Plus reverse-engineering) is
 out of scope unless a customer pays for it.
 - **Files**: `docs/v2/s7.md` (Optimized DB section + how to disable),
  `docs/featuregaps.md` row #1 updated to reflect the Track 1+3 decision.
 - **Tests**: live-firmware test against the dev-box S7-1500 with optimized
  block access toggled both ways, asserting `BadDeviceFailure` vs
  successful read.
 - **Risks**: Track 3's OPC-UA-Client-bridging needs Admin UI plumbing to
  configure; that's a larger workstream tracked separately.
 - **Effort**: S (docs + decision); L if Track 2 is taken.
 - **Deps**: Open Question (a) below.
 - **Docs / fixture / e2e**: rewrites `docs/v2/s7.md` to land a
  prominent "Optimized DB constraint" section at the top — explicitly
  documents the S7-1200 V4.0+ / S7-1500 default, the
  `BadDeviceFailure` shape on absolute `DB1.DBW0` reads against an
  optimized DB, the "Uncheck Optimized block access in TIA Portal"
  fix, and the recommended **bridge-via-OpcUaClient** pattern with a
  worked example (Siemens S7-1500 V2.5+ onboard OPC UA server →
  `OpcUaClient` driver → re-publish on the OtOpcUa server's address
  space); updates `docs/featuregaps.md` row #1 to reflect the
  Track 1+3 decision; updates the "Optimized-DB" line of
  `docs/drivers/S7-Test-Fixture.md` §"What it does NOT cover" item 4
  to point at the new doc; no CLI doc change (CLI is a probe tool, not
  the bridging path); no Snap7 fixture change (snap7 has no Optimized-
  DB mode); the live-firmware test toggling Optimized block access on
  / off is recorded as a manual checklist in
  `docs/drivers/S7-Test-Fixture.md` §"Follow-up candidates" and gated
  behind `--with-real-plc`; if Track 2 is taken later, this PR's doc
  surface becomes the migration baseline; no `scripts/e2e/test-s7.ps1`
  change.
 ---
 ## Documentation, fixture, and e2e impact
 Consolidated view of every per-PR `Docs / fixture / e2e` line above, so a
 reviewer can see the cross-cutting churn at a glance and so the doc /
 fixture / e2e maintainers can sequence their work alongside the code PRs.
 ### User-facing documentation churn
 | PR | `docs/v2/s7.md` | `docs/Driver.S7.Cli.md` | `docs/drivers/S7-Test-Fixture.md` | New / cross-cut docs |
 |----|-----------------|-------------------------|------------------------------------|----------------------|
 | PR-S7-A1 (LInt/ULInt/LReal/LWord) | extend type-mapping table | new sizes in cookbook | remove "no 64-bit types" | — |
 | PR-S7-A2 (STRING/WSTRING/CHAR/WCHAR) | string layout subsection | `--type WString` / `--string-length` | list new types | — |
 | PR-S7-A3 (DTL/DT/S5TIME/TIME/TOD/DATE) | "Date / time types" subsection | datetime cookbook entries | list new types | — |
 | PR-S7-A4 (arrays) | "Array tags (ValueRank=1)" subsection | `--array-count` flag + examples | list array round-trips | — |
 | PR-S7-A5 (V-memory) | "LOGO! 8 / S7-200 V-memory" subsection | grammar table + S7200Smart example | parser coverage note | — |
 | PR-S7-B1 (PDU packing) | "Performance — multi-variable PDU packing" subsection | — | — | — |
 | PR-S7-B2 (block coalescing) | "Block-read coalescing" subsection | — | — | — |
 | PR-S7-C1 (negotiated PDU diag) | "Diagnostics surfacing" subsection | — | "negotiated PDU size" line | — |
 | PR-S7-C2 (TSAP) | "TSAP / Connection Type" section | `--tsap-mode` / `--local-tsap` / `--remote-tsap` flags | — | — |
 | PR-S7-C3 (scan groups) | "Per-tag scan groups" subsection | — | — | — |
 | PR-S7-C4 (deadband) | "Deadband / on-change" subsection | — | — | — |
 | PR-S7-C5 (PUT/GET pre-flight) | "Pre-flight PUT/GET enablement" subsection | extend "PUT/GET must be enabled" | mark live-firmware test | — |
 | PR-S7-D1 (TIA CSV / AWL import) | "Symbol import" cross-link | future `import` subcommand stub | — | **new `docs/drivers/S7-TIA-Import.md`** |
 | PR-S7-D2 (UDT / STRUCT) | "UDT / STRUCT support" section | — | remove "UDT fan-out" | extend `S7-TIA-Import.md` |
 | PR-S7-D3 (instance DB) | re-import-on-FB-edit caveat | — | — | extend `S7-TIA-Import.md` |
 | PR-S7-E1 (SZL diagnostics) | "CPU diagnostics (SZL)" section | `read -a @System.CpuType` example | "SZL not modelled by snap7" + Follow-up | — |
 | PR-S7-E2 (PLC password) | "PLC password / protection levels" section | `--password` flag | "password not modelled by snap7" | — |
 | PR-S7-F (Optimized DB / S7Plus) | top-level "Optimized DB constraint" + bridge-via-OpcUaClient worked example | — | point §"What it does NOT cover" at new doc | also updates `docs/featuregaps.md` row #1 |
 ### Snap7-server fixture seed-type additions per PR
 The snap7 simulator at `localhost:1102` (driven by
 `tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/server.py` +
 `Docker/profiles/s7_1500.json`) has a `seed_buffer` pump with a fixed type
 set — `u8 / i8 / u16 / i16 / u32 / i32 / f32 / bool / ascii`. New PRs need
 new seed-type cases in `server.py`, new offsets in `s7_1500.json`, and
 matching constants in `S7_1500Profile.cs`. The table below names the
 delta for each Build-Yes PR:
 | PR | New `server.py` seed types | New `s7_1500.json` seed offsets | `S7_1500Profile.cs` additions |
 |----|----------------------------|----------------------------------|-------------------------------|
 | PR-S7-A1 | `i64`, `u64`, `f64` | `DB1.DBL40` (i64), `DB1.DBL48` (f64), `DB1.DBL56` (u64) | `SmokeI64Tag` / `SmokeU64Tag` / `SmokeF64Tag` |
 | PR-S7-A2 | `wstring`, `char`, `wchar` (existing `ascii` covers STRING) | `DB1.WSTRING[256]`, `DB1.CHAR[300]` | `SmokeWStringTag` / `SmokeCharTag` |
 | PR-S7-A3 | `dtl`, `dt`, `s5time`, `time`, `tod`, `date` (golden-byte vectors in comments) | `DB1.DTL[260]`, `DB1.DT[272]`, `DB1.S5TIME[280]`, `DB1.TIME[284]`, `DB1.TOD[288]`, `DB1.DATE[292]` | `SmokeDtl` / `SmokeDt` / `SmokeS5Time` / `SmokeTime` / `SmokeTod` / `SmokeDate` |
 | PR-S7-A4 | `array` meta-seed (inner-type + count) | `DB1.ArrayInt[300]` 10×Int, `DB1.ArrayReal[320]` 10×Real | `ArrayInt10Tag` / `ArrayReal10Tag` |
 | PR-S7-A5 | none (V-memory aliases land in DB1, which `server.py` already exposes) | none | unit-only — no profile change |
 | PR-S7-B1 | none | none (existing scalar seeds suffice for packing) | none — perf integration test reuses scalar tags |
 | PR-S7-B2 | none | none (existing contiguous DBW0 / DBW10 / DBD20 already test merge) | none |
 | PR-S7-C1 | none | none | none |
 | PR-S7-C2 | none (snap7 accepts any TSAP) | none | none |
 | PR-S7-C3 | none | none | none |
 | PR-S7-C4 | none | none | none |
 | PR-S7-C5 | none (existing `MK0` MW0 seed covers success path) | none | none |
 | PR-S7-D1 | none (CSV import lands tags pointing at existing seeds) | none | possibly add fixture-pointer constants |
 | PR-S7-D2 | `udt_layout` meta-seed (per-member offsets) | `DB1.MyUdt[400]` (Real + Int + Bool layout) | `MyUdtTag` + member tags |
 | PR-S7-D3 | none (resolved addresses land in DB1) | none | none |
 | PR-S7-E1 | none — snap7 doesn't model SZL; unit-level golden bytes cover the parser | none | none |
 | PR-S7-E2 | none — snap7 doesn't enforce protection levels; options-binding unit tests only | none | none |
 | PR-S7-F | none — snap7 has no Optimized-DB mode; live-firmware checklist instead | none | none |
 ### E2E `scripts/e2e/test-s7.ps1` impact
 `scripts/e2e/test-s7.ps1` runs the five-assertion CLI loopback (probe /
 driver-loopback / forward-bridge / reverse-bridge / subscribe-sees-change)
 against `DB1.DBW0` Int16. Build-Yes PRs that add CLI surface get a
 matching loopback assertion; PRs that touch only internals or admin-UI
 flows do not.
 | PR | E2E script change |
 |----|-------------------|
 | PR-S7-A1 | add LInt loopback assertion (write 0x7FFFFFFFFFFFFFFF, read back) |
 | PR-S7-A2 | add string round-trip assertion |
 | PR-S7-A3 | none (CLI cookbook covers manual surface) |
 | PR-S7-A4 | add array round-trip assertion |
 | PR-S7-A5 | none (live-LOGO! field-only) |
 | PR-S7-B1 | none |
 | PR-S7-B2 | none |
 | PR-S7-C1 | none |
 | PR-S7-C2 | none (live-firmware-only) |
 | PR-S7-C3 | none (subscribe assertion already covers polling) |
 | PR-S7-C4 | none |
 | PR-S7-C5 | none (probe runs first today) |
 | PR-S7-D1 | none (Admin UI has its own e2e) |
 | PR-S7-D2 | add UDT-member round-trip assertion |
 | PR-S7-D3 | none (import-time concern) |
 | PR-S7-E1 | none |
 | PR-S7-E2 | none (live-firmware-only) |
 | PR-S7-F | none (decision PR; live-firmware checklist instead) |
 ---
 ## Skip-rated items (for context)
 | # | Gap | Skip rationale |
 |---|-----|---------------|
 | 12 | AS-Alarms / Alarm_S / ProDiag | Alarms are a separate workstream; no `IAlarmSource` shipped on this driver yet, and the gap analysis flags it as a deferred topic. |
 | 13 | CPU Run / Stop control / block download | Security and safety risk. PG-class writes that change CPU state are explicitly out of scope. |
 | 15 | S7-1500 Secure Communication / TLS | Significant work; S7netplus has no TLS surface. Reconsider when S7Plus track is taken. |
 | 16 | S7-400H redundant H-system support | Rare in our deployment scope. Server-level redundancy (`docs/Redundancy.md`) covers the OPC UA layer; H-system driver-level failover is a separate axis. |
 | 17 | Multi-CPU rack parallel sessions | One session per CPU works for the deployments we target; multi-CPU racks are an S7-400 niche. |
 | 18 | MPI / Profibus / RFC1006-routed transports | Declining use; brownfield only. S7netplus is Ethernet-only. |
 | 23 | Connection-resource budget / parallel jobs | One connection works; premature optimization until a deployment hits the cap. |
 ---
 ## Open questions
 ### (a) Library choice for S7Plus
 PR-S7-F gates on this decision. Options:
 1. **Stay on S7netplus + document Optimized-DB constraint** (preferred default).
 2. **Fork to Sharp7 / Snap7 v2** — does *not* solve the S7Plus / Optimized-DB
   problem; both are classic S7comm only. Adopting them buys nothing for this
   gap. Reject unless we want it for unrelated reasons.
 3. **Custom S7Plus client over Wireshark-dissected protocol** — large effort,
   ongoing maintenance risk. Only if a customer is paying.
 4. **OPC UA → OPC UA bridge via existing OPC UA Client driver** — sidesteps
   S7Plus by re-using Siemens's onboard OPC UA server. Recommended secondary
   track.
 Decision needed before Phase 6 PR-S7-F kicks off.
 ### (b) `WriteIdempotent` semantics for new types
 The `WriteIdempotent` per-tag flag (decisions #44, #45, #143) governs replay-
 safe writes. New types from Phase 1:
 - **STRING / WSTRING** — typically idempotent (recipe / message text).
  Replay-safe by default? **Need confirmation.** Risk: PLC programs that
  treat a new string write as a "new message" event would double-fire.
 - **DTL / DT** — usually written from a clock master; replay-safe.
 - **Arrays of UDT** — depends on the UDT semantics (recipe = safe, command
  block = unsafe). Inherit `WriteIdempotent` from the parent tag, do not
  add a per-member flag.
 - **64-bit types** — same rule as 32-bit equivalents.
 Default: keep `WriteIdempotent = false` for everything. Operators flip per
 tag based on PLC program semantics. **No semantic extension needed**, but
 document the per-type guidance in `docs/v2/s7.md`.
 ### (c) Symbol-import file format(s)
 PR-S7-D1 ships an importer. Which formats?
 - **TIA Portal CSV** (Show all tags / Export) — preferred entry point;
  most common. **Confirm.**
 - **TIA Portal SDF / Excel** — same data; harder to parse. Skip unless
  customer demand emerges.
 - **STEP 7 Classic AWL / SCL `.AWL`** — secondary. Useful for legacy
  S7-300/400 sites still on Classic. **Include in D1?**
 - **`.s7p` / `.zap` project archive** — full TIA project. ZIP-shaped;
  symbol export would require unpacking and parsing internal XML. Large
  scope. **Defer.**
 - **`.udt` / `.SDF` external tag library** — niche; defer unless asked.
 Recommendation: PR-S7-D1 ships **TIA CSV** + **AWL** only. Anything else is
 a follow-up. Decision needed before Phase 4 work begins.
--- a/docs/plans/twincat-plan.md
+++ b/docs/plans/twincat-plan.md
@@ -0,0 +1,899 @@
 # TwinCAT Driver — Implementation Plan
 > Source of gap analysis: [featuregaps.md → TwinCAT](../featuregaps.md#twincat-beckhoff-ads)
 >
 > Covers Build = Yes items only.
 ## Summary
 The TwinCAT driver (`src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/`) ships a solid baseline:
 six capability interfaces over `Beckhoff.TwinCAT.Ads` v6 `AdsClient`, native
 `AdsTransMode.OnChange` notifications, AMS address parsing, symbol-path parser
 with multi-dim subscripts, controller-side browse with system-symbol filtering,
 and a 30-case live integration suite against TCBSD + Hyper-V XAR. Twelve gaps
 remain rated Build=Yes in `docs/featuregaps.md` and they cluster cleanly into
 five themes:
 1. **Data-type correctness** — `LInt`/`ULInt` silently truncated to Int32
   (explicit `// matches Int64 gap` comment in `TwinCATDataType.cs:40`),
   `TIME`/`DATE`/`DT`/`TOD` marshalled as raw `UDINT` rather than native UA
   types, `ENUM`/`ALIAS` skipped at browse, bit-indexed BOOL writes throw,
   multi-dim and whole-array reads not batched.
 2. **Performance** — every read is a `ReadValueAsync` call with re-resolved
   symbolic name; no Sum commands, no handle caching. Multi-thousand-tag
   scans pay symbol resolution + per-tag AMS round-trip cost on every cycle.
 3. **Operability** — `NotificationSettings(OnChange, cycleMs, 0)` clamps
   max-delay to zero with no per-tag override; probe loop only checks
   reachability — no cycle-time / jitter / `_AppInfo` / RT-state telemetry.
 4. **UDT decomposition** — `Structure` is declared in the enum but discovery
   skips non-atomic symbols (`AdsTwinCATClient.cs:224`); to expose nested UDT
   trees we need TMC-file parsing or runtime data-type table introspection.
 5. **Alarms** — no `IAlarmSource` implementation; TC3 EventLogger / AMS port
   110 events never surface as OPC UA AC events.
 The plan ships as five phases / 12 PRs. Phases 1-3 are all narrow scope and can
 land in parallel where dependencies allow. Phase 4 (UDT/TMC) is the largest
 single piece of work and is called out as such. Phase 5 (alarms) requires
 investigation up front (Beckhoff TC3 EventLogger NuGet availability — see
 Open questions).
 Hyper-V conflict gating: live integration runs against the TCBSD VM
 (`docs/drivers/TwinCAT-Test-Fixture.md`, AmsNetId `41.169.163.43.1.1` at
 `10.100.0.128`) since the local Hyper-V XAR can't co-exist with Docker
 Desktop. All wire-level tests gate on `[TwinCATFact]` / `[TwinCATTheory]`
 and skip cleanly when `TWINCAT_TARGET_NETID` is unset.
 ## Phased delivery
 | Phase | Theme | PRs | Sequencing |
 |---|---|---|---|
 | 1 | Data-type correctness | 1.1 — 1.5 | Independent; ship in any order |
 | 2 | Performance — Sum + handles | 2.1 — 2.3 | 2.3 depends on 2.2 |
 | 3 | Operability — max-delay + diagnostics | 3.1 — 3.2 | Independent |
 | 4 | UDT decomposition with TMC parsing | 4.1 | Stand-alone; significant scope |
 | 5 | TC3 EventLogger alarms | 5.1 | Stand-alone; spike first |
 Total: 12 PRs covering the 12 Build=Yes gaps.
 Recommended landing order: **Phase 1 (correctness) → Phase 3 (operability) →
 Phase 2 (perf) → Phase 5 (alarms) → Phase 4 (UDT)**. Correctness first because
 it's cheap and removes fixtures' `Skip("Int64 gap")`-style workarounds.
 Operability before perf because the diagnostics surface created in 3.2 makes it
 much easier to validate Sum-command throughput claims in 2.1.
 ## Per-PR detail
 ### Phase 1 — Data-type correctness
 #### PR 1.1 — Int64 fidelity for `LINT` / `ULINT`
 **Scope**: Map `LInt`/`ULInt` to `DriverDataType.Int64` (currently truncates to
 Int32 per `TwinCATDataType.cs:40` comment "matches Int64 gap"). `MapToClrType`
 already returns `typeof(long)`/`typeof(ulong)`; the truncation is purely in the
 `ToDriverDataType` extension.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDataType.cs` — change line 40 to
  `=> DriverDataType.Int64;` (drop the gap comment).
 - Verify `DriverDataType.Int64` exists in `Core.Abstractions` — if not, add it
  (likely scope creep into `ZB.MOM.WW.OtOpcUa.Core.Abstractions/DriverDataType.cs`).
 **Beckhoff.TwinCAT.Ads API**: none — the wire-level `AdsClient.ReadValueAsync`
 already returns `long`/`ulong` boxed in `result.Value` when called with
 `typeof(long)` per `MapToClrType`.
 **Test plan**:
 - Unit: extend `TwinCATCapabilityTests` — assert `LInt.ToDriverDataType() ==
  Int64`, `ULInt.ToDriverDataType() == Int64`.
 - Integration: extend `GVL_Primitives` to include an `LINT` (`nLargeCounter`)
  seeded with `0x1_0000_0000L` (above Int32 range). Add a `[TwinCATTheory]`
  case asserting the value round-trips without truncation. May need a new
  `GVL_Primitives.lLong : LINT` symbol if not already present (the existing
  16-primitive theory in `TwinCAT3SmokeTests.cs` covers `LInt`/`ULInt` —
  inspect what value it seeds and tighten the assertion).
 **Effort**: S (half day).
 **Deps**: none.
 **Docs / fixture / e2e**:
 - Docs: `docs/Driver.TwinCAT.Cli.md` "Data types" table — drop the "marshal as
  `UDINT` on the wire" caveat for `LInt` / `ULInt` (this PR keeps Int64 fidelity);
  `docs/drivers/TwinCAT-Test-Fixture.md` "Bugs caught by live runs" gains a 4th
  entry pinning the truncation regression.
 - Fixture (TCBSD PLC project): `PLC/GVLs/GVL_Primitives.TcGVL` adds
  `vLargeCounter : LINT := 16#1_0000_0000` (above Int32 range) + matching
  `vLargeCounterU : ULINT`; `tests/.../TwinCatProject/README.md` "GVL_Primitives
  numeric seeds" enumerates the new symbols.
 - Integration tests: `TwinCAT3SmokeTests.cs` — extend the 16-case
  `[TwinCATTheory]` to 17/18 cases covering the new LINT/ULINT seeds; assert
  the value round-trips without truncation.
 - E2E: no change to `scripts/e2e/test-twincat.ps1` — the bridge script targets
  a single DINT counter, untouched by Int64 work.
 #### PR 1.2 — TIME / DATE / DT / TOD as native UA types
 **Scope**: Stop marshalling `TIME` / `DATE` / `DT` / `TOD` as raw `UDINT`
 (`AdsTwinCATClient.cs:278-280`). Map according to IEC 61131-3 semantics:
 - `TIME` (ms duration) → `DriverDataType.Duration` (UA `Double` seconds, or
  add `Duration` to `DriverDataType` if missing).
 - `DATE` (days since 1970-01-01) → `DriverDataType.DateTime` (midnight UTC).
 - `DT` (seconds since 1970-01-01) → `DriverDataType.DateTime`.
 - `TOD` (ms since midnight) → `DriverDataType.DateTime` (today's date +
  offset) or a dedicated `TimeOfDay` type if the abstraction supports it.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDataType.cs` — update
  `ToDriverDataType` mapping for the four IEC time types.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs` — `MapToClrType`
  returns the raw UDINT today; keep that for the wire read but post-process
  inside `ReadValueAsync` / `ConvertForWrite` to convert UDINT ↔ `DateTime` /
  `TimeSpan`. Symmetrical change in `OnAdsNotificationEx` so subscriptions see
  the same shape.
 **Beckhoff.TwinCAT.Ads API**: still `AdsClient.ReadValueAsync(symbol,
 typeof(uint), ct)`. Beckhoff exposes `PlcOpenDate` / `PlcOpenTimeOfDay` etc.
 in `TwinCAT.Ads.TypeSystem` — using those types directly would simplify
 conversion but tightens our coupling. Investigate during PR.
 **Test plan**:
 - Unit: round-trip helpers UDINT-since-epoch ↔ `DateTime` for each variant.
 - Integration: add `GVL_Primitives.dCurrentTime : DT` seeded with a known
  literal (e.g. `DT#2026-01-15-12:00:00`); assert the driver returns a
  `DateTime` matching that instant within 1 s.
 **Effort**: M (1-2 days).
 **Deps**: none. May expose missing `Duration` in `DriverDataType` enum.
 **Docs / fixture / e2e**:
 - Docs: `docs/Driver.TwinCAT.Cli.md` "Data types" section — replace the
  "marshal as `UDINT` on the wire — CLI takes a numeric raw value" paragraph
  with native syntax (e.g. `read -t DateTime` returns ISO-8601, `write -t Time
  -v 00:00:01.500` for IEC TIME duration). New examples for each of the four
  IEC time types under `read` / `write`.
 - Fixture (TCBSD PLC project): `PLC/GVLs/GVL_Primitives.TcGVL` adds
  `dCurrentTime : DT := DT#2026-01-15-12:00:00`, `tCycleDuration : TIME :=
  T#1500ms`, `dToday : DATE := DATE#2026-04-25`, `tShiftStart : TOD :=
  TOD#06:30:00`. Existing primitives theory in
  `tests/.../TwinCatProject/README.md` § "Type coverage" gets the seed values
  documented.
 - Integration tests: `TwinCAT3SmokeTests.cs` — new
  `Driver_round_trips_TIME_DATE_DT_TOD_as_native_UA_types` `[TwinCATFact]`
  reading each variable and asserting the CLR shape (`TimeSpan` / `DateTime`).
  Update the existing 16-case primitive `[TwinCATTheory]` to assert native
  types instead of raw `UDINT` for these four entries.
 - E2E: `scripts/e2e/test-twincat.ps1` unchanged for now (single DINT bridge);
  follow-up could add a DT-typed bridge node but it's not on the critical path.
 #### PR 1.3 — Bit-indexed BOOL writes (read-modify-write)
 **Scope**: Replace the `NotSupportedException` at `AdsTwinCATClient.cs:99-100`
 with a read-modify-write sequence: read parent word as `uint`, set/clear bit,
 write the word back. Must serialize against concurrent writes to the same
 parent word — a single `SemaphoreSlim` keyed on parent symbol path is
 sufficient (concurrency on bit writes within the same parent is rare and the
 PLC cycle is the natural lower bound on contention anyway).
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs` — replace `throw`
  branch in `WriteValueAsync` with RMW logic mirroring `ReadValueAsync`'s
  bit-index path. Add `ConcurrentDictionary<string, SemaphoreSlim>
  _bitWriteLocks` keyed on parent symbol.
 **Beckhoff.TwinCAT.Ads API**: `AdsClient.ReadValueAsync(parent, typeof(uint))`
 + `AdsClient.WriteValueAsync(parent, modifiedWord)`. Both already used.
 **Test plan**:
 - Unit: extend `TwinCATReadWriteTests` with a `FakeTwinCATClient` test
  covering set + clear of bits 0, 7, 15, 31 of a `uint` parent.
 - Integration: add a new `[TwinCATFact]` —
  `Driver_round_trips_bit_indexed_BOOL_write_and_read` against
  `GVL_Primitives.vWord.4` (the `0xBEEF` word's bit-4); flip to true, read
  back as true, flip to false, read back as false.
 **Effort**: S-M (1 day).
 **Deps**: none. Closes task #181 referenced in the existing `NotSupported`
 exception message.
 **Docs / fixture / e2e**:
 - Docs: `docs/Driver.TwinCAT.Cli.md` `write` section — add an example
  `otopcua-twincat-cli write -n ... -s "GVL_Primitives.vWord.4" -t Bool -v
  true` and a note explaining the RMW semantics + concurrency caveat (parent
  word is locked per write — concurrent bit writes on the same word
  serialize). `docs/drivers/TwinCAT-Test-Fixture.md` "Bugs caught by live
  runs" updates entry #3 to note that writes now also work (read previously
  shipped; write was the gap).
 - Fixture (TCBSD PLC project): no schema change required —
  `GVL_Primitives.vWord` already exists with seed `0xBEEF`. Tests use bits 4
  (clear) and 7 (set) to round-trip.
 - Integration tests: `TwinCAT3SmokeTests.cs` — new
  `Driver_round_trips_bit_indexed_BOOL_write_and_read` `[TwinCATFact]`. Unit
  tests in `TwinCATReadWriteTests` extended via `FakeTwinCATClient` for bits
  0/7/15/31 of a `uint` parent.
 - E2E: no change.
 #### PR 1.4 — Multi-dim and whole-array reads
 **Scope**: Expand `ReadValueAsync` / `WriteValueAsync` to handle whole-array
 reads via Beckhoff's array marshalling, instead of element-by-element. The
 symbol-path parser already produces `TwinCATSymbolSegment.Subscripts` with N
 dims; today the driver only reads single elements (one path per request).
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs` — when a tag
  declares `IsArray=true` (extend `TwinCATTagDefinition`), use
  `AdsClient.ReadValueAsync(symbol, typeof(int[]))` / `typeof(double[,])` etc.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs` — surface
  `IsArray` + `ArrayDim` through `DriverAttributeInfo` in `DiscoverAsync`.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATTagDefinition.cs` (if exists,
  in `TwinCATDriverOptions.cs`) — add `bool IsArray`, `int[]? ArrayDimensions`.
 **Beckhoff.TwinCAT.Ads API**: `AdsClient.ReadValueAsync(symbol, Type, ct)`
 accepts CLR array types. For dynamically-sized reads use
 `AdsClient.ReadAnyAsync<T[]>(...)` or pass `Array.CreateInstance(elemType,
 dims)`. SymbolLoader yields a `Symbol.Category == DataTypeCategory.Array` we
 can inspect to autoderive dimensions during discovery.
 **Test plan**:
 - Unit: parse `Matrix[1,2]` and verify ranking / dimension flow into the
  request shape via `FakeTwinCATClient`.
 - Integration: extend `GVL_Arrays` with a 5x5 `aReal2D : ARRAY [1..5, 1..5]
  OF REAL`; new `[TwinCATFact]` reads the whole array in one call and
  verifies element count + values.
 **Effort**: M (2-3 days).
 **Deps**: none. Sets up the array-shape plumbing the rest of the driver
 needs anyway.
 **Docs / fixture / e2e**:
 - Docs: `docs/Driver.TwinCAT.Cli.md` `read` section — add whole-array example
  (`read -s "GVL_Arrays.aReal2D"` returns the full matrix as JSON) plus a
  dedicated "Arrays" sub-section calling out 1-D / N-D / array-of-struct
  semantics. `docs/drivers/TwinCAT-Test-Fixture.md` "What it actually covers"
  list adds the whole-array bullet.
 - Fixture (TCBSD PLC project): `PLC/GVLs/GVL_Arrays.TcGVL` already declares
  `ARRAY[1..4,1..4] OF REAL` per `TwinCatProject/README.md` § "Array
  coverage". This PR adds a 5x5 `aReal2D : ARRAY [1..5, 1..5] OF REAL`
  initialised with a deterministic pattern (e.g. `(i-1)*5 + (j-1)`) so the
  whole-array test can assert each element. README "Array coverage" gets the
  new symbol.
 - Integration tests: `TwinCAT3SmokeTests.cs` — new
  `Driver_reads_whole_2D_array_in_one_call` `[TwinCATFact]`. Unit tests
  extend `TwinCATSymbolPathTests` for multi-dim subscript shape.
 - E2E: no change to `scripts/e2e/test-twincat.ps1` (scalar bridge); a future
  array-bridge scenario is captured in the consolidated section below.
 #### PR 1.5 — ENUM and ALIAS at discovery
 **Scope**: `MapSymbolTypeName` returns `null` for any non-atomic type
 (`AdsTwinCATClient.cs:224`), so ENUM and ALIAS symbols are silently dropped
 during browse. ENUM is essentially a sized-integer with named members; ALIAS
 is a renamed atomic. Both are extremely common in real projects (motor states,
 recipe-step IDs, bit-flag groups).
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs` —
  `MapSymbolTypeName` keyed only on the type name today; switch to inspecting
  `symbol.DataType` + `symbol.Category` from `TwinCAT.TypeSystem`. For
  `DataTypeCategory.Enum` walk `EnumType.EnumValues` and pick the underlying
  base type. For `DataTypeCategory.Alias` resolve `AliasType.BaseType`
  recursively until atomic.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/BrowseSymbolsAsync` —
  surface enum members so the OPC UA layer can later emit them as
  EnumStrings.
 **Beckhoff.TwinCAT.Ads API**: `TwinCAT.Ads.TypeSystem.SymbolLoaderFactory`
 already returns full `IDataType` objects with `Category`, `EnumType`,
 `AliasType`, etc. No new APIs.
 **Test plan**:
 - Unit: extend `TwinCATSymbolBrowserTests` — fake an enum symbol via
  `FakeTwinCATClient`; assert it browses with the underlying base type.
 - Integration: add `E_LineState : (Idle, Running, Faulted)` + a GVL instance
  variable; new `[TwinCATFact]` browses + reads it as `Int16` (or whatever
  the underlying type is).
 **Effort**: M (1-2 days).
 **Deps**: none. POINTER / REFERENCE / INTERFACE / UNION are explicitly
 out-of-scope for this PR — they need real-world demand and a much larger
 type-system rework. ENUM and ALIAS are the 80% case.
 **Docs / fixture / e2e**:
 - Docs: `docs/Driver.TwinCAT.Cli.md` `browse` section — note that ENUM and
  ALIAS symbols now appear in the output (previously dropped); add a Data
  types row for "Enum (surfaced as underlying integer with EnumStrings)"
  and "Alias (resolved to base atomic)". `docs/drivers/TwinCAT-Test-
  Fixture.md` "What it actually covers" extends with the enum/alias bullet.
 - Fixture (TCBSD PLC project): `PLC/DUTs/E_AxisState.TcDUT` and
  `E_Severity.TcDUT` already exist; `PLC/DUTs/T_Temperature.TcDUT` and
  `T_MeterPerSec.TcDUT` already exist. `PLC/GVLs/GVL_Enums.TcGVL` already
  exposes them at the root per `TwinCatProject/README.md` § "Enum + alias
  coverage" — no fixture change needed for this PR. README's "Integration-
  test contract" gets a new entry for `GVL_Enums.currentSeverity` /
  `currentTemperature` so the new browse assertion has a stable target.
 - Integration tests: `TwinCAT3SmokeTests.cs` — new
  `Driver_browses_enums_and_aliases_with_resolved_base_types` `[TwinCATFact]`
  asserting the four `GVL_Enums` symbols surface with the correct underlying
  CLR type (`Int32` for E_AxisState, `Int16` for E_Severity, `Double` for
  the LREAL aliases).
 - E2E: no change.
 ### Phase 2 — Performance (Sum commands + handle caching)
 #### PR 2.1 — ADS Sum-read / Sum-write
 **Scope**: Today `ReadAsync` loops over `fullReferences` issuing one
 `ReadValueAsync` per tag (`TwinCATDriver.cs:118-156`). Beckhoff's ADS Sum
 commands (`IndexGroup=0xF080..0xF084`) batch N reads/writes into a single AMS
 request. `Beckhoff.TwinCAT.Ads` v6 exposes this via
 `AdsClient.ReadWriteAsync` with `SumCommand` request envelopes —
 specifically `SumSymbolRead` / `SumSymbolWrite` from
 `TwinCAT.Ads.SumCommand`. ~10x throughput on multi-thousand-tag scans
 according to Beckhoff InfoSys.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs` — new
  `ReadValuesAsync(IReadOnlyList<(string symbol, Type clrType)>, ct)` returning
  a parallel array of `(value, status)`.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs::ReadAsync` — bucket
  `fullReferences` by `DeviceHostAddress`, call the new client method per
  bucket. `bitIndex` handling stays per-tag (RMW post-step).
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/ITwinCATClient.cs` — add the
  bulk-read / bulk-write surface.
 **Beckhoff.TwinCAT.Ads API**:
 - `AdsClient.ReadWriteAsync(IndexGroup=0xF080, IndexOffset=count, ...)` for
  raw sum-read by handle.
 - Higher-level: `TwinCAT.Ads.SumCommand.SumSymbolRead(client, symbols)` /
  `SumSymbolWrite(client, symbols, values)` in v6. Verify the exact namespace
  during PR — Beckhoff sometimes re-shuffles between minor versions.
 - For symbolic (no handle) batching: `SumSymbolReadByName`.
 **Test plan**:
 - Unit: `FakeTwinCATClient.ReadValuesAsync` fakes the bulk surface; test
  ordering preservation, partial-failure mapping, empty-input handling.
 - Integration: `[TwinCATFact]` reads 100 declared tags in one call, asserts
  value parity with 100 single-call equivalents and measures wall-clock
  difference (assert under 50% of the loop baseline).
 **Effort**: M-L (3 days).
 **Deps**: none (handle caching in 2.2 amplifies the win but isn't required).
 **Docs / fixture / e2e**:
 - Docs: `docs/v3/twincat-backlog.md` perf note moves out (Sum-commands no
  longer deferred) — add a closed-out bullet pointing at this PR. New
  performance section in `docs/drivers/TwinCAT-Test-Fixture.md` documenting
  the throughput baseline + Sum-command delta. `docs/Driver.TwinCAT.Cli.md`
  doesn't expose Sum directly to the user — the CLI still drives one symbol
  per call — so no CLI doc change.
 - Fixture (TCBSD PLC project, primary fixture-extension surface): add a new
  `PLC/GVLs/GVL_Perf.TcGVL` declaring `aTags : ARRAY[1..1000] OF DINT` plus
  a `MAIN` rung (or new `FB_PerfChurn` POU) that increments each element on
  a rotating subset. `TwinCatProject/README.md` § "Required project state"
  gains a "Performance scenarios" subsection documenting the 1000-tag GVL.
 - Integration tests: new perf test
  `Driver_sum_read_1000_tags_beats_loop_baseline_by_5x` (`[TwinCATFact]`,
  perf-tier — guarded behind a separate `TWINCAT_PERF=1` env flag so CI
  noise from VM jitter doesn't flap the suite). Unit tests cover ordering,
  partial-failure mapping, empty-input via `FakeTwinCATClient.ReadValuesAsync`.
 - E2E: `scripts/e2e/test-twincat.ps1` unchanged for the canonical bridge;
  perf scripts live alongside as a separate `scripts/perf/twincat-sum.ps1`
  if/when introduced (deferred — integration test is sufficient).
 #### PR 2.2 — Handle-based access with caching
 **Scope**: Cache `AdsClient.CreateVariableHandleAsync` results so per-read
 overhead drops from "resolve symbolic name + read by name" to "read by handle"
 — smaller AMS payloads, no name resolution on each call. Cache lifetime is
 process-scoped; eviction is via the PR 2.3 invalidation listener. Until 2.3
 ships the cache must be cleared on `AdsClient` reconnect (the existing
 auto-reconnect path in `EnsureConnectedAsync`).
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs` — add
  `ConcurrentDictionary<string, uint> _handleCache`. Wrap reads/writes through
  `EnsureHandleAsync(symbolPath)` that hits the cache or calls
  `CreateVariableHandleAsync`. On `AdsErrorCode.DeviceSymbolVersionInvalid`
  (0x710 / 1808) evict the entry and retry once.
 - Dispose path: `DeleteVariableHandleAsync` for every cached handle on
  `AdsClient.Dispose` to be a good citizen with the runtime.
 **Beckhoff.TwinCAT.Ads API**:
 - `AdsClient.CreateVariableHandleAsync(string symbol, ct)` → returns
  `ResultHandle` with `.Handle` (uint).
 - `AdsClient.ReadAnyAsync<T>(IndexGroup=0xF005, IndexOffset=handle, ct)`
  reads by handle.
 - `AdsClient.WriteAnyAsync(IndexGroup=0xF005, IndexOffset=handle, value, ct)`.
 - `AdsClient.DeleteVariableHandleAsync(uint handle, ct)`.
 **Test plan**:
 - Unit: `FakeTwinCATClient` records handle-create / read-by-handle calls;
  test asserts second read of same symbol uses cached handle (zero new
  creates).
 - Integration: subscribe + read 50 tags, capture AMS round-trips via probe
  counter, assert the second pass uses ~50% of the bytes (handle = 4 bytes
  vs symbol path = N bytes).
 **Effort**: M (2 days).
 **Deps**: combines with PR 2.1 for sum-read-by-handle (highest perf path).
 Without 2.3, handles can go stale after an online change — call out the
 caveat in driver options and add a manual `FlushOptionalCachesAsync` invocation
 that wipes the handle cache.
 **Docs / fixture / e2e**:
 - Docs: `docs/drivers/TwinCAT-Test-Fixture.md` perf section gets a paragraph
  noting that handles drop AMS payload size for repeated reads (4 bytes vs.
  N-byte symbol path); call out the staleness caveat (online-change
  invalidation lands in 2.3). `docs/Driver.TwinCAT.Cli.md` adds a brief note
  in the `subscribe` / `read` sections that handles are cached transparently
  — no user-visible flag.
 - Fixture (TCBSD PLC project): no change required — handle caching is
  observable via byte-counter on the wire, not via PLC-side state. The
  perf-scenario `GVL_Perf.aTags` from PR 2.1 doubles as the exercise target.
 - Integration tests: new
  `Driver_handle_cache_avoids_repeat_symbol_resolution` `[TwinCATFact]`
  reads the same 50 symbols twice; asserts second pass uses cached handles
  (probed via diagnostics counters from PR 3.2 if shipped, otherwise via a
  test-only hook on `AdsTwinCATClient`). Unit tests on
  `FakeTwinCATClient.HandleCacheTests` assert second read of same symbol
  triggers zero new handle creates.
 - E2E: no change.
 #### PR 2.3 — Symbol-version invalidation listener
 **Scope**: TwinCAT publishes a "symbol table version changed" notification on
 ADS Index Group `ADSIGRP_SYMVAL_BYHND` (or rather, version bumps land via
 `SystemServiceLoadFile` style notifications + `SymbolVersion` reads). When the
 PLC takes an online change, all cached handles are silently invalidated; the
 next read returns `DeviceSymbolVersionInvalid` if you're lucky and a wrong
 value if you're not. We register a notification on the symbol-version index
 and wipe the handle cache on bump.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs` — on connect,
  call `AddDeviceNotificationAsync(ADSIGRP_SYM_VERSION, 0, length=1, ...)`
  with `AdsTransMode.OnChange`. On callback, clear `_handleCache` + log.
 **Beckhoff.TwinCAT.Ads API**:
 - `AdsClient.AddDeviceNotificationAsync(uint indexGroup, uint indexOffset,
  int length, NotificationSettings, object userData, ct)` — the raw,
  index-group-based variant (not the symbol-name `Ex` variant we use today).
 - Index group: `AdsReservedIndexGroup.SymbolVersion` (0xF008). One byte
  payload that's the current symbol-version counter. Confirm during PR — open
  question (c) below.
 **Test plan**:
 - Unit: extend `TwinCATNativeNotificationTests` — `FakeTwinCATClient` exposes
  a `FireSymbolVersionChange()` method; test asserts handle cache is cleared
  and subsequent reads recreate handles.
 - Integration: `[TwinCATFact]` triggers an online change on the TCBSD project
  (rebuild a GVL with one new variable + login activate) — needs a project
  helper that automates the online-change. May ship behind a manual gate
  (`[TwinCATFact(Reason="requires-manual-online-change")]`) initially.
 **Effort**: M (2 days).
 **Deps**: PR 2.2 (no point invalidating an empty cache). Confirm
 `SymbolVersion` index-group constant in `Beckhoff.TwinCAT.Ads` v6 — open
 question (c) below.
 **Docs / fixture / e2e**:
 - Docs: `docs/drivers/TwinCAT-Test-Fixture.md` section on "What it does NOT
  cover" — drop the implicit "online-change handling" gap. New paragraph in
  the perf section noting handle cache is now self-invalidating.
  `docs/Driver.TwinCAT.Cli.md` no change (transparent to CLI user).
 - Fixture (TCBSD PLC project): no schema change. Operator workflow gains an
  online-change drill — `TwinCatProject/README.md` adds a § "Online-change
  test scenario" describing the steps (open project, add a dummy variable
  to `GVL_Perf`, "Login + Activate" → triggers the symbol-version bump).
  This is the manual gate for the integration assertion.
 - Integration tests: new `Driver_invalidates_handle_cache_on_symbol_version_bump`
  `[TwinCATFact]` — initially gated `[TwinCATFact(Reason="requires-manual-online-change")]`
  until automation lands. Unit tests cover the callback path via
  `FakeTwinCATClient.FireSymbolVersionChange()`.
 - E2E: no change.
 ### Phase 3 — Operability
 #### PR 3.1 — Per-tag MaxDelay tuning
 **Scope**: Today `NotificationSettings` is hard-coded as `(OnChange, cycleMs,
 0)` (`AdsTwinCATClient.cs:144-145`). MaxDelay=0 means "fire as soon as the
 change is detected, no coalescing"; for bursty high-frequency signals this
 floods the OPC UA subscription queue. Surface MaxDelay as a per-tag option
 (default 0 to preserve current behavior).
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriverOptions.cs` — add
  `int? MaxDelayMs` to `TwinCATTagDefinition`.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs::SubscribeAsync` —
  pass through to client.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs::AddNotificationAsync`
  — accept `int maxDelayMs`, plumb into `NotificationSettings(...,
  cycleMs, maxDelayMs)`.
 **Beckhoff.TwinCAT.Ads API**: `NotificationSettings(AdsTransMode mode, int
 cycleTime, int maxDelay)` — both args in milliseconds per Beckhoff InfoSys
 `tcadsnetref/7313319051`.
 **Test plan**:
 - Unit: extend `TwinCATNativeNotificationTests` — assert the plumbed
  `maxDelayMs` lands on `NotificationSettings`.
 - Integration: subscribe to `GVL_Fixture.nCounter` with `MaxDelayMs=500`;
  assert delivery rate is ≤ 2 Hz even when PLC cycle is 10 ms.
 **Effort**: S (half day).
 **Deps**: none.
 **Docs / fixture / e2e**:
 - Docs: `docs/Driver.TwinCAT.Cli.md` `subscribe` flag table — add `--max-delay-ms`
  with default `0` and a note that nonzero coalesces high-frequency PLC
  signals. Update the description of `-i` / `--interval-ms` to disambiguate
  cycle vs. max-delay (both pass through to `NotificationSettings`).
  `docs/drivers/TwinCAT-Test-Fixture.md` "Notification coalescing under
  jitter" caveat — noting per-tag MaxDelay is now configurable.
 - Fixture (TCBSD PLC project): no change required — `GVL_Fixture.nCounter`
  already increments on every 10 ms cycle (see `MAIN.TcPOU`), so the test
  can drive a 100 Hz change rate and verify ≤ 2 Hz delivery with
  `MaxDelayMs=500`. README "Required project state" gets a one-line note
  that the counter doubles as the coalescing-test driver.
 - Integration tests: new `Driver_coalesces_notifications_at_max_delay`
  `[TwinCATFact]` subscribes to `GVL_Fixture.nCounter` with `MaxDelayMs=500`
  and asserts delivered-event count ≤ 3 over a 1 s window.
 - E2E: `scripts/e2e/test-twincat.ps1` `Test-SubscribeSeesChange` is a
  one-shot subscribe; no change. A future high-rate variant could test
  coalescing end-to-end through the OPC UA bridge but it's not on the
  critical path.
 #### PR 3.2 — Cycle-time / jitter / PLC-state diagnostics
 **Scope**: Probe loop today only checks reachability via `ReadStateAsync`
 (`TwinCATDriver.cs::ProbeLoopAsync`). Surface cycle-time, jitter, and online-
 change counter as health signals via the standard `_AppInfo` /
 `TwinCAT_SystemInfoVarList._AppInfo` GVL (the same one we filter out of
 discovery). Specifically:
 - `_AppInfo.OnlineChangeCnt` (UDINT) — incremented on every online change.
 - `_AppInfo.AppName` (STRING) — TC project name, useful for
  cross-instance identification.
 - `_TaskInfo[1].CycleTime` (UDINT, 100 ns units) — the configured PLC cycle.
 - `_TaskInfo[1].LastExecTime` (UDINT, 100 ns units) — most recent measured
  cycle execution; jitter is the delta against `CycleTime`.
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs::ProbeLoopAsync` —
  augment success path to also read these four symbols. Surface via a new
  `TwinCATDeviceDiagnostics` record on `DeviceState`. Emit through
  `IDriverDiagnostics` (the cross-driver diagnostics surface introduced for
  Modbus prohibition events — task #154).
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATSystemSymbolFilter.cs` — leave
  the filter as-is for the user-visible browse; the probe path reads system
  symbols directly without going through discovery.
 **Beckhoff.TwinCAT.Ads API**: still `AdsClient.ReadValueAsync(symbol, type,
 ct)`. The symbols are read by name, not by index group, so no new API.
 **Test plan**:
 - Unit: `FakeTwinCATClient` exposes `SetSystemSymbolValue(string name, object
  value)` so tests can drive the diagnostics surface deterministically.
 - Integration: `[TwinCATFact]` connects to TCBSD, asserts the diagnostics
  block populates `CycleTimeMs > 0` and `OnlineChangeCnt >= 0` within one
  probe interval.
 **Effort**: M (1-2 days).
 **Deps**: confirm `IDriverDiagnostics` shape from existing Modbus diagnostics
 RPC (task #154 in MEMORY); it should be reusable.
 **Docs / fixture / e2e**:
 - Docs: new section "Diagnostics" in `docs/drivers/TwinCAT-Test-Fixture.md`
  documenting the four exposed signals (cycle time, jitter, online-change
  counter, app name) and where they surface in the cross-driver
  diagnostics RPC. `docs/Driver.TwinCAT.Cli.md` `probe` section gains a
  "Health probe" sub-section noting the same symbols can be read directly
  via `probe -s "TwinCAT_SystemInfoVarList._AppInfo.OnlineChangeCnt"`
  (the existing example) plus the new `_TaskInfo[1].CycleTime` /
  `LastExecTime`. Add `docs/v3/twincat-backlog.md` cross-link confirming
  cycle-time/jitter no longer deferred.
 - Fixture (TCBSD PLC project): no change required — `_AppInfo` and
  `_TaskInfo[1]` are TwinCAT system GVLs, present on every runtime. The
  `TwinCATSystemSymbolFilter` already drops them from user browse;
  `TwinCatProject/README.md` adds a one-line "These symbols are read by
  the probe loop, not project-defined" callout.
 - Integration tests: new `Probe_loop_surfaces_cycle_time_and_online_change_count`
  `[TwinCATFact]` asserts the diagnostics record populates within one
  probe interval against TCBSD. Unit tests via `FakeTwinCATClient.SetSystemSymbolValue`
  drive the diagnostics surface deterministically.
 - E2E: no change. Future enhancement could expose driver diagnostics via a
  CLI subcommand (`otopcua-twincat-cli diagnostics -n ...`) — captured in
  the consolidated section below as a follow-up.
 ### Phase 4 — UDT decomposition with TMC parsing
 #### PR 4.1 — Nested UDT browse via TMC parsing
 **Scope**: Largest single piece of work in the plan. `TwinCATDataType.Structure`
 exists but `BrowseSymbolsAsync` skips non-atomic symbols
 (`AdsTwinCATClient.cs:224`); to expose nested UDT trees we either:
 1. **Online**: walk the `IDataType` tree returned by `SymbolLoaderFactory` —
   each `IStructType` exposes `SubItems` recursively. This is what
   `Beckhoff.TwinCAT.Ads` v6's TypeSystem already gives us at runtime; we just
   never recursed.
 2. **Offline (TMC file)**: parse the TwinCAT Module Class XML file the project
   compiles to (`*.tmc`), build a type catalogue, drive discovery from it
   without requiring a live runtime.
 We ship the **online** path first (PR 4.1) because it covers 100% of the case
 where the runtime is reachable, and `SymbolLoaderFactory` already does the
 heavy lifting. TMC offline parsing is deferred to a hypothetical PR 4.2 if a
 disconnected-discovery use case emerges (unlikely; live integration tests
 demonstrate runtime is always available in our deployments).
 **Files**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs` —
  `BrowseSymbolsAsync` recurses into `IStructType.SubItems`, yielding one
  `TwinCATDiscoveredSymbol` per leaf with the dotted instance path
  (`MyStruct.Inner.Field`). For arrays-of-structs, expand element-by-element
  up to a configurable bound (default 1024) — beyond that, expose only the
  array root with `IsArray=true`.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs::DiscoverAsync` —
  fold the recursed structure into the existing `Discovered/` folder tree
  using `IAddressSpaceBuilder.Folder` for each struct member.
 - New: `TwinCATTypeWalker.cs` — pure helper that takes an `IDataType` and
  yields `(instancePath, atomicType, readOnly)` tuples. Unit-testable without
  touching `AdsClient`.
 **Beckhoff.TwinCAT.Ads API**:
 - `TwinCAT.TypeSystem.IStructType` — `SubItems` (collection of
  `IMember`); each member has `BaseType`, `Name`, `Offset`.
 - `TwinCAT.TypeSystem.IArrayType` — `Dimensions`, `BaseType`.
 - `TwinCAT.TypeSystem.IEnumType` — handled in PR 1.5 (atomic surface).
 - `TwinCAT.TypeSystem.IAliasType.BaseType` — recurse until atomic.
 **Test plan**:
 - Unit: new `TwinCATTypeWalkerTests` — feed synthetic `IDataType` trees,
  assert the flattened paths and types.
 - Integration: extend `GVL_Plant` (already has `Line1.Stations[1].Axes[1].Motor`
  per `TwinCAT3SmokeTests.cs`) — the existing `Driver_reads_deeply_nested_UDT_path`
  test reads a known-leaf path; add a new test that browses into the same
  GVL and asserts the entire tree shape matches expectation. Should yield
  ~50+ leaves.
 **Effort**: L (4-5 days). Most of the cost is in the addressspace-builder
 folder/variable plumbing, not the type walking itself.
 **Deps**: PR 1.5 (ENUM/ALIAS) — without it, struct members of enum type
 silently drop. PR 1.4 (whole-array reads) is helpful but not blocking.
 **Docs / fixture / e2e**:
 - Docs: this is the **largest doc-write of the plan**.
  `docs/Driver.TwinCAT.Cli.md` gains a new top-level "UDT decomposition"
  section explaining the dotted-instance browse syntax (`MyStruct.Inner.
  Field`), array-of-struct expansion bound, and how members surface via
  `browse`. The existing `read` example "Nested UDT member" gets expanded
  with a multi-level case targeting the plant hierarchy. `docs/drivers/
  TwinCAT-Test-Fixture.md` "What it actually covers" gets a UDT bullet
  per-member rather than per-leaf. Update `docs/v3/twincat-backlog.md` —
  remove the implicit UDT-decomposition gap.
 - Fixture (TCBSD PLC project, primary fixture-extension surface): the
  existing `GVL_Plant.Line1.Stations[1..3].Axes[1..4]...` 5-level
  hierarchy already provides ~50+ leaves per `TwinCatProject/README.md`
  § "5-level plant hierarchy" + § "Live value churn". This PR may add a
  few **edge cases** to stress the type walker:
  - `PLC/DUTs/ST_NestedFlags.TcDUT` — struct containing a BIT-packed
    member (e.g. `Flags : DWORD` with named bit-mask aliases).
  - `PLC/DUTs/ST_RecursiveCap.TcDUT` — struct with a self-pointer (must
    be capped by the type walker, not infinite-recurse). Demonstrates
    POINTER skip behavior.
  - Add an `ARRAY [1..2000] OF ST_AlarmRecord` to exercise the
    `MaxArrayExpansion` (default 1024) cutoff.
  README § "Complex hierarchy" gets the new edge-case DUTs documented.
 - Integration tests: new `TwinCATTypeWalkerTests` (unit) feeding synthetic
  `IDataType` trees. Live: `Driver_browses_full_plant_hierarchy_yields_50_plus_leaves`,
  `Driver_caps_array_of_struct_expansion_at_configured_bound`,
  `Driver_handles_self_referential_struct_without_recursion` against the
  new edge-case DUTs.
 - E2E: `scripts/e2e/test-twincat.ps1` could gain a UDT-bridge scenario
  (`-BridgeNodeId` pointing at `GVL_Plant.Line1.Stations[1].Axes[1].Motor.
  Temperature`) but this requires the OPC UA server's address-space to
  reflect the decomposed tree — keep as a follow-up after server-side
  rendering ships in v3.
 ### Phase 5 — TC3 EventLogger alarms
 #### PR 5.1 — `IAlarmSource` via TC3 EventLogger
 **Scope**: TwinCAT 3.1 build 4022+ ships TcEventLogger as a system service
 exposing alarms/events on AMS port 110 (`AMSPORT_EVENTLOG`). Implement
 `IAlarmSource` over that interface so PLC alarms surface as OPC UA AC events.
 **Open question (b) below** drives the implementation: does Beckhoff publish
 a managed wrapper, or do we hit AMS port 110 directly?
 If a managed wrapper exists:
 - `Beckhoff.TwinCAT.Ads.TcEventLogger` (or similar) — subscribe via
  `EventLogger.AlarmRaised` event.
 If not (likely — InfoSys docs lean on `TcCOM` C++ APIs):
 - Open a second `AdsClient` connection to port 110 via
  `_secondaryClient.Connect(netId, 110)`.
 - Use `AddDeviceNotificationAsync` on the alarm-list index group
  (`ADSIGRP_TCEVENTLOG_ALARMS`, exact constant TBD during spike).
 - Decode the binary event payload into `AlarmEvent` records (severity,
  source, message, time-of-occurrence, ack state).
 **Files**:
 - New: `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATAlarmSource.cs`
  — implements `IAlarmSource` (currently used by Galaxy / Wonderware).
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs` — declare
  `IAlarmSource` interface, delegate to the helper.
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriverOptions.cs` — new
  `bool EnableAlarms` (default `false` until production-validated).
 **Beckhoff.TwinCAT.Ads API**: TBD pending spike. Falls back to raw
 `AdsClient.AddDeviceNotificationAsync` on port 110 if no managed wrapper.
 **Test plan**:
 - Unit: fake event-logger feeds synthetic alarms; assert `IAlarmSource`
  surface raises events with correct shape.
 - Integration: TCBSD project gains an `Alarm.Raise(...)` call site on a GVL
  bool transition; new `[TwinCATFact]` subscribes via the driver, toggles the
  trigger, asserts the alarm appears in the source within 5 s.
 **Effort**: L (4-5 days), most of which is the spike. If no managed wrapper
 exists, add another L (3-4 days) to implement the binary protocol decoder.
 **Deps**: spike answer to open question (b) — surface that as an explicit
 investigation PR before committing to the build.
 **Docs / fixture / e2e**:
 - Docs: **new file** `docs/drivers/TwinCAT.md` (the existing
  `TwinCAT-Test-Fixture.md` is fixture-only) covering the alarm
  configuration surface — `EnableAlarms` option, AMS port 110 routing,
  severity / source / message decode, OPC UA AC mapping. Spike output
  goes to `docs/v3/twincat-eventlogger-spike.md` per open question (b).
  `docs/Driver.TwinCAT.Cli.md` gains a new `alarms` subcommand (subscribe
  + print stream) mirroring the OPC UA Client CLI's `alarms` verb.
  `docs/drivers/TwinCAT-Test-Fixture.md` "Alarms / history" caveat
  removed; capability matrix gets `IAlarmSource = yes`.
 - Fixture (TCBSD PLC project, primary fixture-extension surface): add
  `PLC/POUs/FB_AlarmHarness.TcPOU` that calls `FB_TcLogEvent` (or
  equivalent TC3 EventLogger PLC API) on a 5 s tick, raising / clearing
  a known event class. New `PLC/GVLs/GVL_Alarms.TcGVL` exposes the
  trigger booleans the test toggles. `TwinCatProject/README.md` § new
  "Alarm scenarios" subsection documents the event class IDs + severity
  + cleared-on transitions. The existing `ST_Alarm` DUT remains for
  PLC-level data; the EventLogger is the AC source.
 - Integration tests: new `TwinCATAlarmIntegrationTests.cs` —
  `Driver_raises_alarm_event_when_PLC_logs_event` `[TwinCATFact]`
  toggles the trigger via `WriteAsync`, asserts the alarm appears in
  `IAlarmSource.AlarmRaised` within 5 s. Includes a clear-event variant.
  Unit tests via fake event-logger feed synthetic alarms.
 - E2E: `scripts/e2e/test-twincat.ps1` gains a `Test-AlarmRoundTrip`
  step (toggle PLC trigger → assert event surfaces via OPC UA AC client)
  once the server-side wiring is in. Likely defers to a follow-up PR
  after the server-tier alarm rendering catches up.
 ## Documentation, fixture, and e2e impact
 Consolidated view across all 12 PRs. The **TCBSD fixture PLC project**
 (`tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/`) is
 the **primary fixture-extension surface** — it's a real TwinCAT XAE project
 committed object-by-object as `.TcGVL` / `.TcDUT` / `.TcPOU` files. Most PRs
 extend it by adding GVL variables, DUTs (structs / enums / aliases), or POUs
 (function blocks driving live data churn). The TCBSD VM at AmsNetId
 `41.169.163.43.1.1` on `10.100.0.128` is the deployment target (per memory
 entry `project_tcbsd_fixture.md`); the project bypasses the local Hyper-V/RTIME
 conflict (per `project_twincat_hyperv_conflict.md`) by running on ESXi.
 ### User docs touched
 | PR | `docs/Driver.TwinCAT.Cli.md` | `docs/drivers/TwinCAT-Test-Fixture.md` | `docs/v3/twincat-backlog.md` | Other |
 |---|---|---|---|---|
 | 1.1 LINT/ULINT | Data-types caveat removed | Bugs-caught entry #4 | — | — |
 | 1.2 TIME/DATE/DT/TOD | Native-type syntax + 4 examples | — | — | — |
 | 1.3 Bit-write | `write` example + RMW note | Bugs-caught entry #3 update | — | — |
 | 1.4 Arrays | New "Arrays" sub-section + read example | Coverage list bullet | — | — |
 | 1.5 ENUM/ALIAS | `browse` data-types rows | Coverage list bullet | — | — |
 | 2.1 Sum cmds | — | New "Performance" section | Closed-out perf bullet | — |
 | 2.2 Handles | Cache note in `read` / `subscribe` | Perf-section paragraph | — | — |
 | 2.3 Sym-version | — | Online-change-handling caveat dropped | — | — |
 | 3.1 MaxDelay | `--max-delay-ms` flag | Coalescing caveat updated | — | — |
 | 3.2 Diagnostics | `probe` health-symbols sub-section | New "Diagnostics" section | Cycle-time bullet closed | — |
 | 4.1 UDT | New top-level "UDT decomposition" section | Coverage list per-member | UDT-decomp gap removed | — |
 | 5.1 Alarms | New `alarms` subcommand | "Alarms" caveat removed | — | **New** `docs/drivers/TwinCAT.md`; **new** `docs/v3/twincat-eventlogger-spike.md` |
 ### TCBSD fixture PLC project changes
 | PR | GVL changes | DUT changes | POU changes | README section |
 |---|---|---|---|---|
 | 1.1 LINT/ULINT | `GVL_Primitives.vLargeCounter`, `vLargeCounterU` | — | — | "GVL_Primitives numeric seeds" |
 | 1.2 TIME/DATE/DT/TOD | `GVL_Primitives.dCurrentTime`, `tCycleDuration`, `dToday`, `tShiftStart` | — | — | "Type coverage" seed values |
 | 1.3 Bit-write | _(reuse `GVL_Primitives.vWord`)_ | — | — | — |
 | 1.4 Arrays | `GVL_Arrays.aReal2D : ARRAY[1..5,1..5] OF REAL` | — | — | "Array coverage" |
 | 1.5 ENUM/ALIAS | _(reuse `GVL_Enums`; new `currentSeverity`/`currentTemperature` instance vars)_ | — | — | "Integration-test contract" entry |
 | 2.1 Sum cmds | **`GVL_Perf.aTags : ARRAY[1..1000] OF DINT`** | — | New `FB_PerfChurn` driving rotating writes | New "Performance scenarios" subsection |
 | 2.2 Handles | _(reuse `GVL_Perf.aTags`)_ | — | — | — |
 | 2.3 Sym-version | _(no schema change; manual online-change drill)_ | — | — | New "Online-change test scenario" |
 | 3.1 MaxDelay | _(reuse `GVL_Fixture.nCounter` 100 Hz driver)_ | — | — | One-line note in "Required project state" |
 | 3.2 Diagnostics | _(reads system GVLs `_AppInfo`, `_TaskInfo[1]`)_ | — | — | Probe-symbols callout |
 | 4.1 UDT | _(reuse `GVL_Plant`; possibly grow `aLargeAlarms : ARRAY[1..2000] OF ST_AlarmRecord`)_ | New `ST_NestedFlags`, `ST_RecursiveCap`, `ST_AlarmRecord` | — | "Complex hierarchy" edge-cases |
 | 5.1 Alarms | New `GVL_Alarms` (trigger booleans) | — | New `FB_AlarmHarness` calling `FB_TcLogEvent` | New "Alarm scenarios" |
 ### Integration test additions
 All new tests gate on `[TwinCATFact]` / `[TwinCATTheory]` against
 `TWINCAT_TARGET_NETID`. Most ship in `tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.
 IntegrationTests/TwinCAT3SmokeTests.cs`; PR 5.1 introduces a new
 `TwinCATAlarmIntegrationTests.cs`. The existing 30-case suite grows to
 roughly **45 cases** end-of-plan, plus a perf-tier guarded behind
 `TWINCAT_PERF=1`.
 ### E2E scripts
 `scripts/e2e/test-twincat.ps1` is the single TwinCAT e2e bridge today; it's
 gated behind `TWINCAT_TRUST_WIRE=1` (see task #221 — CI fixture). The plan
 intentionally **does not change** the canonical bridge for most PRs because
 the bridge exercises one DINT counter through the OPC UA server, and that
 path stays correct. PRs 1.2 (DT bridge), 1.4 (array bridge), 4.1 (UDT
 bridge), 5.1 (alarm round-trip) each list speculative e2e extensions but
 they're explicitly marked as follow-ups gated on server-side rendering
 catching up.
 ## Skip-rated items (for context)
 These are intentionally not built. Listed for future-reader completeness so
 nobody re-invests effort that was already triaged:
 | # | Gap | Why skip |
 |---|---|---|
 | 9 | Multi-target / multi-route AMS gateway | Per-device config in `TwinCATDriverOptions.Devices` already supports N targets |
 | 10 | Secure ADS / ADS-over-TLS | Significant work — TC3.1 build 4024+ feature, host-router-level config; defer |
 | 11 | Route credential management | Host-level AMS router responsibility (`StaticRoutes.xml`); not driver scope |
 | 12 | NC-axis / CNC channel / EtherCAT slave I/O | Specialty; system-symbol filter actively drops `Mc_*` (`TwinCATSystemSymbolFilter.cs:28`) |
 | 13 | System-service ports (200/10000) | Niche operational tooling; user-runtime ports cover real use cases |
 | 15 | PLC RPC / method invocation | Niche; design-heavy; no demand signal yet |
 | 16 | Per-PLC-runtime auto-discover | Cosmetic; manual port config in options works |
 | 20 | File-system access via ADS (FOPEN/FREAD) | Niche; out of scope |
 ## Open questions
 1. **(a) TMC parsing — separate library or embedded?**
   Phase 4 ships the **online type-walker** path which uses
   `Beckhoff.TwinCAT.Ads.TypeSystem.SymbolLoaderFactory` and needs a live
   runtime. If a future use case needs offline discovery (e.g. address-space
   pre-bake at build time without a reachable PLC), do we:
   - vendor a TMC-XML parser into this driver, or
   - build a separate `ZB.MOM.WW.OtOpcUa.Tooling.TwinCAT` CLI that emits a
     pre-baked tag manifest?
   The latter cleanly separates build-time tooling from runtime driver code
   and matches how Galaxy.Host is split. Decision deferred until demand
   appears; recommend the CLI route when it does.
 2. **(b) Beckhoff TC3 EventLogger NuGet — published, or AMS port 110 raw?**
   Need to spike against the current `Beckhoff.TwinCAT.Ads` v6 NuGet API
   surface. Beckhoff InfoSys lists a `Tc3_EventLogger` PLC library and a
   TcCOM C++ API but the .NET surface is thinner. PR 5.1 starts with a
   one-day spike documented as `docs/v3/twincat-eventlogger-spike.md` before
   committing to the implementation path.
 3. **(c) Symbol-version invalidation event details**
   PR 2.3 needs the exact index-group constant and notification semantics for
   the symbol-version counter. `AdsReservedIndexGroup.SymbolVersion` (0xF008)
   is the working hypothesis but the field on the v6 enum needs verification
   — the older `TwinCAT.Ads.AdsReservedIndexGroup` enum had different naming.
   Beckhoff InfoSys `tcadscommon/tcadscommon_indexgroups` is the reference;
   confirm during the PR 2.3 spike. Fallback: poll the version counter at
   probe-loop cadence and treat any change as an invalidation.
 ## References
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs`
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs`
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDataType.cs`
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATSymbolPath.cs`
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATSystemSymbolFilter.cs`
 - `src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATAmsAddress.cs`
 - `docs/featuregaps.md` — TwinCAT (Beckhoff ADS) section
 - `docs/v3/twincat-backlog.md` — deferred items (TC2, multi-hop, lab IPC)
 - `docs/drivers/TwinCAT-Test-Fixture.md` — TCBSD + XAR fixture details
 - Beckhoff InfoSys: <https://infosys.beckhoff.com/english.php?content=../content/1033/tcadsdll2/117571083.html> (Sum commands)
 - Beckhoff InfoSys: <https://infosys.beckhoff.com/english.php?content=../content/1033/tcadsnetref/7313319051.html> (NotificationSettings)
 - Beckhoff GitHub: <https://github.com/Beckhoff/TC3-AdsClient-Csharp>
--- a/docs/v2/focas-deployment.md
+++ b/docs/v2/focas-deployment.md
@@ -0,0 +1,159 @@
 # FOCAS deployment guide
 Operational reference for deploying the Fanuc FOCAS driver in production.
 ## Licence + DLL provisioning
 Fanuc's FOCAS2 library is proprietary + closed-source. Two DLL variants exist:
 | Variant | Bitness | OtOpcUa usage |
 |---|---|---|
 | **`Fwlib64.dll`** | x64 | **Default production binary.** Loaded by `Driver.FOCAS.Host` (net10.0 x64 Windows service) and by the `Driver.FOCAS.Cli` when running on an x64 server. |
 | `Fwlib32.dll` | x86 | Historical — what the project was originally scaffolded against. Not used by any current binary post the 2026-04-23 Host retarget. Kept in the licence set for legacy deployments that insist on x86-only Hosts. |
 Both are **licensed for this project** — this project has a valid Fanuc FOCAS developer-kit licence that grants redistribution for either variant internally.
 ### The DLLs now ship with the Host (2026-04-23)
 As of the vendoring change, the Host csproj copies the licensed FOCAS binaries from [`vendor/fanuc/`](../../vendor/fanuc/README.md) to its build output automatically. So after a `dotnet build` / `dotnet publish`, the layout is:
 ```
 <publish-root>\Driver.FOCAS.Host\
 ├── OtOpcUa.Driver.FOCAS.Host.exe
 ├── OtOpcUa.Driver.FOCAS.Host.dll
 ├── ... runtime deps ...
 ├── Fwlib64.dll               ← master FOCAS runtime (generic x64)
 ├── fwlib0iD64.dll            ← 0i-D series dispatch target
 ├── fwlib30i64.dll            ← 30i / 31i / 32i series dispatch target
 ├── fwlibe64.dll              ← Ethernet transport variant
 ├── fwlibNCG64.dll            ← NC Guide (Fanuc PC simulator) target
 └── fwlib0DN64.dll            ← 0i-D Numeric-control thin variant
 ```
 No operator step required to "drop Fwlib64.dll on PATH" anymore — the Host loads `Fwlib64.dll` via bare-name and Windows finds it in the exe's own directory first. Shipping the full set of series-specific siblings lets the Host work against any Fanuc CNC the deployment points it at; the master `Fwlib64.dll` dispatches to the right variant based on what the CNC reports during `cnc_allclibhndl3`.
 The DLL loads lazily on the first `OpenSessionAsync` call. When somehow missing (deployment artefact surgery), `Fwlib64FocasBackend` returns a structured `Fwlib64DllMissing` error-code rather than crashing; the Proxy maps it to `BadCommunicationError` with a clear operator message.
 ### Repo confidentiality note
 **The FOCAS runtime DLLs in `vendor/fanuc/` are licensed binaries — treat this repo accordingly.** Do not mirror / push / fork to any public forge without first confirming the redistribution is covered by whoever manages the Fanuc relationship. Internal / customer-licensed mirrors are fine. See [`vendor/fanuc/README.md`](../../vendor/fanuc/README.md) for the full provenance + licence context.
 ## Tier-C architecture recap
 The FOCAS driver is **Tier-C** — out-of-process — for **blast-radius isolation**, not bitness. Fanuc's DLL has documented crash modes (network errors, malformed responses, handle-recycle bugs) that could take the main OPC UA server down if loaded in-process. Splitting the P/Invoke into a separate Host process means a Fwlib crash only loses FOCAS tags; every other driver keeps running, and the supervisor restarts the Host.
 Galaxy has the same pattern but is **forced** by MXAccess's 32-bit-only COM — there's no x64 path. FOCAS would work in-process on x64 (Fwlib64 is licensed), but the blast-radius argument keeps it Tier-C anyway.
 See [`implementation/focas-isolation-plan.md`](implementation/focas-isolation-plan.md) for the full topology.
 ## Installing the Host service
 Use the NSSM wrapper script:
 ```powershell
 .\scripts\install\Install-FocasHost.ps1 `
  -InstallRoot 'C:\Program Files\OtOpcUa\Driver.FOCAS.Host' `
  -ServiceAccount 'OTOPCUA\svc-otopcua' `
  -FocasBackend fwlib64
 ```
 Parameters:
 | Parameter | Default | Purpose |
 |---|---|---|
 | `-InstallRoot` | **required** | Where the Host binaries + `Fwlib64.dll` live |
 | `-ServiceAccount` | **required** | Must match the main OtOpcUa server account so the named-pipe ACL allows the Proxy to connect |
 | `-FocasBackend` | `fwlib64` | `fwlib64` (production), `fake` (in-memory for Tier-C pipeline smoke without a CNC), `unconfigured` (returns BadDeviceFailure for every call) |
 | `-FocasSharedSecret` | auto-gen | Per-process secret passed at service start so it never touches disk |
 | `-FocasPipeName` | `OtOpcUaFocas` | Named pipe the Proxy connects to |
 | `-ServiceName` | `OtOpcUaFocasHost` | Windows service display name |
 `fwlib32` is accepted as a legacy alias but maps to `Fwlib64FocasBackend` internally — the Host is x64 post-2026-04-23, so 32-bit-only deployments would need to rebuild + retarget.
 ## Configuring a FOCAS driver instance
 In the Admin UI's Drivers tab, create a `DriverInstance` with `DriverType = "FOCAS"` and a JSON config of the shape:
 ```json
 {
    "Backend": "ipc",
    "PipeName": "OtOpcUaFocas",
    "SharedSecret": "<matches OTOPCUA_FOCAS_SECRET env var on the Host>",
    "Devices": [
        { "Name": "Mill-01", "HostAddress": "focas://192.168.1.50:8193", "Series": "ThirtyOne_i" }
    ],
    "Tags": [
        { "Name": "SpindleLoad",  "DeviceName": "Mill-01", "Address": "R100",        "DataType": "Int16" },
        { "Name": "CycleRunning", "DeviceName": "Mill-01", "Address": "X0.0",        "DataType": "Bit"   },
        { "Name": "PartCount",    "DeviceName": "Mill-01", "Address": "MACRO:500",   "DataType": "Float64" }
    ],
    "Probe": { "Enabled": true, "IntervalMs": 5000, "TimeoutMs": 2000 }
 }
 ```
 `Backend` selector (on the Proxy side — not to be confused with `OTOPCUA_FOCAS_BACKEND` on the Host):
 | Value | Meaning |
 |---|---|
 | `ipc` (default) | Route through `Driver.FOCAS.Host` over the named pipe. **Production shape.** |
 | `fwlib` | Direct in-process P/Invoke via `FwlibFocasClient`. Only valid on x64 servers that are willing to accept the blast-radius trade-off. |
 | `unimplemented` | Throws at construction — used for scaffolding `DriverInstance` rows before the Host is deployed. |
 ## Smoke testing
 **Without a CNC — pipeline only:**
 ```powershell
 $env:OTOPCUA_FOCAS_BACKEND = "fake"
 Start-Service OtOpcUaFocasHost
 ```
 The `FakeFocasBackend` stores per-address values in-memory and survives read/write/subscribe exercising. Use `otopcua-focas-cli` (in-process, bypasses the Host) or the OtOpcUa server's own driver registration to exercise the pipeline.
 **Version-aware fake** (Stream A of the simulator plan, shipped 2026-04-23) — set `OTOPCUA_FOCAS_SERIES` to simulate a specific Fanuc controller's capability matrix. Addresses outside the series' documented ranges get rejected with `BadOutOfRange` (matching what the real DLL returns as `EW_NUMBER` / `EW_PARAM`):
 ```powershell
 $env:OTOPCUA_FOCAS_BACKEND = "fake"
 $env:OTOPCUA_FOCAS_SERIES = "ThirtyOne_i"   # or Zero_i_D / Zero_i_F / Sixteen_i / PowerMotion_i / ...
 Start-Service OtOpcUaFocasHost
 ```
 **Optional behavioural quirks** — `OTOPCUA_FOCAS_QUIRKS` is a comma-separated list:
 | Token | Behaviour |
 |---|---|
 | `EditMode` | `OpenSessionAsync` refuses sessions with `ErrorCode=EditModeActive`, mimicking a CNC in Edit mode |
 | `Emergency` | `ProbeAsync` reports the session as unhealthy with `emergency-stop active` error even after a clean open — exercises the driver's probe-surfaces-non-connectivity path |
 | `SlowFirstConnect[=ms]` | First `OpenSessionAsync` blocks for `ms` (default 3000) milliseconds, mimicking the 16i-series slow-first-connect — subsequent opens are fast |
 | `CrashAfterCycles=N` | After `N` session opens, the `N+1`-th returns `ErrorCode=Fwlib64Crashed` — mimics the documented Fanuc handle-leak |
 Example combining several:
 ```powershell
 $env:OTOPCUA_FOCAS_QUIRKS = "EditMode,CrashAfterCycles=5,SlowFirstConnect=500"
 ```
 Unknown tokens log a warning but don't abort startup.
 **With a real CNC:**
 ```powershell
 $env:OTOPCUA_FOCAS_BACKEND = "fwlib64"
 $env:FOCAS_TRUST_WIRE = "1"
 Start-Service OtOpcUaFocasHost
 .\scripts\e2e\test-focas.ps1 -CncHost 192.168.1.50 -BridgeNodeId 'ns=2;s=Focas/R100'
 ```
 Requires `Fwlib64.dll` on `PATH` alongside the Host exe.
 ## Observability
 - Host logs: `%ProgramData%\OtOpcUa\focas-host-*.log` (Serilog daily rolling)
 - Post-mortem: `%ProgramData%\OtOpcUa\focas-post-mortem.mmf` — ring buffer of the last ~1000 IPC operations, survives a Host crash so the Proxy-side supervisor can read it during respawn diagnostic
 - `DriverHostStatus` rows in the central Config DB under `HostName = <configured device host>` — `State` transitions + Polly resilience counters surface on the Admin `/hosts` page
 ## Known issues
 - **No public simulator** — Fanuc FOCAS has no published emulator. Lab-rig validation (a real FANUC 0i-F / 30i controller or an FDK-licenced dev rig) is the only way to confirm wire-level correctness. Tracked under task #222.
 - **32-bit-only deployments unsupported** — post the 2026-04-23 retarget, running the Host as net48 x86 is not a supported mode. If you genuinely need Fwlib32-only, revert the Host csproj + Program.cs changes from that commit.
 - **Handle-recycling cadence** — documented Fanuc issue where long-lived FWLIB session handles can leak inside the DLL; the Host periodically cycles them. Currently on a fixed 60-minute cadence; future config knob tracked as a post-release follow-up.
--- a/docs/v2/implementation/focas-simulator-plan.md
+++ b/docs/v2/implementation/focas-simulator-plan.md
@@ -0,0 +1,315 @@
 # FOCAS Docker simulator — implementation plan
 > **Status**: **IN PROGRESS** 2026-04-23. **Streams A + B shipped.** Stream C (real Fwlib64 wire compat) + Stream D (e2e + docs) still open — both require a Windows rig with licensed Fwlib64.dll + captured Wireshark traces. Stream B shipped the full architectural scaffold (Docker image, 9 per-series compose profiles, asyncio TCP server, handler dispatch, profile-driven range enforcement, local validation harness) — exercised end-to-end against both `thirtyone_i` and `powermotion_i` profiles.
 ## Goal
 Close the one remaining FOCAS gap (`#222` follow-up — "wire-level live-boot against real hardware") with a hardware-free fixture that:
 1. Runs in Docker, matches the per-driver fixture pattern (`docker compose up -d` in the test project).
 2. Exposes the FOCAS TCP port (`8193` by default) to the host.
 3. Speaks enough of the FOCAS wire protocol that **a Windows test rig running our unmodified `Driver.FOCAS.Host` + licensed `Fwlib64.dll` can open a session and exercise the 9 FWLIB functions the driver actually uses.**
 4. Supports **version profiles** — one container per Fanuc series (0i-D, 0i-F, 30i, 31i, 32i, PowerMotion-i) — so driver-side range validation, error-code mapping, and per-series quirks get exercised against a server that actually behaves differently per series.
 5. Plugs into the existing e2e infrastructure (`scripts/e2e/test-focas.ps1` loses the `FOCAS_TRUST_WIRE=1` gate when the fixture is up).
 ## Non-goals
 - **Not a full FOCAS emulator.** Fanuc's FOCAS spec is closed; faithfully reproducing every function across every controller model would be a years-long project. We implement the narrow subset the driver uses (see §Protocol surface).
 - **Not a CNC behavioural model.** We return plausible values for PMC/param/macro reads; we do NOT simulate axis motion, program execution, or alarm generation. The mock exists to exercise the driver's marshalling + IPC + status-code paths, not to prove the CNC behaves correctly.
 - **Not a replacement for a bench CNC.** A physical controller still catches timing-dependent bugs (Fwlib-internal thread-pool exhaustion, handle-recycle pathologies, vendor-firmware quirks) that a mock can't reproduce. Mock covers ~80% of value; real-hardware smoke stays as a final gate.
 ## Constraint that shapes the design
 `Fwlib64.dll` is a proprietary closed-source library that speaks FOCAS to the CNC. **Our driver never touches raw TCP** — it calls `cnc_allclibhndl3` / `pmc_rdpmcrng` / etc. and Fwlib encodes the wire frames internally.
 This means the mock has two possible architectures:
 | Option | Where the mock lives | Exercises Fwlib? |
 |---|---|---|
 | **A. IPC-layer fake** (already shipped as `FakeFocasBackend`) | Between `FwlibFrameHandler` and the FWLIB call | ❌ No — bypasses Fwlib entirely |
 | **B. TCP wire mock** (this plan) | Listens on port 8193; Fwlib connects to it | ✅ Yes — Fwlib encodes real frames |
 Option B is the only one that validates the driver's actual production wire path (driver → Host → `FwlibFocasClient` → `Fwlib64.dll` → TCP → mock).
 **Prerequisite reading** the implementer needs before starting Option B:
 - `strangesast/fwlib` on GitHub — reverse-engineered FOCAS2 Linux client, has frame-format notes
 - `GalvinGao/opcua-server-fanuc` — another OSS FOCAS client with wire-format traces
 - `jdegre/focas-python` (if it still exists) — previous Python FOCAS stub, starting point
 - Our own `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FwlibNative.cs` — the 9-function surface we need to satisfy
 ## Protocol surface (what the mock must speak)
 From `FwlibNative.cs`, our driver makes exactly 9 FWLIB calls:
 | FWLIB function | What it does | Wire complexity |
 |---|---|---|
 | `cnc_allclibhndl3` | Open Ethernet handle (connect) | **High** — initial handshake, version negotiation, session state |
 | `cnc_freelibhndl` | Close handle | Low |
 | `pmc_rdpmcrng` | PMC range read (byte/word/long + optional bit) | **Medium** — 40-byte buffer with type-dependent layout |
 | `pmc_wrpmcrng` | PMC range write | **Medium** — same buffer shape inverted |
 | `cnc_rdparam` | Parameter read (axis-aware) | Medium — 32-byte buffer |
 | `cnc_wrparam` | Parameter write | Medium |
 | `cnc_rdmacro` | Macro variable read (value + decimal-point count) | Low |
 | `cnc_wrmacro` | Macro variable write | Low |
 | `cnc_statinfo` | Status info (for probe) | Low — fixed-shape response |
 **Coverage target**: all 9 functions return plausible responses for the address ranges declared in each series profile. Out-of-range addresses return `EW_NUMBER` / `EW_PARAM`. Unknown PMC letters return `EW_DATA`. Session state (handle validity, unknown handle detection) is enforced.
 ## Version profiles
 The driver has `FocasCncSeries` + `FocasCapabilityMatrix` already — we mirror that matrix into JSON profiles the mock loads at start:
 ```
 fixture/
 ├── Dockerfile
 ├── requirements.txt
 ├── server/
 │   ├── focas_server.py          # asyncio TCP server + frame parser
 │   ├── handlers/
 │   │   ├── allclibhndl3.py
 │   │   ├── pmc.py
 │   │   ├── param.py
 │   │   ├── macro.py
 │   │   └── status.py
 │   ├── state.py                 # in-memory "CNC" state
 │   └── frames.py                # FOCAS frame encode/decode
 └── profiles/
    ├── zero_i_d.json
    ├── zero_i_f.json
    ├── zero_i_mf.json
    ├── zero_i_tf.json
    ├── sixteen_i.json
    ├── thirty_i.json
    ├── thirtyone_i.json
    ├── thirtytwo_i.json
    └── powermotion_i.json
 ```
 Each profile captures:
 ```json
 {
    "series": "ThirtyOne_i",
    "api_version": "0x30",
    "pmc_ranges": {
        "X": [0, 127], "Y": [0, 127], "F": [0, 767], "G": [0, 767],
        "R": [0, 1499], "D": [0, 2999], "C": [0, 199], "K": [0, 31],
        "A": [0, 24], "T": [0, 79], "E": [0, 9999]
    },
    "param_ranges": [[1000, 9999], [10000, 15999]],
    "macro_range": [100, 999],
    "extended_macros": false,
    "axes": 3,
    "quirks": {
        "crash_after_handle_cycles": null,
        "edit_mode_rejects_connection": false,
        "allclibhndl3_blocks_during_alarm": false,
        "param_bit_index_max": 7
    },
    "alarm_default": false,
    "emergency_default": false
 }
 ```
 **Differences that actually matter** for driver coverage:
 | Series | Meaningful difference vs baseline |
 |---|---|
 | 0i-D / 0i-F / 0i-MF / 0i-TF | PMC range narrower; no E-relay; macro range `100-999` strict |
 | 16i | Older Fwlib version; `cnc_allclibhndl3` extra-slow on first connect (artificial delay in mock) |
 | 30i | Full PMC range; extended macros (`#10000+`) supported |
 | 31i / 32i | 5-axis; larger parameter ranges |
 | PowerMotion-i | No PMC `T` timer; motion-only controller quirks |
 ## Architecture
 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │  Windows test rig (net10.0 x64)                                 │
 │                                                                 │
 │  FocasDriver ──► FwlibFocasClient ──► Fwlib64.dll ──► TCP ──┐   │
 │                       (real P/Invoke)                       │   │
 └─────────────────────────────────────────────────────────────┼───┘
                                                              │
                              port 8193                       │
                                                              ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │  Docker container: otopcua-focas-sim-{series}                   │
 │                                                                 │
 │  Python asyncio TCP server                                      │
 │    ├─ frames.py: parse + encode FOCAS frames                    │
 │    ├─ handlers/: one module per FWLIB function                  │
 │    ├─ state.py: per-session handle registry + simulated memory  │
 │    └─ profiles/{series}.json: range + quirk table loaded at     │
 │                               boot via env var OTOPCUA_FOCAS_   │
 │                               PROFILE=thirtyone_i               │
 └─────────────────────────────────────────────────────────────────┘
 ```
 Python choice rationale: the existing OSS FOCAS implementations are Python-first; asyncio's `StreamReader`/`StreamWriter` maps cleanly to FOCAS's length-prefixed frame model; one Dockerfile covers every profile because profile-switching is an env-var.
 `docker-compose.yml` exposes one service per profile as a `--profile`:
 ```yaml
 services:
  focas-thirtyone:
    profiles: ["thirtyone"]
    image: otopcua-focas-sim:latest
    environment: { OTOPCUA_FOCAS_PROFILE: "thirtyone_i" }
    ports: ["8193:8193"]
  focas-zerod:
    profiles: ["zerod"]
    image: otopcua-focas-sim:latest
    environment: { OTOPCUA_FOCAS_PROFILE: "zero_i_d" }
    ports: ["8193:8193"]
  # ... one per supported series ...
 ```
 Users pick a profile with `docker compose --profile thirtyone up -d`. Only one profile runs at a time (port collision on 8193) — matching the other driver fixtures' single-image pattern.
 ## Delivery plan — three streams
 ### Stream A — Version-aware fake backend (C#, 2-3 days) — ✅ **SHIPPED 2026-04-23**
 **What landed**:
 - `FakeFocasBackend` gained a second ctor `(FocasCncSeries series, FakeFocasBackendQuirks? quirks)`; default ctor preserves the pre-Stream-A permissive behaviour.
 - `ValidateAddress` delegates to the existing `FocasCapabilityMatrix.Validate` so mock + driver share one source of truth. Out-of-range reads/writes/PMC-bit-writes return `BadOutOfRange` (0x803C0000 — matching what the real driver maps `EW_NUMBER`/`EW_PARAM` to).
 - `FakeFocasBackendQuirks` record carries four opt-in quirks: `EditModeRejectsConnection`, `CrashAfterHandleCycles`, `SlowFirstConnectDelay`, `EmergencyAtStartup`.
 - `Program.cs` reads `OTOPCUA_FOCAS_SERIES` (case-insensitive FocasCncSeries enum value) + `OTOPCUA_FOCAS_QUIRKS` (comma-separated token list: `EditMode`, `Emergency`, `SlowFirstConnect[=ms]`, `CrashAfterCycles=N`). Unknown tokens log-and-ignore. Values surface in Host log at startup.
 - 19 new tests in `FakeFocasBackendSeriesTests.cs` covering: Unknown-permissive baseline, Zero_i_D macro rejection, ThirtyOne_i extended-macro acceptance, PowerMotion_i T-timer rejection, Write+PmcBitWrite parallel rejection, all four quirks, + 8 theory cases for the env-var parser.
 **Deliverable shipped**:
 - `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/Backend/FakeFocasBackend.cs` — extended
 - `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/Program.cs` — `BuildFakeBackend` local fn + `ParseFakeQuirks` helper
 - `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host.Tests/FakeFocasBackendSeriesTests.cs` — new, 19 tests
 - 38/38 Host tests green post-Stream-A.
 ### Stream B — Python FOCAS TCP server (scaffold) — ✅ **SHIPPED 2026-04-23**
 **What landed** under `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/Docker/`:
 - `Dockerfile` — Python 3.12-slim image; stdlib-only, no external deps
 - `docker-compose.yml` — 9 `--profile` entries, one per Fanuc series (`thirtyone`, `thirtytwo`, `thirty`, `sixteen`, `zerod`, `zerof`, `zeromf`, `zerotf`, `powermotion`). All share one image + one port (8193).
 - `server/focas_server.py` — asyncio entry point, per-connection session loop, graceful-shutdown signal handling
 - `server/frames.py` — length-prefixed frame codec (scaffold — see Stream C note below)
 - `server/state.py` — per-session handle registry + in-memory PMC/param/macro dictionaries
 - `server/profile.py` — JSON profile loader
 - `server/handlers/` — one module per FWLIB function (9 total): open/close, PMC read/write, param read/write, macro read/write, statinfo. Profile-driven range validation; error responses use a `FLAG_ERROR` bit on the response header.
 - `profiles/*.json` — 9 series profiles mirroring `FocasCapabilityMatrix`. Quirks (`slow_first_connect_ms`, `alarm_default`, `emergency_default`, `crash_after_handle_cycles`, `edit_mode_rejects_connection`) declared per profile.
 - `validate_harness.py` — scaffold-protocol TCP client that opens a session, round-trips a macro, triggers range-rejection, asserts the expected error reasons surface.
 - `README.md` — operator-facing usage + Stream C next-steps checklist.
 **Exit criterion met**: validated end-to-end against two profiles (`thirtyone_i`, `powermotion_i`) via the local harness. Session handshake → statinfo → macro round-trip → out-of-range rejection → PMC round-trip → bad-letter rejection → clean close — all PASS. Profile-switching confirmed working: 31i API 0x0030 → PowerMotion 0x0040, macro range [0,99999]→[0,999], letter set {A,C,D,E,F,G,K,M,R,T,X,Y}→{D,R,X,Y}.
 **⚠️ The wire *framing* is a scaffold — NOT Fwlib64-compatible yet.** `server/frames.py` uses a plausible length-prefixed framing (big-endian header: uint32 length, uint16 function_id, uint16 flags) that satisfies the harness but has never been validated against the real Fanuc DLL. Stream C is the iterative refinement cycle where a Windows rig drives that convergence.
 **The response payload shapes inside those frames ARE authoritative** (refined 2026-04-23 after `fwlib32.h` review):
 - `ODBM` (macro read) = 10 bytes: `short datano, short dummy, int32 mcr_val, short dec_val`
 - `ODBST` (statinfo) = 18 bytes: 9 × `short` (dummy/tmmode/aut/run/motion/mstb/emergency/alarm/edit)
 - `IODBPSD` (param read) = 36 bytes: `short datano, short type, bytes[32]` (union = 8 axes × 4 bytes)
 - `IODBPMC` (PMC range read) = 48 bytes: `short type_a, short type_d, uint16 datano_s, uint16 datano_e, bytes[40]`
 Validate harness asserts exact byte sizes + header field round-trip. When Stream C's Wireshark traces arrive, the payload layer should already match — only framing needs iteration.
 See [`focas-wire-protocol.md`](focas-wire-protocol.md) for the authoritative-vs-guessed breakdown.
 **C# integration test scaffold** also shipped (`tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/`) — `FocasSimFixture` probes port 8193 + skips when the container's down; three smoke tests pass against a running container (TCP reachability, clean connect-close, profile parsing). A `Series/WireCompatGatedTests.cs` skeleton gates Fwlib64-dependent tests behind `OTOPCUA_FOCAS_SIM_WIRE_COMPAT=1`, ready for Stream C activation.
 ### Stream C — FWLIB compat + version profiles (2-3 weeks) — **blocked on Windows rig + Wireshark traces**
 See `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/Docker/README.md` §"Stream C — what's required to reach wire compatibility" for the concrete implementer checklist.
 **Goal**: real Fwlib64.dll running on a Windows test rig can open a session against the mock and round-trip the 9 FWLIB calls our driver makes.
 Sub-tasks:
 1. **Handshake** (`handlers/allclibhndl3.py`) — the hardest piece. FOCAS session open negotiates protocol version + controller type. Incorrect negotiation → Fwlib disconnects. Start from `strangesast/fwlib`'s handshake trace.
 2. **PMC read/write** (`handlers/pmc.py`) — 40-byte buffer with type-dependent layout. Must match `FwlibNative.IODBPMC` struct layout exactly. Implement per-profile range checks.
 3. **Parameter read/write** (`handlers/param.py`) — 32-byte axis-aware buffer. Similar to PMC but simpler (no sub-address bit indexing beyond `param_bit_index_max`).
 4. **Macro read/write** (`handlers/macro.py`) — straightforward; value + decimal-point count as `ODBM`.
 5. **Status info** (`handlers/status.py`) — fixed `ODBST` shape; profile declares defaults for `Aut` / `Run` / `Motion` / `Alarm`.
 6. **State management** (`server/state.py`) — per-session handle registry, in-memory PMC/param/macro dictionaries, persistent across one session, reset on session close.
 7. **Profile loader** — reads `OTOPCUA_FOCAS_PROFILE` env var, loads matching JSON, injects into handlers.
 8. **Windows validation rig** — one-time setup: a Windows VM (or dev box) with licensed `Fwlib64.dll` + a tiny test driver that calls the 9 FWLIB functions + asserts round-trip. This is the first live-wire validation the plan asks for.
 9. **Per-series test matrix** — `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/` new project, one test class per series, each class's `[Fact]` runs against that profile's container.
 **Exit criterion**: live Fwlib64.dll on a Windows rig opens a session, reads + writes across all 9 FWLIB functions, against each of the 9 profiles. Integration test suite green.
 ### Stream D — e2e integration + doc close-out (1-2 days)
 - Update `scripts/e2e/test-focas.ps1` to accept `-ProfileName` and skip `FOCAS_TRUST_WIRE` gate when the matching container is up.
 - Add the FOCAS simulator to `docs/v2/test-data-sources.md` + `docs/drivers/FOCAS-Test-Fixture.md` (flip the "hardware-gated" caveat to "fixture or hardware").
 - Update `exit-gate-phase-3.md` — final FOCAS deferral closes.
 ## Test integration
 The new project `tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/` mirrors `Driver.OpcUaClient.IntegrationTests`:
 ```
 tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/
 ├── Docker/
 │   ├── docker-compose.yml           # references the 9 series profiles
 │   ├── Dockerfile                   # Python image
 │   ├── requirements.txt
 │   ├── server/
 │   └── profiles/
 ├── FocasSimFixture.cs               # probes 8193 at collection init, skips if down
 ├── FocasSimSeriesProfile.cs         # test-side mirror of the JSON profile
 └── Series/
    ├── ThirtyOneITests.cs
    ├── ZeroIDTests.cs
    └── ... one file per series ...
 ```
 The existing `FocasDocker`-less skip pattern applies: if the container isn't running, tests skip with a clear message pointing at `docker compose up -d`. Matches Modbus / S7 / OpcUaClient.
 ## Risks + mitigations
 | Risk | Likelihood | Impact | Mitigation |
 |---|---|---|---|
 | FOCAS wire protocol is more complex than the OSS traces suggest → Stream C slips weeks | **Medium** | High | Stream A delivers 70% value with zero protocol risk. If Stream C stalls, ship A + schedule C as a follow-up. |
 | Fwlib64.dll version differs from what `strangesast/fwlib` reverse-engineered → handshake fails | Medium | High | Capture Wireshark trace of a real CNC session against our actual licensed Fwlib64 version before coding. One-time investment, catches drift early. |
 | Profile differences that matter at the wire level aren't captured in `FocasCapabilityMatrix` | Medium | Medium | Stream C exit criterion includes validating each profile against live Fwlib — any mismatch is a profile-table bug we fix then. |
 | Docker container startup time breaks PR-CI budget | Low | Low | Each profile is one Python container + profile JSON — sub-5s cold start. Matches opc-plc. |
 | Windows validation rig availability blocks Stream C | Medium | High | Use the existing TCBSD-class approach: a dedicated ESXi VM with Windows + licensed Fwlib64.dll, provisioned once, shared by the team. Cost ~1 dev-day to set up; unblocks all future FOCAS work forever. |
 | Fanuc licence audit surfaces our mock as an "unlicensed FOCAS implementation" | **Low** | **High** | The mock doesn't ship the Fanuc DLL or reproduce any of Fanuc's code. Reverse-engineered wire formats from OSS research are fair use; the mock is our code. Consult legal before open-sourcing, not before internal use. |
 ## Timeline estimate
 Assuming one dev full-time:
 | Stream | Duration | Dependencies |
 |---|---|---|
 | A — Version-aware fake backend | 2-3 days | none |
 | B — TCP server scaffold | 1 week | Windows rig not required yet |
 | C — FWLIB compat + profiles | 2-3 weeks | Windows rig with Fwlib64 + Wireshark trace |
 | D — e2e + docs | 1-2 days | C done |
 **Total**: ~4-5 weeks to full coverage. Ship A immediately (independent value), start C in parallel with Windows-rig setup.
 ## Exit criteria (what closes #222)
 - [ ] All 9 series profiles containerized + pass startup health check
 - [ ] Live Fwlib64.dll round-trips all 9 FWLIB calls against every profile (Stream C validation rig)
 - [ ] Per-series integration test suite green in CI
 - [ ] `test-focas.ps1` runs end-to-end against the simulator without `FOCAS_TRUST_WIRE=1`
 - [ ] Docs updated: `FOCAS-Test-Fixture.md` flipped from "hardware-only" to "fixture or hardware"
 - [ ] One live-CNC smoke still runs during v2 release readiness, as a belt-and-braces final check
 ## Open questions
 1. **Licence clarity**: is reverse-engineered FOCAS2 wire-format documentation (from `strangesast/fwlib` etc.) compatible with our Fanuc FOCAS developer-kit licence? Legal check required before starting Stream C.
 2. **Windows rig**: do we dedicate an existing VM (like the TCBSD box) or provision a new one? Cost difference is small; decision affects who owns maintenance.
 3. **Profile source of truth**: if `FocasCapabilityMatrix.cs` and `profiles/*.json` ever disagree, which wins? Proposal: profiles win (wire behavior is authoritative), driver's matrix is regenerated from profiles as a build step.
 4. **Alarm events**: the driver doesn't currently use `cnc_rdalmmsg2` / alarm subscription, so the mock doesn't need to simulate alarms beyond the `statinfo.Alarm` flag. If we add `IAlarmSource` to FOCAS later, Stream C expands.
 ## References
 - `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FwlibNative.cs` — 9-function P/Invoke surface the mock must satisfy
 - `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasCapabilityMatrix.cs` — per-series range tables (profile seed data)
 - `docs/v2/focas-version-matrix.md` — human-readable version matrix the profiles mirror
 - `docs/drivers/FOCAS-Test-Fixture.md` — current test-fixture doc (flips post-Stream-D)
 - `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/Docker/` — pattern this plan mirrors for the Docker compose + fixture-skip shape
 - `strangesast/fwlib` (GitHub, OSS) — primary FOCAS wire-format reverse-engineering reference
--- a/followup.md
+++ b/followup.md
@@ -0,0 +1,87 @@
 # Follow-ups from `auto/driver-gaps` queue (PRs #225–#316, 92 merged)
 Captured 2026-04-26 after the plan-execution queue drained. Organised by category.
 ## Wrapper / library-version-blocked (waiting on upstream)
 | Driver | PR | Blocker | Resolution path |
 |---|---|---|---|
 | AbCip | abcip-3.1 | libplctag.NET 1.5.2 doesn't expose `connection_size` | Reflection fallback ships; remove when wrapper publishes the property |
 | AbCip | abcip-3.2 | libplctag.NET 1.5.x has no public instance-ID knob | Wire stays Symbolic regardless of mode; flip when wrapper exposes it |
 | AbCip | abcip-3.3 | libplctag.NET wire-level multi-service-packet bundling not exposed | Planner ships correct; runtime currently issues N reads. Switch when wrapper bundles |
 | S7 | s7-e1 | S7netplus 0.20 has no public `ReadSzlAsync` (request builder is internal) | Parser tested + cached; `BadNotSupported` until S7netplus exposes it or we add raw S7comm SZL-PDU helper |
 | S7 | s7-e2 | S7netplus 0.20 doesn't expose `SendPassword` | `IS7PlcAuthGate` reflection probe; logs warning, no exception. Flip when library exposes it |
 | TwinCAT | twincat-2.2 | Bulk Sum path stays on symbolic | Phase-2 perf sweep follow-up to switch bulk to handle-based |
 | TwinCAT | twincat-5.1 | Beckhoff doesn't ship a managed `TcEventLogger` wrapper | Gate seam ships; production `AdsTwinCATAlarmGate` binary decoder against `ADSIGRP_TCEVENTLOG_ALARMS` is the next chunk of work |
 ## Fixture / simulator gaps
 ### focas-mock simulator doesn't exist
 - Blocks integration tests for: f3a (alarm history ring-buffer + `mock_patch_alarmhistory`), f4b (`mock_set_unlock_state`, `mock_get_last_write`), f4c (`pmc_wrpmcrng` handler), f4d (`cnc_wrunlockparam` + `mock_set_password`), f5a (`mock_simulate_cycle_completion`).
 - No FOCAS IntegrationTests project exists yet — it needs to be created when the mock lands.
 ### opc-plc fixture upgrades
 - **opcuaclient-10**: `TriggerModelChangeAsync` is a stub. Live HTTP-driven model-change verification deferred. Tests use an inject seam.
 - **opcuaclient-11**: `opc-plc-rc` Docker fixture session-open assertion (gated `OPCUACLIENT_TOPOLOGY_TRIGGER_CMD` / `OPCUA_RC_SIM`).
 - **opcuaclient-12**: opc-plc `--alm` fixture run for HistoryRead Events (waiting for fixture image upgrade).
 - **opcuaclient-13**: opc-plc historian-sim wire-level sweep for the 25 new aggregates (only ~5 likely honoured today).
 - **opcuaclient-14**: Two-container failover smoke against opc-plc + opc-plc-secondary on the live fixture.
 ### AbCip HSBY paired-fixture
 - **abcip-5.1/5.2**: `hsby-mux` Python sidecar is a stub; the patched `ab_server` image and live role-flip integration test are gated until that stabilises.
 ### AbLegacy auto-demote fixture
 - **ablegacy-12**: `slc500-faulty` is a commented compose placeholder; tests use the `127.0.0.1:1` ECONNREFUSED trick. Real refusing-proxy fixture is follow-up.
 ### TCBSD TwinCAT project
 - twincat-2.1, 3.1, 3.2, 4.1, 5.1 added new fixture stub files that need to be imported into the actual TwinCAT XAE project before `[TwinCATFact]` integration tests can exercise them:
  - `PLC/GVLs/GVL_Perf.TcGVL` + `PLC/POUs/FB_PerfChurn.TcPOU` (twincat-2.1)
  - `PLC/DUTs/ST_NestedFlags.TcDUT`, `ST_RecursiveCap.TcDUT`, `ST_AlarmRecord.TcDUT` (twincat-4.1)
  - `PLC/GVLs/GVL_Plant.TcGVL` extensions (twincat-4.1)
  - `PLC/GVLs/GVL_Alarms.TcGVL` + `PLC/POUs/FB_AlarmHarness.TcPOU` (twincat-5.1)
 ### Snap7 round-trip tests
 - s7-d1 (TIA CSV), s7-d2 (UDT fan-out), s7-d3 (instance-DB), s7-c1 (negotiated PDU), s7-c3 (scan groups), s7-c4 (deadband) integration tests are build-only until run against the live Snap7 fixture.
 ## Live-firmware / hardware verification
 - **s7-c2** — hardened S7-1500 with non-PG TSAP modes (gated `--with-real-plc`).
 - **s7-c5** — hardened PLC with PUT/GET disabled (currently only Snap7 happy-path tested).
 - **s7-f** — manual checklist: toggle Optimized block access in TIA + Track 3 OPC UA bridge verification.
 - **ablegacy-13** — DH+ via real 1756-DHRIO + PLC-5. No Docker fixture possible.
 - **twincat-2.1 perf-tier** — `Driver_sum_read_1000_tags_beats_loop_baseline_by_5x` gated `TWINCAT_PERF=1`.
 - **twincat-2.3** — symbol-version online-change drill (`TWINCAT_MANUAL_ONLINE_CHANGE=1`).
 - **focas-f4b/c/d** — live CNC parameter / macro / PMC writes + password-protected CNC.
 ## Cross-driver / ecosystem
 - **opcuaclient-12** — Galaxy A&E projection currently keeps the fixed-field `ReadEventsAsync(sourceName, ...)` overload; richer SelectClause-aware projection on the Galaxy A&E log is best-effort future work.
 - **per-driver plan files don't exist** — opcuaclient-12 cross-driver `IHistoryProvider` heads-up went into doc-comments instead. If anyone adds per-driver plan files later, the heads-up note belongs in each.
 ## Pre-existing red-build issues (NOT touched, will block solution-level CI)
 - **NU1902 OpenTelemetry warning-as-error in Admin** — predates the queue.
 - **`Server/Phase7/DriverSubscriptionBridge.cs` cref ambiguity** — predates the queue.
 Both must be fixed before solution-level CI can pass on the merged-up `task-galaxy-e2e`.
 ## Integration-branch merge
 - **`auto/driver-gaps` has 92 stacked PRs** vs `task-galaxy-e2e`. Final merge needs a careful single review — likely staged or one big PR — and will collide with whatever has landed on `task-galaxy-e2e` in parallel.
 ## Plan-vs-reality deltas (informational; nothing to chase)
 - **focas-f4a/b/c/d** — Plan referenced doc lines that had already been removed in prior evolution (FOCAS.md "intentionally returns BadNotWritable" callout; FOCAS-Test-Fixture.md alarms-not-covered caveat).
 - **opcuaclient-12** — Repo has no per-driver plan files for abcip / ablegacy / s7 / twincat — heads-up went into IHistoryProvider doc-comments instead.
 - **twincat-4.1** — `docs/v3/twincat-backlog.md` doesn't exist; UDT-gap-removal item N/A.
 ## Highest-leverage cleanup once upstream catches up
 When the upstream library bumps, these reflection / `BadNotSupported` paths simplify to direct calls:
 - **abcip-3.1**: remove reflection fallback in `LibplctagTagRuntime.TrySetIntAttribute(connection_size, ...)`.
 - **abcip-3.2**: remove `LibplctagTagRuntime.TrySetLogicalAddressing` reflection.
 - **abcip-3.3**: switch `MultiPacket` runtime from N-reads to true wire-bundle.
 - **s7-e1**: replace `S7NetSzlReader.ReadAsync` returning null with real `Plc.ReadSzlAsync`.
 - **s7-e2**: replace `ReflectionS7PlcAuthGate` warning path with direct `Plc.SendPasswordAsync` call.
 - **twincat-5.1**: ship `AdsTwinCATAlarmGate` binary decoder.
--- a/scripts/e2e/test-opcuaclient.ps1
+++ b/scripts/e2e/test-opcuaclient.ps1
@@ -11,7 +11,7 @@
  of this test use `otopcua-cli` against two different endpoints:
    remote  = the upstream OPC UA server the driver connects to (opc-plc fixture
-              by default, opc.tcp://localhost:50000)
+              by default, opc.tcp://10.100.0.35:50000)
    local   = the OtOpcUa server itself, which mirrors remote nodes through the
              OpcUaClient driver instance (opc.tcp://localhost:4840)
@@ -72,7 +72,7 @@
 .PARAMETER RemoteUrl
  Upstream OPC UA server endpoint (the server the driver connects to).
-  Default matches the opc-plc Docker fixture — opc.tcp://localhost:50000.
+  Default matches the opc-plc Docker fixture — opc.tcp://10.100.0.35:50000.
 .PARAMETER OpcUaUrl
  Local OtOpcUa server endpoint. Default opc.tcp://localhost:4840.
@@ -146,7 +146,7 @@
 #>
 param(
-    [string]$RemoteUrl              = "opc.tcp://localhost:50000",
+    [string]$RemoteUrl              = "opc.tcp://10.100.0.35:50000",
    [string]$OpcUaUrl               = "opc.tcp://localhost:4840",
    [string]$RemoteNodeId           = "ns=3;s=FastUInt1",
    [Parameter(Mandatory)] [string]$BridgeNodeId,
--- a/scripts/queue/.label-ids.json
+++ b/scripts/queue/.label-ids.json
@@ -0,0 +1,21 @@
 {
  "auto-managed": 10,
  "cross-driver": 14,
  "driver/abcip": 13,
  "driver/ablegacy": 16,
  "driver/focas": 11,
  "driver/opcuaclient": 12,
  "driver/s7": 19,
  "driver/twincat": 17,
  "phase/1": 8,
  "phase/2": 7,
  "phase/3": 6,
  "phase/4": 5,
  "phase/5": 4,
  "phase/6": 3,
  "queue/blocked": 2,
  "queue/done": 15,
  "queue/failed": 9,
  "queue/in-progress": 1,
  "queue/queued": 18
 }
--- a/scripts/queue/.partial-twincat.yaml
+++ b/scripts/queue/.partial-twincat.yaml
@@ -0,0 +1,320 @@
 - id: twincat-1.1
  driver: twincat
  phase: 1
  plan_pr_id: "1.1"
  title: "TwinCAT — Int64 fidelity for LINT/ULINT"
  plan_anchor: "docs/plans/twincat-plan.md"
  summary: |
    Map LInt/ULInt to DriverDataType.Int64 instead of silently truncating to Int32.
    The TwinCATDataType.cs:40 truncation comment "matches Int64 gap" is removed and
    MapToClrType already returns long/ulong, so the wire-level read returns the
    correct boxed types. May add Int64 to Core.Abstractions DriverDataType enum if
    missing. Closes a long-standing fixture caveat noted in the test suite.
  files:
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDataType.cs"
    - "src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/DriverDataType.cs"
  docs:
    - "docs/Driver.TwinCAT.Cli.md"
    - "docs/drivers/TwinCAT-Test-Fixture.md"
  fixture:
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/GVLs/GVL_Primitives.TcGVL"
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md"
  e2e: []
  effort: S
  deps: []
  cross_driver: false
  notes: "Hardware-gated via TWINCAT_TARGET_NETID; no e2e change to test-twincat.ps1."
 - id: twincat-1.2
  driver: twincat
  phase: 1
  plan_pr_id: "1.2"
  title: "TwinCAT — TIME/DATE/DT/TOD as native UA types"
  plan_anchor: "docs/plans/twincat-plan.md"
  summary: |
    Stop marshalling IEC TIME/DATE/DT/TOD as raw UDINT and convert to native UA
    Duration/DateTime types via post-processing in ReadValueAsync, ConvertForWrite,
    and OnAdsNotificationEx. May expose missing Duration in DriverDataType. CLI
    syntax updates so users write ISO-8601 / IEC literals instead of numeric raw
    values.
  files:
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDataType.cs"
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs"
  docs:
    - "docs/Driver.TwinCAT.Cli.md"
  fixture:
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/GVLs/GVL_Primitives.TcGVL"
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md"
  e2e: []
  effort: M
  deps: []
  cross_driver: false
  notes: "Hardware-gated via TWINCAT_TARGET_NETID. May add Duration to DriverDataType enum."
 - id: twincat-1.3
  driver: twincat
  phase: 1
  plan_pr_id: "1.3"
  title: "TwinCAT — Bit-indexed BOOL writes (read-modify-write)"
  plan_anchor: "docs/plans/twincat-plan.md"
  summary: |
    Replace the NotSupportedException at AdsTwinCATClient.cs:99 with read-modify-write
    on the parent word, serializing concurrent bit writes to the same parent via a
    keyed SemaphoreSlim. Closes referenced task #181. CLI gains an example and the
    fixture caveat in the bugs-caught list updates to note writes now work.
  files:
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs"
  docs:
    - "docs/Driver.TwinCAT.Cli.md"
    - "docs/drivers/TwinCAT-Test-Fixture.md"
  fixture: []
  e2e: []
  effort: S
  deps: []
  cross_driver: false
  notes: "Reuses GVL_Primitives.vWord (0xBEEF) — no fixture schema change."
 - id: twincat-1.4
  driver: twincat
  phase: 1
  plan_pr_id: "1.4"
  title: "TwinCAT — Multi-dim and whole-array reads"
  plan_anchor: "docs/plans/twincat-plan.md"
  summary: |
    Expand ReadValueAsync/WriteValueAsync to handle whole-array reads in a single
    AdsClient call rather than element-by-element. Surface IsArray + ArrayDimensions
    on TwinCATTagDefinition and through DriverAttributeInfo from DiscoverAsync. Sets
    up the array-shape plumbing the rest of the driver needs.
  files:
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs"
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs"
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriverOptions.cs"
  docs:
    - "docs/Driver.TwinCAT.Cli.md"
    - "docs/drivers/TwinCAT-Test-Fixture.md"
  fixture:
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/GVLs/GVL_Arrays.TcGVL"
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md"
  e2e: []
  effort: M
  deps: []
  cross_driver: false
  notes: "Hardware-gated via TWINCAT_TARGET_NETID. New 5x5 aReal2D seed with deterministic pattern."
 - id: twincat-1.5
  driver: twincat
  phase: 1
  plan_pr_id: "1.5"
  title: "TwinCAT — ENUM and ALIAS at discovery"
  plan_anchor: "docs/plans/twincat-plan.md"
  summary: |
    MapSymbolTypeName currently returns null for non-atomic types, dropping ENUM and
    ALIAS symbols silently. Switch to inspecting symbol.DataType + Category from
    TwinCAT.TypeSystem so DataTypeCategory.Enum walks EnumValues and Alias resolves
    to base atomic recursively. Surface enum members for later EnumStrings rendering.
    POINTER/REFERENCE/INTERFACE/UNION explicitly out of scope.
  files:
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs"
  docs:
    - "docs/Driver.TwinCAT.Cli.md"
    - "docs/drivers/TwinCAT-Test-Fixture.md"
  fixture:
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md"
  e2e: []
  effort: M
  deps: []
  cross_driver: false
  notes: "Reuses existing GVL_Enums + DUTs; only README integration-test contract entry added."
 - id: twincat-2.1
  driver: twincat
  phase: 2
  plan_pr_id: "2.1"
  title: "TwinCAT — ADS Sum-read / Sum-write"
  plan_anchor: "docs/plans/twincat-plan.md"
  summary: |
    Replace per-tag ReadValueAsync loops with Beckhoff's ADS Sum commands
    (IndexGroup 0xF080-0xF084) via SumSymbolRead/SumSymbolWrite to batch N
    reads/writes per AMS request. Bucket fullReferences by DeviceHostAddress and
    expose a new ReadValuesAsync surface on ITwinCATClient. Targets ~10x throughput
    on multi-thousand-tag scans; perf-tier test gated behind TWINCAT_PERF=1.
  files:
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs"
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs"
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/ITwinCATClient.cs"
  docs:
    - "docs/v3/twincat-backlog.md"
    - "docs/drivers/TwinCAT-Test-Fixture.md"
  fixture:
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/GVLs/GVL_Perf.TcGVL"
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md"
  e2e: []
  effort: L
  deps: []
  cross_driver: false
  notes: "Perf test gated behind TWINCAT_PERF=1 plus TWINCAT_TARGET_NETID; new FB_PerfChurn POU."
 - id: twincat-2.2
  driver: twincat
  phase: 2
  plan_pr_id: "2.2"
  title: "TwinCAT — Handle-based access with caching"
  plan_anchor: "docs/plans/twincat-plan.md"
  summary: |
    Cache CreateVariableHandleAsync results so per-read overhead drops to
    read-by-handle (4-byte index vs N-byte symbol path). On
    DeviceSymbolVersionInvalid (0x710) evict and retry once. Clear cache on
    AdsClient reconnect until the symbol-version listener (PR 2.3) ships. Dispose
    path calls DeleteVariableHandleAsync for cached handles.
  files:
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs"
  docs:
    - "docs/Driver.TwinCAT.Cli.md"
    - "docs/drivers/TwinCAT-Test-Fixture.md"
  fixture: []
  e2e: []
  effort: M
  deps: []
  cross_driver: false
  notes: "Combines with PR 2.1 for sum-read-by-handle. Reuses GVL_Perf.aTags."
 - id: twincat-2.3
  driver: twincat
  phase: 2
  plan_pr_id: "2.3"
  title: "TwinCAT — Symbol-version invalidation listener"
  plan_anchor: "docs/plans/twincat-plan.md"
  summary: |
    Register an AddDeviceNotificationAsync on the symbol-version index group
    (AdsReservedIndexGroup.SymbolVersion 0xF008) so the handle cache from PR 2.2
    is wiped on online-change bumps. Initial integration test gated as
    requires-manual-online-change until automation lands. Resolves open question
    (c) confirming the v6 enum constant.
  files:
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs"
  docs:
    - "docs/drivers/TwinCAT-Test-Fixture.md"
  fixture:
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md"
  e2e: []
  effort: M
  deps: ["twincat-2.2"]
  cross_driver: false
  notes: "Hardware-gated via TWINCAT_TARGET_NETID; manual online-change drill documented in README."
 - id: twincat-3.1
  driver: twincat
  phase: 3
  plan_pr_id: "3.1"
  title: "TwinCAT — Per-tag MaxDelay tuning"
  plan_anchor: "docs/plans/twincat-plan.md"
  summary: |
    Surface NotificationSettings MaxDelay as a per-tag option (default 0 to
    preserve current behavior). Plumb int? MaxDelayMs through TwinCATTagDefinition,
    SubscribeAsync, and AddNotificationAsync. Coalesces high-frequency PLC signals
    so the OPC UA subscription queue stops flooding under bursty change rates.
  files:
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriverOptions.cs"
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs"
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs"
  docs:
    - "docs/Driver.TwinCAT.Cli.md"
    - "docs/drivers/TwinCAT-Test-Fixture.md"
  fixture:
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md"
  e2e: []
  effort: S
  deps: []
  cross_driver: false
  notes: "Reuses GVL_Fixture.nCounter as 100 Hz driver. Hardware-gated via TWINCAT_TARGET_NETID."
 - id: twincat-3.2
  driver: twincat
  phase: 3
  plan_pr_id: "3.2"
  title: "TwinCAT — Cycle-time / jitter / PLC-state diagnostics"
  plan_anchor: "docs/plans/twincat-plan.md"
  summary: |
    Augment the probe loop to read _AppInfo.OnlineChangeCnt/AppName and
    _TaskInfo[1].CycleTime/LastExecTime, surface as TwinCATDeviceDiagnostics on
    DeviceState, and emit through IDriverDiagnostics (cross-driver surface from
    Modbus task #154). Read system symbols directly without going through the user
    browse filter.
  files:
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs"
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATSystemSymbolFilter.cs"
  docs:
    - "docs/drivers/TwinCAT-Test-Fixture.md"
    - "docs/Driver.TwinCAT.Cli.md"
    - "docs/v3/twincat-backlog.md"
  fixture:
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md"
  e2e: []
  effort: M
  deps: []
  cross_driver: true
  notes: "Reuses IDriverDiagnostics from Modbus task #154. Hardware-gated via TWINCAT_TARGET_NETID."
 - id: twincat-4.1
  driver: twincat
  phase: 4
  plan_pr_id: "4.1"
  title: "TwinCAT — Nested UDT browse via online type walker"
  plan_anchor: "docs/plans/twincat-plan.md"
  summary: |
    Largest single piece of work. Recurse BrowseSymbolsAsync into IStructType.SubItems
    yielding one TwinCATDiscoveredSymbol per leaf with dotted instance paths. Expand
    arrays-of-structs up to a configurable bound (default 1024). Add a pure
    TwinCATTypeWalker helper. Folds recursed structure into Discovered/ folder tree.
    Online runtime path only — TMC offline parsing deferred per open question (a).
  files:
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs"
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs"
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATTypeWalker.cs"
  docs:
    - "docs/Driver.TwinCAT.Cli.md"
    - "docs/drivers/TwinCAT-Test-Fixture.md"
    - "docs/v3/twincat-backlog.md"
  fixture:
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/DUTs/ST_NestedFlags.TcDUT"
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/DUTs/ST_RecursiveCap.TcDUT"
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/DUTs/ST_AlarmRecord.TcDUT"
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md"
  e2e: []
  effort: L
  deps: ["twincat-1.5"]
  cross_driver: false
  notes: "Hardware-gated via TWINCAT_TARGET_NETID. PR 1.4 helpful but not blocking."
 - id: twincat-5.1
  driver: twincat
  phase: 5
  plan_pr_id: "5.1"
  title: "TwinCAT — IAlarmSource via TC3 EventLogger"
  plan_anchor: "docs/plans/twincat-plan.md"
  summary: |
    Implement IAlarmSource over TcEventLogger on AMS port 110 so PLC alarms
    surface as OPC UA AC events. Begins with a one-day spike (open question (b))
    documented in docs/v3/twincat-eventlogger-spike.md to determine if a managed
    wrapper exists or if we hit AMS port 110 directly via a secondary AdsClient
    + AddDeviceNotificationAsync on the alarm-list index group. Gated by new
    EnableAlarms option (default false).
  files:
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATAlarmSource.cs"
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs"
    - "src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriverOptions.cs"
  docs:
    - "docs/drivers/TwinCAT.md"
    - "docs/v3/twincat-eventlogger-spike.md"
    - "docs/Driver.TwinCAT.Cli.md"
    - "docs/drivers/TwinCAT-Test-Fixture.md"
  fixture:
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/POUs/FB_AlarmHarness.TcPOU"
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/GVLs/GVL_Alarms.TcGVL"
    - "tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md"
  e2e:
    - "scripts/e2e/test-twincat.ps1"
  effort: L
  deps: []
  cross_driver: false
  notes: "Hardware-gated via TWINCAT_TARGET_NETID. Spike-first; e2e Test-AlarmRoundTrip likely deferred to follow-up."
--- a/scripts/queue/README.md
+++ b/scripts/queue/README.md
@@ -0,0 +1,36 @@
 # Plan-execution queue
 Gitea-backed work queue that drives the per-driver implementation plans (`docs/plans/*-plan.md`) to completion in **Mode B** (autonomous: auto-merges into the `auto/driver-gaps` integration branch when build+tests pass).
 ## Pieces
 - `pr-manifest.yaml` — canonical list of every PR across all six plans.
 - `setup-labels.sh` — idempotently creates the queue labels in Gitea.
 - `file-issues.sh` — files one Gitea issue per manifest entry (idempotent — skips ids that already exist).
 - `next-pr.sh` — picks the next eligible queue issue (queued, blockers all done) as JSON.
 - `start-pr.sh ISSUE BRANCH` — flips queued → in-progress and creates the branch off `auto/driver-gaps`.
 - `open-pr.sh ISSUE BRANCH TITLE BODY_FILE` — opens a PR from BRANCH into `auto/driver-gaps`.
 - `merge-pr.sh PR` — merges a PR with branch-delete (Mode B).
 - `finish-pr.sh ISSUE success PR` / `finish-pr.sh ISSUE failed REASON_FILE` — closes / marks failed.
 ## Flow per loop iteration
 1. `next-pr.sh` → issue#, branch, canonical id.
 2. `start-pr.sh` → mark in-progress, create branch.
 3. Loop driver dispatches a Claude Agent to implement the PR on the branch.
 4. Loop runs `dotnet build` + `dotnet test`.
 5. On green: `open-pr.sh`, `merge-pr.sh`, `finish-pr.sh success`.
 6. On red: capture log → `finish-pr.sh failed log.txt`. Issue stays open with `queue/failed` label for retry.
 ## Environment
 - Gitea repo: `dohertj2/lmxopcua` on `gitea.dohertylan.com`.
 - Token: read from `%LOCALAPPDATA%\tea\config.yml` (or `$GITEA_TOKEN` override).
 - Integration branch: `auto/driver-gaps` (created off master).
 - Per-PR branches: `auto/<driver>/<plan-pr-id>`.
 ## Reset / debug
 - Re-list eligible issues: `bash scripts/queue/next-pr.sh`.
 - Manually unblock: remove `queue/blocked` label and add `queue/queued`.
 - Drop a failed PR back into queue: remove `queue/failed`, add `queue/queued`.
--- a/scripts/queue/file-issues.sh
+++ b/scripts/queue/file-issues.sh
@@ -0,0 +1,122 @@
 #!/usr/bin/env bash
 # Reads scripts/queue/pr-manifest.yaml and creates one Gitea issue per PR.
 # Idempotent: skips PRs whose canonical id already exists as an open issue.
 set -euo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "$HERE/lib.sh"
 if [ ! -f "$MANIFEST" ]; then
  echo "manifest not found: $MANIFEST" >&2
  exit 1
 fi
 # Collect existing canonical-id → issue# mapping (from queue-meta blocks)
 EXISTING_JSON=$(api_repo GET "issues?state=all&type=issues&limit=200&page=1")
 # multiple pages — keep paging until empty
 PAGE=2
 while :; do
  PG=$(api_repo GET "issues?state=all&type=issues&limit=200&page=$PAGE")
  COUNT=$(echo "$PG" | python -c "import sys,json; print(len(json.load(sys.stdin)))")
  if [ "$COUNT" = "0" ]; then break; fi
  EXISTING_JSON=$(python -c "import sys,json; a=json.loads(sys.argv[1]); b=json.loads(sys.argv[2]); print(json.dumps(a+b))" "$EXISTING_JSON" "$PG")
  PAGE=$((PAGE+1))
 done
 python - "$MANIFEST" "$LABEL_MAP" <<'PY'
 import json, sys, re, yaml, urllib.request, os
 manifest_path, label_map_path = sys.argv[1], sys.argv[2]
 gitea_token = os.environ["GITEA_TOKEN"]
 api_base = "https://gitea.dohertylan.com/api/v1/repos/dohertj2/lmxopcua"
 with open(manifest_path) as f: manifest = yaml.safe_load(f)
 with open(label_map_path) as f: lmap = json.load(f)
 def api(method, path, data=None):
    req = urllib.request.Request(
        f"{api_base}/{path}",
        method=method,
        headers={
            "Authorization": f"token {gitea_token}",
            "Content-Type": "application/json",
            "Accept": "application/json",
        },
        data=json.dumps(data).encode() if data else None,
    )
    with urllib.request.urlopen(req) as r:
        return json.loads(r.read().decode())
 # Collect existing issues' canonical ids → issue#
 existing = {}
 page = 1
 while True:
    items = api("GET", f"issues?state=all&type=issues&limit=50&page={page}")
    if not items: break
    for it in items:
        m = re.search(r'<!-- queue-meta\s*(\{.*?\})\s*-->', it.get("body","") or "", re.S)
        if m:
            try:
                meta = json.loads(m.group(1))
                if "id" in meta:
                    existing[meta["id"]] = it["number"]
            except: pass
    page += 1
 print(f"existing queue issues: {len(existing)}")
 filed = 0
 skipped = 0
 for pr in manifest["prs"]:
    if pr["id"] in existing:
        skipped += 1
        continue
    title = f"[{pr['driver']}] {pr['title']}"
    meta = {
        "id": pr["id"],
        "driver": pr["driver"],
        "phase": pr["phase"],
        "plan_pr_id": pr.get("plan_pr_id",""),
        "deps": pr.get("deps", []),
        "cross_driver": pr.get("cross_driver", False),
    }
    body_parts = [
        f"<!-- queue-meta\n{json.dumps(meta)}\n-->",
        "## Auto-managed PR — Mode B (autonomous)",
        f"**Driver**: `{pr['driver']}`  **Phase**: `{pr['phase']}`  **Plan PR**: `{pr.get('plan_pr_id','')}`",
        f"**Plan**: [`{pr.get('plan_anchor','docs/plans/' + pr['driver'] + '-plan.md')}`]({pr.get('plan_anchor','../docs/plans/' + pr['driver'] + '-plan.md')})",
        f"**Effort**: `{pr.get('effort','M')}`  **Cross-driver**: `{pr.get('cross_driver', False)}`",
        "",
        "## Summary",
        pr.get("summary","_(see plan)_"),
    ]
    if pr.get("files"):
        body_parts += ["", "## Source files", *[f"- `{f}`" for f in pr["files"]]]
    if pr.get("docs"):
        body_parts += ["", "## Docs", *[f"- `{d}`" for d in pr["docs"]]]
    if pr.get("fixture"):
        body_parts += ["", "## Fixture", *[f"- `{x}`" for x in pr["fixture"]]]
    if pr.get("e2e"):
        body_parts += ["", "## E2E", *[f"- `{x}`" for x in pr["e2e"]]]
    if pr.get("deps"):
        body_parts += ["", "## Depends on", *[f"- canonical: `{d}`" for d in pr["deps"]]]
    if pr.get("notes"):
        body_parts += ["", "## Notes", pr["notes"]]
    body_parts += ["",
                   "---",
                   f"_Branch: `auto/{pr['driver']}/{pr.get('plan_pr_id','').replace('/','-')}`. Target: `auto/driver-gaps`._"]
    body = "\n".join(body_parts)
    label_names = [
        f"driver/{pr['driver']}",
        f"phase/{pr['phase']}",
        "queue/queued",
        "auto-managed",
    ]
    if pr.get("cross_driver"): label_names.append("cross-driver")
    label_ids = [lmap[n] for n in label_names if n in lmap]
    issue = api("POST", "issues", {"title": title, "body": body, "labels": label_ids})
    print(f"  filed #{issue['number']}: {pr['id']}")
    filed += 1
 print(f"\nfiled {filed}, skipped (existing) {skipped}")
 PY
--- a/scripts/queue/finish-pr.sh
+++ b/scripts/queue/finish-pr.sh
@@ -0,0 +1,39 @@
 #!/usr/bin/env bash
 # Closes the issue (success) or marks failed and reopens for retry.
 # Usage:
 #   finish-pr.sh ISSUE_NUM success PR_NUM
 #   finish-pr.sh ISSUE_NUM failed  REASON_FILE
 set -euo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "$HERE/lib.sh"
 ISSUE="${1:?ISSUE_NUM required}"
 RESULT="${2:?success|failed required}"
 ARG3="${3:?PR_NUM or REASON_FILE required}"
 INPROG=$(python -c "import json; print(json.load(open('$LABEL_MAP'))['queue/in-progress'])")
 DONE=$(python  -c "import json; print(json.load(open('$LABEL_MAP'))['queue/done'])")
 FAILED=$(python -c "import json; print(json.load(open('$LABEL_MAP'))['queue/failed'])")
 api_repo DELETE "issues/$ISSUE/labels/$INPROG" >/dev/null || true
 case "$RESULT" in
  success)
    PR_NUM="$ARG3"
    api_repo POST "issues/$ISSUE/labels" "{\"labels\":[$DONE]}" >/dev/null
    BODY=$(python -c "import json; print(json.dumps({'body':'✅ Auto-loop completed. Merged via PR #$PR_NUM.'}))")
    api_repo POST "issues/$ISSUE/comments" "$BODY" >/dev/null
    api_repo PATCH "issues/$ISSUE" '{"state":"closed"}' >/dev/null
    echo "  issue #$ISSUE closed (PR #$PR_NUM merged)"
    ;;
  failed)
    REASON_FILE="$ARG3"
    REASON=$(cat "$REASON_FILE" 2>/dev/null | head -c 4000 || echo "(no reason file)")
    api_repo POST "issues/$ISSUE/labels" "{\"labels\":[$FAILED]}" >/dev/null
    BODY=$(python -c "import json,sys; r=open('$REASON_FILE').read()[:4000] if __import__('os').path.exists('$REASON_FILE') else '(no log)'; print(json.dumps({'body':'❌ Auto-loop failed.\n\n\`\`\`\n'+r+'\n\`\`\`'}))")
    api_repo POST "issues/$ISSUE/comments" "$BODY" >/dev/null
    echo "  issue #$ISSUE marked failed (still open for retry)"
    ;;
  *)
    echo "unknown result: $RESULT" >&2; exit 1 ;;
 esac
--- a/scripts/queue/lib.sh
+++ b/scripts/queue/lib.sh
@@ -0,0 +1,57 @@
 #!/usr/bin/env bash
 # Shared helpers for the Gitea-backed plan-execution queue.
 set -euo pipefail
 GITEA_URL="https://gitea.dohertylan.com"
 GITEA_REPO="dohertj2/lmxopcua"
 GITEA_API="$GITEA_URL/api/v1"
 if [ -z "${GITEA_TOKEN:-}" ]; then
  TEA_CONFIG="${LOCALAPPDATA:-$HOME/AppData/Local}/tea/config.yml"
  if [ ! -f "$TEA_CONFIG" ]; then
    TEA_CONFIG="$HOME/.config/tea/config.yml"
  fi
  GITEA_TOKEN="$(awk '/token:/{gsub(/[ \t]/,"",$2); print $2; exit}' "$TEA_CONFIG" 2>/dev/null || true)"
 fi
 if [ -z "${GITEA_TOKEN:-}" ]; then
  echo "lib.sh: GITEA_TOKEN not set and tea config not readable" >&2
  exit 1
 fi
 export GITEA_TOKEN
 INTEGRATION_BRANCH="auto/driver-gaps"
 QUEUE_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && { pwd -W 2>/dev/null || pwd; })"
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && { pwd -W 2>/dev/null || pwd; })"
 MANIFEST="$QUEUE_ROOT/pr-manifest.yaml"
 LABEL_MAP="$QUEUE_ROOT/.label-ids.json"
 LABEL_QUEUED="queue/queued"
 LABEL_IN_PROGRESS="queue/in-progress"
 LABEL_BLOCKED="queue/blocked"
 LABEL_FAILED="queue/failed"
 LABEL_DONE="queue/done"
 LABEL_AUTO="auto-managed"
 LABEL_CROSS="cross-driver"
 api() {
  local method="$1" path="$2" data="${3:-}"
  if [ -n "$data" ]; then
    curl -sf -X "$method" \
      -H "Authorization: token $GITEA_TOKEN" \
      -H "Content-Type: application/json" \
      -d "$data" \
      "$GITEA_API/$path"
  else
    curl -sf -X "$method" \
      -H "Authorization: token $GITEA_TOKEN" \
      "$GITEA_API/$path"
  fi
 }
 api_repo() {
  api "$1" "repos/$GITEA_REPO/$2" "${3:-}"
 }
 label_id() {
  python -c "import json,sys; m=json.load(open('$LABEL_MAP')); print(m['$1'])"
 }
--- a/scripts/queue/loop-iteration.md
+++ b/scripts/queue/loop-iteration.md
@@ -0,0 +1,57 @@
 # Loop iteration prompt (Mode B autonomous)
 This is the single self-contained prompt that `/loop` re-fires until the queue empties. Each iteration handles exactly one PR end-to-end.
 ---
 You are running one iteration of the autonomous plan-execution loop. The queue lives in Gitea at `dohertj2/lmxopcua`. Helpers: `scripts/queue/*.sh`.
 ## Step 1 — pick the next PR
 Run `bash scripts/queue/next-pr.sh`. It returns JSON.
 - If `{"empty": true}` → the queue is drained. **Do not call ScheduleWakeup.** Report "queue empty — loop terminating" and exit. The /loop will end.
 - Otherwise parse: `issue_num`, `canonical_id`, `driver`, `phase`, `plan_pr_id`, `branch`, `title`, `url`.
 ## Step 2 — claim it
 Run `bash scripts/queue/start-pr.sh "$ISSUE_NUM" "$BRANCH"`. This swaps `queue/queued` → `queue/in-progress` and creates the branch off `auto/driver-gaps`.
 ## Step 3 — pull the issue body
 Run `curl -sf -H "Authorization: token $(awk '/token:/{print $2}' "$LOCALAPPDATA/tea/config.yml")" "https://gitea.dohertylan.com/api/v1/repos/dohertj2/lmxopcua/issues/$ISSUE_NUM"` and extract the `body` field. The body contains the Plan link, summary, source files, docs/fixture/e2e files.
 ## Step 4 — implement on a worktree
 Dispatch a general-purpose Agent with `isolation: "worktree"`. Brief it with:
 - the issue body verbatim
 - the linked plan section (read `docs/plans/<driver>-plan.md` and quote the relevant per-PR detail)
 - explicit instructions: implement the source-file changes, the doc updates, the fixture extensions, and the e2e test additions named in the issue
 - run `dotnet build c:/Users/dohertj2/Desktop/lmxopcua/ZB.MOM.WW.OtOpcUa.slnx` until green
 - run `dotnet test` for the relevant test project until green
 - commit on `$BRANCH` with message `Auto: <canonical_id> — <short summary>` followed by `Closes #$ISSUE_NUM`
 - return a brief summary of what changed
 ## Step 5 — verify and push
 Verify the agent did commit + push. If branch isn't pushed, push it: `git push origin "$BRANCH"`.
 ## Step 6 — open PR
 Build a body file: include the issue summary + the agent's summary. Then:
 ```
 PR_NUM=$(bash scripts/queue/open-pr.sh "$ISSUE_NUM" "$BRANCH" "$TITLE" /tmp/pr-body.md)
 ```
 ## Step 7 — auto-merge (Mode B)
 Run `bash scripts/queue/merge-pr.sh "$PR_NUM"`.
 ## Step 8 — close issue
 Run `bash scripts/queue/finish-pr.sh "$ISSUE_NUM" success "$PR_NUM"`.
 ## On failure
 If anywhere from Step 4 onward fails (build red, tests red, agent gives up, push fails, merge conflict):
 - write the failure log to `/tmp/loop-fail-$ISSUE_NUM.log`
 - run `bash scripts/queue/finish-pr.sh "$ISSUE_NUM" failed /tmp/loop-fail-$ISSUE_NUM.log`
 - the issue keeps `queue/failed` and stays open for retry
 - **do not** retry the same issue this iteration; let the loop pick a different one next fire
 ## Re-arm
 At the very end of the iteration (success OR failure), call `ScheduleWakeup` with the same `/loop` prompt and `delaySeconds: 60` to fire the next iteration.
 If the queue was empty in Step 1, do NOT call ScheduleWakeup.
 Report a one-line summary to the user before re-arming.
--- a/scripts/queue/merge-pr.sh
+++ b/scripts/queue/merge-pr.sh
@@ -0,0 +1,11 @@
 #!/usr/bin/env bash
 # Merges a PR (Mode B autonomous merge into auto/driver-gaps).
 # Usage: merge-pr.sh PR_NUM
 set -euo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "$HERE/lib.sh"
 PR="${1:?PR_NUM required}"
 PAYLOAD='{"Do":"merge","delete_branch_after_merge":true}'
 api_repo POST "pulls/$PR/merge" "$PAYLOAD" >/dev/null
 echo "  PR #$PR merged into $INTEGRATION_BRANCH (branch deleted)"
--- a/scripts/queue/next-pr.sh
+++ b/scripts/queue/next-pr.sh
@@ -0,0 +1,77 @@
 #!/usr/bin/env bash
 # Prints the next eligible queue issue as JSON: {issue_num, canonical_id, driver, plan_pr_id, branch, ...}
 # Eligible = open + label queue/queued + all canonical deps closed.
 # Picks lowest phase first, then lowest issue number within phase.
 set -euo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "$HERE/lib.sh"
 python - <<PY
 import json, urllib.request, re, os, sys
 token = os.environ["GITEA_TOKEN"]
 api_base = "https://gitea.dohertylan.com/api/v1/repos/dohertj2/lmxopcua"
 def api(path):
    req = urllib.request.Request(f"{api_base}/{path}",
        headers={"Authorization": f"token {token}"})
    with urllib.request.urlopen(req) as r:
        return json.loads(r.read().decode())
 # Gather all queue issues
 issues = []
 page = 1
 while True:
    items = api(f"issues?state=all&type=issues&limit=50&page={page}&labels=auto-managed")
    if not items: break
    issues.extend(items)
    page += 1
 by_id = {}
 for it in issues:
    m = re.search(r'<!-- queue-meta\s*(\{.*?\})\s*-->', it.get("body","") or "", re.S)
    if not m: continue
    try: meta = json.loads(m.group(1))
    except: continue
    by_id[meta["id"]] = (it, meta)
 def is_done(issue):
    if issue["state"] == "closed": return True
    labels = {l["name"] for l in issue["labels"]}
    return "queue/done" in labels
 eligible = []
 for cid, (it, meta) in by_id.items():
    labels = {l["name"] for l in it["labels"]}
    if it["state"] != "open": continue
    if "queue/queued" not in labels: continue
    deps = meta.get("deps", [])
    blocked = False
    for d in deps:
        if d not in by_id:
            blocked = True; break
        if not is_done(by_id[d][0]):
            blocked = True; break
    if blocked: continue
    eligible.append((meta.get("phase",99), it["number"], cid, it, meta))
 if not eligible:
    print(json.dumps({"empty": True}))
    sys.exit(0)
 eligible.sort(key=lambda x: (x[0], x[1]))
 phase, num, cid, it, meta = eligible[0]
 plan_pr = meta.get("plan_pr_id","").replace("/","-")
 result = {
    "empty": False,
    "issue_num": num,
    "canonical_id": cid,
    "driver": meta["driver"],
    "phase": meta["phase"],
    "plan_pr_id": meta.get("plan_pr_id",""),
    "title": it["title"],
    "branch": f"auto/{meta['driver']}/{plan_pr}",
    "url": it["html_url"],
 }
 print(json.dumps(result, indent=2))
 PY
--- a/scripts/queue/open-pr.sh
+++ b/scripts/queue/open-pr.sh
@@ -0,0 +1,24 @@
 #!/usr/bin/env bash
 # Opens a PR from BRANCH into auto/driver-gaps, references the issue, sets ready/draft.
 # Usage: open-pr.sh ISSUE_NUM BRANCH_NAME TITLE BODY_FILE
 # Echoes the PR number on stdout.
 set -euo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "$HERE/lib.sh"
 ISSUE="${1:?}"; BRANCH="${2:?}"; TITLE="${3:?}"; BODY_FILE="${4:?}"
 BODY=$(cat "$BODY_FILE")
 PAYLOAD=$(python -c "
 import json, sys
 print(json.dumps({
    'title': sys.argv[1],
    'body':  sys.argv[2] + '\n\nCloses #' + sys.argv[3],
    'head':  sys.argv[4],
    'base':  sys.argv[5],
 }))
 " "$TITLE" "$BODY" "$ISSUE" "$BRANCH" "$INTEGRATION_BRANCH")
 PR=$(api_repo POST pulls "$PAYLOAD")
 PR_NUM=$(echo "$PR" | python -c "import sys,json; print(json.load(sys.stdin)['number'])")
 echo "$PR_NUM"
--- a/scripts/queue/pr-manifest.yaml
+++ b/scripts/queue/pr-manifest.yaml
--- a/scripts/queue/setup-labels.sh
+++ b/scripts/queue/setup-labels.sh
@@ -0,0 +1,58 @@
 #!/usr/bin/env bash
 # Idempotent: creates queue labels in Gitea and stores name→id map at .label-ids.json
 set -euo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "$HERE/lib.sh"
 declare -A LABELS=(
  ["driver/abcip"]="0e8a16"
  ["driver/ablegacy"]="0e8a16"
  ["driver/focas"]="0e8a16"
  ["driver/opcuaclient"]="0e8a16"
  ["driver/s7"]="0e8a16"
  ["driver/twincat"]="0e8a16"
  ["phase/1"]="bfd4f2"
  ["phase/2"]="bfd4f2"
  ["phase/3"]="bfd4f2"
  ["phase/4"]="bfd4f2"
  ["phase/5"]="bfd4f2"
  ["phase/6"]="bfd4f2"
  ["queue/queued"]="d4c5f9"
  ["queue/in-progress"]="fbca04"
  ["queue/blocked"]="b60205"
  ["queue/failed"]="b60205"
  ["queue/done"]="2ea44f"
  ["auto-managed"]="cccccc"
  ["cross-driver"]="d93f0b"
 )
 # Pull existing labels
 EXISTING=$(api_repo GET "labels?limit=200")
 emit_map() {
  python - <<PY
 import json, sys
 existing = json.loads('''$EXISTING''')
 print(json.dumps({l['name']: l['id'] for l in existing}, indent=2))
 PY
 }
 # Create any missing
 for name in "${!LABELS[@]}"; do
  color="${LABELS[$name]}"
  exists=$(echo "$EXISTING" | python -c "import json,sys; ls=json.load(sys.stdin); print('yes' if any(l['name']=='$name' for l in ls) else 'no')")
  if [ "$exists" = "no" ]; then
    payload=$(python -c "import json; print(json.dumps({'name':'$name','color':'#$color','description':'queue management'}))")
    api_repo POST labels "$payload" >/dev/null
    echo "created label: $name"
  fi
 done
 # Refresh and write the map file
 api_repo GET "labels?limit=200" | python -c "
 import json, sys
 ls = json.load(sys.stdin)
 m = {l['name']: l['id'] for l in ls}
 open('$LABEL_MAP','w').write(json.dumps(m, indent=2))
 print(f'wrote {len(m)} labels to $LABEL_MAP')
 "
--- a/scripts/queue/start-pr.sh
+++ b/scripts/queue/start-pr.sh
@@ -0,0 +1,31 @@
 #!/usr/bin/env bash
 # Marks an issue in-progress and creates its branch off the integration branch.
 # Usage: start-pr.sh ISSUE_NUM BRANCH_NAME
 set -euo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "$HERE/lib.sh"
 ISSUE="${1:?ISSUE_NUM required}"
 BRANCH="${2:?BRANCH_NAME required}"
 # Swap labels: queued -> in-progress
 QUEUED=$(python -c "import json; print(json.load(open('$LABEL_MAP'))['queue/queued'])")
 INPROG=$(python -c "import json; print(json.load(open('$LABEL_MAP'))['queue/in-progress'])")
 api_repo DELETE "issues/$ISSUE/labels/$QUEUED" >/dev/null || true
 api_repo POST   "issues/$ISSUE/labels"          "{\"labels\":[$INPROG]}" >/dev/null
 # Create branch off integration
 EXISTS=$(api_repo GET "branches/$BRANCH" 2>/dev/null || echo "")
 if [ -z "$EXISTS" ]; then
  PAYLOAD=$(python -c "import json; print(json.dumps({'new_branch_name':'$BRANCH','old_branch_name':'$INTEGRATION_BRANCH'}))")
  api_repo POST branches "$PAYLOAD" >/dev/null
  echo "  branch created: $BRANCH"
 else
  echo "  branch exists: $BRANCH"
 fi
 # Comment
 COMMENT=$(python -c "import json; print(json.dumps({'body':'🤖 Auto-loop picked this up. Branch: \`$BRANCH\`. Status: in-progress.'}))")
 api_repo POST "issues/$ISSUE/comments" "$COMMENT" >/dev/null
 echo "  issue #$ISSUE marked in-progress"
--- a/src/ZB.MOM.WW.OtOpcUa.Admin/appsettings.json
+++ b/src/ZB.MOM.WW.OtOpcUa.Admin/appsettings.json
@@ -1,6 +1,6 @@
 {
  "ConnectionStrings": {
-    "ConfigDb": "Server=localhost,14330;Database=OtOpcUaConfig;User Id=sa;Password=OtOpcUaDev_2026!;TrustServerCertificate=True;Encrypt=False;"
+    "ConfigDb": "Server=10.100.0.35,14330;Database=OtOpcUaConfig;User Id=sa;Password=OtOpcUaDev_2026!;TrustServerCertificate=True;Encrypt=False;"
  },
  "Authentication": {
    "Ldap": {
--- a/tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbServerFixture.cs
+++ b/tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbServerFixture.cs
@@ -8,7 +8,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests;
 ///     Reachability probe for the <c>ab_server</c> Docker container (libplctag's CIP
 ///     simulator built via <c>Docker/Dockerfile</c>) or any real AB PLC the
 ///     <c>AB_SERVER_ENDPOINT</c> env var points at. Parses
-///     <c>AB_SERVER_ENDPOINT</c> (default <c>localhost:44818</c>) + TCP-connects
+///     <c>AB_SERVER_ENDPOINT</c> (default <c>10.100.0.35:44818</c>) + TCP-connects
 ///     once at fixture construction. Tests skip via <see cref="AbServerFactAttribute"/>
 ///     / <see cref="AbServerTheoryAttribute"/> when the port isn't live, so
 ///     <c>dotnet test</c> stays green on a fresh clone without Docker running.
@@ -28,7 +28,7 @@ public sealed class AbServerFixture : IAsyncLifetime
    /// instantiate the fixture with the profile matching their compose-file service.</summary>
    public AbServerProfile Profile { get; }
-    public string Host { get; } = "127.0.0.1";
+    public string Host { get; } = "10.100.0.35";
    public int Port { get; } = AbServerProfile.DefaultPort;
    public AbServerFixture() : this(KnownProfiles.ControlLogix) { }
@@ -59,7 +59,7 @@ public sealed class AbServerFixture : IAsyncLifetime
        TcpProbe(ResolveHost(), ResolvePort());
    private static string ResolveHost() =>
-        Environment.GetEnvironmentVariable(EndpointEnvVar)?.Split(':', 2)[0] ?? "127.0.0.1";
+        Environment.GetEnvironmentVariable(EndpointEnvVar)?.Split(':', 2)[0] ?? "10.100.0.35";
    private static int ResolvePort()
    {
@@ -84,7 +84,7 @@ public sealed class AbServerFixture : IAsyncLifetime
 /// <summary>
 ///     <c>[Fact]</c>-equivalent that skips when ab_server isn't reachable — accepts a
-///     live Docker listener on <c>localhost:44818</c> or an <c>AB_SERVER_ENDPOINT</c>
+///     live Docker listener on <c>10.100.0.35:44818</c> or an <c>AB_SERVER_ENDPOINT</c>
 ///     override pointing at a real PLC.
 /// </summary>
 public sealed class AbServerFactAttribute : FactAttribute
--- a/tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Docker/docker-compose.yml
+++ b/tests/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Docker/docker-compose.yml
@@ -17,6 +17,8 @@ services:
      dockerfile: Dockerfile
    image: otopcua-ab-server:libplctag-release
    container_name: otopcua-ab-server-controllogix
    labels:
      project: lmxopcua
    restart: "no"
    ports:
      - "44818:44818"
@@ -40,6 +42,8 @@ services:
      context: .
      dockerfile: Dockerfile
    container_name: otopcua-ab-server-compactlogix
    labels:
      project: lmxopcua
    restart: "no"
    ports:
      - "44818:44818"
@@ -63,6 +67,8 @@ services:
      context: .
      dockerfile: Dockerfile
    container_name: otopcua-ab-server-micro800
    labels:
      project: lmxopcua
    restart: "no"
    ports:
      - "44818:44818"
@@ -82,6 +88,8 @@ services:
      context: .
      dockerfile: Dockerfile
    container_name: otopcua-ab-server-guardlogix
    labels:
      project: lmxopcua
    restart: "no"
    ports:
      - "44818:44818"
--- a/tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/Docker/docker-compose.yml
+++ b/tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/Docker/docker-compose.yml
@@ -17,6 +17,8 @@ services:
      dockerfile: Dockerfile
    image: otopcua-pymodbus:3.13.0
    container_name: otopcua-pymodbus-standard
    labels:
      project: lmxopcua
    restart: "no"
    ports:
      - "5020:5020"
@@ -34,6 +36,8 @@ services:
      context: .
      dockerfile: Dockerfile
    container_name: otopcua-pymodbus-dl205
    labels:
      project: lmxopcua
    restart: "no"
    ports:
      - "5020:5020"
@@ -51,6 +55,8 @@ services:
      context: .
      dockerfile: Dockerfile
    container_name: otopcua-pymodbus-mitsubishi
    labels:
      project: lmxopcua
    restart: "no"
    ports:
      - "5020:5020"
@@ -68,6 +74,8 @@ services:
      context: .
      dockerfile: Dockerfile
    container_name: otopcua-pymodbus-s7_1500
    labels:
      project: lmxopcua
    restart: "no"
    ports:
      - "5020:5020"
@@ -91,6 +99,8 @@ services:
      context: .
      dockerfile: Dockerfile
    container_name: otopcua-modbus-exception-injector
    labels:
      project: lmxopcua
    restart: "no"
    ports:
      - "5020:5020"
--- a/tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/ModbusSimulatorFixture.cs
+++ b/tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/ModbusSimulatorFixture.cs
@@ -5,7 +5,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests;
 /// <summary>
 ///     Reachability probe for a Modbus TCP simulator (pymodbus in Docker, see
 ///     <c>Docker/docker-compose.yml</c>) or a real PLC. Parses
-///     <c>MODBUS_SIM_ENDPOINT</c> (default <c>localhost:5020</c> per PR 43) and TCP-connects once at
+///     <c>MODBUS_SIM_ENDPOINT</c> (default <c>10.100.0.35:5020</c>) and TCP-connects once at
 ///     fixture construction. Each test checks <see cref="SkipReason"/> and calls
 ///     <c>Assert.Skip</c> when the endpoint was unreachable, so a dev box without a running
 ///     simulator still passes `dotnet test` cleanly — matches the Galaxy live-smoke pattern in
@@ -30,7 +30,7 @@ public sealed class ModbusSimulatorFixture : IAsyncDisposable
    // Picking 5020 sidesteps the privileged-port admin requirement on Windows + matches the
    // port baked into the pymodbus simulator JSON profiles in Docker/profiles/. Override with
    // MODBUS_SIM_ENDPOINT to point at a real PLC on its native port 502.
-    private const string DefaultEndpoint = "localhost:5020";
+    private const string DefaultEndpoint = "10.100.0.35:5020";
    private const string EndpointEnvVar = "MODBUS_SIM_ENDPOINT";
    public string Host { get; }
--- a/tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/Docker/docker-compose.yml
+++ b/tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/Docker/docker-compose.yml
@@ -8,6 +8,8 @@ services:
  opc-plc:
    image: mcr.microsoft.com/iotedge/opc-plc:2.14.10
    container_name: otopcua-opc-plc
    labels:
      project: lmxopcua
    restart: "no"
    ports:
      - "50000:50000"
--- a/tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/OpcPlcFixture.cs
+++ b/tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/OpcPlcFixture.cs
@@ -6,7 +6,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests;
 ///     Reachability probe for an <c>opc-plc</c> simulator (Microsoft Industrial IoT's
 ///     OPC UA PLC from <c>mcr.microsoft.com/iotedge/opc-plc</c>) or any real OPC UA
 ///     server the <c>OPCUA_SIM_ENDPOINT</c> env var points at. Parses
-///     <c>OPCUA_SIM_ENDPOINT</c> (default <c>opc.tcp://localhost:50000</c>),
+///     <c>OPCUA_SIM_ENDPOINT</c> (default <c>opc.tcp://10.100.0.35:50000</c>),
 ///     TCP-connects to the resolved host:port at collection init, and records a
 ///     <see cref="SkipReason"/> on failure. Tests call <c>Assert.Skip</c> on that, so
 ///     `dotnet test` stays green when Docker isn't running the simulator — mirrors the
@@ -32,7 +32,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests;
 /// </remarks>
 public sealed class OpcPlcFixture : IAsyncDisposable
 {
-    private const string DefaultEndpoint = "opc.tcp://localhost:50000";
+    private const string DefaultEndpoint = "opc.tcp://10.100.0.35:50000";
    private const string EndpointEnvVar = "OPCUA_SIM_ENDPOINT";
    /// <summary>Full <c>opc.tcp://host:port</c> URL the driver session should connect to.</summary>
--- a/tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/docker-compose.yml
+++ b/tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/docker-compose.yml
@@ -14,6 +14,8 @@ services:
      dockerfile: Dockerfile
    image: otopcua-python-snap7:1.0
    container_name: otopcua-python-snap7-s7_1500
    labels:
      project: lmxopcua
    restart: "no"
    ports:
      - "1102:1102"
--- a/tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Snap7ServerFixture.cs
+++ b/tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Snap7ServerFixture.cs
@@ -5,7 +5,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests;
 /// <summary>
 ///     Reachability probe for the python-snap7 simulator Docker container (see
 ///     <c>Docker/docker-compose.yml</c>) or a real S7 PLC. Parses <c>S7_SIM_ENDPOINT</c>
-///     (default <c>localhost:1102</c>) + TCP-connects once at fixture construction.
+///     (default <c>10.100.0.35:1102</c>) + TCP-connects once at fixture construction.
 ///     Tests check <see cref="SkipReason"/> + call <c>Assert.Skip</c> when unreachable, so
 ///     `dotnet test` stays green on a fresh box without the simulator installed —
 ///     mirrors the <c>ModbusSimulatorFixture</c> pattern.
@@ -35,7 +35,7 @@ public sealed class Snap7ServerFixture : IAsyncDisposable
 {
    // Default 1102 (non-privileged) matches Docker/server.py. Override with
    // S7_SIM_ENDPOINT to point at a real PLC on its native 102.
-    private const string DefaultEndpoint = "localhost:1102";
+    private const string DefaultEndpoint = "10.100.0.35:1102";
    private const string EndpointEnvVar = "S7_SIM_ENDPOINT";
    public string Host { get; }