@northguild/gmt 1.18.0 → 1.20.0

package/dist/internal/dutyRunIndex.d.ts

@@ -0,0 +1,150 @@
+import type { DutyLogEntry, DutyRun } from "./dutyLog.js";
+import type { ResolvedPair, StatusSet } from "./dutyRules.js";
+/**
+ * Which entries a view of the log counts: the entries in a set, the entries outside one, or the
+ * entries outside one and inside another (`within`; null for any status).
+ */
+export type StatusKey = StatusSet | {
+    not: StatusSet;
+    within?: StatusSet | null;
+};
+/** One status test's view of the whole log, built once per call. */
+export type RunIndex = {
+    entries: readonly DutyLogEntry[];
+    entryStarts: readonly bigint[];
+    /** `matched[i]`: whether `entries[i]` passes the test. */
+    matched: readonly boolean[];
+    /** `entryPrefix[i]`: time in the test over `entries[0..i)`; one longer than `entries`. */
+    entryPrefix: readonly bigint[];
+    /** The runs of the whole log, as today's `runsOf` gives them. */
+    runs: readonly DutyRun[];
+    runStarts: readonly bigint[];
+    runEnds: readonly bigint[];
+    /** Per-`(minimum)` and per-`(minimum, maximum)` arrays, built on first use. */
+    qualifying: Map<bigint, readonly number[]>;
+    events: Map<string, EventList>;
+    interruptions: Map<string, InterruptionStates>;
+    /** Per-`(fullRest, pair)` tables of the whole log's rest pairs, built on first use. */
+    pairTables: Map<string, PairTable>;
+};
+/**
+ * Every rest pair of the whole log: `seconds[k]` and `firsts[k]` are the run indexes of the k-th
+ * pair, in order, and `previous[i]` is the run a pair ending at run `i` would start from (-1 for
+ * none). Firsts never decrease along the pairs.
+ */
+type PairTable = {
+    seconds: readonly number[];
+    firsts: readonly number[];
+    previous: readonly number[];
+};
+/** The runs of the whole log whose length is in a range: their run indexes and starts. */
+type EventList = {
+    indexes: readonly number[];
+    starts: readonly bigint[];
+};
+/** The log and the indexes built from it, kept for one call. */
+export type RunStore = {
+    entries: readonly DutyLogEntry[];
+    entryStarts: readonly bigint[];
+    positive: Map<StatusSet, RunIndex>;
+    complement: Map<StatusSet, Map<StatusSet | null, RunIndex>>;
+    /** `nextMatch(set)[i]`: the first entry at or after `i` in the set, or `entries.length`. */
+    nextMatch: Map<StatusSet, readonly number[]>;
+};
+/** The first `count` runs of an index, the last cut at the instant: the log as it stood there. */
+export type RunView = {
+    index: RunIndex;
+    count: number;
+    last: DutyRun | undefined;
+};
+/**
+ * The first position in `[0, count)` where `holds` is true, given it is false and then true; `count`
+ * when it never is.
+ */
+export declare function firstWhere(count: number, holds: (position: number) => boolean): number;
+/** Maximal runs of touching entries passing `matches`, merged as `mergeIntervals` merges them. */
+export declare function runsMatching(entries: readonly DutyLogEntry[], matches: (status: string) => boolean): DutyRun[];
+/**
+ * A call's store: the entries and, as tests ask for them, an index of each.
+ *
+ * @param entries the parsed log, ordered and separate
+ */
+export declare function createRunStore(entries: readonly DutyLogEntry[]): RunStore;
+/**
+ * The index of a test, built on first use and kept: a set or the complement of one is keyed by its
+ * set object, which the rules hold once per call.
+ */
+export declare function runIndex(store: RunStore, test: StatusKey): RunIndex;
+/**
+ * Time in the test inside `[from, to)` of the log as it stood at `at`: entries starting at or after
+ * `at` are gone and the one straddling it ends there.
+ *
+ * @example timeInBefore(index, 0n, 100n, 10n) // time in the test inside [0, 10)
+ */
+export declare function timeInBefore(index: RunIndex, from: bigint, to: bigint, at: bigint): bigint;
+/** The runs of the log as it stood at `at`: no copy, the last cut there. */
+export declare function runsUntil(index: RunIndex, at: bigint): RunView;
+/** The `position`-th run of a view, the last one cut. */
+export declare function viewRun(view: RunView, position: number): DutyRun;
+/** The first position in a view whose run ends after `t`; the view's count when none does. */
+export declare function firstEndingAfter(view: RunView, t: bigint): number;
+/** The first position in a view whose run starts at or after `t`; the view's count when none. */
+export declare function firstStartingAtOrAfter(view: RunView, t: bigint): number;
+/**
+ * The latest of a view's first `taken` runs that is at least `minimum` long. The view's last run
+ * counts at its cut length.
+ */
+export declare function latestAtLeast(view: RunView, taken: number, minimum: bigint): DutyRun | undefined;
+/** The latest run in a view at least `minimum` long. */
+export declare function lastAtLeastUntil(view: RunView, minimum: bigint): DutyRun | undefined;
+/** How many of a view's first runs end at or before `t`. */
+export declare function endingAtOrBefore(view: RunView, t: bigint): number;
+/** The run of a view that ends at `t`, if one does. */
+export declare function runEndingAt(view: RunView, t: bigint): DutyRun | undefined;
+/**
+ * How many of a view's runs of at least `minimum` and under `maximum` (`null`: no upper bound)
+ * start in `[from, to)` (`null`: no upper bound). The view's last run counts at its cut length,
+ * and not at all when it ends at `skipEndingAt`.
+ */
+export declare function countEvents(view: RunView, bounds: {
+    minimum: bigint;
+    maximum: bigint | null;
+}, range: {
+    from: bigint;
+    to: bigint | null;
+}, skipEndingAt: bigint | null): number;
+/** The start of the log's first entry, when it starts before `at`. */
+export declare function logStartBefore(store: RunStore, at: bigint): bigint | undefined;
+/** The log's last entry as it stood at `at`, cut there. */
+export declare function lastEntryBefore(store: RunStore, at: bigint): DutyLogEntry | undefined;
+/** The entry holding the instant `at`, if one does (start ≤ at < end). */
+export declare function entryHolding(store: RunStore, at: bigint): DutyLogEntry | undefined;
+/**
+ * The first entry in `statuses` that starts at or after `from` (`null`: any) and before `at`.
+ */
+export declare function firstEntryIn(store: RunStore, statuses: StatusSet, from: bigint | null, at: bigint): DutyLogEntry | undefined;
+/** Where a required-interruption count stands after each break of the log. */
+type InterruptionStates = {
+    resetAt: readonly (bigint | null)[];
+    part: readonly number[];
+};
+/**
+ * Where a required-interruption count was reset, taking every break a view holds in order: a break
+ * of `minimum` resets it, and breaks that meet `split` one after another in order reset it too.
+ *
+ * @returns the instant of the last reset, or null when none
+ */
+export declare function interruptionResetAt(view: RunView, minimum: bigint, split: readonly bigint[] | null): bigint | null;
+/**
+ * The latest rest pair among a view's runs from `from` on: what the last of
+ * `restPairs(viewRunsFrom(view, from), fullRest, pair)` is, without walking the runs. Only the
+ * view's last run is cut, so it is tried by itself and every earlier pair comes from the whole-log
+ * table.
+ */
+export declare function latestPairFrom(view: RunView, from: number, fullRest: bigint, pair: ResolvedPair): {
+    first: DutyRun;
+    second: DutyRun;
+} | undefined;
+/** How many of the ascending values are in `[low, high)`. */
+export declare function countInRange(sorted: readonly bigint[], low: bigint, high: bigint): number;
+export {};

