okengine 0.12.0 → 0.13.0

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

@@ -34,12 +34,20 @@ import type { BootOptions } from "../boot.ts"; // type-only — no cycle at runt
  * @param docker - Prefer compose URLs when opening postgres/redis
  */
 let filesFsWarned = false;
+let kvCacheShapedWarned = false;
+let kvMemoryDurableWarned = false;
 
 /** Test helper — reset the one-shot `fs` multi-instance warn. */
 export function resetFilesFsWarnForTests(): void {
   filesFsWarned = false;
 }
 
+/** Test helper — reset durable-KV boot warns. */
+export function resetKvDurableWarnsForTests(): void {
+  kvCacheShapedWarned = false;
+  kvMemoryDurableWarned = false;
+}
+
 /**
  * Warn once when `drivers.store.files` is `fs` — per-process (or per-pod)
  * filesystem visibility under horizontal scale.
@@ -54,6 +62,39 @@ function warnFilesFsMultiInstance(): void {
   );
 }
 
+/**
+ * Warn once: default KV namespaces are cache-shaped (no AOF) unless
+ * `{ durable: true }` persists them in SQL (`oke_kv`).
+ */
+function warnKvCacheShaped(names: readonly string[]): void {
+  if (kvCacheShapedWarned) return;
+  kvCacheShapedWarned = true;
+  const listed = names
+    .slice(0, 4)
+    .map((n) => `"${n}"`)
+    .join(", ");
+  const extra = names.length > 4 ? ` (and ${String(names.length - 4)} more)` : "";
+  emitBootWarn(
+    `oke boot: store.kv ${listed}${extra} is cache-shaped — a Redis recreate drops keys ` +
+      "(no AOF). Declare `{ durable: true }` on a separate namespace to persist in " +
+      "your SQL database (`oke_kv`).",
+  );
+}
+
+/**
+ * Warn once: in-process memory SQL cannot honor `{ durable: true }`.
+ */
+function warnKvMemoryDurable(names: readonly string[]): void {
+  if (kvMemoryDurableWarned) return;
+  kvMemoryDurableWarned = true;
+  const listed = names.map((n) => `"${n}"`).join(", ");
+  emitBootWarn(
+    `oke boot: store.kv ${listed} declared { durable: true } but drivers.store.sql is ` +
+      '"memory" — keys are process-local and vanish on restart. Use drivers.store.sql ' +
+      "postgres with DATABASE_URL.",
+  );
+}
+
 export function bindStore(
   options: BootOptions,
   env: ConfigEnv,
@@ -65,9 +106,28 @@ export function bindStore(
   const filesId = resolveFilesDriverId(options, env, docker);
   const indexId = resolveIndexDriverId(options, env, docker);
   if (filesId === "fs") warnFilesFsMultiInstance();
+  const kvDecls = (options.stores ?? []).filter(isKvDecl);
+  const durableKvDecls = kvDecls.filter((d) => d.durable === true);
+  const cacheKvDecls = kvDecls.filter((d) => d.durable !== true);
+  if (durableKvDecls.length > 0 && sqlId === "postgres") {
+    const url = process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL;
+    if (!url) {
+      throw new Error(
+        docker
+          ? "oke boot: durable store.kv needs DATABASE_URL (did `oke dev` write .env.local?)"
+          : "oke boot: durable store.kv needs DATABASE_URL",
+      );
+    }
+  }
   const sqlUrl = sqlUrlFor(sqlId, docker, env);
   const kvUrl = kvUrlFor(kvId, docker);
   const filesRoot = filesRootFor(filesId);
+  if (kvId === "redis" && env !== "test" && cacheKvDecls.length > 0) {
+    warnKvCacheShaped(cacheKvDecls.map((d) => d.name));
+  }
+  if (sqlId === "memory" && env !== "test" && durableKvDecls.length > 0) {
+    warnKvMemoryDurable(durableKvDecls.map((d) => d.name));
+  }
 
   const sqlBindings: Record<string, { name: string; primary: { url: string } }> = {};
   const kvBindings: Record<string, { url?: string }> = {};
@@ -81,7 +141,11 @@ export function bindStore(
         primary: { url: sqlUrl },
       };
     } else if (isKvDecl(decl)) {
-      kvBindings[decl.name] = kvUrl !== undefined ? { url: kvUrl } : {};
+      if (decl.durable === true) {
+        kvBindings[decl.name] = {};
+      } else {
+        kvBindings[decl.name] = kvUrl !== undefined ? { url: kvUrl } : {};
+      }
     } else if (isFilesDecl(decl)) {
       filesBindings[decl.name] = filesRoot !== undefined ? { root: filesRoot } : {};
     } else if (isIndexDecl(decl)) {
@@ -114,6 +178,7 @@ export function bindStore(
     index: indexBindings,
     now,
     domainDdl,
+    sqlUrl,
   });
   for (const decl of options.stores ?? []) {
     store.register?.(decl);

package/src/manifest/diff.test.ts

@@ -309,6 +309,19 @@ describe("diffManifest — additional branches", () => {
     expect(hasCategory(result.changes, "contract-breaking", "facet")).toBe(true);
   });
 
+  test("store.kv durable on is effect-widening; off is contract-breaking", async () => {
+    const before = await loadBase();
+    before.stores!.db!.facet = "kv";
+    before.stores!.db!.namespaces = ["cache"];
+    delete before.stores!.db!.tables;
+    const on = clone(before);
+    on.stores!.db!.durable = true;
+    expect(hasCategory(diffManifest(before, on).changes, "effect-widening", "durable")).toBe(true);
+    const off = clone(on);
+    off.stores!.db!.durable = false;
+    expect(hasCategory(diffManifest(on, off).changes, "contract-breaking", "durable")).toBe(true);
+  });
+
   test("clocks, vault, channels, journeys, drivers, i18n, topology, images", async () => {
     const before = await loadBase();
     const after = clone(before);

package/src/manifest/diff.ts

@@ -779,6 +779,21 @@ function diffStore(before: Store, after: Store, path: string, out: ManifestChang
   diffStringSet(before.namespaces, after.namespaces, `${path}/namespaces`, out);
   diffStringSet(before.buckets, after.buckets, `${path}/buckets`, out);
   diffStringSet(before.indexes, after.indexes, `${path}/indexes`, out);
+  if (
+    before.durable !== after.durable &&
+    (before.durable !== undefined || after.durable !== undefined)
+  ) {
+    out.push(
+      change(
+        `${path}/durable`,
+        after.durable === true ? "effect-widening" : "contract-breaking",
+        "changed",
+        before.durable,
+        after.durable,
+        `store durable ${String(before.durable)} → ${String(after.durable)}`,
+      ),
+    );
+  }
   if (!deepEqual(before.classifications, after.classifications)) {
     out.push(
       change(

package/src/manifest/types.ts

@@ -234,6 +234,11 @@ export interface Store {
   buckets?: string[];
   indexes?: string[];
   classifications?: Record<string, ClassificationValue>;
+  /**
+   * KV only — namespace persists in SQL (`oke_kv`), not the cache Redis.
+   * Distinct from Flow `durable` (journaled steps).
+   */
+  durable?: boolean;
 }
 
 /** Named clock / schedule. */