okengine 0.12.0 → 0.14.1

package/src/elements/clock/schedule.ts

@@ -1,13 +1,58 @@
 /**
  * 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.
+ * Cron math uses {@link Bun.cron.parse} (5-field + nicknames + `{ tz }`).
+ * Interval (`every`) stays on {@link parseDurationMs}.
  */
 
 import { parseDurationMs } from "./duration.ts";
 import { effectiveSchedule, type CronRow } from "./reconcile.ts";
 
+/**
+ * Bun 1.4 `{ tz }` parse — `@types/bun` 1.3.14 only declares two arguments.
+ *
+ * @param expression - 5-field expression or nickname
+ * @param relativeMs - Exclusive start
+ * @param timezone - IANA zone
+ */
+function parseCronNext(expression: string, relativeMs: number, timezone: string): Date | null {
+  return (
+    Bun.cron.parse as (
+      expression: string,
+      relativeDate?: Date | number,
+      options?: { readonly tz?: string },
+    ) => Date | null
+  )(expression, relativeMs, { tz: timezone });
+}
+
+/** Cap walk loops so a `* * * * *` range cannot hang the Console timeline. */
+const MAX_CRON_FIRES = 10_000;
+/** How far back {@link previousOccurrence} searches for a prior cron fire. */
+const PREVIOUS_LOOKBACK_MS = 400 * 86_400_000;
+
+/**
+ * Next matching UTC epoch-ms after `relativeMs`, or `undefined` when the
+ * expression is invalid or has no match within eight years.
+ *
+ * {@link Bun.cron.parse} is exclusive of `relativeMs`.
+ *
+ * @param cron - 5-field expression or nickname (`@hourly`)
+ * @param relativeMs - Search starts after this instant
+ * @param timezone - IANA zone passed as `{ tz }`
+ */
+export function nextCronFireAt(
+  cron: string,
+  relativeMs: number,
+  timezone: string,
+): number | undefined {
+  try {
+    const next = parseCronNext(cron, relativeMs, timezone);
+    return next === null ? undefined : next.getTime();
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Compute fire times in `[from, until)` for a reconciled cron row.
  *
@@ -24,7 +69,7 @@ export function nextOccurrences(row: CronRow, from: number, until: number): read
     return nextEveryOccurrences(row, sched.every, from, until);
   }
   if (sched.cron) {
-    return nextCronOccurrences(row, sched.cron, sched.timezone, from, until);
+    return nextCronOccurrences(sched.cron, row.timezone, from, until);
   }
   return [];
 }
@@ -41,25 +86,12 @@ export function previousOccurrence(row: CronRow, at: number): number | null {
     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 previousCronFire(sched.cron, row.timezone, at);
   }
   return null;
 }
@@ -77,11 +109,10 @@ export function countMissedOccurrences(row: CronRow, from: number, until: number
   if (sched.every) {
     const interval = parseDurationMs(sched.every);
     if (interval <= 0) return 0;
-    return Math.max(0, Math.floor((until - from) / interval) - 0);
+    return Math.max(0, Math.floor((until - from) / interval));
   }
   if (sched.cron) {
-    // Count fires in (from, until].
-    const fires = nextCronOccurrences(row, sched.cron, sched.timezone, from + 1, until + 1);
+    const fires = nextCronOccurrences(sched.cron, row.timezone, from + 1, until + 1);
     return fires.filter((t) => t > from && t <= until).length;
   }
   return 0;
@@ -102,145 +133,43 @@ function nextEveryOccurrences(
       : 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;
+    if (out.length > MAX_CRON_FIRES) 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;
+  // parse is exclusive of the cursor — step back 1ms so `from` itself can match.
+  let cursor = from - 1;
+  while (out.length < MAX_CRON_FIRES) {
+    const t = nextCronFireAt(cron, cursor, timezone);
+    if (t === undefined || t >= until) break;
+    if (t >= from) out.push(t);
+    cursor = t;
   }
-  return out.sort((a, b) => a - b);
-}
-
-/** Parsed simple daily cron. */
-interface SimpleDaily {
-  readonly minute: number;
-  readonly hour: number;
-  readonly dow?: number;
+  return out;
 }
 
-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 };
+function previousCronFire(cron: string, timezone: string, at: number): number | null {
+  let cursor = at - PREVIOUS_LOOKBACK_MS;
+  let prev: number | null = null;
+  let steps = 0;
+  while (steps < MAX_CRON_FIRES) {
+    const t = nextCronFireAt(cron, cursor, timezone);
+    if (t === undefined || t >= at) break;
+    prev = t;
+    cursor = t;
+    steps++;
   }
-  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;
+  return prev;
 }

