@j13b/scheduler 0.0.0-stage → 0.1.1

package/src/alterations.ts

@@ -0,0 +1,108 @@
+import { intersects } from "./generators/types.js";
+import type { KeyedOccurrence } from "./occurrence_key.js";
+import type { Alteration, ScheduledEvent } from "./types.js";
+import { computeSpanEnd } from "./tz.js";
+
+// Apply a template's alterations to its base occurrences and emit the final
+// ScheduledEvents.
+//
+// Two passes:
+//   1. Walk base occurrences. Cancel suppresses; reschedule replaces (and
+//      may move out of window, in which case it's not emitted).
+//   2. Walk reschedules whose original key is NOT in the base list (the
+//      original was outside the window) but whose new time IS in the window.
+//      Synthesize an event for them. This is what activity-board does in its
+//      separate AlterationEventGenerator.
+//
+// `tz` is the template's timezone. Used to interpret hourSpan on the
+// alteration's timeSpan (if any). When the alteration carries no timeSpan,
+// we preserve the original occurrence's duration (end - start in UTC ms).
+//
+// Result is sorted ascending by startTimestamp.
+export function applyAlterations<TPayload extends { type: string }>(
+  templateId: string,
+  basePayload: TPayload,
+  keyedOccurrences: readonly KeyedOccurrence[],
+  alterations: readonly Alteration<TPayload>[],
+  tz: string | undefined,
+  windowStart: number,
+  windowEnd: number
+): ScheduledEvent<TPayload>[] {
+  // Index alterations for THIS template by occurrence key. If multiple
+  // alterations target the same key, last-write-wins.
+  const altByKey = new Map<string, Alteration<TPayload>>();
+  for (const alt of alterations) {
+    if (alt.templateId === templateId) altByKey.set(alt.occurrenceKey, alt);
+  }
+
+  const out: ScheduledEvent<TPayload>[] = [];
+  const seenKeys = new Set<string>();
+
+  for (const occ of keyedOccurrences) {
+    seenKeys.add(occ.occurrenceKey);
+    const alt = altByKey.get(occ.occurrenceKey);
+
+    if (alt == null) {
+      out.push({
+        templateId,
+        occurrenceKey: occ.occurrenceKey,
+        startTimestamp: occ.startTimestamp,
+        endTimestamp: occ.endTimestamp,
+        payload: basePayload,
+      });
+      continue;
+    }
+    if (alt.kind === "cancel") continue;
+
+    // reschedule
+    const start = alt.startTimestamp ?? occ.startTimestamp;
+    // If the alteration specifies a timeSpan, use it (with tz semantics).
+    // Otherwise preserve the original UTC duration.
+    const end =
+      alt.timeSpan != null
+        ? computeSpanEnd(start, alt.timeSpan, tz)
+        : start + (occ.endTimestamp - occ.startTimestamp);
+    if (!intersects(start, end, windowStart, windowEnd)) continue;
+    out.push({
+      templateId,
+      occurrenceKey: occ.occurrenceKey,
+      startTimestamp: start,
+      endTimestamp: end,
+      payload: _mergePayload(basePayload, alt.payloadOverride),
+      alterationId: alt.id,
+    });
+  }
+
+  // Orphan reschedules: alteration's occurrenceKey isn't in the base list
+  // (because the original fell outside the window) but the rescheduled time
+  // is. Cancels for orphans are no-ops — there was nothing to cancel here.
+  for (const alt of altByKey.values()) {
+    if (seenKeys.has(alt.occurrenceKey)) continue;
+    if (alt.kind !== "reschedule") continue;
+    if (alt.startTimestamp == null) continue;
+    // No original to inherit duration from; default to 1ms if no timeSpan.
+    const end =
+      alt.timeSpan != null
+        ? computeSpanEnd(alt.startTimestamp, alt.timeSpan, tz)
+        : alt.startTimestamp + 1;
+    if (!intersects(alt.startTimestamp, end, windowStart, windowEnd)) continue;
+    out.push({
+      templateId,
+      occurrenceKey: alt.occurrenceKey,
+      startTimestamp: alt.startTimestamp,
+      endTimestamp: end,
+      payload: _mergePayload(basePayload, alt.payloadOverride),
+      alterationId: alt.id,
+    });
+  }
+
+  return out.sort((a, b) => a.startTimestamp - b.startTimestamp);
+}
+
+function _mergePayload<TPayload extends { type: string }>(
+  base: TPayload,
+  override: Partial<TPayload> | undefined
+): TPayload {
+  if (override == null) return base;
+  return { ...base, ...override } as TPayload;
+}

