okengine 0.6.1 → 0.8.0

package/src/kernel/journal.ts

@@ -9,6 +9,9 @@
 
 import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
+import { JournalSuspend } from "./journal-suspend.ts";
+
+export { JournalSuspend, isJournalSuspend } from "./journal-suspend.ts";
 
 /** Status of a durable run. */
 export type JournalRunStatus = "running" | "sleeping" | "completed" | "failed";
@@ -53,32 +56,58 @@ export interface JournalRun {
   wakeAt?: number;
   error?: string;
   output?: unknown;
+  /** Lease holder instance id (run-level coordination — Signal/Clock physics). */
+  lockedBy?: string;
+  /** Lease expiry epoch-ms; a crashed holder's run is reclaimable after this. */
+  leaseExpiresAt?: number;
   readonly createdAt: number;
   updatedAt: number;
 }
 
 /**
- * Thrown inside a durable body when a sleep has not yet elapsed.
- * The runner catches this and parks the run as `sleeping`.
+ * Run-level lease coordination — same SKIP LOCKED + lazy-reclaim physics as
+ * Signal's message claims and Clock's tick claims. No sweeper, no fencing
+ * token: at-least-once after lease expiry, journal replay keeps completed
+ * steps from re-running.
  */
-export class JournalSuspend extends Error {
-  readonly wakeAt: number;
-  readonly label: string;
-
+export interface JournalLeaseStore {
   /**
-   * @param label - Sleep label
-   * @param wakeAt - Absolute wake epoch-ms
+   * Acquire / renew / reclaim a run lease. Claimable when unlocked, held by
+   * the same instance, or expired.
+   *
+   * @param runId - Run id
+   * @param instanceId - Claimant instance
+   * @param now - Epoch-ms
+   * @param leaseMs - Lease duration
    */
-  constructor(label: string, wakeAt: number) {
-    super(`journal suspend: sleep "${label}" until ${wakeAt}`);
-    this.name = "JournalSuspend";
-    this.label = label;
-    this.wakeAt = wakeAt;
-  }
+  acquireLease(runId: string, instanceId: string, now: number, leaseMs: number): Promise<boolean>;
+  /**
+   * Release a lease held by `instanceId` (no-op for other holders).
+   *
+   * @param runId - Run id
+   * @param instanceId - Holder instance
+   */
+  releaseLease(runId: string, instanceId: string): Promise<void>;
+  /**
+   * Atomically claim the next due sleep (`status=sleeping`, `wakeAt<=now`, no
+   * live lease) and return it — `undefined` when none is claimable.
+   *
+   * @param instanceId - Claimant instance
+   * @param now - Epoch-ms
+   * @param leaseMs - Lease duration
+   */
+  claimDueSleep(instanceId: string, now: number, leaseMs: number): Promise<JournalRun | undefined>;
+  /**
+   * Boot-time orphan discovery: `running` / `sleeping` runs with no live lease
+   * (crashed holder or never claimed). Rows are never deleted.
+   *
+   * @param now - Epoch-ms
+   */
+  listOrphans(now: number): Promise<readonly JournalRun[]>;
 }
 
 /** Persistence backend for journal runs. */
-export interface JournalStore {
+export interface JournalStore extends Partial<JournalLeaseStore> {
   /**
    * Load a run by id.
    *
@@ -95,12 +124,107 @@ export interface JournalStore {
   list(): Promise<readonly JournalRun[]>;
 }
 
+/** Default run lease — matches Signal's claim lease. */
+export const JOURNAL_DEFAULT_LEASE_MS = 30_000;
+
+/**
+ * Narrow a store to its lease-coordination surface (present on the built-in
+ * memory / file / postgres stores; absent on custom minimal stores).
+ *
+ * @param store - Journal store
+ */
+export function hasJournalLease(store: JournalStore): store is JournalStore & JournalLeaseStore {
+  return (
+    typeof store.acquireLease === "function" &&
+    typeof store.releaseLease === "function" &&
+    typeof store.claimDueSleep === "function" &&
+    typeof store.listOrphans === "function"
+  );
+}
+
+/** Thrown when a run resume loses the lease race to another live instance. */
+export class JournalLeaseBusy extends Error {
+  readonly runId: string;
+  constructor(runId: string) {
+    super(`journal: run "${runId}" is leased by another instance`);
+    this.name = "JournalLeaseBusy";
+    this.runId = runId;
+  }
+}
+
+/** Type guard for {@link JournalLeaseBusy}. */
+export function isJournalLeaseBusy(err: unknown): err is JournalLeaseBusy {
+  return err instanceof JournalLeaseBusy;
+}
+
+/** Live lease = a holder with an unexpired expiry. */
+function hasLiveLease(run: JournalRun, now: number): boolean {
+  return run.lockedBy !== undefined && run.leaseExpiresAt !== undefined && run.leaseExpiresAt > now;
+}
+
+/** Claimable when unlocked, same-holder, or without a live lease. */
+function claimable(run: JournalRun, instanceId: string, now: number): boolean {
+  if (run.lockedBy === undefined) return true;
+  if (run.lockedBy === instanceId) return true;
+  return !hasLiveLease(run, now);
+}
+
+/** Lease methods shared by the memory + file stores (single-writer maps). */
+function leaseMethods(
+  load: () => Promise<Map<string, JournalRun>>,
+  flush?: (map: Map<string, JournalRun>) => Promise<void>,
+): JournalLeaseStore {
+  return {
+    async acquireLease(runId, instanceId, now, leaseMs) {
+      const map = await load();
+      const run = map.get(runId);
+      if (!run || !claimable(run, instanceId, now)) return false;
+      run.lockedBy = instanceId;
+      run.leaseExpiresAt = now + leaseMs;
+      await flush?.(map);
+      return true;
+    },
+    async releaseLease(runId, instanceId) {
+      const map = await load();
+      const run = map.get(runId);
+      if (!run || run.lockedBy !== instanceId) return;
+      delete run.lockedBy;
+      delete run.leaseExpiresAt;
+      await flush?.(map);
+    },
+    async claimDueSleep(instanceId, now, leaseMs) {
+      const map = await load();
+      const due = [...map.values()]
+        .filter(
+          (r) =>
+            r.status === "sleeping" &&
+            r.wakeAt !== undefined &&
+            r.wakeAt <= now &&
+            claimable(r, instanceId, now),
+        )
+        .sort((a, b) => (a.wakeAt ?? 0) - (b.wakeAt ?? 0))[0];
+      if (!due) return undefined;
+      due.lockedBy = instanceId;
+      due.leaseExpiresAt = now + leaseMs;
+      await flush?.(map);
+      return cloneRun(due);
+    },
+    async listOrphans(now) {
+      const map = await load();
+      return [...map.values()]
+        .filter((r) => (r.status === "running" || r.status === "sleeping") && !hasLiveLease(r, now))
+        .map(cloneRun);
+    },
+  };
+}
+
 /** In-memory journal store. */
 export function createMemoryJournalStore(seed?: readonly JournalRun[]): JournalStore {
   const runs = new Map<string, JournalRun>();
   for (const r of seed ?? []) {
     runs.set(r.id, cloneRun(r));
   }
+  const load = async (): Promise<Map<string, JournalRun>> => runs;
   return {
     async get(runId) {
       const r = runs.get(runId);
@@ -112,6 +236,7 @@ export function createMemoryJournalStore(seed?: readonly JournalRun[]): JournalS
     async list() {
       return [...runs.values()].map(cloneRun);
     },
+    ...leaseMethods(load),
   };
 }
 
@@ -156,9 +281,19 @@ export function createFileJournalStore(path: string): JournalStore {
       const map = await load();
       return [...map.values()].map(cloneRun);
     },
+    // Single-host file: leases coordinate same-machine processes only.
+    ...leaseMethods(load, flush),
   };
 }
 
+/** Run-level lease holder for {@link CreateJournalOptions.lease}. */
+export interface JournalLeaseOptions {
+  /** This instance's id (lease holder). */
+  readonly instanceId: string;
+  /** Lease duration ms (default {@link JOURNAL_DEFAULT_LEASE_MS}). */
+  readonly leaseMs?: number;
+}
+
 /** Options for {@link createJournal}. */
 export interface CreateJournalOptions {
   /** Persistence backend. */
@@ -167,6 +302,13 @@ export interface CreateJournalOptions {
   readonly now?: () => number;
   /** Id factory (defaults to UUID). */
   readonly id?: () => string;
+  /**
+   * Run-level lease (when the store supports it). `start` inserts with the
+   * lease held; `resume` claims the run or throws {@link JournalLeaseBusy};
+   * every persist renews; parking a sleep and terminal commits release so a
+   * sleeping/finished run never holds a 30s lock.
+   */
+  readonly lease?: JournalLeaseOptions;
 }
 
 /**
@@ -240,16 +382,31 @@ export interface Journal {
 export function createJournal(options: CreateJournalOptions): Journal {
   const now = options.now ?? (() => Date.now());
   const newId = options.id ?? (() => crypto.randomUUID());
+  const lease = options.lease;
+  const coordinated = lease !== undefined && hasJournalLease(options.store);
 
-  function openSession(run: JournalRun): JournalSession {
+  function openSession(run: JournalRun, leased: boolean): JournalSession {
     /** Next entry index to consume on replay. */
     let cursor = 0;
+    let leaseHeld = leased;
 
     async function persist(): Promise<void> {
       run.updatedAt = now();
+      // Natural heartbeat — a live holder renews on every journal write.
+      if (leaseHeld && lease) {
+        run.lockedBy = lease.instanceId;
+        run.leaseExpiresAt = now() + (lease.leaseMs ?? JOURNAL_DEFAULT_LEASE_MS);
+      }
       await options.store.put(cloneRun(run));
     }
 
+    /** Parking / terminal states must not hold a short lease across days. */
+    function releaseLeaseLocally(): void {
+      leaseHeld = false;
+      delete run.lockedBy;
+      delete run.leaseExpiresAt;
+    }
+
     return {
       runId: run.id,
       run,
@@ -282,6 +439,7 @@ export function createJournal(options: CreateJournalOptions): Journal {
             if (now() < e.wakeAt) {
               run.status = "sleeping";
               run.wakeAt = e.wakeAt;
+              releaseLeaseLocally();
               await persist();
               throw new JournalSuspend(label, e.wakeAt);
             }
@@ -301,6 +459,7 @@ export function createJournal(options: CreateJournalOptions): Journal {
         if (now() < wakeAt) {
           run.status = "sleeping";
           run.wakeAt = wakeAt;
+          releaseLeaseLocally();
           await persist();
           throw new JournalSuspend(label, wakeAt);
         }
@@ -341,6 +500,7 @@ export function createJournal(options: CreateJournalOptions): Journal {
         if (patch?.error !== undefined) run.error = patch.error;
         if (status === "completed" || status === "failed") {
           delete run.wakeAt;
+          releaseLeaseLocally();
         }
         await persist();
       },
@@ -360,31 +520,46 @@ export function createJournal(options: CreateJournalOptions): Journal {
         createdAt: t,
         updatedAt: t,
       };
+      if (coordinated && lease) {
+        // Fresh id — insert already holding the lease (no claim race).
+        run.lockedBy = lease.instanceId;
+        run.leaseExpiresAt = t + (lease.leaseMs ?? JOURNAL_DEFAULT_LEASE_MS);
+      }
       await options.store.put(cloneRun(run));
-      return openSession(run);
+      return openSession(run, coordinated);
     },
     async resume(runId) {
+      if (coordinated && lease) {
+        const t = now();
+        const claimed = await options.store.acquireLease!(
+          runId,
+          lease.instanceId,
+          t,
+          lease.leaseMs ?? JOURNAL_DEFAULT_LEASE_MS,
+        );
+        if (!claimed) {
+          throw new JournalLeaseBusy(runId);
+        }
+      }
       const run = await options.store.get(runId);
       if (!run) {
+        if (coordinated && lease) {
+          await options.store.releaseLease!(runId, lease.instanceId);
+        }
         throw new Error(`journal: run "${runId}" not found`);
       }
       // Leave status intact — the durable runner parks or continues.
       run.updatedAt = now();
+      if (coordinated && lease) {
+        run.lockedBy = lease.instanceId;
+        run.leaseExpiresAt = now() + (lease.leaseMs ?? JOURNAL_DEFAULT_LEASE_MS);
+      }
       await options.store.put(cloneRun(run));
-      return openSession(run);
+      return openSession(run, coordinated);
     },
   };
 }
 
-/**
- * True when `err` is a {@link JournalSuspend}.
- *
- * @param err - Unknown
- */
-export function isJournalSuspend(err: unknown): err is JournalSuspend {
-  return err instanceof JournalSuspend;
-}
-
 function cloneRun(run: JournalRun): JournalRun {
   return structuredClone(run);
 }

package/src/plugins/auth-methods.security.test.ts

@@ -421,7 +421,7 @@ describe("auth methods — anonymous non-escalation", () => {
 });
 
 describe("auth methods — channel delivery", () => {
-  test("magic / email-otp send via fx.send; phone remains unwired; exposeDev* stays off by default", async () => {
+  test("magic / email-otp send via fx.send; phone uses fx.sendOtp (Taqnyat Verify); exposeDev* stays off by default", async () => {
     resetBindings();
     resetFlowSeq();
     const app = oke({
@@ -445,6 +445,7 @@ describe("auth methods — channel delivery", () => {
     expect(otpBody.data.ok).toBe(true);
     expect(otpBody.data.devOtp).toBeUndefined();
 
+    // No SMS driver in test env → local hashed path; never exposeDevOtp by default.
     const phone = await app.fetch(jsonPost("/auth/phone/request", { phone: "+15551112222" }));
     const phoneBody = (await phone.json()) as { data: Record<string, unknown> };
     expect(phoneBody.data.ok).toBe(true);
@@ -453,14 +454,16 @@ describe("auth methods — channel delivery", () => {
     const magicSrc = await Bun.file(new URL("./magic-link.ts", import.meta.url)).text();
     const emailSrc = await Bun.file(new URL("./email-otp.ts", import.meta.url)).text();
     const phoneSrc = await Bun.file(new URL("./phone-number.ts", import.meta.url)).text();
-    expect(magicSrc).toMatch(/fx\.send/);
+    expect(magicSrc).toMatch(/fx\.send\(/);
     expect(magicSrc).toMatch(/channel\./);
-    expect(emailSrc).toMatch(/fx\.send/);
+    expect(emailSrc).toMatch(/fx\.send\(/);
     expect(emailSrc).toMatch(/channel\./);
-    // SMS delivery stays deferred — phone must not import Channel or fx.send.
-    expect(phoneSrc).not.toMatch(/fx\.send/);
-    expect(phoneSrc).not.toMatch(/channel\./);
-    expect(phoneSrc).not.toMatch(/from ["'].*channel/);
+    // Phone OTP is provider-managed via Taqnyat Verify through fx — never a
+    // raw transport import or a generic fx.send template. Regexes tolerate
+    // formatter line wraps between `fx` and the method name.
+    expect(phoneSrc).toMatch(/fx\s*\.\s*sendOtp/);
+    expect(phoneSrc).toMatch(/fx\s*\.\s*verifyOtp/);
+    expect(phoneSrc).not.toMatch(/taqnyat-sms|sently\/transports/);
 
     await app.stop();
   });

package/src/plugins/phone-number.ts

@@ -64,22 +64,57 @@ export function phoneNumber(opts: PhoneNumberOptions = {}): PluginDef {
     name: "auth.requestPhoneOtp",
     unit: "auth",
     plane: "user",
-    in: z.object({ phone: z.string().min(8) }),
+    in: z.object({
+      phone: z.string().min(8),
+      /** OTP message language for the Taqnyat Verify path. */
+      lang: z.enum(["en", "ar"]).optional(),
+    }),
     out: z.object({
       ok: z.literal(true),
       devOtp: z.string().optional(),
     }),
     errors: { AuthFailed, AuthRateLimited },
-    do: async (input) => {
+    effects: { sends: ["auth-phone-otp", "sms-otp"] },
+    do: async (input, fx) => {
       const phone = input.phone.trim();
       if (!E164.test(phone)) return fail("AuthFailed", { reason: "invalid_phone" });
-      const otp = generateOtp(6);
       const now = runtime.now();
       for (const row of verifications.rows.values()) {
         if (row.identifier === `phone-otp:${phone}` && row.consumedAt === null) {
           row.consumedAt = now;
         }
       }
+
+      // Provider-managed OTP (Taqnyat Verify) when a Taqnyat SMS driver is
+      // bound via Channel. Throws loudly for unsupported SMS drivers; returns
+      // undefined only when no SMS driver is bound (local/dev path).
+      const requestId = crypto.randomUUID();
+      const provider = await fx
+        .sendOtp({
+          to: phone,
+          requestId,
+          ...(input.lang ? { lang: input.lang } : {}),
+        })
+        .catch((err: unknown) => {
+          const msg = err instanceof Error ? err.message : String(err);
+          if (msg.includes("no SMS driver bound")) return undefined;
+          throw err;
+        });
+
+      if (provider) {
+        putVerification(verifications, {
+          id: crypto.randomUUID(),
+          identifier: `phone-otp:${phone}`,
+          value: `taqnyat:${requestId}`,
+          expiresAt: now + ttlMs,
+          createdAt: now,
+          consumedAt: null,
+          attempts: 0,
+        });
+        return { ok: true as const };
+      }
+
+      const otp = generateOtp(6);
       putVerification(verifications, {
         id: crypto.randomUUID(),
         identifier: `phone-otp:${phone}`,
@@ -103,10 +138,13 @@ export function phoneNumber(opts: PhoneNumberOptions = {}): PluginDef {
     in: z.object({
       phone: z.string().min(8),
       otp: z.string().min(4).max(8),
+      /** OTP message language for the Taqnyat Verify path. */
+      lang: z.enum(["en", "ar"]).optional(),
     }),
     out: SessionTokensOut,
     errors: { AuthFailed, AuthRateLimited },
-    do: async (input) => {
+    effects: { sends: ["sms-otp"] },
+    do: async (input, fx) => {
       const phone = input.phone.trim();
       if (!E164.test(phone)) return fail("AuthFailed", { reason: "invalid_phone" });
       const now = runtime.now();
@@ -116,13 +154,32 @@ export function phoneNumber(opts: PhoneNumberOptions = {}): PluginDef {
         row.consumedAt = now;
         return fail("AuthFailed", { reason: "invalid_credentials" });
       }
-      const hash = await hashChallenge(input.otp.trim());
-      if (hash !== row.value) {
-        row.attempts += 1;
-        if (row.attempts >= MAX_ATTEMPTS) row.consumedAt = now;
-        return fail("AuthFailed", { reason: "invalid_credentials" });
+
+      if (row.value.startsWith("taqnyat:")) {
+        const requestId = row.value.slice("taqnyat:".length);
+        try {
+          await fx.verifyOtp({
+            to: phone,
+            requestId,
+            code: input.otp.trim(),
+            ...(input.lang ? { lang: input.lang } : {}),
+          });
+        } catch {
+          row.attempts += 1;
+          if (row.attempts >= MAX_ATTEMPTS) row.consumedAt = now;
+          return fail("AuthFailed", { reason: "invalid_credentials" });
+        }
+        row.consumedAt = now;
+      } else {
+        const hash = await hashChallenge(input.otp.trim());
+        if (hash !== row.value) {
+          row.attempts += 1;
+          if (row.attempts >= MAX_ATTEMPTS) row.consumedAt = now;
+          return fail("AuthFailed", { reason: "invalid_credentials" });
+        }
+        row.consumedAt = now;
       }
-      row.consumedAt = now;
+
       let userId = phones.byPhone.get(phone);
       if (!userId) {
         userId = crypto.randomUUID();

package/src/plugins/taqnyat.live.test.ts

@@ -0,0 +1,174 @@
+/**
+ * Real Taqnyat end-to-end: phoneNumber OTP via Verify API + magic-link via Taqnyat Mail.
+ *
+ * Double-gated — runs ONLY when BOTH:
+ *   1. The global per-medium opt-in flag is set explicitly
+ *      (`OKE_SMS_LIVE=1` / `OKE_EMAIL_LIVE=1`), and
+ *   2. the matching real credentials are present in the environment.
+ *
+ * Credential presence alone is NEVER enough — this mirrors sently's own
+ * opt-in live suite and prevents burning provider quota on a routine
+ * `bun test` run with stray credentials in the shell. The flags are
+ * provider-agnostic: any future SMS or email provider live suite gates on
+ * the same medium flag plus its own credentials.
+ *
+ * Skip is always visible (`console.log("skip: …")` + `test.skip`), never a
+ * silent pass.
+ *
+ * Setup:
+ *   # SMS OTP — sends exactly ONE real SMS (the plugin's own send; its
+ *   # provider response is captured for the code-5 assertion)
+ *   export OKE_SMS_LIVE=1
+ *   export TAQNYAT_TOKEN=…            (or TAQNYAT_BEARER_TOKEN)
+ *   export TAQNYAT_SENDER=YourBrand
+ *   export OKE_TEST_TAQNYAT_PHONE=+9665xxxxxxxx   (or TAQNYAT_TO)
+ *   # Mail
+ *   export OKE_EMAIL_LIVE=1
+ *   export TAQNYAT_MAIL_TOKEN=…
+ *   export TAQNYAT_CAMPAIGN=auth
+ *   export OKE_TEST_TAQNYAT_MAIL=you@example.com  (or TAQNYAT_MAIL_TO)
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { oke } from "../kernel/app.ts";
+import { resetFlowSeq } from "../kernel/flow.ts";
+import { resetBindings } from "../kernel/on.ts";
+import { magicLink } from "./magic-link.ts";
+import { phoneNumber } from "./phone-number.ts";
+
+const SECRET = "test-secret-at-least-16";
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+function jsonPost(path: string, body: unknown): Request {
+  return new Request(`http://localhost${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+const WANT_SMS = process.env.OKE_SMS_LIVE === "1";
+const WANT_MAIL = process.env.OKE_EMAIL_LIVE === "1";
+
+const SMS_TOKEN = process.env.TAQNYAT_TOKEN ?? process.env.TAQNYAT_BEARER_TOKEN;
+const SMS_CREDS = Boolean(SMS_TOKEN) && Boolean(process.env.TAQNYAT_SENDER);
+// OKE_TEST_TAQNYAT_PHONE wins; TAQNYAT_TO (sently's convention) is the alias.
+const SMS_PHONE = process.env.OKE_TEST_TAQNYAT_PHONE ?? process.env.TAQNYAT_TO;
+const LIVE_SMS = WANT_SMS && SMS_CREDS && Boolean(SMS_PHONE);
+
+const MAIL_CREDS = Boolean(process.env.TAQNYAT_MAIL_TOKEN) && Boolean(process.env.TAQNYAT_CAMPAIGN);
+const MAIL_TO = process.env.OKE_TEST_TAQNYAT_MAIL ?? process.env.TAQNYAT_MAIL_TO;
+const LIVE_MAIL = WANT_MAIL && MAIL_CREDS && Boolean(MAIL_TO);
+
+if (!LIVE_SMS) {
+  console.log(
+    WANT_SMS
+      ? "skip: taqnyat SMS OTP live (missing TAQNYAT_TOKEN/TAQNYAT_SENDER or OKE_TEST_TAQNYAT_PHONE)"
+      : "skip: taqnyat SMS OTP live (OKE_SMS_LIVE≠1)",
+  );
+}
+if (!LIVE_MAIL) {
+  console.log(
+    WANT_MAIL
+      ? "skip: taqnyat mail live (missing TAQNYAT_MAIL_TOKEN/TAQNYAT_CAMPAIGN or OKE_TEST_TAQNYAT_MAIL)"
+      : "skip: taqnyat mail live (OKE_EMAIL_LIVE≠1)",
+  );
+}
+
+const liveSms = LIVE_SMS ? test : test.skip;
+const liveMail = LIVE_MAIL ? test : test.skip;
+
+describe("taqnyat live — provider-managed OTP (Taqnyat Verify)", () => {
+  liveSms(
+    "phone OTP request → real sendOtp → Taqnyat success code 5",
+    async () => {
+      const app = oke({
+        name: `taqnyat-live-${crypto.randomUUID()}`,
+        env: "test",
+        registry: "ignore",
+        gate: { auth: { secret: SECRET } },
+        config: {
+          drivers: { channel: { sms: { test: "taqnyat" } } },
+        },
+      }).plug(phoneNumber());
+      await app.boot({ env: "test" });
+
+      // Wrap the live transport so the plugin's single real send also proves
+      // the provider accepted it (success code 5) — exactly one SMS, never two.
+      const sms = app.bootResult?.channel?.drivers.find((d) => d.id === "taqnyat")?.smsTransport as
+        | {
+            sendOtp(o: {
+              to: string;
+              requestId: string;
+              lang?: "en" | "ar";
+            }): Promise<{ code: number }>;
+          }
+        | undefined;
+      expect(sms).toBeDefined();
+      const realSendOtp = sms!.sendOtp.bind(sms);
+      let providerCode: number | undefined;
+      sms!.sendOtp = async (opts) => {
+        const result = await realSendOtp(opts);
+        providerCode = result.code;
+        return result;
+      };
+
+      const res = await app.fetch(
+        jsonPost("/auth/phone/request", { phone: SMS_PHONE, lang: "en" }),
+      );
+      const body = (await res.json()) as { data?: { ok: true }; error?: { message?: string } };
+      if (res.status !== 200) {
+        console.log("taqnyat sendOtp response", res.status, body);
+      }
+      expect(res.status).toBe(200);
+      expect(body.data?.ok).toBe(true);
+      // Local dev leak must stay off in the provider path.
+      expect((body.data as { devOtp?: string }).devOtp).toBeUndefined();
+      // Taqnyat Verify documented success code — from the plugin's own send.
+      expect(providerCode).toBe(5);
+
+      await app.stop();
+    },
+    30_000,
+  );
+});
+
+describe("taqnyat live — magic-link via Taqnyat Mail", () => {
+  liveMail(
+    "magic-link request → real TaqnyatMailTransport send",
+    async () => {
+      const app = oke({
+        name: `taqnyat-mail-live-${crypto.randomUUID()}`,
+        env: "test",
+        registry: "ignore",
+        gate: { auth: { secret: SECRET } },
+        config: {
+          drivers: { channel: { email: { test: "taqnyat-mail" } } },
+        },
+      }).plug(magicLink({ baseUrl: "http://app.test:6530" }));
+      await app.boot({ env: "test" });
+
+      const res = await app.fetch(jsonPost("/auth/magic-link/request", { email: MAIL_TO }));
+      const body = (await res.json()) as { data?: { ok: true }; error?: { message?: string } };
+      if (res.status !== 200) {
+        console.log("taqnyat mail send response", res.status, body);
+      }
+      expect(res.status).toBe(200);
+      expect(body.data?.ok).toBe(true);
+      expect((body.data as { devToken?: string }).devToken).toBeUndefined();
+
+      // A successful send is recorded in the Channel receipt ledger.
+      const receipts = app.bootResult?.channel?.receipts.all() ?? [];
+      const sent = receipts.find((r) => r.to === MAIL_TO);
+      expect(sent?.status === "sent" || sent?.status === "fallback").toBe(true);
+      expect(sent?.driverId).toContain("taqnyat");
+
+      await app.stop();
+    },
+    30_000,
+  );
+});