Is the epoch used by class Instant an implementation detail or not?

[arkiuat]

We need to decide whether class Instant's epoch is an implementation detail (as the docs currently seem to assert) or if on the other hand it should be

1. made part of the language definition
2. checked for a specific value in roast (same thing, right?)

…

Currently the epoch used here by Rakudo corresponds to 1969-12-31T23:59:50Z (because leap seconds hadn't yet been clearly discerned at that time, as explained below).

I raised docs issue Raku/doc#4608 because the statement about the epoch in the current docs for class Instant is confusing. In a comment on that issue, @raiph added the following (I've corrected a disastrous typo in the part where I am quoted: see Raku/doc#4608 (comment) for the complete original text):

the 1969-12-31T23:59:50Z epoch of Rakudo's implementation of Instant

...

Let me excerpt what I think is about the right amount from the Wikipedia page on Leap seconds, with key parts in italic and critical parts in bold:

In 1972, the leap-second system was introduced so that the UTC second could be set exactly equal to the standard SI second, while still maintaining the UTC time of day and changes of UTC date synchronized with those of UT1.

By then, the UTC clock was already 10 seconds behind TAI, which had been synchronized with UT1 in 1958, but had been counting true SI seconds since then.

After 1972, both clocks have been ticking in SI seconds, so the difference between their displays at any time is 10 seconds plus the total number of leap seconds that have been applied to UTC as of that time; as of 2024, 27 leap seconds have been applied to UTC, so the difference [in 2024] is 10 + 27 = 37 seconds.

As I understand things, the DateTime class must do something sensible about the default default epoch aspect of a DateTime. (Note that that's two uses of "default".)

Furthermore, as I understand things, an epoch with a -10 second offset from midnight January 1st 1970 is the only sane default default epoch for an ISO 8601 compliant date/time stamp.

...

So, as I understand things, the doc must make it clear (which it clearly currently doesn't given that you've opened this issue) that something needs to take leap seconds (and perhaps the epoch) into account if users of the DateTime class are to avoid having their Instants off by nearly a half a minute and counting.

[librasteve]

My take on this (and I am definitely not a datetime expert!) is as follows:

in Raku
class Instant is an abstraction of an instant in time measured in seconds
class Duration is an abstraction of duration in time measured in seconds 
a Duration is the difference between two Instants

From this definition, the following arises:

• class Instant may use a standard epoch, but this is implementation dependent
• in general code should not rely on class Instant's underlying epoch
• you could make a library (eg. class Instant1970 is Instant {...}) that pins the epoch and may be used interchangeably
• in which case you need to worry about coercion to/from, comparisons, math, etc. to handle the 10 secs here and there
• other libraries could do things like NTP / atomic clock signal distribution, jitter control and so on

I am sure that I could be convinced that choosing an Epoch is better than leaving it implementation dependent. But I think that this is the current status quo so would like to understand the benefits and costs to make this change.

And yes, ROAST is the Raku language specification and definition.