@elmundi/ship-cli 0.12.0 → 0.12.2

package/lib/config/schema.mjs

@@ -49,6 +49,18 @@ export const LANE_FANOUT_MODES = Object.freeze([
 ]);
 export const LANE_FANOUT_DEFAULT = "matrix";
 
+export const PROCESS_AGENT_PROFILES = Object.freeze([
+  "auto",
+  "main",
+  "cheaper",
+  "cursor_agent",
+  "codex_cli",
+  "ship_cloud_agent",
+  "local_cli",
+]);
+
+export const PROCESS_TRIGGER_TYPES = Object.freeze(["manual", "event", "schedule"]);
+
 /* Lane ids travel into file paths (`.ship/state/<key>.json`), workflow
  * file names (`.github/workflows/ship-<lane>.yml`), and env vars, so
  * restrict them conservatively: ASCII lowercase, digits, dash, underscore. */
@@ -198,14 +210,14 @@ export function DEFAULT_PROCESS_CONFIG() {
       { from: "dev_implementation", to: "qa_manual" },
       { from: "qa_manual", to: "pr_review" },
     ],
-    routines: [],
+    routines: {},
   };
 }
 
 /**
  * Back-compat alias. Pre-existing callers expect DEFAULT_CONFIG() to
  * return the current schema's shape; default to v2 so new installs
- * benefit from lanes.
+ * benefit from process routines.
  */
 export function DEFAULT_CONFIG() {
   return DEFAULT_CONFIG_V2();
@@ -346,7 +358,7 @@ function validateV2Process(obj, errors, warnings) {
     }
     pushUnknownKeyWarnings(
       state,
-      new Set(["id", "name", "specialist", "layout", "instructions", "triggers", "exit_conditions", "block_conditions"]),
+      new Set(["id", "name", "specialist", "agent_profile", "layout", "instructions", "triggers", "exit_conditions", "block_conditions"]),
       prefix,
       warnings,
     );
@@ -363,9 +375,33 @@ function validateV2Process(obj, errors, warnings) {
     if (state.instructions !== undefined && typeof state.instructions !== "string") {
       errors.push(`${prefix}.instructions: must be a string when set`);
     }
-    if (state.specialist !== undefined && !isPlainObject(state.specialist) && typeof state.specialist !== "string") {
-      errors.push(`${prefix}.specialist: must be an object or string when set`);
+    if (state.specialist !== undefined) {
+      if (typeof state.specialist === "string") {
+        if (!state.specialist.trim()) {
+          errors.push(`${prefix}.specialist: must be a non-empty string when set`);
+        }
+      } else if (!isPlainObject(state.specialist)) {
+        errors.push(`${prefix}.specialist: must be an object or string when set`);
+      } else {
+        pushUnknownKeyWarnings(
+          state.specialist,
+          new Set(["id", "name", "agent_profile"]),
+          `${prefix}.specialist`,
+          warnings,
+        );
+        requireOptionalString(state.specialist.id, `${prefix}.specialist.id`, errors, { required: false });
+        requireOptionalString(state.specialist.name, `${prefix}.specialist.name`, errors, { required: false });
+        validateProcessAgentProfile(
+          state.specialist.agent_profile,
+          `${prefix}.specialist.agent_profile`,
+          errors,
+        );
+      }
     }
+    validateProcessAgentProfile(state.agent_profile, `${prefix}.agent_profile`, errors);
+    validateProcessTriggers(state.triggers, `${prefix}.triggers`, errors);
+    validateProcessConditions(state.exit_conditions, `${prefix}.exit_conditions`, errors);
+    validateProcessConditions(state.block_conditions, `${prefix}.block_conditions`, errors);
     if (state.layout !== undefined) {
       if (!isPlainObject(state.layout)) {
         errors.push(`${prefix}.layout: must be an object when set`);
@@ -399,12 +435,162 @@ function validateV2Process(obj, errors, warnings) {
         if (!stateIds.has(transition.to)) {
           errors.push(`${prefix}.to: must reference an existing state id`);
         }
+        requireOptionalString(transition.condition, `${prefix}.condition`, errors, { required: false });
       }
     }
   }
 
-  if (process.routines !== undefined && !Array.isArray(process.routines)) {
-    errors.push("process.routines: must be a list when set");
+  validateProcessRoutines(process.routines, errors, warnings);
+}
+
+function validateProcessAgentProfile(value, prefix, errors) {
+  if (value === undefined || value === null) return;
+  if (typeof value !== "string" || !PROCESS_AGENT_PROFILES.includes(value)) {
+    errors.push(`${prefix}: must be one of ${PROCESS_AGENT_PROFILES.join("|")}`);
+  }
+}
+
+function validateProcessTriggers(value, prefix, errors) {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) {
+    errors.push(`${prefix}: must be a list when set`);
+    return;
+  }
+  for (let i = 0; i < value.length; i += 1) {
+    const trigger = value[i];
+    const itemPrefix = `${prefix}[${i}]`;
+    if (!isPlainObject(trigger)) {
+      errors.push(`${itemPrefix}: must be an object`);
+      continue;
+    }
+    if (!PROCESS_TRIGGER_TYPES.includes(trigger.type)) {
+      errors.push(`${itemPrefix}.type: must be one of ${PROCESS_TRIGGER_TYPES.join("|")}`);
+    }
+    if (trigger.type === "schedule") {
+      requireOptionalString(trigger.interval, `${itemPrefix}.interval`, errors, { required: true });
+    } else if (trigger.type === "event") {
+      requireOptionalString(trigger.event, `${itemPrefix}.event`, errors, { required: true });
+    }
+  }
+}
+
+function validateProcessConditions(value, prefix, errors) {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) {
+    errors.push(`${prefix}: must be a list when set`);
+    return;
+  }
+  for (let i = 0; i < value.length; i += 1) {
+    const condition = value[i];
+    const itemPrefix = `${prefix}[${i}]`;
+    if (!isPlainObject(condition)) {
+      errors.push(`${itemPrefix}: must be an object`);
+      continue;
+    }
+    requireOptionalString(condition.expression, `${itemPrefix}.expression`, errors, { required: true });
+  }
+}
+
+function validateProcessRoutines(value, errors, warnings) {
+  if (value === undefined) return;
+  const entries = Array.isArray(value)
+    ? value.map((routine, i) => [String(i), routine, `process.routines[${i}]`])
+    : isPlainObject(value)
+      ? Object.entries(value).map(([id, routine]) => [id, routine, `process.routines.${id}`])
+      : null;
+  if (!entries) {
+    errors.push("process.routines: must be a map or list when set");
+    return;
+  }
+  for (const [routineId, routine, prefix] of entries) {
+    if (!isPlainObject(routine)) {
+      errors.push(`${prefix}: must be an object`);
+      continue;
+    }
+    pushUnknownKeyWarnings(
+      routine,
+      new Set([
+        "id",
+        "name",
+        "cadence",
+        "enabled",
+        "trigger",
+        "description",
+        "prompt",
+        "instructions",
+        "pattern",
+        "patterns",
+        "pattern_version",
+        "fanout",
+        "idempotency",
+        "agent_profile",
+        "specialist_id",
+        "specialist_name",
+        "specialist",
+        "schedule",
+        "window",
+        "event",
+      ]),
+      prefix,
+      warnings,
+    );
+    if (Array.isArray(value)) {
+      requireOptionalString(routine.id, `${prefix}.id`, errors, { required: true });
+    } else if (!LANE_ID_REGEX.test(routineId)) {
+      errors.push(`${prefix}: invalid routine id`);
+    }
+    requireOptionalString(routine.name, `${prefix}.name`, errors, { required: true });
+    requireOptionalString(routine.cadence, `${prefix}.cadence`, errors, { required: false });
+    if (routine.enabled !== undefined && routine.enabled !== null && typeof routine.enabled !== "boolean") {
+      errors.push(`${prefix}.enabled: must be a boolean when set`);
+    }
+    requireOptionalString(routine.description, `${prefix}.description`, errors, { required: false });
+    requireOptionalString(routine.instructions, `${prefix}.instructions`, errors, { required: false });
+    requireOptionalString(routine.prompt, `${prefix}.prompt`, errors, { required: false });
+    requireOptionalString(routine.pattern, `${prefix}.pattern`, errors, { required: false });
+    if (routine.patterns !== undefined) {
+      if (!Array.isArray(routine.patterns) || routine.patterns.some((p) => typeof p !== "string" || !p.trim())) {
+        errors.push(`${prefix}.patterns: must be a list of non-empty strings`);
+      }
+    }
+    if (routine.fanout !== undefined && !LANE_FANOUT_MODES.includes(routine.fanout)) {
+      errors.push(`${prefix}.fanout: must be one of ${LANE_FANOUT_MODES.join("|")}`);
+    }
+    requireOptionalString(routine.specialist_id, `${prefix}.specialist_id`, errors, { required: false });
+    requireOptionalString(routine.specialist_name, `${prefix}.specialist_name`, errors, { required: false });
+    validateProcessAgentProfile(routine.agent_profile, `${prefix}.agent_profile`, errors);
+    validateRoutineTrigger(routine.trigger, `${prefix}.trigger`, errors);
+    if (routine.schedule !== undefined && routine.schedule !== null) {
+      if (typeof routine.schedule !== "string" && !isPlainObject(routine.schedule)) {
+        errors.push(`${prefix}.schedule: must be an object or cron string when set`);
+      }
+    }
+  }
+}
+
+function validateRoutineTrigger(value, prefix, errors) {
+  if (value === undefined || value === null) return;
+  if (!isPlainObject(value)) {
+    errors.push(`${prefix}: must be an object when set`);
+    return;
+  }
+  if (!PROCESS_TRIGGER_TYPES.includes(value.type)) {
+    errors.push(`${prefix}.type: must be one of ${PROCESS_TRIGGER_TYPES.join("|")}`);
+  }
+  if (value.type === "schedule") {
+    requireOptionalString(value.cron ?? value.interval, `${prefix}.cron`, errors, { required: true });
+  }
+  if (value.type === "event") {
+    requireOptionalString(value.event, `${prefix}.event`, errors, { required: true });
+  }
+}
+
+function requireOptionalString(value, prefix, errors, { required }) {
+  if ((value === undefined || value === null) && !required) return;
+  if (typeof value !== "string" || !value.trim()) {
+    errors.push(
+      `${prefix}: must be ${required ? "a non-empty string" : "null or a non-empty string"}`,
+    );
   }
 }
 

package/lib/config.mjs

@@ -8,6 +8,7 @@ export function extractGlobalArgv(argv) {
     baseUrl: (
       process.env.SHIP_API_BASE || "https://ship.elmundi.com/api/methodology"
     ).replace(/\/$/, ""),
+    baseUrlSource: process.env.SHIP_API_BASE ? "env" : "default",
     json: false,
     yes: false,
     force: false,
@@ -39,10 +40,12 @@ export function extractGlobalArgv(argv) {
     if (a === "--base-url" && copy[1]) {
       copy.shift();
       out.baseUrl = String(copy.shift()).replace(/\/$/, "");
+      out.baseUrlSource = "flag";
       continue;
     }
     if (a.startsWith("--base-url=")) {
       out.baseUrl = a.slice("--base-url=".length).replace(/\/$/, "");
+      out.baseUrlSource = "flag";
       copy.shift();
       continue;
     }

package/lib/process/specialist-prompt-contract.mjs

@@ -0,0 +1,171 @@
+export const SPECIALIST_PROMPT_GUARDRAILS = `# Ship specialist execution guardrails
+
+These rules apply to specialist prompts assembled from process configuration,
+ticket context, workspace policies, and knowledge buckets.
+
+## Knowledge First
+
+Before inventing a solution or procedure, search Ship knowledge for relevant
+recipes, patterns, policies, and technical context. Use repository-specific
+knowledge first when a repo is known, then workspace knowledge. If no relevant
+article is found, say that explicitly before proposing a new approach.
+
+Knowledge articles can also answer clarifying technical questions when the
+ticket lacks implementation detail.
+
+## Allowed Exits
+
+A specialist cycle may end only through a Ship-controlled outcome:
+
+- Ask for clarification: return a clarification intent for Ship to post as a
+  tracker comment and mirror into Inbox.
+- Handoff: request one of the transitions explicitly configured in the process
+  FSM. Ship validates the transition before any side effect.
+- Complete with result: produce the final result or PR reference for Ship to
+  record. Repository changes must be delivered through pull requests only.
+
+## Boundaries
+
+Do not perform direct ticket-system mutations. Do not execute transitions that
+are not declared in the process configuration. Do not push directly to protected
+branches or bypass review. All material actions must be represented in Ship
+audit data. Workspace policies are mandatory and override recipe guidance.`;
+
+export function renderSpecialistPromptGuardrails() {
+  return `${SPECIALIST_PROMPT_GUARDRAILS.trim()}\n`;
+}
+
+export function buildSpecialistPromptBundle({
+  process,
+  state,
+  allowedTransitions = [],
+  ticket = null,
+  policies = null,
+}) {
+  const specialist = normalizeSpecialist(state.specialist);
+  const agentProfile =
+    state.agent_profile || specialist.agent_profile || "auto";
+  return {
+    process: {
+      id: process.id,
+      name: process.name || process.id,
+      primary: process.primary === true,
+    },
+    state: {
+      id: state.id,
+      name: state.name || state.id,
+      instructions: typeof state.instructions === "string" ? state.instructions : "",
+      triggers: Array.isArray(state.triggers) ? state.triggers : [],
+      exit_conditions: Array.isArray(state.exit_conditions) ? state.exit_conditions : [],
+      block_conditions: Array.isArray(state.block_conditions) ? state.block_conditions : [],
+    },
+    specialist,
+    agent_profile: agentProfile,
+    ticket,
+    policies,
+    allowed_transitions: allowedTransitions.map((transition) => ({
+      from: transition.from,
+      to: transition.to,
+      condition: transition.condition || null,
+    })),
+    guardrails: renderSpecialistPromptGuardrails(),
+  };
+}
+
+export function renderSpecialistPromptBundleMarkdown(bundle) {
+  const lines = [
+    "# Ship Specialist Prompt Bundle",
+    "",
+    "## Process",
+    "",
+    `- Process: ${bundle.process.name} (\`${bundle.process.id}\`)`,
+    `- Primary: ${bundle.process.primary ? "yes" : "no"}`,
+    `- State: ${bundle.state.name} (\`${bundle.state.id}\`)`,
+    "",
+    "## Specialist",
+    "",
+    `- Specialist: ${bundle.specialist.name} (\`${bundle.specialist.id}\`)`,
+    `- Agent profile: \`${bundle.agent_profile}\``,
+    "",
+    bundle.specialist.role || "No specialist role description configured.",
+    "",
+  ];
+
+  if (bundle.state.instructions) {
+    lines.push("## State Instructions", "", bundle.state.instructions, "");
+  }
+
+  lines.push("## Ticket Context", "");
+  if (bundle.ticket) {
+    lines.push(...renderTicketLines(bundle.ticket), "");
+  } else {
+    lines.push("No ticket context was supplied. Use the Ship tracker picker before starting this specialist cycle.", "");
+  }
+
+  lines.push("## Workspace Policies", "");
+  if (bundle.policies && bundle.policies.trim()) {
+    lines.push(bundle.policies.trim(), "");
+  } else {
+    lines.push("Workspace policies were not supplied locally. In managed runs, Ship must inject enabled workspace policies before the agent starts.", "");
+  }
+
+  lines.push("## Allowed Transitions", "");
+  if (bundle.allowed_transitions.length) {
+    for (const transition of bundle.allowed_transitions) {
+      const condition = transition.condition ? ` when ${transition.condition}` : "";
+      lines.push(`- \`${transition.from}\` -> \`${transition.to}\`${condition}`);
+    }
+  } else {
+    lines.push("- No outgoing transitions are configured for this state. The agent may only ask for clarification or complete with a result.");
+  }
+
+  lines.push(
+    "",
+    "## Required Guardrails",
+    "",
+    bundle.guardrails.trim(),
+    "",
+  );
+  return `${lines.join("\n").trim()}\n`;
+}
+
+function normalizeSpecialist(value) {
+  if (typeof value === "string") {
+    return { id: value, name: value, role: "", agent_profile: null };
+  }
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return {
+      id: String(value.id || value.name || "specialist"),
+      name: String(value.name || value.id || "Specialist"),
+      role: typeof value.role === "string" ? value.role : "",
+      agent_profile: typeof value.agent_profile === "string" ? value.agent_profile : null,
+    };
+  }
+  return { id: "specialist", name: "Specialist", role: "", agent_profile: null };
+}
+
+function renderTicketLines(ticket) {
+  const lines = [];
+  for (const key of ["id", "key", "title", "url", "status", "description"]) {
+    const value = ticket[key];
+    if (typeof value === "string" && value.trim()) {
+      lines.push(`- ${titleCase(key)}: ${value.trim()}`);
+    }
+  }
+  const extra = Object.entries(ticket).filter(
+    ([key, value]) =>
+      !["id", "key", "title", "url", "status", "description"].includes(key) &&
+      value != null &&
+      typeof value !== "object",
+  );
+  for (const [key, value] of extra) {
+    lines.push(`- ${titleCase(key)}: ${String(value)}`);
+  }
+  return lines.length ? lines : ["- Ticket context object was empty."];
+}
+
+function titleCase(value) {
+  return value
+    .replace(/[_-]+/g, " ")
+    .replace(/\b\w/g, (char) => char.toUpperCase());
+}

package/lib/runtime/routines.mjs

@@ -0,0 +1,264 @@
+import { laneFanout, lanePatterns, LANE_FANOUT_DEFAULT } from "../config/schema.mjs";
+
+const DEFAULT_SCHEDULE_WINDOW_MINUTES = 30;
+
+export function routineEntries(config) {
+  const process = config?.process;
+  const raw = process && typeof process === "object" ? process.routines : null;
+  const out = [];
+  if (Array.isArray(raw)) {
+    for (const item of raw) {
+      if (!item || typeof item !== "object") continue;
+      const id = typeof item.id === "string" ? item.id.trim() : "";
+      if (!id) continue;
+      out.push([id, item]);
+    }
+  } else if (raw && typeof raw === "object") {
+    for (const [id, item] of Object.entries(raw)) {
+      if (!item || typeof item !== "object") continue;
+      out.push([id, { id, ...item }]);
+    }
+  }
+  return out;
+}
+
+export function routineMap(config) {
+  return Object.fromEntries(routineEntries(config));
+}
+
+export function resolveExecutable(config, id) {
+  const routines = routineMap(config);
+  if (routines[id]) {
+    return { kind: "routine", id, source: routines[id], executable: routineToExecutable(id, routines[id]) };
+  }
+  const lane = config?.lanes?.[id];
+  if (lane) {
+    return { kind: "lane", id, source: lane, executable: laneToExecutable(id, lane) };
+  }
+  return null;
+}
+
+export function executableIds(config) {
+  return {
+    routines: Object.keys(routineMap(config)).sort(),
+    lanes: Object.keys(config?.lanes || {}).sort(),
+  };
+}
+
+export function routineToExecutable(id, routine) {
+  const trigger = normalizeRoutineTrigger(routine);
+  return {
+    id,
+    type: "routine",
+    kind: trigger.kind,
+    trigger,
+    pattern: stringOrNull(routine.pattern),
+    patterns: Array.isArray(routine.patterns) ? routine.patterns : undefined,
+    pattern_version: stringOrNull(routine.pattern_version),
+    fanout: routine.fanout || LANE_FANOUT_DEFAULT,
+    idempotency: routine.idempotency || null,
+    prompt: stringOrNull(routine.prompt) || stringOrNull(routine.instructions),
+    agent_profile: stringOrNull(routine.agent_profile) || stringOrNull(routine.specialist?.agent_profile),
+  };
+}
+
+export function laneToExecutable(id, lane) {
+  return {
+    id,
+    type: "lane",
+    kind: lane.kind,
+    trigger: laneTrigger(lane),
+    pattern: lane.pattern,
+    patterns: lane.patterns,
+    pattern_version: lane.pattern_version,
+    fanout: laneFanout(lane),
+    idempotency: lane.idempotency || null,
+    prompt: null,
+    agent_profile: null,
+  };
+}
+
+export function executablePatterns(executable) {
+  return lanePatterns(executable);
+}
+
+export function executableFanout(executable) {
+  return executable?.fanout || LANE_FANOUT_DEFAULT;
+}
+
+export function dueRoutines(config, { event, now = new Date() }) {
+  const due = [];
+  const skipped = [];
+  for (const [routineId, routine] of routineEntries(config)) {
+    if (routine.enabled === false) {
+      skipped.push({ routine_id: routineId, reason: "disabled" });
+      continue;
+    }
+    const executable = routineToExecutable(routineId, routine);
+    if (!routineAcceptsEvent(executable, event)) {
+      skipped.push({ routine_id: routineId, reason: "trigger_mismatch", trigger: executable.kind });
+      continue;
+    }
+    if (event === "schedule") {
+      const slot = latestCronMatch(executable.trigger.cron, {
+        now,
+        windowMinutes: executable.trigger.window_minutes,
+      });
+      if (!slot) {
+        skipped.push({ routine_id: routineId, reason: "not_due", trigger: "schedule" });
+        continue;
+      }
+      const windowEnd = new Date(slot.getTime() + executable.trigger.window_minutes * 60_000);
+      due.push({
+        routine_id: routineId,
+        trigger: "schedule",
+        cron: executable.trigger.cron,
+        scheduled_for: slot.toISOString(),
+        window_start: slot.toISOString(),
+        window_end: windowEnd.toISOString(),
+        window_key: `schedule:${routineId}:${formatWindowKey(slot)}`,
+      });
+      continue;
+    }
+    const started = new Date(now);
+    due.push({
+      routine_id: routineId,
+      trigger: event,
+      scheduled_for: started.toISOString(),
+      window_start: started.toISOString(),
+      window_end: started.toISOString(),
+      window_key: `${event}:${routineId}:${formatWindowKey(started)}`,
+    });
+  }
+  return { due, skipped };
+}
+
+export function dueLanesFromRoutines(due) {
+  return due.map((routine) => ({
+    lane_id: routine.routine_id,
+    routine_id: routine.routine_id,
+    kind: routine.trigger,
+    reason: "due",
+    window_key: routine.window_key,
+    scheduled_for: routine.scheduled_for,
+  }));
+}
+
+function normalizeRoutineTrigger(routine) {
+  const trigger = routine.trigger && typeof routine.trigger === "object" ? routine.trigger : {};
+  if (routine.schedule || trigger.type === "schedule") {
+    const schedule = routine.schedule && typeof routine.schedule === "object" ? routine.schedule : {};
+    const cron =
+      stringOrNull(trigger.cron) ||
+      stringOrNull(trigger.interval) ||
+      stringOrNull(schedule.cron) ||
+      stringOrNull(schedule.interval) ||
+      (typeof routine.schedule === "string" ? routine.schedule : null);
+    return {
+      kind: "schedule",
+      cron,
+      window_minutes: parseWindowMinutes(trigger.window || schedule.window || routine.window),
+      catchup: stringOrNull(trigger.catchup) || stringOrNull(schedule.catchup) || "latest",
+    };
+  }
+  if (trigger.type === "event" || routine.event) {
+    return {
+      kind: "event",
+      event: stringOrNull(trigger.event) || stringOrNull(routine.event),
+    };
+  }
+  return { kind: "once" };
+}
+
+function laneTrigger(lane) {
+  if (lane.kind === "schedule") {
+    return {
+      kind: "schedule",
+      cron: stringOrNull(lane.cron),
+      window_minutes: DEFAULT_SCHEDULE_WINDOW_MINUTES,
+      catchup: "latest",
+    };
+  }
+  if (lane.kind === "event") return { kind: "event", event: stringOrNull(lane.on) };
+  return { kind: lane.kind || "once" };
+}
+
+function routineAcceptsEvent(executable, event) {
+  if (event === "schedule") return executable.kind === "schedule";
+  if (event === "manual") return ["schedule", "event", "once"].includes(executable.kind);
+  if (executable.kind !== "event") return false;
+  const configured = executable.trigger.event || "";
+  return configured.split(",").map((part) => part.trim()).filter(Boolean).includes(event);
+}
+
+function latestCronMatch(cron, { now, windowMinutes }) {
+  if (typeof cron !== "string" || !cron.trim()) return null;
+  const fields = cron.trim().split(/\s+/);
+  if (fields.length !== 5) return null;
+  const [minute, hour, dom, month, dow] = fields;
+  const cursor = new Date(now);
+  cursor.setUTCSeconds(0, 0);
+  for (let offset = 0; offset <= windowMinutes; offset += 1) {
+    const candidate = new Date(cursor.getTime() - offset * 60_000);
+    if (
+      cronFieldMatches(minute, candidate.getUTCMinutes(), 0, 59) &&
+      cronFieldMatches(hour, candidate.getUTCHours(), 0, 23) &&
+      cronFieldMatches(dom, candidate.getUTCDate(), 1, 31) &&
+      cronFieldMatches(month, candidate.getUTCMonth() + 1, 1, 12) &&
+      cronFieldMatches(dow, candidate.getUTCDay(), 0, 6)
+    ) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function cronFieldMatches(expr, value, min, max) {
+  for (const rawPart of String(expr).split(",")) {
+    const part = rawPart.trim();
+    if (!part) continue;
+    let step = 1;
+    let base = part;
+    if (part.includes("/")) {
+      const pieces = part.split("/");
+      base = pieces[0];
+      step = Number.parseInt(pieces[1], 10);
+      if (!Number.isInteger(step) || step <= 0) continue;
+    }
+    let start;
+    let end;
+    if (base === "*") {
+      start = min;
+      end = max;
+    } else if (base.includes("-")) {
+      const [a, b] = base.split("-");
+      start = Number.parseInt(a, 10);
+      end = Number.parseInt(b, 10);
+    } else {
+      start = Number.parseInt(base, 10);
+      end = start;
+    }
+    if (!Number.isInteger(start) || !Number.isInteger(end)) continue;
+    if (start <= value && value <= end && (value - start) % step === 0) return true;
+  }
+  return false;
+}
+
+function parseWindowMinutes(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return Math.floor(value);
+  if (typeof value !== "string" || !value.trim()) return DEFAULT_SCHEDULE_WINDOW_MINUTES;
+  const raw = value.trim();
+  const match = raw.match(/^(\d+)\s*(m|min|minute|minutes)?$/i);
+  if (match) return Math.max(1, Number.parseInt(match[1], 10));
+  const hours = raw.match(/^(\d+)\s*(h|hr|hour|hours)$/i);
+  if (hours) return Math.max(1, Number.parseInt(hours[1], 10) * 60);
+  return DEFAULT_SCHEDULE_WINDOW_MINUTES;
+}
+
+function formatWindowKey(date) {
+  return date.toISOString().slice(0, 16).replace(/[-:]/g, "").replace("T", "T");
+}
+
+function stringOrNull(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}