okengine 0.1.4

package/src/elements/clock/schedule.ts

@@ -0,0 +1,262 @@
+/**
+ * Next-occurrence helpers for cron / every schedules (console §9.6 timeline).
+ *
+ * Supports `every` intervals and simple daily cron (`M H * * *` / `M H * * DOW`).
+ * Complex cron expressions fall back to a single `nextRunAt` when present.
+ */
+
+import { parseDurationMs } from "./duration.ts";
+import { effectiveSchedule, type CronRow } from "./reconcile.ts";
+
+/**
+ * Compute fire times in `[from, until)` for a reconciled cron row.
+ *
+ * @param row - Store row
+ * @param from - Inclusive start epoch-ms
+ * @param until - Exclusive end epoch-ms
+ */
+export function nextOccurrences(
+  row: CronRow,
+  from: number,
+  until: number,
+): readonly number[] {
+  if (row.status !== "active" && row.status !== "paused") return [];
+  if (until <= from) return [];
+
+  const sched = effectiveSchedule(row);
+  if (sched.every) {
+    return nextEveryOccurrences(row, sched.every, from, until);
+  }
+  if (sched.cron) {
+    return nextCronOccurrences(row, sched.cron, sched.timezone, from, until);
+  }
+  return [];
+}
+
+/**
+ * Expected previous fire before `at` (for drift), or `null` when unknown.
+ *
+ * @param row - Store row
+ * @param at - Anchor epoch-ms (usually `lastRunAt` or `now`)
+ */
+export function previousOccurrence(row: CronRow, at: number): number | null {
+  const sched = effectiveSchedule(row);
+  if (sched.every) {
+    const interval = parseDurationMs(sched.every);
+    if (interval <= 0) return null;
+    if (row.lastRunAt === undefined) return null;
+    // Floor to the slot boundary at or before `at`.
+    const origin = row.lastRunAt % interval;
+    const slot = at - ((at - origin) % interval);
+    return slot > 0 ? slot : null;
+  }
+  if (sched.cron) {
+    const parsed = parseSimpleDaily(sched.cron);
+    if (!parsed) return null;
+    // Walk back up to 400 days for a prior civil fire.
+    for (let day = 1; day <= 400; day++) {
+      const probe = at - day * 86_400_000;
+      const local = zonedParts(probe, sched.timezone);
+      if (local.hour === parsed.hour && local.minute === parsed.minute) {
+        // Align to that local wall time's UTC instant near `probe`.
+        const fires = civilFiresOnDay(local.date, parsed, sched.timezone);
+        const prior = fires.filter((t) => t <= at).pop();
+        if (prior !== undefined) return prior;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Count schedule slots strictly after `from` and at or before `until`.
+ *
+ * @param row - Store row
+ * @param from - Exclusive lower bound (usually lastRunAt)
+ * @param until - Inclusive upper bound (usually now)
+ */
+export function countMissedOccurrences(
+  row: CronRow,
+  from: number,
+  until: number,
+): number {
+  if (until <= from) return 0;
+  const sched = effectiveSchedule(row);
+  if (sched.every) {
+    const interval = parseDurationMs(sched.every);
+    if (interval <= 0) return 0;
+    return Math.max(0, Math.floor((until - from) / interval) - 0);
+  }
+  if (sched.cron) {
+    // Count fires in (from, until].
+    const fires = nextCronOccurrences(row, sched.cron, sched.timezone, from + 1, until + 1);
+    return fires.filter((t) => t > from && t <= until).length;
+  }
+  return 0;
+}
+
+function nextEveryOccurrences(
+  row: CronRow,
+  every: string,
+  from: number,
+  until: number,
+): readonly number[] {
+  const interval = parseDurationMs(every);
+  if (interval <= 0) return [];
+  const out: number[] = [];
+  let t =
+    row.nextRunAt !== undefined && row.nextRunAt >= from
+      ? row.nextRunAt
+      : row.lastRunAt !== undefined
+        ? row.lastRunAt + interval
+        : from;
+  // If still in the past relative to `from`, advance to first >= from.
+  while (t < from) t += interval;
+  while (t < until) {
+    out.push(t);
+    t += interval;
+    if (out.length > 10_000) break;
+  }
+  return out;
+}
+
+function nextCronOccurrences(
+  row: CronRow,
+  cron: string,
+  timezone: string,
+  from: number,
+  until: number,
+): readonly number[] {
+  const parsed = parseSimpleDaily(cron);
+  if (!parsed) {
+    if (
+      row.nextRunAt !== undefined &&
+      row.nextRunAt >= from &&
+      row.nextRunAt < until
+    ) {
+      return [row.nextRunAt];
+    }
+    return [];
+  }
+
+  const out: number[] = [];
+  const start = new Date(from);
+  for (let day = 0; day < 400; day++) {
+    const probe = Date.UTC(
+      start.getUTCFullYear(),
+      start.getUTCMonth(),
+      start.getUTCDate() + day,
+      12,
+      0,
+      0,
+    );
+    if (probe > until + 86_400_000) break;
+    const local = zonedParts(probe, timezone);
+    const fires = civilFiresOnDay(local.date, parsed, timezone);
+    for (const t of fires) {
+      if (t >= from && t < until) out.push(t);
+    }
+    if (out.length > 10_000) break;
+  }
+  return out.sort((a, b) => a - b);
+}
+
+/** Parsed simple daily cron. */
+interface SimpleDaily {
+  readonly minute: number;
+  readonly hour: number;
+  readonly dow?: number;
+}
+
+function parseSimpleDaily(cron: string): SimpleDaily | null {
+  const parts = cron.trim().split(/\s+/);
+  if (parts.length < 5) return null;
+  const minute = parts[0]!;
+  const hour = parts[1]!;
+  const dom = parts[2]!;
+  const mon = parts[3]!;
+  const dow = parts[4]!;
+  if (!/^\d+$/.test(minute) || !/^\d+$/.test(hour)) return null;
+  if (dom !== "*" || mon !== "*") return null;
+  const m = Number(minute);
+  const h = Number(hour);
+  if (m < 0 || m > 59 || h < 0 || h > 23) return null;
+  if (dow === "*") return { minute: m, hour: h };
+  if (/^\d+$/.test(dow)) {
+    const d = Number(dow);
+    if (d < 0 || d > 6) return null;
+    return { minute: m, hour: h, dow: d };
+  }
+  return null;
+}
+
+function civilFiresOnDay(
+  dateStr: string,
+  parsed: SimpleDaily,
+  timezone: string,
+): readonly number[] {
+  const matches: number[] = [];
+  const base = Date.parse(`${dateStr}T00:00:00.000Z`);
+  if (Number.isNaN(base)) return [];
+
+  for (let offsetMin = -14 * 60; offsetMin <= 14 * 60; offsetMin += 15) {
+    const utc = base + parsed.hour * 3_600_000 + parsed.minute * 60_000 - offsetMin * 60_000;
+    const local = zonedParts(utc, timezone);
+    if (
+      local.date === dateStr &&
+      local.hour === parsed.hour &&
+      local.minute === parsed.minute
+    ) {
+      if (parsed.dow !== undefined) {
+        const localDow = zonedDow(utc, timezone);
+        if (localDow !== parsed.dow) continue;
+      }
+      if (!matches.includes(utc)) matches.push(utc);
+    }
+  }
+  return matches;
+}
+
+interface ZonedParts {
+  readonly date: string;
+  readonly hour: number;
+  readonly minute: number;
+}
+
+function zonedParts(utcMs: number, timezone: string): ZonedParts {
+  const fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hourCycle: "h23",
+  });
+  const parts = fmt.formatToParts(new Date(utcMs));
+  const get = (type: Intl.DateTimeFormatPartTypes): string =>
+    parts.find((p) => p.type === type)?.value ?? "0";
+  return {
+    date: `${get("year")}-${get("month")}-${get("day")}`,
+    hour: Number(get("hour")),
+    minute: Number(get("minute")),
+  };
+}
+
+function zonedDow(utcMs: number, timezone: string): number {
+  const fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    weekday: "short",
+  });
+  const w = fmt.format(new Date(utcMs));
+  const map: Record<string, number> = {
+    Sun: 0,
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6,
+  };
+  return map[w] ?? 0;
+}

