okengine 0.10.3 → 0.11.1

package/src/kernel/compensate.test.ts

@@ -4,11 +4,13 @@
  */
 
 import { describe, expect, test } from "bun:test";
-import { createMemoryJournalStore } from "./journal.ts";
+import { createMemoryJournalStore, createJournal } from "./journal.ts";
 import type { JournalRuntime } from "./boot-bind/journal.ts";
 import { flow } from "./flow.ts";
 import { oke } from "./app.ts";
 import { createRunsRuntime } from "../runs/runtime.ts";
+import { runDurable } from "../elements/clock/durable.ts";
+import { fail } from "./errors.ts";
 
 function memoryJournal(store = createMemoryJournalStore()): JournalRuntime {
   return {
@@ -125,4 +127,289 @@ describe("durable compensate", () => {
     expect((await store.list())[0]!.status).toBe("failed");
     await runs.close();
   });
+
+  test("per-step { undo } runs LIFO and skips the failed step", async () => {
+    const store = createMemoryJournalStore();
+    const undos: string[] = [];
+
+    const pay = flow("pay.perStep", {
+      durable: true,
+      do: async (_input: { orderId: string }, fx) => {
+        await fx.step("reserve", () => "reserved", {
+          undo: () => {
+            undos.push("undo:reserve");
+          },
+        });
+        await fx.step(
+          "charge",
+          () => {
+            throw new Error("card_declined");
+          },
+          {
+            undo: () => {
+              undos.push("undo:charge");
+            },
+          },
+        );
+        return true;
+      },
+    });
+
+    const app = oke({
+      name: "compensate-per-step",
+      env: "test",
+      startScheduler: false,
+      gate: { unguardedHttp: "allow" },
+      elements: { journal: memoryJournal(store) },
+    }).adopt(pay);
+    await app.boot();
+    await app.execute(pay, { orderId: "o1" }, { kind: "internal" });
+
+    expect(undos).toEqual(["undo:reserve"]);
+    const stepNames = (await store.list())[0]!.entries
+      .filter((e) => e.kind === "step")
+      .map((e) => (e as { name: string }).name);
+    expect(stepNames).toEqual(["reserve", "undo:reserve"]);
+    expect((await store.list())[0]!.status).toBe("failed");
+  });
+
+  test("per-step undo receives the journaled step value", async () => {
+    const store = createMemoryJournalStore();
+    let refunded: unknown;
+
+    const pay = flow("pay.value", {
+      durable: true,
+      do: async (_input, fx) => {
+        await fx.step("charge", () => ({ id: "ch_1" }), {
+          undo: (intent) => {
+            refunded = intent;
+          },
+        });
+        throw new Error("after_charge");
+      },
+    });
+
+    const app = oke({
+      name: "compensate-value",
+      env: "test",
+      startScheduler: false,
+      gate: { unguardedHttp: "allow" },
+      elements: { journal: memoryJournal(store) },
+    }).adopt(pay);
+    await app.boot();
+    await app.execute(pay, {}, { kind: "internal" });
+    expect(refunded).toEqual({ id: "ch_1" });
+  });
+
+  test("auto undos then flow.compensate", async () => {
+    const store = createMemoryJournalStore();
+    const order: string[] = [];
+
+    const pay = flow("pay.both", {
+      durable: true,
+      do: async (_input, fx) => {
+        await fx.step("reserve", () => "ok", {
+          undo: () => {
+            order.push("auto:reserve");
+          },
+        });
+        throw new Error("boom");
+      },
+      compensate: async (_ctx, fx) => {
+        await fx.step("undo:extra", async () => {
+          order.push("hook:extra");
+        });
+      },
+    });
+
+    const app = oke({
+      name: "compensate-both",
+      env: "test",
+      startScheduler: false,
+      gate: { unguardedHttp: "allow" },
+      elements: { journal: memoryJournal(store) },
+    }).adopt(pay);
+    await app.boot();
+    await app.execute(pay, {}, { kind: "internal" });
+    expect(order).toEqual(["auto:reserve", "hook:extra"]);
+  });
+
+  test("fx.fail triggers compensate on execute", async () => {
+    const store = createMemoryJournalStore();
+    const undos: string[] = [];
+
+    const pay = flow("pay.fail", {
+      durable: true,
+      do: async (_input, fx) => {
+        await fx.step("reserve", () => "ok", {
+          undo: () => {
+            undos.push("undo:reserve");
+          },
+        });
+        return fail("Declined", {});
+      },
+    });
+
+    const app = oke({
+      name: "compensate-fx-fail",
+      env: "test",
+      startScheduler: false,
+      gate: { unguardedHttp: "allow" },
+      elements: { journal: memoryJournal(store) },
+    }).adopt(pay);
+    await app.boot();
+    const result = await app.execute(pay, {}, { kind: "internal" });
+    expect(result.failure?.error.code).toBe("Declined");
+    expect(undos).toEqual(["undo:reserve"]);
+    expect((await store.list())[0]!.status).toBe("failed");
+  });
+
+  test("runDurable: fx.fail triggers compensate", async () => {
+    const store = createMemoryJournalStore();
+    const undos: string[] = [];
+    const pay = flow("pay.durableFail", {
+      durable: true,
+      do: async (_input, fx) => {
+        await fx.step("reserve", () => "ok", {
+          undo: () => {
+            undos.push("undo:reserve");
+          },
+        });
+        return fail("Declined", {});
+      },
+    });
+
+    const result = await runDurable({ flow: pay, journalStore: store });
+    expect(result.status).toBe("failed");
+    expect(undos).toEqual(["undo:reserve"]);
+  });
+
+  test("runDurable refuses resume of failed runs", async () => {
+    const store = createMemoryJournalStore();
+    let runs = 0;
+    const pay = flow("pay.terminal", {
+      durable: true,
+      do: async () => {
+        runs += 1;
+        throw new Error("boom");
+      },
+    });
+    const first = await runDurable({ flow: pay, journalStore: store });
+    expect(first.status).toBe("failed");
+    expect(runs).toBe(1);
+    const second = await runDurable({
+      flow: pay,
+      journalStore: store,
+      runId: first.status === "failed" ? first.runId : "",
+    });
+    expect(second.status).toBe("failed");
+    expect(runs).toBe(1); // do must not re-enter
+  });
+
+  test("orphan mid-undo resumes compensating without forward re-entry", async () => {
+    const store = createMemoryJournalStore();
+    const forward: string[] = [];
+    const undos: string[] = [];
+    const now = () => 1_000;
+
+    const pay = flow("pay.midUndo", {
+      durable: true,
+      do: async (_input, fx) => {
+        await fx.step(
+          "reserve",
+          () => {
+            forward.push("reserve");
+            return "r";
+          },
+          {
+            undo: () => {
+              undos.push("undo:reserve");
+            },
+          },
+        );
+        await fx.step(
+          "charge",
+          () => {
+            forward.push("charge");
+            return "c";
+          },
+          {
+            undo: () => {
+              undos.push("undo:charge");
+            },
+          },
+        );
+        return true;
+      },
+    });
+
+    // Seed: forwards done, first undo journaled, status compensating (crash mid-phase).
+    await store.put({
+      id: "mid-undo",
+      flow: "pay.midUndo",
+      input: {},
+      status: "compensating",
+      error: "after_steps",
+      entries: [
+        { kind: "step", name: "reserve", value: "r", at: now() },
+        { kind: "step", name: "charge", value: "c", at: now() },
+        { kind: "step", name: "undo:charge", value: undefined, at: now() },
+      ],
+      createdAt: now(),
+      updatedAt: now(),
+    });
+
+    const second = await runDurable({
+      flow: pay,
+      journalStore: store,
+      runId: "mid-undo",
+      now,
+    });
+    expect(second.status).toBe("failed");
+    expect(forward).toEqual([]); // registration pass only — no new forward work
+    expect(undos).toEqual(["undo:reserve"]);
+    const names = (await store.get("mid-undo"))!.entries
+      .filter((e) => e.kind === "step")
+      .map((e) => (e as { name: string }).name);
+    expect(names).toEqual(["reserve", "charge", "undo:charge", "undo:reserve"]);
+  });
+
+  test("flow.retry does not undo between attempts", async () => {
+    const store = createMemoryJournalStore();
+    const undos: string[] = [];
+    let attempts = 0;
+
+    const pay = flow("pay.retryUndo", {
+      durable: true,
+      retry: { retries: 2, delay: 0, jitter: false },
+      do: async (_input, fx) => {
+        await fx.step("reserve", () => "ok", {
+          undo: () => {
+            undos.push("undo:reserve");
+          },
+        });
+        attempts += 1;
+        if (attempts < 3) throw new Error("transient");
+        return true;
+      },
+    });
+
+    const result = await runDurable({ flow: pay, journalStore: store });
+    expect(result.status).toBe("completed");
+    expect(undos).toEqual([]);
+    expect(attempts).toBe(3);
+  });
+
+  test("duplicate forward step name throws", async () => {
+    const store = createMemoryJournalStore();
+    const journal = createJournal({ store });
+    const session = await journal.start("dup");
+    await session.step("a", () => 1);
+    try {
+      await session.step("a", () => 2);
+      expect.unreachable();
+    } catch (err) {
+      expect(String(err)).toMatch(/duplicate step name/);
+    }
+  });
 });

