@stonyx/cron 0.2.1-beta.24 → 0.2.1-beta.25

package/package.json

@@ -3,7 +3,7 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.24",
+  "version": "0.2.1-beta.25",
   "description": "Cron/job scheduler for Stonyx framework",
   "main": "src/main.js",
   "type": "module",
@@ -12,6 +12,13 @@
   ],
   "exports": {
     ".": "./src/main.js",
+    "./service": "./src/service.js",
+    "./cron-parser": "./src/cron-parser.js",
+    "./schedule": "./src/schedule.js",
+    "./job": "./src/job.js",
+    "./normalize": "./src/normalize.js",
+    "./locked": "./src/locked.js",
+    "./run-log": "./src/run-log.js",
     "./min-heap": "./src/min-heap.js"
   },
   "publishConfig": {

package/src/cron-parser.js

@@ -0,0 +1,246 @@
+/**
+ * 5-field cron expression parser with next-occurrence computation.
+ * No external dependencies — built for stonyx-cron.
+ *
+ * Fields: minute(0-59) hour(0-23) day-of-month(1-31) month(1-12) day-of-week(0-6)
+ * Supports: wildcards(*), ranges(1-5), steps(* /5), lists(1,3,5), names(jan-dec, sun-sat)
+ */
+
+const MONTH_NAMES = { jan: 1, feb: 2, mar: 3, apr: 4, may: 5, jun: 6, jul: 7, aug: 8, sep: 9, oct: 10, nov: 11, dec: 12 };
+const DAY_NAMES = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
+
+const FIELD_RANGES = [
+  { min: 0, max: 59 },  // minute
+  { min: 0, max: 23 },  // hour
+  { min: 1, max: 31 },  // day of month
+  { min: 1, max: 12 },  // month
+  { min: 0, max: 6 },   // day of week
+];
+
+/**
+ * Parse a single cron field into a sorted array of allowed values.
+ * @param {string} field - The field string (e.g., "1-5", "* /15", "mon,wed,fri")
+ * @param {number} fieldIndex - Index (0=minute, 1=hour, 2=dom, 3=month, 4=dow)
+ * @returns {number[]} Sorted array of allowed integer values
+ */
+export function parseField(field, fieldIndex) {
+  const { min, max } = FIELD_RANGES[fieldIndex];
+  const names = fieldIndex === 3 ? MONTH_NAMES : fieldIndex === 4 ? DAY_NAMES : null;
+
+  const resolveToken = (token) => {
+    if (names) {
+      const lower = token.toLowerCase();
+      if (lower in names) return names[lower];
+    }
+    const n = Number(token);
+    if (!Number.isInteger(n)) throw new Error(`Invalid cron value: "${token}" in field ${fieldIndex}`);
+    // Normalize day-of-week 7 → 0 (both mean Sunday)
+    if (fieldIndex === 4 && n === 7) return 0;
+    return n;
+  };
+
+  const results = new Set();
+
+  for (const part of field.split(',')) {
+    const trimmed = part.trim();
+    const [rangeStr, stepStr] = trimmed.split('/');
+    const step = stepStr !== undefined ? Number(stepStr) : 1;
+
+    if (!Number.isInteger(step) || step < 1) {
+      throw new Error(`Invalid step "${stepStr}" in cron field ${fieldIndex}`);
+    }
+
+    let start, end;
+
+    if (rangeStr === '*') {
+      start = min;
+      end = max;
+    } else if (rangeStr.includes('-')) {
+      const [lo, hi] = rangeStr.split('-');
+      start = resolveToken(lo);
+      end = resolveToken(hi);
+    } else {
+      start = resolveToken(rangeStr);
+      end = stepStr !== undefined ? max : start;
+    }
+
+    if (start < min || start > max || end < min || end > max) {
+      throw new Error(`Value out of range [${min}-${max}] in cron field ${fieldIndex}: "${trimmed}"`);
+    }
+
+    for (let v = start; v <= end; v += step) {
+      results.add(v);
+    }
+  }
+
+  return [...results].sort((a, b) => a - b);
+}
+
+/**
+ * Parse a 5-field cron expression into field arrays.
+ * @param {string} expr - Cron expression (e.g., "0 9 * * 1-5")
+ * @returns {{ minutes: number[], hours: number[], daysOfMonth: number[], months: number[], daysOfWeek: number[] }}
+ */
+export function parseCronExpression(expr) {
+  const fields = expr.trim().split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error(`Cron expression must have exactly 5 fields, got ${fields.length}: "${expr}"`);
+  }
+
+  return {
+    minutes: parseField(fields[0], 0),
+    hours: parseField(fields[1], 1),
+    daysOfMonth: parseField(fields[2], 2),
+    months: parseField(fields[3], 3),
+    daysOfWeek: parseField(fields[4], 4),
+  };
+}
+
+/**
+ * Get the number of days in a given month/year.
+ */
+function daysInMonth(year, month) {
+  return new Date(year, month, 0).getDate();
+}
+
+/**
+ * Check if a day-of-month + day-of-week pair matches the parsed expression.
+ *
+ * Standard cron behavior: if BOTH dom and dow are restricted (not *),
+ * then EITHER matching is sufficient (OR logic).
+ * If only one is restricted, it acts as the sole filter.
+ */
+function dayMatches(parsed, domWild, dowWild, dayOfMonth, dayOfWeek) {
+  const domMatch = parsed.daysOfMonth.includes(dayOfMonth);
+  const dowMatch = parsed.daysOfWeek.includes(dayOfWeek);
+
+  if (domWild && dowWild) return true;
+  if (domWild) return dowMatch;
+  if (dowWild) return domMatch;
+  return domMatch || dowMatch; // Both restricted → OR
+}
+
+/**
+ * Compute the next occurrence of a cron expression after a given timestamp.
+ *
+ * @param {string} expr - 5-field cron expression
+ * @param {number} afterMs - Timestamp in milliseconds (exclusive — finds strictly after this)
+ * @param {string} [tz] - IANA timezone (defaults to system timezone)
+ * @returns {number|undefined} Next occurrence in milliseconds, or undefined if none within 4 years
+ */
+export function nextOccurrence(expr, afterMs, tz) {
+  const parsed = parseCronExpression(expr);
+  const exprFields = expr.trim().split(/\s+/);
+  const domWild = exprFields[2] === '*';
+  const dowWild = exprFields[4] === '*';
+
+  // Start from the next whole minute after afterMs
+  const startDate = new Date(afterMs);
+  startDate.setSeconds(0, 0);
+  startDate.setMinutes(startDate.getMinutes() + 1);
+
+  // Convert to target timezone for field matching
+  const formatter = new Intl.DateTimeFormat('en-US', {
+    timeZone: tz || undefined,
+    year: 'numeric', month: 'numeric', day: 'numeric',
+    hour: 'numeric', minute: 'numeric', hour12: false,
+    weekday: 'short',
+  });
+
+  const dayMap = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+
+  // Parse formatted date parts in the target timezone
+  function getLocalParts(date) {
+    const parts = {};
+    for (const { type, value } of formatter.formatToParts(date)) {
+      parts[type] = value;
+    }
+    return {
+      year: Number(parts.year),
+      month: Number(parts.month),
+      day: Number(parts.day),
+      hour: Number(parts.hour === '24' ? 0 : parts.hour),
+      minute: Number(parts.minute),
+      weekday: dayMap[parts.weekday] ?? 0,
+    };
+  }
+
+  // Search limit: 4 years of minutes (≈ 2.1M iterations max)
+  const maxMs = afterMs + 4 * 365.25 * 24 * 60 * 60 * 1000;
+  let candidate = new Date(startDate);
+
+  while (candidate.getTime() <= maxMs) {
+    const p = getLocalParts(candidate);
+
+    // Check month
+    if (!parsed.months.includes(p.month)) {
+      // Advance to next matching month
+      const nextMonth = parsed.months.find(m => m > p.month);
+      if (nextMonth) {
+        // Stay in same year, advance to first day of nextMonth
+        candidate = advanceToMonth(candidate, p.year, nextMonth, tz, formatter, dayMap);
+      } else {
+        // Wrap to next year, first matching month
+        candidate = advanceToMonth(candidate, p.year + 1, parsed.months[0], tz, formatter, dayMap);
+      }
+      continue;
+    }
+
+    // Check day (dom + dow)
+    if (!dayMatches(parsed, domWild, dowWild, p.day, p.weekday)) {
+      candidate.setMinutes(candidate.getMinutes() + (24 * 60 - p.hour * 60 - p.minute));
+      continue;
+    }
+
+    // Check hour
+    if (!parsed.hours.includes(p.hour)) {
+      const nextHour = parsed.hours.find(h => h > p.hour);
+      if (nextHour) {
+        candidate.setMinutes(candidate.getMinutes() + ((nextHour - p.hour) * 60 - p.minute));
+      } else {
+        // Advance to next day
+        candidate.setMinutes(candidate.getMinutes() + ((24 - p.hour) * 60 - p.minute));
+      }
+      continue;
+    }
+
+    // Check minute
+    if (!parsed.minutes.includes(p.minute)) {
+      const nextMin = parsed.minutes.find(m => m > p.minute);
+      if (nextMin) {
+        candidate.setMinutes(candidate.getMinutes() + (nextMin - p.minute));
+      } else {
+        // Advance to next hour
+        candidate.setMinutes(candidate.getMinutes() + (60 - p.minute));
+      }
+      continue;
+    }
+
+    // All fields match
+    return candidate.getTime();
+  }
+
+  return undefined;
+}
+
+/**
+ * Create a Date advanced to the start of a specific month in a specific year,
+ * using the target timezone's midnight.
+ */
+function advanceToMonth(current, year, month, tz, formatter, dayMap) {
+  // Create a new date at ~start of the target month in UTC, then adjust
+  const d = new Date(current);
+  // Jump to approximately the right time
+  d.setFullYear(year, month - 1, 1);
+  d.setHours(0, 0, 0, 0);
+  return d;
+}
+
+/**
+ * Validate a cron expression without computing next occurrence.
+ * @param {string} expr - 5-field cron expression
+ * @throws {Error} if the expression is invalid
+ */
+export function validateCronExpression(expr) {
+  parseCronExpression(expr);
+}

