Normative: add Temporal

[ptomato]

Stage 4 PR for Temporal.

Draft 2026-02-16: This currently includes only the changes to ECMA-262 that would need to be made if putting Temporal in a separate document. It does not yet include the Temporal Object itself. I've posted this for early feedback since I expect these parts will be what attracts the most review comments anyway. I'll update this later on to include the rest of the proposal.

2026-02-20: This now includes the rest of the Temporal proposal.

[ptomato]

Self-reviewing to point out places where you might particularly have questions/comments and places where the one-document approach would simplify things.

We may want to additionally look at https://tc39.es/ecma262/#sec-date-time-string-format. Most likely this can be simplified with Temporal stuff, or turned into a grammar using the building blocks from Temporal's RFC9557 grammar.

[ptomato]

This grammar would be deduplicated into Temporal's RFC 9557 grammar if we go the same-document route.

[ptomato]

This grammar would also be deduplicated into Temporal's RFC 9557 grammar.

[ptomato]

These three sections on ISO Date Records, Time Records, and ISO Date-Time Records would go into a Temporal section if we put Temporal in the same document. But they're needed in ECMA-262 for AOs like GetNamedTimeZoneEpochNanoseconds and GetNamedTimeZoneOffsetNanoseconds.

[ptomato]

As for the "esmeta yet phrases detection" job there seem to be two main issues:

• ESMeta seems not to ignore steps beginning with "NOTE:"
• ESMeta seems not to understand "an integer in the inclusive interval from X to Y"

I'm puzzled about that since both constructions seem to be used elsewhere in the spec. Am I doing something wrong here or do I need to add these manually to a skip list?

Once those are resolved I can dig into the remaining items turned up by ESMeta.

[ptomato]

More self-review with comments on things you may want to look at. I'm planning to join the editor call on Monday 23 Feb, so we can talk through this PR live.

Additional comments not tied to a particular place in the PR:

• We may want to refactor/rewrite 21.4.1.32 Date Time String Format to use the new grammar.
• Probably one of the main things to talk about in the editor call is "how to structure the sections". I've put most everything as subsections of the "Numbers and Dates" section. Maybe it makes sense to split that up into two toplevel sections, "Numbers" and "Dates"? Here's what the second-level outline looks like now:

[ptomato]

CanonicalizeUValue is debatable whether it should be included here. It's moved from ECMA-402 into here, but is only used for CanonicalizeCalendar, to show that if the implementation supports multiple calendars, their identifiers should be canonicalized in the way specified in UTS#35.

An alternative would be to override CanonicalizeCalendar in ECMA-402 instead, and provide a skeleton CanonicalizeCalendar here which does something like "If id is some case-insensitive form of "iso8601", return "iso8601", else throw".

[ptomato]

I've included what this would look like, in an additional commit named "(optional) Change approach for specifying CanonicalizeCalendar".

[Jack-Works]

Hi! I'm implementing Temporal in engine262. I'd like to know if all changes made here will be synced to the Temporal repo, or if the repo will be stale and all new changes will be made here.

[ptomato]

I'm not planning to sync changes back to the Temporal repo, unless someone really wants that.

[github-actions]

The rendered spec preview for this PR is available as a single page at https://tc39.es/ecma262/pr/3759 and as multiple pages at https://tc39.es/ecma262/pr/3759/multipage .

[bakkot]

Notes from editor call:

• let's put Dates+Temporal in their own section, and reduce the current Numbers and Dates section to just Number/BigInt/Math
• Date.parse is no longer strictly a simplification of ISO 8601 as 8601 no longer allows "24" for hours; as this PR is updating the referenced version of 8601, we should add some wording to that effect
• GetOption is overkill, at least for base64, and it can probably be inlined into all of its callsites in Temporal
• [[EpochNanoseconds]] should be a mathematical value instead of a BigInt, both as a matter of convention and because implementations are likely to use a different type than their internal bigint type
• the algorithm in AddTimeDurationToEpochNanoseconds is written with the values backwards from the order in which they appear as parameters, which is confusing even though it doesn't actually affect anything
• don't worry about esmeta for now
• we are undecided on how to handle CanonicalizeCalendar (personally I am fine with the current approach, or for doing something like we do for timezones, as in, we can say here's the implementation if you only support iso8601, otherwise you must use the implementation from 402)

[ptomato]

I've added commits addressing all the things we discussed in Monday's editor call. (To make it easy to see what changed, I'll refrain from squashing or force-pushing until it comes time to merge.)

I tried to request another preview but the job failed with a 403 on npm ci, so not sure what's going on there.

[ptomato]

Pushed another commit addressing a comment from @Jack-Works (tc39/proposal-temporal#3290)

[gibson042]

I think we're missing a syntax error for |TimeZoneIANAName| productions when |TimeZoneIANANameComponent| is "." or "..", which should be added for alignment with RFC 9557.

[ptomato]

I don't think it matters that much, since an annotation like [../../Foobar] will throw a RangeError anyway when given to Instant.from() or ZonedDateTime.from(), because there won't be an IANA time zone with that name.

But note that it would technically be a normative change to make it into a syntax error, because Temporal.PlainDate.from('2026-03-06T15[../../Foobar]') would throw an error instead of ignoring the annotation (as it would with an otherwise syntactically valid annotation such as Temporal.PlainDate.from('2026-03-06T15[Europe/Custom]')).

[ptomato]

I've pushed a commit marked "(optional)" implementing this, if we choose to go ahead with it. But I'd personally recommend against at this point.

[michaelficarra]

I'd prefer you not include that commit in this PR unless you're planning to ask for consensus for the normative change.

[ptomato]

I did not ask for consensus on it, so I've pushed another commit reverting it.

[gibson042]

As noted at tc39/ecma402#1044 (comment) , it might be worth <dfn>ing something like "Temporal data object" for replacing the various lists like this one.

[ptomato]

@gibson042 How important is this to you? I think I'd rather keep it as is for now, but I don't feel strongly about that.

If we add the definition, I don't love the name "Temporal data object", so maybe we could iterate on that.

[gibson042]

I can live with this as it is now, but would prefer to simplify things with a <dfn>. And I'm very open to alternatives for that suggested term—maybe "Temporal value"?

[ptomato]

One sticking point is that we don't want to include Temporal.Duration, so how to express "Temporal object but not Duration"?

[gibson042]

An observation from proposal-amount: these three proposed operations could instead be implemented as a single new operation.

Suggested change

	<emu-clause id="sec-tointegerifintegral" type="abstract operation">
	<h1>
	ToIntegerIfIntegral (
	_argument_: an ECMAScript language value,
	): either a normal completion containing an integer or a throw completion
	</h1>
	<dl class="header">
	<dt>description</dt>
	<dd>It converts _argument_ to an integer representing its Number value, or throws a *RangeError* when that value is not <emu-xref href="#integral-number">integral</emu-xref>.</dd>
	</dl>
	<emu-alg>
	1. Let _number_ be ? ToNumber(_argument_).
	1. If _number_ is not an integral Number, throw a *RangeError* exception.
	1. Return ℝ(_number_).
	</emu-alg>
	</emu-clause>
	<emu-clause id="sec-tointegerwithtruncation" type="abstract operation">
	<h1>
	ToIntegerWithTruncation (
	_argument_: an ECMAScript language value,
	): either a normal completion containing an integer or a throw completion
	</h1>
	<dl class="header">
	<dt>description</dt>
	<dd>It converts _argument_ to an integer representing its Number value with fractional part truncated, or throws a *RangeError* when that value is not finite.</dd>
	</dl>
	<emu-alg>
	1. Let _number_ be ? ToNumber(_argument_).
	1. If _number_ is one of *NaN*, *+∞*<sub>𝔽</sub>, or *-∞*<sub>𝔽</sub>, throw a *RangeError* exception.
	1. Return truncate(ℝ(_number_)).
	</emu-alg>
	</emu-clause>
	<emu-clause id="sec-topositiveintegerwithtruncation" type="abstract operation">
	<h1>
	ToPositiveIntegerWithTruncation (
	_argument_: an ECMAScript language value,
	): either a normal completion containing a positive integer or a throw completion
	</h1>
	<dl class="header">
	<dt>description</dt>
	<dd>It converts _argument_ to an integer representing its Number value with fractional part truncated, or throws a *RangeError* when that value is not finite or not positive.</dd>
	</dl>
	<emu-alg>
	1. Let _integer_ be ? ToIntegerWithTruncation(_argument_).
	1. If _integer_ ≤ 0, throw a *RangeError* exception.
	1. Return _integer_.
	</emu-alg>
	</emu-clause>
	<emu-clause id="sec-snaptointeger" type="abstract operation">
	<h1>
	SnapToInteger (
	_argument_: an ECMAScript language value,
	_mode_: ~strict~ or ~truncate-strict~,
	optional _minimum_: an integer,
	optional _maximum_: an integer,
	): either a normal completion containing an integer or a throw completion
	</h1>
	<dl class="header">
	<dt>description</dt>
	<dd>It converts _argument_ to an integer representing its Number value, rejecting a non-finite value and handling a finite non-<emu-xref href="#integral-number">integral</emu-xref> value by either rejecting or truncating it, and optionally imposes inclusive constraining bounds.</dd>
	</dl>
	<emu-alg>
	1. Let _number_ be ? ToNumber(_argument_).
	1. If _number_ is one of *NaN*, *+∞*<sub>𝔽</sub>, or *-∞*<sub>𝔽</sub>, throw a *RangeError* exception.
	1. Let _mv_ be ℝ(_number_).
	1. If _mode_ is ~truncate-strict~, set _mv_ to truncate(_mv_).
	1. Else if _mv_ is not an integer, throw a *RangeError* exception.
	1. If _minimum_ is present and _mv_ &lt; _minimum_, throw a *RangeError* exception.
	1. If _maximum_ is present and _mv_ > _maximum_, throw a *RangeError* exception.
	1. Return _mv_.
	</emu-alg>
	</emu-clause>

PrepareCalendarFields:

             1. If _Conversion_ is ~to-integer-with-truncation~, then
-              1. Set _value_ to ? ToIntegerWithTruncation(_value_).
+              1. Set _value_ to ? SnapToInteger(_value_, ~truncate-strict~).
               1. Set _value_ to 𝔽(_value_).
             1. Else if _Conversion_ is ~to-positive-integer-with-truncation~, then
-              1. Set _value_ to ? ToPositiveIntegerWithTruncation(_value_).
+              1. Set _value_ to ? SnapToInteger(_value_, ~truncate-strict~, 1).
               1. Set _value_ to 𝔽(_value_).

Temporal.Duration:

-        1. If _years_ is *undefined*, let _y_ be 0; else let _y_ be ? ToIntegerIfIntegral(_years_).
+        1. If _years_ is *undefined*, let _y_ be 0; else let _y_ be ? SnapToInteger(_y_, ~strict~).

[ptomato]

I would like to avoid scope creep on this PR. That said, this wasn't too difficult, I'll add a commit onto the stack marked "(optional)". If it turns out this generates a lot of bikeshedding, then I'd prefer to revert it back to separate operations and save SnapToInteger for a future change.

[Jack-Works]

t is a Number, but TimeValueToISODateTimeRecord requires a finite time value (a time value is NaN or finite int). You did not check if it is an int.

[ptomato]

This is a pre-existing problem. I believe, based on all the current callers of UTC, the type of t should be "integral Number or NaN", but I'm hesitant to change that in this PR without a go-ahead from the editors. It would involve changing the types of MakeDate etc.

See also #3464, not the same but related.

[Jack-Works]

type mismatch: HourFromTime, MinFromTime, SecFromTime both require a finite time value (int), but t is finite number

[ptomato]

Same response as above.

[Jack-Works]

Suggested change

	1. Set _microseconds_ to floor(_nanoseconds_ / 1000).
	1. Set _microseconds_ to R(F(floor(_nanoseconds_ / 1000))).

This precision loss is implemented in TemporalDurationFromInternal in https://tc39.es/proposal-temporal/docs/playground.js, it calls FMAPowerOf10 to do the precision loss.

Without this precision loss, this test will fail:

built-ins/Temporal/Duration/prototype/round/float64-representable-integer.js

Test requires: Temporal.Duration <PT18014398509.48198S>
Current spec: Temporal.Duration <PT18014398509.481981S>

[anba]

The R(F(...)) happens in CreateTemporalDuration, so it doesn't need to be repeated here.

[Jack-Works]

Suggested change

	1. Let _nanosecondsString_ be the substring of _fraction_ from 0 to 9.

If "substring" here is in the sense of JavaScript String.prototype.substring.

Failed case:

 Temporal.Instant.from("1970-01-01T00:19:32.37+00:19:32.37")

parsed as Temporal.Instant <1969-12-31T23:59:59.67Z> if use 1 to 10, correctly as Temporal.Instant <1970-01-01T00:00:00Z> use 0 to 9.

[Jack-Works]

context: ParseDateTimeUTCOffset step 16.c

[gibson042]

In Temporal.Instant.from("1970-01-01T00:19:32.37+00:19:32.37"), ParseDateTimeUTCOffset is called with offsetString "+00:19:32.37", which it parses using |UTCOffset[+SubMinutePrecision]| and gets back a parseResult Parse Node containing a |TemporalDecimalFraction| whose source text is ".37". Step 16.b then sets fraction to the string-concatenation of that string and "000000000" (i.e., ".37000000000"), 16.c sets nanosecondsString to the substring of fraction from 1 to 10 (i.e., "370000000"), and 16.d sets nanoseconds to that number (i.e., 370_000_000), which is in fact the count of nanoseconds indicated by the ".37" in "+00:19:32.37". So what exactly is the problem?

[Jack-Works]

Thanks for the clarification, because my parse node does not contain the . dot, so I need to use 0, 9

[gibson042]

However, there does seem to be a problem in ToTemporalInstant for Temporal.Instant.from("1970-01-01T00+00:19:32.37")—step 3 sets parsed to ParseISODateTime(item, « |TemporalInstantString| »), and ParseISODateTime step 7 initializes minute, second, and fSeconds from the first |MinuteSecond|, |TimeSecond|, and the first |TemporalDecimalFraction| from a parseResult Parse Node resulting from parsing "1970-01-01T00+00:19:32.37" as a |TemporalInstantString|. But |MinuteSecond| and |TemporalDecimalFraction| are optional in |Time| ::: |TimeSpec| (and in fact absent in this |TimeSpec| ::: |Hour| case) and in |DateTimeUTCOffset| ::: |UTCOffset| via |HourSubcomponents| (and present in this |HourSubcomponents| case), resulting in «the first |MinuteSecond|» and «the first |TemporalDecimalFraction|» coming from inside |DateTimeUTCOffset| rather than from inside |Time|, which AFAIK is unintentional and incorrect.

Interestingly, initializing second from |TimeSecond| escapes this problem because |DateTimeUTCOffset| doesn't contain |TimeSecond|. The fix could duplicate that for offset minute and fractional seconds, but that seems brittle. I think instead ParseISODateTime step 7 should take care to specifically exclude Parse Nodes that are part of an offset rather than a base date/time/datetime (noting that this affects all use of ParseISODateTime with a nonterminal that includes |DateTimeUTCOffset|, even as in ToTemporalTime).