@northguild/gmt 1.16.0 → 1.18.0

package/dist/internal/zonedTransitionSearch.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The sampling step: 5 days. It must stay under the smallest gap between two offset changes of
+ * one zone, 601,200 s in tz 2026c (`zdump -v`, America/Boa_Vista 2000-10-08 to 2000-10-15).
+ */
+export declare const TRANSITION_SEARCH_STEP_NANOSECONDS: bigint;
+/**
+ * TC39 `GetNamedTimeZoneNextTransition`: the first offset change strictly after `from`.
+ *
+ * @param timeZone a named zone
+ * @param from the instant to search after (exclusive)
+ * @param until optional: the last instant to search (inclusive); a later change returns null
+ * @returns the change's epoch nanoseconds, or null when there is none up to `until` or none within
+ *   three years of the later of `from` and the current instant
+ * @throws RangeError past `MAX_SEARCH_STEPS` steps
+ */
+export declare function nextTransitionAfter(timeZone: string, from: bigint, until?: bigint): bigint | null;
+/**
+ * TC39 `GetNamedTimeZonePreviousTransition`: the last offset change strictly before `from`.
+ *
+ * @param timeZone a named zone
+ * @param from the instant to search before (exclusive)
+ * @param since optional: the search stops here (exclusive); an earlier change returns null
+ * @returns the change's epoch nanoseconds, or null when there is none after `since`, or, with no
+ *   `since`, none at all
+ * @throws RangeError past `MAX_SEARCH_STEPS` steps or `MAX_TABLED_TRANSITIONS` tabled changes
+ */
+export declare function previousTransitionBefore(timeZone: string, from: bigint, since?: bigint): bigint | null;

package/dist/internal/zonedTransitionSearch.js

