okengine 0.22.0 → 0.23.1

package/src/drivers/memory.ts

@@ -503,7 +503,7 @@ function createMemorySqlConnection(role: "primary" | "replica"): SqlConnection {
       }
 
       const create =
-        /^CREATE\s+TABLE\s+IF\s+NOT\s+EXISTS\s+("?[a-zA-Z_][a-zA-Z0-9_]*"?)\s*\((.+)\)\s*$/i.exec(
+        /^CREATE\s+TABLE\s+IF\s+NOT\s+EXISTS\s+("?[a-zA-Z_][a-zA-Z0-9_]*"?)\s*\((.+)\)\s*$/is.exec(
           text,
         );
       if (create) {
@@ -519,6 +519,26 @@ function createMemorySqlConnection(role: "primary" | "replica"): SqlConnection {
         return { changes: 0 };
       }
 
+      const addColumn =
+        /^ALTER\s+TABLE\s+("?[a-zA-Z_][a-zA-Z0-9_]*"?)\s+ADD\s+COLUMN\s+IF\s+NOT\s+EXISTS\s+("?[a-zA-Z_][a-zA-Z0-9_]*"?)\b/is.exec(
+          text,
+        );
+      if (addColumn) {
+        const name = parseIdent(addColumn[1]!);
+        const column = parseIdent(addColumn[2]!);
+        const table = tables.get(name);
+        if (table && !table.columns.includes(column)) table.columns.push(column);
+        return { changes: 0 };
+      }
+
+      // Scan results do not depend on indexes. Identity and vault DDL still
+      // issue CREATE INDEX IF NOT EXISTS on the shared memory connection.
+      const createIndex =
+        /^CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+NOT\s+EXISTS\s+)?(?:"?[a-zA-Z_][a-zA-Z0-9_]*"?)\s+ON\s+/is.exec(
+          text,
+        );
+      if (createIndex) return { changes: 0 };
+
       const insert =
         /^INSERT\s+INTO\s+("?[a-zA-Z_][a-zA-Z0-9_]*"?)\s*\(([^)]+)\)\s*VALUES\s*\(([^)]+)\)\s*$/i.exec(
           text,

package/src/drivers/pg-rls.test.ts

@@ -5,6 +5,7 @@ import {
   buildRlsIdentityPreludeSql,
   emitPgPolicySource,
   formatPolicyRole,
+  OKE_PG_STAT_STATEMENTS_SQL,
   OKE_RLS_HELPER_STATEMENTS,
   OKE_RLS_ROLE,
   parseSqlPolicySpec,
@@ -149,6 +150,36 @@ describe("OKE_RLS_HELPER_STATEMENTS", () => {
     expect(hasScope).not.toMatch(/jsonb\s+\?/);
   });
 
+  test("initial oke SQL creates pg_stat_statements before helpers", async () => {
+    const ran: string[] = [];
+    const { installOkeRlsHelpers } = await import("./pg-rls.ts");
+    await installOkeRlsHelpers(async (sql) => {
+      ran.push(sql);
+      if (sql.startsWith("CREATE EXTENSION")) return;
+      if (sql.includes("pg_vault") || sql.includes("vault.")) {
+        throw new Error("stop before vault attach");
+      }
+    }).catch(() => undefined);
+    expect(ran[0]).toBe(OKE_PG_STAT_STATEMENTS_SQL);
+    expect(ran[1]).toBe(OKE_RLS_HELPER_STATEMENTS[0]);
+  });
+
+  test("a rejected pg_stat_statements create still installs helpers", async () => {
+    const ran: string[] = [];
+    const { installOkeRlsHelpers } = await import("./pg-rls.ts");
+    await installOkeRlsHelpers(async (sql) => {
+      ran.push(sql);
+      if (sql.startsWith("CREATE EXTENSION")) {
+        throw new Error('extension "pg_stat_statements" is not available');
+      }
+      if (sql.includes("CREATE OR REPLACE FUNCTION oke.gate")) {
+        throw new Error("stop");
+      }
+    }).catch(() => undefined);
+    expect(ran[0]).toBe(OKE_PG_STAT_STATEMENTS_SQL);
+    expect(ran.some((sql) => sql.includes("CREATE SCHEMA IF NOT EXISTS oke"))).toBe(true);
+  });
+
   test("pins search_path to public so schema oke is not the table home", () => {
     expect(OKE_RLS_HELPER_STATEMENTS).toContain("SET search_path TO public, oke");
     expect(

package/src/drivers/pg-rls.ts

@@ -135,12 +135,27 @@ $oke_app_search_path$`,
  */
 export const OKE_RLS_HELPER_SQL = `${OKE_RLS_HELPER_STATEMENTS.join(";\n")};`;
 
+/**
+ * Enable query telemetry on postgres. Preload is still required
+ * (`shared_preload_libraries=pg_stat_statements`). PGlite and Cockroach
+ * reject this; callers swallow that failure so the rest of the oke SQL runs.
+ */
+export const OKE_PG_STAT_STATEMENTS_SQL = "CREATE EXTENSION IF NOT EXISTS pg_stat_statements";
+
 /**
  * Install `oke.*` helpers one statement at a time.
  *
+ * `pg_stat_statements` is created first when the engine allows it, so Store
+ * performance does not depend on a later manual `CREATE EXTENSION`.
+ *
  * @param exec - Statement runner
  */
 export async function installOkeRlsHelpers(exec: (sql: string) => Promise<unknown>): Promise<void> {
+  try {
+    await exec(OKE_PG_STAT_STATEMENTS_SQL);
+  } catch {
+    // Not preloaded, or this engine has no pg_stat_statements (pglite, cockroach).
+  }
   for (const stmt of OKE_RLS_HELPER_STATEMENTS) {
     await exec(stmt);
   }

package/src/drivers/postgres.test.ts

@@ -38,6 +38,15 @@ describe("toPostgresParams", () => {
 });
 
 describe("closeSharedPostgresClients", () => {
+  test("a different max is a different pool on the same URL", () => {
+    const url = "postgres://127.0.0.1:9/oke-pool-max-shared-test";
+    const small = sharedPostgresClient(url, 8);
+    const large = sharedPostgresClient(url, 20);
+    expect(large).not.toBe(small);
+    expect(sharedPostgresClient(url, 20)).toBe(large);
+    expect(sharedPostgresClient(url)).toBe(small);
+  });
+
   test("drops cached pools so the next checkout is a new client", async () => {
     const url = "postgres://127.0.0.1:9/oke-close-shared-test";
     const first = sharedPostgresClient(url);

package/src/drivers/postgres.ts

@@ -43,7 +43,27 @@ type SharedPostgresEntry = {
   readonly guarded: PostgresClientLike;
 };
 
-const sharedClients = new Map<string, SharedPostgresEntry>();
+/**
+ * Process-wide pool registry.
+ *
+ * `bun --hot` re-evaluates this module on each save. A module-local `Map`
+ * would drop the only handle to the previous Bun.SQL pools and leave them
+ * connected. PgDog then queues every checkout — Console login included —
+ * until its server pool times out.
+ */
+const SHARED_POSTGRES_CLIENTS = Symbol.for("oke.sharedPostgresClients");
+
+function sharedClientMap(): Map<string, SharedPostgresEntry> {
+  const g = globalThis as typeof globalThis & {
+    [SHARED_POSTGRES_CLIENTS]?: Map<string, SharedPostgresEntry>;
+  };
+  let map = g[SHARED_POSTGRES_CLIENTS];
+  if (!map) {
+    map = new Map();
+    g[SHARED_POSTGRES_CLIENTS] = map;
+  }
+  return map;
+}
 
 /**
  * When true, shared pools stay closed and every query fails fast — no Bun.SQL
@@ -160,21 +180,38 @@ function guardSharedPostgresClient(raw: PostgresClientLike): PostgresClientLike
 }
 
 /**
- * One Bun.SQL pool per URL for store / journal / clock / vault / console.
+ * Bun.SQL pool size. Unset, non-finite, or below 1 keeps {@link POSTGRES_POOL_MAX}.
+ * A configured max is not capped — callers that need a larger pool ask for it.
+ *
+ * @param poolMax - Requested `max`
+ */
+function postgresPoolMax(poolMax: number | undefined): number {
+  if (poolMax === undefined || !Number.isFinite(poolMax) || poolMax < 1) return POSTGRES_POOL_MAX;
+  return Math.floor(poolMax);
+}
+
+/**
+ * One Bun.SQL pool per URL and `max` for store / journal / clock / vault / console.
  *
  * Returns a pause-aware client — holders (including fleet store wrappers)
  * fail soft after {@link pauseSharedPostgresClients} instead of reconnecting.
  *
  * @param url - Connection URL
+ * @param poolMax - Bun.SQL `max`. Omitted uses {@link POSTGRES_POOL_MAX}. A
+ * different max is a different pool — a store pin of 20 must not reuse a
+ * pool another subsystem already opened at the default.
  */
-export function sharedPostgresClient(url?: string): PostgresClientLike {
+export function sharedPostgresClient(url?: string, poolMax?: number): PostgresClientLike {
   assertSharedPostgresReady();
-  const key = resolvePostgresUrl(url);
-  const existing = sharedClients.get(key);
+  const resolved = resolvePostgresUrl(url);
+  const max = postgresPoolMax(poolMax);
+  const key = `${resolved}\0${String(max)}`;
+  const clients = sharedClientMap();
+  const existing = clients.get(key);
   if (existing) return existing.guarded;
-  const raw = new Bun.SQL(key, { max: POSTGRES_POOL_MAX }) as unknown as PostgresClientLike;
+  const raw = new Bun.SQL(resolved, { max }) as unknown as PostgresClientLike;
   const guarded = guardSharedPostgresClient(raw);
-  sharedClients.set(key, { raw, guarded });
+  clients.set(key, { raw, guarded });
   return guarded;
 }
 
@@ -185,8 +222,8 @@ export function sharedPostgresClient(url?: string): PostgresClientLike {
  * not stop Console from opening a fresh pool on the next poll.
  */
 export async function closeSharedPostgresClients(): Promise<void> {
-  const clients = [...sharedClients.values()];
-  sharedClients.clear();
+  const clients = [...sharedClientMap().values()];
+  sharedClientMap().clear();
   await Promise.all(
     clients.map(async (entry) => {
       try {
@@ -283,12 +320,13 @@ export async function connectPostgres(options: SqlConnectOptions = {}): Promise<
   // must not share a pooled client — Bun raises ERR_POSTGRES_UNSAFE_TRANSACTION
   // when raw statements interleave with open transaction state on the shared
   // pool. Opt in explicitly; default behavior is unchanged.
-  const dedicated = !injected && options.pool?.max === 1;
+  const requestedMax = options.pool?.max;
+  const dedicated = !injected && requestedMax === 1;
   const client =
     injected ??
     (dedicated
       ? dedicatedPostgresClient(resolvePostgresUrl(options.url))
-      : sharedPostgresClient(options.url));
+      : sharedPostgresClient(options.url, requestedMax));
   return wrapPostgresClient(client, role, {
     shared: injected === undefined && !dedicated,
     ...(options.url !== undefined ? { url: options.url } : {}),

package/src/drivers/signal-compete.test.ts

@@ -0,0 +1,234 @@
+/**
+ * Two consumers, one bus: postgres SKIP LOCKED and redis consumer groups.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { signal } from "../elements/signal.ts";
+import {
+  openPostgresChannelLedger,
+  type ChannelLedgerSql,
+} from "../elements/channel/sql-ledger.ts";
+import { createPostgresSignalFake, openPostgresSignal } from "./signal-postgres.ts";
+import {
+  createBunSignalRedisClient,
+  createSignalRedisFake,
+  openRedisSignal,
+} from "./signal-redis.ts";
+
+function decls(name: string, retries = 3) {
+  const decl = signal.once(name, { retries, deadLetter: true });
+  return new Map([[decl.name, decl]]);
+}
+
+describe("postgres signal competing consumers", () => {
+  test("one message is delivered once across two buses", async () => {
+    const sql = createPostgresSignalFake();
+    const name = "order-placed";
+    const a = await openPostgresSignal({ signals: decls(name), sql });
+    const b = await openPostgresSignal({ signals: decls(name), sql });
+    const got: string[] = [];
+    await a.subscribe(name, "a", async () => {
+      got.push("a");
+    });
+    await b.subscribe(name, "b", async () => {
+      got.push("b");
+    });
+    await a.emit(name, { id: "1" });
+    await Bun.sleep(5);
+    await a.drain();
+    await b.drain();
+    expect(got).toHaveLength(1);
+    await a.close();
+    await b.close();
+  });
+});
+
+describe("redis streams competing consumers", () => {
+  test("one message is delivered once across two groups", async () => {
+    const redis = createSignalRedisFake();
+    const name = "order-placed";
+    const shared = { signals: decls(name), redis, compete: true as const };
+    const a = await openRedisSignal({ ...shared, consumerId: "a" });
+    const b = await openRedisSignal({ ...shared, consumerId: "b" });
+    const got: string[] = [];
+    await a.subscribe(name, "a", async () => {
+      got.push("a");
+    });
+    await b.subscribe(name, "b", async () => {
+      got.push("b");
+    });
+    await a.emit(name, { id: "1" });
+    await a.drain();
+    await b.drain();
+    expect(got).toHaveLength(1);
+    await a.close();
+    await b.close();
+  });
+
+  test("a failed handler leaves the entry pending for redelivery", async () => {
+    const redis = createSignalRedisFake();
+    const name = "flaky";
+    const bus = await openRedisSignal({
+      signals: decls(name, 2),
+      redis,
+      compete: true,
+      consumerId: "a",
+    });
+    let calls = 0;
+    await bus.subscribe(name, "a", async () => {
+      calls += 1;
+      if (calls === 1) throw new Error("boom");
+    });
+    await bus.emit(name, { id: "1" });
+    await bus.drain();
+    expect(calls).toBe(1);
+    await bus.drain();
+    expect(calls).toBe(2);
+    await bus.close();
+  });
+
+  test("another consumer reclaims an unacked entry", async () => {
+    const redis = createSignalRedisFake();
+    const name = "handoff";
+    const shared = { signals: decls(name, 3), redis, compete: true as const };
+    const a = await openRedisSignal({ ...shared, consumerId: "a" });
+    const b = await openRedisSignal({ ...shared, consumerId: "b" });
+    let aCalls = 0;
+    const got: string[] = [];
+    await a.subscribe(name, "a", async () => {
+      aCalls += 1;
+      throw new Error("down");
+    });
+    await b.subscribe(name, "b", async () => {
+      got.push("b");
+    });
+    await a.emit(name, { id: "1" });
+    await a.drain();
+    await b.drain();
+    expect(aCalls).toBe(1);
+    expect(got).toEqual(["b"]);
+    await a.close();
+    await b.close();
+  });
+
+  test.skipIf(!process.env.REDIS_URL)("REDIS_URL: two clients ack once", async () => {
+    const url = process.env.REDIS_URL;
+    const name = `oke-compete-${Date.now()}`;
+    const redisA = createBunSignalRedisClient(url);
+    const redisB = createBunSignalRedisClient(url);
+    const a = await openRedisSignal({
+      signals: decls(name),
+      redis: redisA,
+      compete: true,
+      consumerId: "a",
+    });
+    const b = await openRedisSignal({
+      signals: decls(name),
+      redis: redisB,
+      compete: true,
+      consumerId: "b",
+    });
+    const got: string[] = [];
+    await a.subscribe(name, "a", async () => {
+      got.push("a");
+    });
+    await b.subscribe(name, "b", async () => {
+      got.push("b");
+    });
+    await a.emit(name, { id: "1" });
+    await a.drain();
+    await b.drain();
+    expect(got).toHaveLength(1);
+    await a.close();
+    await b.close();
+  });
+});
+
+function memoryLedgerSql(): ChannelLedgerSql {
+  const consent = new Map<string, { subject: string; medium: string; at: number }>();
+  const bounce = new Map<string, { subject: string; medium: string; at: number }>();
+  const receipts = new Map<string, string>();
+
+  function pair(params: readonly unknown[]): string {
+    return `${String(params[0])}\0${String(params[1])}`;
+  }
+
+  return {
+    async query(sql) {
+      if (sql.includes("oke_channel_consent")) {
+        return [...consent.values()];
+      }
+      if (sql.includes("oke_channel_bounce")) {
+        return [...bounce.values()];
+      }
+      if (sql.includes("oke_channel_receipt")) {
+        return [...receipts.entries()].map(([id, body]) => ({ id, body }));
+      }
+      return [];
+    },
+    async exec(sql, params = []) {
+      if (sql.startsWith("CREATE")) return { changes: 0 };
+      if (sql.includes("INSERT INTO oke_channel_consent")) {
+        consent.set(pair(params), {
+          subject: String(params[0]),
+          medium: String(params[1]),
+          at: Number(params[2]),
+        });
+        return { changes: 1 };
+      }
+      if (sql.includes("DELETE FROM oke_channel_consent")) {
+        consent.delete(pair(params));
+        return { changes: 1 };
+      }
+      if (sql.includes("INSERT INTO oke_channel_bounce")) {
+        bounce.set(pair(params), {
+          subject: String(params[0]),
+          medium: String(params[1]),
+          at: Number(params[2]),
+        });
+        return { changes: 1 };
+      }
+      if (sql.includes("DELETE FROM oke_channel_bounce")) {
+        bounce.delete(pair(params));
+        return { changes: 1 };
+      }
+      if (sql.includes("INSERT INTO oke_channel_receipt")) {
+        receipts.set(String(params[0]), String(params[1]));
+        return { changes: 1 };
+      }
+      if (sql.includes("UPDATE oke_channel_receipt")) {
+        receipts.set(String(params[1]), String(params[0]));
+        return { changes: 1 };
+      }
+      return { changes: 0 };
+    },
+  };
+}
+
+describe("channel ledger across instances", () => {
+  test("consent and suppression written on A are visible to B", async () => {
+    const sql = memoryLedgerSql();
+    const a = await openPostgresChannelLedger(sql);
+    const b = await openPostgresChannelLedger(sql);
+    a.suppression.optOut("a@b.c", "email");
+    a.suppression.addPriorBounce("c@d.e", "sms");
+    a.receipts.record({
+      id: "r1",
+      template: "note",
+      to: "a@b.c",
+      medium: "email",
+      status: "sent",
+      attempts: [],
+      at: 1,
+    });
+    await a.flush();
+    await b.reload();
+    expect(b.consent.isOptedOut("a@b.c", "email")).toBe(true);
+    expect(b.suppression.isSuppressed("c@d.e", "sms")).toEqual({
+      suppressed: true,
+      reason: "prior-bounce",
+    });
+    expect(b.receipts.all()).toHaveLength(1);
+    expect(b.receipts.all()[0]?.id).toBe("r1");
+  });
+});

package/src/drivers/signal-postgres.ts

@@ -2,7 +2,8 @@
  * `postgres` signal driver — transactional emit (dual-write fix).
  *
  * `fx.emit` inserts into the outbox on the caller's connection. Consumers
- * claim with `FOR UPDATE SKIP LOCKED`; wakeups use `LISTEN` / `NOTIFY`.
+ * claim with `FOR UPDATE SKIP LOCKED`. Wakeups use `LISTEN` / `NOTIFY` when
+ * the client has them; otherwise the boot scheduler polls `drain`.
  */
 
 import type { SignalDecl } from "../elements/signal/declare.ts";
@@ -65,18 +66,19 @@ export interface PostgresSignalSql {
   begin<T>(fn: (sql: PostgresSignalSql) => Promise<T>): Promise<T>;
   /**
    * LISTEN channel; returns unsubscribe.
+   * Optional — Bun.SQL has no listen API. Omit it and poll {@link SignalBus.drain}.
    *
    * @param channel - Channel name
    * @param onNotify - Payload callback
    */
-  listen(channel: string, onNotify: (payload: string) => void): Promise<() => void>;
+  listen?(channel: string, onNotify: (payload: string) => void): Promise<() => void>;
   /**
-   * NOTIFY channel.
+   * NOTIFY channel. Optional when the client cannot notify.
    *
    * @param channel - Channel name
    * @param payload - Payload
    */
-  notify(channel: string, payload: string): Promise<void>;
+  notify?(channel: string, payload: string): Promise<void>;
   close(): Promise<void>;
 }
 
@@ -205,6 +207,9 @@ export function createPostgresSignalFake(options?: {
           return true;
         });
         if (!row) return [];
+        // Hold the row before yielding so a concurrent claim skips it.
+        row.status = "inflight";
+        if (row.locked_by === null) row.locked_by = "claimed";
         return [{ ...row }];
       }
 
@@ -565,9 +570,18 @@ export async function openPostgresSignal(options: SignalOpenOptions): Promise<Si
     return n;
   }
 
-  unlisten = await sql.listen(CHANNEL, () => {
-    void drainQuiet();
-  });
+  if (typeof sql.listen === "function") {
+    unlisten = await sql.listen(CHANNEL, () => {
+      void drainQuiet();
+    });
+  } else if ((options.pollMs ?? 0) > 0) {
+    const timer = setInterval(() => {
+      void drainQuiet();
+    }, options.pollMs);
+    unlisten = () => {
+      clearInterval(timer);
+    };
+  }
 
   function requireDecl(name: string): SignalDecl {
     const decl = signals.get(name);
@@ -663,7 +677,9 @@ export async function openPostgresSignal(options: SignalOpenOptions): Promise<Si
             await insertEmit(tx, e.signal, e.payload, e.options);
           }
         });
-        await sql.notify(CHANNEL, "commit");
+        if (typeof sql.notify === "function") {
+          await sql.notify(CHANNEL, "commit");
+        }
       },
       async rollback() {
         if (finished) throw new Error("transaction finished");
@@ -827,20 +843,24 @@ export async function openPostgresSignal(options: SignalOpenOptions): Promise<Si
     for (const consumer of consumers) {
       const decl = signals.get(consumer.signal);
       if (decl?.delivery !== "once") continue;
-      const claimed = await sql.query(CLAIM_ONCE_SQL, [consumer.signal, t, t, t]);
-      if (claimed[0]) {
-        progress = true;
-        const row = claimed[0];
-        const attempts = Number(row.attempts) + 1;
+      const row = await sql.begin(async (tx) => {
+        const claimed = await tx.query(CLAIM_ONCE_SQL, [consumer.signal, t, t, t]);
+        const hit = claimed[0];
+        if (!hit) return undefined;
+        const attempts = Number(hit.attempts) + 1;
         const leaseExpiresAt = t + leaseMs;
-        await sql.exec(
+        await tx.exec(
           `UPDATE oke_signal_messages SET status = 'inflight', locked_by = ?, attempts = ?, lease_expires_at = ? WHERE id = ?`,
-          [consumer.subscriberId, attempts, leaseExpiresAt, row.id],
+          [consumer.subscriberId, attempts, leaseExpiresAt, hit.id],
         );
-        row.locked_by = consumer.subscriberId;
-        row.attempts = attempts;
-        row.status = "inflight";
-        row.lease_expires_at = leaseExpiresAt;
+        hit.locked_by = consumer.subscriberId;
+        hit.attempts = attempts;
+        hit.status = "inflight";
+        hit.lease_expires_at = leaseExpiresAt;
+        return hit;
+      });
+      if (row) {
+        progress = true;
         await deliverOnce(row, consumer);
       }
     }