lmxopcua/archreview/plans/R2-03-vt-failure-quality-plan.md

Design + Implementation Plan — R2-03: VT script-failure quality + cache-clear hardening

• Source report: archreview/02-scripting-alarms.md (2026-07-12 re-review)
• Review commit: f6eaa267 · Plan verified against tree at: f6eaa267 (master, clean)
• Scope: OVERALL prioritized action item #3 — "Publish Bad quality on VT script failure/timeout (match the dormant engine's BadInternalError); optionally gate the apply-boundary cache clear on changed scripts" — covering findings 02/S13 (Medium — failure/timeout never degrades node quality), 02/S12 (Medium — apply-boundary ClearCompiledScripts races in-flight child evaluations), and 02/P7 (Low — unconditional per-apply cache flush forces full VT recompilation on every deploy).
• Touches: Runtime/VirtualTags/VirtualTagActor.cs, Runtime/VirtualTags/VirtualTagHostActor.cs, Host/Engines/RoslynVirtualTagEvaluator.cs, Runtime.Tests/VirtualTags/*, Host.IntegrationTests/RoslynVirtualTagEvaluatorTests.cs. No Core.Scripting / Commons-contract / OPC UA-sink changes except one additive field on VirtualTagActor.EvaluationResult.

Verification summary

Every anchor in the three findings was opened at the cited file:line against the working tree at f6eaa267. All three findings CONFIRMED. One minor anchor drift (noted below); everything else is line-exact.

• S13 — Confirmed. VirtualTagActor.OnDependencyChanged returns without any publish on !result.Success (Runtime/VirtualTags/VirtualTagActor.cs:123-128) and on evaluator-threw (:115-121) — Warning ScriptLogEntry + fail metric only. The host bridge hard-codes OpcUaQuality.Good into every AttributeValueUpdate (Runtime/VirtualTags/VirtualTagHostActor.cs:179-180) and hard-codes 0u /* StatusCodes.Good */ into the historize snapshot (:187-188). EvaluationResult (VirtualTagActor.cs:23) carries no quality at all, so the child cannot express degradation today. Confirmed downstream that Bad quality is honored end to end once published: OpcUaPublishActor.HandleAttributeUpdate → IOpcUaAddressSpaceSink.WriteValue → OtOpcUaNodeManager.WriteValue (OpcUaServer/OtOpcUaNodeManager.cs:261-281) sets variable.StatusCode = StatusFromQuality(quality) + ClearChangeMasks, where StatusFromQuality (:2418-2423) maps Good→StatusCodes.Good, Uncertain→StatusCodes.Uncertain, _→StatusCodes.Bad. So the only missing plumbing is child → bridge.
• S13 anchor drift (minor): the report cites the dormant engine's failure mapping at VirtualTagEngine.cs:307,328. At f6eaa267, line 307 is the cold-start guard (BadWaitingForInitialData when inputs aren't ready yet — AreInputsReady); the actual failure→BadInternalError (0x80020000u) mappings are at 327-329 (uncoercible result), 334 (ScriptTimeoutException), and 343 (script threw). The substance of the finding is unaffected — and line 305-311 turns out to be load-bearing for this plan's design (the inputs-ready gate, below).
• S12 — Confirmed. VirtualTagHostActor.OnApply calls ClearCompiledScripts() first thing (VirtualTagHostActor.cs:92), on the host's dispatcher thread, with nothing gating concurrent child evaluations. The race window is inside one RoslynVirtualTagEvaluator.Evaluate call: the evaluator is fetched at RoslynVirtualTagEvaluator.cs:69 (_cache.GetOrCompile), the host's Clear() value-scoped-removes and disposes it (CompiledScriptCache.cs:113-116 → ScriptEvaluator.Dispose → _alc.Unload()), and the child's subsequent run (RoslynVirtualTagEvaluator.cs:108-109, via TimedScriptEvaluator.RunAsync's Task.Run) trips the disposed guard (ScriptEvaluator.cs:180) → ObjectDisposedException surfaces through GetAwaiter().GetResult() into the generic catch (Exception) (RoslynVirtualTagEvaluator.cs:116-120) → Failure("script threw: Cannot access a disposed object…") → dropped update (and, per S13, no quality degradation either). The contrast with ScriptedAlarmEngine holds: its per-generation _compileCache.Clear() (ScriptedAlarmEngine.cs:209) runs under _evalGate with upstream subscriptions already torn down, so no alarm evaluation can hold a disposed evaluator. The secondary wrinkle also confirmed: the clear runs before the removed/changed children are stopped (VirtualTagHostActor.cs:98-118) and Context.Stop is asynchronous, so a doomed child can recompile its stale expression into the fresh cache for one generation (bounded — not a leak). Note a mid-execution clear is safe: AssemblyLoadContext.Unload() is cooperative (the executing delegate keeps the ALC alive); only the guard at ScriptEvaluator.cs:180 — i.e. dispose landing between fetch and run-start — produces the dropped update. The Task.Run hop inside TimedScriptEvaluator widens exactly that window.
• P7 — Confirmed. The clear at VirtualTagHostActor.cs:92 is unconditional per ApplyVirtualTags, including a byte-identical redeploy whose plans all diff equal (the no-churn path proven by ApplyVirtualTags_does_not_respawn_child_when_plan_unchanged). The host already keeps last generation's plans in _planByVtag (:50, rebuilt at :160-164) — the comparison input for a conditional clear is already sitting in actor state. EquipmentVirtualTagPlan has element-wise value equality including Expression (OpcUaServer/AddressSpaceComposer.cs:179-188). The existing wiring guard VirtualTagHostActorTests.ApplyVirtualTags_clears_the_evaluator_compile_cache_each_generation asserts the clear fires on an identical second apply — that test encodes the P7 behavior and must be rewritten, not just kept green (called out in the task breakdown).
• Existing-test impact identified: VirtualTagActorTests.Evaluator_failure_publishes_ScriptLogEntry_warning ends with parent.ExpectNoMsg(...) — under the S13 fix a failure now does send the parent a Bad-quality EvaluationResult, so that assertion inverts (task R2-03-T3 updates it deliberately).
• Design constraint verified: the value fan-out's quality vocabulary is the coarse 3-value OpcUaQuality { Good, Uncertain, Bad } (Commons/OpcUa/IOpcUaAddressSpaceSink.cs:99) — there is no sub-code channel to the node, and AttributeValueUpdate (Runtime/OpcUa/OpcUaPublishActor.cs:42) already carries it. NullVirtualTagEvaluator returns NoChange (Success=true), so the dev/Mac path can never emit Bad. The passthrough fast-path returns Ok(null) for a missing dep (never Failure), so it is unaffected by all three fixes.

