okengine 0.7.0 → 0.9.0

package/src/cli/db.test.ts

@@ -3,15 +3,74 @@
  */
 
 import { describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { Database } from "bun:sqlite";
+import { mkdir, mkdtemp, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import { EXIT_OK, EXIT_RUNTIME } from "./exit.ts";
-import { dbCli, emitAbstractSchemaPrestep, runDb, runGenerate, runPush } from "./db.ts";
+import { createFx } from "../kernel/fx.ts";
+import { defineSeed, type SeedFn } from "../elements/store/seed.ts";
+import { EXIT_OK, EXIT_RUNTIME, EXIT_USAGE } from "./exit.ts";
+import {
+  dbCli,
+  emitAbstractSchemaPrestep,
+  executeSeedDef,
+  runDb,
+  runGenerate,
+  runPush,
+  runSeed,
+} from "./db.ts";
 
 /** Repo public entry — absolute import so temp apps need no install. */
 const OKE_INDEX = resolve(import.meta.dir, "../index.ts");
 const CONFIG_MOD = resolve(import.meta.dir, "../config/index.ts");
+const DB_MOD = resolve(import.meta.dir, "./db.ts");
+
+/**
+ * Run `oke db generate|migrate` in a fresh Bun process.
+ *
+ * drizzle-kit's in-process `generate` caches the schema module — a second
+ * generate in the same process after rewriting the schema file returns
+ * `no_changes`. Real CLI invocations are one process each; the adversarial
+ * multi-migration test must match that.
+ *
+ * Temp projects live under {@link import.meta.dir} so `bunx drizzle-kit`
+ * (migrate's default) walks up to the repo `node_modules`.
+ */
+async function runDbFresh(
+  sub: "generate" | "migrate",
+  cwd: string,
+): Promise<{ readonly code: number; readonly out: string }> {
+  const proc = Bun.spawn(
+    [
+      "bun",
+      "-e",
+      `import { runDb } from ${JSON.stringify(DB_MOD)};
+const cwd = ${JSON.stringify(cwd)};
+const prev = process.cwd();
+process.chdir(cwd);
+try {
+  process.exit(await runDb(${JSON.stringify(sub)}, { cwd, skipEmit: true }));
+} finally {
+  process.chdir(prev);
+}
+`,
+    ],
+    { cwd, stdout: "pipe", stderr: "pipe", env: process.env as Record<string, string> },
+  );
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { code, out: `${stdout}${stderr}` };
+}
+
+async function migrationFolders(drizzleDir: string): Promise<string[]> {
+  return (await readdir(drizzleDir, { withFileTypes: true }))
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    .sort();
+}
 
 describe("oke db", () => {
   test("help lists subcommands", async () => {
@@ -26,6 +85,7 @@ describe("oke db", () => {
       expect(lines.join("\n")).toContain("push");
       expect(lines.join("\n")).toContain("generate");
       expect(lines.join("\n")).toContain("migrate");
+      expect(lines.join("\n")).toContain("seed");
       expect(lines.join("\n")).toContain("oke schema generate");
     } finally {
       console.log = orig;
@@ -187,3 +247,281 @@ export const app = oke({ name: "plugin-only" }).plug(
     expect(generated).toContain('integer("hits")');
   });
 });
+
+describe("oke db multi-migration catch-up", () => {
+  /**
+   * Real drizzle-kit generate/migrate through `oke db` — proves multi-file
+   * versioned migrations and that re-migrate / environment lag only apply
+   * previously-unapplied files (drizzle-kit `__drizzle_migrations` history).
+   * The CLI wrapper must not interfere with that bookkeeping.
+   */
+  test("second migrate skips applied files; lag DB catches up with only the new one", async () => {
+    const dir = await mkdtemp(join(import.meta.dir, ".tmp-db-mig-"));
+    try {
+      await mkdir(join(dir, "src"), { recursive: true });
+      await writeFile(
+        join(dir, "src", "schema.ts"),
+        `import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+export const notes = sqliteTable("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+});
+`,
+      );
+      await writeFile(
+        join(dir, "drizzle.config.ts"),
+        `import { defineConfig } from "drizzle-kit";
+export default defineConfig({
+  dialect: "sqlite",
+  schema: "./src/schema.ts",
+  out: "./drizzle",
+  dbCredentials: { url: "file:./app.db" },
+});
+`,
+      );
+
+      const gen1 = await runDbFresh("generate", dir);
+      expect(gen1.code).toBe(EXIT_OK);
+      expect(gen1.out).toMatch(/oke db generate: wrote /);
+      const migsAfterFirst = await migrationFolders(join(dir, "drizzle"));
+      expect(migsAfterFirst.length).toBe(1);
+      const initialMig = migsAfterFirst[0];
+      expect(initialMig).toBeDefined();
+      if (initialMig === undefined) throw new Error("expected initial migration folder");
+
+      const mig1 = await runDbFresh("migrate", dir);
+      expect(mig1.code).toBe(EXIT_OK);
+      expect(mig1.out).toContain("oke db migrate: applied");
+
+      let db = new Database(join(dir, "app.db"));
+      expect(
+        db.query("SELECT name FROM sqlite_master WHERE type='table' AND name='notes'").get(),
+      ).toBeTruthy();
+      let history = db.query("SELECT name FROM __drizzle_migrations ORDER BY id").all() as Array<{
+        name: string;
+      }>;
+      expect(history.map((r) => r.name)).toEqual([initialMig]);
+      db.close();
+
+      await writeFile(
+        join(dir, "src", "schema.ts"),
+        `import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+export const notes = sqliteTable("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  pinned: integer("pinned").notNull().default(0),
+});
+`,
+      );
+      // Distinct timestamp folder names (drizzle-kit uses YYYYMMDDHHmmss).
+      await Bun.sleep(1100);
+
+      const gen2 = await runDbFresh("generate", dir);
+      expect(gen2.code).toBe(EXIT_OK);
+      expect(gen2.out).toMatch(/oke db generate: wrote /);
+      const migs = await migrationFolders(join(dir, "drizzle"));
+      expect(migs.length).toBe(2);
+      const firstMig = migs[0];
+      const secondMig = migs[1];
+      expect(firstMig).toBeDefined();
+      expect(secondMig).toBeDefined();
+      if (firstMig === undefined || secondMig === undefined) {
+        throw new Error("expected two migration folders");
+      }
+      expect(firstMig).toBe(initialMig);
+
+      const mig2 = await runDbFresh("migrate", dir);
+      expect(mig2.code).toBe(EXIT_OK);
+
+      db = new Database(join(dir, "app.db"));
+      history = db.query("SELECT name FROM __drizzle_migrations ORDER BY id").all() as Array<{
+        name: string;
+      }>;
+      expect(history.map((r) => r.name)).toEqual([firstMig, secondMig]);
+      const cols = db.query("PRAGMA table_info(notes)").all() as Array<{ name: string }>;
+      expect(cols.map((c) => c.name)).toContain("pinned");
+      db.close();
+
+      // Idempotent re-migrate: history unchanged, no error.
+      const migNoop = await runDbFresh("migrate", dir);
+      expect(migNoop.code).toBe(EXIT_OK);
+      db = new Database(join(dir, "app.db"));
+      const historyNoop = db
+        .query("SELECT name FROM __drizzle_migrations ORDER BY id")
+        .all() as Array<{ name: string }>;
+      expect(historyNoop.map((r) => r.name)).toEqual([firstMig, secondMig]);
+      db.close();
+
+      // Staging/prod lag: fresh DB with only the first migration applied,
+      // then both files present — catch up applies only the second.
+      await rm(join(dir, "app.db"), { force: true });
+      const stash = join(dir, "_stash_second");
+      await rm(stash, { recursive: true, force: true });
+      await rename(join(dir, "drizzle", secondMig), stash);
+
+      const lagFirst = await runDbFresh("migrate", dir);
+      expect(lagFirst.code).toBe(EXIT_OK);
+      db = new Database(join(dir, "app.db"));
+      const lagHist1 = db
+        .query("SELECT name FROM __drizzle_migrations ORDER BY id")
+        .all() as Array<{ name: string }>;
+      expect(lagHist1.map((r) => r.name)).toEqual([firstMig]);
+      const lagCols1 = db.query("PRAGMA table_info(notes)").all() as Array<{ name: string }>;
+      expect(lagCols1.map((c) => c.name)).not.toContain("pinned");
+      db.close();
+
+      await rename(stash, join(dir, "drizzle", secondMig));
+      const lagCatchUp = await runDbFresh("migrate", dir);
+      expect(lagCatchUp.code).toBe(EXIT_OK);
+      db = new Database(join(dir, "app.db"));
+      const lagHist2 = db
+        .query("SELECT name FROM __drizzle_migrations ORDER BY id")
+        .all() as Array<{ name: string }>;
+      expect(lagHist2.map((r) => r.name)).toEqual([firstMig, secondMig]);
+      const lagCols2 = db.query("PRAGMA table_info(notes)").all() as Array<{ name: string }>;
+      expect(lagCols2.map((c) => c.name)).toContain("pinned");
+      db.close();
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }, 120_000);
+});
+
+describe("oke db seed", () => {
+  function trackingDef(order: string[]) {
+    const a: SeedFn = async function a() {
+      order.push("a");
+    };
+    const b: SeedFn = async function b() {
+      order.push("b");
+    };
+    const dev: SeedFn = async function seedDev() {
+      order.push("dev");
+    };
+    const prod: SeedFn = async function seedProd() {
+      order.push("prod");
+    };
+    return defineSeed({
+      essential: [a, b],
+      dev,
+      prod,
+    });
+  }
+
+  async function seedWith(
+    env: "local" | "docker" | "test" | "prod",
+    extras: Parameters<typeof runSeed>[0] = {},
+  ) {
+    const order: string[] = [];
+    const out: string[] = [];
+    const code = await runSeed({
+      env,
+      seedDef: trackingDef(order),
+      createFx: async () => ({
+        fx: createFx({ flow: "oke.db.seed.test" }),
+        stop: async () => {},
+      }),
+      write: (t) => out.push(t),
+      force: true,
+      ...extras,
+    });
+    return { code, order, out: out.join("") };
+  }
+
+  test("essential array order is execution order", async () => {
+    const { code, order, out } = await seedWith("local");
+    expect(code).toBe(EXIT_OK);
+    expect(order.slice(0, 2)).toEqual(["a", "b"]);
+    expect(out).toContain("oke db seed: essential a");
+    expect(out).toContain("oke db seed: ok");
+  });
+
+  test("local runs essential + dev, never prod", async () => {
+    const { order } = await seedWith("local");
+    expect(order).toEqual(["a", "b", "dev"]);
+  });
+
+  test("docker runs essential + dev, never prod", async () => {
+    const { order } = await seedWith("docker");
+    expect(order).toEqual(["a", "b", "dev"]);
+  });
+
+  test("prod runs essential + prod, never dev", async () => {
+    const { order } = await seedWith("prod");
+    expect(order).toEqual(["a", "b", "prod"]);
+  });
+
+  test("test runs essential only", async () => {
+    const { order, out } = await seedWith("test");
+    expect(order).toEqual(["a", "b"]);
+    expect(out).toContain("essential only");
+  });
+
+  test("prod without --force requires confirmEnv", async () => {
+    const out: string[] = [];
+    let asked = false;
+    const code = await runSeed({
+      env: "prod",
+      force: false,
+      stdinIsTTY: true,
+      seedDef: defineSeed({ essential: async () => {} }),
+      createFx: async () => ({
+        fx: createFx({ flow: "oke.db.seed.test" }),
+        stop: async () => {},
+      }),
+      confirmEnv: async () => {
+        asked = true;
+        return false;
+      },
+      write: (t) => out.push(t),
+    });
+    expect(asked).toBe(true);
+    expect(code).toBe(EXIT_USAGE);
+    expect(out.join("")).toContain("cancelled");
+  });
+
+  test("prod with --force skips confirm", async () => {
+    let asked = false;
+    const { code } = await seedWith("prod", {
+      force: true,
+      confirmEnv: async () => {
+        asked = true;
+        return false;
+      },
+    });
+    expect(asked).toBe(false);
+    expect(code).toBe(EXIT_OK);
+  });
+
+  test("docker confirm proceeds when confirmEnv returns true", async () => {
+    const out: string[] = [];
+    const order: string[] = [];
+    const code = await runSeed({
+      env: "docker",
+      force: false,
+      stdinIsTTY: true,
+      seedDef: trackingDef(order),
+      createFx: async () => ({
+        fx: createFx({ flow: "oke.db.seed.test" }),
+        stop: async () => {},
+      }),
+      confirmEnv: async (env, target) => {
+        expect(env).toBe("docker");
+        expect(target.length).toBeGreaterThan(0);
+        return true;
+      },
+      write: (t) => out.push(t),
+    });
+    expect(code).toBe(EXIT_OK);
+    expect(order).toEqual(["a", "b", "dev"]);
+    expect(out.join("")).toContain("oke db seed:");
+  });
+
+  test("executeSeedDef is the category source of truth", async () => {
+    const order: string[] = [];
+    const out: string[] = [];
+    const fx = createFx({ flow: "x" });
+    await executeSeedDef(trackingDef(order), "prod", fx, (t) => out.push(t));
+    expect(order).toEqual(["a", "b", "prod"]);
+  });
+});

package/src/cli/db.ts

@@ -1,5 +1,6 @@
 /**
- * `oke db push|generate|migrate` — domain schema sync via drizzle-kit.
+ * `oke db push|generate|migrate|seed` — domain schema sync via drizzle-kit,
+ * plus explicit seed runs.
  *
  * Distinct from `oke schema generate` (core/plugin stub tables).
  * When abstract decls exist (`src/schema.decl.ts`), emits Drizzle first —
@@ -15,11 +16,24 @@ import {
 import { loadPluginTablesFromAppEntry } from "../elements/store/load-plugin-tables.ts";
 import { resolveDriverId, type ConfigEnv, type OkeConfig } from "../config/index.ts";
 import type { TableContribution } from "../kernel/plugin.ts";
+import { runSeed, type SeedOptions } from "./db-seed.ts";
 import { resolveDrizzleKitEnv } from "./drizzle-env.ts";
 import { resolveDevSqlEnv } from "./resolve-dev-sql-env.ts";
 import { EXIT_OK, EXIT_RUNTIME, EXIT_USAGE } from "./exit.ts";
 import { loadOkeConfig } from "./load-config.ts";
 
+export {
+  executeSeedDef,
+  formatSeedTarget,
+  isSeedDef,
+  loadSeedDef,
+  redactConnectionTarget,
+  runSeed,
+  runSeedFns,
+  type SeedOptions,
+  type SeedTally,
+} from "./db-seed.ts";
+
 /**
  * Apply a drizzle-kit env overlay to `process.env` for the in-process SDK,
  * returning a restore function. drizzle-kit's `push`/`generate` read
@@ -67,7 +81,7 @@ export async function withDrizzleKitEnv<T>(
 }
 
 /** Subcommands under `oke db`. */
-export type DbSubcommand = "push" | "generate" | "migrate";
+export type DbSubcommand = "push" | "generate" | "migrate" | "seed";
 
 /** Options for {@link runDb}. */
 export interface DbOptions {
@@ -104,6 +118,15 @@ export interface DbOptions {
   readonly pluginTables?: readonly TableContribution[];
   /** Override app entry path for plugin-table discovery. */
   readonly entry?: string;
+  /** Skip docker/prod confirm for seed (`--force`). */
+  readonly force?: boolean;
+  /** Seed module path override. */
+  readonly seedPath?: string;
+  /** Seed-only injectables forwarded to {@link runSeed}. */
+  readonly seedDef?: SeedOptions["seedDef"];
+  readonly createFx?: SeedOptions["createFx"];
+  readonly confirmEnv?: SeedOptions["confirmEnv"];
+  readonly stdinIsTTY?: boolean;
 }
 
 /** Minimal drizzle-kit envelope we handle. */
@@ -135,7 +158,7 @@ export async function resolveDrizzleConfigPath(
 /**
  * Run `oke db <subcommand>`.
  *
- * @param sub - push | generate | migrate
+ * @param sub - push | generate | migrate | seed
  * @param options - Paths / injectables
  */
 export async function runDb(sub: DbSubcommand, options: DbOptions = {}): Promise<number> {
@@ -143,6 +166,22 @@ export async function runDb(sub: DbSubcommand, options: DbOptions = {}): Promise
   const cwd = options.cwd ?? process.cwd();
   const loaded = await loadOkeConfig(cwd).catch(() => null);
   const env = options.env ?? (await resolveDevSqlEnv(cwd));
+
+  if (sub === "seed") {
+    return runSeed({
+      cwd,
+      write,
+      env,
+      force: options.force,
+      seedPath: options.seedPath,
+      entry: options.entry,
+      seedDef: options.seedDef,
+      createFx: options.createFx,
+      confirmEnv: options.confirmEnv,
+      stdinIsTTY: options.stdinIsTTY,
+    });
+  }
+
   if (!options.skipEmit) {
     await emitAbstractSchemaPrestep(cwd, loaded?.config, write, env, {
       pluginTables: options.pluginTables,
@@ -399,16 +438,16 @@ export async function detectDbDrift(options: DbOptions = {}): Promise<{
 }
 
 /**
- * CLI entry: parse `oke db <push|generate|migrate> [--config path]`.
+ * CLI entry: parse `oke db <push|generate|migrate|seed> […]`.
  *
  * @param args - Args after `db`
  */
 export async function dbCli(args: readonly string[]): Promise<number> {
   const sub = args[0];
   if (!sub || sub === "--help" || sub === "-h") {
-    console.log(`oke db push|generate|migrate [--config|-c drizzle.config.ts]
+    console.log(`oke db push|generate|migrate|seed [--config|-c] [--env name] [--force]
 
-Domain schema sync via drizzle-kit.
+Domain schema sync via drizzle-kit, plus explicit seed.
 When src/schema.decl.ts and/or a plugged app entry exists, emits
 schema.generated.ts from store.schema.table + live plugin .table()
 contributions — then runs drizzle-kit.
@@ -418,24 +457,52 @@ Not the same as \`oke schema generate\` (core/plugin stub tables).
   push       Apply schema to the live local DB (dev; no migration files)
   generate   Write versioned SQL under drizzle/ for review
   migrate    Apply generated migrations (explicit; never automatic in prod)
+  seed       Run defineSeed (essential + env category); never at boot
+
+  --env      Override config env (local|docker|test|prod)
+  --force    Skip docker/prod confirmation prompt (CI)
+  --entry    App entry for seed boot / plugin table discovery
 `);
     return sub ? EXIT_OK : EXIT_USAGE;
   }
-  if (sub !== "push" && sub !== "generate" && sub !== "migrate") {
+  if (sub !== "push" && sub !== "generate" && sub !== "migrate" && sub !== "seed") {
     console.error(`oke db: unknown subcommand "${sub}"`);
     return EXIT_USAGE;
   }
 
   let config: string | undefined;
+  let env: ConfigEnv | undefined;
+  let force = false;
+  let entry: string | undefined;
   for (let i = 1; i < args.length; i++) {
     const a = args[i]!;
     if (a === "--config" || a === "-c") config = args[++i];
+    else if (a === "--env") {
+      const value = args[++i];
+      const parsed = parseConfigEnv(value);
+      if (!parsed) {
+        console.error(`oke db: invalid --env ${JSON.stringify(value)} (local|docker|test|prod)`);
+        return EXIT_USAGE;
+      }
+      env = parsed;
+    } else if (a === "--force") force = true;
+    else if (a === "--entry" || a === "-e") entry = args[++i];
     else if (a === "--help" || a === "-h") {
       return dbCli(["--help"]);
+    } else if (a.startsWith("-")) {
+      console.error(`oke db ${sub}: unknown flag ${a}`);
+      return EXIT_USAGE;
     }
   }
 
-  return runDb(sub, { config });
+  return runDb(sub, { config, env, force, entry });
+}
+
+function parseConfigEnv(value: string | undefined): ConfigEnv | undefined {
+  if (value === "local" || value === "docker" || value === "test" || value === "prod") {
+    return value;
+  }
+  return undefined;
 }
 
 function reportKitResult(verb: string, result: DbKitResult, write: (text: string) => void): number {

package/src/cli/dev-app-runner.ts

@@ -17,6 +17,7 @@
 
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { installGracefulShutdown, type GracefulShutdownApp } from "../kernel/graceful-shutdown.ts";
 import { createBunRuntime } from "../runtime/bun.ts";
 import { APP_PORT, type FetchApp } from "../runtime/types.ts";
 import { clearTerminalScreen, formatAppReadyLine, formatDevHero } from "../term.ts";
@@ -33,6 +34,8 @@ type DevRunnerGlobals = typeof globalThis & {
 /** App entry shape — FetchApp plus boot before serve. */
 type BootableApp = FetchApp & {
   boot(): Promise<unknown>;
+  stop(): Promise<void>;
+  readonly bootResult?: GracefulShutdownApp["bootResult"];
 };
 
 const entry = Bun.env["OKE_ENTRY"];
@@ -68,6 +71,7 @@ const handle = createBunRuntime().serve(mod.app, {
   hostname,
   id: DEV_APP_SERVE_ID,
 });
+installGracefulShutdown({ app: mod.app, handle });
 
 const appUrl = `http://${formatHostForUrl(hostname)}:${handle.port}`;
 const g = globalThis as DevRunnerGlobals;

package/src/cli/docker.ts

@@ -105,7 +105,10 @@ export async function runDockerDerive(
     write(
       `compose merge order (cwd ${composeDir}/):\n${result.composeFiles.map((f) => `  -f ${f}`).join("\n")}\n`,
     );
-    write(`(${composeDir}/compose.override.yml is layer 4 — user-owned, never written by oke)\n`);
+    write(
+      `(${composeDir}/compose.override.yml is layer 4 — user-owned, never written by oke)\n` +
+        `(${composeDir}/compose.all.yml is layers 1–3 merged — single-file alternative for Swarm / one \`-c\`)\n`,
+    );
     return { code: 0, result };
   } catch (err) {
     console.error(err instanceof Error ? err.message : String(err));

package/src/cli/load-config.images.test.ts

@@ -21,6 +21,7 @@ describe("defaultImagesFromConfig", () => {
     });
     expect(images).toEqual({
       "store.sql": "postgres:18-alpine",
+      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
       "store.kv": "redis:8-alpine",
     });
   });
@@ -35,6 +36,31 @@ describe("defaultImagesFromConfig", () => {
       },
     });
     expect(images["store.sql"]).toBe("pgvector/pgvector:pg17");
+    expect(images.pgdog).toBe("ghcr.io/pgdogdev/pgdog:v0.1.51");
+  });
+
+  test("clock postgres alone pulls store.sql image", () => {
+    const images = defaultImagesFromConfig({
+      drivers: {
+        clock: { prod: "postgres" },
+      },
+    });
+    expect(images).toEqual({
+      "store.sql": "postgres:18-alpine",
+      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
+    });
+  });
+
+  test("journal postgres alone pulls store.sql image", () => {
+    const images = defaultImagesFromConfig({
+      drivers: {
+        journal: { prod: "postgres" },
+      },
+    });
+    expect(images).toEqual({
+      "store.sql": "postgres:18-alpine",
+      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
+    });
   });
 
   test("returns empty when no container drivers", () => {

package/src/cli/load-config.ts

@@ -9,6 +9,7 @@ import type { Manifest } from "../manifest/types.ts";
 /** Default image pins when `images` is omitted but prod drivers need containers. */
 const DEFAULT_SQL_IMAGE = "postgres:18-alpine";
 const DEFAULT_PGVECTOR_IMAGE = "pgvector/pgvector:pg17";
+const DEFAULT_PGDOG_IMAGE = "ghcr.io/pgdogdev/pgdog:v0.1.51";
 const DEFAULT_KV_IMAGE = "redis:8-alpine";
 const DEFAULT_VAULT_IMAGE = "openbao/openbao:2.6.1";
 
@@ -47,18 +48,25 @@ export function defaultImagesFromConfig(config: OkeConfig): Readonly<Record<stri
   const index = dockerOrProdId(config.drivers?.store?.index);
   const kv = dockerOrProdId(config.drivers?.store?.kv);
   const signal = dockerOrProdId(config.drivers?.signal);
+  const clock = dockerOrProdId(config.drivers?.clock);
+  const journal = dockerOrProdId(config.drivers?.journal);
 
-  // Only real SQL-consuming facets pull a SQL image. Clock/signal no longer
-  // advertise a fictional postgres CronStore / LISTEN bus via compose.
+  // SQL-consuming facets pull a SQL image. Signal postgres still needs a
+  // LISTEN/NOTIFY client (not Bun.SQL); clock + journal postgres are real
+  // SKIP LOCKED stores (CronStore / durable-run journal).
   const needsSql =
     sql === "postgres" ||
     sql === "pgvector" ||
     index === "pgvector" ||
+    clock === "postgres" ||
+    journal === "postgres" ||
     (config.drivers?.prod ?? []).some((p) => p === "postgres" || p === "pgvector");
 
   if (needsSql) {
     out["store.sql"] =
       sql === "pgvector" || index === "pgvector" ? DEFAULT_PGVECTOR_IMAGE : DEFAULT_SQL_IMAGE;
+    // PgDog in front of Postgres — caps real server connections under horizontal scale.
+    out.pgdog = DEFAULT_PGDOG_IMAGE;
   }
 
   const needsKv =