Methodology & Data Sources

All local-time and offset values are computed with Luxon, which reads the IANA Time Zone Database (tzdb) through the platform's bundled ICU/Intl data. Each city carries an explicit IANA zone identifier in our public dataset (/data/cities.json) — offsets are never hand-written.

tzdb rule changes (abolitions, reinstatements, date moves) reach these pages when the platform's tzdb bundle updates. We do not maintain our own copy of historical tzdb archives, so past-year rule archaeology is out of scope unless a named source covers it.

Precision. Offsets and transition instants are resolved to the minute — the practical granularity of civil time. We do not claim millisecond accuracy.

Public-holiday rules live in src/data/holidays.ts. Every rule that ships on a public page carries a named legal source alongside it — for example the US Office of Personnel Management federal holiday schedule (5 U.S.C. §6103) and the UK Banking and Financial Dealings Act 1971 with the Christmas Day and Bank Holidays Order 1978.

Each country is graded by coverage level:

• complete — every gazetted holiday in the stated scope is encoded with a named source (currently GB, DE, FR, IE, CA, US, AU).
• partial — useful status hints only; the page carries a visible disclaimer and is excluded from indexing.
• unavailable — no encoded calendar.

Substitute days. Fixed holidays falling on a weekend are observed on a substitute weekday according to each country's rule (for example, next-Monday observation in the UK). Easter-based dates use the anonymous Gregorian computus algorithm.

Scope honesty. Coverage is stated per country and scope — GB is England & Wales bank holidays, US is the federal (OPM) schedule, AU is nationally uniform days. State-variable or region-specific days outside the stated scope are not encoded.

Clock changes are probed, not hand-written (src/lib/dst-country.ts). For each IANA zone we read the offset at day granularity, then binary-search the first minute where the offset changes. Every row on a /dst page is derived from the IANA tzdb via this probe at request time.

Precision limits. Resolution is one minute. Transition instants are exact when the tzdb encodes them; regions with pending or unratified legislation are only reflected once the tzdb ships the change.

Sunrise/sunset and daylight values use the SunCalclibrary (MIT-licensed, vendored under src/lib/vendor/). City pages and the sun pages call the same wrapper over the same library, so they can never disagree. Polar edge cases (midnight sun, polar night) follow a NaN → null convention and render as absent rather than as a fabricated time.

Monthly grids sample one representative day per month at mid-month local noon, producing durable, cacheable copy with no render-time values.

The recurring planner evaluates candidate instants in each participant's IANA zone. It checks editable workdays, preferred and acceptable hours, sleep/off-day penalties, manual unavailable dates, holiday coverage, and DST offset changes. A recurring rule is bounded to at most 52 occurrences and a 366-day search horizon by default; wall-time anchoring is kept explicit so a weekly meeting does not silently become a different local hour after a DST change.

Burden is intentionally visible rather than hidden in a single “best time” claim. A candidate adds 1 for missing preferred hours, 1 for missing acceptable hours, 2 for a non-workday, 2 for sleep hours, 2 for a supported holiday conflict, and 4 for a manual unavailability conflict. Candidate scores also account for DST drift and the spread between participant burdens. The fairness objective uses a 55% fairness weight; convenience, DST stability, and workability have explicit mode-dependent weights.

Rotation is offered only when it improves burden spread without making total burden materially worse. The rejection threshold is more than 15% above the fixed schedule (with a small absolute guard), so “fairness” cannot justify a substantially worse series. This is a heuristic, not a labor-policy or universal optimum; people should review the occurrence-level reasons before sending an invite.

Holiday projection is deliberately limited. Supported country rules can flag known dates, but regional closures, one-off government announcements, lunar sightings, and future rule changes are not inferred. Add local unavailable dates when those distinctions matter.

The availability parser turns entered prose into a typed intermediate record with timezone candidates, windows, exclusions, warnings, a schema version, and confirmation: pending. Ambiguous zones, date-only windows, open-ended ranges, and unparsed lines remain warnings or errors; the parser does not silently turn them into planner constraints. A user must confirm the resolved timezone and windows before conversion to planner participants.

Model-assisted parsing is currently hard-off: there are no vendor calls, no model, no timeout, and no cost ceiling to configure. Entered availability is not sent to an external parser by this feature. If model assistance is ever proposed, it requires a separate privacy review and ADR; confirmation and the input-size/participant/window limits remain part of the contract.

The clock check compares the device timestamp captured on response with the server's UTC timestamp. It estimates offset from that pair and displays an honest one-sided uncertainty of half the measured round-trip time (±RTT/2), assuming symmetric network travel. CDN, TLS, and asymmetric-network jitter mean this is seconds-level guidance, not NTP and never millisecond synchronization.

The verdict is operational guidance: a few seconds is usually fine for meetings, drift that reaches the small tolerance used by time-based one-time passwords deserves a resync, and a minute or more warrants checking automatic time and timezone settings. It cannot prove the device's NTP health, identify every network asymmetry, or replace the operating system's time service.

• Moon-sighting holidays. Dates that depend on lunar sighting (e.g. Eid) cannot be computed exactly in advance; approximate rules are flagged and never presented as fixed dates.
• Matariki. The New Zealand lunisolar holiday is currently excluded from our holiday calendar.
• Coverage scope. Holiday data reflects the stated statutory scope per country; regional or state-specific days outside it are not encoded.
• Rule-change archaeology. We do not reconstruct historical tzdb rules beyond the bundled current data; historical claims on editorial pages cite named sources.
• Device-time accuracy. Times shown are computed from server data; a user's own clock may drift independently (see the clock-check tool's error band).