@amenophis1er/foreman 0.1.16 → 0.1.18

package/src/schedule.test.ts

@@ -0,0 +1,240 @@
+// Scheduling is wall-clock arithmetic, so the tests have to own the clock:
+// pin the zone before anything reads a Date, and skip the DST assertions on a
+// machine where the pin did not take (Node re-reads process.env.TZ, but a
+// container without tzdata cannot honour it).
+process.env.TZ = 'America/New_York';
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  describeCadence, nextRunAt, nextRuns, parseCron, validateCadence, type Cadence,
+} from './schedule.js';
+
+/** Is the process actually in US Eastern, offsets and all? */
+const EASTERN = new Date(2026, 0, 15, 12, 0).getTimezoneOffset() === 300
+  && new Date(2026, 6, 15, 12, 0).getTimezoneOffset() === 240;
+
+/** A local-time Date, written the way the assertions read. */
+const local = (y: number, mo: number, d: number, h = 0, mi = 0, s = 0) => new Date(y, mo - 1, d, h, mi, s, 0);
+
+/** 'YYYY-MM-DD HH:MM' in local time — what a failure message should show. */
+const show = (d: Date | null) => (d === null ? 'null' : [
+  `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`,
+  `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`,
+].join(' '));
+
+const at = (cadence: Cadence, after: Date) => show(nextRunAt(cadence, after));
+
+test('daily fires at its wall-clock time, and rolls to tomorrow once past', () => {
+  const daily: Cadence = { kind: 'daily', at: '07:30' };
+  assert.equal(at(daily, local(2026, 3, 2, 6, 0)), '2026-03-02 07:30');
+  assert.equal(at(daily, local(2026, 3, 2, 7, 29, 59)), '2026-03-02 07:30');
+  // Strictly after: standing exactly on the firing minute means tomorrow.
+  assert.equal(at(daily, local(2026, 3, 2, 7, 30)), '2026-03-03 07:30');
+  assert.equal(at(daily, local(2026, 3, 2, 8, 0)), '2026-03-03 07:30');
+  // Seconds and milliseconds are never carried into a firing.
+  const next = nextRunAt(daily, local(2026, 3, 2, 6, 0, 42))!;
+  assert.equal(next.getSeconds(), 0);
+  assert.equal(next.getMilliseconds(), 0);
+  // Month and year roll on their own.
+  assert.equal(at(daily, local(2026, 12, 31, 9, 0)), '2027-01-01 07:30');
+});
+
+test('weekly fires on its day, rolling a whole week when the day has passed', () => {
+  const monday: Cadence = { kind: 'weekly', day: 1, at: '09:00' };
+  // 2026-03-04 is a Wednesday.
+  assert.equal(local(2026, 3, 4).getDay(), 3);
+  assert.equal(at(monday, local(2026, 3, 4, 12, 0)), '2026-03-09 09:00');
+  // On the day, before and after the hour.
+  assert.equal(at(monday, local(2026, 3, 9, 8, 59)), '2026-03-09 09:00');
+  assert.equal(at(monday, local(2026, 3, 9, 9, 0)), '2026-03-16 09:00');
+  // Sunday is 0, not 7.
+  assert.equal(at({ kind: 'weekly', day: 0, at: '23:00' }, local(2026, 3, 4, 12, 0)), '2026-03-08 23:00');
+});
+
+test('interval is elapsed time from `after`, to the millisecond', () => {
+  const six: Cadence = { kind: 'interval', everyMinutes: 360 };
+  const from = local(2026, 5, 4, 10, 17, 33);
+  assert.equal(nextRunAt(six, from)!.getTime() - from.getTime(), 360 * 60_000);
+  const ninety = nextRunAt({ kind: 'interval', everyMinutes: 90 }, from)!;
+  assert.equal(ninety.getTime() - from.getTime(), 90 * 60_000);
+});
+
+test('cron: single values, lists, ranges and steps', () => {
+  assert.equal(at({ kind: 'cron', expr: '0 9 * * *' }, local(2026, 3, 2, 12, 0)), '2026-03-03 09:00');
+  // A list of minutes inside the hour.
+  const list: Cadence = { kind: 'cron', expr: '1,15,45 * * * *' };
+  assert.equal(at(list, local(2026, 3, 2, 12, 2)), '2026-03-02 12:15');
+  assert.equal(at(list, local(2026, 3, 2, 12, 45)), '2026-03-02 13:01');
+  // A range of weekdays: Friday 09:00 jumps to Monday.
+  const weekdays: Cadence = { kind: 'cron', expr: '0 9 * * 1-5' };
+  assert.equal(local(2026, 3, 6).getDay(), 5);
+  assert.equal(at(weekdays, local(2026, 3, 6, 9, 0)), '2026-03-09 09:00');
+  // Steps, on the minute field and on a range.
+  assert.equal(at({ kind: 'cron', expr: '*/15 * * * *' }, local(2026, 3, 2, 12, 1)), '2026-03-02 12:15');
+  assert.equal(at({ kind: 'cron', expr: '10-50/20 * * * *' }, local(2026, 3, 2, 12, 31)), '2026-03-02 12:50');
+  assert.equal(at({ kind: 'cron', expr: '10-50/20 * * * *' }, local(2026, 3, 2, 12, 51)), '2026-03-02 13:10');
+  // An hour step lands on the next multiple, not the next hour.
+  assert.equal(at({ kind: 'cron', expr: '0 */6 * * *' }, local(2026, 3, 2, 7, 0)), '2026-03-02 12:00');
+});
+
+test('parseCron: fields come back sorted, and 7 means Sunday', () => {
+  const c = parseCron('45,15 1-3 1,15 */6 7');
+  assert.deepEqual(c.minutes, [15, 45]);
+  assert.deepEqual(c.hours, [1, 2, 3]);
+  assert.deepEqual(c.daysOfMonth, [1, 15]);
+  assert.deepEqual(c.months, [1, 7]);
+  assert.deepEqual(c.daysOfWeek, [0]);
+  assert.equal(c.domRestricted, true);
+  assert.equal(c.dowRestricted, true);
+  const star = parseCron('0 0 * * *');
+  assert.equal(star.domRestricted, false);
+  assert.equal(star.dowRestricted, false);
+  assert.equal(star.daysOfMonth.length, 31);
+  assert.equal(star.daysOfWeek.length, 7);
+  // Extra whitespace between fields is not an error.
+  assert.deepEqual(parseCron('  0   9  *  *  1  ').hours, [9]);
+});
+
+test('cron: with both day fields restricted, either one may match', () => {
+  // "the 1st of the month, and every Monday" — not the intersection.
+  const both: Cadence = { kind: 'cron', expr: '0 0 1 * 1' };
+  // 2026-04-01 is a Wednesday; it fires on the date alone.
+  assert.equal(local(2026, 4, 1).getDay(), 3);
+  assert.equal(at(both, local(2026, 3, 31, 12, 0)), '2026-04-01 00:00');
+  // and on the next Monday, which is not the 1st.
+  assert.equal(at(both, local(2026, 4, 1, 0, 0)), '2026-04-06 00:00');
+  assert.equal(local(2026, 4, 6).getDay(), 1);
+  // One field restricted is a plain AND with the other's "every".
+  assert.equal(at({ kind: 'cron', expr: '0 0 1 * *' }, local(2026, 4, 1, 0, 0)), '2026-05-01 00:00');
+});
+
+test('cron: month ends, February, and a leap day', () => {
+  // The 31st skips the 30-day months entirely: Jan 31 → Mar 31.
+  assert.equal(at({ kind: 'cron', expr: '0 0 31 * *' }, local(2026, 1, 31, 0, 0)), '2026-03-31 00:00');
+  assert.equal(at({ kind: 'cron', expr: '0 0 31 * *' }, local(2026, 4, 1, 0, 0)), '2026-05-31 00:00');
+  // A February end-of-month rule lands on the 28th in a common year...
+  assert.equal(at({ kind: 'cron', expr: '0 12 28-31 2 *' }, local(2026, 2, 27, 0, 0)), '2026-02-28 12:00');
+  assert.equal(at({ kind: 'cron', expr: '0 12 28-31 2 *' }, local(2026, 2, 28, 12, 0)), '2027-02-28 12:00');
+  // ...and on the 29th in a leap year. 2028 is one; 2100 would not be.
+  assert.equal(at({ kind: 'cron', expr: '0 12 29 2 *' }, local(2026, 1, 1, 0, 0)), '2028-02-29 12:00');
+  // February 30th never happens; the scan gives up instead of hanging.
+  assert.equal(nextRunAt({ kind: 'cron', expr: '0 0 30 2 *' }, local(2026, 1, 1, 0, 0)), null);
+});
+
+test('interval survives a DST change; wall-clock cadences keep the clock time', { skip: EASTERN ? false : 'not in America/New_York' }, () => {
+  // 2026-03-08 is spring forward in US Eastern: 02:00 becomes 03:00.
+  assert.equal(new Date(2026, 2, 8, 0, 30).getTimezoneOffset(), 300);
+  assert.equal(new Date(2026, 2, 8, 12, 0).getTimezoneOffset(), 240);
+
+  // Six hours means six hours: 00:30 EST + 6 h reads 07:30 EDT on the wall.
+  const from = local(2026, 3, 8, 0, 30);
+  const six = nextRunAt({ kind: 'interval', everyMinutes: 360 }, from)!;
+  assert.equal(six.getTime() - from.getTime(), 6 * 3_600_000);
+  assert.equal(show(six), '2026-03-08 07:30');
+
+  // 02:30 does not exist that morning. It must still resolve to a real
+  // instant just after the skip, not hang and not vanish.
+  const daily: Cadence = { kind: 'daily', at: '02:30' };
+  const skipped = nextRunAt(daily, local(2026, 3, 7, 12, 0))!;
+  assert.ok(skipped.getTime() > local(2026, 3, 7, 12, 0).getTime());
+  assert.equal(show(skipped), '2026-03-08 03:30');
+  // and the day after is an ordinary 02:30 again.
+  assert.equal(show(nextRunAt(daily, skipped)), '2026-03-09 02:30');
+
+  // Fall back (2026-11-01, 02:00 becomes 01:00): the hour repeats, and a
+  // daily 01:30 fires once, then the next day.
+  const back = nextRunAt({ kind: 'daily', at: '01:30' }, local(2026, 11, 1, 0, 0))!;
+  assert.equal(show(back), '2026-11-01 01:30');
+  assert.equal(show(nextRunAt({ kind: 'daily', at: '01:30' }, back)), '2026-11-02 01:30');
+
+  // A whole DST week of firings stays strictly increasing.
+  const week = nextRuns({ kind: 'daily', at: '02:30' }, local(2026, 3, 6, 12, 0), 5);
+  assert.equal(week.length, 5);
+  for (let i = 1; i < week.length; i++) assert.ok(week[i].getTime() > week[i - 1].getTime());
+});
+
+test('parseCron: bad expressions say which field and why', () => {
+  const why = (expr: string) => {
+    try {
+      parseCron(expr);
+    } catch (e) {
+      return (e as Error).message;
+    }
+    assert.fail(`expected ${JSON.stringify(expr)} to be rejected`);
+  };
+  assert.match(why('62 * * * *'), /minute: "62" is out of range 0-59/);
+  assert.match(why('0 24 * * *'), /hour: "24" is out of range 0-23/);
+  assert.match(why('0 0 0 * *'), /day-of-month: "0" is out of range 1-31/);
+  assert.match(why('0 0 * 13 *'), /month: "13" is out of range 1-12/);
+  assert.match(why('0 0 * * 8'), /day-of-week: "8" is out of range 0-7/);
+  assert.match(why('0 0 * * mon'), /day-of-week: "mon" is out of range/);
+  assert.match(why('0 0 * *'), /five fields.*got 4/);
+  assert.match(why('0 0 * * * *'), /five fields.*got 6/);
+  assert.match(why(''), /five fields.*got 0/);
+  assert.match(why('5-1 * * * *'), /minute: range "5-1" runs backwards/);
+  assert.match(why('*/0 * * * *'), /minute: step "0" must be a whole number of 1 or more/);
+  assert.match(why('0,,5 * * * *'), /minute: .* has an empty item/);
+  assert.match(why('1-2-3 * * * *'), /minute: "1-2-3" is not a range/);
+  assert.match(why('*/2/2 * * * *'), /minute: .* has more than one step/);
+});
+
+test('validateCadence: accepts what it should and explains what it will not', () => {
+  assert.deepEqual(validateCadence({ kind: 'daily', at: '07:30' }), { ok: true, cadence: { kind: 'daily', at: '07:30' } });
+  assert.deepEqual(validateCadence({ kind: 'weekly', day: 6, at: '23:59' }), { ok: true, cadence: { kind: 'weekly', day: 6, at: '23:59' } });
+  assert.deepEqual(validateCadence({ kind: 'interval', everyMinutes: 60 }), { ok: true, cadence: { kind: 'interval', everyMinutes: 60 } });
+  // Extra fields are dropped, and a cron expression comes back normalised.
+  assert.deepEqual(validateCadence({ kind: 'cron', expr: ' 0  9 * * 1-5 ', junk: 1 }), { ok: true, cadence: { kind: 'cron', expr: '0 9 * * 1-5' } });
+
+  const bad = (input: unknown) => {
+    const r = validateCadence(input);
+    assert.equal(r.ok, false, `expected ${JSON.stringify(input)} to be rejected`);
+    return (r as { ok: false; error: string }).error;
+  };
+  assert.match(bad(null), /must be an object/);
+  assert.match(bad('daily'), /must be an object/);
+  assert.match(bad([{ kind: 'daily', at: '07:30' }]), /must be an object/);
+  assert.match(bad({ kind: 'hourly' }), /kind must be daily, weekly, interval or cron/);
+  assert.match(bad({ kind: 'daily' }), /"HH:MM"/);
+  assert.match(bad({ kind: 'daily', at: '7:30' }), /"HH:MM"/);
+  assert.match(bad({ kind: 'daily', at: '24:00' }), /"HH:MM"/);
+  assert.match(bad({ kind: 'daily', at: '07:60' }), /"HH:MM"/);
+  assert.match(bad({ kind: 'weekly', day: 7, at: '07:30' }), /day must be a whole number 0/);
+  assert.match(bad({ kind: 'weekly', day: 1.5, at: '07:30' }), /day must be a whole number 0/);
+  assert.match(bad({ kind: 'weekly', at: '07:30' }), /day must be a whole number 0/);
+  assert.match(bad({ kind: 'interval', everyMinutes: 59 }), /at least 60/);
+  assert.match(bad({ kind: 'interval', everyMinutes: 90.5 }), /whole number of minutes/);
+  assert.match(bad({ kind: 'interval', everyMinutes: '90' }), /whole number of minutes/);
+  // The point of validating cron here: the reason travels to the 400.
+  assert.match(bad({ kind: 'cron', expr: '99 * * * *' }), /minute: "99" is out of range 0-59/);
+  assert.match(bad({ kind: 'cron', expr: '   ' }), /expr must be a cron expression/);
+  assert.match(bad({ kind: 'cron' }), /expr must be a cron expression/);
+});
+
+test('nextRuns previews N firings, strictly increasing', () => {
+  const three = nextRuns({ kind: 'daily', at: '07:30' }, local(2026, 5, 4, 9, 0), 3);
+  assert.deepEqual(three.map(show), ['2026-05-05 07:30', '2026-05-06 07:30', '2026-05-07 07:30']);
+  for (let i = 1; i < three.length; i++) assert.ok(three[i].getTime() > three[i - 1].getTime());
+
+  assert.deepEqual(
+    nextRuns({ kind: 'interval', everyMinutes: 90 }, local(2026, 5, 4, 9, 0), 3).map(show),
+    ['2026-05-04 10:30', '2026-05-04 12:00', '2026-05-04 13:30'],
+  );
+  assert.deepEqual(
+    nextRuns({ kind: 'cron', expr: '0 9 * * 1-5' }, local(2026, 3, 6, 12, 0), 3).map(show),
+    ['2026-03-09 09:00', '2026-03-10 09:00', '2026-03-11 09:00'],
+  );
+  // Nothing to preview: an impossible expression, and a zero count.
+  assert.deepEqual(nextRuns({ kind: 'cron', expr: '0 0 30 2 *' }, local(2026, 1, 1), 3), []);
+  assert.deepEqual(nextRuns({ kind: 'daily', at: '07:30' }, local(2026, 1, 1), 0), []);
+});
+
+test('describeCadence puts the cadence in words', () => {
+  assert.equal(describeCadence({ kind: 'daily', at: '07:30' }), 'daily 07:30');
+  assert.equal(describeCadence({ kind: 'weekly', day: 1, at: '09:00' }), 'every Monday 09:00');
+  assert.equal(describeCadence({ kind: 'weekly', day: 0, at: '18:15' }), 'every Sunday 18:15');
+  assert.equal(describeCadence({ kind: 'interval', everyMinutes: 360 }), 'every 6 hours');
+  assert.equal(describeCadence({ kind: 'interval', everyMinutes: 60 }), 'every hour');
+  assert.equal(describeCadence({ kind: 'interval', everyMinutes: 90 }), 'every 90 minutes');
+  assert.equal(describeCadence({ kind: 'cron', expr: '0 9 * * 1-5' }), 'cron 0 9 * * 1-5');
+});

