fix(search): enforce embedding identity

Forward the selected device to Transformers.js and record the model-device identity in each search index. Reject incompatible indexes before queries can mix embedding spaces. Replace duplicated cache tests with API-level regression coverage.

Author: harlan-zw

README.md

@@ -241,21 +241,22 @@ The large default context can exceed memory for big models on constrained hardwa
 
 ### Embedding Model
 
-`skilld search` is powered by a local embedding model. It runs offline through transformers.js — no API key, and no network traffic after the first download. Pick one under **Embedding model** in `skilld config`:
+`skilld search` uses a local embedding model. It runs offline through transformers.js. It needs no API key or network after the first download. Pick one under **Embedding model** in `skilld config`:
 
 | Model | Dimensions | Notes |
 |-------|-----------:|-------|
 | `bge-small-en-v1.5` | 384 | Default. Fastest to index, smallest download. |
 | `bge-base-en-v1.5` | 768 | Balanced accuracy and speed. |
 | `bge-m3` | 1024 | Multilingual, 8192-token context. |
 
-Larger models retrieve more accurately but cost more time and memory when indexing. Set `SKILLD_EMBED_MODEL` to override the saved setting for a single run:
+Larger models retrieve more accurately but cost more time and memory when indexing. Set `SKILLD_EMBED_MODEL` to override the saved setting:
 
 ```bash
-SKILLD_EMBED_MODEL=bge-m3 skilld add npm:vue
+export SKILLD_EMBED_MODEL=bge-m3
+skilld update --force
 ```
 
-Search indexes store fixed-width vectors, so changing to a model with different dimensions strands existing indexes. Rebuild them after switching:
+Each search index belongs to one model and device. Keep environment overrides set for both indexing and querying. Rebuild indexes after either setting changes:
 
 ```bash
 skilld update --force
@@ -267,7 +268,7 @@ The embedding model runs on the CPU by default. **Embedding device** in `skilld
 
 | Device | Notes |
 |--------|-------|
-| `auto` | Default. Lets transformers.js choose — CPU under Node. |
+| `auto` | Default. Lets transformers.js choose, CPU under Node. |
 | `cpu` | Always available, predictable. |
 | `webgpu` | Fastest on Apple Silicon in testing. |
 | `coreml` | Apple Neural Engine. Measured slower than CPU for these models. |
@@ -280,15 +281,16 @@ Measured on an Apple M5 Max, 120 documents, best of 3 after warm-up (docs/sec):
 | `bge-base-en-v1.5` | 198 | 68 | **580** |
 | `Xenova/bge-large-en-v1.5` | 71 | 9 | **201** |
 
-WebGPU was 2.6-2.9x faster than CPU at every size, which means `bge-large` on WebGPU indexes faster than `bge-base` does on CPU — better retrieval for less wall-clock. CoreML was consistently slower.
+WebGPU was 2.6 to 2.9 times faster than CPU at every size. `bge-large` on WebGPU indexed faster than `bge-base` on CPU. CoreML was consistently slower.
 
-The ranking is hardware-specific, so benchmark before trusting a device on other machines. Override for a single run with `SKILLD_EMBED_DEVICE`:
+The ranking is hardware-specific, so benchmark before trusting a device on other machines. Set `SKILLD_EMBED_DEVICE` to override the saved setting:
 
 ```bash
-SKILLD_EMBED_DEVICE=cpu skilld update --force
+export SKILLD_EMBED_DEVICE=cpu
+skilld update --force
 ```
 
-If a backend is unavailable, indexing fails to start — switch back to `auto`.
+If a backend is unavailable, indexing fails to start. Switch back to `auto`.
 
 ### Eject
 

src/commands/config.ts

@@ -11,7 +11,7 @@ import { guard, menuLoop } from '../cli/menu.ts'
 import { NO_MODELS_MESSAGE, OAUTH_NOTE, pickModel } from '../cli/model-picker.ts'
 import { defaultFeatures, readConfig, updateConfig } from '../core/config.ts'
 import { getProjectState } from '../core/skills.ts'
-import { DEFAULT_EMBED_DEVICE, DEFAULT_EMBED_MODEL, EMBED_DEVICES, EMBED_MODELS, getEmbedModelInfo, resolveEmbedModel } from '../retriv/models.ts'
+import { DEFAULT_EMBED_DEVICE, DEFAULT_EMBED_MODEL, EMBED_DEVICES, EMBED_MODELS, resolveEmbedModel } from '../retriv/models.ts'
 
 export async function configCommand(): Promise<void> {
   const initConfig = readConfig()
@@ -248,7 +248,7 @@ async function configureModel(): Promise<void> {
   }
 }
 
