@northguild/gmt 1.15.0 → 1.16.0

package/skills/gmt-arithmetic/SKILL.md

@@ -2,21 +2,37 @@
 name: gmt-arithmetic
 description: >
   Date arithmetic — add/subtract duration objects, diff values, clamp/closest,
-  ISO 8601 duration strings, and interval range math (contain, overlap, union,
-  split, count boundaries). Reads the installed package README.md and source
-  JSDoc for API details; this skill is a routing pointer, not an API dump.
+  ISO 8601 duration strings, elapsed-versus-wall-clock spans, business-day
+  arithmetic and interval range math. Covers the half-open [start, end) interval
+  algebra over instants (intervalsOverlap, intervalContains, intersectIntervals,
+  clampInterval, mergeIntervals, subtractIntervals, splitIntervalAt,
+  sumIntervals, isValidInterval, Interval) and the positional interval*Date /
+  *Utc / *Zoned / *Unix functions on the same rule, business calendars
+  (BusinessCalendar, RollConvention, isBusinessDay, addBusinessDays,
+  subtractBusinessDays, businessDaysBetween, nextBusinessDay,
+  previousBusinessDay, rollDate, mergeCalendars), overflow "constrain" month-end
+  clamping, splitIntervalByUnit* stepping from the anchor, maxPieces limits,
+  intervalCount* matching bucketRange, RFC 9557 calendar strings, and the
+  correct-at-the-edges guarantees at the first and last representable instant. A
+  routing pointer, not an API dump.
 sources:
   - 'northguild/gmt:README.md'
   - 'northguild/gmt:packages/gmt/src/plain/calculate/index.ts'
   - 'northguild/gmt:packages/gmt/src/duration/index.ts'
+  - 'northguild/gmt:packages/gmt/src/interval/index.ts'
+  - 'northguild/gmt:packages/gmt/src/types/interval.ts'
   - 'northguild/gmt:packages/gmt/src/plain/interval/index.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/interval/index.ts'
   - 'northguild/gmt:packages/gmt/src/unix/interval/index.ts'
   - 'northguild/gmt:packages/gmt/src/utc/interval/index.ts'
+  - 'northguild/gmt:packages/gmt/src/span/calculate/index.ts'
+  - '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'
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.15.0'
+  library_version: '1.16.0'
 ---
 
 # GMT Arithmetic
@@ -33,19 +49,171 @@ and full interval set operations.
 - The user wants to restrict a value to a min/max range, or find the nearest
   candidate.
 - The user needs range math: "do these overlap?", "merge these", "split this