package/src/dispatcher.ts

@@ -0,0 +1,184 @@
+import type { IEventSubscription } from "@j13b/state";
+import { type DispatcherStore, InMemoryDispatcherStore } from "./dispatcher_store.js";
+import type { Scheduler } from "./scheduler.js";
+import type { ScheduledEvent } from "./types.js";
+
+// Default safety-net wait when nothing is scheduled. The Scheduler.changed
+// event normally wakes us as soon as something gets added, so this is just
+// a backstop in case a notification is missed.
+const DEFAULT_IDLE_TIMEOUT_MS = 60 * 60 * 1000;
+
+export interface DispatcherConfig<TPayload extends { type: string }> {
+  scheduler: Scheduler<TPayload>;
+  // Called for each due event in cursor → now order. Errors thrown from here
+  // are passed to onError; the cursor advances regardless (cron-style: a
+  // permanently-failing fire shouldn't block the queue forever).
+  fire: (event: ScheduledEvent<TPayload>) => Promise<void> | void;
+  // Persists the cursor across restarts. Defaults to in-memory (no recovery).
+  store?: DispatcherStore;
+  // Called when fire() throws or list() fails. Defaults to console.error.
+  onError?: (err: unknown, event?: ScheduledEvent<TPayload>) => void;
+  // Backstop wait when no event is scheduled. Default 1 hour. Lower for tests.
+  idleTimeoutMs?: number;
+  // Clock injection (Date.now) and timer injection (setTimeout/clearTimeout).
+  // Defaults to wall clock. Inject for deterministic tests.
+  now?: () => number;
+  setTimeout?: (fn: () => void, ms: number) => unknown;
+  clearTimeout?: (handle: unknown) => void;
+}
+
+// Drives a Scheduler in real time. The loop:
+//   1. Catch up: list(cursor, now) → fire each → advance cursor → save.
+//   2. Find next: nextDue(now, 1) → wait until its startTimestamp.
+//   3. Wait may end early via Scheduler.changed (a write happened) or stop().
+// Catch-up handles crashes AND in-process adds we missed. The change event
+// handles in-process adds while we're sleeping — the dispatcher wakes
+// immediately and re-queries instead of firing the stale "next" event late.
+export class Dispatcher<TPayload extends { type: string }> {
+  private readonly _scheduler: Scheduler<TPayload>;
+  private readonly _fire: (event: ScheduledEvent<TPayload>) => Promise<void> | void;
+  private readonly _store: DispatcherStore;
+  private readonly _onError: (err: unknown, event?: ScheduledEvent<TPayload>) => void;
+  private readonly _idleTimeoutMs: number;
+  private readonly _now: () => number;
+  private readonly _setTimeout: (fn: () => void, ms: number) => unknown;
+  private readonly _clearTimeout: (handle: unknown) => void;
+
+  private _running = false;
+  private _wakeResolve: (() => void) | null = null;
+  private _changeSubscription: IEventSubscription<void> | null = null;
+
+  constructor(config: DispatcherConfig<TPayload>) {
+    this._scheduler = config.scheduler;
+    this._fire = config.fire;
+    this._store = config.store ?? new InMemoryDispatcherStore();
+    this._onError = config.onError ?? defaultOnError;
+    this._idleTimeoutMs = config.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    this._now = config.now ?? Date.now;
+    this._setTimeout = config.setTimeout ?? ((fn, ms) => globalThis.setTimeout(fn, ms));
+    this._clearTimeout =
+      config.clearTimeout ?? ((h) => globalThis.clearTimeout(h as ReturnType<typeof setTimeout>));
+  }
+
+  // Starts the loop. Resolves after the first catch-up pass completes (so
+  // tests can await an initial sync). The loop keeps running in the
+  // background until stop() is called.
+  async start(): Promise<void> {
+    if (this._running) return;
+    this._running = true;
+    this._changeSubscription = this._scheduler.changed.subscribe(() => this._wake());
+    // First iteration in foreground so callers can await initial catch-up.
+    await this._tick();
+    if (this._running) void this._loop();
+  }
+
+  // Halts the loop. Any in-flight fire() completes; subsequent fires are
+  // skipped. The Scheduler subscription is removed.
+  stop(): void {
+    if (!this._running) return;
+    this._running = false;
+    if (this._changeSubscription != null) {
+      this._changeSubscription.unsubscribe();
+      this._changeSubscription = null;
+    }
+    this._wake();
+  }
+
+  // ─── Internals ──────────────────────────────────────────────
+
+  private async _loop(): Promise<void> {
+    while (this._running) {
+      const target = await this._findNextTarget();
+      if (!this._running) return;
+      await this._sleepUntil(target);
+      if (!this._running) return;
+      await this._tick();
+    }
+  }
+
+  // Returns the epoch-ms instant the dispatcher should next wake. Either
+  // the next due event's startTimestamp, or now + idleTimeoutMs.
+  private async _findNextTarget(): Promise<number> {
+    try {
+      const upcoming = await this._scheduler.nextDue(this._now(), 1);
+      const next = upcoming[0];
+      return next != null ? next.startTimestamp : this._now() + this._idleTimeoutMs;
+    } catch (err) {
+      this._onError(err);
+      return this._now() + this._idleTimeoutMs;
+    }
+  }
+
+  // Catch-up pass: fire everything with start in [cursor, now]. We use
+  // `now + 1` as the half-open windowEnd so an event scheduled exactly at
+  // the wake instant is included (the wake from setTimeout lands on the
+  // event's startTimestamp, and we don't want to miss it). Advancing the
+  // cursor to `now + 1` likewise avoids re-listing the same event on the
+  // next tick.
+  private async _tick(): Promise<void> {
+    const cursor = (await this._store.loadCursor()) ?? this._now();
+    const now = this._now();
+    const windowEnd = now + 1;
+    if (windowEnd <= cursor) {
+      // Cursor is already at or past `now + 1` — happens on the very first
+      // tick when we just-saved-and-rewoke. Nothing to do.
+      return;
+    }
+
+    let events: ScheduledEvent<TPayload>[];
+    try {
+      events = await this._scheduler.list(cursor, windowEnd);
+    } catch (err) {
+      this._onError(err);
+      // Don't advance cursor on a list failure — try again next tick.
+      return;
+    }
+
+    for (const event of events) {
+      if (!this._running) return;
+      try {
+        await this._fire(event);
+      } catch (err) {
+        this._onError(err, event);
+      }
+    }
+    await this._store.saveCursor(windowEnd);
+  }
+
+  // Sleeps until either the target epoch-ms instant, or wake() is called
+  // (via Scheduler.changed or stop()). No-op if target is already past.
+  private async _sleepUntil(targetMs: number): Promise<void> {
+    const remaining = targetMs - this._now();
+    if (remaining <= 0) return;
+    await new Promise<void>((resolve) => {
+      let done = false;
+      const timer = this._setTimeout(() => {
+        if (done) return;
+        done = true;
+        this._wakeResolve = null;
+        resolve();
+      }, remaining);
+      this._wakeResolve = () => {
+        if (done) return;
+        done = true;
+        this._clearTimeout(timer);
+        this._wakeResolve = null;
+        resolve();
+      };
+    });
+  }
+
+  // Resolves any in-flight _sleepUntil. Called by stop() and by the
+  // Scheduler.changed subscription.
+  private _wake(): void {
+    if (this._wakeResolve != null) this._wakeResolve();
+  }
+}
+
+function defaultOnError(err: unknown, event?: ScheduledEvent<{ type: string }>): void {
+  if (event != null) {
+    console.error(`[Dispatcher] fire failed for ${event.templateId}/${event.occurrenceKey}:`, err);
+  } else {
+    console.error("[Dispatcher] error:", err);
+  }
+}

