okengine 0.3.5 → 0.3.6

package/src/elements/store/declare.ts

@@ -40,6 +40,8 @@ export interface StoreDeclBase {
 
 /** Options for {@link store.sql}. */
 export interface SqlStoreOptions {
+  /** Optional human description for Console / docs (falls back to the store name). */
+  readonly description?: string;
   /**
    * Schema tables — okengine {@link TableHandle}s and/or Drizzle tables.
    * Classification is read from TableHandle columns when present.
@@ -56,6 +58,7 @@ export interface SqlStoreOptions {
 export interface SqlStoreDecl extends StoreDeclBase {
   readonly facet: "sql";
   readonly ref: `sql:${string}`;
+  readonly description?: string;
   readonly schema?: SqlStoreOptions["schema"];
   readonly classify?: SqlStoreOptions["classify"];
   /**
@@ -94,6 +97,8 @@ export interface FilesStoreDecl extends StoreDeclBase {
 
 /** Options for {@link store.index}. */
 export interface IndexStoreOptions {
+  /** Optional human description for Console / docs (falls back to the index name). */
+  readonly description?: string;
   /** Vector dimensions (default 3 for tests; set explicitly in apps). */
   readonly dims?: number;
 }
@@ -102,6 +107,7 @@ export interface IndexStoreOptions {
 export interface IndexStoreDecl extends StoreDeclBase {
   readonly facet: "index";
   readonly ref: `index:${string}`;
+  readonly description?: string;
   readonly dims?: number;
 }
 
@@ -119,6 +125,7 @@ export function sql(name: string, options: SqlStoreOptions = {}): SqlStoreDecl {
     facet: "sql",
     name,
     ref: `sql:${name}`,
+    ...(options.description !== undefined ? { description: options.description } : {}),
     schema: options.schema,
     classify: options.classify,
     table(table) {
@@ -147,7 +154,7 @@ export function kv(name: string, options: KvStoreOptions = {}): KvStoreDecl {
     facet: "kv",
     name,
     ref: `kv:${name}`,
-    description: options.description,
+    ...(options.description !== undefined ? { description: options.description } : {}),
   };
 }
 
@@ -162,7 +169,7 @@ export function files(name: string, options: FilesStoreOptions = {}): FilesStore
     facet: "files",
     name,
     ref: `files:${name}`,
-    description: options.description,
+    ...(options.description !== undefined ? { description: options.description } : {}),
   };
 }
 
@@ -177,6 +184,7 @@ export function index(name: string, options: IndexStoreOptions = {}): IndexStore
     facet: "index",
     name,
     ref: `index:${name}`,
+    ...(options.description !== undefined ? { description: options.description } : {}),
     dims: options.dims,
   };
 }

package/src/elements/store/index-boot.test.ts

