Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

29.9 KB
Raw Blame
/**
 * Event Scheduler Service
 *
 * Event-driven scheduling with cron expressions and timeout-safe timers.
 * Replaces setInterval with more robust scheduling.
 */

import { cosEvents, emitLog } from './cosEvents.js'
import { getLocalParts } from '../lib/timezone.js'
import { recurrenceRuleSchema } from '../lib/recurrenceValidation.js'
// Syntax/range validation is shared with every save boundary and the browser
// cron editor, so an expression the routes accept is exactly the set this
// walker can search (#6634).
import { isValidCronField, CRON_FIELD_BOUNDS, CRON_FIELD_NAMES } from '../lib/cronValidation.js'
// Field MATCHING is shared with the quality-schedule planner, so an hour the
// planner reads as free is exactly an hour this walker will not fire in.
import { matchesCronField } from '../lib/cronFields.js'

// Maximum safe setTimeout value (2^31 - 1 ms, ~24.8 days)
const MAX_TIMEOUT = 2147483647

// Boot grace period for overdue interval schedules across restarts (#12624)
const BOOT_GRACE_MS = 2 * 60 * 1000 // 2 minutes

function parseTimestamp(value) {
  if (value == null) return null
  if (typeof value === 'number') {
    return Number.isFinite(value) && value > 0 ? value : null
  }
  if (value instanceof Date) {
    const ms = value.getTime()
    return Number.isFinite(ms) && ms > 0 ? ms : null
  }
  if (typeof value === 'string') {
    const trimmed = value.trim()
    if (!trimmed) return null
    if (/^\d+$/.test(trimmed)) {
      const num = Number(trimmed)
      return Number.isFinite(num) && num > 0 ? num : null
    }
    const ms = Date.parse(trimmed)
    return Number.isFinite(ms) && ms > 0 ? ms : null
  }
  return null
}

// Scheduled events storage
const scheduledEvents = new Map()

// Active timers
const activeTimers = new Map()

// Cancellation removes an event from the registry while its handler can still
// be writing. Keep those runs until shutdown has drained them before DB close.
const activeRuns = new Set()
let quiesced = false

// Event history
const eventHistory = []
const MAX_HISTORY = 500

// Maximum iterations for cron search loop (2 years in minutes, matches maxDate window)
const MAX_CRON_ITERATIONS = 1051920

/**
 * Walk a cron expression in either direction until a matching minute is found.
 *
 * @param {string} cronExpr - Cron expression
 * @param {Date} from - Starting point (default: now)
 * @param {string} timezone - IANA timezone for matching (default: 'UTC')
 * @param {Object} options - Walk options
 * @param {number} options.stepMs - Signed minute step; positive walks forward,
 *   negative walks backward
 * @param {Date|null} options.until - Optional exclusive forward search bound
 * @returns {Date|null} - Matching execution time, or null if invalid/no match
 */