package/src/elements/clock/time-travel.ts

@@ -0,0 +1,53 @@
+/**
+ * Frozen / time-travel clock for deterministic tests.
+ *
+ * ```ts
+ * const t = createTimeTravel(0);
+ * await durableSleep(...);          // parks
+ * t.advance("7d");                  // sleep elapses instantly
+ * await resume(...);
+ * ```
+ */
+
+import { parseDurationMs } from "./duration.ts";
+
+/** Injectable frozen clock with advance. */
+export interface TimeTravel {
+  /** Current frozen epoch-ms. */
+  now(): number;
+  /**
+   * Advance the frozen clock by a duration string or milliseconds.
+   *
+   * @param by - `"7d"` / `"2m"` / milliseconds
+   */
+  advance(by: string | number): number;
+  /**
+   * Jump to an absolute epoch-ms.
+   *
+   * @param ms - Absolute time
+   */
+  set(ms: number): number;
+}
+
+/**
+ * Create a frozen clock starting at `start` (default `0`).
+ *
+ * @param start - Initial epoch-ms
+ */
+export function createTimeTravel(start = 0): TimeTravel {
+  let current = start;
+  return {
+    now() {
+      return current;
+    },
+    advance(by) {
+      const ms = typeof by === "number" ? by : parseDurationMs(by);
+      current += ms;
+      return current;
+    },
+    set(ms) {
+      current = ms;
+      return current;
+    },
+  };
+}

