@northguild/gmt 1.14.2 → 1.16.0

package/dist/internal/getLocaleWeekYearBounds.d.ts

@@ -1,19 +1,27 @@
-import { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "@js-temporal/polyfill";
 export interface LocaleWeekYearBounds {
     weekYear: number;
-    /** First day of `weekYear`'s week 1. */
-    start: Temporal.PlainDate;
-    /** First day of `weekYear + 1`'s week 1 — an exclusive upper bound. */
-    end: Temporal.PlainDate;
+    /** Days from the source date to the first day of `weekYear`'s week 1 (0 or negative). */
+    startOffsetDays: number;
+    /** Days from the source date to the first day of `weekYear + 1`'s week 1 — exclusive (positive). */
+    endOffsetDays: number;
 }
 /**
  * Resolve the locale week-numbering year `date` belongs to, and the
- * `[start, end)` bounds (in calendar days) of that week-year, given a
+ * `[start, end)` bounds of that week-year as day offsets from `date`, given a
  * locale's `firstDay` (1 = Monday .. 7 = Sunday) and `minimalDays` (the
  * minimum January days a week must have to count as week 1) — both from
  * `Intl.Locale.prototype.weekInfo`.
  *
- * Shared by `getLocaleWeekYear` (the year itself) and
- * `getWeeksInLocaleWeekYear` (the week count, derived from `start`/`end`).
+ * Pure day arithmetic on `date`'s ISO fields: no neighbouring year's week 1 is
+ * built as a date, because it can lie outside the representable range (week 1
+ * of -271821 starts before `-271821-04-19`, week 1 of +275761 after
+ * `+275760-09-13`) while `date` itself and its week-year are valid.
+ *
+ * Shared by `getLocaleWeekYear` (the year itself),
+ * `getWeeksInLocaleWeekYear` and `getWeeksInYear` (the week count, derived
+ * from the offsets).
+ *
+ * @example getLocaleWeekYearBounds(Temporal.PlainDate.from("2024-12-30"), 1, 4) // { weekYear: 2025, startOffsetDays: 0, endOffsetDays: 364 }
  */
-export declare function getLocaleWeekYearBounds(date: Temporal.PlainDate, firstDay: number, minimalDays: number): LocaleWeekYearBounds;
+export declare function getLocaleWeekYearBounds(date: Pick<Temporal.PlainDate, "year" | "dayOfYear" | "dayOfWeek">, firstDay: number, minimalDays: number): LocaleWeekYearBounds;

package/dist/internal/getLocaleWeekYearBounds.js

@@ -1,44 +1,63 @@
-import { Temporal } from "@js-temporal/polyfill";
+/** Proleptic Gregorian leap year (ISO 8601-1:2019 §3.1.1.4 and §4.3.4). */
+function daysInIsoYear(year) {
+    const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    return leap ? 366 : 365;
+}
+/** Weekday (1 = Monday .. 7 = Sunday) `days` after a day whose weekday is `dayOfWeek`. */
+function shiftWeekday(dayOfWeek, days) {
+    return ((((dayOfWeek - 1 + days) % 7) + 7) % 7) + 1;
+}
 // Week 1 of a locale week-year always contains January's `minimalDays`-th
 // day: the week starting on/before Jan 1 has k days in January, where k
 // ranges from `minimalDays` (the threshold to still count as week 1) up
 // to 7 (a full week starting exactly on Jan 1) — so day `minimalDays` of
 // January falls within that range no matter which end it lands on. This
 // generalizes ISO 8601's own rule (minimalDays = 4, so week 1 always
-// contains Jan 4).
-function startOfWeek1(year, firstDay, minimalDays) {
-    const anchor = Temporal.PlainDate.from({
-        year,
-        month: 1,
-        day: minimalDays,
-    });
-    const daysSinceFirstDay = (anchor.dayOfWeek - firstDay + 7) % 7;
-    return anchor.subtract({ days: daysSinceFirstDay });
+// contains Jan 4). Returned as days from January 1, given its weekday.
+function week1StartFromJanuary1(january1DayOfWeek, firstDay, minimalDays) {
+    const anchorDayOfWeek = shiftWeekday(january1DayOfWeek, minimalDays - 1);
+    return minimalDays - 1 - ((anchorDayOfWeek - firstDay + 7) % 7);
 }
 /**
  * Resolve the locale week-numbering year `date` belongs to, and the
- * `[start, end)` bounds (in calendar days) of that week-year, given a
+ * `[start, end)` bounds of that week-year as day offsets from `date`, given a
  * locale's `firstDay` (1 = Monday .. 7 = Sunday) and `minimalDays` (the
  * minimum January days a week must have to count as week 1) — both from
  * `Intl.Locale.prototype.weekInfo`.
  *
- * Shared by `getLocaleWeekYear` (the year itself) and
- * `getWeeksInLocaleWeekYear` (the week count, derived from `start`/`end`).
+ * Pure day arithmetic on `date`'s ISO fields: no neighbouring year's week 1 is
+ * built as a date, because it can lie outside the representable range (week 1
+ * of -271821 starts before `-271821-04-19`, week 1 of +275761 after
+ * `+275760-09-13`) while `date` itself and its week-year are valid.
+ *
+ * Shared by `getLocaleWeekYear` (the year itself),
+ * `getWeeksInLocaleWeekYear` and `getWeeksInYear` (the week count, derived
+ * from the offsets).
+ *
+ * @example getLocaleWeekYearBounds(Temporal.PlainDate.from("2024-12-30"), 1, 4) // { weekYear: 2025, startOffsetDays: 0, endOffsetDays: 364 }
  */
 export function getLocaleWeekYearBounds(date, firstDay, minimalDays) {
-    let weekYear = date.year;
-    let start = startOfWeek1(weekYear, firstDay, minimalDays);
-    if (Temporal.PlainDate.compare(date, start) < 0) {
-        weekYear -= 1;
-        start = startOfWeek1(weekYear, firstDay, minimalDays);
+    const year = date.year;
+    const january1 = 1 - date.dayOfYear;
+    const january1DayOfWeek = shiftWeekday(date.dayOfWeek, january1);
+    const weekYearStart = (yearJanuary1) => yearJanuary1 +
+        week1StartFromJanuary1(shiftWeekday(january1DayOfWeek, yearJanuary1 - january1), firstDay, minimalDays);
+    const nextJanuary1 = january1 + daysInIsoYear(year);
+    const start = weekYearStart(january1);
+    const nextStart = weekYearStart(nextJanuary1);
+    if (start > 0) {
+        return {
+            weekYear: year - 1,
+            startOffsetDays: weekYearStart(january1 - daysInIsoYear(year - 1)),
+            endOffsetDays: start,
+        };
     }
-    else {
-        const nextStart = startOfWeek1(weekYear + 1, firstDay, minimalDays);
-        if (Temporal.PlainDate.compare(date, nextStart) >= 0) {
-            weekYear += 1;
-            start = nextStart;
-        }
+    if (nextStart <= 0) {
+        return {
+            weekYear: year + 1,
+            startOffsetDays: nextStart,
+            endOffsetDays: weekYearStart(nextJanuary1 + daysInIsoYear(year + 1)),
+        };
     }
-    const end = startOfWeek1(weekYear + 1, firstDay, minimalDays);
-    return { weekYear, start, end };
+    return { weekYear: year, startOffsetDays: start, endOffsetDays: nextStart };
 }

package/dist/internal/getLocaleWeekendDays.d.ts

@@ -1,22 +1,13 @@
-interface LocaleWeekInfo {
-    firstDay: number;
-    weekend: number[];
-    minimalDays: number;
-}
-declare global {
-    namespace Intl {
-        interface Locale {
-            readonly weekInfo: LocaleWeekInfo;
-        }
-    }
-}
+import type { LocalesArgument } from "./resolveLocale.js";
 /**
  * Resolve the set of ISO day-of-week numbers (1 = Monday .. 7 = Sunday)
- * that count as "weekend" for a locale, via `Intl.Locale.prototype.weekInfo`.
+ * that count as "weekend" for a locale, from its CLDR week data
+ * (`Intl.Locale#getWeekInfo`, or the older `weekInfo` accessor — see
+ * `localeWeekInfo`).
  *
- * - Returns `null` if `locale` is not a valid BCP 47 tag.
- * - Falls back to Saturday/Sunday (`[6, 7]`) if `weekInfo` is unavailable
- *   on the runtime (older engines) or unresolvable for the given locale.
+ * - Returns `null` if `locale` is not a well-formed BCP 47 tag; a well-formed tag with no
+ *   locale data does not throw, so it does not return `null` either.
+ * - Falls back to Saturday/Sunday (`[6, 7]`) if the runtime exposes no week
+ *   data or none for the given locale.
  */
-export declare function getLocaleWeekendDays(locale: string): Set<number> | null;
-export {};
+export declare function getLocaleWeekendDays(locale: LocalesArgument): Set<number> | null;

package/dist/internal/getLocaleWeekendDays.js

@@ -1,14 +1,18 @@
+import { localeWeekInfo } from "./localeWeekInfo.js";
 /**
  * Resolve the set of ISO day-of-week numbers (1 = Monday .. 7 = Sunday)
- * that count as "weekend" for a locale, via `Intl.Locale.prototype.weekInfo`.
+ * that count as "weekend" for a locale, from its CLDR week data
+ * (`Intl.Locale#getWeekInfo`, or the older `weekInfo` accessor — see
+ * `localeWeekInfo`).
  *
- * - Returns `null` if `locale` is not a valid BCP 47 tag.
- * - Falls back to Saturday/Sunday (`[6, 7]`) if `weekInfo` is unavailable
- *   on the runtime (older engines) or unresolvable for the given locale.
+ * - Returns `null` if `locale` is not a well-formed BCP 47 tag; a well-formed tag with no
+ *   locale data does not throw, so it does not return `null` either.
+ * - Falls back to Saturday/Sunday (`[6, 7]`) if the runtime exposes no week
+ *   data or none for the given locale.
  */
 export function getLocaleWeekendDays(locale) {
     try {
-        const weekInfo = new Intl.Locale(locale).weekInfo;
+        const weekInfo = localeWeekInfo(locale);
         if (!weekInfo || !Array.isArray(weekInfo.weekend)) {
             return new Set([6, 7]);
         }

package/dist/internal/halfOpenIntervals.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Half-open `[start, end)` interval algebra over any totally ordered value type.
+ *
+ * `t ∈ [start, end) ⇔ start ≤ t < end` — EWD831, SQL:2011 closed-open `PERIOD`
+ * (ISO/IEC 9075-2:2011) and RFC 5545 §3.6.1 non-inclusive `DTEND`. These helpers carry the same
+ * rules as the CORE-6 `interval/` namespace (see `context/domination/specs/CORE-6-spec.md` §3)
+ * for the positional families whose values are not instants (`PlainDate`, `PlainDateTime`,
+ * `PlainTime`) and for the relations `interval/` has no function for.
+ *
+ * - `compare` returns a negative, zero or positive number, like `Temporal.*.compare`.
+ * - Callers validate first: every span passed in has `start ≤ end`.
+ * - No helper ever steps a value by one unit, so nothing can overflow a type's range or wrap a
+ *   `PlainTime` past midnight.
+ * - Every returned span is a fresh object holding values from the inputs.
+ */
+type Compare<T> = (left: T, right: T) => number;
+/** A validated `[start, end)` span of one value type. */
+export interface HalfOpenSpan<T> {
+    start: T;
+    end: T;
+}
+/**
+ * True when the spans share at least one value: `a.start < b.end && b.start < a.end`.
+ * Touching spans do not overlap, and an empty span overlaps only when strictly inside the other.
+ *
+ * @example halfOpenOverlap({ start: 1, end: 5 }, { start: 3, end: 8 }, (x, y) => x - y) // true
+ * @example halfOpenOverlap({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // false (touching)
+ */
+export declare function halfOpenOverlap<T>(a: HalfOpenSpan<T>, b: HalfOpenSpan<T>, compare: Compare<T>): boolean;
+/**
+ * True when `start ≤ point < end`. An empty span contains no value.
+ *
+ * @example halfOpenContainsPoint({ start: 1, end: 5 }, 1, (x, y) => x - y) // true
+ * @example halfOpenContainsPoint({ start: 1, end: 5 }, 5, (x, y) => x - y) // false (end is excluded)
+ */
+export declare function halfOpenContainsPoint<T>(span: HalfOpenSpan<T>, point: T, compare: Compare<T>): boolean;
+/**
+ * True when `inner` lies within `outer` and the two overlap. For a non-empty `inner` this is
+ * `outer.start ≤ inner.start && inner.end ≤ outer.end`; an empty `inner` counts only strictly
+ * inside `outer`, matching CORE-6's `clampInterval`, which clamps an empty interval at an edge to
+ * `null` and one strictly inside to itself.
+ *
+ * @example halfOpenContainsSpan({ start: 1, end: 9 }, { start: 3, end: 9 }, (x, y) => x - y) // true
+ * @example halfOpenContainsSpan({ start: 1, end: 9 }, { start: 9, end: 9 }, (x, y) => x - y) // false (empty at the edge)
+ */
+export declare function halfOpenContainsSpan<T>(outer: HalfOpenSpan<T>, inner: HalfOpenSpan<T>, compare: Compare<T>): boolean;
+/**
+ * The shared span `[max(starts), min(ends))`, or `null` when the spans do not overlap.
+ * `halfOpenIntersection(a, b) !== null ⇔ halfOpenOverlap(a, b)` by construction.
+ *
+ * @example halfOpenIntersection({ start: 1, end: 5 }, { start: 3, end: 8 }, (x, y) => x - y) // { start: 3, end: 5 }
+ * @example halfOpenIntersection({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // null (touching)
+ */
+export declare function halfOpenIntersection<T>(a: HalfOpenSpan<T>, b: HalfOpenSpan<T>, compare: Compare<T>): HalfOpenSpan<T> | null;
+/**
+ * Coalesce spans into sorted, disjoint, non-touching, non-empty runs (CORE-6
+ * `coalesceIntervalNanoseconds`): touching spans join, an empty span touching or inside a run is
+ * absorbed, and an empty span nothing touches is dropped.
+ *
+ * @example halfOpenMerge([{ start: 3, end: 8 }, { start: 1, end: 3 }], (x, y) => x - y) // [{ start: 1, end: 8 }]
+ * @example halfOpenMerge([{ start: 5, end: 5 }], (x, y) => x - y) // []
+ */
+export declare function halfOpenMerge<T>(spans: ReadonlyArray<HalfOpenSpan<T>>, compare: Compare<T>): Array<HalfOpenSpan<T>>;
+/**
+ * The union of two spans when it is one non-empty span, otherwise `null` — the single run of
+ * `halfOpenMerge([a, b])`. Touching spans join; spans with a gap, and two empty spans, give `null`.
+ *
+ * @example halfOpenUnion({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // { start: 1, end: 5 }
+ * @example halfOpenUnion({ start: 1, end: 3 }, { start: 4, end: 5 }, (x, y) => x - y) // null (gap)
+ */
+export declare function halfOpenUnion<T>(a: HalfOpenSpan<T>, b: HalfOpenSpan<T>, compare: Compare<T>): HalfOpenSpan<T> | null;
+/**
+ * The parts of `from` not covered by any span in `remove`, sorted and non-empty (CORE-6
+ * `subtractIntervals`). Pieces end exactly where a removal starts and start exactly where one
+ * ends.
+ *
+ * @example halfOpenDifference({ start: 1, end: 9 }, [{ start: 3, end: 5 }], (x, y) => x - y) // [{ start: 1, end: 3 }, { start: 5, end: 9 }]
+ * @example halfOpenDifference({ start: 1, end: 9 }, [{ start: 1, end: 9 }], (x, y) => x - y) // []
+ */
+export declare function halfOpenDifference<T>(from: HalfOpenSpan<T>, remove: ReadonlyArray<HalfOpenSpan<T>>, compare: Compare<T>): Array<HalfOpenSpan<T>>;
+/**
+ * The symmetric difference of any number of spans: every maximal run of values covered an odd
+ * number of times, sorted by start.
+ *
+ * Every start and end is a boundary. At each distinct boundary value the coverage parity flips
+ * when the number of starts plus ends there is odd. A span's own start and end cancel when it is
+ * empty, and one span ending where another starts leaves the parity unchanged, so touching odd
+ * runs come out as one maximal run.
+ *
+ * @example halfOpenXor([{ start: 1, end: 5 }, { start: 3, end: 8 }], (x, y) => x - y) // [{ start: 1, end: 3 }, { start: 5, end: 8 }]
+ * @example halfOpenXor([{ start: 1, end: 3 }, { start: 3, end: 5 }], (x, y) => x - y) // [{ start: 1, end: 5 }]
+ */
+export declare function halfOpenXor<T>(spans: ReadonlyArray<HalfOpenSpan<T>>, compare: Compare<T>): Array<HalfOpenSpan<T>>;
+/**
+ * True when one non-empty span ends exactly where the other non-empty span starts — they share
+ * no value and leave no gap (Allen's "meets", in either order). An empty span abuts nothing.
+ *
+ * @example halfOpenAbuts({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // true
+ * @example halfOpenAbuts({ start: 1, end: 3 }, { start: 4, end: 5 }, (x, y) => x - y) // false (gap)
+ */
+export declare function halfOpenAbuts<T>(a: HalfOpenSpan<T>, b: HalfOpenSpan<T>, compare: Compare<T>): boolean;
+export {};

package/dist/internal/halfOpenIntervals.js

@@ -0,0 +1,180 @@
+/**
+ * Half-open `[start, end)` interval algebra over any totally ordered value type.
+ *
+ * `t ∈ [start, end) ⇔ start ≤ t < end` — EWD831, SQL:2011 closed-open `PERIOD`
+ * (ISO/IEC 9075-2:2011) and RFC 5545 §3.6.1 non-inclusive `DTEND`. These helpers carry the same
+ * rules as the CORE-6 `interval/` namespace (see `context/domination/specs/CORE-6-spec.md` §3)
+ * for the positional families whose values are not instants (`PlainDate`, `PlainDateTime`,
+ * `PlainTime`) and for the relations `interval/` has no function for.
+ *
+ * - `compare` returns a negative, zero or positive number, like `Temporal.*.compare`.
+ * - Callers validate first: every span passed in has `start ≤ end`.
+ * - No helper ever steps a value by one unit, so nothing can overflow a type's range or wrap a
+ *   `PlainTime` past midnight.
+ * - Every returned span is a fresh object holding values from the inputs.
+ */
+/**
+ * True when the spans share at least one value: `a.start < b.end && b.start < a.end`.
+ * Touching spans do not overlap, and an empty span overlaps only when strictly inside the other.
+ *
+ * @example halfOpenOverlap({ start: 1, end: 5 }, { start: 3, end: 8 }, (x, y) => x - y) // true
+ * @example halfOpenOverlap({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // false (touching)
+ */
+export function halfOpenOverlap(a, b, compare) {
+    return compare(a.start, b.end) < 0 && compare(b.start, a.end) < 0;
+}
+/**
+ * True when `start ≤ point < end`. An empty span contains no value.
+ *
+ * @example halfOpenContainsPoint({ start: 1, end: 5 }, 1, (x, y) => x - y) // true
+ * @example halfOpenContainsPoint({ start: 1, end: 5 }, 5, (x, y) => x - y) // false (end is excluded)
+ */
+export function halfOpenContainsPoint(span, point, compare) {
+    return compare(span.start, point) <= 0 && compare(point, span.end) < 0;
+}
+/**
+ * True when `inner` lies within `outer` and the two overlap. For a non-empty `inner` this is
+ * `outer.start ≤ inner.start && inner.end ≤ outer.end`; an empty `inner` counts only strictly
+ * inside `outer`, matching CORE-6's `clampInterval`, which clamps an empty interval at an edge to
+ * `null` and one strictly inside to itself.
+ *
+ * @example halfOpenContainsSpan({ start: 1, end: 9 }, { start: 3, end: 9 }, (x, y) => x - y) // true
+ * @example halfOpenContainsSpan({ start: 1, end: 9 }, { start: 9, end: 9 }, (x, y) => x - y) // false (empty at the edge)
+ */
+export function halfOpenContainsSpan(outer, inner, compare) {
+    return (halfOpenOverlap(outer, inner, compare) &&
+        compare(outer.start, inner.start) <= 0 &&
+        compare(inner.end, outer.end) <= 0);
+}
+/**
+ * The shared span `[max(starts), min(ends))`, or `null` when the spans do not overlap.
+ * `halfOpenIntersection(a, b) !== null ⇔ halfOpenOverlap(a, b)` by construction.
+ *
+ * @example halfOpenIntersection({ start: 1, end: 5 }, { start: 3, end: 8 }, (x, y) => x - y) // { start: 3, end: 5 }
+ * @example halfOpenIntersection({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // null (touching)
+ */
+export function halfOpenIntersection(a, b, compare) {
+    if (!halfOpenOverlap(a, b, compare)) {
+        return null;
+    }
+    return {
+        start: compare(a.start, b.start) >= 0 ? a.start : b.start,
+        end: compare(a.end, b.end) <= 0 ? a.end : b.end,
+    };
+}
+/**
+ * Coalesce spans into sorted, disjoint, non-touching, non-empty runs (CORE-6
+ * `coalesceIntervalNanoseconds`): touching spans join, an empty span touching or inside a run is
+ * absorbed, and an empty span nothing touches is dropped.
+ *
+ * @example halfOpenMerge([{ start: 3, end: 8 }, { start: 1, end: 3 }], (x, y) => x - y) // [{ start: 1, end: 8 }]
+ * @example halfOpenMerge([{ start: 5, end: 5 }], (x, y) => x - y) // []
+ */
+export function halfOpenMerge(spans, compare) {
+    const sorted = [...spans].sort((left, right) => compare(left.start, right.start));
+    const runs = [];
+    for (const span of sorted) {
+        const last = runs[runs.length - 1];
+        if (last !== undefined && compare(span.start, last.end) <= 0) {
+            if (compare(span.end, last.end) > 0) {
+                last.end = span.end;
+            }
+        }
+        else {
+            runs.push({ start: span.start, end: span.end });
+        }
+    }
+    return runs.filter((run) => compare(run.start, run.end) < 0);
+}
+/**
+ * The union of two spans when it is one non-empty span, otherwise `null` — the single run of
+ * `halfOpenMerge([a, b])`. Touching spans join; spans with a gap, and two empty spans, give `null`.
+ *
+ * @example halfOpenUnion({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // { start: 1, end: 5 }
+ * @example halfOpenUnion({ start: 1, end: 3 }, { start: 4, end: 5 }, (x, y) => x - y) // null (gap)
+ */
+export function halfOpenUnion(a, b, compare) {
+    const runs = halfOpenMerge([a, b], compare);
+    return runs.length === 1 ? runs[0] : null;
+}
+/**
+ * The parts of `from` not covered by any span in `remove`, sorted and non-empty (CORE-6
+ * `subtractIntervals`). Pieces end exactly where a removal starts and start exactly where one
+ * ends.
+ *
+ * @example halfOpenDifference({ start: 1, end: 9 }, [{ start: 3, end: 5 }], (x, y) => x - y) // [{ start: 1, end: 3 }, { start: 5, end: 9 }]
+ * @example halfOpenDifference({ start: 1, end: 9 }, [{ start: 1, end: 9 }], (x, y) => x - y) // []
+ */
+export function halfOpenDifference(from, remove, compare) {
+    const pieces = [];
+    let cursor = from.start;
+    for (const run of halfOpenMerge(remove, compare)) {
+        if (compare(run.start, from.end) >= 0) {
+            break;
+        }
+        if (compare(run.end, cursor) <= 0) {
+            continue;
+        }
+        if (compare(run.start, cursor) > 0) {
+            pieces.push({ start: cursor, end: run.start });
+        }
+        cursor = run.end;
+    }
+    if (compare(cursor, from.end) < 0) {
+        pieces.push({ start: cursor, end: from.end });
+    }
+    return pieces;
+}
+/**
+ * The symmetric difference of any number of spans: every maximal run of values covered an odd
+ * number of times, sorted by start.
+ *
+ * Every start and end is a boundary. At each distinct boundary value the coverage parity flips
+ * when the number of starts plus ends there is odd. A span's own start and end cancel when it is
+ * empty, and one span ending where another starts leaves the parity unchanged, so touching odd
+ * runs come out as one maximal run.
+ *
+ * @example halfOpenXor([{ start: 1, end: 5 }, { start: 3, end: 8 }], (x, y) => x - y) // [{ start: 1, end: 3 }, { start: 5, end: 8 }]
+ * @example halfOpenXor([{ start: 1, end: 3 }, { start: 3, end: 5 }], (x, y) => x - y) // [{ start: 1, end: 5 }]
+ */
+export function halfOpenXor(spans, compare) {
+    const boundaries = spans
+        .flatMap((span) => [span.start, span.end])
+        .sort(compare);
+    const result = [];
+    let runStart = null;
+    let index = 0;
+    while (index < boundaries.length) {
+        const point = boundaries[index];
+        let count = 0;
+        while (index < boundaries.length &&
+            compare(boundaries[index], point) === 0) {
+            count += 1;
+            index += 1;
+        }
+        if (count % 2 === 0) {
+            continue;
+        }
+        if (runStart === null) {
+            runStart = point;
+        }
+        else {
+            result.push({ start: runStart, end: point });
+            runStart = null;
+        }
+    }
+    return result;
+}
+/**
+ * True when one non-empty span ends exactly where the other non-empty span starts — they share
+ * no value and leave no gap (Allen's "meets", in either order). An empty span abuts nothing.
+ *
+ * @example halfOpenAbuts({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // true
+ * @example halfOpenAbuts({ start: 1, end: 3 }, { start: 4, end: 5 }, (x, y) => x - y) // false (gap)
+ */
+export function halfOpenAbuts(a, b, compare) {
+    if (compare(a.start, a.end) === 0 || compare(b.start, b.end) === 0) {
+        return false;
+    }
+    return compare(a.end, b.start) === 0 || compare(b.end, a.start) === 0;
+}

package/dist/internal/hasCalendarAnnotation.d.ts

@@ -1,27 +1,27 @@
 /**
- * Return true when `value` carries a `[u-ca=...]` calendar annotation — either GMT's own
- * native-digit shape or Temporal's own ISO-digit RFC 9557 shape.
+ * Return true when `value` carries a `[u-ca=...]` calendar annotation, in any position.
  *
- * The implementation has not changed since E5; its *meaning* has, because `zoned/` is no longer
- * uniform. Current usage, after E7 (issue #152):
+ * RFC 9557 lets any suffix annotation carry a critical flag (§3.3; `critical-flag` in the §4.1
+ * ABNF), and Temporal honours it for the calendar key:
+ * `Temporal.ZonedDateTime.from("5784-01-01T14:30:00-05:00[America/New_York][!u-ca=hebrew]")`
+ * succeeds in the Hebrew calendar, reading ISO year 5784 as Hebrew year 9544. The flag only makes
+ * the annotation harder to ignore, so `[!u-ca=...]` is detected exactly like `[u-ca=...]`. A
+ * critical time-zone annotation (`[!America/New_York]`) carries no key and does not match.
+ * Temporal rejects an upper-case `[U-CA=` key outright, so it needs no special case.
  *
- * - **`utc/`** (already regex-gated to a strict `<date>T<time>Z` shape) and **`unix/`** (numeric
- *   input, structurally immune) reject every annotation, exactly as they always have.
- * - **`isValidZonedDateTime`** still rejects every annotation, and the ~72 `zoned/` functions
- *   gated on it therefore still do too. That gate is deliberately left alone: loosening it would
- *   make `isValidZonedDateTime(x) === true` while e.g. `getZonedYear(x) === null`, i.e. a
- *   validator certifying strings its own namespace refuses.
- * - **The ~18 calendar-aware `zoned/` functions** added by E7 gate on the parallel
- *   `isValidCalendarZonedDateTime`/`isValidCalendarZonedInterval` instead, which ACCEPT GMT's
- *   `<date>T<time><offset>[u-ca=...][timeZone]` grammar and reject only Temporal's own segment
- *   ordering. Those paths use `internal/calendarValueOfZoned.ts` and
- *   `internal/calendarZonedString.ts`, not this predicate.
- * - **`plain/`** `PlainDate` functions accept GMT's annotated shape via `isValidCalendarDate`
- *   (E5's D1); `plain/` `PlainDateTime`/`PlainTime` functions have no annotated grammar of their
- *   own and treat one as invalid input.
+ * Since CORE-8 (#22) the non-calendar validators no longer use it: `isValidDate`,
+ * `isValidDateTime`, `isValidZonedDateTime` and `isValidZonedRange` read the calendar Temporal
+ * reads (`calendarId === "iso8601"`), and instants ignore the annotation as `Temporal.Instant.from`
+ * does. It remains a routing test: does a string name a calendar at all?
  *
  * So this predicate answers exactly one question — "does this string carry an annotation at all?"
- * — and says nothing about whether the caller should accept it. Reach for it only where the
- * answer is "reject unconditionally".
+ * — and says nothing about whether the caller should accept it.
+ *
+ * @param value candidate ISO 8601 string
+ * @returns true when a calendar annotation is present, critical or not
+ *
+ * @example hasCalendarAnnotation("2024-02-10T12:00:00Z[u-ca=hebrew]") // true
+ * @example hasCalendarAnnotation("2024-02-10T12:00:00Z[!u-ca=hebrew]") // true (critical flag)
+ * @example hasCalendarAnnotation("2024-02-10T12:00:00-05:00[!America/New_York]") // false (a zone, not a calendar)
  */
 export declare function hasCalendarAnnotation(value: string): boolean;

package/dist/internal/hasCalendarAnnotation.js

@@ -1,29 +1,31 @@
+/** A `[u-ca=` calendar annotation, with or without RFC 9557's critical flag (`[!u-ca=`). */
+const calendarAnnotation = /\[!?u-ca=/;
 /**
- * Return true when `value` carries a `[u-ca=...]` calendar annotation — either GMT's own
- * native-digit shape or Temporal's own ISO-digit RFC 9557 shape.
+ * Return true when `value` carries a `[u-ca=...]` calendar annotation, in any position.
  *
- * The implementation has not changed since E5; its *meaning* has, because `zoned/` is no longer
- * uniform. Current usage, after E7 (issue #152):
+ * RFC 9557 lets any suffix annotation carry a critical flag (§3.3; `critical-flag` in the §4.1
+ * ABNF), and Temporal honours it for the calendar key:
+ * `Temporal.ZonedDateTime.from("5784-01-01T14:30:00-05:00[America/New_York][!u-ca=hebrew]")`
+ * succeeds in the Hebrew calendar, reading ISO year 5784 as Hebrew year 9544. The flag only makes
+ * the annotation harder to ignore, so `[!u-ca=...]` is detected exactly like `[u-ca=...]`. A
+ * critical time-zone annotation (`[!America/New_York]`) carries no key and does not match.
+ * Temporal rejects an upper-case `[U-CA=` key outright, so it needs no special case.
  *
- * - **`utc/`** (already regex-gated to a strict `<date>T<time>Z` shape) and **`unix/`** (numeric
- *   input, structurally immune) reject every annotation, exactly as they always have.
- * - **`isValidZonedDateTime`** still rejects every annotation, and the ~72 `zoned/` functions
- *   gated on it therefore still do too. That gate is deliberately left alone: loosening it would
- *   make `isValidZonedDateTime(x) === true` while e.g. `getZonedYear(x) === null`, i.e. a
- *   validator certifying strings its own namespace refuses.
- * - **The ~18 calendar-aware `zoned/` functions** added by E7 gate on the parallel
- *   `isValidCalendarZonedDateTime`/`isValidCalendarZonedInterval` instead, which ACCEPT GMT's
- *   `<date>T<time><offset>[u-ca=...][timeZone]` grammar and reject only Temporal's own segment
- *   ordering. Those paths use `internal/calendarValueOfZoned.ts` and
- *   `internal/calendarZonedString.ts`, not this predicate.
- * - **`plain/`** `PlainDate` functions accept GMT's annotated shape via `isValidCalendarDate`
- *   (E5's D1); `plain/` `PlainDateTime`/`PlainTime` functions have no annotated grammar of their
- *   own and treat one as invalid input.
+ * Since CORE-8 (#22) the non-calendar validators no longer use it: `isValidDate`,
+ * `isValidDateTime`, `isValidZonedDateTime` and `isValidZonedRange` read the calendar Temporal
+ * reads (`calendarId === "iso8601"`), and instants ignore the annotation as `Temporal.Instant.from`
+ * does. It remains a routing test: does a string name a calendar at all?
  *
  * So this predicate answers exactly one question — "does this string carry an annotation at all?"
- * — and says nothing about whether the caller should accept it. Reach for it only where the
- * answer is "reject unconditionally".
+ * — and says nothing about whether the caller should accept it.
+ *
+ * @param value candidate ISO 8601 string
+ * @returns true when a calendar annotation is present, critical or not
+ *
+ * @example hasCalendarAnnotation("2024-02-10T12:00:00Z[u-ca=hebrew]") // true
+ * @example hasCalendarAnnotation("2024-02-10T12:00:00Z[!u-ca=hebrew]") // true (critical flag)
+ * @example hasCalendarAnnotation("2024-02-10T12:00:00-05:00[!America/New_York]") // false (a zone, not a calendar)
  */
 export function hasCalendarAnnotation(value) {
-    return typeof value === "string" && value.includes("[u-ca=");
+    return typeof value === "string" && calendarAnnotation.test(value);
 }

package/dist/internal/hourDurationString.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Format a non-negative count of nanoseconds as an ISO 8601 duration with hours as the largest
+ * unit — the string `Temporal.Instant.prototype.until(…, { largestUnit: "hour" }).toString()`
+ * produces for a span of that length. Returns "" for a negative count or if Temporal throws.
+ *
+ * - Splits with bigint division, so it stays exact past 2^53 ns and across the full Instant
+ *   span (1.728 × 10^22 ns = 4 800 000 000 h, which `Number` holds exactly).
+ *
+ * @param nanoseconds non-negative elapsed nanoseconds
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example formatHourDuration(0n) // "PT0S"
+ * @example formatHourDuration(178200000000001n) // "PT49H30M0.000000001S"
+ * @example formatHourDuration(-1n) // ""
+ */
+export declare function formatHourDuration(nanoseconds: bigint): string;

package/dist/internal/hourDurationString.js

@@ -0,0 +1,47 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { NANOSECONDS_PER_MICROSECOND, NANOSECONDS_PER_MILLISECOND, NANOSECONDS_PER_SECOND, } from "./foreignEpochs.js";
+const NANOSECONDS_PER_HOUR = 3600000000000n;
+const NANOSECONDS_PER_MINUTE = 60000000000n;
+/**
+ * Format a non-negative count of nanoseconds as an ISO 8601 duration with hours as the largest
+ * unit — the string `Temporal.Instant.prototype.until(…, { largestUnit: "hour" }).toString()`
+ * produces for a span of that length. Returns "" for a negative count or if Temporal throws.
+ *
+ * - Splits with bigint division, so it stays exact past 2^53 ns and across the full Instant
+ *   span (1.728 × 10^22 ns = 4 800 000 000 h, which `Number` holds exactly).
+ *
+ * @param nanoseconds non-negative elapsed nanoseconds
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example formatHourDuration(0n) // "PT0S"
+ * @example formatHourDuration(178200000000001n) // "PT49H30M0.000000001S"
+ * @example formatHourDuration(-1n) // ""
+ */
+export function formatHourDuration(nanoseconds) {
+    if (nanoseconds < 0n) {
+        return "";
+    }
+    const hours = nanoseconds / NANOSECONDS_PER_HOUR;
+    const afterHours = nanoseconds % NANOSECONDS_PER_HOUR;
+    const minutes = afterHours / NANOSECONDS_PER_MINUTE;
+    const afterMinutes = afterHours % NANOSECONDS_PER_MINUTE;
+    const seconds = afterMinutes / NANOSECONDS_PER_SECOND;
+    const afterSeconds = afterMinutes % NANOSECONDS_PER_SECOND;
+    const milliseconds = afterSeconds / NANOSECONDS_PER_MILLISECOND;
+    const afterMilliseconds = afterSeconds % NANOSECONDS_PER_MILLISECOND;
+    const microseconds = afterMilliseconds / NANOSECONDS_PER_MICROSECOND;
+    const remainder = afterMilliseconds % NANOSECONDS_PER_MICROSECOND;
+    try {
+        return Temporal.Duration.from({
+            hours: Number(hours),
+            minutes: Number(minutes),
+            seconds: Number(seconds),
+            milliseconds: Number(milliseconds),
+            microseconds: Number(microseconds),
+            nanoseconds: Number(remainder),
+        }).toString();
+    }
+    catch {
+        return "";
+    }
+}