okengine 0.22.0 → 0.23.1

package/src/kernel/app.ts

@@ -6,6 +6,7 @@
  * pipeline, and wires `fx.call` to untriggered (and triggered) flows.
  */
 
+import { bindAgentApprovalFlows } from "../elements/ai/approval-http.ts";
 import { compileRoute } from "../compiler/dynamic.ts";
 import type { CompiledRoute } from "../compiler/aot.ts";
 import { encodeExecuteResult, encodeFailure } from "../compiler/response.ts";
@@ -67,6 +68,7 @@ import {
 import { GATE_PUBLIC_NAME } from "../elements/gate/flatten.ts";
 import type { JsonCodeAuth } from "../runtime/json-code-block.ts";
 import { resolveDurationMs } from "./elapsed.ts";
+import { captureHttpFrame } from "./http-frame.ts";
 import { fail, throwOke, OkeError } from "./errors.ts";
 import { FLOW_NAME_DUPLICATE, FLOW_UNNAMED } from "./errors-flow-name.ts";
 import { ONCE_SIGNAL_MULTI_FLOW } from "./errors-once-signal.ts";
@@ -217,6 +219,39 @@ function loadClientDescriptor(): typeof import("./client-descriptor.ts") {
   return lazyRequire(import.meta.dir, ["client", "descriptor"].join("-"));
 }
 
+/** Decision HTTP flows. A static `import()` still lands on every HTTP bundle. */
+function loadDecisionBind(): typeof import("../elements/ai/decisions/bind.ts") {
+  return lazyRequire(`${import.meta.dir}/../elements/ai/decisions`, ["bi", "nd"].join(""));
+}
+
+/** Decision lockfile. Loaded only when the manifest declares decisions. */
+function loadDecisionCertificate(): typeof import("../elements/ai/decisions/certificate.ts") {
+  return lazyRequire(`${import.meta.dir}/../elements/ai/decisions`, ["certificate"].join(""));
+}
+
+/** Decision label opener. Loaded only when the manifest declares decisions. */
+function loadDecisionLabels(): typeof import("../elements/ai/decisions/labels.ts") {
+  return lazyRequire(`${import.meta.dir}/../elements/ai/decisions`, ["lab", "els"].join(""));
+}
+
+/** Drift-flag registration. Loaded only when the manifest declares decisions. */
+function loadDecisionLabelStore(): typeof import("./decision-label-store.ts") {
+  return lazyRequire(import.meta.dir, ["decision", "label", "store"].join("-"));
+}
+
+/** `fx.decide` gate hook. Loaded only when the manifest declares decisions. */
+function loadFxDecideModule(): typeof import("./fx-decide.ts") {
+  return lazyRequire(import.meta.dir, ["fx", "decide"].join("-"));
+}
+
+/**
+ * Full boot graph (drivers, elements). A static `import()` string is still
+ * bundled into every HTTP app; the stem stays computed.
+ */
+function loadBoot(): typeof import("./boot.ts") {
+  return lazyRequire(import.meta.dir, ["bo", "ot"].join(""));
+}
+
 /** Options for {@link oke}. */
 export interface OkeOptions {
   /** Application name (Manifest `app`). */
@@ -333,6 +368,15 @@ export interface OkeOptions {
       };
     };
   };
+  /**
+   * Tier-1 read cache. Omitted caches pure store-read flows. `{ auto: false }`
+   * turns that off. A flow can still opt in with `cache: true` or a duration,
+   * and `cache: false` always disables. The key includes tenant, locale,
+   * scopes, and membership roles.
+   */
+  readonly cache?: {
+    readonly auto?: boolean;
+  };
   /** Channel runtime options. */
   readonly channel?: BootOptions["channel"];
   /** AI runtime options. */
@@ -563,6 +607,8 @@ export interface OkeApp<D extends Record<string, unknown> = {}, R extends AppRou
       readonly runId?: string;
       /** Tenant identity for cron / `fx.call` (propagated, unlike auth). */
       readonly tenant?: { readonly id: string | null };