package/src/dispatcher_store.ts

@@ -0,0 +1,26 @@
+// Persistence for the Dispatcher's tick cursor. The cursor is a single
+// epoch-ms value: the last instant for which the Dispatcher has fired all
+// due events. On restart, the Dispatcher catches up by listing events in
+// [cursor, now) and firing them — so a process crash followed by restart
+// won't lose events that were due during downtime.
+//
+// Same shape as ChatStore / MemoryStore in the agent module — implement
+// against whatever backend you want.
+export interface DispatcherStore {
+  loadCursor(): Promise<number | null>;
+  saveCursor(cursor: number): Promise<void>;
+}
+
+// Reference in-memory implementation. Useful for tests and short-lived
+// processes that don't need crash recovery.
+export class InMemoryDispatcherStore implements DispatcherStore {
+  private _cursor: number | null = null;
+
+  async loadCursor(): Promise<number | null> {
+    return this._cursor;
+  }
+
+  async saveCursor(cursor: number): Promise<void> {
+    this._cursor = cursor;
+  }
+}

package/src/generators/anchored.ts

@@ -0,0 +1,69 @@
+import type { AnchoredRule } from "../types.js";
+import { computeSpanEnd } from "../tz.js";
+import {
+  MAX_OCCURRENCES_PER_GENERATE,
+  type Occurrence,
+  TooManyOccurrencesError,
+  intersects,
+} from "./types.js";
+
+// Anchored is tz-independent for STEPPING (every occurrence is exactly
+// intervalMs ms from the anchor), but tz can still affect the end-of-
+// occurrence when hourSpan is used. seriesStart/seriesEnd bound in UTC.
+export function generateAnchored(
+  rule: AnchoredRule,
+  tz: string | undefined,
+  windowStart: number,
+  windowEnd: number
+): Occurrence[] {
+  if (rule.intervalMs <= 0) {
+    throw new Error(`AnchoredRule.intervalMs must be > 0 (got ${rule.intervalMs})`);
+  }
+  if (rule.count != null && rule.count < 0) {
+    throw new Error(`AnchoredRule.count must be >= 0 (got ${rule.count})`);
+  }
+
+  const seriesEnd = rule.seriesEnd ?? Number.POSITIVE_INFINITY;
+  const effectiveEnd = Math.min(windowEnd, seriesEnd);
+  const effectiveStart = Math.max(windowStart, rule.seriesStart);
+
+  if (effectiveStart >= effectiveEnd) return [];
+
+  // If `count` is set we must start counting from the anchor; otherwise we
+  // can fast-forward to the window start.
+  let index: number;
+  let occurrenceStart: number;
+  if (rule.count != null) {
+    index = 0;
+    occurrenceStart = rule.anchorDate;
+  } else {
+    if (effectiveStart <= rule.anchorDate) {
+      index = 0;
+      occurrenceStart = rule.anchorDate;
+    } else {
+      // First occurrence at or after effectiveStart.
+      const stepsAhead = Math.ceil((effectiveStart - rule.anchorDate) / rule.intervalMs);
+      index = stepsAhead;
+      occurrenceStart = rule.anchorDate + stepsAhead * rule.intervalMs;
+    }
+  }
+
+  const out: Occurrence[] = [];
+  while (occurrenceStart < effectiveEnd) {
+    if (rule.count != null && index >= rule.count) break;
+
+    const occEnd = computeSpanEnd(occurrenceStart, rule.timeSpan, tz);
+    if (
+      intersects(occurrenceStart, occEnd, windowStart, windowEnd) &&
+      occurrenceStart >= rule.seriesStart
+    ) {
+      out.push({ startTimestamp: occurrenceStart, endTimestamp: occEnd });
+      if (out.length > MAX_OCCURRENCES_PER_GENERATE) {
+        throw new TooManyOccurrencesError("anchored");
+      }
+    }
+    index++;
+    occurrenceStart += rule.intervalMs;
+  }
+  return out;
+}