@@ -0,0 +1,218 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { MAX_EPOCH_NANOSECONDS, MIN_EPOCH_NANOSECONDS, } from "./epochNanoseconds.js";
+import { POLYFILL_TRANSITION_SEARCH_FLOOR, missedNextTransition, missedPreviousTransition, offsetAt, transitionBetween, } from "./zonedWallClock.js";
+/*
+ * ---------------------------------------------------------------------------------------------
+ * GMT's own time zone transition search (temporalCompat D13; `zonedWallClock.ts` defect 5)
+ * ---------------------------------------------------------------------------------------------
+ * TC39 `GetNamedTimeZoneNextTransition` / `GetNamedTimeZonePreviousTransition`: the first offset
+ * change strictly after an instant, and the last strictly before it. `@js-temporal/polyfill`
+ * 0.5.1 samples the offset every 14 days and bisects a step whose ends differ. Two changes inside
+ * one step break it: a pair that returns to the same offset is skipped (America/Boa_Vista,
+ * 2000-10-08 and 2000-10-15), and three different offsets make its bisection loop forever
+ * (Europe/Riga, 1944-10-02 and 1944-10-12).
+ *
+ * This search samples the same way with a step shorter than any gap between two changes in the
+ * tz database, so a step holds at most one change: equal ends mean none, different ends mean
+ * exactly one, and bisecting it always narrows.
+ *
+ * The sampling assumption, pinned by the all-zones guard in `zonedTransitionSearch.test.ts`: no
+ * zone changes its offset twice within `TRANSITION_SEARCH_STEP_NANOSECONDS`. The closest pair in
+ * tz 2026c is 601,200 s apart (America/Boa_Vista, Noronha and Recife in 2000; Asia/Gaza and
+ * Asia/Hebron in 2040), measured with `zdump -v`. The step is 432,000 s (5 days), 169,200 s
+ * under that. A tz release with a closer pair fails the guard.
+ *
+ * "No further change" follows the polyfill's own rule, so removal changes no answer: a forward
+ * search stops three 366-day years past the later of its start and the current instant, and a
+ * backward search stops at 1847-01-01, before which the one earlier change a zone can have is
+ * found by comparing offsets (`missedNextTransition`, `missedPreviousTransition`).
+ *
+ * Bounds, in offset reads (one `Intl` read each):
+ * - a limit instant only shortens a search; the horizon above applies with or without one, so a
+ *   limit thousands of years away costs no more than none. Within the horizon: one read per 5
+ *   days of the limit, plus at most 51 to pin the change. The daylight rule passes 365 days: at
+ *   most 74 + 51 reads.
+ * - forward: at most the steps from the start (1847 at the earliest) to three years past the later
+ *   of the start and today, about 13,400 from 1847 and 220 from any later start; a system clock
+ *   set absurdly far ahead stops at `MAX_SEARCH_STEPS` (200,000) with a RangeError.
+ * - backward: the same span, down to 1847. From more than three years past today: 220 reads over
+ *   the three years before the instant; if nothing is there, one backward search from three years
+ *   past today and then at most `MAX_TABLED_TRANSITIONS` (1,000) forward searches, then a
+ *   RangeError.
+ *
+ * Removed with the D13 workaround: see `temporalCompat/README.md`.
+ * ---------------------------------------------------------------------------------------------
+ */
+const NANOSECONDS_PER_SECOND = 1000000000n;
+const NANOSECONDS_PER_DAY = 86400n * NANOSECONDS_PER_SECOND;
+/**
+ * The sampling step: 5 days. It must stay under the smallest gap between two offset changes of
+ * one zone, 601,200 s in tz 2026c (`zdump -v`, America/Boa_Vista 2000-10-08 to 2000-10-15).
+ */
+export const TRANSITION_SEARCH_STEP_NANOSECONDS = 432000n * NANOSECONDS_PER_SECOND;
+/**
+ * js-temporal `GetNamedTimeZoneNextTransition`: "the farthest that we'll look for a next
+ * transition is 3 years after the later of epochNanoseconds or the current time"
+ * (`DAY_MS * 366 * 3`).
+ */
+const NO_FURTHER_TRANSITION_HORIZON_NANOSECONDS = 3n * 366n * NANOSECONDS_PER_DAY;
+/** Steps one search may take: 200,000 five-day steps is 2,700 years. */
+const MAX_SEARCH_STEPS = 200_000;
+/** Forward searches when walking a zone's tabled future changes; Africa/Casablanca has about 120. */
+const MAX_TABLED_TRANSITIONS = 1_000;
+/** Halvings to pin a whole second inside one step: 2^19 s is more than 5 days. */
+const MAX_SECOND_BISECTION_STEPS = 20;
+function minimum(a, b) {
+    return a < b ? a : b;
+}
+function maximum(a, b) {
+    return a > b ? a : b;
+}
+function floorSecond(epochNanoseconds) {
+    const seconds = epochNanoseconds / NANOSECONDS_PER_SECOND;
+    return epochNanoseconds % NANOSECONDS_PER_SECOND < 0n
+        ? seconds - 1n
+        : seconds;
+}
+/**
+ * The one change in `(low, high]`, given that the offsets at the two ends differ and the window is
+ * no longer than a step. tz changes fall on whole seconds (RFC 9636 §3.2 stores transition times in
+ * seconds), so the search runs over seconds; the result is checked one nanosecond earlier, and a
+ * change that is not on a whole second is pinned to the nanosecond instead.
+ */
+function changeBetween(timeZone, low, high, lowOffset, highOffset) {
+    let before = floorSecond(low);
+    let after = floorSecond(high);
+    for (let i = 0; i < MAX_SECOND_BISECTION_STEPS && after - before > 1n; i++) {
+        const middle = (before + after) / 2n;
+        if (offsetAt(timeZone, middle * NANOSECONDS_PER_SECOND) === lowOffset) {
+            before = middle;
+        }
+        else {
+            after = middle;
+        }
+    }
+    const change = after * NANOSECONDS_PER_SECOND;
+    if (after - before === 1n &&
+        change > low &&
+        offsetAt(timeZone, change) === highOffset &&
+        offsetAt(timeZone, change - 1n) === lowOffset) {
+        return change;
+    }
+    return transitionBetween(timeZone, low, high, highOffset);
+}
+function currentEpochNanoseconds() {
+    return Temporal.Now.instant().epochNanoseconds;
+}
+/**
+ * TC39 `GetNamedTimeZoneNextTransition`: the first offset change strictly after `from`.
+ *
+ * @param timeZone a named zone
+ * @param from the instant to search after (exclusive)
+ * @param until optional: the last instant to search (inclusive); a later change returns null
+ * @returns the change's epoch nanoseconds, or null when there is none up to `until` or none within
+ *   three years of the later of `from` and the current instant
+ * @throws RangeError past `MAX_SEARCH_STEPS` steps
+ */
+export function nextTransitionAfter(timeZone, from, until) {
+    // The horizon holds with or without a limit, as it does when the polyfill answers and the
+    // limit only filters its result.
+    const horizon = maximum(from, currentEpochNanoseconds()) +
+        NO_FURTHER_TRANSITION_HORIZON_NANOSECONDS;
+    const end = minimum(MAX_EPOCH_NANOSECONDS, until === undefined ? horizon : minimum(until, horizon));
+    if (from >= end)
+        return null;
+    let low = from;
+    if (low < POLYFILL_TRANSITION_SEARCH_FLOOR) {
+        const missed = missedNextTransition(timeZone, low);
+        if (missed !== null)
+            return missed <= end ? missed : null;
+        if (end <= POLYFILL_TRANSITION_SEARCH_FLOOR)
+            return null;
+        low = POLYFILL_TRANSITION_SEARCH_FLOOR;
+    }
+    const lowOffset = offsetAt(timeZone, low);
+    for (let i = 0; i < MAX_SEARCH_STEPS; i++) {
+        const high = minimum(low + TRANSITION_SEARCH_STEP_NANOSECONDS, end);
+        const highOffset = offsetAt(timeZone, high);
+        if (highOffset !== lowOffset) {
+            return changeBetween(timeZone, low, high, lowOffset, highOffset);
+        }
+        if (high >= end)
+            return null;
+        low = high;
+    }
+    throw new RangeError(`Transition search in ${timeZone} ran past its bound`);
+}
+/** The last change in `(since, start]`, scanning back from `start`; null when there is none. */
+function lastChangeBack(timeZone, start, since) {
+    let high = start;
+    const highOffset = offsetAt(timeZone, high);
+    for (let i = 0; i < MAX_SEARCH_STEPS; i++) {
+        if (high <= since)
+            return null;
+        const low = maximum(high - TRANSITION_SEARCH_STEP_NANOSECONDS, since);
+        const lowOffset = offsetAt(timeZone, low);
+        if (lowOffset !== highOffset) {
+            return changeBetween(timeZone, low, high, lowOffset, highOffset);
+        }
+        high = low;
+    }
+    throw new RangeError(`Transition search in ${timeZone} ran past its bound`);
+}
+/**
+ * The last change before an instant more than three years past the current one. The polyfill's
+ * rule: when the zone has no change between now and three years from now, there is none later, so
+ * the answer is the last change before that horizon. A zone whose rules repeat has one in the
+ * three years before `from`. Otherwise its future changes are a finite table (Africa/Casablanca,
+ * to 2087), walked forward to its end. A change at or before `since` is not looked for.
+ */
+function previousTransitionFarAhead(timeZone, from, now, since) {
+    const recentStart = from - NO_FURTHER_TRANSITION_HORIZON_NANOSECONDS;
+    const recent = lastChangeBack(timeZone, from - 1n, since === undefined ? recentStart : maximum(since, recentStart));
+    if (recent !== null)
+        return recent;
+    if (since !== undefined && since >= recentStart)
+        return null;
+    const horizon = now + NO_FURTHER_TRANSITION_HORIZON_NANOSECONDS;
+    let last = previousTransitionBefore(timeZone, horizon, since);
+    if (last === null || last < now)
+        return last;
+    for (let i = 0; i < MAX_TABLED_TRANSITIONS; i++) {
+        const next = nextTransitionAfter(timeZone, last);
+        if (next === null || next >= from)
+            return last;
+        last = next;
+    }
+    throw new RangeError(`Transition walk in ${timeZone} ran past its bound`);
+}
+/**
+ * TC39 `GetNamedTimeZonePreviousTransition`: the last offset change strictly before `from`.
+ *
+ * @param timeZone a named zone
+ * @param from the instant to search before (exclusive)
+ * @param since optional: the search stops here (exclusive); an earlier change returns null
+ * @returns the change's epoch nanoseconds, or null when there is none after `since`, or, with no
+ *   `since`, none at all
+ * @throws RangeError past `MAX_SEARCH_STEPS` steps or `MAX_TABLED_TRANSITIONS` tabled changes
+ */
+export function previousTransitionBefore(timeZone, from, since) {
+    if (from <= MIN_EPOCH_NANOSECONDS)
+        return null;
+    // The horizon holds with or without a limit: see `nextTransitionAfter`.
+    const now = currentEpochNanoseconds();
+    if (from - 1n > now + NO_FURTHER_TRANSITION_HORIZON_NANOSECONDS) {
+        return previousTransitionFarAhead(timeZone, from, now, since);
+    }
+    const floor = maximum(since ?? POLYFILL_TRANSITION_SEARCH_FLOOR, POLYFILL_TRANSITION_SEARCH_FLOOR);
+    const found = from - 1n > floor ? lastChangeBack(timeZone, from - 1n, floor) : null;
+    if (found !== null)
+        return found;
+    if (since !== undefined && since >= POLYFILL_TRANSITION_SEARCH_FLOOR) {
+        return null;
+    }
+    const missed = missedPreviousTransition(timeZone, from);
+    return missed !== null && (since === undefined || missed > since)
+        ? missed
+        : null;
+}

