@northguild/gmt 1.17.0 → 1.19.0

package/skills/gmt-timezone/SKILL.md

@@ -1,23 +1,25 @@
 ---
 name: gmt-timezone
 description: >
-  Timezone-aware operations — get zoned now, format zoned datetimes/ranges,
-  convert between plain↔zoned↔UTC↔Unix, DST disambiguation on construction and
-  arithmetic, the instant-plus-offset pair, classifying a zoneless wall time
-  before resolving it, real zone unit boundaries
-  (startOfZoned/endOfZoned/startOfUnix/endOfUnix), hours in a local day,
-  flooring or bucketing on local boundaries (floorToZone/bucketRange),
-  calendar-annotated zoned strings, zoned values at the range limits, the
-  transport legs transitTime, etaAtZone and dwellTime (local calendar days
-  crossed), intermodal free time — freeTimeExpiry (the free window and its
-  half-open expiry), chargeableDays (the dates charged, with tier bands),
-  demurrageClock (which events a demurrage, detention, storage or combined clock
-  runs between) — and billingTimeline (invoice, dispute and resolution
-  deadlines, windows as caller parameters). Reads the installed package
-  README.md and source JSDoc for API details; this skill is a routing pointer,
-  not an API dump.
+  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
+  (OperatingSchedule, recurringWindows, operatingIntervals, isOpenAt,
+  nextOpenAt, nextCloseAt, operatingTimeBetween, addOperatingTime), and daylight
+  time (isInDaylightSaving, hasDaylightSaving).
 sources:
-  - 'northguild/gmt:README.md'
+  - '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'
@@ -32,15 +34,26 @@ sources:
   - 'northguild/gmt:packages/gmt/src/utc/get/index.ts'
   - 'northguild/gmt:packages/gmt/src/utc/convert/index.ts'
   - 'northguild/gmt:packages/gmt/src/instant/convert/index.ts'
+  - 'northguild/gmt:packages/gmt/src/instant/validate/index.ts'
   - 'northguild/gmt:packages/gmt/src/calendar/calculate/index.ts'
   - '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.17.0'
+  library_version: '1.19.0'
 ---
 
 # GMT Timezone
@@ -66,6 +79,13 @@ converting between time zones, or doing arithmetic that must respect DST.
 - 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
+  expanding a recurring local window such as a night curfew.
 
 ## Core rules
 
@@ -108,11 +128,11 @@ converting between time zones, or doing arithmetic that must respect DST.
    on a spring-forward one. `resolveLocal(local, zone, { disambiguation })` then
    returns the instant, exact to the nanosecond, or `""` under `"reject"`. Reach
    for `convertPlainDateTimeToZoned` instead when you want the zoned string.
-6. **An offset is not a zone.** `-05:00` does not identify `America/New_York`.
-   `toOffsetInstant` splits a timestamp into `{ instant, offset, timeZone? }` —
-   the shape EPCIS 2.0, EDIFACT DTM and DICOM all exchange, because the instant
-   orders events and the offset renders them where they happened, and neither
-   derives from the other. Keep the zone for what is still to be scheduled.
+6. **An offset is not a zone, but a stored one is a rule for local time.**
+   `toOffsetInstant` gives `{ instant, offset, timeZone? }`, the pair EPCIS 2.0,
+   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.
 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
