fix(siteruntime): harden WaitAsync — no spurious match on quality republish, guard throwing predicate, Ask-timeout returns false

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

@@ -81,9 +81,24 @@ public class AttributeAccessor
     /// <c>false</c> on timeout (no throw). Honors the script's execution-timeout token.
     /// Scope/composition path resolution (<see cref="Resolve"/>) is applied just like
     /// <see cref="GetAsync"/> / <see cref="SetAsync"/>.
+    ///
+    /// <para>
+    /// <b>Quality-agnostic by default (spec §4.2):</b> matching tests the VALUE, not
+    /// the quality — a value arriving at Bad quality still satisfies the wait. A
+    /// quality-gated ("Good"-only) mode is a planned enhancement, deferred per spec §4.2.
+    /// </para>
+    ///
+    /// <para>
+    /// Passing a <b>null</b> <paramref name="targetValue"/> means "match on any change":
+    /// the wait then matches the next value the attribute receives — and matches
+    /// IMMEDIATELY (fast-path) if the attribute already holds any value at registration.
+    /// </para>
     /// </summary>
     /// <param name="key">The attribute key (scope-resolved before the wait is registered).</param>
-    /// <param name="targetValue">The value to wait for (codec-encoded for comparison).</param>
+    /// <param name="targetValue">
+    /// The value to wait for (codec-encoded for comparison); <c>null</c> means
+    /// "match on any change" (matches immediately if the attribute already has a value).
+    /// </param>
     /// <param name="timeout">How long to wait before returning false.</param>
     /// <returns><c>true</c> on match within the timeout; <c>false</c> on timeout.</returns>
     public Task<bool> WaitAsync(string key, object? targetValue, TimeSpan timeout)
@@ -95,6 +110,13 @@ public class AttributeAccessor
     /// value, bounded by <paramref name="timeout"/>. Site-local only (the predicate
     /// is an in-process delegate). Returns <c>true</c> if matched within the timeout,
     /// <c>false</c> on timeout (no throw). Scope/composition path resolution applies.
+    ///
+    /// <para>
+    /// <b>Quality-agnostic by default (spec §4.2):</b> the predicate is tested against
+    /// the VALUE, regardless of quality — a value arriving at Bad quality still
+    /// satisfies the wait if the predicate passes. A quality-gated ("Good"-only) mode
+    /// is a planned enhancement, deferred per spec §4.2.
+    /// </para>
     /// </summary>
     /// <param name="key">The attribute key (scope-resolved before the wait is registered).</param>
     /// <param name="predicate">The site-local predicate tested against the current value.</param>