optave-codegraph 3.13.0

package/src/db/repository/build-stmts.ts

@@ -0,0 +1,126 @@
+import type { BetterSqlite3Database, SqliteStatement } from '../../types.js';
+
+interface PurgeStmts {
+  embeddings: SqliteStatement | null;
+  cfgEdges: SqliteStatement | null;
+  cfgBlocks: SqliteStatement | null;
+  dataflow: SqliteStatement | null;
+  dataflowByVertex: SqliteStatement | null;
+  dataflowSummary: SqliteStatement | null;
+  dataflowVertices: SqliteStatement | null;
+  complexity: SqliteStatement | null;
+  nodeMetrics: SqliteStatement | null;
+  astNodes: SqliteStatement | null;
+  edges: SqliteStatement;
+  nodes: SqliteStatement;
+  fileHashes: SqliteStatement | null;
+}
+
+interface PurgeOpts {
+  purgeHashes?: boolean;
+}
+
+/**
+ * Prepare all purge statements once, returning an object of runnable stmts.
+ * Optional tables are wrapped in try/catch — if the table doesn't exist,
+ * that slot is set to null.
+ */
+function preparePurgeStmts(db: BetterSqlite3Database): PurgeStmts {
+  const tryPrepare = (sql: string): SqliteStatement | null => {
+    try {
+      return db.prepare(sql);
+    } catch {
+      return null;
+    }
+  };
+
+  return {
+    embeddings: tryPrepare(
+      'DELETE FROM embeddings WHERE node_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
+    cfgEdges: tryPrepare(
+      'DELETE FROM cfg_edges WHERE function_node_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
+    cfgBlocks: tryPrepare(
+      'DELETE FROM cfg_blocks WHERE function_node_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
+    dataflow: tryPrepare(
+      'DELETE FROM dataflow WHERE source_id IN (SELECT id FROM nodes WHERE file = ?) OR target_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
+    dataflowByVertex: tryPrepare(
+      `DELETE FROM dataflow WHERE source_vertex IN (SELECT id FROM dataflow_vertices WHERE func_id IN (SELECT id FROM nodes WHERE file = ?))
+         OR target_vertex IN (SELECT id FROM dataflow_vertices WHERE func_id IN (SELECT id FROM nodes WHERE file = ?))`,
+    ),
+    dataflowSummary: tryPrepare(
+      'DELETE FROM dataflow_summary WHERE func_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
+    dataflowVertices: tryPrepare(
+      'DELETE FROM dataflow_vertices WHERE func_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
+    complexity: tryPrepare(
+      'DELETE FROM function_complexity WHERE node_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
+    nodeMetrics: tryPrepare(
+      'DELETE FROM node_metrics WHERE node_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
+    astNodes: tryPrepare('DELETE FROM ast_nodes WHERE file = ?'),
+    // Core tables — always exist
+    edges: db.prepare(
+      'DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = @f) OR target_id IN (SELECT id FROM nodes WHERE file = @f)',
+    ),
+    nodes: db.prepare('DELETE FROM nodes WHERE file = ?'),
+    fileHashes: tryPrepare('DELETE FROM file_hashes WHERE file = ?'),
+  };
+}
+
+/**
+ * Cascade-delete all graph data for a single file across all tables.
+ * Order: dependent tables first, then edges, then nodes, then hashes.
+ */
+export function purgeFileData(db: BetterSqlite3Database, file: string, opts: PurgeOpts = {}): void {
+  const stmts = preparePurgeStmts(db);
+  runPurge(stmts, file, opts);
+}
+
+/**
+ * Run purge using pre-prepared statements for a single file.
+ */
+function runPurge(stmts: PurgeStmts, file: string, opts: PurgeOpts = {}): void {
+  const { purgeHashes = true } = opts;
+
+  // Optional tables
+  stmts.embeddings?.run(file);
+  stmts.cfgEdges?.run(file);
+  stmts.cfgBlocks?.run(file);
+  stmts.dataflow?.run(file, file);
+  stmts.dataflowByVertex?.run(file, file);
+  stmts.dataflowSummary?.run(file);
+  stmts.dataflowVertices?.run(file);
+  stmts.complexity?.run(file);
+  stmts.nodeMetrics?.run(file);
+  stmts.astNodes?.run(file);
+
+  // Core tables
+  stmts.edges.run({ f: file });
+  stmts.nodes.run(file);
+
+  if (purgeHashes) {
+    stmts.fileHashes?.run(file);
+  }
+}
+
+/**
+ * Purge all graph data for multiple files.
+ * Prepares statements once and loops over files for efficiency.
+ */
+export function purgeFilesData(
+  db: BetterSqlite3Database,
+  files: string[],
+  opts: PurgeOpts = {},
+): void {
+  if (!files || files.length === 0) return;
+  const stmts = preparePurgeStmts(db);
+  for (const file of files) {
+    runPurge(stmts, file, opts);
+  }
+}

package/src/db/repository/cached-stmt.ts

@@ -0,0 +1,20 @@
+import type { BetterSqlite3Database, SqliteStatement, StmtCache } from '../../types.js';
+
+/**
+ * Resolve a cached prepared statement, compiling on first use per db.
+ * Each `cache` WeakMap must always be called with the same `sql` —
+ * the sql argument is only used on the first compile; subsequent calls
+ * return the cached statement regardless of the sql passed.
+ */
+export function cachedStmt<TRow = unknown>(
+  cache: StmtCache<TRow>,
+  db: BetterSqlite3Database,
+  sql: string,
+): SqliteStatement<TRow> {
+  let stmt = cache.get(db);
+  if (!stmt) {
+    stmt = db.prepare<TRow>(sql);
+    cache.set(db, stmt);
+  }
+  return stmt;
+}

package/src/db/repository/cfg.ts

@@ -0,0 +1,81 @@
+import type { BetterSqlite3Database, StmtCache } from '../../types.js';
+import { cachedStmt } from './cached-stmt.js';
+
+// ─── Statement caches (one prepared statement per db instance) ────────────
+
+interface CfgBlockRow {
+  id: number;
+  block_index: number;
+  block_type: string;
+  start_line: number;
+  end_line: number;
+  label: string | null;
+}
+
+interface CfgEdgeRow {
+  kind: string;
+  source_index: number;
+  source_type: string;
+  target_index: number;
+  target_type: string;
+}
+
+const _getCfgBlocksStmt: StmtCache<CfgBlockRow> = new WeakMap();
+const _getCfgEdgesStmt: StmtCache<CfgEdgeRow> = new WeakMap();
+const _deleteCfgEdgesStmt: StmtCache = new WeakMap();
+const _deleteCfgBlocksStmt: StmtCache = new WeakMap();
+
+/**
+ * Check whether CFG tables exist.
+ */
+export function hasCfgTables(db: BetterSqlite3Database): boolean {
+  try {
+    db.prepare('SELECT 1 FROM cfg_blocks LIMIT 0').get();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get CFG blocks for a function node.
+ */
+export function getCfgBlocks(db: BetterSqlite3Database, functionNodeId: number): CfgBlockRow[] {
+  return cachedStmt(
+    _getCfgBlocksStmt,
+    db,
+    `SELECT id, block_index, block_type, start_line, end_line, label
+     FROM cfg_blocks WHERE function_node_id = ?
+     ORDER BY block_index`,
+  ).all(functionNodeId);
+}
+
+/**
+ * Get CFG edges for a function node (with block info).
+ */
+export function getCfgEdges(db: BetterSqlite3Database, functionNodeId: number): CfgEdgeRow[] {
+  return cachedStmt(
+    _getCfgEdgesStmt,
+    db,
+    `SELECT e.kind,
+            sb.block_index AS source_index, sb.block_type AS source_type,
+            tb.block_index AS target_index, tb.block_type AS target_type
+     FROM cfg_edges e
+     JOIN cfg_blocks sb ON e.source_block_id = sb.id
+     JOIN cfg_blocks tb ON e.target_block_id = tb.id
+     WHERE e.function_node_id = ?
+     ORDER BY sb.block_index, tb.block_index`,
+  ).all(functionNodeId);
+}
+
+/**
+ * Delete all CFG data for a function node.
+ */
+export function deleteCfgForNode(db: BetterSqlite3Database, functionNodeId: number): void {
+  cachedStmt(_deleteCfgEdgesStmt, db, 'DELETE FROM cfg_edges WHERE function_node_id = ?').run(
+    functionNodeId,
+  );
+  cachedStmt(_deleteCfgBlocksStmt, db, 'DELETE FROM cfg_blocks WHERE function_node_id = ?').run(
+    functionNodeId,
+  );
+}

package/src/db/repository/cochange.ts

@@ -0,0 +1,48 @@
+import type { BetterSqlite3Database, StmtCache } from '../../types.js';
+import { cachedStmt } from './cached-stmt.js';
+
+// ─── Statement caches (one prepared statement per db instance) ────────────
+const _hasCoChangesStmt: StmtCache<{ 1: number }> = new WeakMap();
+const _getCoChangeMetaStmt: StmtCache<{ key: string; value: string }> = new WeakMap();
+const _upsertCoChangeMetaStmt: StmtCache = new WeakMap();
+
+/**
+ * Check whether the co_changes table has data.
+ */
+export function hasCoChanges(db: BetterSqlite3Database): boolean {
+  try {
+    return !!cachedStmt(_hasCoChangesStmt, db, 'SELECT 1 FROM co_changes LIMIT 1').get();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get all co-change metadata as a key-value map.
+ */
+export function getCoChangeMeta(db: BetterSqlite3Database): Record<string, string> {
+  const meta: Record<string, string> = {};
+  try {
+    for (const row of cachedStmt(
+      _getCoChangeMetaStmt,
+      db,
+      'SELECT key, value FROM co_change_meta',
+    ).all()) {
+      meta[row.key] = row.value;
+    }
+  } catch {
+    /* table may not exist */
+  }
+  return meta;
+}
+
+/**
+ * Upsert a co-change metadata key-value pair.
+ */
+export function upsertCoChangeMeta(db: BetterSqlite3Database, key: string, value: string): void {
+  cachedStmt(
+    _upsertCoChangeMetaStmt,
+    db,
+    'INSERT INTO co_change_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value',
+  ).run(key, value);
+}

package/src/db/repository/complexity.ts

@@ -0,0 +1,21 @@
+import type { BetterSqlite3Database, ComplexityMetrics, StmtCache } from '../../types.js';
+import { cachedStmt } from './cached-stmt.js';
+
+// ─── Statement caches (one prepared statement per db instance) ────────────
+const _getComplexityForNodeStmt: StmtCache<ComplexityMetrics> = new WeakMap();
+
+/**
+ * Get complexity metrics for a node.
+ * Used by contextData and explainFunctionImpl in queries.js.
+ */
+export function getComplexityForNode(
+  db: BetterSqlite3Database,
+  nodeId: number,
+): ComplexityMetrics | undefined {
+  return cachedStmt(
+    _getComplexityForNodeStmt,
+    db,
+    `SELECT cognitive, cyclomatic, max_nesting, maintainability_index, halstead_volume
+     FROM function_complexity WHERE node_id = ?`,
+  ).get(nodeId);
+}

package/src/db/repository/dataflow.ts

@@ -0,0 +1,35 @@
+import type { BetterSqlite3Database, StmtCache } from '../../types.js';
+import { cachedStmt } from './cached-stmt.js';
+
+// ─── Statement caches (one prepared statement per db instance) ────────────
+const _hasDataflowTableStmt: StmtCache<{ c: number }> = new WeakMap();
+const _hasDataflowVerticesStmt: StmtCache<{ c: number }> = new WeakMap();
+
+/**
+ * Check whether the dataflow table exists and has data.
+ */
+export function hasDataflowTable(db: BetterSqlite3Database): boolean {
+  try {
+    return (
+      (cachedStmt(_hasDataflowTableStmt, db, 'SELECT COUNT(*) AS c FROM dataflow').get()?.c ?? 0) >
+      0
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check whether the dataflow_vertices table exists and has data.
+ * Returns false on DBs built before migration v18.
+ */
+export function hasDataflowVertices(db: BetterSqlite3Database): boolean {
+  try {
+    return (
+      (cachedStmt(_hasDataflowVerticesStmt, db, 'SELECT COUNT(*) AS c FROM dataflow_vertices').get()
+        ?.c ?? 0) > 0
+    );
+  } catch {
+    return false;
+  }
+}

package/src/db/repository/edges.ts

@@ -0,0 +1,281 @@
+import type {
+  AdjacentEdgeRow,
+  BetterSqlite3Database,
+  ImportEdgeRow,
+  IntraFileCallEdge,
+  NodeRow,
+  RelatedNodeRow,
+  StmtCache,
+} from '../../types.js';
+import { cachedStmt } from './cached-stmt.js';
+
+// ─── Prepared-statement caches (one per db instance) ────────────────────
+const _findCalleesStmt: StmtCache<RelatedNodeRow> = new WeakMap();
+const _findCallersStmt: StmtCache<RelatedNodeRow> = new WeakMap();
+const _findDistinctCallersStmt: StmtCache<RelatedNodeRow> = new WeakMap();
+const _findAllOutgoingStmt: StmtCache<AdjacentEdgeRow> = new WeakMap();
+const _findAllIncomingStmt: StmtCache<AdjacentEdgeRow> = new WeakMap();
+const _findCalleeNamesStmt: StmtCache<{ name: string }> = new WeakMap();
+const _findCallerNamesStmt: StmtCache<{ name: string }> = new WeakMap();
+const _findImportTargetsStmt: StmtCache<ImportEdgeRow> = new WeakMap();
+const _findImportSourcesStmt: StmtCache<ImportEdgeRow> = new WeakMap();
+const _findImportDependentsStmt: StmtCache<NodeRow> = new WeakMap();
+const _findCrossFileCallTargetsStmt: StmtCache<{ target_id: number }> = new WeakMap();
+const _countCrossFileCallersStmt: StmtCache<{ cnt: number }> = new WeakMap();
+const _getClassAncestorsStmt: StmtCache<{ id: number; name: string }> = new WeakMap();
+const _findIntraFileCallEdgesStmt: StmtCache<IntraFileCallEdge> = new WeakMap();
+const _findImplementorsStmt: StmtCache<RelatedNodeRow> = new WeakMap();
+const _findInterfacesStmt: StmtCache<RelatedNodeRow> = new WeakMap();
+
+// ─── Call-edge queries ──────────────────────────────────────────────────
+
+/**
+ * Find all callees of a node (outgoing 'calls' edges).
+ */
+export function findCallees(db: BetterSqlite3Database, nodeId: number): RelatedNodeRow[] {
+  return cachedStmt(
+    _findCalleesStmt,
+    db,
+    `SELECT DISTINCT n.id, n.name, n.kind, n.file, n.line, n.end_line
+     FROM edges e JOIN nodes n ON e.target_id = n.id
+     WHERE e.source_id = ? AND e.kind = 'calls'`,
+  ).all(nodeId);
+}
+
+/**
+ * Find all callers of a node (incoming 'calls' edges).
+ */
+export function findCallers(db: BetterSqlite3Database, nodeId: number): RelatedNodeRow[] {
+  return cachedStmt(
+    _findCallersStmt,
+    db,
+    `SELECT n.id, n.name, n.kind, n.file, n.line
+     FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ? AND e.kind = 'calls'`,
+  ).all(nodeId);
+}
+
+/**
+ * Find distinct callers of a node (for impact analysis BFS).
+ */
+export function findDistinctCallers(db: BetterSqlite3Database, nodeId: number): RelatedNodeRow[] {
+  return cachedStmt(
+    _findDistinctCallersStmt,
+    db,
+    `SELECT DISTINCT n.id, n.name, n.kind, n.file, n.line
+     FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ? AND e.kind = 'calls'`,
+  ).all(nodeId);
+}
+
+// ─── All-edge queries (no kind filter) ─────────────────────────────────
+
+/**
+ * Find all outgoing edges with edge kind (for queryNameData).
+ */
+export function findAllOutgoingEdges(db: BetterSqlite3Database, nodeId: number): AdjacentEdgeRow[] {
+  return cachedStmt(
+    _findAllOutgoingStmt,
+    db,
+    `SELECT n.name, n.kind, n.file, n.line, e.kind AS edge_kind
+     FROM edges e JOIN nodes n ON e.target_id = n.id
+     WHERE e.source_id = ?`,
+  ).all(nodeId);
+}
+
+/**
+ * Find all incoming edges with edge kind (for queryNameData).
+ */
+export function findAllIncomingEdges(db: BetterSqlite3Database, nodeId: number): AdjacentEdgeRow[] {
+  return cachedStmt(
+    _findAllIncomingStmt,
+    db,
+    `SELECT n.name, n.kind, n.file, n.line, e.kind AS edge_kind
+     FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ?`,
+  ).all(nodeId);
+}
+
+// ─── Name-only callee/caller lookups (for embedder) ────────────────────
+
+/**
+ * Get distinct callee names for a node, sorted alphabetically.
+ */
+export function findCalleeNames(db: BetterSqlite3Database, nodeId: number): string[] {
+  return cachedStmt(
+    _findCalleeNamesStmt,
+    db,
+    `SELECT DISTINCT n.name
+     FROM edges e JOIN nodes n ON e.target_id = n.id
+     WHERE e.source_id = ? AND e.kind = 'calls'
+     ORDER BY n.name`,
+  )
+    .all(nodeId)
+    .map((r) => r.name);
+}
+
+/**
+ * Get distinct caller names for a node, sorted alphabetically.
+ */
+export function findCallerNames(db: BetterSqlite3Database, nodeId: number): string[] {
+  return cachedStmt(
+    _findCallerNamesStmt,
+    db,
+    `SELECT DISTINCT n.name
+     FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ? AND e.kind = 'calls'
+     ORDER BY n.name`,
+  )
+    .all(nodeId)
+    .map((r) => r.name);
+}
+
+// ─── Import-edge queries ───────────────────────────────────────────────
+
+/**
+ * Find outgoing import edges (files this node imports).
+ */
+export function findImportTargets(db: BetterSqlite3Database, nodeId: number): ImportEdgeRow[] {
+  return cachedStmt(
+    _findImportTargetsStmt,
+    db,
+    `SELECT n.file, e.kind AS edge_kind
+     FROM edges e JOIN nodes n ON e.target_id = n.id
+     WHERE e.source_id = ? AND e.kind IN ('imports', 'imports-type')`,
+  ).all(nodeId);
+}
+
+/**
+ * Find incoming import edges (files that import this node).
+ */
+export function findImportSources(db: BetterSqlite3Database, nodeId: number): ImportEdgeRow[] {
+  return cachedStmt(
+    _findImportSourcesStmt,
+    db,
+    `SELECT n.file, e.kind AS edge_kind
+     FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ? AND e.kind IN ('imports', 'imports-type')`,
+  ).all(nodeId);
+}
+
+/**
+ * Find nodes that import a given node (BFS-ready, returns full node info).
+ */
+export function findImportDependents(db: BetterSqlite3Database, nodeId: number): NodeRow[] {
+  return cachedStmt(
+    _findImportDependentsStmt,
+    db,
+    `SELECT n.* FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ? AND e.kind IN ('imports', 'imports-type')`,
+  ).all(nodeId);
+}
+
+// ─── Cross-file and hierarchy queries ──────────────────────────────────
+
+/**
+ * Get IDs of symbols in a file that are called from other files.
+ */
+export function findCrossFileCallTargets(db: BetterSqlite3Database, file: string): Set<number> {
+  return new Set(
+    cachedStmt(
+      _findCrossFileCallTargetsStmt,
+      db,
+      `SELECT DISTINCT e.target_id FROM edges e
+       JOIN nodes caller ON e.source_id = caller.id
+       JOIN nodes target ON e.target_id = target.id
+       WHERE target.file = ? AND caller.file != ? AND e.kind = 'calls'`,
+    )
+      .all(file, file)
+      .map((r) => r.target_id),
+  );
+}
+
+/**
+ * Count callers that are in a different file than the target node.
+ */
+export function countCrossFileCallers(
+  db: BetterSqlite3Database,
+  nodeId: number,
+  file: string,
+): number {
+  return (
+    cachedStmt(
+      _countCrossFileCallersStmt,
+      db,
+      `SELECT COUNT(*) AS cnt FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ? AND e.kind = 'calls' AND n.file != ?`,
+    ).get(nodeId, file)?.cnt ?? 0
+  );
+}
+
+/**
+ * Get all ancestor class IDs via extends edges (BFS).
+ */
+export function getClassHierarchy(db: BetterSqlite3Database, classNodeId: number): Set<number> {
+  const ancestors = new Set<number>();
+  const queue = [classNodeId];
+  const stmt = cachedStmt(
+    _getClassAncestorsStmt,
+    db,
+    `SELECT n.id, n.name FROM edges e JOIN nodes n ON e.target_id = n.id
+     WHERE e.source_id = ? AND e.kind = 'extends'`,
+  );
+  while (queue.length > 0) {
+    const current = queue.shift() as number;
+    const parents = stmt.all(current);
+    for (const p of parents) {
+      if (!ancestors.has(p.id)) {
+        ancestors.add(p.id);
+        queue.push(p.id);
+      }
+    }
+  }
+  return ancestors;
+}
+
+// ─── Implements-edge queries ──────────────────────────────────────────
+
+/**
+ * Find all concrete types that implement a given interface/trait node.
+ */
+export function findImplementors(db: BetterSqlite3Database, nodeId: number): RelatedNodeRow[] {
+  return cachedStmt(
+    _findImplementorsStmt,
+    db,
+    `SELECT DISTINCT n.id, n.name, n.kind, n.file, n.line
+     FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ? AND e.kind = 'implements'`,
+  ).all(nodeId);
+}
+
+/**
+ * Find all interfaces/traits that a given class/struct implements.
+ */
+export function findInterfaces(db: BetterSqlite3Database, nodeId: number): RelatedNodeRow[] {
+  return cachedStmt(
+    _findInterfacesStmt,
+    db,
+    `SELECT DISTINCT n.id, n.name, n.kind, n.file, n.line
+     FROM edges e JOIN nodes n ON e.target_id = n.id
+     WHERE e.source_id = ? AND e.kind = 'implements'`,
+  ).all(nodeId);
+}
+
+/**
+ * Find intra-file call edges (caller → callee within the same file).
+ */
+export function findIntraFileCallEdges(
+  db: BetterSqlite3Database,
+  file: string,
+): IntraFileCallEdge[] {
+  return cachedStmt(
+    _findIntraFileCallEdgesStmt,
+    db,
+    `SELECT caller.name AS caller_name, callee.name AS callee_name
+     FROM edges e
+     JOIN nodes caller ON e.source_id = caller.id
+     JOIN nodes callee ON e.target_id = callee.id
+     WHERE caller.file = ? AND callee.file = ? AND e.kind = 'calls'
+     ORDER BY caller.line`,
+  ).all(file, file);
+}

package/src/db/repository/embeddings.ts

@@ -0,0 +1,47 @@
+import type { BetterSqlite3Database, StmtCache } from '../../types.js';
+import { cachedStmt } from './cached-stmt.js';
+
+// ─── Statement caches (one prepared statement per db instance) ────────────
+const _hasEmbeddingsStmt: StmtCache<{ 1: number }> = new WeakMap();
+const _getEmbeddingCountStmt: StmtCache<{ c: number }> = new WeakMap();
+const _getEmbeddingMetaStmt: StmtCache<{ value: string }> = new WeakMap();
+
+/**
+ * Check whether the embeddings table has data.
+ */
+export function hasEmbeddings(db: BetterSqlite3Database): boolean {
+  try {
+    return !!cachedStmt(_hasEmbeddingsStmt, db, 'SELECT 1 FROM embeddings LIMIT 1').get();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the count of embeddings.
+ */
+export function getEmbeddingCount(db: BetterSqlite3Database): number {
+  try {
+    return (
+      cachedStmt(_getEmbeddingCountStmt, db, 'SELECT COUNT(*) AS c FROM embeddings').get()?.c ?? 0
+    );
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Get a single embedding metadata value by key.
+ */
+export function getEmbeddingMeta(db: BetterSqlite3Database, key: string): string | undefined {
+  try {
+    const row = cachedStmt(
+      _getEmbeddingMetaStmt,
+      db,
+      'SELECT value FROM embedding_meta WHERE key = ?',
+    ).get(key);
+    return row?.value;
+  } catch {
+    return undefined;
+  }
+}