# Changelog 1.20

Industry: Core

Release notes of `@northguild/gmt` 1.20.0, newest first, built from [`packages/gmt/CHANGELOG.md`](https://github.com/northguild/gmt/blob/main/packages/gmt/CHANGELOG.md). Back to [Changelog](/gmt/changelog/).

## @northguild/gmt

### 1.20.0

Released 2026-10-22

#### Minor Changes

- 8871bc6: Add `classifyStoredZoned`, which says why a stored zoned time no longer resolves (Story CORE-83). It is in the new `@northguild/gmt/zoned/classify` subpath, and the root and `@northguild/gmt/zoned` export it too.
  
  Apps store a future event as an RFC 9557 string with both an offset and a zone, such as `2016-12-01T09:00:00+02:00[Europe/Istanbul]`. When the zone's rules change after the string is written, the offset and the zone can disagree, or the local time can land in a new gap or overlap. `toOffsetInstant` returns `null` for such a string and does not say why. `classifyStoredZoned` names the cause and returns every reading, so your code chooses one.
  
  ```typescript
  import { classifyStoredZoned } from "@northguild/gmt/zoned/classify";
  
  classifyStoredZoned("2016-12-01T09:00:00+02:00[Europe/Istanbul]");
  // { kind: "offsetMismatch", storedOffset: "+02:00", zoneOffset: "+03:00",
  //   atStoredOffset: "2016-12-01T07:00:00Z", atZoneOffset: "2016-12-01T06:00:00Z" }
  
  classifyStoredZoned("2026-03-29T01:30:00+00:00[Europe/London]");
  // { kind: "nonexistent", earlier: "2026-03-29T00:30:00Z",
  //   later: "2026-03-29T01:30:00Z", atStoredOffset: "2026-03-29T01:30:00Z" }
  
  classifyStoredZoned("2026-03-29T01:30:00[Europe/London]"); // null (no offset)
  ```
  
  The result has one of five kinds: `valid`, `validInOverlap`, `offsetMismatch`, `ambiguous` and `nonexistent`. Every kind carries `atStoredOffset`, the instant that Temporal's `offset: "use"` gives. From the returned fields you can reproduce each of Temporal's four `offset` options. The function returns `null` for a string that lacks an offset or a zone, names an unknown zone, or uses a calendar other than `iso8601`.
  
  The answer depends on the time zone rules of the host, so the same string can be `valid` on one runtime and `offsetMismatch` on another. On Node, `process.versions.tz` names the tzdb release. A string ending in `Z` before the zone is always `valid`, as the Temporal specification reads it.
  
  The `StoredZonedClassification` type is exported from `@northguild/gmt`. The docs add the Stored Time Audit tool at `/tools/stored-time-audit/` and a section in the offset-instants guide.
- f939505: Add the `timescale/` namespace for leap seconds and TAI, and the `gnss/` namespace for the time scales of six satellite navigation systems (Stories MAR-16 and SPA-48). `getFiscalPeriod` and `getQuarter` now take the 53rd-week placement and the fiscal year label from the caller. Three changes break existing code, and **Breaking changes** covers each: `isLeapSecond` in `plain/` is renamed `hasSecond60`, a fiscal calendar needs two new fields, and the hours-of-work functions move from `@northguild/gmt/duty` to `@northguild/gmt/workforce`.
  
  UTC has leap seconds. TAI and most satellite time scales do not. So the offset between UTC and a satellite clock is not a constant: it grew by one second with each of the 27 leap seconds inserted since 1972. A receiver's week number also wraps, so one week number names several dates decades apart. The new functions take every offset from the IERS leap-second table built into GMT, never from a literal.
  
  ```typescript
  import {
    fromTAI,
    gnssToUtc,
    gnssWeekToUtc,
    isLeapSecond,
    leapSecondsBetween,
    nextLeapSecond,
    rinexWeekToUtc,
    taiMinusUtc,
    toTAI,
    utcToGnss,
    utcToGnssWeek,
    utcToRinexWeek,
  } from "@northguild/gmt";
  
  // The leap-second table.
  taiMinusUtc("2024-01-01T00:00:00Z"); // 37
  taiMinusUtc("2016-01-01T00:00:00Z"); // 36
  taiMinusUtc("1971-01-01T00:00:00Z"); // null (before 1972)
  leapSecondsBetween("2000-01-01T00:00:00Z", "2024-01-01T00:00:00Z"); // 5
  nextLeapSecond("2016-01-01T00:00:00Z"); // "2016-12-31T23:59:60Z"
  nextLeapSecond("2024-01-01T00:00:00Z"); // "" (there are no more)
  isLeapSecond("2016-12-31T23:59:60Z"); // true
  isLeapSecond("2024-12-31T23:59:60Z"); // false (well-formed, but no leap second that day)
  
  // TAI.
  toTAI("2026-01-01T00:00:00Z"); // "2026-01-01T00:00:37 TAI"
  toTAI("2016-12-31T23:59:60.5Z"); // "2017-01-01T00:00:36.5 TAI"
  fromTAI("2017-01-01T00:00:36 TAI"); // "2016-12-31T23:59:60Z"
  
  // Six satellite time scales, one pair of functions for all of them.
  utcToGnss("GPS", "1980-01-06T00:00:00Z"); // "1980-01-06T00:00:00 GPS" (0 s at the GPS epoch)
  utcToGnss("GPS", "2024-01-01T00:00:00Z"); // "2024-01-01T00:00:18 GPS"
  utcToGnss("BDT", "2024-01-01T00:00:00Z"); // "2024-01-01T00:00:04 BDT"
  utcToGnss("GAL", "1999-08-22T00:00:00Z"); // "1999-08-22T00:00:13 GAL"
  utcToGnss("GLO", "2016-12-31T23:59:60Z"); // "2016-12-31T23:59:60 GLO" (UTC's own clock)
  gnssToUtc("GPS", "2017-01-01T00:00:17 GPS"); // "2016-12-31T23:59:60Z"
  
  // A broadcast week: name the counter and the era.
  gnssWeekToUtc("GPS-LNAV", 100, 0, 0); // "1981-12-05T23:59:59Z"
  gnssWeekToUtc("GPS-LNAV", 100, 0, 1); // "2001-07-21T23:59:47Z" (era 1: 1024 GPS weeks later)
  gnssWeekToUtc("GPS-LNAV", 1020, 0, { notBefore: "2019-04-07T00:00:00Z" }); // "2038-10-23T23:59:42Z"
  utcToGnssWeek("GPS-LNAV", "2019-04-07T00:00:00Z"); // { week: 0, timeOfWeekSeconds: 18, era: 2 }
  utcToGnssWeek("GAL", "2019-04-07T00:00:00Z"); // { week: 1024, timeOfWeekSeconds: 18, era: 0 }
  
  // A RINEX navigation-file week never wraps.
  rinexWeekToUtc("IRN", 2295, 86418); // "2024-01-01T00:00:00Z"
  utcToRinexWeek("BDT", "2021-07-05T21:59:56Z"); // { week: 809, timeOfWeekSeconds: 165600 }
  ```
  
  - **`timescale/` holds the IERS leap-second table as a closed record.** The table runs to the last insertion, 2016-12-31, and is current through IERS Bulletin C 72 (6 July 2026). The CGPM decided in 2026 that UTC becomes continuous on 20 May 2027, so TAI − UTC stays 37 s for every later date. No function takes a table argument. A weekly check in this repository compares the table with the IERS file.
  - **`taiMinusUtc`, `leapSecondsBetween` and `nextLeapSecond` read the table.** Before 1972-01-01, TAI − UTC was fractional, so each returns the sentinel there instead of a whole number. `leapSecondsBetween` is signed, and counts a leap second when its second starts, at `23:59:60.000`, inside `[start, end)`.
  - **`isLeapSecond` is a table lookup.** It is true for the 27 inserted seconds only, in any offset spelling. A smeared clock never reads `23:59:60`, so GMT cannot detect smearing. For the syntax test alone, use `hasSecond60`.
  - **The `timescale/` and `gnss/` functions accept a listed second 60.** `"2016-12-31T23:59:60Z"` is a real instant to them, and a second 60 on any other day returns the sentinel. Every other GMT function still rejects a second of 60.
  - **`toTAI` and `fromTAI` convert between UTC and a TAI string**, `YYYY-MM-DDTHH:MM:SS[.fraction] TAI`. The token is the FITS 4.0 time-scale name.
  - **`gnss/` treats six systems as peers:** GPS, Galileo, BeiDou, QZSS, GLONASS and NavIC, named by their RINEX 4.02 time-system tokens `GPS`, `GAL`, `BDT`, `QZS`, `GLO` and `IRN`. No system is a default, and none has functions of its own.
  - **`utcToGnss` and `gnssToUtc` convert between UTC and a system's time-scale string**, such as `"2024-01-01T00:00:18 GPS"`. GPS, Galileo, QZSS and NavIC time run 19 s behind TAI, and BeiDou time 33 s. `GLO` is GLONASS time as RINEX reports it: UTC's own hours, leap seconds included, not UTC + 3 h. Each system returns the sentinel before its own epoch. The offsets are nominal: the nanosecond corrections a satellite broadcasts are not applied.
  - **`gnssWeekToUtc` and `utcToGnssWeek` read a broadcast week by its counter.** Each `GnssWeekCounter` has one modulus. `"GPS-LNAV"`, `"QZS-LNAV"` and `"IRN-LNAV"` wrap every 1024 weeks, `"GAL"` every 4096, and `"GPS-CNAV"`, `"QZS-CNAV"`, `"BDT"` and `"IRN-L1NV"` every 8192. GLONASS has no week counter.
  - **`rolloverEra` is required**, because a week number alone cannot say which pass of the counter it belongs to. Pass an integer era for stored data. Pass `"rolling"` for live receiver output: it picks the era within half a counter period of today, so it reads the clock. Pass `{ notBefore }` to take the earliest match at or after an instant you state, such as a receiver's firmware build date. It gives the same answer in any year.
  - **`rinexWeekToUtc` and `utcToRinexWeek` read the week of a RINEX navigation record.** That week is a continuous count that never wraps, from 1980 for GPS, Galileo, QZSS and NavIC, and from 2006 for BeiDou, so it has no era. A RINEX NavIC week read as a broadcast NavIC week is 1024 weeks off, which is why the two kinds of week have separate functions.
  - Also exported: the `GnssSystem`, `GnssWeekCounter`, `RolloverEra`, `GnssWeek`, `RinexWeekSystem` and `RinexWeek` types, and the `@northguild/gmt/timescale`, `/timescale/calculate`, `/timescale/convert`, `/timescale/validate`, `@northguild/gmt/gnss` and `/gnss/convert` subpaths.
  
  **Fiscal calendars.** IFRS 18 ¶29 (formerly IAS 1 ¶37) does not preclude a reporting period of 52 weeks, and no international standard says where a 53rd week goes or which calendar year names the fiscal year. Published calendars disagree on both. The NRF 4-5-4 calendar (US) adds the week to the last period and names the year by the year it starts in. The ONS retail trading periods (UK) add it to the first period and name the year by the calendar year that holds most of it. IFRS 18 ¶27(c) (formerly IAS 1 ¶51(c)) lets a reporting period be identified by the date it ends. IFRS 18 replaces IAS 1 for reporting periods beginning on or after 2027-01-01. So the caller now states both choices, and there is no default.
  
  ```typescript
  import { getFiscalPeriod, getQuarter, isValidFiscalCalendar } from "@northguild/gmt";
  
  const ons = { pattern: "4-4-5", yearEndsOn: "2022-12-31", extraWeek: "firstPeriod", yearLabel: "majorityYear" } as const;
  getFiscalPeriod("2024-12-29", ons); // { year: 2025, period: 1, week: 1 } (ONS 2025 opens in December 2024)
  getFiscalPeriod("2025-02-01", ons); // { year: 2025, period: 1, week: 5 } (a five-week January)
  
  const nrf = { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "endYear" } as const;
  getFiscalPeriod("2024-01-28", nrf); // { year: 2024, period: 12, week: 53 } (week 53, named by the year it ends in)
  
  getQuarter("2023-10-15", { fiscalYearStartMonth: 7, yearLabel: "majorityYear" }); // { year: 2023, quarter: 2 }
  isValidFiscalCalendar({ pattern: "4-5-4", yearEndsOn: "2026-01-31" }); // false (no extraWeek or yearLabel)
  ```
  
  - **`extraWeek` is the period a 53rd week is added to:** `"firstPeriod"` or `"lastPeriod"`. It has no effect in a 52-week year.
  - **`yearLabel` names the fiscal year:** `"startYear"`, `"endYear"` or `"majorityYear"`, the calendar year holding the most of its days. It is a field of `FiscalCalendar` and an option of `getQuarter`. When two calendar years hold 182 days each, `"majorityYear"` gives the end year, because IFRS 18 ¶27(c) (formerly IAS 1 ¶51(c)) lets a period be identified by its end date. For `getQuarter`, start months 1 to 7 put the most days in the start year and 8 to 12 in the end year, so a month-based fiscal year never ties.
  - **`year` is still not a unique key for every year end.** A 364- or 371-day year drifts against the calendar, so each label rule has a few year ends where two fiscal years share a label. The JSDoc lists them. If your year end is one of them, key on the fiscal year's start date.
  - **New validators.** `isValidFiscalCalendar` checks a whole calendar, so you can tell a bad calendar from a date `getFiscalPeriod` cannot place. `isValidFiscalExtraWeek` and `isValidFiscalYearLabel` narrow a string read from configuration.
  - **Fix: `getFiscalPeriod` returns a value for every date Temporal accepts.** 1.19 returned `null` near Temporal's first and last dates when the fiscal year ran past that limit. `getFiscalPeriod("-271821-04-19", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" })` now returns `{ year: -271821, period: 3, week: 12 }`.
  - **Fix: an array is not a fiscal calendar.** 1.19 read an array with `pattern` and `yearEndsOn` set as properties as a calendar. `getFiscalPeriod` now returns `null` for any array, and `isValidFiscalCalendar` returns `false`, as `isValidBusinessCalendar` does.
  - Also exported: the `FiscalExtraWeek` and `FiscalYearLabel` types.
  
  **Other changes.**
  
  - **The pattern parsers read names in `"en"` when no locale is given**, not `"en-US"`. This covers `parseDateWithPattern`, `parseDateTimeWithPattern` and `parseTimeWithPattern`. CLDR gives `"en"` the same month, weekday, era and AM/PM names as `"en-US"`, so every result is unchanged.
  - **The NRF 4-5-4 calendar is described as one published example (US), not the retail standard.** The JSDoc quotes NRF's current wording: a 53rd week is added when "there are four or more days left in January".
  - **`isBusinessDay`'s fixed Monday-to-Friday week is described correctly.** ISO 8601 defines no weekend. Saturday and Sunday off is CLDR's world default.
  - **The JSDoc examples use zones and locales from several countries**, such as London, Tokyo, Sydney, São Paulo, Johannesburg and Kolkata. Only the zone and its offset changed in each example, and every changed result was run again.
  - **Each industry layer has its own TanStack Intent skill:** `gmt-gnss`, `gmt-transport`, `gmt-intermodal` and `gmt-workforce`. Their functions have moved out of the topic skills, so `gmt-integration`, `gmt-timezone`, `gmt-arithmetic` and `gmt-basics` now cover Core alone. `timescale/` is Core, so its leap-second table stays in `gmt-integration`. If you installed a skill with `--map`, map the new industry skills you need.
  - **The notes for readers moving from date-fns are corrected.** date-fns numbers Sunday 0, so `nextDay(value, 0)` becomes `nextWeekday(value, 7)`, and `previousDay` maps the same way. date-fns starts a week on Sunday by default, so `isSameWeek(a, b)` becomes `areDatesEqualBy(a, b, "week", { weekStartsOn: "sunday" })`. Rules that cited another library now cite ECMA-402, UTS #35 or Temporal.
  
  ##### Breaking changes
  
  **1. `isLeapSecond` in `plain/` is renamed `hasSecond60`.** The name `isLeapSecond` now belongs to the table lookup in `timescale/`. An import from `@northguild/gmt/plain` or `@northguild/gmt/plain/validate` fails to compile. An import from `@northguild/gmt` still compiles and now runs the lookup, so its result can change with no type error:
  
  | Call | 1.19 | 1.20 |
  | --- | --- | --- |
  | `isLeapSecond("2024-06-15T12:34:60Z")` | `true` | `false` (no leap second can occur at 12:34) |
  | `isLeapSecond("2024-12-31T23:59:60Z")` | `true` | `false` (no leap second that day) |
  | `isLeapSecond("23:59:60")` | `true` | `false` (not an instant) |
  | `isLeapSecond("2016-12-31T23:59:60Z")` | `true` | `true` |
  
  ```typescript
  // 1.19: the syntax test
  import { isLeapSecond } from "@northguild/gmt/plain/validate";
  isLeapSecond("2024-06-15T12:34:60Z"); // true
  
  // 1.20: the same test, renamed
  import { hasSecond60 } from "@northguild/gmt/plain/validate";
  hasSecond60("2024-06-15T12:34:60Z"); // true
  
  // 1.20: whether a leap second was inserted
  import { isLeapSecond } from "@northguild/gmt/timescale";
  isLeapSecond("2024-06-15T12:34:60Z"); // false
  isLeapSecond("2016-12-31T23:59:60Z"); // true
  ```
  
  Migration: to keep the 1.19 result, rename the call and its import to `hasSecond60`. Its arguments and results are the same. To ask whether a second 60 is a real leap second, use `isLeapSecond`.
  
  **2. A fiscal calendar needs `extraWeek` and `yearLabel`, and fiscal `getQuarter` options need `yearLabel`.**
  
  | Call that compiled in 1.19 | 1.20 | Migration |
  | --- | --- | --- |
  | `getFiscalPeriod(value, { pattern, yearEndsOn })` | a type error, and `null` at run time | add `extraWeek: "lastPeriod", yearLabel: "startYear"` |
  | `getQuarter(value, { fiscalYearStartMonth })` | a type error, and `null` at run time | add `yearLabel: "startYear"` |
  | `getQuarter(value, {})` | a type error, and `null` at run time | drop the options to get calendar quarters |
  
  ```typescript
  // 1.19
  getFiscalPeriod("2024-01-28", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }); // { year: 2023, period: 12, week: 53 }
  // 1.20, the same result
  getFiscalPeriod("2024-01-28", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }); // { year: 2023, period: 12, week: 53 }
  
  // 1.19
  getQuarter("2024-03-31", { fiscalYearStartMonth: 4 }); // { year: 2023, quarter: 4 }
  // 1.20, the same result
  getQuarter("2024-03-31", { fiscalYearStartMonth: 4, yearLabel: "startYear" }); // { year: 2023, quarter: 4 }
  ```
  
  Migration: each migration in the table gives exactly the 1.19 result. `fiscalYearStartMonth` no longer defaults to `1`. If you added one to `year` to label a fiscal year by the year it ends in, pass `yearLabel: "endYear"` and remove the `+ 1`. `getQuarter` with no options still returns calendar quarters.
  
  **3. The hours-of-work functions move to `@northguild/gmt/workforce`.** Hours-of-work rules serve drivers, seafarers, rail crew, flight crew and resident doctors alike, so they sit in a workforce layer of their own. The `/duty` subpaths are removed, and no alias is kept.
  
  | 1.19 | 1.20 |
  | --- | --- |
  | `@northguild/gmt/duty` | `@northguild/gmt/workforce` |
  | `@northguild/gmt/duty/calculate` | `@northguild/gmt/workforce/calculate` |
  | `@northguild/gmt/duty/validate` | `@northguild/gmt/workforce/validate` |
  
  ```typescript
  // 1.19
  import { evaluateDutyLog } from "@northguild/gmt/duty";
  import { isValidDutyLog } from "@northguild/gmt/duty/validate";
  
  // 1.20
  import { evaluateDutyLog } from "@northguild/gmt/workforce";
  import { isValidDutyLog } from "@northguild/gmt/workforce/validate";
  ```
  
  Migration: change the import path. The function names, the types, the arguments and the results are the same, and an import from `@northguild/gmt` is unchanged.

#### Patch Changes

- 57b0556: The documentation moves to https://northguild.dev/gmt/. The package `homepage`, the README and the
  agent skills link there; old `gmt-dox.northguild.workers.dev` links redirect.
- e043391: Long spans and long logs are much faster, and the business-day functions are smaller. No option or signature changes, and every function returns what it returned before, with one exception: a holiday array with its own `Symbol.iterator` is now read by index in `rollDate` and `isBusinessDay`, as `businessDaysBetween` already read it.
  
  **Speed** (Node 24, warm, before → after):
  
  | Function | Input | Before | After |
  | --- | --- | --- | --- |
  | `dutyViolations` | 365-day log | 336 ms | about 14 ms |
  | `dutyViolations` | split sleeper rule, 10 years | 10,460 ms | 194 ms |
  | `businessDaysBetween` | 480 holidays, 1 to 30 years | 3.74 ms | 0.048 ms |
  | `operatingTimeBetween` | 1 year | 62.6 ms | 0.40 ms |
  | `operatingTimeBetween` | 10 years | 444 ms | 0.67 ms (4.3 ms the first time) |
  | `addOperatingTime` | 400 hours | 12.2 ms | 0.79 ms |
  | `chargeableDays` and `freeTimeExpiry` | 10 years, `Europe/London` | 162.6 ms | 0.70 ms (4.7 ms the first time) |
  | `chargeableDays` and `freeTimeExpiry` | 10 years, working days | 218.4 ms | 0.79 ms |
  | `chargeableDays` and `freeTimeExpiry` | 10 years, `America/Port_of_Spain` | 177.7 ms | 0.59 ms |
  | `intervalCountZoned`, `intervalOverlappingDaysZoned`, `dwellTime` | 100 years, `Europe/London` | 42 to 48 ms | about 2 ms |
  | `intervalSplitAtZoned` | 1,000 points | 65.5 ms | 56.5 ms |
  | Offset-change search | 40-year span, `Asia/Kolkata` | 34.8 ms | 19.8 ms the first time, 0.06 ms after |
  | `formatDate` | `de-DE` | 0.073 ms | 0.0068 ms |
  | `getLocaleMonthNames` | one locale | 1.28 ms | 0.036 ms |
  | `cutoffSchedule` | 50 entries | 13.1 ms | 5.6 ms |
  
  The cost of the day-count and operating-hours functions no longer grows with the number of days. A 10-year span now costs a small multiple of a 1-year span.
  
  **Size** (minified / gzipped kB, one function imported):
  
  | Import | Before | After |
  | --- | --- | --- |
  | `businessDaysBetween` | 172.5 / 50.1 | 155.9 / 45.6 |
  | `addBusinessDays` | 173.6 / 50.6 | 157.0 / 46.0 |
  | `formatDate` | 155.4 / 45.2 | 156.8 / 45.7 |
  | `chargeableDays` | 197.3 / 57.8 | 196.4 / 58.5 |
  | `operatingTimeBetween` | 200.8 / 58.8 | 204.0 / 60.6 |
  | `dutyViolations` | 226.7 / 67.1 | 228.5 / 68.2 |
  | the whole package (root) | 487.1 / 127.9 | 500.9 / 133.6 |
  
  `@js-temporal/polyfill` alone is 152.5 / 44.2 kB, so it is most of every figure. The business-day functions are smaller because checking a time zone no longer loads the Temporal workarounds. `operatingTimeBetween`, `dutyViolations` and the root are a little larger, and `chargeableDays` a little larger gzipped: they hold the new methods and keep the day-by-day one for spans near the limits of Temporal's range. `formatDate` is 1.4 kB larger for its formatter cache.
- 0645a85: `formatCalendar` reads a `timeStyle` given as an object, such as `new String("long")`, as the plain string. Before, it printed the UTC zone name it uses internally, as in "tomorrow at 2:30:00 PM UTC".
- 0645a85: `roundZoned` and `roundUnix` now round to the day as Temporal specifies when a clock change makes a date start twice, such as America/Goose_Bay on 6 November 2010.
- 8871bc6: Fix a zoned value ending in `Z` and carrying a calendar annotation, such as `+275760-09-12T23:00:00Z[America/Sao_Paulo][u-ca=hebrew]`, being refused near the end of the supported range. `addZoned` returned `""` for it, as did the other functions that read the calendar first, because GMT read the time of day in the zone instead of taking the instant the `Z` names, which is how the Temporal specification reads it. They now return the result.
