okengine 0.5.0 → 0.6.0

package/src/i18n/messages.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, test } from "bun:test";
+import { clearMessageFormatCache, formatMessage } from "./format.ts";
+import {
+  clearMessageCatalogs,
+  defineLocale,
+  defineMessages,
+  flattenMessages,
+  getMessageCatalogs,
+  matchConfiguredLocale,
+  translate,
+} from "./messages.ts";
+import type { FlattenKeys, MessagesFor } from "./types.ts";
+
+describe("flattenMessages", () => {
+  test("flattens nested trees with dot keys", () => {
+    expect(
+      flattenMessages({
+        errors: { notFound: "Missing" },
+        hello: "Hi",
+      }),
+    ).toEqual({
+      "errors.notFound": "Missing",
+      hello: "Hi",
+    });
+  });
+});
+
+describe("defineLocale / getMessageCatalogs", () => {
+  test("registers overlays that win over built-ins", () => {
+    clearMessageCatalogs();
+    defineLocale("en", { greeting: "Hello, {name}" });
+    defineLocale("ar", { greeting: "مرحباً، {name}" });
+    const catalogs = getMessageCatalogs();
+    expect(catalogs.en?.greeting).toBe("Hello, {name}");
+    expect(catalogs.ar?.greeting).toBe("مرحباً، {name}");
+    // Built-ins remain available under the same locale.
+    expect(catalogs.en?.["errors.Unauthorized"]).toBe("Authentication required.");
+    defineLocale("en", { greeting: "Hi, {name}" });
+    expect(getMessageCatalogs().en?.greeting).toBe("Hi, {name}");
+    clearMessageCatalogs();
+  });
+});
+
+describe("formatMessage — ICU", () => {
+  test("interpolates simple placeholders", () => {
+    clearMessageFormatCache();
+    expect(formatMessage("Hello, {name}", "en", { name: "Ada" })).toBe("Hello, Ada");
+  });
+
+  test("cardinal plurals", () => {
+    clearMessageFormatCache();
+    const msg = "{count, plural, =0 {no items} one {# item} other {# items}}";
+    expect(formatMessage(msg, "en", { count: 0 })).toBe("no items");
+    expect(formatMessage(msg, "en", { count: 1 })).toBe("1 item");
+    expect(formatMessage(msg, "en", { count: 5 })).toBe("5 items");
+  });
+
+  test("ordinal plurals via selectordinal", () => {
+    clearMessageFormatCache();
+    const msg = "You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!";
+    expect(formatMessage(msg, "en", { place: 1 })).toBe("You finished 1st!");
+    expect(formatMessage(msg, "en", { place: 2 })).toBe("You finished 2nd!");
+    expect(formatMessage(msg, "en", { place: 3 })).toBe("You finished 3rd!");
+    expect(formatMessage(msg, "en", { place: 11 })).toBe("You finished 11th!");
+  });
+
+  test("enum select", () => {
+    clearMessageFormatCache();
+    const msg = "{status, select, online {Online} offline {Offline} other {Unknown}}";
+    expect(formatMessage(msg, "en", { status: "online" })).toBe("Online");
+    expect(formatMessage(msg, "en", { status: "offline" })).toBe("Offline");
+    expect(formatMessage(msg, "en", { status: "away" })).toBe("Unknown");
+  });
+
+  test("rich text tags via function values", () => {
+    clearMessageFormatCache();
+    const msg = "Read <docs>the docs</docs>.";
+    expect(
+      formatMessage(msg, "en", {
+        docs: (chunks) => `[${chunks.join("")}]`,
+      }),
+    ).toBe("Read [the docs].");
+  });
+
+  test("Arabic plural sample", () => {
+    clearMessageFormatCache();
+    const msg =
+      "{count, plural, zero {لا عناصر} one {عنصر واحد} two {عنصران} few {# عناصر} many {# عنصراً} other {# عنصر}}";
+    expect(formatMessage(msg, "ar", { count: 0 })).toBe("لا عناصر");
+    expect(formatMessage(msg, "ar", { count: 1 })).toBe("عنصر واحد");
+    expect(formatMessage(msg, "ar", { count: 2 })).toBe("عنصران");
+  });
+});
+
+describe("translate", () => {
+  const catalogs = {
+    en: {
+      "errors.notFound": "Not found",
+      greeting: "Hello, {name}",
+      items: "{count, plural, one {# item} other {# items}}",
+    },
+    ar: {
+      greeting: "مرحباً، {name}",
+    },
+  };
+
+  test("uses locale, then default, then key", () => {
+    expect(
+      translate({
+        locale: "ar",
+        defaultLocale: "en",
+        catalogs,
+        key: "greeting",
+        values: { name: "Ada" },
+      }),
+    ).toBe("مرحباً، Ada");
+    expect(
+      translate({
+        locale: "ar",
+        defaultLocale: "en",
+        catalogs,
+        key: "errors.notFound",
+      }),
+    ).toBe("Not found");
+    expect(
+      translate({
+        locale: "en",
+        defaultLocale: "en",
+        catalogs,
+        key: "items",
+        values: { count: 3 },
+      }),
+    ).toBe("3 items");
+    expect(
+      translate({
+        locale: "ar",
+        defaultLocale: "en",
+        catalogs,
+        key: "missing",
+        values: { x: 1 },
+      }),
+    ).toBe('missing:{"x":1}');
+  });
+});
+
+describe("matchConfiguredLocale", () => {
+  test("matches exact, base tag, then default", () => {
+    const locales = ["en", "ar"] as const;
+    expect(matchConfiguredLocale("ar", locales, "en")).toBe("ar");
+    expect(matchConfiguredLocale("ar-SA", locales, "en")).toBe("ar");
+    expect(matchConfiguredLocale("fr", locales, "en")).toBe("en");
+    expect(matchConfiguredLocale(undefined, locales, "en")).toBe("en");
+  });
+});
+
+describe("type helpers (compile-time shapes)", () => {
+  test("defineMessages preserves tree; MessagesFor aligns locales", () => {
+    const en = defineMessages({
+      errors: { notFound: "Not found" },
+      greeting: "Hello, {name}",
+    });
+    const ar = {
+      errors: { notFound: "غير موجود" },
+      greeting: "مرحباً، {name}",
+    } satisfies MessagesFor<typeof en>;
+
+    type Keys = FlattenKeys<typeof en>;
+    const key: Keys = "errors.notFound";
+    expect(en.errors.notFound).toBe("Not found");
+    expect(ar.greeting).toContain("{name}");
+    expect(key).toBe("errors.notFound");
+  });
+});

