okengine 0.23.0 → 0.23.2

package/src/kernel/auto-cache.test.ts

@@ -9,6 +9,7 @@ import { gate } from "../elements/gate.ts";
 import { field, id, now, store } from "../elements/store.ts";
 import { createTestApp, type TestApiCall, type TestApp } from "../test/create-test-app.ts";
 import { isStoreResourceRef } from "../elements/store/cache.ts";
+import type { Effects } from "../manifest/types.ts";
 import { oke } from "./app.ts";
 import { resetNoEffectsWarnForTests } from "./boot.ts";
 import { flow, resetFlowSeq } from "./flow.ts";
@@ -56,6 +57,7 @@ describe("automatic tier-1 cache from effects", () => {
     const app = oke({
       name: "auto-cache",
       stores: [db],
+      cache: { auto: true },
       gate: { policies: [gate.public] },
     }).adopt({ list });
     const t = await createTestApp(app, { capability: "open" });
@@ -88,6 +90,7 @@ describe("automatic tier-1 cache from effects", () => {
     const app = oke({
       name: "auto-cache-execute",
       stores: [db],
+      cache: { auto: true },
       gate: { policies: [gate.public] },
     }).adopt({ list });
     const t = await createTestApp(app, { capability: "open" });
@@ -156,6 +159,7 @@ describe("automatic tier-1 cache from effects", () => {
     const app = oke({
       name: "auto-cache-ledger",
       stores: [db],
+      cache: { auto: true },
       gate: { policies: [gate.public] },
     }).adopt({ list });
     const t = await createTestApp(app, { capability: "open" });
@@ -207,6 +211,7 @@ describe("automatic tier-1 cache from effects", () => {
     const app = oke({
       name: "auto-cache-inv",
       stores: [db],
+      cache: { auto: true },
       gate: { policies: [gate.public] },
     }).adopt({ list, create });
     const t = await createTestApp(app, { capability: "open" });
@@ -249,6 +254,7 @@ describe("automatic tier-1 cache from effects", () => {
     const app = oke({
       name: "auto-cache-ledger-inv",
       stores: [db],
+      cache: { auto: true },
       gate: { policies: [gate.public] },
     }).adopt({ list, create });
     const t = await createTestApp(app, { capability: "open" });
@@ -261,4 +267,226 @@ describe("automatic tier-1 cache from effects", () => {
     expect(lists).toBe(2);
     await t.close();
   });
+
+  test("omitted cache caches a pure store read", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const db = store.sql("app", { schema: { notes } });
+    let lists = 0;
+    const list = on(
+      http.get("/notes").public(),
+      flow("notes.list", {
+        effects: { reads: ["sql:notes"] },
+        do: () => {
+          lists += 1;
+          return [{ id: "n1", title: "Harbor" }];
+        },
+      }),
+    );
+    const app = oke({
+      name: "auto-cache-default-on",
+      stores: [db],
+      gate: { policies: [gate.public] },
+    }).adopt({ list });
+    const t = await createTestApp(app, { capability: "open" });
+    const notesApi = requireNotesApi(t);
+    await notesApi.list({});
+    await notesApi.list({});
+    expect(lists).toBe(1);
+    await t.close();
+  });
+
+  test("cache.auto false turns automatic caching off", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const db = store.sql("app", { schema: { notes } });
+    let lists = 0;
+    const list = on(
+      http.get("/notes").public(),
+      flow("notes.list", {
+        effects: { reads: ["sql:notes"] },
+        do: () => {
+          lists += 1;
+          return [{ id: "n1", title: "Harbor" }];
+        },
+      }),
+    );
+    const app = oke({
+      name: "auto-cache-app-off",
+      stores: [db],
+      cache: { auto: false },
+      gate: { policies: [gate.public] },
+    }).adopt({ list });
+    const t = await createTestApp(app, { capability: "open" });
+    const notesApi = requireNotesApi(t);
+    await notesApi.list({});
+    await notesApi.list({});
+    expect(lists).toBe(2);
+    await t.close();
+  });
+
+  test("cache: true opts one flow in without the app switch", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const db = store.sql("app", { schema: { notes } });
+    let lists = 0;
+    const list = on(
+      http.get("/notes", { out: z.array(NoteOut) }).public(),
+      flow("notes.list", {
+        cache: true,
+        effects: { reads: ["sql:notes"] },
+        do: () => {
+          lists += 1;
+          return [{ id: "n1", title: "Harbor" }];
+        },
+      }),
+    );
+    const app = oke({
+      name: "auto-cache-flow-opt-in",
+      stores: [db],
+      gate: { policies: [gate.public] },
+    }).adopt({ list });
+    const t = await createTestApp(app, { capability: "open" });
+    const notesApi = requireNotesApi(t);
+    await notesApi.list({});
+    await notesApi.list({});
+    expect(lists).toBe(1);
+    await t.close();
+  });
+
+  const sideEffects = [
+    { kind: "emit", effects: { reads: ["sql:notes"], emits: ["note.created"] } },
+    { kind: "send", effects: { reads: ["sql:notes"], sends: ["welcome"] } },
+    { kind: "fetch", effects: { reads: ["sql:notes"], fetches: ["api.example.com"] } },
+    { kind: "secret", effects: { reads: ["sql:notes"], secrets: ["stripe"] } },
+    { kind: "ask", effects: { reads: ["sql:notes"], asks: ["summarize"] } },
+    { kind: "decide", effects: { reads: ["sql:notes"], decides: ["route"] } },
+    { kind: "call", effects: { reads: ["sql:notes"], calls: ["notes.create"] } },
+  ] satisfies readonly { kind: string; effects: Effects }[];
+
+  for (const side of sideEffects) {
+    test(`${side.kind} effects run the handler on every call`, async () => {
+      resetBindings();
+      resetFlowSeq();
+      const db = store.sql("app", { schema: { notes } });
+      let lists = 0;
+      const list = on(
+        http.get("/notes").public(),
+        flow("notes.list", {
+          effects: side.effects,
+          do: () => {
+            lists += 1;
+            return [{ id: "n1", title: "Harbor" }];
+          },
+        }),
+      );
+      const app = oke({
+        name: `auto-cache-${side.kind}`,
+        stores: [db],
+        cache: { auto: true },
+        gate: { policies: [gate.public] },
+      }).adopt({ list });
+      const t = await createTestApp(app, { capability: "open" });
+      const notesApi = requireNotesApi(t);
+      await notesApi.list({});
+      await notesApi.list({});
+      expect(lists).toBe(2);
+      await t.close();
+    });
+  }
+
+  test("a ledgered call beside a store read is not cached", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const db = store.sql("app", { schema: { notes } });
+    let lists = 0;
+    const list = on(
+      http.get("/notes", { out: z.array(NoteOut) }).public(),
+      flow("notes.list", {
+        do: async (_input, fx) => {
+          lists += 1;
+          await fx.store(db).select().from(notes);
+          await fx.call("notes.missing", {});
+          return [{ id: "n1", title: "Harbor" }];
+        },
+      }),
+    );
+    const app = oke({
+      name: "auto-cache-ledger-call",
+      stores: [db],
+      cache: { auto: true },
+      gate: { policies: [gate.public] },
+    }).adopt({ list });
+    const t = await createTestApp(app, { capability: "open" });
+    const notesApi = requireNotesApi(t);
+    await notesApi.list({});
+    await notesApi.list({});
+    expect(lists).toBe(2);
+    await t.close();
+  });
+
+  test("two tenants do not share a cache hit", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const db = store.sql("app", { schema: { notes } });
+    let lists = 0;
+    const list = on(
+      http.get("/notes").public(),
+      flow("notes.list", {
+        effects: { reads: ["sql:notes"] },
+        do: () => {
+          lists += 1;
+          return [{ id: "n1", title: "Harbor" }];
+        },
+      }),
+    );
+    const app = oke({
+      name: "auto-cache-tenant",
+      stores: [db],
+      cache: { auto: true },
+      gate: { policies: [gate.public] },
+    }).adopt({ list });
+    const t = await createTestApp(app, { capability: "open" });
+    const trigger = list.triggers[0];
+    if (trigger === undefined) throw new Error("notes.list has no trigger");
+    await app.execute(list, {}, trigger, { tenant: { id: "ta" } });
+    await app.execute(list, {}, trigger, { tenant: { id: "ta" } });
+    expect(lists).toBe(1);
+    await app.execute(list, {}, trigger, { tenant: { id: "tb" } });
+    expect(lists).toBe(2);
+    await t.close();
+  });
+
+  test("two locales do not share a cache hit", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const db = store.sql("app", { schema: { notes } });
+    let lists = 0;
+    const list = on(
+      http.get("/notes").public(),
+      flow("notes.list", {
+        effects: { reads: ["sql:notes"] },
+        do: () => {
+          lists += 1;
+          return [{ id: "n1", title: "Harbor" }];
+        },
+      }),
+    );
+    const app = oke({
+      name: "auto-cache-locale",
+      stores: [db],
+      cache: { auto: true },
+      config: { i18n: { locales: ["en", "ar"], default: "en" } },
+      gate: { policies: [gate.public] },
+    }).adopt({ list });
+    const t = await createTestApp(app, { capability: "open" });
+    const trigger = list.triggers[0];
+    if (trigger === undefined) throw new Error("notes.list has no trigger");
+    await app.execute(list, {}, trigger, { locale: "en" });
+    await app.execute(list, {}, trigger, { locale: "en" });
+    expect(lists).toBe(1);
+    await app.execute(list, {}, trigger, { locale: "ar" });
+    expect(lists).toBe(2);
+    await t.close();
+  });
 });

package/src/kernel/auto-registry.test.ts

@@ -285,7 +285,11 @@ describe("oke() auto-registry — stores/secrets/signals/clocks/gates/channel.te
     });
 
     const res = await app.fetch(
-      new Request("http://127.0.0.1/ai-ping", { method: "POST", body: "{}" }),
+      new Request("http://127.0.0.1/ai-ping", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
     );
     expect(res.status).toBe(200);
     const json = (await res.json()) as { data: { summary: string } };

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

@@ -4,6 +4,8 @@
 
 import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import { CHANNEL_EMAIL_DEFAULTS, CHANNEL_SMS_DEFAULTS } from "../../config/driver-defaults.ts";
+import { sharedPostgresClient, toPostgresParams } from "../../drivers/postgres.ts";
+import type { PostgresClientLike } from "../../drivers/postgres.ts";
 import { openConsoleChannel } from "../../drivers/channel-console.ts";
 import { openMsegatChannel } from "../../drivers/channel-msegat.ts";
 import { openResendChannel } from "../../drivers/channel-resend.ts";
@@ -16,8 +18,59 @@ import { openUnifonicChannel } from "../../drivers/channel-unifonic.ts";
 import { openWaCloudChannel } from "../../drivers/channel-wa-cloud.ts";
 import type { ChannelDriver, ChannelOpenOptions } from "../../drivers/channel-types.ts";
 import { createChannelRuntime, type ChannelRuntime } from "../../elements/channel.ts";
+import {
+  openPostgresChannelLedger,
+  type ChannelLedgerSql,
+  type PostgresChannelLedger,
+} from "../../elements/channel/sql-ledger.ts";
 import type { BootOptions } from "../boot.ts";
 
+/**
+ * Query/exec wrapper over the shared Bun.SQL pool.
+ *
+ * @param client - Shared postgres client
+ */
+function asChannelSql(client: PostgresClientLike): ChannelLedgerSql {
+  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 };
+    },
+  };
+}
+
+/**
+ * Durable ledger when a SQL URL is set outside `test`.
+ * Injected stores win. `test` stays in memory.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+async function maybeLedger(
+  options: BootOptions,
+  env: ConfigEnv,
+): Promise<PostgresChannelLedger | undefined> {
+  if (env === "test") return undefined;
+  if (options.channel?.suppression && options.channel.receipts) return undefined;
+  const url = process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL;
+  if (!url) return undefined;
+  return openPostgresChannelLedger(asChannelSql(sharedPostgresClient(url)));
+}
+
 /**
  * Construct a Channel runtime (console inbox default).
  *
@@ -29,16 +82,24 @@ import type { BootOptions } from "../boot.ts";
  * @param now - Clock
  * @param docker - Prefer compose SMTP when active
  */