package/src/generators/days_of_month.ts

@@ -0,0 +1,100 @@
+import type { DaysOfMonthRule, Disambiguation } from "../types.js";
+import {
+  computeSpanEnd,
+  isNonexistentWallTime,
+  monthLength,
+  utcToWallParts,
+  wallTimeToUtc,
+} from "../tz.js";
+import {
+  MAX_OCCURRENCES_PER_GENERATE,
+  type Occurrence,
+  TooManyOccurrencesError,
+  intersects,
+} from "./types.js";
+
+// Numerical date-based recurrence: months × daysOfMonth. Days clamp per
+// month (day 31 in April → Apr 30, day 29 in Feb non-leap → Feb 28).
+export function generateDaysOfMonth(
+  rule: DaysOfMonthRule,
+  tz: string | undefined,
+  windowStart: number,
+  windowEnd: number,
+  disambiguation: Disambiguation = "compatible"
+): Occurrence[] {
+  if (rule.yearInterval <= 0) {
+    throw new Error(`DaysOfMonthRule.yearInterval must be > 0 (got ${rule.yearInterval})`);
+  }
+  if (rule.months.length === 0) {
+    throw new Error("DaysOfMonthRule.months must be non-empty");
+  }
+  for (const m of rule.months) {
+    if (m < 0 || m > 11) {
+      throw new Error(`DaysOfMonthRule.months entries must be in 0..11 (got ${m})`);
+    }
+  }
+  if (rule.daysOfMonth.length === 0) {
+    throw new Error("DaysOfMonthRule.daysOfMonth must be non-empty");
+  }
+  for (const d of rule.daysOfMonth) {
+    if (d < 1 || d > 31) {
+      throw new Error(`DaysOfMonthRule.daysOfMonth entries must be in 1..31 (got ${d})`);
+    }
+  }
+  if (rule.count != null && rule.count < 0) {
+    throw new Error(`DaysOfMonthRule.count must be >= 0 (got ${rule.count})`);
+  }
+
+  const seriesEnd = rule.seriesEnd ?? Number.POSITIVE_INFINITY;
+  const effectiveEnd = Math.min(windowEnd, seriesEnd);
+  if (rule.seriesStart >= effectiveEnd) return [];
+
+  const months = [...new Set(rule.months)].sort((a, b) => a - b);
+  const daysOfMonth = [...new Set(rule.daysOfMonth)].sort((a, b) => a - b);
+
+  const startYear = utcToWallParts(rule.seriesStart, tz).year;
+  const endYear = utcToWallParts(Math.min(effectiveEnd, Number.MAX_SAFE_INTEGER), tz).year;
+
+  const out: Occurrence[] = [];
+  let count = 0;
+
+  for (let year = startYear; year <= endYear; year += rule.yearInterval) {
+    const yearEmits: Occurrence[] = [];
+
+    for (const month of months) {
+      const len = monthLength(year, month);
+      // Dedup clamped days so day-31 + day-30 in April don't both emit Apr 30.
+      const clampedDays = [...new Set(daysOfMonth.map((d) => Math.min(d, len)))];
+      for (const day of clampedDays) {
+        if (
+          disambiguation === "skip" &&
+          isNonexistentWallTime(year, month, day, rule.timeOfDay, tz)
+        ) {
+          continue;
+        }
+        const occStart = wallTimeToUtc(year, month, day, rule.timeOfDay, tz, disambiguation);
+        const occEnd = computeSpanEnd(occStart, rule.timeSpan, tz);
+
+        if (occStart < rule.seriesStart) continue;
+        if (occStart >= seriesEnd) continue;
+
+        if (rule.count != null && count >= rule.count) {
+          yearEmits.sort((a, b) => a.startTimestamp - b.startTimestamp);
+          out.push(...yearEmits);
+          return out;
+        }
+        count++;
+
+        if (intersects(occStart, occEnd, windowStart, windowEnd)) {
+          yearEmits.push({ startTimestamp: occStart, endTimestamp: occEnd });
+          if (out.length + yearEmits.length > MAX_OCCURRENCES_PER_GENERATE) {
+            throw new TooManyOccurrencesError("daysOfMonth");
+          }
+        }
+      }
+    }
+    yearEmits.sort((a, b) => a.startTimestamp - b.startTimestamp);
+    out.push(...yearEmits);
+  }
+  return out;
+}

