okengine 0.3.5 → 0.4.3

package/src/kernel/concurrency.test.ts

@@ -0,0 +1,294 @@
+import { describe, expect, test } from "bun:test";
+
+import { currentAbortSignal, isAbortError, withAbortSignal } from "./abort-scope.ts";
+import { createMemoryJournalStore } from "./journal.ts";
+import { createFx, createFxContext } from "./fx.ts";
+import { flow } from "./flow.ts";
+import { runDurable } from "../elements/clock/durable.ts";
+import { fxAll, fxRace } from "./concurrency.ts";
+
+describe("fx.all — structured concurrency", () => {
+  test("resolves tuple results in order", async () => {
+    const fx = createFx({ flow: "t", effects: {} });
+    const out = await fx.all([async () => 1, async () => "a", () => true]);
+    expect(out).toEqual([1, "a", true]);
+  });
+
+  test("on failure aborts sibling branches via ambient signal", async () => {
+    const fx = createFx({ flow: "t", effects: {} });
+    let siblingAborted = false;
+    let loserSawAbort = false;
+
+    await expect(
+      fx.all([
+        async () => {
+          await new Promise<void>((_resolve, reject) => {
+            const signal = fx.signal;
+            if (signal.aborted) {
+              loserSawAbort = true;
+              reject(signal.reason ?? new Error("aborted"));
+              return;
+            }
+            signal.addEventListener(
+              "abort",
+              () => {
+                siblingAborted = true;
+                loserSawAbort = true;
+                reject(new DOMException("aborted", "AbortError"));
+              },
+              { once: true },
+            );
+            // Stay pending until aborted.
+          });
+        },
+        async () => {
+          await new Promise((r) => setTimeout(r, 5));
+          throw new Error("boom");
+        },
+      ]),
+    ).rejects.toThrow("boom");
+
+    expect(siblingAborted || loserSawAbort).toBe(true);
+  });
+
+  test("empty all resolves to []", async () => {
+    await expect(fxAll([])).resolves.toEqual([]);
+  });
+});
+
+describe("fx.race — structured concurrency", () => {
+  test("winner wins and loser sees abort", async () => {
+    const fx = createFx({ flow: "t", effects: {} });
+    let loserAborted = false;
+
+    const value = await fx.race([
+      async () => {
+        await new Promise<void>((_resolve, reject) => {
+          fx.signal.addEventListener(
+            "abort",
+            () => {
+              loserAborted = true;
+              reject(new DOMException("aborted", "AbortError"));
+            },
+            { once: true },
+          );
+        });
+        return "slow";
+      },
+      async () => {
+        await new Promise((r) => setTimeout(r, 5));
+        return "fast";
+      },
+    ]);
+
+    expect(value).toBe("fast");
+    // Give the abort listener a tick.
+    await new Promise((r) => setTimeout(r, 10));
+    expect(loserAborted).toBe(true);
+  });
+
+  test("empty race throws", async () => {
+    await expect(fxRace([])).rejects.toThrow(/empty/);
+  });
+});
+
+describe("fx.using — scoped cleanup", () => {
+  test("release runs on success and on thrown error", async () => {
+    const fx = createFx({ flow: "t", effects: {} });
+    const released: string[] = [];
+
+    const ok = await fx.using(
+      async () => "res-a",
+      (r) => {
+        released.push(`ok:${r}`);
+      },
+      async (r) => r.toUpperCase(),
+    );
+    expect(ok).toBe("RES-A");
+    expect(released).toEqual(["ok:res-a"]);
+
+    await expect(
+      fx.using(
+        async () => "res-b",
+        async (r) => {
+          released.push(`err:${r}`);
+        },
+        async () => {
+          throw new Error("boom");
+        },
+      ),
+    ).rejects.toThrow("boom");
+    expect(released).toEqual(["ok:res-a", "err:res-b"]);
+  });
+
+  test("release runs when a sibling fx.race winner aborts mid-use", async () => {
+    const fx = createFx({ flow: "t", effects: {} });
+    let released = false;
+
+    const winner = await fx.race([
+      () =>
+        fx.using(
+          async () => "lock",
+          () => {
+            released = true;
+          },
+          () =>
+            new Promise<never>(() => {
+              // Stay pending until ambient abort releases us.
+            }),
+        ),
+      async () => {
+        await new Promise((r) => setTimeout(r, 5));
+        return "fast";
+      },
+    ]);
+
+    expect(winner).toBe("fast");
+    // Let the abort listener settle.
+    await new Promise((r) => setTimeout(r, 20));
+    expect(released).toBe(true);
+  });
+});
+
+describe("fx.retry", () => {
+  test("retries then succeeds", async () => {
+    const fx = createFx({ flow: "t", effects: {} });
+    let n = 0;
+    const value = await fx.retry(
+      async () => {
+        n += 1;
+        if (n < 3) throw new Error("transient");
+        return "ok";
+      },
+      { retries: 3, delay: 0, jitter: false },
+    );
+    expect(value).toBe("ok");
+    expect(n).toBe(3);
+  });
+
+  test("does not retry AbortError", async () => {
+    const fx = createFx({ flow: "t", effects: {} });
+    let n = 0;
+    await expect(
+      fx.retry(
+        async () => {
+          n += 1;
+          throw new DOMException("aborted", "AbortError");
+        },
+        { retries: 3, delay: 0 },
+      ),
+    ).rejects.toMatchObject({ name: "AbortError" });
+    expect(n).toBe(1);
+  });
+
+  test("honors when predicate", async () => {
+    const fx = createFx({ flow: "t", effects: {} });
+    let n = 0;
+    await expect(
+      fx.retry(
+        async () => {
+          n += 1;
+          throw new Error("nope");
+        },
+        { retries: 5, delay: 0, when: () => false },
+      ),
+    ).rejects.toThrow("nope");
+    expect(n).toBe(1);
+  });
+});
+
+describe("ambient abort signal", () => {
+  test("outside scope is never aborted", () => {
+    const fx = createFx({ flow: "t", effects: {} });
+    expect(fx.signal.aborted).toBe(false);
+    expect(isAbortError(new DOMException("x", "AbortError"))).toBe(true);
+  });
+
+  test("withAbortSignal installs ambient signal", async () => {
+    const ctrl = new AbortController();
+    await withAbortSignal(ctrl.signal, async () => {
+      expect(currentAbortSignal()).toBe(ctrl.signal);
+    });
+  });
+});
+
+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({
+      name: "pay.retry",
+      durable: true,
+      do: async (_input, fx) => {
+        const charged = await fx.step("charge", () =>
+          fx.retry(
+            async () => {
+              attempts += 1;
+              return { id: "ch_1" };
+            },
+            { retries: 2, delay: 0 },
+          ),
+        );
+        if (crash) throw new Error("KILLED");
+        return charged;
+      },
+    });
+
+    const first = await runDurable({ flow: f, journalStore });
+    expect(first.status).toBe("failed");
+    expect(attempts).toBe(1);
+
+    crash = false;
+    const second = await runDurable({
+      flow: f,
+      journalStore,
+      runId: first.status === "failed" ? first.runId : "",
+    });
+    expect(second.status).toBe("completed");
+    expect(attempts).toBe(1);
+  });
+
+  test("flow({ retry }) reuses journal — completed steps do not re-run", async () => {
+    const journalStore = createMemoryJournalStore();
+    const calls: string[] = [];
+    let failOnce = true;
+
+    const f = flow({
+      name: "flow.retry",
+      durable: true,
+      retry: { retries: 2, delay: 0, jitter: false },
+      do: async (_input, fx) => {
+        await fx.step("a", () => {
+          calls.push("a");
+          return 1;
+        });
+        if (failOnce) {
+          failOnce = false;
+          throw new Error("transient");
+        }
+        return fx.step("b", () => {
+          calls.push("b");
+          return 2;
+        });
+      },
+    });
+
+    const result = await runDurable({ flow: f, journalStore });
+    expect(result.status).toBe("completed");
+    // step a ran once; flow-level retry re-entered do but journal replayed a.
+    expect(calls).toEqual(["a", "b"]);
+  });
+});
+
+describe("capability + concurrency compose", () => {
+  test("fx.all records effects from successful branches", async () => {
+    const { fx, ledger } = createFxContext({
+      flow: "parallel",
+      effects: { emits: ["a", "b"] },
+    });
+    await fx.all([() => fx.emit("a"), () => fx.emit("b")]);
+    expect(ledger.entries.map((e) => e.resource)).toEqual(["a", "b"]);
+  });
+});

