okengine 0.6.0 → 0.7.0

package/src/elements/vault/boot-chain.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared Vault resolution-chain assembly for app boot and Console.
+ *
+ * Order (first hit wins): process.env → .env.local → compose .env.docker →
+ * backend layer (`env` seed / openbao / memory / managed).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ConfigEnv } from "../../config/index.ts";
+import {
+  envVaultDriver,
+  managedVaultDriver,
+  memoryVaultDriver,
+  openbaoVaultDriver,
+} from "../../drivers/index.ts";
+import { parseDotenv } from "../../drivers/vault-dotenv-parse.ts";
+import type { VaultDriverId } from "../../drivers/vault-types.ts";
+import { resolveComposeEnvPath } from "./chain.ts";
+import type { VaultChainLayer } from "./runtime.ts";
+
+/** Options for {@link buildVaultBootChain}. */
+export interface BuildVaultBootChainOptions {
+  /** Project root (defaults to `process.cwd()`). */
+  readonly cwd?: string;
+  /** Resolved `drivers.vault` id for the active env. */
+  readonly driverId: VaultDriverId;
+  /** Active config env — controls fail-loud vs soft fallback for openbao. */
+  readonly env?: ConfigEnv;
+  /** Seed secrets for the terminal memory / managed layer. */
+  readonly seed?: Readonly<Record<string, string>>;
+  /**
+   * When `openbao` is selected but credentials are missing:
+   * - `"throw"` — fail loud (default for `prod` / `docker`)
+   * - `"memory"` — soft-fallback to a seeded memory bag (Console / local)
+   */
+  readonly missingOpenbao?: "throw" | "memory";
+}
+
+/**
+ * Normalize a config label to a {@link VaultDriverId}.
+ *
+ * Accepts legacy `"dotenv"` as an alias for `"env"`.
+ *
+ * @param raw - Config string
+ */
+export function normalizeVaultDriverId(raw: string): VaultDriverId {
+  if (raw === "dotenv") return "env";
+  if (raw === "env" || raw === "openbao" || raw === "memory" || raw === "managed") {
+    return raw;
+  }
+  throw new Error(
+    `oke boot: unknown vault driver "${raw}" (expected env · openbao · memory · managed)`,
+  );
+}
+
+/**
+ * Build the standard Vault resolution chain for app boot / Console.
+ *
+ * @param options - Driver id + cwd + seed
+ */
+export function buildVaultBootChain(options: BuildVaultBootChainOptions): VaultChainLayer[] {
+  const cwd = options.cwd ?? process.cwd();
+  const seed = options.seed ?? {};
+  const composeEnv = resolveComposeEnvPath(cwd);
+
+  let composeText = "";
+  if (existsSync(composeEnv.path)) {
+    composeText = readFileSync(composeEnv.path, "utf8").toString();
+  }
+  const envMap = parseDotenv(composeText);
+  const openbaoUrl = process.env.OKE_VAULT_URL ?? envMap.get("OKE_VAULT_URL");
+  const openbaoToken = process.env.OKE_VAULT_TOKEN ?? envMap.get("OKE_VAULT_TOKEN");
+  const openbaoMount = process.env.OKE_VAULT_MOUNT ?? envMap.get("OKE_VAULT_MOUNT") ?? "secret";
+
+  const envLayers: VaultChainLayer[] = [
+    { driver: envVaultDriver, source: "process.env" },
+    {
+      driver: envVaultDriver,
+      source: ".env.local",
+      options: { path: resolve(cwd, ".env.local") },
+    },
+    {
+      driver: envVaultDriver,
+      source: composeEnv.source,
+      options: { path: composeEnv.path },
+    },
+  ];
+
+  switch (options.driverId) {
+    case "memory":
+      return [
+        {
+          driver: memoryVaultDriver,
+          source: "driver",
+          options: { secrets: seed },
+        },
+      ];
+    case "managed":
+      return [
+        {
+          driver: managedVaultDriver,
+          source: "driver",
+          options: { secrets: seed },
+        },
+      ];
+    case "env":
+      return [
+        ...envLayers,
+        {
+          driver: memoryVaultDriver,
+          source: "driver",
+          options: { secrets: seed },
+        },
+      ];
+    case "openbao": {
+      if (openbaoUrl && openbaoToken) {
+        return [
+          ...envLayers,
+          {
+            driver: openbaoVaultDriver,
+            source: "driver",
+            options: { url: openbaoUrl, token: openbaoToken, mount: openbaoMount },
+          },
+        ];
+      }
+      const env = options.env ?? "local";
+      const missing =
+        options.missingOpenbao ?? (env === "prod" || env === "docker" ? "throw" : "memory");
+      if (missing === "throw") {
+        throw new Error(
+          'oke boot: vault driver "openbao" needs OKE_VAULT_URL and OKE_VAULT_TOKEN ' +
+            "(did `oke dev -d` bootstrap OpenBao / write docker/.env.docker?)",
+        );
+      }
+      return [
+        ...envLayers,
+        {
+          driver: memoryVaultDriver,
+          source: "driver",
+          options: { secrets: seed },
+        },
+      ];
+    }
+    default: {
+      const _exhaustive: never = options.driverId;
+      throw new Error(`oke boot: unhandled vault driver ${String(_exhaustive)}`);
+    }
+  }
+}

