lmxopcua/archreview/05-protocol-drivers.md

# Architecture Review 05 — Protocol Drivers

**Date:** 2026-07-08
**Commit:** `9cad9ed0`
**Scope:** the seven cross-platform protocol drivers and their satellites —
`Driver.Modbus` (+ `.Addressing`, `.Contracts`), `Driver.S7` (+ `.Contracts`),
`Driver.AbCip` (+ `.Contracts`), `Driver.AbLegacy` (+ `.Contracts`),
`Driver.TwinCAT` (+ `.Contracts`), `Driver.FOCAS` (+ `.Contracts`),
`Driver.OpcUaClient` (+ `.Contracts`, `.Browser`), and `src/Drivers/Cli/*`
(six per-driver CLI harnesses + `Cli.Common`). Test projects under
`tests/Drivers/` and `tests/Drivers/Cli/` were assessed for coverage only.
Galaxy and the Historian drivers are out of scope.

**Method:** Modbus was read exhaustively as the reference driver (it is the
documented origin of the shared `PollGroupEngine` and the richest read
planner); each other driver's main client/poller/factory/probe/contracts
files were then read in full and diffed structurally against the Modbus
shape. Cross-cutting greps covered TODO/HACK/NotImplemented, JSON
serializer options, `PollGroupEngine` construction, and interface
declarations. File references are repo-relative; drivers are abbreviated to
their suffix (e.g. `Driver.S7/S7Driver.cs`).

---

## Architecture Overview

### The common driver shape

Every protocol driver is expected to follow the same template:

1. **Factory extension** (`<X>DriverFactoryExtensions.Register`) registers a
   `DriverTypeName → CreateInstance(id, configJson)` closure with the
   `DriverFactoryRegistry` (wired centrally in
   `src/Server/ZB.MOM.WW.OtOpcUa.Host/Drivers/DriverFactoryBootstrap.cs`).
   Config parses through a string-typed DTO with fail-loud `ParseEnum`
   helpers and `PropertyNameCaseInsensitive` + comment/trailing-comma
   tolerance.
2. **Driver class** implements `IDriver, ITagDiscovery, IReadable,
   IWritable, ISubscribable, IHostConnectivityProbe, IPerCallHostResolver,
   IDisposable, IAsyncDisposable` (Modbus,
   `Driver.Modbus/ModbusDriver.cs:21-22`), with optional capability
   interfaces (`IAlarmSource`, `IRediscoverable`, `IHistoryProvider`) per
   protocol.
3. **Reference resolution** goes through the shared
   `EquipmentTagRefResolver<TDef>`
   (`src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/EquipmentTagRefResolver.cs`),
   bridging authored tag-table names and raw equipment-tag `TagConfig` JSON
   blobs (parsed once by a per-driver `<X>EquipmentTagParser` in the
   Contracts project, cached, cleared on teardown).
4. **Subscriptions** overlay a polling loop via the shared `PollGroupEngine`
   (`Core.Abstractions/PollGroupEngine.cs`) for protocols without a push
   model; the driver supplies the batch reader + on-change bridge.
5. **Health** is an immutable `DriverHealth` snapshot published via
   `Volatile.Read/Write`; failures set `Degraded` while retaining
   `LastSuccessfulRead`; `Faulted` is reserved for permanent config faults.
6. **Writes** return per-item `WriteResult` with protocol-error → OPC UA
   StatusCode mapping (a per-driver `<X>StatusMapper` or switch). Accurate
   per-item statuses are load-bearing: the server's write-outcome
   self-correction (`OtOpcUaNodeManager` reverting the node value on a
   failed device write) only works if the driver reports the failure.
7. **Probe loop** — a background task issuing a cheap protocol-level
   handshake, raising `OnHostStatusChanged` on Running↔Stopped transitions
   under a probe lock; plus a stateless `<X>DriverProbe : IDriverProbe`
   backing the AdminUI Test Connect button.
8. **Teardown** — one shared `TeardownAsync` used by both `ShutdownAsync`
   and `DisposeAsync`: cancel loops, await them, dispose CTSs, clear
   caches, dispose the transport.

Modbus adds the most advanced read planner in the fleet: block-read
coalescing (`MaxReadGap`), auto-prohibition of failing ranges with
bisection re-probing (`ModbusDriver.cs:687-795, 553-677`), chunking over
per-device caps, per-register bit-RMW locks, deadband publish filtering,
and `WriteOnChangeOnly` suppression with read-side invalidation.

### Per-driver conformance matrix

