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

package/src/routes.ts

@@ -20,6 +20,7 @@ import {
   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";
@@ -41,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";
@@ -51,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,
@@ -133,7 +143,7 @@ import {
   type ExpandMode,
 } from "../core/src/expand.ts";
 import { join, extname, normalize } from "path";
-import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, statSync, unlinkSync, writeFileSync } from "fs";
 import { assetsDir, readGlobalConfig, readVaultConfig } from "./config.ts";
 import { shouldAutoTranscribe } from "./auto-transcribe.ts";
 // usage.ts imports `assetsDir` from config.ts (neutral ground), so this import
@@ -1213,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
@@ -1254,7 +1376,7 @@ 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
@@ -1519,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")
           ? [
@@ -3651,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);
 
@@ -3660,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
@@ -4307,97 +4444,64 @@ 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;
+
+/**
+ * Parse a single-range `Range: bytes=a-b` header (RFC 7233 §2.1 — single
+ * range only, attachments-for-agents design D9, the REST twin of MCP's
+ * `content_offset`). Returns `null` — this function's own contract is
+ * "serve the full response, unranged" — for a missing header, a
+ * MALFORMED value, an unrecognized unit, a multi-range list
+ * (`bytes=0-10,20-30` — ignored, not an error, per D9), or a range this
+ * file can't satisfy (a `start` past EOF). `start`/`end` are both
+ * INCLUSIVE byte offsets; `end` is clamped to `total - 1` when the
+ * request left it open (`bytes=500-`) or asked past EOF.
+ *
+ * IMPORTANT — this `null` contract is NOT the last word for an
+ * unsatisfiable (syntactically-valid but out-of-bounds) range on a real
+ * `Bun.serve()` deployment. Live-verified against an actual socket (not
+ * the in-process `handleStorage()` call the test suite uses): when the
+ * response body is a `Bun.file()` — which `handleStorage`'s full-response
+ * branch below always hands back — Bun's OWN runtime transparently
+ * reinterprets the incoming request's `Range` header a second time and,
+ * for an out-of-bounds range, overrides our 200 with a native
+ * **416 Range Not Satisfiable**, regardless of what this function or
+ * `handleStorage` returned. That's RFC 7233-correct and is being KEPT,
+ * not fought — so in practice, `null` from an out-of-bounds `start`
+ * still results in a 200 from `handleStorage`'s own logic, but the byte
+ * that actually reaches a real client for that specific case is a 416
+ * courtesy of Bun itself. MALFORMED and multi-range headers are NOT
+ * range-shaped at all, so Bun's native layer doesn't touch them — those
+ * two cases genuinely serve the full 200, in-process harness and real
+ * socket alike.
+ */
+export function parseByteRangeHeader(header: string | null, total: number): { start: number; end: number } | null {
+  if (!header || total <= 0) return null;
+  const match = header.match(/^bytes=(\d*)-(\d*)$/);
+  if (!match) return null; // malformed, unrecognized unit, or a multi-range list
+  const [, startRaw, endRaw] = match;
+  if (startRaw === "" && endRaw === "") return null;
+
+  if (startRaw === "") {
+    // Suffix range: last N bytes (`bytes=-500`).
+    const suffixLength = Number(endRaw);
+    if (!Number.isSafeInteger(suffixLength) || suffixLength <= 0) return null;
+    return { start: Math.max(0, total - suffixLength), end: total - 1 };
+  }
+
+  const start = Number(startRaw);
+  if (!Number.isSafeInteger(start) || start < 0 || start >= total) return null;
+  const end = endRaw === "" ? total - 1 : Math.min(Number(endRaw), total - 1);
+  if (!Number.isSafeInteger(end) || end < start) return null;
+  return { start, end };
+}
 
 export async function handleStorage(
   req: Request,
@@ -4561,12 +4665,38 @@ export async function handleStorage(
     const stat = statSync(filePath);
     const ext = extname(filePath).toLowerCase();
     const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
-    const fileBuffer = readFileSync(filePath);
+    const total = stat.size;
+
+    // vault attachments-for-agents design (D9) — the REST twin of MCP's
+    // `content_offset`. `Bun.file(filePath)` resolves lazily: `.slice()`
+    // creates a bounded view and only the requested bytes are actually read
+    // on `.arrayBuffer()`/streaming, replacing the prior whole-file
+    // `readFileSync` (a standing memory smell on a large attachment, e.g. a
+    // 90 MB video) on BOTH the ranged and full-file paths below.
+    const bunFile = Bun.file(filePath);
+    const range = parseByteRangeHeader(req.headers.get("range"), total);
+
+    if (range) {
+      const { start, end } = range; // inclusive
+      return new Response(bunFile.slice(start, end + 1), {
+        status: 206,
+        headers: {
+          "Content-Type": contentType,
+          "Content-Length": String(end - start + 1),
+          "Content-Range": `bytes ${start}-${end}/${total}`,
+          "Accept-Ranges": "bytes",
+          // Defense-in-depth: never let a browser MIME-sniff a stored asset
+          // into an active type — see the full-response branch below.
+          "X-Content-Type-Options": "nosniff",
+        },
+      });
+    }
 
-    return new Response(fileBuffer, {
+    return new Response(bunFile, {
       headers: {
         "Content-Type": contentType,
-        "Content-Length": String(stat.size),
+        "Content-Length": String(total),
+        "Accept-Ranges": "bytes",
         // Defense-in-depth: never let a browser MIME-sniff a stored asset into
         // an active type (e.g. an octet-stream body sniffed as text/html).
         // Combined with the upload blocklist (no .svg/.html) this closes the

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

package/src/server.ts

@@ -19,7 +19,9 @@ 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 { startAttachmentTicketSweep, stopAttachmentTicketSweep } from "./attachment-tickets.ts";
 import { seedOnboardingNotesBestEffort } from "./onboarding-seed.ts";
 import { defaultHookRegistry } from "../core/src/hooks.ts";
 import { registerTriggers } from "./triggers.ts";
@@ -220,6 +222,27 @@ 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();
+
+// Attachment-ticket sweep (vault#612) — drops expired-unspent tickets from
+// the in-process store so an abandoned mint (an agent that never curls)
+// doesn't sit in memory forever. See src/attachment-tickets.ts.
+startAttachmentTicketSweep();
+
 if (process.env.VAULT_AUTH_TOKEN?.trim()) {
   console.log("[auth] VAULT_AUTH_TOKEN set — server-wide operator bearer active");
 }
@@ -599,7 +622,10 @@ 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();
+        stopAttachmentTicketSweep();
         await Promise.all([
           defaultHookRegistry.drain(),
           transcriptionWorker?.stop() ?? Promise.resolve(),