@johpaz/hive-sdk 0.1.6 → 0.3.0

package/packages/core/src/scheduler/CronScheduler.ts

@@ -1,16 +1,27 @@
 /**
  * Hive CronScheduler
  *
- * Croner-based scheduler for Hive with HiveDB persistence.
- * Manages recurring and one-shot cron jobs that execute through the agent pipeline.
+ * Manages recurring and one-shot cron jobs that execute through the agent pipeline,
+ * persisted in HiveDB.
+ *
+ * El motor de cron es propio (`./cron`), sin dependencias: sólo `setTimeout` e
+ * `Intl` del runtime. Antes era `croner`.
+ *
+ * `Bun.cron()` no sirve como reemplazo —se evaluó contra el runtime 1.4.0—:
+ * acepta sólo 5 campos y rechaza el sexto, no admite una fecha ISO como patrón
+ * (que es como se agendan los jobs `one_shot`), ignora la zona horaria, y su
+ * handle no expone la próxima corrida, que es de donde sale `next_run_at` y con
+ * lo que se detectan las corridas perdidas al arrancar. Tampoco tiene
+ * equivalente de `protect`, `maxRuns`, `interval`, `startAt`/`stopAt` ni
+ * `domAndDow`, todos campos persistidos de `CronJobDoc`.
  */
 
-import { Cron } from "croner";
-import { logger } from "../utils/logger";
-import { notifyTaskCompletion } from "./integration";
-import { col, toIndexable, fromIndexable } from "../storage/hive";
-import type { CronJobDoc, TaskRunDoc } from "../storage/collections";
-import { expireArtifacts } from "../artifacts/store";
+import { Cron } from "./cron/index.ts";
+import { logger } from "../utils/logger.ts";
+import { notifyTaskCompletion } from "./integration.ts";
+import { col, toIndexable, fromIndexable } from "../storage/hive.ts";
+import type { CronJobDoc, TaskRunDoc } from "../storage/collections.ts";
+import { expireArtifacts } from "../artifacts/store.ts";
 import type {
   CronJob,
   TaskRun,
@@ -18,7 +29,7 @@ import type {
   UpdateCronJobInput,
   CronJobStatus,
   CronJobExecutionHandler,
-} from "./types";
+} from "./types.ts";
 
 const log = logger.child("CronScheduler");
 
