@openparachute/vault 0.7.3-rc.9 → 0.7.4-rc.1

package/src/config.test.ts

@@ -344,6 +344,22 @@ describe("config", () => {
     expect(readGlobalConfig().autostart).toBe(false);
   });
 
+  test("round-trips embeddings_enabled: true|false (semantic-search opt-in, 0.7.3)", () => {
+    // Absent means off — semantic search is opt-in as of 0.7.3. The key is
+    // only persisted when explicitly set (the self-host settings toggle).
+    writeGlobalConfig({ port: 1940 });
+    expect(readGlobalConfig().embeddings_enabled).toBeUndefined();
+
+    // Explicit true — the operator turned semantic search on without editing
+    // the env file; getSharedEmbeddingProvider threads this in as the default.
+    writeGlobalConfig({ port: 1940, embeddings_enabled: true });
+    expect(readGlobalConfig().embeddings_enabled).toBe(true);
+
+    // Explicit false — persisted opt-out (distinct from absent for clarity).
+    writeGlobalConfig({ port: 1940, embeddings_enabled: false });
+    expect(readGlobalConfig().embeddings_enabled).toBe(false);
+  });
+
   test("round-trips default_mirror: internal|off", () => {
     // Absent: createVault falls back to the in-code default ("internal" —
     // backup-on-by-default). The knob is only persisted when explicitly set.

package/src/config.ts

@@ -387,6 +387,18 @@ export interface GlobalConfig {
     /** Master toggle. Default false; the worker is a no-op when unset. */
     enabled?: boolean;
   };
+  /**
+   * Semantic-search opt-in (0.7.3, Aaron-ratified). Semantic search is OFF
+   * by default; set this to `true` to build the embedding provider and turn
+   * on embed-on-write + the backfill sweep. This is the persisted,
+   * settings-surface-friendly toggle a self-host operator flips without
+   * editing the env file. The `EMBEDDINGS_ENABLED` env var is the low-level
+   * OVERRIDE (`true`/`1` forces on, `false`/`0` forces off, anything else
+   * defers here) — see `src/embedding/select.ts`'s `resolveEmbeddingsEnabled`.
+   * Unset ⇒ off. Takes effect on server (re)start, since the process shares
+   * one embedding provider resolved at boot.
+   */
+  embeddings_enabled?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -1308,6 +1320,7 @@ export function readGlobalConfig(): GlobalConfig {
       const discoveryMatch = yaml.match(/^discovery:\s*(enabled|disabled)/m);
       const autostartMatch = yaml.match(/^autostart:\s*(true|false)/m);
       const autoCreateMatch = yaml.match(/^auto_create:\s*(true|false)/m);
+      const embeddingsEnabledMatch = yaml.match(/^embeddings_enabled:\s*(true|false)/m);
       const defaultMirrorMatch = yaml.match(/^default_mirror:\s*(internal|off)/m);
       // auto_transcribe block — currently single boolean `enabled` (vault#353).
       // Parsed as a nested 2-space-indent block so future fields can grow under
@@ -1340,6 +1353,9 @@ export function readGlobalConfig(): GlobalConfig {
       if (autoCreateMatch) {
         config.auto_create = autoCreateMatch[1]! === "true";
       }
+      if (embeddingsEnabledMatch) {
+        config.embeddings_enabled = embeddingsEnabledMatch[1]! === "true";
+      }
       if (defaultMirrorMatch) {
         config.default_mirror = defaultMirrorMatch[1]! as "internal" | "off";
       }
@@ -1416,6 +1432,7 @@ export function writeGlobalConfig(config: GlobalConfig): void {
   if (config.discovery) lines.push(`discovery: ${config.discovery}`);
   if (config.autostart !== undefined) lines.push(`autostart: ${config.autostart}`);
   if (config.auto_create !== undefined) lines.push(`auto_create: ${config.auto_create}`);
+  if (config.embeddings_enabled !== undefined) lines.push(`embeddings_enabled: ${config.embeddings_enabled}`);
   if (config.default_mirror) lines.push(`default_mirror: ${config.default_mirror}`);
   if (config.owner_password_hash) {
     lines.push(`owner_password_hash: "${config.owner_password_hash}"`);

package/src/embedding/select.test.ts

@@ -2,7 +2,8 @@ import { describe, test, expect } from "bun:test";
 import {
   resolveEmbeddingApiConfig,
   buildEmbeddingProvider,
-  embeddingsExplicitlyDisabled,
+  embeddingsEnabledEnvOverride,
+  resolveEmbeddingsEnabled,
   DEFAULT_EXTERNAL_EMBEDDING_MODEL,
 } from "./select.ts";
 import { ExternalApiEmbeddingProvider } from "./external-api.ts";
@@ -29,71 +30,98 @@ describe("resolveEmbeddingApiConfig", () => {
   });
 });
 
-describe("buildEmbeddingProvider — two-tier selection", () => {
+describe("buildEmbeddingProvider — two-tier selection (once ENABLED)", () => {
+  // Semantic search is opt-in as of 0.7.3, so every case here enables it
+  // (via the env override) before asserting WHICH tier is selected.
   test("zero-config: no EMBEDDING_API_URL -> the bundled floor (onnx-transformers)", () => {
-    const provider = buildEmbeddingProvider({});
+    const provider = buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "true" });
     expect(provider).toBeInstanceOf(OnnxTransformersEmbeddingProvider);
   });
 
   test("EMBEDDING_API_URL set -> the config upgrade tier (external-api) wins", () => {
-    const provider = buildEmbeddingProvider({ EMBEDDING_API_URL: "http://localhost:11434/v1" });
+    const provider = buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "true", EMBEDDING_API_URL: "http://localhost:11434/v1" });
     expect(provider).toBeInstanceOf(ExternalApiEmbeddingProvider);
-    expect(provider.model).toBe(DEFAULT_EXTERNAL_EMBEDDING_MODEL);
+    expect(provider!.model).toBe(DEFAULT_EXTERNAL_EMBEDDING_MODEL);
   });
 
   test("EMBEDDING_MODEL alone (no URL) has no effect — still the bundled floor", () => {
-    const provider = buildEmbeddingProvider({ EMBEDDING_MODEL: "bge-m3" });
+    const provider = buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "true", EMBEDDING_MODEL: "bge-m3" });
     expect(provider).toBeInstanceOf(OnnxTransformersEmbeddingProvider);
   });
 
   test("an explicit EMBEDDING_MODEL overrides the config-tier default", () => {
     const provider = buildEmbeddingProvider({
+      EMBEDDINGS_ENABLED: "true",
       EMBEDDING_API_URL: "http://x",
       EMBEDDING_MODEL: "nomic-embed-text",
     });
-    expect(provider.model).toBe("nomic-embed-text");
+    expect(provider!.model).toBe("nomic-embed-text");
   });
 });
 