function walkCron(cronExpr, from = new Date(), timezone = 'UTC', { stepMs, until = null } = {}) {
  if (!Number.isFinite(stepMs) || stepMs === 0) {
    throw new Error(`Cron walk requires a non-zero step: ${stepMs}`)
  }

  const parts = cronExpr.trim().split(/\s+/)
  if (parts.length !== 5) {
    throw new Error(`Invalid cron expression: ${cronExpr}`)
  }

  const [minuteExpr, hourExpr, dayOfMonthExpr, monthExpr, dayOfWeekExpr] = parts

  // Validate cron field ranges before entering the search loop. Out-of-range
  // fields return null (not throw) — callers rely on that; the save boundaries
  // reject such expressions up front with the same shared validator.
  for (let i = 0; i < parts.length; i += 1) {
    const [min, max] = CRON_FIELD_BOUNDS[i]
    if (!isValidCronField(parts[i], min, max)) {
      console.error(`❌ Invalid cron ${CRON_FIELD_NAMES[i]} field "${parts[i]}" in expression: ${cronExpr}`)
      return null
    }
  }

  const direction = Math.sign(stepMs)
  const cursor = new Date(from)
  cursor.setSeconds(0, 0)
  if (direction > 0) cursor.setMinutes(cursor.getMinutes() + 1)

  const boundary = new Date(from)
  boundary.setFullYear(boundary.getFullYear() + (direction > 0 ? 2 : -2))
  const maxDate = direction > 0 && until instanceof Date && until < boundary ? until : boundary

  const useLocal = timezone !== 'UTC'

  let iterations = 0
  while (direction > 0 ? cursor < maxDate : cursor > maxDate) {
    if (++iterations > MAX_CRON_ITERATIONS) {
      console.error(`❌ Cron search exceeded ${MAX_CRON_ITERATIONS} iterations for: ${cronExpr}`)
      return null
    }

    let month, day, dow, hour, minute
    if (useLocal) {
      const lp = getLocalParts(cursor, timezone)
      month = lp.month; day = lp.day; dow = lp.dayOfWeek; hour = lp.hour; minute = lp.minute
    } else {
      month = cursor.getMonth() + 1; day = cursor.getDate(); dow = cursor.getDay()
      hour = cursor.getHours(); minute = cursor.getMinutes()
    }

    // Normalize DOW: cron allows 7 for Sunday, but JS getDay() returns 0
    // Match both 0 and 7 representations for Sunday
    const dowMatches = matchesCronField(dow, dayOfWeekExpr, 0) ||
      (dow === 0 && matchesCronField(7, dayOfWeekExpr, 0))

    if (matchesCronField(month, monthExpr, 1) &&
        matchesCronField(day, dayOfMonthExpr, 1) &&
        dowMatches &&
        matchesCronField(hour, hourExpr, 0) &&
        matchesCronField(minute, minuteExpr, 0)) {
      return cursor
    }
    cursor.setTime(cursor.getTime() + stepMs)
  }

  return null
}

/**
 * Parse cron expression to next execution time.
 * @param {string} cronExpr - Cron expression
 * @param {Date} from - Starting point (default: now)
 * @param {string} timezone - IANA timezone for matching (default: 'UTC')
 * @param {Date|null} until - Optional exclusive search bound
 * @returns {Date|null} - Next execution time (UTC), or null if invalid/no match
 */
function parseCronToNextRun(cronExpr, from = new Date(), timezone = 'UTC', until = null) {
  return walkCron(cronExpr, from, timezone, { stepMs: 60 * 1000, until })
}

/**
 * Parse cron expression to most-recent past execution time (at or before `from`).
 *
 * Mirrors parseCronToNextRun but walks backwards. Used to detect missed cron slots
 * for catch-up logic when the daemon was down across a scheduled time.
 *
 * @param {string} cronExpr - Cron expression
 * @param {Date} from - Reference point; result will be <= from
 * @param {string} timezone - IANA timezone for matching
 * @returns {Date|null} - Previous execution time (UTC), or null if invalid/no match within 2 years
 */
function parseCronToPrevRun(cronExpr, from = new Date(), timezone = 'UTC') {
  return walkCron(cronExpr, from, timezone, { stepMs: -60 * 1000 })
}

const RECURRENCE_DAY = 24 * 60 * 60 * 1000

function localDaySerial(parts) {
  return Date.UTC(parts.year, parts.month - 1, parts.day) / RECURRENCE_DAY
}

function parseAnchorDate(value) {
  if (typeof value !== 'string') return null
  const match = value.match(/^(\d{4})-(\d{2})-(\d{2})$/)
  if (!match) return null
  const year = Number(match[1]); const month = Number(match[2]); const day = Number(match[3])
  const date = new Date(Date.UTC(year, month - 1, day))
  if (date.getUTCFullYear() !== year || date.getUTCMonth() + 1 !== month || date.getUTCDate() !== day) return null
  return { year, month, day, serial: date.getTime() / RECURRENCE_DAY, dayOfWeek: date.getUTCDay() }
}

function daysInMonth(year, month) {
  return new Date(Date.UTC(year, month, 0)).getUTCDate()
}