package/src/kernel/concurrency.ts

@@ -0,0 +1,220 @@
+/**
+ * Structured concurrency and retry — plain Promise helpers for `fx`.
+ *
+ * No generators, no monadic wrapper. Branches are thunks so an AbortController
+ * can be installed before work starts. Retry backoff uses non-journaled sleep.
+ */
+
+import { parseDurationMs } from "../elements/clock/duration.ts";
+import {
+  abortableSleep,
+  abortError,
+  currentAbortSignal,
+  isAbortError,
+  linkAbort,
+  withAbortSignal,
+} from "./abort-scope.ts";
+import { isJournalSuspend } from "./journal.ts";
+
+/** A unit of work started under an abort scope. */
+export type FxThunk<T> = () => T | Promise<T>;
+
+/**
+ * Retry policy — same shape as the client transport, with duration strings
+ * and optional full jitter (no Schedule DSL).
+ */
+export interface FxRetryOptions {
+  /** Extra attempts after the first (default 0). */
+  readonly retries?: number;
+  /** Initial delay: ms number or duration string (default 50). */
+  readonly delay?: number | string;
+  /** Multiplier applied after each retry (default 2). */
+  readonly backoff?: number;
+  /** Full jitter on delay (default true). */
+  readonly jitter?: boolean;
+  /** Predicate; default retries thrown errors except abort / journal suspend. */
+  readonly when?: (err: unknown) => boolean;
+}
+
+/**
+ * Default retry filter — skip abort and durable-sleep park.
+ *
+ * @param err - Thrown value
+ */
+export function defaultRetryWhen(err: unknown): boolean {
+  if (isAbortError(err)) return false;
+  if (isJournalSuspend(err)) return false;
+  return true;
+}
+
+/**
+ * Resolve a delay option to milliseconds.
+ *
+ * @param delay - Number or duration string
+ * @param fallback - Default ms
+ */
+export function resolveRetryDelayMs(delay: number | string | undefined, fallback = 50): number {
+  if (delay === undefined) return fallback;
+  if (typeof delay === "number") return Math.max(0, delay);
+  const parsed = parseDurationMs(delay);
+  return parsed > 0 ? parsed : fallback;
+}
+
+/**
+ * Run thunks in parallel; on first rejection abort siblings and rethrow.
+ *
+ * @param thunks - Work units (not already-started Promises)
+ */
+export async function fxAll<const T extends readonly unknown[]>(thunks: {
+  readonly [K in keyof T]: FxThunk<T[K]>;
+}): Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }> {
+  const list = thunks as readonly FxThunk<unknown>[];
+  if (list.length === 0) {
+    return [] as { -readonly [K in keyof T]: Awaited<T[K]> };
+  }
+
+  const parent = currentAbortSignal();
+  const controllers = list.map(() => new AbortController());
+  const unsubs = controllers.map((c) => linkAbort(parent, c));
+
+  let firstError: unknown;
+  const results = await Promise.allSettled(
+    list.map((thunk, i) =>
+      withAbortSignal(controllers[i]!.signal, async () => {
+        try {
+          return await thunk();
+        } catch (err) {
+          if (firstError === undefined) {
+            firstError = err;
+            for (let j = 0; j < controllers.length; j++) {
+              if (j !== i) controllers[j]!.abort(err);
+            }
+          }
+          throw err;
+        }
+      }),
+    ),
+  );
+
+  for (const unsub of unsubs) unsub();
+
+  if (firstError !== undefined) throw firstError;
+  const values: unknown[] = [];
+  for (const r of results) {
+    if (r.status === "rejected") throw r.reason;
+    values.push(r.value);
+  }
+  return values as { -readonly [K in keyof T]: Awaited<T[K]> };
+}
+
+/**
+ * Race thunks; the first settle wins and siblings are aborted.
+ *
+ * @param thunks - Work units
+ */
+export async function fxRace<T>(thunks: ReadonlyArray<FxThunk<T>>): Promise<T> {
+  if (thunks.length === 0) {
+    throw new TypeError("fx.race: empty thunk list");
+  }
+
+  const parent = currentAbortSignal();
+  const controllers = thunks.map(() => new AbortController());
+  const unsubs = controllers.map((c) => linkAbort(parent, c));
+
+  return new Promise<T>((resolve, reject) => {
+    let done = false;
+    const settle = (ok: boolean, value: unknown): void => {
+      if (done) return;
+      done = true;
+      for (const c of controllers) {
+        if (!c.signal.aborted) c.abort();
+      }
+      for (const unsub of unsubs) unsub();
+      if (ok) resolve(value as T);
+      else reject(value);
+    };
+
+    for (let i = 0; i < thunks.length; i++) {
+      const thunk = thunks[i]!;
+      const ctrl = controllers[i]!;
+      void withAbortSignal(ctrl.signal, () => Promise.resolve().then(thunk)).then(
+        (value) => settle(true, value),
+        (err: unknown) => settle(false, err),
+      );
+    }
+  });
+}
+
+/**
+ * Scope a resource to a unit of work — `release` runs exactly once when
+ * `use` settles or when the ambient abort signal fires, whichever comes
+ * first. Uses the same AbortSignal as {@link Fx.signal}; no second
+ * cancellation channel.
+ *
+ * Process-local only: do not journal acquire/release, and do not hold
+ * handles across durable park/resume — journal replay returns values and
+ * never re-enters step bodies.
+ *
+ * @param acquire - Open the resource
+ * @param release - Cleanup, always run
+ * @param use - Work with the resource
+ */
+export async function fxUsing<A, T>(
+  acquire: () => A | Promise<A>,
+  release: (resource: A) => void | Promise<void>,
+  use: (resource: A) => T | Promise<T>,
+): Promise<T> {
+  const resource = await acquire();
+  const signal = currentAbortSignal();
+  let released = false;
+
+  const releaseOnce = async (): Promise<void> => {
+    if (released) return;
+    released = true;
+    await release(resource);
+  };
+
+  const onAbort = (): void => {
+    void releaseOnce();
+  };
+
+  if (signal.aborted) {
+    await releaseOnce();
+    throw abortError(signal.reason);
+  }
+  signal.addEventListener("abort", onAbort);
+
+  try {
+    return await use(resource);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+    await releaseOnce();
+  }
+}
+
+/**
+ * Retry a thunk with exponential backoff and optional full jitter.
+ *
+ * @param fn - Operation
+ * @param opts - Retry policy
+ */
+export async function fxRetry<T>(fn: FxThunk<T>, opts: FxRetryOptions = {}): Promise<T> {
+  const retries = Math.max(0, opts.retries ?? 0);
+  const backoff = opts.backoff ?? 2;
+  const jitter = opts.jitter !== false;
+  const when = opts.when ?? defaultRetryWhen;
+  let delayMs = resolveRetryDelayMs(opts.delay, 50);
+  let attempt = 0;
+
+  for (;;) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (attempt >= retries || !when(err)) throw err;
+      const wait = jitter ? Math.random() * delayMs : delayMs;
+      await abortableSleep(wait, currentAbortSignal());
+      delayMs *= backoff;
+      attempt += 1;
+    }
+  }
+}