| Aspect | Modbus (ref) | S7 | AbCip | AbLegacy | TwinCAT | FOCAS | OpcUaClient |
|---|---|---|---|---|---|---|---|
| LOC (driver proj) | 2,374 | 1,979 | 3,762 | 1,830 | 2,261 | 5,007 | 2,347 |
| `IPerCallHostResolver` | yes | **no** | yes | yes | yes | yes | no (single endpoint, defensible) |
| Extra capabilities | — | — | `IAlarmSource` | — | `IRediscoverable` | `IAlarmSource` | `IAlarmSource`, `IHistoryProvider` |
| Subscription model | PollGroupEngine | **bespoke forked loop** | PollGroupEngine | PollGroupEngine | native ADS push (default) + PollGroupEngine fallback | PollGroupEngine | **real OPC UA MonitoredItems** |
| `onError` sink passed to engine | no | n/a | no | no | no | no | n/a |
| Reconnect story | transport auto-reconnect + geometric backoff | **none** | evict + recreate handle, no backoff | **no eviction on data path** | lazy per-call reconnect, **native subs orphaned** | lazy reconnect per tick, no backoff | `SessionReconnectHandler` + re-arm (best) |
| Read batching | block coalescing + bisection | per-tag | per-tag; UDT planner **half-built** | per-tag | per-tag (no ADS sum-read) | per-address, single-flight socket | batched `ReadValueIdCollection` |
| Deadband / WriteOnChangeOnly | yes / yes | no / no | no / no | no / no | no / no | no / no | n/a (passthrough) |
| Bit-level writes | RMW + per-register lock | native S7 bit write | RMW + per-parent lock (DINT-only assumption) | RMW + per-parent lock, width-aware | RMW + per-parent lock (**4-byte width assumption unverified**) | n/a (read-only backend) | n/a |
| Health via `Volatile`/`volatile` | yes | **plain field** | **plain field** | `volatile` | **plain field** | yes | **plain field** |
| `InitializeAsync` honours configJson | **no** | yes | yes | **no** | yes (empty-config quirk) | yes | yes |
| Factory `Register` takes `ILoggerFactory` | yes | **no** | **no** | yes | **no** | **no** | yes |
| Options `Validate()` | no (none in fleet) | no | no | no | no | no | no |
| Live browse / discovery | declared tags only | declared tags only | declared + opt-in controller browse + UDT fan-out | declared only (correct for PCCC) | declared + opt-in symbol browse + expander | declared + capability-gated fixed tree | full recursive remote browse |
| CLI harness | yes | yes | yes | yes | yes (+`browse`) | yes | **none** |

---

## Findings

Severity scale: **Critical** = live data-loss/unavailability in a realistic
field scenario; **High** = correctness or stability defect likely to bite;
**Medium** = architectural debt / divergence with concrete failure modes;
**Low** = hygiene.

### 1. Stability

**STAB-1 — Critical — S7 has no reconnect path at all.**
`Plc.OpenAsync` is called exactly once, in `InitializeAsync`
(`Driver.S7/S7Driver.cs:165-167`). Read/write failures set `Degraded` and
keep using the dead `Plc` (`S7Driver.cs:479-483, 995-1001`); the probe loop
detects the outage, transitions `Stopped` (`S7Driver.cs:1351-1383`) — and
keeps probing the same dead connection forever. A transient PLC reboot or
network blip permanently kills the driver instance until an external
redeploy/restart. Every sibling driver has *some* recovery path (Modbus:
transport-level reconnect+backoff; TwinCAT/FOCAS: lazy recreate; AbCip:
handle eviction). *Recommendation:* on socket-level `PlcException`, dispose
and lazily reopen the `Plc` under `_gate` (mirror TwinCAT's
`EnsureConnectedAsync`), or let the probe loop own recycle-on-Stopped.
Note the test suite has **zero reconnect tests for S7** (see TEST-1), which
is how this shipped.

**STAB-2 — Critical — TwinCAT native subscriptions are silently orphaned
after reconnect.** Native ADS notifications are the *default* mode
(`Driver.TwinCAT.Contracts/TwinCATDriverOptions.cs:31`). When
`EnsureConnectedAsync` discards a stale client
(`Driver.TwinCAT/TwinCATDriver.cs:615-619`), `AdsTwinCATClient.Dispose`
clears its notification table (`AdsTwinCATClient.cs:422-436`) and nothing
re-runs `AddNotificationAsync` on the replacement client — all subscribed
data flow stops with no Bad status and no error. Compounding: the fast path
keys on `IsConnected` (`TwinCATDriver.cs:606`), which reflects the local
AMS port, not wire liveness, so the replacement path may never even
trigger; and a probe failure never recycles the client
(`TwinCATDriver.cs:542-544`). *Recommendation:* record registration intent
(symbol, interval, handler) per subscription and replay it whenever the
per-device client instance changes; make probe-detected outage force a
client recycle.

**STAB-3 — High — Modbus transport desynchronizes after a response
timeout.** `SendAsync` reconnect-retries only on `IsSocketLevelFailure`
(`Driver.Modbus/ModbusTcpTransport.cs:155-165, 257-261`). A per-op timeout
surfaces as `OperationCanceledException` — not socket-level — so the socket
is kept with a half-read (or still-in-flight) response. The next
transaction then reads the stale response, hits the TxId mismatch check
(`ModbusTcpTransport.cs:233-235`), and throws `InvalidDataException` —
which is *also* not socket-level, so the stream is still not torn down.
The single-flight connection stays permanently desynchronized until a real
socket error or the (optional, default-off) idle-disconnect fires.
*Recommendation:* treat per-op timeout and any framing violation
(TxId mismatch, truncated header) as connection-fatal: tear down the socket
before propagating.