@@ -0,0 +1,257 @@
+/**
+ * End-to-end `store.index()` boot wiring — the CONFIGURED driver resolves at
+ * real boot for every backend (memory / libsql / pgvector over pglite /
+ * pgvector over real Postgres), SQL-backed indexes share store.sql's
+ * already-open connection (never a second, redundant one), and search runs
+ * through each engine's native ANN index — no JS-side full scan survives.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  connectLibsql,
+  libsqlDriver,
+  libsqlIndexDriver,
+  openLibsqlIndex,
+} from "../../drivers/libsql.ts";
+import { connectPglite } from "../../drivers/pglite.ts";
+import { openPgvectorIndex } from "../../drivers/pgvector.ts";
+import { connectPostgres } from "../../drivers/postgres.ts";
+import type { SqlConnection, SqlDriver } from "../../drivers/types.ts";
+import { bindStore } from "../../kernel/boot-bind/store.ts";
+import {
+  createStoreRuntime,
+  index as declareIndex,
+  sql as declareSql,
+  type IndexStoreFxHandle,
+  type SqlStoreHandle,
+} from "../store.ts";
+
+const WRITE_CTX = (name: string) => ({
+  effects: { reads: [`index:${name}` as const], writes: [`index:${name}` as const] },
+});
+
+const prev = {
+  libsql: process.env.OKE_LIBSQL_URL,
+  pglite: process.env.OKE_PGLITE_URL,
+};
+
+afterEach(() => {
+  if (prev.libsql === undefined) delete process.env.OKE_LIBSQL_URL;
+  else process.env.OKE_LIBSQL_URL = prev.libsql;
+  if (prev.pglite === undefined) delete process.env.OKE_PGLITE_URL;
+  else process.env.OKE_PGLITE_URL = prev.pglite;
+});
+
+/** Wrap a real connection so the SQL it executes can be asserted on. */
+function recordingConn(conn: SqlConnection): { conn: SqlConnection; statements: string[] } {
+  const statements: string[] = [];
+  return {
+    statements,
+    conn: {
+      driverId: conn.driverId,
+      role: conn.role,
+      query: (sql, params) => {
+        statements.push(sql);
+        return conn.query(sql, params);
+      },
+      exec: (sql, params) => {
+        statements.push(sql);
+        return conn.exec(sql, params);
+      },
+      close: () => conn.close(),
+    },
+  };
+}
+
+describe("store.index boot wiring — memory", () => {
+  test("boot with no configured index driver resolves memory end to end", async () => {
+    const kb = declareIndex("kb", { dims: 3 });
+    const runtime = bindStore({ stores: [kb] }, "local", () => Date.now());
+    const handle = (await runtime.open(kb, WRITE_CTX("kb"))) as IndexStoreFxHandle;
+    expect(handle.driverId).toBe("memory");
+    await handle.upsert("near", [1, 0, 0]);
+    await handle.upsert("far", [0, 1, 0]);
+    const hits = await handle.search([1, 0, 0], 2);
+    expect(hits[0]?.id).toBe("near");
+    await runtime.close();
+  });
+});
+
+describe("store.index boot wiring — libsql", () => {
+  test("boot: sql=libsql + index=libsql resolves native ANN end to end", async () => {
+    process.env.OKE_LIBSQL_URL = ":memory:";
+    const kb = declareIndex("kb", { dims: 3 });
+    const runtime = bindStore(
+      {
+        config: { drivers: { store: { sql: { local: "libsql" }, index: { local: "libsql" } } } },
+        stores: [kb],
+      },
+      "local",
+      () => Date.now(),
+    );
+    const handle = (await runtime.open(kb, WRITE_CTX("kb"))) as IndexStoreFxHandle;
+    expect(handle.driverId).toBe("libsql");
+
+    await handle.upsert("near", [1, 0.1, 0], { label: "near" });
+    await handle.upsert("far", [0, 1, 0]);
+    await handle.upsert("farther", [-1, 0, 0]);
+    const hits = await handle.search([1, 0, 0], 3);
+    expect(hits.map((h) => h.id)).toEqual(["near", "far", "farther"]);
+    expect(hits[0]!.score).toBeGreaterThan(hits[1]!.score);
+    expect(hits[0]!.meta).toEqual({ label: "near" });
+    expect(await handle.delete("farther")).toBe(true);
+    await runtime.close();
+  });
+
+  test("sql and index facets share one already-open libsql connection", async () => {
+    let connects = 0;
+    const countingLibsql: SqlDriver = {
+      ...libsqlDriver,
+      connect: async (opts) => {
+        connects++;
+        return libsqlDriver.connect(opts);
+      },
+    };
+    const docs = declareSql("docs");
+    const kb = declareIndex("kb", { dims: 3 });
+    const runtime = createStoreRuntime({
+      drivers: { sql: countingLibsql, index: libsqlIndexDriver },
+      sql: { docs: { name: "docs", primary: { url: ":memory:" } } },
+      index: { kb: { url: ":memory:" } },
+    });
+    // Index first: it must open the connection the sql facet then reuses.
+    const idxHandle = (await runtime.open(kb, WRITE_CTX("kb"))) as IndexStoreFxHandle;
+    await idxHandle.upsert("a", [1, 0, 0]);
+    const sqlHandle = (await runtime.open(docs, {
+      effects: { reads: ["sql:docs"], writes: ["sql:docs"] },
+    })) as SqlStoreHandle;
+    await sqlHandle.raw("CREATE TABLE IF NOT EXISTS t_share (id TEXT)", []);
+    expect(connects).toBe(1);
+    await runtime.close();
+  });
+
+  test("libsql index searches through vector_top_k — real ANN, not a scan", async () => {
+    const real = await connectLibsql({ url: ":memory:" });
+    const { conn, statements } = recordingConn(real);
+    const idx = await openLibsqlIndex({ name: "ann", dims: 3, sql: conn });
+    await idx.upsert("x", [1, 0, 0]);
+    await idx.upsert("y", [0, 1, 0]);
+    const hits = await idx.search([1, 0, 0], 1);
+    expect(hits[0]?.id).toBe("x");
+    expect(statements.some((s) => s.includes("libsql_vector_idx"))).toBe(true);
+    expect(statements.some((s) => s.includes("vector_top_k"))).toBe(true);
+    const plan = await real.query(
+      `EXPLAIN QUERY PLAN SELECT * FROM vector_top_k('oke_idx_ann_vec', vector32('[1,0,0]'), 1)`,
+    );
+    expect(JSON.stringify(plan)).toContain("vector_top_k");
+    await idx.close();
+    await real.close();
+  });
+});
+
+describe("store.index boot wiring — pglite + pgvector", () => {
+  test("boot: sql=pglite + index=pgvector resolves end to end", async () => {
+    process.env.OKE_PGLITE_URL = "memory://";
+    const kb = declareIndex("kb", { dims: 3 });
+    const runtime = bindStore(
+      {
+        config: { drivers: { store: { sql: { local: "pglite" }, index: { local: "pgvector" } } } },
+        stores: [kb],
+      },
+      "local",
+      () => Date.now(),
+    );
+    const handle = (await runtime.open(kb, WRITE_CTX("kb"))) as IndexStoreFxHandle;
+    expect(handle.driverId).toBe("pgvector");
+
+    await handle.upsert("near", [1, 0.1, 0], { label: "near" });
+    await handle.upsert("far", [0, 1, 0]);
+    await handle.upsert("farther", [-1, 0, 0]);
+    const hits = await handle.search([1, 0, 0], 3);
+    expect(hits.map((h) => h.id)).toEqual(["near", "far", "farther"]);
+    expect(hits[0]!.score).toBeGreaterThan(hits[1]!.score);
+    expect(hits[0]!.meta).toEqual({ label: "near" });
+    expect(await handle.delete("farther")).toBe(true);
+    await runtime.close();
+  });
+
+  test("pglite runs the shared pgvector HNSW path — real ANN, not a scan", async () => {
+    const real = await connectPglite({ url: "memory://" });
+    const { conn, statements } = recordingConn(real);
+    const idx = await openPgvectorIndex({ name: "ann", dims: 3, sql: conn });
+    await idx.upsert("a", [1, 0, 0]);
+    await idx.upsert("b", [0, 1, 0]);
+    const hits = await idx.search([1, 0, 0], 2);
+    expect(hits[0]?.id).toBe("a");
+    expect(statements.some((s) => s.includes("CREATE EXTENSION IF NOT EXISTS vector"))).toBe(true);
+    expect(
+      statements.some((s) => s.includes("USING hnsw") && s.includes("vector_cosine_ops")),
+    ).toBe(true);
+    expect(statements.some((s) => s.includes("<=>"))).toBe(true);
+    const indexes = await real.query(
+      `SELECT indexdef FROM pg_indexes WHERE tablename = 'oke_idx_ann'`,
+    );
+    expect(JSON.stringify(indexes)).toContain("USING hnsw");
+    await idx.close();
+    await real.close();
+  });
+});
+
+describe("store.index boot wiring — fail loud", () => {
+  test("pgvector index with memory sql driver throws — never silently memory", async () => {
+    const kb = declareIndex("kb", { dims: 3 });
+    const runtime = bindStore(
+      {
+        config: { drivers: { store: { sql: { local: "memory" }, index: { local: "pgvector" } } } },
+        stores: [kb],
+      },
+      "local",
+      () => Date.now(),
+    );
+    await expect(runtime.open(kb, WRITE_CTX("kb"))).rejects.toThrow(/cannot share sql driver/);
+    await runtime.close();
+  });
+
+  test("libsql index with sqlite sql driver throws", async () => {
+    const kb = declareIndex("kb", { dims: 3 });
+    const runtime = bindStore(
+      {
+        config: { drivers: { store: { sql: { local: "sqlite" }, index: { local: "libsql" } } } },
+        stores: [kb],
+      },
+      "local",
+      () => Date.now(),
+    );
+    await expect(runtime.open(kb, WRITE_CTX("kb"))).rejects.toThrow(/cannot share sql driver/);
+    await runtime.close();
+  });
+});
+
+const PGVECTOR_URL = process.env.OKE_TEST_PGVECTOR_URL;
+if (!PGVECTOR_URL) {
+  console.log("skip: live pgvector e2e (OKE_TEST_PGVECTOR_URL not set)");
+}
+const liveTest = PGVECTOR_URL ? test : test.skip;
+
+describe("store.index boot wiring — real Postgres pgvector", () => {
+  liveTest("live Postgres runs real HNSW ANN, not a scan", async () => {
+    const real = await connectPostgres({ url: PGVECTOR_URL });
+    const { conn, statements } = recordingConn(real);
+    const idx = await openPgvectorIndex({ name: "live", dims: 3, sql: conn });
+    await idx.upsert("near", [1, 0.1, 0]);
+    await idx.upsert("far", [0, 1, 0]);
+    await idx.upsert("farther", [-1, 0, 0]);
+    const hits = await idx.search([1, 0, 0], 3);
+    expect(hits.map((h) => h.id)).toEqual(["near", "far", "farther"]);
+    expect(statements.some((s) => s.includes("CREATE EXTENSION IF NOT EXISTS vector"))).toBe(true);
+    expect(statements.some((s) => s.includes("USING hnsw"))).toBe(true);
+    expect(statements.some((s) => s.includes("<=>"))).toBe(true);
+    const indexes = await real.query(
+      `SELECT indexdef FROM pg_indexes WHERE tablename = 'oke_idx_live'`,
+    );
+    expect(JSON.stringify(indexes)).toContain("USING hnsw");
+    await idx.delete("farther");
+    await idx.close();
+    await real.close();
+  });
+});

