@openparachute/vault 0.7.2 → 0.7.3-rc.10

package/src/routes.ts

@@ -17,8 +17,10 @@ import {
   collectUnknownTagWarnings,
   emptySearchWarning,
   ignoredParamWarning,
+  truncatedResultsWarning,
   computeSearchDidYouMean,
   searchDidYouMeanWarning,
+  embeddingsPendingWarning,
   type QueryWarning,
 } from "../core/src/query-warnings.ts";
 import { SEARCH_MODES, buildLiteralSearchQuery, isValidSearchMode, type SearchMode } from "../core/src/search-query.ts";
@@ -40,6 +42,10 @@ import {
   type ContentRange,
 } from "../core/src/content-range.ts";
 import { attachValidationStatus, enforceStrictWrite, applySchemaDefaults } from "../core/src/mcp.ts";
+import {
+  BLOCKED_ATTACHMENT_EXTENSIONS,
+  ATTACHMENT_MIME_TYPES,
+} from "../core/src/attachment/policy.ts";
 import type { ValidationWarning } from "../core/src/schema-defaults.ts";
 import { logStrictBypass } from "./scopes.ts";
 import * as linkOps from "../core/src/links.ts";
@@ -50,6 +56,11 @@ import {
   resolveTranscriptionCapability,
   type TranscriptionCapability,
 } from "./transcription/capability.ts";
