Normative: Disallow rounding to increment while balancing to calendar…

… unit

The corner case of rounding to a >1 increment of a calendar smallest unit
while simultaneously balancing to a larger calendar unit is ambiguous.
This use case was probably never considered.

const d1 = Temporal.Duration.from({months: 9});
d1.round({
  relativeTo: '2024-01-01',
  largestUnit: 'years',
  smallestUnit: 'months',
  roundingIncrement: 8,
  roundingMode: 'ceil',
});  // => 1 year? 1 year 4 months?

This never came up in real-world usage. Disallow it explicitly, to leave
space for a future proposal if it ever comes up.

Closes: #2902

polyfill/lib/duration.mjs

@@ -286,6 +286,13 @@ export class Duration {
     };
     const maximum = maximumIncrements[smallestUnit];
     if (maximum !== undefined) ES.ValidateTemporalRoundingIncrement(roundingIncrement, maximum, false);
+    if (
+      roundingIncrement > 1 &&
+      (ES.IsCalendarUnit(smallestUnit) || smallestUnit === 'day') &&
+      largestUnit !== smallestUnit
+    ) {
+      throw new RangeError('For calendar units with roundingIncrement > 1, use largestUnit = smallestUnit');
+    }
 
     const roundingGranularityIsNoop = smallestUnit === 'nanosecond' && roundingIncrement === 1;
     const balancingRequested = largestUnit !== existingLargestUnit;

spec/duration.html

@@ -451,6 +451,8 @@ <h1>Temporal.Duration.prototype.round ( _roundTo_ )</h1>
         1. If LargerOfTwoTemporalUnits(_largestUnit_, _smallestUnit_) is not _largestUnit_, throw a *RangeError* exception.
         1. Let _maximum_ be MaximumTemporalDurationRoundingIncrement(_smallestUnit_).
         1. If _maximum_ is not *undefined*, perform ? ValidateTemporalRoundingIncrement(_roundingIncrement_, _maximum_, *false*).
+        1. If _roundingIncrement_ &gt; 1, and _largestUnit_ is not _smallestUnit_, and IsCalendarUnit(_smallestUnit_) is *true* or _smallestUnit_ is *"day"*, then
+          1. Throw a *RangeError* exception.
         1. Let _hoursToDaysConversionMayOccur_ be *false*.
         1. If _duration_.[[Days]] &ne; 0 and _zonedRelativeTo_ is not *undefined*, set _hoursToDaysConversionMayOccur_ to *true*.
         1. Else if abs(_duration_.[[Hours]]) &ge; 24, set _hoursToDaysConversionMayOccur_ to *true*.