**STAB-4 — High — AbCip runs concurrent operations on shared libplctag
handles with no serialization.** `ReadSingleAsync` / `ReadGroupAsync` /
`WriteAsync` execute Read→GetStatus→Decode and Encode→Write→GetStatus on
cached `IAbCipTagRuntime` instances with zero locking
(`Driver.AbCip/AbCipDriver.cs:544-575, 614-637, 708-726`) while the server
read path, every poll-group loop, and the alarm-projection loop
(`AbCipAlarmProjection.cs:228`) can hit the same handle concurrently.
AbLegacy documents this exact hazard and guards it with a per-runtime
operation lock (“A libplctag Tag handle is not safe for concurrent
Read/GetStatus/DecodeValue”, `Driver.AbLegacy/AbLegacyDriver.cs:775-787`);
the fix never propagated to AbCip. Consequences: torn/wrong values decoded
with Good status, cross-attributed `GetStatus` results.
*Recommendation:* port AbLegacy's `GetRuntimeLock` pattern to AbCip.

**STAB-5 — High — FOCAS fixed-tree caches are plain `Dictionary`s mutated
across threads.** `LastFixedSnapshots` / `LastServoLoads` /
`LastSpindleLoads` / `LastTimers` (`Driver.FOCAS/FocasDriver.cs:1184-1194`)
are written by `FixedTreeLoopAsync` (`FocasDriver.cs:752, 793, 836-839`)
while `TryReadFixedTree` reads them on `ReadAsync` callers' threads
(`FocasDriver.cs:912, 920, 945`). Concurrent write-during-read on
`Dictionary<K,V>` is undefined behaviour (corruption or throw on resize).
The neighbouring `_parsedAddressesByTagName` already got the
`ConcurrentDictionary` treatment (`FocasDriver.cs:40`); these did not.
*Recommendation:* convert to `ConcurrentDictionary` or swap immutable
snapshots.

**STAB-6 — High — AbLegacy probe-loop shutdown race; S7 unsubscribe
race.** AbLegacy discards the probe task at spawn (`_ = Task.Run(...)`,
`Driver.AbLegacy/AbLegacyDriver.cs:118`) and `ShutdownAsync` cancels then
immediately disposes the CTS and runtimes without awaiting loop exit
(`AbLegacyDriver.cs:156-170`) — a winding-down loop can raise
`OnHostStatusChanged` after shutdown and touch a disposed CTS. AbCip fixed
this identical bug (retained `ProbeTask` + phased shutdown,
`Driver.AbCip/AbCipDriver.cs:295-298, 332-365`); the fix never propagated
back. S7 has the mirror-image bug in `UnsubscribeAsync`: cancel + dispose
the CTS without draining `PollTask` (`Driver.S7/S7Driver.cs:1185-1193`),
so `Task.Delay` on the disposed source can throw `ObjectDisposedException`
that the loop only catches as OCE (`S7Driver.cs:1233-1234`) —
`PollGroupEngine.StopState` exists precisely to prevent this
(`PollGroupEngine.cs:99-112, 136`). *Recommendation:* await the loop task
(bounded) before disposing the CTS in both places.

**STAB-7 — High — `InitializeAsync` ignores `driverConfigJson` in Modbus
and AbLegacy.** AbLegacy's `_options` is readonly ctor state and
`Initialize/Reinitialize` never parse the parameter
(`Driver.AbLegacy/AbLegacyDriver.cs:16, 78-153`); Modbus likewise uses only
ctor options (`Driver.Modbus/ModbusDriver.cs:167-197`). S7, AbCip and
TwinCAT deliberately re-parse (`Driver.AbCip/AbCipDriver.cs:229-236`
documents “rather than being silently discarded”). Any config change
delivered through `ReinitializeAsync` on a live instance is silently
discarded for these two drivers. TwinCAT has a related quirk: a parsed
config with zero devices AND zero tags is silently discarded in favour of
ctor options (`Driver.TwinCAT/TwinCATDriver.cs:89-94`), so an intentional
“empty the driver” redeploy is ignored. *Recommendation:* make config
re-parse on initialize a template requirement; add a consuming test per
driver.