+import {
+  resolveEmbeddingCapability,
+  type EmbeddingCapability,
+} from "./embedding/capability.ts";
+import { getSharedEmbeddingProvider } from "./vault-store.ts";
 import { loadSchemaConfig } from "../core/src/schema-defaults.ts";
 import {
   buildExpandVisibility,
@@ -1212,6 +1223,118 @@ async function handleNotesInner(
         return json(result);
       }
 
+      // Semantic search (EXPERIMENTAL — semantic search MVP). Mirrors the
+      // MCP `query-notes` tool's `near_text`/`semantic` params — see
+      // `core/src/mcp.ts`'s `query-notes` handler for the identical
+      // validation/shape this branch reproduces over REST. Checked BEFORE
+      // the search/cursor exclusivity check below so `semantic=true`
+      // combined with `search=` or `cursor=` gets its OWN error naming
+      // `semantic`, not silently routed into the search branch.
+      const nearText = parseQuery(url, "near_text");
+      const semantic = parseBool(parseQuery(url, "semantic"), false);
+      if (semantic) {
+        if (search) {
+          return json(
+            {
+              error: "semantic is incompatible with full-text search — pick one (semantic ranks by meaning via near_text; search ranks by keyword).",
+              code: "INVALID_QUERY",
+              error_type: "invalid_query",
+              field: "semantic",
+              hint: "drop `search` when using `semantic`, or drop `semantic`/`near_text` to use keyword search",
+            },
+            400,
+          );
+        }
+        if (parseQuery(url, "cursor") !== null) {
+          return json(
+            {
+              error: "cursor is incompatible with semantic search — ranking is by similarity, not a stable row order to page through.",
+              code: "INVALID_QUERY",
+              error_type: "invalid_query",
+              field: "semantic",
+              hint: "drop `cursor` when using `semantic`",
+            },
+            400,
+          );
+        }
+        if (!nearText || !nearText.trim()) {
+          return json(
+            {
+              error: "semantic=true requires `near_text` — the free text to rank notes by meaning.",
+              code: "INVALID_QUERY",
+              error_type: "invalid_query",
+              field: "near_text",
+              hint: "pass ?near_text=...&semantic=true",
+            },
+            400,
+          );
+        }
+        const parsed = parseNotesQueryOpts(url);
+        if (parsed.error) return parsed.error;
+        try {
+          const semanticResult = await store.semanticSearch(nearText, { ...parsed.queryOpts, cursor: undefined });
+          const semanticWarnings: QueryWarning[] = [];
+          if (semanticResult.pendingCount > 0) {
+            semanticWarnings.push(
+              embeddingsPendingWarning(semanticResult.pendingCount, semanticResult.totalCandidates),
+            );
+          }
+          const filtered = filterNotesByTagScope(semanticResult.notes, tagScope.allowed, tagScope.raw);
+          const includeContent = parseBool(parseQuery(url, "include_content"), false);
+          const contentRange = parseContentRangeQuery(url, includeContent);
+          if (contentRange.error) return contentRange.error;
+          const inclMeta = parseIncludeMetadata(url);
+          let output: any[] = includeContent ? filtered.map((n) => ({ ...n })) : filtered.map(toNoteIndex);
+          const expand = parseExpandParams(url, db, tagScope);
+          if (expand && includeContent) {
+            for (const n of output) expand.ctx.expanded.add(n.id);
+            for (const n of output) {
+              if (typeof n.content === "string") {
+                n.content = expandContent(n.content, expand.ctx, expand.depth);
+              }
+            }
+          }
+          if (contentRange.range && includeContent) {
+            for (const n of output) applyContentRange(n, contentRange.range);
+          }
+          if (inclMeta !== undefined && inclMeta !== true) {
+            output = output.map((n: any) => filterMetadata(n, inclMeta));
+          }
+          if (parseBool(parseQuery(url, "include_link_count"), false)) {
+            const counts = linkOps.getLinkCounts(db, output.map((n: any) => n.id), parseLinkCountDirection(url));
+            for (const n of output) n.linkCount = counts.get(n.id) ?? 0;
+          }
+          return jsonWithWarnings(output, semanticWarnings);
+        } catch (e: any) {
+          if (e && e.name === "QueryError") {
+            // `semantic_unavailable` (no/not-ready provider) is a capability
+            // gap, not a malformed request — 503, distinct from every other
+            // QueryError's 400. Never a silent fallback to keyword search.
+            const status = e.error_type === "semantic_unavailable" ? 503 : 400;
+            return json(
+              {
+                error: e.message,
+                code: e.code ?? "INVALID_QUERY",
+                error_type: e.error_type ?? "invalid_query",
+                ...(e.field !== undefined ? { field: e.field } : {}),
+                ...(e.got !== undefined ? { got: e.got } : {}),
+                ...(e.hint !== undefined ? { hint: e.hint } : {}),
+              },
+              status,
+            );
+          }
+          throw e;
+        }
+      }
+      // `near_text` without `semantic: true` is inert — same ignored_param
+      // convention as `search_mode` without `search` (below). Rather than a
+      // whole extra branch, this warning rides whichever normal path (search
+      // or structured query) actually runs — appended just before each
+      // branch's own `jsonWithWarnings` call would otherwise return.
+      const nearTextIgnored: QueryWarning[] = nearText !== null
+        ? [ignoredParamWarning("near_text", "`semantic=true` is required to activate near_text — pass both together")]
+        : [];
+
       // Cursor + full-text search is mutually exclusive (vault#313 reviewer).
       // FTS owns its own ordering (relevance, not updated_at), so a cursor
       // would skip rows. MCP rejects this combo at `core/src/mcp.ts`; REST
@@ -1253,7 +1376,24 @@ async function handleNotesInner(
         // (default, unchanged); explicit asc/desc switches to created_at.
         const sort = (parseQuery(url, "sort") as "asc" | "desc" | null) ?? undefined;
 
-        const searchWarnings: QueryWarning[] = [];
+        const searchWarnings: QueryWarning[] = [...nearTextIgnored];
+        // `offset` under full-text search (vault contracts-brief V1.2):
+        // `searchNotes` has no offset parameter at all — FTS5 ranks by
+        // relevance, not a stable row order, so paging by offset over it
+        // is unsound. Rather than silently return page 1 with no signal
+        // (the pre-existing behavior — `?search=x&offset=50` == `?search=x`),
+        // flag it. Presence check (not truthiness) so `offset=0` — a caller
+        // being explicit about "start" — still warns; it's equally
+        // meaningless here. The structured-query path (below) has real
+        // offset support and is unaffected.
+        if (parseQuery(url, "offset") !== null) {
+          searchWarnings.push(
+            ignoredParamWarning(
+              "offset",
+              "full-text search has no stable row order to offset into — results are always page 1, ranked by relevance",
+            ),
+          );
+        }
         let rawResults: Note[];
         // "Only whitespace/quotes" (vault#551 edge case) — short-circuit
         // BEFORE ever calling FTS5 rather than risk a syntax error (or a
@@ -1501,6 +1641,7 @@ async function handleNotesInner(
       // IS the structured-query path precisely because `search` was absent
       // or empty, so a `search_mode` param here is always a no-op.
       const queryWarnings: QueryWarning[] = [
+        ...nearTextIgnored,
         ...collectRemovedParamWarnings(url),
         ...(parseQuery(url, "search_mode")
           ? [
@@ -1558,6 +1699,15 @@ async function handleNotesInner(
         }
         throw e;
       }
+      // Truncation-honesty (vault contracts-brief V1.3): captured BEFORE
+      // near/tag-scope filtering, which can only shrink the set further —
+      // this reflects whether the underlying store query actually hit its
+      // `limit` (i.e. there may be more rows the caller never saw). Cursor
+      // mode is exempt — it already carries `next_cursor` as the honest
+      // "more may follow" signal, so a second warning would be redundant.
+      if (!cursorMode && results.length === queryOpts.limit) {
+        queryWarnings.push(truncatedResultsWarning(queryOpts.limit));
+      }
 
       // Near-scope filter (graph neighborhood)
       const nearNoteId = parseQuery(url, "near[note_id]");
@@ -3624,6 +3774,14 @@ export async function handleVault(
    * which pass this — is unaffected.
    */
   tagScope: TagScopeCtx = NO_TAG_SCOPE,
+  /**
+   * Injection seam (semantic search MVP, EXPERIMENTAL) for the embeddings
+   * capability probe — same shape as `resolveCapability` above. Production
+   * omits it and resolves the shared embedding provider's availability;
+   * tests inject a deterministic resolver.
+   */
+  resolveEmbeddingCap: () => Promise<EmbeddingCapability> = () =>
+    resolveEmbeddingCapability(getSharedEmbeddingProvider()),
 ): Promise<Response> {
   const url = new URL(req.url);
 
@@ -3633,6 +3791,12 @@ export async function handleVault(
     // and available. `minutes_remaining` is omitted (cloud/plan concern;
     // self-host is unmetered). This is the field Notes gates the mic on.
     result.transcription = await resolveCapability();
+    // Embeddings capability flag (semantic search MVP, EXPERIMENTAL) — same
+    // "configured AND available" contract as transcription above. This is
+    // the honest advertisement `query-notes { semantic: true }` backs: a
+    // vault reporting `enabled: false` gets `semantic_unavailable`, never a
+    // silent keyword fallback.
+    result.embeddings = await resolveEmbeddingCap();
     // Front-door structural map — ALWAYS included (unlike `stats`, which is
     // include_stats-gated): three cheap grouped-COUNT queries, so a fresh
     // reader orients in one call. Scope-aware: a tag-scoped token's map
@@ -4280,97 +4444,14 @@ export const MAX_UPLOAD_BYTES = 100 * 1024 * 1024; // 100MB
  */
 export const MAX_REQUEST_BODY_BYTES = MAX_UPLOAD_BYTES + 20 * 1024 * 1024; // 120MB
 
-// Storage upload policy: DENY-LIST (vault#517). A knowledge vault stores
-// arbitrary files — ebooks, office docs, datasets, archives, binaries — so we
-// accept ANY upload EXCEPT the handful of types a browser can execute as
-// active content in our origin when served back from /storage/. (The prior
-// allowlist rejected the long tail: .epub/.csv/.zip/… all came back "File type
-// not allowed".)
-//
-// BLOCKED — same-origin-XSS / active-content set:
-//   .html/.htm/.xhtml/.shtml/.xht  HTML — embeds <script>
-//   .svg                           XML image — embeds <script>
-//   .xml                           can carry XSLT / be parsed as XHTML
-//   .js/.mjs/.cjs                  JavaScript
-//   .css                           style-injection / UI-redress vector
-//
-// Two independent guards keep every STORED file inert when served:
-//   1. Only the curated MIME_TYPES below map to a real (always passive) type;
-//      every other extension serves as application/octet-stream — a download,
-//      never rendered.
-//   2. The GET byte-serve response pins `X-Content-Type-Options: nosniff`, so
-//      a browser can't sniff an octet-stream body into an executable type.
-// The blocklist is belt-and-suspenders on top of those: even if a future MIME
-// entry or an upstream proxy weakened (1) or (2), these extensions still never
-// land on disk. If a future use case needs SVG, sanitize on read (strip
-// <script>/<foreignObject>) and revisit.
-const BLOCKED_EXTENSIONS = new Set([
-  ".html", ".htm", ".xhtml", ".shtml", ".xht",
-  ".svg",
-  ".xml",
-  ".js", ".mjs", ".cjs",
-  ".css",
-]);
-
-// Explicit MIME types for the commonly-previewed formats. Anything accepted
-// but absent here serves as application/octet-stream — a download, never
-// rendered (e.g. .pages/.key/.numbers/.azw3/.exe/arbitrary binaries). None of
-// these map to an active type (text/html, image/svg+xml), so a served asset
-// can't execute script; `nosniff` on the GET response makes that ironclad.
-//
-// INVARIANT: never add an entry that maps to a browser-active type —
-// text/html, image/svg+xml, application/xhtml+xml, text/javascript,
-// application/wasm, text/css. Doing so re-enables same-origin execution for
-// that extension (and would mean it must also join BLOCKED_EXTENSIONS).
-const MIME_TYPES: Record<string, string> = {
-  // Audio
-  ".wav": "audio/wav",
-  ".mp3": "audio/mpeg",
-  ".m4a": "audio/mp4",
-  ".ogg": "audio/ogg",
-  ".oga": "audio/ogg",
-  ".opus": "audio/opus",
-  ".aac": "audio/aac",
-  ".flac": "audio/flac",
-  ".webm": "audio/webm",
-  // Image
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".bmp": "image/bmp",
-  ".tiff": "image/tiff",
-  ".tif": "image/tiff",
-  ".heic": "image/heic",
-  ".heif": "image/heif",
-  ".avif": "image/avif",
-  // Video
-  ".mp4": "video/mp4",
-  ".m4v": "video/x-m4v",
-  ".mov": "video/quicktime",
-  // Documents / ebooks / data
-  ".pdf": "application/pdf",
-  ".epub": "application/epub+zip",
-  ".mobi": "application/x-mobipocket-ebook",
-  ".txt": "text/plain; charset=utf-8",
-  ".md": "text/markdown; charset=utf-8",
-  ".markdown": "text/markdown; charset=utf-8",
-  ".rtf": "application/rtf",
-  ".csv": "text/csv; charset=utf-8",
-  ".tsv": "text/tab-separated-values; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".doc": "application/msword",
-  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-  ".ppt": "application/vnd.ms-powerpoint",
-  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-  ".xls": "application/vnd.ms-excel",
-  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-  ".odt": "application/vnd.oasis.opendocument.text",
-  ".ods": "application/vnd.oasis.opendocument.spreadsheet",
-  ".odp": "application/vnd.oasis.opendocument.presentation",
-  ".zip": "application/zip",
-};
+// Storage upload policy (extension blocklist + MIME lookup) now lives in
+// core/src/attachment/policy.ts — the canonical source shared with the
+// attachment-ticket mint/spend path (vault attachment-tickets design,
+// "shared BLOCKED_EXTENSIONS"), so a blocked extension can never diverge
+// between REST and tickets. See that module's doc comment for the full
+// same-origin-XSS rationale and the MIME curation invariant.
+const BLOCKED_EXTENSIONS = BLOCKED_ATTACHMENT_EXTENSIONS;
+const MIME_TYPES = ATTACHMENT_MIME_TYPES;
 
 export async function handleStorage(
   req: Request,

package/src/routing.ts

@@ -103,6 +103,7 @@ import {
 } from "./mirror-routes.ts";
 import { getMirrorManager } from "./mirror-registry.ts";
 import { buildUsageReport } from "./usage.ts";
+import { handleTicketSpend } from "./attachment-tickets.ts";
 
 /**
  * Decorate a 401 response from the MCP endpoint with the RFC 9728 challenge
@@ -490,6 +491,22 @@ export async function route(
     return handleAuthorizationServer(req, vaultName);
   }
 
+  // Attachment ticket spend (attachment-tickets design, Wave 1) — no auth
+  // beyond the ticket itself; the ticket IS the credential (single-use,
+  // short TTL, scoped to exactly one upload slot or one attachment's
+  // bytes). Deliberately placed BEFORE `authenticateVaultRequest` below —
+  // a bearer-less runtime (a bare `curl`) must be able to spend a ticket
+  // without ever holding this vault's API key. The path segment
+  // (`/tickets/<id>`) is outside the authed `/api` tree and outside
+  // `/mcp` on purpose — see `request-attachment-upload`/`-download`
+  // (core/src/mcp.ts) for where tickets are minted.
+  const vaultTicketMatch = subpath.match(/^\/tickets\/([^/]+)$/);
+  if (vaultTicketMatch) {
+    const ticketId = decodeURIComponent(vaultTicketMatch[1]!);
+    const store = getVaultStore(vaultName);
+    return handleTicketSpend(req, ticketId, vaultName, store);
+  }
+
   // ---------------------------------------------------------------------
   // Authenticated surface
   // ---------------------------------------------------------------------

package/src/scribe-discovery.test.ts

@@ -7,7 +7,7 @@
  */
 
 import { describe, test, expect, beforeEach } from "bun:test";
-import { resolveScribeUrl, clearScribeUrlCache } from "./scribe-discovery.ts";
+import { resolveScribeUrl, getCachedScribeUrl, clearScribeUrlCache } from "./scribe-discovery.ts";
 
 function mkManifest(services: Array<{ name: string; port: number; origin?: string }>): typeof import("./services-manifest.ts").readManifest {
   return () => ({
@@ -75,3 +75,78 @@ describe("resolveScribeUrl", () => {
     expect(resolveScribeUrl(env, manifest)).toBe("http://127.0.0.1:1943");
   });
 });
+
+describe("getCachedScribeUrl (vault contracts-brief V1.5 — TTL, not process-lifetime)", () => {
+  // A manifest fn that counts calls, so tests can prove whether the cache
+  // actually skipped a re-read (rather than just asserting the RESULT,
+  // which would pass even if the cache silently didn't cache at all).
+  function mkCountingManifest(port: number): { impl: typeof import("./services-manifest.ts").readManifest; calls: () => number } {
+    let calls = 0;
+    const impl = (() => {
+      calls++;
+      return {
+        services: [
+          { name: "parachute-scribe", port, paths: ["/parachute-scribe"], health: "/health", version: "0.0.0-test" },
+        ],
+      };
+    }) as unknown as typeof import("./services-manifest.ts").readManifest;
+    return { impl, calls: () => calls };
+  }
+
+  test("within the TTL window, repeated calls reuse the cached value (manifest read once)", () => {
+    const env = {} as NodeJS.ProcessEnv;
+    const { impl, calls } = mkCountingManifest(1943);
+    let t = 1_000_000;
+    const now = () => t;
+
+    expect(getCachedScribeUrl(env, impl, console, now)).toBe("http://127.0.0.1:1943");
+    t += 1_000; // well inside the 30s TTL
+    expect(getCachedScribeUrl(env, impl, console, now)).toBe("http://127.0.0.1:1943");
+    expect(calls()).toBe(1);
+  });
+
+  test("after the TTL expires, the next call re-resolves — a scribe that appeared mid-process is picked up without a restart", () => {
+    const env = {} as NodeJS.ProcessEnv;
+    // First manifest: no scribe registered yet.
+    let manifestCalls = 0;
+    let portToReturn: number | null = null;
+    const impl = (() => {
+      manifestCalls++;
+      return {
+        services: portToReturn === null
+          ? []
+          : [{ name: "parachute-scribe", port: portToReturn, paths: ["/parachute-scribe"], health: "/health", version: "0.0.0-test" }],
+      };
+    }) as unknown as typeof import("./services-manifest.ts").readManifest;
+    let t = 1_000_000;
+    const now = () => t;
+
+    // Nothing registered yet — vault boots before scribe.
+    expect(getCachedScribeUrl(env, impl, console, now)).toBeUndefined();
+
+    // Scribe installs and registers itself mid-process — still within TTL,
+    // so the stale "undefined" is what a caller sees (this is the bound the
+    // TTL accepts, not the bug being fixed).
+    portToReturn = 1943;
+    t += 1_000;
+    expect(getCachedScribeUrl(env, impl, console, now)).toBeUndefined();
+    expect(manifestCalls).toBe(1); // still cached — didn't re-read
+
+    // TTL elapses — next probe re-reads and picks up the now-live scribe,
+    // with no vault restart in between.
+    t += 30_000;
+    expect(getCachedScribeUrl(env, impl, console, now)).toBe("http://127.0.0.1:1943");
+    expect(manifestCalls).toBe(2);
+  });
+
+  test("clearScribeUrlCache forces a fresh resolve even within the TTL window", () => {
+    const env = {} as NodeJS.ProcessEnv;
+    const { impl, calls } = mkCountingManifest(1943);
+    const now = () => 1_000_000;
+
+    expect(getCachedScribeUrl(env, impl, console, now)).toBe("http://127.0.0.1:1943");
+    clearScribeUrlCache();
+    expect(getCachedScribeUrl(env, impl, console, now)).toBe("http://127.0.0.1:1943");
+    expect(calls()).toBe(2);
+  });
+});

package/src/scribe-discovery.ts

@@ -68,24 +68,43 @@ export function resolveScribeUrl(
 }
 
 /**
- * Process-lifetime cache. Computed at first call (typically during server
- * boot), reused for every subsequent transcription request. Operators who
- * change the scribe URL via `services.json` (re-install of scribe with a
- * different port) need to restart vault; we deliberately don't watch the
- * file because the v0.6 deploy model has a single restart-on-change story.
+ * Short-TTL cache (vault contracts-brief V1.5 — was process-lifetime).
+ * `resolveScribeUrl` is just an env read + a `services.json` stat/read, cheap
+ * enough to redo on this cadence — but the transcription capability probe
+ * (`GET /api/vault`, `src/transcription/capability.ts`) can be hit often
+ * enough that re-reading the manifest on EVERY call is wasteful. A TTL
+ * splits the difference: scribe installing/moving/starting mid-process (the
+ * real deploy sequencing — hub can bring scribe up after vault) is picked up
+ * within `SCRIBE_URL_CACHE_TTL_MS` instead of requiring a vault restart,
+ * while a steady-state deployment still avoids a filesystem read per
+ * request. Previously this was a `let ... = null` sentinel computed once at
+ * first call and reused for the rest of the process — that's the staleness
+ * this replaces.
  *
  * Tests should pass an explicit `env` + `readManifestImpl` to `resolveScribeUrl`
- * directly to bypass the cache.
+ * directly to bypass the cache, or use the `now` injection seam here to
+ * simulate TTL expiry without real sleeps.
  */
+const SCRIBE_URL_CACHE_TTL_MS = 30_000;
+
 let cachedScribeUrl: string | undefined | null = null;
+let cachedAt = 0;
 
-export function getCachedScribeUrl(): string | undefined {
-  if (cachedScribeUrl === null) {
-    cachedScribeUrl = resolveScribeUrl();
+export function getCachedScribeUrl(
+  env: NodeJS.ProcessEnv = process.env,
+  readManifestImpl: typeof readManifest = readManifest,
+  logger: { warn?: (...args: unknown[]) => void } = console,
+  now: () => number = Date.now,
+): string | undefined {
+  const t = now();
+  if (cachedScribeUrl === null || t - cachedAt >= SCRIBE_URL_CACHE_TTL_MS) {
+    cachedScribeUrl = resolveScribeUrl(env, readManifestImpl, logger);
+    cachedAt = t;
   }
   return cachedScribeUrl;
 }
 
 export function clearScribeUrlCache(): void {
   cachedScribeUrl = null;
+  cachedAt = 0;
 }

package/src/semantic-search-routes.test.ts

@@ -0,0 +1,161 @@
+/**
+ * REST face of semantic search (EXPERIMENTAL — semantic search MVP).
+ * Mirrors the MCP `query-notes` tool's `near_text`/`semantic` params —
+ * see `core/src/mcp-semantic-search.test.ts` for the MCP-side twin of
+ * this suite. Fully sandboxed — in-memory SQLite, mocked provider, no
+ * daemon, no real model.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunStore } from "./vault-store.ts";
+import { handleNotes } from "./routes.ts";
+import type { EmbeddingProvider, EmbedInput, EmbedResult, ProviderAvailability } from "../core/src/embedding/provider.ts";
+import { encodeVector, normalize } from "../core/src/embedding/vector-codec.ts";
+
+const MODEL = "mock-model";
+const DIMS = 4;
+
+class MockEmbeddingProvider implements EmbeddingProvider {
+  readonly name = "mock";
+  readonly model = MODEL;
+  readonly dims = DIMS;
+  available_ = true;
+  reason_: string | undefined;
+
+  async embed(input: EmbedInput): Promise<EmbedResult> {
+    return { vectors: input.texts.map(() => new Float32Array([1, 0, 0, 0])), model: this.model, dims: this.dims };
+  }
+
+  async available(): Promise<ProviderAvailability> {
+    return this.available_ ? { ok: true } : { ok: false, reason: this.reason_ };
+  }
+}
+
+let db: Database;
+let store: BunStore;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+});
+
+afterEach(() => {
+  db.close();
+});
+
+const BASE = "http://localhost/api";
+
+function get(store: BunStore, path: string): Promise<Response> {
+  return handleNotes(new Request(`${BASE}/notes${path}`, { method: "GET" }), store, "");
+}
+
+function insertVector(noteId: string, vector: number[]): void {
+  const encoded = encodeVector(normalize(new Float32Array(vector)));
+  db.prepare(
+    `INSERT INTO note_vectors (note_id, chunk_ix, vector, dims, model, content_hash, embedded_at) VALUES (?, 0, ?, ?, ?, ?, ?)`,
+  ).run(noteId, encoded, DIMS, MODEL, "hash", new Date().toISOString());
+}
+
+/** Decode the `X-Parachute-Warnings` header (vault#550 — percent-encoded JSON; see `jsonWithWarnings` in routes.ts). */
+function decodeWarningsHeader(res: Response): any[] | null {
+  const raw = res.headers.get("X-Parachute-Warnings");
+  if (!raw) return null;
+  return JSON.parse(decodeURIComponent(raw));
+}
+
+describe("GET /notes?near_text=&semantic= (REST, EXPERIMENTAL)", () => {
+  it("400s when semantic=true is passed without near_text", async () => {
+    store = new BunStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    const res = await get(store, "?semantic=true");
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error_type).toBe("invalid_query");
+    expect(body.field).toBe("near_text");
+  });
+
+  it("400s when semantic=true is combined with search", async () => {
+    store = new BunStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    const res = await get(store, "?semantic=true&near_text=x&search=y");
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.field).toBe("semantic");
+  });
+
+  it("400s when semantic=true is combined with cursor", async () => {
+    store = new BunStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    const res = await get(store, "?semantic=true&near_text=x&cursor=");
+    expect(res.status).toBe(400);
+  });
+
+  it("503s with a structured semantic_unavailable error when no provider is configured", async () => {
+    store = new BunStore(db); // no embeddingProvider
+    const res = await get(store, "?semantic=true&near_text=anything");
+    expect(res.status).toBe(503);
+    const body = await res.json();
+    expect(body.error_type).toBe("semantic_unavailable");
+  });
+
+  it("M2: 503s (not a raw 500) when the provider's embed() call fails mid-flight, e.g. a lazy model load blowing up on the first real query", async () => {
+    const provider = new MockEmbeddingProvider();
+    provider.embed = async () => {
+      throw new Error("bundled ONNX embedding model failed to load: simulated ORT failure");
+    };
+    store = new BunStore(db, { embeddingProvider: provider });
+    const res = await get(store, "?semantic=true&near_text=anything");
+    expect(res.status).toBe(503);
+    const body = await res.json();
+    expect(body.error_type).toBe("semantic_unavailable");
+  });
+
+  it("near_text without semantic=true is inert and carries an ignored_param warning (via the header, bare-array body)", async () => {
+    store = new BunStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    await store.createNote("hello world");
+    const res = await get(store, "?near_text=hello");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(Array.isArray(body)).toBe(true);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings?.some((w: any) => w.code === "ignored_param" && w.param === "near_text")).toBe(true);
+  });
+
+  it("returns notes ranked by meaning", async () => {
+    store = new BunStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    const close = await store.createNote("close note", { path: "close" });
+    const far = await store.createNote("far note", { path: "far" });
+    insertVector(close.id, [1, 0, 0, 0]);
+    insertVector(far.id, [0, 1, 0, 0]);
+
+    const res = await get(store, "?semantic=true&near_text=anything&include_content=true");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as any[];
+    expect(body.map((n) => n.id)).toEqual([close.id, far.id]);
+    expect(body[0].score).toBeCloseTo(1, 4);
+  });
+
+  it("composes with tag filters", async () => {
+    store = new BunStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    const tagged = await store.createNote("tagged", { path: "tagged", tags: ["project"] });
+    const untagged = await store.createNote("untagged", { path: "untagged" });
+    insertVector(tagged.id, [1, 0, 0, 0]);
+    insertVector(untagged.id, [1, 0, 0, 0]);
+
+    const res = await get(store, "?semantic=true&near_text=x&tag=project");
+    const body = (await res.json()) as any[];
+    expect(body.map((n) => n.id)).toEqual([tagged.id]);
+  });
+
+  it("attaches embeddings_pending warning (via the header) with counts while backfill is incomplete", async () => {
+    store = new BunStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    const embedded = await store.createNote("embedded", { path: "a" });
+    await store.createNote("pending", { path: "b" });
+    insertVector(embedded.id, [1, 0, 0, 0]);
+
+    const res = await get(store, "?semantic=true&near_text=x&include_content=true");
+    const body = (await res.json()) as any[];
+    expect(body.map((n: any) => n.id)).toEqual([embedded.id]);
+    const warnings = decodeWarningsHeader(res);
+    const w = warnings?.find((x: any) => x.code === "embeddings_pending");
+    expect(w).toBeDefined();
+    expect(w.pending).toBe(1);
+    expect(w.total_candidates).toBe(2);
+  });
+});