@oneuptime/common 11.3.26 → 11.4.0

package/Tests/Types/OnCallDutyPolicy/LayerUtilExhaustiveRotation.test.ts

@@ -0,0 +1,957 @@
+/**
+ * EXHAUSTIVE unrestricted-rotation correctness matrix for LayerUtil.getEvents
+ * and LayerUtil.getMultiLayerEvents.
+ *
+ * Covers the full cross product:
+ *   intervalType {Hour, Day, Week, Month, Year}
+ *   x intervalCount {1, 2, 3}
+ *   x users {1, 2, 3, 5}
+ *   x calendar windows {starting AT the layer start, starting PARTWAY through}
+ *   x timezone {local (undefined), America/New_York, Asia/Kolkata}
+ *
+ * Invariants asserted per config:
+ *  (a) 24/7 CONTIGUITY - each event.start == previous.end + exactly 1 second
+ *      (no gaps, no overlaps, every event has positive length), over a
+ *      multi-period horizon.
+ *  (b) ROTATION ORDER - users cycle A,B,C,... with no skips and no repeats
+ *      (the user index advances by exactly one every period, modulo the roster
+ *      size), and an at-layer-start expansion begins with the first user.
+ *  (c) FAIRNESS - shift counts across the roster differ by at most one over
+ *      many periods, and every user takes a turn.
+ *  (d) WINDOWED == FULL EXPANSION - the live "who is on call at `at`" resolution
+ *      (getEvents / getMultiLayerEvents with getNumberOfEvents:1 starting the
+ *      window at `at`) agrees with the covering event of a full expansion from
+ *      the layer start, at many OFF-boundary instants; the windowed event is
+ *      clamped to `at` and runs to the true period boundary.
+ *  (e) EDGE CASES - single user (always that user), empty users (no events),
+ *      calendar end before layer start (no events), and grid-aligned degenerate
+ *      handoffs (handoff == layer start, handoff before layer start) resolving
+ *      to the exact same rotation as the natural handoff.
+ *
+ * A dedicated block exercises America/New_York across US spring-forward and
+ * fall-back so the schedule-zone (wall-clock) stepping diverges from the
+ * process zone (run this file additionally under TZ=UTC).
+ *
+ * Everything is internally consistent (windowed vs full both flow through the
+ * same engine with the same zone), so the timezone/DST assertions hold under
+ * any process TZ. Ground-truth boundaries are always read back from the engine
+ * rather than recomputed, so the tests never depend on a hand-rolled boundary
+ * model.
+ */
+import LayerUtil, { LayerProps } from "../../../Types/OnCallDutyPolicy/Layer";
+import CalendarEvent from "../../../Types/Calendar/CalendarEvent";
+import RestrictionTimes, {
+  RestrictionType,
+} from "../../../Types/OnCallDutyPolicy/RestrictionTimes";
+import Recurring from "../../../Types/Events/Recurring";
+import OneUptimeDate from "../../../Types/Date";
+import User from "../../../Models/DatabaseModels/User";
+import EventInterval from "../../../Types/Events/EventInterval";
+import PositiveNumber from "../../../Types/PositiveNumber";
+import moment from "moment-timezone";
+
+// Documented User mock pattern (id.toString() returns the title used by events).
+function user(id: string): User {
+  return {
+    id: {
+      toString: (): string => {
+        return id;
+      },
+    } as any,
+  } as User;
+}
+
+function noRestriction(): RestrictionTimes {
+  const r: RestrictionTimes = new RestrictionTimes();
+  r.restictionType = RestrictionType.None;
+  r.dayRestrictionTimes = null;
+  return r;
+}
+
+const NY: string = "America/New_York";
+const KOLKATA: string = "Asia/Kolkata";
+
+// A Monday 00:00 UTC, far from any DST transition for Day/Week horizons.
+const FIXED_START: Date = OneUptimeDate.fromString("2025-01-06T00:00:00.000Z");
+
+interface Cfg {
+  name: string;
+  intervalType: EventInterval;
+  count: number;
+  userIds: string[];
+  timezone: string | undefined;
+  start: Date;
+}
+
+/*
+ * Calendar-unit stepping that mirrors the engine (Hour absolute; others honor
+ * the schedule zone across DST, exactly like moveHandsOffTimeAfterCurrentEventStartTime).
+ */
+function addUnits(
+  date: Date,
+  units: number,
+  intervalType: EventInterval,
+  tz: string | undefined,
+): Date {
+  switch (intervalType) {
+    case EventInterval.Hour:
+      return OneUptimeDate.addRemoveHours(date, units);
+    case EventInterval.Day:
+      return OneUptimeDate.addRemoveDays(date, units, tz);
+    case EventInterval.Week:
+      return OneUptimeDate.addRemoveWeeks(date, units, tz);
+    case EventInterval.Month:
+      return OneUptimeDate.addRemoveMonths(date, units, tz);
+    case EventInterval.Year:
+      return OneUptimeDate.addRemoveYears(date, units, tz);
+    default:
+      return OneUptimeDate.addRemoveDays(date, units, tz);
+  }
+}
+
+function rotationOf(cfg: Cfg): Recurring {
+  const rot: Recurring = new Recurring();
+  rot.intervalType = cfg.intervalType;
+  rot.intervalCount = new PositiveNumber(cfg.count);
+  return rot;
+}
+
+function layerOf(cfg: Cfg, handoff?: Date): LayerProps {
+  const rot: Recurring = rotationOf(cfg);
+  return {
+    users: cfg.userIds.map(user),
+    startDateTimeOfLayer: cfg.start,
+    restrictionTimes: noRestriction(),
+    handOffTime: handoff ?? Recurring.getNextDateInterval(cfg.start, rot),
+    rotation: rot,
+    timezone: cfg.timezone,
+  };
+}
+
+// Target number of full-period events to expand per interval (bounds horizon).
+const NUM_FULL: Record<EventInterval, number> = {
+  [EventInterval.Hour]: 26,
+  [EventInterval.Day]: 26,
+  [EventInterval.Week]: 20,
+  [EventInterval.Month]: 16,
+  [EventInterval.Year]: 12,
+};
+
+/*
+ * Expand `numFull` full-period events from the layer start. The horizon end is
+ * pushed several periods past the target so the returned slice is entirely
+ * full periods whose end timestamps are REAL engine boundaries (the trailing
+ * artifact event that getEvents can emit when the window end lands on a
+ * boundary, if any, falls beyond the slice and is discarded).
+ */
+function expandFull(cfg: Cfg, numFull: number): CalendarEvent[] {
+  const layer: LayerProps = layerOf(cfg);
+  const util: LayerUtil = new LayerUtil();
+  const horizonEnd: Date = addUnits(
+    cfg.start,
+    (numFull + 6) * cfg.count,
+    cfg.intervalType,
+    cfg.timezone,
+  );
+  const events: CalendarEvent[] = util.getEvents({
+    ...layer,
+    calendarStartDate: cfg.start,
+    calendarEndDate: horizonEnd,
+  });
+  return events.slice(0, numFull);
+}
+
+function titleIndex(cfg: Cfg, title: string): number {
+  return cfg.userIds.indexOf(title);
+}
+
+// An interior (strictly off-boundary) instant of an event, at fraction f in (0,1).
+function interiorInstant(e: CalendarEvent, f: number): Date {
+  const span: number = e.end.getTime() - e.start.getTime();
+  return new Date(e.start.getTime() + Math.floor(f * span));
+}
+
+// ---- invariant checkers (return human-readable problems; empty == pass) ----
+
+function contiguityProblems(events: CalendarEvent[]): string[] {
+  const problems: string[] = [];
+  for (let i: number = 0; i < events.length; i++) {
+    const e: CalendarEvent = events[i]!;
+    if (!OneUptimeDate.isAfter(e.end, e.start)) {
+      problems.push(
+        `event ${i} non-positive length ${e.start.toISOString()}->${e.end.toISOString()}`,
+      );
+    }
+    if (i > 0) {
+      const prev: CalendarEvent = events[i - 1]!;
+      const gapSeconds: number = OneUptimeDate.getSecondsBetweenTwoDates(
+        prev.end,
+        e.start,
+      );
+      // exactly 1s handoff gap => no overlap (would be <=0) and no gap (>1).
+      if (gapSeconds !== 1) {
+        problems.push(
+          `event ${i} handoff gap ${gapSeconds}s (expected 1) prevEnd=${prev.end.toISOString()} start=${e.start.toISOString()}`,
+        );
+      }
+    }
+  }
+  return problems;
+}
+
+function orderProblems(
+  events: CalendarEvent[],
+  cfg: Cfg,
+  expectedFirstIndex: number | undefined,
+): string[] {
+  const problems: string[] = [];
+  const k: number = cfg.userIds.length;
+  if (events.length === 0) {
+    return problems;
+  }
+  const idx0: number = titleIndex(cfg, events[0]!.title);
+  if (idx0 < 0) {
+    problems.push(`event 0 unknown title ${events[0]!.title}`);
+    return problems;
+  }
+  if (expectedFirstIndex !== undefined && idx0 !== expectedFirstIndex) {
+    problems.push(`first user index ${idx0} != expected ${expectedFirstIndex}`);
+  }
+  for (let i: number = 1; i < events.length; i++) {
+    const idx: number = titleIndex(cfg, events[i]!.title);
+    const expected: number = (idx0 + i) % k;
+    if (idx !== expected) {
+      problems.push(
+        `event ${i} user index ${idx} != expected ${expected} (title ${events[i]!.title})`,
+      );
+    }
+  }
+  return problems;
+}
+
+function fairnessProblems(events: CalendarEvent[], cfg: Cfg): string[] {
+  const problems: string[] = [];
+  const counts: Map<string, number> = new Map<string, number>();
+  for (const e of events) {
+    counts.set(e.title, (counts.get(e.title) || 0) + 1);
+    if (titleIndex(cfg, e.title) < 0) {
+      problems.push(`unexpected on-call title ${e.title}`);
+    }
+  }
+  const values: number[] = Array.from(counts.values());
+  if (values.length > 0) {
+    const max: number = Math.max(...values);
+    const min: number = Math.min(...values);
+    if (max - min > 1) {
+      problems.push(`shift-count spread ${min}..${max} exceeds 1`);
+    }
+  }
+  // Over a horizon >= roster size, every user must take a turn.
+  if (events.length >= cfg.userIds.length) {
+    for (const id of cfg.userIds) {
+      if (!counts.has(id)) {
+        problems.push(`user ${id} never on-call over ${events.length} periods`);
+      }
+    }
+  }
+  return problems;
+}
+
+// ---------------------------- matrix ----------------------------
+
+const INTERVALS: EventInterval[] = [
+  EventInterval.Hour,
+  EventInterval.Day,
+  EventInterval.Week,
+  EventInterval.Month,
+  EventInterval.Year,
+];
+const COUNTS: number[] = [1, 2, 3];
+const USER_SETS: string[][] = [
+  ["A"],
+  ["A", "B"],
+  ["A", "B", "C"],
+  ["A", "B", "C", "D", "E"],
+];
+const TIMEZONES: (string | undefined)[] = [undefined, NY, KOLKATA];
+
+function buildMatrix(): Cfg[] {
+  const cfgs: Cfg[] = [];
+  for (const it of INTERVALS) {
+    for (const count of COUNTS) {
+      for (const users of USER_SETS) {
+        for (const tz of TIMEZONES) {
+          cfgs.push({
+            name: `${count}x${it} users=${users.length} tz=${tz ?? "local"}`,
+            intervalType: it,
+            count,
+            userIds: users,
+            timezone: tz,
+            start: FIXED_START,
+          });
+        }
+      }
+    }
+  }
+  return cfgs;
+}
+
+const MATRIX: Cfg[] = buildMatrix();
+
+/*
+ * ================================================================
+ * (a)(b)(c) contiguity + rotation order + fairness, window AT layer start.
+ * ================================================================
+ */
+describe("Unrestricted rotation: 24/7 contiguity + order + fairness (window AT layer start)", () => {
+  for (const cfg of MATRIX) {
+    it(`${cfg.name}`, () => {
+      const numFull: number = NUM_FULL[cfg.intervalType];
+      const events: CalendarEvent[] = expandFull(cfg, numFull);
+
+      // Sanity: we actually got the requested number of full events.
+      expect(events.length).toBe(numFull);
+
+      // (a) contiguity / positive length / no gaps or overlaps.
+      expect({ cfg: cfg.name, problems: contiguityProblems(events) }).toEqual({
+        cfg: cfg.name,
+        problems: [],
+      });
+
+      // (b) rotation order begins at the first user and never skips/repeats.
+      expect({
+        cfg: cfg.name,
+        problems: orderProblems(events, cfg, 0),
+      }).toEqual({ cfg: cfg.name, problems: [] });
+
+      // (c) fairness across the roster.
+      expect({
+        cfg: cfg.name,
+        problems: fairnessProblems(events, cfg),
+      }).toEqual({ cfg: cfg.name, problems: [] });
+
+      // The layer start owns the first period.
+      expect(events[0]!.start.getTime()).toBe(cfg.start.getTime());
+      // Single-user rotations are always that user.
+      if (cfg.userIds.length === 1) {
+        expect(
+          events.every((e: CalendarEvent) => {
+            return e.title === "A";
+          }),
+        ).toBe(true);
+      }
+    });
+  }
+});
+
+/*
+ * ================================================================
+ * (a)(b) contiguity + consecutive order for a window that starts PARTWAY
+ * through a period (the windowed/live path). First event is clamped to the
+ * window start and carries the correct in-progress user.
+ * ================================================================
+ */
+describe("Unrestricted rotation: contiguity + order for a PARTWAY (windowed) calendar start", () => {
+  for (const cfg of MATRIX) {
+    it(`${cfg.name}`, () => {
+      const numFull: number = NUM_FULL[cfg.intervalType];
+      const full: CalendarEvent[] = expandFull(cfg, numFull);
+
+      // Start partway through period p; span M subsequent periods.
+      const p: number = Math.min(3, numFull - 8);
+      const startIdx: number = p < 0 ? 0 : p;
+      const spanPeriods: number = Math.min(12, numFull - startIdx - 2);
+
+      const windowStart: Date = interiorInstant(full[startIdx]!, 0.4);
+      const windowEnd: Date = interiorInstant(
+        full[startIdx + spanPeriods]!,
+        0.6,
+      );
+
+      const util: LayerUtil = new LayerUtil();
+      const events: CalendarEvent[] = util.getEvents({
+        ...layerOf(cfg),
+        calendarStartDate: windowStart,
+        calendarEndDate: windowEnd,
+      });
+
+      expect(events.length).toBeGreaterThan(0);
+
+      // First event is clamped to the window start and is the in-progress user.
+      expect(events[0]!.start.getTime()).toBe(windowStart.getTime());
+      expect(events[0]!.title).toBe(full[startIdx]!.title);
+      // ...and runs to that period's true boundary.
+      expect(events[0]!.end.getTime()).toBe(full[startIdx]!.end.getTime());
+      // Last event is clamped to the window end.
+      expect(events[events.length - 1]!.end.getTime()).toBe(
+        windowEnd.getTime(),
+      );
+
+      // (a) contiguity.
+      expect({ cfg: cfg.name, problems: contiguityProblems(events) }).toEqual({
+        cfg: cfg.name,
+        problems: [],
+      });
+
+      /*
+       * (b) consecutive rotation advancement (no skips/repeats), anchored on the
+       * in-progress user (partway start need not begin at index 0).
+       */
+      const expectedFirst: number = titleIndex(cfg, full[startIdx]!.title);
+      expect({
+        cfg: cfg.name,
+        problems: orderProblems(events, cfg, expectedFirst),
+      }).toEqual({ cfg: cfg.name, problems: [] });
+    });
+  }
+});
+
+/*
+ * ================================================================
+ * (d) windowed resolution == full-expansion cover at many OFF-boundary instants,
+ * through BOTH getEvents and getMultiLayerEvents.
+ * ================================================================
+ */
+function sampleIndices(n: number): number[] {
+  const raw: number[] = [0, 1, Math.floor(n / 2), n - 2, n - 1];
+  const seen: Set<number> = new Set<number>();
+  const out: number[] = [];
+  for (const i of raw) {
+    if (i >= 0 && i < n && !seen.has(i)) {
+      seen.add(i);
+      out.push(i);
+    }
+  }
+  return out;
+}
+
+describe("Unrestricted rotation: windowed current-user == full-expansion cover (OFF-boundary)", () => {
+  // Two off-boundary probes per sampled period (early and late in the period).
+  const FRACTIONS: number[] = [0.35, 0.72];
+
+  for (const cfg of MATRIX) {
+    it(`${cfg.name}`, () => {
+      const numFull: number = NUM_FULL[cfg.intervalType];
+      const full: CalendarEvent[] = expandFull(cfg, numFull);
+      const util: LayerUtil = new LayerUtil();
+      const problems: string[] = [];
+      const indices: number[] = sampleIndices(numFull);
+
+      for (let s: number = 0; s < indices.length; s++) {
+        const idx: number = indices[s]!;
+        const cover: CalendarEvent = full[idx]!;
+        for (const f of FRACTIONS) {
+          const at: Date = interiorInstant(cover, f);
+          // strictly interior guard.
+          if (
+            !OneUptimeDate.isAfter(at, cover.start) ||
+            !OneUptimeDate.isBefore(at, cover.end)
+          ) {
+            continue;
+          }
+          const windowEnd: Date = addUnits(
+            at,
+            4 * cfg.count,
+            cfg.intervalType,
+            cfg.timezone,
+          );
+
+          // getEvents windowed - the live "who is on call at `at`" path.
+          const windowed: CalendarEvent[] = util.getEvents(
+            {
+              ...layerOf(cfg),
+              calendarStartDate: at,
+              calendarEndDate: windowEnd,
+            },
+            { getNumberOfEvents: 1 },
+          );
+          if (windowed.length !== 1) {
+            problems.push(
+              `at=${at.toISOString()} getEvents returned ${windowed.length}`,
+            );
+            continue;
+          }
+          if (windowed[0]!.title !== cover.title) {
+            problems.push(
+              `at=${at.toISOString()} getEvents title ${windowed[0]!.title} != cover ${cover.title}`,
+            );
+          }
+          if (windowed[0]!.start.getTime() !== at.getTime()) {
+            problems.push(
+              `at=${at.toISOString()} getEvents start not clamped to instant (${windowed[0]!.start.toISOString()})`,
+            );
+          }
+          if (windowed[0]!.end.getTime() !== cover.end.getTime()) {
+            problems.push(
+              `at=${at.toISOString()} getEvents end ${windowed[0]!.end.toISOString()} != boundary ${cover.end.toISOString()}`,
+            );
+          }
+
+          /*
+           * getMultiLayerEvents windowed (single layer) must agree on the user.
+           * Checked once per config (first probe) to keep runtime bounded; the
+           * dedicated parity/windowed blocks below cover getMultiLayerEvents more.
+           */
+          if (s === 0 && f === FRACTIONS[0]) {
+            const multi: CalendarEvent[] = util.getMultiLayerEvents(
+              {
+                layers: [layerOf(cfg)],
+                calendarStartDate: at,
+                calendarEndDate: windowEnd,
+              },
+              { getNumberOfEvents: 1 },
+            );
+            if (multi.length !== 1 || multi[0]!.title !== cover.title) {
+              problems.push(
+                `at=${at.toISOString()} getMultiLayerEvents title ${multi[0]?.title} != cover ${cover.title}`,
+              );
+            }
+          }
+        }
+      }
+
+      expect({ cfg: cfg.name, problems }).toEqual({
+        cfg: cfg.name,
+        problems: [],
+      });
+    });
+  }
+});
+
+/*
+ * ================================================================
+ * getMultiLayerEvents structural parity + priority shadowing.
+ * ================================================================
+ */
+describe("getMultiLayerEvents: single-layer parity with getEvents (interior window)", () => {
+  const parityCfgs: Cfg[] = MATRIX.filter((c: Cfg) => {
+    return c.timezone === undefined && c.count <= 2;
+  });
+
+  for (const cfg of parityCfgs) {
+    it(`${cfg.name}`, () => {
+      const numFull: number = NUM_FULL[cfg.intervalType];
+      const full: CalendarEvent[] = expandFull(cfg, numFull);
+      /*
+       * interior window: [start, interior of a later period] => no boundary-aligned
+       * trailing artifact, so getEvents and getMultiLayerEvents must match exactly.
+       */
+      const endIdx: number = Math.min(10, numFull - 1);
+      const calEnd: Date = interiorInstant(full[endIdx]!, 0.5);
+      const util: LayerUtil = new LayerUtil();
+
+      const single: CalendarEvent[] = util.getEvents({
+        ...layerOf(cfg),
+        calendarStartDate: cfg.start,
+        calendarEndDate: calEnd,
+      });
+      const multi: CalendarEvent[] = util.getMultiLayerEvents({
+        layers: [layerOf(cfg)],
+        calendarStartDate: cfg.start,
+        calendarEndDate: calEnd,
+      });
+
+      expect(multi.length).toBe(single.length);
+      for (let i: number = 0; i < single.length; i++) {
+        expect(multi[i]!.title).toBe(single[i]!.title);
+        expect(multi[i]!.start.getTime()).toBe(single[i]!.start.getTime());
+        expect(multi[i]!.end.getTime()).toBe(single[i]!.end.getTime());
+      }
+      // And the merged output is itself contiguous.
+      expect(contiguityProblems(multi)).toEqual([]);
+    });
+  }
+});
+
+describe("getMultiLayerEvents: a 24/7 higher-priority layer fully shadows a lower-priority layer", () => {
+  it("Day x1 primary [A,B] over fallback [X,Y,Z] => only primary users, contiguous", () => {
+    const primary: Cfg = {
+      name: "primary",
+      intervalType: EventInterval.Day,
+      count: 1,
+      userIds: ["A", "B"],
+      timezone: undefined,
+      start: FIXED_START,
+    };
+    const fallback: Cfg = {
+      name: "fallback",
+      intervalType: EventInterval.Day,
+      count: 1,
+      userIds: ["X", "Y", "Z"],
+      timezone: undefined,
+      start: FIXED_START,
+    };
+
+    const full: CalendarEvent[] = expandFull(primary, 12);
+    const calEnd: Date = interiorInstant(full[10]!, 0.5);
+    const util: LayerUtil = new LayerUtil();
+
+    const merged: CalendarEvent[] = util.getMultiLayerEvents({
+      layers: [layerOf(primary), layerOf(fallback)],
+      calendarStartDate: FIXED_START,
+      calendarEndDate: calEnd,
+    });
+    const primaryOnly: CalendarEvent[] = util.getMultiLayerEvents({
+      layers: [layerOf(primary)],
+      calendarStartDate: FIXED_START,
+      calendarEndDate: calEnd,
+    });
+
+    // Fallback is completely shadowed by the 24/7 primary.
+    for (const e of merged) {
+      expect(["A", "B"]).toContain(e.title);
+    }
+    // Merged == primary alone.
+    expect(merged.length).toBe(primaryOnly.length);
+    for (let i: number = 0; i < merged.length; i++) {
+      expect(merged[i]!.title).toBe(primaryOnly[i]!.title);
+      expect(merged[i]!.start.getTime()).toBe(primaryOnly[i]!.start.getTime());
+      expect(merged[i]!.end.getTime()).toBe(primaryOnly[i]!.end.getTime());
+    }
+    expect(contiguityProblems(merged)).toEqual([]);
+    expect(orderProblems(merged, primary, 0)).toEqual([]);
+  });
+});
+
+/*
+ * ================================================================
+ * (e) edge cases.
+ * ================================================================
+ */
+describe("Edge cases", () => {
+  it("empty users => no events", () => {
+    const cfg: Cfg = {
+      name: "empty",
+      intervalType: EventInterval.Day,
+      count: 1,
+      userIds: [],
+      timezone: undefined,
+      start: FIXED_START,
+    };
+    const util: LayerUtil = new LayerUtil();
+    const events: CalendarEvent[] = util.getEvents({
+      ...layerOf(cfg),
+      calendarStartDate: FIXED_START,
+      calendarEndDate: OneUptimeDate.addRemoveDays(FIXED_START, 10),
+    });
+    expect(events).toEqual([]);
+    const multi: CalendarEvent[] = util.getMultiLayerEvents({
+      layers: [layerOf(cfg)],
+      calendarStartDate: FIXED_START,
+      calendarEndDate: OneUptimeDate.addRemoveDays(FIXED_START, 10),
+    });
+    expect(multi).toEqual([]);
+  });
+
+  it("calendar end strictly before layer start => no events", () => {
+    for (const it of INTERVALS) {
+      const cfg: Cfg = {
+        name: `calEndBefore-${it}`,
+        intervalType: it,
+        count: 1,
+        userIds: ["A", "B"],
+        timezone: undefined,
+        start: FIXED_START,
+      };
+      const util: LayerUtil = new LayerUtil();
+      const events: CalendarEvent[] = util.getEvents({
+        ...layerOf(cfg),
+        calendarStartDate: OneUptimeDate.addRemoveDays(FIXED_START, -30),
+        calendarEndDate: OneUptimeDate.addRemoveDays(FIXED_START, -5),
+      });
+      expect(events).toEqual([]);
+    }
+  });
+
+  it("calendar window entirely before layer start (both ends before) => no events", () => {
+    const cfg: Cfg = {
+      name: "before",
+      intervalType: EventInterval.Hour,
+      count: 2,
+      userIds: ["A", "B", "C"],
+      timezone: undefined,
+      start: FIXED_START,
+    };
+    const util: LayerUtil = new LayerUtil();
+    const events: CalendarEvent[] = util.getEvents({
+      ...layerOf(cfg),
+      calendarStartDate: OneUptimeDate.addRemoveHours(FIXED_START, -50),
+      calendarEndDate: OneUptimeDate.addRemoveHours(FIXED_START, -1),
+    });
+    expect(events).toEqual([]);
+  });
+
+  it("single user => always that user across every interval/count", () => {
+    for (const it of INTERVALS) {
+      for (const count of COUNTS) {
+        const cfg: Cfg = {
+          name: `single-${count}x${it}`,
+          intervalType: it,
+          count,
+          userIds: ["SOLO"],
+          timezone: undefined,
+          start: FIXED_START,
+        };
+        const events: CalendarEvent[] = expandFull(cfg, 10);
+        expect(events.length).toBe(10);
+        expect(
+          events.every((e: CalendarEvent) => {
+            return e.title === "SOLO";
+          }),
+        ).toBe(true);
+        expect(contiguityProblems(events)).toEqual([]);
+      }
+    }
+  });
+
+  it("grid-aligned degenerate handoffs (== start, and before start) equal the natural rotation", () => {
+    const intervals: EventInterval[] = [
+      EventInterval.Hour,
+      EventInterval.Day,
+      EventInterval.Week,
+      EventInterval.Month,
+    ];
+    for (const it of intervals) {
+      for (const count of [1, 2]) {
+        const cfg: Cfg = {
+          name: `${count}x${it}`,
+          intervalType: it,
+          count,
+          userIds: ["A", "B", "C"],
+          timezone: undefined,
+          start: FIXED_START,
+        };
+        // interior end derived from the natural expansion (no boundary artifact).
+        const naturalFull: CalendarEvent[] = expandFull(cfg, 10);
+        const calEnd: Date = interiorInstant(naturalFull[8]!, 0.5);
+        const util: LayerUtil = new LayerUtil();
+
+        const natural: CalendarEvent[] = util.getEvents({
+          ...layerOf(cfg),
+          calendarStartDate: cfg.start,
+          calendarEndDate: calEnd,
+        });
+
+        /*
+         * handoff == layer start (k=0), and grid-aligned handoffs before the
+         * layer start (k = -1, -2, -3 periods) must produce the SAME rotation.
+         */
+        for (const k of [0, 1, 2, 3]) {
+          const handoff: Date = addUnits(
+            cfg.start,
+            -k * count,
+            it,
+            cfg.timezone,
+          );
+          const events: CalendarEvent[] = util.getEvents({
+            ...layerOf(cfg, handoff),
+            calendarStartDate: cfg.start,
+            calendarEndDate: calEnd,
+          });
+          expect(events.length).toBe(natural.length);
+          for (let i: number = 0; i < natural.length; i++) {
+            expect(events[i]!.title).toBe(natural[i]!.title);
+            expect(events[i]!.start.getTime()).toBe(
+              natural[i]!.start.getTime(),
+            );
+            expect(events[i]!.end.getTime()).toBe(natural[i]!.end.getTime());
+          }
+        }
+      }
+    }
+  });
+
+  it("NOTE: current behavior - getEvents emits a trailing negative-length event when the window end lands exactly on a rotation boundary; getMultiLayerEvents filters it out", () => {
+    const cfg: Cfg = {
+      name: "boundary",
+      intervalType: EventInterval.Day,
+      count: 1,
+      userIds: ["A", "B"],
+      timezone: undefined,
+      start: FIXED_START,
+    };
+    const util: LayerUtil = new LayerUtil();
+    // 3 days == exactly a rotation boundary for a daily x1 rotation.
+    const calEnd: Date = OneUptimeDate.addRemoveDays(FIXED_START, 3);
+
+    const raw: CalendarEvent[] = util.getEvents({
+      ...layerOf(cfg),
+      calendarStartDate: FIXED_START,
+      calendarEndDate: calEnd,
+    });
+    const last: CalendarEvent = raw[raw.length - 1]!;
+    /*
+     * NOTE: current behavior - the final event is inverted (end 1s before start).
+     * This is an internal artifact; both production consumers go through
+     * getMultiLayerEvents, which removes it (see assertion below). Not a
+     * user-observable defect, so it is documented rather than reported.
+     */
+    expect(OneUptimeDate.isBefore(last.end, last.start)).toBe(true);
+
+    const multi: CalendarEvent[] = util.getMultiLayerEvents({
+      layers: [layerOf(cfg)],
+      calendarStartDate: FIXED_START,
+      calendarEndDate: calEnd,
+    });
+    // No inverted / zero-length events survive the merge.
+    for (const e of multi) {
+      expect(OneUptimeDate.isAfter(e.end, e.start)).toBe(true);
+    }
+    expect(contiguityProblems(multi)).toEqual([]);
+  });
+});
+
+/*
+ * ================================================================
+ * DST / server-vs-schedule divergence (America/New_York). Run also under TZ=UTC.
+ * ================================================================
+ */
+describe("America/New_York rotation across DST transitions (schedule-zone wall-clock preserved)", () => {
+  // 2025-03-08 00:00 New York (EST) - one day before US spring-forward.
+  const SPRING_START: Date = moment.tz("2025-03-08 00:00", NY).toDate();
+  // 2025-11-01 00:00 New York (EDT) - one day before US fall-back.
+  const FALL_START: Date = moment.tz("2025-11-01 00:00", NY).toDate();
+
+  const scenarios: {
+    label: string;
+    start: Date;
+    it: EventInterval;
+    count: number;
+  }[] = [
+    {
+      label: "spring daily x1",
+      start: SPRING_START,
+      it: EventInterval.Day,
+      count: 1,
+    },
+    {
+      label: "spring daily x2",
+      start: SPRING_START,
+      it: EventInterval.Day,
+      count: 2,
+    },
+    {
+      label: "spring weekly x1",
+      start: SPRING_START,
+      it: EventInterval.Week,
+      count: 1,
+    },
+    {
+      label: "spring hourly x1",
+      start: SPRING_START,
+      it: EventInterval.Hour,
+      count: 1,
+    },
+    {
+      label: "fall daily x1",
+      start: FALL_START,
+      it: EventInterval.Day,
+      count: 1,
+    },
+    {
+      label: "fall daily x2",
+      start: FALL_START,
+      it: EventInterval.Day,
+      count: 2,
+    },
+    {
+      label: "fall weekly x1",
+      start: FALL_START,
+      it: EventInterval.Week,
+      count: 1,
+    },
+    {
+      label: "fall hourly x1",
+      start: FALL_START,
+      it: EventInterval.Hour,
+      count: 1,
+    },
+  ];
+
+  for (const s of scenarios) {
+    it(`${s.label}: contiguous, ordered, and windowed==cover across the transition`, () => {
+      const cfg: Cfg = {
+        name: s.label,
+        intervalType: s.it,
+        count: s.count,
+        userIds: ["A", "B", "C"],
+        timezone: NY,
+        start: s.start,
+      };
+      const numFull: number = 12;
+      const full: CalendarEvent[] = expandFull(cfg, numFull);
+
+      expect(full.length).toBe(numFull);
+      // Contiguity holds structurally even across the 23h/25h DST day.
+      expect(contiguityProblems(full)).toEqual([]);
+      // Rotation order is unaffected by DST.
+      expect(orderProblems(full, cfg, 0)).toEqual([]);
+      expect(fairnessProblems(full, cfg)).toEqual([]);
+
+      if (s.it === EventInterval.Day && s.count === 1) {
+        /*
+         * Prove tz-aware (wall-clock) stepping is in effect rather than fixed
+         * 24h arithmetic: the daily rotation period that spans the DST
+         * transition has a different absolute length (23h spring / 25h fall)
+         * than a normal 24h period. (We do NOT assert the boundary lands on a
+         * specific NY wall-clock time: the FIRST handoff is computed zone-naive
+         * by Recurring.getNextDateInterval, so the boundary grid may be offset
+         * by the DST hour - that is the documented server-vs-schedule behavior.)
+         */
+        const daySpans: Set<number> = new Set<number>();
+        for (const e of full) {
+          daySpans.add(OneUptimeDate.getSecondsBetweenTwoDates(e.start, e.end));
+        }
+        expect(daySpans.size).toBeGreaterThan(1);
+        // Every period is within +/- 1h of a nominal 24h day.
+        for (const span of Array.from(daySpans)) {
+          expect(Math.abs(span - 86400)).toBeLessThanOrEqual(3600 + 1);
+        }
+      }
+
+      // Windowed==cover across the transition (OFF-boundary instants).
+      const util: LayerUtil = new LayerUtil();
+      const problems: string[] = [];
+      for (let idx: number = 0; idx < full.length; idx++) {
+        const cover: CalendarEvent = full[idx]!;
+        for (const f of [0.25, 0.75]) {
+          const at: Date = interiorInstant(cover, f);
+          if (
+            !OneUptimeDate.isAfter(at, cover.start) ||
+            !OneUptimeDate.isBefore(at, cover.end)
+          ) {
+            continue;
+          }
+          const windowEnd: Date = addUnits(
+            at,
+            4 * cfg.count,
+            cfg.intervalType,
+            cfg.timezone,
+          );
+          const windowed: CalendarEvent[] = util.getEvents(
+            {
+              ...layerOf(cfg),
+              calendarStartDate: at,
+              calendarEndDate: windowEnd,
+            },
+            { getNumberOfEvents: 1 },
+          );
+          if (windowed[0]?.title !== cover.title) {
+            problems.push(
+              `at=${at.toISOString()} title ${windowed[0]?.title} != ${cover.title}`,
+            );
+          }
+          if (windowed[0]!.end.getTime() !== cover.end.getTime()) {
+            problems.push(
+              `at=${at.toISOString()} end mismatch ${windowed[0]!.end.toISOString()} vs ${cover.end.toISOString()}`,
+            );
+          }
+        }
+      }
+      expect({ label: s.label, problems }).toEqual({
+        label: s.label,
+        problems: [],
+      });
+    });
+  }
+});