testland/dst-transition-reference

Pure-reference catalog of Daylight Saving Time (DST) transition patterns and their canonical bug classes. Covers the spring-forward (skipped hour: 02:00 → 03:00 local) and fall-back (repeated hour: 02:00 → 01:00 local) transitions, the historical irregularity of DST (different jurisdictions, transitions on different dates, some regions abolish DST or never adopted it), the IANA timezone database (tz / Olson DB) as the canonical source, and the testable behaviors DST creates (duplicate / missing local timestamps, cron jobs that fire 0 or 2 times, billing periods that miss / double-count, recurring meetings on transition days). Per-jurisdiction DST-rule tables, refreshable per-region test-data fixtures, and the leap-second reference (23:59:60 insertion, time_t stalls, leap-smear vs step, monotonic-clock fixes) live in references/. Use when designing or auditing time-handling code or test cases, or when auditing leap-second assumptions.

Quality

86%

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

Name: testland/dst-transition-reference
Rating: 68.8 (1 reviews)
Author: testland

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