Skip to content

Enforce callback deadlines from a host-owned epoch clock (opt-in) - #29

Merged
ReneeGA2020 merged 16 commits into
mainfrom
feature/optional-epoch-deadline-integration-20261112
Nov 12, 2026
Merged

ReneeGA2020 merged 16 commits into
mainfrom
feature/optional-epoch-deadline-integration-20261112

Conversation

@ReneeGA2020

@ReneeGA2020 ReneeGA2020 commented Nov 12, 2026 •

Copy link
Copy Markdown
Owner

Enforce callback deadlines from a host-owned epoch clock (opt-in)

Summary

Extends the existing callback-deadline option with explicit Epoch mode in MapRunOptions/MapSession.
The trusted host can use the existing monotonic clock or a process-wide epoch that it ticks and
reads itself. Clock remains the default deadline mode and stock-SDK behaviour is preserved.
Deadline enforcement requires the matching interpreter runtime and fails closed.

The branch also merges origin/main aa31875 (the merged session-origin host PR #28), so both
opt-ins ship together and were accepted together on one combined runtime.

Paired runtime change: ReneeGA2020/runtime#2, merged into
runeclr/dev as b747ab4d51d8da563b709a8b08ba69d15a314c03. It is docs-only beyond the tested
source fed410bbe368b465b6628338a6fc04d6c38a4f2e (parent merge 234c0b7a… over runeclr/dev
474eb8ad…), whose 14 product paths are byte-identical in the merged tree, so the measured
binaries above remain the validated product code. The earlier e637bd79… delivery and its
numbers are kept as history.

What changes

  • MapDeadlineMode (Clock default, Epoch opt-in) plus the epoch period on MapRunOptions.
  • CallbackEpochTicker: one process-wide lease and ticker owned by the host. A session leases it
    before any author file is opened and releases it after the author stack returns. The runtime
    creates no timer and no thread.
  • CallbackDeadlineBridge gains the additive epoch factory, tick/read delegates and a capability
    check (capabilities & 2). A deadline-only session no longer requires the instruction-terminal
    API: the deadline ABI, the instruction budget and both together bind independently.
  • Termination reporting names the mechanism that actually tripped; author failures still report the
    exception type only.
  • Epoch tests, eng/verify-epoch-integration.py and an 11-case provenance fixture
    (eng/test-epoch-integration-provenance.py) cover the new path.
  • eng/verify-runtime-session-origin.py gains 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/<name>.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, the same base/allowlist/expected HEAD is revalidated
    after the run, and the new flags are refused in the committed-source and source-manifest modes.
    eng/test-session-origin-provenance.py covers the accepted and rejected shapes (43 cases).

Behavior and compatibility

  • The clock path stays the default. Sessions that do not opt in behave as before.
  • Configuration happens on a fresh interpreter-required context before its first execution. A
    context that already executed is rejected and the caller must create a new context.
  • Author exceptions, budget exhaustion and ticker faults all fail closed. This is an execution
    budget, not a security sandbox, and the host must keep the ticker alive and dispose it from an
    ordinary thread. Author finalizers in a budgeted context are process-fatal (see Limits).
  • The session-origin switch RuneCLR.EnableReflectionPolicyOriginScan stays disabled by default.

Verification

Host builds and stock-SDK regressions are separate from the private-runtime results below. The
combined results are local Windows x64 Release runs on one private layout composed from the combined
delivery (coreclr 48289d63…, clrinterpreter 6b861fc7…, clrjit 197834f4…, corerun 30a8dd9a…,
CoreLib e9a94ae0…) with bootstrap hosting components only; no installed runtime is replaced.

  • Stock desktop build: 0 warnings, 0 errors. Stock regression on the installed SDK: 156/156.
  • Epoch suite on the combined runtime: 24 passed / 0 skipped / 0 failed.
  • Epoch verifier: 669 pinned inputs, 523-file private layout, zero drift.
  • Session-origin fixed matrix on the same layout: 16/16 modes at --runtime-base 474eb8ad… --runtime-commit fed410b…, 710 pinned inputs, zero drift. The runtime delta over the base is 15
    files under src/ plus the two canonical documents docs/runeclr-dev.md and
    docs/runeclr-callback-epoch.md, and the native hashes are the five above.
  • Lifecycle harness: 156/156 ordinary and 156/156 with --require-interpreter, separate processes.
  • Provenance fixtures: epoch 11 passed / 0 skipped / 0 failed; session-origin 43 passed / 0 skipped /
    0 failed.
  • Focused upstream compatibility on the combined Release binary: ContextualReflection,
    CollectibleStatics, GenericVirtualMethod and InterpreterTester each Expected 100 / Actual
    100, exit 0. The official interpreter wrapper asserts only the child exit code, so this is
    compatibility evidence for the documented configuration, not a per-method interpreted trace.

Performance scope

One machine, Windows x64 Release interpreter, 7 timed samples per round, no CPU pinning.

  • Default OFF (patched but unconfigured) versus unpatched runeclr/dev: final three-round window
    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; it is history. No universal zero-overhead or
    speedup claim is made.
  • Epoch ON versus the same build's OFF lanes at intervals 1 / 100 / 1000: about 3.4x to 5.3x in
    the three micro lanes. The 2x budget tolerance is a granularity choice, not a CPU acceptance
    threshold.
  • Cross-module delegate calls (three interleaved rounds, artifact-only corrected driver): the
    headline is the minimum of the three round minima, 13.9 ms cross-module versus 13.9 ms
    baseline. The normalised medians over the same logs are 14.6 vs 14.3 ms (median of per-round
    min-of-7 values) and 16.8 vs 14.6 ms (median of sample medians). The minimum is not a median and
    none of these is a noiseless speedup claim.

Limits

  • Windows x64 Release interpreter only; Debug is compile-only. No Linux, Wasm, device, AOT,
    unmanaged-entry, global all-load or JIT/R2R instrumentation evidence. The combined acceptance
    covers both opt-ins on this one process model and adds nothing beyond it.
  • Native blocking cannot be interrupted, including a Sleep inside a finally block.
  • Author finalizers in a budgeted context are process-fatal: an isolated lane showed a post-End
    finalizer denied at its first checkpoint, terminating the process with an unhandled
    OperationCanceledException on both the frozen 7f and final 08 runtimes, while the unconfigured
    control completed normally. This is a pre-existing limitation, not cleanup or recovery; an
    active-window finalizer and epoch-mode finalizers were not tested, and not every finalizer is
    shown to be blocked. Keep no pending author finalizer in a budgeted context; explicit disposal
    alone does not prevent finalization.
  • One active callback per session and a single owner thread; a competing callback or thread fails
    closed.
  • The epoch runtime has no instruction quota or terminal bridge; the both-feature path is only
    covered at its pre-author missing-capability check.
  • The ticker must be ticked and read from non-blocking code; Stop/Dispose must be called from an
    ordinary host thread, and the join has no timeout.
  • InstallTestTimerFault is an internal experimental test hook in the test assembly, not product
    API.
  • The numbers above are local runs, not remote CI, and they do not establish device or iOS
    behaviour.

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)
…type

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)
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)
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)
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)
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)
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)
Fixes the git diff --check 'new blank line at EOF' report from the previous commit.

Assisted-by: Cindy (https://cindy.app)
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)
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)
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)
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)
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)
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)
…h-deadline-integration-20261112

# Conflicts:
#	docs/development.md
… 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/<name>.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)
@ReneeGA2020
ReneeGA2020 merged commit ca5f626 into main Nov 12, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant