PluginPublic

testland/dst-transition-reference

Use when designing or auditing time-handling code or its tests around daylight saving time: skipped and repeated hours, jurisdiction differences, the IANA tz database, cron jobs that fire zero or two times, billing and meetings on transition days, plus leap seconds and clock smearing.

Quality

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Leap-second mechanics and bug classes

A leap second is an extra second (23:59:60 UTC) inserted to keep UTC within 0.9s of UT1. Per IERS Bulletin C (datacenter.iers.org/data/latestVersion/bulletinC.txt), insertions get ~6 months of notice. 27 were inserted 1972-2016 (most recent 2016-12-31); none since, and per the 27th CGPM resolution (2022) leap seconds will be abolished by 2035. Audit this surface only when second-granular progress matters: financial timestamping, distributed logs, NTP-sensitive schedulers.

Mechanics

Property	Detail
Frequency	Irregular; announced by IERS Bulletin C
Insertion point	Last second of UTC June 30 or December 31
Wire format	23:59:60 UTC (a real 61st second of the minute)
POSIX `time_t`	Does NOT include leap seconds; it stalls or jumps back 1s on insertion
NTP	Carries a leap indicator; client handling varies (2012 Linux kernel-hang incident)

Whether a host inserts a real 23:59:60 or smears it over 24 hours (Google / AWS) is per-host - see smear-strategies-and-history.md. A smear is invisible to applications; a real insertion exposes the discontinuities below.

Bug classes

time_t non-monotonicity - on insertion the clock stalls (1483228799 repeats) or jumps; "1s of CPU = 1s of clock" breaks.
Negative durations - time.time() - start can go below zero across the insertion. Fix: monotonic clocks (time.monotonic(), clock_gettime(CLOCK_MONOTONIC)) for all duration measurement.
NTP cascading - OS-dependent handling of the leap indicator.
Distributed clock skew - one node steps, another smears; skew temporarily exceeds 1s. Per AWS, AWS smears specifically to avoid this.

Testable behaviours

Behaviour	Test
Durations use a monotonic clock	`time.monotonic()` deltas stay >= 0 across the leap
Sortable timestamps don't collide	Sequence numbers / sub-second resolution beside stalled `time_t`
Cron at `00:00:00 UTC` of leap day	Fires exactly once
Per-host absorption strategy known	Verify step vs smear per host before comparing cross-node timestamps

Worked assertion - negative durations

start = time.monotonic()
do_work()                     # crosses 2016-12-31 23:59:60 UTC
elapsed = time.monotonic() - start
assert elapsed >= 0           # holds; the time.time() form can trip

Simulate by pinning a fake clock to the last real leap second (freeze_time('2016-12-31 23:59:59 UTC') - see the fake-clock-testing skill) and advancing across it. Caveat: fake clocks can't replay the OS-level leap indication - this asserts the code's clock choice, not the kernel's behaviour; a real leap needs an OS-level test.

Anti-patterns

Anti-pattern	Why it fails	Fix
`time.time() - start` for durations	Wall clock; affected by leap	`time.monotonic()`
Treating `time_t` as continuous	Historical insertions broke it	Per IANA leap-seconds.list
Hardcoding 86400 seconds-per-day	Only sometimes true	Calendar arithmetic
Assuming all servers smear	Some step	Verify per-host strategy