From 2dc9c0ca36e92ca340bb649b3966561528109c1a Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Thu, 12 Nov 2026 18:16:27 +0800 Subject: [PATCH 01/15] Integrate optional epoch callback deadline onto current main Ports the reviewed 2026-11-10 epoch experiment onto origin/main cbac2a6: opt-in MapDeadlineMode (Clock default, Epoch explicit), the shared CallbackEpochTicker lease with diagnostics, and the additive CallbackDeadlineBridge capability gate. A runtime without the epoch capability fails before author files are opened; no silent downgrade. The only delta beyond the reviewed snapshot is a whitespace-only EOF fix in CallbackEpochTicker.cs so the branch is diff --check clean; the archive branch keeps its original bytes. Verification: stock build 0 warnings/0 errors, Runtime.Tests 156/156, epoch tests 5 passed / 19 skipped (matching private runtime absent) / 0 failed. Epoch enforcement with a matching runtime remains pending. Assisted-by: Cindy (https://cindy.app) --- RuneCLR.slnx | 2 + ...nal-epoch-deadline-integration-20261112.md | 47 ++ eng/verify-epoch-integration.py | 126 ++++ src/RuneCLR.Runtime/CallbackDeadlineBridge.cs | 112 ++- .../CallbackEpochDiagnostics.cs | 23 + src/RuneCLR.Runtime/CallbackEpochTicker.cs | 391 ++++++++++ src/RuneCLR.Runtime/MapRunOptions.cs | 32 +- src/RuneCLR.Runtime/MapSession.cs | 44 +- .../EpochDeadline.Author.csproj | 5 + tests/EpochDeadline.Author/Scripts.cs | 197 +++++ tests/RuneCLR.EpochDeadline.Tests/Program.cs | 710 ++++++++++++++++++ .../RuneCLR.EpochDeadline.Tests.csproj | 11 + 12 files changed, 1680 insertions(+), 20 deletions(-) create mode 100644 docs/experiments/optional-epoch-deadline-integration-20261112.md create mode 100644 eng/verify-epoch-integration.py create mode 100644 src/RuneCLR.Runtime/CallbackEpochDiagnostics.cs create mode 100644 src/RuneCLR.Runtime/CallbackEpochTicker.cs create mode 100644 tests/EpochDeadline.Author/EpochDeadline.Author.csproj create mode 100644 tests/EpochDeadline.Author/Scripts.cs create mode 100644 tests/RuneCLR.EpochDeadline.Tests/Program.cs create mode 100644 tests/RuneCLR.EpochDeadline.Tests/RuneCLR.EpochDeadline.Tests.csproj diff --git a/RuneCLR.slnx b/RuneCLR.slnx index 70be0b3..9cfe72c 100644 --- a/RuneCLR.slnx +++ b/RuneCLR.slnx @@ -36,6 +36,8 @@ + + diff --git a/docs/experiments/optional-epoch-deadline-integration-20261112.md b/docs/experiments/optional-epoch-deadline-integration-20261112.md new file mode 100644 index 0000000..e187392 --- /dev/null +++ b/docs/experiments/optional-epoch-deadline-integration-20261112.md @@ -0,0 +1,47 @@ +# Optional epoch callback deadline — host integration (2026-11-12) + +This branch integrates the reviewed 2026-11-10 epoch callback-deadline experiment onto the +current RuneCLR `origin/main` (cbac2a657793dca7f22b1e1feff4aab26b898b4e). It replaces the +archive branch `experiment/optional-epoch-deadline-20261112` (base bdbc7f52) as the host +integration line; that branch stays untouched as the sealed source snapshot. + +## What is integrated + +- `MapDeadlineMode` (`Clock` default, `Epoch` opt-in) plus the epoch period on `MapRunOptions`. +- `CallbackEpochTicker` (process-wide lease, single shared ticker) and + `CallbackEpochDiagnostics`, ported unchanged from the reviewed experiment. +- `CallbackDeadlineBridge` gains the additive epoch factory, tick/read delegates and the + capability check; `MapSession` leases the ticker before any author file is opened and releases + it after the author stack has returned. +- Epoch tests and the acceptance script from the experiment. + +The clock path is unchanged and remains the default. Epoch mode is explicit: a runtime without +the additive capability (version-1 clock ABI plus capability bit 2 plus the epoch factory/tick/ +read entry points) fails before author files are opened, never silently downgrades. + +## Difference from the archive snapshot + +- The only source edit beyond the reviewed experiment is whitespace: the trailing blank line at + the end of `CallbackEpochTicker.cs` (the archive has a CRLF blank line at EOF) is removed so + this branch is `git diff --check` clean. The archive branch keeps its original bytes. +- No other behaviour changes. + +## Verification status + +- Stock desktop build: `dotnet build RuneCLR.slnx -c Release` — 0 warnings, 0 errors. +- Stock regression: `tests/RuneCLR.Runtime.Tests` — 156/156 passed. +- Epoch tests on stock runtime: 5 passed, 19 skipped (matching private CoreCLR/native runtime not + present), 0 failed. Epoch enforcement is therefore **pending a matching runtime build**; the + 2026-11-10 campaign numbers come from the archived binaries and do not validate this branch. +- Native JIT/R2R remains a future direction: this work is an interpreter callback deadline. + +## Runtime expectation + +Matching runtime must provide, on `System.Runtime.Loader.AssemblyLoadContext`: + +- `RuneCLR_GetCallbackDeadlineVersion() -> long` returning 1 (existing clock ABI); +- `RuneCLR_GetCallbackDeadlineCapabilities() -> int` with bit 2 set for epoch support; +- `RuneCLR_CreateCallbackDeadlineEpoch(name, resolver, deadlineTicks, pollInterval, cleanupBudget, epochPeriodMicros)`; +- `RuneCLR_TickCallbackDeadlineEpoch() -> long` and `RuneCLR_ReadCallbackDeadlineEpoch() -> long`. + +The native side (reviewer5) owns that runtime delta; this branch is host-only. diff --git a/eng/verify-epoch-integration.py b/eng/verify-epoch-integration.py new file mode 100644 index 0000000..41b6c45 --- /dev/null +++ b/eng/verify-epoch-integration.py @@ -0,0 +1,126 @@ +#!/usr/bin/env python3 +"""Acceptance for the optional 10 ms epoch callback deadline in the RuneCLR host. + +Pins every input before the run, requires the frozen Release runtime outputs to +equal the layout copies, runs the epoch-deadline test harness against that +layout, and re-pins afterwards (zero drift required). +""" +import argparse +import hashlib +import json +import os +from pathlib import Path +import subprocess +import sys + +NL = chr(10) + + +def digest(path): + with path.open("rb") as stream: + return hashlib.file_digest(stream, "sha256").hexdigest() + + +def git(root, *args): + return subprocess.check_output(["git", "-C", str(root), *args], text=True).strip() + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument("--host-root", type=Path, default=Path(__file__).resolve().parents[1]) + parser.add_argument("--layout", required=True, type=Path) + parser.add_argument("--runtime-root", required=True, type=Path) + parser.add_argument("--source-manifest", required=True, type=Path) + parser.add_argument("--output", required=True, type=Path) + parser.add_argument("--framework-version", default="12.0.0") + parser.add_argument("--build-rid", default="windows.x64.Release") + parser.add_argument("--timeout", type=int, default=900) + args = parser.parse_args() + + root = args.host_root.resolve() + layout = args.layout.resolve() + runtime = args.runtime_root.resolve() + output = args.output.resolve() + if output.exists(): + raise ValueError("Output must be a new directory.") + output.mkdir(parents=True) + + manifest = json.loads(args.source_manifest.read_text(encoding="utf-8")) + head = git(runtime, "rev-parse", "HEAD") + if head != (manifest.get("head") or manifest.get("baseline_head")): + raise ValueError("Runtime HEAD mismatch: " + head) + files = manifest.get("dirty_files") or manifest.get("files") or {} + status = subprocess.check_output(["git", "-C", str(runtime), "status", "--porcelain", "--untracked-files=normal"], + text=True).splitlines() + changed = sorted(line[3:].strip() for line in status if line.strip()) + if changed != sorted(files): + raise ValueError("Runtime delta does not equal the source manifest.") + for name, value in files.items(): + if digest(runtime / name) != value: + raise ValueError("Source hash mismatch: " + name) + + build = runtime / "artifacts/bin/coreclr" / args.build_rid + shared = layout / "shared/Microsoft.NETCore.App" / args.framework_version + outputs = {"System.Private.CoreLib.dll": "CoreLib", "coreclr.dll": "coreclr", "clrjit.dll": "clrjit", + "clrinterpreter.dll": "clrinterpreter", "corerun.exe": "corerun"} + artifact = {} + for name in outputs: + produced, installed = build / name, shared / name + if not produced.is_file(): + raise ValueError("Runtime artifact output absent (build not terminal): " + str(produced)) + if not installed.is_file(): + raise ValueError("Layout is missing " + name) + if digest(produced) != digest(installed): + raise ValueError("Layout " + name + " does not equal the runtime build output.") + artifact[name] = digest(produced) + + harness = root / "tests/RuneCLR.EpochDeadline.Tests/bin/Release/net11.0/RuneCLR.EpochDeadline.Tests.dll" + inputs = {harness, Path(__file__).resolve(), root / "RuneCLR.slnx", root / "Directory.Build.props", + args.source_manifest} + inputs.update(path for path in harness.parent.rglob("*") if path.is_file()) + for folder in (root / "src", root / "tests"): + inputs.update(path for path in folder.rglob("*") if path.is_file() + and not {"bin", "obj"}.intersection(path.relative_to(folder).parts)) + inputs.update(path for path in layout.rglob("*") if path.is_file()) + inputs.update(build / name for name in outputs) + pins = {str(path): digest(path) for path in sorted(inputs) if path.is_file()} + write = output / "pins-before.json" + write.write_text(json.dumps(pins, indent=2) + NL, encoding="utf-8") + + environment = {k: v for k, v in os.environ.items() if not k.startswith(("DOTNET_", "COMPlus_"))} + environment.update({"DOTNET_MULTILEVEL_LOOKUP": "0", "DOTNET_RuneCLRInterpretCollectible": "1", + "DOTNET_InterpMode": "0", "DOTNET_ReadyToRun": "1", "DOTNET_TieredCompilation": "0"}) + command = [str(layout / ("dotnet.exe" if os.name == "nt" else "dotnet")), "exec", + "--fx-version", args.framework_version, str(harness)] + stdout = output / "tests.stdout.log" + stderr = output / "tests.stderr.log" + with stdout.open("wb") as out, stderr.open("wb") as err: + process = subprocess.run(command, cwd=root, env=environment, stdout=out, stderr=err, timeout=args.timeout) + text = stdout.read_text(encoding="utf-8", errors="replace") + print(("PASS" if process.returncode == 0 else "FAIL"), "epoch-deadline tests", + "exit=" + str(process.returncode), "log=" + stdout.name) + if process.returncode != 0: + failures = [line for line in text.splitlines() if line.startswith("FAIL ")] + print(" " + (failures[0] if failures else "see log")) + + after = {str(path): digest(path) if path.is_file() else None for path in sorted(inputs)} + (output / "pins-after.json").write_text(json.dumps(after, indent=2) + NL, encoding="utf-8") + drift = [path for path in pins if pins[path] != after[path]] + summary = {"harnessExit": process.returncode, "pinCount": len(pins), "drift": drift, + "buildRID": args.build_rid, "artifact": artifact, + "sourceIdentity": {"head": head, "deltaFiles": len(files), "localUncommitted": True}, + "layoutFiles": sum(1 for p in layout.rglob("*") if p.is_file())} + (output / "summary.json").write_text(json.dumps(summary, indent=2) + NL, encoding="utf-8") + if drift: + raise RuntimeError("Input drift: " + repr(drift)) + if process.returncode != 0: + raise RuntimeError("Epoch-deadline tests failed.") + print("EPOCH_INTEGRATION PASS; pins=" + str(len(pins)) + "; layout=" + str(summary["layoutFiles"])) + + +if __name__ == "__main__": + try: + main() + except Exception as error: + print("FAIL " + str(error), file=sys.stderr) + raise diff --git a/src/RuneCLR.Runtime/CallbackDeadlineBridge.cs b/src/RuneCLR.Runtime/CallbackDeadlineBridge.cs index fe4c129..6fd4bd5 100644 --- a/src/RuneCLR.Runtime/CallbackDeadlineBridge.cs +++ b/src/RuneCLR.Runtime/CallbackDeadlineBridge.cs @@ -3,19 +3,31 @@ namespace RuneCLR.Runtime; +/// Binds the private callback-deadline surface. The clock factory and its instance methods +/// are the original version-1 contract; the epoch factory, ticker delegates and epoch snapshot +/// fields are additive and are only bound when a session explicitly selects epoch mode. internal sealed class CallbackDeadlineBridge { - private readonly Func, long, int, long, AssemblyLoadContext> _create; + private readonly MapDeadlineMode _mode; + private readonly Func, long, int, long, AssemblyLoadContext> _createClock; + private readonly Func, long, int, long, long, AssemblyLoadContext>? _createEpoch; private readonly Func _begin; private readonly Func _end; private readonly Func _query; + private readonly Func? _tickEpoch; + private readonly Func? _readEpoch; - private CallbackDeadlineBridge() + private CallbackDeadlineBridge(MapDeadlineMode mode, + Func, long, int, long, AssemblyLoadContext> createClock, + Func, long, int, long, long, AssemblyLoadContext>? createEpoch, + Func? tickEpoch, Func? readEpoch) { + _mode = mode; + _createClock = createClock; + _createEpoch = createEpoch; + _tickEpoch = tickEpoch; + _readEpoch = readEpoch; var type = typeof(AssemblyLoadContext); - _create = RequiredInterpreterBridge.Method(type, "RuneCLR_CreateCallbackDeadline", true, - type, typeof(string), typeof(Func), typeof(long), typeof(int), typeof(long)) - .CreateDelegate, long, int, long, AssemblyLoadContext>>(); _begin = RequiredInterpreterBridge.Method(type, "RuneCLR_BeginCallbackDeadline", false, typeof(long)) .CreateDelegate>(); _end = RequiredInterpreterBridge.Method(type, "RuneCLR_EndCallbackDeadline", false, typeof(bool), typeof(long)) @@ -24,27 +36,97 @@ private CallbackDeadlineBridge() .CreateDelegate>(); } - public static CallbackDeadlineBridge Bind() + internal MapDeadlineMode Mode => _mode; + + public static CallbackDeadlineBridge Bind(MapDeadlineMode mode, int epochPeriodMicros) { try { - var version = RequiredInterpreterBridge.Method(typeof(AssemblyLoadContext), "RuneCLR_GetCallbackDeadlineVersion", true, - typeof(long)).CreateDelegate>(); + var type = typeof(AssemblyLoadContext); + var version = RequiredInterpreterBridge.Method(type, "RuneCLR_GetCallbackDeadlineVersion", true, typeof(long)) + .CreateDelegate>(); if (version() != 1) throw new PlatformNotSupportedException("Callback deadline version 1 is required."); - return new CallbackDeadlineBridge(); + if (mode == MapDeadlineMode.Clock) + return new CallbackDeadlineBridge(mode, ClockFactory(), null, null, null); + + // Epoch is explicit: an old runtime without the capability rejects here, before files. + var capabilities = RequiredInterpreterBridge.Method(type, "RuneCLR_GetCallbackDeadlineCapabilities", true, typeof(int)) + .CreateDelegate>(); + if ((capabilities() & 2) == 0) + throw new PlatformNotSupportedException("The runtime does not advertise the epoch callback-deadline capability."); + if (epochPeriodMicros is < 1 or > 1_000_000) + throw new PlatformNotSupportedException("The epoch period is outside the supported 1..1000000 microsecond range."); + var tick = RequiredInterpreterBridge.Method(type, "RuneCLR_TickCallbackDeadlineEpoch", true, typeof(long)) + .CreateDelegate>(); + var read = RequiredInterpreterBridge.Method(type, "RuneCLR_ReadCallbackDeadlineEpoch", true, typeof(long)) + .CreateDelegate>(); + return new CallbackDeadlineBridge(mode, ClockFactory(), EpochFactory(), tick, read); } + catch (PlatformNotSupportedException) { throw; } catch (Exception error) { - throw new PlatformNotSupportedException("PrototypeCallbackDeadline requires matching private CoreLib/native support.", error); + throw new PlatformNotSupportedException( + "PrototypeCallbackDeadline requires matching private CoreLib/native support.", error); } } + private static Func, long, int, long, AssemblyLoadContext> ClockFactory() + { + var type = typeof(AssemblyLoadContext); + return RequiredInterpreterBridge.Method(type, "RuneCLR_CreateCallbackDeadline", true, + type, typeof(string), typeof(Func), typeof(long), typeof(int), typeof(long)) + .CreateDelegate, long, int, long, AssemblyLoadContext>>(); + } + + private static Func, long, int, long, long, AssemblyLoadContext> EpochFactory() + { + var type = typeof(AssemblyLoadContext); + return RequiredInterpreterBridge.Method(type, "RuneCLR_CreateCallbackDeadlineEpoch", true, + type, typeof(string), typeof(Func), typeof(long), typeof(int), typeof(long), typeof(long)) + .CreateDelegate, long, int, long, long, AssemblyLoadContext>>(); + } + + internal long TickEpoch() => (_tickEpoch ?? throw new InvalidOperationException("Epoch mode is not active."))(); + internal long ReadEpoch() => (_readEpoch ?? throw new InvalidOperationException("Epoch mode is not active."))(); + public AssemblyLoadContext Create(string name, Func resolver, - MapRunOptions options) => _create(name, resolver, options.PrototypeCallbackDeadline!.Value.Ticks, - options.PrototypeDeadlinePollInterval, options.PrototypeCleanupInstructionBudget); + MapRunOptions options) + { + var deadline = options.PrototypeCallbackDeadline!.Value; + if (_mode == MapDeadlineMode.Clock) + return _createClock(name, resolver, deadline.Ticks, options.PrototypeDeadlinePollInterval, + options.PrototypeCleanupInstructionBudget); + try + { + return _createEpoch!(name, resolver, deadline.Ticks, options.PrototypeDeadlinePollInterval, + options.PrototypeCleanupInstructionBudget, options.PrototypeDeadlineEpochPeriodMicros); + } + catch (ArgumentOutOfRangeException error) + { + // The native side latches the epoch period process-wide; an externally or earlier + // latched different period surfaces as ArgumentOutOfRangeException from the factory. + // Only this configuration failure is normalized - resolver/author exceptions are not. + throw new PlatformNotSupportedException( + $"The runtime epoch period {options.PrototypeDeadlineEpochPeriodMicros} us conflicts with the period already latched by the process.", + error); + } + } + public long Begin(AssemblyLoadContext context) => _begin(context); public bool End(AssemblyLoadContext context, long token) => _end(context, token); - public CallbackDeadlineSnapshot Snapshot(AssemblyLoadContext context) => new( - _query(context, 0), _query(context, 1), _query(context, 2), _query(context, 3) != 0, - checked((int)_query(context, 4)), _query(context, 5), checked((int)_query(context, 6))); + + public CallbackDeadlineSnapshot Snapshot(AssemblyLoadContext context) + { + var snapshot = new CallbackDeadlineSnapshot( + _query(context, 0), _query(context, 1), _query(context, 2), _query(context, 3) != 0, + checked((int)_query(context, 4)), _query(context, 5), checked((int)_query(context, 6))); + // Clock snapshots never touch the additive fields: an old v1 runtime has no fields 8..10. + if (_mode == MapDeadlineMode.Clock) return snapshot; + return snapshot with + { + Mode = (int)MapDeadlineMode.Epoch, + EpochBudgetTicks = _query(context, 9), + CurrentGlobalEpoch = _query(context, 10) + }; + } } diff --git a/src/RuneCLR.Runtime/CallbackEpochDiagnostics.cs b/src/RuneCLR.Runtime/CallbackEpochDiagnostics.cs new file mode 100644 index 0000000..c4d2f00 --- /dev/null +++ b/src/RuneCLR.Runtime/CallbackEpochDiagnostics.cs @@ -0,0 +1,23 @@ +namespace RuneCLR.Runtime; + +/// +/// Read-only process-wide epoch ticker scalars for tests and diagnostics. There is no control +/// surface here: it cannot start, stop, retarget or tick the ticker. +/// +public static class CallbackEpochDiagnostics +{ + /// Number of live sessions currently leasing the shared ticker (0 in clock-only processes). + public static int ActiveLeaseCount => CallbackEpochTicker.ActiveLeases; + + /// Host-latched period in microseconds (0 before the first lease). + public static int LatchedPeriodMicros => CallbackEpochTicker.LatchedPeriodMicros; + + /// Total successful ticker increments since process start. + public static long TotalTicks => CallbackEpochTicker.TotalTicks; + + /// True once the ticker thread captured a fault. + public static bool Faulted => CallbackEpochTicker.Faulted; + + /// Captured fault type name, or null. Never an author message. + public static string? FaultTypeName => CallbackEpochTicker.FaultType; +} diff --git a/src/RuneCLR.Runtime/CallbackEpochTicker.cs b/src/RuneCLR.Runtime/CallbackEpochTicker.cs new file mode 100644 index 0000000..a116cf8 --- /dev/null +++ b/src/RuneCLR.Runtime/CallbackEpochTicker.cs @@ -0,0 +1,391 @@ +using System.Runtime.InteropServices; +using System.Threading; +using Microsoft.Win32.SafeHandles; + +namespace RuneCLR.Runtime; + +/// +/// Process-wide trusted ticker for the opt-in epoch callback deadline. It owns at most one worker +/// thread, is leased by live epoch sessions, and advances only the native epoch counter. It never +/// holds an author load context, policy, session callback or author metadata. +/// +/// +/// Clock/default sessions never touch this type (no thread, no capability probe, no epoch call). +/// The period is latched permanently by the first acquisition and is never reset, including after a +/// failed bootstrap or after the last release; the native side latches independently inside the +/// epoch factory. A fault is persistent for the process: later acquisitions and every live lease +/// fail closed with the captured type name, which the worker release can never erase. +/// The final release joins the worker with no timeout because the only bound calls are the trusted, +/// non-blocking native tick/read entry points and a blocking wait; that is not a general guarantee +/// for arbitrary delegated work. The host owns the dispose obligation: stop/dispose sessions from +/// ordinary host code, never from inside the ticker's own path. +/// Exception contract: configuration/environment failures detected before author files (missing +/// native capability, unsupported or conflicting period) are PlatformNotSupportedException; +/// runtime-health failures (a live lease observing a ticker fault, or any later Acquire after the +/// permanent process fault) are InvalidOperationException carrying the captured type name only. +/// +internal static class CallbackEpochTicker +{ + private static readonly object Gate = new(); + private static Worker? _worker; + private static int _leases; + private static long _totalTicks; + private static int _latchedPeriodMicros; + private static string? _lastFaultType; + private static int _liveWorkers; + private static int _maxLiveWorkers; + + internal static int ActiveLeases { get { lock (Gate) return _leases; } } + internal static int LatchedPeriodMicros { get { lock (Gate) return _latchedPeriodMicros; } } + internal static bool Faulted => Volatile.Read(ref _lastFaultType) is not null; + internal static string? FaultType => Volatile.Read(ref _lastFaultType); + internal static long TotalTicks => Interlocked.Read(ref _totalTicks); + + // Concurrency diagnostics for tests: a regression that allowed two tickers would be visible as + // MaxLiveWorkerCount > 1 even though TotalTicks alone cannot prove spacing. + internal static int LiveWorkerCount => Volatile.Read(ref _liveWorkers); + internal static int MaxLiveWorkerCount => Volatile.Read(ref _maxLiveWorkers); + + private static void NoteWorkerStarted() + { + int live = Interlocked.Increment(ref _liveWorkers); + int max = Volatile.Read(ref _maxLiveWorkers); + while (live > max) + { + int seen = Interlocked.CompareExchange(ref _maxLiveWorkers, live, max); + if (seen == max) break; + max = seen; + } + } + + private static void NoteWorkerStopped() => Interlocked.Decrement(ref _liveWorkers); + + /// Leases the shared ticker, starting it (and proving the counter advanced) on first use. + internal static Lease Acquire(int periodMicros, Func tick, Func read) + { + ArgumentNullException.ThrowIfNull(tick); + ArgumentNullException.ThrowIfNull(read); + if (periodMicros is < 1 or > 1_000_000) + throw new ArgumentOutOfRangeException(nameof(periodMicros), "The epoch period must be 1..1000000 microseconds."); + lock (Gate) + { + // A process fault is permanent: no later acquisition may silently restart a ticker. + string? latchedFault = Volatile.Read(ref _lastFaultType); + if (latchedFault is not null) + throw new InvalidOperationException($"The process epoch ticker failed ({latchedFault})."); + + // Permanent host latch: set on the first acquisition and never reset, even when the + // bootstrap below fails or the last lease is released. + if (_latchedPeriodMicros == 0) + _latchedPeriodMicros = periodMicros; + else if (_latchedPeriodMicros != periodMicros) + throw new PlatformNotSupportedException( + $"The process epoch period is latched at {_latchedPeriodMicros} us and cannot serve {periodMicros} us."); + + if (_worker is null) + { + var worker = new Worker(periodMicros, tick, read); + worker.Start(); // rolls back its own resources on failure; not published on throw + NoteWorkerStarted(); + _worker = worker; + } + else + { + _worker.ThrowIfFaulted(); + if (_worker.Read() <= 0) + throw new PlatformNotSupportedException("The process epoch ticker did not advance the native counter."); + } + _leases++; + return new Lease(_worker); + } + } + + private static void Release() + { + lock (Gate) + { + if (_leases == 0) return; + _leases--; + if (_leases != 0 || _worker is null) return; + // Stop and join BEFORE any new acquisition can start another ticker, otherwise a + // replacement worker would tick alongside the old one (too-short spacing, early + // expiry). The worker never takes this gate, so joining here cannot deadlock. + if (!_worker.Stop()) + { + // The bound tick is expected to be non-blocking; if the join cannot complete, keep the + // worker published and latch a permanent fault so no second ticker can ever start. + ReportFault("RuntimeException:ThreadJoinIncomplete"); + return; + } + NoteWorkerStopped(); + _worker = null; + } + } + + /// + /// Test-only, process-wide scoped override of the timer facade. It can be installed only while + /// the ticker is idle (no leases, no worker), and disposal restores the facade flags only - it + /// never clears the permanent fault latch or the latched period. The override makes Arm fail or + /// Wait report the unexpected result, so the worker runs the SAME real fault path as a genuine + /// SetWaitableTimer failure / WAIT_FAILED instead of short-circuiting the latch. + /// + internal static IDisposable InstallTestTimerFault(bool armFails, bool waitFails) + { + lock (Gate) + { + if (_leases != 0 || _worker is not null || Volatile.Read(ref _liveWorkers) != 0) + throw new InvalidOperationException( + "The test timer fault hook requires an idle ticker (no leases and no live worker)."); + HighResolutionTimer.SetTestFault(armFails, waitFails); + return new TestFaultScope(); + } + } + + private sealed class TestFaultScope : IDisposable + { + private int _disposed; + + public void Dispose() + { + if (Interlocked.Exchange(ref _disposed, 1) != 0) return; + HighResolutionTimer.SetTestFault(false, false); // flags only; latch/period untouched + } + } + + /// + /// Lock-free fault publication. The worker calls this from its fault/exit path, and the last + /// release holds Gate while joining the worker, so taking Gate here would deadlock. + /// + internal static void ReportFault(string typeName) + { + Interlocked.CompareExchange(ref _lastFaultType, typeName, null); + } + + internal sealed class Lease : IDisposable + { + private readonly Worker _worker; + private int _released; + private string? _faultType; + + internal Lease(Worker worker) => _worker = worker; + + internal string? FaultType => _faultType ?? _worker.FaultType; + + /// Host-gate fault check. It never rescues an infinite body; it only fails closed. + internal void ThrowIfFaulted() + { + var fault = _faultType ?? _worker.FaultType; + if (fault is null) return; + _faultType = fault; // preserved on the lease even after the worker is released + throw new InvalidOperationException($"The process epoch ticker failed ({fault})."); + } + + public void Dispose() + { + if (Interlocked.Exchange(ref _released, 1) == 0) Release(); + } + } + + internal sealed class Worker + { + private readonly int _periodMicros; + private readonly Func _tick; + private readonly Func _read; + private readonly CancellationTokenSource _cancel = new(); + private readonly Thread _thread; + private volatile string? _faultType; + + internal Worker(int periodMicros, Func tick, Func read) + { + _periodMicros = periodMicros; + _tick = tick; + _read = read; + _thread = new Thread(Run) { IsBackground = true, Name = "RuneCLR epoch ticker" }; + } + + internal int PeriodMicros => _periodMicros; + internal string? FaultType => _faultType; + + internal long Read() => _read(); + + internal void ThrowIfFaulted() + { + var fault = _faultType; + if (fault is not null) + throw new InvalidOperationException($"The process epoch ticker failed ({fault})."); + } + + internal void Start() + { + try + { + // Bootstrap before any author code exists: one tick plus a positive read proves the + // native counter is live, so a callback Begin can never observe epoch 0. + long value = _tick(); + if (value <= 0 || _read() <= 0) + throw new PlatformNotSupportedException("The native epoch counter did not start."); + // The trusted worker must not inherit the caller's ExecutionContext (policy scopes, + // AsyncLocal state) into its thread. + if (ExecutionContext.IsFlowSuppressed()) + _thread.Start(); + else + using (ExecutionContext.SuppressFlow()) _thread.Start(); + } + catch + { + // Roll back an unstarted worker. No thread is running, so no join is attempted. + try { _cancel.Cancel(); } catch (Exception) { } + _cancel.Dispose(); + throw; + } + } + + private void Run() + { + SafeWaitHandle? timer = null; + try + { + (timer, var createFault) = HighResolutionTimer.Create(); + if (createFault is not null) + { + Fault(createFault); + return; + } + while (!_cancel.IsCancellationRequested) + { + if (timer is not null) + { + if (!HighResolutionTimer.Arm(timer, _periodMicros)) + { + Fault(HighResolutionTimer.Describe("SetWaitableTimer")); + return; + } + var outcome = HighResolutionTimer.Wait(timer, _cancel.Token); + if (outcome == WaitOutcome.Cancelled) return; // exact cancellation index only + if (outcome == WaitOutcome.Failed) + { + Fault(HighResolutionTimer.Describe("WaitForMultipleObjects")); + return; + } + } + else if (_cancel.Token.WaitHandle.WaitOne(Milliseconds(_periodMicros))) + { + return; + } + if (_cancel.IsCancellationRequested) return; + _tick(); + Interlocked.Increment(ref _totalTicks); + } + } + catch (Exception error) + { + // Scalar only: the fault is reported by type name, never by reading an author message. + Fault(error.GetType().FullName ?? "Exception"); + } + finally + { + try { timer?.Dispose(); } catch (Exception) { } + } + } + + private void Fault(string typeName) + { + _faultType ??= typeName; + CallbackEpochTicker.ReportFault(_faultType!); + } + + private static int Milliseconds(int periodMicros) => (periodMicros + 999) / 1000; + + /// Stops and joins the worker; false means the thread is still alive afterwards. + internal bool Stop() + { + try { _cancel.Cancel(); } catch (Exception) { } + if (_thread.IsAlive && _thread != Thread.CurrentThread) + { + try { _thread.Join(); } catch (Exception) { } + } + bool stopped = !_thread.IsAlive; + if (stopped) + { + try { _cancel.Dispose(); } catch (Exception) { } + } + return stopped; + } + } + + private enum WaitOutcome { Tick, Cancelled, Failed } + + /// + /// Windows high-resolution waitable timer when the OS supports it; the waiting thread blocks, + /// so the normal path never spins. Each iteration re-arms exactly one period: spacing is never + /// shorter than declared and a late tick is never replayed as a burst. + /// + private static class HighResolutionTimer + { + private const uint HighResolution = 0x00000002; + private const uint AllAccess = 0x1F0003; + private const uint Infinite = 0xFFFFFFFF; + private const int ErrorInvalidParameter = 87; + + [DllImport("kernel32.dll", SetLastError = true, CharSet = CharSet.Unicode)] + private static extern SafeWaitHandle CreateWaitableTimerExW(IntPtr attributes, string? name, uint flags, uint access); + + [DllImport("kernel32.dll", SetLastError = true)] + private static extern bool SetWaitableTimer(SafeWaitHandle handle, ref long dueTime, int period, + IntPtr completionRoutine, IntPtr completionArg, bool resume); + + [DllImport("kernel32.dll", SetLastError = true)] + private static extern uint WaitForMultipleObjects(uint count, IntPtr[] handles, bool waitAll, uint milliseconds); + + private static int s_testArmFails; + private static int s_testWaitFails; + + internal static void SetTestFault(bool armFails, bool waitFails) + { + Volatile.Write(ref s_testArmFails, armFails ? 1 : 0); + Volatile.Write(ref s_testWaitFails, waitFails ? 1 : 0); + } + + internal static string Describe(string call) => + $"Win32Exception:{call}:{Marshal.GetLastWin32Error()}"; + + internal static (SafeWaitHandle? Handle, string? Fault) Create() + { + if (!OperatingSystem.IsWindows()) return (null, null); + try + { + var handle = CreateWaitableTimerExW(IntPtr.Zero, null, HighResolution, AllAccess); + if (!handle.IsInvalid) return (handle, null); + int error = Marshal.GetLastWin32Error(); + handle.Dispose(); + // ERROR_INVALID_PARAMETER means this OS predates the high-resolution flag; that is + // the documented coarse fallback, not a fault. + if (error == ErrorInvalidParameter) return (null, null); + return (null, $"Win32Exception:CreateWaitableTimerExW:{error}"); + } + catch (Exception error) + { + return (null, error.GetType().FullName ?? "Exception"); + } + } + + internal static bool Arm(SafeWaitHandle handle, int periodMicros) + { + // Test override only: same return path as a genuine SetWaitableTimer failure. + if (Volatile.Read(ref s_testArmFails) != 0) return false; + long due = -(long)periodMicros * 10; // negative = relative, 100 ns units + return SetWaitableTimer(handle, ref due, 0, IntPtr.Zero, IntPtr.Zero, false); + } + + internal static WaitOutcome Wait(SafeWaitHandle handle, CancellationToken cancel) + { + // Test override only: same path as WAIT_FAILED (unexpected result -> Fault). + if (Volatile.Read(ref s_testWaitFails) != 0) return WaitOutcome.Failed; + IntPtr[] handles = [handle.DangerousGetHandle(), cancel.WaitHandle.SafeWaitHandle.DangerousGetHandle()]; + uint result = WaitForMultipleObjects(2, handles, false, Infinite); + if (result == 0) return WaitOutcome.Tick; // WAIT_OBJECT_0: timer + if (result == 1) return WaitOutcome.Cancelled; // WAIT_OBJECT_0 + 1: cancellation event + return WaitOutcome.Failed; // WAIT_FAILED / abandoned / unexpected + } + } +} diff --git a/src/RuneCLR.Runtime/MapRunOptions.cs b/src/RuneCLR.Runtime/MapRunOptions.cs index 54c5ec5..30ae7a6 100644 --- a/src/RuneCLR.Runtime/MapRunOptions.cs +++ b/src/RuneCLR.Runtime/MapRunOptions.cs @@ -15,6 +15,11 @@ public sealed record MapRunOptions // Experimental native IR-dispatch budget, not a complete execution-time sandbox. public long? PrototypeInstructionBudget { get; init; } public TimeSpan? PrototypeCallbackDeadline { get; init; } + // Sampling source for the callback deadline. Clock (the default) is the original v1 clock ABI. + // Epoch needs the runtime epoch capability, a process-wide trusted ticker and a process-latched + // period; a runtime without the capability fails before any author file, never downgrades. + public MapDeadlineMode PrototypeDeadlineMode { get; init; } = MapDeadlineMode.Clock; + public int PrototypeDeadlineEpochPeriodMicros { get; init; } = 10_000; public int PrototypeDeadlinePollInterval { get; init; } = 100; public long PrototypeCleanupInstructionBudget { get; init; } = 4_096; // Only MapRunner.Run uses TickCount; pumped sessions advance when the host calls Tick. @@ -48,6 +53,15 @@ internal void Validate() if (PrototypeDeadlinePollInterval is not (1 or 100 or 1000)) throw new ArgumentOutOfRangeException(nameof(PrototypeDeadlinePollInterval)); } + if (!Enum.IsDefined(PrototypeDeadlineMode)) + throw new ArgumentOutOfRangeException(nameof(PrototypeDeadlineMode)); + if (PrototypeDeadlineMode == MapDeadlineMode.Epoch) + { + if (PrototypeCallbackDeadline is null) + throw new ArgumentException("Epoch deadline mode requires PrototypeCallbackDeadline.", nameof(PrototypeDeadlineMode)); + if (PrototypeDeadlineEpochPeriodMicros is < 1 or > 1_000_000) + throw new ArgumentOutOfRangeException(nameof(PrototypeDeadlineEpochPeriodMicros)); + } ArgumentOutOfRangeException.ThrowIfNegative(TickCount); ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(TickDuration, TimeSpan.Zero); ArgumentOutOfRangeException.ThrowIfNegativeOrZero(OperationBudgetPerCallback); @@ -59,6 +73,15 @@ internal void Validate() } } +/// Sampling source for the prototype callback deadline. +public enum MapDeadlineMode +{ + /// Original v1 clock mode; the default and the only mode old runtimes support. + Clock, + /// Opt-in shared-ticker epoch mode; requires the additive runtime capability. + Epoch +} + public enum MapRunOutcome { Completed, @@ -82,7 +105,14 @@ public sealed record MapRunReport( } public sealed record CallbackDeadlineSnapshot(long ClockFrequency, long ClockChecks, long AdmittedOperations, - bool Active, int PollInterval, long LastToken, int Reason); + bool Active, int PollInterval, long LastToken, int Reason) +{ + // Epoch evidence. Clock snapshots leave these at zero and never query the additive fields, + // so an old v1 runtime without fields 8..10 keeps working unchanged. + public int Mode { get; init; } + public long EpochBudgetTicks { get; init; } + public long CurrentGlobalEpoch { get; init; } +} // Scalars copied before Unload; no session context, author metadata or exception is retained. public sealed record PrototypeBudgetSnapshot( diff --git a/src/RuneCLR.Runtime/MapSession.cs b/src/RuneCLR.Runtime/MapSession.cs index b35164f..b435edf 100644 --- a/src/RuneCLR.Runtime/MapSession.cs +++ b/src/RuneCLR.Runtime/MapSession.cs @@ -18,6 +18,7 @@ public sealed class MapSession : IDisposable private AssemblyLoadContext? _loadContext; private TerminalPrototypeBridge? _terminal; private CallbackDeadlineBridge? _deadline; + private CallbackEpochTicker.Lease? _epochLease; private ReflectionPolicySession? _reflectionPolicy; private long _deadlineToken; private string? _deadlineFailure; @@ -36,12 +37,21 @@ private MapSession(MapPackage package, MapRunOptions options, CallbackDeadlineBr // Capability failure is a host configuration error, before opening author files. var required = options.ExecutionPolicy == MapExecutionPolicy.RequireInterpreter ? RequiredInterpreterBridge.Bind() : null; - _deadline = options.PrototypeCallbackDeadline is not null ? deadlineBridge ?? CallbackDeadlineBridge.Bind() : null; + _deadline = options.PrototypeCallbackDeadline is not null + ? deadlineBridge ?? CallbackDeadlineBridge.Bind(options.PrototypeDeadlineMode, + options.PrototypeDeadlineEpochPeriodMicros) + : null; _terminal = options.PrototypeInstructionBudget is not null || _deadline is not null ? TerminalPrototypeBridge.Bind(required!) : null; _policyVersion = required is null ? 0 : 1; if (options.PrototypeApiPolicy is not null) PrototypeReflectionPolicy.Prepare(); try { + // Lease and bootstrap the shared ticker before any author file is opened or loaded. + // The native period acknowledgement happens later, inside the epoch factory (op 6); + // until then this latch is host-side and two sessions must agree on the period here. + if (_deadline is { Mode: MapDeadlineMode.Epoch }) + _epochLease = CallbackEpochTicker.Acquire(options.PrototypeDeadlineEpochPeriodMicros, + _deadline.TickEpoch, _deadline.ReadEpoch); var resolver = new MapDependencyResolver(package, allowSessionAssemblyNames: options.PrototypeApiPolicy is not null); var admission = options.PrototypeApiPolicy is { } policy ? new UgcAssemblyAdmission(policy, package, options.PrototypeSharedAssemblies) : null; @@ -54,10 +64,14 @@ private MapSession(MapPackage package, MapRunOptions options, CallbackDeadlineBr } catch { - _reflectionPolicy?.Dispose(); + // Every cleanup step is isolated so the original constructor failure is rethrown, and + // the epoch lease is always released even when Dispose/Unload throw. + try { _reflectionPolicy?.Dispose(); } catch (Exception) { } _reflectionPolicy = null; - _loadContext?.Unload(); + try { _loadContext?.Unload(); } catch (Exception) { } _loadContext = null; + try { _epochLease?.Dispose(); } catch (Exception) { } + _epochLease = null; throw; } } @@ -331,7 +345,18 @@ private MapRunResult StopCore() { _error = Append(_error, "The native prototype state snapshot could not be read."); } - finally { _deadline = null; loadContext.Unload(); } + finally + { + _deadline = null; + try { loadContext.Unload(); } + finally + { + // Author execution has returned; the final lease always stops and joins the + // ticker, even when a native snapshot or Unload above throws. + _epochLease?.Dispose(); + _epochLease = null; + } + } } } @@ -355,6 +380,7 @@ private void CheckReentry() private void CheckPrototypeState() { + CheckEpochTicker(); if (_deadlineFailure is not null) throw new InvalidOperationException(_deadlineFailure); bool terminated; try { terminated = _terminal?.IsTerminated(_loadContext!) == true; } @@ -369,6 +395,7 @@ private void CheckPrototypeState() private void BeginDeadline() { + CheckEpochTicker(); if (_deadlineFailure is not null) throw new InvalidOperationException(_deadlineFailure); if (_deadline is null) return; try @@ -385,6 +412,7 @@ private void BeginDeadline() private void EndDeadline() { + CheckEpochTicker(); if (_deadlineToken == 0) return; var token = _deadlineToken; _deadlineToken = 0; @@ -399,6 +427,14 @@ private void EndDeadline() } } + // A persistent ticker fault is reported at host gates only; it never promises to rescue an + // infinite author body whose counter keeps advancing (or a ticker that stopped advancing). + private void CheckEpochTicker() + { + if (_epochLease is not { } lease || lease.FaultType is not { } fault) return; + FailDeadlineBridge($"The process epoch ticker failed ({fault})."); + } + private void FailDeadlineBridge(string message) { _deadlineFailure ??= message; diff --git a/tests/EpochDeadline.Author/EpochDeadline.Author.csproj b/tests/EpochDeadline.Author/EpochDeadline.Author.csproj new file mode 100644 index 0000000..f6bb485 --- /dev/null +++ b/tests/EpochDeadline.Author/EpochDeadline.Author.csproj @@ -0,0 +1,5 @@ + + + + + diff --git a/tests/EpochDeadline.Author/Scripts.cs b/tests/EpochDeadline.Author/Scripts.cs new file mode 100644 index 0000000..267d38a --- /dev/null +++ b/tests/EpochDeadline.Author/Scripts.cs @@ -0,0 +1,197 @@ +using RuneCLR; + +namespace EpochDeadline.Author; + +/// Maintained copy of the measured interpreter workloads (same kernels and sizes +/// as the sealed measurement campaign). +public static class Kernel +{ + public static long Arithmetic(int units, long seed) + { + long state = seed | 1; + long accumulator = 0; + for (var index = 0; index < units; index++) + { + state ^= state << 13; + state ^= (long)((ulong)state >> 7); + state ^= state << 17; + if ((state & 0x100) != 0) accumulator += state & 0xFFFF; + else accumulator -= state & 0xFF; + if ((index & 0x3FF) == 0) accumulator ^= state; + } + + return accumulator; + } + + public static long CallHeavy(int units, int seed) + { + IWorker worker = new AddWorker(); + var state = seed | 1; + long accumulator = 0; + for (var index = 0; index < units; index++) + { + var value = worker.Step((int)(state & 0xFF)); + var squared = Square(value); + var twisted = Twist(squared); + if ((twisted & 1) != 0) accumulator += twisted; + else accumulator -= Bias(squared); + state = (state * 1103515245 + 12345) & 0x7FFFFFFF; + } + + return accumulator; + } + + public static long Mixed(int units, int seed) + { + long accumulator = 0; + long state = seed | 1; + for (var index = 0; index < units; index++) + { + state ^= state << 13; + state ^= (long)((ulong)state >> 7); + state ^= state << 17; + accumulator += Square((int)(state & 0xFF)); + if ((state & 0x1F) == 0) accumulator ^= Twist((int)(state & 0xFF)); + } + + return accumulator; + } + + private static int Square(int value) => (value * value) & 0xFFFF; + + private static int Twist(int value) => ((value << 3) ^ (value >> 2)) & 0xFFFF; + + private static int Bias(int value) => value + 1; +} + +public interface IWorker +{ + int Step(int value); +} + +public sealed class AddWorker : IWorker +{ + public int Step(int value) => value + 3; +} + +public abstract class Script : IMapScript +{ + private long checksum; + private int steps; + private IMapContext? context; + + protected abstract int Units { get; } + + protected abstract long Run(int units); + + public void OnStart(IMapContext context) + { + this.context = context; + Step(); + } + + public void OnTick(MapTick tick) => Step(); + + public void OnStop() => context = null; + + private void Step() + { + checksum = unchecked(checksum * 1_000_003 + (Run(Units) ^ (steps * 2_654_435_761L))); + steps++; + context?.Log("checksum=" + checksum + ";steps=" + steps); + } +} + +public abstract class TickOnlyScript : IMapScript +{ + protected abstract int Units { get; } + + protected abstract long Run(int units); + + public void OnStart(IMapContext context) { } + + public void OnTick(MapTick tick) => Run(Units); + + public void OnStop() { } +} + +public sealed class ArithmeticSmall : Script +{ + protected override int Units => 200_000; + + protected override long Run(int units) => Kernel.Arithmetic(units, 17); +} + +public sealed class MixedSmall : Script +{ + protected override int Units => 100_000; + + protected override long Run(int units) => Kernel.Mixed(units, 17); +} + +public sealed class CallHeavySmall : Script +{ + protected override int Units => 20_000; + + protected override long Run(int units) => Kernel.CallHeavy(units, 17); +} + +public sealed class TickOnlyLong : TickOnlyScript +{ + protected override int Units => 40_000_000; + + protected override long Run(int units) => Kernel.Arithmetic(units, 17); +} + +public sealed class TickOnlyCatchLong : TickOnlyScript +{ + protected override int Units => 40_000_000; + + protected override long Run(int units) + { + long result = 0; + try + { + result += Kernel.Arithmetic(units, 17); + } + catch (Exception) + { + result -= 1; + } + finally + { + result ^= 3; + } + + return result; + } +} + +public sealed class CleanupHeavy : IMapScript +{ + public void OnStart(IMapContext context) { } + + public void OnTick(MapTick tick) { } + + public void OnStop() => Kernel.Arithmetic(40_000_000, 17); +} + +public sealed class CtorFails : IMapScript +{ + public CtorFails() => throw new InvalidOperationException("author constructor failure"); + + public void OnStart(IMapContext context) { } + + public void OnTick(MapTick tick) { } + + public void OnStop() { } +} + +public sealed class StartFails : IMapScript +{ + public void OnStart(IMapContext context) => throw new InvalidOperationException("author start failure"); + + public void OnTick(MapTick tick) { } + + public void OnStop() { } +} diff --git a/tests/RuneCLR.EpochDeadline.Tests/Program.cs b/tests/RuneCLR.EpochDeadline.Tests/Program.cs new file mode 100644 index 0000000..82e0e79 --- /dev/null +++ b/tests/RuneCLR.EpochDeadline.Tests/Program.cs @@ -0,0 +1,710 @@ +using System.Reflection; +using System.Runtime.CompilerServices; +using System.Runtime.Loader; +using RuneCLR.Runtime; + +internal static class Program +{ + private static string AuthorPath => Path.Combine(AppContext.BaseDirectory, "epoch-author", "EpochDeadline.Author.dll"); + + private static MapRunOptions Options(string mode, int periodMicros = 10_000, int deadlineMs = 1_000, int poll = 100) + { + var options = new MapRunOptions + { + ExecutionPolicy = MapExecutionPolicy.RequireInterpreter, + PrototypeCallbackDeadline = TimeSpan.FromMilliseconds(deadlineMs), + PrototypeDeadlinePollInterval = poll, + TickCount = 0, + MaxLogMessages = 512 + }; + return DeadlineApi.WithMode(options, mode, periodMicros); + } + + private static MapRunOptions Off() => new() { TickCount = 0, MaxLogMessages = 512 }; + + private static int Main(string[] args) + { + if (args.Length == 2 && args[0] == "--fault") return FaultMode(args[1]); + if (args.Length == 2 && args[0] == "--fault-stop") return FaultDuringLastStop(args[1]); + if (args.Length == 2 && args[0] == "--sanity") return Sanity(args[1]); + var filter = args.Length > 0 ? args[0] : null; + var cases = Cases().Where(item => filter is null || item.Name.Contains(filter, StringComparison.OrdinalIgnoreCase)).ToList(); + var passed = 0; + var skipped = 0; + var failed = 0; + foreach (var (name, run) in cases) + { + try + { + run(); + passed++; + Console.WriteLine("PASS " + name); + } + catch (SkipException error) + { + skipped++; + Console.WriteLine("SKIP " + name + " :: " + error.Message); + } + catch (Exception error) + { + failed++; + Console.WriteLine("FAIL " + name + " :: " + error.GetType().Name + ": " + error.Message + + " @ " + (error.StackTrace ?? "").Split('\n').FirstOrDefault()); + } + } + + Console.WriteLine("EPOCH_DEADLINE_TESTS passed=" + passed + " skipped=" + skipped + " failed=" + failed); + return failed == 0 ? 0 : 1; + } + + /// Separate-process deadlock probe: the fault fires while the last lease is + /// being stopped. A hang is a failure; the driver also applies a hard watchdog. + private static int Sanity(string mode) + { + if (mode != "clock" && mode != "epoch") { Console.WriteLine("FAIL sanity mode " + mode); return 2; } + if (mode == "epoch" && (!DeadlineApi.NativeEpoch || !DeadlineApi.PrivateBridge)) + { Console.WriteLine("SKIP native epoch is not available"); return 3; } + foreach (var deadline in new[] { 100, 1000, 5000 }) + { + using var process = System.Diagnostics.Process.GetCurrentProcess(); + process.Refresh(); + var cpuBefore = process.TotalProcessorTime; + var watch = System.Diagnostics.Stopwatch.StartNew(); + using var session = new MapRunner().Start(Package("EpochDeadline.Author.TickOnlyLong"), + Options(mode, 10_000, deadlineMs: deadline, poll: 100)); + var ok = session.Tick(); + watch.Stop(); + var result = session.Stop(); + process.Refresh(); + var cpu = (process.TotalProcessorTime - cpuBefore).TotalMilliseconds; + var snapshot = result.Report.PrototypeDeadline; + Console.WriteLine("SANITY mode=" + mode + " deadlineMs=" + deadline + + " tripped=" + (!ok) + " wallMs=" + watch.Elapsed.TotalMilliseconds.ToString("F1") + + " cpuMs=" + cpu.ToString("F1") + + " reason=" + (snapshot?.Reason.ToString() ?? "none") + + " modeField=" + (snapshot?.Mode.ToString() ?? "none") + + " leases=" + DeadlineApi.ActiveLeaseCount + + " live=" + DeadlineApi.LiveWorkers + " max=" + DeadlineApi.MaxLiveWorkers + + " latched=" + DeadlineApi.LatchedPeriodMicros); + } + return 0; + } + private static int FaultDuringLastStop(string kind) + { + var armFails = kind == "arm"; + var waitFails = kind == "wait"; + if (!armFails && !waitFails) { Console.WriteLine("FAIL unknown fault kind " + kind); return 2; } + var ticker = typeof(MapRunOptions).Assembly.GetType("RuneCLR.Runtime.CallbackEpochTicker", throwOnError: false); + var gateField = ticker?.GetField("Gate", BindingFlags.NonPublic | BindingFlags.Static); + var acquire = ticker?.GetMethod("Acquire", BindingFlags.NonPublic | BindingFlags.Static); + var install = ticker?.GetMethod("InstallTestTimerFault", BindingFlags.NonPublic | BindingFlags.Static); + if (ticker is null || gateField is null || acquire is null || install is null) + { + Console.WriteLine("SKIP internal ticker surface is not available"); + return 3; + } + + var tick = typeof(AssemblyLoadContext).GetMethod("RuneCLR_TickCallbackDeadlineEpoch", + BindingFlags.NonPublic | BindingFlags.Static)!.CreateDelegate>(); + var read = typeof(AssemblyLoadContext).GetMethod("RuneCLR_ReadCallbackDeadlineEpoch", + BindingFlags.NonPublic | BindingFlags.Static)!.CreateDelegate>(); + var gate = gateField.GetValue(null)!; + Monitor.Enter(gate); + try + { + using var hook = (IDisposable)install.Invoke(null, new object[] { armFails, waitFails })!; + var lease = acquire.Invoke(null, new object[] { 10_000, tick, read })!; + var faultProperty = lease.GetType().GetProperty("FaultType", BindingFlags.NonPublic | BindingFlags.Instance); + var wait = System.Diagnostics.Stopwatch.StartNew(); + while (wait.Elapsed < TimeSpan.FromSeconds(10)) + { + if (!string.IsNullOrEmpty(faultProperty?.GetValue(lease) as string)) break; + Thread.Sleep(10); + } + + var observed = faultProperty?.GetValue(lease) as string; + var stop = System.Diagnostics.Stopwatch.StartNew(); + ((IDisposable)lease).Dispose(); + stop.Stop(); + var ok = !string.IsNullOrEmpty(observed) && stop.Elapsed < TimeSpan.FromSeconds(5) + && DeadlineApi.LiveWorkers == 0 && DeadlineApi.MaxLiveWorkers <= 1 + && DeadlineApi.ActiveLeaseCount == 0 && DeadlineApi.Faulted + && DeadlineApi.LatchedPeriodMicros == 10_000; + Console.WriteLine((ok ? "PASS" : "FAIL") + " fault-stop-" + kind + + " fault=" + (observed ?? "none") + " disposeMs=" + stop.Elapsed.TotalMilliseconds.ToString("F0") + + " live=" + DeadlineApi.LiveWorkers + " max=" + DeadlineApi.MaxLiveWorkers + + " leases=" + DeadlineApi.ActiveLeaseCount + " latched=" + DeadlineApi.LatchedPeriodMicros); + return ok ? 0 : 1; + } + finally + { + Monitor.Exit(gate); + } + } + + /// Separate-process fault case: install the internal timer fault while idle, + /// then require the existing lease and future acquires to fail. + private static int FaultMode(string kind) + { + var armFails = kind == "arm"; + var waitFails = kind == "wait"; + if (!armFails && !waitFails) { Console.WriteLine("FAIL unknown fault kind " + kind); return 2; } + var install = typeof(MapRunOptions).Assembly.GetType("RuneCLR.Runtime.CallbackEpochTicker", throwOnError: false)? + .GetMethod("InstallTestTimerFault", BindingFlags.NonPublic | BindingFlags.Static); + if (install is null) { Console.WriteLine("SKIP fault hook is not available"); return 3; } + if (!DeadlineApi.NativeEpoch || !DeadlineApi.PrivateBridge) { Console.WriteLine("SKIP native epoch is not available"); return 3; } + using var hook = (IDisposable)install.Invoke(null, new object[] { armFails, waitFails })!; + try + { + using var session = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch", 10_000)); + var threw = Capture(() => session.Tick()) is InvalidOperationException; + var acquire = Capture(() => new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch", 10_000))); + session.Stop(); + Check(threw, "an existing lease did not surface the fault as InvalidOperationException"); + Check(acquire is InvalidOperationException, "a future acquire did not fail after the fault: " + acquire?.GetType().Name); + Check(DeadlineApi.Faulted, "the fault was not latched"); + Check(!string.IsNullOrEmpty(DeadlineApi.FaultTypeName), "no fault type was captured"); + using var clock = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Clock")); + Check(clock.Tick(), "clock mode was affected by the epoch fault"); + clock.Stop(); + Console.WriteLine("PASS fault-" + kind + " latched=" + DeadlineApi.FaultTypeName); + return 0; + } + catch (Exception error) + { + Console.WriteLine("FAIL fault-" + kind + " :: " + error.GetType().Name + ": " + error.Message); + return 1; + } + } + + private static IEnumerable<(string Name, Action Run)> Cases() + { + yield return ("default Clock starts no thread and reports no deadline evidence", DefaultNoTicker); + yield return ("explicit Epoch is refused before the missing author file when native support is absent", EpochRefusedBeforeFile); + yield return ("invalid option combinations are rejected", InvalidCombinations); + yield return ("clock mode keeps the version-1 contract", ClockOnV1); + yield return ("first epoch session sees a positive native epoch", FirstEpochPositive); + yield return ("four concurrent sessions share one ticker", FourConcurrent); + yield return ("stopping one session does not stop the others", StopOneKeepsOthers); + yield return ("last stop joins the ticker", LastStopJoins); + yield return ("failure during ctor/OnStart rolls back the lease", FailureRollback); + yield return ("a stopped session does not root its ALC", StoppedDoesNotRoot); + yield return ("duplicate Stop is idempotent", DuplicateStop); + yield return ("period mismatch is rejected before the author file while a ticker is active", PeriodMismatchWhileActive); + yield return ("catch/filter cannot resume a terminated callback", CatchCannotResume); + yield return ("next good session completes after termination and unloads", NextGoodAfterTermination); + yield return ("no public pause/escape API is exposed", NoPauseApi); + yield return ("default epoch period is 10000 microseconds", DefaultPeriod); + yield return ("clock mode never starts or latches the epoch ticker", ClockKeepsTickerIdle); + yield return ("epoch ticker diagnostics reset leases and keep the latched period", TickerDiagnostics); + yield return ("last stop racing a new start never overlaps or double-ticks", LastStopRacesStart); + yield return ("a conflicting period is rejected before files after the last lease is gone", PeriodLatchedAfterLastLease); + yield return ("a failed start leaves no lease behind", FailedStartLeavesNoLease); + yield return ("the ticker thread does not inherit the caller ExecutionContext", TickerDoesNotInheritFlow); + yield return ("injected ticker faults surface to an existing lease", InjectedFaultVisibility); + yield return ("legacy Query fields stay -1 on the clock path", LegacyQueryUnchanged); + } + + private static void DefaultNoTicker() + { + var before = ThreadCount(); + using var session = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Off()); + session.Tick(); + session.Stop(); + var after = ThreadCount(); + Check(after <= before + 1, "default run started persistent threads: " + before + " -> " + after); + } + + private static void EpochRefusedBeforeFile() + { + var missing = MissingPackage(); + var options = Options("Epoch"); + var error = Capture(() => new MapRunner().Start(missing, options)); + if (DeadlineApi.NativeEpoch) + { + Check(error is not PlatformNotSupportedException, + "native epoch support is present but the session refused as unsupported"); + } + else + { + Check(error is PlatformNotSupportedException, + "epoch mode without native support must refuse: " + error?.GetType().Name); + } + + Check(!File.Exists(missing.AssemblyPath), "refusal opened or created the author path"); + } + + private static void InvalidCombinations() + { + var plain = Capture(() => new MapRunner().Start(MissingPackage(), + new MapRunOptions { ExecutionPolicy = MapExecutionPolicy.RequireInterpreter })); + Check(plain is not ArgumentException, + "valid interpreter options were rejected by validation: " + plain?.GetType().Name); + if (!DeadlineApi.EpochSupported) return; + var noDeadline = DeadlineApi.WithMode(Off(), "Epoch", 10_000); + Check(Capture(() => new MapRunner().Start(MissingPackage(), noDeadline)) is ArgumentException, + "epoch mode without a deadline must be an ArgumentException"); + var badPeriod = Options("Epoch", 0); + Check(Capture(() => new MapRunner().Start(MissingPackage(), badPeriod)) is ArgumentException, + "an out-of-range epoch period must be an ArgumentException"); + } + + private static void ClockOnV1() + { + if (DeadlineVersion() != 1) throw new SkipException("the runtime does not expose the version-1 clock bridge"); + using var session = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Clock")); + Check(session.Tick(), "clock session failed on a healthy tick"); + var result = session.Stop(); + Check(result.Report.PrototypeDeadline is not null, "clock mode did not report deadline evidence"); + } + + private static void FirstEpochPositive() + { + if (!DeadlineApi.EpochSupported || !DeadlineApi.PrivateBridge) throw new SkipException("epoch mode is not available on this runtime"); + using var session = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch")); + Check(session.Tick(), "epoch session failed on a healthy tick"); + var result = session.Stop(); + var snapshot = result.Report.PrototypeDeadline; + Check(snapshot is not null, "epoch mode did not report deadline evidence"); + } + + private static void FourConcurrent() + { + if (!DeadlineApi.EpochSupported || !DeadlineApi.PrivateBridge) throw new SkipException("epoch mode is not available on this runtime"); + var sessions = Enumerable.Range(0, 4) + .Select(_ => new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch"))) + .ToList(); + try + { + foreach (var session in sessions) Check(session.Tick(), "a concurrent session failed a healthy tick"); + } + finally + { + foreach (var session in sessions) session.Stop(); + } + } + + private static void StopOneKeepsOthers() + { + if (!DeadlineApi.EpochSupported || !DeadlineApi.PrivateBridge) throw new SkipException("epoch mode is not available on this runtime"); + var first = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch")); + var second = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch")); + first.Stop(); + Check(second.IsRunning, "stopping one session stopped another"); + Check(second.Tick(), "the surviving session failed a tick"); + second.Stop(); + } + + private static void LastStopJoins() + { + if (!DeadlineApi.EpochSupported || !DeadlineApi.PrivateBridge) throw new SkipException("epoch mode is not available on this runtime"); + var before = ThreadCount(); + var session = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch")); + session.Tick(); + session.Stop(); + Thread.Sleep(200); + Check(ThreadCount() <= before + 1, "the ticker thread survived the last stop: " + before + " -> " + ThreadCount()); + } + + private static void FailureRollback() + { + if (!DeadlineApi.EpochSupported || !DeadlineApi.PrivateBridge) throw new SkipException("epoch mode is not available on this runtime"); + foreach (var entry in new[] { "EpochDeadline.Author.CtorFails", "EpochDeadline.Author.StartFails" }) + { + using var session = new MapRunner().Start(Package(entry), Options("Epoch")); + Check(!session.IsRunning, entry + " should not stay running"); + session.Stop(); + } + + var missing = MissingPackage(); + var error = Capture(() => new MapRunner().Start(missing, Options("Epoch"))); + Check(error is not null, "a missing author file must surface an error"); + } + + private static void StoppedDoesNotRoot() + { + if (!DeadlineApi.EpochSupported || !DeadlineApi.PrivateBridge) throw new SkipException("epoch mode is not available on this runtime"); + var weak = RunAndCaptureContext("EpochDeadline.Author.ArithmeticSmall"); + for (var attempt = 0; attempt < 3 && weak.IsAlive; attempt++) + { + GC.Collect(); + GC.WaitForPendingFinalizers(); + } + + Check(!weak.IsAlive, "a stopped session still roots its load context"); + } + + private static void DuplicateStop() + { + using var session = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Off()); + var first = session.Stop(); + var second = session.Stop(); + Check(ReferenceEquals(first, second), "duplicate Stop returned a different result"); + } + + private static void PeriodMismatchWhileActive() + { + if (!DeadlineApi.EpochSupported || !DeadlineApi.PrivateBridge) throw new SkipException("epoch mode is not available on this runtime"); + using var active = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch", 10_000)); + var error = Capture(() => new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch", 5_000))); + Check(error is not null, "a conflicting period was accepted while the ticker was active"); + active.Stop(); + using var restart = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch", 10_000)); + Check(restart.Tick(), "restart with the same period failed"); + restart.Stop(); + } + + private static void CatchCannotResume() + { + if (!DeadlineApi.EpochSupported || !DeadlineApi.NativeEpoch || !DeadlineApi.PrivateBridge) + throw new SkipException("native epoch mode is not available on this runtime"); + using var session = new MapRunner().Start(Package("EpochDeadline.Author.TickOnlyCatchLong"), + Options("Epoch", 10_000, deadlineMs: 50, poll: 100)); + var ok = session.Tick(); + Check(!ok, "the catch/filter workload was not terminated"); + var result = session.Stop(); + Check(result.Report.Outcome == MapRunOutcome.Failed, "the terminated session did not report failure"); + Check(result.Report.PrototypeDeadline is { } snapshot && snapshot.Reason == 2, + "termination was not the deadline reason 2"); + } + + private static void NextGoodAfterTermination() + { + if (!DeadlineApi.EpochSupported || !DeadlineApi.NativeEpoch || !DeadlineApi.PrivateBridge) + throw new SkipException("native epoch mode is not available on this runtime"); + for (var index = 0; index < 2; index++) + { + using var terminated = new MapRunner().Start(Package("EpochDeadline.Author.TickOnlyLong"), + Options("Epoch", 10_000, deadlineMs: 50, poll: 100)); + Check(!terminated.Tick(), "the long tick was not terminated"); + terminated.Stop(); + } + + using var good = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch", 10_000)); + Check(good.Tick(), "the good session after terminations failed"); + var result = good.Stop(); + Check(result.Report.Outcome == MapRunOutcome.Completed, "the good session did not complete"); + } + + private static void NoPauseApi() + { + var exposed = typeof(MapRunOptions).Assembly.GetExportedTypes() + .SelectMany(type => type.GetMethods(BindingFlags.Public | BindingFlags.Static | BindingFlags.Instance)) + .Any(method => method.Name.Contains("Pause", StringComparison.OrdinalIgnoreCase)); + Check(!exposed, "a public pause/escape API is exposed"); + } + + private static void DefaultPeriod() + { + if (!DeadlineApi.EpochSupported || !DeadlineApi.PrivateBridge) throw new SkipException("epoch options are not available on this runtime"); + Check(DeadlineApi.DefaultPeriodMicros == 10_000, + "default epoch period is " + DeadlineApi.DefaultPeriodMicros); + } + + private static void ClockKeepsTickerIdle() + { + if (!DeadlineApi.TickerAvailable || !DeadlineApi.PrivateBridge) + throw new SkipException("the production ticker diagnostics or private bridge are not available"); + var periodBefore = DeadlineApi.LatchedPeriodMicros; + using var session = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Clock")); + session.Tick(); + Check(DeadlineApi.ActiveLeases == 0, "clock mode acquired epoch ticker leases"); + Check(DeadlineApi.LatchedPeriodMicros == periodBefore, "clock mode changed the latched epoch period"); + session.Stop(); + } + + private static void TickerDiagnostics() + { + if (!DeadlineApi.TickerAvailable || !DeadlineApi.NativeEpoch) + throw new SkipException("the production ticker or native epoch is not available"); + DeadlineApi.ResetDiagnostics(); + for (var index = 0; index < 2; index++) + { + using var session = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch", 10_000)); + Check(DeadlineApi.ActiveLeases == 1, "active leases should be 1 while a session runs"); + Check(DeadlineApi.LatchedPeriodMicros == 10_000, + "latched period while active is " + DeadlineApi.LatchedPeriodMicros); + Check(session.Tick(), "epoch session failed a healthy tick"); + session.Stop(); + } + + Check(DeadlineApi.ActiveLeases == 0, "leases were not released after the last stop: " + DeadlineApi.ActiveLeases); + Check(DeadlineApi.TotalTicks > 0, "the ticker published no ticks"); + Check(DeadlineApi.LatchedPeriodMicros == 10_000, + "the latched period should persist after the last stop, got " + DeadlineApi.LatchedPeriodMicros); + Check(!DeadlineApi.Faulted, "ticker faulted: " + DeadlineApi.FaultType); + var error = Capture(() => new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch", 5_000))); + Check(error is not null, "a conflicting period was accepted after the last stop"); + } + + private static void LastStopRacesStart() + { + if (!DeadlineApi.NativeEpoch || !DeadlineApi.PrivateBridge) throw new SkipException("native epoch mode is not available"); + var faults = 0; + var before = DeadlineApi.TotalTicks; + var clock = System.Diagnostics.Stopwatch.StartNew(); + for (var round = 0; round < 12; round++) + { + var first = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch", 10_000)); + using var barrier = new Barrier(2); + Exception? startError = null; + var starter = new Thread(() => + { + barrier.SignalAndWait(); + try + { + using var second = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch", 10_000)); + second.Tick(); + second.Stop(); + } + catch (Exception error) { startError = error; } + }); + starter.Start(); + barrier.SignalAndWait(); + first.Stop(); + starter.Join(TimeSpan.FromSeconds(10)); + if (startError is not null) faults++; + } + + clock.Stop(); + var ticks = DeadlineApi.TotalTicks - before; + var seconds = Math.Max(0.001, clock.Elapsed.TotalSeconds); + var rate = ticks / seconds; + // One ticker at a 10 ms period yields about 100 ticks/s; two tickers would double it. + Check(rate <= 200.0, "ticker rate " + rate.ToString("F1") + "/s suggests two tickers"); + Check(faults == 0, "a racing start failed: " + faults + " rounds"); + Check(DeadlineApi.ActiveLeaseCount == 0, "leases leaked after the race: " + DeadlineApi.ActiveLeaseCount); + Check(!DeadlineApi.Faulted, "the ticker faulted during the race: " + DeadlineApi.FaultTypeName); + } + + private static void PeriodLatchedAfterLastLease() + { + if (!DeadlineApi.NativeEpoch || !DeadlineApi.PrivateBridge) throw new SkipException("native epoch mode is not available"); + using (var session = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch", 10_000))) + { + session.Tick(); + session.Stop(); + } + + Check(DeadlineApi.ActiveLeaseCount == 0, "the last lease was not released"); + var missing = MissingPackage(); + var error = Capture(() => new MapRunner().Start(missing, Options("Epoch", 5_000))); + Check(error is not null, "a conflicting period was accepted after the last lease"); + Check(!File.Exists(missing.AssemblyPath), "the conflict was rejected only after opening the author file"); + } + + private static void FailedStartLeavesNoLease() + { + if (!DeadlineApi.NativeEpoch || !DeadlineApi.PrivateBridge) throw new SkipException("native epoch mode is not available"); + var before = DeadlineApi.ActiveLeaseCount; + foreach (var entry in new[] { "EpochDeadline.Author.CtorFails", "EpochDeadline.Author.StartFails" }) + { + using var session = new MapRunner().Start(Package(entry), Options("Epoch", 10_000)); + Check(!session.IsRunning, entry + " should not stay running"); + session.Stop(); + } + + Check(DeadlineApi.ActiveLeaseCount == before, "a failed start leaked a lease"); + } + + private static void TickerDoesNotInheritFlow() + { + if (!DeadlineApi.NativeEpoch || !DeadlineApi.PrivateBridge) throw new SkipException("native epoch mode is not available"); + var weak = LeaseWithFlowSentinel(); + for (var attempt = 0; attempt < 5 && weak.IsAlive; attempt++) + { + GC.Collect(); + GC.WaitForPendingFinalizers(); + } + + Check(!weak.IsAlive, "the ticker thread inherited and rooted the caller ExecutionContext"); + } + + [MethodImpl(MethodImplOptions.NoInlining)] + private static WeakReference LeaseWithFlowSentinel() + { + var sentinel = new object(); + var flow = new AsyncLocal(); + flow.Value = sentinel; + var weak = new WeakReference(sentinel); + using (var session = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Epoch", 10_000))) + { + session.Tick(); + } + + flow.Value = null; + return weak; + } + + private static void LegacyQueryUnchanged() + { + if (DeadlineVersion() != 1) throw new SkipException("the runtime does not expose the version-1 clock bridge"); + using var session = new MapRunner().Start(Package("EpochDeadline.Author.ArithmeticSmall"), Options("Clock")); + var contextField = typeof(MapSession).GetField("_loadContext", BindingFlags.NonPublic | BindingFlags.Instance); + var context = contextField?.GetValue(session) as AssemblyLoadContext; + Check(context is not null, "could not reach the session load context for the legacy query"); + var query = typeof(AssemblyLoadContext).GetMethod("RuneCLR_QueryCallbackDeadline", + BindingFlags.NonPublic | BindingFlags.Instance, binder: null, types: new[] { typeof(int) }, modifiers: null); + Check(query is not null, "the legacy Query entry is missing"); + var delegateQuery = query!.CreateDelegate>(); + Check(delegateQuery(context!, 7) == -1, "legacy field 7 must stay -1"); + Check(delegateQuery(context!, 99) == -1, "an unknown legacy field must stay -1"); + session.Tick(); + session.Stop(); + } + + private static void InjectedFaultVisibility() + { + // Requires an internal test hook for the timer facade; coordinate with the Lead. + if (!DeadlineApi.FaultHookAvailable) throw new SkipException("no internal timer fault hook is available"); + throw new SkipException("fault hook present but not yet bound"); + } + + private static WeakReference RunAndCaptureContext(string entry) + { + var session = new MapRunner().Start(Package(entry), Options("Epoch")); + session.Tick(); + var result = session.Stop(); + var weak = new WeakReference(null); + var field = typeof(UnloadTicket).GetField("_context", BindingFlags.NonPublic | BindingFlags.Instance); + if (field?.GetValue(result.Unload) is WeakReference context) weak = context; + session.Dispose(); + return weak; + } + + private static MapPackage Package(string entry) => new("epoch-tests", AuthorPath, entry); + + private static MapPackage MissingPackage() => new( + "epoch-missing", Path.Combine(Path.GetTempPath(), "runeclr-epoch-" + Guid.NewGuid().ToString("N") + ".dll"), "Unused"); + + private static int ThreadCount() + { + GC.Collect(); + return System.Diagnostics.Process.GetCurrentProcess().Threads.Count; + } + + private static Exception? Capture(Action action) + { + try + { + action(); + return null; + } + catch (Exception error) + { + return error; + } + } + + private static long DeadlineVersion() + { + try + { + var method = typeof(AssemblyLoadContext).GetMethod("RuneCLR_GetCallbackDeadlineVersion", + BindingFlags.NonPublic | BindingFlags.Static, binder: null, types: Type.EmptyTypes, modifiers: null); + return method is null ? 0 : method.CreateDelegate>()(); + } + catch { return 0; } + } + + private static void Check(bool condition, string message) + { + if (!condition) throw new InvalidOperationException(message); + } + + private sealed class SkipException : Exception + { + public SkipException(string message) : base(message) { } + } +} + +/// Binds the optional epoch options reflectively so the harness compiles before +/// the production change lands and fails closed when it is absent. +internal static class DeadlineApi +{ + private static readonly PropertyInfo? ModeProperty = typeof(MapRunOptions).GetProperty("PrototypeDeadlineMode"); + private static readonly PropertyInfo? PeriodProperty = typeof(MapRunOptions).GetProperty("PrototypeDeadlineEpochPeriodMicros"); + private static readonly Type? ModeType = typeof(MapRunOptions).Assembly.GetType("RuneCLR.Runtime.MapDeadlineMode"); + + public static bool EpochSupported => ModeProperty is not null && PeriodProperty is not null && ModeType is not null; + + private static readonly Type? TickerType = typeof(MapRunOptions).Assembly.GetType("RuneCLR.Runtime.CallbackEpochTicker"); + + public static bool TickerAvailable => typeof(CallbackEpochDiagnostics) is not null; + + public static bool PrivateBridge + { + get + { + try + { + var method = typeof(AssemblyLoadContext).GetMethod("RuneCLR_GetExecutionPolicyVersion", + BindingFlags.NonPublic | BindingFlags.Static, binder: null, types: Type.EmptyTypes, modifiers: null); + return method is not null && method.CreateDelegate>()() == 1; + } + catch { return false; } + } + } + + public static bool FaultHookAvailable => + typeof(MapRunOptions).Assembly.GetType("RuneCLR.Runtime.CallbackEpochTicker", throwOnError: false)? + .GetMethod("InstallTestTimerFault", BindingFlags.NonPublic | BindingFlags.Static) is not null; + + public static int DefaultPeriodMicros => + PeriodProperty is null ? -1 : (int)PeriodProperty.GetValue(new MapRunOptions())!; + + public static int ActiveLeases => CallbackEpochDiagnostics.ActiveLeaseCount; + public static int ActiveLeaseCount => CallbackEpochDiagnostics.ActiveLeaseCount; + + /// Optional worker-count diagnostic; -1 when production does not expose one. + public static int LiveWorkers + { + get + { + var property = TickerType?.GetProperty("LiveWorkerCount", BindingFlags.NonPublic | BindingFlags.Static); + return property is null ? -1 : Convert.ToInt32(property.GetValue(null) ?? -1); + } + } + + public static int MaxLiveWorkers + { + get + { + var property = TickerType?.GetProperty("MaxLiveWorkerCount", BindingFlags.NonPublic | BindingFlags.Static); + return property is null ? -1 : Convert.ToInt32(property.GetValue(null) ?? -1); + } + } + public static int LatchedPeriodMicros => CallbackEpochDiagnostics.LatchedPeriodMicros; + public static long TotalTicks => CallbackEpochDiagnostics.TotalTicks; + public static bool Faulted => CallbackEpochDiagnostics.Faulted; + public static string? FaultType => CallbackEpochDiagnostics.FaultTypeName; + public static string? FaultTypeName => CallbackEpochDiagnostics.FaultTypeName; + + public static void ResetDiagnostics() + { + // Diagnostics are read-only; this exists so a test can state intent explicitly. + } + + public static bool NativeEpoch + { + get + { + try + { + var method = typeof(AssemblyLoadContext).GetMethod("RuneCLR_GetCallbackDeadlineCapabilities", + BindingFlags.NonPublic | BindingFlags.Static, binder: null, types: Type.EmptyTypes, modifiers: null); + return method is not null && (method.CreateDelegate>()() & 2) != 0; + } + catch { return false; } + } + } + + public static MapRunOptions WithMode(MapRunOptions options, string mode, int periodMicros) + { + if (ModeType is null || ModeProperty is null) return options; + var value = Enum.Parse(ModeType, mode, ignoreCase: true); + if (PeriodProperty?.SetMethod is { } setter) setter.Invoke(options, new object[] { periodMicros }); + ModeProperty.SetValue(options, value); + return options; + } +} diff --git a/tests/RuneCLR.EpochDeadline.Tests/RuneCLR.EpochDeadline.Tests.csproj b/tests/RuneCLR.EpochDeadline.Tests/RuneCLR.EpochDeadline.Tests.csproj new file mode 100644 index 0000000..1d9b118 --- /dev/null +++ b/tests/RuneCLR.EpochDeadline.Tests/RuneCLR.EpochDeadline.Tests.csproj @@ -0,0 +1,11 @@ + + Exe + + + + + + + + + From 70d53f17aaaeef32fe5e73864a66332ca8d5b6dd Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:40:51 +0800 Subject: [PATCH 02/15] Bind the deadline ABI independently of the instruction-terminal prototype Problem: a callback-deadline session bound the instruction-terminal prototype bridge even when no instruction budget was requested, so a runtime that implements only the minimal deadline ABI refused every deadline session. Change: - MapSession binds the terminal bridge only for an explicit instruction budget; deadline-only sessions use the deadline ABI on its own and sessions with both features still bind both; - the failure-description path treats a deadline session like a terminal one for message safety (exception type only, never an author message); - eng/verify-epoch-integration.py accepts the CoreLib under IL/ when this build subset has no crossgen copy (byte-preserving +6 lines, no assertion changed). Verification: epoch suite against the real epoch runtime layout -> 23 passed / 0 failed / 1 skipped (remaining skip is the unbound ticker fault hook); eng/verify-epoch-integration.py PASS with 657 pins and a 520-file layout on the frozen binaries (coreclr ed76bfa6, CoreLib 6f181812, interpreter 905bb9bb); stock lifecycle 156/156; full solution Release build 0 warnings 0 errors. Host-only. The runtime branch 7f5a0bc8 and its binaries are untouched; required interpreter acknowledgement, fail-closed termination/cleanup and the pre-author capability rejection are unchanged. Assisted-by: Cindy (https://cindy.app) --- eng/verify-epoch-integration.py | 6 ++++++ src/RuneCLR.Runtime/MapSession.cs | 6 ++++-- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/eng/verify-epoch-integration.py b/eng/verify-epoch-integration.py index 41b6c45..76d7180 100644 --- a/eng/verify-epoch-integration.py +++ b/eng/verify-epoch-integration.py @@ -66,6 +66,12 @@ def main(): artifact = {} for name in outputs: produced, installed = build / name, shared / name + if not produced.is_file(): + # This build publishes the CoreLib as IL/ (no crossgen copy in the + # clr.runtime+clr.corelib+libs subset); accept that exact produced file. + alternate = build / "IL" / name + if alternate.is_file(): + produced = alternate if not produced.is_file(): raise ValueError("Runtime artifact output absent (build not terminal): " + str(produced)) if not installed.is_file(): diff --git a/src/RuneCLR.Runtime/MapSession.cs b/src/RuneCLR.Runtime/MapSession.cs index b435edf..c065e73 100644 --- a/src/RuneCLR.Runtime/MapSession.cs +++ b/src/RuneCLR.Runtime/MapSession.cs @@ -41,7 +41,9 @@ private MapSession(MapPackage package, MapRunOptions options, CallbackDeadlineBr ? deadlineBridge ?? CallbackDeadlineBridge.Bind(options.PrototypeDeadlineMode, options.PrototypeDeadlineEpochPeriodMicros) : null; - _terminal = options.PrototypeInstructionBudget is not null || _deadline is not null ? TerminalPrototypeBridge.Bind(required!) : null; + // The callback-deadline ABI is independent of the instruction-terminal prototype: a deadline-only + // session must not require that unrelated native surface. Only an explicit instruction budget binds it. + _terminal = options.PrototypeInstructionBudget is not null ? TerminalPrototypeBridge.Bind(required!) : null; _policyVersion = required is null ? 0 : 1; if (options.PrototypeApiPolicy is not null) PrototypeReflectionPolicy.Prepare(); try @@ -459,7 +461,7 @@ private string DescribeFailure(Exception exception) if (exception is TargetInvocationException { InnerException: { } inner }) exception = inner; var typeName = exception.GetType().FullName ?? "Exception"; - if (_terminal is not null || _reflectionPolicy is not null) + if (_terminal is not null || _deadline is not null || _reflectionPolicy is not null) { // Message/ToString may invoke author code even before native termination. return typeName.Length <= 512 ? typeName : typeName[..512]; From 17a41fb8bea14318a8ad38aaf2230f5e19cab272 Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:45:00 +0800 Subject: [PATCH 03/15] Run the injected ticker fault regression in child processes Problem: the epoch suite skipped the ticker-fault case unconditionally, so the fault-propagation path of the deadline ticker had no regression coverage. Change (tests only): InjectedFaultVisibility now launches one child per fault mode (arm, wait) for both the live-lease case (--fault) and the last-stop case (--fault-stop), under the same private host/runtime, with a bounded watchdog and captured stdout/stderr. The child resolves the private framework explicitly (exec --fx-version 12.0.0 + DOTNET_ROOT/DOTNET_MULTILEVEL_LOOKUP) instead of relying on inherited host settings. No timer machinery was added. Verification: EPOCH_DEADLINE_TESTS passed=24 skipped=0 failed=0; verifier PASS with 657 pins and a 520-file layout on the frozen epoch binaries. Assisted-by: Cindy (https://cindy.app) --- tests/RuneCLR.EpochDeadline.Tests/Program.cs | 52 +++++++++++++++++++- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/tests/RuneCLR.EpochDeadline.Tests/Program.cs b/tests/RuneCLR.EpochDeadline.Tests/Program.cs index 82e0e79..9aca58d 100644 --- a/tests/RuneCLR.EpochDeadline.Tests/Program.cs +++ b/tests/RuneCLR.EpochDeadline.Tests/Program.cs @@ -555,11 +555,59 @@ private static void LegacyQueryUnchanged() private static void InjectedFaultVisibility() { - // Requires an internal test hook for the timer facade; coordinate with the Lead. + // Real regression: each fault case runs in its own child process (the hook is process-wide + // and a latched fault is permanent), under the same private host/runtime as this test. if (!DeadlineApi.FaultHookAvailable) throw new SkipException("no internal timer fault hook is available"); - throw new SkipException("fault hook present but not yet bound"); + foreach (var kind in new[] { "arm", "wait" }) + { + var r1 = RunFaultChild("--fault", kind); + Check(r1.Exit == 0, "fault " + kind + " child exit=" + r1.Exit + " :: " + r1.Output); + var r2 = RunFaultChild("--fault-stop", kind); + Check(r2.Exit == 0, "fault-stop " + kind + " child exit=" + r2.Exit + " :: " + r2.Output); + } } + private static (int Exit, string Output) RunFaultChild(string mode, string kind) + { + var host = Environment.ProcessPath ?? "dotnet"; + var assembly = typeof(Program).Assembly.Location; + var info = new System.Diagnostics.ProcessStartInfo(host) + { + RedirectStandardOutput = true, + RedirectStandardError = true, + UseShellExecute = false, + WorkingDirectory = AppContext.BaseDirectory, + // Resolve the same private runtime the parent is running on (the muxer lives beside + // shared/Microsoft.NETCore.App/); an inherited DOTNET_ROOT may point elsewhere. + Environment = + { + ["DOTNET_ROOT"] = string.IsNullOrEmpty(Environment.GetEnvironmentVariable("DOTNET_ROOT")) + ? System.IO.Path.GetFullPath(System.IO.Path.Combine(AppContext.BaseDirectory, "..", "..", "..")) + : Environment.GetEnvironmentVariable("DOTNET_ROOT")!, + ["DOTNET_MULTILEVEL_LOOKUP"] = "0", + }, + }; + info.ArgumentList.Add("exec"); + info.ArgumentList.Add("--fx-version"); + info.ArgumentList.Add("12.0.0"); + if (!string.Equals(System.IO.Path.GetFileNameWithoutExtension(host), + System.IO.Path.GetFileNameWithoutExtension(assembly), StringComparison.OrdinalIgnoreCase)) + info.ArgumentList.Add(assembly); + info.ArgumentList.Add(mode); + info.ArgumentList.Add(kind); + using var process = System.Diagnostics.Process.Start(info)!; + var stdout = process.StandardOutput.ReadToEndAsync(); + var stderr = process.StandardError.ReadToEndAsync(); + if (!process.WaitForExit(60000)) + { + try { process.Kill(true); } catch { } + throw new InvalidOperationException("fault child watchdog"); + } + var output = (stdout.GetAwaiter().GetResult() + " " + stderr.GetAwaiter().GetResult()).Trim(); + return (process.ExitCode, output.Length > 400 ? output[..400] : output); + } + + private static WeakReference RunAndCaptureContext(string entry) { var session = new MapRunner().Start(Package(entry), Options("Epoch")); From 593551a334867ed74c9c6763eeb20ff6162d41a4 Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:47:02 +0800 Subject: [PATCH 04/15] Harden the epoch verifier input pins and post-run rechecks Problem: the verifier hashed the resolved IL CoreLib but pinned the non-existent build/name path, parsed the source manifest as text before pinning, and did not re-validate the runtime HEAD/status/declared files after the run. Change: - pin the actually resolved produced paths (CoreLib under IL/ in this build subset); - read the source manifest once, keep its sha256 and length, write a consumed copy as an output, and verify that copy still hashes to the pinned bytes at the end; - re-check the runtime HEAD, worktree status and declared source hashes after the tests; - replace the unconditional localUncommitted:true with the factual mode (dirty only when the manifest declares files) and record the manifest hash/length in the summary. Verification: verifier PASS, pins=658, layout=520 on the frozen epoch binaries; the epoch suite still passes 24/24 with no skip. Assisted-by: Cindy (https://cindy.app) --- eng/verify-epoch-integration.py | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/eng/verify-epoch-integration.py b/eng/verify-epoch-integration.py index 76d7180..981d417 100644 --- a/eng/verify-epoch-integration.py +++ b/eng/verify-epoch-integration.py @@ -45,7 +45,11 @@ def main(): raise ValueError("Output must be a new directory.") output.mkdir(parents=True) - manifest = json.loads(args.source_manifest.read_text(encoding="utf-8")) + manifest_bytes = args.source_manifest.read_bytes() + manifest_sha = hashlib.sha256(manifest_bytes).hexdigest() + manifest_length = len(manifest_bytes) + (output / "source-manifest.copy.json").write_bytes(manifest_bytes) + manifest = json.loads(manifest_bytes.decode("utf-8")) head = git(runtime, "rev-parse", "HEAD") if head != (manifest.get("head") or manifest.get("baseline_head")): raise ValueError("Runtime HEAD mismatch: " + head) @@ -64,6 +68,7 @@ def main(): outputs = {"System.Private.CoreLib.dll": "CoreLib", "coreclr.dll": "coreclr", "clrjit.dll": "clrjit", "clrinterpreter.dll": "clrinterpreter", "corerun.exe": "corerun"} artifact = {} + produced_paths = {} for name in outputs: produced, installed = build / name, shared / name if not produced.is_file(): @@ -79,6 +84,7 @@ def main(): if digest(produced) != digest(installed): raise ValueError("Layout " + name + " does not equal the runtime build output.") artifact[name] = digest(produced) + produced_paths[name] = produced harness = root / "tests/RuneCLR.EpochDeadline.Tests/bin/Release/net11.0/RuneCLR.EpochDeadline.Tests.dll" inputs = {harness, Path(__file__).resolve(), root / "RuneCLR.slnx", root / "Directory.Build.props", @@ -88,7 +94,7 @@ def main(): inputs.update(path for path in folder.rglob("*") if path.is_file() and not {"bin", "obj"}.intersection(path.relative_to(folder).parts)) inputs.update(path for path in layout.rglob("*") if path.is_file()) - inputs.update(build / name for name in outputs) + inputs.update(produced_paths[name] for name in outputs) pins = {str(path): digest(path) for path in sorted(inputs) if path.is_file()} write = output / "pins-before.json" write.write_text(json.dumps(pins, indent=2) + NL, encoding="utf-8") @@ -110,11 +116,26 @@ def main(): print(" " + (failures[0] if failures else "see log")) after = {str(path): digest(path) if path.is_file() else None for path in sorted(inputs)} + # Post-run re-validation: the runtime HEAD, its worktree state and the declared source files must be + # unchanged, and the consumed manifest copy must still hash to the bytes read at pin time. + if git(runtime, "rev-parse", "HEAD") != head: + raise RuntimeError("Runtime HEAD drifted during the run.") + status_after = subprocess.check_output(["git", "-C", str(runtime), "status", "--porcelain", "--untracked-files=normal"], text=True).splitlines() + changed_after = sorted(line[3:].strip() for line in status_after if line.strip()) + if changed_after != sorted(files): + raise RuntimeError("Runtime working tree drifted during the run.") + for name, value in files.items(): + if digest(runtime / name) != value: + raise RuntimeError("Declared runtime source drifted during the run: " + name) + if hashlib.sha256((output / "source-manifest.copy.json").read_bytes()).hexdigest() != manifest_sha: + raise RuntimeError("Consumed source manifest copy drifted.") (output / "pins-after.json").write_text(json.dumps(after, indent=2) + NL, encoding="utf-8") drift = [path for path in pins if pins[path] != after[path]] summary = {"harnessExit": process.returncode, "pinCount": len(pins), "drift": drift, "buildRID": args.build_rid, "artifact": artifact, - "sourceIdentity": {"head": head, "deltaFiles": len(files), "localUncommitted": True}, + "sourceIdentity": {"head": head, "deltaFiles": len(files), + "localUncommitted": bool(files), + "manifestSha256": manifest_sha, "manifestBytes": manifest_length}, "layoutFiles": sum(1 for p in layout.rglob("*") if p.is_file())} (output / "summary.json").write_text(json.dumps(summary, indent=2) + NL, encoding="utf-8") if drift: From 2387d81f2b6f1c70e88ecef3ad7ddd3224c1950f Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:48:17 +0800 Subject: [PATCH 05/15] Report the termination mechanism that actually tripped Problem: a session with both an instruction budget and a callback deadline reported the deadline error even when the instruction terminal had exhausted. Change: DescribeTermination() picks the message from the deadline snapshot reason when a deadline budget was exceeded and from the instruction-budget terminal state otherwise; a missing/retired deadline bridge or a failed query falls back to the terminal message. Author failures still report the exception type only, and the session still fails closed. Verification: full solution Release build 0 warnings/0 errors; stock lifecycle 156/156; epoch suite against the real epoch runtime 24 passed / 0 skipped / 0 failed; verifier PASS with 658 pins and a 520-file layout. Note for the both-feature case: the minimal epoch runtime has no instruction-terminal API, so native both-feature execution was not exercised here; only the pre-author missing-capability path is covered. Assisted-by: Cindy (https://cindy.app) --- src/RuneCLR.Runtime/MapSession.cs | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/src/RuneCLR.Runtime/MapSession.cs b/src/RuneCLR.Runtime/MapSession.cs index c065e73..48e8cfe 100644 --- a/src/RuneCLR.Runtime/MapSession.cs +++ b/src/RuneCLR.Runtime/MapSession.cs @@ -392,7 +392,7 @@ private void CheckPrototypeState() throw; } if (terminated) - throw new InvalidOperationException(_deadline is null ? TerminationError : DeadlineTerminationError); + throw new InvalidOperationException(DescribeTermination()); } private void BeginDeadline() @@ -437,6 +437,22 @@ private void CheckEpochTicker() FailDeadlineBridge($"The process epoch ticker failed ({fault})."); } + // Report the mechanism that actually tripped: the deadline reason when a deadline budget was exceeded, + // otherwise the instruction-budget terminal state. A missing/retired deadline bridge falls back to the + // terminal text, and query failures keep the fail-closed terminal message. + private string DescribeTermination() + { + if (_deadline is null) return TerminationError; + try + { + return _deadline.Snapshot(_loadContext!).Reason != 0 ? DeadlineTerminationError : TerminationError; + } + catch (Exception) + { + return TerminationError; + } + } + private void FailDeadlineBridge(string message) { _deadlineFailure ??= message; @@ -450,7 +466,7 @@ private string DescribeFailure(Exception exception) { try { - if (_terminal.IsTerminated(_loadContext!)) return _deadline is null ? TerminationError : DeadlineTerminationError; + if (_terminal.IsTerminated(_loadContext!)) return DescribeTermination(); } catch (Exception) { From 0f2f135098f046f2865e667746876e2ab4accebb Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:49:27 +0800 Subject: [PATCH 06/15] Verify the epoch host integration and document its scope Problem: the epoch runtime work had no host-side functional evidence, and the host bound the instruction-terminal prototype for deadline-only sessions. Change: the deadline ABI is independent of the terminal prototype, termination reporting picks the mechanism that actually tripped, the ticker-fault case runs as real child processes, and the verifier pins the resolved inputs (IL CoreLib, manifest read-to-pin consistency, post-run runtime/source rechecks). Verification: epoch suite 24 passed / 0 skipped / 0 failed against the frozen runtime; verifier PASS with 658 pins and a 520-file layout; stock lifecycle 156/156; solution build 0/0. Assisted-by: Cindy (https://cindy.app) --- eng/verify-epoch-integration.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/eng/verify-epoch-integration.py b/eng/verify-epoch-integration.py index 981d417..0b9cd56 100644 --- a/eng/verify-epoch-integration.py +++ b/eng/verify-epoch-integration.py @@ -96,6 +96,13 @@ def main(): inputs.update(path for path in layout.rglob("*") if path.is_file()) inputs.update(produced_paths[name] for name in outputs) pins = {str(path): digest(path) for path in sorted(inputs) if path.is_file()} + # Parse-to-pin consistency: the bytes parsed above must be the bytes pinned now. + pin_sha = pins.get(str(args.source_manifest.resolve())) + if pin_sha is None: + raise RuntimeError("Source manifest is missing from the input pins.") + if pin_sha != manifest_sha: + raise RuntimeError("Source manifest changed between parse and pin.") + loaded_sha = manifest_sha write = output / "pins-before.json" write.write_text(json.dumps(pins, indent=2) + NL, encoding="utf-8") @@ -127,7 +134,9 @@ def main(): for name, value in files.items(): if digest(runtime / name) != value: raise RuntimeError("Declared runtime source drifted during the run: " + name) - if hashlib.sha256((output / "source-manifest.copy.json").read_bytes()).hexdigest() != manifest_sha: + if hashlib.sha256(args.source_manifest.read_bytes()).hexdigest() != loaded_sha: + raise RuntimeError("Original source manifest changed during the run.") + if hashlib.sha256((output / "source-manifest.copy.json").read_bytes()).hexdigest() != loaded_sha: raise RuntimeError("Consumed source manifest copy drifted.") (output / "pins-after.json").write_text(json.dumps(after, indent=2) + NL, encoding="utf-8") drift = [path for path in pins if pins[path] != after[path]] From 17e54d97e0e8abfad4c312ab6b3ac151f7f05b2b Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:51:59 +0800 Subject: [PATCH 07/15] Document the current epoch host integration scope The tracked experiment doc still described a whitespace-only port with 5 passed / 19 skipped and a pending matching runtime. Rewrite it for the current state: the deadline ABI is decoupled from the instruction-terminal prototype, termination reporting follows the mechanism that tripped, the ticker-fault case is a real child-process regression, and the host suite plus verifier pass against the paired native branch. Historical figures stay labelled as history, the capability mask is corrected to bit0 clock / bit1 epoch (0x2), and provenance, limits and the unresolved performance question are stated. Assisted-by: Cindy (https://cindy.app) --- ...nal-epoch-deadline-integration-20261112.md | 97 +++++++++++++------ 1 file changed, 69 insertions(+), 28 deletions(-) diff --git a/docs/experiments/optional-epoch-deadline-integration-20261112.md b/docs/experiments/optional-epoch-deadline-integration-20261112.md index e187392..1fe5453 100644 --- a/docs/experiments/optional-epoch-deadline-integration-20261112.md +++ b/docs/experiments/optional-epoch-deadline-integration-20261112.md @@ -1,47 +1,88 @@ # Optional epoch callback deadline — host integration (2026-11-12) This branch integrates the reviewed 2026-11-10 epoch callback-deadline experiment onto the -current RuneCLR `origin/main` (cbac2a657793dca7f22b1e1feff4aab26b898b4e). It replaces the -archive branch `experiment/optional-epoch-deadline-20261112` (base bdbc7f52) as the host -integration line; that branch stays untouched as the sealed source snapshot. +current RuneCLR `origin/main` (cbac2a657793dca7f22b1e1feff4aab26b898b4e) and pairs it with the +matching native runtime branch `runeclr/optional-callback-epoch-integration-20261112` +(commit 7f5a0bc8c6d58a46d2dff91571cad04b2b3a9416, parent `runeclr/dev` 474eb8ad). ## What is integrated - `MapDeadlineMode` (`Clock` default, `Epoch` opt-in) plus the epoch period on `MapRunOptions`. -- `CallbackEpochTicker` (process-wide lease, single shared ticker) and - `CallbackEpochDiagnostics`, ported unchanged from the reviewed experiment. -- `CallbackDeadlineBridge` gains the additive epoch factory, tick/read delegates and the - capability check; `MapSession` leases the ticker before any author file is opened and releases - it after the author stack has returned. -- Epoch tests and the acceptance script from the experiment. +- `CallbackEpochTicker` (process-wide lease, one shared ticker) and `CallbackEpochDiagnostics`. +- `CallbackDeadlineBridge` gains the additive epoch factory, tick/read delegates and the capability + check; `MapSession` leases the ticker before any author file is opened and releases it after the + author stack has returned. +- Epoch tests and the verifier under `eng/verify-epoch-integration.py`. -The clock path is unchanged and remains the default. Epoch mode is explicit: a runtime without -the additive capability (version-1 clock ABI plus capability bit 2 plus the epoch factory/tick/ -read entry points) fails before author files are opened, never silently downgrades. +The clock path is unchanged and remains the default. -## Difference from the archive snapshot +## Behaviour beyond the archive snapshot -- The only source edit beyond the reviewed experiment is whitespace: the trailing blank line at - the end of `CallbackEpochTicker.cs` (the archive has a CRLF blank line at EOF) is removed so - this branch is `git diff --check` clean. The archive branch keeps its original bytes. -- No other behaviour changes. +This is not a whitespace-only port. Compared with the archived experiment the host now has +intentional behaviour changes: -## Verification status +- The callback-deadline ABI is independent of the old instruction-terminal prototype. A + deadline-only session binds only the deadline bridge; a session with an explicit instruction + budget still binds the terminal bridge, and both-feature sessions bind both. Previously a + deadline session required the terminal API, which a minimal deadline-only runtime does not have. +- Termination reporting picks the mechanism that actually tripped: the deadline snapshot reason + when a deadline budget was exceeded, otherwise the instruction-terminal state. Author failures + still report the exception type only, and the session still fails closed. +- The ticker-fault case is a real regression (child processes for arm/wait and live-lease/last-stop) + instead of a placeholder skip. -- Stock desktop build: `dotnet build RuneCLR.slnx -c Release` — 0 warnings, 0 errors. -- Stock regression: `tests/RuneCLR.Runtime.Tests` — 156/156 passed. -- Epoch tests on stock runtime: 5 passed, 19 skipped (matching private CoreCLR/native runtime not - present), 0 failed. Epoch enforcement is therefore **pending a matching runtime build**; the - 2026-11-10 campaign numbers come from the archived binaries and do not validate this branch. -- Native JIT/R2R remains a future direction: this work is an interpreter callback deadline. +The archive branch keeps its original bytes and is untouched. -## Runtime expectation +## Verification status (current) + +- Stock desktop build `dotnet build RuneCLR.slnx -c Release`: 0 warnings, 0 errors. +- Stock regression `tests/RuneCLR.Runtime.Tests`: 156/156 passed. +- Epoch suite against the matching private runtime: **24 passed / 0 skipped / 0 failed** + (host commits 17a41fb and the P3 reporting fix 2387d81). +- `eng/verify-epoch-integration.py`: PASS with 658 pinned inputs and a 520-file private layout + (verifier commit 0f2f135; run evidence `run13`). + +Historical figures are kept separate: the earlier stock-runtime run was 5 passed / 19 skipped +because no matching runtime was present, and the 2026-11-10 campaign numbers came from the +archived binaries. Those are history, not the current result. + +## Runtime expectation (paired branch) Matching runtime must provide, on `System.Runtime.Loader.AssemblyLoadContext`: - `RuneCLR_GetCallbackDeadlineVersion() -> long` returning 1 (existing clock ABI); -- `RuneCLR_GetCallbackDeadlineCapabilities() -> int` with bit 2 set for epoch support; -- `RuneCLR_CreateCallbackDeadlineEpoch(name, resolver, deadlineTicks, pollInterval, cleanupBudget, epochPeriodMicros)`; +- `RuneCLR_GetCallbackDeadlineCapabilities() -> int`: **bit0 (0x1) is the clock ABI and bit1 (0x2) + is the epoch ABI** — hosts test `(capabilities & 2) != 0`; there is no `1 << 2` bit; +- `RuneCLR_CreateCallbackDeadlineEpoch(name, resolver, deadlineTicks, pollInterval, cleanupBudget, + epochPeriodMicros)`; - `RuneCLR_TickCallbackDeadlineEpoch() -> long` and `RuneCLR_ReadCallbackDeadlineEpoch() -> long`. -The native side (reviewer5) owns that runtime delta; this branch is host-only. +## Provenance + +- Paired native: fork branch `runeclr/optional-callback-epoch-integration-20261112` at 7f5a0bc8, + parent `runeclr/dev` 474eb8ad; frozen binaries used for the run: coreclr `ed76bfa6…`, CoreLib + `6f181812…` (under IL/), clrinterpreter `905bb9bb…`, corerun `24ffba3e…`, clrjit `23e3411d…`. +- The verifier's source manifest `{head 7f5a0bc8, files {}}` records the CURRENT clean Git identity + of that worktree. It does not prove the binaries were compiled from that clean tree: the build + record is base 474eb8ad plus a 14-file delta with its own raw source hashes. + +## Limits + +- One active callback per session and a single owner thread; a competing callback or thread fails + closed with reason 4. +- Windows x64 Release interpreter only. No device, AOT, unmanaged-entry or global all-load evidence. +- Native blocking cannot be interrupted, including a `Sleep` inside a finally block; finalizers run + outside the deadline. This is not a sandbox. +- `InstallTestTimerFault` is an internal test hook compiled into the experiment assembly, not a + product API. `Stop`/`Dispose` must be called from an ordinary host thread, never from the ticker + path; the trusted tick/read calls are assumed non-blocking and the final join has no timeout. +- The both-feature case is not validated natively: the minimal epoch runtime has no + instruction-terminal API, so only the pre-author missing-capability path is covered. + +## Performance + +Unresolved. The 5.33x (poll interval 1) and 3.18x (poll interval 100) figures are a historical +microbenchmark scope (arithmetic lane versus the unconfigured interpreter), not a CPU gate and not +an acceptance for the roughly 2x budget tolerance. Conflicting measurements across runtime builds +mean a dedicated matched audit is still pending; no default-OFF cost conclusion is drawn here. + From 4a1c23d02dccc449382f9e3db83efcfa916da10c Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:52:31 +0800 Subject: [PATCH 08/15] Trim the trailing blank line in the epoch integration doc Fixes the git diff --check 'new blank line at EOF' report from the previous commit. Assisted-by: Cindy (https://cindy.app) --- docs/experiments/optional-epoch-deadline-integration-20261112.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/experiments/optional-epoch-deadline-integration-20261112.md b/docs/experiments/optional-epoch-deadline-integration-20261112.md index 1fe5453..cb29a29 100644 --- a/docs/experiments/optional-epoch-deadline-integration-20261112.md +++ b/docs/experiments/optional-epoch-deadline-integration-20261112.md @@ -85,4 +85,3 @@ Unresolved. The 5.33x (poll interval 1) and 3.18x (poll interval 100) figures ar microbenchmark scope (arithmetic lane versus the unconfigured interpreter), not a CPU gate and not an acceptance for the roughly 2x budget tolerance. Conflicting measurements across runtime builds mean a dedicated matched audit is still pending; no default-OFF cost conclusion is drawn here. - From b4b060eb7f3c88426e1b942d7a05955ed755d264 Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:57:17 +0800 Subject: [PATCH 09/15] Land the epoch verifier provenance fixture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Import the independently authored tooling fixture (sha256 c45da78d…) as eng/test-epoch-integration-provenance.py and normalise the verifier's source manifest path once to an absolute path, so a relative --source-manifest resolves to the same pin key the parse-to-pin equality check compares against. The fixture is tooling-only: it drives the verifier with a fake harness and never stands in for native acceptance evidence. Verification: fixture 7/7 passed (including the parse/pin mismatch case that failed against the previous verifier), py_compile clean, git diff --check clean, and the real pinned verifier still PASS with 658 pins / 520-file layout and the epoch suite at 24 passed / 0 skipped / 0 failed. Assisted-by: Cindy (https://cindy.app) --- eng/test-epoch-integration-provenance.py | 316 +++++++++++++++++++++++ eng/verify-epoch-integration.py | 9 +- 2 files changed, 322 insertions(+), 3 deletions(-) create mode 100644 eng/test-epoch-integration-provenance.py diff --git a/eng/test-epoch-integration-provenance.py b/eng/test-epoch-integration-provenance.py new file mode 100644 index 0000000..bf6199e --- /dev/null +++ b/eng/test-epoch-integration-provenance.py @@ -0,0 +1,316 @@ +#!/usr/bin/env python3 +"""Fixture regressions for eng/verify-epoch-integration.py. + +Self-contained stdlib test: builds throwaway git/host/layout fixtures, imports the real +verifier module from --host-root and drives its real main() path with a fixture-only +subprocess.run stub for the harness child. Git, digest and input-pinning code all run for real. + +Installed later as eng/test-epoch-integration-provenance.py; default host root is +Path(__file__).resolve().parents[1]. No native matrix is executed here. +""" +import argparse +import contextlib +import hashlib +import importlib.util +import io +import json +import shutil +import subprocess +import sys +import tempfile +import types +from pathlib import Path + + +def digest(path): + with Path(path).open('rb') as stream: + return hashlib.file_digest(stream, 'sha256').hexdigest() + + +def load_verifier(host_root): + path = Path(host_root) / 'eng' / 'verify-epoch-integration.py' + if not path.is_file(): + raise SystemExit('verifier not found: ' + str(path)) + spec = importlib.util.spec_from_file_location('epoch_verifier_under_test', path) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module, digest(path) + + +NATIVE = {'coreclr.dll': b'coreclr-fixture', 'clrjit.dll': b'clrjit-fixture', + 'clrinterpreter.dll': b'interpreter-fixture', 'corerun.exe': b'corerun-fixture'} +DIRTY_FILE = 'src/RuneCLR.Runtime/Committed.cs' + + +class Fixture: + def __init__(self, base, il_fallback=True): + self.base = Path(base) + self.il_fallback = il_fallback + self.host = self.base / 'host' + self.runtime = self.base / 'runtime' + self.layout = self.base / 'layout' + self.build = self.runtime / 'artifacts/bin/coreclr/windows.x64.Release' + self.manifest_path = self.base / 'source-manifest.json' + self._build() + + def git(self, *args, check=True): + return subprocess.run(['git', '-C', str(self.runtime), *args], capture_output=True, text=True, check=check) + + def _build(self): + (self.host / 'eng').mkdir(parents=True) + (self.host / 'RuneCLR.slnx').write_text('' + chr(10), encoding='utf-8') + (self.host / 'Directory.Build.props').write_text('' + chr(10), encoding='utf-8') + harness_dir = self.host / 'tests/RuneCLR.EpochDeadline.Tests/bin/Release/net11.0' + harness_dir.mkdir(parents=True) + (harness_dir / 'RuneCLR.EpochDeadline.Tests.dll').write_bytes(b'harness-fixture') + (self.host / 'src/RuneCLR.Runtime').mkdir(parents=True) + (self.host / 'src/RuneCLR.Runtime/MapSession.cs').write_text('// fixture source' + chr(10), encoding='utf-8') + (self.host / 'tests/RuneCLR.EpochDeadline.Tests/Program.cs').write_text('// fixture test' + chr(10), encoding='utf-8') + + self.build.mkdir(parents=True) + for name, payload in NATIVE.items(): + (self.build / name).write_bytes(payload) + corelib = b'corelib-fixture' + if self.il_fallback: + (self.build / 'IL').mkdir() + (self.build / 'IL/System.Private.CoreLib.dll').write_bytes(corelib) + else: + (self.build / 'System.Private.CoreLib.dll').write_bytes(corelib) + + shared = self.layout / 'shared/Microsoft.NETCore.App/12.0.0' + shared.mkdir(parents=True) + for name, payload in NATIVE.items(): + (shared / name).write_bytes(payload) + (shared / 'System.Private.CoreLib.dll').write_bytes(corelib) + (self.layout / 'dotnet.exe').write_bytes(b'dotnet-fixture') + + self.runtime.mkdir(parents=True, exist_ok=True) + self.git('init', '-q') + self.git('config', 'user.email', 'fixture@example.invalid') + self.git('config', 'user.name', 'fixture') + dirty = self.runtime / DIRTY_FILE + dirty.parent.mkdir(parents=True) + dirty.write_text('// baseline' + chr(10), encoding='utf-8') + self.git('add', '-A') + self.git('commit', '-q', '-m', 'fixture baseline') + dirty.write_text('// dirty' + chr(10), encoding='utf-8') + self.write_manifest() + + def head(self): + return self.git('rev-parse', 'HEAD').stdout.strip() + + def manifest(self): + return {'head': self.head(), + 'dirty_files': {DIRTY_FILE: digest(self.runtime / DIRTY_FILE)}} + + def write_manifest(self, extra_space=False): + text = json.dumps(self.manifest(), indent=2) + if extra_space: + text = text.replace('"', '" ', 1) + self.manifest_path.write_text(text + chr(10), encoding='utf-8') + + def argv(self, output): + return ['--host-root', str(self.host), '--layout', str(self.layout), + '--runtime-root', str(self.runtime), '--source-manifest', str(self.manifest_path), + '--output', str(output)] + + +def run_main(module, argv, on_harness=None): + """Drive the real main() with a fixture-only child-process stub for the harness.""" + + def stub(command, cwd=None, env=None, stdout=None, stderr=None, timeout=None, check=False): + if on_harness is not None: + on_harness() + if stdout is not None: + stdout.write(b'PASS fixture harness' + bytes([10])) + return types.SimpleNamespace(returncode=0, stdout='', stderr='') + + # Give the verifier module its own subprocess shim so the git helpers in this file keep + # using the real module (the verifier only uses run() for the harness child). + real_subprocess = module.subprocess + shim = types.SimpleNamespace(run=stub, check_output=real_subprocess.check_output, + check_call=real_subprocess.check_call, PIPE=real_subprocess.PIPE, + DEVNULL=real_subprocess.DEVNULL, STDOUT=real_subprocess.STDOUT, + CalledProcessError=real_subprocess.CalledProcessError) + + previous_argv = sys.argv + sys.argv = ['verify-epoch-integration.py'] + list(argv) + module.subprocess = shim + text = io.StringIO() + try: + with contextlib.redirect_stdout(text): + module.main() + return True, '', text.getvalue() + except Exception as error: + return False, str(error), text.getvalue() + finally: + module.subprocess = real_subprocess + sys.argv = previous_argv + + +def rejected(result, *keywords): + ok, error, _ = result + lowered = error.lower() + return (not ok) and any(keyword.lower() in lowered for keyword in keywords) + ok, error, _ = result + return (not ok) and keyword.lower() in error.lower() + + +def case_positive(fixture, module): + output = fixture.base / 'out-positive' + ok, error, text = run_main(module, fixture.argv(output)) + if not ok: + return False, 'positive run rejected: ' + error + pins = json.loads((output / 'pins-before.json').read_text(encoding='utf-8')) + il = str(fixture.build / 'IL/System.Private.CoreLib.dll') + if il not in pins: + return False, 'accepted, but the produced IL CoreLib is not pinned (known gap)' + return True, 'accepted and the IL produced file is pinned' + + +def case_il_produced_drift(fixture, module): + output = fixture.base / 'out-il-drift' + il = fixture.build / 'IL/System.Private.CoreLib.dll' + + def drift(): + il.write_bytes(il.read_bytes() + b'!') + + result = run_main(module, fixture.argv(output), on_harness=drift) + if rejected(result, 'drift', 'changed during the run'): + return True, 'IL produced file change rejected as drift' + if result[0]: + return False, 'IL produced file changed during the run but the run was accepted (known gap)' + return False, 'rejected for an unexpected reason: ' + result[1] + + +def case_manifest_between_parse_and_pin(fixture, module): + output = fixture.base / 'out-manifest-pin' + real_digest = module.digest + state = {'done': False} + + def wrapped(path): + if not state['done'] and Path(path) == fixture.manifest_path: + state['done'] = True + fixture.write_manifest(extra_space=True) + return real_digest(path) + + module.digest = wrapped + try: + result = run_main(module, fixture.argv(output)) + finally: + module.digest = real_digest + if not state['done']: + return False, 'fixture did not reach the manifest pin' + if result[0]: + return False, 'manifest changed between parse and pin but the run was accepted (known gap)' + return True, 'manifest parse/pin mismatch rejected' + + +def case_manifest_during_run(fixture, module): + output = fixture.base / 'out-manifest-run' + result = run_main(module, fixture.argv(output), on_harness=lambda: fixture.write_manifest(extra_space=True)) + if rejected(result, 'drift', 'changed during the run'): + return True, 'manifest change during the run rejected as drift' + return False, ('accepted despite a manifest change during the run' if result[0] else 'rejected for an unexpected reason: ' + result[1]) + + +def case_consumed_copy(fixture, module): + output = fixture.base / 'out-consumed' + ok, error, _ = run_main(module, fixture.argv(output)) + if not ok: + return False, 'positive run rejected: ' + error + copies = [p for p in output.rglob('*') if p.is_file() and ('consumed' in p.name.lower() or 'copy' in p.name.lower())] + if not copies: + return None, 'verifier writes no consumed manifest copy, so copy drift cannot be exercised' + source = digest(fixture.manifest_path) + for copy in copies: + if digest(copy) != source: + return False, 'consumed copy does not match the manifest: ' + copy.name + return True, 'consumed copy matches the manifest bytes' + + +def case_runtime_head_drift(fixture, module): + output = fixture.base / 'out-head-drift' + + def drift(): + fixture.git('commit', '-q', '--allow-empty', '-m', 'fixture head drift') + + result = run_main(module, fixture.argv(output), on_harness=drift) + if result[0]: + return False, 'runtime HEAD changed during the run but the run was accepted (known gap)' + return True, 'runtime HEAD change rejected: ' + result[1] + + +def case_stdout_append(fixture, module): + output = fixture.base / 'out-stdout' + ok, error, _ = run_main(module, fixture.argv(output)) + if not ok: + return False, 'positive run rejected: ' + error + pins = json.loads((output / 'pins-before.json').read_text(encoding='utf-8')) + stdout_log = output / 'tests.stdout.log' + if str(stdout_log) in pins: + return False, 'the run stdout log is pinned as an input' + summary = json.loads((output / 'summary.json').read_text(encoding='utf-8')) + if summary.get('drift'): + return False, 'unexpected drift in a clean run: ' + repr(summary['drift']) + with stdout_log.open('ab') as stream: + stream.write(b'appended after the run' + bytes([10])) + if digest(fixture.manifest_path) != pins.get(str(fixture.manifest_path), digest(fixture.manifest_path)): + return False, 'manifest pin does not match the manifest' + return True, 'stdout is not pinned and appending after the run is harmless' + + +CASES = [ + ('positive-clean-il-fallback', case_positive), + ('il-produced-drift', case_il_produced_drift), + ('manifest-parse-pin-change', case_manifest_between_parse_and_pin), + ('manifest-during-run', case_manifest_during_run), + ('consumed-copy', case_consumed_copy), + ('runtime-head-drift', case_runtime_head_drift), + ('stdout-append', case_stdout_append), +] + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--host-root', type=Path, default=Path(__file__).resolve().parents[1]) + parser.add_argument('--keep', action='store_true', help='keep the fixture directories') + parser.add_argument('--workdir', type=Path, default=None) + args = parser.parse_args() + + module, verifier_sha = load_verifier(args.host_root) + print('VERIFIER ' + str((Path(args.host_root) / 'eng/verify-epoch-integration.py').resolve()) + ' sha256=' + verifier_sha) + + base = Path(args.workdir) if args.workdir else Path(tempfile.mkdtemp(prefix='epoch-provenance-')) + base.mkdir(parents=True, exist_ok=True) + failures = 0 + skipped = 0 + try: + for name, case in CASES: + fixture_root = base / name + fixture_root.mkdir(parents=True, exist_ok=True) + fixture = Fixture(fixture_root) + try: + outcome, detail = case(fixture, module) + except Exception as error: + outcome, detail = False, 'fixture error: ' + type(error).__name__ + ': ' + str(error) + if outcome is None: + skipped += 1 + print('SKIP ' + name + ' :: ' + detail) + elif outcome: + print('PASS ' + name + ' :: ' + detail) + else: + failures += 1 + print('FAIL ' + name + ' :: ' + detail) + finally: + if not args.keep and args.workdir is None: + shutil.rmtree(base, ignore_errors=True) + else: + print('WORKDIR ' + str(base)) + print('EPOCH_PROVENANCE_TESTS passed=' + str(len(CASES) - failures - skipped) + + ' skipped=' + str(skipped) + ' failed=' + str(failures) + ' verifier=' + verifier_sha[:12]) + return 0 if failures == 0 else 1 + + +if __name__ == '__main__': + sys.exit(main()) \ No newline at end of file diff --git a/eng/verify-epoch-integration.py b/eng/verify-epoch-integration.py index 0b9cd56..dc1ece1 100644 --- a/eng/verify-epoch-integration.py +++ b/eng/verify-epoch-integration.py @@ -45,7 +45,10 @@ def main(): raise ValueError("Output must be a new directory.") output.mkdir(parents=True) - manifest_bytes = args.source_manifest.read_bytes() + # Normalise the manifest path once: the pins use resolved paths, so a relative --source-manifest + # must resolve to the same key or the parse-to-pin equality would report a false missing pin. + source_manifest = args.source_manifest.resolve() + manifest_bytes = source_manifest.read_bytes() manifest_sha = hashlib.sha256(manifest_bytes).hexdigest() manifest_length = len(manifest_bytes) (output / "source-manifest.copy.json").write_bytes(manifest_bytes) @@ -97,7 +100,7 @@ def main(): inputs.update(produced_paths[name] for name in outputs) pins = {str(path): digest(path) for path in sorted(inputs) if path.is_file()} # Parse-to-pin consistency: the bytes parsed above must be the bytes pinned now. - pin_sha = pins.get(str(args.source_manifest.resolve())) + pin_sha = pins.get(str(source_manifest)) if pin_sha is None: raise RuntimeError("Source manifest is missing from the input pins.") if pin_sha != manifest_sha: @@ -134,7 +137,7 @@ def main(): for name, value in files.items(): if digest(runtime / name) != value: raise RuntimeError("Declared runtime source drifted during the run: " + name) - if hashlib.sha256(args.source_manifest.read_bytes()).hexdigest() != loaded_sha: + if hashlib.sha256(source_manifest.read_bytes()).hexdigest() != loaded_sha: raise RuntimeError("Original source manifest changed during the run.") if hashlib.sha256((output / "source-manifest.copy.json").read_bytes()).hexdigest() != loaded_sha: raise RuntimeError("Consumed source manifest copy drifted.") From fa89805c8171eb034d55d564f33813ab5f9ee63d Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Thu, 12 Nov 2026 20:06:20 +0800 Subject: [PATCH 10/15] Complete the epoch provenance fixture coverage Add a true clean-current-commit positive (the existing positive is now named as a declared-dirty source), a consumed-copy corruption case, an untracked runtime status-drift case, and a relative --source-manifest case driven from a deliberate working directory. Drop the unreachable tail in rejected() and reword the docstring so it describes the committed file instead of an installation step. The relative-manifest case exposed that the base verifier normalised the manifest path only for parsing: the pin set still used the raw argument, so the parse-to-pin equality failed for relative paths. Pin the resolved path (one line); absolute paths pin exactly the same set as before. The file is converted to LF, matching the repository convention, so git diff --check is clean under eng/** -text. Verification: fixture 11/11 passed with the default host root and with an explicit --host-root (11 passed / 0 skipped / 0 failed), py_compile clean, git diff --check clean. This is tooling-only: the frozen runtime, layout, product source, SDK and the run14 verifier evidence are unchanged. The experiment doc records the focused upstream results and the interpreter-runner qualification, with no epoch timing claim. Assisted-by: Cindy (https://cindy.app) --- ...nal-epoch-deadline-integration-20261112.md | 44 +- eng/test-epoch-integration-provenance.py | 702 ++++++++++-------- eng/verify-epoch-integration.py | 2 +- 3 files changed, 431 insertions(+), 317 deletions(-) diff --git a/docs/experiments/optional-epoch-deadline-integration-20261112.md b/docs/experiments/optional-epoch-deadline-integration-20261112.md index cb29a29..7b2cc5f 100644 --- a/docs/experiments/optional-epoch-deadline-integration-20261112.md +++ b/docs/experiments/optional-epoch-deadline-integration-20261112.md @@ -40,12 +40,54 @@ The archive branch keeps its original bytes and is untouched. - Epoch suite against the matching private runtime: **24 passed / 0 skipped / 0 failed** (host commits 17a41fb and the P3 reporting fix 2387d81). - `eng/verify-epoch-integration.py`: PASS with 658 pinned inputs and a 520-file private layout - (verifier commit 0f2f135; run evidence `run13`). + (verifier commit 0f2f135; run evidence `run13`). The same runtime layout was re-run as `run14` + on the fixture landing: 24 passed / 0 skipped / 0 failed, the same 658 pins and 520 files. The + later one-line relative-manifest pin fix does not change absolute-path runs. Historical figures are kept separate: the earlier stock-runtime run was 5 passed / 19 skipped because no matching runtime was present, and the 2026-11-10 campaign numbers came from the archived binaries. Those are history, not the current result. +## Tooling regressions + +`eng/test-epoch-integration-provenance.py` builds throwaway Git/host/layout fixtures and drives the +real `main()` of `eng/verify-epoch-integration.py` with a fixture-only stub for the harness child; +git, digest and input-pinning code all run for real. Run from the repository root: + +```sh +python3 eng/test-epoch-integration-provenance.py +``` + +Result for this candidate: **11 passed / 0 skipped / 0 failed**, confirmed both with the default +host root and with an explicit `--host-root`. The cases are: a dirty declared-source positive and a +clean committed-worktree positive (both also require the produced IL CoreLib to be pinned); IL +produced-file drift; a manifest change between parse and pin; a manifest change during the run; a +corrupted consumed manifest copy; runtime HEAD drift; untracked runtime-source status drift; a +relative `--source-manifest` resolved under a deliberate working directory and pinned under its +resolved key; and stdout appended after the run (stdout is not an input, so that is harmless). + +The suite exposed one remaining path bug in the base verifier: the pin set still used the raw +`--source-manifest` argument, so a relative path failed the parse-to-pin equality even though the +path had already been normalised for parsing. The fix reuses that normalisation and is a single +line; absolute paths pin exactly the same set as before. + +## Focused upstream regression on the frozen runtime + +A private flat Core_Root was assembled from the frozen Release layout without modifying any +layout, binary, host branch or SDK. Four official tests each reported **Expected 100 / Actual 100, +exit 0**: `ContextualReflection`, `CollectibleStatics`, `GenericVirtualMethod` and +`InterpreterTester`. The five Core_Root binaries were identical before and after the runs: coreclr +`ed76bfa6…`, clrjit `23e3411d…`, clrinterpreter `905bb9bb…`, corerun `24ffba3e…`, +System.Private.CoreLib `6f181812…` (under IL/). The test assemblies came from the official +474-based test source and were not recompiled for these runs. + +`InterpreterTester` is the official wrapper and sets `DOTNET_Interpreter=RunInterpreterTests` +internally. That runner configuration alone is not an independent per-method interpreted-mode +trace: the same app also exits 100 with the switch off, and `DOTNET_InterpList`/`DOTNET_InterpDump` +produced no method lines in this build. The pass is therefore compatibility evidence for the +documented configuration, not proof of interpreted method entry, and it is not an epoch timing or +overhead measurement. + ## Runtime expectation (paired branch) Matching runtime must provide, on `System.Runtime.Loader.AssemblyLoadContext`: diff --git a/eng/test-epoch-integration-provenance.py b/eng/test-epoch-integration-provenance.py index bf6199e..5f97d33 100644 --- a/eng/test-epoch-integration-provenance.py +++ b/eng/test-epoch-integration-provenance.py @@ -1,316 +1,388 @@ -#!/usr/bin/env python3 -"""Fixture regressions for eng/verify-epoch-integration.py. - -Self-contained stdlib test: builds throwaway git/host/layout fixtures, imports the real -verifier module from --host-root and drives its real main() path with a fixture-only -subprocess.run stub for the harness child. Git, digest and input-pinning code all run for real. - -Installed later as eng/test-epoch-integration-provenance.py; default host root is -Path(__file__).resolve().parents[1]. No native matrix is executed here. -""" -import argparse -import contextlib -import hashlib -import importlib.util -import io -import json -import shutil -import subprocess -import sys -import tempfile -import types -from pathlib import Path - - -def digest(path): - with Path(path).open('rb') as stream: - return hashlib.file_digest(stream, 'sha256').hexdigest() - - -def load_verifier(host_root): - path = Path(host_root) / 'eng' / 'verify-epoch-integration.py' - if not path.is_file(): - raise SystemExit('verifier not found: ' + str(path)) - spec = importlib.util.spec_from_file_location('epoch_verifier_under_test', path) - module = importlib.util.module_from_spec(spec) - spec.loader.exec_module(module) - return module, digest(path) - - -NATIVE = {'coreclr.dll': b'coreclr-fixture', 'clrjit.dll': b'clrjit-fixture', - 'clrinterpreter.dll': b'interpreter-fixture', 'corerun.exe': b'corerun-fixture'} -DIRTY_FILE = 'src/RuneCLR.Runtime/Committed.cs' - - -class Fixture: - def __init__(self, base, il_fallback=True): - self.base = Path(base) - self.il_fallback = il_fallback - self.host = self.base / 'host' - self.runtime = self.base / 'runtime' - self.layout = self.base / 'layout' - self.build = self.runtime / 'artifacts/bin/coreclr/windows.x64.Release' - self.manifest_path = self.base / 'source-manifest.json' - self._build() - - def git(self, *args, check=True): - return subprocess.run(['git', '-C', str(self.runtime), *args], capture_output=True, text=True, check=check) - - def _build(self): - (self.host / 'eng').mkdir(parents=True) - (self.host / 'RuneCLR.slnx').write_text('' + chr(10), encoding='utf-8') - (self.host / 'Directory.Build.props').write_text('' + chr(10), encoding='utf-8') - harness_dir = self.host / 'tests/RuneCLR.EpochDeadline.Tests/bin/Release/net11.0' - harness_dir.mkdir(parents=True) - (harness_dir / 'RuneCLR.EpochDeadline.Tests.dll').write_bytes(b'harness-fixture') - (self.host / 'src/RuneCLR.Runtime').mkdir(parents=True) - (self.host / 'src/RuneCLR.Runtime/MapSession.cs').write_text('// fixture source' + chr(10), encoding='utf-8') - (self.host / 'tests/RuneCLR.EpochDeadline.Tests/Program.cs').write_text('// fixture test' + chr(10), encoding='utf-8') - - self.build.mkdir(parents=True) - for name, payload in NATIVE.items(): - (self.build / name).write_bytes(payload) - corelib = b'corelib-fixture' - if self.il_fallback: - (self.build / 'IL').mkdir() - (self.build / 'IL/System.Private.CoreLib.dll').write_bytes(corelib) - else: - (self.build / 'System.Private.CoreLib.dll').write_bytes(corelib) - - shared = self.layout / 'shared/Microsoft.NETCore.App/12.0.0' - shared.mkdir(parents=True) - for name, payload in NATIVE.items(): - (shared / name).write_bytes(payload) - (shared / 'System.Private.CoreLib.dll').write_bytes(corelib) - (self.layout / 'dotnet.exe').write_bytes(b'dotnet-fixture') - - self.runtime.mkdir(parents=True, exist_ok=True) - self.git('init', '-q') - self.git('config', 'user.email', 'fixture@example.invalid') - self.git('config', 'user.name', 'fixture') - dirty = self.runtime / DIRTY_FILE - dirty.parent.mkdir(parents=True) - dirty.write_text('// baseline' + chr(10), encoding='utf-8') - self.git('add', '-A') - self.git('commit', '-q', '-m', 'fixture baseline') - dirty.write_text('// dirty' + chr(10), encoding='utf-8') - self.write_manifest() - - def head(self): - return self.git('rev-parse', 'HEAD').stdout.strip() - - def manifest(self): - return {'head': self.head(), - 'dirty_files': {DIRTY_FILE: digest(self.runtime / DIRTY_FILE)}} - - def write_manifest(self, extra_space=False): - text = json.dumps(self.manifest(), indent=2) - if extra_space: - text = text.replace('"', '" ', 1) - self.manifest_path.write_text(text + chr(10), encoding='utf-8') - - def argv(self, output): - return ['--host-root', str(self.host), '--layout', str(self.layout), - '--runtime-root', str(self.runtime), '--source-manifest', str(self.manifest_path), - '--output', str(output)] - - -def run_main(module, argv, on_harness=None): - """Drive the real main() with a fixture-only child-process stub for the harness.""" - - def stub(command, cwd=None, env=None, stdout=None, stderr=None, timeout=None, check=False): - if on_harness is not None: - on_harness() - if stdout is not None: - stdout.write(b'PASS fixture harness' + bytes([10])) - return types.SimpleNamespace(returncode=0, stdout='', stderr='') - - # Give the verifier module its own subprocess shim so the git helpers in this file keep - # using the real module (the verifier only uses run() for the harness child). - real_subprocess = module.subprocess - shim = types.SimpleNamespace(run=stub, check_output=real_subprocess.check_output, - check_call=real_subprocess.check_call, PIPE=real_subprocess.PIPE, - DEVNULL=real_subprocess.DEVNULL, STDOUT=real_subprocess.STDOUT, - CalledProcessError=real_subprocess.CalledProcessError) - - previous_argv = sys.argv - sys.argv = ['verify-epoch-integration.py'] + list(argv) - module.subprocess = shim - text = io.StringIO() - try: - with contextlib.redirect_stdout(text): - module.main() - return True, '', text.getvalue() - except Exception as error: - return False, str(error), text.getvalue() - finally: - module.subprocess = real_subprocess - sys.argv = previous_argv - - -def rejected(result, *keywords): - ok, error, _ = result - lowered = error.lower() - return (not ok) and any(keyword.lower() in lowered for keyword in keywords) - ok, error, _ = result - return (not ok) and keyword.lower() in error.lower() - - -def case_positive(fixture, module): - output = fixture.base / 'out-positive' - ok, error, text = run_main(module, fixture.argv(output)) - if not ok: - return False, 'positive run rejected: ' + error - pins = json.loads((output / 'pins-before.json').read_text(encoding='utf-8')) - il = str(fixture.build / 'IL/System.Private.CoreLib.dll') - if il not in pins: - return False, 'accepted, but the produced IL CoreLib is not pinned (known gap)' - return True, 'accepted and the IL produced file is pinned' - - -def case_il_produced_drift(fixture, module): - output = fixture.base / 'out-il-drift' - il = fixture.build / 'IL/System.Private.CoreLib.dll' - - def drift(): - il.write_bytes(il.read_bytes() + b'!') - - result = run_main(module, fixture.argv(output), on_harness=drift) - if rejected(result, 'drift', 'changed during the run'): - return True, 'IL produced file change rejected as drift' - if result[0]: - return False, 'IL produced file changed during the run but the run was accepted (known gap)' - return False, 'rejected for an unexpected reason: ' + result[1] - - -def case_manifest_between_parse_and_pin(fixture, module): - output = fixture.base / 'out-manifest-pin' - real_digest = module.digest - state = {'done': False} - - def wrapped(path): - if not state['done'] and Path(path) == fixture.manifest_path: - state['done'] = True - fixture.write_manifest(extra_space=True) - return real_digest(path) - - module.digest = wrapped - try: - result = run_main(module, fixture.argv(output)) - finally: - module.digest = real_digest - if not state['done']: - return False, 'fixture did not reach the manifest pin' - if result[0]: - return False, 'manifest changed between parse and pin but the run was accepted (known gap)' - return True, 'manifest parse/pin mismatch rejected' - - -def case_manifest_during_run(fixture, module): - output = fixture.base / 'out-manifest-run' - result = run_main(module, fixture.argv(output), on_harness=lambda: fixture.write_manifest(extra_space=True)) - if rejected(result, 'drift', 'changed during the run'): - return True, 'manifest change during the run rejected as drift' - return False, ('accepted despite a manifest change during the run' if result[0] else 'rejected for an unexpected reason: ' + result[1]) - - -def case_consumed_copy(fixture, module): - output = fixture.base / 'out-consumed' - ok, error, _ = run_main(module, fixture.argv(output)) - if not ok: - return False, 'positive run rejected: ' + error - copies = [p for p in output.rglob('*') if p.is_file() and ('consumed' in p.name.lower() or 'copy' in p.name.lower())] - if not copies: - return None, 'verifier writes no consumed manifest copy, so copy drift cannot be exercised' - source = digest(fixture.manifest_path) - for copy in copies: - if digest(copy) != source: - return False, 'consumed copy does not match the manifest: ' + copy.name - return True, 'consumed copy matches the manifest bytes' - - -def case_runtime_head_drift(fixture, module): - output = fixture.base / 'out-head-drift' - - def drift(): - fixture.git('commit', '-q', '--allow-empty', '-m', 'fixture head drift') - - result = run_main(module, fixture.argv(output), on_harness=drift) - if result[0]: - return False, 'runtime HEAD changed during the run but the run was accepted (known gap)' - return True, 'runtime HEAD change rejected: ' + result[1] - - -def case_stdout_append(fixture, module): - output = fixture.base / 'out-stdout' - ok, error, _ = run_main(module, fixture.argv(output)) - if not ok: - return False, 'positive run rejected: ' + error - pins = json.loads((output / 'pins-before.json').read_text(encoding='utf-8')) - stdout_log = output / 'tests.stdout.log' - if str(stdout_log) in pins: - return False, 'the run stdout log is pinned as an input' - summary = json.loads((output / 'summary.json').read_text(encoding='utf-8')) - if summary.get('drift'): - return False, 'unexpected drift in a clean run: ' + repr(summary['drift']) - with stdout_log.open('ab') as stream: - stream.write(b'appended after the run' + bytes([10])) - if digest(fixture.manifest_path) != pins.get(str(fixture.manifest_path), digest(fixture.manifest_path)): - return False, 'manifest pin does not match the manifest' - return True, 'stdout is not pinned and appending after the run is harmless' - - -CASES = [ - ('positive-clean-il-fallback', case_positive), - ('il-produced-drift', case_il_produced_drift), - ('manifest-parse-pin-change', case_manifest_between_parse_and_pin), - ('manifest-during-run', case_manifest_during_run), - ('consumed-copy', case_consumed_copy), - ('runtime-head-drift', case_runtime_head_drift), - ('stdout-append', case_stdout_append), -] - - -def main(): - parser = argparse.ArgumentParser(description=__doc__) - parser.add_argument('--host-root', type=Path, default=Path(__file__).resolve().parents[1]) - parser.add_argument('--keep', action='store_true', help='keep the fixture directories') - parser.add_argument('--workdir', type=Path, default=None) - args = parser.parse_args() - - module, verifier_sha = load_verifier(args.host_root) - print('VERIFIER ' + str((Path(args.host_root) / 'eng/verify-epoch-integration.py').resolve()) + ' sha256=' + verifier_sha) - - base = Path(args.workdir) if args.workdir else Path(tempfile.mkdtemp(prefix='epoch-provenance-')) - base.mkdir(parents=True, exist_ok=True) - failures = 0 - skipped = 0 - try: - for name, case in CASES: - fixture_root = base / name - fixture_root.mkdir(parents=True, exist_ok=True) - fixture = Fixture(fixture_root) - try: - outcome, detail = case(fixture, module) - except Exception as error: - outcome, detail = False, 'fixture error: ' + type(error).__name__ + ': ' + str(error) - if outcome is None: - skipped += 1 - print('SKIP ' + name + ' :: ' + detail) - elif outcome: - print('PASS ' + name + ' :: ' + detail) - else: - failures += 1 - print('FAIL ' + name + ' :: ' + detail) - finally: - if not args.keep and args.workdir is None: - shutil.rmtree(base, ignore_errors=True) - else: - print('WORKDIR ' + str(base)) - print('EPOCH_PROVENANCE_TESTS passed=' + str(len(CASES) - failures - skipped) + - ' skipped=' + str(skipped) + ' failed=' + str(failures) + ' verifier=' + verifier_sha[:12]) - return 0 if failures == 0 else 1 - - -if __name__ == '__main__': +#!/usr/bin/env python3 +"""Fixture regressions for eng/verify-epoch-integration.py. + +Self-contained stdlib test: builds throwaway git/host/layout fixtures, imports the real +verifier module from --host-root and drives its real main() path with a fixture-only +subprocess.run stub for the harness child. Git, digest and input-pinning code all run for real. + +This is the committed fixture set at eng/test-epoch-integration-provenance.py; the default +host root is Path(__file__).resolve().parents[1]. No native matrix is executed here. +""" +import argparse +import contextlib +import hashlib +import importlib.util +import io +import json +import os +import shutil +import subprocess +import sys +import tempfile +import types +from pathlib import Path + + +def digest(path): + with Path(path).open('rb') as stream: + return hashlib.file_digest(stream, 'sha256').hexdigest() + + +def load_verifier(host_root): + path = Path(host_root) / 'eng' / 'verify-epoch-integration.py' + if not path.is_file(): + raise SystemExit('verifier not found: ' + str(path)) + spec = importlib.util.spec_from_file_location('epoch_verifier_under_test', path) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module, digest(path) + + +NATIVE = {'coreclr.dll': b'coreclr-fixture', 'clrjit.dll': b'clrjit-fixture', + 'clrinterpreter.dll': b'interpreter-fixture', 'corerun.exe': b'corerun-fixture'} +DIRTY_FILE = 'src/RuneCLR.Runtime/Committed.cs' + + +class Fixture: + def __init__(self, base, il_fallback=True, dirty=True): + self.base = Path(base) + self.il_fallback = il_fallback + self.dirty = dirty + self.host = self.base / 'host' + self.runtime = self.base / 'runtime' + self.layout = self.base / 'layout' + self.build = self.runtime / 'artifacts/bin/coreclr/windows.x64.Release' + self.manifest_path = self.base / 'source-manifest.json' + self._build() + + def git(self, *args, check=True): + return subprocess.run(['git', '-C', str(self.runtime), *args], capture_output=True, text=True, check=check) + + def _build(self): + (self.host / 'eng').mkdir(parents=True) + (self.host / 'RuneCLR.slnx').write_text('' + chr(10), encoding='utf-8') + (self.host / 'Directory.Build.props').write_text('' + chr(10), encoding='utf-8') + harness_dir = self.host / 'tests/RuneCLR.EpochDeadline.Tests/bin/Release/net11.0' + harness_dir.mkdir(parents=True) + (harness_dir / 'RuneCLR.EpochDeadline.Tests.dll').write_bytes(b'harness-fixture') + (self.host / 'src/RuneCLR.Runtime').mkdir(parents=True) + (self.host / 'src/RuneCLR.Runtime/MapSession.cs').write_text('// fixture source' + chr(10), encoding='utf-8') + (self.host / 'tests/RuneCLR.EpochDeadline.Tests/Program.cs').write_text('// fixture test' + chr(10), encoding='utf-8') + + self.build.mkdir(parents=True) + for name, payload in NATIVE.items(): + (self.build / name).write_bytes(payload) + corelib = b'corelib-fixture' + if self.il_fallback: + (self.build / 'IL').mkdir() + (self.build / 'IL/System.Private.CoreLib.dll').write_bytes(corelib) + else: + (self.build / 'System.Private.CoreLib.dll').write_bytes(corelib) + + shared = self.layout / 'shared/Microsoft.NETCore.App/12.0.0' + shared.mkdir(parents=True) + for name, payload in NATIVE.items(): + (shared / name).write_bytes(payload) + (shared / 'System.Private.CoreLib.dll').write_bytes(corelib) + (self.layout / 'dotnet.exe').write_bytes(b'dotnet-fixture') + + self.runtime.mkdir(parents=True, exist_ok=True) + self.git('init', '-q') + self.git('config', 'user.email', 'fixture@example.invalid') + self.git('config', 'user.name', 'fixture') + dirty = self.runtime / DIRTY_FILE + dirty.parent.mkdir(parents=True) + dirty.write_text('// baseline' + chr(10), encoding='utf-8') + self.git('add', '-A') + self.git('commit', '-q', '-m', 'fixture baseline') + if self.dirty: + dirty.write_text('// dirty' + chr(10), encoding='utf-8') + self.write_manifest() + + def head(self): + return self.git('rev-parse', 'HEAD').stdout.strip() + + def manifest(self): + files = {DIRTY_FILE: digest(self.runtime / DIRTY_FILE)} if self.dirty else {} + return {'head': self.head(), 'dirty_files': files} + + def write_manifest(self, extra_space=False): + text = json.dumps(self.manifest(), indent=2) + if extra_space: + text = text.replace('"', '" ', 1) + self.manifest_path.write_text(text + chr(10), encoding='utf-8') + + def argv(self, output): + return ['--host-root', str(self.host), '--layout', str(self.layout), + '--runtime-root', str(self.runtime), '--source-manifest', str(self.manifest_path), + '--output', str(output)] + + +def run_main(module, argv, on_harness=None, cwd=None): + """Drive the real main() with a fixture-only child-process stub for the harness.""" + + def stub(command, cwd=None, env=None, stdout=None, stderr=None, timeout=None, check=False): + if on_harness is not None: + on_harness() + if stdout is not None: + stdout.write(b'PASS fixture harness' + bytes([10])) + return types.SimpleNamespace(returncode=0, stdout='', stderr='') + + # Give the verifier module its own subprocess shim so the git helpers in this file keep + # using the real module (the verifier only uses run() for the harness child). + real_subprocess = module.subprocess + shim = types.SimpleNamespace(run=stub, check_output=real_subprocess.check_output, + check_call=real_subprocess.check_call, PIPE=real_subprocess.PIPE, + DEVNULL=real_subprocess.DEVNULL, STDOUT=real_subprocess.STDOUT, + CalledProcessError=real_subprocess.CalledProcessError) + + previous_argv = sys.argv + previous_cwd = Path.cwd() + sys.argv = ['verify-epoch-integration.py'] + list(argv) + module.subprocess = shim + if cwd is not None: + os.chdir(cwd) + text = io.StringIO() + try: + with contextlib.redirect_stdout(text): + module.main() + return True, '', text.getvalue() + except Exception as error: + return False, str(error), text.getvalue() + finally: + module.subprocess = real_subprocess + sys.argv = previous_argv + if cwd is not None: + os.chdir(previous_cwd) + + +def rejected(result, *keywords): + ok, error, _ = result + lowered = error.lower() + return (not ok) and any(keyword.lower() in lowered for keyword in keywords) + + +def case_positive_dirty(fixture, module): + output = fixture.base / 'out-positive' + ok, error, text = run_main(module, fixture.argv(output)) + if not ok: + return False, 'positive run rejected: ' + error + pins = json.loads((output / 'pins-before.json').read_text(encoding='utf-8')) + il = str(fixture.build / 'IL/System.Private.CoreLib.dll') + if il not in pins: + return False, 'accepted, but the produced IL CoreLib is not pinned (known gap)' + return True, 'dirty declared source accepted and the IL produced file is pinned' + + +def case_il_produced_drift(fixture, module): + output = fixture.base / 'out-il-drift' + il = fixture.build / 'IL/System.Private.CoreLib.dll' + + def drift(): + il.write_bytes(il.read_bytes() + b'!') + + result = run_main(module, fixture.argv(output), on_harness=drift) + if rejected(result, 'drift', 'changed during the run'): + return True, 'IL produced file change rejected as drift' + if result[0]: + return False, 'IL produced file changed during the run but the run was accepted (known gap)' + return False, 'rejected for an unexpected reason: ' + result[1] + + +def case_manifest_between_parse_and_pin(fixture, module): + output = fixture.base / 'out-manifest-pin' + real_digest = module.digest + state = {'done': False} + + def wrapped(path): + if not state['done'] and Path(path) == fixture.manifest_path: + state['done'] = True + fixture.write_manifest(extra_space=True) + return real_digest(path) + + module.digest = wrapped + try: + result = run_main(module, fixture.argv(output)) + finally: + module.digest = real_digest + if not state['done']: + return False, 'fixture did not reach the manifest pin' + if result[0]: + return False, 'manifest changed between parse and pin but the run was accepted (known gap)' + return True, 'manifest parse/pin mismatch rejected' + + +def case_manifest_during_run(fixture, module): + output = fixture.base / 'out-manifest-run' + result = run_main(module, fixture.argv(output), on_harness=lambda: fixture.write_manifest(extra_space=True)) + if rejected(result, 'drift', 'changed during the run'): + return True, 'manifest change during the run rejected as drift' + return False, ('accepted despite a manifest change during the run' if result[0] else 'rejected for an unexpected reason: ' + result[1]) + + +def case_consumed_copy(fixture, module): + output = fixture.base / 'out-consumed' + ok, error, _ = run_main(module, fixture.argv(output)) + if not ok: + return False, 'positive run rejected: ' + error + copies = [p for p in output.rglob('*') if p.is_file() and ('consumed' in p.name.lower() or 'copy' in p.name.lower())] + if not copies: + return None, 'verifier writes no consumed manifest copy, so copy drift cannot be exercised' + source = digest(fixture.manifest_path) + for copy in copies: + if digest(copy) != source: + return False, 'consumed copy does not match the manifest: ' + copy.name + return True, 'consumed copy matches the manifest bytes' + + +def case_runtime_head_drift(fixture, module): + output = fixture.base / 'out-head-drift' + + def drift(): + fixture.git('commit', '-q', '--allow-empty', '-m', 'fixture head drift') + + result = run_main(module, fixture.argv(output), on_harness=drift) + if result[0]: + return False, 'runtime HEAD changed during the run but the run was accepted (known gap)' + return True, 'runtime HEAD change rejected: ' + result[1] + + +def case_stdout_append(fixture, module): + output = fixture.base / 'out-stdout' + ok, error, _ = run_main(module, fixture.argv(output)) + if not ok: + return False, 'positive run rejected: ' + error + pins = json.loads((output / 'pins-before.json').read_text(encoding='utf-8')) + stdout_log = output / 'tests.stdout.log' + if str(stdout_log) in pins: + return False, 'the run stdout log is pinned as an input' + summary = json.loads((output / 'summary.json').read_text(encoding='utf-8')) + if summary.get('drift'): + return False, 'unexpected drift in a clean run: ' + repr(summary['drift']) + with stdout_log.open('ab') as stream: + stream.write(b'appended after the run' + bytes([10])) + if digest(fixture.manifest_path) != pins.get(str(fixture.manifest_path), digest(fixture.manifest_path)): + return False, 'manifest pin does not match the manifest' + return True, 'stdout is not pinned and appending after the run is harmless' + + +def case_positive_clean(fixture, module): + output = fixture.base / 'out-clean' + ok, error, _ = run_main(module, fixture.argv(output)) + if not ok: + return False, 'clean positive run rejected: ' + error + pins = json.loads((output / 'pins-before.json').read_text(encoding='utf-8')) + il = str(fixture.build / 'IL/System.Private.CoreLib.dll') + if il not in pins: + return False, 'accepted, but the produced IL CoreLib is not pinned' + summary = json.loads((output / 'summary.json').read_text(encoding='utf-8')) + if summary.get('drift'): + return False, 'unexpected drift in a clean run: ' + repr(summary['drift']) + return True, 'clean committed worktree accepted and the IL produced file is pinned' + + +def case_consumed_copy_corrupt(fixture, module): + output = fixture.base / 'out-consumed-corrupt' + copy = output / 'source-manifest.copy.json' + + def corrupt(): + if copy.is_file(): + copy.write_bytes(copy.read_bytes() + b'!') + + result = run_main(module, fixture.argv(output), on_harness=corrupt) + if rejected(result, 'consumed', 'copy drifted'): + return True, 'consumed copy corrupted during the run was rejected' + if result[0]: + return False, 'consumed copy corrupted during the run but the run was accepted' + return False, 'rejected for an unexpected reason: ' + result[1] + + +def case_runtime_status_drift(fixture, module): + output = fixture.base / 'out-status-drift' + + def drift(): + (fixture.runtime / 'src/RuneCLR.Runtime/Untracked.cs').write_text('// untracked' + chr(10), encoding='utf-8') + + result = run_main(module, fixture.argv(output), on_harness=drift) + if rejected(result, 'working tree drifted', 'status'): + return True, 'untracked source status drift during the run was rejected' + if result[0]: + return False, 'untracked source appeared during the run but the run was accepted' + return False, 'rejected for an unexpected reason: ' + result[1] + + +def case_relative_manifest(fixture, module): + output = fixture.base / 'out-relative' + argv = ['--host-root', str(fixture.host), '--layout', str(fixture.layout), + '--runtime-root', str(fixture.runtime), '--source-manifest', fixture.manifest_path.name, + '--output', str(output)] + ok, error, _ = run_main(module, argv, cwd=fixture.base) + if not ok: + return False, 'relative --source-manifest run rejected: ' + error + pins = json.loads((output / 'pins-before.json').read_text(encoding='utf-8')) + resolved = str(fixture.manifest_path.resolve()) + if resolved not in pins: + return False, 'the resolved manifest path is not pinned' + if pins[resolved] != digest(fixture.manifest_path): + return False, 'the pinned manifest hash differs from the manifest bytes' + return True, 'relative --source-manifest resolved and pinned under a deliberate cwd' + + +CASES = [ + ('positive-dirty-il-fallback', case_positive_dirty, {}), + ('positive-clean-commit', case_positive_clean, {'dirty': False}), + ('il-produced-drift', case_il_produced_drift, {}), + ('manifest-parse-pin-change', case_manifest_between_parse_and_pin, {}), + ('manifest-during-run', case_manifest_during_run, {}), + ('consumed-copy', case_consumed_copy, {}), + ('consumed-copy-corrupt', case_consumed_copy_corrupt, {}), + ('runtime-head-drift', case_runtime_head_drift, {}), + ('runtime-status-drift', case_runtime_status_drift, {}), + ('relative-source-manifest', case_relative_manifest, {}), + ('stdout-append', case_stdout_append, {}), +] + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--host-root', type=Path, default=Path(__file__).resolve().parents[1]) + parser.add_argument('--keep', action='store_true', help='keep the fixture directories') + parser.add_argument('--workdir', type=Path, default=None) + args = parser.parse_args() + + module, verifier_sha = load_verifier(args.host_root) + print('VERIFIER ' + str((Path(args.host_root) / 'eng/verify-epoch-integration.py').resolve()) + ' sha256=' + verifier_sha) + + base = Path(args.workdir) if args.workdir else Path(tempfile.mkdtemp(prefix='epoch-provenance-')) + base.mkdir(parents=True, exist_ok=True) + failures = 0 + skipped = 0 + try: + for name, case, fixture_options in CASES: + fixture_root = base / name + fixture_root.mkdir(parents=True, exist_ok=True) + fixture = Fixture(fixture_root, **fixture_options) + try: + outcome, detail = case(fixture, module) + except Exception as error: + outcome, detail = False, 'fixture error: ' + type(error).__name__ + ': ' + str(error) + if outcome is None: + skipped += 1 + print('SKIP ' + name + ' :: ' + detail) + elif outcome: + print('PASS ' + name + ' :: ' + detail) + else: + failures += 1 + print('FAIL ' + name + ' :: ' + detail) + finally: + if not args.keep and args.workdir is None: + shutil.rmtree(base, ignore_errors=True) + else: + print('WORKDIR ' + str(base)) + print('EPOCH_PROVENANCE_TESTS passed=' + str(len(CASES) - failures - skipped) + + ' skipped=' + str(skipped) + ' failed=' + str(failures) + ' verifier=' + verifier_sha[:12]) + return 0 if failures == 0 else 1 + + +if __name__ == '__main__': sys.exit(main()) \ No newline at end of file diff --git a/eng/verify-epoch-integration.py b/eng/verify-epoch-integration.py index dc1ece1..9acfb22 100644 --- a/eng/verify-epoch-integration.py +++ b/eng/verify-epoch-integration.py @@ -91,7 +91,7 @@ def main(): harness = root / "tests/RuneCLR.EpochDeadline.Tests/bin/Release/net11.0/RuneCLR.EpochDeadline.Tests.dll" inputs = {harness, Path(__file__).resolve(), root / "RuneCLR.slnx", root / "Directory.Build.props", - args.source_manifest} + source_manifest} inputs.update(path for path in harness.parent.rglob("*") if path.is_file()) for folder in (root / "src", root / "tests"): inputs.update(path for path in folder.rglob("*") if path.is_file() From eff89922008d6b93197c522a4dfd8b570d288f57 Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Thu, 12 Nov 2026 20:16:08 +0800 Subject: [PATCH 11/15] Record lifecycle runs on the matching patched runtime Record separate ordinary and RequireInterpreter lifecycle passes on the matching private runtime, with unchanged binary identities. Documentation only; no build or epoch performance claim. Assisted-by: Cindy (https://cindy.app) --- .../optional-epoch-deadline-integration-20261112.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/experiments/optional-epoch-deadline-integration-20261112.md b/docs/experiments/optional-epoch-deadline-integration-20261112.md index 7b2cc5f..9cea905 100644 --- a/docs/experiments/optional-epoch-deadline-integration-20261112.md +++ b/docs/experiments/optional-epoch-deadline-integration-20261112.md @@ -37,6 +37,12 @@ The archive branch keeps its original bytes and is untouched. - Stock desktop build `dotnet build RuneCLR.slnx -c Release`: 0 warnings, 0 errors. - Stock regression `tests/RuneCLR.Runtime.Tests`: 156/156 passed. +- The same lifecycle harness on the matching private Release runtime: **156/156** in ordinary + mode and **156/156** with explicit `--require-interpreter`, in separate processes. These runs + use the unchanged host binaries containing the reporting fix `2387d81`; all five runtime + hashes match the frozen set below and the source stays clean at `7f5a0bc8`. Launch receipts, + logs and binary identities are recorded under `lead-patched-lifecycle/` in the integration + artifact. These are additional lifecycle regressions, separate from stock and deadline tests. - Epoch suite against the matching private runtime: **24 passed / 0 skipped / 0 failed** (host commits 17a41fb and the P3 reporting fix 2387d81). - `eng/verify-epoch-integration.py`: PASS with 658 pinned inputs and a 520-file private layout From 3de2e08158dcdee279e5968685fbf7a7388a77eb Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:49:59 +0800 Subject: [PATCH 12/15] Document the final epoch runtime and measured scope Point the epoch experiment at the published runtime branch and the delivered 08e031af/e637 code, record the final host join (24/24 epoch, 659 pins, 521-file layout, 156/156 lifecycle twice) and the four focused upstream tests on that exact Release binary, and keep the earlier 7f5a0bc8 numbers as history. Replace the pending-performance paragraph with the measured scope: default OFF 1.03/1.11/0.97 in the final three-round window, epoch ON about 3.4-5.3x of its own OFF, and the three-round cross-module lane reported as minimum-of-minima plus the normalised medians. The 2x budget tolerance is granularity, not a CPU gate. The host already configures before the first author file and rejects late activation; no host API or source changes are made here. Assisted-by: Cindy (https://cindy.app) --- docs/development.md | 13 ++ ...nal-epoch-deadline-integration-20261112.md | 130 +++++++++++------- 2 files changed, 97 insertions(+), 46 deletions(-) diff --git a/docs/development.md b/docs/development.md index 0950253..333b8a1 100644 --- a/docs/development.md +++ b/docs/development.md @@ -20,6 +20,19 @@ callback-epoch stacks are not part of it. Its Windows x64 build/test evidence does not establish iOS or device behavior - the accepted iPad results stay with their own recorded pins. +## Optional callback deadline (2026-11-12) + +The [callback-epoch increment](experiments/optional-epoch-deadline-integration-20261112.md) pairs +the opt-in epoch callback deadline with the runtime publication branch +`runeclr/optional-callback-epoch-integration-final-20261112` (tested code `e637bd79`, parent +`runeclr/dev` `474eb8ad`). The final host join on that delivery passes the epoch suite 24/24, the +verifier with 659 pins and zero drift, and the lifecycle harness 156/156 both ordinary and with +`--require-interpreter`; four focused upstream tests pass on the exact Release binary. It stays +private and opt-in: the clock path is the default, configuration must happen before a context's +first execution, and late activation is rejected. The limits are recorded there: Windows x64 +Release only, no device/AOT/Linux/Wasm or JIT/R2R instrumentation, a fail-closed budget rather than +a sandbox, and a host-owned ticker. + ## Physical iPad device R2R experiment (2026-11-10) The [iPad device R2R experiment](ios-device-r2r-experiment.md) records the first diff --git a/docs/experiments/optional-epoch-deadline-integration-20261112.md b/docs/experiments/optional-epoch-deadline-integration-20261112.md index 9cea905..ef26992 100644 --- a/docs/experiments/optional-epoch-deadline-integration-20261112.md +++ b/docs/experiments/optional-epoch-deadline-integration-20261112.md @@ -1,9 +1,10 @@ # Optional epoch callback deadline — host integration (2026-11-12) -This branch integrates the reviewed 2026-11-10 epoch callback-deadline experiment onto the -current RuneCLR `origin/main` (cbac2a657793dca7f22b1e1feff4aab26b898b4e) and pairs it with the -matching native runtime branch `runeclr/optional-callback-epoch-integration-20261112` -(commit 7f5a0bc8c6d58a46d2dff91571cad04b2b3a9416, parent `runeclr/dev` 474eb8ad). +This branch integrates the reviewed epoch callback-deadline experiment onto the current RuneCLR +`origin/main` (cbac2a657793dca7f22b1e1feff4aab26b898b4e) and pairs it with the native runtime +publication branch `runeclr/optional-callback-epoch-integration-final-20261112` (tested code +commit e637bd791bd824b3a8118fca47073f6390bcb52a, parent `runeclr/dev` 474eb8ad). The earlier +local 7f5a0bc8 snapshot and its numbers are kept only as history. ## What is integrated @@ -12,6 +13,9 @@ matching native runtime branch `runeclr/optional-callback-epoch-integration-2026 - `CallbackDeadlineBridge` gains the additive epoch factory, tick/read delegates and the capability check; `MapSession` leases the ticker before any author file is opened and releases it after the author stack has returned. +- Configuration happens on a fresh interpreter-required context before any author file is opened; + a context that already executed is rejected (configure-before-first-execution), with no + additional host API surface. - Epoch tests and the verifier under `eng/verify-epoch-integration.py`. The clock path is unchanged and remains the default. @@ -37,21 +41,21 @@ The archive branch keeps its original bytes and is untouched. - Stock desktop build `dotnet build RuneCLR.slnx -c Release`: 0 warnings, 0 errors. - Stock regression `tests/RuneCLR.Runtime.Tests`: 156/156 passed. -- The same lifecycle harness on the matching private Release runtime: **156/156** in ordinary - mode and **156/156** with explicit `--require-interpreter`, in separate processes. These runs - use the unchanged host binaries containing the reporting fix `2387d81`; all five runtime - hashes match the frozen set below and the source stays clean at `7f5a0bc8`. Launch receipts, - logs and binary identities are recorded under `lead-patched-lifecycle/` in the integration - artifact. These are additional lifecycle regressions, separate from stock and deadline tests. -- Epoch suite against the matching private runtime: **24 passed / 0 skipped / 0 failed** - (host commits 17a41fb and the P3 reporting fix 2387d81). -- `eng/verify-epoch-integration.py`: PASS with 658 pinned inputs and a 520-file private layout - (verifier commit 0f2f135; run evidence `run13`). The same runtime layout was re-run as `run14` - on the fixture landing: 24 passed / 0 skipped / 0 failed, the same 658 pins and 520 files. The - later one-line relative-manifest pin fix does not change absolute-path runs. - -Historical figures are kept separate: the earlier stock-runtime run was 5 passed / 19 skipped -because no matching runtime was present, and the 2026-11-10 campaign numbers came from the +- Final host join against the delivered epoch runtime (coreclr `08e031af…`, CoreLib `30020d07…`, + clrinterpreter `f4d5ea48…`, corerun `09017fa3…`, clrjit `4b15f3ae…`; source `e637bd79…`): + the epoch suite passes **24 passed / 0 skipped / 0 failed**, and + `eng/verify-epoch-integration.py` passes with **659 pinned inputs**, a **521-file** private + layout and zero drift. +- The same layout and unchanged host binaries run the lifecycle harness **156/156** in ordinary + mode and **156/156** with explicit `--require-interpreter`, in separate processes (host commits + 17a41fb and the reporting fix 2387d81 are in this branch's history). +- Focused upstream compatibility on that exact Release runtime: four official tests pass + (Expected 100 / Actual 100, exit 0). +- `eng/test-epoch-integration-provenance.py`: **11 passed / 0 skipped / 0 failed** (see below). + +Historical figures are kept separate: the earlier 7f5a0bc8 snapshot ran the epoch suite 24/24 +with 658 pins and a 520-file layout (run13/run14); the stock-runtime run was 5 passed / 19 skipped +because no matching runtime was present; and the 2026-11-10 campaign numbers came from the archived binaries. Those are history, not the current result. ## Tooling regressions @@ -79,13 +83,13 @@ line; absolute paths pin exactly the same set as before. ## Focused upstream regression on the frozen runtime -A private flat Core_Root was assembled from the frozen Release layout without modifying any -layout, binary, host branch or SDK. Four official tests each reported **Expected 100 / Actual 100, -exit 0**: `ContextualReflection`, `CollectibleStatics`, `GenericVirtualMethod` and -`InterpreterTester`. The five Core_Root binaries were identical before and after the runs: coreclr -`ed76bfa6…`, clrjit `23e3411d…`, clrinterpreter `905bb9bb…`, corerun `24ffba3e…`, -System.Private.CoreLib `6f181812…` (under IL/). The test assemblies came from the official -474-based test source and were not recompiled for these runs. +The final run composes a private flat Core_Root from the delivered layout (519 shared-framework +files plus ten official xunit runner files, 529 files total) without modifying any layout, binary, +host branch or SDK. Four official tests each reported **Expected 100 / Actual 100, exit 0**: +`ContextualReflection`, `CollectibleStatics`, `GenericVirtualMethod` and `InterpreterTester`. The +five runtime binaries were identical before and after the runs: coreclr `08e031af…`, clrjit +`4b15f3ae…`, clrinterpreter `f4d5ea48…`, corerun `09017fa3…`, System.Private.CoreLib `30020d07…`. +The test assemblies are the official Checked build from the 474-based test source, reused unchanged. `InterpreterTester` is the official wrapper and sets `DOTNET_Interpreter=RunInterpreterTests` internally. That runner configuration alone is not an independent per-method interpreted-mode @@ -94,9 +98,15 @@ produced no method lines in this build. The pass is therefore compatibility evid documented configuration, not proof of interpreted method entry, and it is not an epoch timing or overhead measurement. +The earlier `ed76bfa6` run on the 7f5a0bc8 snapshot is historical and is not reused for this +candidate; the current evidence is the exact delivered `08e031af` Release binary above. + ## Runtime expectation (paired branch) -Matching runtime must provide, on `System.Runtime.Loader.AssemblyLoadContext`: +Matching runtime must provide, on `System.Runtime.Loader.AssemblyLoadContext`. The published +implementation and its limits are in +[the runtime callback-epoch document](https://github.com/ReneeGA2020/runtime/blob/runeclr/optional-callback-epoch-integration-final-20261112/docs/runeclr-callback-epoch.md); +the tested code pin is `e637bd79…` and the publication branch adds documentation only: - `RuneCLR_GetCallbackDeadlineVersion() -> long` returning 1 (existing clock ABI); - `RuneCLR_GetCallbackDeadlineCapabilities() -> int`: **bit0 (0x1) is the clock ABI and bit1 (0x2) @@ -107,29 +117,57 @@ Matching runtime must provide, on `System.Runtime.Loader.AssemblyLoadContext`: ## Provenance -- Paired native: fork branch `runeclr/optional-callback-epoch-integration-20261112` at 7f5a0bc8, - parent `runeclr/dev` 474eb8ad; frozen binaries used for the run: coreclr `ed76bfa6…`, CoreLib - `6f181812…` (under IL/), clrinterpreter `905bb9bb…`, corerun `24ffba3e…`, clrjit `23e3411d…`. -- The verifier's source manifest `{head 7f5a0bc8, files {}}` records the CURRENT clean Git identity - of that worktree. It does not prove the binaries were compiled from that clean tree: the build - record is base 474eb8ad plus a 14-file delta with its own raw source hashes. +- Paired native publication branch: `runeclr/optional-callback-epoch-integration-final-20261112` + in `ReneeGA2020/runtime`, tested code `e637bd79…`, parent `runeclr/dev` `474eb8ad`. Delivery + identity for the measured run: coreclr `08e031af…`, CoreLib `30020d07…`, clrinterpreter + `f4d5ea48…`, corerun `09017fa3…`, clrjit `4b15f3ae…`; the delivery manifest and per-file hashes + ship with the evidence. +- The source is the clean `e637` worktree (manifest `{head e637bd79, files {}}`). The inspected + Release build log stamps `1ac56d5` because that build predates `e637`; `e637` changes only + preprocessor guards and comments with 0 differing active Release lines, and its Windows + Debug/Checked compile is separate. The documentation commit on the publication branch is not a + new build. +- The earlier 7f5a0bc8 frozen set (coreclr `ed76bfa6…`, CoreLib `6f181812…`, clrinterpreter + `905bb9bb…`, corerun `24ffba3e…`, clrjit `23e3411d…`) and its run13/run14 numbers are + historical. ## Limits - One active callback per session and a single owner thread; a competing callback or thread fails closed with reason 4. -- Windows x64 Release interpreter only. No device, AOT, unmanaged-entry or global all-load evidence. +- Windows x64 Release interpreter only. No Linux, Wasm, device, AOT, unmanaged-entry, global + all-load or JIT/R2R instrumentation evidence; the Debug configuration is proven to compile, not + to execute this backend. - Native blocking cannot be interrupted, including a `Sleep` inside a finally block; finalizers run - outside the deadline. This is not a sandbox. + outside the deadline. This is a fail-closed budget, not a sandbox. +- The minimal epoch runtime has no instruction quota or terminal bridge; the both-feature case is + only validated at its pre-author missing-capability check. +- The host must keep the ticker alive and dispose it from an ordinary thread; the trusted tick/read + calls are assumed non-blocking and the final join has no timeout. - `InstallTestTimerFault` is an internal test hook compiled into the experiment assembly, not a - product API. `Stop`/`Dispose` must be called from an ordinary host thread, never from the ticker - path; the trusted tick/read calls are assumed non-blocking and the final join has no timeout. -- The both-feature case is not validated natively: the minimal epoch runtime has no - instruction-terminal API, so only the pre-author missing-capability path is covered. - -## Performance - -Unresolved. The 5.33x (poll interval 1) and 3.18x (poll interval 100) figures are a historical -microbenchmark scope (arithmetic lane versus the unconfigured interpreter), not a CPU gate and not -an acceptance for the roughly 2x budget tolerance. Conflicting measurements across runtime builds -mean a dedicated matched audit is still pending; no default-OFF cost conclusion is drawn here. + product API. + +## Performance (measured scope, not a CPU gate) + +All figures are one machine, Windows x64 Release interpreter, one driver image, 7 timed samples per +round and no CPU pinning; they are medians in milliseconds unless stated. + +- Default OFF (patched but unconfigured) versus the unpatched `474eb8ad` runtime, final three-round + confirmation: **1.03 / 1.11 / 0.97** for TightLoop / CallBoundary / BusinessLoop. An earlier + six-round window on the `1ac` revision measured 0.96 / 1.04 / 0.95; that window is history. The + arithmetic lanes return to baseline and the call lane recovers to about 1.04-1.11x, so no + universal "zero overhead" or speedup claim is made. +- Epoch ON against the same build's OFF lanes in three micro lanes at intervals 1 / 100 / 1000: + about **3.4x to 5.3x**. The 2x budget tolerance is a granularity choice, not a CPU acceptance + threshold; these ratios are workload-specific. +- Cross-module delegate calls (300k calls per sample, callee in a second interpreter-required ALC) + were measured with a corrected artifact-only driver (`a49635576a84…`) in three interleaved rounds + only. The native headline used the **minimum of the three round minima: 13.9 ms cross-module + versus 13.9 ms baseline**. The lead-normalised receipt over the same logs gives baseline 14.6 vs + final 14.3 ms as the median of per-round min-of-7 values, and 16.8 vs 14.6 ms as the median of + the sample medians. The minimum is not a median, and none of these figures is a noiseless + speedup claim. +- The first cross-module attempt failed with a driver NullReferenceException (the artifact driver + lacked a helper that only the native test assembly had); only the driver was fixed + (`a49635576a84…`). Runtime source, HEAD and the delivery were untouched, and the blocked attempt + is not counted as a measurement. From 5b45565c8e83762c3530e947069b70967d86b2b0 Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:06:19 +0800 Subject: [PATCH 13/15] Clarify validated build configurations and deadline performance Distinguish the measured Debug compile from source-only Checked selection, state the observed OFF and ON costs, and preserve the exact tested-code build relation. Documentation only; validated product sources are unchanged. Assisted-by: Cindy (https://cindy.app) --- .../optional-epoch-deadline-integration-20261112.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/experiments/optional-epoch-deadline-integration-20261112.md b/docs/experiments/optional-epoch-deadline-integration-20261112.md index ef26992..c08dea9 100644 --- a/docs/experiments/optional-epoch-deadline-integration-20261112.md +++ b/docs/experiments/optional-epoch-deadline-integration-20261112.md @@ -118,14 +118,15 @@ the tested code pin is `e637bd79…` and the publication branch adds documentati ## Provenance - Paired native publication branch: `runeclr/optional-callback-epoch-integration-final-20261112` - in `ReneeGA2020/runtime`, tested code `e637bd79…`, parent `runeclr/dev` `474eb8ad`. Delivery + in `ReneeGA2020/runtime`, tested code `e637bd79…`, base `runeclr/dev` `474eb8ad`. Delivery identity for the measured run: coreclr `08e031af…`, CoreLib `30020d07…`, clrinterpreter `f4d5ea48…`, corerun `09017fa3…`, clrjit `4b15f3ae…`; the delivery manifest and per-file hashes ship with the evidence. - The source is the clean `e637` worktree (manifest `{head e637bd79, files {}}`). The inspected - Release build log stamps `1ac56d5` because that build predates `e637`; `e637` changes only - preprocessor guards and comments with 0 differing active Release lines, and its Windows - Debug/Checked compile is separate. The documentation commit on the publication branch is not a + Release build log stamps `1ac56d5` because that build predates `e637`; `e637` consolidates + preprocessor guards and updates comments and the test fixture, with 0 differing active Windows + Release interpreter implementation lines. Its Windows Debug compile is separate; Checked backend + selection has source proof only. The documentation commit on the publication branch is not a new build. - The earlier 7f5a0bc8 frozen set (coreclr `ed76bfa6…`, CoreLib `6f181812…`, clrinterpreter `905bb9bb…`, corerun `24ffba3e…`, clrjit `23e3411d…`) and its run13/run14 numbers are From 5b7fbd4ca2f50f6b8cd8e59da216c38b663e2d41 Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:29:04 +0800 Subject: [PATCH 14/15] Document the process-fatal author finalizer limitation Record the isolated-lane result for budgeted contexts: an author finalizer after End on a configured CLOCK context is denied at its first checkpoint, raises an unhandled OperationCanceledException and terminates the process on both the frozen 7f and final 08 runtimes; the unconfigured control completes normally. Add the host guidance and the handoff note; this is a pre-existing limitation, not cleanup or recovery. Assisted-by: Cindy (https://cindy.app) --- docs/development.md | 8 +++--- ...nal-epoch-deadline-integration-20261112.md | 27 +++++++++++++++++-- 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/docs/development.md b/docs/development.md index 333b8a1..4f498d0 100644 --- a/docs/development.md +++ b/docs/development.md @@ -29,9 +29,11 @@ the opt-in epoch callback deadline with the runtime publication branch verifier with 659 pins and zero drift, and the lifecycle harness 156/156 both ordinary and with `--require-interpreter`; four focused upstream tests pass on the exact Release binary. It stays private and opt-in: the clock path is the default, configuration must happen before a context's -first execution, and late activation is rejected. The limits are recorded there: Windows x64 -Release only, no device/AOT/Linux/Wasm or JIT/R2R instrumentation, a fail-closed budget rather than -a sandbox, and a host-owned ticker. +first execution, and late activation is rejected. Author finalizers are not safe in a budgeted +context: an isolated lane showed a post-`End` finalizer terminating the process on both the frozen +7f and final 08 runtimes, so no pending author finalizer may remain in a budgeted context. The +limits are recorded there: Windows x64 Release only, no device/AOT/Linux/Wasm or JIT/R2R +instrumentation, a fail-closed budget rather than a sandbox, and a host-owned ticker. ## Physical iPad device R2R experiment (2026-11-10) diff --git a/docs/experiments/optional-epoch-deadline-integration-20261112.md b/docs/experiments/optional-epoch-deadline-integration-20261112.md index c08dea9..b941507 100644 --- a/docs/experiments/optional-epoch-deadline-integration-20261112.md +++ b/docs/experiments/optional-epoch-deadline-integration-20261112.md @@ -132,6 +132,28 @@ the tested code pin is `e637bd79…` and the publication branch adds documentati `905bb9bb…`, corerun `24ffba3e…`, clrjit `23e3411d…`) and its run13/run14 numbers are historical. +## Author finalizer limitation (process-fatal) + +An isolated artifact lane tested a configured CLOCK context (60 s budget, poll interval 1, cleanup +budget 1000): an author object allocated inside `Begin`/`End` was kept alive through `End` and +released afterwards. Its finalizer ran on the finalizer thread outside any active callback, was +denied at its first interpreter checkpoint, and the resulting unhandled +`System.OperationCanceledException` terminated the process (exit 0xE0434352). The finalizer wrote +no marker at all; the same lane fails identically on the frozen 7f runtime, while the same payload +without a deadline runs both finalizer markers and exits 0. + +This is not successful cleanup or recovery. The empty marker shows the failure happened before the +finalizer's first observable instruction; the first-checkpoint/owner-active explanation is source +reasoning, not a dynamically traced opcode. The lane did not test a finalizer inside an active +callback, did not test epoch mode, and does not show that every finalizer is blocked. It is a +pre-existing limitation, not a regression of this host integration. + +Guidance: do not keep pending author finalizers in a budgeted context. Explicit disposal alone does +not prevent finalization; a type that relies on cleanup must either release its resources inside the +active callback with no pending finalizer, or suppress finalization correctly as part of its +disposal design. Generic `Dispose`/`using` and unloading the context are not guaranteed to avoid +this failure. The prototype cannot safely recover from this ordinary author mistake. + ## Limits - One active callback per session and a single owner thread; a competing callback or thread fails @@ -139,8 +161,9 @@ the tested code pin is `e637bd79…` and the publication branch adds documentati - Windows x64 Release interpreter only. No Linux, Wasm, device, AOT, unmanaged-entry, global all-load or JIT/R2R instrumentation evidence; the Debug configuration is proven to compile, not to execute this backend. -- Native blocking cannot be interrupted, including a `Sleep` inside a finally block; finalizers run - outside the deadline. This is a fail-closed budget, not a sandbox. +- Native blocking cannot be interrupted, including a `Sleep` inside a finally block. Author + finalizers in a budgeted context are process-fatal (see above); this is a fail-closed budget, not + a sandbox. - The minimal epoch runtime has no instruction quota or terminal bridge; the both-feature case is only validated at its pre-author missing-capability check. - The host must keep the ticker alive and dispose it from an ordinary thread; the trusted tick/read From cc1992adff6dd911244c03bf8b698070365999f3 Mon Sep 17 00:00:00 2001 From: lulan <49630018+ReneeGA2020@users.noreply.github.com> Date: Fri, 13 Nov 2026 01:12:55 +0800 Subject: [PATCH 15/15] Accept a combined clean-commit runtime comparison and record combined evidence eng/verify-runtime-session-origin.py inherited the published reflection base 7cbdad39, so the combined session-origin and callback-deadline runtime delta looked like hundreds of unrelated files. Add an explicit clean-commit mode: --runtime-base names a full ancestor commit while the default keeps the published base, and each repeatable --additional-allowed-path must be an exact tracked docs/.md path that is part of the delta. Unlisted, non-document, wildcard, untracked and unchanged paths are rejected, every changed source and allowed document stays pinned, and the same base, allowlist and expected HEAD are revalidated after the run. The new flags are refused in the committed-source and source-manifest modes. eng/test-session-origin-provenance.py covers the accepted combined shape and the rejected ones, plus worktree drift after acceptance and the CLI refusal; 43 cases pass. The combined host/runtime run at 474eb8ad..fed410bb passes the session-origin matrix 16/16 modes with 710 pinned inputs and zero drift on a private layout built from the combined Release delivery. The callback-epoch increment and the development handoff record that combined acceptance, the tooling mode and the earlier published-base cause. Assisted-by: Cindy (https://cindy.app) --- docs/development.md | 14 ++ ...nal-epoch-deadline-integration-20261112.md | 35 ++++ eng/test-session-origin-provenance.py | 174 ++++++++++++++++++ eng/verify-runtime-session-origin.py | 70 ++++++- 4 files changed, 284 insertions(+), 9 deletions(-) diff --git a/docs/development.md b/docs/development.md index 80f2adb..c2988bb 100644 --- a/docs/development.md +++ b/docs/development.md @@ -45,6 +45,20 @@ contract and limits are in The runtime `RuneCLR.EnableReflectionPolicyOriginScan` switch defaults to disabled, so a host that does not opt in keeps the existing reflection-policy behavior. +## Combined opt-in acceptance (2026-11-13) + +The epoch callback-deadline host branch merges `origin/main` `aa31875` (the merged session-origin +host PR) and is accepted together with both opt-ins on runtime +`runeclr/optional-callback-epoch-integration-final-20261112` `fed410bbe368b465b6628338a6fc04d6c38a4f2e` +(parent merge `234c0b7a…` over `runeclr/dev` `474eb8ad…`). On one private layout composed from that +`windows.x64.Release` delivery the epoch suite passes 24/24, the epoch verifier 669 pins with zero +drift, the session-origin fixed matrix 16/16 modes with 710 pins and zero drift, and the lifecycle +harness 156/156 both ordinary and with `--require-interpreter`. Both switches stay off by default and +the documented limits are unchanged; the +[callback-epoch increment](experiments/optional-epoch-deadline-integration-20261112.md) records the +combined evidence, the allowed-document provenance mode of `eng/verify-runtime-session-origin.py`, +and the earlier published-base comparison that blocked the first attempt. + ## Physical iPad device R2R experiment (2026-11-10) The [iPad device R2R experiment](ios-device-r2r-experiment.md) records the first diff --git a/docs/experiments/optional-epoch-deadline-integration-20261112.md b/docs/experiments/optional-epoch-deadline-integration-20261112.md index b941507..b914af2 100644 --- a/docs/experiments/optional-epoch-deadline-integration-20261112.md +++ b/docs/experiments/optional-epoch-deadline-integration-20261112.md @@ -195,3 +195,38 @@ round and no CPU pinning; they are medians in milliseconds unless stated. lacked a helper that only the native test assembly had); only the driver was fixed (`a49635576a84…`). Runtime source, HEAD and the delivery were untouched, and the blocked attempt is not counted as a measurement. + +## Combined host/runtime acceptance (2026-11-13) + +The host branch merges `origin/main` `aa31875` (the merged session-origin host PR) into this work, +and both opt-ins are now accepted together on one runtime: the publication branch +`runeclr/optional-callback-epoch-integration-final-20261112` at +`fed410bbe368b465b6628338a6fc04d6c38a4f2e` (parent merge `234c0b7a…` over `runeclr/dev` +`474eb8ad…`), built as a `windows.x64.Release` delivery. The private host layout is composed from +that delivery (coreclr `48289d63…`, clrinterpreter `6b861fc7…`, clrjit `197834f4…`, corerun +`30a8dd9a…`, CoreLib `e9a94ae0…`) with bootstrap hosting components only; no installed runtime is +replaced. + +- Epoch suite **24 passed / 0 skipped / 0 failed**, and `eng/verify-epoch-integration.py` passes with + **669 pinned inputs**, a **523-file** private layout and zero drift. +- Session-origin fixed matrix **16/16 modes** at `--runtime-base 474eb8ad…` `--runtime-commit + fed410b…`, with **710 pinned inputs**, zero drift, and the five hashes above. The delta over the + base is 15 files under `src/` plus the two canonical documents `docs/runeclr-dev.md` and + `docs/runeclr-callback-epoch.md`. +- Lifecycle harness **156/156** ordinary and **156/156** with `--require-interpreter`. + +Both opt-ins stay off by default (`MapDeadlineMode.Clock`, +`RuneCLR.EnableReflectionPolicyOriginScan=false`) and the configuration contract is unchanged: +configuration must happen on a fresh interpreter-required context before the first execution. +Existing limits carry over unchanged: Windows x64 Release interpreter only, no device / AOT / Linux / +Wasm or JIT/R2R instrumentation claims, a fail-closed budget rather than a sandbox, and author +finalizers unsafe in a budgeted context. + +`eng/verify-runtime-session-origin.py` gained an explicit clean-commit mode for this comparison: +`--runtime-base` names a full ancestor commit while the default stays the published base, and each +repeatable `--additional-allowed-path` must be an exact tracked `docs/.md` path that is part of +the delta. Unlisted, non-document, wildcard, untracked and unchanged paths are rejected, every +changed source and allowed document stays pinned, and the same base, allowlist and expected HEAD are +revalidated after the run. The earlier blocked attempt is explained by the tool inheriting the +published reflection base `7cbdad39…`, which made the combined delta look like hundreds of unrelated +files; `eng/test-session-origin-provenance.py` now covers the accepted and rejected shapes. diff --git a/eng/test-session-origin-provenance.py b/eng/test-session-origin-provenance.py index 28da02b..04448dc 100644 --- a/eng/test-session-origin-provenance.py +++ b/eng/test-session-origin-provenance.py @@ -242,6 +242,178 @@ def accept_shape(): return failures +def clean_commit_fixture(base, name="clean"): + """Synthetic runtime-shaped repository: source delta plus two tracked docs.""" + repo = base / name + repo.mkdir() + run(repo, "init", "-q", "-b", "main") + for relative, content in (("src/coreclr/vm/f1.cpp", "base-1"), + ("src/coreclr/vm/f2.cpp", "base-2"), + ("docs/runeclr-dev.md", "base doc"), + ("docs/stable.md", "stable doc"), + ("a.txt", "stable")): + path = repo / relative + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(content + NL, encoding="utf-8") + run(repo, "add", "-A") + commit(repo, "base") + base_commit = run(repo, "rev-parse", "HEAD") + (repo / "src/coreclr/vm/f1.cpp").write_text("changed-1" + NL, encoding="utf-8") + (repo / "src/coreclr/vm/f3.cpp").write_text("added-3" + NL, encoding="utf-8") + (repo / "docs/runeclr-dev.md").write_text("changed doc" + NL, encoding="utf-8") + (repo / "docs/runeclr-callback-epoch.md").write_text("new doc" + NL, encoding="utf-8") + run(repo, "add", "-A") + commit(repo, "integration") + return repo, base_commit, run(repo, "rev-parse", "HEAD") + + +def clean_commit_cases(base, driver): + """Explicit --runtime-base/--additional-allowed-path behaviour in clean-commit mode.""" + failures = [] + repo, base_commit, head = clean_commit_fixture(base) + docs = ("docs/runeclr-dev.md", "docs/runeclr-callback-epoch.md") + original_base = driver.RUNTIME_BASE + driver.RUNTIME_BASE = base_commit + try: + def accept_combined(): + observed_head, changed = driver.verify_runtime_provenance( + repo, head, base=base_commit, allowed_paths=docs) + if observed_head != head: + raise ValueError("unexpected head " + observed_head) + if len(changed) != 4: + raise ValueError("expected four changed paths, got " + repr(changed)) + if not any(path.startswith("src/") for path in changed): + raise ValueError("combined delta lost its source files") + if sorted(path for path in changed if not path.startswith("src/")) != sorted(docs): + raise ValueError("combined delta lost its allowed docs") + + failures.append(expect_accept("clean-commit explicit base with exactly the two canonical docs", + accept_combined)) + + failures.append(expect_reject( + "clean-commit default comparison still rejects docs", + lambda: driver.verify_runtime_provenance(repo, head), + "outside src/")) + + failures.append(expect_reject( + "clean-commit explicit base without the allowlist rejects docs", + lambda: driver.verify_runtime_provenance(repo, head, base=base_commit), + "outside src/")) + + failures.append(expect_reject( + "clean-commit unlisted doc", + lambda: driver.verify_runtime_provenance(repo, head, base=base_commit, allowed_paths=docs[:1]), + "outside src/")) + + for label, allowed_path in (("source file", "src/coreclr/vm/f1.cpp"), + ("wildcard", "docs/*.md"), + ("directory", "docs"), + ("missing doc", "docs/missing.md"), + ("unchanged doc", "docs/stable.md")): + failures.append(expect_reject( + "clean-commit allowed path " + label, + lambda allowed_path=allowed_path: driver.verify_runtime_provenance( + repo, head, base=base_commit, allowed_paths=(allowed_path,)), + "additional allowed path")) + + failures.append(expect_reject( + "clean-commit short base", + lambda: driver.verify_runtime_provenance(repo, head, base="474eb8a"), + "full 40-character commit id")) + + failures.append(expect_reject( + "clean-commit unknown base", + lambda: driver.verify_runtime_provenance(repo, head, base="f" * 40), + "is not a commit in the runtime repository")) + + tree = run(repo, "rev-parse", base_commit + "^{tree}") + unrelated = run(repo, "commit-tree", tree, "-m", "unrelated root") + failures.append(expect_reject( + "clean-commit non-ancestor base", + lambda: driver.verify_runtime_provenance(repo, head, base=unrelated), + "is not descended from base")) + + failures.append(expect_reject( + "clean-commit wrong expected head", + lambda: driver.verify_runtime_provenance(repo, "0" * 40, base=base_commit), + "Runtime HEAD must be")) + + (repo / "docs/runeclr-dev.md").write_text("drifted doc" + NL, encoding="utf-8") + failures.append(expect_reject( + "clean-commit allowed doc drift after acceptance", + lambda: driver.verify_runtime_provenance(repo, head, base=base_commit, allowed_paths=docs), + "must be clean")) + (repo / "docs/runeclr-dev.md").write_text("changed doc" + NL, encoding="utf-8") + + (repo / "src/coreclr/vm/f1.cpp").write_text("drifted source" + NL, encoding="utf-8") + failures.append(expect_reject( + "clean-commit source drift after acceptance", + lambda: driver.verify_runtime_provenance(repo, head, base=base_commit, allowed_paths=docs), + "must be clean")) + (repo / "src/coreclr/vm/f1.cpp").write_text("changed-1" + NL, encoding="utf-8") + + failures.append(expect_accept( + "clean-commit restored worktree still accepted", + lambda: driver.verify_runtime_provenance(repo, head, base=base_commit, allowed_paths=docs))) + finally: + driver.RUNTIME_BASE = original_base + + docs_only = base / "docs-only" + docs_only.mkdir() + run(docs_only, "init", "-q", "-b", "main") + (docs_only / "src").mkdir() + (docs_only / "docs").mkdir() + (docs_only / "src/main.cpp").write_text("base" + NL, encoding="utf-8") + (docs_only / "docs/stable.md").write_text("base doc" + NL, encoding="utf-8") + run(docs_only, "add", "-A") + commit(docs_only, "base") + docs_base = run(docs_only, "rev-parse", "HEAD") + (docs_only / "docs/stable.md").write_text("updated doc" + NL, encoding="utf-8") + run(docs_only, "add", "-A") + commit(docs_only, "docs only") + docs_head = run(docs_only, "rev-parse", "HEAD") + failures.append(expect_reject( + "clean-commit delta without any source file", + lambda: driver.verify_runtime_provenance(docs_only, docs_head, base=docs_base, + allowed_paths=("docs/stable.md",)), + "no source delta under src/")) + return failures + + +def cli_cases(base): + """The new clean-commit flags must be rejected in the other provenance modes.""" + failures = [] + root = Path(__file__).resolve().parents[1] + driver_path = str(root / "eng/verify-runtime-session-origin.py") + output = str(base / "cli-output") + global CASES + CASES += 1 + command = [sys.executable, driver_path, "--runtime-root", str(base), "--layout", str(base), + "--output", output, "--runtime-committed-source", str(base / "receipt.json"), + "--runtime-base", "0" * 40] + result = subprocess.run(command, capture_output=True, text=True) + if result.returncode == 0: + failures.append("CLI accepted --runtime-base together with --runtime-committed-source") + elif "only valid in clean-commit" not in result.stderr: + failures.append("CLI incompatible-mode rejection had an unexpected message: " + + result.stderr.strip()[-200:]) + else: + print("PASS reject CLI --runtime-base with --runtime-committed-source") + + CASES += 1 + result = subprocess.run([sys.executable, driver_path, "--runtime-root", str(base), + "--layout", str(base), "--output", output, + "--runtime-base", "474eb8a"], capture_output=True, text=True) + if result.returncode == 0: + failures.append("CLI accepted a short --runtime-base") + elif "full 40-character commit id" not in result.stderr: + failures.append("CLI short-base rejection had an unexpected message: " + + result.stderr.strip()[-200:]) + else: + print("PASS reject CLI short --runtime-base") + return failures + + def main(): parser = argparse.ArgumentParser() parser.add_argument("--workdir", type=Path) @@ -323,6 +495,8 @@ def main(): (build / "clrinterpreter.dll").write_bytes(b"built-clrinterpreter.dll") failures.extend(committed_cases(base, driver)) + failures.extend(clean_commit_cases(base, driver)) + failures.extend(cli_cases(base)) failures = [failure for failure in failures if failure] print("CASES", CASES, "FAILURES", len(failures)) for failure in failures: diff --git a/eng/verify-runtime-session-origin.py b/eng/verify-runtime-session-origin.py index 805b197..7d5cc58 100644 --- a/eng/verify-runtime-session-origin.py +++ b/eng/verify-runtime-session-origin.py @@ -45,22 +45,54 @@ def git_raw(root, *args): return subprocess.check_output(["git", "-C", str(root), *args], text=True) -def verify_runtime_provenance(runtime, expected): - """Require a clean worktree carrying only in-tree runtime source changes.""" +HEX = set("0123456789abcdef") + + +def verify_runtime_provenance(runtime, expected, base=None, allowed_paths=()): + """Require a clean worktree carrying only in-tree runtime source changes. + + base: explicit ancestor commit to diff against. It defaults to the published base so + the historical reproductions keep their original comparison. + allowed_paths: exact canonical tracked docs/.md paths that may appear outside + src/. Wildcards, directories and other folders are rejected. + """ + base = base or RUNTIME_BASE + explicit = base != RUNTIME_BASE or bool(allowed_paths) + if base != RUNTIME_BASE and (len(base) != 40 or not set(base.lower()) <= HEX): + raise ValueError("Runtime base must be a full 40-character commit id; found " + repr(base) + ".") status = git(runtime, "status", "--porcelain", "--untracked-files=normal") if status: raise ValueError("Runtime worktree must be clean; found: " + status.replace(NL, " | ")) head = git(runtime, "rev-parse", "HEAD") if expected and head != expected: raise ValueError("Runtime HEAD must be " + expected + "; found " + head + ".") - if subprocess.run(["git", "-C", str(runtime), "merge-base", "--is-ancestor", RUNTIME_BASE, head]).returncode: - raise ValueError("Runtime HEAD " + head + " is not descended from published base " + RUNTIME_BASE + ".") - changed = [line for line in git(runtime, "diff", "--name-only", RUNTIME_BASE + ".." + head).splitlines() if line] - outside = [path for path in changed if not path.startswith("src/")] + if subprocess.run(["git", "-C", str(runtime), "cat-file", "-e", base + "^{commit}"], + capture_output=True).returncode: + raise ValueError("Runtime base " + base + " is not a commit in the runtime repository.") + if subprocess.run(["git", "-C", str(runtime), "merge-base", "--is-ancestor", base, head]).returncode: + raise ValueError("Runtime HEAD " + head + " is not descended from base " + base + ".") + changed = [line for line in git(runtime, "diff", "--name-only", base + ".." + head).splitlines() if line] + allowed = [] + for path_name in allowed_paths: + parts = path_name.split("/") + if (len(parts) != 2 or parts[0] != "docs" or not parts[1].endswith(".md") + or parts[1].startswith(".") or any(mark in path_name for mark in "*?[")): + raise ValueError("Additional allowed path must be an exact docs/.md file; found " + + repr(path_name) + ".") + if subprocess.run(["git", "-C", str(runtime), "cat-file", "-e", "HEAD:" + path_name], + capture_output=True).returncode: + raise ValueError("Additional allowed path is not tracked at runtime HEAD: " + path_name) + if path_name not in changed: + raise ValueError("Additional allowed path is not part of the delta over the base: " + path_name) + allowed.append(path_name) + outside = [changed_path for changed_path in changed + if not changed_path.startswith("src/") and changed_path not in set(allowed)] if outside: raise ValueError("Runtime changes outside src/: " + ", ".join(outside)) - if not changed and head != RUNTIME_BASE: + if not changed and head != base: raise ValueError("Runtime HEAD carries no source delta over the published base.") + if explicit and not any(changed_path.startswith("src/") for changed_path in changed): + raise ValueError("Runtime HEAD carries no source delta under src/ over base " + base + ".") return head, changed @@ -353,7 +385,16 @@ def main(): parser.add_argument("--build-rid", default=BUILD_RID) parser.add_argument("--build-layout", action="store_true") parser.add_argument("--expect-fixed", action="store_true") + parser.add_argument("--runtime-base", default="") + parser.add_argument("--additional-allowed-path", action="append", default=[]) args = parser.parse_args() + runtime_base = args.runtime_base.strip() or None + allowed_paths = tuple(args.additional_allowed_path) + if runtime_base is not None and (len(runtime_base) != 40 or not set(runtime_base.lower()) <= HEX): + raise ValueError("--runtime-base must be a full 40-character commit id; found " + repr(runtime_base) + ".") + if (runtime_base or allowed_paths) and (args.runtime_committed_source or args.runtime_source_manifest): + raise ValueError("--runtime-base/--additional-allowed-path are only valid in clean-commit provenance mode, " + "not with the committed-source or source-manifest modes.") root = Path(__file__).resolve().parents[1] runtime = args.runtime_root.resolve() @@ -387,7 +428,10 @@ def main(): runtime_head, runtime_changed = verify_source_manifest(runtime, manifest) provenance = "source-manifest" else: - runtime_head, runtime_changed = verify_runtime_provenance(runtime, args.runtime_commit) + if (runtime_base or allowed_paths) and not args.runtime_commit: + raise ValueError("--runtime-base/--additional-allowed-path require --runtime-commit naming the expected HEAD.") + runtime_head, runtime_changed = verify_runtime_provenance( + runtime, args.runtime_commit, base=runtime_base, allowed_paths=allowed_paths) provenance = "clean-commit" if args.build_layout: @@ -663,13 +707,21 @@ def gate_refused_before_file(parsed): verify_source_manifest(runtime, manifest) except ValueError as error: failures.append("runtime source state changed during the run: " + str(error)) + else: + try: + verify_runtime_provenance(runtime, args.runtime_commit, base=runtime_base, + allowed_paths=allowed_paths) + except ValueError as error: + failures.append("runtime state changed during the run: " + str(error)) result["modes"] = {name: {"exit": mode["exit"], "parsed": mode["parsed"] is not None, "stdout": mode["stdout"], "stderr": mode["stderr"]} for name, mode in modes.items()} result["failures"] = failures result["inputCount"] = len(pins) result["drift"] = drift - result["runtimeBase"] = RUNTIME_BASE + result["runtimeBase"] = runtime_base or RUNTIME_BASE + result["runtimeAllowlist"] = list(allowed_paths) + result["runtimeExpectedHead"] = args.runtime_commit or None result["runtimeHead"] = runtime_head result["runtimeChangedFiles"] = runtime_changed result["layoutBuilt"] = bool(args.build_layout)