racket/time: Ambiguous local time resolution during DST transitions

Local Time Resolution in racket/time

In Racket (v8.0+), the racket/time module does not implement its own time zone logic. Instead, it serves as a wrapper around the host operating system's C library (libc) functions. Consequently, when converting an ambiguous local time (the "autumn fold") back to UTC, the library defers resolution entirely to the underlying OS.

Likely Resolution Behavior

Because there is no explicit "fold" or "gap" parameter in the Racket API, the resulting UTC timestamp depends on the OS implementation of mktime() or its equivalent. While behavior varies by platform, the most common outcomes are:

• System Default: The OS may default to the first occurrence of the hour (the DST offset) or the second (the standard offset).
• Current State: Some systems resolve the ambiguity based on whether the system is currently in DST at the moment the code is executed.

Ensuring Consistency Across Servers

There is no documented method within racket/time to specify a target IANA time zone or resolve offsets on a per-call basis without modifying the system environment. To ensure consistent date offsets across different regional server configurations, you have two primary options:

1. Standardize on UTC: The most reliable method is to avoid local time conversions entirely. Store and manipulate all timestamps as UTC seconds (via current-seconds) and only convert to local time for final display to the user.
2. Environment Variable Control: You can set the TZ environment variable before launching the Racket process. This forces the OS to use a specific IANA time zone regardless of the server's physical location.

; Example: Launching the process with a specific timezone
; bash: TZ="America/New_York" racket my_app.rkt

Verification and Constraints

To verify how your specific OS handles the fold, you can test a known transition date:

(require racket/time)
; Test a date known to be ambiguous in your target timezone
(date-to-seconds #date("2026-11-01T01:30:00"))

Warning: Avoid attempting to change the TZ environment variable using (setenv ... ) within a running Racket process. This is generally not thread-safe and may result in inconsistent behavior across different parts of the application.

To provide a more specific recommendation, please clarify: Are you targeting a specific OS (e.g., Linux vs. Windows) for your server deployments?