package/dist/internal/zonedWallClock.d.ts

@@ -15,8 +15,6 @@ type ResolvedOffsetOption = NonNullable<Offset>;
 export type CarriedOffset = "absent" | "out-of-range" | {
     nanoseconds: bigint;
 };
-/** TC39 `CheckISODaysRange`: a date may sit at most 10^8 days from the Unix epoch. */
-export declare const MAX_ISO_EPOCH_DAYS = 100000000;
 /**
  * `getTimeZoneTransition("next")` looks at most three years (366-day years) past its receiver;
  * a `null` from further than this from the maximum is the polyfill's own horizon, not defect 2.
@@ -35,21 +33,34 @@ export declare function isNearRangeEdge(date: Temporal.PlainDate): boolean;
 export declare function isNamedTimeZone(timeZone: string): boolean;
 /** TC39 `IsValidEpochNanoseconds`. */
 export declare function isValidEpoch(epochNanoseconds: bigint): boolean;
+/** UTC offset in force at an instant, reading the nearest limit for an instant outside the range. */
+export declare function offsetAt(timeZone: string, epochNanoseconds: bigint): bigint;
 /** TC39 `GetUTCEpochNanoseconds`: the wall clock read as if it were UTC (may lie outside the range). */
 export declare function utcEpochNanoseconds(wall: Temporal.PlainDateTime): bigint;
 /** TC39 `GetEpochNanosecondsFor`. */
 export declare function epochNanosecondsFor(timeZone: string, wall: Temporal.PlainDateTime, disambiguation: ResolvedDisambiguation): bigint;