@@ -76,7 +87,7 @@ export class CronScheduler {
 
         if (misfirePolicy === "fire_once" && withinGrace) {
           log.info(`[boot:misfire] Job "${task.name}" (${task.id}) misfired at ${misfireTime.toISOString()} — executing now (fire_once, within grace)`);
-          // Activate the job first (so the Croner handle exists for future runs)
+          // Activate the job first (so it stays scheduled for future runs)
           await this.activate(task);
           // Then execute it immediately
           this.execute(task.id).catch((err) => {
@@ -100,7 +111,7 @@ export class CronScheduler {
           });
           await this.activate(task);
         } else {
-          // skip policy — recurring re-schedules its next occurrence via Croner
+          // skip policy — recurring re-schedules its next occurrence on its own
           log.info(`[boot:misfire] Job "${task.name}" (${task.id}) misfired at ${misfireTime.toISOString()} — skipping (misfire_policy=skip)`);
           await this.updateJob(task.id, {
             last_error: `Missed run at ${misfireTime.toISOString()} (policy: skip)`,
@@ -120,7 +131,7 @@ export class CronScheduler {
   }
 
   /**
-   * Activate a cron job - create or recreate its Croner instance
+   * Activate a cron job - create or recreate its scheduled instance
    */
   async activate(task: CronJob): Promise<void> {
     const existingJob = this.jobs.get(task.id);
@@ -218,13 +229,29 @@ export class CronScheduler {
     }
   }
 
-  /** Read-modify-write helper for cron_jobs partial updates, retrying on OCC conflict. */
-  private async updateJob(taskId: string, patch: Partial<CronJobDoc>): Promise<CronJobDoc | null> {
+  /**
+   * Read-modify-write helper for cron_jobs partial updates, retrying on OCC conflict.
+   *
+   * El parche puede ser una función, y para los contadores **tiene que serlo**:
+   * un objeto fijo se calcula una sola vez, fuera del bucle, así que al
+   * reintentar por conflicto de versión se vuelve a escribir el valor viejo y
+   * el incremento se pierde. Con dos ejecuciones solapadas del mismo job —algo
+   * normal en uno que tarda más que su intervalo y no declara `protect`— ambas
+   * leen `error_count: 4` y ambas escriben 5: el job nunca llega al umbral de
+   * auto-pausa y sigue fallando para siempre.
+   */
+  private async updateJob(
+    taskId: string,
+    patch: Partial<CronJobDoc> | ((actual: CronJobDoc) => Partial<CronJobDoc>),
+  ): Promise<CronJobDoc | null> {
     const cronJobsCol = await col<CronJobDoc>("cronJobs");
     for (let attempt = 0; attempt < 5; attempt++) {
       const existing = await cronJobsCol.get(taskId);
       if (!existing) return null;
-      const merged = { ...existing.doc, ...patch };
+      const merged = {
+        ...existing.doc,
+        ...(typeof patch === "function" ? patch(existing.doc) : patch),
+      };
       try {
         await cronJobsCol.put(taskId, merged, { expectedVersion: existing.version });
         return merged;
@@ -284,11 +311,11 @@ export class CronScheduler {
           agent_response: result.response?.slice(0, 1000) || null,
         });
 
-        const refreshed = await this.updateJob(task.id, {
-          run_count: task.run_count + 1,
+        const refreshed = await this.updateJob(task.id, (actual) => ({
+          run_count: actual.run_count + 1,
           last_run_at: finishedAt,
           last_error: null,
-        });
+        }));
 
         const job = this.jobs.get(task.id);
         if (job) {
@@ -322,10 +349,10 @@ export class CronScheduler {
         error_message: errorMessage,
       });
 
-      const updated = await this.updateJob(task.id, {
-        error_count: task.error_count + 1,
+      const updated = await this.updateJob(task.id, (actual) => ({
+        error_count: actual.error_count + 1,
         last_error: errorMessage,
-      });
+      }));
 
       log.error(`[execute] Job "${task.name}" (${task.id}) failed: ${errorMessage}`);
 
@@ -358,12 +385,12 @@ export class CronScheduler {
   }
 
   /**
-   * Handle errors from Croner
+   * Handle errors raised by the scheduled job
    */
   private handleError(task: CronJob, error: Error): void {
     log.error(`[error] Job "${task.name}" (${task.id}) error: ${error.message}`);
 
-    // Fix 3: record Croner-level errors in task_runs for full history
+    // Fix 3: record scheduler-level errors in task_runs for full history
     Promise.resolve().then(async () => {
       const runId = crypto.randomUUID().replace(/-/g, "").slice(0, 16);
       const now = new Date().toISOString();
@@ -384,10 +411,10 @@ export class CronScheduler {
         log.warn(`[handleError] Failed to insert task_run: ${(e as Error).message}`);
       }
 
-      await this.updateJob(task.id, {
-        error_count: task.error_count + 1,
+      await this.updateJob(task.id, (actual) => ({
+        error_count: actual.error_count + 1,
         last_error: error.message,
-      });
+      }));
     });
   }
 
@@ -431,7 +458,7 @@ export class CronScheduler {
   }
 
   /**
-   * Deactivate a cron job - stop Croner instance but keep in DB
+   * Deactivate a cron job - stop the scheduled instance but keep it in DB
    */
   deactivate(taskId: string): void {
     const job = this.jobs.get(taskId);

package/packages/core/src/scheduler/cron/expression.ts

@@ -0,0 +1,165 @@
+/**
+ * Parseo de expresiones cron.
+ *
+ * Acepta 5 campos (`min hora dom mes dow`) y 6 (con segundos adelante), que es
+ * lo que aceptaba croner y por lo tanto lo que puede haber guardado en
+ * `cronJobDoc.cron_expression` de instalaciones anteriores. `Bun.cron` sólo
+ * admite 5 y rechaza el sexto con un error, así que no sirve como reemplazo
+ * directo.
+ *
+ * Cada campo se expande a la lista ordenada de valores que casa. Expandir por
+ * adelantado —en vez de evaluar la expresión en cada comparación— hace que
+ * buscar la próxima corrida sea recorrer números, y es lo que permite saltar de
+ * un match al siguiente sin probar minuto por minuto.
+ */
+
+export interface CronFields {
+  second: number[]
+  minute: number[]
+  hour: number[]
+  dayOfMonth: number[]
+  /** 1-12. */
+  month: number[]
+  /** 0-6, 0 = domingo. */
+  dayOfWeek: number[]
+  /** `false` cuando el campo es `*`: no restringe qué días casan. */
+  domRestricted: boolean
+  dowRestricted: boolean
+  /** La expresión trae campo de segundos. */
+  hasSeconds: boolean
+}
+
+const MESES = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"]
+const DIAS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"]
+
+interface Rango {
+  min: number
+  max: number
+  nombre: string
+  /** Alias por nombre (ENE, LUN…), en minúsculas. */
+  nombres?: string[]
+}
+
+function traducirNombre(texto: string, rango: Rango): string {
+  if (!rango.nombres) return texto
+  const i = rango.nombres.indexOf(texto.toLowerCase())
+  return i >= 0 ? String(i + rango.min) : texto
+}
+
+function entero(texto: string, rango: Rango, expr: string): number {
+  const n = Number(texto)
+  if (!Number.isInteger(n)) {
+    throw new Error(`campo ${rango.nombre}: "${texto}" no es un número (en "${expr}")`)
+  }
+  return n
+}
+
+/** Expande un campo (`*`, `5`, `1-5`, `*​/2`, `1-9/3`, `a,b`) a sus valores. */
+function expandirCampo(campo: string, rango: Rango, expr: string): { valores: number[]; restringe: boolean } {
+  // `?` es sinónimo de `*` en los dialectos que lo traen; aceptarlo evita
+  // rechazar expresiones que en otro scheduler funcionaban.
+  const texto = campo.trim() === "?" ? "*" : campo.trim()
+  if (texto === "") throw new Error(`campo ${rango.nombre} vacío (en "${expr}")`)
+
+  const valores = new Set<number>()
+  let restringe = false
+
+  for (const parte of texto.split(",")) {
+    const [base, pasoTexto] = parte.split("/")
+    if (pasoTexto !== undefined && parte.split("/").length > 2) {
+      throw new Error(`campo ${rango.nombre}: "${parte}" tiene más de un "/" (en "${expr}")`)
+    }
+
+    const paso = pasoTexto === undefined ? 1 : entero(pasoTexto, rango, expr)
+    if (paso < 1) throw new Error(`campo ${rango.nombre}: el paso debe ser ≥ 1 (en "${expr}")`)
+
+    let desde: number
+    let hasta: number
+
+    if (base === "*" || base === "") {
+      desde = rango.min
+      hasta = rango.max
+    } else if (base.includes("-")) {
+      restringe = true
+      const [a, b] = base.split("-")
+      desde = entero(traducirNombre(a, rango), rango, expr)
+      hasta = entero(traducirNombre(b, rango), rango, expr)
+    } else {
+      restringe = true
+      desde = entero(traducirNombre(base, rango), rango, expr)
+      // `5/15` significa "desde 5, cada 15" — sin paso es un valor suelto.
+      hasta = pasoTexto === undefined ? desde : rango.max
+    }
+
+    for (const v of [desde, hasta]) {
+      if (v < rango.min || v > rango.max) {
+        throw new Error(
+          `campo ${rango.nombre}: ${v} fuera de rango ${rango.min}-${rango.max} (en "${expr}")`,
+        )
+      }
+    }
+
+    if (desde > hasta) {
+      // Un rango que da la vuelta (`22-4` en horas) se lee como las dos puntas.
+      for (let v = desde; v <= rango.max; v += paso) valores.add(v)
+      for (let v = rango.min; v <= hasta; v += paso) valores.add(v)
+    } else {
+      for (let v = desde; v <= hasta; v += paso) valores.add(v)
+    }
+  }
+
+  return { valores: [...valores].sort((a, b) => a - b), restringe }
+}
+
+/**
+ * Parsea la expresión. Lanza con un mensaje que dice **qué campo** falló y por
+ * qué: el mensaje va a parar a la respuesta de `cron.create`, así que lo lee el
+ * modelo —o la persona— que se equivocó al escribirla.
+ */
+export function parseCronExpression(expr: string): CronFields {
+  const campos = expr.trim().split(/\s+/)
+  if (campos.length !== 5 && campos.length !== 6) {
+    throw new Error(
+      `una expresión cron lleva 5 campos (min hora día mes día-semana) o 6 con segundos adelante; ` +
+        `"${expr}" tiene ${campos.length}`,
+    )
+  }
+
+  const hasSeconds = campos.length === 6
+  const [seg, min, hora, dom, mes, dow] = hasSeconds
+    ? campos
+    : ["0", ...campos]
+
+  const segundo = expandirCampo(seg, { min: 0, max: 59, nombre: "segundos" }, expr)
+  const minuto = expandirCampo(min, { min: 0, max: 59, nombre: "minutos" }, expr)
+  const horas = expandirCampo(hora, { min: 0, max: 23, nombre: "horas" }, expr)
+  const diaMes = expandirCampo(dom, { min: 1, max: 31, nombre: "día del mes" }, expr)
+  const meses = expandirCampo(mes, { min: 1, max: 12, nombre: "mes", nombres: MESES }, expr)
+  const diaSemana = expandirCampo(dow, { min: 0, max: 7, nombre: "día de la semana", nombres: DIAS }, expr)
+
+  // 7 y 0 son ambos domingo: se normaliza a 0 para que `0-7` no deje un valor
+  // que después no casa con ningún `getUTCDay()`.
+  const dowNormalizado = [...new Set(diaSemana.valores.map((d) => (d === 7 ? 0 : d)))].sort((a, b) => a - b)
+
+  return {
+    second: segundo.valores,
+    minute: minuto.valores,
+    hour: horas.valores,
+    dayOfMonth: diaMes.valores,
+    month: meses.valores,
+    dayOfWeek: dowNormalizado,
+    domRestricted: diaMes.restringe,
+    dowRestricted: diaSemana.restringe,
+    hasSeconds,
+  }
+}
+
+/** `true` si la expresión parsea. Para validar sin construir un job. */
+export function isValidCronExpression(expr: string): boolean {
+  try {
+    parseCronExpression(expr)
+    return true
+  } catch {
+    return false
+  }
+}

package/packages/core/src/scheduler/cron/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Motor de cron propio, sin dependencias: sólo el runtime de Bun.
+ *
+ * Reemplaza a `croner`. Ver `job.ts` para por qué tampoco se usa `Bun.cron()`.
+ */
+
+export { Cron, type CronOptions, type CronFunction } from "./job.ts"
+export { parseCronExpression, isValidCronExpression, type CronFields } from "./expression.ts"
+export { nextOccurrence, type NextOccurrenceOptions } from "./next-run.ts"
+export { toWallClock, toInstant, assertTimeZone, type WallClock } from "./zoned-time.ts"

package/packages/core/src/scheduler/cron/job.ts

@@ -0,0 +1,339 @@
+/**
+ * `Cron` — un job agendado, sin dependencias.
+ *
+ * Reemplaza a `croner` conservando la superficie que el SDK ya usaba
+ * (`nextRun`, `pause`, `resume`, `stop`, y las opciones `timezone`, `protect`,
+ * `catch`, `name`, `domAndDow`, `maxRuns`, `interval`, `startAt`, `stopAt`),
+ * porque esas opciones son campos persistidos de `CronJobDoc` y cambiarlas
+ * habría sido migrar la base para no ganar nada.
+ *
+ * No usa `Bun.cron()`: ese sólo acepta 5 campos, no admite una fecha ISO como
+ * patrón —que es como se agendan los jobs `one_shot`—, ignora la zona horaria y
+ * su handle no expone la próxima corrida, que es de donde sale `next_run_at` y
+ * con lo que el scheduler detecta las corridas perdidas al arrancar. Lo que sí
+ * se usa de Bun es el runtime pelado: `setTimeout` e `Intl`.
+ */
+
+import { parseCronExpression, type CronFields } from "./expression.ts"
+import { nextOccurrence } from "./next-run.ts"
+import { assertTimeZone } from "./zoned-time.ts"
+
+/**
+ * Tope de `setTimeout`.
+ *
+ * Un delay mayor a 2^31-1 ms desborda a 32 bits y el timer dispara **de
+ * inmediato**, no tarde. Un job anual programado de una sola vez correría al
+ * instante, y otra vez, y otra: es el error clásico de escribir un scheduler a
+ * mano. Los esperas largas se encadenan en tramos de ~24 días.
+ */
+const MAX_DELAY_MS = 2_147_483_647
+
+export type CronFunction = (job: Cron) => void | Promise<void>
+
+export interface CronOptions {
+  /** Zona IANA en la que se interpreta la expresión. Por defecto, UTC. */
+  timezone?: string
+  /** No arrancar una corrida si la anterior sigue en curso. */
+  protect?: boolean
+  /** Qué hacer si la función lanza. Una función la recibe; `true` la traga. */
+  catch?: boolean | ((error: Error, job: Cron) => void)
+  name?: string
+  /** Exigir que casen día del mes **y** día de semana, en vez de cualquiera. */
+  domAndDow?: boolean
+  /** Dejar de correr después de estas corridas. */
+  maxRuns?: number
+  /** Segundos mínimos entre el arranque de una corrida y la siguiente. */
+  interval?: number
+  /** No correr antes de esta fecha. */
+  startAt?: string | Date
+  /** No correr después de esta fecha. */
+  stopAt?: string | Date
+  /** Nace pausado. */
+  paused?: boolean
+}
+
+function aFecha(valor: string | Date | undefined, campo: string): Date | null {
+  if (valor === undefined || valor === null) return null
+  const d = valor instanceof Date ? valor : new Date(valor)
+  if (Number.isNaN(d.getTime())) throw new Error(`${campo} no es una fecha válida: "${String(valor)}"`)
+  return d
+}
+
+export class Cron {
+  /** El patrón tal como se recibió. */
+  readonly pattern: string
+  readonly name: string
+
+  private readonly fields: CronFields | null
+  /** Instante único, cuando el patrón es una fecha en vez de una expresión. */
+  private readonly fireAt: Date | null
+  private readonly fn: CronFunction | null
+  private readonly timeZone: string
+  private readonly protect: boolean
+  private readonly onError: boolean | ((error: Error, job: Cron) => void)
+  private readonly domAndDow: boolean
+  private readonly maxRuns: number | null
+  private readonly intervalMs: number
+  private readonly startAt: Date | null
+  private readonly stopAt: Date | null
+
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private paused: boolean
+  private detenido = false
+  private ocupado = false
+  private corridas = 0
+  private ultimoArranque: Date | null = null
+  /** La corrida para la que está armado el timer. */
+  private proxima: Date | null = null
+
+  constructor(pattern: string | Date, options?: CronOptions | null, fn?: CronFunction) {
+    const opts = options ?? {}
+
+    this.timeZone = opts.timezone || "UTC"
+    assertTimeZone(this.timeZone)
+
+    this.protect = opts.protect === true
+    this.onError = opts.catch ?? false
+    this.domAndDow = opts.domAndDow === true
+    this.maxRuns = opts.maxRuns ?? null
+    this.intervalMs = (opts.interval ?? 0) * 1000
+    this.startAt = aFecha(opts.startAt, "startAt")
+    this.stopAt = aFecha(opts.stopAt, "stopAt")
+    this.paused = opts.paused === true
+    this.fn = fn ?? null
+
+    // Una fecha —o una cadena que lo sea— agenda una sola corrida. Es como se
+    // agendan los jobs `one_shot`, que pasan su `fire_at` como patrón.
+    if (pattern instanceof Date || esFechaISO(pattern)) {
+      const cuando = aFecha(pattern, "el patrón")!
+      this.pattern = pattern instanceof Date ? pattern.toISOString() : pattern
+      this.fireAt = cuando
+      this.fields = null
+    } else {
+      this.pattern = pattern
+      this.fireAt = null
+      this.fields = parseCronExpression(pattern)
+    }
+
+    this.name = opts.name ?? this.pattern
+
+    // Sin función no hay nada que correr: `new Cron(expr)` es la forma de
+    // validar una expresión, y no debe dejar un timer suelto.
+    if (this.fn) this.armar()
+  }
+
+  /** La próxima corrida, o `null` si ya no queda ninguna. */
+  nextRun(from?: Date): Date | null {
+    if (this.detenido) return null
+    if (this.maxRuns !== null && this.corridas >= this.maxRuns) return null
+
+    const desde = from ?? new Date()
+    let candidata: Date | null
+
+    if (this.fireAt) {
+      candidata = this.fireAt.getTime() > desde.getTime() ? this.fireAt : null
+    } else {
+      candidata = nextOccurrence(this.fields!, desde, {
+        timeZone: this.timeZone,
+        domAndDow: this.domAndDow,
+      })
+    }
+    if (!candidata) return null
+
+    // `startAt` corre la primera corrida hacia adelante en vez de saltearla: un
+    // job con ventana de arranque futura debe correr cuando la ventana abre.
+    if (this.startAt && candidata.getTime() < this.startAt.getTime()) {
+      candidata = this.fireAt
+        ? this.fireAt
+        : nextOccurrence(this.fields!, new Date(this.startAt.getTime() - 1000), {
+            timeZone: this.timeZone,
+            domAndDow: this.domAndDow,
+          })
+      if (!candidata || candidata.getTime() < this.startAt.getTime()) return null
+    }
+
+    if (this.stopAt && candidata.getTime() > this.stopAt.getTime()) return null
+
+    // `interval` es un piso entre arranques: con `*/1 * * * *` e `interval: 300`
+    // el job corre cada cinco minutos, no cada uno.
+    if (this.intervalMs > 0 && this.ultimoArranque) {
+      const piso = this.ultimoArranque.getTime() + this.intervalMs
+      if (candidata.getTime() < piso) {
+        // El piso se redondea hacia arriba al segundo antes de buscar desde él.
+        // `nextOccurrence` trabaja en segundos enteros —descarta los
+        // milisegundos al leer el reloj de pared—, así que buscar desde un piso
+        // con milisegundos devuelve el segundo redondeado hacia ABAJO, que
+        // sigue siendo menor que el piso. Reintentar con el mismo valor recursa
+        // para siempre y cuelga el proceso sin un error que lo explique.
+        const pisoEnSegundos = Math.ceil(piso / 1000) * 1000
+        candidata = nextOccurrence(this.fields!, new Date(pisoEnSegundos - 1000), {
+          timeZone: this.timeZone,
+          domAndDow: this.domAndDow,
+        })
+        if (!candidata) return null
+        if (this.stopAt && candidata.getTime() > this.stopAt.getTime()) return null
+      }
+    }
+
+    return candidata
+  }
+
+  /** Las próximas `n` corridas. Útil para mostrar una agenda. */
+  nextRuns(n: number, from?: Date): Date[] {
+    const salida: Date[] = []
+    let cursor = from ?? new Date()
+    for (let i = 0; i < n; i++) {
+      const siguiente = this.nextRun(cursor)
+      if (!siguiente) break
+      salida.push(siguiente)
+      cursor = siguiente
+    }
+    return salida
+  }
+
+  /** Suspende las corridas sin perder el job. `true` si quedó pausado. */
+  pause(): boolean {
+    if (this.detenido) return false
+    this.paused = true
+    this.desarmar()
+    return true
+  }
+
+  /** Reanuda un job pausado. `true` si quedó corriendo. */
+  resume(): boolean {
+    if (this.detenido) return false
+    this.paused = false
+    if (this.fn) this.armar()
+    return true
+  }
+
+  /** Termina el job para siempre. No se puede reanudar. */
+  stop(): void {
+    this.detenido = true
+    this.paused = false
+    this.desarmar()
+  }
+
+  /** ¿Está agendado y sin pausar? */
+  isRunning(): boolean {
+    return !this.detenido && !this.paused && this.timer !== null
+  }
+
+  /** ¿Hay una corrida en curso ahora mismo? */
+  isBusy(): boolean {
+    return this.ocupado
+  }
+
+  /**
+   * Corre la función ahora mismo, fuera de agenda, sin tocar la programación.
+   *
+   * Es lo que hace la tool `cron.trigger` ("corré esto ya"). Ignora `protect` a
+   * propósito: quien dispara a mano está pidiendo una corrida, no sugiriéndola,
+   * y devolver silencio porque la anterior sigue en curso se ve como que el
+   * botón no funciona.
+   */
+  trigger(): void {
+    if (this.detenido) return
+    void (async () => {
+      this.ocupado = true
+      this.corridas++
+      this.ultimoArranque = new Date()
+      try {
+        await this.fn?.(this)
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err))
+        if (typeof this.onError === "function") this.onError(error, this)
+        else if (!this.onError) throw error
+      } finally {
+        this.ocupado = false
+      }
+    })()
+  }
+
+  /** Cuántas veces corrió. */
+  runCount(): number {
+    return this.corridas
+  }
+
+  /** Cuándo arrancó la última corrida. */
+  previousRun(): Date | null {
+    return this.ultimoArranque
+  }
+
+  // ── Interno ────────────────────────────────────────────────────────────────
+
+  private desarmar(): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+    this.proxima = null
+  }
+
+  private armar(): void {
+    this.desarmar()
+    if (this.detenido || this.paused) return
+
+    const siguiente = this.nextRun()
+    if (!siguiente) return
+
+    this.proxima = siguiente
+    this.programar()
+  }
+
+  /** Arma el timer, encadenando tramos cuando la espera excede el tope. */
+  private programar(): void {
+    if (!this.proxima) return
+    const falta = this.proxima.getTime() - Date.now()
+
+    if (falta > MAX_DELAY_MS) {
+      this.timer = setTimeout(() => this.programar(), MAX_DELAY_MS)
+      return
+    }
+
+    this.timer = setTimeout(() => {
+      this.timer = null
+      void this.disparar()
+    }, Math.max(0, falta))
+  }
+
+  private async disparar(): Promise<void> {
+    if (this.detenido || this.paused) return
+
+    // `protect` se comprueba acá y no al agendar: lo que importa es si la
+    // anterior sigue corriendo **ahora**, no si lo estaba cuando se armó.
+    // La corrida se saltea pero el job se re-agenda igual; si no, un job lento
+    // se apagaría solo al primer solapamiento.
+    if (this.protect && this.ocupado) {
+      this.armar()
+      return
+    }
+
+    this.ocupado = true
+    this.corridas++
+    this.ultimoArranque = new Date()
+
+    try {
+      await this.fn?.(this)
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err))
+      if (typeof this.onError === "function") this.onError(error, this)
+      else if (!this.onError) throw error
+    } finally {
+      this.ocupado = false
+      // Re-agendar va en el `finally`: si quedara después del `await` y la
+      // función lanzara con `catch: false`, el job dejaría de correr para
+      // siempre por un error de una sola corrida.
+      this.armar()
+    }
+  }
+}
+
+/** ¿Es una fecha ISO en vez de una expresión cron? */
+function esFechaISO(valor: string): boolean {
+  // Una expresión cron nunca lleva "-" en la primera posición ni ":" en ningún
+  // lado, así que alcanza con exigir la forma de fecha antes de intentar
+  // parsearla — `new Date("0 9 * * *")` en algunos runtimes no da NaN.
+  if (!/^\d{4}-\d{2}-\d{2}([T ]|$)/.test(valor.trim())) return false
+  return !Number.isNaN(new Date(valor).getTime())
+}