@@ -192,7 +212,64 @@ converting between time zones, or doing arithmetic that must respect DST.
     (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.
-16. **Free time is counted in the terminal's local days; the start day and the
+    `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
@@ -212,7 +289,7 @@ converting between time zones, or doing arithmetic that must respect DST.
     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.
-17. **Billing deadlines are dates counted from an anchor, and every window is
+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,
@@ -227,9 +304,143 @@ converting between time zones, or doing arithmetic that must respect DST.
     `convertUtcToPlainDate(instant, { timeZone })`. A request before its
     invoice, or an agreed date before the request, returns `null`. GMT
     computes dates, not liability.
-18. **Read the README.** This skill is a routing pointer. For the full DST
-    disambiguation walkthrough, code examples, and locale ICU notes, read the
-    installed package's `README.md` and the source JSDoc.
+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
+    `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
+    midnight and the window belongs to the date it starts on. Holidays are local
+    dates (a `BusinessCalendar` is accepted; only its `holidays` are read); an
+    override replaces one date's windows, holiday or not. Every edge goes
+    through `resolveLocal` with `disambiguation` (default `"compatible"`), so a
+    23:00–06:00 window is 8 real hours across New York's fall-back night.
+    `recurringWindows(weekly, range, zone)` and `operatingIntervals(schedule,
+    range)` return merged open intervals; `isOpenAt`, `nextOpenAt` and
+    `nextCloseAt` answer point questions; `operatingTimeBetween(start, end,
+    schedule)` is open time elapsed (hours as the largest unit), and
+    `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
+    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
+    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
+    string GMT wrote reads back as the instant it was written for. Otherwise
+    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
+    `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
+    valid. 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
+    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.**
+    `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
+    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 is a
+    change of standard time, so
+    `isInDaylightSaving("2016-12-01T12:00:00+03:00[Europe/Istanbul]")` is
+    `false`. The higher of two alternating offsets is the daylight one:
+    `Europe/Dublin` in summer, `Africa/Casablanca` at `+01:00`.
+    `hasDaylightSaving` is `true` when the zone is in daylight time at `at`
+    or a daylight period begins less than 365 days after it. Pass `at` (an
+    ISO 8601 instant string) for an answer that does not depend on the day
+    the code runs: `hasDaylightSaving("Europe/Istanbul", { at:
+    "2015-06-15T12:00:00Z" })` is `true`, and with `"2016-06-15T12:00:00Z"`
+    it is `false`. Without `at` the reference is the current instant. Both
+    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
+    has a `.md` twin that holds its text. The JSDoc ships in the installed
+    package: `node_modules/@northguild/gmt/dist/**/*.d.ts`.
 
 ## Key functions
 
@@ -237,7 +448,7 @@ converting between time zones, or doing arithmetic that must respect DST.
 - **Formatting**: `formatZonedDateTime`, `formatZonedRange`,
   `formatRelativeZoned`, `formatTimeZoneName`
 - **Validation**: `isValidTimeZone`, `isValidZonedDateTime`,
-  `hasDaylightSaving`, `getDstTransitions`, `isInDaylightSaving`
+  `hasDaylightSaving` (`{ at }`), `getDstTransitions`, `isInDaylightSaving`
 - **Conversion**: `convertPlainDateTimeToZoned`, `convertZonedToPlainDateTime`,
   `convertUtcToZoned`, `convertZonedToUtc`, `convertZonedToCalendar`,
   `convertUtcToUnix`, `convertUnixToUtc`
@@ -249,16 +460,39 @@ converting between time zones, or doing arithmetic that must respect DST.
   `endOfUnix`, `mapZonedHoursInDay`, `getHoursInZonedDay`
 - **Offset/DST reads**: `getZonedOffset`, `getZonedOffsetAs`,
   `getTimeZoneOffset`, `parseTimeZoneFromZoned`
-- **Offset-preserving instants**: `toOffsetInstant`, `fromOffsetInstant`
+- **Offset-preserving instants**: `toOffsetInstant`, `fromOffsetInstant`,
+  `isValidUtcOffset` (the pair's `±HH:MM[:SS]` offset; not `Z`, not `+0530`)
 - **Local-time resolution**: `classifyLocal`, `resolveLocal`
 - **Zone-aware buckets**: `floorToZone`, `bucketRange`,
   `isValidZoneBucketUnit`
-- **Transport legs and dwell**: `transitTime`, `etaAtZone`, `dwellTime`
+- **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
 
-- [README — Timezone and Calendar examples](README.md)
+- [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/)

package/dist/duration/calculate/durationAs.d.ts

@@ -1,62 +0,0 @@
-import { Temporal } from "@js-temporal/polyfill";
-import type { DateTimeDurationUnit, DurationRelativeTo } from "../../types/index.js";
-/**
- * Express an ISO 8601 duration as a single fractional total in one unit.
- *
- * - Uses Temporal.Duration.from and .total — the whole duration is converted, so
- *   durationAs("P1DT2H30M", "hours") is 26.5, not the 2 that `getDurationUnit` reads.
- * - The result is fractional, not rounded: durationAs("P1DT2H30M", "days") is
- *   1.1041666666666667. Round it yourself, or reach for `normalizeDuration` instead.
- * - `relativeTo` is required whenever a calendar unit (year/month/week) is involved, in
- *   *either* direction — as the requested `unit`, or because the input duration already has
- *   a nonzero year/month/week component. Without it, returns null. This is the same
- *   documented gap `normalizeDuration` (A3) carries; `addDuration`/`subtractDuration` (A2)
- *   have it worse still, since Temporal gives them no `relativeTo` option at all.
- * - The requested-unit half of that rule bites even on day/time-only input: "P1DT2H30M" has
- *   no calendar component, yet durationAs("P1DT2H30M", "weeks") is still null — a week is a
- *   calendar quantity to Temporal regardless of what it is being measured from.
- * - `relativeTo` changes the answer for non-calendar units too when it names a zoned instant:
- *   a day spanning a DST spring-forward transition totals 23 hours, not 24.
- * - A zoned `relativeTo` string resolves its wall time with disambiguation "compatible" and
- *   offset "reject", as Temporal does: an ambiguous wall time takes the earlier instant, a
- *   nonexistent one the later instant, and an offset that does not match the zone returns null.
- *   Pass an explicit offset to pick the other reading of an ambiguous wall time.
- * - A `relativeTo` string is ISO 8601 extended format before its first `[`:
- *   a date, a date-time, or with a time zone annotation a zoned date-time (`<date>T<time>`, then
- *   nothing, `Z` or `±HH:MM`). Basic format (`"20240101"`), a space or lower-case `t` separator, a
- *   lower-case `z`, a UTC offset without a zone and a zoned date without a time are invalid.
- * - A `relativeTo` string takes a calendar in RFC 9557 form, as `convertDateToCalendar` and
- *   `convertZonedToCalendar` write it: ISO digits and a `[u-ca=<id>]` annotation, after the zone
- *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`).
- *   The annotations are read as Temporal reads them: the critical flag and the id's letter case
- *   are accepted, elective unknown annotations are ignored, the first `u-ca` names the calendar,
- *   and a string with a time zone annotation is zoned. An unknown critical annotation, a critical
- *   duplicate calendar, a calendar before the zone, an unsupported calendar and a leap second in
- *   any spelling return null.
- *   Compatibility: before 1.16.0 the digits were read as the calendar's own year, month and day.
- * - `unit` accepts the plural or singular name (`"hours"` or `"hour"`), as Temporal does.
- * - Returns null on a non-duration `value`, an invalid `unit`, or an invalid `relativeTo`.
- *
- * @param value ISO 8601 duration string
- * @param unit DateTimeDurationUnit to total into ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds", or the singular name)
- * @param options optional: { relativeTo } — anchor date/instant, required for any calendar unit
- * @returns the fractional total in `unit`, or null on invalid input
- *
- * @example durationAs("P1DT2H30M", "hours") // 26.5
- * @example durationAs("P1DT2H30M", "minutes") // 1590
- * @example durationAs("PT36H", "days") // 1.5
- * @example durationAs("-PT90M", "hours") // -1.5
- * @example durationAs("P1M", "days") // null (calendar unit needs relativeTo)
- * @example durationAs("P1M", "days", { relativeTo: "2024-02-01" }) // 29
- * @example durationAs("P1M", "days", { relativeTo: "20240201" }) // null (basic format)
- * @example durationAs("P1D", "hours", { relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]" }) // 23 (spring-forward)
- * @example durationAs("P1D", "hours", { relativeTo: "2024-11-03T01:30[America/New_York]" }) // 25
- * @example durationAs("P1DT2H30M", "minute") // 1590 (singular unit name)
- * @example durationAs("not a duration", "hours") // null
- * @example durationAs("P1Y", "days", { relativeTo: "2024-02-24[u-ca=hebrew]" }) // 385 (Hebrew leap year 5784)
- * @example durationAs("P1M", "days", { relativeTo: "2024-02-10[!u-ca=hebrew]" }) // 30 (1 Adar I 5784; the critical flag is accepted)
- * @example durationAs("P1M", "days", { relativeTo: "2024-02-10T00:00:00[u-ca=hebrew]" }) // 30 (a date-time without a zone reads as its date, as Temporal reads relativeTo)
- */
-export declare function durationAs(value: string, unit: DateTimeDurationUnit | Temporal.DateTimeUnit, options?: {
-    relativeTo?: DurationRelativeTo;
-}): number | null;

package/dist/internal/resolveReadingTimeZone.d.ts

@@ -1,11 +0,0 @@
-/**
- * Resolve the `timeZone` option a UTC reader uses to read a value's wall-clock fields.
- *
- * - `undefined` (the option omitted) resolves to `"UTC"`.
- * - A valid IANA zone (or `"UTC"`) resolves to itself.
- * - Any other value is invalid and resolves to `null`, which callers map to their sentinel.
- *
- * @param timeZone raw option value from caller input
- * @returns the zone to read in, or `null` when the value is invalid
- */
-export declare function resolveReadingTimeZone(timeZone: unknown): string | null;

package/dist/internal/resolveReadingTimeZone.js

@@ -1,18 +0,0 @@
-import { isValidTimeZone } from "../zoned/validate/isValidTimeZone.js";
-/**
- * Resolve the `timeZone` option a UTC reader uses to read a value's wall-clock fields.
- *
- * - `undefined` (the option omitted) resolves to `"UTC"`.
- * - A valid IANA zone (or `"UTC"`) resolves to itself.
- * - Any other value is invalid and resolves to `null`, which callers map to their sentinel.
- *
- * @param timeZone raw option value from caller input
- * @returns the zone to read in, or `null` when the value is invalid
- */
-export function resolveReadingTimeZone(timeZone) {
-    if (timeZone === undefined || timeZone === "UTC")
-        return "UTC";
-    return typeof timeZone === "string" && isValidTimeZone(timeZone)
-        ? timeZone
-        : null;
-}

package/dist/internal/unixZonedDateTime.d.ts

@@ -1,22 +0,0 @@
-import type { Temporal } from "@js-temporal/polyfill";
-/**
- * Read a Unix epoch argument as a `Temporal.ZonedDateTime` under the shared `unix/` options, or
- * null when anything is invalid.
- *
- * - `value` follows the one epoch grammar (`parseUnixEpochValue`).
- * - `epochUnit` accepts singular or plural names and defaults to `"milliseconds"`.
- * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone is invalid
- *   (see `normalizeTimeZone`).
- *
- * @param value Unix epoch number or digit string
- * @param options optional `{ epochUnit, timeZone }`
- * @returns the zoned date-time, or null
- *
- * @example unixZonedDateTime(0)?.toString() // "1970-01-01T00:00:00+00:00[UTC]"
- * @example unixZonedDateTime("86400", { epochUnit: "second", timeZone: "Asia/Tokyo" })?.hour // 9
- * @example unixZonedDateTime(0, { timeZone: "Asia/Tokio" }) // null
- */
-export declare function unixZonedDateTime(value: unknown, options?: {
-    epochUnit?: unknown;
-    timeZone?: unknown;
-}): Temporal.ZonedDateTime | null;

package/dist/internal/unixZonedDateTime.js

@@ -1,32 +0,0 @@
-import { normalizeTimeZone } from "./normalizeTimeZone.js";
-import { resolveUnixEpochUnit, unixEpochToInstant } from "./unixEpochValue.js";
-/**
- * Read a Unix epoch argument as a `Temporal.ZonedDateTime` under the shared `unix/` options, or
- * null when anything is invalid.
- *
- * - `value` follows the one epoch grammar (`parseUnixEpochValue`).
- * - `epochUnit` accepts singular or plural names and defaults to `"milliseconds"`.
- * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone is invalid
- *   (see `normalizeTimeZone`).
- *
- * @param value Unix epoch number or digit string
- * @param options optional `{ epochUnit, timeZone }`
- * @returns the zoned date-time, or null
- *
- * @example unixZonedDateTime(0)?.toString() // "1970-01-01T00:00:00+00:00[UTC]"
- * @example unixZonedDateTime("86400", { epochUnit: "second", timeZone: "Asia/Tokyo" })?.hour // 9
- * @example unixZonedDateTime(0, { timeZone: "Asia/Tokio" }) // null
- */
-export function unixZonedDateTime(value, options) {
-    const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-    const timeZone = normalizeTimeZone(options?.timeZone);
-    if (epochUnit === null || !timeZone) {
-        return null;
-    }
-    try {
-        return (unixEpochToInstant(value, epochUnit)?.toZonedDateTimeISO(timeZone) ?? null);
-    }
-    catch {
-        return null;
-    }
-}

package/dist/internal/utcZonedDateTime.d.ts

@@ -1,16 +0,0 @@
-import { Temporal } from "@js-temporal/polyfill";
-/**
- * Read a UTC ISO string as a zoned date-time for the `parse*FromUtc` accessors: the instant it
- * names, on the wall clock of `options.timeZone` (UTC when omitted). The utc twin of
- * `unixZonedDateTime`.
- *
- * @param value UTC ISO 8601 datetime string
- * @param options optional `{ timeZone }`
- * @returns the zoned date-time, or null when the value or the zone is invalid
- * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "Asia/Tokyo" })?.toString() // "2024-03-15T23:30:00+09:00[Asia/Tokyo]"
- * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "Invalid/Zone" }) // null
- * @example utcZonedDateTime("2024-03-15T14:30:00") // null (no Z)
- */
-export declare function utcZonedDateTime(value: string, options?: {
-    timeZone?: string;
-}): Temporal.ZonedDateTime | null;

package/dist/internal/utcZonedDateTime.js

@@ -1,28 +0,0 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUtc } from "../utc/validate/isValidUtc.js";
-import { resolveReadingTimeZone } from "./resolveReadingTimeZone.js";
-/**
- * Read a UTC ISO string as a zoned date-time for the `parse*FromUtc` accessors: the instant it
- * names, on the wall clock of `options.timeZone` (UTC when omitted). The utc twin of
- * `unixZonedDateTime`.
- *
- * @param value UTC ISO 8601 datetime string
- * @param options optional `{ timeZone }`
- * @returns the zoned date-time, or null when the value or the zone is invalid
- * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "Asia/Tokyo" })?.toString() // "2024-03-15T23:30:00+09:00[Asia/Tokyo]"
- * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "Invalid/Zone" }) // null
- * @example utcZonedDateTime("2024-03-15T14:30:00") // null (no Z)
- */
-export function utcZonedDateTime(value, options) {
-    if (!isValidUtc(value))
-        return null;
-    const timeZone = resolveReadingTimeZone(options?.timeZone);
-    if (timeZone === null)
-        return null;
-    try {
-        return Temporal.Instant.from(value).toZonedDateTimeISO(timeZone);
-    }
-    catch {
-        return null;
-    }
-}

package/dist/types/duration-unit.d.ts

@@ -1,5 +0,0 @@
-/**
- * Plural unit keys accepted by `formatDuration` for `UNIT_TO_INTL` lookup. Maps to
- * singular `Intl.NumberFormat` unit labels (e.g. `"years"` → `"year"`).
- */
-export type DurationUnit = "years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds";