okengine 0.1.4

package/src/elements/clock/dst.ts

@@ -0,0 +1,197 @@
+/**
+ * DST ambiguity detection — expression + zone together (console §9.6).
+ *
+ * A daily 02:00 job in a DST-observing zone runs twice or never on
+ * transition days. The warning appears only when the schedule actually
+ * falls in the ambiguous window.
+ */
+
+/** Result when a schedule hits a DST gap or overlap. */
+export interface DstAmbiguity {
+  /** `"gap"` — spring forward (time skipped); `"overlap"` — fall back (time repeats). */
+  readonly kind: "gap" | "overlap";
+  /** IANA timezone. */
+  readonly timezone: string;
+  /** Cron expression that was checked. */
+  readonly cron: string;
+  /** Local wall time (`HH:MM`) that is ambiguous. */
+  readonly localTime: string;
+  /** Example transition day (ISO date) where the issue occurs. */
+  readonly on: string;
+  /** Human-readable reason. */
+  readonly reason: string;
+}
+
+/**
+ * Detect whether a cron expression + timezone falls in a DST ambiguous window.
+ *
+ * Supports simple forms `M H * * *` (and `M H * * DOW`). Complex lists /
+ * steps / ranges return `null` (no spurious always-on warning).
+ *
+ * @param cron - Five-field cron expression
+ * @param timezone - IANA timezone
+ * @param from - Optional epoch-ms scan start (defaults to now)
+ */
+export function detectDstAmbiguity(
+  cron: string,
+  timezone: string,
+  from: number = Date.now(),
+): DstAmbiguity | null {
+  if (timezone === "UTC" || timezone === "Etc/UTC" || timezone === "GMT") {
+    return null;
+  }
+
+  const parsed = parseSimpleDaily(cron);
+  if (!parsed) return null;
+
+  const { minute, hour } = parsed;
+  const start = new Date(from);
+  let prevOffset: number | null = null;
+
+  // Walk day-by-day; only classify on days where the noon offset jumps
+  // (DST transition). Keeps the warning precise without a full-year grind.
+  for (let day = 0; day < 450; day++) {
+    const probe = Date.UTC(
+      start.getUTCFullYear(),
+      start.getUTCMonth(),
+      start.getUTCDate() + day,
+      12,
+      0,
+      0,
+    );
+    const offset = offsetMinutesAt(probe, timezone);
+    if (prevOffset !== null && offset !== prevOffset) {
+      // Transition occurred between yesterday noon and today noon —
+      // check both civil dates around the jump.
+      for (const delta of [-1, 0] as const) {
+        const t = new Date(probe + delta * 86_400_000);
+        const y = t.getUTCFullYear();
+        const mo = t.getUTCMonth() + 1;
+        const d = t.getUTCDate();
+        const dateStr = `${y}-${pad(mo)}-${pad(d)}`;
+        const kind = classifyLocalInstant(dateStr, hour, minute, timezone);
+        if (kind === "gap" || kind === "overlap") {
+          const localTime = `${pad(hour)}:${pad(minute)}`;
+          return {
+            kind,
+            timezone,
+            cron: cron.trim(),
+            localTime,
+            on: dateStr,
+            reason:
+              kind === "gap"
+                ? `${localTime} in ${timezone} is skipped on ${dateStr} (DST spring forward)`
+                : `${localTime} in ${timezone} occurs twice on ${dateStr} (DST fall back)`,
+          };
+        }
+      }
+    }
+    prevOffset = offset;
+  }
+  return null;
+}
+
+/** Parsed simple daily cron. */
+interface SimpleDaily {
+  readonly minute: number;
+  readonly hour: 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]!;
+  // Only flag when the schedule pins a specific local wall-clock time.
+  if (!/^\d+$/.test(minute) || !/^\d+$/.test(hour)) return null;
+  if (dom !== "*" && !/^\d+$/.test(dom)) return null;
+  if (mon !== "*" && !/^\d+$/.test(mon)) return null;
+  const m = Number(minute);
+  const h = Number(hour);
+  if (m < 0 || m > 59 || h < 0 || h > 23) return null;
+  return { minute: m, hour: h };
+}
+
+/**
+ * Classify a local civil time in `timezone` on `YYYY-MM-DD`.
+ *
+ * - `ok` — exactly one UTC instant
+ * - `gap` — no UTC instant (spring forward)
+ * - `overlap` — two UTC instants (fall back)
+ */
+function classifyLocalInstant(
+  dateStr: string,
+  hour: number,
+  minute: number,
+  timezone: string,
+): "ok" | "gap" | "overlap" {
+  const matches: number[] = [];
+  const base = Date.parse(`${dateStr}T00:00:00.000Z`);
+  if (Number.isNaN(base)) return "ok";
+
+  for (let offsetMin = -14 * 60; offsetMin <= 14 * 60; offsetMin += 15) {
+    const utc = base + hour * 3_600_000 + minute * 60_000 - offsetMin * 60_000;
+    const local = formatInZone(utc, timezone);
+    if (
+      local.date === dateStr &&
+      local.hour === hour &&
+      local.minute === minute
+    ) {
+      if (!matches.includes(utc)) matches.push(utc);
+    }
+  }
+
+  if (matches.length === 0) return "gap";
+  if (matches.length >= 2) return "overlap";
+  return "ok";
+}
+
+/** UTC offset (minutes) of `timezone` at `utcMs`. */
+function offsetMinutesAt(utcMs: number, timezone: string): number {
+  const local = formatInZone(utcMs, timezone);
+  // Reconstruct a UTC ms for the same wall clock as if it were UTC, then diff.
+  const asUtc = Date.UTC(
+    Number(local.date.slice(0, 4)),
+    Number(local.date.slice(5, 7)) - 1,
+    Number(local.date.slice(8, 10)),
+    local.hour,
+    local.minute,
+    0,
+  );
+  return Math.round((asUtc - utcMs) / 60_000);
+}
+
+interface ZonedParts {
+  readonly date: string;
+  readonly hour: number;
+  readonly minute: number;
+}
+
+function formatInZone(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";
+  const year = get("year");
+  const month = get("month");
+  const day = get("day");
+  return {
+    date: `${year}-${month}-${day}`,
+    hour: Number(get("hour")),
+    minute: Number(get("minute")),
+  };
+}
+
+function pad(n: number): string {
+  return n < 10 ? `0${n}` : String(n);
+}

