okengine 0.7.0 → 0.9.0

package/src/drivers/clock-postgres.test.ts

@@ -0,0 +1,258 @@
+/**
+ * Postgres CronStore — unit (fake) + live multi-process chaos.
+ *
+ * Live suite: set `OKE_TEST_POSTGRES_URL` (or `OKE_TEST_POSTGRES=1` + `DATABASE_URL`).
+ * Without a live Postgres the chaos describe skips visibly.
+ */
+
+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 { clock } from "../elements/clock/declare.ts";
+import { createClockRuntime } from "../elements/clock/runtime.ts";
+import { createPostgresCronFake, createPostgresCronStore } from "./clock-postgres.ts";
+
+const childPath = join(import.meta.dir, "../elements/clock/chaos-child.ts");
+
+const LIVE_URL =
+  process.env.OKE_TEST_POSTGRES_URL?.trim() ||
+  (process.env.OKE_TEST_POSTGRES === "1"
+    ? (process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL)?.trim()
+    : undefined);
+
+describe("postgres CronStore (fake)", () => {
+  test("put / get / list round-trip", async () => {
+    const store = await createPostgresCronStore({ sql: createPostgresCronFake() });
+    await store.put({
+      name: "job",
+      effectiveEvery: "1h",
+      timezone: "UTC",
+      overridable: false,
+      status: "active",
+    });
+    const row = await store.get("job");
+    expect(row?.name).toBe("job");
+    expect(row?.effectiveEvery).toBe("1h");
+    expect(await store.list()).toHaveLength(1);
+    await store.close();
+  });
+
+  test("acquireLease: exactly one of two racing claimants wins", async () => {
+    const fake = createPostgresCronFake();
+    const store = await createPostgresCronStore({ sql: fake });
+    await store.put({
+      name: "race",
+      effectiveEvery: "1h",
+      timezone: "UTC",
+      overridable: false,
+      status: "active",
+    });
+
+    const now = 1_000;
+    const leaseMs = 500;
+    // Overlap transactions: start both begins concurrently via fake's
+    // sequential begin — second joins only when nested; here we race
+    // two top-level acquires after seeding.
+    const a = store.acquireLease("race", "a", now, leaseMs);
+    const b = store.acquireLease("race", "b", now, leaseMs);
+    const [wa, wb] = await Promise.all([a, b]);
+    expect([wa, wb].filter(Boolean)).toHaveLength(1);
+
+    const row = await store.get("race");
+    expect(row?.leaderInstanceId).toBe(wa ? "a" : "b");
+    expect(row?.leaderLeaseUntil).toBe(now + leaseMs);
+    await store.close();
+  });
+
+  test("acquireLease: expired lease is reclaimed lazily (no sweeper)", async () => {
+    const store = await createPostgresCronStore({ sql: createPostgresCronFake() });
+    await store.put({
+      name: "reclaim",
+      effectiveEvery: "1h",
+      timezone: "UTC",
+      overridable: false,
+      status: "active",
+      leaderInstanceId: "dead",
+      leaderLeaseUntil: 100,
+    });
+
+    expect(await store.acquireLease("reclaim", "survivor", 100, 50)).toBe(true);
+    const row = await store.get("reclaim");
+    expect(row?.leaderInstanceId).toBe("survivor");
+    expect(row?.leaderLeaseUntil).toBe(150);
+    await store.close();
+  });
+
+  test("acquireLease: live lease blocks other instance", async () => {
+    const store = await createPostgresCronStore({ sql: createPostgresCronFake() });
+    await store.put({
+      name: "held",
+      effectiveEvery: "1h",
+      timezone: "UTC",
+      overridable: false,
+      status: "active",
+    });
+    expect(await store.acquireLease("held", "leader", 0, 1_000)).toBe(true);
+    expect(await store.acquireLease("held", "other", 100, 1_000)).toBe(false);
+    // Same holder may renew.
+    expect(await store.acquireLease("held", "leader", 100, 1_000)).toBe(true);
+    await store.close();
+  });
+
+  test("runtime: two instances fire a due tick once", async () => {
+    const store = await createPostgresCronStore({ sql: createPostgresCronFake() });
+    const fires: string[] = [];
+    const a = createClockRuntime({ instanceId: "a", store, leaseMs: 200 });
+    const b = createClockRuntime({ instanceId: "b", store, leaseMs: 200 });
+    a.register(clock("once", { every: "1h" }));
+    b.register(clock("once", { every: "1h" }));
+    await a.reconcile();
+    a.onCron("once", () => {
+      fires.push("a");
+    });
+    b.onCron("once", () => {
+      fires.push("b");
+    });
+    const [ra, rb] = await Promise.all([a.tick(), b.tick()]);
+    expect([...ra.ran, ...rb.ran].filter((n) => n === "once")).toHaveLength(1);
+    expect(fires).toHaveLength(1);
+    await store.close();
+  });
+});
+
+describe.skipIf(!LIVE_URL)("chaos — postgres CronStore multi-process", () => {
+  test("two OS processes fire exactly once (no shared filesystem)", async () => {
+    const url = LIVE_URL!;
+    const dir = await mkdtemp(join(tmpdir(), "oke-clock-pg-leader-"));
+    const fireLogPath = join(dir, "fires.jsonl");
+    const leaseMs = 200;
+    const schemaStore = await createPostgresCronStore({ url });
+    // Isolate this run from prior leftovers.
+    await schemaStore.sql.exec(`DELETE FROM oke_crons WHERE name = ?`, ["chaos-job"]);
+    await schemaStore.close();
+
+    try {
+      const a = Bun.spawn({
+        cmd: ["bun", childPath, "tick-loop-pg", url, "inst-a", fireLogPath, String(leaseMs), "1h"],
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      const b = Bun.spawn({
+        cmd: ["bun", childPath, "tick-loop-pg", url, "inst-b", fireLogPath, String(leaseMs), "1h"],
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const deadline = Date.now() + 15_000;
+      while (Date.now() < deadline) {
+        if (await Bun.file(fireLogPath).exists()) {
+          const text = await Bun.file(fireLogPath).text();
+          if (text.trim().split("\n").filter(Boolean).length >= 1) break;
+        }
+        await Bun.sleep(20);
+      }
+      a.kill(9);
+      b.kill(9);
+      await Promise.all([a.exited, b.exited]);
+
+      expect(await Bun.file(fireLogPath).exists()).toBe(true);
+      const lines = (await Bun.file(fireLogPath).text()).trim().split("\n").filter(Boolean);
+      expect(lines).toHaveLength(1);
+      const fire = JSON.parse(lines[0]!) as { instanceId: string };
+      expect(["inst-a", "inst-b"]).toContain(fire.instanceId);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+      const cleanup = await createPostgresCronStore({ url });
+      await cleanup.sql.exec(`DELETE FROM oke_crons WHERE name = ?`, ["chaos-job"]);
+      await cleanup.close();
+    }
+  });
+
+  test("SIGKILL leader mid-lease: survivor takes over; report real latency", async () => {
+    const url = LIVE_URL!;
+    const dir = await mkdtemp(join(tmpdir(), "oke-clock-pg-takeover-"));
+    const markerPath = join(dir, "held.json");
+    const fireLogPath = join(dir, "fires.jsonl");
+    const leaseMs = 120;
+    const tickSlackMs = 400;
+
+    const schemaStore = await createPostgresCronStore({ url });
+    await schemaStore.sql.exec(`DELETE FROM oke_crons WHERE name = ?`, ["chaos-job"]);
+    await schemaStore.close();
+
+    async function waitForFile(path: string, timeoutMs = 15_000): Promise<boolean> {
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() < deadline) {
+        if (await Bun.file(path).exists()) return true;
+        await Bun.sleep(10);
+      }
+      return false;
+    }
+
+    try {
+      const leader = Bun.spawn({
+        cmd: ["bun", childPath, "hold-lease-pg", url, "leader", markerPath, String(leaseMs)],
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      expect(await waitForFile(markerPath)).toBe(true);
+      const held = (await Bun.file(markerPath).json()) as {
+        leaderLeaseUntil?: number;
+        heldAt: number;
+      };
+
+      const killAt = Date.now();
+      leader.kill(9);
+      await leader.exited;
+
+      const survivor = Bun.spawn({
+        cmd: [
+          "bun",
+          childPath,
+          "tick-loop-pg",
+          url,
+          "survivor",
+          fireLogPath,
+          String(leaseMs),
+          "50ms",
+        ],
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      expect(await survivor.exited).toBe(0);
+
+      expect(await Bun.file(fireLogPath).exists()).toBe(true);
+      const lines = (await Bun.file(fireLogPath).text()).trim().split("\n").filter(Boolean);
+      expect(lines).toHaveLength(1);
+      const fire = JSON.parse(lines[0]!) as { instanceId: string; firedAt: number };
+      expect(fire.instanceId).toBe("survivor");
+
+      const takeoverMs = fire.firedAt - killAt;
+      const leaseRemainingAtKill = Math.max(
+        0,
+        (held.leaderLeaseUntil ?? killAt + leaseMs) - killAt,
+      );
+      expect(takeoverMs).toBeGreaterThanOrEqual(Math.max(0, leaseRemainingAtKill - 40));
+      expect(takeoverMs).toBeLessThanOrEqual(leaseMs + tickSlackMs);
+
+      console.log(
+        `[clock postgres takeover] measured=${takeoverMs}ms leaseMs=${leaseMs} leaseRemainingAtKill=${leaseRemainingAtKill}ms`,
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+      const cleanup = await createPostgresCronStore({ url });
+      await cleanup.sql.exec(`DELETE FROM oke_crons WHERE name = ?`, ["chaos-job"]);
+      await cleanup.close();
+    }
+  });
+});
+
+// Visible skip reason when the live gate is off (describe.skipIf hides the body).
+if (!LIVE_URL) {
+  console.log(
+    "skip: postgres CronStore chaos (set OKE_TEST_POSTGRES_URL or OKE_TEST_POSTGRES=1 + DATABASE_URL)",
+  );
+}

package/src/drivers/clock-postgres.ts

@@ -0,0 +1,410 @@
+/**
+ * `postgres` clock driver — multi-host CronStore via SKIP LOCKED + lease reclaim.
+ *
+ * Same concurrency physics as Signal's `once` delivery (`signal-postgres.ts`):
+ * claim with `FOR UPDATE SKIP LOCKED`; a crashed holder's lease is reclaimed
+ * lazily on the next claim attempt (no sweeper).
+ */
+
+import type { CronRow, CronStatus, CronStore } from "../elements/clock/reconcile.ts";
+import { toPostgresParams } from "./postgres.ts";
+
+/** Row shape in `oke_crons` (lease columns mirror `oke_signal_messages`). */
+interface CronDbRow {
+  name: string;
+  declared_cron: string | null;
+  declared_every: string | null;
+  override_cron: string | null;
+  override_every: string | null;
+  effective_cron: string | null;
+  effective_every: string | null;
+  timezone: string;
+  overridable: boolean | number;
+  status: string;
+  locked_by: string | null;
+  lease_expires_at: number | null;
+  last_run_at: number | null;
+  next_run_at: number | null;
+  dst_ambiguity: string | null;
+}
+
+/** Minimal SQL + transaction surface for the postgres cron store. */
+export interface PostgresCronSql {
+  query(sql: string, params?: readonly unknown[]): Promise<Record<string, unknown>[]>;
+  exec(sql: string, params?: readonly unknown[]): Promise<{ changes: number }>;
+  /**
+   * Run `fn` inside a transaction. Nested calls join the outer txn.
+   *
+   * @param fn - Body
+   */
+  begin<T>(fn: (sql: PostgresCronSql) => Promise<T>): Promise<T>;
+  close(): Promise<void>;
+}
+
+/**
+ * Claim a cron row for lease acquire / renew / reclaim.
+ *
+ * Claimable when unlocked, same holder renewing, or lease expired
+ * (lazy reclaim — matches Signal's once-claim predicate).
+ */
+const CLAIM_LEASE_SQL = `SELECT * FROM oke_crons WHERE name=? AND ((locked_by IS NULL) OR (locked_by=?) OR (lease_expires_at IS NOT NULL AND lease_expires_at<=?)) FOR UPDATE SKIP LOCKED`;
+
+/** Options for {@link createPostgresCronStore}. */
+export interface CreatePostgresCronStoreOptions {
+  /** Postgres connection URL (Bun.SQL). Ignored when `sql` is injected. */
+  readonly url?: string;
+  /** Injected SQL surface (tests / fakes). */
+  readonly sql?: PostgresCronSql;
+  /** Injected Bun.SQL-compatible client. */
+  readonly client?: BunCronClient;
+}
+
+/** Minimal Bun.SQL surface used by the real driver. */
+export interface BunCronClient {
+  unsafe(
+    sql: string,
+    values?: unknown[],
+  ): PromiseLike<Record<string, unknown>[] | { length: number; changes?: number }>;
+  begin<T>(fn: (tx: BunCronClient) => Promise<T> | T): Promise<T>;
+  close?(options?: { timeout?: number }): Promise<void>;
+}
+
+function wrapBunClient(client: BunCronClient): PostgresCronSql {
+  const api: PostgresCronSql = {
+    async query(sql, params = []) {
+      const pg = toPostgresParams(sql);
+      const result = await client.unsafe(pg, [...params]);
+      if (Array.isArray(result)) return result as Record<string, unknown>[];
+      return Array.from(result as ArrayLike<Record<string, unknown>>);
+    },
+    async exec(sql, params = []) {
+      const pg = toPostgresParams(sql);
+      const result = await client.unsafe(pg, [...params]);
+      if (
+        result &&
+        typeof result === "object" &&
+        "changes" in result &&
+        typeof (result as { changes: unknown }).changes === "number"
+      ) {
+        return { changes: (result as { changes: number }).changes };
+      }
+      if (Array.isArray(result)) return { changes: result.length };
+      return { changes: 0 };
+    },
+    async begin(fn) {
+      return client.begin(async (tx) => fn(wrapBunClient(tx)));
+    },
+    async close() {
+      await client.close?.();
+    },
+  };
+  return api;
+}
+
+function strOrUndef(v: unknown): string | undefined {
+  if (v === undefined || v === null || v === "") return undefined;
+  return String(v);
+}
+
+function numOrUndef(v: unknown): number | undefined {
+  if (v === undefined || v === null || v === "") return undefined;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function rowToCron(row: Record<string, unknown>): CronRow {
+  const dstRaw = row.dst_ambiguity;
+  let dstAmbiguity: CronRow["dstAmbiguity"];
+  if (typeof dstRaw === "string" && dstRaw.trim()) {
+    dstAmbiguity = JSON.parse(dstRaw) as CronRow["dstAmbiguity"];
+  }
+  return {
+    name: String(row.name),
+    declaredCron: strOrUndef(row.declared_cron),
+    declaredEvery: strOrUndef(row.declared_every),
+    overrideCron: strOrUndef(row.override_cron),
+    overrideEvery: strOrUndef(row.override_every),
+    effectiveCron: strOrUndef(row.effective_cron),
+    effectiveEvery: strOrUndef(row.effective_every),
+    timezone: String(row.timezone ?? "UTC"),
+    overridable: Boolean(row.overridable),
+    status: String(row.status) as CronStatus,
+    leaderInstanceId: strOrUndef(row.locked_by),
+    leaderLeaseUntil: numOrUndef(row.lease_expires_at),
+    lastRunAt: numOrUndef(row.last_run_at),
+    nextRunAt: numOrUndef(row.next_run_at),
+    dstAmbiguity,
+  };
+}
+
+function cronToParams(row: CronRow): unknown[] {
+  return [
+    row.name,
+    row.declaredCron ?? null,
+    row.declaredEvery ?? null,
+    row.overrideCron ?? null,
+    row.overrideEvery ?? null,
+    row.effectiveCron ?? null,
+    row.effectiveEvery ?? null,
+    row.timezone,
+    row.overridable,
+    row.status,
+    row.leaderInstanceId ?? null,
+    row.leaderLeaseUntil ?? null,
+    row.lastRunAt ?? null,
+    row.nextRunAt ?? null,
+    row.dstAmbiguity ? JSON.stringify(row.dstAmbiguity) : null,
+  ];
+}
+
+async function ensureSchema(sql: PostgresCronSql): Promise<void> {
+  await sql.exec(`CREATE TABLE IF NOT EXISTS oke_crons (
+    name TEXT PRIMARY KEY,
+    declared_cron TEXT,
+    declared_every TEXT,
+    override_cron TEXT,
+    override_every TEXT,
+    effective_cron TEXT,
+    effective_every TEXT,
+    timezone TEXT NOT NULL,
+    overridable BOOLEAN NOT NULL DEFAULT FALSE,
+    status TEXT NOT NULL,
+    locked_by TEXT,
+    lease_expires_at BIGINT,
+    last_run_at BIGINT,
+    next_run_at BIGINT,
+    dst_ambiguity TEXT
+  )`);
+}
+
+/**
+ * In-memory Postgres-protocol fake with transactions + SKIP LOCKED for tests.
+ */
+export function createPostgresCronFake(): PostgresCronSql & {
+  /** Force-kill mid-transaction (drops uncommitted state). */
+  killActiveTransaction(): void;
+} {
+  type State = { rows: CronDbRow[] };
+
+  let committed: State = { rows: [] };
+  let active: { state: State; locked: Set<string>; done: boolean } | null = null;
+  /** Names held by other active transactions (SKIP LOCKED). */
+  const heldByTxn = new Set<string>();
+  /** Serialize top-level begins so concurrent acquires cannot join one txn. */
+  let beginGate: Promise<void> = Promise.resolve();
+
+  function view(): State {
+    return active?.state ?? committed;
+  }
+
+  function cloneState(s: State): State {
+    return { rows: s.rows.map((r) => ({ ...r })) };
+  }
+
+  const api: PostgresCronSql & { killActiveTransaction(): void } = {
+    killActiveTransaction() {
+      if (active) {
+        for (const name of active.locked) heldByTxn.delete(name);
+        active = null;
+      }
+    },
+    async query(sql, params = []) {
+      const text = sql.trim();
+      const state = view();
+
+      const isClaim = /FOR\s+UPDATE\s+SKIP\s+LOCKED/i.test(text) && /oke_crons/i.test(text);
+      if (isClaim) {
+        const name = String(params[0]);
+        const holder = String(params[1]);
+        const leaseCutoff = Number(params[2]);
+        if (heldByTxn.has(name) && !(active?.locked.has(name) ?? false)) {
+          return [];
+        }
+        const row = state.rows.find((r) => {
+          if (r.name !== name) return false;
+          const unlocked = r.locked_by === null;
+          const renew = r.locked_by === holder;
+          const expired = r.lease_expires_at !== null && r.lease_expires_at <= leaseCutoff;
+          return unlocked || renew || expired;
+        });
+        if (!row) return [];
+        if (active) {
+          active.locked.add(name);
+          heldByTxn.add(name);
+        }
+        return [{ ...row }];
+      }
+
+      const byName = /^SELECT\s+\*\s+FROM\s+oke_crons\s+WHERE\s+name\s*=\s*\?\s*$/i.exec(text);
+      if (byName) {
+        return state.rows.filter((r) => r.name === params[0]).map((r) => ({ ...r }));
+      }
+
+      const all = /^SELECT\s+\*\s+FROM\s+oke_crons\s*$/i.exec(text);
+      if (all) {
+        return state.rows.map((r) => ({ ...r }));
+      }
+
+      throw new Error(`postgres cron fake: unsupported query: ${sql}`);
+    },
+    async exec(sql, params = []) {
+      const text = sql.trim();
+      const state = view();
+
+      if (/^CREATE\s+TABLE/i.test(text)) return { changes: 0 };
+
+      const upsert =
+        /^INSERT\s+INTO\s+oke_crons\s*\(([^)]+)\)\s*VALUES\s*\(([^)]+)\)\s*ON\s+CONFLICT\s*\(\s*name\s*\)\s*DO\s+UPDATE\s+SET\s+.+$/i.exec(
+          text,
+        );
+      if (upsert) {
+        const cols = upsert[1]!.split(",").map((c) => c.trim());
+        const record: Record<string, unknown> = {};
+        cols.forEach((c, i) => {
+          record[c] = params[i];
+        });
+        const next: CronDbRow = {
+          name: String(record.name),
+          declared_cron: (record.declared_cron as string | null) ?? null,
+          declared_every: (record.declared_every as string | null) ?? null,
+          override_cron: (record.override_cron as string | null) ?? null,
+          override_every: (record.override_every as string | null) ?? null,
+          effective_cron: (record.effective_cron as string | null) ?? null,
+          effective_every: (record.effective_every as string | null) ?? null,
+          timezone: String(record.timezone ?? "UTC"),
+          overridable: Boolean(record.overridable),
+          status: String(record.status),
+          locked_by: (record.locked_by as string | null) ?? null,
+          lease_expires_at:
+            record.lease_expires_at === undefined || record.lease_expires_at === null
+              ? null
+              : Number(record.lease_expires_at),
+          last_run_at:
+            record.last_run_at === undefined || record.last_run_at === null
+              ? null
+              : Number(record.last_run_at),
+          next_run_at:
+            record.next_run_at === undefined || record.next_run_at === null
+              ? null
+              : Number(record.next_run_at),
+          dst_ambiguity: (record.dst_ambiguity as string | null) ?? null,
+        };
+        const idx = state.rows.findIndex((r) => r.name === next.name);
+        if (idx >= 0) state.rows[idx] = next;
+        else state.rows.push(next);
+        return { changes: 1 };
+      }
+
+      const updLease =
+        /^UPDATE\s+oke_crons\s+SET\s+locked_by\s*=\s*\?,\s*lease_expires_at\s*=\s*\?\s+WHERE\s+name\s*=\s*\?\s*$/i.exec(
+          text,
+        );
+      if (updLease) {
+        const row = state.rows.find((r) => r.name === params[2]);
+        if (!row) return { changes: 0 };
+        row.locked_by = params[0] === null ? null : String(params[0]);
+        row.lease_expires_at =
+          params[1] === null || params[1] === undefined ? null : Number(params[1]);
+        return { changes: 1 };
+      }
+
+      throw new Error(`postgres cron fake: unsupported exec: ${sql}`);
+    },
+    async begin(fn) {
+      // Nested begin (same call stack) joins the open txn.
+      if (active && !active.done) {
+        return fn(api);
+      }
+      // Top-level begins serialize so Promise.all racing acquires stay exclusive.
+      let release!: () => void;
+      const slot = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      const prev = beginGate;
+      beginGate = slot;
+      await prev;
+      active = { state: cloneState(committed), locked: new Set(), done: false };
+      try {
+        const result = await fn(api);
+        if (active) {
+          for (const name of active.locked) heldByTxn.delete(name);
+          committed = active.state;
+          active.done = true;
+          active = null;
+        }
+        return result;
+      } catch (err) {
+        if (active) {
+          for (const name of active.locked) heldByTxn.delete(name);
+        }
+        active = null;
+        throw err;
+      } finally {
+        release();
+      }
+    },
+    async close() {
+      active = null;
+      heldByTxn.clear();
+    },
+  };
+
+  return api;
+}
+
+const UPSERT_SQL = `INSERT INTO oke_crons (name, declared_cron, declared_every, override_cron, override_every, effective_cron, effective_every, timezone, overridable, status, locked_by, lease_expires_at, last_run_at, next_run_at, dst_ambiguity) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT (name) DO UPDATE SET declared_cron = EXCLUDED.declared_cron, declared_every = EXCLUDED.declared_every, override_cron = EXCLUDED.override_cron, override_every = EXCLUDED.override_every, effective_cron = EXCLUDED.effective_cron, effective_every = EXCLUDED.effective_every, timezone = EXCLUDED.timezone, overridable = EXCLUDED.overridable, status = EXCLUDED.status, locked_by = EXCLUDED.locked_by, lease_expires_at = EXCLUDED.lease_expires_at, last_run_at = EXCLUDED.last_run_at, next_run_at = EXCLUDED.next_run_at, dst_ambiguity = EXCLUDED.dst_ambiguity`;
+
+/**
+ * Open a postgres-backed CronStore (multi-host leader election).
+ *
+ * @param options - URL / injected sql / Bun.SQL client
+ */
+export async function createPostgresCronStore(
+  options: CreatePostgresCronStoreOptions = {},
+): Promise<CronStore & { readonly sql: PostgresCronSql; close(): Promise<void> }> {
+  const sql =
+    options.sql ??
+    wrapBunClient(
+      options.client ??
+        (new Bun.SQL(
+          options.url ?? process.env.DATABASE_URL ?? "postgres://localhost:5432/oke",
+        ) as unknown as BunCronClient),
+    );
+
+  await ensureSchema(sql);
+
+  const store: CronStore & { readonly sql: PostgresCronSql; close(): Promise<void> } = {
+    kind: "postgres",
+    sql,
+    async get(name) {
+      const rows = await sql.query(`SELECT * FROM oke_crons WHERE name = ?`, [name]);
+      if (!rows[0]) return undefined;
+      return rowToCron(rows[0]);
+    },
+    async put(row) {
+      await sql.exec(UPSERT_SQL, cronToParams(row));
+    },
+    async list() {
+      const rows = await sql.query(`SELECT * FROM oke_crons`);
+      return rows.map((r) => rowToCron(r));
+    },
+    async acquireLease(name, instanceId, now, leaseMs) {
+      return sql.begin(async (tx) => {
+        const claimed = await tx.query(CLAIM_LEASE_SQL, [name, instanceId, now]);
+        if (!claimed[0]) return false;
+        const until = now + leaseMs;
+        await tx.exec(`UPDATE oke_crons SET locked_by = ?, lease_expires_at = ? WHERE name = ?`, [
+          instanceId,
+          until,
+          name,
+        ]);
+        return true;
+      });
+    },
+    async close() {
+      await sql.close();
+    },
+  };
+
+  return store;
+}

package/src/drivers/index.ts

@@ -106,6 +106,23 @@ export {
   type PostgresSignalSql,
 } from "./signal-postgres.ts";
 
+export {
+  createPostgresCronStore,
+  createPostgresCronFake,
+  type PostgresCronSql,
+  type CreatePostgresCronStoreOptions,
+  type BunCronClient,
+} from "./clock-postgres.ts";
+
+export {
+  createPostgresJournalStore,
+  createPostgresJournalFake,
+  type PostgresJournalSql,
+  type PostgresJournalStore,
+  type CreatePostgresJournalStoreOptions,
+  type BunJournalClient,
+} from "./journal-postgres.ts";
+
 export {
   redisSignalDriver,
   openRedisSignal,
@@ -144,6 +161,7 @@ export { smtpChannelDriver, openSmtpChannel } from "./channel-smtp.ts";
 export { resendChannelDriver, openResendChannel } from "./channel-resend.ts";
 export { sndrChannelDriver, openSndrChannel } from "./channel-sndr.ts";
 export { taqnyatChannelDriver, openTaqnyatChannel } from "./channel-taqnyat.ts";
+export { taqnyatMailChannelDriver, openTaqnyatMailChannel } from "./channel-taqnyat-mail.ts";
 export { msegatChannelDriver, openMsegatChannel } from "./channel-msegat.ts";
 export { unifonicChannelDriver, openUnifonicChannel } from "./channel-unifonic.ts";
 export { waCloudChannelDriver, openWaCloudChannel } from "./channel-wa-cloud.ts";