okengine 0.8.0 → 0.9.0

package/src/kernel/app.ts

@@ -78,6 +78,7 @@ import {
   type JournalSession,
   type JournalStore,
 } from "./journal.ts";
+import { releaseInstanceLeases } from "./graceful-shutdown.ts";
 import type { JournalRuntime } from "./boot-bind/journal.ts";
 import { listBindings, resetBindings, type Binding } from "./on.ts";
 import {
@@ -199,6 +200,9 @@ export interface OkeOptions {
   readonly journalLeaseMs?: number;
 }
 
+/** Readiness probe state — see `GET /_/ready`. */
+export type ReadyState = "booting" | "orphan_scan" | "ready";
+
 /** Payload for a CDC invocation. */
 export interface CdcPayload {
   readonly before: Record<string, unknown> | null;
@@ -257,6 +261,11 @@ export interface OkeApp<D extends Record<string, unknown> = {}, R extends AppRou
   readonly plugins: PluginRegistry;
   /** Whether {@link OkeApp.boot} has completed. */
   readonly booted: boolean;
+  /**
+   * Readiness for probes — `booting` until boot returns, `orphan_scan` while
+   * the durable orphan resume runs, then `ready`. See `GET /_/ready`.
+   */
+  readonly readyState: ReadyState;
   /** Result of {@link OkeApp.boot} (element runtimes, capabilities). */
   readonly bootResult: BootResult | undefined;
   /**
@@ -565,6 +574,7 @@ export function oke(options: OkeOptions): OkeApp {
   // --- boot (vault → store → signal → clock → channel → AI → runs → caps) ---
   let bootResult: BootResult | undefined;
   let bootPromise: Promise<BootResult> | undefined;
+  let readyState: ReadyState = "booting";
   let bootEnv: BootOptions["env"] = options.env ?? "local";
   let authBinding: AppAuthBinding | undefined =
     gateConfig.auth !== undefined
@@ -834,13 +844,29 @@ export function oke(options: OkeOptions): OkeApp {
     };
     const result = await bootApplication(merged);
     bootResult = result;
+    // otp() Tier 1 / Tier 2 capability — fail loud at boot, never silent downgrade.
+    if (result.channel) {
+      const { assertOtpPluginCapability } = await import("../auth/otp-capability.ts");
+      for (const entry of pluginRegistry.installed) {
+        if (entry.plugin.name === "otp") {
+          assertOtpPluginCapability(entry.plugin.configSnapshot, result.channel.drivers);
+        }
+      }
+    }
     // Boot-time orphan discovery: resume/schedule any `running` / `sleeping`
     // run left without a live lease by a crashed (or previous) instance.
-    // Fire-and-forget — boot must not block serving on a long resume.
+    // Does not block boot return — readiness stays `orphan_scan` until done.
     if (result.journal && hasJournalLease(result.journal.store)) {
-      void resumeOrphanedDurableRuns().catch((err) => {
-        console.error("oke: durable orphan scan failed", err);
-      });
+      readyState = "orphan_scan";
+      void resumeOrphanedDurableRuns()
+        .catch((err) => {
+          console.error("oke: durable orphan scan failed", err);
+        })
+        .finally(() => {
+          if (bootResult === result) readyState = "ready";
+        });
+    } else {
+      readyState = "ready";
     }
     // Prefer the booted clock for access-token expiry checks.
     if (authBinding) {
@@ -1196,6 +1222,9 @@ export function oke(options: OkeOptions): OkeApp {
     get booted() {
       return bootResult !== undefined;
     },
+    get readyState() {
+      return readyState;
+    },
     get bootResult() {
       return bootResult;
     },
@@ -1227,9 +1256,18 @@ export function oke(options: OkeOptions): OkeApp {
     async stop() {
       if (!bootResult) return;
       bootResult.stopScheduler();
+      // Proactive lease release so survivors need not wait for TTL reclaim.
+      await releaseInstanceLeases({
+        bootResult: {
+          clock: bootResult.clock,
+          journal: bootResult.journal,
+        },
+        stop: async () => {},
+      });
       await bootResult.close();
       bootResult = undefined;
       bootPromise = undefined;
+      readyState = "booting";
     },
     get authBinding() {
       return authBinding;
@@ -1347,6 +1385,24 @@ export function oke(options: OkeOptions): OkeApp {
         return response;
       };
 
+      // Kernel readiness — distinct from app-authored GET /health (liveness).
+      if (method === "GET" && url.pathname === "/_/ready") {
+        if (readyState === "ready") {
+          return respond(
+            new Response(JSON.stringify({ ready: true }), {
+              status: 200,
+              headers: { "content-type": "application/json" },
+            }),
+          );
+        }
+        return respond(
+          new Response(JSON.stringify({ ready: false, reason: readyState }), {
+            status: 503,
+            headers: { "content-type": "application/json" },
+          }),
+        );
+      }
+
       if (method === "GET" && url.pathname === "/_oke/client.json") {
         return respond(
           new Response(JSON.stringify(routes), {

package/src/kernel/boot-bind/channel.ts

@@ -10,7 +10,9 @@ import { openSmtpChannel } from "../../drivers/channel-smtp.ts";
 import { openSndrChannel } from "../../drivers/channel-sndr.ts";
 import { openTaqnyatChannel } from "../../drivers/channel-taqnyat.ts";
 import { openTaqnyatMailChannel } from "../../drivers/channel-taqnyat-mail.ts";
+import { openTaqnyatWhatsAppChannel } from "../../drivers/channel-taqnyat-whatsapp.ts";
 import { openUnifonicChannel } from "../../drivers/channel-unifonic.ts";
+import { openWaCloudChannel } from "../../drivers/channel-wa-cloud.ts";
 import type { ChannelDriver, ChannelOpenOptions } from "../../drivers/channel-types.ts";
 import { createChannelRuntime, type ChannelRuntime } from "../../elements/channel.ts";
 import type { BootOptions } from "../boot.ts";
@@ -43,6 +45,8 @@ function defaultDrivers(options: BootOptions, env: ConfigEnv, docker: boolean):
   const drivers: ChannelDriver[] = [emailDriverFor(options, env, docker)];
   const sms = smsDriverFor(options, env);
   if (sms) drivers.push(sms);
+  const whatsapp = whatsappDriverFor(options, env);
+  if (whatsapp) drivers.push(whatsapp);
   return drivers;
 }
 
@@ -92,6 +96,53 @@ export function resolveSmsDriverId(options: BootOptions, env: ConfigEnv): string
   return resolveDriverId(options.config?.drivers?.channel?.sms, env);
 }
 
+/**
+ * Resolve the configured WhatsApp driver for one environment.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+export function resolveWhatsappDriverId(options: BootOptions, env: ConfigEnv): string | undefined {
+  return resolveDriverId(options.config?.drivers?.channel?.whatsapp, env);
+}
+
+function whatsappDriverFor(options: BootOptions, env: ConfigEnv): ChannelDriver | undefined {
+  const id = resolveWhatsappDriverId(options, env);
+  if (!id || id === "console") return undefined;
+  if (id === "taqnyat-whatsapp") return openTaqnyatWhatsAppChannel(taqnyatWhatsAppOptionsFromEnv());
+  if (id === "wa-cloud") return openWaCloudChannel(waCloudOptionsFromEnv());
+  throw new Error(`oke boot: unknown whatsapp channel driver "${id}"`);
+}
+
+/**
+ * Resolve Taqnyat WhatsApp options from env.
+ */
+export function taqnyatWhatsAppOptionsFromEnv(): ChannelOpenOptions {
+  const bearerToken =
+    process.env.TAQNYAT_WHATSAPP_TOKEN?.trim() ??
+    process.env.TAQNYAT_BEARER_TOKEN?.trim() ??
+    process.env.TAQNYAT_TOKEN?.trim();
+  if (!bearerToken) {
+    throw new Error(
+      "oke boot: taqnyat-whatsapp channel needs TAQNYAT_WHATSAPP_TOKEN (or TAQNYAT_BEARER_TOKEN)",
+    );
+  }
+  return { bearerToken };
+}
+
+/**
+ * Resolve WhatsApp Cloud API options from env.
+ */
+export function waCloudOptionsFromEnv(): ChannelOpenOptions {
+  const token = process.env.WHATSAPP_TOKEN?.trim() ?? process.env.WA_CLOUD_TOKEN?.trim();
+  const from =
+    process.env.WHATSAPP_PHONE_NUMBER_ID?.trim() ?? process.env.WA_CLOUD_PHONE_NUMBER_ID?.trim();
+  if (!token || !from) {
+    throw new Error("oke boot: wa-cloud channel needs WHATSAPP_TOKEN and WHATSAPP_PHONE_NUMBER_ID");
+  }
+  return { token, from };
+}
+
 /**
  * Resolve SMTP connection options from `SMTP_URL` plus optional auth overrides.
  *

package/src/kernel/boot-bind/gate.ts

@@ -33,15 +33,14 @@ export function resolveGateKvDriverId(
   return docker ? "redis" : "memory";
 }
 
-function kvUrlFor(docker: boolean): string | undefined {
+function kvUrlFor(docker: boolean): string {
   const url = process.env.REDIS_URL ?? process.env.OKE_STORE_KV_URL ?? undefined;
   if (!url) {
-    if (docker) {
-      throw new Error(
-        "oke boot: gate redis kv needs REDIS_URL (did `oke dev -d` write docker/.env.docker?)",
-      );
-    }
-    return undefined;
+    throw new Error(
+      docker
+        ? "oke boot: gate redis kv needs REDIS_URL (did `oke dev -d` write docker/.env.docker?)"
+        : "oke boot: gate redis kv needs REDIS_URL — declare drivers.store.kv memory for local, or set REDIS_URL",
+    );
   }
   return url;
 }
@@ -65,19 +64,15 @@ export async function bindGate(
 
   let kvNs;
   if (kvId === "redis") {
+    // Fail loud when redis is configured without URL/inject — never soft-fallback
+    // to memory (that silently doubles rate budgets under horizontal scale).
     const url = injected ? undefined : kvUrlFor(docker);
-    if (!injected && url === undefined) {
-      // Local without REDIS_URL — soft-fallback to memory (same as missing redis for store would fail;
-      // gate rates should not brick local apps that only declared policy gates).
-      kvNs = await memoryDrivers.kv.open({ name: GATE_KV_NAMESPACE, nowMs: now });
-    } else {
-      kvNs = await redisDriver.open({
-        name: GATE_KV_NAMESPACE,
-        ...(url !== undefined ? { url } : {}),
-        ...(injected !== undefined ? { client: injected } : {}),
-        nowMs: now,
-      });
-    }
+    kvNs = await redisDriver.open({
+      name: GATE_KV_NAMESPACE,
+      ...(url !== undefined ? { url } : {}),
+      ...(injected !== undefined ? { client: injected } : {}),
+      nowMs: now,
+    });
   } else {
     kvNs = await memoryDrivers.kv.open({ name: GATE_KV_NAMESPACE, nowMs: now });
   }

package/src/kernel/boot-bind/honor-config.test.ts

@@ -263,6 +263,24 @@ describe("boot binders honour drivers.* config", () => {
     }
   });
 
+  test("gate: drivers.store.kv redis without REDIS_URL fails loud (never soft memory)", async () => {
+    delete process.env.REDIS_URL;
+    delete process.env.OKE_STORE_KV_URL;
+    await expect(
+      bootApplication({
+        env: "local",
+        gates: [gate.rate({ max: 10, per: "1m" })],
+        config: {
+          drivers: {
+            store: {
+              kv: { local: "redis", docker: "redis", prod: "redis" },
+            },
+          },
+        },
+      }),
+    ).rejects.toThrow(/gate redis kv needs REDIS_URL/);
+  });
+
   test("gate: drivers.store.kv memory keeps memory oke:gates", async () => {
     const result = await bootApplication({
       env: "local",

package/src/kernel/boot-bind/signal.ts

@@ -29,6 +29,25 @@ function redisUrlFor(docker: boolean): string | undefined {
   return url;
 }
 
+let signalRedisWarned = false;
+
+/** One-shot: redis Signal is emit-relay + process-local outbox consume today. */
+function warnSignalRedisProcessLocal(): void {
+  if (signalRedisWarned) return;
+  signalRedisWarned = true;
+  console.warn(
+    "oke boot: drivers.signal redis — emit relays to Redis, but consume/live/drain use a " +
+      "process-local outbox (not multi-instance competing consumers). Prefer a shared durable " +
+      "outbox path for multi-process tests, or a single consumer instance, until Redis Streams " +
+      "consume ships.",
+  );
+}
+
+/** Test helper — reset the one-shot redis Signal warn. */
+export function resetSignalRedisWarnForTests(): void {
+  signalRedisWarned = false;
+}
+
 /**
  * Construct a Signal runtime, register decls / binding names, start the bus.
  *
@@ -59,6 +78,7 @@ export async function bindSignal(
       break;
     case "redis": {
       const redis = injectedRedis ?? createBunSignalRedisClient(redisUrlFor(docker));
+      warnSignalRedisProcessLocal();
       signal = createSignalRuntime({
         driver: redisSignalDriver,
         now,

package/src/kernel/boot-bind/store.test.ts

@@ -3,8 +3,11 @@
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
+import { files } from "../../elements/store.ts";
 import {
+  bindStore,
   indexDriverFor,
+  resetFilesFsWarnForTests,
   resolveFilesDriverId,
   resolveIndexDriverId,
   resolveKvDriverId,
@@ -77,6 +80,85 @@ describe("bindStore driver resolution", () => {
   });
 });
 
+describe("bindStore files fs multi-instance warn", () => {
+  afterEach(() => {
+    resetFilesFsWarnForTests();
+  });
+
+  test("warns once when files driver is fs", () => {
+    const warnings: string[] = [];
+    const prev = console.warn;
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.map(String).join(" "));
+    };
+    try {
+      const uploads = files("uploads");
+      bindStore(
+        {
+          stores: [uploads],
+          config: {
+            drivers: {
+              store: {
+                files: { local: "fs", docker: "s3", prod: "s3" },
+              },
+            },
+          },
+        },
+        "local",
+        () => Date.now(),
+        false,
+      );
+      bindStore(
+        {
+          stores: [uploads],
+          config: {
+            drivers: {
+              store: {
+                files: { local: "fs", docker: "s3", prod: "s3" },
+              },
+            },
+          },
+        },
+        "local",
+        () => Date.now(),
+        false,
+      );
+      expect(warnings.some((w) => w.includes('drivers.store.files "fs"'))).toBe(true);
+      expect(warnings.filter((w) => w.includes('drivers.store.files "fs"'))).toHaveLength(1);
+    } finally {
+      console.warn = prev;
+    }
+  });
+
+  test("does not warn for memory or s3 files", () => {
+    const warnings: string[] = [];
+    const prev = console.warn;
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.map(String).join(" "));
+    };
+    try {
+      bindStore(
+        {
+          stores: [files("uploads")],
+          config: {
+            drivers: {
+              store: {
+                files: { local: "memory", docker: "s3", prod: "s3" },
+              },
+            },
+          },
+        },
+        "local",
+        () => Date.now(),
+        false,
+      );
+      expect(warnings.some((w) => w.includes('drivers.store.files "fs"'))).toBe(false);
+    } finally {
+      console.warn = prev;
+    }
+  });
+});
+
 describe("bindStore index driver resolution", () => {
   const prevIndex = process.env.OKE_INDEX_DRIVER;
 

package/src/kernel/boot-bind/store.ts

@@ -29,6 +29,27 @@ import type { BootOptions } from "../boot.ts"; // type-only — no cycle at runt
  * @param now - Clock
  * @param docker - Prefer compose URLs when opening postgres/redis
  */
+let filesFsWarned = false;
+
+/** Test helper — reset the one-shot `fs` multi-instance warn. */
+export function resetFilesFsWarnForTests(): void {
+  filesFsWarned = false;
+}
+
+/**
+ * Warn once when `drivers.store.files` is `fs` — per-process (or per-pod)
+ * filesystem visibility under horizontal scale.
+ */
+function warnFilesFsMultiInstance(): void {
+  if (filesFsWarned) return;
+  filesFsWarned = true;
+  console.warn(
+    'oke boot: drivers.store.files "fs" is single-host — each instance sees its own ' +
+      "filesystem (temp root when unbound). For horizontal scale use drivers.store.files s3 " +
+      "(or an explicitly shared volume root, still single-host semantics).",
+  );
+}
+
 export function bindStore(
   options: BootOptions,
   env: ConfigEnv,
@@ -39,6 +60,7 @@ export function bindStore(
   const kvId = resolveKvDriverId(options, env, docker);
   const filesId = resolveFilesDriverId(options, env, docker);
   const indexId = resolveIndexDriverId(options, env, docker);
+  if (filesId === "fs") warnFilesFsMultiInstance();
   const sqlUrl = sqlUrlFor(sqlId, docker);
   const kvUrl = kvUrlFor(kvId, docker);
   const filesRoot = filesRootFor(filesId);

package/src/kernel/boot.test.ts

@@ -79,7 +79,7 @@ describe("boot — lazy element needs", () => {
     expect(needs.signal).toBe(false);
   });
 
-  test("oke() Store-only graph stays under the prior 51 kB baseline", async () => {
+  test("oke() Store-only graph stays under the prior 53 kB baseline", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-store-only-"));
     const entry = join(dir, "entry.ts");
     const appPath = join(import.meta.dir, "app.ts");
@@ -117,10 +117,10 @@ describe("boot — lazy element needs", () => {
         total += Bun.gzipSync(new Uint8Array(raw)).byteLength;
       }
       // Rebased after fx.sendOtp/verifyOtp on the shared fx surface (~50.1 kB
-      // gzip), then again after the durable-journal lease surface (SKIP LOCKED
-      // claim/release/orphan-scan on journal.ts + app.ts wiring, ~51.2 kB).
-      // Clock/channel/journal drivers stay lazy-bound; far below eager bind.
-      expect(total).toBeLessThan(51_500);
+      // gzip), durable-journal lease surface (~51.2 kB), then fx.deliverOtp +
+      // unified otp() plugin wiring on the shared surface (~50.9 kB → 53 kB
+      // cap). Clock/channel/journal drivers stay lazy-bound; far below eager bind.
+      expect(total).toBeLessThan(53_000);
     } finally {
       await rm(dir, { recursive: true, force: true });
     }

package/src/kernel/fx.test.ts

@@ -147,6 +147,9 @@ describe("fx — wholesale swap", () => {
       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

@@ -265,6 +265,20 @@ export interface FxVerifyOtpOptions {
   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[];
@@ -385,6 +399,18 @@ export interface Fx {
    * @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 `{}`.
    *
@@ -1213,6 +1239,29 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         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();
+  });
+});