okengine 0.7.0 → 0.9.0

package/src/elements/store/upsert-app.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Real app-boot path for fx.store(db).upsert — must work through
+ * oke() → createTestApp → app.fetch(), not only the isolated SqlStoreHandle.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { gate } from "../gate.ts";
+import { oke } from "../../kernel/app.ts";
+import { createFx } from "../../kernel/fx.ts";
+import { flow, resetFlowSeq } from "../../kernel/flow.ts";
+import { on, resetBindings } from "../../kernel/on.ts";
+import { http } from "../../kernel/triggers.ts";
+import { createTestApp } from "../../test/create-test-app.ts";
+import { field, id, now, store } from "../store.ts";
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+const notes = store.schema.table("notes", {
+  id: field.text().primaryKey().defaultFn(id),
+  title: field.text().notNull(),
+  body: field.text().notNull(),
+  createdAt: field.integer().notNull().defaultFn(now),
+});
+
+const UpsertIn = z.object({
+  id: z.string(),
+  title: z.string(),
+  body: z.string(),
+  onExisting: z.enum(["update"]).optional(),
+});
+
+const UpsertOut = z.object({
+  status: z.enum(["upserted", "changed", "already-existed"]),
+});
+
+describe("fx.store(db).upsert via app.fetch (real boot)", () => {
+  test("abstract schema table: upserted → already-existed → changed", async () => {
+    resetBindings();
+    resetFlowSeq();
+
+    const db = store.sql("app", { schema: { notes } });
+
+    const seed = on(
+      http.post("/seed").gate(gate.public),
+      flow({
+        name: "notes.seed",
+        in: UpsertIn,
+        out: UpsertOut,
+        effects: { writes: ["sql:app"], reads: ["sql:app"] },
+        do: async (input, fx) =>
+          fx
+            .store(db)
+            .upsert(
+              notes,
+              { id: input.id },
+              { id: input.id, title: input.title, body: input.body, createdAt: 1 },
+              input.onExisting ? { onExisting: input.onExisting } : undefined,
+            ),
+      }),
+    );
+
+    const app = oke({
+      name: "upsert-app-boot",
+      gate: { policies: [gate.public] },
+    }).adopt({ seed });
+    Object.assign(app.$options, { env: "test", stores: [db], unguardedHttp: "allow" });
+    await createTestApp(app);
+
+    async function post(body: unknown) {
+      const res = await app.fetch(
+        new Request("http://localhost/seed", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(body),
+        }),
+      );
+      expect(res.status).toBe(200);
+      const json = (await res.json()) as { data: { status: string } };
+      return json.data.status;
+    }
+
+    expect(await post({ id: "welcome", title: "Hello", body: "one" })).toBe("upserted");
+    expect(await post({ id: "welcome", title: "Changed", body: "two" })).toBe("already-existed");
+    expect(
+      await post({
+        id: "welcome",
+        title: "Updated",
+        body: "three",
+        onExisting: "update",
+      }),
+    ).toBe("changed");
+  });
+
+  test("SQL StoreDecl without store runtime fails loudly (not stub upsert-missing)", async () => {
+    const db = store.sql("app", { schema: { notes } });
+    const fx = createFx({ flow: "orphan" });
+    expect(() => fx.store(db)).toThrow(/no store runtime/);
+  });
+});

package/src/elements/store.ts

@@ -91,6 +91,9 @@ export type {
   ResolvedListConfig,
 } from "./store/resource.ts";
 
