@northguild/gmt 1.15.0 → 1.17.0

package/skills/gmt-timezone/SKILL.md

@@ -2,9 +2,20 @@
 name: gmt-timezone
 description: >
   Timezone-aware operations — get zoned now, format zoned datetimes/ranges,
-  convert between plain↔zoned↔UTC↔Unix, and DST disambiguation control on
-  construction and arithmetic. Reads the installed package README.md and source
-  JSDoc for API details; this skill is a routing pointer, not an API dump.
+  convert between plain↔zoned↔UTC↔Unix, DST disambiguation on construction and
+  arithmetic, the instant-plus-offset pair, classifying a zoneless wall time
+  before resolving it, real zone unit boundaries
+  (startOfZoned/endOfZoned/startOfUnix/endOfUnix), hours in a local day,
+  flooring or bucketing on local boundaries (floorToZone/bucketRange),
+  calendar-annotated zoned strings, zoned values at the range limits, the
+  transport legs transitTime, etaAtZone and dwellTime (local calendar days
+  crossed), intermodal free time — freeTimeExpiry (the free window and its
+  half-open expiry), chargeableDays (the dates charged, with tier bands),
+  demurrageClock (which events a demurrage, detention, storage or combined clock
+  runs between) — and billingTimeline (invoice, dispute and resolution
+  deadlines, windows as caller parameters). Reads the installed package
+  README.md and source JSDoc for API details; this skill is a routing pointer,
+  not an API dump.
 sources:
   - 'northguild/gmt:README.md'
   - 'northguild/gmt:packages/gmt/src/zoned/get/index.ts'
@@ -14,14 +25,22 @@ sources:
   - 'northguild/gmt:packages/gmt/src/zoned/validate/index.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/calculate/addZoned.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/calculate/startOfZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/roundZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/getHoursInZonedDay.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/calculate/clampZoned.ts'
   - 'northguild/gmt:packages/gmt/src/unix/get/index.ts'
   - 'northguild/gmt:packages/gmt/src/utc/get/index.ts'
   - 'northguild/gmt:packages/gmt/src/utc/convert/index.ts'
+  - 'northguild/gmt:packages/gmt/src/instant/convert/index.ts'
+  - 'northguild/gmt:packages/gmt/src/calendar/calculate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/calendar/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/transport/calculate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/transport/convert/index.ts'
+  - 'northguild/gmt:packages/gmt/src/intermodal/calculate/index.ts'
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.15.0'
+  library_version: '1.17.0'
 ---
 
 # GMT Timezone
@@ -36,27 +55,181 @@ converting between time zones, or doing arithmetic that must respect DST.
 - The user needs to convert a plain datetime to a zoned instant, or between
   timezones, or between UTC and Unix epochs.
 - The user is adding/subtracting durations across a DST transition.
+- The user has a timestamp that must keep the local offset it happened at, or a
+  local wall time that arrived with no offset at all.
+- The user needs the start or end of a local hour, day, week, month or quarter.
+- The user is grouping or aggregating UTC timestamps by local day, hour, week or
+  month — an observability rollup, a chargeable-days count.
+- The user is adding a leg's transit time to a departure, showing an arrival in
+  the zone where it lands, or counting how long cargo, a vessel or a patient sat
+  somewhere in local calendar days.
+- The user is working out when a container's free time ends, how many days of
+  demurrage or detention are chargeable and for which dates, or which events a
+  charge's clock runs between.
 
 ## Core rules
 
 1. **Use IANA timezone ids, not raw offsets.** `"2024-03-15T14:30:45[America/New_York]"`
    is correct; bare `"-05:00"` loses the zone and can't observe DST rules.
