@graphorin/triggers 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @graphorin/triggers
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release. Background-task scheduler for the Graphorin
+  framework — durable cron / interval / idle / event triggers, an
+  in-tree 5-field cron parser, per-trigger catch-up policies, and a
+  shared code path for library and server modes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksiy Stepurenko
+
+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

@@ -0,0 +1,72 @@
+# @graphorin/triggers
+
+> Background-task scheduler for the Graphorin framework.
+
+`@graphorin/triggers` ships durable cron / interval / idle / event
+triggers with the same code path in library and server modes. The
+package owns:
+
+- An in-tree 5-field **cron parser** (`* * * * *`, ranges, lists,
+  steps; no third-party dependency).
+- A `Scheduler` runtime — a process-bound loop that fires registered
+  triggers and persists their state via the `TriggerStore` contract
+  from `@graphorin/core/contracts`.
+- Per-trigger **catch-up policies** (`'none'` default, `'last'`,
+  `'all'`) plus `maxCatchupRuns` and `catchupWindowMs` knobs.
+- An **AsyncIterable lifecycle event stream** (`scheduler.events()`)
+  so observability and tests can subscribe without monkey-patching.
+- A one-time per-process **library-mode WARN** (`acknowledgeLibMode`
+  to suppress) reminding library callers that triggers fire as long
+  as the parent process lives.
+
+## Install
+
+```bash
+pnpm add @graphorin/triggers @graphorin/store-sqlite
+```
+
+## Quick start
+
+```ts
+import { createScheduler, cron, interval, idle, event } from '@graphorin/triggers';
+import { createSqliteStore } from '@graphorin/store-sqlite';
+
+const store = await createSqliteStore({ path: './assistant.db' });
+await store.init();
+
+const scheduler = createScheduler({ store: store.triggers });
+
+scheduler.register(
+  cron('daily-digest', '0 9 * * *', async () => {
+    // …compose and send a daily digest email
+  }, { catchupPolicy: 'last' }),
+);
+
+scheduler.register(
+  interval('poll-mailbox', 60_000, async () => {
+    // …poll IMAP every minute
+  }),
+);
+
+scheduler.register(
+  idle('flush-buffer', 5 * 60_000, async () => {
+    // …fires after the user has been idle for 5 minutes
+  }),
+);
+
+scheduler.register(
+  event('on-handoff', 'session.handoff', async (payload) => {
+    // …fires whenever a handoff event is published
+  }),
+);
+
+await scheduler.start();
+```
+
+## License
+
+MIT © 2026 Oleksiy Stepurenko.
+
+---
+
+**Project Graphorin** · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/cron.d.ts

@@ -0,0 +1,76 @@
+//#region src/cron.d.ts
+/**
+ * Tiny in-tree 5-field cron parser used by `@graphorin/triggers`.
+ *
+ * Supported syntax:
+ *
+ *   minute   (0-59)
+ *   hour     (0-23)
+ *   day      (1-31)
+ *   month    (1-12)
+ *   dayOfWeek (0-6; Sunday = 0)
+ *
+ * Each field accepts:
+ *   - star (asterisk) for every value
+ *   - a single number `5`
+ *   - a comma list `1,2,5`
+ *   - a range `1-4`
+ *   - a step expression with the slash operator (e.g. every-5 minutes,
+ *     `0-30/10` for "0,10,20,30 minutes")
+ *
+ * The parser is intentionally **strict**: any unrecognised character
+ * raises {@link CronParseError} so a typo never silently never-fires.
+ *
+ * **Day vs. day-of-week semantics — AND, not OR.** When *both* `day`
+ * and `dayOfWeek` are restricted (neither is the every-value
+ * wildcard), Graphorin requires **both** to match for a fire to
+ * happen — i.e. `0 12 1-7 * 1` means "noon on the first Monday of
+ * every month". This differs from Vixie / POSIX cron, which
+ * OR-combines the two restricted fields. AND semantics are easier to
+ * reason about in personal-assistant scenarios; the framework stays
+ * consistent with this rule rather than mixing the two conventions.
+ *
+ * The scheduler treats every trigger as **UTC**. Operators that need
+ * a local-time fire encode the offset directly into their cron
+ * expression (e.g. `0 14 * * *` for "9am Eastern in winter").
+ *
+ * @packageDocumentation
+ */
+/** @stable */
+declare class CronParseError extends Error {
+  readonly expression: string;
+  readonly name = "CronParseError";
+  constructor(expression: string, message: string);
+}
+/** @stable */
+interface ParsedCron {
+  readonly expression: string;
+  readonly minute: ReadonlySet<number>;
+  readonly hour: ReadonlySet<number>;
+  readonly day: ReadonlySet<number>;
+  readonly month: ReadonlySet<number>;
+  readonly dayOfWeek: ReadonlySet<number>;
+}
+/**
+ * Parse a 5-field cron expression. Throws {@link CronParseError} on
+ * any malformed input.
+ *
+ * @stable
+ */
+declare function parseCron(expression: string): ParsedCron;
+/**
+ * Compute the next fire time strictly after `from` for the supplied
+ * cron schedule. Returns a UTC `Date` (the scheduler treats every
+ * trigger as UTC; operators that need local time express that in
+ * their cron expression).
+ *
+ * Returns `null` if no fire happens in the next 4 years (defensive —
+ * impossible for a well-formed cron expression except a vacuous
+ * combination that never aligns).
+ *
+ * @stable
+ */
+declare function nextFireAfter(parsed: ParsedCron, from: Date): Date | null;
+//#endregion
+export { CronParseError, ParsedCron, nextFireAfter, parseCron };
+//# sourceMappingURL=cron.d.ts.map

package/dist/cron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.d.ts","names":[],"sources":["../src/cron.ts"],"sourcesContent":[],"mappings":";;AAuCA;AAWA;;;;;;;AA4BA;AAoGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA3Ia,cAAA,SAAuB,KAAA;;;;;;UAWnB,UAAA;;mBAEE;iBACF;gBACD;kBACE;sBACI;;;;;;;;iBAsBN,SAAA,sBAA+B;;;;;;;;;;;;;iBAoG/B,aAAA,SAAsB,kBAAkB,OAAO"}

package/dist/cron.js

