feat(siteruntime): event-driven Attributes.WaitAsync attribute-change helper

Adds InstanceActor one-shot waiter registry (fast-path + change-match + scheduled
timeout self-eviction), threads per-script timeout token through ScriptRuntimeContext,
and exposes Attributes.WaitAsync(value|predicate, timeout). Replaces handshake busy-poll.
Implements spec docs/plans/2026-06-17-waitfor-attribute-change-helper-spec.md §3-§5;
§6 routed variant + WaitForAsync + quality-only mode deferred.

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Actors/AlarmExecutionActor.cs

@@ -113,7 +113,12 @@ public class AlarmExecutionActor : ReceiveActor
                     // context's id as its ParentExecutionId — null today, so the
                     // run is a root, but the plumbing exists for a future
                     // firing id.
-                    parentExecutionId: parentExecutionId);
+                    parentExecutionId: parentExecutionId,
+                    // WaitForAttribute (spec §4.4): thread the alarm on-trigger
+                    // script's per-script execution-timeout token so a
+                    // Attributes.WaitAsync inside an on-trigger script is bounded
+                    // by the same script deadline.
+                    scriptTimeoutToken: cts.Token);
 
                 var globals = new ScriptGlobals
                 {

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Actors/InstanceActor.cs

@@ -68,6 +68,18 @@ public class InstanceActor : ReceiveActor
     // mirroring the rest of the actor's by-name dictionaries).
     private readonly Dictionary<string, ResolvedAttribute> _resolvedAttributeByName = new();
 
+    // WaitForAttribute (spec §4.2): one-shot waiter registry keyed by the
+    // request CorrelationId. Each entry holds the watched attribute name, the
+    // match test (decoded target equality OR a site-local predicate), the
+    // original Sender to reply to, and the scheduled-timeout handle so a match
+    // can cancel it. Single-threaded actor access — no locking needed.
+    private readonly Dictionary<string, PendingWait> _attributeWaiters = new();
+
+    // WaitForAttribute: defensive per-instance cap so a script leaking waiters
+    // in a loop cannot grow the registry without bound. Exceeding it refuses the
+    // wait with an error reply rather than registering.
+    private const int MaxAttributeWaiters = 100;
+
     // DCL manager actor reference for subscribing to tag values
     private readonly IActorRef? _dclManager;
     // Maps each tag path to every attribute canonical name that references it.
@@ -170,6 +182,12 @@ public class InstanceActor : ReceiveActor
         // WP-22/23: Handle attribute value changes from DCL (Tell pattern)
         Receive<AttributeValueChanged>(HandleAttributeValueChanged);
 
+        // WaitForAttribute (spec §4.2): event-driven "wait for value" waiter
+        // registration + its scheduled-timeout self-message. Both flow only
+        // site-locally (the predicate variant carries a non-serializable delegate).
+        Receive<WaitForAttributeRequest>(HandleWaitForAttribute);
+        Receive<WaitForAttributeTimeout>(HandleWaitForAttributeTimeout);
+
         // Handle tag value updates from DCL — convert to AttributeValueChanged
         Receive<TagValueUpdate>(HandleTagValueUpdate);
         Receive<SubscribeTagsResponse>(_ => { }); // Ack from DCL subscribe — no action needed
@@ -519,6 +537,80 @@ public class InstanceActor : ReceiveActor
         PublishAndNotifyChildren(changed);
     }
 