package/src/job.js

@@ -0,0 +1,200 @@
+/**
+ * Job data model and state machine for the advanced scheduling system.
+ */
+import { computeNextRunAtMs, validateSchedule } from './schedule.js';
+
+/**
+ * Error backoff table (milliseconds).
+ * Applied after consecutive errors to prevent hammering.
+ */
+const ERROR_BACKOFF_MS = [30_000, 60_000, 300_000, 900_000, 3_600_000];
+
+export function errorBackoffMs(consecutiveErrors) {
+  if (consecutiveErrors < 1) return 0;
+  return ERROR_BACKOFF_MS[Math.min(consecutiveErrors - 1, ERROR_BACKOFF_MS.length - 1)];
+}
+
+/**
+ * Create a new job object from input.
+ *
+ * @param {object} input - Job creation input
+ * @param {string} input.name - Job name
+ * @param {object} input.schedule - Schedule definition (at/every/cron)
+ * @param {object} input.payload - What to execute
+ * @param {string} [input.description]
+ * @param {boolean} [input.enabled=true]
+ * @param {boolean} [input.deleteAfterRun=false]
+ * @param {string} [input.sessionTarget="isolated"]
+ * @param {string} [input.wakeMode="now"]
+ * @param {object} [input.delivery]
+ * @returns {object} Complete job object with state
+ */
+export function createJob(input) {
+  validateSchedule(input.schedule);
+
+  const nowMs = Date.now();
+  const enabled = input.enabled !== false;
+  const deleteAfterRun = input.deleteAfterRun ?? (input.schedule.kind === 'at');
+
+  const job = {
+    id: crypto.randomUUID(),
+    name: input.name,
+    description: input.description || undefined,
+    enabled,
+    deleteAfterRun,
+    createdAtMs: nowMs,
+    updatedAtMs: nowMs,
+    schedule: { ...input.schedule },
+    sessionTarget: input.sessionTarget || 'isolated',
+    wakeMode: input.wakeMode || 'now',
+    payload: { ...input.payload },
+    delivery: input.delivery ? { ...input.delivery } : undefined,
+    state: {
+      nextRunAtMs: undefined,
+      runningAtMs: undefined,
+      lastRunAtMs: undefined,
+      lastStatus: undefined,
+      lastError: undefined,
+      lastDurationMs: undefined,
+      consecutiveErrors: 0,
+      scheduleErrorCount: 0,
+    },
+  };
+
+  // Compute initial next run
+  if (enabled) {
+    try {
+      job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
+    } catch {
+      job.state.scheduleErrorCount = 1;
+    }
+  }
+
+  return job;
+}
+
+/**
+ * Apply an update patch to a job.
+ *
+ * @param {object} job - Existing job
+ * @param {object} patch - Fields to update
+ * @returns {object} Updated job (same reference, mutated)
+ */
+export function updateJob(job, patch) {
+  const nowMs = Date.now();
+
+  if (patch.name !== undefined) job.name = patch.name;
+  if (patch.description !== undefined) job.description = patch.description || undefined;
+  if (patch.deleteAfterRun !== undefined) job.deleteAfterRun = patch.deleteAfterRun;
+  if (patch.sessionTarget !== undefined) job.sessionTarget = patch.sessionTarget;
+  if (patch.wakeMode !== undefined) job.wakeMode = patch.wakeMode;
+  if (patch.payload !== undefined) job.payload = { ...patch.payload };
+  if (patch.delivery !== undefined) job.delivery = patch.delivery ? { ...patch.delivery } : undefined;
+
+  if (patch.schedule !== undefined) {
+    validateSchedule(patch.schedule);
+    job.schedule = { ...patch.schedule };
+    job.state.scheduleErrorCount = 0;
+    // Recompute next run
+    if (job.enabled) {
+      try {
+        job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
+      } catch {
+        job.state.scheduleErrorCount = 1;
+      }
+    }
+  }
+
+  if (patch.enabled !== undefined) {
+    job.enabled = patch.enabled;
+    if (job.enabled && !job.state.nextRunAtMs) {
+      try {
+        job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
+      } catch {
+        job.state.scheduleErrorCount++;
+      }
+    }
+    if (!job.enabled) {
+      job.state.nextRunAtMs = undefined;
+    }
+  }
+
+  job.updatedAtMs = nowMs;
+  return job;
+}
+
+/**
+ * Mark a job as started (running).
+ */
+export function markRunning(job) {
+  job.state.runningAtMs = Date.now();
+}
+
+/**
+ * Apply the result of a job execution.
+ *
+ * @param {object} job - The job
+ * @param {"ok"|"error"|"skipped"} status - Execution result
+ * @param {string} [error] - Error message if status is "error"
+ * @param {number} [durationMs] - Execution duration
+ */
+export function applyResult(job, status, error, durationMs) {
+  const nowMs = Date.now();
+
+  job.state.lastRunAtMs = job.state.runningAtMs || nowMs;
+  job.state.runningAtMs = undefined;
+  job.state.lastStatus = status;
+  job.state.lastError = status === 'error' ? error : undefined;
+  job.state.lastDurationMs = durationMs;
+
+  if (status === 'error') {
+    job.state.consecutiveErrors = (job.state.consecutiveErrors || 0) + 1;
+  } else {
+    job.state.consecutiveErrors = 0;
+  }
+
+  // One-shot jobs: disable after any terminal status
+  if (job.schedule.kind === 'at') {
+    job.enabled = false;
+    job.state.nextRunAtMs = undefined;
+    return;
+  }
+
+  // Recurring jobs: compute next run with backoff
+  if (job.enabled) {
+    try {
+      const normalNext = computeNextRunAtMs(job.schedule, nowMs);
+      if (normalNext === undefined) {
+        job.enabled = false;
+        job.state.nextRunAtMs = undefined;
+        return;
+      }
+
+      if (status === 'error' && job.state.consecutiveErrors > 0) {
+        const backoff = errorBackoffMs(job.state.consecutiveErrors);
+        job.state.nextRunAtMs = Math.max(normalNext, nowMs + backoff);
+      } else {
+        job.state.nextRunAtMs = normalNext;
+      }
+
+      job.state.scheduleErrorCount = 0;
+    } catch {
+      job.state.scheduleErrorCount = (job.state.scheduleErrorCount || 0) + 1;
+      // Auto-disable after 3 consecutive schedule computation errors
+      if (job.state.scheduleErrorCount >= 3) {
+        job.enabled = false;
+        job.state.nextRunAtMs = undefined;
+      }
+    }
+  }
+}
+
+/**
+ * Check if a job is due to run.
+ */
+export function isDue(job, nowMs) {
+  return job.enabled
+    && !job.state.runningAtMs
+    && job.state.nextRunAtMs !== undefined
+    && job.state.nextRunAtMs <= nowMs;
+}