package/dist/internal/dutyRunIndex.js

@@ -0,0 +1,398 @@
+import { coalesceIntervalNanoseconds } from "./intervalNanoseconds.js";
+const length = (run) => run.end - run.start;
+/** Binary-search steps: an array holds under 2^32 elements. */
+const SEARCH_STEPS = 33;
+/**
+ * The first position in `[0, count)` where `holds` is true, given it is false and then true; `count`
+ * when it never is.
+ */
+export function firstWhere(count, holds) {
+    let low = 0;
+    let high = count;
+    for (let step = 0; step < SEARCH_STEPS && low < high; step++) {
+        const middle = (low + high) >> 1;
+        if (holds(middle)) {
+            high = middle;
+        }
+        else {
+            low = middle + 1;
+        }
+    }
+    return low;
+}
+/** The first position in `[0, limit)` whose value is at least `target`, in ascending values. */
+function lowerBound(values, target, limit = values.length) {
+    return firstWhere(limit, (position) => values[position] >= target);
+}
+/** Maximal runs of touching entries passing `matches`, merged as `mergeIntervals` merges them. */
+export function runsMatching(entries, matches) {
+    return coalesceIntervalNanoseconds(entries
+        .filter((entry) => matches(entry.status))
+        .map(({ start, end }) => ({ start, end, startText: "", endText: "" }))).map(({ start, end }) => ({ start, end }));
+}
+/** The index of a log's entries under a test. */
+function buildIndex(store, matches) {
+    const { entries } = store;
+    const matched = entries.map((entry) => matches(entry.status));
+    const entryPrefix = [0n];
+    let total = 0n;
+    for (let position = 0; position < entries.length; position++) {
+        const entry = entries[position];
+        if (matched[position]) {
+            total += entry.end - entry.start;
+        }
+        entryPrefix.push(total);
+    }
+    const runs = runsMatching(entries, matches);
+    return {
+        entries,
+        entryStarts: store.entryStarts,
+        matched,
+        entryPrefix,
+        runs,
+        runStarts: runs.map((run) => run.start),
+        runEnds: runs.map((run) => run.end),
+        qualifying: new Map(),
+        events: new Map(),
+        interruptions: new Map(),
+        pairTables: new Map(),
+    };
+}
+/**
+ * A call's store: the entries and, as tests ask for them, an index of each.
+ *
+ * @param entries the parsed log, ordered and separate
+ */
+export function createRunStore(entries) {
+    return {
+        entries,
+        entryStarts: entries.map((entry) => entry.start),
+        positive: new Map(),
+        complement: new Map(),
+        nextMatch: new Map(),
+    };
+}
+/**
+ * The index of a test, built on first use and kept: a set or the complement of one is keyed by its
+ * set object, which the rules hold once per call.
+ */
+export function runIndex(store, test) {
+    if (test instanceof Set) {
+        let known = store.positive.get(test);
+        if (known === undefined) {
+            known = buildIndex(store, (status) => test.has(status));
+            store.positive.set(test, known);
+        }
+        return known;
+    }
+    const { not, within = null } = test;
+    let byWithin = store.complement.get(not);
+    if (byWithin === undefined) {
+        byWithin = new Map();
+        store.complement.set(not, byWithin);
+    }
+    let known = byWithin.get(within);
+    if (known === undefined) {
+        known = buildIndex(store, (status) => !not.has(status) && (within === null || within.has(status)));
+        byWithin.set(within, known);
+    }
+    return known;
+}
+/** Time in the test over `[-∞, t)`, whole entries by prefix and the entry holding `t` by part. */
+function cumulative(index, t) {
+    const taken = lowerBound(index.entryStarts, t);
+    if (taken === 0) {
+        return 0n;
+    }
+    const entry = index.entries[taken - 1];
+    const prefix = index.entryPrefix[taken - 1];
+    return index.matched[taken - 1]
+        ? prefix + ((entry.end < t ? entry.end : t) - entry.start)
+        : prefix;
+}
+/**
+ * Time in the test inside `[from, to)` of the log as it stood at `at`: entries starting at or after
+ * `at` are gone and the one straddling it ends there.
+ *
+ * @example timeInBefore(index, 0n, 100n, 10n) // time in the test inside [0, 10)
+ */
+export function timeInBefore(index, from, to, at) {
+    const upper = to < at ? to : at;
+    return upper > from ? cumulative(index, upper) - cumulative(index, from) : 0n;
+}
+/** The runs of the log as it stood at `at`: no copy, the last cut there. */
+export function runsUntil(index, at) {
+    const count = lowerBound(index.runStarts, at);
+    const run = count > 0 ? index.runs[count - 1] : undefined;
+    return {
+        index,
+        count,
+        last: run !== undefined && run.end > at ? { start: run.start, end: at } : run,
+    };
+}
+/** The `position`-th run of a view, the last one cut. */
+export function viewRun(view, position) {
+    return position === view.count - 1
+        ? view.last
+        : view.index.runs[position];
+}
+/** The first position in a view whose run ends after `t`; the view's count when none does. */
+export function firstEndingAfter(view, t) {
+    return firstWhere(view.count, (position) => viewRun(view, position).end > t);
+}
+/** The first position in a view whose run starts at or after `t`; the view's count when none. */
+export function firstStartingAtOrAfter(view, t) {
+    return lowerBound(view.index.runStarts, t, view.count);
+}
+/** For each run, the index of the latest run up to it of at least `minimum`, or -1. */
+function qualifyingAt(index, minimum) {
+    let known = index.qualifying.get(minimum);
+    if (known === undefined) {
+        const found = [];
+        let latest = -1;
+        for (let position = 0; position < index.runs.length; position++) {
+            if (length(index.runs[position]) >= minimum) {
+                latest = position;
+            }
+            found.push(latest);
+        }
+        known = found;
+        index.qualifying.set(minimum, known);
+    }
+    return known;
+}
+/**
+ * The latest of a view's first `taken` runs that is at least `minimum` long. The view's last run
+ * counts at its cut length.
+ */
+export function latestAtLeast(view, taken, minimum) {
+    let whole = taken - 1;
+    if (taken === view.count && view.last !== undefined) {
+        if (length(view.last) >= minimum) {
+            return view.last;
+        }
+        whole = taken - 2;
+    }
+    const position = whole < 0 ? -1 : qualifyingAt(view.index, minimum)[whole];
+    return position < 0 ? undefined : view.index.runs[position];
+}
+/** The latest run in a view at least `minimum` long. */
+export function lastAtLeastUntil(view, minimum) {
+    return latestAtLeast(view, view.count, minimum);
+}
+/** How many of a view's first runs end at or before `t`. */
+export function endingAtOrBefore(view, t) {
+    return firstEndingAfter(view, t);
+}
+/** The run of a view that ends at `t`, if one does. */
+export function runEndingAt(view, t) {
+    const position = firstEndingAfter(view, t - 1n);
+    if (position >= view.count) {
+        return undefined;
+    }
+    const run = viewRun(view, position);
+    return run.end === t ? run : undefined;
+}
+function eventsOf(index, minimum, maximum) {
+    const key = `${minimum}:${maximum ?? ""}`;
+    let known = index.events.get(key);
+    if (known === undefined) {
+        const indexes = [];
+        const starts = [];
+        for (let position = 0; position < index.runs.length; position++) {
+            const run = index.runs[position];
+            const taken = length(run);
+            if (taken >= minimum && (maximum === null || taken < maximum)) {
+                indexes.push(position);
+                starts.push(run.start);
+            }
+        }
+        known = { indexes, starts };
+        index.events.set(key, known);
+    }
+    return known;
+}
+/**
+ * How many of a view's runs of at least `minimum` and under `maximum` (`null`: no upper bound)
+ * start in `[from, to)` (`null`: no upper bound). The view's last run counts at its cut length,
+ * and not at all when it ends at `skipEndingAt`.
+ */
+export function countEvents(view, bounds, range, skipEndingAt) {
+    const { minimum, maximum } = bounds;
+    const { from, to } = range;
+    const list = eventsOf(view.index, minimum, maximum);
+    const whole = lowerBound(list.indexes, view.count - 1);
+    const low = lowerBound(list.starts, from, whole);
+    const high = to === null ? whole : lowerBound(list.starts, to, whole);
+    let found = high > low ? high - low : 0;
+    const { last } = view;
+    if (last !== undefined) {
+        const taken = length(last);
+        if (taken >= minimum &&
+            (maximum === null || taken < maximum) &&
+            last.start >= from &&
+            (to === null || last.start < to) &&
+            last.end !== skipEndingAt) {
+            found++;
+        }
+    }
+    return found;
+}
+/** The entries starting before `at`: the log's length at `at`. */
+function entriesBefore(store, at) {
+    return lowerBound(store.entryStarts, at);
+}
+/** The start of the log's first entry, when it starts before `at`. */
+export function logStartBefore(store, at) {
+    const first = store.entries[0];
+    return first !== undefined && first.start < at ? first.start : undefined;
+}
+/** The log's last entry as it stood at `at`, cut there. */
+export function lastEntryBefore(store, at) {
+    const taken = entriesBefore(store, at);
+    const entry = taken > 0 ? store.entries[taken - 1] : undefined;
+    return entry !== undefined && entry.end > at ? { ...entry, end: at } : entry;
+}
+/** The entry holding the instant `at`, if one does (start ≤ at < end). */
+export function entryHolding(store, at) {
+    const taken = lowerBound(store.entryStarts, at + 1n);
+    const entry = taken > 0 ? store.entries[taken - 1] : undefined;
+    return entry !== undefined && entry.end > at ? entry : undefined;
+}
+/**
+ * The first entry in `statuses` that starts at or after `from` (`null`: any) and before `at`.
+ */
+export function firstEntryIn(store, statuses, from, at) {
+    let next = store.nextMatch.get(statuses);
+    if (next === undefined) {
+        const found = Array.from({ length: store.entries.length + 1 }, () => store.entries.length);
+        for (let position = store.entries.length - 1; position >= 0; position--) {
+            found[position] = statuses.has(store.entries[position].status)
+                ? position
+                : found[position + 1];
+        }
+        next = found;
+        store.nextMatch.set(statuses, next);
+    }
+    const begin = from === null ? 0 : lowerBound(store.entryStarts, from);
+    const entry = store.entries[next[begin]];
+    return entry !== undefined && entry.start < at ? entry : undefined;
+}
+/** One break applied to a required-interruption state. */
+function interrupt(state, pause, minimum, split) {
+    const taken = length(pause);
+    if (taken >= minimum) {
+        return { resetAt: pause.end, part: 0 };
+    }
+    if (split !== null && taken >= split[state.part]) {
+        const part = state.part + 1;
+        return part === split.length
+            ? { resetAt: pause.end, part: 0 }
+            : { resetAt: state.resetAt, part };
+    }
+    return state;
+}
+/**
+ * Where a required-interruption count was reset, taking every break a view holds in order: a break
+ * of `minimum` resets it, and breaks that meet `split` one after another in order reset it too.
+ *
+ * @returns the instant of the last reset, or null when none
+ */
+export function interruptionResetAt(view, minimum, split) {
+    const { index } = view;
+    const key = `${minimum}|${split === null ? "" : split.join(",")}`;
+    let states = index.interruptions.get(key);
+    if (states === undefined) {
+        const resetAt = [];
+        const part = [];
+        let state = {
+            resetAt: null,
+            part: 0,
+        };
+        for (const pause of index.runs) {
+            state = interrupt(state, pause, minimum, split);
+            resetAt.push(state.resetAt);
+            part.push(state.part);
+        }
+        states = { resetAt, part };
+        index.interruptions.set(key, states);
+    }
+    if (view.last === undefined) {
+        return null;
+    }
+    const before = view.count - 2;
+    const state = interrupt(before < 0
+        ? { resetAt: null, part: 0 }
+        : {
+            resetAt: states.resetAt[before],
+            part: states.part[before],
+        }, view.last, minimum, split);
+    return state.resetAt;
+}
+/** Whether two rests of these lengths, in a row and each over the floor, are a pair. */
+function qualifies(pair, earlier, later) {
+    return ((earlier > later ? earlier : later) >= pair.one &&
+        earlier + later >= pair.combined);
+}
+/** The pairs of the whole log for these floors, as `restPairs` finds them, built once. */
+function pairTableOf(index, fullRest, pair) {
+    const key = `${fullRest}|${pair.each}|${pair.one}|${pair.combined}`;
+    const pairs = (earlier, taken) => qualifies(pair, earlier, taken);
+    let known = index.pairTables.get(key);
+    if (known === undefined) {
+        const seconds = [];
+        const firsts = [];
+        const previous = [];
+        let before = -1;
+        for (const [position, run] of index.runs.entries()) {
+            const taken = length(run);
+            previous.push(before);
+            if (taken >= fullRest) {
+                before = -1;
+            }
+            else if (taken >= pair.each) {
+                if (before >= 0 &&
+                    pairs(length(index.runs[before]), taken)) {
+                    seconds.push(position);
+                    firsts.push(before);
+                }
+                before = position;
+            }
+        }
+        known = { seconds, firsts, previous };
+        index.pairTables.set(key, known);
+    }
+    return known;
+}
+/**
+ * The latest rest pair among a view's runs from `from` on: what the last of
+ * `restPairs(viewRunsFrom(view, from), fullRest, pair)` is, without walking the runs. Only the
+ * view's last run is cut, so it is tried by itself and every earlier pair comes from the whole-log
+ * table.
+ */
+export function latestPairFrom(view, from, fullRest, pair) {
+    const { index, count, last } = view;
+    if (count === 0 || last === undefined) {
+        return undefined;
+    }
+    const table = pairTableOf(index, fullRest, pair);
+    const taken = length(last);
+    const before = table.previous[count - 1];
+    if (taken < fullRest && taken >= pair.each && before >= from) {
+        const earlier = index.runs[before];
+        if (qualifies(pair, length(earlier), taken)) {
+            return { first: earlier, second: last };
+        }
+    }
+    const found = firstWhere(table.seconds.length, (k) => table.seconds[k] >= count - 1) - 1;
+    return found >= 0 && table.firsts[found] >= from
+        ? {
+            first: index.runs[table.firsts[found]],
+            second: index.runs[table.seconds[found]],
+        }
+        : undefined;
+}
+/** How many of the ascending values are in `[low, high)`. */
+export function countInRange(sorted, low, high) {
+    return high > low ? lowerBound(sorted, high) - lowerBound(sorted, low) : 0;
+}

