okengine 0.2.6 → 0.3.2

package/src/elements/vault.ts

@@ -2,7 +2,7 @@
  * Vault element — protected knowledge.
  *
  * Physics: secrets · config · environment.
- * Drivers: `sops` (Typage/age) · `env` · `openbao` · `infisical` · `managed`.
+ * Drivers: `env` · `openbao` · `infisical` · `managed`.
  *
  * A declaration is a contract, never a value. Boot validates every contract
  * and lists all gaps at once. Logs/traces receive fingerprints and redaction
@@ -12,15 +12,12 @@
 
 export {
   vault,
-  fromStack,
-  FROM_STACK_PREFIX,
-  isFromStack,
-  fromStackRole,
-} from "./vault/declare.ts";
-export type {
-  VaultSecretDecl,
-  VaultSecretOptions,
+  fromDocker,
+  FROM_DOCKER_PREFIX,
+  isFromDocker,
+  fromDockerRole,
 } from "./vault/declare.ts";
+export type { VaultSecretDecl, VaultSecretOptions } from "./vault/declare.ts";
 
 export {
   createVaultRuntime,
@@ -37,9 +34,8 @@ export type {
   VaultRuntime,
 } from "./vault/runtime.ts";
 
-export {
-  fingerprintSecret,
-  fingerprintSecretSync,
-} from "./vault/fingerprint.ts";
+export { COMPOSE_ENV_REL, resolveComposeEnvPath } from "./vault/chain.ts";
+
+export { fingerprintSecret, fingerprintSecretSync } from "./vault/fingerprint.ts";
 
 export { createSecretRedactor } from "./vault/redact.ts";

package/src/index.ts

@@ -56,11 +56,14 @@ export {
   id,
   now,
   defineTable,
+  field,
   createStoreRuntime,
   type StoreDecl,
   type StoreRuntime,
   type SqlStoreHandle,
   type TableHandle,
+  type SchemaTableDecl,
+  type SchemaColumnDecl,
 } from "./elements/store.ts";
 
 export {
@@ -98,8 +101,8 @@ export {
 
 export {
   vault,
-  fromStack,
-  FROM_STACK_PREFIX,
+  fromDocker,
+  FROM_DOCKER_PREFIX,
   createVaultRuntime,
   VaultBootError,
   SECRET_MASK,

package/src/kernel/adopt-routes.ts

@@ -68,17 +68,12 @@ export type ErrorDataOf<E extends FlowErrorMap> = {
  *
  * @typeParam F - Flow definition
  */
-export type RouteFromFlow<F> = F extends FlowDef<
-  infer I,
-  infer O,
-  infer E,
-  any,
-  infer T
->
-  ? [T] extends [HttpTrigger<infer M, infer P>]
-    ? AppFlowRoute<I, O, ErrorDataOf<E>, M, P>
-    : AppFlowRoute<I, O, ErrorDataOf<E>>
-  : never;
+export type RouteFromFlow<F> =
+  F extends FlowDef<infer I, infer O, infer E, any, infer T>
+    ? [T] extends [HttpTrigger<infer M, infer P>]
+      ? AppFlowRoute<I, O, ErrorDataOf<E>, M, P>
+      : AppFlowRoute<I, O, ErrorDataOf<E>>
+    : never;
 
 /**
  * Map a flow namespace (`{ create, get, … }`) to a unit route table.
@@ -115,12 +110,11 @@ export type RoutesFromAdoptArg<A> = A extends AnyFlowDef
  *
  * @typeParam Args - Adopt argument tuple
  */
-export type RoutesFromAdoptArgs<Args extends readonly unknown[]> =
-  Args extends readonly []
-    ? {}
-    : Args extends readonly [infer H, ...infer T]
-      ? RoutesFromAdoptArg<H> & RoutesFromAdoptArgs<T>
-      : {};
+export type RoutesFromAdoptArgs<Args extends readonly unknown[]> = Args extends readonly []
+  ? {}
+  : Args extends readonly [infer H, ...infer T]
+    ? RoutesFromAdoptArg<H> & RoutesFromAdoptArgs<T>
+    : {};
 
 /** Runtime leaf: method/path when the flow has an HTTP trigger. */
 export interface RuntimeFlowRoute {
@@ -141,8 +135,7 @@ export type RuntimeRouteMap = {
  * @param flowDef - Flow definition
  */
 export function runtimeRouteFromFlow(flowDef: AnyFlowDef): RuntimeFlowRoute {
-  const trigger: Trigger | undefined =
-    flowDef.$trigger ?? flowDef.triggers[0];
+  const trigger: Trigger | undefined = flowDef.$trigger ?? flowDef.triggers[0];
   if (trigger?.kind === "http") {
     return { method: trigger.method, path: trigger.path };
   }
@@ -156,10 +149,7 @@ export function runtimeRouteFromFlow(flowDef: AnyFlowDef): RuntimeFlowRoute {
  * @param into - Mutable route map to extend
  * @returns Flows discovered (for `fx.call` registration)
  */
-export function accumulateAdoptArgs(
-  args: readonly unknown[],
-  into: RuntimeRouteMap,
-): AnyFlowDef[] {
+export function accumulateAdoptArgs(args: readonly unknown[], into: RuntimeRouteMap): AnyFlowDef[] {
   const found: AnyFlowDef[] = [];
 
   for (const arg of args) {
@@ -169,9 +159,7 @@ export function accumulateAdoptArgs(
     }
     if (typeof arg !== "object" || arg === null) continue;
 
-    for (const [unit, value] of Object.entries(
-      arg as Record<string, unknown>,
-    )) {
+    for (const [unit, value] of Object.entries(arg as Record<string, unknown>)) {
       if (isFlow(value)) {
         // Flat `{ create: flow }` without a unit wrapper — skip client map
         found.push(value);
@@ -180,9 +168,7 @@ export function accumulateAdoptArgs(
       if (typeof value !== "object" || value === null) continue;
 
       const unitBag = into[unit] ?? (into[unit] = {});
-      for (const [flowName, flowDef] of Object.entries(
-        value as Record<string, unknown>,
-      )) {
+      for (const [flowName, flowDef] of Object.entries(value as Record<string, unknown>)) {
         if (!isFlow(flowDef)) continue;
         found.push(flowDef);
         unitBag[flowName] = runtimeRouteFromFlow(flowDef);

package/src/kernel/app.ts

@@ -32,10 +32,7 @@ import {
   type CreateAppAuthBindingOptions,
 } from "./auth-resolve.ts";
 import { runDurable } from "../elements/clock/durable.ts";
-import {
-  isFlow,
-  type AnyFlowDef,
-} from "./flow.ts";
+import { isFlow, type AnyFlowDef } from "./flow.ts";
 import {
   createFxContext,
   resolveName,
@@ -65,7 +62,7 @@ import {
   isJournalSuspend,
   type JournalSession,
 } from "./journal.ts";
-import { listBindings, type Binding } from "./on.ts";
+import { listBindings, resetBindings, type Binding } from "./on.ts";
 import {
   applyPrincipal,
   createElementPipelineHooks,
@@ -80,16 +77,8 @@ import {
   type AccumulateDecorations,
 } from "./plug.ts";
 import type { PluginCapabilities, PluginDef } from "./plugin.ts";
-import {
-  createPluginRegistry,
-  type PluginRegistry,
-} from "./registry.ts";
-import {
-  createRouter,
-  type Router,
-  type RouterPreset,
-  type SmartRouter,
-} from "./router.ts";
+import { createPluginRegistry, type PluginRegistry } from "./registry.ts";
+import { createRouter, type Router, type RouterPreset, type SmartRouter } from "./router.ts";
 import type {
   CdcTrigger,
   EveryTrigger,
@@ -113,8 +102,23 @@ export interface OkeOptions {
    * Default `true`.
    */
   readonly aot?: boolean;
-  /** Extra bindings (in addition to the global {@link on} registry). */
+  /**
+   * Extra bindings. Combined with the global {@link on} registry unless
+   * {@link OkeOptions.registry} is `"ignore"` — then this is the only source.
+   */
   readonly bindings?: readonly Binding[];
+  /**
+   * How the global {@link on} registry is treated at construction.
+   *
+   * - `"consume"` (default) — adopt registered bindings, then clear the
+   *   registry so a later {@link oke} in the same process cannot inherit
+   *   this app's flows.
+   * - `"keep"` — adopt registered bindings and leave the registry intact
+   *   (legacy behavior).
+   * - `"ignore"` — adopt only {@link OkeOptions.bindings}; the registry is
+   *   neither read nor cleared (embedding / Console).
+   */
+  readonly registry?: "consume" | "keep" | "ignore";
   /** Base fx options applied to every invocation. */
   readonly fx?: Omit<CreateFxOptions, "flow" | "effects" | "capability">;
   /**
@@ -129,13 +133,13 @@ export interface OkeOptions {
    * subject key.
    */
   readonly archiveInputFields?: readonly string[];
-  /** Active environment for {@link OkeApp.boot} (defaults to `dev`). */
+  /** Active environment for {@link OkeApp.boot} (defaults to `local`). */
   readonly env?: BootOptions["env"];
   /**
-   * Local-server mode (`oke dev -s` / `OKE_STACK=1`) — force the `stack`
+   * Docker mode (`oke dev -d` / `OKE_DOCKER=1`) — force the `docker`
    * driver profile at boot.
    */
-  readonly stack?: BootOptions["stack"];
+  readonly docker?: BootOptions["docker"];
   /** Optional `oke.config.ts` document consumed at boot. */
   readonly config?: BootOptions["config"];
   /** Pre-built element runtimes (skip construction at boot when present). */
@@ -209,9 +213,7 @@ export interface UnitHooks<D extends Record<string, unknown> = {}> {
    *
    * @param pluginDef - Plugin from {@link plugin}
    */
-  plug<P extends PluginDef>(
-    pluginDef: P,
-  ): UnitHooks<AccumulateDecorations<D, P>>;
+  plug<P extends PluginDef>(pluginDef: P): UnitHooks<AccumulateDecorations<D, P>>;
 }
 
 /**
@@ -220,10 +222,7 @@ export interface UnitHooks<D extends Record<string, unknown> = {}> {
  * @typeParam D - Accumulated decoration types from app `.plug()`
  * @typeParam R - Accumulated client route map from `.adopt({ unit })`
  */
-export interface OkeApp<
-  D extends Record<string, unknown> = {},
-  R extends AppRouteMap = {},
-> {
+export interface OkeApp<D extends Record<string, unknown> = {}, R extends AppRouteMap = {}> {
   /** App name. */
   readonly name: string;
   /** Whether AoT compilation is enabled. */
@@ -269,9 +268,7 @@ export interface OkeApp<
    *
    * @param pluginDef - Plugin from {@link plugin}
    */
-  plug<P extends PluginDef>(
-    pluginDef: P,
-  ): OkeApp<AccumulateDecorations<D, P>, R>;
+  plug<P extends PluginDef>(pluginDef: P): OkeApp<AccumulateDecorations<D, P>, R>;
   /**
    * Captured plugin capabilities for the Manifest.
    */
@@ -357,10 +354,7 @@ export interface OkeApp<
    * @param signal - Signal name or handle
    * @param payload - Payload
    */
-  dispatchSignal(
-    signal: NamedRef,
-    payload?: unknown,
-  ): Promise<ExecuteResult[]>;
+  dispatchSignal(signal: NamedRef, payload?: unknown): Promise<ExecuteResult[]>;
   /**
    * Invoke all flows bound to an `every` interval.
    *
@@ -374,11 +368,7 @@ export interface OkeApp<
    * @param payload - before/after
    * @param column - Optional column filter
    */
-  dispatchCdc(
-    tableName: string,
-    payload: CdcPayload,
-    column?: string,
-  ): Promise<ExecuteResult[]>;
+  dispatchCdc(tableName: string, payload: CdcPayload, column?: string): Promise<ExecuteResult[]>;
   /**
    * Call a flow by name/handle (same path as `fx.call`).
    *
@@ -408,10 +398,12 @@ export interface OkeApp<
  */
 export function oke(options: OkeOptions): OkeApp {
   const aot = options.aot !== false;
-  const adopted: Binding[] = [
-    ...listBindings(),
-    ...(options.bindings ?? []),
-  ];
+  const registry = options.registry ?? "consume";
+  const adopted: Binding[] =
+    registry === "ignore"
+      ? [...(options.bindings ?? [])]
+      : [...listBindings(), ...(options.bindings ?? [])];
+  if (registry === "consume") resetBindings();
   /** Retained for test harness / boot merges. */
   const $options = options;
 
@@ -459,7 +451,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 bootEnv: BootOptions["env"] = options.env ?? "dev";
+  let bootEnv: BootOptions["env"] = options.env ?? "local";
   let authBinding: AppAuthBinding | undefined =
     options.auth !== undefined
       ? createAppAuthBinding({
@@ -490,10 +482,10 @@ export function oke(options: OkeOptions): OkeApp {
 
   async function doBoot(overrides?: Partial<BootOptions>): Promise<BootResult> {
     const { bootApplication } = await import("./boot.ts");
-    bootEnv = overrides?.env ?? options.env ?? "dev";
+    bootEnv = overrides?.env ?? options.env ?? "local";
     const merged: BootOptions = {
       env: bootEnv,
-      stack: overrides?.stack ?? options.stack,
+      docker: overrides?.docker ?? options.docker,
       config: overrides?.config ?? options.config,
       elements: overrides?.elements ?? options.elements,
       secrets: overrides?.secrets ?? options.secrets,
@@ -508,8 +500,7 @@ export function oke(options: OkeOptions): OkeApp {
       now: overrides?.now ?? options.fx?.now,
       instanceId: overrides?.instanceId,
       startScheduler: overrides?.startScheduler ?? options.startScheduler,
-      schedulerIntervalMs:
-        overrides?.schedulerIntervalMs ?? options.schedulerIntervalMs,
+      schedulerIntervalMs: overrides?.schedulerIntervalMs ?? options.schedulerIntervalMs,
       bindings: adopted,
       flows: [...flowsByName.values()],
       onCronFire: overrides?.onCronFire ?? handleCronFire,
@@ -542,9 +533,7 @@ export function oke(options: OkeOptions): OkeApp {
     return bootPromise;
   }
 
-  function isRunsRuntimeLike(
-    value: OkeOptions["runs"],
-  ): value is RunsRuntime {
+  function isRunsRuntimeLike(value: OkeOptions["runs"]): value is RunsRuntime {
     return (
       typeof value === "object" &&
       value !== null &&
@@ -570,20 +559,11 @@ export function oke(options: OkeOptions): OkeApp {
 
     const booted = await ensureBoot();
 
-    const unitBag =
-      flowDef.unit !== undefined ? unitHooks.get(flowDef.unit) : undefined;
+    const unitBag = flowDef.unit !== undefined ? unitHooks.get(flowDef.unit) : undefined;
     // app (hooks + plugs) → unit (hooks + plugs) → flow (hooks + plugs)
     const composedHooks = mergeHooks(
-      mergeHooks(
-        appHooks,
-        pluginRegistry.hooksAt("app", flowDef.unit, flowDef.name),
-        undefined,
-      ),
-      mergeHooks(
-        unitBag,
-        pluginRegistry.hooksAt("unit", flowDef.unit, flowDef.name),
-        undefined,
-      ),
+      mergeHooks(appHooks, pluginRegistry.hooksAt("app", flowDef.unit, flowDef.name), undefined),
+      mergeHooks(unitBag, pluginRegistry.hooksAt("unit", flowDef.unit, flowDef.name), undefined),
       mergeHooks(
         flowDef.hooks as HookMap,
         pluginRegistry.hooksAt("flow", flowDef.unit, flowDef.name),
@@ -591,10 +571,7 @@ export function oke(options: OkeOptions): OkeApp {
       ),
     );
 
-    const decorations = pluginRegistry.decorationsFor(
-      flowDef.unit,
-      flowDef.name,
-    );
+    const decorations = pluginRegistry.decorationsFor(flowDef.unit, flowDef.name);
 
     const ctx: InvocationContext = {
       trigger,
@@ -631,10 +608,7 @@ export function oke(options: OkeOptions): OkeApp {
       // a real HTTP request in production mode.
       const testMode = bootEnv === "test";
       if (testMode) {
-        applyPrincipal(
-          principals,
-          extras?.auth as ResolvedPrincipal | undefined,
-        );
+        applyPrincipal(principals, extras?.auth as ResolvedPrincipal | undefined);
         applyPrincipal(principals, extras?.principal);
         if (extras?.operator) principals.operator.id = extras.operator.id;
       }
@@ -645,9 +619,7 @@ export function oke(options: OkeOptions): OkeApp {
         principals,
         telemetry,
         allowTestPrincipals: testMode,
-        verifyBearer: binding
-          ? (token) => verifyBearerToken(binding, token)
-          : undefined,
+        verifyBearer: binding ? (token) => verifyBearerToken(binding, token) : undefined,
       });
 
       // Element hooks run first in the app-level onAuth/beforeHandle chain —
@@ -675,9 +647,7 @@ export function oke(options: OkeOptions): OkeApp {
       effects: flowDef.effects,
       runTelemetry: telemetry,
       now,
-      ...(principals
-        ? { auth: principals.auth as FxAuth, operator: principals.operator }
-        : {}),
+      ...(principals ? { auth: principals.auth as FxAuth, operator: principals.operator } : {}),
       ...(capability ? { capability } : {}),
       ...(booted
         ? {
@@ -704,29 +674,37 @@ export function oke(options: OkeOptions): OkeApp {
 
     const alreadyValidated = extras?.validated === true;
 
-    const result = await runPipeline(ctx, fx, hooks, async () => {
-      try {
-        if (!alreadyValidated) {
-          const parsed = await validate(flowDef.in, ctx.input);
-          if (!parsed.ok) return parsed.failure;
-          ctx.input = parsed.value;
-          return await flowDef.do(parsed.value as never, fx);
-        }
-        return await flowDef.do(ctx.input as never, fx);
-      } catch (err) {
-        // A durable sleep that has not yet elapsed suspends the run — this
-        // is a park, not a pipeline failure, so it must not throw upward.
-        if (flowDef.durable && journalSession && isJournalSuspend(err)) {
-          ctx.state.sleeping = {
-            wakeAt: err.wakeAt,
-            label: err.label,
-            runId: journalSession.runId,
-          };
-          return undefined;
+    const result = await runPipeline(
+      ctx,
+      fx,
+      hooks,
+      async () => {
+        try {
+          if (!alreadyValidated) {
+            const parsed = await validate(flowDef.in, ctx.input);
+            if (!parsed.ok) return parsed.failure;
+            ctx.input = parsed.value;
+            return await flowDef.do(parsed.value as never, fx);
+          }
+          return await flowDef.do(ctx.input as never, fx);
+        } catch (err) {
+          // A durable sleep that has not yet elapsed suspends the run — this
+          // is a park, not a pipeline failure, so it must not throw upward.
+          if (flowDef.durable && journalSession && isJournalSuspend(err)) {
+            ctx.state.sleeping = {
+              wakeAt: err.wakeAt,
+              label: err.label,
+              runId: journalSession.runId,
+            };
+            return undefined;
+          }
+          throw err;
         }
-        throw err;
-      }
-    });
+      },
+      // 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,
+    );
 
     const endedAt = now();
 
@@ -750,13 +728,9 @@ export function oke(options: OkeOptions): OkeApp {
     }
 
     const runsRuntime =
-      booted?.runs ??
-      (isRunsRuntimeLike(options.runs) ? options.runs : undefined);
+      booted?.runs ?? (isRunsRuntimeLike(options.runs) ? options.runs : undefined);
     if (runsRuntime) {
-      const archiveCleartext = archiveFromInput(
-        ctx.input,
-        options.archiveInputFields,
-      );
+      const archiveCleartext = archiveFromInput(ctx.input, options.archiveInputFields);
       await runsRuntime.record(
         {
           flow: flowDef,
@@ -936,8 +910,7 @@ export function oke(options: OkeOptions): OkeApp {
         if (parts.length >= 2) {
           const [unit, ...flowParts] = parts;
           const flowName = flowParts.join("/");
-          const target =
-            flowsByName.get(`${unit}.${flowName}`) ?? flowsByName.get(flowName);
+          const target = flowsByName.get(`${unit}.${flowName}`) ?? flowsByName.get(flowName);
           if (!target) {
             return respond(new Response("Not Found", { status: 404 }));
           }
@@ -960,6 +933,12 @@ export function oke(options: OkeOptions): OkeApp {
 
       const matched = router.match(method, url.pathname);
       if (!matched) {
+        // Plugin edge handlers answer requests no flow owns (e.g. CORS
+        // preflight for a path bound to another method) — first Response wins.
+        for (const handle of pluginRegistry.edgeHandlers()) {
+          const edgeResponse = await handle(request, { method, path: url.pathname });
+          if (edgeResponse !== undefined) return respond(edgeResponse);
+        }
         return respond(new Response("Not Found", { status: 404 }));
       }
       const { value: binding, params } = matched;
@@ -986,12 +965,11 @@ export function oke(options: OkeOptions): OkeApp {
         input = undefined;
       }
 
-      const result = await execute(
-        binding.flow,
-        input,
-        binding.trigger,
-        { request, params, validated },
-      );
+      const result = await execute(binding.flow, input, binding.trigger, {
+        request,
+        params,
+        validated,
+      });
 
       return respond(encodeExecuteResult(result));
     },
@@ -1000,9 +978,7 @@ export function oke(options: OkeOptions): OkeApp {
       const results: ExecuteResult[] = [];
       for (const b of adopted) {
         if (b.trigger.kind === "signal" && b.trigger.name === name) {
-          results.push(
-            await execute(b.flow, payload, b.trigger as SignalAsTrigger),
-          );
+          results.push(await execute(b.flow, payload, b.trigger as SignalAsTrigger));
         }
       }
       return results;
@@ -1011,9 +987,7 @@ export function oke(options: OkeOptions): OkeApp {
       const results: ExecuteResult[] = [];
       for (const b of adopted) {
         if (b.trigger.kind === "every" && b.trigger.interval === interval) {
-          results.push(
-            await execute(b.flow, undefined, b.trigger as EveryTrigger),
-          );
+          results.push(await execute(b.flow, undefined, b.trigger as EveryTrigger));
         }
       }
       return results;

package/src/kernel/auth-resolve.ts

@@ -36,9 +36,7 @@ export interface CreateAppAuthBindingOptions {
  *
  * @param options - Secret + optional session store / clock
  */
-export function createAppAuthBinding(
-  options: CreateAppAuthBindingOptions,
-): AppAuthBinding {
+export function createAppAuthBinding(options: CreateAppAuthBindingOptions): AppAuthBinding {
   return {
     secret: options.secret,
     sessions: options.sessions ?? createSessionStore(),
@@ -57,12 +55,7 @@ export async function verifyBearerToken(
   auth: AppAuthBinding,
   token: string,
 ): Promise<ResolvedPrincipal> {
-  const claims = await verifyAccess(
-    auth.sessions,
-    auth.secret,
-    token,
-    auth.now,
-  );
+  const claims = await verifyAccess(auth.sessions, auth.secret, token, auth.now);
   return claimsToPrincipal(claims);
 }
 

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

@@ -3,10 +3,7 @@
  */
 
 import { mockAiDriver } from "../../drivers/ai-mock.ts";
-import {
-  createAiRuntime,
-  type AiRuntime,
-} from "../../elements/ai.ts";
+import { createAiRuntime, type AiRuntime } from "../../elements/ai.ts";
 import type { GateRuntime } from "../../elements/gate.ts";
 import type { BootOptions } from "../boot.ts";
 

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

@@ -0,0 +1,60 @@
+/**
+ * Channel binder — profile selection + SMTP env parsing.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { resolveEmailDriverId, smtpOptionsFromEnv } from "./channel.ts";
+
+const previous = {
+  url: process.env.SMTP_URL,
+  user: process.env.SMTP_USER,
+  password: process.env.SMTP_PASSWORD,
+  okeUrl: process.env.OKE_CHANNEL_EMAIL_URL,
+};
+
+afterEach(() => {
+  restoreEnv("SMTP_URL", previous.url);
+  restoreEnv("SMTP_USER", previous.user);
+  restoreEnv("SMTP_PASSWORD", previous.password);
+  restoreEnv("OKE_CHANNEL_EMAIL_URL", previous.okeUrl);
+});
+
+describe("bindChannel driver resolution", () => {
+  const options = {
+    config: {
+      drivers: {
+        channel: {
+          email: { local: "console", docker: "smtp", test: "console", prod: "smtp" },
+        },
+      },
+    },
+  };
+
+  test("uses console locally and smtp in docker", () => {
+    expect(resolveEmailDriverId(options, "local", false)).toBe("console");
+    expect(resolveEmailDriverId(options, "docker", true)).toBe("smtp");
+  });
+
+  test("parses SMTP_URL and optional auth overrides", () => {
+    process.env.SMTP_URL = "smtp://url-user:url-pass@127.0.0.1:20975";
+    process.env.SMTP_USER = "override-user";
+    process.env.SMTP_PASSWORD = "override-pass";
+    expect(smtpOptionsFromEnv(true)).toEqual({
+      host: "127.0.0.1",
+      port: 20975,
+      user: "override-user",
+      pass: "override-pass",
+    });
+  });
+
+  test("missing SMTP_URL includes docker recovery hint", () => {
+    delete process.env.SMTP_URL;
+    delete process.env.OKE_CHANNEL_EMAIL_URL;
+    expect(() => smtpOptionsFromEnv(true)).toThrow("docker/.env.docker");
+  });
+});
+
+function restoreEnv(key: string, value: string | undefined): void {
+  if (value === undefined) delete process.env[key];
+  else process.env[key] = value;
+}