package/src/locked.js

@@ -0,0 +1,34 @@
+/**
+ * Async locking mechanism to serialize state mutations.
+ * Prevents concurrent operations from corrupting job state.
+ */
+
+let chain = Promise.resolve();
+
+/**
+ * Execute a function with exclusive access to cron state.
+ * Operations queue behind each other — no concurrent mutations.
+ *
+ * @param {Function} fn - Async function to execute under lock
+ * @returns {Promise<*>} Result of fn
+ */
+export async function locked(fn) {
+  let resolve;
+  const prev = chain;
+  chain = new Promise(r => { resolve = r; });
+
+  await prev;
+
+  try {
+    return await fn();
+  } finally {
+    resolve();
+  }
+}
+
+/**
+ * Reset the lock chain. Only for testing.
+ */
+export function resetLock() {
+  chain = Promise.resolve();
+}

package/src/normalize.js

@@ -0,0 +1,163 @@
+/**
+ * Input normalization for AI-generated job definitions.
+ * Handles imperfect JSON from AI models: wrong casing, missing fields,
+ * flat-param recovery, type coercion.
+ */
+
+/**
+ * Normalize a schedule object. Infers kind from fields if missing.
+ */
+export function normalizeSchedule(raw) {
+  if (!raw || typeof raw !== 'object') return raw;
+
+  const schedule = { ...raw };
+
+  // Infer kind from fields if missing
+  if (!schedule.kind) {
+    if (schedule.at || schedule.atMs) schedule.kind = 'at';
+    else if (schedule.everyMs) schedule.kind = 'every';
+    else if (schedule.expr) schedule.kind = 'cron';
+  }
+
+  // Case normalization
+  if (typeof schedule.kind === 'string') {
+    schedule.kind = schedule.kind.toLowerCase();
+  }
+
+  // Legacy: atMs (number) → at (ISO string)
+  if (schedule.atMs && !schedule.at) {
+    schedule.at = new Date(schedule.atMs).toISOString();
+    delete schedule.atMs;
+  }
+
+  // Coerce string everyMs to number
+  if (typeof schedule.everyMs === 'string') {
+    schedule.everyMs = Number(schedule.everyMs);
+  }
+
+  return schedule;
+}
+
+/**
+ * Normalize a payload object. Infers kind from fields if missing.
+ */
+export function normalizePayload(raw) {
+  if (!raw || typeof raw !== 'object') return raw;
+
+  const payload = { ...raw };
+
+  // Infer kind from fields
+  if (!payload.kind) {
+    if (payload.message) payload.kind = 'agentTurn';
+    else if (payload.text) payload.kind = 'systemEvent';
+  }
+
+  // Case normalization
+  if (typeof payload.kind === 'string') {
+    const lower = payload.kind.toLowerCase();
+    if (lower === 'agentturn') payload.kind = 'agentTurn';
+    else if (lower === 'systemevent') payload.kind = 'systemEvent';
+  }
+
+  return payload;
+}
+
+/**
+ * Recover a job object from flat parameters.
+ * AI models sometimes flatten nested fields to the top level.
+ */
+const JOB_KEYS = new Set([
+  'name', 'description', 'schedule', 'sessionTarget', 'payload',
+  'delivery', 'enabled', 'deleteAfterRun', 'wakeMode',
+]);
+
+export function recoverFlatParams(params) {
+  if (params.job && typeof params.job === 'object' && Object.keys(params.job).length > 0) {
+    return params.job;
+  }
+
+  const synthetic = {};
+  for (const key of Object.keys(params)) {
+    if (JOB_KEYS.has(key)) {
+      synthetic[key] = params[key];
+    }
+  }
+
+  // message/text are not JOB_KEYS but need to be recovered for payload wrapping
+  const message = params.message;
+  const text = params.text;
+
+  if (synthetic.schedule || synthetic.payload || message || text) {
+    // If message/text are at top level, wrap into payload
+    if (!synthetic.payload) {
+      if (message) {
+        synthetic.payload = { kind: 'agentTurn', message };
+      } else if (text) {
+        synthetic.payload = { kind: 'systemEvent', text };
+      }
+    }
+    return synthetic;
+  }
+
+  return params;
+}
+
+/**
+ * Normalize a complete job input for creation.
+ * Applies all normalization: schedule, payload, defaults.
+ */
+export function normalizeJobInput(raw) {
+  const job = { ...raw };
+
+  if (job.schedule) {
+    job.schedule = normalizeSchedule(job.schedule);
+  }
+
+  if (job.payload) {
+    job.payload = normalizePayload(job.payload);
+  }
+
+  // Default: enabled
+  if (job.enabled === undefined) job.enabled = true;
+
+  // Default: wakeMode
+  if (!job.wakeMode) job.wakeMode = 'now';
+
+  // Default: sessionTarget inferred from payload
+  if (!job.sessionTarget && job.payload) {
+    job.sessionTarget = job.payload.kind === 'systemEvent' ? 'main' : 'isolated';
+  }
+
+  // Default: deleteAfterRun for one-shot
+  if (job.deleteAfterRun === undefined && job.schedule?.kind === 'at') {
+    job.deleteAfterRun = true;
+  }
+
+  // Default: delivery for isolated agentTurn
+  if (!job.delivery && job.sessionTarget === 'isolated' && job.payload?.kind === 'agentTurn') {
+    job.delivery = { mode: 'announce' };
+  }
+
+  // Auto-generate name if missing
+  if (!job.name) {
+    job.name = inferName(job);
+  }
+
+  return job;
+}
+
+/**
+ * Infer a job name from schedule and payload.
+ */
+function inferName(job) {
+  const parts = [];
+
+  if (job.schedule?.kind === 'at') parts.push('One-shot');
+  else if (job.schedule?.kind === 'every') parts.push('Recurring');
+  else if (job.schedule?.kind === 'cron') parts.push('Scheduled');
+
+  if (job.payload?.kind === 'agentTurn') parts.push('agent task');
+  else if (job.payload?.kind === 'systemEvent') parts.push('system event');
+
+  return parts.join(' ') || 'Unnamed job';
+}