+      /** Explicit locale override for {@link Fx.t} / channel sends. */
+      readonly locale?: string;
     },
   ): Promise<ExecuteResult>;
   /**
@@ -1095,6 +1141,8 @@ export function oke(options: OkeOptions): OkeApp {
   // contribute auth-method Bindings before traffic (plan Phase 2).
   const router: Router<Binding> = smart;
 
+  bindAgentApprovalFlows(adoptBinding);
+
   function adoptBinding(b: Binding): void {
     adopted.push(b);
     registerFlow(b.flow);
@@ -1115,6 +1163,24 @@ export function oke(options: OkeOptions): OkeApp {
 
   /** Once-per-app: system `_oke_search_embed_*` CDC bindings from Manifest. */
   let searchEmbedFlowsBound = false;
+  let decisionFlowsBound = false;
+
+  /**
+   * Register the decision aggregate, drift monitor, and candidate route
+   * when any decision declares autonomy.
+   *
+   * @param manifest - Boot manifest
+   */
+  async function ensureDecisionFlows(manifest: BootOptions["manifest"] | undefined): Promise<void> {
+    if (decisionFlowsBound || !manifest) return;
+    const { bindDecisionFlows, manifestHasDecisionAutonomy } = loadDecisionBind();
+    if (!manifestHasDecisionAutonomy(manifest)) {
+      decisionFlowsBound = true;
+      return;
+    }
+    bindDecisionFlows(adoptBinding, manifest);
+    decisionFlowsBound = true;
+  }
   /**
    * Auto-register hybrid-search embed CDC flows when any `.embed()` column
    * exists. Lazy-loads search-bind so edge graphs without search stay lean.
@@ -1339,6 +1405,19 @@ export function oke(options: OkeOptions): OkeApp {
             ...durableResumeFx(),
             ...(gateConfig.auth?.tenant ? (loadAppTenant().w(5, gateConfig.auth) as object) : {}),
             ...(existing?.tenant ? { tenant: { id: existing.tenant } } : {}),
+            callHandler: async (name, callInput) => {
+              const target = flowsByName.get(name);
+              if (!target) return undefined;
+              const inner = await execute(
+                target,
+                callInput,
+                { kind: "internal" } satisfies InternalTrigger,
+                { parentId: runId },
+              );
+              if (inner.failure) return inner.failure;
+              if (inner.ctx.error !== undefined) throw inner.ctx.error;
+              return inner.output;
+            },
           },
         });
       } catch (err) {
@@ -1367,7 +1446,7 @@ export function oke(options: OkeOptions): OkeApp {
   }
 
   async function doBoot(overrides?: Partial<BootOptions>): Promise<BootResult> {
-    const { bootApplication, resolveElementNeeds } = await import("./boot.ts");
+    const { bootApplication, resolveElementNeeds } = loadBoot();
     const { assertHttpGatePosture } = await import("../elements/gate/boot.ts");
     const { assertPluginNeeds, buildAvailableNeedTokens } = await import("./plugin-needs.ts");
     const dockerFlag =
@@ -1388,6 +1467,7 @@ export function oke(options: OkeOptions): OkeApp {
     }
 
     const unguardedHttp = overrides?.unguardedHttp ?? gateConfig.unguardedHttp ?? "deny";
+    await ensureDecisionFlows(overrides?.manifest ?? options.manifest);
     // Auth bindings are in `adopted` — missing posture fails with GateBootError.
     assertHttpGatePosture(adopted, { unguardedHttp, env: bootEnv });
 
@@ -1557,6 +1637,26 @@ export function oke(options: OkeOptions): OkeApp {
     // Built-in hybrid search — auto-register durable embed CDC flows when the
     // Manifest declares any `.embed()` column (writer flows stay embed-free).
     await ensureSearchEmbedFlows(overrides?.manifest ?? options.manifest);
+    const decisionManifest = overrides?.manifest ?? options.manifest;
+    const declaredDecisions = decisionManifest?.ai?.decisions;
+    if (declaredDecisions && Object.keys(declaredDecisions).length > 0) {
+      const { loadDecisionLockfile, setDecisionDrift } = loadDecisionCertificate();
+      const { openDecisionLabelStore } = loadDecisionLabels();
+      const { setDeclaredDriftDecisions } = loadDecisionLabelStore();
+      const { setDecisionGateAllow } = loadFxDecideModule();
+      const root = overrides?.rootDir ?? options.rootDir ?? process.env["OKE_ROOT_DIR"];
+      if (!root) {
+        throw new Error(
+          "oke boot: decisions are declared but rootDir and OKE_ROOT_DIR are unset, so the decision lockfile cannot load.",
+        );
+      }
+      await loadDecisionLockfile(root);
+      setDeclaredDriftDecisions(Object.keys(declaredDecisions));
+      if (result.journal && result.journal.store.decisions) {
+        await openDecisionLabelStore(result.journal.store, setDecisionDrift);
+      }
+      if (result.gate) setDecisionGateAllow((names, ctx) => result.gate!.allow(names, ctx));
+    }
     // otp() provider / app mode capability — fail loud at boot, never silent downgrade.
     if (result.channel) {
       const { assertOtpPluginCapability } = await import("../auth/otp-capability.ts");
@@ -1996,6 +2096,14 @@ export function oke(options: OkeOptions): OkeApp {
               : undefined;
             // Revealed PII must not hit a prior masked entry or land in cache.
             const reveal = extras?.trustedInvoke === true && extras.revealPii === true;
+            const cacheAuto = options.cache?.auto !== false;
+            const cacheCaller = {
+              userId: fx.auth.userId,
+              tenantId: fx.tenant.id,
+              locale: fx.locale,
+              scopes: fx.auth.scopes,
+              roles: principals?.cacheRoles ?? [],
+            };
             const cacheOk =
               cache !== undefined &&
               storeRt !== undefined &&
@@ -2003,12 +2111,13 @@ export function oke(options: OkeOptions): OkeApp {
               !reveal &&
               cache.autoCacheEligible({
                 cache: flowDef.cache,
+                auto: cacheAuto,
                 durable: flowDef.durable,
                 effects: cacheEffects,
               });
             const dims =
               cacheOk && cache && cacheEffects
-                ? cache.tier1DimsByResource(cacheEffects, flowDef.name, input, fx.auth.userId)
+                ? cache.tier1DimsByResource(cacheEffects, flowDef.name, input, cacheCaller)
                 : undefined;
             if (cacheOk && cache && dims && storeRt) {
               const keys = cache.tier1KeysForReads(cacheEffects, dims);
@@ -2043,39 +2152,35 @@ export function oke(options: OkeOptions): OkeApp {
             const output = isFlowFailure(raw) ? raw : await projectFlowOut(flowDef.out, raw);
             if (!isFlowFailure(output) && cache && storeRt && cacheEffects) {
               const ledgerFx = cache.effectsFromLedger(ledger.entries);
+              const observed = cache.mergeEffects(cacheEffects, ledgerFx);
               const writeEffects: Effects = {
-                writes: [
-                  ...new Set([...(cacheEffects.writes ?? []), ...(ledgerFx.writes ?? [])]),
-                ].filter(cache.isStoreResourceRef),
+                writes: (observed.writes ?? []).filter(cache.isStoreResourceRef),
               };
               if ((writeEffects.writes?.length ?? 0) > 0) {
                 storeRt.onWriteEffects(writeEffects);
               }
-              const mergedReads = [
-                ...new Set([...(cacheEffects.reads ?? []), ...(ledgerFx.reads ?? [])]),
-              ].filter(cache.isStoreResourceRef);
-              if (mergedReads.length > 0) {
-                learnedTier1Reads.set(flowDef.name, mergedReads);
+              const storeReads = (observed.reads ?? []).filter(cache.isStoreResourceRef);
+              if (cache.autoCachePure(observed) && storeReads.length > 0) {
+                learnedTier1Reads.set(flowDef.name, storeReads);
+              } else {
+                learnedTier1Reads.delete(flowDef.name);
               }
-              const putEffects: Effects = {
-                reads: mergedReads,
-                ...(ledgerFx.writes ? { writes: ledgerFx.writes } : {}),
-                ...(ledgerFx.asks ? { asks: ledgerFx.asks } : {}),
-              };
               const storeAfter =
                 !reveal &&
                 cache.autoCacheEligible({
                   cache: flowDef.cache,
+                  auto: cacheAuto,
                   durable: flowDef.durable,
-                  effects: putEffects,
+                  effects: observed,
                 });
               if (storeAfter && output !== undefined && !loadFx().isJsonStreamResult(output)) {
                 const ttlMs =
                   typeof flowDef.cache === "string" ? cache.parseTtlMs(flowDef.cache) : undefined;
+                const putEffects: Effects = { reads: storeReads };
                 storeRt.putTier1(
                   putEffects,
                   output,
-                  cache.tier1DimsByResource(putEffects, flowDef.name, input, fx.auth.userId),
+                  cache.tier1DimsByResource(putEffects, flowDef.name, input, cacheCaller),
                   ttlMs,
                 );
                 if (!cacheOk) telemetry.cacheMisses += 1;
@@ -2257,6 +2362,14 @@ export function oke(options: OkeOptions): OkeApp {
         : durationMs;
       if (journalSession) {
         inflightRuns.delete(journalSession.runId);
+        const parked = streamOut?.parked;
+        if (parked) {
+          ctx.state.sleeping = {
+            wakeAt: parked.wakeAt,
+            label: parked.label,
+            runId: journalSession.runId,
+          };
+        }
         const sleeping = ctx.state.sleeping as
           | { readonly wakeAt: number; readonly label: string; readonly runId: string }
           | undefined;
@@ -2277,6 +2390,8 @@ export function oke(options: OkeOptions): OkeApp {
             fx,
             error: terminalErr,
           });
+        } else if (parked && sleeping) {
+          await journalSession.commit("sleeping", { wakeAt: sleeping.wakeAt });
         } else if (!sleeping) {
           await journalSession.commit("completed", {
             output: streamOut ? { streamed: true } : result.output,
@@ -2309,6 +2424,9 @@ export function oke(options: OkeOptions): OkeApp {
               ? { output: streamOut ? { streamed: true } : result.output }
               : {}),
             ...(parentId !== undefined ? { parentId } : {}),
+            ...(trigger.kind === "http" && extras?.request
+              ? { http: captureHttpFrame(extras.request, result.response) }
+              : {}),
           },
           archiveCleartext,
         );

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/boot-bind/ai.ts

@@ -14,6 +14,7 @@ import type { AiDriver, AiOpenOptions } from "../../drivers/ai-types.ts";
 import { createAiRuntime, type AiRuntime } from "../../elements/ai.ts";
 import type { GateRuntime } from "../../elements/gate.ts";
 import type { VaultRuntime } from "../../elements/vault.ts";
+import type { JournalStore } from "../journal.ts";
 import type { BootOptions } from "../boot.ts";
 
 /**
@@ -33,6 +34,7 @@ export function bindAi(
   env: ConfigEnv = "test",
   docker = false,
   vault?: VaultRuntime,
+  journalStore?: JournalStore,
 ): AiRuntime {
   const id = resolveAiDriverId(options, env, docker);
   const driver =
@@ -48,6 +50,7 @@ export function bindAi(
     },
     gates: options.ai?.gates ?? gate,
     now,
+    ...(journalStore ? { journalStore } : {}),
   });
 }
 

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(),
+        }
+      : {}),
   });
 }