@northguild/gmt 1.15.0 → 1.16.0

package/README.md

@@ -11,12 +11,14 @@ Give Me Temporal.
 
 It wraps `@js-temporal/polyfill` behind a smaller, more opinionated API aimed at the cases application code actually hits: arithmetic, comparison, parsing, formatting, unix conversions, timezone conversion, and validation.
 
+Read the [docs](https://gmt-dox.northguild.workers.dev/), or ask us on [Discord](https://discord.gg/TdvQdP3t5a).
+
 **Why GMT:**
 
 - **100% Temporal, Temporal-first.** GMT is built directly on the TC39 `Temporal` standard (via `@js-temporal/polyfill`) — not a custom, homegrown date/time type system like `@internationalized/date`'s own `CalendarDate`/`ZonedDateTime` classes. No `Date` object anywhere, enforced by 3 dedicated lint packages.
 - **A full replacement for any and all of them.** Luxon, date-fns, Moment.js, and react-aria's `@internationalized/date` don't have parity with each other — GMT covers the combined capabilities of all four in one library, plus what none of them do alone.
-- **~15× more CI test executions than all four competitors combined**: 334,020 (16,701 tests × 17 locales × 10 timezones × 2 Node versions) vs. their combined 20,190.
-- **~40× more test cases than `@internationalized/date`**: 16,701 vs. 386 — Adobe's own library, run at its own commit.
+- **~54× more CI test executions than all four competitors combined**: 1,090,440 from 36,348 tests run in all 10 timezones × 3 Node versions, vs. their combined 20,190.
+- **~94× more test cases than `@internationalized/date`**: 36,348 vs. 386 — Adobe's own library, run at its own commit.
 - **The only one of the five that tests systematically across locales in CI at all.** Zero of the four comparison libraries run a locale-test matrix; GMT mandates all 17 locales on every locale-aware function.
 - **The only one that runs its entire suite under a real `TZ` env var across real-world zones.** Luxon and `@internationalized/date` have no CI timezone matrix; date-fns's zone scope is unclear; Moment.js covers 6 zones but not its full suite.
 - **Explicit DST disambiguation control on both construction _and_ arithmetic** — a control none of the others expose.
@@ -36,8 +38,8 @@ pnpm add @northguild/gmt
 
 GMT enforces a strict input/output contract to keep behavior predictable and auditable:
 
-- **Explicit inputs only**: Public APIs accept clearly defined shapes — ISO 8601 date/time strings, IANA timezone identifiers, or numeric Unix epoch values (explicitly seconds or milliseconds). We do not attempt to parse arbitrary or ambiguous date formats.
-- **Predictable outputs**: Helpers return normalized values (ISO strings, numbers, booleans, or arrays). Invalid input yields typed fallbacks (`""`, `null`, or `false`) instead of throwing.
+- **Explicit inputs only**: Public APIs accept clearly defined shapes — ISO 8601 date/time strings, IANA timezone identifiers, or Unix epochs as safe integers or digit strings, in seconds or milliseconds (`{ epochUnit }`). We do not attempt to parse arbitrary or ambiguous date formats.
+- **Predictable outputs**: Helpers return normalized values (ISO strings, numbers, booleans, or arrays). Invalid input yields typed fallbacks (`""`, `null`, `false` or `[]`) instead of throwing.
 - **No fuzzy parsing**: Avoid "throw everything at the wall" patterns found in permissive libraries. If you need permissive parsing, perform it outside of `@northguild/gmt` and then canonicalize to the strict shapes before calling into gmt.
 - **Developer comfort with standards**: The library's goal is to make developers comfortable and deliberate with ISO 8601, IANA timezones, UTC instants, and Unix epochs by keeping APIs small and explicit.
 
@@ -59,7 +61,7 @@ Invalid input fallbacks are consistent across the library:
 
 ## Testing
 
-Every function is exercised across **17 locales** and a full IANA timezone matrix. The CI pipeline runs the complete suite in **20 environments** — 2 Node versions (22, 24) × 10 timezones spanning every UTC offset band from Pacific/Niue (−11:00) to Pacific/Apia (+14:00):
+Every function is exercised across **17 locales** and a full IANA timezone matrix. The CI pipeline runs the complete suite in **30 environments** — 3 Node versions (22, 24, 26) × 10 timezones spanning every UTC offset band from Pacific/Niue (−11:00) to Pacific/Apia (+14:00):
 
 | Timezone            | UTC Offset      |
 | ------------------- | --------------- |
@@ -92,7 +94,7 @@ GMT's test suite balances **thoroughness** against **maintenance burden** by tes
 - **Non-string input tables** — functions that guard with `typeof x !== "string"` return the same sentinel for `null`, `undefined`, `123`, `true`, `[]`, and `{}`. We test one representative non-string per argument position rather than all six types × N positions. The collapse is safe because all non-string types hit the identical early-return code path.
 - **Redundant permutations** — adjacent/disjoint/reversed interval cases that produce identical results are not duplicated across every function variant. The `plain/`, `zoned/`, `utc/`, and `unix/` families share the same mathematical behavior; each family gets the minimum set of cases needed to prove correctness.
 
-**Result:** 16,701 tests across 552 files that exercise real behavior differences without redundant permutations. The suite runs in CI as 334,020 executions (16,701 × 2 Node versions × 10 timezones).
+**Result:** 36,348 tests across 663 files that exercise real behavior differences without redundant permutations. They run in CI as 1,090,440 executions — every one of them × 3 Node versions × 10 timezones.
 
 ## How GMT is tested, vs. the libraries it targets
 
@@ -108,11 +110,11 @@ GMT is measured directly against react-aria's **`@internationalized/date`**, **L
 
 | Metric                          | GMT                                                | `@internationalized/date`      | Luxon                                | date-fns                                  | Moment.js                        |
 | ------------------------------- | -------------------------------------------------- | ------------------------------ | ------------------------------------ | ----------------------------------------- | -------------------------------- |
-| Test files                      | 552                                                | 6                              | 58 / 60<br>(2 didn't run<br>locally) | 256                                       | 191<br>(52 core +<br>139 locale) |
-| Individual test cases           | **16,701**                                         | 386                            | 1,222                                | 3,213                                     | 3,901                            |
-| Effective CI test<br>executions | **334,020**<br>(16,701 × 2 Node<br>× 10 timezones) | 386<br>(×1 Node)               | 4,888<br>(1,222 × 4 Node)            | 3,213<br>(×1 Node)                        | 11,703<br>(3,901 × 3 Node)       |
-| CI Node.js matrix               | 22, 24                                             | n/a — tests<br>React 16–canary | 20, 22, 24, 25                       | not explicit<br>(`node = "latest"`)       | LTS, LTS-1,<br>latest            |
-| CI timezone matrix              | **10 zones × 2**<br>**Node, full suite**           | none found                     | none found                           | dedicated workflow,<br>zone scope unclear | 6 zones,<br>partial suite only   |
+| Test files                      | 663                                                | 6                              | 58 / 60<br>(2 didn't run<br>locally) | 256                                       | 191<br>(52 core +<br>139 locale) |
+| Individual test cases           | **36,348**                                         | 386                            | 1,222                                | 3,213                                     | 3,901                            |
+| Effective CI test<br>executions | **1,090,440**<br>(36,348 × 3 Node<br>× 10 timezones) | 386<br>(×1 Node)               | 4,888<br>(1,222 × 4 Node)            | 3,213<br>(×1 Node)                        | 11,703<br>(3,901 × 3 Node)       |
+| CI Node.js matrix               | 22, 24, 26                                         | n/a — tests<br>React 16–canary | 20, 22, 24, 25                       | not explicit<br>(`node = "latest"`)       | LTS, LTS-1,<br>latest            |
+| CI timezone matrix              | **10 zones × 3**<br>**Node, full suite**           | none found                     | none found                           | dedicated workflow,<br>zone scope unclear | 6 zones,<br>partial suite only   |
 | Locale test matrix              | **17 locales**,<br>every locale fn                 | none found                     | none found                           | none found                                | none found                       |
 | Real-browser CI                 | not yet                                            | yes (Playwright)               | not found                            | yes (Playwright)                          | not found                        |
 | Maintenance                     | active                                             | active                         | active                               | active                                    | **maintenance<br>mode**          |
@@ -129,7 +131,7 @@ GMT has **full functional parity** with all four comparison libraries, capabilit
 | Interval/range math<br>(contains, overlap, union,<br>intersection, split, set ops)           | ✅ Done                      | Luxon `Interval`,<br>date-fns `areIntervalsOverlapping`                  |
 | DST disambiguation control<br>on construction _and_ arithmetic                               | ✅ Done — **differentiator** | None of the others expose<br>this on arithmetic                          |
 | Locale-aware calendar helpers<br>(weekend, week start/end, day-of-week)                      | ✅ Done                      | `@internationalized/date`                                                |
-| Business-day arithmetic,<br>clamp/closest, time rounding                                     | ✅ Done                      | `temporal-kit`                                                           |
+| Business-day arithmetic with<br>holiday calendars and roll conventions,<br>clamp/closest, time rounding    | ✅ Done                      | `temporal-kit` (arithmetic only)                                         |
 | Interval rounding-out<br>(boundary count, from-duration)                                     | ✅ Done                      | Luxon                                                                    |
 | Locale calendar metadata<br>(names, `hasDST`)                                                | ✅ Done                      | Luxon `Info`                                                             |
 | Overlap-day count, relative<br>rounding, DST transitions, hours-in-day                       | ✅ Done                      | date-fns, `@internationalized/date`                                      |
@@ -142,40 +144,46 @@ Specific, sourced claims — not a repeat of the metrics above.
 
 | Claim                                                                                                                                         | The others                                                                                                                            |
 | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| Only GMT runs its **entire** suite in CI<br>under a real `TZ` env var across 10<br>real-world zones × 2 Node versions<br>(20 full-suite runs) | Luxon/`@internationalized/date`: no<br>CI timezone matrix. date-fns: zone<br>scope unclear. Moment.js: 6 zones,<br>partial suite only |
+| Only GMT runs its **entire** suite in CI<br>under a real `TZ` env var across 10<br>real-world zones × 3 Node versions<br>(30 full-suite runs) | Luxon/`@internationalized/date`: no<br>CI timezone matrix. date-fns: zone<br>scope unclear. Moment.js: 6 zones,<br>partial suite only |
 | Only GMT enforces a mandatory<br>17-locale test matrix on every<br>locale-aware function                                                      | No CI-level or systematic<br>locale-matrix testing found<br>in any of the four                                                        |
 | Only GMT exposes explicit DST<br>disambiguation control on both<br>construction _and_ arithmetic                                              | Luxon's docs call this explicitly<br>undefined; `@internationalized/date`<br>only covers construction, not arithmetic                 |
 | Only GMT is Temporal-native with<br>zero `Date` usage, enforced by<br>3 dedicated lint packages                                               | Luxon, date-fns, and Moment.js all<br>still wrap or depend on `Date` internally                                                       |
-| GMT's effective CI test<br>executions exceed all four<br>competitors **combined**<br>by ~15×                                                  | 334,020 vs. 386 + 4,888 + 3,213<br>+ 11,703 = 20,190                                                                                  |
+| GMT's effective CI test<br>executions exceed all four<br>competitors **combined**<br>by ~54×                                                  | 1,090,440 vs. 386 + 4,888 + 3,213<br>+ 11,703 = 20,190                                                                                  |
 
 ## Package Layout
 
-The package exports seven top-level namespaces:
+Every public function, type and regex is a flat named export of the package root, beside
+`Temporal`, `Intl` and `toTemporalInstant` re-exported from `@js-temporal/polyfill`. There are no
+namespace objects: a namespace is a subpath.
 
 ```typescript
-import {
-  Temporal,
-  duration,
-  plain,
-  zoned,
-  unix,
-  utc,
-  regex,
-} from "@northguild/gmt";
+import { addDate, getNow, formatRelativeZoned, Temporal } from "@northguild/gmt";
 ```
 
-- `Temporal`: re-exported from `@js-temporal/polyfill`
-- `duration`: ISO 8601 duration string parsing, validation, and arithmetic
-- `plain`: timezone-free helpers
-- `zoned`: timezone-aware helpers
-- `unix`: Unix epoch (seconds or milliseconds) helpers
-- `utc`: UTC instant helpers
-- `regex`: low-level regex building blocks
+The twelve namespace subpaths:
+
+- `@northguild/gmt/calendar`: ISO week and ordinal dates, quarter and fiscal periods, zone-aware bucketing, and business calendars with holiday sets and roll conventions
+- `@northguild/gmt/duration`: ISO 8601 duration string parsing, validation, and arithmetic
+- `@northguild/gmt/instant`: the instant-plus-offset pair, and explicit resolution of zoneless local wall times
+- `@northguild/gmt/interval`: half-open `[start, end)` interval algebra over instants — overlap, intersect, clamp, merge, subtract, split, sum
+- `@northguild/gmt/plain`: timezone-free helpers
+- `@northguild/gmt/precision`: nanosecond (`bigint`) instants, their JSON bridge, storage truncation, and foreign epoch bridges
+- `@northguild/gmt/span`: elapsed and wall-clock durations between two timestamps, as raw numbers
+- `@northguild/gmt/zoned`: timezone-aware helpers
+- `@northguild/gmt/unix`: Unix epoch (seconds or milliseconds) helpers
+- `@northguild/gmt/utc`: UTC instant helpers
+- `@northguild/gmt/regex`: low-level regex building blocks
+- `@northguild/gmt/types`: the shared option and unit types
+
+Every namespace subpath except `types` also re-exports `Temporal`, `Intl` and `toTemporalInstant`, so `import { Temporal, addZoned } from "@northguild/gmt/zoned"` needs no second import.
 
-You can also import subpaths directly:
+Every namespace except `regex` and `types` also exposes its modules as subpaths,
+`@northguild/gmt/<namespace>/<module>`:
 
 ```typescript
-import { addDate, getNow, formatRelativeZoned } from "@northguild/gmt";
+import { getZonedNow } from "@northguild/gmt/zoned";
+import { addDateTime, diffDate } from "@northguild/gmt/plain/calculate";
+import type { BusinessCalendar } from "@northguild/gmt/types";
 ```
 
 ## Quick Start
@@ -192,8 +200,8 @@ import {
   isBeforeDateTime,
 } from "@northguild/gmt";
 
-addDate("2026-01-01", 90, "day");
-// "2026-03-32" is impossible, so Temporal normalizes correctly -> "2026-04-01"
+addDate("2026-01-01", { days: 90 });
+// "2026-04-01"
 
 addBusinessDays("2024-03-15", 1);
 // "2024-03-18" (skips weekend)
@@ -201,7 +209,7 @@ addBusinessDays("2024-03-15", 1);
 subtractBusinessDays("2024-03-18", 1);
 // "2024-03-15" (skips weekend)
 
-diffDateTime("2024-03-17T12:00:00", "2024-03-17T12:30:00", "minute");
+diffDateTime("2024-03-17T12:00:00", "2024-03-17T12:30:00", "minutes");
 // 30
 
 areDatesEqual("2026-03-17", "2026-03-17T09:00:00");
@@ -211,7 +219,7 @@ isBeforeDateTime("2026-03-17T09:00:00", "2026-03-17T10:00:00");
 // true
 ```
 
-`add*`/`subtract*` accept an optional `overflow` (`"constrain"` (default) | `"reject"`) to control out-of-range results (e.g. adding a month to Jan 31), and `diff*` accept optional `smallestUnit`/`roundingIncrement`/`roundingMode` to round the computed difference:
+`add*`/`subtract*` accept an optional `overflow` (`"constrain"` (default) | `"reject"`) to control out-of-range results (e.g. adding a month to Jan 31) — except `addTime`/`subtractTime`, which take no options argument because a clock time wraps (`addTime("23:00:00", { hours: 2 })` is `"01:00:00"`), as Temporal's `PlainTime#add` does — and `diff*` accept optional `smallestUnit`/`roundingIncrement`/`roundingMode` to round the computed difference:
 
 ```typescript
 import { addDate, diffDate } from "@northguild/gmt";
@@ -219,7 +227,10 @@ import { addDate, diffDate } from "@northguild/gmt";
 addDate("2024-01-31", { months: 1 }, { overflow: "reject" });
 // "" — Feb 31 doesn't exist and overflow: "reject" refuses to clamp it
 
-diffDate("2023-01-01", "2023-01-10", "week", {
+addDate("2024-02-29", { years: 1 });
+// "2025-02-28" — "constrain" (the default) clamps to the last valid day, as Temporal does
+
+diffDate("2023-01-01", "2023-01-10", "weeks", {
   smallestUnit: "week",
   roundingMode: "halfExpand",
 });
@@ -237,14 +248,20 @@ setDate("2024-01-31", { month: 2 });
 setZoned(
   "2024-11-03T01:45:00-05:00[America/New_York]",
   { minute: 0 },
-  {
-    disambiguation: "reject",
-  },
+  { disambiguation: "reject" },
 );
-// "" — offset defaults to "ignore" so disambiguation actually fires on this fall-back overlap
+// "2024-11-03T01:00:00-05:00[America/New_York]" — offset defaults to "prefer", as Temporal's
+// ZonedDateTime#with does: the source's -05:00 is still valid, so it is kept
+
+setZoned(
+  "2024-11-03T01:45:00-05:00[America/New_York]",
+  { minute: 0 },
+  { disambiguation: "reject", offset: "ignore" },
+);
+// "" — offset "ignore" re-resolves the repeated 01:00, and "reject" fires on the fall-back overlap
 ```
 
-`setZoned`/`setUnix`/`setUtc` also accept `disambiguation` and `offset` for DST gap/overlap control — see [DST Disambiguation](../../docs/dst-disambiguation.md).
+`setZoned`/`setUnix` also accept `disambiguation` and `offset` for DST gap/overlap control (`setUtc` takes only `overflow`: a UTC wall clock is never ambiguous) — see [DST Disambiguation](../../docs/dst-disambiguation.md).
 
 `cycleDate`/`cycleDateTime`/`cycleTime`/`cycleZoned` adjust a single field and **wrap** at that field's own min/max instead of carrying into the next larger field — the datepicker-segment-editing primitive `add*` can't express, since overflowing into the next field is exactly what `add*` is for:
 
@@ -262,9 +279,9 @@ cycleZoned("2024-03-10T01:30:00-06:00[America/Chicago]", "hour", 1);
 // gap; disambiguation ("compatible" by default) resolves it the same way setZoned does
 ```
 
-`cycleZoned` also accepts `disambiguation` and `offset` (default `offset: "ignore"`) for the same DST gap/overlap control as `setZoned` — see [DST Disambiguation](../../docs/dst-disambiguation.md). `options.round` on any of the four steps to the next multiple of `amount` rather than rounding to the nearest one, matching `@internationalized/date`'s `CycleOptions.round`.
+`cycleZoned` also accepts `disambiguation` and `offset` (default `offset: "prefer"`) for the same DST gap/overlap control as `setZoned` — see [DST Disambiguation](../../docs/dst-disambiguation.md). `options.round` on any of the four steps to the next multiple of `amount` rather than rounding to the nearest one, matching `@internationalized/date`'s `CycleOptions.round`.
 
-`isWeekend`/`isZonedWeekend` check locale-specific weekend days (via `Intl.Locale`'s `weekInfo`) rather than assuming Saturday/Sunday:
+`isWeekend`/`isZonedWeekend` check locale-specific weekend days (via `Intl.Locale#getWeekInfo()`, falling back to `weekInfo`) rather than assuming Saturday/Sunday:
 
 ```typescript
 import { isWeekend, isZonedWeekend } from "@northguild/gmt";
@@ -279,7 +296,7 @@ isZonedWeekend("2024-02-04T10:00:00+02:00[Asia/Jerusalem]", "he-IL");
 // false (Sunday isn't part of he-IL's weekend)
 ```
 
-`isBusinessDay` returns true for fixed ISO Monday–Friday business days (Mon=1 … Fri=5), locale-agnostic and with no holiday calendar. It's the complement to locale-aware `isWeekend` and matches the boundary that `addBusinessDays`/`subtractBusinessDays` use:
+`isBusinessDay` is the complement to locale-aware `isWeekend`, and shares its weekend rule with `addBusinessDays`/`subtractBusinessDays`. Called with one argument it uses fixed ISO Monday–Friday business days (Mon=1 … Fri=5), locale-agnostic and with no holidays; pass a `BusinessCalendar` to state the weekend and holidays yourself:
 
 ```typescript
 import { isBusinessDay } from "@northguild/gmt";
@@ -289,8 +306,81 @@ isBusinessDay("2024-02-05");
 
 isBusinessDay("2024-02-10");
 // false (Saturday)
+
+isBusinessDay("2024-07-04", {
+  weekend: [6, 7],
+  holidays: ["2024-07-04"],
+  timeZone: "America/New_York",
+});
+// false (a holiday, though it's a Thursday)
 ```
 
+### Business calendars and roll conventions
+
+A `BusinessCalendar` is `{ weekend: number[], holidays: string[], timeZone: string }`. The weekend is explicit ISO weekday numbers because Saturday–Sunday is not universal — much of the Middle East is Friday–Saturday, and some markets keep a one-day weekend. Holidays are yours to supply: GMT bundles no holiday table on the default import path, because holiday data is jurisdictional and changes annually, sometimes with days of notice. `timeZone` records which locality the calendar describes; the business-day functions take and return local dates and never read it, so a caller holding an instant reduces it with `floorToZone` first.
+
+`isBusinessDay`, `addBusinessDays` and `subtractBusinessDays` all take a calendar as an optional trailing argument. The rest of the family requires one — there is no default weekend to fall back on:
+
+```typescript
+import {
+  businessDaysBetween,
+  nextBusinessDay,
+  previousBusinessDay,
+  rollDate,
+  mergeCalendars,
+  isValidBusinessCalendar,
+} from "@northguild/gmt";
+
+const nyse = {
+  weekend: [6, 7],
+  holidays: ["2024-05-31", "2024-07-04"],
+  timeZone: "America/New_York",
+};
+
+businessDaysBetween("2024-07-01", "2024-07-05", nyse);
+// 3 — start exclusive, end inclusive, and 4 July is a holiday
+
+nextBusinessDay("2024-07-03", nyse);
+// "2024-07-05" — strictly after, skipping the holiday
+
+previousBusinessDay("2024-07-05", nyse);
+// "2024-07-03"
+```
+
+`rollDate` moves a date onto a working day by an explicit convention — `following`, `modifiedFollowing`, `preceding`, `modifiedPreceding`, `endOfMonth` or `none`. `following` and `preceding` are on-or-after and on-or-before, so they leave a working day alone; `nextBusinessDay`/`previousBusinessDay` are the strict neighbours:
+
+```typescript
+rollDate("2024-05-31", "following", nyse);
+// "2024-06-03" — forward past the weekend
+
+rollDate("2024-05-31", "modifiedFollowing", nyse);
+// "2024-05-30" — backward instead, because forward leaves May
+
+rollDate("2024-03-15", "endOfMonth", nyse);
+// "2024-03-29" — March's last working day; March ends on a Sunday
+
+rollDate("2024-06-01", "none", nyse);
+// "2024-06-01" — unadjusted, Saturday or not
+```
+
+`mergeCalendars` composes jurisdictions: weekend rules and holidays union, so a date survives only if it is a working day in **every** input. That is the two-currency intersection FX settlement needs, and the two-port one an intermodal move needs:
+
+```typescript
+const london = { weekend: [6, 7], holidays: ["2024-05-06"], timeZone: "Europe/London" };
+
+const both = mergeCalendars([nyse, london]);
+// { weekend: [6, 7], holidays: ["2024-05-06", "2024-05-31", "2024-07-04"], timeZone: "America/New_York" }
+// timeZone is the first calendar's; the merged set spans localities that may disagree
+
+isBusinessDay("2024-05-06", both);
+// false — a UK holiday closes the merged calendar too
+
+mergeCalendars([]);
+// null
+```
+
+`isValidBusinessCalendar` and `isValidRollConvention` narrow a candidate, so a misconfigured calendar or contract term can be told apart from bad date input when a function returns its sentinel.
+
 `isRelativeDay`/`isThisUnit`/`isPast`/`isFuture` are now-relative predicates — `isRelativeDay` subsumes `isToday`/`isYesterday`/`isTomorrow`, `isThisUnit` subsumes `isThisWeek`/`isThisMonth`/`isThisYear`. They compare against `getToday()`, so they depend on the **system clock and system timeZone**; the zoned variants (`isZonedRelativeDay`, `isZonedThisUnit`, `isZonedPast`, `isZonedFuture`) resolve "today"/"now" in the value's own timeZone instead, for deterministic results regardless of the host machine's timeZone:
 
 ```typescript
@@ -375,8 +465,8 @@ getLocaleDayOfWeek("2024-02-25", "en-US");
 getLocaleDayOfWeek("2024-02-26", "fr-FR");
 // 0 (Monday = first day of fr-FR week)
 
-getLocaleDayOfWeek("2024-02-24", "he-IL");
-// 0 (Saturday = first day of he-IL week)
+getLocaleDayOfWeek("2024-02-24", "ar-EG");
+// 0 (Saturday = first day of ar-EG week)
 
 getLocaleZonedDayOfWeek("2024-02-25T12:00:00+00:00[UTC]", "en-US");
 // 0
@@ -447,153 +537,127 @@ Supported tokens include `yyyy`/`MM`/`dd`/`HH`/`mm`/`ss`/`SSS` for fixed-width f
 
 ### Calendar systems
 
-GMT's `CalendarSystem` type (`"gregorian" | "hebrew" | "islamic-civil" | "islamic-tabular" | "islamic-umalqura" | "japanese" | "buddhist" | "taiwan" | "persian" | "indian" | "ethiopic" | "ethiopic-amete-alem" | "coptic"`, extended by later stories) and `convertDateToCalendar` express a date in a non-Gregorian calendar system, built almost entirely on Temporal's native calendar support — no bundled leap-year tables or ported arithmetic, with one deliberate exception (the Ethiopic family, covered below).
+`convertDateToCalendar` expresses a date in another calendar system. GMT writes the standard form, exactly what `Temporal.PlainDate.prototype.toString()` writes: the ISO 8601 date, then an RFC 9557 `[u-ca=<id>]` annotation naming the calendar. The digits stay ISO. The annotation says which calendar the date is presented and computed in (RFC 9557 §3.3), so the string means the same date to GMT, to Temporal and to any other RFC 9557 parser.
 
 ```typescript
 import { convertDateToCalendar } from "@northguild/gmt";
 
 convertDateToCalendar("2024-10-03", "hebrew");
-// "5785-01-01[u-ca=hebrew]" — Rosh Hashanah 5785
+// "2024-10-03[u-ca=hebrew]" — Rosh Hashanah 5785, written as its ISO date
 
-convertDateToCalendar("5785-01-01[u-ca=hebrew]", "gregorian");
-// "2024-10-03" — round-trips back
+convertDateToCalendar("2024-10-03[u-ca=hebrew]", "iso8601");
+// "2024-10-03" — iso8601 writes no annotation
 
-convertDateToCalendar("2024-10-03", "islamic-umalqura");
-// "1446-03-30[u-ca=islamic-umalqura]" — Saudi Umm al-Qura calendar
+convertDateToCalendar("2024-10-03", "gregory");
+// "2024-10-03[u-ca=gregory]" — gregory is its own calendar, so it is annotated
 
 convertDateToCalendar("invalid", "hebrew");
 // ""
 ```
 
-The output string shape is the key design decision here, and it deliberately **diverges from Temporal's own** `[u-ca=...]` convention. Temporal's `Temporal.PlainDate.prototype.toString()` always keeps the ISO/proleptic-Gregorian year-month-day digits and only tags the calendar (`"2024-10-03[u-ca=hebrew]"` — still literally October 3rd's Gregorian digits). That hides the calendar's own fields behind calendar-aware accessors, which GMT's string-only contract has no place for. GMT's annotated string instead carries the **calendar-native** year/month/day — Hebrew year 5785, not 2024 — so the calendar-system concept is visible directly in the string, not just in an object property. A plain, unannotated ISO string is always treated as (and always produced for) the `"gregorian"` calendar, so every existing GMT function keeps working unchanged.
-
-Hebrew years can run 12 or 13 months (7 leap years per 19-year Metonic cycle insert a 13th month, Adar I, before the regular Adar); `convertDateToCalendar` resolves this the same way Temporal does internally, via ordinal month numbers (`1`-`13`) rather than fixed month names, so no month-counting logic lives in GMT itself.
+`CalendarSystem` is `"iso8601" | "gregory" | "hebrew" | "islamic-civil" | "islamic-tbla" | "islamic-umalqura" | "japanese" | "buddhist" | "roc" | "persian" | "indian" | "ethiopic" | "ethioaa" | "coptic"`: the canonical BCP 47 / CLDR `calendar.xml` ids Temporal uses, in the annotation and as function arguments. An alias or another letter case is canonicalized the way Temporal's `withCalendar` does it (`"ethiopic-amete-alem"` writes `[u-ca=ethioaa]`, `[u-ca=HEBREW]` reads as `hebrew`), and the canonical id is always written. `gregorian`, `taiwan` and `islamic-tabular` are not calendar ids, so they return the sentinel. `chinese`, `dangi`, `islamic` and `islamic-rgsa` are not supported.
 
-Three Islamic (Hijri) calendar variants are supported, and they are **not interchangeable** — each resolves the same Gregorian date to different calendar-native digits:
+Every calendar-accepting function reads annotations the way `Temporal.PlainDate.from` / `Temporal.ZonedDateTime.from` read them. The critical flag is accepted and not written back (`"2024-10-03[!u-ca=hebrew]"` converts to `"2024-10-03[u-ca=hebrew]"`), and an unknown critical annotation is rejected. `;era=` is not RFC 9557 syntax and is rejected. A year is four digits, or a sign and six (`"+275760-09-13[u-ca=hebrew]"`), across Temporal's whole range, `-271821-04-19` to `+275760-09-13`.
 
-- `"islamic-civil"` — a fixed 30-year leap-year cycle, Friday epoch (`1 AH = 622-07-19`).
-- `"islamic-tabular"` — the same style of fixed arithmetic cycle, but a Thursday epoch one day earlier (`1 AH = 622-07-18`); maps to Temporal's `"islamic-tbla"` calendar id internally, though GMT's own string annotation always reads `[u-ca=islamic-tabular]`.
-- `"islamic-umalqura"` — the Saudi civil calendar, based on Umm al-Qura University's own published tables rather than a fixed arithmetic rule. This is **not** approximated by the tabular variant's math — `convertDateToCalendar("2020-02-24", "islamic-umalqura")` returns `"1441-06-30[u-ca=islamic-umalqura]"` while the same input under `"islamic-tabular"` returns `"1441-07-01[u-ca=islamic-tabular]"`, a genuine one-day divergence, not a rounding difference.
+**Calendar fields are read values, never string content.** The Hebrew year 5785, the Japanese era `reiwa` and year 6, and the Umm al-Qura day number are all properties of the date, so GMT never puts them in a string. No standard defines a machine-readable date string with calendar-native digits, and such a string would be ambiguous: `5785-01-01[u-ca=hebrew]` is also a valid RFC 9557 string for ISO year 5785. When you need a field for display, format the date with `Intl.DateTimeFormat` and its `calendar` option, or read it from Temporal, which every GMT entry point re-exports:
 
-Five era-based solar calendars round out the set. Unlike Hebrew and the Islamic variants, none of these needed new leap-year logic — each is either Gregorian-shaped with a different year numbering layered on top, or a distinct-but-simple solar calendar, so they were materially less work than Hebrew or Islamic:
+```typescript
+import { Temporal } from "@northguild/gmt";
 
-- `"buddhist"` — Gregorian day/month structure, a fixed `+543` year offset (`convertDateToCalendar("2024-10-03", "buddhist")` → `"2567-10-03[u-ca=buddhist]"`). One continuous era, no reset.
-- `"taiwan"` — Gregorian day/month structure, year numbering reset at 1912 (the Republic of China's founding): `2024` → `"0113-10-03[u-ca=taiwan]"` (`2024 - 1911`). Dates before 1912 count backward through Temporal's inverse era instead of going negative in the way a plain offset would — `convertDateToCalendar("1911-12-31", "taiwan")` is `"0000-12-31[u-ca=taiwan]"`, not `"-0001-12-31"`.
-- `"persian"` — a genuinely distinct solar calendar (not Gregorian-derived): own month lengths (6 months of 31 days, 5 of 30, a 29/30-day 12th month) and its own 33-year leap-year cycle (a year is leap when `(25 × year + 11) mod 33 < 8`), verified against `@internationalized/date`'s `PersianCalendar.ts` rather than assumed from the offset-only calendars above.
-- `"indian"` — the Indian National Calendar (Saka era, epoch 78 CE). Also not offset-only: its leap-year alignment follows the Gregorian rule rather than an independent cycle — the calendar's first month is 31 days in a Gregorian leap year, 30 otherwise, which is why its Saka-year boundary (`convertDateToCalendar("2024-03-20", "indian")` → `"1945-12-30[u-ca=indian]"`, `convertDateToCalendar("2024-03-21", "indian")` → `"1946-01-01[u-ca=indian]"`) doesn't land on a fixed day-of-year every year.
-- `"japanese"` — era-based: the year resets to `1` at each imperial era change (Meiji, Taishō, Shōwa, Heisei, Reiwa). This is the one calendar where GMT's annotated string carries an era-relative year instead of the calendar's plain native year, and needs its own explanation below.
+Temporal.PlainDate.from("2024-10-03[u-ca=hebrew]").year; // 5785
+Temporal.PlainDate.from("2024-10-03[u-ca=japanese]").eraYear; // 6
+```
 
-**Why `"japanese"` gets a different string shape.** Every other supported calendar's plain `year` field is exactly what belongs in GMT's annotated string — Hebrew year 5785, Taiwan year 113, and so on are each already the single number that identifies the year. Japanese is the exception: Temporal's `.year` for the `"japanese"` calendar stays **proleptic** across era changes (it doesn't reset — `1912-07-30`, the first day of Taishō, still reports `.year === 1912`, not `1`), because Temporal's `.year` is designed to be a stable sort key, not a display value. Using it directly would silently contradict the calendar's entire reason for existing. So `convertDateToCalendar` uses Temporal's `.eraYear` (the field that _does_ reset) paired with the era name, tagged onto the annotation as `;era=<name>`:
+The three Islamic variants are different calendars, not spellings of one. On ISO 2020-02-24, `islamic-civil` (Friday epoch) reads day 29 of month 6 of 1441, `islamic-tbla` (the same arithmetic cycle with a Thursday epoch) reads day 1 of month 7, and `islamic-umalqura` (the Saudi civil calendar, from Umm al-Qura University's published tables) reads day 30 of month 6. Month arithmetic follows each calendar's own months, so the same `+1 month` lands on different ISO dates:
 
 ```typescript
-convertDateToCalendar("2024-10-03", "japanese");
-// "0006-10-03[u-ca=japanese;era=reiwa]" — year 6 of the Reiwa era, not the proleptic 2024
+import { addDate } from "@northguild/gmt";
 
-convertDateToCalendar("1912-07-30", "japanese");
-// "0001-07-30[u-ca=japanese;era=taisho]" — the first day of Taishō reads year 1
+addDate("2020-02-24[u-ca=islamic-umalqura]", { months: 1 });
+// "2020-03-24[u-ca=islamic-umalqura]"
 
-convertDateToCalendar("0001-07-30[u-ca=japanese;era=taisho]", "gregorian");
-// "1912-07-30" — round-trips back through the era + eraYear pair
+addDate("2020-02-24[u-ca=islamic-tbla]", { months: 1 });
+// "2020-03-25[u-ca=islamic-tbla]"
 ```
 
-`@internationalized/date` documents pre-Meiji (before 1868-10-23) dates as unsupported for its Japanese calendar. GMT does not replicate that restriction: since `convertDateToCalendar` is built entirely on Temporal's own calendar support rather than a ported implementation, and Temporal resolves those dates correctly under a synthetic `"japanese"` era (with an ISO-aligned `eraYear`), rejecting them would mean writing new validation solely to reproduce another library's gap rather than an actual GMT limitation. `convertDateToCalendar("1800-01-01", "japanese")` returns `"1800-01-01[u-ca=japanese;era=japanese]"` rather than `""`.
+`ethiopic` and `coptic` compute in `ethioaa`. The three share months, days and arithmetic and differ only by a constant year offset, and `@js-temporal/polyfill` 0.5.1 throws reading `ethiopic` and `coptic` fields under ICU 78 or later (`Temporal.PlainDate.from("2024-10-03[u-ca=ethiopic]").year` throws there). GMT's results are the same either way, and only the written id differs. Where the polyfill or the runtime's ICU computes a calendar wrongly (Buddhist before 1582, Hebrew years ≤ 0, Indian dates before ISO year 1, dates near either range limit), GMT's arithmetic computes the specified answer instead. Each correction probes the runtime once and stays inactive where the runtime is already right.
 
-Three Ethiopic-family calendars round out the set, all sharing one 13-month structure (12 months of 30 days, plus a short Pagume/Nasie 13th month of 5 days, or 6 in a leap year) but differing in epoch:
+#### Calendar-aware interval and duration arithmetic
 
-- `"ethiopic"` — the modern Ethiopian calendar, era-based like `"japanese"`: it resets to the Amete Mihret ("Year of Mercy"/Incarnation) era at its own epoch (~AD 8), so `convertDateToCalendar("2024-10-03", "ethiopic")` returns `"2017-01-23[u-ca=ethiopic;era=ethiopic]"` — year 2017, not a 5-digit proleptic number. Dates before that epoch resolve under the Amete Alem ("Year of the World") era instead: `convertDateToCalendar("0001-01-01", "ethiopic")` → `"5493-05-08[u-ca=ethiopic;era=ethioaa]"`.
-- `"ethiopic-amete-alem"` — the same calendar, but always counted continuously from the Amete Alem epoch (~5493 BCE), never resetting: `convertDateToCalendar("2024-10-03", "ethiopic-amete-alem")` → `"7517-01-23[u-ca=ethiopic-amete-alem]"`.
-- `"coptic"` — the Coptic Orthodox calendar: same 13-month structure, its own epoch (the Diocletian/Martyrs era, AD 284): `convertDateToCalendar("2024-10-03", "coptic")` → `"1741-01-23[u-ca=coptic]"`.
+A calendar-annotated date feeds `addDate`/`subtractDate`/`diffDate`/`diffDateAsDuration` and every `Date`-suffixed `plain/interval/*` function (`intervalContainsDate`, `intervalCountDate`, `splitIntervalByUnitDate`, and the rest). Calendar units ("add 1 month") resolve in the value's own calendar:
 
-**Why this family isn't built on Temporal's native `"ethiopic"`/`"coptic"` calendar ids, unlike every other calendar above.** `@js-temporal/polyfill`'s implementation of these two calendars resolves year/era by formatting the date through `Intl.DateTimeFormat` and matching the result against a hardcoded era-name table — unlike calendars with a fixed year-offset from ISO (Buddhist, Taiwan, and Ethiopic Amete Alem, which the polyfill computes with pure arithmetic and never touches `Intl` for). CLDR's era-name output for these two calendars changed between ICU versions: under ICU ≥ 78 (the version Node 22 and 24 both bundle — this is an ICU-version boundary, not a Node-major one), every read _or_ write of Temporal's `"ethiopic"`/`"coptic"` calendar ids throws a `RangeError` (`Era am (ISO year …) was not matched by any era`) — confirmed directly, not a hypothetical. `"ethiopic-amete-alem"` (Temporal's `"ethioaa"` id) is unaffected, since it has no era at all and is resolved with pure arithmetic. GMT routes around the bug rather than inheriting it: month/day are identical across all three calendars (they share one annual cycle), so `convertDateToCalendar` reads/writes them via the safe `"ethioaa"` calendar and computes each calendar's own displayed year (+ era, for `"ethiopic"`) with GMT-owned arithmetic — ported from the same `EthiopicHelper`/`CopticHelper` epoch constants `@js-temporal/polyfill` itself uses internally, just evaluated in GMT's code instead of through the ICU-dependent path. See `internal/ethiopicFamilyCalendar.ts` for the implementation.
+```typescript
+import { addDate, diffDate, diffDateAsDuration, durationAs, intervalCountDate } from "@northguild/gmt";
 
-#### Calendar-aware interval and duration arithmetic
+addDate("2024-02-24[u-ca=hebrew]", { months: 1 });
+// "2024-03-25[u-ca=hebrew]" — 15 Adar I 5784 to 15 Adar II; addDate("2024-02-24", { months: 1 }) is "2024-03-24"
 
-`convertDateToCalendar`'s output feeds directly back into `addDate`/`subtractDate`/`diffDate`/`diffDateAsDuration` and every `Date`-suffixed `plain/interval/*` function (`intervalContainsDate`, `intervalCountDate`, `splitIntervalByUnitDate`, and the rest) — calendar-unit arithmetic ("add 1 month") resolves in the value's own calendar rather than being rejected or silently treated as Gregorian:
+intervalCountDate("2023-09-16[u-ca=hebrew]", "2024-10-03[u-ca=hebrew]", "month");
+// 13 — Hebrew leap year 5784 has 13 months; the same ISO span touches 14 ISO months
 
-```typescript
-addDate("5784-06-15[u-ca=hebrew]", { months: 1 });
-// "5784-07-15[u-ca=hebrew]" — Adar I (a leap-only 30-day month) -> Adar
+diffDate("2024-03-11[u-ca=hebrew]", "2024-04-10[u-ca=hebrew]", "months");
+// 1 — 1 Adar II to 2 Nisan; the bare ISO dates are 0 whole months apart
 
-intervalCountDate(
-  "5784-01-01[u-ca=hebrew]",
-  "5785-01-01[u-ca=hebrew]",
-  "month",
-);
-// 13 — a Hebrew leap year crosses 13 month boundaries, not 12 (ISO's answer for the same span)
+diffDateAsDuration("2024-08-31[u-ca=buddhist]", "2024-09-30[u-ca=buddhist]", "months");
+// "P30D" — not "P1M": a month counts only once the end reaches the same day of the next month
 
-diffDate("5784-06-15[u-ca=hebrew]", "5784-07-15[u-ca=hebrew]", "months");
-// 1 — measured in the shared calendar when both endpoints carry the same tag
+durationAs("P1Y", "days", { relativeTo: "2023-09-16[u-ca=hebrew]" });
+// 383 — Hebrew leap year 5784; relativeTo "2023-09-16" gives 366
 ```
 
-`utc/` and `unix/` reject a `[u-ca=...]` calendar annotation outright, and `duration/`'s `relativeTo` option accepts GMT's calendar-annotated string (not Temporal's own differently-shaped `[u-ca=...]` convention) when a calendar-aware anchor is needed:
+Month and year differences follow Temporal's `NonISODateSurpasses` in every calendar, so a span from a month's last day into a shorter month is days, not a month. This matches the ISO calendar (`diffDateAsDuration("2024-08-31", "2024-09-30", "months")` is `"P30D"`), and applies to `diffDate*`, `intervalLength*`, `intervalCount*` and `diffZoned*` alike.
 
-```typescript
-durationAs("P1Y", "days", { relativeTo: "5784-06-15[u-ca=hebrew]" });
-// 385 — a Hebrew leap year, not the 366 a Gregorian P1Y would total
-```
+`utc/` reads a UTC string as `Temporal.Instant.from` does, so a `[u-ca=...]` annotation is ignored there: `isValidUtc("2024-01-01T00:00:00Z[u-ca=hebrew]")` is `true`. `duration/`'s `relativeTo` reads a calendar-annotated string as Temporal's `ParseTemporalRelativeToString` does: zoned when it carries a time zone annotation, otherwise a date.
+
+Two values that name different calendars follow Temporal's `CalendarEquals`. A bare ISO string names `iso8601`.
 
-`zoned/` has its own calendar-annotated grammar as of E7 (issue #152) — see "Calendar-aware zoned datetimes" below.
+- **Differences return the sentinel** on a mismatch, as Temporal's `until` throws: `diffDate`, `diffDateAsDuration`, `intervalCountDate`, `intervalLengthDate`, `splitIntervalByUnitDate` and `intervalOverlappingDaysDate`.
+- **Ordering accepts mixed calendars**, as `Temporal.PlainDate.compare` has no calendar check: `intervalContainsDate`, `intervalsOverlapDate`, `intervalAbutsDate`, `intervalEngulfsDate` and `isValidDateInterval`.
+- **Functions that return a date value** (`intervalUnionDate`, `intervalIntersectionDate`, `intervalDifferenceDate`, `intervalXorDate`, `intervalXorAllDate`, `mergeIntervalsDate`, `intervalDivideEquallyDate`, `intervalSplitAtDate`) require one shared calendar and return `null`/`[]` on a mismatch, because no calendar can be chosen for the output.
+
+```typescript
+intervalCountDate("2023-09-16[u-ca=hebrew]", "2024-10-03", "month");
+// null — hebrew and iso8601
 
-Interval functions that only compare or diff absolute instants (`intervalContainsDate`, `intervalsOverlapDate`, `intervalAbutsDate`, `intervalEngulfsDate`, `isValidDateInterval`, `intervalOverlappingDaysDate`) accept endpoints tagged with _different_ calendars, since ordering and day-counting don't depend on which calendar a date is expressed in. Functions that return a date _value_ (`intervalUnionDate`, `intervalIntersectionDate`, `intervalDifferenceDate`, `intervalXorDate`, `intervalXorAllDate`, `mergeIntervalsDate`, `intervalDivideEquallyDate`, `intervalSplitAtDate`) require every argument to share one calendar and return their sentinel (`null`/`[]`) on a mismatch, since there's no principled way to pick which calendar the output should be expressed in. See `context/roadmap/issues/E.md`'s "E5 outcome" section for the full per-function audit, including the negatives ("no change needed, verified why") this scope boundary implies — `*DateTime`/`*Time` variants, `unix/`, and `utc/` were all confirmed unaffected rather than assumed to be.
+intervalContainsDate("2023-09-16[u-ca=hebrew]", "2024-10-03", "2024-01-01[u-ca=roc]");
+// true — ordering compares the ISO dates
+```
 
 #### Calendar-aware zoned datetimes
 
-A calendar-annotated `ZonedDateTime` string adds a time, a UTC offset and an IANA zone to the
-plain grammar above:
+A calendar-annotated `ZonedDateTime` string is the RFC 9557 form `Temporal.ZonedDateTime.prototype.toString()` writes: the time zone annotation first, then the calendar (RFC 9557 §4.1):
 
 ```
-<calendar-native-date>T<time><offset>[u-ca=<id>[;era=<era>]][<timeZone>]
+<date>T<time><offset>[<timeZone>][u-ca=<id>]
 
-5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]
-0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]
-7517-12-30T00:30:00-04:00[u-ca=ethiopic-amete-alem][America/Santiago]
+2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]
+2019-04-30T12:00:00+09:00[Asia/Tokyo][u-ca=japanese]
 ```
 
-`convertZonedToCalendar` produces it, and `isValidCalendarZonedDateTime` validates it:
+`convertZonedToCalendar` produces it, and `isValidCalendarZonedDateTime` validates it. A calendar annotation before the zone is not RFC 9557 and returns the sentinel:
 
 ```typescript
+import { addZoned, convertZonedToCalendar } from "@northguild/gmt";
+
 convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "hebrew");
-// "5785-01-01T14:30:45-04:00[u-ca=hebrew][America/New_York]"
+// "2024-10-03T14:30:45-04:00[America/New_York][u-ca=hebrew]"
 
-addZoned("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]", {
-  months: 1,
-});
-// "5784-07-15T14:30:00-04:00[u-ca=hebrew][America/New_York]"
-// Adar I -> Adar AND EST -> EDT, resolved in one call. No ordering of a plain/ calendar
+convertZonedToCalendar("2024-10-03T14:30:45-04:00[u-ca=hebrew][America/New_York]", "iso8601");
+// "" — the calendar annotation must follow the zone
+
+addZoned("2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]", { months: 1 });
+// "2024-03-25T14:30:00-04:00[America/New_York][u-ca=hebrew]"
+// Adar I -> Adar II AND EST -> EDT, resolved in one call. No ordering of a plain/ calendar
 // operation and a zoned/ conversion produces this: do the calendar step first and DST is
 // applied to an already-resolved wall time; do the zoned step first and there is no calendar
 // left to step in.
+```
 
-addZoned("0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]", {
-  days: 1,
-});
-// "0001-05-01T12:00:00+09:00[u-ca=japanese;era=reiwa][Asia/Tokyo]" — era re-derived, never copied
-```
-
-> **The `[u-ca=...]` segment comes BEFORE `[timeZone]` — the reverse of RFC 9557.** This is
-> deliberate. GMT's digits are calendar-native (Hebrew year 5784, not ISO year 5784), so the
-> string is never valid RFC 9557 to begin with, and the `;era=` suffix is not valid RFC 9557 at
-> any ordering. Writing it in RFC order is actively dangerous:
-> `Temporal.ZonedDateTime.from("5784-01-01T14:30:00-05:00[America/New_York][u-ca=hebrew]")`
-> _succeeds_, silently reading 5784 as an ISO year — a ~3760-year misparse with no error. GMT's
-> ordering makes that shape uniformly rejected instead.
-
-Scope: `addZoned`, `subtractZoned`, `diffZoned`, `diffZonedAsDuration`, `convertZonedToCalendar`,
-and the `zoned/interval/*` family. Everything else in `zoned/` still rejects the annotation —
-`isValidZonedDateTime` is unchanged, so a function that has not opted in fails closed rather than
-silently answering in the wrong calendar. `addZonedBusinessDays`/`subtractZonedBusinessDays` stay
-out by design: day-of-week is ISO-fixed in every supported calendar, so a tag would change nothing
-while implying it might.
-
-Mixed-calendar endpoints follow the same split as `plain/`: ordering functions
-(`intervalContainsZoned`, `intervalsOverlapZoned`, `intervalAbutsZoned`, `intervalEngulfsZoned`,
-`intervalOverlappingDaysZoned`, `isValidCalendarZonedInterval`) accept them; the eight
-value-returning set operations require one shared calendar and return their sentinel on a
-mismatch. Measurement functions (`diffZoned`, `diffZonedAsDuration`, `intervalCountZoned`,
-`intervalLengthZoned`, `splitIntervalByUnitZoned`) measure in the endpoints' shared calendar when
-both tags match and fall back to Gregorian otherwise — mandatory here rather than merely
-convenient, because `Temporal.ZonedDateTime.prototype.until` throws across mismatched calendars
-for _every_ unit, including pure time units like hours.
+Scope: `addZoned`, `subtractZoned`, `diffZoned`, `diffZonedAsDuration`, `convertZonedToCalendar`, and the `zoned/interval/*` family. Everything else in `zoned/`, and `isValidZonedDateTime`, accepts `[u-ca=iso8601]` and rejects any other calendar, so a function that has not opted in fails closed rather than silently answering in the wrong calendar. `addZonedBusinessDays`/`subtractZonedBusinessDays` stay out by design: day-of-week is ISO-fixed in every supported calendar, so a tag would change nothing while implying it might.
+
+Mixed-calendar endpoints follow the same rules as `plain/`. Ordering functions (`intervalContainsZoned`, `intervalsOverlapZoned`, `intervalAbutsZoned`, `intervalEngulfsZoned`, `isValidCalendarZonedInterval`) accept them. The value-returning set operations require one shared calendar. Differences (`diffZoned`, `diffZonedAsDuration`, `intervalCountZoned`, `intervalLengthZoned`, `splitIntervalByUnitZoned`, `intervalOverlappingDaysZoned`) return their sentinel on a mismatch for every unit, including hours, as `Temporal.ZonedDateTime.prototype.until` throws across calendars.
+
+**Migrating strings written before 1.16.0.** Earlier releases wrote the calendar's own year, month and day (`"5785-01-01[u-ca=hebrew]"` for ISO 2024-10-03), a `;era=` suffix, the zoned calendar annotation before the zone, and the ids `gregorian`, `taiwan`, `islamic-tabular` and `ethiopic-amete-alem` (now `iso8601`, `roc`, `islamic-tbla` and `ethioaa`). No converter exists: most old strings are also valid RFC 9557 strings for a different ISO date, and the two readings cannot be told apart. `convertDateToCalendar("5785-01-01[u-ca=hebrew]", "iso8601")` returns `"5785-01-01"`. Regenerate each stored value from its ISO date with `convertDateToCalendar` or `convertZonedToCalendar`.
 
 ### Durations
 
@@ -684,6 +748,8 @@ diffDateAsDuration("2024-03-10", "2024-04-05", "days");
 
 ### Intervals
 
+> **One boundary model.** Every interval function in this section (`intervalsOverlapDate`, `intervalDifferenceUtc`, …) reads an interval as half-open, `[start, end)`: `start` is inside and `end` is not, as in the `interval/` namespace described under [Interval algebra](#interval-algebra) (SQL:2011 closed-open `PERIOD`, RFC 5545's non-inclusive `DTEND`, EWD831). Touching intervals share no instant, so they abut rather than overlap, and no function steps an endpoint by one unit. For a `Date` interval that means `end` is the first day **after** the period: pass `"2024-07-01"`, not `"2024-06-30"`, for the first half of 2024 (`addDate(lastDay, { days: 1 })`). Before 1.16.0 most positional families read intervals as closed `[start, end]`.
+
 Interval and range validators are available in two API shapes — **range validators** (matching `isValidDateRange`'s `{ value1, value2, options? }` object-param shape) and **interval validators** (`(start, end)` positional args, `start <= end` always):
 
 ```typescript
@@ -734,8 +800,8 @@ isValidZonedRange({
 
 Interval containment checks (`intervalContains*`) test whether a point or inner interval falls within an outer interval. Each supports two modes via an optional fourth argument:
 
-- 3-arg: `intervalContains(start, end, point)` — true when `start <= point <= end`
-- 4-arg: `intervalContains(start, end, innerStart, innerEnd)` — true when the inner interval is fully contained
+- 3-arg: `intervalContains(start, end, point)` — true when `start <= point < end`
+- 4-arg: `intervalContains(start, end, innerStart, innerEnd)` — true when the inner interval lies within the outer one and overlaps it, so an inner interval may share the outer `end`, but an empty inner interval at `end` is not contained
 
 ```typescript
 import {
@@ -751,6 +817,9 @@ import {
 intervalContainsDate("2024-01-01", "2024-12-31", "2024-06-15");
 // true
 
+intervalContainsDate("2024-01-01", "2024-12-31", "2024-12-31");
+// false (the end is excluded)
+
 intervalContainsTime("09:00:00", "17:00:00", "12:00:00");
 // true
 
@@ -779,9 +848,9 @@ intervalContainsTime("09:00:00", "17:00:00", "10:00:00", "16:00:00");
 // true
 ```
 
-All interval containment checks return `false` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, non-finite values for Unix).
+All interval containment checks return `false` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, or an epoch outside the `unix/` grammar: not a safe integer or a digit string).
 
-`intervalsOverlap*` checks whether two intervals share any time. Returns `true` when intervals overlap, `false` when they are disjoint or only adjacent (touching at a single instant with no shared time):
+`intervalsOverlap*` checks whether two intervals share any instant. Returns `false` when they are disjoint. Intervals that touch (one's end equals the other's start) share no instant, so they do **not** overlap, exactly as `intervalsOverlap` in `interval/`:
 
 ```typescript
 import {
@@ -797,23 +866,23 @@ intervalsOverlapDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31");
 // true
 
 intervalsOverlapDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31");
-// false (adjacent, no shared time)
+// false (touching — 2024-06-30 is outside the first interval)
 
 intervalsOverlapUnix(0, 1700000000, 1000000, 2000000);
 // true
 
 intervalsOverlapUtc(
-  "2024-01-01T00:00:00Z",
-  "2024-06-30T23:59:59Z",
-  "2024-04-01T00:00:00Z",
-  "2024-12-31T23:59:59Z",
+  "2024-01-01T09:00:00Z",
+  "2024-01-01T17:00:00Z",
+  "2024-01-01T17:00:00Z",
+  "2024-01-01T18:00:00Z",
 );
-// true
+// false (touching at 17:00)
 ```
 
-All overlap checks return `false` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, non-finite values for Unix).
+All overlap checks return `false` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, or an epoch outside the `unix/` grammar: not a safe integer or a digit string).
 
-`intervalIntersection*` returns the overlapping span of two intervals, or `null` when they do not overlap. Adjacent intervals (sharing one instant) count as overlapping and return a single-point span:
+`intervalIntersection*` returns the overlapping span of two intervals, or `null` when they do not overlap. Touching intervals share no instant, so their intersection is `null`:
 
 ```typescript
 import {
@@ -827,43 +896,35 @@ import {
 
 intervalIntersectionDate(
   "2024-01-01",
-  "2024-06-30",
+  "2024-07-01",
   "2024-04-01",
-  "2024-12-31",
-);
-// { start: "2024-04-01", end: "2024-06-30" }
-
-intervalIntersectionDate(
-  "2024-01-01",
-  "2024-06-30",
-  "2024-06-30",
-  "2024-12-31",
+  "2025-01-01",
 );
-// { start: "2024-06-30", end: "2024-06-30" } (adjacent, shares one instant)
+// { start: "2024-04-01", end: "2024-07-01" }
 
 intervalIntersectionDate(
   "2024-01-01",
-  "2024-06-30",
   "2024-07-01",
-  "2024-12-31",
+  "2024-07-01",
+  "2025-01-01",
 );
-// null (disjoint)
+// null (touching, no shared day)
 
 intervalIntersectionUnix(0, 1700000000, 1000000, 2000000);
-// { start: 1000000, end: 1700000000 }
+// { start: 1000000, end: 2000000 } (B lies inside A)
 
 intervalIntersectionUtc(
   "2024-01-01T00:00:00Z",
-  "2024-06-30T23:59:59Z",
+  "2024-07-01T00:00:00Z",
   "2024-04-01T00:00:00Z",
-  "2024-12-31T23:59:59Z",
+  "2025-01-01T00:00:00Z",
 );
-// { start: "2024-04-01T00:00:00Z", end: "2024-06-30T23:59:59Z" }
+// { start: "2024-04-01T00:00:00Z", end: "2024-07-01T00:00:00Z" }
 ```
 
-All intersection functions return `null` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, non-finite values for Unix).
+All intersection functions return `null` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, or an epoch outside the `unix/` grammar: not a safe integer or a digit string).
 
-`intervalOverlappingDays*` returns how many distinct calendar dates two intervals share — the numeric counterpart to `intervalIntersection*`'s span. Counting is inclusive of both endpoints of the closed intersection `[max(aStart, bStart), min(aEnd, bEnd)]`, so `intervalOverlappingDaysDate("2024-01-01", "2024-01-01", "2024-01-01", "2024-01-01")` is `1`, not `0`. There is no `Time` variant — `PlainTime` has no calendar, so a day count is undefined for it:
+`intervalOverlappingDays*` returns how many distinct calendar dates two intervals share — the numeric counterpart to `intervalIntersection*`'s span. It counts the calendar dates that hold at least one instant of the half-open intersection `[max(aStart, bStart), min(aEnd, bEnd))`, so an empty intersection counts `0`: `intervalOverlappingDaysDate("2024-01-01", "2024-01-02", "2024-01-01", "2024-01-02")` is `1`, and touching intervals are `0`. There is no `Time` variant — `PlainTime` has no calendar, so a day count is undefined for it:
 
 ```typescript
 import {
@@ -876,44 +937,42 @@ import {
 
 intervalOverlappingDaysDate(
   "2024-01-01",
-  "2024-06-30",
+  "2024-07-01",
   "2024-04-01",
-  "2024-12-31",
+  "2025-01-01",
 );
-// 91
+// 91 (2024-04-01 through 2024-06-30)
 
 intervalOverlappingDaysDate(
   "2024-01-01",
-  "2024-06-30",
-  "2024-06-30",
-  "2024-12-31",
+  "2024-07-01",
+  "2024-07-01",
+  "2025-01-01",
 );
-// 1 (adjacent, shares one date)
+// 0 (touching, no shared date)
 
-intervalOverlappingDaysDate(
-  "2024-01-01",
-  "2024-06-30",
-  "2024-07-01",
-  "2024-12-31",
+intervalOverlappingDaysUtc(
+  "2024-01-17T12:00:00Z",
+  "2024-01-19T00:00:00Z",
+  "2024-01-10T00:00:00Z",
+  "2024-01-18T06:00:00Z",
 );
-// 0 (disjoint)
+// 2 (18 hours of overlap touch 17 and 18 January)
 
-intervalOverlappingDaysUnix(0, 172800000, 86400000, 259200000, {
-  timeZone: "UTC",
-});
-// 2
+intervalOverlappingDaysUnix(0, 172800000, 86400000, 259200000);
+// 1 (the intersection [86400000, 172800000) is 1970-01-02 in UTC)
 ```
 
-Returns `0` when the intervals do not overlap (a well-defined answer, not invalid input) and `null` on invalid input, including an inverted interval (`start > end`). `intervalOverlappingDaysZoned` and `intervalOverlappingDaysUnix` count days in `aStart`'s time zone (`intervalOverlappingDaysUnix` defaults to the system time zone, overridable via `{ timeZone }`) — the same rule `intervalCountZoned`/`intervalCountUnix` use — so `intervalOverlappingDaysZoned` is **not commutative** when the two intervals carry different zones: swapping the arguments can change the answer.
+Returns `0` when the intervals do not overlap (a well-defined answer, not invalid input) and `null` on invalid input, including an inverted interval (`start > end`). `intervalOverlappingDaysZoned` and `intervalOverlappingDaysUnix` count days in `aStart`'s time zone (`intervalOverlappingDaysUnix` defaults to UTC; pass `{ timeZone }`, or `"local"` for the system zone) — the same rule `intervalCountZoned`/`intervalCountUnix` use — so `intervalOverlappingDaysZoned` is **not commutative** when the two intervals carry different zones: swapping the arguments can change the answer. Both count the distinct local dates the overlap touches, so a date the zone skipped (`Pacific/Apia`, 2011-12-30) is not counted, and a fall-back that sends the clock back into the previous date counts that date too.
 
-This deliberately diverges from date-fns's `getOverlappingDaysInIntervals`, which rounds up elapsed 24-hour periods instead of counting calendar dates — its own doc example (`Jan 10–20` vs `Jan 17–21`) returns `3` there and `4` here. To reproduce date-fns's number, compose `intervalIntersection*` with `intervalCount*`:
+It counts calendar dates, not elapsed days: the 18-hour overlap above touches two dates. For the elapsed length of the overlap, compose `intervalIntersection*` with `intervalLength*`:
 
 ```typescript
-const span = intervalIntersectionDate(aStart, aEnd, bStart, bEnd);
-span ? intervalCountDate(span.start, span.end, "day") : 0; // date-fns semantics
+const span = intervalIntersectionUtc(aStart, aEnd, bStart, bEnd);
+span ? intervalLengthUtc(span.start, span.end, "day") : 0; // 0.75 for the overlap above
 ```
 
-`intervalUnion*` returns the combined span of two overlapping or adjacent intervals, or `null` when they are disjoint with a gap. Adjacent intervals (sharing one instant) count as mergeable:
+`intervalUnion*` returns the combined span of two overlapping or touching intervals, or `null` when a gap separates them. Touching intervals (one's end equals the other's start) join:
 
 ```typescript
 import {
@@ -925,28 +984,28 @@ import {
   intervalUnionZoned,
 } from "@northguild/gmt";
 
-intervalUnionDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31");
-// { start: "2024-01-01", end: "2024-12-31" }
+intervalUnionDate("2024-01-01", "2024-07-01", "2024-04-01", "2025-01-01");
+// { start: "2024-01-01", end: "2025-01-01" }
 
-intervalUnionDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31");
-// { start: "2024-01-01", end: "2024-12-31" } (adjacent, merged)
+intervalUnionDate("2024-01-01", "2024-07-01", "2024-07-01", "2025-01-01");
+// { start: "2024-01-01", end: "2025-01-01" } (touching, joined)
 
 intervalUnionDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31");
-// null (disjoint with a gap)
+// null (2024-06-30 lies in neither interval)
 
 intervalUnionUnix(0, 1700000000, 1000000, 2000000);
 // { start: 0, end: 1700000000 }
 
 intervalUnionUtc(
   "2024-01-01T00:00:00Z",
-  "2024-06-30T23:59:59Z",
+  "2024-07-01T00:00:00Z",
   "2024-04-01T00:00:00Z",
-  "2024-12-31T23:59:59Z",
+  "2025-01-01T00:00:00Z",
 );
-// { start: "2024-01-01T00:00:00Z", end: "2024-12-31T23:59:59Z" }
+// { start: "2024-01-01T00:00:00Z", end: "2025-01-01T00:00:00Z" }
 ```
 
-All union functions return `null` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, non-finite values for Unix).
+All union functions return `null` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, or an epoch outside the `unix/` grammar: not a safe integer or a digit string).
 
 `intervalDifference*` returns the portion(s) of interval A not covered by interval B, as an array of `{ start, end }` records:
 
@@ -961,24 +1020,26 @@ import {
 } from "@northguild/gmt";
 
 intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-06-01", "2024-07-01");
-// [{ start: "2024-01-01", end: "2024-05-31" }, { start: "2024-07-02", end: "2024-12-31" }]
+// [{ start: "2024-01-01", end: "2024-06-01" }, { start: "2024-07-01", end: "2024-12-31" }]
 
 intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-01-01", "2024-12-31");
 // [] (B fully covers A)
 
 intervalDifferenceUnix(0, 1700000000, 1000000, 2000000);
-// [{ start: 0, end: 999999 }, { start: 2000001, end: 1700000000 }]
+// [{ start: 0, end: 1000000 }, { start: 2000000, end: 1700000000 }]
 
 intervalDifferenceUtc(
-  "2024-01-01T00:00:00Z",
-  "2024-12-31T23:59:59Z",
-  "2024-06-01T00:00:00Z",
-  "2024-07-01T00:00:00Z",
+  "2024-01-01T09:00:00Z",
+  "2024-01-01T17:00:00Z",
+  "2024-01-01T12:00:00Z",
+  "2024-01-01T13:00:00Z",
 );
-// [{ start: "2024-01-01T00:00:00Z", end: "2024-05-31T23:59:59Z" }, { start: "2024-07-02T00:00:00Z", end: "2024-12-31T23:59:59Z" }]
+// [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }]
 ```
 
-All difference functions return `[]` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, non-finite values for Unix).
+Each piece ends exactly where B starts and resumes exactly where B ends, with no one-unit step, so the pieces and B together cover A once. `intervalDifferenceUtc` returns the same pieces as `subtractIntervals`.
+
+All difference functions return `[]` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, or an epoch outside the `unix/` grammar: not a safe integer or a digit string).
 
 `intervalXor*` returns the symmetric difference of two intervals — the portions covered by exactly one of them, not both — as an array of `{ start, end }` records:
 
@@ -992,27 +1053,27 @@ import {
   intervalXorZoned,
 } from "@northguild/gmt";
 
-intervalXorDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31");
-// [{ start: "2024-01-01", end: "2024-03-31" }, { start: "2024-07-01", end: "2024-12-31" }]
+intervalXorDate("2024-01-01", "2024-07-01", "2024-04-01", "2025-01-01");
+// [{ start: "2024-01-01", end: "2024-04-01" }, { start: "2024-07-01", end: "2025-01-01" }]
 
-intervalXorDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31");
-// [{ start: "2024-01-01", end: "2024-06-29" }, { start: "2024-07-01", end: "2024-12-31" }] (adjacent)
+intervalXorDate("2024-01-01", "2024-07-01", "2024-07-01", "2025-01-01");
+// [{ start: "2024-01-01", end: "2025-01-01" }] (touching intervals share no date, so the runs join)
 
 intervalXorUnix(0, 1700000000, 1000000, 2000000);
-// [{ start: 0, end: 999999 }, { start: 2000001, end: 1700000000 }]
+// [{ start: 0, end: 1000000 }, { start: 2000000, end: 1700000000 }]
 
 intervalXorUtc(
-  "2024-01-01T00:00:00Z",
-  "2024-06-30T23:59:59Z",
-  "2024-04-01T00:00:00Z",
-  "2024-12-31T23:59:59Z",
+  "2024-01-01T09:00:00Z",
+  "2024-01-01T13:00:00Z",
+  "2024-01-01T12:00:00Z",
+  "2024-01-01T17:00:00Z",
 );
-// [{ start: "2024-01-01T00:00:00Z", end: "2024-03-31T23:59:59Z" }, { start: "2024-07-01T00:00:00Z", end: "2024-12-31T23:59:59Z" }]
+// [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }]
 ```
 
-All xor functions return `[]` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, non-finite values for Unix).
+All xor functions return `[]` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, or an epoch outside the `unix/` grammar: not a safe integer or a digit string).
 
-`intervalAbuts*` checks whether two intervals are exactly adjacent — one's end equals the other's start with zero gap and zero overlap:
+`intervalAbuts*` checks whether two intervals are exactly adjacent, in either order: one interval's `end` equals the other's `start` (Allen's "meets"). The two then share no instant and leave no gap. Intervals separated by any gap, even one nanosecond or one epoch unit, do not abut, and an empty interval abuts nothing:
 
 ```typescript
 import {
@@ -1024,30 +1085,30 @@ import {
   intervalAbutsZoned,
 } from "@northguild/gmt";
 
-intervalAbutsDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31");
-// true
+intervalAbutsDate("2024-01-01", "2024-07-01", "2024-07-01", "2025-01-01");
+// true (the first interval ends where the second starts)
 
-intervalAbutsDate("2024-01-01", "2024-06-29", "2024-06-30", "2024-12-31");
-// false (one-day gap)
+intervalAbutsDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31");
+// false (2024-06-30 lies in neither interval)
 
-intervalAbutsDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31");
+intervalAbutsDate("2024-01-01", "2024-07-01", "2024-04-01", "2025-01-01");
 // false (overlap)
 
 intervalAbutsUnix(0, 1000000, 1000000, 2000000);
 // true
 
 intervalAbutsUtc(
-  "2024-01-01T00:00:00Z",
-  "2024-06-30T23:59:59Z",
-  "2024-06-30T23:59:59Z",
-  "2024-12-31T23:59:59Z",
+  "2024-01-01T09:00:00Z",
+  "2024-01-01T12:00:00Z",
+  "2024-01-01T12:00:00.000000001Z",
+  "2024-01-01T17:00:00Z",
 );
-// true
+// false (1 ns apart)
 ```
 
-All abuts checks return `false` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, non-finite values for Unix).
+All abuts checks return `false` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, or an epoch outside the `unix/` grammar: not a safe integer or a digit string).
 
-`intervalEngulfs*` checks whether interval B is fully contained within interval A — every instant of B falls within A. Equivalent to the 4-argument `intervalContains*` mode:
+`intervalEngulfs*` checks whether interval B lies within interval A and overlaps it — B may share A's `start` or `end`, but an empty B at A's `end` is not engulfed. Equivalent to the 4-argument `intervalContains*` mode:
 
 ```typescript
 import {
@@ -1080,7 +1141,7 @@ intervalEngulfsUtc(
 // true
 ```
 
-All engulfs checks return `false` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, non-finite values for Unix).
+All engulfs checks return `false` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, or an epoch outside the `unix/` grammar: not a safe integer or a digit string).
 
 `splitIntervalByUnit*` splits an interval into sub-intervals of `amount × unit`, returning an array of `{ start, end }` records. The final sub-interval is trimmed so its `end` never exceeds the original `end`:
 
@@ -1109,7 +1170,26 @@ splitIntervalByUnitUnix(0, 86400000, "hour", 6);
 // [{ start: 0, end: 21600000 }, { start: 21600000, end: 43200000 }, { start: 43200000, end: 64800000 }, { start: 64800000, end: 86400000 }]
 ```
 
-All split functions return `[]` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, non-positive amount, unsupported unit, or a unit that has no effect on the target type).
+All split functions return `[]` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, non-positive amount, unsupported unit, or a unit that has no effect on the target type). A zero-length interval returns itself as the one piece (`[{ start, end }]`) for a supported unit, and `[]` for an unsupported one: `splitIntervalByUnitDate("2024-01-01", "2024-01-01", "hour", 1)` is `[]`.
+
+`splitIntervalByUnit*`, `intervalDivideEqually*`, `mapDatesInRange` and `mapZonedDatesInRange` build one array element per piece, so each takes an optional `{ maxPieces }` (a positive safe integer, default `1_000_000`) and returns `[]` when the result would be longer. A split stops as soon as the piece past the limit is due, so a huge range answers in bounded time instead of exhausting the heap. Pass a larger `maxPieces` when a long range legitimately needs it:
+
+```typescript
+import { mapDatesInRange, splitIntervalByUnitDate } from "@northguild/gmt";
+
+splitIntervalByUnitDate("2024-01-01", "2024-01-10", "day", 2, { maxPieces: 4 });
+// [] — 5 slices exceed the limit
+
+mapDatesInRange("0001-01-01", "9999-12-31", 1);
+// [] — 3,652,059 dates exceed the default
+```
+
+Each boundary is computed from `start` (`start + k × amount`, as Temporal and Luxon's `Interval.splitBy` do), never by stepping from the previous boundary, so month-end starts don't drift. A yearly split from February 29 likewise returns to February 29 in leap years:
+
+```typescript
+splitIntervalByUnitDate("2024-01-31", "2024-05-01", "month", 1);
+// [{ start: "2024-01-31", end: "2024-02-29" }, { start: "2024-02-29", end: "2024-03-31" }, { start: "2024-03-31", end: "2024-04-30" }, { start: "2024-04-30", end: "2024-05-01" }]
+```
 
 `intervalCount*` returns how many calendar-unit boundaries an interval crosses — the number of units the half-open interval `[start, end)` touches. This is distinct from `diff*`, which measures exact elapsed duration: an interval from 23:59 to 00:01 is two minutes long but touches two days:
 
@@ -1146,7 +1226,9 @@ intervalCountUnix(0, 86400000, "hour");
 // 24
 ```
 
-Zero-length intervals count `1` when they sit mid-unit and `0` when they sit exactly on a unit boundary — `intervalCountDate("2024-01-15", "2024-01-15", "month")` is `1`, while `intervalCountDate("2024-01-01", "2024-01-01", "month")` is `0`. Weeks start on Monday (ISO 8601), singular and plural units are interchangeable (`"day"` and `"days"`), and `intervalCountUnix` uses the system timeZone for calendar boundaries (consistent with `addUnix`). All count functions return `null` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, unsupported unit, or a unit that has no effect on the target type).
+A zero-length interval counts `0` in every unit — the empty `[start, start)` holds no instant, so `intervalCountDate("2024-01-15", "2024-01-15", "month")` is `0`. Weeks start on Monday (ISO 8601), singular and plural units are interchangeable (`"day"` and `"days"`), and `intervalCountUnix` counts calendar boundaries in `options.timeZone`, UTC by default (`"local"` for the system zone), like `addUnix`. All count functions return `null` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, unsupported unit, or a unit that has no effect on the target type).
+
+`intervalCountZoned`, `intervalCountUnix` and `intervalCountUtc` count the same local buckets `bucketRange` returns. A bucket shorter than its unit still counts once — a 20-minute range straddling 04:00 on `Pacific/Chatham`'s spring-forward day counts 2 hours, because its 03:00 hour lasts only 15 minutes — and a day the zone deleted counts not at all (`Pacific/Apia`'s 30 December 2011).
 
 `intervalLength*` is `intervalCount*`'s exact-duration counterpart — it answers "how long is this interval" as a real, possibly fractional number, rather than "how many boundaries does it touch":
 
@@ -1174,7 +1256,7 @@ intervalLengthZoned(
 // 23 (spring-forward local day is 23 real hours)
 ```
 
-`intervalLength*` uses `Temporal.Duration.prototype.total`, so calendar units (month, year) resolve against the interval's own `start` rather than truncating, and zoned/unix/utc variants are DST-aware the same way `intervalCount*` is. Returns `0` for a zero-length interval, and `null` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, unsupported unit).
+`intervalLength*` uses `Temporal.Duration.prototype.total`, so calendar units (month, year) resolve against the interval's own `start` rather than truncating, and zoned/unix/utc variants are DST-aware the same way `intervalCount*` is. Returns `0` for a zero-length interval, and `null` on invalid input (wrong type, malformed strings, leap seconds, inverted intervals, unsupported unit). `intervalLengthUnix` and `splitIntervalByUnitUnix` take `{ epochUnit, timeZone }` like `intervalCountUnix` (milliseconds and UTC by default): `intervalLengthUnix(0, 86400, "day", { epochUnit: "seconds" })` is `1`.
 
 `intervalDivideEqually*` splits an interval into `n` equal-length sub-intervals, and `intervalSplitAt*` splits an interval at arbitrary points instead of by count:
 
@@ -1191,7 +1273,7 @@ intervalSplitAtDate("2024-01-01", "2024-01-10", ["2024-01-07", "2024-01-03"]);
 // [{ start: "2024-01-01", end: "2024-01-03" }, { start: "2024-01-03", end: "2024-01-07" }, { start: "2024-01-07", end: "2024-01-10" }]
 ```
 
-`n` must be a positive integer (`[]` otherwise); `n === 1` returns the original interval unchanged, and a zero-length interval returns `n` identical zero-length sub-intervals. Non-fractional types (`PlainDate`) round internal boundaries to the nearest whole unit; every other variant is exact, computed from total elapsed nanoseconds (`intervalDivideEquallyZoned` splits DST-crossing intervals by real elapsed time, not local clock time). `intervalSplitAt*` sorts its `points` internally — they need not be pre-sorted — and drops points outside `[start, end]` or exactly on a boundary, since those cannot introduce a new sub-interval; an empty or all-dropped `points` array returns `[{ start, end }]` unsplit.
+`n` must be a positive integer (`[]` otherwise), and `n` above `maxPieces` also returns `[]`; `n === 1` returns the original interval unchanged, and a zero-length interval returns `n` identical zero-length sub-intervals. Each internal boundary is `start + round((end − start) · i / n)`, an exact half rounding up — in whole days for `PlainDate`, nanoseconds for the other string variants and the arguments' own epoch unit for `intervalDivideEquallyUnix` — so the split is exact when the span divides evenly by `n`, within half a unit otherwise, and the pieces tile the range with no gap or overshoot (`intervalDivideEquallyZoned` splits DST-crossing intervals by real elapsed time, not local clock time). `intervalSplitAt*` sorts its `points` internally — they need not be pre-sorted — and drops points outside the interval or exactly on `start` or `end`, since those cannot introduce a new sub-interval. Each piece's `end` is the next piece's `start`, so under `[start, end)` the pieces partition the interval; an empty or all-dropped `points` array returns `[{ start, end }]` unsplit.
 
 `mergeIntervals*` and `intervalXorAll*` are the list-form generalizations of `intervalUnion*` and `intervalXor*`, which are pairwise only — each takes a single array of `{ start, end }` records instead of two flat intervals:
 
@@ -1209,10 +1291,10 @@ intervalXorAllDate([
   { start: "2024-01-05", end: "2024-01-15" },
   { start: "2024-01-08", end: "2024-01-20" },
 ]);
-// [{ start: "2024-01-01", end: "2024-01-04" }, { start: "2024-01-08", end: "2024-01-10" }, { start: "2024-01-16", end: "2024-01-20" }]
+// [{ start: "2024-01-01", end: "2024-01-05" }, { start: "2024-01-08", end: "2024-01-10" }, { start: "2024-01-15", end: "2024-01-20" }]
 ```
 
-`mergeIntervals*` collapses overlapping or adjacent intervals (shared endpoint) into the minimum non-overlapping set. `intervalXorAll*` returns the set covered by an odd number of the input intervals — for exactly two intervals the result is identical to the pairwise `intervalXor*`, and two identical intervals cancel out to `[]`. All four return `[]` for an empty list or on invalid input.
+`mergeIntervals*` collapses overlapping or touching intervals (one's end equals the next one's start) into the minimum sorted set that does not overlap. `intervalXorAll*` returns the maximal runs covered by an odd number of the input intervals, sorted by start — for exactly two intervals the result is identical to the pairwise `intervalXor*`, and two identical intervals cancel out to `[]`. All four return `[]` for an empty list or on invalid input.
 
 `intervalFromDuration*` constructs an interval from a single point plus an ISO 8601 duration, anchored at either end — Luxon's `Interval.after`/`Interval.before` as one function with an `anchor` param instead of two:
 
@@ -1243,16 +1325,16 @@ intervalFromDurationTime("12:00:00", "P1D", "start");
 // null (PlainTime has no calendar — a date-unit duration needs a relativeTo it can't supply)
 ```
 
-Calendar units (years/months/weeks) resolve against `value` itself, so no separate `relativeTo` is needed — except for `intervalFromDurationTime`, which returns `null` for a `duration` with a nonzero years/months/weeks/days component, since `PlainTime` has no calendar to resolve it against. `intervalFromDurationZoned` accepts the same `disambiguation`/`offset`/`overflow` options as `addZoned`; `intervalFromDurationUnix` accepts `addUnix`'s `epochUnit`/`timeZone`/`overflow` options. A negative `duration` that inverts the computed span, or an `overflow: "reject"` result, returns `null` — same sentinel as any other invalid input.
+Calendar units (years/months/weeks) resolve against `value` itself, so no separate `relativeTo` is needed — except for `intervalFromDurationTime`, which returns `null` for a `duration` with a nonzero years/months/weeks/days component, since `PlainTime` has no calendar to resolve it against. `intervalFromDurationZoned` accepts the same `disambiguation`/`overflow` options as `addZoned`; `intervalFromDurationUnix` accepts `addUnix`'s `epochUnit`/`timeZone`/`overflow` options; `intervalFromDurationTime` takes no options argument, like `addTime`. A negative `duration` that inverts the computed span, or an `overflow: "reject"` result, returns `null` — same sentinel as any other invalid input.
 
-All validators return `false` on invalid input (wrong type, malformed strings, leap seconds, mixed kinds for plain interval validators, non-finite values for Unix).
+All validators return `false` on invalid input (wrong type, malformed strings, leap seconds, mixed kinds for plain interval validators, or an epoch outside the `unix/` grammar: not a safe integer or a digit string).
 
 ### Zoned operations
 
 ```typescript
 import { addZoned, formatZonedDateTime } from "@northguild/gmt";
 
-addZoned("2026-03-07T23:00:00-05:00[America/New_York]", 2, "hour");
+addZoned("2026-03-07T23:00:00-05:00[America/New_York]", { hours: 2 });
 // "2026-03-08T01:00:00-05:00[America/New_York]"
 
 formatZonedDateTime("2024-03-17T14:30:45+00:00[UTC]", "en-US", {
@@ -1274,23 +1356,31 @@ convertPlainDateTimeToZoned("2024-03-10T02:30:00", "America/New_York", {
 // "" — no such local time exists
 ```
 
-The `startOfZoned`/`endOfZoned`/`startOfQuarterForZoned`/`endOfQuarterForZoned`/`mapZonedHoursInDay` family (and their `unix/` counterparts) also accept `disambiguation`, plus an `offset` option (`"prefer"` | `"use"` | `"ignore"` (default) | `"reject"`) that controls whether the source's existing UTC offset is kept when computing the new boundary. **`offset` must stay at its default (`"ignore"`) for `disambiguation` to take effect** — Temporal's own default (`"prefer"`) keeps the source offset whenever still valid, which silently makes `disambiguation` a no-op:
+The `startOfZoned`/`endOfZoned`/`startOfQuarterForZoned`/`endOfQuarterForZoned`/`getLocaleZonedStartOfWeek`/`getLocaleZonedEndOfWeek` family (and their `unix/` counterparts) always return the real boundary of the unit that contains the input, in its zone: a start is never after the input and an end never before it, even when the wall-clock boundary was skipped or repeated. `Pacific/Chatham`'s 03:00 hour on its spring-forward starts at 03:45, New York's repeated 1 a.m. is its own hour, and a midnight repeated on the same date (America/Havana, 2024-11-03) stays one 25-hour day:
 
 ```typescript
 import { startOfZoned } from "@northguild/gmt";
 
 // 2024-11-03T01:45:00-05:00 is the SECOND, repeated 1am of the fall-back overlap in America/New_York.
-const source = "2024-11-03T01:45:00-05:00[America/New_York]";
+startOfZoned("2024-11-03T01:45:00-05:00[America/New_York]", "hour");
+// "2024-11-03T01:00:00-05:00[America/New_York]" — the real start of the repeated hour
+```
 
-startOfZoned(source, "hour", { disambiguation: "reject" });
-// "" — offset defaults to "ignore", so disambiguation actually fires and "reject" throws
+These boundary functions follow TC39's `startOfDay()`, which takes no resolution options: they take no `disambiguation` or `offset` options, and neither does `mapZonedHoursInDay`. Resolution options belong on functions that set wall-clock fields. `getHoursInZonedDay` and `mapZonedHoursInDay` measure the input's calendar date exactly as TC39's `hoursInDay` does, which differs from `startOfZoned(…, "day")` only where a fall-back re-enters the previous date (America/Goose_Bay, 2010-11-07).
 
-startOfZoned(source, "hour", { disambiguation: "reject", offset: "prefer" });
-// "2024-11-03T01:00:00-05:00[America/New_York]" — offset:"prefer" keeps the source's
-// still-valid -05:00 offset, so disambiguation is never consulted and "reject" never fires
-```
+`convertPlainDateTimeToZoned`, `addZoned`, `subtractZoned` and `intervalFromDurationZoned` take no `offset` option: they resolve a plain date-time that has no UTC offset for it to act on.
+
+`addZoned`, `subtractZoned` and `intervalFromDurationZoned` follow TC39's AddZonedDateTime: the date part of the duration (years to days) moves the wall clock, and the time part (hours and smaller) is added in exact time. `disambiguation` resolves the wall clock the date part lands on — in a spring-forward gap `"compatible"` and `"later"` move it forward, `"earlier"` back, and `"reject"` returns the sentinel; in a fall-back overlap it picks the occurrence — and never re-resolves the time part, so adding 10 minutes is always 10 real minutes. Before 1.16.0 a gap landing always moved forward. `diffZoned`, `diffZonedAsDuration` and `intervalLengthZoned` follow DifferenceZonedDateTime: days, weeks, months and years are counted on the zone's wall clock, and hours and smaller in exact time. Two values in different zones share no wall clock, so a calendar unit returns the sentinel; convert one end with `convertZonedToZoned` first:
+
+```typescript
+import { diffZoned } from "@northguild/gmt";
+
+diffZoned("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]", "days");
+// 1 — noon to noon across a 23-hour day
 
-`convertPlainDateTimeToZoned` and `addZoned`/`subtractZoned` also accept `offset` for API consistency, but it's permanently inert on both — their construction path never has a stored offset for it to act on.
+diffZoned("2024-01-01T00:00:00-05:00[America/New_York]", "2024-01-03T00:00:00+01:00[Europe/Paris]", "days");
+// null — calendar unit across two time zones
+```
 
 `hasDaylightSaving` reports whether an IANA timezone observes daylight saving time at all:
 
@@ -1431,7 +1521,7 @@ closestZonedTo("2024-03-15T12:00:00[America/New_York]", [
 // "2024-03-18T00:00:00-04:00[America/New_York]"
 ```
 
-See [`docs/dst-disambiguation.md`](../../docs/dst-disambiguation.md) for the full explanation, including why `overflow` was deliberately left off the public API.
+See [`docs/dst-disambiguation.md`](../../docs/dst-disambiguation.md) for the full explanation, including where `overflow` is and is not exposed.
 
 ### Formatting
 
@@ -1466,24 +1556,36 @@ formatRelativeDate("2026-01-15");
 // e.g. "3 months ago"
 
 formatRelativeTime("14:30:00", "en-US", { style: "short" });
-// e.g. "2 hours ago"
+// e.g. "2 hr. ago"
 
 formatRelativeDateTime("2026-03-17T09:00:00", "en-GB", {
   style: "long",
   numeric: "always",
 });
-// e.g. "17 March, 2026 at 09:00"
+// e.g. "in 3 hours"
 
 // Zoned relative formatting — reference can be a ZonedDateTime, UTC string, or unix epoch.
 formatRelativeZoned("2026-03-08T01:00:00-05:00[America/New_York]", "en-US");
 // e.g. "tomorrow"
 
-formatRelativeUtc("2024-03-17T14:30:45+00:00[UTC]", "en-US");
-// e.g. "2 years ago"
+// Auto-picked units run from second through year, with formatRelativeDate's thresholds;
+// pass largestUnit to cap them.
+formatRelativeUtc("2024-03-17T14:30:45Z", "en-US", {
+  reference: "2026-03-17T14:30:45Z",
+});
+// "2 years ago"
+formatRelativeUtc("2024-03-17T14:30:45Z", "en-US", {
+  reference: "2026-03-17T14:30:45Z",
+  largestUnit: "day",
+});
+// "730 days ago"
 
 // Unix epoch relative formatting.
-formatRelativeUnix(1710685845000, "en-US", { epochUnit: "milliseconds" });
-// e.g. "3 years ago"
+formatRelativeUnix(1710685845000, "en-US", {
+  epochUnit: "milliseconds",
+  reference: 1805358645000,
+});
+// "3 years ago"
 
 // roundingMethod ("floor" | "ceil" | "round", default "round") controls how the
 // computed distance rounds to the display unit — every formatRelative* function accepts it.
@@ -1514,13 +1616,13 @@ formatCalendarZoned("2026-03-16T14:30:00-04:00[America/New_York]", "de-DE", {
 // formatZonedRange (same parameter order and option shape), for a
 // locale-elided range between two timezone-free values.
 formatDateRange("2024-02-03", "2024-02-05", "en-US", { dateStyle: "long" });
-// "February 3 – 5, 2024"
+// "February 3 - 5, 2024"
 
 formatDateTimeRange("2024-02-03T09:00:00", "2024-02-03T17:00:00", "en-US", {
   dateStyle: "long",
   timeStyle: "short",
 });
-// "February 3, 2024, 9:00 AM – 5:00 PM"
+// "February 3, 2024, 9:00 AM - 5:00 PM"
 
 // formatDateToParts / formatDateTimeToParts / formatZonedToParts return the
 // locale-ordered Array<{ type, value }> parts behind the strings above,
@@ -1541,7 +1643,7 @@ formatDateToParts("2024-03-15", "fr-FR");
 formatZonedToParts("2024-03-15T14:30:00-04:00[America/New_York]", "en-US", {
   timeZoneName: "longOffset",
 });
-// includes { type: "timeZoneName", value: "GMT-4" }
+// includes { type: "timeZoneName", value: "GMT-04:00" }
 ```
 
 ### Named machine formats
@@ -1569,17 +1671,29 @@ formatRfc2822("2024-03-15T14:30:00-04:00[America/New_York]");
 parseRfc2822("Fri, 15 Mar 2024 14:30:00 -0400");
 // "2024-03-15T14:30:00-04:00[-04:00]"
 
-// HTTP headers (RFC 7231 IMF-fixdate) — Last-Modified, Date, Expires.
+// A receiver reads RFC 5322's full and obsolete syntax: comments, any case,
+// two-digit years and zone names. A day name that contradicts the date is "".
+parseRfc2822("fri,15 Mar 24 14:30 -0400 (EDT)");
+// "2024-03-15T14:30:00-04:00[-04:00]"
+parseRfc2822("Sat, 15 Mar 2024 14:30:00 -0400");
+// "" — 15 March 2024 was a Friday
+
+// HTTP headers (RFC 9110 IMF-fixdate) — Last-Modified, Date, Expires.
 formatHttp("2024-03-15T14:30:00Z");
 // "Fri, 15 Mar 2024 14:30:00 GMT"
 parseHttp("Fri, 15 Mar 2024 14:30:00 GMT");
 // "2024-03-15T14:30:00Z"
+// parseHttp also reads the obsolete rfc850-date and asctime-date forms.
+parseHttp("Sun Nov  6 08:49:37 1994");
+// "1994-11-06T08:49:37Z"
 
 // ANSI SQL / ODBC datetime literals (DATETIME/TIMESTAMP columns, no tz).
 formatSql("2024-03-15T14:30:00");
 // "2024-03-15 14:30:00"
 parseSql("2024-03-15 14:30:00");
 // "2024-03-15T14:30:00"
+parseSql("2024-03-15 14:30");
+// "" — the SQL literal grammar requires seconds, and a year of 0001–9999
 
 // Strict RFC 3339 — strips the bracketed IANA zone GMT's own zoned strings
 // carry, which RFC 3339 does not permit.
@@ -1589,21 +1703,482 @@ parseRfc3339("2024-03-15T14:30:00-04:00");
 // "2024-03-15T14:30:00-04:00[-04:00]"
 ```
 
+The formatters return `""` for a value their grammar cannot express, such as a year outside `0000`–`9999` for RFC 3339 and HTTP-date or outside `0001`–`9999` for SQL, rather than writing a string no conforming parser accepts. Use Temporal's own `toString()` when you need any year.
+
 ### Unix and UTC helpers
 
 ```typescript
 import { getUnixNow, getUtcNow, convertUnixToPlainDate } from "@northguild/gmt";
 
-getUnixNow("milliseconds");
-// 1710685845000
+getUnixNow();
+// 1710685845000 (milliseconds; getUnixNow({ epochUnit: "seconds" }) is 1710685845)
 
 getUtcNow();
 // "2026-03-18T11:42:33.123Z"
 
-convertUnixToPlainDate(1710685845);
+convertUnixToPlainDate(1710685845000, { timeZone: "UTC" });
 // "2024-03-17"
 ```
 
+### Nanosecond precision
+
+`convertZonedToUnix` and friends return `number` milliseconds. Systems that record
+telemetry, trades or sensor readings need nanoseconds, and a `number` cannot hold them:
+integers are exact only to `2^53 − 1` ≈ 9.0 × 10^15, and nanoseconds since the epoch
+passed that in April 1970. (`Date.now() * 1e6` is not a nanosecond timestamp — it is a
+millisecond timestamp with three zeroes appended.) The `precision/` namespace works in
+`bigint`:
+
+```typescript
+import {
+  toNanoseconds,
+  fromNanoseconds,
+  formatNanoseconds,
+  parseNanoseconds,
+  truncateNanoseconds,
+} from "@northguild/gmt";
+
+toNanoseconds("2024-03-10T12:00:00.123456789Z");
+// 1710072000123456789n
+
+fromNanoseconds(1710072000123456789n);
+// "2024-03-10T12:00:00.123456789Z"
+
+fromNanoseconds(1710072000123456789n, "America/New_York");
+// "2024-03-10T08:00:00.123456789-04:00[America/New_York]"
+```
+
+`JSON.stringify` throws a `TypeError` on a `bigint`, so the value crosses a wire as a
+canonical decimal string:
+
+```typescript
+JSON.stringify({ observedAt: formatNanoseconds(1710072000123456789n) });
+// '{"observedAt":"1710072000123456789"}'
+
+parseNanoseconds("1710072000123456789");
+// 1710072000123456789n
+```
+
+Most storage engines cannot hold nanoseconds — PostgreSQL `timestamptz` and MySQL
+`DATETIME(6)` hold microseconds — so a naive write-then-read loses the last digits
+silently. Truncate to the target precision first, and the round-trip is exact:
+
+```typescript
+truncateNanoseconds(1710072000123456789n, "us");
+// 1710072000123456000n — safe to write to a microsecond column
+
+truncateNanoseconds(1710072000123456789n, "ms");
+// 1710072000123000000n
+```
+
+Truncation floors toward negative infinity, so pre-1970 values truncate the same way
+post-1970 ones do — `truncateNanoseconds(-1500n, "us")` is `-2000n`, not `-1000n`.
+Rounding toward zero would make the result jump direction either side of the epoch.
+
+`0n` is both the epoch and the invalid-input sentinel, so `precision/validate` exists to
+tell them apart. Each predicate accepts exactly what its partner parses:
+
+```typescript
+import {
+  isValidInstant,
+  isValidNanoseconds,
+  isValidNanoPattern,
+} from "@northguild/gmt";
+
+isValidInstant("1970-01-01T00:00:00Z"); // true  — toNanoseconds returns 0n, the epoch
+isValidInstant("garbage"); // false — toNanoseconds returns 0n, the sentinel
+
+isValidNanoPattern("0"); // true  — parseNanoseconds returns 0n, the epoch
+isValidNanoPattern("1e18"); // false
+
+isValidNanoseconds(0n); // true  — in range for truncateNanoseconds / fromNanoseconds
+isValidNanoseconds(0); // false — a number cannot carry a nanosecond timestamp
+```
+
+Reach for `isValidInstant` rather than `isValidUtc`: the latter gates on GMT's stricter
+`<date>T<time>Z` shape and rejects the offsets and bracketed zones `toNanoseconds`
+accepts, so validating with it discards valid input.
+
+Every `precision/` function returns a sentinel (`""` for strings, `0n` for bigints) on
+invalid input, and accepts only values inside the range `Temporal.Instant` can represent
+(±8_640_000_000_000_000_000_000n). `0n` is also the epoch itself, so validate the input
+first when the two must be told apart. Leap-second-aware time scales (TAI, GPS) are not
+part of this namespace — these are plain instant conversions.
+
+### Foreign epoch bridges
+
+Other systems do not count from 1970. NTP counts from 1900 and rolls over in 2036, Windows
+`FILETIME` counts 100-nanosecond intervals from 1601, .NET ticks count the same interval
+from year 1, Excel uses a day serial with a deliberate 1900 leap-year bug, and PostgreSQL
+stores microseconds from 2000-01-01. Every integration re-derives these constants, usually
+wrongly:
+
+```typescript
+import {
+  toNtpTimestamp,
+  fromNtpTimestamp,
+  toFileTime,
+  fromFileTime,
+  toDotNetTicks,
+  fromDotNetTicks,
+  toExcelSerial,
+  fromExcelSerial,
+  toPgMicroseconds,
+  fromPgMicroseconds,
+} from "@northguild/gmt";
+
+toFileTime("1970-01-01T00:00:00Z");
+// 116444736000000000n — 100 ns intervals since 1601-01-01
+
+toDotNetTicks("1970-01-01T00:00:00Z");
+// 621355968000000000n — same unit, counted from 0001-01-01
+
+toPgMicroseconds("2024-03-10T12:00:00Z");
+// 763387200000000n — microseconds since 2000-01-01
+```
+
+**NTP timestamps are era-ambiguous by design.** The seconds field is unsigned 32-bit, so it
+wraps every ~136.19 years and the era is not part of the value. `fromNtpTimestamp` takes it
+as an explicit argument:
+
+```typescript
+toNtpTimestamp("2036-02-07T06:28:15Z");
+// 18446744069414584320n — the last second of era 0
+
+toNtpTimestamp("2036-02-07T06:28:16Z");
+// 0n — era 1 begins, and the seconds field wraps
+
+fromNtpTimestamp(0n);
+// "1900-01-01T00:00:00Z"
+
+fromNtpTimestamp(0n, 1);
+// "2036-02-07T06:28:16Z" — the same value, one era on
+```
+
+**Excel's serial 60 is the phantom 29 February 1900**, a date that never existed — 1900 was
+not a leap year. Lotus 1-2-3 got it wrong and Excel keeps the bug for compatibility, so the
+serial day `[60, 61)` is a hole rather than a date. "Fixing" it would put GMT one day out
+from Excel for every date before March 1900:
+
+```typescript
+fromExcelSerial(59);
+// "1900-02-28T00:00:00Z"
+
+fromExcelSerial(60);
+// "" — the phantom 1900-02-29
+
+fromExcelSerial(61);
+// "1900-03-01T00:00:00Z"
+
+toExcelSerial("2024-03-10T12:00:00Z");
+// 45361.5 — days, with the time of day as the fraction
+
+toExcelSerial("2024-03-10T12:00:00Z", { system: "1904" });
+// 43899.5 — the legacy Mac system, exactly 1462 days lower
+```
+
+Each bridge accepts only what its target format can actually hold, and returns the
+namespace's sentinel otherwise — `toFileTime` on a pre-1601 instant is `0n`, not a negative
+tick count, and `toExcelSerial` past 9999-12-31 is `null`, not an out-of-range serial.
+PostgreSQL's range is the one that surprises: its timestamp domain starts at 4713 BC, which
+is 40× later than the earliest instant Temporal can represent, so an in-range Temporal
+instant is not automatically an in-range PostgreSQL one. Where
+the target unit is coarser than a nanosecond the conversion floors toward negative infinity,
+so a round trip is exact to that unit: 100 ns for `FILETIME` and .NET ticks, 1 µs for
+PostgreSQL, 1 ms for Excel. NTP is the exception in the other direction — its 2^-32 s unit is
+finer than a nanosecond, so `fromNtpTimestamp` rounds to the nearest nanosecond and the round
+trip is exact.
+### Spans
+
+`diffZoned` measures in calendar units and returns a `Duration`. Profiling, tracing and
+telemetry want a raw number, and the `span/` namespace gives one:
+
+```typescript
+import { spanMs, spanNs, spanWallClock } from "@northguild/gmt";
+
+spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:01Z");
+// 1000
+
+spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00.123456789Z");
+// 123.456789 — fractional, like performance.now()
+
+spanNs("2024-03-10T12:00:00.123456789Z", "2024-03-10T12:00:00.123456790Z");
+// 1n
+```
+
+Both are signed — `spanMs(b, a)` is exactly `-spanMs(a, b)` — and both measure **exact
+elapsed time**. That is not the same question as calendar distance, and conflating the two
+is the most common span bug there is. A wall-clock day containing a DST transition is 23 or
+25 hours long (24.5 in `Australia/Lord_Howe`), so:
+
+```typescript
+const start = "2024-03-09T12:00:00-05:00[America/New_York]";
+const end = "2024-03-10T12:00:00-04:00[America/New_York]";
+
+spanMs(start, end);
+// 82800000 — 23 hours actually elapsed
+
+spanWallClock(start, end, "hours");
+// 24 — the clock face advanced a full day
+
+spanWallClock(start, end, "days");
+// 1
+```
+
+`spanWallClock` reads each endpoint's own local wall clock — straight off the string, never
+via an instant, so DST disambiguation cannot distort it and a local time that never occurred
+is measured as written. The two endpoints need not share a zone: a flight leaving New York at 23:00 and landing in Berlin at 11:00 the next local day
+is 12 wall-clock hours and 7 elapsed hours. It truncates toward zero, and it is not a count
+of midnights crossed.
+
+`isValidSpan(start, end)` answers "will these two produce a span?" — true exactly when
+`spanMs` and `spanNs` will return a value. It is symmetric, since a reversed pair is a
+negative span rather than an invalid one. `spanWallClock` has a different input grammar and
+is covered by `isValidZonedDateTime`.
+
+Three limits, all deliberate:
+
+- **`0` and `0n` are valid spans**, so invalid input returns `null` from all three rather
+  than the zero the rest of the library uses for numbers. `null` and not `NaN`: it is the
+  sentinel every other number-returning function in GMT uses, and the only one
+  `strictNullChecks` forces a caller to handle — a `NaN` types as plain `number` and
+  propagates silently through arithmetic.
+- **`spanMs` returns `null` past `Number.MAX_SAFE_INTEGER` milliseconds** (±285,000 years,
+  which two instants at opposite ends of `Temporal.Instant`'s range exceed). A
+  sub-millisecond fraction counts toward that ceiling, so what comes back is always a safe
+  integer or below. Use `spanNs` there; its result is a duration, not an instant, and can be
+  twice the epoch-nanosecond range.
+- **Leap seconds are not counted.** UTC repeats a second rather than numbering a 61st one,
+  so a span across one is a second short of the physical elapsed time; against a smeared
+  clock (Google, AWS, Meta) the error is up to a second spread over the smear window.
+
+### Offset-preserving instants and local resolution
+
+An instant orders events globally; the UTC offset in force where the event happened renders
+it as the human on the ground saw it. Neither derives from the other, which is why GS1 EPCIS
+2.0 requires both fields (`eventTime` plus `eventTimeZoneOffset`), UN/EDIFACT DTM has
+qualifiers `303`/`304` for the pair, and DICOM appends `&ZZXX` to a `DT` value. The `instant/`
+namespace is that pair:
+
+```typescript
+import { fromOffsetInstant, toOffsetInstant } from "@northguild/gmt";
+
+toOffsetInstant("2024-07-15T12:00:00-04:00[America/New_York]");
+// { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }
+
+// Most feeds send no zone at all — the offset alone is what happened.
+toOffsetInstant("2024-07-15T12:00:00-04:00");
+// { instant: "2024-07-15T16:00:00Z", offset: "-04:00" }
+
+// A UTC-only feed plus a zone you know from somewhere else.
+toOffsetInstant("2024-07-15T16:00:00Z", "America/New_York");
+// { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }
+
+fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "-04:00" });
+// "2024-07-15T12:00:00-04:00"
+```
+
+**An offset is not a zone.** `-05:00` does not identify `America/New_York` — it is every zone
+sitting at `-05:00` that day, and it says nothing about what that zone will do next spring.
+Store the zone for anything still to be scheduled; store the offset for anything that already
+happened. `timeZone` is optional because most feeds do not send one, and a string whose
+offset contradicts its own bracketed zone returns `null` rather than a guess.
+
+The other half of the namespace is the reverse problem: a wall time that arrives with no
+offset at all ("gate-out 08:00"). Resolving one needs a zone the sender did not send, plus a
+policy for the two days a year the mapping is not one-to-one:
+
+```typescript
+import { classifyLocal, resolveLocal } from "@northguild/gmt";
+
+classifyLocal("2024-11-03T01:30:00", "America/New_York"); // "ambiguous"
+classifyLocal("2024-03-10T02:30:00", "America/New_York"); // "nonexistent"
+classifyLocal("2024-07-15T12:00:00", "America/New_York"); // "unique"
+
+resolveLocal("2024-11-03T01:30:00", "America/New_York");
+// "2024-11-03T05:30:00Z" — the default "compatible" takes the first 01:30
+
+resolveLocal("2024-11-03T01:30:00", "America/New_York", { disambiguation: "later" });
+// "2024-11-03T06:30:00Z" — the same wall clock, an hour of real time later
+
+resolveLocal("2024-11-03T01:30:00", "America/New_York", { disambiguation: "reject" });
+// "" — ambiguous, and not guessed
+```
+
+`classifyLocal` exists so code can branch **before** a policy is applied. A demurrage clock, a
+medication window or a duty limit should refuse an ambiguous wall time, or route it to a
+human — not silently accept whichever of two instants an hour apart a default handed it. See
+[DST Disambiguation](../../docs/dst-disambiguation.md) for the four strategies in full.
+
+Two notes on the boundaries of this namespace:
+
+- **`resolveLocal` returns an instant; `convertPlainDateTimeToZoned` returns a zoned string.**
+  Same underlying resolution, different output and different precision — `resolveLocal` is
+  exact to the nanosecond, while `convertPlainDateTimeToZoned` defaults to milliseconds.
+  Neither takes an `offset` option. Reach for whichever shape you need next.
+- **`offset` is `±HH:MM`, except where it is not.** A handful of zones did not run on a whole
+  minute before 1972 — `Africa/Monrovia` really was `-00:44:30` — and those report
+  `±HH:MM:SS`. Rounding them would put the pair thirty seconds from the event it describes.
+
+### Calendar boundaries and zone-aware buckets
+
+Two absences with outsized consequences, and they turn out to be the same absence twice: a
+calendar boundary is not a fixed number of hours, and it is not in UTC.
+
+**Week and period identifiers.** Vessel schedules are published by week number and retail runs
+on 52/53-week fiscal calendars. Both come back as whole identifiers, not as fields to combine
+by hand — a week number without its week-numbering year is ambiguous at both ends of a year:
+
+```typescript
+import { getFiscalPeriod, getIsoWeekDate, getOrdinalDate, getQuarter } from "@northguild/gmt";
+
+getIsoWeekDate("2027-01-01"); // { year: 2026, week: 53, weekday: 5 } — week-year 2026, not 2027
+getOrdinalDate("2024-12-31"); // { year: 2024, dayOfYear: 366 }
+getQuarter("2024-03-31", { fiscalYearStartMonth: 4 }); // { year: 2023, quarter: 4 }
+
+// The NRF retail calendar, stated as its published rule: "the Saturday nearest to January 31".
+const nrf = { pattern: "4-5-4", yearEndsOn: "2026-01-31" } as const;
+
+getFiscalPeriod("2024-06-15", nrf); // { year: 2024, period: 5, week: 19 }
+getFiscalPeriod("2024-01-28", nrf); // { year: 2023, period: 12, week: 53 } — a 53-week year
+```
+
+52 × 7 is 364 days, so a 53rd week is inserted every five or six years and lands in the final
+period. `yearEndsOn` states the *rule*, by example — years end on that date's weekday, nearest
+that date's month and day — not one year's end, because GMT bundles no fiscal calendar. There
+is no single correct retail calendar to bundle.
+
+**Zone-aware bucketing.** "Group by day in `America/New_York`" over UTC timestamps is the most
+common observability bug there is, and the same operation decides how many chargeable days a
+container accrued, because free time is counted in terminal-local calendar days:
+
+```typescript
+import { bucketRange, floorToZone } from "@northguild/gmt";
+
+floorToZone("2024-06-15T03:00:00Z", "day", "America/New_York"); // "2024-06-14T04:00:00Z"
+floorToZone("2024-06-15T03:00:00Z", "day", "UTC");              // "2024-06-15T00:00:00Z"
+```
+
+Same instant, different calendar day — 03:00 UTC on 15 June is still 14 June in New York, and
+flooring it to the UTC day is wrong for most of the world for most of the day. The zone is an
+argument because GMT has no ambient one and must not acquire one.
+
+`bucketRange` returns the boundaries spanning a range, and **the buckets are deliberately not
+uniform in length**:
+
+```typescript
+bucketRange("2024-03-09T05:00:00Z", "2024-03-12T04:00:00Z", "day", "America/New_York");
+// ["2024-03-09T05:00:00Z", "2024-03-10T05:00:00Z", "2024-03-11T04:00:00Z"]
+// 24h, then 23h — the middle day springs forward
+
+bucketRange("2024-11-02T04:00:00Z", "2024-11-05T05:00:00Z", "day", "America/New_York");
+// ["2024-11-02T04:00:00Z", "2024-11-03T04:00:00Z", "2024-11-04T05:00:00Z"]
+// 24h, then 25h — the middle day falls back
+```
+
+Forcing 24 hours here is what makes a daily aggregate drift an hour twice a year. The same
+honesty applies to boundaries that do not exist: the calendar day Samoa deleted crossing the
+date line is absent from the list, a local day whose midnight is skipped by a spring-forward
+starts at 01:00, and in a zone that falls back by half an hour (`Australia/Lord_Howe`) the
+local 01:00 hour bucket is genuinely 90 minutes long.
+
+For a zoned or epoch value, `startOfZoned`/`startOfUnix` with no options return the same real
+boundary. Do not floor with `roundZoned`/`roundUnix` and `roundingMode: "trunc"`: they follow
+TC39 `ZonedDateTime.round`, which rounds the wall clock and re-resolves it in the zone, so
+`"2024-09-29T03:50:00+13:45[Pacific/Chatham]"` truncated to the hour gives 04:00 — after the
+input.
+
+A pattern or a bucket unit the namespace does not recognise returns the same sentinel an
+unusable date or instant does, so both unions have a type guard to narrow one that arrived as
+a bare string — from config, an env var, a form:
+
+```typescript
+import { isValidFiscalPattern, isValidZoneBucketUnit } from "@northguild/gmt";
+
+isValidFiscalPattern("4-5-4"); // true  — the NRF retail calendar
+isValidFiscalPattern("4-5-5"); // false — the shape a 53-week year's last quarter takes
+isValidZoneBucketUnit("day");  // true
+isValidZoneBucketUnit("days"); // true  — singular or plural, as floorToZone accepts
+isValidZoneBucketUnit("year"); // false — the year question is getQuarter's
+```
+
+### Interval algebra
+
+Four realms need the same operation and none of them could express it: sum the parts of an
+interval that fall inside a set of allowed windows. Laytime counts only the hours a charter
+clause allows, driver hours split a duty period around mandatory rest, demurrage free time
+counts only working days, and a trading window counts only continuous-session time. The
+`interval/` namespace is that one shared primitive, with one boundary rule:
+
+**Half-open `[start, end)`.** An instant `t` is inside when `start ≤ t < end`. That is SQL:2011's
+closed-open `PERIOD`, RFC 5545's non-inclusive `DTEND` and Dijkstra's EWD831. A container gated
+out at exactly 17:00 has not used another day, and two consecutive shifts never double-count the
+instant they meet.
+
+```typescript
+import {
+  clampInterval,
+  intersectIntervals,
+  intervalContains,
+  intervalsOverlap,
+  isValidInterval,
+  mergeIntervals,
+  splitIntervalAt,
+  subtractIntervals,
+  sumIntervals,
+} from "@northguild/gmt";
+
+const shift = { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" };
+
+intervalContains(shift, "2024-01-01T09:00:00Z"); // true — start is inside
+intervalContains(shift, "2024-01-01T17:00:00Z"); // false — end is not
+
+intervalsOverlap(shift, { start: "2024-01-01T17:00:00Z", end: "2024-01-01T18:00:00Z" });
+// false — touching intervals share no instant
+intersectIntervals(shift, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T18:00:00Z" });
+// { start: "2024-01-01T12:00:00Z", end: "2024-01-01T17:00:00Z" }
+clampInterval({ start: "2024-01-01T08:00:00Z", end: "2024-01-01T12:00:00Z" }, shift);
+// { start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }
+
+mergeIntervals([
+  { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" },
+  { start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" },
+  { start: "2024-01-01T12:00:00Z", end: "2024-01-01T13:00:00Z" },
+]);
+// [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }] — sorted, touching runs joined
+
+const worked = 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(worked); // "PT7H"
+
+splitIntervalAt(shift, ["2024-01-01T15:00:00Z", "2024-01-01T11:00:00Z"]);
+// [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T11:00:00Z" },
+//  { start: "2024-01-01T11:00:00Z", end: "2024-01-01T15:00:00Z" },
+//  { start: "2024-01-01T15:00:00Z", end: "2024-01-01T17:00:00Z" }] — pieces share no instant
+
+isValidInterval({ start: "2024-01-01T17:00:00Z", end: "2024-01-01T09:00:00Z" }); // false — inverted
+```
+
+- **Endpoints are instants.** An offset (`Z` or `±HH:MM`) is required and a `[Zone]` annotation is
+  optional. As with a TC39 `Temporal.Instant`, endpoints compare by epoch nanoseconds, so two of
+  them may name different zones. Leap seconds are rejected, and a `[u-ca=…]` annotation is ignored, as `Temporal.Instant.from` ignores it. For local-calendar
+  edges, build them with `floorToZone` or `bucketRange` first.
+- **Outputs are the caller's own strings**, never re-serialised. When two strings spell the same
+  instant, the first argument's spelling wins. No spec covers the tie, so this is a GMT rule.
+- **`start === end` is a valid empty interval.** It contains no instant, overlaps only an interval
+  it lies strictly inside, and adds nothing to a sum. An inverted interval returns the sentinel:
+  `false`, `null`, `[]` or `""`.
+- **`sumIntervals` is covered time.** It returns the length of the union, with overlaps counted
+  once, as an exact duration with hours as the largest unit. That is exactly what TC39
+  `Instant.prototype.until(…, { largestUnit: "hour" })` produces, because an instant has no
+  calendar that says how long a day is. So `PT49H30M` is never written `P2DT1H30M`, a New York
+  spring-forward day is `PT23H`, and `sumIntervals([])` is `"PT0S"`. The sum is exact past
+  2^53 nanoseconds.
+- **`[]` means two things.** From `mergeIntervals`, `subtractIntervals` and `splitIntervalAt` it
+  is both a legitimate result (a fully covered subtraction) and the invalid-input sentinel.
+  `isValidInterval` tells them apart.
+
 ## API Surface
 
 For the complete API listing, see the namespace documentation on GitHub:
@@ -1612,6 +2187,11 @@ For the complete API listing, see the namespace documentation on GitHub:
 - [Plain API](https://github.com/northguild/gmt/tree/main/packages/gmt/src/plain) — timezone-free operations
 - [Zoned API](https://github.com/northguild/gmt/tree/main/packages/gmt/src/zoned) — IANA timezone-aware operations
 - [Unix API](https://github.com/northguild/gmt/tree/main/packages/gmt/src/unix) — Unix epoch utilities
+- [Precision API](https://github.com/northguild/gmt/tree/main/packages/gmt/src/precision) — nanosecond instants, JSON transport, storage truncation, NTP / FILETIME / .NET ticks / Excel / PostgreSQL epoch bridges
+- [Span API](https://github.com/northguild/gmt/tree/main/packages/gmt/src/span) — elapsed and wall-clock durations as raw numbers
+- [Calendar API](https://github.com/northguild/gmt/tree/main/packages/gmt/src/calendar) — ISO week and ordinal dates, quarter and fiscal periods, zone-aware bucketing, and business calendars with holiday sets and roll conventions
+- [Interval API](https://github.com/northguild/gmt/tree/main/packages/gmt/src/interval) — half-open interval algebra over instants: overlap, intersect, clamp, merge, subtract, split, sum
+- [Instant API](https://github.com/northguild/gmt/tree/main/packages/gmt/src/instant) — the instant-plus-offset pair, and explicit local-time resolution
 - [UTC API](https://github.com/northguild/gmt/tree/main/packages/gmt/src/utc) — UTC instant utilities
 - [Regex API](https://github.com/northguild/gmt/tree/main/packages/gmt/src/regex) — composable regex patterns
 
@@ -1647,7 +2227,7 @@ When working with `@northguild/gmt`, follow these rules:
 3. **Invalid input returns a sentinel, never throws.** `""` for strings, `null` for numbers, `false` for booleans, `[]` for arrays.
 4. **Wrap all Temporal calls in `try-catch`.** `.from()`, `.add()`, `.since()`, etc. throw `RangeError` on bad input.
 5. **Keep `plain/` and `zoned/` strictly separate.** Never mix `PlainDateTime` and `ZonedDateTime`.
-6. **Full locale matrix for any locale-aware function.** 17 locales, explicit rows, `hasFullIcu` ternaries where output differs.
+6. **Full locale matrix for any locale-aware function.** 17 locales, explicit rows, `expectOneOfIcu`/`expectDateTimeEqual` (from `src/test/icuVariants.ts`) where CLDR wording differs.
 7. **Use pre-built mocks for error-path tests.** See `packages/gmt/src/test/mocks`.
 8. **JSDoc with `@example` on every public function.** Cover valid, invalid, and edge-case inputs.