daymath 0.4.0 → 0.6.0

package/index.js

@@ -1,8 +1,47 @@
 /** daymath — calendar date math (ISO 8601 day). date-fns-shaped. No Date. No time zones. */
-// temporal-polyfill already resolves this: its entry is `globalThis.Temporal ||
-// bundled`, so a runtime with native Temporal gets native. Re-reading
-// globalThis here only duplicated that check and hid where it happens.
-import { Temporal } from 'temporal-polyfill'
+// daymath reaches Temporal through `temporal-polyfill/fns`, the tree-shakable functional API, not
+// through the `Temporal` class. A class is one unit to a bundler, because it cannot prove a method
+// unreachable, so the class API shipped the whole polyfill for the ~20 operations used here.
+// Measured on a three-call program by `npm run size`, shape A: 24,735 B gzip to 16,295 B, −34%.
+// Nothing a caller can observe changes.
+//
+// **`getAny` is required, and `getISO` would be a defect.** `fromString` takes the calendar
+// resolver as a REQUIRED second argument, and it is the set of calendars the bundle admits. With
+// `getISO` the same program answers two ways: the native funcApi keeps `[u-ca=buddhist]` and reads
+// 2569, the shim funcApi drops the annotation and reads 2026. Node 20 and bun are the shim lanes in
+// CI. `getAny` carries the calendar data itself and answers identically on every path, measured
+// with no global, with a BASE polyfill global, with a FULL one, and on native. That costs 4.2 kB
+// and it is what keeps the calendar rule below a MEASUREMENT rather than a build-time list.
+//
+// It also retires the selection block this file used to carry. daymath no longer reads
+// `globalThis.Temporal` at all, so the 0.5.0 defect class — a base polyfill global silently costing
+// three of four calendars, decided by import order — cannot recur here. `fns` picks its own funcApi
+// and `getAny` makes that choice unobservable.
+//
+// `Duration` is deliberately not imported. `add(record, durationRecord)` needs one, but every
+// daymath call moves a single unit, so `addDays` / `addMonths` / `addYears` serve instead and that
+// whole subpath stays out of the bundle.
+import * as PlainDateFns from 'temporal-polyfill/fns/PlainDate'
+import { getAny } from 'temporal-polyfill/fns/Calendar'
+import * as InstantFns from 'temporal-polyfill/fns/Instant'
+import * as ZonedFns from 'temporal-polyfill/fns/ZonedDateTime'
+import * as NowFns from 'temporal-polyfill/fns/Now'
+
+/** The ISO calendar record, resolved once. `isoOf` runs on every two-date export. */
+const ISO_CALENDAR = getAny('iso8601')
+
+/**
+ * Every calendar this runtime names. Read once, lowercased, because BCP-47 keys are
+ * case-insensitive while a `Map` key is not.
+ *
+ * This set is also what bounds the verdict cache below. It is closed and small — 18 ids on Node 26
+ * — so an id the runtime does not name is refused without ever being stored.
+ *
+ * `Intl.supportedValuesOf` is ES2022 and present on every runtime in `engines`.
+ */
+const RUNTIME_CALENDARS = new Set(
+  Intl.supportedValuesOf('calendar').map((id) => id.toLowerCase()),
+)
 
 /**
  * ISO 8601 calendar day string:
@@ -82,7 +121,14 @@ function hasZoneAnnotation(text) {
 const ZONE_LIKE =
   /^(?:(?![Tt]\d)[A-Za-z][A-Za-z0-9_+.-]*(?:\/[A-Za-z0-9_+.-]+)*|[+-]\d{2}(?::?\d{2})?)$/u
 
-/** @typedef {string | Temporal.PlainDate} DayInput */
+// Two different things wear the name PlainDate here, and keeping them apart is the whole type
+// story of this file. `PlainDateRecord` is daymath's INTERNAL value, and the name is the polyfill's
+// own for it. `PlainDate` is the public INPUT type, a real `Temporal.PlainDate` object from any
+// implementation, which callers still pass and `isPlainDate` still recognises by brand. daymath
+// never returns one.
+/** @typedef {import('temporal-polyfill/fns/PlainDate').Record} PlainDateRecord */
+/** @typedef {import('temporal-polyfill').Temporal.PlainDate} PlainDate */
+/** @typedef {string | PlainDate} DayInput */
 /**
  * @typedef {object} Interval
  * @property {DayInput} start
@@ -100,11 +146,9 @@ const ZONE_LIKE =
 /**
  * The bare ISO day inside a string, or `null` if there is not one.
  *
- * An annotation is dropped, not judged: `assertIsoCalendar` owns that rule and
- * runs before both callers, so by here the only calendar left is ISO. Temporal
- * writes `[u-ca=iso8601]` itself for `toString({ calendarName: 'always' })`, and
- * it names the very calendar daymath reads, so refusing a caller's own
- * round-trip would be arbitrary.
+ * An annotation is dropped here, never judged. `supportedCalendar` owns that rule, and the two do
+ * not run in a fixed order: `toPlainDate` judges first, and `day()` calls this first. That is safe
+ * precisely because this function strips the annotation without reading it.
  *
  * One predicate, because `toPlainDate` and `day()` both ask this question. They
  * asked it separately once, and day() alone then refused a string that every
@@ -119,21 +163,139 @@ function bareDay(text) {
 }
 
 /**
- * Refuse a non-ISO calendar, wherever the annotation is attached.
+ * Nine probe dates for the calendar rule below.
+ *
+ * They span 1900 to 2100, they sit in different months, and two pairs straddle a Japanese era
+ * boundary: 1989-01-07/08 is Showa 64 into Heisei 1, and 2019-04-30/05-01 is Heisei 31 into
+ * Reiwa 1. An era change *inside* one ISO year is the case a single probe cannot see, and it is
+ * exactly what separates a year label from a year renumbering.
+ */
+const CALENDAR_PROBES = [
+  '1900-01-01',
+  '1900-07-01',
+  '1989-01-07',
+  '1989-01-08',
+  '2019-04-30',
+  '2019-05-01',
+  '2026-01-31',
+  '2026-12-31',
+  '2100-06-15',
+]
+
+/** @type {Map<string, {offset: number} | {reason: 'unknown' | 'renumbers'}>} */
+const calendarRuleCache = new Map()
+
+/**
+ * Is this a calendar the runtime actually names?
+ *
+ * **This is what bounds `calendarRuleCache`, and it is a memory-exhaustion fix.** The cache keys on
+ * whatever sits between `[u-ca=` and `]`, which is caller input.
+ *
+ * A shape guard was tried first and was only half a fix. It bounded the key LENGTH and not the
+ * entry COUNT, so any BCP-47-shaped string still bought a permanent entry: 800,000 distinct
+ * guard-passing ids retained 76.8 MB, growing linearly and never released. Case made it worse,
+ * because the shape test ignored case while the `Map` key did not, so one name had 256 keys.
+ *
+ * A closed set fixes both at once. `RUNTIME_CALENDARS` holds 18 ids on Node 26, so entries can
+ * never exceed what the runtime has, and a lowercased key collapses the case variants. It also
+ * needs no length cap and no pattern, which removes the last quadratic-regex risk from this file.
+ *
+ * The quiet path was `isValid`, which swallows the `RangeError`, so a loop raised nothing and
+ * logged nothing.
+ * @param {string} lowerId
+ */
+function runtimeKnowsCalendar(lowerId) {
+  return RUNTIME_CALENDARS.has(lowerId)
+}
+
+/**
+ * Measure whether a calendar only relabels the year.
  *
- * Checked on the *string*, before any parse. Implementations disagree past this
- * point: native Temporal builds a `[u-ca=buddhist]` ZonedDateTime and the
- * polyfill refuses to, so parsing first made the error depend on the runtime.
+ * **This is a method, not a list.** Nothing here names a calendar, so a calendar CLDR adds later
+ * is admitted or refused by the same measurement, with no code change. Today it admits
+ * `buddhist` (+543), `roc` (−1911), `japanese` (0) and `gregory` (0), and refuses the other
+ * eleven the runtime knows.
+ *
+ * Two conditions, both required on every probe:
+ *
+ * 1. **Month and day equal the ISO fields.** A month-count test would be wrong: `hebrew` is
+ *    lunisolar, so `monthsInYear` is 13 in 2024, 12 in 2025 and 13 in 2027. Comparing the fields
+ *    is correct in every year.
+ * 2. **The year offset is constant.** `japanese` and `roc` pass condition 1, and Temporal reports
+ *    a continuous year for both, so both are pure labels — `roc` 1900 is −11, not "12 before".
+ *    Reading the year from `Intl` instead would fail here, because `Intl` reports the *era* year:
+ *    Reiwa 8 and B.R.O.C. 12. Temporal is the reference, so Temporal is what this asks.
+ *
+ * The verdict is cached per calendar. It cannot change while the process runs.
+ * @param {string} calendar
+ */
+function calendarRule(calendar) {
+  const cached = calendarRuleCache.get(calendar)
+  if (cached !== undefined) return cached
+  /** @type {{offset: number} | {reason: 'unknown' | 'renumbers'}} */
+  let verdict = { reason: 'renumbers' }
+  try {
+    const offsets = new Set()
+    // `getAny(calendar)` throws for an id the polyfill cannot build, which is the `unknown` case
+    // below. It is resolved once rather than per probe.
+    const calendarRecord = getAny(calendar)
+    for (const probe of CALENDAR_PROBES) {
+      const iso = PlainDateFns.fromString(probe, getAny)
+      const dated = PlainDateFns.withCalendar(iso, calendarRecord)
+      if (dated.month !== iso.month || dated.day !== iso.day) {
+        offsets.clear()
+        break
+      }
+      offsets.add(dated.year - iso.year)
+    }
+    // The offset is the discriminant — `'offset' in verdict` is what accepts — and the number
+    // itself is kept unread on purpose, so a debugger shows WHY a calendar passed.
+    if (offsets.size === 1) verdict = { offset: [...offsets][0] }
+  } catch {
+    // The runtime cannot build this calendar at all, which is a different message for the caller.
+    verdict = { reason: 'unknown' }
+  }
+  calendarRuleCache.set(calendar, verdict)
+  return verdict
+}
+
+/**
+ * Accept a calendar that only relabels the year, and refuse one that renumbers.
+ *
+ * Checked on the *string*, before any parse, so the outcome cannot depend on where the annotation
+ * sits. Returns the calendar for `toPlainDate` to carry, or `undefined` for plain ISO.
+ *
+ * `[u-ca=iso8601]` returns `undefined` rather than carrying: Temporal writes it itself for
+ * `toString({ calendarName: 'always' })`, and daymath already answers in it, so there is nothing
+ * to relabel.
  * @param {string} text
  * @param {string} label
+ * @returns {string | undefined}
  */