package/src/kernel/flow.ts

@@ -8,6 +8,7 @@
 
 import type { Effects, FlowPlane, Slo } from "../manifest/types.ts";
 import type { InferSchemaOutput, SchemaInput } from "../validation/standard-schema.ts";
+import type { FxRetryOptions } from "./concurrency.ts";
 import type { FlowFailure } from "./errors.ts";
 import type { Fx } from "./fx.ts";
 import type { HookFn, HookStage } from "./hooks.ts";
@@ -51,6 +52,11 @@ export interface FlowOptions<I = unknown, O = unknown, E extends FlowErrorMap =
   readonly effects?: Effects;
   /** Journal every effect call. */
   readonly durable?: boolean;
+  /**
+   * Retry the whole `do` body on thrown errors (same journal session when
+   * durable). Prefer {@link Fx.retry} inside {@link Fx.step} for fine control.
+   */
+  readonly retry?: FxRetryOptions;
   /** Live-query / push result. */
   readonly live?: boolean;
   /** Cache TTL (`true` = default policy, or a duration string). */
@@ -147,6 +153,8 @@ export interface FlowDef<
   readonly effects: Effects | undefined;
   /** Durability flag. */
   readonly durable: boolean;
+  /** Whole-body retry policy (runtime). */
+  readonly retry: FxRetryOptions | undefined;
   /** Live flag. */
   readonly live: boolean;
   /** Cache option. */