function localDateFromSerial(serial) {
  const date = new Date(serial * RECURRENCE_DAY)
  return {
    year: date.getUTCFullYear(),
    month: date.getUTCMonth() + 1,
    day: date.getUTCDate(),
    dayOfWeek: date.getUTCDay(),
    serial,
  }
}

function monthSerial(year, month) {
  return year * 12 + month - 1
}

function localMonthFromSerial(serial) {
  const year = Math.floor(serial / 12)
  return { year, month: serial - year * 12 + 1 }
}

/**
 * Resolve a local calendar date/time to its UTC instant. A short correction
 * loop handles ordinary timezone offsets and DST transitions without walking
 * every minute between `from` and the next sparse occurrence.
 */
function localDateTimeToUtc(date, time, timezone) {
  const [hour, minute] = time.split(':').map(Number)
  const targetMs = Date.UTC(date.year, date.month - 1, date.day, hour, minute)
  let candidate = new Date(targetMs)

  for (let attempt = 0; attempt < 4; attempt += 1) {
    const actual = getLocalParts(candidate, timezone)
    const actualMs = Date.UTC(actual.year, actual.month - 1, actual.day, actual.hour, actual.minute)
    const deltaMs = targetMs - actualMs
    if (deltaMs === 0) return candidate
    candidate = new Date(candidate.getTime() + deltaMs)
  }

  // A local time skipped by a DST spring-forward has no exact UTC instant.
  return null
}

function weekdayOfMonth(year, month, weekday, ordinal) {
  const lastDay = daysInMonth(year, month)
  if (ordinal === 'last') {
    const lastWeekday = new Date(Date.UTC(year, month - 1, lastDay)).getUTCDay()
    return lastDay - ((lastWeekday - weekday + 7) % 7)
  }

  const ordinalNumber = { first: 1, second: 2, third: 3, fourth: 4 }[ordinal]
  if (!ordinalNumber) return null
  const firstWeekday = new Date(Date.UTC(year, month - 1, 1)).getUTCDay()
  const day = 1 + ((weekday - firstWeekday + 7) % 7) + (ordinalNumber - 1) * 7
  return day <= lastDay ? day : null
}

function findNextRecurrenceCandidate(rule, anchor, from, timezone, maxDate) {
  const reference = getLocalParts(from, timezone)
  const referenceSerial = localDaySerial(reference)
  const maxLocalParts = getLocalParts(new Date(maxDate.getTime() - 1), timezone)
  const maxSerial = localDaySerial(maxLocalParts)
  const isUsable = date => {
    if (!date || date.serial < anchor.serial || date.serial < referenceSerial || date.serial > maxSerial) return null
    const candidate = localDateTimeToUtc(date, rule.time, timezone)
    return candidate && candidate > from && candidate < maxDate ? candidate : null
  }

  if (rule.frequency === 'daily') {
    const firstSerial = Math.max(anchor.serial, referenceSerial)
    const firstIndex = Math.max(0, Math.ceil((firstSerial - anchor.serial) / rule.interval))
    for (let index = firstIndex; ; index += 1) {
      const serial = anchor.serial + index * rule.interval
      if (serial > maxSerial) return null
      const date = localDateFromSerial(serial)
      if (rule.weekdays.length && !rule.weekdays.includes(date.dayOfWeek)) continue
      const candidate = isUsable(date)
      if (candidate) return candidate
    }
  }

  if (rule.frequency === 'weekly') {
    const anchorWeek = anchor.serial - anchor.dayOfWeek
    const referenceWeek = referenceSerial - reference.dayOfWeek
    const firstWeek = Math.max(anchorWeek, referenceWeek)
    const firstIndex = Math.max(0, Math.ceil((firstWeek - anchorWeek) / (7 * rule.interval)))
    const weekdays = [...rule.weekdays].sort((a, b) => a - b)
    for (let index = firstIndex; ; index += 1) {
      const weekStart = anchorWeek + index * rule.interval * 7
      if (weekStart > maxSerial) return null
      for (const weekday of weekdays) {
        const date = localDateFromSerial(weekStart + weekday)
        const candidate = isUsable(date)
        if (candidate) return candidate
      }
    }
  }

  const anchorMonth = monthSerial(anchor.year, anchor.month)
  const referenceMonth = monthSerial(reference.year, reference.month)
  const firstMonth = Math.max(anchorMonth, referenceMonth)
  const firstIndex = Math.max(0, Math.ceil((firstMonth - anchorMonth) / rule.interval))
  const maxMonth = monthSerial(maxLocalParts.year, maxLocalParts.month)

  for (let index = firstIndex; ; index += 1) {
    const currentMonth = anchorMonth + index * rule.interval
    if (currentMonth > maxMonth) return null
    const { year, month } = localMonthFromSerial(currentMonth)
    const day = rule.frequency === 'monthly-date'
      ? (rule.dayOfMonth <= daysInMonth(year, month) ? rule.dayOfMonth : null)
      : weekdayOfMonth(year, month, rule.weekday, rule.ordinal)
    if (!day) continue
    const candidate = isUsable({
      year,
      month,
      day,
      dayOfWeek: new Date(Date.UTC(year, month - 1, day)).getUTCDay(),
      serial: Date.UTC(year, month - 1, day) / RECURRENCE_DAY,
    })
    if (candidate) return candidate
  }
}

