@johpaz/hive-sdk 0.2.0 → 0.3.0

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())
+}

package/packages/core/src/scheduler/cron/next-run.ts

@@ -0,0 +1,121 @@
+/**
+ * Próxima corrida de una expresión cron, en la zona horaria del job.
+ *
+ * La búsqueda avanza **día por día** en el reloj de pared de la zona y, dentro
+ * del día que casa, recorre las horas/minutos/segundos que casan. Podría
+ * hacerse aritmética de campos con acarreo y sería algo más rápido, pero acá
+ * cada job calcula esto una vez por corrida: la claridad vale más que los
+ * microsegundos, y el acarreo es justo donde se esconden los errores de fin de
+ * mes y de año bisiesto.
+ *
+ * Avanzar el día con `Date.UTC(y, m-1, d+1)` es deliberado: deja que el runtime
+ * resuelva el largo de cada mes y los bisiestos, así que un 31 de febrero nunca
+ * llega a probarse.
+ */
+
+import type { CronFields } from "./expression.ts"
+import { toInstant, toWallClock, wallClockWeekday, type WallClock } from "./zoned-time.ts"
+
+/**
+ * Tope de la búsqueda.
+ *
+ * Hay expresiones válidas que no ocurren nunca: `0 0 30 2 *` —30 de febrero—
+ * parsea bien y no casa jamás. Sin tope, buscarle la próxima corrida cuelga el
+ * proceso. Cinco años cubre de sobra cualquier expresión que sí ocurra, incluida
+ * la del 29 de febrero, que puede tardar hasta ocho.
+ */
+const MAX_DIAS = 366 * 8
+
+/** ¿Casa el día (mes + día del mes/semana) según la semántica de `domAndDow`? */
+function diaCasa(fields: CronFields, wall: WallClock, domAndDow: boolean): boolean {
+  if (!fields.month.includes(wall.month)) return false
+
+  const porMes = fields.dayOfMonth.includes(wall.day)
+  const porSemana = fields.dayOfWeek.includes(wallClockWeekday(wall))
+
+  // Ninguno de los dos restringe (`* *`): casa cualquier día.
+  if (!fields.domRestricted && !fields.dowRestricted) return true
+
+  // Los dos restringen: es el caso raro del cron clásico, donde por defecto la
+  // lógica es O y no Y — `0 9 15 * 1` es "los 15 **o** los lunes". `domAndDow`
+  // existe para pedir la otra.
+  if (fields.domRestricted && fields.dowRestricted) {
+    return domAndDow ? porMes && porSemana : porMes || porSemana
+  }
+
+  return fields.domRestricted ? porMes : porSemana
+}
+
+/** Las horas del día que casan, de la más temprana a la más tarde, desde un piso. */
+function* horasDelDia(
+  fields: CronFields,
+  piso: { hour: number; minute: number; second: number } | null,
+): Generator<{ hour: number; minute: number; second: number }> {
+  for (const hour of fields.hour) {
+    if (piso && hour < piso.hour) continue
+    for (const minute of fields.minute) {
+      if (piso && hour === piso.hour && minute < piso.minute) continue
+      for (const second of fields.second) {
+        if (piso && hour === piso.hour && minute === piso.minute && second < piso.second) continue
+        yield { hour, minute, second }
+      }
+    }
+  }
+}
+
+/** El día siguiente en el calendario, a las 00:00:00. */
+function diaSiguiente(wall: WallClock): WallClock {
+  const d = new Date(Date.UTC(wall.year, wall.month - 1, wall.day + 1))
+  return {
+    year: d.getUTCFullYear(),
+    month: d.getUTCMonth() + 1,
+    day: d.getUTCDate(),
+    hour: 0,
+    minute: 0,
+    second: 0,
+  }
+}
+
+export interface NextOccurrenceOptions {
+  timeZone: string
+  domAndDow?: boolean
+}
+
+/**
+ * La próxima vez que la expresión casa, **estrictamente después** de `from`.
+ * `null` si no ocurre dentro del horizonte de búsqueda.
+ */
+export function nextOccurrence(
+  fields: CronFields,
+  from: Date,
+  opts: NextOccurrenceOptions,
+): Date | null {
+  const { timeZone, domAndDow = false } = opts
+
+  // Un segundo después: sin esto, pedirle la próxima corrida a un job justo
+  // cuando acaba de correr devolvería el mismo instante y el scheduler se
+  // reprogramaría con demora cero, en bucle.
+  let cursor = toWallClock(new Date(from.getTime() + 1000), timeZone)
+  let piso: { hour: number; minute: number; second: number } | null = {
+    hour: cursor.hour,
+    minute: cursor.minute,
+    second: cursor.second,
+  }
+
+  for (let dia = 0; dia < MAX_DIAS; dia++) {
+    if (diaCasa(fields, cursor, domAndDow)) {
+      for (const hora of horasDelDia(fields, piso)) {
+        const instante = toInstant({ ...cursor, ...hora }, timeZone)
+        // `null` = esa hora no existe hoy en esta zona porque el reloj saltó
+        // hacia adelante. Se prueba la siguiente que casa en vez de inventar un
+        // instante: correr "a las 2:30" el día que 2:30 no existió sería correr
+        // a una hora que nadie agendó.
+        if (instante) return instante
+      }
+    }
+    cursor = diaSiguiente(cursor)
+    piso = null
+  }
+
+  return null
+}