okengine 0.7.0 → 0.9.0

package/src/kernel/boot.ts

@@ -5,7 +5,9 @@
  * 1. Vault     — resolve every declared secret (list all gaps at once)
  * 2. Store     — bind drivers per environment; open connections
  * 3. Signals   — register declarations; start consumers
- * 4. Clocks    — reconcile into the Store; start scheduler (leader election)
+ * 4. Clocks    — reconcile into the Store
+ * 4b. Journal  — bind the durable-run store (SKIP LOCKED + lease when shared)
+ * 4c. Scheduler — tick clocks + resume due durable runs (leader election)
  * 5. Channel   — bind channel runtime
  * 6. AI        — bind AI runtime
  * 7. Runs      — open the runs store
@@ -33,6 +35,7 @@ import type {
   VaultRuntime,
   VaultSecretDecl,
 } from "../elements/vault.ts";
+import type { JournalRuntime } from "./boot-bind/journal.ts";
 import type { CreateRunsRuntimeOptions, RunsRuntime } from "../runs/index.ts";
 import { createCapabilityToken, type CapabilityToken } from "./capability.ts";
 import type { AnyFlowDef } from "./flow.ts";
@@ -48,6 +51,8 @@ export interface ElementRuntimes {
   readonly channel?: ChannelRuntime;
   readonly ai?: AiRuntime;
   readonly runs?: RunsRuntime;
+  /** Pre-bound durable-run journal (skips driver resolution). */
+  readonly journal?: JournalRuntime;
 }
 
 /** Declarations + options consumed by {@link bootApplication}. */
