@northguild/gmt 1.16.0 → 1.17.0

package/dist/intermodal/calculate/billingTimeline.js

@@ -0,0 +1,168 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isObject } from "../../internal/index.js";
+import { isValidDate } from "../../plain/validate/isValidDate.js";
+/**
+ * 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 function billingTimeline(dates, windows) {
+    try {
+        return layOutDeadlines(dates, windows);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}
+/** A window is a whole number of calendar days, zero or more. */
+function isWindow(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/** An optional date is absent (`undefined`) or a valid ISO date; anything else is invalid. */
+function optionalDate(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return typeof value === "string" && isValidDate(value) ? value : null;
+}
+/** `date + days` on the ISO calendar, canonical. Throws `RangeError` past Temporal's range. */
+function plusDays(date, days) {
+    return Temporal.PlainDate.from(date).add({ days }).toString();
+}
+/** Whether `date` is on or before `deadline`. */
+function byDeadline(date, deadline) {
+    return (Temporal.PlainDate.compare(Temporal.PlainDate.from(date), Temporal.PlainDate.from(deadline)) <= 0);
+}
+/** The dates, each a valid ISO date, with no request before its invoice; `null` otherwise. */
+function readDates(dates) {
+    const { anchorOn } = dates;
+    if (typeof anchorOn !== "string" || !isValidDate(anchorOn)) {
+        return null;
+    }
+    const invoiceIssuedOn = optionalDate(dates.invoiceIssuedOn);
+    const requestReceivedOn = optionalDate(dates.requestReceivedOn);
+    if (invoiceIssuedOn === null || requestReceivedOn === null) {
+        return null;
+    }
+    // A request cannot precede the invoice it disputes.
+    if (requestReceivedOn !== undefined &&
+        (invoiceIssuedOn === undefined ||
+            !byDeadline(invoiceIssuedOn, requestReceivedOn))) {
+        return null;
+    }
+    return { anchorOn, invoiceIssuedOn, requestReceivedOn };
+}
+/** The three windows, each present and valid, and the agreed date if given; `null` otherwise. */
+function readWindows(windows) {
+    const { issueDays, disputeDays, resolutionDays } = windows;
+    if (!isWindow(issueDays) ||
+        !isWindow(disputeDays) ||
+        !isWindow(resolutionDays)) {
+        return null;
+    }
+    const agreedResolutionOn = optionalDate(windows.agreedResolutionOn);
+    if (agreedResolutionOn === null) {
+        return null;
+    }
+    return { issueDays, disputeDays, resolutionDays, agreedResolutionOn };
+}
+/** The agreed date when given, else `requestReceivedOn + resolutionDays`; `null` with no request. */
+function resolutionDeadline(requestReceivedOn, windows) {
+    if (requestReceivedOn === undefined) {
+        return null;
+    }
+    return windows.agreedResolutionOn === undefined
+        ? plusDays(requestReceivedOn, windows.resolutionDays)
+        : Temporal.PlainDate.from(windows.agreedResolutionOn).toString();
+}
+/** Whether `date` is on or before `deadline`; `null` until both exist. */
+function onOrBefore(date, deadline) {
+    return date === undefined || deadline === null
+        ? null
+        : byDeadline(date, deadline);
+}
+/** An agreed resolution date cannot precede the request it resolves. */
+function agreedAfterRequest(requestReceivedOn, agreedResolutionOn) {
+    return (requestReceivedOn === undefined ||
+        agreedResolutionOn === undefined ||
+        byDeadline(requestReceivedOn, agreedResolutionOn));
+}
+/** `billingTimeline` without the guard; every read of its arguments happens here. */
+function layOutDeadlines(dates, windows) {
+    if (!isObject(dates) || !isObject(windows)) {
+        return null;
+    }
+    const read = readDates(dates);
+    const counts = readWindows(windows);
+    if (read === null ||
+        counts === null ||
+        !agreedAfterRequest(read.requestReceivedOn, counts.agreedResolutionOn)) {
+        return null;
+    }
+    const { anchorOn, invoiceIssuedOn, requestReceivedOn } = read;
+    const invoiceDeadline = plusDays(anchorOn, counts.issueDays);
+    const disputeDeadline = invoiceIssuedOn === undefined
+        ? null
+        : plusDays(invoiceIssuedOn, counts.disputeDays);
+    return {
+        invoiceDeadline,
+        issuedByDeadline: onOrBefore(invoiceIssuedOn, invoiceDeadline),
+        disputeDeadline,
+        requestedByDeadline: onOrBefore(requestReceivedOn, disputeDeadline),
+        resolutionDeadline: resolutionDeadline(requestReceivedOn, counts),
+    };
+}

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

@@ -0,0 +1,98 @@
+import type { FreeTimeBasis, FreeTimeOptions } from "../../types/index.js";
+/** A band of chargeable-day ordinals and how many of the charged days fell in it. */
+export interface TierBand {
+    /** First chargeable-day ordinal of the band, from 1. */
+    from: number;
+    /** Last ordinal of the band, or `null` for the open final band. */
+    to: number | null;
+    /** Charged days that fell in the band. */
+    days: number;
+}
+/** What `chargeableDays` returns: the day count an invoice bills, and the dates that back it. */
+export interface FreeTimeCharges {
+    /** Free days the dwell touched, at most the tariff's `freeDays`. */
+    freeDaysUsed: number;
+    /** Counted days on or after `expiresAt` the dwell touched. */
+    chargeableDays: number;
+    /** The instant free time ended, as a UTC instant, as `freeTimeExpiry` reports it. */
+    expiresAt: string;
+    /**
+     * The local dates charged, ascending. Carriers' day-numbered tariff grids and progressive tiers
+     * are applied to this list, and its entries are the dates an itemised invoice can list.
+     */
+    chargedDates: string[];
+    /** The charged days split into the `tiers` bands; one open band when no tiers were given. */
+    byTier: TierBand[];
+}
+/** `FreeTimeOptions` plus how charged days are counted, and the optional tier boundaries. */
+export type FreeTimeChargeOptions = FreeTimeOptions & {
+    /**
+     * How days after expiry are charged: `"calendar"` charges every local day, `"working"` only the
+     * working days of `calendar`. No default; see `chargeableDays`.
+     */
+    chargeBasis: FreeTimeBasis;
+    tiers?: number[];
+};
+/**
+ * Count the days a container is charged for between the start of its clock and its exit,
+ * and list the dates behind the count.
+ *
+ * Lays out free time with the same walk as `freeTimeExpiry`, then counts the days on or after
+ * the expiry that the half-open dwell `[clockStart, clockEnd)` touched. The result is the
+ * auditable form of a demurrage or detention charge: `chargedDates` lists the days behind the
+ * count, which is the list a day-numbered tariff grid is applied to, and the dates an itemised
+ * invoice can list. No regulation or industry standard fixes how the days are counted; every term
+ * below is the tariff's. GMT computes days, never money: `byTier` says how many days fell in each
+ * band so the caller can apply its rates.
+ *
+ * - **Half-open at the exit.** A day is charged when it started before `clockEnd`, so a
+ *   gate-out at exactly `expiresAt` is `0` chargeable days and one nanosecond later is `1`. A
+ *   zero-length dwell touches the day it sits on, as `dwellTime` counts. On the calendar basis
+ *   with `firstDay: "eventDay"`, `freeDaysUsed + chargeableDays` equals `dwellTime(...).calendarDays`,
+ *   with one exception: a fall-back that re-enters the day before the event day (`America/Goose_Bay`,
+ *   00:01 on 7 November 2010 back into the 6th) is a date `dwellTime` counts as touched, and a
+ *   tariff never counts a date before the event day.
+ * - **The free-time terms are `freeTimeExpiry`'s**: `basis`, `timeZone`, `firstDay` and
+ *   `calendar` mean the same, and `firstDay` has no default.
+ * - **`chargeBasis` says how days after expiry are charged, and has no default.** Many
+ *   tariffs count free time and charges alike in calendar days. Where a tariff grants free time in
+ *   working days, the days after it are mostly charged as calendar days, weekends and holidays
+ *   included (Hapag-Lloyd's tables: "Rate per Calendar day"; ACL: "Once free time expires ...
+ *   charged on calendar days"): `basis: "working", chargeBasis: "calendar"`. Some tariffs charge
+ *   working days only, for free time and charges alike, so neither counts a day the gate is
+ *   closed or a holiday: both `"working"`.
+ *   Either `"working"` needs `calendar`. The two differ by every closed day after expiry, so
+ *   neither is assumed.
+ * - **`freeDays` may be `0`** for a tariff with no free time: `expiresAt` is the start of day one,
+ *   the first day counted on `basis` (under `"nextDay"`, the first after the event day), and days
+ *   before it are neither free nor charged.
+ * - **`tiers` are day bands, not rates.** `[5, 10]` names the last chargeable-day ordinal of
+ *   each band: days 1–5, 6–10 and 11 onward. Every band is returned, an empty one with
+ *   `days: 0`, and the last is always open. Omitted, `byTier` is the single open band
+ *   `{ from: 1, to: null }`. A list that is not strictly ascending positive whole numbers
+ *   returns `null`.
+ * - Returns `null` when either instant is invalid, `clockEnd` is before `clockStart` (an
+ *   inverted dwell is a data error), `freeDays` is not a whole number of at least `0`, the
+ *   options fail as they do for `freeTimeExpiry`, `tiers` has a hole, an unsafe integer or does not ascend, or the walk would pass
+ *   10,000 local days.
+ *
+ * @param clockStart ISO 8601 instant string of the event that starts the clock
+ * @param clockEnd ISO 8601 instant string of the event that stops it (gate-out or empty return)
+ * @param freeDays whole number of free days the tariff allows, 0 or more
+ * @param options { basis, chargeBasis, timeZone, firstDay, calendar?, tiers?: number[] }
+ * @returns the free days used, the chargeable days, the expiry, the charged dates and the days per tier band, or null on invalid input
+ *
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (gate-out exactly at expiry is free)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 1, expiresAt: "2024-06-17T04:00:00Z", chargedDates: ["2024-06-17"], byTier: [{ from: 1, to: null, days: 1 }] } (one second later is a charged day)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "nextDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-18T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (the other start-day convention: still free)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", 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 }] }
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/New_York" } }) // { 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 }] } (free days in working days, every calendar day after expiry charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/New_York" } }) // { 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 }] } (working days throughout: closed days after expiry are not charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-15T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 2, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (out on the second free day)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-16T15:00:00Z", 0, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 0, chargeableDays: 3, expiresAt: "2024-06-14T04:00:00Z", chargedDates: ["2024-06-14", "2024-06-15", "2024-06-16"], byTier: [{ from: 1, to: null, days: 3 }] } (no free time: every day is charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", tiers: [10, 5] }) // null (tiers must ascend)
+ * @example chargeableDays("2024-06-17T04:00:01Z", "2024-06-14T19:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (exit before the clock started)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York" }) // null (firstDay has no default)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (chargeBasis has no default)
+ */
+export declare function chargeableDays(clockStart: string, clockEnd: string, freeDays: number, options: FreeTimeChargeOptions): FreeTimeCharges | null;

package/dist/intermodal/calculate/chargeableDays.js

@@ -0,0 +1,101 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { bandsByTier, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "../../internal/index.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+/**
+ * Count the days a container is charged for between the start of its clock and its exit,
+ * and list the dates behind the count.
+ *
+ * Lays out free time with the same walk as `freeTimeExpiry`, then counts the days on or after
+ * the expiry that the half-open dwell `[clockStart, clockEnd)` touched. The result is the
+ * auditable form of a demurrage or detention charge: `chargedDates` lists the days behind the
+ * count, which is the list a day-numbered tariff grid is applied to, and the dates an itemised
+ * invoice can list. No regulation or industry standard fixes how the days are counted; every term
+ * below is the tariff's. GMT computes days, never money: `byTier` says how many days fell in each
+ * band so the caller can apply its rates.
+ *
+ * - **Half-open at the exit.** A day is charged when it started before `clockEnd`, so a
+ *   gate-out at exactly `expiresAt` is `0` chargeable days and one nanosecond later is `1`. A
+ *   zero-length dwell touches the day it sits on, as `dwellTime` counts. On the calendar basis
+ *   with `firstDay: "eventDay"`, `freeDaysUsed + chargeableDays` equals `dwellTime(...).calendarDays`,
+ *   with one exception: a fall-back that re-enters the day before the event day (`America/Goose_Bay`,
+ *   00:01 on 7 November 2010 back into the 6th) is a date `dwellTime` counts as touched, and a
+ *   tariff never counts a date before the event day.
+ * - **The free-time terms are `freeTimeExpiry`'s**: `basis`, `timeZone`, `firstDay` and
+ *   `calendar` mean the same, and `firstDay` has no default.
+ * - **`chargeBasis` says how days after expiry are charged, and has no default.** Many
+ *   tariffs count free time and charges alike in calendar days. Where a tariff grants free time in
+ *   working days, the days after it are mostly charged as calendar days, weekends and holidays
+ *   included (Hapag-Lloyd's tables: "Rate per Calendar day"; ACL: "Once free time expires ...
+ *   charged on calendar days"): `basis: "working", chargeBasis: "calendar"`. Some tariffs charge
+ *   working days only, for free time and charges alike, so neither counts a day the gate is
+ *   closed or a holiday: both `"working"`.
+ *   Either `"working"` needs `calendar`. The two differ by every closed day after expiry, so
+ *   neither is assumed.
+ * - **`freeDays` may be `0`** for a tariff with no free time: `expiresAt` is the start of day one,
+ *   the first day counted on `basis` (under `"nextDay"`, the first after the event day), and days
+ *   before it are neither free nor charged.
+ * - **`tiers` are day bands, not rates.** `[5, 10]` names the last chargeable-day ordinal of
+ *   each band: days 1–5, 6–10 and 11 onward. Every band is returned, an empty one with
+ *   `days: 0`, and the last is always open. Omitted, `byTier` is the single open band
+ *   `{ from: 1, to: null }`. A list that is not strictly ascending positive whole numbers
+ *   returns `null`.
+ * - Returns `null` when either instant is invalid, `clockEnd` is before `clockStart` (an
+ *   inverted dwell is a data error), `freeDays` is not a whole number of at least `0`, the
+ *   options fail as they do for `freeTimeExpiry`, `tiers` has a hole, an unsafe integer or does not ascend, or the walk would pass
+ *   10,000 local days.
+ *
+ * @param clockStart ISO 8601 instant string of the event that starts the clock
+ * @param clockEnd ISO 8601 instant string of the event that stops it (gate-out or empty return)
+ * @param freeDays whole number of free days the tariff allows, 0 or more
+ * @param options { basis, chargeBasis, timeZone, firstDay, calendar?, tiers?: number[] }
+ * @returns the free days used, the chargeable days, the expiry, the charged dates and the days per tier band, or null on invalid input
+ *
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (gate-out exactly at expiry is free)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 1, expiresAt: "2024-06-17T04:00:00Z", chargedDates: ["2024-06-17"], byTier: [{ from: 1, to: null, days: 1 }] } (one second later is a charged day)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "nextDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-18T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (the other start-day convention: still free)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", 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 }] }
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/New_York" } }) // { 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 }] } (free days in working days, every calendar day after expiry charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/New_York" } }) // { 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 }] } (working days throughout: closed days after expiry are not charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-15T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 2, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (out on the second free day)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-16T15:00:00Z", 0, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 0, chargeableDays: 3, expiresAt: "2024-06-14T04:00:00Z", chargedDates: ["2024-06-14", "2024-06-15", "2024-06-16"], byTier: [{ from: 1, to: null, days: 3 }] } (no free time: every day is charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", tiers: [10, 5] }) // null (tiers must ascend)
+ * @example chargeableDays("2024-06-17T04:00:01Z", "2024-06-14T19:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (exit before the clock started)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York" }) // null (firstDay has no default)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (chargeBasis has no default)
+ */
+export function chargeableDays(clockStart, clockEnd, freeDays, options) {
+    try {
+        const terms = parseFreeTimeTerms(options, true);
+        const allowed = parseFreeDays(freeDays, 0);
+        // Read after the terms, so a non-object `options` is never read from.
+        const tiers = terms === null ? null : parseTiers(options.tiers);
+        if (!isValidInstant(clockStart) ||
+            !isValidInstant(clockEnd) ||
+            terms === null ||
+            allowed === null ||
+            tiers === null) {
+            return null;
+        }
+        const start = Temporal.Instant.from(clockStart).toZonedDateTimeISO(terms.timeZone);
+        const end = Temporal.Instant.from(clockEnd).toZonedDateTimeISO(terms.timeZone);
+        if (Temporal.ZonedDateTime.compare(start, end) > 0) {
+            return null;
+        }
+        const ledger = walkFreeTime(start, allowed, terms, end);
+        if (ledger === null) {
+            return null;
+        }
+        return {
+            freeDaysUsed: ledger.used,
+            chargeableDays: ledger.charged.length,
+            expiresAt: ledger.expiresAt.toInstant().toString(),
+            chargedDates: ledger.charged.map((day) => day.date),
+            byTier: bandsByTier(tiers, ledger.charged.length),
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,93 @@
+import type { Interval } from "../../types/index.js";
+/**
+ * The events a container's charging clocks run between, named after the DCSA Track & Trace
+ * equipment events they correspond to (`equipmentEventTypeCode` with `emptyIndicatorCode`):
+ *
+ * - `discharged`: DISC, laden — the full container is discharged from the vessel (import).
+ * - `available`: no DCSA event — the container availability date some import tariffs start the
+ *   clock at.
+ * - `gatedOut`: GTOT, laden — the full container leaves the terminal (import).
+ * - `emptyReturned`: GTIN, empty — the empty is returned to the terminal or depot (import).
+ * - `emptyReleased`: GTOT or PICK, empty — the empty is picked up for stuffing (export).
+ * - `gatedIn`: GTIN, laden — the full container is received at the terminal (export).
+ * - `loaded`: LOAD, laden — the full container is loaded on board (export).
+ */
+export type ClockEventType = "discharged" | "available" | "gatedOut" | "emptyReturned" | "emptyReleased" | "gatedIn" | "loaded";
+/** A container event: what happened and the instant it happened. */
+export interface ClockEvent {
+    type: ClockEventType;
+    /** ISO 8601 instant string: `Z`, an offset, or a bracketed zone. */
+    at: string;
+}
+/** Which charge is being clocked. `combined` is the merged demurrage-and-detention clock. */
+export type ClockScope = "demurrage" | "detention" | "storage" | "combined";
+/** Which leg of the container's cycle the clock is on. */
+export type ClockDirection = "import" | "export";
+/** Where an import demurrage, storage or combined clock starts, when the tariff says so. */
+export type ClockStartEvent = "discharged" | "available";
+/** The options `demurrageClock` reads. */
+export interface ClockOptions {
+    /** `"import"` or `"export"`; required, because the same scope runs between different events in each. */
+    direction: ClockDirection;
+    /** Import only: `"discharged"` (the default) or `"available"`. Not read for export or detention. */
+    startEvent?: ClockStartEvent;
+}
+/**
+ * Pick the two events a charge's clock runs between.
+ *
+ * No regulation or industry standard fixes these events; the carriers' published tariffs agree
+ * on them (import: Maersk's terms, CMA CGM's general terms, Hapag-Lloyd, ACL; export: Maersk, CMA
+ * CGM, ACL), and DCSA's glossary draws the line they rest on: demurrage is charged while the
+ * container is inside the terminal or depot, detention while it is outside, and storage is the
+ * charge for the terminal's space, paid to the terminal or to the carrier on its behalf. Export
+ * storage (`gatedIn` → `loaded`) follows from that storage definition; no tariff read quotes it.
+ * The merged clock runs demurrage and detention as one period, a named tariff product at Maersk
+ * ("Combined"), CMA CGM ("merged") and MSC. `demurrageClock` selects the pair for the charge and
+ * direction asked for, so the wrong pair can never reach `chargeableDays`.
+ *
+ * | scope | import | export |
+ * | --- | --- | --- |
+ * | `demurrage`, `storage` | `startEvent` → `gatedOut` | `gatedIn` → `loaded` |
+ * | `detention` | `gatedOut` → `emptyReturned` | `emptyReleased` → `gatedIn` |
+ * | `combined` | `startEvent` → `emptyReturned` | `emptyReleased` → `loaded` |
+ *
+ * - **`direction` has no default.** The same scope name selects different events on the import and
+ *   export legs, and guessing it from the events present would be a silent guess.
+ * - **`startEvent` is import only**: `"discharged"` by default, the classic definition, or
+ *   `"available"` for tariffs that start at the availability date. It is not read for detention
+ *   or export, so one options object can serve every scope on a leg. A tariff that starts at
+ *   customs release (Hapag-Lloyd Japan) or ends export demurrage at the cut-off or the scheduled
+ *   sailing passes that instant as the event's `at`; GMT does not invent an event for one tariff.
+ * - Events may be in any order, and every one must be `{ type, at }` with a known type and a
+ *   valid instant, used or not, with no holes in the array: a list with a bad entry is a bad list.
+ * - The result is an `Interval`, half-open `[start, end)`, in the caller's own strings, and feeds
+ *   `chargeableDays(start, end, …)` directly.
+ * - Some tariffs differ in words, not events: MSC USA calls the in-terminal container charge
+ *   "detention" and the out-of-terminal one "per diem". GMT's scope names follow the global usage.
+ * - Returns `null` when `events` is not an array or holds an invalid event or a hole, `scope`,
+ *   `direction` or `startEvent` is unknown, `options` is not an object, a required event is
+ *   missing or occurs more than once (a container discharged twice is a data error, not a choice),
+ *   or the end event precedes the start event.
+ *
+ * @param events the container's events, `{ type, at }`, `type` one of discharged, available, gatedOut, emptyReturned, emptyReleased, gatedIn, loaded
+ * @param scope "demurrage" | "detention" | "storage" | "combined"
+ * @param options { direction: "import" | "export", startEvent?: "discharged" | "available" }
+ * @returns { start, end } of the requested clock, or null on invalid input
+ *
+ * @example demurrageClock([{ 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" }], "demurrage", { direction: "import" }) / { start: "2024-06-14T19:00:00Z", end: "2024-06-20T14:30:00Z" }
+ * @example demurrageClock([{ 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" }], "detention", { direction: "import" }) / { start: "2024-06-20T14:30:00Z", end: "2024-06-27T09:00:00Z" } (gate-out to empty return, not discharge)
+ * @example demurrageClock([{ 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" }], "combined", { direction: "import" }) / { start: "2024-06-14T19:00:00Z", end: "2024-06-27T09:00:00Z" } (merged: discharge to empty return)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "available", at: "2024-06-15T12:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage", { direction: "import", startEvent: "available" }) // { start: "2024-06-15T12:00:00Z", end: "2024-06-20T14:30:00Z" }
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "storage", { direction: "import" }) / { start: "2024-06-14T19:00:00Z", end: "2024-06-20T14:30:00Z" }
+ * @example demurrageClock([{ type: "emptyReleased", at: "2024-07-01T08:00:00Z" }, { type: "gatedIn", at: "2024-07-05T16:00:00Z" }, { type: "loaded", at: "2024-07-09T03:00:00Z" }], "demurrage", { direction: "export" }) // { start: "2024-07-05T16:00:00Z", end: "2024-07-09T03:00:00Z" } (gate-in full to loaded on board)
+ * @example demurrageClock([{ type: "emptyReleased", at: "2024-07-01T08:00:00Z" }, { type: "gatedIn", at: "2024-07-05T16:00:00Z" }, { type: "loaded", at: "2024-07-09T03:00:00Z" }], "detention", { direction: "export" }) // { start: "2024-07-01T08:00:00Z", end: "2024-07-05T16:00:00Z" } (empty picked up to gate-in full)
+ * @example demurrageClock([{ type: "emptyReleased", at: "2024-07-01T08:00:00Z" }, { type: "gatedIn", at: "2024-07-05T16:00:00Z" }, { type: "loaded", at: "2024-07-09T03:00:00Z" }], "combined", { direction: "export" }) // { start: "2024-07-01T08:00:00Z", end: "2024-07-09T03:00:00Z" }
+ * @example demurrageClock([{ type: "gatedOut", at: "2024-06-20T10:30:00-04:00[America/New_York]" }, { type: "emptyReturned", at: "2024-06-27T09:00:00Z" }], "detention", { direction: "import", startEvent: "available" }) // { start: "2024-06-20T10:30:00-04:00[America/New_York]", end: "2024-06-27T09:00:00Z" } (startEvent is not read for detention; strings are echoed as given)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage") // null (direction has no default)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage", { direction: "import", startEvent: "available" }) // null (no availability event)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }], "demurrage", { direction: "import" }) // null (still in the terminal: no gate-out)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "discharged", at: "2024-06-15T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage", { direction: "import" }) // null (discharged twice)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-21T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage", { direction: "import" }) // null (gate-out before discharge)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "laytime", { direction: "import" }) // null (not a clock this function selects)
+ */
+export declare function demurrageClock(events: ClockEvent[], scope: ClockScope, options: ClockOptions): Interval | null;

package/dist/intermodal/calculate/demurrageClock.js

@@ -0,0 +1,140 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isObject } from "../../internal/index.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+const CLOCK_EVENT_TYPES = [
+    "discharged",
+    "available",
+    "gatedOut",
+    "emptyReturned",
+    "emptyReleased",
+    "gatedIn",
+    "loaded",
+];
+const CLOCK_SCOPES = [
+    "demurrage",
+    "detention",
+    "storage",
+    "combined",
+];
+const CLOCK_START_EVENTS = [
+    "discharged",
+    "available",
+];
+/** The export clocks: fixed pairs, no start-event choice. */
+const EXPORT_CLOCKS = {
+    demurrage: ["gatedIn", "loaded"],
+    storage: ["gatedIn", "loaded"],
+    detention: ["emptyReleased", "gatedIn"],
+    combined: ["emptyReleased", "loaded"],
+};
+/**
+ * Pick the two events a charge's clock runs between.
+ *
+ * No regulation or industry standard fixes these events; the carriers' published tariffs agree
+ * on them (import: Maersk's terms, CMA CGM's general terms, Hapag-Lloyd, ACL; export: Maersk, CMA
+ * CGM, ACL), and DCSA's glossary draws the line they rest on: demurrage is charged while the
+ * container is inside the terminal or depot, detention while it is outside, and storage is the
+ * charge for the terminal's space, paid to the terminal or to the carrier on its behalf. Export
+ * storage (`gatedIn` → `loaded`) follows from that storage definition; no tariff read quotes it.
+ * The merged clock runs demurrage and detention as one period, a named tariff product at Maersk
+ * ("Combined"), CMA CGM ("merged") and MSC. `demurrageClock` selects the pair for the charge and
+ * direction asked for, so the wrong pair can never reach `chargeableDays`.
+ *
+ * | scope | import | export |
+ * | --- | --- | --- |
+ * | `demurrage`, `storage` | `startEvent` → `gatedOut` | `gatedIn` → `loaded` |
+ * | `detention` | `gatedOut` → `emptyReturned` | `emptyReleased` → `gatedIn` |
+ * | `combined` | `startEvent` → `emptyReturned` | `emptyReleased` → `loaded` |
+ *
+ * - **`direction` has no default.** The same scope name selects different events on the import and
+ *   export legs, and guessing it from the events present would be a silent guess.
+ * - **`startEvent` is import only**: `"discharged"` by default, the classic definition, or
+ *   `"available"` for tariffs that start at the availability date. It is not read for detention
+ *   or export, so one options object can serve every scope on a leg. A tariff that starts at
+ *   customs release (Hapag-Lloyd Japan) or ends export demurrage at the cut-off or the scheduled
+ *   sailing passes that instant as the event's `at`; GMT does not invent an event for one tariff.
+ * - Events may be in any order, and every one must be `{ type, at }` with a known type and a
+ *   valid instant, used or not, with no holes in the array: a list with a bad entry is a bad list.
+ * - The result is an `Interval`, half-open `[start, end)`, in the caller's own strings, and feeds
+ *   `chargeableDays(start, end, …)` directly.
+ * - Some tariffs differ in words, not events: MSC USA calls the in-terminal container charge
+ *   "detention" and the out-of-terminal one "per diem". GMT's scope names follow the global usage.
+ * - Returns `null` when `events` is not an array or holds an invalid event or a hole, `scope`,
+ *   `direction` or `startEvent` is unknown, `options` is not an object, a required event is
+ *   missing or occurs more than once (a container discharged twice is a data error, not a choice),
+ *   or the end event precedes the start event.
+ *
+ * @param events the container's events, `{ type, at }`, `type` one of discharged, available, gatedOut, emptyReturned, emptyReleased, gatedIn, loaded
+ * @param scope "demurrage" | "detention" | "storage" | "combined"
+ * @param options { direction: "import" | "export", startEvent?: "discharged" | "available" }
+ * @returns { start, end } of the requested clock, or null on invalid input
+ *
+ * @example demurrageClock([{ 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" }], "demurrage", { direction: "import" }) / { start: "2024-06-14T19:00:00Z", end: "2024-06-20T14:30:00Z" }
+ * @example demurrageClock([{ 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" }], "detention", { direction: "import" }) / { start: "2024-06-20T14:30:00Z", end: "2024-06-27T09:00:00Z" } (gate-out to empty return, not discharge)
+ * @example demurrageClock([{ 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" }], "combined", { direction: "import" }) / { start: "2024-06-14T19:00:00Z", end: "2024-06-27T09:00:00Z" } (merged: discharge to empty return)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "available", at: "2024-06-15T12:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage", { direction: "import", startEvent: "available" }) // { start: "2024-06-15T12:00:00Z", end: "2024-06-20T14:30:00Z" }
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "storage", { direction: "import" }) / { start: "2024-06-14T19:00:00Z", end: "2024-06-20T14:30:00Z" }
+ * @example demurrageClock([{ type: "emptyReleased", at: "2024-07-01T08:00:00Z" }, { type: "gatedIn", at: "2024-07-05T16:00:00Z" }, { type: "loaded", at: "2024-07-09T03:00:00Z" }], "demurrage", { direction: "export" }) // { start: "2024-07-05T16:00:00Z", end: "2024-07-09T03:00:00Z" } (gate-in full to loaded on board)
+ * @example demurrageClock([{ type: "emptyReleased", at: "2024-07-01T08:00:00Z" }, { type: "gatedIn", at: "2024-07-05T16:00:00Z" }, { type: "loaded", at: "2024-07-09T03:00:00Z" }], "detention", { direction: "export" }) // { start: "2024-07-01T08:00:00Z", end: "2024-07-05T16:00:00Z" } (empty picked up to gate-in full)
+ * @example demurrageClock([{ type: "emptyReleased", at: "2024-07-01T08:00:00Z" }, { type: "gatedIn", at: "2024-07-05T16:00:00Z" }, { type: "loaded", at: "2024-07-09T03:00:00Z" }], "combined", { direction: "export" }) // { start: "2024-07-01T08:00:00Z", end: "2024-07-09T03:00:00Z" }
+ * @example demurrageClock([{ type: "gatedOut", at: "2024-06-20T10:30:00-04:00[America/New_York]" }, { type: "emptyReturned", at: "2024-06-27T09:00:00Z" }], "detention", { direction: "import", startEvent: "available" }) // { start: "2024-06-20T10:30:00-04:00[America/New_York]", end: "2024-06-27T09:00:00Z" } (startEvent is not read for detention; strings are echoed as given)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage") // null (direction has no default)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage", { direction: "import", startEvent: "available" }) // null (no availability event)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }], "demurrage", { direction: "import" }) // null (still in the terminal: no gate-out)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "discharged", at: "2024-06-15T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage", { direction: "import" }) // null (discharged twice)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-21T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage", { direction: "import" }) // null (gate-out before discharge)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "laytime", { direction: "import" }) // null (not a clock this function selects)
+ */
+export function demurrageClock(events, scope, options) {
+    try {
+        return selectClock(events, scope, options);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}
+/** `demurrageClock` without the guard; every read of its arguments happens here. */
+function selectClock(events, scope, options) {
+    if (!Array.isArray(events) ||
+        !CLOCK_SCOPES.includes(scope) ||
+        !isObject(options)) {
+        return null;
+    }
+    const { direction } = options;
+    if (direction !== "import" && direction !== "export") {
+        return null;
+    }
+    // An explicit `undefined` is an omission (TC39 GetOption); `null` is a value, and not a valid one.
+    const startEvent = options.startEvent === undefined ? "discharged" : options.startEvent;
+    if (!CLOCK_START_EVENTS.includes(startEvent)) {
+        return null;
+    }
+    // `Array.from` turns a hole into `undefined`, which the check rejects; `every` would skip it.
+    const list = Array.from(events);
+    const wellFormed = list.every((event) => isObject(event) &&
+        CLOCK_EVENT_TYPES.includes(event.type) &&
+        typeof event.at === "string" &&
+        isValidInstant(event.at));
+    if (!wellFormed) {
+        return null;
+    }
+    const [startType, endType] = direction === "export"
+        ? EXPORT_CLOCKS[scope]
+        : scope === "detention"
+            ? ["gatedOut", "emptyReturned"]
+            : [startEvent, scope === "combined" ? "emptyReturned" : "gatedOut"];
+    const only = (type) => {
+        const matches = list.filter((event) => event.type === type);
+        return matches.length === 1 ? matches[0].at : null;
+    };
+    const start = only(startType);
+    const end = only(endType);
+    if (start === null || end === null) {
+        return null;
+    }
+    return Temporal.Instant.compare(Temporal.Instant.from(start), Temporal.Instant.from(end)) > 0
+        ? null
+        : { start, end };
+}