oqronkit 0.0.1-alpha.1

package/dist/chunk-PLN5A6LU.mjs

@@ -0,0 +1,1447 @@
+import { randomUUID } from 'crypto';
+import 'url';
+import 'find-up';
+import { z } from 'zod';
+import { EventEmitter } from 'eventemitter3';
+import { redactionMiddleware, prettyTransport, consoleTransport, createLogger as createLogger$1 } from 'voltlog-io';
+import 'better-sqlite3';
+import _cronParser from 'cron-parser';
+import { rrulestr, RRule } from 'rrule';
+
+// src/scheduler/cron-engine.ts
+var isIOqronAdapter = (val) => {
+  if (!val || typeof val !== "object") return false;
+  return typeof val.upsertSchedule === "function" && typeof val.getDueSchedules === "function";
+};
+var isILockAdapter = (val) => {
+  if (!val || typeof val !== "object") return false;
+  return typeof val.acquire === "function" && typeof val.renew === "function";
+};
+z.object({
+  project: z.string().optional(),
+  environment: z.string().default("development"),
+  // Infrastructure — Union of explicit DI or declarative config
+  db: z.union([
+    z.custom(
+      isIOqronAdapter,
+      "db must be an instance of IOqronAdapter"
+    ),
+    z.object({
+      adapter: z.enum([
+        "sqlite",
+        "memory",
+        "postgres",
+        "mysql",
+        "mongodb",
+        "redis"
+      ]),
+      url: z.string().optional(),
+      poolMin: z.number().default(2),
+      poolMax: z.number().default(10),
+      tablePrefix: z.string().default("chrono_"),
+      migrations: z.union([z.enum(["auto", "manual"]), z.literal(false)]).default("auto"),
+      ssl: z.boolean().default(false)
+    })
+  ]).optional(),
+  lock: z.union([
+    z.custom(
+      isILockAdapter,
+      "lock must be an instance of ILockAdapter"
+    ),
+    z.object({
+      adapter: z.enum(["db", "memory", "redis"]),
+      url: z.string().optional(),
+      ttl: z.number().default(3e4),
+      retryDelay: z.number().default(200),
+      retryCount: z.number().default(5)
+    })
+  ]).optional(),
+  broker: z.any().optional(),
+  // Modules
+  modules: z.array(
+    z.enum([
+      "cron",
+      "scheduler",
+      "queue",
+      "workflow",
+      "batch",
+      "webhook",
+      "pipeline"
+    ])
+  ).default([]),
+  // Module-specific configs
+  cron: z.object({
+    enable: z.boolean().default(true),
+    timezone: z.string().optional(),
+    tickInterval: z.number().default(1e3),
+    missedFirePolicy: z.enum(["skip", "run-once", "run-all"]).default("run-once"),
+    maxConcurrentJobs: z.number().default(5),
+    leaderElection: z.boolean().default(true),
+    keepJobHistory: z.union([z.boolean(), z.number()]).default(true),
+    keepFailedJobHistory: z.union([z.boolean(), z.number()]).default(true)
+  }).default({}),
+  scheduler: z.object({
+    enable: z.boolean().default(true),
+    tickInterval: z.number().default(1e3),
+    keepJobHistory: z.union([z.boolean(), z.number()]).default(true),
+    keepFailedJobHistory: z.union([z.boolean(), z.number()]).default(true)
+  }).default({}),
+  // Auto-discovery directory
+  jobsDir: z.string().default("./src/jobs"),
+  // Global tags
+  tags: z.array(z.string()).default([]),
+  // Worker
+  worker: z.object({
+    concurrency: z.number().default(50),
+    gracefulShutdownMs: z.number().default(3e4)
+  }).default({ concurrency: 50, gracefulShutdownMs: 3e4 }),
+  // Logger (voltlog-io config or false to disable)
+  logger: z.union([
+    z.literal(false),
+    z.object({
+      enabled: z.boolean().default(true),
+      level: z.string().default("info"),
+      prettify: z.boolean().default(false),
+      showMetadata: z.boolean().default(true),
+      redact: z.array(z.string()).default([])
+    })
+  ]).default({
+    enabled: true,
+    level: "info",
+    prettify: false,
+    showMetadata: true,
+    redact: []
+  }),
+  // Telemetry
+  telemetry: z.object({
+    prometheus: z.object({
+      enabled: z.boolean().default(false),
+      path: z.string().default("/metrics")
+    }).default({}),
+    opentelemetry: z.object({
+      enabled: z.boolean().default(false)
+    }).default({})
+  }).default({}),
+  // Shutdown
+  shutdown: z.object({
+    enabled: z.boolean().default(true),
+    timeout: z.number().default(3e4),
+    signals: z.array(z.string()).default(["SIGINT", "SIGTERM"])
+  }).default({})
+});
+
+// src/core/context/job-context.ts
+var JobContext = class {
+  id;
+  log;
+  signal;
+  environment;
+  project;
+  _progress = 0;
+  _onProgress;
+  constructor(opts) {
+    this.id = opts.id;
+    this.log = opts.logger;
+    this.signal = opts.signal;
+    this.environment = opts.environment;
+    this.project = opts.project;
+    this._onProgress = opts.onProgress;
+    this.progress = this.progress.bind(this);
+  }
+  progress(value, label) {
+    this._progress = Math.max(0, Math.min(100, value));
+    if (this._onProgress) {
+      this._onProgress(this._progress, label);
+    }
+  }
+  getProgress() {
+    return this._progress;
+  }
+};
+
+// src/core/context/cron-context.ts
+var CronContext = class extends JobContext {
+  firedAt;
+  scheduleName;
+  startedLocalAt;
+  constructor(opts) {
+    super(opts);
+    this.firedAt = opts.firedAt;
+    this.scheduleName = opts.scheduleName;
+    this.startedLocalAt = Date.now();
+  }
+  get duration() {
+    return Date.now() - this.startedLocalAt;
+  }
+};
+
+// src/core/context/schedule-context.ts
+var ScheduleContext = class {
+  id;
+  name;
+  firedAt;
+  payload;
+  environment;
+  project;
+  logger;
+  signal;
+  startedLocalAt;
+  _onProgress;
+  constructor(opts) {
+    this.id = opts.id;
+    this.name = opts.scheduleName;
+    this.firedAt = opts.firedAt;
+    this.payload = opts.payload;
+    this.logger = opts.logger;
+    this.signal = opts.signal;
+    this.environment = opts.environment;
+    this.project = opts.project;
+    this.startedLocalAt = Date.now();
+    this._onProgress = opts.onProgress;
+    this.log = this.log.bind(this);
+    this.progress = this.progress.bind(this);
+  }
+  get aborted() {
+    return this.signal.aborted;
+  }
+  get duration() {
+    return Date.now() - this.startedLocalAt;
+  }
+  log(level, message, meta) {
+    if (this.logger && typeof this.logger[level] === "function") {
+      this.logger[level](message, meta);
+    }
+  }
+  progress(percent, label) {
+    if (this._onProgress) {
+      this._onProgress(percent, label);
+    } else {
+      this.logger.debug("Progress updated", { percent, label, runId: this.id });
+    }
+  }
+};
+var OqronEventBusClass = class _OqronEventBusClass extends EventEmitter {
+  static _instance;
+  static getInstance() {
+    if (!_OqronEventBusClass._instance) {
+      _OqronEventBusClass._instance = new _OqronEventBusClass();
+    }
+    return _OqronEventBusClass._instance;
+  }
+};
+OqronEventBusClass.getInstance();
+var NOOP_LOGGER = {
+  trace() {
+  },
+  debug() {
+  },
+  info() {
+  },
+  warn() {
+  },
+  error() {
+  },
+  fatal() {
+  },
+  child() {
+    return NOOP_LOGGER;
+  },
+  addTransport() {
+  },
+  removeTransport() {
+  },
+  addMiddleware() {
+  },
+  removeMiddleware() {
+  },
+  setLevel() {
+  },
+  getLevel() {
+    return "SILENT";
+  },
+  isLevelEnabled() {
+    return false;
+  },
+  startTimer() {
+    return { done() {
+    }, elapsed: () => 0 };
+  },
+  async flush() {
+  },
+  async close() {
+  }
+};
+function createLogger(config, context) {
+  if (typeof config?.enabled !== "undefined" && config?.enabled === false)
+    return NOOP_LOGGER;
+  if (config?.logger) return config.logger;
+  const level = (config?.level ?? "INFO").toUpperCase();
+  const opts = {
+    level,
+    transports: [],
+    context
+  };
+  if (config?.redact?.length) {
+    const keys = config.redact;
+    opts.middleware = [
+      redactionMiddleware({
+        paths: keys,
+        deep: true
+      })
+    ];
+  }
+  if (config?.prettify) {
+    opts.transports.push(prettyTransport());
+  } else {
+    opts.transports.push(consoleTransport());
+  }
+  return createLogger$1(opts);
+}
+
+// src/lock/heartbeat-worker.ts
+var HeartbeatWorker = class {
+  constructor(lock, logger, key, ownerId, ttlMs = 3e4, heartbeatMs) {
+    this.lock = lock;
+    this.logger = logger;
+    this.key = key;
+    this.ownerId = ownerId;
+    this.ttlMs = ttlMs;
+    this.heartbeatMs = heartbeatMs;
+  }
+  heartbeatTimer;
+  _active = false;
+  async start() {
+    const acquired = await this.lock.acquire(
+      this.key,
+      this.ownerId,
+      this.ttlMs
+    );
+    if (!acquired) return false;
+    this._active = true;
+    const pingInterval = this.heartbeatMs ?? Math.floor(this.ttlMs / 3);
+    this.heartbeatTimer = setInterval(async () => {
+      if (!this._active) return;
+      try {
+        const renewed = await this.lock.renew(
+          this.key,
+          this.ownerId,
+          this.ttlMs
+        );
+        if (!renewed) {
+          this.logger.warn("Heartbeat renewal failed \u2014 lock lost", {
+            key: this.key,
+            ownerId: this.ownerId
+          });
+          this._active = false;
+          clearInterval(this.heartbeatTimer);
+        }
+      } catch (err) {
+        this.logger.error("Heartbeat renewal threw", {
+          key: this.key,
+          err: String(err)
+        });
+      }
+    }, pingInterval);
+    return true;
+  }
+  async stop() {
+    this._active = false;
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = void 0;
+    }
+    try {
+      await this.lock.release(this.key, this.ownerId);
+    } catch (err) {
+      this.logger.error("Failed to release lock cleanly", {
+        key: this.key,
+        err: String(err)
+      });
+    }
+  }
+  get isActive() {
+    return this._active;
+  }
+};
+
+// src/lock/leader-election.ts
+var LeaderElection = class {
+  constructor(lock, logger, leaderKey, nodeId, ttlMs = 3e4) {
+    this.lock = lock;
+    this.logger = logger;
+    this.leaderKey = leaderKey;
+    this.nodeId = nodeId;
+    this.ttlMs = ttlMs;
+  }
+  electionTimer;
+  _isLeader = false;
+  async start() {
+    await this.campaign();
+    const interval = Math.floor(this.ttlMs / 3);
+    this.electionTimer = setInterval(() => void this.campaign(), interval);
+  }
+  async campaign() {
+    try {
+      if (this._isLeader) {
+        const ok = await this.lock.renew(
+          this.leaderKey,
+          this.nodeId,
+          this.ttlMs
+        );
+        if (!ok) {
+          this._isLeader = false;
+          this.logger.warn("Lost leadership", {
+            leaderKey: this.leaderKey,
+            nodeId: this.nodeId
+          });
+        }
+      } else {
+        const ok = await this.lock.acquire(
+          this.leaderKey,
+          this.nodeId,
+          this.ttlMs
+        );
+        if (ok) {
+          this._isLeader = true;
+          this.logger.info("Became leader", {
+            leaderKey: this.leaderKey,
+            nodeId: this.nodeId
+          });
+        }
+      }
+    } catch (err) {
+      this.logger.error("Leader election error", {
+        leaderKey: this.leaderKey,
+        err: String(err)
+      });
+      this._isLeader = false;
+    }
+  }
+  get isLeader() {
+    return this._isLeader;
+  }
+  async stop() {
+    if (this.electionTimer) {
+      clearInterval(this.electionTimer);
+      this.electionTimer = void 0;
+    }
+    if (this._isLeader) {
+      try {
+        await this.lock.release(this.leaderKey, this.nodeId);
+      } catch {
+      }
+      this._isLeader = false;
+    }
+  }
+};
+
+// src/lock/stall-detector.ts
+var StallDetector = class {
+  constructor(lock, logger, checkIntervalMs = 15e3) {
+    this.lock = lock;
+    this.logger = logger;
+    this.checkIntervalMs = checkIntervalMs;
+  }
+  timer;
+  /**
+   * Start the stall detection loop.
+   * @param getActiveJobs - Returns a list of { key, ownerId } for all currently tracked jobs.
+   * @param onStalled     - Called when a job is detected as stalled (lock lost).
+   */
+  start(getActiveJobs, onStalled) {
+    this.timer = setInterval(async () => {
+      try {
+        const jobs = getActiveJobs();
+        for (const job of jobs) {
+          const owned = await this.lock.isOwner(job.key, job.ownerId);
+          if (!owned) {
+            this.logger.warn("Stalled job detected \u2014 lock lost", {
+              key: job.key,
+              ownerId: job.ownerId
+            });
+            onStalled(job.key);
+          }
+        }
+      } catch (err) {
+        this.logger.error("StallDetector tick error", { err: String(err) });
+      }
+    }, this.checkIntervalMs);
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = void 0;
+    }
+  }
+};
+var cronParser = _cronParser.default ?? _cronParser;
+function getNextRunDate(expression, timezone, from = /* @__PURE__ */ new Date()) {
+  const opts = { currentDate: from };
+  if (timezone) opts.tz = timezone;
+  return cronParser.parseExpression(expression, opts).next().toDate();
+}
+var cronParser2 = _cronParser.default ?? _cronParser;
+var MissedFireHandler = class {
+  constructor(logger, _db) {
+    this.logger = logger;
+    this._db = _db;
+  }
+  async checkMissed(def, lastRunAt, now) {
+    if (!lastRunAt) return false;
+    try {
+      let missed = false;
+      if (def.expression) {
+        const opts = { currentDate: now, tz: def.timezone };
+        const prevRun = cronParser2.parseExpression(def.expression, opts).prev().toDate();
+        missed = prevRun > lastRunAt;
+      } else if (def.intervalMs) {
+        const elapsed = now.getTime() - lastRunAt.getTime();
+        missed = elapsed > def.intervalMs;
+      }
+      if (missed) {
+        this.logger.warn("Missed execution detected", {
+          name: def.name,
+          policy: def.missedFire
+        });
+        if (def.hooks?.onMissedFire) {
+          try {
+            const ctx = {
+              id: randomUUID(),
+              log: this.logger.child({
+                schedule: def.name,
+                scope: "missed-fire"
+              }),
+              logger: this.logger.child({
+                schedule: def.name,
+                scope: "missed-fire"
+              }),
+              signal: new AbortController().signal,
+              firedAt: now,
+              scheduleName: def.name,
+              progress: () => {
+              }
+            };
+            await def.hooks.onMissedFire(ctx, lastRunAt);
+          } catch (err) {
+            this.logger.error("onMissedFire hook threw", {
+              name: def.name,
+              err: String(err)
+            });
+          }
+        }
+        if (def.missedFire === "run-once" || def.missedFire === "run-all") {
+          return true;
+        }
+      }
+    } catch {
+    }
+    return false;
+  }
+};
+
+// src/scheduler/cron-engine.ts
+var SchedulerModule = class {
+  constructor(schedules, db, lock, logger, environment, project, config) {
+    this.schedules = schedules;
+    this.db = db;
+    this.lock = lock;
+    this.environment = environment;
+    this.project = project;
+    this.config = config;
+    this.nodeId = randomUUID();
+    this.logger = logger ?? createLogger({ level: "info" }, { module: "scheduler" });
+    this.stallDetector = new StallDetector(this.lock, this.logger, 15e3);
+    this.missedFireHandler = new MissedFireHandler(this.logger, this.db);
+  }
+  name = "cron";
+  enabled = true;
+  nodeId;
+  logger;
+  leader;
+  stallDetector;
+  missedFireHandler;
+  tickTimer;
+  activeJobs = /* @__PURE__ */ new Map();
+  _hasRunLeaderInit = false;
+  // ── Lifecycle ───────────────────────────────────────────────────────────────
+  async init() {
+    this.logger.info("Initializing scheduler", {
+      nodeId: this.nodeId,
+      count: this.schedules.length
+    });
+    for (const def of this.schedules) {
+      await this.db.upsertSchedule(def);
+      this.logger.debug("Registered schedule", {
+        name: def.name,
+        expression: def.expression,
+        intervalMs: def.intervalMs
+      });
+    }
+    const existing = await this.db.getSchedules();
+    const now = /* @__PURE__ */ new Date();
+    for (const record of existing) {
+      if (record.nextRunAt !== null) continue;
+      const def = this.schedules.find((s) => s.name === record.name);
+      if (!def) continue;
+      const nextRun = this.computeNextRun(def, now);
+      if (nextRun) {
+        await this.db.updateNextRun(def.name, nextRun);
+        this.logger.debug("Seeded nextRunAt", {
+          name: def.name,
+          nextRunAt: nextRun.toISOString()
+        });
+      }
+    }
+  }
+  async start() {
+    if (this.config?.leaderElection !== false) {
+      this.leader = new LeaderElection(
+        this.lock,
+        this.logger,
+        "oqron:scheduler:leader",
+        this.nodeId,
+        3e4
+      );
+      await this.leader.start();
+    }
+    const interval = this.config?.tickInterval ?? 1e3;
+    this.tickTimer = setInterval(() => {
+      void this.tick();
+    }, interval);
+    this.logger.info("Scheduler started", { nodeId: this.nodeId, interval });
+  }
+  async stop() {
+    if (this.tickTimer) clearInterval(this.tickTimer);
+    if (this.leader) await this.leader.stop();
+    this.stallDetector.stop();
+    for (const job of this.activeJobs.values()) {
+      if (job.abort) job.abort.abort();
+      if (job.worker) {
+        await job.worker.stop();
+      } else {
+        await this.lock.release(job.lockKey, this.nodeId).catch(() => {
+        });
+      }
+    }
+    this.activeJobs.clear();
+    this.logger.info("Scheduler stopped");
+  }
+  // ── Core scheduling helpers ─────────────────────────────────────────────────
+  /**
+   * Compute the next fire time for a definition.
+   * Returns null if computation fails (invalid expression, etc).
+   */
+  computeNextRun(def, from) {
+    if (def.expression) {
+      try {
+        const timezone = def.timezone ?? this.config?.timezone;
+        return getNextRunDate(def.expression, timezone, from);
+      } catch (err) {
+        this.logger.error("Failed to compute next run from expression", {
+          name: def.name,
+          expression: def.expression,
+          err: String(err)
+        });
+        return null;
+      }
+    }
+    if (def.intervalMs) {
+      return new Date(from.getTime() + def.intervalMs);
+    }
+    this.logger.error("Schedule has neither expression nor intervalMs", {
+      name: def.name
+    });
+    return null;
+  }
+  // ── Leader init (missed-fire recovery + stall detector) ─────────────────────
+  async handleLeaderInit() {
+    this.logger.info("Performing leader initialization...");
+    const knownSchedules = await this.db.getSchedules();
+    const now = /* @__PURE__ */ new Date();
+    for (const record of knownSchedules) {
+      const def = this.schedules.find((s) => s.name === record.name);
+      if (!def) continue;
+      const missed = await this.missedFireHandler.checkMissed(
+        def,
+        record.lastRunAt,
+        now
+      );
+      if (missed) {
+        this.logger.info("Triggering recovery run for missed schedule", {
+          name: def.name
+        });
+        void this.fire(def);
+      }
+    }
+    this.stallDetector.start(
+      () => {
+        return Array.from(this.activeJobs.values()).filter((job) => job.worker !== void 0).map((job) => ({
+          key: job.lockKey,
+          ownerId: this.nodeId
+        }));
+      },
+      (key) => {
+        this.logger.warn("Local stall detected", { key });
+      }
+    );
+  }
+  async detectClusterStalls() {
+    try {
+      const activeDbJobs = await this.db.getActiveJobs();
+      for (const job of activeDbJobs) {
+        if (!job.scheduleId) continue;
+        const def = this.schedules.find((s) => s.name === job.scheduleId);
+        if (!def?.guaranteedWorker) continue;
+        const ageMs = Date.now() - job.startedAt.getTime();
+        const ttl = def.lockTtlMs ?? 5e4;
+        if (ageMs > ttl + 1e4) {
+          this.logger.warn("Cluster stall detected", { runId: job.id });
+          await this.db.recordExecution({
+            id: job.id,
+            scheduleId: job.scheduleId,
+            status: "failed",
+            error: "Stall detected (lock assumed expired)",
+            startedAt: job.startedAt,
+            completedAt: /* @__PURE__ */ new Date()
+          });
+        }
+      }
+    } catch (err) {
+      this.logger.error("Failed to detect cluster stalls", {
+        err: String(err)
+      });
+    }
+  }
+  // ── Tick loop ───────────────────────────────────────────────────────────────
+  async tick() {
+    if (this.leader && !this.leader.isLeader) return;
+    if (!this._hasRunLeaderInit) {
+      this._hasRunLeaderInit = true;
+      await this.handleLeaderInit();
+    }
+    try {
+      if (Math.random() < 0.1) {
+        void this.detectClusterStalls();
+      }
+      const now = /* @__PURE__ */ new Date();
+      const due = await this.db.getDueSchedules(now, 50);
+      for (const { name } of due) {
+        const def = this.schedules.find((s) => s.name === name);
+        if (!def) continue;
+        const nextRun = this.computeNextRun(def, now);
+        if (!nextRun) {
+          this.logger.error(
+            "Cannot compute next run \u2014 suspending cron to prevent runaway loop",
+            { name: def.name }
+          );
+          await this.db.updateNextRun(def.name, null).catch(() => {
+          });
+          continue;
+        }
+        await this.db.updateNextRun(def.name, nextRun);
+        void this.fire(def);
+      }
+    } catch (err) {
+      this.logger.error("Tick error", { err: String(err) });
+    }
+  }
+  // ── Fire handler ────────────────────────────────────────────────────────────
+  async fire(def) {
+    const isOverlapSkip = def.overlap === "skip" || def.overlap === false;
+    if (isOverlapSkip) {
+      for (const job of this.activeJobs.values()) {
+        if (job.lockKey === `oqron:run:${def.name}`) {
+          this.logger.debug("Skipping overlapping run", { name: def.name });
+          return;
+        }
+      }
+    }
+    const runId = randomUUID();
+    const lockKey = isOverlapSkip ? `oqron:run:${def.name}` : `oqron:run:${def.name}:${runId}`;
+    const startedAt = /* @__PURE__ */ new Date();
+    let worker;
+    let acquired = false;
+    if (def.guaranteedWorker) {
+      worker = new HeartbeatWorker(
+        this.lock,
+        this.logger,
+        lockKey,
+        this.nodeId,
+        def.lockTtlMs ?? 3e4,
+        def.heartbeatMs ?? 1e4
+      );
+      acquired = await worker.start();
+    } else {
+      acquired = await this.lock.acquire(
+        lockKey,
+        this.nodeId,
+        def.lockTtlMs ?? 3e4
+      );
+    }
+    if (!acquired) return;
+    const abort = new AbortController();
+    this.activeJobs.set(runId, { runId, lockKey, worker, abort });
+    await this.db.recordExecution({
+      id: runId,
+      scheduleId: def.name,
+      status: "running",
+      startedAt
+    });
+    void Promise.resolve().then(async () => {
+      const ctx = new CronContext({
+        id: runId,
+        logger: this.logger.child({ schedule: def.name }),
+        signal: abort.signal,
+        firedAt: startedAt,
+        scheduleName: def.name,
+        environment: this.environment,
+        project: this.project,
+        onProgress: (percent, label) => {
+          this.db.updateJobProgress(runId, percent, label).catch(
+            (err) => this.logger.error("Failed to update progress", { runId, err })
+          );
+        }
+      });
+      let status = "completed";
+      let error;
+      let timeoutHandle;
+      let finalResult;
+      let attempts = 1;
+      const maxAttempts = (def.retries?.max ?? 0) + 1;
+      while (attempts <= maxAttempts) {
+        try {
+          if (def.hooks?.beforeRun) await def.hooks.beforeRun(ctx);
+          if (def.timeout) {
+            const timeoutPromise = new Promise((_, reject) => {
+              timeoutHandle = setTimeout(() => {
+                abort.abort();
+                reject(new Error(`Handler timed out after ${def.timeout}ms`));
+              }, def.timeout);
+            });
+            finalResult = await Promise.race([
+              def.handler(ctx),
+              timeoutPromise
+            ]);
+          } else {
+            finalResult = await def.handler(ctx);
+          }
+          if (def.hooks?.afterRun) {
+            await def.hooks.afterRun(ctx, finalResult);
+          }
+          status = "completed";
+          error = void 0;
+          break;
+        } catch (err) {
+          error = err instanceof Error ? err.message : String(err);
+          status = "failed";
+          if (def.hooks?.onError && err instanceof Error) {
+            try {
+              await Promise.resolve(def.hooks.onError(ctx, err));
+            } catch (e) {
+              this.logger.error("onError hook threw", { err: String(e) });
+            }
+          }
+          if (attempts < maxAttempts) {
+            this.logger.warn("Job handler threw, retrying...", {
+              name: def.name,
+              runId,
+              attempt: attempts,
+              error
+            });
+            const baseDelay = def.retries?.baseDelay ?? 2e3;
+            const delay = def.retries?.strategy === "exponential" ? baseDelay * 2 ** (attempts - 1) : baseDelay;
+            attempts++;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+          } else {
+            this.logger.error("Job handler failed completely", {
+              name: def.name,
+              runId,
+              attempts,
+              error
+            });
+            break;
+          }
+        } finally {
+          if (timeoutHandle) clearTimeout(timeoutHandle);
+        }
+      }
+      const completedAt = /* @__PURE__ */ new Date();
+      await this.db.recordExecution({
+        id: runId,
+        scheduleId: def.name,
+        status,
+        startedAt,
+        completedAt,
+        error,
+        result: finalResult !== void 0 ? JSON.stringify(finalResult) : void 0,
+        attempts,
+        durationMs: completedAt.getTime() - startedAt.getTime(),
+        ...status === "completed" ? { progressPercent: 100, progressLabel: "Completed" } : {}
+      });
+      if (worker) {
+        await worker.stop();
+      } else {
+        await this.lock.release(lockKey, this.nodeId).catch(() => {
+        });
+      }
+      this.activeJobs.delete(runId);
+      if (def.intervalMs) {
+        const nextRun = this.computeNextRun(def, /* @__PURE__ */ new Date());
+        if (nextRun) {
+          await this.db.updateNextRun(def.name, nextRun).catch(() => {
+          });
+        }
+      }
+      const keepJobHistory = def.keepHistory ?? this.config?.keepJobHistory ?? true;
+      const keepFailedHistory = def.keepFailedHistory ?? this.config?.keepFailedJobHistory ?? true;
+      if (keepJobHistory !== true || keepFailedHistory !== true) {
+        this.db.pruneHistoryForSchedule(def.name, keepJobHistory, keepFailedHistory).catch(
+          (err) => this.logger.debug("Failed to prune history", {
+            err,
+            name: def.name
+          })
+        );
+      }
+      this.logger.info("Job finished", {
+        name: def.name,
+        runId,
+        status,
+        attempts
+      });
+    });
+  }
+};
+
+// src/scheduler/registry.ts
+var GLOBAL_KEY = "__oqronkit_pending_crons__";
+function _getPending() {
+  if (!globalThis[GLOBAL_KEY]) {
+    globalThis[GLOBAL_KEY] = [];
+  }
+  return globalThis[GLOBAL_KEY];
+}
+function _registerCron(def) {
+  _getPending().push(def);
+}
+function _drainPending() {
+  const pending = _getPending();
+  return pending.splice(0);
+}
+
+// src/scheduler/define-cron.ts
+var cronParser3 = _cronParser.default ?? _cronParser;
+function everyToIntervalMs(every) {
+  let ms = 0;
+  if (every.seconds) ms += every.seconds * 1e3;
+  if (every.minutes) ms += every.minutes * 6e4;
+  if (every.hours) ms += every.hours * 36e5;
+  if (ms <= 0)
+    throw new Error(
+      "[OqronKit] `every` config must resolve to a positive interval"
+    );
+  return ms;
+}
+var cron = (options) => {
+  let expression;
+  let intervalMs;
+  if ("expression" in options && options.expression) {
+    try {
+      cronParser3.parseExpression(options.expression, { tz: options.timezone });
+    } catch {
+      throw new Error(
+        `[OqronKit] Invalid cron expression for "${options.name}": "${options.expression}"`
+      );
+    }
+    expression = options.expression;
+  } else if ("every" in options && options.every) {
+    intervalMs = everyToIntervalMs(options.every);
+  } else {
+    throw new Error(
+      `[OqronKit] Cron "${options.name}" must specify either "expression" or "every"`
+    );
+  }
+  const def = {
+    name: options.name,
+    expression,
+    intervalMs,
+    timezone: options.timezone,
+    missedFire: options.missedFire ?? "skip",
+    overlap: options.overlap ?? "skip",
+    guaranteedWorker: options.guaranteedWorker ?? false,
+    heartbeatMs: options.heartbeatMs,
+    lockTtlMs: options.lockTtlMs,
+    timeout: options.timeout,
+    tags: options.tags ?? [],
+    handler: options.handler,
+    hooks: options.hooks,
+    retries: options.retries
+  };
+  _registerCron(def);
+  return def;
+};
+
+// src/scheduler/registry-schedule.ts
+var GLOBAL_KEY2 = "__oqronkit_pending_schedules__";
+function _getPending2() {
+  if (!globalThis[GLOBAL_KEY2]) {
+    globalThis[GLOBAL_KEY2] = [];
+  }
+  return globalThis[GLOBAL_KEY2];
+}
+function _registerSchedule(def) {
+  _getPending2().push(def);
+}
+function _drainPendingSchedules() {
+  const pending = _getPending2();
+  return pending.splice(0);
+}
+
+// src/scheduler/define-schedule.ts
+var engineRef = { current: null };
+function _attachScheduleEngine(engine) {
+  engineRef.current = engine;
+}
+var schedule = (options) => {
+  const def = {
+    name: options.name,
+    runAt: options.runAt,
+    runAfter: options.runAfter,
+    recurring: options.recurring,
+    rrule: options.rrule,
+    every: options.every,
+    timezone: options.timezone,
+    missedFire: options.missedFire ?? "skip",
+    overlap: options.overlap ?? "skip",
+    guaranteedWorker: options.guaranteedWorker ?? false,
+    heartbeatMs: options.heartbeatMs,
+    lockTtlMs: options.lockTtlMs,
+    timeout: options.timeout,
+    tags: options.tags ?? [],
+    condition: options.condition,
+    handler: options.handler,
+    hooks: options.hooks,
+    payload: options.payload,
+    retries: options.retries
+  };
+  _registerSchedule(def);
+  return {
+    ...def,
+    trigger: async (opts) => {
+      if (!engineRef.current) {
+        throw new Error(
+          `[OqronKit] Cannot trigger "${options.name}" \u2014 ScheduleEngine is not running.`
+        );
+      }
+      const dynamicDef = { ...def };
+      if (opts) {
+        if (opts.nameSuffix) dynamicDef.name = `${def.name}:${opts.nameSuffix}`;
+        if (opts.runAt) dynamicDef.runAt = opts.runAt;
+        if (opts.runAfter) dynamicDef.runAfter = opts.runAfter;
+        if (opts.recurring) dynamicDef.recurring = opts.recurring;
+        if (opts.rrule) dynamicDef.rrule = opts.rrule;
+        if (opts.every) dynamicDef.every = opts.every;
+        if (opts.payload) dynamicDef.payload = opts.payload;
+      }
+      if (!opts?.runAt && !opts?.runAfter && !opts?.recurring && !opts?.rrule && !opts?.every) {
+        dynamicDef.runAt = /* @__PURE__ */ new Date();
+      }
+      await engineRef.current.registerDynamic(dynamicDef);
+    },
+    schedule: async (opts) => {
+      if (!engineRef.current) {
+        throw new Error(
+          `[OqronKit] Cannot schedule "${options.name}" \u2014 ScheduleEngine is not running.`
+        );
+      }
+      const dynamicDef = { ...def };
+      if (opts) {
+        if (opts.nameSuffix) dynamicDef.name = `${def.name}:${opts.nameSuffix}`;
+        if (opts.runAt) dynamicDef.runAt = opts.runAt;
+        if (opts.runAfter) dynamicDef.runAfter = opts.runAfter;
+        if (opts.recurring) dynamicDef.recurring = opts.recurring;
+        if (opts.rrule) dynamicDef.rrule = opts.rrule;
+        if (opts.every) dynamicDef.every = opts.every;
+        if (opts.payload) dynamicDef.payload = opts.payload;
+      }
+      await engineRef.current.registerDynamic(dynamicDef);
+    },
+    cancel: async () => {
+      if (!engineRef.current) return;
+      await engineRef.current.cancel(def.name);
+    }
+  };
+};
+var ScheduleEngine = class {
+  constructor(staticSchedules, db, lock, logger, environment, project, config) {
+    this.db = db;
+    this.lock = lock;
+    this.environment = environment;
+    this.project = project;
+    this.config = config;
+    this.nodeId = randomUUID();
+    this.logger = logger ?? createLogger({ level: "info" }, { module: "scheduler" });
+    this.stallDetector = new StallDetector(this.lock, this.logger, 15e3);
+    for (const def of staticSchedules) {
+      this.schedules.set(def.name, def);
+    }
+  }
+  name = "scheduler";
+  enabled = true;
+  nodeId;
+  logger;
+  leader;
+  stallDetector;
+  tickTimer;
+  activeJobs = /* @__PURE__ */ new Map();
+  // Includes static instances and dynamically triggered instances
+  schedules = /* @__PURE__ */ new Map();
+  _hasRunLeaderInit = false;
+  // ── Lifecycle ───────────────────────────────────────────────────────────────
+  async init() {
+    this.logger.info("Initializing schedule engine", {
+      nodeId: this.nodeId,
+      staticCount: this.schedules.size
+    });
+    _attachScheduleEngine(this);
+    const now = /* @__PURE__ */ new Date();
+    for (const def of this.schedules.values()) {
+      await this.upsertAndSeed(def, now);
+    }
+  }
+  async upsertAndSeed(def, now) {
+    await this.db.upsertSchedule(def);
+    const nextRun = this.computeNextRun(def, now);
+    if (nextRun) {
+      await this.db.updateNextRun(def.name, nextRun);
+    }
+  }
+  /** Dynamically register and schedule a definition from trigger/schedule call */
+  async registerDynamic(def) {
+    this.schedules.set(def.name, def);
+    await this.upsertAndSeed(def, /* @__PURE__ */ new Date());
+    this.logger.debug("Registered dynamic schedule", { name: def.name });
+  }
+  async cancel(name) {
+    this.schedules.delete(name);
+  }
+  async start() {
+    this.leader = new LeaderElection(
+      this.lock,
+      this.logger,
+      "oqron:scheduleengine:leader",
+      this.nodeId,
+      3e4
+    );
+    await this.leader.start();
+    const interval = this.config?.tickInterval ?? 1e3;
+    this.tickTimer = setInterval(() => {
+      void this.tick();
+    }, interval);
+    this.logger.info("Schedule engine started", {
+      nodeId: this.nodeId,
+      interval
+    });
+  }
+  async stop() {
+    if (this.tickTimer) clearInterval(this.tickTimer);
+    if (this.leader) await this.leader.stop();
+    this.stallDetector.stop();
+    for (const job of this.activeJobs.values()) {
+      if (job.abort) job.abort.abort();
+      if (job.worker) {
+        await job.worker.stop();
+      } else {
+        await this.lock.release(job.lockKey, this.nodeId).catch(() => {
+        });
+      }
+    }
+    this.activeJobs.clear();
+    this.logger.info("Schedule engine stopped");
+  }
+  // ── Core scheduling helpers ─────────────────────────────────────────────────
+  computeNextRun(def, from) {
+    try {
+      if (def.runAt) {
+        return new Date(def.runAt);
+      }
+      if (def.runAfter) {
+        const add = (def.runAfter.days ?? 0) * 864e5 + (def.runAfter.hours ?? 0) * 36e5 + (def.runAfter.minutes ?? 0) * 6e4 + (def.runAfter.seconds ?? 0) * 1e3;
+        return new Date(from.getTime() + add);
+      }
+      if (def.rrule) {
+        const rule = rrulestr(def.rrule);
+        return rule.after(from);
+      }
+      if (def.recurring) {
+        const freqMapHash = {
+          daily: RRule.DAILY,
+          weekly: RRule.WEEKLY,
+          monthly: RRule.MONTHLY,
+          yearly: RRule.YEARLY
+        };
+        const freq = freqMapHash[def.recurring.frequency] ?? RRule.DAILY;
+        const options = { freq };
+        if (def.recurring.months?.length)
+          options.bymonth = def.recurring.months;
+        if (def.recurring.dayOfMonth)
+          options.bymonthday = [def.recurring.dayOfMonth];
+        if (def.recurring.at) {
+          options.byhour = [def.recurring.at.hour];
+          options.byminute = [def.recurring.at.minute];
+          options.bysecond = [0];
+        }
+        const rule = new RRule(options);
+        return rule.after(from);
+      }
+      if (def.every) {
+        const add = (def.every.hours ?? 0) * 36e5 + (def.every.minutes ?? 0) * 6e4 + (def.every.seconds ?? 0) * 1e3;
+        return new Date(from.getTime() + add);
+      }
+    } catch (err) {
+      this.logger.error("Failed to compute next run", {
+        name: def.name,
+        err: String(err)
+      });
+    }
+    return null;
+  }
+  // ── Leader init (missed-fire recovery + stall detector) ─────────────────────
+  async handleLeaderInit() {
+    this.logger.info("Schedule Engine: Performing leader initialization...");
+    this.stallDetector.start(
+      () => {
+        return Array.from(this.activeJobs.values()).filter((job) => job.worker !== void 0).map((job) => ({
+          key: job.lockKey,
+          ownerId: this.nodeId
+        }));
+      },
+      (key) => {
+        this.logger.warn("Local stall detected", { key });
+      }
+    );
+  }
+  // ── Tick loop ───────────────────────────────────────────────────────────────
+  async tick() {
+    if (!this.leader?.isLeader) return;
+    if (!this._hasRunLeaderInit) {
+      this._hasRunLeaderInit = true;
+      await this.handleLeaderInit();
+    }
+    try {
+      const now = /* @__PURE__ */ new Date();
+      const due = await this.db.getDueSchedules(now, 50);
+      for (const { name } of due) {
+        const def = this.schedules.get(name);
+        if (!def) continue;
+        if (def.condition) {
+          try {
+            const conditionVal = await def.condition(
+              new ScheduleContext({
+                id: "eval",
+                scheduleName: def.name,
+                firedAt: now,
+                logger: this.logger,
+                signal: new AbortController().signal,
+                payload: def.payload,
+                environment: this.environment,
+                project: this.project
+              })
+            );
+            if (!conditionVal) {
+              const nextRun2 = this.computeNextRun(def, now);
+              if (nextRun2) await this.db.updateNextRun(def.name, nextRun2);
+              continue;
+            }
+          } catch (e) {
+            this.logger.error("Condition crashed", {
+              name: def.name,
+              error: String(e)
+            });
+            continue;
+          }
+        }
+        let nextRun = null;
+        if (!def.runAt && !def.runAfter) {
+          nextRun = this.computeNextRun(def, now);
+          if (!nextRun) {
+            this.logger.error(
+              "Cannot compute next run \u2014 suspending schedule to prevent runaway loop",
+              { name: def.name }
+            );
+            await this.db.updateNextRun(def.name, null).catch(() => {
+            });
+            continue;
+          }
+        }
+        await this.db.updateNextRun(def.name, nextRun);
+        void this.fire(def);
+      }
+    } catch (err) {
+      this.logger.error("Tick error", { err: String(err) });
+    }
+  }
+  // ── Fire handler ────────────────────────────────────────────────────────────
+  async fire(def) {
+    const isOverlapSkip = def.overlap === "skip" || def.overlap === false;
+    if (isOverlapSkip) {
+      for (const job of this.activeJobs.values()) {
+        if (job.lockKey === `oqron:schedule:run:${def.name}`) {
+          this.logger.debug("Skipping overlapping run", { name: def.name });
+          return;
+        }
+      }
+    }
+    const runId = randomUUID();
+    const lockKey = isOverlapSkip ? `oqron:schedule:run:${def.name}` : `oqron:schedule:run:${def.name}:${runId}`;
+    const startedAt = /* @__PURE__ */ new Date();
+    let worker;
+    let acquired = false;
+    if (def.guaranteedWorker) {
+      worker = new HeartbeatWorker(
+        this.lock,
+        this.logger,
+        lockKey,
+        this.nodeId,
+        def.lockTtlMs ?? 3e4,
+        def.heartbeatMs ?? 1e4
+      );
+      acquired = await worker.start();
+    } else {
+      acquired = await this.lock.acquire(
+        lockKey,
+        this.nodeId,
+        def.lockTtlMs ?? 3e4
+      );
+    }
+    if (!acquired) return;
+    const abort = new AbortController();
+    this.activeJobs.set(runId, { runId, lockKey, worker, abort });
+    await this.db.recordExecution({
+      id: runId,
+      scheduleId: def.name,
+      status: "running",
+      startedAt
+    });
+    void Promise.resolve().then(async () => {
+      const ctx = new ScheduleContext({
+        id: runId,
+        logger: this.logger.child({ schedule: def.name }),
+        signal: abort.signal,
+        firedAt: startedAt,
+        scheduleName: def.name,
+        payload: def.payload,
+        environment: this.environment,
+        project: this.project,
+        onProgress: (percent, label) => {
+          this.db.updateJobProgress(runId, percent, label).catch(
+            (err) => this.logger.error("Failed to update schedule progress", {
+              runId,
+              err
+            })
+          );
+        }
+      });
+      let status = "completed";
+      let error;
+      let timeoutHandle;
+      let finalResult;
+      let attempts = 1;
+      const maxAttempts = (def.retries?.max ?? 0) + 1;
+      while (attempts <= maxAttempts) {
+        try {
+          if (def.hooks?.beforeRun) await def.hooks.beforeRun(ctx);
+          if (def.timeout) {
+            const timeoutPromise = new Promise((_, reject) => {
+              timeoutHandle = setTimeout(() => {
+                abort.abort();
+                reject(new Error(`Handler timed out after ${def.timeout}ms`));
+              }, def.timeout);
+            });
+            finalResult = await Promise.race([
+              def.handler(ctx),
+              timeoutPromise
+            ]);
+          } else {
+            finalResult = await def.handler(ctx);
+          }
+          if (def.hooks?.afterRun) {
+            await def.hooks.afterRun(ctx, finalResult);
+          }
+          status = "completed";
+          error = void 0;
+          break;
+        } catch (err) {
+          error = err instanceof Error ? err.message : String(err);
+          status = "failed";
+          if (def.hooks?.onError && err instanceof Error) {
+            try {
+              await Promise.resolve(def.hooks.onError(ctx, err));
+            } catch (e) {
+              this.logger.error("onError hook threw", { err: String(e) });
+            }
+          }
+          if (attempts < maxAttempts) {
+            this.logger.warn("Schedule handler threw, retrying...", {
+              name: def.name,
+              runId,
+              attempt: attempts,
+              error
+            });
+            const baseDelay = def.retries?.baseDelay ?? 2e3;
+            const delay = def.retries?.strategy === "exponential" ? baseDelay * 2 ** (attempts - 1) : baseDelay;
+            attempts++;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+          } else {
+            this.logger.error("Schedule handler failed completely", {
+              name: def.name,
+              runId,
+              attempts,
+              error
+            });
+            break;
+          }
+        } finally {
+          if (timeoutHandle) clearTimeout(timeoutHandle);
+        }
+      }
+      const completedAt = /* @__PURE__ */ new Date();
+      await this.db.recordExecution({
+        id: runId,
+        scheduleId: def.name,
+        status,
+        startedAt,
+        completedAt,
+        error,
+        result: finalResult !== void 0 ? JSON.stringify(finalResult) : void 0,
+        attempts,
+        durationMs: completedAt.getTime() - startedAt.getTime(),
+        ...status === "completed" ? { progressPercent: 100, progressLabel: "Completed" } : {}
+      });
+      if (worker) {
+        await worker.stop();
+      } else {
+        await this.lock.release(lockKey, this.nodeId).catch(() => {
+        });
+      }
+      this.activeJobs.delete(runId);
+      const keepJobHistory = def.keepHistory ?? this.config?.keepJobHistory ?? true;
+      const keepFailedHistory = def.keepFailedHistory ?? this.config?.keepFailedJobHistory ?? true;
+      if (keepJobHistory !== true || keepFailedHistory !== true) {
+        this.db.pruneHistoryForSchedule(def.name, keepJobHistory, keepFailedHistory).catch(
+          (err) => this.logger.debug("Failed to prune history", {
+            err,
+            name: def.name
+          })
+        );
+      }
+      this.logger.info("Schedule finished", {
+        name: def.name,
+        runId,
+        status,
+        attempts
+      });
+    });
+  }
+};
+
+export { ScheduleEngine, SchedulerModule, _drainPending, _drainPendingSchedules, _registerCron, _registerSchedule, cron, getNextRunDate, schedule };