feat(scripting): PE cache, quarantine-race fix, recovery, readiness for the out-of-process runner (lmxopcua#780 P1)
v2-ci / unit-tests (push) Failing after 1h12m10s

Second P1 slice of docs/plans/2026-11-09-out-of-process-script-runner-design.md; still opt-in behind
Scripting:Runner=OutOfProcess (InProcess unchanged).

- Compiled-PE cache (design §7, §14 #8): Scripting:Worker:PeCacheDir holds <dir>/pe/<id>.pe entries authenticated
  with HMAC-SHA256 under a per-node random key (<dir>/pe-cache.key, created by the host, 0600/0700 on Unix), handed to
  the worker in Hello. Entry id = SHA-256(compile fingerprint + kind + source); the fingerprint covers the Roslyn
  version, the Core.Scripting build (analyzer, wrapper, stack guard), the sandbox reference set and the runtime. Edited,
  truncated, other-key or renamed entries are rejected, deleted and recompiled; the worker never loads unverified bytes.
  Pruned by recency at startup (30 d / 50 000). ScriptEvaluator splits into CompileToImage + FromImage. Measured on
  40 scripts, restart to every first result: macOS 820 ms no cache / 840 ms empty / 85 ms warm;
  windev (Windows) 9.5 s / 9.4 s / 1.0 s.
- Quarantine race: WorkerConnection runs exit attribution synchronously BEFORE completing the evaluations/loads it held
  (and before Exited), and the shard passes it straight to the runner — a kill strike is in place before the killed
  key's slot is released.
- Supervision: a dead worker restarts by itself after its backoff; Unavailable outcomes carry ScriptRunOutcome.Recovery
  (-> VirtualTagEvalResult.RetryWhen) and the VT actor / Calculation driver re-evaluate once against current inputs when
  it completes. Isolation worker stops after Scripting:Worker:IsolationIdleTimeout (10 min). Keys compiling when a
  worker dies are suspects too (isolation finds a poison compile and quarantines it). Startup orphan sweep by launch
  marker: kills only a process whose marker's host is gone and whose pid + start time + image match.
- Crash-loop circuit (Scripting:Worker:CircuitOpenAfter, 2 min): runner Unavailable, one Error, evaluations answered
  at once while shards keep retrying at the cap.
- Observability (§10): otopcua.script.runner.state, worker.up/inflight/queue_depth/heap_bytes (shard),
  ipc.roundtrip + eval.duration (kind), compile{cache}, isolation.suspects, exits reason=idle. `script-runner` health
  check on the ready tier, at worst Degraded (§14 #12: degraded but still ready).

Left on #780: self-contained worker publish, installer (account, pipe ACL, firewall), docker-dev live drill,
scripted-alarm seam, the §4.5 per-seam batch submit, the §8 perf harness.

Tests: SupervisionTests, PeCacheStoreTests/PeCacheWorkerTests (real workers), ScriptRunnerHealthCheckTests, VT + Calc
recovery seam tests; 14 mutations each turned their test red.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-10 00:20:24 -05:00
parent 69a6e0b4c8
commit f50b29abae
27 changed files with 2291 additions and 78 deletions
@@ -74,6 +74,12 @@ public sealed class ScriptWorkerOptions
/// <summary>Default <see cref="IsolationProbationRuns"/>: 20.</summary>
public const int DefaultIsolationProbationRuns = 20;
/// <summary>Default <see cref="IsolationIdleTimeout"/>: 10 min (design §3.3).</summary>
public static readonly TimeSpan DefaultIsolationIdleTimeout = TimeSpan.FromMinutes(10);
/// <summary>Default <see cref="CircuitOpenAfter"/>: 2 min (design §5.3.6).</summary>
public static readonly TimeSpan DefaultCircuitOpenAfter = TimeSpan.FromMinutes(2);
/// <summary>Shard workers per node; a script is placed by a stable hash of its key. Clamped to 1–8.</summary>
public int Shards { get; set; } = DefaultShards;
@@ -102,9 +108,22 @@ public sealed class ScriptWorkerOptions
public int IsolationProbationRuns { get; set; } = DefaultIsolationProbationRuns;
/// <summary>
/// Directory of the node-local compiled-PE cache (design §7). Must be absolute and outside the content root
/// when set; startup fails otherwise (the family's fail-closed path rule). Reserved: the cache itself has
/// not landed yet (lmxopcua#780 P1 remainder), so a worker restart recompiles.
/// How long the isolation worker may sit with nothing to run before it is stopped (it is started again by the
/// next suspect). Default 10 min; 1 s – 24 h.
/// </summary>
public TimeSpan IsolationIdleTimeout { get; set; } = DefaultIsolationIdleTimeout;
/// <summary>
/// The crash-loop circuit (design §5.3.6): when every shard worker has been down for this long, the runner
/// reports <c>Unavailable</c>, logs one Error and answers evaluations at once (no <see cref="UnavailableGrace"/>
/// wait) while it keeps retrying at the backoff cap. Default 2 min; 1 s – 1 h.
/// </summary>
public TimeSpan CircuitOpenAfter { get; set; } = DefaultCircuitOpenAfter;
/// <summary>
/// Directory of the node-local compiled-PE cache (design §7): HMAC-authenticated PE images, so a worker restart
/// does not re-enter Roslyn. Must be absolute and outside the content root when set; startup fails otherwise
/// (the family's fail-closed path rule). Null (the default) runs without a cache: every worker start recompiles.
/// </summary>
public string? PeCacheDir { get; set; }
@@ -175,9 +194,27 @@ public sealed class ScriptWorkerOptions
probation = clamped;
}
var idle = IsolationIdleTimeout;
if (idle < TimeSpan.FromSeconds(1) || idle > TimeSpan.FromHours(24))
{
var clamped = idle < TimeSpan.FromSeconds(1) ? TimeSpan.FromSeconds(1) : TimeSpan.FromHours(24);
notes.Add($"{prefix}{nameof(IsolationIdleTimeout)} {idle} is outside 00:00:01–1.00:00:00; clamped to {clamped}.");
idle = clamped;
}
var circuit = CircuitOpenAfter;
if (circuit < TimeSpan.FromSeconds(1) || circuit > TimeSpan.FromHours(1))
{
var clamped = circuit < TimeSpan.FromSeconds(1) ? TimeSpan.FromSeconds(1) : TimeSpan.FromHours(1);
notes.Add($"{prefix}{nameof(CircuitOpenAfter)} {circuit} is outside 00:00:01–01:00:00; clamped to {clamped}.");
circuit = clamped;
}
adjustments = notes;
return new ScriptWorkerOptions
{
IsolationIdleTimeout = idle,
CircuitOpenAfter = circuit,
Shards = shards,
HardGrace = grace,
HeapLimitBytes = heap,