@openparachute/vault 0.7.3-rc.1 → 0.7.3-rc.10

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

@@ -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");