@graphorin/triggers 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @graphorin/triggers
 
+## 0.7.0
+
+### Minor Changes
+
+- [#154](https://github.com/o-stepper/graphorin/pull/154) [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04) Thanks [@o-stepper](https://github.com/o-stepper)! - W-072: every export map's `import` condition becomes `default`, and the Node floor rises to `>=22.12.0`.
+
+  CJS consumers previously hit a bewildering `ERR_PACKAGE_PATH_NOT_EXPORTED` instead of a clear ESM-only signal. With the `default` condition, plain `require('@graphorin/core')` works via Node's stable `require(esm)` - which shipped in 22.12, hence the engines bump across every workspace manifest (packages, examples, benchmarks, docs; enforced by the widened mvp-readiness sweep). No dual-instance hazard: there is no CJS build, `require()` returns the same ESM module instance. ESM consumers are unaffected (`default` serves both paths; `types` stays first). The pack gate now runs attw under the full `node16` profile (was `esm-only`) and adds a runtime `require(esm)` smoke against the packed tarballs. Installs on Node 22.0-22.11 with `engine-strict` will refuse - upgrade Node (see the migration guide).
+
+### Patch Changes
+
+- [#164](https://github.com/o-stepper/graphorin/pull/164) [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00) Thanks [@o-stepper](https://github.com/o-stepper)! - Tarballs now ship `src/` so the published `dist/**/*.d.ts.map` files actually work (W-136): the maps referenced `../src/*.ts` that the `files` whitelist excluded, so go-to-definition fell back into `.d.ts` and the shipped maps were dead weight. The pack gate gains a `map-integrity` leg: every source referenced by a shipped map must resolve inside the tarball (or be embedded via `sourcesContent`), with an anti-vacuous guard - a package whose tsdown config emits declaration maps must contain a non-zero number of `.d.ts.map` files, so a cache-restored dist that silently dropped maps fails the gate instead of passing vacuously. `mvp-readiness` now requires `src` in every publishable `files` array.
+
+- [#164](https://github.com/o-stepper/graphorin/pull/164) [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00) Thanks [@o-stepper](https://github.com/o-stepper)! - Every published package now declares its tree-shaking contract via `sideEffects` (W-137): 18 packages audited to a pure module scope get `false`, the CLI declares its bin entry (`["./dist/bin/*"]`), and `@graphorin/security` gets an explicit `true` - its secrets subsystem registers built-in resolvers and the SecretValue caller-context provider at import time, so marking it pure would let bundlers drop those registrations. `mvp-readiness` now fails any publishable manifest without a declared `sideEffects`, closing the drift for future packages.
+
+- Updated dependencies [[`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`832f22e`](https://github.com/o-stepper/graphorin/commit/832f22e570b8c3175c1adeb4c150070cbd131534), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04)]:
+  - @graphorin/core@0.7.0
+
+## 0.6.1
+
+### Patch Changes
+
+- [#142](https://github.com/o-stepper/graphorin/pull/142) [`436d6ca`](https://github.com/o-stepper/graphorin/commit/436d6ca5ebbd16df094e915682d3915c279a8430) Thanks [@o-stepper](https://github.com/o-stepper)! - Version constants and version-bearing strings now derive from each package's manifest at build time (`VERSION = pkg.version`; writer ids, client/server info, OTLP framework attributes, build-info metrics interpolate it). No behavioral change at the current version: the rendered strings are byte-identical. A release bump no longer edits source; the new `check-version-consistency` gate fails any reintroduced hardcoded framework version.
+
+- Updated dependencies [[`436d6ca`](https://github.com/o-stepper/graphorin/commit/436d6ca5ebbd16df094e915682d3915c279a8430)]:
+  - @graphorin/core@0.6.1
+
 ## 0.6.0
 
 ### Patch Changes

package/README.md

@@ -54,6 +54,11 @@ scheduler.register(
   }),
 );
 
+// Idle triggers measure idleness relative to the activity feed:
+// call this from your request/message handlers so "idle" means
+// "no user activity", not "process started 5 minutes ago".
+scheduler.recordActivity();
+
 scheduler.register(
   event('on-handoff', 'session.handoff', async (payload) => {
     // …fires whenever a handoff event is published
@@ -69,4 +74,4 @@ MIT © 2026 Oleksiy Stepurenko.
 
 ---
 
-**Project Graphorin** · v0.6.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>
+**Project Graphorin** · v0.7.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/index.d.ts

@@ -3,8 +3,7 @@ import { TriggerState, TriggerStore } from "@graphorin/core/contracts";
 
 //#region src/index.d.ts
 
-/** Canonical version constant. Mirrors the `package.json` version. */
-declare const VERSION = "0.6.0";
+declare const VERSION: string;
 /**
  * Catch-up policy applied when a trigger missed one or more fires
  * while the scheduler was offline.

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;AA4DY,cA7CC,OA6Cc,EAAA,MAAiC;AAQ5D;;;;;AAeA;;;;;AAWgB,KAnEJ,aAAA,GAmEY,MAAA,GAAA,MAAA,GAAA,KAAA;;AAIb,KApEC,WAAA,GAoED,MAAA,GAAA,UAAA,GAAA,MAAA,GAAA,OAAA;;AACU,UAlEJ,cAAA,CAkEI;EAcL,SAAI,aAAA,CAAA,EA/EO,aA+EP;EAGR,SAAA,cAAA,CAAA,EAAA,MAAA;EACD;;;AAeX;;;;EAKqB,SAAA,eAAA,CAAA,EAAA,MAAA;EAmBT,SAAA,IAAA,CAAA,EAhHM,aAmHqD,CAAA,MAAA,CAAA;EAiBtD;AA2BjB;;;;EAE0B,SAAA,kBAAA,CAAA,EAAA,OAAA;;;;;;;;;AAgBA,KAjKd,eAAA,GAiKc,CAAA,OAAA,CAAA,EAAA,OAAA,EAAA,GAAA,IAAA,GAjKkC,OAiKlC,CAAA,IAAA,CAAA;;;AAM1B;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

@@ -1,8 +1,9 @@
 import { CronParseError, nextFireAfter, parseCron } from "./cron.js";
+import { version } from "./package.js";
 
 //#region src/index.ts
-/** Canonical version constant. Mirrors the `package.json` version. */
-const VERSION = "0.6.0";
+/** Canonical version constant, derived from `package.json` at build time. */
+const VERSION = version;
 /**
 * Build a cron trigger declaration. The expression is validated
 * eagerly - a malformed cron expression throws at registration time,

package/dist/index.js.map

@@ -1 +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.6.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    // periphery (P-14): never (re)arm idle timers on a scheduler that\n    // is not started - a stopped scheduler firing callbacks is a\n    // lifecycle violation. The activity timestamp is still recorded so\n    // a later start() computes the idle window correctly.\n    if (!this.#started) return;\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        const next = last + intervalMs;\n        // periphery-11: after downtime `last + interval` is in the past;\n        // the schedule clamp turned that into an IMMEDIATE fire even\n        // under `catchupPolicy: 'none'` (\"drop missed fires\"). Advance\n        // to the next FUTURE boundary on the original cadence - missed\n        // boundaries are the catch-up machinery's business, not the\n        // base schedule's. (Cron already behaves this way:\n        // `nextFireAfter(now)` is always future.)\n        if (next <= now && Number.isFinite(intervalMs) && intervalMs > 0) {\n          const missedBoundaries = Math.floor((now - last) / intervalMs) + 1;\n          return last + missedBoundaries * intervalMs;\n        }\n        return next;\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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"}
+{"version":3,"file":"index.js","names":["VERSION: string","pkg.version","#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, derived from `package.json` at build time. */\nimport pkg from '../package.json' with { type: 'json' };\n\nexport const VERSION: string = pkg.version;\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    // periphery (P-14): never (re)arm idle timers on a scheduler that\n    // is not started - a stopped scheduler firing callbacks is a\n    // lifecycle violation. The activity timestamp is still recorded so\n    // a later start() computes the idle window correctly.\n    if (!this.#started) return;\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        const next = last + intervalMs;\n        // periphery-11: after downtime `last + interval` is in the past;\n        // the schedule clamp turned that into an IMMEDIATE fire even\n        // under `catchupPolicy: 'none'` (\"drop missed fires\"). Advance\n        // to the next FUTURE boundary on the original cadence - missed\n        // boundaries are the catch-up machinery's business, not the\n        // base schedule's. (Cron already behaves this way:\n        // `nextFireAfter(now)` is always future.)\n        if (next <= now && Number.isFinite(intervalMs) && intervalMs > 0) {\n          const missedBoundaries = Math.floor((now - last) / intervalMs) + 1;\n          return last + missedBoundaries * intervalMs;\n        }\n        return next;\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/dist/package.js

@@ -0,0 +1,6 @@
+//#region package.json
+var version = "0.7.0";
+
+//#endregion
+export { version };
+//# sourceMappingURL=package.js.map

package/dist/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","names":[],"sources":["../package.json"],"sourcesContent":["{\n  \"name\": \"@graphorin/triggers\",\n  \"version\": \"0.7.0\",\n  \"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.\",\n  \"license\": \"MIT\",\n  \"author\": \"Oleksiy Stepurenko\",\n  \"homepage\": \"https://github.com/o-stepper/graphorin/tree/main/packages/triggers\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/o-stepper/graphorin.git\",\n    \"directory\": \"packages/triggers\"\n  },\n  \"bugs\": {\n    \"url\": \"https://github.com/o-stepper/graphorin/issues\"\n  },\n  \"keywords\": [\n    \"graphorin\",\n    \"ai\",\n    \"agents\",\n    \"framework\",\n    \"triggers\",\n    \"scheduler\",\n    \"cron\",\n    \"background-tasks\",\n    \"durable\"\n  ],\n  \"type\": \"module\",\n  \"sideEffects\": false,\n  \"engines\": {\n    \"node\": \">=22.12.0\"\n  },\n  \"main\": \"./dist/index.js\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"default\": \"./dist/index.js\"\n    },\n    \"./cron\": {\n      \"types\": \"./dist/cron.d.ts\",\n      \"default\": \"./dist/cron.js\"\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"files\": [\n    \"dist\",\n    \"src\",\n    \"README.md\",\n    \"CHANGELOG.md\",\n    \"LICENSE\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsdown\",\n    \"typecheck\": \"tsc --noEmit && tsc -p tsconfig.tests.json\",\n    \"test\": \"vitest run\",\n    \"lint\": \"biome check .\",\n    \"clean\": \"rimraf dist .turbo *.tsbuildinfo\"\n  },\n  \"dependencies\": {\n    \"@graphorin/core\": \"workspace:*\"\n  },\n  \"publishConfig\": {\n    \"access\": \"public\",\n    \"provenance\": true\n  },\n  \"devDependencies\": {\n    \"@graphorin/store-sqlite\": \"workspace:*\"\n  }\n}\n"],"mappings":";cAEa"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/triggers",
-  "version": "0.6.0",
+  "version": "0.7.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",
@@ -25,8 +25,9 @@
     "durable"
   ],
   "type": "module",
+  "sideEffects": false,
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -34,29 +35,30 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     },
     "./cron": {
       "types": "./dist/cron.d.ts",
-      "import": "./dist/cron.js"
+      "default": "./dist/cron.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@graphorin/core": "0.6.0"
+    "@graphorin/core": "0.7.0"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "devDependencies": {
-    "@graphorin/store-sqlite": "0.6.0"
+    "@graphorin/store-sqlite": "0.7.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/cron.ts

@@ -0,0 +1,221 @@
+/**
+ * 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 */
+export class CronParseError extends Error {
+  override readonly name = 'CronParseError';
+  constructor(
+    public readonly expression: string,
+    message: string,
+  ) {
+    super(`[graphorin/triggers] cron expression '${expression}': ${message}`);
+  }
+}
+
+/** @stable */
+export 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>;
+}
+
+interface FieldRange {
+  readonly min: number;
+  readonly max: number;
+}
+
+const RANGES: Readonly<Record<keyof Omit<ParsedCron, 'expression'>, FieldRange>> = {
+  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
+ */
+export function parseCron(expression: string): ParsedCron {
+  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 as [
+    string,
+    string,
+    string,
+    string,
+    string,
+  ];
+  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: string,
+  raw: string,
+  range: FieldRange,
+  expression: string,
+): ReadonlySet<number> {
+  const out = new Set<number>();
+  for (const part of raw.split(',')) {
+    if (part.length === 0) {
+      throw new CronParseError(expression, `field '${name}' has an empty list element`);
+    }
+    let stepStr: string | undefined;
+    let bodyStr = part;
+    if (part.includes('/')) {
+      const [body, step] = part.split('/', 2);
+      bodyStr = body ?? '';
+      stepStr = step;
+    }
+    const step = stepStr === undefined ? 1 : Number.parseInt(stepStr, 10);
+    if (!Number.isFinite(step) || step <= 0) {
+      throw new CronParseError(expression, `field '${name}' has invalid step '${stepStr}'`);
+    }
+    let from: number;
+    let to: number;
+    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 === undefined ? 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: string, raw: string | undefined, expression: string): number {
+  if (raw === undefined || 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
+ */
+export function nextFireAfter(parsed: ParsedCron, from: Date): Date | null {
+  const start = new Date(from.getTime() + 60_000);
+  start.setUTCSeconds(0, 0);
+  const horizon = new Date(start.getTime() + 4 * 365 * 24 * 60 * 60 * 1000);
+
+  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() + 24 * 60 * 60 * 1000);
+      cursor.setUTCHours(0, 0, 0, 0);
+      continue;
+    }
+    if (!parsed.hour.has(cursor.getUTCHours())) {
+      cursor = new Date(cursor.getTime() + 60 * 60 * 1000);
+      cursor.setUTCMinutes(0, 0, 0);
+      continue;
+    }
+    if (!parsed.minute.has(cursor.getUTCMinutes())) {
+      cursor = new Date(cursor.getTime() + 60_000);
+      cursor.setUTCSeconds(0, 0);
+      continue;
+    }
+    return cursor;
+  }
+  return null;
+}

package/src/index.ts

@@ -0,0 +1,651 @@
+/**
+ * @graphorin/triggers - durable cron / interval / idle / event
+ * trigger scheduler for the Graphorin framework.
+ *
+ * @packageDocumentation
+ */
+
+import type { TriggerState, TriggerStore } from '@graphorin/core/contracts';
+import { nextFireAfter, type ParsedCron, parseCron } from './cron.js';
+
+export { CronParseError, nextFireAfter, type ParsedCron, parseCron } from './cron.js';
+
+/** Canonical version constant, derived from `package.json` at build time. */
+import pkg from '../package.json' with { type: 'json' };
+
+export const VERSION: string = pkg.version;
+
+/**
+ * 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
+ */
+export type CatchupPolicy = 'none' | 'last' | 'all';
+
+/** @stable */
+export type TriggerKind = 'cron' | 'interval' | 'idle' | 'event';
+
+/** @stable */
+export 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
+ */
+export type TriggerCallback = (payload?: unknown) => void | Promise<void>;
+
+/**
+ * Public trigger declaration emitted by the helper functions
+ * (`cron(...)`, `interval(...)`, `idle(...)`, `event(...)`).
+ *
+ * @stable
+ */
+export 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
+ */
+export function cron(
+  id: string,
+  expression: string,
+  callback: TriggerCallback,
+  options: TriggerOptions = {},
+): TriggerDeclaration {
+  parseCron(expression);
+  return { id, kind: 'cron', spec: expression, callback, options };
+}
+
+/** @stable */
+export function interval(
+  id: string,
+  intervalMs: number,
+  callback: TriggerCallback,
+  options: TriggerOptions = {},
+): TriggerDeclaration {
+  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 */
+export function idle(
+  id: string,
+  idleMs: number,
+  callback: TriggerCallback,
+  options: TriggerOptions = {},
+): TriggerDeclaration {
+  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 */
+export function event(
+  id: string,
+  eventName: string,
+  callback: TriggerCallback,
+  options: TriggerOptions = {},
+): TriggerDeclaration {
+  if (eventName.length === 0) {
+    throw new Error(`[graphorin/triggers] event(${id}): eventName must not be empty`);
+  }
+  return {
+    id,
+    kind: 'event',
+    spec: eventName,
+    callback,
+    options,
+  };
+}
+
+/**
+ * Lifecycle event emitted by {@link Scheduler.events}. Useful for
+ * tests and for piping into observability without monkey-patching.
+ *
+ * @stable
+ */
+export 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
+ */
+export 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
+ */
+export 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 */
+export function createScheduler(options: CreateSchedulerOptions): Scheduler {
+  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
+ */
+export function _resetLibModeWarningForTesting(): void {
+  LIB_MODE_WARNED = false;
+}
+
+const DEFAULT_CATCHUP_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * 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;
+
+class SchedulerImpl implements Scheduler {
+  readonly #store: TriggerStore;
+  readonly #mode: 'lib' | 'server';
+  readonly #now: () => number;
+  readonly #setTimeout: (cb: () => void, ms: number) => unknown;
+  readonly #clearTimeout: (handle: unknown) => void;
+  #started = false;
+  #disposed = false;
+  #lastActivity: number;
+  #handles: Map<string, unknown> = new Map();
+  #parsedCron: Map<string, ParsedCron> = new Map();
+  #declarations: Map<string, TriggerDeclaration> = new Map();
+  #eventQueue: SchedulerEvent[] = [];
+  #eventResolvers: Array<(value: IteratorResult<SchedulerEvent>) => void> = [];
+  #closedEvents = false;
+
+  constructor(options: CreateSchedulerOptions) {
+    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 as ReturnType<typeof setTimeout>));
+    this.#lastActivity = this.#now();
+    if (options._resetLibModeFlag) LIB_MODE_WARNED = false;
+  }
+
+  async register(declaration: TriggerDeclaration): Promise<TriggerState> {
+    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: TriggerState = {
+      id: declaration.id,
+      kind: declaration.kind,
+      spec: declaration.spec,
+      callbackRef: declaration.id,
+      ...(existing?.lastFiredAt !== undefined ? { 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 !== undefined ? { 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: string): Promise<void> {
+    this.#cancelHandle(id);
+    this.#declarations.delete(id);
+    this.#parsedCron.delete(id);
+    await this.#store.remove(id);
+  }
+
+  async list(): Promise<readonly TriggerState[]> {
+    return this.#store.list();
+  }
+
+  async start(): Promise<void> {
+    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(): Promise<void> {
+    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) {
+      const resolver = this.#eventResolvers.shift();
+      resolver?.({ done: true, value: undefined });
+    }
+  }
+
+  async emit(eventName: string, payload?: unknown): Promise<void> {
+    for (const decl of this.#declarations.values()) {
+      if (decl.kind === 'event' && decl.spec === eventName) {
+        await this.fire(decl.id, payload);
+      }
+    }
+  }
+
+  async fire(id: string, payload?: unknown): Promise<void> {
+    const decl = this.#declarations.get(id);
+    if (decl === undefined) {
+      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);
+      // RP-13: compute the next fire from THIS fire's timestamp - the
+      // persisted state still carries the PREVIOUS lastFiredAt, which
+      // for interval triggers yields `prev + interval ≈ now` and an
+      // immediate duplicate via the clamped-to-0 delay. Idle triggers
+      // never self-reschedule: their next window starts only when
+      // `recordActivity()` observes new activity (a fire-driven re-arm
+      // would compute a stale `lastActivity + idleMs`, clamp to 0 and
+      // refire in a loop).
+      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() : undefined,
+      );
+      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 });
+      // RP-14: the one-shot timer is consumed by this fire - recompute
+      // and persist the next fire WITHOUT recording a successful fire
+      // (lastFiredAt stays put), and re-arm, so a single callback
+      // failure cannot permanently silence a daily cron.
+      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: TriggerState = {
+            ...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 {
+        // Best-effort re-arm - a store failure here must not become an
+        // unhandled rejection out of the timer callback.
+      }
+    }
+  }
+
+  async setDisabled(id: string, disabled: boolean): Promise<TriggerState> {
+    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: TriggerState = { ...state, disabled: true, updatedAt: nowIso };
+      await this.#store.upsert(updated);
+      return updated;
+    }
+    // Re-enable: recompute the next fire from NOW (a stale persisted
+    // nextFireAt from before the disable would otherwise clamp to 0 and
+    // fire immediately), then re-arm.
+    const decl = this.#declarations.get(id);
+    const nextMs =
+      decl !== undefined
+        ? this.#computeNextFire(decl, { ...state, lastFiredAt: nowIso }, this.#now())
+        : null;
+    const updated: TriggerState = {
+      ...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(): void {
+    this.#lastActivity = this.#now();
+    // periphery (P-14): never (re)arm idle timers on a scheduler that
+    // is not started - a stopped scheduler firing callbacks is a
+    // lifecycle violation. The activity timestamp is still recorded so
+    // a later start() computes the idle window correctly.
+    if (!this.#started) return;
+    // Reschedule idle triggers so they treat "now" as the start of
+    // their idle window.
+    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(() => {
+        void this.fire(decl.id);
+      }, idleMs);
+      this.#handles.set(decl.id, handle);
+    }
+  }
+
+  events(): AsyncIterable<SchedulerEvent> {
+    const queue = this.#eventQueue;
+    const resolvers = this.#eventResolvers;
+    const me = this;
+    return {
+      [Symbol.asyncIterator](): AsyncIterator<SchedulerEvent> {
+        return {
+          async next(): Promise<IteratorResult<SchedulerEvent>> {
+            if (queue.length > 0) {
+              const value = queue.shift() as SchedulerEvent;
+              return { done: false, value };
+            }
+            if (me.#closedEvents) return { done: true, value: undefined };
+            return new Promise((resolve) => resolvers.push(resolve));
+          },
+          async return(): Promise<IteratorResult<SchedulerEvent>> {
+            return { done: true, value: undefined };
+          },
+        };
+      },
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+
+  #publish(event: SchedulerEvent): void {
+    if (this.#closedEvents) return;
+    if (this.#eventResolvers.length > 0) {
+      const resolver = this.#eventResolvers.shift();
+      resolver?.({ done: false, value: event });
+      return;
+    }
+    this.#eventQueue.push(event);
+  }
+
+  #computeNextFire(
+    decl: TriggerDeclaration,
+    state: TriggerState | null,
+    now: number,
+  ): number | null {
+    switch (decl.kind) {
+      case 'cron': {
+        const parsed = this.#parsedCron.get(decl.id) ?? parseCron(decl.spec);
+        const next = nextFireAfter(parsed, new Date(now));
+        return next === null ? null : next.getTime();
+      }
+      case 'interval': {
+        const intervalMs = Number.parseInt(decl.spec, 10);
+        const last = state?.lastFiredAt !== undefined ? Date.parse(state.lastFiredAt) : now;
+        const next = last + intervalMs;
+        // periphery-11: after downtime `last + interval` is in the past;
+        // the schedule clamp turned that into an IMMEDIATE fire even
+        // under `catchupPolicy: 'none'` ("drop missed fires"). Advance
+        // to the next FUTURE boundary on the original cadence - missed
+        // boundaries are the catch-up machinery's business, not the
+        // base schedule's. (Cron already behaves this way:
+        // `nextFireAfter(now)` is always future.)
+        if (next <= now && Number.isFinite(intervalMs) && intervalMs > 0) {
+          const missedBoundaries = Math.floor((now - last) / intervalMs) + 1;
+          return last + missedBoundaries * intervalMs;
+        }
+        return next;
+      }
+      case 'idle': {
+        const idleMs = Number.parseInt(decl.spec, 10);
+        return this.#lastActivity + idleMs;
+      }
+      case 'event':
+        return null;
+    }
+  }
+
+  async #applyCatchup(state: TriggerState, existing: TriggerState, now: number): Promise<void> {
+    if (state.catchupPolicy === 'none') return;
+    const decl = this.#declarations.get(state.id);
+    if (decl === undefined || (decl.kind !== 'cron' && decl.kind !== 'interval')) return;
+    const lastFired = existing.lastFiredAt !== undefined ? Date.parse(existing.lastFiredAt) : null;
+    if (lastFired === null) return;
+    if (lastFired < now - state.catchupWindowMs) return;
+
+    // RP-12: count the REAL missed fires by walking the schedule from
+    // the last successful fire to now - a restart with zero crossed
+    // boundaries must apply zero catch-up (the old code fired `1` /
+    // `maxCatchupRuns` times unconditionally).
+    const SCAN_CAP = 1000;
+    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);
+    }
+    // The overflow beyond what we re-ran is recorded for health/CLI.
+    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: string, state: TriggerState): void {
+    this.#cancelHandle(id);
+    if (state.disabled) return;
+    const decl = this.#declarations.get(id);
+    if (decl === undefined) return;
+    if (decl.kind === 'event') return;
+
+    let delay: number | null = null;
+    if (state.nextFireAt !== undefined) {
+      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) {
+      // RP-15: chunk the wait - the intermediate wake-up re-reads the
+      // freshest state and re-schedules (it never fires the callback).
+      const handle = this.#setTimeout(() => {
+        void this.#store
+          .get(id)
+          .then((s) => {
+            if (s !== null) this.#schedule(id, s);
+          })
+          .catch(() => {});
+      }, MAX_TIMEOUT_MS);
+      this.#handles.set(id, handle);
+      return;
+    }
+
+    const handle = this.#setTimeout(() => {
+      void this.fire(id);
+    }, delay);
+    this.#handles.set(id, handle);
+  }
+
+  #cancelHandle(id: string): void {
+    const handle = this.#handles.get(id);
+    if (handle !== undefined) {
+      this.#clearTimeout(handle);
+      this.#handles.delete(id);
+    }
+  }
+}