@@ -112,6 +117,13 @@ export interface BootOptions {
    * @param payload - Payload
    */
   readonly onSignal?: (signal: string, payload: unknown) => void | Promise<void>;
+  /**
+   * Resume due durable runs — called on every scheduler tick when any flow
+   * declares `durable: true` (claimDueSleep on the shared journal store).
+   */
+  readonly onDurableResume?: () => void | Promise<void>;
+  /** Durable-run lease duration ms (default 30_000 — matches Signal claims). */
+  readonly journalLeaseMs?: number;
   /** Injectable clock for test / frozen harnesses. */
   readonly now?: () => number;
   /**
@@ -144,6 +156,8 @@ export interface BootResult {
   readonly channel?: ChannelRuntime;
   readonly ai?: AiRuntime;
   readonly runs?: RunsRuntime;
+  /** Durable-run journal (present when any flow declares `durable: true`). */
+  readonly journal?: JournalRuntime;
   /** Per-flow capability tokens minted from declared effects. */
   readonly capabilities: ReadonlyMap<string, CapabilityToken>;
   /** Stop the background scheduler (if started). */
@@ -162,6 +176,8 @@ export interface ElementNeeds {
   readonly channel: boolean;
   readonly ai: boolean;
   readonly runs: boolean;
+  /** Durable-run journal — any flow with `durable: true`. */
+  readonly journal: boolean;
 }
 
 /**
@@ -182,9 +198,11 @@ export function resolveElementNeeds(options: BootOptions): ElementNeeds {
   let channel = pre.channel !== undefined || options.channel !== undefined;
   let ai = pre.ai !== undefined || options.ai !== undefined;
   let runs = pre.runs !== undefined || options.runs !== undefined;
+  let journal = pre.journal !== undefined;
 
   const considerFlow = (f: AnyFlowDef): void => {
     const e = f.effects;
+    if (f.durable === true) journal = true;
     if ((e?.reads?.length ?? 0) > 0 || (e?.writes?.length ?? 0) > 0) {
       store = true;
     }
@@ -216,7 +234,7 @@ export function resolveElementNeeds(options: BootOptions): ElementNeeds {
     signal = true;
   }
 
-  return { vault, store, signal, clock, gate, channel, ai, runs };
+  return { vault, store, signal, clock, gate, channel, ai, runs, journal };
 }
 
 /**
@@ -272,6 +290,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   type StoreBind = typeof import("./boot-bind/store.ts");
   type SignalBind = typeof import("./boot-bind/signal.ts");
   type ClockBind = typeof import("./boot-bind/clock.ts");
+  type JournalBind = typeof import("./boot-bind/journal.ts");
   type GateBind = typeof import("./boot-bind/gate.ts");
   type ChannelBind = typeof import("./boot-bind/channel.ts");
   type AiBind = typeof import("./boot-bind/ai.ts");
@@ -280,6 +299,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   let storeBind: StoreBind | undefined;
   let signalBind: SignalBind | undefined;
   let clockBind: ClockBind | undefined;
+  let journalBind: JournalBind | undefined;
   let gateBind: GateBind | undefined;
   let channelBind: ChannelBind | undefined;
   let aiBind: AiBind | undefined;
@@ -306,6 +326,13 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
       }),
     );
   }
+  if (needs.journal && !pre.journal) {
+    binderLoads.push(
+      loadBind<JournalBind>("journal").then((m) => {
+        journalBind = m;
+      }),
+    );
+  }
   if (needs.gate && !pre.gate) {
     binderLoads.push(
       loadBind<GateBind>("gate").then((m) => {
@@ -364,21 +391,31 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
     }
   }
 
-  // 4. Clocks + optional scheduler
+  // 4. Clocks
   let clock = pre.clock;
-  let schedulerTimer: ReturnType<typeof setInterval> | undefined;
   if (needs.clock) {
     const bound = await clockBind!.bindClock(options, env, now, clock);
     clock = bound.clock;
-    const startScheduler = options.startScheduler ?? env !== "test";
-    if (startScheduler) {
-      const period = options.schedulerIntervalMs ?? 1000;
-      const clockRt = clock;
-      schedulerTimer = setInterval(() => {
-        void clockRt.tick();
-      }, period);
-      schedulerTimer.unref?.();
-    }
+  }
+
+  // 4b. Journal — durable-run store (shared + leased when a driver is bound).
+  let journal = pre.journal;
+  if (needs.journal && !journal) {
+    journal = (await journalBind!.bindJournal(options, env)).journal;
+  }
+
+  // 4c. Scheduler — one timer drives clock ticks and durable-run resume.
+  let schedulerTimer: ReturnType<typeof setInterval> | undefined;
+  const startScheduler = options.startScheduler ?? env !== "test";
+  if (startScheduler && (clock !== undefined || journal !== undefined)) {
+    const period = options.schedulerIntervalMs ?? 1000;
+    const clockRt = clock;
+    const durableResume = options.onDurableResume;
+    schedulerTimer = setInterval(() => {
+      if (clockRt) void clockRt.tick();
+      if (journal && durableResume) void durableResume();
+    }, period);
+    schedulerTimer.unref?.();
   }
 
   // Gate (before AI)
@@ -427,6 +464,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
     channel,
     ai,
     runs,
+    journal,
     capabilities,
     stopScheduler() {
       if (schedulerTimer !== undefined) {
@@ -442,6 +480,8 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
       await signal?.close();
       await vault?.close();
       await runs?.flush();
+      const journalStore = journal?.store as { close?: () => Promise<void> } | undefined;
+      await journalStore?.close?.();
     },
   };
 }

package/src/kernel/concurrency.ts

@@ -14,7 +14,7 @@ import {
   linkAbort,
   withAbortSignal,
 } from "./abort-scope.ts";
-import { isJournalSuspend } from "./journal.ts";
+import { isJournalSuspend } from "./journal-suspend.ts";
 
 /** A unit of work started under an abort scope. */
 export type FxThunk<T> = () => T | Promise<T>;

package/src/kernel/fx.test.ts

@@ -141,6 +141,15 @@ describe("fx — wholesale swap", () => {
       async send() {
         return { ok: true };
       },
+      async sendOtp() {
+        return { ok: true };
+      },
+      async verifyOtp() {
+        return { ok: true };
+      },
+      async deliverOtp(opts) {
+        return { ok: true as const, channel: opts.only ?? opts.channels[0] ?? "email" };
+      },
       async ask() {
         return {};
       },

package/src/kernel/fx.ts

@@ -11,7 +11,14 @@
 
 import type { Effects, ResourceRef } from "../manifest/types.ts";
 import type {
+  FilesStoreDecl,
+  FilesStoreFxHandle,
+  IndexStoreDecl,
+  IndexStoreFxHandle,
+  KvStoreDecl,
+  KvStoreFxHandle,
   SelectOrderBuilder,
+  SqlStoreDecl,
   StoreDecl,
   StoreHandle,
   StoreRuntime,
@@ -228,6 +235,50 @@ export interface FxSendOptions {
   readonly acceptLanguage?: string;
 }
 
+/** Options for {@link Fx.sendOtp} (provider-managed SMS OTP). */
+export interface FxSendOtpOptions {
+  /** Recipient phone number (E.164). */
+  readonly to: string;
+  /** Unique id for this verification flow (required again on verify). */
+  readonly requestId: string;
+  /** Message language (`en` or `ar`). */
+  readonly lang?: "en" | "ar";
+  /** Optional note appended to the OTP SMS. */
+  readonly note?: string;
+  /** Sender id override. */
+  readonly from?: string;
+}
+
+/** Options for {@link Fx.verifyOtp}. */
+export interface FxVerifyOtpOptions {
+  /** Recipient phone number (same as send). */
+  readonly to: string;
+  /** Same {@link FxSendOtpOptions.requestId} used when sending. */
+  readonly requestId: string;
+  /** OTP code the user entered. */
+  readonly code: string;
+  /** Message language (`en` or `ar`). */
+  readonly lang?: "en" | "ar";
+  /** Sender id override. */
+  readonly from?: string;
+  /** Optional note. */
+  readonly note?: string;
+}
+
+/** Options for {@link Fx.deliverOtp} (Tier-2 multi-channel delivery). */
+export interface FxDeliverOtpOptions {
+  /** Preferred channel order. */
+  readonly channels: readonly ("sms" | "whatsapp" | "email")[];
+  /** Template name per medium. */
+  readonly templates: Readonly<Partial<Record<"sms" | "whatsapp" | "email", string>>>;
+  readonly email?: string;
+  readonly phone?: string;
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly locale?: string;
+  /** Explicit single-channel resend — no cross-medium failover. */
+  readonly only?: "sms" | "whatsapp" | "email";
+}
+
 /** Options for {@link Fx.ask}. */
 export interface FxAskOptions {
   readonly via?: readonly NamedRef[];
@@ -286,10 +337,15 @@ export interface Fx {
    * Open a store handle for `ref` (capability checked on each op).
    *
    * When a {@link CreateFxOptions.storeRuntime} is bound and `ref` is a
-   * registered store declaration, returns the driver-backed handle.
+   * facet declaration, returns the driver-backed handle for that facet.
+   * String / `{ ref }` forms return the in-memory stub (tests).
    *
    * @param ref - Store resource ref, named handle, or store declaration
    */
+  store(ref: SqlStoreDecl): SqlStoreHandle;
+  store(ref: KvStoreDecl): KvStoreFxHandle;
+  store(ref: FilesStoreDecl): FilesStoreFxHandle;
+  store(ref: IndexStoreDecl): IndexStoreFxHandle;
   store(ref: NamedRef | { readonly ref: ResourceRef } | StoreDecl): FxStoreHandle;
   /**
    * Emit a signal (records `emit`).
@@ -327,6 +383,34 @@ export interface Fx {
    * @param opts - Recipient / data
    */
   send(template: NamedRef, opts?: FxSendOptions): Promise<{ ok: true }>;
+  /**
+   * Send a provider-managed SMS OTP (records `send` on `sms-otp`).
+   *
+   * Vendor extra (Taqnyat Verify API) — requires a bound SMS driver that
+   * supports provider-managed OTP. Dry-run records would-have-fired without
+   * contacting the provider.
+   *
+   * @param opts - Recipient + requestId (+ lang / note / from)
+   */
+  sendOtp(opts: FxSendOtpOptions): Promise<{ ok: true }>;
+  /**
+   * Verify a provider-managed SMS OTP code (records `send` on `sms-otp`).
+   *
+   * @param opts - Recipient + requestId + code (+ lang / note / from)
+   */
+  verifyOtp(opts: FxVerifyOtpOptions): Promise<{ ok: true }>;
+  /**
+   * Deliver an app-owned OTP across declared channels (records `send` on `auth-otp`).
+   *
+   * Tier-2 only — uses Channel `deliverOtp` (sently FallbackTransport). Pass
+   * `only` for explicit user resend (single channel, no cross-medium failover).
+   *
+   * @param opts - Channels, templates, addresses, OTP data
+   */
+  deliverOtp(opts: FxDeliverOtpOptions): Promise<{
+    ok: true;
+    channel: "sms" | "whatsapp" | "email";
+  }>;
   /**
    * Ask an AI prompt (records `ask`). Stub returns `{}`.
    *
@@ -837,6 +921,13 @@ export function createFxContext(options: CreateFxOptions): FxContext {
           return h.exists(table, idOrWhere);
         });
       },
+      upsert(table, matchOn, values, upsertOptions) {
+        return gated("write", ref, async () => {
+          refuseDryRunWrite();
+          const h = await ensure();
+          return h.upsert(table, matchOn, values, upsertOptions);
+        });
+      },
       increment(table, id, column, by) {
         return gated("write", ref, async () => {
           refuseDryRunWrite();
@@ -872,10 +963,25 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     } as SqlStoreHandle;
   }
 
+  function storeHandle(ref: SqlStoreDecl): SqlStoreHandle;
+  function storeHandle(ref: KvStoreDecl): KvStoreFxHandle;
+  function storeHandle(ref: FilesStoreDecl): FilesStoreFxHandle;
+  function storeHandle(ref: IndexStoreDecl): IndexStoreFxHandle;
+  function storeHandle(ref: NamedRef | { readonly ref: ResourceRef } | StoreDecl): FxStoreHandle;
   function storeHandle(ref: NamedRef | { readonly ref: ResourceRef } | StoreDecl): FxStoreHandle {
     const runtime = options.storeRuntime;
-    if (runtime && typeof ref === "object" && ref !== null && "facet" in ref) {
+    if (typeof ref === "object" && ref !== null && "facet" in ref) {
       const decl = ref;
+      // SQL physics cannot run on the in-memory stub (insert(table).values ≠ stub insert(row)).
+      // Without a runtime, fail loudly — never return a stub missing upsert/select/….
+      if (!runtime) {
+        if (decl.facet === "sql") {
+          throw new Error(
+            `fx.store("${decl.ref}"): no store runtime — boot the app (stores / flow effects) before using SQL handles`,
+          );
+        }
+        return stubStoreHandle(decl.ref);
+      }
       const cache: { handle?: StoreHandle } = {};
       const open = async () => {
         if (!cache.handle) {
@@ -1030,9 +1136,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
   };
 
   const fx: Fx = {
-    store(ref) {
-      return storeHandle(ref);
-    },
+    store: storeHandle,
     emit(signal, payload, emitOptions) {
       const name = resolveName(signal);
       return gated("emit", name, async () => {
@@ -1092,6 +1196,72 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         return { ok: true as const };
       });
     },
+    sendOtp(opts) {
+      return gated("send", "sms-otp", async () => {
+        if (isDryRun()) {
+          recordWouldHaveFired("send", "sms-otp");
+          return { ok: true as const };
+        }
+        if (!options.channelRuntime) {
+          throw new Error(
+            "fx.sendOtp needs a bound Channel — declare channel and set drivers.channel.sms (e.g. taqnyat)",
+          );
+        }
+        await options.channelRuntime.sendOtp({
+          to: opts.to,
+          requestId: opts.requestId,
+          ...(opts.lang ? { lang: opts.lang } : {}),
+          ...(opts.note ? { note: opts.note } : {}),
+          ...(opts.from ? { from: opts.from } : {}),
+        });
+        return { ok: true as const };
+      });
+    },
+    verifyOtp(opts) {
+      return gated("send", "sms-otp", async () => {
+        if (isDryRun()) {
+          recordWouldHaveFired("send", "sms-otp");
+          return { ok: true as const };
+        }
+        if (!options.channelRuntime) {
+          throw new Error(
+            "fx.verifyOtp needs a bound Channel — declare channel and set drivers.channel.sms (e.g. taqnyat)",
+          );
+        }
+        await options.channelRuntime.verifyOtp({
+          to: opts.to,
+          requestId: opts.requestId,
+          code: opts.code,
+          ...(opts.lang ? { lang: opts.lang } : {}),
+          ...(opts.from ? { from: opts.from } : {}),
+          ...(opts.note ? { note: opts.note } : {}),
+        });
+        return { ok: true as const };
+      });
+    },
+    deliverOtp(opts) {
+      return gated("send", "auth-otp", async () => {
+        if (isDryRun()) {
+          recordWouldHaveFired("send", "auth-otp");
+          return { ok: true as const, channel: opts.only ?? opts.channels[0] ?? "email" };
+        }
+        if (!options.channelRuntime) {
+          throw new Error(
+            "fx.deliverOtp needs a bound Channel — declare channel templates and drivers for the configured media",
+          );
+        }
+        const result = await options.channelRuntime.deliverOtp({
+          channels: opts.channels,
+          templates: opts.templates,
+          ...(opts.email ? { email: opts.email } : {}),
+          ...(opts.phone ? { phone: opts.phone } : {}),
+          data: opts.data,
+          ...(opts.locale ? { locale: opts.locale } : {}),
+          ...(opts.only ? { only: opts.only } : {}),
+        });
+        return { ok: true as const, channel: result.channel };
+      });
+    },
     ask(prompt, input, opts) {
       const name = resolveName(prompt);
       return gated("ask", name, async () => {

package/src/kernel/graceful-shutdown.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Graceful shutdown — Clock / Journal lease release without waiting for TTL.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { createClockRuntime, createMemoryCronStore } from "../elements/clock.ts";
+import { tryAcquireLease } from "../elements/clock/leader.ts";
+import { createMemoryJournalStore, hasJournalLease, JOURNAL_DEFAULT_LEASE_MS } from "./journal.ts";
+import { releaseInstanceLeases } from "./graceful-shutdown.ts";
+
+describe("releaseInstanceLeases", () => {
+  test("releases Clock cron leases held by this instance", async () => {
+    const store = createMemoryCronStore();
+    await store.put({
+      name: "hourly",
+      status: "active",
+      timezone: "UTC",
+      overridable: false,
+      effectiveEvery: "1h",
+    });
+    const clock = createClockRuntime({ store, instanceId: "inst-a", leaseMs: 30_000 });
+    const t = 1_000_000;
+    expect(
+      await tryAcquireLease({
+        name: "hourly",
+        instanceId: "inst-a",
+        now: t,
+        leaseMs: 30_000,
+        store,
+      }),
+    ).toBe(true);
+    expect((await store.get("hourly"))!.leaderInstanceId).toBe("inst-a");
+
+    await releaseInstanceLeases({
+      bootResult: {
+        clock: {
+          instanceId: clock.instanceId,
+          store,
+          now: () => t + 1,
+        },
+      },
+      stop: async () => {},
+    });
+
+    const row = await store.get("hourly");
+    expect(row!.leaderInstanceId).toBeUndefined();
+    expect(row!.leaderLeaseUntil).toBeUndefined();
+  });
+
+  test("releases Journal run leases held by this instance", async () => {
+    const store = createMemoryJournalStore();
+    expect(hasJournalLease(store)).toBe(true);
+    const runId = "run-1";
+    await store.put({
+      id: runId,
+      flow: "charge",
+      status: "running",
+      input: {},
+      entries: [],
+      createdAt: 1,
+      updatedAt: 1,
+    });
+    expect(await store.acquireLease!(runId, "inst-a", 1_000, JOURNAL_DEFAULT_LEASE_MS)).toBe(true);
+    expect((await store.get(runId))!.lockedBy).toBe("inst-a");
+
+    await releaseInstanceLeases({
+      bootResult: {
+        journal: { instanceId: "inst-a", store },
+      },
+      stop: async () => {},
+    });
+
+    expect((await store.get(runId))!.lockedBy).toBeUndefined();
+  });
+});

package/src/kernel/graceful-shutdown.ts

@@ -0,0 +1,106 @@
+/**
+ * Graceful shutdown — release Clock / Journal leases held by this instance,
+ * then stop the HTTP server and close element runtimes.
+ *
+ * Reuses existing `releaseLease` APIs. Signal message leases have no release
+ * surface today — survivors reclaim after TTL (lazy claim).
+ */
+
+import { releaseLease } from "../elements/clock/leader.ts";
+import type { CronStore } from "../elements/clock/reconcile.ts";
+import type { ServerHandle } from "../runtime/types.ts";
+import { hasJournalLease, type JournalStore } from "./journal.ts";
+
+/** Minimal app surface for shutdown. */
+export interface GracefulShutdownApp {
+  readonly bootResult?: {
+    readonly clock?: {
+      readonly instanceId: string;
+      readonly store: CronStore;
+      now(): number;
+    };
+    readonly journal?: {
+      readonly instanceId: string;
+      readonly store: JournalStore;
+    };
+  };
+  stop(): Promise<void>;
+}
+
+/**
+ * Release Clock cron leases and Journal run leases held by this instance.
+ *
+ * @param app - Booted app
+ */
+export async function releaseInstanceLeases(app: GracefulShutdownApp): Promise<void> {
+  const boot = app.bootResult;
+  if (!boot) return;
+
+  const clock = boot.clock;
+  if (clock) {
+    const t = clock.now();
+    for (const row of await clock.store.list()) {
+      if (row.leaderInstanceId === clock.instanceId) {
+        await releaseLease(clock.store, row.name, clock.instanceId, t);
+      }
+    }
+  }
+
+  const journal = boot.journal;
+  if (journal && hasJournalLease(journal.store)) {
+    for (const run of await journal.store.list()) {
+      if (run.lockedBy === journal.instanceId) {
+        await journal.store.releaseLease(run.id, journal.instanceId);
+      }
+    }
+  }
+}
+
+/** Options for {@link installGracefulShutdown}. */
+export interface InstallGracefulShutdownOptions {
+  readonly app: GracefulShutdownApp;
+  readonly handle?: ServerHandle;
+  /** Signals to listen for (default SIGTERM + SIGINT). */
+  readonly signals?: readonly NodeJS.Signals[];
+  /** Exit after shutdown (default true). */
+  readonly exit?: boolean;
+}
+
+/**
+ * Register SIGTERM/SIGINT handlers that release leases, drain the server,
+ * and stop the app.
+ *
+ * @param options - App + optional server handle
+ * @returns Dispose function that removes the handlers
+ */
+export function installGracefulShutdown(options: InstallGracefulShutdownOptions): () => void {
+  const signals = options.signals ?? (["SIGTERM", "SIGINT"] as const);
+  let shuttingDown = false;
+
+  const onSignal = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    void (async () => {
+      try {
+        // Stop accepting new connections first (keep in-flight open).
+        options.handle?.stop(false);
+        await releaseInstanceLeases(options.app);
+        await options.app.stop();
+      } catch (err) {
+        console.error("oke: graceful shutdown failed", err);
+      } finally {
+        if (options.exit !== false) process.exit(0);
+      }
+    })();
+  };
+
+  for (const signal of signals) {
+    process.on(signal, onSignal);
+  }
+
+  return () => {
+    for (const signal of signals) {
+      process.off(signal, onSignal);
+    }
+  };
+}