@northguild/gmt 1.19.0 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@northguild/gmt",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "Temporal-based date and time utilities with timezone support and polyfill integration",
   "keywords": [
     "date",
@@ -11,7 +11,7 @@
     "time",
     "timezone"
   ],
-  "homepage": "https://gmt-dox.northguild.workers.dev",
+  "homepage": "https://northguild.dev/gmt/",
   "bugs": {
     "url": "https://github.com/northguild/gmt/issues"
   },
@@ -81,14 +81,11 @@
       "duration/validate": [
         "./dist/duration/validate/index.d.ts"
       ],
-      "duty": [
-        "./dist/duty/index.d.ts"
+      "gnss": [
+        "./dist/gnss/index.d.ts"
       ],
-      "duty/calculate": [
-        "./dist/duty/calculate/index.d.ts"
-      ],
-      "duty/validate": [
-        "./dist/duty/validate/index.d.ts"
+      "gnss/convert": [
+        "./dist/gnss/convert/index.d.ts"
       ],
       "instant": [
         "./dist/instant/index.d.ts"
@@ -192,6 +189,18 @@
       "span/validate": [
         "./dist/span/validate/index.d.ts"
       ],
+      "timescale": [
+        "./dist/timescale/index.d.ts"
+      ],
+      "timescale/calculate": [
+        "./dist/timescale/calculate/index.d.ts"
+      ],
+      "timescale/convert": [
+        "./dist/timescale/convert/index.d.ts"
+      ],
+      "timescale/validate": [
+        "./dist/timescale/validate/index.d.ts"
+      ],
       "transport": [
         "./dist/transport/index.d.ts"
       ],
@@ -264,6 +273,15 @@
       "utc/validate": [
         "./dist/utc/validate/index.d.ts"
       ],
+      "workforce": [
+        "./dist/workforce/index.d.ts"
+      ],
+      "workforce/calculate": [
+        "./dist/workforce/calculate/index.d.ts"
+      ],
+      "workforce/validate": [
+        "./dist/workforce/validate/index.d.ts"
+      ],
       "zoned": [
         "./dist/zoned/index.d.ts"
       ],
@@ -273,6 +291,9 @@
       "zoned/chop": [
         "./dist/zoned/chop/index.d.ts"
       ],
+      "zoned/classify": [
+        "./dist/zoned/classify/index.d.ts"
+      ],
       "zoned/compare": [
         "./dist/zoned/compare/index.d.ts"
       ],
@@ -352,17 +373,13 @@
       "types": "./dist/duration/validate/index.d.ts",
       "default": "./dist/duration/validate/index.js"
     },
-    "./duty": {
-      "types": "./dist/duty/index.d.ts",
-      "default": "./dist/duty/index.js"
+    "./gnss": {
+      "types": "./dist/gnss/index.d.ts",
+      "default": "./dist/gnss/index.js"
     },
-    "./duty/calculate": {
-      "types": "./dist/duty/calculate/index.d.ts",
-      "default": "./dist/duty/calculate/index.js"
-    },
-    "./duty/validate": {
-      "types": "./dist/duty/validate/index.d.ts",
-      "default": "./dist/duty/validate/index.js"
+    "./gnss/convert": {
+      "types": "./dist/gnss/convert/index.d.ts",
+      "default": "./dist/gnss/convert/index.js"
     },
     "./instant": {
       "types": "./dist/instant/index.d.ts",
@@ -500,6 +517,22 @@
       "types": "./dist/span/validate/index.d.ts",
       "default": "./dist/span/validate/index.js"
     },
+    "./timescale": {
+      "types": "./dist/timescale/index.d.ts",
+      "default": "./dist/timescale/index.js"
+    },
+    "./timescale/calculate": {
+      "types": "./dist/timescale/calculate/index.d.ts",
+      "default": "./dist/timescale/calculate/index.js"
+    },
+    "./timescale/convert": {
+      "types": "./dist/timescale/convert/index.d.ts",
+      "default": "./dist/timescale/convert/index.js"
+    },
+    "./timescale/validate": {
+      "types": "./dist/timescale/validate/index.d.ts",
+      "default": "./dist/timescale/validate/index.js"
+    },
     "./transport": {
       "types": "./dist/transport/index.d.ts",
       "default": "./dist/transport/index.js"
@@ -596,6 +629,18 @@
       "types": "./dist/utc/validate/index.d.ts",
       "default": "./dist/utc/validate/index.js"
     },
+    "./workforce": {
+      "types": "./dist/workforce/index.d.ts",
+      "default": "./dist/workforce/index.js"
+    },
+    "./workforce/calculate": {
+      "types": "./dist/workforce/calculate/index.d.ts",
+      "default": "./dist/workforce/calculate/index.js"
+    },
+    "./workforce/validate": {
+      "types": "./dist/workforce/validate/index.d.ts",
+      "default": "./dist/workforce/validate/index.js"
+    },
     "./zoned": {
       "types": "./dist/zoned/index.d.ts",
       "default": "./dist/zoned/index.js"
@@ -608,6 +653,10 @@
       "types": "./dist/zoned/chop/index.d.ts",
       "default": "./dist/zoned/chop/index.js"
     },
+    "./zoned/classify": {
+      "types": "./dist/zoned/classify/index.d.ts",
+      "default": "./dist/zoned/classify/index.js"
+    },
     "./zoned/compare": {
       "types": "./dist/zoned/compare/index.d.ts",
       "default": "./dist/zoned/compare/index.js"
@@ -649,10 +698,10 @@
     "@js-temporal/polyfill": "^0.5.1"
   },
   "devDependencies": {
+    "@northguild/gmt-oxlint": "1.2.1",
     "@tanstack/intent": "^0.4.0",
     "oxfmt": "^0.62.0",
-    "oxlint": "^1.78.0",
-    "@northguild/gmt-oxlint": "1.2.1"
+    "oxlint": "^1.78.0"
   },
   "engines": {
     "node": ">=22.16.0"
@@ -663,6 +712,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
+    "bench": "vitest bench --run --config vitest.bench.config.ts",
     "lint": "oxlint",
     "format": "oxfmt"
   }

package/skills/gmt-arithmetic/SKILL.md

@@ -12,9 +12,8 @@ description: >
   subtractBusinessDays, businessDaysBetween, nextBusinessDay,
   previousBusinessDay, rollDate, mergeCalendars), overflow "constrain" month-end
   clamping, splitIntervalByUnit* anchor stepping, maxPieces limits,
-  intervalCount* matching bucketRange, RFC 9557 calendar strings, and the
-  correct-at-the-edges guarantees at the representable limits, and hours-of-work
-  rules over a duty log (evaluateDutyLog, dutyViolations, dutyDayFor).
+  intervalCount* matching bucketRange, RFC 9557 calendar strings,
+  correct-at-the-edges guarantees at the limits.
 sources:
   - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/plain-arithmetic.mdx'
   - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/durations.mdx'
@@ -35,12 +34,10 @@ sources:
   - 'northguild/gmt:packages/gmt/src/calendar/business/index.ts'
   - 'northguild/gmt:packages/gmt/src/types/business-calendar.ts'
   - 'northguild/gmt:packages/gmt/src/types/roll-convention.ts'
-  - 'northguild/gmt:packages/gmt/src/duty/index.ts'
-  - 'northguild/gmt:packages/gmt/src/types/duty.ts'
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.19.0'
+  library_version: '1.20.0'
 ---
 
 # GMT Arithmetic
@@ -61,8 +58,6 @@ and full interval set operations.
   these windows?".
 - The user is measuring elapsed time — a profile, a trace span, a sensor
   interval — and wants milliseconds or nanoseconds rather than a `Duration`.
-- The user checks hours of work against rules: driving or duty caps, rest in
-  every 24 hours, a free day in seven, a monthly record of violations.
 
 ## Core rules
 
@@ -149,6 +144,8 @@ and full interval set operations.
    "hours")` measures what the clock face did. Across a DST transition they
    differ by the size of the shift — a wall-clock day is 23, 24.5 or 25 real
    hours. Reaching for the wrong one is the most common span bug there is.
+   `spanMs` and `spanNs` do not count leap seconds: for a leap-second-exact span, convert both ends
+   with `toTAI` or add `leapSecondsBetween(start, end)` (see `gmt-integration`).
 7. **Span sentinels are `null`, not `0`.** `0` and `0n` are valid spans, so all
    three span functions return `null` on invalid input rather than a zero —
    `spanMs` also returns it past `Number.MAX_SAFE_INTEGER` milliseconds, where
@@ -236,10 +233,10 @@ and full interval set operations.
     caller-supplied — GMT bundles no holiday table on the default import path.
 
     ```typescript
-    const nyse = { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" };
-    addBusinessDays("2024-07-03", 1, nyse); // "2024-07-05" — skips the holiday
-    businessDaysBetween("2024-07-01", "2024-07-05", nyse); // 3 — start exclusive, end inclusive
-    rollDate("2024-05-31", "modifiedFollowing", nyse); // backward when forward leaves the month
+    const tokyo = { weekend: [6, 7], holidays: ["2024-05-03", "2024-05-06"], timeZone: "Asia/Tokyo" };
+    addBusinessDays("2024-05-02", 1, tokyo); // "2024-05-07" — skips both holidays and the weekend
+    businessDaysBetween("2024-05-01", "2024-05-07", tokyo); // 2 — start exclusive, end inclusive
+    rollDate("2024-08-31", "modifiedFollowing", tokyo); // "2024-08-30" — backward when forward leaves the month
     ```
 
     These are **local-date in, local-date out**: `calendar.timeZone` records the
@@ -250,43 +247,11 @@ and full interval set operations.
     survives only if it is a working day in every input, and returns `null` for an
     empty list. Narrow inputs with `isValidBusinessCalendar` /
     `isValidRollConvention`.
-13. **Hours of work are rules over a duty log, and every number is the
-    caller's.** A log is `{ status, start, end }[]` in the caller's own status
-    words, ordered and non-overlapping (`isValidDutyLog`). A rule is one of 13
-    `DutyRule` kinds (`cumulativeCap`, `elapsedWindow`, `requiredInterruption`,
-    `rollingCap`, `fixedPeriodCap`, `restRequirement`, `freePeriod`,
-    `restBeforeDuty`, `quota`, `dueBy`, `pattern`, `occurrenceCap`,
-    `usageLookback`) with no default limit; GMT names no regulation.
-    `evaluateDutyLog(log, at, rules, { timeZone, dayStartTime?, disambiguation? })`
-    reports every rule at one instant; `dutyViolations` lists each violation in a
-    range once, by its worst window, in the range it began in.
-
-    ```typescript
-    evaluateDutyLog(log, "2024-01-01T21:30:00Z", [{ label: "11 driving", kind: "cumulativeCap",
-      statuses: ["driving"], cap: "PT11H", since: { statuses: ["off"], consecutive: "PT10H" } }],
-      { timeZone: "UTC" }).violations; // [{ label: "11 driving", used: "PT11H30M", limit: "PT11H", … }]
-    ```
-
-    - `{ elapsed: "PT24H" }` slides; `{ operatorDays }`, `{ calendarDays }`,
-      `{ isoWeeks }`, `{ calendarMonths }`, `{ calendarYears }` are whole local
-      periods in `timeZone` (28 calendar days across a fall-back are 673 hours).
-    - The operator day is `dutyDayFor(instant, { timeZone, dayStartTime })`,
-      never local midnight; a rule counting `operatorDays` needs `dayStartTime`.
-    - The log is read up to `at`; unlogged time is neither work nor rest. To
-      check a roster, append the plan and set `at` to its end.
-    - A paired rest is three floors (`PairSpec`), not two integers:
-      `qualifyingRestPairs`.
-    - A count of periods is 10,000 at most, alone or times `adjacent`,
-      `lookback` or `periods`. `fixedPeriodCap.period` and `occurrenceCap.per`
-      are a `LocalPeriod`: a count, never `elapsed`.
-    - `dutyViolations` reads only the time the log covers, and each check reads
-      the log as it stood then, so a record only grows as the log does.
-    - Nested caps are separate rules, reported separately.
-14. **Read the docs site.** This skill is a routing pointer. For full option
+13. **Read the docs site.** This skill is a routing pointer. For full option
     shapes, locale matrices, and code examples, read these:
-    - `https://gmt-dox.northguild.workers.dev/llms.txt` is the map of every docs page.
+    - `https://northguild.dev/gmt/llms.txt` is the map of every docs page.
     - Each page has a `.md` twin that holds its text, for example
-      `https://gmt-dox.northguild.workers.dev/guides/core-date-operations/plain-arithmetic.md`.
+      `https://northguild.dev/gmt/guides/core-date-operations/plain-arithmetic.md`.
     - The JSDoc of the function you intend to call ships in the installed
       package: `node_modules/@northguild/gmt/dist/**/*.d.ts`.
 
@@ -323,11 +288,6 @@ and full interval set operations.
   `intervalLengthDate`, `intervalDivideEquallyDate`, `mergeIntervalsDate` (each
   with `DateTime`/`Zoned`/`Unix`/`Utc` variants where the type supports it)
 
-- **Hours of work**: `evaluateDutyLog`, `dutyViolations`, `dutyDayFor`,
-  `dutyTotals`, `longestRun`, `qualifyingRests`, `qualifyingRestPairs`,
-  `isValidDutyLog`, types `DutyEntry`, `DutyRule`, `Period`, `LocalPeriod`,
-  `DutyReport`
-
 ## Namespace selection
 
 - `plain/*` — timezone-free dates, times, datetimes
@@ -337,15 +297,14 @@ and full interval set operations.
 - `duration/*` — ISO 8601 duration strings
 - `span/*` — elapsed and wall-clock spans as raw numbers
 - `interval/*` — half-open interval algebra over instant strings
-- `duty/*` — hours-of-work rules over a duty log
+- `workforce/*` — see the `gmt-workforce` skill
 
 ## References
 
-- [Docs map for agents (llms.txt)](https://gmt-dox.northguild.workers.dev/llms.txt)
-- [Plain arithmetic guide](https://gmt-dox.northguild.workers.dev/guides/core-date-operations/plain-arithmetic/)
-- [Durations guide](https://gmt-dox.northguild.workers.dev/guides/core-date-operations/durations/)
-- [Spans guide](https://gmt-dox.northguild.workers.dev/guides/core-date-operations/spans/)
-- [Business calendars guide](https://gmt-dox.northguild.workers.dev/guides/core-date-operations/business-calendars/)
+- [Docs map for agents (llms.txt)](https://northguild.dev/gmt/llms.txt)
+- [Plain arithmetic guide](https://northguild.dev/gmt/guides/core-date-operations/plain-arithmetic/)
+- [Durations guide](https://northguild.dev/gmt/guides/core-date-operations/durations/)
+- [Spans guide](https://northguild.dev/gmt/guides/core-date-operations/spans/)
+- [Business calendars guide](https://northguild.dev/gmt/guides/core-date-operations/business-calendars/)
 - [Interval algebra reference](/reference/interval/calculate/intersectIntervals)
 - [Interval guides](/guides/intervals/interval-basics/)
-- [Hours of work guide](https://gmt-dox.northguild.workers.dev/guides/intervals/hours-of-work/)

package/skills/gmt-basics/SKILL.md

@@ -34,7 +34,7 @@ sources:
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.19.0'
+  library_version: '1.20.0'
 ---
 
 # GMT Basics
@@ -64,9 +64,9 @@ input before you act on it.
    `try`/`catch` around a GMT call is dead code.
 3. **Read the docs site.** This skill is a routing pointer. For full API
    signatures, locale matrices, and code examples, read these:
-   - `https://gmt-dox.northguild.workers.dev/llms.txt` is the map of every docs page.
+   - `https://northguild.dev/gmt/llms.txt` is the map of every docs page.
    - Each page has a `.md` twin that holds its text, for example
-     `https://gmt-dox.northguild.workers.dev/guides/core-date-operations/parsing.md`.
+     `https://northguild.dev/gmt/guides/core-date-operations/parsing.md`.
    - The JSDoc of the function you intend to call ships in the installed
      package: `node_modules/@northguild/gmt/dist/**/*.d.ts`.
 
@@ -87,7 +87,9 @@ input before you act on it.
 - **Comparison**: `isAfterDate`, `isBeforeDate`, `areDatesEqual`,
   `areDatesEqualBy`, `isWeekend`, `isBusinessDay`, `nextWeekday`
 - **Validation**: `isValidDate`, `isValidTime`, `isValidTimeZone`,
-  `isValidZonedDateTime`, `isValidDateInterval`, `isValidFiscalPattern`
+  `isValidZonedDateTime`, `isValidDateInterval`, `isValidFiscalPattern`,
+  `isValidFiscalCalendar`, `isValidFiscalExtraWeek`, `isValidFiscalYearLabel`,
+  `hasSecond60`
 - **Interchange-format validation**: `isValidRfc3339DateTime`,
   `isValidRfc2822DateTime`, `isValidHttpDate`, `isValidSqlDateTime`
 - **UTC timestamp validation**: `isValidUtcTimestamp` (a UTC instant written
@@ -146,8 +148,14 @@ input before you act on it.
   lacks (`timeStyle` on `formatDate`, `dateStyle` on `formatTime`) returns `""`.
   Zoned formatters return `""`/`[]` for a `timeZone` option: to show an instant
   in another zone, use `formatUtc(value, locale, { timeZone })`.
-- Leap seconds (`:60`) are invalid in every spelling (`T`, `t`, space, basic
-  format). `isLeapSecond` tells you one is there. Validators return `false`.
+- A second of `60` is invalid in every spelling (`T`, `t`, space, basic
+  format), and validators return `false` for it. Two functions tell you about
+  one. `hasSecond60` is the shape test: it is true for any second 60, real or
+  not (`"2024-06-15T12:34:60Z"` is `true`). `isLeapSecond`, from `timescale/`,
+  is the table lookup: it is true only for the 27 inserted leap seconds
+  (`"2016-12-31T23:59:60Z"` is `true`, `"2024-06-15T12:34:60Z"` is `false`).
+  Only the `timescale/` and `gnss/` functions accept a second 60, and only a
+  listed one; see the `gmt-integration` and `gmt-gnss` skills.
 - `isValidTimeZone` accepts every IANA name, including single-component links
   such as `Japan`, `Zulu` and `EST5EDT`, and ignores case. It also accepts
   offset zone ids such as `"+05:00"`, as Temporal does.
@@ -163,16 +171,28 @@ input before you act on it.
   instant has no calendar date until you name a zone — floor it with
   `floorToZone` first, or convert it in the zone you mean.
 - `getFiscalPeriod`'s `yearEndsOn` states the year-end **rule** by example, not
-  one year's end. The NRF 4-5-4 calendar is `"2026-01-31"` — a Saturday on
-  January 31, which is "the Saturday nearest to January 31".
+  one year's end. One published 4-5-4 example (NRF, US) adds a 53rd week when
+  "there are four or more days left in January", which is the Saturday nearest
+  January 31: `"2026-01-31"`, a Saturday on January 31.
+- `getFiscalPeriod` also requires `extraWeek` and `yearLabel`, with no default,
+  because published calendars disagree on both. `extraWeek` is the period a 53rd
+  week is added to: `"firstPeriod"` (ONS, UK) or `"lastPeriod"` (NRF, US).
+  `yearLabel` names the fiscal year: `"startYear"` (NRF, US), `"endYear"`, the
+  year its last day falls in, or `"majorityYear"`, the calendar year holding the
+  most of its days (ONS, UK); a 182/182 split goes to the end year. IFRS 18
+  ¶27(c) (formerly IAS 1 ¶51(c)) lets a period be identified by the date it
+  ends, which supports `"endYear"` and the tie rule. `getQuarter` with options takes
+  `fiscalYearStartMonth` and `yearLabel`, both required. A calendar missing a
+  field returns `null`; check it with `isValidFiscalCalendar`.
 - `isWeekend` is locale-aware via `Intl.Locale.weekInfo`; `isBusinessDay` is
-  fixed ISO Mon–Fri with no locale and no holidays **until you pass it a
+  a fixed Mon–Fri week (Sat–Sun off, CLDR's world default; ISO 8601 defines no
+  weekend) with no locale and no holidays **until you pass it a
   `BusinessCalendar`** — `isBusinessDay(value, { weekend, holidays, timeZone })`
   states the weekend and holidays itself. See the `gmt-arithmetic` skill.
 
 ## References
 
-- [Docs map for agents (llms.txt)](https://gmt-dox.northguild.workers.dev/llms.txt)
-- [API reference](https://gmt-dox.northguild.workers.dev/reference/)
-- [Core date operations guides index](https://gmt-dox.northguild.workers.dev/guides/core-date-operations/)
+- [Docs map for agents (llms.txt)](https://northguild.dev/gmt/llms.txt)
+- [API reference](https://northguild.dev/gmt/reference/)
+- [Core date operations guides index](https://northguild.dev/gmt/guides/core-date-operations/)
 - [Core date operations guides](/guides/core-date-operations/get-current/)

package/skills/gmt-gnss/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: gmt-gnss
+description: >
+  GNSS time in @northguild/gmt/gnss — the six RINEX GNSS time scales as peers
+  (GPS, GAL, BDT, QZS, GLO, IRN: utcToGnss, gnssToUtc), broadcast weeks by named
+  counter (GnssWeekCounter) with a required rolloverEra (integer, "rolling" or {
+  notBefore }) for gnssWeekToUtc/utcToGnssWeek, and continuous RINEX navigation
+  weeks (rinexWeekToUtc, utcToRinexWeek). Reads the docs site (llms.txt) and the
+  installed package's JSDoc; a routing pointer, not an API dump.
+sources:
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/gnss-system-time-and-week-rollover.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/maritime-gnss-time-and-week-rollover.mdx'
+  - 'northguild/gmt:packages/gmt/src/gnss/index.ts'
+  - 'northguild/gmt:packages/gmt/src/types/gnss.ts'
+metadata:
+  type: core
+  library: '@northguild/gmt'
+  library_version: '1.20.0'
+---
+
+# GMT GNSS
+
+Use this skill when the task is reading satellite receiver output: a GNSS
+time-scale string, a broadcast week and time of week, or a RINEX navigation
+file week. TAI and the leap-second table are in the `gmt-integration` skill.
+
+## When to load
+
+- The user is reading satellite receiver output: a GNSS time-scale string, a
+  broadcast week and time of week, or a RINEX navigation-file week.
+
+## Core rules
+
+1. **The six GNSS time scales are peers, named by their RINEX 4.02 tokens.**
+   `GPS`, `GAL` (Galileo), `BDT` (BeiDou), `QZS` (QZSS), `GLO` (GLONASS) and
+   `IRN` (NavIC). No system is a default; each goes through the same functions,
+   with the system first.
+   ```typescript
+   utcToGnss("GAL", "2024-01-01T00:00:00Z"); // "2024-01-01T00:00:18 GAL"
+   utcToGnss("BDT", "2024-01-01T00:00:00Z"); // "2024-01-01T00:00:04 BDT"
+   utcToGnss("GPS", "1980-01-06T00:00:00Z"); // "1980-01-06T00:00:00 GPS" (0 s at the epoch)
+   gnssToUtc("IRN", "2024-01-01T00:00:18 IRN"); // "2024-01-01T00:00:00Z"
+   ```
+   - `GLO` is GLONASS time as RINEX reports it: UTC's own hours, leap seconds
+     included, not UTC + 3 h. Remove the three hours from raw system time first.
+   - Each system returns the sentinel before its own epoch. Offsets are nominal:
+     broadcast nanosecond corrections are not applied.
+2. **A broadcast week needs its counter and its era.** `GnssWeekCounter` names
+   one counter with one modulus: `"GPS-LNAV"`, `"QZS-LNAV"`, `"IRN-LNAV"` 1024
+   weeks; `"GAL"` 4096; `"GPS-CNAV"`, `"QZS-CNAV"`, `"BDT"`, `"IRN-L1NV"` 8192.
+   GLONASS has no week counter. `rolloverEra` is required: an integer era for
+   stored data, `"rolling"` for live output (the era within half a counter
+   period of today, so it reads the clock), or `{ notBefore }`, the earliest
+   match at or after an instant you state, such as a firmware build date.
+   ```typescript
+   gnssWeekToUtc("GPS-LNAV", 100, 0, 0); // "1981-12-05T23:59:59Z"
+   gnssWeekToUtc("GPS-LNAV", 100, 0, 1); // "2001-07-21T23:59:47Z"
+   gnssWeekToUtc("GPS-LNAV", 1020, 0, { notBefore: "2019-04-07T00:00:00Z" }); // "2038-10-23T23:59:42Z"
+   utcToGnssWeek("GAL", "2019-04-07T00:00:00Z"); // { week: 1024, timeOfWeekSeconds: 18, era: 0 }
+   ```
+   A RINEX navigation record's week is continuous and never wraps: read it with
+   `rinexWeekToUtc` / `utcToRinexWeek`, not the broadcast functions. A RINEX
+   NavIC week read as a broadcast week is 1024 weeks off.
+   ```typescript
+   rinexWeekToUtc("IRN", 2295, 86418); // "2024-01-01T00:00:00Z"
+   gnssWeekToUtc("IRN-L1NV", 2295, 86418, 0); // "2043-08-17T00:00:00Z" (not the same week)
+   ```
+3. **Second 60 is accepted only on a listed insertion day.** `gnss/` and
+   `timescale/` accept `:60` only on a listed insertion day, and may return
+   `…T23:59:60Z`. Every other GMT function rejects `:60`, so do not pass that
+   result on.
+4. **Convert at the boundary and store the era rule.** Convert a GNSS label to
+   a UTC instant on the way in (`gnssToUtc`, `gnssWeekToUtc`, `rinexWeekToUtc`),
+   and back on the way out. Store the era rule you used with any week you
+   decode.
+5. **Read the docs site.** This skill is a routing pointer. The map of the
+   docs is `https://northguild.dev/gmt/llms.txt`, and each page
+   has a `.md` twin that holds its text. The JSDoc ships in the installed
+   package: `node_modules/@northguild/gmt/dist/**/*.d.ts`.
+
+## Key functions
+
+- **GNSS time scales** (`@northguild/gmt/gnss`): `utcToGnss`, `gnssToUtc`,
+  `gnssWeekToUtc`, `utcToGnssWeek`, `rinexWeekToUtc`, `utcToRinexWeek`, types
+  `GnssSystem`, `GnssWeekCounter`, `RolloverEra`, `GnssWeek`,
+  `RinexWeekSystem`, `RinexWeek`
+
+## References
+
+- [gnss reference](https://northguild.dev/gmt/reference/gnss/)
+- [Docs map for agents (llms.txt)](https://northguild.dev/gmt/llms.txt)
+- [GMT Integration skill](../gmt-integration/SKILL.md)

package/skills/gmt-integration/SKILL.md

@@ -3,11 +3,13 @@ name: gmt-integration
 description: >
   Application integration patterns — stable cache keys, router/query params,
   table-sort keys, nanosecond timestamps across JSON and storage boundaries,
-  foreign epoch bridges (NTP, FILETIME, .NET ticks, Excel, PostgreSQL), and lint
-  package selection (ESLint, Biome, Oxlint). Reads the docs site (llms.txt and
-  each page's .md twin) and the installed package's JSDoc for API details, and
-  the lint-package READMEs for lint setup; this skill is a routing pointer, not
-  an API dump.
+  foreign epoch bridges (NTP, FILETIME, .NET ticks, Excel, PostgreSQL), TAI and
+  the closed IERS leap-second table (taiMinusUtc, leapSecondsBetween,
+  nextLeapSecond, isLeapSecond, toTAI, fromTAI), and lint package selection
+  (ESLint, Biome, Oxlint). GNSS time is in gmt-gnss. Reads the docs site
+  (llms.txt and each page's .md twin) and the installed package's JSDoc for API
+  details, and the lint-package READMEs for lint setup; this skill is a routing
+  pointer, not an API dump.
 sources:
   - 'northguild/gmt:apps/dox/src/content/docs/install.mdx'
   - 'northguild/gmt:apps/dox/src/content/docs/guides/integration/app-integration.mdx'
@@ -19,10 +21,11 @@ sources:
   - 'northguild/gmt:packages/gmt/src/precision/format/index.ts'
   - 'northguild/gmt:packages/gmt/src/precision/calculate/index.ts'
   - 'northguild/gmt:packages/gmt/src/precision/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/timescale/index.ts'
 metadata:
   type: composition
   library: '@northguild/gmt'
-  library_version: '1.19.0'
+  library_version: '1.20.0'
 ---
 
 # GMT Integration
@@ -37,6 +40,8 @@ which lint package to install for Date-ban enforcement.
 - The user is moving nanosecond timestamps across a JSON wire or into a database.
 - The user is reading or writing another system's epoch — NTP, Windows `FILETIME`,
   .NET ticks, an Excel day serial, or PostgreSQL's internal microseconds.
+- The user needs TAI, TAI − UTC on a date, or whether a `23:59:60` was a real
+  leap second.
 - The user is picking an ESLint, Biome, or Oxlint plugin to ban `Date` APIs.
 - The user has a lint package but not the gmt runtime (or vice versa).
 
@@ -87,13 +92,32 @@ which lint package to install for Date-ban enforcement.
      bracketed zone annotation. One thing is read from it: an offset written to the
      minute that is the zone's sub-minute offset rounded (`-00:45[Africa/Monrovia]`)
      names the instant the zone gives.
-6. **Lint packages are toolchain-specific, not mutually exclusive.** Recommend
+6. **Leap seconds come from the built-in table, never a literal.** `timescale/`
+   holds the IERS leap-second table as a closed record: 27 insertions, the last
+   on 2016-12-31, and TAI − UTC stays 37 s for every later date, because UTC
+   becomes continuous on 20 May 2027 (CGPM 2026). No function takes a table.
+   ```typescript
+   taiMinusUtc("2024-01-01T00:00:00Z"); // 37
+   leapSecondsBetween("2000-01-01T00:00:00Z", "2024-01-01T00:00:00Z"); // 5
+   isLeapSecond("2016-12-31T23:59:60Z"); // true (a table lookup)
+   isLeapSecond("2024-06-15T12:34:60Z"); // false (hasSecond60 is the shape test)
+   toTAI("2026-01-01T00:00:00Z"); // "2026-01-01T00:00:37 TAI"
+   fromTAI("2017-01-01T00:00:36 TAI"); // "2016-12-31T23:59:60Z"
+   ```
+   - Before 1972-01-01 TAI − UTC was fractional, so every function returns its
+     sentinel there.
+   - `timescale/` and `gnss/` accept a second 60 only on a listed insertion
+     day (for `gnss/`, see the `gmt-gnss` skill), and may return `…T23:59:60Z`. Every other GMT function rejects `:60`,
+     so do not pass that result on.
+   - A smeared clock never reads `23:59:60` and is up to a second off UTC
+     around an insertion. GMT cannot detect smearing.
+7. **Lint packages are toolchain-specific, not mutually exclusive.** Recommend
    only the one matching the project's existing linter; do not force all three.
-7. **Read the docs site and the lint README.** This skill is a routing pointer.
+8. **Read the docs site and the lint README.** This skill is a routing pointer.
    For full integration guidance, read these:
-   - `https://gmt-dox.northguild.workers.dev/llms.txt` is the map of every docs page.
+   - `https://northguild.dev/gmt/llms.txt` is the map of every docs page.
    - Each page has a `.md` twin that holds its text, for example
-     `https://gmt-dox.northguild.workers.dev/guides/integration/app-integration.md`.
+     `https://northguild.dev/gmt/guides/integration/app-integration.md`.
    - The JSDoc ships in the installed package:
      `node_modules/@northguild/gmt/dist/**/*.d.ts`.
    - For lint setup, read the matching `@northguild/gmt-eslint` / `gmt-oxlint` /
@@ -127,13 +151,22 @@ the pattern.
 - **Foreign epochs at the boundary**: convert on the way in and on the way out with
   the `precision/convert/` bridges, and keep ISO strings or `bigint` nanoseconds
   everywhere in between — never carry another system's serial through your own code.
+- **Atomic time at the boundary**: convert a TAI label to a UTC instant on the
+  way in (`fromTAI`), and back on the way out. GNSS time scales and weeks are in
+  the `gmt-gnss` skill.
+
+## Key functions
+
+- **Leap seconds and TAI** (`@northguild/gmt/timescale`): `taiMinusUtc`,
+  `leapSecondsBetween`, `nextLeapSecond`, `isLeapSecond`, `toTAI`, `fromTAI`
 
 ## References
 
-- [Docs map for agents (llms.txt)](https://gmt-dox.northguild.workers.dev/llms.txt)
-- [Install](https://gmt-dox.northguild.workers.dev/install/)
-- [App integration guide](https://gmt-dox.northguild.workers.dev/guides/integration/app-integration/)
-- [Nanosecond precision guide](https://gmt-dox.northguild.workers.dev/guides/core-date-operations/nanosecond-precision/)
-- [Foreign epoch bridges guide](https://gmt-dox.northguild.workers.dev/guides/conversion/foreign-epoch-bridges/)
+- [Docs map for agents (llms.txt)](https://northguild.dev/gmt/llms.txt)
+- [Install](https://northguild.dev/gmt/install/)
+- [App integration guide](https://northguild.dev/gmt/guides/integration/app-integration/)
+- [Nanosecond precision guide](https://northguild.dev/gmt/guides/core-date-operations/nanosecond-precision/)
+- [Foreign epoch bridges guide](https://northguild.dev/gmt/guides/conversion/foreign-epoch-bridges/)
+- [timescale reference](https://northguild.dev/gmt/reference/timescale/)
 - [Lint Package Selection guide](/guides/integration/linting/)
 - [Core Rules](/core-rules/)