okengine 0.23.0 → 0.23.1

package/src/elements/channel/sql-ledger.ts

@@ -0,0 +1,251 @@
+/**
+ * Postgres-backed consent, suppression, and receipt ledger.
+ *
+ * Reads are synchronous against a cache. Writes hit SQL and the cache.
+ * Call {@link PostgresChannelLedger.reload} on another instance to see them.
+ */
+
+import type { ChannelMedium } from "../../manifest/types.ts";
+import type { ConsentStore, OptOut } from "./consent.ts";
+import type { DeliveryReceipt, ReceiptLedger } from "./receipts.ts";
+import type { SuppressionEntry, SuppressionReason, SuppressionStore } from "./suppression.ts";
+
+/** SQL surface the channel ledger needs (`?` placeholders). */
+export interface ChannelLedgerSql {
+  /**
+   * Run a query and return rows.
+   *
+   * @param sql - Statement
+   * @param params - Bindings
+   */
+  query(sql: string, params?: readonly unknown[]): Promise<Record<string, unknown>[]>;
+  /**
+   * Run a statement.
+   *
+   * @param sql - Statement
+   * @param params - Bindings
+   */
+  exec(sql: string, params?: readonly unknown[]): Promise<{ changes: number }>;
+}
+
+/** Shared channel ledger (consent + suppression + receipts). */
+export interface PostgresChannelLedger {
+  readonly consent: ConsentStore;
+  readonly suppression: SuppressionStore;
+  readonly receipts: ReceiptLedger;
+  /** Wait for queued writes. */
+  flush(): Promise<void>;
+  /** Wait for queued writes, then replace the cache from SQL. */
+  reload(): Promise<void>;
+}
+
+const CONSENT = "oke_channel_consent";
+const BOUNCE = "oke_channel_bounce";
+const RECEIPT = "oke_channel_receipt";
+
+/**
+ * Open the ledger tables and load the current rows.
+ *
+ * @param sql - App SQL client
+ */
+export async function openPostgresChannelLedger(
+  sql: ChannelLedgerSql,
+): Promise<PostgresChannelLedger> {
+  await sql.exec(
+    `CREATE TABLE IF NOT EXISTS ${CONSENT} (subject TEXT NOT NULL, medium TEXT NOT NULL, at BIGINT NOT NULL, PRIMARY KEY (subject, medium))`,
+  );
+  await sql.exec(
+    `CREATE TABLE IF NOT EXISTS ${BOUNCE} (subject TEXT NOT NULL, medium TEXT NOT NULL, at BIGINT NOT NULL, PRIMARY KEY (subject, medium))`,
+  );
+  await sql.exec(`CREATE TABLE IF NOT EXISTS ${RECEIPT} (id TEXT PRIMARY KEY, body TEXT NOT NULL)`);
+
+  const consents: OptOut[] = [];
+  const bounces: OptOut[] = [];
+  const receipts: DeliveryReceipt[] = [];
+  let chain: Promise<void> = Promise.resolve();
+
+  function enqueue(work: () => Promise<void>): void {
+    chain = chain.then(work);
+  }
+
+  async function flush(): Promise<void> {
+    await chain;
+  }
+
+  function matches(rows: readonly OptOut[], subject: string, medium: ChannelMedium): boolean {
+    return rows.some(
+      (row) => row.subject === subject && (row.medium === "all" || row.medium === medium),
+    );
+  }
+
+  function remember(
+    rows: OptOut[],
+    subject: string,
+    medium: ChannelMedium | "all",
+    at: number,
+  ): void {
+    const idx = rows.findIndex((row) => row.subject === subject && row.medium === medium);
+    const next: OptOut = { subject, medium, at };
+    if (idx >= 0) rows[idx] = next;
+    else rows.push(next);
+  }
+
+  function forget(rows: OptOut[], subject: string, medium: ChannelMedium | "all"): void {
+    for (let i = rows.length - 1; i >= 0; i--) {
+      const row = rows[i]!;
+      if (row.subject === subject && row.medium === medium) rows.splice(i, 1);
+    }
+  }
+
+  const consent: ConsentStore = {
+    isOptedOut(subject, medium) {
+      return matches(consents, subject, medium);
+    },
+    optOut(subject, medium) {
+      const at = Date.now();
+      remember(consents, subject, medium, at);
+      enqueue(() =>
+        sql
+          .exec(
+            `INSERT INTO ${CONSENT} (subject, medium, at) VALUES (?, ?, ?) ON CONFLICT (subject, medium) DO UPDATE SET at = excluded.at`,
+            [subject, medium, at],
+          )
+          .then(() => undefined),
+      );
+    },
+    optIn(subject, medium) {
+      forget(consents, subject, medium);
+      enqueue(() =>
+        sql
+          .exec(`DELETE FROM ${CONSENT} WHERE subject = ? AND medium = ?`, [subject, medium])
+          .then(() => undefined),
+      );
+    },
+    list() {
+      return [...consents];
+    },
+  };
+
+  function reasonFor(
+    subject: string,
+    medium: ChannelMedium,
+  ):
+    | { readonly suppressed: true; readonly reason: SuppressionReason }
+    | { readonly suppressed: false } {
+    if (consent.isOptedOut(subject, medium)) return { suppressed: true, reason: "opted-out" };
+    if (matches(bounces, subject, medium)) return { suppressed: true, reason: "prior-bounce" };
+    return { suppressed: false };
+  }
+
+  const suppression: SuppressionStore = {
+    consent,
+    isSuppressed: reasonFor,
+    optOut(subject, medium) {
+      consent.optOut(subject, medium);
+    },
+    addPriorBounce(subject, medium) {
+      const at = Date.now();
+      remember(bounces, subject, medium, at);
+      enqueue(() =>
+        sql
+          .exec(
+            `INSERT INTO ${BOUNCE} (subject, medium, at) VALUES (?, ?, ?) ON CONFLICT (subject, medium) DO UPDATE SET at = excluded.at`,
+            [subject, medium, at],
+          )
+          .then(() => undefined),
+      );
+    },
+    clear(subject, medium) {
+      consent.optIn(subject, medium);
+      forget(bounces, subject, medium);
+      enqueue(() =>
+        sql
+          .exec(`DELETE FROM ${BOUNCE} WHERE subject = ? AND medium = ?`, [subject, medium])
+          .then(() => undefined),
+      );
+    },
+    list() {
+      const rows: SuppressionEntry[] = [];
+      for (const row of consents) {
+        rows.push({ subject: row.subject, medium: row.medium, reason: "opted-out", at: row.at });
+      }
+      for (const row of bounces) {
+        rows.push({ subject: row.subject, medium: row.medium, reason: "prior-bounce", at: row.at });
+      }
+      return rows;
+    },
+  };
+
+  const receiptLedger: ReceiptLedger = {
+    record(receipt) {
+      receipts.push(receipt);
+      enqueue(() =>
+        sql
+          .exec(`INSERT INTO ${RECEIPT} (id, body) VALUES (?, ?)`, [
+            receipt.id,
+            JSON.stringify(receipt),
+          ])
+          .then(() => undefined),
+      );
+    },
+    all() {
+      return [...receipts];
+    },
+    forTemplate(template) {
+      return receipts.filter((row) => row.template === template);
+    },
+    byMessageId(messageId) {
+      for (let i = receipts.length - 1; i >= 0; i--) {
+        const row = receipts[i]!;
+        if (row.messageId === messageId || row.id === messageId) return row;
+      }
+      return undefined;
+    },
+    updateStatus(messageId, patch) {
+      const idx = receipts.findIndex((row) => row.messageId === messageId || row.id === messageId);
+      if (idx < 0) return undefined;
+      const prev = receipts[idx]!;
+      const next: DeliveryReceipt = {
+        ...prev,
+        status: patch.status,
+        at: patch.at ?? prev.at,
+        ...(patch.error !== undefined ? { error: patch.error } : {}),
+      };
+      receipts[idx] = next;
+      enqueue(() =>
+        sql
+          .exec(`UPDATE ${RECEIPT} SET body = ? WHERE id = ?`, [JSON.stringify(next), next.id])
+          .then(() => undefined),
+      );
+      return next;
+    },
+  };
+
+  async function loadOptOuts(table: string, into: OptOut[]): Promise<void> {
+    const rows = await sql.query(`SELECT subject, medium, at FROM ${table}`);
+    into.length = 0;
+    for (const row of rows) {
+      into.push({
+        subject: String(row.subject),
+        medium: String(row.medium) as ChannelMedium | "all",
+        at: Number(row.at),
+      });
+    }
+  }
+
+  async function reload(): Promise<void> {
+    await flush();
+    await loadOptOuts(CONSENT, consents);
+    await loadOptOuts(BOUNCE, bounces);
+    const rows = await sql.query(`SELECT id, body FROM ${RECEIPT}`);
+    receipts.length = 0;
+    for (const row of rows) {
+      const parsed: unknown = JSON.parse(String(row.body));
+      if (parsed && typeof parsed === "object") receipts.push(parsed as DeliveryReceipt);
+    }
+  }
+
+  await reload();
+
+  return { consent, suppression, receipts: receiptLedger, flush, reload };
+}

