docs(r2-01): mark EnsureConnectedAsync as the R2-09 connect-throttle seam (STAB-8 note, task 10)

2026-07-13 10:04:22 -04:00
parent 8999c722a0
commit 92b2ac4891
2 changed files with 10 additions and 1 deletions
@@ -1211,6 +1211,15 @@ public sealed class S7Driver
    ///     MUST be called while holding <see cref="_gate"/> — it mutates <see cref="Plc"/> /
    ///     <see cref="_plcDead"/> and reuses the single-connection-per-PLC invariant the gate
    ///     enforces. The read / write / probe paths all take the gate before calling it.
+    ///     <para>
+    ///         While the PLC is down every data call and probe tick pays a full connect attempt
+    ///         bounded only by <c>_options.Timeout</c> (STAB-8). This method is the single
+    ///         choke-point all S7 reconnects flow through (already gate-serialized), so the
+    ///         fleet-wide connect-attempt throttle planned in R2-09 plugs in here: a
+    ///         last-failed-attempt timestamp checked at the top of the slow path. Deliberately NOT
+    ///         implemented driver-locally — see
+    ///         <c>archreview/plans/R2-01-s7-fault-hardening-plan.md</c> Finding 3.
+    ///     </para>
    /// </remarks>
    /// <param name="ct">Cancellation token for the (re)connect attempt.</param>
    /// <returns>A live <see cref="IS7Plc"/>.</returns>