feat(engines): IVirtualTagEvaluator snapshot overload; Roslyn read cache stops fabricating Good (02/S14)

src/Core/ZB.MOM.WW.OtOpcUa.Commons/Engines/IVirtualTagEvaluator.cs

@@ -1,3 +1,5 @@
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
 namespace ZB.MOM.WW.OtOpcUa.Commons.Engines;
 
 /// <summary>
@@ -18,6 +20,34 @@ public interface IVirtualTagEvaluator
     /// <param name="dependencies">Read-only dictionary of variable names to values for expression evaluation.</param>
     /// <returns>Result containing success flag, evaluated value, and optional failure reason.</returns>
     VirtualTagEvalResult Evaluate(string virtualTagId, string expression, IReadOnlyDictionary<string, object?> dependencies);
+
+    /// <summary>
+    ///     Evaluate <paramref name="expression"/> against dependency <b>snapshots</b> — value, status
+    ///     code and source timestamp per input — so a script's <c>ctx.GetTag(path).StatusCode</c> reports
+    ///     what the source actually said (archreview 02/S14).
+    /// </summary>
+    /// <remarks>
+    ///     <b>Default-implemented on purpose.</b> It projects to values and calls the older overload, so
+    ///     every existing implementation — the Roslyn evaluator aside, that is the null evaluator and the
+    ///     test fakes — compiles and behaves unchanged; an implementation that can do better (the Roslyn
+    ///     one) overrides it. Making it abstract would have been a breaking change for a fix whose whole
+    ///     point is that it changes nothing on the Good path.
+    ///     <para>The default necessarily discards the status codes it was given, which is exactly the
+    ///     laundering this overload exists to end — so a consumer that cares must call an implementation
+    ///     that overrides it.</para>
+    /// </remarks>
+    /// <param name="virtualTagId">The unique identifier of the virtual tag being evaluated.</param>
+    /// <param name="expression">The expression string to evaluate.</param>
+    /// <param name="dependencies">Read-only dictionary of dependency snapshots, keyed by tag path.</param>
+    /// <returns>Result containing success flag, evaluated value, and optional failure reason.</returns>
+    VirtualTagEvalResult Evaluate(
+        string virtualTagId, string expression, IReadOnlyDictionary<string, DataValueSnapshot> dependencies)
+    {
+        ArgumentNullException.ThrowIfNull(dependencies);
+        var values = new Dictionary<string, object?>(dependencies.Count, StringComparer.Ordinal);
+        foreach (var kv in dependencies) values[kv.Key] = kv.Value?.Value;
+        return Evaluate(virtualTagId, expression, values);
+    }
 }
 
 /// <summary>Result of one virtual-tag expression eval. Stash a Reason on every Failure so

src/Server/ZB.MOM.WW.OtOpcUa.Host/Engines/RoslynVirtualTagEvaluator.cs

@@ -59,7 +59,34 @@ public sealed class RoslynVirtualTagEvaluator : IVirtualTagEvaluator, IScriptCac
     }
 
     /// <inheritdoc />
+    /// <remarks>
+    ///     <b>Value-only overload.</b> Every dependency reaches the script stamped <c>Good</c> with an
+    ///     evaluation-time timestamp — bare values carry nothing better. The runtime calls the snapshot
+    ///     overload instead (archreview 02/S14); this one remains for callers that genuinely hold only
+    ///     values.
+    /// </remarks>
     public VirtualTagEvalResult Evaluate(string virtualTagId, string expression, IReadOnlyDictionary<string, object?> dependencies)
+    {
+        ArgumentNullException.ThrowIfNull(dependencies);
+        var nowUtc = DateTime.UtcNow;
+        var snapshots = new Dictionary<string, DataValueSnapshot>(dependencies.Count, StringComparer.Ordinal);
+        foreach (var kv in dependencies)
+            snapshots[kv.Key] = new DataValueSnapshot(kv.Value, StatusCode: 0u, nowUtc, nowUtc);
+
+        return Evaluate(virtualTagId, expression, snapshots);
+    }
+
+    /// <inheritdoc />
+    /// <remarks>
+    ///     Overrides the interface's default (which projects to values and loses the status codes): the
+    ///     snapshots pass <b>through</b> as the script's read cache, so
+    ///     <c>ctx.GetTag(path).StatusCode</c> and <c>.SourceTimestampUtc</c> are the input's own rather
+    ///     than a fabricated <c>Good</c> stamped at evaluation time (archreview 02/S14). The virtual-tag
+    ///     actor holds evaluation entirely while any input is Bad, so what a script observes here is Good
+    ///     or Uncertain.
+    /// </remarks>
+    public VirtualTagEvalResult Evaluate(
+        string virtualTagId, string expression, IReadOnlyDictionary<string, DataValueSnapshot> dependencies)
     {
         if (_disposed) return VirtualTagEvalResult.Failure("evaluator disposed");
         if (string.IsNullOrWhiteSpace(expression)) return VirtualTagEvalResult.Failure("empty expression");
@@ -71,12 +98,14 @@ public sealed class RoslynVirtualTagEvaluator : IVirtualTagEvaluator, IScriptCac
         // so the script returns null — Ok(null) here too.
         if (PassthroughScript.TryMatch(expression, out var passthroughRef))
         {
-            return dependencies.TryGetValue(passthroughRef, out var ptValue)
-                ? VirtualTagEvalResult.Ok(ptValue)
+            // The VALUE only — the caller stamps the result with the worst input status, which for a
+            // single-dependency passthrough IS this input's status.
+            return dependencies.TryGetValue(passthroughRef, out var ptSnapshot)
+                ? VirtualTagEvalResult.Ok(ptSnapshot?.Value)
                 : VirtualTagEvalResult.Ok(null);
         }
 
-        var readCache = BuildReadCache(dependencies);
+        var readCache = dependencies;
         // Per-evaluation script logger: bind both ScriptId and VirtualTagId from the virtual-tag id
         // (in the live path the script id equals the virtual-tag id) so the Script-log page can
         // attribute each line. EquipmentId stays unbound for now.
@@ -162,21 +191,6 @@ public sealed class RoslynVirtualTagEvaluator : IVirtualTagEvaluator, IScriptCac
     /// <inheritdoc />
     public void ClearCompiledScripts() => _cache.Clear();
 
-    private static IReadOnlyDictionary<string, DataValueSnapshot> BuildReadCache(
-        IReadOnlyDictionary<string, object?> deps)
-    {
-        // VirtualTagContext.GetTag returns a DataValueSnapshot — we wrap each raw dep value
-        // as Good-quality so the script's `(int)ctx.GetTag("a").Value` pattern works. Null
-        // values stay null; the script can null-check via GetTag(path).Value.
-        var nowUtc = DateTime.UtcNow;
-        var cache = new Dictionary<string, DataValueSnapshot>(StringComparer.Ordinal);
-        foreach (var kv in deps)
-        {
-            cache[kv.Key] = new DataValueSnapshot(kv.Value, StatusCode: 0u, SourceTimestampUtc: nowUtc, ServerTimestampUtc: nowUtc);
-        }
-        return cache;
-    }
-
     /// <summary>Disposes the evaluator and cleans up all cached script evaluators.</summary>
     public void Dispose()
     {