+    /// <summary>
+    /// WaitForAttribute (spec §4.2): registers a one-shot event-driven waiter for
+    /// an attribute to reach a value (encoded-equality), satisfy a site-local
+    /// predicate, or change at all. The current-value fast-path and the
+    /// change-handling in <see cref="HandleAttributeValueChanged"/> both run on
+    /// this single-threaded actor, so a value that flips between "read current"
+    /// and "register" cannot be missed (spec §5).
+    /// </summary>
+    private void HandleWaitForAttribute(WaitForAttributeRequest req)
+    {
+        // Capture the sender immediately — Sender is invalid once we schedule /
+        // return and a later message arrives.
+        var replyer = Sender;
+
+        // Build the match test: explicit predicate wins; else null encoded target
+        // means "any change"; else compare the codec-encoded current value to the
+        // encoded target (avoids needing the attribute's DataType to decode).
+        Func<object?, bool> test;
+        if (req.Predicate is not null)
+        {
+            test = req.Predicate;
+        }
+        else if (req.TargetValueEncoded is null)
+        {
+            test = _ => true;
+        }
+        else
+        {
+            var target = req.TargetValueEncoded;
+            test = v => string.Equals(
+                AttributeValueCodec.Encode(v), target, StringComparison.Ordinal);
+        }
+
+        // Fast path: the current value already satisfies the test → reply now.
+        if (_attributes.TryGetValue(req.AttributeName, out var current) && test(current))
+        {
+            _attributeQualities.TryGetValue(req.AttributeName, out var quality);
+            replyer.Tell(new WaitForAttributeResponse(
+                req.CorrelationId, Matched: true, current, quality ?? "Good", TimedOut: false));
+            return;
+        }
+
+        // Defensive cap: refuse rather than register if the instance already has
+        // too many concurrent waiters (guards against a script leaking waiters).
+        if (_attributeWaiters.Count >= MaxAttributeWaiters)
+        {
+            replyer.Tell(new WaitForAttributeResponse(
+                req.CorrelationId, Matched: false, null, "", TimedOut: false,
+                ErrorMessage: "Too many concurrent attribute waiters on this instance"));
+            return;
+        }
+
+        // Register and schedule the self-evicting timeout (NativeAlarmActor idiom).
+        var handle = Context.System.Scheduler.ScheduleTellOnceCancelable(
+            req.Timeout, Self, new WaitForAttributeTimeout(req.CorrelationId), Self);
+
+        _attributeWaiters[req.CorrelationId] =
+            new PendingWait(req.AttributeName, test, replyer, handle);
+    }
+
+    /// <summary>
+    /// WaitForAttribute (spec §4.2): the scheduled timeout fired for a waiter that
+    /// never matched. If still registered (a match would have removed + canceled
+    /// it), reply TimedOut and evict it.
+    /// </summary>
+    private void HandleWaitForAttributeTimeout(WaitForAttributeTimeout msg)
+    {
+        if (_attributeWaiters.Remove(msg.CorrelationId, out var pending))
+        {
+            pending.Replyer.Tell(new WaitForAttributeResponse(
+                msg.CorrelationId, Matched: false, null, "", TimedOut: true));
+        }
+    }
+
     /// <summary>
     /// Handles tag value updates from DCL. Maps the tag path back to the attribute
     /// canonical name and converts to an AttributeValueChanged for unified processing.
@@ -924,6 +1016,41 @@ public class InstanceActor : ReceiveActor
         {
             alarmActor.Tell(changed);
         }
+
+        // WaitForAttribute (spec §4.2): re-evaluate any waiters on THIS attribute.
+        // PublishAndNotifyChildren is THE single choke point for every value change
+        // — both the DCL ingest path (HandleAttributeValueChanged) and the static
+        // write path (HandleSetStaticAttributeCore) call it AFTER updating
+        // _attributes, so changed.Value is the just-applied current value. Iterate a
+        // snapshot so satisfied waiters can be removed during the loop; each match
+        // cancels its scheduled timeout (so no stray WaitForAttributeTimeout follows)
+        // and replies Matched=true.
+        ResolveMatchedWaiters(changed);
+    }
+
+    /// <summary>
+    /// WaitForAttribute (spec §4.2): fires every registered waiter on
+    /// <paramref name="changed"/>'s attribute whose test now passes against the
+    /// just-applied value — cancelling its timeout, replying Matched, and removing
+    /// it from the registry. A no-op when there are no waiters.
+    /// </summary>
+    private void ResolveMatchedWaiters(AttributeValueChanged changed)
+    {
+        if (_attributeWaiters.Count == 0)
+            return;
+
+        var matched = _attributeWaiters
+            .Where(kvp => kvp.Value.AttributeName == changed.AttributeName
+                          && kvp.Value.Test(changed.Value))
+            .ToList();
+
+        foreach (var (cid, pending) in matched)
+        {
+            pending.Timeout.Cancel();
+            pending.Replyer.Tell(new WaitForAttributeResponse(
+                cid, Matched: true, changed.Value, changed.Quality, TimedOut: false));
+            _attributeWaiters.Remove(cid);
+        }
     }
 
     /// <summary>
