Skip to content

fix(slots): align slot starts to local wall clock, not the UTC epoch - #183

Merged
shockalotti merged 1 commit into
Calnode:mainfrom
MohammadHadi2031:fix/slots-local-alignment
Oct 29, 2026
Merged

shockalotti merged 1 commit into
Calnode:mainfrom
MohammadHadi2031:fix/slots-local-alignment

Conversation

@MohammadHadi2031

Copy link
Copy Markdown
Contributor

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/slots and internal/handler pass.

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>
Copilot AI balanced review requested due to automatic review settings October 28, 2026 19:27

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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)
Comment on lines +417 to +419
steps := wall/secs + 1
y, m, d := lt.Date()
out := time.Date(y, m, d, 0, 0, int(steps*secs), 0, loc)
Comment on lines +419 to +421
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)

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ No behavioral defects found in the new alignment logic — a few comment and doc-accuracy notes inline.

Reviewed changes

  • Local-midnight alignment — alignUp now rounds to the next interval multiple counted from local midnight on a supplied location instead of the Unix epoch.
  • Shared grid — newParams takes that location from the first pool host and hostsByStart uses 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.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using 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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
// 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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
// 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).

@shockalotti
shockalotti merged commit b2857fa into Calnode:main Oct 29, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Hourly slots start at :30 for hosts in UTC+3:30 / +5:30 / +5:45 (Tehran, India, Nepal, Adelaide, Newfoundland)

3 participants