package/src/run-log.js

@@ -0,0 +1,79 @@
+/**
+ * In-memory run log for job execution history.
+ * Stores recent execution results per job with auto-pruning.
+ *
+ * Persistence (via ORM) is added in PR 2.
+ */
+
+const DEFAULT_MAX_ENTRIES_PER_JOB = 100;
+
+export default class RunLog {
+  constructor(maxEntriesPerJob = DEFAULT_MAX_ENTRIES_PER_JOB) {
+    this.maxEntries = maxEntriesPerJob;
+    this.entries = new Map(); // jobId → RunLogEntry[]
+  }
+
+  /**
+   * Record a job execution result.
+   *
+   * @param {object} entry
+   * @param {string} entry.jobId
+   * @param {"ok"|"error"|"skipped"} entry.status
+   * @param {string} [entry.error]
+   * @param {string} [entry.summary]
+   * @param {number} [entry.runAtMs]
+   * @param {number} [entry.durationMs]
+   * @param {number} [entry.nextRunAtMs]
+   */
+  record(entry) {
+    const log = {
+      ts: Date.now(),
+      jobId: entry.jobId,
+      status: entry.status,
+      error: entry.error,
+      summary: entry.summary,
+      runAtMs: entry.runAtMs,
+      durationMs: entry.durationMs,
+      nextRunAtMs: entry.nextRunAtMs,
+    };
+
+    if (!this.entries.has(entry.jobId)) {
+      this.entries.set(entry.jobId, []);
+    }
+
+    const logs = this.entries.get(entry.jobId);
+    logs.push(log);
+
+    // Auto-prune
+    if (logs.length > this.maxEntries) {
+      logs.splice(0, logs.length - this.maxEntries);
+    }
+  }
+
+  /**
+   * Get run history for a job.
+   *
+   * @param {string} jobId
+   * @param {number} [limit=20]
+   * @returns {object[]} Most recent entries, newest first
+   */
+  get(jobId, limit = 20) {
+    const logs = this.entries.get(jobId);
+    if (!logs) return [];
+    return logs.slice(-limit).reverse();
+  }
+
+  /**
+   * Remove all entries for a job.
+   */
+  removeJob(jobId) {
+    this.entries.delete(jobId);
+  }
+
+  /**
+   * Clear all entries.
+   */
+  clear() {
+    this.entries.clear();
+  }
+}

