@data-club/ai-hub-server 0.0.1

package/src/state/cron.ts

@@ -0,0 +1,179 @@
+/**
+ * Minimal, self-contained 5-field cron evaluator.
+ *
+ * Used as the "advanced" escape hatch for rotating-message schedules
+ * (`schedule_kind = 'cron'`). The common cases are covered by the `every` /
+ * `daily` presets; this handles arbitrary recurrence without pulling in an
+ * external dependency (keeps the build hermetic — no network install).
+ *
+ * **Scope (intentionally numeric-only).** Supports the standard five fields —
+ * `minute hour day-of-month month day-of-week` — with `*`, single values,
+ * ranges (`a-b`), steps (`* / n`, `a-b/n`), and comma lists. It does NOT
+ * support month/weekday names, `L`/`W`/`#`, `@`-aliases, or seconds. Invalid
+ * input throws `CronParseError` so the admin route can surface a 400.
+ *
+ * **Timezone.** All evaluation is in **UTC** — the server stores ISO-8601
+ * UTC timestamps everywhere, and UTC keeps next-run computation deterministic
+ * and test-stable. The admin UI labels cron/daily times as UTC.
+ *
+ * Day-of-month vs day-of-week follow cron's classic rule: when BOTH are
+ * restricted (neither is `*`), a timestamp matches if EITHER matches; when one
+ * is `*`, the other must match.
+ *
+ * @see docs/server/rotating-messages.md
+ */
+
+/** Thrown when a cron expression can't be parsed. */
+export class CronParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CronParseError";
+  }
+}
+
+interface CronFields {
+  minute: ReadonlySet<number>;
+  hour: ReadonlySet<number>;
+  /** day-of-month; `null` when the field is `*` (unrestricted). */
+  dom: ReadonlySet<number> | null;
+  month: ReadonlySet<number>;
+  /** day-of-week 0..6 (Sunday=0); `null` when the field is `*` (unrestricted). */
+  dow: ReadonlySet<number> | null;
+}
+
+/**
+ * Parses one cron field into the set of values it allows.
+ *
+ * @param raw - the field text (e.g. a step `"x/15"`, a range `"1-5"`, a list `"0,30"`).
+ * @param min - smallest legal value for this field.
+ * @param max - largest legal value for this field.
+ * @returns the allowed values, or `null` when the field is a bare `*`.
+ * @throws {CronParseError} on malformed syntax or out-of-range values.
+ */
+function parseField(
+  raw: string,
+  min: number,
+  max: number,
+): Set<number> | null {
+  const trimmed = raw.trim();
+  if (trimmed === "") throw new CronParseError("Empty cron field.");
+  if (trimmed === "*") return null;
+
+  const out = new Set<number>();
+  for (const part of trimmed.split(",")) {
+    const [rangePart, stepPart] = part.split("/") as [string, string?];
+    let step = 1;
+    if (stepPart !== undefined) {
+      step = Number(stepPart);
+      if (!Number.isInteger(step) || step <= 0) {
+        throw new CronParseError(`Invalid step "${stepPart}" in "${raw}".`);
+      }
+    }
+
+    let lo: number;
+    let hi: number;
+    if (rangePart === "*") {
+      lo = min;
+      hi = max;
+    } else if (rangePart.includes("-")) {
+      const [a, b] = rangePart.split("-") as [string, string];
+      lo = Number(a);
+      hi = Number(b);
+    } else {
+      lo = Number(rangePart);
+      hi = lo;
+    }
+    if (!Number.isInteger(lo) || !Number.isInteger(hi)) {
+      throw new CronParseError(`Invalid value "${part}" in "${raw}".`);
+    }
+    if (lo < min || hi > max || lo > hi) {
+      throw new CronParseError(
+        `Value "${part}" out of range ${min}-${max} in "${raw}".`,
+      );
+    }
+    for (let v = lo; v <= hi; v += step) out.add(v);
+  }
+  return out;
+}
+
+/**
+ * Parses a 5-field cron expression.
+ *
+ * @param expr - the expression (whitespace-separated).
+ * @returns the parsed field sets.
+ * @throws {CronParseError} when the expression isn't exactly 5 valid fields.
+ */
+export function parseCron(expr: string): CronFields {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new CronParseError(
+      `Expected 5 cron fields (minute hour day-of-month month day-of-week), got ${parts.length}.`,
+    );
+  }
+  const [m, h, dom, mon, dowRaw] = parts as [string, string, string, string, string];
+  let dow = parseField(dowRaw, 0, 7);
+  // Normalize Sunday-as-7 to 0 so matching against getUTCDay() (0..6) works.
+  if (dow) {
+    const norm = new Set<number>();
+    for (const v of dow) norm.add(v === 7 ? 0 : v);
+    dow = norm;
+  }
+  return {
+    minute: parseField(m, 0, 59) ?? fullRange(0, 59),
+    hour: parseField(h, 0, 23) ?? fullRange(0, 23),
+    dom: parseField(dom, 1, 31),
+    month: parseField(mon, 1, 12) ?? fullRange(1, 12),
+    dow,
+  };
+}
+
+/** Builds a set covering `[lo, hi]` inclusive (used for the `*` minute/hour/month case). */
+function fullRange(lo: number, hi: number): Set<number> {
+  const s = new Set<number>();
+  for (let v = lo; v <= hi; v++) s.add(v);
+  return s;
+}
+
+/** Whether a given instant (in UTC) matches the parsed cron fields. */
+function matches(fields: CronFields, d: Date): boolean {
+  if (!fields.minute.has(d.getUTCMinutes())) return false;
+  if (!fields.hour.has(d.getUTCHours())) return false;
+  if (!fields.month.has(d.getUTCMonth() + 1)) return false;
+
+  const domOk = fields.dom === null || fields.dom.has(d.getUTCDate());
+  const dowOk = fields.dow === null || fields.dow.has(d.getUTCDay());
+  // Classic cron rule: both restricted → OR; otherwise → AND (the `*` side is true).
+  if (fields.dom !== null && fields.dow !== null) {
+    return domOk || dowOk;
+  }
+  return domOk && dowOk;
+}
+
+/** Upper bound on the minute-by-minute forward search (~4 years + buffer). */
+const MAX_SEARCH_MINUTES = 4 * 366 * 24 * 60;
+
+/**
+ * Returns the next instant strictly after `from` that satisfies `expr`, as a
+ * UTC ISO-8601 string.
+ *
+ * @param expr - a 5-field cron expression.
+ * @param from - the reference instant (exclusive lower bound).
+ * @returns the next matching instant as an ISO-8601 UTC string.
+ * @throws {CronParseError} on a malformed expression or if no match is found
+ *   within the search bound (effectively an impossible schedule, e.g. Feb 30).
+ */
+export function cronNextRun(expr: string, from: Date): string {
+  const fields = parseCron(expr);
+  // Start at the next whole minute strictly after `from`.
+  const cursor = new Date(from.getTime());
+  cursor.setUTCSeconds(0, 0);
+  cursor.setUTCMinutes(cursor.getUTCMinutes() + 1);
+
+  for (let i = 0; i < MAX_SEARCH_MINUTES; i++) {
+    if (matches(fields, cursor)) return cursor.toISOString();
+    cursor.setUTCMinutes(cursor.getUTCMinutes() + 1);
+  }
+  throw new CronParseError(
+    `Cron expression "${expr}" has no occurrence within ~4 years — likely impossible (e.g. an invalid day/month combo).`,
+  );
+}