+export { defineSeed, normalizeSeedFns, resolveSeedCategory } from "./store/seed.ts";
+export type { SeedCategory, SeedDef, SeedFn, SeedFns } from "./store/seed.ts";
+
 export { createSqlStoreHandle, resolvePkColumn } from "./store/sql-session.ts";
 export type {
   SqlStoreHandle,
@@ -102,6 +105,8 @@ export type {
   InsertValuesBuilder,
   SqlSessionOptions,
   SqlPageOptions,
+  UpsertResult,
+  UpsertStatus,
   WhereMap,
 } from "./store/sql-session.ts";
 

package/src/index.ts

@@ -41,8 +41,11 @@ export {
   PluginNeedsError,
   assertPluginNeeds,
   freezePrincipal,
+  installGracefulShutdown,
+  releaseInstanceLeases,
   type OkeApp,
   type OkeOptions,
+  type ReadyState,
   type FlowDef,
   type FlowFailure,
   type FlowErrorValue,
@@ -65,6 +68,9 @@ export {
   now,
   defineTable,
   field,
+  defineSeed,
+  normalizeSeedFns,
+  resolveSeedCategory,
   createStoreRuntime,
   type StoreDecl,
   type StoreRuntime,
@@ -72,6 +78,12 @@ export {
   type TableHandle,
   type SchemaTableDecl,
   type SchemaColumnDecl,
+  type SeedDef,
+  type SeedFn,
+  type SeedFns,
+  type SeedCategory,
+  type UpsertResult,
+  type UpsertStatus,
 } from "./elements/store.ts";
 
 export {
@@ -152,7 +164,13 @@ export {
   createJournal,
   createMemoryJournalStore,
   createFileJournalStore,
+  hasJournalLease,
+  isJournalLeaseBusy,
+  JournalLeaseBusy,
+  JOURNAL_DEFAULT_LEASE_MS,
   type Journal,
+  type JournalLeaseOptions,
+  type JournalLeaseStore,
   type JournalStore,
   type JournalRun,
 } from "./kernel/journal.ts";

package/src/kernel/app.ts

@@ -71,9 +71,15 @@ import {
 import {
   createJournal,
   createMemoryJournalStore,
+  hasJournalLease,
+  isJournalLeaseBusy,
   isJournalSuspend,
+  JOURNAL_DEFAULT_LEASE_MS,
   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 {
   applyPrincipal,
@@ -190,8 +196,13 @@ export interface OkeOptions {
   readonly startScheduler?: boolean;
   /** Scheduler tick period ms (default 1000). Forwarded to boot. */
   readonly schedulerIntervalMs?: number;
+  /** Durable-run lease duration ms (default 30_000). Forwarded to boot. */
+  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;
@@ -250,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;
   /**
@@ -558,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
@@ -579,13 +596,37 @@ export function oke(options: OkeOptions): OkeApp {
   } else {
     setActiveGateAuthContext(undefined);
   }
-  const journalStore = createMemoryJournalStore();
+  // Fallback journal for pre-boot / `autoBoot: false` unit tests. A booted
+  // app replaces this with the bound `drivers.journal` store (postgres etc.).
+  const fallbackJournalStore = createMemoryJournalStore();
+  const fallbackJournalInstanceId = `app-${crypto.randomUUID()}`;
   const sleepingRuns = new Map<
     string,
     { readonly flow: AnyFlowDef; readonly input: unknown; readonly wakeAt: number }
   >();
+  // Same-process mutual exclusion per runId. The lease coordinates across
+  // processes, but same-holder renew cannot distinguish two overlapping
+  // sessions inside one process (boot orphan scan vs. scheduler tick).
+  const inflightRuns = new Set<string>();
   const EMPTY_CAPABILITIES: ReadonlyMap<string, CapabilityToken> = new Map();
 
+  /** Active journal: the boot-bound store once available, else the fallback. */
+  function activeJournal(): {
+    readonly store: JournalStore;
+    readonly instanceId: string;
+    readonly leaseMs: number;
+  } {
+    const bound: JournalRuntime | undefined = bootResult?.journal;
+    if (bound) {
+      return { store: bound.store, instanceId: bound.instanceId, leaseMs: bound.leaseMs };
+    }
+    return {
+      store: fallbackJournalStore,
+      instanceId: fallbackJournalInstanceId,
+      leaseMs: JOURNAL_DEFAULT_LEASE_MS,
+    };
+  }
+
   async function handleCronFire(name: string): Promise<void> {
     await app.dispatchEvery(name);
     // Named clocks (e.g. `clock("expire-stale", { every: "1h" })`) reconcile
@@ -600,6 +641,84 @@ export function oke(options: OkeOptions): OkeApp {
     await app.dispatchSignal(name, payload);
   }
 
+  async function handleDurableResume(): Promise<void> {
+    await app.resumeDurable();
+  }
+
+  /** Element runtimes handed to durable resumes (same bag as cron dispatch). */
+  function durableResumeFx() {
+    return {
+      storeRuntime: bootResult?.store,
+      signalRuntime: bootResult?.signal,
+      vaultRuntime: bootResult?.vault,
+      channelRuntime: bootResult?.channel,
+      aiRuntime: bootResult?.ai,
+    };
+  }
+
+  /**
+   * Resume one persisted run under its lease. A lost lease race is the
+   * coordination win — another live instance owns the run, so skip quietly.
+   */
+  /** Runs whose undeclared flow was already logged (sweep ticks must not spam). */
+  const warnedOrphanRuns = new Set<string>();
+
+  async function resumeDurableRun(
+    runId: string,
+    flowName: string,
+    input: unknown,
+    now: () => number,
+  ): Promise<void> {
+    // The lease only coordinates across processes — within one process,
+    // overlapping callers (orphan scan vs. scheduler tick) would both pass
+    // same-holder lease renewal and run two sessions for one runId.
+    if (inflightRuns.has(runId)) return;
+    inflightRuns.add(runId);
+    try {
+      const flowDef = flowsByName.get(flowName);
+      if (!flowDef) {
+        if (!warnedOrphanRuns.has(runId)) {
+          warnedOrphanRuns.add(runId);
+          console.warn(`oke: durable run "${runId}": undeclared flow "${flowName}" — skipped`);
+        }
+        return;
+      }
+      const { store, instanceId, leaseMs } = activeJournal();
+      try {
+        await runDurable({
+          flow: flowDef,
+          input,
+          journalStore: store,
+          runId,
+          ...(hasJournalLease(store) ? { lease: { instanceId, leaseMs } } : {}),
+          now,
+          fx: durableResumeFx(),
+        });
+      } catch (err) {
+        if (isJournalLeaseBusy(err)) return;
+        throw err;
+      }
+    } finally {
+      inflightRuns.delete(runId);
+    }
+  }
+
+  /** Boot-time orphan scan — `running`/`sleeping` runs with no live lease. */
+  async function resumeOrphanedDurableRuns(): Promise<void> {
+    const { store } = activeJournal();
+    if (!hasJournalLease(store)) return;
+    const now = () => bootResult?.clock?.now() ?? options.fx?.now?.() ?? Date.now();
+    const orphans = await store.listOrphans(now());
+    for (const orphan of orphans) {
+      // Future sleeps are claimed by the scheduler tick when they come due —
+      // the shared store is the schedule, no in-process seeding needed.
+      if (orphan.status === "sleeping" && orphan.wakeAt !== undefined && orphan.wakeAt > now()) {
+        continue;
+      }
+      await resumeDurableRun(orphan.id, orphan.flow, orphan.input, now);
+    }
+  }
+
   async function doBoot(overrides?: Partial<BootOptions>): Promise<BootResult> {
     const { bootApplication, resolveElementNeeds } = await import("./boot.ts");
     const { assertHttpGatePosture } = await import("../elements/gate/boot.ts");
@@ -716,13 +835,39 @@ export function oke(options: OkeOptions): OkeApp {
       instanceId: overrides?.instanceId,
       startScheduler: overrides?.startScheduler ?? options.startScheduler,
       schedulerIntervalMs: overrides?.schedulerIntervalMs ?? options.schedulerIntervalMs,
+      journalLeaseMs: overrides?.journalLeaseMs ?? options.journalLeaseMs,
       bindings: adopted,
       flows: [...flowsByName.values()],
       onCronFire: overrides?.onCronFire ?? handleCronFire,
       onSignal: overrides?.onSignal ?? handleSignalFire,
+      onDurableResume: overrides?.onDurableResume ?? handleDurableResume,
     };
     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.
+    // Does not block boot return — readiness stays `orphan_scan` until done.
+    if (result.journal && hasJournalLease(result.journal.store)) {
+      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) {
       authBinding = createAppAuthBinding({
@@ -908,8 +1053,16 @@ export function oke(options: OkeOptions): OkeApp {
       capability = booted.capabilities.get(flowDef.name);
 
       if (flowDef.durable) {
-        const journal = createJournal({ store: journalStore, now });
+        const { store, instanceId, leaseMs } = activeJournal();
+        const journal = createJournal({
+          store,
+          now,
+          // Hold the run lease for the request's lifetime — a crash mid-run
+          // leaves an expired lease another instance can reclaim and resume.
+          ...(hasJournalLease(store) ? { lease: { instanceId, leaseMs } } : {}),
+        });
         journalSession = await journal.start(flowDef.name, input);
+        inflightRuns.add(journalSession.runId);
       }
     }
 
@@ -998,25 +1151,34 @@ export function oke(options: OkeOptions): OkeApp {
       // HTTP flows serialize before `onResponse` so the last stage can see
       // and replace the final response (plugin header/middleware surfaces).
       trigger.kind === "http" ? encodeExecuteResult : undefined,
-    );
+    ).catch((err: unknown) => {
+      // Park suspensions are already absorbed above; a real pipeline failure
+      // still leaves the run lease to expire for cross-process reclaim, but
+      // must not pin the runId in this process's in-flight guard forever.
+      if (journalSession) inflightRuns.delete(journalSession.runId);
+      throw err;
+    });
 
     const endedAt = now();
 
     if (journalSession) {
+      inflightRuns.delete(journalSession.runId);
       const sleeping = ctx.state.sleeping as
         | { readonly wakeAt: number; readonly label: string; readonly runId: string }
         | undefined;
-      if (sleeping) {
+      // Lease-capable stores make the shared row the wake schedule; the
+      // in-process map is only for custom stores without the lease surface.
+      if (sleeping && !hasJournalLease(activeJournal().store)) {
         sleepingRuns.set(sleeping.runId, {
           flow: flowDef,
           input: ctx.input,
           wakeAt: sleeping.wakeAt,
         });
-      } else if (result.failure) {
+      } else if (!sleeping && result.failure) {
         await journalSession.commit("failed", {
           error: result.failure.error.code,
         });
-      } else {
+      } else if (!sleeping) {
         await journalSession.commit("completed", { output: result.output });
       }
     }
@@ -1060,6 +1222,9 @@ export function oke(options: OkeOptions): OkeApp {
     get booted() {
       return bootResult !== undefined;
     },
+    get readyState() {
+      return readyState;
+    },
     get bootResult() {
       return bootResult;
     },
@@ -1074,6 +1239,7 @@ export function oke(options: OkeOptions): OkeApp {
         channel: bootResult.channel,
         ai: bootResult.ai,
         runs: bootResult.runs,
+        ...(bootResult.journal ? { journal: bootResult.journal } : {}),
       };
     },
     get capabilities() {
@@ -1090,31 +1256,54 @@ 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;
     },
     async resumeDurable(now) {
       const t = now ?? bootResult?.clock?.now() ?? options.fx?.now?.() ?? Date.now();
+      const { store, instanceId, leaseMs } = activeJournal();
+      if (hasJournalLease(store)) {
+        // Shared store is the wake schedule — claim due sleeps across all
+        // instances (SKIP LOCKED; exactly one claimant wins a raced claim).
+        for (;;) {
+          const due = await store.claimDueSleep(instanceId, t, leaseMs);
+          if (!due) break;
+          sleepingRuns.delete(due.id);
+          await resumeDurableRun(due.id, due.flow, due.input, () => t);
+        }
+        // Crash sweep: the boot orphan scan is once-only, so each tick also
+        // reclaims `running` runs whose holder's lease has expired (same
+        // takeover physics as Clock: lease expiry + next tick).
+        for (const orphan of await store.listOrphans(t)) {
+          if (orphan.status !== "running") continue;
+          await resumeDurableRun(orphan.id, orphan.flow, orphan.input, () => t);
+        }
+        return;
+      }
+      // Custom store without the lease surface — in-process sleepers only.
       for (const [runId, sleeper] of [...sleepingRuns.entries()]) {
         if (t < sleeper.wakeAt) continue;
         sleepingRuns.delete(runId);
         const result = await runDurable({
           flow: sleeper.flow,
           input: sleeper.input,
-          journalStore,
+          journalStore: store,
           runId,
           now: () => t,
-          fx: {
-            storeRuntime: bootResult?.store,
-            signalRuntime: bootResult?.signal,
-            vaultRuntime: bootResult?.vault,
-            channelRuntime: bootResult?.channel,
-            aiRuntime: bootResult?.ai,
-          },
+          fx: durableResumeFx(),
         });
         if (result.status === "sleeping") {
           sleepingRuns.set(runId, {
@@ -1196,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.test.ts

@@ -10,6 +10,7 @@ import {
   resolveSmsDriverId,
   smtpOptionsFromEnv,
   sndrOptionsFromEnv,
+  taqnyatMailOptionsFromEnv,
   taqnyatOptionsFromEnv,
   unifonicOptionsFromEnv,
 } from "./channel.ts";
@@ -24,6 +25,8 @@ const previous = {
   sndrBase: process.env.SNDR_BASE_URL,
   taqBearer: process.env.TAQNYAT_BEARER_TOKEN,
   taqSender: process.env.TAQNYAT_SENDER,
+  taqMailToken: process.env.TAQNYAT_MAIL_TOKEN,
+  taqCampaign: process.env.TAQNYAT_CAMPAIGN,
   msegatUser: process.env.MSEGAT_USERNAME,
   msegatKey: process.env.MSEGAT_API_KEY,
   msegatSender: process.env.MSEGAT_SENDER,
@@ -41,6 +44,8 @@ afterEach(() => {
   restoreEnv("SNDR_BASE_URL", previous.sndrBase);
   restoreEnv("TAQNYAT_BEARER_TOKEN", previous.taqBearer);
   restoreEnv("TAQNYAT_SENDER", previous.taqSender);
+  restoreEnv("TAQNYAT_MAIL_TOKEN", previous.taqMailToken);
+  restoreEnv("TAQNYAT_CAMPAIGN", previous.taqCampaign);
   restoreEnv("MSEGAT_USERNAME", previous.msegatUser);
   restoreEnv("MSEGAT_API_KEY", previous.msegatKey);
   restoreEnv("MSEGAT_SENDER", previous.msegatSender);
@@ -117,6 +122,17 @@ describe("bindChannel driver resolution", () => {
     process.env.UNIFONIC_SENDER = "Brand";
     expect(unifonicOptionsFromEnv()).toEqual({ appSid: "sid", sender: "Brand" });
   });
+
+  test("taqnyat-mail env helper", () => {
+    process.env.TAQNYAT_MAIL_TOKEN = "bearer-mail";
+    process.env.TAQNYAT_CAMPAIGN = "auth";
+    expect(taqnyatMailOptionsFromEnv()).toEqual({
+      bearerToken: "bearer-mail",
+      campaignName: "auth",
+    });
+    delete process.env.TAQNYAT_CAMPAIGN;
+    expect(() => taqnyatMailOptionsFromEnv()).toThrow("TAQNYAT_CAMPAIGN");
+  });
 });
 
 function restoreEnv(key: string, value: string | undefined): void {

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

@@ -9,7 +9,10 @@ import { openResendChannel } from "../../drivers/channel-resend.ts";
 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";
@@ -42,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;
 }
 
@@ -51,6 +56,7 @@ function emailDriverFor(options: BootOptions, env: ConfigEnv, docker: boolean):
   if (id === "smtp") return openSmtpChannel(smtpOptionsFromEnv(docker));
   if (id === "resend") return openResendChannel(resendOptionsFromEnv());
   if (id === "sndr") return openSndrChannel(sndrOptionsFromEnv());
+  if (id === "taqnyat-mail") return openTaqnyatMailChannel(taqnyatMailOptionsFromEnv());
   throw new Error(`oke boot: unknown email channel driver "${id}"`);
 }
 
@@ -90,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.
  *
@@ -150,6 +203,17 @@ export function taqnyatOptionsFromEnv(): ChannelOpenOptions {
   return { bearerToken, sender };
 }
 
+/**
+ * Resolve Taqnyat Email options from env.
+ */
+export function taqnyatMailOptionsFromEnv(): ChannelOpenOptions {
+  const bearerToken = process.env.TAQNYAT_MAIL_TOKEN?.trim();
+  const campaignName = process.env.TAQNYAT_CAMPAIGN?.trim();
+  if (!bearerToken) throw new Error("oke boot: taqnyat-mail channel needs TAQNYAT_MAIL_TOKEN");
+  if (!campaignName) throw new Error("oke boot: taqnyat-mail channel needs TAQNYAT_CAMPAIGN");
+  return { bearerToken, campaignName };
+}
+
 /**
  * Resolve Msegat SMS options from env.
  */