okengine 0.7.0 → 0.9.0

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

@@ -13,6 +13,7 @@ import {
   type ClockDecl,
   type ClockRuntime,
 } from "../../elements/clock.ts";
+import { createPostgresCronStore } from "../../drivers/clock-postgres.ts";
 import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import type { BootOptions } from "../boot.ts";
 
@@ -40,8 +41,7 @@ export function resolveClockDriverId(options: BootOptions, env: ConfigEnv): stri
 /**
  * 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.
+ * Supported ids: `frozen` · `memory` · `file` · `postgres`.
  *
  * @param options - Boot options
  * @param env - Active environment
@@ -76,12 +76,23 @@ export async function bindClock(
       store: createFileCronStore(path),
     });
   } else if (clockDriver === "postgres") {
-    throw new Error(
-      'oke boot: clock driver "postgres" is not implemented — use "memory", "file", or "frozen"',
-    );
+    const url = process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL ?? undefined;
+    if (!url) {
+      throw new Error(
+        env === "docker"
+          ? 'oke boot: clock driver "postgres" needs DATABASE_URL (did `oke dev -d` write docker/.env.docker?)'
+          : 'oke boot: clock driver "postgres" needs DATABASE_URL',
+      );
+    }
+    const store = await createPostgresCronStore({ url });
+    clock = createClockRuntime({
+      instanceId: options.instanceId,
+      now,
+      store,
+    });
   } else {
     throw new Error(
-      `oke boot: unknown clock driver "${clockDriver}" (expected memory · file · frozen)`,
+      `oke boot: unknown clock driver "${clockDriver}" (expected memory · file · postgres · frozen)`,
     );
   }
 

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

@@ -33,15 +33,14 @@ export function resolveGateKvDriverId(
   return docker ? "redis" : "memory";
 }
 
-function kvUrlFor(docker: boolean): string | undefined {
+function kvUrlFor(docker: boolean): string {
   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;
+    throw new Error(
+      docker
+        ? "oke boot: gate redis kv needs REDIS_URL (did `oke dev -d` write docker/.env.docker?)"
+        : "oke boot: gate redis kv needs REDIS_URL — declare drivers.store.kv memory for local, or set REDIS_URL",
+    );
   }
   return url;
 }
@@ -65,19 +64,15 @@ export async function bindGate(
 
   let kvNs;
   if (kvId === "redis") {
+    // Fail loud when redis is configured without URL/inject — never soft-fallback
+    // to memory (that silently doubles rate budgets under horizontal scale).
     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,
-      });
-    }
+    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 });
   }

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

@@ -15,6 +15,7 @@ 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", () => {
@@ -126,19 +127,119 @@ describe("boot binders honour drivers.* config", () => {
     }
   });
 
-  test("clock: drivers.clock postgres fails loud", async () => {
+  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,
-        clocks: [clock("tick", { every: "1h" })],
+        flows: [flow({ name: "charge", durable: true, do: () => ({ ok: true }) })],
         config: {
           drivers: {
-            clock: { local: "postgres" },
+            journal: { local: "neon" },
           },
         },
       }),
-    ).rejects.toThrow(/clock driver "postgres" is not implemented/);
+    ).rejects.toThrow(/unknown journal driver "neon"/);
   });
 
   test("gate: drivers.store.kv redis opens redis-backed oke:gates", async () => {
@@ -162,6 +263,24 @@ describe("boot binders honour drivers.* config", () => {
     }
   });
 
+  test("gate: drivers.store.kv redis without REDIS_URL fails loud (never soft memory)", async () => {
+    delete process.env.REDIS_URL;
+    delete process.env.OKE_STORE_KV_URL;
+    await expect(
+      bootApplication({
+        env: "local",
+        gates: [gate.rate({ max: 10, per: "1m" })],
+        config: {
+          drivers: {
+            store: {
+              kv: { local: "redis", docker: "redis", prod: "redis" },
+            },
+          },
+        },
+      }),
+    ).rejects.toThrow(/gate redis kv needs REDIS_URL/);
+  });
+
   test("gate: drivers.store.kv memory keeps memory oke:gates", async () => {
     const result = await bootApplication({
       env: "local",

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

@@ -29,6 +29,25 @@ function redisUrlFor(docker: boolean): string | undefined {
   return url;
 }
 
+let signalRedisWarned = false;
+
+/** One-shot: redis Signal is emit-relay + process-local outbox consume today. */
+function warnSignalRedisProcessLocal(): void {
+  if (signalRedisWarned) return;
+  signalRedisWarned = true;
+  console.warn(
+    "oke boot: drivers.signal redis — emit relays to Redis, but consume/live/drain use a " +
+      "process-local outbox (not multi-instance competing consumers). Prefer a shared durable " +
+      "outbox path for multi-process tests, or a single consumer instance, until Redis Streams " +
+      "consume ships.",
+  );
+}
+
+/** Test helper — reset the one-shot redis Signal warn. */
+export function resetSignalRedisWarnForTests(): void {
+  signalRedisWarned = false;
+}
+
 /**
  * Construct a Signal runtime, register decls / binding names, start the bus.
  *
@@ -59,6 +78,7 @@ export async function bindSignal(
       break;
     case "redis": {
       const redis = injectedRedis ?? createBunSignalRedisClient(redisUrlFor(docker));
+      warnSignalRedisProcessLocal();
       signal = createSignalRuntime({
         driver: redisSignalDriver,
         now,

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

@@ -3,8 +3,11 @@
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
+import { files } from "../../elements/store.ts";
 import {
+  bindStore,
   indexDriverFor,
+  resetFilesFsWarnForTests,
   resolveFilesDriverId,
   resolveIndexDriverId,
   resolveKvDriverId,
@@ -77,6 +80,85 @@ describe("bindStore driver resolution", () => {
   });
 });
 
+describe("bindStore files fs multi-instance warn", () => {
+  afterEach(() => {
+    resetFilesFsWarnForTests();
+  });
+
+  test("warns once when files driver is fs", () => {
+    const warnings: string[] = [];
+    const prev = console.warn;
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.map(String).join(" "));
+    };
+    try {
+      const uploads = files("uploads");
+      bindStore(
+        {
+          stores: [uploads],
+          config: {
+            drivers: {
+              store: {
+                files: { local: "fs", docker: "s3", prod: "s3" },
+              },
+            },
+          },
+        },
+        "local",
+        () => Date.now(),
+        false,
+      );
+      bindStore(
+        {
+          stores: [uploads],
+          config: {
+            drivers: {
+              store: {
+                files: { local: "fs", docker: "s3", prod: "s3" },
+              },
+            },
+          },
+        },
+        "local",
+        () => Date.now(),
+        false,
+      );
+      expect(warnings.some((w) => w.includes('drivers.store.files "fs"'))).toBe(true);
+      expect(warnings.filter((w) => w.includes('drivers.store.files "fs"'))).toHaveLength(1);
+    } finally {
+      console.warn = prev;
+    }
+  });
+
+  test("does not warn for memory or s3 files", () => {
+    const warnings: string[] = [];
+    const prev = console.warn;
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.map(String).join(" "));
+    };
+    try {
+      bindStore(
+        {
+          stores: [files("uploads")],
+          config: {
+            drivers: {
+              store: {
+                files: { local: "memory", docker: "s3", prod: "s3" },
+              },
+            },
+          },
+        },
+        "local",
+        () => Date.now(),
+        false,
+      );
+      expect(warnings.some((w) => w.includes('drivers.store.files "fs"'))).toBe(false);
+    } finally {
+      console.warn = prev;
+    }
+  });
+});
+
 describe("bindStore index driver resolution", () => {
   const prevIndex = process.env.OKE_INDEX_DRIVER;
 

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

@@ -29,6 +29,27 @@ import type { BootOptions } from "../boot.ts"; // type-only — no cycle at runt
  * @param now - Clock
  * @param docker - Prefer compose URLs when opening postgres/redis
  */
