@j13b/scheduler 0.0.0-stage → 0.1.0

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;
+}

package/src/generators/instant.ts

@@ -0,0 +1,18 @@
+import type { InstantRule } from "../types.js";
+import { computeSpanEnd } from "../tz.js";
+import { type Occurrence, intersects } from "./types.js";
+
+// A single occurrence at an absolute UTC instant. The template timezone does
+// not affect the start (the instant is already a fixed point on the timeline);
+// it only flexes an hourSpan end, via computeSpanEnd.
+export function generateInstant(
+  rule: InstantRule,
+  tz: string | undefined,
+  windowStart: number,
+  windowEnd: number
+): Occurrence[] {
+  const start = rule.startOn;
+  const end = computeSpanEnd(start, rule.timeSpan, tz);
+  if (!intersects(start, end, windowStart, windowEnd)) return [];
+  return [{ startTimestamp: start, endTimestamp: end }];
+}

package/src/generators/local_date_time.ts

@@ -0,0 +1,38 @@
+import type { Disambiguation, LocalDateTimeRule } from "../types.js";
+import { computeSpanEnd, isNonexistentWallTime, monthLength, wallTimeToUtc } from "../tz.js";
+import { type Occurrence, intersects } from "./types.js";
+
+// A single occurrence expressed in wall-clock terms, resolved through the
+// template timezone (DST-aware). `day` clamps to the month length. When tz is
+// undefined the wall-clock fields are interpreted as UTC. A spring-forward gap
+// or fall-back overlap on the start is resolved per `disambiguation` (see
+// tz.ts) — "skip" drops the occurrence entirely if its wall time doesn't exist.
+export function generateLocalDateTime(
+  rule: LocalDateTimeRule,
+  tz: string | undefined,
+  windowStart: number,
+  windowEnd: number,
+  disambiguation: Disambiguation = "compatible"
+): Occurrence[] {
+  if (!Number.isInteger(rule.year)) {
+    throw new Error(`LocalDateTimeRule.year must be an integer (got ${rule.year})`);
+  }
+  if (rule.month < 0 || rule.month > 11) {
+    throw new Error(`LocalDateTimeRule.month must be in 0..11 (got ${rule.month})`);
+  }
+  if (rule.day < 1 || rule.day > 31) {
+    throw new Error(`LocalDateTimeRule.day must be in 1..31 (got ${rule.day})`);
+  }
+
+  const day = Math.min(rule.day, monthLength(rule.year, rule.month));
+  if (
+    disambiguation === "skip" &&
+    isNonexistentWallTime(rule.year, rule.month, day, rule.timeOfDay, tz)
+  ) {
+    return [];
+  }
+  const start = wallTimeToUtc(rule.year, rule.month, day, rule.timeOfDay, tz, disambiguation);
+  const end = computeSpanEnd(start, rule.timeSpan, tz);
+  if (!intersects(start, end, windowStart, windowEnd)) return [];
+  return [{ startTimestamp: start, endTimestamp: end }];
+}