What goes wrong when converting wall-clock times across DST gaps and overlaps, and how does atZone resolve them?

## Background: what DST does to a wall clock **Daylight Saving Time (DST)** is the practice of shifting a region's clocks (usually +1 hour in spring, back in autumn) to better align daylight with waking hours. A **time zone** like `Europe/London` is not a fixed offset; it has **`ZoneRules`** describing when the offset changes. These shifts create two anomalies in the *local* (wall-clock) timeline: ### 1. The spring-forward GAP When clocks jump from `01:59 -> 03:00`, the wall-clock times `02:00`–`02:59` **never happen**. A `LocalDateTime` of `02:30` on that day is **invalid** for that zone — it points to no real instant. ### 2. The fall-back OVERLAP When clocks fall back from `02:59 -> 02:00`, the wall-clock times `02:00`–`02:59` happen **twice**: once at the old (summer) offset and again at the new (winter) offset. A `LocalDateTime` of `02:30` is now **ambiguous** — it maps to *two* different Instants. ## Why this breaks naive conversion Converting `LocalDateTime -> Instant` requires choosing the offset, and in a gap there is none while in an overlap there are two. A silent cast would have to invent or guess — so java.time forces you through `atZone`, which applies an explicit, documented **resolver** via the zone's `ZoneRules`. ## How `atZone` resolves each case ```java ZoneId paris = ZoneId.of("Europe/Paris"); // GAP: 2026-03-29 02:30 does not exist (clocks 02:00 -> 03:00) ZonedDateTime gap = LocalDateTime.of(2026, 3, 29, 2, 30).atZone(paris); // -> shifted FORWARD to 03:30 with the summer offset (+02:00) // OVERLAP: 2026-10-25 02:30 happens twice (clocks 03:00 -> 02:00) ZonedDateTime overlap = LocalDateTime.of(2026, 10, 25, 2, 30).atZone(paris); // -> defaults to the EARLIER offset (+02:00, the summer one) ZonedDateTime later = overlap.withLaterOffsetAtOverlap(); // picks +01:00 ``` **Gap rule:** the local time is pushed **forward** by the size of the gap, and the *after-gap* offset is used. **Overlap rule:** the **earlier** offset is chosen by default. Override with `withEarlierOffsetAtOverlap()` (explicit default) or `withLaterOffsetAtOverlap()`. You can inspect the rules directly: ```java ZoneRules rules = paris.getRules(); List<ZoneOffset> valid = rules.getValidOffsets(localDateTime); // size 0=gap, 1=normal, 2=overlap ``` ## Practical consequences and best practices - **Past/absolute moments (logs, created-at):** store an **`Instant`** (UTC). There is no ambiguity for a moment that already happened; convert to local only for display. - **Future wall-clock appointments ("meeting at 09:00 next March"):** do **not** pre-resolve to an Instant and store that, because the zone's DST rules (or even political rule changes) might shift before then. Store the **`LocalDateTime` + `ZoneId`** and resolve to an Instant at the last moment, so the *current* rules apply. - **Round-tripping:** `Instant -> LocalDateTime -> Instant` can land on a different moment if the intermediate local time falls in a gap/overlap and you reattach the zone. Avoid the local hop for absolute timestamps. - **Time-zone database updates:** the JDK ships the IANA tz database (tzdb). Governments change DST rules; keeping the JDK / tzdata current matters for correctness of future conversions. ## Mental model The local timeline is not a clean 1:1 mirror of the global timeline — DST tears a hole in it (gap) and folds it over itself (overlap). `atZone` is the function that maps a possibly-invalid/ambiguous local value onto exactly one real instant using deterministic rules, which is precisely why the conversion must be explicit.