@j13b/scheduler 0.1.0 → 0.1.1

package/src/__tests__/validate_rule.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, test } from "vitest";
+import { InMemorySchedulerPort } from "../in_memory_port.js";
+import { Scheduler } from "../scheduler.js";
+import type { RecurrenceRule } from "../types.js";
+import { RULE_KINDS, validateRule, validateTimeSpan } from "../validate_rule.js";
+
+const START = Date.UTC(2026, 0, 1);
+const SEVEN_AM = 7 * 60 * 60 * 1000;
+
+// A rule as it arrives from JSON: anything at all.
+const loose = (rule: unknown): RecurrenceRule => rule as RecurrenceRule;
+
+const VALID: RecurrenceRule[] = [
+  { kind: "instant", startOn: START },
+  { kind: "localDateTime", year: 2026, month: 0, day: 1, timeOfDay: SEVEN_AM },
+  { kind: "anchored", anchorDate: START, intervalMs: 1000, seriesStart: START, seriesEnd: null },
+  {
+    kind: "daysOfWeek",
+    days: [1],
+    weekInterval: 1,
+    timeOfDay: 0,
+    seriesStart: START,
+    seriesEnd: null,
+  },
+  {
+    kind: "weeksOfMonth",
+    days: [0],
+    weeks: [1, 3],
+    monthInterval: 1,
+    timeOfDay: SEVEN_AM,
+    seriesStart: START,
+    seriesEnd: null,
+  },
+  {
+    kind: "monthsOfYear",
+    months: [10],
+    weeks: [4],
+    days: [4],
+    yearInterval: 1,
+    timeOfDay: 0,
+    seriesStart: START,
+    seriesEnd: null,
+    count: 3,
+  },
+  {
+    kind: "yearly",
+    month: 6,
+    day: 4,
+    yearInterval: 1,
+    timeOfDay: 0,
+    seriesStart: START,
+    seriesEnd: null,
+  },
+  {
+    kind: "daysOfMonth",
+    months: [0, 1],
+    daysOfMonth: [1, 15],
+    yearInterval: 1,
+    timeOfDay: 0,
+    seriesStart: START,
+    seriesEnd: START + 1,
+    timeSpan: { type: "duration", ms: 60_000 },
+  },
+  {
+    kind: "daysOfYear",
+    daysOfYear: [1, 366],
+    yearInterval: 1,
+    timeOfDay: 0,
+    seriesStart: START,
+    seriesEnd: null,
+  },
+];
+
+describe("validateRule accepts", () => {
+  test.each(VALID.map((r) => [r.kind, r] as const))("a whole %s rule", (_kind, rule) => {
+    expect(() => validateRule(rule)).not.toThrow();
+  });
+
+  test("every kind is covered here", () => {
+    expect(VALID.map((r) => r.kind).sort()).toEqual([...RULE_KINDS].sort());
+  });
+});
+
+// The rules an LLM sent for "the 1st and 3rd Sunday at 7am". Before, each one
+// crashed inside the scheduler ("Cannot read properties of undefined", "Invalid
+// time value"); now each names what is wrong.
+describe("validateRule names the field that is wrong", () => {
+  test("a field the kind does not have", () => {
+    expect(() =>
+      validateRule(loose({ kind: "weeksOfMonth", weeks: [1, 3], weekdays: [0] }))
+    ).toThrow(
+      'WeeksOfMonthRule has no field "weekdays" (its fields are: days, weeks, monthInterval'
+    );
+  });
+
+  test("a required field that is missing, with the form it expects", () => {
+    expect(() => validateRule(loose({ kind: "weeksOfMonth", weeks: [1, 3], days: [0] }))).toThrow(
+      "WeeksOfMonthRule.monthInterval is required: a whole number >= 1 (1 = every month)"
+    );
+    expect(() =>
+      validateRule(loose({ kind: "weeksOfMonth", weeks: [1, 3], days: [0], monthInterval: 1 }))
+    ).toThrow("WeeksOfMonthRule.timeOfDay is required: ms after local midnight");
+    expect(() =>
+      validateRule(
+        loose({
+          kind: "weeksOfMonth",
+          weeks: [1, 3],
+          days: [0],
+          monthInterval: 1,
+          timeOfDay: SEVEN_AM,
+        })
+      )
+    ).toThrow("WeeksOfMonthRule.seriesStart is required: a UTC timestamp in ms");
+    expect(() =>
+      validateRule(
+        loose({
+          kind: "weeksOfMonth",
+          weeks: [1, 3],
+          days: [0],
+          monthInterval: 1,
+          timeOfDay: SEVEN_AM,
+          seriesStart: START,
+        })
+      )
+    ).toThrow("WeeksOfMonthRule.seriesEnd is required: a UTC timestamp in ms or null (no end)");
+  });
+
+  test("a wrong type or value", () => {
+    const base = VALID[4] as unknown as Record<string, unknown>;
+
+    expect(() => validateRule(loose({ ...base, days: [] }))).toThrow(
+      "WeeksOfMonthRule.days must be a non-empty array"
+    );
+    expect(() => validateRule(loose({ ...base, days: 0 }))).toThrow(
+      "WeeksOfMonthRule.days must be a non-empty array"
+    );
+    expect(() => validateRule(loose({ ...base, days: [7] }))).toThrow("7 is out of range");
+    expect(() => validateRule(loose({ ...base, weeks: [0] }))).toThrow("0 is out of range");
+    expect(() => validateRule(loose({ ...base, timeOfDay: "07:00" }))).toThrow(
+      "WeeksOfMonthRule.timeOfDay must be ms after local midnight"
+    );
+    expect(() => validateRule(loose({ ...base, seriesStart: "2026-01-01" }))).toThrow(
+      "seriesStart must be a UTC timestamp"
+    );
+    expect(() => validateRule(loose({ ...base, count: -1 }))).toThrow(
+      "count must be a whole number >= 0 or null"
+    );
+    expect(() => validateRule(loose({ ...base, seriesEnd: START }))).toThrow(
+      "seriesEnd must be > seriesStart"
+    );
+  });
+
+  test("an unknown kind, or no rule at all", () => {
+    expect(() => validateRule(loose({ kind: "monthly" }))).toThrow(
+      'Unknown rule kind "monthly" (expected one of instant,'
+    );
+    expect(() => validateRule(loose(null))).toThrow('A rule must be an object with a "kind"');
+  });
+});
+
+describe("validateTimeSpan", () => {
+  test("accepts nothing, a duration, or an hour span", () => {
+    expect(() => validateTimeSpan(undefined)).not.toThrow();
+    expect(() => validateTimeSpan({ type: "duration", ms: 1 })).not.toThrow();
+    expect(() => validateTimeSpan({ type: "hourSpan", hours: 1.5 })).not.toThrow();
+  });
+
+  test("rejects anything else with the forms it takes", () => {
+    expect(() => validateTimeSpan({ ms: 5 })).toThrow('timeSpan must be { "type": "duration"');
+    expect(() => validateTimeSpan({ type: "duration", ms: 0 })).toThrow("timeSpan.ms must be >= 1");
+  });
+});
+
+describe("the scheduler refuses a malformed rule before storing it", () => {
+  test("add throws the field message and stores nothing", async () => {
+    const port = new InMemorySchedulerPort<{ type: "event" }>();
+    const scheduler = new Scheduler(port);
+
+    await expect(
+      scheduler.add({
+        id: "t1",
+        rule: loose({ kind: "weeksOfMonth", weeks: [1, 3], weekdays: [0] }),
+        timezone: "UTC",
+        payload: { type: "event" },
+      })
+    ).rejects.toThrow('has no field "weekdays"');
+
+    expect(await port.getTemplate("t1")).toBeNull();
+  });
+});