@@ -0,0 +1,174 @@
+//#region src/cron.ts
+/**
+* Tiny in-tree 5-field cron parser used by `@graphorin/triggers`.
+*
+* Supported syntax:
+*
+*   minute   (0-59)
+*   hour     (0-23)
+*   day      (1-31)
+*   month    (1-12)
+*   dayOfWeek (0-6; Sunday = 0)
+*
+* Each field accepts:
+*   - star (asterisk) for every value
+*   - a single number `5`
+*   - a comma list `1,2,5`
+*   - a range `1-4`
+*   - a step expression with the slash operator (e.g. every-5 minutes,
+*     `0-30/10` for "0,10,20,30 minutes")
+*
+* The parser is intentionally **strict**: any unrecognised character
+* raises {@link CronParseError} so a typo never silently never-fires.
+*
+* **Day vs. day-of-week semantics — AND, not OR.** When *both* `day`
+* and `dayOfWeek` are restricted (neither is the every-value
+* wildcard), Graphorin requires **both** to match for a fire to
+* happen — i.e. `0 12 1-7 * 1` means "noon on the first Monday of
+* every month". This differs from Vixie / POSIX cron, which
+* OR-combines the two restricted fields. AND semantics are easier to
+* reason about in personal-assistant scenarios; the framework stays
+* consistent with this rule rather than mixing the two conventions.
+*
+* The scheduler treats every trigger as **UTC**. Operators that need
+* a local-time fire encode the offset directly into their cron
+* expression (e.g. `0 14 * * *` for "9am Eastern in winter").
+*
+* @packageDocumentation
+*/
+/** @stable */
+var CronParseError = class extends Error {
+	name = "CronParseError";
+	constructor(expression, message) {
+		super(`[graphorin/triggers] cron expression '${expression}': ${message}`);
+		this.expression = expression;
+	}
+};
+const RANGES = {
+	minute: {
+		min: 0,
+		max: 59
+	},
+	hour: {
+		min: 0,
+		max: 23
+	},
+	day: {
+		min: 1,
+		max: 31
+	},
+	month: {
+		min: 1,
+		max: 12
+	},
+	dayOfWeek: {
+		min: 0,
+		max: 6
+	}
+};
+/**
+* Parse a 5-field cron expression. Throws {@link CronParseError} on
+* any malformed input.
+*
+* @stable
+*/
+function parseCron(expression) {
+	const trimmed = expression.trim();
+	if (trimmed.length === 0) throw new CronParseError(expression, "expression is empty");
+	const fields = trimmed.split(/\s+/);
+	if (fields.length !== 5) throw new CronParseError(expression, `expected 5 whitespace-separated fields (minute hour day month dayOfWeek), got ${fields.length}`);
+	const [minuteStr, hourStr, dayStr, monthStr, dowStr] = fields;
+	return {
+		expression: trimmed,
+		minute: parseField("minute", minuteStr, RANGES.minute, expression),
+		hour: parseField("hour", hourStr, RANGES.hour, expression),
+		day: parseField("day", dayStr, RANGES.day, expression),
+		month: parseField("month", monthStr, RANGES.month, expression),
+		dayOfWeek: parseField("dayOfWeek", dowStr, RANGES.dayOfWeek, expression)
+	};
+}
+function parseField(name, raw, range, expression) {
+	const out = /* @__PURE__ */ new Set();
+	for (const part of raw.split(",")) {
+		if (part.length === 0) throw new CronParseError(expression, `field '${name}' has an empty list element`);
+		let stepStr;
+		let bodyStr = part;
+		if (part.includes("/")) {
+			const [body, step$1] = part.split("/", 2);
+			bodyStr = body ?? "";
+			stepStr = step$1;
+		}
+		const step = stepStr === void 0 ? 1 : Number.parseInt(stepStr, 10);
+		if (!Number.isFinite(step) || step <= 0) throw new CronParseError(expression, `field '${name}' has invalid step '${stepStr}'`);
+		let from;
+		let to;
+		if (bodyStr === "*") {
+			from = range.min;
+			to = range.max;
+		} else if (bodyStr.includes("-")) {
+			const [a, b] = bodyStr.split("-", 2);
+			from = parseNumeric(name, a, expression);
+			to = parseNumeric(name, b, expression);
+		} else {
+			const single = parseNumeric(name, bodyStr, expression);
+			from = single;
+			to = stepStr === void 0 ? single : range.max;
+		}
+		if (from < range.min || to > range.max || from > to) throw new CronParseError(expression, `field '${name}' value out of range [${range.min}, ${range.max}]: ${bodyStr}`);
+		for (let v = from; v <= to; v += step) out.add(v);
+	}
+	return out;
+}
+function parseNumeric(name, raw, expression) {
+	if (raw === void 0 || raw.length === 0) throw new CronParseError(expression, `field '${name}' has empty numeric component`);
+	if (!/^\d+$/.test(raw)) throw new CronParseError(expression, `field '${name}' value '${raw}' is not numeric`);
+	return Number.parseInt(raw, 10);
+}
+/**
+* Compute the next fire time strictly after `from` for the supplied
+* cron schedule. Returns a UTC `Date` (the scheduler treats every
+* trigger as UTC; operators that need local time express that in
+* their cron expression).
+*
+* Returns `null` if no fire happens in the next 4 years (defensive —
+* impossible for a well-formed cron expression except a vacuous
+* combination that never aligns).
+*
+* @stable
+*/
+function nextFireAfter(parsed, from) {
+	const start = new Date(from.getTime() + 6e4);
+	start.setUTCSeconds(0, 0);
+	const horizon = new Date(start.getTime() + 4 * 365 * 24 * 60 * 60 * 1e3);
+	let cursor = new Date(start.getTime());
+	while (cursor.getTime() < horizon.getTime()) {
+		const month = cursor.getUTCMonth() + 1;
+		if (!parsed.month.has(month)) {
+			cursor = new Date(Date.UTC(cursor.getUTCMonth() === 11 ? cursor.getUTCFullYear() + 1 : cursor.getUTCFullYear(), (cursor.getUTCMonth() + 1) % 12, 1, 0, 0, 0, 0));
+			continue;
+		}
+		const day = cursor.getUTCDate();
+		const dow = cursor.getUTCDay();
+		if (!parsed.day.has(day) || !parsed.dayOfWeek.has(dow)) {
+			cursor = new Date(cursor.getTime() + 1440 * 60 * 1e3);
+			cursor.setUTCHours(0, 0, 0, 0);
+			continue;
+		}
+		if (!parsed.hour.has(cursor.getUTCHours())) {
+			cursor = new Date(cursor.getTime() + 3600 * 1e3);
+			cursor.setUTCMinutes(0, 0, 0);
+			continue;
+		}
+		if (!parsed.minute.has(cursor.getUTCMinutes())) {
+			cursor = new Date(cursor.getTime() + 6e4);
+			cursor.setUTCSeconds(0, 0);
+			continue;
+		}
+		return cursor;
+	}
+	return null;
+}
+
+//#endregion
+export { CronParseError, nextFireAfter, parseCron };
+//# sourceMappingURL=cron.js.map