/**
 * Find the next local-calendar occurrence for an anchored recurrence rule.
 * Unlike cron, the interval is measured from the persisted local anchor, so
 * every two weeks remains every two weeks across month boundaries and DST.
 */
function parseRecurrenceToNextRun(rule, from = new Date(), timezone = 'UTC', until = null) {
  const parsed = recurrenceRuleSchema.safeParse(rule)
  if (!parsed.success) return null
  const normalized = parsed.data
  if (normalized.frequency === 'custom') return parseCronToNextRun(normalized.cron, from, timezone, until)

  const reference = getLocalParts(from, timezone)
  const parsedAnchor = parseAnchorDate(normalized.anchorDate)
  if (normalized.anchorDate && !parsedAnchor) return null
  const anchor = parsedAnchor || {
    year: reference.year,
    month: reference.month,
    day: reference.day,
    serial: localDaySerial(reference),
    dayOfWeek: reference.dayOfWeek,
  }
  const boundary = new Date(from)
  boundary.setFullYear(boundary.getFullYear() + 2)
  // The two-year search horizon is relative to `from`, but a persisted anchor
  // may intentionally begin farther in the future. Extend the horizon through
  // that anchor so a valid recurrence is not rejected merely because its first
  // occurrence lies beyond the runtime look-ahead window.
  if (parsedAnchor) {
    const anchorBoundary = new Date(Date.UTC(parsedAnchor.year, parsedAnchor.month - 1, parsedAnchor.day))
    anchorBoundary.setUTCFullYear(anchorBoundary.getUTCFullYear() + 2)
    if (anchorBoundary > boundary) boundary.setTime(anchorBoundary.getTime())
  }
  const maxDate = until instanceof Date && until < boundary ? until : boundary
  return findNextRecurrenceCandidate(normalized, anchor, from, timezone, maxDate)
}


/**
 * Create a timeout-safe timer
 * Handles values larger than MAX_TIMEOUT by chaining
 *
 * @param {Function} callback - Function to call
 * @param {number} delayMs - Delay in milliseconds
 * @param {string} eventId - Event identifier for tracking
 * @returns {Object} - Timer handle
 */
function createSafeTimer(callback, delayMs, eventId) {
  const clampedDelay = Math.min(delayMs, MAX_TIMEOUT)

  if (delayMs <= MAX_TIMEOUT) {
    // Simple case - use regular setTimeout
    const timerId = setTimeout(() => {
      activeTimers.delete(eventId)
      callback()
    }, clampedDelay)

    return { timerId, type: 'simple' }
  }

  // Chain timeouts for longer delays
  const remaining = delayMs - MAX_TIMEOUT
  const timerId = setTimeout(() => {
    // Schedule the next chunk
    const nextTimer = createSafeTimer(callback, remaining, eventId)
    activeTimers.set(eventId, nextTimer)
  }, MAX_TIMEOUT)

  return { timerId, type: 'chained', remaining }
}