-function assertIsoCalendar(text, label) {
+function supportedCalendar(text, label) {
   const annotated = calendarAnnotation(text)
-  if (annotated && annotated.calendar.toLowerCase() !== 'iso8601') {
-    throw new RangeError(
-      `daymath: ${label} must use the ISO 8601 calendar, not ${JSON.stringify(annotated.calendar)} (convert with withCalendar('iso8601'))`,
-    )
-  }
+  // A bare `return` rather than `return undefined`: oxlint's no-useless-undefined forbids the
+  // explicit spelling, and "nothing to carry" is what both of these mean.
+  if (annotated === null) return
+  const { calendar } = annotated
+  // Lowercased once. BCP-47 keys are case-insensitive, and this is also the cache key, so the case
+  // variants of one name must collapse to one entry rather than 256.
+  const lowerId = calendar.toLowerCase()
+  if (lowerId === 'iso8601') return
+  // Membership FIRST, so an id the runtime does not name is never stored. See runtimeKnowsCalendar.
+  // One throw, not two: an unknown id and a renumbering one differ only in the reason.
+  const verdict = runtimeKnowsCalendar(lowerId)
+    ? calendarRule(lowerId)
+    : /** @type {const} */ ({ reason: 'unknown' })
+  if ('offset' in verdict) return calendar
+  const why =
+    verdict.reason === 'unknown'
+      ? 'is not a calendar this runtime knows'
+      : 'renumbers months or days, so daymath cannot answer a day in it'
+  // The id is sliced because it is caller input, so a megabyte in cannot become a megabyte of error.
+  throw new RangeError(
+    `daymath: ${label} calendar ${JSON.stringify(calendar.slice(0, 40))} ${why} (convert with withCalendar('iso8601'))`,
+  )
 }
 
 /**
@@ -142,7 +304,7 @@ function assertIsoCalendar(text, label) {
  * `instanceof` recognises only one of those. Every Temporal puts this tag on
  * `PlainDate.prototype` as a non-writable property, so it is the portable brand.
  * @param {unknown} value
- * @returns {value is Temporal.PlainDate} a predicate, so callers narrow
+ * @returns {value is PlainDate} a predicate, so callers narrow
  */
 function isPlainDate(value) {
   return Object.prototype.toString.call(value) === '[object Temporal.PlainDate]'
@@ -154,21 +316,12 @@ function isPlainDate(value) {
  * A PlainDate becomes its ISO day string first, so every input reaches one
  * validation path and daymath owns the resulting instance.
  *
- * A non-ISO calendar is refused rather than reinterpreted. `toString()` writes
- * the ISO date then an optional `[u-ca=…]`, so the *day* would survive — but
- * the field numbers would not. Thai Buddhist years run 543 ahead, so
- * `2026-01-31[u-ca=buddhist]` is year 2569, and `getYear` would answer `2026`
- * where the caller's own object says `2569`. A string carrying the annotation is
- * refused for the same reason, and the error names both the calendar it found
- * and the way through, `withCalendar('iso8601')`.
- *
- * `[u-ca=iso8601]` is the exception: it is accepted and dropped. Temporal writes
- * it itself for `toString({ calendarName: 'always' })`, and it names the very
- * calendar daymath reads, so refusing a caller's own round-trip would be
- * arbitrary.
+ * A calendar annotation is judged by `supportedCalendar` and then CARRIED, so `getYear` answers
+ * the caller's own number: `2026-01-31[u-ca=buddhist]` reads 2569, not 2026. The rule and the
+ * reasons live on `supportedCalendar`; this function only applies the verdict.
  * @param {unknown} value
  * @param {string} label
- * @returns {Temporal.PlainDate}
+ * @returns {PlainDateRecord}
  */
 function toPlainDate(value, label = 'date') {
   if (value instanceof Date) {
@@ -184,7 +337,7 @@ function toPlainDate(value, label = 'date') {
     )
   }
   // Before the shape check: an annotated day is well formed, not malformed.
-  assertIsoCalendar(text, label)
+  const calendar = supportedCalendar(text, label)
   const bare = bareDay(text)
   if (bare === null) {
     throw new RangeError(
@@ -192,7 +345,15 @@ function toPlainDate(value, label = 'date') {
     )
   }
   try {
-    return Temporal.PlainDate.from(bare)
+    // The bare day is parsed with the ISO resolver's own entry point. `getAny` is passed as the
+    // resolver rather than called, because `fromString` calls it with whatever the string names,
+    // and a bare day names nothing.
+    const plain = PlainDateFns.fromString(bare, getAny)
+    // The annotation rides along, so getYear answers 2569 for a Buddhist day and every
+    // returned string keeps the calendar the caller named.
+    return calendar === undefined
+      ? plain
+      : PlainDateFns.withCalendar(plain, getAny(calendar))
   } catch (err) {
     throw new RangeError(`daymath: invalid ${label} ${JSON.stringify(text)}`, {
       cause: err,
@@ -200,9 +361,25 @@ function toPlainDate(value, label = 'date') {
   }
 }
 
-/** @param {Temporal.PlainDate} plain @returns {string} */
+/**
+ * The same day in ISO, for measurement only.
+ *
+ * Temporal refuses `since` and `until` across two calendars with `Mismatched calendars`, and its
+ * `equals` compares the calendar as well as the day. Neither matters to a day count: a day is the
+ * same day whatever the year is labelled, so daymath normalises and answers. Only the exports that
+ * *read* or *write* a field honour the label.
+ * @param {PlainDateRecord} plain
+ * @returns {PlainDateRecord}
+ */
+function isoOf(plain) {
+  return plain.calendarId === 'iso8601'
+    ? plain
+    : PlainDateFns.withCalendar(plain, ISO_CALENDAR)
+}
+
+/** @param {PlainDateRecord} plain @returns {string} */
 function toDayString(plain) {
-  return plain.toString()
+  return PlainDateFns.toString(plain)
 }
 
 /** @param {unknown} n @param {string} label */
@@ -243,14 +420,29 @@ function guardRange(label, op) {
 /**
  * Shared body for every add/sub function. Each caller passes its own name, so
  * the message never reports a function the caller did not call.
+ *
+ * The unit is a parameter rather than a duration object on purpose. `PlainDateFns.add` would need a
+ * `DurationRecord`, which means importing `fns/Duration`, and every daymath caller moves exactly
+ * one unit. `addDays` / `addMonths` / `addYears` take a plain number and keep that subpath out of
+ * the bundle. Subtraction is a negative amount, exactly as it was when this passed `-amount`.
+ *
+ * `addMonths` and `addYears` clamp by default, which is daymath's one overflow rule and the same
+ * behaviour the class API gave: 31 January plus one month is 28 February.
  * @param {DayInput} date
- * @param {{ days?: number, months?: number, years?: number }} delta
+ * @param {'days'|'months'|'years'} unit
+ * @param {number} amount
  * @param {string} label
  * @returns {string}
  */
-function addDuration(date, delta, label) {
+function addDuration(date, unit, amount, label) {
   const d = toPlainDate(date)
-  return guardRange(label, () => toDayString(d.add(delta)))
+  const move =
+    unit === 'days'
+      ? PlainDateFns.addDays
+      : unit === 'months'
+        ? PlainDateFns.addMonths
+        : PlainDateFns.addYears
+  return guardRange(label, () => toDayString(move(d, amount)))
 }
 
 /** @param {unknown} dates */
@@ -274,7 +466,7 @@ function weekStartsOnFrom(options) {
 
 /**
  * @param {unknown} interval
- * @returns {{ start: Temporal.PlainDate, end: Temporal.PlainDate }}
+ * @returns {{ start: PlainDateRecord, end: PlainDateRecord }}
  */
 function toInterval(interval) {
   // `typeof x === 'object'` alone let a Date, an array or a PlainDate through,
@@ -315,6 +507,16 @@ function toInterval(interval) {
  * - a string carrying a `[Zone]` annotation, which names its own zone, so it
  *   answers its own civil day and the `tz` default never applies
  *
+ * **day() is the normaliser, and that is the one rule to hold: a moment
+ * converts to a plain ISO day, and so does a day.** A `[u-ca=…]` annotation is
+ * accepted wherever the other 68 exports accept it, and then dropped from the
+ * result. Those exports carry it, because the caller asked for that numbering;
+ * day() exists to hand back the canonical form. It cannot do both, because an
+ * `Instant` has no fields for a calendar to renumber, so an annotation on
+ * `'…T20:00:00Z[u-ca=buddhist]'` is inert and that path has nothing to carry.
+ * Carrying only on the `[Zone]` path would make the same annotation behave two
+ * ways in one function.
+ *
  * `'11/12/2026'` is refused. Nobody can tell November from December in it.
  * `'2026-08-08T12:00'` is refused too: no offset and no zone, so daymath would
  * have to pick one, and it will not pick on the caller's behalf. Name the zone
@@ -335,7 +537,10 @@ function toInterval(interval) {
  *
  * @param {Date | number | DayInput | null} [moment] instant, epoch ms, day, or a zone
  * @param {string} [tz] IANA time zone id, e.g. `'utc'`, `'Asia/Tokyo'`
- * @returns {string} `YYYY-MM-DD`
+ * @returns {string} a plain ISO day. `YYYY-MM-DD`, or expanded `±YYYYYY-MM-DD` outside years
+ *   0000-9999 — the annotation said `YYYY-MM-DD` alone, which was already wrong for
+ *   `day('+010000-01-01')`. **Never carries `[u-ca=…]`.** day() is the normaliser, so a calendar
+ *   annotation is accepted on input and dropped from the result. Every other export carries it.
  * @throws {TypeError} If `moment` is not one of the accepted shapes
  * @throws {RangeError} On an Invalid Date, a non-finite number, or an unknown zone
  * @example day()                              // '2026-08-08'  now, UTC
@@ -355,9 +560,9 @@ export function day(moment, tz) {
   const isMoment = isDay || moment instanceof Date || typeof moment === 'number'
 
   let zone = tz
-  /** @type {Temporal.Instant | undefined} */
+  /** @type {import('temporal-polyfill/fns/Instant').Record | undefined} */
   let instant
-  /** @type {Temporal.ZonedDateTime | undefined} */
+  /** @type {import('temporal-polyfill/fns/ZonedDateTime').Record | undefined} */
   let zoned
   if (!isMoment && moment !== undefined && moment !== null) {
     if (typeof moment !== 'string') {
@@ -376,20 +581,20 @@ export function day(moment, tz) {
     // `'…[Asia/Tokoy]'` is a typo. Falling back to the instant would answer a
     // UTC day for both, silently, which is the defect this branch exists to fix.
     if (hasZoneAnnotation(moment)) {
-      // A calendar is refused only where it is applied. With a zone bracket it
-      // is: the fields get renumbered, and `toPlainDate()` carries the
-      // annotation into daymath's own output. Refused on the string, before the
-      // parse, because native Temporal builds a `[u-ca=buddhist]` ZonedDateTime
-      // and the polyfill refuses to — judging after the parse would make the
-      // message depend on the runtime.
-      assertIsoCalendar(moment, 'date')
+      // A calendar is judged only where it is applied. With a zone bracket it is: the fields get
+      // renumbered, and `toPlainDate()` carries the annotation into daymath's own output. Judged
+      // on the string, before the parse, so the message cannot depend on the runtime. A calendar
+      // that only relabels the year passes here, exactly as it does through toPlainDate.
+      supportedCalendar(moment, 'date')
       if (tz !== undefined && tz !== null) {
         throw new TypeError(
           `daymath: day() got two time zones, ${JSON.stringify(moment)} and ${JSON.stringify(tz)}`,
         )
       }
       try {
-        zoned = Temporal.ZonedDateTime.from(moment)
+        // `getAny` again, for the same reason it is used everywhere else: a zoned string can carry
+        // a calendar annotation, and the shim funcApi would drop it under `getISO`.
+        zoned = ZonedFns.fromString(moment, getAny)
       } catch (err) {
         throw new RangeError(
           `daymath: day() could not read ${JSON.stringify(moment)} in the time zone it names`,
@@ -405,7 +610,7 @@ export function day(moment, tz) {
         // year, month or day for a calendar to renumber, and without a zone
         // bracket Temporal will not build anything that does. Refusing it would
         // reject a right answer for a reason that cannot apply.
-        instant = Temporal.Instant.from(moment)
+        instant = InstantFns.fromString(moment)
       } catch {
         // Not a moment, so the string must be a zone — decided by shape, before
         // Temporal sees it. Temporal's zone grammar also accepts a whole
@@ -447,10 +652,10 @@ export function day(moment, tz) {
   // whatever the moment is. A caller mapping rows that are sometimes a Date and
   // sometimes a day string would otherwise see the typo only on some rows.
   //
-  // `ZonedDateTime.from` accepts exactly what `Temporal.Now` accepts and reads
+  // `ZonedDateTime.fromFields` accepts exactly the zone ids `Now` accepts and reads
   // no clock, so a day input stays a pure function.
   try {
-    Temporal.ZonedDateTime.from({ timeZone: zone, year: 1970, month: 1, day: 1 })
+    ZonedFns.fromFields({ timeZone: zone, year: 1970, month: 1, day: 1 })
   } catch (err) {
     throw new RangeError(
       `daymath: day() got an unknown time zone ${JSON.stringify(zone)}`,
@@ -460,27 +665,39 @@ export function day(moment, tz) {
 
   // A day carries no time, so a zone has nothing to shift. Applying one would
   // invent a moment the caller never gave.
-  if (isDay) return toDayString(toPlainDate(moment))
+  //
+  // `isoOf` is what makes day() the normaliser. Every other export carries a
+  // `[u-ca=…]` annotation through, because the caller asked for that numbering.
+  // day() is the door: something that is not a plain ISO day goes in, and a
+  // plain ISO day comes out. Carrying it here also could not be made
+  // consistent, because an `Instant` has no fields for a calendar to renumber,
+  // so that path has nothing to carry and would answer bare ISO regardless.
+  if (isDay) return toDayString(isoOf(toPlainDate(moment)))
 
   // The string named its own zone, so that zone decides the day, not the
   // default. This is the one path where `zone` is deliberately not consulted.
   //
-  // The result still goes through `toPlainDate`. A ZonedDateTime keeps a
-  // `[u-ca=…]` annotation, and `PlainDate.toString()` writes it back out, so
-  // returning directly emitted `'2026-08-08[u-ca=buddhist]'` — a value daymath
-  // itself refuses. Every path adjudicates the calendar in one place or none.
+  // The result still goes through `toPlainDate`, so the calendar is adjudicated
+  // in one place, and then through `isoOf` for the reason above.
   if (zoned !== undefined) {
-    const plain = guardRange('day', () => zoned.toPlainDate())
-    return toDayString(toPlainDate(plain))
+    // `toPlainDate` is re-entered with the STRING, not the record, because daymath's own funnel
+    // takes a day string or a `Temporal.PlainDate`, and an fns record is neither. `PlainDateFns.toString`
+    // writes the same day the class API's `toPlainDate()` produced, annotation and all.
+    const plain = guardRange('day', () =>
+      PlainDateFns.toString(ZonedFns.toPlainDate(zoned)),
+    )
+    return toDayString(isoOf(toPlainDate(plain)))
   }
 
   if (instant !== undefined) {
     return guardRange('day', () =>
-      instant.toZonedDateTimeISO(zone).toPlainDate().toString(),
+      PlainDateFns.toString(
+        ZonedFns.toPlainDate(InstantFns.toZonedDateTimeISO(instant, zone)),
+      ),
     )
   }
 
-  if (!isMoment) return Temporal.Now.plainDateISO(zone).toString()
+  if (!isMoment) return PlainDateFns.toString(NowFns.plainDateISO(zone))
 
   // Truncate, because `new Date(n)` truncates, and the contract here is that a
   // number reads exactly as it does. Verified equal on positive and negative
@@ -492,10 +709,11 @@ export function day(moment, tz) {
       ? Math.trunc(moment)
       : /** @type {Date} */ (moment).getTime()
   return guardRange('day', () =>
-    Temporal.Instant.fromEpochMilliseconds(epochMs)
-      .toZonedDateTimeISO(zone)
-      .toPlainDate()
-      .toString(),
+    PlainDateFns.toString(
+      ZonedFns.toPlainDate(
+        InstantFns.toZonedDateTimeISO(InstantFns.fromEpochMilliseconds(epochMs), zone),
+      ),
+    ),
   )
 }
 
@@ -555,7 +773,7 @@ export function format(date, pattern = 'yyyy-MM-dd') {
  */
 export function addDays(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return addDuration(date, { days: amount }, 'addDays')
+  return addDuration(date, 'days', amount, 'addDays')
 }
 
 /**
@@ -565,7 +783,7 @@ export function addDays(date, amount) {
  */
 export function subDays(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return addDuration(date, { days: -amount }, 'subDays')
+  return addDuration(date, 'days', -amount, 'subDays')
 }
 
 /**
@@ -577,7 +795,7 @@ export function addWeeks(date, amount) {
   assertFiniteNumber(amount, 'amount')
   const days = amount * 7 // re-check: 7x a finite amount can still reach Infinity
   assertFiniteNumber(days, 'amount')
-  return addDuration(date, { days }, 'addWeeks')
+  return addDuration(date, 'days', days, 'addWeeks')
 }
 
 /**
@@ -589,7 +807,7 @@ export function subWeeks(date, amount) {
   assertFiniteNumber(amount, 'amount')
   const days = -amount * 7
   assertFiniteNumber(days, 'amount')
-  return addDuration(date, { days }, 'subWeeks')
+  return addDuration(date, 'days', days, 'subWeeks')
 }
 
 /**
@@ -600,7 +818,7 @@ export function subWeeks(date, amount) {
  */
 export function addMonths(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return addDuration(date, { months: amount }, 'addMonths')
+  return addDuration(date, 'months', amount, 'addMonths')
 }
 
 /**
@@ -610,7 +828,7 @@ export function addMonths(date, amount) {
  */
 export function subMonths(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return addDuration(date, { months: -amount }, 'subMonths')
+  return addDuration(date, 'months', -amount, 'subMonths')
 }
 
 /**
@@ -620,7 +838,7 @@ export function subMonths(date, amount) {
  */
 export function addYears(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return addDuration(date, { years: amount }, 'addYears')
+  return addDuration(date, 'years', amount, 'addYears')
 }
 
 /**
@@ -630,7 +848,7 @@ export function addYears(date, amount) {
  */
 export function subYears(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return addDuration(date, { years: -amount }, 'subYears')
+  return addDuration(date, 'years', -amount, 'subYears')
 }
 
 /**
@@ -642,7 +860,7 @@ export function addQuarters(date, amount) {
   assertFiniteNumber(amount, 'amount')
   const months = amount * 3
   assertFiniteNumber(months, 'amount')
-  return addDuration(date, { months }, 'addQuarters')
+  return addDuration(date, 'months', months, 'addQuarters')
 }
 
 /**
@@ -654,7 +872,7 @@ export function subQuarters(date, amount) {
   assertFiniteNumber(amount, 'amount')
   const months = -amount * 3
   assertFiniteNumber(months, 'amount')
-  return addDuration(date, { months }, 'subQuarters')
+  return addDuration(date, 'months', months, 'subQuarters')
 }
 
 // ─── getters / setters (date-fns / Date month & weekday indexing) ─
@@ -687,27 +905,51 @@ export function getDate(date) {
  * @returns {number}
  */
 export function getDay(date) {
-  return toPlainDate(date).dayOfWeek
+  return PlainDateFns.dayOfWeek(toPlainDate(date))
 }
 
 /** @param {DayInput} date @returns {number} */
 export function getDayOfYear(date) {
-  return toPlainDate(date).dayOfYear
+  return PlainDateFns.dayOfYear(toPlainDate(date))
 }
 
 /** @param {DayInput} date @returns {number} */
 export function getDaysInMonth(date) {
-  return toPlainDate(date).daysInMonth
+  return PlainDateFns.daysInMonth(toPlainDate(date))
+}
+
+/**
+ * Quarter of a record daymath already owns.
+ *
+ * The class API needed no such helper, because a `Temporal.PlainDate` passed back into
+ * `toPlainDate` was recognised by `isPlainDate` and survived the round trip. An fns record is not
+ * a `Temporal.PlainDate` and is correctly refused, so every internal caller now works on the
+ * record. That was always the honest shape: re-validating a value daymath just built is waste.
+ * @param {PlainDateRecord} plain
+ * @returns {number}
+ */
+function quarterOf(plain) {
+  return Math.ceil(plain.month / 3)
+}
+
+/**
+ * Calendar month index between two records already normalised to ISO.
+ * @param {PlainDateRecord} left
+ * @param {PlainDateRecord} right
+ * @returns {number}
+ */
+function calendarMonthsBetween(left, right) {
+  return (left.year - right.year) * 12 + (left.month - right.month)
 }
 
 /** Quarter 1…4. @param {DayInput} date @returns {number} */
 export function getQuarter(date) {
-  return Math.ceil(toPlainDate(date).month / 3)
+  return quarterOf(toPlainDate(date))
 }
 
 /** @param {DayInput} date @returns {boolean} */
 export function isLeapYear(date) {
-  return toPlainDate(date).inLeapYear
+  return PlainDateFns.inLeapYear(toPlainDate(date))
 }
 
 /**
@@ -718,7 +960,7 @@ export function isLeapYear(date) {
 export function setYear(date, year) {
   assertFiniteNumber(year, 'year')
   const d = toPlainDate(date)
-  return guardRange('setYear', () => toDayString(d.with({ year })))
+  return guardRange('setYear', () => toDayString(PlainDateFns.withFields(d, { year })))
 }
 
 /**
@@ -732,7 +974,7 @@ export function setMonth(date, month) {
     throw new RangeError('daymath: month must be 1…12 (1=January)')
   }
   const d = toPlainDate(date)
-  return guardRange('setMonth', () => toDayString(d.with({ month })))
+  return guardRange('setMonth', () => toDayString(PlainDateFns.withFields(d, { month })))
 }
 
 /**
@@ -744,7 +986,9 @@ export function setMonth(date, month) {
 export function setDate(date, dayOfMonth) {
   assertFiniteNumber(dayOfMonth, 'day')
   const d = toPlainDate(date)
-  return guardRange('setDate', () => toDayString(d.with({ day: dayOfMonth })))
+  return guardRange('setDate', () =>
+    toDayString(PlainDateFns.withFields(d, { day: dayOfMonth })),
+  )
 }
 
 // ─── start / end of unit ───────────────────────────────────────────
@@ -756,41 +1000,53 @@ export function setDate(date, dayOfMonth) {
 /** @param {DayInput} date @returns {string} */
 export function startOfMonth(date) {
   const d = toPlainDate(date)
-  return guardRange('startOfMonth', () => toDayString(d.with({ day: 1 })))
+  return guardRange('startOfMonth', () =>
+    toDayString(PlainDateFns.withFields(d, { day: 1 })),
+  )
 }
 
 /** @param {DayInput} date @returns {string} */
 export function endOfMonth(date) {
   const d = toPlainDate(date)
-  return guardRange('endOfMonth', () => toDayString(d.with({ day: d.daysInMonth })))
+  return guardRange('endOfMonth', () =>
+    toDayString(PlainDateFns.withFields(d, { day: PlainDateFns.daysInMonth(d) })),
+  )
 }
 
 /** @param {DayInput} date @returns {string} */
 export function startOfYear(date) {
   const d = toPlainDate(date)
-  return guardRange('startOfYear', () => toDayString(d.with({ month: 1, day: 1 })))
+  return guardRange('startOfYear', () =>
+    toDayString(PlainDateFns.withFields(d, { month: 1, day: 1 })),
+  )
 }
 
 /** @param {DayInput} date @returns {string} */
 export function endOfYear(date) {
   const d = toPlainDate(date)
-  return guardRange('endOfYear', () => toDayString(d.with({ month: 12, day: 31 })))
+  return guardRange('endOfYear', () =>
+    toDayString(PlainDateFns.withFields(d, { month: 12, day: 31 })),
+  )
 }
 
 /** @param {DayInput} date @returns {string} */
 export function startOfQuarter(date) {
   const d = toPlainDate(date)
-  const month = (getQuarter(d) - 1) * 3 + 1
-  return guardRange('startOfQuarter', () => toDayString(d.with({ month, day: 1 })))
+  const month = (quarterOf(d) - 1) * 3 + 1
+  return guardRange('startOfQuarter', () =>
+    toDayString(PlainDateFns.withFields(d, { month, day: 1 })),
+  )
 }
 
 /** @param {DayInput} date @returns {string} */
 export function endOfQuarter(date) {
   const d = toPlainDate(date)
-  const month = getQuarter(d) * 3
+  const month = quarterOf(d) * 3
   return guardRange('endOfQuarter', () => {
-    const mid = d.with({ month, day: 1 })
-    return toDayString(mid.with({ day: mid.daysInMonth }))
+    const mid = PlainDateFns.withFields(d, { month, day: 1 })
+    return toDayString(
+      PlainDateFns.withFields(mid, { day: PlainDateFns.daysInMonth(mid) }),
+    )
   })
 }
 
@@ -802,19 +1058,19 @@ export function endOfQuarter(date) {
 export function startOfWeek(date, options) {
   const d = toPlainDate(date)
   const diff = daysIntoWeek(d, options)
-  return guardRange('startOfWeek', () => toDayString(d.subtract({ days: diff })))
+  return guardRange('startOfWeek', () => toDayString(PlainDateFns.subtractDays(d, diff)))
 }
 
 /**
  * How far the day sits past the start of its week.
- * @param {Temporal.PlainDate} d
+ * @param {PlainDateRecord} d
  * @param {WeekOptions} [options]
  * @returns {number}
  */
 function daysIntoWeek(d, options) {
   const weekStartsOn = weekStartsOnFrom(options)
   // mod 7 makes weekStartsOn 0 and 7 identical, so both spellings of Sunday work
-  return (d.dayOfWeek - weekStartsOn + 7) % 7
+  return (PlainDateFns.dayOfWeek(d) - weekStartsOn + 7) % 7
 }
 
 /**
@@ -827,7 +1083,7 @@ export function endOfWeek(date, options) {
   const diff = daysIntoWeek(d, options)
   // one guard for the whole walk, so a failure at either end says endOfWeek
   return guardRange('endOfWeek', () =>
-    toDayString(d.subtract({ days: diff }).add({ days: 6 })),
+    toDayString(PlainDateFns.addDays(PlainDateFns.subtractDays(d, diff), 6)),
   )
 }
 
@@ -842,7 +1098,26 @@ export function endOfWeek(date, options) {
 export function differenceInDays(dateLeft, dateRight) {
   const left = toPlainDate(dateLeft, 'dateLeft')
   const right = toPlainDate(dateRight, 'dateRight')
-  return left.since(right, { largestUnit: 'day' }).days
+  // `diff` IS Temporal: it is the `fns` spelling of `PlainDate.prototype.until`, which is what
+  // `since` was here with the operands the other way round. The choice below is between two
+  // Temporal functions, not between Temporal and anything else.
+  //
+  // `diff`, NOT `diffDays`, and the reason is the one day where the two Temporal ranges disagree.
+  //
+  // `PlainDate`'s minimum is `-271821-04-19`, one day BELOW `PlainDateTime`'s, because midnight on
+  // that day is out of bounds while the same day is reachable in a positive-offset zone. The
+  // maximum is not widened, so the asymmetry is real and only the low edge has it. Measured:
+  // `PlainDate.from('-271821-04-19').toPlainDateTime()` throws `Out-of-bounds date`, and
+  // `-271821-04-20` does not.
+  //
+  // `diffDays` converts to a `PlainDateTime` and inherits that, so it throws on exactly one
+  // operand. `diff` with `largestUnit: 'day'` does not, and answers what the class API's `since`
+  // answered. The cross-runtime baseline caught it, because no test in the suite covers a pair
+  // that wide; `differenceInDays` and `differenceInWeeks` both went red.
+  //
+  // The argument order is `(record, other)` for `other − record`, so the operands are swapped to
+  // keep daymath's date-fns order of `dateLeft − dateRight`.
+  return PlainDateFns.diff(isoOf(right), isoOf(left), { largestUnit: 'day' }).days
 }
 
 /**
@@ -871,18 +1146,22 @@ export function differenceInWeeks(dateLeft, dateRight) {
  * @returns {number}
  */
 export function differenceInMonths(dateLeft, dateRight) {
-  const left = toPlainDate(dateLeft, 'dateLeft')
-  const right = toPlainDate(dateRight, 'dateRight')
-  const sign = Temporal.PlainDate.compare(left, right)
+  // `isoOf` on both, like differenceInDays. Without it this function read TWO coordinate systems
+  // at once: the sign came from `compare`, which ignores the calendar, and the magnitude came from
+  // `differenceInCalendarMonths`, which does not. A mixed pair then measured 6,513 months for a
+  // 29-day gap, and two days 543 ISO years apart measured 0.
+  const left = isoOf(toPlainDate(dateLeft, 'dateLeft'))
+  const right = isoOf(toPlainDate(dateRight, 'dateRight'))
+  const sign = PlainDateFns.compare(left, right)
   if (sign === 0) return 0
-  const diff = Math.abs(differenceInCalendarMonths(left, right))
+  const diff = Math.abs(calendarMonthsBetween(left, right))
   if (diff < 1) return 0
   const [earlier, later] = sign > 0 ? [right, left] : [left, right]
   // Where `earlier` lands after `diff` months: same year-month as `later` by
   // construction, on `earlier`'s day clamped to that month's length. Compared
   // as day numbers rather than built as a date, because the landing can sit
   // past the maximum PlainDate even when both operands are inside the range.
-  const landingDay = Math.min(earlier.day, later.daysInMonth)
+  const landingDay = Math.min(earlier.day, PlainDateFns.daysInMonth(later))
   const isLastMonthNotFull = landingDay > later.day
   return sign * (diff - +isLastMonthNotFull) || 0
 }
@@ -894,9 +1173,9 @@ export function differenceInMonths(dateLeft, dateRight) {
  * @returns {number}
  */
 export function differenceInCalendarMonths(dateLeft, dateRight) {
-  const left = toPlainDate(dateLeft, 'dateLeft')
-  const right = toPlainDate(dateRight, 'dateRight')
-  return (left.year - right.year) * 12 + (left.month - right.month)
+  const left = isoOf(toPlainDate(dateLeft, 'dateLeft'))
+  const right = isoOf(toPlainDate(dateRight, 'dateRight'))
+  return calendarMonthsBetween(left, right)
 }
 
 /**
@@ -910,9 +1189,10 @@ export function differenceInCalendarMonths(dateLeft, dateRight) {
  * @returns {number}
  */
 export function differenceInYears(dateLeft, dateRight) {
-  const left = toPlainDate(dateLeft, 'dateLeft')
-  const right = toPlainDate(dateRight, 'dateRight')
-  const sign = Temporal.PlainDate.compare(left, right)
+  // `isoOf` on both: a measurement, so it ignores the year LABEL. See differenceInMonths.
+  const left = isoOf(toPlainDate(dateLeft, 'dateLeft'))
+  const right = isoOf(toPlainDate(dateRight, 'dateRight'))
+  const sign = PlainDateFns.compare(left, right)
   if (sign === 0) return 0
   const diff = Math.abs(left.year - right.year)
   if (diff < 1) return 0
@@ -923,7 +1203,9 @@ export function differenceInYears(dateLeft, dateRight) {
   // Compared field by field rather than built as a date, because the landing
   // can sit past the maximum PlainDate even with both operands inside the range.
   const landingDay =
-    earlier.month === 2 && earlier.day === 29 && !later.inLeapYear ? 28 : earlier.day
+    earlier.month === 2 && earlier.day === 29 && !PlainDateFns.inLeapYear(later)
+      ? 28
+      : earlier.day
   const isLastYearNotFull =
     earlier.month > later.month ||
     (earlier.month === later.month && landingDay > later.day)
@@ -937,7 +1219,12 @@ export function differenceInYears(dateLeft, dateRight) {
  * @returns {number}
  */
 export function differenceInCalendarYears(dateLeft, dateRight) {
-  return getYear(dateLeft) - getYear(dateRight)
+  // NOT getYear: that is a field read and honours the label, so a mixed pair subtracted two
+  // different year spaces and answered 0 for days 543 ISO years apart.
+  return (
+    isoOf(toPlainDate(dateLeft, 'dateLeft')).year -
+    isoOf(toPlainDate(dateRight, 'dateRight')).year
+  )
 }
 
 /**
@@ -959,9 +1246,9 @@ export function differenceInQuarters(dateLeft, dateRight) {
  * @returns {number}
  */
 export function differenceInCalendarQuarters(dateLeft, dateRight) {
-  const left = toPlainDate(dateLeft, 'dateLeft')
-  const right = toPlainDate(dateRight, 'dateRight')
-  return (left.year - right.year) * 4 + (getQuarter(left) - getQuarter(right))
+  const left = isoOf(toPlainDate(dateLeft, 'dateLeft'))
+  const right = isoOf(toPlainDate(dateRight, 'dateRight'))
+  return (left.year - right.year) * 4 + (quarterOf(left) - quarterOf(right))
 }
 
 // ─── compare / equal ───────────────────────────────────────────────
@@ -973,10 +1260,8 @@ export function differenceInCalendarQuarters(dateLeft, dateRight) {
  */
 export function isBefore(date, dateToCompare) {
   return (
-    Temporal.PlainDate.compare(
-      toPlainDate(date),
-      toPlainDate(dateToCompare, 'dateToCompare'),
-    ) < 0
+    PlainDateFns.compare(toPlainDate(date), toPlainDate(dateToCompare, 'dateToCompare')) <
+    0
   )
 }
 
@@ -987,10 +1272,8 @@ export function isBefore(date, dateToCompare) {
  */
 export function isAfter(date, dateToCompare) {
   return (
-    Temporal.PlainDate.compare(
-      toPlainDate(date),
-      toPlainDate(dateToCompare, 'dateToCompare'),
-    ) > 0
+    PlainDateFns.compare(toPlainDate(date), toPlainDate(dateToCompare, 'dateToCompare')) >
+    0
   )
 }
 
@@ -1002,7 +1285,7 @@ export function isAfter(date, dateToCompare) {
  */
 export function isEqual(dateLeft, dateRight) {
   return (
-    Temporal.PlainDate.compare(
+    PlainDateFns.compare(
       toPlainDate(dateLeft, 'dateLeft'),
       toPlainDate(dateRight, 'dateRight'),
     ) === 0
@@ -1022,10 +1305,15 @@ export function isSameWeek(dateLeft, dateRight, options) {
   const left = toPlainDate(dateLeft, 'dateLeft')
   const right = toPlainDate(dateRight, 'dateRight')
   // own guard, so a week start below the minimum does not say startOfWeek
-  return guardRange('isSameWeek', () =>
-    left
-      .subtract({ days: daysIntoWeek(left, options) })
-      .equals(right.subtract({ days: daysIntoWeek(right, options) })),
+  // compare, not equals: Temporal's equals compares the calendar as well as the day, so it
+  // answers false for the same week in two calendars. compare reads the ISO fields alone.
+  return guardRange(
+    'isSameWeek',
+    () =>
+      PlainDateFns.compare(
+        PlainDateFns.subtractDays(left, daysIntoWeek(left, options)),
+        PlainDateFns.subtractDays(right, daysIntoWeek(right, options)),
+      ) === 0,
   )
 }
 
@@ -1035,8 +1323,8 @@ export function isSameWeek(dateLeft, dateRight, options) {
  * @returns {boolean}
  */
 export function isSameMonth(dateLeft, dateRight) {
-  const a = toPlainDate(dateLeft, 'dateLeft')
-  const b = toPlainDate(dateRight, 'dateRight')
+  const a = isoOf(toPlainDate(dateLeft, 'dateLeft'))
+  const b = isoOf(toPlainDate(dateRight, 'dateRight'))
   return a.year === b.year && a.month === b.month
 }
 
@@ -1046,7 +1334,12 @@ export function isSameMonth(dateLeft, dateRight) {
  * @returns {boolean}
  */
 export function isSameYear(dateLeft, dateRight) {
-  return getYear(dateLeft) === getYear(dateRight)
+  // NOT getYear, for the same reason as differenceInCalendarYears: two days 543 ISO years apart
+  // both read year 2569 once one of them carries a Buddhist label, and this answered true.
+  return (
+    isoOf(toPlainDate(dateLeft, 'dateLeft')).year ===
+    isoOf(toPlainDate(dateRight, 'dateRight')).year
+  )
 }
 
 /**
@@ -1055,9 +1348,9 @@ export function isSameYear(dateLeft, dateRight) {
  * @returns {boolean}
  */
 export function isSameQuarter(dateLeft, dateRight) {
-  const a = toPlainDate(dateLeft, 'dateLeft')
-  const b = toPlainDate(dateRight, 'dateRight')
-  return a.year === b.year && getQuarter(a) === getQuarter(b)
+  const a = isoOf(toPlainDate(dateLeft, 'dateLeft'))
+  const b = isoOf(toPlainDate(dateRight, 'dateRight'))
+  return a.year === b.year && quarterOf(a) === quarterOf(b)
 }
 
 /**
@@ -1067,7 +1360,7 @@ export function isSameQuarter(dateLeft, dateRight) {
  */
 export function compareAsc(dateLeft, dateRight) {
   return /** @type {-1 | 0 | 1} */ (
-    Temporal.PlainDate.compare(
+    PlainDateFns.compare(
       toPlainDate(dateLeft, 'dateLeft'),
       toPlainDate(dateRight, 'dateRight'),
     )
@@ -1093,7 +1386,7 @@ export function min(dates) {
   return toDayString(
     dates
       .map((d) => toPlainDate(d))
-      .reduce((a, b) => (Temporal.PlainDate.compare(a, b) <= 0 ? a : b)),
+      .reduce((a, b) => (PlainDateFns.compare(a, b) <= 0 ? a : b)),
   )
 }
 
@@ -1106,7 +1399,7 @@ export function max(dates) {
   return toDayString(
     dates
       .map((d) => toPlainDate(d))
-      .reduce((a, b) => (Temporal.PlainDate.compare(a, b) >= 0 ? a : b)),
+      .reduce((a, b) => (PlainDateFns.compare(a, b) >= 0 ? a : b)),
   )
 }
 
@@ -1154,7 +1447,7 @@ export function isFirstDayOfMonth(date) {
 /** @param {DayInput} date @returns {boolean} */
 export function isLastDayOfMonth(date) {
   const d = toPlainDate(date)
-  return d.day === d.daysInMonth
+  return d.day === PlainDateFns.daysInMonth(d)
 }
 
 // ─── intervals ─────────────────────────────────────────────────────
@@ -1166,7 +1459,7 @@ export function isLastDayOfMonth(date) {
  */
 export function eachDayOfInterval(interval) {
   const { start, end } = toInterval(interval)
-  if (Temporal.PlainDate.compare(start, end) > 0) {
+  if (PlainDateFns.compare(start, end) > 0) {
     throw new RangeError('daymath: interval start must not be after end')
   }
   /** @type {string[]} */
@@ -1176,8 +1469,8 @@ export function eachDayOfInterval(interval) {
   // PlainDate (+275760-09-13) throws
   for (;;) {
     out.push(toDayString(cur))
-    if (Temporal.PlainDate.compare(cur, end) >= 0) break
-    cur = cur.add({ days: 1 })
+    if (PlainDateFns.compare(cur, end) >= 0) break
+    cur = PlainDateFns.addDays(cur, 1)
   }
   return out
 }
@@ -1189,22 +1482,22 @@ export function eachDayOfInterval(interval) {
  */
 export function eachMonthOfInterval(interval) {
   const { start, end } = toInterval(interval)
-  if (Temporal.PlainDate.compare(start, end) > 0) {
+  if (PlainDateFns.compare(start, end) > 0) {
     throw new RangeError('daymath: interval start must not be after end')
   }
   /** @type {string[]} */
   const out = []
   // the 1st of start's month can sit below the minimum PlainDate
   const [cur0, last] = guardRange('eachMonthOfInterval', () => [
-    start.with({ day: 1 }),
-    end.with({ day: 1 }),
+    PlainDateFns.withFields(start, { day: 1 }),
+    PlainDateFns.withFields(end, { day: 1 }),
   ])
   let cur = cur0
   // same boundary rule as eachDayOfInterval
   for (;;) {
     out.push(toDayString(cur))
-    if (Temporal.PlainDate.compare(cur, last) >= 0) break
-    cur = cur.add({ months: 1 })
+    if (PlainDateFns.compare(cur, last) >= 0) break
+    cur = PlainDateFns.addMonths(cur, 1)
   }
   return out
 }
@@ -1216,17 +1509,23 @@ export function eachMonthOfInterval(interval) {
  */
 export function eachYearOfInterval(interval) {
   const { start, end } = toInterval(interval)
-  if (Temporal.PlainDate.compare(start, end) > 0) {
+  if (PlainDateFns.compare(start, end) > 0) {
     throw new RangeError('daymath: interval start must not be after end')
   }
   /** @type {string[]} */
   const out = []
-  let y = start.year
-  // Jan 1 of start's year can sit below the minimum PlainDate
+  // `with` then `add`, never `PlainDate.from({year})`: both keep start's calendar, and the object
+  // form would read `year` as an ISO year, which is 543 years out for a Buddhist day.
+  // Jan 1 of start's year can sit below the minimum PlainDate.
   guardRange('eachYearOfInterval', () => {
-    while (y <= end.year) {
-      out.push(toDayString(Temporal.PlainDate.from({ year: y, month: 1, day: 1 })))
-      y += 1
+    // Compare ISO years, then add. Testing the loop condition AFTER the push is what keeps the
+    // top edge working: Jan 1 of +275760 is valid, and adding a year to it is not.
+    const lastIsoYear = isoOf(end).year
+    let cur = PlainDateFns.withFields(start, { month: 1, day: 1 })
+    for (;;) {
+      out.push(toDayString(cur))
+      if (isoOf(cur).year >= lastIsoYear) break
+      cur = PlainDateFns.addYears(cur, 1)
     }
   })
   return out
@@ -1241,12 +1540,10 @@ export function eachYearOfInterval(interval) {
 export function isWithinInterval(date, interval) {
   const d = toPlainDate(date)
   const { start, end } = toInterval(interval)
-  if (Temporal.PlainDate.compare(start, end) > 0) {
+  if (PlainDateFns.compare(start, end) > 0) {
     throw new RangeError('daymath: interval start must not be after end')
   }
-  return (
-    Temporal.PlainDate.compare(d, start) >= 0 && Temporal.PlainDate.compare(d, end) <= 0
-  )
+  return PlainDateFns.compare(d, start) >= 0 && PlainDateFns.compare(d, end) <= 0
 }
 
 /**
@@ -1258,11 +1555,11 @@ export function isWithinInterval(date, interval) {
 export function clamp(date, interval) {
   const d = toPlainDate(date)
   const { start, end } = toInterval(interval)
-  if (Temporal.PlainDate.compare(start, end) > 0) {
+  if (PlainDateFns.compare(start, end) > 0) {
     throw new RangeError('daymath: interval start must not be after end')
   }
-  if (Temporal.PlainDate.compare(d, start) < 0) return toDayString(start)
-  if (Temporal.PlainDate.compare(d, end) > 0) return toDayString(end)
+  if (PlainDateFns.compare(d, start) < 0) return toDayString(start)
+  if (PlainDateFns.compare(d, end) > 0) return toDayString(end)
   return toDayString(d)
 }
 
@@ -1276,22 +1573,21 @@ export function clamp(date, interval) {
 export function areIntervalsOverlapping(intervalLeft, intervalRight, options) {
   const a = toInterval(intervalLeft)
   const b = toInterval(intervalRight)
-  if (Temporal.PlainDate.compare(a.start, a.end) > 0) {
+  if (PlainDateFns.compare(a.start, a.end) > 0) {
     throw new RangeError('daymath: intervalLeft start must not be after end')
   }
-  if (Temporal.PlainDate.compare(b.start, b.end) > 0) {
+  if (PlainDateFns.compare(b.start, b.end) > 0) {
     throw new RangeError('daymath: intervalRight start must not be after end')
   }
   const inclusive = options?.inclusive ?? false
   if (inclusive) {
     return (
-      Temporal.PlainDate.compare(a.start, b.end) <= 0 &&
-      Temporal.PlainDate.compare(b.start, a.end) <= 0
+      PlainDateFns.compare(a.start, b.end) <= 0 &&
+      PlainDateFns.compare(b.start, a.end) <= 0
     )
   }
   // date-fns default: touch-at-endpoint is NOT overlap
   return (
-    Temporal.PlainDate.compare(a.start, b.end) < 0 &&
-    Temporal.PlainDate.compare(b.start, a.end) < 0
+    PlainDateFns.compare(a.start, b.end) < 0 && PlainDateFns.compare(b.start, a.end) < 0
   )
 }