okengine 0.23.0 → 0.23.1

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/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,19 @@
 
 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 { 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 +40,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 +103,33 @@ 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: postgresSignalDriver,
+        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.ts

@@ -191,6 +191,8 @@ export interface BootOptions {
   readonly clients?: {
     readonly kv?: import("../drivers/types.ts").KvClientLike;
     readonly signalRedis?: import("../drivers/signal-types.ts").SignalRedisClientLike;
+    /** Injected postgres signal client (tests). Production opens Bun.SQL. */
+    readonly signalSql?: import("../drivers/signal-postgres.ts").PostgresSignalSql;
   };
   /**
    * Process instance id for Clock / Journal / fleet registry.
@@ -538,7 +540,16 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   // 4d. Scheduler — one timer drives clock ticks, durable-run resume, heartbeat.
   let schedulerTimer: ReturnType<typeof setInterval> | undefined;
   const startScheduler = options.startScheduler ?? env !== "test";
-  if (startScheduler && (clock !== undefined || journal !== undefined || instances !== undefined)) {
+  const signalBus = signal?.bus ?? undefined;
+  let refreshChannel: (() => Promise<void>) | undefined;
+  if (
+    startScheduler &&
+    (clock !== undefined ||
+      journal !== undefined ||
+      instances !== undefined ||
+      signalBus !== undefined ||
+      needs.channel)
+  ) {
     const period = options.schedulerIntervalMs ?? 1000;
     const clockRt = clock;
     const durableResume = options.onDurableResume;
@@ -550,6 +561,8 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
       console.error(err);
     };
     schedulerTimer = setInterval(() => {
+      if (signalBus) void signalBus.drain().catch(ignoreBenignSql);
+      if (refreshChannel) void refreshChannel().catch(ignoreBenignSql);
       if (clockRt) void Promise.resolve(clockRt.tick()).catch(ignoreBenignSql);
       if (journal && durableResume) void Promise.resolve(durableResume()).catch(ignoreBenignSql);
       if (fleet) void fleet.maybeHeartbeat().catch(ignoreBenignSql);
@@ -572,7 +585,8 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   // 5. Channel
   let channel = pre.channel;
   if (needs.channel && !channel) {
-    channel = channelBind!.bindChannel(options, env, now, docker);
+    channel = await channelBind!.bindChannel(options, env, now, docker);
+    refreshChannel = channel.refresh?.bind(channel);
   }
 
   // 6. AI

package/src/kernel/errors-compiler.ts

@@ -12,6 +12,17 @@ import type { OkeErrorDefinition } from "./errors.ts";
  * A Flow hides `fx` from effect inference, or an explicit `effects` block
  * omits an effect the walk can see.
  */
+/**
+ * A durable Flow calls `fx.fetch` or `fx.send` outside `fx.step`.
+ * Those effects are irreversible and must be an explicit step so replay skips them.
+ */
+export const DURABLE_BARE_EFFECT: OkeErrorDefinition = {
+  code: 1901,
+  domain: "compiler",
+  cause: 'Durable flow "{flow}" calls fx.{effect} outside fx.step.',
+  fix: "Wrap fx.fetch and fx.send in fx.step so replay returns the journaled value instead of repeating the call.",
+};
+
 export const FX_INFERENCE_OPAQUE: OkeErrorDefinition = {
   code: 1900,
   domain: "compiler",

package/src/kernel/errors-text.ts

@@ -84,6 +84,22 @@ export const OKE_ERROR_TEXT: Readonly<Record<string, OkeErrorText>> = {
       'Live signal "{signal}" is exposed twice with the same gates ({gates}) and match ({match}).',
     fix: "Use a different gate or path-param filter, or drop the extra route.",
   },
+  JOURNAL_STALE_LEASE: {
+    cause: 'Journal run "{runId}" rejected a write from an expired lease holder.',
+    fix: "Resume the run so the current holder acquires a new lease token. Do not write with a token from a previous holder.",
+  },
+  JOURNAL_REPLAY_DIVERGENCE: {
+    cause: 'Journal run "{runId}" expected {expected} but the code called {actual}.',
+    fix: "Keep step names, sleep labels, and effect order stable for in-flight runs. A code change that reorders journal calls cannot resume the old run.",
+  },
+  JOURNAL_CODE_VERSION: {
+    cause: 'Journal run "{runId}" was started on code {expected} and this process is {actual}.',
+    fix: "Finish or abandon in-flight runs before deploying a different code version. Do not replay them on the new build.",
+  },
+  JOURNAL_VALUE_NOT_JSON: {
+    cause: "A durable journal entry held a value that is not JSON ({detail}).",
+    fix: "Return plain JSON from fx.step. fx.fetch and fx.send must run inside fx.step so the journal can store a JSON snapshot.",
+  },
   MCP_TOOL_DUPLICATE: {
     cause: 'MCP tool "{tool}" is bound twice (flow "{flow}").',
     fix: "Give each MCP tool exposure a unique tool name.",

package/src/kernel/errors.ts

@@ -294,6 +294,14 @@ const OKE_ERROR_ROWS = {
   LIVE_EXPOSURE_DUPLICATE: { code: 1050, domain: "kernel" },
   /** Two MCP tool bindings share the same exposed tool name. */
   MCP_TOOL_DUPLICATE: { code: 1060, domain: "kernel" },
+  /** A journal write arrived from a holder whose lease token no longer matches. */
+  JOURNAL_STALE_LEASE: { code: 1074, domain: "kernel" },
+  /** Replay called a different step or effect than the next journal entry. */
+  JOURNAL_REPLAY_DIVERGENCE: { code: 1075, domain: "kernel" },
+  /** Resume of a run stamped with a different code version. */
+  JOURNAL_CODE_VERSION: { code: 1076, domain: "kernel" },
+  /** A journaled value could not be stored as JSON. */
+  JOURNAL_VALUE_NOT_JSON: { code: 1077, domain: "kernel" },
   /**
    * Emit target has no subscriber (unified-theory §21).
    * Thrown at emit when `optional` is false and nobody is subscribed.