Document ambiguous time resolution during DST fallback

src/lib/__tests__/hafas-time.test.ts

@@ -124,6 +124,34 @@ describe("getTimezoneOffsetMinutes (via parseHafasTime)", () => {
       expect(d.getUTCHours()).toBe(2);
     });
 
+    it("resolves ambiguous 02:30 to post-transition CET → 01:30 UTC", () => {
+      // During fall-back, 02:30 occurs twice:
+      //   first  02:30 CEST = Oct 26 00:30 UTC
+      //   second 02:30 CET  = Oct 27 01:30 UTC
+      // HAFAS uses the post-transition (standard-time) interpretation.
+      // Our loop tries CET (+60) before CEST (+120), so this is the natural
+      // resolution — matching HAFAS convention.
+      const d = parseHafasTime("20241027", "023000");
+      expect(d.getUTCDate()).toBe(27);
+      expect(d.getUTCHours()).toBe(1);
+      expect(d.getUTCMinutes()).toBe(30);
+    });
+
+    it("resolves ambiguous 02:00 to post-transition CET → 01:00 UTC", () => {
+      const d = parseHafasTime("20241027", "020000");
+      expect(d.getUTCDate()).toBe(27);
+      expect(d.getUTCHours()).toBe(1);
+      expect(d.getUTCMinutes()).toBe(0);
+    });
+
+    it("resolves ambiguous 02:59 to post-transition CET → 01:59 UTC", () => {
+      const d = parseHafasTime("20241027", "025959");
+      expect(d.getUTCDate()).toBe(27);
+      expect(d.getUTCHours()).toBe(1);
+      expect(d.getUTCMinutes()).toBe(59);
+      expect(d.getUTCSeconds()).toBe(59);
+    });
+
     it("treats 12:00 on Oct 27 as CET (after transition) → 11:00 UTC", () => {
       const d = parseHafasTime("20241027", "120000");
       expect(d.getUTCHours()).toBe(11);

src/lib/hafas-time.ts

@@ -37,6 +37,13 @@ function getTimezoneOffsetMinutes(instant: Date, tz: string): number {
  * candidate UTC timestamp via Date.UTC, and verify by checking that Vienna's
  * offset at that candidate instant matches the assumed offset. The first match
  * wins. This correctly handles DST transitions.
+ *
+ * Ambiguous times during the fall-back DST transition (02:xx on Oct 27, 2024):
+ * HAFAS resolves ambiguous local times by using the post-transition (standard)
+ * interpretation. Our loop tries CET (+60) before CEST (+120), so ambiguous
+ * hours naturally resolve to CET — matching HAFAS convention. For example
+ * "023000" on "20241027" → Oct 27 01:30:00 UTC (the second 02:30, not the
+ * first).
  */
 export function parseHafasTime(dateStr: string, timeStr: string): Date {
   const y = parseInt(dateStr.slice(0, 4), 10);