**STAB-8 — Medium — No reconnect backoff anywhere except the Modbus
transport and S7's poll loop.** A dead device pays: AbCip — a full `Tag`
create + Forward Open per tag per poll tick (evict-recreate,
`AbCipDriver.cs:891-897`); FOCAS — a full two-socket reconnect attempt per
tick of *each* of three loops (`Driver.FOCAS/FocasDriver.cs:1089-1120`);
TwinCAT — a connect attempt per call (`TwinCATDriver.cs:602-651`).
`PollGroupEngine` itself polls at a fixed cadence regardless of failures —
S7's bespoke loop is the only subscriber-side backoff in the fleet
(`S7Driver.cs:1284-1293`, capped 30 s). *Recommendation:* add optional
failure backoff to `PollGroupEngine` (adopt S7's `ComputeBackoffDelay`)
and a small connect-attempt throttle to the lazy-reconnect drivers.

**STAB-9 — Medium — `PollGroupEngine`'s `onError` sink is dead code: no
driver passes it.** All five consumers construct the engine without the
error callback (`ModbusDriver.cs:115`, `AbCipDriver.cs:133`,
`AbLegacyDriver.cs:65`, `TwinCATDriver.cs:69`, `FocasDriver.cs:72`), so a
reader exception in a poll tick (e.g. `RequireTransport` after teardown,
reader contract violation) is silently swallowed — the precise
“silently-broken subscription” failure mode the engine's own doc comment
warns about (`PollGroupEngine.cs:21-25, 164-169`). *Recommendation:* pass
`onError` routing to the driver's health surface + logger in all five;
consider making the parameter required.

**STAB-10 — Medium — AbLegacy never evicts failed tag handles on the data
path.** Non-zero status and transport exceptions leave the cached runtime
in place (`AbLegacyDriver.cs:246-259, 269-274`) with no recreate-on-failure
(contrast `AbCipDriver.cs:891-897` and AbLegacy's own probe loop at
`AbLegacyDriver.cs:456-461`). A handle invalidated by a PLC state change
pins the tag Bad until full driver reinit.

**STAB-11 — Medium — RMW locks don't cover direct parent writes (AbCip,
AbLegacy, TwinCAT).** The per-parent semaphore serializes bit-RMW callers
against each other, but a direct write to the parent word/DINT itself goes
through the normal write path without taking the same lock
(`AbCipDriver.cs:708-710` vs `787-818`; same shape in AbLegacy and
TwinCAT), so it can interleave with an in-flight read-modify-write → lost
update. Additionally AbCip's RMW hard-codes DINT while `AbCipTagPath`
accepts `.N` on any parent (`Driver.AbCip/AbCipTagPath.cs:17-19`), and
TwinCAT's RMW always accesses the parent as 4-byte `UDInt` — explicitly
flagged as an unverified assumption that will likely fail
`DeviceInvalidSize` on WORD/BYTE parents on real hardware
(`Driver.TwinCAT/AdsTwinCATClient.cs:96-107`).

**STAB-12 — Medium — Blocking/uncancellable teardown paths.** FOCAS's sync
`Dispose()` performs a close-PDU exchange (`SendPdu` + `ReadPdu`) on a
`NetworkStream` with no ReadTimeout and no token
(`Driver.FOCAS/Wire/FocasWireClient.cs:164-175`) — a stalled CNC can wedge
`ShutdownAsync` indefinitely. TwinCAT's `ConnectAsync` calls the blocking
SDK `Connect` and ignores both its token and timeout parameter for the
connect itself (`AdsTwinCATClient.cs:73-80`).

**STAB-13 — Positive.** Write-outcome surfacing — the seam the server's
value-revert self-correction depends on — is honoured by every protocol
driver: per-item `WriteResult` with typed exception→status mapping (Modbus
`ModbusDriver.cs:897-942`; S7 `S7Driver.cs:921-1006` including the
PUT/GET-denied → `Faulted` escalation; AbCip `AbCipDriver.cs:732-775`;
AbLegacy `AbLegacyDriver.cs:348-366`; TwinCAT `TwinCATDriver.cs:332-349`
with a numerically-verified ADS error table; OpcUaClient passes upstream
codes verbatim and distinguishes post-dispatch cancellation as
`BadTimeout` "outcome unknown" — `OpcUaClientDriver.cs:753-779`, the most
careful non-idempotency handling in the fleet). Nothing is
fire-and-forget except the AbCip alarm *acknowledge* path (UNDER-5).
OpcUaClient's reconnect state machine (double-arm guard, re-arm on
exhaustion, session swap under `_probeLock` —
`OpcUaClientDriver.cs:1908-2058`) is the strongest reconnect
implementation in the subsystem.

### 2. Performance

**PERF-1 — High — Five of seven drivers read one tag per wire round-trip.**
Only Modbus (block coalescing + auto-prohibition/bisection,
`ModbusDriver.cs:687-795`) and OpcUaClient (single
`ReadValueIdCollection` per batch, `OpcUaClientDriver.cs:640-666`) batch.
The others are O(N) round trips per poll tick on serialized links:
- S7: one PDU per tag under one `_gate`d connection
  (`S7Driver.cs:443-484`); S7comm multi-var reads (S7.Net
  `ReadMultipleVarsAsync`) unused.
- TwinCAT: one ADS call per symbol; ADS **sum-read** — Beckhoff's
  documented batching mechanism — unused (`TwinCATDriver.cs:203-248`).
- FOCAS: one request/response per address on a strictly single-flight
  socket (`SynchronizedFocasClient.cs:34`); `pmc_rdpmcrng` supports ranges
  but each read fetches exactly one value's width
  (`Wire/WireFocasClient.cs:296-334`). Throughput ceiling ≈ tags × RTT.
- AbLegacy: one PCCC transaction per scalar; no span coalescing of
  adjacent file elements (N7:0..N7:2), the natural Modbus analog.
*Recommendation:* per-protocol batching is the single biggest scalability
lever; priority order = TwinCAT sum-read, S7 multi-var, FOCAS PMC range
reads, AbLegacy spans.

**PERF-2 — High — AbCip's whole-UDT batched read exists in two halves that
were never joined.** The read planner
(`Driver.AbCip/AbCipUdtReadPlanner.cs:32-100`) can collapse N members into
one parent read, but only via declaration-order layout — off by default
because it produces “silently-plausible wrong numbers” when member order
diverges (`AbCipDriverOptions.cs:60-72`). Meanwhile the driver already
fetches and caches *true* member offsets via the CIP Template Object
(`AbCipDriver.cs:151-182`, `AbCipTemplateCache.cs`) — used only for
discovery, never consulted by the planner
(`AbCipUdtMemberLayout.cs:22-24` even points at the richer path). Net: in
every safe configuration, N UDT members = N CIP round trips per tick.
*Recommendation:* feed `AbCipUdtShape` offsets into the planner; retire
the unsafe declaration-order mode.

