okengine 0.3.5 → 0.4.3

package/site/content/docs/get-started/why.mdx

@@ -0,0 +1,141 @@
+---
+title: Why OKE
+description: The six seams every TypeScript backend maintains by hand — and what OKE derives from one Manifest instead.
+source: docs/spec/unified-theory.md
+icon: Compass
+---
+
+Every TypeScript backend works on day one. The bill arrives later: the cache
+that serves last month's schema, the secret that only exists on your laptop,
+the dashboard that has never heard of your new Flow.
+
+None of these are router problems. They are **seams** — copies of your code's
+knowledge, kept in places the compiler cannot check, updated by memory.
+
+<Callout title="The one rule">
+  **All world access goes through `fx`.** What a Flow reads, writes, emits, and reveals is recorded
+  — so the seams below are derived from one Manifest, not re-typed per project.
+</Callout>
+
+## The six seams
+
+### The cache that lies
+
+You add a column to `orders` and update three writers. The hand-bumped cache
+key in `checkout` is not one of them. A customer finds it a week later.
+
+**OKE derives:** reads and writes are recorded through `fx`, so invalidation
+follows the Flow — there is no separate key to remember.
+
+### The secret that fails in prod
+
+`STRIPE_KEY` lives in your laptop's `.env`, a README, and a teammate's shell
+history. The deploy boots fine — the first charge request dies at 2am.
+
+**OKE derives:** [Vault](/docs/elements/vault) contracts declare the need in
+code; boot resolves every contract and fails loud with every gap listed —
+never halfway.
+
+### The glue you rewrite
+
+CORS rules, security headers, CSRF tokens, compression — copied from the last
+repo, tweaked, and already drifting from whatever that repo does today.
+
+**OKE derives:** the official `okengine/plugins` set ships this glue once —
+shared lifecycle, optional live DB config, nothing to re-copy.
+
+### The dashboard that doesn't know you
+
+Your observability stack learned your routes from sampled traffic. The Flow
+you deployed an hour ago is invisible until someone wires it by hand.
+
+**OKE derives:** the [Console](/docs/console/overview) reads the Manifest —
+flows, effects, traces, architecture — current on every save, in dev and prod
+(`:6533`).
+
+### The permission check in the wrong place
+
+`if (!user.isAdmin)` sits in handler forty-one of sixty. Which Flows touch
+`payments`? grep answers slowly; review answers never.
+
+**OKE derives:** declared effects produce a least-privilege matrix — widening
+access appears in Manifest Diff, not in a diff nobody reads.
+
+### Local works, prod doesn't
+
+Local runs one vendor client, CI another, prod a third — three glue stories
+for the same database. "Works on my machine" is a driver mismatch.
+
+**OKE derives:** drivers are named after protocols (`postgres`, `redis`,
+`s3`), the vendor lives in `images`, and `oke dev --docker` runs the real
+stack locally.
+
+## The tax is drift
+
+Every seam above is the same shape: a hand-maintained copy of knowledge the
+code already has. Watch one change propagate both ways.
+
+<DriftBoard />
+
+On the left, versions scatter and stay scattered. On the right, one Manifest
+feeds five surfaces — they cannot disagree, because none of them is a copy.
+
+## The answer's shape
+
+Forty infrastructure concerns collapse into eight elements — each kept only
+because it has irreducible physics. One change costs up to fifteen seams in
+the zoo; here it always costs two.
+
+<CollapseBoard />
+
+New infrastructure becomes a **driver** for an existing element, never a
+ninth element — the set of eight is closed.
+
+## Traditional vs OKE
+
+| Seam               | Maintained by hand                                        | Derived by OKE                                                                  |
+| ------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Behavior model     | Endpoints, jobs, consumers, workflows as separate species | One species — Flow: `on(Trigger) → Effects`                                     |
+| Cache invalidation | Hand-written keys; drift from writers                     | Derived from effects recorded through `fx`                                      |
+| HTTP glue          | Middleware copied per repo                                | Official plugins — `securityHeaders`, `cors`, `csrf`, compression, IP allowlist |
+| Secrets / config   | Env sprawl; fails on first request                        | Vault contracts; `VaultBootError` at boot                                       |
+| Observability      | Bolted on; separate source of truth                       | Console from the Manifest, dev and prod (`:6533`)                               |
+| Permissions        | Ad-hoc checks scattered in handlers                       | Least-privilege matrix from declared effects                                    |
+| Local vs prod      | Vendor clients; one-off compose                           | Protocol drivers; vendor in `images`; `oke dev --docker`                        |
+| Client / agents    | Separate codegen or hand-kept schemas                     | Typed client and MCP (`:6535`) from the same Manifest                           |
+
+## Ambition, stated plainly
+
+|                 | Statement                                                                                        |
+| --------------- | ------------------------------------------------------------------------------------------------ |
+| **Ambition**    | The default, most capable TypeScript backend — Bun-first, Web-Standards portable, contract-first |
+| **Grounded in** | Eight elements, effect inference through `fx`, Gate and Vault, the official plugin set           |
+| **Maturity**    | **pre-1.0** — published and usable; not independently battle-tested at scale yet                 |
+
+## Learn more
+
+- [Introduction](/docs/get-started/introduction) — the one law, eight elements, ten exports
+- [Flow](/docs/elements/flow) — how effects are recorded and inferred
+- [Vault](/docs/elements/vault) — fail-loud secret contracts
+- [Plugins](/docs/reference/plugins) — the official HTTP glue set
+- [Console · Overview](/docs/console/overview) — the Manifest-derived operator UI
+
+## Next
+
+<Cards>
+  <Card
+    title="Installation"
+    description="Scaffold with create-oke and open the Console."
+    href="/docs/get-started/installation"
+  />
+  <Card
+    title="Basic Usage"
+    description="Health Flow, typed client, and bun:test."
+    href="/docs/get-started/basic-usage"
+  />
+  <Card
+    title="Introduction"
+    description="The one law, eight elements, ten exports."
+    href="/docs/get-started/introduction"
+  />
+</Cards>

