okengine 0.22.0 → 0.23.1

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

@@ -336,18 +336,48 @@ describe("boot binders honour drivers.* config", () => {
     }
   });
 
-  test("signal: drivers.signal postgres fails loud (never silent memory)", async () => {
-    await expect(
-      bootApplication({
-        env: "test",
-        signals: [signal.once("ping")],
-        config: {
-          drivers: {
-            signal: { test: "postgres" },
+  test("signal: drivers.signal postgres needs DATABASE_URL (never silent memory)", 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: "test",
+          signals: [signal.once("ping")],
+          config: {
+            drivers: {
+              signal: { test: "postgres" },
+            },
           },
+        }),
+      ).rejects.toThrow(/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("signal: drivers.signal postgres binds an injected client", async () => {
+    const { createPostgresSignalFake } = await import("../../drivers/signal-postgres.ts");
+    const result = await bootApplication({
+      env: "test",
+      signals: [signal.once("ping")],
+      clients: { signalSql: createPostgresSignalFake() },
+      config: {
+        drivers: {
+          signal: { test: "postgres" },
         },
-      }),
-    ).rejects.toThrow(/signal driver "postgres"/);
+      },
+    });
+    try {
+      expect(result.signal!.driverId).toBe("postgres");
+    } finally {
+      await result.close();
+    }
   });
 
   test("runs: drivers.runs unset in test binds memory", async () => {

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

@@ -4,11 +4,19 @@
 
 import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import { SIGNAL_DEFAULTS } from "../../config/driver-defaults.ts";
+import {
+  sharedPostgresClient,
+  toPostgresParams,
+  withPinnedPostgres,
+} from "../../drivers/postgres.ts";
+import type { PostgresClientLike } from "../../drivers/postgres.ts";
 import { memorySignalDriver } from "../../drivers/signal-memory.ts";
+import type { PostgresSignalSql } from "../../drivers/signal-postgres.ts";
+import { postgresSignalDriver } from "../../drivers/signal-postgres.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 { emitBootWarn } from "../../runtime/boot-warn.ts";
+import { resolveInstanceId } from "../instance-id.ts";
 import type { BootOptions } from "../boot.ts";
 
 /**
@@ -32,29 +40,43 @@ 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;
-  emitBootWarn(
-    "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;
+/**
+ * Wrap a Bun.SQL client as the signal driver's query surface.
+ * `listen` is omitted — Bun.SQL has no LISTEN/NOTIFY. Boot polls `drain`.
+ *
+ * @param client - Shared postgres pool
+ */
+function asSignalSql(client: PostgresClientLike): PostgresSignalSql {
+  return {
+    async query(sql, params = []) {
+      const result = await client.unsafe(toPostgresParams(sql, params), [...params]);
+      if (Array.isArray(result)) return result as Record<string, unknown>[];
+      return Array.from(result as ArrayLike<Record<string, unknown>>);
+    },
+    async exec(sql, params = []) {
+      const result = await client.unsafe(toPostgresParams(sql, params), [...params]);
+      if (
+        result &&
+        typeof result === "object" &&
+        "changes" in result &&
+        typeof result.changes === "number"
+      ) {
+        return { changes: result.changes };
+      }
+      if (Array.isArray(result)) return { changes: result.length };
+      return { changes: 0 };
+    },
+    begin: (fn) => withPinnedPostgres(client, (tx) => fn(asSignalSql(tx))),
+    async close() {
+      /* Shared pool — boot owns the connection. */
+    },
+  };
 }
 
 /**
  * Construct a Signal runtime, register decls / binding names, start the bus.
  *
- * Supported ids: `memory` · `redis`. `postgres` / `nats` fail loud until a real
+ * Supported ids: `memory` · `redis` · `postgres`. `nats` fails loud until a
  * native client can be constructed (never silently bind memory).
  *
  * @param options - Boot options
@@ -81,19 +103,33 @@ export async function bindSignal(
       break;
     case "redis": {
       const redis = injectedRedis ?? createBunSignalRedisClient(redisUrlFor(docker));
-      warnSignalRedisProcessLocal();
       signal = createSignalRuntime({
         driver: redisSignalDriver,
         now,
         redis,
+        compete: true,
+        consumerId: resolveInstanceId(options.instanceId),
+      });
+      break;
+    }
+    case "postgres": {
+      const injected = options.clients?.signalSql;
+      const url = process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL ?? undefined;
+      if (!injected && !url) {
+        throw new Error(
+          env === "dev"
+            ? 'oke boot: signal driver "postgres" needs DATABASE_URL (did `oke dev` write .env.local?)'
+            : 'oke boot: signal driver "postgres" needs DATABASE_URL',
+        );
+      }
+      signal = createSignalRuntime({
+        driver: postgresSignalDriver,
+        now,
+        sql: injected ?? asSignalSql(sharedPostgresClient(url)),
+        pollMs: injected ? undefined : 1_000,
       });
       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 — ' +

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

@@ -13,6 +13,7 @@ import {
   resolveIndexDriverId,
   resolveKvDriverId,
   resolveSqlDriverId,
+  sqlBindingForDecl,
 } from "./store.ts";
 
 describe("bindStore driver resolution", () => {
@@ -99,6 +100,31 @@ describe("bindStore driver resolution", () => {
   });
 });
 
+describe("sqlBindingForDecl", () => {
+  test("pool.max and replica URLs land on the binding; min is ignored", () => {
+    const binding = sqlBindingForDecl("db", "postgres://primary/db", {
+      driver: "postgres",
+      pool: { max: 20, min: 2 },
+      replicas: ["postgres://ro-1/db", "postgres://ro-2/db"],
+    });
+    expect(binding).toEqual({
+      name: "db",
+      primary: { url: "postgres://primary/db", pool: { max: 20 } },
+      replicas: [
+        { url: "postgres://ro-1/db", pool: { max: 20 } },
+        { url: "postgres://ro-2/db", pool: { max: 20 } },
+      ],
+    });
+  });
+
+  test("a string pin keeps the URL and omits pool and replicas", () => {
+    expect(sqlBindingForDecl("db", "memory://", "memory")).toEqual({
+      name: "db",
+      primary: { url: "memory://" },
+    });
+  });
+});
+
 describe("bindStore durable KV routing", () => {
   const prev = {
     redis: process.env.REDIS_URL,

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

@@ -2,7 +2,14 @@
  * Lazy store binder — loaded only when Store is declared.
  */
 
-import { resolveDomainDdlMode, resolveDriverId, type ConfigEnv } from "../../config/index.ts";
+import {
+  driverRefId,
+  resolveDomainDdlMode,
+  resolveDriverId,
+  resolveDriverRef,
+  type ConfigEnv,
+  type DriverRef,
+} from "../../config/index.ts";
 import {
   STORE_FILES_DEFAULTS,
   STORE_KV_DEFAULTS,
@@ -18,6 +25,7 @@ import { redisDriver } from "../../drivers/redis.ts";
 import { s3Driver } from "../../drivers/s3.ts";
 import type { FilesDriver, IndexDriver, KvDriver, SqlDriver } from "../../drivers/types.ts";
 import { createStoreRuntime, type StoreRuntime } from "../../elements/store.ts";
+import type { SqlRuntimeBinding } from "../../elements/store/runtime.ts";
 import type { StoreDecl } from "../../elements/store/declare.ts";
 import { emitBootWarn } from "../../runtime/boot-warn.ts";
 import type { BootOptions } from "../boot.ts"; // type-only — no cycle at runtime
@@ -129,17 +137,15 @@ export function bindStore(
     warnKvMemoryDurable(durableKvDecls.map((d) => d.name));
   }
 
-  const sqlBindings: Record<string, { name: string; primary: { url: string } }> = {};
+  const sqlRef = resolveSqlDriverRef(options, env, docker);
+  const sqlBindings: Record<string, SqlRuntimeBinding> = {};
   const kvBindings: Record<string, { url?: string }> = {};
   const filesBindings: Record<string, { root?: string }> = {};
   const indexBindings: Record<string, { url?: string; apiKey?: string }> = {};
 
   for (const decl of options.stores ?? []) {
     if (isSqlDecl(decl)) {
-      sqlBindings[decl.name] = {
-        name: decl.name,
-        primary: { url: sqlUrl },
-      };
+      sqlBindings[decl.name] = sqlBindingForDecl(decl.name, sqlUrl, sqlRef);
     } else if (isKvDecl(decl)) {
       if (decl.durable === true) {
         kvBindings[decl.name] = {};
@@ -210,6 +216,76 @@ export function resolveSqlDriverId(options: BootOptions, env: ConfigEnv, docker:
   return resolveDriverId(options.config?.drivers?.store?.sql, env, STORE_SQL_DEFAULTS)!;
 }
 
+/**
+ * Rich SQL driver ref for the active env. A docker `OKE_SQL_DRIVER` override
+ * that changes the protocol drops `pool` / `replicas` — those belong to the
+ * configured driver, not the override.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ * @param docker - Docker mode
+ */
+function resolveSqlDriverRef(
+  options: BootOptions,
+  env: ConfigEnv,
+  docker: boolean,
+): DriverRef | undefined {
+  const configured = resolveDriverRef(options.config?.drivers?.store?.sql, env, STORE_SQL_DEFAULTS);
+  const fromEnv = process.env.OKE_SQL_DRIVER?.trim();
+  if (docker && fromEnv && fromEnv !== driverRefId(configured)) return fromEnv;
+  return configured;
+}
+
+/**
+ * Primary URL plus documented `pool.max` and read-replica URLs.
+ *
+ * `pool.min` is ignored — Bun.SQL has no minimum pool size. Unset `max`
+ * leaves pool sizing to the postgres driver default of 8.
+ *
+ * @param name - Store declaration name
+ * @param url - Primary connection URL
+ * @param ref - Active driver pin (string or rich object)
+ */
+export function sqlBindingForDecl(
+  name: string,
+  url: string,
+  ref: DriverRef | undefined,
+): SqlRuntimeBinding {
+  const max = driverPoolMax(ref);
+  const pool = max !== undefined ? { pool: { max } } : {};
+  const replicas = driverReplicaUrls(ref).map((replicaUrl) => ({
+    url: replicaUrl,
+    ...pool,
+  }));
+  return {
+    name,
+    primary: { url, ...pool },
+    ...(replicas.length > 0 ? { replicas } : {}),
+  };
+}
+
+/**
+ * Positive finite `pool.max` from a rich driver ref.
+ *
+ * @param ref - Driver pin
+ */
+function driverPoolMax(ref: DriverRef | undefined): number | undefined {
+  if (ref === undefined || typeof ref === "string") return undefined;
+  const max = ref.pool?.max;
+  if (typeof max !== "number" || !Number.isFinite(max) || max < 1) return undefined;
+  return Math.floor(max);
+}
+
+/**
+ * Replica connection strings from a rich driver ref. Non-strings are dropped.
+ *
+ * @param ref - Driver pin
+ */
+function driverReplicaUrls(ref: DriverRef | undefined): readonly string[] {
+  if (ref === undefined || typeof ref === "string" || ref.replicas === undefined) return [];
+  return ref.replicas.filter((item): item is string => typeof item === "string" && item.length > 0);
+}
+
 /**
  * @param options - Boot options
  * @param env - Active env

package/src/kernel/boot.ts

@@ -191,6 +191,8 @@ export interface BootOptions {
   readonly clients?: {
     readonly kv?: import("../drivers/types.ts").KvClientLike;
     readonly signalRedis?: import("../drivers/signal-types.ts").SignalRedisClientLike;
+    /** Injected postgres signal client (tests). Production opens Bun.SQL. */
+    readonly signalSql?: import("../drivers/signal-postgres.ts").PostgresSignalSql;
   };
   /**
    * Process instance id for Clock / Journal / fleet registry.
@@ -282,9 +284,14 @@ export function resolveElementNeeds(options: BootOptions): ElementNeeds {
   const considerFlow = (f: AnyFlowDef): void => {
     const e = f.effects;
     if (f.durable === true) journal = true;
-    if ((e?.reads?.length ?? 0) > 0 || (e?.writes?.length ?? 0) > 0) {
-      store = true;
-    }
+    const touchesStore = [...(e?.reads ?? []), ...(e?.writes ?? [])].some(
+      (ref) =>
+        ref.startsWith("sql:") ||
+        ref.startsWith("kv:") ||
+        ref.startsWith("files:") ||
+        ref.startsWith("index:"),
+    );
+    if (touchesStore) store = true;
     if ((e?.emits?.length ?? 0) > 0) signal = true;
     if ((e?.secrets?.length ?? 0) > 0) vault = true;
     if ((e?.sends?.length ?? 0) > 0) channel = true;
@@ -533,7 +540,16 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   // 4d. Scheduler — one timer drives clock ticks, durable-run resume, heartbeat.
   let schedulerTimer: ReturnType<typeof setInterval> | undefined;
   const startScheduler = options.startScheduler ?? env !== "test";
-  if (startScheduler && (clock !== undefined || journal !== undefined || instances !== undefined)) {
+  const signalBus = signal?.bus ?? undefined;
+  let refreshChannel: (() => Promise<void>) | undefined;
+  if (
+    startScheduler &&
+    (clock !== undefined ||
+      journal !== undefined ||
+      instances !== undefined ||
+      signalBus !== undefined ||
+      needs.channel)
+  ) {
     const period = options.schedulerIntervalMs ?? 1000;
     const clockRt = clock;
     const durableResume = options.onDurableResume;
@@ -545,9 +561,17 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
       console.error(err);
     };
     schedulerTimer = setInterval(() => {
+      if (signalBus) void signalBus.drain().catch(ignoreBenignSql);
+      if (refreshChannel) void refreshChannel().catch(ignoreBenignSql);
       if (clockRt) void Promise.resolve(clockRt.tick()).catch(ignoreBenignSql);
       if (journal && durableResume) void Promise.resolve(durableResume()).catch(ignoreBenignSql);
       if (fleet) void fleet.maybeHeartbeat().catch(ignoreBenignSql);
+      const stem = ["run", "events"].join("-");
+      void import(`../elements/ai/${stem}.ts`)
+        .then((mod: typeof import("../elements/ai/run-events.ts")) =>
+          mod.sweepInstalledAgentEvents(),
+        )
+        .catch(ignoreBenignSql);
     }, period);
     schedulerTimer.unref?.();
   }
@@ -561,13 +585,14 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   // 5. Channel
   let channel = pre.channel;
   if (needs.channel && !channel) {
-    channel = channelBind!.bindChannel(options, env, now, docker);
+    channel = await channelBind!.bindChannel(options, env, now, docker);
+    refreshChannel = channel.refresh?.bind(channel);
   }
 
   // 6. AI
   let ai = pre.ai;
   if (needs.ai && !ai) {
-    ai = aiBind!.bindAi(options, gate, now, env, docker, vault);
+    ai = aiBind!.bindAi(options, gate, now, env, docker, vault, journal?.store);
   }
 
   // 7. Runs

package/src/kernel/builtin-errors.ts

@@ -25,6 +25,7 @@ export const BUILTIN_ERROR_STATUS = {
   IdempotencyKeyInvalid: 400,
   IdempotencyKeyReused: 422,
   IdempotencyInProgress: 409,
+  JournalLeaseBusy: 409,
 } as const;
 
 /** Built-in error code (including `DatabaseError`). */
@@ -94,6 +95,7 @@ export type BuiltinErrorMap = {
   readonly IdempotencyKeyInvalid: Record<string, never>;
   readonly IdempotencyKeyReused: Record<string, never>;
   readonly IdempotencyInProgress: { readonly retryAfter?: number };
+  readonly JournalLeaseBusy: { readonly retryAfter?: number };
 };
 
 /**

package/src/kernel/capability.ts

@@ -21,6 +21,7 @@ const UNDECLARED_KEY: Readonly<Record<EffectKind, keyof typeof OKE_ERRORS>> = {
   secret: "UNDECLARED_SECRET",
   call: "UNDECLARED_CALL",
   fetch: "UNDECLARED_FETCH",
+  decide: "UNDECLARED_DECIDE",
 };
 
 /** Maps effect kind → the corresponding `Effects` field. */
@@ -34,6 +35,7 @@ const EFFECTS_FIELD: Readonly<Record<EffectKind, keyof Effects>> = {
   secret: "secrets",
   call: "calls",
   fetch: "fetches",
+  decide: "decides",
 };
 
 /**
@@ -91,6 +93,7 @@ export function createCapabilityToken(flow: string, declared?: Effects): Capabil
     secret: new Set(effects.secrets ?? []),
     call: new Set(effects.calls ?? []),
     fetch: new Set(effects.fetches ?? []),
+    decide: new Set(effects.decides ?? []),
   };
 
   return {