package/src/i18n/messages.ts

@@ -0,0 +1,169 @@
+/**
+ * App message catalogs for {@link Fx.t}.
+ *
+ * Locales register via {@link defineLocale}; boot wires catalogs into `fx`
+ * with the active request locale and the `i18n.default` fallback from
+ * `oke.config.ts`. Messages use ICU MessageFormat syntax.
+ *
+ * Built-in EN/AR catalogs (framework OKE codes + typed failures) are always
+ * present; app keys override built-ins for the same locale/key.
+ */
+
+import { builtinAr } from "./catalogs/ar.ts";
+import { builtinEn } from "./catalogs/en.ts";
+import { formatMessage } from "./format.ts";
+import type { MessageTree, MessageValues } from "./types.ts";
+
+export type { MessageTree, MessageValues } from "./types.ts";
+
+/** Flat key → message map after {@link flattenMessages}. */
+export type MessageCatalog = Readonly<Record<string, string>>;
+
+/** All registered locale catalogs (locale → flat map). */
+export type MessageCatalogs = Readonly<Record<string, MessageCatalog>>;
+
+/**
+ * Flatten a nested message tree into dot-separated keys.
+ *
+ * @param tree - Nested or flat messages
+ * @param prefix - Key prefix for recursion
+ */
+export function flattenMessages(tree: MessageTree, prefix = ""): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(tree)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (typeof value === "string") {
+      out[path] = value;
+    } else {
+      Object.assign(out, flattenMessages(value, path));
+    }
+  }
+  return out;
+}
+
+/** App-registered overlays (win over built-ins per key). */
+const registry = new Map<string, Record<string, string>>();
+
+/** Built-in EN/AR catalogs (framework + typed failures). */
+const builtins: Readonly<Record<string, MessageCatalog>> = {
+  en: flattenMessages(builtinEn as unknown as MessageTree),
+  ar: flattenMessages(builtinAr as unknown as MessageTree),
+};
+
+/**
+ * Identity helper that preserves a `const` message tree for typing.
+ *
+ * @param messages - Canonical catalog (usually English)
+ */
+export function defineMessages<const T extends MessageTree>(messages: T): T {
+  return messages;
+}
+
+/**
+ * Register (or replace) messages for a locale.
+ *
+ * Side-effect import from `src/locales/<locale>.ts` before boot.
+ * Prefer `as const` / {@link defineMessages} on the default locale, then
+ * `satisfies MessagesFor<typeof en>` on translations so keys stay aligned.
+ *
+ * @param locale - BCP 47 locale tag (e.g. `"en"`, `"ar"`)
+ * @param messages - Nested or flat ICU message tree
+ */
+export function defineLocale<const T extends MessageTree>(locale: string, messages: T): T {
+  const tag = locale.trim();
+  if (!tag) throw new Error("defineLocale: locale must be non-empty");
+  registry.set(tag, flattenMessages(messages));
+  return messages;
+}
+
+/**
+ * Snapshot of every catalog — built-ins merged under app overlays.
+ */
+export function getMessageCatalogs(): MessageCatalogs {
+  const locales = new Set([...Object.keys(builtins), ...registry.keys()]);
+  const out: Record<string, MessageCatalog> = {};
+  for (const locale of locales) {
+    out[locale] = { ...(builtins[locale] ?? {}), ...(registry.get(locale) ?? {}) };
+  }
+  return out;
+}
+
+/**
+ * Clear app-registered catalogs (tests only). Built-ins remain.
+ */
+export function clearMessageCatalogs(): void {
+  registry.clear();
+}
+
+/**
+ * @deprecated Use ICU `{name}` via {@link formatMessage} / `fx.t`. Kept for
+ * channel-style `{{name}}` callers during migration; not used by `fx.t`.
+ *
+ * @param template - Message template
+ * @param params - Replacement values
+ */
+export function interpolateMessage(
+  template: string,
+  params?: Readonly<Record<string, unknown>>,
+): string {
+  if (!params) return template;
+  return template.replace(/\{\{(\w+)\}\}/g, (_, name: string) => {
+    const value = params[name];
+    return value === undefined || value === null ? `{{${name}}}` : String(value);
+  });
+}
+
+/** Options for {@link translate}. */
+export interface TranslateOptions {
+  readonly locale: string;
+  readonly defaultLocale: string;
+  readonly catalogs: MessageCatalogs;
+  readonly key: string;
+  readonly values?: MessageValues;
+  /** @deprecated Prefer {@link TranslateOptions.values}. */
+  readonly params?: MessageValues;
+}
+
+/**
+ * Resolve a message key through locale → default → key fallback, then format
+ * with ICU MessageFormat.
+ *
+ * @param options - Locale, catalogs, key, values
+ */
+export function translate(options: TranslateOptions): string {
+  const { locale, defaultLocale, catalogs, key } = options;
+  const values = options.values ?? options.params;
+  const primary = catalogs[locale]?.[key];
+  if (primary !== undefined) return formatMessage(primary, locale, values);
+  if (locale !== defaultLocale) {
+    const fallback = catalogs[defaultLocale]?.[key];
+    if (fallback !== undefined) return formatMessage(fallback, defaultLocale, values);
+  }
+  if (values === undefined) return key;
+  return `${key}:${JSON.stringify(values)}`;
+}
+
+/**
+ * Pick the best catalog locale from a candidate against configured locales.
+ *
+ * Exact match, then language subtag (`ar-SA` → `ar`), then default.
+ *
+ * @param candidate - Requested locale (may be undefined)
+ * @param locales - Configured locales
+ * @param defaultLocale - Fallback locale
+ */
+export function matchConfiguredLocale(
+  candidate: string | undefined,
+  locales: readonly string[],
+  defaultLocale: string,
+): string {
+  if (!candidate?.trim()) return defaultLocale;
+  const tag = candidate.trim();
+  if (locales.includes(tag)) return tag;
+  const base = tag.toLowerCase().split("-")[0] ?? tag;
+  const byBase = locales.find(
+    (l) => l.toLowerCase() === base || l.toLowerCase().startsWith(`${base}-`),
+  );
+  if (byBase) return byBase;
+  return defaultLocale;
+}

