# Patch request — event-driven "wait for attribute change (with timeout)" script helper

**Date:** 2026-06-17
**Type:** Source enhancement (small, additive) to the SiteRuntime script surface
**Why now:** the DELMIA/MES receiver re-implementation
([`2026-06-17-delmia-mes-receiver-templates-design.md`](2026-06-17-delmia-mes-receiver-templates-design.md), §9 risk #1)
currently has to **busy-poll** for the handshake completion flag. This spec describes the gap
and a precise, patch-ready design for a host-provided `WaitAsync` helper so scripts can wait
**event-driven** for a tag/attribute to reach a value, bounded by a timeout.

> All file paths, line numbers, message records, and signatures below were read from source on
> 2026-06-17. Treat line numbers as guides (they drift); the type/method names are the anchors.

---

## 1. The gap

The receiver handshake (and any request/response tag interaction) needs to **wait until a
data-sourced attribute reaches a value** — e.g. wait up to 30 s for `RecipeProcessedFlag == true`
or `MoveInCompleteFlag == true` after setting the trigger flag.

ScadaBridge's script surface today has **read** (`Attributes.GetAsync` / indexer) and **write**
(`Attributes.SetAsync` / indexer), but **no "wait for value" primitive**. The only way to wait is
a manual poll loop:

```csharp
// current workaround — every handshake script repeats this
var deadline = DateTime.UtcNow.AddSeconds(30);
while (DateTime.UtcNow < deadline && !CancellationToken.IsCancellationRequested)
{
    if ((bool?)(await Attributes.GetAsync("RecipeProcessedFlag")) == true) break;
    await Task.Delay(200, CancellationToken);
}
```

Why this is unsatisfactory:

- **Latency** — completion is detected up to one poll interval late (200 ms here).
- **Wasted work** — each iteration is an actor `Ask` (`GetAttributeRequest` round-trip to the
  `InstanceActor`); N handshakes × M polls = a lot of needless messages.
- **Boilerplate** — the same loop is copy-pasted into every handshake script, easy to get wrong
  (forgetting `CancellationToken`, off-by-one on the deadline, not handling quality).
- **No quality awareness** — the poll reads whatever value is cached regardless of OPC/MX quality.

Crucially, **the data is already being pushed to the actor that owns it.** A data-sourced
attribute's value arrives from the DCL and is applied in the `InstanceActor`, which then raises
`AttributeValueChanged`. So an event-driven waiter is natural and removes the poll entirely.

---

## 2. Where the change goes (verified wiring)

| Concern | Type / file | Notes |
|---|---|---|
| Change notification | `AttributeValueChanged(InstanceUniqueName, AttributePath, AttributeName, Value, Quality, Timestamp)` — `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Streaming/AttributeValueChanged.cs` | raised on **every** change |
| **Single choke point** | `InstanceActor.HandleAttributeValueChanged(...)` — `src/…/SiteRuntime/Actors/InstanceActor.cs` | both static writes (`HandleSetStaticAttributeCore`) **and** DCL/subscription updates (`HandleTagValueUpdate` ← `TagValueUpdate`) funnel through here, then `PublishAndNotifyChildren` |
| Owner of state | `InstanceActor` (`_attributes`, `_attributeQualities`, `_attributeTimestamps`) | **single-threaded** — registration + current-value check is atomic here |
| Script read path | `AttributeAccessor` (`ScopeAccessors.cs`) → `ScriptRuntimeContext.GetAttribute` → `Ask<GetAttributeResponse>(GetAttributeRequest)` | the helper mirrors this |
| Script globals build | `ScriptExecutionActor` (`src/…/SiteRuntime/Actors/ScriptExecutionActor.cs`) builds `ScriptRuntimeContext` (passes `instanceActor`, `self`, `_askTimeout`) and `ScriptGlobals` (`CancellationToken = cts.Token` from the per-script timeout) | **the script timeout token is NOT currently passed into `ScriptRuntimeContext`** — this patch must thread it in |
| Helper idiom | `ScriptRuntimeContext` nested helpers (e.g. `ExternalSystemHelper`) — ctor deps stored as readonly fields, exposed via an on-demand property | follow this idiom |
| Trust model | `ScriptTrustPolicy` (`src/…/ScriptAnalysis/`) | `System.Threading.Tasks` + `CancellationToken`/`CancellationTokenSource` are in `AllowedExceptions`; lambdas/`Func<>` are fine. **No trust change needed** — the wait runs in host code; the script just `await`s a provided method. |

**Design principle:** do the wait **inside the `InstanceActor`** as a one-shot registered waiter,
not in the script via polling. Because the actor is single-threaded and `HandleAttributeValueChanged`
is the one place every change passes, a waiter that (a) checks the current value on registration and
(b) is re-evaluated on each change **cannot miss the edge** between "read current" and "subscribe".

---

## 3. Proposed API (script-facing)

Add to the `Attributes` accessor (`AttributeAccessor` in `ScopeAccessors.cs`), so scope/composition
path resolution (`Resolve(name)`) applies just like get/set:

```csharp
// Wait until `name` equals targetValue (value-equality, codec-normalized). Returns true if matched
// within the timeout, false if it timed out. Honors the script CancellationToken.
Task<bool> Attributes.WaitAsync(string name, object? targetValue, TimeSpan timeout);

// Predicate form — site-local template scripts only (predicate is an in-process delegate).
Task<bool> Attributes.WaitAsync(string name, Func<object?, bool> predicate, TimeSpan timeout);

// Optional richer overload that also returns the matched value + quality.
Task<WaitResult> Attributes.WaitForAsync(string name, object? targetValue, TimeSpan timeout);
// record WaitResult(bool Matched, object? Value, string? Quality, bool TimedOut);
```

> **Status:** IMPLEMENTED. `Attributes.WaitForAsync(...)` returns a `WaitResult`
> (`readonly record struct WaitResult(bool Matched, object? Value, string? Quality, bool TimedOut)`
> in Commons), populated on match (Value + Quality) and `Matched:false, TimedOut:true` on timeout.

Return **bool** (not throw) for the common case — the handshake wants matched/timed-out, not an
exception. The value-equality overload is the one the handshake needs and is the one that can also
be exposed on the inbound/routed side (§6), because a value serializes and a delegate does not.

Handshake, rewritten (replaces the §1 poll loop):

```csharp
await Attributes.SetAsync("RecipeDownloadFlag", true);                 // trigger
var ok = await Attributes.WaitAsync("RecipeProcessedFlag", true, TimeSpan.FromSeconds(30));
if (!ok) return new { Result = false, ResultText = "Timeout waiting for recipe to be processed" };
return new {
    Result     = (bool?)(await Attributes.GetAsync("RecipeProcessResult")) ?? false,
    ResultText = (string?)(await Attributes.GetAsync("RecipeProcessResultText")) ?? ""
};
```

```csharp
await Attributes.SetAsync("MoveInFlag", true);
var ok = await Attributes.WaitAsync("MoveInCompleteFlag", true, TimeSpan.FromSeconds(30));
// … read MoveInSuccessfulFlag / MoveInErrorText / MoveInBatchID …
```

---

## 4. Implementation outline (the patch)

### 4.1 New messages (`src/ZB.MOM.WW.ScadaBridge.Commons/Messages/…`)
```csharp
// actor protocol (site-local; delegate is fine because messaging is in-process)
public record WaitForAttributeRequest(
    string  CorrelationId,
    string  InstanceName,
    string  AttributeName,            // already scope-resolved by the accessor
    string? TargetValueEncoded,       // AttributeValueCodec.Encode(targetValue); null = "any change"
    Func<object?, bool>? Predicate,   // local-only; null when TargetValueEncoded is used
    TimeSpan Timeout,
    DateTimeOffset OccurredAtUtc);

public record WaitForAttributeResponse(
    string CorrelationId,
    bool   Matched,
    object? Value,
    string Quality,
    bool   TimedOut,
    string? ErrorMessage = null);

// internal self-message used to fire the timeout
public record WaitForAttributeTimeout(string CorrelationId);
```

### 4.2 `InstanceActor` (`src/…/SiteRuntime/Actors/InstanceActor.cs`)
- Add a registry: `Dictionary<string, PendingWait> _attributeWaiters` keyed by `CorrelationId`, where
  `PendingWait` holds the attribute name, the match test (decoded target value **or** predicate),
  the original `Sender` (`IActorRef`), and the scheduled `ICancelable` timeout handle.
- **Handle `WaitForAttributeRequest`:**
  1. Build the match test (decode `TargetValueEncoded` via `AttributeValueCodec` → equality test, or
     use `Predicate`).
  2. **Fast path:** if the current `_attributes[name]` already satisfies the test, reply
     `WaitForAttributeResponse(Matched: true, Value, Quality)` immediately and return.
  3. Otherwise register the waiter and schedule the timeout:
     `Context.System.Scheduler.ScheduleTellOnce(effectiveTimeout, Self, new WaitForAttributeTimeout(cid), Self)`,
     storing the returned `ICancelable`. Capture `Sender` now (it is invalid later).
  4. Bound `effectiveTimeout = min(request.Timeout, requestDeadlineFromCaller)` (the caller's `Ask`
     already carries the script token; see §4.3). Optionally cap the number of concurrent waiters
     per instance (defensive; reply with `ErrorMessage` if exceeded).
- **In `HandleAttributeValueChanged` (after state is updated):** iterate `_attributeWaiters` whose
  attribute matches the changed `AttributeName`; for any whose test now passes, cancel its timeout,
  reply `WaitForAttributeResponse(Matched: true, …)`, and remove it. (Iterate over a snapshot to
  allow removal during enumeration.)
- **Handle `WaitForAttributeTimeout`:** if still registered, reply
  `WaitForAttributeResponse(Matched: false, TimedOut: true)` and remove.
- Optional: a `quality == "Good"`-only mode (parameter on the request) if a handshake must ignore
  Bad-quality transients.

> **Status:** IMPLEMENTED as an opt-in `requireGoodQuality` parameter on `WaitAsync`/`WaitForAsync`
> (additive trailing `RequireGoodQuality` field on `WaitForAttributeRequest`, gated at both the
> fast-path and resolve-loop match sites). Default `false` = quality-agnostic (matches on value only).

### 4.3 `ScriptRuntimeContext` (`src/…/SiteRuntime/Scripts/ScriptRuntimeContext.cs`)
- **Thread the script timeout token in.** Add a `CancellationToken scriptTimeoutToken` constructor
  parameter (today only `_askTimeout` is available to helpers; the per-script `cts.Token` is **not**
  passed). `ScriptExecutionActor` already has `cts.Token` — pass it when constructing the context.
- Add a method that the accessor calls:
  ```csharp
  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);
      // Ask bounded by the script timeout token so a script-deadline abort cancels the await.
      var resp = await _instanceActor.Ask<WaitForAttributeResponse>(
                     req, timeout + _askTimeout /* small slack */, _scriptTimeoutToken);
      return resp.Matched;
  }
  ```

### 4.4 `ScriptExecutionActor` (`src/…/SiteRuntime/Actors/ScriptExecutionActor.cs`)
- Pass `cts.Token` (the per-script timeout, created at the `new CancellationTokenSource(timeout)`
  site) into the new `ScriptRuntimeContext` constructor parameter from §4.3.

### 4.5 `AttributeAccessor` (`src/…/SiteRuntime/Scripts/ScopeAccessors.cs`)
```csharp
public Task<bool> WaitAsync(string key, object? targetValue, TimeSpan timeout)
    => _ctx.WaitAttribute(Resolve(key), AttributeValueCodec.Encode(targetValue), null, timeout);

public Task<bool> WaitAsync(string key, Func<object?, bool> predicate, TimeSpan timeout)
    => _ctx.WaitAttribute(Resolve(key), null, predicate, timeout);
```

### 4.6 Trust model — no change
`WaitAsync` is a host-provided async method; the wait/scheduling happens in host code. The script
only `await`s it and may pass a `Func<>` (a normal closure, not reflection). `System.Threading.Tasks`
+ `CancellationToken` are already in `ScriptTrustPolicy.AllowedExceptions`. Verify the new helper
type/members don't collide with `ForbiddenIdentifiers` (`dynamic`, `Activator`) — they don't.

---

## 5. Correctness notes

- **No missed edge.** Registration (current-value check) and change-handling both run on the
  `InstanceActor`'s single thread, so a value that flips between "set trigger" and "register waiter"
  is caught by the fast-path check; a value that flips after registration is caught by
  `HandleAttributeValueChanged`. The poll-loop and this design are both correct; this one is
  event-driven and cheaper.
- **Timeout is authoritative and self-cleaning.** The scheduled `WaitForAttributeTimeout` guarantees
  the waiter is removed and the caller answered even if the value never changes. Match cancels the
  scheduled timeout.
- **Cancellation.** Bounding the helper `Ask` with the script timeout token means a script that hits
  its own `ExecutionTimeoutSeconds` abandons the wait; pair with a best-effort cancel message to the
  actor to evict the orphan waiter promptly (otherwise it self-evicts at its own timeout).
- **Concurrency / re-entrancy.** Multiple waiters per instance are fine (keyed by `CorrelationId`).
  Consider a per-instance cap as a guard against a script leaking waiters in a loop.

---

## 6. Optional: inbound / routed variant

For symmetry with `RouteTarget.GetAttributes` (`src/…/InboundAPI/RouteHelper.cs`), an inbound script
could call `Route.To(code).WaitForAttribute(name, targetValue, timeout)`. Mirror the existing routed
pattern: add `RouteToWaitForAttributeRequest/Response`, an `IInstanceRouter.RouteToWaitForAttributeAsync`
method, and unpack it on the site comms actor into the same `WaitForAttributeRequest` to the
`InstanceActor`. **Value-equality only** across the wire — a `Func<>` predicate cannot be serialized,
so the routed form takes the encoded target value (the predicate overload stays site-local). This is
optional: the receiver handshake runs **inside** the template script (site-local), so §3–§5 alone
fully cover the DELMIA/MES use case.

> **Status:** IMPLEMENTED. `Route.To(code).WaitForAttribute(name, targetValue, timeout)` is wired
> end-to-end (`RouteToWaitForAttributeRequest/Response` → `IInstanceRouter` → `CommunicationService`
> → `SiteCommunicationActor` → `DeploymentManagerActor` → `InstanceActor`), value-equality only
> across the wire. ~~NOT wired into the CentralUI Test-Run sandbox — that remains a follow-up.~~
> **Follow-up SHIPPED 2026-07-10** — the CentralUI Test-Run sandbox is wired via
> `SandboxInstanceGateway`/`SandboxScriptHost` (deferred-work register row #14 resolved).

---

## 7. Acceptance criteria

1. A template script can `await Attributes.WaitAsync("Flag", true, TimeSpan.FromSeconds(30))` and it
   returns `true` promptly when the data-sourced attribute reaches `true` (driven by a DCL update),
   with no poll loop.
2. Returns `false` (no throw) when the value never matches within the timeout.
3. The wait is bounded by the script's own `ExecutionTimeoutSeconds` (a shorter script deadline wins).
4. No `AttributeValueChanged` edge is missed across the register/change boundary (unit test: flip the
   value in the same actor step as registration, and one step after).
5. Waiters are removed on match and on timeout (no leak; assert registry empty afterward).
6. Scope/composition path resolution works (`Children["DelmiaReceiver"]`-scoped wait resolves to the
   composed child's attribute).
7. Passes `ScriptAnalysis` trust validation unchanged.
8. The DELMIA/MES handshake base scripts (design doc §4) compile and pass using `WaitAsync` in place
   of the poll loop.

Suggested tests: extend `InstanceActor` tests (waiter fast-path, change-match, timeout, removal) and
the script-surface tests under `tests/…/SiteRuntime*`.
```