/**
 * Schedule an event
 *
 * @param {Object} config - Event configuration
 * @param {string} config.id - Unique event identifier
 * @param {string} config.type - Event type (cron, interval, once)
 * @param {string} config.cron - Cron expression (for type: cron)
 * @param {Object} config.recurrence - Anchored calendar rule (for type: recurrence)
 * @param {number} config.intervalMs - Interval in ms (for type: interval)
 * @param {number} config.delayMs - Delay in ms (for type: once)
 * @param {Function} config.handler - Event handler function
 * @param {Object} config.metadata - Additional metadata
 * @returns {Object} - Scheduled event
 */
function schedule(config) {
  const { id, type, cron, recurrence, timezone, intervalMs, delayMs, handler, metadata = {}, lastRunAt = null } = config

  if (!id || !type || !handler) {
    throw new Error('Event requires id, type, and handler')
  }

  // Cancel existing event with same ID
  if (scheduledEvents.has(id)) {
    cancel(id)
  }

  const parsedLastRunAt = parseTimestamp(lastRunAt)

  const event = {
    id,
    type,
    cron,
    recurrence,
    timezone: timezone || 'UTC',
    intervalMs,
    delayMs,
    handler,
    metadata,
    createdAt: Date.now(),
    nextRunAt: null,
    lastRunAt: parsedLastRunAt,
    runCount: 0,
    active: !quiesced,
    lastRunSucceeded: null,
    lastRunSkipped: null,
    lastSkipReason: null,
    lastError: null,
    consecutiveFailures: 0,
    // The promise of the run in progress, or null. One run per event at a
    // time: a trigger that lands mid-run joins it instead of starting a
    // second handler over the same state (#12022).
    inFlight: null
  }

  // Calculate next run time
  switch (type) {
    case 'cron':
      if (!cron) throw new Error('Cron type requires cron expression')
      event.nextRunAt = parseCronToNextRun(cron, new Date(), event.timezone)?.getTime() || null
      break

    case 'recurrence':
      if (!recurrence) throw new Error('Recurrence type requires recurrence rule')
      event.nextRunAt = parseRecurrenceToNextRun(recurrence, new Date(), event.timezone)?.getTime() || null
      break

    case 'interval':
      if (!intervalMs) throw new Error('Interval type requires intervalMs')
      if (parsedLastRunAt !== null) {
        event.nextRunAt = Math.max(parsedLastRunAt + intervalMs, Date.now() + BOOT_GRACE_MS)
      } else {
        event.nextRunAt = Date.now() + intervalMs
      }
      break

    case 'once':
      if (!delayMs) throw new Error('Once type requires delayMs')
      event.nextRunAt = Date.now() + delayMs
      break

    default:
      throw new Error(`Unknown event type: ${type}`)
  }

  scheduledEvents.set(id, event)
  scheduleNextRun(event)

  console.log(`📅 Event scheduled: ${id} (${type}) - next run: ${event.nextRunAt ? new Date(event.nextRunAt).toISOString() : 'never'}`)
  cosEvents.emit('scheduler:scheduled', { id, type, nextRunAt: event.nextRunAt })

  return event
}

/**
 * Schedule the next run of an event
 * @param {Object} event - Event object
 */
function scheduleNextRun(event) {
  if (quiesced || !event.active || !event.nextRunAt) return

  const delay = event.nextRunAt - Date.now()
  if (delay < 0) {
    // Already past - run immediately for non-recurring, or calculate next for recurring
    if (event.type === 'once') {
      runEventFloating(event)
      return
    }
    // Calculate next occurrence
    updateNextRunTime(event)
    scheduleNextRun(event)
    return
  }

  // Drop any handle this arm replaces (e.g. triggerNow re-arming ahead of the
  // pending deadline) so the old timeout can't fire a duplicate run later.
  clearPendingTimer(event.id)
  const timer = createSafeTimer(() => runEventFloating(event), delay, event.id)
  activeTimers.set(event.id, timer)
}