package/src/schedule.js

@@ -0,0 +1,81 @@
+/**
+ * Schedule types and next-run computation.
+ *
+ * Three schedule kinds:
+ *   - "at": One-shot at an absolute ISO-8601 timestamp
+ *   - "every": Recurring interval in milliseconds
+ *   - "cron": 5-field cron expression with optional timezone
+ */
+import { nextOccurrence, validateCronExpression } from './cron-parser.js';
+
+/**
+ * Compute the next run time for a schedule.
+ *
+ * @param {object} schedule - Schedule definition
+ * @param {string} schedule.kind - "at" | "every" | "cron"
+ * @param {number} nowMs - Current time in milliseconds
+ * @returns {number|undefined} Next run time in ms, or undefined if no future occurrence
+ */
+export function computeNextRunAtMs(schedule, nowMs) {
+  if (schedule.kind === 'at') {
+    const atMs = typeof schedule.at === 'number' ? schedule.at : Date.parse(schedule.at);
+    if (!Number.isFinite(atMs)) return undefined;
+    return atMs > nowMs ? atMs : undefined;
+  }
+
+  if (schedule.kind === 'every') {
+    const everyMs = Math.max(1, Math.floor(schedule.everyMs));
+    const anchor = Math.max(0, Math.floor(schedule.anchorMs ?? nowMs));
+
+    if (nowMs < anchor) return anchor;
+
+    const elapsed = nowMs - anchor;
+    const steps = Math.max(1, Math.floor((elapsed + everyMs - 1) / everyMs));
+    return anchor + steps * everyMs;
+  }
+
+  if (schedule.kind === 'cron') {
+    const tz = schedule.tz?.trim() || undefined;
+    // Round nowMs down to the current second to avoid sub-second drift
+    const nowSecondMs = Math.floor(nowMs / 1000) * 1000;
+    return nextOccurrence(schedule.expr.trim(), nowSecondMs, tz);
+  }
+
+  throw new Error(`Unknown schedule kind: "${schedule.kind}"`);
+}
+
+/**
+ * Validate a schedule definition.
+ * @param {object} schedule
+ * @throws {Error} if the schedule is invalid
+ */
+export function validateSchedule(schedule) {
+  if (!schedule || typeof schedule !== 'object') {
+    throw new Error('Schedule must be an object');
+  }
+
+  if (schedule.kind === 'at') {
+    const atMs = typeof schedule.at === 'number' ? schedule.at : Date.parse(schedule.at);
+    if (!Number.isFinite(atMs)) {
+      throw new Error(`Invalid "at" timestamp: "${schedule.at}"`);
+    }
+    return;
+  }
+
+  if (schedule.kind === 'every') {
+    if (typeof schedule.everyMs !== 'number' || schedule.everyMs < 1) {
+      throw new Error(`"every" schedule requires everyMs >= 1, got: ${schedule.everyMs}`);
+    }
+    return;
+  }
+
+  if (schedule.kind === 'cron') {
+    if (typeof schedule.expr !== 'string' || !schedule.expr.trim()) {
+      throw new Error('"cron" schedule requires a non-empty expr string');
+    }
+    validateCronExpression(schedule.expr.trim());
+    return;
+  }
+
+  throw new Error(`Unknown schedule kind: "${schedule.kind}"`);
+}

