@northguild/gmt 1.16.0 → 1.17.0

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

@@ -0,0 +1,66 @@
+import type { FreeTimeOptions } from "../../types/index.js";
+/** What `freeTimeExpiry` returns: the free-time window as local dates, and the instant it ends. */
+export interface FreeTime {
+    /** Free day one, as a local date in the counting zone. */
+    freeTimeStart: string;
+    /** The last free day, as a local date in the counting zone. */
+    lastFreeDay: string;
+    /** The instant free time ends: the start of the local day after `lastFreeDay`, as a UTC instant. */
+    expiresAt: string;
+}
+/**
+ * Lay out a container's free time from the instant its clock started, and say when it ends.
+ *
+ * Free time is the money calculation in container logistics, and none of its terms is a fact
+ * about the port: the number of free days, whether the day of discharge is free day one, and
+ * whether weekends count are all set by the carrier's tariff or the service contract. So every
+ * term is a parameter. No regulation or industry standard fixes how free time is counted (DCSA types only its unit: calendar days, working days, hours or day of discharge; GMT counts
+ * days); the result is the window every tariff states, and what an invoice can print about it:
+ * the free time allowed and the dates it starts and ends.
+ *
+ * - **Days are the terminal's local days.** `clockStart` is an instant (`Z`, an offset, or a
+ *   bracketed zone, of which only the instant is read); its local date in `options.timeZone` is
+ *   the event day. A container discharged at 23:00 has used a free day by 00:01 under
+ *   `firstDay: "eventDay"`. Day boundaries are the zone's real ones, as `floorToZone` and
+ *   `dwellTime` find them: a 23- or 25-hour day is one day, a date the zone deleted is never a
+ *   free day, and a fall-back that re-enters an earlier date never moves the count backwards.
+ * - **`firstDay` has no default.** `"eventDay"` makes the event day free day one; `"nextDay"`
+ *   starts free time on the following counted day. The two differ by exactly one day of charges,
+ *   and a silent default here is a wrong invoice, so omitting it returns `null`.
+ * - **`basis` decides which days count.** `"calendar"` counts every local day, so a weekend
+ *   burns two free days while the terminal is shut. `"working"` counts only the working days of
+ *   `options.calendar` (its weekend and holidays; `calendar.timeZone` is not read), and is
+ *   required to have one: a working-day count without a calendar is a guess and returns `null`.
+ *   Under `"working"` a Saturday discharge starts free time on Monday under either `firstDay`.
+ *   A tariff counting "calendar days excluding bank holidays" (Hapag-Lloyd Japan, MSC Vietnam) is
+ *   `"working"` with an empty `weekend`. How days after expiry are charged is a separate term;
+ *   see `chargeableDays`'s `chargeBasis`.
+ * - **`expiresAt` is half-open.** It is the first instant of the local day after `lastFreeDay`,
+ *   as a UTC instant. A gate-out at exactly `expiresAt` is not a chargeable day; see
+ *   `chargeableDays`. Under `"working"` it can fall on a weekend, which is then simply not
+ *   chargeable.
+ * - `freeDays` is a whole number of at least `1`: with no free days there is no last free day
+ *   to name, and `chargeableDays` accepts `0` for that tariff.
+ * - Returns `null` when `clockStart` is not an instant, `freeDays` is not a whole number of at
+ *   least `1`, `options` is not an object, `basis` or `firstDay` is missing or unknown,
+ *   `timeZone` is invalid, `basis` is `"working"` without a valid `BusinessCalendar`, or the walk
+ *   would pass 10,000 local days.
+ *
+ * @param clockStart ISO 8601 instant string of the event that starts the clock (discharge, availability or gate-out)
+ * @param freeDays whole number of free days the tariff allows, at least 1
+ * @param options { basis: "calendar" | "working", timeZone: string, firstDay: "eventDay" | "nextDay", calendar?: BusinessCalendar }
+ * @returns the free-time start and last free day as local dates, and the expiry instant, or null on invalid input
+ *
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-16", expiresAt: "2024-06-17T04:00:00Z" } (a Friday discharge: the weekend is consumed)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "nextDay" }) // { freeTimeStart: "2024-06-15", lastFreeDay: "2024-06-17", expiresAt: "2024-06-18T04:00:00Z" } (the same tariff read the other way: one more day)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (Friday, Monday, Tuesday: the weekend does not count)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-17"], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-19", expiresAt: "2024-06-20T04:00:00Z" } (a terminal holiday on the Monday moves expiry a day)
+ * @example freeTimeExpiry("2024-06-15T14:00:00Z", 2, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-17", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (a Saturday discharge: free time starts Monday)
+ * @example freeTimeExpiry("2024-06-15T03:00:00Z", 1, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-14", expiresAt: "2024-06-15T04:00:00Z" } (23:00 local on the 14th: the free day is over an hour later)
+ * @example freeTimeExpiry("2024-09-07T15:00:00Z", 1, { basis: "calendar", timeZone: "America/Santiago", firstDay: "eventDay" }) // { freeTimeStart: "2024-09-07", lastFreeDay: "2024-09-07", expiresAt: "2024-09-08T04:00:00Z" } (Santiago skipped midnight on the 8th, so the day starts at 01:00)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York" }) // null (firstDay has no default)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay" }) // null (a working-day count needs the terminal's calendar)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 0, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no free days means no last free day)
+ * @example freeTimeExpiry("2024-06-14T19:00:00", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no offset: not an instant)
+ */
+export declare function freeTimeExpiry(clockStart: string, freeDays: number, options: FreeTimeOptions): FreeTime | null;

