Temporal: a month difference past the calendar's range raises RangeError instead of spinning

[lahma]

Fixes #3428.

What was wrong

NonIsoCalendars.CalendarDateUntil measures a difference by walking one month at a time from the source
towards the target, and its only exit is "this step passed the target". NonIsoCalendars.CalendarDateAdd
takes those steps, and when the conversion back to ISO left the range of the backing
System.Globalization.Calendar it did not report that — it answered with ClampToCalendarRange, which
ignored its year, month and day arguments entirely and returned cal.MaxSupportedDateTime:

private static IsoDate ClampToCalendarRange(Calendar cal, int year, int month, int day)
{
    var dt = cal.MaxSupportedDateTime;
    return new IsoDate(dt.Year, dt.Month, dt.Day);
}

The calendar's maximum, whichever end had been overrun. So every further step of a backwards walk landed
on that same date, no step ever passed the target, and the loop had no other exit.

Temporal.PlainDate.from('1910-01-01').withCalendar('chinese')
    .until(Temporal.PlainDate.from('1900-01-03').withCalendar('chinese'), { largestUnit: 'year' });
// never returned

ChineseLunisolarCalendar spans ISO 1901-02-19 to 2101-01-28, so the target is outside it.

What an embedder saw

The thread, and nothing else. It is a CLR loop inside one interpreter step, so it crosses no statement
boundary: LimitStatements never counted, LimitExecutionTime never got a check, and a
CancellationToken was never observed. Jint.Constraints.OperationDeadlineConstraint does not help
either, for the same reason. A host that bounded untrusted script the documented way still lost the
thread, and the only way back was to end the process.

Reachable from any script that can name a chinese, dangi, hebrew or persian date, through until,
since and total on PlainDate, PlainDateTime, PlainYearMonth, ZonedDateTime and Duration.
Present in every released version; nothing recent introduced it.

The same clamp was also answering, rather than hanging, on the addition side — with the wrong date, and
with no signal that it was wrong:

Temporal.PlainDate.from('1950-01-01').withCalendar('chinese').subtract({ years: 100 });
// 2101-01-28[u-ca=chinese]   -- subtracting a century moved it a century and a half forward
Temporal.PlainDate.from('2050-01-01').withCalendar('hebrew').add({ years: 500 });
// 2239-09-29[u-ca=hebrew]

What changed

Out-of-range calendar arithmetic reports itself instead of clamping. NonISODateAdd is
implementation-defined and is declared as returning "either a normal completion containing an ISO Date
Record or a throw completion"
(spec), and CalendarDateAdd raises a
RangeError for a result it cannot represent
(spec), so that is what the two
TemporalHelpers entry points now do with it. Both overflow modes report it: leaving the calendar's
range is not the month-or-day overflow constrain is allowed to clamp, because there is no nearby valid
date to clamp to — only the calendar's own boundary.

• NonIsoCalendars.CalendarDateAdd — ClampToCalendarRange is gone; the ArgumentOutOfRangeException
  from cal.ToDateTime becomes a CalendarRangeException.
• NonIsoCalendars.IndianCalendarDateAdd and IslamicTabularCalendarDateAdd — both answered
  result ?? isoDate, handing back their input date when the conversion failed. That is the same
  no-progress answer by a different route: add reports that adding a year changed nothing, and the walk
  takes the same step forever. Both now report instead.
• NonIsoCalendars.CalendarDateUntil — the walk keeps a no-progress guard of its own. A step that does
  not move the date can never pass the target however many more are taken, so it is a RangeError too.
  With the three fixes above it is unreachable today; it stays as the structural guarantee that this loop
  terminates, so a clamp reintroduced anywhere below it cannot become a hang again.
• TemporalHelpers.CalendarDateAdd / CalendarDateUntil map it to Throw.RangeError. realm is now
  threaded through DifferenceISODateTime (all three of its callers already had one) and is no longer
  optional on CalendarDateUntil, so no call site can lose it and turn a script-visible RangeError into
  a CLR exception escaping Engine.Evaluate.

All internal; no public API change.

Siblings checked and found sound

• CalendarDateUntil's other units. week, day and smaller are closed-form ISO epoch-day
  arithmetic with no loop; the year count is arithmetic plus a single overshoot check. Only the month walk
  loops, and with largestUnit: 'year' it takes at most ~13 steps whatever the span.