package/src/service.js

@@ -0,0 +1,303 @@
+/**
+ * CronService — the main API for advanced job scheduling.
+ *
+ * Manages jobs in memory with a min-heap for efficient next-job lookup.
+ * Supports pluggable store interface (memory-only by default, ORM in PR 2).
+ * All state mutations are serialized via async locking.
+ */
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import MinHeap from './min-heap.js';
+import { createJob, updateJob, markRunning, applyResult, isDue } from './job.js';
+import { computeNextRunAtMs } from './schedule.js';
+import { locked } from './locked.js';
+import { normalizeJobInput, recoverFlatParams } from './normalize.js';
+import RunLog from './run-log.js';
+
+const MAX_TIMER_DELAY_MS = 60_000;
+
+export default class CronService {
+  constructor() {
+    this.jobs = new Map();       // id → job
+    this.heap = new MinHeap();   // ordered by nextRunAtMs
+    this.timer = null;
+    this.running = false;
+    this.runLog = new RunLog();
+    this.started = false;
+
+    // Pluggable callbacks for consumers
+    this.onJobDue = null;        // async (job) => { status, error?, summary? }
+  }
+
+  // ── Lifecycle ──────────────────────────────────────────────
+
+  /**
+   * Start the service. Loads jobs from store (if any), arms timer.
+   */
+  async start(initialJobs) {
+    if (this.started) return;
+    this.started = true;
+
+    if (initialJobs) {
+      for (const job of initialJobs) {
+        this.jobs.set(job.id, job);
+        if (job.enabled && job.state.nextRunAtMs) {
+          this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
+        }
+      }
+    }
+
+    this.armTimer();
+  }
+
+  /**
+   * Stop the service. Clears timer.
+   */
+  stop() {
+    this.started = false;
+    clearTimeout(this.timer);
+    this.timer = null;
+  }
+
+  // ── CRUD ───────────────────────────────────────────────────
+
+  /**
+   * Get service status.
+   */
+  status() {
+    const peek = this.heap.peek();
+    return {
+      started: this.started,
+      jobCount: this.jobs.size,
+      nextWakeAtMs: peek ? peek.nextTrigger : undefined,
+    };
+  }
+
+  /**
+   * List jobs, optionally including disabled ones.
+   */
+  list(opts) {
+    const includeDisabled = opts?.includeDisabled ?? false;
+    const jobs = [...this.jobs.values()];
+    const filtered = includeDisabled ? jobs : jobs.filter(j => j.enabled);
+    return filtered.sort((a, b) => (a.state.nextRunAtMs ?? Infinity) - (b.state.nextRunAtMs ?? Infinity));
+  }
+
+  /**
+   * Get a single job by ID.
+   */
+  get(id) {
+    return this.jobs.get(id) || null;
+  }
+
+  /**
+   * Add a new job. Input is normalized for AI compatibility.
+   */
+  async add(rawInput) {
+    return locked(() => {
+      const input = normalizeJobInput(recoverFlatParams(rawInput));
+      const job = createJob(input);
+      this.jobs.set(job.id, job);
+
+      if (job.enabled && job.state.nextRunAtMs) {
+        this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
+        this.armTimer();
+      }
+
+      return job;
+    });
+  }
+
+  /**
+   * Update an existing job.
+   */
+  async update(id, patch) {
+    return locked(() => {
+      const job = this.jobs.get(id);
+      if (!job) throw new Error(`Job not found: ${id}`);
+
+      const oldNextRun = job.state.nextRunAtMs;
+      updateJob(job, patch);
+
+      // Update heap entry
+      this.removeFromHeap(id);
+      if (job.enabled && job.state.nextRunAtMs) {
+        this.heap.push({ key: id, nextTrigger: job.state.nextRunAtMs });
+      }
+
+      if (job.state.nextRunAtMs !== oldNextRun) {
+        this.armTimer();
+      }
+
+      return job;
+    });
+  }
+
+  /**
+   * Remove a job.
+   */
+  async remove(id) {
+    return locked(() => {
+      const job = this.jobs.get(id);
+      if (!job) throw new Error(`Job not found: ${id}`);
+
+      this.jobs.delete(id);
+      this.removeFromHeap(id);
+      this.runLog.removeJob(id);
+      this.armTimer();
+    });
+  }
+
+  /**
+   * Manually trigger a job.
+   *
+   * @param {string} id - Job ID
+   * @param {"due"|"force"} [mode="force"] - "due" only runs if the job is due, "force" runs regardless
+   */
+  async run(id, mode = 'force') {
+    const job = this.jobs.get(id);
+    if (!job) throw new Error(`Job not found: ${id}`);
+
+    if (mode === 'due' && !isDue(job, Date.now())) {
+      return { status: 'skipped', reason: 'not due' };
+    }
+
+    return this.executeJob(job);
+  }
+
+  /**
+   * Get run history for a job.
+   */
+  runs(id, limit) {
+    return this.runLog.get(id, limit);
+  }
+
+  // ── Timer Engine ──────────────────────────────────────��────
+
+  armTimer() {
+    clearTimeout(this.timer);
+    if (!this.started) return;
+
+    const peek = this.heap.peek();
+    if (!peek) return;
+
+    const delay = Math.min(Math.max(peek.nextTrigger - Date.now(), 0), MAX_TIMER_DELAY_MS);
+    this.timer = setTimeout(() => this.onTimer(), delay);
+  }
+
+  async onTimer() {
+    if (this.running) {
+      // Already processing — re-arm at max delay to prevent scheduler death
+      this.timer = setTimeout(() => this.onTimer(), MAX_TIMER_DELAY_MS);
+      return;
+    }
+
+    this.running = true;
+
+    try {
+      await locked(async () => {
+        const nowMs = Date.now();
+        const dueJobs = this.findDueJobs(nowMs);
+
+        for (const job of dueJobs) {
+          markRunning(job);
+        }
+
+        for (const job of dueJobs) {
+          await this.executeJob(job);
+        }
+      });
+    } finally {
+      this.running = false;
+      this.armTimer();
+    }
+  }
+
+  findDueJobs(nowMs) {
+    const due = [];
+
+    while (!this.heap.isEmpty()) {
+      const peek = this.heap.peek();
+      if (peek.nextTrigger > nowMs) break;
+
+      this.heap.pop();
+      const job = this.jobs.get(peek.key);
+      if (job && isDue(job, nowMs)) {
+        due.push(job);
+      }
+    }
+
+    return due;
+  }
+
+  async executeJob(job) {
+    const startMs = Date.now();
+    let status = 'ok';
+    let error;
+    let summary;
+
+    try {
+      if (this.onJobDue) {
+        const result = await this.onJobDue(job);
+        if (result) {
+          status = result.status || 'ok';
+          error = result.error;
+          summary = result.summary;
+        }
+      }
+    } catch (err) {
+      status = 'error';
+      error = err?.message || String(err);
+      this.log(`Job "${job.name}" (${job.id}) failed: ${error}`);
+    }
+
+    const durationMs = Date.now() - startMs;
+
+    applyResult(job, status, error, durationMs);
+
+    // Log the run
+    this.runLog.record({
+      jobId: job.id,
+      status,
+      error,
+      summary,
+      runAtMs: startMs,
+      durationMs,
+      nextRunAtMs: job.state.nextRunAtMs,
+    });
+
+    // Handle one-shot auto-delete
+    if (job.deleteAfterRun && status === 'ok' && !job.enabled) {
+      this.jobs.delete(job.id);
+      this.runLog.removeJob(job.id);
+      return { status, summary, deleted: true };
+    }
+
+    // Re-insert into heap if still active
+    if (job.enabled && job.state.nextRunAtMs) {
+      this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
+    }
+
+    return { status, error, summary, durationMs };
+  }
+
+  // ── Helpers ────────────────────────────────────────────────
+
+  removeFromHeap(id) {
+    // MinHeap doesn't support remove-by-key efficiently,
+    // so we rebuild. Fine for typical job counts (< 1000).
+    const remaining = [];
+    while (!this.heap.isEmpty()) {
+      const item = this.heap.pop();
+      if (item.key !== id) remaining.push(item);
+    }
+    for (const item of remaining) {
+      this.heap.push(item);
+    }
+  }
+
+  log(message) {
+    if (!config.cron?.log) return;
+    log.cron(`Cron — ${message}`);
+  }
+}