From ee3ffa90ef26fa19a59a60f163d2d370ac497936 Mon Sep 17 00:00:00 2001
From: Joseph Doherty <dohejw01@gmail.com>
Date: Wed, 7 Oct 2026 21:41:18 -0400
Subject: [PATCH] =?UTF-8?q?docs:=20final=20review=20=E2=80=94=20CLAUDE.md?=
 =?UTF-8?q?=20AB=20transport=20section=20(I1/I2/I3/I4)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

AbCip: node-level Drivers:AbCip:DefaultTransport and the working pin
recipe. AbLegacy: default libplctag, Native opt-in, exact wire evidence.
Type-mismatch and Unsupported are refusals that never evict or degrade.

Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
---
 CLAUDE.md | 37 ++++++++++++++++++++++++++-----------
 1 file changed, 26 insertions(+), 11 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index ceb70efd..65a02ec7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -977,17 +977,32 @@ Dev/test LDAP is the **shared GLAuth** running on the Linux Docker host at `10.1
 
 AbCip and AbLegacy have a second, managed wire transport (`Driver.Ab.Transport`) beside libplctag, chosen by
 the driver-config key `transport` = `Native` | `Libplctag` (string; takes effect when the driver is
-constructed — every process start, so **the upgrade restart alone moves no-key drivers to Native**; set
-`"transport": "Libplctag"` BEFORE upgrading to stay put; AdminUI "Transport" dropdown; CLIs `--transport`). **Native is the default (Task 22):**
-an ABSENT key resolves to `Native` via `AbCipTransportResolver` / `AbLegacyTransportResolver` (driver, probe and
-CLI share them) — except an AbLegacy driver with any PLC-5 / `LogixPccc` device, which resolves to `Libplctag`.
-"Default" is encoded by omitting the key; the AdminUI must never re-emit a concrete default. Evidence: AbCip
-reads proven on a real CompactLogix (Z-35162, read-only); AbCip writes and all AbLegacy are `ab_server`-only.
-Fall back with `"transport": "Libplctag"`. ⚠️ AbLegacy native refuses status-bit sub-element
-writes (`T4:0.DN`…, client sees `BadNotSupported`; refusals never evict or degrade) and its ST byte order is unverified. Client-visible: native reports `BadTypeMismatch` where libplctag returned
-Good garbage for a same-width mis-authored type (DINT authored, REAL returned). libplctag is confined to
-`Libplctag*.cs` adapters by `LibplctagConfinementGuardTests`; do not reference it elsewhere. See
-`docs/drivers/AbCip.md` §Transport, `docs/drivers/AbLegacy.md`, and
+**constructed** — every process start, or a deploy that recreates it, not `ReinitializeAsync`; AdminUI
+"Transport" dropdown; CLIs `--transport`). "Default" is encoded by omitting the key; the AdminUI must never
+re-emit a concrete default. The defaults differ per driver (final review, 2026-10-07):
+
+- **AbCip: an absent key resolves to the node default, `Native` unless pinned.** Precedence (one place,
+  `AbCipTransportResolver`, shared by driver, probe and CLI): explicit per-driver key → node-level appsetting
+  **`Drivers:AbCip:DefaultTransport`** (`Native` | `Libplctag`, env `Drivers__AbCip__DefaultTransport`,
+  `AbCipDriverDefaultsOptions`; a bad value **fails host start**) → compiled `Native`. Bound unconditionally
+  because the driver factory AND the admin-node Test Connect probe both read it. ⚠️ So **the upgrade restart
+  alone moves no-key AbCip drivers to Native**; to stay on libplctag, set the node key — NOT a per-driver key
+  through the old AdminUI, whose typed form drops unknown keys (#576). Evidence: AbCip reads proven on a real
+  CompactLogix (Z-35162, read-only); AbCip writes are `ab_server`-only.
+- **AbLegacy: an absent key resolves to `Libplctag` for every family; `Native` is opt-in** (no node key). On
+  a wire the native PCCC path is proven only for **N-file reads/writes and one F8 read**, all on `ab_server`;
+  `S:0` (the default probe), B/T/C/R/S/L/ST/A/O/I and the T/C/R sub-element offsets are encoded from the PCCC
+  table and **unverified natively**. Explicit Native on PLC-5/`LogixPccc` logs a once-per-instance Warning.
+  AbLegacy native refuses status-bit sub-element writes (`T4:0.DN`…, `BadNotSupported`) and its ST byte order
+  is unverified.
+
+Refusals are not comms faults: an Unsupported refusal (`BadNotSupported`) and an AbCip native **type
+mismatch** (`BadTypeMismatch`, where libplctag returned Good garbage for a same-width mis-authored type) both
+keep the tag handle, leave driver health alone (no `Degraded`, nothing for the comms-loss watchdog) and warn
+once per tag — only genuine transport failures evict and degrade. `DeviceSessionPool.Shared` logs through the
+host logger factory (wired in `DriverFactoryBootstrap`). libplctag is confined to `Libplctag*.cs` adapters by
+`LibplctagConfinementGuardTests`; do not reference it elsewhere. See `docs/drivers/AbCip.md` §Transport,
+`docs/drivers/AbLegacy.md` §Transport + §Wire evidence, `docs/Configuration.md` §`Drivers:AbCip`, and
 `docs/plans/2026-10-07-native-ab-transport-gate-results.md`.
 
 ## Library Preferences