okengine 0.23.1 → 0.23.2

package/src/kernel/journal.test.ts

@@ -8,6 +8,7 @@ import { describe, expect, test } from "bun:test";
 import { runDurable } from "../elements/clock/durable.ts";
 import { flow } from "./flow.ts";
 import {
+  clearJournalHeartbeats,
   createJournal,
   createMemoryJournalStore,
   hasJournalLease,
@@ -171,6 +172,34 @@ describe("journal lease (memory store)", () => {
     }
   });
 
+  test("heartbeat extends the lease, and a lost lease does not persist the step", async () => {
+    let t = 1_000;
+    const store = createMemoryJournalStore();
+    const a = createJournal({
+      store,
+      now: () => t,
+      lease: { instanceId: "a", leaseMs: 60 },
+      codeVersion: "v1",
+    });
+    const session = await a.start("charge");
+    t = 1_030;
+    await Bun.sleep(40);
+    expect((await store.get(session.runId))?.leaseExpiresAt).toBe(1_090);
+    t = 2_000;
+    const b = createJournal({
+      store,
+      now: () => t,
+      lease: { instanceId: "b", leaseMs: 60 },
+      codeVersion: "v1",
+    });
+    await b.resume(session.runId);
+    await Bun.sleep(40);
+    await expect(session.step("capture", () => 1)).rejects.toBeInstanceOf(OkeError);
+    expect((await store.get(session.runId))?.entries ?? []).toHaveLength(0);
+    expect((await store.get(session.runId))?.lockedBy).toBe("b");
+    clearJournalHeartbeats();
+  });
+
   test("replay throws when the next call does not match the journal", async () => {
     const store = createMemoryJournalStore();
     const journal = createJournal({ store, now: () => 1, codeVersion: "v1" });
@@ -198,6 +227,21 @@ describe("journal lease (memory store)", () => {
     }
   });
 
+  test("a 0.23.1 stamp resumes and is restamped when codeVersion is set", async () => {
+    const store = createMemoryJournalStore();
+    const started = await createJournal({ store, now: () => 1, codeVersion: "v1" }).start("charge");
+    const row = await store.get(started.runId);
+    if (row) {
+      row.codeVersion = "0.23.1";
+      await store.put(row);
+    }
+    const resumed = await createJournal({ store, now: () => 2, codeVersion: "v9" }).resume(
+      started.runId,
+    );
+    expect(resumed.run.codeVersion).toBe("app:v9");
+    expect((await store.get(started.runId))?.status).not.toBe("failed");
+  });
+
   test("resume rejects a run stamped with another code version", async () => {
     const store = createMemoryJournalStore();
     const started = await createJournal({ store, now: () => 1, codeVersion: "v1" }).start("charge");

package/src/kernel/journal.ts

@@ -7,11 +7,10 @@
  * (four-applications · Provisions).
  */
 
-import { readFileSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { okid } from "../okid.ts";
-import { throwOke } from "./errors.ts";
+import { OkeError, throwOke } from "./errors.ts";
 import type { DecisionLabelStore } from "./decision-label-store.ts";
 import type { IdempotencyStore } from "./idempotency-store.ts";
 import { JournalSuspend } from "./journal-suspend.ts";
@@ -145,6 +144,15 @@ export interface JournalLeaseStore {
    * @param leaseMs - Lease duration
    */
   acquireLease(runId: string, instanceId: string, now: number, leaseMs: number): Promise<boolean>;
+  /**
+   * Extend `lease_expires_at` without changing the fencing token.
+   * Returns false when this holder no longer owns the run.
+   *
+   * @param runId - Run id
+   * @param expiresAt - New expiry, epoch-ms
+   * @param fence - Caller's lease fence
+   */
+  renewLeaseExpiry?(runId: string, expiresAt: number, fence: JournalWriteFence): Promise<boolean>;
   /**
    * Take the lease and write `update(run)` in that same hold.
    * `undefined` from `update` keeps the previous entries and still holds the lease.
@@ -259,6 +267,22 @@ export interface JournalStore extends Partial<JournalLeaseStore> {
     entry: JournalEntry,
     fence?: JournalWriteFence,
   ): Promise<void>;
+  /**
+   * Replace one existing entry under the caller's fence. Built-in stores
+   * implement this so approval and decide can correct a step without
+   * rewriting the run. Absent on a custom store — callers keep `put`.
+   *
+   * @param runId - Run id
+   * @param seq - Zero-based position
+   * @param entry - Replacement entry
+   * @param fence - Lease fence
+   */
+  updateEntry?(
+    runId: string,
+    seq: number,
+    entry: JournalEntry,
+    fence: JournalWriteFence,
+  ): Promise<void>;
   /** List all runs (test / console helper). */
   list(): Promise<readonly JournalRun[]>;
 }
@@ -296,6 +320,27 @@ export function isJournalLeaseBusy(err: unknown): err is JournalLeaseBusy {
   return err instanceof JournalLeaseBusy;
 }
 
+/**
+ * A fenced write lost the lease (OKE1074). The holder must not compensate
+ * or record the step — another instance may already own the run.
+ *
+ * @param err - Caught error
+ */
+export function isLostJournalLease(err: unknown): boolean {
+  return err instanceof OkeError && err.code === 1074;
+}
+
+const heartbeatTimers = new Set<ReturnType<typeof setInterval>>();
+
+/**
+ * Stop every session heartbeat. `stop` and `close` call this so a shut
+ * down process does not keep renewing leases it no longer owns.
+ */
+export function clearJournalHeartbeats(): void {
+  for (const timer of heartbeatTimers) clearInterval(timer);
+  heartbeatTimers.clear();
+}
+
 /** Live lease = a holder with an unexpired expiry. */
 function hasLiveLease(run: JournalRun, now: number): boolean {
   return run.lockedBy !== undefined && run.leaseExpiresAt !== undefined && run.leaseExpiresAt > now;
@@ -350,6 +395,20 @@ function leaseMethods(
         release();
       }
     },
+    async renewLeaseExpiry(runId, expiresAt, fence) {
+      const map = await load();
+      const run = map.get(runId);
+      if (!run) return false;
+      const expired = run.leaseExpiresAt !== undefined && run.leaseExpiresAt <= fence.now;
+      if (run.lockedBy !== fence.lockedBy || run.leaseToken !== fence.leaseToken || expired) {
+        return false;
+      }
+      if (run.leaseExpiresAt === undefined || run.leaseExpiresAt < expiresAt) {
+        run.leaseExpiresAt = expiresAt;
+      }
+      await flush?.(map);
+      return true;
+    },
     async releaseLease(runId, instanceId) {
       const map = await load();
       const run = map.get(runId);
@@ -410,6 +469,14 @@ export function createMemoryJournalStore(seed?: readonly JournalRun[]): JournalS
       assertJournalFence(existing, fence);
       appendStoredEntry(existing, seq, entry);
     },
+    async updateEntry(runId, seq, entry, fence) {
+      const existing = runs.get(runId);
+      if (!existing) throwOke("JOURNAL_STALE_LEASE", { runId });
+      assertJournalFence(existing, fence);
+      const entries = existing.entries as JournalEntry[];
+      if (!entries[seq]) throwOke("JOURNAL_STALE_LEASE", { runId });
+      entries[seq] = structuredClone(entry);
+    },
     async list() {
       return [...runs.values()].map(cloneRun);
     },
@@ -479,6 +546,16 @@ export function createFileJournalStore(path: string): JournalStore {
       appendStoredEntry(existing, seq, entry);
       await flush(map);
     },
+    async updateEntry(runId, seq, entry, fence) {
+      const map = await load();
+      const existing = map.get(runId);
+      if (!existing) throwOke("JOURNAL_STALE_LEASE", { runId });
+      assertJournalFence(existing, fence);
+      const entries = existing.entries as JournalEntry[];
+      if (!entries[seq]) throwOke("JOURNAL_STALE_LEASE", { runId });
+      entries[seq] = structuredClone(entry);
+      await flush(map);
+    },
     async list() {
       const map = await load();
       return [...map.values()].map(cloneRun);
@@ -674,7 +751,7 @@ export function createJournal(options: CreateJournalOptions): Journal {
   const now = options.now ?? (() => Date.now());
   const newId = options.id ?? (() => okid());
   const lease = options.lease;
-  const codeVersion = options.codeVersion ?? packageVersion();
+  const codeVersion = stampAppVersion(options.codeVersion);
   const coordinated = lease !== undefined && hasJournalLease(options.store);
 
   function openSession(run: JournalRun, leased: boolean): JournalSession {
@@ -697,6 +774,7 @@ export function createJournal(options: CreateJournalOptions): Journal {
     }
 
     async function persist(entry?: JournalEntry): Promise<void> {
+      if (lostLease) throwOke("JOURNAL_STALE_LEASE", { runId: run.id });
       run.updatedAt = now();
       // Natural heartbeat — a live holder renews on every journal write.
       if (leaseHeld && lease) {
@@ -742,8 +820,52 @@ export function createJournal(options: CreateJournalOptions): Journal {
     }
 
     /** Parking / terminal states must not hold a short lease across days. */
+    let heartbeat: ReturnType<typeof setInterval> | undefined;
+    let lostLease = false;
+    let activeStep = "";
+
+    function stopHeartbeat(): void {
+      if (!heartbeat) return;
+      clearInterval(heartbeat);
+      heartbeatTimers.delete(heartbeat);
+      heartbeat = undefined;
+    }
+
+    function startHeartbeat(): void {
+      if (!leased || !lease || heartbeat) return;
+      const every = Math.max(1, Math.floor((lease.leaseMs ?? JOURNAL_DEFAULT_LEASE_MS) / 3));
+      heartbeat = setInterval(() => {
+        void (async () => {
+          if (!leaseHeld || lostLease || !options.store.renewLeaseExpiry) return;
+          const writeFence = fence();
+          if (!writeFence) return;
+          const expiresAt = now() + (lease.leaseMs ?? JOURNAL_DEFAULT_LEASE_MS);
+          const ok = await options.store.renewLeaseExpiry(run.id, expiresAt, writeFence);
+          if (!ok) {
+            lostLease = true;
+            console.warn(
+              JSON.stringify({
+                event: "journal.lease.lost",
+                runId: run.id,
+                step: activeStep,
+                instanceId: lease.instanceId,
+              }),
+            );
+            return;
+          }
+          if (run.leaseExpiresAt === undefined || run.leaseExpiresAt < expiresAt) {
+            run.leaseExpiresAt = expiresAt;
+          }
+        })();
+      }, every);
+      heartbeat.unref?.();
+      heartbeatTimers.add(heartbeat);
+    }
+
     function releaseLeaseLocally(): void {
       leaseHeld = false;
+      lostLease = false;
+      stopHeartbeat();
       delete run.lockedBy;
       delete run.leaseExpiresAt;
     }
@@ -772,6 +894,8 @@ export function createJournal(options: CreateJournalOptions): Journal {
       }
     }
 
+    if (leased) startHeartbeat();
+
     return {
       runId: run.id,
       run,
@@ -792,6 +916,7 @@ export function createJournal(options: CreateJournalOptions): Journal {
           return value;
         }
         assertCanAppendStep(name);
+        activeStep = name;
         stepDepth += 1;
         let stored: unknown;
         try {
@@ -799,6 +924,7 @@ export function createJournal(options: CreateJournalOptions): Journal {
         } finally {
           stepDepth -= 1;
         }
+        if (lostLease) throwOke("JOURNAL_STALE_LEASE", { runId: run.id });
         const value = reviveJournalValue(stored) as T;
         const entry: JournalStepEntry = {
           kind: "step",
@@ -808,7 +934,13 @@ export function createJournal(options: CreateJournalOptions): Journal {
         };
         run.entries.push(entry);
         cursor = run.entries.length;
-        await persist(entry);
+        try {
+          await persist(entry);
+        } catch (err) {
+          run.entries.pop();
+          cursor = run.entries.length;
+          throw err;
+        }
         if (!name.startsWith(JOURNAL_UNDO_PREFIX)) {
           registerUndo(name, value, opts);
         }
@@ -998,15 +1130,30 @@ export function createJournal(options: CreateJournalOptions): Journal {
         }
         throw new Error(`journal: run "${runId}" not found`);
       }
-      if (run.codeVersion !== undefined && run.codeVersion !== codeVersion) {
-        if (coordinated && lease) {
-          await options.store.releaseLease!(runId, lease.instanceId);
+      if (
+        codeVersion !== undefined &&
+        run.codeVersion !== undefined &&
+        run.codeVersion !== codeVersion
+      ) {
+        if (run.codeVersion.startsWith("app:")) {
+          run.status = "failed";
+          run.error = "OKE1076";
+          run.updatedAt = now();
+          const skewFence =
+            coordinated && lease && run.leaseToken !== undefined && run.lockedBy !== undefined
+              ? { lockedBy: run.lockedBy, leaseToken: run.leaseToken, now: now() }
+              : undefined;
+          await options.store.put(cloneRun(run), skewFence);
+          if (coordinated && lease) {
+            await options.store.releaseLease!(runId, lease.instanceId);
+          }
+          throwOke("JOURNAL_CODE_VERSION", {
+            runId,
+            expected: run.codeVersion,
+            actual: codeVersion,
+          });
         }
-        throwOke("JOURNAL_CODE_VERSION", {
-          runId,
-          expected: run.codeVersion,
-          actual: codeVersion,
-        });
+        run.codeVersion = codeVersion;
       }
       // Leave status intact — the durable runner parks or continues.
       run.updatedAt = now();
@@ -1014,7 +1161,11 @@ export function createJournal(options: CreateJournalOptions): Journal {
         run.lockedBy = lease.instanceId;
         run.leaseExpiresAt = now() + (lease.leaseMs ?? JOURNAL_DEFAULT_LEASE_MS);
       }
-      await options.store.put(cloneRun(run));
+      const resumeFence =
+        coordinated && lease && run.leaseToken !== undefined && run.lockedBy !== undefined
+          ? { lockedBy: run.lockedBy, leaseToken: run.leaseToken, now: now() }
+          : undefined;
+      await options.store.put(cloneRun(run), resumeFence);
       return openSession(run, coordinated);
     },
   };
@@ -1159,19 +1310,13 @@ function entryLabel(entry: JournalEntry): string {
   return `effect ${entry.effectKind} ${entry.resource}`;
 }
 
-let cachedPackageVersion: string | undefined;
-
 /**
- * Package version used when a journal is not given an explicit code version.
+ * Namespace an opt-in code version so an okengine package version stored by
+ * 0.23.1 (`"0.23.1"`) is not compared with an app stamp (`"app:1"`).
+ *
+ * @param version - Caller version, or unset to skip the check
  */
-function packageVersion(): string {
-  if (cachedPackageVersion !== undefined) return cachedPackageVersion;
-  try {
-    const raw = readFileSync(new URL("../../package.json", import.meta.url), "utf8");
-    const parsed = JSON.parse(raw) as { version?: string };
-    cachedPackageVersion = parsed.version && parsed.version.length > 0 ? parsed.version : "0";
-  } catch {
-    cachedPackageVersion = "0";
-  }
-  return cachedPackageVersion;
+function stampAppVersion(version: string | undefined): string | undefined {
+  if (version === undefined || version.length === 0) return undefined;
+  return version.startsWith("app:") ? version : `app:${version}`;
 }

package/src/mcp/authorization.ts

@@ -225,25 +225,19 @@ export const MCP_TOOL_POLICIES: readonly McpToolPolicy[] = [
     name: "oke.action.confirm",
     scopes: ["mcp:action:invoke", "console:flows:invoke"],
     mutability: "read",
-    description: "Request a single-use confirmation token for a write tool (no caching).",
+    description:
+      "Issue a single-use confirmation token for a pending write. The caller must be a different auth session than the requester (no caching).",
     inputSchema: {
       type: "object",
       properties: {
-        tool: {
-          type: "string",
-          enum: ["oke.action.invoke", "oke.action.structural_propose"],
-        },
-        args: { type: "object" },
+        confirmationId: { type: "string", minLength: 1 },
         reason: { type: "string", minLength: 3 },
       },
-      required: ["tool", "args", "reason"],
+      required: ["confirmationId", "reason"],
       additionalProperties: false,
     },
     params: [
-      {
-        name: "tool",
-        enum: ["oke.action.invoke", "oke.action.structural_propose"],
-      },
+      { name: "confirmationId", maxLength: 200 },
       { name: "reason", maxLength: 2000 },
     ],
   },