-describe("embeddingsExplicitlyDisabled — the EMBEDDINGS_ENABLED off switch (M1)", () => {
-  test("false only for the literal string \"false\"", () => {
-    expect(embeddingsExplicitlyDisabled({ EMBEDDINGS_ENABLED: "false" })).toBe(true);
+describe("embeddingsEnabledEnvOverride — the EMBEDDINGS_ENABLED tri-state override", () => {
+  test("\"true\"/\"1\" force ON (case-insensitive, trimmed)", () => {
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "true" })).toBe(true);
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "TRUE" })).toBe(true);
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "  1  " })).toBe(true);
   });
 
-  test("case-insensitive and trims whitespace", () => {
-    expect(embeddingsExplicitlyDisabled({ EMBEDDINGS_ENABLED: "FALSE" })).toBe(true);
-    expect(embeddingsExplicitlyDisabled({ EMBEDDINGS_ENABLED: "  false  " })).toBe(true);
+  test("\"false\"/\"0\" force OFF (case-insensitive, trimmed)", () => {
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "false" })).toBe(false);
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "FALSE" })).toBe(false);
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "  0  " })).toBe(false);
   });
 
-  test("unset defaults to enabled (not disabled)", () => {
-    expect(embeddingsExplicitlyDisabled({})).toBe(false);
+  test("unset / blank / unrecognized → undefined (defer to the persisted setting)", () => {
+    expect(embeddingsEnabledEnvOverride({})).toBeUndefined();
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "" })).toBeUndefined();
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "  " })).toBeUndefined();
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "yes" })).toBeUndefined();
+  });
+});
+
+describe("resolveEmbeddingsEnabled — env override, else persisted, else OFF", () => {
+  test("defaults OFF when neither env nor persisted setting is present (opt-in)", () => {
+    expect(resolveEmbeddingsEnabled({})).toBe(false);
+    expect(resolveEmbeddingsEnabled({}, undefined)).toBe(false);
+  });
+
+  test("persisted setting decides when the env var is absent", () => {
+    expect(resolveEmbeddingsEnabled({}, true)).toBe(true);
+    expect(resolveEmbeddingsEnabled({}, false)).toBe(false);
+  });
+
+  test("env override wins over the persisted setting in BOTH directions", () => {
+    expect(resolveEmbeddingsEnabled({ EMBEDDINGS_ENABLED: "false" }, true)).toBe(false);
+    expect(resolveEmbeddingsEnabled({ EMBEDDINGS_ENABLED: "true" }, false)).toBe(true);
   });
 
-  test("\"true\" (and any other value) is enabled — this var is an off switch, not an opt-in", () => {
-    expect(embeddingsExplicitlyDisabled({ EMBEDDINGS_ENABLED: "true" })).toBe(false);
-    expect(embeddingsExplicitlyDisabled({ EMBEDDINGS_ENABLED: "0" })).toBe(false);
-    expect(embeddingsExplicitlyDisabled({ EMBEDDINGS_ENABLED: "no" })).toBe(false);
+  test("an unrecognized env value defers to the persisted setting (not a guess)", () => {
+    expect(resolveEmbeddingsEnabled({ EMBEDDINGS_ENABLED: "maybe" }, true)).toBe(true);
+    expect(resolveEmbeddingsEnabled({ EMBEDDINGS_ENABLED: "maybe" }, false)).toBe(false);
   });
 });
 
-describe("buildEmbeddingProvider — EMBEDDINGS_ENABLED=false (M1)", () => {
-  test("returns undefined even when the config-upgrade tier is otherwise fully configured", () => {
-    const provider = buildEmbeddingProvider({
-      EMBEDDINGS_ENABLED: "false",
-      EMBEDDING_API_URL: "http://localhost:11434/v1",
-      EMBEDDING_MODEL: "bge-m3",
-    });
-    expect(provider).toBeUndefined();
+describe("buildEmbeddingProvider — opt-in gate (0.7.3)", () => {
+  test("DEFAULT off: no provider when nothing enables it (unset env, no persisted setting)", () => {
+    expect(buildEmbeddingProvider({})).toBeUndefined();
+    expect(buildEmbeddingProvider({ EMBEDDING_API_URL: "http://localhost:11434/v1", EMBEDDING_MODEL: "bge-m3" })).toBeUndefined();
   });
 
-  test("returns undefined for the zero-config (bundled-floor) case too", () => {
-    expect(buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "false" })).toBeUndefined();
+  test("EMBEDDINGS_ENABLED=false forces off even with the persisted setting on", () => {
+    expect(buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "false" }, { persistedEnabled: true })).toBeUndefined();
   });
 
-  test("EMBEDDINGS_ENABLED=true (or unset) is unaffected — both tiers still resolve normally", () => {
+  test("EMBEDDINGS_ENABLED=true (or =1) enables — both tiers then resolve normally", () => {
     expect(buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "true" })).toBeInstanceOf(OnnxTransformersEmbeddingProvider);
+    expect(buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "1" })).toBeInstanceOf(OnnxTransformersEmbeddingProvider);
     expect(
       buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "true", EMBEDDING_API_URL: "http://x" }),
     ).toBeInstanceOf(ExternalApiEmbeddingProvider);
   });
+
+  test("the persisted setting alone enables it (the self-host settings toggle, no env var)", () => {
+    expect(buildEmbeddingProvider({}, { persistedEnabled: true })).toBeInstanceOf(OnnxTransformersEmbeddingProvider);
+    expect(buildEmbeddingProvider({}, { persistedEnabled: false })).toBeUndefined();
+  });
 });