-2. **DST disambiguation.** `convertPlainDateTimeToZoned`, `addZoned`, `startOfZoned`,
-   and `setZoned` accept `disambiguation` (`"compatible"` | `"earlier"` |
-   `"later"` | `"reject"`) for gap/overlap resolution. It only affects fall-back
-   overlaps, **not** spring-forward gaps — use `convertPlainDateTimeToZoned`
-   with `"reject"` for gap-safety.
-3. **The `offset` parameter.** Defaults to `"ignore"` so `disambiguation` takes
-   effect. Passing `offset: "prefer"` keeps the source offset and silently
-   disables `disambiguation` — leave it at default unless you need Temporal's
-   raw `.with()` semantics.
-4. **Calendar annotations.** GMT's zoned grammar puts `[u-ca=...]` **before**
-   `[timeZone]` — the reverse of RFC 9557. Only `addZoned`, `subtractZoned`,
-   `diffZoned`, and `convertZonedToCalendar` accept it; everything else rejects
-   it and returns `""`. Always produce these with `convertZonedToCalendar`.
-5. **Read the README.** This skill is a routing pointer. For the full DST
-   disambiguation walkthrough, code examples, and locale ICU notes, read the
-   installed package's `README.md` and the source JSDoc.
+2. **DST disambiguation.** `convertPlainDateTimeToZoned`, `addZoned` and
+   `setZoned` accept `disambiguation` (`"compatible"` | `"earlier"` |
+   `"later"` | `"reject"`) for gap/overlap resolution. On `addZoned`,
+   `subtractZoned` and `intervalFromDurationZoned` it follows TC39
+   AddZonedDateTime: the date part (years to days) moves the wall clock, the
+   time part (hours and smaller) is added in exact time, and `disambiguation`
+   resolves the wall clock the date part lands on, in a spring-forward gap or
+   a fall-back overlap: `"compatible"`/`"later"` move a gap landing forward,
+   `"earlier"` back, `"reject"` returns the sentinel. A time-only duration
+   ignores it, so `+ { minutes: 10 }` is always 10 real minutes.
+3. **Boundaries are always the real zone boundary.** `startOfZoned`,
+   `endOfZoned`, `startOfQuarterForZoned`, `endOfQuarterForZoned`,
+   `getLocaleZonedStartOfWeek`, `getLocaleZonedEndOfWeek` and their `unix/`
+   counterparts (`startOfUnix`,
+   `endOfUnix`, …) return the real start and end of the unit that contains the
+   input: the start is never after the input, and the end is the last
+   nanosecond before the next start, printed at nanosecond precision by default
+   (`"…T23:59:59.999999999…"`); pass `fractionalSecondDigits: 0` for the shorter
+   pre-1.16.0 string. `Pacific/Chatham`'s 03:00 hour on its
+   spring-forward begins at 03:45, and New York's repeated 1 a.m. is its own
+   hour. `areZonedEqualBy`/`areUnixEqualBy` compare these boundary instants, so
+   the two passes of a repeated hour are not equal. A day whose midnight repeats
+   on the same date (America/Havana, 2024-11-03) is one 25-hour day.
+   `getHoursInZonedDay` and `mapZonedHoursInDay` measure the input's calendar
+   date via TC39 `hoursInDay`; that differs from `startOfZoned(…, "day")` only
+   where a fall-back re-enters the previous date (America/Goose_Bay,
+   2010-11-07).
+4. **Boundary functions take no `disambiguation` or `offset`.** They match
+   TC39 `startOfDay()`, which takes no such options. Resolution options belong on
+   functions that set wall-clock fields —
+   `convertPlainDateTimeToZoned`, `resolveLocal`, `addZoned`, `setZoned`.
+5. **Classify a zoneless wall time before resolving it.** `classifyLocal(local,
+   zone)` returns `"unique"` | `"ambiguous"` | `"nonexistent"` so code can branch
+   rather than accept a policy — 01:30 happens twice on a fall-back day and never
+   on a spring-forward one. `resolveLocal(local, zone, { disambiguation })` then
+   returns the instant, exact to the nanosecond, or `""` under `"reject"`. Reach
+   for `convertPlainDateTimeToZoned` instead when you want the zoned string.
+6. **An offset is not a zone.** `-05:00` does not identify `America/New_York`.
+   `toOffsetInstant` splits a timestamp into `{ instant, offset, timeZone? }` —
+   the shape EPCIS 2.0, EDIFACT DTM and DICOM all exchange, because the instant
+   orders events and the offset renders them where they happened, and neither
+   derives from the other. Keep the zone for what is still to be scheduled.
+7. **Bucket in the zone, not in UTC.** `floorToZone(instant, unit, zone)` and
+   `bucketRange(start, end, unit, zone)` floor on the zone's own calendar
+   boundaries. Flooring a UTC instant to a UTC day and calling it a local day is
+   wrong for most of the world for most of the day. The buckets are deliberately
+   not uniform: a day that springs forward is 23 hours and one that falls back is
+   25, and forcing 24 is what makes a daily aggregate drift.
+   `intervalCountZoned`/`intervalCountUnix`/`intervalCountUtc` count exactly
+   the buckets `bucketRange` returns.
+8. **`roundZoned`/`roundUnix` are not a floor.** They follow TC39
+   `ZonedDateTime.round`, which rounds the wall clock and re-resolves it in the
+   zone, so `roundingMode: "trunc"` can land after the input:
+   `"2024-09-29T03:50:00+13:45[Pacific/Chatham]"` truncated to the hour gives
+   04:00. Never truncate-and-re-resolve (`round` with `"trunc"`, or `.with()`
+   on the wall clock) to find a zoned boundary — use `floorToZone` or
+   `startOfZoned` with no options.
+9. **Hours in a day come from the zone.** `getHoursInZonedDay` is Temporal's
+   `hoursInDay`: 23 on a spring-forward day, 25 on a fall-back day, 23.5 in
+   `Australia/Lord_Howe`, and 23 on a day whose midnight is skipped
+   (`America/Santiago`, 2024-09-08). `mapZonedHoursInDay` stops at the next
+   local day.
+10. **Calendar annotations.** A calendar-annotated zoned string is RFC 9557,
+    `Temporal.ZonedDateTime#toString()`: ISO digits, then `[timeZone]`, then
+    `[u-ca=<id>]` (`"2024-10-03T14:30:45-04:00[America/New_York][u-ca=hebrew]"`).
+    A calendar annotation before the zone is rejected. Only `addZoned`, `subtractZoned`,
+    `diffZoned`, `diffZonedAsDuration`, `convertZonedToCalendar`,
+    `isValidCalendarZonedDateTime` and `zoned/interval/*` (including
+    `isValidCalendarZonedInterval`) accept it; everything else rejects it and
+    returns its invalid-input sentinel — `""` for a string result, `null` for a
+    number, `[]` for a list, and `false` for a validator or predicate such as
+    `isValidZonedDateTime` or `isBeforeZoned`. Always produce these with
+    `convertZonedToCalendar`. Calendar ids are the canonical Temporal ids (see
+    the `gmt-arithmetic` skill), and `[!u-ca=…]` is accepted wherever
+    `[u-ca=…]` is. Differences between values naming different calendars
+    return the sentinel for every unit, hours included.
+11. **Zoned values are exact at the range limits.** In zones ahead of UTC,
+    `isValidZonedDateTime("+275760-09-13T10:00:00+10:00[Australia/Sydney]")`
+    is `true` and one nanosecond later is `false`. Parsing, arithmetic,
+    boundaries, differences and `relativeTo` totals all work there.
+    Daylight-saving rules hold to the end: `America/Santiago`'s
+    `+275760-09-07` is a 23-hour day. At the first instant in a zone behind
+    UTC, an offset-less wall clock (`"-271821-04-19T12:00:00[Etc/GMT+12]"`)
+    resolves. The same string with its `-12:00` offset returns the sentinel,
+    because TC39 checks that local date against the day range.
+12. **Zoned differences count calendar units on the wall clock.** `diffZoned`,
+    `diffZonedAsDuration` and `intervalLengthZoned` follow TC39
+    DifferenceZonedDateTime: days, weeks, months and years are counted on the
+    zone's wall clock (noon to noon across a 23-hour day is `1` day), and hours
+    and smaller are exact time. Two values in different zones have no shared
+    wall clock, so a calendar unit returns `null`/`""`; hours still work.
+    Convert both ends to one zone with `convertZonedToZoned` first, or diff the
+    UTC instants with `diffUtc` if UTC days are what you mean.
+    `intervalOverlappingDaysZoned`/`intervalOverlappingDaysUnix` count the
+    distinct local dates the overlap touches: a deleted day is not counted, and a
+    fall-back into the previous date counts that date.
+13. **Zone names and leap seconds.** Every IANA name is a zone, including
+    single-component links (`Japan`, `Zulu`, `EST5EDT`), in any case.
+    `toOffsetInstant` returns IANA casing (`"america/new_york"` gives
+    `"America/New_York"`). `:60` is invalid in every spelling (`T`, `t`, space,
+    basic format) and every zoned function returns its sentinel for it rather
+    than reading `:59`.
+14. **A zoned value formats in its own zone.** `formatZonedDateTime`,
+    `formatZonedRange` and `formatZonedToParts` return `""`/`[]` for a
+    `timeZone` option. To show an instant in another zone, use
+    `formatUtc(convertZonedToUtc(value), locale, { timeZone })`.
+15. **Transport legs are exact time; dwell is counted in local days.**
+    `transitTime(departure, duration)` adds hours, minutes and seconds as
+    elapsed time (`P1D` is 24 exact hours) in the departure's own zone, so a leg
+    across a DST transition lands at the wall time the vehicle really arrives;
+    years, months and weeks return `""`, and a bracketed zone that contradicts
+    its offset is rejected rather than reinterpreted. `etaAtZone(instant, zone)`
+    renders a moment in the zone the caller names — no disambiguation arises,
+    the offset in the result tells the two passes of a fall-back hour apart, and
+    GMT never resolves a port, airport or station code to a zone.
+    `dwellTime(entry, exit, targetZone?)` returns `{ duration, enter, exit,
+    calendarDays }`; `calendarDays` is the number of distinct local dates the
+    half-open `[entry, exit)` touches, walked across the zone's real transitions
+    (a skipped date is not counted, a re-entered one only once), and is the
+    library's one "local days crossed" count.
+    Bare instants with no `targetZone` return `null`: an offset is not a place.
+16. **Free time is counted in the terminal's local days; the start day and the
+    basis are tariff terms, never defaults.**
+    `freeTimeExpiry(clockStart, freeDays, { basis, timeZone, firstDay, calendar? })`
+    returns `{ freeTimeStart, lastFreeDay, expiresAt }`: local dates in
+    `timeZone`, and the first instant of the day after the last free day.
+    `firstDay` (`"eventDay"` | `"nextDay"`) has no default because the two
+    differ by a day of charges; `basis: "working"` needs a `BusinessCalendar`
+    and returns `null` without one. `chargeableDays(clockStart, clockEnd,
+    freeDays, options)` also needs `chargeBasis` (no default): many tariffs
+    count both in calendar days; where a tariff grants free time in working
+    days the days after it are mostly charged as calendar days, and some
+    tariffs charge working days only. It counts the days on or after
+    `expiresAt` the half-open dwell touched, lists them as `chargedDates`, and
+    splits them into `tiers` bands; `freeDays: 0` is allowed there.
+    `demurrageClock(events, scope, { direction, startEvent? })` selects the
+    events per leg: import demurrage and storage run discharge (or
+    availability) to gate-out, detention gate-out to empty return; export
+    demurrage gate-in to loaded, detention empty release to gate-in; `combined`
+    runs both as one period. No standard fixes how these days are counted;
+    every term is the tariff's.
+17. **Billing deadlines are dates counted from an anchor, and every window is
+    the caller's.** `billingTimeline({ anchorOn, invoiceIssuedOn?,
+    requestReceivedOn? }, { issueDays, disputeDays, resolutionDays,
+    agreedResolutionOn? })` returns `{ invoiceDeadline, issuedByDeadline,
+    disputeDeadline, requestedByDeadline, resolutionDeadline }`. Day zero is
+    the anchor and each deadline is `date + days` on the ISO calendar; a date
+    is by the deadline when it is on or before it. No window has a default (a
+    missing one returns `null`); fields whose input does not exist yet are
+    `null`, so an anchor alone is a forecast. The anchor is whatever date the
+    caller counts from: the last charged date
+    (`chargedDates.at(-1)`), or for a re-bill the issuance date of the invoice
+    received. Reduce an instant to the billing party's local date first with
+    `convertUtcToPlainDate(instant, { timeZone })`. A request before its
+    invoice, or an agreed date before the request, returns `null`. GMT
+    computes dates, not liability.
+18. **Read the README.** This skill is a routing pointer. For the full DST
+    disambiguation walkthrough, code examples, and locale ICU notes, read the
+    installed package's `README.md` and the source JSDoc.
 
 ## Key functions
 
@@ -69,12 +242,23 @@ converting between time zones, or doing arithmetic that must respect DST.
   `convertUtcToZoned`, `convertZonedToUtc`, `convertZonedToCalendar`,
   `convertUtcToUnix`, `convertUnixToUtc`
 - **Arithmetic (with disambiguation)**: `addZoned`, `subtractZoned`, `clampZoned`,
-  `closestZonedTo`, `startOfZoned`, `endOfZoned`, `startOfQuarterForZoned`,
-  `setZoned`, `cycleZoned`, `mapZonedHoursInDay`, `getHoursInZonedDay`
+  `closestZonedTo`, `setZoned`, `cycleZoned`, `roundZoned`
+- **Boundaries (real by default)**: `startOfZoned`, `endOfZoned`,
+  `startOfQuarterForZoned`, `endOfQuarterForZoned`,
+  `getLocaleZonedStartOfWeek`, `getLocaleZonedEndOfWeek`, `startOfUnix`,
+  `endOfUnix`, `mapZonedHoursInDay`, `getHoursInZonedDay`
 - **Offset/DST reads**: `getZonedOffset`, `getZonedOffsetAs`,
-  `getTimeZoneOffset`, `parseTimezoneFromZoned`
+  `getTimeZoneOffset`, `parseTimeZoneFromZoned`
+- **Offset-preserving instants**: `toOffsetInstant`, `fromOffsetInstant`
+- **Local-time resolution**: `classifyLocal`, `resolveLocal`
+- **Zone-aware buckets**: `floorToZone`, `bucketRange`,
+  `isValidZoneBucketUnit`
+- **Transport legs and dwell**: `transitTime`, `etaAtZone`, `dwellTime`
+- **Free time and demurrage**: `freeTimeExpiry`, `chargeableDays`,
+  `demurrageClock`
+- **Billing deadlines**: `billingTimeline`
 
 ## References
 
 - [README — Timezone and Calendar examples](README.md)
-- [DST Disambiguation guide](https://gmt-dox.northguild.workers.dev/docs/dst-disambiguation/)
+- [DST Disambiguation guide](https://gmt-dox.northguild.workers.dev/guides/concepts/dst-disambiguation/)

package/dist/internal/advanceBusinessDays.d.ts

@@ -1,2 +0,0 @@
-import type { Temporal } from "@js-temporal/polyfill";
-export declare function advanceBusinessDays(start: Temporal.PlainDate, direction: 1 | -1, target: number): Temporal.PlainDate;

package/dist/internal/advanceBusinessDays.js

@@ -1,15 +0,0 @@
-function getStep(date, direction) {
-    return direction === 1 ? date.add({ days: 1 }) : date.subtract({ days: 1 });
-}
-export function advanceBusinessDays(start, direction, target) {
-    const advance = (date, remaining) => {
-        if (remaining === 0)
-            return date;
-        const next = getStep(date, direction);
-        if (next.dayOfWeek >= 1 && next.dayOfWeek <= 5) {
-            return advance(next, remaining - 1);
-        }
-        return advance(next, remaining);
-    };
-    return advance(start, target);
-}

package/dist/internal/ethiopicFamilyCalendar.d.ts

@@ -1,47 +0,0 @@
-import { Temporal } from "@js-temporal/polyfill";
-export type EthiopicFamilyCalendar = "ethiopic" | "ethiopic-amete-alem" | "coptic";
-export declare function isEthiopicFamilyCalendar(value: string): value is EthiopicFamilyCalendar;
-export interface EthiopicFamilyFields {
-    year: number;
-    era?: "ethioaa" | "ethiopic";
-    eraYear?: number;
-    month: number;
-    day: number;
-}
-/**
- * Derive an Ethiopic-family calendar's native year/month/day (+ era, for "ethiopic") from a
- * Temporal.PlainDate, via Temporal's ICU-independent "ethioaa" calendar rather than the
- * target's own native calendar id. See the module comment above for why.
- */
-export declare function ethiopicFamilyFieldsFromDate(date: Temporal.PlainDate, calendar: EthiopicFamilyCalendar): EthiopicFamilyFields;
-/**
- * Construct a Temporal.PlainDate from an Ethiopic-family calendar's native fields, backed
- * by Temporal's "ethioaa" calendar rather than the target's own native calendar id. Throws
- * on an unrecognized era or a missing required field — callers wrap this in try-catch per
- * GMT's sentinel-return contract. See the module comment above for why.
- */
-export declare function dateFromEthiopicFamilyFields(calendar: EthiopicFamilyCalendar, fields: {
-    year?: number;
-    era?: string;
-    eraYear?: number;
-    month: number;
-    day: number;
-}): Temporal.PlainDate;
-/**
- * Split a Temporal.PlainDate into GMT's calendar-annotated string halves for an Ethiopic-family
- * calendar, mirroring `calendarDateParts`' shape for the rest of the calendar systems but
- * routed entirely through `ethiopicFamilyFieldsFromDate` — see the module comment above.
- *
- * Returned as `{ date, annotation }` rather than one string so the zoned grammar can splice its
- * time/offset between the two halves — see `calendarDateParts`' doc comment for why.
- */
-export declare function ethiopicFamilyDateParts(date: Temporal.PlainDate, calendar: EthiopicFamilyCalendar): {
-    date: string;
-    annotation: string;
-};
-/**
- * Format a Temporal.PlainDate as GMT's calendar-annotated string for an Ethiopic-family
- * calendar, mirroring `formatCalendarDate`'s shape for the rest of the calendar systems but
- * routed entirely through `ethiopicFamilyFieldsFromDate` — see the module comment above.
- */
-export declare function formatEthiopicFamilyDate(date: Temporal.PlainDate, calendar: EthiopicFamilyCalendar): string;

package/dist/internal/ethiopicFamilyCalendar.js

@@ -1,136 +0,0 @@
-import { Temporal } from "@js-temporal/polyfill";
-export function isEthiopicFamilyCalendar(value) {
-    return (value === "ethiopic" ||
-        value === "ethiopic-amete-alem" ||
-        value === "coptic");
-}
-// @js-temporal/polyfill@0.5.1's "ethiopic" and "coptic" calendar ids resolve year/era by
-// formatting the date through Intl.DateTimeFormat and matching the resulting era part
-// against a hardcoded era-name table (its HelperBase.isoToCalendarDate — used because,
-// unlike "ethioaa", these two calendars aren't a fixed year-offset from ISO, so the
-// polyfill can't compute them with pure arithmetic the way it does for "ethioaa"). CLDR's
-// era abbreviation for both calendars changed at the ICU 78 boundary, not at any particular
-// Node major version: ICU < 78 emits an era string the polyfill's table matches; ICU >= 78
-// emits "am", which isn't in that table. This is a real trap for "which Node am I on" bug
-// hunting — ICU 78 ships in *both* Node 22 and Node 24 (confirmed directly against a Node 20 /
-// ICU 78.2 environment during E5, issue #78, where the bug reproduces despite being on Node
-// 20 — an earlier draft of this comment wrongly pinned the boundary to "Node 24"). The result
-// is that *every* read or write of Temporal's "ethiopic"/"coptic" calendar ids throws a
-// RangeError under ICU >= 78 (verified directly — this isn't a hypothetical). "ethioaa" (Ethiopic Amete Alem)
-// has no era at all — a single continuous count from a fixed epoch — so the polyfill
-// resolves it with pure arithmetic and never touches Intl, making it stable across Node
-// versions. This module uses "ethioaa" as a computation carrier for the whole Ethiopic
-// family: month/day are identical across all three (they share one annual 13-month cycle),
-// so only the displayed year (+ era, for "ethiopic") needs converting, which this module
-// does with GMT-owned arithmetic instead of ever constructing or reading a Temporal
-// PlainDate calendared as "ethiopic" or "coptic".
-//
-// The two constants below are ported from the same source file
-// (@js-temporal/polyfill/lib/calendar.ts)'s EthiopicHelper/CopticHelper definitions, not
-// independently derived: the Amete Mihret ("ethiopic") era begins at ethioaa proleptic year
-// 5501 (EthiopicHelper's `anchorEpoch: { year: 5501 }`), and Coptic's own epoch
-// (0284-08-29) falls 5776 ethioaa years after ethioaa's epoch (-005492-07-17) — both
-// verified against the polyfill's own output across a spread of dates spanning multiple
-// centuries and both 13th-month lengths before being hardcoded here.
-const ETHIOPIC_ERA_ANCHOR_ETHIOAA_YEAR = 5501;
-const COPTIC_ETHIOAA_YEAR_OFFSET = 5776;
-/**
- * Derive an Ethiopic-family calendar's native year/month/day (+ era, for "ethiopic") from a
- * Temporal.PlainDate, via Temporal's ICU-independent "ethioaa" calendar rather than the
- * target's own native calendar id. See the module comment above for why.
- */
-export function ethiopicFamilyFieldsFromDate(date, calendar) {
-    const { year: ethioaaYear, month, day } = date.withCalendar("ethioaa");
-    if (calendar === "ethiopic-amete-alem") {
-        return { year: ethioaaYear, month, day };
-    }
-    if (calendar === "coptic") {
-        return { year: ethioaaYear - COPTIC_ETHIOAA_YEAR_OFFSET, month, day };
-    }
-    if (ethioaaYear >= ETHIOPIC_ERA_ANCHOR_ETHIOAA_YEAR) {
-        return {
-            year: ethioaaYear,
-            era: "ethiopic",
-            eraYear: ethioaaYear - (ETHIOPIC_ERA_ANCHOR_ETHIOAA_YEAR - 1),
-            month,
-            day,
-        };
-    }
-    return {
-        year: ethioaaYear,
-        era: "ethioaa",
-        eraYear: ethioaaYear,
-        month,
-        day,
-    };
-}
-/**
- * Construct a Temporal.PlainDate from an Ethiopic-family calendar's native fields, backed
- * by Temporal's "ethioaa" calendar rather than the target's own native calendar id. Throws
- * on an unrecognized era or a missing required field — callers wrap this in try-catch per
- * GMT's sentinel-return contract. See the module comment above for why.
- */
-export function dateFromEthiopicFamilyFields(calendar, fields) {
-    let ethioaaYear;
-    if (calendar === "ethiopic-amete-alem" || calendar === "coptic") {
-        if (fields.year === undefined) {
-            throw new RangeError(`${calendar} requires a year`);
-        }
-        ethioaaYear =
-            calendar === "coptic"
-                ? fields.year + COPTIC_ETHIOAA_YEAR_OFFSET
-                : fields.year;
-    }
-    else if (fields.era === "ethioaa" || fields.era === "ethiopic") {
-        if (fields.eraYear === undefined) {
-            throw new RangeError("ethiopic requires an eraYear");
-        }
-        ethioaaYear =
-            fields.era === "ethioaa"
-                ? fields.eraYear
-                : fields.eraYear + (ETHIOPIC_ERA_ANCHOR_ETHIOAA_YEAR - 1);
-    }
-    else {
-        throw new RangeError(`Unknown ethiopic era: ${fields.era}`);
-    }
-    return Temporal.PlainDate.from({
-        year: ethioaaYear,
-        month: fields.month,
-        day: fields.day,
-        calendar: "ethioaa",
-    }, { overflow: "reject" });
-}
-/**
- * Split a Temporal.PlainDate into GMT's calendar-annotated string halves for an Ethiopic-family
- * calendar, mirroring `calendarDateParts`' shape for the rest of the calendar systems but
- * routed entirely through `ethiopicFamilyFieldsFromDate` — see the module comment above.
- *
- * Returned as `{ date, annotation }` rather than one string so the zoned grammar can splice its
- * time/offset between the two halves — see `calendarDateParts`' doc comment for why.
- */
-export function ethiopicFamilyDateParts(date, calendar) {
-    const fields = ethiopicFamilyFieldsFromDate(date, calendar);
-    const month = String(fields.month).padStart(2, "0");
-    const day = String(fields.day).padStart(2, "0");
-    if (calendar === "ethiopic") {
-        const eraYear = String(fields.eraYear).padStart(4, "0");
-        return {
-            date: `${eraYear}-${month}-${day}`,
-            annotation: `[u-ca=ethiopic;era=${fields.era}]`,
-        };
-    }
-    const year = String(fields.year).padStart(4, "0");
-    return {
-        date: `${year}-${month}-${day}`,
-        annotation: `[u-ca=${calendar}]`,
-    };
-}
-/**
- * Format a Temporal.PlainDate as GMT's calendar-annotated string for an Ethiopic-family
- * calendar, mirroring `formatCalendarDate`'s shape for the rest of the calendar systems but
- * routed entirely through `ethiopicFamilyFieldsFromDate` — see the module comment above.
- */
-export function formatEthiopicFamilyDate(date, calendar) {
-    const { date: datePart, annotation } = ethiopicFamilyDateParts(date, calendar);
-    return `${datePart}${annotation}`;
-}

package/dist/internal/getLocaleMinimalDaysInFirstWeek.d.ts

@@ -1,20 +0,0 @@
-/**
- * Resolve the minimum number of days a week must have in January for that
- * week to count as a locale's week 1, via `Intl.Locale.prototype.weekInfo`.
- *
- * - Returns `null` if `locale` is not a valid BCP 47 tag.
- * - Falls back to `4` (matching ISO 8601's rule — week 1 is the first
- *   week with at least 4 days in January, equivalently the week
- *   containing Jan 4) if `weekInfo` is unavailable on the runtime (older
- *   engines) or unresolvable for the given locale. This mirrors
- *   `getLocaleFirstDayOfWeek`'s fallback-to-ISO-default pattern.
- * - Observed on Node 24 (V8/ICU 78): `weekInfo` omits `minimalDays`
- *   entirely, for every locale, even though Node 20/22 (ICU 77) populate
- *   it — so this fallback engages universally on that runtime rather
- *   than only for locales missing data. `getLocaleWeekYear` and
- *   `getWeeksInLocaleWeekYear` therefore lose locale-specific
- *   minimal-days behavior (silently degrading to the ISO value) on
- *   runtimes where the engine doesn't expose it, which is worth knowing
- *   before treating a Node-version-only test failure as a real bug.
- */
-export declare function getLocaleMinimalDaysInFirstWeek(locale: string): number | null;

package/dist/internal/getLocaleMinimalDaysInFirstWeek.js

@@ -1,31 +0,0 @@
-/**
- * Resolve the minimum number of days a week must have in January for that
- * week to count as a locale's week 1, via `Intl.Locale.prototype.weekInfo`.
- *
- * - Returns `null` if `locale` is not a valid BCP 47 tag.
- * - Falls back to `4` (matching ISO 8601's rule — week 1 is the first
- *   week with at least 4 days in January, equivalently the week
- *   containing Jan 4) if `weekInfo` is unavailable on the runtime (older
- *   engines) or unresolvable for the given locale. This mirrors
- *   `getLocaleFirstDayOfWeek`'s fallback-to-ISO-default pattern.
- * - Observed on Node 24 (V8/ICU 78): `weekInfo` omits `minimalDays`
- *   entirely, for every locale, even though Node 20/22 (ICU 77) populate
- *   it — so this fallback engages universally on that runtime rather
- *   than only for locales missing data. `getLocaleWeekYear` and
- *   `getWeeksInLocaleWeekYear` therefore lose locale-specific
- *   minimal-days behavior (silently degrading to the ISO value) on
- *   runtimes where the engine doesn't expose it, which is worth knowing
- *   before treating a Node-version-only test failure as a real bug.
- */
-export function getLocaleMinimalDaysInFirstWeek(locale) {
-    try {
-        const weekInfo = new Intl.Locale(locale).weekInfo;
-        if (!weekInfo || typeof weekInfo.minimalDays !== "number") {
-            return 4;
-        }
-        return weekInfo.minimalDays;
-    }
-    catch {
-        return null;
-    }
-}

package/dist/internal/resolveUnixTimeZone.d.ts

@@ -1,20 +0,0 @@
-/**
- * Resolve an optional Unix diff timeZone to its default (system timeZone) when unset.
- *
- * @param timeZone optional IANA timeZone
- * @returns the resolved timeZone, or "" if invalid
- * @example resolveUnixTimeZone(undefined) // system timeZone, e.g. "America/New_York"
- * @example resolveUnixTimeZone("Europe/Helsinki") // "Europe/Helsinki"
- * @example resolveUnixTimeZone("not-a-timezone") // ""
- */
-export declare function resolveUnixTimeZone(timeZone?: string): string;
-/**
- * Validate that both Unix epoch values are finite integers.
- *
- * @param value1 first Unix timestamp
- * @param value2 second Unix timestamp
- * @returns true if both values are finite integers
- * @example isValidUnixEpochPair(1704067200000, 1704153600000) // true
- * @example isValidUnixEpochPair(NaN, 1704153600000) // false
- */
-export declare function isValidUnixEpochPair(value1: number, value2: number): boolean;

package/dist/internal/resolveUnixTimeZone.js

@@ -1,30 +0,0 @@
-import { getSystemTimeZone } from "../zoned/get/index.js";
-import { isValidTimeZone } from "../zoned/validate/index.js";
-/**
- * Resolve an optional Unix diff timeZone to its default (system timeZone) when unset.
- *
- * @param timeZone optional IANA timeZone
- * @returns the resolved timeZone, or "" if invalid
- * @example resolveUnixTimeZone(undefined) // system timeZone, e.g. "America/New_York"
- * @example resolveUnixTimeZone("Europe/Helsinki") // "Europe/Helsinki"
- * @example resolveUnixTimeZone("not-a-timezone") // ""
- */
-export function resolveUnixTimeZone(timeZone) {
-    const resolved = timeZone ?? getSystemTimeZone();
-    return resolved && isValidTimeZone(resolved) ? resolved : "";
-}
-/**
- * Validate that both Unix epoch values are finite integers.
- *
- * @param value1 first Unix timestamp
- * @param value2 second Unix timestamp
- * @returns true if both values are finite integers
- * @example isValidUnixEpochPair(1704067200000, 1704153600000) // true
- * @example isValidUnixEpochPair(NaN, 1704153600000) // false
- */
-export function isValidUnixEpochPair(value1, value2) {
-    return (Number.isFinite(value1) &&
-        Number.isInteger(value1) &&
-        Number.isFinite(value2) &&
-        Number.isInteger(value2));
-}

package/dist/unix/calculate/startOrEndOfUnix.d.ts

@@ -1,27 +0,0 @@
-import { Temporal } from "@js-temporal/polyfill";
-import type { Disambiguation, Offset } from "../../types/index.js";
-/**
- * Internal shared implementation for `startOfUnix` / `endOfUnix`.
- *
- * - Converts the epoch to a ZonedDateTime, snaps to the start or end of the
- *   requested unit, then converts back to an epoch number.
- * - Supports every Temporal `DateUnit` and `TimeUnit`.
- * - `epochUnit` controls whether the input/output is interpreted as `"milliseconds"` (default) or `"seconds"`.
- * - `timeZone` defaults to the system time zone via `getSystemTimeZone()`.
- * - `disambiguation` and `offset` are forwarded to Temporal's `.with()` for
- *   DST-gap/overlap boundaries; see `startOfUnix`'s JSDoc for the full
- *   semantics — they behave identically here.
- *
- * @param value Unix epoch number
- * @param unit Temporal.DateUnit | Temporal.TimeUnit to snap to
- * @param options optional: epochUnit, timeZone, weekStartsOn, disambiguation, offset
- * @param isEnd false for start-of-unit, true for end-of-unit
- * @returns Unix epoch number, or null on invalid input
- */
-export declare function startOrEndOfUnix(value: number, unit: Temporal.DateUnit | Temporal.TimeUnit, options: {
-    epochUnit?: "seconds" | "milliseconds";
-    timeZone?: string;
-    weekStartsOn?: "monday" | "sunday";
-    disambiguation?: Disambiguation;
-    offset?: Offset;
-}, isEnd: boolean): number | null;