**PERF-3 — High — S7's forked poll loop diffs arrays by reference.**
`PollOnceAsync` compares `Equals(lastSeen?.Value, current.Value)`
(`S7Driver.cs:1304`); array reads return a fresh CLR array every poll, so
every subscribed array tag fires `OnDataChange` **every tick**, flooding
the dependency mux/DPS downstream. `PollGroupEngine` fixed exactly this
with `StructuralComparisons` (`PollGroupEngine.cs:203-209`); the bespoke
S7 copy never picked it up. (Also a Conventions finding — see CONV-1.)

**PERF-4 — Medium — OpcUaClient serializes all traffic on one global
`SemaphoreSlim(1,1)`.** Reads, writes, discovery, subscription creates,
acks and HistoryReads all queue on `_gate`
(`OpcUaClientDriver.cs:78, 626, 713, 836, 1186, 1377, 1451, 1653, 1825`).
OPC UA sessions multiplex service calls natively; a multi-second
HistoryRead or full re-discovery blocks every live read/write behind it.
The gate is only needed for session-swap consistency, which `_probeLock` +
re-read-inside-critical-section already provide.

**PERF-5 — Medium — OpcUaClient discovery enrichment issues one giant
un-chunked Read and silently degrades on rejection.**
`EnrichAndRegisterVariablesAsync` sends `pending.Count * 4` ReadValueIds in
a single call (`OpcUaClientDriver.cs:1029-1046`) — 40k operations for a
10k-node server. A server enforcing `MaxNodesPerRead` returns
`BadTooManyOperations`; the blanket catch (`:1049-1057`) then registers
*every* variable as Int32/ViewOnly/non-historized with no log or health
signal. *Recommendation:* chunk client-side; log the fallback.

**PERF-6 — Low — Assorted per-tick allocation churn.** TwinCAT re-parses
`TwinCATSymbolPath` on every read/write/subscribe call — lists +
StringBuilder per tag per tick (`TwinCATDriver.cs:220, 284, 468`); S7
caches parses (`_parsedByName`) and is the model. Modbus publishes a fresh
`DriverHealth` record per successful tag read (`ModbusDriver.cs:285`).
AbCip's `BuildArray<T>` boxes per element
(`LibplctagTagRuntime.cs:107-118`). None are hot enough to be urgent.

**PERF-7 — Low — Deadband exists only in Modbus.** The publish-suppression
deadband (`ModbusDriver.cs:136-159`) and `WriteOnChangeOnly` never
generalized; noisy analog CNC/PLC signals on the other five poll-based
drivers publish every jitter. The mechanism is driver-agnostic and belongs
in or beside `PollGroupEngine`.

### 3. Conventions

**CONV-1 — High — S7 forked the poll loop instead of using
`PollGroupEngine`, and the fork has diverged in both directions.**
`PollGroupEngine`'s own doc claims it serves “Modbus, AB CIP, S7, FOCAS”
(`PollGroupEngine.cs:8-9`) but S7 re-ships the entire loop
(`S7Driver.cs:1165-1307`). The fork is *better* in two ways the engine
never absorbed (capped exponential failure backoff `:1284-1293`; poll
failures logged + degrade health `:1258-1274`) and *worse* in two ways the
engine already fixed (reference-equality array diff — PERF-3; CTS disposed
without draining the loop — STAB-6). This is the textbook cost of template
divergence: each side owns fixes the other needs. *Recommendation:*
extend `PollGroupEngine` with backoff + onError-driven health, then move
S7 onto it and delete the fork.

**CONV-2 — High — Three different strictness tiers parse the same config,
and the most-used one is the most permissive.** For every driver the same
enum field is parsed three ways:
- **Factory**: string-typed DTO + fail-loud `ParseEnum` listing valid
  values (`ModbusDriverFactoryExtensions.cs:191-201` and equivalents) —
  deliberate, good.
- **Probe**: deserializes with `JsonStringEnumConverter`; Modbus's probe
  binds the *runtime options type* (`ModbusDriverOptions`, TimeSpan
  fields) rather than the factory DTO shape
  (`ModbusDriverProbe.cs:19-24, 36`), so a DB config with `timeoutMs`
  silently loses its timeout in the probe and tag-shape mismatches can
  make the probe reject/misread a config the factory accepts. OpcUaClient
  documents probe/factory parse-parity as the rule
  (`OpcUaClientDriverProbe.cs:22`); Modbus violates it.
- **Equipment-tag parser**: silent fallback — an unknown or typo'd
  `dataType` string quietly becomes the default type (`Int16`/`DInt`/
  `Int`/`Int32` per driver) instead of a rejection
  (`Driver.Modbus.Contracts/ModbusEquipmentTagParser.cs:65-67`,
  `S7EquipmentTagParser.cs:59-61`, `AbCipEquipmentTagParser.cs:86-88`,
  `AbLegacyEquipmentTagParser.cs:60-62`,
  `TwinCATEquipmentTagParser.cs:47-49`,
  `FocasEquipmentTagParser.cs:43-45`). A mis-typed equipment tag reads and
  writes the wrong width with Good status. The identical private
  `ReadEnum` helper is copy-pasted six times instead of living beside
  `EquipmentTagRefResolver` in Core.Abstractions.