package/site/content/docs/plugins/ip-allowlist.mdx

@@ -46,8 +46,7 @@ A client whose IP is not on the list receives `403` with a typed denial:
 <Callout type="error">
   Standard reverse proxies **append** to `X-Forwarded-For` — left-side hops are attacker-controlled.
   The plugin trusts the hop `trustedProxyDepth` from the **right** (default `1` = last hop). Set
-  this to your real proxy count; wrong depth bypasses the allowlist — topology-dependent, not
-  drop-in.
+  this to your real proxy count — wrong depth bypasses the allowlist.
 </Callout>
 
 ## Notes

package/site/content/docs/plugins/security-headers.mdx

@@ -51,7 +51,7 @@ Every [helmet.js](https://helmet.js.org/) middleware maps to an option here —
 | `xPoweredBy`                    | `poweredBy`                                                                               | Yes — removed; a string sets a decoy value                                  |
 | `xXssProtection`                | `xssProtection`                                                                           | Yes — `0` (disables the legacy buggy auditor)                               |
 
-Beyond parity: headers land on **failures too** (helmet middleware ordering bugs are a classic Express footgun), app-set values win by default, and every option can be driven live from the database (below).
+Beyond parity: headers land on **failures too** (middleware that only wraps happy paths skips error responses), app-set values win by default, and every option can be driven live from the database (below).
 
 ## Options
 

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

@@ -36,10 +36,10 @@ drivers: {
 
 | Key                | Shape          | Driver ids (verified)                                                        |
 | ------------------ | -------------- | ---------------------------------------------------------------------------- |
-| `store.sql`        | env driver map | `sqlite` · `postgres` · `memory`                                             |
+| `store.sql`        | env driver map | `sqlite` · `postgres` · `libsql` · `pglite` · `memory`                       |
 | `store.kv`         | env driver map | `memory` · `redis`                                                           |
 | `store.files`      | env driver map | `memory` · `fs` · `s3`                                                       |
-| `store.index`      | env driver map | `memory` · `pgvector`                                                        |
+| `store.index`      | env driver map | `memory` · `pgvector` · `libsql` · `meilisearch`                             |
 | `signal`           | env driver map | `memory` · `postgres` · `redis` · `nats`                                     |
 | `clock`            | env driver map | `memory` · `postgres` · `frozen`                                             |
 | `vault`            | env driver map | `dotenv` · `openbao` · `memory`                                              |

package/site/content/docs/reference/environment-variables.mdx

@@ -18,8 +18,18 @@ OKE reads environment variables at boot for connection detail and secrets — ne
 | `DATABASE_URL`      | Postgres connection (`postgres` driver, drizzle-kit) | `postgres://localhost:5432/oke` |
 | `OKE_STORE_SQL_URL` | Explicit SQL URL override                            | —                               |
 | `OKE_SQLITE_URL`    | SQLite file path (`sqlite` driver)                   | `.oke/app.sqlite`               |
+| `OKE_LIBSQL_URL`    | libSQL URL or file path (`libsql` driver)            | `.oke/app.libsql`               |
+| `OKE_PGLITE_URL`    | PGlite data dir or `memory://` (`pglite` driver)     | `.oke/pgdata`                   |
 | `OKE_SQL_DRIVER`    | Force the sql driver id at boot                      | config map                      |
 
+## Index store
+
+| Variable              | Used for                                            | Default when unset |
+| --------------------- | --------------------------------------------------- | ------------------ |
+| `OKE_INDEX_DRIVER`    | Force the index driver id                           | config map         |
+| `OKE_STORE_INDEX_URL` | Meilisearch base URL (`meilisearch` driver)         | —                  |
+| `OKE_STORE_INDEX_KEY` | Meilisearch API / master key (`meilisearch` driver) | `MEILI_MASTER_KEY` |
+
 ## KV store
 
 | Variable           | Used for                 | Default when unset |

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

@@ -41,8 +41,61 @@ See [Store](/docs/elements/store) for the query-builder surface.
 | ---------------------------- | ------- | ----------------------------------------------------- |
 | `fx.call(flow, input?)`      | `call`  | The callee's `out` — runs through the same pipeline   |
 | `fx.step(name, fn)`          | —       | Durable step: replays from the journal, never re-runs |
+| `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)        |
 
+## Concurrency and retry
+
+Pass **thunks** to `all` / `race` — not already-started Promises — so each branch gets an abort scope before work begins.
+
+```typescript
+const [user, stock] = await fx.all([
+  () => fx.store(db).findById(users, input.userId),
+  () => fx.store(db).findById(inventory, input.sku),
+]);
+
+const charge = await fx.step("charge", () =>
+  fx.retry(() => fx.call(stripeCharge, { amount: input.total }), {
+    retries: 3,
+    delay: "100ms",
+    backoff: 2,
+    jitter: true,
+  }),
+);
+```
+
+| `fx.retry` option | Default | Meaning                                      |
+| ----------------- | ------- | -------------------------------------------- |
+| `retries`         | `0`     | Extra attempts after the first               |
+| `delay`           | `50`    | Initial backoff — ms number or `"100ms"`     |
+| `backoff`         | `2`     | Multiplier after each retry                  |
+| `jitter`          | `true`  | Full jitter on the delay (thundering-herd)   |
+| `when`            | thrown  | Predicate; skips `AbortError` and sleep park |
+
+<Callout title="Cooperative cancel">
+  Losing branches see `fx.signal` abort. Drivers that do not yet honor the signal may still finish
+  in the background — check `fx.signal.aborted` in long user work, and prefer `fx.all` over bare
+  `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
 
 | Signature                                 | Records | Notes                                                               |
@@ -62,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/site/content/docs/reference/plugins.mdx

@@ -64,22 +64,22 @@ Plugin flows appear in the Manifest, plugin tables land in `schema.generated.ts`
 
 Every method below exists on both the fluent definition and the boot-time builder the registry records:
 
-| Method                           | Contributes                                         |
-| -------------------------------- | --------------------------------------------------- |
-| `.flow(def)`                     | An ordinary flow — Manifest, Console, client types  |
-| `.hook(stage, fn)`               | A per-request intercept at one pipeline stage       |
-| `.edge(fn)`                      | A handler for HTTP requests that match **no** flow  |
-| `.decorate(key, value)`          | A typed context decoration, visible to flows        |
-| `.element({ kind, name })`       | An element contribution (e.g. `store.sql` facet)    |
-| `.driver(id, impl)`              | A protocol-named driver for an existing element     |
-| `.image(role, recipe)`           | An image recipe for a docker role                   |
-| `.table(name, columns, options)` | A whole DB table, merged into the generated schema  |
-| `.errors(map)`                   | Typed errors flows can fail with                    |
-| `.client(name, ext)`             | A typed client extension                            |
-| `.consolePanel(panel)`           | A Console panel (ESM entry loaded at runtime)       |
-| `.cli(name, handler)`            | An `oke <name>` CLI command                         |
-| `.config(schema)`                | A config schema; values live on the plugin identity |
-| `.needs(dep)`                    | A declared dependency (e.g. `"store.kv"`)           |
+| Method                           | Contributes                                                                                   |
+| -------------------------------- | --------------------------------------------------------------------------------------------- |
+| `.flow(def)`                     | An ordinary flow — Manifest, Console, client types                                            |
+| `.hook(stage, fn)`               | A per-request intercept at one pipeline stage                                                 |
+| `.edge(fn)`                      | A handler for HTTP requests that match **no** flow                                            |
+| `.decorate(key, value)`          | A typed context decoration, visible to flows                                                  |
+| `.element({ kind, name })`       | An element contribution (e.g. `store.sql` facet)                                              |
+| `.driver(id, impl)`              | A protocol-named driver for an existing element                                               |
+| `.image(role, recipe)`           | An image recipe for a docker role                                                             |
+| `.table(name, columns, options)` | A whole DB table, merged into the generated schema (`options.description` / `plane` optional) |
+| `.errors(map)`                   | Typed errors flows can fail with                                                              |
+| `.client(name, ext)`             | A typed client extension                                                                      |
+| `.consolePanel(panel)`           | A Console panel (ESM entry loaded at runtime)                                                 |
+| `.cli(name, handler)`            | An `oke <name>` CLI command                                                                   |
+| `.config(schema)`                | A config schema; values live on the plugin identity                                           |
+| `.needs(dep)`                    | A declared dependency (e.g. `"store.kv"`)                                                     |
 
 New infrastructure is a **driver** for an existing element, never a ninth element — plugins follow the same law.
 
@@ -194,11 +194,11 @@ A plugin may declare **its own tables** with `field.*` columns, merged into the
 plugin("billing", { version: "2.1.0" }).table(
   "invoices",
   { id: field.text().primaryKey().defaultFn(id) },
-  { plane: "user" },
+  { plane: "user", description: "Customer invoices" },
 );
 ```
 
-Extending an existing **app-owned** table with plugin columns is not supported in v1 — contribute a separate table and reference the app's by key. The optional `plane` metadata (`"operator" | "user" | "shared"`) keeps data-plane isolation intact for privacy tooling.
+Extending an existing **app-owned** table with plugin columns is not supported in v1 — contribute a separate table and reference the app's by key. The optional `plane` metadata (`"operator" | "user" | "shared"`) keeps data-plane isolation intact for privacy tooling. Optional `description` is a human title in the Console (falls back to the table name).
 
 ## Identity, config, and dependencies
 

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"));
+  });
+});