fix(scripting): review minors: configured limit in summaries, dispose gate/CTS, validator, docs (fix round 1)

- ScriptLogRateLimiter.LimitPerWindow. The ScriptLogTopicSink and VirtualTagActor summaries now print the configured limit, not DefaultLimitPerWindow. Tests assert "limit N/window" for a non-default N. - CalculationDriver.Dispose cancels, then takes _evalGate (bounded 2 s) and disposes the gate and _evalCts. The pump and timer ticks enter the gate through TryEnterEvalGateAsync, which stops cleanly once the driver is disposed. Test: Dispose with a 6 s runaway run in flight returns promptly, disposes both, and a late trigger is harmless. - ScriptedAlarmEngine captures _shutdownToken once and disposes _shutdownCts in Dispose when every drained task has completed. A task stuck past the grace leaves the CTS to the GC. Lifecycle tests assert the disposal. - DraftValidator: CalculationNoEffectiveTrigger is skipped for a change-triggered tag whose scriptId does not resolve. That case is already CalculationScriptMissing or CalculationScriptNotFound, and there are no reads to count. Both existing tests now assert the absence (red before the change). - docs/VirtualTags.md: System.Threading is denied as a whole namespace, with an allow-list; the type list is now accurate (Unsafe, RuntimeHelpers, and the ForbiddenMembers on System.Type); the resource limits section covers the run guard and the allocation budget. docs/ScriptEditor.md: accurate deny-list and a new "Runtime safety" section covering timeout, refusal, quarantine after 3 timeouts, allocation budget, lifting, and rate-limit summaries that appear only on the source's next entry after a burst then quiet. Refs #734 Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT
2026-10-22 13:41:15 -04:00
parent ad6be56850
commit ef2eebe6b6
13 changed files with 161 additions and 18 deletions
@@ -55,7 +55,10 @@ public sealed class DraftValidatorCalculationTests
            Tags = [CalcTagRow("t-1", "dev-1", "a", "{\"changeTriggered\":true}")],
        };

-        DraftValidator.Validate(draft).ShouldContain(e => e.Code == "CalculationScriptMissing" && e.Context == "t-1");
+        var errors = DraftValidator.Validate(draft);
+        errors.ShouldContain(e => e.Code == "CalculationScriptMissing" && e.Context == "t-1");
+        errors.ShouldNotContain(e => e.Code == "CalculationNoEffectiveTrigger",
+            "an unresolved script has no reads to count — the missing script is the one error to report");
    }

    [Fact]
@@ -70,7 +73,10 @@ public sealed class DraftValidatorCalculationTests
            Scripts = [],
        };

-        DraftValidator.Validate(draft).ShouldContain(e => e.Code == "CalculationScriptNotFound" && e.Context == "t-1");
+        var errors = DraftValidator.Validate(draft);
+        errors.ShouldContain(e => e.Code == "CalculationScriptNotFound" && e.Context == "t-1");
+        errors.ShouldNotContain(e => e.Code == "CalculationNoEffectiveTrigger",
+            "an unresolved script has no reads to count — the missing script is the one error to report");
    }

    [Fact]
@@ -82,6 +82,7 @@ public sealed class ScriptedAlarmEngineLifecycleTests
        sw.Elapsed.ShouldBeLessThan(TimeSpan.FromSeconds(5), "the drain is bounded; a hung store cannot hang shutdown");
        await WaitForAsync(() => store.ObservedCancellation, timeoutMs: 2000);
        store.ObservedCancellation.ShouldBeTrue("the in-flight save was cancelled through the engine's shutdown token");
+        eng.ShutdownCtsDisposedForTest.ShouldBeTrue("the cancelled save completed inside the grace, so the CTS is released");
    }

    [Fact]
@@ -105,6 +106,8 @@ public sealed class ScriptedAlarmEngineLifecycleTests
        store.SaveInProgress.ShouldBeFalse();
        store.ObservedCancellation.ShouldBeFalse("a save that completes within the bound is never cancelled");
        store.Saved.ShouldContain("A");
