@northguild/gmt 1.16.0 → 1.18.0

package/README.md

@@ -17,8 +17,8 @@ Read the [docs](https://gmt-dox.northguild.workers.dev/), or ask us on [Discord]
 
 - **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.
-- **~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.
+- **~59× more CI test executions than all four competitors combined**: 1,200,990 from 40,033 tests run in all 10 timezones × 3 Node versions, vs. their combined 20,190.
+- **~104× more test cases than `@internationalized/date`**: 40,033 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.
@@ -94,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:** 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.
+**Result:** 40,033 tests across 706 files that exercise real behavior differences without redundant permutations. They run in CI as 1,200,990 executions — every one of them × 3 Node versions × 10 timezones.
 
 ## How GMT is tested, vs. the libraries it targets
 
@@ -110,9 +110,9 @@ GMT is measured directly against react-aria's **`@internationalized/date`**, **L
 
 | Metric                          | GMT                                                | `@internationalized/date`      | Luxon                                | date-fns                                  | Moment.js                        |
 | ------------------------------- | -------------------------------------------------- | ------------------------------ | ------------------------------------ | ----------------------------------------- | -------------------------------- |
-| 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)       |
+| Test files                      | 706                                                | 6                              | 58 / 60<br>(2 didn't run<br>locally) | 256                                       | 191<br>(52 core +<br>139 locale) |
+| Individual test cases           | **40,033**                                         | 386                            | 1,222                                | 3,213                                     | 3,901                            |
+| Effective CI test<br>executions | **1,200,990**<br>(40,033 × 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                       |
@@ -148,7 +148,7 @@ Specific, sourced claims — not a repeat of the metrics above.
 | 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 ~54×                                                  | 1,090,440 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 ~59×                                                  | 1,200,990 vs. 386 + 4,888 + 3,213<br>+ 11,703 = 20,190                                                                                  |
 
 ## Package Layout
 
@@ -160,15 +160,17 @@ namespace objects: a namespace is a subpath.
 import { addDate, getNow, formatRelativeZoned, Temporal } from "@northguild/gmt";
 ```
 
-The twelve namespace subpaths:
+The fourteen 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/calendar`: ISO week and ordinal dates, quarter and fiscal periods, zone-aware bucketing, business calendars with holiday sets and roll conventions, and operating hours with open-time SLA arithmetic
 - `@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/transport`: transit legs as exact elapsed time, arrivals rendered where they land, dwell measured in local calendar days, crossings read in the zone that administers them, multi-leg schedules with missed connections flagged, cut-offs counted back from an anchor event, punctuality against a stated tolerance, planned, estimated, requested and actual timestamps kept apart, and the next departure a connection can make
+- `@northguild/gmt/intermodal`: free time, demurrage and detention counted in the terminal's local days, with the charged dates behind every count, and the invoice, dispute and resolution deadline chain with every window a caller parameter
 - `@northguild/gmt/zoned`: timezone-aware helpers
 - `@northguild/gmt/unix`: Unix epoch (seconds or milliseconds) helpers
 - `@northguild/gmt/utc`: UTC instant helpers
@@ -533,7 +535,7 @@ parseDateWithPattern("02/31/2024", "MM/dd/yyyy");
 // "" — shape-valid but not a real date; Temporal validates after the regex match
 ```
 
-Supported tokens include `yyyy`/`MM`/`dd`/`HH`/`mm`/`ss`/`SSS` for fixed-width fields, `M`/`d`/`H`/`h`/`m`/`s` for variable-width, `MMMM`/`MMM`/`EEEE`/`EEE`/`a`/`GGGG`/`GG` for locale-aware names, and `'single quotes'` for literal text. A `locale` parameter (default `"en-US"`) controls name-token matching. Invalid input, no-match, and malformed patterns all return `""`.
+Supported tokens include `yyyy`/`MM`/`dd`/`HH`/`mm`/`ss`/`SSS` for fixed-width fields, `M`/`d`/`H`/`h`/`m`/`s` for variable-width, `MMMM`/`MMM`/`EEEE`/`EEE`/`a`/`GGGG`/`GG` for locale-aware names, and `'single quotes'` for literal text. Two single quotes in a row are one literal quote, inside or outside quoted text, as UTS #35 reads them: `"MMM d, ''yy"` reads `"Mar 15, '24"`. A `locale` parameter (default `"en-US"`) controls name-token matching. Invalid input, no-match, and malformed patterns all return `""`.
 
 ### Calendar systems
 
@@ -1184,7 +1186,7 @@ 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:
+For a calendar unit (day, week, month, year) each boundary is computed from `start` (`start + k × amount`), 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. An exact unit (hour and smaller) steps from the previous boundary: adding an exact unit never clamps, so the two ways give the same boundaries.
 
 ```typescript
 splitIntervalByUnitDate("2024-01-31", "2024-05-01", "month", 1);
@@ -1382,18 +1384,18 @@ diffZoned("2024-01-01T00:00:00-05:00[America/New_York]", "2024-01-03T00:00:00+01
 // null — calendar unit across two time zones
 ```
 
-`hasDaylightSaving` reports whether an IANA timezone observes daylight saving time at all:
+`hasDaylightSaving(timeZone, { at })` reports whether an IANA timezone observes daylight saving time at a reference instant. It is `true` when the zone is in daylight time at `at`, or a daylight period begins less than 365 days after it. So a zone in its winter is `true`, and a zone that has stopped changing its clocks is `false`. `at` is an ISO 8601 instant string. With it, the answer does not depend on the day the code runs; without it, the reference is the current instant. An invalid zone, an invalid `at` and a fixed offset return `false`:
 
 ```typescript
 import { hasDaylightSaving } from "@northguild/gmt";
 
-hasDaylightSaving("America/New_York");
+hasDaylightSaving("America/New_York", { at: "2024-01-15T12:00:00Z" });
 // true
 
-hasDaylightSaving("Asia/Tokyo");
+hasDaylightSaving("Asia/Tokyo", { at: "2024-01-15T12:00:00Z" });
 // false
 
-hasDaylightSaving("Invalid/Zone");
+hasDaylightSaving("Invalid/Zone", { at: "2024-01-15T12:00:00Z" });
 // false
 ```
 
@@ -1421,12 +1423,18 @@ Each object's `instant` is a UTC ISO 8601 string; `offsetBefore`/`offsetAfter` a
 
 | Question                                                                        | Function                                      | Scope                                                |
 | ------------------------------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------- |
-| Does this zone observe DST at all?                                              | `hasDaylightSaving(timeZone)`                 | Zone-level, no instant                               |
+| Does this zone observe DST at this instant, or now?                             | `hasDaylightSaving(timeZone, { at })`         | Zone-level, judged from a reference instant          |
 | Where do this zone's transitions fall?                                          | `getDstTransitions(timeZone, year)`           | Enumerates instants                                  |
 | Is _this particular instant_ currently in DST?                                  | `isInDaylightSaving(value)`                   | A single zoned value                                 |
 | What should happen when construction lands on an ambiguous/nonexistent instant? | `disambiguation` / `offset` options (Group C) | Orthogonal — a construction-time choice, not a query |
 
-`isInDaylightSaving` answers the third question:
+`isInDaylightSaving` answers the third question. It and `hasDaylightSaving` apply one rule, read from the zone's own clock changes in the runtime's time zone data. The rule is GMT's own definition, not the tz database's daylight flag: no JavaScript API exposes that flag, and it cannot be worked out from offsets.
+
+- **The rule.** Daylight time runs from a forward change of the zone's clocks to the backward change of the same size that undoes it, less than 365 days later.
+- **A forward change never undone, or undone 365 days or more later, is a change of standard time.** `Europe/Istanbul` has been on standard time since its last advance in March 2016.
+- **The higher of two alternating offsets is the daylight one.** `Europe/Dublin` is in daylight time in summer, and `Africa/Casablanca` at `+01:00`.
+
+The full list of what the rule reads as standard time is in [DST Disambiguation](../../docs/dst-disambiguation.md) and in the function's JSDoc.
 
 ```typescript
 import { isInDaylightSaving } from "@northguild/gmt/zoned";
@@ -1442,7 +1450,13 @@ isInDaylightSaving("2024-01-15T12:00:00+11:00[Australia/Sydney]");
 // true
 
 isInDaylightSaving("2024-07-15T12:00:00+09:00[Asia/Tokyo]");
-// false — Asia/Tokyo has no DST, so this is always false
+// false — Asia/Tokyo has had no DST since 1951
+
+isInDaylightSaving("2015-07-01T12:00:00+03:00[Europe/Istanbul]");
+// true — the clocks went back on 2015-11-08
+
+isInDaylightSaving("2016-12-01T12:00:00+03:00[Europe/Istanbul]");
+// false — the advance of March 2016 was never undone
 
 isInDaylightSaving("invalid");
 // false
@@ -1569,7 +1583,9 @@ formatRelativeZoned("2026-03-08T01:00:00-05:00[America/New_York]", "en-US");
 // e.g. "tomorrow"
 
 // Auto-picked units run from second through year, with formatRelativeDate's thresholds;
-// pass largestUnit to cap them.
+// pass largestUnit to cap them. It takes a singular or plural name: "day" or "days".
+// Each function accepts the units its values have: formatRelativeDate day to year,
+// formatRelativeTime second to hour, the others second to year. Any other unit returns "".
 formatRelativeUtc("2024-03-17T14:30:45Z", "en-US", {
   reference: "2026-03-17T14:30:45Z",
 });
@@ -1589,6 +1605,7 @@ formatRelativeUnix(1710685845000, "en-US", {
 
 // roundingMethod ("floor" | "ceil" | "round", default "round") controls how the
 // computed distance rounds to the display unit — every formatRelative* function accepts it.
+// Any other value returns "".
 formatRelativeUtc(value, "en-US", { roundingMethod: "floor" });
 
 // formatCalendar* — a relative day label + time-of-day, joined with the
@@ -1805,6 +1822,40 @@ invalid input, and accepts only values inside the range `Temporal.Instant` can r
 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.
 
+**A zoned string names one instant in every reader.** Temporal writes a zone's offset rounded
+to the minute, so a zone with a sub-minute offset is written with an offset up to 30 seconds
+from the real one: `Africa/Monrovia` stood at −00:44:30 until 1972 and is written `-00:45`.
+Every GMT function that reads a moment reads such a string as `Temporal.ZonedDateTime.from`
+does (TC39 `ToTemporalZonedDateTime` matches a minute-precision offset by minutes), so a zoned
+string GMT wrote reads back as the instant it was written for:
+
+```typescript
+import { isValidZonedDateTime, toNanoseconds } from "@northguild/gmt";
+
+toNanoseconds("1960-01-01T00:20:00-00:45[Africa/Monrovia]"); // -315615330000000000n (01:04:30Z)
+toNanoseconds("1960-01-01T00:20:00-00:45"); // -315615300000000000n (01:05:00Z; no zone, so the offset is exact)
+toNanoseconds("2024-06-15T10:00:00Z[Not/AZone]"); // 1718445600000000000n (an instant reader does not validate the bracket)
+
+isValidZonedDateTime("1960-01-01T00:20:00-00:45[Africa/Monrovia]"); // true  (the rounded offset)
+isValidZonedDateTime("1960-01-01T00:20:00-00:44:30[Africa/Monrovia]"); // true  (the exact offset)
+isValidZonedDateTime("1960-01-01T00:20:00-00:45:00[Africa/Monrovia]"); // false (an offset with seconds must be exact)
+```
+
+- The rule applies to `precision/`, `span/`, `interval/`, `calendar/`, `intermodal/`,
+  `transport/` and `getTimeZoneOffset` alike. Any other string keeps its written offset: one
+  without a bracket, a `Z` instant, an offset written with seconds, and a bracket whose zone
+  does not exist or does not fit the offset.
+- Every string Temporal writes for an instant in range is valid, the first and last instants
+  included: `-271821-04-19T23:58:45-00:01[Europe/London]` is the first instant.
+- A function that keeps the zone (`isValidZonedDateTime`, `transitTime`, `toOffsetInstant`,
+  every `zoned/` function, a zoned `relativeTo`) rejects a bracket that contradicts the
+  offset, and requires an offset written with seconds to be the zone's offset exactly.
+- Two limits are Temporal's own. A wall time repeated inside a sub-minute offset change,
+  written to the minute, reads as its first pass (`1952-10-15T23:59:59-11:20[Pacific/Niue]`);
+  write the offset with seconds (`-11:20:00`) to name the second. A zoned read refuses a local
+  date of −271821-04-19, which a zone west of Greenwich shows for the first hours of the
+  instant range; pass that instant in `Z` form.
+
 ### Foreign epoch bridges
 
 Other systems do not count from 1970. NTP counts from 1900 and rolls over in 2036, Windows
@@ -2162,7 +2213,15 @@ isValidInterval({ start: "2024-01-01T17:00:00Z", end: "2024-01-01T09:00:00Z" });
 
 - **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
+  them may name different zones. Leap seconds are rejected, and a `[u-ca=…]` annotation is ignored, as `Temporal.Instant.from` ignores it.
+  The offset fixes the instant; an offset written to the minute that is the bracketed zone's
+  sub-minute offset rounded (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the
+  zone gives, so a zoned string GMT wrote is read back as the same moment. That holds
+  from the first instant of the range to the last. The one exception is Temporal's own: a wall
+  time repeated inside a sub-minute offset change, written with a minute-rounded offset, reads
+  as its first pass (for example `1952-10-15T23:59:59-11:20[Pacific/Niue]`; several zones have
+  such a change in their history).
+  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.
@@ -2179,6 +2238,666 @@ isValidInterval({ start: "2024-01-01T17:00:00Z", end: "2024-01-01T09:00:00Z" });
   is both a legitimate result (a fully covered subtraction) and the invalid-input sentinel.
   `isValidInterval` tells them apart.
 
+### Operating hours and open-time SLAs
+
+A business day answers "is Thursday a working day". A terminal gate, a support desk, a customs
+office and a night curfew ask a finer question: is it open right now, how many open hours have
+passed, and when does an SLA measured in open hours fall due. `calendar/hours` answers them from
+one `OperatingSchedule`: a zone, windows of local wall time for each ISO weekday, holiday dates,
+and dated overrides.
+
+```typescript
+import {
+  addOperatingTime,
+  isOpenAt,
+  nextCloseAt,
+  nextOpenAt,
+  operatingIntervals,
+  operatingTimeBetween,
+  recurringWindows,
+} from "@northguild/gmt";
+import type { OperatingSchedule } from "@northguild/gmt/types";
+
+const nineToFive = [{ from: "09:00", to: "17:00" }];
+const desk: OperatingSchedule = {
+  timeZone: "America/New_York",
+  weekly: { 1: nineToFive, 2: nineToFive, 3: nineToFive, 4: nineToFive, 5: nineToFive },
+  holidays: ["2024-07-04"],
+  overrides: [{ date: "2024-07-05", windows: [{ from: "10:00", to: "12:00" }] }],
+};
+
+operatingIntervals(desk, { start: "2024-07-04T04:00:00Z", end: "2024-07-06T04:00:00Z" });
+// [{ start: "2024-07-05T14:00:00Z", end: "2024-07-05T16:00:00Z" }] — the holiday is closed, the override replaces Friday
+
+isOpenAt("2024-06-17T14:00:00Z", desk); // true — Monday 10:00 local
+nextOpenAt("2024-06-15T16:00:00Z", desk); // "2024-06-17T13:00:00Z" — Saturday noon to Monday 09:00 local
+nextCloseAt("2024-06-17T14:00:00Z", desk); // "2024-06-17T21:00:00Z" — 17:00 local
+
+operatingTimeBetween("2024-06-14T20:00:00Z", "2024-06-17T14:00:00Z", desk); // "PT2H" — Friday 16:00 to Monday 10:00
+addOperatingTime("2024-06-14T20:00:00Z", "PT8H", desk); // "2024-06-17T20:00:00Z" — an 8-hour SLA from Friday 16:00: Monday 16:00
+addOperatingTime("2024-06-14T20:00:00Z", "PT8H", desk, { within: "P1D" }); // "" — not due within a day
+
+// A curfew wraps midnight and belongs to the night it starts on.
+recurringWindows(
+  { 6: [{ from: "23:00", to: "06:00" }] },
+  { start: "2024-11-02T00:00:00Z", end: "2024-11-04T00:00:00Z" },
+  "America/New_York",
+);
+// [{ start: "2024-11-03T03:00:00Z", end: "2024-11-03T11:00:00Z" }] — 8 hours across the fall-back night
+```
+
+- **Windows are half-open local wall time.** `{ from: "09:00", to: "17:00" }` is open at 09:00
+  and closed at 17:00. A `to` at or before its `from` wraps past midnight: `23:00`–`06:00` is a
+  night and `00:00`–`00:00` a whole day. A window belongs to the date it starts on, so a holiday
+  or override on Friday removes or replaces a Friday-night window, and one on Saturday does not.
+  Windows that overlap or touch merge, so a run of whole days is one interval.
+- **Every edge goes through `resolveLocal`.** The default `disambiguation` is `"compatible"`: an
+  edge in a repeated fall-back hour takes the earlier instant, and one in a skipped
+  spring-forward hour moves forward by the gap. So a 23:00–06:00 window is 8 real hours across
+  New York's fall-back night and 6 across its spring-forward night. Under `"earlier"`, a skipped
+  midnight can move a date's first window onto the previous date. `"earlier"` and `"later"`
+  pick the other instant. `"reject"` guesses nothing: it returns the sentinel when a window with
+  an ambiguous or nonexistent edge could change the answer, and ignores one that cannot.
+- **Dates are the zone's real local dates.** Holidays and overrides are ISO dates in the
+  schedule's zone. A `BusinessCalendar` can be passed as `holidays`; its `holidays` are read, and
+  its `weekend` is not, because `weekly` already says which weekdays open. A date the zone
+  deleted (`Pacific/Apia`, 2011-12-30) has no windows. An override wins over a holiday on the
+  same date, and `windows: []` closes a date.
+- **Open time is elapsed time.** `operatingTimeBetween` is the length of the open intervals
+  inside `[start, end)`, the same number `sumIntervals` gives for their intersections with the
+  range, with hours as the largest unit. `addOperatingTime` is its inverse: the earliest instant
+  at which that much open time has passed, so a deadline that lands on a closing time is that
+  closing time. Its duration is hours and smaller units: `P1D` of open time could mean 24 open
+  hours or one working day, so it returns `""`.
+- **Searches stop at a horizon.** `nextOpenAt`, `nextCloseAt` and `addOperatingTime` search up to
+  `within` after the input (default `"P1Y"`), added in the schedule's zone so `"P1D"` is one local
+  day. An answer exactly at the horizon counts; one past it returns `""`. A 24/7 schedule never
+  closes, so `nextCloseAt` returns `""` for it.
+- **Bounded walks.** A range spanning more than 10,000 local dates (about 27 years), counted from
+  its start's date, or a search that would go that far past its input, returns the sentinel
+  rather than a truncated answer. A search answers as soon as the answer is certain, so a long
+  `within` costs nothing when the answer is near. A horizon past Temporal's last instant stops
+  there.
+- **Not a recurrence engine.** A weekly pattern with dated exceptions covers gate hours, office
+  hours, trading sessions and curfews. Monthly and yearly RFC 5545 rules are out of scope.
+
+### Transport legs and dwell
+
+Every transport mode shares three operations: add a leg's duration to a departure, show the
+arrival in the zone where it lands, and measure how long something sat at a terminal, berth,
+gate or yard. Every mode also gets the same two things wrong: a leg across a DST transition is a
+fixed number of *elapsed* hours, and dwell is charged in *local calendar days*, not hours.
+
+```typescript
+import { dwellTime, etaAtZone, transitTime } from "@northguild/gmt";
+
+// A leg is exact time in the departure's own zone. Four elapsed hours across the
+// spring-forward: the wall clock reads 04:00, not 03:00.
+transitTime("2024-03-09T23:00:00-05:00[America/New_York]", "PT4H");
+// "2024-03-10T04:00:00-04:00[America/New_York]"
+
+// A day is 24 exact hours, not "the same wall time tomorrow".
+transitTime("2024-03-09T12:00:00-05:00[America/New_York]", "P1D");
+// "2024-03-10T13:00:00-04:00[America/New_York]"
+
+// The departure's form is preserved: Z stays Z, an offset stays an offset.
+transitTime("2024-06-15T10:00:00Z", "PT36H"); // "2024-06-16T22:00:00Z"
+transitTime("2024-06-15T10:00:00+09:00", "PT1H"); // "2024-06-15T11:00:00+09:00"
+transitTime("2024-06-15T10:00:00+05:30:15", "PT1H"); // "2024-06-15T11:00:00+05:30:15"
+
+// Calendar units need a reference point; a zone that contradicts its offset is rejected.
+transitTime("2024-06-15T10:00:00Z", "P1M"); // ""
+transitTime("2024-06-15T10:00:00-05:00[America/New_York]", "PT2H"); // "" (June is -04:00)
+
+// Render a moment where it will be read. No disambiguation arises: on a fall-back night
+// two arrivals an hour apart print the same wall time, and the offset tells them apart.
+etaAtZone("2024-06-15T12:30:00Z", "Asia/Tokyo"); // "2024-06-15T21:30:00+09:00[Asia/Tokyo]"
+etaAtZone("2024-11-03T05:30:00Z", "America/New_York"); // "2024-11-03T01:30:00-04:00[America/New_York]"
+etaAtZone("2024-11-03T06:30:00Z", "America/New_York"); // "2024-11-03T01:30:00-05:00[America/New_York]"
+
+// Dwell: exact duration, zone-local entry and exit, and the local calendar days touched.
+dwellTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "Europe/London");
+// { duration: "PT2H30M",
+//   enter: "2024-06-15T23:30:00+01:00[Europe/London]",
+//   exit: "2024-06-16T02:00:00+01:00[Europe/London]",
+//   calendarDays: 2 }
+
+// The same two instants, one fewer day: the zone decides.
+dwellTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "Europe/Amsterdam");
+// { duration: "PT2H30M",
+//   enter: "2024-06-16T00:30:00+02:00[Europe/Amsterdam]",
+//   exit: "2024-06-16T03:00:00+02:00[Europe/Amsterdam]",
+//   calendarDays: 1 }
+
+// The zone comes from targetZone or from the entry's bracketed zone. Bare instants with
+// neither return null: an offset is not a place, and a day count needs one.
+dwellTime("2024-06-15T22:30:00+01:00[Europe/London]", "2024-06-16T02:00:00+01:00[Europe/London]");
+// { duration: "PT3H30M",
+//   enter: "2024-06-15T22:30:00+01:00[Europe/London]",
+//   exit: "2024-06-16T02:00:00+01:00[Europe/London]",
+//   calendarDays: 2 }
+dwellTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z"); // null
+
+// Inverted intervals return null.
+dwellTime("2024-06-16T01:00:00Z", "2024-06-15T22:30:00Z", "Europe/London"); // null
+```
+
+- **`transitTime` adds exact time.** Hours, minutes, seconds and fractions are elapsed time and a
+  `D` component is 24 hours exactly, so the arrival wall clock reflects any DST shift in between.
+  Years, months and weeks return `""`: no leg takes "a month" without a reference point. A
+  negative duration moves backwards, which is how a departure is recovered from an arrival.
+- **`etaAtZone` renders a moment.** The input is an instant (`Z`, an offset, or an offset with a
+  bracketed zone), and only the instant is read; `targetZone` is where it is rendered. The zone
+  is the caller's fact: GMT does not resolve a port, airport or station code to a timezone. A
+  fixed offset such as `"+09:00"` is accepted as a zone, as `isValidTimeZone` accepts it.
+  `dwellTime` accepts one as `targetZone` too, and counts days in that offset, which observes
+  no DST.
+- **`dwellTime.calendarDays` counts local dates, not hours.** It is the number of distinct
+  local dates the half-open interval `[entry, exit)` touches: same date is `1`, across one
+  local midnight is `2`, and an exit exactly at local midnight does not touch the new day. It
+  is counted by walking the zone's real transitions, so a 23- or 25-hour local day is one day,
+  a date the zone deleted (`Pacific/Apia`, 2011-12-30) is never touched, and a date the clock
+  falls back into (`America/Goose_Bay`, 2010-11-07) is counted once. `duration` is the exact elapsed time with hours as the largest unit, as
+  `sumIntervals` reports it.
+
+### Crossings and multi-leg schedules
+
+A crossing (a canal transit, a strait passage, a border queue) is logged as two instants and
+read on the clock of whoever administers it. A multi-leg move (truck, ship, rail) is one
+departure, a duration per leg and a handling time at each handoff, and each handoff is where a
+naive implementation loses an hour. Every leg boundary here is an exact instant; local time is
+rendered only at the edges, with `etaAtZone`.
+
+```typescript
+import { crossingTime, scheduleDelivery } from "@northguild/gmt";
+
+// A crossing: exact elapsed time, both ends read in the zone that runs the crossing.
+crossingTime("2024-03-10T05:00:00Z", "2024-03-10T12:00:00Z", "America/New_York");
+// { duration: "PT7H",
+//   enter: "2024-03-10T00:00:00-05:00[America/New_York]",
+//   exit: "2024-03-10T08:00:00-04:00[America/New_York]" } (seven hours across the spring-forward)
+
+// targetZone is always the rendering zone; a bracketed zone on the input never is.
+crossingTime("2024-06-15T10:00:00+02:00[Europe/Berlin]", "2024-06-15T12:00:00+02:00[Europe/Berlin]", "Africa/Cairo");
+// { duration: "PT2H",
+//   enter: "2024-06-15T11:00:00+03:00[Africa/Cairo]",
+//   exit: "2024-06-15T13:00:00+03:00[Africa/Cairo]" }
+crossingTime("2024-06-16T01:00:00Z", "2024-06-15T22:30:00Z", "Europe/London"); // null (exit before entry)
+
+// Truck, ship, rail. The first departure is a published local wall time, read in startTimeZone.
+// The ship waits for its scheduled sailing; the rail leg leaves when the 48-hour dwell ends.
+const legs = [
+  { departure: "2024-06-14T08:00:00", duration: "PT6H", timeZone: "Asia/Shanghai",
+    dwellAfter: "PT12H", mode: "truck", origin: "CNSZX-DC", destination: "CNYTN" },
+  { departure: "2024-06-15T10:00:00+08:00[Asia/Shanghai]", duration: "PT336H",
+    timeZone: "America/Los_Angeles", dwellAfter: "PT48H", mode: "ship", origin: "CNYTN", destination: "USLAX" },
+  { duration: "PT70H", timeZone: "America/Chicago", mode: "rail", origin: "USLAX", destination: "USCHI" },
+];
+scheduleDelivery(legs, { startTimeZone: "Asia/Shanghai" });
+// { eta: "2024-07-03T19:00:00-05:00[America/Chicago]",
+//   legTimes: [
+//     { arrival: "2024-06-14T06:00:00Z", localArrival: "2024-06-14T14:00:00+08:00[Asia/Shanghai]",
+//       dwellAfter: "PT12H", mode: "truck", origin: "CNSZX-DC", destination: "CNYTN" },
+//     { arrival: "2024-06-29T02:00:00Z", localArrival: "2024-06-28T19:00:00-07:00[America/Los_Angeles]",
+//       dwellAfter: "PT48H", mode: "ship", origin: "CNYTN", destination: "USLAX" },
+//     { arrival: "2024-07-04T00:00:00Z", localArrival: "2024-07-03T19:00:00-05:00[America/Chicago]",
+//       dwellAfter: "PT0S", mode: "rail", origin: "USLAX", destination: "USCHI" } ] }
+
+// A sailing at 20:00 local on the 14th leaves inside the truck leg's 12-hour dwell: missed.
+scheduleDelivery([legs[0], { ...legs[1], departure: "2024-06-14T20:00:00+08:00[Asia/Shanghai]" }],
+  { startTimeZone: "Asia/Shanghai" }); // null
+
+scheduleDelivery(legs); // null (a zoneless first departure needs startTimeZone)
+scheduleDelivery([]); // { eta: "", legTimes: [] }
+```
+
+- **`crossingTime` counts no days.** It returns the exact duration, with hours as the largest
+  unit, and the entry and exit rendered in `targetZone`, an IANA identifier or a fixed offset.
+  A crossing that needs a day count is a dwell: use `dwellTime`. An exit before the entry
+  returns `null`; a zero-length crossing is `PT0S`.
+- **`dwellAfter` is the minimum connect time.** Each leg leaves at its own `departure`, or, when
+  it has none, at the previous arrival plus the previous leg's `dwellAfter`. A scheduled
+  departure earlier than that (inside the dwell, or before the arrival) is a missed connection
+  and returns `null`. Equal passes: a zero-slack connection is feasible. `dwellAfter` is echoed
+  as written (`"PT90M"` stays `"PT90M"`), `"PT0S"` when omitted. The last leg's `dwellAfter` is
+  validated and echoed but never added to an instant, because no leg follows it.
+- **Departures must be exact, with two wall-time exceptions.** A departure is an instant (`Z` or
+  an offset) or a zoned string, whose bracketed zone must be real and agree with its offset.
+  Schedules are published as local wall times, so a zoneless first departure is read in
+  `startTimeZone`, and a zoneless later-leg departure is read in the _previous_ leg's own
+  `timeZone` (leg N−1's destination is exactly leg N's departure zone). Zoneless without one of
+  these returns `null`.
+- **Wall times resolve as `"compatible"`.** A zoneless first departure, a zoneless later-leg
+  departure, or a zoned departure written without an offset, is a wall time. An ambiguous one (a
+  fall-back hour the clock ran through twice) resolves to the earlier instant; a skipped one (a
+  spring-forward hour) resolves to the later instant. Write the offset to pick the other pass of
+  a repeated hour. At a hub, a printed timetable never says which pass it means, so on any leg
+  but the first a repeated hour takes the earliest pass at or after the previous arrival plus its
+  dwell; when neither is that late, the connection is missed.
+- **Durations follow `transitTime`.** Time units are elapsed time and a day is 24 hours;
+  years, months and weeks return `null`. A negative leg returns `null`, because a leg cannot
+  arrive before it departs. A single-leg schedule is exactly `transitTime` composed with
+  `etaAtZone`.
+- **Tags are opaque.** `mode`, `origin` and `destination` are echoed onto each `LegTime` and are
+  absent when not supplied. GMT never resolves them to a zone: `timeZone` is the caller's fact.
+- Also exported: the `Crossing`, `Leg`, `LegTime`, `ScheduleDeliveryOptions` and
+  `DeliverySchedule` types.
+
+### Cut-offs and deadlines
+
+A logistics deadline is not a fixed timestamp. It counts back from an event (a vessel's
+departure, a container's loading, an arrival) in the local time of the place that enforces it,
+and it moves when that event moves. An ocean booking carries a stack of them: documentation,
+VGM, gate-in and customs. `cutoffAt` finds one, `cutoffSchedule` finds the whole stack, and
+`isPastCutoff` and `timeToCutoff` read the clock against one.
+
+```typescript
+import { cutoffAt, cutoffSchedule, isPastCutoff, timeToCutoff } from "@northguild/gmt";
+
+// A vessel sails Friday 14 June 2024 at 18:00 in Amsterdam (16:00Z).
+// "Two days before, 17:00" is 17:00 local on Wednesday: not 48 hours, which keeps 18:00.
+cutoffAt("2024-06-14T16:00:00Z", "P2D", { timeZone: "Europe/Amsterdam", atLocalTime: "17:00" });
+// "2024-06-12T17:00:00+02:00[Europe/Amsterdam]"
+cutoffAt("2024-06-14T16:00:00Z", "PT48H", { timeZone: "Europe/Amsterdam" });
+// "2024-06-12T18:00:00+02:00[Europe/Amsterdam]"
+
+// The whole stack against one departure, earliest first. Reschedule the vessel, call it again.
+cutoffSchedule("2024-06-14T16:00:00Z", [
+  { name: "gate-in", offset: "P1D" },
+  { name: "document", offset: "P2D", atLocalTime: "17:00" },
+  { name: "customs", offset: "PT30H" },
+  { name: "VGM", offset: "P1D", atLocalTime: "10:00" },
+], { timeZone: "Europe/Amsterdam" });
+// [ { name: "document", at: "2024-06-12T17:00:00+02:00[Europe/Amsterdam]" },
+//   { name: "VGM", at: "2024-06-13T10:00:00+02:00[Europe/Amsterdam]" },
+//   { name: "customs", at: "2024-06-13T12:00:00+02:00[Europe/Amsterdam]" },
+//   { name: "gate-in", at: "2024-06-13T18:00:00+02:00[Europe/Amsterdam]" } ]
+
+// A cut-off on a weekend or holiday moves by the roll convention you name. There is no default.
+cutoffAt("2024-06-18T16:00:00Z", "P2D", {
+  timeZone: "Europe/Amsterdam",
+  atLocalTime: "17:00",
+  calendar: { weekend: [6, 7], holidays: [], timeZone: "Europe/Amsterdam" },
+  roll: "preceding",
+}); // "2024-06-14T17:00:00+02:00[Europe/Amsterdam]" (Sunday rolls back to Friday)
+
+// The anchor is the caller's event. The same 24 hours from loading and from departure:
+cutoffAt("2024-06-10T08:00:00Z", "PT24H", { timeZone: "Asia/Shanghai" });
+// "2024-06-09T16:00:00+08:00[Asia/Shanghai]"
+cutoffAt("2024-06-12T20:00:00Z", "PT24H", { timeZone: "Asia/Shanghai" });
+// "2024-06-12T04:00:00+08:00[Asia/Shanghai]"
+
+// 96 hours before an arrival is exact elapsed time, across New York's fall-back.
+cutoffAt("2024-11-05T17:00:00Z", "PT96H", { timeZone: "America/New_York" });
+// "2024-11-01T13:00:00-04:00[America/New_York]"
+
+// A cut-off in an hour the clock skipped is refused, not moved.
+cutoffAt("2024-03-11T22:00:00Z", "P1D", { timeZone: "America/New_York", atLocalTime: "02:30" }); // ""
+
+isPastCutoff("2024-06-12T16:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]"); // true
+timeToCutoff("2024-06-12T16:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]"); // "-PT1H"
+timeToCutoff("2024-06-10T15:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]"); // "PT48H"
+```
+
+- **`atLocalTime` pins the time of day.** With it, only the day the offset lands on matters: the
+  offset's exact part (hours and smaller) comes off the anchor's instant, its calendar part
+  (years, months, weeks, days) off that local date, and the cut-off is `atLocalTime` on that day.
+  The exact part comes off first, so it can change the day: from midnight, `P2DT0.000000001S`
+  lands a day before `P2D`. Without it, the offset is taken off as Temporal's `ZonedDateTime#subtract` takes it: `P2D`
+  keeps the anchor's wall clock, and `PT96H` is 96 elapsed hours.
+- **The anchor is exact and is the caller's event.** An instant (`Z` or an offset) or a zoned
+  string; its bracket never supplies the zone, and `timeZone` (an IANA identifier or a fixed
+  offset) is the local frame. `cutoffAt` never guesses whether a rule counts from loading, departure or arrival.
+  The functions are pure, so a rescheduled departure is a new call, not a stored cut-off to fix.
+- **Non-business days roll as you say.** With `calendar` (a `BusinessCalendar`), a cut-off on a
+  weekend or holiday moves by `roll`, as `rollDate` moves it, and keeps its local time of day.
+  Every industry answers "what if it lands on a non-working day" differently, so the convention
+  is always explicit and there is no default: `calendar` without `roll`, or `roll` without
+  `calendar`, returns `""`. `calendar.timeZone` is not read. `"endOfMonth"` is `rollDate`'s
+  schedule tool, not a cut-off convention.
+- **The order is not checked.** `cutoffAt` does not check that the cut-off is before the anchor.
+  A negative offset, `P0D` with a late `atLocalTime`, `"following"` or `"endOfMonth"` can each
+  put it after.
+- **Local wall times resolve for a deadline.** `atLocalTime`, the calendar part of an unpinned
+  offset and a rolled day are wall times. An ambiguous one (a fall-back hour the clock ran
+  through twice) takes the earlier instant, the first occurrence, as RFC 5545 §3.3.5 reads a
+  repeated local time. A nonexistent one (a spring-forward hour, a deleted day) returns `""`
+  rather than shifting the deadline.
+- **`cutoffSchedule` is all or nothing.** Each entry is `cutoffAt` with its own `atLocalTime`;
+  the result is sorted by instant, and entries on the same instant keep their order. One invalid
+  entry returns `[]`, never a stack with a deadline missing.
+- **The window closes at the cut-off.** `isPastCutoff` is `true` from the cut-off instant on, and
+  `timeToCutoff` is `PT0S` there, exact hours before it and negative after it. Both compare
+  instants, and `now` is always the caller's. Both return their sentinel (`false`, `""`) for
+  `cutoffAt`'s `""`, so check the cut-off first.
+- Also exported: the `CutoffOptions`, `Cutoff`, `CutoffTime` and `CutoffScheduleOptions` types.
+
+### Punctuality, timestamp classes and the next departure
+
+Every mode publishes a plan and records what happened, and measures the gap the same way. Only
+the tolerance differs, and it is the caller's. `scheduleDeviation` measures the gap,
+`classifyPunctuality` judges it against a tolerance, and `punctualityRate` counts a list of
+arrivals under one. One field often holds four kinds of time (planned, estimated, requested and
+actual), so `bestAvailable` returns the class with the value, and `estimateDrift` measures how far
+an estimate moved. `nextDeparture` finds the departure a connection can make.
+
+```typescript
+import {
+  bestAvailable,
+  classifyPunctuality,
+  estimateDrift,
+  nextDeparture,
+  punctualityRate,
+  scheduleDeviation,
+  type TimestampEvent,
+} from "@northguild/gmt";
+
+scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-15T10:14:00Z"); // "PT14M"
+scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-15T09:55:00Z"); // "-PT5M" (early)
+scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-17T11:30:00Z"); // "PT49H30M" (hours, never days)
+// The same wall time, an hour later across New York's fall-back: 60 minutes, not 0.
+scheduleDeviation("2024-11-03T01:30:00-04:00[America/New_York]", "2024-11-03T01:30:00-05:00[America/New_York]");
+// "PT1H"
+
+// A 15-minute tolerance. Exactly 15 minutes is late: on time is strictly inside.
+classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:14:59Z", { late: "PT15M" }); // "onTime"
+classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:15:00Z", { late: "PT15M" }); // "late"
+// Without `early`, an early arrival is on time. With it, 11 minutes early is early.
+classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T09:49:00Z", { late: "PT15M" }); // "onTime"
+classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T09:49:00Z", { late: "PT15M", early: "PT10M" }); // "early"
+// The same 90-minute delay under a 60-minute and a 120-minute tolerance.
+classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T11:30:00Z", { late: "PT60M" }); // "late"
+classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T11:30:00Z", { late: "PT120M" }); // "onTime"
+classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:14:00Z", { late: "P1W" }); // null (weeks have no exact length)
+
+punctualityRate([
+  { planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:05:00Z" },
+  { planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:14:00Z" },
+  { planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:16:00Z" },
+  { planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T09:57:00Z" },
+], { late: "PT15M" }); // { onTime: 3, total: 4, rate: 0.75 }
+punctualityRate([], { late: "PT15M" }); // null
+
+// An estimate recorded after the actual is still only an estimate.
+bestAvailable([
+  { classifier: "ACT", at: "2024-06-15T12:52:00Z", recordedAt: "2024-06-15T12:53:00Z" },
+  { classifier: "EST", at: "2024-06-15T13:05:00Z", recordedAt: "2024-06-15T14:00:00Z" },
+]); // { at: "2024-06-15T12:52:00Z", classifier: "ACT" }
+// Never an estimate when a request exists.
+bestAvailable([
+  { classifier: "EST", at: "2024-06-15T12:40:00Z", recordedAt: "2024-06-14T00:00:00Z" },
+  { classifier: "REQ", at: "2024-06-15T12:30:00Z", recordedAt: "2024-06-12T00:00:00Z" },
+]); // { at: "2024-06-15T12:30:00Z", classifier: "REQ" }
+
+// Three revisions of one arrival estimate: it slid nine hours.
+const estimates: TimestampEvent[] = [
+  { classifier: "EST", at: "2024-06-20T08:00:00Z", recordedAt: "2024-06-01T00:00:00Z" },
+  { classifier: "EST", at: "2024-06-20T12:00:00Z", recordedAt: "2024-06-05T00:00:00Z" },
+  { classifier: "EST", at: "2024-06-20T17:00:00Z", recordedAt: "2024-06-10T00:00:00Z" },
+];
+estimateDrift(estimates, { tolerance: "PT8H" });
+// { first: "2024-06-20T08:00:00Z", last: "2024-06-20T17:00:00Z", drift: "PT9H", revisions: 3, exceedsTolerance: true }
+estimateDrift(estimates.slice(0, 1)); // null (no drift from one estimate)
+
+const timetable = ["2024-06-15T08:00:00Z", "2024-06-15T09:30:00Z", "2024-06-15T11:00:00Z"];
+nextDeparture("2024-06-15T09:00:00Z", timetable); // "2024-06-15T09:30:00Z"
+nextDeparture("2024-06-15T09:00:00Z", timetable, { minimumConnection: "PT45M" }); // "2024-06-15T11:00:00Z"
+nextDeparture("2024-06-15T09:00:00Z", ["2024-06-15T09:30:00"]); // "" (a timetable entry needs an offset)
+
+// Every 20 minutes from 06:00, up to but never at 09:00.
+const shuttle = { headway: "PT20M", from: "2024-06-15T06:00:00+02:00", to: "2024-06-15T09:00:00+02:00" };
+nextDeparture("2024-06-15T06:05:00+02:00", shuttle); // "2024-06-15T06:20:00+02:00"
+nextDeparture("2024-06-15T09:00:00+02:00", shuttle); // ""
+```
+
+- **A deviation is exact elapsed time.** `scheduleDeviation` is `actual` minus `planned` with
+  hours as the largest unit: positive when late, negative when early, `"PT0S"` on the plan. A
+  delay across a DST transition is measured in real minutes, never wall-clock ones. Both times
+  are an instant (`Z` or an offset) or a zoned string; the zone each is written in does not
+  matter. The offset fixes the instant, and a bracketed zone resolves only a rounded one: an
+  offset written to the minute that is the zone's sub-minute offset rounded
+  (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, so a zoned string
+  GMT wrote is read back as the same moment, except a wall time repeated inside a sub-minute
+  offset change, which reads as its first pass. To show a schedule's local time, use `etaAtZone`.
+- **"On time" needs a stated tolerance.** GMT holds no default. A `PunctualityTolerance` is
+  `{ late, early? }` as ISO 8601 durations of exact time: a day is 24 hours, and years, months,
+  weeks or a negative value return `null`. Tolerances differ by mode (15 minutes, a 60/120-minute
+  pair, a day), and each is the same call with different numbers.
+- **Both edges belong to the outside.** A deviation of `late` or more is late; with `early`, one
+  of `-early` or less is early. Without `early`, every early arrival is on time. `late: "PT0S"`
+  makes an arrival exactly on the plan late. This half-open convention is GMT's own, stated here.
+  `classifyPunctuality` returns `null` on invalid input.
+- **A rate is a count under one tolerance.** `punctualityRate` reads the tolerance once and
+  judges every pair under it. Only `"onTime"` counts, so with an `early` tolerance an early
+  arrival is not on time. `rate` is `onTime / total`, not rounded. An empty list, or any invalid
+  pair, returns `null`, never a rate over the rest. Percentiles and causes are the consumer's.
+- **The class travels with the value.** A `TimestampEvent` is `{ classifier, at, recordedAt }`,
+  with `classifier` one of DCSA's `PLN`, `EST`, `REQ` and `ACT`. `bestAvailable` picks an `ACT`
+  whenever one exists, else `PLN`, else `REQ`, else `EST`, and within that class the latest
+  `recordedAt`. This order is GMT's and is not configurable. It reads, from its most settled
+  end, the estimated, requested, planned, then actual pattern that
+  [DCSA's Port Call standard](https://reference.dcsa.org/content/standards/releases/port-call/v2-0-0/port-call-v2-0-0-use-cases)
+  describes for some port call services; DCSA defines the classes and that pattern, not a
+  selection rule. `at` is echoed exactly as written. An empty list or any invalid event returns
+  `null`.
+- **Drift needs two estimates.** `estimateDrift` reads only the `EST` records, in `recordedAt`
+  order, and reports the last `at` minus the first, negative when the estimate moved earlier. It
+  returns `null` with fewer than two, since one estimate has no drift. With `tolerance`,
+  `exceedsTolerance` is `true` when the drift in either direction is greater than it; exactly the
+  tolerance is `false`. Without it, `null`.
+- **`nextDeparture` is timetable lookup, not routing.** It returns the first departure at or
+  after `after` plus `minimumConnection` (default `"PT0S"`, exact time, not negative); one exactly
+  at that threshold is made. A list entry is returned exactly as written, so it can go straight
+  into `scheduleDelivery` as a leg's `departure`. Every moment (`after`, each entry, `from` and
+  `to`) must carry its offset, as `nextOpenAt` requires: a wall time without one returns `""`,
+  because in a repeated fall-back hour it names two departures. One invalid entry returns `""`.
+- **A headway window is half-open.** `{ headway, from, to }` has the shape of a GTFS
+  [`frequencies.txt`](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#frequenciestxt) row. Departures are `from` plus whole headways in exact time, up to but never
+  at `to`, and are computed from `from`, not stepped, so a long window costs nothing. Across a DST
+  transition they keep their spacing and the wall clock shifts. The result is written the way
+  `from` was written.
+- Also exported: the `TimestampClass`, `TimestampEvent`, `PunctualityTolerance`, `Punctuality`,
+  `PlannedActual`, `OnTimeRate`, `ClassifiedTimestamp`, `EstimateDriftOptions`, `DriftReport`,
+  `Headway` and `NextDepartureOptions` types.
+
+### Free time and demurrage
+
+Free time is the money calculation in container logistics, and none of its terms is a fact about
+the port or fixed by a world standard. How many days are free, whether the day of discharge is
+free day one, how free days and charged days are counted, and which clock a charge runs on are set
+by the carrier's tariff and the service contract. DCSA defines what demurrage, detention and
+storage are, but not how their days are counted. So every term is a parameter, no counting term has a default, and what comes back is the free-time window and the specific dates charged.
+
+```typescript
+import { chargeableDays, demurrageClock, freeTimeExpiry } from "@northguild/gmt";
+
+const tariff = { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" };
+
+// A Friday afternoon discharge in New York with three free calendar days: the weekend is
+// consumed, and free time ends at Monday 00:00 local.
+freeTimeExpiry("2024-06-14T19:00:00Z", 3, tariff);
+// { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-16", expiresAt: "2024-06-17T04:00:00Z" }
+
+// The same tariff read the other way: one more day. firstDay has no default.
+freeTimeExpiry("2024-06-14T19:00:00Z", 3, { ...tariff, firstDay: "nextDay" });
+// { freeTimeStart: "2024-06-15", lastFreeDay: "2024-06-17", expiresAt: "2024-06-18T04:00:00Z" }
+freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York" }); // null
+
+// Working days skip the weekend, and a terminal holiday moves expiry a day.
+const terminal = { weekend: [6, 7], holidays: [], timeZone: "America/New_York" };
+freeTimeExpiry("2024-06-14T19:00:00Z", 3, { ...tariff, basis: "working", calendar: terminal });
+// { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" }
+freeTimeExpiry("2024-06-14T19:00:00Z", 3, { ...tariff, basis: "working", calendar: { ...terminal, holidays: ["2024-06-17"] } });
+// { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-19", expiresAt: "2024-06-20T04:00:00Z" }
+
+// Expiry is half-open: out exactly as free time ends is free, one second later is a charged day,
+// and the date is listed.
+chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:00Z", 3, tariff);
+// { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z",
+//   chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] }
+chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, tariff);
+// { freeDaysUsed: 3, chargeableDays: 1, expiresAt: "2024-06-17T04:00:00Z",
+//   chargedDates: ["2024-06-17"], byTier: [{ from: 1, to: null, days: 1 }] }
+
+// Charged days are counted on their own basis. Where a tariff grants free time in working days,
+// the days after it are mostly charged as calendar days; some tariffs charge working days only.
+const juneteenth = { ...terminal, holidays: ["2024-06-19"] };
+chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { ...tariff, basis: "working", calendar: juneteenth });
+// { freeDaysUsed: 3, chargeableDays: 6, expiresAt: "2024-06-19T04:00:00Z",
+//   chargedDates: ["2024-06-19", "2024-06-20", "2024-06-21", "2024-06-22", "2024-06-23", "2024-06-24"],
+//   byTier: [{ from: 1, to: null, days: 6 }] }
+chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { ...tariff, basis: "working", chargeBasis: "working", calendar: juneteenth });
+// { freeDaysUsed: 3, chargeableDays: 3, expiresAt: "2024-06-19T04:00:00Z",
+//   chargedDates: ["2024-06-20", "2024-06-21", "2024-06-24"],
+//   byTier: [{ from: 1, to: null, days: 3 }] }
+
+// Tiers are day bands, not rates: twelve charged days in bands of 5, 5 and the rest.
+chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { ...tariff, tiers: [5, 10] });
+// { freeDaysUsed: 3, chargeableDays: 12, expiresAt: "2024-06-17T04:00:00Z",
+//   chargedDates: ["2024-06-17", "2024-06-18", "2024-06-19", "2024-06-20", "2024-06-21",
+//                  "2024-06-22", "2024-06-23", "2024-06-24", "2024-06-25", "2024-06-26",
+//                  "2024-06-27", "2024-06-28"],
+//   byTier: [{ from: 1, to: 5, days: 5 }, { from: 6, to: 10, days: 5 }, { from: 11, to: null, days: 2 }] }
+
+// Which two events a charge runs between, on the import or the export leg.
+const imported = [
+  { type: "discharged", at: "2024-06-14T19:00:00Z" },
+  { type: "available", at: "2024-06-15T12:00:00Z" },
+  { type: "gatedOut", at: "2024-06-20T14:30:00Z" },
+  { type: "emptyReturned", at: "2024-06-27T09:00:00Z" },
+];
+demurrageClock(imported, "demurrage", { direction: "import" }); // { start: "2024-06-14T19:00:00Z", end: "2024-06-20T14:30:00Z" }
+demurrageClock(imported, "detention", { direction: "import" }); // { start: "2024-06-20T14:30:00Z", end: "2024-06-27T09:00:00Z" }
+demurrageClock(imported, "combined", { direction: "import" }); // { start: "2024-06-14T19:00:00Z", end: "2024-06-27T09:00:00Z" }
+demurrageClock(imported, "demurrage", { direction: "import", startEvent: "available" }); // { start: "2024-06-15T12:00:00Z", end: "2024-06-20T14:30:00Z" }
+const exported = [
+  { type: "emptyReleased", at: "2024-07-01T08:00:00Z" },
+  { type: "gatedIn", at: "2024-07-05T16:00:00Z" },
+  { type: "loaded", at: "2024-07-09T03:00:00Z" },
+];
+demurrageClock(exported, "demurrage", { direction: "export" }); // { start: "2024-07-05T16:00:00Z", end: "2024-07-09T03:00:00Z" }
+demurrageClock(exported, "detention", { direction: "export" }); // { start: "2024-07-01T08:00:00Z", end: "2024-07-05T16:00:00Z" }
+demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }], "demurrage", { direction: "import" }); // null (no gate-out yet)
+```
+
+- **Days are the terminal's local days.** `clockStart` and `clockEnd` are instants; their local
+  dates in `options.timeZone` are what is counted, over the zone's real day boundaries, the same
+  ones `dwellTime` and `floorToZone` find. A 23- or 25-hour day is one day, a date the zone deleted
+  is never a free or charged day, and a date the clock falls back into counts once. On the calendar
+  basis with `firstDay: "eventDay"`, `freeDaysUsed + chargeableDays` is exactly
+  `dwellTime(...).calendarDays` for the same dwell, except that a fall-back re-entering the day
+  before the event day (Goose Bay, 7 November 2010) is a date `dwellTime` counts and a tariff
+  never does.
+- **`firstDay` has no default.** `"eventDay"` makes the event day free day one; `"nextDay"` starts
+  free time the following counted day. The two differ by a full day of charges, so omitting it
+  returns `null`.
+- **`basis` counts free days; `chargeBasis` counts charged days.** `"calendar"` counts every local
+  day; `"working"` counts only the working days of `options.calendar`, a `BusinessCalendar` (its
+  weekend and holidays; its `timeZone` is not read), and returns `null` without one. Many tariffs
+  count both in calendar days. Where a tariff grants free time in working days, the days after it
+  are mostly charged as calendar days; some tariffs charge working days only. Neither has a default.
+  "Calendar days excluding bank holidays" is `"working"` with an empty `weekend`.
+- **Expiry is half-open.** `expiresAt` is the first instant of the local day after `lastFreeDay`, as
+  a UTC instant. A gate-out at exactly `expiresAt` is not a chargeable day; one nanosecond later is.
+- **`chargedDates` makes the count auditable.** It is the list a carrier's day-numbered tariff grid
+  is applied to, and the dates an itemised invoice can list.
+- **Tiers are day bands, not rates.** `tiers: [5, 10]` names days 1–5, 6–10 and 11 onward; `byTier`
+  says how many charged days fell in each band, empty bands included, so a rate table applies by
+  index. Omitted, it is the single open band. GMT computes days, never money.
+- **`freeDays: 0`** is a tariff with no free time: `chargeableDays` charges every counted day from day
+  one, and `freeTimeExpiry` returns `null` because there is no last free day to name.
+- **`demurrageClock` selects the pair, per leg.** DCSA's glossary puts demurrage inside the terminal
+  or depot and detention outside it; the carriers' published tariffs agree on the events. Import: demurrage and
+  storage run from `startEvent` (`"discharged"` by default, or `"available"`) to `gatedOut`, detention
+  from `gatedOut` to `emptyReturned`, and the combined clock from `startEvent` to `emptyReturned`.
+  Export: demurrage and storage run from `gatedIn` to `loaded`, detention from `emptyReleased` to
+  `gatedIn`, and the combined clock from `emptyReleased` to `loaded`. `direction` has no default. The
+  event names follow DCSA's Track & Trace equipment events (DISC, GTOT, GTIN, LOAD). A required event
+  that is missing or present twice, or an end before its start, returns `null`, and the result is an
+  `Interval` in the caller's own strings, ready for `chargeableDays(start, end, …)`.
+
+### Billing deadlines
+
+A billing regime or service contract can set up to three windows around a demurrage or
+detention invoice: one to issue it, counted from an anchor date; one to dispute it, counted from
+issuance; and one to resolve the dispute, counted from the request, unless the parties
+agree a date instead. The number of days in each is the caller's fact; GMT carries none of them. The arithmetic
+is the function's: each deadline is a date, counted in calendar days from a date, with the anchor
+as day zero and the deadline day itself inside the window.
+
+```typescript
+import { billingTimeline, convertUtcToPlainDate } from "@northguild/gmt";
+
+const windows = { issueDays: 30, disputeDays: 30, resolutionDays: 30 };
+
+// Charges last accrued on 1 March. Day 30 is the last day by the deadline; day 31 is not.
+billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-31" }, windows);
+// { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-30",
+//   requestedByDeadline: null, resolutionDeadline: null }
+billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-04-01" }, windows);
+// { invoiceDeadline: "2026-03-31", issuedByDeadline: false, disputeDeadline: "2026-05-01",
+//   requestedByDeadline: null, resolutionDeadline: null }
+
+// No invoice yet: a forecast. Only the invoice deadline is known.
+billingTimeline({ anchorOn: "2026-03-01" }, windows);
+// { invoiceDeadline: "2026-03-31", issuedByDeadline: null, disputeDeadline: null,
+//   requestedByDeadline: null, resolutionDeadline: null }
+
+// A dispute received on the dispute deadline, and one received a day later with a resolution
+// date the parties agreed, which replaces the computed one.
+billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-20", requestReceivedOn: "2026-04-19" }, windows);
+// { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-19",
+//   requestedByDeadline: true, resolutionDeadline: "2026-05-19" }
+billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-20", requestReceivedOn: "2026-04-20" }, { ...windows, agreedResolutionOn: "2026-06-01" });
+// { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-19",
+//   requestedByDeadline: false, resolutionDeadline: "2026-06-01" }
+
+// A re-bill is anchored on the invoice it received (issued 10 March), not on the charge.
+billingTimeline({ anchorOn: "2026-03-10", invoiceIssuedOn: "2026-04-05" }, windows);
+// { invoiceDeadline: "2026-04-09", issuedByDeadline: true, disputeDeadline: "2026-05-05",
+//   requestedByDeadline: null, resolutionDeadline: null }
+
+// A 14/14/45 service contract through the same chain: the numbers are the caller's.
+billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-05", requestReceivedOn: "2026-03-18" }, { issueDays: 14, disputeDays: 14, resolutionDays: 45 });
+// { invoiceDeadline: "2026-03-15", issuedByDeadline: true, disputeDeadline: "2026-03-19",
+//   requestedByDeadline: true, resolutionDeadline: "2026-05-02" }
+
+// Windows have no defaults.
+billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-31" }, { disputeDays: 30, resolutionDays: 30 }); // null
+
+// Deadlines are dates. Reduce an instant to the billing party's local date first.
+convertUtcToPlainDate("2024-06-17T04:00:01Z", { timeZone: "America/New_York" }); // "2024-06-17"
+```
+
+- **Day zero is the anchor and the deadline is `anchor + days`** on the ISO calendar
+  (`Temporal.PlainDate.add`); a date is by the deadline when it is on or before it
+  (`Temporal.PlainDate.compare(date, deadline) <= 0`). That is the function's stated contract, not
+  a reading of any rule; a regime that counts differently passes a different number. Thirty days
+  across a leap day, a month end, a year end or a DST change is thirty dates, never thirty times
+  24 hours: `2028-01-30` plus 30 is `2028-02-29`.
+- **Deadlines are dates, never instants.** Reduce an instant to the billing party's local date
+  first with `convertUtcToPlainDate(instant, { timeZone })`; the function does not guess a zone,
+  and a date-time or an instant passed as a date returns `null`.
+- **Windows have no defaults.** Each is a safe integer of at least `0`; a missing, negative or
+  non-integer window returns `null`, because a silently defaulted window is a wrong deadline. The
+  same rule as `firstDay`.
+- **The anchor is whatever date the caller counts from.** The last date a charge accrued is
+  `chargeableDays(...).chargedDates.at(-1)`. A party re-billing a charge it was itself billed
+  passes the issuance date of the invoice it received; the chain is the same.
+- **The chain fills in as its dates exist.** With only `anchorOn` the result is a forecast:
+  `invoiceDeadline` is set and every other field is `null`. An invoice date sets
+  `issuedByDeadline` and `disputeDeadline`; a request date sets `requestedByDeadline` and
+  `resolutionDeadline`. A request without an invoice, or dated before it, is a data error and
+  returns `null`; an invoice dated before the anchor is allowed, because an invoice may be issued
+  while charges still accrue.
+- **An agreed date replaces the computed resolution deadline.** `agreedResolutionOn` must be a
+  valid date on or after `requestReceivedOn`, else `null`; it is validated even when no request
+  exists, but cannot act without one. Every emitted date is bare ISO, so an input annotation such
+  as `[u-ca=iso8601]` does not reach the output.
+- **GMT computes dates, not liability.** `issuedByDeadline` and `requestedByDeadline` compare
+  dates and say nothing else. Whether a charge is payable, whether a dispute must be heard, and
+  any consequence are the consumer's, the sibling of "GMT computes days, never money".
+
 ## API Surface
 
 For the complete API listing, see the namespace documentation on GitHub:
@@ -2189,8 +2908,10 @@ For the complete API listing, see the namespace documentation on GitHub:
 - [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
+- [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, business calendars with holiday sets and roll conventions, and operating hours: open intervals, open or closed now, open time elapsed and SLA deadlines
 - [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
+- [Transport API](https://github.com/northguild/gmt/tree/main/packages/gmt/src/transport) — transit legs as exact elapsed time, arrivals rendered in the zone where they land, dwell in local calendar days, crossings, multi-leg delivery schedules, cut-offs, schedule deviation and punctuality, PLN/EST/REQ/ACT timestamp classes, and timetable and headway departures
+- [Intermodal API](https://github.com/northguild/gmt/tree/main/packages/gmt/src/intermodal) — free time, demurrage and detention: which clock, which start day, calendar or working days, and the charged dates an itemised invoice can list, plus the deadline chain around the invoice with every window a caller parameter
 - [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