okengine 0.6.0 → 0.7.0

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

@@ -0,0 +1,247 @@
+/**
+ * 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 { 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 loud", async () => {
+    await expect(
+      bootApplication({
+        env: "local",
+        startScheduler: false,
+        clocks: [clock("tick", { every: "1h" })],
+        config: {
+          drivers: {
+            clock: { local: "postgres" },
+          },
+        },
+      }),
+    ).rejects.toThrow(/clock driver "postgres" is not implemented/);
+  });
+
+  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/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.ts

@@ -114,6 +114,14 @@ export interface BootOptions {
   readonly onSignal?: (signal: string, payload: unknown) => void | Promise<void>;
   /** Injectable clock for test / frozen harnesses. */
   readonly now?: () => number;
+  /**
+   * Test-only client injection for binders that open redis / signal redis.
+   * Production apps leave this unset.
+   */
+  readonly clients?: {
+    readonly kv?: import("../drivers/types.ts").KvClientLike;
+    readonly signalRedis?: import("../drivers/signal-types.ts").SignalRedisClientLike;
+  };
   /** Instance id for leader election. */
   readonly instanceId?: string;
   /**
@@ -344,7 +352,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   let signal = pre.signal;
   if (needs.signal) {
     if (!signal) {
-      signal = await signalBind!.bindSignal(options, env, now);
+      signal = await signalBind!.bindSignal(options, env, now, docker);
     } else {
       // Pre-built: still register decls / start if needed.
       for (const decl of options.signals ?? []) {
@@ -376,7 +384,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   // Gate (before AI)
   let gate = pre.gate;
   if (needs.gate && !gate) {
-    gate = await gateBind!.bindGate(options, now);
+    gate = await gateBind!.bindGate(options, now, env, docker);
   }
 
   // 5. Channel

package/src/kernel/errors.ts

@@ -143,14 +143,20 @@ export const OKE_ERRORS = {
     fix: 'Add "{resource}" to this flow\'s effects.calls.',
   },
   /**
-   * Emit target has no subscriber (unified-theory §21 example).
-   * Reserved now so the number stays permanent.
+   * Emit target has no subscriber (unified-theory §21).
+   * Thrown at emit when `optional` is false and nobody is subscribed.
    */
   ORPHAN_EMIT: {
     code: 1042,
     cause: 'Flow "{flow}" emits signal "{resource}" with no subscriber.',
     fix: "Add `on({resource}, …)` or mark the signal `{ optional: true }`.",
   },
+  /** Emit payload failed the signal's declared Standard Schema. */
+  SIGNAL_SCHEMA: {
+    code: 1043,
+    cause: '"{resource}": {detail}',
+    fix: "Fix schema payload.",
+  },
   /**
    * Domain table/column missing under docker/prod (migrations not applied).
    * Store/DDL band starts at 1100.

package/src/kernel/fx.test.ts

@@ -258,6 +258,19 @@ describe("errors — registry", () => {
     expect(err.message).toContain("→");
   });
 
+  test("OKE1043 is reserved for signal schema emit failures", () => {
+    const def = OKE_ERRORS.SIGNAL_SCHEMA;
+    expect(def.code).toBe(1043);
+    expect(lookupOkeError(1043)).toEqual(def);
+    const err = new OkeError(def, {
+      resource: "order-placed",
+      detail: "total: Expected number, received string",
+    });
+    expect(err.message).toContain("OKE1043");
+    expect(err.message).toContain("order-placed");
+    expect(err.message).toContain("https://oke.omqkhafi.dev/e/1043");
+  });
+
   test("fx.fail returns a value, not an exception", () => {
     const fx = createFx({ flow: "x", effects: {} });
     const result = fx.fail(

package/src/kernel/fx.ts

@@ -19,6 +19,7 @@ import type {
 } from "../elements/store.ts";
 import type { SqlRow } from "../drivers/types.ts";
 import type { SignalRuntime } from "../elements/signal.ts";
+import type { SignalEmitOptions } from "../drivers/signal-types.ts";
 import type { VaultRuntime } from "../elements/vault.ts";
 import type { ChannelRuntime } from "../elements/channel.ts";
 import type { AiRuntime } from "../elements/ai.ts";
@@ -295,8 +296,9 @@ export interface Fx {
    *
    * @param signal - Signal name or handle
    * @param payload - Payload
+   * @param options - Optional emit options (`key` for per-key once ordering)
    */
