fix(scripts): reset-aware handshake refuses a null reset value; document additive timeouts (#36 review)

A null resetValue encoded to null, which wrote an empty string and then handed the
waiter a null target (= any change), fast-pathing on the stale cache and reinstating
the race the overload exists to close. The context parameter is now non-nullable and
the accessor throws ArgumentException before any write. Also: additive-timeout note on
all surfaces, batch-failure message no longer names the bool overload, and the
error-message/batch-failure branches are pinned.

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

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Scripts/ScopeAccessors.cs

@@ -122,7 +122,10 @@ public class AttributeAccessor
     /// flag handshake: without an observed reset the plain overload can be satisfied
     /// instantly by the previous run's cached response value. Throws
     /// <see cref="System.InvalidOperationException"/> if the reset write or the batch/trigger
-    /// write itself fails; never throws on either timeout.
+    /// write itself fails; never throws on either timeout. The two waits are ADDITIVE — the call
+    /// can run for <paramref name="resetTimeout"/> + <paramref name="timeout"/> plus Ask slack, so
+    /// size the script's <c>ExecutionTimeoutSeconds</c> above that sum: a deadline hit mid-leg
+    /// propagates as cancellation (spec §4.3), not as a <see cref="HandshakeResult"/>.
     /// </summary>
     /// <param name="values">Attribute key → value to batch-write (data-sourced, one connection).</param>
     /// <param name="flagKey">Trigger attribute key written AFTER the batch.</param>
@@ -131,7 +134,12 @@ public class AttributeAccessor
     /// <param name="responseValue">Target value to wait for (<c>null</c> ⇒ any change).</param>
     /// <param name="timeout">How long to wait for the response before giving up.</param>
     /// <param name="resetKey">Attribute written FIRST (usually <paramref name="responseKey"/>); static or data-sourced.</param>
-    /// <param name="resetValue">Value the device must echo back before the batch is written.</param>
+    /// <param name="resetValue">
+    /// Value the device must echo back before the batch is written. MUST NOT be null: a null encodes
+    /// to null, which would write an empty string and then wait on "any change", fast-pathing on the
+    /// stale cached value and reinstating the race this overload exists to close —
+    /// <see cref="System.ArgumentException"/> is thrown before anything is written.
+    /// </param>
     /// <param name="resetTimeout">How long to wait for the reset echo; <c>null</c> ⇒ <paramref name="timeout"/>.</param>
     /// <returns>The phase-aware handshake outcome.</returns>
     public Task<HandshakeResult> WriteBatchAndWaitAsync(
@@ -148,7 +156,11 @@ public class AttributeAccessor
             Resolve(flagKey), AttributeValueCodec.Encode(flagValue),
             Resolve(responseKey), AttributeValueCodec.Encode(responseValue),
             timeout,
-            Resolve(resetKey), AttributeValueCodec.Encode(resetValue),
+            Resolve(resetKey),
+            AttributeValueCodec.Encode(resetValue)
+                ?? throw new ArgumentException(
+                    "A reset-aware handshake needs a definite reset value: null would write an " +
+                    "empty string and then match on any change.", nameof(resetValue)),
             resetTimeout ?? timeout);
     }
 

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Scripts/ScriptRuntimeContext.cs

@@ -985,6 +985,12 @@ public class ScriptRuntimeContext
     /// would never resolve at all. Holding the trigger until the echo lands makes the existing
     /// level-triggered fast-path correct again. Each leg is already a traced Flow Debugger
     /// step, so a traced run shows all four.
+    /// <para>
+    /// The two waits are ADDITIVE: the call can run for <paramref name="resetTimeout"/> +
+    /// <paramref name="timeout"/> plus Ask slack, so size the script's
+    /// <c>ExecutionTimeoutSeconds</c> above that sum — a script deadline hit mid-leg propagates
+    /// as cancellation (spec §4.3), not as a <see cref="HandshakeResult"/>.
+    /// </para>
     /// </remarks>
     /// <param name="encodedValues">Scope-resolved attribute name → codec-encoded value to batch-write.</param>
     /// <param name="triggerAttr">Scope-resolved trigger attribute written AFTER the batch.</param>
@@ -993,17 +999,22 @@ public class ScriptRuntimeContext
     /// <param name="responseEncoded">Codec-encoded response target (null ⇒ any change).</param>
     /// <param name="timeout">Bound for the response wait.</param>
     /// <param name="resetAttr">Scope-resolved attribute written FIRST (usually the response attribute).</param>
-    /// <param name="resetEncoded">Codec-encoded reset value the device must echo before anything else is written.</param>
+    /// <param name="resetEncoded">
+    /// Codec-encoded reset value the device must echo before anything else is written. NON-NULL by
+    /// contract: a null would write an empty string on leg 1 and then give the leg-2 waiter a null
+    /// target — "any change" — which fast-paths on the stale cached value and reinstates the very
+    /// race this overload exists to close. The accessor rejects a null reset value before it gets here.
+    /// </param>
     /// <param name="resetTimeout">Bound for the reset-echo wait.</param>
     /// <returns>A phase-aware result; never throws on either timeout.</returns>
     public async Task<HandshakeResult> WriteBatchResetAndWait(
         IReadOnlyDictionary<string, string?> encodedValues, string triggerAttr, string? triggerEncoded,
         string responseAttr, string? responseEncoded, TimeSpan timeout,
-        string resetAttr, string? resetEncoded, TimeSpan resetTimeout)
+        string resetAttr, string resetEncoded, TimeSpan resetTimeout)
     {
         // Leg 1 — reset write. A static attribute updates the cache synchronously (leg 2 then
         // fast-paths); a data-sourced one goes to the device and the cache waits for the echo.
-        await SetAttribute(resetAttr, resetEncoded ?? string.Empty).ConfigureAwait(false);
+        await SetAttribute(resetAttr, resetEncoded).ConfigureAwait(false);
 
         // Leg 2 — reset echo. Quality-agnostic, like the response wait.
         var reset = await WaitInternal(resetAttr, resetEncoded, null, resetTimeout, requireGoodQuality: false)
@@ -1084,7 +1095,7 @@ public class ScriptRuntimeContext
 
         if (!batchResp.Success)
             throw new InvalidOperationException(
-                $"WriteBatchAndWait write failed: {batchResp.ErrorMessage}");
+                $"Batch write failed: {batchResp.ErrorMessage}");
 
         return await WaitInternal(responseAttr, responseEncoded, null, timeout, requireGoodQuality: false)
             .ConfigureAwait(false);