okengine 0.3.6 → 0.4.3

package/site/content/docs/reference/fx.mdx

@@ -44,6 +44,7 @@ See [Store](/docs/elements/store) for the query-builder surface.
 | `fx.all([...thunks])`        | —       | Parallel; first rejection aborts siblings             |
 | `fx.race([...thunks])`       | —       | First settle wins; losers aborted                     |
 | `fx.retry(fn, opts?)`        | —       | Exponential backoff + jitter (plain Promise)          |
+| `fx.using(acq, rel, use)`    | —       | `release` runs once on settle or ambient abort        |
 | `fx.signal`                  | —       | Ambient `AbortSignal` for the current branch          |
 | `fx.fail(code, data, opts?)` | —       | Typed failure value (`opts.message` overrides)        |
 
@@ -81,6 +82,18 @@ const charge = await fx.step("charge", () =>
   `Promise.all`.
 </Callout>
 
+`fx.using(acquire, release, use)` scopes a process-local resource to one attempt: `release` runs
+exactly once when `use` settles **or** when the ambient signal aborts (a sibling `fx.race` winner,
+a failing `fx.all` sibling). It is not journaled — do not hold handles across durable park/resume.
+
+```typescript
+const rows = await fx.using(
+  () => pool.acquire(),
+  (conn) => conn.release(),
+  (conn) => conn.query("select …"),
+);
+```
+
 **Consequence:** put `fx.retry` inside `fx.step` on durable flows so a completed charge never re-runs on resume. Coarse whole-body retry is `flow({ retry: { … } })` on the same journal session.
 
 ## Channel
@@ -102,9 +115,9 @@ AI calls are nondeterministic: journaling is forced on and auto-cache disabled a
 
 ## Vault
 
-| Signature            | Records | Returns / notes                                                         |
-| -------------------- | ------- | ----------------------------------------------------------------------- |
-| `fx.vault(contract)` | `read`  | Cleartext, inside this flow only — registered with the redactor at boot |
+| Signature            | Records | Returns / notes                                                                           |
+| -------------------- | ------- | ----------------------------------------------------------------------------------------- |
+| `fx.vault(contract)` | `read`  | `Redacted<string>` — prints/logs as a placeholder; `.reveal()` at the credential boundary |
 
 ## Clock
 

package/src/cli/competitor-mention-removal.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Gate: named competitor comparisons stay gone from the tracked tree.
+ *
+ * Mirrors {@link ./doc-staleness.test.ts} — `git grep` must find zero hits
+ * (the security-headers decoy header fixture may still use a common
+ * `X-Powered-By` value; that path is allow-listed).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+
+const ROOT = join(import.meta.dir, "../..");
+
+/** Forbidden peer name — split so this file does not match itself. */
+const FORBIDDEN_HONO = ["Ho", "no"].join("");
+/** Forbidden peer name. */
+const FORBIDDEN_ELYSIA = ["Ely", "sia"].join("");
+/** Forbidden peer name (covers Enc + ore.ts). */
+const FORBIDDEN_ENCORE = ["Enc", "ore"].join("");
+/** Forbidden peer name. */
+const FORBIDDEN_NESTJS = ["Nest", "JS"].join("");
+/** Forbidden peer name. */
+const FORBIDDEN_FASTIFY = ["Fast", "ify"].join("");
+/** Forbidden peer site — avoid bare `iii` (matches lockfile hashes). */
+const FORBIDDEN_III_DEV = ["iii", ".", "dev"].join("");
+/** Deleted Comparison page path residue. */
+const FORBIDDEN_COMPARISON_PATH = ["get-started/", "comparison"].join("");
+/** Word-boundary classic Node framework — `-F` false-positives on `CallExpression`. */
+const FORBIDDEN_EXPRESS = ["\\b", "Ex", "press", "\\b"].join("");
+
+/** Decoy `X-Powered-By` fixture value in the security-headers plugin tests. */
+const EXPRESS_ALLOW = ["src/plugins/security-headers.test.ts:"];
+
+/**
+ * Run `git grep -F` and assert zero matches after ignoring allow-listed paths.
+ *
+ * @param pattern - Fixed-string pattern
+ * @param ignorePrefixes - Path prefixes to ignore (`path:line:` hits)
+ */
+function assertZeroGitGrepFixed(pattern: string, ignorePrefixes: readonly string[] = []): void {
+  const proc = Bun.spawnSync(["git", "grep", "-F", "-n", "-e", pattern, "--"], {
+    cwd: ROOT,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  // git grep exits 1 when there are no matches.
+  if (proc.exitCode === 1) {
+    expect(proc.stdout.toString()).toBe("");
+    return;
+  }
+  const hits = proc.stdout
+    .toString()
+    .trim()
+    .split("\n")
+    .filter((line) => line.length > 0)
+    .filter((line) => !ignorePrefixes.some((prefix) => line.startsWith(prefix)));
+  expect(hits.join("\n")).toBe("");
+}
+
+/**
+ * Run `git grep` with a basic regex and assert zero matches after allow-list.
+ *
+ * @param pattern - Basic regex (no `-F`)
+ * @param ignorePrefixes - Path prefixes to ignore (`path:line:` hits)
+ */
+function assertZeroGitGrepRegex(pattern: string, ignorePrefixes: readonly string[] = []): void {
+  const proc = Bun.spawnSync(["git", "grep", "-n", "-e", pattern, "--"], {
+    cwd: ROOT,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (proc.exitCode === 1) {
+    expect(proc.stdout.toString()).toBe("");
+    return;
+  }
+  const hits = proc.stdout
+    .toString()
+    .trim()
+    .split("\n")
+    .filter((line) => line.length > 0)
+    .filter((line) => !ignorePrefixes.some((prefix) => line.startsWith(prefix)));
+  expect(hits.join("\n")).toBe("");
+}
+
+describe("named competitor mention removal gate", () => {
+  test("tracked tree has zero mentions of the thin multi-runtime router peer", () => {
+    assertZeroGitGrepFixed(FORBIDDEN_HONO);
+  });
+
+  test("tracked tree has zero mentions of the Bun-first peer framework", () => {
+    assertZeroGitGrepFixed(FORBIDDEN_ELYSIA);
+  });
+
+  test("tracked tree has zero mentions of the Rust-core peer platform", () => {
+    assertZeroGitGrepFixed(FORBIDDEN_ENCORE);
+  });
+
+  test("tracked tree has zero mentions of the decorator DI peer", () => {
+    assertZeroGitGrepFixed(FORBIDDEN_NESTJS);
+  });
+
+  test("tracked tree has zero mentions of the Node HTTP peer", () => {
+    assertZeroGitGrepFixed(FORBIDDEN_FASTIFY);
+  });
+
+  test("tracked tree has zero mentions of the polyglot peer site host", () => {
+    assertZeroGitGrepFixed(FORBIDDEN_III_DEV);
+  });
+
+  test("tracked tree has zero deleted Comparison path residue", () => {
+    assertZeroGitGrepFixed(FORBIDDEN_COMPARISON_PATH);
+  });
+
+  test("tracked tree has zero classic Node framework peer mentions outside decoy fixture", () => {
+    assertZeroGitGrepRegex(FORBIDDEN_EXPRESS, EXPRESS_ALLOW);
+  });
+});

package/src/cli/dev.ts

@@ -339,6 +339,24 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     loadedConfig = null;
   }
 
+  // Local mode + a configured `meilisearch` store.index: bring the server up
+  // as a fourth local process (binary on PATH — a documented prerequisite,
+  // like Docker for --docker). Docker mode instead relies on the recipe.
+  let meili: import("./meilisearch-local.ts").LocalMeilisearchHandle | null = null;
+  if (mode === "local") {
+    const indexId = resolveDriverId(loadedConfig?.drivers?.store?.index, "local") ?? "memory";
+    if (indexId === "meilisearch") {
+      try {
+        const { startLocalMeilisearch } = await import("./meilisearch-local.ts");
+        meili = await startLocalMeilisearch({ cwd });
+        write(formatStatusLine(`meilisearch local server on ${meili.url}`));
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { code: 1 };
+      }
+    }
+  }
+
   if (mode === "docker") {
     let images = options.images;
     if (!images) {
@@ -567,6 +585,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
           OKE_KV_DRIVER: stackKvDriver,
         }
       : {}),
+    ...(meili?.overlay ?? {}),
   };
   process.env.OKE_DEV_REQUEST_LOG = "1";
 
@@ -755,6 +774,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     stopped = true;
     autoPushRunner.cancel();
     watcher.close();
+    meili?.stop();
     app.stop();
     consoleServer.stop();
     mcpServer?.stop();

package/src/cli/meilisearch-local.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Local Meilisearch lifecycle — persisted master key material and fail-loud
+ * binary resolution. Never spawns a real server here.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  ensureMasterKey,
+  MEILISEARCH_STATE_DIR_REL,
+  MeilisearchLocalError,
+  startLocalMeilisearch,
+} from "./meilisearch-local.ts";
+
+const dirs: string[] = [];
+
+function tempStateDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "oke-meili-"));
+  dirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (dirs.length > 0) {
+    const dir = dirs.pop();
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("ensureMasterKey", () => {
+  test("generates once, persists 0600, reuses on next call", () => {
+    const stateDir = tempStateDir();
+    const first = ensureMasterKey(stateDir);
+    const second = ensureMasterKey(stateDir);
+    expect(first).toBe(second);
+    expect(first.length).toBeGreaterThanOrEqual(32);
+    const keyPath = join(stateDir, "master.key");
+    expect(statSync(keyPath).mode & 0o777).toBe(0o600);
+    expect(statSync(stateDir).mode & 0o777).toBe(0o700);
+    expect(readFileSync(keyPath, "utf8").trim()).toBe(first);
+    // No leftover temp files.
+    expect(readdirSync(stateDir).filter((f) => f.includes(".tmp-"))).toHaveLength(0);
+  });
+
+  test("a too-short persisted key fails loud", () => {
+    const stateDir = tempStateDir();
+    const keyPath = join(stateDir, "master.key");
+    // Write a weak key directly (bypasses the writer) to simulate corruption.
+    writeFileSync(keyPath, "short\n");
+    expect(() => ensureMasterKey(stateDir)).toThrow(MeilisearchLocalError);
+  });
+});
+
+describe("startLocalMeilisearch", () => {
+  test("missing binary fails loud with an install hint (never silent memory)", async () => {
+    await expect(
+      startLocalMeilisearch({
+        binary: "meilisearch-definitely-not-on-path-xyz",
+        stateDir: tempStateDir(),
+      }),
+    ).rejects.toThrow(/not found on PATH|never auto-downloads/i);
+  });
+
+  test("state dir rel lives under .oke", () => {
+    expect(MEILISEARCH_STATE_DIR_REL).toBe(join(".oke", "meilisearch"));
+  });
+});

package/src/cli/meilisearch-local.ts

@@ -0,0 +1,188 @@
+/**
+ * Local Meilisearch lifecycle for `oke dev` (local mode).
+ *
+ * A Meilisearch server is a fourth moving part only when the app actually
+ * opts into the `meilisearch` store.index driver. This module:
+ *
+ *  - generates the master key once and persists it under `.oke/meilisearch/`
+ *    (`0700` dir / `0600` file, atomic write — same material discipline as
+ *    OpenBao, minus the init/unseal ceremony: a single static key),
+ *  - resolves the `meilisearch` binary from `PATH` (a documented prerequisite,
+ *    like Docker for `--docker`; we never auto-download binaries),
+ *  - spawns it via `Bun.spawn` with its own data dir + port, polls `/health`,
+ *    and hands back an env overlay (`OKE_STORE_INDEX_URL` / `…_KEY`) plus a
+ *    `stop()` that kills the child alongside the app.
+ *
+ * Fail-loud: missing binary / unhealthy server / never-ready all throw
+ * {@link MeilisearchLocalError} — never a silent memory fallback.
+ */
+
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/** Material directory relative to the project root. */
+export const MEILISEARCH_STATE_DIR_REL = join(".oke", "meilisearch");
+/** Default loopback port for the local server. */
+export const MEILISEARCH_LOCAL_PORT = 7700;
+
+/** Fail-loud local Meilisearch error (missing binary / never healthy). */
+export class MeilisearchLocalError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MeilisearchLocalError";
+  }
+}
+
+/** Options for {@link startLocalMeilisearch}. */
+export interface LocalMeilisearchOptions {
+  readonly cwd?: string;
+  /** Loopback port (default {@link MEILISEARCH_LOCAL_PORT}). */
+  readonly port?: number;
+  /** Override state dir (tests). */
+  readonly stateDir?: string;
+  /** Binary name/path resolved via `Bun.which` (default `meilisearch`). */
+  readonly binary?: string;
+  /** Max ms to wait for `/health` to report available (default 30_000). */
+  readonly readyTimeoutMs?: number;
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+/** A running local Meilisearch child. */
+export interface LocalMeilisearchHandle {
+  /** Base URL the app should talk to. */
+  readonly url: string;
+  /** Master key (also persisted on disk). */
+  readonly masterKey: string;
+  /** Env overlay for the app child. */
+  readonly overlay: Record<string, string>;
+  /** Kill the child (idempotent). */
+  readonly stop: () => void;
+}
+
+/** Env overlay for the app child. */
+export function meilisearchStackEnv(handle: LocalMeilisearchHandle): Record<string, string> {
+  return handle.overlay;
+}
+
+function writeMaterial(path: string, value: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  chmodSync(dirname(path), 0o700);
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${value}\n`, { mode: 0o600 });
+  renameSync(tmp, path);
+  chmodSync(path, 0o600);
+  const back = readFileSync(path, "utf8").trim();
+  if (back !== value) {
+    throw new MeilisearchLocalError(`meilisearch local: verify failed reading ${path}`);
+  }
+}
+
+/** Read the persisted master key, or generate + persist a fresh one. */
+export function ensureMasterKey(stateDir: string): string {
+  const keyPath = join(stateDir, "master.key");
+  if (existsSync(keyPath)) {
+    const key = readFileSync(keyPath, "utf8").trim();
+    if (key.length >= 16) return key;
+    throw new MeilisearchLocalError(
+      `meilisearch local: ${keyPath} exists but is too short — delete it to regenerate`,
+    );
+  }
+  const key = randomBytes(32).toString("hex");
+  writeMaterial(keyPath, key);
+  return key;
+}
+
+/**
+ * Start a local Meilisearch server and wait for `/health`.
+ *
+ * @param options - cwd / port / binary / injected fetch
+ */
+export async function startLocalMeilisearch(
+  options: LocalMeilisearchOptions = {},
+): Promise<LocalMeilisearchHandle> {
+  const cwd = options.cwd ?? process.cwd();
+  const port = options.port ?? MEILISEARCH_LOCAL_PORT;
+  const stateDir = options.stateDir ?? resolve(cwd, MEILISEARCH_STATE_DIR_REL);
+  const dataDir = join(stateDir, "data");
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const readyTimeoutMs = options.readyTimeoutMs ?? 30_000;
+
+  const binary = options.binary ?? "meilisearch";
+  const resolved = Bun.which(binary);
+  if (!resolved) {
+    throw new MeilisearchLocalError(
+      "meilisearch local: `meilisearch` not found on PATH — install it to use the store.index FTS driver " +
+        "(brew install meilisearch · curl -L https://install.meilisearch.com | sh), " +
+        "or run `oke dev --docker` instead. OKE never auto-downloads binaries.",
+    );
+  }
+
+  const masterKey = ensureMasterKey(stateDir);
+  mkdirSync(dataDir, { recursive: true });
+
+  const url = `http://127.0.0.1:${port}`;
+  const proc = Bun.spawn(
+    [
+      resolved,
+      "--http-addr",
+      `127.0.0.1:${port}`,
+      "--master-key",
+      masterKey,
+      "--db-path",
+      dataDir,
+      "--env",
+      "development",
+      "--no-analytics",
+    ],
+    {
+      cwd,
+      stdout: "ignore",
+      stderr: "inherit",
+      env: { ...(process.env as Record<string, string>) },
+    },
+  );
+
+  let stopped = false;
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+      // Already gone.
+    }
+  };
+
+  const deadline = Date.now() + readyTimeoutMs;
+  for (;;) {
+    if (proc.exitCode !== null) {
+      throw new MeilisearchLocalError(
+        `meilisearch local: server exited (${proc.exitCode}) before becoming healthy`,
+      );
+    }
+    try {
+      const res = await fetchFn(`${url}/health`);
+      if (res.ok) break;
+    } catch {
+      // Not up yet.
+    }
+    if (Date.now() > deadline) {
+      stop();
+      throw new MeilisearchLocalError(
+        `meilisearch local: no /health from ${url} within ${readyTimeoutMs}ms`,
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+
+  return {
+    url,
+    masterKey,
+    overlay: {
+      OKE_STORE_INDEX_URL: url,
+      OKE_STORE_INDEX_KEY: masterKey,
+    },
+    stop,
+  };
+}

package/src/compiler/fixtures/skyport/src/flows/payments/index.ts

@@ -5,7 +5,11 @@ export const chargeBooking = flow({
   name: "payments.chargeBooking",
   durable: true,
   do: async ({ orderId }, fx) => {
-    const intent = await fx.step("create-intent", () => fx.vault(stripeKey));
+    // Journal only serializable step values — a Redacted is not journaled.
+    const intent = await fx.step("create-intent", async () => ({
+      id: `pi_${orderId}`,
+      key: fx.vault(stripeKey).reveal(),
+    }));
     await fx.clock.sleep("verify-window", "2m");
     return fx.step("confirm", () => intent);
   },

package/src/console/server/store.test.ts

@@ -137,7 +137,7 @@ describe("index driver resolution", () => {
     expect(decl).toBeDefined();
     const handle = (await runtime.open(decl!, {
       effects: { reads: ["index:docs"], writes: ["index:docs"] },
-    })) as import("../../elements/store.ts").IndexStoreFxHandle;
+    })) as import("../../elements/store.ts").VectorIndexStoreFxHandle;
     expect(handle.driverId).toBe("memory");
     await handle.upsert("d1", [1, 0, 0], { t: 1 });
     const hits = await handle.search([1, 0, 0], 1);

package/src/console/server/store.ts

@@ -329,6 +329,7 @@ export interface StoreQueryInput {
   readonly prefix?: string;
   readonly limit?: number;
   readonly vector?: readonly number[];
+  readonly q?: string;
   readonly topK?: number;
   readonly revealPii?: boolean;
 }
@@ -350,6 +351,7 @@ export interface StoreQueryResult {
     readonly score: number;
     readonly meta?: Record<string, unknown>;
   }>;
+  readonly facetDistribution?: Record<string, Record<string, number>>;
   readonly masked: boolean;
   readonly routedRole?: "primary" | "replica";
 }
@@ -438,12 +440,20 @@ export async function queryStore(
 
   // index
   const idx = handle as IndexStoreFxHandle;
+  void manifest;
+  if (idx.driverId === "meilisearch") {
+    const q = input.q ?? "";
+    if (q.trim().length === 0) {
+      return { facet, hits: [], masked: false };
+    }
+    const result = await idx.search(q, { topK: input.topK ?? 5 });
+    return { facet, hits: result.hits, facetDistribution: result.facetDistribution, masked: false };
+  }
   const vector = input.vector ?? [];
   if (vector.length === 0) {
     return { facet, hits: [], masked: false };
   }
   const hits = await idx.search(vector, input.topK ?? 5);
-  void manifest;
   return { facet, hits, masked: false };
 }