-export function bindChannel(
+export async function bindChannel(
   options: BootOptions,
   env: ConfigEnv,
   now: () => number,
   docker = false,
-): ChannelRuntime {
+): Promise<ChannelRuntime> {
+  const ledger = await maybeLedger(options, env);
   return createChannelRuntime({
     ...(options.channel ?? {}),
     drivers: options.channel?.drivers ?? defaultDrivers(options, env, docker),
     now,
+    ...(ledger
+      ? {
+          suppression: options.channel?.suppression ?? ledger.suppression,
+          receipts: options.channel?.receipts ?? ledger.receipts,
+          refresh: () => ledger.reload(),
+        }
+      : {}),
   });
 }
 

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,23 @@
 
 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 {
+  POSTGRES_SIGNAL_DEFAULT_LAG_MS,
+  openPostgresSignal,
+  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 +44,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 +107,40 @@ 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: {
+          id: postgresSignalDriver.id,
+          open: (openOptions) =>
+            openPostgresSignal({
+              ...openOptions,
+              lagMs: injected ? undefined : POSTGRES_SIGNAL_DEFAULT_LAG_MS,
+            }),
+        },
+        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.ts

@@ -24,6 +24,7 @@ import { postgresDriver } from "../../drivers/postgres.ts";
 import { redisDriver } from "../../drivers/redis.ts";
 import { s3Driver } from "../../drivers/s3.ts";
 import type { FilesDriver, IndexDriver, KvDriver, SqlDriver } from "../../drivers/types.ts";
+import { bunRedisCacheClient } from "../../elements/store/cache-bus.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";
@@ -171,7 +172,14 @@ export function bindStore(
   const autoPush = resolveAutoPush(options);
   const domainDdl = resolveDomainDdlMode(env, autoPush);
 
-  const store = createStoreRuntime({
+  let store!: StoreRuntime;
+  const cacheBus =
+    kvId === "redis" && kvUrl
+      ? { kind: "redis" as const, redis: bunRedisCacheClient(kvUrl) }
+      : sqlId === "postgres" && sqlUrl
+        ? { kind: "postgres" as const, sql: () => store.primarySql() }
+        : undefined;
+  store = createStoreRuntime({
     drivers: {
       sql: sqlDriverFor(sqlId),
       kv: kvDriverFor(kvId),
@@ -183,6 +191,13 @@ export function bindStore(
     files: filesBindings,
     index: indexBindings,
     now,
+    ...(options.cache?.maxEntries !== undefined
+      ? { cacheMaxEntries: options.cache.maxEntries }
+      : {}),
+    ...(options.cache?.defaultTtlMs !== undefined
+      ? { cacheDefaultTtlMs: options.cache.defaultTtlMs }
+      : {}),
+    ...(cacheBus ? { cacheBus } : {}),
     domainDdl,
     sqlUrl,
   });

package/src/kernel/boot.test.ts

@@ -285,8 +285,8 @@ describe("boot — cron autostart via real timer loop", () => {
     // Drive the wall-clock interval that boot installed — not clock.advance /
     // runNow / dispatchEvery (those prove the harness, not autostart).
     jest.advanceTimersByTime(1000);
-    // Interval callback does `void clock.tick()`; drain the async store walk.
-    for (let i = 0; i < 50; i++) await Promise.resolve();
+    // The tick is guarded and async. Wait until it settles, but not forever.
+    for (let i = 0; i < 50 && ran < 1; i++) await Promise.resolve();
 
     expect(ran).toBeGreaterThanOrEqual(1);