@northguild/gmt 1.17.0 → 1.19.0

package/dist/duty/calculate/dutyViolations.d.ts

@@ -0,0 +1,74 @@
+import type { Disambiguation, DutyEntry, DutyRule, DutyViolation, Interval } from "../../types/index.js";
+/**
+ * Return every violation of a set of hours-of-work rules inside a range, each with the window
+ * that failed it: the record over a month, not the check before dispatch.
+ *
+ * - Each rule is checked as `evaluateDutyLog` checks it, at every instant where its answer can
+ *   change: entry bounds, those bounds shifted by a sliding window's length, where a run reaches
+ *   or falls below a floor the rule compares it with, the boundaries of its local periods, and
+ *   the instants either side of each. So the record does not depend on how a status is split
+ *   into entries.
+ * - One entry per violation. A moving window (an elapsed duration, or more than one local period)
+ *   is one violation for as long as it keeps failing, with no passing check between, reported by
+ *   the window that failed worst, the earliest on a tie. A count since a reset, or one short rest
+ *   before a duty, is one violation however often it is checked, reported by its worst check. One
+ *   fixed period is one violation, reported by its last check, which judges the period complete.
+ * - A violation is listed in the range it began in. One already failing at `range.start` belongs
+ *   to the range before; one still failing at `range.end` is followed to its worst window, which
+ *   may end after the range, but never past the log's last entry. So two adjacent ranges list
+ *   every violation once.
+ * - Each check reads the log as it stood then, so a failure stays listed when later entries would
+ *   have excused it, such as a rest that completes a pair after the window it would have moved
+ *   had closed. The record lists what a check at that moment would have said, so it only grows as
+ *   the log does.
+ * - Only logged time is judged. Nothing after the log's last entry is checked, so a range running
+ *   past the log reads as one ending with it, and a period still open there is judged as not yet
+ *   over. Nothing before the log's first entry (and, for `usageLookback`, its first use) is
+ *   checked either, so a range of any length is read as the part of it the log covers.
+ * - Time before the log is read two ways. `evaluateDutyLog` reads it strictly, for a check before
+ *   dispatch: it is neither work nor rest, so a rest rule whose window reaches back before the log
+ *   fails for want of logged rest. The record does not invent a violation there: a rest rule
+ *   (`restRequirement`, `freePeriod`, `pattern`, `restBeforeDuty`) is not judged on a window that
+ *   starts before the log's first entry. A cap is, since time no entry covers never counts towards
+ *   one. Both read the log's first entry as the start of a stretch without rest for `maxGap`.
+ * - Rules with `severity: "advisory"` are not listed: an advisory is not a violation.
+ * - Entries are ordered by window start, then by the order of `rules`.
+ * - Returns `null` for anything `evaluateDutyLog` refuses, for a `range` that is not a valid
+ *   `Interval`, when more than 10,000 of a rule's local periods end in the part of `range` the log
+ *   covers, and when one rule would need more than 1,000,000 instants checked there.
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param range `{ start, end }` record of ISO 8601 instant strings to report on
+ * @param rules the rules, every number the caller's
+ * @param options the reference zone and the operator day
+ * @returns the violations, or null on invalid input
+ *
+ * @example dutyViolations([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T10:00:00Z" }, { status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T22:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, [{ label: "11 driving", kind: "cumulativeCap", statuses: ["driving"], cap: "PT11H", since: { statuses: ["off"], consecutive: "PT10H" } }], { timeZone: "UTC" }) // [{ label: "11 driving", window: { start: "2024-01-01T10:00:00Z", end: "2024-01-01T22:00:00Z" }, used: "PT12H", limit: "PT11H" }]
+ * @example dutyViolations([], { start: "2024-01-01T00:00:00Z", end: "2024-02-01T00:00:00Z" }, [], { timeZone: "UTC" }) // []
+ * @example dutyViolations([], { start: "2024-02-01T00:00:00Z", end: "2024-01-01T00:00:00Z" }, [], { timeZone: "UTC" }) // null — inverted range
+ */
+export declare function dutyViolations(log: DutyEntry[], range: Interval, rules: DutyRule[], options: {
+    /**
+     * The reference time zone every local period is read in, an IANA name or UTC offset: a time
+     * zone identifier (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns).
+     */
+    timeZone: string;
+    /**
+     * The local wall time each operator day starts at, as an ISO PlainTime string (`"04:00"`).
+     * A rule that counts `operatorDays` needs it.
+     *
+     * @defaultValue None. A rule that counts operator days makes the call invalid.
+     */
+    dayStartTime?: string;
+    /**
+     * How a day start, or a `freePeriod` window edge, that the clock repeats or skips becomes an
+     * instant, as `resolveLocal` resolves it. `"compatible"` reads a skipped time after the gap
+     * and a repeated one at its first pass, `"earlier"` and `"later"` take that side in both
+     * cases, and `"reject"` returns the sentinel when an operator day a rule counts starts or ends
+     * at such a time, or a local window with such an edge reaches a logged free period.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
+    disambiguation?: Disambiguation;
+}): DutyViolation[] | null;

package/dist/duty/calculate/dutyViolations.js

@@ -0,0 +1,65 @@
+import { parseIntervalNanoseconds } from "../../internal/index.js";
+import { prepareDutyCall, scanDutyViolations } from "../../internal/dutyEngine.js";
+/**
+ * Return every violation of a set of hours-of-work rules inside a range, each with the window
+ * that failed it: the record over a month, not the check before dispatch.
+ *
+ * - Each rule is checked as `evaluateDutyLog` checks it, at every instant where its answer can
+ *   change: entry bounds, those bounds shifted by a sliding window's length, where a run reaches
+ *   or falls below a floor the rule compares it with, the boundaries of its local periods, and
+ *   the instants either side of each. So the record does not depend on how a status is split
+ *   into entries.
+ * - One entry per violation. A moving window (an elapsed duration, or more than one local period)
+ *   is one violation for as long as it keeps failing, with no passing check between, reported by
+ *   the window that failed worst, the earliest on a tie. A count since a reset, or one short rest
+ *   before a duty, is one violation however often it is checked, reported by its worst check. One
+ *   fixed period is one violation, reported by its last check, which judges the period complete.
+ * - A violation is listed in the range it began in. One already failing at `range.start` belongs
+ *   to the range before; one still failing at `range.end` is followed to its worst window, which
+ *   may end after the range, but never past the log's last entry. So two adjacent ranges list
+ *   every violation once.
+ * - Each check reads the log as it stood then, so a failure stays listed when later entries would
+ *   have excused it, such as a rest that completes a pair after the window it would have moved
+ *   had closed. The record lists what a check at that moment would have said, so it only grows as
+ *   the log does.
+ * - Only logged time is judged. Nothing after the log's last entry is checked, so a range running
+ *   past the log reads as one ending with it, and a period still open there is judged as not yet
+ *   over. Nothing before the log's first entry (and, for `usageLookback`, its first use) is
+ *   checked either, so a range of any length is read as the part of it the log covers.
+ * - Time before the log is read two ways. `evaluateDutyLog` reads it strictly, for a check before
+ *   dispatch: it is neither work nor rest, so a rest rule whose window reaches back before the log
+ *   fails for want of logged rest. The record does not invent a violation there: a rest rule
+ *   (`restRequirement`, `freePeriod`, `pattern`, `restBeforeDuty`) is not judged on a window that
+ *   starts before the log's first entry. A cap is, since time no entry covers never counts towards
+ *   one. Both read the log's first entry as the start of a stretch without rest for `maxGap`.
+ * - Rules with `severity: "advisory"` are not listed: an advisory is not a violation.
+ * - Entries are ordered by window start, then by the order of `rules`.
+ * - Returns `null` for anything `evaluateDutyLog` refuses, for a `range` that is not a valid
+ *   `Interval`, when more than 10,000 of a rule's local periods end in the part of `range` the log
+ *   covers, and when one rule would need more than 1,000,000 instants checked there.
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param range `{ start, end }` record of ISO 8601 instant strings to report on
+ * @param rules the rules, every number the caller's
+ * @param options the reference zone and the operator day
+ * @returns the violations, or null on invalid input
+ *
+ * @example dutyViolations([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T10:00:00Z" }, { status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T22:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, [{ label: "11 driving", kind: "cumulativeCap", statuses: ["driving"], cap: "PT11H", since: { statuses: ["off"], consecutive: "PT10H" } }], { timeZone: "UTC" }) // [{ label: "11 driving", window: { start: "2024-01-01T10:00:00Z", end: "2024-01-01T22:00:00Z" }, used: "PT12H", limit: "PT11H" }]
+ * @example dutyViolations([], { start: "2024-01-01T00:00:00Z", end: "2024-02-01T00:00:00Z" }, [], { timeZone: "UTC" }) // []
+ * @example dutyViolations([], { start: "2024-02-01T00:00:00Z", end: "2024-01-01T00:00:00Z" }, [], { timeZone: "UTC" }) // null — inverted range
+ */
+export function dutyViolations(log, range, rules, options) {
+    try {
+        const bounds = parseIntervalNanoseconds(range);
+        const call = prepareDutyCall(log, rules, options);
+        if (bounds === null || call === null) {
+            return null;
+        }
+        return scanDutyViolations(call.context, call.rules, bounds);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/duty/calculate/evaluateDutyLog.d.ts

@@ -0,0 +1,77 @@
+import type { Disambiguation, DutyEntry, DutyReport, DutyRule } from "../../types/index.js";
+/**
+ * Evaluate every hours-of-work rule over a duty log at one instant, and report each one whether
+ * or not it binds.
+ *
+ * GMT implements no regulation: each rule is a shape, and every number in it is the caller's. A
+ * regime is the array of rules the caller assembles and labels. GMT reports totals, what is left
+ * and what failed; it does not decide dispatch, fitness or eligibility.
+ *
+ * - The log is read as it stands at `at`: later entries are ignored and one straddling `at` is cut
+ *   there. Time no entry covers is in no status, so it is neither work nor rest. That includes the
+ *   time before the log's first entry: give a log that reaches back as far as the longest rule
+ *   looks, or a rest rule fails for want of logged rest. A planned roster is the same call with
+ *   the plan appended and `at` set to its end.
+ * - This is the strict reading, for a check before dispatch. `dutyViolations` reads a record the
+ *   other way: it does not judge a rest rule on a window that starts before the log's first
+ *   entry, since the log cannot say what happened then. Both read the log's first entry as the
+ *   start of a stretch without rest for `maxGap`, as the end of a rest would be.
+ * - Every outcome carries `used`, `limit`, `remaining`, `window`, `dueBy` and `resetAt`, so the
+ *   second-tightest limit is visible before it binds. Failed rules are listed again under
+ *   `violations` or, with `severity: "advisory"`, under `advisories` only.
+ * - A duration in a `Period` is a sliding window ending at `at`; `operatorDays` are the days of
+ *   `dutyDayFor`; calendar days, ISO weeks, months and years are local periods in `timeZone`,
+ *   23 or 25 hours long across a one-hour clock change. Each outcome names its `periodBasis`.
+ * - The local periods are the ones holding the last instant before `at`, so at a boundary the
+ *   period just ended is judged: a roster ending at midnight is checked through its last day.
+ * - A window that runs past `at` (the rest of today, this week) has not failed a minimum while
+ *   the minimum could still be met with rest from `at` to its end; a cap fails as soon as it is
+ *   passed.
+ * - Endpoints are UTC instants ending in "Z"; durations are ISO 8601 with hours as the largest
+ *   unit (`"PT49H30M"`).
+ * - Returns `null` when the log fails `isValidDutyLog`, when `at` is not an ISO 8601 instant
+ *   string, when a rule is malformed (an unknown kind, a status list that is empty or holds a
+ *   non-string, a duration that is not positive exact time, a malformed period, a duplicate
+ *   label, a count of periods past 10,000 alone or times `adjacent`, `lookback` or `periods`, a
+ *   `containing.count` past 10,000), when `options.timeZone` is invalid, when a rule counts
+ *   `operatorDays` without `options.dayStartTime`, when a window, or a requirement `orFactor`
+ *   scales, falls outside Temporal's range, when a count of free periods passes
+ *   `Number.MAX_SAFE_INTEGER`, and when one run of rest in a `freePeriod` window holds more than
+ *   20,000 of its `containing` windows (about 54 years of a daily window).
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param at ISO 8601 instant string to evaluate at
+ * @param rules the rules, every number the caller's
+ * @param options the reference zone and the operator day
+ * @returns the report, or null on invalid input
+ *
+ * @example evaluateDutyLog([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T10:00:00Z" }, { status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T21:00:00Z" }], "2024-01-01T21:00:00Z", [{ label: "11 driving", kind: "cumulativeCap", statuses: ["driving"], cap: "PT11H", since: { statuses: ["off"], consecutive: "PT10H" } }], { timeZone: "UTC" }) // { at: "2024-01-01T21:00:00Z", outcomes: [{ label: "11 driving", kind: "cumulativeCap", severity: "violation", satisfied: true, used: "PT11H", limit: "PT11H", remaining: "PT0S", window: { start: "2024-01-01T10:00:00Z", end: "2024-01-01T21:00:00Z" }, periodBasis: null, dueBy: null, resetAt: "2024-01-01T10:00:00Z" }], violations: [], advisories: [] }
+ * @example evaluateDutyLog([{ status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T21:00:00Z" }], "2024-01-01T21:00:00Z", [{ label: "60 in 7", kind: "rollingCap", statuses: ["driving"], cap: "PT60H", window: { operatorDays: 7 } }], { timeZone: "UTC" }) // null — operator days without dayStartTime
+ * @example evaluateDutyLog([], "2024-01-01T00:00:00Z", [], { timeZone: "UTC" }) // { at: "2024-01-01T00:00:00Z", outcomes: [], violations: [], advisories: [] }
+ * @example evaluateDutyLog([{ status: "on", start: "2024-01-01T02:00:00Z", end: "2024-01-01T01:00:00Z" }], "2024-01-01T03:00:00Z", [], { timeZone: "UTC" }) // null — inverted entry
+ */
+export declare function evaluateDutyLog(log: DutyEntry[], at: string, rules: DutyRule[], options: {
+    /**
+     * The reference time zone every local period is read in, an IANA name or UTC offset: a time
+     * zone identifier (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns). A log kept in another clock is converted to instants first.
+     */
+    timeZone: string;
+    /**
+     * The local wall time each operator day starts at, as an ISO PlainTime string (`"04:00"`).
+     * A rule that counts `operatorDays` needs it.
+     *
+     * @defaultValue None. A rule that counts operator days makes the call invalid.
+     */
+    dayStartTime?: string;
+    /**
+     * How a day start, or a `freePeriod` window edge, that the clock repeats or skips becomes an
+     * instant, as `resolveLocal` resolves it. `"compatible"` reads a skipped time after the gap
+     * and a repeated one at its first pass, `"earlier"` and `"later"` take that side in both
+     * cases, and `"reject"` returns the sentinel when an operator day a rule counts starts or ends
+     * at such a time, or a local window with such an edge reaches a logged free period.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
+    disambiguation?: Disambiguation;
+}): DutyReport | null;

package/dist/duty/calculate/evaluateDutyLog.js

@@ -0,0 +1,75 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { parseInstantNanoseconds } from "../../internal/index.js";
+import { evaluateDutyRules, prepareDutyCall } from "../../internal/dutyEngine.js";
+/**
+ * Evaluate every hours-of-work rule over a duty log at one instant, and report each one whether
+ * or not it binds.
+ *
+ * GMT implements no regulation: each rule is a shape, and every number in it is the caller's. A
+ * regime is the array of rules the caller assembles and labels. GMT reports totals, what is left
+ * and what failed; it does not decide dispatch, fitness or eligibility.
+ *
+ * - The log is read as it stands at `at`: later entries are ignored and one straddling `at` is cut
+ *   there. Time no entry covers is in no status, so it is neither work nor rest. That includes the
+ *   time before the log's first entry: give a log that reaches back as far as the longest rule
+ *   looks, or a rest rule fails for want of logged rest. A planned roster is the same call with
+ *   the plan appended and `at` set to its end.
+ * - This is the strict reading, for a check before dispatch. `dutyViolations` reads a record the
+ *   other way: it does not judge a rest rule on a window that starts before the log's first
+ *   entry, since the log cannot say what happened then. Both read the log's first entry as the
+ *   start of a stretch without rest for `maxGap`, as the end of a rest would be.
+ * - Every outcome carries `used`, `limit`, `remaining`, `window`, `dueBy` and `resetAt`, so the
+ *   second-tightest limit is visible before it binds. Failed rules are listed again under
+ *   `violations` or, with `severity: "advisory"`, under `advisories` only.
+ * - A duration in a `Period` is a sliding window ending at `at`; `operatorDays` are the days of
+ *   `dutyDayFor`; calendar days, ISO weeks, months and years are local periods in `timeZone`,
+ *   23 or 25 hours long across a one-hour clock change. Each outcome names its `periodBasis`.
+ * - The local periods are the ones holding the last instant before `at`, so at a boundary the
+ *   period just ended is judged: a roster ending at midnight is checked through its last day.
+ * - A window that runs past `at` (the rest of today, this week) has not failed a minimum while
+ *   the minimum could still be met with rest from `at` to its end; a cap fails as soon as it is
+ *   passed.
+ * - Endpoints are UTC instants ending in "Z"; durations are ISO 8601 with hours as the largest
+ *   unit (`"PT49H30M"`).
+ * - Returns `null` when the log fails `isValidDutyLog`, when `at` is not an ISO 8601 instant
+ *   string, when a rule is malformed (an unknown kind, a status list that is empty or holds a
+ *   non-string, a duration that is not positive exact time, a malformed period, a duplicate
+ *   label, a count of periods past 10,000 alone or times `adjacent`, `lookback` or `periods`, a
+ *   `containing.count` past 10,000), when `options.timeZone` is invalid, when a rule counts
+ *   `operatorDays` without `options.dayStartTime`, when a window, or a requirement `orFactor`
+ *   scales, falls outside Temporal's range, when a count of free periods passes
+ *   `Number.MAX_SAFE_INTEGER`, and when one run of rest in a `freePeriod` window holds more than
+ *   20,000 of its `containing` windows (about 54 years of a daily window).
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param at ISO 8601 instant string to evaluate at
+ * @param rules the rules, every number the caller's
+ * @param options the reference zone and the operator day
+ * @returns the report, or null on invalid input
+ *
+ * @example evaluateDutyLog([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T10:00:00Z" }, { status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T21:00:00Z" }], "2024-01-01T21:00:00Z", [{ label: "11 driving", kind: "cumulativeCap", statuses: ["driving"], cap: "PT11H", since: { statuses: ["off"], consecutive: "PT10H" } }], { timeZone: "UTC" }) // { at: "2024-01-01T21:00:00Z", outcomes: [{ label: "11 driving", kind: "cumulativeCap", severity: "violation", satisfied: true, used: "PT11H", limit: "PT11H", remaining: "PT0S", window: { start: "2024-01-01T10:00:00Z", end: "2024-01-01T21:00:00Z" }, periodBasis: null, dueBy: null, resetAt: "2024-01-01T10:00:00Z" }], violations: [], advisories: [] }
+ * @example evaluateDutyLog([{ status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T21:00:00Z" }], "2024-01-01T21:00:00Z", [{ label: "60 in 7", kind: "rollingCap", statuses: ["driving"], cap: "PT60H", window: { operatorDays: 7 } }], { timeZone: "UTC" }) // null — operator days without dayStartTime
+ * @example evaluateDutyLog([], "2024-01-01T00:00:00Z", [], { timeZone: "UTC" }) // { at: "2024-01-01T00:00:00Z", outcomes: [], violations: [], advisories: [] }
+ * @example evaluateDutyLog([{ status: "on", start: "2024-01-01T02:00:00Z", end: "2024-01-01T01:00:00Z" }], "2024-01-01T03:00:00Z", [], { timeZone: "UTC" }) // null — inverted entry
+ */
+export function evaluateDutyLog(log, at, rules, options) {
+    try {
+        const instant = typeof at === "string" ? parseInstantNanoseconds(at) : null;
+        const call = prepareDutyCall(log, rules, options);
+        if (instant === null || call === null) {
+            return null;
+        }
+        const outcomes = evaluateDutyRules(call.context, call.rules, instant);
+        return {
+            at: Temporal.Instant.fromEpochNanoseconds(instant).toString(),
+            outcomes,
+            violations: outcomes.filter((outcome) => !outcome.satisfied && outcome.severity === "violation"),
+            advisories: outcomes.filter((outcome) => !outcome.satisfied && outcome.severity === "advisory"),
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/duty/calculate/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./dutyDayFor.js";
+export * from "./dutyTotals.js";
+export * from "./dutyViolations.js";
+export * from "./evaluateDutyLog.js";
+export * from "./longestRun.js";
+export * from "./qualifyingRestPairs.js";
+export * from "./qualifyingRests.js";

package/dist/duty/calculate/index.js

@@ -0,0 +1,7 @@
+export * from "./dutyDayFor.js";
+export * from "./dutyTotals.js";
+export * from "./dutyViolations.js";
+export * from "./evaluateDutyLog.js";
+export * from "./longestRun.js";
+export * from "./qualifyingRestPairs.js";
+export * from "./qualifyingRests.js";

package/dist/duty/calculate/longestRun.d.ts

@@ -0,0 +1,28 @@
+import type { DutyEntry, Interval } from "../../types/index.js";
+/**
+ * Return the longest unbroken stretch a duty log spends in any of `statuses` inside a window.
+ *
+ * - A stretch is a run of touching entries whose statuses are all in `statuses`; another status
+ *   or an unlogged gap ends it. Each run is cut to `window` (half-open) before it is measured.
+ * - On a tie the earlier stretch is returned.
+ * - `interval` is in UTC instants ending in "Z"; `duration` is an exact ISO 8601 duration with
+ *   hours as the largest unit.
+ * - Returns `null` when no stretch falls inside the window, which is also the sentinel: when the
+ *   log fails `isValidDutyLog`, when `window` is not a valid `Interval`, and when `statuses` is not
+ *   an array of strings.
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param window `{ start, end }` record of ISO 8601 instant strings to search inside
+ * @param statuses the statuses a stretch is made of
+ * @returns `{ interval, duration }` of the longest stretch, or null when there is none or on invalid input
+ *
+ * @example longestRun([{ status: "driving", start: "2024-01-01T00:00:00Z", end: "2024-01-01T03:00:00Z" }, { status: "onDuty", start: "2024-01-01T03:00:00Z", end: "2024-01-01T04:00:00Z" }, { status: "driving", start: "2024-01-01T04:00:00Z", end: "2024-01-01T08:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // { interval: { start: "2024-01-01T04:00:00Z", end: "2024-01-01T08:00:00Z" }, duration: "PT4H" }
+ * @example longestRun([{ status: "driving", start: "2024-01-01T00:00:00Z", end: "2024-01-01T03:00:00Z" }, { status: "onDuty", start: "2024-01-01T03:00:00Z", end: "2024-01-01T04:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving", "onDuty"]) // { interval: { start: "2024-01-01T00:00:00Z", end: "2024-01-01T04:00:00Z" }, duration: "PT4H" } — touching entries join
+ * @example longestRun([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T08:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // null — none
+ */
+export declare function longestRun(log: DutyEntry[], window: Interval, statuses: string[]): {
+    /** The stretch, as UTC instants ending in "Z", cut to the window. */
+    interval: Interval;
+    /** Its length, an exact ISO 8601 duration with hours as the largest unit. */
+    duration: string;
+} | null;

package/dist/duty/calculate/longestRun.js

@@ -0,0 +1,54 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { formatHourDuration, parseIntervalNanoseconds } from "../../internal/index.js";
+import { parseDutyLog } from "../../internal/dutyLog.js";
+import { clipRuns, readStatusList, runsOf } from "../../internal/dutyEngine.js";
+/**
+ * Return the longest unbroken stretch a duty log spends in any of `statuses` inside a window.
+ *
+ * - A stretch is a run of touching entries whose statuses are all in `statuses`; another status
+ *   or an unlogged gap ends it. Each run is cut to `window` (half-open) before it is measured.
+ * - On a tie the earlier stretch is returned.
+ * - `interval` is in UTC instants ending in "Z"; `duration` is an exact ISO 8601 duration with
+ *   hours as the largest unit.
+ * - Returns `null` when no stretch falls inside the window, which is also the sentinel: when the
+ *   log fails `isValidDutyLog`, when `window` is not a valid `Interval`, and when `statuses` is not
+ *   an array of strings.
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param window `{ start, end }` record of ISO 8601 instant strings to search inside
+ * @param statuses the statuses a stretch is made of
+ * @returns `{ interval, duration }` of the longest stretch, or null when there is none or on invalid input
+ *
+ * @example longestRun([{ status: "driving", start: "2024-01-01T00:00:00Z", end: "2024-01-01T03:00:00Z" }, { status: "onDuty", start: "2024-01-01T03:00:00Z", end: "2024-01-01T04:00:00Z" }, { status: "driving", start: "2024-01-01T04:00:00Z", end: "2024-01-01T08:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // { interval: { start: "2024-01-01T04:00:00Z", end: "2024-01-01T08:00:00Z" }, duration: "PT4H" }
+ * @example longestRun([{ status: "driving", start: "2024-01-01T00:00:00Z", end: "2024-01-01T03:00:00Z" }, { status: "onDuty", start: "2024-01-01T03:00:00Z", end: "2024-01-01T04:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving", "onDuty"]) // { interval: { start: "2024-01-01T00:00:00Z", end: "2024-01-01T04:00:00Z" }, duration: "PT4H" } — touching entries join
+ * @example longestRun([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T08:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // null — none
+ */
+export function longestRun(log, window, statuses) {
+    try {
+        const entries = parseDutyLog(log);
+        const bounds = parseIntervalNanoseconds(window);
+        const wanted = readStatusList(statuses);
+        if (entries === null || bounds === null || wanted === null) {
+            return null;
+        }
+        const runs = clipRuns(runsOf(entries, wanted), bounds.start, bounds.end);
+        const longest = runs.reduce((best, run) => best === undefined || run.end - run.start > best.end - best.start
+            ? run
+            : best, undefined);
+        if (longest === undefined) {
+            return null;
+        }
+        return {
+            interval: {
+                start: Temporal.Instant.fromEpochNanoseconds(longest.start).toString(),
+                end: Temporal.Instant.fromEpochNanoseconds(longest.end).toString(),
+            },
+            duration: formatHourDuration(longest.end - longest.start),
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/duty/calculate/qualifyingRestPairs.d.ts

@@ -0,0 +1,37 @@
+import type { DutyEntry, PairSpec, RestPair } from "../../types/index.js";
+/**
+ * Return every paired rest in a duty log: two separate rests that together count as one, because
+ * they meet all three floors of `spec.pair`.
+ *
+ * A pair is three constraints, not two integers: with `{ eachAtLeast: "PT2H", oneAtLeast: "PT7H",
+ * combinedAtLeast: "PT10H" }`, 7.5 + 2.5 hours and 8 + 2 qualify, and 6 + 4 does not.
+ *
+ * - Rests are runs of touching entries in `spec.statuses`. Two rests in a row pair; either may be
+ *   the longer.
+ * - A rest of `spec.minimum` or more is a full rest on its own: it pairs with nothing, and no pair
+ *   spans it. A rest shorter than `eachAtLeast` is neither half of a pair nor a break between two.
+ * - Pairs chain: rests of 7, 3 and 7 hours give two pairs, (7, 3) and (3, 7).
+ * - Intervals are UTC instants ending in "Z", in log order.
+ * - `[]` is both a legitimate result and the sentinel: returned when the log fails
+ *   `isValidDutyLog`, when `spec` is not an object, when `statuses` is not an array of strings,
+ *   and when `minimum` or a floor of `pair` is not a positive ISO 8601 duration of exact time.
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param spec the statuses a rest is made of, the length of a full rest, and the pair's floors
+ * @returns the pairs as `{ first, second }` records, or [] on invalid input
+ *
+ * @example qualifyingRestPairs([{ status: "sleeper", start: "2024-01-01T00:00:00Z", end: "2024-01-01T07:30:00Z" }, { status: "work", start: "2024-01-01T07:30:00Z", end: "2024-01-01T11:30:00Z" }, { status: "off", start: "2024-01-01T11:30:00Z", end: "2024-01-01T14:00:00Z" }], { statuses: ["off", "sleeper"], minimum: "PT10H", pair: { eachAtLeast: "PT2H", oneAtLeast: "PT7H", combinedAtLeast: "PT10H" } }) // [{ first: { start: "2024-01-01T00:00:00Z", end: "2024-01-01T07:30:00Z" }, second: { start: "2024-01-01T11:30:00Z", end: "2024-01-01T14:00:00Z" } }]
+ * @example qualifyingRestPairs([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T06:00:00Z" }, { status: "work", start: "2024-01-01T06:00:00Z", end: "2024-01-01T10:00:00Z" }, { status: "off", start: "2024-01-01T10:00:00Z", end: "2024-01-01T14:00:00Z" }], { statuses: ["off"], minimum: "PT10H", pair: { eachAtLeast: "PT2H", oneAtLeast: "PT7H", combinedAtLeast: "PT10H" } }) // [] — 6 + 4: neither is 7
+ * @example qualifyingRestPairs([], { statuses: ["off"], minimum: "PT10H" }) // [] — no pair
+ */
+export declare function qualifyingRestPairs(log: DutyEntry[], spec: {
+    /** The statuses a rest is made of. Touching entries in any of them are one rest. */
+    statuses: string[];
+    /**
+     * The length of a full rest, a positive ISO 8601 duration of exact time (`"PT10H"`). A rest
+     * this long or longer is not half of a pair.
+     */
+    minimum: string;
+    /** The three floors the two rests must meet. */
+    pair: PairSpec;
+}): RestPair[];

package/dist/duty/calculate/qualifyingRestPairs.js

@@ -0,0 +1,58 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isObject, nonNegativeExactDurationNanoseconds } from "../../internal/index.js";
+import { readStatusList, restPairs, runsOf } from "../../internal/dutyEngine.js";
+import { parseDutyLog } from "../../internal/dutyLog.js";
+import { parsePairSpec } from "../../internal/dutyRules.js";
+/**
+ * Return every paired rest in a duty log: two separate rests that together count as one, because
+ * they meet all three floors of `spec.pair`.
+ *
+ * A pair is three constraints, not two integers: with `{ eachAtLeast: "PT2H", oneAtLeast: "PT7H",
+ * combinedAtLeast: "PT10H" }`, 7.5 + 2.5 hours and 8 + 2 qualify, and 6 + 4 does not.
+ *
+ * - Rests are runs of touching entries in `spec.statuses`. Two rests in a row pair; either may be
+ *   the longer.
+ * - A rest of `spec.minimum` or more is a full rest on its own: it pairs with nothing, and no pair
+ *   spans it. A rest shorter than `eachAtLeast` is neither half of a pair nor a break between two.
+ * - Pairs chain: rests of 7, 3 and 7 hours give two pairs, (7, 3) and (3, 7).
+ * - Intervals are UTC instants ending in "Z", in log order.
+ * - `[]` is both a legitimate result and the sentinel: returned when the log fails
+ *   `isValidDutyLog`, when `spec` is not an object, when `statuses` is not an array of strings,
+ *   and when `minimum` or a floor of `pair` is not a positive ISO 8601 duration of exact time.
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param spec the statuses a rest is made of, the length of a full rest, and the pair's floors
+ * @returns the pairs as `{ first, second }` records, or [] on invalid input
+ *
+ * @example qualifyingRestPairs([{ status: "sleeper", start: "2024-01-01T00:00:00Z", end: "2024-01-01T07:30:00Z" }, { status: "work", start: "2024-01-01T07:30:00Z", end: "2024-01-01T11:30:00Z" }, { status: "off", start: "2024-01-01T11:30:00Z", end: "2024-01-01T14:00:00Z" }], { statuses: ["off", "sleeper"], minimum: "PT10H", pair: { eachAtLeast: "PT2H", oneAtLeast: "PT7H", combinedAtLeast: "PT10H" } }) // [{ first: { start: "2024-01-01T00:00:00Z", end: "2024-01-01T07:30:00Z" }, second: { start: "2024-01-01T11:30:00Z", end: "2024-01-01T14:00:00Z" } }]
+ * @example qualifyingRestPairs([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T06:00:00Z" }, { status: "work", start: "2024-01-01T06:00:00Z", end: "2024-01-01T10:00:00Z" }, { status: "off", start: "2024-01-01T10:00:00Z", end: "2024-01-01T14:00:00Z" }], { statuses: ["off"], minimum: "PT10H", pair: { eachAtLeast: "PT2H", oneAtLeast: "PT7H", combinedAtLeast: "PT10H" } }) // [] — 6 + 4: neither is 7
+ * @example qualifyingRestPairs([], { statuses: ["off"], minimum: "PT10H" }) // [] — no pair
+ */
+export function qualifyingRestPairs(log, spec) {
+    try {
+        const entries = parseDutyLog(log);
+        if (entries === null || !isObject(spec)) {
+            return [];
+        }
+        const { statuses, minimum, pair } = spec;
+        const wanted = readStatusList(statuses);
+        const fullRest = nonNegativeExactDurationNanoseconds(minimum);
+        const floors = parsePairSpec(pair);
+        if (wanted === null ||
+            fullRest === null ||
+            fullRest === 0n ||
+            floors === null) {
+            return [];
+        }
+        const text = (nanoseconds) => Temporal.Instant.fromEpochNanoseconds(nanoseconds).toString();
+        return restPairs(runsOf(entries, wanted), fullRest, floors).map(({ first, second }) => ({
+            first: { start: text(first.start), end: text(first.end) },
+            second: { start: text(second.start), end: text(second.end) },
+        }));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return [];
+    }
+}

package/dist/duty/calculate/qualifyingRests.d.ts

@@ -0,0 +1,27 @@
+import type { DutyEntry, Interval } from "../../types/index.js";
+/**
+ * Return every rest of at least `minimum` in a duty log: the runs of touching entries in any of
+ * `spec.statuses` that last that long.
+ *
+ * - A run is ended by another status or an unlogged gap, never by a change between two of
+ *   `statuses`: an off period running straight into a sleeper-berth period is one rest.
+ * - The whole log is read. Intervals are UTC instants ending in "Z", in log order.
+ * - For two shorter rests that count together, use `qualifyingRestPairs`.
+ * - `[]` is both a legitimate result and the sentinel: returned when the log fails
+ *   `isValidDutyLog`, when `spec` is not an object, when `statuses` is not an array of strings,
+ *   and when `minimum` is not a positive ISO 8601 duration of exact time.
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param spec the statuses a rest is made of and the shortest that counts
+ * @returns the rests' `{ start, end }` records, or [] on invalid input
+ *
+ * @example qualifyingRests([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T10:00:00Z" }, { status: "work", start: "2024-01-01T10:00:00Z", end: "2024-01-01T16:00:00Z" }, { status: "off", start: "2024-01-01T16:00:00Z", end: "2024-01-01T23:00:00Z" }], { statuses: ["off"], minimum: "PT10H" }) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-01T10:00:00Z" }]
+ * @example qualifyingRests([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T05:00:00Z" }, { status: "sleeper", start: "2024-01-01T05:00:00Z", end: "2024-01-01T12:00:00Z" }], { statuses: ["off", "sleeper"], minimum: "PT10H" }) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-01T12:00:00Z" }] — one rest
+ * @example qualifyingRests([], { statuses: ["off"], minimum: "PT0S" }) // [] — a zero minimum
+ */
+export declare function qualifyingRests(log: DutyEntry[], spec: {
+    /** The statuses a rest is made of. Touching entries in any of them are one rest. */
+    statuses: string[];
+    /** The shortest rest returned, a positive ISO 8601 duration of exact time (`"PT10H"`). */
+    minimum: string;
+}): Interval[];

package/dist/duty/calculate/qualifyingRests.js

@@ -0,0 +1,49 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isObject, nonNegativeExactDurationNanoseconds } from "../../internal/index.js";
+import { parseDutyLog } from "../../internal/dutyLog.js";
+import { readStatusList, runsOf } from "../../internal/dutyEngine.js";
+/**
+ * Return every rest of at least `minimum` in a duty log: the runs of touching entries in any of
+ * `spec.statuses` that last that long.
+ *
+ * - A run is ended by another status or an unlogged gap, never by a change between two of
+ *   `statuses`: an off period running straight into a sleeper-berth period is one rest.
+ * - The whole log is read. Intervals are UTC instants ending in "Z", in log order.
+ * - For two shorter rests that count together, use `qualifyingRestPairs`.
+ * - `[]` is both a legitimate result and the sentinel: returned when the log fails
+ *   `isValidDutyLog`, when `spec` is not an object, when `statuses` is not an array of strings,
+ *   and when `minimum` is not a positive ISO 8601 duration of exact time.
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param spec the statuses a rest is made of and the shortest that counts
+ * @returns the rests' `{ start, end }` records, or [] on invalid input
+ *
+ * @example qualifyingRests([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T10:00:00Z" }, { status: "work", start: "2024-01-01T10:00:00Z", end: "2024-01-01T16:00:00Z" }, { status: "off", start: "2024-01-01T16:00:00Z", end: "2024-01-01T23:00:00Z" }], { statuses: ["off"], minimum: "PT10H" }) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-01T10:00:00Z" }]
+ * @example qualifyingRests([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T05:00:00Z" }, { status: "sleeper", start: "2024-01-01T05:00:00Z", end: "2024-01-01T12:00:00Z" }], { statuses: ["off", "sleeper"], minimum: "PT10H" }) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-01T12:00:00Z" }] — one rest
+ * @example qualifyingRests([], { statuses: ["off"], minimum: "PT0S" }) // [] — a zero minimum
+ */
+export function qualifyingRests(log, spec) {
+    try {
+        const entries = parseDutyLog(log);
+        if (entries === null || !isObject(spec)) {
+            return [];
+        }
+        const { statuses, minimum } = spec;
+        const wanted = readStatusList(statuses);
+        const floor = nonNegativeExactDurationNanoseconds(minimum);
+        if (wanted === null || floor === null || floor === 0n) {
+            return [];
+        }
+        return runsOf(entries, wanted)
+            .filter((run) => run.end - run.start >= floor)
+            .map((run) => ({
+            start: Temporal.Instant.fromEpochNanoseconds(run.start).toString(),
+            end: Temporal.Instant.fromEpochNanoseconds(run.end).toString(),
+        }));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return [];
+    }
+}

package/dist/duty/index.d.ts

@@ -0,0 +1,3 @@
+export * from "@js-temporal/polyfill";
+export * from "./calculate/index.js";
+export * from "./validate/index.js";

package/dist/duty/index.js

@@ -0,0 +1,4 @@
+// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
+export * from "@js-temporal/polyfill";
+export * from "./calculate/index.js";
+export * from "./validate/index.js";

package/dist/duty/validate/index.d.ts

@@ -0,0 +1 @@
+export * from "./isValidDutyLog.js";

package/dist/duty/validate/index.js

@@ -0,0 +1 @@
+export * from "./isValidDutyLog.js";

package/dist/duty/validate/isValidDutyLog.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Validate whether a value is a duty log every `duty/` function accepts.
+ *
+ * - True for an array of `{ status, start, end }` entries where `status` is a string and `start`
+ *   and `end` are ISO 8601 instant strings (offset required, no leap second), `end` after `start`.
+ * - Entries must be ordered by `start` and must not overlap. One may start exactly where the
+ *   previous one ends, since entries are half-open, or later, leaving a gap. Order is by instant,
+ *   not text.
+ * - `[]` is a valid, empty log. Extra keys on an entry are ignored.
+ * - Every other `duty/` function returns its sentinel for a log this rejects.
+ * - Returns `false` for a non-array, an entry that is not an object, a non-string status, a bound
+ *   that is not an instant, a zero-length or inverted entry, and entries out of order or
+ *   overlapping.
+ *
+ * @param log candidate array of `{ status, start, end }` records
+ * @returns boolean indicating whether the log is valid
+ *
+ * @example isValidDutyLog([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T10:00:00Z" }, { status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T15:00:00Z" }]) // true
+ * @example isValidDutyLog([]) // true — an empty log
+ * @example isValidDutyLog([{ status: "on", start: "2024-01-01T02:00:00Z", end: "2024-01-01T01:00:00Z" }]) // false — inverted
+ * @example isValidDutyLog([{ status: "on", start: "2024-01-01T00:00:00Z", end: "2024-01-01T02:00:00Z" }, { status: "off", start: "2024-01-01T01:59:59Z", end: "2024-01-01T03:00:00Z" }]) // false — overlapping
+ * @example isValidDutyLog([{ status: "on", start: "2024-01-01T00:00:00", end: "2024-01-01T01:00:00Z" }]) // false — no offset
+ */
+export declare function isValidDutyLog(log: unknown): boolean;