package/src/kernel/compensate.ts

@@ -0,0 +1,126 @@
+/**
+ * Durable compensation phase — auto per-step undos then optional flow.compensate.
+ *
+ * Runs under the same journal session after terminal failure. Uses status
+ * `compensating` so orphan reclaim resumes undos instead of forward `do`.
+ */
+
+import type { AnyFlowDef } from "./flow.ts";
+import type { Fx } from "./fx.ts";
+import { isFlowFailure } from "./hooks.ts";
+import { JOURNAL_UNDO_PREFIX, type JournalSession, type JournalStepEntry } from "./journal.ts";
+
+/**
+ * Machine-readable code for journal / Runs failure fields.
+ *
+ * @param err - Thrown value or {@link FlowFailure}
+ */
+export function failureCodeOf(err: unknown): string {
+  if (isFlowFailure(err)) return err.error.code;
+  if (err instanceof Error && err.name && err.name !== "Error") return err.name;
+  if (err instanceof Error && err.message) return err.message.slice(0, 120);
+  return "Error";
+}
+
+/** Forward step names only (excludes journaled `undo:*` entries). */
+export function forwardCompletedSteps(session: JournalSession): readonly string[] {
+  return session.run.entries
+    .filter(
+      (e): e is JournalStepEntry => e.kind === "step" && !e.name.startsWith(JOURNAL_UNDO_PREFIX),
+    )
+    .map((e) => e.name);
+}
+
+/** Options for {@link runCompensationPhase}. */
+export interface RunCompensationPhaseOptions {
+  /** Flow definition (optional `compensate` hook). */
+  readonly flow: AnyFlowDef;
+  /** Original flow input. */
+  readonly input: unknown;
+  /** Active journal session. */
+  readonly session: JournalSession;
+  /** Fx bound to the same journal. */
+  readonly fx: Fx;
+  /** Terminal failure that triggered compensation. */
+  readonly error: unknown;
+}
+
+/**
+ * Enter compensating status, run LIFO per-step undos, then `flow.compensate`,
+ * and commit `failed`.
+ *
+ * @param options - Session, fx, terminal error
+ */
+export async function runCompensationPhase(options: RunCompensationPhaseOptions): Promise<void> {
+  const { flow, input, session, fx, error } = options;
+  const terminalCode = failureCodeOf(error);
+
+  if (session.run.status !== "compensating") {
+    await session.commit("compensating", { error: terminalCode });
+  }
+
+  session.setUndoExecution(true);
+  try {
+    const stack = [...session.undoStack()].reverse();
+    for (const frame of stack) {
+      const undoName = `${JOURNAL_UNDO_PREFIX}${frame.name}`;
+      await session.step(undoName, () => frame.undo(frame.value));
+    }
+
+    if (flow.compensate) {
+      try {
+        await flow.compensate(
+          {
+            input: input as never,
+            error,
+            completedSteps: forwardCompletedSteps(session),
+          },
+          fx,
+        );
+      } catch (compErr) {
+        await session.commit("failed", {
+          error: `compensate:${failureCodeOf(compErr)}`,
+        });
+        return;
+      }
+    }
+
+    if (session.run.status === "compensating" || session.run.status === "running") {
+      await session.commit("failed", { error: terminalCode });
+    }
+  } catch (undoErr) {
+    if (session.run.status !== "failed") {
+      await session.commit("failed", {
+        error: `compensate:${failureCodeOf(undoErr)}`,
+      });
+    }
+  } finally {
+    session.setUndoExecution(false);
+  }
+}
+
+/**
+ * Re-bind per-step undos by re-entering `do` without new forward work.
+ *
+ * @param flow - Flow definition
+ * @param input - Original input
+ * @param fx - Fx bound to the journal
+ * @param session - Compensating session
+ */
+export async function rebindUndosFromDo(
+  flow: AnyFlowDef,
+  input: unknown,
+  fx: Fx,
+  session: JournalSession,
+): Promise<void> {
+  session.rewind();
+  session.beginRegistrationPass();
+  try {
+    await flow.do(input as never, fx);
+  } catch {
+    // JournalRegistrationComplete = caught up with journaled forwards.
+    // Other throws while replaying between steps: keep whatever undos bound.
+  } finally {
+    session.endRegistrationPass();
+  }
+}