package/src/i18n/types.ts

@@ -0,0 +1,90 @@
+/**
+ * Type-level helpers for message catalogs — keys, shapes, Register slot.
+ */
+
+/** Nested or flat message tree (leaf values are ICU message strings). */
+export type MessageTree = {
+  readonly [key: string]: string | MessageTree;
+};
+
+/**
+ * Flatten a message tree into dot-separated key unions.
+ *
+ * @typeParam T - Message tree
+ * @typeParam Prefix - Accumulated path prefix
+ */
+export type FlattenKeys<T, Prefix extends string = ""> = {
+  [K in keyof T & string]: T[K] extends string
+    ? Prefix extends ""
+      ? K
+      : `${Prefix}.${K}`
+    : T[K] extends MessageTree
+      ? FlattenKeys<T[K], Prefix extends "" ? K : `${Prefix}.${K}`>
+      : never;
+}[keyof T & string];
+
+/**
+ * Same key structure as {@link Base}; every leaf is an ICU message string.
+ * Use with `satisfies` so Arabic (etc.) cannot drift from English keys.
+ *
+ * @typeParam Base - Canonical (usually English) tree
+ */
+export type MessagesFor<Base extends MessageTree> = {
+  [K in keyof Base]: Base[K] extends string
+    ? string
+    : Base[K] extends MessageTree
+      ? MessagesFor<Base[K]>
+      : never;
+};
+
+/**
+ * Module-augmentation slot for typed `fx.t` keys.
+ *
+ * @example
+ * ```ts
+ * const en = { greeting: "Hello, {name}" } as const;
+ * defineLocale("en", en);
+ *
+ * declare module "okengine" {
+ *   interface Register {
+ *     messages: typeof en;
+ *   }
+ * }
+ * ```
+ */
+export interface Register {
+  // intentionally empty — augmented by the app
+}
+
+/** Messages from {@link Register}, when the app augments them. */
+type MessagesFromRegister = Register extends { readonly messages: infer M }
+  ? M extends MessageTree
+    ? M
+    : never
+  : never;
+
+/**
+ * Autocomplete / compile-time keys for {@link Fx.t}.
+ * Falls back to `string` until the app augments {@link Register}.
+ */
+export type AppMessageKey = [MessagesFromRegister] extends [never]
+  ? string
+  : FlattenKeys<MessagesFromRegister>;
+
+/**
+ * Values passed to ICU messages — primitives plus rich-text tag functions.
+ *
+ * Tag functions receive the formatted chunks inside `<tag>…</tag>` and return
+ * a string (or stringable) replacement.
+ */
+export type MessageValue =
+  | string
+  | number
+  | boolean
+  | Date
+  | null
+  | undefined
+  | ((chunks: readonly string[]) => string);
+
+/** Named values for one `fx.t` / {@link formatMessage} call. */
+export type MessageValues = Readonly<Record<string, MessageValue>>;

package/src/index.ts

@@ -176,6 +176,32 @@ export {
   type ContextInference,
 } from "./compiler/index.ts";
 
+export {
+  defineLocale,
+  defineMessages,
+  flattenMessages,
+  formatMessage,
+  getMessageCatalogs,
+  interpolateMessage,
+  isRtlLocale,
+  matchConfiguredLocale,
+  parseAcceptLanguage,
+  resolveFailureMessage,
+  resolveLocale,
+  runWithLocale,
+  translate,
+  type AppMessageKey,
+  type FlattenKeys,
+  type LocaleContext,
+  type MessageCatalog,
+  type MessageCatalogs,
+  type MessageTree,
+  type MessageValue,
+  type MessageValues,
+  type MessagesFor,
+  type Register,
+} from "./i18n/index.ts";
+
 export {
   createBunRuntime,
   createWebStandardRuntime,

package/src/kernel/app.ts

@@ -35,6 +35,10 @@ import {
   type GateOptions,
   type ResolvedGateConfig,
 } from "../elements/gate/config.ts";
+import type { TemplateCatalog } from "../elements/channel/runtime.ts";
+import { parseAcceptLanguage } from "../elements/channel/locale.ts";
+import { runWithLocale } from "../i18n/locale-context.ts";
+import { getMessageCatalogs, matchConfiguredLocale } from "../i18n/messages.ts";
 import { runDurable } from "../elements/clock/durable.ts";
 import { isFlow, type AnyFlowDef } from "./flow.ts";
 import { fxRetry } from "./concurrency.ts";
@@ -567,6 +571,9 @@ export function oke(options: OkeOptions): OkeApp {
       secret: authBinding.secret,
       sessions: authBinding.sessions,
       now: authBinding.now,
+      passwordPolicy: gateConfig.auth?.passwordPolicy,
+      password: gateConfig.auth?.password,
+      breachCheck: gateConfig.auth?.breachCheck,
     });
   } else {
     setActiveGateAuthContext(undefined);
@@ -663,11 +670,14 @@ export function oke(options: OkeOptions): OkeApp {
     const pluginSignals = pluginRegistry.signalContributions();
     const pluginClocks = pluginRegistry.clockContributions();
     const pluginChannelTemplates = pluginRegistry.channelTemplateContributions();
+    const pluginChannelCatalogs = pluginRegistry.channelCatalogContributions();
     if (pluginSecrets.length > 0) available.add("vault");
     if (pluginGates.length > 0) available.add("gate");
     if (pluginSignals.length > 0) available.add("signal");
     if (pluginClocks.length > 0) available.add("clock");
-    if (pluginChannelTemplates.length > 0) available.add("channel");
+    if (pluginChannelTemplates.length > 0 || pluginChannelCatalogs.length > 0) {
+      available.add("channel");
+    }
     // gate.auth (auto-absorbed auth plugin) satisfies `.needs("auth")`.
     if (gateConfig.auth) available.add("auth");
     assertPluginNeeds(caps, { pluginNames, available });
@@ -676,6 +686,7 @@ export function oke(options: OkeOptions): OkeApp {
     const baseSignals = overrides?.signals ?? options.signals ?? [];
     const baseClocks = overrides?.clocks ?? options.clocks ?? [];
     const baseChannel = overrides?.channel ?? options.channel;
+    const mergedCatalog = mergeTemplateCatalogs(baseChannel?.catalog, ...pluginChannelCatalogs);
 
     const merged: BootOptions = {
       env: bootEnv,
@@ -692,6 +703,11 @@ export function oke(options: OkeOptions): OkeApp {
       channel: {
         ...(baseChannel ?? {}),
         templates: [...(baseChannel?.templates ?? []), ...pluginChannelTemplates],
+        ...(mergedCatalog ? { catalog: mergedCatalog } : {}),
+        defaultLocale:
+          baseChannel?.defaultLocale ??
+          (overrides?.config ?? options.config)?.i18n?.default ??
+          "en",
       },
       ai: overrides?.ai ?? options.ai,
       runs: overrides?.runs ?? options.runs,
@@ -754,10 +770,52 @@ export function oke(options: OkeOptions): OkeApp {
       readonly principal?: ResolvedPrincipal;
       /** Frozen origin identity for {@link Fx.principal} across `fx.call`. */
       readonly originPrincipal?: FxPrincipal;
+      /** Explicit locale override for {@link Fx.t} / channel sends. */
+      readonly locale?: string;
     },
   ): Promise<ExecuteResult> {
     registerFlow(flowDef);
 
+    const i18nConfig = options.config?.i18n;
+    const configuredLocales = i18nConfig?.locales ?? ["en", "ar"];
+    const defaultLocale = i18nConfig?.default ?? "en";
+    const acceptLanguage = extras?.request?.headers.get("accept-language") ?? undefined;
+    const resolvedLocale = matchConfiguredLocale(
+      extras?.locale ?? parseAcceptLanguage(acceptLanguage),
+      configuredLocales,
+      defaultLocale,
+    );
+
+    return runWithLocale({ locale: resolvedLocale, defaultLocale }, () =>
+      executeInLocale({
+        flowDef,
+        input,
+        trigger,
+        extras,
+        resolvedLocale,
+        defaultLocale,
+      }),
+    );
+  }
+
+  async function executeInLocale(args: {
+    readonly flowDef: AnyFlowDef;
+    readonly input: unknown;
+    readonly trigger: Trigger;
+    readonly extras?: {
+      readonly request?: Request;
+      readonly params?: Record<string, string>;
+      readonly validated?: boolean;
+      readonly auth?: ResolvedPrincipal | FxAuth;
+      readonly operator?: FxOperator;
+      readonly principal?: ResolvedPrincipal;
+      readonly originPrincipal?: FxPrincipal;
+      readonly locale?: string;
+    };
+    readonly resolvedLocale: string;
+    readonly defaultLocale: string;
+  }): Promise<ExecuteResult> {
+    const { flowDef, input, trigger, extras, resolvedLocale, defaultLocale } = args;
     const booted = await ensureBoot();
 
     const unitBag = flowDef.unit !== undefined ? unitHooks.get(flowDef.unit) : undefined;
@@ -860,6 +918,12 @@ export function oke(options: OkeOptions): OkeApp {
       effects: flowDef.effects,
       runTelemetry: telemetry,
       now,
+      i18n: {
+        locale: resolvedLocale,
+        defaultLocale,
+        catalogs: getMessageCatalogs(),
+        ...options.fx?.i18n,
+      },
       ...(principals ? { auth: principals.auth as FxAuth, operator: principals.operator } : {}),
       ...(extras?.originPrincipal ? { principal: extras.originPrincipal } : {}),
       ...(capability ? { capability } : {}),
@@ -882,7 +946,10 @@ export function oke(options: OkeOptions): OkeApp {
           target,
           callInput,
           { kind: "internal" } satisfies InternalTrigger,
-          { originPrincipal: freezePrincipal(fx.principal) },
+          {
+            originPrincipal: freezePrincipal(fx.principal),
+            locale: resolvedLocale,
+          },
         );
         if (inner.failure) return inner.failure;
         return inner.output;
@@ -1300,5 +1367,28 @@ function archiveFromInput(
   return Object.keys(out).length > 0 ? out : undefined;
 }
 
+/**
+ * Deep-merge channel template catalogs (later parts win per locale).
+ *
+ * @param parts - Catalog fragments (undefined skipped)
+ */
+function mergeTemplateCatalogs(
+  ...parts: readonly (TemplateCatalog | undefined)[]
+): TemplateCatalog | undefined {
+  const out: Record<
+    string,
+    Record<string, { readonly subject?: string; readonly text?: string; readonly html?: string }>
+  > = {};
+  let any = false;
+  for (const part of parts) {
+    if (!part) continue;
+    any = true;
+    for (const [template, locales] of Object.entries(part)) {
+      out[template] = { ...(out[template] ?? {}), ...locales };
+    }
+  }
+  return any ? out : undefined;
+}
+
 /** @internal expose smart router type for tests */
 export type { HttpTrigger, SmartRouter };

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

@@ -0,0 +1,60 @@
+/**
+ * AI boot binder — shared driver switch + fail-loud resolution.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mockAiDriver } from "../../drivers/ai-mock.ts";
+import { ollamaAiDriver } from "../../drivers/ai-ollama.ts";
+import { aiDriverFor, aiUrlFor, bindAi, resolveAiDriverId } from "./ai.ts";
+
+describe("ai boot binder", () => {
+  test("aiDriverFor maps protocol ids; unknown / reserved throw", () => {
+    expect(aiDriverFor("mock").id).toBe("mock");
+    expect(aiDriverFor("ollama")).toBe(ollamaAiDriver);
+    expect(() => aiDriverFor("bedrock")).toThrow(/not implemented/);
+    expect(() => aiDriverFor("nope")).toThrow(/unknown AI driver/);
+  });
+
+  test("resolveAiDriverId defaults to mock; honours config + OKE_AI_DRIVER in docker", () => {
+    expect(resolveAiDriverId({}, "local")).toBe("mock");
+    expect(resolveAiDriverId({ config: { drivers: { ai: { local: "ollama" } } } }, "local")).toBe(
+      "ollama",
+    );
+
+    const prev = process.env.OKE_AI_DRIVER;
+    process.env.OKE_AI_DRIVER = "ollama";
+    try {
+      expect(resolveAiDriverId({}, "local", true)).toBe("ollama");
+    } finally {
+      if (prev === undefined) delete process.env.OKE_AI_DRIVER;
+      else process.env.OKE_AI_DRIVER = prev;
+    }
+  });
+
+  test("aiUrlFor fails loud in docker without OKE_AI_URL", () => {
+    const prevUrl = process.env.OKE_AI_URL;
+    const prevHost = process.env.OLLAMA_HOST;
+    delete process.env.OKE_AI_URL;
+    delete process.env.OLLAMA_HOST;
+    try {
+      expect(() => aiUrlFor(true)).toThrow(/OKE_AI_URL/);
+      expect(aiUrlFor(false)).toBe("http://127.0.0.1:11434");
+    } finally {
+      if (prevUrl !== undefined) process.env.OKE_AI_URL = prevUrl;
+      if (prevHost !== undefined) process.env.OLLAMA_HOST = prevHost;
+    }
+  });
+
+  test("bindAi uses injected defaultDriver over config (tests stay on mock)", () => {
+    const runtime = bindAi(
+      {
+        config: { drivers: { ai: { local: "ollama" } } },
+        ai: { defaultDriver: mockAiDriver },
+      },
+      undefined,
+      () => 0,
+      "local",
+    );
+    expect(runtime.autoCacheDisabled).toBe(true);
+  });
+});