/**
 * Start a run without awaiting it, from a timer or another fire-and-forget path.
 * runEvent already swallows handler failures; this catch exists so a defect in
 * runEvent's own bookkeeping surfaces as one log line instead of an unhandled
 * rejection that can take the process down.
 * @param {Object} event - Event object
 */
function runEventFloating(event) {
  runEvent(event).catch(err => {
    console.error(`❌ Event ${event.id} run failed: ${err.message}`)
  })
}

/**
 * Clear an event's pending timeout and forget its handle.
 * @param {string} id - Event identifier
 */
function clearPendingTimer(id) {
  const timer = activeTimers.get(id)
  if (timer) clearTimeout(timer.timerId)
  activeTimers.delete(id)
}

/**
 * Stop an event and drop its pending timer handle.
 * @param {Object} event - Event object
 */
function deactivate(event) {
  event.active = false
  clearPendingTimer(event.id)
}

/**
 * Re-arm an event after a run.
 *
 * Runs from runEvent's `finally`, so a throw anywhere earlier in the run can
 * never leave a recurring schedule un-armed but still listed as active. A next
 * run time that cannot be computed (malformed cron, a recurrence with no
 * occurrence left in the search horizon) deactivates the event with an error
 * line naming the reason, rather than leaving the CoS Schedule tab showing an
 * armed schedule that will never fire again.
 *
 * @param {Object} event - Event object
 */
function rearm(event) {
  if (!event.active) return

  if (event.type === 'once') {
    deactivate(event)
    return
  }

  try {
    updateNextRunTime(event)
  } catch (err) {
    emitLog('error', `Event ${event.id} could not compute its next run (${err.message}) - schedule stopped`, { eventId: event.id, type: event.type })
    deactivate(event)
    return
  }

  if (!event.nextRunAt) {
    emitLog('error', `Event ${event.id} has no next run time - schedule stopped`, { eventId: event.id, type: event.type })
    deactivate(event)
    return
  }

  scheduleNextRun(event)
}

/**
 * Append one run to the bounded history ring.
 * @param {Object} event - Event object
 * @param {Object} result - Run outcome
 * @param {number} result.startTime - Run start timestamp
 * @param {boolean} result.success - Whether the handler completed
 * @param {string|null} result.error - Handler failure message, if any
 */
function recordEventHistory(event, { startTime, success, error, skipped, skipReason }) {
  // push + truncate is faster than unshift + pop for large arrays
  eventHistory.push({
    eventId: event.id,
    type: event.type,
    runAt: startTime,
    duration: Date.now() - startTime,
    success,
    error,
    skipped,
    skipReason
  })

  if (eventHistory.length > MAX_HISTORY) {
    eventHistory.splice(0, eventHistory.length - MAX_HISTORY)
  }
}

/**
 * Run an event, or join the run already in flight for it. Only `runBackup`
 * guards itself; every other handler relies on this latch to never execute
 * twice concurrently.
 * @param {Object} event - Event object
 * @returns {Promise<void>}
 */
function runEvent(event) {
  if (event.inFlight) return event.inFlight
  if (quiesced) return Promise.resolve()
  event.inFlight = executeEvent(event).finally(() => {
    activeRuns.delete(event.inFlight)
    event.inFlight = null
  })
  activeRuns.add(event.inFlight)
  return event.inFlight
}

/**
 * Execute an event's handler once and record the outcome. Callers go through
 * `runEvent`, which owns the in-flight latch.
 * @param {Object} event - Event object
 */
