feat(commons): additive Trace flag + ChildExecutionId/TraceEvents on route/call/write/change records

Flow Debugger (design 2026-09-05 §5.2/§5.4): Trace rides beside ParentExecutionId on
RouteToCallRequest/RouteToSetAttributesRequest/ScriptCallRequest/SetStaticAttributeCommand/
AttributeValueChanged; RouteToCallResponse and ScriptCallResult carry the site run's
ExecutionId and its ScriptTrace AuditEvents inline. All trailing optional — zero call-site edits.

Claude-Session: https://claude.ai/code/session_01GSLkkHKz9JrAtmJjmQK3cP

src/ZB.MOM.WW.ScadaBridge.Commons/Messages/InboundApi/RouteToInstanceRequest.cs

@@ -1,3 +1,5 @@
+using ZB.MOM.WW.Audit;
+
 namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.InboundApi;
 
 /// <summary>
@@ -12,23 +14,29 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.InboundApi;
 /// Additive trailing member — null for requests built before the field existed
 /// or for routed calls with no spawning execution (e.g. the Central UI sandbox).
 /// </param>
+/// <param name="Trace">Flow Debugger trace flag — see design 2026-09-05 §5.2. Additive; defaults to untraced.</param>
 public record RouteToCallRequest(
     string CorrelationId,
     string InstanceUniqueName,
     string ScriptName,
     IReadOnlyDictionary<string, object?>? Parameters,
     DateTimeOffset Timestamp,
-    Guid? ParentExecutionId = null);
+    Guid? ParentExecutionId = null,
+    bool Trace = false);
 
 /// <summary>
 /// Response from a Route.To() call.
 /// </summary>
+/// <param name="ChildExecutionId">Flow Debugger — the routed site run's <c>ExecutionId</c> (design 2026-09-05 §5.4); null from a site that predates the field.</param>
+/// <param name="TraceEvents">Flow Debugger — the site's <c>ScriptTrace</c> audit events for a traced run, in emission order (design 2026-09-05 §5.4); null when untraced or from an older site.</param>
 public record RouteToCallResponse(
     string CorrelationId,
     bool Success,
     object? ReturnValue,
     string? ErrorMessage,
-    DateTimeOffset Timestamp);
+    DateTimeOffset Timestamp,
+    Guid? ChildExecutionId = null,
+    IReadOnlyList<AuditEvent>? TraceEvents = null);
 
 /// <summary>
 /// Request to read attribute(s) from a remote instance.
@@ -68,12 +76,14 @@ public record RouteToGetAttributesResponse(
 /// write path. Additive trailing member — null for the Central UI sandbox path or for
 /// callers built before the field existed.
 /// </param>
+/// <param name="Trace">Flow Debugger trace flag — see design 2026-09-05 §5.2. Additive; defaults to untraced.</param>
 public record RouteToSetAttributesRequest(
     string CorrelationId,
     string InstanceUniqueName,
     IReadOnlyDictionary<string, string> AttributeValues,
     DateTimeOffset Timestamp,
-    Guid? ParentExecutionId = null);
+    Guid? ParentExecutionId = null,
+    bool Trace = false);
 
 /// <summary>
 /// Response confirming attribute writes on a remote instance.

src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Instance/SetStaticAttributeCommand.cs

@@ -19,13 +19,15 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.Instance;
 /// <c>AttributeValueChanged</c> so an alarm the write trips can record it as the
 /// on-trigger script run's <c>ParentExecutionId</c>.
 /// </param>
+/// <param name="Trace">Flow Debugger trace flag — see design 2026-09-05 §5.2. Additive; defaults to untraced.</param>
 public record SetStaticAttributeCommand(
     string CorrelationId,
     string InstanceUniqueName,
     string AttributeName,
     string Value,
     DateTimeOffset Timestamp,
-    Guid? SourceExecutionId = null);
+    Guid? SourceExecutionId = null,
+    bool Trace = false);
 
 /// <summary>
 /// Response confirming that a static attribute was set.

src/ZB.MOM.WW.ScadaBridge.Commons/Messages/ScriptExecution/ScriptCallRequest.cs

@@ -9,9 +9,11 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.ScriptExecution;
 /// null for normal (tag-change / timer-triggered) runs, nested <c>Script.Call</c>
 /// invocations, and any request built before the field existed.
 /// </param>
+/// <param name="Trace">Flow Debugger trace flag — see design 2026-09-05 §5.2. Additive; defaults to untraced.</param>
 public record ScriptCallRequest(
     string ScriptName,
     IReadOnlyDictionary<string, object?>? Parameters,
     int CurrentCallDepth,
     string CorrelationId,
-    Guid? ParentExecutionId = null);
+    Guid? ParentExecutionId = null,
+    bool Trace = false);

