@moxxy/sdk 0.44.0 → 0.45.0

package/src/cron.test.ts

@@ -0,0 +1,280 @@
+import { describe, expect, it } from 'vitest';
+import { assertDefined } from './assert.js';
+import { isValidCron, isValidTimeZone, nextFireTime, parseCron } from './cron.js';
+
+describe('parseCron', () => {
+  it('parses every-minute', () => {
+    const c = parseCron('* * * * *');
+    expect(c.minute.values.size).toBe(60);
+    expect(c.hour.values.size).toBe(24);
+    expect(c.minute.restricted).toBe(false);
+  });
+
+  it('parses a literal', () => {
+    const c = parseCron('0 9 * * *');
+    expect([...c.minute.values]).toEqual([0]);
+    expect([...c.hour.values]).toEqual([9]);
+    expect(c.minute.restricted).toBe(true);
+  });
+
+  it('parses a range', () => {
+    const c = parseCron('0 9-11 * * *');
+    expect([...c.hour.values]).toEqual([9, 10, 11]);
+  });
+
+  it('parses a list', () => {
+    const c = parseCron('0 0,12,18 * * *');
+    expect([...c.hour.values].sort((a, b) => a - b)).toEqual([0, 12, 18]);
+  });
+
+  it('parses a step', () => {
+    const c = parseCron('*/15 * * * *');
+    expect([...c.minute.values].sort((a, b) => a - b)).toEqual([0, 15, 30, 45]);
+    expect(c.minute.restricted).toBe(false);
+  });
+
+  it('parses a range with step', () => {
+    const c = parseCron('0 9-17/2 * * *');
+    expect([...c.hour.values].sort((a, b) => a - b)).toEqual([9, 11, 13, 15, 17]);
+  });
+
+  it('rejects out-of-range', () => {
+    expect(() => parseCron('0 25 * * *')).toThrow();
+  });
+
+  it('rejects wrong-arity', () => {
+    expect(() => parseCron('0 9 *')).toThrow();
+  });
+
+  it('isValidCron returns false on garbage', () => {
+    expect(isValidCron('not a cron')).toBe(false);
+    expect(isValidCron('0 9 * * *')).toBe(true);
+  });
+});
+
+describe('nextFireTime', () => {
+  it('finds the next 9 AM', () => {
+    // Mon 2026-05-11 08:30 local → next 9 AM is same day 09:00
+    const after = new Date(2026, 4, 11, 8, 30, 0);
+    const next = nextFireTime('0 9 * * *', after);
+    expect(next).not.toBeNull();
+    assertDefined(next, 'nextFireTime resolves to a fire time');
+    expect(next.getHours()).toBe(9);
+    expect(next.getMinutes()).toBe(0);
+    expect(next.getDate()).toBe(11);
+  });
+
+  it('wraps to next day when already past', () => {
+    const after = new Date(2026, 4, 11, 10, 0, 0);
+    const next = nextFireTime('0 9 * * *', after);
+    assertDefined(next, 'nextFireTime resolves to a fire time');
+    expect(next.getDate()).toBe(12);
+    expect(next.getHours()).toBe(9);
+  });
+
+  it('every-15-min fires at the next quarter', () => {
+    const after = new Date(2026, 4, 11, 10, 7, 0);
+    const next = nextFireTime('*/15 * * * *', after);
+    assertDefined(next, 'nextFireTime resolves to a fire time');
+    expect(next.getHours()).toBe(10);
+    expect(next.getMinutes()).toBe(15);
+  });
+
+  it('every hour at minute 30 finds the next half-hour', () => {
+    const after = new Date(2026, 4, 11, 10, 45, 0);
+    const next = nextFireTime('30 * * * *', after);
+    assertDefined(next, 'nextFireTime resolves to a fire time');
+    expect(next.getHours()).toBe(11);
+    expect(next.getMinutes()).toBe(30);
+  });
+
+  it('returns null for impossible expressions', () => {
+    // Feb 30th never exists.
+    const after = new Date(2026, 0, 1, 0, 0, 0);
+    const next = nextFireTime('0 0 30 2 *', after);
+    expect(next).toBeNull();
+  });
+
+  it('honors DOW restriction', () => {
+    // 2026-05-11 is a Monday. "9 AM on Sundays" -> next Sunday 2026-05-17
+    const after = new Date(2026, 4, 11, 8, 0, 0);
+    const next = nextFireTime('0 9 * * 0', after);
+    assertDefined(next, 'nextFireTime resolves to a fire time');
+    expect(next.getDay()).toBe(0);
+    expect(next.getDate()).toBe(17);
+  });
+
+  // u103-4: jumpToNextMonth must walk across a year boundary. From mid-year,
+  // "midnight on Jan 1" lands on the following Jan 1.
+  it('walks across a year boundary for an annual expression', () => {
+    const after = new Date(2026, 5, 15, 12, 0, 0); // mid-June 2026
+    const next = nextFireTime('0 0 1 1 *', after);
+    expect(next).not.toBeNull();
+    assertDefined(next, 'nextFireTime resolves to a fire time');
+    expect(next.getFullYear()).toBe(2027);
+    expect(next.getMonth()).toBe(0); // January
+    expect(next.getDate()).toBe(1);
+    expect(next.getHours()).toBe(0);
+    expect(next.getMinutes()).toBe(0);
+  });
+
+  it('jumps to the next valid month within the same year', () => {
+    // From January, "midnight on the 1st of March" -> 2026-03-01.
+    const after = new Date(2026, 0, 10, 0, 0, 0); // 2026-01-10
+    const next = nextFireTime('0 0 1 3 *', after);
+    assertDefined(next, 'nextFireTime resolves to a fire time');
+    expect(next.getFullYear()).toBe(2026);
+    expect(next.getMonth()).toBe(2); // March
+    expect(next.getDate()).toBe(1);
+  });
+
+  // u103-4: vixie-cron OR semantics — when BOTH DOM and DOW are restricted,
+  // a fire matches on EITHER. `0 0 13 * 5` fires on the 13th OR any Friday.
+  it('matches the soonest of DOM-13 OR Friday (DOW arm first)', () => {
+    // After Sat 2026-06-06, the next Friday is 2026-06-12 (DOW arm), which
+    // comes before the 13th (the DOM arm). So the Friday wins.
+    const after = new Date(2026, 5, 6, 0, 0, 0); // Sat 2026-06-06
+    const next = nextFireTime('0 0 13 * 5', after);
+    expect(next).not.toBeNull();
+    assertDefined(next, 'nextFireTime resolves to a fire time');
+    expect(next.getDate()).toBe(12);
+    expect(next.getDay()).toBe(5); // Friday
+  });
+
+  it('matches the 13th via the DOM arm even when it is not a Friday', () => {
+    // After Fri 2026-06-12 00:01, the next match is Sat 2026-06-13 — a 13th
+    // that is NOT a Friday. AND-semantics would skip it; OR-semantics fires.
+    const after = new Date(2026, 5, 12, 0, 1, 0); // just past midnight Fri 06-12
+    const next = nextFireTime('0 0 13 * 5', after);
+    expect(next).not.toBeNull();
+    assertDefined(next, 'nextFireTime resolves to a fire time');
+    expect(next.getDate()).toBe(13);
+    expect(next.getDay()).toBe(6); // Saturday — matched purely via DOM
+  });
+
+  // Regression for u103-1: with an explicit IANA zone the cursor walk must
+  // match AND advance in that zone, not jump in the host-local zone. These
+  // assertions hold regardless of the host TZ because they check the
+  // absolute instant's wall-clock rendering in the target zone.
+  const wallClockInZone = (d: Date, timeZone: string) => {
+    const fmt = new Intl.DateTimeFormat('en-US', {
+      timeZone,
+      hour: '2-digit',
+      minute: '2-digit',
+      hour12: false,
+    });
+    const parts: Record<string, string> = {};
+    for (const p of fmt.formatToParts(d)) parts[p.type] = p.value;
+    return { hour: Number(parts.hour) % 24, minute: Number(parts.minute) };
+  };
+
+  it('fires at 09:00 wall-clock in an explicit New York zone', () => {
+    // Anchor far enough back that the host TZ cannot accidentally satisfy it.
+    const after = new Date(Date.UTC(2026, 4, 11, 0, 0, 0));
+    const next = nextFireTime('0 9 * * *', after, 'America/New_York');
+    expect(next).not.toBeNull();
+    assertDefined(next, 'nextFireTime resolves to a fire time');
+    const wc = wallClockInZone(next, 'America/New_York');
+    expect(wc.hour).toBe(9);
+    expect(wc.minute).toBe(0);
+  });
+
+  it('fires at 09:00 wall-clock in an explicit Tokyo zone', () => {
+    const after = new Date(Date.UTC(2026, 4, 11, 0, 0, 0));
+    const next = nextFireTime('0 9 * * *', after, 'Asia/Tokyo');
+    expect(next).not.toBeNull();
+    assertDefined(next, 'nextFireTime resolves to a fire time');
+    const wc = wallClockInZone(next, 'Asia/Tokyo');
+    expect(wc.hour).toBe(9);
+    expect(wc.minute).toBe(0);
+  });
+
+  it('handles spring-forward DST in an explicit zone', () => {
+    // US spring-forward 2026: 2026-03-08, clocks jump 02:00 -> 03:00 EST->EDT.
+    // "30 2 * * *" (02:30) does not exist that day; the next valid 02:30 is
+    // the following day. The walk must not loop to the 1-year cap.
+    const after = new Date(Date.UTC(2026, 2, 8, 0, 0, 0));
+    const next = nextFireTime('30 2 * * *', after, 'America/New_York');
+    expect(next).not.toBeNull();
+    assertDefined(next, 'nextFireTime resolves to a fire time');
+    const wc = wallClockInZone(next, 'America/New_York');
+    expect(wc.hour).toBe(2);
+    expect(wc.minute).toBe(30);
+  });
+
+  // Worst case (DoS): a structurally-impossible expression in an EXPLICIT IANA
+  // zone must NOT walk the full 366-day minute-by-minute window (~527k
+  // Intl.formatToParts calls, ~2s of blocked event loop) before returning null.
+  // The calendar-fact pre-check bails instantly. We assert correctness (null)
+  // AND a tight time bound so a regression that removes the short-circuit fails.
+  it('bails instantly (not a 2s walk) on an impossible explicit-zone cron', () => {
+    const after = new Date(Date.UTC(2026, 0, 1, 0, 0, 0));
+    const start = performance.now();
+    expect(nextFireTime('0 0 30 2 *', after, 'America/New_York')).toBeNull(); // Feb 30
+    expect(nextFireTime('0 0 31 4 *', after, 'America/New_York')).toBeNull(); // Apr 31
+    expect(nextFireTime('0 0 31 4,6,9,11 *', after, 'Asia/Tokyo')).toBeNull(); // 31st of only 30-day months
+    const elapsed = performance.now() - start;
+    // Three impossible explicit-zone evaluations. Pre-fix this was ~6s; the
+    // short-circuit makes it sub-millisecond. Generous bound to avoid CI flake.
+    expect(elapsed).toBeLessThan(250);
+  });
+
+  it('does NOT declare a valid sparse explicit-zone cron impossible', () => {
+    const after = new Date(Date.UTC(2026, 0, 1, 0, 0, 0));
+    // Jan 31 exists — must resolve, not be short-circuited to null.
+    const jan31 = nextFireTime('0 0 31 1 *', after, 'America/New_York');
+    expect(jan31).not.toBeNull();
+    assertDefined(jan31, 'Jan 31 exists, so nextFireTime resolves');
+    const wc = wallClockInZone(jan31, 'America/New_York');
+    expect(wc.hour).toBe(0);
+  });
+
+  it('still finds leap-year Feb 29 (29 is a legal DOM, not impossible)', () => {
+    // 2028 is a leap year. The pre-check uses Feb max = 29 so it does not
+    // wrongly reject Feb 29; the walk then lands on it.
+    const after = new Date(2028, 0, 1, 0, 0, 0);
+    const next = nextFireTime('0 0 29 2 *', after);
+    expect(next).not.toBeNull();
+    assertDefined(next, 'Feb 29 in a leap year resolves');
+    expect(next.getMonth()).toBe(1); // February
+    expect(next.getDate()).toBe(29);
+  });
+
+  it('does NOT treat an impossible-DOM cron as impossible when DOW is restricted (OR-semantics)', () => {
+    // `0 0 30 2 5` = (Feb 30, never) OR (any Friday). The Friday arm makes it
+    // perfectly reachable; the pre-check must NOT short-circuit it to null.
+    const after = new Date(2026, 0, 1, 0, 0, 0);
+    const next = nextFireTime('0 0 30 2 5', after);
+    expect(next).not.toBeNull();
+    assertDefined(next, 'the Friday (DOW) arm makes this reachable');
+    expect(next.getDay()).toBe(5); // matched via the Friday (DOW) arm
+  });
+
+  // Worst case: a non-IANA timeZone must NOT throw a RangeError out of
+  // nextFireTime (which would abort the whole poller tick) — it returns null
+  // (treated as "never due") instead.
+  it('returns null instead of throwing for a non-IANA timeZone', () => {
+    const after = new Date(Date.UTC(2026, 4, 11, 0, 0, 0));
+    expect(() => nextFireTime('0 9 * * *', after, 'Mars/Phobos')).not.toThrow();
+    expect(nextFireTime('0 9 * * *', after, 'Mars/Phobos')).toBeNull();
+    // Other non-IANA strings are rejected the same way.
+    expect(nextFireTime('0 9 * * *', after, 'Not/AZone')).toBeNull();
+    expect(nextFireTime('0 9 * * *', after, '')).toBeNull();
+  });
+});
+
+describe('isValidTimeZone', () => {
+  it('accepts undefined / local / real IANA zones', () => {
+    expect(isValidTimeZone(undefined)).toBe(true);
+    expect(isValidTimeZone('local')).toBe(true);
+    expect(isValidTimeZone('UTC')).toBe(true);
+    expect(isValidTimeZone('America/New_York')).toBe(true);
+    expect(isValidTimeZone('Asia/Tokyo')).toBe(true);
+  });
+
+  it('rejects non-IANA strings that would make Intl throw', () => {
+    expect(isValidTimeZone('Mars/Phobos')).toBe(false);
+    expect(isValidTimeZone('Not/AZone')).toBe(false);
+    expect(isValidTimeZone('')).toBe(false);
+  });
+});

