The canonical unit of this knowledge base is the hour-of-week slot: an integer from 0 to 167 identifying which of the 168 hours in a repeating week an instant falls in. It is the single coordinate every conversion, model feature, and report in this KB is ultimately expressed against.
Definition
Slot 0 is Monday 00:00 UTC. The slot of any UTC instant is computed as:
where weekdayMon0 is 0 for Monday through 6 for Sunday, and hourUTC is
the UTC hour-of-day, 0 through 23. The formula takes only the UTC instant
as input — no zone, no local calendar, no declared cutover. That is
deliberate: the slot is defined once, on the one timeline every system in
the world already agrees on, and every zone-aware complexity (which local
hour this corresponds to in Tokyo versus Toronto) is pushed to a separate
annotation layer rather than baked into the coordinate itself.
- range
- 0 to 167 inclusive, 168 total slots
- origin
- slot 0 = Monday 00:00:00 UTC
- input
- a single UTC instant (epoch milliseconds)
- determinism
- pure function of the instant; no zone or policy parameter
- period
- repeats every 7 days (604,800,000 ms)
- uniqueness
- not unique alone; pair with an ISO week for a unique moment
A slot repeats; a (week, slot) pair does not
Slot 45 identifies "Wednesday, 21:00 UTC" as a recurring position in the
weekly cycle — this Wednesday, next Wednesday, and every Wednesday since
the epoch share slot 45. That repetition is the entire value of the
coordinate for demand modeling: it lets a Tuesday-lunch spike be compared
week over week without re-deriving "Tuesday lunch" from a calendar each
time. But repetition means slot 45 alone cannot answer "when," only
"which position in the cycle." Uniqueness requires pairing the slot with
an ISO 8601 week number and week-numbering year, producing the canonical
key format 2026-W29-S045 — see
ISO week and the week-slot key. The pairing is computed
by weekSlotKey, which derives both the ISO week and the slot from the
same UTC instant, so the two halves of the key can never disagree about
which timeline they were measured on.
import { instantToSlot, slotToLabel } from "@/lib/time/slot";
import { weekSlotKey } from "@/lib/time/isoweek";
const epochMs = Date.UTC(2026, 6, 22, 21, 0, 0); // 2026-07-22T21:00:00Z, a Wednesday
const slot = instantToSlot(epochMs);
// 69 — Wednesday is weekdayMon0=2, hourUTC=21 -> 2*24 + 21 = 69
console.log(slotToLabel(slot));
// "Wed 21:00 UTC" (label is derived from the slot, not recomputed from epochMs)
const key = weekSlotKey(epochMs);
// { isoYear: 2026, isoWeek: 30, slot: 69, key: "2026-W30-S069" }
instantToSlot and weekSlotKey both derive the weekday/hour split from
the same UTC instant, which is the property that matters: two calls
against the same epoch millisecond value, anywhere in the codebase,
always agree, because neither depends on the caller's local clock,
locale, or the platform's default time zone — only on the instant itself.
The H3-cell analogy
The slot is the time analog of an H3 cell in the geo-interoperability KB: a deterministic, boundary-independent bucket that every instant (point) falls into exactly once per period, computed from a fixed, declared convention rather than from the observer's frame of reference. An H3 cell does not care which country's coastline drew the polygon it sits inside; a slot does not care which local clock the observer used to describe the hour. Both are stable join keys precisely because they are decoupled from the political and cultural boundaries — administrative or civil-time — laid over the same underlying continuum. And, just as an H3 cell needs a resolution parameter to be meaningful (R7 versus R8), a slot needs its pairing convention (bare slot versus week-keyed slot) declared before being joined against another dataset — see Resolution and grain for when a coarser or finer unit than the slot is the right choice.
Edge cases
Slot-origin convention is the most common integration bug: a system that assumes a Sunday-start week, or one that anchors slot 0 to local midnight instead of UTC midnight, disagrees with this KB's convention by a whole day (24 slots) or by the zone offset, respectively — and the disagreement is silent until two slot-indexed datasets are joined and every weekday looks shifted. Always declare the origin (Monday 00:00 UTC) explicitly when documenting or exporting a slot-indexed dataset, and convert incoming data from any other convention on ingest rather than downstream.
Week-year boundary affects the pairing, not the slot itself: the ISO week-numbering year can differ from the calendar year in late December and early January (for example, 2027-01-01 falls in ISO week 2026-W53), so a slot must always be carried alongside both the ISO week number and the ISO week-year, never a bare week number, or the pairing silently points at the wrong year's week 1. See ISO week and the week-slot key for the full resolution.