+        eng.ShutdownCtsDisposedForTest.ShouldBeTrue("every background task completed, so the shutdown CTS is disposed");
+        Should.NotThrow(() => eng.OnUpstreamChange("Temp", new DataValueSnapshot(1, 0u, DateTime.UtcNow, DateTime.UtcNow)));
    }

    private static async Task WaitForAsync(Func<bool> cond, int timeoutMs = 5000)
@@ -59,6 +59,9 @@ public sealed class ScriptLogRateLimiterTests
        ScriptLogRateLimiter.DefaultLimitPerWindow.ShouldBe(20);
        ScriptLogRateLimiter.DefaultWindow.ShouldBe(TimeSpan.FromMinutes(1));
        var limiter = new ScriptLogRateLimiter();
+        limiter.LimitPerWindow.ShouldBe(20);
+        new ScriptLogRateLimiter(limitPerWindow: 3).LimitPerWindow.ShouldBe(3);
+        new ScriptLogRateLimiter(limitPerWindow: 0).LimitPerWindow.ShouldBe(1, "values below 1 are treated as 1");
        for (var i = 0; i < 20; i++) limiter.Admit("s").Admitted.ShouldBeTrue();
        limiter.Admit("s").Admitted.ShouldBeFalse();
    }
@@ -101,6 +104,7 @@ public sealed class ScriptLogRateLimiterTests
        var summary = s1[2];
        summary.Message.ShouldContain("3");
        summary.Message.ShouldContain("suppressed");
+        summary.Message.ShouldContain("limit 2/window", Case.Sensitive, "the summary names the CONFIGURED limit, not the default");
        summary.VirtualTagId.ShouldBe("V1", "the summary carries the source's identity so the page attributes it");
        summary.Level.ShouldBe("Warning");
        s1[3].Message.ShouldBe("chatty again");
@@ -50,6 +50,29 @@ public sealed class CalculationDriverRemediationTests
        driver.IsEvaluationIdle.ShouldBeTrue("the calc driver's evaluation pump should have drained");
    }

+    /// <summary>Fix round 1 minor: Dispose releases the evaluation gate and its cancellation source — even
+    /// with a runaway run in flight (the guard lets the caller's cancel win, so the awaited run returns
+    /// promptly) — and a trigger arriving after Dispose is harmless.</summary>
+    [Fact]
+    public async Task Dispose_with_a_run_in_flight_disposes_the_eval_gate_and_a_late_trigger_is_harmless()
+    {
+        var (driver, _, _, _) = Build(
+            CalcTag("calc/e/spin", "var v = ctx.GetTag(\"src/a\").Value; var end = System.DateTime.UtcNow.AddSeconds(6); while (System.DateTime.UtcNow < end) { } return 1;"));
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        driver.OnDependencyValue("src/a", 1, StatusGood, DateTime.UtcNow);
+        var deadline = DateTime.UtcNow.AddSeconds(10);
+        while (driver.IsEvaluationIdle && DateTime.UtcNow < deadline) await Task.Delay(5);
+        driver.IsEvaluationIdle.ShouldBeFalse("positive control: a run is in flight when Dispose lands");
+
+        var sw = System.Diagnostics.Stopwatch.StartNew();
+        driver.Dispose();
+        sw.Elapsed.ShouldBeLessThan(TimeSpan.FromSeconds(5), "the caller's cancel releases the awaited run; Dispose is not held for the 6 s spin");
+        driver.EvalResourcesDisposedForTest.ShouldBeTrue();
+
+        Should.NotThrow(() => driver.OnDependencyValue("src/a", 2, StatusGood, DateTime.UtcNow));
+        Should.NotThrow(() => driver.Dispose());
+    }
+
    [Fact]
    public async Task A_compile_failure_is_remembered_and_logged_once_across_repeated_triggers()
    {
@@ -43,6 +43,7 @@ public sealed class VirtualTagActorFailureLogRateLimitTests : RuntimeActorTestBa
        var entries = capture.ToArray();
        entries[3].Message.ShouldContain("7");
        entries[3].Message.ShouldContain("suppressed");
+        entries[3].Message.ShouldContain("limit 3/window", Case.Sensitive, "the summary names the CONFIGURED limit, not the default");
        entries[3].VirtualTagId.ShouldBe("vt-chatty");
        entries[4].Message.ShouldBe("boom");
    }