package/src/elements/signal/runtime.ts

@@ -26,6 +26,12 @@ export interface CreateSignalRuntimeOptions {
   readonly sql?: unknown;
   readonly redis?: import("../../drivers/signal-types.ts").SignalRedisClientLike;
   readonly nats?: import("../../drivers/signal-types.ts").SignalNatsClientLike;
+  /** Forwarded to the driver. Postgres poll when `listen` is absent. */
+  readonly pollMs?: number;
+  /** Redis consumer-group consume for `once`. */
+  readonly compete?: boolean;
+  /** Redis consumer name. */
+  readonly consumerId?: string;
 }
 
 /** Signal runtime. */
@@ -106,6 +112,9 @@ export function createSignalRuntime(options: CreateSignalRuntimeOptions): Signal
         sql: options.sql,
         redis: options.redis,
         nats: options.nats,
+        pollMs: options.pollMs,
+        compete: options.compete,
+        consumerId: options.consumerId,
       });
       return bus;
     },

package/src/elements/signal.test.ts

@@ -267,6 +267,7 @@ describe("postgres transactional emit (dual-write fix)", () => {
     });
 
     const notified: string[] = [];
+    if (sql.listen === undefined) throw new Error("postgres fake has no listen");
     await sql.listen("oke_signal", (p) => {
       notified.push(p);
     });