package/src/state/rotationRunner.ts

@@ -0,0 +1,326 @@
+/**
+ * Rotation runner for **rotating starting messages**.
+ *
+ * One rotation turns a configured prompt into a fresh, forkable "prepared
+ * conversation" (see `rotating_message` in `db/schema.ts`):
+ *
+ *   1. `createConversation(letta_agent_id)` — a clean conversation.
+ *   2. Send `prompt` via the normal streaming path, drained to the terminal
+ *      `result`. Reuses `streamUserMessage`, so the rotation inherits the same
+ *      subprocess throttle + toolset-none suppression + model routing as a
+ *      real chat turn.
+ *   3. Find the prompt's `user_message` in the resulting history and delete it,
+ *      so the conversation opens with the agent's reply.
+ *   4. Persist the new conversation id as `current_conversation_id`.
+ *
+ * **Resilience.** Any failure leaves `current_conversation_id` at its last-good
+ * value (sessions keep forking the previous good conversation), records
+ * `last_status = 'error'` + `last_error`, and still advances `next_rotation_at`
+ * so the next interval retries rather than the tick hammering a broken agent.
+ *
+ * `computeNextRotation` / `validateScheduleFields` are pure and unit-tested
+ * independently of any Letta interaction.
+ *
+ * @see docs/server/rotating-messages.md
+ */
+
+import { eq } from "drizzle-orm";
+
+import type { DrizzleDB } from "../db/connection.js";
+import { rotatingMessage, type RotatingMessageRow } from "../db/schema.js";
+import type { LettaClient } from "../letta/client.js";
+import type { Logger } from "../observability/logger.js";
+
+import { CronParseError, cronNextRun, parseCron } from "./cron.js";
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Schedule (pure)                                                           */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** The schedule-shaped subset of a `rotating_message` row. */
+export interface RotationSchedule {
+  scheduleKind: "every" | "daily" | "cron";
+  intervalSeconds: number | null;
+  dailyTime: string | null;
+  cronExpression: string | null;
+}
+
+/** Smallest allowed `every`-interval (guards against hammering Letta). */
+export const MIN_INTERVAL_SECONDS = 60;
+/** Largest allowed `every`-interval (366 days). */
+export const MAX_INTERVAL_SECONDS = 366 * 24 * 3600;
+/** `"HH:MM"` 24-hour validator for the `daily` preset (UTC). */
+const DAILY_TIME_RE = /^([01]\d|2[0-3]):([0-5]\d)$/;
+
+/** Outcome of validating a schedule config. */
+export type ScheduleValidation = { ok: true } | { ok: false; message: string };
+
+/**
+ * Validates a schedule config (used by the admin create/patch handlers).
+ * Pure — the only "work" is parsing cron, which throws `CronParseError` on
+ * malformed input.
+ *
+ * @param s - the schedule fields to validate.
+ * @returns `{ ok: true }` or `{ ok: false, message }`.
+ */
+export function validateScheduleFields(s: RotationSchedule): ScheduleValidation {
+  switch (s.scheduleKind) {
+    case "every": {
+      if (
+        s.intervalSeconds === null ||
+        !Number.isInteger(s.intervalSeconds) ||
+        s.intervalSeconds < MIN_INTERVAL_SECONDS ||
+        s.intervalSeconds > MAX_INTERVAL_SECONDS
+      ) {
+        return {
+          ok: false,
+          message: `interval_seconds must be an integer between ${MIN_INTERVAL_SECONDS} and ${MAX_INTERVAL_SECONDS}.`,
+        };
+      }
+      return { ok: true };
+    }
+    case "daily": {
+      if (!s.dailyTime || !DAILY_TIME_RE.test(s.dailyTime)) {
+        return { ok: false, message: 'daily_time must be "HH:MM" (24-hour, UTC).' };
+      }
+      return { ok: true };
+    }
+    case "cron": {
+      if (!s.cronExpression || s.cronExpression.trim() === "") {
+        return { ok: false, message: "cron_expression is required for schedule_kind 'cron'." };
+      }
+      try {
+        parseCron(s.cronExpression);
+      } catch (err) {
+        return {
+          ok: false,
+          message: err instanceof CronParseError ? err.message : "Invalid cron expression.",
+        };
+      }
+      return { ok: true };
+    }
+  }
+}
+
+/**
+ * Computes the next rotation instant (UTC ISO-8601) strictly after `from`.
+ *
+ * Assumes the schedule already passed `validateScheduleFields`. `daily` and
+ * `cron` are evaluated in UTC (see `cron.ts`).
+ *
+ * @param s - the schedule fields.
+ * @param from - the reference instant.
+ * @returns the next rotation time as a UTC ISO string.
+ */
+export function computeNextRotation(s: RotationSchedule, from: Date): string {
+  switch (s.scheduleKind) {
+    case "every": {
+      const secs = s.intervalSeconds ?? MIN_INTERVAL_SECONDS;
+      return new Date(from.getTime() + secs * 1000).toISOString();
+    }
+    case "daily": {
+      const [hh, mm] = (s.dailyTime ?? "00:00").split(":").map(Number) as [number, number];
+      const next = new Date(from.getTime());
+      next.setUTCHours(hh, mm, 0, 0);
+      if (next.getTime() <= from.getTime()) {
+        next.setUTCDate(next.getUTCDate() + 1);
+      }
+      return next.toISOString();
+    }
+    case "cron":
+      return cronNextRun(s.cronExpression ?? "* * * * *", from);
+  }
+}
+
+/** `computeNextRotation` that never throws — falls back to +1h on a poison row. */
+function safeComputeNextRotation(s: RotationSchedule, from: Date, logger: Logger): string {
+  try {
+    return computeNextRotation(s, from);
+  } catch (err) {
+    logger.error(
+      { err: err instanceof Error ? err.message : String(err), event: "rotation_next_compute_failed" },
+      "Failed to compute next rotation time; falling back to +1h.",
+    );
+    return new Date(from.getTime() + 3600 * 1000).toISOString();
+  }
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Runner                                                                    */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Dependency bundle for `runRotation`. */
+export interface RotationRunnerDeps {
+  /** Drizzle handle. */
+  db: DrizzleDB;
+  /** Letta client wrapper. */
+  lettaClient: LettaClient;
+  /** Logger for this rotation. */
+  logger: Logger;
+  /** Override "now" for deterministic tests. Defaults to `new Date()`. */
+  now?: () => Date;
+}
+
+/** Result of a single rotation attempt. */
+export interface RotationOutcome {
+  status: "ok" | "error";
+  /** The new prepared conversation id (only on success). */
+  conversationId?: string;
+  /** Error message (only on failure). */
+  error?: string;
+}
+
+/**
+ * Runs one rotation for `row` and persists the result. Never throws — the
+ * outcome is reported via the return value and the row's `last_status`.
+ *
+ * @param deps - db + Letta client + logger.
+ * @param row - the rotating-message row to rotate.
+ * @returns the rotation outcome.
+ */
+export async function runRotation(
+  deps: RotationRunnerDeps,
+  row: RotatingMessageRow,
+): Promise<RotationOutcome> {
+  const now = (deps.now ?? (() => new Date()))();
+  const nowIso = now.toISOString();
+  const nextRotationAt = safeComputeNextRotation(row, now, deps.logger);
+  const previousConversationId = row.currentConversationId;
+
+  let createdConversationId: string | null = null;
+  try {
+    const conv = await deps.lettaClient.createConversation(row.lettaAgentId);
+    createdConversationId = conv.id;
+
+    await sendPromptAndDrain(deps.lettaClient, conv.id, row.lettaAgentId, row.prompt);
+
+    // Delete the prompt's user message so the conversation opens with the
+    // agent's reply. listMessages is oldest-first; the first user_message is
+    // the prompt we just sent.
+    const messages = await deps.lettaClient.listMessages(conv.id);
+    const firstUser = messages.find(
+      (m) => (m as { message_type?: string }).message_type === "user_message",
+    );
+    if (firstUser?.id) {
+      await deps.lettaClient.deleteMessage(row.lettaAgentId, firstUser.id);
+    } else {
+      deps.logger.warn(
+        { rotating_message_id: row.id, conversation_id: conv.id, event: "rotation_no_user_message" },
+        "Rotation produced no user_message to delete; storing conversation as-is.",
+      );
+    }
+
+    deps.db
+      .update(rotatingMessage)
+      .set({
+        currentConversationId: conv.id,
+        lastStatus: "ok",
+        lastError: null,
+        lastRotatedAt: nowIso,
+        nextRotationAt,
+        updatedAt: nowIso,
+      })
+      .where(eq(rotatingMessage.id, row.id))
+      .run();
+
+    // Best-effort cleanup of the now-superseded conversation.
+    if (previousConversationId && previousConversationId !== conv.id) {
+      try {
+        await deps.lettaClient.deleteConversation(previousConversationId);
+      } catch (err) {
+        deps.logger.warn(
+          {
+            rotating_message_id: row.id,
+            conversation_id: previousConversationId,
+            err: err instanceof Error ? err.message : String(err),
+            event: "rotation_previous_cleanup_failed",
+          },
+          "Failed to delete the previous prepared conversation; leaving it orphaned.",
+        );
+      }
+    }
+
+    deps.logger.info(
+      {
+        rotating_message_id: row.id,
+        letta_agent_id: row.lettaAgentId,
+        conversation_id: conv.id,
+        next_rotation_at: nextRotationAt,
+        event: "rotation_ok",
+      },
+      "Rotating starting message refreshed.",
+    );
+    return { status: "ok", conversationId: conv.id };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+
+    // Best-effort drop of the half-built conversation so failures don't
+    // accumulate orphans. The last-good current_conversation_id is untouched.
+    if (createdConversationId) {
+      try {
+        await deps.lettaClient.deleteConversation(createdConversationId);
+      } catch {
+        /* best-effort */
+      }
+    }
+
+    deps.db
+      .update(rotatingMessage)
+      .set({
+        lastStatus: "error",
+        lastError: message,
+        nextRotationAt,
+        updatedAt: nowIso,
+      })
+      .where(eq(rotatingMessage.id, row.id))
+      .run();
+
+    deps.logger.error(
+      {
+        rotating_message_id: row.id,
+        letta_agent_id: row.lettaAgentId,
+        err: message,
+        next_rotation_at: nextRotationAt,
+        event: "rotation_error",
+      },
+      "Rotation failed; keeping the previous prepared conversation.",
+    );
+    return { status: "error", error: message };
+  }
+}
+
+/**
+ * Sends `prompt` to `conversationId` and drains the stream to its terminal
+ * `result`. Throws when the run produced no terminal result or finished
+ * unsuccessfully. Always tears the subprocess down via `handle.close()`.
+ */
+async function sendPromptAndDrain(
+  client: LettaClient,
+  conversationId: string,
+  lettaAgentId: string,
+  prompt: string,
+): Promise<void> {
+  const handle = await client.streamUserMessage({
+    conversationId,
+    lettaAgentId,
+    userMessage: prompt,
+  });
+  let sawResult = false;
+  let success = false;
+  try {
+    for await (const msg of handle.events) {
+      if (msg.type === "result") {
+        sawResult = true;
+        success = msg.success;
+      }
+    }
+  } finally {
+    handle.close();
+  }
+  if (!sawResult) {
+    throw new Error("Agent run produced no terminal result.");
+  }
+  if (!success) {
+    throw new Error("Agent run did not complete successfully.");
+  }
+}

package/src/state/rotationScheduler.ts

@@ -0,0 +1,164 @@
+/**
+ * In-process scheduler for **rotating starting messages**.
+ *
+ * ai-hub deploys as one long-running Node process (in-process
+ * `better-sqlite3` + self-hosted Letta), so a simple tick loop is the right
+ * tool — no external cron, queue, or multi-instance coordination needed.
+ *
+ * Each tick selects non-archived `rotating_message` rows whose
+ * `next_rotation_at <= now` and runs them **serially** through `runRotation`.
+ * An in-memory `inFlight` set prevents a slow rotation from being re-picked by
+ * the next tick. `runRotation` advances `next_rotation_at` itself, so a row is
+ * naturally not due again until its interval elapses.
+ *
+ * The scheduler is started once per process from `createFetchHandler`
+ * (`ensureRotationScheduler`) — that's the single construction point both the
+ * dev `node:http` runner and the Next.js wrapper go through. It is **skipped
+ * under tests** (`VITEST` / `NODE_ENV=test`) and via
+ * `AI_HUB_DISABLE_ROTATION_SCHEDULER=1`, so the existing server-boot test
+ * suite is unaffected.
+ *
+ * @see docs/server/rotating-messages.md
+ */
+
+import { and, eq, lte } from "drizzle-orm";
+
+import type { DrizzleDB } from "../db/connection.js";
+import { rotatingMessage } from "../db/schema.js";
+import type { LettaClient } from "../letta/client.js";
+import type { Logger } from "../observability/logger.js";
+
+import { runRotation } from "./rotationRunner.js";
+
+/** Default tick cadence. Rotations are hourly/daily, so 30s polling is ample. */
+const DEFAULT_TICK_MS = 30_000;
+
+/** Dependency bundle for the scheduler. */
+export interface RotationSchedulerDeps {
+  db: DrizzleDB;
+  lettaClient: LettaClient;
+  logger: Logger;
+}
+
+/** Handle for stopping a running scheduler. */
+export interface RotationScheduler {
+  /** Stops the tick loop. Idempotent. */
+  stop(): void;
+}
+
+/** Options for `startRotationScheduler`. */
+export interface StartRotationSchedulerOptions {
+  /** Tick interval in ms. Default 30000. Tests pass a small value. */
+  intervalMs?: number;
+  /** Skip the immediate kick-off tick (tests drive `tickOnce` directly). */
+  skipInitialTick?: boolean;
+}
+
+/**
+ * Starts a tick loop and returns a handle. Most callers want
+ * `ensureRotationScheduler` (process singleton); this is the testable core.
+ *
+ * @param deps - db + Letta client + logger.
+ * @param opts - tick cadence + initial-tick control.
+ * @returns a scheduler handle with `stop()`.
+ */
+export function startRotationScheduler(
+  deps: RotationSchedulerDeps,
+  opts: StartRotationSchedulerOptions = {},
+): RotationScheduler {
+  const intervalMs = opts.intervalMs ?? DEFAULT_TICK_MS;
+  const inFlight = new Set<string>();
+  let stopped = false;
+  let ticking = false;
+
+  const tick = async (): Promise<void> => {
+    if (stopped || ticking) return;
+    ticking = true;
+    try {
+      await tickOnce(deps, inFlight);
+    } catch (err) {
+      deps.logger.error(
+        { err: err instanceof Error ? err.message : String(err), event: "rotation_tick_failed" },
+        "Rotation scheduler tick failed.",
+      );
+    } finally {
+      ticking = false;
+    }
+  };
+
+  const timer = setInterval(() => void tick(), intervalMs);
+  // Never let the scheduler alone keep the process alive.
+  if (typeof timer.unref === "function") timer.unref();
+
+  if (!opts.skipInitialTick) {
+    void tick();
+  }
+
+  return {
+    stop(): void {
+      stopped = true;
+      clearInterval(timer);
+    },
+  };
+}
+
+/**
+ * Runs every due, non-archived rotation once, serially. Exported for tests
+ * (drive a single tick deterministically without a timer).
+ *
+ * @param deps - db + Letta client + logger.
+ * @param inFlight - shared set guarding against re-entrancy across ticks.
+ */
+export async function tickOnce(
+  deps: RotationSchedulerDeps,
+  inFlight: Set<string> = new Set(),
+): Promise<void> {
+  const nowIso = new Date().toISOString();
+  const due = deps.db
+    .select()
+    .from(rotatingMessage)
+    .where(and(eq(rotatingMessage.isArchived, false), lte(rotatingMessage.nextRotationAt, nowIso)))
+    .all();
+
+  for (const row of due) {
+    if (inFlight.has(row.id)) continue;
+    inFlight.add(row.id);
+    try {
+      await runRotation(deps, row);
+    } finally {
+      inFlight.delete(row.id);
+    }
+  }
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Process singleton                                                         */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+let singleton: RotationScheduler | null = null;
+
+/**
+ * Starts the rotation scheduler once per process and returns it (or `null`
+ * when intentionally disabled). Idempotent — subsequent calls return the
+ * already-running instance, so building multiple Fetch handlers in one process
+ * never spawns competing loops.
+ *
+ * Disabled (returns `null`, starts nothing) when:
+ *  - `AI_HUB_DISABLE_ROTATION_SCHEDULER=1`, or
+ *  - running under tests (`VITEST` set, or `NODE_ENV === "test"`).
+ *
+ * @param deps - db + Letta client + logger.
+ * @param env - env source (defaults to `process.env`).
+ * @returns the scheduler handle, or `null` when disabled.
+ */
+export function ensureRotationScheduler(
+  deps: RotationSchedulerDeps,
+  env: Record<string, string | undefined> = process.env,
+): RotationScheduler | null {
+  if (singleton) return singleton;
+  if (env.AI_HUB_DISABLE_ROTATION_SCHEDULER === "1") return null;
+  if (env.VITEST || env.NODE_ENV === "test") return null;
+  singleton = startRotationScheduler(deps);
+  deps.logger.info({ event: "rotation_scheduler_started" }, "Rotating-message scheduler started.");
+  return singleton;
+}