okengine 0.6.1 → 0.8.0

package/src/kernel/boot-bind/honor-config.test.ts

@@ -0,0 +1,348 @@
+/**
+ * Boot-level acceptance: binders honour `drivers.*` config pins.
+ *
+ * Asserts runtime identity (driverId / store kind / chain), not hero strings.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRedisFakeClient } from "../../drivers/redis.ts";
+import { createSignalRedisFake } from "../../drivers/signal-redis.ts";
+import { clock } from "../../elements/clock.ts";
+import { gate } from "../../elements/gate.ts";
+import { signal } from "../../elements/signal.ts";
+import { vault } from "../../elements/vault.ts";
+import { buildVaultBootChain } from "../../elements/vault/boot-chain.ts";
+import { flow } from "../flow.ts";
+import { bootApplication } from "../boot.ts";
+
+describe("boot binders honour drivers.* config", () => {
+  const prevCwd = process.cwd();
+  let tmp: string | undefined;
+
+  afterEach(async () => {
+    process.chdir(prevCwd);
+    if (tmp) {
+      await rm(tmp, { recursive: true, force: true });
+      tmp = undefined;
+    }
+    delete process.env.OKE_VAULT_URL;
+    delete process.env.OKE_VAULT_TOKEN;
+    delete process.env.REDIS_URL;
+  });
+
+  test("vault: drivers.vault env builds env chain layers", async () => {
+    process.env.APP_NAME = "honor-config";
+    try {
+      const result = await bootApplication({
+        env: "local",
+        secrets: [vault.config("APP_NAME", { description: "app" })],
+        config: {
+          drivers: {
+            vault: { local: "env", docker: "openbao", test: "memory", prod: "openbao" },
+          },
+        },
+      });
+      try {
+        expect(result.vault).toBeDefined();
+        expect(result.vault!.chainDriverIds).toContain("env");
+        expect(result.vault!.chainDriverIds).toContain("memory");
+        expect(result.vault!.chainDriverIds[0]).toBe("env");
+      } finally {
+        await result.close();
+      }
+    } finally {
+      delete process.env.APP_NAME;
+    }
+  });
+
+  test("vault: drivers.vault openbao with credentials selects openbao layer", () => {
+    process.env.OKE_VAULT_URL = "http://127.0.0.1:8200";
+    process.env.OKE_VAULT_TOKEN = "test-token";
+    const chain = buildVaultBootChain({
+      driverId: "openbao",
+      env: "local",
+      missingOpenbao: "throw",
+    });
+    expect(chain.map((l) => l.driver.id)).toContain("openbao");
+    expect(chain.map((l) => l.driver.id)).toContain("env");
+  });
+
+  test("vault: openbao without credentials fails loud in prod", async () => {
+    delete process.env.OKE_VAULT_URL;
+    delete process.env.OKE_VAULT_TOKEN;
+    await expect(
+      bootApplication({
+        env: "prod",
+        secrets: [vault.config("APP_NAME", { description: "app", dev: "x" })],
+        vault: { allowDevFallbacks: true },
+        config: {
+          drivers: {
+            vault: { prod: "openbao" },
+          },
+        },
+      }),
+    ).rejects.toThrow(/openbao.*OKE_VAULT_URL/);
+  });
+
+  test("clock: drivers.clock memory binds memory CronStore", async () => {
+    const result = await bootApplication({
+      env: "local",
+      startScheduler: false,
+      clocks: [clock("tick", { every: "1h" })],
+      config: {
+        drivers: {
+          clock: { local: "memory", docker: "file", test: "frozen", prod: "file" },
+        },
+      },
+    });
+    try {
+      expect(result.clock!.driverId).toBe("memory");
+      expect(result.clock!.store.kind).toBe("memory");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("clock: drivers.clock file binds file CronStore", async () => {
+    tmp = await mkdtemp(join(tmpdir(), "oke-clock-file-"));
+    process.chdir(tmp);
+    const result = await bootApplication({
+      env: "local",
+      startScheduler: false,
+      clocks: [clock("tick", { every: "1h" })],
+      config: {
+        drivers: {
+          clock: { local: "file", docker: "file", test: "frozen", prod: "file" },
+        },
+      },
+    });
+    try {
+      expect(result.clock!.driverId).toBe("file");
+      expect(result.clock!.store.kind).toBe("file");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("clock: drivers.clock postgres fails without DATABASE_URL", async () => {
+    const prevDb = process.env.DATABASE_URL;
+    const prevStore = process.env.OKE_STORE_SQL_URL;
+    delete process.env.DATABASE_URL;
+    delete process.env.OKE_STORE_SQL_URL;
+    try {
+      await expect(
+        bootApplication({
+          env: "local",
+          startScheduler: false,
+          clocks: [clock("tick", { every: "1h" })],
+          config: {
+            drivers: {
+              clock: { local: "postgres" },
+            },
+          },
+        }),
+      ).rejects.toThrow(/clock driver "postgres" needs DATABASE_URL/);
+    } finally {
+      if (prevDb !== undefined) process.env.DATABASE_URL = prevDb;
+      else delete process.env.DATABASE_URL;
+      if (prevStore !== undefined) process.env.OKE_STORE_SQL_URL = prevStore;
+      else delete process.env.OKE_STORE_SQL_URL;
+    }
+  });
+
+  test("journal: durable flow binds memory journal by default", async () => {
+    const result = await bootApplication({
+      env: "local",
+      startScheduler: false,
+      flows: [flow({ name: "charge", durable: true, do: () => ({ ok: true }) })],
+    });
+    try {
+      expect(result.journal?.driverId).toBe("memory");
+      expect(typeof result.journal?.instanceId).toBe("string");
+      expect(result.journal?.leaseMs).toBeGreaterThan(0);
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("journal: no durable flow → no journal runtime", async () => {
+    const result = await bootApplication({
+      env: "local",
+      startScheduler: false,
+      flows: [flow({ name: "plain", do: () => ({ ok: true }) })],
+    });
+    try {
+      expect(result.journal).toBeUndefined();
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("journal: drivers.journal file binds file store", async () => {
+    tmp = await mkdtemp(join(tmpdir(), "oke-journal-file-"));
+    process.chdir(tmp);
+    const result = await bootApplication({
+      env: "local",
+      startScheduler: false,
+      flows: [flow({ name: "charge", durable: true, do: () => ({ ok: true }) })],
+      config: {
+        drivers: {
+          journal: { local: "file", docker: "postgres", test: "memory", prod: "postgres" },
+        },
+      },
+    });
+    try {
+      expect(result.journal?.driverId).toBe("file");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("journal: drivers.journal postgres fails without DATABASE_URL", async () => {
+    const prevDb = process.env.DATABASE_URL;
+    const prevStore = process.env.OKE_STORE_SQL_URL;
+    delete process.env.DATABASE_URL;
+    delete process.env.OKE_STORE_SQL_URL;
+    try {
+      await expect(
+        bootApplication({
+          env: "local",
+          startScheduler: false,
+          flows: [flow({ name: "charge", durable: true, do: () => ({ ok: true }) })],
+          config: {
+            drivers: {
+              journal: { local: "postgres" },
+            },
+          },
+        }),
+      ).rejects.toThrow(/journal driver "postgres" needs DATABASE_URL/);
+    } finally {
+      if (prevDb !== undefined) process.env.DATABASE_URL = prevDb;
+      else delete process.env.DATABASE_URL;
+      if (prevStore !== undefined) process.env.OKE_STORE_SQL_URL = prevStore;
+      else delete process.env.OKE_STORE_SQL_URL;
+    }
+  });
+
+  test("journal: unknown driver fails loud", async () => {
+    await expect(
+      bootApplication({
+        env: "local",
+        startScheduler: false,
+        flows: [flow({ name: "charge", durable: true, do: () => ({ ok: true }) })],
+        config: {
+          drivers: {
+            journal: { local: "neon" },
+          },
+        },
+      }),
+    ).rejects.toThrow(/unknown journal driver "neon"/);
+  });
+
+  test("gate: drivers.store.kv redis opens redis-backed oke:gates", async () => {
+    const fake = createRedisFakeClient();
+    const result = await bootApplication({
+      env: "local",
+      gates: [gate.rate({ max: 10, per: "1m" })],
+      clients: { kv: fake },
+      config: {
+        drivers: {
+          store: {
+            kv: { local: "redis", docker: "redis", prod: "redis" },
+          },
+        },
+      },
+    });
+    try {
+      expect(result.gate!.kvDriverId).toBe("redis");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("gate: drivers.store.kv memory keeps memory oke:gates", async () => {
+    const result = await bootApplication({
+      env: "local",
+      gates: [gate.rate({ max: 10, per: "1m" })],
+      config: {
+        drivers: {
+          store: {
+            kv: { local: "memory", docker: "redis", prod: "redis" },
+          },
+        },
+      },
+    });
+    try {
+      expect(result.gate!.kvDriverId).toBe("memory");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("signal: drivers.signal memory binds memory", async () => {
+    const result = await bootApplication({
+      env: "local",
+      signals: [signal("ping", { delivery: "once" })],
+      config: {
+        drivers: {
+          signal: { local: "memory", docker: "redis", prod: "redis" },
+        },
+      },
+    });
+    try {
+      expect(result.signal!.driverId).toBe("memory");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("signal: drivers.signal redis binds redis", async () => {
+    const fake = createSignalRedisFake();
+    const result = await bootApplication({
+      env: "local",
+      signals: [signal("ping", { delivery: "once" })],
+      clients: { signalRedis: fake },
+      config: {
+        drivers: {
+          signal: { local: "redis", docker: "redis", prod: "redis" },
+        },
+      },
+    });
+    try {
+      expect(result.signal!.driverId).toBe("redis");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("signal: drivers.signal postgres fails loud (never silent memory)", async () => {
+    await expect(
+      bootApplication({
+        env: "local",
+        signals: [signal("ping", { delivery: "once" })],
+        config: {
+          drivers: {
+            signal: { local: "postgres" },
+          },
+        },
+      }),
+    ).rejects.toThrow(/signal driver "postgres"/);
+  });
+
+  test("signal: drivers.signal nats fails loud", async () => {
+    await expect(
+      bootApplication({
+        env: "local",
+        signals: [signal("ping", { delivery: "once" })],
+        config: {
+          drivers: {
+            signal: { local: "nats" },
+          },
+        },
+      }),
+    ).rejects.toThrow(/signal driver "nats"/);
+  });
+});

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

@@ -0,0 +1,89 @@
+/**
+ * Lazy journal binder — loaded only when a flow declares `durable: true`.
+ */
+
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import {
+  createFileJournalStore,
+  createMemoryJournalStore,
+  JOURNAL_DEFAULT_LEASE_MS,
+  type JournalStore,
+} from "../journal.ts";
+import { createPostgresJournalStore } from "../../drivers/journal-postgres.ts";
+import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
+import type { BootOptions } from "../boot.ts";
+
+/** Bound journal runtime — store + this instance's lease identity. */
+export interface JournalRuntime {
+  readonly store: JournalStore;
+  readonly instanceId: string;
+  readonly leaseMs: number;
+  readonly driverId: string;
+}
+
+/** Result of binding a journal runtime. */
+export interface BindJournalResult {
+  readonly journal: JournalRuntime;
+}
+
+/** Default on-disk journal path (single-host file driver). */
+export const DEFAULT_FILE_JOURNAL_PATH = ".oke/journal.json";
+
+/**
+ * Resolve `drivers.journal` for the active env (default `memory`).
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+export function resolveJournalDriverId(options: BootOptions, env: ConfigEnv): string {
+  const resolved = resolveDriverId(options.config?.drivers?.journal, env);
+  if (resolved) return resolved;
+  return "memory";
+}
+
+/**
+ * Construct a journal store. Supported ids: `memory` · `file` · `postgres`.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+export async function bindJournal(
+  options: BootOptions,
+  env: ConfigEnv,
+): Promise<BindJournalResult> {
+  const driver = resolveJournalDriverId(options, env);
+  const instanceId = options.instanceId ?? `inst-${crypto.randomUUID()}`;
+
+  let store: JournalStore;
+  if (driver === "memory") {
+    store = createMemoryJournalStore();
+  } else if (driver === "file") {
+    const path = resolve(process.cwd(), DEFAULT_FILE_JOURNAL_PATH);
+    mkdirSync(dirname(path), { recursive: true });
+    store = createFileJournalStore(path);
+  } else if (driver === "postgres") {
+    const url = process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL ?? undefined;
+    if (!url) {
+      throw new Error(
+        env === "docker"
+          ? 'oke boot: journal driver "postgres" needs DATABASE_URL (did `oke dev -d` write docker/.env.docker?)'
+          : 'oke boot: journal driver "postgres" needs DATABASE_URL',
+      );
+    }
+    store = await createPostgresJournalStore({ url });
+  } else {
+    throw new Error(
+      `oke boot: unknown journal driver "${driver}" (expected memory · file · postgres)`,
+    );
+  }
+
+  return {
+    journal: {
+      store,
+      instanceId,
+      leaseMs: options.journalLeaseMs ?? JOURNAL_DEFAULT_LEASE_MS,
+      driverId: driver,
+    },
+  };
+}

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

@@ -2,29 +2,86 @@
  * Lazy signal binder — loaded only when Signal is declared.
  */
 
+import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import { memorySignalDriver } from "../../drivers/signal-memory.ts";
+import { createBunSignalRedisClient, redisSignalDriver } from "../../drivers/signal-redis.ts";
+import type { SignalRedisClientLike } from "../../drivers/signal-types.ts";
 import { createSignalRuntime, type SignalRuntime } from "../../elements/signal.ts";
-import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import type { BootOptions } from "../boot.ts";
 
+/**
+ * Resolve `drivers.signal` for the active env (default `memory`).
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+export function resolveSignalDriverId(options: BootOptions, env: ConfigEnv): string {
+  return resolveDriverId(options.config?.drivers?.signal, env) ?? "memory";
+}
+
+function redisUrlFor(docker: boolean): string | undefined {
+  const url = process.env.REDIS_URL ?? process.env.OKE_STORE_KV_URL ?? undefined;
+  if (!url && docker) {
+    throw new Error(
+      "oke boot: signal redis driver needs REDIS_URL (did `oke dev -d` write docker/.env.docker?)",
+    );
+  }
+  return url;
+}
+
 /**
  * Construct a Signal runtime, register decls / binding names, start the bus.
  *
+ * Supported ids: `memory` · `redis`. `postgres` / `nats` fail loud until a real
+ * native client can be constructed (never silently bind memory).
+ *
  * @param options - Boot options
  * @param env - Active environment
  * @param now - Clock
+ * @param docker - Docker mode
  */
 export async function bindSignal(
   options: BootOptions,
   env: ConfigEnv,
   now: () => number,
+  docker = false,
 ): Promise<SignalRuntime> {
-  const signalId = resolveDriverId(options.config?.drivers?.signal, env) ?? "memory";
-  void signalId;
-  const signal = createSignalRuntime({
-    driver: memorySignalDriver,
-    now,
-  });
+  const signalId = resolveSignalDriverId(options, env);
+  const injectedRedis = options.clients?.signalRedis as SignalRedisClientLike | undefined;
+
+  let signal: SignalRuntime;
+  switch (signalId) {
+    case "memory":
+      signal = createSignalRuntime({
+        driver: memorySignalDriver,
+        now,
+      });
+      break;
+    case "redis": {
+      const redis = injectedRedis ?? createBunSignalRedisClient(redisUrlFor(docker));
+      signal = createSignalRuntime({
+        driver: redisSignalDriver,
+        now,
+        redis,
+      });
+      break;
+    }
+    case "postgres":
+      throw new Error(
+        'oke boot: signal driver "postgres" needs a LISTEN/NOTIFY-capable SQL client — ' +
+          'not available via Bun.SQL yet. Use "redis" or "memory", or inject elements.signal.',
+      );
+    case "nats":
+      throw new Error(
+        'oke boot: signal driver "nats" has no production client bind yet — ' +
+          'use "redis" or "memory", or inject elements.signal.',
+      );
+    default:
+      throw new Error(
+        `oke boot: unknown signal driver "${signalId}" (expected memory · redis · postgres · nats)`,
+      );
+  }
+
   for (const decl of options.signals ?? []) {
     signal.register(decl);
   }

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

@@ -2,28 +2,47 @@
  * Lazy vault binder — loaded only when secrets are declared.
  */
 
-import { memoryVaultDriver } from "../../drivers/vault-memory.ts";
+import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import { createVaultRuntime, type VaultRuntime } from "../../elements/vault.ts";
-import type { ConfigEnv } from "../../config/index.ts";
+import { buildVaultBootChain, normalizeVaultDriverId } from "../../elements/vault/boot-chain.ts";
 import type { BootOptions } from "../boot.ts";
 
+/**
+ * Resolve `drivers.vault` for the active env (default `env` locally, `memory` in test).
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+export function resolveVaultDriverId(options: BootOptions, env: ConfigEnv): string {
+  const resolved = resolveDriverId(options.config?.drivers?.vault, env);
+  if (resolved) return resolved;
+  return env === "test" ? "memory" : "env";
+}
+
 /**
  * Construct and boot a Vault runtime from BootOptions.
  *
+ * Uses `drivers.vault` via the shared {@link buildVaultBootChain} helper
+ * (same chain Console uses). Injected `options.vault.chain` still wins for tests.
+ *
  * @param options - Boot options
  * @param env - Active environment
  */
 export async function bindVault(options: BootOptions, env: ConfigEnv): Promise<VaultRuntime> {
   const vaultSecrets = options.vault?.secrets ?? options.secrets ?? [];
+  const chain =
+    options.vault?.chain ??
+    buildVaultBootChain({
+      driverId: normalizeVaultDriverId(resolveVaultDriverId(options, env)),
+      env,
+      cwd: process.cwd(),
+      seed: {},
+    });
   const vault = createVaultRuntime({
     secrets: vaultSecrets,
-    chain: options.vault?.chain ?? [
-      {
-        driver: memoryVaultDriver,
-        options: { secrets: {} },
-      },
-    ],
+    chain,
     allowDevFallbacks: options.vault?.allowDevFallbacks ?? env !== "prod",
+    now: options.vault?.now,
   });
   await vault.boot();
   return vault;

package/src/kernel/boot.test.ts

@@ -79,7 +79,7 @@ describe("boot — lazy element needs", () => {
     expect(needs.signal).toBe(false);
   });
 
-  test("oke() Store-only graph stays under the prior 50 kB baseline", async () => {
+  test("oke() Store-only graph stays under the prior 51 kB baseline", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-store-only-"));
     const entry = join(dir, "entry.ts");
     const appPath = join(import.meta.dir, "app.ts");
@@ -116,9 +116,11 @@ describe("boot — lazy element needs", () => {
         if (raw.byteLength === 0) continue;
         total += Bun.gzipSync(new Uint8Array(raw)).byteLength;
       }
-      // Rebased after AI stream/tool-loop + fx.t/i18n on the shared fx surface
-      // (~49.5 kB gzip). Still far below an eager full-element bind.
-      expect(total).toBeLessThan(50_000);
+      // Rebased after fx.sendOtp/verifyOtp on the shared fx surface (~50.1 kB
+      // gzip), then again after the durable-journal lease surface (SKIP LOCKED
+      // claim/release/orphan-scan on journal.ts + app.ts wiring, ~51.2 kB).
+      // Clock/channel/journal drivers stay lazy-bound; far below eager bind.
+      expect(total).toBeLessThan(51_500);
     } finally {
       await rm(dir, { recursive: true, force: true });
     }