async function executeEvent(event) {
  const startTime = Date.now()

  event.lastRunAt = startTime
  event.runCount++

  let success = true
  let error = null
  let skipped = false
  let skipReason = null

  try {
    const result = await event.handler(event)
    // A handler that did no work reports `{ skipped: true, reason }` so the
    // slot is recorded as skipped rather than as a successful run (#12023).
    if (result?.skipped === true) {
      skipped = true
      skipReason = typeof result.reason === 'string' ? result.reason : null
    }
  } catch (err) {
    success = false
    error = err.message
    emitLog('error', `Event ${event.id} failed: ${err.message}`, {
      eventId: event.id,
      type: event.type,
      source: event.metadata?.source,
      durationMs: Date.now() - startTime,
      stack: err.stack
    })
  } finally {
    event.lastRunSucceeded = success
    event.lastRunSkipped = skipped
    event.lastSkipReason = skipReason
    event.lastError = error
    event.consecutiveFailures = success ? 0 : event.consecutiveFailures + 1

    recordEventHistory(event, { startTime, success, error, skipped, skipReason })

    // A synchronous listener that throws must not cost the schedule its re-arm
    try {
      cosEvents.emit('scheduler:ran', { id: event.id, success, skipped, runCount: event.runCount })
    } catch (err) {
      console.error(`⚠️ Event ${event.id} scheduler:ran listener threw: ${err.message}`)
    }

    rearm(event)
  }
}

/**
 * Update the next run time for a recurring event
 * @param {Object} event - Event object
 */
function updateNextRunTime(event) {
  switch (event.type) {
    case 'cron':
      const nextDate = parseCronToNextRun(event.cron, new Date(), event.timezone || 'UTC')
      event.nextRunAt = nextDate?.getTime() || null
      break

    case 'recurrence':
      const nextRecurrence = parseRecurrenceToNextRun(event.recurrence, new Date(), event.timezone || 'UTC')
      event.nextRunAt = nextRecurrence?.getTime() || null
      break

    case 'interval':
      event.nextRunAt = Date.now() + event.intervalMs
      break

    case 'once':
      event.nextRunAt = null
      break
  }
}

/**
 * Cancel a scheduled event
 * @param {string} id - Event identifier
 * @returns {boolean} - True if event was found and cancelled
 */
function cancel(id) {
  const event = scheduledEvents.get(id)
  if (!event) return false

  event.active = false
  clearPendingTimer(id)

  scheduledEvents.delete(id)
  console.log(`📅 Event cancelled: ${id}`)
  cosEvents.emit('scheduler:cancelled', { id })

  return true
}

/**
 * Pause a scheduled event
 * @param {string} id - Event identifier
 * @returns {boolean} - True if event was found and paused
 */
function pause(id) {
  const event = scheduledEvents.get(id)
  if (!event) return false

  event.active = false
  clearPendingTimer(id)

  console.log(`⏸️ Event paused: ${id}`)
  return true
}

/**
 * Resume a paused event
 * @param {string} id - Event identifier
 * @returns {boolean} - True if event was found and resumed
 */
function resume(id) {
  if (quiesced) return false
  const event = scheduledEvents.get(id)
  if (!event) return false

  event.active = true
  updateNextRunTime(event)
  scheduleNextRun(event)

  console.log(`▶️ Event resumed: ${id}`)
  return true
}

/**
 * Get all scheduled events
 * @returns {Array} - All scheduled events
 */
function getScheduledEvents() {
  return Array.from(scheduledEvents.values()).map(e => ({
    id: e.id,
    type: e.type,
    active: e.active,
    cron: e.cron,
    recurrence: e.recurrence,
    nextRunAt: e.nextRunAt,
    lastRunAt: e.lastRunAt,
    runCount: e.runCount,
    metadata: e.metadata
  }))
}

/**
 * Get event by ID
 * @param {string} id - Event identifier
 * @returns {Object|null} - Event or null
 */
function getEvent(id) {
  const event = scheduledEvents.get(id)
  if (!event) return null

  return {
    id: event.id,
    type: event.type,
    active: event.active,
    cron: event.cron,
    recurrence: event.recurrence,
    intervalMs: event.intervalMs,
    nextRunAt: event.nextRunAt,
    lastRunAt: event.lastRunAt,
    runCount: event.runCount,
    lastRunSucceeded: event.lastRunSucceeded,
    lastRunSkipped: event.lastRunSkipped,
    lastSkipReason: event.lastSkipReason,
    lastError: event.lastError,
    consecutiveFailures: event.consecutiveFailures,
    metadata: event.metadata
  }
}

