@northguild/gmt 1.16.0 → 1.17.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.
+- **~55× more CI test executions than all four competitors combined**: 1,109,250 from 36,975 tests run in all 10 timezones × 3 Node versions, vs. their combined 20,190.
+- **~96× more test cases than `@internationalized/date`**: 36,975 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:** 36,975 tests across 674 files that exercise real behavior differences without redundant permutations. They run in CI as 1,109,250 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                      | 674                                                | 6                              | 58 / 60<br>(2 didn't run<br>locally) | 256                                       | 191<br>(52 core +<br>139 locale) |
+| Individual test cases           | **36,975**                                         | 386                            | 1,222                                | 3,213                                     | 3,901                            |
+| Effective CI test<br>executions | **1,109,250**<br>(36,975 × 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 ~55×                                                  | 1,109,250 vs. 386 + 4,888 + 3,213<br>+ 11,703 = 20,190                                                                                  |
 
 ## Package Layout
 
@@ -160,7 +160,7 @@ 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/duration`: ISO 8601 duration string parsing, validation, and arithmetic
@@ -169,6 +169,8 @@ The twelve namespace subpaths:
 - `@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, and dwell measured in local calendar days
+- `@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
@@ -2179,6 +2181,283 @@ 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.
 
+### 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.
+
+### 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:
@@ -2191,6 +2470,8 @@ For the complete API listing, see the namespace documentation on GitHub:
 - [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
+- [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
+- [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

package/dist/index.d.ts

@@ -2,11 +2,13 @@ export * from "@js-temporal/polyfill";
 export * from "./calendar/index.js";
 export * from "./duration/index.js";
 export * from "./instant/index.js";
+export * from "./intermodal/index.js";
 export * from "./interval/index.js";
 export * from "./plain/index.js";
 export * from "./precision/index.js";
 export * from "./regex/index.js";
 export * from "./span/index.js";
+export * from "./transport/index.js";
 export * from "./types/index.js";
 export * from "./unix/index.js";
 export * from "./utc/index.js";

package/dist/index.js

@@ -2,11 +2,13 @@ export * from "@js-temporal/polyfill";
 export * from "./calendar/index.js";
 export * from "./duration/index.js";
 export * from "./instant/index.js";
+export * from "./intermodal/index.js";
 export * from "./interval/index.js";
 export * from "./plain/index.js";
 export * from "./precision/index.js";
 export * from "./regex/index.js";
 export * from "./span/index.js";
+export * from "./transport/index.js";
 export * from "./types/index.js";
 export * from "./unix/index.js";
 export * from "./utc/index.js";

package/dist/instant/convert/fromOffsetInstant.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { formatUtcOffset, parseInstantNanoseconds, parseUtcOffsetNanoseconds, } from "../../internal/index.js";
+import { formatUtcOffset, parseInstantNanoseconds, parseUtcOffsetNanoseconds, wallClockAtOffset, } from "../../internal/index.js";
 import { utcOffset } from "../../regex/index.js";
 /**
  * Render an instant-plus-offset pair back to the local time it describes.
@@ -75,16 +75,8 @@ export function fromOffsetInstant(value) {
                 return zoned.offset === offset ? zoned.toString() : "";
             }
             // With no zone, the offset is the only thing that can shift the instant onto a wall
-            // clock. The shift happens on the wall clock, never on the instant: `PlainDateTime`
-            // reaches a day further either side than `Instant` does, so shifting the instant first
-            // would reject the last 14 hours of the representable range — where a pair like
-            // `{ "+275760-09-13T00:00:00Z", "+14:00" }` names a local time that exists. No offset
-            // time zone is used either, since Temporal refuses to build one from a sub-minute
-            // offset.
-            const wallClock = instant
-                .toZonedDateTimeISO("UTC")
-                .toPlainDateTime()
-                .add({ nanoseconds: Number(offsetNanoseconds) });
+            // clock (`wallClockAtOffset` keeps both range limits and sub-minute offsets).
+            const wallClock = wallClockAtOffset(instant, offsetNanoseconds);
             return `${wallClock.toString()}${offset}`;
         }
         catch {

package/dist/instant/convert/toOffsetInstant.d.ts

@@ -1,3 +1,26 @@
+/**
+ * An absolute instant paired with the local UTC offset in force where the event happened.
+ *
+ * @remarks Members:
+ *
+ * | Member | Type | Description |
+ * | --- | --- | --- |
+ * | `instant` | `string` | UTC instant, ISO 8601 ending in `Z` (e.g. `2024-07-15T16:00:00Z`). Orders events globally. |
+ * | `offset` | `string` | UTC offset in force where the event happened, `±HH:MM` (or `±HH:MM:SS` for a pre-1972 zone that did not run on a whole minute). Renders the event as the human on the ground saw it. |
+ * | `timeZone` | `string \| undefined` | IANA zone identifier, when one is known. Absent from most feeds, so absent from most pairs. |
+ *
+ * Neither `instant` nor `offset` derives from the other, which is why both are stored. It is
+ * the shape GS1 EPCIS 2.0 (`eventTime` + a required `eventTimeZoneOffset`), UN/EDIFACT DTM
+ * (qualifier `303`/`304`) and DICOM (`DT` + `&ZZXX`) all exchange.
+ *
+ * @example
+ * import { OffsetInstant } from "@northguild/gmt/instant";
+ * const pair: OffsetInstant = {
+ *   instant: "2024-07-15T16:00:00Z",
+ *   offset: "-04:00",
+ *   timeZone: "America/New_York",
+ * };
+ */
 export interface OffsetInstant {
     instant: string;
     offset: string;

package/dist/instant/convert/toOffsetInstant.js

@@ -1,32 +1,9 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { formatUtcOffset, isoStringBody, parseInstantNanoseconds, zonedDateTimeFrom, } from "../../internal/index.js";
+import { formatUtcOffset, isoStringBody, parseInstantNanoseconds, TIME_ZONE_ANNOTATION, zonedDateTimeFrom, } from "../../internal/index.js";
 import { utcOffset } from "../../regex/index.js";
 import { isValidTimeZone } from "../../zoned/validate/index.js";
-/**
- * An absolute instant paired with the local UTC offset in force where the event happened.
- *
- * @remarks Members:
- *
- * | Member | Type | Description |
- * | --- | --- | --- |
- * | `instant` | `string` | UTC instant, ISO 8601 ending in `Z` (e.g. `2024-07-15T16:00:00Z`). Orders events globally. |
- * | `offset` | `string` | UTC offset in force where the event happened, `±HH:MM` (or `±HH:MM:SS` for a pre-1972 zone that did not run on a whole minute). Renders the event as the human on the ground saw it. |
- * | `timeZone` | `string \| undefined` | IANA zone identifier, when one is known. Absent from most feeds, so absent from most pairs. |
- *
- * Neither `instant` nor `offset` derives from the other, which is why both are stored. It is
- * the shape GS1 EPCIS 2.0 (`eventTime` + a required `eventTimeZoneOffset`), UN/EDIFACT DTM
- * (qualifier `303`/`304`) and DICOM (`DT` + `&ZZXX`) all exchange.
- *
- * @example
- * import { OffsetInstant } from "@northguild/gmt/instant";
- * const pair: OffsetInstant = {
- *   instant: "2024-07-15T16:00:00Z",
- *   offset: "-04:00",
- *   timeZone: "America/New_York",
- * };
- */
 /** A leading RFC 9557 time zone annotation: `[zone]` or `[!zone]`, with no `=`. */
-const timeZoneAnnotation = /^\[!?[^\]=]+\]/;
+const timeZoneAnnotation = new RegExp(`^${TIME_ZONE_ANNOTATION}`);
 /**
  * Split an ISO 8601 instant string into the instant-plus-offset pair the world exchanges.
  *

package/dist/intermodal/calculate/billingTimeline.d.ts

@@ -0,0 +1,94 @@
+/** The dates a billing timeline is counted from: the anchor, and the invoice and request once they exist. */
+export interface BillingDates {
+    /**
+     * The date the issue window is counted from, as an ISO date, such as the date the charge was
+     * last incurred or, for a re-bill, the issuance date of the invoice received.
+     */
+    anchorOn: string;
+    /** The date the invoice was issued, once it has been. */
+    invoiceIssuedOn?: string;
+    /** The date the dispute request was received, once it has been. */
+    requestReceivedOn?: string;
+}
+/** The three windows the caller supplies, in calendar days, none defaulted, and an optional agreed resolution date. */
+export interface BillingWindows {
+    /** Days from `anchorOn` within which the invoice must be issued. */
+    issueDays: number;
+    /** Days from `invoiceIssuedOn` within which a dispute may be raised. */
+    disputeDays: number;
+    /** Days from `requestReceivedOn` within which the dispute must be resolved. */
+    resolutionDays: number;
+    /** A resolution date the parties agreed instead; it replaces the computed one. */
+    agreedResolutionOn?: string;
+}
+/** What `billingTimeline` returns: each deadline as an ISO date, and each comparison once its date exists. */
+export interface BillingDeadlines {
+    /** `anchorOn + issueDays`. */
+    invoiceDeadline: string;
+    /** Whether `invoiceIssuedOn` is on or before `invoiceDeadline`; `null` until an invoice date exists. */
+    issuedByDeadline: boolean | null;
+    /** `invoiceIssuedOn + disputeDays`; `null` until an invoice date exists. */
+    disputeDeadline: string | null;
+    /** Whether `requestReceivedOn` is on or before `disputeDeadline`; `null` until a request date exists. */
+    requestedByDeadline: boolean | null;
+    /** `requestReceivedOn + resolutionDays`, or `agreedResolutionOn`; `null` until a request date exists. */
+    resolutionDeadline: string | null;
+}
+/**
+ * Lay out the deadline chain around a demurrage or detention invoice: the last date it may be
+ * issued, the last date it may be disputed, and the last date the dispute must be resolved.
+ *
+ * A billing regime or service contract can set up to three windows around an invoice: one to
+ * issue it, one to dispute it, and one to resolve the dispute. The number of days in each is the
+ * caller's fact; GMT carries none of them. The arithmetic is this 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.
+ *
+ * - **Day zero is the anchor and the deadline is `anchor + days`** on the ISO 8601 calendar
+ *   (`Temporal.PlainDate.add`); a date is "by the deadline" when
+ *   `Temporal.PlainDate.compare(date, deadline) <= 0`. That is this function's stated contract,
+ *   not a reading of any rule; a regime that counts differently passes a different number.
+ * - **Deadlines are dates, never instants.** Reduce an instant to the billing party's local date
+ *   first with `convertUtcToPlainDate(instant, { timeZone })`; this function does not guess a
+ *   zone. `anchorOn` is whatever date the caller counts from, such as the last charged date
+ *   (`chargeableDays(...).chargedDates.at(-1)`) or, for a party re-billing a charge it was
+ *   itself billed, the issuance date of the invoice it received.
+ * - **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 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`. An explicit `undefined` is an omission; any other value must be a
+ *   valid ISO date.
+ * - **The booleans compare dates and say nothing else.** Whether a charge is payable, whether a
+ *   dispute must be heard, and any consequence are the consumer's. GMT computes dates, not
+ *   liability.
+ * - **`agreedResolutionOn` replaces the computed `resolutionDeadline`** when given. It must be a
+ *   valid date on or after `requestReceivedOn`, else `null`; it is validated even when no
+ *   request exists, but cannot act without one.
+ * - **A request cannot precede the invoice it disputes.** `requestReceivedOn` without
+ *   `invoiceIssuedOn`, or earlier than it, is a data error and returns `null`. An invoice earlier
+ *   than the anchor is allowed: an invoice may be issued while charges still accrue.
+ * - Every emitted date is canonical bare ISO (`Temporal.PlainDate#toString()`), so an input
+ *   annotation such as `[u-ca=iso8601]` does not reach the output, as `addDate` behaves.
+ * - Returns `null` when `dates` or `windows` is not an object, `anchorOn` or a given optional
+ *   date is not a valid ISO date, a window is missing or not a safe integer of at least `0`, a
+ *   request exists without an invoice or before it, `agreedResolutionOn` is before the request,
+ *   or a deadline would leave Temporal's range.
+ *
+ * @param dates { anchorOn: string, invoiceIssuedOn?: string, requestReceivedOn?: string } ISO dates
+ * @param windows { issueDays: number, disputeDays: number, resolutionDays: number, agreedResolutionOn?: string } calendar-day windows, none defaulted
+ * @returns { invoiceDeadline, issuedByDeadline, disputeDeadline, requestedByDeadline, resolutionDeadline }, or null on invalid input
+ *
+ * @example billingTimeline({ anchorOn: "2026-03-01" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: null, disputeDeadline: null, requestedByDeadline: null, resolutionDeadline: null } (no invoice yet: a forecast)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-31" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-30", requestedByDeadline: null, resolutionDeadline: null } (day 30 is the last day by the deadline)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-04-01" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: false, disputeDeadline: "2026-05-01", requestedByDeadline: null, resolutionDeadline: null } (day 31)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-20", requestReceivedOn: "2026-04-19" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-19", requestedByDeadline: true, resolutionDeadline: "2026-05-19" }
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-20", requestReceivedOn: "2026-04-20" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30, agreedResolutionOn: "2026-06-01" }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-19", requestedByDeadline: false, resolutionDeadline: "2026-06-01" } (an agreed date replaces the computed one)
+ * @example billingTimeline({ anchorOn: "2026-03-10", invoiceIssuedOn: "2026-04-05" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-04-09", issuedByDeadline: true, disputeDeadline: "2026-05-05", requestedByDeadline: null, resolutionDeadline: null } (a re-bill anchored on the invoice it received, not on the charge)
+ * @example 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" } (a service contract's own windows)
+ * @example billingTimeline({ anchorOn: "2028-01-30" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2028-02-29", issuedByDeadline: null, disputeDeadline: null, requestedByDeadline: null, resolutionDeadline: null } (calendar days across a leap day)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-31" }, { disputeDays: 30, resolutionDays: 30 }) // null (issueDays has no default)
+ * @example billingTimeline({ anchorOn: "2026-03-01", requestReceivedOn: "2026-04-19" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // null (a request cannot precede the invoice it disputes)
+ */
+export declare function billingTimeline(dates: BillingDates, windows: BillingWindows): BillingDeadlines | null;