package/dist/internal/earlierOccurrence.d.ts

@@ -0,0 +1,41 @@
+import { Temporal } from "./temporal.js";
+import type { ZoneFrame } from "./zoneFrame.js";
+/** Whether a local wall time is one instant, a repeated hour or a skipped one. */
+export type WallClassification = "unique" | "ambiguous" | "nonexistent";
+/**
+ * Classify a local wall time in a named zone and place its earlier reading.
+ *
+ * Temporal separates a repeated wall time from a skipped one the same way: two instants. Only the
+ * wall clock the earlier one lands on tells them apart: for an overlap both instants read back as
+ * the requested time, and for a gap neither does, because `"earlier"` and `"later"` resolve a gap
+ * by moving off the requested time entirely.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param wall the local wall time
+ * @param timeZone a Temporal time zone identifier (a `ZoneFrame`'s `timeZone` with no stored offset)
+ * @returns the classification, the earlier reading (for a gap, the one `"earlier"` moves to) and the later one
+ *
+ * @example classifyWall(Temporal.PlainDateTime.from("2024-11-03T01:30:00"), "America/New_York").kind // "ambiguous"
+ * @example classifyWall(Temporal.PlainDateTime.from("2024-03-10T02:30:00"), "America/New_York").kind // "nonexistent"
+ */
+export declare function classifyWall(wall: Temporal.PlainDateTime, timeZone: string): {
+    kind: WallClassification;
+    earliest: Temporal.ZonedDateTime;
+    latest: Temporal.ZonedDateTime;
+};
+/**
+ * The instant a local wall time names: the first occurrence of a repeated hour, as RFC 5545
+ * §3.3.5 reads a local time that "occurs more than once", and `null` for a skipped one, which is
+ * never shifted.
+ *
+ * @param wall the local wall time
+ * @param frame the zone, from `zoneFrame`; a frame with a stored offset (seconds) names no
+ * `ZonedDateTime`, so it answers `null`
+ * @returns the zoned date-time, or `null` for a skipped wall time, a wall time Temporal cannot
+ * place, or a frame with a stored offset
+ *
+ * @example earlierOccurrence(Temporal.PlainDateTime.from("2024-11-03T01:30:00"), { timeZone: "America/New_York", shiftNanoseconds: 0n })?.offset // "-04:00"
+ * @example earlierOccurrence(Temporal.PlainDateTime.from("2024-03-10T02:30:00"), { timeZone: "America/New_York", shiftNanoseconds: 0n }) // null
+ */
+export declare function earlierOccurrence(wall: Temporal.PlainDateTime, frame: ZoneFrame): Temporal.ZonedDateTime | null;

