@openparachute/vault 0.7.2 → 0.7.3-rc.10

package/src/server.ts

@@ -19,7 +19,8 @@ import { readVaultConfig, readGlobalConfig, writeGlobalConfig, writeVaultConfig,
 import { existsSync, rmSync } from "fs";
 import { migrateVaultKeys } from "./token-store.ts";
 import { resolveFirstBootVaultName, reservedNameSquatWarnings } from "./vault-name.ts";
-import { getVaultStore, getVaultNameForStore } from "./vault-store.ts";
+import { getVaultStore, getVaultNameForStore, getSharedEmbeddingProvider } from "./vault-store.ts";
+import { EmbeddingWorker, registerEmbeddingHook } from "./embedding-worker.ts";
 import { seedOnboardingNotesBestEffort } from "./onboarding-seed.ts";
 import { defaultHookRegistry } from "../core/src/hooks.ts";
 import { registerTriggers } from "./triggers.ts";
@@ -220,6 +221,22 @@ if (providerName === "transcribe-cpp") {
   }
 }
 
+// Embedding worker (semantic search MVP — EXPERIMENTAL). Unlike
+// transcription (no-op without a discoverable scribe), a provider is
+// ALWAYS resolved here — the bundled floor tier (`onnx-transformers.ts`)
+// is the zero-config default, so a fresh install gets working semantic
+// search with no operator action. The event hook embeds on every note
+// create/update (a no-op edit makes zero provider calls — see
+// `embedding-worker.ts`); the sweep drains the backfill for pre-existing
+// notes and catches anything a dropped dispatch left behind.
+const embeddingWorker = new EmbeddingWorker({
+  provider: getSharedEmbeddingProvider(),
+  vaultList: () => listVaults(),
+  getStore: (name: string) => getVaultStore(name),
+});
+registerEmbeddingHook(defaultHookRegistry, embeddingWorker, (store) => getVaultNameForStore(store as never));
+embeddingWorker.start();
+
 if (process.env.VAULT_AUTH_TOKEN?.trim()) {
   console.log("[auth] VAULT_AUTH_TOKEN set — server-wide operator bearer active");
 }
@@ -599,7 +616,9 @@ async function shutdown(signal: string): Promise<void> {
             ),
           ),
         );