package/src/generators/days_of_week.ts

@@ -0,0 +1,101 @@
+import type { DaysOfWeekRule, Disambiguation } from "../types.js";
+import {
+  addDaysInTz,
+  computeSpanEnd,
+  dayOfWeekInTz,
+  isNonexistentWallTime,
+  utcToWallParts,
+  wallTimeToUtc,
+} from "../tz.js";
+import {
+  MAX_OCCURRENCES_PER_GENERATE,
+  type Occurrence,
+  TooManyOccurrencesError,
+  intersects,
+} from "./types.js";
+
+// Iterate week-by-week (in wall time, in tz) starting from seriesStart's
+// week. For each scheduled week, emit the occurrences that fall on the
+// rule's days.
+export function generateDaysOfWeek(
+  rule: DaysOfWeekRule,
+  tz: string | undefined,
+  windowStart: number,
+  windowEnd: number,
+  disambiguation: Disambiguation = "compatible"
+): Occurrence[] {
+  if (rule.weekInterval <= 0) {
+    throw new Error(`DaysOfWeekRule.weekInterval must be > 0 (got ${rule.weekInterval})`);
+  }
+  if (rule.days.length === 0) {
+    throw new Error("DaysOfWeekRule.days must be non-empty");
+  }
+  if (rule.count != null && rule.count < 0) {
+    throw new Error(`DaysOfWeekRule.count must be >= 0 (got ${rule.count})`);
+  }
+
+  const seriesEnd = rule.seriesEnd ?? Number.POSITIVE_INFINITY;
+  const effectiveEnd = Math.min(windowEnd, seriesEnd);
+  if (rule.seriesStart >= effectiveEnd) return [];
+
+  // Sort days for deterministic emit order within a week.
+  const days = [...rule.days].sort((a, b) => a - b);
+
+  // Anchor: snap seriesStart to the start of its week (Sunday) in tz.
+  const seriesStartParts = utcToWallParts(rule.seriesStart, tz);
+  const daysSinceSunday = seriesStartParts.dayOfWeek;
+  const weekAnchor = wallTimeToUtc(
+    seriesStartParts.year,
+    seriesStartParts.month,
+    seriesStartParts.day - daysSinceSunday,
+    0,
+    tz
+  );
+
+  const out: Occurrence[] = [];
+  let count = 0;
+  // Step by `weekInterval` weeks at a time. Use addDaysInTz to handle DST
+  // correctly (a week is 7 calendar days, not 7*86400000 ms).
+  let weekStart = weekAnchor;
+  while (weekStart < effectiveEnd) {
+    for (const dow of days) {
+      // Compute the day-of-week within this week in tz wall time.
+      const dayUtc = addDaysInTz(weekStart, dow, tz);
+      const dayParts = utcToWallParts(dayUtc, tz);
+      if (
+        disambiguation === "skip" &&
+        isNonexistentWallTime(dayParts.year, dayParts.month, dayParts.day, rule.timeOfDay, tz)
+      ) {
+        continue;
+      }
+      const occStart = wallTimeToUtc(
+        dayParts.year,
+        dayParts.month,
+        dayParts.day,
+        rule.timeOfDay,
+        tz,
+        disambiguation
+      );
+      const occEnd = computeSpanEnd(occStart, rule.timeSpan, tz);
+
+      // Must be on/after seriesStart and before seriesEnd.
+      if (occStart < rule.seriesStart) continue;
+      if (occStart >= seriesEnd) continue;
+
+      if (rule.count != null && count >= rule.count) return out;
+      count++;
+
+      if (intersects(occStart, occEnd, windowStart, windowEnd)) {
+        out.push({ startTimestamp: occStart, endTimestamp: occEnd });
+        if (out.length > MAX_OCCURRENCES_PER_GENERATE) {
+          throw new TooManyOccurrencesError("daysOfWeek");
+        }
+      }
+    }
+    weekStart = addDaysInTz(weekStart, 7 * rule.weekInterval, tz);
+  }
+  return out;
+}
+
+// Re-export so consumers can sanity-check the rule's first day in tz.
+export { dayOfWeekInTz };