-  into n parts".
+  into n parts", "split this by month", "how much of this shift fell inside
+  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`.
 
 ## Core rules
 
 1. **`add*` takes a `{ unit: number }` object, not an ISO duration string.**
    `addDate("2024-03-15", { days: 5 })` works; `addDate("2024-03-15", "P5D")`
    returns `""`. Use `diffDateAsDuration` / `addDuration` for duration strings.
-2. **`overflow`** defaults to `"constrain"` (clamps to a valid date). Pass
+2. **Arithmetic clamps; parsers reject.** `overflow` defaults to `"constrain"`,
+   Temporal's default: January 31 plus one month is February 29, and
+   `addDate("2024-02-29", { years: 1 })` is `"2025-02-28"`. Pass
    `{ overflow: "reject" }` to get the `""` sentinel instead of a clamp.
-3. **Calendar units need `relativeTo`.** `durationAs`, `normalizeDuration`, and
+   `addTime`/`subtractTime`/`intervalFromDurationTime` take no options: a clock
+   time wraps (`addTime("23:00:00", { hours: 2 })` is `"01:00:00"`).
+   `parse*` functions never clamp — `31 February` returns the sentinel.
+3. **Repeated steps come from the anchor.** `splitIntervalByUnit*` computes
+   boundary k as `start + k × amount`, never by stepping from the previous
+   boundary, so month-end starts don't drift:
+   `splitIntervalByUnitDate("2024-01-31", "2024-05-01", "month", 1)` gives
+   February 29, March 31, April 30 (then a trimmed slice to May 1). A yearly
+   split from February 29 returns to February 29 in leap years. Build your own
+   series the same way — chaining `add*` onto the previous clamped result
+   drifts to the 29th for good.
+   - **Piece-building functions have a limit.** `splitIntervalByUnit*`,
+     `intervalDivideEqually*`, `mapDatesInRange` and `mapZonedDatesInRange` take
+     `{ maxPieces }` (a positive safe integer, default `1_000_000`) and return
+     `[]` when the result would be longer. `[]` there is not "empty range": if a
+     long range can legitimately exceed the default, pass a larger `maxPieces`.
+     `bucketRange` has its own fixed limit of 10,000 buckets.
+
+     ```typescript
+     mapDatesInRange("0001-01-01", "9999-12-31", 1); // [] — 3,652,059 dates
+     splitIntervalByUnitDate("2024-01-01", "2024-01-10", "day", 2, { maxPieces: 5 }).length; // 5
+     ```
+
+   - `intervalDivideEqually*` boundaries are integers, rounded half up — exact
+     nanoseconds, or the epoch arguments' own unit for `intervalDivideEquallyUnix`
+     (`intervalDivideEquallyUnix(0, 100, 3)` cuts at 33 and 67) — so the pieces
+     tile the range with no gap or overshoot.
+4. **Zoned counts match zoned buckets.** `intervalCountZoned`,
+   `intervalCountUnix` and `intervalCountUtc` count the buckets `bucketRange`
+   returns: a 20-minute range straddling `Pacific/Chatham`'s 15-minute 03:00
+   hour on its spring-forward counts 2 hours, and a range over `Pacific/Apia`'s
+   deleted 30 December 2011 does not count that day. `intervalCountUnix` counts
+   in `options.timeZone`, UTC by default (`"local"` for the system zone).
+5. **Calendar units need `relativeTo`.** `durationAs`, `normalizeDuration`, and
    `compareDurations` return `null`/`""` for year/month/week arithmetic without
-   a `relativeTo` anchor — a month is not a fixed length.
-4. **Read the README.** This skill is a routing pointer. For full option shapes,
+   a `relativeTo` anchor — a month is not a fixed length. A calendar-annotated
+   `relativeTo` is read as Temporal reads it: zoned when it has a time zone
+   annotation, otherwise a date, and its calendar must be a `CalendarSystem`.
+   - `round*` accept singular or plural `smallestUnit` names (`"hour"` or
+     `"hours"`). A `roundingMode` outside Temporal's nine returns the sentinel.
+   - `diff*` with an array of units returns only the listed units, and each
+     unlisted unit in between folds into the next smaller listed one:
+     `diffDate("2024-01-01", "2025-03-15", ["years", "days"])` is
+     `{ years: 1, days: 73 }` (January to mid-March becomes days).
+6. **Elapsed time and calendar distance are different questions.** `spanMs` /
+   `spanNs` measure what actually elapsed; `spanWallClock(start, end, "days" |
+   "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.
+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
+   `spanNs` still carries the exact value as a `bigint`.
+8. **Interval algebra over instants is half-open — reach for `interval/`.**
+   `intervalsOverlap`, `intervalContains`, `intersectIntervals`,
+   `clampInterval`, `mergeIntervals`, `subtractIntervals`, `splitIntervalAt`
+   and `sumIntervals` take `Interval` records (`{ start, end }`) of instant
+   strings with an offset, and treat them as `[start, end)` (SQL:2011
+   `PERIOD`, RFC 5545 `DTEND`). Touching intervals do not overlap; outputs
+   are the caller's own strings; `start === end` is a valid empty interval.
+
+   ```typescript
+   const shift = { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" };
+   subtractIntervals(shift, [{ start: "2024-01-01T12:00:00Z", end: "2024-01-01T13:00:00Z" }]);
+   // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" },
+   //  { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }]
+   sumIntervals(/* that result */); // "PT7H" — hours are the largest unit, never days
+   ```
+
+   `sumIntervals` returns covered time (overlaps count once), `[]` → `"PT0S"`.
+   `[]` is both a real result and the array sentinel: check inputs with
+   `isValidInterval`. Plain dates, zoneless datetimes and inverted intervals
+   return the sentinel — build local edges with `floorToZone` first.
+9. **The positional `interval*Date|Time|DateTime|Utc|Zoned|Unix` functions are
+   half-open `[start, end)` too.** `intervalsOverlapUtc` is `false` for touching
+   intervals and `intervalContainsUtc` excludes `end`; `intervalAbuts*` means
+   one interval's `end` equals the other's `start`
+   (`intervalAbutsDate("2024-01-01", "2024-07-01", "2024-07-01", …)` is `true`);
+   `intervalDifference*`/`intervalXor*` cut exactly at the other interval's
+   edges, with no one-unit step. A `Date` interval's `end` is the first day
+   after the period: pass `addDate(lastDay, { days: 1 })`, never the last day.
+10. **Calendar strings are RFC 9557: ISO digits plus `[u-ca=<id>]`.**
+    `convertDateToCalendar("2024-10-03", "hebrew")` is
+    `"2024-10-03[u-ca=hebrew]"`, exactly `Temporal.PlainDate#toString()`. It
+    feeds `addDate`, `subtractDate`, `diffDate*` and the `plain/interval/*Date`
+    functions, and `Temporal.PlainDate.from` reads it as the same date.
+    - Ids are the canonical BCP 47 / Temporal ids, in strings and arguments:
+      `iso8601`, `gregory`, `hebrew`, `islamic-civil`, `islamic-tbla`,
+      `islamic-umalqura`, `japanese`, `buddhist`, `roc`, `persian`, `indian`,
+      `ethiopic`, `ethioaa`, `coptic`. `gregorian`, `taiwan` and
+      `islamic-tabular` return the sentinel; aliases Temporal accepts
+      (`ethiopic-amete-alem`) are canonicalized. `iso8601` writes no annotation.
+    - Never put calendar fields (a Hebrew year, a Japanese era) in the string,
+      and never slice them out of it: read them from Temporal
+      (`Temporal.PlainDate.from(s).eraYear`). `;era=` is rejected.
+    - A string written before 1.16.0 (`"5785-01-01[u-ca=hebrew]"`) reads as ISO
+      year 5785 with no error: regenerate stored values from their ISO dates.
+    - Values naming different calendars: differences (`diffDate*`,
+      `intervalCount*`, `intervalLength*`, `splitIntervalByUnit*`,
+      `intervalOverlappingDays*`) return the sentinel; ordering accepts them.
+    - Month arithmetic of any size in range is safe:
+      `addDate("2024-01-15[u-ca=persian]", { months: 3000000 })` is
+      `"+252023-12-27[u-ca=persian]"`.
+    - A month counts only once the end date reaches the same day of the next
+      month: `diffDateAsDuration("2024-08-31[u-ca=buddhist]",
+      "2024-09-30[u-ca=buddhist]", "months")` is `"P30D"`, not `"P1M"`.
+11. **Correct at the edges — rely on it, do not work around it.** Temporal's
+    instant range is `-271821-04-20T00:00:00Z` to `+275760-09-13T00:00:00Z`,
+    and GMT returns the TC39 answer up to both ends:
+    - `PlainTime`'s last nanosecond stays on its day, and no interval boundary
+      is computed past the last instant (`intervalAbuts*`, `intervalXorAll*`).
+    - The earliest month has an end: `endOfDate("-271821-04-19", "month")` is
+      `"-271821-04-30"`.
+    - Every supported calendar parses and does arithmetic at both limits.
+      Hebrew years ≤ 0 and Indian dates before ISO year 1 are correct.
+    - `spanNs` and `sumIntervals` are exact across the whole range (up to
+      `PT4800000000H`), past where a `number` stops holding nanoseconds.
+    - `unix/interval` functions return the sentinel for a fractional or
+      unsafe epoch, or `""`.
+    - Rounding, week functions, splits, counts, `bucketRange` and the date
+      mappers return the answer at both limits when it exists:
+      `roundDate("+275760-06-15", { smallestUnit: "year", roundingMode: "floor" })`
+      is `"+275760-01-01"`. Only a result past the limit is the sentinel.
+    - Near the maximum in `UTC`, a rounded difference or total whose window
+      passes the limit returns the sentinel, exactly as `+00:00` does.
+    Zoned limits are in the `gmt-timezone` skill.
+12. **Business days need a `BusinessCalendar`, and a weekend is never assumed.**
+    `{ weekend: number[], holidays: string[], timeZone: string }` — `weekend` is
+    ISO weekday numbers, because Saturday–Sunday is not universal (much of the
+    Middle East is `[5, 6]`). `isBusinessDay`, `addBusinessDays` and
+    `subtractBusinessDays` take it as an optional trailing argument, defaulting to
+    Monday–Friday with no holidays; `businessDaysBetween`, `nextBusinessDay`,
+    `previousBusinessDay`, `rollDate` and `mergeCalendars` require it. Holidays are
+    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
+    ```
+
+    These are **local-date in, local-date out**: `calendar.timeZone` records the
+    locality and is never read, so reduce an instant with `floorToZone` first.
+    `nextBusinessDay`/`previousBusinessDay` are strictly after/before;
+    `rollDate`'s `following`/`preceding` are on-or-after/on-or-before and leave a
+    working day alone. `mergeCalendars` unions weekends and holidays, so a date
+    survives only if it is a working day in every input, and returns `null` for an
+    empty list. Narrow inputs with `isValidBusinessCalendar` /
+    `isValidRollConvention`.
+13. **Read the README.** This skill is a routing pointer. For full option shapes,
    locale matrices, and code examples, read the installed package's `README.md`
    and the source JSDoc of the function you intend to call.
 
@@ -53,21 +221,31 @@ and full interval set operations.
 
 - **Point arithmetic**: `addDate`, `addDateTime`, `addTime`, `subtractTime`,
   `addBusinessDays`, `subtractBusinessDays`, `cycleDate`, `setDate`
+- **Business calendars**: `isBusinessDay`, `businessDaysBetween`,
+  `nextBusinessDay`, `previousBusinessDay`, `rollDate`, `mergeCalendars`,
+  `isValidBusinessCalendar`, `isValidRollConvention`
 - **Diffs**: `diffDate`, `diffDateTime`, `diffTime` (+ `diffZoned`,
   `diffUnix`, `diffUtc` in their namespaces)
+- **Spans (raw numbers)**: `spanMs`, `spanNs`, `spanWallClock`, `isValidSpan`
 - **Bounds**: `clampDate`, `closestDateTo`, `startOfDate`, `endOfDate`,
-  `startOfQuarterForDate`, `getLocaleStartOfWeek`
+  `startOfQuarterForDate`, `getLocaleStartOfWeek` (zoned boundaries: see the
+  `gmt-timezone` skill)
 - **Durations (ISO 8601)**: `isValidDuration`, `parseDuration`, `addDuration`,
   `subtractDuration`, `normalizeDuration`, `durationAs`, `formatDuration`,
   `negateDuration`, `absDuration`, `compareDurations`, `getDurationUnit`,
   `getDurationSign`
 - **Diff-to-duration bridge**: `diffDateAsDuration`,
   `diffZonedAsDuration`, `diffUnixAsDuration`, `diffUtcAsDuration`
-- **Intervals (range math)**: `isValidDateInterval`, `intervalContainsDate`,
-  `intervalsOverlapDate`, `intervalIntersectionDate`, `intervalUnionDate`,
-  `intervalDifferenceDate`, `intervalXorDate`, `intervalFromDurationDate`,
-  `splitIntervalByUnitDate`, `intervalCountDate`, `intervalLengthDate`,
-  `intervalDivideEquallyDate`, `mergeIntervalsDate`
+- **Interval algebra (half-open, instants)**: `isValidInterval`,
+  `intervalsOverlap`, `intervalContains`, `intersectIntervals`,
+  `clampInterval`, `mergeIntervals`, `subtractIntervals`, `splitIntervalAt`,
+  `sumIntervals`, type `Interval`
+- **Positional intervals (half-open)**: `isValidDateInterval`,
+  `intervalContainsDate`, `intervalsOverlapDate`, `intervalIntersectionDate`,
+  `intervalUnionDate`, `intervalDifferenceDate`, `intervalXorDate`,
+  `intervalFromDurationDate`, `splitIntervalByUnitDate`, `intervalCountDate`,
+  `intervalLengthDate`, `intervalDivideEquallyDate`, `mergeIntervalsDate` (each
+  with `DateTime`/`Zoned`/`Unix`/`Utc` variants where the type supports it)
 
 ## Namespace selection
 
@@ -76,8 +254,11 @@ and full interval set operations.
 - `unix/*` — epoch seconds/milliseconds
 - `utc/*` — UTC instants (`"2024-03-15T14:30:45Z"`)
 - `duration/*` — ISO 8601 duration strings
+- `span/*` — elapsed and wall-clock spans as raw numbers
+- `interval/*` — half-open interval algebra over instant strings
 
 ## References
 
 - [README — Quick Start](README.md)
-- [Interval function reference](/reference/plain)
+- [Interval algebra reference](/reference/interval/calculate/intersectIntervals)
+- [Interval guides](/guides/intervals/interval-basics/)

package/skills/gmt-basics/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: gmt-basics
 description: >
-  Core date/time basics — get current values, parse components, format for
-  display, format relative time, compare dates, and validate
-  strings/timezones/intervals. Reads the installed package README.md and source
-  JSDoc for API details; this skill is a routing pointer, not an API dump.
+  Core date/time basics — get current values, parse components, read ISO week,
+  ordinal, quarter and fiscal-period identifiers, format for display, format
+  relative time, compare dates, and validate strings/timezones/intervals. Reads
+  the installed package README.md and source JSDoc for API details; this skill
+  is a routing pointer, not an API dump.
 sources:
   - 'northguild/gmt:README.md'
   - 'northguild/gmt:packages/gmt/src/plain/get/index.ts'
@@ -18,10 +19,12 @@ sources:
   - 'northguild/gmt:packages/gmt/src/zoned/validate/index.ts'
   - 'northguild/gmt:packages/gmt/src/unix/get/index.ts'
   - 'northguild/gmt:packages/gmt/src/utc/get/index.ts'
+  - 'northguild/gmt:packages/gmt/src/calendar/calculate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/calendar/validate/index.ts'
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.15.0'
+  library_version: '1.16.0'
 ---
 
 # GMT Basics
@@ -35,6 +38,8 @@ input before you act on it.
 
 - The user needs "now" as an ISO string, or a formatted/localized display value.
 - The user wants to extract a year/month/day/hour from a date string.
+- The user needs the ISO week, ordinal, quarter or retail-calendar period a date
+  falls in — a week number on a vessel schedule, a 4-5-4 fiscal period.
 - The user needs "yesterday" or "in 2 hours" style output.
 - The user is comparing or sorting two date strings.
 - The user wants to guard a call with a validity check first.
@@ -44,7 +49,9 @@ input before you act on it.
 1. **ISO 8601 strings in.** Public APIs consume ISO strings, IANA timezone ids,
    or numeric Unix epochs — never `new Date()`.
 2. **Sentinel returns, never throws.** `""` for strings, `null` for numbers,
-   `false` for booleans, `[]` for arrays. Always check before using.
+   `false` for booleans, `[]` for arrays. Always check before using. This holds
+   for a `null` or wrong-typed argument too (`addDate(x, null)` is `""`), so a
+   `try`/`catch` around a GMT call is dead code.
 3. **Read the README.** This skill is a routing pointer. For full API
    signatures, locale matrices, and code examples, read the installed package's
    `README.md` and the source JSDoc of the function you intend to call.
@@ -55,6 +62,8 @@ input before you act on it.
   `getSystemTimeZone`, `getTimeZones`
 - **Parsing**: `parseYearFromDate`, `parseMonthFromDate`,
   `parseDateTimeWithPattern`, `parseRfc3339`, `parseHttp`, `parseSql`
+- **Calendar identifiers**: `getIsoWeekDate`, `getOrdinalDate`, `getQuarter`,
+  `getFiscalPeriod`
 - **Formatting**: `formatDate`, `formatTime`, `formatDateTime`,
   `formatRelativeDate`, `formatCalendar`, `formatRfc3339`
 - **Locale names**: `getLocaleMonthNames`, `getLocaleWeekdayNames`,
@@ -62,19 +71,57 @@ input before you act on it.
 - **Comparison**: `isAfterDate`, `isBeforeDate`, `areDatesEqual`,
   `areDatesEqualBy`, `isWeekend`, `isBusinessDay`, `nextWeekday`
 - **Validation**: `isValidDate`, `isValidTime`, `isValidTimeZone`,
-  `isValidZonedDateTime`, `isValidDateInterval`
+  `isValidZonedDateTime`, `isValidDateInterval`, `isValidFiscalPattern`
 
 ## Common pitfalls
 
-- `formatRelativeDate` requires a `reference` option — without it, you get `""`.
-- `parseDateWithPattern` returns `""` on shape-valid-but-unreal dates (regex
-  only proves shape; Temporal validates the real value).
-- Week numbers are ambiguous across year boundaries — pair
-  `parseWeekFromDate` with `getWeekYear`.
+- `formatRelative*` measure from now when `reference` is omitted, so the output
+  changes from day to day. Pass `reference` whenever the result must be deterministic.
+- `parseDateWithPattern`, `parseRfc2822` and `parseHttp` return `""` on
+  shape-valid-but-unreal dates such as 31 February (regex only proves shape;
+  Temporal validates the real value). Parsers reject; only arithmetic clamps.
+- `parseRfc2822` reads everything RFC 5322 says a receiver must: comments,
+  folding whitespace, any case, two-digit years and zone names such as `EST`
+  (an unknown name reads as `+00:00`). `parseHttp` reads all three HTTP-date
+  forms, including `rfc850-date` and `asctime-date`. Both return `""` when the
+  day name contradicts the date (`"Sat, 15 Mar 2024 …"`), so do not synthesise
+  a day name; omit it. The `rfc2822DateTime` and `httpDate` regexes stay strict
+  and match only what GMT writes, so do not use them to pre-filter parser input.
+- `formatRfc2822`, `formatHttp` and `formatRfc3339` return `""` for a year their
+  grammar cannot hold (before 0000, or after 9999 for RFC 3339 and HTTP).
+  `formatRfc3339` writes a sub-minute historical offset as the same instant at
+  `+00:00`. Use Temporal's `toString()` when you need any year.
+- Text formatters follow ECMA-402 as Temporal amends it, so text equals the
+  `…ToParts` result joined. `era` or `timeZoneName` alone keep the default
+  fields. A plain value never shows a zone name, and a style for fields the type
+  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`.
+- `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.
+- `isLeapYear` and `getWeekNumber` take a `PlainDate` only: a date-time returns
+  `false`/`null`. Pass `value.slice(0, 10)` for a date-time's date.
+- Week numbers are ambiguous across year boundaries — `getIsoWeekDate` returns
+  the week-numbering year with the week so the pair can never drift apart, and
+  `getWeekYear` reads that year on its own.
+- `getLocaleWeekYear` and `getWeeksInLocaleWeekYear` use the ISO rule (`minimalDays` 4)
+  unless you pass `{ minimalDays }`: ECMA-402 no longer exposes a locale's value. CLDR's
+  world default is `1` (`en-US` included), so pass `{ minimalDays: 1 }` for those locales.
+- The `calendar/` identifier functions take a **zoneless** date or datetime. An
+  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".
 - `isWeekend` is locale-aware via `Intl.Locale.weekInfo`; `isBusinessDay` is
-  fixed ISO Mon–Fri with no locale and no holidays.
+  fixed ISO Mon–Fri 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
 
 - [README — API Surface and Quick Start](README.md)
-- [Full API reference](/reference/plain)
+- [Core date operations guides](/guides/core-date-operations/get-current/)

package/skills/gmt-integration/SKILL.md

@@ -2,16 +2,22 @@
 name: gmt-integration
 description: >
   Application integration patterns — stable cache keys, router/query params,
-  table-sort keys, and lint package selection (ESLint, Biome, Oxlint). Reads the
-  installed package README.md and lint-package READMEs for API details; this
-  skill is a routing pointer, not an API dump.
+  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 installed package
+  README.md and lint-package READMEs for API details; this skill is a routing
+  pointer, not an API dump.
 sources:
   - 'northguild/gmt:README.md'
   - 'northguild/gmt:packages/gmt/src/zoned/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/precision/convert/index.ts'
+  - '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'
 metadata:
   type: composition
   library: '@northguild/gmt'
-  library_version: '1.15.0'
+  library_version: '1.16.0'
 ---
 
 # GMT Integration
@@ -23,6 +29,9 @@ which lint package to install for Date-ban enforcement.
 
 - The user asks about cache keys, router params, or table-sort keys for dates.
 - The user wants to validate a timezone id before using it as a cache key.
+- 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 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).
 
@@ -35,11 +44,42 @@ which lint package to install for Date-ban enforcement.
    before using it as a cache key or router param — `"Invalid/Zone"` is a sentinel
    failure, not a real zone.
 3. **Pick one canonical Unix unit.** If you mix epoch seconds and milliseconds,
-   convert explicitly with `convertUtcToUnix` / `convertUtcToUnixMs` rather than
-   dividing/multiplying by hand.
-4. **Lint packages are toolchain-specific, not mutually exclusive.** Recommend
+   convert explicitly with `convertUtcToUnix(value)` (milliseconds) /
+   `convertUtcToUnix(value, { epochUnit: "seconds" })` rather than
+   dividing/multiplying by hand. An `epochUnit` option must be `"seconds"` or
+   `"milliseconds"` (singular accepted): any other value returns the sentinel
+   instead of being read as milliseconds. `unix/` reads zone-dependent fields in
+   UTC unless you pass `timeZone` (`"local"` for the system zone). A
+   blank epoch string is invalid, not `1970`, and `sortUnix`/`minUnix`/`maxUnix`
+   skip values that are not integer epochs in Temporal's range.
+4. **Nanoseconds are `bigint`, never `number`.** A `number` is exact only to
+   `2^53 − 1`, which nanoseconds since the epoch passed in April 1970. Use
+   `toNanoseconds` / `fromNanoseconds`, cross a JSON boundary with
+   `formatNanoseconds` / `parseNanoseconds` (`JSON.stringify` throws on a raw
+   `bigint`), and call `truncateNanoseconds(ns, "us" | "ms")` before writing to a
+   store that holds less than nanoseconds — PostgreSQL `timestamptz` holds
+   microseconds — or the read-back value will not equal what was written.
+5. **Never hand-roll another system's epoch constant.** `precision/convert/` carries
+   the bridges: `toNtpTimestamp` / `fromNtpTimestamp`, `toFileTime` / `fromFileTime`,
+   `toDotNetTicks` / `fromDotNetTicks`, `toExcelSerial` / `fromExcelSerial`,
+   `toPgMicroseconds` / `fromPgMicroseconds`. Two traps they exist to close: an NTP
+   timestamp's seconds field wraps every ~136 years and carries no era, so
+   `fromNtpTimestamp` needs the era passed in; and Excel's serial 60 is the phantom
+   1900-02-29, a date that never existed, so it returns `""` rather than a neighbouring
+   day. Each bridge rejects instants its target format cannot hold instead of returning
+   an out-of-range number. More edges to know:
+   - A `FILETIME` at or above `2^63` is out of range, as Windows'
+     `FileTimeToSystemTime` rules, so `fromFileTime` returns `""`. That includes
+     `0xFFFFFFFFFFFFFFFF`, the "do not modify" marker.
+   - An all-zero NTP timestamp is both the NTP epoch and RFC 5905's "unknown or
+     unsynchronized" marker. Check for `0n` yourself before trusting it as 1900.
+   - .NET ticks name an instant only when `DateTimeKind` is `Utc`. `Local` and
+     `Unspecified` ticks count wall-clock time.
+   - `toNanoseconds` and `isValidInstant` read the offset and ignore a bracketed
+     zone annotation, which is not checked.
+6. **Lint packages are toolchain-specific, not mutually exclusive.** Recommend
    only the one matching the project's existing linter; do not force all three.
-5. **Read the READMEs.** This skill is a routing pointer. For full integration
+7. **Read the READMEs.** This skill is a routing pointer. For full integration
    guidance, read the installed package's `README.md` and the matching
    `@northguild/gmt-eslint` / `gmt-oxlint` / `gmt-biome` README.
 
@@ -65,6 +105,12 @@ the pattern.
 - **Router params**: validate with `isValidDate` / `isValidTimeZone` before use.
 - **Table sorting**: use ISO strings as sort keys for consistent ordering.
 - **State management**: canonicalized strings/numbers at boundaries only.
+- **High-precision timestamps**: keep `bigint` nanoseconds internally, send the
+  decimal string from `formatNanoseconds` over the wire, and truncate to the
+  target column's precision before persisting.
+- **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.
 
 ## References