*Recommendation:* hoist a shared strict `ReadEnum` (present-but-invalid ⇒
parse failure ⇒ `BadNodeIdUnknown`); make probes parse the factory DTO.

**CONV-3 — Medium — Factory registration asymmetry leaves four drivers
logging to `NullLogger` in production.** S7, TwinCAT, AbCip and FOCAS
`Register(registry)` take no `ILoggerFactory`
(`S7DriverFactoryExtensions.cs:19`, `TwinCATDriverFactoryExtensions.cs:18`,
`AbCipDriverFactoryExtensions.cs:21`, `FocasDriverFactoryExtensions.cs:36`)
even though all four driver classes accept a logger; the bootstrap
consequently can't pass one
(`Host/Drivers/DriverFactoryBootstrap.cs:100-107`). All the warning paths
those drivers carefully log (poll failures, prohibitions, live-risk
assumptions) are invisible in production. Modbus/AbLegacy/OpcUaClient/
Galaxy have the logger-aware overload. *Recommendation:* one-line fix per
factory; align all eight `Register` signatures.

**CONV-4 — Medium — `ResolveHost` mis-keys equipment-tag references in
every multi-device driver.** The implementations consult only
`_tagsByName` (authored names); an equipment-tag TagConfig-JSON reference
never matches and falls back to the driver-level/first-device host
(`AbCipDriver.cs:483-488`, `AbLegacyDriver.cs:496-501`,
`TwinCATDriver.cs:585-592`, `FocasDriver.cs:1082-1087`; Modbus
`ModbusDriver.cs:125-131` has the same shape but per-tag `UnitId` isn't in
the equipment parser anyway). Per-host Polly bulkhead/circuit-breaker keys
are therefore wrong for equipment tags on multi-device instances — a
broken device B can trip device A's breaker and vice versa. Since
equipment tags are the *primary* authoring model post-Galaxy-standardization,
the per-call host resolver is effectively inert for the flagship path.
*Recommendation:* route `ResolveHost` through
`EquipmentTagRefResolver` and derive the host from the parsed def
(`deviceHostAddress` / `unitId`).

**CONV-5 — Medium — Health-field publication conventions drift.** The
template documents `Volatile.Read/Write` (`ModbusDriver.cs:217-228`);
FOCAS conforms (`FocasDriver.cs:43-46`), AbLegacy uses a `volatile` field
with rationale (`AbLegacyDriver.cs:29-34`), while S7
(`S7Driver.cs:124, 1272`), AbCip (`AbCipDriver.cs:95`), TwinCAT and
OpcUaClient (`OpcUaClientDriver.cs:96`) use plain fields. Immutable record
swap means no torn reads — this is a visibility/staleness nit — but four
different idioms for the same one-line concern is exactly the divergence
this review is hunting. Related one-offs: TwinCAT declares `Healthy` at
init with zero wire contact (`TwinCATDriver.cs:115`) where every other
driver proves the connection first; TwinCAT reads host state without its
probe lock (`TwinCATDriver.cs:524-525`); AbLegacy never refreshes health
on successful writes (`AbLegacyDriver.cs:344-346` vs
`AbCipDriver.cs:725`); AbLegacy silently clobbers duplicate tag names
(`AbLegacyDriver.cs:91`) where AbCip fails fast
(`AbCipDriver.cs:249-256`).

**CONV-6 — Medium — Contracts layering is uniform except OpcUaClient,
which drags the whole OPC UA SDK into its Contracts.** Six Contracts
projects are POCO options + equipment-tag parser (FOCAS's csproj even
enforces “NO PackageReference. NO ProjectReference.”), but
`Driver.OpcUaClient.Contracts` carries a full OPC UA stack reference
because `NamespaceMap` lives there
(`OpcUaClient.Contracts.csproj:9`) — every consumer wanting just the
options DTO (probe hosts, AdminUI editors, Browser) transitively loads the
SDK. This is the previously-deferred OpcUaClient.Contracts-002 finding;
it remains the right call to move `NamespaceMap` out. Minor: all Contracts
projects use the parent namespace without a `.Contracts` suffix —
consistent, just surprising.

**CONV-7 — Low/Medium — CLI harness divergences.** The six CLIs share
`DriverCommandBase` + `SnapshotFormatter` and a uniform
probe/read/write/subscribe verb set, but: `ParseValue`/`ParseBool` is
copy-pasted six times (`*/Commands/WriteCommand.cs`), option validation is
a different shape in every base and **absent entirely in AbLegacy**
(`AbLegacyCommandBase.cs` — `--timeout-ms 0` reaches the driver), the
abstract `Timeout` init-setter is a silent no-op in five bases but throws
`NotSupportedException` in AbCip (`AbCipCommandBase.cs:43`), and only
TwinCAT exposes a `browse` command despite AbCip also supporting
controller browse (hardcoded `EnableControllerBrowse=false`,
`AbCipCommandBase.cs:63`). OpcUaClient has no CLI at all (the server-side
Client.CLI tests the *server*, not this driver against a third-party
endpoint). *Recommendation:* hoist value parsing + a standard `Validate()`
into Cli.Common; add an OpcUaClient CLI or document the gap.

**CONV-8 — Low — Dead/no-op config knobs and stale scaffold docs.**
`DisableFC23` is a documented no-op (`ModbusDriverOptions.cs:83-89`);
AbCip `ConnectionSize` is plumbed but never applied
(`AbCipDriverOptions.cs:97-103`); AbLegacy's class doc still says
read/write “ship in PRs 2 and 3” (`AbLegacyDriver.cs:9-11`); OpcUaClient's
header still says “PR 66 ships the scaffold: IDriver only”
(`OpcUaClientDriver.cs:12-14`). No options class in the fleet has a
`Validate()` method — validation is scattered across factory throws and
init guards (S7's init guards are the best of breed,
`S7Driver.cs:314-385`).

### 4. Underdeveloped areas

**UNDER-1 — High — FOCAS advertises writes it cannot perform.** The only
real backend returns `BadNotWritable` for every address
(`Wire/WireFocasClient.cs:71-73`), yet `FocasTagDefinition.Writable`
defaults `true` with a doc-comment citing write tests
(`FOCAS.Contracts/FocasDriverOptions.cs:152-158`) and
`FocasEquipmentTagParser` hard-codes `Writable: true`
(`FocasEquipmentTagParser.cs:35`) — so equipment tags can surface as
Operate-writable OPC UA nodes whose writes always fail. The driver-side
write status mapping (`FocasDriver.cs:353-381`) is currently dead code.
*Recommendation:* either implement PMC writes in the wire client or force
`Writable:false` at the parser/discovery seams until it exists.

**UNDER-2 — High — OpcUaClient's `UnsMappingTable` is validated as
mandatory but consumed nowhere.** `ValidateNamespaceKind` hard-fails
Equipment-kind configs lacking a mapping table
(`OpcUaClientDriver.cs:330-355`), yet no code reads the table —
`DiscoverAsync` builds the local tree purely from remote browse structure
(`:824-1105`). Operators are forced to author config with zero runtime
effect; the promised remote→UNS remapping feature does not exist.
*Recommendation:* delete the gate or build the feature.

**UNDER-3 — High — OpcUaClient alarm source-node filtering compares
mismatched NodeId encodings.** `OnEventNotification` filters
session-relative `ns=N;…` renderings against caller-supplied refs by
ordinal string compare (`OpcUaClientDriver.cs:1337, 1538-1539`), while the
driver's own persisted references are stable `nsu=…` strings
(`:808-809`). Any non-empty filter built from stored refs silently drops
every event; only empty-filter subscriptions work today.

**UNDER-4 — Medium — S7 feature gaps make authored array tags
unreachable.** `S7TagDto` has no `ArrayCount` field and `BuildTag` never
sets it (`S7DriverFactoryExtensions.cs:80-90, 137-151`) — driver-config
array tags are silently scalar; arrays only work as equipment tags
(`S7EquipmentTagParser.cs:73-87`). Array *writes* are unsupported
(`S7Driver.cs:1014-1017`), wide-type arrays are a stated follow-up
(`:861-862`), and `UInt32` surfaces lossily as `Int32`
(`S7Driver.cs:1149-1152`).

**UNDER-5 — Medium — AbCip alarm acknowledge outcomes are discarded.**
`AcknowledgeAsync` fire-and-forgets the write results
(`AbCipAlarmProjection.cs:143-149`); a failed ack (undeclared `.Acked`
member, non-writable, comms error) is invisible to the operator, health,
and the Part 9 caller — conditions stick un-acked with no visible cause.
Related discovery weak spots: with `EnableControllerBrowse` on, one
unreachable PLC faults the entire multi-device `DiscoverAsync`
(uncaught `await foreach`, `AbCipDriver.cs:970-1037`), and browsed tags
default to writable/Operate (`CipSymbolObjectDecoder.cs:91`).

**UNDER-6 — Medium — Equipment-tag parsers lag the authored-tag feature
set.** Modbus's parser ignores `unitId`, `deadband`, `stringByteOrder`,
`writable`, `coalesceProhibited` and the address-grammar string, and
forces `Writable: true` (`ModbusEquipmentTagParser.cs:54-57`); AbLegacy
and FOCAS also hard-code writable-true
(`AbLegacyEquipmentTagParser.cs:52`, `FocasEquipmentTagParser.cs:35`) —
read-only equipment tags are unauthorable on three drivers (AbCip honours
a `writable` key, `AbCipEquipmentTagParser.cs:53-54`). FOCAS equipment
tags additionally bypass the `FocasCapabilityMatrix` pre-flight gate that
authored tags get (`FocasDriver.cs:243-247` vs `:115-119`). As equipment
tags are the primary authoring model, the parsers deserve parity plus a
shared conformance test.

