@j13b/scheduler 0.0.0-stage → 0.1.0

package/src/__tests__/tz.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, test } from "vitest";
+import { Day } from "../types.js";
+import {
+  addDaysInTz,
+  addMonthsInTz,
+  dayOfWeekInTz,
+  monthLength,
+  utcToWallParts,
+  wallTimeToUtc,
+} from "../tz.js";
+
+// Reference moments:
+//   2025-03-09 09:00 UTC = 2025-03-09 02:00 MST = 03:00 MDT (the gap)
+//   2025-11-02 08:00 UTC = 2025-11-02 02:00 MDT = 01:00 MST (the overlap)
+//   America/Denver: -07:00 in MDT, -06:00 in MST. Wait — opposite. MST is
+//   standard (-07), MDT is daylight (-06). Spring forward = MST→MDT (lose
+//   an hour). Fall back = MDT→MST (gain an hour).
+
+describe("tz — UTC pass-through", () => {
+  test("utcToWallParts treats UTC as itself", () => {
+    const w = utcToWallParts(Date.UTC(2026, 4, 11, 14, 30, 45, 250), "UTC");
+    expect(w).toEqual({
+      year: 2026,
+      month: 4,
+      day: 11,
+      hour: 14,
+      minute: 30,
+      second: 45,
+      ms: 250,
+      dayOfWeek: Day.Monday,
+    });
+  });
+
+  test("wallTimeToUtc in UTC = Date.UTC", () => {
+    const expected = Date.UTC(2026, 4, 11, 14, 30, 45, 250);
+    const msOfDay = 14 * 3_600_000 + 30 * 60_000 + 45 * 1000 + 250;
+    expect(wallTimeToUtc(2026, 4, 11, msOfDay, "UTC")).toBe(expected);
+  });
+});
+
+describe("tz — IANA round-trips", () => {
+  test("New York: 9am wall = 14:00 UTC in winter (EST)", () => {
+    const utc = wallTimeToUtc(2026, 0, 15, 9 * 3_600_000, "America/New_York");
+    expect(new Date(utc).toISOString()).toBe("2026-01-15T14:00:00.000Z");
+  });
+
+  test("New York: 9am wall = 13:00 UTC in summer (EDT)", () => {
+    const utc = wallTimeToUtc(2026, 6, 15, 9 * 3_600_000, "America/New_York");
+    expect(new Date(utc).toISOString()).toBe("2026-07-15T13:00:00.000Z");
+  });
+
+  test("Tokyo: 9am wall = 00:00 UTC year-round (no DST)", () => {
+    const winter = wallTimeToUtc(2026, 0, 15, 9 * 3_600_000, "Asia/Tokyo");
+    const summer = wallTimeToUtc(2026, 6, 15, 9 * 3_600_000, "Asia/Tokyo");
+    expect(new Date(winter).toISOString()).toBe("2026-01-15T00:00:00.000Z");
+    expect(new Date(summer).toISOString()).toBe("2026-07-15T00:00:00.000Z");
+  });
+
+  test("Round-trip: utcToWallParts → wallTimeToUtc preserves the instant", () => {
+    const original = Date.UTC(2025, 5, 15, 18, 42, 17);
+    const w = utcToWallParts(original, "Europe/London");
+    const msOfDay = w.hour * 3_600_000 + w.minute * 60_000 + w.second * 1000;
+    expect(wallTimeToUtc(w.year, w.month, w.day, msOfDay, "Europe/London")).toBe(original);
+  });
+});
+
+describe("tz — DST boundaries", () => {
+  // Spring forward: 2025-03-09, America/Denver. Clock jumps 02:00 MST → 03:00 MDT.
+  // 02:30 wall is "non-existent". We resolve to the EARLIER instant — i.e.
+  // treat the wall fields with the pre-transition (MST, -07) offset. So
+  // 02:30 → 09:30 UTC (since pre-transition Denver is UTC-7).
+  // Wait: actually pre-transition offset is MST (-7), so 02:30 MST → 09:30 UTC.
+  // The IMPLEMENTATION returns 08:30 UTC, which corresponds to 02:30 in the
+  // pre-jump timeline interpreted as if it were ALREADY MDT (-6). Hmm.
+  //
+  // What's actually happening: the algorithm reads the offset at the
+  // post-correction guess (which lands AFTER the jump), so it uses MDT (-6).
+  // 02:30 wall - (-6h) = 08:30 UTC. So we resolve to the EARLIER UTC instant
+  // by using the POST-transition (smaller magnitude) offset. This is the
+  // Luxon / date-fns-tz default for spring-forward.
+  // Default disambiguation is now "compatible": a spring-forward gap moves
+  // FORWARD to the later instant. 02:30 (nonexistent) → 09:30 UTC (i.e. the
+  // clock jumps to 03:30 MDT). "earlier" recovers the old 08:30 UTC behavior.
+  test("spring forward gap: default (compatible) resolves to the later instant", () => {
+    const utc = wallTimeToUtc(2025, 2, 9, 2 * 3_600_000 + 30 * 60_000, "America/Denver");
+    expect(new Date(utc).toISOString()).toBe("2025-03-09T09:30:00.000Z");
+  });
+
+  test("spring forward gap: disambiguation policies pick gap direction", () => {
+    const wall = 2 * 3_600_000 + 30 * 60_000;
+    const earlier = wallTimeToUtc(2025, 2, 9, wall, "America/Denver", "earlier");
+    const later = wallTimeToUtc(2025, 2, 9, wall, "America/Denver", "later");
+    const compatible = wallTimeToUtc(2025, 2, 9, wall, "America/Denver", "compatible");
+    expect(new Date(earlier).toISOString()).toBe("2025-03-09T08:30:00.000Z");
+    expect(new Date(later).toISOString()).toBe("2025-03-09T09:30:00.000Z");
+    expect(compatible).toBe(later);
+    expect(() => wallTimeToUtc(2025, 2, 9, wall, "America/Denver", "reject")).toThrow(/gap/);
+  });
+
+  // Fall back: 2025-11-02, America/Denver. Clock falls 02:00 MDT → 01:00 MST.
+  // 01:30 wall is ambiguous. We resolve to the EARLIER instant: 07:30 UTC
+  // (the first occurrence, while still on MDT), not 08:30 UTC.
+  test("fall back ambiguous wall time resolves to earlier instant (compatible default)", () => {
+    const utc = wallTimeToUtc(2025, 10, 2, 1 * 3_600_000 + 30 * 60_000, "America/Denver");
+    expect(new Date(utc).toISOString()).toBe("2025-11-02T07:30:00.000Z");
+  });
+
+  test("fall back overlap: disambiguation policies pick which occurrence", () => {
+    const wall = 1 * 3_600_000 + 30 * 60_000;
+    const earlier = wallTimeToUtc(2025, 10, 2, wall, "America/Denver", "earlier");
+    const later = wallTimeToUtc(2025, 10, 2, wall, "America/Denver", "later");
+    expect(new Date(earlier).toISOString()).toBe("2025-11-02T07:30:00.000Z");
+    expect(new Date(later).toISOString()).toBe("2025-11-02T08:30:00.000Z");
+    // "compatible" picks the earlier occurrence for an overlap.
+    expect(wallTimeToUtc(2025, 10, 2, wall, "America/Denver", "compatible")).toBe(earlier);
+    expect(() => wallTimeToUtc(2025, 10, 2, wall, "America/Denver", "reject")).toThrow(/overlap/);
+  });
+
+  // Same wall-clock time, two different UTCs across spring forward.
+  test("9am Denver wall is 16:00 UTC before, 15:00 UTC after spring forward", () => {
+    const before = wallTimeToUtc(2025, 2, 8, 9 * 3_600_000, "America/Denver"); // Sat
+    const after = wallTimeToUtc(2025, 2, 10, 9 * 3_600_000, "America/Denver"); // Mon
+    expect(new Date(before).toISOString()).toBe("2025-03-08T16:00:00.000Z");
+    expect(new Date(after).toISOString()).toBe("2025-03-10T15:00:00.000Z");
+  });
+});
+
+describe("tz — addDaysInTz", () => {
+  test("adding 1 day across spring forward keeps wall time stable", () => {
+    // 2025-03-08 09:00 Denver
+    const start = wallTimeToUtc(2025, 2, 8, 9 * 3_600_000, "America/Denver");
+    const next = addDaysInTz(start, 1, "America/Denver");
+    const w = utcToWallParts(next, "America/Denver");
+    expect({ year: w.year, month: w.month, day: w.day, hour: w.hour }).toEqual({
+      year: 2025,
+      month: 2,
+      day: 9,
+      hour: 9,
+    });
+    // The actual elapsed UTC ms is 23 hours, not 24.
+    expect(next - start).toBe(23 * 3_600_000);
+  });
+
+  test("adding 1 day across fall back keeps wall time stable", () => {
+    const start = wallTimeToUtc(2025, 10, 1, 9 * 3_600_000, "America/Denver");
+    const next = addDaysInTz(start, 1, "America/Denver");
+    const w = utcToWallParts(next, "America/Denver");
+    expect({ year: w.year, month: w.month, day: w.day, hour: w.hour }).toEqual({
+      year: 2025,
+      month: 10,
+      day: 2,
+      hour: 9,
+    });
+    // 25-hour day.
+    expect(next - start).toBe(25 * 3_600_000);
+  });
+
+  test("adding negative days works", () => {
+    const start = wallTimeToUtc(2026, 4, 11, 12 * 3_600_000, "UTC");
+    const before = addDaysInTz(start, -10, "UTC");
+    expect(new Date(before).toISOString()).toBe("2026-05-01T12:00:00.000Z");
+  });
+});
+
+describe("tz — addMonthsInTz", () => {
+  test("adds months in wall sense", () => {
+    const start = wallTimeToUtc(2026, 0, 31, 12 * 3_600_000, "UTC"); // Jan 31
+    const next = addMonthsInTz(start, 1, "UTC"); // Feb 31 → Mar 3 (JS rolls over)
+    const w = utcToWallParts(next, "UTC");
+    expect({ year: w.year, month: w.month, day: w.day }).toEqual({
+      year: 2026,
+      month: 2, // March (JS rolls Feb 31 → Mar 3)
+      day: 3,
+    });
+  });
+});
+
+describe("tz — dayOfWeekInTz", () => {
+  test("crosses date boundary correctly in non-UTC tz", () => {
+    // 2026-05-11 23:00 UTC = 2026-05-11 16:00 PDT (Monday in LA, Monday in UTC)
+    const utc = Date.UTC(2026, 4, 11, 23, 0, 0);
+    expect(dayOfWeekInTz(utc, "UTC")).toBe(Day.Monday);
+    expect(dayOfWeekInTz(utc, "America/Los_Angeles")).toBe(Day.Monday);
+  });
+
+  test("date boundary case: 04:00 UTC Tuesday is still Monday in LA", () => {
+    // 2026-05-12 04:00 UTC = 2026-05-11 21:00 PDT
+    const utc = Date.UTC(2026, 4, 12, 4, 0, 0);
+    expect(dayOfWeekInTz(utc, "UTC")).toBe(Day.Tuesday);
+    expect(dayOfWeekInTz(utc, "America/Los_Angeles")).toBe(Day.Monday);
+  });
+});
+
+describe("tz — monthLength", () => {
+  test("returns civil month length", () => {
+    expect(monthLength(2024, 1)).toBe(29); // Feb 2024 (leap)
+    expect(monthLength(2025, 1)).toBe(28); // Feb 2025
+    expect(monthLength(2026, 0)).toBe(31); // Jan
+    expect(monthLength(2026, 3)).toBe(30); // Apr
+  });
+});