package/src/embedding/select.ts

@@ -17,15 +17,28 @@
  *     in-process. This is what makes semantic search work on a fresh
  *     install with no operator action.
  *
- * **Off switch:** `EMBEDDINGS_ENABLED=false` short-circuits BOTH tiers —
- * `buildEmbeddingProvider` returns `undefined` regardless of what else is
- * configured. Mirrors the `EMBEDDINGS_ENABLED` wrangler var C2 (cloud)
- * plans for the same gate. A caller wired against an `undefined` provider
- * (see `Store.embeddingProvider`) reports the `embeddings` capability as
+ * **Opt-in gate (0.7.3, Aaron-ratified):** semantic search is OFF by
+ * default. `buildEmbeddingProvider` returns a provider ONLY when the
+ * feature is explicitly enabled — otherwise it returns `undefined` and
+ * BOTH tiers are short-circuited. The enable signal is resolved with a
+ * two-level precedence (see `resolveEmbeddingsEnabled`):
+ *
+ *   1. **`EMBEDDINGS_ENABLED` env var** — the low-level override. `true`/`1`
+ *      forces ON, `false`/`0` forces OFF, anything else (incl. unset)
+ *      defers to the persisted setting. Mirrors the cloud wrangler var.
+ *   2. **Persisted `embeddings_enabled`** (config.yaml, wired in by the
+ *      caller — see `getSharedEmbeddingProvider`) — the self-host settings
+ *      toggle, so an operator can turn semantic search on without editing
+ *      the env file. Defaults OFF when unset.
+ *
+ * A caller wired against an `undefined` provider (see
+ * `Store.embeddingProvider`) reports the `embeddings` capability as
  * disabled and `semanticSearch` throws `semantic_unavailable` — the exact
  * same honest-failure path as "no provider configured" (never a silent
  * keyword fallback). The embed-on-write drain simply has nothing to