package/src/elements/vault/runtime.ts

@@ -87,6 +87,11 @@ export interface CreateVaultRuntimeOptions {
 export interface VaultRuntime {
   /** Declared contracts by name. */
   readonly contracts: ReadonlyMap<string, VaultSecretDecl>;
+  /**
+   * Driver ids of each chain layer in order (`env` · `openbao` · `memory` · `managed`).
+   * Available before {@link boot}.
+   */
+  readonly chainDriverIds: readonly string[];
   /**
    * Open every chain layer, merge (first wins), validate all contracts,
    * register redaction. Throws {@link VaultBootError} listing every gap.
@@ -245,8 +250,11 @@ export function createVaultRuntime(options: CreateVaultRuntimeOptions = {}): Vau
     booted = true;
   }
 
+  const chainDriverIds = (options.chain ?? []).map((layer) => layer.driver.id);
+
   return {
     contracts,
+    chainDriverIds,
     get booted() {
       return booted;
     },

package/src/kernel/app.ts

@@ -55,6 +55,7 @@ import {
 } from "./fx.ts";
 import {
   currentDevSurface,
+  failureDetailFromResponse,
   logDevRequest,
   shouldLogDevRequests,
 } from "../runtime/dev-request-log.ts";
@@ -1180,7 +1181,7 @@ export function oke(options: OkeOptions): OkeApp {
       const url = new URL(request.url);
       const method = request.method.toUpperCase();
 
-      const respond = (response: Response): Response => {
+      const respond = async (response: Response): Promise<Response> => {
         if (shouldLogDevRequests()) {
           logDevRequest({
             surface: currentDevSurface(),
@@ -1189,6 +1190,7 @@ export function oke(options: OkeOptions): OkeApp {
             flow: flowLabel,
             status: response.status,
             ms: Math.round(performance.now() - started),
+            detail: await failureDetailFromResponse(response),
           });
         }
         return response;

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

@@ -1,15 +1,34 @@
 /**
- * Channel binder — profile selection + SMTP env parsing.
+ * Channel binder — profile selection + env parsing.
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
-import { resolveEmailDriverId, smtpOptionsFromEnv } from "./channel.ts";
+import {
+  msegatOptionsFromEnv,
+  resendOptionsFromEnv,
+  resolveEmailDriverId,
+  resolveSmsDriverId,
+  smtpOptionsFromEnv,
+  sndrOptionsFromEnv,
+  taqnyatOptionsFromEnv,
+  unifonicOptionsFromEnv,
+} 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,
+  resend: process.env.RESEND_API_KEY,
+  sndr: process.env.SNDR_API_KEY,
+  sndrBase: process.env.SNDR_BASE_URL,
+  taqBearer: process.env.TAQNYAT_BEARER_TOKEN,
+  taqSender: process.env.TAQNYAT_SENDER,
+  msegatUser: process.env.MSEGAT_USERNAME,
+  msegatKey: process.env.MSEGAT_API_KEY,
+  msegatSender: process.env.MSEGAT_SENDER,
+  unifonicSid: process.env.UNIFONIC_APPSID,
+  unifonicSender: process.env.UNIFONIC_SENDER,
 };
 
 afterEach(() => {
@@ -17,6 +36,16 @@ afterEach(() => {
   restoreEnv("SMTP_USER", previous.user);
   restoreEnv("SMTP_PASSWORD", previous.password);
   restoreEnv("OKE_CHANNEL_EMAIL_URL", previous.okeUrl);
+  restoreEnv("RESEND_API_KEY", previous.resend);
+  restoreEnv("SNDR_API_KEY", previous.sndr);
+  restoreEnv("SNDR_BASE_URL", previous.sndrBase);
+  restoreEnv("TAQNYAT_BEARER_TOKEN", previous.taqBearer);
+  restoreEnv("TAQNYAT_SENDER", previous.taqSender);
+  restoreEnv("MSEGAT_USERNAME", previous.msegatUser);
+  restoreEnv("MSEGAT_API_KEY", previous.msegatKey);
+  restoreEnv("MSEGAT_SENDER", previous.msegatSender);
+  restoreEnv("UNIFONIC_APPSID", previous.unifonicSid);
+  restoreEnv("UNIFONIC_SENDER", previous.unifonicSender);
 });
 
 describe("bindChannel driver resolution", () => {
@@ -24,7 +53,8 @@ describe("bindChannel driver resolution", () => {
     config: {
       drivers: {
         channel: {
-          email: { local: "console", docker: "smtp", test: "console", prod: "smtp" },
+          email: { local: "console", docker: "smtp", test: "console", prod: "sndr" },
+          sms: { local: "console", docker: "taqnyat", test: "msegat", prod: "taqnyat" },
         },
       },
     },
@@ -33,6 +63,13 @@ describe("bindChannel driver resolution", () => {
   test("uses console locally and smtp in docker", () => {
     expect(resolveEmailDriverId(options, "local", false)).toBe("console");
     expect(resolveEmailDriverId(options, "docker", true)).toBe("smtp");
+    expect(resolveEmailDriverId(options, "prod", false)).toBe("sndr");
+  });
+
+  test("resolves sms driver ids", () => {
+    expect(resolveSmsDriverId(options, "local")).toBe("console");
+    expect(resolveSmsDriverId(options, "docker")).toBe("taqnyat");
+    expect(resolveSmsDriverId(options, "test")).toBe("msegat");
   });
 
   test("parses SMTP_URL and optional auth overrides", () => {
@@ -52,6 +89,34 @@ describe("bindChannel driver resolution", () => {
     delete process.env.OKE_CHANNEL_EMAIL_URL;
     expect(() => smtpOptionsFromEnv(true)).toThrow("docker/.env.docker");
   });
+
+  test("resend and sndr env helpers", () => {
+    process.env.RESEND_API_KEY = "re_x";
+    expect(resendOptionsFromEnv()).toEqual({ apiKey: "re_x" });
+    process.env.SNDR_API_KEY = "sndr_test_x";
+    process.env.SNDR_BASE_URL = "https://api.example.test";
+    expect(sndrOptionsFromEnv()).toEqual({
+      apiKey: "sndr_test_x",
+      url: "https://api.example.test",
+    });
+  });
+
+  test("taqnyat, msegat, and unifonic env helpers", () => {
+    process.env.TAQNYAT_BEARER_TOKEN = "bearer";
+    process.env.TAQNYAT_SENDER = "Brand";
+    expect(taqnyatOptionsFromEnv()).toEqual({ bearerToken: "bearer", sender: "Brand" });
+    process.env.MSEGAT_USERNAME = "user";
+    process.env.MSEGAT_API_KEY = "key";
+    process.env.MSEGAT_SENDER = "Brand";
+    expect(msegatOptionsFromEnv()).toEqual({
+      userName: "user",
+      apiKey: "key",
+      sender: "Brand",
+    });
+    process.env.UNIFONIC_APPSID = "sid";
+    process.env.UNIFONIC_SENDER = "Brand";
+    expect(unifonicOptionsFromEnv()).toEqual({ appSid: "sid", sender: "Brand" });
+  });
 });
 
 function restoreEnv(key: string, value: string | undefined): void {

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

@@ -4,7 +4,12 @@
 
 import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import { openConsoleChannel } from "../../drivers/channel-console.ts";
+import { openMsegatChannel } from "../../drivers/channel-msegat.ts";
+import { openResendChannel } from "../../drivers/channel-resend.ts";
 import { openSmtpChannel } from "../../drivers/channel-smtp.ts";
+import { openSndrChannel } from "../../drivers/channel-sndr.ts";
+import { openTaqnyatChannel } from "../../drivers/channel-taqnyat.ts";
+import { openUnifonicChannel } from "../../drivers/channel-unifonic.ts";
 import type { ChannelDriver, ChannelOpenOptions } from "../../drivers/channel-types.ts";
 import { createChannelRuntime, type ChannelRuntime } from "../../elements/channel.ts";
 import type { BootOptions } from "../boot.ts";
@@ -12,6 +17,9 @@ import type { BootOptions } from "../boot.ts";
 /**
  * Construct a Channel runtime (console inbox default).
  *
+ * When `options.channel.drivers` is omitted, opens the configured email driver
+ * and, if `drivers.channel.sms` resolves, appends that SMS driver to the chain.
+ *
  * @param options - Boot options
  * @param env - Active environment
  * @param now - Clock
@@ -25,18 +33,36 @@ export function bindChannel(
 ): ChannelRuntime {
   return createChannelRuntime({
     ...(options.channel ?? {}),
-    drivers: options.channel?.drivers ?? [channelDriverFor(options, env, docker)],
+    drivers: options.channel?.drivers ?? defaultDrivers(options, env, docker),
     now,
   });
 }
 
-function channelDriverFor(options: BootOptions, env: ConfigEnv, docker: boolean): ChannelDriver {
+function defaultDrivers(options: BootOptions, env: ConfigEnv, docker: boolean): ChannelDriver[] {
+  const drivers: ChannelDriver[] = [emailDriverFor(options, env, docker)];
+  const sms = smsDriverFor(options, env);
+  if (sms) drivers.push(sms);
+  return drivers;
+}
+
+function emailDriverFor(options: BootOptions, env: ConfigEnv, docker: boolean): ChannelDriver {
   const id = resolveEmailDriverId(options, env, docker);
   if (id === "console") return openConsoleChannel();
   if (id === "smtp") return openSmtpChannel(smtpOptionsFromEnv(docker));
+  if (id === "resend") return openResendChannel(resendOptionsFromEnv());
+  if (id === "sndr") return openSndrChannel(sndrOptionsFromEnv());
   throw new Error(`oke boot: unknown email channel driver "${id}"`);
 }
 
+function smsDriverFor(options: BootOptions, env: ConfigEnv): ChannelDriver | undefined {
+  const id = resolveSmsDriverId(options, env);
+  if (!id || id === "console") return undefined;
+  if (id === "taqnyat") return openTaqnyatChannel(taqnyatOptionsFromEnv());
+  if (id === "msegat") return openMsegatChannel(msegatOptionsFromEnv());
+  if (id === "unifonic") return openUnifonicChannel(unifonicOptionsFromEnv());
+  throw new Error(`oke boot: unknown sms channel driver "${id}"`);
+}
+
 /**
  * Resolve the configured email driver for one environment.
  *
@@ -54,6 +80,16 @@ export function resolveEmailDriverId(
   );
 }
 
+/**
+ * Resolve the configured SMS driver for one environment.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+export function resolveSmsDriverId(options: BootOptions, env: ConfigEnv): string | undefined {
+  return resolveDriverId(options.config?.drivers?.channel?.sms, env);
+}
+
 /**
  * Resolve SMTP connection options from `SMTP_URL` plus optional auth overrides.
  *
@@ -81,3 +117,58 @@ export function smtpOptionsFromEnv(docker = false): ChannelOpenOptions {
     ...(pass ? { pass } : {}),
   };
 }
+
+/**
+ * Resolve Resend options from env.
+ */
+export function resendOptionsFromEnv(): ChannelOpenOptions {
+  const apiKey = process.env.RESEND_API_KEY?.trim();
+  if (!apiKey) throw new Error("oke boot: resend channel needs RESEND_API_KEY");
+  return { apiKey };
+}
+
+/**
+ * Resolve SNDR options from env.
+ */
+export function sndrOptionsFromEnv(): ChannelOpenOptions {
+  const apiKey = process.env.SNDR_API_KEY?.trim();
+  if (!apiKey) throw new Error("oke boot: sndr channel needs SNDR_API_KEY");
+  const url = process.env.SNDR_BASE_URL?.trim();
+  return { apiKey, ...(url ? { url } : {}) };
+}
+
+/**
+ * Resolve Taqnyat SMS options from env.
+ */
+export function taqnyatOptionsFromEnv(): ChannelOpenOptions {
+  const bearerToken = process.env.TAQNYAT_BEARER_TOKEN?.trim() ?? process.env.TAQNYAT_TOKEN?.trim();
+  const sender = process.env.TAQNYAT_SENDER?.trim();
+  if (!bearerToken) {
+    throw new Error("oke boot: taqnyat channel needs TAQNYAT_BEARER_TOKEN");
+  }
+  if (!sender) throw new Error("oke boot: taqnyat channel needs TAQNYAT_SENDER");
+  return { bearerToken, sender };
+}
+
+/**
+ * Resolve Msegat SMS options from env.
+ */
+export function msegatOptionsFromEnv(): ChannelOpenOptions {
+  const userName = process.env.MSEGAT_USERNAME?.trim();
+  const apiKey = process.env.MSEGAT_API_KEY?.trim();
+  const sender = process.env.MSEGAT_SENDER?.trim();
+  if (!userName) throw new Error("oke boot: msegat channel needs MSEGAT_USERNAME");
+  if (!apiKey) throw new Error("oke boot: msegat channel needs MSEGAT_API_KEY");
+  if (!sender) throw new Error("oke boot: msegat channel needs MSEGAT_SENDER");
+  return { userName, apiKey, sender };
+}
+
+/**
+ * Resolve Unifonic SMS options from env.
+ */
+export function unifonicOptionsFromEnv(): ChannelOpenOptions {
+  const appSid = process.env.UNIFONIC_APPSID?.trim() ?? process.env.UNIFONIC_APP_SID?.trim();
+  const sender = process.env.UNIFONIC_SENDER?.trim();
+  if (!appSid) throw new Error("oke boot: unifonic channel needs UNIFONIC_APPSID");
+  return { appSid, ...(sender ? { sender } : {}) };
+}

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

@@ -2,9 +2,13 @@
  * Lazy clock binder — loaded only when Clock is declared.
  */
 
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import {
   clock as declareClock,
   createClockRuntime,
+  createFileCronStore,
+  createMemoryCronStore,
   createTestClockRuntime,
   type ClockDecl,
   type ClockRuntime,
@@ -18,9 +22,27 @@ export interface BindClockResult {
   readonly clockDecls: ReadonlyMap<string, ClockDecl>;
 }
 
+/** Default on-disk cron store path (multi-process leader election). */
+export const DEFAULT_FILE_CRON_PATH = ".oke/crons.json";
+
+/**
+ * Resolve `drivers.clock` for the active env.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+export function resolveClockDriverId(options: BootOptions, env: ConfigEnv): string {
+  const resolved = resolveDriverId(options.config?.drivers?.clock, env);
+  if (resolved) return resolved;
+  return env === "test" ? "frozen" : "memory";
+}
+
 /**
  * Construct / adopt a Clock runtime, register decls, reconcile.
  *
+ * Supported ids: `frozen` · `memory` · `file`. `postgres` (and any other id)
+ * fail loud — there is no postgres CronStore.
+ *
  * @param options - Boot options
  * @param env - Active environment
  * @param now - Clock
@@ -32,13 +54,36 @@ export async function bindClock(
   now: () => number,
   prebuilt?: ClockRuntime,
 ): Promise<BindClockResult> {
-  const clockDriver =
-    resolveDriverId(options.config?.drivers?.clock, env) ?? (env === "test" ? "frozen" : "memory");
-  const clock =
-    prebuilt ??
-    (clockDriver === "frozen" || env === "test"
-      ? createTestClockRuntime(now(), { instanceId: options.instanceId })
-      : createClockRuntime({ instanceId: options.instanceId, now }));
+  const clockDriver = resolveClockDriverId(options, env);
+
+  let clock: ClockRuntime;
+  if (prebuilt) {
+    clock = prebuilt;
+  } else if (clockDriver === "frozen" || env === "test") {
+    clock = createTestClockRuntime(now(), { instanceId: options.instanceId });
+  } else if (clockDriver === "memory") {
+    clock = createClockRuntime({
+      instanceId: options.instanceId,
+      now,
+      store: createMemoryCronStore(),
+    });
+  } else if (clockDriver === "file") {
+    const path = resolve(process.cwd(), DEFAULT_FILE_CRON_PATH);
+    mkdirSync(dirname(path), { recursive: true });
+    clock = createClockRuntime({
+      instanceId: options.instanceId,
+      now,
+      store: createFileCronStore(path),
+    });
+  } else if (clockDriver === "postgres") {
+    throw new Error(
+      'oke boot: clock driver "postgres" is not implemented — use "memory", "file", or "frozen"',
+    );
+  } else {
+    throw new Error(
+      `oke boot: unknown clock driver "${clockDriver}" (expected memory · file · frozen)`,
+    );
+  }
 
   const clockDecls = new Map<string, ClockDecl>();
   for (const c of options.clocks ?? []) {

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

@@ -2,18 +2,86 @@
  * Lazy gate binder — loaded only when Gate is declared (or required by AI).
  */
 
+import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import { memoryDrivers } from "../../drivers/memory.ts";
+import { redisDriver } from "../../drivers/redis.ts";
+import type { KvClientLike } from "../../drivers/types.ts";
 import { createGateRuntime, type GateRuntime } from "../../elements/gate.ts";
 import type { BootOptions } from "../boot.ts";
 
+/** Namespace for gate rate-limit counters (never shares an app kv declaration). */
+export const GATE_KV_NAMESPACE = "oke:gates";
+
 /**
- * Construct a Gate runtime backed by a memory kv namespace.
+ * Resolve the KV backend for Gate rates — same facet as `drivers.store.kv`.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ * @param docker - Docker mode
+ */
+export function resolveGateKvDriverId(
+  options: BootOptions,
+  env: ConfigEnv,
+  docker = false,
+): "memory" | "redis" {
+  const fromEnv = process.env.OKE_KV_DRIVER?.trim();
+  if (docker && fromEnv === "redis") return "redis";
+  if (docker && fromEnv === "memory") return "memory";
+  const resolved = resolveDriverId(options.config?.drivers?.store?.kv, env);
+  if (resolved === "redis") return "redis";
+  if (resolved === "memory") return "memory";
+  return docker ? "redis" : "memory";
+}
+
+function kvUrlFor(docker: boolean): string | undefined {
+  const url = process.env.REDIS_URL ?? process.env.OKE_STORE_KV_URL ?? undefined;
+  if (!url) {
+    if (docker) {
+      throw new Error(
+        "oke boot: gate redis kv needs REDIS_URL (did `oke dev -d` write docker/.env.docker?)",
+      );
+    }
+    return undefined;
+  }
+  return url;
+}
+
+/**
+ * Construct a Gate runtime backed by `drivers.store.kv` (namespace {@link GATE_KV_NAMESPACE}).
  *
  * @param options - Boot options
  * @param now - Clock
+ * @param env - Active environment
+ * @param docker - Docker mode
  */
-export async function bindGate(options: BootOptions, now: () => number): Promise<GateRuntime> {
-  const kvNs = await memoryDrivers.kv.open({ name: "oke:gates" });
+export async function bindGate(
+  options: BootOptions,
+  now: () => number,
+  env: ConfigEnv = "local",
+  docker = false,
+): Promise<GateRuntime> {
+  const kvId = resolveGateKvDriverId(options, env, docker);
+  const injected = options.clients?.kv as KvClientLike | undefined;
+
+  let kvNs;
+  if (kvId === "redis") {
+    const url = injected ? undefined : kvUrlFor(docker);
+    if (!injected && url === undefined) {
+      // Local without REDIS_URL — soft-fallback to memory (same as missing redis for store would fail;
+      // gate rates should not brick local apps that only declared policy gates).
+      kvNs = await memoryDrivers.kv.open({ name: GATE_KV_NAMESPACE, nowMs: now });
+    } else {
+      kvNs = await redisDriver.open({
+        name: GATE_KV_NAMESPACE,
+        ...(url !== undefined ? { url } : {}),
+        ...(injected !== undefined ? { client: injected } : {}),
+        nowMs: now,
+      });
+    }
+  } else {
+    kvNs = await memoryDrivers.kv.open({ name: GATE_KV_NAMESPACE, nowMs: now });
+  }
+
   return createGateRuntime({
     gates: options.gates ?? [],
     kv: kvNs,