package/src/index.ts

@@ -22,3 +22,4 @@ export {
   type TimeSpan,
   type Disambiguation,
 } from "./types.js";
+export { RULE_KINDS, validateRule, validateTimeSpan } from "./validate_rule.js";

package/src/scheduler.ts

@@ -21,6 +21,7 @@ import type {
   TimeSpan,
 } from "./types.js";
 import { isValidTimeZone } from "./tz.js";
+import { validateRule, validateTimeSpan } from "./validate_rule.js";
 
 const DAY_MS = 24 * 60 * 60 * 1000;
 // Search horizon for next() / nextDue() before giving up. Five years covers
@@ -185,7 +186,7 @@ export class Scheduler<TPayload extends { type: string }> {
     newTimeSpan?: TimeSpan,
     payloadOverride?: Partial<TPayload>
   ): Promise<string> {
-    if (newTimeSpan != null) _validateTimeSpan(newTimeSpan);
+    if (newTimeSpan != null) validateTimeSpan(newTimeSpan);
     const id = `alt-${templateId}-${occurrenceKey}-${Date.now()}`;
     await this._removeExistingAlteration(templateId, occurrenceKey);
     const alt: Alteration<TPayload> = {
@@ -277,138 +278,6 @@ export class Scheduler<TPayload extends { type: string }> {
 
 // ─── Validation ───────────────────────────────────────────────
 
-export function validateRule(rule: RecurrenceRule): void {
-  switch (rule.kind) {
-    case "instant":
-      _validateTimeSpan(rule.timeSpan);
-      return;
-    case "localDateTime":
-      if (!Number.isInteger(rule.year)) {
-        throw new Error("LocalDateTimeRule.year must be an integer");
-      }
-      if (rule.month < 0 || rule.month > 11) {
-        throw new Error("LocalDateTimeRule.month must be in 0..11");
-      }
-      if (rule.day < 1 || rule.day > 31) throw new Error("LocalDateTimeRule.day must be in 1..31");
-      _validateTimeOfDay(rule.timeOfDay);
-      _validateTimeSpan(rule.timeSpan);
-      return;
-    case "anchored":
-      if (rule.intervalMs <= 0) throw new Error("AnchoredRule.intervalMs must be > 0");
-      _validateTimeSpan(rule.timeSpan);
-      _validateSeries(rule.seriesStart, rule.seriesEnd, rule.count);
-      return;
-    case "daysOfWeek":
-      if (rule.weekInterval <= 0) throw new Error("DaysOfWeekRule.weekInterval must be > 0");
-      if (rule.days.length === 0) throw new Error("DaysOfWeekRule.days must be non-empty");
-      _validateTimeOfDay(rule.timeOfDay);
-      _validateTimeSpan(rule.timeSpan);
-      _validateSeries(rule.seriesStart, rule.seriesEnd, rule.count);
-      return;
-    case "weeksOfMonth":
-      if (rule.monthInterval <= 0) throw new Error("WeeksOfMonthRule.monthInterval must be > 0");
-      if (rule.weeks.length === 0) throw new Error("WeeksOfMonthRule.weeks must be non-empty");
-      for (const w of rule.weeks) {
-        if (w === 0 || w < -5 || w > 5) {
-          throw new Error("WeeksOfMonthRule.weeks entries must be in [-5..-1] or [1..5]");
-        }
-      }
-      if (rule.days.length === 0) throw new Error("WeeksOfMonthRule.days must be non-empty");
-      _validateTimeOfDay(rule.timeOfDay);
-      _validateTimeSpan(rule.timeSpan);
-      _validateSeries(rule.seriesStart, rule.seriesEnd, rule.count);
-      return;
-    case "monthsOfYear":
-      if (rule.yearInterval <= 0) throw new Error("MonthsOfYearRule.yearInterval must be > 0");
-      if (rule.months.length === 0) throw new Error("MonthsOfYearRule.months must be non-empty");
-      for (const m of rule.months) {
-        if (m < 0 || m > 11) {
-          throw new Error("MonthsOfYearRule.months entries must be in 0..11");
-        }
-      }
-      if (rule.weeks.length === 0) throw new Error("MonthsOfYearRule.weeks must be non-empty");
-      for (const w of rule.weeks) {
-        if (w === 0 || w < -5 || w > 5) {
-          throw new Error("MonthsOfYearRule.weeks entries must be in [-5..-1] or [1..5]");
-        }
-      }
-      if (rule.days.length === 0) throw new Error("MonthsOfYearRule.days must be non-empty");
-      _validateTimeOfDay(rule.timeOfDay);
-      _validateTimeSpan(rule.timeSpan);
-      _validateSeries(rule.seriesStart, rule.seriesEnd, rule.count);
-      return;
-    case "yearly":
-      if (rule.yearInterval <= 0) throw new Error("YearlyRule.yearInterval must be > 0");
-      if (rule.month < 0 || rule.month > 11) {
-        throw new Error("YearlyRule.month must be in 0..11");
-      }
-      if (rule.day < 1 || rule.day > 31) throw new Error("YearlyRule.day must be in 1..31");
-      _validateTimeOfDay(rule.timeOfDay);
-      _validateTimeSpan(rule.timeSpan);
-      _validateSeries(rule.seriesStart, rule.seriesEnd, rule.count);
-      return;
-    case "daysOfMonth":
-      if (rule.yearInterval <= 0) throw new Error("DaysOfMonthRule.yearInterval must be > 0");
-      if (rule.months.length === 0) throw new Error("DaysOfMonthRule.months must be non-empty");
-      for (const m of rule.months) {
-        if (m < 0 || m > 11) {
-          throw new Error("DaysOfMonthRule.months entries must be in 0..11");
-        }
-      }
-      if (rule.daysOfMonth.length === 0) {
-        throw new Error("DaysOfMonthRule.daysOfMonth must be non-empty");
-      }
-      for (const d of rule.daysOfMonth) {
-        if (d < 1 || d > 31) {
-          throw new Error("DaysOfMonthRule.daysOfMonth entries must be in 1..31");
-        }
-      }
-      _validateTimeOfDay(rule.timeOfDay);
-      _validateTimeSpan(rule.timeSpan);
-      _validateSeries(rule.seriesStart, rule.seriesEnd, rule.count);
-      return;
-    case "daysOfYear":
-      if (rule.yearInterval <= 0) throw new Error("DaysOfYearRule.yearInterval must be > 0");
-      if (rule.daysOfYear.length === 0) {
-        throw new Error("DaysOfYearRule.daysOfYear must be non-empty");
-      }
-      for (const d of rule.daysOfYear) {
-        if (d < 1 || d > 366) {
-          throw new Error("DaysOfYearRule.daysOfYear entries must be in 1..366");
-        }
-      }
-      _validateTimeOfDay(rule.timeOfDay);
-      _validateTimeSpan(rule.timeSpan);
-      _validateSeries(rule.seriesStart, rule.seriesEnd, rule.count);
-      return;
-    default: {
-      const _exhaustive: never = rule;
-      throw new Error(`Unknown rule kind: ${JSON.stringify(_exhaustive)}`);
-    }
-  }
-}
-
-// Validates the TimeSpan shape. Throws on { type: "duration", ms < 1 } or
-// { type: "hourSpan", hours <= 0 }. Undefined is valid (defaults to 1ms).
-function _validateTimeSpan(span: TimeSpan | undefined): void {
-  if (span == null) return;
-  if (span.type === "duration") {
-    if (span.ms < 1) {
-      throw new Error(`timeSpan.ms must be >= 1 if supplied (got ${span.ms})`);
-    }
-    return;
-  }
-  if (span.type === "hourSpan") {
-    if (!Number.isFinite(span.hours) || span.hours <= 0) {
-      throw new Error(`timeSpan.hours must be > 0 (got ${span.hours})`);
-    }
-    return;
-  }
-  // Exhaustiveness — TS will flag a missing case if TimeSpan grows.
-  const _exhaustive: never = span;
-  throw new Error(`Unknown TimeSpan type: ${JSON.stringify(_exhaustive)}`);
-}
-
 // Returns a copy of `rule` with timeSpan defaulted when omitted, so
 // generators don't have to handle undefined repeatedly.
 function _normalizeRule(rule: RecurrenceRule): RecurrenceRule {
@@ -442,21 +311,6 @@ function _validateDisambiguation(d: Disambiguation | undefined): void {
   }
 }
 
-function _validateTimeOfDay(ms: number): void {
-  if (ms < 0 || ms >= 24 * 60 * 60 * 1000) {
-    throw new Error(`timeOfDay must be in [0, 86_400_000) (got ${ms})`);
-  }
-}
-
-function _validateSeries(
-  start: number,
-  end: number | null,
-  count: number | null | undefined
-): void {
-  if (end != null && end <= start) throw new Error("seriesEnd must be > seriesStart");
-  if (count != null && count < 0) throw new Error("count must be >= 0");
-}
-
 function _rulesEqual(a: RecurrenceRule, b: RecurrenceRule): boolean {
   return JSON.stringify(_canonicalize(a)) === JSON.stringify(_canonicalize(b));
 }

package/src/validate_rule.ts

@@ -0,0 +1,311 @@
+import type { RecurrenceRule, TimeSpan } from "./types.js";
+
+// ─── Rule validation ──────────────────────────────────────────
+//
+// A rule often comes from outside the type system: JSON in a database, a
+// request body, or an LLM tool call. So validation checks the WHOLE shape —
+// every required field present, of the right type, in range, and no fields
+// the kind does not have — and throws an Error that names the field and the
+// form it expects. A bad rule never reaches a generator, where it would crash
+// with "Cannot read properties of undefined" or "Invalid time value".
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const DAYS_HINT = "Day numbers 0..6 (0=Sunday, 1=Monday … 6=Saturday)";
+const MONTHS_HINT = "Month numbers 0..11 (0=January … 11=December)";
+const WEEKS_HINT = "week-of-month numbers 1..5 (1=first) or -1..-5 (-1=last)";
+const TIME_OF_DAY_HINT = "ms after local midnight, 0..86_399_999 (7:00 = 25_200_000)";
+const TIMESTAMP_HINT = "a UTC timestamp in ms";
+
+// One field of a rule kind: whether it must be there, and how to check it.
+interface FieldSpec {
+  required: boolean;
+  check: (value: unknown, field: string) => void;
+}
+
+// The common series fields every repeating kind has.
+const SERIES: Record<string, FieldSpec> = {
+  timeSpan: { required: false, check: (v) => validateTimeSpan(v) },
+  seriesStart: { required: true, check: timestamp },
+  seriesEnd: { required: true, check: nullable(timestamp, "null (no end)") },
+  count: {
+    required: false,
+    check: nullable(int(0, Number.MAX_SAFE_INTEGER, "a whole number >= 0"), "null"),
+  },
+};
+
+const TIME_OF_DAY: FieldSpec = { required: true, check: int(0, DAY_MS - 1, TIME_OF_DAY_HINT) };
+
+const KINDS: Record<RecurrenceRule["kind"], { name: string; fields: Record<string, FieldSpec> }> = {
+  instant: {
+    name: "InstantRule",
+    fields: {
+      startOn: { required: true, check: timestamp },
+      timeSpan: { required: false, check: (v) => validateTimeSpan(v) },
+    },
+  },
+  localDateTime: {
+    name: "LocalDateTimeRule",
+    fields: {
+      year: { required: true, check: int(1, 9999, "a year such as 2026") },
+      month: { required: true, check: int(0, 11, MONTHS_HINT) },
+      day: { required: true, check: int(1, 31, "a day of the month 1..31") },
+      timeOfDay: TIME_OF_DAY,
+      timeSpan: { required: false, check: (v) => validateTimeSpan(v) },
+    },
+  },
+  anchored: {
+    name: "AnchoredRule",
+    fields: {
+      anchorDate: { required: true, check: timestamp },
+      intervalMs: { required: true, check: positive("an interval in ms > 0") },
+      ...SERIES,
+    },
+  },
+  daysOfWeek: {
+    name: "DaysOfWeekRule",
+    fields: {
+      days: { required: true, check: intList(0, 6, DAYS_HINT) },
+      weekInterval: {
+        required: true,
+        check: int(1, Number.MAX_SAFE_INTEGER, "a whole number >= 1 (1 = every week)"),
+      },
+      timeOfDay: TIME_OF_DAY,
+      ...SERIES,
+    },
+  },
+  weeksOfMonth: {
+    name: "WeeksOfMonthRule",
+    fields: {
+      days: { required: true, check: intList(0, 6, DAYS_HINT) },
+      weeks: { required: true, check: weekList },
+      monthInterval: {
+        required: true,
+        check: int(1, Number.MAX_SAFE_INTEGER, "a whole number >= 1 (1 = every month)"),
+      },
+      timeOfDay: TIME_OF_DAY,
+      ...SERIES,
+    },
+  },
+  monthsOfYear: {
+    name: "MonthsOfYearRule",
+    fields: {
+      months: { required: true, check: intList(0, 11, MONTHS_HINT) },
+      weeks: { required: true, check: weekList },
+      days: { required: true, check: intList(0, 6, DAYS_HINT) },
+      yearInterval: {
+        required: true,
+        check: int(1, Number.MAX_SAFE_INTEGER, "a whole number >= 1 (1 = every year)"),
+      },
+      timeOfDay: TIME_OF_DAY,
+      ...SERIES,
+    },
+  },
+  yearly: {
+    name: "YearlyRule",
+    fields: {
+      month: { required: true, check: int(0, 11, MONTHS_HINT) },
+      day: { required: true, check: int(1, 31, "a day of the month 1..31") },
+      yearInterval: {
+        required: true,
+        check: int(1, Number.MAX_SAFE_INTEGER, "a whole number >= 1 (1 = every year)"),
+      },
+      timeOfDay: TIME_OF_DAY,
+      ...SERIES,
+    },
+  },
+  daysOfMonth: {
+    name: "DaysOfMonthRule",
+    fields: {
+      months: { required: true, check: intList(0, 11, MONTHS_HINT) },
+      daysOfMonth: { required: true, check: intList(1, 31, "days of the month 1..31") },
+      yearInterval: {
+        required: true,
+        check: int(1, Number.MAX_SAFE_INTEGER, "a whole number >= 1 (1 = every year)"),
+      },
+      timeOfDay: TIME_OF_DAY,
+      ...SERIES,
+    },
+  },
+  daysOfYear: {
+    name: "DaysOfYearRule",
+    fields: {
+      daysOfYear: { required: true, check: intList(1, 366, "days of the year 1..366") },
+      yearInterval: {
+        required: true,
+        check: int(1, Number.MAX_SAFE_INTEGER, "a whole number >= 1 (1 = every year)"),
+      },
+      timeOfDay: TIME_OF_DAY,
+      ...SERIES,
+    },
+  },
+};
+
+// The rule kinds, in the order the types declare them.
+export const RULE_KINDS = Object.keys(KINDS) as RecurrenceRule["kind"][];
+
+// Throws when `rule` is not a valid RecurrenceRule. The message names the
+// first wrong field and the form it expects.
+export function validateRule(rule: RecurrenceRule): void {
+  const raw: unknown = rule;
+
+  if (typeof raw !== "object" || raw == null || Array.isArray(raw)) {
+    throw new Error(`A rule must be an object with a "kind" (one of ${RULE_KINDS.join(", ")})`);
+  }
+
+  const obj = raw as Record<string, unknown>;
+  const kind = KINDS[obj.kind as RecurrenceRule["kind"]];
+
+  if (kind == null) {
+    throw new Error(
+      `Unknown rule kind ${JSON.stringify(obj.kind)} (expected one of ${RULE_KINDS.join(", ")})`
+    );
+  }
+
+  const known = Object.keys(kind.fields);
+
+  for (const key of Object.keys(obj)) {
+    if (key !== "kind" && !known.includes(key)) {
+      throw new Error(`${kind.name} has no field "${key}" (its fields are: ${known.join(", ")})`);
+    }
+  }
+
+  for (const [field, spec] of Object.entries(kind.fields)) {
+    const label = `${kind.name}.${field}`;
+
+    if (obj[field] === undefined) {
+      if (spec.required) throw new Error(`${label} is required: ${describe(spec, label)}`);
+      continue;
+    }
+
+    spec.check(obj[field], label);
+  }
+
+  const seriesStart = obj.seriesStart as number | undefined;
+  const seriesEnd = obj.seriesEnd as number | null | undefined;
+
+  if (seriesStart != null && seriesEnd != null && seriesEnd <= seriesStart) {
+    throw new Error(`${kind.name}.seriesEnd must be > seriesStart`);
+  }
+}
+
+// Throws when `span` is not a TimeSpan. Undefined is valid (the rule's
+// default span applies).
+export function validateTimeSpan(span: unknown): asserts span is TimeSpan | undefined {
+  if (span === undefined) return;
+
+  const form =
+    '{ "type": "duration", "ms": <ms >= 1> } or { "type": "hourSpan", "hours": <hours > 0> }';
+
+  if (typeof span !== "object" || span == null) {
+    throw new Error(`timeSpan must be ${form}`);
+  }
+
+  const s = span as Record<string, unknown>;
+
+  if (s.type === "duration") {
+    if (typeof s.ms !== "number" || !Number.isFinite(s.ms) || s.ms < 1) {
+      throw new Error(`timeSpan.ms must be >= 1 if supplied (got ${String(s.ms)})`);
+    }
+
+    return;
+  }
+
+  if (s.type === "hourSpan") {
+    if (typeof s.hours !== "number" || !Number.isFinite(s.hours) || s.hours <= 0) {
+      throw new Error(`timeSpan.hours must be > 0 (got ${String(s.hours)})`);
+    }
+
+    return;
+  }
+
+  throw new Error(`timeSpan must be ${form} (got type ${JSON.stringify(s.type)})`);
+}
+
+// ─── Field checks ─────────────────────────────────────────────
+
+// What the field should hold, for "is required" messages: each check is
+// called on undefined and its message reused.
+function describe(spec: FieldSpec, label: string): string {
+  try {
+    spec.check(undefined, label);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const at = msg.indexOf(" must be ");
+
+    if (at >= 0) return msg.slice(at + " must be ".length).replace(/ \(got [^)]*\)$/, "");
+  }
+
+  return "see the rule's type";
+}
+
+function show(v: unknown): string {
+  return v === undefined ? "nothing" : JSON.stringify(v);
+}
+
+function isInt(v: unknown): v is number {
+  return typeof v === "number" && Number.isInteger(v);
+}
+
+function int(min: number, max: number, hint: string) {
+  return (v: unknown, field: string): void => {
+    if (!isInt(v) || v < min || v > max)
+      throw new Error(`${field} must be ${hint} (got ${show(v)})`);
+  };
+}
+
+function positive(hint: string) {
+  return (v: unknown, field: string): void => {
+    if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) {
+      throw new Error(`${field} must be ${hint} (got ${show(v)})`);
+    }
+  };
+}
+
+function timestamp(v: unknown, field: string): void {
+  if (typeof v !== "number" || !Number.isFinite(v)) {
+    throw new Error(`${field} must be ${TIMESTAMP_HINT} (got ${show(v)})`);
+  }
+}
+
+function nullable(check: (v: unknown, field: string) => void, nullHint: string) {
+  return (v: unknown, field: string): void => {
+    if (v === null) return;
+
+    try {
+      check(v, field);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+
+      throw new Error(msg.replace(/ \(got /, ` or ${nullHint} (got `));
+    }
+  };
+}
+
+function intList(min: number, max: number, hint: string) {
+  return (v: unknown, field: string): void => {
+    const form = `a non-empty array of ${hint}`;
+
+    if (!Array.isArray(v) || v.length === 0)
+      throw new Error(`${field} must be ${form} (got ${show(v)})`);
+
+    for (const x of v) {
+      if (!isInt(x) || x < min || x > max) {
+        throw new Error(`${field} must be ${form} (got ${show(v)}; ${show(x)} is out of range)`);
+      }
+    }
+  };
+}
+
+function weekList(v: unknown, field: string): void {
+  const form = `a non-empty array of ${WEEKS_HINT}`;
+
+  if (!Array.isArray(v) || v.length === 0)
+    throw new Error(`${field} must be ${form} (got ${show(v)})`);
+
+  for (const w of v) {
+    if (!isInt(w) || w === 0 || w < -5 || w > 5) {
+      throw new Error(`${field} must be ${form} (got ${show(v)}; ${show(w)} is out of range)`);
+    }
+  }
+}