package/src/cron.ts

@@ -0,0 +1,355 @@
+/**
+ * Tiny POSIX-style 5-field cron parser.
+ *
+ *   ┌───────────── minute        (0-59)
+ *   │ ┌─────────── hour          (0-23)
+ *   │ │ ┌───────── day-of-month  (1-31)
+ *   │ │ │ ┌─────── month         (1-12)
+ *   │ │ │ │ ┌───── day-of-week   (0-6, Sunday=0)
+ *   * * * * *
+ *
+ * Each field supports:
+ *   - `*`           — any value in range
+ *   - `n`           — literal
+ *   - `a-b`         — inclusive range
+ *   - `a,b,c`       — list
+ *   - `*\/n`         — every n
+ *   - `a-b/n`       — every n within a range
+ *
+ * `nextFireTime(expr, after)` walks forward minute-by-minute (with cheap
+ * field-by-field jumps) until every field matches, capped at a year
+ * lookahead. Returns null if no fire is reachable (impossible expression
+ * like `0 0 31 2 *`).
+ *
+ * Standard cron quirk: when both DOM and DOW are restricted, vixie-cron
+ * matches on EITHER. We follow that convention.
+ */
+
+import { assertDefined } from './assert.js';
+
+interface FieldSpec {
+  readonly values: ReadonlySet<number>;
+  readonly restricted: boolean;
+}
+
+export interface ParsedCron {
+  readonly minute: FieldSpec;
+  readonly hour: FieldSpec;
+  readonly dom: FieldSpec;
+  readonly month: FieldSpec;
+  readonly dow: FieldSpec;
+}
+
+interface FieldRange {
+  readonly min: number;
+  readonly max: number;
+}
+
+const FIELD_RANGES: Record<keyof ParsedCron, FieldRange> = {
+  minute: { min: 0, max: 59 },
+  hour: { min: 0, max: 23 },
+  dom: { min: 1, max: 31 },
+  month: { min: 1, max: 12 },
+  dow: { min: 0, max: 6 },
+};
+
+function parseField(raw: string, range: FieldRange, fieldName: string): FieldSpec {
+  const values = new Set<number>();
+  const restricted = raw !== '*' && !raw.startsWith('*/');
+  for (const piece of raw.split(',')) {
+    const [rangePart, stepPart] = piece.split('/');
+    if (rangePart === undefined) throw new Error(`empty term in ${fieldName}: "${raw}"`);
+    const step = stepPart ? toIntStrict(stepPart, fieldName) : 1;
+    if (step < 1) throw new Error(`step must be >= 1 in ${fieldName}: "${raw}"`);
+
+    let lo: number;
+    let hi: number;
+    if (rangePart === '*') {
+      lo = range.min;
+      hi = range.max;
+    } else if (rangePart.includes('-')) {
+      const [a, b] = rangePart.split('-');
+      // A string containing '-' always splits into >= 2 parts, so both bounds
+      // are present by construction (empty strings are caught by toIntStrict).
+      assertDefined(a, 'range lower bound (rangePart contains "-")');
+      assertDefined(b, 'range upper bound (rangePart contains "-")');
+      lo = toIntStrict(a, fieldName);
+      hi = toIntStrict(b, fieldName);
+    } else {
+      lo = toIntStrict(rangePart, fieldName);
+      hi = lo;
+    }
+    if (lo < range.min || hi > range.max || lo > hi) {
+      throw new Error(
+        `out-of-range term "${piece}" in ${fieldName} (allowed ${range.min}-${range.max})`,
+      );
+    }
+    for (let v = lo; v <= hi; v += step) values.add(v);
+  }
+  return { values, restricted };
+}
+
+function toIntStrict(s: string, fieldName: string): number {
+  if (!/^-?\d+$/.test(s)) throw new Error(`non-integer "${s}" in ${fieldName}`);
+  return Number(s);
+}
+
+export function parseCron(expr: string): ParsedCron {
+  const fields = expr.trim().split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error(`cron expression must have 5 fields, got ${fields.length}: "${expr}"`);
+  }
+  const [minute, hour, dom, month, dow] = fields as [string, string, string, string, string];
+  return {
+    minute: parseField(minute, FIELD_RANGES.minute, 'minute'),
+    hour: parseField(hour, FIELD_RANGES.hour, 'hour'),
+    dom: parseField(dom, FIELD_RANGES.dom, 'dom'),
+    month: parseField(month, FIELD_RANGES.month, 'month'),
+    dow: parseField(dow, FIELD_RANGES.dow, 'dow'),
+  };
+}
+
+export function isValidCron(expr: string): boolean {
+  try {
+    parseCron(expr);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Calendar maximum day-of-month per month (1-12). February uses 29 to allow
+// leap-year Feb 29 fires; non-leap years are then handled by the normal walk.
+const MAX_DOM_BY_MONTH: Record<number, number> = {
+  1: 31, 2: 29, 3: 31, 4: 30, 5: 31, 6: 30,
+  7: 31, 8: 31, 9: 30, 10: 31, 11: 30, 12: 31,
+};
+
+/**
+ * Cheap, zone-independent structural-impossibility check. Some cron
+ * expressions can never fire because their day-of-month is larger than every
+ * candidate month allows (e.g. `0 0 30 2 *` — Feb never has a 30th, or
+ * `0 0 31 4 *` — April has no 31st). Without this, an explicit-IANA-zone walk
+ * for such an expression advances minute-by-minute through the full 366-day cap
+ * (~527k `Intl.formatToParts` calls, ~2s of blocked event loop) only to return
+ * null. The DOM/DOW OR-semantics quirk means this is only safe to declare
+ * impossible when DOW is unrestricted (`*`): if DOW is restricted the day can
+ * still match via the weekday arm regardless of DOM. We check exactly the case
+ * the walk is slowest on — a restricted DOM whose smallest value exceeds the
+ * largest day any selected month can hold — and bail to "no fire" instantly.
+ */
+function isStructurallyImpossible(cron: ParsedCron): boolean {
+  // OR-semantics: a restricted DOW can satisfy the day on its own, so DOM being
+  // unreachable does not make the expression impossible. Only decide when DOW
+  // is unrestricted (every weekday allowed) and DOM is restricted.
+  if (cron.dow.restricted || !cron.dom.restricted) return false;
+  const minDom = Math.min(...cron.dom.values);
+  let maxAllowed = 0;
+  for (const month of cron.month.values) {
+    const cap = MAX_DOM_BY_MONTH[month] ?? 31;
+    if (cap > maxAllowed) maxAllowed = cap;
+  }
+  // If the smallest requested day-of-month is larger than the biggest day any
+  // selected month can ever hold, no instant can match — impossible.
+  return minDom > maxAllowed;
+}
+
+/**
+ * Whether `tz` is an IANA zone the runtime's `Intl` accepts. A non-IANA
+ * string (e.g. 'PST', 'Mars/Phobos') makes `Intl.DateTimeFormat` throw a
+ * RangeError. `nextFireTime` would otherwise inherit that throw deep inside
+ * the poller tick (outside its per-entry try/catch), aborting evaluation of
+ * every schedule positioned after the bad one. We reject the zone at the
+ * trust boundary instead. `undefined`/'local' mean system-local (always ok).
+ */
+export function isValidTimeZone(tz: string | undefined): boolean {
+  if (tz === undefined || tz === 'local') return true;
+  try {
+    new Intl.DateTimeFormat(undefined, { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Minute-precision walk forward from `after` (exclusive) until every
+ * field matches. Operates in the caller-supplied IANA timezone via
+ * `Intl.DateTimeFormat` — defaults to system local. The walk is
+ * bounded at 1-year so a structurally-impossible expression returns
+ * null instead of looping forever.
+ */
+export function nextFireTime(
+  expr: string,
+  after: Date,
+  timeZone?: string,
+): Date | null {
+  const cron = parseCron(expr);
+  // Defense in depth: a malformed/legacy timeZone that slipped past the
+  // trust-boundary validation would make `Intl.DateTimeFormat` throw deep in
+  // the walk — outside the poller's per-entry guard, which would abort every
+  // later schedule's evaluation. Treat an unusable zone as "no reachable fire"
+  // (null) so the entry is simply never due, matching how callers handle null.
+  if (!isValidTimeZone(timeZone)) return null;
+  // Bail instantly on a structurally-impossible expression (e.g. Feb 30,
+  // Apr 31) BEFORE the walk. For an explicit IANA zone the walk would
+  // otherwise advance minute-by-minute through the full 366-day cap (~527k
+  // `Intl.formatToParts` calls, ~2s of blocked event loop) just to return
+  // null — a self-inflicted DoS one typo'd skill could trigger every time its
+  // baseline changes. This check is calendar-fact-only, so it is correct in
+  // any zone.
+  if (isStructurallyImpossible(cron)) return null;
+  // Start at after + 1 minute, zero seconds.
+  const start = new Date(after.getTime() + 60_000);
+  start.setSeconds(0, 0);
+  const limit = new Date(start.getTime() + 366 * 24 * 60 * 60_000);
+
+  // The field-by-field jump helpers mutate the cursor with system-local
+  // `Date` methods, so they are only correct when matching is also done in
+  // the host's local zone. For an explicit (non-local) IANA zone we walk
+  // minute-by-minute on the absolute instant instead — slower, but advancing
+  // the cursor by a fixed 60_000 ms is zone-independent, whereas the local
+  // setHours/setDate jumps would land on the wrong wall-clock instant in the
+  // target zone (off-by-offset / DST errors). The 1-year cap still bounds it.
+  const explicitZone = !!timeZone && timeZone !== 'local';
+
+  const cursor = new Date(start);
+  while (cursor <= limit) {
+    const parts = decomposeInZone(cursor, timeZone);
+    if (!cron.month.values.has(parts.month)) {
+      if (explicitZone) {
+        cursor.setTime(cursor.getTime() + 60_000);
+      } else {
+        // Jump to the first day of the next candidate month.
+        jumpToNextMonth(cursor, parts, cron.month.values, timeZone);
+      }
+      continue;
+    }
+    const domOk = cron.dom.values.has(parts.dom);
+    const dowOk = cron.dow.values.has(parts.dow);
+    // Vixie-cron OR semantics when both DOM and DOW are restricted.
+    const dayMatches = cron.dom.restricted && cron.dow.restricted
+      ? domOk || dowOk
+      : domOk && dowOk;
+    if (!dayMatches) {
+      if (explicitZone) cursor.setTime(cursor.getTime() + 60_000);
+      else jumpToNextDay(cursor, timeZone);
+      continue;
+    }
+    if (!cron.hour.values.has(parts.hour)) {
+      if (explicitZone) cursor.setTime(cursor.getTime() + 60_000);
+      else jumpToNextHour(cursor, timeZone);
+      continue;
+    }
+    if (!cron.minute.values.has(parts.minute)) {
+      if (explicitZone) cursor.setTime(cursor.getTime() + 60_000);
+      else cursor.setMinutes(cursor.getMinutes() + 1, 0, 0);
+      continue;
+    }
+    return new Date(cursor.getTime());
+  }
+  return null;
+}
+
+interface DateParts {
+  readonly year: number;
+  readonly month: number; // 1-12
+  readonly dom: number; // 1-31
+  readonly dow: number; // 0=Sunday
+  readonly hour: number;
+  readonly minute: number;
+}
+
+// Memoized Intl.DateTimeFormat per IANA zone. Formatters are stateless, so
+// caching them across the (potentially long) minute-walk avoids re-allocating
+// one on every cursor step for explicit-zone crons.
+const formatterCache = new Map<string, Intl.DateTimeFormat>();
+
+function formatterFor(timeZone: string): Intl.DateTimeFormat {
+  let fmt = formatterCache.get(timeZone);
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat('en-US', {
+      timeZone,
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      weekday: 'short',
+      hour: '2-digit',
+      minute: '2-digit',
+      hour12: false,
+    });
+    formatterCache.set(timeZone, fmt);
+  }
+  return fmt;
+}
+
+function decomposeInZone(d: Date, timeZone?: string): DateParts {
+  // Local time decomposition. We deliberately default to system-local —
+  // a user saying "every day at 9 AM" overwhelmingly means their wall
+  // clock, not UTC. Callers that need UTC pass timeZone='UTC'.
+  if (!timeZone || timeZone === 'local') {
+    return {
+      year: d.getFullYear(),
+      month: d.getMonth() + 1,
+      dom: d.getDate(),
+      dow: d.getDay(),
+      hour: d.getHours(),
+      minute: d.getMinutes(),
+    };
+  }
+  // Intl-based decomposition for explicit zones. A formatter is stateless,
+  // so memoize one per IANA zone — `nextFireTime` can walk many minute steps
+  // for a sparse cron and was previously allocating a fresh formatter on each
+  // step. Correctness is unchanged; only the per-step allocation is removed.
+  const fmt = formatterFor(timeZone);
+  const parts: Record<string, string> = {};
+  for (const part of fmt.formatToParts(d)) parts[part.type] = part.value;
+  const weekdayMap: Record<string, number> = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+  // The formatter is configured with `weekday: 'short'`, so formatToParts
+  // always emits a weekday part, so its presence is impossible by construction.
+  const weekday = parts.weekday;
+  assertDefined(weekday, 'formatToParts includes weekday (formatter sets weekday: short)');
+  return {
+    year: Number(parts.year),
+    month: Number(parts.month),
+    dom: Number(parts.day),
+    dow: weekdayMap[weekday] ?? 0,
+    hour: Number(parts.hour) % 24,
+    minute: Number(parts.minute),
+  };
+}
+
+function jumpToNextMonth(
+  cursor: Date,
+  current: DateParts,
+  validMonths: ReadonlySet<number>,
+  _timeZone?: string,
+): void {
+  // Find next valid month >= current+1; wraps to next year if needed.
+  let nextMonth = current.month + 1;
+  let yearDelta = 0;
+  while (!validMonths.has(((nextMonth - 1) % 12) + 1)) {
+    nextMonth += 1;
+    if (nextMonth > 24) {
+      // Pathological: walk hit a wall. Caller's outer loop will give up
+      // at the 1-year limit.
+      cursor.setFullYear(cursor.getFullYear() + 1);
+      return;
+    }
+  }
+  while (nextMonth > 12) {
+    nextMonth -= 12;
+    yearDelta += 1;
+  }
+  cursor.setFullYear(cursor.getFullYear() + yearDelta, nextMonth - 1, 1);
+  cursor.setHours(0, 0, 0, 0);
+}
+
+function jumpToNextDay(cursor: Date, _timeZone?: string): void {
+  cursor.setDate(cursor.getDate() + 1);
+  cursor.setHours(0, 0, 0, 0);
+}
+
+function jumpToNextHour(cursor: Date, _timeZone?: string): void {
+  cursor.setHours(cursor.getHours() + 1, 0, 0, 0);
+}

package/src/define.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { z } from 'zod';
+import { z } from 'zod/v3';
 import {
   defineCompactor,
   defineMode,

package/src/define.ts

@@ -17,7 +17,7 @@ import type { SynthesizerDef } from './synthesizer.js';
 import type { ViewRendererDef } from './view-renderer.js';
 import type { TunnelProviderDef } from './tunnel.js';
 import type { WorkflowExecutorDef } from './workflow.js';
-import type { z } from 'zod';
+import type { z } from 'zod/v3';
 
 export function definePlugin(spec: PluginSpec): Plugin {
   // Spread spec first so the defaults below can't be clobbered by an
@@ -52,6 +52,7 @@ export function defineTool<S extends z.ZodTypeAny, O = unknown>(spec: {
   liveState?: boolean;
   alwaysLoaded?: boolean;
   modes?: ReadonlyArray<string>;
+  notInModes?: ReadonlyArray<string>;
   refusalEndsTurn?: string;
 }): ToolDef {
   return Object.freeze({
@@ -70,6 +71,7 @@ export function defineTool<S extends z.ZodTypeAny, O = unknown>(spec: {
     ...(spec.alwaysLoaded ? { alwaysLoaded: true } : {}),
     ...(spec.refusalEndsTurn !== undefined ? { refusalEndsTurn: spec.refusalEndsTurn } : {}),
     ...(spec.modes ? { modes: Object.freeze([...spec.modes]) } : {}),
+    ...(spec.notInModes ? { notInModes: Object.freeze([...spec.notInModes]) } : {}),
   });
 }
 

package/src/event-store.ts

@@ -19,6 +19,7 @@ export const SESSION_SOURCES = [
   'cli',
   'tui',
   'desktop',
+  // The mobile app was removed; kept so sessions it recorded still read back.
   'mobile',
   'slack',
   'telegram',
@@ -34,7 +35,7 @@ export type SessionSource = (typeof SESSION_SOURCES)[number];
 /**
  * The single per-session metadata record (the JSONL impl writes it to
  * `~/.moxxy/sessions/<id>.json`). ONE per session — the unit every surface
- * (TUI/desktop/mobile) lists, searches and caches; the conversation itself is
+ * (TUI/desktop) lists, searches and caches; the conversation itself is
  * the append-only event stream. Fields split by owner: the runner owns the
  * content fields (`firstPrompt`/`eventCount`/`lastActivity`/`provider`/`model`/
  * `startedAt`/`source`); the UI owns `title` (rename) and `groupId` (desk).