Make the *Async entries honour their own cancellation token

[lahma]

Problem

EvaluateAsync, ExecuteAsync, InvokeAsync and Modules.ImportAsync take a CancellationToken but only observed it while awaiting a pending promise:

• a token already cancelled when the call was made still let the script run to completion;
• the interpreter was never told about it, so a script that never yields (while (true) { }) could not be stopped through it at all (the XML docs said so: "does not preempt").

The documented remedy, ObserveCancellation, is fixed when the Options are built, so it cannot carry a per-request token on options shared between engines.

Embedder impact

This is the motivation: OrchardCore's JavaScript engine shares Options per tenant and gets a token per request, so to make the token actually stop a script it

1. calls ThrowIfCancellationRequested() itself before the call,
2. registers an OperationDeadlineConstraint through a per-engine constraint factory for no other reason,
3. Find<OperationDeadlineConstraint>(), Begin(Timeout.InfiniteTimeSpan, token) around every call and End() in a finally.

After this change none of that is needed; passing the token to the *Async call is enough. Hosts that keep the bracket keep working (pinned).

Change

• Each *Async body now calls BeginObservingAsyncEntryToken first, inside its try: an already-cancelled token cancels the returned task (OperationCanceledException carrying the token) before anything is parsed or run, still through the task, per the failure-channel invariant. A cancellable token is installed in engine state (Engine._asyncEntryToken) and EndObservingAsyncEntryToken clears it in the finally, so no later entry, whether sync or async, observes it.
• The token rides the amortized cadence: EvaluationContext's single "amortized work" flag now also includes "an async entry's token is installed" (the same refresh mechanism the sampling profiler uses), and CheckAmortizedConstraints, Constraints.Check() (the self-check of long built-in loops) and interop projection read it. It is never an exact constraint, so the tight-loop lane stays armed. A non-cancellable token (default / CancellationToken.None) changes nothing: the flag and the per-statement path stay as they were.
• It covers the synchronous run, every continuation (fast path and after a pending await), and synchronous re-entries from host callbacks. A second async entry cannot overlap; the reservation already refuses it.
• Registered constraints are checked first, so a host that also registered ObserveCancellation for the same token keeps getting ExecutionCanceledException from a running script.
• The promise-wait loop now hands back the caller's token on OperationCanceledException. Before, it carried the internal linked PromiseTimeout token, or none.

Behaviour change (v5)

This is a documented behaviour change on main, which the v5 line allows: new section 4.146 in docs/guide/migrating-to-v5.md. The XML docs on the entries, docs/guide/async.md, the threat model (TM-10 residual) and Jint/AGENTS.md were updated to match. Code that passed an already-cancelled or soon-cancelled token and relied on the script finishing now gets OperationCanceledException.

Hot-path note for review: per-statement code is unchanged. The amortized check (once per 64 statements) gains one token read. During an *Async call with a cancellable token on an engine with no amortized constraint, the countdown now runs, at the same cost ObserveCancellation has always had.

Tests

All written first and run against the unfixed engine: 22 of the 24 in Jint.Tests failed and 3 of the 4 in Jint.Tests.PublicInterface failed. The ones that passed are non-regression pins.

• Jint.Tests/Runtime/AsyncEntryCancellationTests.cs (24): pre-cancelled token runs no script for every entry (both EvaluateAsync/ExecuteAsync overloads, InvokeAsync, ImportAsync); a cancel during the synchronous run stops five loop shapes (tight-loop lanes included) within the cadence; a cancel at a host-delegate boundary; a cancel in a fast-path continuation and in one resumed after a pending await; a cancel while awaiting carries the caller's token; a nested synchronous re-entry observes the token; a live token changes no result; only a cancellable token arms the cadence and only for the call; the engine is clean after a cancelled call (sync and async entries no longer see the old token, and passing it again is refused up front); a registered amortized constraint keeps the cadence; coexistence with ObserveCancellation.
• Jint.Tests.PublicInterface/HostAsyncEntryCancellationTests.cs (4): the shared-options, per-request-token shape with nothing registered; an already-cancelled request runs nothing (task IsCanceled); an invoked handler is stopped by its request token; a host keeping its OperationDeadlineConstraint bracket still gets its cancellation.

Nothing is timed: each cancel comes from a ClrFunction on the engine thread (not a host-boundary check point), and each loop is bounded, so an engine that ignores the token fails an assertion instead of hanging.

Full Jint.Tests (net8.0, net10.0, net48) and Jint.Tests.PublicInterface pass locally in Release.

🤖 Generated with Claude Code