Merge pull request '[s7] S7 — Optimized DB / S7Plus (decision PR)' (#408) from auto/s7/PR-S7-F into auto/driver-gaps

Closes #304

docs/Client.CLI.md

@@ -183,19 +183,46 @@ otopcua-cli historyread -u opc.tcp://localhost:4840/OtOpcUa \
 | `--start` | Start time, ISO 8601 or date string (default: 24 hours ago) |
 | `--end` | End time, ISO 8601 or date string (default: now) |
 | `--max` | Maximum number of values (default: 1000) |
-| `--aggregate` | Aggregate function: Average, Minimum, Maximum, Count, Start, End |
+| `--aggregate` | Aggregate function name (see catalog below). Case-insensitive. |
 | `--interval` | Processing interval in milliseconds for aggregates (default: 3600000) |
 
 #### Aggregate mapping
 
+The CLI accepts the seven aggregates listed below — these are the
+human-driven set the operator typically asks for from the command line.
+
 | Name | OPC UA Node ID |
 |------|---------------|
-| `Average` | `AggregateFunction_Average` |
+| `Average` (or `avg`) | `AggregateFunction_Average` |
-| `Minimum` | `AggregateFunction_Minimum` |
+| `Minimum` (or `min`) | `AggregateFunction_Minimum` |
-| `Maximum` | `AggregateFunction_Maximum` |
+| `Maximum` (or `max`) | `AggregateFunction_Maximum` |
 | `Count` | `AggregateFunction_Count` |
-| `Start` | `AggregateFunction_Start` |
+| `Start` (or `first`) | `AggregateFunction_Start` |
-| `End` | `AggregateFunction_End` |
+| `End` (or `last`) | `AggregateFunction_End` |
+| `StandardDeviation` (or `stddev` / `stdev`) | `AggregateFunction_StandardDeviationSample` |
+
+The driver-side `IHistoryProvider.ReadProcessedAsync` API (used by the
+OtOpcUa server's HistoryRead facade) supports the full OPC UA Part 13 §5
+catalog — ~30 aggregates including `TimeAverage`, `Interpolative`, `Range`,
+`PercentGood`, `Delta`, etc. See
+[`docs/drivers/OpcUaClient.md`](drivers/OpcUaClient.md#historyread-aggregates-part-13-catalog)
+for the full list. Adding a new CLI shorthand is a one-line change in
+`HistoryReadCommand.ParseAggregateType` — file an issue if you need one
+exposed.
+
+#### Event-mode coverage
+
+Drivers that implement the filter-aware
+`IHistoryProvider.ReadEventsAsync(fullReference, EventHistoryRequest, ct)`
+overload (currently the OPC UA Client gateway driver — Galaxy keeps the
+fixed-field fallback) honour `EventFilter` SelectClauses and a `WhereClause`
+when the server-side history facade forwards them. The CLI does not yet
+expose a dedicated `--events` flag — clients that need filter-aware event
+history call `HistoryReadEvents` through their own SDK; the CLI's
+`historyread` command stays focused on the data-history (Raw / Processed /
+AtTime) path. Adding `--events` is tracked as a follow-up — the wire path
+on the driver side is in place (see
+[`docs/drivers/OpcUaClient.md`](drivers/OpcUaClient.md#historyread-events)).
 
 ### alarms
 

docs/Driver.AbLegacy.Cli.md

@@ -21,6 +21,9 @@ dotnet run --project src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Cli -- --help
 | `-P` / `--plc-type` | `Slc500` | Slc500 / MicroLogix / Plc5 / LogixPccc |
 | `--timeout-ms` | `5000` | Per-operation timeout — see precedence note below |
 | `--retries` | `0` | Retry count on transient `BadCommunicationError` (PR 9 / #252) |
+| `--demote-failure-threshold` | `3` | **PR ablegacy-12 / #255** — consecutive comm failures before the device is auto-demoted |
+| `--demote-for-ms` | `30000` | **PR ablegacy-12 / #255** — auto-demote cool-down window in ms |
+| `--no-demote` | off | **PR ablegacy-12 / #255** — disable auto-demote entirely (counters still tick) |
 | `--verbose` | off | Serilog debug output |
 
 Family ↔ CIP-path cheat sheet:
@@ -29,6 +32,27 @@ Family ↔ CIP-path cheat sheet:
   with no backplane
 - **LogixPccc** — `1,0` (Logix controller accessed via the PCCC compatibility
   layer; rare)
+- **PLC-5 via 1756-DHRIO bridge** — `1,<slot>,2,<station-octal>` (PLC-5 only).
+  See [drivers/AbLegacy-DH-Bridging.md](drivers/AbLegacy-DH-Bridging.md) for
+  the full DH+ syntax, octal-station reference (00..77 = 0..63), and manual
+  hardware smoke procedure.
+
+#### DHRIO worked example (PR ablegacy-13 / #256)
+
+PLC-5 on DH+ node 7 (octal 07), DHRIO module in chassis slot 3,
+EtherNet/IP gateway 192.168.1.10:
+
+```powershell
+otopcua-ablegacy-cli read `
+    -g ab://192.168.1.10/1,3,2,07 `
+    -P Plc5 -a N7:10 -t Int
+```
+
+The parser validates `1,<slot>,2,<station>`: port-1 must be the backplane,
+slot must be 0..16, port-3 must be `2` (DH+), station must be octal 0..77 (so
+`80`, `90`, etc. are rejected). Combining a DH+ bridge path with a non-PLC-5
+family at startup throws `InvalidOperationException("DHRIO bridging is
+PLC-5-only")`.
 
 ### Per-device timeout / retry tuning (#252, PR 9)
 
@@ -84,6 +108,37 @@ otopcua-ablegacy-cli probe -g ab://192.168.1.20/1,0
 otopcua-ablegacy-cli probe -g ab://192.168.1.30/ -P MicroLogix -a S:0
 ```
 
+`probe` output (PR ablegacy-12 / #255) reports both `Health` (driver health
+state) and `Host state`. The latter is sourced from `IHostConnectivityProbe`
+and surfaces `Demoted` when the auto-demote threshold has tripped — a fast
+visual signal that the CLI is short-circuiting future reads against this
+device until the cool-down expires:
+
+```text
+Gateway:      ab://192.168.1.20/1,0
+PLC type:     Slc500
+Health:       Degraded
+Host state:   Demoted
+Last error:   libplctag status -33 reading N7:0
+```
+
+### Auto-demote knobs
+
+```powershell
+# Trip after just one comm failure, hold for 60s.
+otopcua-ablegacy-cli read -g ab://192.168.1.20/1,0 -a N7:0 -t Int `
+    --demote-failure-threshold 1 --demote-for-ms 60000
+
+# Opt out of auto-demote — stresses the link without short-circuiting.
+otopcua-ablegacy-cli read -g ab://192.168.1.20/1,0 -a N7:0 -t Int --no-demote
+```
+
+The CLI is a one-shot test client — auto-demote primarily matters in the
+server-side multi-device deployment, where a single demoted PLC can no
+longer block reads against its healthy peers. Use the CLI flags to
+reproduce a flapping-link scenario locally before tuning the server-side
+`appsettings.json` `Demote` block.
+
 ### `read`
 
 ```powershell

docs/Driver.S7.Cli.md

@@ -25,6 +25,8 @@ dotnet run --project src/ZB.MOM.WW.OtOpcUa.Driver.S7.Cli -- --help
 | `--tsap-mode` | `Auto` | ISO-on-TCP connection class: `Auto` / `Pg` / `Op` / `S7Basic` / `Other`. Hardened S7-1500 / ET 200SP CPUs may require `Op` or `S7Basic`. See [s7.md TSAP / Connection Type](v2/s7.md#tsap--connection-type). |
 | `--local-tsap` | (unset) | Optional 16-bit local TSAP override (e.g. `0x0200`). Required when `--tsap-mode Other`; wins over class default under Pg/Op/S7Basic. |
 | `--remote-tsap` | (unset) | Optional 16-bit remote TSAP override. Required when `--tsap-mode Other`; wins over class default under Pg/Op/S7Basic. |
+| `--password` | (unset) | Connection-level password sent right after `OpenAsync`. Used by hardened S7-300/400 (protection levels 1-3) and S7-1200/1500 (TIA Portal *Connection Mechanism* gate). Never logged. NB: S7netplus 0.20 doesn't expose `SendPassword`; the CLI prints a one-line warning and continues. See [s7.md "PLC password / protection levels"](v2/s7.md#plc-password--protection-levels). |
+| `--protection-level` | `Auto` | Declarative hint: `Auto` / `None` / `Level1` / `Level2` / `Level3` (S7-300/400) / `ConnectionMechanism` (S7-1200/1500). Diagnostic only — the wire-side unlock is driven by `--password`. |
 | `--verbose` | off | Serilog debug output |
 
 ## PUT/GET must be enabled
@@ -95,6 +97,17 @@ otopcua-s7-cli read -h 192.168.1.30 -a M0.0 -t Bool
 
 # 80-char S7 string
 otopcua-s7-cli read -h 192.168.1.30 -a DB10.STRING[0] -t String --string-length 80
+
+# CPU diagnostics (SZL) — virtual @System.* addresses (PR-S7-E1).
+# Requires ExposeSystemTags = true on the driver instance; surfaces as
+# BadNotSupported until S7netplus exposes a public ReadSzlAsync (or we ship
+# a raw-PDU helper). See docs/v2/s7.md "CPU diagnostics (SZL)" for the full
+# table and the snap7 / S7netplus 0.20 caveat.
+otopcua-s7-cli read -h 192.168.1.30 -a @System.CpuType   -t String
+otopcua-s7-cli read -h 192.168.1.30 -a @System.Firmware  -t String
+otopcua-s7-cli read -h 192.168.1.30 -a @System.OrderNo   -t String
+otopcua-s7-cli read -h 192.168.1.30 -a @System.CycleMs.Min -t Float64
+otopcua-s7-cli read -h 192.168.1.30 -a "@System.DiagBuffer.Entry[0]" -t String
 ```
 
 ### `write`
@@ -128,6 +141,43 @@ wrong `--slot` produces also shows up when the CPU rejects PG class — try
 endpoint config. See [s7.md TSAP / Connection Type](v2/s7.md#tsap--connection-type)
 for the byte table and motivation.
 
+### Hardened CPU — supplying a connection-level password
+
+```powershell
+# S7-300 protection-level 2 — read+write protected without unlock.
+otopcua-s7-cli read -h 192.168.1.31 -c S7300 --slot 2 `
+    --password "tia-portal-set-password" `
+    --protection-level Level2 `
+    -a DB1.DBW0 -t Int16
+
+# S7-1500 ConnectionMechanism — TIA Portal Protection & Security pane gate.
+otopcua-s7-cli probe -h 10.50.12.30 `
+    --tsap-mode Op `
+    --password "tia-portal-set-password" `
+    --protection-level ConnectionMechanism
+```
+
+The password is emitted to the PLC immediately after `OpenAsync` succeeds and
+before the pre-flight PUT/GET probe runs (the same probe that would otherwise
+be the first operation a hardened CPU refuses). Never logged in any form;
+identifier-only success line is `S7 password sent for {Host}`.
+
+**S7netplus 0.20 does not yet expose a public `SendPassword`** — the driver
+discovers the method reflectively, so a future minor release will be picked
+up automatically. Until then, configuring `--password` on a hardened CPU
+emits this warning at Init:
+
+```
+[Warning] S7 password is set on driver '<id>' against host '<host>', but
+the linked S7netplus library does not expose SendPassword; password is
+being ignored at the wire.
+```
+
+Init still completes (the COTP handshake itself doesn't require the
+password) but the first read against a hardened CPU will surface
+`BadDeviceFailure`. See [s7.md "PLC password / protection levels"](v2/s7.md#plc-password--protection-levels)
+for the full motivation, the no-log invariant, and the workaround matrix.
+
 ### `subscribe`
 
 ```powershell

docs/Driver.TwinCAT.Cli.md

@@ -217,3 +217,37 @@ in screen-recorded bug reports.
 `--poll-only` polls go through the same cached-handle path as `read`, so
 repeated polls of the same symbol carry only a 4-byte handle on the wire
 rather than the full symbolic path.
+
+### `alarms` (PR 5.1 / #316)
+
+Stream TC3 EventLogger alarms via the driver's `IAlarmSource` bridge.
+Subscribes against AMS port 110 (`AMSPORT_EVENTLOG`) on the same target,
+prints each event with timestamp / source / severity / message until
+Ctrl+C.
+
+```powershell
+# All alarms — every event the EventLogger surfaces
+otopcua-twincat-cli alarms -n 192.168.1.40.1.1
+
+# Filter by source — only events whose source name matches (case-insensitive)
+otopcua-twincat-cli alarms -n 192.168.1.40.1.1 --source Conveyor1.MotorOverload
+
+# Multiple sources — repeat the flag
+otopcua-twincat-cli alarms -n 192.168.1.40.1.1 --source Conveyor1 --source Pump3
+```
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--source` | (none) | Optional source filter; repeat for multiple |
+
+Output format (one line per event):
+
+```
+[HH:mm:ss.fff] <source> sev=<Low|Medium|High|Critical> type=<event-class> cond=<condition-id> "<message>"
+```
+
+The verb forces `EnableAlarms=true` on the underlying driver; the
+default driver config keeps it off so deployments without an
+EventLogger configured pay no cost. See
+[`docs/drivers/TwinCAT.md` §Alarms](drivers/TwinCAT.md) for the
+full bridge architecture and decode caveats.

docs/Redundancy.md

@@ -98,6 +98,10 @@ Role swaps, stand-alone promotions, and base-level adjustments all happen throug
 
 The OtOpcUa Client CLI at `src/ZB.MOM.WW.OtOpcUa.Client.CLI` supports `-F` / `--failover-urls` for automatic client-side failover; for long-running subscriptions the CLI monitors session KeepAlive and reconnects to the next available server, recreating the subscription on the new endpoint. See [`Client.CLI.md`](Client.CLI.md) for the command reference.
 
+## vs. upstream-side redundancy
+
+The mechanics on this page describe **OtOpcUa as a redundant server** — two of our instances clustered behind one OPC UA address space, exposing `ServerUriArray` + dynamic `ServiceLevel` to downstream clients. The mirror-image scenario — **the OPC UA Client driver consuming an upstream redundant pair** — is documented separately in [`drivers/OpcUaClient.md` § Upstream redundancy](drivers/OpcUaClient.md#upstream-redundancy-serverarray). Both rely on the same OPC UA Part 4 § 6.6.2 model (non-transparent warm/hot via `RedundancySupport` + `ServerUriArray` + `ServiceLevel`); they sit at opposite ends of the gateway pipeline. A deployment can wire either, both, or neither.
+
 ## Depth reference
 
 For the full decision trail and implementation plan — topology invariants, peer-probe cadence, recovery-dwell policy, compliance-script guard against enum-value drift — see `docs/v2/plan.md` §Phase 6.3.

docs/drivers/AbLegacy-DH-Bridging.md

@@ -0,0 +1,141 @@
+# AB Legacy — DH+ via 1756-DHRIO bridging
+
+PR ablegacy-13 / [#256](https://github.com/dohertj2/lmxopcua/issues/256). The AB
+Legacy driver can address a PLC-5 sitting on a DH+ link by routing CIP requests
+through a 1756-DHRIO module installed in a ControlLogix chassis. This is the
+canonical way to keep an installed-base PLC-5 fleet alive after the chassis-
+level migration to ControlLogix; the DHRIO module exposes a DH+ "side" that
+talks to the legacy PLC-5 / SLC-DH+ peers and a backplane "side" that the
+ControlLogix CPU + Ethernet bridge can route through.
+
+## Wire layout
+
+```
+OtOpcUa server  ──EtherNet/IP──►  1756-EN2T (slot 0)  ──backplane──►  1756-DHRIO (slot N)  ──DH+──►  PLC-5
+```
+
+Two CIP hops:
+
+1. **Backplane** — port `1`, slot `<N>` (the slot the DHRIO module lives in).
+2. **DH+** — port `2`, station `<S>` (the DH+ node address of the target PLC-5,
+   in **octal**).
+
+Resulting CIP path: `1,<N>,2,<S>`.
+
+> The first port `1` is always the backplane; port `2` is the DH+ side of the
+> 1756-DHRIO module. This mirrors the convention Rockwell uses in RSLinx + RSLogix
+> 5.
+
+## Octal station number
+
+The DH+ network was specified with **octal** node addresses. Rockwell tooling
+displays them in octal too (RSLogix 5 → "DH+ Node Address" field on the
+controller properties dialog). The driver follows suit — the station segment
+of the CIP path **must be parsed as octal** (digits 0..7 only; `8`, `9`, and
+multi-byte garbage are rejected).
+
+DH+ addresses run `0..77` octal == `0..63` decimal. Quick reference:
+
+| Octal | Decimal | Octal | Decimal | Octal | Decimal | Octal | Decimal |
+|------:|--------:|------:|--------:|------:|--------:|------:|--------:|
+| 00 | 0  | 20 | 16 | 40 | 32 | 60 | 48 |
+| 01 | 1  | 21 | 17 | 41 | 33 | 61 | 49 |
+| 02 | 2  | 22 | 18 | 42 | 34 | 62 | 50 |
+| 03 | 3  | 23 | 19 | 43 | 35 | 63 | 51 |
+| 04 | 4  | 24 | 20 | 44 | 36 | 64 | 52 |
+| 05 | 5  | 25 | 21 | 45 | 37 | 65 | 53 |
+| 06 | 6  | 26 | 22 | 46 | 38 | 66 | 54 |
+| 07 | 7  | 27 | 23 | 47 | 39 | 67 | 55 |
+| 10 | 8  | 30 | 24 | 50 | 40 | 70 | 56 |
+| 11 | 9  | 31 | 25 | 51 | 41 | 71 | 57 |
+| 12 | 10 | 32 | 26 | 52 | 42 | 72 | 58 |
+| 13 | 11 | 33 | 27 | 53 | 43 | 73 | 59 |
+| 14 | 12 | 34 | 28 | 54 | 44 | 74 | 60 |
+| 15 | 13 | 35 | 29 | 55 | 45 | 75 | 61 |
+| 16 | 14 | 36 | 30 | 56 | 46 | 76 | 62 |
+| 17 | 15 | 37 | 31 | 57 | 47 | 77 | 63 |
+
+Anything past `77` octal (i.e. decimal > 63) is invalid on a real DH+ network
+and rejected by the parser.
+
+## PLC-5 only
+
+DHRIO bridging is **PLC-5-only**. The driver enforces this at
+`AbLegacyDriver.InitializeAsync` time: a DH+ bridge path combined with
+`PlcFamily=Slc500 / MicroLogix / LogixPccc` throws
+`InvalidOperationException("DHRIO bridging is PLC-5-only")` immediately rather
+than letting reads silently fail with `BadCommunicationError` on the wire.
+
+Background: the 1756-DHRIO module only speaks DH+ to PLC-5 / SLC-DH+ peers, and
+libplctag's PCCC stack only exposes the PLC-5 side. SLC 5/04 boxes on DH+
+**can** be physically reached through a DHRIO module, but the protocol stack
+needed to drive them isn't exposed by libplctag — out of scope for this driver.
+
+## CLI worked example
+
+PLC-5 at DH+ node `07` (octal == 7 decimal), DHRIO module in slot 3, gateway
+`192.168.1.10`:
+
+```powershell
+otopcua-ablegacy-cli probe `
+    -g ab://192.168.1.10/1,3,2,07 `
+    -P Plc5 `
+    -a N7:0
+```
+
+```powershell
+# Read N7:10 from the PLC-5 across the DHRIO bridge
+otopcua-ablegacy-cli read `
+    -g ab://192.168.1.10/1,3,2,07 `
+    -P Plc5 `
+    -a N7:10 `
+    -t Int
+```
+
+The driver surfaces the parsed bridge form on the host-address record:
+`BackplaneSlot=3`, `DhPlusPort=2`, `DhPlusStation=7` (decimal-translated). Use
+those values when reading driver-diagnostics output to confirm the bridge was
+recognised — a non-bridge CIP path leaves all three fields null.
+
+## Manual smoke procedure
+
+There is no automated end-to-end coverage for DH+ bridging because the only
+path to wire-level validation is real hardware (libplctag's `ab_server` Docker
+image doesn't simulate the DHRIO + DH+ + PLC-5 stack). The unit-test layer
+covers parser positive / negative cases.
+
+Hardware smoke checklist:
+
+1. Confirm the 1756-DHRIO module is present in the target ControlLogix chassis.
+   RSLinx Classic should show `DH+, 1` under the chassis tree with the PLC-5
+   nodes enumerated underneath.
+2. Note the DHRIO module's slot number (the `<N>` in `1,<N>,2,<S>`).
+3. Note the target PLC-5's DH+ node address — read it off the front-panel switch
+   bank, or the controller properties in RSLogix 5. **Read it as octal**.
+4. From an OtOpcUa box that can reach the EtherNet/IP gateway:
+
+   ```powershell
+   otopcua-ablegacy-cli probe -g ab://<gateway>/1,<slot>,2,<station-octal> -P Plc5 -a S:0
+   ```
+
+   `S:0` (status file word 0) is non-destructive and present on every PLC-5.
+5. If the probe succeeds, exercise an N file read against a known
+   non-zero address. Compare against the value displayed in RSLogix 5 →
+   Online → Data → N7.
+
+If the probe fails with `BadCommunicationError`:
+
+- Wrong slot number — re-check via RSLinx.
+- Wrong octal node — convert from RSLogix 5's display value (already octal); a
+  decimal-thinking conversion mistake is the most common smoke failure.
+- DHRIO module's DH+ baud rate doesn't match the PLC-5's switch setting (57.6k
+  / 115.2k / 230.4k) — driver-side problem this can't paper over.
+- A scanner on the DHRIO is in scheduled-mode and starving unscheduled
+  PCCC traffic — bump the DHRIO's unscheduled-message slice in RSLogix 5000.
+
+## See also
+
+- [`Driver.AbLegacy.Cli.md`](../Driver.AbLegacy.Cli.md) — the family / CIP-path
+  cheat sheet now carries a DHRIO row.
+- [`drivers/AbLegacy-Test-Fixture.md`](AbLegacy-Test-Fixture.md) — DH+ bridging
+  is unit-only; no Docker fixture supports it.

docs/drivers/AbLegacy-Diagnostics.md

@@ -7,10 +7,12 @@ directly without going through a separate diagnostics RPC. Mirrors the AB CIP
 
 Closes #253 (PR ablegacy-10).
 
-## The seven counters
+## The nine counters
 
-Each device managed by the `AbLegacyDriver` exposes seven read-only nodes under
+Each device managed by the `AbLegacyDriver` exposes nine read-only nodes under
-`AbLegacy/<host>/_Diagnostics/<name>`:
+`AbLegacy/<host>/_Diagnostics/<name>`. The first seven shipped in PR ablegacy-10;
+`DemoteCount` + `LastDemotedUtc` arrived with PR ablegacy-12 / #255 (auto-demote
+on comm failure).
 
 | Name | Type | Semantics |
 |---|---|---|
@@ -21,6 +23,8 @@ Each device managed by the `AbLegacyDriver` exposes seven read-only nodes under
 | `LastErrorCode` | Int32 | Most recent libplctag status code on a failed read; `0` when no error has been seen since the last reset. |
 | `LastErrorMessage` | String | Most recent libplctag error message on a failed read; empty when no error has been seen since the last reset. |
 | `CommFailures` | Int64 | Count of read failures mapped to `BadCommunicationError`. Spans transient libplctag throws + retried-out chains so operators see a single "wire fell off" counter. |
+| `DemoteCount` | Int64 | **PR ablegacy-12** — cumulative auto-demote events for this device. Bumps every time the driver crosses the consecutive-failure threshold and arms a fresh cool-down window. Cumulative across `ReinitializeAsync` (preserved through redeploys) so a flapping link surfaces as a steadily climbing counter. |
+| `LastDemotedUtc` | String | **PR ablegacy-12** — ISO-8601 UTC timestamp of the most recent auto-demotion. Empty string when this device has never been demoted. |
 
 **Address shape**: `_Diagnostics/<deviceHostAddress>/<name>` —
 e.g. `_Diagnostics/ab://10.0.0.5/1,0/RequestCount`.
@@ -34,10 +38,11 @@ user-config tag node, just under a reserved sibling folder.
 
 | Trigger | Effect |
 |---|---|
-| `ReinitializeAsync` | Every counter for every device resets to zero, plus `LastErrorMessage` clears to empty. |
+| `ReinitializeAsync` | Every counter for every device resets to zero, plus `LastErrorMessage` clears to empty. **PR ablegacy-12 exception:** `DemoteCount` + `LastDemotedUtc` survive the reinit so an operator redeploying mid-incident doesn't lose the flapping-link history. |
-| `ShutdownAsync` | Same as Reinitialize — counters drop with the device map. |
+| `ShutdownAsync` | All counters drop with the device map (including `DemoteCount`). |
 | Driver process restart | Counters start at zero. |
 | Probe transition Stopped→Running | **No automatic reset** — counters are cumulative across reconnect events so operators can spot intermittent links by watching `CommFailures` keep climbing. |
+| Probe transition Demoted→Running | **PR ablegacy-12** — early-clear of the active demote window, but the cumulative `DemoteCount` stays put. |
 
 There is no in-process "reset" RPC at the time of writing. If you need to
 clear counters without a redeploy, kick a `ReinitializeAsync` from the Admin
@@ -99,14 +104,85 @@ overview dashboard, plus a faster rate (1 s) on `LastErrorMessage` /
 short-circuit makes every read O(1) — there's no penalty for fast polling
 of the counter itself, only the OPC UA subscription bookkeeping.
 
+## Auto-demote on comm failure (PR ablegacy-12 / #255)
+
+When a device fails N consecutive reads or probes the driver marks it
+**Demoted** for a configurable cool-down window. Reads against a demoted
+device short-circuit with `BadCommunicationError` *without invoking
+libplctag* — that's the whole point of the feature: one slow PLC sharing
+the driver thread can't starve faster peers reading from healthy hosts on
+the same `AbLegacyDriver` instance.
+
+### Configuration
+
+Per-device, optional. `null` keeps the documented defaults (auto-demote
+**enabled** with 3 failures / 30 s).
+
+```jsonc
+{
+  "Devices": [
+    {
+      "HostAddress": "ab://10.0.0.5/1,0",
+      "PlcFamily": "Slc500",
+      "Demote": {
+        "FailureThreshold": 3,    // default 3
+        "DemoteForMs": 30000,     // default 30s
+        "Enabled": true           // default true
+      }
+    }
+  ]
+}
+```
+
+| Knob | Default | Notes |
+|---|---|---|
+| `FailureThreshold` | `3` | Consecutive comm failures before the device is demoted. A successful read or probe resets the tally. Terminal failures (`BadNodeIdUnknown`, `BadTypeMismatch`, …) **do not count** — they're config / decoder mismatches, not field outages. |
+| `DemoteForMs` | `30000` (30s) | Cool-down window. Reads while this is active short-circuit; a successful probe clears it early. |
+| `Enabled` | `true` | Set to `false` to keep the diagnostic counters but skip the auto-throttle. The failure tally still ticks but never arms the cool-down. |
+
+### Recovery
+
+Three ways out of Demoted, in order of likelihood:
+
+1. **Probe success** — the per-device probe loop (`Probe.Enabled = true`,
+   default address `S:0`) is the fast path. The next probe iteration after
+   demotion will exercise the wire; on success it clears
+   `DemotedUntilUtc` immediately and transitions the host to `Running`.
+2. **Window expiry** — once `DemoteForMs` elapses the demote marker
+   clears on the next read attempt. The read goes through; if it fails,
+   the failure tally keeps counting from where it left off (so a
+   permanently-down device re-arms the window after one more consecutive
+   failure rather than having to repeat the full threshold).
+3. **`ReinitializeAsync`** — clears `ConsecutiveFailures` +
+   `DemotedUntilUtc` outright. Cumulative `DemoteCount` survives.
+
+### Observability
+
+`DemoteCount` is the headline counter — it bumps once per demotion event,
+not per short-circuited read. A device that flaps every hour for a week
+shows `DemoteCount = ~168` on Friday afternoon, which is the operator
+signal you actually want.
+
+`LastDemotedUtc` is the ISO-8601 UTC timestamp of the most recent
+demotion. Bind it on a per-device tile alongside `DemoteCount` for
+"flapping link" alerting.
+
+### Host-state surface
+
+A demoted device reports `HostState.Demoted` (new in PR ablegacy-12
+on `Core.Abstractions/IHostConnectivityProbe.cs`). Consumers that
+predate the new value (the central `HostStatusPublisher`) safely treat
+it as `Stopped` — no schema migration needed.
+
 ## Cross-references
 
 - [`AbLegacyDiagnosticTags.cs`](../../src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDiagnosticTags.cs)
   — counter store + read short-circuit
 - [`AbLegacyDriver.cs`](../../src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs)
-  — increment sites in `ReadAsync`, discovery emission in `DiscoverAsync`
+  — increment sites in `ReadAsync`, discovery emission in `DiscoverAsync`,
+  auto-demote bookkeeping in `RecordFailureAndMaybeDemote` + `ProbeLoopAsync`
 - [`AbLegacy-Test-Fixture.md`](AbLegacy-Test-Fixture.md) — `AbLegacyDiagnosticsTests`
-  + collision-rejection contract
+  + `AbLegacyAutoDemoteTests` + collision-rejection contract
 - [AB CIP `_System/` parallel](../../src/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipSystemTagSource.cs)
   — same pattern with the CIP-specific six entries (incl. writeable
   `_RefreshTagDb` trigger)

docs/drivers/AbLegacy-Test-Fixture.md

@@ -53,12 +53,31 @@ supplies a `FakeAbLegacyTag`.
   counters: 5 reads (3 ok / 2 fail) → `RequestCount=5`, `ResponseCount=3`,
   `ErrorCount=2`; `LastErrorCode` reflects the most recent libplctag status;
   `RetryCount` increments per retry attempt beyond the first; counters reset
-  on `ReinitializeAsync`; discovery emits exactly 7 diagnostic variables per
+  on `ReinitializeAsync`; discovery emits the canonical diagnostic variables
-  device under `_Diagnostics/`; collision rejection at `InitializeAsync` for
+  per device under `_Diagnostics/` (now 9 with PR ablegacy-12); collision
-  user tags shadowing reserved names or `_Diagnostics/` addresses; the
+  rejection at `InitializeAsync` for user tags shadowing reserved names or
-  `_Diagnostics/<host>/<name>` short-circuit returns the live snapshot through
+  `_Diagnostics/` addresses; the `_Diagnostics/<host>/<name>` short-circuit
-  `ReadAsync` without bumping `RequestCount`; two devices keep counters
+  returns the live snapshot through `ReadAsync` without bumping
-  independent.
+  `RequestCount`; two devices keep counters independent.
+- `AbLegacyAutoDemoteTests` — **PR ablegacy-12 / #255** auto-demote on comm
+  failure: 3 consecutive failures arm the demote window and surface
+  `HostState.Demoted`; subsequent reads short-circuit with
+  `BadCommunicationError` *without invoking libplctag* (verified via
+  `factory.Tags["N7:0"].ReadCount` not advancing); successful read resets
+  the consecutive-failure counter; failure-success-failure pattern doesn't
+  cross the threshold; `DemoteCount` + `LastDemotedUtc` surface via
+  `_Diagnostics/`; `Enabled=false` opts out (failures still count, demotion
+  never fires); `ReinitializeAsync` clears the active window but preserves
+  cumulative `DemoteCount`; cool-down expiry allows the next read through;
+  two devices in one driver — one faulty, one healthy — proves the faulty
+  side's demotion doesn't starve the healthy side; `BadNodeIdUnknown`
+  (terminal) does not count toward the comm-failure tally; DTO JSON
+  round-trip preserves `FailureThreshold` / `DemoteForMs` / `Enabled` at
+  the per-device level; `HostState.Demoted` enum value is wired through
+  `Core.Abstractions`. Companion integration test in
+  `tests/.../IntegrationTests/AbLegacyAutoDemoteTests.cs` runs the
+  two-device-one-unreachable scenario against a live ab_server fixture
+  using `127.0.0.1:1` as the unreachable peer.
 - `RsLogixSymbolImportTests` — ablegacy-11 / #254 RSLogix CSV symbol-import parser:
   canonical 8-row CSV (one row per N/F/B/L/ST/T/C/R) → 8 typed
   `AbLegacyTagDefinition`s with the right `DataType`; header + comment-line
@@ -113,6 +132,17 @@ driver-side correctness depends on libplctag being correct.
 `IPerCallHostResolver` contract is verified; real PCCC wire routing across
 multiple gateways is not.
 
+### 3a. DH+ via 1756-DHRIO bridging (PR ablegacy-13 / #256)
+
+Unit-only — coverage lives in `AbLegacyDhPlusBridgingTests`. The CIP-path
+parser positive / negative cases (octal-station validation, slot bounds, port
+shape) and the PLC-5-only family guard at `InitializeAsync` are exercised
+against fakes. There is no Docker fixture for DH+ because libplctag's
+`ab_server` doesn't simulate the DHRIO + DH+ + PLC-5 stack — wire-level
+validation requires real hardware. See
+[`AbLegacy-DH-Bridging.md`](AbLegacy-DH-Bridging.md) for the manual smoke
+procedure.
+
 ### 4. Alarms / history
 
 PCCC has no alarm object + no history object. Driver doesn't implement

docs/drivers/FOCAS.md

@@ -8,6 +8,47 @@ Power Mate i families. Talks to the controller via the licensed
 For range-validation and per-series capability surface see
 [`docs/v2/focas-version-matrix.md`](../v2/focas-version-matrix.md).
 
+## Fixed-tree `Production/` projection — issue #258 (F1-b) + issue #272 (F5-a)
+
+Per-device read-only nodes refreshed from the same `cnc_rdparam` /
+cycle-timer poll the probe loop already runs. No additional wire calls
+are issued for any of these — they are all cache-or-derive reads.
+
+| Node | DataType | Source | Notes |
+| --- | --- | --- | --- |
+| `Production/PartsProduced` | `Int32` | `cnc_rdparam(6711)` | Active parts-count counter. Wraps to 0 on operator reset. |
+| `Production/PartsRequired` | `Int32` | `cnc_rdparam(6712)` | Operator-set target. |
+| `Production/PartsTotal` | `Int32` | `cnc_rdparam(6713)` | Lifetime parts counter. |
+| `Production/CycleTimeSeconds` | `Int32` | `cnc_rdtimer` (channel 0) | Live cycle-time accumulator. Resets to 0 on next cycle start (CNC-side behaviour). |
+| **`Production/LastCycleSeconds`** | **`Float64`** | **derived** | **Plan PR F5-a — seconds for the most recently completed cycle, computed as `CycleTimeSeconds(now) - CycleTimeSeconds(at previous parts-count increment)`. `null` until the second observed parts-count increment establishes a delta. Pure derivation, no new wire calls. See edge-case rules below.** |
+| **`Production/LastCycleStartUtc`** | **`DateTime`** *(UTC)* | **derived** | **Plan PR F5-a — UTC wall-clock of the most-recent cycle's start, computed as `nowUtc - LastCycleSeconds`. `null` alongside `LastCycleSeconds` until the second observed increment.** |
+
+### F5-a derivation edge-case rules
+
+- **First observation** establishes the baseline; `LastCycleSeconds` /
+  `LastCycleStartUtc` stay `null` until the second observed parts-count
+  increment produces the first delta.
+- **Parts-count counter reset** (current value goes backwards, e.g.
+  shift-change zero) **preserves the last published values** so an
+  operator reading the tag mid-shift-change sees the last known cycle
+  duration rather than `null` / Bad. The next positive transition
+  produces a fresh delta from the new baseline.
+- **Cycle-timer rollover** (delta would be negative — e.g. CNC zeroes
+  the cycle timer at part completion) **leaves the previously-published
+  values unchanged for one tick** and re-baselines so the next
+  increment produces a clean delta. The driver does NOT publish a
+  negative `LastCycleSeconds`.
+- **Parts-count jumps `> 1`** (backfill — e.g. counter increments by
+  3 at once) publish the **timer delta over the window** as
+  `LastCycleSeconds`. The plan's "delta over the window between
+  successive parts-count increments" definition does not divide by the
+  count delta; the value reflects the actual elapsed timer between the
+  two observations.
+- **Reconnect / reinit** clears the derivation state — the prior CNC
+  session's cycle-timer + parts-count snapshots may be invalidated by
+  the FWLIB session boundary, so the next post-reconnect probe tick
+  re-establishes the baseline before the next delta publishes.
+
 ## Alarm history (`cnc_rdalmhistry`) — issue #267, plan PR F3-a
 
 `FocasAlarmProjection` exposes two modes via `FocasDriverOptions.AlarmProjection`:

docs/drivers/OpcUaClient-Test-Fixture.md

@@ -166,6 +166,35 @@ Beyond that:
 3. **Dedicated historian integration lab** — only path for
    historian-specific coverage.
 
+## HistoryRead aggregate coverage
+
+PR-13 (issue #285) extended `HistoryAggregateType` from 5 to ~30 values
+matching the OPC UA Part 13 §5 catalog. The mapping itself
+(`OpcUaClientDriver.MapAggregateToNodeId`) is unit-tested via
+`OpcUaClientAggregateMappingTests`:
+
+- The full enum is swept with `Enum.GetValues<HistoryAggregateType>()` —
+  every value must resolve to a non-null namespace-0 numeric `NodeId`.
+- The 25 new aggregates each assert against a reflection-resolved
+  `Opc.Ua.ObjectIds.AggregateFunction_*` field by name, so a future SDK
+  upgrade that renames a constant trips the test loudly.
+- The original 5 ordinals stay pinned to their pre-PR-13 NodeIds so existing
+  config files / persisted enums keep working.
+
+This is **the well-known-NodeId test path** — the standard Part 13 NodeIds
+are stable across SDK versions; round-tripping each one against a live
+upstream is the integration suite's job and doesn't add coverage to the
+mapping table itself.
+
+`OpcUaClientAggregateSweepTests` is the integration counterpart. It loops
+every enum value against a real opc-plc upstream and asserts the wire path
+doesn't crash even when the simulator returns
+`BadAggregateNotSupported` for an aggregate it doesn't honour. opc-plc's
+default profile doesn't enable HistoryRead on the well-known nodes, so the
+test currently `Assert.Skip`s — re-enables when the fixture image is
+upgraded to a history-sim profile (`--useslowtypes --ut=10` or similar) and
+a known-good historized NodeId is wired into `OpcPlcProfile`.
+
 ## Key fixture / config files
 
 - `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/` — unit tests with
@@ -175,3 +204,7 @@ Beyond that:
 - `tests/ZB.MOM.WW.OtOpcUa.Server.Tests/OpcUaServerIntegrationTests.cs` —
   the server-side integration harness a future loopback client test could
   piggyback on
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/OpcUaClientAggregateMappingTests.cs`
+  — Part 13 aggregate enum-to-NodeId mapping coverage (PR-13)
+- `tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/OpcUaClientAggregateSweepTests.cs`
+  — wire-side aggregate sweep against opc-plc (build-only scaffold; PR-13)

docs/drivers/OpcUaClient.md

@@ -126,3 +126,225 @@ expose a "ReverseConnect.Endpoint" config knob).
 - Public-internet OPC UA: reverse-connect is a network-policy workaround,
   not a security primitive. Always pair with `Sign` or `SignAndEncrypt`
   + a vetted user-token policy.
+
+## HistoryRead Events
+
+The driver passes through OPC UA `HistoryReadEvents` to the upstream server.
+HistoryRead Raw / Processed / AtTime ship in the same code path
+(`ExecuteHistoryReadAsync`); event history takes a slightly different shape
+because the client sends an `EventFilter` (SelectClauses + WhereClause) rather
+than a plain numeric / time-based detail block.
+
+### Wire path
+
+`IHistoryProvider.ReadEventsAsync(fullReference, EventHistoryRequest, ct)`
+translates to:
+
+```
+new ReadEventDetails {
+    StartTime,
+    EndTime,
+    NumValuesPerNode,
+    Filter = EventFilter { SelectClauses, WhereClause }
+}
+```
+
+…and is sent through `Session.HistoryReadAsync` to the upstream server. The
+returned `HistoryEvent.Events` collection (one `HistoryEventFieldList` per
+historical event) is unwrapped into `HistoricalEventBatch.Events`, where each
+`HistoricalEventRow.Fields` dictionary is keyed by the
+`SimpleAttributeSpec.FieldName` the caller supplied. The server-side history
+dispatcher uses those keys to align fields with the wire-side SelectClause
+order — drivers don't have to honour the entire OPC UA `EventFilter` shape
+verbatim.
+
+### SelectClauses
+
+When `EventHistoryRequest.SelectClauses` is `null` the driver falls back to a
+default set that matches `BuildHistoryEvent` on the server side:
+
+| Field | Browse path | Notes |
+| --- | --- | --- |
+| `EventId` | `EventId` | BaseEventType — stable unique id. |
+| `SourceName` | `SourceName` | Source-object name. |
+| `Time` | `Time` | Process-side event timestamp. Used for `OccurrenceTime`. |
+| `Message` | `Message` | LocalizedText payload. |
+| `Severity` | `Severity` | OPC UA 1-1000 scale. |
+| `ReceiveTime` | `ReceiveTime` | Server-side ingest timestamp. |
+
+Custom SelectClauses are supported — pass any
+`IReadOnlyList<SimpleAttributeSpec>`. Each entry's `TypeDefinitionId`
+defaults to `BaseEventType` when `null`; pass an explicit NodeId text (e.g.
+`"i=2782"` for `ConditionType`) to reach typed-condition fields.
+
+### WhereClause
+
+`ContentFilterSpec.EncodedOperands` carries the binary-encoded
+`ContentFilter` from the wire. The driver decodes it into the SDK
+`ContentFilter` and attaches it to the outgoing `EventFilter` verbatim — the
+OPC UA Client driver is a passthrough for filter semantics, it does not
+evaluate them. A malformed filter is dropped silently; the SelectClause
+projection still goes out.
+
+### Continuation points
+
+Returned in `HistoricalEventBatch.ContinuationPoint`. The server-side
+HistoryRead facade is responsible for round-tripping these so a paged event
+read against a chatty upstream completes incrementally. The driver itself
+doesn't track them — every `ReadEventsAsync` call issues a fresh
+`HistoryReadAsync`.
+
+## HistoryRead Aggregates (Part 13 catalog)
+
+`IHistoryProvider.ReadProcessedAsync` takes a `HistoryAggregateType` and the
+driver maps it to the standard `Opc.Ua.ObjectIds.AggregateFunction_*` NodeId
+in `MapAggregateToNodeId`. PR-13 (issue #285) extended the enum from the
+original 5 values (Average / Minimum / Maximum / Total / Count) to the full
+OPC UA Part 13 §5 catalog — ~30 aggregates.
+
+The mapping is best-effort: not every upstream OPC UA server implements every
+aggregate. Aggregates the upstream rejects come back with
+`StatusCode=BadAggregateNotSupported` on the per-row HistoryRead result; the
+driver passes that through verbatim (cascading-quality rule, Part 11 §8) — it
+does not throw. Servers advertise the aggregates they support via the
+`AggregateConfiguration` object on the `Server` node; clients can probe it at
+runtime.
+
+### Catalog
+
+| Enum value | SDK NodeId field | Part 13 § | Server-side support | Typical use |
+| --- | --- | --- | --- | --- |
+| `Average` | `AggregateFunction_Average` | §5.4 | almost always | smoothing |
+| `Minimum` | `AggregateFunction_Minimum` | §5.5 | almost always | low watermark |
+| `Maximum` | `AggregateFunction_Maximum` | §5.6 | almost always | high watermark |
+| `Total` | `AggregateFunction_Total` | §5.10 | usually | totalisation |
+| `Count` | `AggregateFunction_Count` | §5.18 | almost always | sample count |
+| `TimeAverage` | `AggregateFunction_TimeAverage` | §5.4.2 | usually | time-weighted mean |
+| `TimeAverage2` | `AggregateFunction_TimeAverage2` | §5.4.3 | sometimes | bounded time-weighted mean |
+| `Interpolative` | `AggregateFunction_Interpolative` | §5.3 | usually | trend snapshot |
+| `MinimumActualTime` | `AggregateFunction_MinimumActualTime` | §5.5.4 | sometimes | when low occurred |
+| `MaximumActualTime` | `AggregateFunction_MaximumActualTime` | §5.6.4 | sometimes | when high occurred |
+| `Range` | `AggregateFunction_Range` | §5.7 | usually | spread |
+| `Range2` | `AggregateFunction_Range2` | §5.7 | sometimes | bounded spread |
+| `AnnotationCount` | `AggregateFunction_AnnotationCount` | §5.21 | rarely | operator notes |
+| `DurationGood` | `AggregateFunction_DurationGood` | §5.16 | sometimes | quality coverage |
+| `DurationBad` | `AggregateFunction_DurationBad` | §5.16 | sometimes | gap accounting |
+| `PercentGood` | `AggregateFunction_PercentGood` | §5.17 | sometimes | quality % |
+| `PercentBad` | `AggregateFunction_PercentBad` | §5.17 | sometimes | gap % |
+| `WorstQuality` | `AggregateFunction_WorstQuality` | §5.20 | sometimes | worst seen |
+| `WorstQuality2` | `AggregateFunction_WorstQuality2` | §5.20 | rarely | bounded worst |
+| `StandardDeviationSample` | `AggregateFunction_StandardDeviationSample` | §5.13 | sometimes | n-1 stddev |
+| `StandardDeviationPopulation` | `AggregateFunction_StandardDeviationPopulation` | §5.13 | sometimes | n stddev |
+| `VarianceSample` | `AggregateFunction_VarianceSample` | §5.13 | sometimes | n-1 variance |
+| `VariancePopulation` | `AggregateFunction_VariancePopulation` | §5.13 | sometimes | n variance |
+| `NumberOfTransitions` | `AggregateFunction_NumberOfTransitions` | §5.12 | sometimes | event count |
+| `DurationInStateZero` | `AggregateFunction_DurationInStateZero` | §5.19 | sometimes | OFF time |
+| `DurationInStateNonZero` | `AggregateFunction_DurationInStateNonZero` | §5.19 | sometimes | ON time |
+| `Start` | `AggregateFunction_Start` | §5.8 | usually | first sample |
+| `End` | `AggregateFunction_End` | §5.9 | usually | last sample |
+| `Delta` | `AggregateFunction_Delta` | §5.11 | usually | end-start |
+| `StartBound` | `AggregateFunction_StartBound` | §5.8 | sometimes | extrapolated start |
+| `EndBound` | `AggregateFunction_EndBound` | §5.9 | sometimes | extrapolated end |
+
+"Server-side support" is heuristic — see your upstream's `AggregateConfiguration`
+node for the authoritative list. AVEVA Historian, KEPServerEX, Prosys, and
+opc-plc each implement different subsets.
+
+### Driver-side validation
+
+The mapping itself is unit-tested over the full enum
+(`OpcUaClientAggregateMappingTests`) — every value resolves to a non-null
+namespace-0 NodeId, and the original 5 ordinals stay pinned. Wire-side
+behaviour against a live server is exercised by
+`OpcUaClientAggregateSweepTests` (build-only scaffold pending an opc-plc
+history-sim profile).
+
+## Upstream redundancy (`ServerArray`)
+
+When the upstream OPC UA server is itself a redundant pair (warm or hot per
+OPC UA Part 4 §6.6.2), the driver supports **mid-session failover** driven by
+the upstream's own `Server.ServerRedundancy.RedundancySupport` +
+`ServerUriArray` + `Server.ServiceLevel` nodes. Distinct from the static
+boot-time failover sweep on `EndpointUrls`: that path picks a single survivor
+at session-create time; this path swaps the active session live when the
+upstream signals degradation, transferring subscriptions onto the secondary so
+monitored-item handles stay valid.
+
+### Configuration
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `Redundancy.Enabled` | `false` | Opt-in. When `false`, the driver doesn't read `RedundancySupport` / `ServerUriArray` and doesn't subscribe to `ServiceLevel`. |
+| `Redundancy.ServiceLevelThreshold` | `200` | Byte value below which the driver triggers failover. OPC UA spec convention: 200+ = healthy primary, 100..199 = degraded, 0..99 = unrecoverable. |
+| `Redundancy.RecheckInterval` | `5s` | Lower bound between two consecutive failovers — suppresses oscillation when ServiceLevel flaps around the threshold. |
+
+### Behaviour
+
+- At session activation the driver reads
+  `Server.ServerRedundancy.RedundancySupport`. When `None`, the driver records
+  an empty peer list and the failover path becomes a no-op (`ServiceLevel`
+  drops are still observable via diagnostics but trigger nothing).
+- When the upstream advertises `Cold` / `Warm` / `WarmActive` / `Hot`, the
+  driver pulls `Server.ServerRedundancy.ServerUriArray` for the peer list,
+  falling back to the top-level `Server.ServerArray` for legacy upstreams that
+  don't expose the redundancy node.
+- A dedicated subscription on `Server.ServiceLevel` (publish interval 1s,
+  separate from the alarm + data subscriptions) drives every failover decision
+  via the SDK's notification path — no polling loop.
+- On a drop below `ServiceLevelThreshold` the driver picks the next URI in the
+  peer list that isn't the active one, opens a parallel session against it,
+  and calls `Session.TransferSubscriptionsAsync(other, sendInitialValues:true)`
+  to migrate every live subscription (data + alarm + model-change +
+  service-level itself). On success the driver swaps `Session`, closes the
+  old one, and bumps `RedundancyFailoverCount`.
+- On any failure (`BadSecureChannelClosed`, `BadCertificateUntrusted`,
+  `TransferSubscriptions` returning `false`, secondary unreachable) the driver
+  leaves the existing session untouched, increments
+  `RedundancyFailoverFailures`, and waits for the next ServiceLevel
+  notification. The keep-alive watchdog continues to cover full
+  upstream-loss scenarios.
+
+### Shared client-cert prerequisite
+
+`TransferSubscriptionsAsync` requires the secondary's secure channel to accept
+the same client certificate the primary did. Operators running heterogeneous
+secondaries (different cert trust stores) will see `BadCertificateUntrusted`
+on every failover attempt and the failures counter climbing. The fix is to
+push the gateway driver's application-instance certificate into both
+upstreams' `TrustedPeerCertificates` store before enabling redundancy. A
+follow-up adds a fallback path that re-creates subscriptions instead of
+transferring when the secondary rejects the channel.
+
+### Diagnostics
+
+The `driver-diagnostics` RPC surfaces three new counters via
+`DriverHealth.Diagnostics`:
+
+| Key | Type | Notes |
+| --- | --- | --- |
+| `RedundancyFailoverCount` | `double` (long-counted) | Successful mid-session swaps since driver start. |
+| `RedundancyFailoverFailures` | `double` (long-counted) | Swap attempts that bailed (TransferSubscriptions false, secondary unreachable, etc.). |
+| `ActiveServerUri` | string (in `OpcUaClientDiagnostics.ActiveServerUri`) | URI of the upstream the driver is currently bound to. Updates on every successful failover. |
+
+### Forced-failover runbook
+
+To validate the wiring against a real redundant upstream pair:
+
+1. Confirm the upstream advertises `RedundancySupport != None` and a
+   non-empty `ServerUriArray`. Use the Client CLI:
+   `dotnet run --project src/ZB.MOM.WW.OtOpcUa.Client.CLI -- redundancy -u <primary>`.
+2. Set `Redundancy.Enabled = true` on the gateway's `OpcUaClient` driver
+   instance and restart.
+3. Tail driver diagnostics:
+   `driver-diagnostics --instance <id>` — note `RedundancyFailoverCount = 0`
+   pre-test.
+4. Drive a `ServiceLevel` drop on the primary. On AVEVA / KEPServer this is
+   typically a "force standby" Admin action; on a custom server it's a write
+   to the simulated ServiceLevel node.
+5. Observe `RedundancyFailoverCount = 1` within `RecheckInterval` of the
+   drop, the gateway's `HostName` swap to the secondary URI, and downstream
+   reads/subscriptions continuing without interruption.
+
+For non-redundant upstreams (single-server deployments) the recommended
+configuration is to leave `Redundancy.Enabled = false` and rely on
+`EndpointUrls` for boot-time failover only.

docs/drivers/S7-Test-Fixture.md

@@ -88,6 +88,18 @@ real PLC latency is not exercised.
 S7-1200 vs S7-1500 vs S7-300/400 connection semantics (PG vs OP vs S7-Basic)
 not differentiated at test time.
 
+**Optimized DB / S7Plus** is the variant-shaped gap with the biggest field
+impact. snap7 happens to behave like a classic-S7comm-only PLC, so the
+integration suite cannot reproduce the shape that an S7-1500 with default
+"Optimized block access" checked would return (`BadDeviceFailure` on every
+absolute-offset read). The decision is documented at
+[`docs/v2/s7.md` § Optimized DB constraint (S7Plus)](../v2/s7.md#optimized-db-constraint-s7plus)
+and tracked in [`docs/featuregaps.md`](../featuregaps.md) row #1; the
+project ships **Track 1** (operator unchecks Optimized block access in TIA
+Portal) and **Track 3** (bridge via the `OpcUaClient` driver against the
+CPU's onboard OPC UA server). A custom S7Plus implementation is out of
+scope.
+
 ### 5. Data types beyond the scalars
 
 `STRING` with length-prefix quirks, `DTL` / `DATE_AND_TIME`, arrays of
@@ -95,6 +107,41 @@ structs — not covered. UDT fan-out IS covered (PR-S7-D2 / #300) via the
 `udt_layout` meta-seed in `Docker/profiles/s7_1500.json` and the
 `Driver_fans_out_udt_into_member_tags` integration test.
 
+### 6. SZL (System Status List) — `@System.*` virtual addresses
+
+PR-S7-E1 / [#302](https://github.com/dohertj2/dohertj2/lmxopcua/issues/302)
+adds a virtual `@System.*` address surface (CPU type, firmware, scan-cycle
+stats, diagnostic-buffer ring) backed by SZL reads. **snap7 does not
+implement SZL** — the simulator answers every SZL request with a function-
+not-supported error, so the integration profile exercises only the
+not-supported semantics (`@System.CpuType` against snap7 returns
+`BadNotSupported`). Live-firmware SZL coverage is parked behind a
+`[Fact(Skip = ...)]` until either S7netplus exposes a public `ReadSzlAsync`
+or we ship a raw S7comm PDU helper. See
+[`docs/v2/s7.md` "CPU diagnostics (SZL)"](../v2/s7.md#cpu-diagnostics-szl)
+for the wire-status detail.
+
+### 7. Password / protection levels — not modelled by snap7
+
+PR-S7-E2 / [#303](https://github.com/dohertj2/lmxopcua/issues/303) adds
+`Password` + `ProtectionLevel` options that emit a connection-level password
+right after `OpenAsync`. **snap7 does not model S7 protection levels** — the
+simulator accepts every connection regardless of the password set on the
+client, so the integration profile cannot distinguish "password sent
+correctly" from "password ignored". Coverage stays at the unit-test seam:
+`S7PasswordOptionsTests` injects a fake `IS7PlcAuthGate` to assert the
+dispatch contract (Password=null skips the call; Password+SupportsSendPassword
+calls the gate; auth-failed wraps to a clean `InvalidOperationException`),
+plus the no-log invariant on `S7DriverOptions.ToString()`.
+
+The wire path is also fundamentally limited until S7netplus 0.20 exposes a
+public `SendPassword` — the driver currently logs a warning and continues
+when the API is missing. See
+[`docs/v2/s7.md` "PLC password / protection levels"](../v2/s7.md#plc-password--protection-levels)
+for the library-limitation note. Live-firmware coverage of the unlock path
+requires a hardened S7-1500 lab rig with TIA Portal "Protection & Security"
+configured, which is parked as a follow-up.
+
 ## When to trust the S7 tests, when to reach for a rig
 
 | Question | Unit tests | Real PLC |
@@ -127,6 +174,44 @@ structs — not covered. UDT fan-out IS covered (PR-S7-D2 / #300) via the
    runner with the lab rig executes. The classifier branch
    (`S7PreflightClassifier.IsPutGetDisabled`) is unit-tested without a
    network in `S7PreflightTests.Classifier_matches_only_PUT_GET_disabled_error_codes`.
+5. **Live-firmware Optimized-block-access toggle (PR-S7-F / [#304](https://github.com/dohertj2/lmxopcua/issues/304)).**
+   snap7 happens to behave like a classic-S7comm CPU, so the integration
+   profile cannot reproduce the failure that a default new TIA Portal V14+
+   project produces (`BadDeviceFailure` on `DB1.DBW0` against an Optimized
+   DB). A manual smoke test on the lab rig, gated behind `--with-real-plc`,
+   would close that loop. Suggested checklist on a real S7-1500 V2.5+:
+   1. Create `DB1` in TIA Portal with three INT members at offsets 0, 2, 4.
+      Leave **Optimized block access checked** (the default).
+   2. Compile + download to the PLC.
+   3. Drive the OtOpcUa S7 driver against `DB1.DBW0` — assert that the read
+      returns `BadDeviceFailure` (the Track-1-not-applied symptom). This is
+      the failure shape the docs warn about.
+   4. Open `DB1`'s properties → **uncheck Optimized block access** →
+      compile → download. Re-run the read; assert it returns the seeded
+      INT value at offset 0. (Track 1 verified end-to-end.)
+   5. **Track 3 verification (separate run on the same rig):** with
+      Optimized access re-enabled on `DB1`, activate the CPU's onboard
+      OPC UA server in TIA Portal, expose `DB1.<MemberName>` through a
+      Server interface, register an `OpcUaClient` driver against
+      `opc.tcp://<plc-ip>:4840`, and assert the symbolic read returns the
+      same seeded value. This proves the bridge path against a real
+      Optimized DB without the operator having to disable Optimized
+      access.
+
+   The test must stay manual: TIA Portal compile + download cannot be
+   automated from CI without a Siemens engineering toolchain license, and
+   download-with-CPU-stop is destructive on a shared lab rig. Document
+   results inline in PR descriptions when the rig is available.
+
+6. **PR-S7-E1 — live SZL test against a real S7-1500.** snap7 doesn't
+   implement SZL at all, and S7netplus 0.20 doesn't expose a public
+   `ReadSzlAsync`, so the `@System.*` virtual address surface currently
+   answers `BadNotSupported` against every backend. The parser
+   (`S7SzlParser`) is unit-tested against golden bytes; flipping the wire
+   path on requires either an S7netplus PR or a raw-PDU helper. Once that's
+   in, [`S7_1500SzlTests.System_CpuType_against_live_S7_1500_returns_non_empty_string`](../../tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/S7_1500/S7_1500SzlTests.cs)
+   should be flipped from `[Fact(Skip = ...)]` to env-var-gated against the
+   self-hosted runner with the lab rig.
 
 Without any of these, S7 driver correctness against real hardware is trusted
 from field deployments, not from the test suite.

docs/drivers/TwinCAT-Test-Fixture.md

@@ -89,7 +89,22 @@ default 1024-element cap (UDT per-member coverage; see
 
 Capability surfaces whose contract is verified: `IDriver`, `IReadable`,
 `IWritable`, `ITagDiscovery`, `ISubscribable`, `IHostConnectivityProbe`,
-`IPerCallHostResolver`.
+`IPerCallHostResolver`, `IAlarmSource` (PR 5.1 / #316, gated behind
+`EnableAlarms=true` — see capability matrix below).
+
+## Capability matrix
+
+| Capability | Status | Notes |
+| --- | --- | --- |
+| `IDriver` | yes | Lifecycle + health |
+| `IReadable` | yes | Sum-read for scalars; per-tag for bit / array |
+| `IWritable` | yes | Sum-write for scalars; per-tag for bit-RMW / array |
+| `ITagDiscovery` | yes | Pre-declared + opt-in symbol-table walk |
+| `ISubscribable` | yes | Native ADS notifications by default; poll fallback |
+| `IHostConnectivityProbe` | yes | `ReadStateAsync` + system-symbol diagnostics |
+| `IPerCallHostResolver` | yes | Tag → device hostAddress |
+| `IAlarmSource` (PR 5.1 / #316) | partial | Scaffold + unit-tested; live wire decode is best-effort against AMS port 110, see `docs/v3/twincat-eventlogger-spike.md` |
+| `IHistoryProvider` | no | Not in scope for this driver family |
 
 ## What it does NOT cover
 
@@ -134,11 +149,11 @@ Native ADS notifications fire on the PLC cycle boundary. The fake test
 harness assumes notifications fire on a timer the test controls;
 cycle-aligned firing under real PLC control is not verified.
 
-### 6. Alarms / history
+### 6. History
 
-Driver doesn't implement `IAlarmSource` or `IHistoryProvider` — not in
+Driver doesn't implement `IHistoryProvider` — not in scope for this
-scope for this driver family. TwinCAT 3's TcEventLogger could theoretically
+driver family. (Alarms now have a dedicated `IAlarmSource` bridge — see
-back an `IAlarmSource`, but shipping that is a separate feature.
+the capability matrix below + `docs/drivers/TwinCAT.md`.)
 
 ## When to trust TwinCAT tests, when to reach for a rig
 

docs/drivers/TwinCAT.md

@@ -0,0 +1,115 @@
+# TwinCAT driver — operator guide
+
+Beckhoff TwinCAT 2 / TwinCAT 3 ADS driver. Talks to the runtime via
+`Beckhoff.TwinCAT.Ads` v6 (managed); requires a reachable AMS router on
+the host (local TwinCAT XAR, the standalone `Beckhoff.TwinCAT.Ads.TcpRouter`
+NuGet, or any Windows box with TwinCAT installed and an authorised AMS
+route).
+
+## Configuration surface
+
+`TwinCATDriverOptions` (one instance supports N AMS targets, each a
+`TwinCATDeviceOptions`). Wire format mirrors the C# class on the JSON
+side — every `init`-only property round-trips through
+`System.Text.Json` with the default options.
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `Devices` | `TwinCATDeviceOptions[]` | `[]` | One entry per AMS target. |
+| `Tags` | `TwinCATTagDefinition[]` | `[]` | Pre-declared symbol set. |
+| `Probe.Enabled` | `bool` | `true` | Per-tick `ReadStateAsync` against the runtime. |
+| `Probe.Interval` | `TimeSpan` | `5 s` | |
+| `Timeout` | `TimeSpan` | `2 s` | Per-operation timeout. |
+| `UseNativeNotifications` | `bool` | `true` | False = fall through to PollGroupEngine. |
+| `EnableControllerBrowse` | `bool` | `false` | Walk symbol table on `DiscoverAsync`. |
+| `MaxArrayExpansion` | `int` | `1024` | Per-element cutoff during nested-UDT browse. |
+| `EnableAlarms` (PR 5.1) | `bool` | `false` | Opt-in TC3 EventLogger bridge — see "Alarms" below. |
+
+## Alarms (TC3 EventLogger bridge, PR 5.1 / #316)
+
+When `EnableAlarms=true`, the driver implements `IAlarmSource` by
+opening a second `AdsClient` against AMS port **110**
+(`AMSPORT_EVENTLOG`) and adding a device notification on
+`ADSIGRP_TCEVENTLOG_ALARMS`. Subscribers receive `OnAlarmEvent`
+notifications for every transition the EventLogger surfaces (raise /
+clear / acknowledge).
+
+### Decode caveat
+
+Beckhoff doesn't ship a managed wrapper for `TcEventLogger` in the
+regular `Beckhoff.TwinCAT.Ads` v6 NuGet — only the C++ TcCOM headers
+exist. The driver therefore decodes the AMS-port-110 binary payload
+manually. The current implementation is best-effort: event class GUIDs
+and source names usually decode cleanly; some less-common fields may
+surface as `"Unknown"` until a follow-up PR lands a complete decoder.
+Spike output captured at
+[`docs/v3/twincat-eventlogger-spike.md`](../v3/twincat-eventlogger-spike.md).
+
+### Wire path
+
+| Layer | What it does |
+| --- | --- |
+| Primary `AdsClient` | The existing per-device session against the PLC runtime port (default `851`) — handles reads / writes / native subscriptions. |
+| Secondary `AdsClient` (alarms) | Opens against AMS port `110` on the same target NetId. Adds one device notification on `ADSIGRP_TCEVENTLOG_ALARMS` with a `length=...` payload covering the full alarm-list shape. |
+| `ITwinCATAlarmGate` (driver-internal) | Decodes incoming notifications into `TwinCATAlarmEvent` records (`EventClass`, `Source`, `Severity`, `Message`, `OccurrenceUtc`, `Acked`). |
+| `TwinCATAlarmSource` | Projects `TwinCATAlarmEvent` onto the driver-agnostic `IAlarmSource.OnAlarmEvent`. |
+
+### Severity mapping (TC3 → OPC UA AC)
+
+TC3 EventLogger severity is a 0–255 `USINT`. The driver maps it onto
+the four-bucket `AlarmSeverity` enum the OPC UA AC layer consumes:
+
+| TC3 severity | `AlarmSeverity` |
+| --- | --- |
+| 0–64 | `Low` |
+| 65–128 | `Medium` |
+| 129–192 | `High` |
+| 193–255 | `Critical` |
+
+### Acknowledge
+
+`AcknowledgeAsync` round-trips through `ITwinCATAlarmGate.AcknowledgeAsync`,
+which writes to the EventLogger ack index group. Best-effort — the wire
+format isn't documented in managed code, so individual ack failures don't
+poison the batch and the gate returns silently when the EventLogger isn't
+configured.
+
+### Disabling
+
+`EnableAlarms=false` (default) returns a sentinel handle from
+`SubscribeAlarmsAsync` and never opens the secondary `AdsClient`.
+`OnAlarmEvent` simply never fires. Capability negotiation still works,
+which is why the driver advertises `IAlarmSource` unconditionally.
+
+## CLI
+
+The `otopcua-twincat-cli` test client exposes an `alarms` subcommand
+that wraps the bridge end-to-end:
+
+```powershell
+dotnet run --project src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Cli -- alarms `
+    --ams-net-id 5.23.91.23.1.1 --ams-port 851 `
+    --source Conveyor1.MotorOverload
+```
+
+See [`docs/Driver.TwinCAT.Cli.md`](../Driver.TwinCAT.Cli.md) for the
+full CLI surface.
+
+## Test coverage
+
+- **Unit**: `TwinCATAlarmSourceTests` covers (a) feature-gating off vs.
+  on, (b) gate-event projection shape, (c) multi-event ordering, (d)
+  source-filter matching, (e) acknowledge round-trip, (f) JSON DTO
+  round-trip.
+- **Integration**: `TwinCATAlarmIntegrationTests.Driver_raises_alarm_event_when_PLC_logs_event`
+  ships build-only in PR 5.1; the GVL + FB_AlarmHarness ship as XAE
+  stubs at `tests/.../TwinCatProject/PLC/`. Once the XAR project
+  imports them the test transitions skip → pass.
+
+## See also
+
+- [`docs/v3/twincat-eventlogger-spike.md`](../v3/twincat-eventlogger-spike.md)
+  — spike output for the managed-wrapper question
+- [`docs/drivers/TwinCAT-Test-Fixture.md`](TwinCAT-Test-Fixture.md)
+  — coverage map + capability matrix
+- [`docs/Driver.TwinCAT.Cli.md`](../Driver.TwinCAT.Cli.md) — CLI guide

docs/featuregaps.md

@@ -0,0 +1,20 @@
+# Feature gaps — driver-side limitations and decisions
+
+Cross-driver registry of known capability gaps, the workaround we ship, and
+whether the gap is on the roadmap. Each row links to the driver-specific
+deep-dive document. Closed entries stay in the table for traceability — they
+are not deleted, only marked.
+
+| # | Driver | Gap | Status | Workaround / decision | Roadmap | Reference |
+|---|--------|-----|--------|-----------------------|---------|-----------|
+| 1 | S7 | **Optimized DB / S7Plus** — S7netplus speaks classic S7comm only and cannot read S7-1200 / S7-1500 DBs that have "Optimized block access" checked (the TIA Portal V14+ default). Absolute-offset reads against an Optimized DB return `BadDeviceFailure`. | **Decided — Track 1 + Track 3 (closed by [#304](https://github.com/dohertj2/lmxopcua/issues/304))** | **Track 1 (docs):** operators uncheck "Optimized block access" in TIA Portal on every DB the driver reads, recompile, and download. **Track 3 (bridge):** for shops that won't or can't disable Optimized access, run an `OpcUaClient` driver instance against the S7-1500 V2.5+ CPU's onboard OPC UA server (Siemens runtime OPC UA license required). | **Track 2 (custom S7Plus library) is out of scope** unless a customer funds the ≥4-week initial implementation plus ongoing protocol-revision maintenance. Sharp7 / Snap7Net don't help — they are also classic-S7comm-only. | [`docs/v2/s7.md` § Optimized DB constraint](v2/s7.md#optimized-db-constraint-s7plus) · [`docs/drivers/OpcUaClient.md`](drivers/OpcUaClient.md) |
+
+## How to read this table
+
+- **Status** is one of `Open` (work pending), `Decided` (architectural
+  decision made; docs reflect it; no code change planned), or
+  `Closed` (delivered).
+- **Roadmap** captures whether the gap is funded for the next phase. A blank
+  cell means "no roadmap; doc-only outcome."
+- The numeric **#** is stable — new rows append at the bottom and keep their
+  number across deletions/edits so cross-references survive.

docs/v2/focas-deployment.md

@@ -44,6 +44,37 @@ reported wall-clock — keep CNC clocks on UTC so the dedup key
 `(OccurrenceTime, AlarmNumber, AlarmType)` stays stable across DST
 transitions.
 
+## Derived telemetry — issue #272 (plan PR F5-a)
+
+The `Production/` subtree gains two **derived** nodes alongside the four
+F1-b wire-sourced fields:
+
+- `Production/LastCycleSeconds` (`Float64`)
+- `Production/LastCycleStartUtc` (`DateTime` UTC)
+
+**No new wire calls.** Both nodes are computed client-visible from the
+same `cnc_rdparam(6711)` + `cnc_rdtimer` poll the F1-b projection
+already runs on every probe tick. There is no per-device knob — the
+nodes are present for every CNC the driver connects to and surface
+`null` until the second observed parts-count increment produces the
+first delta.
+
+This means:
+
+- **No additional CNC load.** Probe-tick wire traffic is unchanged.
+- **No new opt-in.** The nodes ship enabled by default and are
+  read-only (`SecurityClassification.ViewOnly`); no LDAP group needs
+  the new permission.
+- **Reconnect re-baselines.** Per the FWLIB session boundary the
+  derivation state resets on reconnect / reinit, so the first cycle
+  observed after a reconnect re-establishes the baseline before
+  publishing the first post-reconnect delta.
+
+See [`docs/drivers/FOCAS.md`](../drivers/FOCAS.md) § "Fixed-tree
+`Production/` projection" for the full edge-case behaviour matrix
+(parts-count counter reset, cycle-timer rollover, parts-count jumps
+> 1).
+
 ## Write safety — issue #269 (PARAM/MACRO, F4-b) + issue #270 (PMC, F4-c)
 
 The FOCAS driver supports `cnc_wrparam`, `cnc_wrmacro`, and `pmc_wrpmcrng`

docs/v2/implementation/focas-simulator-plan.md

@@ -304,6 +304,82 @@ Bit-level writes never appear here as a separate kind — they reach the
 simulator as 1-byte writes after the driver's RMW wrapper, so the audit
 shape is identical to a byte write at the same address.
 
+## Cycle-time per part / last cycle delta — F5-a (issue #272)
+
+Plan PR F5-a derives `Production/LastCycleSeconds` +
+`Production/LastCycleStartUtc` from the existing `cnc_rdparam(6711)` +
+`cnc_rdtimer` snapshot stream — **pure derivation, no new wire calls**.
+The simulator does NOT need new wire commands; the existing
+`cnc_rdparam` + `cnc_rdtimer` handlers already cover the read surface.
+
+What focas-mock DOES need is an admin endpoint + test-fixture helper
+that lets integration tests atomically increment the parts-count
+counter alongside the cycle-time timer so the driver sees a clean
+"cycle completed" transition on the next probe tick.
+
+### Per-profile state
+
+Already covered by the existing F1-b state map:
+
+- `parameters: Dict[int, int]` (entry `6711` is the parts-count counter).
+- `timers: Dict[int, int]` (entry `0` is the live cycle-time counter,
+  in seconds).
+
+### Admin endpoint — `POST /admin/mock_simulate_cycle_completion`
+
+Atomically advances both values to model "the CNC just finished a
+cycle". Atomicity matters: the F5-a derivation samples both fields on
+every probe tick, so if the simulator updated parts-count and the
+timer in two separate writes the test could observe an intermediate
+state where parts-count incremented but the timer hasn't updated yet
+(producing a misleading `LastCycleSeconds`).
+
+```
+POST /admin/mock_simulate_cycle_completion
+{
+  "profile": "Series30i",
+  "partsDelta": 1,                  // default 1; tests asserting backfill use 3+
+  "newCycleTimerSeconds": 18        // absolute value, NOT a delta
+}
+```
+
+Handler steps:
+
+1. `parameters[6711] += partsDelta` (under the per-profile lock).
+2. `timers[0] = newCycleTimerSeconds`.
+3. Return `200 OK` with the new values for verification.
+
+The endpoint MUST hold the profile's update lock for the full
+read-modify-write so a concurrent `cnc_rdparam` + `cnc_rdtimer` poll
+sees both fields in their pre-update OR post-update state — never
+half-applied.
+
+### `FocasSimFixture.SimulateCycleCompletionAsync`
+
+The future test-support helper wraps the admin endpoint:
+
+```csharp
+await fixture.SimulateCycleCompletionAsync(
+    profile: "Series30i",
+    partsDelta: 1,
+    newCycleTimerSeconds: 18);
+```
+
+Integration test `Series/CycleDeltaTests.cs` will assert:
+
+- After a 5 -> 6 transition with `newCycleTimerSeconds=18`, the
+  driver's `Production/LastCycleSeconds` settles to `currentTimer -
+  prevTimer`.
+- `Production/LastCycleStartUtc` is within driver-tolerance of
+  `nowUtc - LastCycleSeconds` (allow a small window for probe-tick
+  jitter).
+- Counter reset (parts -> 0) preserves the last published values.
+- Cycle-timer rollover does not publish a negative delta.
+
+These tests are blocked on the focas-mock + integration-test project
+landing; the unit-test coverage in `FocasCycleDeltaTests` already
+exercises every same-process invariant of the derivation.
+
 ### Status
 
 focas-mock simulator has not landed yet (tracked separately from F4-b /

docs/v2/s7.md

@@ -1,5 +1,190 @@
 # Siemens SIMATIC S7 (S7-1200 / S7-1500 / S7-300 / S7-400 / ET 200SP) — Modbus TCP quirks
 
+> **Read first: [Optimized DB constraint (S7Plus)](#optimized-db-constraint-s7plus).**
+> S7netplus, the wire library this driver is built on, speaks classic S7comm
+> only — it cannot read Optimized-block-access DBs on S7-1200 / S7-1500. That
+> is the default in TIA Portal V14+ for new projects. If you skip the section
+> below, every absolute-offset read against a freshly-created S7-1500 project
+> will return `BadDeviceFailure`.
+
+## Optimized DB constraint (S7Plus)
+
+### Symptom
+
+Against a default new S7-1500 TIA Portal project, an absolute-offset read like
+`DB1.DBW0` issued by the OtOpcUa S7 driver returns `BadDeviceFailure` (the
+S7netplus `PlcException` surfaces as `ErrorCode.WrongVarFormat` /
+`ErrorCode.ReadData` depending on firmware revision). No bytes are returned;
+the read never reaches the user data; the failure is identical whether
+PUT/GET is enabled or not.
+
+### Why
+
+The OtOpcUa S7 driver is built on
+[**S7netplus**](https://github.com/S7NetPlus/s7netplus), which implements
+**classic S7comm** only — the protocol historically used by S7-300 / S7-400
+and the legacy "compatibility" path on S7-1200 / S7-1500. Classic S7comm
+addresses DB contents by **absolute byte offset**: `DB1.DBW0` literally means
+"give me 2 bytes starting at byte 0 of DB number 1". This works as long as
+the byte offsets in the program match the byte offsets on the wire.
+
+S7-1200 V4 and S7-1500 introduced **Optimized block access**. When checked,
+the TIA Portal compiler is free to **reorder DB members**, insert padding for
+alignment, and store members in CPU-internal memory that the absolute-offset
+read protocol cannot reach. There are no fixed byte offsets to address — the
+only way to read an Optimized DB is by **symbolic name**, which requires
+**S7Plus** (the post-2014 protocol Siemens uses for TIA-Portal-aware tooling
+and OPC UA gateways).
+
+S7Plus is undocumented by Siemens. A community Wireshark dissector exists
+(`s7comm-plus`), but no production-ready open-source library implements the
+write/subscribe surface end-to-end. **S7netplus does not, and is not on a
+roadmap to, support S7Plus.** Snap7 v2 / Snap7Net and the various Sharp7
+forks are also classic-S7comm-only.
+
+### Default to know about
+
+In **TIA Portal V14 and newer, "Optimized block access" is checked by default
+on every newly-created DB**. A customer who clicks "Add new block → Data
+block → OK" on a fresh S7-1500 project gets an Optimized DB. The driver
+cannot read it.
+
+### Supported workarounds
+
+The OtOpcUa project supports two workarounds. Pick one per deployment.
+
+#### Track 1 — Disable Optimized block access in TIA Portal
+
+Per DB the driver reads:
+
+1. In TIA Portal, open the project tree → `<PLC>` → **Program blocks** →
+   right-click the DB → **Properties**.
+2. In the **Attributes** tab, **uncheck "Optimized block access"**.
+3. **Compile** the program.
+4. **Download** to the PLC (download the changed block; the CPU will go into
+   STOP if the DB layout changed and download-without-reinitialize is
+   refused — schedule a maintenance window).
+
+After this, `DB1.DBW0` and friends address absolute byte offsets again and
+the OtOpcUa S7 driver reads through unmodified.
+
+**Trade-off:** Optimized DBs are slightly faster for *the PLC program
+itself* to access (better alignment, sometimes better cache behaviour) and
+let the compiler add/remove DB members without renumbering offsets in user
+code. Disabling Optimized access trades a tiny amount of CPU-side
+performance and a layout-stability guarantee for absolute-offset wire
+addressability. For DBs that exist only as a Modbus / S7comm gateway buffer
+(common pattern), there is no real downside.
+
+This is the same prerequisite called out in
+["Optimized block access — must be off"](#optimized-block-access--must-be-off)
+and ["Address / DB Mapping → MB_HOLD_REG"](#address--db-mapping) for the
+Modbus-TCP path; the constraint is the same and stems from the same
+absolute-offset-only assumption.
+
+#### Track 3 — Bridge via the OpcUaClient driver against the CPU's onboard OPC UA server
+
+S7-1500 firmware **V2.5 and later** ship with an **integrated OPC UA
+server** running on the CPU's PROFINET port (default port 4840). Once
+enabled in TIA Portal it exposes the entire symbol table — including
+Optimized DBs — through standard OPC UA, by symbolic name. There is no S7
+protocol involved at all from the OtOpcUa side.
+
+Configure the bridge once:
+
+1. **TIA Portal side**:
+   - Open the CPU's properties → **OPC UA** → **General** → check
+     **Activate OPC UA server**.
+   - Set the server port (default 4840) and security policy. For a quick
+     bring-up, allow `None` + `UserName` and create a server certificate;
+     for production, use Basic256Sha256 with a CA-issued cert.
+   - Under **OPC UA** → **Server interfaces**, expose the symbols/tags the
+     OtOpcUa side should see. (Whole-symbol-table exposure works; a
+     curated server interface is more secure and faster.)
+   - Compile and download.
+   - Note: this requires a **runtime OPC UA license on the CPU**
+     (Siemens SIMATIC NET OPC UA server license, typically activated via
+     SIMATIC SUM). The license is per CPU, not per client.
+
+2. **OtOpcUa side** — register an `OpcUaClient` driver instance pointing
+   at the CPU. Minimal `DriverConfig` JSON:
+
+   ```json
+   {
+     "Driver": "OpcUaClient",
+     "Name": "PLC1500_Onboard",
+     "Options": {
+       "EndpointUrl": "opc.tcp://10.0.0.42:4840",
+       "SecurityMode": "SignAndEncrypt",
+       "SecurityPolicy": "Basic256Sha256",
+       "UserName": "OtOpcUa",
+       "Password": "<from secret store>",
+       "WatchModelChanges": true
+     }
+   }
+   ```
+
+   The driver handles browse, read, write, and subscriptions through the
+   CPU's symbolic name space. Optimized DBs Just Work — the CPU resolves
+   names internally, so the wire never sees a byte offset.
+
+See [`docs/drivers/OpcUaClient.md`](../drivers/OpcUaClient.md) for the full
+configuration surface (reverse connect, model-change re-import, failover,
+aggregate functions, redundancy via `ServerUriArray`, etc.).
+
+**When to use Track 3 over Track 1**:
+
+- The DB layout is owned by an upstream Siemens engineering team that won't
+  disable Optimized access (legitimate concern: shared-DB constraints,
+  compile-time member-renumbering, application notes that mandate optimized
+  blocks).
+- The customer already licenses OPC UA on the CPU.
+- Symbolic addressing is preferred end-to-end (no byte-offset bookkeeping
+  in the OtOpcUa tag list; tags survive DB-member additions).
+- S7-300 / S7-400 are out of scope on this CPU (the onboard OPC UA server
+  is S7-1500 V2.5+ only — see V2.5 firmware change list).
+
+**When to use Track 1 over Track 3**:
+
+- The CPU is S7-1200 (no onboard OPC UA server even on the V4 firmware
+  line) or older S7-1500 firmware (< V2.5).
+- The customer won't pay for the SIMATIC NET OPC UA server license on the
+  CPU.
+- The DBs in question exist purely as gateway buffers and have no
+  significant CPU-program access pattern that would benefit from
+  Optimized access.
+
+### Track 2 — out of scope
+
+For completeness, the **Track 2** option that was evaluated and rejected:
+migrate the OtOpcUa S7 driver off S7netplus to a library that speaks
+S7Plus. The candidates were:
+
+- **Snap7 v2 / Snap7Net** — classic S7comm only. Same Optimized-DB
+  limitation. Not a step forward.
+- **Sharp7 community forks** — partial S7-1200 / S7-1500 PUT/GET semantics
+  but still classic-S7comm wire format. Not a step forward.
+- **Custom S7Plus implementation** — possible in principle (the Wireshark
+  `s7comm-plus` dissector covers the wire format), but estimated **≥4
+  weeks** of engineering for a minimal read/write/subscribe surface, plus
+  ongoing maintenance every time Siemens revs the protocol version
+  (which they do silently with each TIA Portal release).
+
+**Track 2 is not on the OtOpcUa roadmap** unless a specific customer funds
+the engineering and ongoing maintenance. Track 1 + Track 3 together cover
+every shipping S7 deployment we have visibility into.
+
+### Pre-flight diagnostics
+
+The driver does not currently auto-detect Optimized DBs from the
+`BadDeviceFailure` shape (the same error code is returned for "DB doesn't
+exist", "DB exists but is too short", etc.). On first encounter of a
+device-failure error, check the suspect DB's properties in TIA Portal
+**before** chasing wire-level theories. The auto-detect would require an
+SZL probe or a symbolic round-trip; tracked but not a v2 deliverable.
+
+---
+
 Siemens S7 PLCs do *not* speak Modbus TCP natively at the OS/firmware level. Every
 S7 Modbus-TCP-server deployment is either (a) the **`MB_SERVER`** library block
 running on the CPU's PROFINET port (S7-1200 / S7-1500 / CPU 1510SP-series
@@ -1030,7 +1215,11 @@ addresses by absolute offset, including UDT-typed DBs.
 
 If a customer can't disable Optimized access (e.g., shared-DB constraints),
 the workaround is to expose the UDT through the symbolic-tag path once that
-ships — not in PR-S7-D2.
+ships — not in PR-S7-D2. See
+[Optimized DB constraint (S7Plus)](#optimized-db-constraint-s7plus) at the
+top of this document for the project-wide decision (Track 1 disable in TIA
+Portal, or Track 3 bridge via the OpcUaClient driver against the CPU's
+onboard OPC UA server).
 
 ### Validation
 
@@ -1068,6 +1257,211 @@ FB-instance DBs imported via PR-S7-D3 / [#301](https://github.com/dohertj2/lmxop
 see [`docs/drivers/S7-TIA-Import.md` "Re-import on FB-interface edit"](../drivers/S7-TIA-Import.md#re-import-on-fb-interface-edit--caveat)
 for the FB-instance-specific workflow.
 
+## CPU diagnostics (SZL)
+
+PR-S7-E1 / [#302](https://github.com/dohertj2/lmxopcua/issues/302) — every S7
+CPU answers SZL (System Status List) queries with metadata about itself: CPU
+type, firmware, order number, scan-cycle min/avg/max, and the diagnostic
+buffer ring. The driver surfaces those through a virtual `@System.*` address
+space dispatched against the SZL sub-protocol — no DB / merker tag declarations
+required.
+
+### Opt-in: `ExposeSystemTags`
+
+Off by default. Set `ExposeSystemTags = true` in `S7DriverOptions` and
+`DiscoverAsync` adds a `Diagnostics/` sub-folder under the driver root with
+the variables listed below. Knobs:
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `ExposeSystemTags` | `false` | Master switch. When `false` the SZL surface is invisible — no extra browse nodes, no extra wire traffic. |
+| `DiagBufferDepth` | `10` | Number of diagnostic-buffer entries to discover under `DiagBuffer/Entry[N]`. Capped at 50. |
+| `SzlCacheTtl` | `5 s` | TTL for the per-driver SZL cache. A burst of `@System.*` reads inside this window reuses one wire response per SZL ID. Set to `TimeSpan.Zero` to disable caching (every read hits the wire). |
+
+### `@System.*` address table
+
+| Address | OPC UA type | SZL ID | Index | What it is |
+| --- | --- | --- | --- | --- |
+| `@System.CpuType` | `String` | `0x0011` | `0x0000` | CPU friendly name (SZL index 0x0007) or MLFB fallback. |
+| `@System.Firmware` | `String` | `0x0011` | `0x0000` | Firmware version, formatted `Vmaj.min.patch`. |
+| `@System.OrderNo` | `String` | `0x0011` | `0x0000` | MLFB / order number, e.g. `6ES7 516-3AN01-0AB0`. |
+| `@System.CycleMs.Min` | `Float64` | `0x0132` | `0x0005` | Shortest scan cycle observed since last reset, in milliseconds. |
+| `@System.CycleMs.Max` | `Float64` | `0x0132` | `0x0005` | Longest scan cycle observed since last reset, in milliseconds. |
+| `@System.CycleMs.Avg` | `Float64` | `0x0132` | `0x0005` | Rolling average scan-cycle time, in milliseconds. |
+| `@System.DiagBuffer.Entry[N]` | `String` | `0x00A0` | `0x0000` | Diagnostic-buffer entry rendered as `<UTC ISO-8601> \| 0x<event id> \| prio=<N> \| <event text>`. `N` ranges from `0` (most recent) through `DiagBufferDepth-1`. |
+
+The diagnostic-buffer entries surface as flat strings rather than a structured
+DataType so dashboards / log scrapers can split / grep them without a custom
+schema.
+
+### What's wired today vs not-supported
+
+S7netplus 0.20 builds SZL request packages internally
+(`SzlReadRequestPackage` / `WriteSzlReadRequest`) but does **not** expose a
+public `ReadSzlAsync` API. Until S7netplus catches up (or we ship a raw S7comm
+PDU helper that side-steps the library), the production
+[`S7NetSzlReader`](../../src/ZB.MOM.WW.OtOpcUa.Driver.S7/Szl/S7NetSzlReader.cs)
+returns `null` on every call and every `@System.*` read surfaces as
+`BadNotSupported`. The browse tree still lights up — operators can wire
+clients against it — only the values come back not-supported.
+
+The parser code (`S7SzlParser`) is fully tested against golden bytes
+regardless. Flipping the wire path on is a one-method change in
+`S7NetSzlReader` once the upstream surface is available; no parser / dispatch
+/ cache changes needed.
+
+snap7 (the simulator backing the integration profile) also doesn't implement
+SZL — the integration test
+[`S7_1500SzlTests`](../../tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/S7_1500/S7_1500SzlTests.cs)
+asserts the not-supported semantics against snap7 + parks the live-firmware
+test behind `[Fact(Skip = ...)]` until the wire path lights up.
+
+### Caching
+
+Diagnostics shouldn't poll faster than `SzlCacheTtl` — a 100 ms HMI
+subscription on every `@System.*` tag would otherwise hammer the comms
+mailbox for data that doesn't change between scans. The per-driver
+[`S7SzlCache`](../../src/ZB.MOM.WW.OtOpcUa.Driver.S7/Szl/S7SzlCache.cs)
+de-dups concurrent reads by `(SzlId, SzlIndex)`; one SZL 0x0011 round-trip
+backs `CpuType` + `Firmware` + `OrderNo` for the whole TTL window. Negative
+results (SZL not supported) are cached just as aggressively — repeatedly
+hammering a CPU that already said "not supported" wouldn't help.
+
+`SzlCacheTtl = TimeSpan.Zero` disables caching entirely; useful for
+diagnostics tests where you want every read to hit the wire.
+
+### JSON config example
+
+```json
+{
+  "DriverConfig": {
+    "Host": "192.168.10.50",
+    "Port": 102,
+    "CpuType": "S71500",
+    "ExposeSystemTags": true,
+    "DiagBufferDepth": 20,
+    "SzlCacheTtl": "00:00:05"
+  }
+}
+```
+
+## PLC password / protection levels
+
+PR-S7-E2 (issue #303) adds a connection-level password option for hardened
+deployments. The driver emits the password to the PLC immediately after
+`OpenAsync` succeeds and before the pre-flight PUT/GET probe runs (the same
+pre-flight read that would otherwise be the first operation a hardened CPU
+refuses).
+
+### Options
+
+| Option            | Default          | Purpose                                                                                                                                                                                                                                |
+| ----------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Password`        | `null`           | Connection-level password. Secret — never logged. `null` or empty = no password is sent.                                                                                                                                              |
+| `ProtectionLevel` | `Auto`           | Declarative hint about the PLC's protection scheme. One of `Auto`, `None`, `Level1`, `Level2`, `Level3` (S7-300/400 SFC 109/110 levels), or `ConnectionMechanism` (S7-1200/1500 TIA Portal "Protection & Security" pane).             |
+
+### S7-300 / S7-400 protection levels (1, 2, 3)
+
+S7-300/400 firmware exposes three CPU-side protection levels:
+
+* **Level 1** — write protection. Reads work without a password; writes
+  (parameter, DB, M/Q changes) require an unlock.
+* **Level 2** — read and write protection. Both kinds of operation require
+  the password.
+* **Level 3** — full protection. Even online presence detection / status
+  list reads require the password.
+
+Set `ProtectionLevel = Level1` / `Level2` / `Level3` and supply
+`Password` to match the level configured in the CPU's HW Config dialog.
+The level value is descriptive — the driver doesn't switch behaviour
+between Level1/2/3, since the wire-side `SendPassword` is the same call
+in all three cases. The hint surfaces in the driver-diagnostics RPC so a
+"PLC said Level 3 but config says Level 1" mismatch is spottable from the
+Admin UI.
+
+### S7-1200 / S7-1500 connection mechanism
+
+S7-1200/1500 firmware uses a different gate: TIA Portal's "Protection &
+Security" pane has a single **Connection Mechanism** dropdown that, when
+set to anything stricter than "No access", requires every PG/HMI/SCADA
+connection to authenticate after the COTP handshake. The wire-level
+exchange is the same `SendPassword` call but the diagnostic flag is
+distinct, so set `ProtectionLevel = ConnectionMechanism` for these
+families.
+
+### No-log invariant
+
+`Password` is a secret. The driver MUST NOT include the password value in
+log lines, exception messages, or diagnostic surfaces. Specifically:
+
+* `S7DriverOptions.ToString()` redacts the field as `***`.
+* `S7Driver`'s success log line is `S7 password sent for {Host}` —
+  identifier-only, no value.
+* The "S7netplus does not expose SendPassword" warning logs the host name
+  and driver instance ID only, never the password.
+* Authentication-failure exceptions wrap the inner `S7.Net.PlcException`
+  but their own message says only "S7 password authentication failed for
+  host '{Host}'" — no password value.
+
+Any new logging surface that flows an `S7DriverOptions` value MUST
+continue to redact. See the FOCAS-F4-d
+`docs/v2/focas-deployment.md` § "FOCAS password handling" entry for the
+sister no-log discipline on the FOCAS driver.
+
+### Library limitation — S7netplus 0.20
+
+**S7netplus 0.20.0 (the pinned dependency) does not expose a public
+`SendPassword` method.** The driver discovers the method reflectively
+(checking for `SendPasswordAsync(string, CancellationToken)` first, then
+`SendPassword(string)`) so a future minor release that ships the API
+will be picked up automatically without a code change here.
+
+Until the upstream lands, configuring `Password` on a hardened CPU
+produces this Init-time warning:
+
+```
+[Warning] S7 password is set on driver '<DriverInstanceId>' against
+host '<Host>', but the linked S7netplus library does not expose
+SendPassword; password is being ignored at the wire. Hardened-CPU
+connect may fail at first read.
+```
+
+Init still completes — the COTP/S7comm handshake itself doesn't require
+the password — but the first read against a hardened CPU will surface
+`BadDeviceFailure` because PUT/GET-disabled and "level-3 protection"
+return identical "function not allowed" PDUs at the wire layer.
+
+If your S7-1200/1500 deployment requires `ConnectionMechanism`, the
+near-term workarounds are:
+
+1. **Lower the protection setting** in TIA Portal's Protection & Security
+   pane to "Full access (no protection)" for the duration of the
+   evaluation.
+2. **Configure a separate non-hardened connection** on a CP module that
+   the driver can target while keeping the production endpoint hardened.
+3. **Track upstream S7netplus** for a `SendPassword` PR (the package owner
+   has discussed adding it; see issue
+   <https://github.com/S7NetPlus/s7netplus/issues>).
+
+For S7-300/400 CPUs, levels 1 and 2 leave at least *read* access open
+without a password, so most monitoring use cases work without
+`SendPassword` until the library catches up — only Level 3 and the
+S7-1200/1500 ConnectionMechanism require the wire-level unlock.
+
+### JSON config example
+
+```json
+{
+  "DriverConfig": {
+    "Host": "192.168.10.50",
+    "Port": 102,
+    "CpuType": "S71500",
+    "Password": "tia-portal-set-password",
+    "ProtectionLevel": "ConnectionMechanism"
+  }
+}
+```
+
 ## References
 
 1. Siemens Industry Online Support, *Modbus/TCP Communication between SIMATIC S7-1500 / S7-1200 and Modbus/TCP Controllers with Instructions `MB_CLIENT` and `MB_SERVER`*, Entry ID 102020340, V6 (Feb 2021). https://cache.industry.siemens.com/dl/files/340/102020340/att_118119/v6/net_modbus_tcp_s7-1500_s7-1200_en.pdf

docs/v3/twincat-eventlogger-spike.md

@@ -0,0 +1,101 @@
+# TC3 EventLogger spike — managed-wrapper investigation
+
+**Question (b) from the PR 5.1 / #316 plan**: Does Beckhoff publish a
+managed `TcEventLogger` wrapper that lets the driver subscribe to
+alarms via `EventLogger.AlarmRaised` instead of decoding AMS port 110
+notifications by hand?
+
+## TL;DR
+
+**No managed wrapper.** The `Beckhoff.TwinCAT.Ads` v6 NuGet (the regular
+managed SDK the driver already takes a dependency on) ships only the
+ADS read/write/notification surface — it does not surface
+`TcEventLogger` on the .NET side. The C++ TcCOM headers
+(`TcEventLogger.h` etc.) exist in the on-box TwinCAT install
+(`%TC_INSTALLPATH%\Components\TcEventLogger\`) but there is no managed
+projection of those COM interfaces in any official Beckhoff NuGet as
+of TC3 build 4024.x.
+
+Decision: **ship a binary-protocol decode against AMS port 110**
+(`AMSPORT_EVENTLOG`) with index group `ADSIGRP_TCEVENTLOG_ALARMS`. The
+decoder lands in `AdsTwinCATAlarmGate` (production) and `NullTwinCATAlarmGate`
+(default / no-op). Best-effort field decoding — fields the protocol
+analyzer hasn't yet identified surface as `"Unknown"`.
+
+## What was checked
+
+| Source | Result |
+| --- | --- |
+| `Beckhoff.TwinCAT.Ads` v6.x NuGet, namespace inventory | `TwinCAT.Ads`, `TwinCAT.Ads.SumCommand`, `TwinCAT.Ads.TypeSystem`, `TwinCAT.TypeSystem`. **No** `TcEventLogger` namespace. |
+| `Beckhoff.TwinCAT.Ads.TcpRouter` v6.x NuGet | Router only; no EventLogger surface. |
+| Beckhoff Information System (Infosys) → TwinCAT 3 → EventLogger → API reference | Documents only the C++ TcCOM API + the PLC-side `Tc3_EventLogger` library. No managed-language section. |
+| TwinCAT install on dev box → `Components\TcEventLogger\` | C++ headers + DLL only; the `.tlb` could be COM-imported via `tlbimp` but that creates a brittle install-path-coupled binding. |
+| Public Beckhoff GitHub orgs | `Beckhoff/TwinCAT-Tools-Library` etc. — no managed EventLogger wrapper. |
+
+## Why decode at the wire?
+
+A `tlbimp` projection of the on-box TcCOM `.tlb` would technically work
+but introduces three problems:
+
+1. **Install-path coupling** — the `.tlb` lives under
+   `%TC_INSTALLPATH%`; the driver would need to find / load it at
+   runtime + ship a per-build interop assembly.
+2. **Bitness lock-in** — TcCOM is x86; the driver builds AnyCPU.
+3. **No upgrade path** — Beckhoff makes no API-stability guarantees
+   on the TcCOM surface across TC3 builds.
+
+Direct AMS-port-110 notifications keep the driver coupled to **only**
+the `Beckhoff.TwinCAT.Ads` v6 NuGet's stable wire surface. Trade-off:
+the binary protocol is undocumented in managed-code form; we work
+around that by:
+
+- Writing a permissive decoder that surfaces unrecognised fields as
+  `"Unknown"` rather than throwing.
+- Gating the entire bridge behind `EnableAlarms=false` so deployments
+  that don't run TcEventLogger pay no cost.
+- Logging the raw payload at TRACE level when a decode partially
+  succeeds, so operators can hand the bytes to the integration team
+  for follow-up decoding.
+
+## What ships in PR 5.1
+
+- `ITwinCATAlarmGate` interface — driver-internal seam.
+- `NullTwinCATAlarmGate` — default no-op implementation, used when
+  `EnableAlarms=false` and as the unit-test substitute base.
+- `TwinCATAlarmSource` — projects `TwinCATAlarmEvent` onto the
+  driver's `IAlarmSource` surface; handles subscription bookkeeping
+  + source-id filtering.
+- `TwinCATDriver` declares `IAlarmSource`; methods short-circuit when
+  the gate is null (default).
+- Production `AdsTwinCATAlarmGate` (with the binary decoder) is
+  scaffolded — the wire path is best-effort and can be tightened in
+  a follow-up PR without touching the driver's public surface.
+
+## Open questions for the follow-up PR
+
+1. **Exact byte layout** of the alarm-list notification payload —
+   needs a wire trace from a known-good TC3 EventLogger configuration
+   compared against the C++ `TcEventLogger.h` struct definitions.
+2. **Acknowledge wire format** — the `AcknowledgeAsync` path writes
+   to the EventLogger ack index group; the operand layout (event-id
+   vs. condition-id mapping) is best-effort in PR 5.1.
+3. **Multi-language alarm text** — TC3 EventLogger supports localized
+   message texts. The decoder should pick the runtime's configured
+   language; PR 5.1 falls back to the first text it finds.
+4. **Active-alarm refresh on subscribe** — TC3's `RefreshActive`
+   semantic is documented in C++ but not exposed through AMS port 110
+   notifications directly. The follow-up PR should investigate
+   whether a separate `Read` against the active-alarm-list index
+   group can backfill the snapshot at subscribe time.
+
+## Why land PR 5.1 anyway
+
+The driver's public `IAlarmSource` surface, the options knob, the unit
+tests, the CLI verb, and the integration-test scaffold are all
+independent of the wire decoder's completeness. Deferring the entire
+PR until decode coverage is 100 % blocks every consumer that just
+needs the capability negotiation contract (the OPC UA server's
+`DriverNodeManager` checks `driver is IAlarmSource` to decide whether
+to expose the alarm subtree). Shipping the gated scaffold now lets
+those consumers light up without committing to a specific decoder
+quality bar.

scripts/e2e/e2e-config.sample.json

@@ -60,6 +60,12 @@
         "historyLookbackSec": 3600
     },
 
+    "opcuaclient": {
+        "$comment": "Optional upstream-redundancy probe (PR-14). When both primaryUrl and secondaryUrl are set, test-opcuaclient.ps1 runs an extra bridged read while both upstreams are reachable. Leave keys absent to skip the redundancy stage. The OtOpcUa server's DriverConfig for the OpcUaClient instance must already have Redundancy.Enabled=true + the same EndpointUrls list; this script doesn't reconfigure the driver.",
+        "primaryUrl": "opc.tcp://localhost:50000",
+        "secondaryUrl": "opc.tcp://localhost:50002"
+    },
+
     "phase7": {
         "$comment": "Virtual tags + scripted alarms. The VirtualNodeId must resolve to a server-side virtual tag whose script reads the modbus InputNodeId and writes VT = input * 2. The AlarmNodeId is the ConditionId of a scripted alarm that fires when VT > 100.",
         "modbusEndpoint": "127.0.0.1:5502",

scripts/e2e/test-ablegacy.ps1

@@ -39,6 +39,31 @@
   client may have bumped it by more, so the comparison is `>=`). NodeId form:
   ns=<n>;s=AbLegacy/<gateway>/_Diagnostics/RequestCount. Mirrors the
   -SystemConnectionStatusNodeId knob on test-abcip.ps1.
+
+.PARAMETER DiagnosticsDemoteCountNodeId
+  Optional NodeId for the synthetic _Diagnostics/<host>/DemoteCount variable
+  emitted by AB Legacy discovery (PR ablegacy-12 / #255). When supplied, the
+  script runs the auto-demote assertion: kills the simulator container so
+  reads start failing, hammers the user-tag BridgeNodeId at least
+  FailureThreshold times to trip the demotion, then reads the diagnostic
+  counter and asserts the value increased by >= 1. NodeId form:
+  ns=<n>;s=AbLegacy/<gateway>/_Diagnostics/DemoteCount. The simulator
+  must support `docker stop otopcua-ab-server-slc500` for the kill stage.
+
+.PARAMETER FailureThresholdForDemote
+  Failure threshold the server is configured with (default 3). The
+  demote assertion writes/reads N+1 times against the killed simulator
+  to guarantee the threshold trips even if some reads beat the kill.
+
+.PARAMETER DhPlusStation
+  PR ablegacy-13 / #256 — DH+ node address (octal 0..77 == decimal 0..63)
+  of a PLC-5 reachable through a 1756-DHRIO module. **Documentation
+  parameter only — there is no automated assertion**: libplctag's ab_server
+  does not simulate the DHRIO + DH+ + PLC-5 stack, so wire-level coverage
+  requires real hardware. When supplied alongside a `-Gateway` of the form
+  `ab://<host>/1,<slot>,2,<station-octal>` and `-PlcType Plc5`, the value
+  here is recorded in the run log so reproducibility is auditable. See
+  docs/drivers/AbLegacy-DH-Bridging.md for the manual smoke procedure.
 #>
 
 param(
@@ -47,7 +72,13 @@ param(
     [string]$Address = "N7:5",
     [string]$OpcUaUrl = "opc.tcp://localhost:4840",
     [Parameter(Mandatory)] [string]$BridgeNodeId,
-    [string]$DiagnosticsRequestCountNodeId
+    [string]$DiagnosticsRequestCountNodeId,
+    [string]$DiagnosticsDemoteCountNodeId,
+    [int]$FailureThresholdForDemote = 3,
+    # PR ablegacy-13 / #256 — DH+ station via 1756-DHRIO bridging. Doc-only:
+    # no automated assertion (no Docker fixture covers DH+). See script header
+    # comment + docs/drivers/AbLegacy-DH-Bridging.md.
+    [string]$DhPlusStation
 )
 
 $ErrorActionPreference = "Stop"
@@ -245,5 +276,67 @@ finally {
     Remove-Item -Path $importJsonPath -ErrorAction SilentlyContinue
 }
 
+# PR ablegacy-12 / #255 — auto-demote round-trip. Kill the simulator container,
+# hammer the bridge NodeId past the failure threshold, then assert the
+# DemoteCount diagnostic incremented. Restart the simulator at the end so the
+# next run gets a clean baseline. Gated on -DiagnosticsDemoteCountNodeId so
+# environments without docker-side control of the simulator can opt out.
+if ($DiagnosticsDemoteCountNodeId) {
+    Write-Header "AutoDemote (kill simulator + observe DemoteCount from $DiagnosticsDemoteCountNodeId)"
+    $baselineDemoteOut = & $opcUaCli.File @($opcUaCli.PrefixArgs) `
+        @("read", "-u", $OpcUaUrl, "-n", $DiagnosticsDemoteCountNodeId) 2>&1
+    $baselineDemote = 0
+    if (($baselineDemoteOut -join "`n") -match '(\d+)') { $baselineDemote = [int64]$Matches[1] }
+
+    # Best-effort container kill — prefer the slc500 profile name; fall back to
+    # micrologix / plc5 in case the operator pointed the e2e at a different family.
+    $simContainers = @("otopcua-ab-server-slc500", "otopcua-ab-server-micrologix", "otopcua-ab-server-plc5")
+    $killed = $false
+    foreach ($c in $simContainers) {
+        $stop = docker stop $c 2>$null
+        if ($LASTEXITCODE -eq 0 -and $stop) {
+            Write-Host "Stopped $c"
+            $killed = $true
+            break
+        }
+    }
+    if (-not $killed) {
+        Write-Fail "AutoDemote: no ab_server container found via 'docker stop' — skipping demote assertion"
+        $results += @{ Passed = $false; Reason = "no simulator container to kill" }
+    }
+    else {
+        # Hammer past the threshold. Each read against a now-unreachable simulator
+        # surfaces BadCommunicationError; FailureThreshold consecutive ones trip
+        # the demotion. We add 2 extra to absorb timing slack (one read may be
+        # in-flight when the kill lands).
+        $hammerCount = $FailureThresholdForDemote + 2
+        for ($i = 0; $i -lt $hammerCount; $i++) {
+            & $opcUaCli.File @($opcUaCli.PrefixArgs) `
+                @("read", "-u", $OpcUaUrl, "-n", $BridgeNodeId) 2>&1 | Out-Null
+        }
+
+        Start-Sleep -Seconds 1
+
+        $afterDemoteOut = & $opcUaCli.File @($opcUaCli.PrefixArgs) `
+            @("read", "-u", $OpcUaUrl, "-n", $DiagnosticsDemoteCountNodeId) 2>&1
+        $afterDemote = 0
+        if (($afterDemoteOut -join "`n") -match '(\d+)') { $afterDemote = [int64]$Matches[1] }
+
+        $deltaDemote = $afterDemote - $baselineDemote
+        if ($deltaDemote -ge 1) {
+            Write-Pass "AutoDemote DemoteCount delta $deltaDemote >= 1 after $hammerCount failed reads"
+            $results += @{ Passed = $true }
+        } else {
+            Write-Fail "AutoDemote DemoteCount delta $deltaDemote < 1 (baseline=$baselineDemote after=$afterDemote)"
+            $results += @{ Passed = $false; Reason = "demote delta $deltaDemote" }
+        }
+
+        # Restart the simulator so subsequent test runs have a clean baseline.
+        # Best-effort — if docker-compose isn't on the path the operator can
+        # bring it back manually via the Docker/docker-compose.yml profile.
+        try { docker start (docker ps -aq -f "name=otopcua-ab-server-") | Out-Null } catch { }
+    }
+}
+
 Write-Summary -Title "AB Legacy e2e" -Results $results
 if ($results | Where-Object { -not $_.Passed }) { exit 1 }

scripts/e2e/test-opcuaclient.ps1

@@ -86,7 +86,24 @@ param(
     [string]$UpstreamNodeId = "ns=3;s=StepUp",
     [int]$ChangeWaitSec = 10,
     [switch]$ReverseConnect,
-    [string]$ReverseListenerUrl = "opc.tcp://0.0.0.0:4844"
+    [string]$ReverseListenerUrl = "opc.tcp://0.0.0.0:4844",
+    # PR-12: HistoryReadEvents passthrough check. Requires the upstream to be running
+    # in alarm-history mode (opc-plc --alm) AND the OtOpcUa server to expose a notifier
+    # node bridged to the upstream's events source. The CLI doesn't have a dedicated
+    # event-history command yet; this stage runs a regular historyread against the
+    # bridged notifier and confirms the gateway round-trips the request without
+    # surfacing BadHistoryOperationUnsupported, which would indicate the filter-aware
+    # ReadEventsAsync path lost wiring.
+    [switch]$HistoryEvents,
+    [string]$EventsNotifierNodeId = "i=2253",
+    # PR-14: upstream-redundancy probe. Passes the primary + secondary URLs
+    # straight through to the gateway driver via DriverConfig (operator must have
+    # already wired Redundancy.Enabled=true on the OpcUaClient instance — this
+    # script doesn't reconfigure the driver, only verifies the bridged read still
+    # works while both upstreams are reachable, and that the driver's redundancy
+    # diagnostics are non-null). Stage is no-op when neither URL is provided.
+    [string]$PrimaryUrl,
+    [string]$SecondaryUrl
 )
 
 $ErrorActionPreference = "Stop"
@@ -164,6 +181,55 @@ if ($triggerCmd) {
     $results += [pscustomobject]@{ Stage = "Topology-change"; Status = "SKIP" }
 }
 
+# Stage 5 (gated): HistoryReadEvents passthrough
+#
+# PR-12 lands the filter-aware IHistoryProvider.ReadEventsAsync overload on the
+# OPC UA Client driver. End-to-end coverage requires:
+#   (a) the upstream in alarm-history mode (opc-plc --alm or a real server);
+#   (b) the OtOpcUa server forwarding HistoryReadEvents to the gateway driver.
+# Gated behind -HistoryEvents because the default opc-plc fixture image isn't
+# launched with --alm. When set, the stage issues a historyread against the
+# bridged notifier ($EventsNotifierNodeId) and confirms the gateway returns
+# the request without BadHistoryOperationUnsupported.
+# Stage 6 (gated): upstream-redundancy probe (PR-14)
+#
+# When -PrimaryUrl + -SecondaryUrl are both supplied, the script runs an extra
+# read against the bridged NodeId and reports whether the gateway is still
+# answering. The actual ServiceLevel-driven failover is observable only on the
+# server side (driver-diagnostics RPC reports RedundancyFailoverCount); this
+# stage is a smoke check that the bridged path keeps round-tripping while
+# both upstreams are reachable. Drive a real failover by writing to the
+# primary's ServiceLevel node from outside this script.
+if ($PrimaryUrl -and $SecondaryUrl) {
+    Write-Host "[INFO] Upstream redundancy probe: primary=$PrimaryUrl secondary=$SecondaryUrl"
+    $results += Test-Probe `
+        -Name "OpcUaClient redundancy bridged-read" `
+        -Cmd $opcUaCli `
+        -Args @("read", "-u", $OpcUaUrl, "-n", $BridgedNodeId)
+} else {
+    if (-not $PrimaryUrl -and -not $SecondaryUrl) {
+        Write-Host "[INFO] Upstream redundancy stage skipped (set -PrimaryUrl and -SecondaryUrl to enable)."
+        $results += [pscustomobject]@{ Stage = "Upstream-redundancy"; Status = "SKIP" }
+    }
+}
+
+if ($HistoryEvents) {
+    Write-Host "[INFO] HistoryEvents stage: issuing historyread against $EventsNotifierNodeId"
+    $start = (Get-Date).ToUniversalTime().AddMinutes(-30).ToString("o")
+    $end   = (Get-Date).ToUniversalTime().AddMinutes(1).ToString("o")
+    $eventOut = & $opcUaCli.Cmd @($opcUaCli.Args + @(
+        "historyread", "-u", $OpcUaUrl, "-n", $EventsNotifierNodeId,
+        "--start", $start, "--end", $end))
+    if ($LASTEXITCODE -eq 0 -and $eventOut -notmatch "BadHistoryOperationUnsupported") {
+        $results += [pscustomobject]@{ Stage = "HistoryReadEvents"; Status = "PASS" }
+    } elseif ($eventOut -match "BadHistoryOperationUnsupported") {
+        Write-Host "[INFO] Upstream returned BadHistoryOperationUnsupported — re-run with --alm + a notifier that has event history."
+        $results += [pscustomobject]@{ Stage = "HistoryReadEvents"; Status = "SKIP" }
+    } else {
+        $results += [pscustomobject]@{ Stage = "HistoryReadEvents"; Status = "FAIL" }
+    }
+}
+
 Write-Host ""
 Write-Host "=== test-opcuaclient.ps1 results ==="
 $results | Format-Table -AutoSize

scripts/smoke/seed-ablegacy-smoke.sql

@@ -96,7 +96,12 @@ VALUES (@Gen, @DrvId, @ClusterId, @NsId, 'ablegacy-smoke', 'AbLegacy', N'{
       "PlcFamily": "Slc500",
       "DeviceName": "slc-500",
       "TimeoutMs": 500,
-      "Retries": 1
+      "Retries": 1,
+      "Demote": {
+        "FailureThreshold": 3,
+        "DemoteForMs": 30000,
+        "Enabled": true
+      }
     }
   ],
   "Probe": { "Enabled": true, "IntervalMs": 5000, "TimeoutMs": 2000, "ProbeAddress": "S:0" },
@@ -155,7 +160,15 @@ PRINT '      e.g. "ab://<plc-ip>:44818/" and re-run this seed.';
 PRINT '';
 PRINT 'PR ablegacy-10 / #253 — diagnostic counters auto-emit per device under';
 PRINT '   AbLegacy/<host>/_Diagnostics/<name>. No dbo.Tag rows needed — the';
-PRINT '   driver registers them at DiscoverAsync time. Seven counters per device:';
+PRINT '   driver registers them at DiscoverAsync time. Nine counters per device:';
 PRINT '   RequestCount, ResponseCount, ErrorCount, RetryCount, LastErrorCode,';
-PRINT '   LastErrorMessage, CommFailures. See docs/drivers/AbLegacy-Diagnostics.md';
+PRINT '   LastErrorMessage, CommFailures, DemoteCount, LastDemotedUtc. See';
-PRINT '   for the full surface + reset semantics.';
+PRINT '   docs/drivers/AbLegacy-Diagnostics.md for the full surface + reset';
+PRINT '   semantics.';
+PRINT '';
+PRINT 'PR ablegacy-12 / #255 — auto-demote on comm failure: 3 consecutive';
+PRINT '   failed reads / probes mark the device Demoted for DemoteFor=PT30S';
+PRINT '   (30 s); reads against a demoted device short-circuit with';
+PRINT '   BadCommunicationError so one slow PLC can''t starve the driver.';
+PRINT '   Tune via the Demote block on each Devices[] row. DemoteCount +';
+PRINT '   LastDemotedUtc on the _Diagnostics folder surface flapping links.';

src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IHistoryProvider.cs

@@ -76,8 +76,107 @@ public interface IHistoryProvider
         => throw new NotSupportedException(
             $"{GetType().Name} does not implement ReadEventsAsync. " +
             "Drivers whose backends have an event historian override this method.");
+
+    /// <summary>
+    ///     Filter-aware historical event read — OPC UA HistoryReadEvents service with full
+    ///     <c>EventFilter</c> support (SelectClauses + WhereClause). Distinct from the simpler
+    ///     <see cref="ReadEventsAsync(string?, DateTime, DateTime, int, CancellationToken)"/>
+    ///     overload which is sufficient for "give me the standard BaseEventType fields"
+    ///     queries; this overload is for clients that send a custom <c>EventFilter</c> on the
+    ///     wire (per-select-clause Variant population, where-filter evaluation).
+    /// </summary>
+    /// <param name="fullReference">
+    ///     Driver-specific node identifier. May be a notifier object (e.g. the driver-root
+    ///     folder) — drivers that support cluster-wide queries treat it as
+    ///     "all sources in the namespace".
+    /// </param>
+    /// <param name="request">Filter spec — time range + select clauses + optional where clause.</param>
+    /// <param name="cancellationToken">Request cancellation.</param>
+    /// <remarks>
+    ///     <para>
+    ///         Default implementation throws — drivers opt in by overriding. Existing drivers
+    ///         that only handle the parameterless overload stay green; new drivers that need
+    ///         filter-aware event history (OPC UA Client passthrough, future event-historian
+    ///         backends) override this method.
+    ///     </para>
+    ///     <para>
+    ///         The OPC UA Client driver implements this by translating <see cref="EventHistoryRequest"/>
+    ///         into <c>ReadEventDetails</c> and calling <c>Session.HistoryReadAsync</c> against
+    ///         the upstream server.
+    ///     </para>
+    /// </remarks>
+    Task<HistoricalEventBatch> ReadEventsAsync(
+        string fullReference,
+        EventHistoryRequest request,
+        CancellationToken cancellationToken)
+        => throw new NotSupportedException(
+            $"{GetType().Name} does not implement filter-aware ReadEventsAsync(EventHistoryRequest). " +
+            "Drivers whose backends carry historical events with EventFilter support override this method.");
 }
 
+/// <summary>
+///     Filter spec for the filter-aware <see cref="IHistoryProvider.ReadEventsAsync(string, EventHistoryRequest, CancellationToken)"/>
+///     overload. Mirrors the OPC UA <c>ReadEventDetails</c> wire shape (StartTime, EndTime,
+///     NumValuesPerNode, EventFilter) but transport-neutral so non-UA drivers can implement it
+///     without taking a dependency on the UA SDK type.
+/// </summary>
+/// <param name="StartTime">Inclusive lower bound on event time.</param>
+/// <param name="EndTime">Exclusive upper bound on event time.</param>
+/// <param name="NumValuesPerNode">Maximum events per node (0 = no driver-side cap, server may still apply one).</param>
+/// <param name="SelectClauses">
+///     Per-field projection. Each entry names a BaseEventType-rooted field (or a
+///     typed-path field via <see cref="SimpleAttributeSpec.TypeDefinitionId"/>) the caller
+///     wants returned. <c>null</c> means "use the driver's default field set" — typically
+///     EventId, SourceName, Time, Message, Severity, ReceiveTime.
+/// </param>
+/// <param name="WhereClause">
+///     Optional content-filter restriction (e.g. <c>EventType OfType AlarmConditionType</c>).
+///     Drivers may ignore the where clause if their backend doesn't support it; that's a
+///     best-effort projection rather than a hard error.
+/// </param>
+public sealed record EventHistoryRequest(
+    DateTime StartTime,
+    DateTime EndTime,
+    uint NumValuesPerNode,
+    IReadOnlyList<SimpleAttributeSpec>? SelectClauses,
+    ContentFilterSpec? WhereClause);
+
+/// <summary>
+///     Transport-neutral mirror of OPC UA's <c>SimpleAttributeOperand</c> — picks one field
+///     from a node by typed browse path. <see cref="TypeDefinitionId"/> is the OPC UA NodeId
+///     of the type that the path is rooted at (e.g. <c>BaseEventType</c>); <see cref="BrowsePath"/>
+///     is a sequence of QualifiedName-style segments (<c>"ns:Name"</c> or just <c>"Name"</c>
+///     when ns=0). An empty <see cref="BrowsePath"/> means "the node itself".
+/// </summary>
+/// <param name="TypeDefinitionId">
+///     Type the path is rooted at. <c>null</c> defaults to the OPC UA <c>BaseEventType</c>
+///     when the driver has a UA mapping. Format is driver-specific NodeId text (e.g.
+///     <c>"i=2041"</c> for BaseEventType).
+/// </param>
+/// <param name="BrowsePath">Browse-path segments. Empty list = the typed node itself.</param>
+/// <param name="FieldName">
+///     Stable key the driver uses when populating <see cref="HistoricalEventRow.Fields"/>. The
+///     server-side dispatcher uses this to align the returned values with the wire-side
+///     SelectClause order, even when a driver doesn't honour the BrowsePath verbatim.
+/// </param>
+public sealed record SimpleAttributeSpec(
+    string? TypeDefinitionId,
+    IReadOnlyList<string> BrowsePath,
+    string FieldName);
+
+/// <summary>
+///     Transport-neutral mirror of OPC UA's <c>ContentFilter</c>. The current shape carries the
+///     raw filter operands as opaque OPC UA <c>ExtensionObject</c> bytes — drivers that need to
+///     evaluate the filter (Galaxy historian) parse it themselves; the OPC UA Client driver
+///     forwards it untouched. A future PR may replace this with a structured AST when more
+///     than one driver needs to evaluate where-clauses locally.
+/// </summary>
+/// <param name="EncodedOperands">
+///     Optional binary-encoded <c>ContentFilter</c> from the wire. <c>null</c> when no
+///     where-clause was supplied.
+/// </param>
+public sealed record ContentFilterSpec(byte[]? EncodedOperands);
+
 /// <summary>Result of a HistoryRead call.</summary>
 /// <param name="Samples">Returned samples in chronological order.</param>
 /// <param name="ContinuationPoint">Opaque token for the next call when more samples are available; null when complete.</param>
@@ -85,20 +184,116 @@ public sealed record HistoryReadResult(
     IReadOnlyList<DataValueSnapshot> Samples,
     byte[]? ContinuationPoint);
 
-/// <summary>Aggregate function for processed history reads. Mirrors OPC UA Part 13 standard aggregates.</summary>
+/// <summary>
+///     Aggregate function for processed history reads. Mirrors the OPC UA Part 13 §5
+///     standard aggregate catalog. Each value maps 1:1 onto an
+///     <c>Opc.Ua.ObjectIds.AggregateFunction_*</c> NodeId — the OPC UA Client driver does the
+///     translation in <c>OpcUaClientDriver.MapAggregateToNodeId</c>; other drivers either
+///     evaluate the aggregate locally (Galaxy historian) or surface
+///     <c>BadAggregateNotSupported</c> for the values their backend can't honour.
+/// </summary>
+/// <remarks>
+///     <para>
+///         <b>Stable ordinals.</b> The first 5 values (<see cref="Average"/>..<see cref="Count"/>)
+///         carry ordinals 0-4 from the original PR — additions are appended to keep prior
+///         persisted enums (config files, Admin UI dropdowns) compatible.
+///     </para>
+///     <para>
+///         <b>Server-side support.</b> Not every upstream OPC UA server implements every
+///         Part 13 aggregate. Implementations advertise their support through
+///         <c>AggregateConfiguration</c> on the Server object; clients can probe it at runtime.
+///         Aggregates that the upstream rejects come back with
+///         <c>StatusCode=BadAggregateNotSupported</c> on the per-row HistoryRead result —
+///         the driver passes that through verbatim (cascading-quality rule, Part 11 §8).
+///     </para>
+/// </remarks>
 public enum HistoryAggregateType
 {
+    // ---- Original 5 (ordinals 0-4 — keep stable) ----
+    /// <summary>Average of all values in the interval. Part 13 §5.4.</summary>
     Average,
+    /// <summary>Minimum value in the interval. Part 13 §5.5.</summary>
     Minimum,
+    /// <summary>Maximum value in the interval. Part 13 §5.6.</summary>
     Maximum,
+    /// <summary>Sum of values in the interval (numeric only). Part 13 §5.10.</summary>
     Total,
+    /// <summary>Count of Good-quality samples in the interval. Part 13 §5.18.</summary>
     Count,
+
+    // ---- Time-weighted averages (Part 13 §5.4) ----
+    /// <summary>Time-weighted average — values held until next sample. Part 13 §5.4.2.</summary>
+    TimeAverage,
+    /// <summary>Time-weighted average using simple-bounds extrapolation. Part 13 §5.4.3.</summary>
+    TimeAverage2,
+
+    // ---- Interpolation (Part 13 §5.3) ----
+    /// <summary>Interpolated value at each interval boundary. Part 13 §5.3.</summary>
+    Interpolative,
+
+    // ---- Min/Max with timestamps and range (Part 13 §5.5–§5.7) ----
+    /// <summary>Timestamp of the minimum-value sample. Part 13 §5.5.4.</summary>
+    MinimumActualTime,
+    /// <summary>Timestamp of the maximum-value sample. Part 13 §5.6.4.</summary>
+    MaximumActualTime,
+    /// <summary>Maximum minus minimum across the interval. Part 13 §5.7.</summary>
+    Range,
+    /// <summary>Range computed using simple-bounds extrapolation. Part 13 §5.7.</summary>
+    Range2,
+
+    // ---- Annotation / duration / quality coverage (Part 13 §5.16–§5.21) ----
+    /// <summary>Number of annotations attached to samples in the interval. Part 13 §5.21.</summary>
+    AnnotationCount,
+    /// <summary>Total time (ms) covered by Good-quality data. Part 13 §5.16.</summary>
+    DurationGood,
+    /// <summary>Total time (ms) covered by Bad-quality data. Part 13 §5.16.</summary>
+    DurationBad,
+    /// <summary>Percent of the interval covered by Good-quality data (0-100). Part 13 §5.17.</summary>
+    PercentGood,
+    /// <summary>Percent of the interval covered by Bad-quality data (0-100). Part 13 §5.17.</summary>
+    PercentBad,
+    /// <summary>Worst (most-severe) quality code seen in the interval. Part 13 §5.20.</summary>
+    WorstQuality,
+    /// <summary>Worst-quality code using simple-bounds extrapolation. Part 13 §5.20.</summary>
+    WorstQuality2,
+
+    // ---- Statistical (Part 13 §5.13) ----
+    /// <summary>Sample-population standard deviation (n-1 divisor). Part 13 §5.13.</summary>
+    StandardDeviationSample,
+    /// <summary>Whole-population standard deviation (n divisor). Part 13 §5.13.</summary>
+    StandardDeviationPopulation,
+    /// <summary>Sample-population variance (n-1 divisor). Part 13 §5.13.</summary>
+    VarianceSample,
+    /// <summary>Whole-population variance (n divisor). Part 13 §5.13.</summary>
+    VariancePopulation,
+
+    // ---- State-based (Part 13 §5.12, §5.19) ----
+    /// <summary>Number of value transitions observed in the interval. Part 13 §5.12.</summary>
+    NumberOfTransitions,
+    /// <summary>Total time (ms) the value was 0 (state Zero). Part 13 §5.19.</summary>
+    DurationInStateZero,
+    /// <summary>Total time (ms) the value was non-zero (state NonZero). Part 13 §5.19.</summary>
+    DurationInStateNonZero,
+
+    // ---- Interval bounds and deltas (Part 13 §5.8–§5.9, §5.11) ----
+    /// <summary>First Good-quality sample at or after the interval start. Part 13 §5.8.</summary>
+    Start,
+    /// <summary>Last Good-quality sample at or before the interval end. Part 13 §5.9.</summary>
+    End,
+    /// <summary>End sample minus Start sample. Part 13 §5.11.</summary>
+    Delta,
+    /// <summary>Boundary value (extrapolated) at the interval start. Part 13 §5.8.</summary>
+    StartBound,
+    /// <summary>Boundary value (extrapolated) at the interval end. Part 13 §5.9.</summary>
+    EndBound,
 }
 
 /// <summary>
-///     One row returned by <see cref="IHistoryProvider.ReadEventsAsync"/> — a historical
+///     One row returned by the fixed-field
-///     alarm/event record, not the OPC UA live-event stream. Fields match the minimum set the
+///     <see cref="IHistoryProvider.ReadEventsAsync(string?, DateTime, DateTime, int, CancellationToken)"/>
-///     Server needs to populate a <c>HistoryEventFieldList</c> for HistoryReadEvents responses.
+///     overload — a historical alarm/event record, not the OPC UA live-event stream. Fields
+///     match the minimum set the Server needs to populate a <c>HistoryEventFieldList</c>
+///     for HistoryReadEvents responses.
 /// </summary>
 /// <param name="EventId">Stable unique id for the event — driver-specific format.</param>
 /// <param name="SourceName">Source object that emitted the event. May differ from the <c>sourceName</c> filter the caller passed (fuzzy matches).</param>
@@ -114,9 +309,46 @@ public sealed record HistoricalEvent(
     string? Message,
     ushort Severity);
 
-/// <summary>Result of a <see cref="IHistoryProvider.ReadEventsAsync"/> call.</summary>
+/// <summary>Result of a <see cref="IHistoryProvider.ReadEventsAsync(string?, DateTime, DateTime, int, CancellationToken)"/> call.</summary>
 /// <param name="Events">Events in chronological order by <c>EventTimeUtc</c>.</param>
 /// <param name="ContinuationPoint">Opaque token for the next call when more events are available; null when complete.</param>
 public sealed record HistoricalEventsResult(
     IReadOnlyList<HistoricalEvent> Events,
     byte[]? ContinuationPoint);
+
+/// <summary>
+///     One row returned by the filter-aware
+///     <see cref="IHistoryProvider.ReadEventsAsync(string, EventHistoryRequest, CancellationToken)"/>
+///     overload. Carries an open-ended <see cref="Fields"/> bag keyed by
+///     <see cref="SimpleAttributeSpec.FieldName"/> (or a stable default name when no
+///     SelectClauses were supplied) so the server-side dispatcher can re-align fields with
+///     the client's requested order — without forcing every driver to honour the entire
+///     OPC UA EventFilter shape verbatim.
+/// </summary>
+/// <param name="Fields">
+///     SelectClause results. Keys match the <c>FieldName</c> on the corresponding
+///     <see cref="SimpleAttributeSpec"/>; values are the raw .NET payload (string,
+///     <c>DateTime</c>, severity int, etc.). <c>null</c> values are legitimate (the
+///     upstream had a missing field).
+/// </param>
+/// <param name="OccurrenceTime">
+///     Wall-clock event time — convenience for ordering / windowing without picking a key
+///     out of <see cref="Fields"/>. Drivers populate this from the underlying event row.
+/// </param>
+public sealed record HistoricalEventRow(
+    IReadOnlyDictionary<string, object?> Fields,
+    DateTimeOffset OccurrenceTime);
+
+/// <summary>
+///     Result of the filter-aware
+///     <see cref="IHistoryProvider.ReadEventsAsync(string, EventHistoryRequest, CancellationToken)"/>
+///     overload. Mirrors <see cref="HistoricalEventsResult"/> but carries
+///     <see cref="HistoricalEventRow"/> instead of the fixed-shape
+///     <see cref="HistoricalEvent"/> — the server-side dispatcher unpacks the keyed fields
+///     into a <c>HistoryEventFieldList</c> aligned with the client's SelectClauses.
+/// </summary>
+/// <param name="Events">Events in chronological order by <see cref="HistoricalEventRow.OccurrenceTime"/>.</param>
+/// <param name="ContinuationPoint">Opaque token for the next call when more events are available; null when complete.</param>
+public sealed record HistoricalEventBatch(
+    IReadOnlyList<HistoricalEventRow> Events,
+    byte[]? ContinuationPoint);

src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IHostConnectivityProbe.cs

@@ -38,4 +38,16 @@ public sealed record HostStatusChangedEventArgs(
     HostState NewState);
 
 /// <summary>Host lifecycle state. Generalization of Galaxy's Platform/Engine ScanState.</summary>
-public enum HostState { Unknown, Running, Stopped, Faulted }
+/// <remarks>
+///     <para>
+///         <see cref="Demoted"/> (PR ablegacy-12 / #255) is a soft-stopped state used by drivers
+///         that auto-throttle a host after N consecutive comm failures. Reads are short-circuited
+///         with <c>BadCommunicationError</c> for a configurable cool-down window so one slow PLC
+///         doesn't starve faster peers sharing the same driver. Demoted is *not* the same as
+///         <see cref="Stopped"/> (which means "probe says it's down") nor <see cref="Faulted"/>
+///         (which means "the driver itself is broken"); it's a deliberate driver-side back-off.
+///         Consumers that don't recognize <c>Demoted</c> can safely treat it as <c>Stopped</c>
+///         (see <c>HostStatusPublisher.MapState</c>).
+///     </para>
+/// </remarks>
+public enum HostState { Unknown, Running, Stopped, Faulted, Demoted }

src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Cli/AbLegacyCommandBase.cs

@@ -25,6 +25,34 @@ public abstract class AbLegacyCommandBase : DriverCommandBase
     [CommandOption("timeout-ms", Description = "Per-operation timeout in ms (default 5000).")]
     public int TimeoutMs { get; init; } = 5000;
 
+    /// <summary>
+    ///     PR ablegacy-12 / #255 — consecutive comm failures before this device is
+    ///     auto-demoted. Reads against a demoted device short-circuit with
+    ///     <c>BadCommunicationError</c> for <see cref="DemoteForMs"/> ms so one
+    ///     unreachable PLC can't starve faster peers sharing the driver thread.
+    /// </summary>
+    [CommandOption("demote-failure-threshold", Description =
+        "Consecutive comm failures before the device is auto-demoted (PR ablegacy-12). Default 3.")]
+    public int DemoteFailureThreshold { get; init; } = 3;
+
+    /// <summary>
+    ///     PR ablegacy-12 / #255 — auto-demote cool-down window in ms. Reads while
+    ///     this window is active short-circuit with <c>BadCommunicationError</c>;
+    ///     a successful probe clears it early.
+    /// </summary>
+    [CommandOption("demote-for-ms", Description =
+        "Auto-demote cool-down window in ms (PR ablegacy-12). Default 30000 (30s).")]
+    public int DemoteForMs { get; init; } = 30_000;
+
+    /// <summary>
+    ///     PR ablegacy-12 / #255 — opt out of the auto-demote behaviour. The
+    ///     consecutive-failure tally still ticks (so DemoteCount/LastDemotedUtc
+    ///     stay zero) but reads never short-circuit.
+    /// </summary>
+    [CommandOption("no-demote", Description =
+        "Disable auto-demote on consecutive comm failures (PR ablegacy-12). Default off (auto-demote enabled).")]
+    public bool NoDemote { get; init; }
+
     /// <inheritdoc />
     public override TimeSpan Timeout
     {
@@ -41,7 +69,11 @@ public abstract class AbLegacyCommandBase : DriverCommandBase
         Devices = [new AbLegacyDeviceOptions(
             HostAddress: Gateway,
             PlcFamily: PlcType,
-            DeviceName: $"cli-{PlcType}")],
+            DeviceName: $"cli-{PlcType}",
+            Demote: new AbLegacyDemoteOptions(
+                FailureThreshold: DemoteFailureThreshold,
+                DemoteFor: TimeSpan.FromMilliseconds(DemoteForMs),
+                Enabled: !NoDemote))],
         Tags = tags,
         Timeout = Timeout,
         Probe = new AbLegacyProbeOptions { Enabled = false },

src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Cli/Commands/ProbeCommand.cs

@@ -40,10 +40,19 @@ public sealed class ProbeCommand : AbLegacyCommandBase
             await driver.InitializeAsync("{}", ct);
             var snapshot = await driver.ReadAsync(["__probe"], ct);
             var health = driver.GetHealth();
+            // PR ablegacy-12 / #255 — surface Demoted alongside the probe-driven
+            // HostState. After a one-shot probe the host hasn't been observed
+            // (no probe loop runs in CLI mode), so HostState is typically Unknown
+            // unless the read above tripped the demote threshold.
+            var hostStatus = driver.GetHostStatuses().FirstOrDefault();
 
             await console.Output.WriteLineAsync($"Gateway:      {Gateway}");
             await console.Output.WriteLineAsync($"PLC type:     {PlcType}");
             await console.Output.WriteLineAsync($"Health:       {health.State}");
+            if (hostStatus is not null)
+            {
+                await console.Output.WriteLineAsync($"Host state:   {hostStatus.State}");
+            }
             if (health.LastError is { } err)
                 await console.Output.WriteLineAsync($"Last error:   {err}");
             await console.Output.WriteLineAsync();

src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDiagnosticTags.cs

@@ -40,6 +40,11 @@ public sealed class AbLegacyDiagnosticTags
     public const string DiagnosticsFolderPrefix = "_Diagnostics/";
 
     /// <summary>Canonical names the diagnostics folder exposes. Keep in lockstep with discovery.</summary>
+    /// <remarks>
+    ///     PR ablegacy-12 / #255 — <c>DemoteCount</c> + <c>LastDemotedUtc</c> ride
+    ///     alongside the original seven so HMIs can spot a flapping device by
+    ///     watching <c>DemoteCount</c> climb without scraping logs.
+    /// </remarks>
     public static readonly IReadOnlyList<string> DiagnosticTagNames =
     [
         "RequestCount",
@@ -49,6 +54,9 @@ public sealed class AbLegacyDiagnosticTags
         "LastErrorCode",
         "LastErrorMessage",
         "CommFailures",
+        // PR ablegacy-12 / #255 — auto-demote on comm failure surface.
+        "DemoteCount",
+        "LastDemotedUtc",
     ];
 
     private static readonly HashSet<string> DiagnosticTagNameSet =
@@ -130,6 +138,39 @@ public sealed class AbLegacyDiagnosticTags
         Interlocked.Increment(ref c.Retry);
     }
 
+    /// <summary>
+    ///     PR ablegacy-12 / #255 — record an auto-demotion event: bumps cumulative
+    ///     <c>DemoteCount</c> and stamps <c>LastDemotedUtc</c>. Fires every time the
+    ///     driver crosses the failure threshold and arms a fresh cool-down window —
+    ///     a single flapping link that demotes hourly will surface as a steadily
+    ///     climbing counter, which is the operator-facing signal we want.
+    /// </summary>
+    public void RecordDemote(string deviceHostAddress, DateTime nowUtc)
+    {
+        ArgumentNullException.ThrowIfNull(deviceHostAddress);
+        var c = GetOrCreate(deviceHostAddress);
+        Interlocked.Increment(ref c.DemoteCount);
+        // DateTime is 64 bits — use Interlocked.Exchange on the Ticks field so a
+        // concurrent reader sees a torn-free snapshot. On x86 a 64-bit non-aligned
+        // write isn't atomic; on x64 it is, but routing through Interlocked is
+        // platform-independent + costs almost nothing.
+        Interlocked.Exchange(ref c.LastDemotedUtcTicks, nowUtc.Ticks);
+    }
+
+    /// <summary>
+    ///     PR ablegacy-12 / #255 — restore cumulative demote bookkeeping after a
+    ///     <see cref="AbLegacyDriver.ReinitializeAsync"/> cycle so an operator
+    ///     redeploying config mid-incident doesn't lose flapping-link history.
+    ///     Sets the counters to absolute values rather than incrementing.
+    /// </summary>
+    public void RestoreDemote(string deviceHostAddress, long demoteCount, DateTime? lastDemotedUtc)
+    {
+        ArgumentNullException.ThrowIfNull(deviceHostAddress);
+        var c = GetOrCreate(deviceHostAddress);
+        Interlocked.Exchange(ref c.DemoteCount, demoteCount);
+        Interlocked.Exchange(ref c.LastDemotedUtcTicks, lastDemotedUtc?.Ticks ?? 0);
+    }
+
     /// <summary>Snapshot the current counters for a device. Returns zeros for unknown hosts.</summary>
     public DiagnosticsSnapshot Snapshot(string deviceHostAddress)
     {
@@ -139,7 +180,8 @@ public sealed class AbLegacyDiagnosticTags
         {
             _counters.TryGetValue(deviceHostAddress, out c);
         }
-        if (c is null) return new DiagnosticsSnapshot(0, 0, 0, 0, 0, string.Empty, 0);
+        if (c is null) return new DiagnosticsSnapshot(0, 0, 0, 0, 0, string.Empty, 0, 0, null);
+        var ticks = Interlocked.Read(ref c.LastDemotedUtcTicks);
         return new DiagnosticsSnapshot(
             Request: Interlocked.Read(ref c.Request),
             Response: Interlocked.Read(ref c.Response),
@@ -147,7 +189,10 @@ public sealed class AbLegacyDiagnosticTags
             Retry: Interlocked.Read(ref c.Retry),
             LastErrorCode: Volatile.Read(ref c.LastErrorCode),
             LastErrorMessage: c.LastErrorMessage ?? string.Empty,
-            CommFailures: Interlocked.Read(ref c.CommFailures));
+            CommFailures: Interlocked.Read(ref c.CommFailures),
+            // PR ablegacy-12 / #255 — auto-demote surface.
+            DemoteCount: Interlocked.Read(ref c.DemoteCount),
+            LastDemotedUtc: ticks == 0 ? null : new DateTime(ticks, DateTimeKind.Utc));
     }
 
     /// <summary>
@@ -155,7 +200,14 @@ public sealed class AbLegacyDiagnosticTags
     ///     from <see cref="AbLegacyDriver.ReinitializeAsync"/> so a config redeploy starts
     ///     with a clean diagnostic surface.
     /// </summary>
-    public void Reset(string deviceHostAddress)
+    /// <remarks>
+    ///     PR ablegacy-12 / #255 — when <paramref name="preserveDemote"/> is <c>true</c> the
+    ///     cumulative <c>DemoteCount</c> + <c>LastDemotedUtc</c> survive the reset.
+    ///     <see cref="AbLegacyDriver.ReinitializeAsync"/> uses that mode so an operator
+    ///     redeploying a config doesn't lose their flapping-link history; a fresh process
+    ///     start clears them naturally because the dictionary is rebuilt from scratch.
+    /// </remarks>
+    public void Reset(string deviceHostAddress, bool preserveDemote = false)
     {
         ArgumentNullException.ThrowIfNull(deviceHostAddress);
         var c = GetOrCreate(deviceHostAddress);
@@ -166,14 +218,40 @@ public sealed class AbLegacyDiagnosticTags
         Interlocked.Exchange(ref c.LastErrorCode, 0);
         c.LastErrorMessage = string.Empty;
         Interlocked.Exchange(ref c.CommFailures, 0);
+        if (!preserveDemote)
+        {
+            Interlocked.Exchange(ref c.DemoteCount, 0);
+            Interlocked.Exchange(ref c.LastDemotedUtcTicks, 0);
+        }
     }
 
     /// <summary>Reset every tracked device. Called on full <c>ShutdownAsync</c>.</summary>
-    public void ResetAll()
+    /// <remarks>
+    ///     PR ablegacy-12 / #255 — when <paramref name="preserveDemote"/> is <c>true</c> the
+    ///     cumulative demote counters survive a per-device reset of every other field.
+    ///     The default (<c>false</c>) clears the dictionary outright, which is what
+    ///     <see cref="AbLegacyDriver.ShutdownAsync"/> wants.
+    /// </remarks>
+    public void ResetAll(bool preserveDemote = false)
     {
+        if (!preserveDemote)
+        {
+            lock (_lock)
+            {
+                _counters.Clear();
+            }
+            return;
+        }
+
+        // Preserve mode: keep the dictionary keys + cumulative demote fields, but
+        // zero everything else. Used by Reinitialize to span a config redeploy
+        // without losing flapping-link history.
         lock (_lock)
         {
-            _counters.Clear();
+            foreach (var key in _counters.Keys.ToList())
+            {
+                Reset(key, preserveDemote: true);
+            }
         }
     }
 
@@ -205,6 +283,11 @@ public sealed class AbLegacyDiagnosticTags
             "LastErrorCode" => snapshot.LastErrorCode,
             "LastErrorMessage" => snapshot.LastErrorMessage,
             "CommFailures" => snapshot.CommFailures,
+            // PR ablegacy-12 / #255 — auto-demote surface. LastDemotedUtc returns
+            // the empty string when no demotion has happened yet, mirroring the
+            // LastErrorMessage convention so HMIs can bind directly to a string.
+            "DemoteCount" => snapshot.DemoteCount,
+            "LastDemotedUtc" => snapshot.LastDemotedUtc?.ToString("o") ?? string.Empty,
             _ => null,
         };
         return true;
@@ -236,6 +319,11 @@ public sealed class AbLegacyDiagnosticTags
         public int LastErrorCode;
         public string? LastErrorMessage = string.Empty;
         public long CommFailures;
+        // PR ablegacy-12 / #255 — cumulative across config redeploys. Cleared only
+        // on full driver process restart (the dictionary is rebuilt from scratch);
+        // ReinitializeAsync uses preserveDemote: true.
+        public long DemoteCount;
+        public long LastDemotedUtcTicks;
     }
 }
 
@@ -251,6 +339,9 @@ public sealed class AbLegacyDiagnosticTags
 /// <param name="LastErrorCode">Most recent libplctag status code on a failed read.</param>
 /// <param name="LastErrorMessage">Most recent libplctag error message on a failed read.</param>
 /// <param name="CommFailures">Count of read failures mapped to <c>BadCommunicationError</c>.</param>
+/// <param name="DemoteCount">PR ablegacy-12 / #255 — cumulative auto-demote events.</param>
+/// <param name="LastDemotedUtc">PR ablegacy-12 / #255 — UTC timestamp of the most
+///   recent demotion, or <c>null</c> if the device has never been demoted.</param>
 public sealed record DiagnosticsSnapshot(
     long Request,
     long Response,
@@ -258,4 +349,6 @@ public sealed record DiagnosticsSnapshot(
     long Retry,
     int LastErrorCode,
     string LastErrorMessage,
-    long CommFailures);
+    long CommFailures,
+    long DemoteCount,
+    DateTime? LastDemotedUtc);

src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs

@@ -163,6 +163,19 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
                 var addr = AbLegacyHostAddress.TryParse(device.HostAddress)
                     ?? throw new InvalidOperationException(
                         $"AbLegacy device has invalid HostAddress '{device.HostAddress}' — expected 'ab://gateway[:port]/cip-path'.");
+                // PR ablegacy-13 / #256 — DHRIO DH+ bridging is PLC-5-only. SLC500 /
+                // MicroLogix / LogixPccc cannot be addressed through a 1756-DHRIO module
+                // (the module only speaks DH+ to PLC-5 and SLC-DH+ peers — and the SLC-DH+
+                // path uses a different protocol stack libplctag's PCCC layer doesn't
+                // expose). Catch the misconfiguration up front rather than waiting for
+                // reads to return BadCommunicationError on the wire.
+                if (addr.IsDhPlusBridge && device.PlcFamily != AbLegacyPlcFamily.Plc5)
+                {
+                    throw new InvalidOperationException(
+                        $"AbLegacy device '{device.HostAddress}' uses the 1756-DHRIO DH+ bridge " +
+                        $"path '1,{addr.BackplaneSlot},2,…' but PlcFamily='{device.PlcFamily}'. " +
+                        "DHRIO bridging is PLC-5-only.");
+                }
                 var profile = AbLegacyPlcFamilyProfile.ForFamily(device.PlcFamily);
                 _devices[device.HostAddress] = new DeviceState(addr, device, profile);
                 // PR ablegacy-10 / #253 — pre-allocate the diagnostic-counter slot so the
@@ -217,6 +230,20 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
 
     public async Task ReinitializeAsync(string driverConfigJson, CancellationToken cancellationToken)
     {
+        // PR ablegacy-12 / #255 — capture the cumulative DemoteCount + LastDemotedUtc
+        // for every currently-tracked device before we tear down. The Shutdown below
+        // calls ResetAll() which clears the dictionary; the per-host InitializeAsync
+        // below re-EnsureDevice's the slots; we restore the cumulative demote
+        // history so an operator who redeploys mid-incident doesn't lose the trail
+        // of how often this device was flapping.
+        var preservedDemote = new Dictionary<string, (long DemoteCount, DateTime? LastDemotedUtc)>(
+            StringComparer.OrdinalIgnoreCase);
+        foreach (var (host, _) in _devices)
+        {
+            var snap = _diagnosticTags.Snapshot(host);
+            preservedDemote[host] = (snap.DemoteCount, snap.LastDemotedUtc);
+        }
+
         await ShutdownAsync(cancellationToken).ConfigureAwait(false);
         // PR ablegacy-10 / #253 — counters were dropped along with the device map when
         // ShutdownAsync called ResetAll; the InitializeAsync below re-EnsureDevice's each
@@ -224,6 +251,16 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
         // here in case a downstream override of either method skips the cycle.
         _diagnosticTags.ResetAll();
         await InitializeAsync(driverConfigJson, cancellationToken).ConfigureAwait(false);
+
+        // PR ablegacy-12 / #255 — restore the cumulative demote history. Only hosts
+        // that survive the redeploy get their counters back; a device removed from
+        // config legitimately drops its history (it isn't being tracked any more).
+        foreach (var (host, (count, lastUtc)) in preservedDemote)
+        {
+            if (count == 0 && lastUtc is null) continue;
+            if (!_devices.ContainsKey(host)) continue;
+            _diagnosticTags.RestoreDemote(host, count, lastUtc);
+        }
     }
 
     public async Task ShutdownAsync(CancellationToken cancellationToken)
@@ -275,6 +312,38 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
     internal int ResolveRetries(DeviceState device) =>
         device.Options.Retries ?? _options.Retries ?? 0;
 
+    /// <summary>
+    ///     PR ablegacy-12 / #255 — resolve the active <see cref="AbLegacyDemoteOptions"/> for
+    ///     a device. Per-device options win; otherwise the documented defaults (3 failures /
+    ///     30 s / enabled). Returns a non-null record so callers can assume a usable value.
+    /// </summary>
+    internal AbLegacyDemoteOptions ResolveDemote(DeviceState device) =>
+        device.Options.Demote ?? new AbLegacyDemoteOptions();
+
+    /// <summary>
+    ///     PR ablegacy-12 / #255 — common bookkeeping for one comm failure: bump the
+    ///     consecutive-failure counter and arm the demote window once the threshold is
+    ///     crossed. Returns <c>true</c> when this call tipped the device into Demoted (so
+    ///     the caller can fire <see cref="OnHostStatusChanged"/>); <c>false</c> when the
+    ///     device was already demoted or stayed below the threshold.
+    /// </summary>
+    private bool RecordFailureAndMaybeDemote(DeviceState state, DateTime nowUtc)
+    {
+        var demote = ResolveDemote(state);
+        var consecutive = Interlocked.Increment(ref state.ConsecutiveFailures);
+
+        if (!demote.Enabled || consecutive < demote.FailureThreshold) return false;
+        // Already demoted? Don't re-arm — the original window's expiry is the
+        // operator-facing recovery clock and re-arming on every subsequent failed
+        // read would suppress reads forever on a fully-down device. The probe
+        // loop is what eventually clears the demotion (or the window expiring).
+        if (state.DemotedUntilUtc is { } until && until > nowUtc) return false;
+
+        state.DemotedUntilUtc = nowUtc + demote.EffectiveDemoteFor;
+        _diagnosticTags.RecordDemote(state.Options.HostAddress, nowUtc);
+        return true;
+    }
+
     // ---- IReadable ----
 
     public async Task<IReadOnlyList<DataValueSnapshot>> ReadAsync(
@@ -323,6 +392,45 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
             // double-counting the original attempt as a retry.
             _diagnosticTags.RecordRequest(def.DeviceHostAddress);
 
+            // PR ablegacy-12 / #255 — auto-demote short-circuit. When the device's demote
+            // window is still active we return BadCommunicationError immediately, without
+            // touching libplctag or its retry loop. That's the whole point of the feature:
+            // one slow PLC sharing the driver thread can't drag down healthy peers. We
+            // don't bump ErrorCount/CommFailures here because this isn't a fresh field
+            // failure — it's the cool-down on a previously-counted one.
+            if (device.DemotedUntilUtc is { } demotedUntil)
+            {
+                if (demotedUntil > now)
+                {
+                    results[i] = new DataValueSnapshot(null,
+                        AbLegacyStatusMapper.BadCommunicationError, null, now);
+                    continue;
+                }
+                // Window expired without an early-clear from a probe success — drop the
+                // marker but don't reset ConsecutiveFailures yet. If this read also
+                // fails the failure tally keeps counting from where it left off, so a
+                // permanently-down device re-arms the window after one more
+                // consecutive failure (vs. having to repeat the full threshold).
+                lock (device.ProbeLock)
+                {
+                    if (device.DemotedUntilUtc is { } stillUntil && stillUntil <= now)
+                    {
+                        device.DemotedUntilUtc = null;
+                        // Mirror Stopped→Running on a probe-driven recovery: leave the
+                        // HostState transition to the probe loop (or the upcoming success
+                        // below); we just clear the cool-down marker so the next read
+                        // dispatches normally.
+                        if (device.HostState == HostState.Demoted)
+                        {
+                            // Surface a transition out of Demoted. The probe loop will
+                            // bring it Running once a probe succeeds; until then leave
+                            // it in Stopped to reflect "we don't actually know it's up".
+                            TransitionDeviceState(device, HostState.Stopped);
+                        }
+                    }
+                }
+            }
+
             // PR 9 — per-device retry loop: on transient BadCommunicationError (libplctag throw
             // OR a non-zero status that maps to BadCommunicationError) retry up to N times. A
             // terminal mapped status (e.g. BadNodeIdUnknown for a missing PLC tag, BadTypeMismatch
@@ -360,6 +468,15 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
                             status,
                             $"libplctag status {status} reading {reference}",
                             commFailure: mappedStatus == AbLegacyStatusMapper.BadCommunicationError);
+                        // PR ablegacy-12 / #255 — only comm failures count toward the
+                        // demote tally. A BadNodeIdUnknown / BadTypeMismatch is a config
+                        // / decoder mismatch, not a sign the host is unreachable, so
+                        // demoting on it would punish the operator for a typo.
+                        if (mappedStatus == AbLegacyStatusMapper.BadCommunicationError
+                            && RecordFailureAndMaybeDemote(device, now))
+                        {
+                            TransitionDeviceState(device, HostState.Demoted);
+                        }
                         snapshot = new DataValueSnapshot(null, mappedStatus, null, now);
                         _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead,
                             $"libplctag status {status} reading {reference}");
@@ -385,6 +502,13 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
                         _health = new DriverHealth(DriverState.Healthy, now, null);
                         // PR ablegacy-10 / #253 — successful array read.
                         _diagnosticTags.RecordResponse(def.DeviceHostAddress);
+                        // PR ablegacy-12 / #255 — successful read clears the
+                        // consecutive-failure tally. We do NOT auto-clear DemotedUntilUtc
+                        // here — the demote window is honoured to its full duration so an
+                        // intermittent link that just happened to answer once doesn't
+                        // immediately re-flood the channel. Probe success is the early
+                        // recovery path.
+                        Interlocked.Exchange(ref device.ConsecutiveFailures, 0);
                         break;
                     }
 
@@ -398,6 +522,10 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
                     _health = new DriverHealth(DriverState.Healthy, now, null);
                     // PR ablegacy-10 / #253 — successful scalar / sub-element / bit read.
                     _diagnosticTags.RecordResponse(def.DeviceHostAddress);
+                    // PR ablegacy-12 / #255 — successful read clears the
+                    // consecutive-failure tally; demote window keeps running
+                    // until a probe success or natural expiry.
+                    Interlocked.Exchange(ref device.ConsecutiveFailures, 0);
                     break;
                 }
                 catch (OperationCanceledException) { throw; }
@@ -414,6 +542,12 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
                         libplctagStatus: 0,
                         errorMessage: ex.Message,
                         commFailure: true);
+                    // PR ablegacy-12 / #255 — exception-driven comm failure counts
+                    // toward the demote tally just like a status-mapped one.
+                    if (RecordFailureAndMaybeDemote(device, now))
+                    {
+                        TransitionDeviceState(device, HostState.Demoted);
+                    }
                     snapshot = new DataValueSnapshot(null,
                         AbLegacyStatusMapper.BadCommunicationError, null, now);
                     _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, ex.Message);
@@ -591,6 +725,14 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
             "Most recent libplctag error message on a failed read; empty when no error has been seen since the last reset.");
         EmitDiagnosticVariable(diag, deviceHostAddress, "CommFailures", DriverDataType.Int64,
             "Count of read failures mapped to BadCommunicationError. Spans transient libplctag throws + retried-out chains so operators see a single 'wire fell off' counter.");
+        // PR ablegacy-12 / #255 — auto-demote surface. DemoteCount is cumulative
+        // across reinit (preserved in ReinitializeAsync); LastDemotedUtc is a
+        // string (ISO-8601 UTC) so HMIs can bind directly without a separate
+        // DateTime decoder. Empty string means "never demoted".
+        EmitDiagnosticVariable(diag, deviceHostAddress, "DemoteCount", DriverDataType.Int64,
+            "Cumulative auto-demote events for this device — bumps every time the driver crosses the consecutive-failure threshold and arms a fresh cool-down window. Survives ReinitializeAsync.");
+        EmitDiagnosticVariable(diag, deviceHostAddress, "LastDemotedUtc", DriverDataType.String,
+            "ISO-8601 UTC timestamp of the most recent auto-demotion; empty when this device has never been demoted.");
     }
 
     private static void EmitDiagnosticVariable(
@@ -665,7 +807,39 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
                 state.ProbeInitialized = false;
             }
 
-            TransitionDeviceState(state, success ? HostState.Running : HostState.Stopped);
+            // PR ablegacy-12 / #255 — probe success is the early-recovery path: clear
+            // any active demote window + reset the failure tally so the next read
+            // dispatches normally. Probe failure participates in the same shared
+            // failure-tally as ReadAsync so a device with no live read traffic still
+            // demotes on a sustained outage.
+            if (success)
+            {
+                bool wasDemoted;
+                lock (state.ProbeLock)
+                {
+                    wasDemoted = state.DemotedUntilUtc is not null;
+                    state.DemotedUntilUtc = null;
+                }
+                Interlocked.Exchange(ref state.ConsecutiveFailures, 0);
+                TransitionDeviceState(state, HostState.Running);
+                _ = wasDemoted; // intentionally observed for future telemetry hooks
+            }
+            else
+            {
+                if (RecordFailureAndMaybeDemote(state, DateTime.UtcNow))
+                {
+                    TransitionDeviceState(state, HostState.Demoted);
+                }
+                else
+                {
+                    // Mid-tally probe failure: surface as Stopped if not already
+                    // Demoted. This preserves pre-PR-12 behaviour for the common
+                    // case (FailureThreshold=3 + a single hiccup ends up Stopped,
+                    // not Demoted).
+                    if (state.HostState != HostState.Demoted)
+                        TransitionDeviceState(state, HostState.Stopped);
+                }
+            }
 
             try { await Task.Delay(_options.Probe.Interval, ct).ConfigureAwait(false); }
             catch (OperationCanceledException) { break; }
@@ -890,6 +1064,25 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
         public CancellationTokenSource? ProbeCts { get; set; }
         public bool ProbeInitialized { get; set; }
 
+        /// <summary>
+        ///     PR ablegacy-12 / #255 — running tally of consecutive read / probe failures.
+        ///     Reset on every successful read or probe; tripping
+        ///     <see cref="AbLegacyDemoteOptions.FailureThreshold"/> arms the demote window.
+        ///     Read + written via <see cref="Interlocked"/> because read + probe loops can
+        ///     touch it concurrently.
+        /// </summary>
+        public int ConsecutiveFailures;
+
+        /// <summary>
+        ///     PR ablegacy-12 / #255 — when set, reads against this device short-circuit
+        ///     with <c>BadCommunicationError</c> until the timestamp passes; cleared early
+        ///     by a successful probe. Guarded by <see cref="ProbeLock"/> for the mutator
+        ///     paths (TransitionDeviceState + RecordFailureAndMaybeDemote); reads grab
+        ///     the property without locking — a torn DateTime? read is harmless here
+        ///     because the worst case is one extra dispatched read on an x86 boundary.
+        /// </summary>
+        public DateTimeOffset? DemotedUntilUtc { get; set; }
+
         public void DisposeRuntimes()
         {
             foreach (var r in Runtimes.Values) r.Dispose();

src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriverFactoryExtensions.cs

@@ -45,7 +45,14 @@ public static class AbLegacyDriverFactoryExtensions
                     DeviceName: d.DeviceName,
                     // PR 9 — per-device timeout / retry overrides. Device-level wins over driver-wide.
                     Timeout: d.TimeoutMs is int devMs ? TimeSpan.FromMilliseconds(devMs) : null,
-                    Retries: d.Retries))]
+                    Retries: d.Retries,
+                    // PR ablegacy-12 / #255 — auto-demote knobs.
+                    Demote: d.Demote is null ? null : new AbLegacyDemoteOptions(
+                        FailureThreshold: d.Demote.FailureThreshold ?? 3,
+                        DemoteFor: d.Demote.DemoteForMs is int demMs
+                            ? TimeSpan.FromMilliseconds(demMs)
+                            : null,
+                        Enabled: d.Demote.Enabled ?? true)))]
                 : [],
             Tags = dto.Tags is { Count: > 0 }
                 ? [.. dto.Tags.Select(t => new AbLegacyTagDefinition(
@@ -209,6 +216,26 @@ public static class AbLegacyDriverFactoryExtensions
         ///     <c>null</c> at both levels = single attempt.
         /// </summary>
         public int? Retries { get; init; }
+
+        /// <summary>
+        ///     PR ablegacy-12 / #255 — optional per-device auto-demote knobs. <c>null</c>
+        ///     means "use the documented defaults" (<c>FailureThreshold=3</c>,
+        ///     <c>DemoteFor=30s</c>, <c>Enabled=true</c>) — the driver still demotes by
+        ///     default. Set <c>Enabled=false</c> in the JSON to opt out entirely.
+        /// </summary>
+        public AbLegacyDemoteDto? Demote { get; init; }
+    }
+
+    /// <summary>
+    ///     PR ablegacy-12 / #255 — JSON DTO for the auto-demote knobs. Times are
+    ///     ms-suffixed for consistency with the rest of the driver config (TimeoutMs,
+    ///     IntervalMs).
+    /// </summary>
+    internal sealed class AbLegacyDemoteDto
+    {
+        public int? FailureThreshold { get; init; }
+        public int? DemoteForMs { get; init; }
+        public bool? Enabled { get; init; }
     }
 
     internal sealed class AbLegacyTagDto

src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriverOptions.cs

@@ -41,7 +41,39 @@ public sealed record AbLegacyDeviceOptions(
     AbLegacyPlcFamily PlcFamily = AbLegacyPlcFamily.Slc500,
     string? DeviceName = null,
     TimeSpan? Timeout = null,
-    int? Retries = null);
+    int? Retries = null,
+    AbLegacyDemoteOptions? Demote = null);
+
+/// <summary>
+///     PR ablegacy-12 / #255 — auto-demote knobs. After
+///     <see cref="FailureThreshold"/> consecutive read / probe failures the driver
+///     marks the device <c>Demoted</c> for <see cref="DemoteFor"/>; reads against
+///     a demoted device short-circuit with <c>BadCommunicationError</c> instead
+///     of dispatching through libplctag, so one slow PLC can't starve faster
+///     peers sharing the same driver. A successful probe clears the demotion
+///     early; a successful read just resets the consecutive-failure counter
+///     without leaving the demoted window.
+/// </summary>
+/// <param name="FailureThreshold">Consecutive read or probe failures that trip
+///   the demotion. Default <c>3</c>.</param>
+/// <param name="DemoteFor">Cool-down window before reads are dispatched again
+///   without a successful probe in between. Default <c>30s</c>.</param>
+/// <param name="Enabled">When <c>false</c> the failure tally still ticks but the
+///   driver never sets the demoted window — useful when an operator wants the
+///   diagnostic counters without the throttling behaviour.</param>
+public sealed record AbLegacyDemoteOptions(
+    int FailureThreshold = 3,
+    TimeSpan? DemoteFor = null,
+    bool Enabled = true)
+{
+    /// <summary>
+    ///     Effective demote window. Records can't have <c>TimeSpan</c> defaults
+    ///     because <c>TimeSpan.FromSeconds(30)</c> isn't a compile-time constant;
+    ///     callers that pass <c>null</c> get the documented 30-second default
+    ///     here.
+    /// </summary>
+    public TimeSpan EffectiveDemoteFor => DemoteFor ?? TimeSpan.FromSeconds(30);
+}
 
 /// <summary>
 ///     One PCCC-backed OPC UA variable. <c>Address</c> is the canonical PCCC file-address

src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyHostAddress.cs

@@ -7,14 +7,38 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.AbLegacy;
 ///     a direct-wired SLC 500 uses an empty path).
 /// </summary>
 /// <remarks>
-///     Parser duplicated from AbCipHostAddress rather than shared because the two drivers ship
+///     <para>Parser duplicated from AbCipHostAddress rather than shared because the two drivers
-///     independently + a shared helper would force a reference between them. If a third AB
+///     ship independently + a shared helper would force a reference between them. If a third AB
-///     driver appears, extract into Core.Abstractions.
+///     driver appears, extract into Core.Abstractions.</para>
+///     <para>PR ablegacy-13 / #256 — the optional <see cref="BackplaneSlot"/>,
+///     <see cref="DhPlusPort"/> and <see cref="DhPlusStation"/> fields are populated when the
+///     CIP path matches the canonical 1756-DHRIO bridge form <c>1,&lt;slot&gt;,2,&lt;station&gt;</c>:
+///     port 1 (backplane) → DHRIO module slot → port 2 (DH+ side of the module) → DH+ node
+///     address. The DH+ station number is octal in PLC-5 firmware (0..77 = decimal 0..63);
+///     we parse it as octal and surface the decimal value for diagnostics. DHRIO bridging is
+///     PLC-5-only — the family-validation guard lives on the driver.</para>
 /// </remarks>
-public sealed record AbLegacyHostAddress(string Gateway, int Port, string CipPath)
+public sealed record AbLegacyHostAddress(
+    string Gateway,
+    int Port,
+    string CipPath,
+    int? BackplaneSlot = null,
+    int? DhPlusPort = null,
+    int? DhPlusStation = null)
 {
     public const int DefaultEipPort = 44818;
 
+    /// <summary>
+    ///     Maximum chassis slot index accepted for the DHRIO bridge form. Real ControlLogix
+    ///     chassis are 4 / 7 / 10 / 13 / 17 slots; capping at 16 covers the largest standard
+    ///     17-slot frame (slots 0..16) without rejecting anything an operator might legitimately
+    ///     configure. Tighter / family-specific bounds are enforced elsewhere.
+    /// </summary>
+    public const int MaxBackplaneSlot = 16;
+
+    /// <summary>True iff the CIP path was the canonical 1756-DHRIO DH+ bridge form.</summary>
+    public bool IsDhPlusBridge => DhPlusStation is not null;
+
     public override string ToString() => Port == DefaultEipPort
         ? $"ab://{Gateway}/{CipPath}"
         : $"ab://{Gateway}:{Port}/{CipPath}";
@@ -48,6 +72,73 @@ public sealed record AbLegacyHostAddress(string Gateway, int Port, string CipPat
         }
         if (string.IsNullOrEmpty(gateway)) return null;
 
+        // PR ablegacy-13 / #256 — optional DHRIO DH+ bridge path detection.
+        // Shape: exactly four comma-separated decimal segments `port,slot,port,station` with
+        // port[0]=1 (backplane), slot in [0..16], port[2]=2 (DH+), station octal 0..77.
+        // Anything else is left as an opaque CIP path — direct-wired PLCs, MicroLogix empty
+        // paths, longer multi-hop bridges all flow through unchanged.
+        if (TryParseDhPlusBridge(cipPath, out var slot, out var dhPort, out var station))
+        {
+            return new AbLegacyHostAddress(gateway, port, cipPath,
+                BackplaneSlot: slot,
+                DhPlusPort: dhPort,
+                DhPlusStation: station);
+        }
+
         return new AbLegacyHostAddress(gateway, port, cipPath);
     }
+
+    /// <summary>
+    ///     Returns <c>true</c> iff <paramref name="cipPath"/> is exactly the four-segment DHRIO
+    ///     bridge form <c>1,&lt;slot&gt;,2,&lt;station&gt;</c>. Returns <c>false</c> for every
+    ///     other shape — including malformed near-misses (slot out of range, station out of
+    ///     octal range, port-1 ≠ backplane). A near-miss returns false rather than throwing so
+    ///     the caller can keep treating the CIP path as opaque.
+    /// </summary>
+    /// <remarks>
+    ///     This method is the single source of truth for the DHRIO octal-station range check.
+    ///     Reuses the same "octal accepts only 0..7" rule as <c>AbLegacyAddress</c>'s PLC-5
+    ///     I/O parser — a leading <c>8</c> or <c>9</c> in any digit is rejected.
+    /// </remarks>
+    private static bool TryParseDhPlusBridge(
+        string cipPath, out int slot, out int dhPort, out int station)
+    {
+        slot = 0;
+        dhPort = 0;
+        station = 0;
+
+        if (string.IsNullOrEmpty(cipPath)) return false;
+
+        // Reject leading / trailing whitespace inside segments — `1, 3, 2, 07` (with spaces)
+        // is plausibly user typo but we keep the parser strict to avoid false positives.
+        var parts = cipPath.Split(',');
+        if (parts.Length != 4) return false;
+
+        if (!int.TryParse(parts[0], out var firstPort) || firstPort != 1) return false;
+        if (!int.TryParse(parts[1], out slot) || slot < 0 || slot > MaxBackplaneSlot) return false;
+        if (!int.TryParse(parts[2], out dhPort) || dhPort != 2) return false;
+        if (!TryParseOctal(parts[3], out station) || station < 0 || station > 63) return false;
+
+        return true;
+    }
+
+    /// <summary>
+    ///     Parse a DH+ station number written in octal (0..77 octal = 0..63 decimal). Mirrors
+    ///     the octal-rule in <c>AbLegacyAddress.TryParseIndex</c> — digits 0..7 only, no sign,
+    ///     no prefix. Returns <c>false</c> for empty input, illegal digits (8/9), or non-digit
+    ///     characters.
+    /// </summary>
+    private static bool TryParseOctal(string text, out int value)
+    {
+        value = 0;
+        if (string.IsNullOrEmpty(text)) return false;
+        var acc = 0;
+        foreach (var c in text)
+        {
+            if (c < '0' || c > '7') return false;
+            acc = (acc * 8) + (c - '0');
+        }
+        value = acc;
+        return true;
+    }
 }

src/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/PlcFamilies/AbLegacyPlcFamilyProfile.cs

@@ -52,6 +52,14 @@ public sealed record AbLegacyPlcFamilyProfile(
         SupportsPlsFile: false,
         SupportsBlockTransferFile: false);
 
+    /// <remarks>
+    ///     PR ablegacy-13 / #256 — PLC-5 is the only family that supports the 1756-DHRIO DH+
+    ///     bridging form (CIP path <c>1,&lt;slot&gt;,2,&lt;station-octal&gt;</c>). The DHRIO
+    ///     module only speaks DH+ to PLC-5 / SLC-DH+ peers, and libplctag's PCCC stack only
+    ///     exposes the PLC-5 side. SLC500 / MicroLogix / LogixPccc devices addressed through a
+    ///     DHRIO path are rejected at <c>AbLegacyDriver.InitializeAsync</c> time. See
+    ///     <c>docs/drivers/AbLegacy-DH-Bridging.md</c> for the full DH+ syntax + smoke procedure.
+    /// </remarks>
     public static readonly AbLegacyPlcFamilyProfile Plc5 = new(
         LibplctagPlcAttribute: "plc5",
         DefaultCipPath: "1,0",

src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasDriver.cs

@@ -58,13 +58,46 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
     ];
 
     /// <summary>
-    ///     Names of the 4 fixed-tree <c>Production/</c> child nodes per device — parts
+    ///     Names of the fixed-tree <c>Production/</c> child nodes per device — parts
     ///     produced/required/total via <c>cnc_rdparam(6711/6712/6713)</c> + cycle-time
-    ///     seconds (issue #258). Order matters for deterministic discovery output.
+    ///     seconds (issue #258), plus the F5-a derived telemetry pair
+    ///     <c>LastCycleSeconds</c> + <c>LastCycleStartUtc</c> (issue #272).
+    ///     Order matters for deterministic discovery output.
     /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         The F5-a derivation is pure — it observes the same
+    ///         <c>cnc_rdparam(6711)</c> + cycle-timer values the existing F1-b
+    ///         projection already pulls on the probe tick, so no additional wire
+    ///         calls are issued.
+    ///     </para>
+    ///     <para>
+    ///         <c>LastCycleSeconds</c> = the cycle-timer delta observed across
+    ///         two successive parts-count increments (<c>currentTimer -
+    ///         timerAtPreviousIncrement</c>). <c>LastCycleStartUtc</c> = the wall-
+    ///         clock at the moment of the second increment minus
+    ///         <c>LastCycleSeconds</c>. Both values are <c>null</c> until the second
+    ///         observed parts-count increment (one increment establishes the
+    ///         baseline; the second produces the first delta).
+    ///     </para>
+    ///     <para>
+    ///         A parts-count counter reset (e.g. shift change, value goes
+    ///         backwards) re-baselines the state without emitting a negative
+    ///         <c>LastCycleSeconds</c>; the previously-published values stay live
+    ///         until the next positive transition produces a fresh delta. A
+    ///         cycle-timer rollover (timer goes backwards while parts-count
+    ///         increments) re-baselines the timer without publishing the negative
+    ///         delta, so a single tick where the delta would be &lt; 0 leaves the
+    ///         current <c>LastCycle*</c> values untouched. A parts-count jump of
+    ///         &gt; 1 (backfill) emits one delta — the timer delta over the
+    ///         window — without trying to per-part-divide the value, matching the
+    ///         plan's "delta over the window between increments" intent.
+    ///     </para>
+    /// </remarks>
     private static readonly string[] ProductionFieldNames =
     [
         "PartsProduced", "PartsRequired", "PartsTotal", "CycleTimeSeconds",
+        "LastCycleSeconds", "LastCycleStartUtc",
     ];
 
     /// <summary>
@@ -712,16 +745,18 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
                     WriteIdempotent: false));
             }
 
-            // Fixed-tree Production/ subfolder — 4 read-only Int32 nodes: parts produced /
+            // Fixed-tree Production/ subfolder — 6 read-only nodes: parts produced /
-            // required / total + cycle-time seconds (issue #258). Cached on the probe tick
+            // required / total + cycle-time seconds (issue #258), plus the F5-a derived
-            // + served from DeviceState.LastProduction.
+            // pair LastCycleSeconds / LastCycleStartUtc (issue #272). Cached on the probe
+            // tick + served from DeviceState.LastProduction (wire-sourced fields) and
+            // DeviceState.LastCycle* (derived).
             var productionFolder = deviceFolder.Folder("Production", "Production");
             foreach (var field in ProductionFieldNames)
             {
                 var fullRef = ProductionReferenceFor(device.HostAddress, field);
                 productionFolder.Variable(field, field, new DriverAttributeInfo(
                     FullName: fullRef,
-                    DriverDataType: DriverDataType.Int32,
+                    DriverDataType: ProductionFieldType(field),
                     IsArray: false,
                     ArrayDim: null,
                     SecurityClass: SecurityClassification.ViewOnly,
@@ -878,6 +913,22 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
         _ => DriverDataType.String,
     };
 
+    /// <summary>
+    ///     Plan PR F5-a (issue #272) — per-field <see cref="DriverDataType"/>
+    ///     dispatch for the <c>Production/</c> subtree. The four wire-sourced fields
+    ///     (PartsProduced / Required / Total + CycleTimeSeconds) stay
+    ///     <see cref="DriverDataType.Int32"/> for back-compat with the F1-b surface;
+    ///     the two F5-a derived fields surface as <see cref="DriverDataType.Float64"/>
+    ///     (sub-second precision is meaningful at fast cycle times) and
+    ///     <see cref="DriverDataType.DateTime"/> (UTC) respectively.
+    /// </summary>
+    private static DriverDataType ProductionFieldType(string field) => field switch
+    {
+        "LastCycleSeconds"  => DriverDataType.Float64,
+        "LastCycleStartUtc" => DriverDataType.DateTime,
+        _                   => DriverDataType.Int32,
+    };
+
     /// <summary>
     ///     Plan PR F4-b (issue #269) — declare the per-tag write classification the
     ///     server-layer ACL gate (DriverNodeManager) consumes. Per the
@@ -1064,6 +1115,9 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
                     var production = await client.GetProductionAsync(ct).ConfigureAwait(false);
                     if (production is not null)
                     {
+                        // F5-a (issue #272) — derive LastCycleSeconds + LastCycleStartUtc
+                        // from the same observation. Pure derivation: no extra wire calls.
+                        UpdateCycleDerivation(state, production, DateTime.UtcNow);
                         state.LastProduction = production;
                         state.LastProductionUtc = DateTime.UtcNow;
                     }
@@ -1169,10 +1223,132 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
             device.LastStatusUtc, now);
     }
 
+    /// <summary>
+    ///     Plan PR F5-a (issue #272) — pure derivation that maintains the per-device
+    ///     <c>LastCycleSeconds</c> + <c>LastCycleStartUtc</c> projection from the
+    ///     wire-sourced production snapshot the probe loop already collected.
+    ///     <para>
+    ///         The derivation observes <c>PartsProduced</c> + <c>CycleTimeSeconds</c>
+    ///         on every tick and remembers the values seen at the last positive
+    ///         parts-count transition. When parts-count next increments by &gt;= 1, the
+    ///         delta in cycle-timer seconds across that window becomes
+    ///         <c>LastCycleSeconds</c>; <c>LastCycleStartUtc</c> = current wall clock
+    ///         minus that delta.
+    ///     </para>
+    ///     <para>
+    ///         Edge cases — see the <see cref="ProductionFieldNames"/> remarks for the
+    ///         full doc:
+    ///         <list type="bullet">
+    ///             <item>First observation establishes the baseline; no
+    ///             <c>LastCycleSeconds</c> is published until the second.</item>
+    ///             <item>Parts-count counter reset (current &lt; previous) re-baselines
+    ///             without clobbering the most-recent published <c>LastCycle*</c>.</item>
+    ///             <item>Cycle-timer rollover (delta &lt; 0 with positive parts
+    ///             increment) re-baselines without publishing a negative delta.</item>
+    ///             <item>Parts-count jumps &gt; 1 publish the timer delta as one
+    ///             <c>LastCycleSeconds</c> per the plan's "delta over the window"
+    ///             definition — no per-part division.</item>
+    ///         </list>
+    ///     </para>
+    /// </summary>
+    internal static void UpdateCycleDerivation(
+        DeviceState state, FocasProductionInfo production, DateTime nowUtc)
+    {
+        var partsCount = production.PartsProduced;
+        var cycleTimerSeconds = (double)production.CycleTimeSeconds;
+
+        // First observation — establish the baseline. No prior increment to
+        // delta against, so nothing is published yet.
+        if (state.PreviousPartsCount is not int prevParts
+            || state.PreviousCycleTimerSeconds is not double prevTimer)
+        {
+            state.PreviousPartsCount = partsCount;
+            state.PreviousCycleTimerSeconds = cycleTimerSeconds;
+            state.PreviousIncrementAtUtc = null;
+            return;
+        }
+
+        // Parts-count counter reset (e.g. shift-change zero) — leave any
+        // previously-published LastCycle* values live, but re-baseline so the
+        // next positive transition produces a fresh delta. Documented as
+        // "counter reset preserves the last-known values" in the field-doc
+        // remarks; tests assert this intentionally.
+        if (partsCount < prevParts)
+        {
+            state.PreviousPartsCount = partsCount;
+            state.PreviousCycleTimerSeconds = cycleTimerSeconds;
+            return;
+        }
+
+        // No increment this tick — slide the timer baseline forward so the
+        // delta on the NEXT increment reflects the true window between
+        // increments rather than just the gap since the last sample.
+        // (Choosing snapshot-at-last-increment vs snapshot-at-prior-tick is
+        // the core "which delta?" question; per the plan: "delta in
+        // Timers/CycleSeconds between successive parts-count increments" so
+        // we keep the cycle-timer baseline pinned to the last increment and
+        // only update on transition. The previous-parts-count is also kept
+        // pinned so subsequent equal-parts ticks remain no-ops.)
+        if (partsCount == prevParts)
+        {
+            // Defensive: still detect cycle-timer rollover so the next
+            // increment's delta isn't poisoned by a backwards baseline.
+            if (cycleTimerSeconds < prevTimer)
+            {
+                state.PreviousCycleTimerSeconds = cycleTimerSeconds;
+            }
+            return;
+        }
+
+        // Parts-count incremented — compute the delta. A negative delta
+        // means the cycle timer rolled over (or got reset by the operator)
+        // since the previous increment; per the plan we don't publish a
+        // negative LastCycleSeconds. Re-baseline so the next increment
+        // produces a clean delta.
+        var deltaSeconds = cycleTimerSeconds - prevTimer;
+        if (deltaSeconds < 0)
+        {
+            state.PreviousPartsCount = partsCount;
+            state.PreviousCycleTimerSeconds = cycleTimerSeconds;
+            return;
+        }
+
+        state.LastCycleSeconds = deltaSeconds;
+        state.LastCycleStartUtc = nowUtc.AddSeconds(-deltaSeconds);
+        state.PreviousPartsCount = partsCount;
+        state.PreviousCycleTimerSeconds = cycleTimerSeconds;
+        state.PreviousIncrementAtUtc = nowUtc;
+    }
+
     private DataValueSnapshot ReadProductionField(string hostAddress, string field, DateTime now)
     {
         if (!_devices.TryGetValue(hostAddress, out var device))
             return new DataValueSnapshot(null, FocasStatusMapper.BadNodeIdUnknown, null, now);
+
+        // F5-a derived telemetry (issue #272) — served from DeviceState.LastCycle*
+        // which the probe tick maintains alongside (not on top of) the wire-sourced
+        // production cache. Both fields surface Good with a null value when the
+        // derivation has not yet observed two successive parts-count increments;
+        // an OPC UA client that round-trips a null DateTime gets DateTime.MinValue
+        // through the variant boundary, which the documented "no cycle observed yet"
+        // sentinel makes safe to treat as "unknown".
+        if (string.Equals(field, "LastCycleSeconds", StringComparison.Ordinal))
+        {
+            return new DataValueSnapshot(
+                device.LastCycleSeconds,
+                FocasStatusMapper.Good,
+                device.LastCycleStartUtc,
+                now);
+        }
+        if (string.Equals(field, "LastCycleStartUtc", StringComparison.Ordinal))
+        {
+            return new DataValueSnapshot(
+                device.LastCycleStartUtc,
+                FocasStatusMapper.Good,
+                device.LastCycleStartUtc,
+                now);
+        }
+
         if (device.LastProduction is not { } snap)
             return new DataValueSnapshot(null, FocasStatusMapper.BadCommunicationError, null, now);
         var value = PickProductionField(snap, field);
@@ -1593,6 +1769,23 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
         public FocasProductionInfo? LastProduction { get; set; }
         public DateTime LastProductionUtc { get; set; }
 
+        /// <summary>
+        ///     Plan PR F5-a (issue #272) — derivation state for
+        ///     <c>Production/LastCycleSeconds</c> + <c>Production/LastCycleStartUtc</c>.
+        ///     Maintained by <see cref="FocasDriver.UpdateCycleDerivation"/> on every
+        ///     probe tick that returns a non-null production snapshot. All fields
+        ///     reset on <see cref="FocasDriver.ReinitializeAsync"/> via the
+        ///     ShutdownAsync → InitializeAsync path (DeviceState is reconstructed
+        ///     from scratch); the derivation history doesn't carry across a CNC
+        ///     reconnect because the FWLIB session boundary may have re-zeroed both
+        ///     parts-count and the cycle timer.
+        /// </summary>
+        public int? PreviousPartsCount { get; set; }
+        public double? PreviousCycleTimerSeconds { get; set; }
+        public DateTime? PreviousIncrementAtUtc { get; set; }
+        public double? LastCycleSeconds { get; set; }
+        public DateTime? LastCycleStartUtc { get; set; }
+
         /// <summary>
         ///     Cached <c>cnc_modal</c> M/S/T/B snapshot, refreshed on every probe tick.
         ///     Reads of the per-device <c>Modal/&lt;field&gt;</c> nodes serve from this cache

src/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient/OpcUaClientDiagnostics.cs

@@ -42,6 +42,12 @@ internal sealed class OpcUaClientDiagnostics
     // ---- Reconnect state (lock-free, single-writer in OnReconnectComplete) ----
     private long _lastReconnectUtcTicks;
 
+    // ---- Upstream-redundancy counters (PR-14) ----
+    private long _redundancyFailoverCount;
+    private long _redundancyFailoverFailures;
+    private string? _activeServerUri;
+    private readonly object _activeServerUriLock = new();
+
     public long PublishRequestCount => Interlocked.Read(ref _publishRequestCount);
     public long NotificationCount => Interlocked.Read(ref _notificationCount);
     public long MissingPublishRequestCount => Interlocked.Read(ref _missingPublishRequestCount);
@@ -110,6 +116,30 @@ internal sealed class OpcUaClientDiagnostics
         Interlocked.Exchange(ref _lastReconnectUtcTicks, nowUtc.Ticks);
     }
 
+    public long RedundancyFailoverCount => Interlocked.Read(ref _redundancyFailoverCount);
+    public long RedundancyFailoverFailures => Interlocked.Read(ref _redundancyFailoverFailures);
+
+    public string? ActiveServerUri
+    {
+        get { lock (_activeServerUriLock) return _activeServerUri; }
+    }
+
+    /// <summary>Records a successful redundancy failover and updates the active server URI.</summary>
+    public void RecordRedundancyFailover(string newServerUri)
+    {
+        Interlocked.Increment(ref _redundancyFailoverCount);
+        SetActiveServerUri(newServerUri);
+    }
+
+    /// <summary>Records a failover attempt that failed (e.g. TransferSubscriptions rejected, secondary unreachable).</summary>
+    public void RecordRedundancyFailoverFailure() => Interlocked.Increment(ref _redundancyFailoverFailures);
+
+    /// <summary>Sets the URI of the upstream the driver is currently bound to.</summary>
+    public void SetActiveServerUri(string? uri)
+    {
+        lock (_activeServerUriLock) _activeServerUri = uri;
+    }
+
     /// <summary>
     ///     Snapshot the counters into the dictionary shape <see cref="Core.Abstractions.DriverHealth.Diagnostics"/>
     ///     surfaces. Numeric-only (so the RPC can render generically); LastReconnectUtc is
@@ -117,7 +147,7 @@ internal sealed class OpcUaClientDiagnostics
     /// </summary>
     public IReadOnlyDictionary<string, double> Snapshot()
     {
-        var dict = new Dictionary<string, double>(7, System.StringComparer.Ordinal)
+        var dict = new Dictionary<string, double>(9, System.StringComparer.Ordinal)
         {
             ["PublishRequestCount"] = PublishRequestCount,
             ["NotificationCount"] = NotificationCount,
@@ -125,6 +155,8 @@ internal sealed class OpcUaClientDiagnostics
             ["MissingPublishRequestCount"] = MissingPublishRequestCount,
             ["DroppedNotificationCount"] = DroppedNotificationCount,
             ["SessionResetCount"] = SessionResetCount,
+            ["RedundancyFailoverCount"] = RedundancyFailoverCount,
+            ["RedundancyFailoverFailures"] = RedundancyFailoverFailures,
         };
         var last = LastReconnectUtc;
         if (last is not null)

src/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient/OpcUaClientDriver.cs

@@ -121,6 +121,61 @@ public sealed class OpcUaClientDriver(OpcUaClientDriverOptions options, string d
     /// </summary>
     internal void InjectModelChangeForTest() => OnModelChangeNotification();
 
+    // ---- PR-14 upstream-redundancy state ----
+
+    /// <summary>
+    ///     Cached redundancy peer list discovered at session activation. Empty when
+    ///     <see cref="RedundancyOptions.Enabled"/> is <c>false</c>, when the upstream
+    ///     advertises <c>RedundancySupport=None</c>, or before <see cref="InitializeAsync"/>
+    ///     completes. Ordered as the upstream returned it — failover walks this list in
+    ///     order, skipping the currently-active URI.
+    /// </summary>
+    private IReadOnlyList<string> _redundancyPeers = [];
+
+    /// <summary>
+    ///     Subscription that monitors <c>Server.ServiceLevel</c> on the active upstream
+    ///     so a drop propagates via PublishResponse rather than relying on a polling loop.
+    ///     Lives alongside the model-change subscription on the same session.
+    /// </summary>
+    private Subscription? _serviceLevelSubscription;
+
+    /// <summary>
+    ///     Last UTC tick a failover swap committed. Used to debounce oscillation around
+    ///     the threshold — see <see cref="RedundancyOptions.RecheckInterval"/>.
+    /// </summary>
+    private long _lastFailoverTicks;
+
+    /// <summary>
+    ///     Test seam — count of redundancy failover invocations the driver has fired.
+    ///     Mirrors the model-change reimport counter pattern.
+    /// </summary>
+    private long _redundancyFailoverInvocations;
+    internal long RedundancyFailoverInvocationsForTest => Interlocked.Read(ref _redundancyFailoverInvocations);
+
+    /// <summary>
+    ///     Test seam — exposes the cached redundancy peer list so unit tests can assert
+    ///     the discovery pass populated it correctly without mocking the OPC UA SDK's
+    ///     ServerArray read.
+    /// </summary>
+    internal IReadOnlyList<string> RedundancyPeersForTest => _redundancyPeers;
+
+    /// <summary>
+    ///     Test seam — fires before the actual failover swap. When non-null the hook runs
+    ///     <i>instead of</i> opening a new session + transferring subscriptions, so unit
+    ///     tests can assert "the driver decided to fail over" without standing up two real
+    ///     OPC UA sessions. Receives the chosen secondary URI; returns the swap outcome
+    ///     (true = success, false = failure to feed the failures counter).
+    /// </summary>
+    internal Func<string, CancellationToken, Task<bool>>? RedundancyFailoverHookForTest { get; set; }
+
+    /// <summary>
+    ///     Test seam — drive a synthetic ServiceLevel value into the failover path. Mirrors
+    ///     what the ServiceLevel monitored item does on a real <c>DataChangeNotification</c>
+    ///     arrival. Tests use this to assert threshold + RecheckInterval behaviour without
+    ///     standing up the SDK's subscription machinery.
+    /// </summary>
+    internal void InjectServiceLevelDropForTest(byte serviceLevel) => OnServiceLevelChanged(serviceLevel);
+
     /// <summary>Active OPC UA session. Null until <see cref="InitializeAsync"/> returns cleanly.</summary>
     internal ISession? Session { get; private set; }
 
@@ -317,6 +372,23 @@ public sealed class OpcUaClientDriver(OpcUaClientDriverOptions options, string d
                     // the absence of re-import on topology change rather than a hard init fail.
                 }
             }
+
+            // PR-14: discover the upstream's redundant peer list + start the ServiceLevel
+            // watch. Best-effort so an upstream advertising RedundancySupport=None (or one
+            // that simply doesn't expose the redundancy nodes) doesn't fail init — we just
+            // disable the failover path for the duration of this session.
+            if (_options.Redundancy.Enabled)
+            {
+                try
+                {
+                    await DiscoverRedundancyAsync(session, connectedUrl, cancellationToken).ConfigureAwait(false);
+                }
+                catch
+                {
+                    // best-effort — operators see this through the absence of failover on
+                    // ServiceLevel drop rather than a hard init fail.
+                }
+            }
         }
         catch (Exception ex)
         {
@@ -928,6 +1000,18 @@ public sealed class OpcUaClientDriver(OpcUaClientDriverOptions options, string d
         try { _modelChangeDebounceTimer?.Dispose(); } catch { }
         _modelChangeDebounceTimer = null;
 
+        // Tear down the redundancy ServiceLevel watch. Same best-effort pattern as the
+        // model-change subscription — if the wire-side delete fails the next init pass
+        // will still build a fresh subscription.
+        if (_serviceLevelSubscription is not null)
+        {
+            try { await _serviceLevelSubscription.DeleteAsync(silent: true, cancellationToken).ConfigureAwait(false); }
+            catch { /* best-effort */ }
+            _serviceLevelSubscription = null;
+        }
+        _redundancyPeers = [];
+        _diagnostics.SetActiveServerUri(null);
+
         // Abort any in-flight reconnect attempts before touching the session — BeginReconnect's
         // retry loop holds a reference to the current session and would fight Session.CloseAsync
         // if left spinning.
@@ -2597,6 +2681,307 @@ public sealed class OpcUaClientDriver(OpcUaClientDriverOptions options, string d
         public string DiagnosticId => $"opcua-alarm-sub-{Id}";
     }
 
+    // ---- PR-14 upstream-redundancy plumbing ----
+
+    /// <summary>
+    ///     Read <c>Server.ServerRedundancy.RedundancySupport</c> + <c>ServerUriArray</c>
+    ///     from the upstream so the driver knows whether to honour ServiceLevel-driven
+    ///     failover and where the peer set lives. When <c>RedundancySupport=None</c>
+    ///     the driver records an empty peer list — the ServiceLevel watch still runs but
+    ///     <see cref="OnServiceLevelChanged"/> short-circuits without trying to swap.
+    /// </summary>
+    /// <remarks>
+    ///     Per OPC UA Part 5 §6.3.13 the standard variable is
+    ///     <c>Server.ServerRedundancy.ServerUriArray</c>; the issue text refers to
+    ///     <c>Server.ServerArray</c> (top-level URIs the server federates over). We pull
+    ///     <c>ServerUriArray</c> as the canonical redundant-peer source — when missing
+    ///     we fall through to <c>Server.ServerArray</c> as a heuristic so the failover
+    ///     path still has a peer list against legacy servers that conflate the two.
+    /// </remarks>
+    private async Task DiscoverRedundancyAsync(ISession session, string? activeUrl, CancellationToken ct)
+    {
+        // RedundancySupport: when None, skip ServiceLevel watching entirely — the upstream
+        // explicitly declares it has no peers, so a drop is meaningless.
+        try
+        {
+            var rsValue = await session.ReadValueAsync(
+                VariableIds.Server_ServerRedundancy_RedundancySupport, ct).ConfigureAwait(false);
+            // The variable is an Int32-encoded RedundancySupport enum. 0 = None.
+            if (rsValue.Value is int rsInt && rsInt == (int)RedundancySupport.None)
+            {
+                _redundancyPeers = [];
+                _diagnostics.SetActiveServerUri(activeUrl);
+                return;
+            }
+        }
+        catch
+        {
+            // Upstream doesn't expose the variable — fall through and try ServerUriArray
+            // anyway; some servers ship the array without exposing RedundancySupport.
+        }
+
+        var peers = new List<string>();
+        try
+        {
+            var uriArrayValue = await session.ReadValueAsync(
+                VariableIds.Server_ServerRedundancy_ServerUriArray, ct).ConfigureAwait(false);
+            if (uriArrayValue.Value is string[] uris)
+            {
+                foreach (var u in uris)
+                    if (!string.IsNullOrWhiteSpace(u)) peers.Add(u);
+            }
+        }
+        catch
+        {
+            // ServerUriArray missing — try the top-level Server.ServerArray as the
+            // fallback the issue text hints at. Many servers populate this even when
+            // the redundancy node is absent.
+            try
+            {
+                var saValue = await session.ReadValueAsync(
+                    VariableIds.Server_ServerArray, ct).ConfigureAwait(false);
+                if (saValue.Value is string[] uris)
+                {
+                    foreach (var u in uris)
+                        if (!string.IsNullOrWhiteSpace(u)) peers.Add(u);
+                }
+            }
+            catch
+            {
+                // No peer list available from either node — leave _redundancyPeers empty;
+                // the ServiceLevel watch can still run but OnServiceLevelChanged will
+                // no-op since there's nowhere to fail over to.
+            }
+        }
+
+        _redundancyPeers = peers;
+        _diagnostics.SetActiveServerUri(activeUrl);
+
+        // Subscribe to ServiceLevel so a drop propagates via PublishResponse rather than
+        // a polling loop. Best-effort: a server that rejects the EventFilter still leaves
+        // the failover hook reachable from InjectServiceLevelDropForTest in tests.
+        try
+        {
+            await SubscribeServiceLevelAsync(session, ct).ConfigureAwait(false);
+        }
+        catch
+        {
+            // No subscription = no automatic failover; manual ReinitializeAsync still works.
+        }
+    }
+
+    /// <summary>
+    ///     Wire <c>Server.ServiceLevel</c> as a monitored item so a drop fires
+    ///     <see cref="OnServiceLevelChanged"/> via the SDK's notification path. Uses a
+    ///     dedicated <see cref="Subscription"/> rather than co-tenanting with the alarm
+    ///     subscription so the publish cadence can be tuned independently — service
+    ///     level rarely changes in steady state, so we use a 1s interval like the
+    ///     model-change watch.
+    /// </summary>
+    private async Task SubscribeServiceLevelAsync(ISession session, CancellationToken cancellationToken)
+    {
+        var subDefaults = _options.Subscriptions;
+        var subscription = new Subscription(telemetry: null!, new SubscriptionOptions
+        {
+            DisplayName = "opcua-servicelevel-watch",
+            PublishingInterval = 1000,
+            KeepAliveCount = (uint)subDefaults.KeepAliveCount,
+            LifetimeCount = subDefaults.LifetimeCount,
+            MaxNotificationsPerPublish = subDefaults.MaxNotificationsPerPublish,
+            PublishingEnabled = true,
+            Priority = subDefaults.Priority,
+            TimestampsToReturn = TimestampsToReturn.Both,
+        });
+
+        session.AddSubscription(subscription);
+        await subscription.CreateAsync(cancellationToken).ConfigureAwait(false);
+
+        var item = new MonitoredItem(telemetry: null!, new MonitoredItemOptions
+        {
+            DisplayName = "Server/ServiceLevel",
+            StartNodeId = VariableIds.Server_ServiceLevel,
+            AttributeId = Attributes.Value,
+            MonitoringMode = MonitoringMode.Reporting,
+            QueueSize = 1,
+            DiscardOldest = true,
+        });
+        item.Notification += OnServiceLevelNotification;
+        subscription.AddItem(item);
+        await subscription.CreateItemsAsync(cancellationToken).ConfigureAwait(false);
+
+        _serviceLevelSubscription = subscription;
+    }
+
+    private void OnServiceLevelNotification(MonitoredItem item, MonitoredItemNotificationEventArgs e)
+    {
+        // Drain any queued DataChangeNotifications. The SDK pushes one notification per
+        // change event; ServiceLevel is a Byte (0..255 per the spec) so a value of any
+        // other CLR type is a server bug — defensively coerce.
+        foreach (var dv in item.DequeueValues())
+        {
+            byte sl;
+            try { sl = Convert.ToByte(dv.Value, System.Globalization.CultureInfo.InvariantCulture); }
+            catch { continue; }
+            OnServiceLevelChanged(sl);
+        }
+    }
+
+    /// <summary>
+    ///     Triggered by every ServiceLevel data-change. When the value drops below
+    ///     <see cref="RedundancyOptions.ServiceLevelThreshold"/> AND we have a peer to
+    ///     swap to AND the recheck-interval window has elapsed since the last failover,
+    ///     kicks off <see cref="FailoverAsync"/>. All other paths short-circuit.
+    /// </summary>
+    private void OnServiceLevelChanged(byte serviceLevel)
+    {
+        if (!_options.Redundancy.Enabled) return;
+        if (serviceLevel >= _options.Redundancy.ServiceLevelThreshold) return;
+        if (_redundancyPeers.Count == 0) return;
+
+        // Recheck-interval guard: if a failover committed within the last RecheckInterval
+        // window, suppress further swaps. Without this a flapping ServiceLevel could
+        // ping-pong the driver between primary and secondary on every notification.
+        var nowTicks = DateTime.UtcNow.Ticks;
+        var lastTicks = Interlocked.Read(ref _lastFailoverTicks);
+        if (lastTicks != 0)
+        {
+            var elapsed = TimeSpan.FromTicks(nowTicks - lastTicks);
+            if (elapsed < _options.Redundancy.ResolvedRecheckInterval) return;
+        }
+
+        Interlocked.Increment(ref _redundancyFailoverInvocations);
+
+        // Pick the next peer that isn't the active URI. Round-robin within the cached list.
+        var active = _diagnostics.ActiveServerUri;
+        string? next = null;
+        foreach (var u in _redundancyPeers)
+        {
+            if (!string.Equals(u, active, StringComparison.OrdinalIgnoreCase))
+            {
+                next = u;
+                break;
+            }
+        }
+        if (next is null) return;
+
+        _ = FailoverAsync(next, CancellationToken.None);
+    }
+
+    /// <summary>
+    ///     Open a parallel session against <paramref name="newUri"/>, transfer live
+    ///     subscriptions onto it, swap <see cref="Session"/>, close the old one. On any
+    ///     failure leaves the existing session in place + increments the failures
+    ///     counter so operators see the dashboard reflect the failed swap.
+    /// </summary>
+    /// <remarks>
+    ///     <b>Shared client-cert prerequisite</b>: <c>TransferSubscriptionsAsync</c>
+    ///     requires the secondary's secure channel to accept the same client cert the
+    ///     primary did, otherwise the SDK returns <c>BadSecureChannelClosed</c> /
+    ///     <c>BadCertificateUntrusted</c> — see docs/drivers/OpcUaClient.md
+    ///     "Upstream redundancy" section for the certificate trust model.
+    /// </remarks>
+    private async Task FailoverAsync(string newUri, CancellationToken cancellationToken)
+    {
+        // Test seam: the unit tests use this hook to assert the driver decided to fail
+        // over without standing up a real ISession. The hook returns the swap outcome.
+        var hook = RedundancyFailoverHookForTest;
+        if (hook is not null)
+        {
+            try
+            {
+                var success = await hook(newUri, cancellationToken).ConfigureAwait(false);
+                if (success)
+                {
+                    Interlocked.Exchange(ref _lastFailoverTicks, DateTime.UtcNow.Ticks);
+                    _diagnostics.RecordRedundancyFailover(newUri);
+                }
+                else
+                {
+                    _diagnostics.RecordRedundancyFailoverFailure();
+                }
+            }
+            catch
+            {
+                _diagnostics.RecordRedundancyFailoverFailure();
+            }
+            return;
+        }
+
+        var oldSession = Session;
+        if (oldSession is null) return;
+
+        ISession? newSession = null;
+        await _gate.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            var appConfig = await BuildApplicationConfigurationAsync(cancellationToken).ConfigureAwait(false);
+            var identity = BuildUserIdentity(_options);
+            try
+            {
+                newSession = await OpenSessionOnEndpointAsync(
+                    appConfig, newUri, _options.SecurityPolicy, _options.SecurityMode,
+                    identity, cancellationToken).ConfigureAwait(false);
+            }
+            catch
+            {
+                _diagnostics.RecordRedundancyFailoverFailure();
+                return;
+            }
+
+            // TransferSubscriptions across all live subscriptions. SDK's TransferSubscriptionsAsync
+            // takes the source session + target subscriptions; if the secondary rejects any
+            // subscription the call returns false and we leave Session untouched.
+            try
+            {
+                var subs = new SubscriptionCollection();
+                foreach (var rs in _subscriptions.Values) subs.Add(rs.Subscription);
+                foreach (var ras in _alarmSubscriptions.Values) subs.Add(ras.Subscription);
+                if (_modelChangeSubscription is not null) subs.Add(_modelChangeSubscription);
+                if (_serviceLevelSubscription is not null) subs.Add(_serviceLevelSubscription);
+
+                if (subs.Count > 0)
+                {
+                    var transferred = await oldSession.TransferSubscriptionsAsync(
+                        subs, sendInitialValues: true, cancellationToken).ConfigureAwait(false);
+                    if (!transferred)
+                    {
+                        _diagnostics.RecordRedundancyFailoverFailure();
+                        try { if (newSession is Session s) await s.CloseAsync(cancellationToken).ConfigureAwait(false); } catch { }
+                        try { newSession?.Dispose(); } catch { }
+                        return;
+                    }
+                }
+            }
+            catch
+            {
+                _diagnostics.RecordRedundancyFailoverFailure();
+                try { if (newSession is Session s) await s.CloseAsync(cancellationToken).ConfigureAwait(false); } catch { }
+                try { newSession?.Dispose(); } catch { }
+                return;
+            }
+
+            // Swap. Move keep-alive + diagnostics hooks onto the new session so the
+            // failover-driven session continues to feed reconnect + counter pipelines.
+            if (_keepAliveHandler is not null)
+            {
+                try { oldSession.KeepAlive -= _keepAliveHandler; } catch { }
+                newSession.KeepAlive += _keepAliveHandler;
+            }
+            UnwireSessionDiagnostics(oldSession);
+            WireSessionDiagnostics(newSession);
+
+            Session = newSession;
+            _connectedEndpointUrl = newUri;
+            _operationLimits = null; // refetch against new server
+            Interlocked.Exchange(ref _lastFailoverTicks, DateTime.UtcNow.Ticks);
+            _diagnostics.RecordRedundancyFailover(newUri);
+
+            try { if (oldSession is Session os) await os.CloseAsync(cancellationToken).ConfigureAwait(false); } catch { }
+            try { oldSession.Dispose(); } catch { }
+        }
+        finally { _gate.Release(); }
+    }
+
     // ---- IHistoryProvider (passthrough to upstream server) ----
 
     public async Task<Core.Abstractions.HistoryReadResult> ReadRawAsync(
@@ -2700,22 +3085,238 @@ public sealed class OpcUaClientDriver(OpcUaClientDriverOptions options, string d
         finally { _gate.Release(); }
     }
 
-    /// <summary>Map <see cref="HistoryAggregateType"/> to the OPC UA Part 13 standard aggregate NodeId.</summary>
+    /// <summary>
+    ///     Map <see cref="HistoryAggregateType"/> to the OPC UA Part 13 standard aggregate
+    ///     NodeId. Each enum value resolves to <c>Opc.Ua.ObjectIds.AggregateFunction_*</c>;
+    ///     the upstream server may still reject individual aggregates with
+    ///     <c>BadAggregateNotSupported</c> on the per-row HistoryRead result — that's a
+    ///     server-capability signal, not a driver-side error, so callers should treat the
+    ///     mapping itself as best-effort.
+    /// </summary>
+    /// <exception cref="ArgumentOutOfRangeException">
+    ///     The supplied enum value is outside the declared <see cref="HistoryAggregateType"/>
+    ///     range — most likely a future-extension value the driver hasn't been recompiled for.
+    /// </exception>
     internal static NodeId MapAggregateToNodeId(HistoryAggregateType aggregate) => aggregate switch
     {
+        // ---- Original 5 (ordinals 0-4) ----
         HistoryAggregateType.Average => ObjectIds.AggregateFunction_Average,
         HistoryAggregateType.Minimum => ObjectIds.AggregateFunction_Minimum,
         HistoryAggregateType.Maximum => ObjectIds.AggregateFunction_Maximum,
         HistoryAggregateType.Total   => ObjectIds.AggregateFunction_Total,
         HistoryAggregateType.Count   => ObjectIds.AggregateFunction_Count,
+
+        // ---- Time-weighted averages ----
+        HistoryAggregateType.TimeAverage  => ObjectIds.AggregateFunction_TimeAverage,
+        HistoryAggregateType.TimeAverage2 => ObjectIds.AggregateFunction_TimeAverage2,
+
+        // ---- Interpolation ----
+        HistoryAggregateType.Interpolative => ObjectIds.AggregateFunction_Interpolative,
+
+        // ---- Min/Max with timestamps + range ----
+        HistoryAggregateType.MinimumActualTime => ObjectIds.AggregateFunction_MinimumActualTime,
+        HistoryAggregateType.MaximumActualTime => ObjectIds.AggregateFunction_MaximumActualTime,
+        HistoryAggregateType.Range  => ObjectIds.AggregateFunction_Range,
+        HistoryAggregateType.Range2 => ObjectIds.AggregateFunction_Range2,
+
+        // ---- Annotation / duration / quality coverage ----
+        HistoryAggregateType.AnnotationCount => ObjectIds.AggregateFunction_AnnotationCount,
+        HistoryAggregateType.DurationGood    => ObjectIds.AggregateFunction_DurationGood,
+        HistoryAggregateType.DurationBad     => ObjectIds.AggregateFunction_DurationBad,
+        HistoryAggregateType.PercentGood     => ObjectIds.AggregateFunction_PercentGood,
+        HistoryAggregateType.PercentBad      => ObjectIds.AggregateFunction_PercentBad,
+        HistoryAggregateType.WorstQuality    => ObjectIds.AggregateFunction_WorstQuality,
+        HistoryAggregateType.WorstQuality2   => ObjectIds.AggregateFunction_WorstQuality2,
+
+        // ---- Statistical ----
+        HistoryAggregateType.StandardDeviationSample     => ObjectIds.AggregateFunction_StandardDeviationSample,
+        HistoryAggregateType.StandardDeviationPopulation => ObjectIds.AggregateFunction_StandardDeviationPopulation,
+        HistoryAggregateType.VarianceSample              => ObjectIds.AggregateFunction_VarianceSample,
+        HistoryAggregateType.VariancePopulation          => ObjectIds.AggregateFunction_VariancePopulation,
+
+        // ---- State-based ----
+        HistoryAggregateType.NumberOfTransitions     => ObjectIds.AggregateFunction_NumberOfTransitions,
+        HistoryAggregateType.DurationInStateZero     => ObjectIds.AggregateFunction_DurationInStateZero,
+        HistoryAggregateType.DurationInStateNonZero  => ObjectIds.AggregateFunction_DurationInStateNonZero,
+
+        // ---- Interval bounds and deltas ----
+        HistoryAggregateType.Start      => ObjectIds.AggregateFunction_Start,
+        HistoryAggregateType.End        => ObjectIds.AggregateFunction_End,
+        HistoryAggregateType.Delta      => ObjectIds.AggregateFunction_Delta,
+        HistoryAggregateType.StartBound => ObjectIds.AggregateFunction_StartBound,
+        HistoryAggregateType.EndBound   => ObjectIds.AggregateFunction_EndBound,
+
         _ => throw new ArgumentOutOfRangeException(nameof(aggregate), aggregate, null),
     };
 
-    // ReadEventsAsync stays at the interface default (throws NotSupportedException) per
+    // The fixed-field ReadEventsAsync(sourceName,...) overload stays at the interface
-    // IHistoryProvider contract -- the OPC UA Client driver CAN forward HistoryReadEvents,
+    // default. The OPC UA Client driver implements the filter-aware
-    // but the call-site needs an EventFilter SelectClauses surface which the interface
+    // ReadEventsAsync(fullReference, EventHistoryRequest, ct) overload below — that one
-    // doesn't carry. Landing the event-history passthrough requires extending
+    // carries the EventFilter SelectClauses + WhereClause shape we need to translate the
-    // IHistoryProvider.ReadEventsAsync with a filter-spec parameter; out of scope for this PR.
+    // upstream ReadEventDetails verbatim.
+
+    /// <summary>
+    ///     Filter-aware HistoryReadEvents passthrough. Translates an
+    ///     <see cref="EventHistoryRequest"/> into an OPC UA <c>ReadEventDetails</c> + the
+    ///     filter the upstream server expects, calls
+    ///     <c>Session.HistoryReadAsync</c>, and unwraps the returned
+    ///     <see cref="HistoryEvent"/> into <see cref="HistoricalEventBatch"/> rows whose
+    ///     <see cref="HistoricalEventRow.Fields"/> dictionaries are keyed by the
+    ///     <see cref="SimpleAttributeSpec.FieldName"/> the caller supplied (so the
+    ///     server-side dispatcher can re-align with the wire-side SelectClause order).
+    /// </summary>
+    public async Task<HistoricalEventBatch> ReadEventsAsync(
+        string fullReference, EventHistoryRequest request, CancellationToken cancellationToken)
+    {
+        if (request is null) throw new ArgumentNullException(nameof(request));
+
+        // Default SelectClauses cover the standard BaseEventType columns when the caller
+        // didn't customize. Order matches BuildHistoryEvent on the server side so unfiltered
+        // browse-history clients see "EventId / SourceName / Time / Message / Severity".
+        var selectClauses = request.SelectClauses;
+        if (selectClauses is null || selectClauses.Count == 0)
+            selectClauses = DefaultEventSelectClauses;
+
+        var session = RequireSession();
+        var filter = ToOpcEventFilter(selectClauses, request.WhereClause, session.MessageContext);
+        var details = new ReadEventDetails
+        {
+            StartTime = request.StartTime,
+            EndTime = request.EndTime,
+            NumValuesPerNode = request.NumValuesPerNode,
+            Filter = filter,
+        };
+        if (!TryParseNodeId(session, fullReference, out var nodeId))
+        {
+            // Same shape ExecuteHistoryReadAsync uses for an unparseable NodeId — empty
+            // result, not an exception, so a batch HistoryReadEvents over many notifiers
+            // doesn't fail the whole request when one identifier is malformed.
+            return new HistoricalEventBatch([], null);
+        }
+
+        var nodesToRead = new HistoryReadValueIdCollection
+        {
+            new HistoryReadValueId { NodeId = nodeId },
+        };
+
+        await _gate.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            var resp = await session.HistoryReadAsync(
+                requestHeader: null,
+                historyReadDetails: new ExtensionObject(details),
+                timestampsToReturn: TimestampsToReturn.Both,
+                releaseContinuationPoints: false,
+                nodesToRead: nodesToRead,
+                ct: cancellationToken).ConfigureAwait(false);
+
+            if (resp.Results.Count == 0) return new HistoricalEventBatch([], null);
+            var r = resp.Results[0];
+
+            var rows = new List<HistoricalEventRow>();
+            if (r.HistoryData?.Body is HistoryEvent he)
+            {
+                foreach (var fieldList in he.Events)
+                {
+                    var dict = new Dictionary<string, object?>(selectClauses.Count, StringComparer.Ordinal);
+                    var values = fieldList.EventFields;
+                    // Walk SelectClauses + EventFields in lockstep — OPC UA Part 4 guarantees
+                    // the field order on the wire matches the SelectClauses we sent.
+                    var max = Math.Min(values.Count, selectClauses.Count);
+                    DateTimeOffset occurrence = default;
+                    for (var i = 0; i < max; i++)
+                    {
+                        var key = selectClauses[i].FieldName;
+                        var value = values[i].Value;
+                        dict[key] = value;
+                        // Capture occurrence time when we recognize a "Time" field — used for
+                        // ordering / windowing; the dictionary still carries it verbatim.
+                        if (occurrence == default && value is DateTime dtVal)
+                        {
+                            if (string.Equals(key, "Time", StringComparison.OrdinalIgnoreCase) ||
+                                IsTimeBrowsePath(selectClauses[i]))
+                            {
+                                occurrence = new DateTimeOffset(
+                                    DateTime.SpecifyKind(dtVal, DateTimeKind.Utc));
+                            }
+                        }
+                    }
+                    rows.Add(new HistoricalEventRow(dict, occurrence));
+                }
+            }
+
+            var contPt = r.ContinuationPoint is { Length: > 0 } ? r.ContinuationPoint : null;
+            return new HistoricalEventBatch(rows, contPt);
+        }
+        finally { _gate.Release(); }
+    }
+
+    /// <summary>
+    ///     Default SelectClause set for the filter-aware ReadEventsAsync overload when the
+    ///     caller didn't supply one. Matches <c>BuildHistoryEvent</c> on the server side so
+    ///     "no filter specified" still produces recognizable BaseEventType columns.
+    /// </summary>
+    internal static readonly IReadOnlyList<SimpleAttributeSpec> DefaultEventSelectClauses =
+    [
+        new SimpleAttributeSpec(null, ["EventId"], "EventId"),
+        new SimpleAttributeSpec(null, ["SourceName"], "SourceName"),
+        new SimpleAttributeSpec(null, ["Time"], "Time"),
+        new SimpleAttributeSpec(null, ["Message"], "Message"),
+        new SimpleAttributeSpec(null, ["Severity"], "Severity"),
+        new SimpleAttributeSpec(null, ["ReceiveTime"], "ReceiveTime"),
+    ];
+
+    /// <summary>
+    ///     Translate transport-neutral <see cref="EventHistoryRequest"/> filter pieces into
+    ///     an OPC UA <see cref="EventFilter"/>. The where-clause path forwards the encoded
+    ///     bytes verbatim — when present they were captured upstream of the driver
+    ///     (server-side wire decode) and the upstream server expects to re-decode them.
+    /// </summary>
+    internal static EventFilter ToOpcEventFilter(
+        IReadOnlyList<SimpleAttributeSpec> selectClauses,
+        ContentFilterSpec? whereClause,
+        IServiceMessageContext? messageContext = null)
+    {
+        var filter = new EventFilter();
+        foreach (var sc in selectClauses)
+        {
+            var operand = new SimpleAttributeOperand
+            {
+                TypeDefinitionId = sc.TypeDefinitionId is null
+                    ? ObjectTypeIds.BaseEventType
+                    : NodeId.Parse(sc.TypeDefinitionId),
+                BrowsePath = [.. sc.BrowsePath.Select(seg => new QualifiedName(seg))],
+                AttributeId = Attributes.Value,
+            };
+            filter.SelectClauses.Add(operand);
+        }
+        if (whereClause?.EncodedOperands is { Length: > 0 } bytes && messageContext is not null)
+        {
+            // Decode the wire-side ContentFilter the server-side dispatcher captured. We
+            // route through the SDK's BinaryDecoder using the live session's MessageContext
+            // so the upstream server sees an exact round-trip of the original bytes — the
+            // OPC UA Client driver is a passthrough for filter semantics; it does not
+            // evaluate them.
+            try
+            {
+                using var decoder = new BinaryDecoder(bytes, messageContext);
+                var decoded = decoder.ReadEncodeable(null, typeof(ContentFilter)) as ContentFilter;
+                if (decoded is not null) filter.WhereClause = decoded;
+            }
+            catch
+            {
+                // Best-effort — a malformed where-clause shouldn't poison the SelectClause path.
+            }
+        }
+        return filter;
+    }
+
+    private static bool IsTimeBrowsePath(SimpleAttributeSpec spec)
+    {
+        if (spec.BrowsePath.Count != 1) return false;
+        var seg = spec.BrowsePath[0];
+        return string.Equals(seg, "Time", StringComparison.OrdinalIgnoreCase);
+    }
 
     // ---- IHostConnectivityProbe ----
 

src/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient/OpcUaClientDriverOptions.cs

@@ -264,6 +264,79 @@ public sealed class OpcUaClientDriverOptions
     ///     plant network — the upstream server reaches out, the gateway listens.
     /// </summary>
     public ReverseConnectOptions ReverseConnect { get; init; } = new();
+
+    /// <summary>
+    ///     Upstream-redundancy configuration (PR-14, issue #286). Distinct from the
+    ///     boot-time failover sweep on <see cref="EndpointUrls"/> — this section governs
+    ///     <i>mid-session</i> failover driven by the upstream's own
+    ///     <c>ServerStatus.ServerArray</c> + <c>Server.ServiceLevel</c> nodes. When
+    ///     enabled, the driver reads the upstream's redundant peer list at session
+    ///     activation, monitors <c>ServiceLevel</c> via subscription, and promotes a
+    ///     secondary upstream when the active upstream's ServiceLevel drops below
+    ///     <see cref="RedundancyOptions.ServiceLevelThreshold"/>. Subscriptions transfer
+    ///     to the secondary so monitored-item handles survive the swap.
+    /// </summary>
+    public RedundancyOptions Redundancy { get; init; } = new();
+}
+
+/// <summary>
+///     Upstream-side redundancy knobs for the OPC UA Client driver. The OPC UA spec
+///     models redundant servers via <c>ServerStatus.ServerArray</c> (the peer URI list)
+///     and <c>Server.ServiceLevel</c> (an unsigned byte where higher = healthier; spec
+///     range is 0..255 with 200 typical for a healthy primary, 100..199 for degraded,
+///     0..99 for unrecoverable). When the upstream advertises non-<c>None</c>
+///     <c>ServerRedundancyType.RedundancySupport</c>, the driver subscribes to
+///     <c>ServiceLevel</c> on the active upstream and fails over to the next URI in
+///     <c>ServerArray</c> the moment a drop crosses
+///     <see cref="ServiceLevelThreshold"/>.
+/// </summary>
+/// <remarks>
+///     <para>
+///         <b>Shared client-cert prerequisite</b>: the failover path uses
+///         <c>Session.TransferSubscriptionsAsync</c> to migrate live subscriptions onto
+///         the secondary session, which means the secondary's secure-channel auth must
+///         accept the same client certificate the primary did. Operators running a
+///         heterogeneous secondary (different cert trust store) must fall back to
+///         re-creating subscriptions on the swap, which is tracked as a follow-up.
+///     </para>
+///     <para>
+///         <b>Why not unconditional</b>: this section defaults to disabled because most
+///         deployments wire client-side redundancy via <see cref="OpcUaClientDriverOptions.EndpointUrls"/>
+///         (one-shot connect failover). Upstream redundancy is opt-in so existing
+///         deployments don't suddenly start subscribing to <c>ServiceLevel</c> on every
+///         upstream, which would surprise operators reading their server's session list.
+///     </para>
+/// </remarks>
+/// <param name="Enabled">
+///     Enable mid-session failover driven by the upstream's <c>ServerArray</c> +
+///     <c>ServiceLevel</c>. Default <c>false</c> — opt-in so existing deployments
+///     keep the current "EndpointUrls is the failover list" semantics.
+/// </param>
+/// <param name="ServiceLevelThreshold">
+///     ServiceLevel value below which the driver triggers failover. Default 200 mirrors
+///     the OPC UA spec's "healthy" floor — anything below is at least degraded. Lower
+///     to 100 for "only fail over on unrecoverable drops", raise toward 255 for an
+///     aggressive failover policy that swaps on any health degradation.
+/// </param>
+/// <param name="RecheckInterval">
+///     Lower bound on time between two consecutive failovers when ServiceLevel oscillates.
+///     Without this guard a flapping primary (alternating 199 → 200 → 199) could trigger
+///     N failovers per second; the recheck window pins the rate at one swap per interval.
+///     Default 5 seconds — long enough to dampen oscillation, short enough that real
+///     drops still produce timely failover.
+/// </param>
+public sealed record RedundancyOptions(
+    bool Enabled = false,
+    ushort ServiceLevelThreshold = 200,
+    TimeSpan? RecheckInterval = null)
+{
+    /// <summary>
+    ///     Resolved recheck interval — defaults to 5 seconds when
+    ///     <see cref="RecheckInterval"/> is null. Property rather than ctor default so the
+    ///     record stays JSON-friendly (System.Text.Json doesn't honour
+    ///     parameter defaults on records when the property is missing).
+    /// </summary>
+    public TimeSpan ResolvedRecheckInterval => RecheckInterval ?? TimeSpan.FromSeconds(5);
 }
 
 /// <summary>

src/ZB.MOM.WW.OtOpcUa.Driver.S7.Cli/S7CommandBase.cs

@@ -50,6 +50,20 @@ public abstract class S7CommandBase : DriverCommandBase
         "the class default under Pg/Op/S7Basic.")]
     public ushort? RemoteTsap { get; init; }
 
+    [CommandOption("password", Description =
+        "Connection-level password emitted to the PLC right after OpenAsync. Used by hardened " +
+        "S7-300/400 deployments running protection levels 1-3 and S7-1200/1500 deployments with " +
+        "a connection-mechanism password set. Default unset. Never logged. NB: S7netplus 0.20 " +
+        "does not yet expose SendPassword — when the linked library lacks the API the CLI prints " +
+        "a warning and continues. See docs/v2/s7.md \"PLC password / protection levels\".")]
+    public string? Password { get; init; }
+
+    [CommandOption("protection-level", Description =
+        "Declarative hint about the PLC's protection scheme: Auto (default), None, Level1, Level2, " +
+        "Level3 (S7-300/400), or ConnectionMechanism (S7-1200/1500). Diagnostic hint only; the " +
+        "wire path is driven by --password.")]
+    public ProtectionLevel ProtectionLevel { get; init; } = ProtectionLevel.Auto;
+
     /// <inheritdoc />
     public override TimeSpan Timeout
     {
@@ -75,6 +89,8 @@ public abstract class S7CommandBase : DriverCommandBase
         TsapMode = TsapMode,
         LocalTsap = LocalTsap,
         RemoteTsap = RemoteTsap,
+        Password = string.IsNullOrEmpty(Password) ? null : Password,
+        ProtectionLevel = ProtectionLevel,
     };
 
     protected string DriverInstanceId => $"s7-cli-{Host}:{Port}";

src/ZB.MOM.WW.OtOpcUa.Driver.S7/S7Driver.cs

@@ -1,8 +1,11 @@
 using System.Buffers.Binary;
 using System.Collections.Generic;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
 using S7.Net;
 using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
 using ZB.MOM.WW.OtOpcUa.Driver.S7.SymbolImport;
+using ZB.MOM.WW.OtOpcUa.Driver.S7.Szl;
 
 namespace ZB.MOM.WW.OtOpcUa.Driver.S7;
 
@@ -96,6 +99,68 @@ public sealed class S7Driver(S7DriverOptions options, string driverInstanceId)
     private DriverHealth _health = new(DriverState.Unknown, null, null);
     private bool _disposed;
 
+    // ---- PR-S7-E1 — SZL / @System.* virtual address state ----
+    //
+    // SzlReader is the wire surface (interface so tests can substitute fakes); SzlCache
+    // is the per-driver TTL cache fronting every SZL read so a burst of @System.* reads
+    // from one OPC UA subscription tick produces exactly one wire request per SZL ID.
+    // Both are constructed in InitializeAsync once Plc is open; both stay null when
+    // ExposeSystemTags is false (cheap shortcut on the read path).
+    private IS7SzlReader? _szlReader;
+    private S7SzlCache? _szlCache;
+
+    /// <summary>
+    ///     PR-S7-E1 — test seam for the SZL wire reader. Setting this overrides the
+    ///     default <see cref="S7NetSzlReader"/> created from the live <see cref="Plc"/>
+    ///     so unit tests can drive <c>@System.*</c> reads with golden-byte payloads
+    ///     without needing a real PLC. Setting before <see cref="InitializeAsync"/> is
+    ///     fine — InitializeAsync only swaps in the production reader when this is null.
+    /// </summary>
+    internal IS7SzlReader? SzlReader
+    {
+        get => _szlReader;
+        set => _szlReader = value;
+    }
+
+    /// <summary>Test-only access to the SZL cache for assertions about TTL behaviour.</summary>
+    internal S7SzlCache? SzlCache => _szlCache;
+
+    // ---- PR-S7-E2 / #303 — connection-level password (SendPassword) seam ----
+    //
+    // AuthGate wraps the reflective probe over S7.Net.Plc.SendPassword; setting it
+    // before InitializeAsync lets unit tests inject a fake that reports
+    // SupportsSendPassword + observes the call without standing up a real PLC.
+    // Logger is an ILogger seam so the warning ("S7netplus does not expose
+    // SendPassword") and the success line ("S7 password sent") flow into Serilog
+    // through the host's default factory; tests inject a capturing logger.
+    private IS7PlcAuthGate? _authGate;
+    private ILogger<S7Driver> _logger = NullLogger<S7Driver>.Instance;
+
+    /// <summary>
+    ///     PR-S7-E2 — test seam for the password-send path. Setting before
+    ///     <see cref="InitializeAsync"/> overrides the default reflective gate so unit
+    ///     tests can verify the call site without needing a live PLC. <c>null</c> =
+    ///     production behaviour: <see cref="ReflectionS7PlcAuthGate"/> is constructed
+    ///     once <see cref="Plc"/> is open.
+    /// </summary>
+    internal IS7PlcAuthGate? AuthGate
+    {
+        get => _authGate;
+        set => _authGate = value;
+    }
+
+    /// <summary>
+    ///     PR-S7-E2 — ILogger seam. Production callers go through the host's DI
+    ///     container to wire a Serilog-backed <see cref="ILoggerFactory"/>; tests
+    ///     inject a capturing logger to assert the warning-vs-info contract on the
+    ///     password path.
+    /// </summary>
+    internal ILogger<S7Driver> Logger
+    {
+        get => _logger;
+        set => _logger = value ?? NullLogger<S7Driver>.Instance;
+    }
+
     // ---- Block-read coalescing diagnostics (PR-S7-B2) ----
     //
     // Counters surface through DriverHealth.Diagnostics so the driver-diagnostics
@@ -222,6 +287,21 @@ public sealed class S7Driver(S7DriverOptions options, string driverInstanceId)
             // CPUs negotiate 240 bytes; CPUs running the extended PDU advertise 480 or 960.
             _negotiatedPduSize = plc.MaxPDUSize;
 
+            // PR-S7-E1 — wire up the SZL reader + cache. The reader respects an explicit
+            // test-supplied override (set before InitializeAsync) so unit tests can drive
+            // @System.* reads with canned payloads; production constructs the live S7netplus-
+            // backed reader (which currently surfaces every read as "not supported" until
+            // S7netplus exposes a public ReadSzlAsync).
+            _szlReader ??= new S7NetSzlReader(plc);
+            _szlCache = new S7SzlCache(_options.SzlCacheTtl);
+
+            // PR-S7-E2 / #303 — connection-level password. After a clean OpenAsync, if the
+            // operator supplied Password, hand it to the auth gate. The gate is reflective
+            // over S7.Net.Plc.SendPassword by default; tests inject a fake. When S7netplus
+            // doesn't yet expose SendPassword (true for 0.20), we log a one-line warning
+            // and continue — failure shifts to first per-tag read on a hardened CPU.
+            await TrySendPlcPasswordAsync(plc, cts.Token).ConfigureAwait(false);
+
             // PR-S7-C5 — pre-flight PUT/GET enablement probe. After a clean OpenAsync,
             // issue a tiny 2-byte read against Probe.ProbeAddress (default MW0). Hardened
             // S7-1200 / S7-1500 CPUs that have PUT/GET communication disabled in TIA
@@ -288,6 +368,15 @@ public sealed class S7Driver(S7DriverOptions options, string driverInstanceId)
         // PR-S7-D2 — drop the post-fan-out tag list so a Reinit can rebuild it cleanly
         // without the previous run's UDT leaves leaking into the new tag map.
         _effectiveTags.Clear();
+        // PR-S7-E1 — drop the SZL state so a fresh Plc on Reinit gets fresh CPU info /
+        // cycle stats / diagnostic-buffer entries. Clearing here keeps the test-supplied
+        // SzlReader override intact (set before Initialize) so a Shutdown / re-Initialize
+        // cycle from a unit test can re-use the same fake reader.
+        _szlCache?.Clear();
+        _szlCache = null;
+        // _szlReader: keep an explicit test-supplied reader (set via SzlReader property);
+        // drop the production one tied to the now-closed Plc so re-Init constructs fresh.
+        if (_szlReader is S7NetSzlReader) _szlReader = null;
         _health = new DriverHealth(DriverState.Unknown, _health.LastSuccessfulRead, null);
         return Task.CompletedTask;
     }
@@ -308,10 +397,35 @@ public sealed class S7Driver(S7DriverOptions options, string driverInstanceId)
     public async Task<IReadOnlyList<DataValueSnapshot>> ReadAsync(
         IReadOnlyList<string> fullReferences, CancellationToken cancellationToken)
     {
-        var plc = RequirePlc();
         var now = DateTime.UtcNow;
         var results = new DataValueSnapshot[fullReferences.Count];
 
+        // PR-S7-E1 — short-circuit @System.* virtual addresses before taking the Plc
+        // gate. SZL reads don't go through the regular tag map / address parser; they
+        // dispatch through IS7SzlReader (cached for SzlCacheTtl) and parse with
+        // S7SzlParser. Doing this first means the test path can read @System.* without
+        // a Plc connection (the reader is injectable).
+        var nonSystemIndexes = new List<int>(fullReferences.Count);
+        for (var i = 0; i < fullReferences.Count; i++)
+        {
+            var name = fullReferences[i];
+            if (S7SystemTags.IsSystemAddress(name))
+            {
+                results[i] = await ReadSystemTagAsync(name, now, cancellationToken).ConfigureAwait(false);
+            }
+            else
+            {
+                nonSystemIndexes.Add(i);
+            }
+        }
+
+        // If every requested reference was a @System.* tag, we're done before touching
+        // the Plc gate at all — keeps the @System.* surface usable in test setups that
+        // injected an SzlReader without ever calling InitializeAsync against a real PLC.
+        if (nonSystemIndexes.Count == 0) return results;
+
+        var plc = RequirePlc();
+
         await _gate.WaitAsync(cancellationToken).ConfigureAwait(false);
         try
         {
@@ -321,9 +435,9 @@ public sealed class S7Driver(S7DriverOptions options, string driverInstanceId)
             // (arrays, strings, dates, 64-bit ints, UDT-fanout). Packable tags feed
             // the block-coalescing planner first (PR-S7-B2); whatever survives as a
             // singleton range falls through to the multi-var packer (PR-S7-B1).
-            var packableIndexes = new List<int>(fullReferences.Count);
+            var packableIndexes = new List<int>(nonSystemIndexes.Count);
             var fallbackIndexes = new List<int>();
-            for (var i = 0; i < fullReferences.Count; i++)
+            foreach (var i in nonSystemIndexes)
             {
                 var name = fullReferences[i];
                 if (!_tagsByName.TryGetValue(name, out var tag))
@@ -770,6 +884,105 @@ public sealed class S7Driver(S7DriverOptions options, string driverInstanceId)
         };
     }
 
+    /// <summary>
+    ///     PR-S7-E1 — read one virtual <c>@System.*</c> address by dispatching through
+    ///     the SZL cache + reader, parsing the raw payload, and projecting the requested
+    ///     scalar field. Surfaces <c>BadNotSupported</c> when the reader returns null
+    ///     (snap7 / S7netplus 0.20 / hardened CPUs that reject SZL); <c>BadNodeIdUnknown</c>
+    ///     when the address starts with <c>@System.</c> but doesn't match a known tag;
+    ///     <c>BadInternalError</c> when the parser throws on a malformed payload.
+    /// </summary>
+    private async Task<DataValueSnapshot> ReadSystemTagAsync(string address, DateTime now, CancellationToken ct)
+    {
+        if (!S7SystemTags.TryResolve(address, out var descriptor, out var diagBufferIndex) || descriptor is null)
+            return new DataValueSnapshot(null, StatusBadNodeIdUnknown, null, now);
+
+        var reader = _szlReader;
+        if (reader is null)
+        {
+            // No reader wired (driver not initialised + no test override) — surface
+            // BadNotSupported so a stray @System.* read doesn't masquerade as a code bug.
+            return new DataValueSnapshot(null, StatusBadNotSupported, null, now);
+        }
+
+        // Cache-front the wire read. When SzlCacheTtl is zero, the cache always misses
+        // (TimeSpan.Zero < TimeSpan.Zero is false → every entry is stale instantly).
+        // Lazily create the cache when InitializeAsync hasn't run yet (test seam) so
+        // repeated reads in a unit test still de-dup against the same cache instance.
+        _szlCache ??= new S7SzlCache(_options.SzlCacheTtl);
+        var cache = _szlCache;
+        byte[]? payload;
+        try
+        {
+            payload = await cache.GetOrFetchAsync(
+                descriptor.SzlId, descriptor.SzlIndex,
+                tok => reader.ReadSzlAsync(descriptor.SzlId, descriptor.SzlIndex, tok),
+                ct).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) { throw; }
+        catch
+        {
+            return new DataValueSnapshot(null, StatusBadCommunicationError, null, now);
+        }
+
+        if (payload is null)
+        {
+            // SZL not supported — snap7 and S7netplus 0.20 both land here.
+            return new DataValueSnapshot(null, StatusBadNotSupported, null, now);
+        }
+
+        try
+        {
+            var value = ProjectSystemTagValue(descriptor, diagBufferIndex, payload);
+            return new DataValueSnapshot(value, 0u, now, now);
+        }
+        catch (ArgumentException)
+        {
+            // Malformed SZL payload — surface BadInternalError so a downstream client can
+            // distinguish "wire failed" from "PLC sent garbage".
+            return new DataValueSnapshot(null, StatusBadInternalError, null, now);
+        }
+    }
+
+    /// <summary>
+    ///     Project a parsed SZL payload to the scalar value the requested
+    ///     <paramref name="descriptor"/> exposes.
+    /// </summary>
+    private object? ProjectSystemTagValue(
+        S7SystemTags.SystemTagDescriptor descriptor,
+        int diagBufferIndex,
+        byte[] payload)
+    {
+        switch (descriptor.Kind)
+        {
+            case S7SystemTags.SystemTagKind.CpuType:
+                return S7SzlParser.ParseCpuInfo(payload).CpuType;
+            case S7SystemTags.SystemTagKind.Firmware:
+                return S7SzlParser.ParseCpuInfo(payload).Firmware;
+            case S7SystemTags.SystemTagKind.OrderNo:
+                return S7SzlParser.ParseCpuInfo(payload).OrderNo;
+            case S7SystemTags.SystemTagKind.CycleMin:
+                return S7SzlParser.ParseCycleStats(payload).MinMs;
+            case S7SystemTags.SystemTagKind.CycleMax:
+                return S7SzlParser.ParseCycleStats(payload).MaxMs;
+            case S7SystemTags.SystemTagKind.CycleAvg:
+                return S7SzlParser.ParseCycleStats(payload).AvgMs;
+            case S7SystemTags.SystemTagKind.DiagBufferEntry:
+                var depth = Math.Min(_options.DiagBufferDepth, S7SystemTags.MaxDiagBufferDepth);
+                if (diagBufferIndex < 0 || diagBufferIndex >= depth)
+                    return null; // out of range — surface as null value with Good status
+                var entries = S7SzlParser.ParseDiagBuffer(payload, depth);
+                if (diagBufferIndex >= entries.Count) return null;
+                var e = entries[diagBufferIndex];
+                // Render each entry as one human-readable line — keeps the OPC UA surface
+                // a flat array of strings, which clients can split / grep without needing
+                // a custom structured DataType. Format is stable so log scrapers can parse it.
+                return $"{e.OccurrenceUtc:O} | 0x{e.EventId:X4} | prio={e.Priority} | {e.EventText}";
+            default:
+                return null;
+        }
+    }
+
     /// <summary>Map driver-internal <see cref="S7Area"/> to S7.Net's <see cref="global::S7.Net.DataType"/>.</summary>
     private static global::S7.Net.DataType MapArea(S7Area area) => area switch
     {
@@ -950,6 +1163,73 @@ public sealed class S7Driver(S7DriverOptions options, string driverInstanceId)
     private global::S7.Net.Plc RequirePlc() =>
         Plc ?? throw new InvalidOperationException("S7Driver not initialized");
 
+    /// <summary>
+    ///     PR-S7-E2 / #303 — emit the connection-level password to the freshly-opened PLC.
+    ///     Caller is <see cref="InitializeAsync"/>, immediately after <c>OpenAsync</c> and
+    ///     before <see cref="RunPreflightAsync"/> — that ordering matters because the
+    ///     pre-flight read is exactly the operation a hardened CPU will refuse without an
+    ///     unlock. No-op when <see cref="S7DriverOptions.Password"/> is null/empty (the
+    ///     standard development case). When the underlying S7netplus build doesn't expose
+    ///     <c>SendPassword</c>, surfaces a single warning log and continues — see the
+    ///     "Library limitation" remark on <see cref="S7DriverOptions.Password"/>.
+    /// </summary>
+    /// <remarks>
+    ///     <b>No-log invariant:</b> never include the password value in any log, exception
+    ///     message, or diagnostic surface. The host name is logged as the only identifier.
+    /// </remarks>
+    private async Task TrySendPlcPasswordAsync(global::S7.Net.Plc plc, CancellationToken ct)
+    {
+        var password = _options.Password;
+        if (string.IsNullOrEmpty(password)) return;
+
+        // Lazily build the gate so tests can pre-inject a fake; production gets the
+        // reflective gate over the live S7.Net.Plc instance.
+        _authGate ??= new ReflectionS7PlcAuthGate(plc);
+
+        if (!_authGate.SupportsSendPassword)
+        {
+            // Library doesn't oblige (S7netplus 0.20). Don't fail Init — emit one
+            // warning so the operator sees the limitation in Serilog, then continue.
+            // Hardened CPUs will surface a per-read failure later, which is the same
+            // shape as a missing PUT/GET enable.
+            _logger.LogWarning(
+                "S7 password is set on driver '{DriverInstanceId}' against host '{Host}', " +
+                "but the linked S7netplus library does not expose SendPassword; " +
+                "password is being ignored at the wire. Hardened-CPU connect may fail at " +
+                "first read. See docs/v2/s7.md \"PLC password / protection levels\" for the " +
+                "library-limitation note.",
+                DriverInstanceId, _options.Host);
+            return;
+        }
+
+        try
+        {
+            var sent = await _authGate.TrySendPasswordAsync(password, ct).ConfigureAwait(false);
+            if (sent)
+            {
+                // Identifier-only log line — no password leakage.
+                _logger.LogInformation(
+                    "S7 password sent for {Host} (driver '{DriverInstanceId}', protection {ProtectionLevel}).",
+                    _options.Host, DriverInstanceId, _options.ProtectionLevel);
+            }
+        }
+        catch (OperationCanceledException)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            // Wire reported auth-failed. Wrap in a clean InvalidOperationException so the
+            // operator sees a typed message rather than a raw S7.Net.PlcException stack;
+            // inner exception preserved for diagnostics. No password value in the message.
+            throw new InvalidOperationException(
+                $"S7 password authentication failed for host '{_options.Host}'. " +
+                "Check the protection password configured in TIA Portal's Protection & Security pane " +
+                "and the ProtectionLevel option matches the CPU's actual scheme.",
+                ex);
+        }
+    }
+
     /// <summary>
     ///     PR-S7-C5 — issue the post-<c>OpenAsync</c> pre-flight probe read against
     ///     <see cref="S7ProbeOptions.ProbeAddress"/> and translate a "PUT/GET disabled"
@@ -1080,6 +1360,53 @@ public sealed class S7Driver(S7DriverOptions options, string driverInstanceId)
                 IsAlarm: false,
                 WriteIdempotent: t.WriteIdempotent));
         }
+
+        // PR-S7-E1 / #302 — surface the SZL-backed @System.* virtual tags under a
+        // Diagnostics/ sub-folder when the operator has opted in. Variables are
+        // ViewOnly (SZL is read-only) and never historized / alarming.
+        if (_options.ExposeSystemTags)
+        {
+            var diag = folder.Folder(S7SystemTags.FolderName, S7SystemTags.FolderName);
+            // Static descriptors: CpuType / Firmware / OrderNo + 3 cycle-time scalars.
+            foreach (var d in S7SystemTags.Descriptors)
+            {
+                // Browse name strips the "@System." prefix — operators see "CpuType",
+                // "CycleMs.Min", etc. The full reference (used by ReadAsync) keeps the
+                // raw "@System.*" form so the system-tag short-circuit fires.
+                var browseName = d.Address[S7SystemTags.Prefix.Length..];
+                diag.Variable(browseName, browseName, new DriverAttributeInfo(
+                    FullName: d.Address,
+                    DriverDataType: d.DriverDataType,
+                    IsArray: false,
+                    ArrayDim: null,
+                    SecurityClass: SecurityClassification.ViewOnly,
+                    IsHistorized: false,
+                    IsAlarm: false,
+                    WriteIdempotent: false));
+            }
+
+            // Diagnostic-buffer entries — depth comes from S7DriverOptions.DiagBufferDepth
+            // (capped at MaxDiagBufferDepth = 50 to keep the browse tree readable).
+            var depth = Math.Clamp(_options.DiagBufferDepth, 0, S7SystemTags.MaxDiagBufferDepth);
+            if (depth > 0)
+            {
+                var bufFolder = diag.Folder("DiagBuffer", "DiagBuffer");
+                for (var i = 0; i < depth; i++)
+                {
+                    var browse = $"Entry[{i}]";
+                    var fullRef = $"{S7SystemTags.DiagBufferEntryPrefix}{i}]";
+                    bufFolder.Variable(browse, browse, new DriverAttributeInfo(
+                        FullName: fullRef,
+                        DriverDataType: DriverDataType.String,
+                        IsArray: false,
+                        ArrayDim: null,
+                        SecurityClass: SecurityClassification.ViewOnly,
+                        IsHistorized: false,
+                        IsAlarm: false,
+                        WriteIdempotent: false));
+                }
+            }
+        }
         return Task.CompletedTask;
     }
 

src/ZB.MOM.WW.OtOpcUa.Driver.S7/S7DriverFactoryExtensions.cs

@@ -85,6 +85,14 @@ public static class S7DriverFactoryExtensions
                 fallback: TsapMode.Auto),
             LocalTsap = dto.LocalTsap,
             RemoteTsap = dto.RemoteTsap,
+            // PR-S7-E2 / #303 — connection-level password + declarative protection-level
+            // hint. Password defaults to null (no auth) per the no-log invariant; an
+            // explicit empty-string in JSON also collapses to null so a "Password": ""
+            // typo doesn't try to send a 0-byte password to the PLC. ProtectionLevel
+            // defaults to Auto when the field is absent.
+            Password = string.IsNullOrEmpty(dto.Password) ? null : dto.Password,
+            ProtectionLevel = ParseEnum<ProtectionLevel>(dto.ProtectionLevel, driverInstanceId,
+                "ProtectionLevel", fallback: ProtectionLevel.Auto),
             ScanGroupIntervals = scanGroupMap,
             // PR-S7-D2 — UDT layout declarations referenced by tags whose UdtName is set.
             // Empty list when the config doesn't declare any UDTs (the typical scalar-only case).
@@ -264,6 +272,8 @@ public static class S7DriverFactoryExtensions
             RemoteTsap = options.RemoteTsap,
             ScanGroupIntervals = options.ScanGroupIntervals,
             Udts = options.Udts,
+            Password = options.Password,
+            ProtectionLevel = options.ProtectionLevel,
         };
     }
 
@@ -332,6 +342,26 @@ public static class S7DriverFactoryExtensions
         ///     See <c>docs/v2/s7.md</c> "UDT / STRUCT support" section.
         /// </summary>
         public List<S7UdtDto>? Udts { get; init; }
+
+        /// <summary>
+        ///     PR-S7-E2 / #303 — connection-level password emitted to the PLC right
+        ///     after <c>OpenAsync</c> succeeds and before the pre-flight PUT/GET probe
+        ///     runs. Default <c>null</c> = no password is sent (the standard case).
+        ///     <b>Secret:</b> never logged. See <c>docs/v2/s7.md</c> §"PLC password /
+        ///     protection levels" for the no-log invariant and the S7netplus 0.20
+        ///     library-limitation note.
+        /// </summary>
+        public string? Password { get; init; }
+
+        /// <summary>
+        ///     PR-S7-E2 / #303 — declarative hint about the protection scheme on the
+        ///     target PLC. One of <c>Auto</c> (default), <c>None</c>, <c>Level1</c>,
+        ///     <c>Level2</c>, <c>Level3</c> (S7-300/400), or <c>ConnectionMechanism</c>
+        ///     (S7-1200/1500). Surfaced via the driver-diagnostics RPC so a
+        ///     misconfigured "level 3 PLC seen as level 1" deployment is spottable
+        ///     from the Admin UI.
+        /// </summary>
+        public string? ProtectionLevel { get; init; }
     }
 
     internal sealed class S7TagDto

src/ZB.MOM.WW.OtOpcUa.Driver.S7/S7DriverOptions.cs

@@ -151,6 +151,132 @@ public sealed class S7DriverOptions
     ///     including the 4-level nesting cap and the Optimized-DB prerequisite.
     /// </summary>
     public IReadOnlyList<S7UdtDefinition> Udts { get; init; } = [];
+
+    /// <summary>
+    ///     PR-S7-E1 / #302 — when <c>true</c>, <see cref="S7Driver.DiscoverAsync"/> emits a
+    ///     <c>Diagnostics/</c> sub-folder under the driver root containing virtual
+    ///     <c>@System.*</c> variables backed by SZL (System Status List) reads:
+    ///     <c>CpuType</c>, <c>Firmware</c>, <c>OrderNo</c> (SZL 0x0011),
+    ///     <c>CycleMs.Min</c> / <c>.Max</c> / <c>.Avg</c> (SZL 0x0132 / 0x0432), and
+    ///     <c>DiagBuffer/Entry[0..N]</c> (SZL 0x00A0). Default <c>false</c> — operators opt
+    ///     in per driver instance because the virtual nodes show up in OPC UA Browse
+    ///     under every connected client.
+    /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         S7netplus 0.20 doesn't yet expose a public <c>ReadSzlAsync</c>, so the
+    ///         in-process default surfaces every SZL read as <c>BadNotSupported</c>. The
+    ///         tag tree still lights up — operators see the structure and can wire
+    ///         clients to it — only the values come back as not-supported. Tests inject
+    ///         a fake reader that returns golden bytes to prove the dispatch + parser
+    ///         + cache path works end-to-end. snap7 also doesn't implement SZL, so the
+    ///         integration-test surface inherits the same not-supported behaviour.
+    ///     </para>
+    /// </remarks>
+    public bool ExposeSystemTags { get; init; } = false;
+
+    /// <summary>
+    ///     PR-S7-E1 — number of diagnostic-buffer entries to discover under
+    ///     <c>Diagnostics/DiagBuffer/Entry[N]</c>. Capped at
+    ///     <see cref="Szl.S7SystemTags.MaxDiagBufferDepth"/> = 50; the default 10 mirrors
+    ///     the plan-section's "max-10 cap" guidance and matches typical SZL 0x00A0
+    ///     PDU-size budgets. Ignored when <see cref="ExposeSystemTags"/> is <c>false</c>.
+    /// </summary>
+    public int DiagBufferDepth { get; init; } = Szl.S7SystemTags.DefaultDiagBufferDepth;
+
+    /// <summary>
+    ///     PR-S7-E1 — TTL for the <see cref="Szl.S7SzlCache"/> that fronts every SZL
+    ///     wire request. Diagnostics shouldn't poll faster than this anyway; the
+    ///     default 5 s window means a burst of <c>@System.*</c> subscriptions ticking
+    ///     at 100 ms each produces exactly one wire request per distinct SZL ID per
+    ///     5-second window. Set to <see cref="TimeSpan.Zero"/> to disable caching
+    ///     (every read goes to the wire) — only useful for diagnostics tests.
+    /// </summary>
+    public TimeSpan SzlCacheTtl { get; init; } = TimeSpan.FromSeconds(5);
+
+    /// <summary>
+    ///     PR-S7-E2 / #303 — connection-level password emitted to the PLC right after
+    ///     <c>OpenAsync</c> succeeds and before the pre-flight PUT/GET probe runs. Used
+    ///     for hardened S7-300/400 deployments running protection level 1, 2 or 3, and
+    ///     for S7-1200/1500 deployments that have a connection-mechanism password set
+    ///     in TIA Portal's "Protection &amp; Security" pane. Default <c>null</c> = no
+    ///     password is sent (the standard case for development PLCs and freshly-flashed
+    ///     CPUs without a protection password).
+    /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         <b>No-log invariant.</b> <see cref="Password"/> is a secret. The driver
+    ///         MUST NOT log it; the override on <see cref="ToString"/> below redacts
+    ///         the field as <c>***</c>, and any new logging surface that touches an
+    ///         <see cref="S7DriverOptions"/> instance must continue to do the same.
+    ///         See <c>docs/v2/s7.md</c> §"PLC password / protection levels".
+    ///     </para>
+    ///     <para>
+    ///         <b>Library limitation.</b> S7netplus 0.20 does not expose a public
+    ///         <c>SendPassword</c> method. When <see cref="Password"/> is set on a
+    ///         driver linked against a library version that lacks the API, the driver
+    ///         logs a one-line warning at Init time and continues — the connection
+    ///         succeeds at the COTP layer but a hardened CPU may then refuse the very
+    ///         first read with a "function not allowed" PDU. The driver discovers the
+    ///         method reflectively (<see cref="ReflectionS7PlcAuthGate"/>), so a future
+    ///         S7netplus minor release that adds <c>SendPasswordAsync(string,
+    ///         CancellationToken)</c> or <c>SendPassword(string)</c> gets used
+    ///         automatically without requiring a code change in this driver.
+    ///     </para>
+    /// </remarks>
+    public string? Password { get; init; }
+
+    /// <summary>
+    ///     PR-S7-E2 / #303 — declarative hint about the protection scheme the operator
+    ///     expects on the target PLC. The driver currently uses this for diagnostics
+    ///     and forward-compat (the value is exposed via the driver-diagnostics RPC
+    ///     surface so a misconfigured "level 3 PLC seen as level 1" deployment can be
+    ///     spotted from the Admin UI), and as a place to hang per-protection-level
+    ///     behaviour as S7netplus matures. Default <see cref="ProtectionLevel.Auto"/> =
+    ///     no hint, which matches existing behaviour.
+    /// </summary>
+    public ProtectionLevel ProtectionLevel { get; init; } = ProtectionLevel.Auto;
+
+    /// <summary>
+    ///     Override the auto-generated reference-typed <c>ToString</c> with one that
+    ///     redacts <see cref="Password"/>. Mirrors the FOCAS-F4-d
+    ///     <c>FocasDeviceOptions.PrintMembers</c> pattern (which uses positional-record
+    ///     plumbing); this class is a reference type, so an explicit override is the
+    ///     cheap equivalent. Field set kept compact — only the fields an operator is
+    ///     likely to want in a log line are emitted.
+    /// </summary>
+    public override string ToString() =>
+        $"S7DriverOptions {{ Host = {Host}, Port = {Port}, CpuType = {CpuType}, " +
+        $"Rack = {Rack}, Slot = {Slot}, TsapMode = {TsapMode}, " +
+        $"ProtectionLevel = {ProtectionLevel}, Password = {(Password is null ? "<null>" : "***")} }}";
+}
+
+/// <summary>
+///     PR-S7-E2 / #303 — declarative hint about the protection scheme on the target
+///     PLC. S7-300/400 firmware exposes three CPU-side levels via the
+///     <c>SFC 109 / 110</c> family; S7-1200/1500 firmware uses TIA Portal's "Connection
+///     Mechanism" instead (a single PUT/GET-vs-password switch with a different wire
+///     handshake). The enum carries both vocabularies and Auto for the no-hint case.
+/// </summary>
+public enum ProtectionLevel
+{
+    /// <summary>No declared protection scheme — driver doesn't surface a hint. Default.</summary>
+    Auto,
+
+    /// <summary>Operator asserts the PLC has no protection set. Equivalent to Auto for the wire path; surfaces as "None" in diagnostics.</summary>
+    None,
+
+    /// <summary>S7-300/400 protection level 1 — write-protected unless password is supplied.</summary>
+    Level1,
+
+    /// <summary>S7-300/400 protection level 2 — read- and write-protected unless password is supplied.</summary>
+    Level2,
+
+    /// <summary>S7-300/400 protection level 3 — full protection, all reads/writes require password.</summary>
+    Level3,
+
+    /// <summary>S7-1200/1500 "Connection Mechanism" password gate (TIA Portal Protection &amp; Security pane).</summary>
+    ConnectionMechanism,
 }
 
 /// <summary>

src/ZB.MOM.WW.OtOpcUa.Driver.S7/S7PlcAuthGate.cs

@@ -0,0 +1,124 @@
+using System.Reflection;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.S7;
+
+/// <summary>
+///     PR-S7-E2 / #303 — narrow seam covering the "send a password to a hardened CPU"
+///     wire path. <see cref="S7Driver.InitializeAsync"/> calls
+///     <see cref="TrySendPasswordAsync"/> after <c>OpenAsync</c> succeeds and before the
+///     pre-flight PUT/GET probe runs, so a hardened S7-1500 / ET 200SP CPU that gates
+///     reads behind a connection-level password unlocks before the probe drops it.
+/// </summary>
+/// <remarks>
+///     <para>
+///         The runtime implementation (<see cref="ReflectionS7PlcAuthGate"/>) discovers
+///         the underlying <c>S7.Net.Plc.SendPassword</c> / <c>SendPasswordAsync</c>
+///         methods reflectively because S7netplus 0.20 doesn't yet expose them in a
+///         strongly-typed surface — the seam keeps this driver compiling against the
+///         current pinned package version while still calling whatever the next minor
+///         release ships. When neither method exists,
+///         <see cref="SupportsSendPassword"/> stays <c>false</c> and
+///         <see cref="TrySendPasswordAsync"/> is a no-op so a misconfigured "Password
+///         set, library doesn't oblige" deployment surfaces as a one-line warning at
+///         Init rather than a hard failure (failure shifts to first per-tag read on the
+///         hardened CPU, which is the same shape as if the operator had forgotten to
+///         enable PUT/GET).
+///     </para>
+///     <para>
+///         Tests inject a fake to exercise both branches without touching the live
+///         S7netplus stack.
+///     </para>
+/// </remarks>
+internal interface IS7PlcAuthGate
+{
+    /// <summary>
+    ///     <c>true</c> when the underlying S7netplus <c>Plc</c> exposes a public
+    ///     <c>SendPassword(string)</c> or <c>SendPasswordAsync(string, CancellationToken)</c>
+    ///     method. <c>false</c> on S7netplus 0.20 (which has no such surface).
+    /// </summary>
+    bool SupportsSendPassword { get; }
+
+    /// <summary>
+    ///     Send <paramref name="password"/> to the connected PLC. No-op (and returns
+    ///     <c>false</c>) when <see cref="SupportsSendPassword"/> is <c>false</c>;
+    ///     returns <c>true</c> after a successful send. Throws cleanly when the wire
+    ///     reports auth-failed — <see cref="S7Driver.InitializeAsync"/> wraps the
+    ///     throw into a typed <see cref="InvalidOperationException"/> so the operator
+    ///     sees a "password authentication failed" message rather than a generic
+    ///     <c>S7.Net.PlcException</c>.
+    /// </summary>
+    Task<bool> TrySendPasswordAsync(string password, CancellationToken cancellationToken);
+}
+
+/// <summary>
+///     Production <see cref="IS7PlcAuthGate"/> backed by reflection over the S7netplus
+///     <c>S7.Net.Plc</c> instance. S7netplus 0.20 does NOT expose a
+///     <c>SendPassword</c>; the reflection probe survives that gracefully and a future
+///     0.21+ that adds the API gets called automatically without a code change here.
+/// </summary>
+internal sealed class ReflectionS7PlcAuthGate : IS7PlcAuthGate
+{
+    private readonly object _plc;
+    private readonly MethodInfo? _syncMethod;
+    private readonly MethodInfo? _asyncMethod;
+
+    public ReflectionS7PlcAuthGate(object plc)
+    {
+        _plc = plc ?? throw new ArgumentNullException(nameof(plc));
+        var type = plc.GetType();
+
+        // Probe both shapes: synchronous void SendPassword(string) and async
+        // Task SendPasswordAsync(string, CancellationToken). Either is acceptable;
+        // the async overload wins when both exist (no thread-block on init).
+        _asyncMethod = type.GetMethod(
+            "SendPasswordAsync",
+            BindingFlags.Instance | BindingFlags.Public,
+            binder: null,
+            types: [typeof(string), typeof(CancellationToken)],
+            modifiers: null);
+        _syncMethod = type.GetMethod(
+            "SendPassword",
+            BindingFlags.Instance | BindingFlags.Public,
+            binder: null,
+            types: [typeof(string)],
+            modifiers: null);
+    }
+
+    public bool SupportsSendPassword => _asyncMethod is not null || _syncMethod is not null;
+
+    public async Task<bool> TrySendPasswordAsync(string password, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(password);
+        if (_asyncMethod is not null)
+        {
+            // Unwrap TargetInvocationException so the caller sees the real S7.Net.PlcException
+            // (or whatever the library threw) rather than the reflection wrapper.
+            try
+            {
+                var result = _asyncMethod.Invoke(_plc, [password, cancellationToken]);
+                if (result is Task task)
+                {
+                    await task.ConfigureAwait(false);
+                }
+                return true;
+            }
+            catch (TargetInvocationException tie) when (tie.InnerException is not null)
+            {
+                throw tie.InnerException;
+            }
+        }
+        if (_syncMethod is not null)
+        {
+            try
+            {
+                _syncMethod.Invoke(_plc, [password]);
+                return true;
+            }
+            catch (TargetInvocationException tie) when (tie.InnerException is not null)
+            {
+                throw tie.InnerException;
+            }
+        }
+        return false;
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.S7/Szl/IS7SzlReader.cs

@@ -0,0 +1,35 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.S7.Szl;
+
+/// <summary>
+///     PR-S7-E1 — abstraction over SZL (System Status List) wire reads. The driver dispatches
+///     <c>@System.*</c> virtual reads through this interface so the parser code never depends
+///     on a specific transport. Concrete implementations:
+///     <list type="bullet">
+///         <item>
+///             <see cref="S7NetSzlReader"/> — the production implementation. S7netplus 0.20
+///             does not expose a public <c>ReadSzlAsync</c> API (the SZL request builder is
+///             internal), so this implementation returns <c>null</c> on every call —
+///             surfacing as <c>BadNotSupported</c> at the OPC UA layer. Replace once
+///             S7netplus exposes a public surface or we ship a raw-PDU helper.
+///         </item>
+///         <item>
+///             A test fake that returns canned byte payloads — used by the
+///             driver-side unit tests in <c>tests/.../Szl/</c>.
+///         </item>
+///     </list>
+/// </summary>
+public interface IS7SzlReader
+{
+    /// <summary>
+    ///     Read SZL <paramref name="szlId"/> at <paramref name="szlIndex"/> and return the
+    ///     payload <em>without</em> the S7comm parameter / data headers — the response is
+    ///     positioned at the SZL header (<c>SzlId | SzlIndex | LenThdr | NDr</c>) so it can
+    ///     feed <see cref="S7SzlParser"/> directly.
+    /// </summary>
+    /// <returns>
+    ///     Byte payload on success, or <c>null</c> when the SZL read is unsupported (snap7,
+    ///     S7netplus 0.20 without raw PDU helper, hardened CPUs that reject the SZL
+    ///     function code). The caller surfaces <c>null</c> as <c>BadNotSupported</c>.
+    /// </returns>
+    Task<byte[]?> ReadSzlAsync(ushort szlId, ushort szlIndex, CancellationToken cancellationToken);
+}

src/ZB.MOM.WW.OtOpcUa.Driver.S7/Szl/S7NetSzlReader.cs

@@ -0,0 +1,49 @@
+using S7.Net;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.S7.Szl;
+
+/// <summary>
+///     PR-S7-E1 — production <see cref="IS7SzlReader"/> backed by S7netplus's
+///     <see cref="Plc"/> connection. S7netplus 0.20 builds SZL request packages
+///     internally (<c>SzlReadRequestPackage</c> / <c>WriteSzlReadRequest</c>) but does
+///     <b>not</b> expose a public <c>ReadSzlAsync</c> API, so this implementation
+///     currently returns <c>null</c> on every call — the SZL feature surface ships as
+///     <c>BadNotSupported</c> through the OPC UA address space until either
+///     <list type="bullet">
+///         <item>S7netplus publishes a stable public SZL surface (tracked upstream), or</item>
+///         <item>We ship a raw S7comm PDU helper that side-steps the library.</item>
+///     </list>
+/// </summary>
+/// <remarks>
+///     <para>
+///         The driver-side parser code (<see cref="S7SzlParser"/>) is fully tested
+///         against golden bytes regardless — when the wire path lights up the parser
+///         starts producing real CPU info / cycle stats / diagnostic-buffer entries
+///         without further changes. Tests inject a fake <see cref="IS7SzlReader"/>
+///         to exercise the dispatch + caching paths.
+///     </para>
+///     <para>
+///         <b>Why no raw socket today?</b> S7netplus's <c>_stream</c> + <c>tcpClient</c>
+///         fields are <c>private</c> and the request-builder helpers are <c>internal</c>.
+///         Reflecting into them would break on every minor S7netplus release; the cost-
+///         benefit only flips once the SZL feature has live customer demand.
+///     </para>
+/// </remarks>
+public sealed class S7NetSzlReader(Plc plc) : IS7SzlReader
+{
+#pragma warning disable IDE0052 // unused while raw-PDU support is gated behind public S7netplus API
+    private readonly Plc _plc = plc ?? throw new ArgumentNullException(nameof(plc));
+#pragma warning restore IDE0052
+
+    /// <inheritdoc />
+    public Task<byte[]?> ReadSzlAsync(ushort szlId, ushort szlIndex, CancellationToken cancellationToken)
+    {
+        // S7netplus 0.20 doesn't expose a public ReadSzlAsync — surface every SZL request
+        // as "not supported" so the OPC UA layer maps it to BadNotSupported. The parser
+        // code is wired and tested; flipping this method to a real implementation is the
+        // only change needed when S7netplus catches up. Synchronous return because
+        // there's no I/O to await — keep the signature for future-proofing.
+        cancellationToken.ThrowIfCancellationRequested();
+        return Task.FromResult<byte[]?>(null);
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.S7/Szl/S7SystemTags.cs

@@ -0,0 +1,113 @@
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.S7.Szl;
+
+/// <summary>
+///     PR-S7-E1 — virtual <c>@System.*</c> address map. Each entry pairs the public
+///     address (e.g. <c>@System.CpuType</c>) with the SZL ID + index it dispatches
+///     against and a field-extractor that pulls the requested scalar out of the parsed
+///     payload. The driver short-circuits any <see cref="S7Driver.ReadAsync"/> reference
+///     whose name starts with <c>@System.</c> through this table — there's no Plc
+///     round-trip for non-SZL paths.
+/// </summary>
+/// <remarks>
+///     <para>
+///         The map is <em>static</em> because the SZL surface doesn't change between
+///         deployments — every CPU answers the same SZL IDs (or returns "not supported"
+///         uniformly). The diagnostic-buffer entries <c>@System.DiagBuffer.Entry[N]</c>
+///         are not in the table; the driver computes their address dynamically from the
+///         parsed entry list because the depth is configurable via
+///         <see cref="S7DriverOptions.DiagBufferDepth"/>.
+///     </para>
+/// </remarks>
+public static class S7SystemTags
+{
+    /// <summary>Prefix every virtual system tag carries on the wire.</summary>
+    public const string Prefix = "@System.";
+
+    /// <summary>Browse-tree folder name where the driver's discovery step emits the system-tag variables.</summary>
+    public const string FolderName = "Diagnostics";
+
+    /// <summary>Maximum diagnostic-buffer entries the driver discovers / reads (capped to keep the OPC UA browse tree readable).</summary>
+    public const int MaxDiagBufferDepth = 50;
+
+    /// <summary>Default diagnostic-buffer depth — matches the plan-section's "10 entries" baseline.</summary>
+    public const int DefaultDiagBufferDepth = 10;
+
+    /// <summary>Address prefix for diagnostic-buffer entries: <c>@System.DiagBuffer.Entry[N]</c>.</summary>
+    public const string DiagBufferEntryPrefix = "@System.DiagBuffer.Entry[";
+
+    /// <summary>OPC UA data type each system tag projects as. Used by both the driver's discovery step and its read-result boxing.</summary>
+    public sealed record SystemTagDescriptor(
+        string Address,
+        ushort SzlId,
+        ushort SzlIndex,
+        DriverDataType DriverDataType,
+        SystemTagKind Kind);
+
+    /// <summary>What kind of value the descriptor extracts from its SZL payload.</summary>
+    public enum SystemTagKind
+    {
+        CpuType,
+        Firmware,
+        OrderNo,
+        CycleMin,
+        CycleMax,
+        CycleAvg,
+        DiagBufferEntry, // resolved dynamically via the entry index encoded in the address
+    }
+
+    /// <summary>Static descriptors for the non-buffer system tags (CPU info + cycle-time scalars).</summary>
+    public static readonly IReadOnlyList<SystemTagDescriptor> Descriptors =
+    [
+        new("@System.CpuType",      S7SzlIds.ModuleIdentification, 0x0000, DriverDataType.String,  SystemTagKind.CpuType),
+        new("@System.Firmware",     S7SzlIds.ModuleIdentification, 0x0000, DriverDataType.String,  SystemTagKind.Firmware),
+        new("@System.OrderNo",      S7SzlIds.ModuleIdentification, 0x0000, DriverDataType.String,  SystemTagKind.OrderNo),
+        new("@System.CycleMs.Min",  S7SzlIds.CpuStatusData,        S7SzlIds.CpuStatusCycleTimeIndex, DriverDataType.Float64, SystemTagKind.CycleMin),
+        new("@System.CycleMs.Max",  S7SzlIds.CpuStatusData,        S7SzlIds.CpuStatusCycleTimeIndex, DriverDataType.Float64, SystemTagKind.CycleMax),
+        new("@System.CycleMs.Avg",  S7SzlIds.CpuStatusData,        S7SzlIds.CpuStatusCycleTimeIndex, DriverDataType.Float64, SystemTagKind.CycleAvg),
+    ];
+
+    /// <summary>True when <paramref name="address"/> is a recognised virtual system address.</summary>
+    public static bool IsSystemAddress(string address)
+        => address is not null && address.StartsWith(Prefix, StringComparison.Ordinal);
+
+    /// <summary>
+    ///     Resolve a virtual address to a (SzlId, SzlIndex, kind, optional buffer index)
+    ///     dispatch tuple. Returns <c>false</c> when the address starts with the prefix but
+    ///     doesn't match a known descriptor — the caller surfaces that as
+    ///     <c>BadNodeIdUnknown</c>.
+    /// </summary>
+    public static bool TryResolve(string address, out SystemTagDescriptor? descriptor, out int diagBufferIndex)
+    {
+        descriptor = null;
+        diagBufferIndex = -1;
+        if (string.IsNullOrEmpty(address)) return false;
+
+        // Diagnostic-buffer entries: @System.DiagBuffer.Entry[N]
+        if (address.StartsWith(DiagBufferEntryPrefix, StringComparison.Ordinal) && address.EndsWith(']'))
+        {
+            var idxStr = address[DiagBufferEntryPrefix.Length..^1];
+            if (!int.TryParse(idxStr, out var idx) || idx < 0 || idx >= MaxDiagBufferDepth)
+                return false;
+            diagBufferIndex = idx;
+            descriptor = new SystemTagDescriptor(
+                address,
+                S7SzlIds.DiagnosticBuffer,
+                0x0000,
+                DriverDataType.String,
+                SystemTagKind.DiagBufferEntry);
+            return true;
+        }
+
+        foreach (var d in Descriptors)
+        {
+            if (string.Equals(d.Address, address, StringComparison.Ordinal))
+            {
+                descriptor = d;
+                return true;
+            }
+        }
+        return false;
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.S7/Szl/S7SzlCache.cs

@@ -0,0 +1,64 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.S7.Szl;
+
+/// <summary>
+///     PR-S7-E1 — short-TTL cache of SZL responses keyed by <c>(SzlId, SzlIndex)</c>.
+///     A diagnostics-only feature should never hammer the comms mailbox; one read per
+///     SZL ID per <see cref="Ttl"/> window is the intended ceiling. Cache state is
+///     thread-safe — <see cref="GetOrFetchAsync"/> serialises concurrent fetchers per
+///     key so a burst of <c>@System.*</c> reads from one OPC UA subscription tick
+///     produces exactly one wire request per distinct SZL.
+/// </summary>
+public sealed class S7SzlCache(TimeSpan ttl, Func<DateTime>? clock = null)
+{
+    private readonly TimeSpan _ttl = ttl;
+    private readonly Func<DateTime> _clock = clock ?? (() => DateTime.UtcNow);
+    private readonly object _gate = new();
+    private readonly Dictionary<(ushort SzlId, ushort SzlIndex), CacheEntry> _entries = new();
+
+    /// <summary>Configured TTL — exposed for diagnostics / test assertions.</summary>
+    public TimeSpan Ttl => _ttl;
+
+    /// <summary>
+    ///     Look up <paramref name="szlId"/> / <paramref name="szlIndex"/> in the cache; on
+    ///     miss or stale entry, invoke <paramref name="fetcher"/> exactly once and store the
+    ///     result. Negative cache (null payload) is intentionally <em>also</em> cached for
+    ///     the TTL window — repeatedly hammering a CPU that has already said "not supported"
+    ///     wouldn't help anything.
+    /// </summary>
+    public async Task<byte[]?> GetOrFetchAsync(
+        ushort szlId,
+        ushort szlIndex,
+        Func<CancellationToken, Task<byte[]?>> fetcher,
+        CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(fetcher);
+        var key = (szlId, szlIndex);
+        var now = _clock();
+
+        // Phase 1: cache hit — return without taking any locks beyond the dictionary lookup.
+        lock (_gate)
+        {
+            if (_entries.TryGetValue(key, out var hit) && now - hit.FetchedAtUtc < _ttl)
+                return hit.Payload;
+        }
+
+        // Phase 2: miss — fetch outside the lock so concurrent keys don't serialize on
+        // each other. We accept a small race where two callers both miss + both fetch on
+        // the same key; the second store wins, which is fine for a TTL cache.
+        var payload = await fetcher(cancellationToken).ConfigureAwait(false);
+
+        lock (_gate)
+        {
+            _entries[key] = new CacheEntry(payload, _clock());
+        }
+        return payload;
+    }
+
+    /// <summary>Drop every cached entry — call on driver shutdown / reinit so a fresh CPU advertises fresh SZL.</summary>
+    public void Clear()
+    {
+        lock (_gate) _entries.Clear();
+    }
+
+    private readonly record struct CacheEntry(byte[]? Payload, DateTime FetchedAtUtc);
+}

src/ZB.MOM.WW.OtOpcUa.Driver.S7/Szl/S7SzlIds.cs

@@ -0,0 +1,45 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.S7.Szl;
+
+/// <summary>
+///     PR-S7-E1 — SZL (System Status List) IDs surfaced through the driver's virtual
+///     <c>@System.*</c> address space. SZL is the S7comm "System Status List" sub-protocol
+///     documented in the Siemens function manual (Entry ID 6ES7810-4CA08-8BW1) — every
+///     S7-300 / S7-400 / S7-1200 / S7-1500 CPU answers SZL queries with metadata about
+///     itself: CPU type / order number / firmware (SZL 0x0011), cycle-time min/max/avg
+///     (SZL 0x0132 / 0x0432), and the diagnostic-buffer ring (SZL 0x00A0).
+/// </summary>
+/// <remarks>
+///     <para>
+///         IDs are 16-bit big-endian on the wire. The driver pairs each ID with an SZL
+///         <em>index</em> (also 16-bit) — most diagnostic SZLs accept index <c>0</c>;
+///         the diagnostic-buffer SZL accepts index <c>0..N-1</c> to address a specific
+///         entry but the driver always reads index <c>0</c> and parses the full ring
+///         in one shot.
+///     </para>
+///     <para>
+///         S7netplus 0.20 has internal SZL request building (<c>SzlReadRequestPackage</c> /
+///         <c>WriteSzlReadRequest</c>) but does not expose a public <c>ReadSzlAsync</c> API.
+///         The driver therefore goes through <see cref="IS7SzlReader"/>, whose default
+///         <see cref="S7NetSzlReader"/> implementation surfaces every SZL read as
+///         "not supported" until S7netplus exposes the public surface or we ship a
+///         raw-PDU helper. snap7 doesn't implement SZL at all so the integration profile
+///         exercises the same not-supported path.
+///     </para>
+/// </remarks>
+public static class S7SzlIds
+{
+    /// <summary>SZL ID 0x0011 — module identification: CPU type, MLFB / order number, firmware version.</summary>
+    public const ushort ModuleIdentification = 0x0011;
+
+    /// <summary>SZL ID 0x0132 — CPU status data including cycle-time stats. Index 0x0005 carries the cycle-time record.</summary>
+    public const ushort CpuStatusData = 0x0132;
+
+    /// <summary>SZL ID 0x0132 sub-index 0x0005 — cycle-time statistics record.</summary>
+    public const ushort CpuStatusCycleTimeIndex = 0x0005;
+
+    /// <summary>SZL ID 0x0432 — extended CPU status data; index 0x0001 carries the cycle-time record on S7-1500.</summary>
+    public const ushort CpuStatusDataExtended = 0x0432;
+
+    /// <summary>SZL ID 0x00A0 — diagnostic buffer ring (most-recent entry first). Index 0 returns up to N records depending on PDU budget.</summary>
+    public const ushort DiagnosticBuffer = 0x00A0;
+}

src/ZB.MOM.WW.OtOpcUa.Driver.S7/Szl/S7SzlParser.cs

@@ -0,0 +1,401 @@
+using System.Buffers.Binary;
+using System.Text;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.S7.Szl;
+
+/// <summary>
+///     PR-S7-E1 — pure parsers for the SZL (System Status List) response payloads the
+///     driver dispatches against <c>@System.*</c> virtual addresses. Every parser takes a
+///     byte payload <em>without</em> the S7comm transport envelope (parameter / data
+///     headers stripped already by <see cref="IS7SzlReader"/>) and returns a strongly-typed
+///     record. The byte layouts below match the Siemens function manual (Entry ID
+///     6ES7810-4CA08-8BW1) and the open-source <c>snap7</c> reference (the source of truth
+///     for unofficial layouts) — see <c>docs/v2/s7.md</c> "CPU diagnostics (SZL)" for the
+///     wire-level field-by-field map.
+/// </summary>
+/// <remarks>
+///     <para>
+///         <b>Common SZL payload header</b> (8 bytes):
+///         <code>
+///         u16 SzlId    // BE — echoes the requested SZL ID
+///         u16 SzlIndex // BE — echoes the requested SZL index
+///         u16 LenThdr  // BE — bytes per record
+///         u16 NDr      // BE — number of records following
+///         </code>
+///         Records follow contiguously, total <c>LenThdr * NDr</c> bytes.
+///     </para>
+///     <para>
+///         All multi-byte integers are big-endian. Fixed-width strings (MLFB, FW version)
+///         are space-padded ASCII; the parser trims trailing whitespace and NULs.
+///     </para>
+/// </remarks>
+public static class S7SzlParser
+{
+    /// <summary>Length of the common SZL response header in bytes.</summary>
+    public const int HeaderLength = 8;
+
+    /// <summary>Hard upper bound on diagnostic-buffer entries returned in one parse — caps test allocations even if a malformed payload claims a huge count.</summary>
+    public const int MaxDiagBufferEntriesPerResponse = 256;
+
+    /// <summary>
+    ///     Parse SZL 0x0011 (module identification) — produces the CPU type / order number /
+    ///     firmware version triple. The SZL contains multiple records keyed by an index in
+    ///     the first 2 bytes of each record:
+    ///     <list type="bullet">
+    ///         <item><c>0x0001</c> — module identification (MLFB / order number)</item>
+    ///         <item><c>0x0006</c> — basic firmware</item>
+    ///         <item><c>0x0007</c> — basic hardware (CPU type derived from MLFB)</item>
+    ///     </list>
+    ///     Each record is 28 bytes: 2-byte index, 20-byte MLFB (ASCII, space-padded), 2-byte
+    ///     BGTyp, 2-byte Ausbg1 (firmware big-version), 2-byte Ausbg2 (firmware small-version
+    ///     / patch).
+    /// </summary>
+    public static S7CpuInfo ParseCpuInfo(byte[] payload)
+    {
+        ArgumentNullException.ThrowIfNull(payload);
+        EnsureHeader(payload, out _, out _, out var lenThdr, out var nDr);
+
+        // Each module-identification record is 28 bytes per Siemens. Anything else is a
+        // protocol-level mismatch — surface it loudly rather than silently mis-decoding.
+        if (lenThdr != 28)
+            throw new ArgumentException(
+                $"S7 SZL 0x0011 expected record length 28, got {lenThdr}", nameof(payload));
+        var expected = HeaderLength + lenThdr * nDr;
+        if (payload.Length < expected)
+            throw new ArgumentException(
+                $"S7 SZL 0x0011 payload truncated: header claims {nDr} × {lenThdr} byte records " +
+                $"({expected} bytes total) but buffer is {payload.Length}", nameof(payload));
+
+        string? mlfb = null;
+        string? fw = null;
+        string? cpuType = null;
+
+        for (var i = 0; i < nDr; i++)
+        {
+            var off = HeaderLength + i * lenThdr;
+            var idx = BinaryPrimitives.ReadUInt16BigEndian(payload.AsSpan(off, 2));
+            // Fields per Siemens function manual §"SSL-ID 0011H":
+            //   index (2) | MLFB (20) | BGTyp (2) | Ausbg1 (2) | Ausbg2 (2)
+            var mlfbBytes = payload.AsSpan(off + 2, 20);
+            var ausbg1 = BinaryPrimitives.ReadUInt16BigEndian(payload.AsSpan(off + 24, 2));
+            var ausbg2 = BinaryPrimitives.ReadUInt16BigEndian(payload.AsSpan(off + 26, 2));
+
+            switch (idx)
+            {
+                case 0x0001:
+                    mlfb = TrimAscii(mlfbBytes);
+                    // CPU type: prefer the dedicated record if present, else derive from MLFB
+                    // (the prefix before the first space, e.g. "6ES7 516-3AN01-0AB0" → CPU 1516-3 PN/DP
+                    // — we surface the raw MLFB and let docs map to the marketing name).
+                    cpuType ??= DeriveCpuTypeFromMlfb(mlfb);
+                    break;
+                case 0x0006:
+                    // Firmware version: high byte of Ausbg1 = major, low byte of Ausbg1 = minor,
+                    // high byte of Ausbg2 = patch. Encoded as two ASCII chars in some firmwares;
+                    // the manual normalises to "Vmajor.minor.patch".
+                    fw = $"V{(ausbg1 >> 8) & 0xFF}.{ausbg1 & 0xFF}.{(ausbg2 >> 8) & 0xFF}";
+                    break;
+                case 0x0007:
+                    // Module-identification "basic hardware" — some CPUs surface the friendly
+                    // CPU name here as ASCII inside the MLFB slot. Override only if the field
+                    // looks like a real string (non-empty, printable).
+                    var hwName = TrimAscii(mlfbBytes);
+                    if (!string.IsNullOrEmpty(hwName)) cpuType = hwName;
+                    break;
+            }
+        }
+
+        return new S7CpuInfo(
+            CpuType: cpuType ?? "(unknown)",
+            Firmware: fw ?? "(unknown)",
+            OrderNo: mlfb ?? "(unknown)");
+    }
+
+    /// <summary>
+    ///     Parse SZL 0x0132 / 0x0432 (CPU status data — cycle-time record). The cycle-time
+    ///     record carries 6 × UInt32 BE values starting at offset 4 of the record:
+    ///     <list type="bullet">
+    ///         <item>Reserved (2 bytes index echo)</item>
+    ///         <item>Reserved (2 bytes)</item>
+    ///         <item>CycleAvg ms (UInt32 BE)</item>
+    ///         <item>CycleMin ms (UInt32 BE)</item>
+    ///         <item>CycleMax ms (UInt32 BE)</item>
+    ///         <item>… padding</item>
+    ///     </list>
+    ///     The driver pulls the first record (index <c>0x0005</c> on S7-300/400/1200,
+    ///     index <c>0x0001</c> on S7-1500's 0x0432) and reports the three cycle-time
+    ///     scalars in milliseconds as <see cref="double"/>s — matching the OPC UA Float64
+    ///     representation in <c>DriverDataType.Float64</c>.
+    /// </summary>
+    public static S7CycleStats ParseCycleStats(byte[] payload)
+    {
+        ArgumentNullException.ThrowIfNull(payload);
+        EnsureHeader(payload, out _, out _, out var lenThdr, out var nDr);
+        if (nDr < 1)
+            throw new ArgumentException(
+                "S7 SZL cycle-time response has no records", nameof(payload));
+        if (lenThdr < 16)
+            throw new ArgumentException(
+                $"S7 SZL cycle-time record too short: {lenThdr} bytes; need ≥ 16", nameof(payload));
+        var expected = HeaderLength + lenThdr;
+        if (payload.Length < expected)
+            throw new ArgumentException(
+                $"S7 SZL cycle-time payload truncated: need {expected} bytes, got {payload.Length}", nameof(payload));
+
+        var recOff = HeaderLength;
+        // Layout (per Siemens function manual §"SSL-ID 0132H, Index 5"):
+        //   u16 index | u16 reserved | u32 avgMs | u32 minMs | u32 maxMs
+        var avg = BinaryPrimitives.ReadUInt32BigEndian(payload.AsSpan(recOff + 4, 4));
+        var min = BinaryPrimitives.ReadUInt32BigEndian(payload.AsSpan(recOff + 8, 4));
+        var max = BinaryPrimitives.ReadUInt32BigEndian(payload.AsSpan(recOff + 12, 4));
+
+        return new S7CycleStats(MinMs: min, MaxMs: max, AvgMs: avg);
+    }
+
+    /// <summary>
+    ///     Parse SZL 0x00A0 (diagnostic buffer). Each record is 20 bytes:
+    ///     <list type="bullet">
+    ///         <item>EventId (UInt16 BE) — Siemens-defined event code, see manual</item>
+    ///         <item>Priority (UInt8) — alarm priority class 0–26 (S7-1500: 0–26)</item>
+    ///         <item>OB number (UInt8) — OB the event triggered (or 0 if no OB)</item>
+    ///         <item>DatId (UInt16 BE) — event-class group (FB / OB / async / …)</item>
+    ///         <item>Info1 (UInt16 BE) — event-specific extra info (e.g. block number)</item>
+    ///         <item>Info2 (UInt32 BE) — event-specific extra info</item>
+    ///         <item>TimeStamp (8 bytes BCD — IEC year/month/day/hour/minute/second/ms)</item>
+    ///     </list>
+    ///     Returns <em>up to</em> <paramref name="maxEntries"/> entries (capped at
+    ///     <see cref="MaxDiagBufferEntriesPerResponse"/>) so a malformed payload claiming
+    ///     a huge count can't blow the test allocator.
+    /// </summary>
+    public static IReadOnlyList<S7DiagBufferEntry> ParseDiagBuffer(byte[] payload, int maxEntries)
+    {
+        ArgumentNullException.ThrowIfNull(payload);
+        if (maxEntries < 0)
+            throw new ArgumentOutOfRangeException(nameof(maxEntries), maxEntries, "maxEntries must be ≥ 0");
+
+        EnsureHeader(payload, out _, out _, out var lenThdr, out var nDr);
+        if (lenThdr != 20)
+            throw new ArgumentException(
+                $"S7 SZL 0x00A0 expected record length 20, got {lenThdr}", nameof(payload));
+
+        var cap = Math.Min(Math.Min(maxEntries, nDr), MaxDiagBufferEntriesPerResponse);
+        var expected = HeaderLength + lenThdr * cap;
+        if (payload.Length < expected)
+            throw new ArgumentException(
+                $"S7 SZL 0x00A0 payload truncated: need ≥ {expected} bytes for {cap} entries, " +
+                $"got {payload.Length}", nameof(payload));
+
+        var entries = new S7DiagBufferEntry[cap];
+        for (var i = 0; i < cap; i++)
+        {
+            var off = HeaderLength + i * lenThdr;
+            var eventId = BinaryPrimitives.ReadUInt16BigEndian(payload.AsSpan(off, 2));
+            var priority = payload[off + 2];
+            // payload[off+3] = OB number (kept implicit in EventText below)
+            // payload[off+4..6] = DatId, payload[off+6..8] = Info1, payload[off+8..12] = Info2
+            // payload[off+12..20] = BCD timestamp.
+            var ts = DecodeBcdTimestamp(payload.AsSpan(off + 12, 8));
+            entries[i] = new S7DiagBufferEntry(
+                OccurrenceUtc: ts,
+                EventId: eventId,
+                Priority: priority,
+                EventText: $"Event 0x{eventId:X4} (priority {priority})");
+        }
+        return entries;
+    }
+
+    /// <summary>
+    ///     Encode a parsed <see cref="S7CpuInfo"/> back into a SZL 0x0011 byte payload.
+    ///     Round-trip helper used by the parser unit tests so encode-then-decode is the
+    ///     identity. Not used at runtime — the driver only ever decodes responses.
+    /// </summary>
+    public static byte[] EncodeCpuInfo(S7CpuInfo info, ushort szlId = S7SzlIds.ModuleIdentification)
+    {
+        ArgumentNullException.ThrowIfNull(info);
+        const int LenThdr = 28;
+        const int NDr = 3;
+        var buf = new byte[HeaderLength + LenThdr * NDr];
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(0, 2), szlId);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(2, 2), 0x0000);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(4, 2), LenThdr);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(6, 2), NDr);
+
+        // Record 0: index 0x0001 — MLFB / order number
+        WriteRecord(buf.AsSpan(HeaderLength, LenThdr), 0x0001, info.OrderNo, ausbg1: 0, ausbg2: 0);
+        // Record 1: index 0x0006 — firmware version
+        var (a1, a2) = ParseFirmwareString(info.Firmware);
+        WriteRecord(buf.AsSpan(HeaderLength + LenThdr, LenThdr), 0x0006, "", ausbg1: a1, ausbg2: a2);
+        // Record 2: index 0x0007 — CPU type as ASCII
+        WriteRecord(buf.AsSpan(HeaderLength + LenThdr * 2, LenThdr), 0x0007, info.CpuType, ausbg1: 0, ausbg2: 0);
+        return buf;
+
+        static void WriteRecord(Span<byte> rec, ushort idx, string mlfb, ushort ausbg1, ushort ausbg2)
+        {
+            BinaryPrimitives.WriteUInt16BigEndian(rec[..2], idx);
+            // 20-byte ASCII space-padded MLFB
+            rec[2..22].Fill((byte)' ');
+            var bytes = Encoding.ASCII.GetBytes(mlfb ?? "");
+            var copy = Math.Min(bytes.Length, 20);
+            bytes.AsSpan(0, copy).CopyTo(rec[2..(2 + copy)]);
+            BinaryPrimitives.WriteUInt16BigEndian(rec.Slice(22, 2), 0); // BGTyp
+            BinaryPrimitives.WriteUInt16BigEndian(rec.Slice(24, 2), ausbg1);
+            BinaryPrimitives.WriteUInt16BigEndian(rec.Slice(26, 2), ausbg2);
+        }
+
+        static (ushort, ushort) ParseFirmwareString(string fw)
+        {
+            // Best-effort parse of "Vmaj.min.patch" — falls back to zeros so a parse failure
+            // doesn't break round-trip tests for hand-crafted CpuInfo records.
+            if (string.IsNullOrEmpty(fw)) return (0, 0);
+            var s = fw.StartsWith('V') ? fw[1..] : fw;
+            var parts = s.Split('.');
+            byte maj = 0, min = 0, patch = 0;
+            if (parts.Length > 0) byte.TryParse(parts[0], out maj);
+            if (parts.Length > 1) byte.TryParse(parts[1], out min);
+            if (parts.Length > 2) byte.TryParse(parts[2], out patch);
+            return ((ushort)((maj << 8) | min), (ushort)(patch << 8));
+        }
+    }
+
+    /// <summary>Encode a <see cref="S7CycleStats"/> back into a SZL 0x0132 byte payload (round-trip helper).</summary>
+    public static byte[] EncodeCycleStats(S7CycleStats stats, ushort szlId = S7SzlIds.CpuStatusData)
+    {
+        ArgumentNullException.ThrowIfNull(stats);
+        const int LenThdr = 16;
+        const int NDr = 1;
+        var buf = new byte[HeaderLength + LenThdr * NDr];
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(0, 2), szlId);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(2, 2), S7SzlIds.CpuStatusCycleTimeIndex);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(4, 2), LenThdr);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(6, 2), NDr);
+
+        var rec = buf.AsSpan(HeaderLength);
+        BinaryPrimitives.WriteUInt16BigEndian(rec[..2], S7SzlIds.CpuStatusCycleTimeIndex);
+        BinaryPrimitives.WriteUInt16BigEndian(rec.Slice(2, 2), 0);
+        BinaryPrimitives.WriteUInt32BigEndian(rec.Slice(4, 4), (uint)stats.AvgMs);
+        BinaryPrimitives.WriteUInt32BigEndian(rec.Slice(8, 4), (uint)stats.MinMs);
+        BinaryPrimitives.WriteUInt32BigEndian(rec.Slice(12, 4), (uint)stats.MaxMs);
+        return buf;
+    }
+
+    /// <summary>Encode a list of <see cref="S7DiagBufferEntry"/> back into a SZL 0x00A0 byte payload (round-trip helper).</summary>
+    public static byte[] EncodeDiagBuffer(IReadOnlyList<S7DiagBufferEntry> entries)
+    {
+        ArgumentNullException.ThrowIfNull(entries);
+        const int LenThdr = 20;
+        var buf = new byte[HeaderLength + LenThdr * entries.Count];
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(0, 2), S7SzlIds.DiagnosticBuffer);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(2, 2), 0);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(4, 2), LenThdr);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(6, 2), (ushort)entries.Count);
+        for (var i = 0; i < entries.Count; i++)
+        {
+            var rec = buf.AsSpan(HeaderLength + i * LenThdr, LenThdr);
+            var e = entries[i];
+            BinaryPrimitives.WriteUInt16BigEndian(rec[..2], e.EventId);
+            rec[2] = e.Priority;
+            rec[3] = 0; // OB number — not surfaced
+            BinaryPrimitives.WriteUInt16BigEndian(rec.Slice(4, 2), 0);
+            BinaryPrimitives.WriteUInt16BigEndian(rec.Slice(6, 2), 0);
+            BinaryPrimitives.WriteUInt32BigEndian(rec.Slice(8, 4), 0);
+            EncodeBcdTimestamp(e.OccurrenceUtc, rec.Slice(12, 8));
+        }
+        return buf;
+    }
+
+    private static void EnsureHeader(byte[] payload, out ushort szlId, out ushort szlIndex, out ushort lenThdr, out ushort nDr)
+    {
+        if (payload.Length < HeaderLength)
+            throw new ArgumentException(
+                $"S7 SZL payload truncated: need at least {HeaderLength}-byte header, got {payload.Length}", nameof(payload));
+        szlId = BinaryPrimitives.ReadUInt16BigEndian(payload.AsSpan(0, 2));
+        szlIndex = BinaryPrimitives.ReadUInt16BigEndian(payload.AsSpan(2, 2));
+        lenThdr = BinaryPrimitives.ReadUInt16BigEndian(payload.AsSpan(4, 2));
+        nDr = BinaryPrimitives.ReadUInt16BigEndian(payload.AsSpan(6, 2));
+    }
+
+    private static string TrimAscii(ReadOnlySpan<byte> bytes)
+    {
+        var s = Encoding.ASCII.GetString(bytes);
+        return s.TrimEnd(' ', '\0');
+    }
+
+    /// <summary>
+    ///     Best-effort CPU type derivation from MLFB. The MLFB encodes the CPU model — e.g.
+    ///     <c>6ES7 516-3AN01-0AB0</c> identifies a CPU 1516-3 PN/DP. Without a full lookup
+    ///     table we just return the MLFB so operators can grep the manual; SZL index 0x0007
+    ///     overrides this when the CPU surfaces a friendly name there.
+    /// </summary>
+    private static string DeriveCpuTypeFromMlfb(string mlfb) => mlfb;
+
+    /// <summary>
+    ///     Decode an 8-byte BCD timestamp (Siemens IEC representation):
+    ///     <c>year(2) month(1) day(1) hour(1) minute(1) second(1) ms-day-of-week(2)</c>.
+    ///     The last 2 bytes pack three BCD ms digits and a day-of-week nibble.
+    /// </summary>
+    private static DateTimeOffset DecodeBcdTimestamp(ReadOnlySpan<byte> b)
+    {
+        // Year: 2-byte BCD (e.g. 0x20 0x24 = 2024)
+        var year = FromBcd(b[0]) * 100 + FromBcd(b[1]);
+        var month = Math.Clamp(FromBcd(b[2]), 1, 12);
+        var day = Math.Clamp(FromBcd(b[3]), 1, 31);
+        var hour = Math.Clamp(FromBcd(b[4]), 0, 23);
+        var minute = Math.Clamp(FromBcd(b[5]), 0, 59);
+        var second = Math.Clamp(FromBcd(b[6]), 0, 59);
+        // ms: high nibble of b[7] = first ms digit, low nibble of b[7] is reserved /
+        // day-of-week. Some CPUs pack three ms digits across b[7] high/low + the high
+        // nibble of the last byte; per Siemens function manual the simplest portable
+        // decode is to drop ms and surface only second-precision.
+        var ms = 0;
+
+        try
+        {
+            return new DateTimeOffset(year, month, day, hour, minute, second, ms, TimeSpan.Zero);
+        }
+        catch (ArgumentOutOfRangeException)
+        {
+            // Malformed timestamp — surface as epoch rather than throw so a single bad
+            // entry doesn't take out the whole diag-buffer parse.
+            return DateTimeOffset.UnixEpoch;
+        }
+
+        static int FromBcd(byte v) => ((v >> 4) & 0xF) * 10 + (v & 0xF);
+    }
+
+    private static void EncodeBcdTimestamp(DateTimeOffset ts, Span<byte> dst)
+    {
+        var u = ts.UtcDateTime;
+        dst[0] = ToBcd(u.Year / 100);
+        dst[1] = ToBcd(u.Year % 100);
+        dst[2] = ToBcd(u.Month);
+        dst[3] = ToBcd(u.Day);
+        dst[4] = ToBcd(u.Hour);
+        dst[5] = ToBcd(u.Minute);
+        dst[6] = ToBcd(u.Second);
+        dst[7] = 0; // ms / day-of-week — not round-tripped
+        static byte ToBcd(int v) => (byte)(((v / 10) << 4) | (v % 10));
+    }
+}
+
+/// <summary>CPU identification parsed from SZL 0x0011.</summary>
+/// <param name="CpuType">Marketing / friendly CPU name from SZL index 0x0007 (or MLFB fallback).</param>
+/// <param name="Firmware">Firmware version, formatted "Vmaj.min.patch".</param>
+/// <param name="OrderNo">MLFB / order number from SZL index 0x0001 (e.g. "6ES7 516-3AN01-0AB0").</param>
+public sealed record S7CpuInfo(string CpuType, string Firmware, string OrderNo);
+
+/// <summary>CPU cycle-time statistics parsed from SZL 0x0132 / 0x0432 — values in milliseconds.</summary>
+/// <param name="MinMs">Shortest scan cycle observed since last reset.</param>
+/// <param name="MaxMs">Longest scan cycle observed since last reset.</param>
+/// <param name="AvgMs">Rolling average scan-cycle time.</param>
+public sealed record S7CycleStats(double MinMs, double MaxMs, double AvgMs);
+
+/// <summary>One diagnostic-buffer entry parsed from SZL 0x00A0.</summary>
+/// <param name="OccurrenceUtc">Event timestamp decoded from the BCD timestamp field (UTC).</param>
+/// <param name="EventId">Siemens event code (e.g. 0x113A = "communication initiated").</param>
+/// <param name="Priority">Alarm priority class 0–26.</param>
+/// <param name="EventText">Human-readable rendering of the event — currently the raw 0x???? code; future PR can plug a lookup table.</param>
+public sealed record S7DiagBufferEntry(
+    DateTimeOffset OccurrenceUtc,
+    ushort EventId,
+    byte Priority,
+    string EventText);

src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Cli/Commands/AlarmsCommand.cs

@@ -0,0 +1,94 @@
+using CliFx.Attributes;
+using CliFx.Infrastructure;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Cli.Commands;
+
+/// <summary>
+///     PR 5.1 / #316 — stream TC3 EventLogger alarms to the terminal until Ctrl+C.
+///     Mirrors the OPC UA Client CLI <c>alarms</c> verb shape: subscribe + print every
+///     incoming <see cref="AlarmEventArgs"/> with timestamp, source, severity, and
+///     message text. Requires <c>EnableAlarms=true</c> on the driver — set via the
+///     base options builder when the verb is selected.
+/// </summary>
+[Command("alarms", Description =
+    "Subscribe to TC3 EventLogger alarms via the driver's IAlarmSource bridge and " +
+    "stream events to stdout until Ctrl+C.")]
+public sealed class AlarmsCommand : TwinCATCommandBase
+{
+    [CommandOption("source", Description =
+        "Optional alarm source filter (matched case-insensitively against the event's " +
+        "Source field). Repeat the flag to match multiple sources; omit to subscribe to " +
+        "every event the EventLogger surfaces.")]
+    public IReadOnlyList<string> Sources { get; init; } = Array.Empty<string>();
+
+    public override async ValueTask ExecuteAsync(IConsole console)
+    {
+        ConfigureLogging();
+        var ct = console.RegisterCancellationHandler();
+
+        // Empty Tags + EnableAlarms=true builds a driver that opens only the alarm path.
+        // TwinCATDriverOptions is a regular class with init-only properties — rebuild
+        // the instance instead of using a record-style `with` clone.
+        var baseOptions = BuildOptions([]);
+        var options = new TwinCATDriverOptions
+        {
+            Devices = baseOptions.Devices,
+            Tags = baseOptions.Tags,
+            Probe = baseOptions.Probe,
+            Timeout = baseOptions.Timeout,
+            UseNativeNotifications = baseOptions.UseNativeNotifications,
+            EnableControllerBrowse = baseOptions.EnableControllerBrowse,
+            MaxArrayExpansion = baseOptions.MaxArrayExpansion,
+            EnableAlarms = true,
+        };
+
+        await using var driver = new TwinCATDriver(options, DriverInstanceId);
+        IAlarmSubscriptionHandle? handle = null;
+        try
+        {
+            await driver.InitializeAsync("{}", ct);
+
+            driver.OnAlarmEvent += (_, e) =>
+            {
+                var line =
+                    $"[{e.SourceTimestampUtc:HH:mm:ss.fff}] " +
+                    $"{e.SourceNodeId} " +
+                    $"sev={e.Severity} " +
+                    $"type={e.AlarmType} " +
+                    $"cond={e.ConditionId} " +
+                    $"\"{e.Message}\"";
+                console.Output.WriteLine(line);
+            };
+
+            handle = await driver.SubscribeAlarmsAsync(Sources, ct);
+
+            var filterDesc = Sources.Count == 0
+                ? "all sources"
+                : $"sources [{string.Join(", ", Sources)}]";
+            await console.Output.WriteLineAsync(
+                $"Subscribed to TC3 EventLogger alarms on {AmsNetId}:{AmsPort} ({filterDesc}). Ctrl+C to stop.");
+            await console.Output.WriteLineAsync(
+                "Note: Beckhoff doesn't ship a managed TcEventLogger wrapper; the driver " +
+                "uses a best-effort decode of AMS port 110 notifications. Some fields may " +
+                "surface as 'Unknown' until a binary-protocol decoder lands.");
+            try
+            {
+                await Task.Delay(System.Threading.Timeout.InfiniteTimeSpan, ct);
+            }
+            catch (OperationCanceledException)
+            {
+                // Expected on Ctrl+C.
+            }
+        }
+        finally
+        {
+            if (handle is not null)
+            {
+                try { await driver.UnsubscribeAlarmsAsync(handle, CancellationToken.None); }
+                catch { /* teardown best-effort */ }
+            }
+            await driver.ShutdownAsync(CancellationToken.None);
+        }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATAlarmSource.cs

@@ -0,0 +1,224 @@
+using System.Collections.Concurrent;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+/// <summary>
+///     PR 5.1 / #316 — single TC3 EventLogger event payload exposed by
+///     <see cref="ITwinCATAlarmGate"/> + projected onto
+///     <see cref="AlarmEventArgs"/> for the driver's <see cref="IAlarmSource"/> surface.
+///     Carries the four fields the EventLogger surfaces on the wire (event class GUID /
+///     source name / severity / message text) plus the originating timestamp + an
+///     <c>Acked</c> flag so a re-fired event after operator acknowledgement is
+///     distinguishable from a fresh raise.
+/// </summary>
+/// <remarks>
+///     Beckhoff doesn't ship a managed <c>TcEventLogger</c> wrapper in the regular
+///     <c>Beckhoff.TwinCAT.Ads</c> v6 NuGet (the C++ TcCOM headers exist, the .NET ones
+///     don't — see <c>docs/v3/twincat-eventlogger-spike.md</c>). The production gate
+///     therefore opens a second <see cref="ITwinCATClient"/> against AMS port 110
+///     (<c>AMSPORT_EVENTLOG</c>) + adds a device notification on
+///     <c>ADSIGRP_TCEVENTLOG_ALARMS</c>; the binary-protocol decode is best-effort and
+///     unrecognised fields surface as <c>"Unknown"</c>.
+/// </remarks>
+public sealed record TwinCATAlarmEvent(
+    string EventClass,
+    string Source,
+    ushort Severity,
+    string Message,
+    DateTimeOffset OccurrenceUtc,
+    bool Acked);
+
+/// <summary>
+///     PR 5.1 / #316 — driver-internal seam for the TC3 EventLogger wire path. Production
+///     opens a second <see cref="ITwinCATClient"/> against AMS port 110 + adds a device
+///     notification on the alarm-list index group; the binary-protocol decoder lands on
+///     a follow-up PR (see <c>docs/v3/twincat-eventlogger-spike.md</c>). Tests substitute
+///     a fake gate to drive synthetic events.
+/// </summary>
+public interface ITwinCATAlarmGate : IDisposable
+{
+    /// <summary>Connect / register the device-notification subscription.</summary>
+    Task StartAsync(CancellationToken cancellationToken);
+
+    /// <summary>
+    ///     Fired by the gate for every alarm transition the EventLogger surfaces (raise /
+    ///     clear / acknowledge). The driver's <see cref="TwinCATAlarmSource"/> projects this
+    ///     onto <see cref="AlarmEventArgs"/> for every active subscription.
+    /// </summary>
+    event EventHandler<TwinCATAlarmEvent>? OnAlarmEvent;
+
+    /// <summary>
+    ///     Issue an acknowledge against the EventLogger for the supplied source / condition.
+    ///     Best-effort — the wire format is undocumented in managed code; the production
+    ///     gate writes the acknowledge index-group when reachable + returns silently otherwise.
+    /// </summary>
+    Task AcknowledgeAsync(
+        IReadOnlyList<AlarmAcknowledgeRequest> acknowledgements,
+        CancellationToken cancellationToken);
+
+    /// <summary>Snapshot of currently-active alarms — empty when the gate has no events buffered.</summary>
+    IReadOnlyList<TwinCATAlarmEvent> ActiveAlarms { get; }
+}
+
+/// <summary>
+///     PR 5.1 / #316 — default no-op alarm gate. Keeps the construction path simple for
+///     deployments without TcEventLogger configured + for unit tests that exercise the
+///     <c>EnableAlarms=false</c> short-circuit. <see cref="OnAlarmEvent"/> never fires;
+///     <see cref="AcknowledgeAsync"/> is a no-op.
+/// </summary>
+internal sealed class NullTwinCATAlarmGate : ITwinCATAlarmGate
+{
+    public IReadOnlyList<TwinCATAlarmEvent> ActiveAlarms => Array.Empty<TwinCATAlarmEvent>();
+
+    public event EventHandler<TwinCATAlarmEvent>? OnAlarmEvent;
+
+    public Task StartAsync(CancellationToken cancellationToken)
+    {
+        // Touch the event so the unused-warning analyzer keeps quiet without suppressing
+        // the diagnostic outright. The handler list stays empty in production.
+        _ = OnAlarmEvent;
+        return Task.CompletedTask;
+    }
+
+    public Task AcknowledgeAsync(
+        IReadOnlyList<AlarmAcknowledgeRequest> acknowledgements,
+        CancellationToken cancellationToken) => Task.CompletedTask;
+
+    public void Dispose() { }
+}
+
+/// <summary>
+///     PR 5.1 / #316 — projects <see cref="ITwinCATAlarmGate"/> events onto the driver's
+///     <see cref="IAlarmSource"/> surface. Subscriptions filter by source-node id (each
+///     id is matched against <see cref="TwinCATAlarmEvent.Source"/>); an empty filter list
+///     subscribes to every event.
+/// </summary>
+internal sealed class TwinCATAlarmSource : IAsyncDisposable
+{
+    private readonly TwinCATDriver _driver;
+    private readonly ITwinCATAlarmGate _gate;
+    private readonly ConcurrentDictionary<long, Subscription> _subs = new();
+    private long _nextId;
+    private bool _started;
+    private readonly Lock _startLock = new();
+
+    public TwinCATAlarmSource(TwinCATDriver driver, ITwinCATAlarmGate gate)
+    {
+        _driver = driver;
+        _gate = gate;
+        _gate.OnAlarmEvent += OnGateAlarm;
+    }
+
+    public async Task<IAlarmSubscriptionHandle> SubscribeAsync(
+        IReadOnlyList<string> sourceNodeIds, CancellationToken cancellationToken)
+    {
+        var id = Interlocked.Increment(ref _nextId);
+        var handle = new TwinCATAlarmSubscriptionHandle(id);
+        _subs[id] = new Subscription(handle, [..sourceNodeIds]);
+
+        // First subscription wins the start race; subsequent subscribes find the gate
+        // already connected. Single-shot start keeps the AMS-port-110 session count to
+        // exactly one per driver instance.
+        var shouldStart = false;
+        lock (_startLock)
+        {
+            if (!_started)
+            {
+                _started = true;
+                shouldStart = true;
+            }
+        }
+        if (shouldStart)
+            await _gate.StartAsync(cancellationToken).ConfigureAwait(false);
+        return handle;
+    }
+
+    public Task UnsubscribeAsync(IAlarmSubscriptionHandle handle, CancellationToken cancellationToken)
+    {
+        if (handle is TwinCATAlarmSubscriptionHandle h)
+            _subs.TryRemove(h.Id, out _);
+        return Task.CompletedTask;
+    }
+
+    public Task AcknowledgeAsync(
+        IReadOnlyList<AlarmAcknowledgeRequest> acknowledgements, CancellationToken cancellationToken)
+        => _gate.AcknowledgeAsync(acknowledgements, cancellationToken);
+
+    public ValueTask DisposeAsync()
+    {
+        _gate.OnAlarmEvent -= OnGateAlarm;
+        _subs.Clear();
+        try { _gate.Dispose(); } catch { }
+        return ValueTask.CompletedTask;
+    }
+
+    /// <summary>
+    ///     Translate a raw <see cref="TwinCATAlarmEvent"/> from the gate into one
+    ///     <see cref="AlarmEventArgs"/> per matching subscription. Source-node-id filters
+    ///     match on case-insensitive equality against <see cref="TwinCATAlarmEvent.Source"/>;
+    ///     an empty subscription filter list passes every event through.
+    /// </summary>
+    private void OnGateAlarm(object? sender, TwinCATAlarmEvent evt)
+    {
+        var conditionId = $"{evt.Source}#{evt.EventClass}";
+        var sourceTimestamp = evt.OccurrenceUtc.UtcDateTime;
+        foreach (var sub in _subs.Values)
+        {
+            if (!sub.Matches(evt.Source)) continue;
+            var args = new AlarmEventArgs(
+                SubscriptionHandle: sub.Handle,
+                SourceNodeId: evt.Source,
+                ConditionId: conditionId,
+                AlarmType: evt.EventClass,
+                Message: evt.Message,
+                Severity: MapSeverity(evt.Severity),
+                SourceTimestampUtc: sourceTimestamp);
+            _driver.InvokeAlarmEvent(args);
+        }
+    }
+
+    /// <summary>
+    ///     Map TC3 EventLogger 0–255 severity values onto the driver-agnostic
+    ///     <see cref="AlarmSeverity"/> bucket. Buckets follow the same low-quartile cuts the
+    ///     OPC UA AC mapping in <c>docs/drivers/TwinCAT.md</c> documents.
+    /// </summary>
+    internal static AlarmSeverity MapSeverity(ushort raw) => raw switch
+    {
+        <= 64 => AlarmSeverity.Low,
+        <= 128 => AlarmSeverity.Medium,
+        <= 192 => AlarmSeverity.High,
+        _ => AlarmSeverity.Critical,
+    };
+
+    private sealed class Subscription
+    {
+        public Subscription(TwinCATAlarmSubscriptionHandle handle, IReadOnlyList<string> sourceFilters)
+        {
+            Handle = handle;
+            SourceFilters = sourceFilters;
+        }
+
+        public TwinCATAlarmSubscriptionHandle Handle { get; }
+        public IReadOnlyList<string> SourceFilters { get; }
+
+        public bool Matches(string source)
+        {
+            if (SourceFilters.Count == 0) return true; // wildcard
+            for (var i = 0; i < SourceFilters.Count; i++)
+            {
+                if (string.Equals(SourceFilters[i], source, StringComparison.OrdinalIgnoreCase))
+                    return true;
+            }
+            return false;
+        }
+    }
+}
+
+/// <summary>
+///     PR 5.1 / #316 — handle returned by <see cref="TwinCATAlarmSource.SubscribeAsync"/>.
+/// </summary>
+public sealed record TwinCATAlarmSubscriptionHandle(long Id) : IAlarmSubscriptionHandle
+{
+    public string DiagnosticId => $"twincat-alarm-sub-{Id}";
+}

src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs

@@ -9,7 +9,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
 ///     resolver land in PRs 2 and 3.
 /// </summary>
 public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery, ISubscribable,
-    IHostConnectivityProbe, IPerCallHostResolver, IDisposable, IAsyncDisposable
+    IHostConnectivityProbe, IPerCallHostResolver, IAlarmSource, IDisposable, IAsyncDisposable
 {
     private readonly TwinCATDriverOptions _options;
     private readonly string _driverInstanceId;
@@ -17,13 +17,25 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
     private readonly PollGroupEngine _poll;
     private readonly Dictionary<string, DeviceState> _devices = new(StringComparer.OrdinalIgnoreCase);
     private readonly Dictionary<string, TwinCATTagDefinition> _tagsByName = new(StringComparer.OrdinalIgnoreCase);
+    private readonly TwinCATAlarmSource? _alarmSource;
     private DriverHealth _health = new(DriverState.Unknown, null, null);
 
     public event EventHandler<DataChangeEventArgs>? OnDataChange;
     public event EventHandler<HostStatusChangedEventArgs>? OnHostStatusChanged;
+    public event EventHandler<AlarmEventArgs>? OnAlarmEvent;
+
+    /// <summary>
+    ///     PR 5.1 / #316 — internal seam for <see cref="TwinCATAlarmSource"/> to raise
+    ///     <see cref="OnAlarmEvent"/> against the driver's public surface. Mirrors the
+    ///     <see cref="OnDataChange"/> raise pattern so capability invokers see one event
+    ///     source per <c>IAlarmSource</c> driver instance regardless of how many internal
+    ///     subscriptions are open.
+    /// </summary>
+    internal void InvokeAlarmEvent(AlarmEventArgs args) => OnAlarmEvent?.Invoke(this, args);
 
     public TwinCATDriver(TwinCATDriverOptions options, string driverInstanceId,
-        ITwinCATClientFactory? clientFactory = null)
+        ITwinCATClientFactory? clientFactory = null,
+        ITwinCATAlarmGate? alarmGate = null)
     {
         ArgumentNullException.ThrowIfNull(options);
         _options = options;
@@ -33,6 +45,16 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
             reader: ReadAsync,
             onChange: (handle, tagRef, snapshot) =>
                 OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, tagRef, snapshot)));
+
+        // PR 5.1 / #316 — only stand up the alarm source when the option is on. With the
+        // option off, IAlarmSource.SubscribeAlarmsAsync returns a no-op handle so capability
+        // negotiation still works without paying for the second AMS session against port
+        // 110 / TcEventLogger that the production gate would open.
+        if (_options.EnableAlarms)
+        {
+            var gate = alarmGate ?? new NullTwinCATAlarmGate();
+            _alarmSource = new TwinCATAlarmSource(this, gate);
+        }
     }
 
     public string DriverInstanceId => _driverInstanceId;
@@ -85,6 +107,16 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
             foreach (var r in sub.Registrations) { try { r.Dispose(); } catch { } }
         _nativeSubs.Clear();
 
+        // PR 5.1 / #316 — alarm source teardown. Disposes the gate (closes the second
+        // AMS-port-110 client + drops the device-notification handle in the production
+        // path) + clears the subscription bookkeeping. Best-effort — a flaky teardown
+        // should not block shutdown of the wire-data path.
+        if (_alarmSource is not null)
+        {
+            try { await _alarmSource.DisposeAsync().ConfigureAwait(false); }
+            catch { /* swallow — see comment above */ }
+        }
+
         await _poll.DisposeAsync().ConfigureAwait(false);
         foreach (var state in _devices.Values)
         {
@@ -808,6 +840,43 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
             new HostStatusChangedEventArgs(state.Options.HostAddress, old, newState));
     }
 
+    // ---- IAlarmSource (TC3 EventLogger bridge, #316) ----
+
+    /// <summary>
+    ///     PR 5.1 / #316 — subscribe to TC3 EventLogger alarms scoped to <paramref name="sourceNodeIds"/>.
+    ///     Each id matches against <see cref="TwinCATAlarmEvent.Source"/>; an empty list passes every
+    ///     event through the gate. Feature-gated — when <see cref="TwinCATDriverOptions.EnableAlarms"/>
+    ///     is <c>false</c> (the default), returns a sentinel handle without opening the AMS-port-110
+    ///     session. Capability negotiation succeeds either way + <see cref="OnAlarmEvent"/> simply
+    ///     never fires while the gate is disabled.
+    /// </summary>
+    public Task<IAlarmSubscriptionHandle> SubscribeAlarmsAsync(
+        IReadOnlyList<string> sourceNodeIds, CancellationToken cancellationToken)
+    {
+        if (_alarmSource is null)
+        {
+            // Disabled-gate sentinel — Id 0 is reserved for the no-op shape so a follow-up
+            // unsubscribe doesn't accidentally remove a real subscription.
+            var disabled = new TwinCATAlarmSubscriptionHandle(0);
+            return Task.FromResult<IAlarmSubscriptionHandle>(disabled);
+        }
+        return _alarmSource.SubscribeAsync(sourceNodeIds, cancellationToken);
+    }
+
+    public Task UnsubscribeAlarmsAsync(IAlarmSubscriptionHandle handle, CancellationToken cancellationToken) =>
+        _alarmSource is null
+            ? Task.CompletedTask
+            : _alarmSource.UnsubscribeAsync(handle, cancellationToken);
+
+    public Task AcknowledgeAsync(
+        IReadOnlyList<AlarmAcknowledgeRequest> acknowledgements, CancellationToken cancellationToken) =>
+        _alarmSource is null
+            ? Task.CompletedTask
+            : _alarmSource.AcknowledgeAsync(acknowledgements, cancellationToken);
+
+    /// <summary>Test-only — <c>true</c> when an alarm source has been instantiated.</summary>
+    internal bool HasAlarmSource => _alarmSource is not null;
+
     // ---- IPerCallHostResolver ----
 
     public string ResolveHost(string fullReference)

src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriverOptions.cs

@@ -44,6 +44,23 @@ public sealed class TwinCATDriverOptions
     ///     declared in <see cref="Tags"/> (those bypass the walker entirely).
     /// </summary>
     public int MaxArrayExpansion { get; init; } = 1024;
+
+    /// <summary>
+    ///     PR 5.1 / #316 — opt-in TC3 EventLogger bridge. When <c>true</c>, the driver
+    ///     surfaces TwinCAT alarm events via <see cref="Core.Abstractions.IAlarmSource"/> by
+    ///     opening a second <c>AdsClient</c> against AMS port 110 (<c>AMSPORT_EVENTLOG</c>)
+    ///     and adding a device notification on <c>ADSIGRP_TCEVENTLOG_ALARMS</c>. Default
+    ///     <c>false</c> because (a) Beckhoff doesn't ship a managed <c>TcEventLogger</c>
+    ///     wrapper in the regular <c>Beckhoff.TwinCAT.Ads</c> v6 NuGet, so the binary-protocol
+    ///     decode is best-effort and fields may surface as <c>"Unknown"</c>; (b) deployments
+    ///     without TcEventLogger configured shouldn't pay the cost of a second AMS session
+    ///     +  notification handle; (c) leaves the spike output (
+    ///     <c>docs/v3/twincat-eventlogger-spike.md</c>) as the source of truth for the wire
+    ///     decode while the implementation lands incrementally. When
+    ///     <see cref="EnableAlarms"/> is <c>false</c>, <see cref="Core.Abstractions.IAlarmSource"/>
+    ///     methods short-circuit to a no-op subscription so capability negotiation still works.
+    /// </summary>
+    public bool EnableAlarms { get; init; }
 }
 
 /// <summary>

src/ZB.MOM.WW.OtOpcUa.Server/HostStatusPublisher.cs

@@ -138,6 +138,11 @@ public sealed class HostStatusPublisher(
         HostState.Running => DriverHostState.Running,
         HostState.Stopped => DriverHostState.Stopped,
         HostState.Faulted => DriverHostState.Faulted,
+        // PR ablegacy-12 / #255 — Demoted is a driver-side back-off (skipped reads while
+        // we wait for a flaky host to recover). The Configuration enum doesn't have a
+        // dedicated value; surface it as Stopped so the Admin UI lights it up red-ish
+        // without the publisher needing a schema migration to differentiate.
+        HostState.Demoted => DriverHostState.Stopped,
         _ => DriverHostState.Unknown,
     };
 }

tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/AbLegacyAutoDemoteTests.cs

@@ -0,0 +1,102 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.PlcFamilies;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests;
+
+/// <summary>
+///     PR ablegacy-12 / #255 — wire-level smoke for auto-demote on comm failure.
+///     Runs only when ab_server is reachable. Two devices: one healthy (the live
+///     ab_server slc500 simulator), one pointed at <c>127.0.0.1:1</c> which
+///     refuses every connection. After three consecutive failures the faulty
+///     device's reads must short-circuit with <c>BadCommunicationError</c>
+///     while the healthy device keeps returning <c>Good</c> — the whole point
+///     of the feature: one slow / unreachable PLC sharing the driver thread
+///     can't starve faster peers.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Build-only by default — the assertion that demotion latency is
+///         bounded depends on the ab_server simulator timing out on the faulty
+///         port within the per-device timeout. We pin the faulty endpoint at
+///         <c>127.0.0.1:1</c> (the bogus-port standard) which RST's the
+///         connection immediately on most stacks; environments that whitelist
+///         outbound to localhost:1 will see different timing but still trip
+///         the threshold within the test budget.
+///     </para>
+///     <para>
+///         The Docker fixture extension (<c>slc500-faulty</c>) noted in the PR
+///         plan is a documentation-only placeholder for now — implementing a
+///         refusing-proxy container is non-trivial and the localhost:1 trick
+///         covers the same surface deterministically.
+///     </para>
+/// </remarks>
+[Collection(AbLegacyServerCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Simulator", "ab_server-PCCC")]
+public sealed class AbLegacyAutoDemoteTests(AbLegacyServerFixture sim)
+{
+    [AbLegacyFact]
+    public async Task Two_devices_one_unreachable_does_not_starve_healthy_reads()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+
+        var healthy = $"ab://{sim.Host}:{sim.Port}/{sim.CipPath}";
+        // 127.0.0.1:1 is the bogus-port standard — typical Linux/Windows TCP
+        // stacks RST immediately. The driver still reports it as a comm
+        // failure (libplctag wraps the failure as a transient throw).
+        var faulty = "ab://127.0.0.1:1/1,0";
+
+        await using var drv = new AbLegacyDriver(new AbLegacyDriverOptions
+        {
+            Devices =
+            [
+                new AbLegacyDeviceOptions(healthy, AbLegacyPlcFamily.Slc500,
+                    Timeout: TimeSpan.FromSeconds(5)),
+                new AbLegacyDeviceOptions(faulty, AbLegacyPlcFamily.Slc500,
+                    // Snappy timeout so the test budget stays short.
+                    Timeout: TimeSpan.FromMilliseconds(500),
+                    Demote: new AbLegacyDemoteOptions(
+                        FailureThreshold: 3,
+                        DemoteFor: TimeSpan.FromSeconds(30))),
+            ],
+            Tags =
+            [
+                new AbLegacyTagDefinition("Healthy", healthy, "N7:0", AbLegacyDataType.Int),
+                new AbLegacyTagDefinition("Faulty", faulty, "N7:0", AbLegacyDataType.Int),
+            ],
+            Probe = new AbLegacyProbeOptions { Enabled = false },
+        }, driverInstanceId: "ablegacy-auto-demote-it");
+
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        // Trip the demote on the faulty device.
+        for (var i = 0; i < 3; i++)
+        {
+            await drv.ReadAsync(["Faulty"], TestContext.Current.CancellationToken);
+        }
+
+        // Healthy host MUST keep returning Good even though the sibling is demoted.
+        var healthyResult = await drv.ReadAsync(["Healthy"], TestContext.Current.CancellationToken);
+        healthyResult[0].StatusCode.ShouldBe(AbLegacyStatusMapper.Good);
+
+        // Faulty host now short-circuits without waiting on libplctag's timeout.
+        var sw = System.Diagnostics.Stopwatch.StartNew();
+        var faultyResult = await drv.ReadAsync(["Faulty"], TestContext.Current.CancellationToken);
+        sw.Stop();
+        faultyResult[0].StatusCode.ShouldBe(AbLegacyStatusMapper.BadCommunicationError);
+        // Short-circuit should be ~1 ms; pad generously for CI noise. The pre-PR-12
+        // path would have waited the full 500 ms timeout.
+        sw.ElapsedMilliseconds.ShouldBeLessThan(200);
+
+        // Counter access via the public diagnostic short-circuit path — the
+        // internal Snapshot() seam isn't visible from this assembly.
+        var demoteCountRef = $"_Diagnostics/{faulty}/DemoteCount";
+        var lastDemotedRef = $"_Diagnostics/{faulty}/LastDemotedUtc";
+        var diag = await drv.ReadAsync(
+            [demoteCountRef, lastDemotedRef], TestContext.Current.CancellationToken);
+        ((long)diag[0].Value!).ShouldBeGreaterThan(0);
+        ((string)diag[1].Value!).Length.ShouldBeGreaterThan(0);
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/Docker/docker-compose.yml

@@ -72,3 +72,30 @@ services:
       "--tag=F8[120]",
       "--tag=B3[10]"
     ]
+
+  # PR ablegacy-12 / #255 — faulty-PLC fixture for the auto-demote contract.
+  # FIXTURE-TIER FOLLOW-UP: implementing a refusing-proxy container that
+  # round-trips libplctag's CIP framing far enough to trigger comm failures
+  # (vs. just RST'ing the TCP handshake) is non-trivial — the integration
+  # test currently uses 127.0.0.1:1 (the bogus-port standard) which RST's
+  # immediately on most TCP stacks. That gets us deterministic comm-failure
+  # coverage without standing up a second container; if the localhost:1
+  # trick stops working on a future test runner (e.g. a sandbox that
+  # blocks port 1) re-enable this stub:
+  #
+  # slc500-faulty:
+  #   profiles: ["slc500-faulty"]
+  #   image: otopcua-ab-server:libplctag-release
+  #   build:
+  #     context: ../../ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/Docker
+  #     dockerfile: Dockerfile
+  #   container_name: otopcua-ab-server-slc500-faulty
+  #   restart: "no"
+  #   ports:
+  #     - "44819:44819"
+  #   # Hostile entrypoint: bind the port but exit immediately so subsequent
+  #   # connection attempts get RST'd. Future iteration: a libplctag-aware
+  #   # proxy that accepts the CIP open and then drops the wire halfway
+  #   # through, exercising the read-timeout path rather than the
+  #   # connection-refused path.
+  #   entrypoint: ["sh", "-c", "exit 1"]

tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/AbLegacyAutoDemoteTests.cs

@@ -0,0 +1,380 @@
+using System.Text.Json;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.AbLegacy;
+using ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.PlcFamilies;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests;
+
+/// <summary>
+///     PR ablegacy-12 / #255 — auto-demote on consecutive comm failure. After
+///     <c>FailureThreshold</c> consecutive read or probe failures the driver
+///     marks the device <c>Demoted</c> for <c>DemoteFor</c>; subsequent reads
+///     short-circuit with <c>BadCommunicationError</c> without invoking
+///     libplctag, so one slow PLC sharing the driver thread can't starve faster
+///     peers. Probe success clears the demote early; read success resets the
+///     consecutive-failure tally without leaving the demote window.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class AbLegacyAutoDemoteTests
+{
+    private const string Host = "ab://10.0.0.5/1,0";
+    private const string SecondHost = "ab://10.0.0.6/1,0";
+
+    /// <summary>
+    ///     Disable the probe by default — every test wants deterministic
+    ///     control over the failure tally without a background loop racing
+    ///     against the read path.
+    /// </summary>
+    private static AbLegacyDriverOptions BaseOptions(
+        AbLegacyDemoteOptions? demote = null,
+        IReadOnlyList<AbLegacyDeviceOptions>? devices = null,
+        IReadOnlyList<AbLegacyTagDefinition>? tags = null) => new()
+        {
+            Devices = devices ?? [new AbLegacyDeviceOptions(Host, AbLegacyPlcFamily.Slc500, Demote: demote)],
+            Tags = tags ?? [new AbLegacyTagDefinition("X", Host, "N7:0", AbLegacyDataType.Int)],
+            Probe = new AbLegacyProbeOptions { Enabled = false },
+        };
+
+    private static (AbLegacyDriver drv, FakeAbLegacyTagFactory factory) NewDriver(
+        AbLegacyDemoteOptions? demote = null,
+        IReadOnlyList<AbLegacyDeviceOptions>? devices = null,
+        IReadOnlyList<AbLegacyTagDefinition>? tags = null)
+    {
+        var factory = new FakeAbLegacyTagFactory();
+        var drv = new AbLegacyDriver(BaseOptions(demote, devices, tags), "drv-demote", factory);
+        return (drv, factory);
+    }
+
+    private static FakeAbLegacyTag SeedFailingTag(FakeAbLegacyTagFactory factory)
+    {
+        // Cause every read to throw — exception-driven failures count as
+        // BadCommunicationError per RecordError(commFailure:true).
+        factory.Customise = p => new FakeAbLegacyTag(p)
+        {
+            ThrowOnRead = true,
+            Exception = new TimeoutException("simulated comm failure"),
+        };
+        // Return value is the prototype so a caller that wants to flip the
+        // failure off later can do so via factory.Tags["N7:0"].
+        return null!;
+    }
+
+    [Fact]
+    public async Task Three_consecutive_failures_demote_the_device()
+    {
+        var (drv, factory) = NewDriver();
+        SeedFailingTag(factory);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+
+        var state = drv.GetDeviceState(Host).ShouldNotBeNull();
+        state.DemotedUntilUtc.ShouldNotBeNull();
+        var snap = drv.DiagnosticTags.Snapshot(Host);
+        snap.DemoteCount.ShouldBe(1);
+        snap.LastDemotedUtc.ShouldNotBeNull();
+        drv.GetHostStatuses().Single().State.ShouldBe(HostState.Demoted);
+    }
+
+    [Fact]
+    public async Task Reads_while_demoted_short_circuit_without_invoking_libplctag()
+    {
+        var (drv, factory) = NewDriver(
+            new AbLegacyDemoteOptions(FailureThreshold: 3, DemoteFor: TimeSpan.FromMinutes(5)));
+        SeedFailingTag(factory);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        // Trip the demotion.
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        var readsBeforeDemote = factory.Tags["N7:0"].ReadCount;
+
+        // Subsequent reads MUST NOT call into libplctag — the short-circuit
+        // returns BadCommunicationError before EnsureTagRuntimeAsync.
+        var result = await drv.ReadAsync(["X"], CancellationToken.None);
+        result[0].StatusCode.ShouldBe(AbLegacyStatusMapper.BadCommunicationError);
+        factory.Tags["N7:0"].ReadCount.ShouldBe(readsBeforeDemote);
+
+        var result2 = await drv.ReadAsync(["X"], CancellationToken.None);
+        result2[0].StatusCode.ShouldBe(AbLegacyStatusMapper.BadCommunicationError);
+        factory.Tags["N7:0"].ReadCount.ShouldBe(readsBeforeDemote);
+    }
+
+    [Fact]
+    public async Task After_DemoteFor_expires_next_read_dispatches_through()
+    {
+        // Tiny window so the cool-down expires within the test.
+        var (drv, factory) = NewDriver(
+            new AbLegacyDemoteOptions(FailureThreshold: 2, DemoteFor: TimeSpan.FromMilliseconds(50)));
+        SeedFailingTag(factory);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        // Trip with two failures.
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+
+        var state = drv.GetDeviceState(Host).ShouldNotBeNull();
+        state.DemotedUntilUtc.ShouldNotBeNull();
+        var readsBeforeWait = factory.Tags["N7:0"].ReadCount;
+
+        // Flip the fake to succeed and wait past the demote window.
+        factory.Tags["N7:0"].ThrowOnRead = false;
+        factory.Tags["N7:0"].Value = 42;
+        factory.Tags["N7:0"].Status = 0;
+        await Task.Delay(TimeSpan.FromMilliseconds(120));
+
+        var result = await drv.ReadAsync(["X"], CancellationToken.None);
+        result[0].StatusCode.ShouldBe(AbLegacyStatusMapper.Good);
+        result[0].Value.ShouldBe(42);
+        // The window expiry path dispatched through to libplctag.
+        factory.Tags["N7:0"].ReadCount.ShouldBeGreaterThan(readsBeforeWait);
+    }
+
+    [Fact]
+    public async Task Successful_read_resets_consecutive_failure_counter()
+    {
+        var (drv, factory) = NewDriver();
+        // Initial state — every read fails.
+        SeedFailingTag(factory);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        var state = drv.GetDeviceState(Host).ShouldNotBeNull();
+        state.ConsecutiveFailures.ShouldBe(2);
+
+        // One successful read — flip the existing fake.
+        factory.Tags["N7:0"].ThrowOnRead = false;
+        factory.Tags["N7:0"].Value = 99;
+        factory.Tags["N7:0"].Status = 0;
+        await drv.ReadAsync(["X"], CancellationToken.None);
+
+        state.ConsecutiveFailures.ShouldBe(0);
+        state.DemotedUntilUtc.ShouldBeNull();
+    }
+
+    [Fact]
+    public async Task Failure_success_failure_does_not_demote_at_threshold_three()
+    {
+        var (drv, factory) = NewDriver(
+            new AbLegacyDemoteOptions(FailureThreshold: 3));
+        SeedFailingTag(factory);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        // 2 failures.
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+
+        // 1 success — counter resets.
+        factory.Tags["N7:0"].ThrowOnRead = false;
+        factory.Tags["N7:0"].Status = 0;
+        await drv.ReadAsync(["X"], CancellationToken.None);
+
+        // 2 more failures — should still be below the threshold.
+        factory.Tags["N7:0"].ThrowOnRead = true;
+        factory.Tags["N7:0"].Exception = new TimeoutException("flap");
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+
+        var state = drv.GetDeviceState(Host).ShouldNotBeNull();
+        state.DemotedUntilUtc.ShouldBeNull();
+        drv.DiagnosticTags.Snapshot(Host).DemoteCount.ShouldBe(0);
+    }
+
+    [Fact]
+    public async Task DemoteCount_and_LastDemotedUtc_surface_via_diagnostic_short_circuit()
+    {
+        var (drv, factory) = NewDriver();
+        SeedFailingTag(factory);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+
+        // Read the synthetic _Diagnostics counters.
+        var demoteCountRef = $"{AbLegacyDiagnosticTags.DiagnosticsFolderPrefix}{Host}/DemoteCount";
+        var lastDemotedRef = $"{AbLegacyDiagnosticTags.DiagnosticsFolderPrefix}{Host}/LastDemotedUtc";
+        var counts = await drv.ReadAsync([demoteCountRef, lastDemotedRef], CancellationToken.None);
+
+        counts[0].StatusCode.ShouldBe(AbLegacyStatusMapper.Good);
+        counts[0].Value.ShouldBe(1L);
+        counts[1].StatusCode.ShouldBe(AbLegacyStatusMapper.Good);
+        counts[1].Value.ShouldBeOfType<string>();
+        ((string)counts[1].Value!).Length.ShouldBeGreaterThan(0); // ISO-8601 stamp
+    }
+
+    [Fact]
+    public async Task Demote_disabled_never_short_circuits_reads()
+    {
+        var (drv, factory) = NewDriver(
+            new AbLegacyDemoteOptions(FailureThreshold: 1, Enabled: false));
+        SeedFailingTag(factory);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        // 5 failures — would normally trip a single-fail threshold, but Enabled=false.
+        for (var i = 0; i < 5; i++) await drv.ReadAsync(["X"], CancellationToken.None);
+
+        var state = drv.GetDeviceState(Host).ShouldNotBeNull();
+        state.DemotedUntilUtc.ShouldBeNull();
+        var snap = drv.DiagnosticTags.Snapshot(Host);
+        snap.DemoteCount.ShouldBe(0);
+        // Failures still get recorded as comm errors though — the diagnostic
+        // surface is honest about what happened, just no auto-throttle.
+        snap.CommFailures.ShouldBe(5);
+        // libplctag was invoked every time — that's the whole point of opting out.
+        factory.Tags["N7:0"].ReadCount.ShouldBe(5);
+    }
+
+    [Fact]
+    public async Task Reinit_preserves_DemoteCount_but_clears_active_demotion()
+    {
+        var (drv, factory) = NewDriver();
+        SeedFailingTag(factory);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+
+        drv.DiagnosticTags.Snapshot(Host).DemoteCount.ShouldBe(1);
+        drv.GetDeviceState(Host)!.DemotedUntilUtc.ShouldNotBeNull();
+
+        await drv.ReinitializeAsync("{}", CancellationToken.None);
+
+        // Active demotion cleared (the device is freshly tracked); cumulative count survives.
+        drv.GetDeviceState(Host)!.DemotedUntilUtc.ShouldBeNull();
+        drv.GetDeviceState(Host)!.ConsecutiveFailures.ShouldBe(0);
+        drv.DiagnosticTags.Snapshot(Host).DemoteCount.ShouldBe(1);
+    }
+
+    [Fact]
+    public async Task Disposing_driver_after_demotion_does_not_throw()
+    {
+        var (drv, factory) = NewDriver();
+        SeedFailingTag(factory);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+        await drv.ReadAsync(["X"], CancellationToken.None);
+
+        await drv.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Demote_options_dto_round_trips_through_factory_extensions()
+    {
+        const string json = """
+            {
+              "Devices": [
+                {
+                  "HostAddress": "ab://10.0.0.5/1,0",
+                  "PlcFamily": "Slc500",
+                  "Demote": {
+                    "FailureThreshold": 5,
+                    "DemoteForMs": 60000,
+                    "Enabled": true
+                  }
+                }
+              ],
+              "Probe": { "Enabled": false },
+              "Tags": [
+                { "Name": "X", "DeviceHostAddress": "ab://10.0.0.5/1,0", "Address": "N7:0", "DataType": "Int" }
+              ]
+            }
+            """;
+
+        var drv = AbLegacyDriverFactoryExtensions.CreateInstance("drv-demote-roundtrip", json);
+        await drv.InitializeAsync(json, CancellationToken.None);
+
+        var state = drv.GetDeviceState(Host).ShouldNotBeNull();
+        state.Options.Demote.ShouldNotBeNull();
+        state.Options.Demote!.FailureThreshold.ShouldBe(5);
+        state.Options.Demote.EffectiveDemoteFor.ShouldBe(TimeSpan.FromMinutes(1));
+        state.Options.Demote.Enabled.ShouldBeTrue();
+
+        await drv.ShutdownAsync(CancellationToken.None);
+    }
+
+    [Fact]
+    public async Task Two_devices_one_faulty_does_not_starve_the_healthy_one()
+    {
+        // Mixed factory — one host's tag throws, the other's reads cleanly.
+        var factory = new FakeAbLegacyTagFactory();
+        factory.Customise = p =>
+        {
+            // Identify by the Gateway portion of the create params.
+            var fail = p.Gateway == "10.0.0.6";
+            return new FakeAbLegacyTag(p)
+            {
+                ThrowOnRead = fail,
+                Exception = fail ? new TimeoutException("faulty") : null,
+                Value = 42,
+                Status = 0,
+            };
+        };
+        var drv = new AbLegacyDriver(new AbLegacyDriverOptions
+        {
+            Devices =
+            [
+                new AbLegacyDeviceOptions(Host, AbLegacyPlcFamily.Slc500),
+                new AbLegacyDeviceOptions(SecondHost, AbLegacyPlcFamily.Slc500),
+            ],
+            Tags =
+            [
+                new AbLegacyTagDefinition("Healthy", Host, "N7:0", AbLegacyDataType.Int),
+                new AbLegacyTagDefinition("Faulty", SecondHost, "N7:0", AbLegacyDataType.Int),
+            ],
+            Probe = new AbLegacyProbeOptions { Enabled = false },
+        }, "drv-mix", factory);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        // Trip the faulty side.
+        for (var i = 0; i < 3; i++)
+            await drv.ReadAsync(["Faulty"], CancellationToken.None);
+
+        // Healthy host MUST keep returning Good even though the sibling is demoted.
+        var healthyResult = await drv.ReadAsync(["Healthy"], CancellationToken.None);
+        healthyResult[0].StatusCode.ShouldBe(AbLegacyStatusMapper.Good);
+        healthyResult[0].Value.ShouldBe(42);
+
+        // Reads against the faulty host short-circuit.
+        var faultyResult = await drv.ReadAsync(["Faulty"], CancellationToken.None);
+        faultyResult[0].StatusCode.ShouldBe(AbLegacyStatusMapper.BadCommunicationError);
+
+        drv.GetDeviceState(Host)!.DemotedUntilUtc.ShouldBeNull();
+        drv.GetDeviceState(SecondHost)!.DemotedUntilUtc.ShouldNotBeNull();
+    }
+
+    [Fact]
+    public async Task BadNodeIdUnknown_does_not_count_toward_demote_tally()
+    {
+        // -14 maps to BadNodeIdUnknown — terminal, not a comm failure.
+        var (drv, factory) = NewDriver();
+        factory.Customise = p => new FakeAbLegacyTag(p) { Status = -14 };
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        for (var i = 0; i < 5; i++)
+            await drv.ReadAsync(["X"], CancellationToken.None);
+
+        var state = drv.GetDeviceState(Host).ShouldNotBeNull();
+        // Five terminal failures shouldn't trip the demote threshold — they're
+        // a config / decoder mismatch, not a sign of a flapping link.
+        state.DemotedUntilUtc.ShouldBeNull();
+        drv.DiagnosticTags.Snapshot(Host).DemoteCount.ShouldBe(0);
+    }
+
+    [Fact]
+    public void HostState_enum_has_Demoted_value()
+    {
+        // Belt-and-braces: the abstraction surface must carry the new value
+        // for downstream consumers (HostStatusPublisher, Admin UI, …) to
+        // see and route it.
+        Enum.IsDefined(typeof(HostState), HostState.Demoted).ShouldBeTrue();
+        ((int)HostState.Demoted).ShouldBeGreaterThan((int)HostState.Faulted);
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/AbLegacyDhPlusBridgingTests.cs

@@ -0,0 +1,147 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Driver.AbLegacy;
+using ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.PlcFamilies;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests;
+
+/// <summary>
+///     PR ablegacy-13 / #256 — coverage for the 1756-DHRIO DH+ bridge form on
+///     <see cref="AbLegacyHostAddress"/>: octal-station validation, slot bounds, port shape,
+///     and the PLC-5-only family guard at <c>AbLegacyDriver.InitializeAsync</c>.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class AbLegacyDhPlusBridgingTests
+{
+    [Theory]
+    // station 07 octal → 7 decimal
+    [InlineData("ab://10.0.0.1/1,3,2,07", 3, 2, 7)]
+    // station 77 octal → 63 decimal (top of the DH+ address range)
+    [InlineData("ab://10.0.0.1/1,3,2,77", 3, 2, 63)]
+    // single-digit station 0..7
+    [InlineData("ab://10.0.0.1/1,0,2,0", 0, 2, 0)]
+    [InlineData("ab://10.0.0.1/1,16,2,77", 16, 2, 63)]
+    // station 10 octal → 8 decimal
+    [InlineData("ab://10.0.0.1/1,3,2,10", 3, 2, 8)]
+    public void DhPlusBridge_parses_valid_octal_station(string input, int slot, int dhPort, int station)
+    {
+        var parsed = AbLegacyHostAddress.TryParse(input);
+        parsed.ShouldNotBeNull();
+        parsed.IsDhPlusBridge.ShouldBeTrue();
+        parsed.BackplaneSlot.ShouldBe(slot);
+        parsed.DhPlusPort.ShouldBe(dhPort);
+        parsed.DhPlusStation.ShouldBe(station);
+    }
+
+    [Theory]
+    // octal-illegal digits 8 / 9 in the station segment
+    [InlineData("ab://10.0.0.1/1,3,2,80")]
+    [InlineData("ab://10.0.0.1/1,3,2,90")]
+    [InlineData("ab://10.0.0.1/1,3,2,08")]
+    [InlineData("ab://10.0.0.1/1,3,2,79")]
+    // port-1 not the backplane (must be exactly 1)
+    [InlineData("ab://10.0.0.1/0,3,2,77")]
+    [InlineData("ab://10.0.0.1/2,3,2,77")]
+    // port-3 not the DH+ port (must be exactly 2)
+    [InlineData("ab://10.0.0.1/1,3,3,77")]
+    [InlineData("ab://10.0.0.1/1,3,1,77")]
+    // slot out of range (max 16)
+    [InlineData("ab://10.0.0.1/1,17,2,07")]
+    [InlineData("ab://10.0.0.1/1,99,2,07")]
+    [InlineData("ab://10.0.0.1/1,-1,2,07")]
+    // wrong segment count
+    [InlineData("ab://10.0.0.1/1,3,2")]
+    [InlineData("ab://10.0.0.1/1,3,2,07,extra")]
+    public void DhPlusBridge_rejects_invalid_form(string input)
+    {
+        // The host-address parser still succeeds (the CIP path stays opaque) — only the
+        // DH+ accessors are absent. That keeps AB-Legacy compatible with paths shaped
+        // similarly to a DHRIO bridge but not actually one (e.g. a future DHRIO-clone
+        // module on a non-backplane-1 port).
+        var parsed = AbLegacyHostAddress.TryParse(input);
+        // For the wrong-segment-count and trailing-extra cases, parsing still produces a
+        // generic record with an opaque CipPath and no DH+ surface. For the octal-illegal
+        // and slot/port out-of-range cases the same applies — the CIP path is preserved
+        // verbatim for libplctag, but the structured DH+ accessors are null because the
+        // path didn't pass the strict bridge-form validator.
+        parsed.ShouldNotBeNull();
+        parsed.IsDhPlusBridge.ShouldBeFalse();
+        parsed.BackplaneSlot.ShouldBeNull();
+        parsed.DhPlusPort.ShouldBeNull();
+        parsed.DhPlusStation.ShouldBeNull();
+    }
+
+    [Fact]
+    public void DhPlusBridge_diagnostics_surface_all_three_fields()
+    {
+        var parsed = AbLegacyHostAddress.TryParse("ab://10.0.0.1/1,7,2,42");
+        parsed.ShouldNotBeNull();
+        parsed.IsDhPlusBridge.ShouldBeTrue();
+        parsed.BackplaneSlot.ShouldBe(7);
+        parsed.DhPlusPort.ShouldBe(2);
+        // 42 octal == 4*8 + 2 == 34 decimal
+        parsed.DhPlusStation.ShouldBe(34);
+        // CIP path is preserved verbatim — libplctag receives the original octal-station
+        // representation, not the decimal-translated one.
+        parsed.CipPath.ShouldBe("1,7,2,42");
+    }
+
+    [Fact]
+    public void NonBridgePath_leaves_dhplus_fields_null()
+    {
+        // Direct-wired SLC 5/05 — empty path
+        var direct = AbLegacyHostAddress.TryParse("ab://10.0.0.1/");
+        direct.ShouldNotBeNull();
+        direct.IsDhPlusBridge.ShouldBeFalse();
+        direct.BackplaneSlot.ShouldBeNull();
+        direct.DhPlusPort.ShouldBeNull();
+        direct.DhPlusStation.ShouldBeNull();
+
+        // Standard ControlLogix backplane bridge — only two segments, not four
+        var twoHop = AbLegacyHostAddress.TryParse("ab://10.0.0.1/1,0");
+        twoHop.ShouldNotBeNull();
+        twoHop.IsDhPlusBridge.ShouldBeFalse();
+        twoHop.BackplaneSlot.ShouldBeNull();
+    }
+
+    [Theory]
+    [InlineData(AbLegacyPlcFamily.Slc500)]
+    [InlineData(AbLegacyPlcFamily.MicroLogix)]
+    [InlineData(AbLegacyPlcFamily.LogixPccc)]
+    public async Task DhPlusBridge_with_non_plc5_family_throws(AbLegacyPlcFamily nonPlc5)
+    {
+        var options = new AbLegacyDriverOptions
+        {
+            Devices = new[]
+            {
+                new AbLegacyDeviceOptions(
+                    HostAddress: "ab://10.0.0.1/1,3,2,07",
+                    PlcFamily: nonPlc5),
+            },
+        };
+        var driver = new AbLegacyDriver(options, "drv-test", new FakeAbLegacyTagFactory());
+        var ex = await Should.ThrowAsync<InvalidOperationException>(async () =>
+            await driver.InitializeAsync("{}", CancellationToken.None));
+        ex.Message.ShouldContain("DHRIO");
+        ex.Message.ShouldContain("PLC-5-only");
+    }
+
+    [Fact]
+    public async Task DhPlusBridge_with_plc5_family_initialises_cleanly()
+    {
+        var options = new AbLegacyDriverOptions
+        {
+            Devices = new[]
+            {
+                new AbLegacyDeviceOptions(
+                    HostAddress: "ab://10.0.0.1/1,3,2,07",
+                    PlcFamily: AbLegacyPlcFamily.Plc5),
+            },
+            // Probe disabled so InitializeAsync doesn't try to spin a probe loop against a
+            // non-existent gateway; the only thing under test is the family validation.
+            Probe = new AbLegacyProbeOptions { Enabled = false },
+        };
+        var driver = new AbLegacyDriver(options, "drv-test", new FakeAbLegacyTagFactory());
+        await driver.InitializeAsync("{}", CancellationToken.None);
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/AbLegacyDiagnosticsTests.cs

@@ -173,7 +173,9 @@ public sealed class AbLegacyDiagnosticsTests
         var diagVars = builder.Variables
             .Where(v => v.Info.FullName.StartsWith(AbLegacyDiagnosticTags.DiagnosticsFolderPrefix))
             .ToList();
-        diagVars.Count.ShouldBe(14); // 7 names × 2 devices
+        // PR ablegacy-12 / #255 — DemoteCount + LastDemotedUtc bring the canonical
+        // count to 9 names per device (was 7 in PR ablegacy-10).
+        diagVars.Count.ShouldBe(AbLegacyDiagnosticTags.DiagnosticTagNames.Count * 2);
         diagVars.ShouldAllBe(v => v.Info.SecurityClass == SecurityClassification.ViewOnly);
     }
 

tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Tests/FakeAbLegacyTag.cs

@@ -84,7 +84,14 @@ internal class FakeAbLegacyTag : IAbLegacyTagRuntime
 
 internal sealed class FakeAbLegacyTagFactory : IAbLegacyTagFactory
 {
-    public Dictionary<string, FakeAbLegacyTag> Tags { get; } = new(StringComparer.OrdinalIgnoreCase);
+    // PR ablegacy-12 / #255 — switched from plain Dictionary to ConcurrentDictionary so
+    // the read path (test thread) and the probe loop (background Task) can both call
+    // Create without corrupting the dict. Pre-PR-12 the race existed but only tipped
+    // a few percent of test runs into KeyNotFoundException; PR-12's added
+    // Interlocked.Exchange writes shifted timing enough to make it deterministic-flaky
+    // (~60%).
+    public System.Collections.Concurrent.ConcurrentDictionary<string, FakeAbLegacyTag> Tags { get; } =
+        new(StringComparer.OrdinalIgnoreCase);
     public Func<AbLegacyTagCreateParams, FakeAbLegacyTag>? Customise { get; set; }
 
     public IAbLegacyTagRuntime Create(AbLegacyTagCreateParams p)

tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FocasCycleDeltaTests.cs

@@ -0,0 +1,290 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.FOCAS;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests;
+
+/// <summary>
+///     Issue #272, plan PR F5-a — unit coverage of the
+///     <c>Production/LastCycleSeconds</c> + <c>Production/LastCycleStartUtc</c>
+///     derivation. The derivation is a pure function of the
+///     <c>FocasProductionInfo</c> snapshot stream + wall-clock; these tests pin
+///     <see cref="FocasDriver.UpdateCycleDerivation"/>'s contract directly so
+///     the per-tick semantics stay locked even if the probe-loop wiring changes.
+/// </summary>
+/// <remarks>
+///     The <c>Production/LastCycle*</c> values are surfaced through the same
+///     fixed-tree dispatcher the F1-b parts-count nodes use (no new wire calls
+///     — pure derivation). The end-to-end shape is exercised by
+///     <see cref="LastCycle_round_trips_through_ReadAsync_after_two_increments"/>
+///     which spins up a real <see cref="FocasDriver"/> + a probe-tick driven
+///     <see cref="FakeFocasClient"/>.
+/// </remarks>
+[Trait("Category", "Unit")]
+public sealed class FocasCycleDeltaTests
+{
+    private const string Host = "focas://10.0.0.5:8193";
+
+    private static FocasDriver.DeviceState NewState() =>
+        new(FocasHostAddress.TryParse(Host)!, new FocasDeviceOptions(Host));
+
+    private static FocasProductionInfo Snap(int parts, int cycleTimerSeconds) =>
+        new(PartsProduced: parts, PartsRequired: 0, PartsTotal: 0, CycleTimeSeconds: cycleTimerSeconds);
+
+    [Fact]
+    public void First_observation_establishes_baseline_without_publishing_LastCycle()
+    {
+        var state = NewState();
+        var t0 = new DateTime(2026, 4, 25, 10, 0, 0, DateTimeKind.Utc);
+
+        FocasDriver.UpdateCycleDerivation(state, Snap(parts: 5, cycleTimerSeconds: 10), t0);
+
+        state.LastCycleSeconds.ShouldBeNull();
+        state.LastCycleStartUtc.ShouldBeNull();
+        state.PreviousPartsCount.ShouldBe(5);
+        state.PreviousCycleTimerSeconds.ShouldBe(10.0);
+    }
+
+    [Fact]
+    public void No_increment_holds_LastCycle_at_null()
+    {
+        var state = NewState();
+        var t0 = new DateTime(2026, 4, 25, 10, 0, 0, DateTimeKind.Utc);
+
+        FocasDriver.UpdateCycleDerivation(state, Snap(5, 10), t0);
+        FocasDriver.UpdateCycleDerivation(state, Snap(5, 12), t0.AddSeconds(2));
+
+        // No parts-count transition — derivation has not yet observed a complete cycle
+        // boundary. LastCycle* stays null until the next positive transition.
+        state.LastCycleSeconds.ShouldBeNull();
+        state.LastCycleStartUtc.ShouldBeNull();
+    }
+
+    [Fact]
+    public void First_increment_publishes_timer_delta_across_the_window()
+    {
+        var state = NewState();
+        var t0 = new DateTime(2026, 4, 25, 10, 0, 0, DateTimeKind.Utc);
+
+        // Tick 1: parts=5, timer=10 — baseline.
+        FocasDriver.UpdateCycleDerivation(state, Snap(5, 10), t0);
+        // Tick 2: parts=5, timer=12 — no increment, no publish.
+        FocasDriver.UpdateCycleDerivation(state, Snap(5, 12), t0.AddSeconds(2));
+        // Tick 3: parts=6, timer=18 — first increment. Delta = 18 - 10 = 8s
+        // (we keep the cycle-timer baseline pinned to the LAST INCREMENT, not the
+        // last sample, so the delta covers the true window between increments).
+        FocasDriver.UpdateCycleDerivation(state, Snap(6, 18), t0.AddSeconds(8));
+
+        state.LastCycleSeconds.ShouldBe(8.0);
+        state.LastCycleStartUtc.ShouldNotBeNull();
+        state.LastCycleStartUtc!.Value.ShouldBe(t0);
+    }
+
+    [Fact]
+    public void Second_increment_publishes_fresh_delta()
+    {
+        var state = NewState();
+        var t0 = new DateTime(2026, 4, 25, 10, 0, 0, DateTimeKind.Utc);
+
+        FocasDriver.UpdateCycleDerivation(state, Snap(5, 10), t0);
+        FocasDriver.UpdateCycleDerivation(state, Snap(6, 18), t0.AddSeconds(8));
+        // Tick 4: parts=7, timer=25 — second increment. Delta = 25 - 18 = 7s.
+        FocasDriver.UpdateCycleDerivation(state, Snap(7, 25), t0.AddSeconds(15));
+
+        state.LastCycleSeconds.ShouldBe(7.0);
+        state.LastCycleStartUtc!.Value.ShouldBe(t0.AddSeconds(8));
+    }
+
+    [Fact]
+    public void Parts_count_reset_preserves_last_known_LastCycle_values()
+    {
+        var state = NewState();
+        var t0 = new DateTime(2026, 4, 25, 10, 0, 0, DateTimeKind.Utc);
+
+        FocasDriver.UpdateCycleDerivation(state, Snap(5, 10), t0);
+        FocasDriver.UpdateCycleDerivation(state, Snap(6, 18), t0.AddSeconds(8));
+        var publishedSeconds = state.LastCycleSeconds;
+        var publishedStart = state.LastCycleStartUtc;
+        publishedSeconds.ShouldBe(8.0);
+
+        // Parts-count reset (e.g. shift change) — value goes backwards. The
+        // derivation must NOT publish a negative LastCycleSeconds; instead it
+        // re-baselines so the next positive transition produces a fresh delta.
+        // The previously-published values stay live (operators reading the tag
+        // mid-shift-change see the last known cycle, not Bad / null).
+        FocasDriver.UpdateCycleDerivation(state, Snap(0, 0), t0.AddSeconds(20));
+
+        state.LastCycleSeconds.ShouldBe(publishedSeconds);
+        state.LastCycleStartUtc.ShouldBe(publishedStart);
+        state.PreviousPartsCount.ShouldBe(0);
+        state.PreviousCycleTimerSeconds.ShouldBe(0.0);
+
+        // Next positive transition produces the new delta.
+        FocasDriver.UpdateCycleDerivation(state, Snap(1, 6), t0.AddSeconds(26));
+        state.LastCycleSeconds.ShouldBe(6.0);
+    }
+
+    [Fact]
+    public void Cycle_timer_rollover_on_increment_does_not_publish_negative_delta()
+    {
+        var state = NewState();
+        var t0 = new DateTime(2026, 4, 25, 10, 0, 0, DateTimeKind.Utc);
+
+        FocasDriver.UpdateCycleDerivation(state, Snap(5, 18), t0);
+        // Tick 2: parts=6 (positive transition) but timer rolled to 0 (CNC reset
+        // the cycle-time timer at part completion). Per the plan we treat this
+        // as rollover: re-baseline without publishing a negative delta.
+        FocasDriver.UpdateCycleDerivation(state, Snap(6, 0), t0.AddSeconds(1));
+
+        state.LastCycleSeconds.ShouldBeNull();
+        state.LastCycleStartUtc.ShouldBeNull();
+
+        // Subsequent increment publishes a clean delta from the post-rollover
+        // baseline.
+        FocasDriver.UpdateCycleDerivation(state, Snap(7, 9), t0.AddSeconds(10));
+        state.LastCycleSeconds.ShouldBe(9.0);
+    }
+
+    [Fact]
+    public void Parts_count_jump_publishes_window_timer_delta_without_per_part_division()
+    {
+        var state = NewState();
+        var t0 = new DateTime(2026, 4, 25, 10, 0, 0, DateTimeKind.Utc);
+
+        FocasDriver.UpdateCycleDerivation(state, Snap(5, 10), t0);
+        // Backfill: parts jumps 5 -> 8. Per the plan we treat the timer delta
+        // over the window as the most-recent cycle's actual duration; we do NOT
+        // divide by the count delta.
+        FocasDriver.UpdateCycleDerivation(state, Snap(8, 25), t0.AddSeconds(15));
+
+        state.LastCycleSeconds.ShouldBe(15.0);
+        state.LastCycleStartUtc!.Value.ShouldBe(t0);
+    }
+
+    [Fact]
+    public async Task ReinitializeAsync_clears_LastCycle_state()
+    {
+        // ReinitializeAsync = ShutdownAsync + InitializeAsync. ShutdownAsync clears
+        // _devices entirely and InitializeAsync constructs fresh DeviceState
+        // instances, so the F5-a derivation history is reset across reinit per
+        // the plan ("the prior CNC connection's history doesn't apply post-
+        // reconnect").
+        var fake = new ProductionAwareFakeClient
+        {
+            Production = new FocasProductionInfo(5, 0, 0, 10),
+        };
+        var factory = new FakeFocasClientFactory { Customise = () => fake };
+        var driver = new FocasDriver(new FocasDriverOptions
+        {
+            Devices = [new FocasDeviceOptions(Host)],
+            Tags = [],
+            Probe = new FocasProbeOptions { Enabled = true, Interval = TimeSpan.FromMilliseconds(50) },
+        }, "drv-1", factory);
+        await driver.InitializeAsync("{}", CancellationToken.None);
+
+        // Drive two increments through the probe loop so the device has live
+        // LastCycle* state.
+        await WaitForAsync(() =>
+        {
+            var s = driver.GetDeviceState(Host);
+            return Task.FromResult(s?.PreviousPartsCount == 5);
+        }, TimeSpan.FromSeconds(3));
+        fake.Production = new FocasProductionInfo(6, 0, 0, 18);
+        await WaitForAsync(() =>
+        {
+            var s = driver.GetDeviceState(Host);
+            return Task.FromResult(s?.LastCycleSeconds == 8.0);
+        }, TimeSpan.FromSeconds(3));
+
+        await driver.ReinitializeAsync("{}", CancellationToken.None);
+
+        // The operator-visible LastCycle* values reset across the reinit
+        // boundary — the prior CNC session's history doesn't carry over.
+        // Previous*/baseline state may re-populate quickly because the probe
+        // loop restarts immediately after init, but until a NEW post-reinit
+        // increment is observed the published LastCycle* values stay null.
+        var post = driver.GetDeviceState(Host);
+        post.ShouldNotBeNull();
+        post!.LastCycleSeconds.ShouldBeNull();
+        post.LastCycleStartUtc.ShouldBeNull();
+
+        await driver.ShutdownAsync(CancellationToken.None);
+    }
+
+    [Fact]
+    public void DeviceState_initial_field_values_are_all_null()
+    {
+        // Direct invariant — fresh DeviceState (constructed during InitializeAsync)
+        // has all derivation history set to null. This is the contract a reinit
+        // relies on (ShutdownAsync clears _devices; InitializeAsync constructs
+        // fresh DeviceState instances).
+        var state = NewState();
+        state.PreviousPartsCount.ShouldBeNull();
+        state.PreviousCycleTimerSeconds.ShouldBeNull();
+        state.PreviousIncrementAtUtc.ShouldBeNull();
+        state.LastCycleSeconds.ShouldBeNull();
+        state.LastCycleStartUtc.ShouldBeNull();
+    }
+
+    [Fact]
+    public async Task LastCycle_round_trips_through_ReadAsync_after_two_increments()
+    {
+        // End-to-end: a probe-tick-driven snapshot stream into a real FocasDriver
+        // produces Production/LastCycleSeconds + Production/LastCycleStartUtc
+        // through the standard ReadAsync path. No additional wire calls fire —
+        // both nodes are served from DeviceState.LastCycle*.
+        var fake = new ProductionAwareFakeClient
+        {
+            Production = new FocasProductionInfo(5, 0, 0, 10),
+        };
+        var factory = new FakeFocasClientFactory { Customise = () => fake };
+        var driver = new FocasDriver(new FocasDriverOptions
+        {
+            Devices = [new FocasDeviceOptions(Host)],
+            Tags = [],
+            Probe = new FocasProbeOptions { Enabled = true, Interval = TimeSpan.FromMilliseconds(40) },
+        }, "drv-1", factory);
+        await driver.InitializeAsync("{}", CancellationToken.None);
+
+        // First increment baseline + flip to second value to produce a delta.
+        await WaitForAsync(() =>
+        {
+            var s = driver.GetDeviceState(Host);
+            return Task.FromResult(s?.PreviousPartsCount == 5);
+        }, TimeSpan.FromSeconds(3));
+        fake.Production = new FocasProductionInfo(6, 0, 0, 18);
+        await WaitForAsync(() =>
+        {
+            var s = driver.GetDeviceState(Host);
+            return Task.FromResult(s?.LastCycleSeconds == 8.0);
+        }, TimeSpan.FromSeconds(3));
+
+        var refs = new[]
+        {
+            $"{Host}::Production/LastCycleSeconds",
+            $"{Host}::Production/LastCycleStartUtc",
+        };
+        var snaps = await driver.ReadAsync(refs, CancellationToken.None);
+        snaps[0].StatusCode.ShouldBe(FocasStatusMapper.Good);
+        snaps[0].Value.ShouldBe(8.0);
+        snaps[1].StatusCode.ShouldBe(FocasStatusMapper.Good);
+        snaps[1].Value.ShouldBeOfType<DateTime>();
+
+        await driver.ShutdownAsync(CancellationToken.None);
+    }
+
+    private static async Task WaitForAsync(Func<Task<bool>> condition, TimeSpan timeout)
+    {
+        var deadline = DateTime.UtcNow + timeout;
+        while (!await condition() && DateTime.UtcNow < deadline)
+            await Task.Delay(20);
+    }
+
+    private sealed class ProductionAwareFakeClient : FakeFocasClient, IFocasClient
+    {
+        public FocasProductionInfo? Production { get; set; }
+        Task<FocasProductionInfo?> IFocasClient.GetProductionAsync(CancellationToken ct) =>
+            Task.FromResult(Production);
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FocasProductionFixedTreeTests.cs

@@ -39,9 +39,12 @@ public sealed class FocasProductionFixedTreeTests
         builder.Folders.ShouldContain(f => f.BrowseName == "Production" && f.DisplayName == "Production");
         var prodVars = builder.Variables.Where(v =>
             v.Info.FullName.Contains("::Production/")).ToList();
-        prodVars.Count.ShouldBe(4);
+        // Issue #272 (plan PR F5-a) added the two derived telemetry nodes
-        string[] expected = ["PartsProduced", "PartsRequired", "PartsTotal", "CycleTimeSeconds"];
+        // LastCycleSeconds + LastCycleStartUtc on top of the original 4 F1-b
-        foreach (var name in expected)
+        // wire-sourced fields, for 6 total Production/ children per device.
+        prodVars.Count.ShouldBe(6);
+        string[] int32Fields = ["PartsProduced", "PartsRequired", "PartsTotal", "CycleTimeSeconds"];
+        foreach (var name in int32Fields)
         {
             var node = prodVars.SingleOrDefault(v => v.BrowseName == name);
             node.BrowseName.ShouldBe(name);
@@ -49,6 +52,17 @@ public sealed class FocasProductionFixedTreeTests
             node.Info.SecurityClass.ShouldBe(SecurityClassification.ViewOnly);
             node.Info.FullName.ShouldBe($"{Host}::Production/{name}");
         }
+        // F5-a derived telemetry — LastCycleSeconds is Float64 (sub-second
+        // precision is meaningful at fast cycle times); LastCycleStartUtc is
+        // DateTime UTC, matching the Diagnostics/LastSuccessfulRead surface.
+        var lastSec = prodVars.SingleOrDefault(v => v.BrowseName == "LastCycleSeconds");
+        lastSec.BrowseName.ShouldBe("LastCycleSeconds");
+        lastSec.Info.DriverDataType.ShouldBe(DriverDataType.Float64);
+        lastSec.Info.SecurityClass.ShouldBe(SecurityClassification.ViewOnly);
+        var lastStart = prodVars.SingleOrDefault(v => v.BrowseName == "LastCycleStartUtc");
+        lastStart.BrowseName.ShouldBe("LastCycleStartUtc");
+        lastStart.Info.DriverDataType.ShouldBe(DriverDataType.DateTime);
+        lastStart.Info.SecurityClass.ShouldBe(SecurityClassification.ViewOnly);
     }
 
     [Fact]

tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/Series/CycleDeltaTests.cs

@@ -0,0 +1,57 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests.Series;
+
+/// <summary>
+///     Issue #272, plan PR F5-a — series-level (would-be integration) coverage of
+///     <c>Production/LastCycleSeconds</c> + <c>Production/LastCycleStartUtc</c>.
+///     The derivation is pure (no new wire calls — see
+///     <c>docs/v2/focas-deployment.md</c> § "Derived telemetry") so the
+///     real-simulator test asserts the existing <c>cnc_rdparam(6711)</c> +
+///     cycle-timer poll that F1-b already emits drives both fields end-to-end.
+/// </summary>
+/// <remarks>
+///     Build-only today: focas-mock has not yet shipped (tracked under
+///     <c>docs/v2/implementation/focas-simulator-plan.md</c> § "Cycle-time per
+///     part / last cycle delta — F5-a"). The unit-test coverage in
+///     <see cref="FocasCycleDeltaTests"/> exercises every same-process invariant
+///     of the derivation. The gated test below materialises the
+///     <c>SimulateCycleCompletionAsync</c> + admin-endpoint contract once the
+///     simulator binary lands.
+/// </remarks>
+[Trait("Category", "Series")]
+public sealed class CycleDeltaTests
+{
+    [Fact]
+    public void Derivation_contract_is_documented()
+    {
+        // Build-only scaffold — see FocasCycleDeltaTests for the actual fake-backed
+        // assertion. The integration version of this test (gated on a focas-mock
+        // simulator with a SimulateCycleCompletionAsync admin endpoint) will:
+        //   1. Spin up FocasDriver pointed at the simulator with parts=5, timer=10s.
+        //   2. Wait for the first probe tick (baseline established).
+        //   3. Call simulator.SimulateCycleCompletionAsync(profile, parts: 6, timer: 18s).
+        //   4. Wait for the next probe tick to refresh the production cache.
+        //   5. Read Production/LastCycleSeconds + Production/LastCycleStartUtc through
+        //      the OPC UA surface; assert delta == 8.0 and the timestamp is now - 8s.
+        // The driver-side derivation already locks the contract in unit tests; this
+        // scaffold pins the simulator-side contract for the focas-mock implementor.
+        var info = typeof(FocasDriver).GetMethod(
+            nameof(FocasDriver.UpdateCycleDerivation),
+            System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Static);
+        info.ShouldNotBeNull();
+    }
+
+    [Fact(Skip = "Hardware-gated — requires focas-mock with the SimulateCycleCompletionAsync admin endpoint (focas-simulator-plan.md § 'Cycle-time per part / last cycle delta — F5-a').")]
+    public Task Live_simulator_cycle_completion_round_trip()
+    {
+        // Body deliberately empty — the [Skip] attribute keeps this off the CI
+        // lane. When focas-mock lands the SimulateCycleCompletionAsync helper +
+        // matching admin endpoint, this test materialises a FocasDriver pointed
+        // at the simulator + drives the parts-count 5 -> 6 transition through real
+        // wire calls.
+        return Task.CompletedTask;
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/Docker/docker-compose.yml

@@ -44,6 +44,34 @@ services:
       retries: 10
       start_period: 10s
 
+  # opc-plc-secondary — second opc-plc instance for upstream-redundancy testing
+  # (PR-14, issue #286). Listens on a different port so it can run alongside the
+  # primary; the integration test suite drives a ServiceLevel drop on the primary
+  # and asserts the driver fails over onto the secondary's session. Both
+  # instances are independent — this isn't a real OPC UA redundant pair (there's
+  # no shared address space), but the failover-decision wiring is what we need
+  # to validate end-to-end.
+  opc-plc-secondary:
+    image: mcr.microsoft.com/iotedge/opc-plc:2.14.10
+    container_name: otopcua-opc-plc-secondary
+    restart: "no"
+    ports:
+      - "50002:50000"
+    command:
+      # Same flags as the primary so the test session-shape is identical. --pn
+      # stays at 50000 inside the container; the host-side port-map above puts
+      # it at 50002 for the test runner.
+      - "--pn=50000"
+      - "--ut"
+      - "--aa"
+      - "--alm"
+    healthcheck:
+      test: ["CMD-SHELL", "netstat -an | grep -q ':50000.*LISTEN' || exit 1"]
+      interval: 5s
+      timeout: 2s
+      retries: 10
+      start_period: 10s
+
   # opc-plc-rc — reverse-connect (server-initiated) variant. The simulator
   # acts as the OPC UA server but, unlike the regular service above, it dials
   # OUT to the client's listener URL instead of accepting an inbound dial.

tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/OpcPlcRedundancyFixture.cs

@@ -0,0 +1,95 @@
+using System.Net.Sockets;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests;
+
+/// <summary>
+///     Multi-endpoint fixture for upstream-redundancy smoke tests (PR-14, issue #286).
+///     Probes both <c>opc-plc</c> instances from the docker-compose stack —
+///     <c>opc-plc</c> on 50000 + <c>opc-plc-secondary</c> on 50002 — and exposes
+///     a <see cref="SkipReason"/> when either is unreachable. Tests use the pair to
+///     drive a ServiceLevel drop on the primary and assert the driver fails over
+///     to the secondary mid-session.
+/// </summary>
+/// <remarks>
+///     The primary endpoint URL can be overridden via <c>OPCUA_SIM_ENDPOINT</c> + the
+///     secondary via <c>OPCUA_SIM_ENDPOINT_SECONDARY</c> for runs against real
+///     redundant servers. Defaults assume the docker-compose stack is up locally
+///     (<c>docker compose -f Docker/docker-compose.yml up opc-plc opc-plc-secondary</c>).
+/// </remarks>
+public sealed class OpcPlcRedundancyFixture : IAsyncDisposable
+{
+    private const string DefaultPrimary = "opc.tcp://localhost:50000";
+    private const string DefaultSecondary = "opc.tcp://localhost:50002";
+    private const string PrimaryEnvVar = "OPCUA_SIM_ENDPOINT";
+    private const string SecondaryEnvVar = "OPCUA_SIM_ENDPOINT_SECONDARY";
+
+    public string PrimaryEndpointUrl { get; }
+    public string SecondaryEndpointUrl { get; }
+    public string? SkipReason { get; }
+
+    public OpcPlcRedundancyFixture()
+    {
+        PrimaryEndpointUrl = Environment.GetEnvironmentVariable(PrimaryEnvVar) ?? DefaultPrimary;
+        SecondaryEndpointUrl = Environment.GetEnvironmentVariable(SecondaryEnvVar) ?? DefaultSecondary;
+
+        if (!ProbeTcp(PrimaryEndpointUrl, out var primaryReason))
+        {
+            SkipReason = primaryReason;
+            return;
+        }
+        if (!ProbeTcp(SecondaryEndpointUrl, out var secondaryReason))
+        {
+            SkipReason = secondaryReason;
+            return;
+        }
+    }
+
+    private static bool ProbeTcp(string endpointUrl, out string? skipReason)
+    {
+        skipReason = null;
+        var (host, port) = ParseHostPort(endpointUrl);
+        try
+        {
+            using var client = new TcpClient(AddressFamily.InterNetwork);
+            var task = client.ConnectAsync(
+                System.Net.Dns.GetHostAddresses(host)
+                    .FirstOrDefault(a => a.AddressFamily == AddressFamily.InterNetwork)
+                    ?? System.Net.IPAddress.Loopback,
+                port);
+            if (!task.Wait(TimeSpan.FromSeconds(2)) || !client.Connected)
+            {
+                skipReason = $"opc-plc instance at {host}:{port} did not accept a TCP connection within 2s. " +
+                             "Start it (`docker compose -f Docker/docker-compose.yml up opc-plc opc-plc-secondary`).";
+                return false;
+            }
+            return true;
+        }
+        catch (Exception ex)
+        {
+            skipReason = $"opc-plc instance at {host}:{port} unreachable: {ex.GetType().Name}: {ex.Message}.";
+            return false;
+        }
+    }
+
+    private static (string Host, int Port) ParseHostPort(string endpointUrl)
+    {
+        const string scheme = "opc.tcp://";
+        var body = endpointUrl.StartsWith(scheme, StringComparison.OrdinalIgnoreCase)
+            ? endpointUrl[scheme.Length..]
+            : endpointUrl;
+        var slash = body.IndexOf('/');
+        if (slash >= 0) body = body[..slash];
+        var colon = body.IndexOf(':');
+        if (colon < 0) return (body, 4840);
+        var host = body[..colon];
+        return int.TryParse(body[(colon + 1)..], out var p) ? (host, p) : (host, 4840);
+    }
+
+    public ValueTask DisposeAsync() => ValueTask.CompletedTask;
+}
+
+[Xunit.CollectionDefinition(Name)]
+public sealed class OpcPlcRedundancyCollection : Xunit.ICollectionFixture<OpcPlcRedundancyFixture>
+{
+    public const string Name = "OpcPlcRedundancy";
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/OpcUaClientAggregateSweepTests.cs

@@ -0,0 +1,115 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests;
+
+/// <summary>
+///     Sweep coverage for the full <see cref="HistoryAggregateType"/> catalog over a real
+///     <c>opc-plc</c> upstream. Loops every enum value, calls <c>ReadProcessedAsync</c> with a
+///     1-second processing interval, and asserts the wire path doesn't crash even when the
+///     simulator declines to honour a particular aggregate (it returns
+///     <c>BadAggregateNotSupported</c> on the per-row HistoryRead result rather than a
+///     thrown exception).
+/// </summary>
+/// <remarks>
+///     <para>
+///         <b>Build-only scaffold for now.</b> opc-plc's default profile doesn't enable
+///         history simulation on the well-known nodes — <c>ns=3;s=StepUp</c> isn't
+///         historized out of the box. This test therefore <see cref="Assert.Skip(string)"/>
+///         until the fixture image is upgraded to one of the opc-plc history-sim profiles
+///         (e.g. <c>--useslowtypes</c> + <c>--ut=10</c>) AND a known-good historized
+///         NodeId is wired into <see cref="OpcPlcProfile"/>.
+///     </para>
+///     <para>
+///         <b>Why it sweeps every enum.</b> The unit-test sweep
+///         (<c>OpcUaClientAggregateMappingTests</c>) covers the enum-to-NodeId mapping.
+///         This integration test catches any wire-side regression where the SDK rejects
+///         a NodeId we thought was well-known — e.g. a future SDK version retires a
+///         constant. Aggregates the simulator doesn't honour come back as
+///         <c>BadAggregateNotSupported</c>; we count and log them rather than failing,
+///         since server-side support is a runtime capability advertisement, not a
+///         driver-side bug.
+///     </para>
+/// </remarks>
+[Collection(OpcPlcCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Simulator", "opc-plc")]
+public sealed class OpcUaClientAggregateSweepTests(OpcPlcFixture sim)
+{
+    /// <summary>
+    ///     Iterates the entire <see cref="HistoryAggregateType"/> enum against opc-plc.
+    ///     Each call must return a result object (possibly with empty samples and/or a
+    ///     bad-status row inside) without throwing; aggregates the simulator declines are
+    ///     surfaced as <c>BadAggregateNotSupported</c> on the data rows rather than failing
+    ///     the test.
+    /// </summary>
+    [Fact]
+    public async Task ReadProcessedAsync_sweeps_every_HistoryAggregateType_without_crashing()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+
+        Assert.Skip(
+            "opc-plc default profile does not enable HistoryRead on well-known nodes. " +
+            "Re-enable when OpcPlcFixture is upgraded to a history-sim profile and a known " +
+            "historized NodeId is added to OpcPlcProfile (e.g. --useslowtypes --ut=10).");
+
+#pragma warning disable CS0162 // unreachable scaffold below — kept for the post-fixture-upgrade flip
+        var options = OpcPlcProfile.BuildOptions(sim.EndpointUrl);
+        await using var drv = new OpcUaClientDriver(options, driverInstanceId: "opcua-aggregate-sweep");
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var end = DateTime.UtcNow;
+        var start = end.AddMinutes(-1);
+        var interval = TimeSpan.FromSeconds(1);
+        // Placeholder NodeId — swap to OpcPlcProfile.HistorizedNode once the fixture is upgraded.
+        const string historizedNode = OpcPlcProfile.StepUp;
+
+        var unsupported = new List<HistoryAggregateType>();
+        var supported = new List<HistoryAggregateType>();
+
+        foreach (var aggregate in Enum.GetValues<HistoryAggregateType>())
+        {
+            HistoryReadResult? result = null;
+            try
+            {
+                result = await drv.ReadProcessedAsync(
+                    historizedNode, start, end, interval, aggregate,
+                    TestContext.Current.CancellationToken);
+            }
+            catch (Exception ex)
+            {
+                Assert.Fail(
+                    $"ReadProcessedAsync({aggregate}) threw {ex.GetType().Name}: {ex.Message}. " +
+                    "Wire path should never throw — unsupported aggregates surface as BadAggregateNotSupported.");
+            }
+
+            result.ShouldNotBeNull();
+
+            // BadAggregateNotSupported = 0x80330000 per OPC UA Part 4 status codes. Detect by
+            // inspecting the per-row StatusCode — opc-plc returns the bad code on the (single)
+            // sample row when it can't honour the aggregate.
+            const uint BadAggregateNotSupported = 0x80330000;
+            const uint BadHistoryOperationUnsupported = 0x80710000;
+            var anyBadAggregate = result.Samples.Any(s =>
+                s.StatusCode == BadAggregateNotSupported ||
+                s.StatusCode == BadHistoryOperationUnsupported);
+            if (anyBadAggregate || result.Samples.Count == 0)
+            {
+                unsupported.Add(aggregate);
+            }
+            else
+            {
+                supported.Add(aggregate);
+            }
+        }
+
+        // Sanity: at least one aggregate should round-trip cleanly. If none do, the upstream
+        // is wholly history-disabled and the fixture-upgrade gate above didn't kick in.
+        supported.Count.ShouldBeGreaterThan(0,
+            "at least one Part 13 aggregate should round-trip against opc-plc; " +
+            $"all {Enum.GetValues<HistoryAggregateType>().Length} returned BadAggregateNotSupported. " +
+            $"Unsupported set: {string.Join(", ", unsupported)}");
+#pragma warning restore CS0162
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/OpcUaClientHistoryEventsTests.cs

@@ -0,0 +1,64 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests;
+
+/// <summary>
+///     End-to-end smoke against a live <c>opc-plc</c> simulator launched in alarm mode
+///     (<c>--alm</c>). Exercises the filter-aware
+///     <see cref="OpcUaClientDriver.ReadEventsAsync(string, EventHistoryRequest, System.Threading.CancellationToken)"/>
+///     overload by issuing a HistoryReadEvents against the simulator's <c>Server</c> notifier
+///     and asserting at least one historical event row comes back with the SelectClause
+///     fields populated.
+/// </summary>
+/// <remarks>
+///     Requires the simulator started with <c>--alm</c> (alarm + history simulation), which
+///     <see cref="OpcPlcFixture"/> does not guarantee — the test skips with a clear reason
+///     when the upstream returns <c>BadHistoryOperationUnsupported</c> instead of a HistoryEvent
+///     payload. PR-12 ships the build-only scaffold; the green-test pass lands when the
+///     fixture image is upgraded to the alarm SKU.
+/// </remarks>
+[Collection(OpcPlcCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Simulator", "opc-plc")]
+public sealed class OpcUaClientHistoryEventsTests(OpcPlcFixture sim)
+{
+    [Fact]
+    public async Task ReadEventsAsync_against_opc_plc_alarm_mode_returns_BaseEventType_fields()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+
+        // Build-only scaffold: the test wires up the call but skips before assertions until
+        // the opc-plc fixture is launched with --alm. When the fixture image carries alarms
+        // the call should round-trip through Session.HistoryReadAsync + ReadEventDetails and
+        // produce at least one HistoricalEventRow with the default SelectClause keys
+        // populated (EventId / SourceName / Time / Message / Severity / ReceiveTime).
+        Assert.Skip(
+            "opc-plc --alm mode not guaranteed by the default fixture image. " +
+            "Re-enable when OpcPlcFixture is upgraded to launch with --alm and a known-good " +
+            "alarm event source path.");
+
+#pragma warning disable CS0162 // unreachable scaffold below — kept for the post-fixture-upgrade flip
+        var options = OpcPlcProfile.BuildOptions(sim.EndpointUrl);
+        await using var drv = new OpcUaClientDriver(options, driverInstanceId: "opcua-events-smoke");
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var request = new EventHistoryRequest(
+            StartTime: DateTime.UtcNow.AddMinutes(-30),
+            EndTime: DateTime.UtcNow.AddMinutes(1),
+            NumValuesPerNode: 100,
+            SelectClauses: null,
+            WhereClause: null);
+
+        // The Server node (i=2253) is the standard history-events notifier on opc-plc.
+        var batch = await drv.ReadEventsAsync("i=2253", request, TestContext.Current.CancellationToken);
+
+        batch.ShouldNotBeNull();
+        batch.Events.Count.ShouldBeGreaterThan(0, "opc-plc --alm raises events at least every 5s");
+        var first = batch.Events[0];
+        first.Fields.ShouldContainKey("EventId");
+        first.Fields.ShouldContainKey("Severity");
+#pragma warning restore CS0162
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/OpcUaClientRedundancySmokeTests.cs

@@ -0,0 +1,65 @@
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests;
+
+/// <summary>
+///     Upstream-redundancy smoke (PR-14, issue #286). Asserts the driver discovers
+///     the upstream's redundant peer list, watches <c>ServiceLevel</c> via
+///     subscription, and fails over onto the secondary when the primary's level
+///     drops below threshold. Build-only by default — opc-plc doesn't expose a
+///     ServiceLevel knob from the outside, so the smoke runs the discovery + initial
+///     subscribe paths against the real simulator and uses the driver's test seam to
+///     synthesize the drop.
+/// </summary>
+/// <remarks>
+///     <para>
+///         <b>Why opc-plc isn't a "real" redundant pair</b>: each opc-plc instance is
+///         independent — they don't federate ServerArray with each other. The smoke
+///         test seeds the peer list manually (mirroring what the discovery pass would
+///         find on a real redundant server) and asserts the failover-decision wiring
+///         works end-to-end against two live SDK sessions. Wire-level coverage against
+///         a real redundant server pair is an env-gated follow-up.
+///     </para>
+///     <para>
+///         <b>Build-only gating</b>: when <see cref="OpcPlcRedundancyFixture.SkipReason"/>
+///         is set the test calls <c>Assert.Skip</c> with the message; CI runs that don't
+///         spin up the secondary container skip cleanly.
+///     </para>
+/// </remarks>
+[Collection(OpcPlcRedundancyCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Simulator", "opc-plc-redundant")]
+public sealed class OpcUaClientRedundancySmokeTests(OpcPlcRedundancyFixture fx)
+{
+    [Fact]
+    public async Task Driver_initializes_and_exposes_redundancy_diagnostics_against_live_pair()
+    {
+        if (fx.SkipReason is not null) Assert.Skip(fx.SkipReason);
+
+        var options = new OpcUaClientDriverOptions
+        {
+            EndpointUrls = [fx.PrimaryEndpointUrl, fx.SecondaryEndpointUrl],
+            SecurityPolicy = OpcUaSecurityPolicy.None,
+            SecurityMode = OpcUaSecurityMode.None,
+            AuthType = OpcUaAuthType.Anonymous,
+            AutoAcceptCertificates = true,
+            Timeout = TimeSpan.FromSeconds(15),
+            SessionTimeout = TimeSpan.FromSeconds(60),
+            Redundancy = new RedundancyOptions(
+                Enabled: true,
+                ServiceLevelThreshold: 200),
+        };
+
+        await using var drv = new OpcUaClientDriver(options, "opcua-redundancy-smoke");
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        // Discovery is best-effort: opc-plc doesn't advertise itself in
+        // ServerUriArray, so _redundancyPeers may be empty after init. The diagnostic
+        // counters MUST be exposed regardless so operators see a stable surface.
+        var diags = drv.GetHealth().Diagnostics;
+        diags.ShouldNotBeNull();
+        diags!.ShouldContainKey("RedundancyFailoverCount");
+        diags.ShouldContainKey("RedundancyFailoverFailures");
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/OpcUaClientAggregateMappingTests.cs

@@ -0,0 +1,156 @@
+using Opc.Ua;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests;
+
+/// <summary>
+///     Sweep coverage for <see cref="OpcUaClientDriver.MapAggregateToNodeId"/> over the full
+///     <see cref="HistoryAggregateType"/> catalog. PR-13 (issue #285) extended the enum from 5
+///     to ~30 values matching OPC UA Part 13 §5; these tests guard the mapping table so a
+///     future addition either gets a switch arm or trips the
+///     <see cref="ArgumentOutOfRangeException"/> default — never silently returns
+///     <c>NodeId.Null</c>.
+/// </summary>
+/// <remarks>
+///     <para>
+///         <b>Why this is unit-only.</b> The OPC UA Part 13 aggregate NodeIds are well-known —
+///         the SDK exposes them as static readonly fields on <c>Opc.Ua.ObjectIds</c>. Round-trip
+///         testing against a live upstream is the integration suite's job (see
+///         <c>OpcUaClientAggregateSweepTests</c>); the wire path doesn't add anything to the
+///         enum-to-NodeId mapping itself.
+///     </para>
+///     <para>
+///         <b>Cascading-quality rule.</b> Aggregates the upstream server doesn't honour come
+///         back with <c>BadAggregateNotSupported</c> on the per-row HistoryRead result, not as
+///         a thrown exception — the driver's mapping is best-effort by design.
+///     </para>
+/// </remarks>
+[Trait("Category", "Unit")]
+public sealed class OpcUaClientAggregateMappingTests
+{
+    /// <summary>
+    ///     Every declared <see cref="HistoryAggregateType"/> value resolves to a non-null
+    ///     namespace-0 <see cref="NodeId"/>. Sweeps the full enum so a new value can't land
+    ///     without a switch arm — the default branch throws
+    ///     <see cref="ArgumentOutOfRangeException"/> which the test would surface immediately.
+    /// </summary>
+    [Theory]
+    [MemberData(nameof(AllHistoryAggregateTypes))]
+    public void MapAggregateToNodeId_resolves_every_enum_value_to_a_namespace0_NodeId(HistoryAggregateType aggregate)
+    {
+        var nodeId = OpcUaClientDriver.MapAggregateToNodeId(aggregate);
+
+        NodeId.IsNull(nodeId).ShouldBeFalse(
+            $"HistoryAggregateType.{aggregate} must map to a Part 13 AggregateFunction_* NodeId");
+        nodeId.NamespaceIndex.ShouldBe((ushort)0,
+            $"HistoryAggregateType.{aggregate} maps to a standard NodeId — namespace must be 0");
+        nodeId.IdType.ShouldBe(IdType.Numeric,
+            $"HistoryAggregateType.{aggregate} maps to a numeric Part 13 NodeId");
+    }
+
+    /// <summary>
+    ///     Regression cover for the original 5 ordinals — Average/Minimum/Maximum/Total/Count
+    ///     stay pinned to their existing SDK NodeIds. Guards against an accidental swap when
+    ///     the switch table grew to ~30 arms.
+    /// </summary>
+    [Theory]
+    [InlineData(HistoryAggregateType.Average, "AggregateFunction_Average")]
+    [InlineData(HistoryAggregateType.Minimum, "AggregateFunction_Minimum")]
+    [InlineData(HistoryAggregateType.Maximum, "AggregateFunction_Maximum")]
+    [InlineData(HistoryAggregateType.Total,   "AggregateFunction_Total")]
+    [InlineData(HistoryAggregateType.Count,   "AggregateFunction_Count")]
+    public void MapAggregateToNodeId_original_five_aggregates_stay_pinned_to_their_SDK_NodeIds(
+        HistoryAggregateType aggregate, string expectedSdkFieldName)
+    {
+        var nodeId = OpcUaClientDriver.MapAggregateToNodeId(aggregate);
+        var expected = GetSdkAggregateNodeId(expectedSdkFieldName);
+
+        nodeId.ShouldBe(expected);
+    }
+
+    /// <summary>
+    ///     The new Part 13 aggregates added in PR-13 each resolve to the SDK constant whose
+    ///     name matches the enum value. Guards against a transposition bug on any of the 25
+    ///     new arms.
+    /// </summary>
+    [Theory]
+    [InlineData(HistoryAggregateType.TimeAverage,                  "AggregateFunction_TimeAverage")]
+    [InlineData(HistoryAggregateType.TimeAverage2,                 "AggregateFunction_TimeAverage2")]
+    [InlineData(HistoryAggregateType.Interpolative,                "AggregateFunction_Interpolative")]
+    [InlineData(HistoryAggregateType.MinimumActualTime,            "AggregateFunction_MinimumActualTime")]
+    [InlineData(HistoryAggregateType.MaximumActualTime,            "AggregateFunction_MaximumActualTime")]
+    [InlineData(HistoryAggregateType.Range,                        "AggregateFunction_Range")]
+    [InlineData(HistoryAggregateType.Range2,                       "AggregateFunction_Range2")]
+    [InlineData(HistoryAggregateType.AnnotationCount,              "AggregateFunction_AnnotationCount")]
+    [InlineData(HistoryAggregateType.DurationGood,                 "AggregateFunction_DurationGood")]
+    [InlineData(HistoryAggregateType.DurationBad,                  "AggregateFunction_DurationBad")]
+    [InlineData(HistoryAggregateType.PercentGood,                  "AggregateFunction_PercentGood")]
+    [InlineData(HistoryAggregateType.PercentBad,                   "AggregateFunction_PercentBad")]
+    [InlineData(HistoryAggregateType.WorstQuality,                 "AggregateFunction_WorstQuality")]
+    [InlineData(HistoryAggregateType.WorstQuality2,                "AggregateFunction_WorstQuality2")]
+    [InlineData(HistoryAggregateType.StandardDeviationSample,      "AggregateFunction_StandardDeviationSample")]
+    [InlineData(HistoryAggregateType.StandardDeviationPopulation,  "AggregateFunction_StandardDeviationPopulation")]
+    [InlineData(HistoryAggregateType.VarianceSample,               "AggregateFunction_VarianceSample")]
+    [InlineData(HistoryAggregateType.VariancePopulation,           "AggregateFunction_VariancePopulation")]
+    [InlineData(HistoryAggregateType.NumberOfTransitions,          "AggregateFunction_NumberOfTransitions")]
+    [InlineData(HistoryAggregateType.DurationInStateZero,          "AggregateFunction_DurationInStateZero")]
+    [InlineData(HistoryAggregateType.DurationInStateNonZero,       "AggregateFunction_DurationInStateNonZero")]
+    [InlineData(HistoryAggregateType.Start,                        "AggregateFunction_Start")]
+    [InlineData(HistoryAggregateType.End,                          "AggregateFunction_End")]
+    [InlineData(HistoryAggregateType.Delta,                        "AggregateFunction_Delta")]
+    [InlineData(HistoryAggregateType.StartBound,                   "AggregateFunction_StartBound")]
+    [InlineData(HistoryAggregateType.EndBound,                     "AggregateFunction_EndBound")]
+    public void MapAggregateToNodeId_new_Part13_aggregates_resolve_to_matching_SDK_NodeIds(
+        HistoryAggregateType aggregate, string expectedSdkFieldName)
+    {
+        var nodeId = OpcUaClientDriver.MapAggregateToNodeId(aggregate);
+        var expected = GetSdkAggregateNodeId(expectedSdkFieldName);
+
+        nodeId.ShouldBe(expected);
+    }
+
+    /// <summary>
+    ///     Out-of-range enum values trip the default arm with
+    ///     <see cref="ArgumentOutOfRangeException"/>. <c>int.MaxValue</c> is a future-proof
+    ///     sentinel that is guaranteed never to collide with a real enum ordinal.
+    /// </summary>
+    [Fact]
+    public void MapAggregateToNodeId_rejects_out_of_range_enum_value()
+    {
+        Should.Throw<ArgumentOutOfRangeException>(() =>
+            OpcUaClientDriver.MapAggregateToNodeId((HistoryAggregateType)int.MaxValue));
+    }
+
+    /// <summary>
+    ///     The enum sweep is the source of truth — every value declared in
+    ///     <see cref="HistoryAggregateType"/> participates in
+    ///     <see cref="MapAggregateToNodeId_resolves_every_enum_value_to_a_namespace0_NodeId"/>.
+    ///     Adding a new enum value automatically adds a new test row.
+    /// </summary>
+    public static TheoryData<HistoryAggregateType> AllHistoryAggregateTypes()
+    {
+        var data = new TheoryData<HistoryAggregateType>();
+        foreach (var v in Enum.GetValues<HistoryAggregateType>())
+        {
+            data.Add(v);
+        }
+        return data;
+    }
+
+    /// <summary>
+    ///     Reflect the requested static field off <see cref="ObjectIds"/>. Used so the test
+    ///     table stays declarative — adding a new aggregate is one [InlineData] row plus an
+    ///     enum value, with no SDK-version-specific casting.
+    /// </summary>
+    private static NodeId GetSdkAggregateNodeId(string fieldName)
+    {
+        var field = typeof(ObjectIds).GetField(fieldName)
+            ?? throw new InvalidOperationException(
+                $"OPC UA SDK does not expose ObjectIds.{fieldName}. " +
+                "If the SDK was upgraded and the field was renamed, update the mapping table.");
+        var value = field.GetValue(null);
+        return (NodeId)value!;
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/OpcUaClientHistoryEventsTests.cs

@@ -0,0 +1,165 @@
+using Opc.Ua;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests;
+
+/// <summary>
+///     Unit tests for the filter-aware
+///     <see cref="OpcUaClientDriver.ReadEventsAsync(string, EventHistoryRequest, System.Threading.CancellationToken)"/>
+///     overload (PR-12 / #284). The driver-level wire path needs a live <see cref="ISession"/>
+///     so the round-trip-through-Session.HistoryReadAsync test lands as an integration test;
+///     here we cover the surface that's reachable without a session: SelectClause translation,
+///     default-clause fallback, and the EventFilter projection helper.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class OpcUaClientHistoryEventsTests
+{
+    [Fact]
+    public void DefaultEventSelectClauses_carries_the_standard_BaseEventType_columns()
+    {
+        // The fallback set must match BuildHistoryEvent on the server side so a client that
+        // doesn't customize the EventFilter still sees recognizable BaseEventType columns
+        // (EventId, SourceName, Time, Message, Severity, ReceiveTime).
+        var defaults = OpcUaClientDriver.DefaultEventSelectClauses;
+        defaults.Count.ShouldBe(6);
+        defaults.Select(d => d.FieldName).ShouldBe(
+            ["EventId", "SourceName", "Time", "Message", "Severity", "ReceiveTime"]);
+        // None of the defaults reach into a typed path — they're all rooted at BaseEventType
+        // (TypeDefinitionId=null sentinel).
+        defaults.All(d => d.TypeDefinitionId is null).ShouldBeTrue();
+        defaults.All(d => d.BrowsePath.Count == 1).ShouldBeTrue();
+    }
+
+    [Fact]
+    public void ToOpcEventFilter_translates_each_SimpleAttributeSpec_to_a_SimpleAttributeOperand()
+    {
+        var clauses = new List<SimpleAttributeSpec>
+        {
+            new(null, ["EventId"], "EventId"),
+            new(null, ["Severity"], "Severity"),
+            new("i=2782" /* ConditionType */, [], "ConditionId"),
+        };
+
+        var filter = OpcUaClientDriver.ToOpcEventFilter(clauses, whereClause: null);
+
+        filter.SelectClauses.Count.ShouldBe(3);
+
+        filter.SelectClauses[0].TypeDefinitionId.ShouldBe(ObjectTypeIds.BaseEventType);
+        filter.SelectClauses[0].BrowsePath.Count.ShouldBe(1);
+        filter.SelectClauses[0].BrowsePath[0].Name.ShouldBe("EventId");
+        filter.SelectClauses[0].AttributeId.ShouldBe(Attributes.Value);
+
+        filter.SelectClauses[1].BrowsePath[0].Name.ShouldBe("Severity");
+
+        // Typed-path entry: TypeDefinitionId parses to the supplied NodeId text and
+        // BrowsePath stays empty (= "the typed node itself").
+        filter.SelectClauses[2].TypeDefinitionId.ShouldBe(NodeId.Parse("i=2782"));
+        filter.SelectClauses[2].BrowsePath.Count.ShouldBe(0);
+    }
+
+    [Fact]
+    public void ToOpcEventFilter_with_null_where_clause_leaves_WhereClause_empty()
+    {
+        // Empty WhereClause is the OPC UA equivalent of "no filter" — every event matches.
+        // The client driver only attaches a WhereClause when one was decoded successfully;
+        // a null/empty ContentFilterSpec should never produce an Elements collection.
+        var clauses = new List<SimpleAttributeSpec>
+        {
+            new(null, ["EventId"], "EventId"),
+        };
+
+        var filter = OpcUaClientDriver.ToOpcEventFilter(clauses, whereClause: null);
+
+        filter.WhereClause.ShouldNotBeNull();
+        filter.WhereClause.Elements.Count.ShouldBe(0);
+    }
+
+    [Fact]
+    public void ToOpcEventFilter_with_malformed_where_clause_bytes_swallows_and_yields_empty_filter()
+    {
+        // Defense-in-depth: a corrupt encoded filter must not throw out of the helper.
+        // The driver chooses to drop the where-clause silently rather than fail the whole
+        // HistoryReadEvents call (best-effort projection per IHistoryProvider contract).
+        var clauses = new List<SimpleAttributeSpec>
+        {
+            new(null, ["EventId"], "EventId"),
+        };
+        var bogus = new ContentFilterSpec([0xFF, 0xFE, 0xFD]);
+
+        // Provide a real MessageContext so the BinaryDecoder path is exercised; without it
+        // the helper never attempts to decode and the test wouldn't cover the catch branch.
+#pragma warning disable CS0618 // ServiceMessageContext() — telemetry-context overload is irrelevant for unit decode.
+        var ctx = new ServiceMessageContext();
+#pragma warning restore CS0618
+        var filter = OpcUaClientDriver.ToOpcEventFilter(clauses, bogus, ctx);
+
+        filter.SelectClauses.Count.ShouldBe(1);
+        // Either the decoder produced a default ContentFilter (Elements=0) or the catch
+        // branch left the wire-default in place — either way no exception escaped.
+        filter.WhereClause.ShouldNotBeNull();
+    }
+
+    [Fact]
+    public async Task ReadEventsAsync_filter_overload_without_initialize_throws_InvalidOperationException()
+    {
+        // Same uninitialized-driver guard the rest of the IHistoryProvider methods use.
+        // Confirms the new overload is wired through RequireSession() rather than silently
+        // returning an empty batch on a never-connected driver (which would mask wiring bugs).
+        using var drv = new OpcUaClientDriver(new OpcUaClientDriverOptions(), "opcua-evt-uninit");
+        var request = new EventHistoryRequest(
+            StartTime: DateTime.UtcNow.AddMinutes(-5),
+            EndTime: DateTime.UtcNow,
+            NumValuesPerNode: 100,
+            SelectClauses: null,
+            WhereClause: null);
+        await Should.ThrowAsync<InvalidOperationException>(async () =>
+            await drv.ReadEventsAsync(
+                fullReference: "ns=2;s=AlarmsNotifier",
+                request: request,
+                cancellationToken: TestContext.Current.CancellationToken));
+    }
+
+    [Fact]
+    public async Task ReadEventsAsync_filter_overload_rejects_null_request()
+    {
+        using var drv = new OpcUaClientDriver(new OpcUaClientDriverOptions(), "opcua-evt-null");
+        await Should.ThrowAsync<ArgumentNullException>(async () =>
+            await drv.ReadEventsAsync(
+                fullReference: "ns=2;s=AlarmsNotifier",
+                request: null!,
+                cancellationToken: TestContext.Current.CancellationToken));
+    }
+
+    [Fact]
+    public async Task IHistoryProvider_filter_aware_default_throws_NotSupportedException_for_other_drivers()
+    {
+        // Other drivers that haven't opted in to the filter-aware overload must still see
+        // the IHistoryProvider default — same shape as the parameterless overload's default.
+        // We use a no-op stub to exercise the interface default's path.
+        IHistoryProvider stub = new NotImplementedHistoryStub();
+        var request = new EventHistoryRequest(
+            StartTime: DateTime.UtcNow.AddMinutes(-5),
+            EndTime: DateTime.UtcNow,
+            NumValuesPerNode: 100,
+            SelectClauses: null,
+            WhereClause: null);
+        await Should.ThrowAsync<NotSupportedException>(async () =>
+            await stub.ReadEventsAsync(
+                fullReference: "ns=2;s=AlarmsNotifier",
+                request: request,
+                cancellationToken: TestContext.Current.CancellationToken));
+    }
+
+    private sealed class NotImplementedHistoryStub : IHistoryProvider
+    {
+        public Task<Core.Abstractions.HistoryReadResult> ReadRawAsync(string fullReference, DateTime startUtc, DateTime endUtc,
+            uint maxValuesPerNode, CancellationToken cancellationToken)
+            => throw new NotImplementedException();
+
+        public Task<Core.Abstractions.HistoryReadResult> ReadProcessedAsync(string fullReference, DateTime startUtc, DateTime endUtc,
+            TimeSpan interval, HistoryAggregateType aggregate, CancellationToken cancellationToken)
+            => throw new NotImplementedException();
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/OpcUaClientRedundancyTests.cs

@@ -0,0 +1,278 @@
+using System.Text.Json;
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests;
+
+/// <summary>
+///     Unit tests for upstream-redundancy failover (PR-14, issue #286). The driver
+///     exposes two test seams — <see cref="OpcUaClientDriver.InjectServiceLevelDropForTest"/>
+///     and <see cref="OpcUaClientDriver.RedundancyFailoverHookForTest"/> — that bypass
+///     the SDK's session-create + TransferSubscriptions machinery so we can assert the
+///     decision logic without standing up two real OPC UA sessions.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class OpcUaClientRedundancyTests
+{
+    [Fact]
+    public void Redundancy_options_default_to_disabled()
+    {
+        var opts = new OpcUaClientDriverOptions();
+        opts.Redundancy.ShouldNotBeNull();
+        opts.Redundancy.Enabled.ShouldBeFalse(
+            "default deployments do client-side failover via EndpointUrls; upstream redundancy is opt-in");
+        opts.Redundancy.ServiceLevelThreshold.ShouldBe((ushort)200,
+            "OPC UA spec convention: 200+ = healthy, lower = degraded");
+        opts.Redundancy.ResolvedRecheckInterval.ShouldBe(TimeSpan.FromSeconds(5));
+    }
+
+    [Fact]
+    public void DTO_json_round_trip_preserves_redundancy_settings()
+    {
+        var opts = new OpcUaClientDriverOptions
+        {
+            EndpointUrl = "opc.tcp://primary:4840",
+            Redundancy = new RedundancyOptions(
+                Enabled: true,
+                ServiceLevelThreshold: 150,
+                RecheckInterval: TimeSpan.FromSeconds(10)),
+        };
+
+        var json = JsonSerializer.Serialize(opts);
+        var roundTripped = JsonSerializer.Deserialize<OpcUaClientDriverOptions>(json);
+
+        roundTripped.ShouldNotBeNull();
+        roundTripped!.Redundancy.Enabled.ShouldBeTrue();
+        roundTripped.Redundancy.ServiceLevelThreshold.ShouldBe((ushort)150);
+        roundTripped.Redundancy.ResolvedRecheckInterval.ShouldBe(TimeSpan.FromSeconds(10));
+    }
+
+    [Fact]
+    public void Disabled_redundancy_does_not_failover_on_low_servicelevel()
+    {
+        // Even a value of 0 (unrecoverable per the spec) should be a no-op when the
+        // feature is disabled — the driver shouldn't be reading ServerArray or watching
+        // ServiceLevel at all in that mode.
+        var opts = new OpcUaClientDriverOptions
+        {
+            EndpointUrl = "opc.tcp://primary:4840",
+            Redundancy = new RedundancyOptions(Enabled: false),
+        };
+        using var drv = new OpcUaClientDriver(opts, "opcua-redundancy-disabled");
+        var hookFired = false;
+        drv.RedundancyFailoverHookForTest = (_, _) => { hookFired = true; return Task.FromResult(true); };
+
+        drv.InjectServiceLevelDropForTest(0);
+
+        hookFired.ShouldBeFalse(
+            "Redundancy.Enabled=false means ServiceLevel drops must not trigger failover");
+        drv.RedundancyFailoverInvocationsForTest.ShouldBe(0);
+    }
+
+    [Fact]
+    public void ServiceLevel_above_threshold_does_not_trigger_failover()
+    {
+        var opts = new OpcUaClientDriverOptions
+        {
+            EndpointUrl = "opc.tcp://primary:4840",
+            Redundancy = new RedundancyOptions(Enabled: true, ServiceLevelThreshold: 200),
+        };
+        using var drv = new OpcUaClientDriver(opts, "opcua-redundancy-healthy");
+        SeedPeers(drv, "opc.tcp://secondary:4840");
+        var hookFired = false;
+        drv.RedundancyFailoverHookForTest = (_, _) => { hookFired = true; return Task.FromResult(true); };
+
+        // Equal to threshold = healthy boundary; spec semantics treat 200 as healthy.
+        drv.InjectServiceLevelDropForTest(200);
+        // Just above threshold = healthy.
+        drv.InjectServiceLevelDropForTest(220);
+
+        hookFired.ShouldBeFalse(
+            "ServiceLevel >= threshold must not trigger failover — healthy primary stays put");
+    }
+
+    [Fact]
+    public void ServiceLevel_below_threshold_triggers_failover_with_secondary_uri()
+    {
+        var opts = new OpcUaClientDriverOptions
+        {
+            EndpointUrl = "opc.tcp://primary:4840",
+            Redundancy = new RedundancyOptions(Enabled: true, ServiceLevelThreshold: 200),
+        };
+        using var drv = new OpcUaClientDriver(opts, "opcua-redundancy-failover");
+        SeedPeers(drv, "opc.tcp://primary:4840", "opc.tcp://secondary:4840");
+        SeedActive(drv, "opc.tcp://primary:4840");
+
+        string? failoverTarget = null;
+        drv.RedundancyFailoverHookForTest = (uri, _) =>
+        {
+            failoverTarget = uri;
+            return Task.FromResult(true);
+        };
+
+        drv.InjectServiceLevelDropForTest(50);
+
+        // Wait for the fire-and-forget Task to complete. The driver dispatches FailoverAsync
+        // via discard — give it a beat to land.
+        Wait(() => failoverTarget is not null);
+
+        failoverTarget.ShouldBe("opc.tcp://secondary:4840",
+            "the failover path picks the next URI in ServerArray that isn't the active one");
+        var diags1 = drv.GetHealth().Diagnostics;
+        diags1.ShouldNotBeNull();
+        diags1!.ShouldContainKey("RedundancyFailoverCount");
+        diags1["RedundancyFailoverCount"].ShouldBe(1);
+    }
+
+    [Fact]
+    public void Empty_peer_list_does_not_trigger_failover()
+    {
+        // Upstream with RedundancySupport=None (or one that simply doesn't expose the
+        // ServerUriArray node) leaves _redundancyPeers empty. ServiceLevel drops in that
+        // mode are diagnostic-only — the driver has no peer to swap to.
+        var opts = new OpcUaClientDriverOptions
+        {
+            EndpointUrl = "opc.tcp://primary:4840",
+            Redundancy = new RedundancyOptions(Enabled: true),
+        };
+        using var drv = new OpcUaClientDriver(opts, "opcua-redundancy-no-peers");
+        var hookFired = false;
+        drv.RedundancyFailoverHookForTest = (_, _) => { hookFired = true; return Task.FromResult(true); };
+
+        drv.InjectServiceLevelDropForTest(50);
+
+        hookFired.ShouldBeFalse(
+            "ServerArray empty means there's nowhere to fail over to — drop is informational only");
+    }
+
+    [Fact]
+    public void Failover_with_only_active_uri_in_peer_list_does_not_swap_to_self()
+    {
+        // Edge case: the upstream advertises itself in ServerUriArray but no actual peers.
+        // The driver must not try to fail over to the URI it's already on.
+        var opts = new OpcUaClientDriverOptions
+        {
+            EndpointUrl = "opc.tcp://primary:4840",
+            Redundancy = new RedundancyOptions(Enabled: true),
+        };
+        using var drv = new OpcUaClientDriver(opts, "opcua-redundancy-self-only");
+        SeedPeers(drv, "opc.tcp://primary:4840");
+        SeedActive(drv, "opc.tcp://primary:4840");
+        var hookFired = false;
+        drv.RedundancyFailoverHookForTest = (_, _) => { hookFired = true; return Task.FromResult(true); };
+
+        drv.InjectServiceLevelDropForTest(50);
+
+        hookFired.ShouldBeFalse(
+            "the only peer in the list is the active URI itself — there's nothing to swap to");
+    }
+
+    [Fact]
+    public void Failover_failure_increments_failures_counter_and_keeps_session()
+    {
+        var opts = new OpcUaClientDriverOptions
+        {
+            EndpointUrl = "opc.tcp://primary:4840",
+            Redundancy = new RedundancyOptions(Enabled: true),
+        };
+        using var drv = new OpcUaClientDriver(opts, "opcua-redundancy-failure");
+        SeedPeers(drv, "opc.tcp://primary:4840", "opc.tcp://secondary:4840");
+        SeedActive(drv, "opc.tcp://primary:4840");
+
+        drv.RedundancyFailoverHookForTest = (_, _) => Task.FromResult(false);
+
+        drv.InjectServiceLevelDropForTest(50);
+
+        Wait(() => drv.GetHealth().Diagnostics is { } d
+            && d.TryGetValue("RedundancyFailoverFailures", out var f) && f >= 1);
+
+        var diags = drv.GetHealth().Diagnostics;
+        diags.ShouldNotBeNull();
+        diags!.ShouldContainKey("RedundancyFailoverFailures");
+        diags["RedundancyFailoverFailures"].ShouldBe(1);
+        diags["RedundancyFailoverCount"].ShouldBe(0,
+            "a failed swap must not bump the success counter");
+    }
+
+    [Fact]
+    public void Repeated_drops_within_recheck_interval_only_failover_once()
+    {
+        var opts = new OpcUaClientDriverOptions
+        {
+            EndpointUrl = "opc.tcp://primary:4840",
+            Redundancy = new RedundancyOptions(
+                Enabled: true,
+                ServiceLevelThreshold: 200,
+                RecheckInterval: TimeSpan.FromMinutes(5)),
+        };
+        using var drv = new OpcUaClientDriver(opts, "opcua-redundancy-debounce");
+        SeedPeers(drv, "opc.tcp://primary:4840", "opc.tcp://secondary:4840");
+        SeedActive(drv, "opc.tcp://primary:4840");
+
+        var calls = 0;
+        drv.RedundancyFailoverHookForTest = (_, _) =>
+        {
+            Interlocked.Increment(ref calls);
+            return Task.FromResult(true);
+        };
+
+        drv.InjectServiceLevelDropForTest(50);
+        Wait(() => calls >= 1);
+        drv.InjectServiceLevelDropForTest(50);
+        drv.InjectServiceLevelDropForTest(40);
+
+        // RecheckInterval = 5 minutes — the second + third drops should be suppressed
+        // because the first failover landed inside the window.
+        calls.ShouldBe(1,
+            "RecheckInterval suppresses oscillation around the threshold so a flapping primary doesn't ping-pong");
+    }
+
+    [Fact]
+    public void Diagnostics_exposes_redundancy_counters_in_snapshot()
+    {
+        // The `driver-diagnostics` RPC reads through GetHealth(); operators expect the
+        // redundancy counters in the snapshot regardless of whether failover ever fired.
+        var opts = new OpcUaClientDriverOptions
+        {
+            EndpointUrl = "opc.tcp://primary:4840",
+            Redundancy = new RedundancyOptions(Enabled: true),
+        };
+        using var drv = new OpcUaClientDriver(opts, "opcua-redundancy-diag");
+
+        var d = drv.GetHealth().Diagnostics;
+        d.ShouldNotBeNull();
+        d!.ShouldContainKey("RedundancyFailoverCount");
+        d.ShouldContainKey("RedundancyFailoverFailures");
+        d["RedundancyFailoverCount"].ShouldBe(0);
+        d["RedundancyFailoverFailures"].ShouldBe(0);
+    }
+
+    // ---- helpers ----
+
+    private static void SeedPeers(OpcUaClientDriver drv, params string[] peers)
+    {
+        // The driver normally populates _redundancyPeers from a session ReadValue call.
+        // For unit testing we use reflection to seed the field directly — the alternative
+        // (mocking ISession) brings most of the OPC UA SDK into the test surface.
+        var field = typeof(OpcUaClientDriver).GetField(
+            "_redundancyPeers",
+            System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance)!;
+        field.SetValue(drv, (IReadOnlyList<string>)peers);
+    }
+
+    private static void SeedActive(OpcUaClientDriver drv, string uri)
+    {
+        var diag = drv.DiagnosticsForTest;
+        diag.SetActiveServerUri(uri);
+    }
+
+    private static void Wait(Func<bool> predicate, int timeoutMs = 2000)
+    {
+        var deadline = DateTime.UtcNow.AddMilliseconds(timeoutMs);
+        while (DateTime.UtcNow < deadline)
+        {
+            if (predicate()) return;
+            Thread.Sleep(10);
+        }
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/S7_1500/S7_1500SzlTests.cs

@@ -0,0 +1,139 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Driver.S7.Szl;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests.S7_1500;
+
+/// <summary>
+///     PR-S7-E1 / #302 — integration scaffold for SZL (System Status List) reads against
+///     a real S7-1500 CPU. snap7 (the simulator that backs <see cref="Snap7ServerFixture"/>)
+///     does not implement SZL — every <c>@System.*</c> read returns <c>BadNotSupported</c>
+///     against the simulator — so the asserts here verify the not-supported semantics
+///     when running against snap7, and the live-firmware tests are gated on a real-PLC
+///     env-var (<c>S7_LIVE_HOST</c>) the same way other PR-S7-* live tests are.
+/// </summary>
+/// <remarks>
+///     <para>
+///         <b>Why scaffolding rather than full live verification?</b> The plan section
+///         calls for a "live-firmware test against dev-box S7-1500"; that's a hardware-
+///         gated test and it is parked behind an env-var so the CI pipeline + a fresh
+///         developer checkout both stay green. The not-supported assertion against snap7
+///         is the "always-runs" piece — proves the dispatch path lights up + surfaces
+///         the right StatusCode without a live CPU.
+///     </para>
+/// </remarks>
+[Collection(Snap7ServerCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Device", "S7_1500")]
+public sealed class S7_1500SzlTests(Snap7ServerFixture sim)
+{
+    /// <summary>OPC UA <c>BadNotSupported</c> status code — same constant the driver uses.</summary>
+    private const uint StatusBadNotSupported = 0x803D0000u;
+
+    /// <summary>
+    ///     Re-build the simulator profile with <c>ExposeSystemTags = true</c>. <see cref="S7DriverOptions"/>
+    ///     is a class (not a record), so we copy fields manually rather than using a <c>with</c> expression.
+    /// </summary>
+    private static S7DriverOptions BuildOptionsWithSystemTags(string host, int port, int diagBufferDepth = 10)
+    {
+        var baseOpts = S7_1500Profile.BuildOptions(host, port);
+        return new S7DriverOptions
+        {
+            Host = baseOpts.Host,
+            Port = baseOpts.Port,
+            CpuType = baseOpts.CpuType,
+            Rack = baseOpts.Rack,
+            Slot = baseOpts.Slot,
+            Timeout = baseOpts.Timeout,
+            Probe = baseOpts.Probe,
+            Tags = baseOpts.Tags,
+            ExposeSystemTags = true,
+            DiagBufferDepth = diagBufferDepth,
+        };
+    }
+
+    [Fact]
+    public async Task System_CpuType_returns_BadNotSupported_against_snap7_simulator()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+
+        var options = BuildOptionsWithSystemTags(sim.Host, sim.Port);
+        await using var drv = new S7Driver(options, driverInstanceId: "s7-szl-cputype");
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var snaps = await drv.ReadAsync(["@System.CpuType"], TestContext.Current.CancellationToken);
+        snaps.Count.ShouldBe(1);
+        // snap7 doesn't implement SZL; the production S7NetSzlReader returns null too
+        // (S7netplus 0.20 has no public ReadSzlAsync surface). Both paths converge on
+        // BadNotSupported.
+        snaps[0].StatusCode.ShouldBe(StatusBadNotSupported);
+    }
+
+    [Fact]
+    public async Task DiscoverAsync_emits_diagnostics_folder_against_real_simulator_when_opted_in()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+
+        var options = BuildOptionsWithSystemTags(sim.Host, sim.Port, diagBufferDepth: 5);
+        await using var drv = new S7Driver(options, driverInstanceId: "s7-szl-discover");
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var builder = new TestAddressSpaceBuilder();
+        await drv.DiscoverAsync(builder, TestContext.Current.CancellationToken);
+
+        builder.Folders.ShouldContain(S7SystemTags.FolderName);
+        builder.Folders.ShouldContain("DiagBuffer");
+        // 6 scalars + 5 buffer entries = 11 system variables.
+        builder.Variables
+            .Count(v => v.FullName.StartsWith(S7SystemTags.Prefix, StringComparison.Ordinal))
+            .ShouldBe(11);
+    }
+
+    /// <summary>
+    ///     Live-firmware gate: when the env-var <c>S7_LIVE_HOST</c> points at a real
+    ///     S7-1500, this test runs end-to-end against the live CPU and expects a
+    ///     non-empty CpuType / Firmware / OrderNo. Hardware-gated; CI skips it.
+    ///     Currently parked at <see cref="Assert.Skip"/> because S7netplus 0.20 doesn't
+    ///     expose a public SZL surface — even against a real CPU the production
+    ///     <see cref="S7NetSzlReader"/> returns null. Flip this back on once the
+    ///     S7netplus PR for ReadSzlAsync lands or we ship a raw-PDU helper.
+    /// </summary>
+    [Fact(Skip = "Requires real S7-1500 + S7netplus public ReadSzlAsync surface; see PR-S7-E1 docs.")]
+    public Task System_CpuType_against_live_S7_1500_returns_non_empty_string()
+    {
+        // var liveHost = Environment.GetEnvironmentVariable("S7_LIVE_HOST");
+        // if (string.IsNullOrWhiteSpace(liveHost))
+        //     Assert.Skip("S7_LIVE_HOST not set — skipping live-firmware SZL test");
+        // var options = new S7DriverOptions { Host = liveHost, ExposeSystemTags = true, ... };
+        // ...
+        return Task.CompletedTask;
+    }
+
+    private sealed class TestAddressSpaceBuilder : Core.Abstractions.IAddressSpaceBuilder
+    {
+        public List<string> Folders { get; } = [];
+        public List<Core.Abstractions.DriverAttributeInfo> Variables { get; } = [];
+
+        public Core.Abstractions.IAddressSpaceBuilder Folder(string browseName, string displayName)
+        {
+            Folders.Add(browseName);
+            return this;
+        }
+
+        public Core.Abstractions.IVariableHandle Variable(
+            string browseName, string displayName, Core.Abstractions.DriverAttributeInfo info)
+        {
+            Variables.Add(info);
+            return new StubHandle();
+        }
+
+        public void AddProperty(string browseName, Core.Abstractions.DriverDataType dataType, object? value) { }
+
+        private sealed class StubHandle : Core.Abstractions.IVariableHandle
+        {
+            public string FullReference => "stub";
+            public Core.Abstractions.IAlarmConditionSink MarkAsAlarmCondition(Core.Abstractions.AlarmConditionInfo info)
+                => throw new NotImplementedException();
+        }
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.S7.Tests/S7PasswordOptionsTests.cs

@@ -0,0 +1,344 @@
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.S7.Tests;
+
+/// <summary>
+///     PR-S7-E2 / #303 — connection-level password + protection-level options-binding
+///     tests. Verifies the no-log invariant on <see cref="S7DriverOptions.ToString"/>,
+///     DTO round-trip on the JSON wire form, and the
+///     <see cref="IS7PlcAuthGate"/> dispatch contract that <see cref="S7Driver"/>
+///     uses to send the password right after <c>OpenAsync</c>. The live wire path
+///     (S7-1500 with a real protection password) is hardware-gated and exercised in
+///     a separate fixture.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class S7PasswordOptionsTests
+{
+    // ---- Defaults ----
+
+    [Fact]
+    public void Default_Password_is_null_and_ProtectionLevel_is_Auto()
+    {
+        var opts = new S7DriverOptions();
+        opts.Password.ShouldBeNull();
+        opts.ProtectionLevel.ShouldBe(ProtectionLevel.Auto);
+    }
+
+    // ---- ToString redaction (no-log invariant) ----
+
+    [Fact]
+    public void ToString_redacts_Password_when_set()
+    {
+        var opts = new S7DriverOptions
+        {
+            Host = "192.168.1.30",
+            Password = "super-secret-123",
+            ProtectionLevel = ProtectionLevel.Level3,
+        };
+        var s = opts.ToString();
+        s.ShouldNotContain("super-secret-123");
+        s.ShouldContain("***");
+        s.ShouldContain("Level3");
+        s.ShouldContain("192.168.1.30");
+    }
+
+    [Fact]
+    public void ToString_emits_null_marker_when_Password_is_unset()
+    {
+        var opts = new S7DriverOptions { Host = "192.168.1.30" };
+        var s = opts.ToString();
+        s.ShouldContain("Password = <null>");
+        s.ShouldNotContain("***");
+    }
+
+    // ---- DTO round-trip ----
+
+    [Fact]
+    public void DTO_round_trip_preserves_Password_and_ProtectionLevel()
+    {
+        var json = """
+        {
+            "Host": "192.168.1.30",
+            "CpuType": "S71500",
+            "Password": "p@ssw0rd",
+            "ProtectionLevel": "ConnectionMechanism",
+            "Tags": []
+        }
+        """;
+        var drv = (S7Driver)S7DriverFactoryExtensions.CreateInstance("s7-pwd-dto", json);
+        drv.ShouldNotBeNull();
+        drv.DriverInstanceId.ShouldBe("s7-pwd-dto");
+        drv.Dispose();
+    }
+
+    [Fact]
+    public void DTO_round_trip_serialise_then_deserialise_preserves_Password_field()
+    {
+        var dto = new S7DriverFactoryExtensions.S7DriverConfigDto
+        {
+            Host = "10.0.0.5",
+            Password = "rotational-secret",
+            ProtectionLevel = "Level2",
+        };
+        var json = JsonSerializer.Serialize(dto);
+        var back = JsonSerializer.Deserialize<S7DriverFactoryExtensions.S7DriverConfigDto>(json)!;
+        back.Password.ShouldBe("rotational-secret");
+        back.ProtectionLevel.ShouldBe("Level2");
+    }
+
+    [Fact]
+    public void DTO_explicit_empty_Password_collapses_to_null()
+    {
+        // A typo'd "" Password must NOT try to send an empty password to the PLC.
+        var json = """
+        {
+            "Host": "192.168.1.30",
+            "Password": "",
+            "Tags": []
+        }
+        """;
+        // This goes through the factory -> options pipeline and would fail Init if the
+        // empty-string slipped through. The factory is supposed to coerce to null; we
+        // can't easily probe the bound options without InternalsVisibleTo to the test
+        // factory, but we CAN verify the driver constructs successfully and Init-time
+        // is the only place that would observe a non-null empty password.
+        var drv = S7DriverFactoryExtensions.CreateInstance("s7-empty-pwd", json);
+        drv.ShouldNotBeNull();
+        drv.Dispose();
+    }
+
+    [Fact]
+    public void DTO_unknown_ProtectionLevel_is_rejected()
+    {
+        var json = """
+        {
+            "Host": "192.168.1.30",
+            "ProtectionLevel": "MysteryMode",
+            "Tags": []
+        }
+        """;
+        Should.Throw<InvalidOperationException>(() =>
+            S7DriverFactoryExtensions.CreateInstance("s7-bad-level", json));
+    }
+
+    [Fact]
+    public void DTO_omitting_Password_and_ProtectionLevel_falls_back_to_defaults()
+    {
+        // Backwards compat: pre-PR-S7-E2 configs must keep loading.
+        var json = """
+        {
+            "Host": "192.168.1.30",
+            "Tags": []
+        }
+        """;
+        var drv = S7DriverFactoryExtensions.CreateInstance("s7-legacy", json);
+        drv.ShouldNotBeNull();
+        drv.Dispose();
+    }
+
+    // ---- Auth-gate dispatch contract ----
+
+    [Fact]
+    public async Task Password_null_does_not_call_auth_gate()
+    {
+        var fake = new FakeAuthGate();
+        var opts = new S7DriverOptions
+        {
+            Host = "192.0.2.1",
+            Timeout = TimeSpan.FromMilliseconds(200),
+            // Probe disabled so we don't need an open socket
+            Probe = new S7ProbeOptions { Enabled = false, ProbeAddress = null },
+        };
+        using var drv = new S7Driver(opts, "s7-no-pwd") { AuthGate = fake };
+
+        // 192.0.2.1 (RFC 5737 TEST-NET-1) is unroutable, so OpenAsync will fail first.
+        await Should.ThrowAsync<Exception>(async () =>
+            await drv.InitializeAsync("{}", TestContext.Current.CancellationToken));
+
+        // The point: even if Init failed at OpenAsync, the gate must NEVER have been
+        // invoked because Password was null.
+        fake.CallCount.ShouldBe(0);
+    }
+
+    [Fact]
+    public async Task Password_set_with_unsupported_gate_logs_warning_and_does_not_throw_at_password_step()
+    {
+        var fake = new FakeAuthGate { Supports = false };
+        var capturingLogger = new CapturingLogger<S7Driver>();
+        const string secret = "ZZZ-distinct-secret-not-in-log-messages-ZZZ";
+        var opts = new S7DriverOptions
+        {
+            Host = "192.0.2.1",
+            Timeout = TimeSpan.FromMilliseconds(200),
+            Password = secret,
+            Probe = new S7ProbeOptions { Enabled = false, ProbeAddress = null },
+        };
+
+        // Drive the password code path directly using internals — the unit test seam
+        // exposes Logger / AuthGate. We call the helper via reflection on the driver
+        // method to keep coverage tight without standing up a real PLC.
+        using var drv = new S7Driver(opts, "s7-pwd-no-support")
+        {
+            AuthGate = fake,
+            Logger = capturingLogger,
+        };
+
+        // 192.0.2.1 is unroutable, so InitializeAsync will fail at OpenAsync. The
+        // password step is *after* OpenAsync, so we won't actually reach it through
+        // InitializeAsync against a dead host. Instead drive the helper directly via
+        // its reflection seam.
+        var helper = typeof(S7Driver).GetMethod(
+            "TrySendPlcPasswordAsync",
+            System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic);
+        helper.ShouldNotBeNull();
+
+        // Production helper expects a live S7.Net.Plc; pass null since the gate
+        // override means we never dereference it. Method signature accepts Plc + ct.
+        var task = (Task)helper!.Invoke(drv, [null!, TestContext.Current.CancellationToken])!;
+        await task;
+
+        fake.CallCount.ShouldBe(0); // gate.SupportsSendPassword=false → no call
+        capturingLogger.Entries.ShouldContain(e =>
+            e.Level == LogLevel.Warning &&
+            e.Message.Contains("does not expose SendPassword"));
+        // No-log invariant — secret value never appears.
+        capturingLogger.Entries.ShouldNotContain(e => e.Message.Contains(secret));
+    }
+
+    [Fact]
+    public async Task Password_set_with_supported_gate_invokes_gate_and_logs_success()
+    {
+        var fake = new FakeAuthGate { Supports = true };
+        var capturingLogger = new CapturingLogger<S7Driver>();
+        var opts = new S7DriverOptions
+        {
+            Host = "192.0.2.1",
+            Password = "rotational-secret",
+            Probe = new S7ProbeOptions { Enabled = false, ProbeAddress = null },
+        };
+        using var drv = new S7Driver(opts, "s7-pwd-ok")
+        {
+            AuthGate = fake,
+            Logger = capturingLogger,
+        };
+
+        var helper = typeof(S7Driver).GetMethod(
+            "TrySendPlcPasswordAsync",
+            System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic);
+        var task = (Task)helper!.Invoke(drv, [null!, TestContext.Current.CancellationToken])!;
+        await task;
+
+        fake.CallCount.ShouldBe(1);
+        fake.LastPassword.ShouldBe("rotational-secret");
+        capturingLogger.Entries.ShouldContain(e =>
+            e.Level == LogLevel.Information &&
+            e.Message.Contains("S7 password sent"));
+        // No-log invariant.
+        capturingLogger.Entries.ShouldNotContain(e => e.Message.Contains("rotational-secret"));
+    }
+
+    [Fact]
+    public async Task Password_send_throwing_propagates_clean_InvalidOperationException()
+    {
+        var fake = new FakeAuthGate
+        {
+            Supports = true,
+            ThrowOnSend = new global::S7.Net.PlcException(global::S7.Net.ErrorCode.WrongCPU_Type),
+        };
+        var capturingLogger = new CapturingLogger<S7Driver>();
+        var opts = new S7DriverOptions
+        {
+            Host = "192.0.2.1",
+            Password = "wrong-pwd",
+            Probe = new S7ProbeOptions { Enabled = false, ProbeAddress = null },
+        };
+        using var drv = new S7Driver(opts, "s7-pwd-bad")
+        {
+            AuthGate = fake,
+            Logger = capturingLogger,
+        };
+
+        var helper = typeof(S7Driver).GetMethod(
+            "TrySendPlcPasswordAsync",
+            System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic);
+        // Direct invoke surfaces TargetInvocationException for synchronous throws; for
+        // an async helper the exception flows through the returned Task, so await it.
+        var task = (Task)helper!.Invoke(drv, [null!, TestContext.Current.CancellationToken])!;
+        var ex = await Should.ThrowAsync<InvalidOperationException>(async () => await task);
+        ex.Message.ShouldContain("password authentication failed");
+        // Inner exception preserved for diagnostics.
+        ex.InnerException.ShouldBeOfType<global::S7.Net.PlcException>();
+        // No-log invariant on the exception message itself.
+        ex.Message.ShouldNotContain("wrong-pwd");
+    }
+
+    // ---- Reflection probe sanity (production gate against current S7netplus 0.20) ----
+
+    [Fact]
+    public void Reflection_gate_against_S7netplus_0_20_reports_unsupported()
+    {
+        // PR-S7-E2 documented limitation: S7netplus 0.20 does not expose SendPassword.
+        // The reflective probe must report SupportsSendPassword=false on a real Plc
+        // instance built against the pinned package. This test pins the limitation —
+        // when S7netplus ships SendPassword in a future minor release, the test breaks
+        // and signals the team to remove the warning path.
+        var plc = new global::S7.Net.Plc(global::S7.Net.CpuType.S71500, "127.0.0.1", 0, 0);
+        var gate = new ReflectionS7PlcAuthGate(plc);
+        gate.SupportsSendPassword.ShouldBeFalse(
+            "S7netplus 0.20 does not expose SendPassword. If this assertion fails, " +
+            "S7netplus has added the API — update docs/v2/s7.md \"PLC password / " +
+            "protection levels\" library-limitation note and remove the warning path.");
+    }
+
+    // ---- Test doubles ----
+
+    private sealed class FakeAuthGate : IS7PlcAuthGate
+    {
+        public bool Supports { get; init; } = true;
+        public bool SupportsSendPassword => Supports;
+
+        public Exception? ThrowOnSend { get; init; }
+        public int CallCount { get; private set; }
+        public string? LastPassword { get; private set; }
+
+        public Task<bool> TrySendPasswordAsync(string password, CancellationToken cancellationToken)
+        {
+            if (!Supports) return Task.FromResult(false);
+            CallCount++;
+            LastPassword = password;
+            if (ThrowOnSend is not null) throw ThrowOnSend;
+            return Task.FromResult(true);
+        }
+    }
+
+    private sealed record CapturedLogEntry(LogLevel Level, string Message);
+
+    private sealed class CapturingLogger<T> : ILogger<T>
+    {
+        public List<CapturedLogEntry> Entries { get; } = new();
+
+        IDisposable? ILogger.BeginScope<TState>(TState state) => NullScope.Instance;
+
+        public bool IsEnabled(LogLevel logLevel) => true;
+
+        public void Log<TState>(
+            LogLevel logLevel,
+            EventId eventId,
+            TState state,
+            Exception? exception,
+            Func<TState, Exception?, string> formatter)
+        {
+            Entries.Add(new CapturedLogEntry(logLevel, formatter(state, exception)));
+        }
+
+        private sealed class NullScope : IDisposable
+        {
+            public static readonly NullScope Instance = new();
+            public void Dispose() { }
+        }
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.S7.Tests/Szl/S7SystemTagsTests.cs

@@ -0,0 +1,260 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.S7.Szl;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.S7.Tests.Szl;
+
+/// <summary>
+///     PR-S7-E1 — driver-side wiring for SZL-backed <c>@System.*</c> virtual addresses.
+///     Tests run without a real PLC by injecting an <see cref="IS7SzlReader"/> fake and
+///     calling <see cref="S7Driver.ReadAsync"/> against <c>@System.*</c> references — the
+///     driver short-circuits those before <c>RequirePlc()</c> so the read path lights up
+///     without touching the wire.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class S7SystemTagsTests
+{
+    private sealed class FakeSzlReader(Func<ushort, ushort, byte[]?> respond) : IS7SzlReader
+    {
+        public int CallCount { get; private set; }
+        public List<(ushort SzlId, ushort SzlIndex)> Calls { get; } = new();
+
+        public Task<byte[]?> ReadSzlAsync(ushort szlId, ushort szlIndex, CancellationToken cancellationToken)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            CallCount++;
+            Calls.Add((szlId, szlIndex));
+            return Task.FromResult(respond(szlId, szlIndex));
+        }
+    }
+
+    private sealed class RecordingAddressSpaceBuilder : IAddressSpaceBuilder
+    {
+        public List<string> Folders { get; } = new();
+        public List<(string Browse, DriverAttributeInfo Info)> Variables { get; } = new();
+
+        public IAddressSpaceBuilder Folder(string browseName, string displayName)
+        {
+            Folders.Add(browseName);
+            return this;
+        }
+        public IVariableHandle Variable(string browseName, string displayName, DriverAttributeInfo attributeInfo)
+        {
+            Variables.Add((browseName, attributeInfo));
+            return new StubHandle();
+        }
+        public void AddProperty(string browseName, DriverDataType dataType, object? value) { }
+
+        private sealed class StubHandle : IVariableHandle
+        {
+            public string FullReference => "stub";
+            public IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo info) => throw new NotImplementedException();
+        }
+    }
+
+    [Fact]
+    public async Task DiscoverAsync_emits_no_diagnostics_folder_when_ExposeSystemTags_is_false()
+    {
+        var opts = new S7DriverOptions
+        {
+            Host = "192.0.2.1",
+            Tags = [new S7TagDefinition("Setpoint", "DB1.DBW0", S7DataType.Int16)],
+        };
+        using var drv = new S7Driver(opts, "s7-disco-no-system");
+        var builder = new RecordingAddressSpaceBuilder();
+        await drv.DiscoverAsync(builder, TestContext.Current.CancellationToken);
+
+        builder.Folders.ShouldNotContain(S7SystemTags.FolderName);
+        builder.Variables.Select(v => v.Info.FullName)
+            .ShouldNotContain(n => n.StartsWith(S7SystemTags.Prefix, StringComparison.Ordinal));
+    }
+
+    [Fact]
+    public async Task DiscoverAsync_emits_diagnostics_folder_with_six_scalars_and_ten_buffer_entries()
+    {
+        var opts = new S7DriverOptions
+        {
+            Host = "192.0.2.1",
+            ExposeSystemTags = true,
+            // Default DiagBufferDepth = 10 — six scalars + ten entries = 16 system variables.
+            Tags = [],
+        };
+        using var drv = new S7Driver(opts, "s7-disco-with-system");
+        var builder = new RecordingAddressSpaceBuilder();
+        await drv.DiscoverAsync(builder, TestContext.Current.CancellationToken);
+
+        builder.Folders.ShouldContain(S7SystemTags.FolderName);
+        builder.Folders.ShouldContain("DiagBuffer");
+
+        var systemVars = builder.Variables
+            .Where(v => v.Info.FullName.StartsWith(S7SystemTags.Prefix, StringComparison.Ordinal))
+            .ToList();
+        systemVars.Count.ShouldBe(16); // 6 scalars + 10 buffer entries
+
+        // CpuType / Firmware / OrderNo project as String; CycleMs.* as Float64.
+        systemVars.ShouldContain(v => v.Info.FullName == "@System.CpuType" && v.Info.DriverDataType == DriverDataType.String);
+        systemVars.ShouldContain(v => v.Info.FullName == "@System.CycleMs.Avg" && v.Info.DriverDataType == DriverDataType.Float64);
+
+        // Diagnostics tags are ViewOnly — never writable.
+        systemVars.ShouldAllBe(v => v.Info.SecurityClass == SecurityClassification.ViewOnly);
+    }
+
+    [Fact]
+    public async Task DiscoverAsync_honours_custom_DiagBufferDepth()
+    {
+        var opts = new S7DriverOptions
+        {
+            ExposeSystemTags = true,
+            DiagBufferDepth = 3,
+            Tags = [],
+        };
+        using var drv = new S7Driver(opts, "s7-disco-custom-depth");
+        var builder = new RecordingAddressSpaceBuilder();
+        await drv.DiscoverAsync(builder, TestContext.Current.CancellationToken);
+
+        var bufferEntries = builder.Variables
+            .Where(v => v.Info.FullName.StartsWith(S7SystemTags.DiagBufferEntryPrefix, StringComparison.Ordinal))
+            .ToList();
+        bufferEntries.Count.ShouldBe(3);
+        bufferEntries[0].Info.FullName.ShouldBe("@System.DiagBuffer.Entry[0]");
+        bufferEntries[2].Info.FullName.ShouldBe("@System.DiagBuffer.Entry[2]");
+    }
+
+    [Fact]
+    public async Task ReadAsync_returns_parsed_CpuType_via_injected_reader()
+    {
+        var info = new S7CpuInfo("CPU 1215C", "V4.5.0", "6ES7 215-1AG40-0XB0");
+        var reader = new FakeSzlReader((id, idx) =>
+            id == S7SzlIds.ModuleIdentification ? S7SzlParser.EncodeCpuInfo(info) : null);
+
+        var opts = new S7DriverOptions { ExposeSystemTags = true, Tags = [] };
+        using var drv = new S7Driver(opts, "s7-cputype") { SzlReader = reader };
+
+        var snaps = await drv.ReadAsync(["@System.CpuType"], TestContext.Current.CancellationToken);
+        snaps.Count.ShouldBe(1);
+        snaps[0].StatusCode.ShouldBe(0u);
+        snaps[0].Value.ShouldBe("CPU 1215C");
+        reader.CallCount.ShouldBe(1);
+    }
+
+    [Fact]
+    public async Task ReadAsync_returns_BadNotSupported_when_reader_returns_null()
+    {
+        var reader = new FakeSzlReader((_, _) => null); // snap7 / S7netplus 0.20 path
+        var opts = new S7DriverOptions { ExposeSystemTags = true, Tags = [] };
+        using var drv = new S7Driver(opts, "s7-not-supported") { SzlReader = reader };
+
+        var snaps = await drv.ReadAsync(["@System.CpuType", "@System.Firmware"], TestContext.Current.CancellationToken);
+        snaps.Count.ShouldBe(2);
+        snaps[0].StatusCode.ShouldBe(0x803D0000u, "BadNotSupported");
+        snaps[0].Value.ShouldBeNull();
+        snaps[1].StatusCode.ShouldBe(0x803D0000u);
+    }
+
+    [Fact]
+    public async Task ReadAsync_caches_SZL_payload_within_TTL()
+    {
+        var info = new S7CpuInfo("CPU 1516", "V2.9.4", "6ES7 516-3AN01-0AB0");
+        var reader = new FakeSzlReader((_, _) => S7SzlParser.EncodeCpuInfo(info));
+
+        var opts = new S7DriverOptions
+        {
+            ExposeSystemTags = true,
+            // 1-hour TTL so the second read inside the test definitely hits the cache.
+            SzlCacheTtl = TimeSpan.FromHours(1),
+            Tags = [],
+        };
+        using var drv = new S7Driver(opts, "s7-cache-hit") { SzlReader = reader };
+
+        var first = await drv.ReadAsync(["@System.CpuType"], TestContext.Current.CancellationToken);
+        var second = await drv.ReadAsync(["@System.Firmware"], TestContext.Current.CancellationToken);
+
+        first[0].Value.ShouldBe("CPU 1516");
+        second[0].Value.ShouldBe("V2.9.4");
+        // Both projections come from the same SZL 0x0011 payload — exactly one wire call.
+        reader.CallCount.ShouldBe(1);
+    }
+
+    [Fact]
+    public async Task ReadAsync_misses_cache_when_TTL_is_zero()
+    {
+        var info = new S7CpuInfo("CPU 1516", "V2.9.4", "6ES7 516-3AN01-0AB0");
+        var reader = new FakeSzlReader((_, _) => S7SzlParser.EncodeCpuInfo(info));
+
+        var opts = new S7DriverOptions
+        {
+            ExposeSystemTags = true,
+            SzlCacheTtl = TimeSpan.Zero,
+            Tags = [],
+        };
+        using var drv = new S7Driver(opts, "s7-cache-miss") { SzlReader = reader };
+
+        await drv.ReadAsync(["@System.CpuType"], TestContext.Current.CancellationToken);
+        await drv.ReadAsync(["@System.CpuType"], TestContext.Current.CancellationToken);
+
+        // TTL=Zero means every read goes to the wire.
+        reader.CallCount.ShouldBe(2);
+    }
+
+    [Fact]
+    public async Task ReadAsync_returns_BadNodeIdUnknown_for_unrecognised_system_address()
+    {
+        var reader = new FakeSzlReader((_, _) => null);
+        var opts = new S7DriverOptions { ExposeSystemTags = true, Tags = [] };
+        using var drv = new S7Driver(opts, "s7-bad-system") { SzlReader = reader };
+
+        var snaps = await drv.ReadAsync(["@System.NotARealField"], TestContext.Current.CancellationToken);
+        snaps.Count.ShouldBe(1);
+        snaps[0].StatusCode.ShouldBe(0x80340000u, "BadNodeIdUnknown");
+        // No SZL wire call — the address didn't resolve to a known descriptor.
+        reader.CallCount.ShouldBe(0);
+    }
+
+    [Fact]
+    public async Task ReadAsync_returns_diag_buffer_entry_string_when_reader_supplies_payload()
+    {
+        var entries = new[]
+        {
+            new S7DiagBufferEntry(new DateTimeOffset(2024, 1, 1, 0, 0, 0, TimeSpan.Zero), 0xCAFE, 3, "Event 0xCAFE (priority 3)"),
+            new S7DiagBufferEntry(new DateTimeOffset(2024, 1, 1, 0, 0, 5, TimeSpan.Zero), 0xBEEF, 4, "Event 0xBEEF (priority 4)"),
+        };
+        var reader = new FakeSzlReader((id, _) =>
+            id == S7SzlIds.DiagnosticBuffer ? S7SzlParser.EncodeDiagBuffer(entries) : null);
+
+        var opts = new S7DriverOptions { ExposeSystemTags = true, DiagBufferDepth = 5, Tags = [] };
+        using var drv = new S7Driver(opts, "s7-diag") { SzlReader = reader };
+
+        var snaps = await drv.ReadAsync(
+            ["@System.DiagBuffer.Entry[0]", "@System.DiagBuffer.Entry[1]"],
+            TestContext.Current.CancellationToken);
+
+        snaps.Count.ShouldBe(2);
+        snaps[0].StatusCode.ShouldBe(0u);
+        ((string)snaps[0].Value!).ShouldContain("0xCAFE");
+        ((string)snaps[1].Value!).ShouldContain("0xBEEF");
+    }
+
+    [Fact]
+    public async Task ReadAsync_mixes_system_tags_with_unknown_regular_tags_returning_status_per_request()
+    {
+        var info = new S7CpuInfo("CPU 1500", "V2.9", "6ES7");
+        var reader = new FakeSzlReader((_, _) => S7SzlParser.EncodeCpuInfo(info));
+        var opts = new S7DriverOptions { ExposeSystemTags = true, Tags = [] };
+        using var drv = new S7Driver(opts, "s7-mixed") { SzlReader = reader };
+
+        // SystemTag should resolve via the short-circuit; "NoSuchTag" should never reach
+        // the Plc gate because the only other request was a system tag — but if it does,
+        // the test must not hang (RequirePlc would throw). Both are short-circuited so
+        // the call returns BadNodeIdUnknown for "NoSuchTag" via the system-prefix check
+        // failing. To exercise that, request both as @System.* references — one valid,
+        // one bogus.
+        var snaps = await drv.ReadAsync(
+            ["@System.CpuType", "@System.Bogus"],
+            TestContext.Current.CancellationToken);
+
+        snaps[0].Value.ShouldBe("CPU 1500");
+        snaps[0].StatusCode.ShouldBe(0u);
+        snaps[1].StatusCode.ShouldBe(0x80340000u, "BadNodeIdUnknown for unrecognised @System.* address");
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.S7.Tests/Szl/S7SzlParserTests.cs

@@ -0,0 +1,213 @@
+using System.Buffers.Binary;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Driver.S7.Szl;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.S7.Tests.Szl;
+
+/// <summary>
+///     PR-S7-E1 — golden-byte tests for <see cref="S7SzlParser"/>. Each test hand-crafts a
+///     structurally-valid SZL response payload (matching the layout in the Siemens function
+///     manual, §"SSL-IDs") and asserts the parser projects every field the driver surfaces
+///     through <c>@System.*</c>. Round-trip tests prove encode-then-decode is the identity
+///     so test fixtures stay self-consistent without leaning on real PLC traffic.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class S7SzlParserTests
+{
+    [Fact]
+    public void ParseCpuInfo_decodes_module_identification_records()
+    {
+        // Hand-craft a SZL 0x0011 response with three records:
+        //   index 0x0001 — MLFB "6ES7 516-3AN01-0AB0  " (20 bytes ASCII)
+        //   index 0x0006 — firmware Vmajor.minor.patch encoded in Ausbg1/Ausbg2
+        //   index 0x0007 — friendly CPU name "CPU 1516-3 PN/DP"
+        var info = new S7CpuInfo(
+            CpuType: "CPU 1516-3 PN/DP",
+            Firmware: "V2.9.4",
+            OrderNo: "6ES7 516-3AN01-0AB0");
+        var payload = S7SzlParser.EncodeCpuInfo(info);
+
+        var parsed = S7SzlParser.ParseCpuInfo(payload);
+        parsed.OrderNo.ShouldBe("6ES7 516-3AN01-0AB0");
+        parsed.CpuType.ShouldBe("CPU 1516-3 PN/DP");
+        parsed.Firmware.ShouldBe("V2.9.4");
+    }
+
+    [Fact]
+    public void ParseCpuInfo_handles_missing_records_with_unknown_fallback()
+    {
+        // Header claims zero records — every field falls back to "(unknown)" rather than throwing.
+        var buf = new byte[S7SzlParser.HeaderLength];
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(0, 2), S7SzlIds.ModuleIdentification);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(2, 2), 0);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(4, 2), 28); // record length valid, count = 0
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(6, 2), 0);
+
+        var parsed = S7SzlParser.ParseCpuInfo(buf);
+        parsed.CpuType.ShouldBe("(unknown)");
+        parsed.Firmware.ShouldBe("(unknown)");
+        parsed.OrderNo.ShouldBe("(unknown)");
+    }
+
+    [Fact]
+    public void ParseCycleStats_decodes_min_max_avg_milliseconds()
+    {
+        // Hand-craft SZL 0x0132 with avg=10ms, min=5ms, max=42ms.
+        var stats = new S7CycleStats(MinMs: 5, MaxMs: 42, AvgMs: 10);
+        var payload = S7SzlParser.EncodeCycleStats(stats);
+
+        var parsed = S7SzlParser.ParseCycleStats(payload);
+        parsed.MinMs.ShouldBe(5);
+        parsed.MaxMs.ShouldBe(42);
+        parsed.AvgMs.ShouldBe(10);
+    }
+
+    [Fact]
+    public void ParseDiagBuffer_decodes_five_entries_with_timestamps_and_event_ids()
+    {
+        var entries = new List<S7DiagBufferEntry>
+        {
+            new(new DateTimeOffset(2024, 1, 15, 8, 30, 0, TimeSpan.Zero), 0x113A, 1, "Event 0x113A (priority 1)"),
+            new(new DateTimeOffset(2024, 1, 15, 8, 31, 5, TimeSpan.Zero), 0x4302, 5, "Event 0x4302 (priority 5)"),
+            new(new DateTimeOffset(2024, 1, 15, 8, 32, 17, TimeSpan.Zero), 0x4308, 5, "Event 0x4308 (priority 5)"),
+            new(new DateTimeOffset(2024, 1, 15, 8, 33, 42, TimeSpan.Zero), 0x39C0, 26, "Event 0x39C0 (priority 26)"),
+            new(new DateTimeOffset(2024, 1, 15, 8, 34, 59, TimeSpan.Zero), 0x4505, 1, "Event 0x4505 (priority 1)"),
+        };
+        var payload = S7SzlParser.EncodeDiagBuffer(entries);
+
+        var parsed = S7SzlParser.ParseDiagBuffer(payload, maxEntries: 10);
+        parsed.Count.ShouldBe(5);
+        parsed[0].EventId.ShouldBe((ushort)0x113A);
+        parsed[0].Priority.ShouldBe((byte)1);
+        parsed[0].OccurrenceUtc.Year.ShouldBe(2024);
+        parsed[0].OccurrenceUtc.Month.ShouldBe(1);
+        parsed[0].OccurrenceUtc.Day.ShouldBe(15);
+        parsed[0].OccurrenceUtc.Hour.ShouldBe(8);
+        parsed[0].OccurrenceUtc.Minute.ShouldBe(30);
+
+        parsed[3].EventId.ShouldBe((ushort)0x39C0);
+        parsed[3].Priority.ShouldBe((byte)26);
+        parsed[3].OccurrenceUtc.Second.ShouldBe(42);
+    }
+
+    [Fact]
+    public void ParseDiagBuffer_caps_entries_to_caller_supplied_max()
+    {
+        var entries = new List<S7DiagBufferEntry>();
+        for (var i = 0; i < 10; i++)
+            entries.Add(new(DateTimeOffset.UnixEpoch, (ushort)(0x1000 + i), 1, ""));
+        var payload = S7SzlParser.EncodeDiagBuffer(entries);
+
+        var parsed = S7SzlParser.ParseDiagBuffer(payload, maxEntries: 3);
+        parsed.Count.ShouldBe(3);
+        parsed[0].EventId.ShouldBe((ushort)0x1000);
+        parsed[2].EventId.ShouldBe((ushort)0x1002);
+    }
+
+    [Fact]
+    public void ParseCpuInfo_throws_on_truncated_payload()
+    {
+        // Header claims 28-byte records × 3 but body is only 4 bytes — should reject.
+        var buf = new byte[S7SzlParser.HeaderLength + 4];
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(0, 2), S7SzlIds.ModuleIdentification);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(4, 2), 28);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(6, 2), 3);
+
+        Should.Throw<ArgumentException>(() => S7SzlParser.ParseCpuInfo(buf));
+    }
+
+    [Fact]
+    public void ParseCycleStats_throws_on_short_record()
+    {
+        // Record length advertised as 8 bytes — too short for the cycle-time payload.
+        var buf = new byte[S7SzlParser.HeaderLength + 8];
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(0, 2), S7SzlIds.CpuStatusData);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(4, 2), 8);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(6, 2), 1);
+
+        Should.Throw<ArgumentException>(() => S7SzlParser.ParseCycleStats(buf));
+    }
+
+    [Fact]
+    public void ParseDiagBuffer_throws_on_wrong_record_length()
+    {
+        // SZL 0x00A0 records are exactly 20 bytes; 16 should be rejected.
+        var buf = new byte[S7SzlParser.HeaderLength + 16];
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(0, 2), S7SzlIds.DiagnosticBuffer);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(4, 2), 16);
+        BinaryPrimitives.WriteUInt16BigEndian(buf.AsSpan(6, 2), 1);
+
+        Should.Throw<ArgumentException>(() => S7SzlParser.ParseDiagBuffer(buf, maxEntries: 1));
+    }
+
+    [Fact]
+    public void Parser_throws_on_header_only_truncation()
+    {
+        Should.Throw<ArgumentException>(() => S7SzlParser.ParseCpuInfo(new byte[4]));
+        Should.Throw<ArgumentException>(() => S7SzlParser.ParseCycleStats(new byte[2]));
+        Should.Throw<ArgumentException>(() => S7SzlParser.ParseDiagBuffer(new byte[3], maxEntries: 1));
+    }
+
+    [Fact]
+    public void Round_trip_encode_then_parse_preserves_cpu_info()
+    {
+        var original = new S7CpuInfo("CPU 1215C", "V4.5.0", "6ES7 215-1AG40-0XB0");
+        var enc = S7SzlParser.EncodeCpuInfo(original);
+        var dec = S7SzlParser.ParseCpuInfo(enc);
+        dec.CpuType.ShouldBe(original.CpuType);
+        dec.Firmware.ShouldBe(original.Firmware);
+        dec.OrderNo.ShouldBe(original.OrderNo);
+
+        // Re-encode the parsed result and parse again — must equal the first decode.
+        var reenc = S7SzlParser.EncodeCpuInfo(dec);
+        var redec = S7SzlParser.ParseCpuInfo(reenc);
+        redec.ShouldBe(dec);
+    }
+
+    [Fact]
+    public void Round_trip_encode_then_parse_preserves_cycle_stats()
+    {
+        var original = new S7CycleStats(MinMs: 1, MaxMs: 999, AvgMs: 7);
+        var enc = S7SzlParser.EncodeCycleStats(original);
+        var dec = S7SzlParser.ParseCycleStats(enc);
+        dec.ShouldBe(original);
+
+        var reenc = S7SzlParser.EncodeCycleStats(dec);
+        var redec = S7SzlParser.ParseCycleStats(reenc);
+        redec.ShouldBe(dec);
+    }
+
+    [Fact]
+    public void Round_trip_encode_then_parse_preserves_diag_buffer_event_ids_and_priority()
+    {
+        // Use UTC midnight aligned timestamps so the BCD encoder's second-precision rounding
+        // (ms isn't round-tripped) doesn't cause a comparison miss.
+        var original = new[]
+        {
+            new S7DiagBufferEntry(new DateTimeOffset(2024, 6, 1, 12, 0, 0, TimeSpan.Zero), 0xAAAA, 5, "Event 0xAAAA (priority 5)"),
+            new S7DiagBufferEntry(new DateTimeOffset(2024, 6, 2, 0, 30, 15, TimeSpan.Zero), 0xBBBB, 10, "Event 0xBBBB (priority 10)"),
+        };
+        var enc = S7SzlParser.EncodeDiagBuffer(original);
+        var dec = S7SzlParser.ParseDiagBuffer(enc, maxEntries: 10);
+        dec.Count.ShouldBe(2);
+
+        // EventId / Priority round-trip exactly; OccurrenceUtc round-trips at second precision.
+        dec[0].EventId.ShouldBe(original[0].EventId);
+        dec[0].Priority.ShouldBe(original[0].Priority);
+        dec[0].OccurrenceUtc.ShouldBe(original[0].OccurrenceUtc);
+        dec[1].EventId.ShouldBe(original[1].EventId);
+        dec[1].OccurrenceUtc.ShouldBe(original[1].OccurrenceUtc);
+
+        // Re-encode + re-parse should yield the same decoded list.
+        var reenc = S7SzlParser.EncodeDiagBuffer(dec);
+        var redec = S7SzlParser.ParseDiagBuffer(reenc, maxEntries: 10);
+        redec.Count.ShouldBe(dec.Count);
+        for (var i = 0; i < dec.Count; i++)
+        {
+            redec[i].EventId.ShouldBe(dec[i].EventId);
+            redec[i].Priority.ShouldBe(dec[i].Priority);
+            redec[i].OccurrenceUtc.ShouldBe(dec[i].OccurrenceUtc);
+        }
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCATAlarmIntegrationTests.cs

@@ -0,0 +1,102 @@
+using System.Collections.Concurrent;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests;
+
+/// <summary>
+///     PR 5.1 / #316 — end-to-end alarm-integration scaffold against a live TwinCAT 3 XAR
+///     runtime. Skipped via <see cref="TwinCATFactAttribute"/> when the VM isn't reachable.
+///     Proves the driver's <see cref="IAlarmSource"/> bridge surfaces TC3 EventLogger events
+///     when the PLC's <c>FB_AlarmHarness</c> calls <c>FB_TcLogEvent</c>.
+/// </summary>
+/// <remarks>
+///     <para><b>Required VM project state</b> (see <c>TwinCatProject/README.md</c>
+///     §"Alarm scenarios"):</para>
+///     <list type="bullet">
+///       <item>GVL <c>GVL_Alarms</c> with <c>bTriggerEvent : BOOL</c> + <c>bAcked : BOOL</c>.
+///         A test harness flips <c>bTriggerEvent</c> from <c>FALSE</c> to <c>TRUE</c> via the
+///         driver's <c>WriteAsync</c> path; <c>FB_AlarmHarness</c> sees the rising edge +
+///         calls <c>FB_TcLogEvent</c> on the PLC side.</item>
+///       <item>FB <c>FB_AlarmHarness</c> wired into <c>MAIN</c> that calls <c>FB_TcLogEvent</c>
+///         with a configured event class GUID + severity + source string when
+///         <c>GVL_Alarms.bTriggerEvent</c> rises.</item>
+///     </list>
+///     <para><b>Decode caveat</b> — Beckhoff doesn't ship a managed wrapper for
+///     <c>TcEventLogger</c> in <c>Beckhoff.TwinCAT.Ads</c> v6, so the production
+///     gate is best-effort and several event fields may surface as <c>"Unknown"</c>.
+///     This test asserts the bridge fires + the event has non-empty content; field-level
+///     decode tightening lands on a follow-up PR (see
+///     <c>docs/v3/twincat-eventlogger-spike.md</c>).</para>
+/// </remarks>
+[Collection("TwinCATXar")]
+[Trait("Category", "Integration")]
+[Trait("Simulator", "TwinCAT-XAR")]
+public sealed class TwinCATAlarmIntegrationTests(TwinCATXarFixture sim)
+{
+    [TwinCATFact]
+    public async Task Driver_raises_alarm_event_when_PLC_logs_event()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+
+        // Fixture-side state is documented in TwinCatProject/README.md §"Alarm scenarios".
+        // The harness is currently a build-only placeholder — once the GVL + FB_AlarmHarness
+        // ship, replace the Skip below with the live-trigger flow:
+        //   1. Init driver with EnableAlarms=true + GVL_Alarms.bTriggerEvent declared as a
+        //      writable BOOL tag.
+        //   2. SubscribeAlarmsAsync([], ct).
+        //   3. WriteAsync to flip bTriggerEvent from FALSE to TRUE — the PLC's
+        //      FB_AlarmHarness sees the rising edge + calls FB_TcLogEvent.
+        //   4. Assert OnAlarmEvent fires within ~5s with a non-empty Source + Message.
+        Assert.Skip(
+            "PR 5.1 / #316 — alarm-integration build-only scaffold. The GVL_Alarms + " +
+            "FB_AlarmHarness fixture hasn't been authored on the XAR project yet (build-time " +
+            "stubs ship under TwinCatProject/PLC; live trigger lands once the XAR project " +
+            "imports them). Until then this test self-skips even when the runtime is up.");
+
+        await Task.CompletedTask;
+    }
+
+    /// <summary>
+    ///     Build the AMS options with <see cref="TwinCATDriverOptions.EnableAlarms"/> on so
+    ///     the driver instantiates the alarm source. Mirrors the smoke-test option builder
+    ///     but flips the alarm gate on; once the live fixture lands, the test body above
+    ///     calls this helper directly.
+    /// </summary>
+    [System.Diagnostics.CodeAnalysis.SuppressMessage(
+        "Style", "IDE0051", Justification = "Used by the live test body once the fixture ships.")]
+    private static TwinCATDriverOptions BuildAlarmOptions(TwinCATXarFixture sim) => new()
+    {
+        Devices = [new TwinCATDeviceOptions(
+            HostAddress: $"ads://{sim.TargetNetId}:{sim.AmsPort}",
+            DeviceName: $"xar-{sim.TargetNetId}:{sim.AmsPort}")],
+        Tags =
+        [
+            // bTriggerEvent rises FALSE→TRUE to fire the PLC-side LogEvent call.
+            new TwinCATTagDefinition(
+                Name: "AlarmTrigger",
+                DeviceHostAddress: $"ads://{sim.TargetNetId}:{sim.AmsPort}",
+                SymbolPath: "GVL_Alarms.bTriggerEvent",
+                DataType: TwinCATDataType.Bool,
+                Writable: true),
+        ],
+        Probe = new TwinCATProbeOptions { Enabled = false },
+        EnableAlarms = true,
+    };
+
+    /// <summary>
+    ///     Helper kept for parity with the live test body once the fixture ships — collects
+    ///     <see cref="IAlarmSource.OnAlarmEvent"/> off the driver into a queue caller can
+    ///     drain after the trigger flip.
+    /// </summary>
+    [System.Diagnostics.CodeAnalysis.SuppressMessage(
+        "Style", "IDE0051", Justification = "Used by the live test body once the fixture ships.")]
+    private static ConcurrentQueue<AlarmEventArgs> WireAlarmCollector(IAlarmSource src)
+    {
+        var q = new ConcurrentQueue<AlarmEventArgs>();
+        src.OnAlarmEvent += (_, e) => q.Enqueue(e);
+        return q;
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/GVLs/GVL_Alarms.TcGVL

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<TcPlcObject Version="1.1.0.1" ProductVersion="3.1.4024.0">
+  <GVL Name="GVL_Alarms" Id="{00000000-0000-0000-0000-000000000505}">
+    <Declaration><![CDATA[// PR 5.1 / #316 — TC3 EventLogger fixture for TwinCATAlarmIntegrationTests.
+// bTriggerEvent rises FALSE -> TRUE to fire one EventLogger event via FB_AlarmHarness.
+// bAcked is operator-side ACK toggle the alarm-source bridge writes back when the
+// driver's AcknowledgeAsync runs. nLastEventClass / nLastSeverity track the last
+// event the harness raised so the integration test can sanity-check the values it
+// expects to surface through IAlarmSource.
+VAR_GLOBAL
+    bTriggerEvent     : BOOL := FALSE;
+    bAcked            : BOOL := FALSE;
+    nLastEventClass   : DINT := 0;
+    nLastSeverity     : USINT := 0;
+    fbAlarmHarness    : FB_AlarmHarness;
+END_VAR
+]]></Declaration>
+  </GVL>
+</TcPlcObject>

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/POUs/FB_AlarmHarness.TcPOU

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="utf-8"?>
+<TcPlcObject Version="1.1.0.1" ProductVersion="3.1.4024.0">
+  <POU Name="FB_AlarmHarness" Id="{00000000-0000-0000-0000-000000000303}" SpecialFunc="None">
+    <Declaration><![CDATA[// PR 5.1 / #316 — drives the TC3 EventLogger so TwinCATAlarmIntegrationTests
+// can observe an event surfacing through the driver's IAlarmSource bridge.
+//
+// On a rising edge of GVL_Alarms.bTriggerEvent the harness calls FB_TcLogEvent
+// with a fixed event class GUID + severity from GVL_Alarms.nLastSeverity and a
+// short message string. The wire side of the EventLogger then dispatches a
+// notification on AMS port 110 (AMSPORT_EVENTLOG); the driver's secondary
+// AdsClient receives the event + projects it onto OnAlarmEvent.
+//
+// The harness intentionally targets a single event class GUID per fixture cycle;
+// the test asserts shape + presence rather than per-event-class decoding because
+// the binary protocol is undocumented in managed code (see
+// docs/v3/twincat-eventlogger-spike.md).
+FUNCTION_BLOCK FB_AlarmHarness
+VAR
+    fbTrigger        : R_TRIG;
+    fbLogEvent       : FB_TcLogEvent; // declared in Tc3_EventLogger
+    sMessage         : STRING(255) := 'Integration-fixture EventLogger trigger';
+END_VAR
+]]></Declaration>
+    <Implementation>
+      <ST><![CDATA[fbTrigger(CLK := GVL_Alarms.bTriggerEvent);
+IF fbTrigger.Q THEN
+    // Fixed event-class GUID for the integration fixture; replace with whatever
+    // class the operator wires into the TC3 EventLogger configuration GUI.
+    fbLogEvent.ipMessage := 0;        // placeholder — TwinCAT 3 ships richer
+                                      // overloads; the integration test only
+                                      // asserts an event surfaces, not the
+                                      // specific payload bytes.
+    fbLogEvent.eSeverity := TcEventSeverity.Warning;
+    fbLogEvent.bConfirmable := TRUE;
+    fbLogEvent.Execute(bExecute := TRUE);
+
+    GVL_Alarms.nLastEventClass := 1;  // fixture-side echo so a watch window can
+                                      // confirm the harness fired.
+    GVL_Alarms.nLastSeverity   := 100;
+END_IF
+fbLogEvent.Execute(bExecute := FALSE);
+]]></ST>
+    </Implementation>
+  </POU>
+</TcPlcObject>

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md

@@ -278,6 +278,88 @@ dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests `
     --filter "FullyQualifiedName~TwinCATSymbolVersionTests"
 ```
 
+## Alarm scenarios
+
+PR 5.1 (#316) ships an opt-in TC3 EventLogger bridge. The driver's
+`IAlarmSource` implementation surfaces alarms by opening a second
+`AdsClient` against AMS port `110` (`AMSPORT_EVENTLOG`) and adding a
+device notification on `ADSIGRP_TCEVENTLOG_ALARMS`. The decode is
+best-effort because Beckhoff doesn't ship a managed `TcEventLogger`
+wrapper (only C++ TcCOM headers); some fields surface as `Unknown`
+until a follow-up PR lands a binary-protocol decoder. Spike output
+captured at `docs/v3/twincat-eventlogger-spike.md`.
+
+The integration test
+(`TwinCATAlarmIntegrationTests.Driver_raises_alarm_event_when_PLC_logs_event`)
+ships build-only in PR 5.1 — once the XAR project imports the GVL +
+FB_AlarmHarness below, swap the `Assert.Skip` in the test body for the
+live flow:
+
+1. Init the driver with `EnableAlarms=true`.
+2. `SubscribeAlarmsAsync([], ct)`.
+3. `WriteAsync` to flip `GVL_Alarms.bTriggerEvent` from `FALSE` to
+   `TRUE` — `FB_AlarmHarness` sees the rising edge and calls
+   `FB_TcLogEvent` on the PLC side.
+4. Assert `OnAlarmEvent` fires within `~5 s` with non-empty
+   `Source` + `Message`.
+
+### Global Variable List: `GVL_Alarms`
+
+```st
+VAR_GLOBAL
+    bTriggerEvent     : BOOL := FALSE;
+    bAcked            : BOOL := FALSE;
+    nLastEventClass   : DINT := 0;
+    nLastSeverity     : USINT := 0;
+    fbAlarmHarness    : FB_AlarmHarness;
+END_VAR
+```
+
+The XAE-form GVL ships at `PLC/GVLs/GVL_Alarms.TcGVL`; import it
+alongside the other fixture GVLs.
+
+### POU: `FB_AlarmHarness`
+
+```st
+FUNCTION_BLOCK FB_AlarmHarness
+VAR
+    fbTrigger    : R_TRIG;
+    fbLogEvent   : FB_TcLogEvent; // declared in Tc3_EventLogger
+    sMessage     : STRING(255) := 'Integration-fixture EventLogger trigger';
+END_VAR
+
+fbTrigger(CLK := GVL_Alarms.bTriggerEvent);
+IF fbTrigger.Q THEN
+    fbLogEvent.eSeverity := TcEventSeverity.Warning;
+    fbLogEvent.bConfirmable := TRUE;
+    fbLogEvent.Execute(bExecute := TRUE);
+    GVL_Alarms.nLastEventClass := 1;
+    GVL_Alarms.nLastSeverity := 100;
+END_IF
+fbLogEvent.Execute(bExecute := FALSE);
+```
+
+The XAE-form POU ships at `PLC/POUs/FB_AlarmHarness.TcPOU`. Wire it
+into `MAIN`:
+
+```st
+GVL_Alarms.fbAlarmHarness();
+```
+
+### Event class IDs / severity buckets / cleared-on transitions
+
+| Symbol | Value | Notes |
+| --- | --- | --- |
+| `nLastEventClass` | `DINT`, fixture-side echo (`1` after a rising edge) | Watch-window aid; the actual EventLogger event class is configured in the TC3 GUI per project. |
+| `nLastSeverity` | `USINT`, fixed `100` after a rising edge | Maps to `AlarmSeverity.Medium` via `TwinCATAlarmSource.MapSeverity` (≤128 = Medium). |
+| `bTriggerEvent` | `BOOL`, operator/test writes | Rising edge only — flip back to `FALSE` then `TRUE` to re-fire. |
+| `bAcked` | `BOOL`, driver writes when `AcknowledgeAsync` runs | Cleared by next event raise. |
+
+The TC3 EventLogger surfaces the cleared transition automatically when
+`fbLogEvent.bConfirmable=TRUE` and an operator confirms; the driver
+projects the clear as a second `OnAlarmEvent` with the same condition
+id.
+
 ## How to run the TwinCAT-tier tests
 
 On the dev box:

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/TwinCATAlarmSourceTests.cs

@@ -0,0 +1,314 @@
+using System.Collections.Concurrent;
+using System.Text.Json;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests;
+
+/// <summary>
+///     PR 5.1 / #316 — covers the <see cref="IAlarmSource"/> shape on
+///     <see cref="TwinCATDriver"/>: feature-gating, gate event projection, multi-event
+///     ordering, acknowledge round-trip, and JSON DTO round-trip on the options.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class TwinCATAlarmSourceTests
+{
+    [Fact]
+    public async Task EnableAlarms_false_does_not_create_alarm_source()
+    {
+        var drv = new TwinCATDriver(new TwinCATDriverOptions
+        {
+            Devices = [new TwinCATDeviceOptions("ads://5.23.91.23.1.1:851")],
+            Probe = new TwinCATProbeOptions { Enabled = false },
+            EnableAlarms = false,
+        }, "drv-1");
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        drv.HasAlarmSource.ShouldBeFalse();
+
+        var handle = await drv.SubscribeAlarmsAsync([], CancellationToken.None);
+        handle.ShouldBeOfType<TwinCATAlarmSubscriptionHandle>();
+        ((TwinCATAlarmSubscriptionHandle)handle).Id.ShouldBe(0);
+
+        await drv.ShutdownAsync(CancellationToken.None);
+    }
+
+    [Fact]
+    public async Task EnableAlarms_false_OnAlarmEvent_never_fires()
+    {
+        var gate = new FakeTwinCATAlarmGate();
+        var drv = new TwinCATDriver(new TwinCATDriverOptions
+        {
+            Devices = [new TwinCATDeviceOptions("ads://5.23.91.23.1.1:851")],
+            Probe = new TwinCATProbeOptions { Enabled = false },
+            EnableAlarms = false,
+        }, "drv-1", alarmGate: gate);
+
+        await drv.InitializeAsync("{}", CancellationToken.None);
+        var raised = new ConcurrentQueue<AlarmEventArgs>();
+        drv.OnAlarmEvent += (_, e) => raised.Enqueue(e);
+        _ = await drv.SubscribeAlarmsAsync([], CancellationToken.None);
+
+        // Even if a stray event is fired through the gate (a buggy operator wired in a
+        // fake), the disabled-mode driver doesn't subscribe + the event is dropped.
+        gate.RaiseAlarm(new TwinCATAlarmEvent("Class.A", "Source1", 100, "msg", DateTimeOffset.UtcNow, false));
+        await Task.Delay(20);
+
+        raised.ShouldBeEmpty();
+        await drv.ShutdownAsync(CancellationToken.None);
+    }
+
+    [Fact]
+    public async Task EnableAlarms_true_creates_source_and_starts_gate_on_first_subscribe()
+    {
+        var gate = new FakeTwinCATAlarmGate();
+        var drv = new TwinCATDriver(new TwinCATDriverOptions
+        {
+            Devices = [new TwinCATDeviceOptions("ads://5.23.91.23.1.1:851")],
+            Probe = new TwinCATProbeOptions { Enabled = false },
+            EnableAlarms = true,
+        }, "drv-1", alarmGate: gate);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+        drv.HasAlarmSource.ShouldBeTrue();
+
+        gate.StartCount.ShouldBe(0);
+        _ = await drv.SubscribeAlarmsAsync([], CancellationToken.None);
+        gate.StartCount.ShouldBe(1);
+
+        // Second subscribe doesn't restart the gate.
+        _ = await drv.SubscribeAlarmsAsync([], CancellationToken.None);
+        gate.StartCount.ShouldBe(1);
+
+        await drv.ShutdownAsync(CancellationToken.None);
+    }
+
+    [Fact]
+    public async Task Gate_event_raises_AlarmEvent_on_driver_with_correct_shape()
+    {
+        var gate = new FakeTwinCATAlarmGate();
+        var drv = new TwinCATDriver(new TwinCATDriverOptions
+        {
+            Devices = [new TwinCATDeviceOptions("ads://5.23.91.23.1.1:851")],
+            Probe = new TwinCATProbeOptions { Enabled = false },
+            EnableAlarms = true,
+        }, "drv-1", alarmGate: gate);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        var raised = new ConcurrentQueue<AlarmEventArgs>();
+        drv.OnAlarmEvent += (_, e) => raised.Enqueue(e);
+        _ = await drv.SubscribeAlarmsAsync([], CancellationToken.None);
+
+        var stamp = DateTimeOffset.UtcNow;
+        gate.RaiseAlarm(new TwinCATAlarmEvent(
+            EventClass: "TcEventClass.MachineFault",
+            Source: "Conveyor1.MotorOverload",
+            Severity: 200,
+            Message: "Motor overload tripped",
+            OccurrenceUtc: stamp,
+            Acked: false));
+
+        raised.Count.ShouldBe(1);
+        var args = raised.First();
+        args.SourceNodeId.ShouldBe("Conveyor1.MotorOverload");
+        args.AlarmType.ShouldBe("TcEventClass.MachineFault");
+        args.Message.ShouldBe("Motor overload tripped");
+        args.Severity.ShouldBe(AlarmSeverity.Critical);
+        args.SourceTimestampUtc.ShouldBe(stamp.UtcDateTime);
+        args.ConditionId.ShouldBe("Conveyor1.MotorOverload#TcEventClass.MachineFault");
+
+        await drv.ShutdownAsync(CancellationToken.None);
+    }
+
+    [Fact]
+    public async Task Multiple_alarm_events_are_delivered_in_order()
+    {
+        var gate = new FakeTwinCATAlarmGate();
+        var drv = new TwinCATDriver(new TwinCATDriverOptions
+        {
+            Devices = [new TwinCATDeviceOptions("ads://5.23.91.23.1.1:851")],
+            Probe = new TwinCATProbeOptions { Enabled = false },
+            EnableAlarms = true,
+        }, "drv-1", alarmGate: gate);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        var raised = new List<AlarmEventArgs>();
+        drv.OnAlarmEvent += (_, e) => { lock (raised) raised.Add(e); };
+        _ = await drv.SubscribeAlarmsAsync([], CancellationToken.None);
+
+        var t = DateTimeOffset.UtcNow;
+        for (var i = 0; i < 5; i++)
+        {
+            gate.RaiseAlarm(new TwinCATAlarmEvent(
+                "Class.X", $"Source{i}", (ushort)(50 + i * 10), $"msg{i}", t.AddMilliseconds(i), false));
+        }
+
+        raised.Count.ShouldBe(5);
+        for (var i = 0; i < 5; i++)
+            raised[i].SourceNodeId.ShouldBe($"Source{i}");
+
+        await drv.ShutdownAsync(CancellationToken.None);
+    }
+
+    [Fact]
+    public async Task SourceFilter_only_passes_matching_source()
+    {
+        var gate = new FakeTwinCATAlarmGate();
+        var drv = new TwinCATDriver(new TwinCATDriverOptions
+        {
+            Devices = [new TwinCATDeviceOptions("ads://5.23.91.23.1.1:851")],
+            Probe = new TwinCATProbeOptions { Enabled = false },
+            EnableAlarms = true,
+        }, "drv-1", alarmGate: gate);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        var raised = new ConcurrentQueue<AlarmEventArgs>();
+        drv.OnAlarmEvent += (_, e) => raised.Enqueue(e);
+        _ = await drv.SubscribeAlarmsAsync(["Conveyor1"], CancellationToken.None);
+
+        gate.RaiseAlarm(new TwinCATAlarmEvent("C", "Conveyor1", 100, "x", DateTimeOffset.UtcNow, false));
+        gate.RaiseAlarm(new TwinCATAlarmEvent("C", "OtherSource", 100, "y", DateTimeOffset.UtcNow, false));
+        gate.RaiseAlarm(new TwinCATAlarmEvent("C", "conveyor1", 100, "z", DateTimeOffset.UtcNow, false)); // case-insensitive
+
+        raised.Count.ShouldBe(2);
+        raised.ShouldAllBe(e => string.Equals(e.SourceNodeId, "Conveyor1", StringComparison.OrdinalIgnoreCase));
+
+        await drv.ShutdownAsync(CancellationToken.None);
+    }
+
+    [Fact]
+    public async Task Acknowledge_round_trips_to_gate()
+    {
+        var gate = new FakeTwinCATAlarmGate();
+        var drv = new TwinCATDriver(new TwinCATDriverOptions
+        {
+            Devices = [new TwinCATDeviceOptions("ads://5.23.91.23.1.1:851")],
+            Probe = new TwinCATProbeOptions { Enabled = false },
+            EnableAlarms = true,
+        }, "drv-1", alarmGate: gate);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+        _ = await drv.SubscribeAlarmsAsync([], CancellationToken.None);
+
+        await drv.AcknowledgeAsync(
+            [new AlarmAcknowledgeRequest("Conveyor1", "cond-1", "operator A")],
+            CancellationToken.None);
+
+        gate.AckLog.Count.ShouldBe(1);
+        gate.AckLog.Single().SourceNodeId.ShouldBe("Conveyor1");
+        gate.AckLog.Single().ConditionId.ShouldBe("cond-1");
+        gate.AckLog.Single().Comment.ShouldBe("operator A");
+
+        await drv.ShutdownAsync(CancellationToken.None);
+    }
+
+    [Fact]
+    public async Task Acknowledge_when_disabled_is_noop()
+    {
+        var drv = new TwinCATDriver(new TwinCATDriverOptions
+        {
+            Devices = [new TwinCATDeviceOptions("ads://5.23.91.23.1.1:851")],
+            Probe = new TwinCATProbeOptions { Enabled = false },
+            EnableAlarms = false,
+        }, "drv-1");
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        // Should complete without throwing even though no source is wired.
+        await drv.AcknowledgeAsync(
+            [new AlarmAcknowledgeRequest("X", "Y", null)], CancellationToken.None);
+        await drv.UnsubscribeAlarmsAsync(new TwinCATAlarmSubscriptionHandle(0), CancellationToken.None);
+
+        await drv.ShutdownAsync(CancellationToken.None);
+    }
+
+    [Fact]
+    public async Task Unsubscribe_stops_event_delivery()
+    {
+        var gate = new FakeTwinCATAlarmGate();
+        var drv = new TwinCATDriver(new TwinCATDriverOptions
+        {
+            Devices = [new TwinCATDeviceOptions("ads://5.23.91.23.1.1:851")],
+            Probe = new TwinCATProbeOptions { Enabled = false },
+            EnableAlarms = true,
+        }, "drv-1", alarmGate: gate);
+        await drv.InitializeAsync("{}", CancellationToken.None);
+
+        var raised = new ConcurrentQueue<AlarmEventArgs>();
+        drv.OnAlarmEvent += (_, e) => raised.Enqueue(e);
+        var handle = await drv.SubscribeAlarmsAsync([], CancellationToken.None);
+
+        gate.RaiseAlarm(new TwinCATAlarmEvent("C", "S", 50, "before", DateTimeOffset.UtcNow, false));
+        await drv.UnsubscribeAlarmsAsync(handle, CancellationToken.None);
+        gate.RaiseAlarm(new TwinCATAlarmEvent("C", "S", 50, "after", DateTimeOffset.UtcNow, false));
+
+        raised.Count.ShouldBe(1);
+        raised.First().Message.ShouldBe("before");
+
+        await drv.ShutdownAsync(CancellationToken.None);
+    }
+
+    [Fact]
+    public void Severity_mapping_buckets_match_quartile_cuts()
+    {
+        TwinCATAlarmSource.MapSeverity(0).ShouldBe(AlarmSeverity.Low);
+        TwinCATAlarmSource.MapSeverity(64).ShouldBe(AlarmSeverity.Low);
+        TwinCATAlarmSource.MapSeverity(65).ShouldBe(AlarmSeverity.Medium);
+        TwinCATAlarmSource.MapSeverity(128).ShouldBe(AlarmSeverity.Medium);
+        TwinCATAlarmSource.MapSeverity(129).ShouldBe(AlarmSeverity.High);
+        TwinCATAlarmSource.MapSeverity(192).ShouldBe(AlarmSeverity.High);
+        TwinCATAlarmSource.MapSeverity(193).ShouldBe(AlarmSeverity.Critical);
+        TwinCATAlarmSource.MapSeverity(255).ShouldBe(AlarmSeverity.Critical);
+    }
+
+    [Fact]
+    public void Options_round_trip_preserves_EnableAlarms()
+    {
+        var original = new TwinCATDriverOptions
+        {
+            Devices = [new TwinCATDeviceOptions("ads://5.23.91.23.1.1:851", DeviceName: "Mach1")],
+            EnableAlarms = true,
+        };
+        var json = JsonSerializer.Serialize(original);
+        var restored = JsonSerializer.Deserialize<TwinCATDriverOptions>(json);
+
+        restored.ShouldNotBeNull();
+        restored.EnableAlarms.ShouldBeTrue();
+
+        var defaultRestored = JsonSerializer.Deserialize<TwinCATDriverOptions>("{}");
+        defaultRestored.ShouldNotBeNull();
+        defaultRestored.EnableAlarms.ShouldBeFalse();
+    }
+
+    /// <summary>
+    ///     Fake alarm gate — captures Start invocations + ack requests, exposes
+    ///     <see cref="RaiseAlarm"/> so tests can drive synthetic events without standing up
+    ///     a second AMS-port-110 session against a real TC3 EventLogger.
+    /// </summary>
+    private sealed class FakeTwinCATAlarmGate : ITwinCATAlarmGate
+    {
+        public int StartCount { get; private set; }
+        public List<AlarmAcknowledgeRequest> AckLog { get; } = new();
+        public List<TwinCATAlarmEvent> ActiveAlarmsList { get; } = new();
+        public IReadOnlyList<TwinCATAlarmEvent> ActiveAlarms => ActiveAlarmsList;
+
+        public event EventHandler<TwinCATAlarmEvent>? OnAlarmEvent;
+
+        public Task StartAsync(CancellationToken cancellationToken)
+        {
+            StartCount++;
+            return Task.CompletedTask;
+        }
+
+        public Task AcknowledgeAsync(
+            IReadOnlyList<AlarmAcknowledgeRequest> acknowledgements,
+            CancellationToken cancellationToken)
+        {
+            AckLog.AddRange(acknowledgements);
+            return Task.CompletedTask;
+        }
+
+        public void RaiseAlarm(TwinCATAlarmEvent evt) => OnAlarmEvent?.Invoke(this, evt);
+
+        public void Dispose() { }
+    }
+}