okengine 0.3.5 → 0.4.3

package/src/elements/vault.ts

@@ -2,7 +2,7 @@
  * Vault element — protected knowledge.
  *
  * Physics: secrets · config · environment.
- * Drivers: `env` · `openbao` · `infisical` · `managed`.
+ * Drivers: `env` · `openbao` · `managed`.
  *
  * A declaration is a contract, never a value. Boot validates every contract
  * and lists all gaps at once. Logs/traces receive fingerprints and redaction

package/src/index.ts

@@ -34,6 +34,10 @@ export {
   journey,
   unit,
   rateLimit,
+  Redacted,
+  isRedacted,
+  maskRedactedDeep,
+  REDACTED_PLACEHOLDER,
   type OkeApp,
   type OkeOptions,
   type FlowDef,

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.

package/src/kernel/boot-bind/store.test.ts

@@ -3,7 +3,13 @@
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
-import { resolveFilesDriverId, resolveKvDriverId, resolveSqlDriverId } from "./store.ts";
+import {
+  indexDriverFor,
+  resolveFilesDriverId,
+  resolveIndexDriverId,
+  resolveKvDriverId,
+  resolveSqlDriverId,
+} from "./store.ts";
 
 describe("bindStore driver resolution", () => {
   const prev = {
@@ -11,6 +17,7 @@ describe("bindStore driver resolution", () => {
     sql: process.env.OKE_SQL_DRIVER,
     kv: process.env.OKE_KV_DRIVER,
     files: process.env.OKE_FILES_DRIVER,
+    index: process.env.OKE_INDEX_DRIVER,
   };
 
   afterEach(() => {
@@ -22,6 +29,8 @@ describe("bindStore driver resolution", () => {
     else process.env.OKE_KV_DRIVER = prev.kv;
     if (prev.files === undefined) delete process.env.OKE_FILES_DRIVER;
     else process.env.OKE_FILES_DRIVER = prev.files;
+    if (prev.index === undefined) delete process.env.OKE_INDEX_DRIVER;
+    else process.env.OKE_INDEX_DRIVER = prev.index;
   });
 
   test("local env keeps sqlite / memory from config", () => {
@@ -67,3 +76,61 @@ describe("bindStore driver resolution", () => {
     expect(resolveFilesDriverId({}, "docker", true)).toBe("s3");
   });
 });
+
+describe("bindStore index driver resolution", () => {
+  const prevIndex = process.env.OKE_INDEX_DRIVER;
+
+  afterEach(() => {
+    if (prevIndex === undefined) delete process.env.OKE_INDEX_DRIVER;
+    else process.env.OKE_INDEX_DRIVER = prevIndex;
+  });
+
+  test("defaults to memory when no index driver is configured", () => {
+    expect(resolveIndexDriverId({}, "local", false)).toBe("memory");
+    expect(resolveIndexDriverId({}, "docker", true)).toBe("memory");
+    expect(indexDriverFor("memory").id).toBe("memory");
+  });
+
+  test("config drivers.store.index is honoured per env", () => {
+    const options = {
+      config: {
+        drivers: {
+          store: {
+            index: { local: "memory", docker: "pgvector", prod: "pgvector" },
+          },
+        },
+      },
+    };
+    expect(resolveIndexDriverId(options, "local", false)).toBe("memory");
+    expect(resolveIndexDriverId(options, "docker", true)).toBe("pgvector");
+    expect(resolveIndexDriverId(options, "prod", false)).toBe("pgvector");
+  });
+
+  test("libsql resolves from config", () => {
+    const options = {
+      config: { drivers: { store: { index: { local: "libsql" } } } },
+    };
+    expect(resolveIndexDriverId(options, "local", false)).toBe("libsql");
+    expect(indexDriverFor("libsql").id).toBe("libsql");
+  });
+
+  test("meilisearch resolves from config as a fourth id", () => {
+    const options = {
+      config: { drivers: { store: { index: { local: "meilisearch", docker: "meilisearch" } } } },
+    };
+    expect(resolveIndexDriverId(options, "local", false)).toBe("meilisearch");
+    expect(resolveIndexDriverId(options, "docker", true)).toBe("meilisearch");
+    expect(indexDriverFor("meilisearch").id).toBe("meilisearch");
+  });
+
+  test("docker mode honours OKE_INDEX_DRIVER override", () => {
+    process.env.OKE_INDEX_DRIVER = "pgvector";
+    expect(resolveIndexDriverId({}, "docker", true)).toBe("pgvector");
+    expect(resolveIndexDriverId({}, "local", false)).toBe("memory");
+  });
+
+  test("indexDriverFor returns the configured driver and throws on unknown ids", () => {
+    expect(indexDriverFor("pgvector").id).toBe("pgvector");
+    expect(() => indexDriverFor("chroma")).toThrow(/unknown index driver "chroma"/);
+  });
+});

package/src/kernel/boot-bind/store.ts

@@ -4,12 +4,16 @@
 
 import { resolveDomainDdlMode, resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import { fsDriver } from "../../drivers/fs.ts";
+import { libsqlDriver, libsqlIndexDriver } from "../../drivers/libsql.ts";
+import { meilisearchDriver } from "../../drivers/meilisearch.ts";
 import { memoryDrivers } from "../../drivers/memory.ts";
+import { pgliteDriver } from "../../drivers/pglite.ts";
+import { pgvectorDriver } from "../../drivers/pgvector.ts";
 import { postgresDriver } from "../../drivers/postgres.ts";
 import { redisDriver } from "../../drivers/redis.ts";
 import { s3Driver } from "../../drivers/s3.ts";
 import { sqliteDriver } from "../../drivers/sqlite.ts";
-import type { FilesDriver, KvDriver, SqlDriver } from "../../drivers/types.ts";
+import type { FilesDriver, IndexDriver, KvDriver, SqlDriver } from "../../drivers/types.ts";
 import { createStoreRuntime, type StoreRuntime } from "../../elements/store.ts";
 import type { StoreDecl } from "../../elements/store/declare.ts";
 import type { BootOptions } from "../boot.ts"; // type-only — no cycle at runtime
@@ -34,6 +38,7 @@ export function bindStore(
   const sqlId = resolveSqlDriverId(options, env, docker);
   const kvId = resolveKvDriverId(options, env, docker);
   const filesId = resolveFilesDriverId(options, env, docker);
+  const indexId = resolveIndexDriverId(options, env, docker);
   const sqlUrl = sqlUrlFor(sqlId, docker);
   const kvUrl = kvUrlFor(kvId, docker);
   const filesRoot = filesRootFor(filesId);
@@ -41,6 +46,7 @@ export function bindStore(
   const sqlBindings: Record<string, { name: string; primary: { url: string } }> = {};
   const kvBindings: Record<string, { url?: string }> = {};
   const filesBindings: Record<string, { root?: string }> = {};
+  const indexBindings: Record<string, { url?: string; apiKey?: string }> = {};
 
   for (const decl of options.stores ?? []) {
     if (isSqlDecl(decl)) {
@@ -52,6 +58,17 @@ export function bindStore(
       kvBindings[decl.name] = kvUrl !== undefined ? { url: kvUrl } : {};
     } else if (isFilesDecl(decl)) {
       filesBindings[decl.name] = filesRoot !== undefined ? { root: filesRoot } : {};
+    } else if (isIndexDecl(decl)) {
+      // SQL-backed index drivers share the sql facet's URL — the runtime opens
+      // one connection and hands it to both (never a second, redundant one).
+      // Meilisearch is a standalone HTTP service: its own URL + key, never sqlUrl.
+      if (indexId === "memory") {
+        indexBindings[decl.name] = {};
+      } else if (indexId === "meilisearch") {
+        indexBindings[decl.name] = { url: indexUrlFor(docker), apiKey: indexApiKeyFor() };
+      } else {
+        indexBindings[decl.name] = { url: sqlUrl };
+      }
     }
   }
 
@@ -63,11 +80,12 @@ export function bindStore(
       sql: sqlDriverFor(sqlId),
       kv: kvDriverFor(kvId),
       files: filesDriverFor(filesId),
-      index: memoryDrivers.index,
+      index: indexDriverFor(indexId),
     },
     sql: sqlBindings,
     kv: kvBindings,
     files: filesBindings,
+    index: indexBindings,
     now,
     domainDdl,
   });
@@ -132,12 +150,37 @@ export function resolveFilesDriverId(
   return docker ? "s3" : "memory";
 }
 
+/**
+ * Index driver — same resolution chain as sql/kv/files. Defaults to `memory`;
+ * a configured `pgvector` / `libsql` is honoured at real boot (and fails loud
+ * if its SQL engine or peer is missing — never silently back to memory).
+ *
+ * @param options - Boot options
+ * @param env - Active env
+ * @param docker - Docker mode
+ */
+export function resolveIndexDriverId(
+  options: BootOptions,
+  env: ConfigEnv,
+  docker: boolean,
+): string {
+  const fromEnv = process.env.OKE_INDEX_DRIVER?.trim();
+  if (docker && fromEnv) return fromEnv;
+  const resolved = resolveDriverId(options.config?.drivers?.store?.index, env);
+  if (resolved) return resolved;
+  return "memory";
+}
+
 function sqlDriverFor(id: string): SqlDriver {
   switch (id) {
     case "postgres":
       return postgresDriver;
     case "sqlite":
       return sqliteDriver;
+    case "libsql":
+      return libsqlDriver;
+    case "pglite":
+      return pgliteDriver;
     case "memory":
       return memoryDrivers.sql;
     default:
@@ -169,6 +212,25 @@ function filesDriverFor(id: string): FilesDriver {
   }
 }
 
+/**
+ * Single id → index driver switch — shared by `bindStore` and the Console's
+ * Manifest runtime so resolution can never drift into two maintained copies.
+ */
+export function indexDriverFor(id: string): IndexDriver {
+  switch (id) {
+    case "memory":
+      return memoryDrivers.index;
+    case "pgvector":
+      return pgvectorDriver;
+    case "libsql":
+      return libsqlIndexDriver;
+    case "meilisearch":
+      return meilisearchDriver;
+    default:
+      throw new Error(`oke boot: unknown index driver "${id}"`);
+  }
+}
+
 function sqlUrlFor(sqlId: string, docker: boolean): string {
   if (sqlId === "postgres") {
     const url = process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL ?? undefined;
@@ -184,6 +246,12 @@ function sqlUrlFor(sqlId: string, docker: boolean): string {
   if (sqlId === "sqlite") {
     return process.env.OKE_SQLITE_URL ?? ".oke/app.sqlite";
   }
+  if (sqlId === "libsql") {
+    return process.env.OKE_LIBSQL_URL ?? ".oke/app.libsql";
+  }
+  if (sqlId === "pglite") {
+    return process.env.OKE_PGLITE_URL ?? ".oke/pgdata";
+  }
   return ":memory:";
 }
 
@@ -205,6 +273,24 @@ function filesRootFor(filesId: string): string | undefined {
   return process.env.S3_BUCKET ?? process.env.OKE_STORE_FILES_DB ?? undefined;
 }
 
+/** Meilisearch base URL — standalone HTTP service, fail loud when missing. */
+function indexUrlFor(docker: boolean): string {
+  const url = process.env.OKE_STORE_INDEX_URL ?? undefined;
+  if (!url) {
+    throw new Error(
+      docker
+        ? "oke boot: meilisearch index needs OKE_STORE_INDEX_URL (did `oke dev -d` write docker/.env.docker?)"
+        : "oke boot: meilisearch index needs OKE_STORE_INDEX_URL",
+    );
+  }
+  return url;
+}
+
+/** Meilisearch API / master key. */
+function indexApiKeyFor(): string | undefined {
+  return process.env.OKE_STORE_INDEX_KEY ?? process.env.MEILI_MASTER_KEY ?? undefined;
+}
+
 function isSqlDecl(decl: StoreDecl): decl is Extract<StoreDecl, { facet: "sql" }> {
   return decl.facet === "sql";
 }
@@ -216,3 +302,7 @@ function isKvDecl(decl: StoreDecl): decl is Extract<StoreDecl, { facet: "kv" }>
 function isFilesDecl(decl: StoreDecl): decl is Extract<StoreDecl, { facet: "files" }> {
   return decl.facet === "files";
 }
+
+function isIndexDecl(decl: StoreDecl): decl is Extract<StoreDecl, { facet: "index" }> {
+  return decl.facet === "index";
+}