feat(twincat): opt-in ADS sum-read and /hosts diagnostics bag; refresh TwinCAT backlog (#645, #612)

Sum-read (#310): batches a poll's reads per device into sum commands capped at sumReadMaxItems,
per-item ADS errors mapped per tag, falls back to individual reads when the target refuses the
command. Diagnostics (#314): ADS state, app name, online-change count, task cycle/exec/jitter via
IDriverDiagnostics. Re-implemented against the current raw-byte read path (stranded auto/driver-gaps
commits predate it). Sum-write not ported. Unit tests only; live gate pending a route.

Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe

docs/v3/twincat-backlog.md

@@ -5,27 +5,61 @@ The v2 TwinCAT driver is considered solid: 28 integration tests (14 `[TwinCATFac
 three latent driver bugs shaken out (notification cycle units, `STRING(N)` mapper,
 bit-indexed BOOL path). Further work is deferred.
 
-Archived from `docs/drivers/TwinCAT-Test-Fixture.md` § Follow-up candidates.
+Archived from `docs/drivers/TwinCAT-Test-Fixture.md` § Follow-up candidates. Refreshed 2026-10-08
+(Gitea #612 / #645); live-validation results live in `docs/drivers/TwinCAT.md` § "Live validation".
 
-## Deferred items
+## Hardware available (as of 2026-10-08)
 
-1. **TC2 coverage** — spin up a TC2 runtime (Windows CE IPC or legacy XAR)
-   and run the same suite; any delta surfaces. Blocked on hardware.
+The Elma cleaner fleet (25 presses, 23 live) is the only real TwinCAT hardware in reach, and it is
+**production — strictly read-only**:
 
-2. **Notification coalescing under load** — run the subscribe test while
-   the PLC cycle is saturated (bump `lineSim` complexity, watch for
-   dropped notifications). Doable on current rig; deferred as lower
-   priority than v3 feature work.
+| Press | Runtime | AMS | Notes |
+|---|---|---|---|
+| 22 presses (e.g. Z33856 `10.201.45.236.1.1`, Z33733 `5.25.53.46.1.1`) | **TC2 2.11 on WinCE 6.0** | port **801** | read-validated 2026-10-07 |
+| **Z35474** (`5.118.56.93.1.1`, 10.201.23.227) | **TC3 3.1.4024** (Win NT 10) | port **851** | the **only TC3 press**; "Plc30 App" |
+| TCBSD fixture `10.100.0.128` (`41.169.163.43.1.1:851`) | TC3 | 851 | not a press; unreachable from the Mac |
 
-3. **Multi-hop AMS route** — add a test behind an IPC gateway with a
-   chained route entry. Blocked on hardware (gateway IPC).
+Access facts: ADS is TCP 48898. The driver sends no AddRoute (routes are provisioned out of band) and has
+no IP field, so a host needs a local AMS router — TwinCAT XAR, or `Beckhoff.TwinCAT.Ads.TcpRouter` hosted
+in-process (the driver csproj does not reference TcpRouter; the 2026-10-07 run used a scratch harness).
+The Mac reaches the presses directly over the VPN. **The PLC routes left by earlier tooling are STALE:**
+they name the Mac's old VPN IP (10.181.198.189), and the Mac is now 10.181.207.140, so a source NetId of
+`10.181.207.140.1.1` has no route on any press. We must not AddRoute on production, so the **live gate for
+this backlog is deferred pending a user-approved route** (owner refreshes the route, or the user approves
+reusing the old source NetId). Nothing below that says "live" has been run against TC3.
 
-4. **License-rotation automation** — XAR's 7-day trial expires on
-   schedule. Either automate `TcActivate.exe /reactivate` via a scheduled
-   task on the VM (not officially supported; reportedly works for some
-   TC3 builds), or buy a paid runtime license (~$1k one-time per runtime
-   per CPU) to kill the rotation. Ops item, not code.
+## Status of the original items
 
-5. **Lab rig** — cheapest IPC (CX7000 / CX9020) on a dedicated network;
-   the only route that covers TC2 + real EtherCAT I/O timing + cycle
-   jitter under CPU load. Blocked on hardware + budget.
+1. **TC2 coverage — DONE (read side).** No longer "blocked on hardware": the 2026-10-07 Elma run
+   (TwinCAT 2.11) verified browse, scalar/array/string reads and native notifications on TC2. What is
+   still unverified there: sum-read support (see item 6) and anything that writes.
+
+2. **Notification coalescing under load** — run the subscribe test while the PLC cycle is saturated.
+   Needs the TCBSD fixture (loading a production press is out of the question) and the `GVL_Perf` /
+   `FB_PerfChurn` fixture project from the stranded `auto/driver-gaps` branch. Fixture-gated.
+
+3. **Multi-hop AMS route** — a test behind an IPC gateway with a chained route entry. No hardware.
+
+4. **License-rotation automation** — XAR's 7-day trial expires on schedule. Ops item, not code.
+
+5. **Lab rig** — cheapest IPC on a dedicated network; the only route that covers real EtherCAT I/O
+   timing and cycle jitter under CPU load. Blocked on hardware + budget.
+
+## Added by #612 / #645
+
+6. **ADS sum-read (#310) — code DONE, live gate pending.** Opt-in `useSumRead` / `sumReadMaxItems`
+   (see `docs/drivers/TwinCAT.md` § "Sum-read"). Unit-tested against the fake client only. Live gate
+   (read-only, valid on a press): enable on Z33856 / Z33733 (TC2) and Z35474 (TC3), compare a batched poll
+   to individual reads value-for-value, and record whether TC2 CE 2.11 answers or refuses the sum command
+   (either outcome is a result — a refusal must fall back cleanly). Needs the route above.
+
+7. **Driver diagnostics (#314) — code DONE, live gate pending.** ADS state, app name, online-change
+   count, task cycle time, last exec time and jitter on the `/hosts` diagnostics bag. Live gate: confirm
+   `TwinCAT_SystemInfoVarList._TaskInfo[1]` resolves on TC2 2.11 (the driver tolerates its absence).
+
+8. **Flat vs VirtualTree browse on TC3 (#612)** — open. Only Z35474 is TC3; read-only symbol-table
+   upload in both modes, compare leaf sets. Add a `SymbolsLoadMode` option only if Flat drops struct
+   members. Needs the route. (Flat on TC2 already proved fine: 45,083 / 42,666 variables.)
+
+9. **Discovered struct/FB member writes (#612)** — deferred: writes, never on a press; fixture-only.
+   Likewise **sum-write** was deliberately NOT ported from the stranded branch.