package/src/generators/days_of_year.ts

@@ -0,0 +1,88 @@
+import type { DaysOfYearRule, Disambiguation } from "../types.js";
+import { computeSpanEnd, isNonexistentWallTime, utcToWallParts, wallTimeToUtc } from "../tz.js";
+import {
+  MAX_OCCURRENCES_PER_GENERATE,
+  type Occurrence,
+  TooManyOccurrencesError,
+  intersects,
+} from "./types.js";
+
+// Day-of-year recurrence. Day 1 = Jan 1. Day 366 only exists in leap
+// years and is SKIPPED in non-leap years (no clamp — "366th day" means
+// literally that).
+export function generateDaysOfYear(
+  rule: DaysOfYearRule,
+  tz: string | undefined,
+  windowStart: number,
+  windowEnd: number,
+  disambiguation: Disambiguation = "compatible"
+): Occurrence[] {
+  if (rule.yearInterval <= 0) {
+    throw new Error(`DaysOfYearRule.yearInterval must be > 0 (got ${rule.yearInterval})`);
+  }
+  if (rule.daysOfYear.length === 0) {
+    throw new Error("DaysOfYearRule.daysOfYear must be non-empty");
+  }
+  for (const d of rule.daysOfYear) {
+    if (d < 1 || d > 366) {
+      throw new Error(`DaysOfYearRule.daysOfYear entries must be in 1..366 (got ${d})`);
+    }
+  }
+  if (rule.count != null && rule.count < 0) {
+    throw new Error(`DaysOfYearRule.count must be >= 0 (got ${rule.count})`);
+  }
+
+  const seriesEnd = rule.seriesEnd ?? Number.POSITIVE_INFINITY;
+  const effectiveEnd = Math.min(windowEnd, seriesEnd);
+  if (rule.seriesStart >= effectiveEnd) return [];
+
+  const days = [...new Set(rule.daysOfYear)].sort((a, b) => a - b);
+
+  const startYear = utcToWallParts(rule.seriesStart, tz).year;
+  const endYear = utcToWallParts(Math.min(effectiveEnd, Number.MAX_SAFE_INTEGER), tz).year;
+
+  const out: Occurrence[] = [];
+  let count = 0;
+
+  for (let year = startYear; year <= endYear; year += rule.yearInterval) {
+    const yearEmits: Occurrence[] = [];
+
+    for (const dayOfYear of days) {
+      // Date.UTC(year, 0, N) treats N as "Nth day from Jan 1". If N is 366
+      // in a non-leap year it rolls into year+1; detect and skip.
+      const probe = new Date(Date.UTC(year, 0, dayOfYear));
+      if (probe.getUTCFullYear() !== year) continue; // day 366 in non-leap year
+
+      const month = probe.getUTCMonth();
+      const day = probe.getUTCDate();
+      if (
+        disambiguation === "skip" &&
+        isNonexistentWallTime(year, month, day, rule.timeOfDay, tz)
+      ) {
+        continue;
+      }
+      const occStart = wallTimeToUtc(year, month, day, rule.timeOfDay, tz, disambiguation);
+      const occEnd = computeSpanEnd(occStart, rule.timeSpan, tz);
+
+      if (occStart < rule.seriesStart) continue;
+      if (occStart >= seriesEnd) continue;
+
+      if (rule.count != null && count >= rule.count) {
+        yearEmits.sort((a, b) => a.startTimestamp - b.startTimestamp);
+        out.push(...yearEmits);
+        return out;
+      }
+      count++;
+
+      if (intersects(occStart, occEnd, windowStart, windowEnd)) {
+        yearEmits.push({ startTimestamp: occStart, endTimestamp: occEnd });
+        if (out.length + yearEmits.length > MAX_OCCURRENCES_PER_GENERATE) {
+          throw new TooManyOccurrencesError("daysOfYear");
+        }
+      }
+    }
+    yearEmits.sort((a, b) => a.startTimestamp - b.startTimestamp);
+    out.push(...yearEmits);
+  }
+  return out;
+}