+/**
+ * The first instant at or after `low` whose offset is `offset`, given that `low` has a different
+ * offset and `high` has `offset`: the transition between them, to the nanosecond.
+ */
+export declare function transitionBetween(timeZone: string, low: bigint, high: bigint, offset: bigint): bigint;
 /**
  * TC39 `GetStartOfDay`: the first valid wall-clock time on `date` in `timeZone` — midnight, or,
  * when midnight is skipped, the transition that skips it.
  */
 export declare function startOfDayEpochNanoseconds(timeZone: string, date: Temporal.PlainDate): bigint;
 /**
- * True when a start of day on this local date — or, for a zoned value, on its own local date —
- * may lie before the polyfill's transition search floor, so the polyfill's `GetStartOfDay` can
- * miss a transition that skips it. A zoned value from 1847-01-03T00:00Z on reads no offset.
+ * True when the polyfill's `GetStartOfDay` cannot be trusted for this date in a named zone: it
+ * lies before the transition search floor (defect 3), or its midnight is skipped while the
+ * runtime's transition search can miss the change that skips it (defect 5). A midnight that exists
+ * never reaches that search, so the polyfill's answer stands for it.
+ */
+export declare function needsOwnStartOfDaySearch(timeZone: string, value: Temporal.PlainDate | Temporal.ZonedDateTime): boolean;
+/**
+ * `needsOwnStartOfDaySearch` for a measure that also reads the next day's start (`hoursInDay`,
+ * rounding to the day).
  */
-export declare function isBeforePolyfillTransitionSearch(value: Temporal.PlainDate | Temporal.ZonedDateTime): boolean;
+export declare function needsOwnDayBoundsSearch(timeZone: string, zoned: Temporal.ZonedDateTime): boolean;
 /**
  * The first transition after `epochNanoseconds` in a named zone when it lies before the polyfill's
  * search floor, which `getTimeZoneTransition("next")` skips; null for any instant at or after the
@@ -63,6 +74,8 @@ export declare function missedNextTransition(timeZone: string, epochNanoseconds:
  * never changes between the minimum instant and there.
  */
 export declare function missedPreviousTransition(timeZone: string, epochNanoseconds: bigint): bigint | null;
+/** TC39 `RoundNumberToIncrement(value, 1 minute, "half-expand")`. */
+export declare function roundToMinute(nanoseconds: bigint): bigint;
 /** TC39 `InterpretISODateTimeOffset` for a named zone and a wall clock with a time of day. */
 export declare function interpretISODateTimeOffset(timeZone: string, wall: Temporal.PlainDateTime, offset: CarriedOffset, disambiguation: ResolvedDisambiguation, offsetOption: ResolvedOffsetOption, matchMinutes: boolean): bigint;
 /** A zone id as Temporal canonicalizes it, from an identifier or any RFC 9557 string. */