package/src/kernel/concurrency.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
 import { currentAbortSignal, isAbortError, withAbortSignal } from "./abort-scope.ts";
-import { createMemoryJournalStore } from "./journal.ts";
+import { createJournal, createMemoryJournalStore } from "./journal.ts";
 import { createFx, createFxContext } from "./fx.ts";
 import { flow } from "./flow.ts";
 import { runDurable } from "../elements/clock/durable.ts";
@@ -216,12 +216,11 @@ describe("retry + durable journal", () => {
   test("fx.retry inside fx.step does not re-run completed step on resume", async () => {
     const journalStore = createMemoryJournalStore();
     let attempts = 0;
-    let crash = true;
 
     const f = flow("pay.retry", {
       durable: true,
       do: async (_input, fx) => {
-        const charged = await fx.step("charge", () =>
+        return fx.step("charge", () =>
           fx.retry(
             async () => {
               attempts += 1;
@@ -230,20 +229,22 @@ describe("retry + durable journal", () => {
             { retries: 2, delay: 0 },
           ),
         );
-        if (crash) throw new Error("KILLED");
-        return charged;
       },
     });
 
-    const first = await runDurable({ flow: f, journalStore });
-    expect(first.status).toBe("failed");
+    // Simulate crash after the journaled step: leave status `running`.
+    const journal = createJournal({ store: journalStore });
+    const crashed = await journal.start("pay.retry");
+    await crashed.step("charge", () => {
+      attempts += 1;
+      return { id: "ch_1" };
+    });
     expect(attempts).toBe(1);
 
-    crash = false;
     const second = await runDurable({
       flow: f,
       journalStore,
-      runId: first.status === "failed" ? first.runId : "",
+      runId: crashed.runId,
     });
     expect(second.status).toBe("completed");
     expect(attempts).toBe(1);

package/src/kernel/effects-stamping.test.ts

@@ -91,8 +91,22 @@ describe("boot-level: undeclared-effects flow, no manifest / rootDir", () => {
     const create = buildUnannotatedCreateFlow(db);
     const app = oke({ name: "stamp-docker", gate: { policies: [gate.public] } }).adopt({ create });
 
+    const memoryDrivers = {
+      store: {
+        sql: { dev: "memory", prod: "memory" },
+        kv: { dev: "memory", prod: "memory" },
+      },
+      channel: { email: { dev: "console", prod: "console" } },
+    } as const;
     await expect(
-      app.boot({ env: "docker", stores: [db], unguardedHttp: "allow", startScheduler: false }),
+      app.boot({
+        env: "dev",
+        docker: true,
+        stores: [db],
+        unguardedHttp: "allow",
+        startScheduler: false,
+        config: { drivers: memoryDrivers },
+      }),
     ).rejects.toThrow(/OKE1008/);
   });
 
@@ -104,7 +118,18 @@ describe("boot-level: undeclared-effects flow, no manifest / rootDir", () => {
     const app = oke({ name: "stamp-prod", gate: { policies: [gate.public] } }).adopt({ create });
 
     await expect(
-      app.boot({ env: "prod", stores: [db], unguardedHttp: "allow", startScheduler: false }),
+      app.boot({
+        env: "prod",
+        stores: [db],
+        unguardedHttp: "allow",
+        startScheduler: false,
+        config: {
+          drivers: {
+            store: { sql: { prod: "memory" }, kv: { prod: "memory" } },
+            channel: { email: { prod: "console" } },
+          },
+        },
+      }),
     ).rejects.toThrow(/OKE1008/);
   });
 });

package/src/kernel/element-registries.ts

@@ -1,8 +1,8 @@
 /**
  * Module-evaluation registries for `store.sql` / `store.files`, `vault.secret`,
- * `signal()`, and `channel.<medium>().template()` — the plain arrays behind
- * each declare module's `listX()` / `resetX()` pair (mirrors `on.ts`'s
- * trigger-drain `bindings` array).
+ * `vault.env.required`, `signal()`, and `channel.<medium>().template()` — the
+ * plain arrays behind each declare module's `listX()` / `resetX()` pair
+ * (mirrors `on.ts`'s trigger-drain `bindings` array).
  *
  * Lives here, not in the declare modules themselves, so {@link oke} can read
  * every registry with one lightweight import instead of statically pulling
@@ -21,6 +21,8 @@ import type { ChannelTemplateDecl } from "../elements/channel/declare.ts";
 export const storeRegistry: StoreDecl[] = [];
 /** `vault.secret` declarations since the last reset. */
 export const secretRegistry: VaultSecretDecl[] = [];
+/** `vault.env.required(name)` environment variables since the last reset. */
+export const requiredEnvRegistry: string[] = [];
 /** `signal()` declarations since the last reset. */
 export const signalRegistry: SignalDecl[] = [];
 /** Medium-binder `.template()` declarations since the last reset. */

package/src/kernel/flow.ts

@@ -71,8 +71,10 @@ export interface FlowOptions<I = unknown, O = unknown, E extends FlowErrorMap =
   readonly breaking?: boolean;
   /**
    * Compensation phase after terminal failure on a durable flow.
-   * Runs under the same journal session before `commit("failed")`.
-   * Bodies must use distinct `fx.step("undo:…")` names — never reuse
+   * Runs under the same journal session after auto per-step `{ undo }`
+   * handlers and before `commit("failed")`. Prefer `fx.step(name, fn, { undo })`
+   * for step-local reverse work; use this hook for cross-cutting cleanup.
+   * Manual bodies must use distinct `fx.step("undo:…")` names — never reuse
    * forward step names. Never called on retryable attempts or sleep park.
    */
   readonly compensate?: (