Repository navigation
fix(slots): align slot starts to local wall clock, not the UTC epoch - #183
Conversation
alignUp rounded starts to multiples of the interval counted from the Unix epoch, i.e. on the UTC clock. For a host whose UTC offset is not a whole number of hours (Tehran +03:30, India +05:30, Nepal +05:45, Adelaide, Newfoundland, ...) every hourly slot started at :30/:45 local: a 09:00-17:00 day offered 09:30, 10:30, ... and never 09:00. Intervals that do not divide a day (50, 35 min) also drifted from one day to the next, even in UTC. Align to local midnight on one shared wall clock - the first pool host's timezone - so collective and round-robin hosts still meet on identical start instants. UTC hosts keep exactly the old grid for intervals dividing a day. Wall-clock arithmetic keeps the grid stable across DST change days. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
🟡 Changes recommended
Slot generation still produces off-grid times across midnight and DST transitions, skipping valid starts and potentially eliminating shared slots for collective routing.
3 open issues
What changed in this PR
Updates slot generation to address #182 by aligning starts to the lead host’s local wall clock rather than the UTC epoch, while retaining a shared clock for multi-host routing.
Changes:
- Selects the first pool host’s timezone as the shared alignment clock.
- Calculates interval boundaries from local midnight.
- Adds regression tests for fractional-hour offsets, daily alignment, and DST-day alignment.
| File | Description |
|---|---|
internal/slots/generate.go |
Introduces the shared timezone and local-midnight alignment logic. |
internal/slots/generate_test.go |
Tests whole-hour slot generation for a Tehran host. |
internal/slots/availability_test.go |
Updates alignment calls and adds timezone, daily-reset, and DST tests. |
Review effort: Balanced
| // (epoch-aligned so slots land on :00/:15/:30/:45 etc.). | ||
| t := alignUp(f.Start, p.interval) | ||
| // on the shared wall clock, so slots land on :00/:15/:30/:45 etc. | ||
| t := alignUp(f.Start, p.interval, p.alignLoc) |
| steps := wall/secs + 1 | ||
| y, m, d := lt.Date() | ||
| out := time.Date(y, m, d, 0, 0, int(steps*secs), 0, loc) |
| out := time.Date(y, m, d, 0, 0, int(steps*secs), 0, loc) | ||
| for out.Before(t) { // a DST gap/overlap can land the wall-clock instant behind t | ||
| out = out.Add(interval) |
There was a problem hiding this comment.
ℹ️ No behavioral defects found in the new alignment logic — a few comment and doc-accuracy notes inline.
Reviewed changes
- Local-midnight alignment —
alignUpnow rounds to the next interval multiple counted from local midnight on a supplied location instead of the Unix epoch. - Shared grid —
newParamstakes that location from the first pool host andhostsByStartuses it for every host, so collective/round-robin starts stay on identical instants. - Tests — added half-hour-offset, non-dividing-interval, DST, and end-to-end Tehran generation coverage.
ℹ️ ARCHITECTURE §9 still describes alignment without its origin
docs/ARCHITECTURE.md:279 says the engine "aligns to the slot interval" but not what it aligns to, and the new shared-clock decision (first host's timezone, why it must be shared) is the kind of non-obvious cross-cutting rule this doc exists to record. §24 asks for the matching section to be updated in the same PR.
Technical details
# Document the alignment origin in §9
## Affected sites
- `docs/ARCHITECTURE.md:279` — "Computes per-host free windows per UTC day, intersects/subtracts busy, aligns to the slot interval" gives no origin and no hint that the grid is shared across hosts.
## Required outcome
- State that starts are aligned from local midnight of the lead (first) host's timezone, shared across the whole pool because collective/round-robin routing joins hosts on identical start instants, and that UTC hosts keep the old epoch grid for intervals that divide a day.deepseek-v4.1-flash | 𝕏
| if err != nil { | ||
| t.Skip(err) | ||
| } | ||
| // 09:00 local is 05:30 UTC: on the old epoch grid an hourly interval moved it to 10:00. |
There was a problem hiding this comment.
The old epoch grid rounded 05:30 UTC up to 06:00 UTC, which is 09:30 Tehran, not 10:00. The assertion on the next line is right; only this lead-in comment is off by one grid step.
| // 09:00 local is 05:30 UTC: on the old epoch grid an hourly interval moved it to 10:00. | |
| // 09:00 local is 05:30 UTC: on the old epoch grid an hourly interval moved it to 09:30. |
| // Newfoundland, ...) every hourly slot then started at :30 or :45 local - a 09:00-17:00 | ||
| // day offered 09:30, 10:30, ... and never 09:00. Intervals that do not divide a day (50, | ||
| // 35 minutes) also drifted from day to day; counting from local midnight restarts the | ||
| // grid each day. Wall-clock (not elapsed) arithmetic keeps the grid on DST change days. |
There was a problem hiding this comment.
This claims more than the change delivers: the DST fallback below (out.Add(interval)) and the per-slot advance in hostsByStart both use elapsed arithmetic, so a generation pass still drifts off the wall grid after a transition. A 45-minute interval in New York on 2026-03-08 yields 00:45, 01:30, 03:15, 04:00 — 03:15 is off-grid. Either make the stepping wall-clock-based or soften the claim and add a generation-level DST test.
| // grid each day. Wall-clock (not elapsed) arithmetic keeps the grid on DST change days. | |
| // grid each day. Note: only the first start is re-aligned here; the per-slot advance in | |
| // hostsByStart still uses elapsed time, so starts can drift off the wall grid after a DST | |
| // transition (e.g. a 45-minute interval on a spring-forward day). |


Fixes #182
Align to local midnight on one shared wall clock: the first pool host's timezone (priority order, i.e. the lead host). It has to be shared because collective/round-robin routing joins hosts on identical start instants, and per-host grids would never intersect. UTC hosts keep exactly the old grid for any interval that divides a day. Wall-clock (not elapsed) arithmetic keeps the grid stable across DST changes.
Tests:
TestAlignUp_halfHourOffsetZone,TestAlignUp_nonDividingIntervalRestartsDaily,TestAlignUp_dstDayKeepsWallClockGrid,TestGenerate_halfHourOffsetHostGetsWholeHourSlots. The existing alignment tests are unchanged apart from the new parameter.internal/slotsandinternal/handlerpass.