From 871273231146c3fa42ac2d50d8f777c2b7f18b13 Mon Sep 17 00:00:00 2001
From: Joseph Doherty <dohejw01@gmail.com>
Date: Tue, 8 Sep 2026 01:07:27 -0400
Subject: [PATCH] =?UTF-8?q?feat(commons):=20FlowDebugRunScriptCommand=20?=
 =?UTF-8?q?=E2=80=94=20additive=20management=20command=20for=20the=20flow?=
 =?UTF-8?q?=20debugger=20script=20entry?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude-Session: https://claude.ai/code/session_01NcMG6xXdsJbmD2wYAgkK29
---
 .../Messages/Management/FlowDebugCommands.cs  | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/FlowDebugCommands.cs b/src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/FlowDebugCommands.cs
index 7231b1e9..42e89448 100644
--- a/src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/FlowDebugCommands.cs
+++ b/src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/FlowDebugCommands.cs
@@ -24,6 +24,27 @@ public record FlowDebugRunMethodCommand(int ApiMethodId, JsonElement? Parameters
 /// <param name="WaitSeconds">How long to wait for a spawned run before reporting <c>NO_TRIGGER_WITHIN_WINDOW</c>.</param>
 public record FlowDebugRunValueChangeCommand(int InstanceId, string AttributeName, string Value, int WaitSeconds = 45);
 
+/// <summary>
+/// Flow Debugger Live run of a site script by name (design 2026-09-08). The runner resolves the
+/// script's effective definition from the flattened instance configuration and branches on its
+/// trigger kind: a <c>ValueChange</c>/<c>Conditional</c> script is fired by WRITING its monitored
+/// attribute (<paramref name="Value"/>) and polling for the spawned run, exactly like
+/// <see cref="FlowDebugRunValueChangeCommand"/>; every other kind is invoked DIRECTLY through the
+/// traced routed-call path with <paramref name="Parameters"/>. Deployer role; refuses on a standby
+/// with <c>STANDBY_NODE</c>.
+/// </summary>
+/// <param name="InstanceId">The instance the script belongs to.</param>
+/// <param name="ScriptName">Canonical script name from the flattened configuration (case-insensitive).</param>
+/// <param name="Parameters">Call kinds: flat JSON object validated against the script's ParameterDefinitions; null = none.</param>
+/// <param name="Value">Write kinds: canonical string value to write to the trigger's attribute.</param>
+/// <param name="WaitSeconds">Write kinds: how long to wait for a spawned run before <c>NO_TRIGGER_WITHIN_WINDOW</c>.</param>
+public record FlowDebugRunScriptCommand(
+    int InstanceId,
+    string ScriptName,
+    JsonElement? Parameters,
+    string? Value,
+    int WaitSeconds = 45);
+
 /// <summary>
 /// Flow Debugger Replay (design 2026-09-05 §7.1): returns the audit events of the execution
 /// tree that <paramref name="ExecutionId"/> belongs to, from the central store.