package/dist/internal/earlierOccurrence.js

@@ -0,0 +1,57 @@
+import { Temporal } from "./temporal.js";
+import { plainToZoned } from "./zonedWallClockOperations.js";
+/**
+ * Classify a local wall time in a named zone and place its earlier reading.
+ *
+ * Temporal separates a repeated wall time from a skipped one the same way: two instants. Only the
+ * wall clock the earlier one lands on tells them apart: for an overlap both instants read back as
+ * the requested time, and for a gap neither does, because `"earlier"` and `"later"` resolve a gap
+ * by moving off the requested time entirely.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param wall the local wall time
+ * @param timeZone a Temporal time zone identifier (a `ZoneFrame`'s `timeZone` with no stored offset)
+ * @returns the classification, the earlier reading (for a gap, the one `"earlier"` moves to) and the later one
+ *
+ * @example classifyWall(Temporal.PlainDateTime.from("2024-11-03T01:30:00"), "America/New_York").kind // "ambiguous"
+ * @example classifyWall(Temporal.PlainDateTime.from("2024-03-10T02:30:00"), "America/New_York").kind // "nonexistent"
+ */
+export function classifyWall(wall, timeZone) {
+    const earliest = plainToZoned(wall, timeZone, "earlier");
+    const latest = plainToZoned(wall, timeZone, "later");
+    if (earliest.epochNanoseconds === latest.epochNanoseconds) {
+        return { kind: "unique", earliest, latest };
+    }
+    return {
+        kind: earliest.toPlainDateTime().equals(wall) ? "ambiguous" : "nonexistent",
+        earliest,
+        latest,
+    };
+}
+/**
+ * The instant a local wall time names: the first occurrence of a repeated hour, as RFC 5545
+ * §3.3.5 reads a local time that "occurs more than once", and `null` for a skipped one, which is
+ * never shifted.
+ *
+ * @param wall the local wall time
+ * @param frame the zone, from `zoneFrame`; a frame with a stored offset (seconds) names no
+ * `ZonedDateTime`, so it answers `null`
+ * @returns the zoned date-time, or `null` for a skipped wall time, a wall time Temporal cannot
+ * place, or a frame with a stored offset
+ *
+ * @example earlierOccurrence(Temporal.PlainDateTime.from("2024-11-03T01:30:00"), { timeZone: "America/New_York", shiftNanoseconds: 0n })?.offset // "-04:00"
+ * @example earlierOccurrence(Temporal.PlainDateTime.from("2024-03-10T02:30:00"), { timeZone: "America/New_York", shiftNanoseconds: 0n }) // null
+ */
+export function earlierOccurrence(wall, frame) {
+    if (frame.shiftNanoseconds !== 0n) {
+        return null;
+    }
+    try {
+        const { kind, earliest } = classifyWall(wall, frame.timeZone);
+        return kind === "nonexistent" ? null : earliest;
+    }
+    catch {
+        return null;
+    }
+}