feat(scripting): Scripting:Runner=Shadow — in-process results published, each compiled run mirrored to the ScriptWorker pool and compared (lmxopcua#780 P2)

- ShadowScriptRunner (Core.Scripting): IScriptShadow.Mirror copies the inputs and queues the shadow run on the
  pool; compares value (structural), CLR type, status and failure class (compile / budget / threw+message /
  unsupported_type); runner-fault shadow outcomes (Unavailable, worker busy) are not compared. Bounded:
  Scripting:Shadow:MaxInFlight (256) and one per script; drops counted (behind | key_busy).
- Metrics otopcua.script.shadow.{compared,mismatch{script},dropped,inflight}; one rate-limited Warning per
  script and reason with a diff summary (Scripting:Shadow:MismatchLogsPerMinute, re-armed at the seam's deploy).
- The VirtualTag, Calculation and scripted-alarm seams recognise the shadow and keep their in-process path
  byte-for-byte (no coalescer, one-at-a-time pump, in-process engine), mirroring after each compiled run.
- ScriptRunnerSelection builds the shadow over an OutOfProcessScriptRunner whose lines carry
  ScriptRunnerRole=Shadow; Status() is null under Shadow so readiness never sees the shadow pool; the
  script-runner health entry stays Healthy and reports the shadow counters as data.
- docker-dev/docker-compose.script-runner-shadow.yml; docs/VirtualTags.md "Shadow mode".
- Tests: comparison table, per-script metric + once-per-reason log, rate limit, hung/blocking/throwing shadow
  never reaches the caller, MaxInFlight drop accounting, input copy; real-worker divergent + unsupported-type
  scripts counted against exactly those scripts, a worker-only runaway killed/quarantined there with every
  published value intact, alarm transitions identical to in process across a kill -9 of the shadow worker.
  Mutation-proved (16 mutants, 15 red; the one survivor added an assertion).

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-10 07:18:40 -05:00
parent 0796928504
commit 03686eb5d7
17 changed files with 1477 additions and 52 deletions
@@ -76,4 +76,23 @@ public sealed class ScriptRunnerHealthCheckTests
(await check.CheckHealthAsync(new HealthCheckContext { Registration = registration }, CancellationToken.None))
.Status.ShouldBe(HealthStatus.Healthy);
}
[Theory]
[InlineData(ScriptRunnerState.Ready)]
[InlineData(ScriptRunnerState.Degraded)]
[InlineData(ScriptRunnerState.Unavailable)]
public void Shadow_is_healthy_whatever_its_worker_pool_does(ScriptRunnerState shadowState)
{
// lmxopcua#780 P2: under Shadow every published value is in process — the shadow pool must never move readiness.
var stats = new ZB.MOM.WW.OtOpcUa.Core.Scripting.ScriptShadowStats(10, 7, 3, 1, 2, 1, 0);
var (status, description, data) = ScriptRunnerHealthDecision.Evaluate(
null, (Status(shadowState, Shard("0", shadowState == ScriptRunnerState.Ready, 200)), stats));
status.ShouldBe(HealthStatus.Healthy);
description.ShouldContain("Shadow");
description.ShouldContain("3 mismatch(es)");
data["mode"].ShouldBe("Shadow");
data["shadow.state"].ShouldBe(shadowState.ToString());
data["shadow.mismatched"].ShouldBe(3L);
data["shadow.dropped"].ShouldBe(3L);
}
}