@@ -1202,4 +1329,17 @@ public class InstanceActor : ReceiveActor
     /// Internal message for async override loading result.
     /// </summary>
     internal record LoadOverridesResult(Dictionary<string, string> Overrides, string? Error);
+
+    /// <summary>
+    /// WaitForAttribute (spec §4.2): one registered, not-yet-satisfied waiter.
+    /// </summary>
+    /// <param name="AttributeName">The attribute this waiter watches (scope-resolved).</param>
+    /// <param name="Test">The match test (decoded-target equality OR site-local predicate OR any-change).</param>
+    /// <param name="Replyer">The original sender to reply to on match / timeout.</param>
+    /// <param name="Timeout">The scheduled timeout handle, canceled on match.</param>
+    private sealed record PendingWait(
+        string AttributeName,
+        Func<object?, bool> Test,
+        IActorRef Replyer,
+        ICancelable Timeout);
 }

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Actors/ScriptExecutionActor.cs

@@ -221,7 +221,12 @@ public class ScriptExecutionActor : ReceiveActor
                     // M2.12 (#25): thread the singleton site event logger so
                     // recursion-limit violations at CallScript/CallShared emit a
                     // script Error site event in addition to ILogger.LogError.
-                    siteEventLogger: siteEventLogger);
+                    siteEventLogger: siteEventLogger,
+                    // WaitForAttribute (spec §4.3/§4.4): thread the per-script
+                    // execution-timeout token so Attributes.WaitAsync's Ask is
+                    // bounded by the script's own ExecutionTimeoutSeconds — a
+                    // shorter script deadline wins over the wait's own timeout.
+                    scriptTimeoutToken: cts.Token);
 
                 var globals = new ScriptGlobals
                 {

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

@@ -73,6 +73,35 @@ public class AttributeAccessor
     /// <returns>A task that represents the asynchronous operation.</returns>
     public Task SetAsync(string key, object? value)
         => _ctx.SetAttribute(Resolve(key), AttributeValueCodec.Encode(value) ?? string.Empty);
+
+    /// <summary>
+    /// WaitForAttribute (spec §3-§5): waits event-driven until the attribute equals
+    /// <paramref name="targetValue"/> (value-equality, codec-normalized), bounded by
+    /// <paramref name="timeout"/>. Returns <c>true</c> if matched within the timeout,
+    /// <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"/>.
+    /// </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="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)
+        => _ctx.WaitAttribute(Resolve(key), AttributeValueCodec.Encode(targetValue), null, timeout);
+
+    /// <summary>
+    /// WaitForAttribute (spec §3-§5): predicate form — waits event-driven until
+    /// <paramref name="predicate"/> returns <c>true</c> for the attribute's current
+    /// 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.
+    /// </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>
+    /// <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, Func<object?, bool> predicate, TimeSpan timeout)
+        => _ctx.WaitAttribute(Resolve(key), null, predicate, timeout);
 }
 
 /// <summary>

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

@@ -46,6 +46,16 @@ public class ScriptRuntimeContext
     private readonly ILogger _logger;
     private readonly string _instanceName;
 
+    /// <summary>
+    /// WaitForAttribute (spec §4.3): the per-script execution-timeout token from
+    /// the owning <c>ScriptExecutionActor</c>/<c>AlarmExecutionActor</c>
+    /// (<c>cts.Token</c>). Bounds the <c>Attributes.WaitAsync</c> Ask so a script
+    /// that hits its own <c>ExecutionTimeoutSeconds</c> abandons the wait. Defaults
+    /// to <see cref="CancellationToken.None"/> for contexts that do not thread one
+    /// (legacy callers / tests / the alarm path when it has no CTS).
+    /// </summary>
+    private readonly CancellationToken _scriptTimeoutToken;
+
     /// <summary>
     /// WP-13: External system client for ExternalSystem.Call/CachedCall.
     /// </summary>
@@ -194,6 +204,13 @@ public class ScriptRuntimeContext
     /// <c>ILogger.LogError</c> + throw. When null the existing behaviour is
     /// unchanged; all existing callers and tests remain source-compatible.
     /// </param>
