What this page covers: define one fixed-time strategy,
resolve an exact timestamp into a window, group records by that window,
and derive a default bucket date from window.start.
For skipped times, repeated times, and DST duration drift, use the
dedicated DST critical-cases page.
Exact Timestamp to Window
Core entry point
Use getWindowForInstant(...) when you have a real exact
timestamp and need the surrounding operational window.
Strategy
Input instant
Window start
Window end
Bucket date
Window ID
Rule
Logical_Date = window.start local date
Metadata
Group Events by Window
Reuse the same rule
The same strategy can drive reports, exports, and dashboards without
duplicating boundary logic in caller code. Events after midnight can
still map to the previous operational bucket when they land before
the next boundary.
Resolved Window
Bucket Date
Events
DST Duration Difference
Elapsed vs wall-clock
During DST transitions, the same labeled duration can end at a
different exact instant depending on whether the rule means elapsed
time or local wall-clock time. This panel is a quick operational
reminder; the dedicated DST page goes deeper into skipped and
repeated local times.
Start
Duration
Elapsed end
Wall-clock end
Same instant?
Difference
Why This Works
Mental model
Related Critical Cases
Where to go next
This operational-day example covers the highest-frequency business
case: a workday that starts on a non-midnight boundary. The same
primitive also protects you from the most expensive clock-change
failures.
Negative offset or night shift: derive the business bucket date from window.start.
Spring-forward gap: choose whether a missing local boundary should resolve forward or fail fast.
Fall-back ambiguity: choose whether repeated local timestamps mean the earlier or later instant.
International Date Line: resolve labels in the owning business zone, not from UTC alone.