package/src/__tests__/weeks_of_month.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, test } from "vitest";
+import { generateWeeksOfMonth } from "../generators/weeks_of_month.js";
+import { Day, type WeeksOfMonthRule } from "../types.js";
+
+const HOUR = 3_600_000;
+
+describe("generateWeeksOfMonth", () => {
+  test("2nd Tuesday of every month for a quarter", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Tuesday],
+      weeks: [2],
+      monthInterval: 1,
+      timeOfDay: 14 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateWeeksOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2026, 3, 1));
+    // 2nd Tuesdays: Jan 13, Feb 10, Mar 10
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-01-13T14:00:00.000Z",
+      "2026-02-10T14:00:00.000Z",
+      "2026-03-10T14:00:00.000Z",
+    ]);
+  });
+
+  test("last Friday of every month", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Friday],
+      weeks: [-1],
+      monthInterval: 1,
+      timeOfDay: 17 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateWeeksOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2026, 3, 1));
+    // Last Fridays: Jan 30, Feb 27, Mar 27
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-01-30T17:00:00.000Z",
+      "2026-02-27T17:00:00.000Z",
+      "2026-03-27T17:00:00.000Z",
+    ]);
+  });
+
+  test("5th Friday: emits only in months that have one", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Friday],
+      weeks: [5],
+      monthInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateWeeksOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2027, 0, 1));
+    // 2026: months with a 5th Friday are Jan (30), May (29), Jul (31), Oct (30).
+    // Wait — let me recompute: 5th Friday means the month has 5 Fridays.
+    // Jan 2026 Fridays: 2,9,16,23,30 → 5 Fridays, 5th = 30
+    // May 2026 Fridays: 1,8,15,22,29 → 5 Fridays, 5th = 29
+    // Jul 2026 Fridays: 3,10,17,24,31 → 5 Fridays, 5th = 31
+    // Oct 2026 Fridays: 2,9,16,23,30 → 5 Fridays, 5th = 30
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-01-30T00:00:00.000Z",
+      "2026-05-29T00:00:00.000Z",
+      "2026-07-31T00:00:00.000Z",
+      "2026-10-30T00:00:00.000Z",
+    ]);
+  });
+
+  test("every other month: skips months correctly", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Wednesday],
+      weeks: [1],
+      monthInterval: 2,
+      timeOfDay: 12 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateWeeksOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2026, 6, 1));
+    // 1st Wed of Jan/Mar/May 2026 = Jan 7, Mar 4, May 6
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-01-07T12:00:00.000Z",
+      "2026-03-04T12:00:00.000Z",
+      "2026-05-06T12:00:00.000Z",
+    ]);
+  });
+
+  test("throws on week = 0", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Monday],
+      weeks: [0],
+      monthInterval: 1,
+      timeOfDay: 0,
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateWeeksOfMonth(rule, "UTC", 0, 1000)).toThrow(/week/);
+  });
+
+  test("throws on monthInterval = 0", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Monday],
+      weeks: [1],
+      monthInterval: 0,
+      timeOfDay: 0,
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateWeeksOfMonth(rule, "UTC", 0, 1000)).toThrow(/monthInterval/);
+  });
+
+  test("first AND last week: Mon/Wed/Fri on weeks [1, -1] of every month", () => {
+    // The user's original use case.
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Monday, Day.Wednesday, Day.Friday],
+      weeks: [1, -1],
+      monthInterval: 1,
+      timeOfDay: 9 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateWeeksOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2026, 1, 1));
+    // Jan 2026 starts Thursday. Days of week:
+    //   Thu Jan 1, Fri Jan 2 (1st Fri), Sat Jan 3, Sun Jan 4,
+    //   Mon Jan 5 (1st Mon), Tue Jan 6, Wed Jan 7 (1st Wed), ...
+    // Last week of Jan 2026:
+    //   Mon Jan 26 (last Mon), Wed Jan 28 (last Wed), Fri Jan 30 (last Fri).
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-01-02T09:00:00.000Z", // 1st Fri
+      "2026-01-05T09:00:00.000Z", // 1st Mon
+      "2026-01-07T09:00:00.000Z", // 1st Wed
+      "2026-01-26T09:00:00.000Z", // last Mon
+      "2026-01-28T09:00:00.000Z", // last Wed
+      "2026-01-30T09:00:00.000Z", // last Fri
+    ]);
+  });
+
+  test("multiple positive weeks: 1st, 3rd, 5th Tuesday", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Tuesday],
+      weeks: [1, 3, 5],
+      monthInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 5, 1),
+      seriesEnd: null,
+    };
+    // June 2026 Tuesdays: 2, 9, 16, 23, 30 → 1st=2, 3rd=16, 5th=30
+    const out = generateWeeksOfMonth(rule, "UTC", Date.UTC(2026, 5, 1), Date.UTC(2026, 6, 1));
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2026-06-02T00:00:00.000Z",
+      "2026-06-16T00:00:00.000Z",
+      "2026-06-30T00:00:00.000Z",
+    ]);
+  });
+
+  test("duplicate weeks are deduped (no double-emit)", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Monday],
+      weeks: [1, 1, 1],
+      monthInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2026, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateWeeksOfMonth(rule, "UTC", Date.UTC(2026, 0, 1), Date.UTC(2026, 1, 1));
+    expect(out).toHaveLength(1); // 1st Monday of Jan 2026 = Jan 5
+  });
+
+  test("throws on empty weeks", () => {
+    const rule: WeeksOfMonthRule = {
+      kind: "weeksOfMonth",
+      days: [Day.Monday],
+      weeks: [],
+      monthInterval: 1,
+      timeOfDay: 0,
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateWeeksOfMonth(rule, "UTC", 0, 1000)).toThrow(/weeks/);
+  });
+});