-// ── Embedding model selection ────────────────────────────────────────
+// Embedding model selection
 
 async function configureEmbedModel(): Promise<void> {
   const config = readConfig()
@@ -260,7 +260,7 @@ async function configureEmbedModel(): Promise<void> {
   }
 
   const choice = guard(await p.select({
-    message: 'Embedding model — indexes and queries docs for skilld search',
+    message: 'Embedding model for indexing and querying skilld search',
     options: EMBED_MODELS.map(m => ({
       label: m.label,
       value: m.id,
@@ -274,22 +274,12 @@ async function configureEmbedModel(): Promise<void> {
     return
   }
 
-  const previous = getEmbedModelInfo(current)
-  const next = getEmbedModelInfo(choice as string)
   updateConfig({ embedModel: choice === DEFAULT_EMBED_MODEL ? undefined : choice as string })
   p.log.success(`Embedding model set to ${choice}`)
-
-  // sqlite-vec columns are fixed-width, so a dimension change strands existing
-  // indexes: they stay queryable at the old width but new docs cannot join them.
-  if (previous && next && previous.dimensions !== next.dimensions) {
-    p.log.warn(
-      `Vector width changed ${previous.dimensions}d → ${next.dimensions}d. `
-      + 'Existing search indexes must be rebuilt: skilld update --force',
-    )
-  }
+  p.log.warn('Embedding model changed. Rebuild existing search indexes: skilld update --force')
 }
 
-// ── Embedding device selection ───────────────────────────────────────
+// Embedding device selection
 
 async function configureEmbedDevice(): Promise<void> {
   const config = readConfig()
@@ -301,23 +291,28 @@ async function configureEmbedDevice(): Promise<void> {
 
   p.note(
     'The fastest backend depends on your hardware. On an Apple M5 Max, WebGPU\n'
-    + 'ran 2.6-2.9x faster than CPU across every model size, while CoreML ran\n'
-    + '3-8x slower. Benchmark before trusting a device on other machines.',
+    + 'ran 2.6 to 2.9 times faster than CPU. CoreML ran 3 to 8 times slower.\n'
+    + 'Benchmark before trusting a device on other machines.',
     'Choosing a device',
   )
 
   const choice = guard(await p.select({
-    message: 'Embedding device — where the model runs',
+    message: 'Embedding device where the model runs',
     options: EMBED_DEVICES.map(d => ({ label: d.label, value: d.id, hint: d.hint })),
     initialValue: current,
   }))
 
+  if (choice === current) {
+    p.log.info(`Embedding device unchanged (${choice})`)
+    return
+  }
+
   updateConfig({ embedDevice: choice === DEFAULT_EMBED_DEVICE ? undefined : choice as string })
   p.log.success(`Embedding device set to ${choice}`)
+  p.log.warn('Embedding device changed. Rebuild existing search indexes: skilld update --force')
 
-  if (choice !== DEFAULT_EMBED_DEVICE && choice !== 'cpu') {
-    p.log.info('If indexing fails to start, the backend is unavailable on this machine — switch back to Auto.')
-  }
+  if (choice !== DEFAULT_EMBED_DEVICE && choice !== 'cpu')
+    p.log.info('If indexing fails to start, switch back to Auto. The backend may be unavailable on this machine.')
 }
 
 export const configCommandDef = defineCommand({

src/retriv/embedding-cache.ts

@@ -55,7 +55,7 @@ function createSqliteStorage(db: DatabaseSync) {
  *
  * `model` identifies which embedder produced the cached vectors. Entries are
  * keyed by text hash alone, so vectors from a different model would be served
- * for the same text — two models of equal width (bge-large and
+ * for the same text. Two models of equal width (bge-large and
  * qwen3-embedding:0.6b are both 1024d) would silently mix embedding spaces and
  * destroy ranking. Dimensions alone cannot catch that; the model id can.
  */

src/retriv/index-embedding-identity.ts

@@ -0,0 +1,57 @@
+import { DatabaseSync } from 'node:sqlite'
+import { existsSync } from 'node:fs'
+import { DEFAULT_EMBEDDING_IDENTITY } from './models.ts'
+
+const META_TABLE = 'skilld_meta'
+const IDENTITY_KEY = 'embedding_identity'
+
+export type IndexEmbeddingIdentityState
+  = | { _tag: 'Current' }
+    | { _tag: 'Missing' }
+    | { _tag: 'Mismatch', current: string, stored: string }
+
+function tableExists(db: DatabaseSync, name: string): boolean {
+  return db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name) !== undefined
+}
+
+function hasIndexedDocuments(db: DatabaseSync): boolean {
+  if (!tableExists(db, 'documents_meta'))
+    return false
+  const row = db.prepare('SELECT EXISTS(SELECT 1 FROM documents_meta) AS found').get() as { found: number }
+  return row.found === 1
+}
+
+export function checkIndexEmbeddingIdentity(dbPath: string, current: string): IndexEmbeddingIdentityState {
+  if (dbPath === ':memory:' || !existsSync(dbPath))
+    return { _tag: 'Missing' }
+
+  const db = new DatabaseSync(dbPath, { open: true, readOnly: true })
+  try {
+    const row = tableExists(db, META_TABLE)
+      ? db.prepare(`SELECT value FROM ${META_TABLE} WHERE key = ?`).get(IDENTITY_KEY) as { value: string } | undefined
+      : undefined
+    const stored = row?.value ?? (hasIndexedDocuments(db) ? DEFAULT_EMBEDDING_IDENTITY : undefined)
+
+    if (!stored)
+      return { _tag: 'Missing' }
+    if (stored !== current)
+      return { _tag: 'Mismatch', current, stored }
+    return { _tag: 'Current' }
+  }
+  finally {
+    db.close()
+  }
+}
+
+export function recordIndexEmbeddingIdentity(dbPath: string, identity: string): void {
+  if (dbPath === ':memory:')
+    return
+  const db = new DatabaseSync(dbPath)
+  try {
+    db.exec(`CREATE TABLE IF NOT EXISTS ${META_TABLE} (key TEXT PRIMARY KEY, value TEXT NOT NULL)`)
+    db.prepare(`INSERT OR REPLACE INTO ${META_TABLE} (key, value) VALUES (?, ?)`).run(IDENTITY_KEY, identity)
+  }
+  finally {
+    db.close()
+  }
+}

src/retriv/index.ts

@@ -1,7 +1,9 @@
 import type { ChunkEntity, Document, IndexConfig, IndexPhase, IndexProgress, SearchFilter, SearchOptions, SearchResult, SearchSnippet } from './types.ts'
 import { readConfig } from '../core/config.ts'
 import { stripFrontmatter } from '../core/markdown.ts'
-import { resolveEmbedDevice, resolveEmbedModel } from './models.ts'
+import { checkIndexEmbeddingIdentity, recordIndexEmbeddingIdentity } from './index-embedding-identity.ts'
+import { getEmbeddingIdentity, resolveEmbedDevice, resolveEmbedModel } from './models.ts'
+import { transformersEmbeddings } from './transformers-embeddings.ts'
 
 export type { ChunkEntity, Document, IndexConfig, IndexPhase, IndexProgress, SearchFilter, SearchOptions, SearchResult, SearchSnippet }
 
@@ -15,6 +17,14 @@ export class SearchDepsUnavailableError extends Error {
   }
 }
 
+export class EmbeddingIndexMismatchError extends Error {
+  constructor(dbPath: string, stored: string, current: string) {
+    super(`Search index uses ${stored}, but embedding settings resolve to ${current}. Rebuild indexes with: skilld update --force`)
+    this.name = 'EmbeddingIndexMismatchError'
+    this.cause = { dbPath, stored, current }
+  }
+}
+
 let _fts5Available: boolean | null = null
 
 /**
@@ -49,21 +59,27 @@ export async function getDb(config: Pick<IndexConfig, 'dbPath'>) {
   if (!checkFts5())
     throw new SearchDepsUnavailableError(new Error('FTS5 module not available'), 'SQLite FTS5 module not available. Search indexing skipped. On Windows, run from WSL where FTS5 is included.')
 
-  let createRetriv, autoChunker, sqliteMod, sqliteVec, transformersJs, cachedEmbeddings
+  const userConfig = readConfig()
+  const embedModel = resolveEmbedModel(userConfig.embedModel)
+  const device = resolveEmbedDevice(userConfig.embedDevice)
+  const embeddingIdentity = getEmbeddingIdentity(embedModel, device)
+  const identityState = checkIndexEmbeddingIdentity(config.dbPath, embeddingIdentity)
+  if (identityState._tag === 'Mismatch')
+    throw new EmbeddingIndexMismatchError(config.dbPath, identityState.stored, identityState.current)
+
+  let createRetriv, autoChunker, sqliteMod, sqliteVec, cachedEmbeddings
   try {
     ;([
       { createRetriv },
       { autoChunker },
       sqliteMod,
       sqliteVec,
-      { transformersJs },
       { cachedEmbeddings },
     ] = await Promise.all([
       import('retriv'),
       import('retriv/chunkers/auto'),
       import('retriv/db/sqlite'),
       import('sqlite-vec'),
-      import('retriv/embeddings/transformers-js'),
       import('./embedding-cache.ts'),
     ]))
   }
@@ -72,27 +88,29 @@ export async function getDb(config: Pick<IndexConfig, 'dbPath'>) {
       throw new SearchDepsUnavailableError(err)
     throw err
   }
-  const userConfig = readConfig()
-  const embedModel = resolveEmbedModel(userConfig.embedModel)
-  const device = resolveEmbedDevice(userConfig.embedDevice)
-  // Cache identity pairs model with device: cached vectors are only valid for
-  // the embedder that produced them, and backends can differ numerically.
   const embeddings = await cachedEmbeddings(
-    transformersJs({
+    transformersEmbeddings({
       model: embedModel,
-      // Omitted when `auto` so transformers.js keeps its own device resolution.
       ...(device ? { device } : {}),
     }),
-    `${embedModel}@${device ?? 'auto'}`,
+    embeddingIdentity,
   )
-  return createRetriv({
+  const db = await createRetriv({
     driver: sqliteMod.default({
       path: config.dbPath,
       embeddings,
       sqliteVec,
     }),
     chunking: autoChunker(),
   })
+  try {
+    recordIndexEmbeddingIdentity(config.dbPath, embeddingIdentity)
+  }
+  catch (error) {
+    await db.close?.()
+    throw error
+  }
+  return db
 }
 
 /**