@northguild/gmt 1.19.0 → 1.20.0

package/skills/gmt-intermodal/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: gmt-intermodal
+description: >
+  Intermodal container and freight timing in @northguild/gmt/intermodal — free
+  time and demurrage (freeTimeExpiry, chargeableDays, demurrageClock), billing
+  deadlines (billingTimeline), bill of lading dates and multimodalETA
+  (bolTimestamp), and EDI and event timestamps: UN/EDIFACT DTM, X12 date, time
+  and time code readers and writers (parseEdifact*, parseX12*,
+  parseX12DateAndTime, x12TimeCodeOffset), EPCIS events (parseEpcisEvent). Every
+  tariff term is the caller's. Reads the docs site (llms.txt) and the installed
+  package's JSDoc; a routing pointer.
+sources:
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/intermodal-bill-of-lading-and-eta.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/intermodal-billing-deadlines.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/intermodal-edi-timestamps.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/intermodal-free-time-and-demurrage.mdx'
+  - 'northguild/gmt:packages/gmt/src/intermodal/calculate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/intermodal/format/index.ts'
+  - 'northguild/gmt:packages/gmt/src/intermodal/parse/index.ts'
+  - 'northguild/gmt:packages/gmt/src/intermodal/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/types/edi.ts'
+  - 'northguild/gmt:packages/gmt/src/types/epcis.ts'
+  - 'northguild/gmt:packages/gmt/src/types/two-digit-year.ts'
+metadata:
+  type: core
+  library: '@northguild/gmt'
+  library_version: '1.20.0'
+---
+
+# GMT Intermodal
+
+Use this skill when the task is container free time and demurrage, billing
+deadlines, bill of lading dates, a multimodal ETA, or reading and writing EDI
+and EPCIS timestamps. The time zone rules it builds on are in the
+`gmt-timezone` skill; leg timing is in the `gmt-transport` skill.
+
+## When to load
+
+- The user is working out when a container's free time ends, how many days of
+  demurrage or detention are chargeable and for which dates, or which events a
+  charge's clock runs between.
+- The user is reading or writing a UN/EDIFACT `DTM` value, an X12 date, time,
+  time code or date time period, or a GS1 EPCIS event time, and must know
+  whether its offset was stated.
+
+## Core rules
+
+1. **Free time is counted in the terminal's local days; the start day and the
+    basis are tariff terms, never defaults.**
+    `freeTimeExpiry(clockStart, freeDays, { basis, timeZone, firstDay, calendar? })`
+    returns `{ freeTimeStart, lastFreeDay, expiresAt }`: local dates in
+    `timeZone`, and the first instant of the day after the last free day.
+    `firstDay` (`"eventDay"` | `"nextDay"`) has no default because the two
+    differ by a day of charges; `basis: "working"` needs a `BusinessCalendar`
+    and returns `null` without one. `chargeableDays(clockStart, clockEnd,
+    freeDays, options)` also needs `chargeBasis` (no default): 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, and some
+    tariffs charge working days only. It counts the days on or after
+    `expiresAt` the half-open dwell touched, lists them as `chargedDates`, and
+    splits them into `tiers` bands; `freeDays: 0` is allowed there.
+    `demurrageClock(events, scope, { direction, startEvent? })` selects the
+    events per leg: import demurrage and storage run discharge (or
+    availability) to gate-out, detention gate-out to empty return; export
+    demurrage gate-in to loaded, detention empty release to gate-in; `combined`
+    runs both as one period. No standard fixes how these days are counted;
+    every term is the tariff's.
+2. **Billing deadlines are dates counted from an anchor, and every window is
+    the caller's.** `billingTimeline({ anchorOn, invoiceIssuedOn?,
+    requestReceivedOn? }, { issueDays, disputeDays, resolutionDays,
+    agreedResolutionOn? })` returns `{ invoiceDeadline, issuedByDeadline,
+    disputeDeadline, requestedByDeadline, resolutionDeadline }`. Day zero is
+    the anchor and each deadline is `date + days` on the ISO calendar; a date
+    is by the deadline when it is on or before it. No window has a default (a
+    missing one returns `null`); fields whose input does not exist yet are
+    `null`, so an anchor alone is a forecast. The anchor is whatever date the
+    caller counts from: the last charged date
+    (`chargedDates.at(-1)`), or for a re-bill the issuance date of the invoice
+    received. Reduce an instant to the billing party's local date first with
+    `convertUtcToPlainDate(instant, { timeZone })`. A request before its
+    invoice, or an agreed date before the request, returns `null`. GMT
+    computes dates, not liability.
+3. **A B/L date is a local date; a multimodal ETA keeps transit and dwell
+    apart.** `bolTimestamp(value, event, { timeZone })` returns the
+    `YYYY-MM-DD` date on the local clock in `timeZone` at the instant `value`:
+    DCSA Bill of Lading 3.0 types `issueDate`, `receivedForShipmentDate` and
+    `shippedOnBoardDate` as dates with no time or offset. `event` is
+    `"issue" | "received" | "shippedOnBoard"`, one per DCSA date field; all
+    three render the same way and anything else is `""`. `timeZone` is
+    required (no UTC default): the place of issue for `issue`, the loading
+    terminal for `received` and `shippedOnBoard`. 21:00 in New York
+    is 01:00Z the next day, so the UTC date is wrong. Only the instant is read;
+    a zoneless value is `""`. `multimodalETA(legs, { startTimeZone? })` takes
+    `scheduleDelivery`'s `Leg[]` and returns `{ eta, totalLegs, totalTransit,
+    totalDwell }`: transit is the legs' durations added up, dwell the time
+    actually spent at handoffs (a wait for a scheduled departure included; the
+    last leg's `dwellAfter` excluded), both with hours as the largest unit, and
+    they sum to the elapsed time. Every `scheduleDelivery` rule applies, so a
+    missed connection is `null`. An empty array is `{ eta: "", totalLegs: 0,
+    totalTransit: "PT0S", totalDwell: "PT0S" }`. Dwell is never estimated.
+4. **An EDI timestamp is read by the function for its kind of value, and
+    nothing the code does not state is guessed.** Each kind has a `parse…`,
+    `format…` and `isValid…` function named for it (`parseEdifactDate`,
+    `formatEdifactDate`, `isValidEdifactDate`), and `format` is typed to that
+    kind's codes. UN/EDIFACT `DTM` (value 2380 against format code 2379):
+    `EdifactDate` (`102`), `EdifactTime` (`401`, `402`), `EdifactDateTime`
+    (`203`, `204`), `EdifactOffsetDateTime` (`205`, `208`, `303`, `304`),
+    `EdifactDatePeriod` (`718`), `EdifactDateTimePeriod` (`719`). X12 (element
+    1251 against qualifier 1250, in `DTP` and `DTM-05`/`06`): `X12Date` (`D8`,
+    `DB`), `X12Time` (`TM`, `TS`), `X12DateTime` (`DT`, `RTS`), `X12DateRange`
+    (`RD8`, `RD`), `X12DateTimeRange` (`RDT`, `DTS`). `parseX12Time(value)`
+    with no `format` reads element 337, tenths and hundredths included
+    (`"14300012"` is `"14:30:00.12"`), and `formatX12TimeElement(value, form)`
+    writes it in the mask named: `HHMM`, `HHMMSS`, `HHMMSSD` or `HHMMSSDD`
+    (`"14:30:00"` under `HHMMSSDD` is `"14300000"`). A parser returns one value:
+    `"2024-06-15"`, `"14:30:00"`, `"2024-06-15T14:30:00"`,
+    `"2024-06-15T14:30:00+02:00"` (the string `toOffsetInstant` reads), or
+    `{ start, end }` for a period or range. The sentinel is `""`, or `null`
+    for a period, a range, a zone or a classifier. A period formatter takes
+    `(start, end, format)`. No EDI function takes options. X12 freight is
+    three calls: `parseX12DateAndTime("20240615", "1430")` is
+    `"2024-06-15T14:30:00"` (elements 373 and 337 of `AT7`, `G62` or `DTM`,
+    both required), `x12TimeCodeOffset("20")` is `"-05:00"`, and
+    `resolveLocal(local, offset)` is `"2024-06-15T19:30:00Z"`. For a code
+    held as a plain string, `classifyEdifactDtmFormat`,
+    `classifyX12DateTimePeriodFormat` and `classifyX12TimeCode` return
+    `{ kind, format }` or `{ kind, timeCode }`, or `null` for a code no
+    function reads; testing `kind` narrows the code with no cast.
+    `parseEpcisEvent({ eventTime, eventTimeZoneOffset })` returns
+    `{ instant, offset, local }`; both fields are required and need not
+    agree. Five no-guess rules. (a) An offsetless value never becomes UTC:
+    `203`, `204`, `DT`, `RTS` and `parseX12DateAndTime` return a local
+    date-time; pass it and an IANA zone to `resolveLocal`. (b) A named X12
+    time code is a zone name, not an offset: `x12TimeCodeZone("ES")` is
+    `{ zone: "Eastern", daylight: false }` and `ET` has `daylight: null`,
+    while `x12TimeCodeOffset` reads `01`–`29`, `UT` and `GM`, and `13`–`24`
+    count down (`13` is `-12:00`). Each returns its sentinel for the other's
+    codes. (c) The `ZZZ` of `303` and `304` is an offset only: `+02`, `UTC`
+    and `GMT` are read, and letters such as `CET` return `""`. (d) A
+    two-digit year is not read by any EDI function: `101`, `201`, `202`,
+    `206`, `207`, `301`, `302`, `713`, `717`, `D6`, `TT`, `TR`, `RD6` and
+    `TU`. Read one with `parseDateWithPattern` or `parseDateTimeWithPattern`,
+    a `yy` pattern and `{ yearWindow }`: a start year such as `2000` (a fixed
+    window, for stored data) or `"rolling"` (50 years before the current UTC
+    year to 49 after). Without `yearWindow` a `yy` pattern returns `""`. (e)
+    `209`, `404`, `406`, `TC`, `EH`, `DDT`, `DTD`, `RTM` and `UN` are not
+    read: none states one date, time or date-time. A UN/EDIFACT period has no
+    hyphen (`2024061520240620` under `718`) and an X12 range has one
+    (`20240615-20240620` under `RD8`); a reversed one returns the sentinel.
+    Pass a UN/EDIFACT parser the unescaped value (`+02`, not `?+02`). A
+    formatter cuts seconds and fractions to its mask and never rounds.
+    It writes `ZZZ` as `±HH`, and `+05:30` under `303` or `304` returns `""`:
+    use `205` or `208`. Each value validator is true exactly when its parser
+    returns a value (`isValidX12DateAndTime(date, time)` for the freight
+    pair), and `isValidEdifactDtmFormat`, `isValidX12DateTimePeriodFormat`
+    and `isValidX12TimeCode` check a code alone. `isValidEpcisEvent` is
+    `isValidEpcisEventTime` and `isValidEpcisTimeZoneOffset` together: the
+    `epcisEventTime` regex matches `2024-02-30`, the validator does not.
+5. **Read the docs site.** This skill is a routing pointer. The map of the
+   docs is `https://northguild.dev/gmt/llms.txt`, and each page
+   has a `.md` twin that holds its text. The JSDoc ships in the installed
+   package: `node_modules/@northguild/gmt/dist/**/*.d.ts`.
+
+## Key functions
+
+- **Free time and demurrage**: `freeTimeExpiry`, `chargeableDays`,
+  `demurrageClock`
+- **Billing deadlines**: `billingTimeline`
+- **Bill of lading dates and multimodal ETA**: `bolTimestamp`, `multimodalETA`
+- **EDI and event timestamps**: `parseEdifactDate`, `parseEdifactTime`,
+  `parseEdifactDateTime`, `parseEdifactOffsetDateTime`,
+  `parseEdifactDatePeriod`, `parseEdifactDateTimePeriod`, `parseX12Date`,
+  `parseX12Time`, `parseX12DateTime`, `parseX12DateRange`,
+  `parseX12DateTimeRange`, `parseX12DateAndTime`, `x12TimeCodeOffset`,
+  `x12TimeCodeZone`, `classifyEdifactDtmFormat`,
+  `classifyX12DateTimePeriodFormat`, `classifyX12TimeCode`,
+  `parseEpcisEvent`; a `format…` and an `isValid…` for each `parseEdifact…`
+  kind, for `X12Date`, `X12Time`, `X12DateTime`, `X12DateRange` and
+  `X12DateTimeRange`, and for `EpcisEvent`; `formatX12TimeElement`,
+  `isValidX12DateAndTime`, `isValidEpcisEventTime`,
+  `isValidEpcisTimeZoneOffset`, `isValidEdifactDtmFormat`,
+  `isValidX12DateTimePeriodFormat`, `isValidX12TimeCode`
+
+## References
+
+- [intermodal reference](https://northguild.dev/gmt/reference/intermodal/)
+- [Docs map for agents (llms.txt)](https://northguild.dev/gmt/llms.txt)
+- [GMT Timezone skill](../gmt-timezone/SKILL.md)
+- [GMT Transport skill](../gmt-transport/SKILL.md)

package/skills/gmt-timezone/SKILL.md

@@ -3,28 +3,23 @@ name: gmt-timezone
 description: >
   Timezone-aware operations — zoned now, zoned formatting, plain↔zoned↔UTC↔Unix
   conversion, DST disambiguation, toOffsetInstant, classifyLocal/resolveLocal,
-  real boundaries (startOfZoned/endOfZoned/startOfUnix/endOfUnix), hours in a
-  local day, floorToZone/bucketRange, calendar-annotated strings, transport legs
-  (transitTime, etaAtZone, dwellTime, crossingTime, scheduleDelivery), cut-offs
-  (cutoffAt, cutoffSchedule, isPastCutoff, timeToCutoff), punctuality
-  (scheduleDeviation, classifyPunctuality, punctualityRate, bestAvailable,
-  estimateDrift over PLN/EST/REQ/ACT, nextDeparture), free time (freeTimeExpiry,
-  chargeableDays, demurrageClock), billingTimeline, bolTimestamp, multimodalETA,
-  EDI timestamps (parseEdifactDateTime, parseX12DateAndTime, x12TimeCodeOffset,
-  parseEpcisEvent, classify*/format*/isValid*), operating hours
+  classifyStoredZoned (why a stored offset+zone string no longer resolves), real
+  boundaries (startOfZoned/endOfZoned/startOfUnix/endOfUnix), hours in a local
+  day, floorToZone/bucketRange, calendar-annotated strings, operating hours
   (OperatingSchedule, recurringWindows, operatingIntervals, isOpenAt,
   nextOpenAt, nextCloseAt, operatingTimeBetween, addOperatingTime), and daylight
-  time (isInDaylightSaving, hasDaylightSaving).
+  time (isInDaylightSaving, hasDaylightSaving). Transport legs, intermodal free
+  time and EDI timestamps are in gmt-transport and gmt-intermodal.
 sources:
   - 'northguild/gmt:apps/dox/src/content/docs/guides/zoned-date-operations/*.mdx'
   - 'northguild/gmt:apps/dox/src/content/docs/guides/concepts/dst-disambiguation.md'
   - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/operating-hours.mdx'
-  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/*.mdx'
   - 'northguild/gmt:packages/gmt/src/zoned/get/index.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/format/index.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/compare/index.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/convert/index.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/classify/index.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/calculate/addZoned.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/calculate/startOfZoned.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/calculate/roundZoned.ts'
@@ -39,21 +34,10 @@ sources:
   - 'northguild/gmt:packages/gmt/src/calendar/validate/index.ts'
   - 'northguild/gmt:packages/gmt/src/calendar/hours/index.ts'
   - 'northguild/gmt:packages/gmt/src/types/operating-schedule.ts'
-  - 'northguild/gmt:packages/gmt/src/types/transport-timestamps.ts'
-  - 'northguild/gmt:packages/gmt/src/transport/calculate/index.ts'
-  - 'northguild/gmt:packages/gmt/src/transport/compare/index.ts'
-  - 'northguild/gmt:packages/gmt/src/transport/convert/index.ts'
-  - 'northguild/gmt:packages/gmt/src/intermodal/calculate/index.ts'
-  - 'northguild/gmt:packages/gmt/src/intermodal/format/index.ts'
-  - 'northguild/gmt:packages/gmt/src/intermodal/parse/index.ts'
-  - 'northguild/gmt:packages/gmt/src/intermodal/validate/index.ts'
-  - 'northguild/gmt:packages/gmt/src/types/edi.ts'
-  - 'northguild/gmt:packages/gmt/src/types/epcis.ts'
-  - 'northguild/gmt:packages/gmt/src/types/two-digit-year.ts'
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.19.0'
+  library_version: '1.20.0'
 ---
 
 # GMT Timezone
@@ -63,7 +47,7 @@ converting between time zones, or doing arithmetic that must respect DST.
 
 ## When to load
 
-- The user needs the current time in a specific timezone (`"America/New_York"`).
+- The user needs the current time in a specific timezone (`"Asia/Tokyo"`).
 - The user wants to format a datetime with its zone attached.
 - The user needs to convert a plain datetime to a zoned instant, or between
   timezones, or between UTC and Unix epochs.
@@ -73,15 +57,6 @@ converting between time zones, or doing arithmetic that must respect DST.
 - The user needs the start or end of a local hour, day, week, month or quarter.
 - The user is grouping or aggregating UTC timestamps by local day, hour, week or
   month — an observability rollup, a chargeable-days count.
-- The user is adding a leg's transit time to a departure, showing an arrival in
-  the zone where it lands, or counting how long cargo, a vessel or a patient sat
-  somewhere in local calendar days.
-- The user is working out when a container's free time ends, how many days of
-  demurrage or detention are chargeable and for which dates, or which events a
-  charge's clock runs between.
-- The user is reading or writing a UN/EDIFACT `DTM` value, an X12 date, time,
-  time code or date time period, or a GS1 EPCIS event time, and must know
-  whether its offset was stated.
 - The user is asking whether a gate, desk, office or venue is open at an
   instant, when it next opens or closes, how many working hours passed between
   two instants, or when an SLA measured in open hours falls due — or is
@@ -89,8 +64,8 @@ converting between time zones, or doing arithmetic that must respect DST.
 
 ## Core rules
 
-1. **Use IANA timezone ids, not raw offsets.** `"2024-03-15T14:30:45[America/New_York]"`
-   is correct; bare `"-05:00"` loses the zone and can't observe DST rules.
+1. **Use IANA timezone ids, not raw offsets.** `"2024-03-15T14:30:45[Australia/Sydney]"`
+   is correct; bare `"+11:00"` loses the zone and can't observe DST rules.
 2. **DST disambiguation.** `convertPlainDateTimeToZoned`, `addZoned` and
    `setZoned` accept `disambiguation` (`"compatible"` | `"earlier"` |
    `"later"` | `"reject"`) for gap/overlap resolution. On `addZoned`,
@@ -133,6 +108,15 @@ converting between time zones, or doing arithmetic that must respect DST.
    EDIFACT DTM and DICOM exchange. Its `±HH:MM[:SS]` offset is a valid `timeZone`
    for `resolveLocal` and every function whose result has no zone in it. One
    that returns a zoned string or formats with `Intl` takes none with seconds.
+   **A stored string can stop agreeing with its zone.**
+   `classifyStoredZoned("2016-12-01T09:00:00+02:00[Europe/Istanbul]")` returns
+   `kind: "offsetMismatch"` with `storedOffset`, `zoneOffset` and the instant each
+   reading gives. The other kinds are `valid`, `validInOverlap`, `ambiguous` and
+   `nonexistent`; every one carries `atStoredOffset`, and it returns `null` for a
+   string without both an offset and a zone. It picks no reading: your policy
+   chooses among those returned. The answer follows the host's time zone rules, so
+   the same string can differ between hosts. Import it from
+   `@northguild/gmt/zoned/classify`.
 7. **Bucket in the zone, not in UTC.** `floorToZone(instant, unit, zone)` and
    `bucketRange(start, end, unit, zone)` floor on the zone's own calendar
    boundaries. Flooring a UTC instant to a UTC day and calling it a local day is
@@ -155,7 +139,7 @@ converting between time zones, or doing arithmetic that must respect DST.
    local day.
 10. **Calendar annotations.** A calendar-annotated zoned string is RFC 9557,
     `Temporal.ZonedDateTime#toString()`: ISO digits, then `[timeZone]`, then
-    `[u-ca=<id>]` (`"2024-10-03T14:30:45-04:00[America/New_York][u-ca=hebrew]"`).
+    `[u-ca=<id>]` (`"2024-10-03T14:30:45+03:00[Asia/Jerusalem][u-ca=hebrew]"`).
     A calendar annotation before the zone is rejected. Only `addZoned`, `subtractZoned`,
     `diffZoned`, `diffZonedAsDuration`, `convertZonedToCalendar`,
     `isValidCalendarZonedDateTime` and `zoned/interval/*` (including
@@ -189,198 +173,15 @@ converting between time zones, or doing arithmetic that must respect DST.
     fall-back into the previous date counts that date.
 13. **Zone names and leap seconds.** Every IANA name is a zone, including
     single-component links (`Japan`, `Zulu`, `EST5EDT`), in any case.
-    `toOffsetInstant` returns IANA casing (`"america/new_york"` gives
-    `"America/New_York"`). `:60` is invalid in every spelling (`T`, `t`, space,
+    `toOffsetInstant` returns IANA casing (`"asia/kolkata"` gives
+    `"Asia/Kolkata"`). `:60` is invalid in every spelling (`T`, `t`, space,
     basic format) and every zoned function returns its sentinel for it rather
-    than reading `:59`.
+    than reading `:59`; only `timescale/` and `gnss/` accept a listed one (for `gnss/`, see the `gmt-gnss` skill).
 14. **A zoned value formats in its own zone.** `formatZonedDateTime`,
     `formatZonedRange` and `formatZonedToParts` return `""`/`[]` for a
     `timeZone` option. To show an instant in another zone, use
     `formatUtc(convertZonedToUtc(value), locale, { timeZone })`.
-15. **Transport legs are exact time; dwell is counted in local days.**
-    `transitTime(departure, duration)` adds hours, minutes and seconds as
-    elapsed time (`P1D` is 24 exact hours) in the departure's own zone, so a leg
-    across a DST transition lands at the wall time the vehicle really arrives;
-    years, months and weeks return `""`, and a bracketed zone that contradicts
-    its offset is rejected rather than reinterpreted. `etaAtZone(instant, zone)`
-    renders a moment in the zone the caller names — no disambiguation arises,
-    the offset in the result tells the two passes of a fall-back hour apart, and
-    GMT never resolves a port, airport or station code to a zone.
-    `dwellTime(entry, exit, targetZone?)` returns `{ duration, enter, exit,
-    calendarDays }`; `calendarDays` is the number of distinct local dates the
-    half-open `[entry, exit)` touches, walked across the zone's real transitions
-    (a skipped date is not counted, a re-entered one only once), and is the
-    library's one "local days crossed" count.
-    Bare instants with no `targetZone` return `null`: an offset is not a place.
-    `crossingTime(entry, exit, targetZone)` returns `{ duration, enter, exit }`
-    with no day count (a crossing that needs one is a dwell); `targetZone` is
-    required and always the rendering zone — a bracket on the input never
-    supplies it.
-    `scheduleDelivery(legs, { startTimeZone? })` chains legs into `{ eta,
-    legTimes }`: each leg leaves at its explicit `departure` or at the previous
-    arrival plus that leg's `dwellAfter`, the minimum connect time. A scheduled
-    departure earlier than that is a missed connection and returns `null`
-    (equal passes). A departure is exact (instant or zoned string) or a
-    zoneless wall time: on the first leg it is read in `startTimeZone`, on a
-    later leg in the previous leg's `timeZone` (where that leg leaves from),
-    both with `"compatible"` resolution (ambiguous → earlier, skipped →
-    later). On a later leg, a repeated hour instead takes the earliest pass
-    at or after the previous arrival plus its dwell. A
-    negative leg `duration` is `null`; the last leg's `dwellAfter` is echoed,
-    never added. `mode`, `origin` and `destination` are opaque tags echoed on
-    each `LegTime`. An empty array returns `{ eta: "", legTimes: [] }`.
-16. **Cut-offs count back from the caller's event.**
-    `cutoffAt(anchor, offset, { timeZone, atLocalTime?, calendar?, roll? })`
-    takes an offset off the anchor (loading, departure or arrival are
-    different instants; it never guesses which). With `atLocalTime` the
-    offset's exact part comes off the anchor's instant first, its calendar
-    part off the local date, and the cut-off is that time of day: `P2D` at
-    `"17:00"` is 17:00 two days before, not 48 hours. Without it the offset
-    is `ZonedDateTime#subtract` (`P2D` keeps the wall clock, `PT96H` is 96
-    exact hours). `calendar` and `roll` go together or not at all — there is
-    no default roll, as in `rollDate`; either alone is `""`. A repeated hour
-    takes the first pass (RFC 5545 §3.3.5); a skipped hour is `""`. It does
-    not check that the cut-off is before the anchor.
-    `cutoffSchedule(anchor, [{ name, offset, atLocalTime? }], options)`
-    sorts the stack by instant and returns `[]` if any entry fails.
-    `isPastCutoff(now, cutoff)` is `true` from the cut-off instant on;
-    `timeToCutoff(now, cutoff)` is exact hours, `PT0S` at it, negative after.
-17. **Planned versus actual is exact time under the caller's tolerance.**
-    `scheduleDeviation(planned, actual)` is `actual − planned` in exact hours
-    (`"PT14M"` late, `"-PT5M"` early; a fall-back delay is `PT1H`, never
-    `PT0S`). `classifyPunctuality(planned, actual, { late, early? })` returns
-    `"early" | "onTime" | "late"`, or `null` on invalid input: both edges are
-    outside (exactly `late` is late), and without `early` every early arrival
-    is on time. There is no default tolerance; tolerances are exact durations
-    (a day is 24 hours; years, months, weeks or negative return `null`).
-    `punctualityRate(pairs, tolerance)` returns `{ onTime, total, rate }`,
-    judging every pair under a tolerance read once; an empty list or any
-    invalid pair is `null`. A `TimestampEvent` is `{ classifier: "PLN" |
-    "EST" | "REQ" | "ACT", at, recordedAt }` (DCSA vocabulary).
-    `bestAvailable(events)` returns `{ at, classifier }`: `ACT` whenever one
-    exists, else `PLN`, else `REQ`, else `EST`, newest `recordedAt` within the
-    class — never an `EST` shown as an actual. `estimateDrift(events, {
-    tolerance? })` reports first-to-last `EST` drift, `revisions` and
-    `exceedsTolerance` (strictly greater, either direction; `null` without a
-    tolerance), and is `null` with fewer than two `EST`s.
-    `nextDeparture(after, timetable, { minimumConnection? })` returns the
-    first departure at or after `after + minimumConnection`: a list entry
-    echoed as written (ready for `scheduleDelivery`'s `departure`), or for
-    `{ headway, from, to }` (a GTFS `frequencies.txt` row) `from + k × headway`
-    in the half-open `[from, to)`, written the way `from` was. Every moment
-    must carry its offset; a wall time without one is `""`.
-18. **Free time is counted in the terminal's local days; the start day and the
-    basis are tariff terms, never defaults.**
-    `freeTimeExpiry(clockStart, freeDays, { basis, timeZone, firstDay, calendar? })`
-    returns `{ freeTimeStart, lastFreeDay, expiresAt }`: local dates in
-    `timeZone`, and the first instant of the day after the last free day.
-    `firstDay` (`"eventDay"` | `"nextDay"`) has no default because the two
-    differ by a day of charges; `basis: "working"` needs a `BusinessCalendar`
-    and returns `null` without one. `chargeableDays(clockStart, clockEnd,
-    freeDays, options)` also needs `chargeBasis` (no default): 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, and some
-    tariffs charge working days only. It counts the days on or after
-    `expiresAt` the half-open dwell touched, lists them as `chargedDates`, and
-    splits them into `tiers` bands; `freeDays: 0` is allowed there.
-    `demurrageClock(events, scope, { direction, startEvent? })` selects the
-    events per leg: import demurrage and storage run discharge (or
-    availability) to gate-out, detention gate-out to empty return; export
-    demurrage gate-in to loaded, detention empty release to gate-in; `combined`
-    runs both as one period. No standard fixes how these days are counted;
-    every term is the tariff's.
-19. **Billing deadlines are dates counted from an anchor, and every window is
-    the caller's.** `billingTimeline({ anchorOn, invoiceIssuedOn?,
-    requestReceivedOn? }, { issueDays, disputeDays, resolutionDays,
-    agreedResolutionOn? })` returns `{ invoiceDeadline, issuedByDeadline,
-    disputeDeadline, requestedByDeadline, resolutionDeadline }`. Day zero is
-    the anchor and each deadline is `date + days` on the ISO calendar; a date
-    is by the deadline when it is on or before it. No window has a default (a
-    missing one returns `null`); fields whose input does not exist yet are
-    `null`, so an anchor alone is a forecast. The anchor is whatever date the
-    caller counts from: the last charged date
-    (`chargedDates.at(-1)`), or for a re-bill the issuance date of the invoice
-    received. Reduce an instant to the billing party's local date first with
-    `convertUtcToPlainDate(instant, { timeZone })`. A request before its
-    invoice, or an agreed date before the request, returns `null`. GMT
-    computes dates, not liability.
-20. **A B/L date is a local date; a multimodal ETA keeps transit and dwell
-    apart.** `bolTimestamp(value, event, { timeZone })` returns the
-    `YYYY-MM-DD` date on the local clock in `timeZone` at the instant `value`:
-    DCSA Bill of Lading 3.0 types `issueDate`, `receivedForShipmentDate` and
-    `shippedOnBoardDate` as dates with no time or offset. `event` is
-    `"issue" | "received" | "shippedOnBoard"`, one per DCSA date field; all
-    three render the same way and anything else is `""`. `timeZone` is
-    required (no UTC default): the place of issue for `issue`, the loading
-    terminal for `received` and `shippedOnBoard`. 21:00 in New York
-    is 01:00Z the next day, so the UTC date is wrong. Only the instant is read;
-    a zoneless value is `""`. `multimodalETA(legs, { startTimeZone? })` takes
-    `scheduleDelivery`'s `Leg[]` and returns `{ eta, totalLegs, totalTransit,
-    totalDwell }`: transit is the legs' durations added up, dwell the time
-    actually spent at handoffs (a wait for a scheduled departure included; the
-    last leg's `dwellAfter` excluded), both with hours as the largest unit, and
-    they sum to the elapsed time. Every `scheduleDelivery` rule applies, so a
-    missed connection is `null`. An empty array is `{ eta: "", totalLegs: 0,
-    totalTransit: "PT0S", totalDwell: "PT0S" }`. Dwell is never estimated.
-21. **An EDI timestamp is read by the function for its kind of value, and
-    nothing the code does not state is guessed.** Each kind has a `parse…`,
-    `format…` and `isValid…` function named for it (`parseEdifactDate`,
-    `formatEdifactDate`, `isValidEdifactDate`), and `format` is typed to that
-    kind's codes. UN/EDIFACT `DTM` (value 2380 against format code 2379):
-    `EdifactDate` (`102`), `EdifactTime` (`401`, `402`), `EdifactDateTime`
-    (`203`, `204`), `EdifactOffsetDateTime` (`205`, `208`, `303`, `304`),
-    `EdifactDatePeriod` (`718`), `EdifactDateTimePeriod` (`719`). X12 (element
-    1251 against qualifier 1250, in `DTP` and `DTM-05`/`06`): `X12Date` (`D8`,
-    `DB`), `X12Time` (`TM`, `TS`), `X12DateTime` (`DT`, `RTS`), `X12DateRange`
-    (`RD8`, `RD`), `X12DateTimeRange` (`RDT`, `DTS`). `parseX12Time(value)`
-    with no `format` reads element 337, tenths and hundredths included
-    (`"14300012"` is `"14:30:00.12"`), and `formatX12TimeElement(value, form)`
-    writes it in the mask named: `HHMM`, `HHMMSS`, `HHMMSSD` or `HHMMSSDD`
-    (`"14:30:00"` under `HHMMSSDD` is `"14300000"`). A parser returns one value:
-    `"2024-06-15"`, `"14:30:00"`, `"2024-06-15T14:30:00"`,
-    `"2024-06-15T14:30:00+02:00"` (the string `toOffsetInstant` reads), or
-    `{ start, end }` for a period or range. The sentinel is `""`, or `null`
-    for a period, a range, a zone or a classifier. A period formatter takes
-    `(start, end, format)`. No EDI function takes options. X12 freight is
-    three calls: `parseX12DateAndTime("20240615", "1430")` is
-    `"2024-06-15T14:30:00"` (elements 373 and 337 of `AT7`, `G62` or `DTM`,
-    both required), `x12TimeCodeOffset("20")` is `"-05:00"`, and
-    `resolveLocal(local, offset)` is `"2024-06-15T19:30:00Z"`. For a code
-    held as a plain string, `classifyEdifactDtmFormat`,
-    `classifyX12DateTimePeriodFormat` and `classifyX12TimeCode` return
-    `{ kind, format }` or `{ kind, timeCode }`, or `null` for a code no
-    function reads; testing `kind` narrows the code with no cast.
-    `parseEpcisEvent({ eventTime, eventTimeZoneOffset })` returns
-    `{ instant, offset, local }`; both fields are required and need not
-    agree. Five no-guess rules. (a) An offsetless value never becomes UTC:
-    `203`, `204`, `DT`, `RTS` and `parseX12DateAndTime` return a local
-    date-time; pass it and an IANA zone to `resolveLocal`. (b) A named X12
-    time code is a zone name, not an offset: `x12TimeCodeZone("ES")` is
-    `{ zone: "Eastern", daylight: false }` and `ET` has `daylight: null`,
-    while `x12TimeCodeOffset` reads `01`–`29`, `UT` and `GM`, and `13`–`24`
-    count down (`13` is `-12:00`). Each returns its sentinel for the other's
-    codes. (c) The `ZZZ` of `303` and `304` is an offset only: `+02`, `UTC`
-    and `GMT` are read, and letters such as `CET` return `""`. (d) A
-    two-digit year is not read by any EDI function: `101`, `201`, `202`,
-    `206`, `207`, `301`, `302`, `713`, `717`, `D6`, `TT`, `TR`, `RD6` and
-    `TU`. Read one with `parseDateWithPattern` or `parseDateTimeWithPattern`,
-    a `yy` pattern and `{ yearWindow }`: a start year such as `2000` (a fixed
-    window, for stored data) or `"rolling"` (50 years before the current UTC
-    year to 49 after). Without `yearWindow` a `yy` pattern returns `""`. (e)
-    `209`, `404`, `406`, `TC`, `EH`, `DDT`, `DTD`, `RTM` and `UN` are not
-    read: none states one date, time or date-time. A UN/EDIFACT period has no
-    hyphen (`2024061520240620` under `718`) and an X12 range has one
-    (`20240615-20240620` under `RD8`); a reversed one returns the sentinel.
-    Pass a UN/EDIFACT parser the unescaped value (`+02`, not `?+02`). A
-    formatter cuts seconds and fractions to its mask and never rounds.
-    It writes `ZZZ` as `±HH`, and `+05:30` under `303` or `304` returns `""`:
-    use `205` or `208`. Each value validator is true exactly when its parser
-    returns a value (`isValidX12DateAndTime(date, time)` for the freight
-    pair), and `isValidEdifactDtmFormat`, `isValidX12DateTimePeriodFormat`
-    and `isValidX12TimeCode` check a code alone. `isValidEpcisEvent` is
-    `isValidEpcisEventTime` and `isValidEpcisTimeZoneOffset` together: the
-    `epcisEventTime` regex matches `2024-02-30`, the validator does not.
-22. **Operating hours are local windows resolved in the schedule's zone.** An
+15. **Operating hours are local windows resolved in the schedule's zone.** An
     `OperatingSchedule` is `{ timeZone, weekly, holidays?, overrides? }`:
     `weekly` maps ISO weekdays `1`–`7` to half-open `LocalWindow`s
     (`{ from: "09:00", to: "17:00" }`); a `to` at or before `from` wraps past
@@ -396,12 +197,11 @@ converting between time zones, or doing arithmetic that must respect DST.
     `addOperatingTime(start, "PT8H", schedule)` is the SLA deadline. Searches
     stop at `within` (default `"P1Y"`) and return `""` past it; `P1D` is not
     open time and returns `""`.
-23. **A zoned string names one instant in every reader.** Temporal writes a
+16. **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
     (`Africa/Monrovia` stood at −00:44:30 until 1972) is written `-00:45`.
     Every function that reads a moment (`toNanoseconds`, `spanNs`, `Interval`
-    endpoints, `floorToZone`, `getTimeZoneOffset`, `scheduleDeviation`,
-    `timeToCutoff`, `dwellTime`) reads an offset written to the minute as the
+    endpoints, `floorToZone`, `getTimeZoneOffset`, and the `transport/` functions that read one) reads an offset written to the minute as the
     bracketed zone's real offset when it is that offset rounded (TC39
     `ToTemporalZonedDateTime`, match-minutes):
     `1960-01-01T00:20:00-00:45[Africa/Monrovia]` is `01:04:30Z`. So a zoned
@@ -409,7 +209,7 @@ converting between time zones, or doing arithmetic that must respect DST.
     the written offset fixes the instant. A function that reads only the
     instant does not validate the bracket, and the bracket never supplies its
     rendering zone. A function that keeps the zone (`isValidZonedDateTime`,
-    `transitTime`, `toOffsetInstant`, every `zoned/` function, a zoned
+    `toOffsetInstant`, every `zoned/` function, a zoned
     `relativeTo`) rejects a bracket that contradicts the offset, and an offset
     written with seconds must be the zone's offset exactly:
     `-00:45:00[Africa/Monrovia]` is invalid, `-00:44:30[Africa/Monrovia]` is
@@ -418,7 +218,7 @@ converting between time zones, or doing arithmetic that must respect DST.
     (`1952-10-15T23:59:59-11:20[Pacific/Niue]`); write the offset with seconds
     to name the second. A zoned read refuses a local date of −271821-04-19,
     which an instant reader accepts; pass that instant in `Z` form.
-24. **Daylight time is read from the zone's clock changes.**
+17. **Daylight time is read from the zone's clock changes.**
     `isInDaylightSaving(zoned)` and `hasDaylightSaving(timeZone, { at })`
     apply one rule, GMT's own definition and not the tz database's daylight
     flag (no JavaScript API exposes it): daylight time runs from a forward
@@ -437,8 +237,8 @@ converting between time zones, or doing arithmetic that must respect DST.
     read the runtime's time zone data, so an answer can change when that data
     does. The JSDoc of `isInDaylightSaving` lists what the rule reads as
     standard time.
-25. **Read the docs site.** This skill is a routing pointer. The map of the
-    docs is `https://gmt-dox.northguild.workers.dev/llms.txt`, and each page
+18. **Read the docs site.** This skill is a routing pointer. The map of the
+    docs is `https://northguild.dev/gmt/llms.txt`, and each page
     has a `.md` twin that holds its text. The JSDoc ships in the installed
     package: `node_modules/@northguild/gmt/dist/**/*.d.ts`.
 
@@ -462,37 +262,14 @@ converting between time zones, or doing arithmetic that must respect DST.
   `getTimeZoneOffset`, `parseTimeZoneFromZoned`
 - **Offset-preserving instants**: `toOffsetInstant`, `fromOffsetInstant`,
   `isValidUtcOffset` (the pair's `±HH:MM[:SS]` offset; not `Z`, not `+0530`)
-- **Local-time resolution**: `classifyLocal`, `resolveLocal`
+- **Local-time resolution**: `classifyLocal`, `resolveLocal`,
+  `classifyStoredZoned`
 - **Zone-aware buckets**: `floorToZone`, `bucketRange`,
   `isValidZoneBucketUnit`
-- **Transport legs and dwell**: `transitTime`, `etaAtZone`, `dwellTime`,
-  `crossingTime`, `scheduleDelivery`
-- **Cut-offs and deadlines**: `cutoffAt`, `cutoffSchedule`, `isPastCutoff`,
-  `timeToCutoff`
-- **Punctuality and timestamp classes**: `scheduleDeviation`,
-  `classifyPunctuality`, `punctualityRate`, `bestAvailable`, `estimateDrift`,
-  `nextDeparture`
-- **Free time and demurrage**: `freeTimeExpiry`, `chargeableDays`,
-  `demurrageClock`
-- **Billing deadlines**: `billingTimeline`
-- **Bill of lading dates and multimodal ETA**: `bolTimestamp`, `multimodalETA`
-- **EDI and event timestamps**: `parseEdifactDate`, `parseEdifactTime`,
-  `parseEdifactDateTime`, `parseEdifactOffsetDateTime`,
-  `parseEdifactDatePeriod`, `parseEdifactDateTimePeriod`, `parseX12Date`,
-  `parseX12Time`, `parseX12DateTime`, `parseX12DateRange`,
-  `parseX12DateTimeRange`, `parseX12DateAndTime`, `x12TimeCodeOffset`,
-  `x12TimeCodeZone`, `classifyEdifactDtmFormat`,
-  `classifyX12DateTimePeriodFormat`, `classifyX12TimeCode`,
-  `parseEpcisEvent`; a `format…` and an `isValid…` for each `parseEdifact…`
-  kind, for `X12Date`, `X12Time`, `X12DateTime`, `X12DateRange` and
-  `X12DateTimeRange`, and for `EpcisEvent`; `formatX12TimeElement`,
-  `isValidX12DateAndTime`, `isValidEpcisEventTime`,
-  `isValidEpcisTimeZoneOffset`, `isValidEdifactDtmFormat`,
-  `isValidX12DateTimePeriodFormat`, `isValidX12TimeCode`
 - **Operating hours**: `recurringWindows`, `operatingIntervals`, `isOpenAt`,
   `nextOpenAt`, `nextCloseAt`, `operatingTimeBetween`, `addOperatingTime`
 
 ## References
 
-- [Zoned operations guide](https://gmt-dox.northguild.workers.dev/guides/zoned-date-operations/zoned-operations/)
-- [DST Disambiguation guide](https://gmt-dox.northguild.workers.dev/guides/concepts/dst-disambiguation/)
+- [Zoned operations guide](https://northguild.dev/gmt/guides/zoned-date-operations/zoned-operations/)
+- [DST Disambiguation guide](https://northguild.dev/gmt/guides/concepts/dst-disambiguation/)