- * invoke, so it no-ops.
+ * invoke, so it no-ops — no hook work, no backfill sweep, and (because the
+ * ~270MB `@huggingface/transformers` import is dynamic and only happens
+ * inside a real `embed()` call) no model download until a user opts in.
  *
  * `EMBEDDING_MODEL` alone (no `EMBEDDING_API_URL`) has no effect — it only
  * shapes the config-upgrade tier. Resolved per-call (not cached here) so
@@ -58,28 +71,56 @@ export function resolveEmbeddingApiConfig(env: NodeJS.ProcessEnv = process.env):
 }
 
 /**
- * `true` only when `EMBEDDINGS_ENABLED` is explicitly the literal string
- * `"false"` (case-insensitive, trimmed) — the off switch. Every other
- * value, INCLUDING unset, is "enabled": the feature defaults ON (the
- * bundled floor tier makes that safe — zero-config still works), and this
- * var exists to opt OUT, not to opt in.
+ * Parse `EMBEDDINGS_ENABLED` as an explicit tri-state OVERRIDE of the
+ * persisted config setting (all matches case-insensitive + trimmed):
+ *
+ *   - `"true"` / `"1"`  → `true`  (force semantic search ON)
+ *   - `"false"` / `"0"` → `false` (force it OFF)
+ *   - unset / blank / anything unrecognized → `undefined` (no opinion —
+ *     defer to the persisted `embeddings_enabled` setting)
+ *
+ * Returning `undefined` (rather than guessing) for an unrecognized value is
+ * what lets the env var be a true override: only an explicit true/false
+ * short-circuits the persisted setting.
+ */
+export function embeddingsEnabledEnvOverride(env: NodeJS.ProcessEnv = process.env): boolean | undefined {
+  const raw = env.EMBEDDINGS_ENABLED?.trim().toLowerCase();
+  if (!raw) return undefined;
+  if (raw === "true" || raw === "1") return true;
+  if (raw === "false" || raw === "0") return false;
+  return undefined;
+}
+
+/**
+ * The effective enabled state for semantic search. Env override wins; else
+ * the persisted config setting; else OFF — semantic search is opt-in as of
+ * 0.7.3. Pure so both the provider factory and the "why is it off" hint
+ * derive from the same rule.
  */
-export function embeddingsExplicitlyDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
-  return env.EMBEDDINGS_ENABLED?.trim().toLowerCase() === "false";
+export function resolveEmbeddingsEnabled(
+  env: NodeJS.ProcessEnv = process.env,
+  persistedEnabled?: boolean,
+): boolean {
+  return embeddingsEnabledEnvOverride(env) ?? persistedEnabled ?? false;
 }
 
 /**
  * Build the provider the current config selects, or `undefined` when
- * `EMBEDDINGS_ENABLED=false` (see the off-switch doc above). Pure factory
- * (no caching, no I/O beyond what the provider's own constructor does —
- * which is none; both providers lazy-load/lazy-connect on first
- * `embed()`), so it's cheap to call repeatedly in tests. Production
- * callers should go through the shared singleton
+ * semantic search is not enabled (see `resolveEmbeddingsEnabled` — env
+ * override, else the persisted `embeddings_enabled` setting, else OFF).
+ * Pure factory (no caching, no I/O beyond what the provider's own
+ * constructor does — which is none; both providers lazy-load/lazy-connect
+ * on first `embed()`), so it's cheap to call repeatedly in tests.
+ * Production callers should go through the shared singleton
  * (`getSharedEmbeddingProvider`) instead of calling this directly, so the
- * bundled ONNX model — when selected — loads at most once per process.
+ * bundled ONNX model — when selected — loads at most once per process, and
+ * so the persisted setting is threaded in.
  */