package/src/elements/clock/durable.ts

@@ -0,0 +1,140 @@
+/**
+ * Durable flow runner — journals every fx call when `durable: true`.
+ *
+ * Workflows are not a separate API: an ordinary flow with one option.
+ * A process killed between steps resumes at the failed step; the prior
+ * step never re-runs (four-applications · Provisions).
+ */
+
+import type { AnyFlowDef } from "../../kernel/flow.ts";
+import {
+  createFxContext,
+  type CreateFxOptions,
+  type Fx,
+} from "../../kernel/fx.ts";
+import {
+  createJournal,
+  isJournalSuspend,
+  type Journal,
+  type JournalSession,
+  type JournalStore,
+} from "../../kernel/journal.ts";
+/** Outcome of one durable attempt. */
+export type DurableResult<O = unknown> =
+  | {
+      readonly status: "completed";
+      readonly runId: string;
+      readonly output: O;
+    }
+  | {
+      readonly status: "sleeping";
+      readonly runId: string;
+      readonly wakeAt: number;
+      readonly label: string;
+    }
+  | {
+      readonly status: "failed";
+      readonly runId: string;
+      readonly error: string;
+    };
+
+/** Options for {@link runDurable}. */
+export interface RunDurableOptions {
+  /** Flow with `durable: true` (or forced via this runner). */
+  readonly flow: AnyFlowDef;
+  /** Input payload. */
+  readonly input?: unknown;
+  /** Journal store (memory or file). */
+  readonly journalStore: JournalStore;
+  /** Resume an existing run id (crash recovery). */
+  readonly runId?: string;
+  /** Injectable clock. */
+  readonly now?: () => number;
+  /** Extra fx options (secrets, store runtime, …). */
+  readonly fx?: Omit<
+    CreateFxOptions,
+    "flow" | "effects" | "capability" | "now" | "journal"
+  >;
+}
+
+/**
+ * Execute (or resume) a durable flow against a journal.
+ *
+ * @param options - Flow, input, journal, clock
+ */
+export async function runDurable<O = unknown>(
+  options: RunDurableOptions,
+): Promise<DurableResult<O>> {
+  const now = options.now ?? (() => Date.now());
+  const journal: Journal = createJournal({
+    store: options.journalStore,
+    now,
+  });
+
+  if (options.runId) {
+    const existing = await options.journalStore.get(options.runId);
+    if (
+      existing?.wakeAt !== undefined &&
+      now() < existing.wakeAt
+    ) {
+      const sleepEntry = [...existing.entries]
+        .reverse()
+        .find((e) => e.kind === "sleep");
+      return {
+        status: "sleeping",
+        runId: existing.id,
+        wakeAt: existing.wakeAt,
+        label: sleepEntry && sleepEntry.kind === "sleep" ? sleepEntry.label : "",
+      };
+    }
+  }
+
+  const session: JournalSession = options.runId
+    ? await journal.resume(options.runId)
+    : await journal.start(options.flow.name, options.input);
+
+  if (session.run.status === "sleeping") {
+    session.run.status = "running";
+  }
+
+  const { fx } = createFxContext({
+    ...options.fx,
+    flow: options.flow.name,
+    effects: options.flow.effects,
+    now,
+    journal: session,
+    durable: true,
+  });
+
+  try {
+    const output = await options.flow.do(options.input as never, fx);
+    await session.commit("completed", { output });
+    return {
+      status: "completed",
+      runId: session.runId,
+      output: output as O,
+    };
+  } catch (err) {
+    if (isJournalSuspend(err)) {
+      return {
+        status: "sleeping",
+        runId: session.runId,
+        wakeAt: err.wakeAt,
+        label: err.label,
+      };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    await session.commit("failed", { error: message });
+    return {
+      status: "failed",
+      runId: session.runId,
+      error: message,
+    };
+  }
+}
+
+/**
+ * Bind a journal session onto an existing {@link Fx} factory path —
+ * re-exported type helper for tests that build fx directly.
+ */
+export type { JournalSession, Fx };

package/src/elements/clock/duration.ts

@@ -0,0 +1,29 @@
+/**
+ * Duration / interval parsing for the Clock element.
+ */
+
+/**
+ * Parse a short duration string (`"7d"`, `"2m"`, `"30s"`, `"1h"`, `"200ms"`)
+ * to milliseconds. Returns `0` when the string is not a duration.
+ *
+ * @param duration - Duration string
+ */
+export function parseDurationMs(duration: string): number {
+  const match = /^(\d+)(ms|s|m|h|d)$/.exec(duration.trim());
+  if (!match) return 0;
+  const n = Number(match[1]);
+  switch (match[2]) {
+    case "ms":
+      return n;
+    case "s":
+      return n * 1000;
+    case "m":
+      return n * 60_000;
+    case "h":
+      return n * 3_600_000;
+    case "d":
+      return n * 86_400_000;
+    default:
+      return 0;
+  }
+}

package/src/elements/clock/health.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Cron health + next-occurrence helpers.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { cronHealth } from "./health.ts";
+import { nextOccurrences } from "./schedule.ts";
+import type { CronRow } from "./reconcile.ts";
+
+function row(partial: Partial<CronRow> & { name: string }): CronRow {
+  return {
+    timezone: "UTC",
+    overridable: false,
+    status: "active",
+    ...partial,
+  };
+}
+
+describe("cronHealth", () => {
+  test("every — overdue with missed runs and catchUp one", () => {
+    const now = 10_000;
+    const h = cronHealth(
+      row({
+        name: "tick",
+        effectiveEvery: "1s",
+        declaredEvery: "1s",
+        lastRunAt: 0,
+        nextRunAt: 1_000,
+      }),
+      now,
+    );
+    expect(h.overdue).toBe(true);
+    expect(h.missedRuns).toBe(10);
+    expect(h.catchUp).toBe("one");
+  });
+
+  test("not overdue when nextRunAt is in the future", () => {
+    const now = 1_000;
+    const h = cronHealth(
+      row({
+        name: "ok",
+        effectiveEvery: "1h",
+        lastRunAt: 0,
+        nextRunAt: 3_600_000,
+      }),
+      now,
+    );
+    expect(h.overdue).toBe(false);
+    expect(h.missedRuns).toBe(0);
+  });
+
+  test("projects lease holder fields", () => {
+    const h = cronHealth(
+      row({
+        name: "leased",
+        effectiveEvery: "1h",
+        leaderInstanceId: "inst-a",
+        leaderLeaseUntil: 99_000,
+        lastRunAt: 0,
+        nextRunAt: 3_600_000,
+      }),
+      1_000,
+    );
+    expect(h.leaderInstanceId).toBe("inst-a");
+    expect(h.leaderLeaseUntil).toBe(99_000);
+  });
+});
+
+describe("nextOccurrences", () => {
+  test("every — next 24h of fires", () => {
+    const from = 0;
+    const until = 10_000;
+    const fires = nextOccurrences(
+      row({
+        name: "tick",
+        effectiveEvery: "2s",
+        lastRunAt: 0,
+      }),
+      from,
+      until,
+    );
+    expect(fires[0]).toBe(2_000);
+    expect(fires.length).toBe(4);
+    expect(fires[fires.length - 1]).toBe(8_000);
+  });
+
+  test("simple daily cron in UTC", () => {
+    // 2024-01-01 00:00 UTC
+    const from = Date.UTC(2024, 0, 1, 0, 0, 0);
+    const until = from + 48 * 3_600_000;
+    const fires = nextOccurrences(
+      row({
+        name: "nightly",
+        effectiveCron: "0 2 * * *",
+        timezone: "UTC",
+      }),
+      from,
+      until,
+    );
+    expect(fires.length).toBeGreaterThanOrEqual(1);
+    expect(fires.every((t) => t >= from && t < until)).toBe(true);
+  });
+});

package/src/elements/clock/health.ts

@@ -0,0 +1,112 @@
+/**
+ * Cron health — four numbers for the Console Clock panel (console §9.6).
+ *
+ * Catch-up policy is `"one"`: the runtime fires at most once per lease when
+ * overdue (`ClockRuntime.tick` / `fire`). Not a Store column.
+ */
+
+import { parseDurationMs } from "./duration.ts";
+import { effectiveSchedule, type CronRow } from "./reconcile.ts";
+import {
+  countMissedOccurrences,
+  previousOccurrence,
+} from "./schedule.ts";
+
+/** Catch-up policy matching ClockRuntime physics. */
+export type CatchUpPolicy = "one";
+
+/** Four-number cron health (+ lease holder). */
+export interface CronHealth {
+  /** Scheduled vs actual (`lastRunAt - expected`); `null` when unknown. */
+  readonly driftMs: number | null;
+  /** Whether the schedule is past due. */
+  readonly overdue: boolean;
+  /** Runs missed while the app was down (slots between last fire and now). */
+  readonly missedRuns: number;
+  /** Runtime catch-up policy (`"one"`). */
+  readonly catchUp: CatchUpPolicy;
+  /** Instance holding the leader lease, if any. */
+  readonly leaderInstanceId?: string;
+  /** Lease expiry epoch-ms. */
+  readonly leaderLeaseUntil?: number;
+}
+
+/**
+ * Compute cron health from a reconciled Store row.
+ *
+ * @param row - `oke_crons` row
+ * @param now - Current epoch-ms
+ */
+export function cronHealth(row: CronRow, now: number): CronHealth {
+  const overdue = isOverdue(row, now);
+  const missedRuns = overdue
+    ? countMissedFromRow(row, now)
+    : 0;
+  const driftMs = computeDrift(row, now);
+
+  return {
+    driftMs,
+    overdue,
+    missedRuns,
+    catchUp: "one",
+    leaderInstanceId: row.leaderInstanceId,
+    leaderLeaseUntil: row.leaderLeaseUntil,
+  };
+}
+
+/**
+ * @param row - Store row
+ * @param now - Clock
+ */
+function isOverdue(row: CronRow, now: number): boolean {
+  if (row.status !== "active") return false;
+  if (row.nextRunAt !== undefined) return row.nextRunAt < now;
+  const sched = effectiveSchedule(row);
+  if (sched.every) {
+    const interval = parseDurationMs(sched.every);
+    if (interval <= 0) return false;
+    if (row.lastRunAt === undefined) return true;
+    return row.lastRunAt + interval < now;
+  }
+  return false;
+}
+
+function countMissedFromRow(row: CronRow, now: number): number {
+  const sched = effectiveSchedule(row);
+  if (sched.every) {
+    const interval = parseDurationMs(sched.every);
+    if (interval <= 0) return 0;
+    if (row.lastRunAt === undefined) return 1;
+    const elapsed = now - row.lastRunAt;
+    return Math.max(0, Math.floor(elapsed / interval));
+  }
+  if (row.lastRunAt !== undefined) {
+    return countMissedOccurrences(row, row.lastRunAt, now);
+  }
+  if (row.nextRunAt !== undefined && row.nextRunAt < now) return 1;
+  return 0;
+}
+
+function computeDrift(row: CronRow, now: number): number | null {
+  if (row.lastRunAt === undefined) return null;
+  const expected = previousOccurrence(row, row.lastRunAt);
+  if (expected === null) {
+    // Fallback: for `every`, expected is lastRunAt floored to interval from origin.
+    const sched = effectiveSchedule(row);
+    if (sched.every) {
+      const interval = parseDurationMs(sched.every);
+      if (interval <= 0) return null;
+      // If nextRunAt is set, expected previous = nextRunAt - interval.
+      if (row.nextRunAt !== undefined) {
+        return row.lastRunAt - (row.nextRunAt - interval);
+      }
+      // No better anchor — drift unknown unless overdue.
+      if (row.lastRunAt + interval < now) {
+        return now - (row.lastRunAt + interval);
+      }
+      return 0;
+    }
+    return null;
+  }
+  return row.lastRunAt - expected;
+}

package/src/elements/clock/leader.ts

@@ -0,0 +1,127 @@
+/**
+ * Cron leader election — N instances, one run (unified-theory · Clone axis).
+ *
+ * Lease lives on the reconciled cron row so the Console can show which
+ * instance holds it (console §9.6).
+ */
+
+/** Cron row fields the lease mutates. */
+export interface LeaseTarget {
+  /** Schedule name. */
+  readonly name: string;
+  /** Instance currently holding the lease, if any. */
+  leaderInstanceId?: string;
+  /** Absolute lease expiry epoch-ms. */
+  leaderLeaseUntil?: number;
+}
+
+/** Store surface required by {@link tryAcquireLease}. */
+export interface LeaseStore {
+  /**
+   * @param name - Cron name
+   */
+  get(name: string): Promise<LeaseTarget | undefined>;
+  /**
+   * @param row - Updated row
+   */
+  put(row: LeaseTarget): Promise<void>;
+  /**
+   * Optional atomic acquire — preferred when present (memory / sql).
+   *
+   * @param name - Cron name
+   * @param instanceId - Candidate instance
+   * @param now - Current epoch-ms
+   * @param leaseMs - Lease TTL
+   */
+  acquireLease?(
+    name: string,
+    instanceId: string,
+    now: number,
+    leaseMs: number,
+  ): Promise<boolean>;
+}
+
+/** Options for {@link tryAcquireLease}. */
+export interface AcquireLeaseOptions {
+  /** Cron name. */
+  readonly name: string;
+  /** This instance's id. */
+  readonly instanceId: string;
+  /** Current epoch-ms. */
+  readonly now: number;
+  /** Lease TTL in milliseconds. */
+  readonly leaseMs: number;
+  /** Backing store. */
+  readonly store: LeaseStore;
+}
+
+/**
+ * Try to acquire (or renew) the leader lease for a cron.
+ *
+ * Returns `true` when this instance holds the lease after the call —
+ * only then may it execute the schedule.
+ *
+ * @param options - Name, instance, clock, store
+ */
+export async function tryAcquireLease(
+  options: AcquireLeaseOptions,
+): Promise<boolean> {
+  if (options.store.acquireLease) {
+    return options.store.acquireLease(
+      options.name,
+      options.instanceId,
+      options.now,
+      options.leaseMs,
+    );
+  }
+
+  const row = await options.store.get(options.name);
+  if (!row) return false;
+
+  const held =
+    row.leaderLeaseUntil !== undefined &&
+    row.leaderLeaseUntil > options.now &&
+    row.leaderInstanceId !== undefined &&
+    row.leaderInstanceId !== options.instanceId;
+
+  if (held) return false;
+
+  const next: LeaseTarget = {
+    ...row,
+    leaderInstanceId: options.instanceId,
+    leaderLeaseUntil: options.now + options.leaseMs,
+  };
+  await options.store.put(next);
+
+  // Re-read: lose the race if another writer won.
+  const confirmed = await options.store.get(options.name);
+  return (
+    confirmed?.leaderInstanceId === options.instanceId &&
+    (confirmed.leaderLeaseUntil ?? 0) > options.now
+  );
+}
+
+/**
+ * Release the lease when held by `instanceId` (best-effort).
+ *
+ * @param store - Lease store
+ * @param name - Cron name
+ * @param instanceId - Instance that should release
+ * @param now - Current epoch-ms
+ */
+export async function releaseLease(
+  store: LeaseStore,
+  name: string,
+  instanceId: string,
+  now: number,
+): Promise<void> {
+  const row = await store.get(name);
+  if (!row) return;
+  if (row.leaderInstanceId !== instanceId) return;
+  if (row.leaderLeaseUntil !== undefined && row.leaderLeaseUntil <= now) return;
+  await store.put({
+    ...row,
+    leaderInstanceId: undefined,
+    leaderLeaseUntil: undefined,
+  });
+}