+let filesFsWarned = false;
+
+/** Test helper — reset the one-shot `fs` multi-instance warn. */
+export function resetFilesFsWarnForTests(): void {
+  filesFsWarned = false;
+}
+
+/**
+ * Warn once when `drivers.store.files` is `fs` — per-process (or per-pod)
+ * filesystem visibility under horizontal scale.
+ */
+function warnFilesFsMultiInstance(): void {
+  if (filesFsWarned) return;
+  filesFsWarned = true;
+  console.warn(
+    'oke boot: drivers.store.files "fs" is single-host — each instance sees its own ' +
+      "filesystem (temp root when unbound). For horizontal scale use drivers.store.files s3 " +
+      "(or an explicitly shared volume root, still single-host semantics).",
+  );
+}
+
 export function bindStore(
   options: BootOptions,
   env: ConfigEnv,
@@ -39,6 +60,7 @@ export function bindStore(
   const kvId = resolveKvDriverId(options, env, docker);
   const filesId = resolveFilesDriverId(options, env, docker);
   const indexId = resolveIndexDriverId(options, env, docker);
+  if (filesId === "fs") warnFilesFsMultiInstance();
   const sqlUrl = sqlUrlFor(sqlId, docker);
   const kvUrl = kvUrlFor(kvId, docker);
   const filesRoot = filesRootFor(filesId);

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 53 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), durable-journal lease surface (~51.2 kB), then fx.deliverOtp +
+      // unified otp() plugin wiring on the shared surface (~50.9 kB → 53 kB
+      // cap). Clock/channel/journal drivers stay lazy-bound; far below eager bind.
+      expect(total).toBeLessThan(53_000);
     } finally {
       await rm(dir, { recursive: true, force: true });
     }