@blamejs/core 0.4.1

package/lib/scheduler.js

@@ -0,0 +1,680 @@
+"use strict";
+/**
+ * scheduler — cron + interval scheduler over lib/jobs (or direct fn).
+ *
+ * The framework's primitive for "run X at Y" — backed by jobs/queue
+ * for retries, audit, and cluster-aware dispatch, with a direct-fn
+ * escape hatch for the simple cases.
+ *
+ *   var sched = b.scheduler.create({
+ *     jobs:    jobsInstance,    // optional; needed for { job: "name" }
+ *     cluster: b.cluster,       // optional; gates fires to leader only
+ *     audit:   true,            // default true
+ *   });
+ *
+ *   sched.schedule({
+ *     name:     "nightly-cleanup",
+ *     cron:     "0 2 * * *",        // POSIX 5-field cron
+ *     timezone: "America/New_York", // IANA name; default = server-local
+ *     job:      "cleanup",          // dispatched via jobs.enqueue
+ *     payload:  { scope: "all" },
+ *   });
+ *
+ *   sched.schedule({
+ *     name:     "stats-aggregation",
+ *     every:    300000,             // ms between runs
+ *     baseline: "00:00",            // HH:MM anchor (optional)
+ *     timezone: "America/New_York",
+ *     job:      "aggregate-stats",
+ *   });
+ *
+ *   sched.schedule({
+ *     name:  "heartbeat",
+ *     every: 60000,
+ *     run:   async function () { … },  // direct function (no jobs needed)
+ *   });
+ *
+ *   await sched.start();   // arms timers
+ *   await sched.stop();    // clears timers, drops pending fires
+ *
+ *   sched.list();          // → [{ name, when, lastRun, nextRun, running }]
+ *
+ * Cron grammar (5 fields, space-separated):
+ *
+ *   minute (0–59)  hour (0–23)  dom (1–31)  month (1–12)  dow (0–7; 0/7=Sun)
+ *
+ * Each field accepts:  *  N  N,M,…  A-B  *\/N  A-B/N
+ *
+ * Shorthands: @hourly @daily @midnight @weekly @monthly @yearly @annually
+ *
+ * Cluster gating: when opts.cluster is wired and the local node is not
+ * the leader, schedule fires no-op. The leader still computes nextRun
+ * locally so a leader transition picks up cleanly.
+ *
+ * Exactly-once-globally: when opts.cluster is wired, every fire first
+ * INSERTs a row into _blamejs_scheduler_ticks keyed on (taskName,
+ * scheduledAtUnix). The PRIMARY KEY race ensures that even if two
+ * nodes briefly believe they are the leader (split-brain on lease
+ * boundary), only the row-winner runs the task. The loser increments
+ * task.tickClaimLost (visible via list()) and skips silently. Task
+ * handlers should still be idempotent — operators may add jobs.enqueue
+ * dedup keys for defense-in-depth.
+ *
+ * Tick-claim retention: rows older than opts.tickRetentionMs (default
+ * 7 days) are pruned automatically — at most once per opts.pruneInterval
+ * Ms (default 60s) — by the leader on its next successful fire. Operators
+ * can also call sched.pruneTickClaims(olderThanMs?) on demand to force
+ * a sweep (e.g. from a maintenance script) and observe the count via
+ * the system.scheduler.tick.pruned audit event.
+ *
+ * Watchdog: if a fire's promise hasn't settled after MAX_JOB_MS
+ * (10min default; opts.maxJobMs to override), the running flag is
+ * force-cleared and a warning emitted, so a hung job doesn't lock out
+ * future fires.
+ */
+
+var lazyRequire = require("./lazy-require");
+var audit  = lazyRequire(function () { return require("./audit"); });
+var log    = lazyRequire(function () { return require("./log").boot("scheduler"); });
+var clusterStorage = require("./cluster-storage");
+var validateOpts = require("./validate-opts");
+var C = require("./constants");
+var { SchedulerError } = require("./framework-error");
+
+var DEFAULT_MAX_JOB_MS             = C.TIME.minutes(10);
+var DEFAULT_TICK_RETENTION_MS      = C.TIME.days(7);
+var DEFAULT_TICK_PRUNE_INTERVAL_MS = C.TIME.minutes(1);
+
+// ---- Cron parsing ----
+
+var CRON_SHORTHANDS = {
+  "@yearly":   "0 0 1 1 *",
+  "@annually": "0 0 1 1 *",
+  "@monthly":  "0 0 1 * *",
+  "@weekly":   "0 0 * * 0",
+  "@daily":    "0 0 * * *",
+  "@midnight": "0 0 * * *",
+  "@hourly":   "0 * * * *",
+};
+
+var CRON_FIELD_RANGES = [
+  { name: "minute", min: 0, max: 59 },
+  { name: "hour",   min: 0, max: 23 },
+  { name: "dom",    min: 1, max: 31 },
+  { name: "month",  min: 1, max: 12 },
+  { name: "dow",    min: 0, max: 7 }, // 0 and 7 both mean Sunday
+];
+
+function _parseCronField(text, range) {
+  var parts = String(text).split(",");
+  var set = new Set();
+  for (var i = 0; i < parts.length; i++) {
+    var part = parts[i].trim();
+    if (part.length === 0) {
+      throw new SchedulerError("scheduler/invalid-cron",
+        "empty term in cron field '" + range.name + "'", true);
+    }
+    var step = 1;
+    var stepIdx = part.indexOf("/");
+    if (stepIdx !== -1) {
+      var stepStr = part.slice(stepIdx + 1);
+      step = parseInt(stepStr, 10);
+      if (!Number.isFinite(step) || step < 1) {
+        throw new SchedulerError("scheduler/invalid-cron",
+          "bad step '" + stepStr + "' in cron field '" + range.name + "'", true);
+      }
+      part = part.slice(0, stepIdx);
+    }
+    var lo, hi;
+    if (part === "*") {
+      lo = range.min; hi = range.max;
+    } else if (part.indexOf("-") !== -1) {
+      var seg = part.split("-");
+      if (seg.length !== 2) {
+        throw new SchedulerError("scheduler/invalid-cron",
+          "bad range '" + part + "' in cron field '" + range.name + "'", true);
+      }
+      lo = parseInt(seg[0], 10);
+      hi = parseInt(seg[1], 10);
+    } else {
+      lo = parseInt(part, 10);
+      hi = lo;
+    }
+    if (!Number.isFinite(lo) || !Number.isFinite(hi) || lo > hi ||
+        lo < range.min || hi > range.max) {
+      throw new SchedulerError("scheduler/invalid-cron",
+        "value '" + part + "' out of range " + range.min + "-" + range.max +
+        " in cron field '" + range.name + "'", true);
+    }
+    for (var v = lo; v <= hi; v += step) set.add(v);
+  }
+  // Normalize Sunday: dow 7 → 0 (so the matcher can use a single set)
+  if (range.name === "dow" && set.has(7)) { set.add(0); set.delete(7); }
+  return set;
+}
+
+function parseCron(expr) {
+  if (typeof expr !== "string" || expr.length === 0) {
+    throw new SchedulerError("scheduler/invalid-cron",
+      "cron expression must be a non-empty string", true);
+  }
+  var trimmed = expr.trim();
+  if (CRON_SHORTHANDS[trimmed.toLowerCase()]) {
+    trimmed = CRON_SHORTHANDS[trimmed.toLowerCase()];
+  }
+  var fields = trimmed.split(/\s+/);
+  if (fields.length !== 5) {
+    throw new SchedulerError("scheduler/invalid-cron",
+      "cron expression must have 5 fields (got " + fields.length + "): " + expr, true);
+  }
+  var sets = [];
+  for (var i = 0; i < 5; i++) {
+    sets.push(_parseCronField(fields[i], CRON_FIELD_RANGES[i]));
+  }
+  return {
+    expr:   trimmed,
+    minute: sets[0],
+    hour:   sets[1],
+    dom:    sets[2],
+    month:  sets[3],
+    dow:    sets[4],
+    // Whether dom or dow was constrained — matters for the cron quirk
+    // where day-of-month and day-of-week are OR'd when both are set.
+    domRestricted: sets[2].size < (CRON_FIELD_RANGES[2].max - CRON_FIELD_RANGES[2].min + 1),
+    dowRestricted: sets[4].size < 7,
+  };
+}
+
+// ---- Timezone-aware wall-clock helpers ----
+//
+// We need "what's the wall clock in TZ for time T?" and "given wall
+// clock W in TZ, what UTC instant does that correspond to?". Intl
+// gives us the first cheaply. The second is approximated by walking
+// minute-by-minute — accurate enough for cron schedules (DST gaps fire
+// at the next valid wall-clock instant; overlaps fire once at the
+// first matching instant).
+
+function _getWallClockParts(date, timeZone) {
+  if (!timeZone) {
+    return {
+      year:   date.getFullYear(),
+      month:  date.getMonth() + 1,
+      day:    date.getDate(),
+      hour:   date.getHours(),
+      minute: date.getMinutes(),
+      dow:    date.getDay(),
+    };
+  }
+  var fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone: timeZone,
+    year: "numeric", month: "2-digit", day: "2-digit",
+    hour: "2-digit", minute: "2-digit", weekday: "short",
+    hour12: false,
+  });
+  var parts = {};
+  fmt.formatToParts(date).forEach(function (p) { parts[p.type] = p.value; });
+  var dowMap = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+  var hr = parseInt(parts.hour, 10);
+  if (hr === 24) hr = 0; // some locales emit 24:00
+  return {
+    year:   parseInt(parts.year, 10),
+    month:  parseInt(parts.month, 10),
+    day:    parseInt(parts.day, 10),
+    hour:   hr,
+    minute: parseInt(parts.minute, 10),
+    dow:    dowMap[parts.weekday] || 0,
+  };
+}
+
+function _validateTimezone(tz) {
+  if (!tz) return null;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz }).format(new Date());
+    return tz;
+  } catch (_e) {
+    throw new SchedulerError("scheduler/invalid-timezone",
+      "unknown IANA timezone '" + tz + "'", true);
+  }
+}
+
+function _matchesCron(cron, parts) {
+  if (!cron.minute.has(parts.minute)) return false;
+  if (!cron.hour.has(parts.hour))     return false;
+  if (!cron.month.has(parts.month))   return false;
+  // POSIX cron quirk: when both dom AND dow are restricted, the day
+  // matches if EITHER matches (OR). When only one is restricted,
+  // standard AND.
+  var domOk = cron.dom.has(parts.day);
+  var dowOk = cron.dow.has(parts.dow);
+  if (cron.domRestricted && cron.dowRestricted) return domOk || dowOk;
+  if (cron.domRestricted) return domOk;
+  if (cron.dowRestricted) return dowOk;
+  return true; // both fully wild
+}
+
+// nextCronFire — earliest UTC ms ≥ `after` whose wall-clock in `tz`
+// matches the cron sets. Walks minute by minute; bounded at ~530K
+// iterations (1 year of minutes) before giving up with a clear error.
+function nextCronFire(cron, after, timeZone) {
+  // Round up to the next whole minute boundary
+  var t = new Date(after.getTime() + (60000 - (after.getTime() % 60000)) % 60000);
+  if (t.getTime() <= after.getTime()) t = new Date(t.getTime() + 60000);
+  var maxIters = 366 * 24 * 60 + 60;
+  for (var i = 0; i < maxIters; i++) {
+    var parts = _getWallClockParts(t, timeZone);
+    if (_matchesCron(cron, parts)) return t.getTime();
+    t = new Date(t.getTime() + 60000);
+  }
+  throw new SchedulerError("scheduler/cron-no-fire",
+    "cron expression '" + cron.expr + "' produced no fire within 1 year " +
+    "(impossible date constraint?)", true);
+}
+
+// nextBaselineFire — next UTC ms whose wall-clock in `tz` matches HH:MM.
+function nextBaselineFire(timeOfDay, timeZone, after) {
+  var match = String(timeOfDay).match(/^(\d{1,2}):(\d{2})$/);
+  if (!match) {
+    throw new SchedulerError("scheduler/invalid-baseline",
+      "baseline must be HH:MM (got '" + timeOfDay + "')", true);
+  }
+  var hh = parseInt(match[1], 10);
+  var mm = parseInt(match[2], 10);
+  if (hh < 0 || hh > 23 || mm < 0 || mm > 59) {
+    throw new SchedulerError("scheduler/invalid-baseline",
+      "baseline '" + timeOfDay + "' is not a valid 24h time", true);
+  }
+  var t = new Date(after.getTime() + (60000 - (after.getTime() % 60000)) % 60000);
+  if (t.getTime() <= after.getTime()) t = new Date(t.getTime() + 60000);
+  for (var i = 0; i < 24 * 60 + 60; i++) {
+    var parts = _getWallClockParts(t, timeZone);
+    if (parts.hour === hh && parts.minute === mm) return t.getTime();
+    t = new Date(t.getTime() + 60000);
+  }
+  throw new SchedulerError("scheduler/baseline-no-fire",
+    "baseline '" + timeOfDay + "' produced no fire within 24h+ (timezone bug?)", true);
+}
+
+// ---- Engine ----
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "jobs", "cluster", "audit",
+    "maxJobMs", "tickRetentionMs", "pruneIntervalMs",
+  ], "scheduler");
+  var jobsInstance    = opts.jobs    || null;
+  var clusterInstance = opts.cluster || null;
+  var auditOn         = opts.audit !== false;
+  var maxJobMs        = opts.maxJobMs || DEFAULT_MAX_JOB_MS;
+  var tickRetentionMs = opts.tickRetentionMs != null
+    ? opts.tickRetentionMs : DEFAULT_TICK_RETENTION_MS;
+  var pruneIntervalMs = opts.pruneIntervalMs != null
+    ? opts.pruneIntervalMs : DEFAULT_TICK_PRUNE_INTERVAL_MS;
+
+  // name → task
+  var tasks   = new Map();
+  var timers  = new Set();
+  var started = false;
+  var lastPruneAt = 0;
+
+  var _err = SchedulerError.factory;
+
+  function _emit(action, info, outcome) {
+    if (!auditOn) return;
+    audit().safeEmit({
+      action:   action,
+      outcome:  outcome,
+      metadata: info || {},
+      reason:   info && info.reason ? info.reason : null,
+    });
+  }
+
+  function _isLeaderHere() {
+    if (!clusterInstance) return true;
+    try {
+      if (typeof clusterInstance.isLeader === "function") return !!clusterInstance.isLeader();
+    } catch (_e) { /* treat unknown leadership state as not-leader */ }
+    return false;
+  }
+
+  function schedule(spec) {
+    if (started) {
+      throw _err("ALREADY_STARTED",
+        "scheduler.schedule: cannot register '" + (spec && spec.name) +
+        "' after start() — schedule all tasks before calling start()", true);
+    }
+    if (!spec || typeof spec !== "object") {
+      throw _err("INVALID_SPEC", "scheduler.schedule requires a spec object", true);
+    }
+    if (typeof spec.name !== "string" || spec.name.length === 0) {
+      throw _err("INVALID_NAME", "scheduler.schedule: spec.name is required", true);
+    }
+    if (tasks.has(spec.name)) {
+      throw _err("DUPLICATE_NAME",
+        "scheduler.schedule: '" + spec.name + "' is already scheduled", true);
+    }
+
+    var hasCron     = typeof spec.cron === "string";
+    var hasEvery    = typeof spec.every === "number";
+    if ((hasCron && hasEvery) || (!hasCron && !hasEvery)) {
+      throw _err("INVALID_SPEC",
+        "scheduler.schedule: spec must set exactly one of cron / every (got cron=" +
+        hasCron + ", every=" + hasEvery + ")", true);
+    }
+    if (hasEvery && (!Number.isFinite(spec.every) || spec.every < 1000)) {
+      throw _err("INVALID_SPEC",
+        "scheduler.schedule: spec.every must be a number ≥ 1000 ms", true);
+    }
+    var hasJob = typeof spec.job === "string" && spec.job.length > 0;
+    var hasRun = typeof spec.run === "function";
+    if ((hasJob && hasRun) || (!hasJob && !hasRun)) {
+      throw _err("INVALID_SPEC",
+        "scheduler.schedule: spec must set exactly one of job / run", true);
+    }
+    if (hasJob && !jobsInstance) {
+      throw _err("INVALID_SPEC",
+        "scheduler.schedule: spec.job requires opts.jobs at scheduler.create — " +
+        "use spec.run for direct-function tasks when jobs is unwired", true);
+    }
+
+    var tz = _validateTimezone(spec.timezone || null);
+    var task = {
+      name:      spec.name,
+      timezone:  tz,
+      job:       hasJob ? spec.job : null,
+      payload:   spec.payload || null,
+      run:       hasRun ? spec.run : null,
+      enqueueOpts: spec.enqueueOpts || null,
+      lastRun:   null,
+      lastFinish: null,
+      lastError: null,
+      running:   false,
+      runningSince: 0,
+      fires:     0,
+      misses:    0,    // skipped because previous run still in-flight
+      nonLeaderSkips: 0,
+      tickClaimLost:  0, // lost the tick-claim race to another leader (cluster only)
+    };
+    if (hasCron) {
+      task.kind = "cron";
+      task.cron = parseCron(spec.cron);
+      task.exprDesc = "cron " + task.cron.expr + (tz ? " " + tz : "");
+      task.nextRun = nextCronFire(task.cron, new Date(), tz);
+    } else {
+      task.kind = "every";
+      task.every = spec.every;
+      if (spec.baseline) {
+        task.baseline = spec.baseline;
+        task.nextRun = nextBaselineFire(spec.baseline, tz, new Date());
+      } else {
+        // Initial offset: fire one full interval after start (consistent
+        // with how operators usually expect interval timers).
+        task.nextRun = Date.now() + spec.every;
+      }
+      task.exprDesc = "every " + spec.every + "ms" +
+                      (spec.baseline ? " from " + spec.baseline : "") +
+                      (tz ? " " + tz : "");
+    }
+
+    tasks.set(spec.name, task);
+    return task;
+  }
+
+  function _computeNextRun(task, after) {
+    if (task.kind === "cron") {
+      return nextCronFire(task.cron, new Date(after), task.timezone);
+    }
+    // every: anchor on baseline if set (so day-to-day drift stays
+    // bounded), otherwise pure interval from `after`.
+    if (task.baseline) {
+      return nextBaselineFire(task.baseline, task.timezone, new Date(after));
+    }
+    return after + task.every;
+  }
+
+  function _fireOnce(task) {
+    // Skip if previous run still in flight.
+    if (task.running) {
+      // Watchdog: if we're past MAX_JOB_MS, force-clear and let this fire.
+      if (task.runningSince && (Date.now() - task.runningSince) > maxJobMs) {
+        try {
+          log().warn("[scheduler] '" + task.name + "' exceeded " +
+            (maxJobMs / 1000) + "s — forcing reset");
+        } catch (_e) { /* logger best-effort */ }
+        _emit("system.scheduler.task.watchdog", { name: task.name }, "failure");
+        task.running = false;
+      } else {
+        task.misses++;
+        _emit("system.scheduler.task.skipped",
+          { name: task.name, reason: "previous-run-in-flight" }, "denied");
+        return;
+      }
+    }
+
+    // Cluster leader gate. Compute nextRun even when not leader so a
+    // leader transition picks up cleanly without a state reload.
+    if (!_isLeaderHere()) {
+      task.nonLeaderSkips++;
+      task.nextRun = _computeNextRun(task, Date.now());
+      return;
+    }
+
+    // Capture the nominal scheduled time for this tick before we
+    // recompute nextRun for the next firing.
+    var nominalRun = task.nextRun;
+
+    // Compute the next fire time forward from now (not from nominal
+    // nextRun) so a long-running fire doesn't queue up backlog ticks.
+    // Done before any await so _arm() reads the fresh value when it
+    // re-arms after this synchronous return.
+    task.nextRun = _computeNextRun(task, Date.now());
+
+    // Cluster mode: race for the tick-claim row. Loser of the INSERT
+    // skips silently. Single-node mode (no clusterInstance wired) fires
+    // unconditionally — there's only one process so no contention is
+    // possible.
+    if (clusterInstance) {
+      var tickKey = task.name + ":" + nominalRun;
+      var claimedBy = (typeof clusterInstance.currentNodeId === "function")
+        ? clusterInstance.currentNodeId() : "unknown";
+      clusterStorage.execute(
+        "INSERT INTO _blamejs_scheduler_ticks " +
+        "(tickKey, name, scheduledAtUnix, claimedAtUnix, claimedBy) " +
+        "VALUES (?, ?, ?, ?, ?) " +
+        "ON CONFLICT (tickKey) DO NOTHING",
+        [tickKey, task.name, nominalRun, Date.now(), claimedBy]
+      ).then(function (result) {
+        var won = (result && result.rowCount > 0);
+        if (won) {
+          _runFire(task);
+        } else {
+          task.tickClaimLost++;
+          _emit("system.scheduler.tick.lost", {
+            name: task.name, tickKey: tickKey, claimedBy: claimedBy,
+          }, "denied");
+        }
+      }, function (e) {
+        try {
+          log().warn("[scheduler] tick-claim failed for '" + task.name + "'",
+            { error: (e && e.message) || String(e) });
+        } catch (_e) { /* logger best-effort */ }
+        _emit("system.scheduler.tick.error", {
+          name: task.name, tickKey: tickKey,
+          reason: (e && e.message) || String(e),
+        }, "failure");
+      });
+      return;
+    }
+
+    _runFire(task);
+  }
+
+  // Operator-callable prune. Deletes _blamejs_scheduler_ticks rows whose
+  // scheduledAtUnix is older than `olderThanMs` (default = retention
+  // window passed to scheduler.create). Returns a Promise that resolves
+  // to the number of rows removed. No-op if cluster wiring is absent
+  // (single-node scheduler doesn't write tick rows).
+  async function pruneTickClaims(olderThanMs) {
+    if (!clusterInstance) return 0;
+    var threshold = Date.now() - (
+      typeof olderThanMs === "number" ? olderThanMs : tickRetentionMs
+    );
+    var result = await clusterStorage.execute(
+      "DELETE FROM _blamejs_scheduler_ticks WHERE scheduledAtUnix < ?",
+      [threshold]
+    );
+    var removed = (result && result.rowCount) || 0;
+    if (removed > 0) {
+      _emit("system.scheduler.tick.pruned", {
+        rowsDeleted:    removed,
+        olderThanUnix:  threshold,
+      });
+    }
+    return removed;
+  }
+
+  // Rate-limited best-effort prune called after a successful tick claim.
+  // Errors are swallowed — pruning is housekeeping, not part of the fire
+  // critical path.
+  function _maybePruneTickClaims() {
+    if (!clusterInstance) return;
+    if (tickRetentionMs <= 0) return;
+    var now = Date.now();
+    if (now - lastPruneAt < pruneIntervalMs) return;
+    lastPruneAt = now;
+    pruneTickClaims().catch(function (e) {
+      try {
+        log().warn("[scheduler] tick-claim prune failed",
+          { error: (e && e.message) || String(e) });
+      } catch (_e) { /* logger best-effort */ }
+    });
+  }
+
+  function _runFire(task) {
+    _maybePruneTickClaims();
+    task.fires++;
+    task.running = true;
+    task.runningSince = Date.now();
+    task.lastRun = new Date().toISOString();
+    var startedAt = Date.now();
+
+    var promise;
+    try {
+      if (task.job) {
+        promise = jobsInstance.enqueue(task.job, task.payload || {}, task.enqueueOpts || {});
+      } else {
+        promise = Promise.resolve(task.run());
+      }
+    } catch (e) {
+      promise = Promise.reject(e);
+    }
+
+    Promise.resolve(promise).then(function (_v) {
+      task.running = false;
+      task.runningSince = 0;
+      task.lastFinish = new Date().toISOString();
+      task.lastError = null;
+      _emit("system.scheduler.task.success", {
+        name:       task.name,
+        kind:       task.kind,
+        durationMs: Date.now() - startedAt,
+        viaJob:     !!task.job,
+      });
+    }, function (e) {
+      task.running = false;
+      task.runningSince = 0;
+      task.lastFinish = new Date().toISOString();
+      task.lastError = (e && e.message) || String(e);
+      try {
+        log().error("[scheduler] '" + task.name + "' failed", { error: task.lastError });
+      } catch (_e) { /* logger best-effort */ }
+      _emit("system.scheduler.task.failure", {
+        name:       task.name,
+        kind:       task.kind,
+        durationMs: Date.now() - startedAt,
+        viaJob:     !!task.job,
+        reason:     task.lastError,
+      }, "failure");
+    });
+  }
+
+  function _arm(task) {
+    var delay = Math.max(0, task.nextRun - Date.now());
+    var t = setTimeout(function () {
+      timers.delete(t);
+      if (!started) return;
+      _fireOnce(task);
+      if (!started) return;
+      _arm(task);
+    }, delay);
+    if (typeof t.unref === "function") t.unref();
+    timers.add(t);
+  }
+
+  async function start() {
+    if (started) return;
+    started = true;
+    tasks.forEach(function (task) { _arm(task); });
+    _emit("scheduler.start", { count: tasks.size });
+  }
+
+  async function stop() {
+    if (!started) return;
+    started = false;
+    timers.forEach(function (t) { try { clearTimeout(t); } catch (_e) {} });
+    timers.clear();
+    _emit("scheduler.stop", { count: tasks.size });
+  }
+
+  function list() {
+    var out = [];
+    tasks.forEach(function (task) {
+      out.push({
+        name:           task.name,
+        when:           task.exprDesc,
+        kind:           task.kind,
+        timezone:       task.timezone || null,
+        lastRun:        task.lastRun,
+        lastFinish:     task.lastFinish,
+        lastError:      task.lastError,
+        nextRun:        task.nextRun ? new Date(task.nextRun).toISOString() : null,
+        running:        task.running,
+        fires:          task.fires,
+        misses:         task.misses,
+        nonLeaderSkips: task.nonLeaderSkips,
+        tickClaimLost:  task.tickClaimLost,
+      });
+    });
+    return out;
+  }
+
+  function _resetForTest() {
+    tasks.forEach(function (_t, _n) { /* noop — drop refs below */ });
+    timers.forEach(function (t) { try { clearTimeout(t); } catch (_e) {} });
+    timers.clear();
+    tasks.clear();
+    started = false;
+  }
+
+  return {
+    schedule:      schedule,
+    start:         start,
+    stop:          stop,
+    list:          list,
+    pruneTickClaims: pruneTickClaims,
+    _fireOnce:     function (name) { // test hook
+      var task = tasks.get(name);
+      if (!task) throw _err("UNKNOWN_NAME", "no task '" + name + "'", true);
+      _fireOnce(task);
+    },
+    _resetForTest: _resetForTest,
+  };
+}
+
+module.exports = {
+  create:           create,
+  parseCron:        parseCron,
+  nextCronFire:     nextCronFire,
+  nextBaselineFire: nextBaselineFire,
+  SchedulerError:   SchedulerError,
+};