@@ -74,7 +87,8 @@ export declare function utcOffsetStringNanoseconds(offset: string): bigint;
  *
  * Returns the polyfill's result whenever it has one. When the polyfill throws for a named zone
  * within a month of either range limit, the TC39 result is recomputed (see the note at the top
- * of this file); every other failure re-throws the polyfill's own error.
+ * of this file); every other failure re-throws the polyfill's own error. A string whose offset
+ * is written with seconds is matched exactly, as TC39 requires (`matchSecondsOffsetExactly`).
  *
  * @param item RFC 9557 zoned string or ZonedDateTime-like property bag
  * @param options Temporal `disambiguation` / `offset` / `overflow`

package/dist/internal/zonedWallClock.js

@@ -1,9 +1,9 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { MAX_EPOCH_NANOSECONDS, MIN_EPOCH_NANOSECONDS, } from "./epochNanoseconds.js";
+import { MAX_EPOCH_NANOSECONDS, MAX_ISO_EPOCH_DAYS, MIN_EPOCH_NANOSECONDS, } from "./epochNanoseconds.js";
+import { isSecondsOffsetMatchCompatNeeded, isTransitionSearchCompatNeeded, } from "./temporalCompat/index.js";
+import { optionOrDefault } from "./optionOrDefault.js";
 const NANOSECONDS_PER_DAY = 86400000000000n;
 const NANOSECONDS_PER_MINUTE = 60000000000n;
-/** TC39 `CheckISODaysRange`: a date may sit at most 10^8 days from the Unix epoch. */
-export const MAX_ISO_EPOCH_DAYS = 100_000_000;
 /**
  * Dates this many days from a range limit are the only ones either defect reaches: defect 1 needs
  * a wall clock within a day of the limit, defect 2 a transition within the scan's two-week step.
@@ -74,7 +74,7 @@ function clampEpoch(epochNanoseconds) {
     return epochNanoseconds;
 }
 /** UTC offset in force at an instant, reading the nearest limit for an instant outside the range. */
