Example Page

DST Critical Cases

Daylight saving time is not just a display problem. It creates missing local times, repeated local times, and duration drift that can break payroll, reporting, and batch processing if boundary logic is vague.

Examples Tour Operational Day Demo Duration Scenarios API Snippets
What this page covers: the spring-forward gap, the fall-back ambiguity, and elapsed-versus-wall-clock duration drift, all using the current day-boundary API.
Spring-forward gap
Crash risk

Configured local times can disappear.

Fall-back ambiguity
Data corruption risk

The same wall-clock time can happen twice.

Duration drift
Payroll risk

The same scheduled span can end at different exact instants.

Spring-Forward Gap

Crash avoidance

On Sunday, March 8, 2026 in America/New_York, local 02:30 does not exist. A fixed boundary at that time needs an explicit policy rather than an implicit crash.

Configured boundary
Reference instant
Resolved window start
Resolved gap-day boundary
Compatible policy
Reject policy

Fall-Back Ambiguity

Identity protection

On Sunday, November 1, 2026 in America/New_York, local 01:30 happens twice. If you collapse those into one timestamp, duration math can silently go wrong.

Policy Local timestamp Exact instant Resolved window
Boundary rule
Different window IDs?

Duration Drift

Payroll semantics

An overnight shift can be eight actual elapsed hours or an 00:00 -> 08:00 local wall-clock schedule. On a fall-back night, those are not the same thing.

Start
Requested duration
Elapsed end
Wall-clock end
Same instant?
Difference

What To Lock Down

Policy checklist
  1. Always require an explicit IANA time zone.
  2. Choose a skipped-time policy for spring-forward boundaries: default resolution or fail fast.
  3. Choose an ambiguous-time policy for repeated fall-back timestamps: earlier or later.
  4. Keep window identity based on exact start and end, not wall-clock labels alone.
  5. Decide whether your business rule means elapsed duration or wall-clock schedule before doing payroll math.
  6. Derive reporting labels such as Logical_Date downstream from the resolved window, usually from window.start.
Practical takeaway: DST bugs are not all the same. Some crash a job immediately, some quietly corrupt timestamps, and some distort shift duration. The library helps by forcing those policies into the open.