• FixedEpochCalendarDateAdd (coptic/ethiopic/ethioaa) is pure epoch-day arithmetic with no backing
  BCL calendar and no clamp, so it always progresses. Same for IndianToCalendarDate,
  IslamicCivilToCalendarDate and the IsoToCalendarDate arms behind them. Those six calendars still
  measure across the whole Temporal range, which a test now pins.
• The month-wrap loops in the four *CalendarDateAdd variants (while (newMonth > 12/13),
  while (newMonth < 1)) are bounded by a months-in-year that every arm documents as never below 12.
• The year-estimate correction loops — HebrewAlgorithmicFromIso, PersianToCalendarDate,
  EpochDaysToFixedEpoch — correct a bounded estimate against a monotone year-start function.
• The reference-year searches (MaxDaysForChineseLeapMonth, FindFixedEpochReferenceYear,
  FindIndianReferenceYear, …) are bounded for loops over fixed windows.
• TemporalHelpers.CalendarDateUntil's Gregorian-based path counts years and months by direct
  arithmetic and has no unbounded loop.

Failing-test evidence

Jint.Tests/Runtime/NonIsoCalendarRangeTests.cs runs every case on a dedicated thread with a 15-second
join, so a regression fails the run rather than wedging it. Against unfixed main, the same file:

Failed chinese below its 1901 floor [15 s]
  did not finish within 00:00:15: Temporal.PlainDate.from('1910-01-01').withCalendar('chinese').until(…)
Failed chinese above its 2101 ceiling [15 s]
Failed dangi above its 2051 ceiling [15 s]
Failed hebrew below its 1583 floor [15 s]
Failed hebrew above its 2239 ceiling [15 s]
Failed persian below its 622 floor [15 s]
Failed EveryDifferenceSurfaceThatWalksMonthsIsBounded [15 s]
Failed TheReportedMonthDifferencePastTheChineseRangeRaisesRangeError [15 s]
Failed TheRefusalIsAJavaScriptErrorAScriptCanCatch [15 s]
Failed ArithmeticPastACalendarRangeRaisesRangeError…("chinese","1950-01-01","subtract({ years: 100 })")
  Expected … "RangeError", but was "2101-01-28[u-ca=chinese]"
… and five more of the same

Failed!  - Failed: 15, Passed: 7, Skipped: 0, Total: 22, Duration: 2 m 15 s

Nine of those fifteen are the hang; six are the boundary date answered as if it were the result. With the
fix: 22 passed / 0 failed on net472, net8.0 and net10.0.

Follow-up: the net472 red leg on the first push, diagnosed

The first push's Windows leg failed one of the new tests on net472 only:

did not finish within 00:00:15: Temporal.PlainDate.from('1950-01-01').withCalendar('coptic')
  .until(Temporal.PlainDate.from('-100000-01-03').withCalendar('coptic'), { largestUnit: 'year' })

It is not the walk. Measured on net472, calling the walk directly:

coptic          cold=0.114ms  warm=0.0102ms/call  years=-101947 months=-11 days=-24
ethiopic        cold=0.011ms  warm=0.0100ms/call  years=-101947 months=-11 days=-24
ethioaa         cold=0.016ms  warm=0.0096ms/call  years=-101947 months=-11 days=-24
indian          cold=0.010ms  warm=0.0073ms/call  years=-101949 months=-11 days=-28
islamic-civil   cold=0.012ms  warm=0.0110ms/call  years=-105078 months=-11 days=-6
islamic-tbla    cold=0.020ms  warm=0.0154ms/call  years=-105078 months=-11 days=-6

Ten microseconds, with the right answer. It could not be an exception-type or range divergence in the
netfx BCL either: coptic, ethiopic and ethioaa have no System.Globalization.Calendar behind them
at all — CalendarDateAdd routes them to FixedEpochCalendarDateAdd, which is pure epoch-day arithmetic,
so no catch and no BCL range is involved on any target framework.

The 15 seconds was thread scheduling. DedicatedThread.Run started every body at
ThreadPriority.Lowest. Pinning the test process to a two-core affinity mask and running two
normal-priority busy threads — a small CI runner reproduced without saturating a 32-core box — the same
warm 0.1 ms evaluation:

round 0: Lowest=2462ms   Normal=144ms
round 1: Lowest=2554ms   Normal=159ms
round 2: Lowest=2488ms   Normal=128ms

A 17× penalty from two competitors. The CI job is far harsher: its log shows four test assemblies in
flight at once on a four-core windows-latest runner —

01:39:47  Jint.Tests.dll (net472)                  1 m 28 s   <- the failure
01:39:54  Jint.Tests.PublicInterface.dll (net8.0)  1 m 43 s
01:41:33  Jint.Tests.dll (net8.0)                  3 m 15 s
01:41:34  Jint.Tests.dll (net10.0)                 3 m 15 s

— each with [assembly: Parallelizable(ParallelScope.Fixtures)] and LevelOfParallelism defaulting to
the core count, so roughly sixteen normal-priority workers over four cores. The net472 assembly alone
took 1 m 28 s there against 19 s uncontended locally, a 4.6× inflation at normal priority; a Lowest
thread inside that fares far worse. And the body was cold: the first Temporal script in a net472 process
pays the intrinsic graph plus JIT, measured at 547 ms of CPU against 0.1 ms for every one after it — and
ACalendarReckonedByArithmeticStillMeasuresAcrossTheWholeTemporalRange sorts first among the fixture's
methods, so it is the body that absorbs that warmup, on the starved thread.

The fix, and it is not a bigger budget

Jint.Tests/DedicatedThread.cs now starts a body at normal priority and demotes the thread to Lowest
only once its join has timed out — at which point it is known to be a runaway that must be kept off the
cores the rest of the run needs. The helper's comment already said what the demotion is for; only its
timing moves. The priority a runaway deserves is not the priority a body that is going to finish deserves,
and every caller of the helper was paying the former.

Verified by reproducing the CI failure locally and then removing it — same machine, same two-core affinity
mask, same full net472 assembly, one line of difference:

DedicatedThread	net472 result
start at Lowest (main's)	Failed: 1 — ACalendarReckoned…("coptic"), did not finish within 00:00:15 [20 s], 7426 passed
demote on timeout (this PR)	Passed: 7427, Failed: 0, 4 skipped

The 15-second budget is untouched. Under the two-core reproduction the body completes in ~0.14 s against
it, a 100× margin.

Test suites

Rebased onto c39396fd4. One dotnet test -c Release run, everything green:

Jint.Tests.dll (net472)                  7427 passed,     0 failed,   4 skipped
Jint.Tests.dll (net8.0)                 10803 passed,     0 failed,   5 skipped
Jint.Tests.dll (net10.0)                10803 passed,     0 failed,   5 skipped
Jint.Tests.PublicInterface.dll (net472)  2501 passed,     0 failed,  21 skipped
Jint.Tests.PublicInterface.dll (net8.0)  3121 passed,     0 failed,  21 skipped
Jint.Tests.PublicInterface.dll (net10.0) 3131 passed,     0 failed,  21 skipped
Jint.Tests.CommonScripts.dll (net472)      28 passed,     0 failed
Jint.Tests.CommonScripts.dll (net10.0)     28 passed,     0 failed
Jint.Tests.SourceGenerators.dll            71 passed,     0 failed
Jint.Tests.Test262.dll                 102495 passed,     0 failed, 189 skipped

test262: 102,495 / 0 / 189 — the control number. dotnet build -c Release: 0 errors, no new warnings.

Two siblings found but not fixed here

Both are wrong answers rather than hangs, with their own blast radius, so they are filed separately:

• Duration.prototype.round reads the calendar off a PlainDate relativeTo and then reckons in iso8601 #3450 — Temporal.Duration.prototype.round reads the calendar off a PlainDate relativeTo and then
  reckons in iso8601. It is why the round half of the report never hung: it was not reaching the walk
  that did.
• A date past a non-ISO calendar's range reports ISO fields under that calendar's name #3451 — a date outside a non-ISO calendar's implementation range reports ISO fields under that
  calendar's name (Temporal.PlainDate.from('1800-01-01').withCalendar('chinese').monthCode is 'M01').
  Now that the arithmetic refuses at the boundary, the field accessors are the remaining place where the
  engine answers something it does not know.

🤖 Generated with Claude Code

https://claude.ai/code/session_014W5mbjGhyvgAS4pivXoc4S