@northguild/gmt 1.14.2 → 1.16.0

package/dist/zoned/interval/intervalSplitAtZoned.d.ts

@@ -4,16 +4,19 @@
  * - `points` need not be sorted — they are sorted internally (by instant) before splitting.
  * - Comparison and boundary placement use the instant each point represents, so points may
  *   carry a different time zone than `start`/`end`.
- * - Points outside `[start, end]` are dropped; they cannot introduce a boundary that isn't
- *   inside the interval.
+ * - Points before `start` or after `end` are dropped; they cannot introduce a boundary that
+ *   isn't inside the interval.
  * - Points on the same instant as `start` or `end` are dropped too — they would only produce a
  *   zero-length sub-interval at the edge.
  * - Duplicate points (same instant) collapse to a single boundary.
+ * - Returns consecutive half-open `[start, end)` records, the same tiling as `splitIntervalAt`:
+ *   each record's `end` is the next record's `start` and belongs only to that next record, so the
+ *   pieces share no instant and together cover `[start, end)` exactly once.
  * - Returns `[{ start, end }]` (the whole interval, unsplit) when no valid in-range point remains.
  * - Returns `[]` when `points` is not an array, when any element is not a valid ISO
  *   ZonedDateTime string, or on invalid input (unparseable start/end, `start > end`,
  *   leap-second strings).
- * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152) — but **rejects a mismatched set**: `start`, `end`
  *   and every element of `points` must name the same calendar system (E7's D4-zoned), since the
  *   returned sub-intervals are values the caller reads back as datetimes and an array of

package/dist/zoned/interval/intervalSplitAtZoned.js

@@ -8,16 +8,19 @@ import { isValidCalendarZonedInterval } from "./validate/index.js";
  * - `points` need not be sorted — they are sorted internally (by instant) before splitting.
  * - Comparison and boundary placement use the instant each point represents, so points may
  *   carry a different time zone than `start`/`end`.
- * - Points outside `[start, end]` are dropped; they cannot introduce a boundary that isn't
- *   inside the interval.
+ * - Points before `start` or after `end` are dropped; they cannot introduce a boundary that
+ *   isn't inside the interval.
  * - Points on the same instant as `start` or `end` are dropped too — they would only produce a
  *   zero-length sub-interval at the edge.
  * - Duplicate points (same instant) collapse to a single boundary.
+ * - Returns consecutive half-open `[start, end)` records, the same tiling as `splitIntervalAt`:
+ *   each record's `end` is the next record's `start` and belongs only to that next record, so the
+ *   pieces share no instant and together cover `[start, end)` exactly once.
  * - Returns `[{ start, end }]` (the whole interval, unsplit) when no valid in-range point remains.
  * - Returns `[]` when `points` is not an array, when any element is not a valid ISO
  *   ZonedDateTime string, or on invalid input (unparseable start/end, `start > end`,
  *   leap-second strings).
- * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152) — but **rejects a mismatched set**: `start`, `end`
  *   and every element of `points` must name the same calendar system (E7's D4-zoned), since the
  *   returned sub-intervals are values the caller reads back as datetimes and an array of
@@ -35,50 +38,57 @@ import { isValidCalendarZonedInterval } from "./validate/index.js";
  * @example intervalSplitAtZoned("invalid", "2024-01-10T00:00:00+00:00[UTC]", ["2024-01-05T00:00:00+00:00[UTC]"]) // []
  */
 export function intervalSplitAtZoned(start, end, points) {
-    if (!Array.isArray(points)) {
-        return [];
-    }
-    if (!isValidCalendarZonedInterval(start, end)) {
-        return [];
-    }
-    if (!points.every((point) => isValidCalendarZonedDateTime(point))) {
-        return [];
-    }
-    // D4-zoned reject gate: the interval's endpoints AND every split point must agree on a
-    // calendar, or there is no calendar to express the returned sub-intervals in.
-    const calendar = calendarOfAllZonedValues([start, end, ...points]);
-    if (!calendar) {
-        return [];
-    }
     try {
-        const startVal = parseCalendarZonedValue(start);
-        const endVal = parseCalendarZonedValue(end);
-        const startInstant = startVal.toInstant();
-        const endInstant = endVal.toInstant();
-        const parsedPoints = points.map((point) => parseCalendarZonedValue(point));
-        const inRangePoints = parsedPoints.filter((point) => {
-            const instant = point.toInstant();
-            return (Temporal.Instant.compare(instant, startInstant) > 0 &&
-                Temporal.Instant.compare(instant, endInstant) < 0);
-        });
-        inRangePoints.sort((a, b) => Temporal.Instant.compare(a.toInstant(), b.toInstant()));
-        // Safe: `.equals()` here is `Temporal.Instant.prototype.equals`, and `Instant` carries no
-        // calendar field at all — verified calendar-blind. E7 re-audited this site rather than
-        // inheriting E5's "structurally unreachable" verdict, which depended on mixed calendars never
-        // reaching `zoned/` at all.
-        const uniquePoints = inRangePoints.filter((point, index) => index === 0 ||
-            !point.toInstant().equals(inRangePoints[index - 1].toInstant()));
-        const boundaries = [startVal, ...uniquePoints, endVal];
-        const result = [];
-        for (let i = 0; i < boundaries.length - 1; i++) {
-            result.push({
-                start: formatZonedInCalendar(boundaries[i], calendar),
-                end: formatZonedInCalendar(boundaries[i + 1], calendar),
+        if (!Array.isArray(points)) {
+            return [];
+        }
+        if (!isValidCalendarZonedInterval(start, end)) {
+            return [];
+        }
+        if (!points.every((point) => isValidCalendarZonedDateTime(point))) {
+            return [];
+        }
+        // D4-zoned reject gate: the interval's endpoints AND every split point must agree on a
+        // calendar, or there is no calendar to express the returned sub-intervals in.
+        const calendar = calendarOfAllZonedValues([start, end, ...points]);
+        if (!calendar) {
+            return [];
+        }
+        try {
+            const startVal = parseCalendarZonedValue(start);
+            const endVal = parseCalendarZonedValue(end);
+            const startInstant = startVal.toInstant();
+            const endInstant = endVal.toInstant();
+            const parsedPoints = points.map((point) => parseCalendarZonedValue(point));
+            const inRangePoints = parsedPoints.filter((point) => {
+                const instant = point.toInstant();
+                return (Temporal.Instant.compare(instant, startInstant) > 0 &&
+                    Temporal.Instant.compare(instant, endInstant) < 0);
             });
+            inRangePoints.sort((a, b) => Temporal.Instant.compare(a.toInstant(), b.toInstant()));
+            // Safe: `.equals()` here is `Temporal.Instant.prototype.equals`, and `Instant` carries no
+            // calendar field at all — verified calendar-blind. E7 re-audited this site rather than
+            // inheriting E5's "structurally unreachable" verdict, which depended on mixed calendars never
+            // reaching `zoned/` at all.
+            const uniquePoints = inRangePoints.filter((point, index) => index === 0 ||
+                !point.toInstant().equals(inRangePoints[index - 1].toInstant()));
+            const boundaries = [startVal, ...uniquePoints, endVal];
+            const result = [];
+            for (let i = 0; i < boundaries.length - 1; i++) {
+                result.push({
+                    start: formatZonedInCalendar(boundaries[i], calendar),
+                    end: formatZonedInCalendar(boundaries[i + 1], calendar),
+                });
+            }
+            return result;
+        }
+        catch {
+            return [];
         }
-        return result;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

package/dist/zoned/interval/intervalUnionZoned.d.ts

@@ -1,12 +1,19 @@
 /**
- * Return the combined span of two zoned intervals, or null when they are disjoint.
+ * Return the combined span of two half-open zoned intervals `[start, end)`, or null when their
+ * union is not one non-empty span.
  *
  * - Uses `Temporal.ZonedDateTime.compare` for comparison (same instant semantics).
- * - Overlapping intervals return their merged span.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and ARE merged.
+ * - The result is the single run `mergeIntervalsZoned([a, b])` produces, the same rule as
+ *   `mergeIntervals`. Overlapping intervals return their merged span, and each boundary keeps the
+ *   time zone of the interval that contributed it.
+ * - Touching intervals (e.g. `aEnd` the same instant as `bStart`) leave no gap between them and
+ *   ARE merged.
+ * - An empty interval (`start` and `end` the same instant) holds no instant, so it never changes
+ *   the result: with a non-empty interval the answer is that interval, and two empty intervals
+ *   give `null`.
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` on invalid input (wrong type, malformed strings, leap seconds).
- * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152) — but **rejects a mismatched pair**: every endpoint
  *   must name the same calendar system (E7's D4-zoned). Unlike the ordering functions, this one
  *   returns a *value* the caller reads back as a datetime, and there is no principled way to pick
@@ -18,8 +25,7 @@
  *   answer.) A mismatch returns the sentinel.
  * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
  *   copied from an input string (E7's D7-zoned).
- * - Still rejects Temporal's own `[timeZone][u-ca=...]` RFC 9557 ordering — see
- *   `regex/calendar-zoned-date-time.ts`.
+ * - Rejects a calendar annotation before the time zone annotation, which is not RFC 9557.
  *
  * @param aStart ISO 8601 zoned datetime string for the first interval start
  * @param aEnd ISO 8601 zoned datetime string for the first interval end
@@ -28,8 +34,8 @@
  * @returns `{ start, end }` with the merged span, or null on invalid input / disjoint intervals
  *
  * @example intervalUnionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // { start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-12-31T23:59:59+00:00[UTC]" }
- * @example intervalUnionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // { start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-12-31T23:59:59+00:00[UTC]" }
- * @example intervalUnionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-07-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null
+ * @example intervalUnionZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]", "2024-01-01T17:00:00+00:00[UTC]") // { start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-01-01T17:00:00+00:00[UTC]" } (touching)
+ * @example intervalUnionZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]", "2024-01-01T12:00:00.000000001+00:00[UTC]", "2024-01-01T17:00:00+00:00[UTC]") // null (one-nanosecond gap)
  * @example intervalUnionZoned("invalid", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null
  */
 export declare function intervalUnionZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): {

package/dist/zoned/interval/intervalUnionZoned.js

@@ -1,15 +1,23 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { calendarOfAllZonedValues, formatZonedInCalendar, parseCalendarZonedValue, } from "../../internal/index.js";
+import { calendarOfAllZonedValues, formatZonedInCalendar, halfOpenUnion, parseCalendarZonedValue, } from "../../internal/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
 /**
- * Return the combined span of two zoned intervals, or null when they are disjoint.
+ * Return the combined span of two half-open zoned intervals `[start, end)`, or null when their
+ * union is not one non-empty span.
  *
  * - Uses `Temporal.ZonedDateTime.compare` for comparison (same instant semantics).
- * - Overlapping intervals return their merged span.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and ARE merged.
+ * - The result is the single run `mergeIntervalsZoned([a, b])` produces, the same rule as
+ *   `mergeIntervals`. Overlapping intervals return their merged span, and each boundary keeps the
+ *   time zone of the interval that contributed it.
+ * - Touching intervals (e.g. `aEnd` the same instant as `bStart`) leave no gap between them and
+ *   ARE merged.
+ * - An empty interval (`start` and `end` the same instant) holds no instant, so it never changes
+ *   the result: with a non-empty interval the answer is that interval, and two empty intervals
+ *   give `null`.
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` on invalid input (wrong type, malformed strings, leap seconds).
- * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152) — but **rejects a mismatched pair**: every endpoint
  *   must name the same calendar system (E7's D4-zoned). Unlike the ordering functions, this one
  *   returns a *value* the caller reads back as a datetime, and there is no principled way to pick
@@ -21,8 +29,7 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  *   answer.) A mismatch returns the sentinel.
  * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
  *   copied from an input string (E7's D7-zoned).
- * - Still rejects Temporal's own `[timeZone][u-ca=...]` RFC 9557 ordering — see
- *   `regex/calendar-zoned-date-time.ts`.
+ * - Rejects a calendar annotation before the time zone annotation, which is not RFC 9557.
  *
  * @param aStart ISO 8601 zoned datetime string for the first interval start
  * @param aEnd ISO 8601 zoned datetime string for the first interval end
@@ -31,14 +38,14 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  * @returns `{ start, end }` with the merged span, or null on invalid input / disjoint intervals
  *
  * @example intervalUnionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // { start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-12-31T23:59:59+00:00[UTC]" }
- * @example intervalUnionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // { start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-12-31T23:59:59+00:00[UTC]" }
- * @example intervalUnionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-07-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null
+ * @example intervalUnionZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]", "2024-01-01T17:00:00+00:00[UTC]") // { start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-01-01T17:00:00+00:00[UTC]" } (touching)
+ * @example intervalUnionZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]", "2024-01-01T12:00:00.000000001+00:00[UTC]", "2024-01-01T17:00:00+00:00[UTC]") // null (one-nanosecond gap)
  * @example intervalUnionZoned("invalid", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null
  */
 export function intervalUnionZoned(aStart, aEnd, bStart, bEnd) {
     // One gate for all four endpoints: `isValidCalendarZonedDateTime` covers non-strings, empty
     // strings, leap seconds (which Temporal would otherwise silently clamp to :59), unknown zones
-    // and Temporal's forbidden segment ordering, while accepting GMT's calendar-annotated grammar.
+    // and a calendar annotation before the zone, while accepting RFC 9557 calendar annotations.
     if (!isValidCalendarZonedDateTime(aStart) ||
         !isValidCalendarZonedDateTime(aEnd) ||
         !isValidCalendarZonedDateTime(bStart) ||
@@ -62,16 +69,14 @@ export function intervalUnionZoned(aStart, aEnd, bStart, bEnd) {
         if (Temporal.ZonedDateTime.compare(bZdt, bZde) > 0) {
             return null;
         }
-        if (Temporal.ZonedDateTime.compare(aZde, bZdt) < 0 ||
-            Temporal.ZonedDateTime.compare(bZde, aZdt) < 0) {
-            return null;
-        }
-        const start = Temporal.ZonedDateTime.compare(aZdt, bZdt) <= 0 ? aZdt : bZdt;
-        const end = Temporal.ZonedDateTime.compare(aZde, bZde) >= 0 ? aZde : bZde;
-        return {
-            start: formatZonedInCalendar(start, calendar),
-            end: formatZonedInCalendar(end, calendar),
-        };
+        // One merged run, or null when a gap (or no instant at all) leaves no single span.
+        const union = halfOpenUnion({ start: aZdt, end: aZde }, { start: bZdt, end: bZde }, Temporal.ZonedDateTime.compare);
+        return union === null
+            ? null
+            : {
+                start: formatZonedInCalendar(union.start, calendar),
+                end: formatZonedInCalendar(union.end, calendar),
+            };
     }
     catch {
         return null;

package/dist/zoned/interval/intervalXorAllZoned.d.ts

@@ -3,18 +3,20 @@
  * covered by an odd number of the input intervals.
  *
  * - List-form generalization of `intervalXorZoned`, which is pairwise only.
- * - Implemented as a coverage sweep over instants: each interval contributes a `+1` at its
- *   start instant and a `-1` one nanosecond after its end instant; the result is every maximal
- *   run where the running coverage count is odd. For two intervals this reduces to exactly
- *   `intervalXorZoned`'s pairwise result.
- * - Output boundaries carry the time zone of whichever input interval contributed them.
+ * - Intervals are half-open `[start, end)`. The result is every maximal run of instants where the
+ *   coverage count is odd, so touching runs join and an empty interval (`start` and `end` the same
+ *   instant) changes nothing. Every boundary is an input's own `start` or `end`; none is stepped
+ *   by a nanosecond, so an interval may end on the last representable instant. For two intervals
+ *   this is exactly `intervalXorZoned`'s pairwise result.
+ * - Output boundaries carry the time zone of whichever input interval contributed them (the
+ *   earlier one in the list on a tie).
  * - Order of the input list does not matter; the result is sorted by start instant.
  * - Returns `[]` for an empty list, and `[]` when every instant is covered an even number of
  *   times (e.g. two identical intervals cancel out).
  * - Returns `[]` when `intervals` is not an array, when any element is not a
  *   `{ start, end }` record of valid ISO ZonedDateTime strings, or when any element has
  *   `start > end` or a leap-second string.
- * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152) — but **rejects a mismatched set**: every endpoint in
  *   the list must name the same calendar system (E7's D4-zoned). This function returns *values*
  *   the caller reads back as datetimes, and an array whose elements carried different calendar
@@ -25,7 +27,7 @@
  * @param intervals array of `{ start, end }` records
  * @returns array of `{ start, end }` records covered an odd number of times, or `[]` on invalid input
  *
- * @example intervalXorAllZoned([{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-10T00:00:00+00:00[UTC]" }, { start: "2024-01-05T00:00:00+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-04T23:59:59.999999999+00:00[UTC]" }, { start: "2024-01-10T00:00:00.000000001+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]
+ * @example intervalXorAllZoned([{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-10T00:00:00+00:00[UTC]" }, { start: "2024-01-05T00:00:00+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-05T00:00:00+00:00[UTC]" }, { start: "2024-01-10T00:00:00+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]
  * @example intervalXorAllZoned([]) // []
  */
 export declare function intervalXorAllZoned(intervals: Array<{

package/dist/zoned/interval/intervalXorAllZoned.js

@@ -1,23 +1,26 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { calendarOfAllZonedValues, formatZonedInCalendar, parseCalendarZonedValue, } from "../../internal/index.js";
+import { calendarOfAllZonedValues, formatZonedInCalendar, halfOpenXor, parseCalendarZonedValue, } from "../../internal/index.js";
 import { isValidCalendarZonedInterval } from "./validate/index.js";
 /**
  * Return the symmetric difference across a list of zoned intervals — the set of instants
  * covered by an odd number of the input intervals.
  *
  * - List-form generalization of `intervalXorZoned`, which is pairwise only.
- * - Implemented as a coverage sweep over instants: each interval contributes a `+1` at its
- *   start instant and a `-1` one nanosecond after its end instant; the result is every maximal
- *   run where the running coverage count is odd. For two intervals this reduces to exactly
- *   `intervalXorZoned`'s pairwise result.
- * - Output boundaries carry the time zone of whichever input interval contributed them.
+ * - Intervals are half-open `[start, end)`. The result is every maximal run of instants where the
+ *   coverage count is odd, so touching runs join and an empty interval (`start` and `end` the same
+ *   instant) changes nothing. Every boundary is an input's own `start` or `end`; none is stepped
+ *   by a nanosecond, so an interval may end on the last representable instant. For two intervals
+ *   this is exactly `intervalXorZoned`'s pairwise result.
+ * - Output boundaries carry the time zone of whichever input interval contributed them (the
+ *   earlier one in the list on a tie).
  * - Order of the input list does not matter; the result is sorted by start instant.
  * - Returns `[]` for an empty list, and `[]` when every instant is covered an even number of
  *   times (e.g. two identical intervals cancel out).
  * - Returns `[]` when `intervals` is not an array, when any element is not a
  *   `{ start, end }` record of valid ISO ZonedDateTime strings, or when any element has
  *   `start > end` or a leap-second string.
- * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152) — but **rejects a mismatched set**: every endpoint in
  *   the list must name the same calendar system (E7's D4-zoned). This function returns *values*
  *   the caller reads back as datetimes, and an array whose elements carried different calendar
@@ -28,81 +31,47 @@ import { isValidCalendarZonedInterval } from "./validate/index.js";
  * @param intervals array of `{ start, end }` records
  * @returns array of `{ start, end }` records covered an odd number of times, or `[]` on invalid input
  *
- * @example intervalXorAllZoned([{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-10T00:00:00+00:00[UTC]" }, { start: "2024-01-05T00:00:00+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-04T23:59:59.999999999+00:00[UTC]" }, { start: "2024-01-10T00:00:00.000000001+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]
+ * @example intervalXorAllZoned([{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-10T00:00:00+00:00[UTC]" }, { start: "2024-01-05T00:00:00+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-05T00:00:00+00:00[UTC]" }, { start: "2024-01-10T00:00:00+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]
  * @example intervalXorAllZoned([]) // []
  */
 export function intervalXorAllZoned(intervals) {
-    if (!Array.isArray(intervals) || intervals.length === 0) {
-        return [];
-    }
-    if (!intervals.every((interval) => interval &&
-        typeof interval === "object" &&
-        typeof interval.start === "string" &&
-        typeof interval.end === "string" &&
-        isValidCalendarZonedInterval(interval.start, interval.end))) {
-        return [];
-    }
-    // D4-zoned reject gate: every endpoint across every interval must agree on a calendar, or there
-    // is no calendar to express the returned boundaries in.
-    const calendar = calendarOfAllZonedValues(intervals.flatMap((interval) => [interval.start, interval.end]));
-    if (!calendar) {
-        return [];
-    }
     try {
-        const events = [];
-        for (const interval of intervals) {
-            const startVal = parseCalendarZonedValue(interval.start);
-            const endVal = parseCalendarZonedValue(interval.end);
-            const closesAfter = endVal.toInstant().add({ nanoseconds: 1 });
-            events.push({
-                instant: startVal.toInstant(),
-                boundary: startVal,
-                delta: 1,
-            });
-            events.push({
-                instant: closesAfter,
-                boundary: closesAfter.toZonedDateTimeISO(endVal.timeZoneId),
-                delta: -1,
-            });
+        if (!Array.isArray(intervals) || intervals.length === 0) {
+            return [];
+        }
+        if (!intervals.every((interval) => interval &&
+            typeof interval === "object" &&
+            typeof interval.start === "string" &&
+            typeof interval.end === "string" &&
+            isValidCalendarZonedInterval(interval.start, interval.end))) {
+            return [];
+        }
+        // D4-zoned reject gate: every endpoint across every interval must agree on a calendar, or there
+        // is no calendar to express the returned boundaries in.
+        const calendar = calendarOfAllZonedValues(intervals.flatMap((interval) => [interval.start, interval.end]));
+        if (!calendar) {
+            return [];
         }
-        events.sort((a, b) => Temporal.Instant.compare(a.instant, b.instant));
-        const grouped = [];
-        for (const event of events) {
-            const last = grouped[grouped.length - 1];
-            // Safe: `.equals()` here is `Temporal.Instant.prototype.equals`, and `Instant` carries no
-            // calendar field at all — verified calendar-blind (`heb.toInstant().equals(iso.toInstant())`
-            // is `true` for the same instant, while `ZonedDateTime.prototype.equals` is not). E7
-            // re-audited this site rather than inheriting E5's "structurally unreachable" verdict, which
-            // depended on mixed calendars never reaching `zoned/` at all.
-            if (last && last.instant.equals(event.instant)) {
-                last.delta += event.delta;
-            }
-            else {
-                grouped.push(event);
-            }
+        try {
+            const parsed = intervals.map((interval) => ({
+                start: parseCalendarZonedValue(interval.start),
+                end: parseCalendarZonedValue(interval.end),
+            }));
+            // Ordering and grouping use `Temporal.ZonedDateTime.compare`, which compares epoch nanoseconds
+            // only — calendar- and zone-blind, unlike `ZonedDateTime.prototype.equals`. Each boundary stays
+            // the ZonedDateTime of the input that contributed it, so it is formatted in that input's zone.
+            return halfOpenXor(parsed, Temporal.ZonedDateTime.compare).map(({ start, end }) => ({
+                start: formatZonedInCalendar(start, calendar),
+                end: formatZonedInCalendar(end, calendar),
+            }));
         }
-        const result = [];
-        let coverage = 0;
-        let runStart = null;
-        for (const group of grouped) {
-            const previousCoverage = coverage;
-            coverage += group.delta;
-            if (previousCoverage % 2 === 0 && coverage % 2 === 1) {
-                runStart = group.boundary;
-            }
-            else if (previousCoverage % 2 === 1 && coverage % 2 === 0 && runStart) {
-                result.push({
-                    start: formatZonedInCalendar(runStart, calendar),
-                    end: formatZonedInCalendar(group.instant
-                        .subtract({ nanoseconds: 1 })
-                        .toZonedDateTimeISO(group.boundary.timeZoneId), calendar),
-                });
-                runStart = null;
-            }
+        catch {
+            return [];
         }
-        return result;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

package/dist/zoned/interval/intervalXorZoned.d.ts

@@ -1,13 +1,23 @@
 /**
- * Return the symmetric difference of two zoned intervals — time covered by exactly one interval.
+ * Return the symmetric difference of two half-open zoned intervals `[start, end)` — the instants
+ * covered by exactly one interval.
  *
- * - Uses `Temporal.Instant.compare` for comparison (via `.toInstant()`).
- * - Returns `[]` when intervals are identical or both invalid.
- * - Returns `[{ start, end }]` when one interval fully contains the other.
- * - Returns `[{ start, end }, { start, end }]` when intervals partially overlap.
+ * - Compares instants (`Temporal.ZonedDateTime.compare`, calendar- and zone-blind).
+ * - The result is every maximal run covered by exactly one interval, sorted by start instant — the
+ *   same as `mergeIntervals` of `subtractIntervals(a, [b])` and `subtractIntervals(b, [a])`, and
+ *   the same as `intervalXorAllZoned([a, b])`.
+ * - Every boundary is an input's own `start` or `end`, in that input's time zone (the first
+ *   interval's on a tie); no boundary is stepped by a nanosecond.
+ * - Touching intervals share no instant, so they join into one run. An empty interval (`start`
+ *   and `end` the same instant) holds no instant and changes nothing.
+ * - Returns `[]` when the intervals are identical.
+ * - Returns `[{ start, end }]` when the intervals share a start or an end, or touch.
+ * - Returns `[{ start, end }, { start, end }]` when they partially overlap, when one strictly
+ *   contains the other (the piece before B and the piece after B), or when they are disjoint with
+ *   a gap.
  * - Returns `[]` if either interval is invalid (`start > end`).
  * - Returns `[]` on invalid input (wrong type, malformed strings, leap seconds).
- * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152) — but **rejects a mismatched pair**: every endpoint
  *   must name the same calendar system (E7's D4-zoned). Unlike the ordering functions, this one
  *   returns a *value* the caller reads back as a datetime, and there is no principled way to pick
@@ -19,8 +29,7 @@
  *   answer.) A mismatch returns the sentinel.
  * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
  *   copied from an input string (E7's D7-zoned).
- * - Still rejects Temporal's own `[timeZone][u-ca=...]` RFC 9557 ordering — see
- *   `regex/calendar-zoned-date-time.ts`.
+ * - Rejects a calendar annotation before the time zone annotation, which is not RFC 9557.
  *
  * @param aStart ISO 8601 zoned datetime string for the first interval start
  * @param aEnd ISO 8601 zoned datetime string for the first interval end
@@ -28,8 +37,9 @@
  * @param bEnd ISO 8601 zoned datetime string for the second interval end
  * @returns array of `{ start, end }` records representing the symmetric difference, or `[]` on invalid input
  *
- * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-04-01T11:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-03-31T17:00:00+00:00[UTC]" }, { start: "2024-06-30T12:00:01+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
- * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-04-01T11:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-03-31T17:00:00+00:00[UTC]" }, { start: "2024-06-30T12:00:01+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
+ * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-04-01T11:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // partial overlap — [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-04-01T11:00:00+00:00[UTC]" }, { start: "2024-06-30T12:00:00+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
+ * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-02-01T08:00:00+00:00[UTC]", "2024-03-01T10:00:00+00:00[UTC]") // B strictly inside A — two remainder pieces — [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-02-01T08:00:00+00:00[UTC]" }, { start: "2024-03-01T10:00:00+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
+ * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // touching intervals join — [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
  * @example intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // []
  * @example intervalXorZoned("invalid", "2024-06-30T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // []
  */