@j13b/scheduler 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jared Barnes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @j13b/scheduler
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A timezone-aware recurrence and dispatch engine. Pure-data rule DSL, IANA timezone support, DST-aware generators, and a cron-style dispatcher.
+
+## Install
+
+```bash
+npm install @j13b/scheduler
+```
+
+## Quick start
+
+```ts
+import {
+  Scheduler,
+  InMemorySchedulerPort,
+  Dispatcher,
+  InMemoryDispatcherStore,
+  Day,
+} from "@j13b/scheduler";
+
+const port = new InMemorySchedulerPort();
+const scheduler = new Scheduler(port);
+
+await scheduler.add({
+  id: "standup",
+  timezone: "America/Denver",
+  rule: {
+    kind: "daysOfWeek",
+    days: [Day.Monday, Day.Tuesday, Day.Wednesday, Day.Thursday, Day.Friday],
+    timeOfDay: 9 * 60 * 60 * 1000, // 9:00 wall-clock
+    weekInterval: 1,
+    seriesStart: Date.UTC(2026, 0, 1),
+    seriesEnd: null, // open-ended
+  },
+  payload: { type: "standup" },
+});
+
+const dispatcher = new Dispatcher({
+  scheduler,
+  store: new InMemoryDispatcherStore(),
+  fire: async (event) => {
+    console.log(`Fire ${event.templateId} at ${new Date(event.startTimestamp).toISOString()}`);
+  },
+});
+
+await dispatcher.start();
+```
+
+## What's in the box
+
+- **Recurrence rules** — `InstantRule`, `LocalDateTimeRule`, `AnchoredRule`, `DaysOfWeekRule`, `WeeksOfMonthRule`, `MonthsOfYearRule`, `YearlyRule`, `DaysOfMonthRule`, `DaysOfYearRule`. Pure-data, JSON-serializable, exhaustive TypeScript union. The two single-occurrence kinds: `InstantRule` fires at an absolute UTC instant (timezone-independent); `LocalDateTimeRule` fires once at a wall-clock date/time resolved (DST-aware) in the template's timezone.
+- **TimeSpan** — two flavors of "how long does an occurrence last":
+  - `{ type: "duration", ms }` — fixed real-elapsed time (payroll-correct, ignores DST jumps).
+  - `{ type: "hourSpan", hours }` — wall-clock hours (calendar-correct, flexes with DST).
+- **Timezone math** — built on `Intl.DateTimeFormat` over IANA zones, zero deps for date logic. Spring-forward gaps and fall-back overlaps are resolved by a configurable per-template `disambiguation` policy (`"compatible"` default, plus `"earlier"`, `"later"`, `"reject"`, and `"skip"`), mirroring the Temporal proposal.
+- **Alterations** — per-occurrence overrides (skip, reschedule, replace).
+- **Dispatcher** — drives a Scheduler in real time; catch-up pass for missed events, resumes early when the schedule changes.
+
+## API surface
+
+See [`src/index.ts`](./src/index.ts) for the full export list. Notable types:
+
+- `RecurrenceRule` — discriminated union over the nine rule kinds.
+- `ScheduleTemplate` — `{ id, rule, timezone, disambiguation?, payload }`. `timezone` is required and validated at write time (use `"UTC"` for zone-free scheduling; it's ignored by the absolute `instant`/`anchored` rules).
+- `validateRule(rule)` — checks a rule's whole shape (every required field present, typed and in range; no fields its kind lacks) and throws an `Error` naming the field and the form it expects. `Scheduler.add`/`update` run it, so a rule from JSON or an LLM fails with a clear message instead of crashing a generator. `validateTimeSpan` and `RULE_KINDS` are exported too.
+- `ScheduledEvent` — `{ templateId, occurrenceKey, startTimestamp, endTimestamp, payload, alterationId? }`.
+- `Disambiguation` — DST-edge resolution policy: `"compatible" | "earlier" | "later" | "reject" | "skip"`.
+- `SchedulerPort` — async storage interface; an `InMemorySchedulerPort` ships with the package.
+- `DispatcherStore` — durable record of the dispatcher's catch-up cursor.
+
+## License
+
+MIT

package/dist/alterations.d.ts

@@ -0,0 +1,6 @@
+import { KeyedOccurrence } from './occurrence_key.js';
+import { Alteration, ScheduledEvent } from './types.js';
+export declare 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>[];
+//# sourceMappingURL=alterations.d.ts.map

package/dist/alterations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alterations.d.ts","sourceRoot":"","sources":["../src/alterations.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAmB7D,wBAAgB,gBAAgB,CAAC,QAAQ,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAChE,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,QAAQ,EACrB,gBAAgB,EAAE,SAAS,eAAe,EAAE,EAC5C,WAAW,EAAE,SAAS,UAAU,CAAC,QAAQ,CAAC,EAAE,EAC5C,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,cAAc,CAAC,QAAQ,CAAC,EAAE,CAsE5B"}

package/dist/alterations.js

@@ -0,0 +1,61 @@
+import { intersects } from "./generators/types.js";
+import { computeSpanEnd } from "./tz.js";
+// src/alterations.ts
+function applyAlterations(templateId, basePayload, keyedOccurrences, alterations, tz, windowStart, windowEnd) {
+	const altByKey = /* @__PURE__ */ new Map();
+	for (const alt of alterations) if (alt.templateId === templateId) altByKey.set(alt.occurrenceKey, alt);
+	const out = [];
+	const seenKeys = /* @__PURE__ */ new Set();
+	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;
+		const start = alt.startTimestamp ?? occ.startTimestamp;
+		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
+		});
+	}
+	for (const alt of altByKey.values()) {
+		if (seenKeys.has(alt.occurrenceKey)) continue;
+		if (alt.kind !== "reschedule") continue;
+		if (alt.startTimestamp == null) continue;
+		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(base, override) {
+	if (override == null) return base;
+	return {
+		...base,
+		...override
+	};
+}
+export { applyAlterations };
+
+//# sourceMappingURL=alterations.js.map

package/dist/alterations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alterations.js","names":[],"sources":["../src/alterations.ts"],"sourcesContent":["import { intersects } from \"./generators/types.js\";\nimport type { KeyedOccurrence } from \"./occurrence_key.js\";\nimport type { Alteration, ScheduledEvent } from \"./types.js\";\nimport { computeSpanEnd } from \"./tz.js\";\n\n// Apply a template's alterations to its base occurrences and emit the final\n// ScheduledEvents.\n//\n// Two passes:\n//   1. Walk base occurrences. Cancel suppresses; reschedule replaces (and\n//      may move out of window, in which case it's not emitted).\n//   2. Walk reschedules whose original key is NOT in the base list (the\n//      original was outside the window) but whose new time IS in the window.\n//      Synthesize an event for them. This is what activity-board does in its\n//      separate AlterationEventGenerator.\n//\n// `tz` is the template's timezone. Used to interpret hourSpan on the\n// alteration's timeSpan (if any). When the alteration carries no timeSpan,\n// we preserve the original occurrence's duration (end - start in UTC ms).\n//\n// Result is sorted ascending by startTimestamp.\nexport function applyAlterations<TPayload extends { type: string }>(\n  templateId: string,\n  basePayload: TPayload,\n  keyedOccurrences: readonly KeyedOccurrence[],\n  alterations: readonly Alteration<TPayload>[],\n  tz: string | undefined,\n  windowStart: number,\n  windowEnd: number\n): ScheduledEvent<TPayload>[] {\n  // Index alterations for THIS template by occurrence key. If multiple\n  // alterations target the same key, last-write-wins.\n  const altByKey = new Map<string, Alteration<TPayload>>();\n  for (const alt of alterations) {\n    if (alt.templateId === templateId) altByKey.set(alt.occurrenceKey, alt);\n  }\n\n  const out: ScheduledEvent<TPayload>[] = [];\n  const seenKeys = new Set<string>();\n\n  for (const occ of keyedOccurrences) {\n    seenKeys.add(occ.occurrenceKey);\n    const alt = altByKey.get(occ.occurrenceKey);\n\n    if (alt == null) {\n      out.push({\n        templateId,\n        occurrenceKey: occ.occurrenceKey,\n        startTimestamp: occ.startTimestamp,\n        endTimestamp: occ.endTimestamp,\n        payload: basePayload,\n      });\n      continue;\n    }\n    if (alt.kind === \"cancel\") continue;\n\n    // reschedule\n    const start = alt.startTimestamp ?? occ.startTimestamp;\n    // If the alteration specifies a timeSpan, use it (with tz semantics).\n    // Otherwise preserve the original UTC duration.\n    const end =\n      alt.timeSpan != null\n        ? computeSpanEnd(start, alt.timeSpan, tz)\n        : start + (occ.endTimestamp - occ.startTimestamp);\n    if (!intersects(start, end, windowStart, windowEnd)) continue;\n    out.push({\n      templateId,\n      occurrenceKey: occ.occurrenceKey,\n      startTimestamp: start,\n      endTimestamp: end,\n      payload: _mergePayload(basePayload, alt.payloadOverride),\n      alterationId: alt.id,\n    });\n  }\n\n  // Orphan reschedules: alteration's occurrenceKey isn't in the base list\n  // (because the original fell outside the window) but the rescheduled time\n  // is. Cancels for orphans are no-ops — there was nothing to cancel here.\n  for (const alt of altByKey.values()) {\n    if (seenKeys.has(alt.occurrenceKey)) continue;\n    if (alt.kind !== \"reschedule\") continue;\n    if (alt.startTimestamp == null) continue;\n    // No original to inherit duration from; default to 1ms if no timeSpan.\n    const end =\n      alt.timeSpan != null\n        ? computeSpanEnd(alt.startTimestamp, alt.timeSpan, tz)\n        : alt.startTimestamp + 1;\n    if (!intersects(alt.startTimestamp, end, windowStart, windowEnd)) continue;\n    out.push({\n      templateId,\n      occurrenceKey: alt.occurrenceKey,\n      startTimestamp: alt.startTimestamp,\n      endTimestamp: end,\n      payload: _mergePayload(basePayload, alt.payloadOverride),\n      alterationId: alt.id,\n    });\n  }\n\n  return out.sort((a, b) => a.startTimestamp - b.startTimestamp);\n}\n\nfunction _mergePayload<TPayload extends { type: string }>(\n  base: TPayload,\n  override: Partial<TPayload> | undefined\n): TPayload {\n  if (override == null) return base;\n  return { ...base, ...override } as TPayload;\n}\n"],"mappings":";;;AAqBA,SAAgB,iBACd,YACA,aACA,kBACA,aACA,IACA,aACA,WAC4B;CAG5B,MAAM,2BAAW,IAAI,IAAkC;CACvD,KAAK,MAAM,OAAO,aAChB,IAAI,IAAI,eAAe,YAAY,SAAS,IAAI,IAAI,eAAe,GAAG;CAGxE,MAAM,MAAkC,CAAC;CACzC,MAAM,2BAAW,IAAI,IAAY;CAEjC,KAAK,MAAM,OAAO,kBAAkB;EAClC,SAAS,IAAI,IAAI,aAAa;EAC9B,MAAM,MAAM,SAAS,IAAI,IAAI,aAAa;EAE1C,IAAI,OAAO,MAAM;GACf,IAAI,KAAK;IACP;IACA,eAAe,IAAI;IACnB,gBAAgB,IAAI;IACpB,cAAc,IAAI;IAClB,SAAS;GACX,CAAC;GACD;EACF;EACA,IAAI,IAAI,SAAS,UAAU;EAG3B,MAAM,QAAQ,IAAI,kBAAkB,IAAI;EAGxC,MAAM,MACJ,IAAI,YAAY,OACZ,eAAe,OAAO,IAAI,UAAU,EAAE,IACtC,SAAS,IAAI,eAAe,IAAI;EACtC,IAAI,CAAC,WAAW,OAAO,KAAK,aAAa,SAAS,GAAG;EACrD,IAAI,KAAK;GACP;GACA,eAAe,IAAI;GACnB,gBAAgB;GAChB,cAAc;GACd,SAAS,cAAc,aAAa,IAAI,eAAe;GACvD,cAAc,IAAI;EACpB,CAAC;CACH;CAKA,KAAK,MAAM,OAAO,SAAS,OAAO,GAAG;EACnC,IAAI,SAAS,IAAI,IAAI,aAAa,GAAG;EACrC,IAAI,IAAI,SAAS,cAAc;EAC/B,IAAI,IAAI,kBAAkB,MAAM;EAEhC,MAAM,MACJ,IAAI,YAAY,OACZ,eAAe,IAAI,gBAAgB,IAAI,UAAU,EAAE,IACnD,IAAI,iBAAiB;EAC3B,IAAI,CAAC,WAAW,IAAI,gBAAgB,KAAK,aAAa,SAAS,GAAG;EAClE,IAAI,KAAK;GACP;GACA,eAAe,IAAI;GACnB,gBAAgB,IAAI;GACpB,cAAc;GACd,SAAS,cAAc,aAAa,IAAI,eAAe;GACvD,cAAc,IAAI;EACpB,CAAC;CACH;CAEA,OAAO,IAAI,MAAM,GAAG,MAAM,EAAE,iBAAiB,EAAE,cAAc;AAC/D;AAEA,SAAS,cACP,MACA,UACU;CACV,IAAI,YAAY,MAAM,OAAO;CAC7B,OAAO;EAAE,GAAG;EAAM,GAAG;CAAS;AAChC"}