-        // Then drain hooks + stop the transcription worker in parallel.
+        // Then drain hooks + stop the transcription/embedding workers in
+        // parallel.
+        embeddingWorker.stop();
         await Promise.all([
           defaultHookRegistry.drain(),
           transcriptionWorker?.stop() ?? Promise.resolve(),

package/src/vault-embeddings-capability.test.ts

@@ -0,0 +1,82 @@
+/**
+ * GET /api/vault — `embeddings` capability field (semantic search MVP,
+ * EXPERIMENTAL). This tests the WIRING (routes.ts's `handleVault` →
+ * `resolveEmbeddingCap` → the response body) — `resolveEmbeddingCapability`
+ * itself is unit-tested in `src/embedding/capability.test.ts`.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunStore } from "./vault-store.ts";
+import { handleVault } from "./routes.ts";
+import type { EmbeddingCapability } from "./embedding/capability.ts";
+
+let db: Database;
+let store: BunStore;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new BunStore(db);
+});
+
+afterEach(() => {
+  db.close();
+});
+
+const BASE = "http://localhost/api";
+
+describe("GET /api/vault embeddings capability", () => {
+  test("surfaces enabled:true + provider/model when the injected resolver reports available", async () => {
+    const cfg = { name: "default" };
+    const resolveEmbeddingCap = async (): Promise<EmbeddingCapability> => ({
+      enabled: true,
+      provider: "onnx-transformers",
+      model: "Xenova/bge-small-en-v1.5",
+    });
+    const res = await handleVault(
+      new Request(`${BASE}/vault`, { method: "GET" }),
+      store,
+      cfg as any,
+      undefined,
+      undefined, // resolveCapability (transcription) — keep default
+      undefined, // tagScope — keep default
+      resolveEmbeddingCap,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as any;
+    expect(body.embeddings).toEqual({
+      enabled: true,
+      provider: "onnx-transformers",
+      model: "Xenova/bge-small-en-v1.5",
+    });
+  });
+
+  test("surfaces enabled:false with no provider/model when the injected resolver reports unavailable", async () => {
+    const cfg = { name: "default" };
+    const resolveEmbeddingCap = async (): Promise<EmbeddingCapability> => ({ enabled: false });
+    const res = await handleVault(
+      new Request(`${BASE}/vault`, { method: "GET" }),
+      store,
+      cfg as any,
+      undefined,
+      undefined,
+      undefined,
+      resolveEmbeddingCap,
+    );
+    const body = (await res.json()) as any;
+    expect(body.embeddings).toEqual({ enabled: false });
+  });
+
+  test("the production default resolves the shared embedding provider (zero-config -> the bundled floor, enabled:true)", async () => {
+    const cfg = { name: "default" };
+    // No resolver override — exercises the real default wiring
+    // (getSharedEmbeddingProvider() -> resolveEmbeddingCapability()).
+    // Zero-config env -> the bundled onnx-transformers floor, which is
+    // optimistically available() before any real model load — see
+    // src/embedding/onnx-transformers.ts's "lazy-fail, not crash" doc.
+    const res = await handleVault(new Request(`${BASE}/vault`, { method: "GET" }), store, cfg as any);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as any;
+    expect(body.embeddings.enabled).toBe(true);
+    expect(body.embeddings.provider).toBe("onnx-transformers");
+  });
+});

package/src/vault-store-embedding-wiring.test.ts

@@ -0,0 +1,69 @@
+/**
+ * End-to-end wiring test for the `EMBEDDINGS_ENABLED=false` off switch's
+ * error hint (review nano flag on #602): `getVaultStore` should thread
+ * "explicitly disabled" through to `Store.semanticSearch`'s
+ * `semantic_unavailable` hint, not the generic provider-setup message —
+ * see `core/src/store.ts`'s `embeddingDisabledReason` doc comment for why
+ * core can't determine this on its own. Unit coverage for the underlying
+ * `Store` behavior lives in `core/src/store.semantic-search.test.ts`; this
+ * file exercises the REAL `src/vault-store.ts` call site.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { QueryError } from "../core/src/query-operators.ts";
+import {
+  getVaultStore,
+  clearVaultStoreCache,
+  resetSharedEmbeddingProviderForTests,
+} from "./vault-store.ts";
+
+let tmpHome: string;
+let prevHome: string | undefined;
+let prevEnabled: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `vault-embed-wiring-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpHome, "vault", "data"), { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  prevEnabled = process.env.EMBEDDINGS_ENABLED;
+  process.env.PARACHUTE_HOME = tmpHome;
+  clearVaultStoreCache();
+  resetSharedEmbeddingProviderForTests();
+});
+
+afterEach(() => {
+  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = prevHome;
+  if (prevEnabled === undefined) delete process.env.EMBEDDINGS_ENABLED;
+  else process.env.EMBEDDINGS_ENABLED = prevEnabled;
+  clearVaultStoreCache();
+  resetSharedEmbeddingProviderForTests();
+  rmSync(tmpHome, { recursive: true, force: true });
+});
+
+describe("getVaultStore — EMBEDDINGS_ENABLED=false hint wiring", () => {
+  test("store.embeddingDisabledReason is set, and semanticSearch's hint names the off switch", async () => {
+    process.env.EMBEDDINGS_ENABLED = "false";
+    const store = getVaultStore("test");
+    expect(store.embeddingDisabledReason).toBe("semantic search is disabled by EMBEDDINGS_ENABLED=false");
+
+    let caught: unknown;
+    try {
+      await store.semanticSearch("anything");
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(QueryError);
+    expect((caught as QueryError).error_type).toBe("semantic_unavailable");
+    expect((caught as QueryError).hint).toBe("semantic search is disabled by EMBEDDINGS_ENABLED=false");
+  });
+
+  test("no reason set when EMBEDDINGS_ENABLED is unset — the store still has a (bundled-floor) provider", async () => {
+    delete process.env.EMBEDDINGS_ENABLED;
+    const store = getVaultStore("test");
+    expect(store.embeddingDisabledReason).toBeUndefined();
+    expect(store.embeddingProvider).toBeDefined();
+  });
+});

package/src/vault-store.ts

@@ -8,6 +8,8 @@
 import { SqliteStore } from "../core/src/store.ts";
 import { defaultHookRegistry } from "../core/src/hooks.ts";
 import type { Store } from "../core/src/types.ts";
+import type { EmbeddingProvider } from "../core/src/embedding/provider.ts";
+import { buildEmbeddingProvider, embeddingsExplicitlyDisabled } from "./embedding/select.ts";
 import { openVaultDb } from "./db.ts";
 
 export { SqliteStore as BunStore };
@@ -20,14 +22,63 @@ const stores = new Map<string, SqliteStore>();
  *  resolve the vault's assets directory from the store handle. */
 const storeToVault = new WeakMap<SqliteStore, string>();
 
+/**
+ * The one shared `EmbeddingProvider` instance for this process (semantic
+ * search MVP, EXPERIMENTAL). Unlike `defaultTranscriptionProvider()`
+ * (resolved fresh per call — transcription providers are cheap stateless
+ * wrappers), this is memoized deliberately: the bundled floor tier
+ * (`onnx-transformers.ts`) lazy-loads a ~34MB ONNX model on first use, and
+ * every vault this server hosts should share that ONE loaded model rather
+ * than each vault's `Store` triggering its own separate load. Resolved
+ * from `process.env` on first access (so `.env` loaded via
+ * `loadEnvFile()` in `server.ts` is visible) and reused for every
+ * subsequent vault opened this process.
+ *
+ * `undefined` is a legitimate, cacheable resolution — `EMBEDDINGS_ENABLED=
+ * false` (the off switch, see `select.ts`) means "no provider," not
+ * "not resolved yet." A separate `resolved` flag (rather than null-
+ * checking the provider itself) distinguishes the two, so an explicitly-
+ * disabled vault doesn't re-run `buildEmbeddingProvider()` on every call.
+ */
+let sharedEmbeddingProvider: EmbeddingProvider | undefined;
+let sharedEmbeddingProviderResolved = false;
+
+/** The shared embedding provider (see `sharedEmbeddingProvider`'s doc comment). `undefined` when `EMBEDDINGS_ENABLED=false`. */
+export function getSharedEmbeddingProvider(): EmbeddingProvider | undefined {
+  if (!sharedEmbeddingProviderResolved) {
+    sharedEmbeddingProvider = buildEmbeddingProvider();
+    sharedEmbeddingProviderResolved = true;
+  }
+  return sharedEmbeddingProvider;
+}
+
+/** Test-only: force a fresh provider on the next `getSharedEmbeddingProvider()` call. */
+export function resetSharedEmbeddingProviderForTests(): void {
+  sharedEmbeddingProvider = undefined;
+  sharedEmbeddingProviderResolved = false;
+}
+
 /** Get or create a store for a vault. */
 export function getVaultStore(name: string): SqliteStore {
   let store = stores.get(name);
   if (!store) {
     const db = openVaultDb(name);
     // Share the process-wide hook registry so features can register
-    // handlers once at startup and have them fire for every vault.
-    store = new SqliteStore(db, { hooks: defaultHookRegistry });
+    // handlers once at startup and have them fire for every vault. Same
+    // for the embedding provider (see `getSharedEmbeddingProvider`'s doc
+    // comment) — every vault's semantic search resolves the SAME provider
+    // instance. `embeddingDisabledReason` is only ever set here (core can't
+    // read env vars itself — see `Store.embeddingDisabledReason`'s doc
+    // comment), so `semanticSearch`'s no-provider hint can say "explicitly
+    // disabled" instead of generic provider-setup instructions when that's
+    // actually why.
+    store = new SqliteStore(db, {
+      hooks: defaultHookRegistry,
+      embeddingProvider: getSharedEmbeddingProvider(),
+      embeddingDisabledReason: embeddingsExplicitlyDisabled()
+        ? "semantic search is disabled by EMBEDDINGS_ENABLED=false"
+        : undefined,
+    });
     stores.set(name, store);
     storeToVault.set(store, name);
   }

package/src/vault.test.ts

@@ -272,9 +272,9 @@ describe("metadata", async () => {
     expect(published[0].content).toBe("Published");
   });
 
-  test("notes without metadata return undefined metadata", async () => {
+  test("notes without metadata return metadata: {} (vault V1.1 — not an absent key)", async () => {
     const note = await store.createNote("Plain note");
-    expect(note.metadata).toBeUndefined();
+    expect(note.metadata).toEqual({});
   });
 
   test("creates link with metadata", async () => {
@@ -2139,6 +2139,22 @@ describe("HTTP /notes", async () => {
     expect(body[0]).not.toHaveProperty("content");
     expect(body[0]).toHaveProperty("byteSize");
     expect(body[0]).toHaveProperty("preview");
+    expect(body[0]).toHaveProperty("displayTitle");
+  });
+
+  // Title axis (ratified 2026-07-17) — displayTitle on the REST lean shape.
+  test("GET /notes lean shape carries the computed displayTitle", async () => {
+    await store.createNote("# Meeting Notes\nagenda: budget", { path: "meeting" });
+    const res = await handleNotes(mkReq("GET", "/notes"), store, "");
+    const body = await res.json() as any[];
+    expect(body[0].displayTitle).toBe("Meeting Notes");
+  });
+
+  test("GET /notes lean shape reports null displayTitle for an empty note", async () => {
+    await store.createNote("", { path: "empty" });
+    const res = await handleNotes(mkReq("GET", "/notes"), store, "");
+    const body = await res.json() as any[];
+    expect(body[0].displayTitle).toBeNull();
   });
 
   test("GET /notes?include_content=true returns full notes", async () => {
@@ -6609,8 +6625,12 @@ describe("stateless MCP transport", async () => {
     expect(toolNames).not.toContain("merge-tags");
     // Admin tools (vault#376) are hidden too
     expect(toolNames).not.toContain("manage-token");
-    // Read tier is exactly 5 tools (doctor added by the re-tier).
-    expect(toolNames.length).toBe(5);
+    // request-attachment-download is read-tier (upload is write-tier).
+    expect(toolNames).toContain("request-attachment-download");
+    expect(toolNames).not.toContain("request-attachment-upload");
+    // Read tier is exactly 6 tools (doctor added by the re-tier;
+    // request-attachment-download added by the attachment-tickets design).
+    expect(toolNames.length).toBe(6);
 
     closeAllStores();
   });
@@ -6891,15 +6911,15 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     return names;
   }
 
-  test("vault:read sees exactly the 5 read tools (doctor moved admin → read)", async () => {
+  test("vault:read sees exactly the 6 read tools (doctor moved admin → read; request-attachment-download is read-tier)", async () => {
     const names = await listToolNames(["vault:read"]);
     expect(new Set(names)).toEqual(
-      new Set(["query-notes", "list-tags", "find-path", "vault-info", "doctor"]),
+      new Set(["query-notes", "list-tags", "find-path", "vault-info", "doctor", "request-attachment-download"]),
     );
-    expect(names.length).toBe(5);
+    expect(names.length).toBe(6);
   });
 
-  test("vault:read + vault:write sees the 8 read+write tools (tag-schema tools moved write → admin)", async () => {
+  test("vault:read + vault:write sees the 10 read+write tools (tag-schema tools moved write → admin; request-attachment-upload is write-tier)", async () => {
     const names = await listToolNames(["vault:read", "vault:write"]);
     expect(new Set(names)).toEqual(
       new Set([
@@ -6911,9 +6931,11 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
         "create-note",
         "update-note",
         "delete-note",
+        "request-attachment-upload",
+        "request-attachment-download",
       ]),
     );
-    expect(names.length).toBe(8);
+    expect(names.length).toBe(10);
     expect(names).not.toContain("manage-token");
     // Re-tier (this PR): update-tag/delete-tag/rename-tag/merge-tags are now
     // admin-tier — structure/taxonomy curation, not content authorship.
@@ -6925,7 +6947,7 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     expect(names).toContain("delete-note");
   });
 
-  test("vault:admin sees all 14 tools including manage-token + prune-schema + the tag-schema tools", async () => {
+  test("vault:admin sees all 16 tools including manage-token + prune-schema + the tag-schema tools + both attachment-ticket tools", async () => {
     const names = await listToolNames(["vault:read", "vault:write", "vault:admin"]);
     expect(names).toContain("manage-token");
     expect(names).toContain("prune-schema");
@@ -6934,10 +6956,12 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     expect(names).toContain("delete-tag");
     expect(names).toContain("rename-tag");
     expect(names).toContain("merge-tags");
-    expect(names.length).toBe(14);
+    expect(names).toContain("request-attachment-upload");
+    expect(names).toContain("request-attachment-download");
+    expect(names.length).toBe(16);
   });
 
-  test("legacy-derived full token sees all 14 tools (back-compat)", async () => {
+  test("legacy-derived full token sees all 16 tools (back-compat)", async () => {
     const { handleScopedMcp } = await import("./mcp-http.ts");
     const { writeVaultConfig } = await import("./config.ts");
     const { closeAllStores } = await import("./vault-store.ts");
@@ -6970,7 +6994,7 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     } as any);
     const body = await res.json() as any;
     const names: string[] = body.result.tools.map((t: any) => t.name);
-    expect(names.length).toBe(14);
+    expect(names.length).toBe(16);
     expect(names).toContain("manage-token");
     expect(names).toContain("prune-schema");
     expect(names).toContain("doctor");
@@ -7602,6 +7626,31 @@ describe("extractApiKey", () => {
     expect(extractApiKey(req)).toBe("pvt_abc123");
   });
 
+  // RFC 7235: the auth-scheme token is case-insensitive (V1.4). A client
+  // sending `bearer`/`BEARER`/`BeArEr` must authenticate identically to
+  // one sending the canonical `Bearer` — only the credentials that follow
+  // the scheme are case-sensitive, and those come through verbatim.
+  test("extracts from a lowercase `bearer` scheme (RFC 7235 case-insensitivity)", () => {
+    const req = new Request("http://localhost/api/notes", {
+      headers: { Authorization: "bearer pvt_abc123" },
+    });
+    expect(extractApiKey(req)).toBe("pvt_abc123");
+  });
+
+  test("extracts from a mixed-case `BeArEr` scheme", () => {
+    const req = new Request("http://localhost/api/notes", {
+      headers: { Authorization: "BeArEr pvt_abc123" },
+    });
+    expect(extractApiKey(req)).toBe("pvt_abc123");
+  });
+
+  test("the token itself stays case-sensitive — only the scheme is folded", () => {
+    const req = new Request("http://localhost/api/notes", {
+      headers: { Authorization: "bearer PvT_MixedCase123" },
+    });
+    expect(extractApiKey(req)).toBe("PvT_MixedCase123");
+  });
+
   test("extracts from X-API-Key header", () => {
     const req = new Request("http://localhost/api/notes", {
       headers: { "X-API-Key": "pvk_xyz789" },