Time zone research

How We Verify a Time Zone Conversion

Time-zone conversions are easy to state and hard to audit, because the correct answer depends on a rule table that changes. The only defensible approach is to derive every value from a maintained database at the moment it is needed and to make the derivation inspectable. This research documents exactly how our evidence file is produced, so the method can be criticised rather than accepted.

By BeanNest Studio Reviewed September 20, 2026

What this guide helps you decide

A time-zone tool reports a conversion. How can that value be independently checked rather than trusted?

This research documents the verification method used for this repository's time-zone evidence. It does not evaluate any third-party tool and does not claim the method covers every edge case.

Try it on the anchor product: BeanNest Time /, BeanNest Time /meeting-planner/, BeanNest Time /converter/.

Sampling the database, not remembering it

The generator reads the offset for a zone by formatting a known instant in that zone and comparing the result to the same instant in UTC. It never contains a hard-coded offset table. Sampling hourly across the year is sufficient because transitions occur on whole or half hours.

Detecting transitions by comparison

Instead of looking up transition dates, the generator samples every hour of the year and records a transition whenever the computed offset differs from the previous sample. That produces transition count, direction, and delta without relying on a published date list.

Modelling the recurring meeting

The meeting model steps a fifty-two week sequence from a fixed local wall-clock time and records the offset difference at each occurrence. The output is the distinct shift values and their spread, which is what makes drift measurable rather than described.

What the method captures well

It captures daylight saving start and end, southern hemisphere timing, non-hour offsets, and zones that never transition. Our evidence set demonstrates all four: six zones with two transitions each, Sydney with the southern pattern, Kolkata and Kathmandu with non-hour offsets, and three zones with zero transitions.

Where the method is limited

Hourly sampling detects transitions on whole or half hours, which covers current IANA data. It does not reconstruct historical rules, and it inherits whatever version of the time-zone database the runtime ships. A future rule change adopted by the database will be reflected only when the evidence is regenerated.

Why the method is published

A conversion result that cannot be reproduced is an assertion. The generator and its output are both in this repository, so any number in these guides can be re-derived. That is the standard, and it is the reason the evidence files are cited by path in every time guide here.

Why derivation beats a lookup table

A hand-maintained offset table goes stale when a jurisdiction changes its rules, and the staleness is invisible until a conversion is wrong. Deriving each value from a maintained database at the moment it is needed means the tool inherits the database's accuracy rather than adding its own error. The cost is a computation per lookup, which is negligible for scheduling work.

Why transitions are detected rather than listed

Detecting a transition by comparing consecutive samples avoids depending on a published date list that might not match the runtime's database. The generator records the instant, the offset before, the offset after, and the delta, all derived from the same source. That makes the evidence internally consistent: the offsets and the transitions cannot disagree, because the transitions are computed from the offsets.

What the fifty-two week model adds

Listing transitions tells a reader when offsets change. Modelling a weekly meeting tells them what the change does to a real schedule, which is the question a user actually has. The model steps from a fixed local wall-clock time and records the offset difference at each occurrence, so the output is a list of distinct shift values and their spread rather than a table of dates.

Where the model is deliberately simple

The model holds the meeting at a fixed local time in the reference zone, which is one of several plausible recurrence rules. A meeting pinned to a fixed instant instead would not drift for the anchor but would drift for everyone else. The guides state the modelled rule explicitly so a reader can judge whether it matches their case rather than assuming the output applies universally.

Why publishing the method is part of the evidence

A conversion result that cannot be reproduced is an assertion. Both the generator and its output live in this repository, so every figure in the time guides can be re-derived rather than taken on trust. That is the same standard the other clusters apply, and it is why each evidence file is cited by path.

How to reproduce the evidence

Run the generator with a year argument and an output path, then read the resulting file. Every zone entry carries its January and July offsets, its transition count, and each transition with its instants and offsets. Every recurring-meeting entry carries the distinct shift values and the spread. The whole file is derived, so a rerun reproduces it exactly.

What a reader should check before trusting a number

Confirm that the year in the file matches the year being discussed, that the zone set covers the zones in question, and that the model's anchoring rule matches the schedule being analysed. Those three checks catch the cases where a correct measurement does not apply to the reader's situation, which is a different failure from an incorrect measurement.

Why unknown and zero are recorded separately

A zone with no transitions reports a zero transition count, which is a measurement rather than missing data. Distinguishing a measured zero from an unknown value matters because the two support different conclusions: a measured zero means the zone does not drift, while an unknown value means nothing can be said. The evidence file reports counts, so a zero is unambiguous.

How the method would extend

Adding zones is a matter of adding entries to the generator's list, and adding a different recurrence rule would mean modelling a fixed instant instead of a fixed local time. Both extensions would produce new evidence rather than changing the existing file, which keeps previously published figures valid for the year and set they describe.

How the method handles a zone that changes rules

Because every offset is read from the database at sampling time, a rule change adopted by the database appears in the next run without any edit to the generator. The method therefore stays current as long as it is rerun, and the evidence file records the year it describes so a reader knows which rules it reflects.

What the method cannot establish

It cannot tell a reader what an organisation's calendar software will do, because that depends on the software's own time-zone handling. It establishes what the rules say, which is the input to any correct behaviour. The distinction keeps the guide from claiming an outcome it does not control.

First-party evidence and provenance

How we checked this

We derived every offset and transition from the runtime's own time-zone database by sampling the zone offset hourly across the calendar year, then modelled a weekly meeting pinned to a fixed local wall-clock time in a reference zone. The generator is in this repository and the evidence file is its output. For this guide we documented the generator's sampling and comparison procedure itself, including the hourly sampling interval and the whole-or-half-hour assumption it depends on.

Method: We derived every offset and transition from the runtime's own time-zone database by sampling the zone offset hourly across the calendar year, then modelled a weekly meeting pinned to a fixed local wall-clock time in a reference zone. The generator is in this repository and the evidence file is its output.
Environment: Node.js on a desktop workstation, using the bundled IANA time-zone data. No network call, no hard-coded offset table, and no user data.
Captured: September 20, 2026
Reviewed by: BeanNest Studio

Repository evidence artifacts:

tools/research-evidence/time/transitions-2026.json
tools/research-evidence/time/README.md