---

Priority ordering

Per the source report's Priority Recommendations (#1 = S13, #2 = S12) and OVERALL action item #3:

1. S13 (Medium, report's top item) — failure/timeout → node quality. The stale-Good repro test lands first and must fail on current code.
2. S12 (Medium) — close the clear-vs-in-flight-evaluate race (retry-once in the adapter).
3. P7 (Low) — gate the apply-boundary clear on an actually-changed script set.

All three are one PR (fix/archreview-r2-03-vt-failure-quality): S13 and S12 touch disjoint files; P7 touches the same OnApply region S13's bridge work sits next to.

---

1. S13 — MEDIUM — Script failure/timeout never degrades the OPC UA node's quality: stale value stays Good forever

Restatement: When a VT script evaluation fails (compile error, runtime throw, sandbox violation, or the U2-era timeout), VirtualTagActor logs + meters and returns without publishing anything, and the host bridge only ever publishes OpcUaQuality.Good. A previously-working script that starts failing leaves its node serving the last Good value with its old timestamp indefinitely — OPC UA clients, the continuous-historization recorder, and ScadaBridge cannot distinguish "healthy but unchanged" from "script broken for a week". The dormant VirtualTagEngine maps this correctly to BadInternalError; the live actor path never implemented it.

Verification: Confirmed (see summary). Bad quality is fully plumbed from AttributeValueUpdate through the sink to the SDK node — the gap is exactly VirtualTagActor (no quality concept) and the VirtualTagHostActor bridge (hard-coded Good at :179-180, hard-coded 0u historize status at :187-188).

Root cause: EvaluationResult was designed as a success-only message ("emit to the parent whenever the value actually changes"); failures were treated purely as an observability event (script-log + metric). The quality dimension was left to the materialiser's initial BadWaitingForInitialData and never revisited when the U2 remediation made timeouts a first-class, expected failure mode.

Proposed design:

(a) StatusCode policy — coarse OpcUaQuality.Bad for both failure and timeout. The node will read StatusCodes.Bad (0x80000000) via the existing StatusFromQuality mapping. This "matches the dormant engine's BadInternalError" at the level that matters — the severity bit that flips client/consumer handling — and the failure kind (timeout vs throw vs compile) is already delivered verbatim to operators as the script-log Reason string on the script-logs topic. Alternatives rejected:

• Widen OpcUaQuality with BadInternalError/BadTimeout members — additive on the enum, but it ripples a Commons contract consumed by every sink implementation and driver publish path, for a sub-code no consumer acts on. Contained follow-up if a real client requirement appears.
• Carry a raw uint status through AttributeValueUpdate/IOpcUaAddressSpaceSink.WriteValue — the precise-parity option, but it changes an interface with four implementations and re-runs the F10b/DeferredAddressSpaceSink forwarding trap for zero operator value. Rejected.
• Exception: the historize snapshot takes raw uint status already (DataValueSnapshot), so there the bridge records exact dormant-engine parity: 0x80020000u /* BadInternalError */ on Bad results (the dormant engine historizes its Bad snapshots unconditionally at VirtualTagEngine.cs:346-348; we mirror that).

(b) Publish cadence — once per transition, not per failure. Every publish is a sink write + ClearChangeMasks → client notification on the pinned OPC UA dispatcher. A failing script on a hot dependency would otherwise emit one identical Bad write per dependency change (each also paying the P2 pool hop + 2 s worst-case actor block per S7). The actor tracks _lastPublishedBad; it publishes Bad on the Good→Bad (or initial→Bad) transition only, and on recovery it force-publishes the next success even if the value equals the pre-failure value — otherwise the value-dedup at VirtualTagActor.cs:138 would leave the node Bad forever after a same-value recovery. (Script-log Warning entries stay per-failure, unchanged — that's the existing operator diagnostic and its volume is pre-existing.)

(c) Cold-start suppression — an inputs-ready gate, mirroring the dormant engine. The live path has no AreInputsReady equivalent: a multi-dep script fails on the first dependency arrival (the missing dep's GetTag(...).Value is null → cast throws) until all deps have landed. Publishing Bad on those would make every fresh/respawned multi-dep VT flash BadWaitingForInitialData → Bad → Good on every deploy — operator-visible churn for healthy scripts. Worse, gating on "had a prior success in this child" is insufficient for S13's headline scenario: an edited-now-broken script respawns its child (plan change ⇒ stop+respawn at VirtualTagHostActor.cs:109-118), so the fresh child has no prior success and would never degrade — reintroducing stale-Good exactly where it matters most. The correct gate is the dormant engine's: suppress Bad publishes until every dependencyRefs entry has been received at least once (_dependencyRefs.All(_dependencies.ContainsKey)); after that, any failure degrades. A never-arriving dependency keeps the node at the materialiser's BadWaitingForInitialData (already Bad — acceptable, and per the report "acceptable" for never-succeeded scripts).

(d) Message/bridge shape — additive Quality on EvaluationResult. Add OpcUaQuality Quality = OpcUaQuality.Good as a trailing optional parameter on the EvaluationResult positional record: every existing construction and destructuring site compiles unchanged, and the message is a local Context.Parent.Tell (no wire serialization concern). The bridge replaces the hard-coded OpcUaQuality.Good with result.Quality, and maps the historize status (Good→0u, else 0x80020000u). The dependency mux is untouched — quality flows child→parent→publish actor; the mux only fans values into children (DependencyValueChanged is unchanged), so no mux registration, routing, or message contract moves.

On failure the Bad EvaluationResult carries the last-known value (_lastValue if _hasLastValue, else null) with the triggering msg.TimestampUtc — clients see the stale value explicitly flagged Bad (the report's "publish the existing value with Bad quality"), rather than the dormant engine's null-value choice; either is defensible, this one preserves more information for trend displays.

Implementation steps:

1. Runtime/VirtualTags/VirtualTagActor.cs:
   • using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
   • public sealed record EvaluationResult(string VirtualTagId, object? Value, DateTime TimestampUtc, CorrelationId Correlation, OpcUaQuality Quality = OpcUaQuality.Good);
   • Add fields private bool _lastPublishedBad; and a helper private bool AllDependenciesArrived() => _dependencyRefs.All(_dependencies.ContainsKey); (refs list is small; called once per failure — no caching needed).
   • Extract the failure tail shared by the evaluator-threw catch (:115-121) and the !Success branch (:123-128) into private void OnEvaluationFailed(string reason, string level, DateTime timestampUtc): keep the existing metric + PublishLog, then if (_lastPublishedBad || !AllDependenciesArrived()) return; else _lastPublishedBad = true; Context.Parent.Tell(new EvaluationResult(_virtualTagId, _hasLastValue ? _lastValue : null, timestampUtc, CorrelationId.NewId(), OpcUaQuality.Bad));
   • Success path: change the dedup guard at :138 to if (!_lastPublishedBad && _hasLastValue && Equals(_lastValue, result.Value)) and set _lastPublishedBad = false; alongside _hasLastValue = true; before the Good publish. The NoChange short-circuit (:132-136) stays above the dedup and does not touch _lastPublishedBad (NoChange = "no fresh value", not a recovery).
   • Update the class summary: failures now degrade quality once per transition.
2. Runtime/VirtualTags/VirtualTagHostActor.cs (OnResult, :170-190):
   • _publishActor.Tell(new OpcUaPublishActor.AttributeValueUpdate(nodeId, result.Value, result.Quality, result.TimestampUtc));
   • Historize: var status = result.Quality == OpcUaQuality.Good ? 0u : 0x80020000u /* BadInternalError — dormant-engine parity */; and pass status into the DataValueSnapshot.
   • Update the :179-180 comment (no longer hard-coded Good).
3. Update VirtualTagActorTests.Evaluator_failure_publishes_ScriptLogEntry_warning: the trailing parent.ExpectNoMsg becomes parent.ExpectMsg<EvaluationResult>() with Quality == Bad (the test constructs the actor with empty dependencyRefs, so the inputs-ready gate is vacuously satisfied — All over an empty list is true).

Tests: (all deterministic; probes only)

• Repro first (must FAIL at f6eaa267): Runtime.Tests VirtualTagHostActorTests. Failing_script_after_success_degrades_node_quality_to_Bad — host + real child + a scripted fail-after-success IVirtualTagEvaluator stub; drive the child (captured via the mux probe's RegisterInterest sender) with two DependencyValueChangeds; assert the publish probe receives update 1 (Good, 42) then update 2 with Quality == OpcUaQuality.Bad carrying the last value. Uses only current types (AttributeValueUpdate already has Quality), so it compiles today and times out on the second ExpectMsg — the stale-Good repro.
• VirtualTagActorTests: failure-after-success emits Bad EvaluationResult with last value; second consecutive failure emits nothing (once-per-transition); recovery to the same value as before the failure does publish (dedup bypass); evaluator-threw path (not just Failure) also degrades; multi-dep cold-start failure with a missing dep publishes no Bad (inputs-ready gate); after all deps arrive, failure publishes Bad.
• VirtualTagHostActorTests: a Bad-quality EvaluationResult bridges to an AttributeValueUpdate with Quality == Bad; a historized plan's Bad result records status 0x80020000u (BadInternalError).
• Wiring note (theme #1, "unit-green ≠ wired"): the repro test above IS the wiring assertion — it runs the real host + real child + parent-Tell bridge, not a hand-delivered message. The remaining live wire (publish actor → sink → SDK node) is pre-existing, already exercised by OpcUaPublishActor tests, and covered by the live-/run gate below.

Effort: S. Risk: Low-Medium. The behavioral deltas are (1) parents now receive Bad results — only VirtualTagHostActor parents children in production, and it handles the new field natively; (2) a node that used to freeze Good now goes Bad on persistent failure — the intended, strictly-safer change; (3) one existing test's expectation inverts (deliberate, task-tracked). Blast radius = VT value path only; alarms/drivers untouched.

---

2. S12 — MEDIUM — Apply-boundary ClearCompiledScripts races in-flight child evaluations

Restatement: The host's per-apply Clear() disposes cached evaluators while unchanged children keep evaluating on other dispatcher threads. A child that fetched its evaluator (GetOrCompile, RoslynVirtualTagEvaluator.cs:69) before the clear hits the disposed guard on run (ScriptEvaluator.cs:180) → ObjectDisposedException → generic catch → Failure → silently dropped update (self-heals only on the tag's next dependency change — a long staleness window for slow tags). Secondary: a stopping child can recompile its stale script into the fresh cache for one generation.

Verification: Confirmed (see summary). The cache itself is blameless — its value-scoped TryRemove protects concurrent GetOrCompile re-adds; the gap is clear-vs-use of an already-handed-out evaluator. The ScriptedAlarmEngine mirror is inexact exactly as the report says (gate-held clear after subscription teardown, ScriptedAlarmEngine.cs:199-209).

Root cause: IScriptCacheOwner.ClearCompiledScripts was wired at the apply boundary (U3) without a coordination primitive between the host actor's clear and child actors' fetch→run sequence — the Task.Run hop inside TimedScriptEvaluator guarantees a real window between fetch and the disposed check.

Proposed design — catch-ObjectDisposedException, re-fetch, retry once (in the adapter). The recompile is idempotent (same source → fresh evaluator in the current cache generation), the retry is entirely local to RoslynVirtualTagEvaluator.Evaluate, and it converts the dropped update into a correct evaluation against the post-clear generation. If a second clear lands mid-retry (two applies inside one evaluation — not a realistic cadence), the second ObjectDisposedException falls through to the existing Failure path — same as today's worst case, now with an S13 Bad-quality publish instead of silence. Alternatives rejected:

• ReaderWriterLockSlim (children read-lock fetch→run; clear write-locks) — blocks the host actor for up to a full in-flight timeout budget (2 s) during every apply, and adds lock traffic to the hot path, to prevent a race the retry heals for free. Rejected.
• Per-generation cache instances with deferred dispose of the old generation — disposing the old generation safely still requires knowing when in-flight evaluations finish, i.e. ref-counting — the same coordination problem with more machinery. Rejected.
• Move the clear after the stop/respawn reconciliation — doesn't close the race for unchanged children (the common case), and the stale-recompile wrinkle survives either way because Context.Stop is asynchronous. Rejected as a fix; the wrinkle stays accepted + documented (bounded to one generation, released at the next apply-with-changes; P7's gate also means no-op redeploys no longer create the window at all).

Implementation steps (Host/Engines/RoslynVirtualTagEvaluator.cs, the compiled path :66-121):

1. Restructure fetch+run into a bounded loop (for (var attempt = 0; ; attempt++)):
   • fetch: evaluator = _cache.GetOrCompile(expression); — keep the existing CompilationErrorException / ScriptSandboxViolationException / generic catches on the fetch (unchanged behavior). A disposed cache here means the whole evaluator is being shut down — GetOrCompile throws ObjectDisposedException, which the new handler must NOT retry: check _disposed and return VirtualTagEvalResult.Failure("evaluator disposed").
   • run: existing TimedScriptEvaluator + GetAwaiter().GetResult() block, adding before the generic catch:

     catch (ObjectDisposedException) when (!_disposed && attempt == 0)
     {
         // S12: the apply-boundary ClearCompiledScripts disposed the evaluator between our
         // GetOrCompile and the run's disposed-guard. Re-fetch — GetOrCompile recompiles the same
         // source into the CURRENT cache generation — and retry once. A second disposal mid-retry
         // (two applies inside one evaluation) falls through to the generic failure path.
         continue;
     }
     

   • catch (ObjectDisposedException) (second hit, or _disposed) → Failure("evaluator disposed during evaluation").
2. Update the class doc: the apply-boundary clear is retry-safe for in-flight evaluations; the one-generation stale-recompile wrinkle for stopping children is the documented residual.

Tests (Host.IntegrationTests/RoslynVirtualTagEvaluatorTests.cs):

• Evaluate_racing_ClearCompiledScripts_never_fails_with_disposed — one evaluator; task A loops N (≈300) compiled (non-passthrough) evaluations of the same expression; task B loops ClearCompiledScripts() with Thread.Yield() between calls until A finishes; whole test WaitAsync-bounded (30 s). Assert every result Success == true (and specifically no Reason containing "disposed"). Determinism note: the pre-fix failure is probabilistic per iteration (the window is fetch → Task.Run-hopped disposed-guard, widened by pool queuing), but at N=300 racing clears it reproduces reliably in practice; post-fix it is deterministic-green by construction (the retry is exhaustive for a single concurrent clear). This is the report's prescribed "concurrent clear-during-evaluate test".
• Evaluate_after_ClearCompiledScripts_recompiles_and_succeeds — deterministic sequential guard: evaluate, clear, evaluate same source again → Success both times, cache Count back to 1 (uses the existing CompiledCacheCount reflection helper).
• Existing Evaluate_after_dispose_returns_Failure still green (the _disposed short-circuit at :51 is untouched; the new ODE handler's !_disposed filter keeps shutdown semantics).

Effort: S (the report's "10-line fix" is accurate; the loop restructure is the only care point). Risk: Low. Happy path unchanged (attempt 0, no exception); passthrough fast-path never enters the loop. Blast radius = one method in the Host adapter.

---

3. P7 — LOW — Unconditional per-apply cache flush forces full VT recompilation on every deploy

Restatement: OnApply clears the compile cache on every ApplyVirtualTags (VirtualTagHostActor.cs:92) — including a byte-identical redeploy that stops/spawns nothing. Every VT script then recompiles on its next evaluation, each paying the still-open P1 full-BCL-reference-set rebuild (5-20 ms+ per script). Amplifies P1; also each unnecessary clear is an unnecessary S12 race window.

Verification: Confirmed (see summary). The host already holds last generation's plans in _planByVtag; EquipmentVirtualTagPlan.Expression participates in value equality. The existing wiring guard asserts the current (unconditional) behavior on an identical redeploy and must be rewritten.

Root cause: The U3 fix chose the simplest correct lifecycle ("clear per generation", mirroring the alarm engine) without consulting the plan diff the same method computes a few lines later.

Proposed design — clear only when the deployed expression set changed. At the top of OnApply, compare the desired expression set against the previous generation's (_planByVtag.Values.Select(p => p.Expression)), and clear only on inequality:

var newExpressions = msg.Plans.Select(p => p.Expression).ToHashSet(StringComparer.Ordinal);
var prevExpressions = _planByVtag.Values.Select(p => p.Expression).ToHashSet(StringComparer.Ordinal);
if (!newExpressions.SetEquals(prevExpressions))
{
    (_evaluator as IScriptCacheOwner)?.ClearCompiledScripts();
}

Decisions inside this shape:

• Expression set, not full-plan set: the cache is keyed by source hash only, so a rename / FolderPath move / Historize toggle (which respawns the child) does not need a recompile — comparing full plans would clear on those spuriously. Two vtags sharing one expression are handled naturally (set semantics: the expression survives while any plan still uses it).
• Any-change clears everything (not per-source eviction): editing 1 of 200 scripts still recompiles 200. Accepted per the report ("cheap to leave as-is at current scale; fix alongside P1") — the headline P7 cost is the no-op redeploy, which this eliminates entirely. Rejected alternative: a CompiledScriptCache.RetainOnly(IEnumerable<string> sources) API — precise, but new Core.Scripting surface + tests for a Low; note it as the follow-up shape if P1's memoization doesn't land first.
• First apply after actor (re)start: _planByVtag is empty → sets differ → clear fires (harmless: the singleton evaluator's cache may hold a prior incarnation's entries; clearing converges state).
• Interaction with S12 (design question d): independent and composing — the gate reduces clear frequency (no-op redeploys stop racing entirely), the retry remains the correctness backstop for genuine changes. The gate must NOT be treated as the S12 fix: a real script edit still clears while unchanged children evaluate.
• Interaction with S13: none (quality path doesn't touch the cache).

Implementation steps:

1. Replace VirtualTagHostActor.cs:88-92 (comment + unconditional call) with the guarded block above + a comment explaining the expression-set gate (and that _planByVtag is "the previous generation" at this point — the method rebuilds it at the end).
2. Rewrite the wiring guard ApplyVirtualTags_clears_the_evaluator_compile_cache_each_generation → ApplyVirtualTags_clears_the_compile_cache_only_when_the_expression_set_changes: apply plan A (ClearCount 1) → re-apply identical plan A (ClearCount still 1) → apply plan A′ with an edited Expression (ClearCount 2) → re-apply with a vtag removed but its expression still used by another vtag (ClearCount still 2). Keeps the load-bearing "the host actually calls it" wiring assertion while pinning the new gate.

Tests: the rewritten wiring guard above (in Runtime.Tests/VirtualTags/VirtualTagHostActorTests.cs, using the existing CacheOwningStubEvaluator spy). New-behavior red state: the identical-redeploy step fails on current code (ClearCount is 2, expected 1).

Effort: S. Risk: Low. The only hazard is under-clearing (a stale ALC surviving a deploy whose expression set is unchanged) — by construction those entries are exactly the still-deployed sources, so nothing stale survives. Blast radius = one method + one test.

---

Live-/run verification (after all tasks green)

Deterministic units + wiring guards above are necessary but not sufficient — unit-green ≠ wired (the F10b lesson). Close with the docker-dev rig (login disabled; do it yourself, no user sign-in):

1. Rebuild both central-1 and central-2 images (:9200 round-robins them) and bring docker-dev/docker-compose.yml up.
2. On /uns (AdminUI http://localhost:9200), author a VirtualTag on a rig equipment with a script that succeeds against live deps (e.g. return (double)ctx.GetTag("<dep>").Value * 2;), deploy (POST :9200/api/deployments, X-Api-Key), and confirm via Client.CLI: dotnet run --project src/Client/ZB.MOM.WW.OtOpcUa.Client.CLI -- read -u opc.tcp://localhost:4840 -n "<folder-scoped NodeId>" → value present, StatusCode Good.
3. Edit the script to a guaranteed runtime throw (e.g. int z = 0; return 1 / z;), redeploy, wait one dependency change → Client.CLI read again → StatusCode Bad (0x80000000), value = last-known. This exercises the exact S13 headline path (edited-broken script ⇒ respawned child ⇒ inputs-ready gate ⇒ Bad publish) end to end through the SDK node.
4. Fix the script back, redeploy → read returns Good with a fresh value (recovery + dedup-bypass live).
5. P7 spot-check: redeploy the identical config; central logs show no recompile burst (and the S12 stress guard covers the race in CI).

---

Task breakdown

Branch: fix/archreview-r2-03-vt-failure-quality off master@f6eaa267. Tasks are ≤5 min each; TDD-ordered (repro/red test precedes each implementation). Test commands run from the repo root.

---

R2-03-T1 — S13 stale-Good repro test (RED — must fail on current code)

Classification: test-first repro (deterministic unit, host-level wiring shape) Estimated implement time: 5 min Parallelizable with: T7 (different test file); everything else depends on this landing red first. Files: tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/VirtualTags/VirtualTagHostActorTests.cs

1. Add a FailAfterFirstSuccessEvaluator : IVirtualTagEvaluator private stub (call 1 → Ok(42.0), thereafter → Failure("boom"); interlocked counter).
2. Add test Failing_script_after_success_degrades_node_quality_to_Bad: host with publish + mux probes and the stub; apply one plan (deps ["a"]); capture the child via mux.ExpectMsg<DependencyMuxActor.RegisterInterest>() + mux.LastSender; tell the child DependencyValueChanged("a", 1, ts1) → publish probe expects AttributeValueUpdate with Quality == OpcUaQuality.Good, Value == 42.0; tell DependencyValueChanged("a", 2, ts2) → expect a second AttributeValueUpdate with Quality == OpcUaQuality.Bad and Value == 42.0 (last-known) and TimestampUtc == ts2.
3. dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter "FullyQualifiedName~VirtualTagHostActorTests.Failing_script_after_success_degrades_node_quality_to_Bad" → expected: FAIL (timeout on the second ExpectMsg — the stale-Good bug, verbatim).

Commit: test(runtime): red repro — VT script failure after success leaves node stale-Good (02/S13)

---

R2-03-T2 — EvaluationResult.Quality + bridge pass-through + historize parity

Classification: implementation (additive message field + bridge) Estimated implement time: 5 min Parallelizable with: T7/T8 (disjoint files). Blocked by T1 (repro must be red first). Files: src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/VirtualTagActor.cs (record only), src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/VirtualTagHostActor.cs, tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/VirtualTags/VirtualTagHostActorTests.cs

1. RED: add bridge tests Bad_quality_EvaluationResult_is_bridged_as_Bad (tell the host a synthetic EvaluationResult(..., Quality: OpcUaQuality.Bad) → publish probe's AttributeValueUpdate.Quality is Bad) and Historized_Bad_result_is_recorded_with_BadInternalError_status (PlanH historize:true; Bad result → CapturingHistoryWriter snapshot StatusCode == 0x80020000u). These require the record change to compile — so within this task: add OpcUaQuality Quality = OpcUaQuality.Good to EvaluationResult (+ using ...Commons.OpcUa;) FIRST, then run the two tests: dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter "FullyQualifiedName~VirtualTagHostActorTests.Bad_quality_EvaluationResult_is_bridged_as_Bad|FullyQualifiedName~VirtualTagHostActorTests.Historized_Bad_result_is_recorded_with_BadInternalError_status" → expected: FAIL (bridge still hard-codes Good / 0u).
2. GREEN: OnResult — pass result.Quality into AttributeValueUpdate; historize status result.Quality == OpcUaQuality.Good ? 0u : 0x80020000u /* BadInternalError — dormant-engine parity */; fix the stale comments at :179-188. Re-run the filter → PASS. Also run the full host-actor class (--filter "FullyQualifiedName~VirtualTagHostActorTests") — all pre-existing tests (Good-path bridging, historize Good 0u) must stay green, proving the default keeps byte-parity.

Commit: feat(runtime): EvaluationResult carries OpcUaQuality; VT bridge publishes it + historizes BadInternalError on Bad (02/S13)

---

R2-03-T3 — VirtualTagActor failure→Bad transition (turns T1 green)

Classification: implementation (actor behavior) Estimated implement time: 5 min Parallelizable with: T7/T8. Blocked by T2. Files: src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/VirtualTagActor.cs, tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/VirtualTags/VirtualTagActorTests.cs

1. Implement per design §1(b)/(c)/(d): _lastPublishedBad field, AllDependenciesArrived(), OnEvaluationFailed(...) shared by the throw-catch and !Success branch (metric + script-log preserved per-failure; Bad publish once per transition, gated on inputs-ready, carrying _hasLastValue ? _lastValue : null + msg.TimestampUtc); success path resets _lastPublishedBad and bypasses the value-dedup when recovering; class-summary xmldoc updated.
2. Update Evaluator_failure_publishes_ScriptLogEntry_warning: replace the trailing parent.ExpectNoMsg(...) with parent.ExpectMsg<VirtualTagActor.EvaluationResult>().Quality.ShouldBe(OpcUaQuality.Bad) — the deliberate behavioral inversion (empty dependencyRefs ⇒ inputs-ready gate vacuously true).
3. dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter "FullyQualifiedName~VirtualTagHostActorTests.Failing_script_after_success_degrades_node_quality_to_Bad" → expected: PASS (T1 repro green). dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter "FullyQualifiedName~VirtualTagActorTests" → expected: PASS (incl. the updated failure test).

Commit: fix(runtime): VT script failure/timeout degrades node quality to Bad once per transition (02/S13)

---

R2-03-T4 — S13 transition-semantics unit guards

Classification: tests (deterministic units pinning the state machine) Estimated implement time: 5 min Parallelizable with: T5, T7/T8. Blocked by T3. Files: tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/VirtualTags/VirtualTagActorTests.cs

Add (scriptable stub evaluator with a queue of results):

1. Second_consecutive_failure_does_not_publish_a_second_Bad — fail, fail → exactly one Bad EvaluationResult at the parent (ExpectMsg then ExpectNoMsg).
2. Recovery_to_the_same_value_republishes_Good_after_Bad — Ok(42), fail, Ok(42) → three parent messages; the third is Quality == Good, Value == 42 (dedup bypass — this is the guard against the node staying Bad forever after a same-value recovery).
3. Evaluator_throw_also_degrades_quality — evaluator that throws (not Failure) → Bad EvaluationResult published (the :115-121 path).
4. dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter "FullyQualifiedName~VirtualTagActorTests" → expected: PASS (all should pass immediately if T3 is correct; any red here is a T3 bug, fix in place).

Commit: test(runtime): pin VT Bad-quality transition semantics — once-per-transition, same-value recovery, throw path (02/S13)

---

R2-03-T5 — S13 cold-start suppression guard (inputs-ready gate)

Classification: tests (deterministic unit pinning the gate) Estimated implement time: 5 min Parallelizable with: T4, T7/T8. Blocked by T3. Files: tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/VirtualTags/VirtualTagActorTests.cs

1. Cold_start_failure_with_missing_dependency_publishes_no_Bad — actor with dependencyRefs: ["a","b"], always-failing evaluator; send DependencyValueChanged("a", ...) only → parent.ExpectNoMsg (node stays at the materialiser's BadWaitingForInitialData; no false Bad flash during deploy/respawn warm-up).
2. Failure_after_all_dependencies_arrived_publishes_Bad — same actor; send "a" then "b" → the second change (all refs now seen) publishes exactly one Bad EvaluationResult.
3. dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter "FullyQualifiedName~VirtualTagActorTests.Cold_start_failure_with_missing_dependency_publishes_no_Bad|FullyQualifiedName~VirtualTagActorTests.Failure_after_all_dependencies_arrived_publishes_Bad" → expected: PASS.

Commit: test(runtime): pin VT inputs-ready gate — no Bad flash before all dependencies arrive (02/S13)

---

R2-03-T6 — S12 sequential clear-then-recompile guard (RED-able)

Classification: test-first (deterministic unit) Estimated implement time: 3 min Parallelizable with: T1-T5 (different project/file). Files: tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/RoslynVirtualTagEvaluatorTests.cs

1. Add Evaluate_after_ClearCompiledScripts_recompiles_and_succeeds: evaluate a compiled expression, ClearCompiledScripts(), evaluate the same source again → both Success, CompiledCacheCount == 1 after the second call. (Green on current code — this pins the sequential contract the T8 retry loop must not regress; the restructure moves the fetch inside a loop.)
2. dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests --filter "FullyQualifiedName~RoslynVirtualTagEvaluatorTests.Evaluate_after_ClearCompiledScripts_recompiles_and_succeeds" → expected: PASS (pre-fix baseline pin).

Commit: test(host): pin sequential clear-then-recompile contract of RoslynVirtualTagEvaluator (02/S12 baseline)

---

R2-03-T7 — S12 concurrent clear-vs-evaluate stress guard (RED — fails on current code)

Classification: test-first repro (concurrency stress; probabilistic-per-iteration, reliable at volume) Estimated implement time: 5 min Parallelizable with: T1-T6. Files: tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/RoslynVirtualTagEvaluatorTests.cs

1. Add async Task Evaluate_racing_ClearCompiledScripts_never_fails_with_disposed: one evaluator (generous 5 s timeout so the budget never fires); Task.Run loop A doing 300 sequential Evaluate("vt-race", "return (int)ctx.GetTag(\"a\").Value + 1;", …) calls collecting results; concurrent loop B calling ClearCompiledScripts() + Thread.Yield() until A completes; whole test awaited with WaitAsync(TimeSpan.FromSeconds(30), TestContext.Current.CancellationToken) (regression fails, never hangs — the U2 test's pattern). Assert every result Success shouldBeTrue with result.Reason as the message (surfaces "script threw: Cannot access a disposed object" on red).
2. dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests --filter "FullyQualifiedName~RoslynVirtualTagEvaluatorTests.Evaluate_racing_ClearCompiledScripts_never_fails_with_disposed" → expected: FAIL on current code (disposed-reason failures observed within 300 racing iterations; the window is GetOrCompile-return → Task.Run-hopped disposed guard). If a run happens to pass, bump iterations — do not weaken the assertion.

Commit: test(host): red repro — apply-boundary cache clear races in-flight VT evaluation into ObjectDisposedException (02/S12)

---

R2-03-T8 — S12 retry-once on ObjectDisposedException (turns T7 green)

Classification: implementation (adapter hardening) Estimated implement time: 5 min Parallelizable with: T1-T5. Blocked by T6 + T7. Files: src/Server/ZB.MOM.WW.OtOpcUa.Host/Engines/RoslynVirtualTagEvaluator.cs

1. Restructure the compiled path per design §2: for (var attempt = 0; ; attempt++) around fetch (GetOrCompile — existing catch chain preserved) + run (TimedScriptEvaluator block), adding catch (ObjectDisposedException) when (!_disposed && attempt == 0) { continue; } before the generic catch, and catch (ObjectDisposedException) → Failure("evaluator disposed during evaluation") for the shutdown / double-clear case. Update the class xmldoc (retry-safe vs apply-boundary clear; one-generation stale-recompile residual documented).
2. dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests --filter "FullyQualifiedName~RoslynVirtualTagEvaluatorTests" → expected: PASS (T7 stress green; T6 sequential pin green; all pre-existing U2/U3/passthrough tests green — proves the loop restructure didn't disturb timeout, cache, or fast-path semantics).

Commit: fix(host): retry VT evaluation once on ObjectDisposedException from the apply-boundary cache clear (02/S12)

---

R2-03-T9 — P7 conditional-clear wiring guard (RED — fails on current code)

Classification: test-first (rewrites an existing wiring guard — deliberate behavior change) Estimated implement time: 5 min Parallelizable with: T7/T8. Blocked by T3 (same test file churn as T1-T5; serialize after S13 lands). Files: tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/VirtualTags/VirtualTagHostActorTests.cs

1. Rewrite ApplyVirtualTags_clears_the_evaluator_compile_cache_each_generation → ApplyVirtualTags_clears_the_compile_cache_only_when_the_expression_set_changes (keep the CacheOwningStubEvaluator spy; keep the "the host actually calls it" wiring-assertion role — update the xmldoc to say the clear is now gated, citing 02/P7): apply plan A (ClearCount == 1) → re-apply value-identical plan A (ClearCount == 1) → apply plan A with an edited Expression (ClearCount == 2) → apply two vtags sharing one expression, then remove one of them (expression set unchanged ⇒ count unchanged).
2. dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter "FullyQualifiedName~VirtualTagHostActorTests.ApplyVirtualTags_clears_the_compile_cache_only_when_the_expression_set_changes" → expected: FAIL on current code (identical-redeploy step observes ClearCount == 2).

Commit: test(runtime): red — apply-boundary compile-cache clear must be gated on a changed expression set (02/P7)

---

R2-03-T10 — P7 expression-set gate (turns T9 green)

Classification: implementation (host-actor apply path) Estimated implement time: 3 min Parallelizable with: — (same method as T2's file; do after T9). Blocked by T9. Files: src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/VirtualTagHostActor.cs

1. Replace OnApply's unconditional clear (:88-92) with the guarded block from design §3 (HashSet.SetEquals over msg.Plans vs _planByVtag.Values expressions; ordinal comparer), with a comment covering: _planByVtag is the previous generation at this point; rename/Historize-only changes don't clear (cache is source-keyed); first-apply-after-restart clears by construction; the S12 retry — not this gate — is the in-flight-race fix.
2. dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter "FullyQualifiedName~VirtualTagHostActorTests" → expected: PASS (T9 guard green + every other host-actor test green).

Commit: perf(runtime): gate the VT apply-boundary compile-cache clear on a changed expression set (02/P7)

---

R2-03-T11 — Full-suite sweep + STATUS/report bookkeeping

Classification: verification + docs Estimated implement time: 5 min Parallelizable with: —. Blocked by T1-T10. Files: archreview/plans/STATUS.md, archreview/plans/R2-03-vt-failure-quality-plan.md.tasks.json

1. dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests → expected: PASS (whole project).
2. dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests --filter "FullyQualifiedName~RoslynVirtualTagEvaluatorTests" → expected: PASS.
3. dotnet build ZB.MOM.WW.OtOpcUa.slnx → clean (analyzer OTOPCUA0001 + xmldoc warnings unchanged).
4. Record S13/S12/P7 as fixed-on-branch in STATUS.md (Re-review 2026-07-12 section) + tick the tasks.json.

Commit: docs(archreview): record R2-03 (02/S13+S12+P7) fixed on branch; full VT suites green

---

R2-03-T12 — Live-/run gate on docker-dev (fail→Bad→recover, end to end)

Classification: live verification (docker-dev rig; no user sign-in needed — login disabled) Estimated implement time: 15-20 min (rig rebuild dominates) Parallelizable with: —. Blocked by T11. Files: none (verification only; findings, if any, loop back as new tasks)

Follow the "Live-/run verification" section above: rebuild both central images; author a working VT → Client.CLI read Good; edit it to a runtime throw → redeploy → after one dependency change, Client.CLI read shows StatusCode Bad with the last-known value (this is the edited-broken-script respawn path — the S13 headline — through the real mux/child/bridge/publish-actor/SDK-node chain); fix → redeploy → read Good with a fresh value. Spot-check an identical redeploy produces no recompile burst in central logs (P7). Do NOT merge on unit-green alone — this is the wiring bar.

Commit: none (verification). If the rig exposes a gap, open follow-up tasks before merge.

---

Task dependency summary

T1 (S13 red repro) ──► T2 (record+bridge) ──► T3 (actor fix, T1 green) ──► T4, T5 (guards)
                                                                └────────► T9 (P7 red) ──► T10 (P7 green)
T6 (S12 pin) ─┐
T7 (S12 red) ─┴──► T8 (S12 retry, T7 green)
T4, T5, T8, T10 ──► T11 (sweep + docs) ──► T12 (live /run gate)

Overall effort: Small (≈2-3 h implementation + the rig session), matching the OVERALL table's estimate for action item #3. Overall risk: Low-Medium, concentrated in S13's deliberate behavior change (nodes that used to freeze Good now go Bad — the point of the fix) and the one inverted legacy test expectation, both explicitly task-tracked.