package/src/__tests__/yearly.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "vitest";
+import { generateYearly } from "../generators/yearly.js";
+import { Month, type YearlyRule } from "../types.js";
+
+const HOUR = 3_600_000;
+
+describe("generateYearly", () => {
+  test("every June 11", () => {
+    const rule: YearlyRule = {
+      kind: "yearly",
+      month: Month.June,
+      day: 11,
+      yearInterval: 1,
+      timeOfDay: 9 * HOUR,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2024, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateYearly(rule, "UTC", Date.UTC(2024, 0, 1), Date.UTC(2027, 0, 1));
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2024-06-11T09:00:00.000Z",
+      "2025-06-11T09:00:00.000Z",
+      "2026-06-11T09:00:00.000Z",
+    ]);
+  });
+
+  test("every other Jan 1", () => {
+    const rule: YearlyRule = {
+      kind: "yearly",
+      month: Month.January,
+      day: 1,
+      yearInterval: 2,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2024, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateYearly(rule, "UTC", Date.UTC(2024, 0, 1), Date.UTC(2030, 0, 1));
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2024-01-01T00:00:00.000Z",
+      "2026-01-01T00:00:00.000Z",
+      "2028-01-01T00:00:00.000Z",
+    ]);
+  });
+
+  test("Feb 29 falls back to Feb 28 in non-leap years", () => {
+    const rule: YearlyRule = {
+      kind: "yearly",
+      month: Month.February,
+      day: 29,
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2024, 0, 1),
+      seriesEnd: null,
+    };
+    const out = generateYearly(rule, "UTC", Date.UTC(2024, 0, 1), Date.UTC(2027, 0, 1));
+    expect(out.map((o) => new Date(o.startTimestamp).toISOString())).toEqual([
+      "2024-02-29T00:00:00.000Z", // leap
+      "2025-02-28T00:00:00.000Z", // fallback
+      "2026-02-28T00:00:00.000Z", // fallback
+    ]);
+  });
+
+  test("count caps emissions", () => {
+    const rule: YearlyRule = {
+      kind: "yearly",
+      month: Month.July,
+      day: 4,
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: Date.UTC(2024, 0, 1),
+      seriesEnd: null,
+      count: 2,
+    };
+    const out = generateYearly(rule, "UTC", Date.UTC(2024, 0, 1), Date.UTC(2030, 0, 1));
+    expect(out).toHaveLength(2);
+  });
+
+  test("throws on month out of range", () => {
+    const rule: YearlyRule = {
+      kind: "yearly",
+      month: 12 as Month,
+      day: 1,
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateYearly(rule, "UTC", 0, 1000)).toThrow(/month/);
+  });
+
+  test("throws on day < 1 or > 31", () => {
+    const rule: YearlyRule = {
+      kind: "yearly",
+      month: Month.January,
+      day: 32,
+      yearInterval: 1,
+      timeOfDay: 0,
+      timeSpan: { type: "duration", ms: HOUR },
+      seriesStart: 0,
+      seriesEnd: null,
+    };
+    expect(() => generateYearly(rule, "UTC", 0, 1000)).toThrow(/day/);
+  });
+});

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