package/src/elements/clock.test.ts

@@ -466,8 +466,9 @@ describe("DST ambiguity", () => {
     expect(doctorSrc).not.toMatch(/detectDstAmbiguity/);
   });
 
-  test("overlap day: two civil instants; lease does not span the gap; stub isDue avoids walk", async () => {
-    // US fall-back 2026-11-01: 01:30 local occurs twice (~1h apart in UTC).
+  test("overlap day: crontab fires once; next slot is the following day", async () => {
+    // US fall-back 2026-11-01: 01:30 local occurs twice. Bun.cron.parse
+    // matches crontab — a fixed wall time fires at the first occurrence only.
     const from = Date.UTC(2026, 10, 1, 0, 0, 0);
     const until = Date.UTC(2026, 10, 2, 0, 0, 0);
     const fires = nextOccurrences(
@@ -481,13 +482,11 @@ describe("DST ambiguity", () => {
       from,
       until,
     );
-    expect(fires.length).toBe(2);
-    expect(fires[1]! - fires[0]!).toBe(3_600_000);
+    expect(fires).toHaveLength(1);
+    expect(fires[0]).toBe(Date.UTC(2026, 10, 1, 5, 30, 0));
 
-    // Stub isDue (nextRunAt unset after first fire): does not walk civil fires →
-    // advancing across the overlap gap does not double-fire.
     const store = createMemoryCronStore();
-    const rt = createTestClockRuntime(0, {
+    const rt = createTestClockRuntime(fires[0]! - 1, {
       store,
       instanceId: "dst-fire",
       leaseMs: 1_000,
@@ -503,43 +502,13 @@ describe("DST ambiguity", () => {
     rt.onCron("ambig", () => {
       ran.push(rt.now());
     });
+    rt.advance(2);
     expect((await rt.tick()).ran).toEqual(["ambig"]);
     rt.advance(3_600_000);
     expect((await rt.tick()).ran).toEqual([]);
     expect(ran).toHaveLength(1);
-
-    // Lease TTL << 1h overlap gap: if nextRunAt is driven to the second civil
-    // instant, a second fire CAN occur. Leader lease is not a DST policy.
-    const store2 = createMemoryCronStore();
-    const rt2 = createTestClockRuntime(fires[0]! - 1, {
-      store: store2,
-      instanceId: "dst-risk",
-      leaseMs: 1_000,
-    });
-    rt2.register(
-      clock("ambig2", {
-        cron: "30 1 * * *",
-        timezone: "America/New_York",
-      }),
-    );
-    await rt2.reconcile();
-    await store2.put({
-      ...(await store2.get("ambig2"))!,
-      nextRunAt: fires[0],
-    });
-    const ran2: number[] = [];
-    rt2.onCron("ambig2", () => {
-      ran2.push(rt2.now());
-    });
-    rt2.advance(2);
-    expect((await rt2.tick()).ran).toEqual(["ambig2"]);
-    rt2.advance(fires[1]! - rt2.now());
-    await store2.put({
-      ...(await store2.get("ambig2"))!,
-      nextRunAt: fires[1],
-    });
-    expect((await rt2.tick()).ran).toEqual(["ambig2"]);
-    expect(ran2).toHaveLength(2);
+    const after = await store.get("ambig");
+    expect(after?.nextRunAt).toBeGreaterThan(fires[0]! + 3_600_000);
   });
 });
 

package/src/elements/clock.ts

@@ -50,7 +50,12 @@ export { runDurable, type DurableResult, type RunDurableOptions } from "./clock/
 
 export { cronHealth, type CatchUpPolicy, type CronHealth } from "./clock/health.ts";
 
-export { nextOccurrences, previousOccurrence, countMissedOccurrences } from "./clock/schedule.ts";
+export {
+  nextOccurrences,
+  previousOccurrence,
+  countMissedOccurrences,
+  nextCronFireAt,
+} from "./clock/schedule.ts";
 
 export {
   pauseCron,

package/src/elements/gate/runtime.ts

@@ -16,8 +16,8 @@ import { takeRate } from "./strategies.ts";
 
 /** KV surface required for rate gates. */
 export interface GateKv {
-  /** Driver id when known (`memory` · `redis`). */
-  readonly driverId?: "memory" | "redis";
+  /** Driver id when known (`memory` · `redis`; SQL ids unused on rate gates). */
+  readonly driverId?: "memory" | "redis" | "postgres" | "pglite";
   eval<T = unknown>(script: string, keys: readonly string[], args?: readonly string[]): Promise<T>;
 }
 
@@ -46,7 +46,7 @@ export interface GateRuntime {
   /** Registered declarations by name. */
   readonly gates: ReadonlyMap<string, GateDecl>;
   /** KV backend used for rate limits (`memory` · `redis`, or unset). */
-  readonly kvDriverId: "memory" | "redis" | undefined;
+  readonly kvDriverId: "memory" | "redis" | "postgres" | "pglite" | undefined;
   /**
    * Evaluate a gate chain in order; stop on first denial.
    *

package/src/elements/index.ts

@@ -176,6 +176,8 @@ export type {
   AiModelDecl,
   AiPromptDecl,
   AiAgentDecl,
+  AiMcpServerDecl,
+  AiMcpServerOptions,
   AiEmbedDecl,
   AiRuntime,
   AgentDenial,

package/src/elements/signal/declare.ts

@@ -34,7 +34,8 @@ export interface SignalOptions {
 }
 
 /**
- * Declared signal handle — usable as `on(signal, flow)` and `fx.emit(signal, …)`.
+ * Declared signal handle — usable as `on(signal, flow)`, `fx.emit(signal, …)`,
+ * and `fx.deadLetters(signal)`.
  */
 export interface SignalDecl<T = unknown> {
   /** Signal name (manifest key). */

package/src/elements/signal/runtime.ts

@@ -3,7 +3,12 @@
  * emit / subscribe / live / drain for `fx` and tests.
  */
 
-import type { SignalBus, SignalDriver, SignalEmitOptions } from "../../drivers/signal-types.ts";
+import type {
+  DeadLetter,
+  SignalBus,
+  SignalDriver,
+  SignalEmitOptions,
+} from "../../drivers/signal-types.ts";
 import type { SignalDecl } from "./declare.ts";
 
 /** Options for {@link createSignalRuntime}. */
@@ -48,6 +53,12 @@ export interface SignalRuntime {
    * @param options - Optional emit options (`key` for per-key once ordering)
    */
   emit(name: string, payload?: unknown, options?: SignalEmitOptions): Promise<void>;
+  /**
+   * Dead-lettered messages for one signal (auto-starts).
+   *
+   * @param name - Signal name
+   */
+  deadLetters(name: string): Promise<readonly DeadLetter[]>;
   /** Close the bus. */
   close(): Promise<void>;
 }
@@ -87,6 +98,10 @@ export function createSignalRuntime(options: CreateSignalRuntimeOptions): Signal
       const b = await this.start();
       await b.emit(name, payload, options);
     },
+    async deadLetters(name) {
+      const b = await this.start();
+      return b.deadLetters(name);
+    },
     async close() {
       if (bus) {
         await bus.close();

package/src/elements/signal.ts

@@ -8,6 +8,7 @@
 
 export { signal } from "./signal/declare.ts";
 export type { SignalDecl, SignalOptions } from "./signal/declare.ts";
+export type { DeadLetter, SignalFailureReason } from "../drivers/signal-types.ts";
 
 export { createSignalRuntime } from "./signal/runtime.ts";
 export type { CreateSignalRuntimeOptions, SignalRuntime } from "./signal/runtime.ts";

package/src/elements/store/cache.test.ts

@@ -92,6 +92,7 @@ describe("autoCacheEligible", () => {
       false,
     );
     expect(autoCacheEligible({ effects: { reads: ["runs"] } })).toBe(false);
+    expect(autoCacheEligible({ effects: { reads: ["signal:notify"] } })).toBe(false);
     expect(autoCacheEligible({ effects: {} })).toBe(false);
   });
 
@@ -112,6 +113,7 @@ describe("autoCacheEligible", () => {
         { kind: "read", resource: "sql:views" },
         { kind: "read", resource: "sql:views" },
         { kind: "read", resource: "runs" },
+        { kind: "read", resource: "signal:notify" },
         { kind: "write", resource: "sql:views" },
         { kind: "ask", resource: "summarize" },
         { kind: "emit", resource: "view-changed" },

package/src/elements/store/cache.ts

@@ -53,7 +53,7 @@ export function tier1KeysForReads(
   effects: Effects,
   dimsByResource?: Readonly<Record<string, readonly string[]>>,
 ): string[] {
-  const reads = (effects.reads ?? []).filter((r): r is ResourceRef => r !== "runs");
+  const reads = (effects.reads ?? []).filter((r): r is ResourceRef => isStoreResourceRef(r));
   return reads.map((resource) => computedCacheKey(resource, dimsByResource?.[resource]));
 }
 
@@ -223,7 +223,7 @@ export function resolveCacheEffects(
   declared: Effects | undefined,
   learnedReads: readonly ResourceRef[] | undefined,
 ): Effects {
-  const declaredReads = (declared?.reads ?? []).filter((r) => r !== "runs");
+  const declaredReads = (declared?.reads ?? []).filter((r) => isStoreResourceRef(r));
   if (declaredReads.length > 0 || (declared?.writes?.length ?? 0) > 0) {
     return declared ?? {};
   }
@@ -275,7 +275,7 @@ export function autoCacheEligible(options: {
   const effects = options.effects ?? {};
   if ((effects.asks?.length ?? 0) > 0) return false;
   if ((effects.writes?.length ?? 0) > 0) return false;
-  const reads = (effects.reads ?? []).filter((r) => r !== "runs");
+  const reads = (effects.reads ?? []).filter((r) => isStoreResourceRef(r));
   return reads.length > 0;
 }
 

package/src/elements/store/declare.ts

@@ -74,6 +74,11 @@ export interface SqlStoreDecl extends StoreDeclBase {
 export interface KvStoreOptions {
   /** Optional description. */
   readonly description?: string;
+  /**
+   * Persist this namespace in SQL (`oke_kv` JSONB on `DATABASE_URL`),
+   * not the cache Redis (`REDIS_URL`). Distinct from Flow `durable`.
+   */
+  readonly durable?: boolean;
 }
 
 /** KV store declaration. */
@@ -81,6 +86,7 @@ export interface KvStoreDecl extends StoreDeclBase {
   readonly facet: "kv";
   readonly ref: `kv:${string}`;
   readonly description?: string;
+  readonly durable?: boolean;
 }
 
 /** Options for {@link store.files}. */
@@ -179,6 +185,7 @@ export function kv(name: string, options: KvStoreOptions = {}): KvStoreDecl {
     name,
     ref: `kv:${name}`,
     ...(options.description !== undefined ? { description: options.description } : {}),
+    ...(options.durable === true ? { durable: true } : {}),
   };
 }
 

package/src/elements/store/kv-sql.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Durable KV on `oke_kv` JSONB — round-trip, TTL purge, cache Redis unchanged.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { pgliteDriver } from "../../drivers/pglite.ts";
+import { createRedisFakeClient, redisDriver } from "../../drivers/redis.ts";
+import { memoryDrivers } from "../../drivers/memory.ts";
+import { store } from "./declare.ts";
+import { openSqlKvNamespace } from "./kv-sql.ts";
+import { createStoreRuntime, type KvStoreFxHandle } from "./runtime.ts";
+
+const ctx = { effects: {} };
+
+describe("oke_kv JSONB durable namespace", () => {
+  test("set/get/delete round-trips a JSON object", async () => {
+    const conn = await pgliteDriver.connect({ url: "memory://" });
+    try {
+      const ns = await openSqlKvNamespace({
+        conn,
+        namespace: "ledger",
+        now: () => 1_000_000,
+      });
+      expect(ns.driverId).toBe("pglite");
+      await ns.set("idemp", { orderId: "o1", n: 2 });
+      expect(await ns.get("idemp")).toEqual({ orderId: "o1", n: 2 });
+      expect(await ns.list("id")).toEqual(["idemp"]);
+      expect(await ns.delete("idemp")).toBe(true);
+      expect(await ns.get("idemp")).toBeUndefined();
+    } finally {
+      await conn.close();
+    }
+  });
+
+  test("expired keys are invisible and purgeExpired removes the row", async () => {
+    const conn = await pgliteDriver.connect({ url: "memory://" });
+    let t = 1_000_000;
+    try {
+      const ns = await openSqlKvNamespace({
+        conn,
+        namespace: "ledger",
+        now: () => t,
+      });
+      await ns.set("fresh", { ok: true }, "5s");
+      await ns.set("stale", { ok: false }, "1s");
+      t += 1_500;
+      expect(await ns.get("stale")).toBeUndefined();
+      expect(await ns.get("fresh")).toEqual({ ok: true });
+      const removed = await ns.purgeExpired();
+      expect(removed).toBe(1);
+      const leftover = await conn.query(`SELECT key FROM oke_kv WHERE key = ?`, ["stale"]);
+      expect(leftover).toEqual([]);
+    } finally {
+      await conn.close();
+    }
+  });
+
+  test("non-durable namespace stays on redis; durable uses pglite", async () => {
+    const fake = createRedisFakeClient();
+    const sessions = store.kv("sessions");
+    const ledger = store.kv("ledger", { durable: true });
+    const runtime = createStoreRuntime({
+      drivers: {
+        sql: pgliteDriver,
+        kv: redisDriver,
+        files: memoryDrivers.files,
+        index: memoryDrivers.index,
+      },
+      sqlUrl: "memory://",
+      kv: { sessions: { url: "redis://cache", client: fake } },
+      now: () => 1_000_000,
+    });
+    runtime.register(sessions);
+    runtime.register(ledger);
+    const cache = (await runtime.open(sessions, ctx)) as KvStoreFxHandle;
+    const durable = (await runtime.open(ledger, ctx)) as KvStoreFxHandle;
+    expect(cache.driverId).toBe("redis");
+    expect(durable.driverId).toBe("pglite");
+    await cache.set("sid", { user: "a" });
+    await durable.set("idemp", { orderId: "o1" });
+    expect(await cache.get("sid")).toEqual({ user: "a" });
+    expect(await durable.get("idemp")).toEqual({ orderId: "o1" });
+    expect([...fake.data.keys()].some((k) => k.includes("idemp"))).toBe(false);
+    await runtime.close();
+  });
+});