@@ -222,6 +230,7 @@ export function flow<Opts extends FlowOptions<any, any, any>>(
     errors: (options.errors ?? undefined) as InferFlowErrors<Opts> | undefined,
     effects: options.effects,
     durable: options.durable ?? false,
+    retry: options.retry,
     live: options.live ?? false,
     cache: options.cache,
     slo: options.slo,

package/src/kernel/fx.test.ts

@@ -9,6 +9,7 @@ import {
   type Fx,
   type FxStubStoreHandle,
 } from "./fx.ts";
+import { Redacted } from "./redacted.ts";
 
 /** Narrow stub handle for tests that exercise the in-memory store. */
 function stub(fx: Fx, ref: string): FxStubStoreHandle {
@@ -99,7 +100,7 @@ describe("fx — effect ledger", () => {
     await fx.emit("order-placed", {});
     await fx.send("order-confirmed", { to: "u1" });
     await fx.ask("triage@1", {});
-    expect(fx.vault("STRIPE_KEY")).toBe("sk_test");
+    expect(fx.vault("STRIPE_KEY").reveal()).toBe("sk_test");
     await fx.call("payments.charge", {});
 
     expect(ledger.entries).toHaveLength(7);
@@ -130,7 +131,7 @@ describe("fx — wholesale swap", () => {
         sleep: async () => undefined,
       },
       vault() {
-        return "";
+        return new Redacted("");
       },
       cache: {
         get: async () => undefined,
@@ -181,6 +182,26 @@ describe("fx — wholesale swap", () => {
       async step(_name, fn) {
         return fn();
       },
+      get signal() {
+        return new AbortController().signal;
+      },
+      all(thunks) {
+        return Promise.all(thunks.map((t) => t())) as never;
+      },
+      race(thunks) {
+        return Promise.race(thunks.map((t) => t()));
+      },
+      retry(fn) {
+        return Promise.resolve().then(fn);
+      },
+      async using(acquire, release, use) {
+        const resource = await acquire();
+        try {
+          return await use(resource);
+        } finally {
+          await release(resource);
+        }
+      },
     };
 
     // Any code that accepts `Fx` can run against a total replacement.