@northguild/gmt 1.18.0 → 1.20.0

package/dist/internal/freeTimeLedger.d.ts

@@ -1,18 +1,16 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 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 = {
+    /**
+     * The counting zone as the caller wrote it: a time zone identifier or a stored UTC offset
+     * (`±HH:MM[:SS]`), so always readable by `zoneFrame`. The walk's zoned values are placed with
+     * `frameZoned` and turned back with `frameEpochNanoseconds` and `Temporal.Instant.fromEpochNanoseconds`.
+     */
     timeZone: string;
     firstDay: "eventDay" | "nextDay";
     calendar: ResolvedBusinessCalendar | null;
@@ -47,47 +45,42 @@ export declare function bandsByTier(tiers: number[], chargeable: 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;
+/**
+ * What a free-time walk returns, on epoch days (days from 1970-01-01, `epochDay.ts`) and epoch
+ * nanoseconds, so the dwell's length costs no Temporal work: callers format the few values they
+ * output.
+ */
+export interface FreeTimeLedger {
+    /** The first free day; `null` with no free days. */
+    firstFree: number | null;
+    /** The last free day; `null` with no free days. */
+    lastFree: number | null;
     /**
-     * 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.
+     * The first instant of the local day after the last free day (with no free days, of day one), in
+     * epoch nanoseconds. It includes the frame's shift, so it is the real instant.
      */
-    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;
+    expiresAtNs: bigint;
     /** 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[];
+    /** Counted days from `expiresAt` that the dwell touched, ascending; empty with no `clockEnd`. */
+    charged: number[];
 }
 /**
- * Walk the terminal's real local days from the clock start and lay out free time and charges.
+ * Lay out free time and charges from the clock start, in epoch days (see `FreeTimeLedger`).
  *
- * 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"`.
+ * The local days of the terminal are the dates from the event day on, each once, without a date
+ * the zone deleted. Free days are the first `freeDays` counted ones (every date on a calendar
+ * basis, a working day of `calendar` otherwise); `expiresAt` is the first instant of the visited
+ * date after the last of them, or with `freeDays` of `0` of the first counted one. With a
+ * `clockEnd` the half-open dwell `[clockStart, clockEnd)` touches a date when it starts before
+ * `clockEnd`, and a zero-length dwell touches the date it sits on, as `dwellTime` counts. `used` is
+ * the free days touched, `charged` the dates from `expiresAt` touched that `chargeCalendar` charges.
+ * The event day 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.
+ * Counts come from closed forms over the zone's offset changes, so the dwell's length costs no
+ * work per date. Returns `null` when the walk would visit more than `MAX_WALKED_DAYS` dates, when
+ * a day boundary cannot be found, or when the expiry lies outside the representable range. A clock
+ * within `MAX_WALKED_DAYS` dates of Temporal's limits, or in a pass that re-enters its date, is
+ * laid out day by day (`walkFreeTimeByDay`).
  */
 export declare function walkFreeTime(clockStart: Temporal.ZonedDateTime, freeDays: number, terms: FreeTimeTerms, clockEnd?: Temporal.ZonedDateTime): FreeTimeLedger | null;

package/dist/internal/freeTimeLedger.js

@@ -1,15 +1,21 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../zoned/validate/isValidTimeZone.js";
-import { isBusinessDate, parseBusinessCalendar, } from "./businessCalendar.js";
+import { Temporal } from "./temporal.js";
+import { businessDaysWithin, isBusinessDate, isBusinessEpochDay, parseBusinessCalendar, } from "./businessCalendar.js";
+import { countWithin, epochDayOfDate, hasEpochDay, lowerBound, } from "./epochDay.js";
+import { NANOSECONDS_PER_DAY } from "./foreignEpochs.js";
+import { MAX_EPOCH_NANOSECONDS, MIN_EPOCH_NANOSECONDS, } from "./epochNanoseconds.js";
+import { floorDivide } from "./floorDivide.js";
 import { isObject } from "./isObject.js";
+import { ensureTimeline, offsetOf, offsetTimeline, startOfDayNs, } from "./offsetTimeline.js";
 import { nextZonedBucketStart, zonedUnitStart } from "./zonedBucket.js";
+import { frameEpochNanoseconds, zoneFrame } from "./zoneFrame.js";
+import { certainlyTouchesMoreBuckets } from "./zoneBucketCap.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;
+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
@@ -34,7 +40,7 @@ function readFreeTimeTerms(options, readChargeBasis = false) {
     if (firstDay !== "eventDay" && firstDay !== "nextDay") {
         return null;
     }
-    if (typeof timeZone !== "string" || !isValidTimeZone(timeZone)) {
+    if (typeof timeZone !== "string" || zoneFrame(timeZone) === null) {
         return null;
     }
     const needsCalendar = basis === "working" || (readChargeBasis && chargeBasis === "working");
@@ -116,6 +122,260 @@ export function bandsByTier(tiers, chargeable) {
     bands.push({ from, to: null, days: Math.max(0, chargeable - from + 1) });
     return bands;
 }
+/**
+ * How near Temporal's limits a clock may sit before the walk steps day by day. The integer walk
+ * reaches up to `MAX_WALKED_DAYS` dates out; this margin keeps every instant it asks a zone about
+ * representable, so only the day-by-day walk has to answer for an expiry past the last instant.
+ */
+const LIMIT_MARGIN_NANOSECONDS = BigInt(MAX_WALKED_DAYS + 100) * NANOSECONDS_PER_DAY;
+/** Days the offset timeline reads past the dwell before a search asks for more. */
+const TIMELINE_LOOKAHEAD_DAYS = 14n;
+const floorDay = (ns) => Number(floorDivide(ns, NANOSECONDS_PER_DAY));
+/**
+ * The dates a zone deleted. Only a forward change can delete one: a date whose midnight lies in
+ * the skipped wall clock, and whose next midnight is no later than the change's end, has no
+ * instants (TC39 `GetStartOfDay` gives it and the next date the same start). `Pacific/Apia` skipped
+ * 30 December 2011.
+ */
+function findDeletedDates(timeline) {
+    const { changes, offsets } = timeline;
+    const deleted = [];
+    for (let index = 0; index < changes.length; index++) {
+        if (offsets[index + 1] > offsets[index]) {
+            const first = floorDay(changes[index] + offsets[index]);
+            const last = floorDay(changes[index] + offsets[index + 1]);
+            for (let day = first; day <= last; day++) {
+                if (startOfDayNs(timeline, day) === startOfDayNs(timeline, day + 1) &&
+                    (deleted.length === 0 || day > deleted[deleted.length - 1])) {
+                    deleted.push(day);
+                }
+            }
+        }
+    }
+    return Int32Array.from(deleted);
+}
+/** Make `deleted` complete up to `day`; every query of a date calls this first. */
+function reach(walk, day) {
+    if (day <= walk.reachedDay) {
+        return;
+    }
+    ensureTimeline(walk.timeline, BigInt(day + 6) * NANOSECONDS_PER_DAY);
+    const reachedDay = floorDay(walk.timeline.toNs) - 6;
+    if (reachedDay !== walk.reachedDay) {
+        walk.deleted = findDeletedDates(walk.timeline);
+        walk.reachedDay = reachedDay;
+    }
+}
+/** The first visited date after `day`: the next one the zone did not delete. */
+function nextVisited(walk, day) {
+    let next = day + 1;
+    reach(walk, next);
+    while (hasEpochDay(walk.deleted, next)) {
+        next++;
+        reach(walk, next);
+    }
+    return next;
+}
+/** Visited dates in [from, to] that count against the free-time terms; 0 when from > to. */
+function countedWithin(walk, from, to) {
+    if (from > to) {
+        return 0;
+    }
+    reach(walk, to);
+    const { calendar } = walk.terms;
+    const { deleted } = walk;
+    if (calendar === null) {
+        return to - from + 1 - countWithin(deleted, from, to);
+    }
+    let count = businessDaysWithin(from, to, calendar);
+    for (let index = lowerBound(deleted, from); index < deleted.length && deleted[index] <= to; index++) {
+        if (isBusinessEpochDay(deleted[index], calendar)) {
+            count--;
+        }
+    }
+    return count;
+}
+/**
+ * The latest date whose visited index is at most `maxIndex`, or one past it when a deleted date
+ * sits there: an upper bound for any visited date within the walk's cap.
+ */
+function lastDateWithin(walk, maxIndex) {
+    let day = walk.eventDay + maxIndex;
+    for (;;) {
+        reach(walk, day);
+        const next = walk.eventDay + maxIndex + countWithin(walk.deleted, walk.eventDay, day);
+        if (next === day) {
+            return day;
+        }
+        day = next;
+    }
+}
+/**
+ * The visited date at which `n` counted dates have been seen, starting at `from`, or `null` when
+ * that date's index passes `maxIndex`. Doubles its reach until the count is met, then bisects.
+ */
+function nthCountedDate(walk, from, n, maxIndex) {
+    let high = from + Math.ceil(n * 1.5) + 8;
+    let capped = false;
+    for (;;) {
+        if (!capped && high > walk.eventDay + maxIndex) {
+            high = lastDateWithin(walk, maxIndex);
+            capped = true;
+        }
+        if (countedWithin(walk, from, high) >= n) {
+            break;
+        }
+        if (capped) {
+            return null;
+        }
+        high = from + 2 * (high - from);
+    }
+    let low = from;
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        if (countedWithin(walk, from, middle) >= n) {
+            high = middle;
+        }
+        else {
+            low = middle + 1;
+        }
+    }
+    return low;
+}
+/**
+ * The latest date whose first instant is at or before `lastNs`. The first instant of a date never
+ * decreases from one date to the next, so this bisects. Never earlier than the event day, so
+ * `lastNs` must not precede the clock start (the callers guarantee it).
+ */
+function lastTouchedDate(walk, lastNs) {
+    const lastDay = floorDay(lastNs + offsetOf(walk.timeline, lastNs));
+    let low = walk.eventDay;
+    let high = lastDay + 3;
+    reach(walk, high);
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (startOfDayNs(walk.timeline, middle) <= lastNs) {
+            low = middle;
+        }
+        else {
+            high = middle - 1;
+        }
+    }
+    return low;
+}
+/** The visited dates in [from, to] that are charged, ascending. */
+function chargedDates(walk, from, to) {
+    const charged = [];
+    const { chargeCalendar } = walk.terms;
+    reach(walk, to);
+    for (let day = from; day <= to; day++) {
+        if ((chargeCalendar === null || isBusinessEpochDay(day, chargeCalendar)) &&
+            !hasEpochDay(walk.deleted, day)) {
+            charged.push(day);
+        }
+    }
+    return charged;
+}
+/** The free-day span and expiry date: what the first part of the day-by-day walk finds. */
+function freeSpan(walk, freeDays) {
+    const firstDay = walk.terms.firstDay === "nextDay"
+        ? nextVisited(walk, walk.eventDay)
+        : walk.eventDay;
+    if (freeDays === 0) {
+        const expiryDay = nthCountedDate(walk, firstDay, 1, MAX_WALKED_DAYS);
+        return expiryDay === null
+            ? null
+            : { firstFree: null, lastFree: null, expiryDay };
+    }
+    // The last free day is one visit short of the cap: the expiry is the visit after it.
+    const lastFree = nthCountedDate(walk, firstDay, freeDays, MAX_WALKED_DAYS - 1);
+    return lastFree === null
+        ? null
+        : {
+            firstFree: nthCountedDate(walk, firstDay, 1, MAX_WALKED_DAYS - 1),
+            lastFree,
+            expiryDay: nextVisited(walk, lastFree),
+        };
+}
+/**
+ * `walkFreeTime` on dates, without a Temporal object per day; `undefined` when the day-by-day walk
+ * has to answer. The visited dates are the dates from the event day on, each once, without those
+ * the zone deleted (`findDeletedDates`); a free day, the expiry and the touched days are all read
+ * from them, by counting and bisecting (the rules are in the day-by-day walk's description).
+ */
+function walkFreeTimeByDate(clockStart, frame, freeDays, terms, clockEnd) {
+    const startNs = frameEpochNanoseconds(clockStart, frame);
+    // The last instant the dwell occupies: one nanosecond before its end, or the end of an empty dwell.
+    let lastNs;
+    if (clockEnd !== undefined) {
+        lastNs = frameEpochNanoseconds(clockEnd, frame);
+        if (Temporal.ZonedDateTime.compare(clockStart, clockEnd) < 0) {
+            lastNs -= 1n;
+        }
+    }
+    const high = lastNs === undefined || lastNs < startNs ? startNs : lastNs;
+    // Too near Temporal's limits for the integer walk.
+    if (startNs - LIMIT_MARGIN_NANOSECONDS < MIN_EPOCH_NANOSECONDS ||
+        high + LIMIT_MARGIN_NANOSECONDS > MAX_EPOCH_NANOSECONDS) {
+        return undefined;
+    }
+    // The dwell certainly touches more dates than the cap; only a dwell long enough to need the
+    // zone's changes counted is asked.
+    if (clockEnd !== undefined &&
+        lastNs !== undefined &&
+        lastNs - startNs > BigInt(MAX_WALKED_DAYS - 2) * NANOSECONDS_PER_DAY &&
+        certainlyTouchesMoreBuckets(clockStart, clockEnd, "day", MAX_WALKED_DAYS)) {
+        return null;
+    }
+    const eventDayStart = localDayOf(clockStart);
+    if (eventDayStart === null) {
+        return null;
+    }
+    const timeline = offsetTimeline(frame, startNs - 6n * NANOSECONDS_PER_DAY, high + TIMELINE_LOOKAHEAD_DAYS * NANOSECONDS_PER_DAY);
+    const eventDay = floorDay(startNs + offsetOf(timeline, startNs));
+    const walk = {
+        timeline,
+        terms,
+        eventDay,
+        deleted: new Int32Array(0),
+        reachedDay: Number.NEGATIVE_INFINITY,
+    };
+    reach(walk, eventDay);
+    // The event day's own start is its first midnight unless the clock sits in a pass that
+    // re-enters the date; the later dates then start after that pass, which only the day-by-day
+    // walk lays out.
+    if (frameEpochNanoseconds(eventDayStart.start, frame) !==
+        startOfDayNs(timeline, eventDay)) {
+        return undefined;
+    }
+    const span = freeSpan(walk, freeDays);
+    if (span === null) {
+        return null;
+    }
+    const { firstFree, lastFree, expiryDay } = span;
+    const touchedDay = lastNs === undefined ? undefined : lastTouchedDate(walk, lastNs);
+    // The date the day-by-day walk would end on: the expiry when the dwell ends before it, else the
+    // first date past the dwell. The walk answers `null` when its index is past the cap.
+    const endDay = touchedDay === undefined || expiryDay > touchedDay
+        ? expiryDay
+        : nextVisited(walk, touchedDay);
+    reach(walk, endDay);
+    if (endDay - eventDay - countWithin(walk.deleted, eventDay, endDay - 1) >
+        MAX_WALKED_DAYS) {
+        return null;
+    }
+    return {
+        firstFree,
+        lastFree,
+        expiresAtNs: startOfDayNs(timeline, expiryDay),
+        used: touchedDay === undefined || firstFree === null || lastFree === null
+            ? 0
+            : countedWithin(walk, firstFree, Math.min(lastFree, touchedDay)),
+        charged: touchedDay === undefined || expiryDay > touchedDay
+            ? []
+            : chargedDates(walk, expiryDay, touchedDay),
+    };
+}
 /** The local day holding `zoned`, or `null` when its start cannot be found. */
 function localDayOf(zoned) {
     let start;
@@ -130,13 +390,13 @@ function localDayOf(zoned) {
         // clock start anchors the walk in its place.
         return {
             start: zoned,
-            date: zoned.toPlainDate().toString(),
+            epochDay: epochDayOfDate(zoned.toPlainDate()),
             clamped: true,
         };
     }
     return start === null
         ? null
-        : { start, date: start.toPlainDate().toString() };
+        : { start, epochDay: epochDayOfDate(start.toPlainDate()) };
 }
 /**
  * The first local day after `day` whose date is later than `day`'s. A bucket that re-enters an
@@ -163,7 +423,7 @@ function nextLocalDay(day) {
         }
         const date = next.toPlainDate();
         if (Temporal.PlainDate.compare(date, current) > 0) {
-            return { start: next, date: date.toString() };
+            return { start: next, epochDay: epochDayOfDate(date) };
         }
         cursor = next;
     }
@@ -190,8 +450,11 @@ function nextLocalDay(day) {
  *   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.
+ *
+ * This is the walk the integer form (`walkFreeTime`) answers for a clock near Temporal's limits
+ * or in a pass that re-enters its date, where the day-by-day boundaries are the rule.
  */
-export function walkFreeTime(clockStart, freeDays, terms, clockEnd) {
+function walkFreeTimeByDay(clockStart, frame, 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
@@ -199,16 +462,23 @@ export function walkFreeTime(clockStart, freeDays, terms, clockEnd) {
             ? 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 countsOn = (day, calendar) => calendar === null || isBusinessDate(day.start.toPlainDate(), calendar);
     const charged = [];
+    let firstFree = null;
+    let lastFree = null;
+    let freeSeen = 0;
     let used = 0;
-    let expiresAt = null;
+    let expiresAtNs = null;
     let expiryPending = false;
     let skipEventDay = terms.firstDay === "nextDay";
+    // A dwell that certainly touches more local days than the walk may visit ends it with the
+    // sentinel anyway: the walk needs one visit for every day the dwell touches, and one more to
+    // pass it. Deciding that from the span skips a 10,000-day walk. When it is not certain, the walk
+    // runs as before, so no answer changes.
+    if (clockEnd !== undefined &&
+        certainlyTouchesMoreBuckets(clockStart, clockEnd, "day", MAX_WALKED_DAYS)) {
+        return null;
+    }
     let day = localDayOf(clockStart);
     if (day === null) {
         return null;
@@ -216,42 +486,44 @@ export function walkFreeTime(clockStart, freeDays, terms, clockEnd) {
     // 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);
+        const counted = !skipEventDay && countsOn(day, terms.calendar);
         skipEventDay = false;
         if (expiryPending) {
-            expiresAt = day.start;
+            expiresAtNs = frameEpochNanoseconds(day.start, frame);
             expiryPending = false;
         }
-        else if (expiresAt === null && counted) {
+        else if (expiresAtNs === 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;
+                expiresAtNs = frameEpochNanoseconds(day.start, frame);
             }
             else {
-                free.push(day);
+                firstFree ??= day.epochDay;
+                lastFree = day.epochDay;
                 if (touched(day))
                     used++;
-                expiryPending = free.length === freeDays;
+                expiryPending = ++freeSeen === 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 };
+        if (expiresAtNs !== null) {
+            // Free time has ended; with no clock end, or past the dwell, there is nothing more to lay out.
+            if (last === undefined ||
+                Temporal.ZonedDateTime.compare(day.start, last) > 0) {
+                return { firstFree, lastFree, expiresAtNs, 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);
+            if (!eventDaySkipped && countsOn(day, terms.chargeCalendar)) {
+                charged.push(day.epochDay);
+            }
         }
         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 };
+            return expiresAtNs === null
+                ? null
+                : { firstFree, lastFree, expiresAtNs, used, charged };
         }
         if (next === null) {
             return null;
@@ -260,3 +532,32 @@ export function walkFreeTime(clockStart, freeDays, terms, clockEnd) {
     }
     return null;
 }
+/**
+ * Lay out free time and charges from the clock start, in epoch days (see `FreeTimeLedger`).
+ *
+ * The local days of the terminal are the dates from the event day on, each once, without a date
+ * the zone deleted. Free days are the first `freeDays` counted ones (every date on a calendar
+ * basis, a working day of `calendar` otherwise); `expiresAt` is the first instant of the visited
+ * date after the last of them, or with `freeDays` of `0` of the first counted one. With a
+ * `clockEnd` the half-open dwell `[clockStart, clockEnd)` touches a date when it starts before
+ * `clockEnd`, and a zero-length dwell touches the date it sits on, as `dwellTime` counts. `used` is
+ * the free days touched, `charged` the dates from `expiresAt` touched that `chargeCalendar` charges.
+ * The event day is neither free nor charged under `"nextDay"`.
+ *
+ * Counts come from closed forms over the zone's offset changes, so the dwell's length costs no
+ * work per date. Returns `null` when the walk would visit more than `MAX_WALKED_DAYS` dates, when
+ * a day boundary cannot be found, or when the expiry lies outside the representable range. A clock
+ * within `MAX_WALKED_DAYS` dates of Temporal's limits, or in a pass that re-enters its date, is
+ * laid out day by day (`walkFreeTimeByDay`).
+ */
+export function walkFreeTime(clockStart, freeDays, terms, clockEnd) {
+    const frame = zoneFrame(terms.timeZone);
+    if (frame === null) {
+        return null;
+    }
+    const ledger = walkFreeTimeByDate(clockStart, frame, freeDays, terms, clockEnd);
+    if (ledger !== undefined) {
+        return ledger;
+    }
+    return walkFreeTimeByDay(clockStart, frame, freeDays, terms, clockEnd);
+}

package/dist/internal/getLocaleWeekYearBounds.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 export interface LocaleWeekYearBounds {
     weekYear: number;
     /** Days from the source date to the first day of `weekYear`'s week 1 (0 or negative). */

package/dist/internal/gnssTimeScales.d.ts

@@ -0,0 +1,53 @@
+import type { GnssSystem } from "../types/gnss.js";
+import type { TimeScaleLabel } from "./timeScaleString.js";
+import type { UtcReading } from "./utcReading.js";
+/** How one satellite system's time scale relates to TAI, and where its labels start. */
+export interface GnssTimeScale {
+    /** TAI minus the scale, in seconds; null for GLO, which is UTC's own wall clock. */
+    readonly taiMinusScale: bigint | null;
+    /** First defined label, label nanoseconds. */
+    readonly epochLabel: bigint;
+}
+/**
+ * The satellite time scales by RINEX 4.02 §5.2.8 time-system identifier. Each `epochLabel` is
+ * `Temporal.PlainDateTime.from(<label>).toZonedDateTime("UTC").epochNanoseconds` of the label in
+ * its comment; gnssTimeScales.test.ts asserts each one. The offsets are nominal: the broadcast
+ * corrections (C0, A0/A1, GGTO), tens of nanoseconds, are not inputs.
+ */
+export declare const GNSS_TIME_SCALES: Readonly<Record<GnssSystem, GnssTimeScale>>;
+/**
+ * Whether a value is one of the six RINEX 4.02 §5.2.8 time-system identifiers GMT reads.
+ *
+ * @param value candidate system
+ * @returns true for `GPS`, `GAL`, `BDT`, `QZS`, `GLO` or `IRN`
+ */
+export declare function isGnssSystem(value: unknown): value is GnssSystem;
+/**
+ * A UTC reading as a label on a satellite system's scale.
+ *
+ * - TAI-based scales: TAI from the leap-second table, minus the scale's fixed offset. A listed
+ *   inserted second maps to its own label; the result is never second 60.
+ * - `GLO`: the reading itself, second 60 included, once the table has checked it.
+ * - `null` when the reading has no TAI instant (before 1972, or a second 60 on a day with no
+ *   insertion), or when the label falls before the scale's epoch.
+ *
+ * @param system the satellite time scale
+ * @param reading the UTC reading
+ * @returns the scale's label, or null
+ */
+export declare function scaleLabelOfUtc(system: GnssSystem, reading: UtcReading): TimeScaleLabel | null;
+/**
+ * A label on a satellite system's scale as a UTC reading.
+ *
+ * - TAI-based scales: the label plus the scale's fixed offset is TAI, read back through the
+ *   leap-second table; inside an inserted second the reading is second 60.
+ * - `GLO`: the label itself is the UTC reading; a second 60 stands only where the table lists an
+ *   insertion.
+ * - `null` before the scale's epoch, for a second-60 label on a continuous scale, and for a `GLO`
+ *   second 60 on a day with no insertion.
+ *
+ * @param system the satellite time scale
+ * @param label the scale's label
+ * @returns the UTC reading, or null
+ */
+export declare function utcOfScaleLabel(system: GnssSystem, label: TimeScaleLabel): UtcReading | null;