package/src/elements/clock.test.ts

@@ -0,0 +1,365 @@
+/**
+ * Clock element acceptance (time-travel harness):
+ * - durable flow killed mid-execution resumes at the failed step
+ * - a 7-day sleep survives a restart
+ * - three instances run a cron once (leader election)
+ * - reconciliation marks a removed cron orphaned without deleting it
+ * - DST ambiguity detected from expression + zone
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { flow } from "../kernel/flow.ts";
+import {
+  createFileJournalStore,
+  createMemoryJournalStore,
+} from "../kernel/journal.ts";
+import {
+  clock,
+  createClockRuntime,
+  createMemoryCronStore,
+  createTestClockRuntime,
+  createTimeTravel,
+  detectDstAmbiguity,
+  parseDurationMs,
+  reconcileClocks,
+  runDurable,
+  tryAcquireLease,
+} from "./clock.ts";
+
+describe("clock declaration", () => {
+  test("requires cron or every", () => {
+    expect(() => clock("x", {})).toThrow(/cron or every/);
+    const c = clock("nightly", {
+      cron: "0 2 * * *",
+      timezone: "America/New_York",
+      overridable: true,
+    });
+    expect(c.name).toBe("nightly");
+    expect(c.timezone).toBe("America/New_York");
+    expect(c.overridable).toBe(true);
+  });
+});
+
+describe("time-travel harness", () => {
+  test("advance moves a frozen clock", () => {
+    const t = createTimeTravel(1_000);
+    expect(t.now()).toBe(1_000);
+    t.advance("7d");
+    expect(t.now()).toBe(1_000 + parseDurationMs("7d"));
+    t.advance(60_000);
+    expect(t.now()).toBe(1_000 + parseDurationMs("7d") + 60_000);
+  });
+});
+
+describe("durable journal", () => {
+  test("killed mid-execution resumes at the failed step, not the beginning", async () => {
+    const calls: string[] = [];
+    const journalStore = createMemoryJournalStore();
+    const tt = createTimeTravel(0);
+    let crashAfterFirstStep = true;
+
+    const charge = flow({
+      name: "payments.charge",
+      durable: true,
+      do: async (_input, fx) => {
+        const intent = await fx.step("create-intent", () => {
+          calls.push("create-intent");
+          return { id: "pi_1" };
+        });
+        if (crashAfterFirstStep) {
+          throw new Error("KILLED");
+        }
+        return fx.step("confirm", () => {
+          calls.push("confirm");
+          return intent.id === "pi_1";
+        });
+      },
+    });
+
+    const first = await runDurable({
+      flow: charge,
+      input: { orderId: "o1" },
+      journalStore,
+      now: tt.now,
+    });
+    expect(first.status).toBe("failed");
+    expect(calls).toEqual(["create-intent"]);
+
+    crashAfterFirstStep = false;
+    const runId = first.status === "failed" ? first.runId : "";
+    const second = await runDurable({
+      flow: charge,
+      input: { orderId: "o1" },
+      journalStore,
+      runId,
+      now: tt.now,
+    });
+
+    expect(second.status).toBe("completed");
+    if (second.status === "completed") {
+      expect(second.output).toBe(true);
+    }
+    // create-intent never re-ran; confirm ran once.
+    expect(calls).toEqual(["create-intent", "confirm"]);
+  });
+
+  test("7-day sleep survives a restart", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-clock-"));
+    const journalPath = join(dir, "journal.json");
+    const tt = createTimeTravel(0);
+
+    try {
+      const sleepy = flow({
+        name: "trial.wait",
+        durable: true,
+        do: async (_input, fx) => {
+          await fx.step("start", () => "begun");
+          await fx.clock.sleep("trial-period", "7d");
+          return fx.step("finish", () => "awake");
+        },
+      });
+
+      // Process A: start, park on sleep, "crash" (drop runtime).
+      const storeA = createFileJournalStore(journalPath);
+      const parked = await runDurable({
+        flow: sleepy,
+        journalStore: storeA,
+        now: tt.now,
+      });
+      expect(parked.status).toBe("sleeping");
+      if (parked.status !== "sleeping") throw new Error("expected sleeping");
+      expect(parked.wakeAt).toBe(parseDurationMs("7d"));
+      const runId = parked.runId;
+
+      // Process B: new store handle on same file, time still before wake.
+      const storeB = createFileJournalStore(journalPath);
+      const stillSleeping = await runDurable({
+        flow: sleepy,
+        journalStore: storeB,
+        runId,
+        now: tt.now,
+      });
+      expect(stillSleeping.status).toBe("sleeping");
+
+      // Time travel past the wake, then resume.
+      tt.advance("7d");
+      const storeC = createFileJournalStore(journalPath);
+      const done = await runDurable({
+        flow: sleepy,
+        journalStore: storeC,
+        runId,
+        now: tt.now,
+      });
+      expect(done.status).toBe("completed");
+      if (done.status === "completed") {
+        expect(done.output).toBe("awake");
+      }
+
+      const final = await storeC.get(runId);
+      expect(final?.entries.filter((e) => e.kind === "step")).toHaveLength(2);
+      expect(final?.entries.some((e) => e.kind === "sleep")).toBe(true);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("leader election", () => {
+  test("three instances run a cron once", async () => {
+    const store = createMemoryCronStore();
+    const tt = createTimeTravel(0);
+    const fired: string[] = [];
+
+    const decl = clock("expire-stale", { every: "1h" });
+    const mk = (instanceId: string) => {
+      const rt = createClockRuntime({
+        instanceId,
+        store,
+        leaseMs: 60_000,
+        timeTravel: tt,
+      });
+      rt.register(decl);
+      rt.onCron("expire-stale", () => {
+        fired.push(instanceId);
+      });
+      return rt;
+    };
+
+    const a = mk("i-a");
+    const b = mk("i-b");
+    const c = mk("i-c");
+    await a.reconcile();
+
+    const results = await Promise.all([
+      a.runNow("expire-stale"),
+      b.runNow("expire-stale"),
+      c.runNow("expire-stale"),
+    ]);
+
+    expect(results.filter(Boolean)).toHaveLength(1);
+    expect(fired).toHaveLength(1);
+    const winner = fired[0];
+    if (winner === undefined) throw new Error("expected a winner");
+    expect(["i-a", "i-b", "i-c"]).toContain(winner);
+
+    // Lease still held — further runs are denied until expiry.
+    expect(await a.runNow("expire-stale")).toBe(false);
+    expect(fired).toHaveLength(1);
+
+    // After lease expires, another instance may run.
+    tt.advance(60_001);
+    expect(await b.runNow("expire-stale")).toBe(true);
+    expect(fired).toEqual([winner, "i-b"]);
+  });
+
+  test("tryAcquireLease is exclusive within the lease window", async () => {
+    const store = createMemoryCronStore([
+      {
+        name: "job",
+        effectiveEvery: "1h",
+        timezone: "UTC",
+        overridable: false,
+        status: "active",
+      },
+    ]);
+    expect(
+      await tryAcquireLease({
+        name: "job",
+        instanceId: "a",
+        now: 0,
+        leaseMs: 1000,
+        store,
+      }),
+    ).toBe(true);
+    expect(
+      await tryAcquireLease({
+        name: "job",
+        instanceId: "b",
+        now: 500,
+        leaseMs: 1000,
+        store,
+      }),
+    ).toBe(false);
+    expect(
+      await tryAcquireLease({
+        name: "job",
+        instanceId: "b",
+        now: 1001,
+        leaseMs: 1000,
+        store,
+      }),
+    ).toBe(true);
+  });
+});
+
+describe("reconciliation", () => {
+  test("marks a removed cron orphaned without deleting it", async () => {
+    const store = createMemoryCronStore();
+    const a = clock("keep", { every: "10m" });
+    const b = clock("remove-me", { cron: "0 * * * *", overridable: true });
+
+    const first = await reconcileClocks([a, b], store);
+    expect([...first.active].sort()).toEqual(["keep", "remove-me"]);
+    expect(await store.get("remove-me")).toMatchObject({ status: "active" });
+
+    // Override is preserved across reconcile while still declared.
+    await store.put({
+      ...(await store.get("remove-me"))!,
+      overrideCron: "30 * * * *",
+      effectiveCron: "30 * * * *",
+    });
+    await reconcileClocks([a, b], store);
+    expect((await store.get("remove-me"))?.overrideCron).toBe("30 * * * *");
+    expect((await store.get("remove-me"))?.effectiveCron).toBe("30 * * * *");
+
+    // Code no longer declares remove-me → orphaned, not deleted.
+    const second = await reconcileClocks([a], store);
+    expect(second.orphaned).toContain("remove-me");
+    const orphan = await store.get("remove-me");
+    expect(orphan).toBeDefined();
+    expect(orphan?.status).toBe("orphaned");
+    expect(orphan?.overrideCron).toBe("30 * * * *");
+
+    // Scheduler runtime skips orphaned rows.
+    const rt = createTestClockRuntime(0, { store, instanceId: "solo" });
+    rt.register(a);
+    await rt.reconcile();
+    let ranOrphan = false;
+    rt.onCron("remove-me", () => {
+      ranOrphan = true;
+    });
+    rt.onCron("keep", () => {});
+    await rt.runNow("remove-me");
+    expect(ranOrphan).toBe(false);
+  });
+
+  test("scheduler reads effective state from the store", async () => {
+    const store = createMemoryCronStore();
+    const rt = createTestClockRuntime(0, { store, instanceId: "s1" });
+    rt.register(clock("job", { every: "1h", overridable: true }));
+    await rt.reconcile();
+
+    await store.put({
+      ...(await store.get("job"))!,
+      overrideEvery: "5m",
+      effectiveEvery: "5m",
+    });
+
+    const fired: number[] = [];
+    rt.onCron("job", () => {
+      fired.push(rt.now());
+    });
+
+    await rt.tick();
+    expect(fired).toHaveLength(1);
+
+    // Not due again until effective every (5m) elapses — not the declared 1h.
+    await rt.tick();
+    expect(fired).toHaveLength(1);
+    rt.advance("5m");
+    await rt.tick();
+    expect(fired).toHaveLength(2);
+  });
+});
+
+describe("DST ambiguity", () => {
+  test("detected from expression plus zone", () => {
+    // 02:00 America/New_York sits in the spring-forward gap / fall-back overlap.
+    const amb = detectDstAmbiguity("0 2 * * *", "America/New_York", Date.UTC(2026, 0, 1));
+    expect(amb).not.toBeNull();
+    if (!amb) throw new Error("expected DST ambiguity");
+    expect(amb.localTime).toBe("02:00");
+    expect(amb.timezone).toBe("America/New_York");
+    expect(["gap", "overlap"]).toContain(amb.kind);
+
+    // UTC has no DST — never warn.
+    expect(detectDstAmbiguity("0 2 * * *", "UTC")).toBeNull();
+
+    // Noon is outside the transition window for US zones.
+    expect(
+      detectDstAmbiguity("0 12 * * *", "America/New_York", Date.UTC(2026, 0, 1)),
+    ).toBeNull();
+  });
+
+  test("reconcile attaches dstAmbiguity on the store row", async () => {
+    const store = createMemoryCronStore();
+    const rt = createTestClockRuntime(Date.UTC(2026, 0, 1), {
+      store,
+      instanceId: "dst",
+    });
+    rt.register(
+      clock("nightly", {
+        cron: "0 2 * * *",
+        timezone: "America/New_York",
+      }),
+    );
+    await rt.reconcile();
+    const row = await store.get("nightly");
+    expect(row?.dstAmbiguity).toBeDefined();
+    expect(row?.dstAmbiguity?.localTime).toBe("02:00");
+  });
+});