package/src/elements/store/runtime.ts

@@ -14,7 +14,9 @@ import type {
   KvDriver,
   KvNamespace,
   SqlConnection,
+  SqlConnectOptions,
   SqlDriver,
+  SqlRole,
   SqlRow,
 } from "../../drivers/types.ts";
 import { buildClassificationMap, type MaskRowsOptions } from "./classify.ts";
@@ -116,7 +118,7 @@ export interface FilesStoreFxHandle {
 /** Index handle on `fx.store`. */
 export interface IndexStoreFxHandle {
   readonly ref: `index:${string}`;
-  readonly driverId: "memory" | "pgvector";
+  readonly driverId: "memory" | "pgvector" | "libsql";
   upsert(id: string, vector: readonly number[], meta?: Record<string, unknown>): Promise<void>;
   search(
     vector: readonly number[],
@@ -186,6 +188,19 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
   const kvNs = new Map<string, KvNamespace>();
   const fileBuckets = new Map<string, FilesBucket>();
   const indexes = new Map<string, IndexStore>();
+  const clientIds = new WeakMap<object, number>();
+  let nextClientId = 0;
+
+  /** Injected test clients with the same URL still get distinct cache entries. */
+  function clientTag(client: unknown): string {
+    if ((typeof client !== "object" && typeof client !== "function") || client === null) return "";
+    let id = clientIds.get(client as object);
+    if (id === undefined) {
+      id = ++nextClientId;
+      clientIds.set(client as object, id);
+    }
+    return `#c${id}`;
+  }
 
   function classificationsFor(decl: SqlStoreDecl): ClassificationMap {
     const nested: Record<
@@ -215,13 +230,7 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
     const driver = options.drivers.sql;
     if (!driver) throw new Error("No sql driver configured");
 
-    const cacheKey = `${decl.name}:${target.role}:${JSON.stringify(target.options.url ?? "")}`;
-    let conn = sqlConns.get(cacheKey);
-    if (!conn) {
-      conn = await driver.connect(target.options);
-      sqlConns.set(cacheKey, conn);
-    }
-
+    const conn = await sharedSqlConn(driver, target.role, target.options);
     return createSqlStoreHandle(`sql:${decl.name}`, {
       connection: conn,
       classifications: classificationsFor(decl),
@@ -231,6 +240,51 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
     });
   }
 
+  /**
+   * One connection per driver+role+URL (+ injected client) — `store.sql` and a
+   * SQL-backed `store.index` share the same already-open connection, never a
+   * second one.
+   */
+  async function sharedSqlConn(
+    driver: SqlDriver,
+    role: SqlRole,
+    connectOptions: SqlConnectOptions,
+  ): Promise<SqlConnection> {
+    const cacheKey = `${driver.id}:${role}:${connectOptions.url ?? ""}${clientTag(connectOptions.client)}`;
+    let conn = sqlConns.get(cacheKey);
+    if (!conn) {
+      conn = await driver.connect({ ...connectOptions, role });
+      sqlConns.set(cacheKey, conn);
+    }
+    return conn;
+  }
+
+  /** Index drivers backed by a SQL engine borrow the sql facet's connection. */
+  async function sqlConnForIndex(
+    driver: IndexDriver,
+    url: string | undefined,
+  ): Promise<SqlConnection> {
+    const sqlDriver = options.drivers.sql;
+    if (!sqlDriver) {
+      throw new Error(
+        `oke store: index driver "${driver.id}" needs a configured sql driver to share its connection`,
+      );
+    }
+    const compatible =
+      driver.id === "pgvector"
+        ? sqlDriver.id === "postgres" || sqlDriver.id === "pglite"
+        : sqlDriver.id === "libsql";
+    if (!compatible) {
+      throw new Error(
+        `oke store: index driver "${driver.id}" cannot share sql driver "${sqlDriver.id}" — ` +
+          (driver.id === "pgvector"
+            ? `pgvector needs store.sql on "postgres" or "pglite"`
+            : `libsql index needs store.sql on "libsql"`),
+      );
+    }
+    return sharedSqlConn(sqlDriver, "primary", { url });
+  }
+
   async function openKv(decl: KvStoreDecl): Promise<KvStoreFxHandle> {
     const driver = options.drivers.kv;
     if (!driver) throw new Error("No kv driver configured");
@@ -284,11 +338,15 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
     let idx = indexes.get(decl.name);
     if (!idx) {
       const binding = options.index?.[decl.name] ?? {};
+      let sql = binding.sql;
+      if (!sql && driver.id !== "memory") {
+        sql = await sqlConnForIndex(driver, binding.url);
+      }
       idx = await driver.open({
         name: decl.name,
         dims: binding.dims ?? decl.dims ?? 3,
         url: binding.url,
-        sql: binding.sql,
+        sql,
       });
       indexes.set(decl.name, idx);
     }

package/src/elements/store/schema-decl.ts

@@ -55,6 +55,8 @@ export interface SchemaColumnDecl extends ColumnDef {
   readonly tableName?: string;
   /** Foreign key when `.references()` was used. */
   readonly references?: ColumnReference;
+  /** Optional human description for Console / docs (falls back to the JS key). */
+  readonly description?: string;
 }
 
 /** Table from {@link store.schema.table} — extends {@link TableHandle}. */
@@ -75,6 +77,8 @@ export interface FieldBuilder {
   retain(duration: string): FieldBuilder;
   /** Override snake_case SQL name. */
   as(sqlName: string): FieldBuilder;
+  /** Optional human description for Console / docs (falls back to the JS key). */
+  describe(description: string): FieldBuilder;
   /**
    * Declare a foreign key to another column (dialect-agnostic).
    *
@@ -100,6 +104,7 @@ interface FieldState {
   readonly defaultFnKind?: DefaultFnKind;
   readonly classification?: ColumnClassification;
   readonly sqlName?: string;
+  readonly description?: string;
   readonly references?: ColumnReference;
 }
 
@@ -145,6 +150,7 @@ function createBuilder(state: FieldState): FieldBuilder {
     retain: (duration) =>
       next({ classification: mergeClassification(state.classification, { retain: duration }) }),
     as: (sqlName) => next({ sqlName }),
+    describe: (description) => next({ description }),
     references: (ref, actions) =>
       next({
         references: actions ? { ref, actions } : { ref },
@@ -163,6 +169,7 @@ function createBuilder(state: FieldState): FieldBuilder {
         ...(state.defaultFn ? { defaultFn: state.defaultFn } : {}),
         ...(state.defaultFnKind ? { defaultFnKind: state.defaultFnKind } : {}),
         ...(state.classification ? { classification: state.classification } : {}),
+        ...(state.description !== undefined ? { description: state.description } : {}),
         ...(state.references ? { references: state.references } : {}),
       };
     },

package/src/kernel/abort-scope.ts

@@ -0,0 +1,116 @@
+/**
+ * Ambient AbortSignal scope for structured concurrency.
+ *
+ * Same ALS pattern as dry-run: `fx.all` / `fx.race` enter a child signal so
+ * cooperative branches (and future driver plumbing) can observe cancellation
+ * without every call site passing a signal argument.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** Never-aborted signal used outside an `all` / `race` branch. */
+const NEVER_ABORTED = new AbortController().signal;
+
+const storage = new AsyncLocalStorage<AbortSignal>();
+
+/**
+ * AbortSignal for the current async chain, or a never-aborted signal when
+ * no structured-concurrency scope is active.
+ */
+export function currentAbortSignal(): AbortSignal {
+  return storage.getStore() ?? NEVER_ABORTED;
+}
+
+/**
+ * Run `fn` with `signal` as the ambient abort signal.
+ *
+ * @param signal - Branch / scope signal
+ * @param fn - Work that may read {@link currentAbortSignal}
+ */
+export async function withAbortSignal<T>(
+  signal: AbortSignal,
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  return storage.run(signal, fn);
+}
+
+/**
+ * When `parent` aborts, abort `child` with the same reason.
+ *
+ * @param parent - Outer signal
+ * @param child - Controller to abort
+ * @returns Unsubscribe
+ */
+export function linkAbort(parent: AbortSignal, child: AbortController): () => void {
+  if (parent.aborted) {
+    child.abort(parent.reason);
+    return () => undefined;
+  }
+  const onAbort = (): void => {
+    child.abort(parent.reason);
+  };
+  parent.addEventListener("abort", onAbort);
+  return () => parent.removeEventListener("abort", onAbort);
+}
+
+/**
+ * True when `err` is an abort rejection (`AbortError` name).
+ *
+ * @param err - Unknown
+ */
+export function isAbortError(err: unknown): boolean {
+  return err instanceof Error && err.name === "AbortError";
+}
+
+/**
+ * Create an `AbortError` matching Web / fetch abort rejections.
+ *
+ * @param reason - Optional abort reason
+ */
+export function abortError(reason?: unknown): Error {
+  if (typeof DOMException === "function") {
+    const message =
+      reason instanceof Error
+        ? reason.message
+        : reason !== undefined
+          ? String(reason)
+          : "This operation was aborted";
+    return new DOMException(message, "AbortError");
+  }
+  const err = new Error(
+    reason instanceof Error
+      ? reason.message
+      : reason !== undefined
+        ? String(reason)
+        : "This operation was aborted",
+  );
+  err.name = "AbortError";
+  return err;
+}
+
+/**
+ * Sleep that rejects promptly when `signal` aborts.
+ *
+ * Not durable — retry backoff must not journal via `fx.clock.sleep`.
+ *
+ * @param ms - Milliseconds
+ * @param signal - Optional abort signal
+ */
+export function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError(signal.reason));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(abortError(signal?.reason));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/kernel/app.ts

@@ -33,6 +33,7 @@ import {
 } from "./auth-resolve.ts";
 import { runDurable } from "../elements/clock/durable.ts";
 import { isFlow, type AnyFlowDef } from "./flow.ts";
+import { fxRetry } from "./concurrency.ts";
 import {
   createFxContext,
   resolveName,
@@ -680,13 +681,22 @@ export function oke(options: OkeOptions): OkeApp {
       hooks,
       async () => {
         try {
+          const invoke = async (input: unknown) => {
+            const run = () => {
+              // Flow-level retry re-enters `do` on the same journal session —
+              // rewind so completed steps/effects replay instead of re-executing.
+              journalSession?.rewind();
+              return flowDef.do(input as never, fx);
+            };
+            return flowDef.retry ? fxRetry(run, flowDef.retry) : run();
+          };
           if (!alreadyValidated) {
             const parsed = await validate(flowDef.in, ctx.input);
             if (!parsed.ok) return parsed.failure;
             ctx.input = parsed.value;
-            return await flowDef.do(parsed.value as never, fx);
+            return await invoke(parsed.value);
           }
-          return await flowDef.do(ctx.input as never, fx);
+          return await invoke(ctx.input);
         } catch (err) {
           // A durable sleep that has not yet elapsed suspends the run — this
           // is a park, not a pipeline failure, so it must not throw upward.