@ap3x/cadence 0.1.0

package/dist/index.js

@@ -0,0 +1,867 @@
+// src/core/backoff.ts
+function backoffMs(attempt, baseMs, capMs) {
+  const a = Number.isFinite(attempt) ? Math.max(1, Math.floor(attempt)) : 1;
+  const base = Number.isFinite(baseMs) ? Math.max(0, baseMs) : 0;
+  const cap = Number.isFinite(capMs) ? Math.max(0, capMs) : Number.POSITIVE_INFINITY;
+  const grown = base * 2 ** (a - 1);
+  return Math.min(grown, cap);
+}
+function applyJitter(ms, jitterMs, seed) {
+  if (!Number.isFinite(jitterMs) || jitterMs <= 0) return ms;
+  let h = (Number.isFinite(seed) ? Math.floor(seed) : 0) | 0;
+  h = Math.imul(h ^ h >>> 16, 73244475);
+  h = Math.imul(h ^ h >>> 16, 73244475);
+  h = (h ^ h >>> 16) >>> 0;
+  const offset = Math.floor(h / 4294967296 * (jitterMs + 1));
+  return ms + offset;
+}
+
+// src/core/clock.ts
+var SystemClock = class {
+  #nowFn;
+  constructor(nowFn) {
+    this.#nowFn = nowFn;
+  }
+  now() {
+    return this.#nowFn();
+  }
+  sleep(ms, signal) {
+    if (signal?.aborted) return Promise.resolve();
+    return new Promise((resolve) => {
+      const onAbort = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+      }, ms);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+};
+var TestClock = class {
+  #nowMs;
+  #pending = [];
+  constructor(startIso) {
+    this.#nowMs = new Date(startIso).getTime();
+  }
+  now() {
+    return new Date(this.#nowMs);
+  }
+  /** Move time forward by `ms`, resolving any sleeps whose deadline passed. */
+  advance(ms) {
+    this.#nowMs += ms;
+    this.#flush();
+  }
+  /** Jump to an absolute instant, resolving any sleeps whose deadline passed. */
+  setNow(iso) {
+    this.#nowMs = new Date(iso).getTime();
+    this.#flush();
+  }
+  sleep(ms, signal) {
+    if (signal?.aborted) return Promise.resolve();
+    return new Promise((resolve) => {
+      const entry = { deadline: this.#nowMs + ms, resolve };
+      this.#pending.push(entry);
+      signal?.addEventListener(
+        "abort",
+        () => {
+          const i = this.#pending.indexOf(entry);
+          if (i !== -1) this.#pending.splice(i, 1);
+          resolve();
+        },
+        { once: true }
+      );
+    });
+  }
+  #flush() {
+    const due = this.#pending.filter((p) => p.deadline <= this.#nowMs).sort((a, b) => a.deadline - b.deadline);
+    this.#pending = this.#pending.filter((p) => p.deadline > this.#nowMs);
+    for (const p of due) p.resolve();
+  }
+};
+
+// src/core/engine.ts
+import { Value } from "@sinclair/typebox/value";
+
+// src/core/next-run.ts
+import parser from "cron-parser";
+var REFERENCE = /* @__PURE__ */ new Date(0);
+function computeNextRun(s, after) {
+  switch (s.kind) {
+    case "cron": {
+      try {
+        const it = parser.parseExpression(s.expr, { currentDate: after, tz: s.timezone });
+        if (!it.hasNext()) return null;
+        return it.next().toDate();
+      } catch {
+        return null;
+      }
+    }
+    case "interval": {
+      const ms = parseIsoDuration(s.expr);
+      if (ms === null || ms <= 0) return null;
+      return new Date(after.getTime() + ms);
+    }
+    case "one_shot": {
+      const at = new Date(s.expr);
+      if (Number.isNaN(at.getTime())) return null;
+      return at.getTime() > after.getTime() ? at : null;
+    }
+    default:
+      return null;
+  }
+}
+function validateSchedule(input, opts = {}) {
+  const { minCadenceMs } = opts;
+  switch (input.kind) {
+    case "cron": {
+      let fires;
+      try {
+        const it = parser.parseExpression(input.expr, {
+          currentDate: REFERENCE,
+          tz: input.timezone ?? "UTC"
+        });
+        fires = [];
+        for (let i = 0; i < 5 && it.hasNext(); i++) fires.push(it.next().toDate());
+      } catch (err) {
+        return { ok: false, error: `invalid cron expression: ${errMsg(err)}` };
+      }
+      if (fires.length === 0) {
+        return { ok: false, error: "cron expression never fires" };
+      }
+      if (minCadenceMs != null) {
+        const gap = tightestGapMs(fires);
+        if (gap != null && gap < minCadenceMs) {
+          return {
+            ok: false,
+            error: `cron cadence ${gap}ms is below the floor of ${minCadenceMs}ms`
+          };
+        }
+      }
+      return { ok: true };
+    }
+    case "interval": {
+      const ms = parseIsoDuration(input.expr);
+      if (ms === null || ms <= 0) {
+        return { ok: false, error: `invalid interval duration: ${input.expr}` };
+      }
+      if (minCadenceMs != null && ms < minCadenceMs) {
+        return {
+          ok: false,
+          error: `interval cadence ${ms}ms is below the floor of ${minCadenceMs}ms`
+        };
+      }
+      return { ok: true };
+    }
+    case "one_shot": {
+      const at = new Date(input.expr);
+      if (Number.isNaN(at.getTime())) {
+        return { ok: false, error: `invalid one_shot instant: ${input.expr}` };
+      }
+      return { ok: true };
+    }
+    default:
+      return { ok: false, error: `unknown schedule kind: ${String(input.kind)}` };
+  }
+}
+function tightestGapMs(fires) {
+  if (fires.length < 2) return null;
+  let min = Number.POSITIVE_INFINITY;
+  for (let i = 1; i < fires.length; i++) {
+    const gap = fires[i].getTime() - fires[i - 1].getTime();
+    if (gap < min) min = gap;
+  }
+  return min;
+}
+var ISO_DURATION = /^P(?:(\d+(?:\.\d+)?)W)?(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?)?$/;
+function parseIsoDuration(expr) {
+  const m = ISO_DURATION.exec(expr);
+  if (!m) return null;
+  const [, w, d, h, min, s] = m;
+  if (!w && !d && !h && !min && !s) return null;
+  const weeks = w ? Number(w) : 0;
+  const days = d ? Number(d) : 0;
+  const hours = h ? Number(h) : 0;
+  const minutes = min ? Number(min) : 0;
+  const seconds = s ? Number(s) : 0;
+  return weeks * 7 * 864e5 + days * 864e5 + hours * 36e5 + minutes * 6e4 + seconds * 1e3;
+}
+function errMsg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/core/types.ts
+import { Type } from "@sinclair/typebox";
+var ScheduleKind = {
+  Cron: "cron",
+  Interval: "interval",
+  OneShot: "one_shot"
+};
+var ScheduleKindSchema = Type.Union([
+  Type.Literal(ScheduleKind.Cron),
+  Type.Literal(ScheduleKind.Interval),
+  Type.Literal(ScheduleKind.OneShot)
+]);
+var OverlapPolicySchema = Type.Union([
+  Type.Literal("allow"),
+  Type.Literal("skip_if_running"),
+  Type.Literal("queue")
+]);
+var MisfirePolicySchema = Type.Union([
+  Type.Literal("fire"),
+  Type.Literal("skip"),
+  Type.Literal("backfill")
+]);
+var AttemptStatusSchema = Type.Union([
+  Type.Literal("running"),
+  Type.Literal("succeeded"),
+  Type.Literal("failed"),
+  Type.Literal("pending"),
+  Type.Literal("dead_letter")
+]);
+var MetadataSchema = Type.Record(Type.String(), Type.Unknown());
+var ScheduleSchema = Type.Object({
+  id: Type.String(),
+  name: Type.Optional(Type.String()),
+  kind: ScheduleKindSchema,
+  expr: Type.String(),
+  timezone: Type.String(),
+  payload: Type.Unknown(),
+  enabled: Type.Boolean(),
+  overlap: OverlapPolicySchema,
+  misfire: MisfirePolicySchema,
+  maxAttempts: Type.Number(),
+  maxRuntimeMs: Type.Optional(Type.Number()),
+  jitterMs: Type.Optional(Type.Number()),
+  validFrom: Type.Optional(Type.String()),
+  validUntil: Type.Optional(Type.String()),
+  maxOccurrences: Type.Optional(Type.Number()),
+  occurrenceCount: Type.Number(),
+  nextRunAt: Type.Union([Type.String(), Type.Null()]),
+  lastTriggeredAt: Type.Optional(Type.String()),
+  createdAt: Type.String(),
+  metadata: Type.Optional(MetadataSchema)
+});
+var AttemptSchema = Type.Object({
+  id: Type.String(),
+  scheduleId: Type.String(),
+  occurrenceAt: Type.String(),
+  attempt: Type.Number(),
+  status: AttemptStatusSchema,
+  startedAt: Type.Optional(Type.String()),
+  finishedAt: Type.Optional(Type.String()),
+  retryAt: Type.Optional(Type.String()),
+  error: Type.Optional(Type.String()),
+  outcome: Type.Optional(Type.Unknown())
+});
+var NewScheduleSchema = Type.Object({
+  name: Type.Optional(Type.String()),
+  kind: ScheduleKindSchema,
+  expr: Type.String(),
+  timezone: Type.Optional(Type.String()),
+  payload: Type.Unknown(),
+  overlap: Type.Optional(OverlapPolicySchema),
+  misfire: Type.Optional(MisfirePolicySchema),
+  maxAttempts: Type.Optional(Type.Number()),
+  maxRuntimeMs: Type.Optional(Type.Number()),
+  jitterMs: Type.Optional(Type.Number()),
+  validFrom: Type.Optional(Type.String()),
+  validUntil: Type.Optional(Type.String()),
+  maxOccurrences: Type.Optional(Type.Number()),
+  enabled: Type.Optional(Type.Boolean()),
+  metadata: Type.Optional(MetadataSchema)
+});
+
+// src/core/engine.ts
+var Engine = class {
+  #store;
+  #executor;
+  #clock;
+  #pollIntervalMs;
+  #batchLimit;
+  #orphanGraceMs;
+  #retryBaseMs;
+  #retryCapMs;
+  #idFactory;
+  #running = false;
+  #loopCtl = null;
+  #loopDone = Promise.resolve();
+  /** In-flight fire/retry tasks; drained by stop(). */
+  #inflight = /* @__PURE__ */ new Set();
+  /** Attempt ids this instance is executing right now (orphan-reclaim exemption). */
+  #inflightAttemptIds = /* @__PURE__ */ new Set();
+  constructor(opts) {
+    this.#store = opts.store;
+    this.#executor = opts.executor;
+    this.#clock = opts.clock;
+    this.#pollIntervalMs = opts.pollIntervalMs ?? 1e3;
+    this.#batchLimit = opts.batchLimit ?? 25;
+    this.#orphanGraceMs = opts.orphanGraceMs ?? 3e5;
+    this.#retryBaseMs = opts.retryBaseMs ?? 1e3;
+    this.#retryCapMs = opts.retryCapMs ?? 6e4;
+    this.#idFactory = opts.idFactory ?? defaultIdFactory();
+  }
+  // -- registration & passthroughs ----------------------------------------
+  /**
+   * Validate (TypeBox shape + kind-specific expression check), fill server-side
+   * fields, compute the initial slot, and persist. Throws on invalid input.
+   */
+  async register(input) {
+    if (!Value.Check(NewScheduleSchema, input)) {
+      throw new Error("invalid schedule input: does not match NewScheduleSchema");
+    }
+    const valid = validateSchedule(input);
+    if (!valid.ok) throw new Error(valid.error);
+    const now = this.#clock.now();
+    const s = {
+      ...input,
+      id: this.#idFactory(),
+      timezone: input.timezone ?? "UTC",
+      enabled: input.enabled ?? true,
+      overlap: input.overlap ?? "allow",
+      misfire: input.misfire ?? "fire",
+      maxAttempts: input.maxAttempts ?? 3,
+      occurrenceCount: 0,
+      createdAt: now.toISOString(),
+      nextRunAt: null
+    };
+    const from = s.validFrom !== void 0 && new Date(s.validFrom).getTime() > now.getTime() ? new Date(s.validFrom) : now;
+    s.nextRunAt = this.#boundedNext(s, from, 0);
+    await this.#store.createSchedule(s);
+    return s;
+  }
+  remove(id) {
+    return this.#store.removeSchedule(id);
+  }
+  setEnabled(id, enabled) {
+    return this.#store.setEnabled(id, enabled);
+  }
+  get(id) {
+    return this.#store.getSchedule(id);
+  }
+  list() {
+    return this.#store.listSchedules();
+  }
+  /** Attempt history for one schedule, newest first — "did it actually run?". */
+  listAttempts(scheduleId, limit = 50) {
+    return this.#store.listAttempts(scheduleId, limit);
+  }
+  /** Occurrences that exhausted the retry ladder: the permanent-failure record. */
+  deadLetteredFor(scheduleId) {
+    return this.#store.deadLetteredFor(scheduleId);
+  }
+  // -- lifecycle -----------------------------------------------------------
+  /** Begin the poll loop. Idempotent: a second start while running is a no-op. */
+  start() {
+    if (this.#running) return;
+    this.#running = true;
+    this.#loopCtl = new AbortController();
+    this.#loopDone = this.#loop(this.#loopCtl.signal);
+  }
+  /**
+   * Drain: stop claiming, let in-flight attempts run to completion (bounded by
+   * their own maxRuntimeMs timeouts), then resolve. Idempotent.
+   */
+  async stop() {
+    if (this.#running) {
+      this.#running = false;
+      this.#loopCtl?.abort();
+    }
+    await this.#loopDone;
+    while (this.#inflight.size > 0) {
+      await Promise.allSettled([...this.#inflight]);
+    }
+  }
+  async #loop(signal) {
+    while (!signal.aborted) {
+      await this.#tick();
+      if (signal.aborted) break;
+      await this.#clock.sleep(this.#pollIntervalMs, signal);
+    }
+  }
+  // -- tick ----------------------------------------------------------------
+  async #tick() {
+    const now = this.#clock.now();
+    await this.#recoverOrphans(now);
+    await this.#runDueRetries(now);
+    const claimed = await this.#store.claimDue(now, this.#batchLimit);
+    for (const c of claimed) await this.#dispatch(c, now);
+  }
+  /** Crashed-worker recovery: route stale "running" attempts to the retry ladder. */
+  async #recoverOrphans(now) {
+    const orphans = await this.#store.reclaimOrphans(now, this.#orphanGraceMs);
+    for (const a of orphans) {
+      if (this.#inflightAttemptIds.has(a.id)) continue;
+      const s = await this.#store.getSchedule(a.scheduleId);
+      if (s !== void 0 && a.attempt < s.maxAttempts) {
+        await this.#store.updateAttempt(a.id, {
+          status: "pending",
+          retryAt: this.#retryAt(s, a.occurrenceAt, now, a.attempt),
+          error: "orphaned: worker crashed or stalled"
+        });
+      } else {
+        await this.#store.updateAttempt(a.id, {
+          status: "dead_letter",
+          finishedAt: now.toISOString(),
+          error: "orphaned: worker crashed or stalled"
+        });
+      }
+    }
+  }
+  /** Re-execute pending attempts whose retryAt has come due. */
+  async #runDueRetries(now) {
+    const due = await this.#store.listDueRetries(now, this.#batchLimit);
+    for (const a of due) {
+      const s = await this.#store.getSchedule(a.scheduleId);
+      if (s === void 0) {
+        await this.#store.updateAttempt(a.id, {
+          status: "dead_letter",
+          finishedAt: now.toISOString(),
+          error: "schedule removed"
+        });
+        continue;
+      }
+      const attemptNo = a.attempt + 1;
+      await this.#store.updateAttempt(a.id, {
+        status: "running",
+        attempt: attemptNo,
+        startedAt: now.toISOString()
+      });
+      this.#track(this.#execute(s, a.id, a.occurrenceAt, attemptNo));
+    }
+  }
+  /** Apply misfire + overlap policies to one claimed occurrence, advance its slot. */
+  async #dispatch(c, now) {
+    const s = c.schedule;
+    const occ = new Date(c.occurrenceAt);
+    const nextAfterOcc = computeNextRun(s, occ);
+    const misfired = nextAfterOcc !== null && nextAfterOcc.getTime() <= now.getTime();
+    let toFire;
+    if (!misfired || s.misfire === "fire") {
+      toFire = [c.occurrenceAt];
+    } else if (s.misfire === "skip") {
+      toFire = [];
+    } else {
+      toFire = [c.occurrenceAt];
+      let cur = occ;
+      while (true) {
+        cur = computeNextRun(s, cur);
+        if (cur === null || cur.getTime() > now.getTime()) break;
+        toFire.push(cur.toISOString());
+      }
+    }
+    if (s.maxOccurrences !== void 0) {
+      toFire = toFire.slice(0, Math.max(0, s.maxOccurrences - s.occurrenceCount));
+    }
+    if (toFire.length > 0 && s.overlap === "queue" && await this.#store.hasActiveAttempt(s.id)) {
+      await this.#store.advanceSlot(
+        s.id,
+        c.occurrenceAt,
+        s.lastTriggeredAt ?? s.createdAt,
+        s.occurrenceCount
+      );
+      return;
+    }
+    const skipped = toFire.length > 0 && s.overlap === "skip_if_running" && await this.#store.hasActiveAttempt(s.id);
+    const firedCount = skipped ? 0 : toFire.length;
+    const countAfter = s.occurrenceCount + firedCount;
+    let anchor;
+    if (!misfired) {
+      anchor = occ;
+    } else if (s.misfire === "backfill" && firedCount > 0) {
+      anchor = new Date(toFire[toFire.length - 1]);
+    } else {
+      anchor = now;
+    }
+    const nextRunAt = this.#boundedNext(s, anchor, countAfter);
+    const lastTriggeredAt = firedCount > 0 ? now.toISOString() : s.lastTriggeredAt ?? s.createdAt;
+    await this.#store.advanceSlot(s.id, nextRunAt, lastTriggeredAt, countAfter);
+    if (skipped) {
+      await this.#store.openAttempt({
+        id: this.#idFactory(),
+        scheduleId: s.id,
+        occurrenceAt: c.occurrenceAt,
+        attempt: 0,
+        status: "failed",
+        finishedAt: now.toISOString(),
+        error: "skipped: overlap policy skip_if_running"
+      });
+      return;
+    }
+    if (toFire.length === 0) return;
+    this.#track(this.#fire(s, toFire));
+  }
+  // -- execution -----------------------------------------------------------
+  /** Fire the given occurrences of one schedule, in order, honoring jitter. */
+  async #fire(s, occurrences) {
+    for (const occurrenceAt of occurrences) {
+      if (s.jitterMs !== void 0 && s.jitterMs > 0) {
+        const delay = applyJitter(0, s.jitterMs, hashSeed(`${s.id}@${occurrenceAt}`));
+        if (delay > 0) await this.#clock.sleep(delay, this.#loopCtl?.signal);
+      }
+      const now = this.#clock.now();
+      const attemptId = this.#idFactory();
+      await this.#store.openAttempt({
+        id: attemptId,
+        scheduleId: s.id,
+        occurrenceAt,
+        attempt: 1,
+        status: "running",
+        startedAt: now.toISOString()
+      });
+      await this.#execute(s, attemptId, occurrenceAt, 1);
+    }
+  }
+  /** One attempt: executor call under a timeout signal, then the retry ladder. */
+  async #execute(s, attemptId, occurrenceAt, attemptNo) {
+    this.#inflightAttemptIds.add(attemptId);
+    const ac = new AbortController();
+    const timeoutCtl = new AbortController();
+    if (s.maxRuntimeMs !== void 0 && s.maxRuntimeMs > 0) {
+      void this.#clock.sleep(s.maxRuntimeMs, timeoutCtl.signal).then(() => {
+        if (!timeoutCtl.signal.aborted) ac.abort();
+      });
+    }
+    let outcome;
+    try {
+      outcome = await this.#executor.execute({
+        schedule: s,
+        occurrenceAt,
+        attempt: attemptNo,
+        signal: ac.signal
+      });
+    } catch (err) {
+      outcome = { ok: false, error: err instanceof Error ? err.message : String(err) };
+    } finally {
+      timeoutCtl.abort();
+      this.#inflightAttemptIds.delete(attemptId);
+    }
+    const now = this.#clock.now();
+    if (outcome.ok) {
+      await this.#store.updateAttempt(attemptId, {
+        status: "succeeded",
+        finishedAt: now.toISOString(),
+        ...outcome.result !== void 0 ? { outcome: outcome.result } : {}
+      });
+    } else if (attemptNo < s.maxAttempts) {
+      await this.#store.updateAttempt(attemptId, {
+        status: "pending",
+        retryAt: this.#retryAt(s, occurrenceAt, now, attemptNo),
+        ...outcome.error !== void 0 ? { error: outcome.error } : {}
+      });
+    } else {
+      await this.#store.updateAttempt(attemptId, {
+        status: "dead_letter",
+        finishedAt: now.toISOString(),
+        ...outcome.error !== void 0 ? { error: outcome.error } : {}
+      });
+    }
+  }
+  // -- helpers ---------------------------------------------------------------
+  /**
+   * Next slot strictly after `anchor`, or null when the schedule terminates:
+   * maxOccurrences reached, validUntil passed, or no further occurrence exists.
+   */
+  #boundedNext(s, anchor, countAfter) {
+    if (s.maxOccurrences !== void 0 && countAfter >= s.maxOccurrences) return null;
+    const next = computeNextRun(s, anchor);
+    if (next === null) return null;
+    if (s.validUntil !== void 0 && next.getTime() > new Date(s.validUntil).getTime()) {
+      return null;
+    }
+    return next.toISOString();
+  }
+  /**
+   * Backoff, jittered per (schedule, occurrence, attempt). Without the jitter,
+   * N schedules that fail together retry at the identical instant, take the
+   * identical rate-limit rejection, and march the whole ladder in lockstep to a
+   * mass dead-letter. Deterministic seed — no RNG, no wall clock.
+   */
+  #retryAt(s, occurrenceAt, now, attemptNo) {
+    const base = backoffMs(attemptNo, this.#retryBaseMs, this.#retryCapMs);
+    const spread = s.jitterMs ?? 0;
+    const delay = spread > 0 ? applyJitter(base, spread, hashSeed(`${s.id}@${occurrenceAt}@${attemptNo}`)) : base;
+    return new Date(now.getTime() + delay).toISOString();
+  }
+  #track(task) {
+    const wrapped = task.catch(() => {
+    });
+    this.#inflight.add(wrapped);
+    void wrapped.finally(() => this.#inflight.delete(wrapped));
+  }
+};
+function defaultIdFactory() {
+  let n = 0;
+  return () => `cad_${++n}`;
+}
+function hashSeed(input) {
+  let h = 5381;
+  for (let i = 0; i < input.length; i++) {
+    h = Math.imul(h, 33) + input.charCodeAt(i) | 0;
+  }
+  return h;
+}
+
+// src/core/memory-store.ts
+var InMemoryStore = class {
+  #clock;
+  #schedules = /* @__PURE__ */ new Map();
+  /** Attempts in insertion order; `listAttempts` returns them newest-first. */
+  #attempts = [];
+  /** Schedule ids whose due slot is claimed pending `advanceSlot`. */
+  #claimed = /* @__PURE__ */ new Set();
+  constructor(clock) {
+    this.#clock = clock;
+  }
+  async createSchedule(s) {
+    this.#schedules.set(s.id, { ...s });
+  }
+  async getSchedule(id) {
+    const s = this.#schedules.get(id);
+    return s ? { ...s } : void 0;
+  }
+  async listSchedules() {
+    return [...this.#schedules.values()].map((s) => ({ ...s }));
+  }
+  async removeSchedule(id) {
+    this.#claimed.delete(id);
+    return this.#schedules.delete(id);
+  }
+  async setEnabled(id, enabled) {
+    const s = this.#schedules.get(id);
+    if (s) s.enabled = enabled;
+  }
+  async claimDue(now, limit) {
+    const nowMs = now.getTime();
+    const out = [];
+    for (const s of this.#schedules.values()) {
+      if (out.length >= limit) break;
+      if (!s.enabled || s.nextRunAt === null) continue;
+      if (this.#claimed.has(s.id)) continue;
+      if (new Date(s.nextRunAt).getTime() > nowMs) continue;
+      this.#claimed.add(s.id);
+      out.push({ schedule: { ...s }, occurrenceAt: s.nextRunAt });
+    }
+    return out;
+  }
+  async advanceSlot(id, nextRunAt, lastTriggeredAt, occurrenceCount) {
+    const s = this.#schedules.get(id);
+    if (s) {
+      s.nextRunAt = nextRunAt;
+      s.lastTriggeredAt = lastTriggeredAt;
+      s.occurrenceCount = occurrenceCount;
+    }
+    this.#claimed.delete(id);
+  }
+  async openAttempt(a) {
+    this.#attempts.push({ ...a });
+  }
+  async updateAttempt(id, patch) {
+    const a = this.#attempts.find((x) => x.id === id);
+    if (a) Object.assign(a, patch);
+  }
+  async listDueRetries(now, limit) {
+    const nowMs = now.getTime();
+    return this.#attempts.filter(
+      (a) => a.status === "pending" && a.retryAt !== void 0 && new Date(a.retryAt).getTime() <= nowMs
+    ).slice(0, limit).map((a) => ({ ...a }));
+  }
+  async hasActiveAttempt(scheduleId) {
+    return this.#attempts.some((a) => a.scheduleId === scheduleId && a.status === "running");
+  }
+  async reclaimOrphans(now, graceMs) {
+    const cutoff = now.getTime() - graceMs;
+    return this.#attempts.filter(
+      (a) => a.status === "running" && a.startedAt !== void 0 && new Date(a.startedAt).getTime() < cutoff
+    ).map((a) => ({ ...a }));
+  }
+  async listAttempts(scheduleId, limit) {
+    const matches = this.#attempts.filter((a) => a.scheduleId === scheduleId);
+    return matches.slice().reverse().slice(0, limit).map((a) => ({ ...a }));
+  }
+  async deadLetteredFor(scheduleId) {
+    return this.#attempts.filter((a) => a.scheduleId === scheduleId && a.status === "dead_letter").map((a) => ({ ...a }));
+  }
+};
+
+// src/core/store.ts
+var StoreError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "StoreError";
+    this.code = code;
+  }
+};
+
+// src/file-store.ts
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeSync
+} from "fs";
+import { join } from "path";
+import { Value as Value2 } from "@sinclair/typebox/value";
+var STATE_FILE = "state.json";
+var TEMP_FILE = "state.json.tmp";
+var FileStore = class {
+  #statePath;
+  #tempPath;
+  #schedules = /* @__PURE__ */ new Map();
+  /** Attempts in insertion order; `listAttempts` returns them newest-first. */
+  #attempts = [];
+  /** Schedule ids whose due slot is claimed pending `advanceSlot`. Transient by design. */
+  #claimed = /* @__PURE__ */ new Set();
+  constructor(dir) {
+    mkdirSync(dir, { recursive: true });
+    this.#statePath = join(dir, STATE_FILE);
+    this.#tempPath = join(dir, TEMP_FILE);
+    rmSync(this.#tempPath, { force: true });
+    this.#load();
+  }
+  #load() {
+    if (!existsSync(this.#statePath)) return;
+    const raw = readFileSync(this.#statePath, "utf8");
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new StoreError("corrupt", `${this.#statePath} is not valid JSON`);
+    }
+    const state = parsed;
+    if (typeof parsed !== "object" || parsed === null || !Array.isArray(state.schedules) || !Array.isArray(state.attempts)) {
+      throw new StoreError("corrupt", `${this.#statePath} has an unexpected shape`);
+    }
+    for (const s of state.schedules) {
+      if (!Value2.Check(ScheduleSchema, s)) {
+        throw new StoreError("corrupt", `${this.#statePath}: invalid schedule record`);
+      }
+      this.#schedules.set(s.id, s);
+    }
+    for (const a of state.attempts) {
+      if (!Value2.Check(AttemptSchema, a)) {
+        throw new StoreError("corrupt", `${this.#statePath}: invalid attempt record`);
+      }
+      this.#attempts.push(a);
+    }
+  }
+  /** Atomically rewrite the full state: temp file + fsync + rename. */
+  #persist() {
+    const json = JSON.stringify({
+      schedules: [...this.#schedules.values()],
+      attempts: this.#attempts
+    });
+    const fd = openSync(this.#tempPath, "w");
+    try {
+      writeSync(fd, json);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    renameSync(this.#tempPath, this.#statePath);
+  }
+  async createSchedule(s) {
+    this.#schedules.set(s.id, { ...s });
+    this.#persist();
+  }
+  async getSchedule(id) {
+    const s = this.#schedules.get(id);
+    return s ? { ...s } : void 0;
+  }
+  async listSchedules() {
+    return [...this.#schedules.values()].map((s) => ({ ...s }));
+  }
+  async removeSchedule(id) {
+    this.#claimed.delete(id);
+    const removed = this.#schedules.delete(id);
+    if (removed) this.#persist();
+    return removed;
+  }
+  async setEnabled(id, enabled) {
+    const s = this.#schedules.get(id);
+    if (s) {
+      s.enabled = enabled;
+      this.#persist();
+    }
+  }
+  async claimDue(now, limit) {
+    const nowMs = now.getTime();
+    const out = [];
+    for (const s of this.#schedules.values()) {
+      if (out.length >= limit) break;
+      if (!s.enabled || s.nextRunAt === null) continue;
+      if (this.#claimed.has(s.id)) continue;
+      if (new Date(s.nextRunAt).getTime() > nowMs) continue;
+      this.#claimed.add(s.id);
+      out.push({ schedule: { ...s }, occurrenceAt: s.nextRunAt });
+    }
+    return out;
+  }
+  async advanceSlot(id, nextRunAt, lastTriggeredAt, occurrenceCount) {
+    const s = this.#schedules.get(id);
+    if (s) {
+      s.nextRunAt = nextRunAt;
+      s.lastTriggeredAt = lastTriggeredAt;
+      s.occurrenceCount = occurrenceCount;
+      this.#persist();
+    }
+    this.#claimed.delete(id);
+  }
+  async openAttempt(a) {
+    this.#attempts.push({ ...a });
+    this.#persist();
+  }
+  async updateAttempt(id, patch) {
+    const a = this.#attempts.find((x) => x.id === id);
+    if (a) {
+      Object.assign(a, patch);
+      this.#persist();
+    }
+  }
+  async listDueRetries(now, limit) {
+    const nowMs = now.getTime();
+    return this.#attempts.filter(
+      (a) => a.status === "pending" && a.retryAt !== void 0 && new Date(a.retryAt).getTime() <= nowMs
+    ).slice(0, limit).map((a) => ({ ...a }));
+  }
+  async hasActiveAttempt(scheduleId) {
+    return this.#attempts.some((a) => a.scheduleId === scheduleId && a.status === "running");
+  }
+  async reclaimOrphans(now, graceMs) {
+    const cutoff = now.getTime() - graceMs;
+    return this.#attempts.filter(
+      (a) => a.status === "running" && a.startedAt !== void 0 && new Date(a.startedAt).getTime() < cutoff
+    ).map((a) => ({ ...a }));
+  }
+  async listAttempts(scheduleId, limit) {
+    const matches = this.#attempts.filter((a) => a.scheduleId === scheduleId);
+    return matches.slice().reverse().slice(0, limit).map((a) => ({ ...a }));
+  }
+  async deadLetteredFor(scheduleId) {
+    return this.#attempts.filter((a) => a.scheduleId === scheduleId && a.status === "dead_letter").map((a) => ({ ...a }));
+  }
+};
+export {
+  AttemptSchema,
+  Engine,
+  FileStore,
+  InMemoryStore,
+  NewScheduleSchema,
+  ScheduleKind,
+  ScheduleSchema,
+  StoreError,
+  SystemClock,
+  TestClock,
+  applyJitter,
+  backoffMs,
+  computeNextRun,
+  validateSchedule
+};