package/dist/cjs/alterations.d.ts

@@ -0,0 +1,5 @@
+import type { KeyedOccurrence } from "./occurrence_key.js";
+import type { Alteration, ScheduledEvent } from "./types.js";
+export declare 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>[];

package/dist/cjs/alterations.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyAlterations = applyAlterations;
+const types_js_1 = require("./generators/types.js");
+const tz_js_1 = require("./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.
+function applyAlterations(templateId, basePayload, keyedOccurrences, alterations, tz, windowStart, windowEnd) {
+    // Index alterations for THIS template by occurrence key. If multiple
+    // alterations target the same key, last-write-wins.
+    const altByKey = new Map();
+    for (const alt of alterations) {
+        if (alt.templateId === templateId)
+            altByKey.set(alt.occurrenceKey, alt);
+    }
+    const out = [];
+    const seenKeys = new Set();
+    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
+            ? (0, tz_js_1.computeSpanEnd)(start, alt.timeSpan, tz)
+            : start + (occ.endTimestamp - occ.startTimestamp);
+        if (!(0, types_js_1.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
+            ? (0, tz_js_1.computeSpanEnd)(alt.startTimestamp, alt.timeSpan, tz)
+            : alt.startTimestamp + 1;
+        if (!(0, types_js_1.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(base, override) {
+    if (override == null)
+        return base;
+    return { ...base, ...override };
+}

package/dist/cjs/dispatcher.d.ts

@@ -0,0 +1,38 @@
+import { type DispatcherStore } from "./dispatcher_store.js";
+import type { Scheduler } from "./scheduler.js";
+import type { ScheduledEvent } from "./types.js";
+export interface DispatcherConfig<TPayload extends {
+    type: string;
+}> {
+    scheduler: Scheduler<TPayload>;
+    fire: (event: ScheduledEvent<TPayload>) => Promise<void> | void;
+    store?: DispatcherStore;
+    onError?: (err: unknown, event?: ScheduledEvent<TPayload>) => void;
+    idleTimeoutMs?: number;
+    now?: () => number;
+    setTimeout?: (fn: () => void, ms: number) => unknown;
+    clearTimeout?: (handle: unknown) => void;
+}
+export declare class Dispatcher<TPayload extends {
+    type: string;
+}> {
+    private readonly _scheduler;
+    private readonly _fire;
+    private readonly _store;
+    private readonly _onError;
+    private readonly _idleTimeoutMs;
+    private readonly _now;
+    private readonly _setTimeout;
+    private readonly _clearTimeout;
+    private _running;
+    private _wakeResolve;
+    private _changeSubscription;
+    constructor(config: DispatcherConfig<TPayload>);
+    start(): Promise<void>;
+    stop(): void;
+    private _loop;
+    private _findNextTarget;
+    private _tick;
+    private _sleepUntil;
+    private _wake;
+}

package/dist/cjs/dispatcher.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Dispatcher = void 0;
+const dispatcher_store_js_1 = require("./dispatcher_store.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;
+// 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.
+class Dispatcher {
+    _scheduler;
+    _fire;
+    _store;
+    _onError;
+    _idleTimeoutMs;
+    _now;
+    _setTimeout;
+    _clearTimeout;
+    _running = false;
+    _wakeResolve = null;
+    _changeSubscription = null;
+    constructor(config) {
+        this._scheduler = config.scheduler;
+        this._fire = config.fire;
+        this._store = config.store ?? new dispatcher_store_js_1.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));
+    }
+    // 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() {
+        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() {
+        if (!this._running)
+            return;
+        this._running = false;
+        if (this._changeSubscription != null) {
+            this._changeSubscription.unsubscribe();
+            this._changeSubscription = null;
+        }
+        this._wake();
+    }
+    // ─── Internals ──────────────────────────────────────────────
+    async _loop() {
+        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.
+    async _findNextTarget() {
+        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.
+    async _tick() {
+        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;
+        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.
+    async _sleepUntil(targetMs) {
+        const remaining = targetMs - this._now();
+        if (remaining <= 0)
+            return;
+        await new Promise((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.
+    _wake() {
+        if (this._wakeResolve != null)
+            this._wakeResolve();
+    }
+}
+exports.Dispatcher = Dispatcher;
+function defaultOnError(err, event) {
+    if (event != null) {
+        console.error(`[Dispatcher] fire failed for ${event.templateId}/${event.occurrenceKey}:`, err);
+    }
+    else {
+        console.error("[Dispatcher] error:", err);
+    }
+}

package/dist/cjs/dispatcher_store.d.ts

@@ -0,0 +1,9 @@
+export interface DispatcherStore {
+    loadCursor(): Promise<number | null>;
+    saveCursor(cursor: number): Promise<void>;
+}
+export declare class InMemoryDispatcherStore implements DispatcherStore {
+    private _cursor;
+    loadCursor(): Promise<number | null>;
+    saveCursor(cursor: number): Promise<void>;
+}

package/dist/cjs/dispatcher_store.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryDispatcherStore = void 0;
+// Reference in-memory implementation. Useful for tests and short-lived
+// processes that don't need crash recovery.
+class InMemoryDispatcherStore {
+    _cursor = null;
+    async loadCursor() {
+        return this._cursor;
+    }
+    async saveCursor(cursor) {
+        this._cursor = cursor;
+    }
+}
+exports.InMemoryDispatcherStore = InMemoryDispatcherStore;

package/dist/cjs/generators/anchored.d.ts

@@ -0,0 +1,3 @@
+import type { AnchoredRule } from "../types.js";
+import { type Occurrence } from "./types.js";
+export declare function generateAnchored(rule: AnchoredRule, tz: string | undefined, windowStart: number, windowEnd: number): Occurrence[];

package/dist/cjs/generators/anchored.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAnchored = generateAnchored;
+const tz_js_1 = require("../tz.js");
+const types_js_1 = require("./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.
+function generateAnchored(rule, tz, windowStart, windowEnd) {
+    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;
+    let occurrenceStart;
+    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 = [];
+    while (occurrenceStart < effectiveEnd) {
+        if (rule.count != null && index >= rule.count)
+            break;
+        const occEnd = (0, tz_js_1.computeSpanEnd)(occurrenceStart, rule.timeSpan, tz);
+        if ((0, types_js_1.intersects)(occurrenceStart, occEnd, windowStart, windowEnd) &&
+            occurrenceStart >= rule.seriesStart) {
+            out.push({ startTimestamp: occurrenceStart, endTimestamp: occEnd });
+            if (out.length > types_js_1.MAX_OCCURRENCES_PER_GENERATE) {
+                throw new types_js_1.TooManyOccurrencesError("anchored");
+            }
+        }
+        index++;
+        occurrenceStart += rule.intervalMs;
+    }
+    return out;
+}

package/dist/cjs/generators/days_of_month.d.ts

@@ -0,0 +1,3 @@
+import type { DaysOfMonthRule, Disambiguation } from "../types.js";
+import { type Occurrence } from "./types.js";
+export declare function generateDaysOfMonth(rule: DaysOfMonthRule, tz: string | undefined, windowStart: number, windowEnd: number, disambiguation?: Disambiguation): Occurrence[];

package/dist/cjs/generators/days_of_month.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDaysOfMonth = generateDaysOfMonth;
+const tz_js_1 = require("../tz.js");
+const types_js_1 = require("./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).
+function generateDaysOfMonth(rule, tz, windowStart, windowEnd, disambiguation = "compatible") {
+    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 = (0, tz_js_1.utcToWallParts)(rule.seriesStart, tz).year;
+    const endYear = (0, tz_js_1.utcToWallParts)(Math.min(effectiveEnd, Number.MAX_SAFE_INTEGER), tz).year;
+    const out = [];
+    let count = 0;
+    for (let year = startYear; year <= endYear; year += rule.yearInterval) {
+        const yearEmits = [];
+        for (const month of months) {
+            const len = (0, tz_js_1.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" &&
+                    (0, tz_js_1.isNonexistentWallTime)(year, month, day, rule.timeOfDay, tz)) {
+                    continue;
+                }
+                const occStart = (0, tz_js_1.wallTimeToUtc)(year, month, day, rule.timeOfDay, tz, disambiguation);
+                const occEnd = (0, tz_js_1.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 ((0, types_js_1.intersects)(occStart, occEnd, windowStart, windowEnd)) {
+                    yearEmits.push({ startTimestamp: occStart, endTimestamp: occEnd });
+                    if (out.length + yearEmits.length > types_js_1.MAX_OCCURRENCES_PER_GENERATE) {
+                        throw new types_js_1.TooManyOccurrencesError("daysOfMonth");
+                    }
+                }
+            }
+        }
+        yearEmits.sort((a, b) => a.startTimestamp - b.startTimestamp);
+        out.push(...yearEmits);
+    }
+    return out;
+}