/**
 * Get event history
 * @param {Object} options - Filter options
 * @returns {Array} - Event history
 */
function getHistory(options = {}) {
  // History is stored oldest-first; reverse for newest-first output
  let history = [...eventHistory].reverse()

  if (options.eventId) {
    history = history.filter(h => h.eventId === options.eventId)
  }

  if (options.success !== undefined) {
    history = history.filter(h => h.success === options.success)
  }

  const limit = options.limit || 50
  return history.slice(0, limit)
}

/**
 * Get scheduler statistics
 * @returns {Object} - Scheduler stats
 */
function getStats() {
  const events = Array.from(scheduledEvents.values())
  // A skipped slot did no work, so it counts toward neither side of the rate.
  const recent = eventHistory.slice(-100).reverse().filter(h => !h.skipped)

  return {
    totalEvents: events.length,
    activeEvents: events.filter(e => e.active).length,
    activeTimers: activeTimers.size,
    byType: events.reduce((acc, e) => {
      acc[e.type] = (acc[e.type] || 0) + 1
      return acc
    }, {}),
    totalRuns: eventHistory.length,
    recentSuccessRate: recent.length > 0
      ? ((recent.filter(h => h.success).length / recent.length) * 100).toFixed(1) + '%'
      : null
  }
}

/**
 * Cancel all scheduled events
 * @returns {number} - Number of events cancelled
 */
function cancelAll() {
  const count = scheduledEvents.size

  for (const id of [...scheduledEvents.keys()]) {
    cancel(id)
  }

  return count
}

/** Stop admitting runs for process exit; active handlers retain their ownership. */
function quiesce() {
  quiesced = true
  for (const event of scheduledEvents.values()) deactivate(event)
}

/** Quiesce first; the shutdown caller owns the bounded wait before closing DB. */
function drain() {
  return Promise.allSettled([...activeRuns])
}

/**
 * Trigger an event immediately (for testing or manual runs). A trigger that
 * lands while the event's timer run is still in flight joins that run rather
 * than starting a second one, and resolves once it finishes.
 * @param {string} id - Event identifier
 * @returns {Promise<boolean|{ joined: true }>} - `false` for an unknown id,
 *   `true` when this call ran the handler, `{ joined: true }` when it waited
 *   on a run already in progress.
 */
async function triggerNow(id) {
  if (quiesced) return false
  const event = scheduledEvents.get(id)
  if (!event) return false

  if (event.inFlight) {
    await event.inFlight
    return { joined: true }
  }

  // Disarm before running: a long manual run must not have its own pending
  // deadline elapse underneath it and start a second, concurrent run.
  clearPendingTimer(id)
  await runEvent(event)
  return true
}

/**
 * Non-throwing predicate: can this scheduler actually parse+run the expression?
 * The single source of truth for "a cron value the scheduler will honor" — reuse
 * this instead of a regex so callers validate against the exact parser (5 fields,
 * valid numeric ranges) rather than a looser approximation.
 * @param {string} expr
 * @returns {boolean}
 */
function isValidCron(expr) {
  if (typeof expr !== 'string' || !expr.trim()) return false;
  // parseCronToNextRun throws / returns null on an unparseable or out-of-range
  // expression; wrap it into a boolean here so callers don't need try/catch.
  try {
    return Boolean(parseCronToNextRun(expr));
  } catch {
    return false;
  }
}

/** Non-throwing predicate for the richer calendar recurrence path. */
function isValidRecurrence(rule) {
  if (!recurrenceRuleSchema.safeParse(rule).success) return false
  try {
    return Boolean(parseRecurrenceToNextRun(rule))
  } catch {
    return false
  }
}

export {
  schedule,
  cancel,
  pause,
  resume,
  getScheduledEvents,
  getEvent,
  getHistory,
  getStats,
  cancelAll,
  quiesce,
  drain,
  triggerNow,
  parseCronToNextRun,
  parseCronToPrevRun,
  parseRecurrenceToNextRun,
  isValidCron,
  isValidRecurrence,
  MAX_TIMEOUT,
  BOOT_GRACE_MS
}