package/dist/intermodal/calculate/freeTimeExpiry.js

@@ -0,0 +1,82 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { parseFreeDays, parseFreeTimeTerms, walkFreeTime, } from "../../internal/index.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+/**
+ * Lay out a container's free time from the instant its clock started, and say when it ends.
+ *
+ * Free time is the money calculation in container logistics, and none of its terms is a fact
+ * about the port: the number of free days, whether the day of discharge is free day one, and
+ * whether weekends count are all set by the carrier's tariff or the service contract. So every
+ * term is a parameter. No regulation or industry standard fixes how free time is counted (DCSA types only its unit: calendar days, working days, hours or day of discharge; GMT counts
+ * days); the result is the window every tariff states, and what an invoice can print about it:
+ * the free time allowed and the dates it starts and ends.
+ *
+ * - **Days are the terminal's local days.** `clockStart` is an instant (`Z`, an offset, or a
+ *   bracketed zone, of which only the instant is read); its local date in `options.timeZone` is
+ *   the event day. A container discharged at 23:00 has used a free day by 00:01 under
+ *   `firstDay: "eventDay"`. Day boundaries are the zone's real ones, as `floorToZone` and
+ *   `dwellTime` find them: a 23- or 25-hour day is one day, a date the zone deleted is never a
+ *   free day, and a fall-back that re-enters an earlier date never moves the count backwards.
+ * - **`firstDay` has no default.** `"eventDay"` makes the event day free day one; `"nextDay"`
+ *   starts free time on the following counted day. The two differ by exactly one day of charges,
+ *   and a silent default here is a wrong invoice, so omitting it returns `null`.
+ * - **`basis` decides which days count.** `"calendar"` counts every local day, so a weekend
+ *   burns two free days while the terminal is shut. `"working"` counts only the working days of
+ *   `options.calendar` (its weekend and holidays; `calendar.timeZone` is not read), and is
+ *   required to have one: a working-day count without a calendar is a guess and returns `null`.
+ *   Under `"working"` a Saturday discharge starts free time on Monday under either `firstDay`.
+ *   A tariff counting "calendar days excluding bank holidays" (Hapag-Lloyd Japan, MSC Vietnam) is
+ *   `"working"` with an empty `weekend`. How days after expiry are charged is a separate term;
+ *   see `chargeableDays`'s `chargeBasis`.
+ * - **`expiresAt` is half-open.** It is the first instant of the local day after `lastFreeDay`,
+ *   as a UTC instant. A gate-out at exactly `expiresAt` is not a chargeable day; see
+ *   `chargeableDays`. Under `"working"` it can fall on a weekend, which is then simply not
+ *   chargeable.
+ * - `freeDays` is a whole number of at least `1`: with no free days there is no last free day
+ *   to name, and `chargeableDays` accepts `0` for that tariff.
+ * - Returns `null` when `clockStart` is not an instant, `freeDays` is not a whole number of at
+ *   least `1`, `options` is not an object, `basis` or `firstDay` is missing or unknown,
+ *   `timeZone` is invalid, `basis` is `"working"` without a valid `BusinessCalendar`, or the walk
+ *   would pass 10,000 local days.
+ *
+ * @param clockStart ISO 8601 instant string of the event that starts the clock (discharge, availability or gate-out)
+ * @param freeDays whole number of free days the tariff allows, at least 1
+ * @param options { basis: "calendar" | "working", timeZone: string, firstDay: "eventDay" | "nextDay", calendar?: BusinessCalendar }
+ * @returns the free-time start and last free day as local dates, and the expiry instant, or null on invalid input
+ *
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-16", expiresAt: "2024-06-17T04:00:00Z" } (a Friday discharge: the weekend is consumed)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "nextDay" }) // { freeTimeStart: "2024-06-15", lastFreeDay: "2024-06-17", expiresAt: "2024-06-18T04:00:00Z" } (the same tariff read the other way: one more day)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (Friday, Monday, Tuesday: the weekend does not count)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-17"], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-19", expiresAt: "2024-06-20T04:00:00Z" } (a terminal holiday on the Monday moves expiry a day)
+ * @example freeTimeExpiry("2024-06-15T14:00:00Z", 2, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-17", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (a Saturday discharge: free time starts Monday)
+ * @example freeTimeExpiry("2024-06-15T03:00:00Z", 1, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-14", expiresAt: "2024-06-15T04:00:00Z" } (23:00 local on the 14th: the free day is over an hour later)
+ * @example freeTimeExpiry("2024-09-07T15:00:00Z", 1, { basis: "calendar", timeZone: "America/Santiago", firstDay: "eventDay" }) // { freeTimeStart: "2024-09-07", lastFreeDay: "2024-09-07", expiresAt: "2024-09-08T04:00:00Z" } (Santiago skipped midnight on the 8th, so the day starts at 01:00)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York" }) // null (firstDay has no default)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay" }) // null (a working-day count needs the terminal's calendar)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 0, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no free days means no last free day)
+ * @example freeTimeExpiry("2024-06-14T19:00:00", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no offset: not an instant)
+ */
+export function freeTimeExpiry(clockStart, freeDays, options) {
+    try {
+        const terms = parseFreeTimeTerms(options);
+        const allowed = parseFreeDays(freeDays, 1);
+        if (!isValidInstant(clockStart) || terms === null || allowed === null) {
+            return null;
+        }
+        const start = Temporal.Instant.from(clockStart).toZonedDateTimeISO(terms.timeZone);
+        const ledger = walkFreeTime(start, allowed, terms);
+        if (ledger === null) {
+            return null;
+        }
+        return {
+            freeTimeStart: ledger.free[0].date,
+            lastFreeDay: ledger.free[allowed - 1].date,
+            expiresAt: ledger.expiresAt.toInstant().toString(),
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,4 @@
+export * from "./billingTimeline.js";
+export * from "./chargeableDays.js";
+export * from "./demurrageClock.js";
+export * from "./freeTimeExpiry.js";

package/dist/intermodal/calculate/index.js

@@ -0,0 +1,4 @@
+export * from "./billingTimeline.js";
+export * from "./chargeableDays.js";
+export * from "./demurrageClock.js";
+export * from "./freeTimeExpiry.js";

package/dist/intermodal/index.d.ts

@@ -0,0 +1,2 @@
+export * from "@js-temporal/polyfill";
+export * from "./calculate/index.js";

package/dist/intermodal/index.js

@@ -0,0 +1,3 @@
+// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
+export * from "@js-temporal/polyfill";
+export * from "./calculate/index.js";

package/dist/internal/freeTimeLedger.d.ts

@@ -0,0 +1,93 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { type ResolvedBusinessCalendar } from "./businessCalendar.js";
+/**
+ * Local days a free-time walk may visit before giving up: the same cap as `bucketRange`. A
+ * valid business calendar leaves at least one working day a week, so a working-day count needs
+ * at most about seven local days per free or chargeable day. A walk that runs out answers with
+ * the sentinel, never a partial ledger.
+ */
+export declare const MAX_WALKED_DAYS = 10000;
+/**
+ * The tariff terms reduced to what the walk reads. `calendar` is the working-day calendar free
+ * days are counted against, `null` on the calendar basis; `chargeCalendar` is the one charged days
+ * are counted against, `null` when every local day after expiry is charged.
+ */
+export type FreeTimeTerms = {
+    timeZone: string;
+    firstDay: "eventDay" | "nextDay";
+    calendar: ResolvedBusinessCalendar | null;
+    chargeCalendar: ResolvedBusinessCalendar | null;
+};
+/**
+ * Read a `FreeTimeOptions` bag, or `null` when it is not one: a non-object, an unknown `basis`
+ * or `firstDay`, a missing `firstDay` (no default: the two conventions differ by a day of
+ * charges), an invalid `timeZone`, or a `"working"` basis without a valid `BusinessCalendar`.
+ * The `calendar` is read only when a basis that needs it is `"working"`.
+ *
+ * With `readChargeBasis`, `chargeBasis` is required too, and has no default for the same reason:
+ * where free time is in working days, tariffs mostly charge every calendar day after it, but some
+ * tariffs charge working days only, and the two differ by every closed day after expiry.
+ */
+export declare function parseFreeTimeTerms(options: unknown, readChargeBasis?: boolean): FreeTimeTerms | null;
+/** A whole number of free days no smaller than `minimum`, or `null`. */
+export declare function parseFreeDays(freeDays: unknown, minimum: 0 | 1): number | null;
+/**
+ * Read a `tiers` option: omitted means no bands, otherwise a strictly ascending list of positive
+ * safe whole chargeable-day ordinals, each the last day of its band, with no holes. Anything
+ * else is `null`.
+ */
+export declare function parseTiers(tiers: unknown): number[] | null;
+/**
+ * Split `chargeable` days into the bands `tiers` describes: `[5, 10]` is days 1–5, 6–10 and 11
+ * onward. Every band is listed, an empty one with `days: 0`, so a caller's rate table lines up
+ * by index; the last band is always open (`to: null`).
+ */
+export declare function bandsByTier(tiers: number[], chargeable: number): {
+    from: number;
+    to: number | null;
+    days: number;
+}[];
+/** One local date of the terminal: its first instant, and its ISO label. */
+export interface LedgerDay {
+    start: Temporal.ZonedDateTime;
+    date: string;
+    /**
+     * True when the date began before the first instant Temporal represents, so `start` is the
+     * clock start standing in for it. Such a start is never output: it can only anchor the walk.
+     */
+    clamped?: boolean;
+}
+/** What `walkFreeTime` returns: the free days, the expiry, and what the dwell used and owes. */
+export interface FreeTimeLedger {
+    /** The free days in order, exactly `freeDays` of them. */
+    free: LedgerDay[];
+    /** The first instant of the local day after the last free day; with no free days, of day one. */
+    expiresAt: Temporal.ZonedDateTime;
+    /** Free days the half-open dwell `[clockStart, clockEnd)` touched; `0` with no `clockEnd`. */
+    used: number;
+    /** Counted days from `expiresAt` that the dwell touched, in order; empty with no `clockEnd`. */
+    charged: LedgerDay[];
+}
+/**
+ * Walk the terminal's real local days from the clock start and lay out free time and charges.
+ *
+ * Each day is a bucket `zonedUnitStart` / `nextZonedBucketStart` returns for `"day"`, the same
+ * boundaries `floorToZone` and `bucketRange` use, so a 23- or 25-hour day is one day, a date the
+ * zone deleted is never visited, and a date the clock falls back into is one day. Free days and
+ * charged days are counted against their own terms: on a working basis a weekend day or holiday is
+ * visited but not counted; on a calendar basis every day counts. The day of the event is neither
+ * free nor charged under `"nextDay"`.
+ *
+ * - Free days are the first `freeDays` days counted on `calendar`. `expiresAt` is the start of the
+ *   day after the last of them, whether or not that day counts; with `freeDays` of `0` it is the
+ *   start of the first counted day.
+ * - With a `clockEnd`, the dwell `[clockStart, clockEnd)` is half-open: a day is touched when it
+ *   starts before `clockEnd`, and a zero-length dwell touches the day it sits on, as `dwellTime`
+ *   counts. `used` is the free days touched; `charged` the days from `expiresAt` touched that count
+ *   on `chargeCalendar`.
+ * - An event day that began before the first representable instant is still walked from the
+ *   clock start; only an expiry that would be that unrepresentable start is refused.
+ * - Returns `null` when the walk would visit more than `MAX_WALKED_DAYS` local days, when a day
+ *   boundary cannot be found, or when the expiry lies outside the representable range.
+ */
+export declare function walkFreeTime(clockStart: Temporal.ZonedDateTime, freeDays: number, terms: FreeTimeTerms, clockEnd?: Temporal.ZonedDateTime): FreeTimeLedger | null;

package/dist/internal/freeTimeLedger.js

@@ -0,0 +1,262 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTimeZone } from "../zoned/validate/isValidTimeZone.js";
+import { isBusinessDate, parseBusinessCalendar, } from "./businessCalendar.js";
+import { isObject } from "./isObject.js";
+import { nextZonedBucketStart, zonedUnitStart } from "./zonedBucket.js";
+/**
+ * Local days a free-time walk may visit before giving up: the same cap as `bucketRange`. A
+ * valid business calendar leaves at least one working day a week, so a working-day count needs
+ * at most about seven local days per free or chargeable day. A walk that runs out answers with
+ * the sentinel, never a partial ledger.
+ */
+export const MAX_WALKED_DAYS = 10_000;
+/**
+ * Buckets stepped over while looking for a later date. A fall-back that re-enters the previous
+ * date (`America/Goose_Bay`, 2010-11-07 00:01 back into the 6th) opens a one-minute 7 November
+ * bucket, then a 6 November one, then 7 November again: two buckets in a row whose date is not
+ * later than the day being left. One transition can do no more than that, so eight is a
+ * generous bound.
+ */
+const MAX_REVISITED_BUCKETS = 8;
+/** `parseFreeTimeTerms` without the guard; every read of `options` happens here. */
+function readFreeTimeTerms(options, readChargeBasis = false) {
+    if (!isObject(options)) {
+        return null;
+    }
+    const { basis, chargeBasis, firstDay, timeZone, calendar } = options;
+    const isBasis = (value) => value === "calendar" || value === "working";
+    if (!isBasis(basis)) {
+        return null;
+    }
+    if (readChargeBasis && !isBasis(chargeBasis)) {
+        return null;
+    }
+    if (firstDay !== "eventDay" && firstDay !== "nextDay") {
+        return null;
+    }
+    if (typeof timeZone !== "string" || !isValidTimeZone(timeZone)) {
+        return null;
+    }
+    const needsCalendar = basis === "working" || (readChargeBasis && chargeBasis === "working");
+    const resolved = needsCalendar ? parseBusinessCalendar(calendar) : null;
+    if (needsCalendar && resolved === null) {
+        return null;
+    }
+    return {
+        timeZone,
+        firstDay,
+        calendar: basis === "working" ? resolved : null,
+        chargeCalendar: readChargeBasis && chargeBasis === "working" ? resolved : null,
+    };
+}
+/**
+ * Read a `FreeTimeOptions` bag, or `null` when it is not one: a non-object, an unknown `basis`
+ * or `firstDay`, a missing `firstDay` (no default: the two conventions differ by a day of
+ * charges), an invalid `timeZone`, or a `"working"` basis without a valid `BusinessCalendar`.
+ * The `calendar` is read only when a basis that needs it is `"working"`.
+ *
+ * With `readChargeBasis`, `chargeBasis` is required too, and has no default for the same reason:
+ * where free time is in working days, tariffs mostly charge every calendar day after it, but some
+ * tariffs charge working days only, and the two differ by every closed day after expiry.
+ */
+export function parseFreeTimeTerms(options, readChargeBasis = false) {
+    try {
+        return readFreeTimeTerms(options, readChargeBasis);
+    }
+    catch {
+        // Never throws (Core Rule 3): a Proxy or getter that throws on access is invalid input.
+        return null;
+    }
+}
+/** A whole number of free days no smaller than `minimum`, or `null`. */
+export function parseFreeDays(freeDays, minimum) {
+    return typeof freeDays === "number" &&
+        Number.isSafeInteger(freeDays) &&
+        freeDays >= minimum
+        ? freeDays
+        : null;
+}
+/**
+ * Read a `tiers` option: omitted means no bands, otherwise a strictly ascending list of positive
+ * safe whole chargeable-day ordinals, each the last day of its band, with no holes. Anything
+ * else is `null`.
+ */
+export function parseTiers(tiers) {
+    if (tiers === undefined) {
+        return [];
+    }
+    if (!Array.isArray(tiers)) {
+        return null;
+    }
+    // `Array.from` fills holes with `undefined`, which the check below rejects; `every` alone
+    // would skip them and let `[5, , ]` through to a `NaN` band.
+    const items = Array.from(tiers);
+    const ascending = items.every((tier, index) => typeof tier === "number" &&
+        Number.isSafeInteger(tier) &&
+        tier >= 1 &&
+        (index === 0 || tier > items[index - 1]));
+    return ascending ? items : null;
+}
+/**
+ * Split `chargeable` days into the bands `tiers` describes: `[5, 10]` is days 1–5, 6–10 and 11
+ * onward. Every band is listed, an empty one with `days: 0`, so a caller's rate table lines up
+ * by index; the last band is always open (`to: null`).
+ */
+export function bandsByTier(tiers, chargeable) {
+    const bands = [];
+    let from = 1;
+    for (const to of tiers) {
+        bands.push({
+            from,
+            to,
+            days: Math.max(0, Math.min(chargeable, to) - from + 1),
+        });
+        from = to + 1;
+    }
+    bands.push({ from, to: null, days: Math.max(0, chargeable - from + 1) });
+    return bands;
+}
+/** The local day holding `zoned`, or `null` when its start cannot be found. */
+function localDayOf(zoned) {
+    let start;
+    try {
+        start = zonedUnitStart(zoned, "day");
+    }
+    catch (error) {
+        if (!(error instanceof RangeError))
+            throw error;
+        // The event day began before Temporal's first instant (-271821-04-20T00:00Z in a zone west
+        // of UTC). Its date is still known, and every later day boundary is representable, so the
+        // clock start anchors the walk in its place.
+        return {
+            start: zoned,
+            date: zoned.toPlainDate().toString(),
+            clamped: true,
+        };
+    }
+    return start === null
+        ? null
+        : { start, date: start.toPlainDate().toString() };
+}
+/**
+ * The first local day after `day` whose date is later than `day`'s. A bucket that re-enters an
+ * earlier or equal date is folded into the day already laid out: a clock that starts in the
+ * one-minute first pass of Goose Bay's 7 November must not free or charge the 6th, and
+ * `countZonedLocalDates` counts a re-entered date once. `undefined` when the next day starts
+ * past the last representable instant, `null` when the walk gives up.
+ */
+function nextLocalDay(day) {
+    const current = day.start.toPlainDate();
+    let cursor = day.start;
+    for (let i = 0; i < MAX_REVISITED_BUCKETS; i++) {
+        let next;
+        try {
+            next = nextZonedBucketStart(cursor, "day");
+        }
+        catch (error) {
+            if (error instanceof RangeError)
+                return undefined;
+            throw error;
+        }
+        if (next === null) {
+            return null;
+        }
+        const date = next.toPlainDate();
+        if (Temporal.PlainDate.compare(date, current) > 0) {
+            return { start: next, date: date.toString() };
+        }
+        cursor = next;
+    }
+    return null;
+}
+/**
+ * Walk the terminal's real local days from the clock start and lay out free time and charges.
+ *
+ * Each day is a bucket `zonedUnitStart` / `nextZonedBucketStart` returns for `"day"`, the same
+ * boundaries `floorToZone` and `bucketRange` use, so a 23- or 25-hour day is one day, a date the
+ * zone deleted is never visited, and a date the clock falls back into is one day. Free days and
+ * charged days are counted against their own terms: on a working basis a weekend day or holiday is
+ * visited but not counted; on a calendar basis every day counts. The day of the event is neither
+ * free nor charged under `"nextDay"`.
+ *
+ * - Free days are the first `freeDays` days counted on `calendar`. `expiresAt` is the start of the
+ *   day after the last of them, whether or not that day counts; with `freeDays` of `0` it is the
+ *   start of the first counted day.
+ * - With a `clockEnd`, the dwell `[clockStart, clockEnd)` is half-open: a day is touched when it
+ *   starts before `clockEnd`, and a zero-length dwell touches the day it sits on, as `dwellTime`
+ *   counts. `used` is the free days touched; `charged` the days from `expiresAt` touched that count
+ *   on `chargeCalendar`.
+ * - An event day that began before the first representable instant is still walked from the
+ *   clock start; only an expiry that would be that unrepresentable start is refused.
+ * - Returns `null` when the walk would visit more than `MAX_WALKED_DAYS` local days, when a day
+ *   boundary cannot be found, or when the expiry lies outside the representable range.
+ */
+export function walkFreeTime(clockStart, freeDays, terms, clockEnd) {
+    // The dwell's last instant, one nanosecond before the exit; a zero-length dwell is its own point.
+    const last = clockEnd === undefined
+        ? undefined
+        : Temporal.ZonedDateTime.compare(clockStart, clockEnd) < 0
+            ? clockEnd.subtract({ nanoseconds: 1 })
+            : clockEnd;
+    const touched = (day) => last !== undefined && Temporal.ZonedDateTime.compare(day.start, last) <= 0;
+    const counts = (day) => terms.calendar === null ||
+        isBusinessDate(day.start.toPlainDate(), terms.calendar);
+    const charges = (day) => terms.chargeCalendar === null ||
+        isBusinessDate(day.start.toPlainDate(), terms.chargeCalendar);
+    const free = [];
+    const charged = [];
+    let used = 0;
+    let expiresAt = null;
+    let expiryPending = false;
+    let skipEventDay = terms.firstDay === "nextDay";
+    let day = localDayOf(clockStart);
+    if (day === null) {
+        return null;
+    }
+    // One more visit than the cap: the day after the last touched one is what ends the walk.
+    for (let i = 0; i <= MAX_WALKED_DAYS; i++) {
+        const eventDaySkipped = skipEventDay;
+        const counted = !skipEventDay && counts(day);
+        skipEventDay = false;
+        if (expiryPending) {
+            expiresAt = day.start;
+            expiryPending = false;
+        }
+        else if (expiresAt === null && counted) {
+            if (freeDays === 0) {
+                // With no free time the expiry is day one's start, which must be a real instant.
+                if (day.clamped)
+                    return null;
+                expiresAt = day.start;
+            }
+            else {
+                free.push(day);
+                if (touched(day))
+                    used++;
+                expiryPending = free.length === freeDays;
+            }
+        }
+        if (expiresAt !== null) {
+            // Free time has ended; with no clock end there is nothing more to lay out.
+            if (last === undefined) {
+                return { free, expiresAt, used, charged };
+            }
+            if (Temporal.ZonedDateTime.compare(day.start, last) > 0) {
+                return { free, expiresAt, used, charged };
+            }
+            // The day of the event under `nextDay` is never charged: free time has not started on it.
+            if (!eventDaySkipped && charges(day))
+                charged.push(day);
+        }
+        const next = nextLocalDay(day);
+        if (next === undefined) {
+            // No representable day follows: free time can still be laid out only if it has ended.
+            return expiresAt === null ? null : { free, expiresAt, used, charged };
+        }
+        if (next === null) {
+            return null;
+        }
+        day = next;
+    }
+    return null;
+}

package/dist/internal/index.d.ts

@@ -15,8 +15,9 @@ export { dateCycleFieldBounds } from "./dateCycleFieldBounds.js";
 export { timeCycleFieldBounds } from "./timeCycleFieldBounds.js";
 export { durationUntilString } from "./durationUntilString.js";
 export { formatDateInCalendar } from "./formatDateInCalendar.js";
+export { bandsByTier, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "./freeTimeLedger.js";
 export { halfOpenAbuts, halfOpenContainsPoint, halfOpenContainsSpan, halfOpenDifference, halfOpenIntersection, halfOpenMerge, halfOpenOverlap, halfOpenUnion, halfOpenXor, } from "./halfOpenIntervals.js";
-export { isoStringBody } from "./isoStringBody.js";
+export { EXTENDED_UTC_OFFSET, isoStringBody, TIME_ZONE_ANNOTATION, } from "./isoStringBody.js";
 export { formatHourDuration } from "./hourDurationString.js";
 export { canonicalInstantIntervals } from "./instantIntervalText.js";
 export { parseInstantNanoseconds } from "./instantNanoseconds.js";
@@ -47,7 +48,8 @@ export { parseUnixEpochInterval, parseUnixEpochIntervalList, parseUnixEpochInter
 export { tileByUnit } from "./splitStep.js";
 export { countZonedBuckets, nextZonedBucketStart, type WeekStartDay, zonedUnitEnd, zonedUnitStart, } from "./zonedBucket.js";
 export { countZonedLocalDates } from "./zonedLocalDates.js";
-export { zonedDateTimeFrom } from "./zonedWallClock.js";
+export { utcOffsetStringNanoseconds, zonedDateTimeFrom, } from "./zonedWallClock.js";
+export { wallClockAtOffset } from "./wallClockAtOffset.js";
 export { durationCompare, durationRound, durationTotal, isCalendarDifferenceAcrossZones, plainUntilWithRounding, zonedUntil, } from "./zonedWallClockDifference.js";
 export { addToZoned, addToZonedDisambiguated, plainToZoned, roundZonedDateTime, subtractFromZoned, withZonedFields, zonedHoursInDay, zonedNextTransition, zonedStartOfDay, } from "./zonedWallClockOperations.js";
 export { zonelessCalendarDate } from "./zonelessCalendarDate.js";

package/dist/internal/index.js

@@ -15,8 +15,9 @@ export { dateCycleFieldBounds } from "./dateCycleFieldBounds.js";
 export { timeCycleFieldBounds } from "./timeCycleFieldBounds.js";
 export { durationUntilString } from "./durationUntilString.js";
 export { formatDateInCalendar } from "./formatDateInCalendar.js";
+export { bandsByTier, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "./freeTimeLedger.js";
 export { halfOpenAbuts, halfOpenContainsPoint, halfOpenContainsSpan, halfOpenDifference, halfOpenIntersection, halfOpenMerge, halfOpenOverlap, halfOpenUnion, halfOpenXor, } from "./halfOpenIntervals.js";
-export { isoStringBody } from "./isoStringBody.js";
+export { EXTENDED_UTC_OFFSET, isoStringBody, TIME_ZONE_ANNOTATION, } from "./isoStringBody.js";
 export { formatHourDuration } from "./hourDurationString.js";
 export { canonicalInstantIntervals } from "./instantIntervalText.js";
 export { parseInstantNanoseconds } from "./instantNanoseconds.js";
@@ -47,7 +48,8 @@ export { parseUnixEpochInterval, parseUnixEpochIntervalList, parseUnixEpochInter
 export { tileByUnit } from "./splitStep.js";
 export { countZonedBuckets, nextZonedBucketStart, zonedUnitEnd, zonedUnitStart, } from "./zonedBucket.js";
 export { countZonedLocalDates } from "./zonedLocalDates.js";
-export { zonedDateTimeFrom } from "./zonedWallClock.js";
+export { utcOffsetStringNanoseconds, zonedDateTimeFrom, } from "./zonedWallClock.js";
+export { wallClockAtOffset } from "./wallClockAtOffset.js";
 export { durationCompare, durationRound, durationTotal, isCalendarDifferenceAcrossZones, plainUntilWithRounding, zonedUntil, } from "./zonedWallClockDifference.js";
 export { addToZoned, addToZonedDisambiguated, plainToZoned, roundZonedDateTime, subtractFromZoned, withZonedFields, zonedHoursInDay, zonedNextTransition, zonedStartOfDay, } from "./zonedWallClockOperations.js";
 export { zonelessCalendarDate } from "./zonelessCalendarDate.js";

package/dist/internal/isoStringBody.d.ts

@@ -17,6 +17,32 @@
  * @example isoStringBody("12:30") // "12:30"
  */
 export declare function isoStringBody(value: string): string;
+/**
+ * An ISO 8601 extended UTC offset, as RFC 3339 §5.6 `time-numoffset` writes it (`±HH:MM`), with
+ * the seconds and fraction Temporal's `UTCOffset` grammar adds (`±HH:MM:SS[.fraction]`, the
+ * fraction after either decimal sign, `.` or `,`, as `TemporalDecimalSeparator` allows). Hours
+ * 00–23. Basic (`-0400`) and hour-only (`-04`) offsets, which Temporal also reads, do not match.
+ *
+ * A regular-expression source with no anchors and no capture groups, so callers can embed it:
+ * GMT's one statement of the offset grammar its instant and zoned validators accept.
+ *
+ * @example new RegExp(`^${EXTENDED_UTC_OFFSET}$`).test("+05:30:00,5") // true
+ * @example new RegExp(`^${EXTENDED_UTC_OFFSET}$`).test("-0400") // false (basic format)
+ */
+export declare const EXTENDED_UTC_OFFSET = "[+-](?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:[.,]\\d{1,9})?)?";
+/**
+ * An RFC 9557 time-zone annotation: a bracket whose content has no `=` (§4.1 `time-zone`,
+ * against `suffix-tag`'s `key=value`), with an optional leading `!` marking it critical (§3.3).
+ * `[Europe/London]`, `[!+01:00]`; never `[u-ca=hebrew]` or `[!foo=bar]`. Every `key=value`
+ * bracket is a tagged annotation, which Temporal reads (or rejects) on its own.
+ *
+ * A regular-expression source with no anchors and no capture groups, so callers can embed or
+ * anchor it: GMT's one statement of "this bracket names a time zone".
+ *
+ * @example new RegExp(TIME_ZONE_ANNOTATION).test("2024-06-15T10:00:00Z[!Europe/London]") // true
+ * @example new RegExp(TIME_ZONE_ANNOTATION).test("2024-06-15T10:00:00Z[u-ca=gregory]") // false
+ */
+export declare const TIME_ZONE_ANNOTATION = "\\[!?[^\\]=]+\\]";
 /**
  * True when `value` is a string whose part before the first annotation is `zonedDateTimeBody`.
  * The shape gate every GMT zoned string input passes before `Temporal.ZonedDateTime.from`.

package/dist/internal/isoStringBody.js

@@ -26,10 +26,30 @@ export function isoStringBody(value) {
 }
 /**
  * An ISO 8601 extended UTC offset, as RFC 3339 §5.6 `time-numoffset` writes it (`±HH:MM`), with
- * the seconds and fraction Temporal's `UTCOffset` grammar adds (`±HH:MM:SS[.fraction]`). Hours
+ * the seconds and fraction Temporal's `UTCOffset` grammar adds (`±HH:MM:SS[.fraction]`, the
+ * fraction after either decimal sign, `.` or `,`, as `TemporalDecimalSeparator` allows). Hours
  * 00–23. Basic (`-0400`) and hour-only (`-04`) offsets, which Temporal also reads, do not match.
+ *
+ * A regular-expression source with no anchors and no capture groups, so callers can embed it:
+ * GMT's one statement of the offset grammar its instant and zoned validators accept.
+ *
+ * @example new RegExp(`^${EXTENDED_UTC_OFFSET}$`).test("+05:30:00,5") // true
+ * @example new RegExp(`^${EXTENDED_UTC_OFFSET}$`).test("-0400") // false (basic format)
+ */
+export const EXTENDED_UTC_OFFSET = "[+-](?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:[.,]\\d{1,9})?)?";
+/**
+ * An RFC 9557 time-zone annotation: a bracket whose content has no `=` (§4.1 `time-zone`,
+ * against `suffix-tag`'s `key=value`), with an optional leading `!` marking it critical (§3.3).
+ * `[Europe/London]`, `[!+01:00]`; never `[u-ca=hebrew]` or `[!foo=bar]`. Every `key=value`
+ * bracket is a tagged annotation, which Temporal reads (or rejects) on its own.
+ *
+ * A regular-expression source with no anchors and no capture groups, so callers can embed or
+ * anchor it: GMT's one statement of "this bracket names a time zone".
+ *
+ * @example new RegExp(TIME_ZONE_ANNOTATION).test("2024-06-15T10:00:00Z[!Europe/London]") // true
+ * @example new RegExp(TIME_ZONE_ANNOTATION).test("2024-06-15T10:00:00Z[u-ca=gregory]") // false
  */
-const EXTENDED_UTC_OFFSET = "[+-](?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:[.,]\\d{1,9})?)?";
+export const TIME_ZONE_ANNOTATION = "\\[!?[^\\]=]+\\]";
 /** `plainDateTime` without its anchors: `<date>T<time>` with an optional fraction. */
 const EXTENDED_DATE_TIME = plainDateTime.source.slice(1, -1);
 /**