-  emit(signal: NamedRef, payload?: unknown): Promise<void>;
+  emit(signal: NamedRef, payload?: unknown, options?: SignalEmitOptions): Promise<void>;
   /**
    * Call another flow (records `call`). Stub returns `undefined`.
    *
@@ -892,7 +894,28 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         });
       }
 
-      // KV / files / index — thin gated wrappers preserving driver methods.
+      if (decl.facet === "files") {
+        const ref = decl.ref;
+        return runtime.openFilesFx(
+          decl as Extract<StoreDecl, { facet: "files" }>,
+          {
+            effects: options.effects ?? {},
+            revealPii: options.revealPii,
+          },
+          {
+            gate: gated,
+            refuseDryRunWrite: () => {
+              if (isDryRun()) {
+                throw new DryRunWriteIsolationError(
+                  `Driver-backed store "${ref}" cannot isolate writes during dry-run; dry-run refused rather than risk a double-write.`,
+                );
+              }
+            },
+          },
+        );
+      }
+
+      // KV / index — thin gated wrappers preserving driver methods.
       const baseRef = decl.ref;
       return new Proxy({} as StoreHandle, {
         get(_t, prop) {
@@ -1010,11 +1033,11 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     store(ref) {
       return storeHandle(ref);
     },
-    emit(signal, payload) {
+    emit(signal, payload, emitOptions) {
       const name = resolveName(signal);
       return gated("emit", name, async () => {
         if (options.signalRuntime) {
-          await options.signalRuntime.emit(name, payload);
+          await options.signalRuntime.emit(name, payload, emitOptions);
         }
       });
     },

package/src/plugins/auth-delivery.mailpit.integration.test.ts

@@ -1,8 +1,9 @@
 /**
  * Real Mailpit end-to-end: magic-link / email-otp request → SMTP → Mailpit API.
  *
- * Gated on a live Docker daemon — same real-skip pattern as pgvector /
- * Meilisearch (`const live = … ? test : test.skip`). Never an empty pass.
+ * Opt-in via `OKE_TEST_DOCKER=1` plus a live Docker daemon — same real-skip
+ * pattern as pgvector / Meilisearch (`const live = … ? test : test.skip`).
+ * Never an empty pass.
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
@@ -36,9 +37,14 @@ function dockerAvailable(): boolean {
   }
 }
 
-const DOCKER = dockerAvailable();
+const WANT = process.env.OKE_TEST_DOCKER === "1";
+const DOCKER = WANT && dockerAvailable();
 if (!DOCKER) {
-  console.log("skip: mailpit e2e (docker daemon not available)");
+  console.log(
+    WANT
+      ? "skip: mailpit e2e (docker daemon not available)"
+      : "skip: mailpit e2e (OKE_TEST_DOCKER≠1)",
+  );
 }
 const live = DOCKER ? test : test.skip;
 

package/src/release/exports.test.ts

@@ -9,7 +9,9 @@ import {
   exportBudgetLabel,
   isMeasurableDriverFile,
   listDriverModules,
+  OFFICIAL_PLUGIN_BUDGETS,
   resolveExportBudgetTargets,
+  resolvePluginBudgetTargets,
 } from "./exports.ts";
 
 const ROOT = resolve(import.meta.dir, "../..");
@@ -29,12 +31,32 @@ describe("export budget targets", () => {
     expect(exportBudgetLabel(".")).toBe("okengine");
     expect(exportBudgetLabel("./channel")).toBe("channel");
     expect(exportBudgetLabel("./drivers/postgres")).toBe("postgres");
+    expect(exportBudgetLabel("./plugins/cors")).toBe("cors");
     expect(exportBudgetGroup(".")).toBe("exports");
     expect(exportBudgetGroup("./channel")).toBe("exports");
+    expect(exportBudgetGroup("./plugins")).toBe("exports");
+    expect(exportBudgetGroup("./plugins/cors")).toBe("plugins");
     expect(exportBudgetGroup("./drivers")).toBe("drivers");
     expect(exportBudgetGroup("./drivers/postgres")).toBe("drivers");
   });
 
+  test("official plugin catalogue files exist and resolve uniquely", async () => {
+    const plugins = resolvePluginBudgetTargets();
+    expect(plugins.length).toBe(OFFICIAL_PLUGIN_BUDGETS.length);
+    expect(new Set(plugins.map((t) => t.id)).size).toBe(plugins.length);
+
+    for (const plugin of OFFICIAL_PLUGIN_BUDGETS) {
+      const path = join(ROOT, "src/plugins", plugin.file);
+      expect(await Bun.file(path).exists()).toBe(true);
+      const target = plugins.find((t) => t.label === plugin.name);
+      expect(target).toBeDefined();
+      expect(target!.id).toBe(`export:./plugins/${plugin.name}`);
+      expect(target!.group).toBe("plugins");
+      expect(target!.category).toBe(plugin.category);
+      expect(target!.entry).toBe(path);
+    }
+  });
+
   test("every non-glob package export and every driver module is covered", async () => {
     const pkg = (await Bun.file(join(ROOT, "package.json")).json()) as {
       exports: Record<string, string>;
@@ -65,6 +87,10 @@ describe("export budget targets", () => {
       expect(target!.entry).toBe(join(ROOT, "src/drivers", file));
     }
 
+    for (const plugin of OFFICIAL_PLUGIN_BUDGETS) {
+      expect(bySubpath.get(`./plugins/${plugin.name}`)).toBeDefined();
+    }
+
     // No duplicates.
     expect(new Set(targets.map((t) => t.id)).size).toBe(targets.length);
   });