libsql-search 0.7.1 → 0.9.0

package/dist/index.esm.js

@@ -786,6 +786,9 @@ function prepareTextForEmbedding(fields) {
 const SQL_IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const DEFAULT_SEARCH_LIMIT = 10;
 const MAX_SEARCH_LIMIT = 100;
+const DEFAULT_SEARCH_CANDIDATE_MULTIPLIER = 4;
+const MIN_SEARCH_CANDIDATES = 32;
+const MAX_SEARCH_CANDIDATES = MAX_SEARCH_LIMIT * 10;
 function validateSqlIdentifier(identifier, name = "identifier") {
   if (typeof identifier !== "string" || !SQL_IDENTIFIER_PATTERN.test(identifier)) {
     throw new Error(
@@ -804,6 +807,23 @@ function normalizeSearchLimit(limit = DEFAULT_SEARCH_LIMIT) {
   }
   return limit;
 }
+function defaultSearchCandidates(limit) {
+  return Math.min(
+    Math.max(limit * DEFAULT_SEARCH_CANDIDATE_MULTIPLIER, MIN_SEARCH_CANDIDATES),
+    MAX_SEARCH_CANDIDATES
+  );
+}
+function normalizeSearchCandidates(candidates, limit) {
+  if (candidates === void 0) {
+    return defaultSearchCandidates(limit);
+  }
+  if (typeof candidates !== "number" || !Number.isFinite(candidates) || !Number.isInteger(candidates) || candidates < limit || candidates > MAX_SEARCH_CANDIDATES) {
+    throw new Error(
+      `Invalid search candidates: expected an integer from the search limit (${limit}) to ${MAX_SEARCH_CANDIDATES}`
+    );
+  }
+  return candidates;
+}
 function normalizeVectorDimensions(dimensions) {
   if (typeof dimensions !== "number" || !Number.isFinite(dimensions) || !Number.isInteger(dimensions) || dimensions < 1) {
     throw new Error("Invalid vector dimensions: expected a positive integer");
@@ -811,6 +831,16 @@ function normalizeVectorDimensions(dimensions) {
   return dimensions;
 }
 
+class IndexingError extends Error {
+  phase;
+  failures;
+  constructor(message, phase, failures = [], options) {
+    super(message, options);
+    this.name = "IndexingError";
+    this.phase = phase;
+    this.failures = failures;
+  }
+}
 async function indexContent(options) {
   const {
     client,
@@ -819,32 +849,92 @@ async function indexContent(options) {
     fileExtensions = [".md", ".markdown"],
     exclude = ["node_modules", ".git", "dist", "build"],
     tableName = "articles",
-    onProgress
+    onProgress,
+    failurePolicy = "abort",
+    allowEmptyIndex = false
   } = options;
   const quotedTableName = quoteSqlIdentifier(tableName, "tableName");
-  const files = await findFiles(contentPath, contentPath, fileExtensions, exclude);
-  if (files.length === 0) {
-    console.warn(`No files found in ${contentPath}`);
-    return { success: 0, failed: 0, total: 0 };
-  }
-  await client.execute(`DELETE FROM ${quotedTableName}`);
-  let success = 0;
-  let failed = 0;
+  let files;
+  try {
+    files = await findFiles(contentPath, contentPath, fileExtensions, exclude);
+  } catch (error) {
+    throw new IndexingError(
+      `Failed to scan ${contentPath} for source files. The existing index was left unchanged.`,
+      "build",
+      [],
+      { cause: toError(error) }
+    );
+  }
+  files.sort((a, b) => a.relativePath < b.relativePath ? -1 : a.relativePath > b.relativePath ? 1 : 0);
+  if (files.length === 0 && !allowEmptyIndex) {
+    throw new IndexingError(
+      `No source files found in ${contentPath}. The existing index was left unchanged. Pass allowEmptyIndex: true to intentionally empty the index.`,
+      "build"
+    );
+  }
+  const documents = [];
+  const failures = [];
+  const slugOwners = /* @__PURE__ */ new Map();
   for (let i = 0; i < files.length; i++) {
     const file = files[i];
     if (onProgress) {
       onProgress(i + 1, files.length, file.relativePath);
     }
-    try {
-      const document = await processFile(file, embeddingOptions);
-      await insertDocument(client, document, quotedTableName);
-      success++;
-    } catch (error) {
-      console.error(`Failed to index ${file.relativePath}:`, error);
-      failed++;
+    const outcome = await buildDocument(file, embeddingOptions);
+    let failure;
+    if (outcome.ok) {
+      const owner = slugOwners.get(outcome.document.slug);
+      if (owner === void 0) {
+        slugOwners.set(outcome.document.slug, file.relativePath);
+        documents.push(outcome.document);
+      } else {
+        failure = {
+          file: file.relativePath,
+          stage: "parse",
+          error: new Error(
+            `Duplicate slug "${outcome.document.slug}": ${file.relativePath} collides with ${owner}`
+          )
+        };
+      }
+    } else {
+      failure = {
+        file: file.relativePath,
+        stage: outcome.stage,
+        error: outcome.error
+      };
+    }
+    if (failure === void 0) {
+      continue;
     }
+    if (failurePolicy === "abort") {
+      throw new IndexingError(
+        `Failed to ${failure.stage} ${file.relativePath}: ${failure.error.message}. The existing index was left unchanged. Pass failurePolicy: 'skip' to rebuild from the remaining files.`,
+        "build",
+        [failure],
+        { cause: failure.error }
+      );
+    }
+    console.error(`Skipping ${file.relativePath} (${failure.stage} failed):`, failure.error);
+    failures.push(failure);
+  }
+  if (files.length > 0 && documents.length === 0) {
+    throw new IndexingError(
+      `All ${files.length} source file(s) in ${contentPath} failed to index. The existing index was left unchanged.`,
+      "build",
+      failures,
+      { cause: failures[0].error }
+    );
   }
-  return { success, failed, total: files.length };
+  const success = documents.length;
+  await replaceIndex(client, quotedTableName, documents, failures);
+  return {
+    success,
+    failed: failures.length,
+    total: files.length,
+    replaced: true,
+    partial: failures.length > 0,
+    failures
+  };
 }
 async function findFiles(dir, baseDir, extensions, exclude) {
   const files = [];
@@ -868,34 +958,113 @@ async function findFiles(dir, baseDir, extensions, exclude) {
   }
   return files;
 }
-async function processFile(file, embeddingOptions) {
-  const content = await readFile(file.fullPath, "utf-8");
-  const { data: frontMatter, content: markdown } = matter(content);
+async function buildDocument(file, embeddingOptions) {
+  let raw;
+  try {
+    raw = await readFile(file.fullPath, "utf-8");
+  } catch (error) {
+    return { ok: false, stage: "read", error: toError(error) };
+  }
+  let parsed;
+  try {
+    parsed = parseFile(file, raw);
+  } catch (error) {
+    return { ok: false, stage: "parse", error: toError(error) };
+  }
+  let embedding;
+  try {
+    embedding = await generateEmbedding(parsed.embeddingText, {
+      ...embeddingOptions,
+      intent: embeddingOptions.intent ?? "document"
+    });
+  } catch (error) {
+    return { ok: false, stage: "embed", error: toError(error) };
+  }
+  return {
+    ok: true,
+    document: {
+      slug: parsed.slug,
+      title: parsed.title,
+      content: parsed.content,
+      folder: file.folder,
+      tags: parsed.tags,
+      serializedTags: parsed.serializedTags,
+      embedding,
+      metadata: parsed.metadata
+    }
+  };
+}
+function parseFile(file, raw) {
+  const { data: frontMatter, content: markdown } = matter(raw);
   const slug = file.relativePath.replace(/\.(md|markdown)$/, "").replace(/\\/g, "/");
-  const title = frontMatter.title || file.relativePath.split("/").pop()?.replace(/\.(md|markdown)$/, "").replace(/-/g, " ") || "Untitled";
+  const title = resolveTitle(file, frontMatter.title);
   const tags = Array.isArray(frontMatter.tags) ? frontMatter.tags : [];
+  const serializedTags = JSON.stringify(tags);
   const embeddingText = prepareTextForEmbedding({
     title,
     description: frontMatter.description,
     content: markdown,
     tags
   });
-  const embedding = await generateEmbedding(embeddingText, {
-    ...embeddingOptions,
-    intent: embeddingOptions.intent ?? "document"
-  });
   return {
     slug,
     title,
     content: markdown,
-    folder: file.folder,
     tags,
-    embedding,
+    serializedTags,
+    embeddingText,
     metadata: frontMatter
   };
 }
-async function insertDocument(client, document, quotedTableName) {
-  await client.execute({
+function resolveTitle(file, rawTitle) {
+  if (!rawTitle) {
+    return fallbackTitle(file);
+  }
+  if (typeof rawTitle === "string") {
+    return rawTitle;
+  }
+  if (typeof rawTitle === "number" || typeof rawTitle === "bigint" || typeof rawTitle === "boolean") {
+    return String(rawTitle);
+  }
+  if (rawTitle instanceof Date) {
+    return rawTitle.toISOString();
+  }
+  throw new Error(
+    `Unsupported frontmatter title of type ${describeType(rawTitle)}: expected a string`
+  );
+}
+function fallbackTitle(file) {
+  return file.relativePath.split("/").pop()?.replace(/\.(md|markdown)$/, "").replace(/-/g, " ") || "Untitled";
+}
+function describeType(value) {
+  return Array.isArray(value) ? "array" : typeof value;
+}
+async function replaceIndex(client, quotedTableName, documents, failures) {
+  const statements = [`DELETE FROM ${quotedTableName}`];
+  try {
+    for (let i = 0; i < documents.length; i++) {
+      const document = documents[i];
+      if (document !== void 0) {
+        statements.push(createInsertStatement(document, quotedTableName));
+        documents[i] = void 0;
+      }
+    }
+  } finally {
+    documents.length = 0;
+  }
+  try {
+    await client.batch(statements, "write");
+  } catch (error) {
+    throw new IndexingError(
+      `Failed to replace the contents of ${quotedTableName}. The transaction was rolled back and the existing index was left unchanged.`,
+      "replace",
+      failures,
+      { cause: toError(error) }
+    );
+  }
+}
+function createInsertStatement(document, quotedTableName) {
+  return {
     sql: `INSERT INTO ${quotedTableName}
           (slug, title, content, folder, tags, embedding, created_at, updated_at)
           VALUES (?, ?, ?, ?, ?, vector(?), datetime('now'), datetime('now'))`,
@@ -904,10 +1073,13 @@ async function insertDocument(client, document, quotedTableName) {
       document.title,
       document.content,
       document.folder,
-      JSON.stringify(document.tags),
+      document.serializedTags,
       JSON.stringify(document.embedding)
     ]
-  });
+  };
+}
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
 }
 async function createTable(client, tableName = "articles", dimensions = 384) {
   const quotedTableName = quoteSqlIdentifier(tableName, "tableName");
@@ -942,39 +1114,102 @@ async function createTable(client, tableName = "articles", dimensions = 384) {
   `);
 }
 
+const RESULT_COLUMNS = "a.id, a.slug, a.title, a.content, a.folder, a.tags, a.created_at";
+const MISSING_VECTOR_INDEX_PATTERNS = [
+  /failed to parse vector index parameters/i
+];
+const NO_VECTOR_SUPPORT_PATTERNS = [
+  /no such table:\s*vector_top_k/i
+];
 async function search(options) {
   const {
     client,
     query,
     limit = 10,
     tableName = "articles",
-    embeddingOptions = {}
+    embeddingOptions = {},
+    candidates,
+    exact = false
   } = options;
   const quotedTableName = quoteSqlIdentifier(tableName, "tableName");
   const resultLimit = normalizeSearchLimit(limit);
+  const embeddingIndexName = validateSqlIdentifier(
+    `${tableName}_embedding_idx`,
+    "embedding index name"
+  );
+  const candidateCount = normalizeSearchCandidates(candidates, resultLimit);
   const queryEmbedding = await generateEmbedding(query, {
     ...embeddingOptions,
     intent: embeddingOptions.intent ?? "query"
   });
-  const results = await client.execute({
+  const queryVector = JSON.stringify(queryEmbedding);
+  const results = exact ? await executeExactSearch(client, quotedTableName, queryVector, resultLimit) : await executeIndexSearch(
+    client,
+    quotedTableName,
+    embeddingIndexName,
+    queryVector,
+    candidateCount,
+    resultLimit
+  );
+  return results.rows.map(toSearchResult);
+}
+async function executeIndexSearch(client, quotedTableName, embeddingIndexName, queryVector, candidateCount, resultLimit) {
+  try {
+    return await client.execute({
+      sql: `
+        SELECT
+          ${RESULT_COLUMNS},
+          vector_distance_cos(a.embedding, vector(:queryVector)) as distance
+        FROM vector_top_k(:indexName, vector(:queryVector), :candidates) AS v
+        JOIN ${quotedTableName} a ON a.rowid = v.id
+        ORDER BY distance, a.id
+        LIMIT :resultLimit
+      `,
+      args: {
+        queryVector,
+        indexName: embeddingIndexName,
+        candidates: candidateCount,
+        resultLimit
+      }
+    });
+  } catch (error) {
+    throw wrapIndexPathError(error, embeddingIndexName);
+  }
+}
+async function executeExactSearch(client, quotedTableName, queryVector, resultLimit) {
+  return client.execute({
     sql: `
       SELECT
-        id,
-        slug,
-        title,
-        content,
-        folder,
-        tags,
-        created_at,
-        vector_distance_cos(embedding, vector(?)) as distance
-      FROM ${quotedTableName}
-      WHERE embedding IS NOT NULL
-      ORDER BY distance
-      LIMIT ?
+        ${RESULT_COLUMNS},
+        vector_distance_cos(a.embedding, vector(:queryVector)) as distance
+      FROM ${quotedTableName} a
+      WHERE a.embedding IS NOT NULL
+      ORDER BY distance, a.id
+      LIMIT :resultLimit
     `,
-    args: [JSON.stringify(queryEmbedding), resultLimit]
+    args: { queryVector, resultLimit }
   });
-  return results.rows.map((row) => ({
+}
+function wrapIndexPathError(error, embeddingIndexName) {
+  if (!(error instanceof Error)) {
+    return error;
+  }
+  if (MISSING_VECTOR_INDEX_PATTERNS.some((pattern) => pattern.test(error.message))) {
+    return new Error(
+      `Vector index "${embeddingIndexName}" could not be used for search. createTable() creates this index; a table created before it existed, or created by hand, will not have it. Create it with CREATE INDEX IF NOT EXISTS "${embeddingIndexName}" ON <table>(libsql_vector_idx(embedding)), or pass exact: true to search without the index.`,
+      { cause: error }
+    );
+  }
+  if (NO_VECTOR_SUPPORT_PATTERNS.some((pattern) => pattern.test(error.message))) {
+    return new Error(
+      `This libSQL deployment has no vector index support: vector_top_k() is unavailable. Pass exact: true to search on the full-scan path.`,
+      { cause: error }
+    );
+  }
+  return error;
+}
+function toSearchResult(row) {
+  return {
     id: row.id,
     slug: row.slug,
     title: row.title,
@@ -983,7 +1218,7 @@ async function search(options) {
     tags: JSON.parse(row.tags || "[]"),
     distance: row.distance,
     created_at: row.created_at
-  }));
+  };
 }
 async function getAllArticles(client, tableName = "articles") {
   const quotedTableName = quoteSqlIdentifier(tableName, "tableName");
@@ -1057,4 +1292,4 @@ async function getFolders(client, tableName = "articles") {
   return results.rows.map((row) => row.folder);
 }
 
-export { createEmbeddingProvider, createTable, generateEmbedding, generateEmbeddings, getAllArticles, getArticleBySlug, getArticlesByFolder, getEmbeddingProviderMetadata, getFolders, indexContent, padEmbedding, prepareTextForEmbedding, search, validateEmbeddingBatch };
+export { DEFAULT_SEARCH_CANDIDATE_MULTIPLIER, IndexingError, MAX_SEARCH_CANDIDATES, MIN_SEARCH_CANDIDATES, createEmbeddingProvider, createTable, generateEmbedding, generateEmbeddings, getAllArticles, getArticleBySlug, getArticlesByFolder, getEmbeddingProviderMetadata, getFolders, indexContent, padEmbedding, prepareTextForEmbedding, search, validateEmbeddingBatch };

package/docs/API.md

@@ -18,6 +18,10 @@
 - `validateEmbeddingBatch`
 - `padEmbedding`
 - `prepareTextForEmbedding`
+- `IndexingError`
+- `DEFAULT_SEARCH_CANDIDATE_MULTIPLIER`
+- `MIN_SEARCH_CANDIDATES`
+- `MAX_SEARCH_CANDIDATES`
 
 It also exports these types:
 
@@ -34,6 +38,11 @@ It also exports these types:
 - `EmbeddingOptions`
 - `IndexerOptions`
 - `IndexedDocument`
+- `IndexResult`
+- `IndexFailure`
+- `IndexFailurePolicy`
+- `IndexFailureStage`
+- `IndexingErrorPhase`
 - `SearchOptions`
 - `SearchResult`
 
@@ -86,6 +95,8 @@ interface IndexerOptions {
   exclude?: string[];
   tableName?: string;
   onProgress?: (current: number, total: number, file: string) => void;
+  failurePolicy?: "abort" | "skip";
+  allowEmptyIndex?: boolean;
 }
 ```
 
@@ -94,25 +105,80 @@ Defaults:
 - `fileExtensions`: [".md", ".markdown"]
 - `exclude`: ["node_modules", ".git", "dist", "build"]
 - `tableName`: `"articles"`
+- `failurePolicy`: `"abort"`
+- `allowEmptyIndex`: `false`
 
 Return shape:
 
 ```ts
-{
-  success: number;
-  failed: number;
-  total: number;
+interface IndexResult {
+  success: number;   // documents written
+  failed: number;    // files that could not be indexed
+  total: number;     // files discovered on disk
+  replaced: boolean; // whether table contents were replaced by this call
+  partial: boolean;  // replaced, but some files were skipped
+  failures: IndexFailure[];
+}
+
+interface IndexFailure {
+  file: string;                        // path relative to contentPath
+  stage: "read" | "parse" | "embed";
+  error: Error;
 }
 ```
 
 Behavior notes:
 
-- `indexContent()` deletes existing rows in the target table before rebuilding
-- rebuilds are not transactional
+- every file is read, parsed, and embedded in memory before any database state changes
+- the target table is then replaced in a single write transaction, so a failed rebuild leaves the previous index exactly as it was
+- that costs peak memory proportional to the whole corpus, and against remote clients the replacement travels as a single un-chunked batch request; see [Costs of the two-phase rebuild](./INDEXING.md#costs-of-the-two-phase-rebuild) before rebuilding a very large corpus in place
+- files are discovered and indexed in sorted path order
+- frontmatter `title` must be a scalar; a structured title such as a YAML list fails the file at the `parse` stage
+- two files that reduce to the same slug (`foo.md` and `foo.markdown`) collide: the first in sorted path order keeps the slug and the later file is reported as a `parse` failure
+- `failurePolicy: "abort"` throws `IndexingError` on the first file that fails
+- `failurePolicy: "skip"` drops the failing file, records it in `failures`, and rebuilds from the survivors, returning `partial: true`
+- under `"skip"`, if every discovered file fails, the rebuild throws instead of replacing a valid index with an empty one
+- an empty source directory throws unless `allowEmptyIndex: true`, which intentionally empties the index
+- `onProgress` is called once per file during the build phase
 - frontmatter `title`, `description`, and `tags` are folded into the embedding text
 - embeddings default to `intent: "document"` unless `embeddingOptions.intent` is set explicitly
 - if a file has no frontmatter title, the filename becomes the title
 
+### `IndexingError`
+
+Thrown when a rebuild cannot complete. The previously indexed rows are always left unchanged.
+
+```ts
+class IndexingError extends Error {
+  readonly phase: "build" | "replace";
+  readonly failures: IndexFailure[];
+}
+```
+
+- `phase: "build"` means the failure happened before any database work: a file failed, every file failed, the source directory was empty, or it could not be scanned
+- `phase: "replace"` means the replacement transaction failed and was rolled back
+- `cause` carries the underlying error
+- on a `phase: "replace"` error, `failures` lists files skipped during the build phase. They are not the cause of the rollback, which is carried by `cause`
+
+```ts
+import { indexContent, IndexingError } from "libsql-search";
+
+try {
+  await indexContent({ client, contentPath: "./content" });
+} catch (error) {
+  if (error instanceof IndexingError) {
+    console.error(error.phase, error.failures);
+  }
+
+  throw error;
+}
+```
+
+Breaking changes in this behavior:
+
+- partial failures previously counted into `failed` and still replaced the table; they now throw. Pass `failurePolicy: "skip"` for the previous lenient behavior.
+- an empty source directory previously returned zeros and left stale rows in place; it now throws. Pass `allowEmptyIndex: true` to intentionally empty the index.
+
 ## `search(options)`
 
 Generates a query embedding and performs vector similarity search.
@@ -124,6 +190,8 @@ interface SearchOptions {
   limit?: number;
   tableName?: string;
   embeddingOptions?: EmbeddingOptions;
+  candidates?: number;
+  exact?: boolean;
 }
 ```
 
@@ -131,9 +199,65 @@ Defaults:
 
 - `limit`: `10`
 - `tableName`: `"articles"`
+- `candidates`: `Math.max(limit * 4, 32)`
+- `exact`: `false`
 
 `limit` must be an integer from `1` through `100`; invalid values are rejected before query embedding generation.
 
+### Search Is Approximate By Default
+
+The default path queries the `<tableName>_embedding_idx` vector index through libSQL's `vector_top_k()`. **That index is an approximate-nearest-neighbor structure. It can miss a true nearest neighbor.** There is no configuration that makes the index path exact; only `exact: true` guarantees exactness.
+
+To limit the accuracy loss, the default path over-fetches: it pulls `candidates` rows from the index, recomputes the true `vector_distance_cos` for each, and orders exactly by `(distance, id)` before trimming to `limit`. So:
+
+- **Recall is approximate.** A row the index does not return as a candidate cannot appear in the results, no matter its true distance. Raising `candidates` raises recall.
+- **Ranking within the candidate set is exact.** Distances on returned rows are always the true cosine distances, not index approximations.
+- **Ordering is fully deterministic.** The `id` tiebreaker means two rows at an identical distance always come back in the same order, even though the index's own candidate order is not stable across runs.
+- **Rows with a `NULL` embedding are never returned.** The vector index excludes them on its own.
+
+**Both paths order by `(distance, id)`.** The determinism guarantee covers `exact: true` as well as the default, so the two paths return identical orderings for identical inputs and can be compared directly. This is a change in tie ordering for the exact path, which previously sorted by distance alone and left tied rows in whatever order the scan produced.
+
+### `candidates`
+
+Controls how many rows the index returns for the exact re-rank. It must be an integer from `limit` through `MAX_SEARCH_CANDIDATES`; a value below `limit` is rejected rather than clamped, because it would silently truncate the result set. Invalid values throw before query embedding generation and before any database call.
+
+```ts
+// Trade query cost for recall on a large corpus
+const results = await search({ client, query, limit: 10, candidates: 200 });
+```
+
+`candidates` has no effect when `exact` is `true` — that path scans every row — but it is **still validated**. `search({ exact: true, limit: 10, candidates: 5 })` throws, exactly as it would on the index path. Validity does not depend on which path a call happens to take.
+
+Related exported constants:
+
+- `DEFAULT_SEARCH_CANDIDATE_MULTIPLIER` (`4`): multiplier applied to `limit`
+- `MIN_SEARCH_CANDIDATES` (`32`): floor for the derived default
+- `MAX_SEARCH_CANDIDATES` (`1000`): ceiling for any explicit value. The derived default cannot reach it today, since `limit` tops out at `100`; the cap constrains explicit values.
+
+### `exact`
+
+Set `exact: true` to bypass the index and score every row in the table.
+
+```ts
+const results = await search({ client, query, exact: true });
+```
+
+This is the guaranteed-exact path: it computes `vector_distance_cos` for every row with a non-`NULL` embedding, sorts by `(distance, id)`, and trims to `limit`. Cost grows linearly with table size, so it is intended for small corpora, correctness checks against the index path, and tables that have no vector index.
+
+### Missing Vector Index
+
+If the target table has no `<tableName>_embedding_idx`, the default path throws an error naming the missing index and pointing at `createTable()` and `exact: true`. libSQL's own message for this case ("failed to parse vector index parameters") says nothing about a missing index, so it is preserved as the thrown error's `cause` rather than surfaced directly.
+
+A deployment with no vector support at all is a separate case with its own message. `vector_top_k()` does not exist there, so no `CREATE INDEX` can help and the error points only at `exact: true`.
+
+**Those two messages are the only ones rewritten.** Every other failure from the index path reaches the caller with its original message intact. In particular, a width mismatch between the query embedding and the `embedding` column surfaces as libSQL's own `vector index(search): dimensions are different: 384 != 4`, which names both widths and is the useful diagnostic for the dimension drift described in the [Migration and reindexing guide](./MIGRATIONS.md).
+
+Search never falls back to the exact scan on its own. A silent fallback would turn a one-line schema fix into an invisible, permanent full-table scan.
+
+### Requirements
+
+`vector_top_k()` and `libsql_vector_idx()` require a libSQL build with native vector support. The peer dependency is `@libsql/client ^0.15.0`; this behavior is verified against `@libsql/client` `0.15.15` with a local `:memory:` database. Remote Turso/libSQL servers must also support vector indexes — that is a property of the server, not the client, and no minimum server version is claimed here beyond that requirement. A deployment without it fails the default path with an error saying so and naming `exact: true` as the remedy. Use `exact: true` against any deployment where vector index support is unavailable or unverified.
+
 Result shape:
 
 ```ts