@northguild/gmt 1.17.0 → 1.19.0

package/dist/internal/temporalCompat/capabilities.d.ts

@@ -3,6 +3,11 @@ import { type DefectId, type Repro } from "./repros.js";
 export declare function runRepro(repro: Pick<Repro, "run">): string;
 /** True when a repro's output is the spec-correct value, i.e. the installed runtime is fixed. */
 export declare function reproPasses(repro: Pick<Repro, "expected">, output: string): boolean;
+/**
+ * True when any of `candidates` for this defect and Temporal calendar id fails. Stops at the first
+ * failure, so the order of a defect's repros is the order they are tried in.
+ */
+export declare function anyReproFails(candidates: readonly Repro[], defect: DefectId, calendar: string): boolean;
 /**
  * True when any repro for this defect and Temporal calendar id fails in the installed runtime.
  * A calendar with no repro for the defect is not affected by it.
@@ -19,6 +24,27 @@ export declare function isDefectPresent(defect: DefectId, calendar: string): boo
  * take the spec path through `isCalendarArithmeticCompatNeeded`.
  */
 export declare function isNudgeWindowCompatNeeded(): boolean;
+/**
+ * True when this runtime matches a zoned string's offset by minutes even when the offset is
+ * written with seconds (defect D12).
+ *
+ * TC39 `ToTemporalZonedDateTime` matches by minutes only an offset with no seconds part; one
+ * written with seconds must equal the zone's offset exactly. A runtime that always matches by
+ * minutes accepts `-00:45:00[Africa/Monrovia]` for a zone at −00:44:30, and picks the wrong pass
+ * of a second repeated by a sub-minute transition (Pacific/Niue, 1952).
+ */
+export declare function isSecondsOffsetMatchCompatNeeded(): boolean;
+/**
+ * True when this runtime's time zone transition search cannot be trusted (defect D13).
+ *
+ * TC39 `GetNamedTimeZoneNextTransition` returns the first offset change after an instant. A runtime
+ * that samples the offset in steps longer than the gap between two changes skips a pair that
+ * returns to the same offset, and can loop for ever on three different offsets in one step. The
+ * skipped-pair repros come first and none of them can stall, so on such a runtime the probe
+ * answers before a stalling repro is reached. Every repro has to pass for the workaround to go
+ * dormant: a runtime that fixes the skipped pairs and still stalls on one zone keeps it.
+ */
+export declare function isTransitionSearchCompatNeeded(): boolean;
 /**
  * True when calendar arithmetic in `calendarId` needs the compat layer in this runtime: any of its
  * add, until or read probes fails (CORE-6 spec §3.6.2). `iso8601` never does, and costs nothing.

package/dist/internal/temporalCompat/capabilities.js

@@ -21,6 +21,15 @@ export function runRepro(repro) {
 export function reproPasses(repro, output) {
     return output === repro.expected;
 }
+/**
+ * True when any of `candidates` for this defect and Temporal calendar id fails. Stops at the first
+ * failure, so the order of a defect's repros is the order they are tried in.
+ */
+export function anyReproFails(candidates, defect, calendar) {
+    return candidates.some((repro) => repro.defect === defect &&
+        repro.calendar === calendar &&
+        !reproPasses(repro, runRepro(repro)));
+}
 const cache = new Map();
 /**
  * True when any repro for this defect and Temporal calendar id fails in the installed runtime.
@@ -32,9 +41,7 @@ export function isDefectPresent(defect, calendar) {
     if (cached !== undefined) {
         return cached;
     }
-    const present = repros.some((repro) => repro.defect === defect &&
-        repro.calendar === calendar &&
-        !reproPasses(repro, runRepro(repro)));
+    const present = anyReproFails(repros, defect, calendar);
     cache.set(key, present);
     return present;
 }
@@ -51,6 +58,31 @@ export function isDefectPresent(defect, calendar) {
 export function isNudgeWindowCompatNeeded() {
     return isDefectPresent("D11", "iso8601");
 }
+/**
+ * True when this runtime matches a zoned string's offset by minutes even when the offset is
+ * written with seconds (defect D12).
+ *
+ * TC39 `ToTemporalZonedDateTime` matches by minutes only an offset with no seconds part; one
+ * written with seconds must equal the zone's offset exactly. A runtime that always matches by
+ * minutes accepts `-00:45:00[Africa/Monrovia]` for a zone at −00:44:30, and picks the wrong pass
+ * of a second repeated by a sub-minute transition (Pacific/Niue, 1952).
+ */
+export function isSecondsOffsetMatchCompatNeeded() {
+    return isDefectPresent("D12", "iso8601");
+}
+/**
+ * True when this runtime's time zone transition search cannot be trusted (defect D13).
+ *
+ * TC39 `GetNamedTimeZoneNextTransition` returns the first offset change after an instant. A runtime
+ * that samples the offset in steps longer than the gap between two changes skips a pair that
+ * returns to the same offset, and can loop for ever on three different offsets in one step. The
+ * skipped-pair repros come first and none of them can stall, so on such a runtime the probe
+ * answers before a stalling repro is reached. Every repro has to pass for the workaround to go
+ * dormant: a runtime that fixes the skipped pairs and still stalls on one zone keeps it.
+ */
+export function isTransitionSearchCompatNeeded() {
+    return isDefectPresent("D13", "iso8601");
+}
 /** Defects that make the runtime's calendar arithmetic or reads differ from the spec. */
 const ARITHMETIC_DEFECTS = [
     "D1",

package/dist/internal/temporalCompat/fieldSearch.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { MAX_ISO_EPOCH_DAYS } from "../zonedWallClock.js";
+import { MAX_ISO_EPOCH_DAYS } from "../epochNanoseconds.js";
 import { calendarFieldsOf } from "./calendarFields.js";
 /*
  * Read-only fields → ISO search. Calendar fields increase strictly with ISO order under the key

package/dist/internal/temporalCompat/index.d.ts

@@ -1,4 +1,4 @@
 export { type CalendarDateUnit, calendarDateAdd, calendarDateUntil, } from "./calendarDateArithmetic.js";
 export { calendarDateFromFields } from "./calendarDateFromFields.js";
-export { isCalendarArithmeticCompatNeeded, isNudgeWindowCompatNeeded, } from "./capabilities.js";
+export { isCalendarArithmeticCompatNeeded, isNudgeWindowCompatNeeded, isSecondsOffsetMatchCompatNeeded, isTransitionSearchCompatNeeded, } from "./capabilities.js";
 export { calendarFieldsOf } from "./calendarFields.js";

package/dist/internal/temporalCompat/index.js

@@ -1,5 +1,5 @@
 // The only import surface of the Temporal compat layer. See README.md.
 export { calendarDateAdd, calendarDateUntil, } from "./calendarDateArithmetic.js";
 export { calendarDateFromFields } from "./calendarDateFromFields.js";
-export { isCalendarArithmeticCompatNeeded, isNudgeWindowCompatNeeded, } from "./capabilities.js";
+export { isCalendarArithmeticCompatNeeded, isNudgeWindowCompatNeeded, isSecondsOffsetMatchCompatNeeded, isTransitionSearchCompatNeeded, } from "./capabilities.js";
 export { calendarFieldsOf } from "./calendarFields.js";

package/dist/internal/temporalCompat/repros.d.ts

@@ -1,5 +1,5 @@
 /** Defect ids from the CORE-6 calendar-correctness spec §1.2. */
-export type DefectId = "D1" | "D2" | "D3" | "D4" | "D5" | "D6" | "D7" | "D8" | "D10" | "D11";
+export type DefectId = "D1" | "D2" | "D3" | "D4" | "D5" | "D6" | "D7" | "D8" | "D10" | "D11" | "D12" | "D13";
 /**
  * Zoned defects worked around in `internal/zonedWallClock*`: the range-limit defects (upstream
  * issue drafts A, B and D in the CORE-6 polyfill research) and zoned.E, the transition search

package/dist/internal/temporalCompat/repros.js

@@ -498,6 +498,161 @@ const d9Repros = [
         },
     ];
 });
+/** The epoch nanoseconds `Temporal.ZonedDateTime.from(item)` reads, or the error's name. */
+function zonedStringEpoch(item) {
+    try {
+        return String(Temporal.ZonedDateTime.from(item).epochNanoseconds);
+    }
+    catch (error) {
+        return error instanceof Error ? error.name : "Error";
+    }
+}
+/**
+ * D12 (`internal/zonedWallClock.ts` defect 4): `ToTemporalZonedDateTime` matches a string's
+ * offset against the zone by minutes even when the offset is written with seconds, where TC39
+ * requires match-exactly ("If offsetParseResult contains more than one MinuteSecond Parse Node,
+ * set matchBehaviour to match-exactly"). Expected values: test262
+ * `test/intl402/Temporal/ZonedDateTime/from/zoneddatetime-sub-minute-offset.js` ("rounded
+ * HH:MM:SS not accepted in string offset (offset=reject)", and the Pacific/Niue edge case,
+ * "-11:20:00 is accepted as -11:20:00": `reference + 20_000_000_000n`). The test writes the
+ * Monrovia time as `T12`; `T12:00` is the same wall time.
+ */
+const d12Repros = [
+    {
+        defect: "D12",
+        calendar: "iso8601",
+        name: "roundedSecondsRejected",
+        expected: "RangeError",
+        run: () => zonedStringEpoch("1970-01-01T12:00-00:45:00[Africa/Monrovia]"),
+    },
+    {
+        defect: "D12",
+        calendar: "iso8601",
+        name: "exactSecondsSecondPass",
+        expected: "-543069601000000000",
+        run: () => zonedStringEpoch("1952-10-15T23:59:59-11:20:00[Pacific/Niue]"),
+    },
+];
+/** More `Intl.DateTimeFormat#format` reads than this for one transition lookup is a stalled search. */
+const D13_INTL_READ_LIMIT = 20_000;
+/**
+ * `run()`'s output, or a note when it made more than `D13_INTL_READ_LIMIT` reads through
+ * `Intl.DateTimeFormat.prototype.format`, where the read then throws so a search that would never
+ * return stops. Polyfill 0.5.1 reads every offset through that getter.
+ */
+function withBoundedOffsetReads(run) {
+    const prototype = Intl.DateTimeFormat.prototype;
+    const original = Object.getOwnPropertyDescriptor(prototype, "format");
+    const originalGet = original?.get;
+    if (original === undefined || originalGet === undefined) {
+        return "cannot bound Intl.DateTimeFormat#format";
+    }
+    let reads = 0;
+    Object.defineProperty(prototype, "format", {
+        configurable: true,
+        get() {
+            const format = originalGet.call(this);
+            return (date) => {
+                reads++;
+                if (reads > D13_INTL_READ_LIMIT) {
+                    throw new RangeError(`more than ${D13_INTL_READ_LIMIT} offset reads`);
+                }
+                return format(date);
+            };
+        },
+    });
+    try {
+        return run();
+    }
+    finally {
+        Object.defineProperty(prototype, "format", original);
+    }
+}
+/** America/Boa_Vista's 2000-10-08T04:00:00Z advance (−04:00 → −03:00, local midnight skipped). */
+const BOA_VISTA_ADVANCE = "2000-10-08T01:00:00-03:00[America/Boa_Vista]";
+/**
+ * D13 (`internal/zonedWallClock.ts` defect 5): `GetNamedTimeZoneNextTransition` and
+ * `…PreviousTransition` sample the offset every 14 days. Two changes inside one step that return
+ * to the same offset are skipped (America/Boa_Vista 2000-10-08 and 2000-10-15, 601,200 s apart),
+ * so `GetStartOfDay` for the skipped midnight of 2000-10-08 fails too; three different offsets in
+ * one step (Europe/Riga 1944-10-02 and 1944-10-12) make `bisect` loop for ever, its assertion
+ * compiled out. Spec: TC39 Temporal `GetNamedTimeZoneNextTransition`, "the smallest integer
+ * greater than epochNanoseconds" at which the offset changes. Expected values: Node 26.10.0's
+ * native Temporal and `zdump -v` (tz 2026c). The polyfill's main branch (a79c6a1, per-zone search
+ * windows, in no release) fixes the zones it lists but leaves `bisect` unchanged, and its 17-day
+ * window for Africa/El_Aaiun holds three offsets in 1976: `stall.nextElAaiun` covers that, so the
+ * workaround stays until every repro here passes.
+ *
+ * Order matters: the capability probe stops at the first failing repro, so the `skip.*` repros,
+ * which cannot stall, come before `stall.*`, which a runtime that fails them never runs in
+ * process. The canary runs `stall.*` under `withBoundedOffsetReads`.
+ */
+const d13Repros = [
+    {
+        defect: "D13",
+        calendar: "iso8601",
+        name: "skip.nextBoaVista",
+        expected: BOA_VISTA_ADVANCE,
+        run: () => String(Temporal.Instant.from("2000-10-01T12:00:00Z")
+            .toZonedDateTimeISO("America/Boa_Vista")
+            .getTimeZoneTransition("next")),
+    },
+    {
+        defect: "D13",
+        calendar: "iso8601",
+        name: "skip.previousBoaVista",
+        expected: "2000-10-14T23:00:00-04:00[America/Boa_Vista]",
+        run: () => String(Temporal.Instant.from("2000-10-20T12:00:00Z")
+            .toZonedDateTimeISO("America/Boa_Vista")
+            .getTimeZoneTransition("previous")),
+    },
+    {
+        defect: "D13",
+        calendar: "iso8601",
+        name: "skip.startOfDayBoaVista",
+        expected: BOA_VISTA_ADVANCE,
+        run: () => String(Temporal.PlainDate.from("2000-10-08").toZonedDateTime("America/Boa_Vista")),
+    },
+    {
+        defect: "D13",
+        calendar: "iso8601",
+        name: "skip.hoursInDayNoronha",
+        expected: "23",
+        run: () => String(Temporal.ZonedDateTime.from("2000-10-08T12:00[America/Noronha]")
+            .hoursInDay),
+    },
+    {
+        defect: "D13",
+        calendar: "iso8601",
+        name: "stall.nextRiga",
+        expected: "1944-10-02T02:00:00+01:00[Europe/Riga]",
+        run: () => withBoundedOffsetReads(() => String(Temporal.Instant.from("1944-04-15T12:00:00Z")
+            .toZonedDateTimeISO("Europe/Riga")
+            .getTimeZoneTransition("next"))),
+    },
+    {
+        defect: "D13",
+        calendar: "iso8601",
+        name: "stall.nextSimferopol",
+        expected: "1944-04-03T03:00:00+02:00[Europe/Simferopol]",
+        run: () => withBoundedOffsetReads(() => String(Temporal.Instant.from("1943-10-15T12:00:00Z")
+            .toZonedDateTimeISO("Europe/Simferopol")
+            .getTimeZoneTransition("next"))),
+    },
+    // js-temporal main (a79c6a1) gives Africa/El_Aaiun a 17-day search window. Its changes of
+    // 1976-04-14T01:00:00Z (−01:00 → +00:00) and 1976-05-01T00:00:00Z (+00:00 → +01:00) are 16.958
+    // days apart, so one window holds three offsets and `bisect`, unchanged there, cannot narrow.
+    // 0.5.1's 14-day step passes these two; a release with a79c6a1 alone would not.
+    ...["1976-04-14T00:30:00Z", "1976-03-28T00:30:00Z"].map((from) => ({
+        defect: "D13",
+        calendar: "iso8601",
+        name: `stall.nextElAaiun ${from}`,
+        expected: "1976-04-14T01:00:00+00:00[Africa/El_Aaiun]",
+        run: () => withBoundedOffsetReads(() => String(Temporal.Instant.from(from)
+            .toZonedDateTimeISO("Africa/El_Aaiun")
+            .getTimeZoneTransition("next"))),
+    })),
+];
 export const repros = [
     ...d9Repros,
     ...zonedARepros,
@@ -508,6 +663,8 @@ export const repros = [
     ...d1ArithmeticRepros,
     d1RelativeToRepro,
     ...d10Repros,
+    ...d12Repros,
+    ...d13Repros,
     ...d6Repros,
     d7Repro,
     d7LeapMonthEndRepro,

package/dist/internal/timestampEvents.d.ts

@@ -0,0 +1,32 @@
+import type { TimestampClass } from "../types/index.js";
+/** A validated `TimestampEvent`, with both of its moments as epoch nanoseconds. */
+export type ParsedTimestampEvent = {
+    classifier: TimestampClass;
+    /** The event's `at`, exactly as the caller wrote it. */
+    at: string;
+    atNanoseconds: bigint;
+    recordedNanoseconds: bigint;
+};
+/**
+ * Validate a list of `TimestampEvent`s and put them in recording order, or `null`.
+ *
+ * The shared reading behind `bestAvailable` and `estimateDrift`:
+ *
+ * - Every event must be an object whose `classifier` is exactly `PLN`, `EST`, `REQ` or `ACT` and
+ *   whose `at` and `recordedAt` are instants (`Z`/offset) or zoned strings, read as
+ *   `parseInstantNanoseconds` reads them: the offset fixes the instant, a minute-rounded offset
+ *   is read as its bracketed zone's real offset, and the bracket is otherwise not checked. One
+ *   invalid event makes the whole list invalid.
+ * - The result is sorted by `recordedAt`, earliest first. Events recorded at the same instant
+ *   keep their input order, so of two ties the later index is the later record.
+ * - `at` is kept exactly as written, so a caller can echo it.
+ * - An empty list is `[]`; the caller decides what that means.
+ * - A hostile value (a throwing getter, a revoked Proxy) is invalid input: `null`, never a throw.
+ *
+ * @param events candidate list of timestamp events
+ * @returns the events in recording order with their instants, or null on invalid input
+ *
+ * @example parseTimestampEvents([]) // []
+ * @example parseTimestampEvents([{ classifier: "ETA", at: "2024-06-15T12:00:00Z", recordedAt: "2024-06-15T10:00:00Z" }]) // null
+ */
+export declare function parseTimestampEvents(events: unknown): ParsedTimestampEvent[] | null;

package/dist/internal/timestampEvents.js

@@ -0,0 +1,76 @@
+import { parseInstantNanoseconds } from "./instantNanoseconds.js";
+import { isObject } from "./isObject.js";
+const TIMESTAMP_CLASSES = new Set([
+    "PLN",
+    "EST",
+    "REQ",
+    "ACT",
+]);
+/** One event validated, or `null`. */
+function parseEvent(event) {
+    if (!isObject(event)) {
+        return null;
+    }
+    const { classifier, at, recordedAt } = event;
+    if (!TIMESTAMP_CLASSES.has(classifier) || typeof at !== "string") {
+        return null;
+    }
+    const atNanoseconds = parseInstantNanoseconds(at);
+    const recordedNanoseconds = parseInstantNanoseconds(recordedAt);
+    if (atNanoseconds === null || recordedNanoseconds === null) {
+        return null;
+    }
+    return {
+        classifier: classifier,
+        at,
+        atNanoseconds,
+        recordedNanoseconds,
+    };
+}
+/**
+ * Validate a list of `TimestampEvent`s and put them in recording order, or `null`.
+ *
+ * The shared reading behind `bestAvailable` and `estimateDrift`:
+ *
+ * - Every event must be an object whose `classifier` is exactly `PLN`, `EST`, `REQ` or `ACT` and
+ *   whose `at` and `recordedAt` are instants (`Z`/offset) or zoned strings, read as
+ *   `parseInstantNanoseconds` reads them: the offset fixes the instant, a minute-rounded offset
+ *   is read as its bracketed zone's real offset, and the bracket is otherwise not checked. One
+ *   invalid event makes the whole list invalid.
+ * - The result is sorted by `recordedAt`, earliest first. Events recorded at the same instant
+ *   keep their input order, so of two ties the later index is the later record.
+ * - `at` is kept exactly as written, so a caller can echo it.
+ * - An empty list is `[]`; the caller decides what that means.
+ * - A hostile value (a throwing getter, a revoked Proxy) is invalid input: `null`, never a throw.
+ *
+ * @param events candidate list of timestamp events
+ * @returns the events in recording order with their instants, or null on invalid input
+ *
+ * @example parseTimestampEvents([]) // []
+ * @example parseTimestampEvents([{ classifier: "ETA", at: "2024-06-15T12:00:00Z", recordedAt: "2024-06-15T10:00:00Z" }]) // null
+ */
+export function parseTimestampEvents(events) {
+    try {
+        if (!Array.isArray(events)) {
+            return null;
+        }
+        const parsed = [];
+        for (const event of events) {
+            const one = parseEvent(event);
+            if (one === null) {
+                return null;
+            }
+            parsed.push(one);
+        }
+        // Array.prototype.sort is stable, so ties keep their input order.
+        return parsed.sort((a, b) => a.recordedNanoseconds < b.recordedNanoseconds
+            ? -1
+            : a.recordedNanoseconds > b.recordedNanoseconds
+                ? 1
+                : 0);
+    }
+    catch {
+        // A hostile value (a throwing getter, a revoked Proxy) is invalid input.
+        return null;
+    }
+}

package/dist/internal/twoDigitYear.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve a two-digit year inside a caller-chosen hundred-year window: the one year in
+ * `[windowStart, windowStart + 99]` whose last two digits are `yy`.
+ *
+ * Pure arithmetic: the function holds no window of its own and reads no clock. The window comes
+ * from the caller's `TwoDigitYearOptions.yearWindow`, resolved by `readYearWindowStart`
+ * (`internal/yearWindowStart.ts`); no standard says which century a two-digit year belongs to,
+ * so the library never supplies one.
+ *
+ * @param yy the two-digit year, 0–99, as the grammar read it
+ * @param windowStart the first year of the hundred-year window
+ * @returns the four-digit year in the window ending in `yy`
+ *
+ * @example twoDigitYear(24, 2000) // 2024
+ * @example twoDigitYear(99, 1950) // 1999
+ * @example twoDigitYear(49, 1950) // 2049
+ * @example twoDigitYear(0, 1976) // 2000
+ */
+export declare function twoDigitYear(yy: number, windowStart: number): number;

package/dist/internal/twoDigitYear.js

@@ -0,0 +1,22 @@
+/**
+ * Resolve a two-digit year inside a caller-chosen hundred-year window: the one year in
+ * `[windowStart, windowStart + 99]` whose last two digits are `yy`.
+ *
+ * Pure arithmetic: the function holds no window of its own and reads no clock. The window comes
+ * from the caller's `TwoDigitYearOptions.yearWindow`, resolved by `readYearWindowStart`
+ * (`internal/yearWindowStart.ts`); no standard says which century a two-digit year belongs to,
+ * so the library never supplies one.
+ *
+ * @param yy the two-digit year, 0–99, as the grammar read it
+ * @param windowStart the first year of the hundred-year window
+ * @returns the four-digit year in the window ending in `yy`
+ *
+ * @example twoDigitYear(24, 2000) // 2024
+ * @example twoDigitYear(99, 1950) // 1999
+ * @example twoDigitYear(49, 1950) // 2049
+ * @example twoDigitYear(0, 1976) // 2000
+ */
+export function twoDigitYear(yy, windowStart) {
+    const candidate = Math.floor(windowStart / 100) * 100 + yy;
+    return candidate < windowStart ? candidate + 100 : candidate;
+}

package/dist/internal/unixEpochValue.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { MAX_EPOCH_NANOSECONDS } from "./epochNanoseconds.js";
+import { isObject } from "./isObject.js";
 // TC39 Temporal IsValidEpochNanoseconds bound (nsMaxInstant = 10^8 days) in milliseconds: 8.64e15.
 const MAX_EPOCH_MILLISECONDS = Number(MAX_EPOCH_NANOSECONDS / 1000000n);
 // An optionally negative run of ASCII digits and nothing else. `\d` without the `u` flag is
@@ -91,7 +92,7 @@ export function resolveUnixEpochUnitOptions(options) {
     if (options === undefined) {
         return "milliseconds";
     }
-    if (options === null || typeof options !== "object") {
+    if (!isObject(options)) {
         return null;
     }
     return resolveUnixEpochUnit(options.epochUnit);
@@ -231,7 +232,7 @@ export function parseUnixEpochIntervalList(intervals) {
     }
     const parsed = [];
     for (const interval of intervals) {
-        if (!interval || typeof interval !== "object") {
+        if (!isObject(interval)) {
             return null;
         }
         const { start, end } = interval;

package/dist/internal/unixWallClock.d.ts

@@ -0,0 +1,24 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * Read a Unix epoch argument on the local wall clock of the shared `unix/` options, or null when
+ * anything is invalid. For the `parse*FromUnix` accessors, which only read fields.
+ *
+ * - `value` follows the one epoch grammar (`parseUnixEpochValue`).
+ * - `epochUnit` accepts singular or plural names and defaults to `"milliseconds"`.
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else is invalid (see
+ *   `normalizeZoneFrame`).
+ *
+ * @param value Unix epoch number or digit string
+ * @param options optional `{ epochUnit, timeZone }`
+ * @returns the local wall clock, or null
+ *
+ * @example unixWallClock(0)?.toString() // "1970-01-01T00:00:00"
+ * @example unixWallClock("86400", { epochUnit: "second", timeZone: "Asia/Tokyo" })?.hour // 9
+ * @example unixWallClock(45870000, { timeZone: "-00:44:30" })?.toString() // "1970-01-01T12:00:00"
+ * @example unixWallClock(0, { timeZone: "Asia/Tokio" }) // null
+ */
+export declare function unixWallClock(value: unknown, options?: {
+    epochUnit?: unknown;
+    timeZone?: unknown;
+}): Temporal.PlainDateTime | null;

package/dist/internal/unixWallClock.js

@@ -0,0 +1,35 @@
+import { resolveUnixEpochUnit, unixEpochToInstant } from "./unixEpochValue.js";
+import { frameWallClock, normalizeZoneFrame } from "./zoneFrame.js";
+/**
+ * Read a Unix epoch argument on the local wall clock of the shared `unix/` options, or null when
+ * anything is invalid. For the `parse*FromUnix` accessors, which only read fields.
+ *
+ * - `value` follows the one epoch grammar (`parseUnixEpochValue`).
+ * - `epochUnit` accepts singular or plural names and defaults to `"milliseconds"`.
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else is invalid (see
+ *   `normalizeZoneFrame`).
+ *
+ * @param value Unix epoch number or digit string
+ * @param options optional `{ epochUnit, timeZone }`
+ * @returns the local wall clock, or null
+ *
+ * @example unixWallClock(0)?.toString() // "1970-01-01T00:00:00"
+ * @example unixWallClock("86400", { epochUnit: "second", timeZone: "Asia/Tokyo" })?.hour // 9
+ * @example unixWallClock(45870000, { timeZone: "-00:44:30" })?.toString() // "1970-01-01T12:00:00"
+ * @example unixWallClock(0, { timeZone: "Asia/Tokio" }) // null
+ */
+export function unixWallClock(value, options) {
+    const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+    const frame = normalizeZoneFrame(options?.timeZone);
+    if (epochUnit === null || frame === null) {
+        return null;
+    }
+    try {
+        const instant = unixEpochToInstant(value, epochUnit);
+        return instant === null ? null : frameWallClock(instant, frame);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/utcWallClock.d.ts

@@ -0,0 +1,20 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Read a UTC ISO string on a local wall clock for the `parse*FromUtc` accessors: the instant it
+ * names, on the wall clock of `options.timeZone`. The utc twin of `unixWallClock`.
+ *
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else is invalid (see
+ *   `normalizeZoneFrame`).
+ *
+ * @param value UTC ISO 8601 datetime string
+ * @param options optional `{ timeZone }`
+ * @returns the local wall clock, or null when the value or the zone is invalid
+ * @example utcWallClock("2024-03-15T14:30:00Z", { timeZone: "Asia/Tokyo" })?.toString() // "2024-03-15T23:30:00"
+ * @example utcWallClock("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" })?.toString() // "1970-01-01T12:00:00"
+ * @example utcWallClock("2024-03-15T14:30:00Z", { timeZone: "Invalid/Zone" }) // null
+ * @example utcWallClock("2024-03-15T14:30:00") // null (no Z)
+ */
+export declare function utcWallClock(value: string, options?: {
+    timeZone?: string;
+}): Temporal.PlainDateTime | null;

package/dist/internal/utcWallClock.js

@@ -0,0 +1,32 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUtc } from "../utc/validate/isValidUtc.js";
+import { frameWallClock, normalizeZoneFrame } from "./zoneFrame.js";
+/**
+ * Read a UTC ISO string on a local wall clock for the `parse*FromUtc` accessors: the instant it
+ * names, on the wall clock of `options.timeZone`. The utc twin of `unixWallClock`.
+ *
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else is invalid (see
+ *   `normalizeZoneFrame`).
+ *
+ * @param value UTC ISO 8601 datetime string
+ * @param options optional `{ timeZone }`
+ * @returns the local wall clock, or null when the value or the zone is invalid
+ * @example utcWallClock("2024-03-15T14:30:00Z", { timeZone: "Asia/Tokyo" })?.toString() // "2024-03-15T23:30:00"
+ * @example utcWallClock("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" })?.toString() // "1970-01-01T12:00:00"
+ * @example utcWallClock("2024-03-15T14:30:00Z", { timeZone: "Invalid/Zone" }) // null
+ * @example utcWallClock("2024-03-15T14:30:00") // null (no Z)
+ */
+export function utcWallClock(value, options) {
+    if (!isValidUtc(value))
+        return null;
+    const frame = normalizeZoneFrame(options?.timeZone);
+    if (frame === null)
+        return null;
+    try {
+        return frameWallClock(Temporal.Instant.from(value), frame);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/yearWindowStart.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolve `TwoDigitYearOptions.yearWindow` to the first year of a hundred-year window, or null
+ * when the option is absent or not one of its two forms.
+ *
+ * - An integer from 0 to 9900 is a fixed window starting in that year.
+ * - `"rolling"` (exact match) is the hundred years around today: 50 years before the current UTC
+ *   calendar year to 49 after it. The year is read once, from
+ *   `Temporal.Now.instant().toZonedDateTimeISO("UTC").year`, so the window moves at the UTC new
+ *   year, not mid-year: year granularity is a **GMT rule**. RFC 9110 §5.6.7 applies the same
+ *   50-year idea to an `rfc850-date` two-digit year, at day granularity; `internal/httpDateFields.ts`
+ *   implements that rule for HTTP dates and is not affected by this one.
+ * - Anything else (a non-integer, a negative, 9901, `NaN`, `Infinity`, a numeric string, any
+ *   other string, `null`) is null. Whether a null window matters is the caller's: a value with no
+ *   two-digit year needs none.
+ *
+ * `options` is read as an Object the way Temporal's GetOptionsObject reads one (a function is an
+ * Object); a non-Object yields null here, and the public function has already returned its
+ * sentinel for one by `isOptionsArgument`.
+ *
+ * @param options the caller's options bag
+ * @returns the window's first year, or null
+ *
+ * @example readYearWindowStart({ yearWindow: 1950 }) // 1950
+ * @example readYearWindowStart({ yearWindow: "rolling" }) // 1976 (in 2026)
+ * @example readYearWindowStart({}) // null
+ * @example readYearWindowStart({ yearWindow: 9901 }) // null
+ */
+export declare function readYearWindowStart(options: unknown): number | null;