okengine 0.10.3 → 0.11.0

package/src/kernel/boot.test.ts

@@ -130,8 +130,9 @@ describe("boot — lazy element needs", () => {
       // + `tryListFlowsUnits` in `boot.ts` (`.adopt()` barrel staleness
       // check, OKE1009) — part of the already-lazily-loaded boot graph, not
       // the `oke()` construction path, but `Bun.build` still traces and
-      // sums the dynamic-import chunk (~54.3 kB → 54.7 kB cap).
-      expect(total).toBeLessThan(54_700);
+      // sums the dynamic-import chunk (~54.3 kB → 54.7 kB → 55.0 kB after
+      // ConfigEnv local/docker → dev/test/prod + sqlite removal).
+      expect(total).toBeLessThan(55_000);
     } finally {
       await rm(dir, { recursive: true, force: true });
     }
@@ -273,11 +274,18 @@ describe("boot — cron autostart via real timer loop", () => {
       }),
     );
 
-    // env: "local" → startScheduler defaults ON. No createTestApp / advance.
+    // Non-test env → startScheduler defaults ON. No createTestApp / advance.
     const app = oke({
       name: "cron-autostart",
-      env: "local",
+      env: "dev",
       schedulerIntervalMs: 1000,
+      config: {
+        drivers: {
+          clock: { dev: "memory" },
+          store: { sql: { dev: "memory" }, kv: { dev: "memory" } },
+          channel: { email: { dev: "console" } },
+        },
+      },
     });
     await app.boot();
 

package/src/kernel/boot.ts

