@monoes/monograph 1.2.0 → 1.2.1

package/src/pipeline/phases/reachability.ts

@@ -73,17 +73,30 @@ export function classifyReachability(
     }
   }
 
-  // ── BFS from entry points — forward direction (walk what files import) ───────
+  // ── Preload forward adjacency map for BFS (one query vs N per BFS node) ────────
+  const forwardEdges = new Map<string, string[]>();
+  const fwdRows = db.prepare(
+    `SELECT source_id, target_id FROM edges WHERE relation IN ('IMPORTS', 'RE_EXPORTS')`,
+  ).all() as { source_id: string; target_id: string }[];
+  for (const row of fwdRows) {
+    let targets = forwardEdges.get(row.source_id);
+    if (!targets) {
+      targets = [];
+      forwardEdges.set(row.source_id, targets);
+    }
+    targets.push(row.target_id);
+  }
+
+  // ── BFS from entry points — uses preloaded adjacency (no per-node DB query) ──
   const bfs = (startIds: Set<string>, role: ReachabilityRole) => {
     const queue = Array.from(startIds);
     const visited = new Set(startIds);
     while (queue.length > 0) {
       const nodeId = queue.shift()!;
-      // Follow forward edges: find files that this file imports
-      const imported = db.prepare(
-        `SELECT DISTINCT target_id FROM edges WHERE source_id = ? AND relation IN ('IMPORTS', 'RE_EXPORTS')`,
-      ).all(nodeId) as { target_id: string }[];
-      for (const { target_id } of imported) {
+      // O(1) adjacency lookup instead of per-node DB query
+      const targets = forwardEdges.get(nodeId);
+      if (!targets) continue;
+      for (const target_id of targets) {
         if (!visited.has(target_id)) {
           visited.add(target_id);
           // Set role only if not already set to a higher-priority role
@@ -102,24 +115,26 @@ export function classifyReachability(
   bfs(testEntryIds, 'test');
   bfs(runtimeEntryIds, 'runtime');
 
-  // ── Persist roles and count ───────────────────────────────────────────────────
-  let runtime = 0, test = 0, support = 0, unreachable = 0;
-  for (const node of allFileNodes) {
-    const role = roleMap.get(node.id) ?? 'unreachable';
-    let props: Record<string, unknown> = {};
-    try {
-      if (node.properties) props = JSON.parse(node.properties);
-    } catch { /* ignore parse errors */ }
-    props.reachabilityRole = role;
-    db.prepare(`UPDATE nodes SET properties = ? WHERE id = ?`)
-      .run(JSON.stringify(props), node.id);
-    if (role === 'runtime') runtime++;
-    else if (role === 'test') test++;
-    else if (role === 'support') support++;
-    else unreachable++;
-  }
-
-  return { runtime, test, support, unreachable };
+  // ── Persist roles and count — batch UPDATE in transaction ────────────────────
+  const updateStmt = db.prepare(`UPDATE nodes SET properties = ? WHERE id = ?`);
+  const persistAll = db.transaction(() => {
+    let runtime = 0, test = 0, support = 0, unreachable = 0;
+    for (const node of allFileNodes) {
+      const role = roleMap.get(node.id) ?? 'unreachable';
+      let props: Record<string, unknown> = {};
+      try {
+        if (node.properties) props = JSON.parse(node.properties);
+      } catch { /* ignore parse errors */ }
+      props.reachabilityRole = role;
+      updateStmt.run(JSON.stringify(props), node.id);
+      if (role === 'runtime') runtime++;
+      else if (role === 'test') test++;
+      else if (role === 'support') support++;
+      else unreachable++;
+    }
+    return { runtime, test, support, unreachable };
+  });
+  return persistAll();
 }
 
 /**

package/src/pipeline/phases/routes.ts

@@ -46,6 +46,23 @@ export const routesPhase: PipelinePhase<RoutesOutput> = {
     const routeNodes: MonographNode[] = [];
     const handlesEdges: MonographEdge[] = [];
 
+    // ── Preload handler index: name:filePath → nodeId (one DB query vs N per route) ──
+    // Keyed as `${name}\0${filePath}` for O(1) lookup during route extraction.
+    const handlerIndex = new Map<string, string>();
+    if (ctx.db) {
+      const handlerRows = ctx.db
+        .prepare(`SELECT id, name, file_path FROM nodes WHERE file_path IS NOT NULL`)
+        .all() as { id: string; name: string; file_path: string }[];
+      for (const row of handlerRows) {
+        handlerIndex.set(`${row.name}\0${row.file_path}`, row.id);
+      }
+    }
+
+    /** O(1) handler lookup using the preloaded index */
+    function lookupHandler(handlerName: string, filePath: string): string | undefined {
+      return handlerIndex.get(`${handlerName}\0${filePath}`);
+    }
+
     for (const fileNode of fileNodes) {
       const relPath = fileNode.filePath ?? '';
       const ext = extname(relPath).toLowerCase();
@@ -84,20 +101,18 @@ export const routesPhase: PipelinePhase<RoutesOutput> = {
           if (source) {
             const handlerName = extractDefaultExportName(source);
             if (handlerName) {
-              const row = ctx.db
-                .prepare(`SELECT id FROM nodes WHERE name = ? AND file_path = ?`)
-                .get(handlerName, relPath) as { id: string } | undefined;
-              if (row) {
-                const edgeId = makeId(routeNodeId, row.id, 'handles_route');
+              const targetId = lookupHandler(handlerName, relPath);
+              if (targetId) {
+                const edgeId = makeId(routeNodeId, targetId, 'handles_route');
                 handlesEdges.push({
                   id: edgeId,
                   sourceId: routeNodeId,
-                  targetId: row.id,
+                  targetId,
                   relation: 'HANDLES_ROUTE',
                   confidence: 'EXTRACTED',
                   confidenceScore: 0.9,
                 });
-                entry.handlerNodeId = row.id;
+                entry.handlerNodeId = targetId;
               }
             }
           }
@@ -131,20 +146,18 @@ export const routesPhase: PipelinePhase<RoutesOutput> = {
         const entry: RouteEntry = { method: e.method, path: e.path, filePath: relPath, routeNodeId, middlewareChain: [] };
 
         if (ctx.db && e.handlerName) {
-          const row = ctx.db
-            .prepare(`SELECT id FROM nodes WHERE name = ? AND file_path = ?`)
-            .get(e.handlerName, relPath) as { id: string } | undefined;
-          if (row) {
-            const edgeId = makeId(routeNodeId, row.id, 'handles_route');
+          const targetId = lookupHandler(e.handlerName, relPath);
+          if (targetId) {
+            const edgeId = makeId(routeNodeId, targetId, 'handles_route');
             handlesEdges.push({
               id: edgeId,
               sourceId: routeNodeId,
-              targetId: row.id,
+              targetId,
               relation: 'HANDLES_ROUTE',
               confidence: 'EXTRACTED',
               confidenceScore: 0.9,
             });
-            entry.handlerNodeId = row.id;
+            entry.handlerNodeId = targetId;
           }
         }
 
@@ -172,20 +185,18 @@ export const routesPhase: PipelinePhase<RoutesOutput> = {
         const entry: RouteEntry = { method: e.method, path: e.path, filePath: relPath, routeNodeId, middlewareChain: [] };
 
         if (ctx.db && e.handlerName) {
-          const row = ctx.db
-            .prepare(`SELECT id FROM nodes WHERE name = ? AND file_path = ?`)
-            .get(e.handlerName, relPath) as { id: string } | undefined;
-          if (row) {
-            const edgeId = makeId(routeNodeId, row.id, 'handles_route');
+          const targetId = lookupHandler(e.handlerName, relPath);
+          if (targetId) {
+            const edgeId = makeId(routeNodeId, targetId, 'handles_route');
             handlesEdges.push({
               id: edgeId,
               sourceId: routeNodeId,
-              targetId: row.id,
+              targetId,
               relation: 'HANDLES_ROUTE',
               confidence: 'EXTRACTED',
               confidenceScore: 0.9,
             });
-            entry.handlerNodeId = row.id;
+            entry.handlerNodeId = targetId;
           }
         }
 

package/src/pipeline/phases/scope-resolution.ts

@@ -210,68 +210,119 @@ function extractCallSites(
   return sites;
 }
 
-// ── Stage 3: Build import map from DB ─────────────────────────────────────────
+// ── Stage 3: Build import maps from DB (batch) ────────────────────────────────
 
-/** Returns a map of imported name → source file path for a given file node */
-function buildImportMap(
+/**
+ * Load all IMPORTS edges once and return a map of fileNodeId → (name → filePath).
+ * Eliminates the N+1 pattern of querying per-file inside the main loop.
+ */
+function buildAllImportMaps(
   ctx: PipelineContext,
-  fileNodeId: string,
   symbolNodes: MonographNode[],
-): Map<string, string> {
-  const importMap = new Map<string, string>();
-
-  if (!ctx.db) return importMap;
+): Map<string, Map<string, string>> {
+  const result = new Map<string, Map<string, string>>();
+  if (!ctx.db) return result;
+
+  // Build a lookup: fileNodeId → filePath from symbolNodes
+  const idToFilePath = new Map<string, string>();
+  for (const n of symbolNodes) {
+    if (n.label === 'File' && n.filePath) {
+      idToFilePath.set(n.id, n.filePath);
+      // Also register the alternate makeId form
+      const altId = makeId(n.filePath.replace(/\//g, '_'), 'file');
+      if (altId !== n.id) idToFilePath.set(altId, n.filePath);
+    }
+  }
 
-  // Get IMPORTS edges for this file to find which modules it imports
+  // Load ALL IMPORTS edges in one query
   const importsRows = ctx.db
-    .prepare(`SELECT target_id FROM edges WHERE source_id = ? AND relation = 'IMPORTS'`)
-    .all(fileNodeId) as { target_id: string }[];
+    .prepare(`SELECT source_id, target_id FROM edges WHERE relation = 'IMPORTS'`)
+    .all() as { source_id: string; target_id: string }[];
 
   for (const row of importsRows) {
-    const targetId = row.target_id;
-    // Find a File node that matches the resolved target
-    const fileNode = symbolNodes.find(
-      n => n.label === 'File' && (
-        n.id === targetId ||
-        makeId(n.filePath?.replace(/\//g, '_') ?? '', 'file') === targetId
-      ),
-    );
-    if (fileNode?.filePath) {
-      // Extract the module name from the last path segment without extension
-      const parts = fileNode.filePath.split('/');
-      const baseName = parts[parts.length - 1].replace(/\.\w+$/, '');
-      importMap.set(baseName, fileNode.filePath);
-      importMap.set(fileNode.filePath, fileNode.filePath);
+    const targetPath = idToFilePath.get(row.target_id);
+    if (!targetPath) continue;
+    let fileMap = result.get(row.source_id);
+    if (!fileMap) {
+      fileMap = new Map();
+      result.set(row.source_id, fileMap);
     }
+    const parts = targetPath.split('/');
+    const baseName = parts[parts.length - 1].replace(/\.\w+$/, '');
+    fileMap.set(baseName, targetPath);
+    fileMap.set(targetPath, targetPath);
   }
 
-  return importMap;
+  return result;
 }
 
-// ── Stage 4 + 5: Resolve target node ─────────────────────────────────────────
+/** Returns the pre-built import map for a given file node (empty map if not found). */
+function getImportMap(
+  allImportMaps: Map<string, Map<string, string>>,
+  fileNodeId: string,
+): Map<string, string> {
+  return allImportMaps.get(fileNodeId) ?? new Map();
+}
+
+// ── Stage 4 helpers: preloaded function/method index ──────────────────────────
+
+/**
+ * Load all Function/Method/Constructor nodes once.
+ * Returns two indices:
+ * - byFilePath: filePath → name → id[] (for resolveTarget candidate lookup)
+ * - nameCounts: name → total occurrences across all files (for ambiguity check)
+ */
+function buildFunctionIndex(ctx: PipelineContext): {
+  byFilePath: Map<string, Map<string, string[]>>;
+  nameCounts: Map<string, number>;
+} {
+  const byFilePath = new Map<string, Map<string, string[]>>();
+  const nameCounts = new Map<string, number>();
+
+  if (!ctx.db) return { byFilePath, nameCounts };
+
+  const rows = ctx.db
+    .prepare(`SELECT id, name, file_path FROM nodes WHERE label IN ('Function', 'Method', 'Constructor') AND file_path IS NOT NULL`)
+    .all() as { id: string; name: string; file_path: string }[];
+
+  for (const row of rows) {
+    // byFilePath index
+    let fileMap = byFilePath.get(row.file_path);
+    if (!fileMap) {
+      fileMap = new Map();
+      byFilePath.set(row.file_path, fileMap);
+    }
+    let ids = fileMap.get(row.name);
+    if (!ids) {
+      ids = [];
+      fileMap.set(row.name, ids);
+    }
+    ids.push(row.id);
+
+    // global count for ambiguity detection
+    nameCounts.set(row.name, (nameCounts.get(row.name) ?? 0) + 1);
+  }
+
+  return { byFilePath, nameCounts };
+}
+
+// ── Stage 4 + 5: Resolve target node (index-based, no per-call DB query) ──────
 
 function resolveTarget(
-  ctx: PipelineContext,
   site: CallSite,
   callerFilePath: string,
   importMap: Map<string, string>,
+  fnIndex: Map<string, Map<string, string[]>>,
 ): { targetId: string } | null {
-  if (!ctx.db) return null;
-
   const methodName = site.methodName;
   if (!methodName) return null;
 
-  let candidateFilePaths: string[] = [];
+  let candidateFilePaths: string[];
 
   if (site.form === 'method' && site.receiverName) {
     // Stage 3: Infer receiver type — look up receiver in import map
     const receiverPath = importMap.get(site.receiverName);
-    if (receiverPath) {
-      candidateFilePaths = [receiverPath];
-    } else {
-      // Receiver not imported — look in same file only
-      candidateFilePaths = [callerFilePath];
-    }
+    candidateFilePaths = receiverPath ? [receiverPath] : [callerFilePath];
   } else if (site.form === 'direct') {
     // Direct call: same file first, then all imported files
     candidateFilePaths = [callerFilePath, ...importMap.values()];
@@ -279,22 +330,13 @@ function resolveTarget(
     return null;
   }
 
-  // Stage 5: Query nodes table for matching function/method/constructor
+  // Stage 5: O(1) lookup in preloaded index instead of per-call DB query
   for (const fp of candidateFilePaths) {
-    const rows = ctx.db
-      .prepare(`
-        SELECT id FROM nodes
-        WHERE name = ?
-          AND label IN ('Function', 'Method', 'Constructor')
-          AND file_path = ?
-        LIMIT 2
-      `)
-      .all(methodName, fp) as { id: string }[];
-
-    if (rows.length === 1) {
-      return { targetId: rows[0].id };
+    const ids = fnIndex.get(fp)?.get(methodName);
+    if (ids && ids.length === 1) {
+      return { targetId: ids[0] };
     }
-    // If > 1 match, it's ambiguous — skip this candidate file
+    // ids.length > 1 → ambiguous within this file — skip to next candidate
   }
 
   return null;
@@ -361,6 +403,8 @@ export const scopeResolutionPhase: PipelinePhase<ScopeResolutionOutput> = {
     let skippedDynamic = 0;
     let ambiguous = 0;
 
+    // ── Batch preload: one query per table instead of one per file/call-site ──
+
     // Build a map from file_path → file node id using the parse output
     const fileNodesByPath = new Map<string, MonographNode>();
     for (const node of symbolNodes) {
@@ -388,6 +432,12 @@ export const scopeResolutionPhase: PipelinePhase<ScopeResolutionOutput> = {
       }
     }
 
+    // Preload all IMPORTS edges → per-file import maps (one DB query total)
+    const allImportMaps = buildAllImportMaps(ctx, symbolNodes);
+
+    // Preload all Function/Method/Constructor nodes into indices (one DB query total)
+    const { byFilePath: fnIndex, nameCounts } = buildFunctionIndex(ctx);
+
     for (const [filePath, fileNode] of fileNodesByPath) {
       const ext = extname(filePath).toLowerCase();
       if (!isSupportedExt(ext)) continue;
@@ -403,8 +453,8 @@ export const scopeResolutionPhase: PipelinePhase<ScopeResolutionOutput> = {
       // Stage 1+2: Extract call sites
       const callSites = extractCallSites(source, filePath, fileNode.id, ext);
 
-      // Stage 3: Build import map for this file
-      const importMap = buildImportMap(ctx, fileNode.id, symbolNodes);
+      // Stage 3: Get pre-built import map for this file (O(1))
+      const importMap = getImportMap(allImportMaps, fileNode.id);
 
       for (const site of callSites) {
         if (site.form === 'dynamic') {
@@ -412,29 +462,18 @@ export const scopeResolutionPhase: PipelinePhase<ScopeResolutionOutput> = {
           continue;
         }
 
-        // Stage 4+5: Resolve target
-        const resolved = resolveTarget(ctx, site, filePath, importMap);
+        // Stage 4+5: Resolve target using preloaded indices (no DB query)
+        const resolved = resolveTarget(site, filePath, importMap, fnIndex);
 
         if (!resolved) {
-          // Could not resolve — treat as ambiguous if we had candidates
-          // (method calls with unresolvable receivers are simply skipped)
+          // Could not resolve — method calls with unresolvable receivers are simply skipped
           continue;
         }
 
-        // Check if the resolved target is actually in multiple places (ambiguity check)
-        if (ctx.db && site.methodName) {
-          const totalMatches = ctx.db
-            .prepare(`
-              SELECT COUNT(*) as cnt FROM nodes
-              WHERE name = ?
-                AND label IN ('Function', 'Method', 'Constructor')
-            `)
-            .get(site.methodName) as { cnt: number };
-          if (totalMatches.cnt > 1) {
-            ambiguous++;
-            // Still emit if we found exactly one in the candidate file — this is per-file ambiguity
-            // The resolve already picked one candidate, so proceed
-          }
+        // Ambiguity check using preloaded name counts (no DB query)
+        if (site.methodName && (nameCounts.get(site.methodName) ?? 0) > 1) {
+          ambiguous++;
+          // Still emit — we found exactly one candidate in the caller's context
         }
 
         // Stage 6: Emit edge (source is the file node of the caller)

package/src/pipeline/runner.ts

@@ -3,36 +3,48 @@ import { MonographError } from '../types.js';
 
 export class PipelineRunner {
   private readonly phases: PipelinePhase<unknown>[];
+  /** Topo-sorted phase names, computed once in constructor for O(1) phase map lookups. */
+  private readonly sortedNames: string[];
+  /** O(1) phase lookup by name. */
+  private readonly phaseMap: Map<string, PipelinePhase<unknown>>;
 
   constructor(phases: PipelinePhase<unknown>[]) {
     this.phases = phases;
-    // Validate: detect cycles and unknown deps
-    topoSort(phases);
+    this.sortedNames = topoSort(phases);
+    this.phaseMap = new Map(phases.map(p => [p.name, p]));
   }
 
   async run(ctx: PipelineContext): Promise<Map<string, unknown>> {
     const outputs = new Map<string, unknown>();
-    const phaseMap = new Map(this.phases.map(p => [p.name, p]));
 
     // Lazily-created promise per phase — ensures dep promises exist before they are awaited
     const promises = new Map<string, Promise<void>>();
 
     const getOrCreatePromise = (name: string): Promise<void> => {
       if (promises.has(name)) return promises.get(name)!;
-      const phase = phaseMap.get(name)!;
+      const phase = this.phaseMap.get(name)!;
       const p = (async () => {
         // Wait for all dep phases to finish
         await Promise.all(phase.deps.map(dep => getOrCreatePromise(dep)));
         ctx.onProgress?.({ phase: phase.name });
-        const output = await phase.execute(ctx, outputs);
-        outputs.set(phase.name, output);
+        try {
+          const output = await phase.execute(ctx, outputs);
+          outputs.set(phase.name, output);
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          throw new MonographError(`Phase '${phase.name}' failed: ${msg}`);
+        }
       })();
       promises.set(name, p);
       return p;
     };
 
-    // Kick off all phases — each self-manages its dep wait via lazy promise creation
-    await Promise.all(this.phases.map(phase => getOrCreatePromise(phase.name)));
+    // Use allSettled so every in-flight phase completes before we return.
+    // This ensures the DB is not closed while phases are still writing to it,
+    // which would otherwise cause unhandled rejections that hang the process.
+    const results = await Promise.allSettled(this.sortedNames.map(name => getOrCreatePromise(name)));
+    const failed = results.find(r => r.status === 'rejected') as PromiseRejectedResult | undefined;
+    if (failed) throw failed.reason;
     return outputs;
   }
 }
@@ -94,14 +106,19 @@ export async function runIncrementalAst(
   if (preserveInferred) {
     if (changedFiles.length > 0) {
       const placeholders = changedFiles.map(() => '?').join(',');
+      // Use a CTE to resolve file_path→id once, then delete edges referencing those ids.
+      // This avoids passing changedFiles twice (N*2 params) and lets SQLite reuse the scan.
       db.prepare(`
+        WITH changed_ids AS (
+          SELECT id FROM nodes WHERE file_path IN (${placeholders})
+        )
         DELETE FROM edges
         WHERE confidence = 'EXTRACTED'
         AND (
-          source_id IN (SELECT id FROM nodes WHERE file_path IN (${placeholders}))
-          OR target_id IN (SELECT id FROM nodes WHERE file_path IN (${placeholders}))
+          source_id IN (SELECT id FROM changed_ids)
+          OR target_id IN (SELECT id FROM changed_ids)
         )
-      `).run(...changedFiles, ...changedFiles);
+      `).run(...changedFiles);
     } else {
       db.prepare(`DELETE FROM edges WHERE confidence = 'EXTRACTED'`).run();
     }

package/src/query/cypher-parser.ts

@@ -365,3 +365,86 @@ export function executeCypherQuery(db: Database.Database, query: string): Cypher
     };
   }
 }
+
+// ── Structured text formatter ──────────────────────────────────────────────────
+
+/**
+ * Format a CypherResult as structured text for LLM consumption.
+ *
+ * Rows that contain *_filePath and *_startLine fields are rendered with
+ * "file:line" navigation hints so LLMs can jump directly to the symbol.
+ * Plain key=value pairs are rendered for all other fields.
+ *
+ * @example
+ * ```
+ * monograph_cypher result (3 rows, 2ms)
+ *
+ * Row 1:
+ *   n.name = buildAsync
+ *   n.filePath = src/server.ts:42
+ *
+ * Row 2:
+ *   ...
+ * ```
+ */
+export function formatCypherResult(result: CypherResult): string {
+  if (result.error) {
+    return `monograph_cypher error: ${result.error}`;
+  }
+
+  if (result.rows.length === 0) {
+    return `monograph_cypher result (0 rows, ${result.queryTime}ms)\n\nNo results found.`;
+  }
+
+  const lines: string[] = [
+    `monograph_cypher result (${result.rows.length} row${result.rows.length === 1 ? '' : 's'}, ${result.queryTime}ms)`,
+    '',
+  ];
+
+  for (let i = 0; i < result.rows.length; i++) {
+    lines.push(`Row ${i + 1}:`);
+    const row = result.rows[i];
+
+    // Group fields by alias prefix (e.g., "n_name", "b_filePath")
+    // and reconstruct "alias.field = value" display, with file:line merging
+    const seen = new Set<string>();
+
+    for (const key of Object.keys(row)) {
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      // key format is aliasName_fieldName (e.g. n_filePath, n_startLine)
+      const sepIdx = key.indexOf('_');
+      if (sepIdx === -1) {
+        lines.push(`  ${key} = ${row[key] ?? 'null'}`);
+        continue;
+      }
+
+      const alias = key.slice(0, sepIdx);
+      const field = key.slice(sepIdx + 1);
+
+      // Merge filePath + startLine into a single file:line hint
+      if (field === 'filePath') {
+        const startLineKey = `${alias}_startLine`;
+        const startLine = row[startLineKey];
+        seen.add(startLineKey);
+        const filePath = row[key];
+        if (filePath != null && startLine != null) {
+          lines.push(`  ${alias}.filePath = ${filePath}:${startLine}`);
+        } else if (filePath != null) {
+          lines.push(`  ${alias}.filePath = ${filePath}`);
+        }
+        continue;
+      }
+
+      // Skip startLine — already consumed by filePath branch above
+      if (field === 'startLine') continue;
+
+      lines.push(`  ${alias}.${field} = ${row[key] ?? 'null'}`);
+    }
+
+    if (i < result.rows.length - 1) lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/src/search/embed-batch.ts

@@ -6,7 +6,7 @@ import type Database from 'better-sqlite3';
 import type { EmbedderFn } from './embedder.js';
 import type { EmbedDeviceConfig } from './device-config.js';
 import type { HttpEmbedderConfig } from './http-embedder.js';
-import { upsertEmbedding, countEmbeddings } from '../storage/embedding-store.js';
+import { upsertEmbedding, ensureEmbeddingSchema, countEmbeddings } from '../storage/embedding-store.js';
 import { embedText } from './embedder.js';
 
 const BATCH_SIZE = 32;
@@ -110,6 +110,9 @@ export async function embedAll(
   const toEmbed = filteredRows.filter((r) => !existingIds.has(r.id));
   skipped = filteredRows.length - toEmbed.length;
 
+  // Ensure schema migration runs once before any upsert — not per-row.
+  if (toEmbed.length > 0) ensureEmbeddingSchema(db);
+
   // Process in batches
   for (let i = 0; i < toEmbed.length; i += BATCH_SIZE) {
     const batch = toEmbed.slice(i, i + BATCH_SIZE);