okengine 0.9.0 → 0.10.0

package/src/docker/recipes/postgres.ts

@@ -1,28 +1,15 @@
 /**
- * Postgres / pgvector / Timescale image recipe (≤15 lines of recipe body).
+ * Postgres / pgvector image recipe (≤15 lines of recipe body).
  */
 
-import { credEnv } from "../helpers.ts";
-import type { ImageRecipe, ServiceSpec } from "../types.ts";
+import { postgresEnv, postgresHealth } from "../helpers.ts";
+import type { ImageRecipe } from "../types.ts";
 
-const postgresEnv = (s: ServiceSpec) => ({
-  POSTGRES_USER: credEnv(s, "USER"),
-  POSTGRES_PASSWORD: credEnv(s, "PASSWORD"),
-  POSTGRES_DB: credEnv(s, "DB"),
-});
-
-const postgresHealth = {
-  test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER"],
-  interval: "5s",
-  timeout: "3s",
-  retries: 10,
-};
-
-/** Postgres-protocol servers (Postgres · Neon · Supabase · pgvector · Timescale). */
+/** Postgres-protocol servers (Postgres · pgvector). Timescale / Supabase match first. */
 export const postgres: ImageRecipe = {
   id: "postgres",
   port: 5432,
-  match: (i) => /postgres|pgvector|timescale/i.test(i),
+  match: (i) => /postgres|pgvector/i.test(i),
   apply: (s) => ({ environment: postgresEnv(s), healthcheck: postgresHealth }),
   url: (_s, c) =>
     `postgres://${c.user}:${encodeURIComponent(c.password)}@${c.host}:${c.port}/${c.database}`,

package/src/docker/recipes/sglang.ts

@@ -0,0 +1,55 @@
+/**
+ * SGLang image recipe — production-tier structured/agent inference.
+ *
+ * Prefer a managed provider unless you run inference yourself. Use SGLang when
+ * the workload is structured generation / agent-heavy on real GPU hardware;
+ * use vLLM for general multi-user serving. Pin an explicit tag — never
+ * `latest`. Host publish is loopback-only.
+ */
+
+import type { ImageRecipe } from "../types.ts";
+
+/** Pinned SGLang runtime image — never `latest`. */
+export const SGLANG_IMAGE = "lmsysorg/sglang:v0.5.16-runtime";
+
+/** SGLang — OpenAI-compatible HTTP on 30000; GPU reservation; loopback publish. */
+export const sglang: ImageRecipe = {
+  id: "sglang",
+  port: 30000,
+  match: (i) => /sglang/i.test(i),
+  apply: (s) => ({
+    command: [
+      "python3",
+      "-m",
+      "sglang.launch_server",
+      "--model-path",
+      "${OKE_AI_MODEL:-Qwen/Qwen3-0.6B}",
+      "--host",
+      "0.0.0.0",
+      "--port",
+      "30000",
+    ],
+    environment: {
+      OKE_AI_MODEL: "${OKE_AI_MODEL:-Qwen/Qwen3-0.6B}",
+      HF_HOME: "/root/.cache/huggingface",
+    },
+    volumes: [`${s.serviceName}-models:/root/.cache/huggingface`],
+    ipc: "host",
+    publishBind: "127.0.0.1",
+    deploy: {
+      resources: {
+        reservations: {
+          devices: [{ driver: "nvidia", count: "all", capabilities: ["gpu"] }],
+        },
+      },
+    },
+    healthcheck: {
+      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:30000/health >/dev/null || exit 1"],
+      interval: "10s",
+      timeout: "5s",
+      retries: 30,
+      start_period: "120s",
+    },
+  }),
+  url: (_s, c) => `http://${c.host}:${c.port}/v1`,
+};

package/src/docker/recipes/supabase.ts

@@ -0,0 +1,21 @@
+/**
+ * Supabase image recipe — self-hosted `supabase/postgres` (Postgres + bundled extensions).
+ *
+ * Postgres-protocol only: the Auth / Storage / Realtime / Kong / Studio layer of the
+ * full Supabase stack is not run here — oke already covers those with Vault, Store ·
+ * files, and Signal. This recipe just gets you Postgres plus Supabase's extension
+ * bundle (pgvector, pg_graphql, pg_cron, wrappers, …) without the rest of the platform.
+ */
+
+import { postgresEnv, postgresHealth } from "../helpers.ts";
+import type { ImageRecipe } from "../types.ts";
+
+/** Supabase Postgres image — checked before the generic `postgres` recipe. */
+export const supabase: ImageRecipe = {
+  id: "supabase",
+  port: 5432,
+  match: (i) => /supabase\/postgres/i.test(i),
+  apply: (s) => ({ environment: postgresEnv(s), healthcheck: postgresHealth }),
+  url: (_s, c) =>
+    `postgres://${c.user}:${encodeURIComponent(c.password)}@${c.host}:${c.port}/${c.database}`,
+};

package/src/docker/recipes/timescale.ts

@@ -0,0 +1,18 @@
+/**
+ * TimescaleDB image recipe — Postgres + hypertables (same POSTGRES_* contract).
+ *
+ * Driver id stays `postgres`. Matched ahead of the generic Postgres recipe.
+ */
+
+import { postgresEnv, postgresHealth } from "../helpers.ts";
+import type { ImageRecipe } from "../types.ts";
+
+/** TimescaleDB — Postgres protocol on 5432. */
+export const timescale: ImageRecipe = {
+  id: "timescale",
+  port: 5432,
+  match: (i) => /timescale/i.test(i),
+  apply: (s) => ({ environment: postgresEnv(s), healthcheck: postgresHealth }),
+  url: (_s, c) =>
+    `postgres://${c.user}:${encodeURIComponent(c.password)}@${c.host}:${c.port}/${c.database}`,
+};

package/src/docker/recipes/vllm.ts

@@ -0,0 +1,44 @@
+/**
+ * vLLM image recipe — production-tier local inference (`vllm/vllm-openai`).
+ *
+ * OpenAI-compatible server for multi-user GPU concurrency. Prefer a managed
+ * provider unless you run inference yourself. Pin an explicit tag — never
+ * `latest`. Host publish is loopback-only (same hard rule as llama.cpp).
+ */
+
+import type { ImageRecipe } from "../types.ts";
+
+/** Pinned vLLM OpenAI server image — never `latest`. */
+export const VLLM_IMAGE = "vllm/vllm-openai:v0.26.0";
+
+/** vLLM — OpenAI-compatible HTTP on 8000; GPU reservation; loopback publish. */
+export const vllm: ImageRecipe = {
+  id: "vllm",
+  port: 8000,
+  match: (i) => /(?:^|\/)vllm(?:[:@/]|$)/i.test(i),
+  apply: (s) => ({
+    command: ["--model", "${OKE_AI_MODEL:-Qwen/Qwen3-0.6B}", "--host", "0.0.0.0", "--port", "8000"],
+    environment: {
+      OKE_AI_MODEL: "${OKE_AI_MODEL:-Qwen/Qwen3-0.6B}",
+      HF_HOME: "/root/.cache/huggingface",
+    },
+    volumes: [`${s.serviceName}-models:/root/.cache/huggingface`],
+    ipc: "host",
+    publishBind: "127.0.0.1",
+    deploy: {
+      resources: {
+        reservations: {
+          devices: [{ driver: "nvidia", count: "all", capabilities: ["gpu"] }],
+        },
+      },
+    },
+    healthcheck: {
+      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8000/health >/dev/null || exit 1"],
+      interval: "10s",
+      timeout: "5s",
+      retries: 30,
+      start_period: "120s",
+    },
+  }),
+  url: (_s, c) => `http://${c.host}:${c.port}/v1`,
+};

package/src/docker/recipes/yugabyte.ts

@@ -0,0 +1,23 @@
+/**
+ * YugabyteDB image recipe — self-hosted single-node YSQL (Postgres-wire).
+ *
+ * Driver id stays `postgres`. Official image: `yugabytedb/yugabyte`.
+ */
+
+import { yugabyteEnv, yugabyteHealth } from "../helpers.ts";
+import type { ImageRecipe } from "../types.ts";
+
+/** YugabyteDB — YSQL on 5433. */
+export const yugabyte: ImageRecipe = {
+  id: "yugabyte",
+  port: 5433,
+  match: (i) => /yugabyte/i.test(i),
+  apply: (s) => ({
+    environment: yugabyteEnv(s),
+    command: ["bin/yugabyted", "start", "--base_dir=/home/yugabyte/yb_data", "--background=false"],
+    healthcheck: yugabyteHealth,
+    volumes: [`${s.serviceName}-data:/home/yugabyte/yb_data`],
+  }),
+  url: (_s, c) =>
+    `postgres://${c.user}:${encodeURIComponent(c.password)}@${c.host}:${c.port}/${c.database}`,
+};

package/src/docker/stack-id.test.ts

@@ -3,10 +3,14 @@
  */
 
 import { describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import {
   extraHostPortForInstance,
   hostPortForInstance,
   instancePortOffset,
+  loadExistingStackControls,
   parseStackControls,
   parseStackCredentials,
   stackAppSlug,
@@ -51,6 +55,24 @@ describe("hostPortForInstance", () => {
   });
 });
 
+describe("loadExistingStackControls", () => {
+  test("seeds OKE_AI_MODEL from .env.local when .env.docker omits it", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-stack-ai-"));
+    await writeFile(join(dir, ".env.local"), "OKE_AI_MODEL=gemma4:e4b-q4_K_M\n", "utf8");
+    const controls = await loadExistingStackControls(dir);
+    expect(controls?.OKE_AI_MODEL).toBe("gemma4:e4b-q4_K_M");
+  });
+
+  test("prefers active OKE_AI_MODEL in docker/.env.docker over .env.local", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-stack-ai-"));
+    await mkdir(join(dir, "docker"), { recursive: true });
+    await writeFile(join(dir, "docker", ".env.docker"), "OKE_AI_MODEL=smollm2\n", "utf8");
+    await writeFile(join(dir, ".env.local"), "OKE_AI_MODEL=gemma4:e4b-q4_K_M\n", "utf8");
+    const controls = await loadExistingStackControls(dir);
+    expect(controls?.OKE_AI_MODEL).toBe("smollm2");
+  });
+});
+
 describe("parseStackCredentials", () => {
   test("reads OKE_* credential keys", () => {
     const text = `

package/src/docker/stack-id.ts

@@ -103,7 +103,9 @@ export function parseStackCredentials(
       map.get(`${prefix}_USER`) ?? (role === "store.files" ? map.get("S3_ACCESS_KEY_ID") : "oke");
     const password =
       map.get(`${prefix}_PASSWORD`) ??
-      (role === "store.files" ? map.get("S3_SECRET_ACCESS_KEY") : undefined);
+      (role === "store.files" ? map.get("S3_SECRET_ACCESS_KEY") : undefined) ??
+      // Meilisearch master key is written as OKE_STORE_INDEX_KEY (not *_PASSWORD).
+      (role === "store.index" ? map.get("OKE_STORE_INDEX_KEY") : undefined);
     const database = map.get(`${prefix}_DB`) ?? "oke";
     if (user && password && database) {
       out[role] = { user, password, database };
@@ -128,6 +130,9 @@ export const STACK_CONTROL_KEYS = [
   "OKE_AI_MODEL",
   "OKE_PROXY_HOST",
   "OKE_PROXY_ACME_EMAIL",
+  // OpenBao app token — minted by bootstrap, must survive `writeDerivedFiles`.
+  "OKE_VAULT_TOKEN",
+  "OKE_VAULT_MOUNT",
 ] as const;
 
 /**
@@ -170,19 +175,48 @@ export async function loadExistingStackCredentials(
 /**
  * Load optional controls from `docker/.env.docker` when present.
  *
+ * Falls back to `.oke/openbao/app.token` for `OKE_VAULT_TOKEN` when the env
+ * file was regenerated without the bootstrap overlay (per-project token).
+ *
  * @param cwd - Project root
  */
 export async function loadExistingStackControls(
   cwd: string,
 ): Promise<Readonly<Record<string, string>> | undefined> {
   const candidates = [resolve(cwd, DEFAULT_DOCKER_DIR, ".env.docker"), resolve(cwd, ".env.docker")];
+  let controls: Record<string, string> = {};
   for (const path of candidates) {
     const file = Bun.file(path);
     if (!(await file.exists())) continue;
-    const controls = parseStackControls(await file.text());
-    if (Object.keys(controls).length > 0) return controls;
+    controls = parseStackControls(await file.text());
+    break;
   }
-  return undefined;
+  // create-oke / `oke ai setup` write the chosen model into `.env.local`.
+  // Seed it into stack controls on first docker boot so `LLAMA_ARG_DOCKER_REPO`
+  // is not stuck on the recipe default (`smollm2`).
+  if (!controls.OKE_AI_MODEL) {
+    const localEnv = Bun.file(resolve(cwd, ".env.local"));
+    if (await localEnv.exists()) {
+      const model = parseDotenv(await localEnv.text())
+        .get("OKE_AI_MODEL")
+        ?.trim();
+      if (model) controls = { ...controls, OKE_AI_MODEL: model };
+    }
+  }
+  if (!controls.OKE_VAULT_TOKEN) {
+    const tokenFile = Bun.file(resolve(cwd, ".oke", "openbao", "app.token"));
+    if (await tokenFile.exists()) {
+      const token = (await tokenFile.text()).trim();
+      if (token) {
+        controls = {
+          ...controls,
+          OKE_VAULT_TOKEN: token,
+          OKE_VAULT_MOUNT: controls.OKE_VAULT_MOUNT ?? "secret",
+        };
+      }
+    }
+  }
+  return Object.keys(controls).length > 0 ? controls : undefined;
 }
 
 function parseDotenv(text: string): Map<string, string> {

package/src/docker/types.ts

@@ -56,6 +56,12 @@ export interface RecipeExtraPort {
   readonly container: number;
 }
 
+/**
+ * Host bind for published ports — AI inference recipes set `127.0.0.1` so the
+ * raw API never lands on `0.0.0.0` (LAN/WAN). Omit for Docker's default bind.
+ */
+export type RecipePublishBind = "127.0.0.1";
+
 /** Compose `ulimits` value — soft/hard object or a single limit. */
 export type RecipeUlimit = number | { readonly soft?: number; readonly hard?: number };
 
@@ -73,6 +79,15 @@ export interface RecipeApplyResult {
   readonly labels?: Readonly<Record<string, string>>;
   /** Additional published ports (e.g. Mailpit UI, RustFS console). */
   readonly extraPorts?: readonly RecipeExtraPort[];
+  /**
+   * Host interface for published ports. AI recipes use `127.0.0.1` — never
+   * omit this for inference servers (raw API must not bind `0.0.0.0`).
+   */
+  readonly publishBind?: RecipePublishBind;
+  /** Compose `ipc` (e.g. vLLM `host` for shared-memory workers). */
+  readonly ipc?: string;
+  /** Compose `deploy` (e.g. GPU device reservations for vLLM / SGLang). */
+  readonly deploy?: Readonly<Record<string, unknown>>;
   /**
    * Compose `depends_on` (e.g. pooler waits for Postgres).
    * Keys are compose service names (`store-sql`), not role keys.

package/src/drivers/ai-ollama.integration.test.ts

@@ -3,8 +3,8 @@
  *
  * Opt-in (never auto-pull a multi-GB model in ordinary `bun test`):
  * 1. `OKE_TEST_OLLAMA_URL` — point at any reachable Ollama
- * 2. `OKE_TEST_OLLAMA_DOCKER=1` — start `ollama/ollama` via the recipe and pull
- *    `qwen3.5:9b` (slow first run)
+ * 2. `OKE_TEST_OLLAMA_DOCKER=1` — start `ollama/ollama` via the recipe; host-side
+ *    `ensureOllamaModel` POSTs `/api/pull` for `qwen3.5:9b` (slow first run)
  *
  * Without one of those, the suite skips with a visible reason (never an empty pass).
  * A local daemon on :11434 is not enough — set `OKE_TEST_OLLAMA_URL` explicitly.
@@ -123,8 +123,11 @@ async function resolveLiveUrl(): Promise<{ url: string; model: string }> {
     await rm(dir, { recursive: true, force: true });
   };
 
-  // Model pull can take a long time on first run.
-  await waitForOllama(url, 20 * 60_000, true);
+  // Serve must answer before we POST /api/pull (same path as `oke dev -d`).
+  await waitForOllama(url, 120_000, false);
+  const { ensureOllamaModel } = await import("../docker/ollama-pull.ts");
+  await ensureOllamaModel({ url, model: OLLAMA_DEFAULT_MODEL });
+  await waitForOllama(url, 60_000, true);
   return { url, model: OLLAMA_DEFAULT_MODEL };
 }
 

package/src/drivers/signal-engine.ts

@@ -39,6 +39,8 @@ interface MutMessage {
   payload: unknown;
   /** Optional per-key ordering token (`once` serialization). */
   key: string | null;
+  /** Producer run id for trace parent/child joins. */
+  parentRunId: string | null;
   delivery: SignalDelivery;
   attempts: number;
   failures: SignalFailureReason[];
@@ -163,6 +165,7 @@ export async function createSignalEngine(
       messages = snap.messages.map((m) => ({
         ...m,
         key: m.key ?? null,
+        parentRunId: m.parentRunId ?? null,
         lockedBy: m.lockedBy,
         leaseExpiresAt: m.leaseExpiresAt ?? null,
         deliveredTo: new Set(m.deliveredTo),
@@ -179,6 +182,7 @@ export async function createSignalEngine(
         signal: m.signal,
         payload: m.payload,
         key: m.key,
+        parentRunId: m.parentRunId,
         delivery: m.delivery,
         attempts: m.attempts,
         failures: m.failures,
@@ -230,11 +234,16 @@ export async function createSignalEngine(
     const value = await validateSignalEmitPayload(name, decl, payload);
     const t = now();
     const key = typeof options?.key === "string" && options.key.length > 0 ? options.key : null;
+    const parentRunId =
+      typeof options?.parentRunId === "string" && options.parentRunId.length > 0
+        ? options.parentRunId
+        : null;
     stagedMessages.push({
       id: crypto.randomUUID(),
       signal: name,
       payload: value,
       key,
+      parentRunId,
       delivery: decl.delivery,
       attempts: 0,
       failures: [],
@@ -332,6 +341,7 @@ export async function createSignalEngine(
       signal: m.signal,
       payload: m.payload,
       ...(m.key !== null ? { key: m.key } : {}),
+      ...(m.parentRunId !== null ? { parentRunId: m.parentRunId } : {}),
       delivery: m.delivery,
       attempts: m.attempts,
       failures: [...m.failures],

package/src/drivers/signal-postgres.ts

@@ -44,6 +44,7 @@ interface MsgRow {
   locked_by: string | null;
   lease_expires_at: number | null;
   delivered_to: string;
+  parent_run_id: string | null;
 }
 
 /** Minimal SQL + listen surface for the postgres signal driver. */
@@ -113,6 +114,7 @@ export function createPostgresSignalFake(options?: {
         ...m,
         ordering_key: m.ordering_key ?? null,
         lease_expires_at: m.lease_expires_at ?? null,
+        parent_run_id: m.parent_run_id ?? null,
       })),
       writes: new Map(snap.writes),
     };
@@ -304,6 +306,10 @@ export function createPostgresSignalFake(options?: {
               ? null
               : Number(row.lease_expires_at),
           delivered_to: String(row.delivered_to ?? "[]"),
+          parent_run_id:
+            row.parent_run_id === undefined || row.parent_run_id === null
+              ? null
+              : String(row.parent_run_id),
         });
         return { changes: 1 };
       }
@@ -409,7 +415,8 @@ async function ensureSchema(sql: PostgresSignalSql): Promise<void> {
     status TEXT,
     locked_by TEXT,
     lease_expires_at BIGINT,
-    delivered_to TEXT
+    delivered_to TEXT,
+    parent_run_id TEXT
   )`);
   // Existing tables created before leases / keys: add columns in place.
   try {
@@ -424,6 +431,11 @@ async function ensureSchema(sql: PostgresSignalSql): Promise<void> {
   } catch {
     /* fake / older engines without IF NOT EXISTS — ignore */
   }
+  try {
+    await sql.exec(`ALTER TABLE oke_signal_messages ADD COLUMN IF NOT EXISTS parent_run_id TEXT`);
+  } catch {
+    /* fake / older engines without IF NOT EXISTS — ignore */
+  }
   await sql.exec(`CREATE TABLE IF NOT EXISTS oke_signal_writes (
     key TEXT PRIMARY KEY,
     value TEXT
@@ -435,11 +447,16 @@ function rowToMessage(row: Record<string, unknown>): SignalMessage {
     row.ordering_key === undefined || row.ordering_key === null || row.ordering_key === ""
       ? undefined
       : String(row.ordering_key);
+  const parentRunId =
+    row.parent_run_id === undefined || row.parent_run_id === null || row.parent_run_id === ""
+      ? undefined
+      : String(row.parent_run_id);
   return {
     id: String(row.id),
     signal: String(row.signal),
     payload: JSON.parse(String(row.payload)),
     ...(key !== undefined ? { key } : {}),
+    ...(parentRunId !== undefined ? { parentRunId } : {}),
     delivery: row.delivery as SignalDelivery,
     attempts: Number(row.attempts),
     failures: JSON.parse(String(row.failures ?? "[]")) as SignalFailureReason[],
@@ -554,8 +571,12 @@ export async function openPostgresSignal(options: SignalOpenOptions): Promise<Si
     const t = now();
     const orderingKey =
       typeof options?.key === "string" && options.key.length > 0 ? options.key : null;
+    const parentRunId =
+      typeof options?.parentRunId === "string" && options.parentRunId.length > 0
+        ? options.parentRunId
+        : null;
     await tx.exec(
-      `INSERT INTO oke_signal_messages (id, signal, payload, ordering_key, delivery, attempts, failures, created_at, available_at, status, locked_by, lease_expires_at, delivered_to) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      `INSERT INTO oke_signal_messages (id, signal, payload, ordering_key, delivery, attempts, failures, created_at, available_at, status, locked_by, lease_expires_at, delivered_to, parent_run_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       [
         crypto.randomUUID(),
         signal,
@@ -570,6 +591,7 @@ export async function openPostgresSignal(options: SignalOpenOptions): Promise<Si
         null,
         null,
         "[]",
+        parentRunId,
       ],
     );
   }

package/src/drivers/signal-types.ts

@@ -40,6 +40,11 @@ export interface SignalEmitOptions {
    * Omit for pure competing-consumer behavior (no ordering guarantee).
    */
   readonly key?: string;
+  /**
+   * Producer WideEvent / run id for Console trace chains.
+   * Set automatically by `fx.emit` when the emitter has a run id.
+   */
+  readonly parentRunId?: string;
 }
 
 /** A durable signal message. */
@@ -49,6 +54,11 @@ export interface SignalMessage {
   readonly payload: unknown;
   /** Optional ordering key from {@link SignalEmitOptions.key}. */
   readonly key?: string;
+  /**
+   * Producer run id when the emit originated from a Flow execution.
+   * Consuming Runs record this as {@link import("../runs/types.ts").WideEvent.parentId}.
+   */
+  readonly parentRunId?: string;
   readonly delivery: SignalDelivery;
   readonly attempts: number;
   readonly failures: readonly SignalFailureReason[];

package/src/elements/channel/fallback.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Same-medium FallbackTransport adversarial proofs:
+ * - provider error advances the chain and delivers via secondary
+ * - permanent client errors (status 400 / invalid address) do NOT failover
+ *   (aligned with shouldFallbackOtpMedium)
+ */
+
+import { describe, expect, test } from "bun:test";
+import { channel, createChannelRuntime } from "../channel.ts";
+import { countingOkTransport, driverFromTransport, failingTransport } from "./test-helpers.ts";
+
+describe("FallbackTransport same-medium failover", () => {
+  test("provider error advances to secondary and delivers", async () => {
+    const secondary = countingOkTransport("resend");
+    const runtime = createChannelRuntime({
+      templates: [channel.template("booking", { medium: "email" })],
+      drivers: [
+        driverFromTransport(
+          "smtp",
+          failingTransport(
+            "smtp",
+            Object.assign(new Error("provider timeout"), { statusCode: 500 }),
+          ),
+        ),
+        driverFromTransport("resend", secondary.transport),
+      ],
+      catalog: { booking: { en: { subject: "Booked", text: "ok" } } },
+    });
+
+    const result = await runtime.send("booking", {
+      to: "user@example.com",
+      via: ["smtp", "resend"],
+    });
+
+    expect(result.ok).toBe(true);
+    expect(secondary.calls.count).toBe(1);
+    expect(result.attempts.some((a) => a.driverId === "smtp" && !a.ok)).toBe(true);
+    expect(result.attempts.some((a) => a.ok)).toBe(true);
+
+    const receipt = runtime.receipts.forTemplate("booking")[0]!;
+    expect(receipt.status).toBe("fallback");
+    expect(receipt.attempts.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("statusCode 400 does not advance to secondary", async () => {
+    const secondary = countingOkTransport("resend");
+    const runtime = createChannelRuntime({
+      templates: [channel.template("booking", { medium: "email" })],
+      drivers: [
+        driverFromTransport(
+          "smtp",
+          failingTransport("smtp", Object.assign(new Error("bad request"), { statusCode: 400 })),
+        ),
+        driverFromTransport("resend", secondary.transport),
+      ],
+    });
+
+    const result = await runtime.send("booking", {
+      to: "user@example.com",
+      via: ["smtp", "resend"],
+    });
+
+    expect(secondary.calls.count).toBe(0);
+    expect(result.ok).toBe(false);
+    expect(result.attempts.every((a) => a.driverId !== "resend")).toBe(true);
+  });
+
+  test("invalid recipient address does not advance to secondary", async () => {
+    const secondary = countingOkTransport("resend");
+    const runtime = createChannelRuntime({
+      templates: [channel.template("booking", { medium: "email" })],
+      drivers: [
+        driverFromTransport(
+          "smtp",
+          failingTransport("smtp", new Error("invalid recipient address")),
+        ),
+        driverFromTransport("resend", secondary.transport),
+      ],
+    });
+
+    const result = await runtime.send("booking", {
+      to: "not-an-email",
+      via: ["smtp", "resend"],
+    });
+
+    expect(secondary.calls.count).toBe(0);
+    expect(result.ok).toBe(false);
+    const receipt = runtime.receipts.forTemplate("booking")[0]!;
+    expect(receipt.status).toBe("blocked/invalid-address");
+  });
+});