+    /// <param name="scriptTimeoutToken">
+    /// WaitForAttribute (spec §4.3): the per-script execution-timeout token
+    /// (<c>cts.Token</c> on the owning execution actor) used to bound
+    /// <c>Attributes.WaitAsync</c>. Defaults to
+    /// <see cref="CancellationToken.None"/> for callers / tests that do not
+    /// thread one — those waits are bounded only by their own timeout.
+    /// </param>
     public ScriptRuntimeContext(
         IActorRef instanceActor,
         IActorRef self,
@@ -215,7 +232,8 @@ public class ScriptRuntimeContext
         Guid? executionId = null,
         Guid? parentExecutionId = null,
         string? sourceNode = null,
-        ISiteEventLogger? siteEventLogger = null)
+        ISiteEventLogger? siteEventLogger = null,
+        CancellationToken scriptTimeoutToken = default)
     {
         _instanceActor = instanceActor;
         _self = self;
@@ -245,6 +263,9 @@ public class ScriptRuntimeContext
         _parentExecutionId = parentExecutionId;
         // M2.12 (#25): optional — null when not wired (tests / AlarmExecutionActor).
         _siteEventLogger = siteEventLogger;
+        // WaitForAttribute (spec §4.3): default(CancellationToken) == None when
+        // not threaded in — the WaitAsync Ask is then bounded only by its own timeout.
+        _scriptTimeoutToken = scriptTimeoutToken;
     }
 
     /// <summary>
@@ -297,7 +318,11 @@ public class ScriptRuntimeContext
             // …parented to THIS run's execution id (the spawner).
             parentExecutionId: _executionId,
             sourceNode: _sourceNode,
-            siteEventLogger: _siteEventLogger);
+            siteEventLogger: _siteEventLogger,
+            // WaitForAttribute (spec §4.3): an inline shared-script call shares the
+            // parent run's execution-timeout token so a WaitAsync inside the shared
+            // script is bounded by the SAME script deadline.
+            scriptTimeoutToken: _scriptTimeoutToken);
     }
 
     /// <summary>
@@ -360,6 +385,42 @@ public class ScriptRuntimeContext
         return response.Value;
     }
 
+    /// <summary>
+    /// WaitForAttribute (spec §3-§5): waits event-driven for an attribute to reach
+    /// a value (encoded-equality), satisfy a site-local predicate, or change at all,
+    /// bounded by <paramref name="timeout"/>. Returns <c>true</c> if matched within
+    /// the timeout, <c>false</c> on timeout — NEVER throws on timeout. The backing
+    /// <c>Attributes.WaitAsync</c> for the accessor.
+    ///
+    /// <para>
+    /// The Ask is bounded by the script's own execution-timeout token (§4.3): a
+    /// script that hits its <c>ExecutionTimeoutSeconds</c> abandons the wait. The
+    /// Ask timeout is the wait timeout plus a small <see cref="_askTimeout"/> slack
+    /// so the InstanceActor's own scheduled timeout reply is the authoritative path
+    /// for the false/timed-out outcome, not the Ask deadline.
+    /// </para>
+    /// </summary>
+    /// <param name="name">The scope-resolved attribute name to wait on.</param>
+    /// <param name="targetValueEncoded">
+    /// The codec-encoded target value; null (with null <paramref name="predicate"/>)
+    /// means "any change".
+    /// </param>
+    /// <param name="predicate">Site-local predicate; null when the encoded target is used.</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 async Task<bool> WaitAttribute(
+        string name, string? targetValueEncoded, Func<object?, bool>? predicate, TimeSpan timeout)
+    {
+        var cid = Guid.NewGuid().ToString();
+        var req = new WaitForAttributeRequest(
+            cid, _instanceName, name, targetValueEncoded, predicate, timeout, DateTimeOffset.UtcNow);
+
+        var resp = await _instanceActor.Ask<WaitForAttributeResponse>(
+            req, timeout + _askTimeout, _scriptTimeoutToken);
+
+        return resp.Matched;
+    }
+
     /// <summary>
     /// Sets an attribute value. For data-connected attributes the Instance Actor
     /// forwards the write to the DCL, which writes the physical device; the