-export function buildEmbeddingProvider(env: NodeJS.ProcessEnv = process.env): EmbeddingProvider | undefined {
-  if (embeddingsExplicitlyDisabled(env)) return undefined;
+export function buildEmbeddingProvider(
+  env: NodeJS.ProcessEnv = process.env,
+  opts?: { persistedEnabled?: boolean },
+): EmbeddingProvider | undefined {
+  if (!resolveEmbeddingsEnabled(env, opts?.persistedEnabled)) return undefined;
   const config = resolveEmbeddingApiConfig(env);
   if (config.url) {
     return new ExternalApiEmbeddingProvider({

package/src/embeddings-routes.test.ts

@@ -0,0 +1,188 @@
+/**
+ * Unit coverage for the semantic-search (embeddings) opt-in toggle surface
+ * (0.7.3 fast-follow). Fully sandboxed — a throwaway `PARACHUTE_HOME` so the
+ * config read/write path operates on a scratch `config.yaml`, and the running
+ * "active" state is injected (never touches the real process-shared provider
+ * memo or downloads a model).
+ *
+ * The snapshot builder is pure over (env, persisted, active) so most of the
+ * matrix (env override wins, restart-required gap, default-off) is exercised
+ * without any I/O; the handler tests verify the config write path + 400s.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { readGlobalConfig, writeGlobalConfig } from "./config.ts";
+import {
+  buildEmbeddingsSnapshot,
+  handleEmbeddingsGet,
+  handleEmbeddingsPut,
+  EMBEDDING_MODEL_DOWNLOAD_MB,
+  type EmbeddingsSettingsSnapshot,
+} from "./embeddings-routes.ts";
+
+let tmpHome: string;
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `vault-embed-routes-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpHome, "vault"), { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = tmpHome;
+  // Seed a config.yaml so readGlobalConfig has a file (port only — embeddings unset).
+  writeGlobalConfig({ port: 1940 });
+});
+
+afterEach(() => {
+  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = prevHome;
+  rmSync(tmpHome, { recursive: true, force: true });
+});
+
+// An env with no EMBEDDINGS_ENABLED — the common self-host case.
+const NO_ENV: NodeJS.ProcessEnv = {};
+
+describe("buildEmbeddingsSnapshot", () => {
+  test("default: persisted unset, no env, not active → all off, no restart", () => {
+    const snap = buildEmbeddingsSnapshot({ env: NO_ENV, persistedEnabled: undefined, active: false });
+    expect(snap).toEqual({
+      enabled: false,
+      env_override: null,
+      env_forced: false,
+      effective: false,
+      active: false,
+      restart_required: false,
+      model_download_mb: EMBEDDING_MODEL_DOWNLOAD_MB,
+    });
+  });
+
+  test("persisted on but not yet active → effective on, restart required", () => {
+    const snap = buildEmbeddingsSnapshot({ env: NO_ENV, persistedEnabled: true, active: false });
+    expect(snap.enabled).toBe(true);
+    expect(snap.effective).toBe(true);
+    expect(snap.active).toBe(false);
+    expect(snap.restart_required).toBe(true);
+  });
+
+  test("persisted on and active → no restart required", () => {
+    const snap = buildEmbeddingsSnapshot({ env: NO_ENV, persistedEnabled: true, active: true });
+    expect(snap.restart_required).toBe(false);
+  });
+
+  test("env override ON wins over persisted OFF", () => {
+    const snap = buildEmbeddingsSnapshot({
+      env: { EMBEDDINGS_ENABLED: "true" },
+      persistedEnabled: false,
+      active: true,
+    });
+    expect(snap.enabled).toBe(false); // toggle still reflects persisted
+    expect(snap.env_override).toBe(true);
+    expect(snap.env_forced).toBe(true);
+    expect(snap.effective).toBe(true); // env forces on
+    expect(snap.restart_required).toBe(false); // active matches env-forced effective
+  });
+
+  test("env override OFF wins over persisted ON (with a pending restart while still active)", () => {
+    const snap = buildEmbeddingsSnapshot({
+      env: { EMBEDDINGS_ENABLED: "false" },
+      persistedEnabled: true,
+      active: true,
+    });
+    expect(snap.enabled).toBe(true); // persisted intent preserved
+    expect(snap.env_override).toBe(false);
+    expect(snap.env_forced).toBe(true);
+    expect(snap.effective).toBe(false); // env forces off
+    expect(snap.active).toBe(true);
+    expect(snap.restart_required).toBe(true); // running still on, env wants off
+  });
+
+  test("unrecognized env value defers to persisted (no force)", () => {
+    const snap = buildEmbeddingsSnapshot({
+      env: { EMBEDDINGS_ENABLED: "maybe" },
+      persistedEnabled: true,
+      active: false,
+    });
+    expect(snap.env_override).toBeNull();
+    expect(snap.env_forced).toBe(false);
+    expect(snap.effective).toBe(true);
+  });
+});
+
+describe("handleEmbeddingsGet", () => {
+  test("reflects the persisted config.yaml value", async () => {
+    writeGlobalConfig({ port: 1940, embeddings_enabled: true });
+    const res = handleEmbeddingsGet(false);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as EmbeddingsSettingsSnapshot;
+    expect(body.enabled).toBe(true);
+    expect(body.effective).toBe(true);
+    expect(body.active).toBe(false);
+    expect(body.restart_required).toBe(true);
+  });
+
+  test("unset persisted → enabled false", async () => {
+    const res = handleEmbeddingsGet(false);
+    const body = (await res.json()) as EmbeddingsSettingsSnapshot;
+    expect(body.enabled).toBe(false);
+  });
+});
+
+describe("handleEmbeddingsPut", () => {
+  function putReq(body: unknown): Request {
+    return new Request("http://x/vault/default/.parachute/embeddings", {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: typeof body === "string" ? body : JSON.stringify(body),
+    });
+  }
+
+  test("enabling persists embeddings_enabled: true via the config write path", async () => {
+    const res = await handleEmbeddingsPut(putReq({ enabled: true }), false);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as EmbeddingsSettingsSnapshot;
+    expect(body.enabled).toBe(true);
+    expect(body.restart_required).toBe(true); // persisted on, injected active=false
+    // The setting is actually on disk (config write path reused, not hand-rolled).
+    expect(readGlobalConfig().embeddings_enabled).toBe(true);
+  });
+
+  test("disabling persists embeddings_enabled: false", async () => {
+    writeGlobalConfig({ port: 1940, embeddings_enabled: true });
+    const res = await handleEmbeddingsPut(putReq({ enabled: false }), true);
+    expect(res.status).toBe(200);
+    expect(readGlobalConfig().embeddings_enabled).toBe(false);
+  });
+
+  test("preserves other config fields on write (round-trips through serialize)", async () => {
+    writeGlobalConfig({ port: 1940, discovery: "disabled", autostart: true });
+    await handleEmbeddingsPut(putReq({ enabled: true }), false);
+    const cfg = readGlobalConfig();
+    expect(cfg.embeddings_enabled).toBe(true);
+    expect(cfg.discovery).toBe("disabled");
+    expect(cfg.autostart).toBe(true);
+    expect(cfg.port).toBe(1940);
+  });
+
+  test("non-boolean enabled → 400", async () => {
+    const res = await handleEmbeddingsPut(putReq({ enabled: "yes" }), false);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { field?: string };
+    expect(body.field).toBe("enabled");
+  });
+
+  test("missing enabled → 400", async () => {
+    const res = await handleEmbeddingsPut(putReq({}), false);
+    expect(res.status).toBe(400);
+  });
+
+  test("non-object body → 400", async () => {
+    const res = await handleEmbeddingsPut(putReq("[]"), false);
+    expect(res.status).toBe(400);
+  });
+
+  test("invalid JSON → 400", async () => {
+    const res = await handleEmbeddingsPut(putReq("{not json"), false);
+    expect(res.status).toBe(400);
+  });
+});