package/src/elements/store/cache.test.ts

@@ -17,6 +17,7 @@ import {
   isInvalidatedByWrite,
   resolveCacheEffects,
   tier1DimsByResource,
+  tier1FlowDims,
   tier1KeysForReads,
   tier1Lookup,
 } from "./cache.ts";
@@ -79,21 +80,41 @@ describe("tier-1 cache — exact per-resource invalidation (path b)", () => {
 });
 
 describe("autoCacheEligible", () => {
-  test("read-only flows cache by default; mutations / asks / durable / cache:false do not", () => {
-    expect(autoCacheEligible({ effects: { reads: ["sql:notes"] } })).toBe(true);
-    expect(autoCacheEligible({ cache: true, effects: { reads: ["sql:notes"] } })).toBe(true);
-    expect(autoCacheEligible({ cache: "30s", effects: { reads: ["sql:notes"] } })).toBe(true);
-    expect(autoCacheEligible({ cache: false, effects: { reads: ["sql:notes"] } })).toBe(false);
-    expect(autoCacheEligible({ durable: true, effects: { reads: ["sql:notes"] } })).toBe(false);
-    expect(autoCacheEligible({ effects: { reads: ["sql:notes"], writes: ["sql:notes"] } })).toBe(
-      false,
-    );
-    expect(autoCacheEligible({ effects: { reads: ["sql:notes"], asks: ["task-suggest"] } })).toBe(
+  test("pure store reads cache by default; side effects never cache", () => {
+    const reads: Effects = { reads: ["sql:notes"] };
+    expect(autoCacheEligible({ effects: reads })).toBe(true);
+    expect(autoCacheEligible({ auto: false, effects: reads })).toBe(false);
+    expect(autoCacheEligible({ auto: false, cache: true, effects: reads })).toBe(true);
+    expect(autoCacheEligible({ auto: true, effects: reads })).toBe(true);
+    expect(autoCacheEligible({ cache: true, effects: reads })).toBe(true);
+    expect(autoCacheEligible({ cache: "30s", effects: reads })).toBe(true);
+    expect(autoCacheEligible({ auto: true, cache: false, effects: reads })).toBe(false);
+    expect(autoCacheEligible({ cache: true, durable: true, effects: reads })).toBe(false);
+    expect(
+      autoCacheEligible({ cache: true, effects: { reads: ["sql:notes"], writes: ["sql:notes"] } }),
+    ).toBe(false);
+    expect(
+      autoCacheEligible({ cache: true, effects: { reads: ["sql:notes"], asks: ["task-suggest"] } }),
+    ).toBe(false);
+    for (const extra of [
+      { emits: ["note.created"] },
+      { sends: ["welcome"] },
+      { fetches: ["api.example.com"] },
+      { secrets: ["stripe"] },
+      { calls: ["notes.create"] },
+      { embeds: ["embed-small"] },
+      { decides: ["route"] },
+    ]) {
+      expect(autoCacheEligible({ auto: true, effects: { reads: ["sql:notes"], ...extra } })).toBe(
+        false,
+      );
+    }
+    expect(autoCacheEligible({ auto: true, effects: { reads: ["runs"] } })).toBe(false);
+    expect(autoCacheEligible({ auto: true, effects: { reads: ["signal:notify"] } })).toBe(false);
+    expect(autoCacheEligible({ auto: true, effects: { reads: ["sql:notes", "runs"] } })).toBe(
       false,
     );
-    expect(autoCacheEligible({ effects: { reads: ["runs"] } })).toBe(false);
-    expect(autoCacheEligible({ effects: { reads: ["signal:notify"] } })).toBe(false);
-    expect(autoCacheEligible({ effects: {} })).toBe(false);
+    expect(autoCacheEligible({ auto: true, effects: {} })).toBe(false);
   });
 
   test("flow+input dims keep list and get from colliding; invalidation still uses the resource", () => {
@@ -107,7 +128,7 @@ describe("autoCacheEligible", () => {
     expect(isInvalidatedByWrite(getKeys[0]!, { writes: ["sql:views"] })).toBe(true);
   });
 
-  test("effectsFromLedger keeps store reads/writes and asks; drops runs", () => {
+  test("effectsFromLedger keeps store effects and side effects, including non-store reads", () => {
     expect(
       effectsFromLedger([
         { kind: "read", resource: "sql:views" },
@@ -117,14 +138,98 @@ describe("autoCacheEligible", () => {
         { kind: "write", resource: "sql:views" },
         { kind: "ask", resource: "summarize" },
         { kind: "emit", resource: "view-changed" },
+        { kind: "send", resource: "welcome" },
+        { kind: "fetch", resource: "api.example.com" },
+        { kind: "secret", resource: "stripe" },
+        { kind: "call", resource: "notes.create" },
+        { kind: "embed", resource: "embed-small" },
+        { kind: "decide", resource: "route" },
       ]),
     ).toEqual({
-      reads: ["sql:views"],
+      reads: ["sql:views", "runs", "signal:notify"],
       writes: ["sql:views"],
       asks: ["summarize"],
+      emits: ["view-changed"],
+      sends: ["welcome"],
+      fetches: ["api.example.com"],
+      secrets: ["stripe"],
+      calls: ["notes.create"],
+      embeds: ["embed-small"],
+      decides: ["route"],
     });
   });
 
+  test("tier-1 dims always include tenant, locale, scopes, and roles", () => {
+    const effects: Effects = { reads: ["sql:notes"] };
+    const a = tier1FlowDims(
+      "notes.list",
+      {},
+      {
+        userId: "u1",
+        tenantId: "ta",
+        locale: "en",
+        scopes: ["b", "a"],
+        roles: ["admin"],
+      },
+    );
+    const b = tier1FlowDims(
+      "notes.list",
+      {},
+      {
+        userId: "u1",
+        tenantId: "tb",
+        locale: "en",
+        scopes: ["a", "b"],
+        roles: ["admin"],
+      },
+    );
+    const locale = tier1FlowDims(
+      "notes.list",
+      {},
+      {
+        userId: "u1",
+        tenantId: "ta",
+        locale: "ar",
+        scopes: ["a", "b"],
+        roles: ["member"],
+      },
+    );
+    expect(a).toContain("t:ta");
+    expect(a).toContain("l:en");
+    expect(a).toContain("s:a,b");
+    expect(a).toContain("r:admin");
+    expect(a).not.toEqual(b);
+    expect(
+      tier1DimsByResource(
+        effects,
+        "notes.list",
+        {},
+        {
+          userId: "u1",
+          tenantId: "ta",
+          locale: "en",
+          scopes: ["a"],
+          roles: ["admin"],
+        },
+      )["sql:notes"],
+    ).not.toEqual(
+      tier1DimsByResource(
+        effects,
+        "notes.list",
+        {},
+        {
+          userId: "u1",
+          tenantId: "ta",
+          locale: "ar",
+          scopes: ["a"],
+          roles: ["member"],
+        },
+      )["sql:notes"],
+    );
+    expect(locale).toContain("l:ar");
+    expect(locale).toContain("r:member");
+  });
+
   test("resolveCacheEffects prefers stamped reads, then learned reads", () => {
     expect(resolveCacheEffects({ reads: ["sql:views"] }, ["sql:tasks"])).toEqual({
       reads: ["sql:views"],