package/src/schedule.ts

@@ -0,0 +1,343 @@
+/**
+ * When does a schedule fire next.
+ *
+ * Two callers ask that question — the server's ticker, deciding whether a
+ * scheduled mission is due, and the preview route behind the UI's "next three
+ * runs". If they disagreed by so much as a minute the UI would be lying about
+ * something the user cannot otherwise see, so both go through this module and
+ * nothing else computes a firing time.
+ *
+ * Three deliberate positions:
+ *  - No cron dependency. Five fields with `*`, lists, ranges and steps is an
+ *    afternoon's work and a well-tested one; a package here would be a supply
+ *    chain and an upgrade treadmill for a parser that never changes.
+ *  - Everything is the machine's LOCAL time, computed with local Date fields.
+ *    "daily 07:30" means what the person who typed it sees on the wall clock,
+ *    which is not a fixed number of hours after midnight UTC.
+ *  - Interval cadence is elapsed-time arithmetic instead, so "every 6 hours"
+ *    stays every 6 hours through a DST change rather than gaining or losing
+ *    one. Wall-clock cadences keep the wall-clock promise; that is the whole
+ *    difference between them.
+ *
+ * Every search is capped (see MAX_SCAN_DAYS): an expression like `0 0 30 2 *`
+ * — February 30th — is legal to write and never happens, and a ticker must
+ * answer null for it rather than spin.
+ */
+
+export type Cadence =
+  | { kind: 'daily'; at: string }               // 'HH:MM', machine local time
+  | { kind: 'weekly'; day: number; at: string }  // day 0=Sunday..6=Saturday
+  | { kind: 'interval'; everyMinutes: number }   // minimum 60
+  | { kind: 'cron'; expr: string };             // five fields: min hour dom mon dow
+
+/** Parsed cron fields, each an ascending list of the values it matches. */
+export interface CronFields {
+  minutes: number[];
+  hours: number[];
+  daysOfMonth: number[];
+  months: number[];
+  daysOfWeek: number[];
+  /** Was day-of-month something other than `*`? Decides the OR rule below. */
+  domRestricted: boolean;
+  /** Was day-of-week something other than `*`? */
+  dowRestricted: boolean;
+}
+
+/** 'HH:MM' on a 24-hour clock, and nothing else. */
+const AT_RE = /^([01]\d|2[0-3]):[0-5]\d$/;
+
+/**
+ * How far ahead a search will look before giving up. Five years is far past
+ * any schedule anyone would wait for, and it bounds the impossible ones
+ * (Feb 30, "the 31st of a 30-day month only") to a few thousand cheap checks.
+ */
+const MAX_SCAN_DAYS = 366 * 5;
+
+const DAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+
+/** One cron field's name and legal range, for parsing and for error wording. */
+interface FieldSpec { name: string; min: number; max: number }
+
+const FIELD_SPECS: FieldSpec[] = [
+  { name: 'minute', min: 0, max: 59 },
+  { name: 'hour', min: 0, max: 23 },
+  { name: 'day-of-month', min: 1, max: 31 },
+  { name: 'month', min: 1, max: 12 },
+  // 7 is accepted below and folded onto 0; both spellings of Sunday are in use.
+  { name: 'day-of-week', min: 0, max: 7 },
+];
+
+/** A whole number, written plainly — no '1e3', no '  5 ', no '+5'. */
+function intOrNull(token: string): number | null {
+  if (!/^\d+$/.test(token)) return null;
+  const n = Number(token);
+  return Number.isSafeInteger(n) ? n : null;
+}
+
+/** One value in a field: in range or a named complaint. */
+function valueIn(token: string, spec: FieldSpec): number {
+  const n = intOrNull(token);
+  if (n === null || n < spec.min || n > spec.max) {
+    throw new Error(`${spec.name}: ${JSON.stringify(token)} is out of range ${spec.min}-${spec.max}`);
+  }
+  return n;
+}
+
+// One comma-separated term: `*`, `5`, `1-5`, `*/15`, `10-50/10`, `5/15`.
+function parseTerm(term: string, spec: FieldSpec): number[] {
+  const [body, stepText, ...rest] = term.split('/');
+  if (rest.length) throw new Error(`${spec.name}: ${JSON.stringify(term)} has more than one step`);
+
+  let step = 1;
+  if (stepText !== undefined) {
+    const s = intOrNull(stepText);
+    if (s === null || s < 1) throw new Error(`${spec.name}: step ${JSON.stringify(stepText)} must be a whole number of 1 or more`);
+    step = s;
+  }
+
+  let lo: number;
+  let hi: number;
+  if (body === '*') {
+    lo = spec.min;
+    hi = spec.max;
+  } else if (body.includes('-')) {
+    const [a, b, ...more] = body.split('-');
+    if (more.length) throw new Error(`${spec.name}: ${JSON.stringify(body)} is not a range`);
+    lo = valueIn(a, spec);
+    hi = valueIn(b, spec);
+    if (lo > hi) throw new Error(`${spec.name}: range ${JSON.stringify(body)} runs backwards`);
+  } else {
+    lo = valueIn(body, spec);
+    // `5/15` is Vixie cron's "from 5 to the end of the field, every 15" — a
+    // bare value with no step is just itself.
+    hi = stepText === undefined ? lo : spec.max;
+  }
+
+  const out: number[] = [];
+  for (let v = lo; v <= hi; v += step) out.push(v);
+  return out;
+}
+
+/**
+ * Parses a five-field cron expression, or throws with a reason a person can
+ * act on. It throws rather than returning null because every caller either
+ * has already validated the expression or wants the reason: a bad expression
+ * that quietly became "never runs" is the failure mode worth designing out.
+ */
+export function parseCron(expr: string): CronFields {
+  const fields = String(expr ?? '').trim().split(/\s+/).filter(Boolean);
+  if (fields.length !== 5) {
+    throw new Error(`a cron expression has five fields (minute hour day-of-month month day-of-week), got ${fields.length}`);
+  }
+
+  const parsed = fields.map((field, i) => {
+    const spec = FIELD_SPECS[i];
+    const values = new Set<number>();
+    for (const term of field.split(',')) {
+      if (!term) throw new Error(`${spec.name}: ${JSON.stringify(field)} has an empty item`);
+      // Sunday is 0 or 7; fold so membership tests only ever see 0.
+      for (const v of parseTerm(term, spec)) values.add(spec.name === 'day-of-week' && v === 7 ? 0 : v);
+    }
+    return [...values].sort((a, b) => a - b);
+  });
+
+  return {
+    minutes: parsed[0],
+    hours: parsed[1],
+    daysOfMonth: parsed[2],
+    months: parsed[3],
+    daysOfWeek: parsed[4],
+    domRestricted: fields[2] !== '*',
+    dowRestricted: fields[4] !== '*',
+  };
+}
+
+/**
+ * Does this local date match the cron day fields?
+ *
+ * The OR is not a shortcut. Standard cron treats day-of-month and day-of-week
+ * as alternatives whenever both are restricted, so `0 0 1 * 1` means "the 1st
+ * of the month AND every Monday", not "Mondays that fall on the 1st". People
+ * write `0 9 * * 1-5` and `0 9 1 * *` expecting exactly that, and a schedule
+ * that fired on neither would look broken.
+ */
+function dayMatches(d: Date, c: CronFields): boolean {
+  if (!c.months.includes(d.getMonth() + 1)) return false;
+  const dom = c.daysOfMonth.includes(d.getDate());
+  const dow = c.daysOfWeek.includes(d.getDay());
+  if (c.domRestricted && c.dowRestricted) return dom || dow;
+  return dom && dow;
+}
+
+/**
+ * The first local wall-clock instant strictly after `after` on a matching day
+ * at a matching hour and minute, or null within the scan cap.
+ *
+ * The candidate is built with local Date fields and taken as the Date
+ * constructor normalises it. On a spring-forward day 02:30 does not exist and
+ * normalises to 03:30 local — a real instant, a minute late, which is what a
+ * daily 02:30 schedule should do rather than skip the day or loop looking for
+ * a time the clock never shows.
+ */
+function nextWallClock(after: Date, c: CronFields): Date | null {
+  const cursor = new Date(after.getTime());
+  cursor.setSeconds(0, 0);
+  // Firings are strictly after `after`, and rounded to the minute: from
+  // 09:00:30 the next 09:00 candidate is tomorrow's, not this second's.
+  cursor.setMinutes(cursor.getMinutes() + 1);
+
+  let day = new Date(cursor.getFullYear(), cursor.getMonth(), cursor.getDate());
+  for (let scanned = 0; scanned < MAX_SCAN_DAYS; scanned++) {
+    if (dayMatches(day, c)) {
+      const sameDay = day.getFullYear() === cursor.getFullYear()
+        && day.getMonth() === cursor.getMonth()
+        && day.getDate() === cursor.getDate();
+      for (const h of c.hours) {
+        if (sameDay && h < cursor.getHours()) continue;
+        for (const m of c.minutes) {
+          if (sameDay && h === cursor.getHours() && m < cursor.getMinutes()) continue;
+          const at = new Date(day.getFullYear(), day.getMonth(), day.getDate(), h, m, 0, 0);
+          if (at.getTime() > after.getTime()) return at;
+        }
+      }
+    }
+    // Step by noon rather than midnight: adding 24 h to a midnight that a DST
+    // change moved can land back on the same date and stall the scan.
+    const nextDay = new Date(day.getFullYear(), day.getMonth(), day.getDate(), 12, 0, 0, 0);
+    nextDay.setDate(nextDay.getDate() + 1);
+    day = new Date(nextDay.getFullYear(), nextDay.getMonth(), nextDay.getDate());
+  }
+  return null;
+}
+
+/** The 'HH:MM' of a validated `at`, as numbers. */
+function splitAt(at: string): { hour: number; minute: number } {
+  const [h, m] = at.split(':');
+  return { hour: Number(h), minute: Number(m) };
+}
+
+/** The cron fields a daily/weekly cadence is shorthand for. */
+function fieldsFor(cadence: Cadence): CronFields | null {
+  if (cadence.kind === 'cron') return parseCron(cadence.expr);
+  if (cadence.kind === 'daily') {
+    const { hour, minute } = splitAt(cadence.at);
+    return {
+      minutes: [minute], hours: [hour],
+      daysOfMonth: allBetween(1, 31), months: allBetween(1, 12), daysOfWeek: allBetween(0, 6),
+      domRestricted: false, dowRestricted: false,
+    };
+  }
+  if (cadence.kind === 'weekly') {
+    const { hour, minute } = splitAt(cadence.at);
+    return {
+      minutes: [minute], hours: [hour],
+      daysOfMonth: allBetween(1, 31), months: allBetween(1, 12), daysOfWeek: [cadence.day],
+      domRestricted: false, dowRestricted: true,
+    };
+  }
+  return null;
+}
+
+function allBetween(lo: number, hi: number): number[] {
+  const out: number[] = [];
+  for (let v = lo; v <= hi; v++) out.push(v);
+  return out;
+}
+
+/**
+ * The first moment strictly after `after` at which this cadence fires, or
+ * null when it never will (an impossible cron expression, or an unparseable
+ * one that slipped past validation — a ticker must not throw).
+ */
+export function nextRunAt(cadence: Cadence, after: Date): Date | null {
+  if (!(after instanceof Date) || Number.isNaN(after.getTime())) return null;
+  if (cadence.kind === 'interval') {
+    if (!Number.isInteger(cadence.everyMinutes) || cadence.everyMinutes < 1) return null;
+    // Elapsed time, not wall clock: immune to DST by construction.
+    return new Date(after.getTime() + cadence.everyMinutes * 60_000);
+  }
+  let fields: CronFields | null;
+  try {
+    fields = fieldsFor(cadence);
+  } catch {
+    return null;
+  }
+  return fields ? nextWallClock(after, fields) : null;
+}
+
+/** The next `count` firings after `after` — the UI's "next three runs". */
+export function nextRuns(cadence: Cadence, after: Date, count: number): Date[] {
+  const out: Date[] = [];
+  let cursor = after;
+  for (let i = 0; i < count; i++) {
+    const next = nextRunAt(cadence, cursor);
+    if (!next) break;
+    out.push(next);
+    cursor = next;
+  }
+  return out;
+}
+
+/**
+ * Validates arbitrary JSON into a Cadence, or explains what is wrong. The
+ * server answers 400 with `error`; a bad cron expression must never become a
+ * schedule that silently never runs.
+ */
+export function validateCadence(input: unknown): { ok: true; cadence: Cadence } | { ok: false; error: string } {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return { ok: false, error: 'cadence must be an object' };
+  const o = input as Record<string, unknown>;
+  const kind = o.kind;
+
+  if (kind === 'daily' || kind === 'weekly') {
+    if (typeof o.at !== 'string' || !AT_RE.test(o.at)) {
+      return { ok: false, error: `at must be a time of day as "HH:MM", got ${JSON.stringify(o.at)}` };
+    }
+    if (kind === 'daily') return { ok: true, cadence: { kind: 'daily', at: o.at } };
+    if (!Number.isInteger(o.day) || (o.day as number) < 0 || (o.day as number) > 6) {
+      return { ok: false, error: `day must be a whole number 0 (Sunday) to 6 (Saturday), got ${JSON.stringify(o.day)}` };
+    }
+    return { ok: true, cadence: { kind: 'weekly', day: o.day as number, at: o.at } };
+  }
+
+  if (kind === 'interval') {
+    if (!Number.isInteger(o.everyMinutes)) {
+      return { ok: false, error: `everyMinutes must be a whole number of minutes, got ${JSON.stringify(o.everyMinutes)}` };
+    }
+    // An hour is the floor on purpose: anything tighter is a poll loop, not a
+    // schedule, and a mission takes longer than that to run anyway.
+    if ((o.everyMinutes as number) < 60) return { ok: false, error: 'everyMinutes must be at least 60' };
+    return { ok: true, cadence: { kind: 'interval', everyMinutes: o.everyMinutes as number } };
+  }
+
+  if (kind === 'cron') {
+    if (typeof o.expr !== 'string' || !o.expr.trim()) return { ok: false, error: 'expr must be a cron expression' };
+    try {
+      parseCron(o.expr);
+    } catch (e) {
+      return { ok: false, error: (e as Error).message };
+    }
+    return { ok: true, cadence: { kind: 'cron', expr: o.expr.trim().split(/\s+/).join(' ') } };
+  }
+
+  return { ok: false, error: `kind must be daily, weekly, interval or cron, got ${JSON.stringify(kind)}` };
+}
+
+/** The cadence in words, for a run list or a confirmation line. */
+export function describeCadence(cadence: Cadence): string {
+  switch (cadence.kind) {
+    case 'daily':
+      return `daily ${cadence.at}`;
+    case 'weekly':
+      return `every ${DAY_NAMES[cadence.day] ?? `day ${cadence.day}`} ${cadence.at}`;
+    case 'interval': {
+      const m = cadence.everyMinutes;
+      if (m % 60 === 0) {
+        const hours = m / 60;
+        return hours === 1 ? 'every hour' : `every ${hours} hours`;
+      }
+      return `every ${m} minutes`;
+    }
+    case 'cron':
+      return `cron ${cadence.expr}`;
+  }
+}