src/ZB.MOM.WW.ScadaBridge.Commons/Messages/ScriptExecution/ScriptCallResult.cs

@@ -1,7 +1,13 @@
+using ZB.MOM.WW.Audit;
+
 namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.ScriptExecution;
 
+/// <param name="ExecutionId">Flow Debugger — the run's own <c>ExecutionId</c> (design 2026-09-05 §5.4). Additive; null from callers that predate the field.</param>
+/// <param name="TraceEvents">Flow Debugger — the run's <c>ScriptTrace</c> audit events in emission order when traced (design 2026-09-05 §5.4); null otherwise.</param>
 public record ScriptCallResult(
     string CorrelationId,
     bool Success,
     object? ReturnValue,
-    string? ErrorMessage);
+    string? ErrorMessage,
+    Guid? ExecutionId = null,
+    IReadOnlyList<AuditEvent>? TraceEvents = null);

src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Streaming/AttributeValueChanged.cs

@@ -33,6 +33,7 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.Streaming;
 /// Actor, and central reads the linkage from the audit rows instead.
 /// </para>
 /// </param>
+/// <param name="Trace">Flow Debugger trace flag — see design 2026-09-05 §5.2. Additive; defaults to untraced.</param>
 public record AttributeValueChanged(
     string InstanceUniqueName,
     string AttributePath,
@@ -40,4 +41,5 @@ public record AttributeValueChanged(
     object? Value,
     string Quality,
     DateTimeOffset Timestamp,
-    Guid? SourceExecutionId = null) : ISiteStreamEvent;
+    Guid? SourceExecutionId = null,
+    bool Trace = false) : ISiteStreamEvent;

tests/ZB.MOM.WW.ScadaBridge.Commons.Tests/Messages/TraceFlagDefaultsTests.cs

@@ -0,0 +1,53 @@
+using ZB.MOM.WW.Audit;
+using ZB.MOM.WW.ScadaBridge.Commons.Messages.InboundApi;
+using ZB.MOM.WW.ScadaBridge.Commons.Messages.Instance;
+using ZB.MOM.WW.ScadaBridge.Commons.Messages.ScriptExecution;
+using ZB.MOM.WW.ScadaBridge.Commons.Messages.Streaming;
+
+namespace ZB.MOM.WW.ScadaBridge.Commons.Tests.Messages;
+
+/// <summary>
+/// Flow Debugger (design 2026-09-05 §5.2/§5.4): the trace flag and trace payload are additive
+/// trailing optional members — every pre-existing positional construction stays untraced.
+/// </summary>
+public class TraceFlagDefaultsTests
+{
+    [Fact]
+    public void ExistingPositionalConstructions_DefaultToUntraced()
+    {
+        var now = DateTimeOffset.UtcNow;
+        Assert.False(new RouteToCallRequest("c", "i", "s", null, now).Trace);
+        Assert.False(new RouteToSetAttributesRequest("c", "i", new Dictionary<string, string>(), now).Trace);
+        Assert.False(new ScriptCallRequest("s", null, 0, "c").Trace);
+        Assert.False(new SetStaticAttributeCommand("c", "i", "a", "v", now).Trace);
+        Assert.False(new AttributeValueChanged("i", "p", "a", 1, "Good", now).Trace);
+
+        var reply = new RouteToCallResponse("c", true, null, null, now);
+        Assert.Null(reply.ChildExecutionId);
+        Assert.Null(reply.TraceEvents);
+
+        var result = new ScriptCallResult("c", true, null, null);
+        Assert.Null(result.ExecutionId);
+        Assert.Null(result.TraceEvents);
+    }
+
+    [Fact]
+    public void TraceEvents_AreAuditEvents()
+    {
+        var evt = new AuditEvent
+        {
+            EventId = Guid.NewGuid(),
+            OccurredAtUtc = DateTimeOffset.UtcNow,
+            Actor = "a",
+            Action = "ScriptTrace.ScriptRun",
+            Outcome = AuditOutcome.Success
+        };
+        var result = new ScriptCallResult("c", true, null, null, Guid.NewGuid(), [evt]);
+        Assert.Single(result.TraceEvents!);
+        Assert.NotNull(result.ExecutionId);
+
+        var reply = new RouteToCallResponse("c", true, null, null, DateTimeOffset.UtcNow, result.ExecutionId, result.TraceEvents);
+        Assert.Equal(result.ExecutionId, reply.ChildExecutionId);
+        Assert.Same(evt, reply.TraceEvents![0]);
+    }
+}