-function offsetAt(timeZone, epochNanoseconds) {
+export function offsetAt(timeZone, epochNanoseconds) {
     return BigInt(new Temporal.ZonedDateTime(clampEpoch(epochNanoseconds), timeZone)
         .offsetNanoseconds);
 }
@@ -158,7 +158,7 @@ export function epochNanosecondsFor(timeZone, wall, disambiguation) {
  * The first instant at or after `low` whose offset is `offset`, given that `low` has a different
  * offset and `high` has `offset`: the transition between them, to the nanosecond.
  */
-function transitionBetween(timeZone, low, high, offset) {
+export function transitionBetween(timeZone, low, high, offset) {
     if (offsetAt(timeZone, high) !== offset ||
         offsetAt(timeZone, low) === offset) {
         throw new RangeError(`No transition in ${timeZone} between the bounds`);
@@ -203,13 +203,52 @@ export function startOfDayEpochNanoseconds(timeZone, date) {
  * may lie before the polyfill's transition search floor, so the polyfill's `GetStartOfDay` can
  * miss a transition that skips it. A zoned value from 1847-01-03T00:00Z on reads no offset.
  */
-export function isBeforePolyfillTransitionSearch(value) {
+function isBeforePolyfillTransitionSearch(value) {
     if (value instanceof Temporal.ZonedDateTime) {
         return (value.epochNanoseconds < FIRST_INSTANT_AFTER_TRANSITION_SEARCH_DATE &&
             isBeforePolyfillTransitionSearch(value.toPlainDate()));
     }
     return (Temporal.PlainDate.compare(value, LAST_DATE_BEFORE_TRANSITION_SEARCH) <= 0);
 }
+/** True when no instant in `timeZone` has `date`'s midnight as its wall time (it is skipped). */
+function isMidnightSkipped(timeZone, date) {
+    try {
+        return (possibleEpochNanoseconds(timeZone, date.withCalendar("iso8601").toPlainDateTime()).length === 0);
+    }
+    catch {
+        // Outside the representable range: the range-limit fallbacks decide.
+        return false;
+    }
+}
+/**
+ * True when the polyfill's `GetStartOfDay` cannot be trusted for this date in a named zone: it
+ * lies before the transition search floor (defect 3), or its midnight is skipped while the
+ * runtime's transition search can miss the change that skips it (defect 5). A midnight that exists
+ * never reaches that search, so the polyfill's answer stands for it.
+ */
+export function needsOwnStartOfDaySearch(timeZone, value) {
+    if (isBeforePolyfillTransitionSearch(value))
+        return true;
+    if (!isTransitionSearchCompatNeeded())
+        return false;
+    return isMidnightSkipped(timeZone, value instanceof Temporal.ZonedDateTime ? value.toPlainDate() : value);
+}
+/**
+ * `needsOwnStartOfDaySearch` for a measure that also reads the next day's start (`hoursInDay`,
+ * rounding to the day).
+ */
+export function needsOwnDayBoundsSearch(timeZone, zoned) {
+    if (needsOwnStartOfDaySearch(timeZone, zoned))
+        return true;
+    if (!isTransitionSearchCompatNeeded())
+        return false;
+    try {
+        return isMidnightSkipped(timeZone, zoned.toPlainDate().add({ days: 1 }));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The first transition after `epochNanoseconds` in a named zone when it lies before the polyfill's
  * search floor, which `getTimeZoneTransition("next")` skips; null for any instant at or after the
@@ -241,7 +280,7 @@ export function missedPreviousTransition(timeZone, epochNanoseconds) {
     return transitionBetween(timeZone, MIN_EPOCH_NANOSECONDS, high, highOffset);
 }
 /** TC39 `RoundNumberToIncrement(value, 1 minute, "half-expand")`. */
-function roundToMinute(nanoseconds) {
+export function roundToMinute(nanoseconds) {
     const sign = nanoseconds < 0n ? -1n : 1n;
     const magnitude = nanoseconds * sign;
     const quotient = magnitude / NANOSECONDS_PER_MINUTE;
@@ -303,14 +342,17 @@ export function utcOffsetStringNanoseconds(offset) {
     const utcMidnight = Temporal.ZonedDateTime.from({ year: 1970, month: 1, day: 1, timeZone: "UTC", offset }, { offset: "use" });
     return -utcMidnight.epochNanoseconds;
 }
-/** The epoch nanoseconds of a zoned string near the range limits, or null when out of scope. */
+/**
+ * TC39 `ToTemporalZonedDateTime` for a zoned string in a named zone, from the wall clock and
+ * zone Temporal has already parsed: the epoch nanoseconds the string names. Used where the
+ * polyfill's own answer is unusable: near the range limits (defect 1) and for an offset written
+ * with seconds (defect 4).
+ */
 function stringEpochAtEdge(item, timeZone, wall, options) {
     if (!TIME_SEPARATOR.test(item)) {
         return startOfDayEpochNanoseconds(timeZone, wall.toPlainDate());
     }
-    const disambiguation = options?.disambiguation === undefined
-        ? "compatible"
-        : options.disambiguation;
+    const disambiguation = optionOrDefault(options?.disambiguation, "compatible");
     if (!UTC_OFFSET.test(item)) {
         return epochNanosecondsFor(timeZone, wall, disambiguation);
     }
@@ -325,7 +367,7 @@ function stringEpochAtEdge(item, timeZone, wall, options) {
         // The grammar is already proven valid, so only the string's own instant can be out of range.
         offset = "out-of-range";
     }
-    return interpretISODateTimeOffset(timeZone, wall, offset, disambiguation, options?.offset === undefined ? "reject" : options.offset, !UTC_OFFSET_WITH_SECONDS.test(item));
+    return interpretISODateTimeOffset(timeZone, wall, offset, disambiguation, optionOrDefault(options?.offset, "reject"), !UTC_OFFSET_WITH_SECONDS.test(item));
 }
 function fromStringAtEdge(item, options) {
     let wall;
@@ -367,9 +409,7 @@ function fromBagAtEdge(item, options) {
     if (!isNamedTimeZone(timeZone) || !isNearRangeEdge(wall.toPlainDate())) {
         return null;
     }
-    const epoch = interpretISODateTimeOffset(timeZone, wall, offset, options?.disambiguation === undefined
-        ? "compatible"
-        : options.disambiguation, options?.offset === undefined ? "reject" : options.offset, false);
+    const epoch = interpretISODateTimeOffset(timeZone, wall, offset, optionOrDefault(options?.disambiguation, "compatible"), optionOrDefault(options?.offset, "reject"), false);
     return new Temporal.ZonedDateTime(epoch, timeZone, wall.calendarId);
 }
 /**
@@ -389,17 +429,43 @@ function dateOnlyBeforeTransitionSearch(item, options) {
     catch {
         return null;
     }
-    if (!isNamedTimeZone(timeZone) || !isBeforePolyfillTransitionSearch(date)) {
+    if (!isNamedTimeZone(timeZone) || !needsOwnStartOfDaySearch(timeZone, date)) {
         return null;
     }
     return new Temporal.ZonedDateTime(startOfDayEpochNanoseconds(timeZone, date), timeZone, date.calendarId);
 }
+/**
+ * The polyfill's result for a zoned string, or the TC39 result when the polyfill matched an
+ * offset written with seconds by minutes (defect 4, temporalCompat D12).
+ *
+ * Dormant unless the D12 probe fails. Then it acts only on a string whose offset has a seconds
+ * part, read with `offset: "reject"` or `"prefer"` (the two options that match the offset
+ * against the zone), whose result has a sub-minute offset: any other result was matched exactly,
+ * because an earlier candidate would have matched by rounding first. For those it recomputes
+ * `InterpretISODateTimeOffset` with match-exactly, which throws a `RangeError` under `"reject"`
+ * when no candidate has the written offset.
+ */
+function matchSecondsOffsetExactly(item, zoned, options) {
+    if (!UTC_OFFSET_WITH_SECONDS.test(item) ||
+        BigInt(zoned.offsetNanoseconds) % NANOSECONDS_PER_MINUTE === 0n ||
+        options?.offset === "use" ||
+        options?.offset === "ignore" ||
+        !isSecondsOffsetMatchCompatNeeded()) {
+        return zoned;
+    }
+    const wall = Temporal.PlainDateTime.from(item).withCalendar("iso8601");
+    const epoch = stringEpochAtEdge(item, zoned.timeZoneId, wall, options);
+    return epoch === zoned.epochNanoseconds
+        ? zoned
+        : new Temporal.ZonedDateTime(epoch, zoned.timeZoneId, zoned.calendarId);
+}
 /**
  * `Temporal.ZonedDateTime.from`, correct across the whole representable range.
  *
  * Returns the polyfill's result whenever it has one. When the polyfill throws for a named zone
  * within a month of either range limit, the TC39 result is recomputed (see the note at the top
- * of this file); every other failure re-throws the polyfill's own error.
+ * of this file); every other failure re-throws the polyfill's own error. A string whose offset
+ * is written with seconds is matched exactly, as TC39 requires (`matchSecondsOffsetExactly`).
  *
  * @param item RFC 9557 zoned string or ZonedDateTime-like property bag
  * @param options Temporal `disambiguation` / `offset` / `overflow`
@@ -413,7 +479,10 @@ export function zonedDateTimeFrom(item, options) {
         return dateOnly;
     }
     try {
-        return Temporal.ZonedDateTime.from(item, options);
+        const zoned = Temporal.ZonedDateTime.from(item, options);
+        return typeof item === "string"
+            ? matchSecondsOffsetExactly(item, zoned, options)
+            : zoned;
     }
     catch (error) {
         const recovered = typeof item === "string"

package/dist/internal/zonedWallClockDifference.js

@@ -1,4 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { TIME_ZONE_ANNOTATION } from "./isoStringBody.js";
 import { MAX_EPOCH_NANOSECONDS, MIN_EPOCH_NANOSECONDS, } from "./epochNanoseconds.js";
 import { calendarDateAdd as compatCalendarDateAdd, calendarDateUntil as compatCalendarDateUntil, isCalendarArithmeticCompatNeeded, isNudgeWindowCompatNeeded, } from "./temporalCompat/index.js";
 import { epochNanosecondsFor, isNamedTimeZone, isValidEpoch, utcEpochNanoseconds, zonedDateTimeFrom, } from "./zonedWallClock.js";
@@ -43,7 +44,7 @@ const UTC_EQUIVALENT_OFFSET_ZONE = "+00:00";
 const OPTIONS_PROBE = new Temporal.ZonedDateTime(0n, "UTC");
 const ZERO_DURATION = new Temporal.Duration();
 /** An RFC 9557 time zone annotation (`[Europe/London]`, `[!+01:00]`), never a `key=value` one. */
-const TIME_ZONE_ANNOTATION = /\[!?[^\]=]+\]/;
+const timeZoneAnnotation = new RegExp(TIME_ZONE_ANNOTATION);
 const ZERO_DATE_DURATION = {
     years: 0,
     months: 0,
@@ -766,7 +767,7 @@ function zonedRelativeTo(relativeTo) {
         return relativeTo;
     try {
         if (typeof relativeTo === "string") {
-            return TIME_ZONE_ANNOTATION.test(relativeTo)
+            return timeZoneAnnotation.test(relativeTo)
                 ? zonedDateTimeFrom(relativeTo)
                 : null;
         }
@@ -868,7 +869,7 @@ function plainRelativeToNeedingCompat(relativeTo) {
         }
         else if (typeof relativeTo === "string" &&
             relativeTo.includes("u-ca=") &&
-            !TIME_ZONE_ANNOTATION.test(relativeTo)) {
+            !timeZoneAnnotation.test(relativeTo)) {
             plain = Temporal.PlainDate.from(relativeTo);
         }
         else {
@@ -974,7 +975,7 @@ function plainRelativeTo(relativeTo) {
             return relativeTo.toPlainDate();
         }
         if (typeof relativeTo === "string" &&
-            !TIME_ZONE_ANNOTATION.test(relativeTo)) {
+            !timeZoneAnnotation.test(relativeTo)) {
             return Temporal.PlainDate.from(relativeTo);
         }
         if (relativeTo !== null &&

package/dist/internal/zonedWallClockOperations.d.ts

@@ -40,28 +40,40 @@ export declare function zonedWithPlainTime(zoned: Temporal.ZonedDateTime, time?:
  */
 export declare function zonedHoursInDay(zoned: Temporal.ZonedDateTime): number;
 /**
- * `ZonedDateTime#getTimeZoneTransition("next")`, correct at the range limits and before 1847.
+ * `ZonedDateTime#getTimeZoneTransition("next")`: TC39 `GetNamedTimeZoneNextTransition`, the first
+ * offset change strictly after `zoned`.
  *
- * - Before 1847-01-01 the polyfill never searches (defect 3), so a named zone whose offset there
- *   differs from its offset at 1847-01-01 has its transition found by bisection first.
- * - The polyfill's forward scan gives up once a two-week step would pass the maximum instant, so a
- *   `null` within its three-year horizon of the maximum is re-checked by walking back from the
- *   maximum with `getTimeZoneTransition("previous")`, which scans correctly there.
+ * - While the D13 probe fails (two changes inside one of the polyfill's 14-day search steps are
+ *   skipped, or stall it for ever), a named zone is searched by GMT's own bounded search
+ *   (`zonedTransitionSearch.ts`) and the polyfill's search is never called.
+ * - Otherwise the polyfill answers, corrected before 1847 (defect 3: it never searches there, so
+ *   the change is found by bisection first) and within its three-year horizon of the maximum
+ *   instant (defect 2: its forward scan gives up once a step would pass the maximum, so a `null`
+ *   is re-checked by walking back from the maximum).
  *
  * @param zoned the instant to search after (exclusive)
- * @returns the next transition, or null when there is none before the maximum instant
+ * @param until optional: the last instant to search, in epoch nanoseconds (inclusive). A caller
+ *   that needs only changes up to there passes it so the search reads no further
+ * @returns the next transition, or null when there is none up to `until` or, without it, none
+ *   that Temporal reports
  */
-export declare function zonedNextTransition(zoned: Temporal.ZonedDateTime): Temporal.ZonedDateTime | null;
+export declare function zonedNextTransition(zoned: Temporal.ZonedDateTime, until?: bigint): Temporal.ZonedDateTime | null;
 /**
- * `ZonedDateTime#getTimeZoneTransition("previous")`, correct before 1847.
+ * `ZonedDateTime#getTimeZoneTransition("previous")`: TC39 `GetNamedTimeZonePreviousTransition`,
+ * the last offset change strictly before `zoned`.
  *
- * The polyfill stops looking at 1847-01-01 (defect 3), so when it finds nothing in a named zone the
- * span from the minimum instant to the floor is checked by comparing offsets and bisecting.
+ * - While the D13 probe fails, a named zone is searched by GMT's own bounded search and the
+ *   polyfill's search is never called (see `zonedNextTransition`).
+ * - Otherwise the polyfill answers, corrected before 1847 (defect 3): when it finds nothing in a
+ *   named zone, the span from the minimum instant to its floor is checked by comparing offsets
+ *   and bisecting.
  *
  * @param zoned the instant to search before (exclusive)
- * @returns the previous transition, or null when there is none
+ * @param since optional: where the search stops, in epoch nanoseconds (exclusive). A caller that
+ *   needs only changes after there passes it so the search reads no further back
+ * @returns the previous transition, or null when there is none after `since` or, without it, none
  */
-export declare function zonedPreviousTransition(zoned: Temporal.ZonedDateTime): Temporal.ZonedDateTime | null;
+export declare function zonedPreviousTransition(zoned: Temporal.ZonedDateTime, since?: bigint): Temporal.ZonedDateTime | null;
 /**
  * `ZonedDateTime#add`, correct at the range limits and in calendars the polyfill gets wrong.
  *
@@ -96,6 +108,7 @@ export declare function subtractFromZoned(zoned: Temporal.ZonedDateTime, duratio
  *   "later"/"compatible" forward (DisambiguatePossibleEpochNanoseconds); "reject" throws for both.
  * - The time portion is then added in exact time and is never re-resolved.
  * - With no date portion, the whole duration is exact time and `disambiguation` never applies.
+ * - Each option is converted to a string once, as Temporal GetOption converts it.
  *
  * @param zoned the starting value
  * @param duration the duration to add or subtract