package/dist/cron.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.js","names":["expression: string","RANGES: Readonly<Record<keyof Omit<ParsedCron, 'expression'>, FieldRange>>","stepStr: string | undefined","step","from: number","to: number"],"sources":["../src/cron.ts"],"sourcesContent":["/**\n * Tiny in-tree 5-field cron parser used by `@graphorin/triggers`.\n *\n * Supported syntax:\n *\n *   minute   (0-59)\n *   hour     (0-23)\n *   day      (1-31)\n *   month    (1-12)\n *   dayOfWeek (0-6; Sunday = 0)\n *\n * Each field accepts:\n *   - star (asterisk) for every value\n *   - a single number `5`\n *   - a comma list `1,2,5`\n *   - a range `1-4`\n *   - a step expression with the slash operator (e.g. every-5 minutes,\n *     `0-30/10` for \"0,10,20,30 minutes\")\n *\n * The parser is intentionally **strict**: any unrecognised character\n * raises {@link CronParseError} so a typo never silently never-fires.\n *\n * **Day vs. day-of-week semantics — AND, not OR.** When *both* `day`\n * and `dayOfWeek` are restricted (neither is the every-value\n * wildcard), Graphorin requires **both** to match for a fire to\n * happen — i.e. `0 12 1-7 * 1` means \"noon on the first Monday of\n * every month\". This differs from Vixie / POSIX cron, which\n * OR-combines the two restricted fields. AND semantics are easier to\n * reason about in personal-assistant scenarios; the framework stays\n * consistent with this rule rather than mixing the two conventions.\n *\n * The scheduler treats every trigger as **UTC**. Operators that need\n * a local-time fire encode the offset directly into their cron\n * expression (e.g. `0 14 * * *` for \"9am Eastern in winter\").\n *\n * @packageDocumentation\n */\n\n/** @stable */\nexport class CronParseError extends Error {\n  override readonly name = 'CronParseError';\n  constructor(\n    public readonly expression: string,\n    message: string,\n  ) {\n    super(`[graphorin/triggers] cron expression '${expression}': ${message}`);\n  }\n}\n\n/** @stable */\nexport interface ParsedCron {\n  readonly expression: string;\n  readonly minute: ReadonlySet<number>;\n  readonly hour: ReadonlySet<number>;\n  readonly day: ReadonlySet<number>;\n  readonly month: ReadonlySet<number>;\n  readonly dayOfWeek: ReadonlySet<number>;\n}\n\ninterface FieldRange {\n  readonly min: number;\n  readonly max: number;\n}\n\nconst RANGES: Readonly<Record<keyof Omit<ParsedCron, 'expression'>, FieldRange>> = {\n  minute: { min: 0, max: 59 },\n  hour: { min: 0, max: 23 },\n  day: { min: 1, max: 31 },\n  month: { min: 1, max: 12 },\n  dayOfWeek: { min: 0, max: 6 },\n};\n\n/**\n * Parse a 5-field cron expression. Throws {@link CronParseError} on\n * any malformed input.\n *\n * @stable\n */\nexport function parseCron(expression: string): ParsedCron {\n  const trimmed = expression.trim();\n  if (trimmed.length === 0) {\n    throw new CronParseError(expression, 'expression is empty');\n  }\n  const fields = trimmed.split(/\\s+/);\n  if (fields.length !== 5) {\n    throw new CronParseError(\n      expression,\n      `expected 5 whitespace-separated fields (minute hour day month dayOfWeek), got ${fields.length}`,\n    );\n  }\n  const [minuteStr, hourStr, dayStr, monthStr, dowStr] = fields as [\n    string,\n    string,\n    string,\n    string,\n    string,\n  ];\n  return {\n    expression: trimmed,\n    minute: parseField('minute', minuteStr, RANGES.minute, expression),\n    hour: parseField('hour', hourStr, RANGES.hour, expression),\n    day: parseField('day', dayStr, RANGES.day, expression),\n    month: parseField('month', monthStr, RANGES.month, expression),\n    dayOfWeek: parseField('dayOfWeek', dowStr, RANGES.dayOfWeek, expression),\n  };\n}\n\nfunction parseField(\n  name: string,\n  raw: string,\n  range: FieldRange,\n  expression: string,\n): ReadonlySet<number> {\n  const out = new Set<number>();\n  for (const part of raw.split(',')) {\n    if (part.length === 0) {\n      throw new CronParseError(expression, `field '${name}' has an empty list element`);\n    }\n    let stepStr: string | undefined;\n    let bodyStr = part;\n    if (part.includes('/')) {\n      const [body, step] = part.split('/', 2);\n      bodyStr = body ?? '';\n      stepStr = step;\n    }\n    const step = stepStr === undefined ? 1 : Number.parseInt(stepStr, 10);\n    if (!Number.isFinite(step) || step <= 0) {\n      throw new CronParseError(expression, `field '${name}' has invalid step '${stepStr}'`);\n    }\n    let from: number;\n    let to: number;\n    if (bodyStr === '*') {\n      from = range.min;\n      to = range.max;\n    } else if (bodyStr.includes('-')) {\n      const [a, b] = bodyStr.split('-', 2);\n      from = parseNumeric(name, a, expression);\n      to = parseNumeric(name, b, expression);\n    } else {\n      const single = parseNumeric(name, bodyStr, expression);\n      from = single;\n      to = stepStr === undefined ? single : range.max;\n    }\n    if (from < range.min || to > range.max || from > to) {\n      throw new CronParseError(\n        expression,\n        `field '${name}' value out of range [${range.min}, ${range.max}]: ${bodyStr}`,\n      );\n    }\n    for (let v = from; v <= to; v += step) {\n      out.add(v);\n    }\n  }\n  return out;\n}\n\nfunction parseNumeric(name: string, raw: string | undefined, expression: string): number {\n  if (raw === undefined || raw.length === 0) {\n    throw new CronParseError(expression, `field '${name}' has empty numeric component`);\n  }\n  if (!/^\\d+$/.test(raw)) {\n    throw new CronParseError(expression, `field '${name}' value '${raw}' is not numeric`);\n  }\n  return Number.parseInt(raw, 10);\n}\n\n/**\n * Compute the next fire time strictly after `from` for the supplied\n * cron schedule. Returns a UTC `Date` (the scheduler treats every\n * trigger as UTC; operators that need local time express that in\n * their cron expression).\n *\n * Returns `null` if no fire happens in the next 4 years (defensive —\n * impossible for a well-formed cron expression except a vacuous\n * combination that never aligns).\n *\n * @stable\n */\nexport function nextFireAfter(parsed: ParsedCron, from: Date): Date | null {\n  const start = new Date(from.getTime() + 60_000);\n  start.setUTCSeconds(0, 0);\n  const horizon = new Date(start.getTime() + 4 * 365 * 24 * 60 * 60 * 1000);\n\n  let cursor = new Date(start.getTime());\n  while (cursor.getTime() < horizon.getTime()) {\n    const month = cursor.getUTCMonth() + 1;\n    if (!parsed.month.has(month)) {\n      cursor = new Date(\n        Date.UTC(\n          cursor.getUTCMonth() === 11 ? cursor.getUTCFullYear() + 1 : cursor.getUTCFullYear(),\n          (cursor.getUTCMonth() + 1) % 12,\n          1,\n          0,\n          0,\n          0,\n          0,\n        ),\n      );\n      continue;\n    }\n    const day = cursor.getUTCDate();\n    const dow = cursor.getUTCDay();\n    if (!parsed.day.has(day) || !parsed.dayOfWeek.has(dow)) {\n      cursor = new Date(cursor.getTime() + 24 * 60 * 60 * 1000);\n      cursor.setUTCHours(0, 0, 0, 0);\n      continue;\n    }\n    if (!parsed.hour.has(cursor.getUTCHours())) {\n      cursor = new Date(cursor.getTime() + 60 * 60 * 1000);\n      cursor.setUTCMinutes(0, 0, 0);\n      continue;\n    }\n    if (!parsed.minute.has(cursor.getUTCMinutes())) {\n      cursor = new Date(cursor.getTime() + 60_000);\n      cursor.setUTCSeconds(0, 0);\n      continue;\n    }\n    return cursor;\n  }\n  return null;\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+import { CronParseError, ParsedCron, nextFireAfter, parseCron } from "./cron.js";
+import { TriggerState, TriggerStore } from "@graphorin/core/contracts";
+
+//#region src/index.d.ts
+
+/** Canonical version constant. Mirrors the `package.json` version. */
+declare const VERSION = "0.5.0";
+/**
+ * Catch-up policy applied when a trigger missed one or more fires
+ * while the scheduler was offline.
+ *
+ * - `'none'` — drop missed fires (default; safest for personal-assistant scenarios).
+ * - `'last'` — fire once on resume (best for cron-style daily jobs).
+ * - `'all'` — fire each missed run up to `maxCatchupRuns` within `catchupWindowMs`.
+ *
+ * @stable
+ */
+type CatchupPolicy = 'none' | 'last' | 'all';
+/** @stable */
+type TriggerKind = 'cron' | 'interval' | 'idle' | 'event';
+/** @stable */
+interface TriggerOptions {
+  readonly catchupPolicy?: CatchupPolicy;
+  readonly maxCatchupRuns?: number;
+  /**
+   * How far back (from the last successful fire) misses are honored.
+   * Catch-up counts REAL missed fires (RP-12), so the window must
+   * exceed the trigger period — a 24h window can never catch up a
+   * daily cron whose boundary is itself 24h after the last fire.
+   * Default 24h.
+   */
+  readonly catchupWindowMs?: number;
+  readonly tags?: ReadonlyArray<string>;
+  /**
+   * Suppress the one-time per-process library-mode WARN. Library
+   * callers acknowledging that triggers fire only as long as the
+   * process lives pass `true` here.
+   */
+  readonly acknowledgeLibMode?: boolean;
+}
+/**
+ * Trigger callback. Receives an optional `payload` for `event`
+ * triggers; for cron / interval / idle triggers `payload` is
+ * `undefined`.
+ *
+ * @stable
+ */
+type TriggerCallback = (payload?: unknown) => void | Promise<void>;
+/**
+ * Public trigger declaration emitted by the helper functions
+ * (`cron(...)`, `interval(...)`, `idle(...)`, `event(...)`).
+ *
+ * @stable
+ */
+interface TriggerDeclaration {
+  readonly id: string;
+  readonly kind: TriggerKind;
+  readonly spec: string;
+  readonly callback: TriggerCallback;
+  readonly options: TriggerOptions;
+}
+/**
+ * Build a cron trigger declaration. The expression is validated
+ * eagerly — a malformed cron expression throws at registration time,
+ * not at first fire.
+ *
+ * @stable
+ */
+declare function cron(id: string, expression: string, callback: TriggerCallback, options?: TriggerOptions): TriggerDeclaration;
+/** @stable */
+declare function interval(id: string, intervalMs: number, callback: TriggerCallback, options?: TriggerOptions): TriggerDeclaration;
+/** @stable */
+declare function idle(id: string, idleMs: number, callback: TriggerCallback, options?: TriggerOptions): TriggerDeclaration;
+/** @stable */
+declare function event(id: string, eventName: string, callback: TriggerCallback, options?: TriggerOptions): TriggerDeclaration;
+/**
+ * Lifecycle event emitted by {@link Scheduler.events}. Useful for
+ * tests and for piping into observability without monkey-patching.
+ *
+ * @stable
+ */
+type SchedulerEvent = {
+  readonly type: 'started';
+} | {
+  readonly type: 'stopped';
+} | {
+  readonly type: 'registered';
+  readonly id: string;
+  readonly kind: TriggerKind;
+} | {
+  readonly type: 'fire-start';
+  readonly id: string;
+  readonly firedAt: number;
+} | {
+  readonly type: 'fire-end';
+  readonly id: string;
+  readonly durationMs: number;
+} | {
+  readonly type: 'fire-error';
+  readonly id: string;
+  readonly error: unknown;
+  readonly durationMs: number;
+} | {
+  readonly type: 'catchup-applied';
+  readonly id: string;
+  readonly missed: number;
+} | {
+  readonly type: 'lib-mode-warning';
+  readonly id: string;
+};
+/**
+ * Options for {@link createScheduler}.
+ *
+ * @stable
+ */
+interface CreateSchedulerOptions {
+  readonly store: TriggerStore;
+  /** Default `'lib'`. Server mode skips the lib-mode warning. */
+  readonly mode?: 'lib' | 'server';
+  /** Override the wall clock — used by tests. */
+  readonly now?: () => number;
+  /**
+   * Override `setTimeout`. The callback receives the chosen delay in
+   * milliseconds; the return value is the handle the scheduler
+   * later passes to `clearTimeout`. Tests inject a controllable timer.
+   */
+  readonly setTimeout?: (cb: () => void, ms: number) => unknown;
+  readonly clearTimeout?: (handle: unknown) => void;
+  /**
+   * Resets the per-process WARN-once flag. Used by the test suite to
+   * verify the warning fires exactly once per run.
+   *
+   * @internal
+   */
+  readonly _resetLibModeFlag?: boolean;
+}
+/**
+ * Public Scheduler surface.
+ *
+ * @stable
+ */
+interface Scheduler {
+  register(declaration: TriggerDeclaration): Promise<TriggerState>;
+  unregister(id: string): Promise<void>;
+  list(): Promise<readonly TriggerState[]>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  /** Emit `eventName` to every registered `event` trigger. */
+  emit(eventName: string, payload?: unknown): Promise<void>;
+  /** Manually fire `id` (used by `graphorin triggers fire`, Phase 15). */
+  fire(id: string, payload?: unknown): Promise<void>;
+  /**
+   * Flip the persistent `disabled` flag (IP-17). Disabling cancels the
+   * armed timer but keeps the trigger registered + persisted; enabling
+   * recomputes the next fire from now and re-arms. The destructive
+   * removal is `unregister(...)`.
+   */
+  setDisabled(id: string, disabled: boolean): Promise<TriggerState>;
+  /** AsyncIterable lifecycle event stream. */
+  events(): AsyncIterable<SchedulerEvent>;
+  /** Notify the scheduler that the user / runtime is no longer idle. */
+  recordActivity(): void;
+}
+/** @stable */
+declare function createScheduler(options: CreateSchedulerOptions): Scheduler;
+/**
+ * Test-only helper. Drops the per-process WARN-once flag so the next
+ * `register(...)` call in lib mode emits the warning again.
+ *
+ * @internal
+ */
+declare function _resetLibModeWarningForTesting(): void;
+//#endregion
+export { CatchupPolicy, CreateSchedulerOptions, CronParseError, type ParsedCron, Scheduler, SchedulerEvent, TriggerCallback, TriggerDeclaration, TriggerKind, TriggerOptions, VERSION, _resetLibModeWarningForTesting, createScheduler, cron, event, idle, interval, nextFireAfter, parseCron };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;AA0DA;AAQiB,cArDJ,OAAA,GAqDsB,OAAA;;;;;AAenC;;;;;AAWA;AAGY,KAtEA,aAAA,GAsEA,MAAA,GAAA,MAAA,GAAA,KAAA;;AAET,KArES,WAAA,GAqET,MAAA,GAAA,UAAA,GAAA,MAAA,GAAA,OAAA;;AAca,UAhFC,cAAA,CAgFG;EAGR,SAAA,aAAA,CAAA,EAlFe,aAkFf;EACD,SAAA,cAAA,CAAA,EAAA,MAAA;EACR;;AAcH;;;;;EAwBY,SAAA,eAAc,CAAA,EAAA,MAG6C;EAiBtD,SAAA,IAAA,CAAA,EApIC,aAoIqB,CAAA,MAAA,CACrB;EA0BD;;;;;EAGU,SAAA,kBAAA,CAAA,EAAA,OAAA;;;;;;;;;AAef,KAjKA,eAAA,GAiKA,CAAA,OAAA,CAAA,EAAA,OAAA,EAAA,GAAA,IAAA,GAjKgD,OAiKhD,CAAA,IAAA,CAAA;;AAMZ;AAaA;;;;UA5KiB,kBAAA;;iBAEA;;qBAEI;oBACD;;;;;;;;;iBAUJ,IAAA,2CAGJ,2BACD,iBACR;;iBAMa,QAAA,2CAGJ,2BACD,iBACR;;iBAca,IAAA,uCAGJ,2BACD,iBACR;;iBAca,KAAA,0CAGJ,2BACD,iBACR;;;;;;;KAmBS,cAAA;;;;;;;iBAG2D;;;;;;;;;;;;;;;;;;;;;;;;;;;UAiBtD,sBAAA;kBACC;;;;;;;;;;;;;;;;;;;;;;;;;UA0BD,SAAA;wBACO,qBAAqB,QAAQ;0BAC3B;UAChB,iBAAiB;WAChB;UACD;;8CAEoC;;uCAEP;;;;;;;8CAOO,QAAQ;;YAE1C,cAAc;;;;;iBAMV,eAAA,UAAyB,yBAAyB;;;;;;;iBAalD,8BAAA,CAAA"}

package/dist/index.js

@@ -0,0 +1,404 @@
+import { CronParseError, nextFireAfter, parseCron } from "./cron.js";
+
+//#region src/index.ts
+/** Canonical version constant. Mirrors the `package.json` version. */
+const VERSION = "0.5.0";
+/**
+* Build a cron trigger declaration. The expression is validated
+* eagerly — a malformed cron expression throws at registration time,
+* not at first fire.
+*
+* @stable
+*/
+function cron(id, expression, callback, options = {}) {
+	parseCron(expression);
+	return {
+		id,
+		kind: "cron",
+		spec: expression,
+		callback,
+		options
+	};
+}
+/** @stable */
+function interval(id, intervalMs, callback, options = {}) {
+	if (!Number.isFinite(intervalMs) || intervalMs <= 0) throw new Error(`[graphorin/triggers] interval(${id}): intervalMs must be > 0`);
+	return {
+		id,
+		kind: "interval",
+		spec: String(intervalMs),
+		callback,
+		options
+	};
+}
+/** @stable */
+function idle(id, idleMs, callback, options = {}) {
+	if (!Number.isFinite(idleMs) || idleMs <= 0) throw new Error(`[graphorin/triggers] idle(${id}): idleMs must be > 0`);
+	return {
+		id,
+		kind: "idle",
+		spec: String(idleMs),
+		callback,
+		options
+	};
+}
+/** @stable */
+function event(id, eventName, callback, options = {}) {
+	if (eventName.length === 0) throw new Error(`[graphorin/triggers] event(${id}): eventName must not be empty`);
+	return {
+		id,
+		kind: "event",
+		spec: eventName,
+		callback,
+		options
+	};
+}
+/** @stable */
+function createScheduler(options) {
+	return new SchedulerImpl(options);
+}
+/** Module-scoped flag — one WARN per process. */
+let LIB_MODE_WARNED = false;
+/**
+* Test-only helper. Drops the per-process WARN-once flag so the next
+* `register(...)` call in lib mode emits the warning again.
+*
+* @internal
+*/
+function _resetLibModeWarningForTesting() {
+	LIB_MODE_WARNED = false;
+}
+const DEFAULT_CATCHUP_WINDOW_MS = 1440 * 60 * 1e3;
+/**
+* Node clamps `setTimeout` delays beyond `2^31 - 1` ms to 1 ms — a
+* quarterly cron would fire immediately in a hot loop (RP-15). Delays
+* above this arm an intermediate wake-up that re-schedules instead.
+*/
+const MAX_TIMEOUT_MS = 2 ** 31 - 1;
+var SchedulerImpl = class {
+	#store;
+	#mode;
+	#now;
+	#setTimeout;
+	#clearTimeout;
+	#started = false;
+	#disposed = false;
+	#lastActivity;
+	#handles = /* @__PURE__ */ new Map();
+	#parsedCron = /* @__PURE__ */ new Map();
+	#declarations = /* @__PURE__ */ new Map();
+	#eventQueue = [];
+	#eventResolvers = [];
+	#closedEvents = false;
+	constructor(options) {
+		this.#store = options.store;
+		this.#mode = options.mode ?? "lib";
+		this.#now = options.now ?? Date.now;
+		this.#setTimeout = options.setTimeout ?? ((cb, ms) => globalThis.setTimeout(cb, ms));
+		this.#clearTimeout = options.clearTimeout ?? ((h) => globalThis.clearTimeout(h));
+		this.#lastActivity = this.#now();
+		if (options._resetLibModeFlag) LIB_MODE_WARNED = false;
+	}
+	async register(declaration) {
+		if (this.#mode === "lib" && declaration.options.acknowledgeLibMode !== true) {
+			if (!LIB_MODE_WARNED) {
+				LIB_MODE_WARNED = true;
+				console.warn("[graphorin/triggers] running in library mode — triggers fire only while the parent process is alive. Pass { acknowledgeLibMode: true } to suppress this warning.");
+				this.#publish({
+					type: "lib-mode-warning",
+					id: declaration.id
+				});
+			}
+		}
+		if (declaration.kind === "cron") this.#parsedCron.set(declaration.id, parseCron(declaration.spec));
+		this.#declarations.set(declaration.id, declaration);
+		const now = this.#now();
+		const existing = await this.#store.get(declaration.id);
+		const nextFireMs = this.#computeNextFire(declaration, existing, now);
+		const state = {
+			id: declaration.id,
+			kind: declaration.kind,
+			spec: declaration.spec,
+			callbackRef: declaration.id,
+			...existing?.lastFiredAt !== void 0 ? { lastFiredAt: existing.lastFiredAt } : {},
+			...nextFireMs !== null ? { nextFireAt: new Date(nextFireMs).toISOString() } : {},
+			missedFires: 0,
+			disabled: existing?.disabled === true,
+			catchupPolicy: declaration.options.catchupPolicy ?? "none",
+			maxCatchupRuns: declaration.options.maxCatchupRuns ?? 1,
+			catchupWindowMs: declaration.options.catchupWindowMs ?? DEFAULT_CATCHUP_WINDOW_MS,
+			...declaration.options.tags !== void 0 ? { tags: declaration.options.tags } : {},
+			createdAt: existing !== null ? existing.createdAt : new Date(now).toISOString(),
+			...existing !== null ? { updatedAt: new Date(now).toISOString() } : {}
+		};
+		await this.#store.upsert(state);
+		this.#publish({
+			type: "registered",
+			id: declaration.id,
+			kind: declaration.kind
+		});
+		if (existing !== null && (declaration.kind === "cron" || declaration.kind === "interval")) await this.#applyCatchup(state, existing, now);
+		if (this.#started) this.#schedule(declaration.id, state);
+		return state;
+	}
+	async unregister(id) {
+		this.#cancelHandle(id);
+		this.#declarations.delete(id);
+		this.#parsedCron.delete(id);
+		await this.#store.remove(id);
+	}
+	async list() {
+		return this.#store.list();
+	}
+	async start() {
+		if (this.#started || this.#disposed) return;
+		this.#started = true;
+		this.#publish({ type: "started" });
+		const states = await this.#store.list();
+		for (const state of states) {
+			if (state.disabled) continue;
+			this.#schedule(state.id, state);
+		}
+	}
+	async stop() {
+		if (!this.#started) return;
+		this.#started = false;
+		for (const id of [...this.#handles.keys()]) this.#cancelHandle(id);
+		this.#publish({ type: "stopped" });
+		this.#closedEvents = true;
+		while (this.#eventResolvers.length > 0) this.#eventResolvers.shift()?.({
+			done: true,
+			value: void 0
+		});
+	}
+	async emit(eventName, payload) {
+		for (const decl of this.#declarations.values()) if (decl.kind === "event" && decl.spec === eventName) await this.fire(decl.id, payload);
+	}
+	async fire(id, payload) {
+		const decl = this.#declarations.get(id);
+		if (decl === void 0) throw new Error(`[graphorin/triggers] no trigger registered with id '${id}'`);
+		const firedAt = this.#now();
+		this.#publish({
+			type: "fire-start",
+			id,
+			firedAt
+		});
+		const start = firedAt;
+		try {
+			await decl.callback(payload);
+			const durationMs = this.#now() - start;
+			this.#publish({
+				type: "fire-end",
+				id,
+				durationMs
+			});
+			const state = await this.#store.get(id);
+			const nextFireMs = state !== null && decl.kind !== "idle" ? this.#computeNextFire(decl, {
+				...state,
+				lastFiredAt: new Date(firedAt).toISOString()
+			}, this.#now()) : null;
+			await this.#store.recordFire(id, new Date(firedAt).toISOString(), nextFireMs !== null ? new Date(nextFireMs).toISOString() : void 0);
+			if (this.#started && decl.kind !== "idle") {
+				const refreshed = await this.#store.get(id);
+				if (refreshed !== null) this.#schedule(id, refreshed);
+			}
+		} catch (err) {
+			const durationMs = this.#now() - start;
+			this.#publish({
+				type: "fire-error",
+				id,
+				error: err,
+				durationMs
+			});
+			try {
+				const state = await this.#store.get(id);
+				if (state !== null && decl.kind !== "idle") {
+					const nextFireMs = this.#computeNextFire(decl, {
+						...state,
+						lastFiredAt: new Date(firedAt).toISOString()
+					}, this.#now());
+					const updated = {
+						...state,
+						...nextFireMs !== null ? { nextFireAt: new Date(nextFireMs).toISOString() } : {},
+						updatedAt: new Date(this.#now()).toISOString()
+					};
+					await this.#store.upsert(updated);
+					if (this.#started) this.#schedule(id, updated);
+				}
+			} catch {}
+		}
+	}
+	async setDisabled(id, disabled) {
+		const state = await this.#store.get(id);
+		if (state === null) throw new Error(`[graphorin/triggers] no trigger registered with id '${id}'`);
+		const nowIso = new Date(this.#now()).toISOString();
+		if (disabled) {
+			this.#cancelHandle(id);
+			const updated$1 = {
+				...state,
+				disabled: true,
+				updatedAt: nowIso
+			};
+			await this.#store.upsert(updated$1);
+			return updated$1;
+		}
+		const decl = this.#declarations.get(id);
+		const nextMs = decl !== void 0 ? this.#computeNextFire(decl, {
+			...state,
+			lastFiredAt: nowIso
+		}, this.#now()) : null;
+		const updated = {
+			...state,
+			disabled: false,
+			...nextMs !== null ? { nextFireAt: new Date(nextMs).toISOString() } : {},
+			updatedAt: nowIso
+		};
+		await this.#store.upsert(updated);
+		if (this.#started) this.#schedule(id, updated);
+		return updated;
+	}
+	recordActivity() {
+		this.#lastActivity = this.#now();
+		for (const decl of this.#declarations.values()) {
+			if (decl.kind !== "idle") continue;
+			this.#cancelHandle(decl.id);
+			const idleMs = Number.parseInt(decl.spec, 10);
+			const handle = this.#setTimeout(() => {
+				this.fire(decl.id);
+			}, idleMs);
+			this.#handles.set(decl.id, handle);
+		}
+	}
+	events() {
+		const queue = this.#eventQueue;
+		const resolvers = this.#eventResolvers;
+		const me = this;
+		return { [Symbol.asyncIterator]() {
+			return {
+				async next() {
+					if (queue.length > 0) return {
+						done: false,
+						value: queue.shift()
+					};
+					if (me.#closedEvents) return {
+						done: true,
+						value: void 0
+					};
+					return new Promise((resolve) => resolvers.push(resolve));
+				},
+				async return() {
+					return {
+						done: true,
+						value: void 0
+					};
+				}
+			};
+		} };
+	}
+	#publish(event$1) {
+		if (this.#closedEvents) return;
+		if (this.#eventResolvers.length > 0) {
+			this.#eventResolvers.shift()?.({
+				done: false,
+				value: event$1
+			});
+			return;
+		}
+		this.#eventQueue.push(event$1);
+	}
+	#computeNextFire(decl, state, now) {
+		switch (decl.kind) {
+			case "cron": {
+				const next = nextFireAfter(this.#parsedCron.get(decl.id) ?? parseCron(decl.spec), new Date(now));
+				return next === null ? null : next.getTime();
+			}
+			case "interval": {
+				const intervalMs = Number.parseInt(decl.spec, 10);
+				return (state?.lastFiredAt !== void 0 ? Date.parse(state.lastFiredAt) : now) + intervalMs;
+			}
+			case "idle": {
+				const idleMs = Number.parseInt(decl.spec, 10);
+				return this.#lastActivity + idleMs;
+			}
+			case "event": return null;
+		}
+	}
+	async #applyCatchup(state, existing, now) {
+		if (state.catchupPolicy === "none") return;
+		const decl = this.#declarations.get(state.id);
+		if (decl === void 0 || decl.kind !== "cron" && decl.kind !== "interval") return;
+		const lastFired = existing.lastFiredAt !== void 0 ? Date.parse(existing.lastFiredAt) : null;
+		if (lastFired === null) return;
+		if (lastFired < now - state.catchupWindowMs) return;
+		const SCAN_CAP = 1e3;
+		let missed = 0;
+		if (decl.kind === "cron") {
+			const parsed = this.#parsedCron.get(decl.id) ?? parseCron(decl.spec);
+			let cursor = lastFired;
+			while (missed < SCAN_CAP) {
+				const next = nextFireAfter(parsed, new Date(cursor));
+				if (next === null || next.getTime() > now) break;
+				cursor = next.getTime();
+				missed += 1;
+			}
+		} else {
+			const intervalMs = Number.parseInt(decl.spec, 10);
+			missed = Math.floor((now - lastFired) / intervalMs);
+		}
+		if (missed <= 0) return;
+		const toFire = state.catchupPolicy === "last" ? 1 : Math.min(missed, state.maxCatchupRuns);
+		for (let i = 0; i < toFire; i++) await this.fire(state.id);
+		const excess = missed - toFire;
+		if (excess > 0) {
+			const refreshed = await this.#store.get(state.id);
+			if (refreshed !== null) await this.#store.upsert({
+				...refreshed,
+				missedFires: excess
+			});
+		}
+		this.#publish({
+			type: "catchup-applied",
+			id: state.id,
+			missed
+		});
+	}
+	#schedule(id, state) {
+		this.#cancelHandle(id);
+		if (state.disabled) return;
+		const decl = this.#declarations.get(id);
+		if (decl === void 0) return;
+		if (decl.kind === "event") return;
+		let delay = null;
+		if (state.nextFireAt !== void 0) delay = Date.parse(state.nextFireAt) - this.#now();
+		else {
+			const next = this.#computeNextFire(decl, state, this.#now());
+			delay = next === null ? null : next - this.#now();
+		}
+		if (delay === null) return;
+		if (delay < 0) delay = 0;
+		if (delay > MAX_TIMEOUT_MS) {
+			const handle$1 = this.#setTimeout(() => {
+				this.#store.get(id).then((s) => {
+					if (s !== null) this.#schedule(id, s);
+				}).catch(() => {});
+			}, MAX_TIMEOUT_MS);
+			this.#handles.set(id, handle$1);
+			return;
+		}
+		const handle = this.#setTimeout(() => {
+			this.fire(id);
+		}, delay);
+		this.#handles.set(id, handle);
+	}
+	#cancelHandle(id) {
+		const handle = this.#handles.get(id);
+		if (handle !== void 0) {
+			this.#clearTimeout(handle);
+			this.#handles.delete(id);
+		}
+	}
+};
+
+//#endregion
+export { CronParseError, VERSION, _resetLibModeWarningForTesting, createScheduler, cron, event, idle, interval, nextFireAfter, parseCron };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#store","#mode","#now","#setTimeout","#clearTimeout","#lastActivity","#publish","#parsedCron","#declarations","#computeNextFire","state: TriggerState","#applyCatchup","#started","#schedule","#cancelHandle","#disposed","#handles","#closedEvents","#eventResolvers","updated: TriggerState","updated","#eventQueue","event","delay: number | null","handle"],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @graphorin/triggers — durable cron / interval / idle / event\n * trigger scheduler for the Graphorin framework.\n *\n * @packageDocumentation\n */\n\nimport type { TriggerState, TriggerStore } from '@graphorin/core/contracts';\nimport { nextFireAfter, type ParsedCron, parseCron } from './cron.js';\n\nexport { CronParseError, nextFireAfter, type ParsedCron, parseCron } from './cron.js';\n\n/** Canonical version constant. Mirrors the `package.json` version. */\nexport const VERSION = '0.5.0';\n\n/**\n * Catch-up policy applied when a trigger missed one or more fires\n * while the scheduler was offline.\n *\n * - `'none'` — drop missed fires (default; safest for personal-assistant scenarios).\n * - `'last'` — fire once on resume (best for cron-style daily jobs).\n * - `'all'` — fire each missed run up to `maxCatchupRuns` within `catchupWindowMs`.\n *\n * @stable\n */\nexport type CatchupPolicy = 'none' | 'last' | 'all';\n\n/** @stable */\nexport type TriggerKind = 'cron' | 'interval' | 'idle' | 'event';\n\n/** @stable */\nexport interface TriggerOptions {\n  readonly catchupPolicy?: CatchupPolicy;\n  readonly maxCatchupRuns?: number;\n  /**\n   * How far back (from the last successful fire) misses are honored.\n   * Catch-up counts REAL missed fires (RP-12), so the window must\n   * exceed the trigger period — a 24h window can never catch up a\n   * daily cron whose boundary is itself 24h after the last fire.\n   * Default 24h.\n   */\n  readonly catchupWindowMs?: number;\n  readonly tags?: ReadonlyArray<string>;\n  /**\n   * Suppress the one-time per-process library-mode WARN. Library\n   * callers acknowledging that triggers fire only as long as the\n   * process lives pass `true` here.\n   */\n  readonly acknowledgeLibMode?: boolean;\n}\n\n/**\n * Trigger callback. Receives an optional `payload` for `event`\n * triggers; for cron / interval / idle triggers `payload` is\n * `undefined`.\n *\n * @stable\n */\nexport type TriggerCallback = (payload?: unknown) => void | Promise<void>;\n\n/**\n * Public trigger declaration emitted by the helper functions\n * (`cron(...)`, `interval(...)`, `idle(...)`, `event(...)`).\n *\n * @stable\n */\nexport interface TriggerDeclaration {\n  readonly id: string;\n  readonly kind: TriggerKind;\n  readonly spec: string;\n  readonly callback: TriggerCallback;\n  readonly options: TriggerOptions;\n}\n\n/**\n * Build a cron trigger declaration. The expression is validated\n * eagerly — a malformed cron expression throws at registration time,\n * not at first fire.\n *\n * @stable\n */\nexport function cron(\n  id: string,\n  expression: string,\n  callback: TriggerCallback,\n  options: TriggerOptions = {},\n): TriggerDeclaration {\n  parseCron(expression);\n  return { id, kind: 'cron', spec: expression, callback, options };\n}\n\n/** @stable */\nexport function interval(\n  id: string,\n  intervalMs: number,\n  callback: TriggerCallback,\n  options: TriggerOptions = {},\n): TriggerDeclaration {\n  if (!Number.isFinite(intervalMs) || intervalMs <= 0) {\n    throw new Error(`[graphorin/triggers] interval(${id}): intervalMs must be > 0`);\n  }\n  return {\n    id,\n    kind: 'interval',\n    spec: String(intervalMs),\n    callback,\n    options,\n  };\n}\n\n/** @stable */\nexport function idle(\n  id: string,\n  idleMs: number,\n  callback: TriggerCallback,\n  options: TriggerOptions = {},\n): TriggerDeclaration {\n  if (!Number.isFinite(idleMs) || idleMs <= 0) {\n    throw new Error(`[graphorin/triggers] idle(${id}): idleMs must be > 0`);\n  }\n  return {\n    id,\n    kind: 'idle',\n    spec: String(idleMs),\n    callback,\n    options,\n  };\n}\n\n/** @stable */\nexport function event(\n  id: string,\n  eventName: string,\n  callback: TriggerCallback,\n  options: TriggerOptions = {},\n): TriggerDeclaration {\n  if (eventName.length === 0) {\n    throw new Error(`[graphorin/triggers] event(${id}): eventName must not be empty`);\n  }\n  return {\n    id,\n    kind: 'event',\n    spec: eventName,\n    callback,\n    options,\n  };\n}\n\n/**\n * Lifecycle event emitted by {@link Scheduler.events}. Useful for\n * tests and for piping into observability without monkey-patching.\n *\n * @stable\n */\nexport type SchedulerEvent =\n  | { readonly type: 'started' }\n  | { readonly type: 'stopped' }\n  | { readonly type: 'registered'; readonly id: string; readonly kind: TriggerKind }\n  | { readonly type: 'fire-start'; readonly id: string; readonly firedAt: number }\n  | { readonly type: 'fire-end'; readonly id: string; readonly durationMs: number }\n  | {\n      readonly type: 'fire-error';\n      readonly id: string;\n      readonly error: unknown;\n      readonly durationMs: number;\n    }\n  | { readonly type: 'catchup-applied'; readonly id: string; readonly missed: number }\n  | { readonly type: 'lib-mode-warning'; readonly id: string };\n\n/**\n * Options for {@link createScheduler}.\n *\n * @stable\n */\nexport interface CreateSchedulerOptions {\n  readonly store: TriggerStore;\n  /** Default `'lib'`. Server mode skips the lib-mode warning. */\n  readonly mode?: 'lib' | 'server';\n  /** Override the wall clock — used by tests. */\n  readonly now?: () => number;\n  /**\n   * Override `setTimeout`. The callback receives the chosen delay in\n   * milliseconds; the return value is the handle the scheduler\n   * later passes to `clearTimeout`. Tests inject a controllable timer.\n   */\n  readonly setTimeout?: (cb: () => void, ms: number) => unknown;\n  readonly clearTimeout?: (handle: unknown) => void;\n  /**\n   * Resets the per-process WARN-once flag. Used by the test suite to\n   * verify the warning fires exactly once per run.\n   *\n   * @internal\n   */\n  readonly _resetLibModeFlag?: boolean;\n}\n\n/**\n * Public Scheduler surface.\n *\n * @stable\n */\nexport interface Scheduler {\n  register(declaration: TriggerDeclaration): Promise<TriggerState>;\n  unregister(id: string): Promise<void>;\n  list(): Promise<readonly TriggerState[]>;\n  start(): Promise<void>;\n  stop(): Promise<void>;\n  /** Emit `eventName` to every registered `event` trigger. */\n  emit(eventName: string, payload?: unknown): Promise<void>;\n  /** Manually fire `id` (used by `graphorin triggers fire`, Phase 15). */\n  fire(id: string, payload?: unknown): Promise<void>;\n  /**\n   * Flip the persistent `disabled` flag (IP-17). Disabling cancels the\n   * armed timer but keeps the trigger registered + persisted; enabling\n   * recomputes the next fire from now and re-arms. The destructive\n   * removal is `unregister(...)`.\n   */\n  setDisabled(id: string, disabled: boolean): Promise<TriggerState>;\n  /** AsyncIterable lifecycle event stream. */\n  events(): AsyncIterable<SchedulerEvent>;\n  /** Notify the scheduler that the user / runtime is no longer idle. */\n  recordActivity(): void;\n}\n\n/** @stable */\nexport function createScheduler(options: CreateSchedulerOptions): Scheduler {\n  return new SchedulerImpl(options);\n}\n\n/** Module-scoped flag — one WARN per process. */\nlet LIB_MODE_WARNED = false;\n\n/**\n * Test-only helper. Drops the per-process WARN-once flag so the next\n * `register(...)` call in lib mode emits the warning again.\n *\n * @internal\n */\nexport function _resetLibModeWarningForTesting(): void {\n  LIB_MODE_WARNED = false;\n}\n\nconst DEFAULT_CATCHUP_WINDOW_MS = 24 * 60 * 60 * 1000;\n\n/**\n * Node clamps `setTimeout` delays beyond `2^31 - 1` ms to 1 ms — a\n * quarterly cron would fire immediately in a hot loop (RP-15). Delays\n * above this arm an intermediate wake-up that re-schedules instead.\n */\nconst MAX_TIMEOUT_MS = 2 ** 31 - 1;\n\nclass SchedulerImpl implements Scheduler {\n  readonly #store: TriggerStore;\n  readonly #mode: 'lib' | 'server';\n  readonly #now: () => number;\n  readonly #setTimeout: (cb: () => void, ms: number) => unknown;\n  readonly #clearTimeout: (handle: unknown) => void;\n  #started = false;\n  #disposed = false;\n  #lastActivity: number;\n  #handles: Map<string, unknown> = new Map();\n  #parsedCron: Map<string, ParsedCron> = new Map();\n  #declarations: Map<string, TriggerDeclaration> = new Map();\n  #eventQueue: SchedulerEvent[] = [];\n  #eventResolvers: Array<(value: IteratorResult<SchedulerEvent>) => void> = [];\n  #closedEvents = false;\n\n  constructor(options: CreateSchedulerOptions) {\n    this.#store = options.store;\n    this.#mode = options.mode ?? 'lib';\n    this.#now = options.now ?? Date.now;\n    this.#setTimeout = options.setTimeout ?? ((cb, ms) => globalThis.setTimeout(cb, ms));\n    this.#clearTimeout =\n      options.clearTimeout ?? ((h) => globalThis.clearTimeout(h as ReturnType<typeof setTimeout>));\n    this.#lastActivity = this.#now();\n    if (options._resetLibModeFlag) LIB_MODE_WARNED = false;\n  }\n\n  async register(declaration: TriggerDeclaration): Promise<TriggerState> {\n    if (this.#mode === 'lib' && declaration.options.acknowledgeLibMode !== true) {\n      if (!LIB_MODE_WARNED) {\n        LIB_MODE_WARNED = true;\n        console.warn(\n          `[graphorin/triggers] running in library mode — triggers fire only while the parent process is alive. ` +\n            `Pass { acknowledgeLibMode: true } to suppress this warning.`,\n        );\n        this.#publish({ type: 'lib-mode-warning', id: declaration.id });\n      }\n    }\n\n    if (declaration.kind === 'cron') {\n      this.#parsedCron.set(declaration.id, parseCron(declaration.spec));\n    }\n    this.#declarations.set(declaration.id, declaration);\n\n    const now = this.#now();\n    const existing = await this.#store.get(declaration.id);\n    const nextFireMs = this.#computeNextFire(declaration, existing, now);\n    const state: TriggerState = {\n      id: declaration.id,\n      kind: declaration.kind,\n      spec: declaration.spec,\n      callbackRef: declaration.id,\n      ...(existing?.lastFiredAt !== undefined ? { lastFiredAt: existing.lastFiredAt } : {}),\n      ...(nextFireMs !== null ? { nextFireAt: new Date(nextFireMs).toISOString() } : {}),\n      missedFires: 0,\n      disabled: existing?.disabled === true,\n      catchupPolicy: declaration.options.catchupPolicy ?? 'none',\n      maxCatchupRuns: declaration.options.maxCatchupRuns ?? 1,\n      catchupWindowMs: declaration.options.catchupWindowMs ?? DEFAULT_CATCHUP_WINDOW_MS,\n      ...(declaration.options.tags !== undefined ? { tags: declaration.options.tags } : {}),\n      createdAt: existing !== null ? existing.createdAt : new Date(now).toISOString(),\n      ...(existing !== null ? { updatedAt: new Date(now).toISOString() } : {}),\n    };\n    await this.#store.upsert(state);\n\n    this.#publish({ type: 'registered', id: declaration.id, kind: declaration.kind });\n\n    if (existing !== null && (declaration.kind === 'cron' || declaration.kind === 'interval')) {\n      await this.#applyCatchup(state, existing, now);\n    }\n\n    if (this.#started) this.#schedule(declaration.id, state);\n    return state;\n  }\n\n  async unregister(id: string): Promise<void> {\n    this.#cancelHandle(id);\n    this.#declarations.delete(id);\n    this.#parsedCron.delete(id);\n    await this.#store.remove(id);\n  }\n\n  async list(): Promise<readonly TriggerState[]> {\n    return this.#store.list();\n  }\n\n  async start(): Promise<void> {\n    if (this.#started || this.#disposed) return;\n    this.#started = true;\n    this.#publish({ type: 'started' });\n    const states = await this.#store.list();\n    for (const state of states) {\n      if (state.disabled) continue;\n      this.#schedule(state.id, state);\n    }\n  }\n\n  async stop(): Promise<void> {\n    if (!this.#started) return;\n    this.#started = false;\n    for (const id of [...this.#handles.keys()]) this.#cancelHandle(id);\n    this.#publish({ type: 'stopped' });\n    this.#closedEvents = true;\n    while (this.#eventResolvers.length > 0) {\n      const resolver = this.#eventResolvers.shift();\n      resolver?.({ done: true, value: undefined });\n    }\n  }\n\n  async emit(eventName: string, payload?: unknown): Promise<void> {\n    for (const decl of this.#declarations.values()) {\n      if (decl.kind === 'event' && decl.spec === eventName) {\n        await this.fire(decl.id, payload);\n      }\n    }\n  }\n\n  async fire(id: string, payload?: unknown): Promise<void> {\n    const decl = this.#declarations.get(id);\n    if (decl === undefined) {\n      throw new Error(`[graphorin/triggers] no trigger registered with id '${id}'`);\n    }\n    const firedAt = this.#now();\n    this.#publish({ type: 'fire-start', id, firedAt });\n    const start = firedAt;\n    try {\n      await decl.callback(payload);\n      const durationMs = this.#now() - start;\n      this.#publish({ type: 'fire-end', id, durationMs });\n      const state = await this.#store.get(id);\n      // RP-13: compute the next fire from THIS fire's timestamp — the\n      // persisted state still carries the PREVIOUS lastFiredAt, which\n      // for interval triggers yields `prev + interval ≈ now` and an\n      // immediate duplicate via the clamped-to-0 delay. Idle triggers\n      // never self-reschedule: their next window starts only when\n      // `recordActivity()` observes new activity (a fire-driven re-arm\n      // would compute a stale `lastActivity + idleMs`, clamp to 0 and\n      // refire in a loop).\n      const nextFireMs =\n        state !== null && decl.kind !== 'idle'\n          ? this.#computeNextFire(\n              decl,\n              { ...state, lastFiredAt: new Date(firedAt).toISOString() },\n              this.#now(),\n            )\n          : null;\n      await this.#store.recordFire(\n        id,\n        new Date(firedAt).toISOString(),\n        nextFireMs !== null ? new Date(nextFireMs).toISOString() : undefined,\n      );\n      if (this.#started && decl.kind !== 'idle') {\n        const refreshed = await this.#store.get(id);\n        if (refreshed !== null) this.#schedule(id, refreshed);\n      }\n    } catch (err) {\n      const durationMs = this.#now() - start;\n      this.#publish({ type: 'fire-error', id, error: err, durationMs });\n      // RP-14: the one-shot timer is consumed by this fire — recompute\n      // and persist the next fire WITHOUT recording a successful fire\n      // (lastFiredAt stays put), and re-arm, so a single callback\n      // failure cannot permanently silence a daily cron.\n      try {\n        const state = await this.#store.get(id);\n        if (state !== null && decl.kind !== 'idle') {\n          const nextFireMs = this.#computeNextFire(\n            decl,\n            { ...state, lastFiredAt: new Date(firedAt).toISOString() },\n            this.#now(),\n          );\n          const updated: TriggerState = {\n            ...state,\n            ...(nextFireMs !== null ? { nextFireAt: new Date(nextFireMs).toISOString() } : {}),\n            updatedAt: new Date(this.#now()).toISOString(),\n          };\n          await this.#store.upsert(updated);\n          if (this.#started) this.#schedule(id, updated);\n        }\n      } catch {\n        // Best-effort re-arm — a store failure here must not become an\n        // unhandled rejection out of the timer callback.\n      }\n    }\n  }\n\n  async setDisabled(id: string, disabled: boolean): Promise<TriggerState> {\n    const state = await this.#store.get(id);\n    if (state === null) {\n      throw new Error(`[graphorin/triggers] no trigger registered with id '${id}'`);\n    }\n    const nowIso = new Date(this.#now()).toISOString();\n    if (disabled) {\n      this.#cancelHandle(id);\n      const updated: TriggerState = { ...state, disabled: true, updatedAt: nowIso };\n      await this.#store.upsert(updated);\n      return updated;\n    }\n    // Re-enable: recompute the next fire from NOW (a stale persisted\n    // nextFireAt from before the disable would otherwise clamp to 0 and\n    // fire immediately), then re-arm.\n    const decl = this.#declarations.get(id);\n    const nextMs =\n      decl !== undefined\n        ? this.#computeNextFire(decl, { ...state, lastFiredAt: nowIso }, this.#now())\n        : null;\n    const updated: TriggerState = {\n      ...state,\n      disabled: false,\n      ...(nextMs !== null ? { nextFireAt: new Date(nextMs).toISOString() } : {}),\n      updatedAt: nowIso,\n    };\n    await this.#store.upsert(updated);\n    if (this.#started) this.#schedule(id, updated);\n    return updated;\n  }\n\n  recordActivity(): void {\n    this.#lastActivity = this.#now();\n    // Reschedule idle triggers so they treat \"now\" as the start of\n    // their idle window.\n    for (const decl of this.#declarations.values()) {\n      if (decl.kind !== 'idle') continue;\n      this.#cancelHandle(decl.id);\n      const idleMs = Number.parseInt(decl.spec, 10);\n      const handle = this.#setTimeout(() => {\n        void this.fire(decl.id);\n      }, idleMs);\n      this.#handles.set(decl.id, handle);\n    }\n  }\n\n  events(): AsyncIterable<SchedulerEvent> {\n    const queue = this.#eventQueue;\n    const resolvers = this.#eventResolvers;\n    const me = this;\n    return {\n      [Symbol.asyncIterator](): AsyncIterator<SchedulerEvent> {\n        return {\n          async next(): Promise<IteratorResult<SchedulerEvent>> {\n            if (queue.length > 0) {\n              const value = queue.shift() as SchedulerEvent;\n              return { done: false, value };\n            }\n            if (me.#closedEvents) return { done: true, value: undefined };\n            return new Promise((resolve) => resolvers.push(resolve));\n          },\n          async return(): Promise<IteratorResult<SchedulerEvent>> {\n            return { done: true, value: undefined };\n          },\n        };\n      },\n    };\n  }\n\n  // ---------------------------------------------------------------------------\n\n  #publish(event: SchedulerEvent): void {\n    if (this.#closedEvents) return;\n    if (this.#eventResolvers.length > 0) {\n      const resolver = this.#eventResolvers.shift();\n      resolver?.({ done: false, value: event });\n      return;\n    }\n    this.#eventQueue.push(event);\n  }\n\n  #computeNextFire(\n    decl: TriggerDeclaration,\n    state: TriggerState | null,\n    now: number,\n  ): number | null {\n    switch (decl.kind) {\n      case 'cron': {\n        const parsed = this.#parsedCron.get(decl.id) ?? parseCron(decl.spec);\n        const next = nextFireAfter(parsed, new Date(now));\n        return next === null ? null : next.getTime();\n      }\n      case 'interval': {\n        const intervalMs = Number.parseInt(decl.spec, 10);\n        const last = state?.lastFiredAt !== undefined ? Date.parse(state.lastFiredAt) : now;\n        return last + intervalMs;\n      }\n      case 'idle': {\n        const idleMs = Number.parseInt(decl.spec, 10);\n        return this.#lastActivity + idleMs;\n      }\n      case 'event':\n        return null;\n    }\n  }\n\n  async #applyCatchup(state: TriggerState, existing: TriggerState, now: number): Promise<void> {\n    if (state.catchupPolicy === 'none') return;\n    const decl = this.#declarations.get(state.id);\n    if (decl === undefined || (decl.kind !== 'cron' && decl.kind !== 'interval')) return;\n    const lastFired = existing.lastFiredAt !== undefined ? Date.parse(existing.lastFiredAt) : null;\n    if (lastFired === null) return;\n    if (lastFired < now - state.catchupWindowMs) return;\n\n    // RP-12: count the REAL missed fires by walking the schedule from\n    // the last successful fire to now — a restart with zero crossed\n    // boundaries must apply zero catch-up (the old code fired `1` /\n    // `maxCatchupRuns` times unconditionally).\n    const SCAN_CAP = 1000;\n    let missed = 0;\n    if (decl.kind === 'cron') {\n      const parsed = this.#parsedCron.get(decl.id) ?? parseCron(decl.spec);\n      let cursor = lastFired;\n      while (missed < SCAN_CAP) {\n        const next = nextFireAfter(parsed, new Date(cursor));\n        if (next === null || next.getTime() > now) break;\n        cursor = next.getTime();\n        missed += 1;\n      }\n    } else {\n      const intervalMs = Number.parseInt(decl.spec, 10);\n      missed = Math.floor((now - lastFired) / intervalMs);\n    }\n    if (missed <= 0) return;\n\n    const toFire = state.catchupPolicy === 'last' ? 1 : Math.min(missed, state.maxCatchupRuns);\n    for (let i = 0; i < toFire; i++) {\n      await this.fire(state.id);\n    }\n    // The overflow beyond what we re-ran is recorded for health/CLI.\n    const excess = missed - toFire;\n    if (excess > 0) {\n      const refreshed = await this.#store.get(state.id);\n      if (refreshed !== null) {\n        await this.#store.upsert({ ...refreshed, missedFires: excess });\n      }\n    }\n    this.#publish({ type: 'catchup-applied', id: state.id, missed });\n  }\n\n  #schedule(id: string, state: TriggerState): void {\n    this.#cancelHandle(id);\n    if (state.disabled) return;\n    const decl = this.#declarations.get(id);\n    if (decl === undefined) return;\n    if (decl.kind === 'event') return;\n\n    let delay: number | null = null;\n    if (state.nextFireAt !== undefined) {\n      delay = Date.parse(state.nextFireAt) - this.#now();\n    } else {\n      const next = this.#computeNextFire(decl, state, this.#now());\n      delay = next === null ? null : next - this.#now();\n    }\n    if (delay === null) return;\n    if (delay < 0) delay = 0;\n\n    if (delay > MAX_TIMEOUT_MS) {\n      // RP-15: chunk the wait — the intermediate wake-up re-reads the\n      // freshest state and re-schedules (it never fires the callback).\n      const handle = this.#setTimeout(() => {\n        void this.#store\n          .get(id)\n          .then((s) => {\n            if (s !== null) this.#schedule(id, s);\n          })\n          .catch(() => {});\n      }, MAX_TIMEOUT_MS);\n      this.#handles.set(id, handle);\n      return;\n    }\n\n    const handle = this.#setTimeout(() => {\n      void this.fire(id);\n    }, delay);\n    this.#handles.set(id, handle);\n  }\n\n  #cancelHandle(id: string): void {\n    const handle = this.#handles.get(id);\n    if (handle !== undefined) {\n      this.#clearTimeout(handle);\n      this.#handles.delete(id);\n    }\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@graphorin/triggers",
+  "version": "0.5.0",
+  "description": "Background-task scheduler for the Graphorin framework. Ships durable cron / interval / idle / event triggers with the same code path in library and server modes, an in-tree 5-field cron parser, per-trigger catch-up policies (`'none'` default; `'last'` or `'all'` opt-in), and an AsyncIterable lifecycle event stream so consumers can plug into observability without monkey-patching.",
+  "license": "MIT",
+  "author": "Oleksiy Stepurenko",
+  "homepage": "https://github.com/o-stepper/graphorin/tree/main/packages/triggers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/graphorin.git",
+    "directory": "packages/triggers"
+  },
+  "bugs": {
+    "url": "https://github.com/o-stepper/graphorin/issues"
+  },
+  "keywords": [
+    "graphorin",
+    "ai",
+    "agents",
+    "framework",
+    "triggers",
+    "scheduler",
+    "cron",
+    "background-tasks",
+    "durable"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cron": {
+      "types": "./dist/cron.d.ts",
+      "import": "./dist/cron.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@graphorin/core": "0.5.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@graphorin/store-sqlite": "0.5.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  }
+}