**UNDER-7 — Medium — Live-risk assumptions documented but ungated.**
TwinCAT carries two explicit "unverified against real hardware" blocks on
core paths — array read shape (`AdsTwinCATClient.cs:109-116`) and
Flat-mode `SubSymbols` population (`:263-277`, struct members could
silently vanish from discovery) — plus the bit-RMW width assumption
(STAB-11). AbLegacy's array decode rests on five explicitly unproven
layout assumptions with no PCCC fixture
(`LibplctagLegacyTagRuntime.cs:64-88`). FOCAS's `cnc_getfigure` command id
and servo-load scaling are sim-validated only
(`FocasWireClient.cs:391-395, 943-947`). These are honest, well-documented
debts — but nothing aggregates them into a "needs bench time" checklist.

**UNDER-8 — Medium — Test coverage is codec-heavy, failure-path-light, and
uneven.** Approximate unit-test counts: Modbus 191 (+71 addressing),
AbCip 234, FOCAS 143, S7 130, TwinCAT 119, AbLegacy 114, OpcUaClient 93
(+10 browser). Integration suites are all skip-gated on fixture
reachability; Modbus's is the richest (30 tests incl. exception injection
and device-quirk profiles), AbLegacy's the thinnest (2), and TwinCAT's 13
require a real TC3 XAR runtime — no docker fixture exists, so it never
runs automated. Systemic gaps: **zero reconnect tests for S7 and
AbLegacy** (the STAB-1/STAB-10 findings live exactly there), zero
concurrency tests for S7 and AbCip (STAB-4 lives there; only AbLegacy has
a dedicated runtime-concurrency suite), and OpcUaClient has the widest
feature surface on the lowest test density (though its failure-path
*spread* — reconnect, failover, stale-session race, continuation points —
is the best). `Cli.Common`'s `DriverCommandBase` has no direct tests.
There is **zero TODO/HACK/FIXME/NotImplementedException debt** in the
subsystem — all `NotSupportedException` sites are deliberate fail-fast
gates with handlers.

**UNDER-9 — Low — OpcUaClient is a 2,154-line monolith.** Six separable
responsibilities share one file (config/PKI/identity, failover sweep,
recursive discovery, live subscriptions, alarms/acks, the full
IHistoryProvider, plus the reconnect state machine). The reconnect state
machine is the trickiest concurrency in the subsystem and deserves
extraction for isolated testability. Also: subscription transfer rests on
the *unset* SDK default `TransferSubscriptionsOnReconnect`
(`OpcUaClientDriver.cs:1946-1949`), and `BuildCertificateIdentity` only
loads PKCS#12 while the options doc promises PEM support
(`:479-484` vs `OpcUaClientDriverOptions.cs:68-75`).

---

## Maturity ratings

| Dimension | Rating (1-5) | Justification |
|---|---|---|
| Stability | **3** | The template (Modbus transport + OpcUaClient reconnect machine) is genuinely robust and write-outcome surfacing is universal, but two Critical connection-loss failures (S7 no-reconnect, TwinCAT orphaned native subs), an AbCip handle-concurrency hazard, and fleet-wide missing backoff mean a routine PLC power-cycle defeats half the fleet. |
| Performance | **2** | Only 2 of 7 drivers batch reads; the rest are O(N) serialized round trips per poll tick, AbCip's flagship UDT batching is half-built, and deadband exists only in Modbus — the subsystem scales by tag count, not by request count. |
| Conventions | **3** | The shared seams (PollGroupEngine, EquipmentTagRefResolver, factory/probe pattern, StatusMapper) are real and mostly followed, but the S7 poll-loop fork, three-tier config-parse strictness, six-way `ReadEnum` copy-paste, logger-registration asymmetry, and drifting health idioms show fixes not flowing back to the template. |
| Underdeveloped areas | **3** | Zero stub/TODO debt and honest live-risk documentation, offset by advertised-but-dead features (FOCAS writes, `UnsMappingTable`, `DisableFC23`, `ConnectionSize`), equipment-tag parsers lagging the primary authoring model, and reconnect/concurrency test gaps precisely where the Critical bugs live. |

---

## Recommended remediation order

1. **S7 reconnect** (STAB-1) + a reconnect test template applied to S7 and
   AbLegacy (UNDER-8) — one field scenario, two drivers, currently fatal.
2. **TwinCAT native-subscription replay on client recycle** (STAB-2).
3. **AbCip per-runtime operation lock** (STAB-4, port from AbLegacy) and
   **FOCAS ConcurrentDictionary caches** (STAB-5) — silent-corruption
   class.
4. **Modbus transport: timeout/framing-violation ⇒ connection teardown**
   (STAB-3).
5. **PollGroupEngine v2**: absorb S7's backoff + failure-health, wire
   `onError` in all five consumers, migrate S7 off its fork
   (CONV-1, STAB-9, PERF-3, STAB-8).
6. **Shared strict equipment-tag enum parsing + writable/capability
   parity** (CONV-2, UNDER-6) — one Core.Abstractions helper, six deletions.
7. **Per-protocol read batching** (PERF-1/PERF-2), starting with the AbCip
   planner⇄template-cache join (design already exists in-tree).
8. Sweep the one-liners: factory `ILoggerFactory` (CONV-3), `ResolveHost`
   via resolver (CONV-4), FOCAS writable-false (UNDER-1), delete
   `UnsMappingTable` gate (UNDER-2), OpcUaClient alarm-filter encoding
   (UNDER-3).