@@ -216,7 +216,9 @@ export interface ElementNeeds {
 export function resolveElementNeeds(options: BootOptions): ElementNeeds {
   const pre = options.elements ?? {};
   let vault =
-    pre.vault !== undefined || (options.vault?.secrets ?? options.secrets ?? []).length > 0;
+    pre.vault !== undefined ||
+    (options.vault?.secrets ?? options.secrets ?? []).length > 0 ||
+    (options.vault?.requiredEnv?.length ?? 0) > 0;
   let store = pre.store !== undefined || (options.stores?.length ?? 0) > 0;
   let signal = pre.signal !== undefined || (options.signals?.length ?? 0) > 0;
   let clock = pre.clock !== undefined || (options.clocks?.length ?? 0) > 0;
@@ -283,9 +285,10 @@ async function loadBind<T>(name: string): Promise<T> {
 export async function bootApplication(input: BootOptions = {}): Promise<BootResult> {
   const docker =
     input.docker === true || (input.docker !== false && process.env.OKE_DOCKER === "1");
-  // `-d` always selects the `docker` driver profile — not a mix of local/test +
-  // prod store overrides when `$options.env` is unset.
-  const env: ConfigEnv = input.env ?? (docker ? "docker" : "local");
+  // Three targets: `prod` when NODE_ENV=production; `dev` when compose infra
+  // is up (`oke dev` / `OKE_DOCKER=1`); otherwise `test` (PGLite / memory).
+  const env: ConfigEnv =
+    input.env ?? (process.env.NODE_ENV === "production" ? "prod" : docker ? "dev" : "test");
   let config = input.config;
   if (config === undefined) {
     try {
@@ -482,12 +485,13 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   const capabilities = await mintCapabilities(options.flows ?? [], env, {
     manifest: options.manifest,
     rootDir: options.rootDir,
+    docker,
   });
 
   // 9. `.adopt()` barrel freshness — opt-in only (same `rootDir` gate as
   // capability minting above; never a filesystem read the kernel performs
   // on its own).
-  await assertAdoptBarrelFresh(options.flows ?? [], env, options.rootDir);
+  await assertAdoptBarrelFresh(options.flows ?? [], env, options.rootDir, docker);
 
   return {
     vault,
@@ -556,10 +560,9 @@ async function tryAutoExtractManifest(rootDir: string): Promise<Manifest | undef
  * an explicit {@link BootOptions.manifest}, or a lazy AoT extract from
  * {@link BootOptions.rootDir} / `OKE_ROOT_DIR`.
  *
- * When neither is available: `local` / `test` stay open (today's dev-loop
- * behavior, unbroken) with a once-per-process `oke boot:` warning; `docker`
- * / `prod` fail loud (`OKE1008`) — docker mirrors prod's posture, never a
- * silent open door in a deploy-shaped environment.
+ * When neither is available: `test` stays open with a once-per-process
+ * `oke boot:` warning; `dev` with compose infra and `prod` fail loud
+ * (`OKE1008`) — never a silent open door in a deploy-shaped environment.
  *
  * @param flows - Adopted flows
  * @param env - Resolved {@link ConfigEnv}
@@ -567,8 +570,12 @@ async function tryAutoExtractManifest(rootDir: string): Promise<Manifest | undef
  */
 export async function mintCapabilities(
   flows: readonly AnyFlowDef[],
-  env: ConfigEnv = "local",
-  options: { readonly manifest?: Manifest; readonly rootDir?: string } = {},
+  env: ConfigEnv = "test",
+  options: {
+    readonly manifest?: Manifest;
+    readonly rootDir?: string;
+    readonly docker?: boolean;
+  } = {},
 ): Promise<Map<string, CapabilityToken>> {
   const map = new Map<string, CapabilityToken>();
 
@@ -591,7 +598,8 @@ export async function mintCapabilities(
       continue;
     }
 
-    if (env === "docker" || env === "prod") {
+    const strict = env === "prod" || (env === "dev" && options.docker === true);
+    if (strict) {
       throwOke("NO_EFFECTS_DECLARED", { flow: f.name });
     }
     if (!noEffectsWarned) {
@@ -600,7 +608,7 @@ export async function mintCapabilities(
         `oke boot: flow "${f.name}" (and possibly others) has no declared effects and no ` +
           "Manifest-derived effects — running with an OPEN capability token (every access " +
           "allowed, ledgered but not gated). Run `oke build`, or boot with `manifest` / " +
-          "`rootDir`, before deploying — docker/prod refuse to boot this way.",
+          "`rootDir`, before deploying — dev+compose/prod refuse to boot this way.",
       );
     }
     map.set(f.name, createCapabilityToken(f.name, undefined));
@@ -645,18 +653,21 @@ async function tryListFlowsUnits(rootDir: string): Promise<readonly string[] | u
  *
  * Opt-in only via {@link BootOptions.rootDir} / `OKE_ROOT_DIR` (same gate as
  * {@link mintCapabilities}'s Manifest fallback) — never a filesystem read
- * the kernel performs on its own. `local` / `test` warn once per process;
- * `docker` / `prod` fail loud (`OKE1009`) — same class as `NO_EFFECTS_DECLARED`,
- * never a silently-incomplete route table in a deploy-shaped environment.
+ * the kernel performs on its own. `test` warns once per process; `prod`
+ * (and `dev` with compose) fail loud (`OKE1009`) — same class as
+ * `NO_EFFECTS_DECLARED`, never a silently-incomplete route table in a
+ * deploy-shaped environment.
  *
  * @param flows - Adopted flows
  * @param env - Resolved {@link ConfigEnv}
  * @param rootDir - Explicit project root (falls back to `OKE_ROOT_DIR`)
+ * @param docker - Compose infra active (`oke dev`)
  */
 export async function assertAdoptBarrelFresh(
   flows: readonly AnyFlowDef[],
-  env: ConfigEnv = "local",
+  env: ConfigEnv = "test",
   rootDir?: string,
+  docker = false,
 ): Promise<void> {
   const dir = rootDir ?? process.env["OKE_ROOT_DIR"];
   if (!dir) return;
@@ -670,7 +681,8 @@ export async function assertAdoptBarrelFresh(
   const missing = diskUnits.filter((u) => !adoptedUnits.has(u));
   if (missing.length === 0) return;
 
-  if (env === "docker" || env === "prod") {
+  const strict = env === "prod" || (env === "dev" && docker);
+  if (strict) {
     throwOke("ADOPT_BARREL_STALE", { unit: missing[0]! });
   }
   if (!staleAdoptBarrelWarned) {
@@ -678,7 +690,7 @@ export async function assertAdoptBarrelFresh(
     emitBootWarn(
       `oke boot: src/flows/${missing[0]} exists on disk but adopted no flows — the ` +
         '.adopt() barrel ("src/flows/generated.ts") is stale. Run `oke dev` or `oke build` ' +
-        "to regenerate it — docker/prod refuse to boot this way.",
+        "to regenerate it — dev+compose/prod refuse to boot this way.",
     );
   }
 }

package/src/kernel/budget-entry.ts

@@ -14,7 +14,7 @@ import { flow } from "./flow.ts";
 import { createFx } from "./fx.ts";
 import { mergeHooks, runPipeline } from "./hooks.ts";
 import { on, resetBindings } from "./on.ts";
-import { createRouter } from "./router.ts";
+import { createEdgeRouter as createRouter } from "./router/create-edge.ts";
 import { http } from "./triggers.ts";
 
 /**

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);