@valentinkolb/sync 2.2.0 → 3.0.0

package/browser/scheduler.js

@@ -0,0 +1,988 @@
+// src/browser/store.ts
+class MemoryStore {
+  data = new Map;
+  timers = new Map;
+  get(key) {
+    const entry = this.data.get(key);
+    if (!entry)
+      return;
+    if (entry.expiresAt !== null && Date.now() >= entry.expiresAt) {
+      this.del(key);
+      return;
+    }
+    return entry.value;
+  }
+  set(key, value, ttlMs) {
+    const existingTimer = this.timers.get(key);
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+      this.timers.delete(key);
+    }
+    const expiresAt = ttlMs != null && ttlMs > 0 ? Date.now() + ttlMs : null;
+    this.data.set(key, { value, expiresAt });
+    if (ttlMs != null && ttlMs > 0) {
+      this.timers.set(key, setTimeout(() => this.del(key), ttlMs));
+    }
+  }
+  del(key) {
+    this.data.delete(key);
+    const timer = this.timers.get(key);
+    if (timer) {
+      clearTimeout(timer);
+      this.timers.delete(key);
+    }
+  }
+  keys(prefix) {
+    const now = Date.now();
+    const result = [];
+    for (const [key, entry] of this.data) {
+      if (entry.expiresAt !== null && now >= entry.expiresAt) {
+        this.del(key);
+        continue;
+      }
+      if (prefix === undefined || key.startsWith(prefix)) {
+        result.push(key);
+      }
+    }
+    return result;
+  }
+  clear() {
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+    this.data.clear();
+  }
+}
+var createMemoryStore = () => new MemoryStore;
+
+// src/browser/internal/sleep.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var createAbortError = () => {
+  const error = new Error("sleep aborted");
+  error.name = "AbortError";
+  return error;
+};
+var sleepWithSignal = async (delayMs, signal) => {
+  if (delayMs <= 0)
+    return;
+  if (!signal) {
+    await sleep(delayMs);
+    return;
+  }
+  if (signal.aborted)
+    throw createAbortError();
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, delayMs);
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+      reject(createAbortError());
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+};
+
+// src/browser/internal/id.ts
+var randomHex = (bytes) => {
+  const buf = new Uint8Array(bytes);
+  crypto.getRandomValues(buf);
+  return Array.from(buf, (b) => b.toString(16).padStart(2, "0")).join("");
+};
+var simpleHash = (str) => {
+  let hash = 5381;
+  for (let i = 0;i < str.length; i++) {
+    hash = (hash << 5) + hash + str.charCodeAt(i) | 0;
+  }
+  return `hash:${(hash >>> 0).toString(16)}`;
+};
+
+// src/browser/mutex.ts
+var DEFAULT_PREFIX = "sync:mutex";
+var DEFAULT_RETRY_COUNT = 10;
+var DEFAULT_RETRY_DELAY = 200;
+var DEFAULT_TTL = 1e4;
+var MAX_RESOURCE_LENGTH = 128;
+var normalizeResource = (resource) => {
+  if (resource.length <= MAX_RESOURCE_LENGTH)
+    return resource;
+  return simpleHash(resource);
+};
+
+class LockError extends Error {
+  resource;
+  constructor(resource) {
+    super(`Failed to acquire lock on resource: ${resource}`);
+    this.name = "LockError";
+    this.resource = resource;
+  }
+}
+var mutex = (config) => {
+  const prefix = config.prefix ?? DEFAULT_PREFIX;
+  const retryCount = config.retryCount ?? DEFAULT_RETRY_COUNT;
+  const retryDelay = config.retryDelay ?? DEFAULT_RETRY_DELAY;
+  const defaultTtl = config.defaultTtl ?? DEFAULT_TTL;
+  const store = config.store ?? createMemoryStore();
+  const acquire = async (resource, ttl = defaultTtl) => {
+    const safeResource = normalizeResource(resource);
+    const key = `${prefix}:${config.id}:${safeResource}`;
+    const value = randomHex(16);
+    for (let attempt = 0;attempt <= retryCount; attempt++) {
+      const existing = store.get(key);
+      if (existing === undefined) {
+        store.set(key, value, ttl);
+        return {
+          resource: key,
+          value,
+          ttl,
+          expiration: Date.now() + ttl
+        };
+      }
+      if (attempt < retryCount) {
+        await sleep(retryDelay + Math.random() * 100);
+      }
+    }
+    return null;
+  };
+  const release = async (lock) => {
+    const current = store.get(lock.resource);
+    if (current === lock.value) {
+      store.del(lock.resource);
+    }
+  };
+  const extend = async (lock, ttl = defaultTtl) => {
+    const current = store.get(lock.resource);
+    if (current === lock.value) {
+      store.set(lock.resource, lock.value, ttl);
+      lock.ttl = ttl;
+      lock.expiration = Date.now() + ttl;
+      return true;
+    }
+    return false;
+  };
+  const withLock = async (resource, fn, ttl) => {
+    const lock = await acquire(resource, ttl);
+    if (!lock)
+      return null;
+    try {
+      return await fn(lock);
+    } finally {
+      await release(lock);
+    }
+  };
+  const withLockOrThrow = async (resource, fn, ttl) => {
+    const lock = await acquire(resource, ttl);
+    if (!lock) {
+      throw new LockError(resource);
+    }
+    try {
+      return await fn(lock);
+    } finally {
+      await release(lock);
+    }
+  };
+  return { id: config.id, acquire, release, withLock, withLockOrThrow, extend };
+};
+
+// src/browser/retry.ts
+var asError = (error) => error instanceof Error ? error : new Error(String(error));
+var createAbortError2 = () => {
+  const error = new Error("retry aborted");
+  error.name = "AbortError";
+  return error;
+};
+var parseCode = (error) => {
+  if (!error || typeof error !== "object")
+    return "";
+  const code = error.code;
+  return typeof code === "string" ? code.toUpperCase() : "";
+};
+var isRetryableTransportError = (error) => {
+  const code = parseCode(error);
+  if (code === "ECONNRESET" || code === "ETIMEDOUT" || code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "EPIPE" || code === "EHOSTUNREACH" || code === "ECONNABORTED") {
+    return true;
+  }
+  const message = asError(error).message.toLowerCase();
+  return message.includes("econnreset") || message.includes("etimedout") || message.includes("connection") || message.includes("socket") || message.includes("broken pipe") || message.includes("network") || message.includes("loading") || message.includes("tryagain") || message.includes("clusterdown");
+};
+var DEFAULT_RETRY_OPTIONS = {
+  attempts: 8,
+  minDelayMs: 100,
+  maxDelayMs: 2000,
+  factor: 2,
+  jitter: 0.2,
+  retryIf: isRetryableTransportError
+};
+var computeDelayMs = (attempt, opts) => {
+  const base = opts.minDelayMs * opts.factor ** Math.max(0, attempt - 1);
+  const capped = Math.min(opts.maxDelayMs, base);
+  const spread = capped * opts.jitter;
+  const jittered = capped + (Math.random() * 2 - 1) * spread;
+  return Math.max(0, Math.floor(jittered));
+};
+var retry = async (fn, opts = {}) => {
+  const attempts = Math.max(1, opts.attempts ?? DEFAULT_RETRY_OPTIONS.attempts);
+  const minDelayMs = Math.max(0, opts.minDelayMs ?? DEFAULT_RETRY_OPTIONS.minDelayMs);
+  const maxDelayMs = Math.max(minDelayMs, opts.maxDelayMs ?? DEFAULT_RETRY_OPTIONS.maxDelayMs);
+  const factor = Math.max(1, opts.factor ?? DEFAULT_RETRY_OPTIONS.factor);
+  const jitter = Math.min(1, Math.max(0, opts.jitter ?? DEFAULT_RETRY_OPTIONS.jitter));
+  const retryIf = opts.retryIf ?? DEFAULT_RETRY_OPTIONS.retryIf;
+  for (let attempt = 1;attempt <= attempts; attempt++) {
+    if (opts.signal?.aborted)
+      throw createAbortError2();
+    try {
+      return await fn(attempt);
+    } catch (error) {
+      if (attempt >= attempts)
+        throw error;
+      if (!retryIf(error))
+        throw error;
+      const delayMs = computeDelayMs(attempt, { minDelayMs, maxDelayMs, factor, jitter });
+      await sleepWithSignal(delayMs, opts.signal);
+    }
+  }
+  throw new Error("unreachable retry state");
+};
+
+// src/internal/cron.ts
+var MAX_LOOKAHEAD_MINUTES = 5 * 366 * 24 * 60;
+var WEEKDAY_TO_NUM = {
+  Sun: 0,
+  Mon: 1,
+  Tue: 2,
+  Wed: 3,
+  Thu: 4,
+  Fri: 5,
+  Sat: 6
+};
+var zonedFormatterCache = new Map;
+var parsedCronCache = new Map;
+var getZonedFormatter = (tz) => {
+  const cached = zonedFormatterCache.get(tz);
+  if (cached)
+    return cached;
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    hour12: false,
+    hourCycle: "h23",
+    minute: "2-digit",
+    hour: "2-digit",
+    day: "2-digit",
+    month: "2-digit",
+    year: "numeric",
+    weekday: "short"
+  });
+  zonedFormatterCache.set(tz, formatter);
+  return formatter;
+};
+var asInt = (value, fieldName) => {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) {
+    throw new Error(`invalid ${fieldName} value: ${value}`);
+  }
+  return parsed;
+};
+var normalizeDow = (value) => {
+  if (value === 7)
+    return 0;
+  return value;
+};
+var parseSegment = (segment, min, max, fieldName) => {
+  const [base, stepRaw] = segment.split("/");
+  const step = stepRaw === undefined ? 1 : asInt(stepRaw, `${fieldName} step`);
+  if (step <= 0)
+    throw new Error(`invalid ${fieldName} step: ${segment}`);
+  const resolvedBase = base ?? "*";
+  let start = min;
+  let end = max;
+  if (resolvedBase !== "*") {
+    if (resolvedBase.includes("-")) {
+      const [a, b] = resolvedBase.split("-");
+      if (a === undefined || b === undefined)
+        throw new Error(`invalid ${fieldName} range: ${segment}`);
+      start = asInt(a, fieldName);
+      end = asInt(b, fieldName);
+    } else {
+      start = asInt(resolvedBase, fieldName);
+      end = start;
+    }
+  }
+  if (fieldName === "day-of-week") {
+    const rawStart = start;
+    const rawEnd = end;
+    start = normalizeDow(start);
+    end = normalizeDow(end);
+    if (rawStart !== rawEnd && start > end) {
+      const wrappedValues = [];
+      for (let v = start;v <= max; v += step)
+        wrappedValues.push(v);
+      for (let v = min;v <= end; v += step)
+        wrappedValues.push(v);
+      return wrappedValues;
+    }
+  }
+  if (start < min || start > max || end < min || end > max || start > end) {
+    throw new Error(`out-of-range ${fieldName}: ${segment}`);
+  }
+  const values = [];
+  for (let v = start;v <= end; v += step)
+    values.push(v);
+  return values;
+};
+var parseField = (raw, min, max, fieldName) => {
+  if (raw === "*")
+    return { any: true, values: new Set };
+  const values = new Set;
+  for (const segment of raw.split(",")) {
+    const trimmed = segment.trim();
+    if (!trimmed)
+      throw new Error(`invalid ${fieldName} field: "${raw}"`);
+    for (const v of parseSegment(trimmed, min, max, fieldName)) {
+      values.add(fieldName === "day-of-week" ? normalizeDow(v) : v);
+    }
+  }
+  if (values.size === 0)
+    throw new Error(`invalid ${fieldName} field: "${raw}"`);
+  return { any: false, values };
+};
+var parseCron = (raw) => {
+  const cached = parsedCronCache.get(raw);
+  if (cached)
+    return cached;
+  const parts = raw.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`cron must have 5 fields (minute hour day-of-month month day-of-week), got: "${raw}"`);
+  }
+  const [minuteRaw, hourRaw, dayOfMonthRaw, monthRaw, dayOfWeekRaw] = parts;
+  const spec = {
+    minute: parseField(minuteRaw, 0, 59, "minute"),
+    hour: parseField(hourRaw, 0, 23, "hour"),
+    dayOfMonth: parseField(dayOfMonthRaw, 1, 31, "day-of-month"),
+    month: parseField(monthRaw, 1, 12, "month"),
+    dayOfWeek: parseField(dayOfWeekRaw, 0, 7, "day-of-week")
+  };
+  parsedCronCache.set(raw, spec);
+  if (parsedCronCache.size > 1000) {
+    const firstKey = parsedCronCache.keys().next().value;
+    if (firstKey)
+      parsedCronCache.delete(firstKey);
+  }
+  return spec;
+};
+var floorToMinute = (timestampMs) => {
+  return Math.floor(timestampMs / 60000) * 60000;
+};
+var toZonedParts = (timestampMs, tz) => {
+  const parts = getZonedFormatter(tz).formatToParts(new Date(timestampMs));
+  let minute = -1;
+  let hour = -1;
+  let dayOfMonth = -1;
+  let month = -1;
+  let dayOfWeek = -1;
+  for (const part of parts) {
+    if (part.type === "minute")
+      minute = Number(part.value);
+    else if (part.type === "hour")
+      hour = Number(part.value);
+    else if (part.type === "day")
+      dayOfMonth = Number(part.value);
+    else if (part.type === "month")
+      month = Number(part.value);
+    else if (part.type === "weekday")
+      dayOfWeek = WEEKDAY_TO_NUM[part.value] ?? -1;
+  }
+  if (minute < 0 || hour < 0 || dayOfMonth < 0 || month < 0 || dayOfWeek < 0) {
+    throw new Error(`failed to resolve zoned time parts for timezone "${tz}"`);
+  }
+  return { minute, hour, dayOfMonth, month, dayOfWeek };
+};
+var matchesField = (field, value) => field.any || field.values.has(value);
+var matchesDay = (spec, dayOfMonth, dayOfWeek) => {
+  const domAny = spec.dayOfMonth.any;
+  const dowAny = spec.dayOfWeek.any;
+  const domMatches = domAny || spec.dayOfMonth.values.has(dayOfMonth);
+  const dowMatches = dowAny || spec.dayOfWeek.values.has(dayOfWeek);
+  if (domAny && dowAny)
+    return true;
+  if (domAny)
+    return dowMatches;
+  if (dowAny)
+    return domMatches;
+  return domMatches || dowMatches;
+};
+var matchesCron = (spec, timestampMs, tz) => {
+  const p = toZonedParts(timestampMs, tz);
+  return matchesField(spec.minute, p.minute) && matchesField(spec.hour, p.hour) && matchesField(spec.month, p.month) && matchesDay(spec, p.dayOfMonth, p.dayOfWeek);
+};
+var nextCronTimestamp = (cron, tz, afterTimestampMs) => {
+  const spec = parseCron(cron);
+  let candidate = floorToMinute(afterTimestampMs) + 60000;
+  for (let i = 0;i < MAX_LOOKAHEAD_MINUTES; i++) {
+    if (matchesCron(spec, candidate, tz))
+      return candidate;
+    candidate += 60000;
+  }
+  throw new Error(`unable to find next cron execution within lookahead window for "${cron}" (${tz})`);
+};
+var assertValidTimeZone = (tz) => {
+  getZonedFormatter(tz);
+};
+
+// src/browser/scheduler.ts
+var DEFAULT_PREFIX2 = "sync:scheduler";
+var DAY_MS = 24 * 60 * 60 * 1000;
+var DEFAULT_LEASE_MS = 5000;
+var DEFAULT_HEARTBEAT_MS = 500;
+var DEFAULT_TICK_MS = 500;
+var DEFAULT_BATCH_SIZE = 200;
+var DEFAULT_MAX_SUBMITS_PER_TICK = 500;
+var DEFAULT_SUBMIT_RETRIES = 3;
+var DEFAULT_SUBMIT_BACKOFF_BASE_MS = 100;
+var DEFAULT_SUBMIT_BACKOFF_MAX_MS = 2000;
+var DEFAULT_SCHEDULED_JOB_KEY_TTL_MS = 90 * DAY_MS;
+var DEFAULT_DISPATCH_DLQ_MAX_ENTRIES = 5000;
+var DEFAULT_MISFIRE = "skip";
+var DEFAULT_MAX_CATCH_UP_RUNS = 100;
+var DEFAULT_MAX_CONSECUTIVE_DISPATCH_FAILURES = 5;
+var DEFAULT_STRICT_HANDLERS = true;
+var asError2 = (error) => error instanceof Error ? error : new Error(String(error));
+var safeMetric = (onMetric, metric) => {
+  if (!onMetric)
+    return;
+  try {
+    onMetric(metric);
+  } catch {}
+};
+var asInfo = (schedule) => ({
+  id: schedule.id,
+  cron: schedule.cron,
+  tz: schedule.tz,
+  misfire: schedule.misfire,
+  maxCatchUpRuns: schedule.maxCatchUpRuns,
+  jobId: schedule.jobId,
+  nextRunAt: schedule.nextRunAt,
+  createdAt: schedule.createdAt,
+  updatedAt: schedule.updatedAt
+});
+var computeDispatchPlan = (schedule, nowMs) => {
+  if (schedule.nextRunAt > nowMs)
+    return null;
+  if (schedule.misfire === "skip") {
+    return {
+      slots: [],
+      nextRunAt: nextCronTimestamp(schedule.cron, schedule.tz, nowMs)
+    };
+  }
+  if (schedule.misfire === "catch_up_one") {
+    return {
+      slots: [schedule.nextRunAt],
+      nextRunAt: nextCronTimestamp(schedule.cron, schedule.tz, nowMs)
+    };
+  }
+  const slots = [];
+  let cursor = schedule.nextRunAt;
+  const maxRuns = Math.max(1, schedule.maxCatchUpRuns);
+  while (cursor <= nowMs && slots.length < maxRuns) {
+    slots.push(cursor);
+    cursor = nextCronTimestamp(schedule.cron, schedule.tz, cursor);
+  }
+  return {
+    slots,
+    nextRunAt: cursor
+  };
+};
+var schedulerSharedStores = new Map;
+var schedulerSharedSchedules = new Map;
+var scheduler = (config) => {
+  const prefix = config.prefix ?? DEFAULT_PREFIX2;
+  const leaseMs = Math.max(500, config.leader?.leaseMs ?? DEFAULT_LEASE_MS);
+  const heartbeatMs = Math.max(100, config.leader?.heartbeatMs ?? DEFAULT_HEARTBEAT_MS);
+  const tickMs = Math.max(50, config.dispatch?.tickMs ?? DEFAULT_TICK_MS);
+  const batchSize = Math.max(1, config.dispatch?.batchSize ?? DEFAULT_BATCH_SIZE);
+  const maxSubmitsPerTick = Math.max(1, config.dispatch?.maxSubmitsPerTick ?? DEFAULT_MAX_SUBMITS_PER_TICK);
+  const submitRetries = Math.max(0, config.dispatch?.submitRetries ?? DEFAULT_SUBMIT_RETRIES);
+  const submitBackoffBaseMs = Math.max(10, config.dispatch?.submitBackoffBaseMs ?? DEFAULT_SUBMIT_BACKOFF_BASE_MS);
+  const submitBackoffMaxMs = Math.max(submitBackoffBaseMs, config.dispatch?.submitBackoffMaxMs ?? DEFAULT_SUBMIT_BACKOFF_MAX_MS);
+  const scheduledJobKeyTtlMs = Math.max(60000, config.dispatch?.scheduledJobKeyTtlMs ?? DEFAULT_SCHEDULED_JOB_KEY_TTL_MS);
+  const dlqMaxEntries = Math.max(1, config.dispatch?.dlqMaxEntries ?? DEFAULT_DISPATCH_DLQ_MAX_ENTRIES);
+  const maxConsecutiveDispatchFailures = Math.max(1, config.dispatch?.maxConsecutiveDispatchFailures ?? DEFAULT_MAX_CONSECUTIVE_DISPATCH_FAILURES);
+  const strictHandlers = config.strictHandlers ?? DEFAULT_STRICT_HANDLERS;
+  const sharedMutexStoreKey = `${prefix}:${config.id}:leader:store`;
+  if (!schedulerSharedStores.has(sharedMutexStoreKey)) {
+    schedulerSharedStores.set(sharedMutexStoreKey, createMemoryStore());
+  }
+  const sharedMutexStore = schedulerSharedStores.get(sharedMutexStoreKey);
+  const leaderMutex = mutex({
+    id: `${config.id}:leader`,
+    prefix: `${prefix}:leader`,
+    defaultTtl: leaseMs,
+    retryCount: 0,
+    store: sharedMutexStore
+  });
+  const sharedSchedulesKey = `${prefix}:${config.id}:schedules`;
+  if (!schedulerSharedSchedules.has(sharedSchedulesKey)) {
+    schedulerSharedSchedules.set(sharedSchedulesKey, new Map);
+  }
+  const schedules = schedulerSharedSchedules.get(sharedSchedulesKey);
+  const jobsById = new Map;
+  const scheduleToJobId = new Map;
+  const dispatchDlq = [];
+  const metricsState = {
+    isLeader: false,
+    leaderEpoch: 0,
+    leaderChanges: 0,
+    dispatchSubmitted: 0,
+    dispatchFailed: 0,
+    dispatchRetried: 0,
+    dispatchSkipped: 0,
+    dispatchDlq: 0,
+    triggerSubmitted: 0,
+    triggerFailed: 0,
+    triggerRejected: 0,
+    tickErrors: 0,
+    lastTickAt: null
+  };
+  let running = false;
+  let loopPromise = null;
+  let currentLeaderLock = null;
+  let currentLeaderEpoch = 0;
+  let lastHeartbeatAt = 0;
+  const setLeader = (next, reason) => {
+    if (metricsState.isLeader === next)
+      return;
+    metricsState.isLeader = next;
+    metricsState.leaderChanges += 1;
+    if (next) {
+      safeMetric(config.onMetric, { type: "leader_acquired", ts: Date.now() });
+      return;
+    }
+    safeMetric(config.onMetric, { type: "leader_lost", ts: Date.now(), reason: reason ?? "stop" });
+  };
+  const tryAcquireLeadership = async () => {
+    if (currentLeaderLock)
+      return;
+    const acquired = await leaderMutex.acquire("active", leaseMs);
+    if (!acquired)
+      return;
+    currentLeaderLock = acquired;
+    currentLeaderEpoch++;
+    metricsState.leaderEpoch = currentLeaderEpoch;
+    lastHeartbeatAt = Date.now();
+    setLeader(true);
+  };
+  const maintainLeadership = async () => {
+    if (!currentLeaderLock)
+      return;
+    const nowMs = Date.now();
+    if (nowMs - lastHeartbeatAt < heartbeatMs)
+      return;
+    const ok = await leaderMutex.extend(currentLeaderLock, leaseMs);
+    lastHeartbeatAt = nowMs;
+    if (!ok) {
+      currentLeaderLock = null;
+      setLeader(false, "extend_failed");
+    }
+  };
+  const relinquishLeadership = async () => {
+    if (!currentLeaderLock)
+      return;
+    try {
+      await leaderMutex.release(currentLeaderLock);
+    } catch {}
+    currentLeaderLock = null;
+    setLeader(false, "stop");
+  };
+  const ensureLeadership = async () => {
+    if (!currentLeaderLock)
+      return false;
+    const nowMs = Date.now();
+    if (nowMs - lastHeartbeatAt >= heartbeatMs) {
+      const ok = await leaderMutex.extend(currentLeaderLock, leaseMs);
+      lastHeartbeatAt = nowMs;
+      if (!ok) {
+        currentLeaderLock = null;
+        setLeader(false, "extend_failed");
+        return false;
+      }
+    }
+    return metricsState.isLeader;
+  };
+  const submitScheduledJob = async (cfg) => {
+    return await retry(async () => {
+      if (cfg.requireLeadership && !await ensureLeadership()) {
+        throw new Error("leadership lost during dispatch");
+      }
+      return await cfg.jobHandle.submit({
+        input: cfg.schedule.input,
+        key: cfg.key,
+        keyTtlMs: scheduledJobKeyTtlMs,
+        ...cfg.at !== undefined ? { at: cfg.at } : {},
+        meta: cfg.meta
+      });
+    }, {
+      attempts: submitRetries + 1,
+      minDelayMs: submitBackoffBaseMs,
+      maxDelayMs: submitBackoffMaxMs,
+      factor: 2,
+      jitter: 0.25,
+      retryIf: (error) => {
+        const err = asError2(error);
+        if (err.name === "ZodError")
+          return false;
+        if (cfg.requireLeadership && err.message === "leadership lost during dispatch")
+          return false;
+        cfg.onRetry?.();
+        return true;
+      }
+    });
+  };
+  const pushDispatchDlq = (cfg) => {
+    dispatchDlq.unshift({ ...cfg, ts: Date.now() });
+    if (dispatchDlq.length > dlqMaxEntries) {
+      dispatchDlq.length = dlqMaxEntries;
+    }
+    metricsState.dispatchDlq += 1;
+    safeMetric(config.onMetric, {
+      type: "dispatch_dlq",
+      ts: Date.now(),
+      scheduleId: cfg.scheduleId,
+      slotTs: cfg.slotTs,
+      message: cfg.message
+    });
+  };
+  const recordDispatchFailure = (cfg) => {
+    const sameSlot = cfg.schedule.lastFailedSlotTs === cfg.failedSlotTs;
+    const failures = sameSlot ? cfg.schedule.consecutiveDispatchFailures + 1 : 1;
+    const shouldAdvance = cfg.deterministic || failures >= maxConsecutiveDispatchFailures;
+    cfg.schedule.consecutiveDispatchFailures = failures;
+    cfg.schedule.lastFailedSlotTs = cfg.failedSlotTs;
+    cfg.schedule.lastDispatchError = cfg.message;
+    cfg.schedule.updatedAt = Date.now();
+    if (shouldAdvance) {
+      cfg.schedule.nextRunAt = nextCronTimestamp(cfg.schedule.cron, cfg.schedule.tz, cfg.failedSlotTs);
+      cfg.schedule.consecutiveDispatchFailures = 0;
+      safeMetric(config.onMetric, {
+        type: "dispatch_advanced_after_failures",
+        ts: Date.now(),
+        scheduleId: cfg.schedule.id,
+        slotTs: cfg.failedSlotTs,
+        failures
+      });
+    }
+  };
+  const dispatchDue = async () => {
+    const nowMs = Date.now();
+    const dueSchedules = [];
+    for (const schedule of schedules.values()) {
+      if (schedule.nextRunAt <= nowMs) {
+        dueSchedules.push(schedule);
+      }
+    }
+    dueSchedules.sort((a, b) => a.nextRunAt - b.nextRunAt);
+    const batch = dueSchedules.slice(0, batchSize);
+    if (batch.length === 0)
+      return;
+    let submitsRemaining = maxSubmitsPerTick;
+    for (const schedule of batch) {
+      if (!await ensureLeadership())
+        break;
+      if (schedule.nextRunAt > nowMs)
+        continue;
+      const plan = computeDispatchPlan(schedule, nowMs);
+      if (!plan)
+        continue;
+      const jobHandle = jobsById.get(schedule.jobId);
+      if (!jobHandle && plan.slots.length > 0) {
+        metricsState.dispatchSkipped += 1;
+        safeMetric(config.onMetric, {
+          type: "dispatch_skipped",
+          ts: nowMs,
+          scheduleId: schedule.id,
+          reason: "missing_handler"
+        });
+        if (strictHandlers) {
+          await relinquishLeadership();
+          break;
+        }
+        continue;
+      }
+      let submitFailed = false;
+      let submittedAny = false;
+      let lastSubmittedSlotTs = null;
+      for (const slotTs of plan.slots) {
+        if (submitsRemaining <= 0)
+          break;
+        if (!await ensureLeadership()) {
+          submitFailed = true;
+          break;
+        }
+        try {
+          const jobId = await submitScheduledJob({
+            jobHandle,
+            schedule,
+            key: `${schedule.id}:${slotTs}`,
+            at: slotTs,
+            meta: {
+              ...schedule.meta ?? {},
+              scheduleId: schedule.id,
+              scheduleSlotTs: slotTs,
+              schedulerId: config.id
+            },
+            requireLeadership: true,
+            onRetry: () => {
+              metricsState.dispatchRetried += 1;
+            }
+          });
+          metricsState.dispatchSubmitted += 1;
+          submitsRemaining -= 1;
+          submittedAny = true;
+          lastSubmittedSlotTs = slotTs;
+          safeMetric(config.onMetric, {
+            type: "dispatch_submitted",
+            ts: Date.now(),
+            scheduleId: schedule.id,
+            slotTs,
+            jobId
+          });
+        } catch (error) {
+          submitFailed = true;
+          metricsState.dispatchFailed += 1;
+          const err = asError2(error);
+          pushDispatchDlq({
+            scheduleId: schedule.id,
+            slotTs,
+            message: err.message
+          });
+          recordDispatchFailure({
+            schedule,
+            failedSlotTs: slotTs,
+            message: err.message,
+            deterministic: err.name === "ZodError"
+          });
+          safeMetric(config.onMetric, {
+            type: "dispatch_failed",
+            ts: Date.now(),
+            scheduleId: schedule.id,
+            message: err.message
+          });
+          break;
+        }
+      }
+      if (submitFailed)
+        continue;
+      if (submitsRemaining <= 0) {
+        if (submittedAny && lastSubmittedSlotTs !== null) {
+          schedule.nextRunAt = nextCronTimestamp(schedule.cron, schedule.tz, lastSubmittedSlotTs);
+          schedule.updatedAt = Date.now();
+          scheduleToJobId.set(schedule.id, schedule.jobId);
+        }
+        break;
+      }
+      schedule.nextRunAt = plan.nextRunAt;
+      schedule.updatedAt = Date.now();
+      scheduleToJobId.set(schedule.id, schedule.jobId);
+    }
+  };
+  const loop = async () => {
+    while (running) {
+      try {
+        await tryAcquireLeadership();
+        await maintainLeadership();
+        if (currentLeaderLock) {
+          await dispatchDue();
+        }
+        metricsState.lastTickAt = Date.now();
+      } catch (error) {
+        metricsState.tickErrors += 1;
+        safeMetric(config.onMetric, {
+          type: "tick_error",
+          ts: Date.now(),
+          message: asError2(error).message
+        });
+      }
+      await sleep(tickMs);
+    }
+  };
+  const register = async (cfg) => {
+    const tz = cfg.tz ?? "UTC";
+    assertValidTimeZone(tz);
+    cfg.job.validateInput?.(cfg.input);
+    const nowMs = Date.now();
+    const misfire = cfg.misfire ?? DEFAULT_MISFIRE;
+    const maxCatchUpRuns = Math.max(1, cfg.maxCatchUpRuns ?? DEFAULT_MAX_CATCH_UP_RUNS);
+    const firstRunAt = nextCronTimestamp(cfg.cron, tz, nowMs);
+    const existing = schedules.get(cfg.id);
+    const stored = {
+      id: cfg.id,
+      cron: cfg.cron,
+      tz,
+      misfire,
+      maxCatchUpRuns,
+      jobId: cfg.job.id,
+      input: cfg.input,
+      meta: cfg.meta,
+      createdAt: existing?.createdAt ?? nowMs,
+      updatedAt: nowMs,
+      nextRunAt: firstRunAt,
+      consecutiveDispatchFailures: 0
+    };
+    if (existing && existing.cron === cfg.cron && existing.tz === tz) {
+      stored.nextRunAt = existing.nextRunAt;
+      stored.consecutiveDispatchFailures = existing.consecutiveDispatchFailures;
+      stored.lastFailedSlotTs = existing.lastFailedSlotTs;
+      stored.lastDispatchError = existing.lastDispatchError;
+    }
+    const created = !existing;
+    const updated = !!existing;
+    schedules.set(cfg.id, stored);
+    jobsById.set(cfg.job.id, cfg.job);
+    const previousJobId = scheduleToJobId.get(cfg.id);
+    scheduleToJobId.set(cfg.id, cfg.job.id);
+    if (previousJobId && previousJobId !== cfg.job.id) {
+      let stillUsed = false;
+      for (const [sid, jid] of scheduleToJobId.entries()) {
+        if (sid !== cfg.id && jid === previousJobId) {
+          stillUsed = true;
+          break;
+        }
+      }
+      if (!stillUsed)
+        jobsById.delete(previousJobId);
+    }
+    safeMetric(config.onMetric, {
+      type: "schedule_registered",
+      ts: Date.now(),
+      scheduleId: cfg.id,
+      created
+    });
+    if (updated) {
+      safeMetric(config.onMetric, {
+        type: "schedule_updated",
+        ts: Date.now(),
+        scheduleId: cfg.id
+      });
+    }
+    return { created, updated };
+  };
+  const unregister = async (cfg) => {
+    const jobId = scheduleToJobId.get(cfg.id);
+    schedules.delete(cfg.id);
+    scheduleToJobId.delete(cfg.id);
+    safeMetric(config.onMetric, {
+      type: "schedule_unregistered",
+      ts: Date.now(),
+      scheduleId: cfg.id
+    });
+    if (jobId) {
+      let stillUsed = false;
+      for (const mappedJobId of scheduleToJobId.values()) {
+        if (mappedJobId === jobId) {
+          stillUsed = true;
+          break;
+        }
+      }
+      if (!stillUsed)
+        jobsById.delete(jobId);
+    }
+  };
+  const triggerNow = async (cfg) => {
+    const schedule = schedules.get(cfg.id);
+    if (!schedule) {
+      metricsState.triggerRejected += 1;
+      safeMetric(config.onMetric, {
+        type: "trigger_rejected",
+        ts: Date.now(),
+        scheduleId: cfg.id,
+        reason: "missing_schedule"
+      });
+      throw new Error(`scheduler trigger rejected: missing schedule ${cfg.id}`);
+    }
+    const jobHandle = jobsById.get(schedule.jobId);
+    if (!jobHandle) {
+      metricsState.triggerRejected += 1;
+      safeMetric(config.onMetric, {
+        type: "trigger_rejected",
+        ts: Date.now(),
+        scheduleId: schedule.id,
+        reason: "missing_handler"
+      });
+      throw new Error(`scheduler trigger rejected: missing local handler for schedule ${schedule.id}`);
+    }
+    try {
+      const jobId = await submitScheduledJob({
+        jobHandle,
+        schedule,
+        key: cfg.key ? `manual:${schedule.id}:${cfg.key}` : undefined,
+        meta: {
+          ...schedule.meta ?? {},
+          scheduleId: schedule.id,
+          schedulerId: config.id,
+          scheduleTrigger: "manual",
+          ...cfg.key ? { scheduleManualKey: cfg.key } : {}
+        },
+        requireLeadership: false
+      });
+      metricsState.triggerSubmitted += 1;
+      safeMetric(config.onMetric, {
+        type: "trigger_submitted",
+        ts: Date.now(),
+        scheduleId: schedule.id,
+        jobId
+      });
+      return jobId;
+    } catch (error) {
+      metricsState.triggerFailed += 1;
+      const err = asError2(error);
+      safeMetric(config.onMetric, {
+        type: "trigger_failed",
+        ts: Date.now(),
+        scheduleId: schedule.id,
+        message: err.message
+      });
+      throw error;
+    }
+  };
+  const get = async (cfg) => {
+    const schedule = schedules.get(cfg.id);
+    if (!schedule)
+      return null;
+    return asInfo(schedule);
+  };
+  const listSchedules = async () => {
+    return Array.from(schedules.values()).map(asInfo).sort((a, b) => a.id.localeCompare(b.id));
+  };
+  const start = () => {
+    if (running)
+      return;
+    running = true;
+    loopPromise = loop();
+  };
+  const stop = async () => {
+    if (!running)
+      return;
+    running = false;
+    setLeader(false, "stop");
+    await relinquishLeadership();
+    if (loopPromise) {
+      await loopPromise;
+      loopPromise = null;
+    }
+  };
+  return {
+    id: config.id,
+    start,
+    stop,
+    register,
+    unregister,
+    triggerNow,
+    get,
+    list: listSchedules,
+    metrics: () => ({ ...metricsState })
+  };
+};
+export {
+  scheduler
+};