okengine 0.6.0 → 0.7.0

package/src/elements/clock.test.ts

@@ -3,8 +3,12 @@
  * - 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)
+ * - catch-up `"one"` after multi-slot downtime
+ * - DST gap/overlap detect-only; overlap civil physics
+ * - overridable edit accept / reject
  * - reconciliation marks a removed cron orphaned without deleting it
- * - DST ambiguity detected from expression + zone
+ *
+ * Multi-process / SIGKILL proofs live in `clock/chaos.test.ts`.
  */
 
 import { describe, expect, test } from "bun:test";
@@ -20,10 +24,14 @@ import {
   createMemoryCronStore,
   createTestClockRuntime,
   createTimeTravel,
+  cronHealth,
   detectDstAmbiguity,
+  editSchedule,
+  nextOccurrences,
   parseDurationMs,
   reconcileClocks,
   runDurable,
+  ScheduleNotOverridableError,
   tryAcquireLease,
 } from "./clock.ts";
 
@@ -323,6 +331,41 @@ describe("reconciliation", () => {
   });
 });
 
+describe("catch-up policy one", () => {
+  test("5h downtime on hourly clock: one fire, missedRuns reflects the gap", async () => {
+    const store = createMemoryCronStore();
+    const rt = createTestClockRuntime(0, {
+      store,
+      instanceId: "catchup",
+      leaseMs: 60_000,
+    });
+    rt.register(clock("hourly", { every: "1h" }));
+    await rt.reconcile();
+    await store.put({
+      ...(await store.get("hourly"))!,
+      lastRunAt: 0,
+    });
+
+    rt.advance("5h");
+    const before = cronHealth((await store.get("hourly"))!, rt.now());
+    expect(before.overdue).toBe(true);
+    expect(before.missedRuns).toBe(5);
+    expect(before.catchUp).toBe("one");
+
+    const fired: number[] = [];
+    rt.onCron("hourly", () => {
+      fired.push(rt.now());
+    });
+    const { ran } = await rt.tick();
+    expect(ran).toEqual(["hourly"]);
+    expect(fired).toHaveLength(1);
+
+    // Not five catch-up runs — and not silently zero.
+    await rt.tick();
+    expect(fired).toHaveLength(1);
+  });
+});
+
 describe("DST ambiguity", () => {
   test("detected from expression plus zone", () => {
     // 02:00 America/New_York sits in the spring-forward gap / fall-back overlap.
@@ -340,7 +383,17 @@ describe("DST ambiguity", () => {
     expect(detectDstAmbiguity("0 12 * * *", "America/New_York", Date.UTC(2026, 0, 1))).toBeNull();
   });
 
-  test("reconcile attaches dstAmbiguity on the store row", async () => {
+  test("gap vs overlap kinds are distinct for US transitions", () => {
+    // 2026-03-08 spring forward → 02:00 skipped (gap).
+    const gap = detectDstAmbiguity("0 2 * * *", "America/New_York", Date.UTC(2026, 2, 1));
+    expect(gap?.kind).toBe("gap");
+
+    // 2026-11-01 fall back → 01:30 occurs twice (overlap).
+    const overlap = detectDstAmbiguity("30 1 * * *", "America/New_York", Date.UTC(2026, 10, 1));
+    expect(overlap?.kind).toBe("overlap");
+  });
+
+  test("reconcile attaches dstAmbiguity on the store row (passive warning)", async () => {
     const store = createMemoryCronStore();
     const rt = createTestClockRuntime(Date.UTC(2026, 0, 1), {
       store,
@@ -352,9 +405,118 @@ describe("DST ambiguity", () => {
         timezone: "America/New_York",
       }),
     );
+    // Detection never throws — warn-only, no schedule rewrite.
     await rt.reconcile();
     const row = await store.get("nightly");
     expect(row?.dstAmbiguity).toBeDefined();
     expect(row?.dstAmbiguity?.localTime).toBe("02:00");
+    expect(row?.status).toBe("active");
+    expect(row?.effectiveCron).toBe("0 2 * * *");
+  });
+
+  test("doctor does not enforce or surface DST (detection is Console-only)", async () => {
+    const doctorSrc = await Bun.file(new URL("../cli/doctor.ts", import.meta.url)).text();
+    expect(doctorSrc.toLowerCase()).not.toContain("dst");
+    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).
+    const from = Date.UTC(2026, 10, 1, 0, 0, 0);
+    const until = Date.UTC(2026, 10, 2, 0, 0, 0);
+    const fires = nextOccurrences(
+      {
+        name: "ambig",
+        effectiveCron: "30 1 * * *",
+        timezone: "America/New_York",
+        overridable: false,
+        status: "active",
+      },
+      from,
+      until,
+    );
+    expect(fires.length).toBe(2);
+    expect(fires[1]! - fires[0]!).toBe(3_600_000);
+
+    // 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, {
+      store,
+      instanceId: "dst-fire",
+      leaseMs: 1_000,
+    });
+    rt.register(
+      clock("ambig", {
+        cron: "30 1 * * *",
+        timezone: "America/New_York",
+      }),
+    );
+    await rt.reconcile();
+    const ran: number[] = [];
+    rt.onCron("ambig", () => {
+      ran.push(rt.now());
+    });
+    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);
+  });
+});
+
+describe("overridable Console edit", () => {
+  test("editSchedule accepts overridable and rejects locked clocks", async () => {
+    const store = createMemoryCronStore();
+    await reconcileClocks(
+      [
+        clock("tunable", { every: "1h", overridable: true }),
+        clock("locked", { cron: "0 2 * * *", overridable: false }),
+      ],
+      store,
+    );
+
+    const edited = await editSchedule(store, { name: "tunable", every: "5m" });
+    expect(edited.effectiveEvery).toBe("5m");
+    expect(edited.overrideEvery).toBe("5m");
+
+    await expect(editSchedule(store, { name: "locked", cron: "0 3 * * *" })).rejects.toBeInstanceOf(
+      ScheduleNotOverridableError,
+    );
+    await expect(editSchedule(store, { name: "locked", cron: "0 3 * * *" })).rejects.toThrow(
+      /not overridable/,
+    );
   });
 });

package/src/elements/clock.ts

@@ -29,6 +29,7 @@ export {
   reconcileClocks,
   effectiveSchedule,
   createMemoryCronStore,
+  createFileCronStore,
   type CronRow,
   type CronStatus,
   type CronStore,

package/src/elements/gate/runtime.ts

@@ -8,6 +8,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";
   eval<T = unknown>(script: string, keys: readonly string[], args?: readonly string[]): Promise<T>;
 }
 
@@ -35,6 +37,8 @@ export interface GateEvaluation {
 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;
   /**
    * Evaluate a gate chain in order; stop on first denial.
    *
@@ -64,6 +68,7 @@ export function createGateRuntime(options: CreateGateRuntimeOptions = {}): GateR
     map.set(g.name, g);
   }
   const now = options.now ?? (() => Date.now());
+  const kvDriverId = options.kv?.driverId;
 
   async function evaluateOne(name: string, ctx: GatePolicyContext): Promise<GateEvaluation> {
     const decl = map.get(name);
@@ -125,6 +130,7 @@ export function createGateRuntime(options: CreateGateRuntimeOptions = {}): GateR
 
   return {
     gates: map,
+    kvDriverId,
     async check(names, ctx) {
       const out: GateEvaluation[] = [];
       for (const name of names) {

package/src/elements/index.ts

@@ -132,6 +132,11 @@ export {
   RetryTransport,
   FallbackTransport,
   FallbackError,
+  parseSndrWebhook,
+  verifySndrSignature,
+  parseUnifonicWebhook,
+  toChannelSendResult,
+  toDeliveryEvent,
 } from "./channel.ts";
 export type {
   ChannelTemplateDecl,
@@ -150,6 +155,10 @@ export type {
   Transport,
   MediumCosts,
   EmailAuthResult,
+  EmailEvent,
+  DeliveryEvent,
+  AnySendResult,
+  SentlyChannelSendResult,
 } from "./channel.ts";
 
 export {

package/src/elements/signal/chaos-child.ts

@@ -2,9 +2,11 @@
  * Chaos child — begins a transaction, stages write + emit, then exits
  * before commit (or is SIGKILL'd by the parent). Used by signal.test.ts.
  *
- * Args: <durablePath> <mode>
- *   mode = "mid-txn" → write + emit, then exit(99) without commit
- *   mode = "commit"  → write + emit + commit, then exit(0)
+ * Args: <durablePath> <mode> [markerPath] [leaseMs]
+ *   mode = "mid-txn"      → write + emit, then exit(99) without commit
+ *   mode = "commit"       → write + emit + commit, then exit(0)
+ *   mode = "consume-hang" → subscribe, drain one message, write marker, hang
+ *                           (parent SIGKILL after claim; lease reclaim tested)
  */
 
 import { join } from "node:path";
@@ -14,9 +16,13 @@ import { createSignalRuntime } from "./runtime.ts";
 
 const durablePath = process.argv[2];
 const mode = process.argv[3] ?? "mid-txn";
+const markerPath = process.argv[4];
+const leaseMs = process.argv[5] !== undefined ? Number(process.argv[5]) : undefined;
 
 if (!durablePath) {
-  console.error("usage: chaos-child <durablePath> <mid-txn|commit>");
+  console.error(
+    "usage: chaos-child <durablePath> <mid-txn|commit|consume-hang> [markerPath] [leaseMs]",
+  );
   process.exit(2);
 }
 
@@ -24,8 +30,39 @@ const orderPlaced = signal("order-placed", {
   delivery: "once",
   retries: 3,
   deadLetter: true,
+  // Producer-only / cross-process consumer: no local subscriber at emit time.
+  optional: true,
 });
 
+if (mode === "consume-hang") {
+  if (!markerPath) {
+    console.error("consume-hang requires markerPath");
+    process.exit(2);
+  }
+  const runtime = createSignalRuntime({
+    driver: memorySignalDriver,
+    durablePath: join(durablePath),
+    leaseMs: Number.isFinite(leaseMs) ? leaseMs : 50,
+  });
+  runtime.register(orderPlaced);
+  const bus = await runtime.start();
+  let claimed = false;
+  await bus.subscribe("order-placed", "chaos-consumer", async () => {
+    claimed = true;
+    await Bun.write(markerPath, "claimed");
+    // Hang while holding the claim — parent will SIGKILL before ack.
+    await Bun.sleep(60_000);
+  });
+  await bus.drain();
+  if (!claimed) {
+    console.error("consume-hang: no message claimed");
+    process.exit(3);
+  }
+  // Should be unreachable — parent kills us while sleeping in the handler.
+  await Bun.sleep(60_000);
+  process.exit(0);
+}
+
 const runtime = createSignalRuntime({
   driver: memorySignalDriver,
   durablePath: join(durablePath),

package/src/elements/signal/declare.ts

@@ -23,7 +23,10 @@ export interface SignalOptions {
   readonly retries?: number;
   /** Preserve exhausted messages in the DLQ (once). */
   readonly deadLetter?: boolean;
-  /** Optional payload schema (Standard Schema / opaque). */
+  /**
+   * Optional payload schema (Standard Schema).
+   * Enforced at `emit` via the same `validate()` path as Flow `in`.
+   */
   readonly schema?: unknown;
   /** Allow emit with zero subscribers (skip orphan check). */
   readonly optional?: boolean;

package/src/elements/signal/delivery-modes.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Signal delivery-mode adversarial proofs:
+ * - once: one message → exactly one of two competing consumers
+ * - once: retries then DLQ (and deadLetter: false)
+ * - broadcast: every subscriber gets a copy
+ * - live: late subscriber replays full retained history (unbounded)
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+
+import {
+  createPostgresSignalFake,
+  createSignalNatsFake,
+  createSignalRedisFake,
+  memorySignalDriver,
+  natsSignalDriver,
+  postgresSignalDriver,
+  redisSignalDriver,
+  type SignalBus,
+  type SignalDriver,
+} from "../../drivers/index.ts";
+import { signal, type SignalDecl } from "./declare.ts";
+
+const drivers: Array<{
+  label: string;
+  driver: SignalDriver;
+  setup?: () => Record<string, unknown>;
+}> = [
+  { label: "memory", driver: memorySignalDriver },
+  {
+    label: "postgres",
+    driver: postgresSignalDriver,
+    setup: () => ({ sql: createPostgresSignalFake() }),
+  },
+  {
+    label: "redis",
+    driver: redisSignalDriver,
+    setup: () => ({ redis: createSignalRedisFake() }),
+  },
+  {
+    label: "nats",
+    driver: natsSignalDriver,
+    setup: () => ({ nats: createSignalNatsFake() }),
+  },
+];
+
+const openBuses: SignalBus[] = [];
+
+afterEach(async () => {
+  while (openBuses.length) {
+    await openBuses.pop()!.close();
+  }
+});
+
+async function openBus(
+  driver: SignalDriver,
+  decls: readonly SignalDecl[],
+  extra: Record<string, unknown> = {},
+): Promise<SignalBus> {
+  const signals = new Map(decls.map((d) => [d.name, d]));
+  const bus = await driver.open({
+    signals,
+    ...extra,
+  });
+  openBuses.push(bus);
+  return bus;
+}
+
+for (const { label, driver, setup } of drivers) {
+  describe(`signal delivery modes · ${label}`, () => {
+    test("once: one message reaches exactly one of two competing consumers", async () => {
+      // Shape matches Linkly linkClicked / Provisions order-placed.
+      const once = signal("link-clicked", {
+        delivery: "once",
+        retries: 3,
+        deadLetter: true,
+      });
+      const bus = await openBus(driver, [once], setup?.() ?? {});
+      const got: string[] = [];
+
+      await bus.subscribe("link-clicked", "worker-a", async (m) => {
+        got.push(`a:${(m.payload as { code: string }).code}`);
+      });
+      await bus.subscribe("link-clicked", "worker-b", async (m) => {
+        got.push(`b:${(m.payload as { code: string }).code}`);
+      });
+
+      await bus.emit("link-clicked", { code: "abc" });
+      await bus.drain();
+
+      expect(got).toHaveLength(1);
+      expect(got[0] === "a:abc" || got[0] === "b:abc").toBe(true);
+    });
+
+    test("once: retries+1 attempts then dead-letter when deadLetter: true", async () => {
+      const once = signal("flaky", {
+        delivery: "once",
+        retries: 2,
+        deadLetter: true,
+      });
+      const bus = await openBus(driver, [once], setup?.() ?? {});
+      let attempts = 0;
+      await bus.subscribe("flaky", "c1", async () => {
+        attempts += 1;
+        throw new Error(`boom-${attempts}`);
+      });
+
+      await bus.emit("flaky", { x: 1 });
+      await bus.drain();
+
+      // attempts > retries ⇒ retries + 1 total handler invocations.
+      expect(attempts).toBe(3);
+      const dlq = await bus.deadLetters("flaky");
+      expect(dlq).toHaveLength(1);
+      expect(dlq[0]!.failures.map((f) => f.attempt)).toEqual([1, 2, 3]);
+    });
+
+    test("once: deadLetter: false marks delivered after exhausting retries", async () => {
+      const once = signal("flaky-drop", {
+        delivery: "once",
+        retries: 1,
+        deadLetter: false,
+      });
+      const bus = await openBus(driver, [once], setup?.() ?? {});
+      let attempts = 0;
+      await bus.subscribe("flaky-drop", "c1", async () => {
+        attempts += 1;
+        throw new Error("nope");
+      });
+
+      await bus.emit("flaky-drop", { x: 1 });
+      await bus.drain();
+
+      expect(attempts).toBe(2);
+      expect(await bus.deadLetters("flaky-drop")).toHaveLength(0);
+      const stats = await bus.inspect("flaky-drop");
+      expect(stats[0]?.dead).toBe(0);
+      expect(stats[0]?.delivered).toBe(1);
+    });
+
+    test("broadcast: every subscriber receives its own copy", async () => {
+      const bcast = signal("news", { delivery: "broadcast" });
+      const bus = await openBus(driver, [bcast], setup?.() ?? {});
+      const a: unknown[] = [];
+      const b: unknown[] = [];
+      await bus.subscribe("news", "sub-a", async (m) => {
+        a.push(m.payload);
+      });
+      await bus.subscribe("news", "sub-b", async (m) => {
+        b.push(m.payload);
+      });
+
+      await bus.emit("news", { headline: "hi" });
+      await bus.drain();
+
+      expect(a).toEqual([{ headline: "hi" }]);
+      expect(b).toEqual([{ headline: "hi" }]);
+    });
+
+    test("live: late subscriber replays full retained history (unbounded)", async () => {
+      // Shape matches Skyport seat-feed.
+      const live = signal("seat-feed", { delivery: "live", optional: true });
+      const bus = await openBus(driver, [live], setup?.() ?? {});
+
+      await bus.emit("seat-feed", { seat: "12A" });
+      await bus.emit("seat-feed", { seat: "12B" });
+      await bus.emit("seat-feed", { seat: "12C" });
+      await bus.drain();
+
+      const late: unknown[] = [];
+      await bus.live("seat-feed", (payload) => {
+        late.push(payload);
+      });
+
+      // All retained live messages replay — not the Console recentLive cap of 50.
+      expect(late).toEqual([{ seat: "12A" }, { seat: "12B" }, { seat: "12C" }]);
+    });
+  });
+}